CSS-Variablen mit Claude Code: praktische Theme Tokens

CSS-Variablen machen Design-Entscheidungen wartbar

CSS-Variablen heißen offiziell CSS Custom Properties. Du definierst Werte wie --color-accent und nutzt sie später mit var(--color-accent). Einfach gesagt sind sie benannte Ablageorte für Farben, Abstände, Radien, Schatten, Schriftgrößen und Zustände.

Gerade mit Claude Code ist diese Grenze nützlich. Eine vage Bitte wie “baue eine schöne Karte” kann hart codierte Farben in vielen Selektoren erzeugen. Wenn du zuerst Theme Tokens verlangst, bekommt Claude Code ein stabiles Vokabular. Dark Mode, CTA-Farbtest oder White-Label-Branding werden dann zu Token-Änderungen statt zu riskanten Suchen im ganzen Stylesheet.

Ergänzend passen der Guide zur Dark-Mode-Implementierung, der Design-System-Guide und die Flexbox-Patterns. Das Modell: Palette Tokens enthalten Rohwerte, semantische Tokens beschreiben Produktbedeutung, Komponenten-Tokens passen ein UI-Element an, Status-Tokens überschreiben Werte für dark, danger, compact oder Marken.

Claude Code zuerst nach Tokens fragen

Dieser Prompt verhindert, dass Claude Code einmalige Werte über das CSS verteilt.

{
  "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 zum Kopieren

Der zweite Wert in var(--surface, #ffffff) ist der Fallback. Wenn --surface fehlt oder ungültig ist, nutzt der Browser #ffffff. Die offizielle MDN-Referenz zu var() erklärt diese Auflösung.

: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);
}

HTML- und JavaScript-Demo

Das Beispiel läuft ohne Framework. data-theme speichert die manuelle Wahl, prefers-color-scheme übernimmt die Systemeinstellung, wenn noch keine Wahl existiert.

<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 dokumentiert prefers-color-scheme und color-scheme. Ersteres erkennt die Nutzervorliebe, letzteres hilft dem Browser bei nativen Formular- und Scrollbar-Farben.

Praktische Einsatzfälle

Einsatzfall 1: Artikel-CTAs und Landingpages. --color-accent kann eine Kampagne, ein Gumroad-Angebot oder einen Hauptbutton ändern, ohne jeden Selektor anzufassen.

Einsatzfall 2: SaaS-Dashboards. Gemeinsame Tokens halten Flächen, Rahmen, Abstände und Fehlerzustände konsistent, auch wenn Claude Code mehrere Screens getrennt generiert.

Einsatzfall 3: White-Label-Branding. Mit [data-brand="client-a"] überschreibst du nur semantische Tokens und duplizierst keine Komponenten.

Einsatzfall 4: Barrierefreiheit. Höherer Kontrast, größere Abstände und lesbare Schriftgrößen können als Tokens beschrieben und mit dem Accessibility Guide geprüft werden.

Typische Fallen

Vermeide var() ohne Fallback auf öffentlichen Seiten. Besser ist color: var(--text, #111827);.

Custom-Property-Namen sind case-sensitive. Die MDN-Referenz zu Custom Properties bestätigt das; nutze Kleinschreibung und Bindestriche.

Nutze CSS-Variablen nicht für Selektoren, Property-Namen oder Media-Query-Bedingungen. Sie sind für Werte gedacht.

Validiere JavaScript-Updates. Wenn Nutzereingaben in setProperty() landen, prüfe sie mit CSS.supports().

Prüfe im Dark Mode auch Schatten und Rahmen. Nur Hintergrund und Text zu ändern wirkt schnell unfertig.

CTA und Review

Lass Claude Code die Token-Schicht gezielt prüfen:

{
  "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."
}

Die offizielle Grundlage findest du in der Claude Code Dokumentation. Für die tägliche Arbeit nutze die kostenlose Cheatsheet, für wiederverwendbare Review- und Implementierungs-Prompts die 50 Prompt Templates, und für Team-Setup mit CLAUDE.md, Permissions und Hooks den Setup Guide.

Im Praxistest mit CTA-Karten war die wichtigste Regel: Rohfarben bleiben in :root, Komponenten nutzen semantische Tokens. Dadurch wurden Theme-Änderungen kleiner und Claude-Code-Diffs leichter prüfbar.