For AI agents: the documentation index is at /llms.txt, and any docs page is available as Markdown by appending .md to its URL.
Designers
Design in the real components. Figma is optional, and the Figma library is compiled from the same source.
The component a designer sees should be the component that ships. With Shelf it is the same file. You don't have to draw it twice, and you don't have to start in Figma.
Work in the real thing
Every component renders live in Storybook and in these docs, with its real states. Change spacing, color, or a variant in the browser, or ask an agent to do it in code. The product picks up the change because the product owns the file.
The tokens behind it are semantic: color, type, radius, spacing, and motion. A theme is one file, in light and dark. Design in the theme your product will ship.
Figma, if your team wants it
Teams that design in Figma get a native library instead of a redrawn one. The Shelf plugin builds it from your registry, and syncs it again when the code changes. The conversion is deterministic: no screenshots, and no AI redrawing a design.
- Variables
- Semantic colors, radius, and spacing, in light and dark.
- Styles
- Text styles and effect styles from the foundations.
- Components
- Variants and properties for the states that exist in code.
- Icons
- From the Shelf icons item, kept as instances inside components.
Hover and focus stay in code. The library holds the states a designer places, not the states a pointer causes.
Set it up
Once per team, by whoever maintains the library file. Your registry must be built with a Storybook: shelf build --storybook storybook-static.
- 1. Get the plugin
- Every registry built with
shelf buildserves the plugin at/figma/manifest.jsonand/figma/code.js. Download both into one folder, then in Figma choose Plugins, Development, Import plugin from manifest. On an Organization or Enterprise plan you can publish it privately instead. - 2. Connect
- Open the file your team publishes as its library, run Shelf, and enter your registry URL. The file remembers it.
- 3. Sync
- Sync, then publish the file as a library.
- 4. Link
- Copy the figma block the plugin shows into your registry's index.json and rebuild. Item pages then open their component in Figma.
The registry site has a Figma page with these steps and download links for your registry, and a check that shows what will sync.
Day to day
Designers enable the library and use the components. They never run the plugin. When the code changes, the library file offers Check for Shelf updates. Syncing updates components in place, so instances stay linked. Removals ask first, because instances of a removed variant detach.
Exploration stays free
Production components follow code. Everything else is normal work: compose with them, detach and copy them, explore new concepts, redesign existing ones. When a direction is approved, it is built in React, and the library follows. Because products own their source, a new interaction doesn't have to wait for the shared system.