For AI agents: the documentation index is at /llms.txt, and any docs page is available as Markdown by appending .md to its URL.
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.
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, patterns, blocks, and templates all ship, and install the same way. There are few patterns and templates so far: each exists because a product needed it.
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. See where this is going in the future.
- 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.
- How to adopt it
- One item at a time. shelf add copies a single item into a product, next to the package it uses today, so nothing needs a rewrite.
- Who governs it
- The system team publishes the registry. Products own their copies. Every difference is recorded, so a change is a decision you can see.
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.