113 lines
3.6 KiB
Markdown
113 lines
3.6 KiB
Markdown
# 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.
|