Charte et styles

Deux fichiers, deux responsabilités#

Cette séparation n'est pas cosmétique. Une classe manquante dans tokens.css et un token accepté par le schéma donneraient un contenu valide qui ne s'affiche pas — un bug invisible en revue. Les deux fichiers vivent donc ensemble, versionnés ensemble.

La charte du site#

C'est le seul fichier à reprendre pour habiller un nouveau site. Il ne définit que des variables :

:root {
  /* Palette — un nom de token du schéma, une variable */
  --color-primary: #101828;
  --color-secondary: #344054;
  --color-muted: #667085;
  --color-accent: #0b5cff;
  --color-inverse: #ffffff;

  --color-surface: #ffffff;
  --color-surface-alt: #f7f8fa;
  --color-border: #e4e7ec;

  /* Échelle typographique — un cran par valeur de l'enum « size » */
  --size-xs: 0.75rem;
  --size-sm: 0.875rem;
  --size-base: 1rem;
  --size-lg: 1.25rem;
  --size-xl: 1.5rem;
  --size-2xl: 2rem;
  --size-3xl: 2.75rem;

  /* Graisses — un cran par valeur de l'enum « weight » */
  --weight-thin: 100;
  --weight-light: 300;
  --weight-regular: 400;
  --weight-medium: 500;
  --weight-semibold: 600;
  --weight-bold: 700;

  --font-body: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
  --line-height: 1.5;

  --space-1: 0.5rem;
  --space-2: 1rem;
  --space-3: 1.5rem;
  --space-4: 2rem;
  --space-6: 3rem;
  --space-8: 4rem;

  --measure: 48rem;
}

La correspondance#

tokens.css traduit chaque valeur d'enum en une classe. Aucune valeur en dur : que des variables, définies par le site.

/* size */
.cms-size-xs   { font-size: var(--size-xs); }
.cms-size-base { font-size: var(--size-base); }
.cms-size-3xl  { font-size: var(--size-3xl); }

/* weight */
.cms-weight-regular  { font-weight: var(--weight-regular); }
.cms-weight-bold     { font-weight: var(--weight-bold); }

/* italic, align, color */
.cms-italic          { font-style: italic; }
.cms-align-center    { text-align: center; }
.cms-color-accent    { color: var(--color-accent); }

Le chemin complet, du fichier de contenu à l'écran :

Et dans l'autre sens : le bouton « accent » de la barre d'outils est construit à partir de la même liste que celle dont Zod tire son enum. Il ne peut donc pas exister de bouton proposant une valeur que le build refuserait — il n'y a pas deux listes à tenir d'accord.

Habiller un nouveau site#

1. Reprendre la palette

   Cinq couleurs de contenu (primary, secondary, muted, accent, inverse) et trois couleurs d'interface (surface, surface-alt, border). C'est peu, et c'est volontaire : cinq couleurs se choisissent bien, quinze se choisissent mal.

2. Poser l'échelle typographique

   Sept crans, de xs à 3xl. Gardez un rapport constant entre les crans plutôt que des valeurs choisies une par une : c'est ce qui empêche une page de dépareiller quand le client change une taille.

3. Choisir la police

   --font-body. Une police auto-hébergée se déclare ici, avec sa règle @font-face :

   @font-face {
     font-family: 'Inter';
     src: url('/fonts/inter.woff2') format('woff2');
     font-weight: 100 900;
     font-display: swap;
   }
   
   :root {
     --font-body: 'Inter', system-ui, sans-serif;
   }

   Les fichiers de police vont dans public/fonts/ — contrairement aux images de contenu, ils ne passent pas par <Image /> et n'ont rien à faire dans src/media.

4. Vérifier avec du vrai contenu

   npm run dev suffit : la mise en page se travaille sans les fonctions. Testez chaque cran de taille et chaque couleur au moins une fois — un token jamais utilisé est un token jamais vérifié.

La mise en page#

tokens.css embarque aussi un squelette de mise en page minimal (.page, .site-nav, .site-footer, .hero, .showcase, .testimonials, .site-langs). Il sert au gabarit livré et aux pages /admin et /aide, pour qu'un site neuf ne soit pas nu.

Ce que le client peut changer#

Au clic sur un texte, une barre propose exactement cinq réglages :

Sur un champ richtext, la barre propose gras, italique, lien et listes — et rien d'autre : ce sont exactement les balises que l'assainissement laisse passer.

Le collage depuis un traitement de texte#

C'est le cas qui arrive dès la première semaine. Un paragraphe collé depuis Word apporte ses polices, ses tailles en points, ses couleurs et une pile de balises invisibles. Le nettoyage à la saisie écrase tout, sans exception : il ne reste que le texte, le gras et l'italique.

Sans cela, la page se retrouve avec du Calibri 11 pt en plein milieu de la charte — et personne ne s'en aperçoit avant que le client ne s'en plaigne.

Ajouter un token de style#

Ajouter une valeur (une sixième couleur, un huitième cran de taille) se fait dans le paquet, en trois endroits qui doivent bouger ensemble :

1. src/style-tokens.ts — la liste, source unique ;
2. styles/tokens.css — la classe correspondante ;
3. la charte de chaque site — la variable, sinon la classe pointe vers rien.

Vérifications#

• Chaque variable attendue par tokens.css existe dans theme.css.
• Les cinq couleurs de contenu sont lisibles sur les surfaces où elles apparaissent.
• inverse est lisible sur les fonds sombres — c'est sa seule raison d'être.
• Les sept crans de taille restent hiérarchisés à l'écran.
• Le contraste des textes courants atteint 4,5:1 (AA).
• La page tient sur un écran de 360 px de large.