Wrong UI must not typecheck.

One of everything

Anything that looks like a button is the Button. One Input, one Dialog, one Menu: behaviour and appearance stay coupled because there is exactly one implementation, with no duplicate to drift. The same goes for the engines underneath. Base UI arrives only inside system components, and icons only through Icon.

Do not import Base UI primitives directly (Radix is not used at all). Consume them through @instruments/materia-ui components (add the primitive to @instruments/materia-ui if it is missing).

Do not import lucide-react directly. Import glyphs from @instruments/materia-ui/icons (and render via the Icon component) so the icon dependency stays behind the design-system boundary.

32 components build on Button rather than restyling their own.

Types are the first reviewer

Props are closed unions, not open strings. Incompatible combinations are compile errors, and a discriminated prop retypes its siblings: switch a toggle group to multiple and onValueChange demands a string[] before the code will build. Every export's resolved signature is hashed, and unreviewed drift fails the gate.

One grammar of props

size draws from one eight-step scale, 2xs through 3xl, and every control at a given size resolves its height from the same token map, so a Button sits flush beside an Input without anyone measuring. Variants, alignment and direction are shared enums: learn them once and they work everywhere.

No raw elements

Application markup renders only system components; a bare div is a lint error. Semantics come from the as prop's closed menu, which refuses what the system already owns: as="button" is a type error, because the answer is Button. The one open escape hatch, className on a primitive, is policed by the tokens-only gate.

A component owns its job, not its space

A component renders its own job and nothing around it: no baked margin, no width cap, no wrapper card or heading it wasn't asked for. The space it sits in belongs to whatever composes it. A Stack sets the gap, a Container the measure, a Section the rhythm, and a Box is the zero-opinion wrapper. Stories follow the same rule, with framing in a decorator rather than the component, so a piece drops into any layout without fighting its own padding.

17 layout primitives carry the spacing, so components never bake their own.

A fix rolls up

Components are made of components, and layers import in one direction only. Fix the focus ring on a primitive and every control composed from it is fixed in the same commit. The flat import shims give consumers a stable path, so internals can be reorganised without breaking them.

Import from the flat shim @instruments/materia-ui/<components|compositions>/<name>, not a deep internal path (@instruments/materia-ui/<components|compositions>/<name>/<part>). The shim re-exports every public part.

Compositions must earn the tier

The package has two tiers: components, and compositions above them. A composition is admitted only when more than one app is expected to render it, such as a product card or a variant selector. Anything a single app needs lives in that app.

34 compositions currently earn it.

Anatomy is data

A compound component ships a typed anatomy: every part, its slot and its purpose. Each part is addressable in the DOM through its data-slot, Storybook renders the tree, and the anatomy sections on this site are generated from it.

31 anatomy files describe the compound components.

One Base story first

A component's first story is Base: one instance wired straight to the controls, with no scenery and no props it doesn't need. If it can't stand alone there, it doesn't ship. Around Base sit accessibility checks, pseudo-state stories, play-function interaction tests and pixel-level visual regression against committed snapshots.

171 story files · 63 interaction-tested · 2 addons.

Every export is documented

Every export carries working JSDoc: @example, @category, parameter docs and cross-references. It shows as hover help in the IDE, compiles into the agent docs coding agents read, and generates the manifest these pages render from. When documentation drifts from the code, the lint fails.

Best practice travels with the code

Each component carries its own @bestPractice lines, one do or don't per line. They travel with the code into hover help, the agent docs and this site, so the advice changes in the same diff as the behaviour it describes.

165 of 165 documented units carry @bestPractice notes.

Strict oxlint

The package's source is linted on the oxc toolchain: oxlint with an extended React preset and the system's own doctrine plugins, oxfmt for formatting. The import bans it exports to consuming apps are oxlint config fragments on the same toolchain. Rules are errors, not warnings. The few switched off are documented, and the doctrine gates, including bundle and motion discipline, run on every lint.