Philosophy

The system team owns foundations and defaults. Each product owns its implementation.

Tokens, typography, icons, motion, and accessibility are worth centralizing: they are hard to get right and should match across products. The final implementation of a product's interface belongs in the product, where its requirements are.

Distribute implementations, not abstractions

A package distributes an abstraction. Its public API is the only way in, so even a spacing or color change becomes an override from the outside or a request to the system team, and the system team has to anticipate every product. Shelf distributes the implementation. The shared component only has to be a good default.

Dependency or source

For each piece, ask whether it gains more from one correct version or from local control.

Dependencies: Base UI for focus, keyboard, and ARIA behavior. StyleX for compiling styles.
Your source: Button, Dialog presentation, form fields, blocks, and the product UI you compose from them.

Use, learn, then standardize

A new interface idea doesn't have to start as a company-wide abstraction. Build it in the product and ship it. When a second product needs it, move it into the registry.

use, learn, standardize

┌──────────────┐   ┌───────────────┐   ┌──────┐   ┌───────┐
│ product need ├──▶│ build locally ├──▶│ ship ├──▶│ learn │
└──────────────┘   └───────────────┘   └──────┘   └───┬───┘
                                                      │ another product needs it
                                                      │
┌────────────────┐   ┌────────────┐
│ shared pattern │◀──┤ contribute ├───────────────────┘
└────────────────┘   └────────────┘

A product need is built locally, shipped, and learned from. When another product needs it, it is contributed back as a shared pattern.

Components, patterns, blocks, templates

Component: Small reusable UI, such as Button, Dialog, or Input.
Pattern: A reusable interaction or composition, such as a command palette.
Block: A finished piece of a page, such as a login form or a settings section.
Template: A page-level starting point, such as a settings page.

Components and blocks ship today. Patterns and templates will install the same way.

For design-system teams

The system team stops owning every product's implementation and owns what should be shared: foundations, accessibility, defaults, and guidance for agents. In return it gets a record it doesn't have today.

Where each item is used: shelf usage reads every product's repository and reports which items it installed, which it imports, and at which revision.
What each product changed: Every product's lock records what it installed, so local changes are visible instead of silent.
How far behind it is: shelf status in a product lists every item with a newer revision. shelf update merges it in.

Open source

You can read every line you install and every line of the tooling, and host your own registry with shelf build, publicly or behind sign-in.

What Shelf is not

Not a component package, a runtime framework, an AI UI generator, or a no-code tool. Not a replacement for Figma, Storybook, Base UI, or StyleX.