Design tokens setup for scaleup teams using Storybook

Define tokens, align design + code, and ship a scalable theming foundation. Tailored for scaleup teams shipping with Storybook.

Use this playbook to scope work, align design and engineering, and avoid the failure modes we see most often on Storybook teams.

Who this is for: scaleup teams shipping design tokens setup on Storybook.

Typical constraints: 3+ product squads, legacy and greenfield code coexist, release trains already exist.

Success looks like: One shared component source with measurable adoption across squads.

Storybook focus areas: Stories should reflect real product compositions—not isolated atoms only.; Document controls for every meaningful prop; hide internal ones..

Watch for: Stories that pass while production usage breaks because args are unrealistic

• Figma variables and CSS custom properties use different names
• Dark mode is bolted on instead of designed as a theme
• Brand updates require manual find-and-replace across repos
• Spacing and typography drift because primitives are undefined
• Stories that pass while production usage breaks because args are unrealistic
• Missing dark-mode or RTL variants in the story matrix
• Docs pages that drift from the actual exported API

1. Audit existing color, type, and spacing decisions in design and code.
2. Define semantic tokens that survive brand refreshes.
3. Wire Figma variables to code exports your CI can validate.
4. Roll out themes incrementally with a deprecation plan for legacy values.

Storybook specifics:

• Stories should reflect real product compositions—not isolated atoms only.
• Document controls for every meaningful prop; hide internal ones.
• Wire visual regression on PRs for components above a traffic threshold.

• Token taxonomy (primitive → semantic → component)
• Figma variables and code export pipeline
• Theme switching strategy (light/dark/high-contrast)
• Migration guide for existing hardcoded values