Tray UI is a clean, well-lit shop counter: a white page, black type that says the thing plainly and large, and goods set out in soft grey trays with very round corners. One yellow marks the thing to do. Nothing is outlined, shadowed or decorated; surfaces are told apart by flat fills alone.
Build with it in this order: pick the ground, set the type, place one yellow action, then reach for components.
Content
- Write short plain statements in sentence case. Headlines are facts: "Our snails grow in the open air", "How to tell it". No capitals for emphasis, no tracked labels above headings, no exclamation marks.
- Buttons start with a verb and name the outcome: "Order a jar", "Save the day", "Keep the order". Never "OK", "Submit" or "Yes".
- Speak as "we" for the company and "you" for the reader. Say what happens next: "The courier calls ten minutes before arriving."
- Errors say what to do: "Enter the phone number with its area code." Never "Invalid value".
- Numbers carry their unit and stand next to what they measure: "22 kg in May", "132 of 412 jars left". Label demo figures as demo data.
- No emoji, no italics, no serif, no superlatives.
Colour
A neutral system with one loud colour.
- The page is
page. Every resting card issurface(Tray Grey). A control that sits on a tray takespageagain. That alternation, white, grey, white, is the whole depth model. - Text is
ink. Secondary text steps down throughink-softandink-muted;ink-hintis the lightest allowed, for axis ticks and placeholders only. accent(Tray Yellow) is for the primary action and for at most one large surface per screen. Two large yellow surfaces in view means one is wrong. Text on yellow is alwayson-accent, never white.- Selected is solid
inkwith page-coloured text: the current tab, the chosen segment, a checked box, a picked day, your own message. Yellow never means "selected". inverseis the one ink card that may anchor a group.leafis the single surface about where a product comes from.dangerandsuccessare for text and icons that come with words: an error under a field, "Paid" in a badge. The only danger fill is the destructive button, withon-dangertext.data-1todata-4belong to chart series, in that order, and appear nowhere else. One series alone is drawn inink, or inaccenton an ink card.code-comment,code-keyword,code-string,code-function,code-tag,code-constantandcode-variableare GitHub's syntax colours, for code in a code block and nowhere else. They colour highlight.js's classes; on the ink card and the yellow card they take their own steps by themselves.- Floating panels (menu, popover, dialog, toast) are
raisedwithshadow-float, overscrimwhen they block the page.
Themes
Set data-theme on <html>, or on any element to theme what is inside it. Ten themes come with the system: light and dark, tuned by hand, and linen, mint, sky, rose, lilac, midnight, forest and espresso, derived from them by the same rules. Each has its own steps, chosen against its own page, not a flip of another one, and its own accent, always bright enough for ink text: yellow in Light and Dark. Accent surfaces, and everything on them, keep the light palette in every theme (the Island Rule): use the paper tokens there, which the tray-card--accent class does for you. Never build a dark variant by inverting colours: derive it, and measure it.
Type
One family, Onest, in two voices: weight 700 with tight tracking for anything that names, weight 400 with open leading for anything that explains. Use the style classes by name.
displayonce per page;headlinefor sections;titleinside a large card or dialog;subtitlefor list items, questions and chart titles.figurefor one large numeral in a card, with its unit attitlesize on the same baseline.leadunder a headline, inink-soft;bodyfor everything else, in a column no wider thanmeasure.- Interface text:
action(large buttons),control(segments, typed values),nav(tabs, menus, table rows),label(field labels, badges, table heads). captionfor hints and dates;tickfor axis ticks and marks;codeandkbdin the mono stack.
The five heading styles are fluid: their sizes come from display-size, headline-size, title-size, subtitle-size and figure-size.
Shape and depth
- Corners are very round and step down with nesting:
radius-card40,radius-panel28,radius-button20,radius-input16,radius-control14,radius-chip12. Chart marks and the checkbox end inradius-mark4.radius-pillis for meters, sliders and the switch only. Nothing has a hard corner, and nothing is a circle except the switch knob, the radio and the slider knob. - Flat. No borders and no shadows on resting surfaces. A ring appears only as state: 2px
inkfor a selected choice or a focused field, 2pxdangerfor an invalid field, 3pxink3px out for keyboard focus (the No-Outline Rule). shadow-floatis the only shadow, for things that float above the page.hairlineis the only rule: list dividers, table rows, form sections, gridlines.rule-strongis a chart baseline.
Layout
- One centred container,
containerwide at most, withpage-padat the edges andsection-gapbetween sections. - Cards sit in a 12-column bento on the 16px
grid-gapand take unequal widths, usually two to one. Below 56rem every card is full width. - Card padding is
card-pad. Space inside components comes from thespace-steps; the gap between a tray and what it holds isspace-1. - Sizes:
size-lg64 for the main action,size-md56 for fields,size-sm48 in headers and toolbars,size-xs40 in dense rows. Nothing a finger must hit is smaller thansize-hit44.
Motion
Every change answers the hand that made it, and nothing moves on its own.
- A press answers at once: a button scales to 0.97, a checkbox and a radio give a little, a switch's knob stretches (
duration-press). - A change of state eases its fill (
duration-fill); a choice slides to its place: the pill of a segmented control or a strip of tabs, the switch's knob (duration-move). - What appears comes in from where it belongs over
duration-inonease: a menu, popover or listbox opens from the corner that touches its trigger, a dialog rises 12px and settles, a sheet comes in from its edge, a drawer from the foot, a toast rises, an accordion's answer unfolds, a field's error comes in under it, a tick draws itself. - What goes away leaves quicker, over
duration-outonease-exit, so a closed thing is out of the way at once. - Only an answer in place overshoots a little (
ease-spring): a count that changes bumps, "Copied" pops in. - For a visitor who asks for reduced motion, overlays fade in a tenth of a second and everything else changes at once.
Modes
A person who asks for more contrast gets darker greys and an edge on every fill. With forced colours (Windows high contrast) every fill becomes an edge and what is chosen takes the system's own colour for it. On paper the page is always the light theme, trays outlined, the navigation left out. Mark what must stay off paper with tray-noprint.
Logo
The mark is a Tray Yellow tile with an ink bar set on it: a tray with one thing on it. It stands before the name, which is set in type (tray-wordmark), at about 1.25 times the size of the type and 10px away. The file is in the Logos asset group.
- Keep it whole and upright, with clear space of a quarter of its width around it; never smaller than 16px.
- On a page in another theme the tile takes that theme's
accentand the bar stays ink, so the page keeps one loud colour. Do not set the mark onaccent. - Where the mark is a link it may move a little: the bar is set down once when the page opens, lifts under the pointer and gives when pressed. It does not move for a visitor who asks for reduced motion.
Icons
The icons are Lucide's (lucide.dev): strokes with round caps and joins, 20px with a 2px stroke, in the colour of the text beside them. Over a hundred are built in, by Lucide's names (src/icons.json lists them); any other Lucide icon fits beside them. Use <svg class="tray-icon"><use href="#tray-i-name"/></svg>; the bundle adds the sprite. The same drawings are in the Icons asset group as single-ink SVG files. An icon never replaces a label except in an icon button, which then carries an aria-label and a Tooltip. Icons that point along the reading direction take tray-icon--flip so they mirror in right-to-left pages.
A product built with the system that has no mark of its own sets its name in type with tray-wordmark, as the blocks do.
Components
Every component is plain HTML with tray- classes from components/bundle.css; behaviour comes from components/bundle.js, which wires up elements that carry a data-tray attribute. Read a component's guidelines before using it: they say which classes, which attributes and which ARIA it needs.
- A surface tells its children what they sit on. Put a field in a
tray-cardand it turns white; put it in atray-panelinside that card and it turns grey again. Do not set those fills by hand. - Prefer the element the browser already has:
<details>for Accordion and Collapsible,<dialog>for Dialog, Sheet and Drawer, real radios and checkboxes inside Toggle Group, Checkbox, Radio Group and Switch. - One primary button per view. Everything else is quiet, ghost or a link.
- A product is framed by the application set: App Shell, Top Bar and Page Header hold every screen; metrics, billing, account and onboarding blocks are built from the base components and keep their rules.
tray-islandmakes any of those blocks the yellow one andtray-inversethe ink one. - Whole screens come ready made:
blocks/holds screens to copy (a dashboard, tables, a shop, articles, a wiki, the sidebar in each of its variants, sign-in and sign-up pages). Start a new screen from the nearest one. Page layouts says how their frames work; Blocks lists them. - Sample content in the application set is about Counter, an invented order desk used by the invented Perly Farm. Replace it; never ship its names, prices or quotes.
Intentional additions
The source of this system is one product landing page with a journal. These parts go beyond it, at the owner's request for a full component set:
- Tokens:
raised,scrim,on-danger, the dark value ofsuccess, the dark value ofshadow-float, thesize-mdandsize-xscontrol heights, thespace-scale as a named scale, the mono stack, and the dark steps ofdata-1todata-4(validated for colour-vision separation on the dark tray). - Components the page did not have: overlays (dialog, sheet, drawer, popover, hover card, tooltip, menus, toast), application navigation (sidebar, menubar, command, breadcrumb, pagination), data (data table, the chart types beyond bars and a line), the conversation set (message, bubble, scroller, attachment, marker, questionnaire, trace, code block), and form controls beyond the order form (select, combobox, slider, one-time code, calendar, date picker).
- The application set, asked for after the first version: the frame of a product (app shell, top bar, page header, workspace switcher, user menu, notification centre, filter bar, stepper, banner), metrics (stat card, usage meter, activity feed, description list, uptime), billing (pricing table, plan comparison, billing summary, payment method, invoice list, checkout summary, upgrade prompt), account (auth form, team members, invite form, API keys, settings section, integration card, notification preferences), onboarding (checklist, tour, feedback widget, changelog, cookie consent), two more form controls (tag input, file upload) and the blocks of a public page (hero, feature grid, testimonial, call to action, footer). They add no tokens.
- Blocks, asked for after the application set, in the manner of the block galleries of component libraries: whole pages built only from the components. For them the app shell and the sidebar gained variants (inset, a header across the product, a sidebar at the end or on both sides, two sidebars, groups and second levels that fold, a tree) and pages outside the shell gained a frame (
tray-screen). They add no tokens. - Icons: the page drew only plus, minus, check, a chevron, a sun and a moon; the system uses Lucide's set, which has the same round stroke.