Design links (Figma)

Design links are provided by a design adapter. Install @storyshelf/design-figma and pass design: [createFigmaDesign()] to createShelfApp — see the package page. Servers generated by storyshelf server init can include it when you answer yes to the Figma prompt; without a provider no design links are shown.

StoryShelf can link each component (story file) to its Figma design. The link shows up as a Figma button on library cards, build cards and the review page — only for components that resolve a link.

Where a project has no Figma token, members can Connect Figma from the review page or a component’s Design tab to see previews with their own account, if your operator enabled it (see the package page).

Declare a link in the story

Use the Storybook design addon shape, or the explicit storyshelf.figma key (which wins when both are set):

const meta = {
  title: "Components/Button",
  parameters: {
    design: { type: "figma", url: "https://www.figma.com/design/KEY/Kit?node-id=1-2" },
    // or: storyshelf: { figma: "https://www.figma.com/design/KEY/Kit?node-id=1-2" },
  },
};

Only Figma URLs are accepted; other values are ignored (and logged during capture) — a bad link never fails a build.

Map a component manually

Settings → Design → Component mapping maps a story file (./src/Button.stories.tsx) to a Figma URL. A manual mapping overrides the story parameters and survives new builds. Mappings are keyed by the story file path, so update one if the file is renamed or moved. Project admins only.

The same tab holds Design files — project-level Figma links shown in the library header.

Optional: Figma token

Add a Figma personal access token (read access to file content) under Settings → Design → Figma access token to show the design name and warn when a design changed after the baseline was approved, or the linked node was deleted. These notices never block review. Tokens are encrypted, never shown again, and expire after at most 90 days — the tab shows the days left and whether the token still works. Without a token, buttons still deep-link to Figma.

Reference renders

With a token, node links (?node-id=…) also get a cached PNG render. The review page shows it as a Figma reference pane under the diff stage, and library cards open a small popover with the render and an Open in Figma action. Renders are downloaded and stored by StoryShelf (Figma’s image URLs expire) and refreshed only when the Figma file version changes. The render is a reference only — StoryShelf never pixel-diffs against it. Links to a whole file (no node) stay plain deep links.