Your product has buttons, modals, cards, and dozens of other components scattered across the codebase — but nobody knows exactly what exists or where it lives. No component inventory. No visual documentation. No single source of truth for your UI.
We've been running into this exact problem with clients who've been shipping fast for months (sometimes years) without ever formalizing their component library. The result is duplicated components, inconsistent patterns, and a design-to-dev handoff that feels like archaeology. The good news: you can fix this in a day with Claude Code and Storybook, and I'm going to walk you through exactly how we did it.
In this guide, I'll break down how to go from zero to a working Storybook component library using AI. We'll cover the full process — from pulling documentation, to auditing every component in the codebase, to building and troubleshooting individual stories, to creating a repeatable system that gets faster the more you use it.
Table of contents:
- What is a Storybook component library (and why build one now)?
- The three-phase approach
- Phase 1: Set up Storybook infrastructure
- Phase 2: Audit and catalog every component
- Phase 3: Build stories one component at a time
- Troubleshooting: when components don't match production
- Building a repeatable process
- Scaling up: from one-by-one to batches
What is a Storybook component library (and why build one now)?
A Storybook component library is a living catalog of every UI component in your product — rendered in isolation, with all its variants, states, and props documented visually. Instead of hunting through code to figure out what a button looks like when it's disabled, loading, or in its hover state, you open Storybook and see everything at a glance.
If your startup has been shipping for 6+ months and you still don't have one, you're probably already feeling the pain: designers recreating components that already exist in code, engineers building slightly different versions of the same card, and nobody quite sure which variant is the "right" one.
The traditional approach — manually auditing every file and hand-writing stories — takes weeks. We've been using Claude Code to compress that into a single day.
The three-phase approach
The process breaks into three clean phases:
- Set up Storybook infrastructure — install dependencies, configure the environment
- Catalog all components — audit the entire codebase and document what exists
- Implement stories one at a time — build, verify, and refine each component
The critical insight here: do not try to build all your component stories at once. We've tried that approach, and the components don't translate perfectly. Going page by page and component by component means you catch problems early and build institutional knowledge about your own design system as you go.
For this walkthrough, I used cal.com's open source repo as the example — a production codebase with 50+ UI components.
Phase 1: Set up Storybook infrastructure {#phase-1}
Start by giving Claude Code the full context it needs. Before writing a single line of config, I use Context7 — an MCP that pulls up-to-date documentation on any library or framework directly into your AI coding session. This matters because Storybook's API changes frequently, and you don't want Claude working from outdated patterns.
The prompt is straightforward:
> Use Context7 to understand how to build out a Storybook component library.
I always run this in plan mode. Plan mode forces Claude Code to lay out the full approach before touching any files, which means you can course-correct before any code gets written. It's the best way to work with Claude Code on anything non-trivial.
From here, Claude Code installs Storybook dependencies, creates the config files, sets up mock files, and scaffolds the package structure. It even runs tasks in parallel where possible, which speeds things up considerably.
Once the build succeeds and you can open Storybook in the browser (even though it's empty), phase one is done.
Phase 2: Audit and catalog every component {#phase-2}
This is where things get interesting. Instead of manually hunting through the codebase, ask Claude Code to do a comprehensive audit.
Here's the prompt I used:
> You are a world-class CTO. I want to get documentation of all the components in the product. Break them down by global and page views. List them out in an easy and understandable way.
Claude Code will ask clarifying questions — where to store the catalog, how much detail per component, etc. For cal.com, I had it create a single markdown file organized into two sections: global components and page-specific views.
What came back was a full inventory with paths and complexity ratings:
- 17 simple components (buttons, badges, icons)
- 20 medium components (modals, dropdowns, form fields)
- 7 complex components (calendar views, event type builders)
Each page view also got its own section listing the unique components on that page versus the shared globals. This catalog becomes the roadmap for phase three — and it doubles as living documentation for the engineering team.
Claude Code also added Storybook coverage tracking, so you can see at a glance which components have stories and which still need them.
Phase 3: Build stories one component at a time {#phase-3}
Here's where the discipline matters. Start with one page, pick the highest-priority component, and build it properly before moving on.
I started with the event types page and asked Claude Code to pull the relevant components from the catalog:
> I want to start building components from the event type page. List out all the components on the event type page. Pull from the component catalog.
Claude Code identified the internal view components and the unique globals, then ranked them by priority. The button was the natural starting point — it's used everywhere and has the most variants.
For each component, Claude Code:
- Pulls the actual component source code
- Identifies all props, variants, and states
- Extracts the design tokens in use
- Writes the Storybook story with full prop coverage
- Builds and verifies the story compiles
The first component will be the slowest. That's expected and that's okay.
Troubleshooting: when components don't match production
The button story compiled on the first try — but when I checked it in the browser, the primary button's hover state wasn't showing up. The secondary and minimal variants had working hovers. Primary didn't.
This is exactly why you build one at a time. If I'd batch-built 50 components, I might not have caught this for weeks.
Here's the troubleshooting workflow that worked:
Step 1: Let Claude Code see the problem itself. Instead of describing the error, I asked Claude Code to open the page using Playwright and compare the production button with the Storybook version. When it actually renders the page and takes screenshots, it catches things you'd struggle to describe in a prompt.
Step 2: Dig into the CSS. Claude Code identified the root cause: the hover styles were wrapped in @media (hover: hover) — a Tailwind v4 feature that only applies hover states on devices that support hover input. Storybook's rendering context handled this differently than the production app.
Step 3: Check the token layer. The deeper issue was a token environment mismatch. Storybook was using default design tokens, but the production platform had custom brand colors. The component wasn't built in a way that cleanly separated its token dependencies.
This is a common finding when you audit an existing codebase — and it's incredibly valuable. You're not just building a component library; you're surfacing architectural debt that the team should know about.
Claude Code resolved it with targeted CSS overrides in the Storybook config. Not ideal long-term, but functional — and the real fix (rebuilding the component's token layer) became a documented conversation for the engineering team.
Building a repeatable process
After the button took longer than expected, I asked Claude Code a simple question:
> There was a lot of back and forth and troubleshooting. How can we build in a process for the next component to make sure we check everything and the output is closer to perfect on the first go?
This is a pattern I use constantly with Claude Code: when something doesn't work well, ask why, ask what we can do better, and save that knowledge so we don't repeat the problem.
Claude Code produced a Storybook Development Guide — a checklist committed directly to the repo next to the Storybook config. It covers:
- Understand the component before writing any code — read the source, identify all props and variants, check for custom tokens
- Check the Storybook environment — verify token availability, confirm CSS context matches production
- Write the stories — cover every variant, state, and edge case
- Verify before declaring done — visual cross-check against production, hover/focus/active states, responsive behavior
The token mismatch issue was explicitly called out as a known gotcha. Future components get checked against it automatically.
Scaling up: from one-by-one to batches
Here's the payoff of the one-at-a-time approach: after building three to four components, you've accumulated enough knowledge about the component library's structure, token system, and quirks that you can start batching.
The progression looks like this:
- Component 1: Slow. Lots of troubleshooting. Build the process.
- Component 2-3: Faster. The checklist catches issues early.
- Component 4+: You can start saying "build these 10 components, follow all the documentation, and make sure we don't run into any of the errors we've already solved."
Claude Code references the development guide, the component catalog, and the coverage tracker — and starts producing stories at a much higher hit rate.
One more thing worth noting: the component descriptions you write during this process have compounding value. When you document when and why to use each component, Claude Code can later use that knowledge to correctly select components when building new pages. A well-described component library doesn't just help designers — it makes your AI tooling smarter.
Getting started
If you want to try this yourself, here's the minimum you need:
- Claude Code — the AI coding agent driving the workflow
- Context7 — MCP for pulling up-to-date library documentation into Claude Code
- Storybook — the component library framework
- Playwright — for visual verification and troubleshooting (Claude Code uses this to actually look at your pages)
Start with whatever codebase you have. You don't need a Figma component library set up first — in fact, this is a great way to figure out what components actually exist before you formalize anything in design.
If your team is spending more time reverse-engineering your own UI than shipping new features, that's exactly what we help with at TDP. We convert Figma designs into production-ready code and help teams build the systems that make future development faster.
Want help building out your component library? We have openings for teams looking to formalize their design systems. Reach out and let's talk about your design challenges.
