Design System — Quick Reference
This file is @imported in CLAUDE.md as session context. Keep it short. Full details in the files linked below.
Status:
packages/tokenscomplete — Session A values + violet/brand additions (ADR-0017).packages/web-uinot yet scaffolded — Phase 4.5.
Key Values
| Token | Dark mode | Light mode | Notes |
|---|---|---|---|
| Background | #0f0e17 | #faf9f4 | Warm purple-black / parchment |
| Surface | #1a1827 | #ffffff | |
| Surface raised | #232135 | #f2f0e6 | |
| Accent | #e8b84b | #5b4fcf | Amber (dark) / Violet (light) — buttons, active states |
| Accent hover | #c49a1a | #4a3db0 | |
| Accent text | #e8b84b | #3d319a | Colored text — passes WCAG AA in both modes |
| On accent | #0f0e17 | #ffffff | Text ON accent button — dark on amber, white on violet |
| Brand | #e8b84b | #c49a1a | Amber — ornaments, dividers only (not the logo mark) |
| Text | #f0eef8 | #0f0e17 | |
| Text muted | #a8a2cc | #524d80 | |
| Text faint | #524d80 | #7b75a8 | Décoratif uniquement — ne pas utiliser pour contenu essentiel |
Typography: Outfit 400/500/600/700/800 (font-display + font-body) · JetBrains Mono 400/500/600 (font-mono) · Self-hosted, font-display: optional
Line heights: paired to type scale — xs/sm/lg 1.5 · base 1.6 · xl 1.4 · 2xl 1.3 · 3xl 1.2 · 4xl 1.1
Letter spacing: tracking-tight -0.02em (headings) · tracking-normal 0 · tracking-wide0.04em (labels)
Semantic Token Names (packages/tokens)
bg · surface · surface-raised · surface-hover · border · border-subtle · border-focus
text · text-muted · text-faint
accent · accent-hover · accent-subtle · accent-border · accent-text · on-accent · brand
mtg-white · mtg-blue · mtg-black · mtg-red · mtg-green · mtg-colorless · mtg-multi
rarity-common · rarity-uncommon · rarity-rare · rarity-mythic
rarity-common-fg · rarity-uncommon-fg · rarity-rare-fg · rarity-mythic-fg
error · error-subtle · error-text
success · success-subtle · success-text
warning · warning-subtle · warning-text
info · info-subtle · info-text
shadow-popover · shadow-card · shadow-overlay · shadow-accent · shadow-sm · shadow-md · shadow-lg
z-base · z-raised · z-dropdown · z-sticky · z-overlay · z-modal · z-toast · z-tooltip
radius-interactive · radius-surface · radius-modal · radius-badge · radius-stampDimensions (control heights, icon sizes) are not tokens. They live in shared cva maps (
CONTROL_HEIGHT/CONTROL_SQUARE/ICON_SIZE/ICON_IN_CONTROL/ICON_INLINE) inpackages/web-ui/src/lib/sizing/, built on Tailwind's spacing scale. See ADR-0017, ADR-0021.
Additional design-system CSS in
layout.css:opacity-disabled(Tailwind@utilityfor disabled state — WCAG 1.4.3 exemption,opacity: 0.38). Inmtg.css:--shadow-pipCSS variable (inner-bevel on mana pips — not a Tailwind utility, used as[box-shadow:var(--shadow-pip)]).
info≠mtg-blue— neutral UI state vs MTG color identity, never substitute one for the other.
Token Architecture (packages/tokens)
web/
tokens.css → master @import — single file to import in apps
colors.css → :root · .dark · @theme inline (semantic colours + shadows)
mtg.css → @theme MTG colors (WUBRG + rarity + foregrounds)
typography.css → @theme font families, type scale, line-height, tracking
layout.css → @theme semantic radius roles, z-index (no size tokens — see ADR-0017)
motion.css → @theme durations, easings + @media prefers-reduced-motionTailwind v4 reads @theme and generates utility classes automatically — no JS preset.
Motion System
| Mode | Durée | Easing | Usage |
|---|---|---|---|
| Micro (A) | 50–200ms | ease-out | hover, focus, toggle, click feedback |
| Moments clés (B) | 300–500ms | ease-spring | modal, drawer, ajout de carte, ouverture builder |
| Navigation | 300ms | ease-in-out | transitions de route |
Non-Negotiable Rules
| Rule | Why |
|---|---|
| Semantic tokens only — never hardcoded hex | Theming, consistency, single source of truth |
Mana symbols via inline SVG paths (mana-font) + mtg-* pip backgrounds — never bare circles | Canonical MTG glyphs, tree-shakeable, no font load. ManaIcon → ManaSymbol → ManaCost |
Theme via .dark on <html>, not dark: variant | Runtime switching, no class proliferation in JSX |
| MTG tokens separate from semantic tokens | mtg-red ≠ error — different semantic meaning |
on-accent is mode-specific — dark on amber, white on violet | Contrast-driven: white on #e8b84b = 1.8:1 (fails); dark on #5b4fcf = 1.1:1 (fails) |
brand (amber) is for ornaments only — never the logo mark | Logo mark uses accent (amber dark / violet light) — theme-adaptive, coherent with halo color |
brand text fails AA in light mode (#c49a1a on #faf9f4 ≈ 2.9:1) | Dark mode is fine (9.8:1) but light mode fails — treat like text-faint, never for readable content |
text-faint for decoration only | 2.5:1 ratio — fails AA for readable content |
| Raw Tailwind type classes never in feature JSX | Encapsulated in <Heading>, <Body>, <Label> |
| Semantic radius tokens in components — never raw values | radius-interactive / radius-surface / radius-modal / radius-badge / radius-stamp — one rule per context, no drift |
| Design system section required in Storybook | Living style guide, always in sync with tokens |
Dimensions = cva map (CONTROL_HEIGHT / CONTROL_SQUARE / ICON_SIZE), never CSS tokens | Tailwind v4 has no --size-* namespace; --spacing-* would leak to p-*/gap-*; Tailwind's spacing scale already is the dimension token system |
Icon size derived from the parent component's size variant — never set by the caller | Three-table system: ICON_IN_CONTROL (square controls), ICON_INLINE (icon+label), ICON_SIZE (self-rendered). Escape hatch: explicit className="size-X" on the icon. See ADR-0021. |
Search Patterns (3 distinct contexts)
| Trigger | Pattern | Behaviour |
|---|---|---|
| Header search bar | Popover/spotlight | Grouped results: CARTES / DECKS / COLLECTION |
| Sidebar search icon | Page /search | Full filters, advanced search |
| Deck builder card add | Slide-over | Keeps deck context visible |
Navigation Patterns
- Desktop: Collapsed icon sidebar (expandable) — persistent left rail
- Mobile: Bottom navigation bar — 4–5 icons, no text labels
Full Documentation
- identity.md — full palette, typography scale, MTG touches
- decisions.md — all design decisions with rationale
- screens/ — ASCII mocks: auth, deck-list, deck-builder, collection, card-search, card-detail, settings
- ADR-0015 — architectural decisions (tokens, theming, Keyrune, no-Figma)
- ADR-0017 — implémentation de
packages/tokens(valeurs finales, hiérarchie, motion, contraste)