story.to.designDocs

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.

Contact us