04 — Design System Mapping (Shared)

1. Theme
2. Widget → token mapping (core)
3. Typography mapping
4. Iconography
5. Motion mapping
6. Layout tokens
7. Theming rules (enforced)
8. Web/desktop (Flutter Web + Windows/macOS/Linux)

Maps Material 3 + Flutter widgets to the StudyLyon token set. Module docs 11_Design_System_Mapping.md extend this with module-specific components.

1. Theme

Concern	Value
Framework	Flutter Material 3 (`useMaterial3: true`)
`ColorScheme`	`ColorScheme.fromSeed(seedColor: primary)` + overrides from 02_Design_Tokens.md
`ThemeData`	One `AppTheme.light()` / `AppTheme.dark()`; `themeMode` from system or org branding
Text theme	`TextTheme` from 02_Design_Tokens.md §2
Spacing	`AppSpacing` extension class (semantic `xs/s/item-spacing.24/m/l/xl` + fixed scale)
Radius	`AppRadius` class (`r-micro … r-full`)
Elevation	`AppElevation` class; shadow tokens via `BoxShadow`/`elevation` params
Motion	`AppMotion` class (durations + `Curves`)
Localization	`flutter_localizations` + `Intl`; `MaterialApp.localizationsDelegates`
Fonts	Theme font Inter (default); `mono` via JetBrains Mono (`fontFamilyFallback`)

Flutter widget	M3 role	StudyLyon token
`FilledButton`	Primary	`primary`/`onPrimary`, `r-md`, `m-fast` ripple
`FilledButton.tonal`	Secondary	`secondaryContainer`/`onSecondaryContainer`
`OutlinedButton`	Tertiary	`outline`, `onSurface`, `r-md`
`TextButton`	Text action	`primary`
`IconButton`	Icon action	`onSurfaceVariant`, tooltip required
`TextField`	Filled input	fill `surfaceVariant`, border `outline`, focus `primary`, `r-md`
`Card`	Elevated card	`surfaceContainerLow`, `e-1`, `r-lg`
`ListTile`	List row	`surface`, height 56, `onSurface`/`onSurfaceVariant`
`NavigationBar`	Bottom nav	`surfaceContainer`, indicator `secondaryContainer`, 64 h
`NavigationRail`	Tablet/desktop nav	`surfaceContainerLow`, indicator `secondaryContainer`
`NavigationDrawer`	Drawer	`surfaceContainerLow`, `e-4`, width 320
`AppBar`	Top bar	`surface`, `titleLarge`, centerTitle false (phone), true (desktop)
`TabBar`	Section tabs	indicator `primary`, `labelLarge`
`FloatingActionButton`	Primary action	`primaryContainer`, `e-3`, 56 dp
`Dialog`/`AlertDialog`	Dialog	`surfaceContainerHigh`, `e-4`, `r-lg`
`BottomSheet`	Sheet	`surfaceContainerHigh`, `e-5`, `r-xl` top corners
`SnackBar`	Toast	`inverseSurface`, `m-base` slide
`Chip` (Filter/Input)	Chip	selected `secondaryContainer`, else `surfaceVariant`
`Switch/Checkbox/Radio`	Toggle	`primary` selected, `onSurfaceVariant` unselected
`Slider`	Slider	`primary`, `e-0`
`LinearProgressIndicator`	Progress	`primary`, `surfaceVariant` track
`RefreshIndicator`	Pull-refresh	`primary` spinner
`Badge`	Badge	`error` for counts, `tertiary` for dues
`Tooltip`	Tooltip	`inverseSurface`, `m-fast`
`Hero`	Hero transition	`m-slow` flight
`Semantics`	A11y labels	all interactive nodes labeled

3. Typography mapping

M3 token	`TextTheme` member	Typical widget
displaySmall	`displaySmall`	Empty states
headlineMedium	`headlineMedium`	Screen titles
titleLarge	`titleLarge`	Card/dialog titles
titleMedium	`titleMedium`	Section headers, list titles
bodyLarge	`bodyLarge`	Body, descriptions
bodyMedium	`bodyMedium`	Labels, secondary
bodySmall	`bodySmall`	Captions, timestamps
labelLarge	`labelLarge`	Buttons, tabs
labelMedium	`labelMedium`	Badges
labelSmall	`labelSmall`	Overlines

4. Iconography

Pack: Material Symbols outlined; 24 dp default; status icons filled.
Sizing: 16 (dense rows), 20 (menu), 24 (default), 32 (empty state), 40 (headers).
Color: onSurfaceVariant default; primary active; error destructive.

5. Motion mapping

Use	Token	Flutter
Page transition	`m-base` 250 ms	`PageTransitionsTheme` (FadeUpwards on Android, Cupertino on iOS)
Dialog/sheet	`m-base`	`showDialog`/`showModalBottomSheet` defaults
Hero	`m-slow` 400 ms	`Hero` widget
Ripple	`m-fast` 150 ms	`InkWell`/`InkResponse`
Hover/focus	`m-fast`	`MouseRegion` + `AnimatedContainer`/focus ring
List entrance	`m-entrance` stagger 40 ms	`AnimatedList`/explicit `TweenAnimationBuilder`
Skeleton shimmer	`m-slow` loop	custom `AnimatedBuilder`
Snackbar	`m-base`	`ScaffoldMessenger`

6. Layout tokens

Token	Value
Screen horizontal padding	16 (phone), 24 (tablet/desktop)
Card padding	16
Card gap	12
Section gap	24
Toolbar	64
Bottom nav height	64
List row	56
Master-detail breakpoint	840 dp

7. Theming rules (enforced)

No literal Color in widget code — context.colorScheme.* / AppTokens.* only.
No literal padding/margin — AppSpacing.* only.
No literal durations — AppMotion.* only.
Dark mode is a first-class theme, not an overlay.
Tenant branding overrides primary at runtime via ThemeData copy.

8. Web/desktop (Flutter Web + Windows/macOS/Linux)

Hover states on all tappables (MouseRegion), focus rings (FocusTraversalGroup), keyboard shortcuts (Shortcuts/Actions), ESC closes dialogs/sheets/menus.
Responsive layout via LayoutBuilder breakpoints (02_Design_Tokens.md §8).
Scrollbars always visible on desktop.

Keyboard shortcuts

StudyLyon — Design Docs