tmj-90/design-system

Ein systematisches Design-System aufbauen

Der Skill brand entscheidet über die Identität; der Skill frontend-design entscheidet, wie eine Oberfläche aussieht. Dieses Paket entscheidet, wie dieses Aussehen strukturiert wird, damit es skaliert: eine dreischichtige Token-Architektur mit einer einzigen Quelle der Wahrheit, Komponenten-Spezifikationen, die jeden Zustand abdecken, und Prüfungen, die verhindern, dass Rohwerte wieder eindringen. Lade eine Referenz, wenn du Tiefe benötigst:

Thema	Referenz
Schichten, Benennung, Dark Mode, DTCG JSON, Migration von flachen Tokens	references/token-architecture.md
Varianten, Größen und Zustandsmatrizen für Button/Input/Card/Badge/Alert/Dialog/Table	references/component-specs.md
Zustandspriorität, Fokus-Ringe, Fehler/Lade-Muster, ARIA pro Zustand	references/states-and-variants.md

Die Architektur in einem Satz

/* PRIMITIV – Rohwerte, keine Bedeutung. Ändern sich selten. */
--blue-600: oklch(55% 0.2 264);
/* SEMANTISCH – Zweck. Die Theme-Naht: Light/Dark/Brand überschreiben nur diese Ebene. */
--color-primary: var(--blue-600);
/* KOMPONENTE – komponentenspezifische Stellschrauben, die auf semantische Tokens verweisen. */
--button-bg: var(--color-primary);

Komponenten konsumieren Komponenten- oder semantische Tokens – niemals ein primitives Token, niemals einen Literalwert. Themes (Dark, High Contrast, eine zweite Marke) zeigen semantische Tokens neu an und sonst nichts.

Quelle der Wahrheit. Wenn das Repository Tokens als W3C Design Tokens Community Group (DTCG) JSON speichert – das Format erreichte im Oktober 2025 seine erste stabile Version, 2025.10 – dann sind diese Dateien die Quelle: Tokens tragen $value und $type, Aliase werden als {color.blue.600} geschrieben, und ein Build-Tool (Style Dictionary oder das Äquivalent des Repos) generiert CSS-Variablen, Tailwind-Theme und native Werte. Bearbeite das JSON und generiere neu; bearbeite niemals generierte Ausgaben von Hand. Wenn das Repository nur CSS-Custom-Properties hat, sind diese die Quelle. Führe keine zweite Quelle ein.

Schritte

1. Lies, was existiert. search_lore nach Design-System-ADRs; finde Token-Dateien (*.tokens.json, tokens/, theme.ts, :root-Blöcke, Tailwind-Konfiguration), den Build-Befehl, der Ausgaben generiert, und zwei benachbarte Komponenten. Erweitere das bestehende System in dessen Idiom; füge niemals ein konkurrierendes hinzu.
2. Prüfe vor dem Hinzufügen. Zähle Literale in Komponenten-Stilen (Befehle unten). Jedes Leck, das du berührst, wird entweder durch ein vorhandenes Token ersetzt oder rechtfertigt ein neues.
3. Platziere jedes neue Token in seiner Schicht. Primitiv nur für einen wirklich neuen Rohwert; semantisch für einen neuen Zweck (--color-surface-raised, --space-section); Komponente nur, wenn eine einzelne Komponente abweichen muss. Namen beschreiben den Zweck, nicht das Aussehen (--color-danger, nicht --color-red). Farb-Primitive in oklch (Hausidiom), Typ in einer clamp()-Fluid-Skala, Abstände basierend auf einer Basiseinheit (4px oder 8px).
4. Theme an der semantischen Naht. Dark Mode und andere Themes überschreiben semantische Tokens in einem Block ([data-theme="dark"], .dark oder @media (prefers-color-scheme: dark), je nach Repository) und setzen color-scheme, damit native Steuerelemente und Scrollbalken folgen. Ein Theme, das ein primitives oder ein Komponenten-Token überschreibt, bedeutet, dass die Naht an der falschen Stelle ist.
5. Überprüfe den Kontrast pro Theme. Für jedes semantische Vordergrund-/Hintergrund-Paar, das tatsächlich verwendet wird (Text auf Oberfläche, Text auf Primär, Rand auf Oberfläche, Fokus-Ring auf Oberfläche), berechne das WCAG-Kontrastverhältnis in jedem Theme: 4,5:1 für Fließtext, 3:1 für großen Text, UI-Grenzen und Fokus-Indikatoren. Die oklch-Helligkeit ist nicht das WCAG-Verhältnis – berechne es (ein Skript, der Checker des Repos oder ein Test). Dokumentiere die Tabelle.
6. Komponenten vollständig spezifizieren. Varianten, Größen (explizite Höhe, Padding, Font-Token) und die Zustandsmatrix – Standard, Hover, Focus-visible, Active, Disabled, Loading, Error, plus Selected/Checked wo relevant – mit dem ARIA, das jeder Zustand bereitstellt. Priorität, wenn mehrere zutreffen: disabled > loading > error > active > focus > hover > default. Fokus ist immer sichtbar (:focus-visible-Ring über --color-ring, niemals outline: none allein). Details: die Referenzen.
7. Empfehlung eines Systems für ein neues Produkt: Begründe vom Produkt aus, nicht von einem Kit – (a) Muster und Dichte (Marketing, datendichtes Dashboard, transaktionaler Ablauf), (b) Richtung (delegiere an brand), (c) Palette-Posture (semantische Rollen inkl. Success/Warning/Danger/Info; Dark Mode nur, wenn Nutzer ihn benötigen), (d) Barrierefreiheits- und Leistungsziele klar vorab formuliert. Gib eine kurze Begründung sowie das Token- und Komponentengerüst aus; übergib die visuelle Umsetzung an frontend-design.
8. Überprüfen und belegen. Generiere Token-Ausgaben neu, wenn das Repository sie baut, und bestätige, dass das Diff nur das enthält, was du beabsichtigt hast; führe Lint, Typprüfung und Tests aus; führe die Leckprüfungen durch; rendere die geänderten Komponenten in jedem Theme mit den Komponenten- oder Screenshot-Tests des Repos, soweit vorhanden. Dokumentiere pro-AC Belege mit dem record-evidence-Skill (Leckanzahl vorher/nachher, Kontrasttabelle), dann halte an.

Leckprüfungen

Führe sie auf geänderten Komponenten- und Stildateien aus (Token-Dateien selbst ausschließen):

• Rohfarben: grep -rEn '#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(|oklch\(' src/components
• Roh-Schriftgrößen: grep -rEn 'font-size:\s*[0-9.]+px' src/components
• Primitive aus Komponenten referenziert: grep -rEn 'var\(--(gray|blue|red|green)-[0-9]+' src/components
• Tailwind-Arbitrary-Werte, wo Tokens existieren: grep -rEn '\[(#|[0-9]+px)' src/components

Passe Pfade und primitive Namen an das Repository an. Neue Treffer in deinem Diff sind Fehler, die der Builder beheben muss, es sei denn, die Zeile ist selbst eine Token-Definition; ein Reviewer listet sie als (optional), es sei denn, eine bricht eine AC oder den Kontrast eines Themes.

Fertig, wenn

Keine neuen Literale oder primitiven Referenzen in Komponenten; jedes Theme überschreibt nur semantische Tokens; die Kontrasttabelle besteht in jedem Theme; die Zustandsmatrix jeder berührten Komponente ist mit sichtbarem Fokus implementiert; generierte Ausgaben stimmen mit der Quelle überein.

Wissen festhalten

Die Token-Architektur eines Repos – die Schichtenaufteilung, die Benennungskonvention, die Dark-Mode-Naht oder eine Regel wie "niemals ein primitives Token in einer Komponente referenzieren" – ist genau die Tatsache, die der nächste Agent benötigt, bevor er beginnt. Diese Art von Tatsache ist Wissen. Halte sie fest über das Lore-Capture-Protokoll in deinem Briefing (CLAUDE.factory.md, Schritt 11 "Memory contribution"): Rufe den Memory MCP suggest_lore einmal am Ende deiner Arbeit auf – nur wiederverwendbare Konventionen, Fallstricke, Entscheidungen und Grenzen, niemals auftragsbezogene Kleinigkeiten.