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