bible-tracker/DESIGN_GUIDE.md

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.