at-mintel/ARCHITECTURE.md

Mintel Universal Design System - Architecture Manifesto

Dieses Dokument ist der absolute Nordstern für alle Entwickler und KI-Agenten, die an der Mintel Codebase arbeiten. Es definiert, wie wir UI-Komponenten bauen, isolieren und skalieren, ohne in eine "Lock-in"-Falle zu tappen.

1. Das Problem: Die Design System Falle

Wir bauen eine neutrale Basis (@mintel/ui), auf der Web, Print (PDF), Präsentationen und Remotion-Videos basieren. Das größte Risiko: Komponenten werden im Laufe der Zeit so komplex (mit dutzenden if/else-Switches für Kunden-Sonderfälle), dass niemand sich mehr traut, sie anzufassen, aus Angst, andere Projekte zu zerstören.

2. Die Zwiebel-Architektur (Core vs. Components)

Um dieses Problem zu lösen, teilen wir unser UI-Paket logisch in zwei Ebenen:

Tier 1: Primitives (Der Kern)

• Was ist das? Die absoluten Grundbausteine: <Box>, <Text>, <Flex>, <Grid>.
• Die Regel: Diese Komponenten haben keine Meinung. Sie dienen ausschließlich als saubere, typisierte Wrapper, um Tailwind-Klassen und Props durchzureichen. Sie dürfen sich architektonisch nie ändern.
• Warum? Weil Projekte im Notfall immer auf diese Bausteine zurückfallen können, um eigene, hochgradig individuelle Layouts zu bauen.

Tier 2: Base Components (Der Mintel Standard)

• Was ist das? Fertige Komponenten wie <Button>, <Card>, <HeroSection>.
• Die Regel: Sie haben den "neutralen" Mintel-Standardlook. Sie bauen zu 100% auf Tier 1 Primitives auf.

3. Die 3 Goldenen Regeln gegen den "Lock-in"

Wenn ein spezifisches Projekt (z.B. ein neuer Kunde) eine Komponente braucht, die radikal vom Mintel-Standard abweicht, gelten folgende Eskalationsstufen:

Eskalation 1: Compound Components

Komponenten dürfen niemals gigantische Props-Monster (<Card hideHeader={true} showFooter={false} />) werden. Wir nutzen Compound Components: Das Projekt setzt die Card selbst aus <Card.Header>, <Card.Body> und <Card.Footer> zusammen. Braucht das Projekt den Header nicht, lässt es ihn einfach weg.

Eskalation 2: Das asChild Pattern (Slot)

Wir sperren Projekte niemals in unsere DOM-Struktur ein. Wenn eine Komponente Logik enthält, nutzen wir das asChild (oder Slot) Pattern. Beispiel: Ein <Button asChild> rendert kein <button> HTML-Tag, sondern reicht seine Tailwind-Styles und seine Accessibility-Logik transparent an das Kind-Element durch (z.B. einen Next.js <Link>).

Eskalation 3: Der "Eject" (Der Shadcn-Weg)

Wenn eine @mintel/ui Komponente absolut nicht mehr für den Kunden X passt, wird sie nicht durch if (kunde === 'X')-Logik in der Basis "aufgebohrt". Stattdessen ejecten (kopieren) wir den Source-Code der Komponente physisch in das Projekt von Kunde X (apps/kunde-x/components/). Ab diesem Moment "besitzt" das Projekt diese Komponente und kann sie nach Belieben modifizieren. Die neutrale Basis bleibt sauber!

4. Agenten & LLM Workflow

Jeder KI-Agent, der eine neue Komponente für @mintel/ui baut, muss folgende Checkliste abarbeiten:

1. Ladle-First (TDD): Keine Komponente wird ohne eine dazugehörige .stories.tsx Datei für den Ladle-Katalog akzeptiert. Ladle ist unsere Source of Truth.
2. Keine Business-Logik: Die Komponente darf keinen State (außer internen UI-State wie isOpen), keine API-Fetches und keine projektspezifischen Konstanten enthalten.
3. Universalität prüfen: Die Komponente darf keine reinen Browser-APIs (window.location) ohne Fallbacks nutzen, damit sie auch serverseitig in der Print-Engine (PDF) und in der Remotion-Engine gerendert werden kann.
4. Tailwind pur: Nutze ausschließlich Tailwind-Klassen. Keine externen CSS-Module oder style-Tags, wenn nicht physikalisch zwingend (z.B. bei dynamischer Frame-Interpolation in Videos).

---

Wer dieses Manifest bricht, sabotiert die Skalierbarkeit des Monorepos. Halte dich an die Zwiebel-Architektur!