11 — Design System Mapping (Settings Module)
- 1. Theme recipes (module)
- 2. Widget → token
- 3. Typography mapping
- 4. Iconography
- 5. Motion tokens (values 00-shared/02 §6)
- 6. Contrast & dark parity
- 7. Breakpoint behaviour
- 8. Cross-surface brand override
Settings module → Material 3 / Flutter / token mapping, extending 00-shared/04. Every color, type, spacing, elevation, radius, icon, motion reference traces to 00-shared/02_Design_Tokens.md.
1. Theme recipes (module)
| Screens | Theme | Exception |
|---|---|---|
| Settings list (hub) | standard shell (surface) | dirty rows primaryContainer tint; type chips surfaceVariant |
| Setting detail/editors | standard shell | JSON editor surfaceVariant fill; error error outline |
| Batch mode | standard shell | bottom bar surfaceContainerHigh, e-3 |
| Cross-link banner | AppBanner(info) | primaryContainer |
| Empty/not-found states | surface | AppEmptyState tokens |
2. Widget → token
| Component | M3 / Flutter | Tokens | Elev | Radius |
|---|---|---|---|---|
| Setting row card | AppCard flat | surfaceContainerLow | e-0 | r-md |
| Dirty row | AppCard tonal | primaryContainer / onPrimaryContainer | e-0 | r-md |
| Type chip | AppBadge | surfaceVariant / onSurfaceVariant | — | r-sm |
| Group chips | FilterChip | selected secondaryContainer, unselected surfaceVariant | — | r-sm |
| Key text | Text | mono, titleMedium | — | — |
| Value preview | Text | bodyMedium onSurfaceVariant, 1-line ellipsis | — | — |
| Editors (string/number) | AppTextField | fill surfaceVariant, border outline, focus primary, error error | — | r-md |
| JSON editor | TextFormField mono | same; valid primary check, invalid error | — | r-md |
| Boolean row | SwitchListTile | switch primary | — | — |
| Save button | FilledButton | primary/onPrimary | — | r-md |
| Batch bar | Material + FilledButton | surfaceContainerHigh, e-3 | e-3 | — |
| Delete confirm | AppDialog | surfaceContainerHigh, destructive error | e-4 | r-lg |
| FAB (new setting) | FloatingActionButton.extended | primaryContainer | e-3 | r-full |
| Cross-link banner | MaterialBanner | primaryContainer | e-1 | — |
3. Typography mapping
| Token | Screen element |
|---|---|
headlineMedium | "Settings" screen title |
titleLarge | detail key header, dialog titles |
titleMedium | section headers ("Attendance (12)"), row keys (mono) |
bodyMedium | value preview, labels, helper text |
bodySmall | meta footer (created/version), "Nothing in this group", JSON error line |
labelLarge | buttons, group chip labels |
mono | keys, JSON editor, numeric values |
Numerals (versions, counts) use FontFeature.tabularFigures() (00-shared/02 §2).
4. Iconography
Material Symbols outlined; module map: settings, tune, school (academic),
event_available (attendance), grading, notifications (notification), palette (theme),
manage_search (general), add, content_copy, delete, check_circle, error,
chevron_right, data_object (JSON).
Group → icon map (leading icon per group):
| Group | Icon |
|---|---|
| academic | school |
| attendance | event_available |
| grading | grading |
| notification | notifications |
| theme | palette |
| general | manage_search |
5. Motion tokens (values 00-shared/02 §6)
| Purpose | Token | Applied to |
|---|---|---|
| Save → result | m-base | snackbar/check swap |
| Dirty dot pop / clear | m-fast | row indicator |
| Row delete exit | m-base | fade-out |
| Batch bar entrance | m-entrance | bottom bar |
| Chip indicator | m-base | group chips |
| Editor error | m-fast | outline/message swap (no shake) |
| List entrance | m-entrance stagger 40 ms | first paint |
Rules: reduced-motion substitutes fades/instants (00-shared/08 §4).
6. Contrast & dark parity
- All text ≥ 4.5:1; interactive chrome ≥ 3:1 (00-shared/09 §2).
- Dark: dirty tint
primaryContainerdark variant (TBD by designer, 02 §1.4); JSON editor fillsurfaceVariant; type chips readable (onSurfaceVariant). - No sole-color status: dirty = dot + "unsaved" semantics; saved = snackbar + check; type = chip label (never color-only, 00-shared/09 §9).
7. Breakpoint behaviour
| Class | List | Detail |
|---|---|---|
| phone <600 | single pane, chips scroll horizontally | pushed page |
| 600–839 | list full width; detail sheet-like push | push |
| 840–1199 | master-detail two-pane (list ≤ 480) | right pane |
| ≥1200 | master-detail; hover rings; keyboard shortcuts | right pane |
8. Cross-surface brand override
Org branding.primaryColor/settings.theme.primaryColor
(organization.schema.ts:108-120) re-seeds the ColorScheme at runtime
(00-shared/04 §7.5) — the Settings hub renders under the same overridden theme; a
theme group value change takes effect on next theme reload (proposed wiring).