# Design links (Figma)

> Link components to Figma from story parameters or project settings, with stale-design and deleted-node warnings.

Source: https://storyshelf.js.org/guides/design-links/

Design links are provided by a design adapter. Install `@storyshelf/design-figma` and pass `design: [createFigmaDesign()]` to `createShelfApp` — see [the package page](https://storyshelf.js.org/packages/design-figma/). 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](https://storyshelf.js.org/packages/design-figma/)).

## Declare a link in the story

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

```ts
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.