# CSS-Framework im Vergleich — Bootstrap & Tailwind

Ein selbst entwickeltes, schlankes CSS-Framework für Jinja2/HTMX-Webapplikationen.  
Kein NPM, kein Build-Schritt, kein fremder Designgeschmack — nur das, was wirklich gebraucht wird.

---

## Warum ein eigenes Framework?

Die meisten Projekte brauchen kein 300-kB-Monster, sondern ein konsistentes Designsystem, das zur eigenen Sprache passt. CSS-Framework wurde für genau einen Stack gebaut: **FastAPI + Jinja2 + HTMX**. Alles andere wurde weggelassen.

---

## Kurzübersicht

| Kriterium | CSS-Framework | Bootstrap 5 | Tailwind CSS |
|---|---|---|---|
| **Eigene Kontrolle** | Vollständig | Begrenzt | Mittel |
| **Build-Tool erforderlich** | Nein | Nein | Ja (PostCSS/Vite) |
| **Dateigröße (unkomprimiert)** | Klein (~5 Dateien) | ~180 kB CSS + JS | Roh ~4 MB, nach Purge variabel |
| **Designsystem (Tokens)** | CSS Custom Properties | Sass-Variablen / CSS Vars (überschreibbar) | Tailwind Config (JS) |
| **Classless Base** | Ja | Nein (Reboot, aber kein Classless) | Nein |
| **Dark Mode** | Eingebaut via `data-theme` | Eingebaut (Klasse/Media) | Eingebaut (Klasse/Media) |
| **HTML-Lesbarkeit** | Hoch | Mittel | Niedrig |
| **Externes CDN / Abhängigkeit** | Keine | Optional, aber üblich | Kein CDN für Production |
| **JavaScript** | Minimal, framework-agnostisch | Umfangreich (Popper, Bundle) | Kein eigenes JS |
| **Jinja2/HTMX-Integration** | Erstklassig | Nachträglich | Nachträglich |

---

## Gegenüber Bootstrap

### Was Bootstrap mitbringt — und was das kostet

Bootstrap ist vollständig und ausgereift. Aber das hat seinen Preis:

- **Der Bootstrap-Look ist unverkennbar.** Ohne umfangreiches Customizing sehen alle Bootstrap-Seiten ähnlich aus. Das Überschreiben von Sass-Variablen oder Custom Properties setzt voraus, dass man zuerst versteht, was Bootstrap macht — bevor man es ändern kann.
- **Alles oder nichts.** Bootstrap lädt Komponenten mit, die nie genutzt werden. Tree-Shaking ist umständlich. PurgeCSS oder eigene Import-Selektion ist nötig.
- **JavaScript-Bundle.** Bootstrap bringt eigene JS-Abhängigkeiten mit (Popper.js für Dropdowns, Tooltips, Modals). Mit HTMX entstehen Konflikte und Redundanzen.
- **Klassen statt Semantik.** Selbst ein Button braucht `class="btn btn-primary"`. Kein Element ist ohne Klasse sinnvoll gestylt.
- **Kein echtes Token-System.** Zwar gibt es CSS Custom Properties, aber sie sind nach Bootstrap-Logik strukturiert — nicht nach dem eigenen Designsystem.

### Was CSS-Framework anders macht

- **Classless First.** Valides, semantisches HTML ist ohne eine einzige Klasse brauchbar gestylt. Formulare, Tabellen, Typografie, Listen — alles läuft direkt aus `base.css`.
- **Token First.** Farben, Spacing, Typografie, Radius und Schatten sind in `tokens.css` zentral definiert. Eine Änderung dort zieht sich durch das gesamte Framework. Keine Sass-Compiler nötig.
- **Kein JavaScript-Bundle.** Die wenigen nötigen Funktionen (Modal, Toast, Dropdown) sind schlanke, eigenständige Funktionen ohne externe Abhängigkeit — kompatibel mit HTMX.
- **Kein Bootstrap-Look.** Das visuelle Ergebnis gehört zu uns, nicht zu Bootstrap.

---

## Gegenüber Tailwind

### Was Tailwind verspricht — und wo es kippt

Tailwind ist ein anderer Ansatz: keine Komponenten, nur Utility-Klassen. Das klingt flexibel, hat aber konkrete Nachteile im gewählten Stack:

- **Build-Toolchain zwingend.** Tailwind braucht PostCSS, Vite oder einen ähnlichen Bundler. Für ein Jinja2-Projekt mit statischem CSS ist das ein erheblicher Overhead — ein Schritt, der bei CSS-Framework vollständig entfällt.
- **HTML wird unleserlich.** Ein Button mit Padding, Hover-Farbe, Radius, Font-Weight und Transition erzeugt in Tailwind 8–12 Klassen auf einem Element. Jinja2-Templates werden dadurch schwer wartbar.
- **Kein Classless-Ansatz.** Jedes Element, das nicht wie `<p>` aussehen soll, braucht Klassen. Formulare, Tabellen und Listen sind ohne Klassen praktisch unstylt.
- **Designentscheidungen im Markup verstreut.** Farb- und Spacing-Entscheidungen stecken in hunderten Template-Zeilen statt in einer zentralen Tokendatei. Farbe ändern bedeutet: alle Dateien durchsuchen.
- **HTMX-Fragmente werden zum Problem.** Wird ein HTML-Fragment dynamisch nachgeladen, muss Tailwind's JIT wissen, welche Klassen vorkommen können — oder die Klassen werden weggepurgt. Mit CSS-Framework ist das kein Thema.

### Was CSS-Framework anders macht

- **Kein Build-Schritt.** `main.css` wird direkt eingebunden. Fertig. Funktioniert in jedem Deployment ohne Pipeline.
- **Lesbares HTML.** Ein Button ist `<button class="btn btn-primary">` — nicht `<button class="px-4 py-2 bg-indigo-600 hover:bg-indigo-700 text-white font-medium rounded-md transition">`.
- **Designsystem an einer Stelle.** Alle Anpassungen in `tokens.css`. Eine Zeile ändert die Akzentfarbe im gesamten Projekt.
- **HTMX-kompatibel by design.** Dynamisch nachgeladene Fragmente nutzen dieselben Klassen — kein Purging, kein JIT-Problem.

---

## Stärken im Überblick

### Volle Kontrolle durch Eigenentwicklung

- Kein fremdes Designsystem, dem man sich unterwerfen muss
- Kein Versionsdruck durch externe Abhängigkeiten
- Keine Breaking Changes von außen
- Jede Zeile Code ist bekannt und erklärbar

### Minimal-Approach: nur was gebraucht wird

- Vier Dateien: `tokens.css`, `base.css`, `components.css`, `utilities.css`
- Kein toter Code — jede Komponente hat einen konkreten Anwendungsfall im Projekt
- Utilities bewusst klein gehalten — keine Tailwind-artige Klassenexplosion
- JavaScript nur wo CSS nicht ausreicht — und dort minimal und framework-agnostisch

### Token-basiertes Designsystem

- Alle visuellen Entscheidungen als CSS Custom Properties in `tokens.css`
- Zweischichtiges Farbsystem: Rohpalette + semantische Aliases
- Dark Mode out of the box via `data-theme`-Attribut
- Konsistenz ohne Disziplin: Wer auf Tokens aufbaut, bleibt automatisch im System

### Classless First

- Semantisches HTML funktioniert ohne eine einzige Klasse
- Bessere Accessibility durch ehrliches HTML statt Div-Suppe
- Niedrigere Einstiegshürde: HTML schreiben, sieht sofort gut aus

### Gebaut für den eigenen Stack

- Erstklassige Jinja2-Template-Unterstützung mit fertigem `base.html` (dokumentiert in `.opencode/skills/references/jinja2.md`)
- HTMX-Patterns dokumentiert und getestet
- FastAPI-Integration beschrieben
- Kein Build-Schritt — `main.css` direkt via `<link>` einbinden

---

## KI-Kompatibilität und Einsatz ohne Frontend-Erfahrung

### Das Framework ist von Grund auf KI-gerecht gebaut

CSS-Framework liefert nicht nur CSS — es bringt eine eigene KI-Guidance-Schicht mit:

```
.opencode/
├── skills/
│   ├── SKILL.md                  — Schnellreferenz: alle Komponenten, Tokens, JS-API
│   └── references/
│       ├── components.md         — Vollständige Beispiele aller Komponenten
│       ├── tokens.md             — Alle CSS Custom Properties mit Werten
│       └── jinja2.md             — Fertiges base.html, HTMX-Patterns, FastAPI-Integration
└── commands/
    ├── create-component.md       — Checkliste: neue Komponente von CSS bis Doku
    ├── add-token.md              — Checkliste: neuen Token einführen
    └── sync-docs.md              — Checkliste: Code-Doku-Drift beheben
```

Ein KI-Tool, das mit diesem Framework arbeitet, hat strukturierte Referenzen on-demand zur Verfügung — keine losen Prompts, keine Halluzinationen über nicht existente Klassen. Das ist bei Bootstrap und Tailwind anders: dort stammt das KI-Wissen aus Trainingsdaten, die veraltet sein können und nicht auf den eigenen Customizing-Stand angepasst sind.

**Konkrete Vorteile gegenüber Bootstrap/Tailwind beim KI-Einsatz:**

| Aspekt | CSS-Framework | Bootstrap | Tailwind |
|---|---|---|---|
| KI-Referenz aktuell und projektspezifisch | Ja (`SKILL.md`, `components.md`) | Nein (Trainingsdaten) | Nein (Trainingsdaten) |
| Halluzinationsrisiko bei Klassen | Gering — alle Klassen dokumentiert | Mittel | Hoch (viele Varianten) |
| KI kann neue Komponenten regelkonform anlegen | Ja (`create-component.md`) | Nein | Nein |
| Konsistenz über KI-generierte Fragmente hinweg | Hoch (Tokens erzwingen System) | Mittel | Niedrig (Utility-Wildwuchs) |

### Geeignet für Entwickler ohne Frontend-Erfahrung

CSS-Framework ist bewusst für Backend-Entwickler und Teams konzipiert, die mit KI-Tools wie Claude Code arbeiten:

**Classless First senkt die Einstiegshürde drastisch.** Wer valides, semantisches HTML schreibt — so wie es FastAPI-Entwickler für Jinja2-Templates ohnehin tun — bekommt sofort anständig aussehendes Ergebnis. Kein Wissen über CSS-Klassen nötig, um loszulegen.

**Token First macht Anpassungen sicher.** Farbe, Spacing oder Typografie ändern sich in einer einzigen Datei (`tokens.css`). Es gibt keine versteckten Abhängigkeiten, die man kennen müsste.

**Die KI arbeitet im gleichen System.** Wer Claude Code oder ein anderes KI-Tool verwendet, kann ihm den SKILL.md-Kontext mitgeben — und bekommt Ausgaben, die das bestehende Designsystem respektieren. Das ist ein qualitativer Unterschied zu Projekten, bei denen die KI rät, welche Bootstrap-Klassen passen könnten.

**Kein Build-Tooling.** Kein Webpack, kein Vite, kein PostCSS. Die einzige Voraussetzung ist ein Webserver, der eine CSS-Datei ausliefert. Das eliminiert eine ganze Kategorie von Problemen, die Frontend-Unerfahrene erfahrungsgemäß aufhalten.

---

## Wann macht ein eigenes Framework Sinn?

| Situation | Empfehlung |
|---|---|
| Eigener Stack mit festem Designsystem | **Eigenes Framework** |
| Schnelles Prototyping ohne Design-Anforderungen | Bootstrap (vertraut, schnell) |
| Design-System via Config, Team mit Build-Infrastruktur | Tailwind |
| Jinja2 + HTMX + FastAPI | **Dieses Framework** |
| Externes Team, wechselnde Entwickler | Bootstrap (niedrige Einarbeitungszeit) |

---

*Dieses Framework ist nicht der richtige Ansatz für jedes Projekt — aber für unseren Stack ist es der richtige.*