For kit authors

A primitive without a page does not exist, and a page without a primitive is a lie. Adding a component and adding its page is ONE change, not two — the repository's checks refuse either half on its own.

1. The component in the kit, exported from its barrel. Texts arrive from the caller; the kit translates not one word.
2. The demo as a module of its own. The page imports it twice — once as code that renders, once as the text of the listing. The listing therefore cannot drift from what the demo does, because it is one file read twice.
3. The page, with its status, version, tag, tokens, summary, when to use it and when not to, and its props. An empty array passes the typecheck; an empty section is caught by a test.
4. A registry entry, in alphabetical place by the name the page shows — without the prefix.
5. A test that names the component. A missing test file is exactly what nobody notices in review.

And the version. A change to a component without moving the version on its page does not pass: releases stand on those versions, so a version that does not move is a release that never ships.

A kit component is recognised by what it allows and what it does not. These four rules hold for every one of them, so you do not have to ask again at each.

• className is layout, never look. Width, spacing, placement in a grid — nothing that changes colour, radius, weight or inner padding. A component whose whole point is to look the same everywhere does not take it at all; every component page says which it is, above the properties table.
• Anything with a DOM target takes ref. Focusing a field, scrolling a row into view, setting indeterminate — all through the API. Reaching inside with querySelector ties the screen to the component's insides, which are free to be renamed.
• A label a screen reader needs is a required property — not an optional one with a default. An optional label is a label somebody forgets, and nobody sees that hole on screen.
• Every visible string arrives translated from the caller. The few labels the kit says itself live in the IngotProvider dictionary and are English without it.

The kit is installed from a tag, so its callers do not sit in this repository. Removing a component without notice therefore means somebody's build stops on a Monday morning with nothing to read. Leaving has three steps; growing up has two conditions.

1. The page gets the deprecated status, with a removal version and a replacement. The badge turns red and the page opens with the notice — before the demo, not after it.
2. The component keeps working, unchanged, for at least two releases. A deprecation that removes the thing in the next version is a removal with extra steps.
3. It disappears in the version the page named — never sooner. That is a minor bump, not a patch: to a caller it is as hard a change as a renamed prop.

A component moves from beta to stable on evidence, not on age: two consumers have to use it (the doc web does not count — it demonstrates everything) and it must go two releases without a major bump. Marking something stable because it looks finished is the fastest way to a system that may not fix its own mistakes.

By that criterion 36 of the 55 primitives are in beta today and stay there: the kit does not yet have two consumers outside this repository. Once it does, the list gets another pass — and there will be something to decide on.

• A new component is born in the system, not in a screen — it gets a name, a rule of use and a page in this documentation, and only then is used. A component assembled inside one screen is an island: nobody finds it next time, and writes their own.
• A custom colour, spacing or radius in a screen means a missing token. It is settled in the system, not in the screen — otherwise that value stays one of a kind and nobody finds it at the next change of the palette.
• Changing a token is changing the product: it goes through the same review as a change of code. It lands everywhere at once, so it cannot be undone by one screen.