feat(design-library): adopt Storybook 10.4 best practices#31197
Conversation
- Disable onboarding checklist (sidebarOnboardingChecklist: false) - Add branded manager.ts theme for professional Storybook UI - Replace custom theme decorator with @storybook/addon-themes - Enable componentsManifest for AI agent support via MCP - Add @storybook/addon-mcp for MCP server integration - Add @storybook/addon-vitest with Playwright for render testing - Add introduction.mdx as the default landing page - Adopt CSF Next API (defineMain/definePreview) for type safety Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
![vex-assistant-bot[bot]](https://avatars.githubusercontent.com/in/3399303?s=60&v=4){kind=small}
There was a problem hiding this comment.
✦ APPROVE
Value: Makes the design library first-class for AI-assisted development — MCP component discovery, automated render testing via Storybook-as-Vitest, and a branded landing page all land together in one clean pass.
What this does: Migrates Storybook config to 10.4 CSF Next API (defineMain/definePreview), replaces the hand-rolled theme decorator with withThemeByDataAttribute, adds three addons (addon-themes, addon-vitest, addon-mcp), wires up Playwright browser render testing, and adds an Introduction MDX landing page.
Per-file
main.ts — CSF Next API migration is correct. defineMain gives full type safety and autocompletion over the old StorybookConfig cast pattern. sidebarOnboardingChecklist: false is a one-liner quality-of-life win. componentsManifest: true generates manifests/components.json inside the built Storybook output (not the source tree), so no .gitignore concern. Addon list is coherent.
manager.ts — Clean branded dark theme. The #E83F5B accent reads as intentional Vellum brand red. showRoots: true in the sidebar is the right default for a multi-component library.
preview.tsx — The withThemeByDataAttribute swap is the right call for docs-mode iframe correctness. One thing worth verifying: the old decorator set data-theme on both document.documentElement and document.body. The addon's default targeting is typically just one of those. If any selector in tokens.css uses body[data-theme="..."] (rather than :root or [data-theme="..."] flat), those won't fire. A quick grep for body\[data-theme in the token files would confirm. Low probability given standard CSS variable patterns, but worth a sanity check.
The addons: [] in definePreview is fine — no preview-side addon config needed since decorators handle theming.
vitest.config.ts — Good setup. storybookTest plugin launching Storybook in background for browser tests is the canonical pattern. The CI Test check passed green, so Playwright/Chromium is handled. headless: true and chromium instance are correct defaults.
vitest.setup.ts — Single-line internal setup import. Correct.
introduction.mdx — Accurate install instructions, token import guidance, and theming docs. Links to AGENTS.md for contributor conventions. No issues.
package.json / bun.lock — Version pins are consistent (vitest@4.1.6, @vitest/browser@4.1.6, playwright@1.60.0). Lockfile changes are expected for this dep footprint.
Anti-pattern check
- No React anti-patterns apply (Storybook config is not component code)
- No Zustand, no hooks, no async effects
- No iOS/Capacitor surface touched
Merge gate
- ✅ Vex approved
- ✅ Devin: "No Issues Found" at HEAD
962b1b7c - ✅ 14/14 CI checks passing (Lint, Type Check, Test, FlexFrame, Socket, OpenAPI all green)
- ✅ Single clean commit,
mergeable_state: blockedonly due to pending second approval
Vellum Constitution — Inviting: surfacing design components to AI tools via MCP makes the design system accessible to every contributor's coding agent, lowering the barrier to building on-brand UI.
- Fix introduction.mdx to import Meta from @storybook/addon-docs/blocks (not @storybook/blocks which doesn't exist in 10.4) - Add docsAddon() and a11yAddon() to definePreview addons array so the docs renderer is properly configured for MDX page rendering Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai>
devin-ai-integration
Bot
dismissed
vex-assistant-bot[bot]’s stale review
via
51f8665
…n README - Switch Storybook manager theme from dark to light, using actual design system token values (surface-base, content-default, border-base, etc.) - Add Testing section to README documenting bun run test (Vitest render tests) - Add MCP section to README explaining AI agent integration via addon-mcp Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai>
Adds a dedicated CI workflow that runs on packages/design-library/** changes. It installs Playwright Chromium and runs the Vitest render tests (every story rendered in a real browser) plus type-checking. Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai>
… browser setup (#31205) * fix(design-library): add postinstall script for Playwright browser setup The @storybook/addon-vitest added in #31197 requires Playwright's Chromium browser binaries to power both the CLI test runner and the in-UI testing widget. The CI workflow correctly installs them, but the local dev path was missing this step — causing a noisy 'Failed to initialize Vitest' error on storybook dev startup. Add a postinstall script that runs 'playwright install chromium' after bun install. Since the design library is a standalone package (not a workspace member), this only affects developers who explicitly install deps in packages/design-library/. Playwright caches binaries so subsequent installs are fast no-ops. Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai> * fix(design-library): use @playwright/browser-chromium for declarative browser setup Replace the custom postinstall script with Playwright's official @playwright/browser-chromium package, which auto-downloads Chromium via its install hook. This is the mechanism Playwright introduced in v1.38 (microsoft/playwright#26672) specifically so browser downloads are opt-in and declarative rather than imperative scripts. Added to trustedDependencies so bun runs the package's install script (@playwright/browser-chromium is not in bun's default allowlist). Co-Authored-By: ashlee@vellum.ai <ashlee@vellum.ai> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
1 participant
Prompt / plan
Audit design-library Storybook setup against 10.4 best practices and implement all recommended improvements. Fixes the default About/Get Started landing page and modernizes the configuration for an open-source design library.
What
sidebarOnboardingChecklist: false(docs)manager.tswith design system tokens (theming docs)@storybook/addon-themes— replaces hand-rolled theme decorator withwithThemeByDataAttribute(addon docs)@storybook/addon-mcp+componentsManifest— AI agent discovery for OSS consumers (addon-mcp)@storybook/addon-vitest— every story becomes a render test in Playwright Chromium (vitest addon docs)defineMain/definePreviewfactory functions for type safety (CSF Next docs)pr-design-library.yamlruns type-check + Vitest render tests onpackages/design-library/**changesAll changes are additive. No component code modified. No breaking changes.
Test plan
bunx tsc --noEmitpasses (zero errors)Link to Devin session: https://app.devin.ai/sessions/4f4a398343124a388e15b81f589a9e79
Requested by: @ashleeradka