11 — Design System Mapping (Academics 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
Academics 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. Module components defined in 07_Component_Library.md.
1. Theme recipes (module)
| Screens | Theme | Exception |
|---|---|---|
| Structure lists (years/grades/classes/sections/subjects) | standard shell surface | current-year row = primaryContainer |
| Class detail (master) | standard shell | roster conflict rows = tertiaryContainer |
| Assignment matrix sheet | surfaceContainerLow sheet | disabled already-assigned options = surfaceVariant text |
| Hierarchy explorer | standard shell | empty nodes / warning dots = tertiary |
| Read-only browse (student/parent) | standard shell, all CTAs hidden | no destructive accents visible |
| Destructive actions (delete/remove/set-current) | error + errorContainer dialogs | — |
2. Widget → token
| Component | M3 / Flutter | Tokens | Elev | Radius |
|---|---|---|---|---|
| Year row (current) | AppListTile in AppCard tonal | primaryContainer, border outlineVariant | e-1 | r-lg |
| Grade ladder row | AppListTile | leading displayOrder circle surfaceVariant, mono labelMedium | — | r-full |
| Class row chips | AppChips | grade chip secondaryContainer, section chip surfaceVariant, year chip outline | — | r-sm |
HierarchyTree node | custom list (07 §1) | hover surfaceVariant; indent guide outlineVariant 1 px | — | r-md |
| Node empty/warning dot | AppBadge | tertiary (empty), tertiaryContainer (warning) | — | r-full |
SectionChips | Wrap of InputChip | selected secondaryContainer; inactive status≠active outlined | — | r-sm |
SubjectAssignmentRow | custom ListTile | conflict: tertiaryContainer bg + 2 px tertiary left border | — | r-md |
YearStatusBadge | AppChips | upcoming outline; active primaryContainer; archived surfaceVariant | — | r-sm |
EntityStatusBadge | AppChips | non-active → neutral surfaceVariant, raw value truncated | — | r-sm |
CascadingEntityPicker | column of AppDropdown | fill surfaceVariant, focus primary; disabled child surfaceContainerLow | — | r-md |
MarksSummaryTiles | 2×2 AppCard tiles | numerals titleMedium mono + tabularFigures; label labelMedium | e-1 | r-lg |
RosterTable (≥840) | DataTable | header surfaceContainerLow sticky; hover surfaceVariant | — | — |
ConflictBanner | custom MaterialBanner-style | tertiaryContainer bg / onTertiaryContainer text | e-1 | r-md |
| Matrix add sheet | AppBottomSheet | surfaceContainerHigh | e-4 | r-xl (top) |
| Destructive dialog | AppDialog | errorContainer icon + error confirm | e-5 | r-lg |
| FAB (add entity) | FloatingActionButton.extended | primaryContainer | e-3 | r-full |
| Empty state | AppEmptyState | icon onSurfaceVariant 40 % | — | — |
3. Typography mapping
| Token | Screen element |
|---|---|
headlineMedium | detail header names (year/grade/class/subject) |
titleLarge | form titles, dialog titles, explorer root nodes |
titleMedium | list row titles, tab labels, section headers |
bodyMedium | meta rows (capacity, teacher, room), roster teacher names |
bodySmall | dates, hints, "N sections · N classes" counts, marks summary |
labelLarge | buttons, FAB label, tabs |
labelMedium | chips, badges, displayOrder circles |
mono | subject code, capacity numerals, displayOrder, marks numerals |
Numerals (capacity, marks, orders) use FontFeature.tabularFigures() so ladder
columns don't jitter (00-shared/02 §2).
4. Iconography
Material Symbols outlined; module map: calendar_month, school, groups,
menu_book, book_2 (subjects), account_tree (explorer), expand_more/less
(tree), warning_amber (conflicts), check_circle (current), add,
swap_horiz (replace), delete_outline, search, filter_list, arrow_back.
5. Motion tokens (values 00-shared/02 §6)
| Purpose | Token | Applied to |
|---|---|---|
| List → detail push | m-base slide + Hero m-slow | all detail pushes |
| Tree expand/collapse | m-base (AnimatedSize) | explorer |
| Sheet (add assignment) | m-base bottom slide | matrix |
| Row exit on delete/remove | m-fast (AnimatedList) | lists, roster |
| Badge change (set-current) | m-fast scale pop | year screens |
| Conflict banner | m-base slide-down + fade | detail/explorer |
| Filter chips swap | m-fast fill/outline | lists |
Rules: reduced-motion substitutes fades/instants only (08 §4).
6. Contrast & dark parity
- All text ≥ 4.5:1; interactive chrome (dots, borders) ≥ 3:1 (00-shared/09 §2).
- Dark: conflict surface =
tertiaryContainer(kept distinct from error banners); current-year pillprimaryContainerwithonPrimaryContainertext. - No sole-color status: status always badge + icon/text label; conflicts always banner + row highlight + icon (color-blind safe, 00-shared/09 §9).
- Tree indent guides:
outlineVarianton light,outlineat 40 % on dark.
7. Breakpoint behaviour
| Class | Lists | Detail | Explorer / Matrix |
|---|---|---|---|
| phone <600 | single column, FAB bottom | pushed (full screen) | tree full width; matrix sheet full-height |
| 600–839 (tablet) | two-column grid (classes by grade groups) | master-detail split | tree with search box pinned |
| ≥840 | list + detail side-by-side (StatefulShellBranch, 00-shared/05 §3) | right pane tabs | roster as RosterTable; explorer 2-pane (tree |
| ≥1200 | max content width 1280, centered | same | same |
Desktop extras: hover rings on rows/nodes, right-click menus, keyboard shortcuts
(10 §2), always-visible Scrollbar (00-shared/04 §8).