3 · Sémantique (le reste)
Au-delà du contrat de rôle : les fonds, le texte, les bordures, le focus, les tailles et la typo.
Couleur
surface est le seul groupe qui parle de fonds.
surface
base
Fond de l’application.
raised
Fond d’un bloc surélevé (carte, panneau).
overlay
Fond d’un élément flottant (popover, menu, modale).
sunken
Fond en creux (piste de slider, zone de dépôt).
inverse
Rupture visuelle négative (tooltip, bandeau).
disabled
Fond d’un composant désactivé.
transparent
Fond absent (variantes outlined/ghost).
text
strong
Titres et libellés d’interface appuyés. Le contraste maximal.
body
Texte de lecture.
muted
Texte secondaire (légende, description).
faint
⚠ NE PASSE PAS AA — décoratif uniquement (séparateurs, échafaudage). Jamais pour du texte à lire.
disabled
Texte d’un composant désactivé.
inverse
Texte posé sur `surface.inverse`.
border
default
Bordure par défaut de tous les composants.
strong
Bordure appuyée.
divider
Séparateur entre deux blocs de contenu.
disabled
Bordure d’un composant désactivé.
transparent
Bordure absente.
Focus & scrim
focus.ring
Anneau de focus clavier. Doit rester visible sur tous les fonds.scrim
Voile assombrissant sous une modale ou un drawer.Tailles — desktop vs mobile
Seules les lignes ≠ sont réémises dans la media query du CSS généré. Les autres sont identiques : aucune ligne inutile.
| Rôle | Desktop | Mobile (< 768px) |
|---|---|---|
space.xs | 4px | 2px ≠ |
space.sm | 8px | 4px ≠ |
space.md | 16px | 12px ≠ |
space.lg | 24px | 16px ≠ |
space.xl | 32px | 24px ≠ |
radius.sm | 4px | 4px |
radius.md | 8px | 8px |
radius.lg | 16px | 8px ≠ |
radius.full | 9999px | 9999px |
borderWidth.default | 1px | 1px |
borderWidth.strong | 2px | 2px |
borderWidth.focus | 2px | 2px |
fontSize.caption | 12px | 12px |
fontSize.small | 14px | 14px |
fontSize.body | 16px | 16px |
fontSize.lead | 20px | 18px ≠ |
fontSize.h3 | 24px | 20px ≠ |
fontSize.h2 | 32px | 24px ≠ |
fontSize.h1 | 48px | 32px ≠ |
Breakpoints. Une media query CSS ne peut pas lire une custom property
—
@media (max-width: var(--size-breakpoint-md)) ne fonctionne pas. Le build lit
donc size.breakpoint.md dans les tokens et inline sa valeur. Une seule source de
vérité.
Typographie
Chaque rôle porte 6 slots — famille, taille, graisse, interligne, crénage, casse —
et se suffit donc à lui-même : font: var(--typography-h1-*) et rien d'autre. La
taille est une référence à fontSize.* (ci-dessus), pas une valeur :
le rôle hérite de la bascule mobile sans la connaître.
| Rôle | Aperçu | Taille · graisse · interligne · crénage |
|---|---|---|
typography.h1 |
Le vif renard brun saute | 48px · 700 · 1.2 · -0.02em |
typography.h2 |
Le vif renard brun saute | 32px · 700 · 1.2 · -0.02em |
typography.h3 |
Le vif renard brun saute | 24px · 600 · 1.2 · -0.01em |
typography.lead |
Le vif renard brun saute | 20px · 400 · 1.5 · 0 |
typography.body |
Le vif renard brun saute | 16px · 400 · 1.5 · 0 |
typography.small |
Le vif renard brun saute | 14px · 400 · 1.5 · 0 |
typography.label |
Le vif renard brun saute | 14px · 500 · 1.2 · 0 |
typography.caption |
Le vif renard brun saute | 12px · 400 · 1.5 · 0.02em |
typography.overline |
Le vif renard brun saute | 12px · 600 · 1.5 · 0.08em |
typography.code |
Le vif renard brun saute | 14px · 400 · 1.5 · 0 |
Tous les tokens de chaque rôle
Les 6 slots de chaque rôle — famille, taille, graisse, interligne,
crénage, casse — le token sémantique que chacun consomme (cliquable, vers la page qui le définit),
et la valeur résolue. C'est ici que se voient font-family, font-weight, etc.
| Token | Consomme (sémantique) | Valeur résolue |
|---|---|---|
| --typography-h1-family | --font-brand-heading |
Inter, system-ui, -apple-system, sans-serif |
| --typography-h1-size | --font-size-h1 |
48px |
| --typography-h1-weight | --font-weight-bold |
700 |
| --typography-h1-line-height | --font-line-height-tight |
1.2 |
| --typography-h1-letter-spacing | --font-letter-spacing-tight |
-0.02em |
| --typography-h1-text-case | valeur directe | none |
| --typography-h2-family | --font-brand-heading |
Inter, system-ui, -apple-system, sans-serif |
| --typography-h2-size | --font-size-h2 |
32px |
| --typography-h2-weight | --font-weight-bold |
700 |
| --typography-h2-line-height | --font-line-height-tight |
1.2 |
| --typography-h2-letter-spacing | --font-letter-spacing-tight |
-0.02em |
| --typography-h2-text-case | valeur directe | none |
| --typography-h3-family | --font-brand-heading |
Inter, system-ui, -apple-system, sans-serif |
| --typography-h3-size | --font-size-h3 |
24px |
| --typography-h3-weight | --font-weight-semibold |
600 |
| --typography-h3-line-height | --font-line-height-tight |
1.2 |
| --typography-h3-letter-spacing | --font-letter-spacing-snug |
-0.01em |
| --typography-h3-text-case | valeur directe | none |
| --typography-lead-family | --font-brand-body |
'JetBrains Mono', ui-monospace, 'SF Mono', monospace |
| --typography-lead-size | --font-size-lead |
20px |
| --typography-lead-weight | --font-weight-regular |
400 |
| --typography-lead-line-height | --font-line-height-normal |
1.5 |
| --typography-lead-letter-spacing | --font-letter-spacing-normal |
0 |
| --typography-lead-text-case | valeur directe | none |
| --typography-body-family | --font-brand-body |
'JetBrains Mono', ui-monospace, 'SF Mono', monospace |
| --typography-body-size | --font-size-body |
16px |
| --typography-body-weight | --font-weight-regular |
400 |
| --typography-body-line-height | --font-line-height-normal |
1.5 |
| --typography-body-letter-spacing | --font-letter-spacing-normal |
0 |
| --typography-body-text-case | valeur directe | none |
| --typography-small-family | --font-brand-body |
'JetBrains Mono', ui-monospace, 'SF Mono', monospace |
| --typography-small-size | --font-size-small |
14px |
| --typography-small-weight | --font-weight-regular |
400 |
| --typography-small-line-height | --font-line-height-normal |
1.5 |
| --typography-small-letter-spacing | --font-letter-spacing-normal |
0 |
| --typography-small-text-case | valeur directe | none |
| --typography-label-family | --font-brand-body |
'JetBrains Mono', ui-monospace, 'SF Mono', monospace |
| --typography-label-size | --font-size-small |
14px |
| --typography-label-weight | --font-weight-medium |
500 |
| --typography-label-line-height | --font-line-height-tight |
1.2 |
| --typography-label-letter-spacing | --font-letter-spacing-normal |
0 |
| --typography-label-text-case | valeur directe | none |
| --typography-caption-family | --font-brand-body |
'JetBrains Mono', ui-monospace, 'SF Mono', monospace |
| --typography-caption-size | --font-size-caption |
12px |
| --typography-caption-weight | --font-weight-regular |
400 |
| --typography-caption-line-height | --font-line-height-normal |
1.5 |
| --typography-caption-letter-spacing | --font-letter-spacing-wide |
0.02em |
| --typography-caption-text-case | valeur directe | none |
| --typography-overline-family | --font-brand-body |
'JetBrains Mono', ui-monospace, 'SF Mono', monospace |
| --typography-overline-size | --font-size-caption |
12px |
| --typography-overline-weight | --font-weight-semibold |
600 |
| --typography-overline-line-height | --font-line-height-normal |
1.5 |
| --typography-overline-letter-spacing | --font-letter-spacing-caps |
0.08em |
| --typography-overline-text-case | valeur directe | uppercase |
| --typography-code-family | --font-brand-mono |
'JetBrains Mono', ui-monospace, 'SF Mono', monospace |
| --typography-code-size | --font-size-small |
14px |
| --typography-code-weight | --font-weight-regular |
400 |
| --typography-code-line-height | --font-line-height-normal |
1.5 |
| --typography-code-letter-spacing | --font-letter-spacing-normal |
0 |
| --typography-code-text-case | valeur directe | none |
La police est dans le brand, pas dans la primitive. Un rôle pointe sur
font.brand.heading|body|mono, qui désigne une pile du catalogue
font.stack.*. Les titres (heading) et le corps (body)
portent deux polices distinctes ; changer l'une, c'est une ligne — BRAND_FONT dans
scripts/generate-theme.js — exactement comme changer la couleur d'un rôle.