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 to render, and no duplicate drifting out of sync. Even the engines underneath obey the rule: Radix arrives only inside system components, icons only through Icon.

Do not import Radix primitives directly. Consume them through @desk/ui components (add the primitive to @desk/ui if it is missing).

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

21 components build on Button rather than restyling their own.

Types are the first reviewer

Wrong UI must not typecheck. Props are closed unions rather than 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. The public surface itself is under type control: every export's resolved signature is hashed, and unreviewed drift fails the gate.

One grammar of props

Every component speaks the same prop vocabulary. 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 pixel-flush beside an Input without anyone measuring. Semantic variants, alignment, direction: shared enums, learned once, guessable everywhere.

No raw elements

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

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 was not asked for. The space a component sits in belongs to whatever composes it: a Stack sets the gap, a Container the measure, a Section the rhythm, a Box the zero-opinion wrapper. Even the demos obey it — a story's framing lives in a decorator, never in the component — so the same piece drops into any layout without fighting the padding it brought with it.

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

A fix rolls up

Components are made of components, and the layers import one way only. Correct the focus ring on a primitive and every control composed from it is corrected in the same commit — nothing has to be found and patched twice. The flat import shims keep the roll-up safe: consumers address a stable seam, so the internals behind it can be reorganised freely.

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

Compositions must earn the tier

The package has two tiers: the component vocabulary below, compositions above. A composition is admitted only when more than one app is expected to render it — a product card, a variant selector. Anything a single app needs lives in that app. The tier is a contract about sharing, not a place to park screens.

6 compositions currently earn it.

Anatomy is data

A compound component ships its skeleton as a typed anatomy: every part, its slot, its purpose. Each part is addressable in the DOM through its data-slot, Storybook renders the tree, and the documentation on this site is generated from it — what a Dialog is made of is recorded, never guessed.

31 anatomy files describe the compound components.

One Base story — then every trick in the book

A component's first story is Base: a single instance wired straight to the controls, no scenery, no props it does not need. If it cannot stand on its own there, it does not ship. Around that base the full Storybook arsenal is in play — accessibility checks, pseudo-state stories, play-function interaction tests, and pixel-level visual regression against committed snapshots.

163 story files · 59 interaction-tested · 2 addons in play.

Documented to the hover

Every export carries working JSDoc — @example, @category, parameter docs, cross-references. The comments are load-bearing: they surface as hover help in the IDE, compile into the agent docs that coding agents read, and generate the manifest these pages are rendered from. When documentation drifts from code, the lint fails.

Best practice travels with the code

Guidance is not a wiki that rots. Each component carries its own @bestPractice lines — one do or don't per line — and they ride with the code into hover help, the agent docs and this site. The advice changes in the same diff as the behaviour it describes.

159 of 159 documented units carry @bestPractice notes.

Oxlint, and strict

The package's own source is linted on the oxc toolchain — oxlint with an extended React preset and the system's custom doctrine plugins, oxfmt for formatting. Biome exists here only as a preset exported to consuming apps. Rules are errors, not warnings; the handful switched off are off for documented, load-bearing reasons; and the doctrine gates — bundle and motion discipline included — run on every lint.