Components
Component recipes and the primitive that owns each behavior.
Rule
Compose the primitives in packages/design-system/components/ui before creating a new
component. A repeated pattern becomes a component. A repeated visual value becomes a
token. Components do not own new colours, sizes, radii, spacing, shadows, or fonts.
| Need | Primitive owner | Recipe |
|---|---|---|
| Primary, secondary, ghost, destructive action | button | components.button-* |
| Label, control, helper, error | field, input | components.input-field* |
| Comparable records | table | components.table-* |
| State | badge | components.badge-* |
| Filter | toggle | components.chip-filter* |
| Independent navigation target | card | components.card-surface |
| Inset explanation | alert, item | components.panel-inset |
| Short supporting text | tooltip | components.tooltip |
| Destructive confirmation | dialog | components.dialog-surface |
| Raised anchored action | popover | components.popover-surface |
| Code or machine sample | kbd | components.code-block |
Token contract
Each components.* recipe composes semantic colour, type, radius, spacing, and control
tokens from the same DESIGN.md front matter. Consume the recipe through the existing
primitive. Do not copy its resolved values into a feature.
Correct example
A filter uses toggle in its chip variant, which carries the
components.chip-filter and components.chip-filter-selected recipes. Its selected
state is also written and exposed to assistive technology. A destructive action uses
button in its destructive variant and names the object and consequence.
Rejected example
A feature copies a button into its route, changes its radius, introduces a local status colour, and opens a dialog where inline expansion would keep the record visible. The feature now owns a second, undocumented component system.
Reasoning
Read the UI pattern catalogue and the visual language for shape and elevation.