• Date: 2026-05-26
• Status: Accepted
• Affects:
  • apps/web/.storybook/ (new) — Storybook config (Vite builder)
  • apps/web/src/**/*.stories.tsx — component stories
  • apps/web/src/stories/Welcome.mdx — overview MDX
  • apps/web/public/storybook/ — built static catalog (gitignored, generated)
  • apps/web/src/app/app/library/page.tsx — iframe указывает на storybook
  • apps/web/public/design-system.html — sunset target
• References: ADR 0020 (Layout Grid), ADR 0021 (30K MAU ceiling)

Context

Текущая ситуация:

• apps/web/public/design-system.html — 4400+ строк handcrafted HTML/CSS/JS catalog компонентов
• Минусы: no auto-generated props tables, no live controls, no a11y checks, no visual regression, hard to maintain in sync с реальным TSX
• /app/library показывает этот HTML через iframe

Industry standard (Stripe, Vercel, Atlassian, Shopify Polaris, Linear, GitHub Primer, Mantine, MUI, Chakra, Geist) — Storybook:

• Каждый компонент имеет Component.stories.tsx рядом с Component.tsx
• Auto-generated docs page per component
• Live controls panel — юзер играет props через UI
• Auto-extracted props table из TypeScript types
• Multiple variants per component (default, hover, dark, mobile)
• A11y addon — accessibility checks per story
• Chromatic integration — visual regression (paid, defer)

Decision

Заменяем design-system.html на Storybook 8 + Vite builder.

Stack:

• storybook@^8.6.18
• @storybook/react-vite@^8.6.18 (Vite builder вместо Webpack — faster, fewer compat issues с Next.js monorepo)
• @storybook/addon-essentials (Controls, Actions, Backgrounds, Viewport, Docs)
• @storybook/addon-interactions (interactive testing)
• @storybook/addon-a11y (accessibility checks)

Build output → apps/web/public/storybook/ (gitignored). Production: CF Pages serves public assets → arnomake.com/storybook/index.html. /app/library iframe указывает на /storybook/index.html.

Key choices

1. Vite builder вместо Webpack/Next.js.

• @storybook/nextjs (Webpack) сломан с Next 14 + pnpm monorepo (Cannot read properties of undefined (reading 'tap'))
• @storybook/react-vite — clean, fast, default for new Storybook projects
• ARNO компоненты которые показываем — pure React, не используют Next-specific features (Image, Router) → Vite OK

2. Build static, embed iframe.

• Storybook builds в public/storybook/ → CF Pages serves through Next.js static export
• Iframe в /app/library указывает на same-origin /storybook/index.html
• Trade-off: bundle size (10-50 MB Storybook output) добавляется в CF Pages deploy. Acceptable для 30K MAU ceiling.

3. Vite builder dev server на :6006 для разработки stories.

• pnpm --filter @arno/web storybook запускает dev mode
• HMR работает для stories edits
• Production build через pnpm build-storybook → static folder

4. Co-locate stories с компонентами.

• Container.tsx + Container.stories.tsx рядом
• Convention: каждый layout-grid component имеет stories
• New component required: .stories.tsx файл с tags ["autodocs"]

5. Tags-based autodocs.

• Каждый meta имеет tags: ["autodocs"] → auto-generated docs page
• Welcome MDX в src/stories/Welcome.mdx — landing page catalog'а

Rejected alternatives

Consequences

Positive

• Auto-generated props tables — нулевая manual writing работа. TypeScript types → catalog
• Live controls panel — попробовать любые props через UI sliders/dropdowns
• Accessibility checks — autoдar onвостроcessability checks для каждой story
• Multiple variants — каждый component имеет default + edge cases visible
• Co-location — stories рядом с components, easy to maintain
• Industry-recognized — onboard nового dev знаком с Storybook → productive за час
• Visual regression ready — Chromatic plug-in готов (paid, $149/mo, defer)
• MDX docs — guidelines / conventions / do-don't живут вместе с code

Negative

• +50 MB devDependencies — Storybook deps weighty
• +10-30 MB CF Pages bundle — built storybook static в public/
• Build time — build-storybook adds ~30 sec to CI
• Maintenance — Storybook major upgrades occasional (8 → 10 в ~год)

Mitigations

• Build-storybook only on demand (не каждый commit), or only on main branch deploys
• Bundle size manageable для CF Pages (free tier 25 MB limit per file, но distributed)
• Storybook lock major version в package.json — controlled upgrades

Implementation

• Install Storybook 8 + Vite builder
• .storybook/main.ts + preview.ts config
• package.json scripts: storybook, build-storybook
• Stories для Layout Grid components (EmptyZone, DropIndicator, InlineEditableText, Container)
• Welcome MDX
• Build static → public/storybook/
• .gitignore storybook output
• /app/library iframe указывает на /storybook/index.html
• CI workflow step build-storybook (deferred — добавить в ci.yml или deploy-test.yml)
• Stories для FALLBACK_LIBRARY components (Button, Input, Title, BgPlate, Token chip — pending DS Components story design)
• Sunset design-system.html после verify (delete file, references)
• Add Chromatic visual regression (deferred, $149/mo, trigger когда team > 1)

Re-evaluation triggers

• Storybook major upgrade (8 → 10) — review compat
• Vite builder breaks на dep update — fallback to Next.js Webpack или Ladle
• Bundle size > 50 MB — separate Storybook deploy (CF Pages preview subdomain)
• Team > 1 contributor — add Chromatic для visual regression
• Need design-token sync с Figma — add Style Dictionary + Tokens Studio
• Component count > 50 — consider grouping (Foundations / Components / Patterns)

References

• ADR 0020 — Layout Grid (components which need catalog entries)
• ADR 0021 — 30K MAU ceiling (justifies CF Pages bundle вместо paid storybook hosting)
• ADR 0022 — Multi-env setup (Storybook builds в каждом env)

Changelog

• 2026-05-26 v1.0: Initial ADR. Storybook installed, 4 stories + Welcome MDX done. Sunset design-system.html pending verify.