What you are moving from Figma to Storybook
Moving a component from Figma to Storybook means translating approved design decisions into a working, documented implementation. The output should include supported properties, states, content rules, and usage examples. A matching screenshot is useful evidence, but it is only one part of that contract.
In TDP’s walkthrough, Dianne starts with the Carrot component library, audits its variables, and chooses a button as the pilot. The audit exposes raw semantic colors, gaps in primitive mappings, conflicting dimensions, and differences between Figma and code. Those findings become decisions before implementation begins.
This guide follows that sequence. Use a component that exists in your product and keep the scope narrow enough for a designer and engineer to review together. The examples below illustrate the method; the exact variants and behaviors must come from your team.
Companion guide: Figma to Storybook
Open From Figma to Storybook: Build Components AI Can Use for TDP’s reusable prompts. Follow the source check, token audit, component specification, and Storybook implementation with your own Figma file and repository. Keep the prompts beside this walkthrough and review each result before moving to the next step. Access may require free signup.
Step 1. Verify the source
Open the component in Figma and find its current implementation, if one exists. If an agent uses a Figma integration, ask it to identify the exact file, component, and variable collections it can access before editing. An answer based only on repository files is insufficient when you asked for a Figma audit.
Step 2. Audit the tokens
Record primitive values and the semantic names that reference them. Check supported modes separately. Two tokens with identical values may serve different purposes, so matching hex codes alone are not a reason to merge them. Agree on the mappings, change a small batch, and inspect the component after the change.
Step 3. Specify the component contract
Use a button as a manageable pilot. Resolve differences between the design and code with the people responsible for the component. The example below is a starting specification; allowed values must match your product.
| Property or state | Example decision to record |
|---|---|
| Purpose | Submits the current form |
| Variant | Primary, secondary, destructive |
| Size | Default and compact, with explicit dimensions |
| Loading | Shows progress and prevents repeated submission |
| Disabled | Explain when and why it becomes unavailable |
| Focus | A visible keyboard indicator |
| Content | A clear action label; an icon has an accessible name |
Step 4. Build inspectable stories
Reuse the existing component where appropriate. Add stories for meaningful variants, loading and disabled states, long labels, and relevant surrounding context. Storybook stories describe component states using arguments; choose the configuration supported by your project. Keep a story close to the implementation so reviewers can compare both in the same change.
Implement [component] using the approved specification.
Reuse our token names and existing component conventions.
Show stories for supported variants and meaningful states.
List changed files, checks run, and unresolved decisions.
Step 5. Compare design, stories, and real use
Review dimensions, tokens, keyboard focus, labels, and behavior. Then place the component in a representative page. An isolated button can look correct while creating poor hierarchy beside another action. Record the decisions from the pilot before applying the workflow to more components.
The audit questions that prevent a misleading conversion
Before asking an agent to build, ask it to distinguish what it observed from what it recommends. In the TDP demonstration, the existing code button did not match the design component, and even the design references disagreed about some values. Treating either artifact as automatically correct would have carried those inconsistencies into a new library.
Inspect the named Figma component and its implementation.
For each proposed requirement, identify its source.
Separate verified facts, recommendations, and unknowns.
Flag disagreements between Figma, code, and documentation.
Ask only the unresolved questions that affect correct behavior.
Do not invent product rules or edit the library yet.
Read the answers with the component owner. A missing pressed state is different from an intentionally unsupported state. A different destructive color might mean the code drifted, or that the design file missed an approved change. Record the decision and update whichever source is now wrong.
A practical component questionnaire
| Question | Why it matters |
|---|---|
| What user intent does this component serve? | Determines whether a button, link, or another control is appropriate |
| What are its named parts? | Makes anatomy and composition understandable |
| Which properties are configurable? | Defines the public API rather than accidental implementation details |
| What is the default? | Prevents consumers from making an arbitrary choice |
| Which combinations are invalid? | Stops plausible but unsupported configurations |
| What can occupy each slot? | Distinguishes a reusable composition from one fixed screenshot |
| What happens with long or missing content? | Exposes layout and labeling assumptions |
| Which behaviors remain undecided? | Keeps recommendations from becoming silent requirements |
This questionnaire applies beyond buttons. A status card needs transition rules and next actions. A field needs labeling and error behavior. A menu needs keyboard and focus behavior. Adapt the contract to the component’s job.
Worked example: resolve an action-group disagreement
Imagine Figma shows two equally prominent actions while the product team intends one primary action and one cancellation path. The implementation also uses an old button size. Record these as separate issues: hierarchy and dimensions. Changing both without explanation makes the review harder.
Approve the action hierarchy first, then agree on the supported size. Create a story showing the whole action group, including long labels. Check the component at the intended viewport and use the keyboard to move through the actions. The result should demonstrate both the visual decision and the interaction.
If loading behavior is unresolved, do not copy the demonstration’s choice into your product. Decide whether the action can be submitted twice, how progress is conveyed, and what happens after failure. The answer depends on the actual operation.
Documentation should explain when and why
Storybook’s documentation tools let teams combine generated component information with richer prose. Use that space for decision rules and meaningful compositions. A props table can tell someone that a variant exists; it usually cannot explain when choosing it would mislead the user.
Keep the longer guidance linked to runnable stories. If an example says the control supports a long translated label, make that example inspectable. If a configuration is unsupported, state the alternative a consumer should choose. “Don’t do this” is easier to apply when the correct pattern is nearby.
Review the handoff as a small pull request
Include the source references, approved decisions, implementation, stories, and checks in one reviewable change. The reviewer should be able to connect a visible result to the decision that produced it. Keep unrelated token cleanup in a separate change when it would obscure the component work.
After approval, repeat the process for another component with a different interaction pattern. That second pilot tests whether the workflow is reusable or merely tailored to buttons. Only then turn the procedure into a shared skill or a larger migration plan.
The AI-ready system walkthrough explains how to connect these component-level decisions to tokens, agent instructions, and ongoing maintenance.
Completion checklist
- Figma and code sources are identified.
- Token changes preserve intended modes and meaning.
- Supported states and invalid combinations are documented.
- Stories match the implementation.
- The component is checked in a real flow, not only in isolation.
Common questions
Does this automatically synchronize Figma and code?
No. This is a reviewable workflow for moving agreed decisions into implementation. Synchronization depends on the integrations and maintenance process you choose.
Should we rebuild the whole library first?
Start with one representative component. Expand when the team can reproduce the process and explain the decisions.
Sources and TDP resources
- Open the full TDP Figma-to-Storybook resource for the original prompts and workflow. The resource may request free signup.
- Storybook: writing stories explains how stories describe component states.