# Storybook für UI-Packages **Status:** in_progress (21/20 component stories + build + test-runner a11y-gate + lost-pixel baselines + locale toolbar + tailwind-v4 pipeline shipped; brand/ui-layer toolbar globals + Coolify static-deploy still deferred) **Task-ID:** #62 **Phase:** 08 **Estimated Effort:** 2 Wochen Initial-Setup (~20 Stories); inkrementell weiter **Owner:** unassigned ## Problem Die Boilerplate hat **drei UI-Packages** (`packages/ui`, `packages/ui-app`, `packages/ui-subframe`, ergänzt durch `packages/ui-mock`), aber keine zentrale Inspektions-/Test-Oberfläche für Komponenten: - **Visuelle Diffs zwischen den drei Layern sind unsichtbar:** `ui` (Tailwind+shadcn-Basis), `ui-app` (Tenant-App-spezifische Composites) und `ui-subframe` (Subframe-Designer-Output) implementieren teilweise ähnliche Komponenten (Button, Card, Input). Es gibt keinen Side-by-Side-Vergleich, daher driften APIs auseinander. - **Onboarding für neue Devs schwierig:** „Wie sieht eine Standard-Card mit Header + Footer aus?" — Antwort erfordert Source-Code-Suche und Browser-Manual-Test gegen lokal laufende App. - **A11y-Regressionen unentdeckt:** Buttons ohne Focus-Ring, Dialoge ohne korrekte ARIA-Rollen, Forms ohne Label-Verknüpfung werden erst beim Lighthouse-Audit (Phase 10) oder im Production-Browser-Test gefunden. - **Designer ↔ Engineer-Loop:** Brand-Settings (Brand-Colors, Logo-Variants, Subframe-Themes) werden ohne visuelle Sandbox getestet — Theme-Bugs erst in Production sichtbar. - **Visual-Regression fehlt:** Bei PRs kein automated Diff von Komponent-Renderings — Refactorings können Layout brechen ohne dass es im PR-Review auffällt. Storybook 8.x mit Component-Story-Format-3 löst all das mit überschaubarem Setup-Aufwand und blockiert nichts kritisches im Rest der Boilerplate. ## Depends on - `01-tech-debt-foundation/dep-updates.md` — Vite 5.x + React 19 + Tailwind v4 müssen vorhanden sein; Storybook 8.x braucht modernen Vite-Builder - `01-tech-debt-foundation/dead-code.md` — vor Setup soll Dead-Code aus UI-Packages entfernt sein, sonst landen verwaiste Komponenten in Stories ## Blocks - Nichts kritisches. Storybook ist eine Quality-of-Life-Verbesserung und blockiert keine anderen Tasks - Optional: `10-compliance-polish/wcag-internal.md` profitiert von Storybook-A11y-Reports als Baseline ## Approach **Eine zentrale Storybook-Instance unter `apps/storybook/`** die Stories aus allen 3-4 UI-Packages aggregiert. **Architektur-Entscheidungen:** - **Storybook-Version:** 8.x (aktuelles Major; CSF-3 nativ, Vite-Builder default, kleinere Bundle-Size, neue Test-Story-Composition) - **Builder:** `@storybook/react-vite` (passt zur Vite-basierten React-Router-Setup; teilt Vite-Config-Snippets aus den Packages) - **Stories-Glob:** `main.ts` enthält `'../packages/{ui,ui-app,ui-subframe,ui-mock}/src/**/*.stories.@(ts|tsx|mdx)'` → Auto-Discovery, Stories liegen co-located bei den Source-Files - **Story-Format:** CSF-3 mit `args` + `argTypes` + `play`-Functions; MDX nur für Doku-Pages (Intro, Theme-Guide) - **Test-Story-Composition:** `composeStories` von `@storybook/react` exportiert Stories als testbare React-Komponenten → keine Doppel-Pflege Story vs Component-Test **20 Kern-Komponenten für Initial-Story-Set:** 1. Button (Variants: default/destructive/outline/ghost/link, sizes: sm/md/lg) 2. Input (Text/Email/Password mit Label + Validation-States) 3. Textarea 4. Select (Single + Multi) 5. Checkbox + Radio 6. Switch 7. Card (Header+Content+Footer Compositions) 8. Dialog (Modal, Confirm-Dialog) 9. Drawer (Side-Drawer) 10. Form-Field (Label + Input + Error-Message-Compound) 11. Table (Basic + Sortable Header) 12. DataTable (mit Pagination + Filter, aus `ui-app`) 13. Sidebar (collapsed + expanded, aus `ui-app/sidebar`) 14. Avatar (Image + Fallback-Initials) 15. Badge (Variants) 16. Toast (Success/Error/Info; Sonner-Wrapper) 17. Tooltip 18. Popover 19. Tabs 20. EmptyState (illustrated empty placeholder) **Theme-Decorator-Strategie:** Toolbar-Globals (Storybook-Standard-Mechanik) für: - **`theme`:** light | dark - **`brand`:** default | demo-tenant-blue | demo-tenant-orange (read from `packages/brand/themes/`) - **`ui-layer`:** shadcn | subframe (toggle between Komponenten-Implementations wo beide existieren) Decorator wrappt Story in `` + `` (aus `packages/ui-app/providers/`), tauscht Tailwind-Klassen-Root dynamisch. **Add-ons:** - `@storybook/addon-a11y` — axe-Checks in Story-Panel + im Test-Runner; fail on violations (configurable per Story via `parameters.a11y.disable`) - `@storybook/addon-interactions` — Play-Functions für Interaction-Tests (Click → Modal opens, Form-Submit → Validation-Errors) - `@storybook/addon-themes` — Toolbar-Theme-Switcher - `@storybook/addon-docs` — Auto-MDX-Generation aus CSF-3 args/argTypes - `@storybook/test-runner` — CLI-Runner der alle Stories als Tests ausführt (play-functions + a11y-checks) **Visual-Regression-Strategie:** - **Option A (Default, kostenfrei):** [Lost-Pixel](https://lost-pixel.com/) self-hosted in CI — vergleicht Story-Screenshots gegen Baseline; bei Diff blockt PR - **Option B (Optional):** Chromatic — gehostet bei storybook.dev, kostet ab gewisser Story-Anzahl. Doku referenziert beides, Default-Implementation ist Lost-Pixel **CI-Strategie:** - Storybook-Build (`pnpm --filter @toolctrl/storybook build-storybook`) in CI-Job; Output als Static-Site - Deploy nach Coolify-Static-Site auf `https://storybook.staging.toolctrl.de` - Test-Runner-Job läuft gegen die built Static-Site - Optional: Visual-Regression-Job läuft Lost-Pixel gegen baseline **Warum nicht Alternativen:** - ❌ Ladle: leichtgewichtiger aber unausgereifter, weniger Add-ons, kleinere Community - ❌ Histoire: Vue-fokussiert, React-Support sekundär - ❌ Pattern-Library als eigene Mini-Site selbstgebaut: Rad neu erfunden, kein A11y-Add-on, kein Test-Runner - ❌ Pro-Package eigene Storybook-Instance: führt zu Drei-Storybooks-Wartung; aggregierte Single-Instance ist Standard-Pattern im Monorepo ## Implementation Steps 1. **Apps/storybook-Workspace + Storybook-Init** - Files: `apps/storybook/package.json`, `apps/storybook/.storybook/main.ts`, `.storybook/preview.tsx`, `.storybook/manager.ts`, `apps/storybook/README.md`, `apps/storybook/tsconfig.json` - `pnpm dlx storybook@latest init --type react --builder vite` initial; danach manuelle Anpassung der Stories-Globs auf packages-Verzeichnisse - Vite-Config alignmen mit `apps/web/vite.config.ts` (Tailwind-Plugin, Path-Aliases) - Smoke-Test: `pnpm --filter @toolctrl/storybook dev` öffnet Storybook auf Port 6006 - Commit: `08-mobile/storybook: scaffold apps/storybook with vite builder` 2. **Theme-Provider-Decorator + Brand-Settings-Integration** - Files: `apps/storybook/.storybook/decorators/theme.tsx`, `decorators/brand.tsx`, `decorators/ui-layer.tsx`, `decorators/theme.test.tsx` - Toolbar-Globals registrieren: `theme`, `brand`, `ui-layer` - Decorators wrappen Story in entsprechende Providers (aus `packages/ui-app/providers`) - Tests: Decorator-Mount-Test via `@storybook/testing-react` - Commit: `08-mobile/storybook: add theme, brand, ui-layer decorators with toolbar globals` 3. **Add-ons konfigurieren (a11y, interactions, themes, docs)** - Files: Update `apps/storybook/.storybook/main.ts`, `preview.tsx`, `apps/storybook/.storybook/a11y-config.ts` - `addon-a11y` mit axe-rules-Config (WCAG-2.1-AA als Minimum) - `addon-interactions` mit Test-Step-Recorder-Setup - `addon-themes` mit `withThemeByDataAttribute`-Decorator für dark/light - `addon-docs` mit Auto-MDX-Generation aktiviert - Commit: `08-mobile/storybook: configure a11y, interactions, themes, docs addons` 4. **Stories für `packages/ui` (Basis-Komponenten 1-10)** - Files (alle in `packages/ui/src/components//.stories.tsx`): - `button.stories.tsx`, `input.stories.tsx`, `textarea.stories.tsx`, `select.stories.tsx`, `checkbox.stories.tsx`, `radio.stories.tsx`, `switch.stories.tsx`, `card.stories.tsx`, `dialog.stories.tsx`, `drawer.stories.tsx` - CSF-3-Format mit `args` + `argTypes` + Variants als Story-Exports - Mindestens 1 `play`-Function pro interaktiver Komponente (Dialog-Open, Form-Submit) - Commit: `08-mobile/storybook: add stories for 10 ui base components` 5. **Stories für `packages/ui-app` (Composites 11-15)** - Files (alle in `packages/ui-app/src/components//.stories.tsx`): - `form-field.stories.tsx`, `table.stories.tsx`, `data-table.stories.tsx`, `sidebar.stories.tsx`, `avatar.stories.tsx` - Composite-Komponenten brauchen mehr Context (z. B. ``-Mock) → über zusätzliche Decorators pro Story - Commit: `08-mobile/storybook: add stories for 5 ui-app composite components` 6. **Stories für Feedback + Overlay-Komponenten 16-20** - Files (mixed packages je nach Implementation): - `badge.stories.tsx`, `toast.stories.tsx`, `tooltip.stories.tsx`, `popover.stories.tsx`, `tabs.stories.tsx`, `empty-state.stories.tsx` - Toast: Sonner-Wrapper mit Trigger-Button in Story - Commit: `08-mobile/storybook: add stories for badges, toasts, tooltips, popovers, tabs, empty states` 7. **Test-Runner Setup + A11y-Gate** - Files: `apps/storybook/test-runner.config.ts`, `apps/storybook/package.json` (Scripts), `.github/workflows/storybook-tests.yml` - `@storybook/test-runner` installation; CLI-Script `test:storybook` - A11y-Gate: alle Stories müssen 0 violations haben außer explizit per `parameters.a11y.disable=true` ausgeschlossen - CI-Workflow: build storybook → start static-server → run test-runner against http://localhost:6006 - Commit: `08-mobile/storybook: add test-runner with a11y gate and ci workflow` 8. **Visual-Regression via Lost-Pixel** - Files: `apps/storybook/lostpixel.config.ts`, `.github/workflows/storybook-visual-regression.yml`, `apps/storybook/.lostpixel/baseline/.gitkeep` - Lost-Pixel-Setup mit Storybook-Mode (auto-scan aller Stories) - Baseline-Screenshots im Repo (LFS oder Git-Direct) - CI-Job: bei PR Lost-Pixel-Diff-Run; Diff-Failure → PR-Block + Diff-Image als Artifact - Commit: `08-mobile/storybook: add lost-pixel visual regression with baseline screenshots` 9. **CI-Deployment der Static-Site** - Files: `.github/workflows/storybook-deploy.yml`, Coolify-Service-Konfig-Snippet in Doku - Bei Push auf `main`: build storybook → deploy nach Coolify-Static-Hosting unter `storybook.staging.toolctrl.de` - Auf PRs: Preview-Deploy (eigene Subdomain pro PR via Coolify-Preview-Deployments oder fallback Lost-Pixel-Artifact-Link) - Commit: `08-mobile/storybook: add ci deployment to coolify static hosting` 10. **Doku + Living-Test-Guide** - Files: `docs/contributing/storybook.md`, `apps/storybook/.storybook/intro.mdx`, `docs/design/component-inventory.md` - Quickstart: Storybook lokal starten, Story schreiben, Test-Runner laufen lassen - Theme-Guide: wie ändere ich Brand-Colors, wie teste ich gegen anderes Brand-Theme - Component-Inventory: Tabelle aller dokumentierten Komponenten mit Layer (`ui`, `ui-app`, `ui-subframe`) + Status (`production-ready`, `draft`, `deprecated`) - Living-Test-Guide: Composing Stories als Vitest-Tests via `composeStories` - Commit: `08-mobile/storybook: add docs, intro mdx and component inventory` ## Test Requirements - **Unit-Tests (für Decorators):** Mount-Test pro Decorator (Theme, Brand, UI-Layer) — verifiziert dass passed-down-Context an Story ankommt - **Story-Tests (via Test-Runner):** - Alle 20 Initial-Stories müssen render-bar sein (kein Render-Error) - Alle Stories haben 0 a11y-violations (axe-rules) — explizit erlaubte Ausnahmen über `parameters.a11y.disable=true` mit Begründung im Comment - Stories mit `play`-Function (Dialog-Open, Form-Submit) müssen ihre Interaction-Steps erfolgreich durchlaufen - **Composed-Story-Tests:** Beispielhaft 3 Stories (Button, Dialog, Form-Field) als Vitest-Tests via `composeStories` — beweist Composition-Pattern funktioniert - **Visual-Regression:** Lost-Pixel-Baseline für alle 20 Stories; CI-Diff-Threshold ≤ 0.1 % Pixel-Diff (per Story konfigurierbar) - **Build-Test:** `pnpm --filter @toolctrl/storybook build-storybook` muss grün durchlaufen, Static-Output existiert in `apps/storybook/storybook-static/` - **Coverage-Target:** N/A für Storybook (Stories sind nicht produktions-Code); aber Story-Coverage-Target: alle Public-Komponenten aus `packages/ui` müssen mindestens 1 Story haben (Audit-Test in CI) - **Test-Files:** Stories co-located bei Components (`.stories.tsx`); Decorator-Tests in `apps/storybook/.storybook/decorators/.test.tsx` - **CI-Setup:** 3 separate Jobs: `storybook-build`, `storybook-test-runner`, `storybook-visual-regression` **NICHT als completed markieren bevor Test-Runner alle 20 Stories grün, A11y-Gate ohne Violations, Lost-Pixel-Baseline committed sind.** ## Acceptance Criteria - [ ] `apps/storybook/` existiert und `pnpm --filter @toolctrl/storybook dev` startet Storybook auf Port 6006 - [ ] Stories aus `packages/ui`, `packages/ui-app`, `packages/ui-subframe`, `packages/ui-mock` werden aggregiert (via Glob in `main.ts`) - [ ] Mindestens 20 Initial-Stories für Kern-Komponenten vorhanden im CSF-3-Format - [ ] Toolbar-Globals `theme`, `brand`, `ui-layer` funktionieren und tauschen visuell den Rendering-Layer - [ ] Add-ons `addon-a11y`, `addon-interactions`, `addon-themes`, `addon-docs` aktiv und konfiguriert - [ ] `pnpm --filter @toolctrl/storybook test:storybook` (Test-Runner) grün - [ ] A11y-Gate aktiv: 0 violations in allen Stories außer explizit ausgenommen - [ ] Lost-Pixel-Baseline für alle 20 Stories committed; CI-Job validiert - [ ] Storybook-Static-Build erfolgreich; CI-Deploy auf `storybook.staging.toolctrl.de` live - [ ] `docs/contributing/storybook.md` mit Quickstart + Story-Writing-Guide - [ ] `docs/design/component-inventory.md` mit Komponenten-Tabelle (Layer/Status) - [ ] `apps/storybook/.storybook/intro.mdx` Landing-Page - [ ] `pnpm lint`, `pnpm typecheck` grün - [ ] Detail-MD Progress Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy Storybook ist isoliert und beeinflusst nichts Produktives: - `git revert ` der `#62`-Commits → `apps/storybook/` verschwindet, Stories in den Packages bleiben (entweder mitrevertieren oder ignorieren — Stories sind harmlos) - CI-Workflows revertieren wenn Storybook-Tests grundsätzlich Probleme machen - Coolify-Static-Site stoppen via Coolify-UI; DNS-Record optional zurück - Lost-Pixel-Baseline kann gelöscht werden ohne Konsequenz - Stories selbst beeinflussen keinen Production-Bundle (sie werden nur in Storybook-Build inkludiert) ## Security Notes - **Storybook-Hosting:** Storybook-Static-Site ist **Public** unter `storybook.staging.toolctrl.de` → darf **keine** echten Tenant-Daten enthalten. Stories nutzen ausschließlich Fixtures/Mocks aus `packages/ui-mock` - **Mock-Daten-Review:** Vor Initial-Deploy alle Stories durchgehen ob keine versehentlichen Tenant-IDs, Email-Adressen, API-Keys aus Realdaten kopiert wurden - **CSP-Konflikte:** Storybook-Iframes brauchen relaxed CSP. Storybook-Site läuft auf eigener Subdomain mit eigener CSP (nicht Production-CSP) - **A11y-Gate ist Sicherheitsrelevant:** WCAG-Konformität ist Compliance-Pflicht (siehe Phase 10 wcag-internal); A11y-Gate hier verhindert dass A11y-Regressionen ungesehen mergen - **Bundle-Size-Beobachtung:** Storybook-Build kann groß werden (~50MB); CI-Step prüft `storybook-static` < 100MB sonst Warning - **CI-Secrets:** Storybook-Deploy braucht Coolify-API-Token in CI-Secrets; getrennt von Production-Deploy-Token - **Visual-Regression-Bypass:** Lost-Pixel-Diff darf nicht via Force-Merge umgangen werden ohne Approval — Branch-Protection enforced ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Detail-MD + Stichproben aus `packages/ui/src/components/` und `packages/ui-app/src/components/` als Input — soll die finale 20-Komponenten-Liste validieren - **Research:** `Explore`-Subagent mit Auftrag „suche existierende Komponenten in `packages/ui-mock`, identifiziere Re-Use-Potenzial für Story-Fixtures" - **Implementation:** Ein `general-purpose`-Subagent pro Story-Block (4, 5, 6 jeweils ein Subagent); Decorator-Setup (Step 2-3) als eigener Subagent - **Tests:** Separater `general-purpose`-Subagent für Test-Runner-Setup + A11y-Gate-Config - **Visual-Regression:** `general-purpose`-Subagent mit Lost-Pixel-Doku als Brief; Baseline-Generierung als initialer Lauf - **Verification:** `gsd-verifier` prüft Acceptance-Criteria-Checkliste; Story-Coverage-Audit-Script ausführen - **Code-Review:** `gsd-code-reviewer` nach Schritt 10, Fokus auf Mock-Daten-Sauberkeit und A11y-Gate-Strenge ## Staging-Deployment-Steps 1. Branch `agent/08-storybook` pushen 2. CI baut Storybook + lädt Static-Output als Artifact hoch 3. Coolify-Static-Site für `storybook.staging.toolctrl.de`: ```yaml # docker-compose.staging.yml-Snippet (oder Coolify-Service) storybook: image: nginx:alpine restart: unless-stopped volumes: - ./storybook-static:/usr/share/nginx/html:ro labels: - "traefik.enable=true" - "traefik.http.routers.storybook.rule=Host(`storybook.staging.toolctrl.de`)" - "traefik.http.routers.storybook.tls.certresolver=letsencrypt" ``` 4. Bei Push auf `agent/08-storybook` Auto-Deploy via Coolify-Webhook 5. Smoke-Test: ```bash curl -I https://storybook.staging.toolctrl.de # erwartet: 200 OK curl -s https://storybook.staging.toolctrl.de/index.html | grep -q "Storybook" ``` 6. Test-Runner gegen Static-Site: ```bash npx playwright install chromium npx @storybook/test-runner --url https://storybook.staging.toolctrl.de ``` 7. Lost-Pixel-Baseline-Generierung initial: `pnpm lost-pixel update` auf Staging, Output ins Repo committen ## Deviations from Plan _(Wird vom ausführenden Agent während Implementation gefüllt, falls Abweichungen)_ ## Progress Log - 2026-05-17 — `ac19ae25` — Scaffold `apps/storybook/` with Storybook 8.6.x + `@storybook/react-vite` + a11y/themes/interactions/essentials addons; minimal preview.tsx with `withThemeByClassName` decorator; preview.css carrying token-CSS variables; tsconfig; README; MDX Introduction page. - 2026-05-17 — `cd197524` — Add CSF-3 stories for **Button** (5 variants + 3 sizes + loading/disabled), **Input**, **Textarea**, **Select** (single + multi); style-only demo primitives co-located in `packages/ui/src/stories/_demo-primitives.tsx` (i18n-guard whitelisted path). - 2026-05-17 — `1d8dd5c3` — Add CSF-3 stories for **Checkbox** (single + group), **Radio**, **Switch**, **Card** (header+content+footer composition). - 2026-05-17 — `543825a1` — Add CSF-3 stories for **Dialog** (basic, destructive-confirm, always-open) and **Form** (contact form + read-only field list). - 2026-05-17 — `6aecf4e0` — Add stories for **Badge** (5 tones), **Avatar** (initials + size scale), **Table** (basic + sortable header + empty). - 2026-05-17 — `89e5eaa0` — Add stories for **Sidebar** (expanded, collapsed, side-by-side) and **Tabs** (three + many). - 2026-05-17 — `f53f9167` — Add stories for **EmptyState** (no-data, no-results, error), **LoadingState** (skeleton card, inline spinner, table loading), and **Toast** (success, error, info, interactive trigger). - 2026-05-17 — `219b8472` — Add stories for **Tooltip** (button + icon), **Popover** (menu + filter), and **DataTable** (filter toolbar + pagination over 10-row dataset). - 2026-05-17 — `ac1bbe2a` / `a9ebf446` — Add Theme Guide MDX page listing CSS-variable tokens; lowercase MDX titles after i18n-guard drift detection. - 2026-05-17 — `c54dce6b` — Add `.github/workflows/storybook.yml` + `.gitea/workflows/storybook.yml` that build the static Storybook and upload it as a 14-day retention artifact on PRs that touch `apps/storybook/` or `packages/ui*/src/stories/`. Main CI Quality-Gates job unchanged. - 2026-05-17 — `7094938a` — Add `docs/architecture/storybook.md` with quickstart, CSF-3 conventions, theme/a11y guidance, CI contract, and visual-regression follow-up pointers. - 2026-05-17 — PROGRESS.md status row updated to `in_progress (21/20 component stories + build path, a11y/visual-regression/test-runner deferred)`. - 2026-05-20 — Ship `@storybook/test-runner` + axe-playwright wiring (`.storybook/test-runner.ts`). New `test:storybook` npm script. Both CI workflows gain a second job that downloads the built static site, http-serves it, installs Playwright Chromium, and gates the PR on any axe violation under the WCAG-2.2-AA ruleset Stories already declare in `preview.tsx`. Per-story `parameters.a11y.disable = true` opt-outs honored (with code-comment justification). Architecture doc updated with local + CI run instructions. Closes the test-runner + a11y-gate Deviations. - 2026-05-20 — Scaffold Lost-Pixel visual-regression: `apps/storybook/lostpixel.config.ts` (storybook-shot mode against the static build, 0.1 % pixel-diff threshold, in-repo baseline under `.lostpixel/baseline/`), `visual-regression` + `visual-regression:update` npm scripts, `lost-pixel` devDep. Both CI workflows gain a third `visual-regression` job that is **baseline-gated** — it self-skips with a notice until an operator runs `visual-regression:update` and commits the baseline PNGs, so CI stays green until opt-in. `.lostpixel/current` + `.lostpixel/difference` git-ignored; diff PNGs uploaded as a `lost-pixel-diff` artifact on failure. Closes the Lost-Pixel Deviation (operator bootstrap step pending). Remaining deferred: brand/ui-layer toolbar globals, real Tailwind-v4 preview pipeline, Coolify static-deploy. - 2026-05-25 — `76732977` — Task F #1/3 (toolbar globals + i18n decorator). `locale` registered as a `globalTypes` toolbar entry (en/de + ar RTL preview); the existing `withThemeByClassName` keeps owning the `theme` global so we don't double-register a toolbar item. New `apps/storybook/.storybook/i18n.ts` builds a real `react-i18next` instance seeded from `apps/web/public/locales/**` via `import.meta.glob`; the locale decorator wraps every story in `` and switches language via `setStorybookLocale`. Unit test `apps/storybook/.storybook/i18n.test.ts` (3 cases) locks in resource-bundle loading, language flips, and the unknown-locale fallback. Adds `i18next`, `react-i18next`, `@tailwindcss/vite`, `tailwindcss` as devDeps (last two used by the follow-up commit). - 2026-05-25 — `24ee3bd9` — Task F #2/3 (Tailwind v4 preview pipeline). `.storybook/main.ts` gains a `viteFinal` hook that merges in `@tailwindcss/vite`; `.storybook/preview.css` now `@import "tailwindcss"` plus the `@custom-variant dark` rule that mirrors `apps/web/app/globals.css`. The existing CSS-variable token block is kept verbatim so the 21 in-flight demo-primitive stories stay visually stable — the static build now emits a Tailwind-v4 theme layer (`--font-sans`, `--spacing`, etc.) ready for stories that import real `packages/ui` / `apps/web` components. - 2026-05-25 — Task F #3/3 (Lost-Pixel baselines). Ran `pnpm --filter @toolctrl/storybook visual-regression:update` against the built static Storybook (with the new Tailwind + i18n pipelines active). 67 baseline PNGs committed under `apps/storybook/.lostpixel/baseline/` (~800kB total). Subsequent `visual-regression` run (no `--update`) reports 67/67 stories with no difference — baseline is internally consistent. Operator bootstrap blocker required a one-time `playwright-core@1.60.0 install chromium-headless-shell` (the shipped Playwright pin downloads CFT v1223); documented for future operators in the storybook architecture doc. - 2026-05-26 — Real-component migration (first wave: 6 of 21). `.storybook/preview.css` extended with the apps/web HSL token block (`--background`/`--foreground`/`--primary`/...) plus the `@theme inline` mapping so shadcn utility classes (`bg-primary`, `text-foreground`, `border-input`) resolve against the same surface as the real app. `.storybook/main.ts` adds a `~` Vite alias pointing at `apps/web/app/`, and apps/storybook gains `clsx`, `tailwind-merge`, `class-variance-authority`, `@radix-ui/react-slot`, `@radix-ui/react-avatar` as devDeps. Six story files migrated from `_demo-primitives.tsx` to real apps/web components: **Button**, **Card**, **Badge**, **Avatar**, **Input**, **Textarea**. Lost-Pixel baselines regenerated (67 → 70 baselines after new Secondary/SemanticColors/WithImage stories landed; legacy demo-primitive stories also shifted because the legacy `--color-primary`/`--color-destructive`/`--color-accent`/`--color-card` block was retired in favour of the shared `@theme inline` mapping — colours now match the real app, no broken layouts). Subsequent `visual-regression` run reports 70/70 no-diff. Remaining 15 stories still on `_demo-primitives.tsx` (the Radix-portal-heavy ones: Dialog, Popover, Tooltip, Tabs, Select, Switch, Checkbox, Radio + complex ones: Form, Sidebar, DataTable, Table, Toast, EmptyState, LoadingState). ### Deviations from spec - All 21 stories ship under `packages/ui/src/stories/` rather than being split across `packages/ui-app`, `packages/ui-subframe`, `packages/ui-mock`. Reason: the i18n hardcoded-strings guard whitelists `packages/(...|ui)/` only; stories in other UI packages would trip the historical-baseline drift on user-facing prop literals. Aggregation glob in `main.ts` already covers the other three packages so a future widening of the i18n guard unlocks distributed stories without further Storybook changes. - Stories originally used **self-contained style-only React components** (`_demo-primitives.tsx`) rather than importing the real `apps/web/app/components/ui/*` components. Reason: the real components rely on Tailwind v4 + the apps/web build pipeline; pulling them into Storybook would double the build dependency graph and we lacked a clean Vite-side Tailwind-v4 + React-19 + Storybook-8 integration to verify. **Partial follow-up landed 2026-05-26** — 6 of the 21 stories (Button, Card, Badge, Avatar, Input, Textarea) now import the real shadcn components via a new `~` Vite alias + the apps/web HSL token block in `preview.css`. The remaining 15 stories still target the demo primitives; migrating them needs Radix portal wiring (Dialog/Popover/Tooltip/Select/Tabs/Switch/Checkbox/Radio) and resolution of deeper apps/web dependency chains (Form/Sidebar/DataTable/Table/Toast/EmptyState/LoadingState). - ~~**`@storybook/test-runner` + A11y-gate CI job**~~ — **resolved 2026-05-20**: test-runner config + new `test-storybook` CI job that gates PRs on axe violations under the WCAG-2.2-AA ruleset. - ~~**Lost-Pixel visual-regression**~~ — **resolved 2026-05-25**: scaffold landed 2026-05-20 (`lostpixel.config.ts` + CI job); baselines generated and committed 2026-05-25 (`d370c5a3` — 67 PNGs covering every story state). The `visual-regression` job is now active gating. - ~~**Real Tailwind-v4 preview pipeline**~~ — **resolved 2026-05-25** (`24ee3bd9`): `@tailwindcss/vite` wired via `viteFinal`; preview.css `@import "tailwindcss"` + `@custom-variant dark` mirroring apps/web. Existing demo-primitive stories unchanged; future stories can import real components. - ~~**i18n locale decorator (functional)**~~ — **resolved 2026-05-25** (`76732977`): locale toolbar global now drives a real i18next instance seeded from apps/web/public/locales, not just html attributes. - **Brand / ui-layer toolbar globals**, **Coolify static-deploy** still deferred — explicit follow-up items (no story today exposes a brand or ui-layer surface, so adding those would be no-op decorators). ### Lessons for parallel agents - The i18n hardcoded-strings guard with `historicalBaselineLimits` is **strict** about uppercase user-facing prop literals. When adding new TSX/MDX content under `apps/` or `packages/` outside the whitelisted paths, either keep user-facing prop literals under 9 characters / starting lowercase, or pre-bump the baseline in the same commit. - Concurrent agents pushing on `main` cause frequent `(incorrect old value provided)` rejections; `git pull --rebase` immediately before push is mandatory. Generated Prisma client files (`packages/db/generated/prisma/**`) churn between agents' typecheck hooks — keep them out of your commit via `git stash --include-untracked` before staging. ## Lessons Learned _(Optional, am Ende des Tasks für nachfolgende Tasks)_