Materials
Corners, edges, depth and the surfaces they sit on. The radius scale is ratios of one knob, --radius (10px); shadows stack low-alpha layers with theme-aware inset highlights, so one token works on both canvases.
Radius
Each step is a multiple of --radius, so raising the knob softens the whole UI in proportion. Pick the step by the element's size, not its importance.
- 4pxCheckbox, swatch
- 6pxInline chips, small controls
- 8pxMenu items, inputs
- 10pxReference chips · the knob
- 14pxPopovers, small cards
- 18pxQuestion bubbles, tiles
- 22pxSuggestions, rows
- 26pxDialogs, large buttons
- 32pxComposer, section cards
- 20pxAssistant chat bubble
- 72pxProfile hero backdrop
- 9999pxPills, icon buttons
Avatars use the squircle class: corner-shape: squircle at 80px where the browser supports it, a 28% radius everywhere else. Nest radii concentrically: an inner corner is the outer corner minus the padding between them.
Borders
Three outline strengths and a hairline drawn as a shadow. All three borders are 1px.
| Example | Token | Usage |
|---|---|---|
| Hairlines: dividers, table rows, the rules of this page.--border-subtle · tint-12 | ||
| A control's resting outline: inputs, outline buttons, frames.--border · neutral-300 / 800 | ||
| An outline that has to hold its own: the composer, a focused field.--border-loud · tint-20 | ||
| The hairline as a box-shadow: no layout cost, stacks under other shadows.0 0 0 1px var(--border-subtle) |
Shadows
Stacked umbra layers with 1px inset highlights. In the dark theme the drops all but vanish and the hairline does the work, by design.
| Example | Token | Usage |
|---|---|---|
| A one-pixel lift: the bottom nav pill.0 1px 2px | ||
| Glass badges, tabs, switches, toggle groups.3px halo + inset highlights | ||
| Brand CTA chip, filled buttons, agent icons.2px + 43px wide ambient | ||
| Raised controls: tooltips, the artifact dock.10px drop + inset highlights | ||
| Floating panels: popover, menu, dialog, sheet, the composer.12px stack + 1px edge | ||
| Photo and window tiles on the landing pages.32px stack | ||
| A tile under the pointer, on hover.20px + 40px blur | ||
| A resting card or block: hairline and a 2px drop.edge + 0 2px 2px | ||
| The card's hover state, eased over 300ms.card + 0 8px 16px | ||
| A card one step quieter: same hairline, half the drop.edge + 0 1px 2px | ||
| The profile avatar.32px stack + inset rim | ||
| Rim light on photo tiles: inset highlights only.inset 2px 4px × 2 | ||
| The same rim on the soft highlight.inset 2px 4px × 2 | ||
| Profile and marketplace hero backdrop.24px stack + tangerine micro-layer |
Surfaces
Fills from lowest to highest. Elevation is the fill and the shadow together: a floating surface always brings its shadow.
| Example | Token | Usage |
|---|---|---|
Canvas | The page canvas and every docs block. White in light, sand 950 in dark.--background | |
Secondary | The “Ask me about” card, nav pill, code blocks. Sunken below the canvas in dark.--surface-secondary · neutral-50 / 975 | |
Raised | A whisper above the canvas: the hero backdrop's gradient start.--surface-raised · neutral-100 / 925 | |
Card | Cards sit on the canvas colour and separate by their shadow-card hairline.--card · with shadow-card | |
Elevated | Anything that floats: the composer, glass badges. Lighter than the canvas in dark.--surface-elevated · with shadow-lg | |
Popover | Popovers, menus and selects, at radius xl.--popover · with shadow-lg | |
Overlay | Dialog and sheet panels, over the scrim.--overlay · with shadow-lg |
Glass
Blur for chrome that content scrolls under, never as decoration. The glass-* utilities predate the brand and are listed so they are recognised, not reused.
| Example | Token | Usage |
|---|---|---|
| Translucent bars: the site header at bg-surface-secondary/85 with one hairline. The current way to make glass.--blur-glass · 12px | ||
| Phase-1 utility from globals.css: card at 96% with blur and a soft drop. No component uses it now.blur 12px · saturate 120% | ||
| Phase-1 chat bubble glass. Kept for reference; chat bubbles use the chat-bubble-* colours.blur 12px · saturate 160% |
Spacing and containers
Three named gaps for group, block and section; everything else is Tailwind’s 4px step. Containers are drawn at half size.
| Example | Token | Usage |
|---|---|---|
| Rows inside one block, chip rows.--spacing-group · 12px | ||
| Between blocks inside an answer.--spacing-stack · 24px | ||
| Between answer sections and turns.--spacing-section · 40px |
| Example | Token | Usage |
|---|---|---|
| The bottom nav pill.--container-nav · 448px | ||
| The profile column and reading measure.--container-content · 672px | ||
| Composer, hero backdrop, questions panel.--container-wide · 752px |
Z-index
A fixed ladder. Reach for a step by name, or isolate a stacking context; never invent a number.
| Example | Token | Usage |
|---|---|---|
| Fixed header, bottom nav pill, this page's top bar.--z-sticky | ||
| The dialog backdrop.--z-scrim | ||
| Menus, selects, popovers.--z-dropdown | ||
| Dialogs and sheets.--z-modal | ||
| Tooltips, above any panel they explain.--z-tooltip | ||
| Toasts, above everything.--z-toast |
Best practices
Depth
- Separate a card from the canvas with shadow-card, not a border and a shadow together.
- Anything that floats over content (popover, menu, dialog) takes shadow-lg and a surface above the canvas.
- Animate shadows on hover with the slow duration and ease-out; never animate blur radius on a large area.
Shape and space
- Small elements get small radii. A chip inside a card uses a smaller step than the card.
- Pills (rounded-full) are for chips, tabs, icon buttons and avatars, not for cards.
- Use gap-group, gap-stack and gap-section for rhythm before reaching for a raw spacing step.