# @storyshelf/design-figma

> Figma design provider for StoryShelf — link validation, file metadata and rendered previews.

Source: https://storyshelf.js.org/packages/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

```sh
npm i @storyshelf/design-figma
```

[![JSR](https://jsr.io/badges/@storyshelf/design-figma)](https://jsr.io/@storyshelf/design-figma) [![JSR Score](https://jsr.io/badges/@storyshelf/design-figma/score)](https://jsr.io/@storyshelf/design-figma)

- [npm package](https://www.npmjs.com/package/@storyshelf/design-figma) — install tarballs and version history.
- [JSR package](https://jsr.io/@storyshelf/design-figma) — TypeScript-first registry page.
- [Public API reference](https://storyshelf.js.org/reference/design-figma/) — generated docs for every export; start here to learn the API. (The same reference is on [JSR](https://jsr.io/@storyshelf/design-figma/doc).)
- [Source on GitHub](https://github.com/GuptaSiddhant/storyshelf/tree/main/packages/design-figma) — package directory on `main`.

## Register the provider

```ts
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](https://storyshelf.js.org/guides/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:

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