# Design Guide

All UI code must reference tokens from `lib/widgets/theme.dart` (`AppTokens`)
rather than hard-coding values. Any new token belongs here first.

## Color

### Seed

- `AppTokens.seed` = `#3F51B5` (indigo).
  Both the light and dark schemes are derived from this seed via
  `ColorScheme.fromSeed`.

### Tracker palette

Each tracker chooses an accent color from `AppTokens.trackerPalette`. The
accent is applied to progress bars, the checked-chapter fill, and the header
stats. The palette (10 colors) is tuned to remain legible on both light and
dark surfaces:

| Color | Hex       |
| ----- | --------- |
| Indigo  | `#3F51B5` |
| Blue    | `#1E88E5` |
| Teal    | `#00897B` |
| Green   | `#43A047` |
| Amber   | `#FDD835` |
| Orange  | `#FB8C00` |
| Red     | `#E53935` |
| Pink    | `#D81B60` |
| Purple  | `#8E24AA` |
| Brown   | `#6D4C41` |

### Usage rules

- **Never** use raw `Color(0x…)` or `Colors.red` outside of `theme.dart` or
  the palette constant. Pull from `Theme.of(context).colorScheme` or pass the
  tracker accent through.
- Inactive surfaces (unread chapters, progress bar track) use
  `colorScheme.surfaceContainerHigh` / `surfaceContainerHighest`.
- Destructive actions use `colorScheme.error`.

## Typography

Use the Material 3 text theme. Reach for:

- `displaySmall` — hero progress percentages on the Stats screen.
- `headlineMedium` — progress percentage on the Tracker header.
- `titleLarge` / `titleMedium` — screen-level and card titles.
- `titleSmall` — list-item titles (e.g. book names).
- `bodyMedium` — body copy, stat values.
- `labelMedium` / `labelSmall` — compact counters, section metadata.

Weight overrides are allowed (`FontWeight.w500` / `w600` / `w700`) but font
family and sizes must come from the theme.

## Spacing

8pt grid, defined in `AppTokens`:

| Token        | Value |
| ------------ | ----- |
| `spaceXS`    | 4     |
| `spaceS`     | 8     |
| `spaceM`     | 12    |
| `spaceL`     | 16    |
| `spaceXL`    | 24    |
| `spaceXXL`   | 32    |

Screen padding defaults to `spaceL`. Inner card padding defaults to `spaceL`.
Gaps between related widgets use `spaceS`–`spaceM`; gaps between distinct
sections use `spaceXL`.

## Radius

| Token      | Value |
| ---------- | ----- |
| `radiusS`  | 8     |
| `radiusM`  | 12    |
| `radiusL`  | 16    |

Cards: `radiusM`. Chapter cells: `radiusM`. Pill chips: `radiusL`. Buttons:
`radiusS`.

## Components

- **`TrackerTile`** — card on the home list. Shows dot + name + percent pill
  + progress bar.
- **`BookTile`** — list row on the Tracker screen. Shows leading status badge,
  book name, inline progress bar, and `read / total` counter.
- **`ProgressBar`** — thin rounded linear indicator with a tracker accent
  color on top of the `surfaceContainerHighest` track.
- **`ProgressPill`** — percent chip tinted with the accent color at 15% alpha.
- **Chapter cell** (`book_screen.dart`) — square tile, accent-filled when
  read; tap toggles.

## Layout conventions

- Home, Tracker, and Stats screens each own a single `Scaffold` with a
  contextual `AppBar`.
- Long scrollable lists always use `ListView.separated` with a thin
  `outlineVariant` divider. Books within a testament are grouped under a
  `_SectionHeader`.
- Destructive confirmations (delete, reset) use a standard `AlertDialog` with
  an error-tinted confirm button.

## Theming

`AppTheme.light()` / `AppTheme.dark()` build from a Material 3
`ColorScheme.fromSeed`. Component themes (`AppBarTheme`, `CardThemeData`,
`ListTileThemeData`, `DividerThemeData`, `FilledButtonThemeData`,
`ProgressIndicatorThemeData`) are centralized so individual widgets stay
declarative.