Extend
Every surface is a printed page.
assistant-ui is drawn as a printed document, not as an application skin. Four registers follow from that one sentence, and every component in the kit is what they produce.
Shape
Every shape question is answered by asking what the thing is. Ask it in order, and only the third answer reaches for a radius.
- --radius-page0
- The page itself, and every full-bleed band on it: header, footer, section rules.
- --radius-document0
- Anything printed on the page: a code sheet, a table, a figure plate, a specimen frame. Declared so a parent radius cannot leak in.
- --radius-sm6px
- Kbd, inline code, the smallest icon button.
- --radius-control8px
- Button, input, header CTA. Marketing calls to action are 8px rectangles, never pills.
- --radius-surface10px
- Menu, popover, tooltip.
- --radius-xl12px
- Dialog, toast, any floating card. Never square a surface that lifts: the shadow reads as a crescent at each corner.
- --radius-thread16px
- Composer and user bubble. Product vocabulary; it never appears on marketing chrome.
- --radius-capsule9999px
- Switch, avatar, status dot.
Ink
One knob sets the whole palette. --tint: 106 puts every neutral on a single low-chroma oklch hue, so the site reads as sand rather than gallery grayscale. Turn the knob and the mood of every page moves together.
- --background0.992 0.002
- Paper. The dark ground is the same hue at 0.17.
- --foreground0.145 0.006
- Ink. Emphasis comes from weight and fill percentage of this one color, not from hue.
- --muted0.97 0.004
- The quiet fill under machine text and selected rows.
- --border0.922 0.005
- The hairline. One line weight for the whole site.
- blue-500live
- Blue means live: streaming, running, connected, or currently selected. One live accent per page, and if nothing is live the page has no blue.
- --destructive0.577 0.245
- A state, not an accent.
- glint0.82 0.14 82
- Specular light catching the printed mark. It carries no meaning and never becomes a second accent.
Chrome is ink; product data may be colored. A chart, a heat map, a trace waterfall, or a syntax theme keeps its own palette, because there the palette is the content.
Voice
Three faces, assigned by meaning rather than by size. Mono has exactly two jobs: the thing you type or install, and the eyebrow that names a section. It is never prose and never emphasis.
Display
Every state an assistant can be in.
The page’s own voice: h1, h2, h3, and the large figures a page is built around.
Sans
Reading text, set at a comfortable size and never shrunk to make density fit.
Public Sans, through --font-sans.
Mono
npx assistant-ui init
JetBrains Mono, ligatures off. What you type or install, plus the eyebrow above every section on this page.
- typeHero
- The masthead statement, one per page at most.
- typePage
- The ordinary page title.
- typeSection
- A major section turn.
- typeDeck
- One short orientation passage.
- typeEyebrow
- The running head that names a section.
- typePackage
- A package name set as a title, in mono.
Line
Ink is expensive, so a rule has to earn its place. Section boundaries are the only line kind a page owes; rows inside a section breathe on rhythm and a hover fill, not on dividers.
A hairline never stacks with a ring and a shadow on the same edge, and rules never nest three levels deep. Shadows are zeroed globally; only a surface that floats may lift.
Motion
Motion explains a state change, preserves continuity, or confirms an action. It never gates reading, and every one of these is off under prefers-reduced-motion.
- hero-word
- A headline arrives word by word, the newest landing in blue and settling into ink.
- hero-rise
- Deck, actions, and metadata rise after the headline has landed.
- hero-glint
- A gold sweep crosses the printed mark, occasionally.
- code-cascade
- Code lines fade in in sequence when a snippet is swapped.
- line-hot
- The lines that changed between two snippets carry a blue gutter bar and settle once.
- stage-progress
- A hairline fills under the active label to show how long the current act has left.
What they produce
The components.
30 primitives drawn to these registers, each with a live specimen, its API, and its source.
/design/components →The same law, for machines.
One Markdown file an agent can read before it draws anything: the registers above, the closed token and component API, and the failure modes that have already cost a rebuild.
/design.md ↗