CP Registry

Contributing

Wie du neue Components erstellst, bestehende verbesserst und zum System beitraegst.

Workflow

1. Registry klonen & CLI installieren

git clone git@github.com:andrenagusch/cp-registry.git
cd cp-registry
pnpm install          # Projekt-Dependencies
./cli/setup.sh        # CLI global installieren

2. Dev-Server starten

pnpm dev

Oeffnet die Showcase-Website auf localhost:4321.

3. Component erstellen

Am schnellsten per CLI-Scaffolding oder Claude Code Agent:

# CLI-Scaffolding (erstellt Boilerplate)
cp-components new Timeline -c content --with-script

# Oder: Claude Code Agent (erstellt fertigen Component)
# → der cp-component-builder Agent wird automatisch genutzt

Mindestens drei Dateien sind nötig:

  1. src/components/{Name}/{Name}.astro — Template + Props
  2. src/components/{Name}/{name}.css — Styles (bei komplexen Components)
  3. src/components/{Name}/{name}.ts — Client-Side Logik (bei interaktiven Components)
  4. registry/components/{name}.json — Manifest (alle Dateien auflisten!)
  5. src/pages/components/{name}.astro — Showcase-Seite

4. Tests schreiben

# Test erstellen
tests/{component-name}.test.ts

# Tests laufen lassen
pnpm test

5. Sidebar aktualisieren

Neuen Eintrag in src/layouts/Layout.astro → navSections hinzufügen.

Component-Checkliste

  • ☐ Nur semantische Tokens nutzen (bg-brand-*, text-brand-*)
  • ☐ Korrektes semantisches HTML (<article>, <nav>, <section> etc.)
  • ☐ Keyboard-Navigation funktioniert (Tab, Enter, Space, Escape, Pfeiltasten)
  • ☐ ARIA-Attribute gesetzt (role, aria-expanded, aria-label etc.)
  • ☐ :focus-visible Ring sichtbar
  • ☐ prefers-reduced-motion respektiert
  • ☐ Responsive: funktioniert von 320px bis ultra-wide
  • ☐ Cross-Browser: Safari, Chrome, Firefox getestet
  • ☐ TypeScript Props-Interface mit JSDoc
  • ☐ Showcase-Seite mit allen Varianten und Props-Tabelle
  • ☐ Registry Manifest vollständig (files, dependencies, requiredTokens)
  • ☐ Sidebar-Navigation aktualisiert

Code-Konventionen

Astro Components

  • PascalCase für Dateinamen: Button.astro
  • Props-Interface mit TypeScript
  • JSDoc-Kommentar mit @example
  • Einfache Components: Tailwind direkt im Markup
  • Komplexe Components: Styles in {name}.css auslagern, Logik in {name}.ts
  • class-Prop für Custom-Styling

Client-Side Scripts

  • TypeScript, kein vanilla JS
  • A11y-Utilities importieren (nicht duplizieren)
  • Separate .ts-Datei, eingebunden via <script>import './name.ts';</script>
  • Event Delegation wo sinnvoll
  • Cleanup bei dynamischen Inhalten

Mit Claude Code entwickeln

Das Registry bringt spezialisierte Agents mit die bei der Component-Entwicklung helfen:

cp-component-builder Agent

Erstellt komplette Components: Astro-Datei, Manifest, Showcase-Seite, Sidebar-Eintrag. Kennt alle Konventionen.

cp-showcase-generator Agent

Generiert Showcase-Seiten mit CodePreview. Liest Props, erstellt realistische Beispiele.

cp-manifest-validator Agent

Validiert alle Manifeste: Pflichtfelder, Datei-Existenz, Token-Naming, Dependencies.

a11y-auditor Agent (universell)

WCAG 2.2 AA Audit. Prüft HTML-Semantik, ARIA, Keyboard, Kontraste. Funktioniert mit jedem Framework.

Mehr dazu: Claude Code Skills & Agents

Manifest-Schema

{
  "name": "ComponentName",           // PascalCase
  "category": "content",             // content | layout | ui | form | overlay | animation
  "description": "Kurze Beschreibung",
  "files": [                         // Alle Dateien die kopiert werden
    "src/components/Name/Name.astro",
    "src/components/Name/name.css",
    "src/components/Name/name.ts"
  ],
  "dependencies": {
    "components": [],                // Andere Components (z.B. ["popover"])
    "npm": []                        // npm-Pakete (z.B. ["swiper"])
  },
  "requiredTokens": [                // Welche Farb-Tokens gebraucht werden
    "--color-brand-primary",
    "--color-brand-border"
  ],
  "types": [],                       // TypeScript-Definitionen
  "globalsImports": []               // CSS-Imports für globals.css
}