story.to.design documentation
Last updated
story.to.design is a Figma plugin that generates and maintains a full Figma library or UI kit directly from your Storybook, Backlight or Histoire stories. It transforms your coded components into Figma components that are ready to use for design work.
New here? Start with What is story.to.design?, then import your first component.
Getting started
- What is story.to.design?
story.to.design is a Figma plugin that generates a Figma UI kit from your Storybook, Backlight or Histoire stories, and keeps it in sync with your code.
- Our vision
Why story.to.design exists: design teams should not spend their time keeping Figma UI kits in sync with code, so the plugin does that maintenance for them.
- Basic concepts and definitions
Design system, UI kit, component library, Storybook and stories: the concepts behind story.to.design, and how they relate to each other.
- Incorporate it in your workflow
Where story.to.design fits in a design system workflow, phase by phase: from designing and coding components to keeping the Figma UI kit synced with code.
- Compatibility
story.to.design creates Figma components from stories hosted on Storybook 6+ (CSF2 or CSF3 with Args) or Histoire 0.15+, whatever the front-end framework.
Set up Storybook
- Connect your Storybook
Connect a public, password-protected, Cloudflare-protected, private or local Storybook or Histoire library to the story.to.design Figma plugin.
- How to write stories
story.to.design extracts the variants of a component from Storybook args: an example story with the argTypes and args the plugin reads.
- Extend stories with Figma variants
Define Figma variants in your stories with the s2d parameter: story.to.design loads them pre-configured, so components import without manual setup.
Import components
- Import your first component
Step by step: run the story.to.design plugin, connect your Storybook, pick a component and story, set up its variants and import it into Figma.
- Understand a component's status
What the status of an imported component means in story.to.design: being analysed, Synced with your stories, or Outdated by a newer version.
- Set up variants
Choose which story args become Figma variant properties when importing a component, update a selection of variants, and see how variants are counted.
- Bring in Storybook updates
When story.to.design detects a new version of your Storybook, regenerate your Figma components from it, review the visual differences and update the canvas.
- Simulated states
Create Figma variants for states that are not Storybook args: hover, tap, focus, active, viewport size and light or dark appearance.
- Documentation of variants
story.to.design imports the documentation written for a component in Storybook, Backlight or Histoire into Figma, with links to its stories.
Advanced features
- Set up variants - JSON mode
Define the Figma variant properties of a component from its story args in JSON, for full control over every property, value and layout.
- Nested components
story.to.design detects already-imported components inside the one you import and places them as nested instances. Import the atomic components first.
- Matching styles
story.to.design uses the color and text styles of your Figma file on imported components instead of hardcoded values, when they match.
- Design tokens as variables
story.to.design turns the CSS custom properties your components use into Figma variables, with modes, and binds the imported layers to them.
- Storybook Globals
Use Storybook globals, such as a theme or locale, as Figma variant properties, and set global values for every component you import.
- Prototype with components
story.to.design generates Figma prototyping interactions between variants: while hovering, on press and on click.
- Import defaults
Set defaults for every component imported from a Storybook in its import configuration: variant properties, viewports, variables and font mappings.
- Local mode
Connect story.to.design to the Storybook running on your computer to iterate on Figma components and variant properties while you develop.
Dev Mode
- Overview
In Figma Dev Mode, story.to.design shows developers a code snippet for the selected component instance and links to its Storybook and story.
How-tos
- Multi-theme
Import components in several themes or brands: as a variant property, as separate components, or as one Figma file per brand.
- Split components
Create several Figma components instead of variants from one story, for example one component per icon to use in instance swaps.
Reference
- Storybook args
What Storybook args are, when story.to.design needs argTypes, and which argTypes it supports to create Figma variants.
- variantProperties API
Reference of variantProperties, which maps story args to Figma variant properties: string, S2dArgVariant and S2dComplexVariant, with examples.
- Axis options
Lay out the variants of a Figma variant property horizontally or vertically, or split them into separate components, with the axis option.
- Special Args
Special Args customize how story.to.design imports variants: :selector, :actionSelector, :portalSelector, :excludeSelector, :slots, :css, :width and :height.
Troubleshooting
- Report a problem
Report a component import problem from the story.to.design plugin: it captures the story for the team and opens a pre-filled GitHub issue.
- Missing fonts
Find which fonts your stories use that are missing in Figma, check the names Figma knows them by, and map a font to one that Figma has.
- No Args found or supported
Why story.to.design shows "No Args found" or "No supported Args found" for a story, and what each message means.
- Storybook variants misrendered
Check whether a variant imported wrong comes from your Storybook renderer: open the story canvas in its own tab with the same args.
Pricing
- Paid plans
story.to.design plans and prices, how to upgrade from the Figma plugin, and how cancelling a monthly or yearly subscription works.
Downloads
- Agent
Download the story.to.design agent for Windows, macOS or Linux, the local app the Figma plugin uses to reach a private or local Storybook.
- Figma plugin
Install story.to.design from the Figma Community, then run it in the file where you want your components.