# System Skills

Verbindliche Regeln für die KI-gestützte Website-Generierung im Agentur-Kontext.

---

## Scope

Diese Datei definiert den **harten Rahmen** für:
- Arbeitsweise und Workflow
- Code-Qualität und Repo-Konventionen
- Source of Truth für Design und Anforderungen
- Verbote und Pflichten

**Geltungsbereich:** Gilt global für jedes Projekt. CLIENT_OVERRIDES.md darf diese Regeln präzisieren oder erweitern, aber niemals widersprechen.

---

## Read Order

Die KI muss Dateien in folgender Reihenfolge lesen:

1. `skills/SYSTEM_SKILLS.md` (diese Datei)
2. `skills/UI_GUIDELINES.md`
3. `skills/DEFINITION_OF_DONE.md`
4. `skills/CLIENT_OVERRIDES.md` (falls vorhanden)
5. `spec/ProjectSpec.json`
6. `spec/design_tokens.json`
7. `theme/stylesheet.css` / `theme/globals.css`

Bei Konflikten gilt: **Globale Skills > Client Overrides**

---

## Non-Goals

Diese Datei definiert **NICHT**:
- Konkrete Design-Vorgaben (Farben, Layouts, Abstände)
- UI-Templates oder vorgefertigte Komponenten
- Visuelle Entscheidungen jeglicher Art
- Landingpage-Strukturen oder Section-Vorlagen

Design entsteht ausschließlich aus den Projekt-Specs, nicht aus diesen Skills.

---

## Source of Truth

Das Design und die Anforderungen einer Website basieren ausschließlich auf:

| Quelle | Inhalt |
|--------|--------|
| `spec/ProjectSpec.json` | Projektanforderungen, Ziele, Inhalte |
| `spec/design_tokens.json` | Farben, Typografie, Spacing-System |
| `theme/stylesheet.css` | Projektspezifische Styles |
| `theme/globals.css` | Globale CSS-Variablen und Resets |

**Regel:** Keine Design-Entscheidung ohne Grundlage in diesen Quellen.

---

## Verbote

### Absolut verboten:
- **KEINE** Templates oder vorgefertigten Layouts
- **KEINE** Copy-Paste-Strukturen aus anderen Projekten
- **KEINE** Boilerplate-Landingpages
- **KEINE** Standard-Hero/Feature/CTA-Sections ohne Spec-Grundlage
- **KEINE** eigenmächtigen Design-Entscheidungen
- **KEINE** hardcodierten Farben, Größen oder Abstände
- **KEINE** UI-Libraries (shadcn, MUI, Chakra, Radix, etc.)
- **KEINE** CSS-Frameworks außer Tailwind (falls im Projekt konfiguriert)
- **KEINE** inline Styles (außer dynamische Werte)
- **KEINE** `!important` (außer dokumentierte Ausnahmen)
- **KEINE** Secrets im Repository (nur .env, .env.local)

### Daten und Secrets:
- Sensible Daten gehören in `.env` / `.env.local`
- `.env*` Dateien sind in `.gitignore`
- API-Keys, Passwörter, Tokens niemals committen

---

## Arbeitsprozess

Jede Aufgabe folgt diesem Ablauf:

### 1. Lesen
- `/skills` vollständig lesen
- `/spec` vollständig lesen
- Bestehenden Code verstehen

### 2. Planen
- Anforderungen analysieren
- Struktur und Komponenten konzipieren
- Abhängigkeiten identifizieren

### 3. Implementieren
- Code schreiben
- Design-Tokens verwenden
- Keine eigenmächtigen Entscheidungen

### 4. Self-Check
- `npm run build` ausführen
- Gegen Definition of Done validieren
- Responsive und Accessibility prüfen

### 5. Dokumentieren
- Änderungen in `generation_log.json` maschinell festhalten
- Keine manuellen Einträge im Log

---

## Coding-Standards

### TypeScript

- **Strict Mode** ist Pflicht
- Keine `any` Types
- Explizite Typdefinitionen für Props und State
- Keine Type-Assertions ohne Notwendigkeit
- Strict null checks beachten

```typescript
// Korrekt
interface ComponentProps {
  title: string;
  items: ReadonlyArray<Item>;
  onSelect?: (item: Item) => void;
}

// Falsch
const props: any = { ... }
```

### React / Next.js

- Funktionale Komponenten
- Server Components wo möglich
- Client Components nur wenn nötig (`"use client"`)
- Keine unnötigen `useEffect` / `useState`
- Keine Over-Abstraktionen

### CSS

- CSS-Variablen aus `globals.css` verwenden
- Tailwind für Utility-Klassen (falls konfiguriert)
- Eigene Klassen für wiederverwendbare Patterns
- Mobile-first Breakpoints

```css
.element {
  color: var(--color-foreground);
  padding: var(--spacing-md);
}
```

### Allgemein

- Lesbarkeit > Cleverness
- Keine unnötigen Abstraktionen
- Keine Over-Engineering
- Konsistente Namenskonventionen
- Keine auskommentierten Code-Blöcke
- Keine `console.log` im Production-Code

---

## Pflichten

### Performance

- Core Web Vitals optimieren
- Lazy Loading für Below-the-fold-Inhalte
- Kritisches CSS inline
- JavaScript-Bundle minimieren
- Fonts optimieren (`display: swap`)
- Bildformate: WebP/AVIF bevorzugen
- Keine unnötigen Dependencies

### SEO

- Semantisches HTML (`header`, `main`, `nav`, `article`, `section`, `footer`)
- Korrekte Heading-Hierarchie (`h1` > `h2` > `h3`)
- Meta-Tags (`title`, `description`)
- Open Graph Tags
- Alt-Texte für alle Bilder
- Strukturierte Daten wo sinnvoll

### Mobile-First

- Responsive Design ist Pflicht
- Touch-Targets mindestens 44x44px
- Keine horizontalen Scrollbars
- Lesbare Schriftgrößen ohne Zoom

---

## Logging

### generation_log.json

- Nur maschinell befüllen
- Keine manuellen Einträge
- Dokumentiert: was wurde generiert, wann, welche Dateien
- Dient der Nachvollziehbarkeit

---

## Zusammenfassung

> Jede Website ist einzigartig. Design kommt aus den Specs, nicht aus dem Bauch.
> Code ist sauber, typisiert und wartbar. Build muss laufen.
> Diese Regeln sind nicht verhandelbar.