CSS-Architektur im großen Maßstab: Vom Chaos zur Souveränität
Wie man CSS in großen Anwendungen strukturiert: Design-Tokens, Komponentenmuster, Utility-Klassen und Prinzipien gegen Stylesheet-Entropie.
Das CSS-Problem im großen Maßstab
CSS ist leicht zu schreiben und schwer zu warten. Jeder Entwickler fügt Styles hinzu, die isoliert funktionieren, und über Monate sammelt das Stylesheet Tausende Zeilen Overrides, toten Code und Spezifitätskämpfe an.
Die Lösung ist kein neues CSS-Framework — es ist ein klarer Architekturansatz, dem das ganze Team folgt.
Ebene 1: Design-Tokens — das Fundament
Design-Tokens sind die einzige Source of Truth für visuelle Werte. Ohne sie tauchen dieselbe Farbe, derselbe Abstand oder Radius als hartkodierte Werte an Dutzenden Stellen auf, was konsistente Änderungen unmöglich macht.
/* tokens.css — global design decisions */
:root {
/* Color palette — raw values */
--color-neutral-50: #fafafa;
--color-neutral-900: #171717;
--color-blue-500: #3b82f6;
--color-blue-600: #2563eb;
/* Semantic tokens — what the color means, not what it is */
--color-text-primary: var(--color-neutral-900);
--color-text-secondary: #6b7280;
--color-action-primary: var(--color-blue-600);
--color-action-primary-hover: var(--color-blue-500);
--color-background-page: #ffffff;
--color-background-subtle: var(--color-neutral-50);
/* Dark mode overrides semantic tokens only */
@media (prefers-color-scheme: dark) {
--color-text-primary: var(--color-neutral-50);
--color-background-page: var(--color-neutral-900);
}
}Die Regel: Komponenten verwenden semantische Tokens, niemals Rohwerte. Eine Markenfarbe zu ändern wird zur Aktualisierung eines einzigen Tokens.
Ebene 2: Tailwind für Utility-First-Komponenten
Tailwinds Utility-First-Ansatz eliminiert Namenskonflikte und ungenutzte Styles von vornherein. Aber im großen Maßstab braucht er Disziplin.
Komponentenextraktion vs. Utility-Wildwuchs
// ❌ Utility sprawl — unreadable, hard to maintain
function Button({ children, variant }: ButtonProps) {
return (
<button
className={`
inline-flex items-center justify-center gap-2 rounded-md px-4 py-2
text-sm font-medium transition-colors focus-visible:outline-none
focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2
disabled:pointer-events-none disabled:opacity-50
${
variant === "primary"
? "bg-blue-600 text-white hover:bg-blue-700 active:bg-blue-800"
: "border border-gray-200 bg-white text-gray-900 hover:bg-gray-50"
}
`}
>
{children}
</button>
);
}
// ✅ Extracted with cva (class-variance-authority)
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";
const buttonVariants = cva(
// Base classes — always applied
"inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
{
variants: {
variant: {
primary: "bg-primary text-primary-foreground hover:bg-primary/90",
secondary:
"border border-input bg-background hover:bg-accent hover:text-accent-foreground",
ghost: "hover:bg-accent hover:text-accent-foreground",
destructive:
"bg-destructive text-destructive-foreground hover:bg-destructive/90",
},
size: {
sm: "h-8 px-3 text-xs",
md: "h-9 px-4",
lg: "h-11 px-6 text-base",
},
},
defaultVariants: { variant: "primary", size: "md" },
},
);
function Button({ className, variant, size, ...props }: ButtonProps) {
return (
<button
className={cn(buttonVariants({ variant, size }), className)}
{...props}
/>
);
}Ebene 3: Das cn()-Utility — Klassen sicher zusammenführen
Beim Kombinieren bedingter Klassen verwende clsx + tailwind-merge, um Konflikte zu vermeiden.
// lib/utils.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
// Without cn — later classes don't override earlier ones
const class1 = "px-4 px-8"; // Both px-4 and px-8 exist — undefined behavior
// With cn — tailwind-merge resolves conflicts
const class2 = cn("px-4", "px-8"); // → "px-8" — last value wins correctly
// Usage in components
function Card({ className, elevated }: CardProps) {
return (
<div
className={cn(
"rounded-lg border bg-card p-6",
elevated && "shadow-lg",
className // Allow consumers to override
)}
/>
);
}Ebene 4: Konsistente Abstände und Layout
Inkonsistente Abstände sind der schnellste Weg, eine UI ungepflegt aussehen zu lassen. Erzwinge eine Abstandsskala.
/* Spacing scale — multiples of 4px */
:root {
--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--space-6: 1.5rem; /* 24px */
--space-8: 2rem; /* 32px */
--space-12: 3rem; /* 48px */
--space-16: 4rem; /* 64px */
}Mit Tailwind wird das durch die Spacing-Skala in tailwind.config.ts erzwungen. Die Regel: Abstandswerte, die nicht in der Skala stehen, sind nicht erlaubt.
Ebene 5: Component-API-Design
Gute CSS-Architektur zeigt sich auf der Ebene der Komponenten-API.
// ❌ Style leaks through className everywhere
<Section className="mt-12 mb-8 px-4 max-w-4xl mx-auto">
<Heading className="text-2xl font-bold mb-4">Title</Heading>
<Text className="text-gray-600 leading-relaxed">Content</Text>
</Section>
// ✅ Semantic props — consumers express intent, not implementation
<Section spacing="lg" contained>
<Heading level={2} size="xl">Title</Heading>
<Text color="secondary" size="base">Content</Text>
</Section>Semantische Props ermöglichen es, die CSS-Implementierung zu refaktorisieren, ohne jeden Consumer anzupassen.
Langfristig gesund halten
Totes CSS auditieren: Verwende PurgeCSS oder Tailwinds eingebautes Purging. Ungenutzte Styles sind unsichtbare Komplexität.
Magic Numbers verbieten: Wenn margin-top: 17px in einem PR auftaucht, frag nach, warum es nicht space-4 (16px) ist. Magic Numbers zerstören das Design-System.
Eine Komponentendatei, eine Style-Datei: Halte Styles bei den Komponenten (Co-Location). Globale Stylesheets, die auf Tausende Zeilen anwachsen, sind unwartbar.
Entscheidungen dokumentieren: Das Wichtigste in einem Design-System sind nicht die Komponenten, sondern das Entscheidungsprotokoll. Warum hat der Button 8px vertikales Padding? Warum beträgt der Border-Radius 6px? Dokumentiere es, damit künftige Contributors nicht raten müssen.
CSS-Architektur ist keine glamouröse Arbeit, aber ein gut strukturiertes Design-System ist eine der Investitionen mit der größten Hebelwirkung, die ein Frontend-Team tätigen kann. Die besten sind unsichtbar — sie sorgen einfach dafür, dass jede neue Komponente schnell zu bauen und konsistent mit allem anderen ist.
