CSS Tokens

Les tokens suivent une dependance a sens unique : primitives → semantics → components. Un niveau peut referencer le niveau precedent, jamais l’inverse.

Architecture

src/styles/
  tokens-primitives.css
  tokens-semantic.css
  tokens-components.css
  pixel.css

Primitives

tokens-primitives.css contient les valeurs brutes exportees depuis Figma : palettes, tailles, spacing, radius, familles typographiques et valeurs de shadow.

:root {
  --colors-neutral-900: #141a32;
  --space-16: 1rem;
  --radius-8: 0.5rem;
}

Semantics

tokens-semantic.css transforme les primitives en intentions stables : texte, surface, action, feedback, spacing inline/stack/layout, typography et elevation.

:root {
  --color-text-primary: var(--colors-neutral-900);
  --color-background-surface: var(--colors-white);
  --spacing-stack-lg: var(--space-16);
  --radius-md: var(--radius-8);
}

Components

tokens-components.css contient les decisions propres aux composants. Ces tokens permettent de faire evoluer Button, Input ou Card sans modifier les roles globaux.

:root {
  --button-primary-background-default: var(--color-action-dark-base);
  --button-medium-padding-y: var(--spacing-stack-md);
  --input-radius: var(--radius-md);
  --card-bg: var(--color-background-surface);
}

Global entry point

pixel.css est le seul point d’entree recommande. L’ordre des imports fait partie du contrat.

@import './tokens-primitives.css';
@import './tokens-semantic.css';
@import './tokens-components.css';

Dans Astro, le portail charge ce fichier globalement depuis astro.config.mjs :

starlight({
  customCss: ['./src/styles/pixel.css', './src/styles/starlight.css'],
});

Usage

Dans une page ou un layout, utiliser les tokens semantiques :

.page-panel {
  padding: var(--spacing-layout-md);
  border: 1px solid var(--color-border-default);
  border-radius: var(--radius-xl);
  background: var(--color-background-surface);
  color: var(--color-text-default);
}

Dans l’implementation d’un composant, utiliser ses tokens dedies :

.button--primary {
  padding: var(--button-medium-padding-y) var(--button-medium-padding-x);
  border-radius: var(--button-medium-radius);
  background: var(--button-primary-background-default);
  color: var(--button-primary-text-default);
}

Compatibility

tokens.css reste temporairement disponible comme alias vers pixel.css pour ne pas casser les imports existants. Les nouvelles integrations doivent importer pixel.css directement.

Rules

• Ne pas referencer un component token depuis semantics ou primitives.
• Ne pas utiliser une primitive dans un composant si un token semantic ou component existe.
• Ne pas redefinir un token Figma dans starlight.css.
• Garder les aliases temporaires marques avec TODO(Figma).
• Conserver l’ordre d’import primitives, semantics, components.