@storyshelf/design-figma

@storyshelf/design-figma links components to Figma. It implements the DesignProvider contract from @storyshelf/core: it validates pasted Figma links, reads file/node metadata (name, version, last modified) and downloads rendered previews through the Figma REST API with a personal access token that a project admin saves under Settings → Design. StoryShelf itself owns link resolution, the metadata/render cache, stale-design warnings and the UI; this package supplies only the Figma specifics.

Install

npm

npm i @storyshelf/design-figma

pnpm

pnpm add @storyshelf/design-figma

yarn

yarn add @storyshelf/design-figma

• npm package — install tarballs and version history.
• JSR package — TypeScript-first registry page.
• Public API reference — generated docs for every export; start here to learn the API. (The same reference is on JSR.)
• Source on GitHub — package directory on main.

Register the provider

import { createShelfApp } from "@storyshelf/app";
import { createFigmaDesign } from "@storyshelf/design-figma";

const app = createShelfApp({
  database,
  storage,
  testing: { runner: captureRunner },
  design: [createFigmaDesign()],
  config: {
    secret: process.env.SHELF_SECRET, // also encrypts the Figma token
  },
});

Without a provider, StoryShelf extracts and shows no design links. With it, stories link to Figma through parameters.storyshelf.figma or the Storybook design addon, and project admins manage mappings and the access token under Settings → Design. See Design links for how stories, mappings and the access token work.

Let members connect their own account

Without a project token, a member can connect their own Figma account (like Jira or Linear integrations) and see previews, names and stale-design warnings with their own access. Register an OAuth app in Figma (Settings → OAuth apps; a private app works within your organization), add the redirect URL <publicBaseUrl>/connections/figma/callback and the file_content:read scope, then:

import { createFigmaDesign, figmaOAuthFromEnv } from "@storyshelf/design-figma";

design: [createFigmaDesign({ oauth: figmaOAuthFromEnv() })], // FIGMA_CLIENT_ID / FIGMA_CLIENT_SECRET

This needs authentication enabled and config.secret (it signs the connect flow and encrypts tokens). A project token, when set, always takes precedence; a member's token is used only while they view a page, and what it fetches is shown only to them.

Accepted links

https://www.figma.com/{file|design|board|proto|make}/<key>/… with an optional node-id. Embed, community and Figma Sites links are rejected.