# Repo Map — CSS-Framework

```
css-framework/
│
├── .opencode/                         — KI-Guidance für OpenCode
│   ├── commands/
│   │   ├── create-component.md       — Checkliste: neue Komponente von CSS bis Doku
│   │   ├── add-token.md              — Checkliste: neuen Design-Token einführen
│   │   └── sync-docs.md              — Checkliste: Code-Doku-Drift beheben
│   └── skills/
│       ├── SKILL.md                  — Schnellreferenz (Komponenten, Tokens, JS-API, Muster)
│       └── references/
│           ├── components.md         — Vollständige Komponenten-Dokumentation mit Beispielen
│           ├── tokens.md             — Alle CSS Custom Properties mit Werten und Verwendung
│           └── jinja2.md             — Basis-Template, HTMX-Muster und FastAPI-Patterns für Consumer-Apps
│
├── AGENTS.md                         — Verbindliche Arbeitsregeln für KI-Agenten
├── README.md                         — Nutzerdokumentation (vollständig, für Menschen)
├── REPO_MAP.md                       — Diese Datei
├── CHANGELOG.md                      — Versionshistorie
│
├── docs/
│   └── VERGLEICH.md                  — Vergleich mit Bootstrap und Tailwind
│
├── main.css                          — Entry Point, importiert alle vier Layer
├── tokens.css                        — Design Tokens (Single Source of Truth)
├── base.css                          — Classless Reset + semantische HTML-Elemente
├── components.css                    — Opt-in Komponenten-Klassen
├── utilities.css                     — Minimale Helfer-Klassen
├── fonts.css                         — Vorlage für lokale Google Fonts (optional)
├── framework.js                      — JavaScript API (data-action, Modal, Toast, Tabs, Dropdown usw.)
├── theme.js                          — Hell/Dunkel vor dem Rendern setzen und umschalten
├── demo.css                          — Styles nur für index.html (nicht Teil des Frameworks)
├── demo.js                           — Skripte nur für index.html (nicht Teil des Frameworks)
├── build.py                          — Minifier: erzeugt dist/ via python3 build.py
│
├── dist/                             — Build-Ausgabe (generiert, nicht editieren)
│   ├── main.min.css                  — Alle vier CSS-Layer gebündelt und minifiziert
│   ├── framework.min.js              — JavaScript API minifiziert
│   └── index.html                    — Demo mit minifizierten Pfaden (Sichtprüfung)
│
└── index.html                        — Vollständige Komponentendemo (Entwicklung + Sichtprüfung)
```

---

## CSS-Schichtenarchitektur

```
tokens.css   →   base.css   →   components.css   →   utilities.css
    ↑                                                       ↑
Single Source                                         Höchste Spezifität
of Truth                                              (überschreibt alles)
```

Entspricht der Import-Reihenfolge in `main.css`. Änderungen immer in der **niedrigsten sinnvollen Schicht**.

---

## KI-Ebenen

| Datei | Zweck | Wann aktiv |
|---|---|---|
| `AGENTS.md` | Guardrails, verbindliche Regeln | Immer — wird automatisch geladen |
| `.opencode/skills/SKILL.md` | Schnellreferenz für Komponenten und Tokens | On-demand beim Skill-Aufruf |
| `.opencode/skills/references/components.md` | Tiefenreferenz mit vollständigen Komponenten-Beispielen | On-demand als Ergänzung zu SKILL.md |
| `.opencode/skills/references/tokens.md` | Alle CSS Custom Properties mit Werten | On-demand bei Token-Fragen |
| `.opencode/skills/references/jinja2.md` | Basis-Template, HTMX-Muster, FastAPI-Patterns | On-demand beim Arbeiten in FastAPI-Apps |
| `.opencode/commands/create-component.md` | Neue Komponente von CSS bis Doku | Manuell bei neuen Komponenten |
| `.opencode/commands/add-token.md` | Neuen Design-Token einführen | Manuell bei neuen Tokens |
| `.opencode/commands/sync-docs.md` | Code-Doku-Drift beheben | Manuell wenn Code und Doku auseinanderlaufen |

---

## Komponenten-Übersicht

### Classless (kein Klassen nötig — `base.css`)
`h1–h6` · `p` · `a` · `strong` · `em` · `code` · `pre` · `blockquote` · `ul` · `ol` · `dl` · `table` · `input` · `select` · `textarea` · `details` · `summary` · `figure` · `img`

### Layout (`components.css`)
`container` (sm/md/lg/xl/2xl) · `stack` (sm/lg) · `cluster` · `grid` (2/3/4) · `with-sidebar`

### Navigation (`components.css`)
`topnav` · `sidebar` · `breadcrumbs` · `footer` (einfach + `footer-full`)

### Komponenten (`components.css`)
`btn` (primary/secondary/ghost/danger/success, xs/sm/lg/xl, full/icon) · `button-group` · `segmented` · `badge` (7 Varianten, dot) · `card` (flat/raised/ghost/hover) · `accordion` (flush/muted) · `tabs` · `modal` (sm/lg/xl) · `dropdown` · `pagination`

### Formulare (`components.css`)
`form-group` · `form-row` · `input-group` (prefix/suffix) · `file-upload` (dropzone, is-error) · `switch`

### Tabellen (`components.css`)
`table-wrap` · `table-striped` · `table-compact` · `table-sticky` · `table-sticky-col` · `table-stack` · `table-sortable`

### Feedback & Status (`components.css`)
`spinner` (sm/lg) · `progress-bar` · `skeleton` · `stat` (data-trend) · `avatar` (sm/lg) · `avatar-group` · `empty` · `toast` · `alert` (info/success/warning/danger, dismissible) · `divider`

### Neue Komponenten (`components.css`)
`chip-group` (checkbox/radio, sm) · `timeline` (accent/success/warning/danger) · `stepper` (horizontal/vertikal) · `list-group` · `action-list` · `meta-list` (stacked/compact/flush)

### Tooltip (`components.css`)
`data-tooltip` · `data-tooltip-pos` (top/bottom/left/right) — CSS-only

### Utilities (`utilities.css`)
Display · Flex · Alignment (`items-*` / `justify-*` / `self-*`) · Gap · Margin · Padding · Text · Font · Border · Background · Shadow · Overflow · Width/Height · Position · Cursor · Opacity · Transition · `filter-bar` · `sr-only` · `hide-mobile` / `hide-desktop`

---

## JavaScript API

Alle Funktionen sind global verfügbar — gehören in einen `<script>`-Block am Ende des Basis-Templates.

| Funktion | Beschreibung |
|---|---|
| `openModal(id)` | Modal öffnen, Fokus setzen, Scroll sperren |
| `closeModal(id)` | Modal schließen |
| `switchTab(btn, panelId)` | Tab wechseln, ARIA aktualisieren |
| `toggleDropdown(id)` | Dropdown öffnen/schließen |
| `toggleNavDd(btn)` | Nav-Dropdown öffnen/schließen |
| `showToast(message, type)` | Toast einblenden (4s Auto-Dismiss) |
| `removeToast(id)` | Toast sofort entfernen |
| `dismissAlert(btn)` | Alert mit Transition entfernen |
| `sortTable(th)` | Tabellenspalte auf-/absteigend sortieren |