# 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.

---

## Parameter-Interpreter-Modus

Das System arbeitet mit **9 strukturierten Parameter-Kategorien (A–J)**. Diese Kategorien sind in `CLIENT_OVERRIDES.md` und `master_prompt.md` vollständig aufbereitet.

### Die 9 Kategorien

| Kat. | Name | Beschreibung |
|------|------|--------------|
| A | Unternehmensidentität & Kontext | Name, Slug, Beschreibung, Branche, Standort, Einzugsgebiet, Unternehmensgröße, Reifegrad, Locale, Kontaktdaten |
| B | Zielgruppe & Psychografie | Hauptzielgruppe, Altersbereich, Geschlecht, Entscheidertyp, Wissensstand, typische Einwände, Hauptprobleme |
| C | Tonalität & Kommunikation | Ansprache (Du/Sie), Basis-Tonalität, Schreibstil, emotionales Gefühl |
| D | Angebot & Leistungsstruktur | Angebotstyp, Leistungen mit Titel/Beschreibung/Nutzen, Preissensitivität, Upsells |
| E | Seitenarchitektur | Website-Typ (Onepager/Multipage), Seiten mit Slug/Titel/Beschreibung/Zweck/Priorität/Sections |
| F | Marken- & Stilparameter | Farben (12 Token), Fonts, Logo, Stil-Adjektive (max 5), Stil-Verbote |
| G | UX & Interaktion | Interaktionsniveau, Animationen, Scroll-Verhalten |
| H | Vertrauen & Conversion | Primärer & Sekundärer CTA, Kontaktmethoden, Vertrauenselemente |
| I | Technik & Recht | Domain, Hosting, Tracking, Legal-Daten, Features, Integrationen |
| J | KI-Kontext | Freitext: Was ist BESONDERS WICHTIG, was darf AUF KEINEN FALL passieren, Referenzen |

### Arbeitsweise

- Jede Kategorie enthält fertig aufbereitete Parameter
- **Keine Interpretation nötig** — die Parameter werden 1:1 umgesetzt
- Bei fehlenden Parametern: Sinnvolle Defaults verwenden, aber dokumentieren

---

## KI-Kontext Gewichtungshierarchie

Die Priorität bei Konflikten folgt dieser Hierarchie (höchste zuerst):

```
1. SYSTEM_SKILLS.md
2. UI_GUIDELINES.md
3. DEFINITION_OF_DONE.md
4. KI-KONTEXT (Kategorie J)
5. CLIENT_OVERRIDES (Kategorien A–I)
```

### Spezielle Regeln für Kategorie J

- **Kategorie J hat die höchste Gewichtung innerhalb der Client-Parameter**
- Bei Konflikten zwischen Kat. J und Kat. A–I: **Kat. J gewinnt**
- Bei Konflikten zwischen Kat. J und SYSTEM_SKILLS/UI_GUIDELINES: **Skills gewinnen**
- `whatIsImportant` aus Kat. J muss in **JEDER Designentscheidung** berücksichtigt werden
- `whatToAvoid` aus Kat. J sind **harte Verbote** — keine Ausnahmen

### Beispiel

Wenn Kat. J sagt "Keine Animationen" und Kat. G sagt "Interaktionsniveau: dynamisch", dann gilt: **Keine Animationen**.

---

## Seiten-Zweck-System

Jede Seite in Kat. E hat einen definierten `purpose` und eine `priority`.

### Purpose-Typen

| Purpose | Beschreibung | Content-Strategie |
|---------|--------------|-------------------|
| `informieren` | Fakten vermitteln | Fakten zuerst, klare Struktur, erklärende Sprache, CTAs dezent |
| `ueberzeugen` | Überzeugungsarbeit leisten | USPs hervorheben, Social Proof, emotionale + rationale Argumentation |
| `konvertieren` | Zur Handlung bewegen | Prominente CTAs, Einwände adressieren, Trust-Elemente, Urgency |

### Priority-Levels

| Priority | Beschreibung |
|----------|--------------|
| `hoch` | Maximaler Detailgrad, höchste Aufmerksamkeit bei der Implementierung |
| `mittel` | Solide Umsetzung mit allen wesentlichen Elementen |
| `niedrig` | Basis-Umsetzung, funktional aber ohne Extras |

### Umsetzung

- **Informieren:** H2-Struktur für Scanability, Inhaltsverzeichnis bei langen Seiten, CTAs am Ende von Sektionen
- **Überzeugen:** Problem → Lösung → Beweis → CTA Flow, USP-Cards/Feature-Grid, Social Proof prominent
- **Konvertieren:** Above-the-fold CTA, Trust-Section direkt unter Hero, Einwand-Entkräftung vor Kontaktformular

---

## Kommunikations-Parameter

Die Kommunikation wird durch Kategorie C definiert und muss **konsistent auf ALLEN Seiten** umgesetzt werden.

### Ansprache (address)

| Wert | Verwendung | Beispiel |
|------|------------|----------|
| `du` | Informelle Ansprache | "Schick uns eine Nachricht", "Dein Name" |
| `sie` | Formelle Ansprache | "Senden Sie uns eine Nachricht", "Ihr Name" |

**Pflicht:** Die gewählte Ansprache gilt für:
- Alle Fließtexte
- Alle Button-Labels
- Alle Formular-Labels und Placeholders
- Alle Microcopy-Elemente
- Alle CTAs

### Tonalität (baseTone)

| Wert | Beschreibung |
|------|--------------|
| `sachlich` | Neutral, faktenbasiert, nüchtern |
| `freundlich` | Warm, einladend, zugänglich |
| `beratend` | Kompetent, hilfsbereit, lösungsorientiert |
| `motivierend` | Energetisch, inspirierend, aktivierend |
| `exklusiv` | Premium, distinguiert, hochwertig |

### Schreibstil (writingStyle)

| Wert | Beschreibung |
|------|--------------|
| `kurz_praegnant` | Kurze Sätze, auf den Punkt, keine Füllwörter |
| `erklaerend` | Ausführlicher, didaktisch, schrittweise |
| `emotional` | Gefühlsbetont, storytelling, persönlich |
| `technisch` | Fachsprachlich, präzise, detailliert |

### Emotionales Gefühl (emotionalFeeling)

Beschreibt das gewünschte Gesamtgefühl der Website (z.B. "vertrauenswürdig und modern", "dynamisch und innovativ"). Muss sich im Gesamtdesign widerspiegeln.

---

## Vertrauens- & Conversion-Elemente

Kategorie H definiert, wie Vertrauen aufgebaut und Conversions erzielt werden.

### Vertrauenselemente (trustElements)

| Element | Implementierung |
|---------|-----------------|
| `bewertungen` | Google/Trustpilot-Widgets oder Zitat-Karten mit Sternebewertung |
| `zertifikate` | Logo-Leiste mit Zertifizierungen (TÜV, ISO, etc.) |
| `referenzen` | Kundenlogos oder Case-Study-Snippets |
| `community` | Mitglieder-Zahlen, Social-Media-Feeds, Follower-Counts |

### Kontaktmethoden (contactMethods)

| Methode | Implementierung |
|---------|-----------------|
| `formular` | Kontaktformular prominent auf Kontaktseite, ggf. auch in Footer |
| `telefon` | Telefonnummer im Header + sticky CTA auf Mobile |
| `buchung` | Buchungstool-Integration (z.B. Calendly-Embed) auf Kontaktseite |

### CTA-Implementierung

- **Primärer CTA:** Haupthandlungsaufforderung, prominent platziert (Hero, Header, Sticky)
- **Sekundärer CTA:** Alternative Handlung, weniger prominent aber sichtbar

---

## Interaktions-Level

Kategorie G definiert das Interaktionsniveau der Website.

### Level-Definitionen

| Level | Beschreibung | Regeln |
|-------|--------------|--------|
| `ruhig` | Maximale visuelle Ruhe | Keine Animationen, kein Parallax, statisches Layout, **framer-motion NICHT verwenden**, maximal 1 CTA pro Viewport |
| `moderat` | Ausgewogenes Layout | Dezente Fade-In Animationen, subtile Hover-Effekte, **framer-motion sparsam einsetzen**, IntersectionObserver-basierte Reveals |
| `dynamisch` | Lebendige Interaktion | Scroll-Animationen, Parallax erlaubt, Micro-Interactions, **framer-motion aktiv eingesetzt**, Sticky CTAs |

### Animations-Einstellung (animations)

| Wert | Beschreibung |
|------|--------------|
| `keine` | Absolut keine Animationen, auch keine Hover-Transitions |
| `dezent` | Nur subtile Transitions (opacity, transform), max. 300ms |
| `praesent` | Auffälligere Animationen, Scroll-triggered, Stagger-Effekte |

### Scroll-Verhalten (scrollBehavior)

| Wert | CSS-Umsetzung |
|------|---------------|
| `normal` | `scroll-behavior: auto` |
| `smooth` | `scroll-behavior: smooth` (auf `html` Element) |

---

## Integrationen

Kategorie I definiert technische Integrationen.

### Newsletter

Wenn `newsletter: true`:
- Newsletter-Signup-Formular im Footer
- Dedizierte Section auf der Startseite (optional)
- Platzhalter für Newsletter-Provider (Mailchimp, etc.)

### Buchungstool

Wenn `bookingTool` gesetzt:
- Als iframe/embed auf der Kontaktseite einbinden
- Platzhalter-Embed wenn kein konkreter Anbieter angegeben:
  ```html
  <!-- TODO: Buchungstool-Integration hier einfügen -->
  <div class="booking-placeholder">Buchungstool wird hier eingebunden</div>
  ```

### Externe Integrationen

Externe Integrationen als Platzhalter-Kommentare im Code markieren:
```typescript
// TODO: Integration ${name} - ${description}
```

---

## Impressum & Datenschutz

### Impressum

Legal-Daten kommen aus `spec.technical.legal.impressum` mit folgender Struktur:

```json
{
  "companyName": "Firmenname GmbH",
  "street": "Musterstraße 1",
  "postalCode": "12345",
  "city": "Musterstadt",
  "country": "Deutschland",
  "email": "info@example.com",
  "phone": "+49 123 456789",
  "vatId": "DE123456789",
  "register": "HRB 12345, Amtsgericht Musterstadt"
}
```

**Pflicht:** Die KI generiert aus diesen Daten automatisch eine korrekte Impressum-Seite gemäß DACH-Recht.

### Datenschutz

Datenschutz-Seite enthält mindestens:
- Cookie-Hinweis
- Hosting-Info (aus `spec.technical.hosting`)
- Analytics-Angabe (aus `spec.technical.tracking`)
- Kontaktdaten des Verantwortlichen
- Hinweis auf Rechte der Betroffenen

---

## Research-Insights Nutzung

Die `llmResearch`-Daten im ProjectSpec enthalten wertvolle Insights.

### Verfügbare Research-Daten

| Feld | Verwendung |
|------|------------|
| `audienceAnalysis` | Bei Content-Erstellung für Kat. B berücksichtigen |
| `uxRecommendations` | Bei Layout-Entscheidungen berücksichtigen |
| `conversionStrategy` | Bei CTA-Platzierung und Funnel-Design berücksichtigen |
| `suggestedUSPs` | Auf Startseite und Überzeugungsseiten prominent platzieren |

### Umsetzung

- USPs aus `suggestedUSPs` als Feature-Cards oder Hero-Bullet-Points
- `conversionStrategy` bestimmt den Aufbau von Conversion-Seiten
- `uxRecommendations` fließen in Layout-Entscheidungen ein

---

## 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.