Storybook Component Library

You are a Storybook expert who has built component development environments used by large frontend teams to develop, test, and document their UI components. Create a comprehensive Storybook setup for the following project.

Project Details:
Framework: [REACT/VUE/SVELTE/ANGULAR]
Component Library Size: [SMALL/MEDIUM/LARGE]
Styling Approach: [TAILWIND/CSS MODULES/STYLED-COMPONENTS/EMOTION]
Design System: [BUILDING/EXTENDING/DOCUMENTING EXISTING]
Team Size: [NUMBER OF FRONTEND DEVELOPERS]
CI/CD Platform: [GITHUB ACTIONS/GITLAB CI/CIRCLECI]

Section 1 - Storybook Configuration and Architecture:
Define the Storybook configuration starting with the framework-specific builder choosing between Webpack and Vite with justification based on build speed and compatibility requirements. Establish the story file organization deciding between co-locating stories alongside component files or maintaining a separate stories directory with the naming convention for story files and their relationship to component source files. Create the story hierarchy and naming structure using the Component Story Format 3 with title paths that organize stories into logical categories like atoms, molecules, organisms, and page templates creating a navigable sidebar. Specify the global decorators and parameters including theme providers, router context, state management wrappers, and viewport presets that stories need to render correctly. Address the Storybook performance optimization including lazy compilation, reference external docs using MDX, and managing the build time as the number of stories grows.

Section 2 - Story Writing Patterns and Best Practices:
Define the standard story structure using Component Story Format 3 with a meta default export defining the component, args defaults, and argTypes configuration followed by named exports for each story representing a specific component state or variant. Create the args and argTypes configuration patterns including how to define control types for different prop types, how to set up action handlers for callback props, and how to create arg combinations that represent realistic usage scenarios. Establish the story template patterns for components with many variants including the matrix pattern showing all size and color combinations in a single story, the interactive pattern allowing users to toggle all props, and the documentation pattern showing a single well-chosen default with explanation. Specify the composition story patterns for complex components that require specific context like a table row story that renders within a table, a dropdown item that renders within a menu, or a form field that renders within a form with validation state. Address the data management approach for stories including how to create realistic mock data factories, how to share mock data across related stories, and how to use MSW (Mock Service Worker) for stories that depend on API responses.

Section 3 - Addon Ecosystem and Integration:
Define the essential addon stack including controls for interactive prop editing, actions for event logging, viewport for responsive testing, a11y for automated accessibility checking, and docs for auto-generated documentation pages. Create the integration with the design system tool using the Figma addon or design tokens addon that links Storybook stories to their corresponding Figma components enabling designers to navigate from the component library to the design source. Establish the interaction testing addon setup that allows writing test scenarios directly within stories using the play function to simulate user interactions like clicking, typing, and navigating and then asserting on the resulting component state. Specify the visual testing integration connecting Storybook to Chromatic or Percy for automated screenshot comparison that catches visual regressions across all stories on every pull request. Address the custom addon development approach for project-specific needs like theme switching, locale switching, user role simulation, or feature flag toggling that test components under different application contexts.

Section 4 - Documentation with Storybook:
Design the documentation strategy using MDX docs pages that combine narrative documentation with live component examples creating comprehensive component pages that serve as both documentation and interactive playground. Create the auto-generated documentation setup using the autodocs tag that generates props tables from TypeScript interfaces, displays all component stories with source code, and provides a structured overview without manual documentation effort. Establish the design guideline documentation including when to use each component, the dos and donts with side-by-side examples, accessibility requirements, and related component links. Specify the pattern documentation approach showing how to compose multiple components together for common UI patterns with complete code examples that developers can copy and adapt. Address the changelog and migration documentation that helps consumers of the component library understand what changed between versions and how to update their usage.

Section 5 - Testing Integration:
Define the component testing strategy using Storybook stories as the test basis where each story serves as both documentation and a test fixture reducing duplication between stories and test files. Create the interaction testing approach using the play function and the testing library within stories to verify component behavior including form validation, keyboard navigation, dynamic content loading, and state transitions. Establish the accessibility testing integration running axe-core checks on every story automatically and failing the CI build when accessibility violations are detected. Specify the visual regression testing workflow using Chromatic or a custom screenshot comparison tool that captures every story in every supported viewport size and theme combination and compares against approved baselines. Address the smoke testing approach that imports every story file and renders every story to verify none crash, catching import errors, missing providers, and broken component compositions before they reach users.

Section 6 - Build, Deploy, and CI Workflow:
Define the Storybook build optimization for deployment including output compression, static asset handling, and the build-storybook configuration that generates a deployable static site. Create the CI pipeline integration that builds Storybook on every pull request, runs the test suite against stories, publishes a preview deployment for visual review, and deploys the main branch build to a permanent documentation URL. Establish the Storybook review workflow where component changes are reviewed by both developers and designers using the deployed Storybook preview that shows exactly how the component looks in every variant and state. Specify the composition strategy for organizations with multiple Storybook instances across teams or packages using Storybook composition to combine them into a single navigable catalog. Address the maintenance and upgrade approach including how to stay current with Storybook major versions, how to migrate stories when the story format evolves, and how to manage addon compatibility during upgrades.