Component lifecycle

The build enforces part of this: a component marked Beta or Stable with an unwritten guidance section fails the build.

Six steps. Most components stay at Beta for a while, and that's fine.

1. Check first. Search the handbook. If a component already does the job, use it, or add an option to it.
2. Propose. Name the job, why nothing existing does it, and the two places (or the second app) that need it.
3. Build in the package. Start from shadcn’s Base UI version (npm run ui-add), move it onto Bridge tokens, and match Bridge OS’s API if one exists.
4. Document. Add it to registry/pages.ts as Experimental and run npm run design:sync. Then write its guidance, live examples, numbered anatomy drawing and states grid.
5. Adopt. Use it from the package on a real screen, merged to the app’s main branch. Refresh the adoption snapshot (below). One screen makes it ready for Beta.
6. Review. Walk the checklist, test it with a keyboard and a screen reader, and list anything still off under known gaps. Change its status in the registry. It moves to Stable once it’s used in two places or by a second app.

Each app chooses which version of @brdgapp/ui it uses, so every release says what it changes.

This holds for every status, Experimental included: a change that could break an app always gets a new first number.

Before something is renamed or removed, it's marked Deprecated for at least one release. Its page names the replacement and the version it goes away in.

Every release gets a line in packages/ui/CHANGELOG.md. To release, bump the version in packages/ui/package.json, add the changelog entry, merge, then push a tag with the same number (v1.1.0). GitLab runs every check and publishes to npm.

Today: 1.0.0 is ready but not published yet. npm needs its Trusted Publisher set up for this GitLab project first (a one-time step by one of the package's npm owners); then the v1.0.0 tag publishes it. Until then, changes go into the 1.0.0 notes.

What a component needs before it's added, and what a reviewer walks before changing its status.

• Read DESIGN.md and the named rules the component touches.
• Colors, radius and spacing come from tokens and the scales; no hex, no palette classes.
• Every rendered part has a data-slot; variants are a cva recipe; className is merged last; named exports only.
• Interactive parts are built on Base UI; links pass through render and stay links. Extra attributes (id, aria-*, data-*) reach the main element.
• Every state is drawn and works: hover, focus, pressed, selected, disabled, loading; and loading, empty and error (DataState) if it shows data, with a skeleton the same size as the loaded content.
• Keyboard works everywhere a pointer does, focus shows, every control is named, contrast is met in both themes, motion respects reduced motion.
• Reads correctly in light and dark, at 390px and 1440px.
• A registry entry with status, level, category and import path; npm run design:sync run.
• Its page has every guidance section, an API entry for every export, honest known gaps and sources, a numbered anatomy drawing, a states grid (if it has states) and three to seven live examples using the sample network's people.
• npm run build passes: the registry check, the token tests, types and lint.

Which components each Bridge app uses from the package, read from the app's main branch. Only merged code counts. A flag means a component's status and its use disagree: a prompt to review, not a verdict.

• Bridge OS: origin/main at 5d9b382, taken 2026-11-02.

0 of 37 components are used on an app's main branch. Every status matches its use.

No app imports the package on its main branch yet. Bridge OS's move onto the package is in an open merge request; when it merges, refresh the snapshot and review the flags.

To refresh, fetch the app's main branch, then run npm run design:adoption -- --app "Bridge OS" --repo <path to the app> and commit registry/adoption.ts. It only reads the app's code.

• Status criteria approved by Aman 2026-11-02 (registry/statuses.ts).
• Sharing rule: decision 2026-11-02 (#11).
• Versions: decision 2026-11-02 (#17). Publishing: GitLab publishes on a version tag (decision 2026-11-02).
• Adding a component: plan 03-architecture.md → Component base.
• Bridge OS components.md → How to use this file (update the docs in the same change).
• Adoption: registry/adoption.ts, a snapshot of each app's main branch taken by scripts/adoption.ts. Decision 2026-11-02: only code merged to main counts.
• Oration Canon → Component lifecycle (the review step, the checklist, adoption read from code).