Créer un design system avec Claude Code : tokens, Storybook et CI

Le problème commence quand chaque écran interprète le design différemment

Imaginez un changement de bleu principal. Le bouton de connexion adopte la nouvelle couleur, mais le paiement conserve l’ancienne, l’indicateur de focus disparaît et une carte devient illisible en mode sombre. L’équipe possède des composants, mais pas encore de méthode fiable pour faire évoluer le produit.

Un design system n’est pas seulement un catalogue de boutons, de cartes et de formulaires. C’est un modèle de travail qui permet de modifier couleurs, espacements, typographie, états et tests sans casser les écrans. Claude Code peut lire le dépôt, modifier plusieurs fichiers liés, lancer Storybook et les tests, puis présenter le diff. Il ne remplace ni le jugement produit, ni les choix de marque, ni la validation finale de l’accessibilité.

Les quatre résultats attendus

Transformer les décisions visuelles en tokens vérifiables et générés automatiquement.
Construire un composant React/TypeScript avec des états explicites et une API stable.
Utiliser @storybook/addon-vitest et vitest --project=storybook, la voie recommandée pour Storybook en 2026.
Séparer les tâches répétables confiées à Claude Code des décisions qui restent humaines.

Ce guide couvre aussi les limites réalistes d’une intégration Figma, l’accessibilité et les contrôles visuels en CI. Pour aller plus loin, consultez la gestion des Design Tokens avec Claude Code, le développement avec Storybook et l’accessibilité avec Claude Code.

Architecture cible : un contrat que la CI peut vérifier

Dans ce flux, tokens.json constitue le contrat côté code. Figma reste indispensable à l’exploration et à la revue du design, mais les décisions qui atteignent le produit doivent exister dans un format versionné, lisible dans un diff et contrôlable par la CI.

flowchart LR
  Figma["Figma Variables"]
  Tokens["tokens.json"]
  Build["token build script"]
  CSS["CSS variables"]
  TS["TypeScript token map"]
  Components["React components"]
  Storybook["Storybook stories"]
  CI["Visual and a11y CI"]

  Figma -->|review input| Tokens
  Tokens --> Build
  Build --> CSS
  Build --> TS
  CSS --> Components
  TS --> Components
  Components --> Storybook
  Storybook --> CI

Les Design Tokens sont des décisions nommées et stockées comme données : couleurs, espacements, rayons, typographie et états de composants. Une valeur brute comme #2563eb décrit une apparence. Un token sémantique comme action.background.primary décrit une intention et résiste mieux à un changement de marque.

Les références actuelles sont le format du Design Tokens Community Group, la documentation de Claude Code, son guide de sécurité, l’addon Vitest de Storybook, les guides de tests d’accessibilité et de tests visuels, ainsi que l’API REST de Figma.

Ce que Claude Code exécute et ce qu’une personne décide

Claude Code donne de meilleurs résultats lorsque la liste des fichiers, le comportement à préserver et les commandes de validation sont explicites. « Crée un design system » ouvre trop de décisions à la fois. « Migre uniquement Button, conserve son API publique, ajoute ses états Storybook et exécute les tests d’accessibilité » aboutit à un changement qu’une personne peut réellement relire.

Domaine	Bon périmètre pour Claude Code	Décision humaine
Tokens	Extraire du CSS les couleurs et espacements répétés	Sens de la marque et noms définitifs
Composants	Implémenter des primitives typées `Button`, `Input` et `Alert`	API publique et sémantique produit
Storybook	Ajouter variantes, états et stories d’interaction	États utiles dans les parcours réels
Accessibilité	Détecter labels absents, défauts de focus et violations axe	Validation finale au clavier et au lecteur d’écran
CI	Ajouter des contrôles visuels et a11y aux pull requests	Politique de blocage et exceptions

Donnez une règle de projet courte avant toute modification :

Règles pour une tâche du design system :
- Modifie uniquement src/components, src/styles, .storybook, tests, scripts et tokens.json.
- Ne change aucune couleur de marque sans lister les anciens et nouveaux noms de tokens.
- Chaque nouveau composant doit avoir des props TypeScript, un comportement clavier, des stories Storybook et des notes d'accessibilité.
- Exécute npm run tokens:build, npm run test:storybook -- --run, npm run build-storybook et npm run test:visual avant d'annoncer la fin de la tâche.
- Si le comportement du focus change, fournis les étapes de vérification manuelle.

La sécurité appartient au flux de conception. Ne collez jamais de jetons d’accès Figma ou npm, de secrets CI ni de captures privées de clients dans un prompt. Limitez les permissions de Claude Code, relisez les commandes avant de les approuver et exigez une validation humaine pour toute mise à jour massive de snapshots.

Installation minimale avec Storybook et Vitest

L’exemple part d’une application React avec TypeScript et des classes utilitaires. Adaptez les commandes au gestionnaire de paquets du projet.

npm install class-variance-authority clsx tailwind-merge
npx storybook@latest init
npx storybook add @storybook/addon-a11y
npx storybook add @storybook/addon-vitest
npm install -D @playwright/test concurrently http-server wait-on
npx playwright install chromium

En 2026, la configuration recommandée pour un Storybook basé sur Vite est @storybook/addon-vitest. Elle fonctionne aussi avec l’intégration Next.js sur Vite prise en charge par Storybook. Si votre framework ne peut pas l’utiliser, consultez l’ancien @storybook/test-runner uniquement comme solution de repli ou de migration ; ne remplacez pas Vitest sans vérifier la compatibilité du projet.

Ajoutez les mêmes scripts en local et en CI. Le point décisif est que test:storybook lance bien vitest --project=storybook :

{
  "scripts": {
    "tokens:build": "node scripts/build-tokens.mjs",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "test:storybook": "vitest --project=storybook",
    "test:visual": "playwright test tests/button.visual.spec.ts"
  }
}

Faites des tokens un contrat vérifiable

Séparez les tokens en trois couches. Les primitifs stockent les valeurs brutes, les tokens sémantiques décrivent une intention et les tokens de composants représentent un état propre à l’interface. Cette structure évite qu’un changement de marque se transforme en recherche-remplacement globale.

{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "primitive": {
    "color": {
      "blue": {
        "50": {
          "$type": "color",
          "$value": { "colorSpace": "srgb", "components": [0.9373, 0.9647, 1], "hex": "#eff6ff" }
        },
        "600": {
          "$type": "color",
          "$value": { "colorSpace": "srgb", "components": [0.1451, 0.3882, 0.9216], "hex": "#2563eb" }
        },
        "700": {
          "$type": "color",
          "$value": { "colorSpace": "srgb", "components": [0.1137, 0.3059, 0.8471], "hex": "#1d4ed8" }
        }
      },
      "gray": {
        "50": {
          "$type": "color",
          "$value": { "colorSpace": "srgb", "components": [0.9765, 0.9804, 0.9843], "hex": "#f9fafb" }
        },
        "200": {
          "$type": "color",
          "$value": { "colorSpace": "srgb", "components": [0.898, 0.9059, 0.9216], "hex": "#e5e7eb" }
        },
        "900": {
          "$type": "color",
          "$value": { "colorSpace": "srgb", "components": [0.0667, 0.0941, 0.1529], "hex": "#111827" }
        }
      },
      "red": {
        "600": {
          "$type": "color",
          "$value": { "colorSpace": "srgb", "components": [0.8627, 0.149, 0.149], "hex": "#dc2626" }
        },
        "700": {
          "$type": "color",
          "$value": { "colorSpace": "srgb", "components": [0.7255, 0.1098, 0.1098], "hex": "#b91c1c" }
        }
      },
      "white": {
        "$type": "color",
        "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" }
      }
    },
    "space": {
      "2": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
      "3": { "$type": "dimension", "$value": { "value": 0.75, "unit": "rem" } },
      "4": { "$type": "dimension", "$value": { "value": 1, "unit": "rem" } },
      "6": { "$type": "dimension", "$value": { "value": 1.5, "unit": "rem" } }
    },
    "radius": {
      "md": { "$type": "dimension", "$value": { "value": 0.375, "unit": "rem" } },
      "lg": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } }
    }
  },
  "semantic": {
    "color": {
      "surface": { "$type": "color", "$value": "{primitive.color.white}" },
      "text": { "$type": "color", "$value": "{primitive.color.gray.900}" },
      "border": { "$type": "color", "$value": "{primitive.color.gray.200}" },
      "focus": { "$type": "color", "$value": "{primitive.color.blue.600}" }
    }
  },
  "component": {
    "button": {
      "primary": {
        "background": { "$type": "color", "$value": "{primitive.color.blue.600}" },
        "backgroundHover": { "$type": "color", "$value": "{primitive.color.blue.700}" },
        "text": { "$type": "color", "$value": "{primitive.color.white}" }
      },
      "danger": {
        "background": { "$type": "color", "$value": "{primitive.color.red.600}" },
        "backgroundHover": { "$type": "color", "$value": "{primitive.color.red.700}" },
        "text": { "$type": "color", "$value": "{primitive.color.white}" }
      }
    }
  }
}

Générez les variables CSS et la table TypeScript depuis ce même fichier. Les styles et la logique consomment ainsi exactement les mêmes noms :

import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname } from "node:path";

const source = JSON.parse(readFileSync("tokens.json", "utf8"));

function getToken(path) {
  const node = path.split(".").reduce((current, key) => current?.[key], source);
  if (!node || typeof node.$value === "undefined") {
    throw new Error(`Unknown token reference: ${path}`);
  }
  return node.$value;
}

function resolveValue(value, stack = []) {
  if (typeof value === "string" && value.startsWith("{") && value.endsWith("}")) {
    const path = value.slice(1, -1);
    if (stack.includes(path)) {
      throw new Error(`Circular token reference: ${[...stack, path].join(" -> ")}`);
    }
    return resolveValue(getToken(path), [...stack, path]);
  }
  return value;
}

function toCssValue(value) {
  if (value && typeof value === "object") {
    if (typeof value.hex === "string") return value.hex;
    if (typeof value.value === "number" && typeof value.unit === "string") {
      return `${value.value}${value.unit}`;
    }
    throw new Error(`Unsupported token value: ${JSON.stringify(value)}`);
  }
  return String(value);
}

function walk(node, pathParts = [], result = {}) {
  if (!node || typeof node !== "object") return result;

  if (node && typeof node === "object" && typeof node.$value !== "undefined") {
    result[pathParts.join("-")] = toCssValue(resolveValue(node.$value));
    return result;
  }

  for (const [key, value] of Object.entries(node)) {
    if (key.startsWith("$")) continue;
    walk(value, [...pathParts, key], result);
  }

  return result;
}

const flat = walk(source);
const css = [
  ":root {",
  ...Object.entries(flat).map(([name, value]) => `  --${name}: ${value};`),
  "}",
  ""
].join("\n");

mkdirSync(dirname("src/styles/tokens.css"), { recursive: true });
mkdirSync(dirname("src/tokens.ts"), { recursive: true });
writeFileSync("src/styles/tokens.css", css);
writeFileSync("src/tokens.ts", `export const tokens = ${JSON.stringify(flat, null, 2)} as const;\n`);

console.log(`Generated ${Object.keys(flat).length} tokens.`);

Ne demandez pas à Claude Code de réécrire toute l’interface dès la première étape. Faites-lui repérer les couleurs et espacements bruts répétés, proposer des tokens et produire un rapport avant toute édition. Une personne valide les noms, car ils forment le langage commun du design et du développement.

Construisez des composants React typés et prévisibles

La couche de composants doit rester prévisible. Ce Button déclare variantes, tailles, chargement, désactivation et focus visible. Il ne cherche pas à anticiper tous les futurs boutons : il expose une petite API que les tests permettent de faire évoluer.

import { forwardRef, type ButtonHTMLAttributes } from "react";
import { cva, type VariantProps } from "class-variance-authority";
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

const buttonVariants = cva(
  [
    "inline-flex items-center justify-center gap-2 rounded-md font-medium",
    "transition-colors focus-visible:outline-none focus-visible:ring-2",
    "focus-visible:ring-[var(--semantic-color-focus)] focus-visible:ring-offset-2",
    "disabled:pointer-events-none disabled:opacity-50"
  ],
  {
    variants: {
      variant: {
        primary: [
          "bg-[var(--component-button-primary-background)]",
          "text-[var(--component-button-primary-text)]",
          "hover:bg-[var(--component-button-primary-backgroundHover)]"
        ],
        secondary: "border border-[var(--semantic-color-border)] bg-[var(--semantic-color-surface)] text-[var(--semantic-color-text)] hover:bg-gray-50",
        danger: [
          "bg-[var(--component-button-danger-background)]",
          "text-[var(--component-button-danger-text)]",
          "hover:bg-[var(--component-button-danger-backgroundHover)]"
        ]
      },
      size: {
        sm: "h-8 px-3 text-sm",
        md: "h-10 px-4 text-sm",
        lg: "h-12 px-6 text-base"
      }
    },
    defaultVariants: {
      variant: "primary",
      size: "md"
    }
  }
);

export interface ButtonProps
  extends ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  loading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
  { className, variant, size, loading = false, disabled, children, ...props },
  ref
) {
  return (
    <button
      ref={ref}
      className={cn(buttonVariants({ variant, size }), className)}
      disabled={disabled || loading}
      aria-busy={loading || undefined}
      {...props}
    >
      {loading ? (
        <span
          aria-hidden="true"
          className="h-4 w-4 animate-spin rounded-full border-2 border-current border-r-transparent"
        />
      ) : null}
      <span>{children}</span>
    </button>
  );
});

La bonne question n’est pas seulement « le bouton est-il joli ? ». Vérifiez plutôt si les props conservent un sens stable, si tous les états fonctionnent au clavier et si plusieurs équipes peuvent adopter cette API sans casser leurs écrans.

Transformez Storybook en spécification exécutable

Chaque état significatif doit exister sous forme de story. Si chargement, erreur, désactivation ou focus sont absents de Storybook, ils deviennent difficiles à relire, tester et discuter avec l’équipe design. Les libellés du bloc restent en anglais afin de conserver exactement le code vérifié dans la source.

import type { Meta, StoryObj } from "@storybook/react-vite";
import { Button } from "./Button";

const meta = {
  title: "Design System/Button",
  component: Button,
  parameters: {
    layout: "centered",
    a11y: {
      test: "error"
    }
  },
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "danger"]
    },
    size: {
      control: "select",
      options: ["sm", "md", "lg"]
    },
    loading: { control: "boolean" },
    disabled: { control: "boolean" }
  }
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: {
    children: "Save changes",
    variant: "primary"
  }
};

export const Danger: Story = {
  args: {
    children: "Delete",
    variant: "danger"
  }
};

export const Loading: Story = {
  args: {
    children: "Saving",
    loading: true
  }
};

export const AllStates: Story = {
  render: () => (
    <div className="flex flex-wrap items-center gap-3">
      <Button variant="primary" size="sm">Small</Button>
      <Button variant="primary" size="md">Medium</Button>
      <Button variant="primary" size="lg">Large</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="danger">Danger</Button>
      <Button disabled>Disabled</Button>
      <Button loading>Loading</Button>
    </div>
  )
};

Demandez à Claude Code de conserver les stories existantes, d’ajouter uniquement les états manquants et d’expliquer chaque changement d’identifiant. Ces identifiants alimentent URLs, snapshots et rapports ; une refactorisation ne doit pas les modifier silencieusement.

Exécutez composants, accessibilité et snapshots en CI

Les contrôles automatiques ne remplacent pas une revue au clavier et au lecteur d’écran, mais ils détectent tôt de nombreux défauts structurels. Pour Storybook sur Vite, l’addon Vitest transforme les stories en tests de navigateur. Avec parameters.a11y.test = "error", une violation signalée par l’addon d’accessibilité fait échouer le test du composant.

Dans la CI, lancez npm run test:storybook -- --run. Contrairement à l’ancien flux test-runner, Vitest n’exige pas de serveur Storybook séparé pour les tests de composants et d’accessibilité. Le serveur de la version statique n’est conservé ici que pour le snapshot Playwright personnalisé ci-dessous.

Commencez par peu de captures et choisissez des stories à forte valeur. Dates, animations, polices distantes et identifiants aléatoires produisent du bruit ; stabilisez ces données avant d’élargir la couverture visuelle.

Avant d’activer la CI, exécutez une fois npx playwright test tests/button.visual.spec.ts --update-snapshots dans l’application cible, contrôlez l’image de référence puis validez-la dans le dépôt. Sans référence, la première exécution échoue car Playwright n’a rien à comparer.

import { expect, test } from "@playwright/test";

test("button all states visual snapshot", async ({ page }) => {
  await page.goto("http://127.0.0.1:6006/iframe.html?id=design-system-button--all-states");
  await expect(page).toHaveScreenshot("button-all-states.png", {
    fullPage: true,
    animations: "disabled"
  });
});

Branchez ensuite ces mêmes commandes dans GitHub Actions :

name: design-system-quality

on:
  pull_request:
    paths:
      - "tokens.json"
      - "scripts/build-tokens.mjs"
      - "src/components/**"
      - "src/styles/**"
      - ".storybook/**"
      - "tests/**"
      - "package.json"
      - "package-lock.json"

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run tokens:build
      - run: npx playwright install --with-deps chromium
      - run: npm run test:storybook -- --run
      - run: npm run build-storybook
      - run: >
          npx concurrently -k -s first -n server,tests
          "npx http-server storybook-static -p 6006"
          "npx wait-on http://127.0.0.1:6006 && npm run test:visual"

En cas d’échec, donnez à Claude Code l’identifiant de la story, la violation d’accessibilité, les fichiers modifiés et le diff visuel. Ne collez ni secrets ni journaux complets : réduisez les éléments au contexte nécessaire au diagnostic.

Une limite réaliste pour l’intégration Figma

Les variables Figma constituent une entrée utile, mais une synchronisation bidirectionnelle automatique est généralement trop risquée au départ. Des expériences non approuvées, d’anciens noms de composants ou des notes privées peuvent se retrouver dans les tokens de production sans décision explicite.

Domaine	Bonne automatisation	À éviter
Variables Figma	Exporter et comparer avec `tokens.json`	Écraser les tokens de production à l’aveugle
Composants Figma	Recenser les candidats d’états et de props	Décider automatiquement des API React
Commentaires Figma	Résumer les questions non résolues	Déduire l’intention finale du design
Liens Storybook	Joindre les stories à la revue design	Considérer Storybook comme une approbation

Demandez d’abord à Claude Code un rapport de revue, sans autorisation de modifier les tokens :

Lis figma-tokens-export.json et tokens.json.
Crée un rapport Markdown avec :
1. les tokens présents dans Figma mais absents du code
2. les tokens présents dans le code mais absents de Figma
3. les différences de valeur entre tokens sémantiques correspondants
Ne modifie pas tokens.json et ne renomme aucun token. Signale comme risquées les différences liées au focus, au danger et à la couleur du texte.

L’objectif n’est pas la synchronisation pour elle-même. Il faut obtenir un diff réduit, explicable et réversible qu’une personne peut approuver.

Cas d’usage pratiques

Cas d’usage 1 : interface d’administration SaaS

Boutons, formulaires, tableaux et fenêtres modales comportent de nombreux états. Claude Code peut inventorier les usages, proposer des props de compatibilité et migrer un écran à la fois. La personne responsable du produit choisit les états obligatoires et valide les changements visuels.

Cas d’usage 2 : produit en marque blanche

Les couleurs primitives changent selon le client, tandis que les tokens sémantiques comme surface, text ou danger restent stables. Claude Code peut générer les variables CSS de chaque marque et les sélecteurs de thème Storybook. L’équipe design valide contrastes et associations avant publication.

Cas d’usage 3 : nettoyage d’un CSS historique

Claude Code peut repérer les valeurs brutes répétées, les regrouper en candidats et produire une table de migration. Ne remplacez pas tout dans un seul commit. Migrez un composant, exécutez les snapshots et comparez les écrans avant le lot suivant.

Cas d’usage 4 : parcours marketing ou formulaire de contact

Des boutons d’action, cartes tarifaires et états de formulaire cohérents rassurent les visiteurs et facilitent les expériences de conversion. L’agent applique les tokens et crée les stories ; une personne décide du message, de la hiérarchie et de la pertinence du parcours.

Pièges concrets : cause et correction

Utiliser directement des tokens primitifs

Cause : les composants dépendent de noms comme blue-600, qui décrivent une apparence plutôt qu’une intention. Correction : introduisez un token sémantique ou de composant, migrez par petits lots et vérifiez visuellement chaque étape.

Laisser Storybook en dehors de la CI

Cause : le catalogue fonctionne sur la machine d’une personne, mais peut casser sans bloquer un pull request. Correction : exécutez vitest --project=storybook, compilez Storybook et gardez le serveur statique uniquement pour les captures Playwright.

Multiplier trop vite les snapshots

Cause : animations, dates, polices externes et IDs aléatoires créent des différences sans intérêt. Correction : figez les données dynamiques et commencez par les états normal, chargement, erreur, désactivé et danger.

Confondre réussite automatique et accessibilité complète

Cause : axe ne comprend pas tout le contexte, la qualité des libellés ni la fluidité du parcours clavier. Correction : ajoutez une revue humaine au clavier et au lecteur d’écran avant d’accepter le composant.

Confier une migration entière en une seule tâche

Cause : le diff mélange décisions d’API, styles et régressions sur trop d’écrans. Correction : limitez les fichiers et le composant, exigez les tests, relisez le diff puis ouvrez seulement le lot suivant.

Liste de contrôle avant fusion

La personne chargée de la revue doit confirmer que :

Les noms de tokens expriment une intention et pas seulement une apparence.
Les props du composant sont minimales et stables.
Storybook couvre les états désactivé, chargement, erreur, focus et hover.
Le parcours fonctionne entièrement au clavier.
ARIA est présent quand il est nécessaire, sans remplacer un HTML natif correct.
Une personne a examiné chaque modification de snapshot.
Le rapport de différences Figma est conservé comme preuve de revue.
Claude Code n’a modifié que les zones demandées.
Aucun secret ni donnée privée n’apparaît dans prompts, logs, stories ou captures.

Ajoutez cette liste aux instructions du projet. Une future session pourra ainsi réutiliser les mêmes garde-fous sans dépendre d’un rappel oral.

Choisissez une seule prochaine étape

Commencez par exécuter le générateur de tokens.json et relire le CSS obtenu. Vérifiez ensuite que les stories de Button rendent tous les états et que la CI reproduit tests et snapshots. Gardez Figma en mode rapport jusqu’à l’accord de l’équipe sur la source de vérité. Pour mettre ce flux en place avec un accompagnement, utilisez la page de formation et de conseil Claude Code.

Ce qui a réellement été testé

Le 22 juillet 2026, le code build-tokens.mjs de cet article a été extrait puis exécuté avec l’exemple complet de tokens.json. Il s’est terminé avec le code 0, a généré 25 propriétés personnalisées CSS et la table de tokens TypeScript, et a résolu {primitive.color.blue.600} en #2563eb. Une fixture négative contenant une référence inconnue s’est terminée avec un code non nul et le message Unknown token reference. Les extraits JSON ont été analysés, puis les blocs de code et les liens internes vérifiés. Les commandes Storybook ont été comparées à la documentation officielle actuelle de l’addon Vitest et de sa migration. Storybook n’est pas installé dans le dépôt de ce site ; il faut donc exécuter les tests de composants et les tests visuels dans l’application cible avant d’adopter ce flux.