02 — Design Tokens (Shared)

1. Color system
2. Typography
- 2.1 M3 type scale mapping
- 2.2 Non-M3 typography tokens (designer-provided)
3. Spacing
4. Radius
5. Elevation & shadow
6. Motion
7. Iconography
8. Breakpoints (responsive)
9. Touch targets
10. Light/dark parity rules

STATUS: v1 — designer-provided (Material 3 token export from Figma). Rows marked TBD by designer or (extrapolated…) are not sourced from the export and need designer sign-off before shipping. All module docs reference this file; changes here propagate everywhere.

1. Color system

1.1 Chromatic roles (light)

Designer-provided M3 roles plus two custom extended roles (success, warning — not standard M3, present in the token set).

Role	Token Name	Hex	Usage
`primary`	International Klein Blue	`#0037B0`	CTAs, active nav, links, focus
`onPrimary`	White	`#FFFFFF`	Text/icons on primary
`primaryContainer`	Titan White	`#E9EDFF`	Selected chips, info banners
`onPrimaryContainer`	International Klein Blue	`#0037B0`	Text on primaryContainer
`secondary`	Persian Blue	`#1D4ED8`	Secondary CTAs
`onSecondary`	White	`#FFFFFF`	Text/icons on secondary
`secondaryContainer`	Pattens Blue	`#DBEAFE`	Tonal buttons, selection indicators
`onSecondaryContainer`	Persian Blue	`#1D4ED8`	Text on secondaryContainer
`tertiary`	Purple Heart	`#712AE2`	Distinct accents, highlights
`onTertiary`	White	`#FFFFFF`	Text/icons on tertiary
`tertiaryContainer`	Blue Chalk	`#EADDFF`	Tonal tertiary surfaces
`onTertiaryContainer`	Purple Heart	`#712AE2`	Text on tertiaryContainer
`error`	Thunderbird	`#BA1A1A`	Validation, destructive
`onError`	White	`#FFFFFF`	Text on error
`errorContainer`	Cinderella	`#FEE2E2`	Error banners, destructive surfaces
`onErrorContainer`	Sangria	`#93000A`	Text on errorContainer
`success` (custom)	Salem	`#16A34A`	Paid, present, approved, healthy
`onSuccess` (custom)	White	`#FFFFFF`	Text/icons on success
`successContainer` (custom)	Scandal	`#DCFCE7`	Success surfaces, badges
`onSuccessContainer` (custom)	Jewel	`#15803D`	Text on successContainer
`warning` (custom)	Ecstasy	`#F97316`	Partial, late, attention
`onWarning` (custom)	White	`#FFFFFF`	Text/icons on warning
`warningContainer` (custom)	Serenade	`#FFF7ED`	Warning surfaces, badges
`onWarningContainer` (custom)	Cedar Wood Finish	`#7F2500`	Text on warningContainer

Note: success and warning are standalone roles, not aliases of secondary/tertiary (previous proposal). Dues/warnings that were formerly tertiary now map to warning; paid/healthy states map to success.

1.2 Surface scale (light)

Role	Token Name	Hex	Usage
`background`	Catskill White	`#F8FAFC`	Screen background
`onBackground`	Ebony	`#0F172A`	Primary text on background
`surface`	White	`#FFFFFF`	Card/screen surfaces
`onSurface`	Ebony	`#0F172A`	Primary text
`surfaceVariant`	Mystic	`#E2E8F0`	Input fills, chips
`onSurfaceVariant`	Fiord	`#475569`	Secondary text, icons
`surfaceContainerLowest`	White	`#FFFFFF`	Flat cards on containers
`surfaceContainerLow`	Catskill White	`#F8FAFC`	Card backgrounds
`surfaceContainer`	Athens Gray	`#E5E7EB`	Raised surfaces, nav bars
`surfaceContainerHigh`	Geyser	`#CBD5E1`	Elevated cards, dialogs
`surfaceContainerHighest`	Gull Gray (extrapolated — next step down the neutral scale)	`#94A3B8`	TBD by designer
`surfaceDim`	Slate Gray (extrapolated — dimmest step before onSurface tones)	`#64748B`	TBD by designer
`surfaceBright`	White (extrapolated — brightest neutral, standard M3 convention)	`#FFFFFF`	TBD by designer

1.3 Outline & inverse

Role	Token Name	Hex
`outline`	Boulder	`#767676`
`outlineVariant`	Geyser	`#CBD5E1`
`shadow`	Black	`#000000`
`scrim`	Black	`#000000`
`inverseSurface`	Mirage	`#141B2B`
`inverseOnSurface`	Catskill White	`#F8FAFC`
`inversePrimary`	Melrose	`#B7C4FF`

1.4 Dark mode

Designer-provided dark surface scale (grey/azure family):

Level	Token Name	Hex
Surface Dim	Ebony	`#0F172A`
Surface	Mirage	`#141B2B`
Surface Container	Ebony Clay	`#293040`
Surface Container High	Pickled Bluewood	`#334155`
Surface Container Highest	Slate Gray	`#64748B`

Dark chromatic roles (primary/secondary/tertiary/error/success/warning + containers) are NOT in the export — TBD by designer.
Working proposal until then (per M3 convention, dark primary ≈ inversePrimary): dark primary ≈ #B7C4FF (Melrose) with onPrimary ≈ #0037B0-family dark. Do not ship dark mode until confirmed.

1.5 Tenant branding

Org branding.color overrides primary only; all other roles stay from this palette. Dark mode default: follow system; org branding can pin one.

1.6 Raw named palette (designer reference)

Token	Hex	Notes
Athens Gray	`#E5E7EB`	neutral
Beeswax	`#FEF9C3`	tertiary tint
Black	`#000000`	scrim / shadow
Blue Chalk	`#EADDFF`	tertiaryContainer
Boulder	`#767676`	outline
Brown Pod	`#390C00`	error-dark accent
Catskill White	`#F8FAFC`	surface/background
Cedar Wood Finish	`#7F2500`	onWarningContainer
Cinderella	`#FEE2E2`	errorContainer
Ebony	`#0F172A`	onSurface (dark)
Ebony Clay	`#293040`	surface container (dark)
Ecstasy	`#F97316`	warning
Fiord	`#475569`	onSurfaceVariant
Fire	`#A73400`	error-dark accent
Flamingo	`#EF4444`	error accent
Foam	`#ECFDF5`	success tint
Fog	`#DCE1FF`	primary tint
Fun Green	`#008542`	success accent
Geyser	`#CBD5E1`	outlineVariant
Ghost	`#C4C5D7`	neutral variant
Gray Chateau	`#9CA3AF`	neutral
Green Haze	`#059669`	success accent
Gull Gray	`#94A3B8`	neutral
Harp	`#F1F8F4`	success tint
Hawkes Blue	`#E1E8FD`	secondaryContainer alt
Humming Bird	`#D1FAE5`	success tint
International Klein Blue	`#0037B0`	primary
Jewel	`#15803D`	onSuccessContainer
Link Water	`#DCE2F7`	neutral variant
Magic Mint	`#A7F3D0`	success tint
Mako	`#434655`	neutral dark
Melrose	`#B7C4FF`	inversePrimary
Mirage	`#141B2B`	inverseSurface
Mountain Meadow	`#10B981`	success accent
Mystic	`#E2E8F0`	surfaceVariant
Pale Sky	`#6B7280`	neutral
Pattens Blue	`#DBEAFE`	secondaryContainer
Peach Schnapps	`#FFDAD6`	error tint
Periwinkle	`#CAD3FF`	primary tint
Persian Blue	`#1D4ED8`	secondary
Pickled Bluewood	`#334155`	surface container (dark)
Provincial Pink	`#FEF2F2`	error tint
Pueblo	`#7C2D12`	warning-dark accent
Purple Heart	`#712AE2`	tertiary
Rich Gold	`#A16207`	warning-dark accent
Romantic	`#FFC9B7`	warning tint
Salem	`#16A34A`	success
Sangria	`#93000A`	onErrorContainer
Scandal	`#DCFCE7`	successContainer
Serenade	`#FFF7ED`	warningContainer
Slate Gray	`#64748B`	neutral
Storm Gray	`#747686`	outline alt
Thunderbird	`#BA1A1A`	error
Titan White	`#E9EDFF`	primaryContainer
Watercourse	`#047857`	success accent
Watusi	`#FFDBCF`	warning tint
White	`#FFFFFF`	onPrimary / surface
Zircon	`#F1F3FF`	neutral tint
Zumthor	`#EFF6FF`	secondary tint

2. Typography

Font families: Inter (UI) and JetBrains Mono (data/identifiers). Both designer-provided.

2.1 M3 type scale mapping

Rows marked (extrapolated…) were not present as named tokens in the export; they are filled from the nearest fontSize scale steps or adjacent tiers per standard M3 conventions. TBD by designer — confirm before shipping.

M3 Scale Role	Mapped Token	Font	Weight	Size	Line Height	Letter Spacing	Case
Display Large	Heading 1 underline	Inter	Extra Bold	48px	48px	-1.2	none
Display Medium	(extrapolated, fontSize step 14)	Inter	Bold	36px	44px	-1.2	none
Display Small	(extrapolated, fontSize step 13)	Inter	Bold	28px	34px	-0.72	none
Headline Large	Heading 1	Inter	Semi Bold	20px	28px	-0.5	none
Headline Medium	(extrapolated — same tier as Heading 1, heavier)	Inter	Bold	20px	28px	-0.5	none
Headline Small	Heading 2	Inter	Bold	18px	27px	0	none
Title Large	Data	Inter	Semi Bold	16px	24px	0	none
Title Medium	Heading 3	Inter	Bold	14px	21px	0	none
Title Small	Inter / Medium	Inter	Medium	14px	20px	0	none
Body Large	Inter / Regular	Inter	Regular	14px	20px	0	none
Body Medium	Input	Inter	Regular	14px	AUTO	0	none
Body Small	Label	Inter	Regular	10.7px	16.5px	0	none
Label Large	Button	Inter	Bold	12px	18px	0	none
Label Medium	Button upper / Cell upper	Inter	Bold	12px	16px	1.2 / 0.6	uppercase
Label Small	Link	Inter	Regular	12px	18px	0	none

2.2 Non-M3 typography tokens (designer-provided)

Token	Font	Weight	Size	Line Height	Case
Inter / Semi Bold upper	Inter	Semi Bold	10px	15px	uppercase
Inter / Regular upper	Inter	Regular	10px	15px	uppercase
Inter / Bold upper	Inter	Bold	10px	15px	uppercase
Inter / Italic	Inter	Italic	16px	26px	none
Inter / Bold	Inter	Bold	16px	24px	none
JetBrains Mono / Regular	JetBrains Mono	Regular	13px	18px	none
JetBrains Mono / Bold	JetBrains Mono	Bold	13px	18px	none

Usage: mono for IDs, roll numbers, amounts, keys. Numerals (scores, amounts) use FontFeature.tabularFigures().

3. Spacing

3.1 Semantic scale (designer-provided)

Token	px	Usage
`xs`	8	Tight gaps between inline elements
`s`	16	Screen horizontal padding, card padding, form field gap
`item-spacing.24`	24	Item spacing, section gaps
`m`	32	Grouping gaps, modal padding
`l`	48	Large section separation
`xl`	64	Screen-level separation, toolbar height

3.2 Fixed numeric scale (designer-provided)

0, 4, 5, 6, 7 px (micro gaps), 35, 53 px (special layout), and negative offsets -12, -2, -1 px.

The export also contains many decimal auto-layout "gap" values (e.g. 130, 238, 981.25, 1520.55) captured directly from Figma frames — not a spacing scale; do not reuse. TBD by designer for scale rationalization.

3.3 Layout conventions (from previous proposal, mapped to new scale)

Use	Value	Token
Screen horizontal padding	16	`s`
Card padding	16	`s`
Card gap	12	derived (half of `item-spacing.24`) — TBD by designer
Section gap	24	`item-spacing.24`
List item height	≥ 56	—
Form field gap	16	`s`
Toolbar height	64	`xl`

4. Radius

Token	Value	Source	Usage
`r-micro`	2.5px	`corner radius.2_5`	Tags, dense chips
`r-xs`	4px	(extrapolated — standard M3 4dp) TBD by designer	Small tags
`r-sm`	8px	`corner radius.8`	Inputs, buttons, cards
`r-md`	12px	`corner radius.12`	Cards (elevated), dialogs
`r-lg`	16px	(extrapolated — standard M3 16dp) TBD by designer	Bottom sheets, FAB
`r-xl`	28px	(extrapolated — standard M3 28dp) TBD by designer	Sheets, large surfaces
`r-full`	9999px	`corner radius.9999`	Avatars, pills

5. Elevation & shadow

No elevation/shadow tokens exist in the export. The dp scale below is a proposal built from Black + the export's opacity tokens (shadow color #000000 at 10% per step). TBD by designer — every row is a starting point.

Token	dp	Suggested shadow
`e-0`	0	`none`
`e-1`	1	`0 1px 2px rgba(0,0,0,0.10), 0 1px 3px rgba(0,0,0,0.10)`
`e-2`	3	`0 1px 2px rgba(0,0,0,0.10), 0 2px 6px rgba(0,0,0,0.10)`
`e-3`	6	`0 1px 3px rgba(0,0,0,0.10), 0 4px 8px rgba(0,0,0,0.10)`
`e-4`	8	`0 2px 3px rgba(0,0,0,0.10), 0 6px 10px rgba(0,0,0,0.10)`
`e-5`	12	`0 4px 4px rgba(0,0,0,0.10), 0 8px 12px rgba(0,0,0,0.10)`

Supporting export tokens: opacity.10/50/60/70/80/90/100 (scrim/overlay steps), stroke weight.1 (1px) / .2 (2px) for borders, shadow = Black.

6. Motion

No motion tokens in the export — still proposed (previous status).

Token	Duration	Curve	Usage
`m-instant`	0 ms	—	Value changes, icon toggles
`m-fast`	150 ms	easeOutCubic	Hover, focus, ripple, small state
`m-base`	250 ms	easeInOutCubic	Screen transitions, dialogs, sheets
`m-slow`	400 ms	easeInOutCubic	Hero, page fade, skeletons
`m-entrance`	300 ms	easeOutBack	List item entrance (stagger 40 ms)

Reduce-motion (platform setting): m-instant for all, no parallax, no stagger.

7. Iconography

No icon tokens in the export — Material Symbols remains the proposal (previous status). Confirm pack with designer before build.

Material Symbols (outlined, weight 400, optical 24). Sizes: 16/20/24/32/40. Status icons use filled variant. All icons need a text label or tooltip+Semantics.label.

8. Breakpoints (responsive)

Class	Width	Layout
Phone	< 600 dp	Bottom nav, single pane
Tablet	600–839 dp	Bottom nav + wider panes, 2-column lists
Landscape tablet	840–1199 dp	Navigation rail, master-detail
Desktop/web	≥ 1200 dp	Navigation rail/drawer, master-detail, hover states

9. Touch targets

Minimum 48 × 48 dp tappable; list rows ≥ 56 dp; FAB 56 dp; 44 dp acceptable for dense inline controls (chip remove, icon buttons with tooltips).

10. Light/dark parity rules

No color hardcoded in widget code — always token references
Surface contrast ≥ 3:1 for UI chrome, ≥ 4.5:1 for text
Elevation substitutes for color on dark surfaces
Both modes must pass the QA color checklist (see 10_QA_Baseline.md)
Dark chromatic roles are TBD by designer (§1.4) — gate dark-mode ship on sign-off

Keyboard shortcuts

StudyLyon — Design Docs