Mitwirken am Design-System
Gilt für packages/design/ und die Bausteine in apps/web/components/. Das Projekt arbeitet spec-getrieben (siehe CLAUDE.md): Nichts wird umgesetzt, das nicht als Spec freigegeben ist.
Leitplanken (nicht neu verhandeln)
- Datensparsamkeit: Kinder nur als „Vorname + abgekürzter Nachname“, keine Fotos von Kindern, in Beispielen nur erfundene Daten.
- Zweisprachig: Deutsch und Englisch, immer beide Dateien ändern.
- Barrierefrei: WCAG 2.2 AA, Kontrast 4,5:1 (Text) und 3:1 (UI), sichtbarer Fokus, Ziele ab 24 px (Touch 44 px), alles per Tastatur.
- Ohne JavaScript benutzbar: Server Components,
<form>-POST,<details>statt Skript-Dialogen. Client-JS nur als Verbesserung, nie als Voraussetzung. - Selbst gehostet: Keine CDN-Schriften, keine fremden Skripte, keine Tracker, keine Abhängigkeit von externen Diensten zur Laufzeit.
- Keine Änderung an Geschäftslogik, API oder Datenmodell im Namen des Designs. Fehlt etwas in der API, kommt eine eigene Spec.
Aufbau
| Ordner | Inhalt |
|---|---|
tokens/ | tokens.json (Quelle aller Werte), Build, Kontrast-Gate, Mandanten-Akzent |
src/ | base.css (semantisches HTML), components.css, print.css, icons.svg, Schriften |
styleguide/ | Komponentenreferenz und Styleguide-Seiten |
emails/, documents/, site/ | E-Mail-Vorlagen, Dokumentvorlagen, Marketing-Seite |
test/ | Paket-Tests, Browser-Tests, Bildvergleich, Mock-API |
docs/ | Entscheidungen (ADR), Microcopy, dieser Leitfaden, Changelog |
brand/ | Bildzeichen und Markenpaket (unverändert übernommen) |
Ablauf einer Änderung
- Spec zuerst. Neue Funktion oder neues Verhalten: Requirements → Design → Tasks (Slash-Commands
/spec-requirements,/spec-design,/spec-tasks). Kleine Korrekturen am bestehenden Verhalten brauchen keine neue Spec, aber einen Eintrag im Changelog. - Wert ändern? Nur in
tokens/tokens.json, dannnpm run build -w @klasu/design. Nie Werte in CSS kopieren. Der Token-Lint (npm test) meldet feste Farben, Dauern und große Pixelwerte. - Komponente bauen:
- Klassen nach dem Muster .teil, .teil__bestandteil, .teil-variante (z. B. .btn, .card__header, .btn-danger). Zustände über Attribute (aria-pressed, aria-current, aria-invalid), nicht über eigene Klassen. - Größen und Umbrüche über Container Queries (@container), nicht über Fenster-Breiten. - In React: Server Component, Variante als Prop (variant, tone), Teile als Slots (Card.Header), keine Ansammlung von Boolean-Props. - Jede Komponente braucht alle Zustände (Ruhe, Hover, Fokus, Aktiv, Deaktiviert, Laden, Fehler, Leer) und gehört in styleguide/components.src.html.
- Texte: In
apps/web/lib/messages/de.jsonunden.json. Regeln sieheMICROCOPY.md. - Tests lokal ``
bash npm run build -w @klasu/design npm test -w @klasu/design # Kontrast, Token-Lint, Akzent, keine externen Adressen, E-Mail-Vorlagen npm run build -w @klasu/web && npm test -w @klasu/web npm run test:app -w @klasu/design # axe, Überlauf, ohne JS, Tastatur, Bildvergleich, Schriftwechsel`` - Bildvergleich bewusst ändern: Läuft er rot und die Änderung ist gewollt, die Diff-Bilder in
packages/design/reports/visual-diff/ansehen und erst dannnpm run test:visual:update -w @klasu/designausführen. Neue Referenzbilder gehören mit in den Commit und in die Beschreibung („was sieht anders aus und warum“). - Manuelles: Was Automatik nicht prüft, steht in
specs/design-system/phase-6/manual-checklist.md. Bei Änderungen an Navigation, Fokus oder Kalender die betroffenen Punkte durchgehen. - Changelog: Eintrag unter „Unveröffentlicht“ in
docs/CHANGELOG.md. Bei einer Entscheidung mit Alternativen zusätzlich ein ADR indocs/ENTSCHEIDUNGEN.md.
Mandantenfarbe
Eine Mandantenfarbe geht nur über tenantAccentCss (@klasu/design/accent). Es hält die Kontraste in beiden Themes ein und liefert null, wenn das nicht gelingt. Gelb ist gesperrt (reserviert für „Neu“).
Was nie in den Commit gehört
Echte Namen oder Daten von Kindern, Zugangsdaten, .env, gebaute Ordner (dist/), Schriftdateien aus fremden Quellen ohne Lizenztext.
Commit-Stil
Kurze deutsche Betreffzeile mit Bereich („Design-System: …“), eine Änderung pro Commit.