Tooling

Wie du das Brand Kit einsetzt — visuell oder per Agent

Was ist ein Brand Kit? Ein Paket mit allen Design-Entscheidungen (Farben, Schriften, Abstaende, Komponenten-Regeln) in maschinenlesbarer Form. Statt Hex-Werte zu kopieren, nutzt du Tokens die sich automatisch anpassen — auch fuer Dark Mode. Das Brand Kit funktioniert mit Tailwind, reinem CSS oder direkt ueber AI-Tools.

Drei Wege zum Brand Kit

Das Brand Kit richtet sich an Designer, Entwickler und LLM-Agents. Waehle den Einstieg der zu deinem Workflow passt.

WEG A

Visuell nachschlagen

Spec-Seiten im Browser durchgehen, Live-Demos ausprobieren, Token-Tabellen lesen. Kein Setup noetig.

→ Farben → Typografie → Buttons

WEG B

AI-Tool

Die /for-ai Seite buendelt alle Guidelines, Tokens und Constraints auf einer URL. Teile sie mit ChatGPT, Claude, v0 oder Cursor.

→ URL teilen, fertig

WEG C

Developer-Integration

npm-Paket installieren, Tailwind Preset einbinden, CLAUDE.md-Fragment ins Repo kopieren. Der Agent arbeitet gegen die Tokens.

→ npm install + CLAUDE.md

Agent-Integration einrichten

Schnellstart

Kopiere diesen Prompt in die erste Nachricht einer neuen Claude Code Session. Er installiert das Paket, liest das Fragment und bettet es in die CLAUDE.md ein.

Startprompt für neue Session

Installiere @panoptia/coffee-elements-brand-kit und lies node_modules/@panoptia/coffee-elements-brand-kit/guidelines/Guidelines.md. Bette den Inhalt der setup.md in die CLAUDE.md dieses Projekts ein. Lies dann design-tokens.css und die guidelines/ Dateien aus demselben Paket, bevor du irgendetwas implementierst.

npm-Paket installieren

Bringt alle Design-Dateien ins Consumer-Repo: Tokens, Kompositionsregeln, CLAUDE.md-Fragment. Versioniert via npm — Updates per npm update.

Im Consumer-Repo

npm install @panoptia/coffee-elements-brand-kit

Inhalt des Pakets

design-tokens.css

Alle --ce-* Token-Werte: Farben (aufgelöste Hex-Werte), Fonts, Spacing, Shadows. LLM-optimiert mit Usage-Kommentaren.

guidelines/

Figma Make Format: Foundations (Farben, Typografie, Spacing, Modes), Composition (Hierarchie, Layout, Surfaces), Components (Entscheidungslogik).

tailwind/preset.js

Tailwind Preset: Theme Extension (Farben, Fonts, Spacing, Shadows) + Component-Klassen mit ce-* Prefix. Dark Mode via .dark Klasse.

tailwind/preset-tokens-only.js

Tailwind Preset ohne Component-Klassen. Fuer Consumer mit eigener CSS-Datei (z.B. Shopify Themes).

tailwind/preset-shopify.js

SHOPIFY

Shopify-spezifisches Preset mit Breakpoints 750/1000/1200px statt Tailwind-Defaults.

css/components.css

Compiled CSS mit allen ce-* Klassen und Dark Mode. Fuer Projekte ohne Tailwind — einfach importieren.

components/*.md

17 Komponenten-Spezifikationen: Varianten, exakte Werte, Dark Mode, Responsive, Tailwind-Beispiele, Compiled CSS.

font-integration.md

Font-Einbindung: Pressura, Pressura Mono, Inter. Lokale Dateien, CDN-Fallbacks, @font-face Snippets.

guidelines/setup.md

Consumer-Setup: npm install, Tailwind Preset, CSS Import, Shopify-Konfiguration, Claude Code Integration.

design-system.json

OPTIONAL

Dieselben Tokens als JSON. Für programmatische Tools, Linting, Validierung. Nicht nötig für die LLM-basierte Arbeit.

CLAUDE.md-Fragment einfügen

Das Fragment sagt dem Agent, wo die Tokens liegen und welche Regeln gelten. Kopiere es in die CLAUDE.md deines Repos — oder nutze den Startprompt oben.

CLAUDE.md Fragment

## Coffee Elements — Brand Kit Integration

> **WICHTIG: Dieses Dokument ist die einzige Quelle fuer Design-Regeln in diesem Projekt.
> Erfinde KEINE eigenen Design-Regeln, Farben, Fonts, Spacing-Werte oder Komponenten-Patterns.
> Alles steht in den Brand Kit Dateien. Was dort nicht steht, existiert nicht.**

### Was ist das Brand Kit?

Ein npm-Paket mit allen Design-Entscheidungen fuer Coffee Elements: Farben, Schriften, Abstaende, Komponenten-Regeln. Statt Hex-Werte oder Pixel zu kopieren, nutzt du semantische Tokens (`--ce-surface-card` statt `#FFFFFF`) die sich automatisch anpassen — auch fuer Dark Mode.

### Setup

\`\`\`bash
npm install @panoptia/coffee-elements-brand-kit
\`\`\`

\`\`\`js
// tailwind.config.js
module.exports = {
  presets: [require('@panoptia/coffee-elements-brand-kit/tailwind/preset')],
  content: ['./src/**/*.{html,js,tsx,liquid}']
}
\`\`\`

Shopify: `preset-shopify` statt `preset` (Breakpoints 750/1000/1200px).
Ohne Tailwind: `@import '@panoptia/coffee-elements-brand-kit/css/components.css';`

### Vor jeder Implementierung lesen

Lies die Dateien in dieser Reihenfolge:

1. `guidelines/Guidelines.md` — Design-Philosophie, Paketinhalt, Core Rules
2. `guidelines/setup.md` — Tailwind/CSS/Shopify Setup
3. `guidelines/foundations/color.md` — Semantische Tokens, Entscheidungsbaum
4. `guidelines/foundations/typography.md` — Drei Fonts, drei Rollen, Scale
5. `guidelines/foundations/spacing.md` — 4px Grid, Stufen
6. `guidelines/foundations/modes.md` — Dark Mode, Breakpoints
7. `guidelines/composition/hierarchy.md` — Visuelles Gewicht
8. `guidelines/composition/layout.md` — Container, Padding, Grid
9. `guidelines/composition/surfaces.md` — FLAT vs BENTO, Shadows
10. `guidelines/components/overview.md` — Katalog, CSS vs JS
11. `guidelines/components/*.md` — Entscheidungslogik pro Komponente
12. `design-tokens.css` — Aufgeloeste Token-Werte (SSOT)
13. `components/*.md` — Implementierungs-Specs mit exakten CSS-Werten

Nichts davon aus dem Gedaechtnis rekonstruieren.

### Critical Rules

1. **Nur semantische Tokens** — `--ce-surface-card` nicht `#FFFFFF`. Nie Palette-Werte direkt.
2. **Font-Zuordnung ist strikt** — Pressura (Headings/Nav), Pressura Mono (Buttons/Labels/Preise), Inter (Body). Keine Ausnahmen.
3. **Fehlende Werte = nachfragen** — `TODO: VERIFY` Kommentar setzen, nie einen plausiblen Wert erfinden.
4. **Dark Mode = Token-Swap** — `.dark` Klasse auf `<html>`, keine strukturellen Aenderungen.
5. **Icons nur Remixicon** — Keine eigenen SVG-Pfade.
6. **4px Spacing Grid** — Nie 5, 7, 10, 15, 18px. Immer Grid-Stufen.
7. **Guidelines beachten** — `guidelines/` definiert alle Guardrails.

### Updates

\`\`\`bash
npm outdated @panoptia/coffee-elements-brand-kit  # Neue Version pruefen
npm update @panoptia/coffee-elements-brand-kit     # Update installieren
\`\`\`

Warum eine eigene Token-Datei

Die globals.css enthält alle Tokens in Tailwind-v4-Syntax — @theme-Blöcke, var()-Ketten, verteilte Patterns. Für Build-Tools kein Problem. Für LLM-Agents schon.

Das Problem

Wenn --ce-surface-card auf var(--ce-zinc-50) verweist, das auf #FBFBFC — muss der Agent die Kette manuell auflösen. Bei 30+ Tokens und Dark-Mode-Swaps entstehen systematisch Fehler.

Die Lösung

design-tokens.css enthält dieselben Tokens — aber aufgelöst, kommentiert und mit Komponenten-Patterns als Inline-Dokumentation. Eine Datei, alle Entscheidungen.