addon-designs: a Figma and website panel inside Storybook

The design file lives next to the component in the panel

The addon does one thing: it embeds Figma files or websites in the Storybook addon panel, described in the README as being for a better design and development workflow.

The problem it addresses is a handoff. A component exists in code, the design for it exists in a design tool, and the two are compared in a meeting or in a chat thread. The addon puts the design inside the same surface where the component is rendered, so a reviewer looking at a story can flip between the rendered component and the file it came from without opening another application.

The panel is where the embed lives, which matters for how it is used. It does not replace the Storybook canvas, and it does not add a new page type. It is a panel, so a screenshot of the component and the Figma frame sit side by side, and the workflow stays in the browser tab that is already open.

The package description is broader than the README text. The repository description says the addon embeds Figma, websites or images in the addon panel, while the README itself says it embeds Figma or websites, so treat image embedding as a stated capability of the description rather than a documented one, and check the documentation site before you rely on it.

One parameter per story is the whole API

The API surface is small enough to describe in one sentence, which is unusual for an addon and makes it easy to adopt.

The design attachment is a parameter on the story, under a design key, with a type and a url. The README example creates a story with a parameters block whose design entry has type set to figma and a url pointing at a Figma file:

const meta = {
  title: "My stories",
  component: Button,
};
export default meta;

export const MyStory = {
  parameters: {
    design: {
      type: "figma",
      url: "https://www.figma.com/file/LKQ4FJ4bTnCSjedbRpk931/Sample-File",
    },
  },
};

Because the attachment is a story parameter, it inherits Storybook's parameter model, so it can be set at the meta level for a whole component and overridden per story. The meta object in the example is the place where a shared design would go.

The url is just a url. The README does not document a token, a file id or a permission model for Figma, which means the file has to be embeddable by whoever opens the Storybook. That is the practical constraint to check before you wire a design file into a story, and it is the one the README is silent about.

Storybook major versions are a hard constraint

The requirements section is short and strict. The addon requires Storybook@>=10.0.0, and the README says it should work well with any framework, with an invitation to open an issue if it does not.

The version compatibility table is the part to keep open in another tab:

| Addon designs version | Storybook version | | --------------------- | ----------------- | | ^11.0.0 | ^10.0.0 | | ^10.0.0 | ^9.0.0 | | ^9.0.0 | ^9.0.0 | | ^8.0.0 | ^8.0.0 | | ^7.0.0 | ^7.0.0 |

Read the top row carefully. The newest addon major, 11, pairs with Storybook 10, while the addon major 10 pairs with Storybook 9, and 9 pairs with 9. The table is not a lockstep mapping, so a project on Storybook 10 needs the 11.x addon and a project on Storybook 9 needs the 10.x line.

That matters for upgrade planning, because the addon's major version and your Storybook major version have to move together. The published tags reflect that: @storybook/[email protected] from 2026-07-07, v11.1.1 from 2025-12-31 and v11.1.0 from 2025-12-07. The last push was on 2026-10-19, so the repository is being worked on, but the version line is what your project actually consumes.

One more detail: the requirements say Storybook 10 or later, while the compatibility table still lists older pairings. The table is there for projects on older Storybook versions that cannot move yet, and the requirement reflects where the project is going.

Install, register, then attach a design to one story

The getting started guide is three steps, and the first one covers the three package managers, since the addon is published to npm under the scoped name @storybook/addon-designs.

Install it as a development dependency:

npm install -D @storybook/addon-designs

yarn add -D @storybook/addon-designs

pnpm add -D @storybook/addon-designs

Register it in the addons array of your main.js configuration file:

export default {
  addons: ["@storybook/addon-designs"],
};

Then attach a design to a story, which is the parameters block shown earlier, with the type and the url under the design key.

The order matters more than it looks. Registration in main.js is what puts the panel in the interface at all, so a story with a design parameter and no registration shows nothing, because there is no panel to show it in. Installing as a dev dependency rather than a regular one keeps the addon out of your production bundle, which matters because the panel is a development-time tool.

The documentation site and demo live at storybookjs.github.io/addon-designs, and the README links them as docs and demo. That is also where the parameter reference and the framework guidance live, so it is the place to look for the cases the README does not spell out.

A pnpm workspace with changesets and a published docs site

The repository is more than a single package, and the layout tells you how the project is run.

It is a pnpm workspace, with pnpm-workspace.yaml and pnpm-lock.yaml at the root and a packages/ directory holding the actual packages, one of which is the examples package used by the demo. The root package.json is private and pins the package manager as pnpm at 10.27.0, and the scripts are workspace level: build runs the build across packages, dev does the same for development, example starts the example Storybook, and build:example builds the example in both storybook and tab modes.

Releases go through changesets. The release script is changeset publish, the dev dependencies include @changesets/cli and @changesets/changelog-github, and a .changeset/ directory is present, which is where pending version bumps and their notes live before a release. A CHANGELOG.md at the root and a CHANGELOG.v1-6.md for the older major line are both kept, so the project documents its past versions rather than truncating history.

The documentation site is deployed from the repository, with vercel.json at the root pointing at the docs build, and the .nvmrc file pins the Node version used for development. The toolchain is Prettier for formatting, with the fmt script scoped to specific file types, and tsup and TypeScript for building. The root also has AGENTS.md and CLAUDE.md files, an editor config, a CODEOWNERS file and a CONTRIBUTING.md, which is the usual shape for a project that takes outside contributions.

Where addon-designs is the wrong tool

There are cases where this addon is the wrong answer, and most of them are about where the design file lives.

The first is a design workflow built on another tool. The README lists similar projects for other tools, including storybook-addon-xd-designs for Adobe XD, storybook-zeplin for Zeplin and storybook-addons-abstract for Abstract. Those are community projects, not part of this package, so if your source of truth is Zeplin you are depending on a third party maintainer with a different release schedule, and the choice between them is a judgement about which community you trust to keep pace with Storybook majors rather than a feature comparison.

The second is a project on an old Storybook. The requirement is Storybook 10 or later, so the upgrade of the addon is blocked on the upgrade of Storybook, and on Storybook 9 or earlier you are on the older addon major with a table row that may eventually stop being maintained.

The third is a team that needs the reverse direction. The addon embeds the design in Storybook. If the goal is to publish a Storybook into a design tool or into a review tool, that is not what this does, and the README documents no such path.

The fourth is access control. The design is a url, and a Figma file that only the design team can open will not render for an engineer without access. Nothing in the README describes authentication, so the permission model of the design tool is the permission model of the Storybook.

On licensing, the repository is MIT with the licence file at the root, and the package is published to npm with provenance enabled in the publish configuration.

Editorial conclusion

addon-designs fits a team that keeps design files in Figma and wants designers and engineers looking at the same story without leaving the browser, and it fits any framework because the addon claims no framework dependency. It does not fit a project still on Storybook 9 or earlier, because the package requires Storybook 10 or later, and it does not fit a team whose source of truth is Zeplin or Adobe XD, since the README points to separate community addons for those. Before adding it, check the version compatibility table against the Storybook major version in your project, add the design parameter to one story first, and confirm that the Figma file permissions allow embedding in a browser.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. storybookjs/addon-designs on GitHub