Composition and Design Integrations
Purpose and Scope
This page explains how Storybook sharing workflows help teams combine component references across tools and Storybook instances. In this context, composition means showing stories from another Storybook alongside local stories, package composition means a design-system package can expose its stories to consuming applications, and design integrations connect stories to design artifacts such as Figma files, prototypes, components, and frames. Together, these workflows turn Storybook from a local component workbench into a shared reference system for implementation, documentation, review, and design handoff.
Storybook’s design-integration documentation frames the goal as speeding up development by making inconsistencies visible earlier, helping teams discover existing components, and allowing direct comparison between designs and stories. That framing matters because the integration is not only a publishing step; it changes where feedback happens. A designer can inspect a live story from Figma, while a developer can open a Figma file or prototype from the relevant story. Sources: docs/sharing/design-integrations.mdx
Relevant Source Files
docs/sharing/design-integrations.mdx— Documents the design-tool sharing workflow, with Figma as the primary integration, Storybook Connect for embedding stories in Figma, the Designs addon for embedding Figma in Storybook, Chromatic requirements, story-linking steps, and thedesignstory parameter.
Sharing Models: Composition, Package Composition, and Design Links
Storybook Composition is the broadest sharing model: it lets a local Storybook browse another Storybook that is reachable by URL. The composed stories appear in the sidebar next to local stories, which is useful when a product team wants to reference a design system, when a platform team audits usage across projects, or when multiple applications need to compare behavior without switching browser tabs. Because composition is URL-based, it is independent of a particular view layer or dependency graph; React, Vue, Angular, and Web Components Storybooks can be viewed together as published or local artifacts.
Package Composition narrows that idea for component libraries and design systems. Instead of each consuming project manually deciding which remote Storybook to compose, a design-system package can participate in the consumer’s Storybook so its stories appear beside the app’s own stories. The official docs call out that this requires a secure integration between the Storybook publishing service and Storybook APIs, and recommend Chromatic for full support. In practical terms, package composition is about adoption: consumers get usage documentation where they already build, test, and review their own UI.
Design integrations solve a related but different problem. They do not primarily combine Storybook sidebars; they create durable links between implementation examples and design artifacts. The repository page focuses on Figma and presents two directions: embed Storybook in Figma, or embed Figma in Storybook. The first direction helps designers inspect working component states directly in their design environment. The second direction helps developers keep design references adjacent to the story that implements or documents a component state. Sources: docs/sharing/design-integrations.mdx
Figma Integration Workflow
The Figma integration starts with Storybook Connect, a Figma plugin that embeds component stories in Figma. The documented prerequisite is a Storybook published to Chromatic, because Chromatic provides the index, versions, and access control that back the plugin. After installing Storybook Connect from the Figma community plugin page, the user opens Figma’s command palette, runs Storybook Connect, and follows the authentication flow with Chromatic. That makes the relationship branch-aware rather than a brittle one-time URL paste.
After authentication, users link stories to Figma components, variants, and instances. The workflow is intentionally concrete: open the story in the Storybook published on Chromatic, make sure it is on the branch that should be linked, copy the story URL, select the matching Figma component, open the plugin, and paste the URL. Chromatic then updates the linked story to the newest Storybook published on that branch, so links continue to resolve as code changes. The documentation also records an important limitation: the plugin does not support linking stories to Figma layers. Sources: docs/sharing/design-integrations.mdx
Viewing the linked implementation happens inside Figma. Once a component is connected, the user can click the story link in the Figma sidebar and choose “View story,” or reopen the plugin from the command palette. This is a design-review workflow rather than a Storybook authoring workflow: the story already exists, the published Storybook already exists, and the link lets the design tool show the live implementation state that corresponds to the selected component, variant, or instance.
Embedding Figma in Storybook
The reverse direction uses the Designs addon, identified in the docs as @storybook/addon-designs, to embed Figma files and prototypes in Storybook. This is the developer-facing side of the integration. Instead of leaving Storybook to inspect a design spec, a developer can keep the relevant design context on the story page. The docs describe the addon as supporting Figma files, prototypes, components, and frames, which gives teams enough granularity to link a whole design file for broad context or a selected frame for a precise component state. Sources: docs/sharing/design-integrations.mdx
Installation is presented through Storybook’s addon installation flow. The docs reference a command snippet for installing the Figma addon and note that the CLI add command automates installation and setup, while manual installation is covered in the addons documentation. After the addon is available, the story-level contract is the design parameter. A story author adds a parameter named design to associate the story with the copied Figma URL. That keeps design metadata in the same place as other Storybook story configuration, such as args, parameters, and addon inputs.
A typical authoring flow is: open the Figma file or prototype, use Figma’s Share dialog to copy a link, optionally check “Link to selected frame” for a component or frame, then paste that URL into the story’s design parameter. This convention is important because it is durable and reviewable in source control. The design reference travels with the story file, so code reviewers can see when a component state is intentionally tied to a specific Figma artifact rather than relying on an external conversation or a separate ticket.
Compact Reference
| Capability | Where it is configured | Primary user | Key names |
|---|---|---|---|
| Storybook Composition | Storybook composition configuration and reachable Storybook URLs | Developers and platform teams | composed Storybook, sidebar stories, remote Storybook URL |
| Package Composition | Design-system package and publishing integration | Design-system authors and consumers | package composition, Chromatic-backed integration |
| Storybook in Figma | Figma plugin plus Chromatic-published Storybook | Designers and design reviewers | Storybook Connect, Chromatic, story URL, component or variant link |
| Figma in Storybook | Storybook addon and story parameters | Developers and documentation authors | @storybook/addon-designs, CLI add, design parameter |
System-to-Code Mapping
The requested repository source for this page is a documentation source file, so the code mapping is best understood as a documentation-to-user-workflow mapping. The frontmatter gives the page title and sidebar order under Sharing, which places design integrations alongside publish, embed, composition, and package-composition topics. The body then defines the user problem, introduces Figma, splits the integration into two supported directions, and documents the operational steps for each direction: install or enable the relevant integration, copy the correct URL, link it to the corresponding artifact, and use Storybook or Figma as the review surface. Sources: docs/sharing/design-integrations.mdx
When implementing this in a project, choose the sharing model that matches the audience. Use ordinary Storybook Composition when a team needs to browse another Storybook inside its own workspace. Use Package Composition when a published design system should show up automatically for consumers. Use Storybook Connect when designers need live component stories in Figma, and use the Designs addon plus the design parameter when developers need Figma context inside Storybook. Next, read the publishing and embed documentation before configuring Figma links, because both Figma directions depend on a shareable Storybook or shareable design URL.