Variables CSS avec Claude Code : tokens de theme pratiques

Les variables CSS structurent les decisions visuelles

Les variables CSS, appelees officiellement proprietes personnalisees CSS, permettent de definir une valeur comme --color-accent puis de l’utiliser avec var(--color-accent). En termes simples, ce sont des emplacements nommes pour les couleurs, espacements, rayons, ombres, tailles de texte et variantes d’etat.

Avec Claude Code, cette frontiere est utile. Une demande vague comme “fais une belle carte” peut produire du CSS avec des couleurs dupliquees dans chaque selecteur. Une demande basee sur des tokens de theme donne au contraire un vocabulaire stable pour les prochaines modifications : mode sombre, couleur de CTA, marque client ou variante compacte.

Lisez aussi le guide du mode sombre, le systeme de design et les patterns Flexbox. Le modele mental est le suivant : tokens de palette pour les valeurs brutes, tokens semantiques pour le sens produit, tokens de composant pour une piece d’interface, puis tokens d’etat pour dark, danger, compact ou marque.

Demander les tokens avant l’interface

Ce prompt force Claude Code a produire une base reutilisable au lieu d’un style ponctuel.

{
  "task": "Create CSS custom properties for an article UI and implement a copy-paste demo.",
  "mustInclude": [
    "palette tokens",
    "semantic theme tokens",
    "component-level tokens",
    "var() fallbacks",
    "dark mode with data-theme and prefers-color-scheme",
    "vanilla JavaScript for theme switching"
  ],
  "constraints": [
    "Use custom properties only for values, not selectors or property names.",
    "Keep contrast readable in light and dark modes.",
    "Add comments for tokens that product designers may edit."
  ]
}

CSS copiable pour les tokens de theme

Dans var(--surface, #ffffff), le second argument est la valeur de secours. Si --surface est absent ou invalide, le navigateur utilise #ffffff. La reference MDN de var() est la source officielle pour cette syntaxe.

:root {
  color-scheme: light;

  /* Palette tokens: raw values */
  --blue-50: #eff6ff;
  --blue-400: #60a5fa;
  --blue-600: #2563eb;
  --blue-700: #1d4ed8;
  --slate-50: #f8fafc;
  --slate-100: #f1f5f9;
  --slate-300: #cbd5e1;
  --slate-700: #334155;
  --slate-900: #0f172a;
  --red-600: #dc2626;

  /* Semantic theme tokens: values used by the app */
  --surface: var(--slate-50);
  --surface-raised: #ffffff;
  --text: var(--slate-900);
  --text-muted: var(--slate-700);
  --border: var(--slate-300);
  --color-accent: var(--blue-600);
  --color-danger: var(--red-600);

  /* Typography and spacing */
  --font-body: Inter, "Noto Sans", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", Consolas, monospace;
  --step-0: 1rem;
  --step-1: 1.125rem;
  --step-2: 1.5rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
  --shadow-card: 0 12px 30px rgb(15 23 42 / 0.12);
}

[data-theme="dark"] {
  color-scheme: dark;
  --surface: var(--slate-900);
  --surface-raised: #111827;
  --text: var(--slate-50);
  --text-muted: var(--slate-300);
  --border: #334155;
  --color-accent: var(--blue-400);
  --shadow-card: 0 18px 42px rgb(0 0 0 / 0.35);
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    color-scheme: dark;
    --surface: var(--slate-900);
    --surface-raised: #111827;
    --text: var(--slate-50);
    --text-muted: var(--slate-300);
    --border: #334155;
    --color-accent: var(--blue-400);
  }
}

body {
  margin: 0;
  font-family: var(--font-body, system-ui, sans-serif);
  background: var(--surface, #ffffff);
  color: var(--text, #111827);
}

.pricing-card {
  --card-padding: var(--space-6);
  --card-border: var(--border);

  max-width: 34rem;
  margin: var(--space-6) auto;
  padding: var(--card-padding);
  background: var(--surface-raised, #ffffff);
  border: 1px solid var(--card-border, #d1d5db);
  border-radius: var(--radius-lg, 0.75rem);
  box-shadow: var(--shadow-card, none);
}

.pricing-card h2 {
  margin: 0 0 var(--space-2);
  font-size: var(--step-2, 1.5rem);
}

.pricing-card p {
  color: var(--text-muted, #4b5563);
  line-height: 1.75;
}

.button {
  --button-bg: var(--color-accent);
  --button-text: #ffffff;
  --button-border: transparent;

  display: inline-flex;
  align-items: center;
  justify-content: center;
  min-height: 2.75rem;
  padding: 0 var(--space-4);
  border: 1px solid var(--button-border);
  border-radius: var(--radius-md);
  background: var(--button-bg, #2563eb);
  color: var(--button-text, #ffffff);
  font-weight: 700;
  cursor: pointer;
}

.button[data-variant="secondary"] {
  --button-bg: transparent;
  --button-text: var(--color-accent);
  --button-border: var(--color-accent);
}

Demo HTML et JavaScript

Ce code fonctionne sans framework. data-theme stocke le choix manuel, tandis que prefers-color-scheme suit le systeme quand aucun choix n’existe.

<section class="pricing-card">
  <h2>Claude Code UI Token Demo</h2>
  <p>
    This card uses CSS custom properties for surface, text, border,
    shadow, and button colors.
  </p>
  <button class="button" type="button" data-theme-toggle>
    Toggle theme
  </button>
  <button class="button" type="button" data-variant="secondary">
    Secondary action
  </button>
  <label>
    Accent color
    <input type="color" value="#2563eb" data-accent-picker>
  </label>
</section>

const root = document.documentElement;
const themeKey = "claude-code-css-variable-theme";
const savedTheme = localStorage.getItem(themeKey);
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;

function applyTheme(theme) {
  root.setAttribute("data-theme", theme);
  localStorage.setItem(themeKey, theme);
}

function toggleTheme() {
  const current = root.getAttribute("data-theme") || "light";
  applyTheme(current === "dark" ? "light" : "dark");
}

function setAccentColor(color) {
  if (CSS.supports("color", color)) {
    root.style.setProperty("--color-accent", color);
  }
}

applyTheme(savedTheme || (prefersDark ? "dark" : "light"));

document.querySelector("[data-theme-toggle]")?.addEventListener("click", toggleTheme);
document.querySelector("[data-accent-picker]")?.addEventListener("input", (event) => {
  setAccentColor(event.target.value);
});

MDN documente prefers-color-scheme et color-scheme. Le premier detecte la preference utilisateur, le second aide le navigateur a choisir les couleurs natives des formulaires et barres de defilement.

Cas d’usage

Cas 1 : CTA d’articles et landing pages. Modifier --color-accent suffit pour tester une offre ou un lien Gumroad sans modifier chaque bouton.

Cas 2 : tableaux de bord SaaS. Les tokens partages gardent les surfaces, bordures, espacements et erreurs coherents entre plusieurs ecrans generes par Claude Code.

Cas 3 : marque blanche. [data-brand="client-a"] peut remplacer seulement les tokens semantiques, sans dupliquer les composants.

Cas 4 : accessibilite. Contraste fort, espacement plus large et typographie lisible deviennent des tokens revisables avec le guide accessibilite.

Pieges frequents

Evitez les var() sans valeur de secours sur les pages publiques. Preferez color: var(--text, #111827);.

Les noms de proprietes personnalisees sont sensibles a la casse. La reference MDN des custom properties le confirme; gardez des noms en minuscules avec tirets.

N’utilisez pas les variables CSS pour les selecteurs, noms de proprietes ou conditions de media query. Elles servent aux valeurs.

Validez les mises a jour JavaScript. Si une saisie utilisateur arrive dans setProperty(), controlez-la avec CSS.supports().

Revoyez les ombres et les bordures en mode sombre. Ne changer que le fond et le texte laisse souvent une interface inachevee.

CTA et verification

Demandez a Claude Code une revue dediee :

{
  "reviewTarget": "CSS custom properties and theme implementation",
  "checks": [
    "undefined custom properties without fallback",
    "light and dark contrast issues",
    "component variants that bypass tokens",
    "duplicated raw colors outside :root",
    "JavaScript setProperty calls without validation",
    "mobile overflow caused by fixed spacing tokens"
  ],
  "output": "List findings with file name, selector, risk, and suggested fix."
}

Pour la reference officielle, consultez la documentation Claude Code. Pour travailler plus vite, commencez par la cheatsheet gratuite, puis utilisez 50 Prompt Templates pour les revues repetables ou le Setup Guide pour standardiser CLAUDE.md, permissions, hooks et controles d’equipe.

Dans mes tests sur des cartes de CTA, la regle la plus rentable a ete de garder les couleurs brutes dans :root et de forcer les composants a consommer des tokens semantiques. Les changements de theme deviennent plus petits et les diffs de Claude Code plus faciles a relire.