Introduction

Start with shared components, then make them yours. Shelf puts the source in every product and tracks every copy, so teams and agents move fast without leaving the system behind.

Components land in your codebase as plain React files that your team and your agents can change or delete. Shelf keeps a hash of each file as installed, so it can tell your changes from upstream changes and merge the two.

Why

Companies with more than one product usually end up with one of two setups. A shared component package keeps products consistent, but its API decides what a product can do: even a spacing or color change becomes an override that breaks on upgrade, or a request that waits on the system team. Copied files remove that wait, but after a few edits nobody knows what the original was, and fixes stop reaching anyone.

Three models

SHARED PACKAGE             COPY AND OWN               SHELF

┌────────────────────┐     ┌────────────────────┐     ┌────────────────────┐
│   design system    │     │    a component     │     │     a registry     │
└──────────┬─────────┘     └──────────┬─────────┘     └──────────┬─────────┘
           │ install                  │ copy                     │ shelf add
           ▼                          ▼                          ▼
┌────────────────────┐     ┌────────────────────┐     ┌────────────────────┐
│    your product    │     │    your source     │     │    your source     │
└────────────────────┘     └────────────────────┘     └────────────────────┘

  + consistent               + fast and yours           + fast and yours
  − its API is the           − disconnected from        + tracked against
    ceiling                    where it came from         the registry

Three models. A shared package is consistent, but its API is the ceiling. Copy and own is fast and yours, but disconnected from where it came from. Shelf is fast and yours, and tracked against the registry.

Shelf keeps the connection of a package and the ownership of copied files. Every product starts from the same source, and files nobody edited stay identical and update as-is. When a product does change something, the change is deliberate and visible: Shelf knows what each product installed, what it changed, and which updates it hasn't taken.

Why source

Engineers and agents change the implementation directly instead of working around an API. Hard interaction behavior stays a dependency: focus, keyboard, and ARIA come from Base UI, and styles compile with StyleX. What you own is the product-facing layer on top.

Designers are meant to work from the same components in Figma. That is in progress.

What you get today

76 components, 11 blocks, and semantic foundations with light and dark themes. A CLI with init, search, add, status, diff, update, and check for each product, and build and usage for the team that runs the registry. The roadmap lists what is available and what is planned.

Where to go next

Install Shelf in a project, read how ownership and provenance work, or see how agents use it.