Storybook for Designers

A fair question before you commit. Designers already live in Figma and can already open the staging URL. What does Storybook add?

• Figma is where designs originate. Source of truth for what you want the product to become.
• Storybook is where designs are verified against what the engineering team actually built. Same component, isolated from content and routing, so you can see whether the built thing matches the drawn thing.
• The staging site is where everything is verified against real content and user flow. That's where copy issues, real-data edge cases, and SEO regressions surface - things Storybook deliberately can't catch.

You won't stop using Figma. You won't stop opening the staging site. Storybook sits in the middle, and its job is to close the Figma-to-code loop without waiting for a Friday QA session.

Two ways, pick whichever fits your week.

Option A - the deployed URL

If the team has already deployed Storybook (Vercel preview, Chromatic, or another host), a developer will share the link. Open it, you're in. No install, no terminal, nothing to maintain. This is the default for quick reviews.

Option B - run it locally

If you can already run the site locally, one more terminal command gets you Storybook:

1. Open a terminal inside the project folder.
2. Type npm run storybook and press Enter.
3. Wait about 15 seconds. A browser tab opens automatically at http://localhost:6006.
4. When you're done, return to the terminal and press Ctrl + C to stop it.

Running locally is slower to start but gives you live reload - if a developer fixes something, the tab updates within a second or two.

Three zones do all the work:

• Sidebar (left) - the navigation tree. Top-level folders group stories by category. Click a folder to expand; click a component to expand its variants.
• Preview (center) - the actual render. Whatever story you clicked is running here at full fidelity.
• Addon panel (bottom) - context-dependent tools. Controls lets you change props live, Accessibility runs a full axe audit, there are tabs for Actions, Interactions, and Visual Tests too.

There's also a toolbar across the top of the preview with icons for viewport size, background swap, zoom, measure, and grid overlay. You'll use the viewport picker most.

The sidebar mirrors how a website is built: the smallest pieces at the top, full page compositions at the bottom. Every Storybook you'll encounter uses some version of this hierarchy, though the exact folder names will differ by team.

On ours you'll also see folders for Animations, Layout, and service-specific heroes; other teams split their tree differently. The idea is always “small-to-large”: anything you can't find at one level, look for at the level above or below.

Don't try to click through every story in one sitting. Use the search bar at the top of the sidebar to jump to anything by name, and let the tree teach itself as you work.

Pick a component, click into its variants, change props, repeat. Start with Button to see the pattern.

Each component folder in the sidebar exposes its variants as stories. Click one (say, Primary) and the preview shows that specific configuration. In the bottom panel, the Controls tab lets you change props live without touching code:

The workflow for reviewing a component:

1. Click the component in the sidebar to expand its variants.
2. Click a specific variant (e.g. Default, Primary, Outline, With Leading Icon).
3. Scroll through the preview; if it's a sized component, change the viewport from the toolbar.
4. Open Controls in the bottom panel to stress-test edge cases - long text, disabled states, odd combinations.
5. If you find something off, leave a comment in Slack with the story URL, or flag it to the dev team directly.

Some stories are rendered as a set piece rather than a controllable prop bundle. You'll see “Controls not available” on those - it's intentional. Switch to the Default story if you want live controls.

This is the feature most designers end up using daily. Click the Pages folder, pick a page, and the entire composition renders - the same sections, in the same order, wrapped in the same Header and Footer as production.

Three things to understand about page stories:

• What you see is what ships. A well-written page story imports the same component that the production route renders. When a developer updates the homepage layout, the Storybook story updates with it. There is no separate Storybook-only version of a page to fall out of sync. (If a team's Storybook uses a hand-rolled copy of a page instead, call it out - that's a drift bug waiting to happen.)
• Content is mocked, layout is real. Blog posts, testimonials, and case studies shown in page stories are sample data - the real copy lives in a CMS or markdown files the Storybook doesn't mount. Spacing, typography, responsive behavior, header-scroll interactions - those are exactly production.
• Chrome is usually included. Good page stories render the site header and footer around the page body, so you're reviewing the page in context rather than floating without nav. On our site this is wired automatically via a shared decorator; other teams use a layout wrapper. Either works.

Most Storybooks include a tokens reference - brand colors, typography scale, spacing, radii. On ours it's at Design System / Tokens. The swatches are rendered from the live CSS variables the rest of the site uses, so the page isn't documentation of the design system. It is the design system, rendered.

That means:

• Before asking “what's the exact brand blue?” - open Tokens and look.
• Before filing a bug for “this button looks wrong” - check Tokens first. If the Tokens swatch is the color you expect, the component has a bug. If the Tokens swatch is also wrong, the token has shifted and that's a different conversation.
• Tokens pages usually list both the brand-facing name (Primary / Accent / Dark) and the engineering identifier (the CSS variable, the Tailwind utility class). Those identifiers make change requests faster - “update --primary to #3e2df5” is unambiguous in a way that “make it a bit more blue” isn't.

Across the top of the preview:

• Backgrounds - swap between white, subtle, and dark backgrounds. Catches components that assume a specific canvas color.
• Viewport - mobile, tablet, and desktop presets, or type in a custom width. Test responsive behavior without resizing the browser window.
• Zoom - pixel-level inspection. Useful when you're checking border radii or icon alignment.
• Measure - overlay a ruler. Click-drag to measure any distance on the preview.
• Grid / Outline - toggle a grid overlay or outline every element. Alignment bugs become obvious.
• Vision filter - simulate color-blindness (deuteranopia, protanopia, tritanopia, achromatopsia). One click to see whether the page still reads when users can't distinguish the hues you chose.

Every story runs through axe automatically. Click the Accessibility tab in the bottom panel to see the audit.

Three sub-tabs under Accessibility:

• Violations - definite problems. Every entry is rated Critical, Serious, Moderate, or Minor. If you're reviewing a page and see a Serious violation, flag it.
• Passes - checks that passed. Useful for confidence, less useful for action.
• Inconclusive - axe couldn't decide automatically. These require manual review, usually screen-reader testing.

For design review, focus on color contrast violations (text or icons that don't meet WCAG ratios against their background) and heading order violations (skipping from H1 to H3 without an H2 in between). Most of the time, they're real and worth fixing.

Set the viewport picker to Mobile (or any preset) and the preview resizes instantly. Here's a card grid - three across on desktop, stacked to a single column on a 320×568 mobile viewport:

A handful of components are deliberately mobile-only or desktop-only. If a component appears blank on desktop, check the story description - it probably expects a mobile viewport, and the default story is configured accordingly.

Habit to keep: for any component that'll appear on mobile in production, flip between mobile and desktop viewports once. Five seconds, catches a lot.

When you spot something - a tight spacing, an off-brand color, a heading that feels off - two good paths.

Option 1 - share the story URL

Every story has its own URL. Copy it from the browser address bar and paste it into Slack or email with a one-line note:

“In Sections / Home / Hero, the subtitle is set smaller than the supporting copy on the About page. Intentional? If not, can we match 16px?”

The developer opens the exact same URL, sees the exact same render, and has zero ambiguity about what you were looking at. Ten seconds from your side, saves the “which page are you on?” thread.

Option 2 - use Claude Code yourself

If you're set up with Claude Code (the Claude Code for Designers series walks through the full workflow), describe the change in plain English and let Claude edit the component. Refresh Storybook and the fix is there:

“In the Hero story, bump the subtitle font size to 16px and make it a shade darker - match the About page.”

Good fit for small visual tweaks. Less good for anything that affects multiple components at once - for those, loop in a developer.

What makes a good change request

• Point at a specific story. “The Hero” means six things; Sections / Home / Hero subtitle means one.
• Say what you want, not just what's wrong. “This feels off” is hard to act on. “The subtitle should be 16px and match the About body text weight” is a ticket.
• Include the story URL. Saves at least one round-trip.
• If it's a token-level change (“the brand blue should be darker”), say that explicitly - it's a different kind of fix than a one-component tweak.

“I want to preview the whole homepage.”

Open Pages / Home. Scroll.

“I want to compare every button variant side by side.”

Open Design System / Button / All Variants.

“I want to check a component on mobile.”

Open the component, flip the Viewport toolbar to Mobile.

“What's the exact brand color again?”

Design System / Tokens.

“I'm about to redesign the blog post page.”

Open Pages / Blog Post and use the current version as reference. Add comments on the story URL as you go.

“I want to compare all the service heroes.”

Expand Sections / Service Heroes in the sidebar. Click through each. Good for catching inconsistency across a set.

Worth knowing what it isn't, so you don't debug the wrong thing:

• It doesn't load real site content. Blog posts, case studies, and testimonials in stories are mocked. The real copy lives in markdown files or a CMS the Storybook doesn't mount.
• Forms don't submit anywhere. The contact form renders and validates client-side, but submitting it in Storybook does nothing - the API isn't connected.
• No SEO metadata. Page titles, meta descriptions, and sitemaps aren't part of visual review. They live in the real page files and get audited through different tools.
• No analytics. No tracking fires inside Storybook. You won't accidentally log events by clicking around.
• It's not a replacement for the real site. For final review of copy, data, and SEO, open the staging URL and navigate normally. Storybook is a design workspace, not a staging environment.

“The component looks broken or unstyled.”

Refresh the page. If it persists, the CSS may have failed to load - tell a developer. This is rare, usually a cache hiccup.

“I can't find a specific component.”

Use the search bar at the top of the sidebar. Type any part of the name - searches are live and fuzzy.

“Controls don't do anything on this story.”

Some stories use a hardcoded composition rather than a prop bundle. Controls are intentionally disabled in that case. Switch to the Default variant of the component - it will usually have live controls.

“The page story is missing a section I see on the live site.”

Page stories are compositions of section components, and occasionally a newly added section hasn't been wired into the story yet. Let a developer know.

“The preview is stuck on loading.”

Hard-refresh with Shift + Reload. If still stuck, there's probably a TypeScript error somewhere in the component code - check with a developer.

A handful of rituals that make design review with Storybook much more productive over time:

• Whole pages first, then sections, then components. Going the other way makes you fall in love with details that don't matter once you see them in context.
• Tokens page before any “is this the right X?” question. It's the fastest answer.
• Every viewport, every time. Desktop, tablet, mobile is five seconds and catches eighty percent of responsive bugs.
• Flag accessibility violations as you see them. Serious contrast issues affect real users. Storybook makes them visible for free - use it.
• Copy the story URL, not a screenshot alone. URLs are searchable and let the developer reproduce instantly.
• Review in Storybook before requesting a new Figma frame. If the answer is “we already have a component for that,” the fastest path is to flag the existing one, not design a new one.

No new visual component ships without a story. Adopt it on your team and the sidebar stays trustworthy; skip it and Storybook rots into a gallery of outdated examples. If you click into a component and find it missing, ping a developer - adding a story takes ten minutes, and getting it done while the component is fresh in their head is cheaper than a rediscovery a quarter later.