28 KiB
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) undui-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-Builder01-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.mdprofitiert 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.tsenthä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:
composeStoriesvon@storybook/reactexportiert Stories als testbare React-Komponenten → keine Doppel-Pflege Story vs Component-Test
20 Kern-Komponenten für Initial-Story-Set:
- Button (Variants: default/destructive/outline/ghost/link, sizes: sm/md/lg)
- Input (Text/Email/Password mit Label + Validation-States)
- Textarea
- Select (Single + Multi)
- Checkbox + Radio
- Switch
- Card (Header+Content+Footer Compositions)
- Dialog (Modal, Confirm-Dialog)
- Drawer (Side-Drawer)
- Form-Field (Label + Input + Error-Message-Compound)
- Table (Basic + Sortable Header)
- DataTable (mit Pagination + Filter, aus
ui-app) - Sidebar (collapsed + expanded, aus
ui-app/sidebar) - Avatar (Image + Fallback-Initials)
- Badge (Variants)
- Toast (Success/Error/Info; Sonner-Wrapper)
- Tooltip
- Popover
- Tabs
- EmptyState (illustrated empty placeholder)
Theme-Decorator-Strategie: Toolbar-Globals (Storybook-Standard-Mechanik) für:
theme: light | darkbrand: default | demo-tenant-blue | demo-tenant-orange (read frompackages/brand/themes/)ui-layer: shadcn | subframe (toggle between Komponenten-Implementations wo beide existieren)
Decorator wrappt Story in <BrandProvider> + <ThemeProvider> (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 viaparameters.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 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
-
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 viteinitial; 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
- Files:
-
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
- Files:
-
Add-ons konfigurieren (a11y, interactions, themes, docs)
- Files: Update
apps/storybook/.storybook/main.ts,preview.tsx,apps/storybook/.storybook/a11y-config.ts addon-a11ymit axe-rules-Config (WCAG-2.1-AA als Minimum)addon-interactionsmit Test-Step-Recorder-Setupaddon-themesmitwithThemeByDataAttribute-Decorator für dark/lightaddon-docsmit Auto-MDX-Generation aktiviert- Commit:
08-mobile/storybook: configure a11y, interactions, themes, docs addons
- Files: Update
-
Stories für
packages/ui(Basis-Komponenten 1-10)- Files (alle in
packages/ui/src/components/<name>/<name>.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
- Files (alle in
-
Stories für
packages/ui-app(Composites 11-15)- Files (alle in
packages/ui-app/src/components/<name>/<name>.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.
<TenantProvider>-Mock) → über zusätzliche Decorators pro Story - Commit:
08-mobile/storybook: add stories for 5 ui-app composite components
- Files (alle in
-
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
- Files (mixed packages je nach Implementation):
-
Test-Runner Setup + A11y-Gate
- Files:
apps/storybook/test-runner.config.ts,apps/storybook/package.json(Scripts),.github/workflows/storybook-tests.yml @storybook/test-runnerinstallation; CLI-Scripttest:storybook- A11y-Gate: alle Stories müssen 0 violations haben außer explizit per
parameters.a11y.disable=trueausgeschlossen - 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
- Files:
-
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
- Files:
-
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 unterstorybook.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
- Files:
-
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
- Files:
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=truemit 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-storybookmuss grün durchlaufen, Static-Output existiert inapps/storybook/storybook-static/ - Coverage-Target: N/A für Storybook (Stories sind nicht produktions-Code); aber Story-Coverage-Target: alle Public-Komponenten aus
packages/uimüssen mindestens 1 Story haben (Audit-Test in CI) - Test-Files: Stories co-located bei Components (
<name>.stories.tsx); Decorator-Tests inapps/storybook/.storybook/decorators/<name>.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 undpnpm --filter @toolctrl/storybook devstartet Storybook auf Port 6006- Stories aus
packages/ui,packages/ui-app,packages/ui-subframe,packages/ui-mockwerden aggregiert (via Glob inmain.ts) - Mindestens 20 Initial-Stories für Kern-Komponenten vorhanden im CSF-3-Format
- Toolbar-Globals
theme,brand,ui-layerfunktionieren und tauschen visuell den Rendering-Layer - Add-ons
addon-a11y,addon-interactions,addon-themes,addon-docsaktiv 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.delive docs/contributing/storybook.mdmit Quickstart + Story-Writing-Guidedocs/design/component-inventory.mdmit Komponenten-Tabelle (Layer/Status)apps/storybook/.storybook/intro.mdxLanding-Pagepnpm lint,pnpm typecheckgrün- Detail-MD Progress Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
Storybook ist isoliert und beeinflusst nichts Produktives:
git revert <range>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 auspackages/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 auspackages/ui/src/components/undpackages/ui-app/src/components/als Input — soll die finale 20-Komponenten-Liste validieren - Research:
Explore-Subagent mit Auftrag „suche existierende Komponenten inpackages/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-verifierprüft Acceptance-Criteria-Checkliste; Story-Coverage-Audit-Script ausführen - Code-Review:
gsd-code-reviewernach Schritt 10, Fokus auf Mock-Daten-Sauberkeit und A11y-Gate-Strenge
Staging-Deployment-Steps
- Branch
agent/08-storybookpushen - CI baut Storybook + lädt Static-Output als Artifact hoch
- Coolify-Static-Site für
storybook.staging.toolctrl.de:# 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" - Bei Push auf
agent/08-storybookAuto-Deploy via Coolify-Webhook - Smoke-Test:
curl -I https://storybook.staging.toolctrl.de # erwartet: 200 OK curl -s https://storybook.staging.toolctrl.de/index.html | grep -q "Storybook" - Test-Runner gegen Static-Site:
npx playwright install chromium npx @storybook/test-runner --url https://storybook.staging.toolctrl.de - Lost-Pixel-Baseline-Generierung initial:
pnpm lost-pixel updateauf 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— Scaffoldapps/storybook/with Storybook 8.6.x +@storybook/react-vite+ a11y/themes/interactions/essentials addons; minimal preview.tsx withwithThemeByClassNamedecorator; 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 inpackages/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.ymlthat build the static Storybook and upload it as a 14-day retention artifact on PRs that touchapps/storybook/orpackages/ui*/src/stories/. Main CI Quality-Gates job unchanged. - 2026-05-17 —
7094938a— Adddocs/architecture/storybook.mdwith 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). Newtest:storybooknpm 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 inpreview.tsx. Per-storyparameters.a11y.disable = trueopt-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:updatenpm scripts,lost-pixeldevDep. Both CI workflows gain a thirdvisual-regressionjob that is baseline-gated — it self-skips with a notice until an operator runsvisual-regression:updateand commits the baseline PNGs, so CI stays green until opt-in..lostpixel/current+.lostpixel/differencegit-ignored; diff PNGs uploaded as alost-pixel-diffartifact 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).localeregistered as aglobalTypestoolbar entry (en/de + ar RTL preview); the existingwithThemeByClassNamekeeps owning thethemeglobal so we don't double-register a toolbar item. Newapps/storybook/.storybook/i18n.tsbuilds a realreact-i18nextinstance seeded fromapps/web/public/locales/**viaimport.meta.glob; the locale decorator wraps every story in<I18nextProvider>and switches language viasetStorybookLocale. Unit testapps/storybook/.storybook/i18n.test.ts(3 cases) locks in resource-bundle loading, language flips, and the unknown-locale fallback. Addsi18next,react-i18next,@tailwindcss/vite,tailwindcssas devDeps (last two used by the follow-up commit). - 2026-05-25 —
24ee3bd9— Task F #2/3 (Tailwind v4 preview pipeline)..storybook/main.tsgains aviteFinalhook that merges in@tailwindcss/vite;.storybook/preview.cssnow@import "tailwindcss"plus the@custom-variant darkrule that mirrorsapps/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 realpackages/ui/apps/webcomponents. - 2026-05-25 — Task F #3/3 (Lost-Pixel baselines). Ran
pnpm --filter @toolctrl/storybook visual-regression:updateagainst the built static Storybook (with the new Tailwind + i18n pipelines active). 67 baseline PNGs committed underapps/storybook/.lostpixel/baseline/(~800kB total). Subsequentvisual-regressionrun (no--update) reports 67/67 stories with no difference — baseline is internally consistent. Operator bootstrap blocker required a one-timeplaywright-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.cssextended with the apps/web HSL token block (--background/--foreground/--primary/...) plus the@theme inlinemapping so shadcn utility classes (bg-primary,text-foreground,border-input) resolve against the same surface as the real app..storybook/main.tsadds a~Vite alias pointing atapps/web/app/, and apps/storybook gainsclsx,tailwind-merge,class-variance-authority,@radix-ui/react-slot,@radix-ui/react-avataras devDeps. Six story files migrated from_demo-primitives.tsxto 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-cardblock was retired in favour of the shared@theme inlinemapping — colours now match the real app, no broken layouts). Subsequentvisual-regressionrun 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 acrosspackages/ui-app,packages/ui-subframe,packages/ui-mock. Reason: the i18n hardcoded-strings guard whitelistspackages/(...|ui)/only; stories in other UI packages would trip the historical-baseline drift on user-facing prop literals. Aggregation glob inmain.tsalready 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 realapps/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 inpreview.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). — resolved 2026-05-20: test-runner config + new@storybook/test-runner+ A11y-gate CI jobtest-storybookCI 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). Thevisual-regressionjob is now active gating.Real Tailwind-v4 preview pipeline— resolved 2026-05-25 (24ee3bd9):@tailwindcss/vitewired viaviteFinal; preview.css@import "tailwindcss"+@custom-variant darkmirroring 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
historicalBaselineLimitsis strict about uppercase user-facing prop literals. When adding new TSX/MDX content underapps/orpackages/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
maincause frequent(incorrect old value provided)rejections;git pull --rebaseimmediately before push is mandatory. Generated Prisma client files (packages/db/generated/prisma/**) churn between agents' typecheck hooks — keep them out of your commit viagit stash --include-untrackedbefore staging.
Lessons Learned
(Optional, am Ende des Tasks für nachfolgende Tasks)