# Tray UI > A design system in plain HTML and CSS: 108 components, 64 blocks, 118 icons and 10 themes, with typed React components and 58 chart examples on Recharts. Version 0.2.0, MIT licence, by Vladyslav Korzh. Link three files and write HTML with `tray-` classes; behaviours attach with `data-tray`, and nothing needs a build step: ```html ``` - From npm: `npm install trayui` for the three files, `npm install trayui-react` for React (it needs `react` and `react-dom`, and `recharts` for the charts). - Counter and Perly Farm, the brands in the examples, are invented, and so is every name and figure in them. - Use only classes that exist; where a layout needs a value no class gives, use a token (`var(--space-6)`), never a literal colour or size. The sections: installation, the rules (the brand book), the guides, theming, React, Tailwind and Figma, coming from Tailwind, for AI agents, the component index, the guidelines of every component, the blocks, charts in React, and the changelog. ## Installation Three files and a font. Link them from a CDN or copy them into your project, then write HTML. There is nothing to build. ### Link them from a CDN The quickest start: put these lines in the `` of a page, the script before `` or with `defer`, and write HTML. ```html ``` jsDelivr serves every release of the `trayui` package on npm, and the address names the release, so a page keeps the version it was built with. For production, copy the files into your project or pin the release you tested. ### Or install them from npm In a project with a bundler, install the package and import the three files once, at the entry of the app: ```sh npm install trayui ``` ```js import 'trayui/tokens.css'; import 'trayui/components/bundle.css'; import 'trayui/components/bundle.js'; ``` The package also holds the font, the blocks and the tokens for Tailwind and Figma. For React, see [React](https://trayui.com/docs/react.md). ### Or get the files Download [trayui-0.2.0.zip](https://trayui.com/trayui-0.2.0.zip) and unpack it beside your pages. ```text trayui/ tokens.css every token as a custom property, the type classes, the font components/bundle.css the tray- classes components/bundle.js behaviours and the icons fonts/ the typeface (Onest-Variable.ttf and .woff2), with its licence (OFL.txt) blocks/ 64 screens to copy tailwind/ the tokens as a Tailwind theme (version 4) and a preset (version 3) figma/ the tokens as Figma variables, a mode for each theme ``` The last two folders are for [Tailwind and Figma](https://trayui.com/docs/tailwind-figma.md); a page in plain HTML needs neither. ### Link them In this order, in every page: ```html …your page… ``` The script is one classic file. It assigns `window.TrayUI`, adds the icon sprite to the page and wires up every element that carries a `data-tray` attribute. It loads nothing from the network. If you add markup after the page has loaded, call `TrayUI.init(root)` on it. ### Write a first screen ```html

Order a jar

``` That is a grey tray on the white page, a white field in it, and the one yellow button. From here, copy a [block](https://trayui.com/blocks.md) (the files in `blocks/` open as they are) or look up a [component](https://trayui.com/components.md). ### Sizes | File | Compressed | | --- | --- | | `tokens.css` | 1 KB | | `components/bundle.css` | 36 KB | | `components/bundle.js` | 42 KB | ### Browsers The current versions of Chrome, Edge, Safari and Firefox. The stylesheet uses logical properties, `:has()`, dynamic viewport units and the native `` and `
` elements; it has no fallbacks for browsers without them. ### The font Onest is a variable font by the Onest Project Authors, under the SIL Open Font License 1.1; the licence text is in `fonts/OFL.txt`. To use another typeface, see [Theming](https://trayui.com/docs/theming.md). ### Licence Tray UI is released under the MIT licence. ## Rules: the brand book The rules of the system in one page: content, colour, type, shape, layout, motion and icons. 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 is `surface` (Tray Grey). A control that sits on a tray takes `page` again. That alternation, white, grey, white, is the whole depth model. - Text is `ink`. Secondary text steps down through `ink-soft` and `ink-muted`; `ink-hint` is 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 always `on-accent`, never white. - Selected is solid `ink` with page-coloured text: the current tab, the chosen segment, a checked box, a picked day, your own message. Yellow never means "selected". - `inverse` is the one ink card that may anchor a group. `leaf` is the single surface about where a product comes from. - `danger` and `success` are 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, with `on-danger` text. - `data-1` to `data-4` belong to chart series, in that order, and appear nowhere else. One series alone is drawn in `ink`, or in `accent` on an ink card. - `code-comment`, `code-keyword`, `code-string`, `code-function`, `code-tag`, `code-constant` and `code-variable` are 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 `raised` with `shadow-float`, over `scrim` when they block the page. #### Themes Set `data-theme` on ``, 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. - `display` once per page; `headline` for sections; `title` inside a large card or dialog; `subtitle` for list items, questions and chart titles. - `figure` for one large numeral in a card, with its unit at `title` size on the same baseline. - `lead` under a headline, in `ink-soft`; `body` for everything else, in a column no wider than `measure`. - Interface text: `action` (large buttons), `control` (segments, typed values), `nav` (tabs, menus, table rows), `label` (field labels, badges, table heads). - `caption` for hints and dates; `tick` for axis ticks and marks; `code` and `kbd` in 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-card` 40, `radius-panel` 28, `radius-button` 20, `radius-input` 16, `radius-control` 14, `radius-chip` 12. Chart marks and the checkbox end in `radius-mark` 4. `radius-pill` is 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 `ink` for a selected choice or a focused field, 2px `danger` for an invalid field, 3px `ink` 3px out for keyboard focus (the No-Outline Rule). - `shadow-float` is the only shadow, for things that float above the page. - `hairline` is the only rule: list dividers, table rows, form sections, gridlines. `rule-strong` is a chart baseline. ### Layout - One centred container, `container` wide at most, with `page-pad` at the edges and `section-gap` between sections. - Cards sit in a 12-column bento on the 16px `grid-gap` and take unequal widths, usually two to one. Below 56rem every card is full width. - Card padding is `card-pad`. Space inside components comes from the `space-` steps; the gap between a tray and what it holds is `space-1`. - Sizes: `size-lg` 64 for the main action, `size-md` 56 for fields, `size-sm` 48 in headers and toolbars, `size-xs` 40 in dense rows. Nothing a finger must hit is smaller than `size-hit` 44. ### 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-in` on `ease`: 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-out` on `ease-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 `accent` and the bar stays ink, so the page keeps one loud colour. Do not set the mark on `accent`. - 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 ``; 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-card` and it turns white; put it in a `tray-panel` inside that card and it turns grey again. Do not set those fills by hand. - Prefer the element the browser already has: `
` for Accordion and Collapsible, `` 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-island` makes any of those blocks the yellow one and `tray-inverse` the 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 of `success`, the dark value of `shadow-float`, the `size-md` and `size-xs` control heights, the `space-` scale as a named scale, the mono stack, and the dark steps of `data-1` to `data-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. ## Grounds and nesting Depth in this system is fill, and fill alternates. A component never needs to be told its colours; it reads them from the ground it sits on. ### The alternation | Ground | Class | Controls on it are | | --- | --- | --- | | The page (`page`) | none | `surface` grey | | A tray (`surface`) | `tray-card` | `page` white | | A white panel inside a tray (`page`) | `tray-panel` | `surface` grey | | A floating panel (`raised`) | `tray-pop`, `tray-dialog`, `tray-sheet`, `tray-drawer`, `tray-toast`, `tray-command`, `tray-raised` | `surface` grey | | Yellow (`accent`) | `tray-card--accent`, `tray-alert--accent`, `tray-island` | `paper` white, text `paper-ink` | | The ink card (`inverse`) | `tray-card--inverse` | `inverse-off`, text `on-inverse` | | Leaf (`leaf`) | `tray-card--leaf` | `page` | A filled row (an Item, an Alert, a choice card, a switch row, an attachment) is a small ground of its own: the tile or button inside it takes the colour behind the row. So on the white page an Item is grey and its icon tile is white; inside a tray the Item is white and its tile grey. ### How it works Four local custom properties carry the ground down the tree. Component styles use these, never a colour token directly, for anything that depends on the ground: - `--tray-ground`: the colour behind the component. - `--tray-fill`: the resting fill of a control on that ground. - `--tray-off`: an unselected ring or an off switch (it is `ink-hint` on `raised`, where `control-off` would be too faint). - `--tray-on-ink`: text on a solid-ink, selected fill. When you build something new, use the same four and it will sit correctly on every ground and in every theme. ### Radii step down with nesting | Level | Token | Examples | | --- | --- | --- | | The surface | `radius-card` 40 | card, dialog, sheet | | A panel on it | `radius-panel` 28 | white panel, popover, media | | A large control | `radius-button` 20 | large button, the tray of a segmented control or tab strip, menu, alert | | A field | `radius-input` 16 | input, select, choice card, item, toast | | A small control | `radius-control` 14 | small button, segment, tab, menu item, day | | A chip | `radius-chip` 12 | badge, chip, tooltip, avatar, icon tile | Never give a child a larger radius than its parent, and never put a 40px corner inside a 40px corner: use `tray-panel`. ### Rules - Do not nest a tray in a tray. Inside a `tray-card` use a `tray-panel`, a hairline, or space. - One yellow surface and one ink card per screen, at most. - Do not set a background on a control to "fix" it on an unusual ground; give the ground one of the classes above. - Yellow keeps the light palette in the dark theme. Put theme-dependent things (a chart drawn in `ink`, a quiet button) on it with care: they will stay light. ## Styles and behaviour The system ships as three files and needs no framework and no build step. ### Loading ```html ``` `tokens.css` declares every token as a custom property (`--ink`, `--radius-card`, `--space-4`) and a class per type style (`.display`, `.body`). `bundle.css` holds the `tray-` classes and loads after it. `bundle.js` is one classic script that assigns `window.TrayUI`, injects the icon sprite and wires up behaviours; it loads nothing from the network. Switch themes by setting `data-theme="dark"` on ``. Follow the system setting until the person chooses, then remember their choice. ### Behaviours A behaviour is attached with `data-tray="name"` on the element named below. Call `TrayUI.init(root)` after adding markup to the page. Most components need none: buttons, cards, fields, checkboxes, radios, switches, accordion, table and tabs-as-links are plain HTML and CSS. | `data-tray` | On | Does | | --- | --- | --- | | `toggle` | a button with `aria-pressed` | flips the pressed state | | `stepper` | a button group with two `data-step` buttons and an `` | counts between `data-min` and `data-max` | | `otp` | the row of one-character inputs | advances, steps back, takes a pasted code | | `slider` | `` | fills the track, writes the value | | `count` | a textarea with `maxlength` | shows the character count | | `reveal` | a button in a password group | shows and hides the password | | `select` | the anchor of a custom select | opens the list, sets the value | | `combobox` | the anchor of a combobox | filters the list as you type | | `calendar` | an empty element | draws a month grid; single date or range | | `datepicker` | the anchor of a date field | ties a calendar to a trigger | | `tabs` | the wrapper of a tablist and its panels | switches panels, arrow keys | | `strip` | a tab strip that may overflow | fades its end while it scrolls | | `menu` | the anchor of a dropdown menu | opens, arrow keys, check and radio items | | `menubar` | a strip of menus | moves between menus | | `contextmenu` | a region holding a menu | opens it where the region is right-clicked | | `popover` | the anchor of a popover | opens a panel, moves focus in and back | | `hovercard` | the anchor around a link | opens a preview on hover or focus | | `tooltip` | an anchor around one control, with `data-tip` | names the control on hover and focus | | `dialog` | a `` (dialog, alert dialog, sheet, drawer) | `data-close` buttons, closing on the veil (a press and a release both on it, so a selection dragged out does not close it) | | `open` | a button with `data-target` | opens that dialog | | `sidebar-toggle` | a button with `aria-controls` | collapses the sidebar to a rail | | `sidebar-sheet` | the `tray-app__menu` button, with `aria-controls` | opens that sidebar in a sheet on a small screen | | `command` | the command panel | filters and runs options | | `split` | a resizable pair of panes | drags the handle, arrow keys | | `carousel` | a carousel | previous, next and the count | | `datatable` | the wrapper of a table | filter, sort, select, page | | `chart` | a figure with `data-chart` JSON | draws the chart | | `scroller` | a message scroller | follows new messages, offers "Latest" | | `reaction` | a reaction button | toggles it and its count | | `more` | a "Show more" button | opens a clamped bubble | | `questionnaire` | the questionnaire form | one question at a time | | `copy` | a button with `data-target` | copies that text, or a field's value; says Copied or Copy failed on the button and through a status beside it | | `dismiss` | a button inside a block with `data-dismissable` | hides that block | | `spark` | an element with `data-points` | draws a small trend line | | `uptime` | an element with `data-days` and `data-incidents` | draws a bar per day | | `pricing` | the wrapper of a billing-period switch | shows the price of the chosen period | | `mask` | an input with `data-mask` | groups a card number, writes an expiry date | | `secret` | the wrapper of a masked key | shows, hides and copies the key | | `taginput` | the tray of a tag input | turns typed values into chips | | `dropzone` | the tray of a file upload | takes dropped or chosen files and lists them | | `checklist` | an onboarding checklist | opens the next task, fills the progress | | `tour` | the area a tour runs in | shows one step at a time beside its target | | `feedback` | a feedback form | opens the follow-up, then the thanks | | `consent` | a cookie consent panel | closes it and reports the choice | | `notices` | a notification panel | marks as read, counts the unread | | `filterbar` | a filter bar | keeps the chips and the menu items in step | ### Events Behaviours report with bubbling custom events on their own element: `tray:change` (a value, a selection, a page, a size), `tray:select` (a menu or command item), `tray:open` and `tray:close` (a floating panel), `tray:complete` (a one-time code, a questionnaire). The value is in `event.detail`. ### Functions | Function | Use | | --- | --- | | `TrayUI.init(root)` | Wire up behaviours under `root` after adding markup. | | `TrayUI.chart(el, config)` | Draw a chart into a `
`. Returns `{ update(config) }`. | | `TrayUI.calendar(el, options)` | Draw a calendar. Returns `{ value(), set(value) }`. | | `TrayUI.toast(options)` | Show a toast. Returns `{ dismiss() }`. | | `TrayUI.formatDate(value, locale)` | "14 Nov 2026", or a range. | | `TrayUI.icon(name, className)` | The markup of an icon. | | `TrayUI.register(name, fn)` | Add your own `data-tray` behaviour. | | `TrayUI.upgrade(selector, fn)` | Run `fn` once for every element that matches, with no `data-tray` of its own (the system gives every `.tray-seg` and `.tray-tabs` its sliding pill this way). | ### Motion Things come in by CSS alone (`@starting-style`); the behaviours help them go away. A panel the behaviours close (a menu, a popover, a listbox, a tooltip, a hover card) is hidden with its exit transition; a dialog the behaviours close leaves first and closes when it has left, Escape included, also where the browser cannot keep it in the top layer while it leaves (there `data-closing` runs the exit first). A toast sinks out and is then taken away. Hiding or closing from your own script works as before, and the panel then goes away at once. The pill of a segmented control follows its radios' `change` event: after setting a radio from script, dispatch `new Event('change')` on its `.tray-seg`. A strip of tabs or links follows `aria-selected` and `aria-current` by itself. ### Naming Classes are `tray-block`, `tray-block__part`, `tray-block--variant`. State is in attributes, never in classes: `aria-pressed`, `aria-selected`, `aria-current`, `aria-invalid`, `aria-busy`, `open`, `hidden`, `disabled`, and `data-` attributes for what ARIA has no word for. Local custom properties start with `--tray-`. ## Accessibility The system is built to pass WCAG 2.2 AA in every theme. These are the rules that keep it there. ### Contrast - Text is `ink`, `ink-soft` or `ink-muted` on `page`, `surface`, `raised` and `leaf`: at least 4.5:1 in every theme. `ink-hint` holds 4.5:1 on `page`, `surface` and `raised` only; never use it on `leaf` or `inverse`. - On `accent` all text is `on-accent` (12.9:1). On `inverse` use `on-inverse`, `on-dark-soft` and `on-dark-muted`; they hold 4.5:1 on the fills inside the ink card (`inverse-off`) too. There `danger` and `success` become `on-dark-danger` and `on-dark-success` by themselves, since the colours of a light theme are too dark to read on ink. On the yellow card they become `paper-danger` and `paper-success`, which read on the accent of every theme. - `danger` and `success` hold at least 5.9:1 as text on `page`, `surface` and `raised`, and always come with words or an icon. - Control edges (`control-off`) hold 3:1 on `page` and `surface`; on `raised` the components switch to `ink-hint`. - Two of the four data colours are below 3:1 on light grounds. Charts therefore never rely on colour: several series always come with a legend, a tooltip and a table of the same figures, and text is never set in a data colour. ### Focus Keyboard focus is a solid 3px `ink` ring, 3px out, on every ground. Fields draw theirs at 2px on the edge; tabs, menu items and days draw it inside. On a yellow surface in the dark theme the ring of the surface itself takes the theme's ink, so it shows on the dark page. Never remove a focus ring without drawing another. Focus order follows reading order. Opening a dialog, sheet, drawer or popover moves focus into it; closing returns focus to the control that opened it. ### Targets Nothing a finger must hit is smaller than 44px (`size-hit`). Checkboxes, radios and switches extend their target over the whole label row. ### Names and roles - Every control has a visible label, or an `aria-label` when it is an icon button. A Tooltip repeats the name; it never holds the only copy. - State lives in ARIA attributes, and the styles read those same attributes: if it looks selected, it is announced as selected. - Components use the element the browser already provides wherever one exists, so they work without script and with assistive technology: `details`, `dialog`, real form controls, `table` with captions and scoped heads. - Charts carry a written `summary` and are focusable. A chart with points along an axis can be walked with the arrow keys, each value said aloud; a radial chart and horizontal bars are read from their summary and their table of figures. ### Motion Nothing moves on its own and nothing auto-advances. Under `prefers-reduced-motion: reduce` nothing travels or scales: menus, popovers, tooltips, dialogs, sheets and drawers only fade, in a tenth of a second; toasts, the sliding pills, the drawn tick, the unfolding answers, a bumping count and a popping word change at once; the skeleton and marker pulses and the progress slide stop; smooth scrolling becomes instant; and the spinner turns slowly instead of stopping so it still reads as activity. ### More contrast, forced colours, print The system draws most things as a fill with no edge. Three settings of the person's own take those fills away or make them weak, and the stylesheet answers each: - **More contrast** (`prefers-contrast: more`). Each grey takes the value its theme gives the next step towards the ink (`ink-soft` becomes `ink`, `ink-muted` becomes `ink-soft`, and so on, down to `hairline`), and every tray, field and quiet control gets a 1px edge. `tokens.css` writes the steps for every theme, and the theme maker on the site writes them for a theme of your own. - **Forced colours** (Windows high contrast and the like). The browser replaces every colour with the few the person chose and drops fills and shadows. Buttons, fields, trays and what floats get an edge; what is chosen (a tab, a segment, a pressed toggle, the current page, a checked box, an on switch, a picked day) is drawn in the system's colours for a chosen item, `SelectedItem` and `SelectedItemText`; the option under the keyboard in a list is `Highlight`. Switches, sliders, meters and thin rules are drawn in system colours too, since they are nothing but fills. The marks of a chart keep the colours of their series, so the key still tells them apart; a chart of one series takes the text colour. - **Print**. The page prints in the light values of its theme, whatever theme it wears on screen. Trays get a thin edge in place of the fill the browser leaves out; a fill that carries meaning (what is chosen, a bar, a meter, the ink card) prints as it is. The sidebar of the app, toasts, tooltips and open menus stay off paper, and what belongs together does not break across sheets. Add `tray-noprint` to keep anything else off paper, and `tray-print-only` to show a thing on paper alone. ### Reading direction Styles use logical properties throughout. Set `dir="rtl"` and layouts mirror; mark directional icons with `tray-icon--flip`. Numbers, time axes and code do not mirror. ### Checks before shipping 1. Tab through the screen: every control is reachable, visibly focused, and operable with Enter, Space, the arrow keys and Escape. 2. Turn on the dark theme: nothing is illegible, yellow surfaces are unchanged. 3. Zoom to 200% and narrow to 320px: nothing overlaps, tables scroll inside their wrapper. 4. Read it with a screen reader: every control says what it is, its state, and what happened after an action. 5. Turn on more contrast and a high-contrast theme of the system, and print the page: every control still shows where it is and what is chosen. ## Page layouts Blocks are whole screens, so they need a frame as well as components. There are two frames: the app shell for a product, and the screen for everything outside it. Both are plain classes; neither adds a token. ### The app shell and its variants `tray-app` is the frame of a product: a sidebar on a tray, a top bar, one centred column (see App Shell). These modifiers change the arrangement, not the parts. | Class | What it does | | --- | --- | | `tray-app--inset` | The page is a tray, the sidebar sits straight on it, and `tray-app__main` is one white panel. Inside that panel a card is grey again. | | `tray-app--header` with `tray-app__header` | A header across the whole product, over the sidebar and the content: `
` as the first child. It stays in place while the page scrolls. | | `tray-app--end` | The sidebar at the end. Put `tray-app__side` after `tray-app__main` in the markup. | | `tray-app--both` | A sidebar on each side: `tray-app__side`, `tray-app__main`, `tray-app__side`. | | `tray-app__side--double` | Two sidebars side by side in one `tray-app__side`: a rail (`tray-sidebar` with `data-collapsed`) and the list of the chosen section. | | `tray-app--fill` | The shell is as tall as the window and the page scrolls inside itself: a conversation whose Message Scroller takes the height that is left. | | `tray-app__side--late` with `tray-app__menu--late` | In `tray-app--both` the end sidebar waits for 80rem; until then its sheet button stays in the top bar. | Below 56rem the sidebars leave the page. A button with `class="tray-app__menu"`, `data-tray="sidebar-sheet"` and `aria-controls` naming a sidebar opens that same sidebar in a sheet, and puts it back when the sheet closes. The sheet comes from the side the sidebar is on, and takes the sidebar's `aria-label` as its name. A second such button opens the sidebar at the end; with two sidebars at the start, give each its own button so nothing is out of reach on a phone. A button that collapses the sidebar to a rail takes `tray-app__collapse`, which hides it where there is nothing to collapse. ```html ``` ### The sidebar and its variants | Markup | What it is | | --- | --- | | `
` with `` | A group that folds. The summary ends with a small `chevron-right` icon, which turns when the group opens. | | `
` with `` and a `tray-sidebar__sub` list | An item whose second level folds. The summary ends with ``. | | `tray-sidebar--flyout`, items inside `
` with a `tray-pop tray-pop--side` | Items that open their second level as a menu beside them. | | `tray-tree` | A tree of 36px rows: nested lists; a folder is `
` whose summary starts with the caret, a file is a link. | | `tray-sidebar--wide` | 21rem, for a list of messages or files. | | `tray-sidebar--plain` | No tray of its own: navigation inside a popover, a dialog or a sheet. | | `tray-sidebar__scroll` | The part that scrolls when the navigation is taller than the window: put the groups in it, and the head and the foot stay in view. | | `tray-sidebar__body` | What a group holds when it is not rows of navigation: checkboxes, a description list. | | `tray-sidebar__sub--text` | A second level under items without icons, as in a table of contents. | In the rail every item keeps its name: the label is hidden from the eye but not from a screen reader, and shows in a Tooltip beside the icon; the tooltip stays away while the label is in view. A sidebar with `tray-sidebar--flyout` cannot scroll, because its menus must be able to leave it: keep its navigation short enough for the smallest window you support (about 790px for eleven items), and in the phone sheet its menus open under their items. `tray-dialog--split` is a dialog with its own navigation: `tray-dialog__split` holds a `tray-sidebar` and a `tray-dialog__pane`. Below 48rem the navigation becomes a strip above the pane. ### The screen `tray-screen` is the frame of a page outside the shell: sign in, a wizard, a public page. It is as tall as the window. | Class | What it does | | --- | --- | | `tray-screen__bar` | A row at the top: the wordmark at the start, one link or button at the end. | | `tray-screen__body` | The content, in the container. `--narrow` keeps it to 42rem for a form or a wizard; `--center` centres it in the height; `--center-wide` does so only from 40rem, so a form under a bar starts at the top of a phone. | | `tray-screen__foot` | One quiet line at the end: terms, a note. | | `tray-screen--tray` | A grey ground. Fields on it turn white by themselves; a card on it is a `tray-panel`, not a `tray-card`. | | `tray-screen--split` | Two halves (`tray-screen__half`) from 56rem: a form beside a cover. `tray-screen__half--wide` is shown only when there is room for both. | | `tray-screen__cover` | On a yellow, ink or leaf card: it fills its half, a statement at one end and a proof at the other. | `tray-auth-wide` is one tray that holds a form (`tray-auth-wide__form`) beside a picture (`tray-auth-wide__media`, painted with `tray-island` or `tray-inverse`). ### Content beside a column `tray-with-aside` puts a narrow column beside the content from 64rem and keeps it in view while the page scrolls: an article and its contents, an order and its customer. `tray-with-aside--narrow` makes the column 15rem. Inside the app shell, where the sidebar has already taken its share, `tray-with-aside--late` waits until 76rem. ### The top bar on a small screen A full top bar (breadcrumb, search, notifications, account) needs about 440px. Below 48rem it folds part by part, each by its own class: `tray-crumbs--fold` keeps only the current page of the breadcrumb, `tray-topbar__search--fold` keeps only the icon of the search (give that button an `aria-label`), and `tray-topbar__wide` marks anything else the bar may drop. ### Public pages A public page sits in `tray-container` with its sections in `tray-section`. `tray-section__head` holds a section's headline and its one sentence (`--center` over a pricing table). In the site header, `
``` | Tokens | Utilities | | --- | --- | | Every colour: `--page`, `--ink`, `--accent`, `--data-1` and the rest | `bg-page`, `text-ink`, `bg-accent`, `border-hairline`, `fill-data-1` | | The corners: `--radius-card` to `--radius-pill` | `rounded-card`, `rounded-button`, `rounded-pill` | | The shadow | `shadow-float` | | The type styles | `text-display` to `text-label`: the size, the line height, the weight and the tracking together | | The sizes of controls | `h-hit`, `h-control-md`, `size-control-lg`, `size-icon` | | The spaces of a layout | `p-card`, `px-gutter`, `gap-grid`, `py-section` | | `--container` and `--measure` | `max-w-page`, `max-w-measure` | | The breakpoints | `phone:`, `tablet:`, `bento:` and `header:` | | The dark themes | `dark:` | - **The theme still works.** Each utility reads the system's own custom property: `bg-page` is `var(--page)`. So `data-theme` on ``, or on any element, changes the utilities the way it changes the components. - **Dark follows the theme, not the system setting.** `dark:` applies inside any of the dark themes. - **Spacing needs nothing.** Tailwind's spacing scale (`p-1` is 4px, `p-4` is 16px) is already the system's own. - **Tailwind's palette stays.** To use only the system's colours, put `@theme { --color-*: initial; }` before the import. ### Tailwind CSS 3 Add [tailwind/preset.cjs](https://trayui.com/tailwind/preset.cjs) as a preset, and link `tokens.css` on the page: ```js // tailwind.config.js module.exports = { presets: [require('./tailwind/preset.cjs')], content: ['./src/**/*.html'], }; ``` The names are the same as in version 4. Version 3 also gets `z-float`, `z-toast`, `duration-press` and `ease-tray`. It does not get the breakpoints: Tailwind 3 adds new ones after its own, out of order. Write `min-[34rem]:` for the width at which the system's layouts change. ### Figma The variables come in the Design Tokens format that Figma imports, with one file per theme: 1. In Figma, open the variables of the file and create a collection named Colours. 2. Drop in the ten files of `figma/colours/`, from [Light](https://trayui.com/figma/colours/Light.tokens.json) to [Espresso](https://trayui.com/figma/colours/Espresso.tokens.json). Each file becomes a mode of the collection, so a frame switches theme the way a page does. 3. Create a second collection and drop in [Scale.tokens.json](https://trayui.com/figma/scale/Scale.tokens.json): the space, the corners, the sizes, the type sizes and weights, the durations and the layers. A variable has the name the token has in code. The colour `ink-soft` is `--ink-soft`, and the scale variable `radius/card` is `--radius-card`. Each variable's description gives its CSS name and what it is for. - **Sizes are in px.** Figma takes px only, so rem is counted at 16px and a fluid size takes its largest value. - **The shadow and the easing are not included.** Figma has no variable for them: draw the shadow as an effect style from `--shadow-float`. - **A paid Figma plan is needed.** Figma's help says importing variables needs a Professional plan or above. - **To update a theme, import its file again.** Right-click its mode and choose Import mode: variables with the same name and type change in place. The ten colour files and the scale are also in the `figma` folder of the download. ## Coming from Tailwind How Tailwind habits map to Tray UI, a design system in plain HTML and CSS: what differs, how to move a screen across, and when to keep Tailwind. ### How the two differ Tailwind gives you small classes, mostly one property each, and you compose the design in the markup: a card is `rounded-xl bg-white p-6 shadow-sm`. Tray UI gives you one class per component and a set of tokens: the card is `tray-card`, and its fill, corners and padding come from custom properties in `tokens.css`. - **Build step.** Tailwind scans your files and writes the CSS they use. Tray UI is three files you link: no compiler, no config. - **Design.** Tailwind has no look of its own: the design is yours. Tray UI is a finished design with rules: one yellow for the main action, flat grey trays, very round corners. You retune its tokens, not its structure. - **States and behaviour.** In Tailwind you write `hover:` and `dark:` on each element and bring a library for menus and dialogs. In Tray UI each class carries its states, `data-theme` picks one of ten themes, and a `data-tray` attribute wires up a behaviour. ### Habits, translated The left column is Tailwind 4. Where no class fits, a token does. | In Tailwind | In Tray UI | | --- | --- | | A card: `rounded-xl bg-white p-6 shadow-sm` (`shadow` in version 3) | `tray-card`: a grey tray, 40px corners, no shadow. `tray-panel` is the white panel inside it. | | `flex flex-wrap items-center gap-4` | `tray-row`; `tray-row--sm` for `gap-2`, `tray-row--between` for `justify-between`. | | `flex flex-col gap-4` | `tray-stack`; `tray-stack--sm` for `gap-2`, `tray-stack--lg` for `gap-6`. | | `grid grid-cols-12 gap-4` with `col-span-8` | `tray-bento` with `tray-span-4` to `tray-span-8`, full width below 56rem. | | `mx-auto max-w-7xl px-4` | `tray-container`: centred, with `--page-pad` at the edges. | | `text-4xl font-bold tracking-tight` | A type style named for its role: `display`, `headline`, `title`, `subtitle`, `lead`, `body`, `caption`. | | `text-gray-500` | `tray-soft`, or the lighter `tray-muted`. In your own CSS, `var(--ink-soft)`. | | A primary button: `rounded-md bg-indigo-600 px-4 py-2.5 font-semibold text-white` | `tray-btn`, once per view; `tray-btn--quiet` for the rest. | | A label, an input and a hint, each with its utilities | `tray-field` around `tray-label`, `tray-input` and `tray-field__hint`. For an error, `aria-invalid="true"` and `tray-field__error`. | | `hover:`, `active:` and `focus-visible:` | Nothing: each class has its hover, press and focus ring. | | `dark:` variants | Nothing: `data-theme="dark"`, or another theme, on `` or any element. | | `sr-only` | `tray-vh` | | Headless UI's `Menu`, or Alpine's `x-data` and `x-show` | `data-tray="menu"` on a `tray-anchor` around the button and its `tray-pop`: see [Dropdown Menu](https://trayui.com/components/dropdown-menu.md). | | Headless UI's `Dialog` | ``, opened by a button with `data-tray="open"` and `data-target`: see [Dialog](https://trayui.com/components/dialog.md). | | `p-6`, `gap-6`, `mt-6` | `--space-6`, also 24px: the space tokens share Tailwind's 4px steps. For layout, `--card-pad`, `--grid-gap` and `--section-gap`. | | `@apply` in a class of your own | A plain rule that reads the tokens, as below. | For a part the system does not have, write the rule yourself. `--tray-fill` is the fill a control takes on its ground, so this note is grey on the page and white in a card ([Grounds and nesting](https://trayui.com/docs/grounds.md)). ```css .order-note { padding: var(--space-4) var(--space-5); border-radius: var(--radius-input); background: var(--tray-fill); color: var(--ink-soft); } ``` ### One card, both ways A heading, a sentence, a field with a hint and a button. In Tailwind 4: ```html

Track an order

We show where it is and when it arrives.

It is on the receipt, under the total.

``` In Tray UI: ```html

Track an order

We show where it is and when it arrives.

It is on the receipt, under the total.

``` - **The look lives in the classes.** The grey tray, the white field and the yellow button come from three classes; a token change reaches every card. - **States come with them.** `aria-invalid="true"` on the input draws the red ring; a `tray-field__error` takes the place of the hint. - **Dark costs nothing.** The Tailwind card needs a `dark:` variant on most of its classes; this one follows `data-theme`. - **They do not look alike.** The first is your design, the second is the system's. That is the trade. ### Move a screen across 1. Start from the nearest [block](https://trayui.com/blocks.md), not from your old markup. 2. Pick the frame: the app shell (`tray-app`) for a product, `tray-screen` for the rest ([Page layouts](https://trayui.com/docs/layouts.md)). 3. Swap each card, field and button for its component, and delete the utilities it replaces. 4. Swap the layout utilities that remain for `tray-row`, `tray-stack` and `tray-bento`, or keep them. 5. Delete every `dark:` variant and look at the screen in two or three themes. 6. Replace the menu and dialog scripts with `data-tray`; call `TrayUI.init(root)` on markup added later. 7. Count the yellow: one primary button per view. ### Using both You can keep Tailwind: utilities for layout glue, Tray UI for the components, and the tokens as Tailwind's theme, so both use the same colours and sizes. ```html
…the card above…
``` `gap-grid`, `py-section`, `text-ink-soft` and `bento:` come from the theme in the `tailwind/` folder. [Tailwind and Figma](https://trayui.com/docs/tailwind-figma.md) has the import lines and every name. - **Put utilities around components, not on them.** Tailwind 4 puts its utilities in a cascade layer and `bundle.css` has none, so where both set the same property, the `tray-` class wins: `p-4` on a `tray-card` does nothing. In version 3, which has no layers, the later stylesheet wins. What the class leaves alone, such as a margin or `self-start`, is free. - **Change a token, not a component.** For calmer corners, set `--radius-card`; [Theming](https://trayui.com/docs/theming.md) says how. ### When Tailwind is the better choice - **A design of your own.** Tray UI is one design with rules. Its tokens change the colours, the corners and the type, not the flat, one-yellow structure. If your brand looks nothing like it, start from Tailwind. - **One-off layouts.** A landing page drawn section by section, or a screen unlike any other. Utilities describe a layout that exists once; the layouts of Tray UI are a fixed set, made to be reused. - **A large codebase already in Tailwind.** Rewriting screens that work costs more than it gains. Use the tokens as a theme and move a screen when you rebuild it. - **Only the CSS you use.** Tailwind writes only the classes your files use; Tray UI ships its whole stylesheet. Tailwind also has editor tooling Tray UI lacks: completion, linting, class sorting. ### Where to go next - [Installation](https://trayui.com/docs/installation.md): the three files and a first screen. - [Components](https://trayui.com/components.md): each with a live example and its markup. - [Blocks](https://trayui.com/blocks.md): whole screens to copy. - [React](https://trayui.com/docs/react.md), if your Tailwind project is in React: the same components, typed. ## For AI agents The system is written to be read by an agent as well as by a person: short rules, exact names, and markup that can be copied. This page says what to give an agent, and what to ask of it. ### What to give it - [llms.txt](https://trayui.com/llms.txt) is the index: what Tray UI is, the three lines that install it, and a link to every page. It is short enough to paste into a prompt. - [llms-full.txt](https://trayui.com/llms-full.txt) holds the whole system in one file: the rules of the brand book, the guides (grounds, behaviour, accessibility, page layouts), theming, React, the index of components and the guidelines of every component with its markup. - Every page of this site is also Markdown at its own address with `.md` added: the page of the button is at `/components/button`, its Markdown at `/components/button.md`. A block's Markdown holds its whole page of HTML, and a chart's holds its React file. Each page names its Markdown in its head, as ``. An agent that can fetch pages needs only the address of llms.txt. One that cannot needs llms-full.txt, or the Markdown of the pages the task touches, pasted in. ### Connect it to a tool 1. In a chat, attach llms-full.txt, or paste llms.txt and let the agent fetch the pages it lists. 2. In an editor with an agent (Cursor, Windsurf, Claude Code, Copilot), add the address of llms.txt as a documentation source where the tool allows one, or save llms-full.txt into the project and point the agent at it from its rules file (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules`). 3. In a project of your own, copy the three files in and tell the agent where they are, so it links them instead of a CDN. ### What to tell the agent - Link the three files; write plain HTML with `tray-` classes; attach behaviour with `data-tray`. - Start a screen from the nearest block, not from an empty page. - Follow the brand book: one yellow per view, depth by fill, selected is solid ink, sentence case, buttons that start with a verb. - Use only classes that exist. If a layout needs a value that no class gives, use a token (`var(--space-6)`), never a literal colour or size. - Check the result at 1280, 768 and 390 pixels in a light and a dark theme. - From npm, the files are `trayui` and React is `trayui-react`; an agent that installs them needs nothing else from the system. ### A prompt to start from ```text Build the order history page of a shop with Tray UI. Read https://trayui.com/llms.txt first, then the pages it lists for the components you use. Start from the closest block (a table page), link tokens.css, components/bundle.css and components/bundle.js, and use only tray- classes and tokens that exist. One yellow button per view. Give me one HTML file, then check it at 1280, 768 and 390 px wide. ``` ### What it gets right, and what to check An agent that has read the guidelines writes the right markup for a component: the classes, the attributes and the ARIA. What it gets wrong most often is the page around the components: two yellow buttons in one view, a colour or a size typed by hand, a heading level skipped. Ask it to check its page against the brand book before it hands it over, and look at it in a dark theme. ## Component index The 108 components of the system, group by group. Read a component's guidelines before using it. ### Actions | Component | Use | | --- | --- | | Button | A button starts an action; the yellow one is the single most important action in view. | | Button Group | A button group is a tray that holds related buttons 4px apart, so they read as one control. | | Toggle | A toggle is one button that stays pressed: on is solid ink, off is the resting fill. | | Toggle Group | A toggle group is the segmented control: a tray of segments where the selected one is solid ink. | ### Forms | Component | Use | | --- | --- | | Calendar | A calendar shows a month as a grid of days and takes one date or a range. | | Checkbox | A checkbox turns one option on or off; a group of them lets several be on at once. | | Combobox | A combobox is a field that filters a list as you type and takes one of its options. | | Date Picker | A date picker is a field that opens a calendar and shows the chosen date in words. | | Field | A field is one question in a form: a label, its control, and one line of help or error beneath. | | File Upload | File upload is a tray with a dashed edge that takes files dropped on it or chosen from the device, and lists them underneath. | | Input | An input takes one line of text: a grey fill, 16px corners, 56px tall, no stroke. | | Input Group | An input group is one field that also holds an icon, a unit, a prefix or a small button. | | Input OTP | Input OTP takes a short one-time code, one character per cell. | | Label | A label names a control in plain words, above it, in `label` type. | | Native Select | A native select is the browser's own menu in the system's field: the right choice on phones and in long forms. | | Radio Group | A radio group picks exactly one option from a few that are all shown. | | Select | A select picks one option from a short list that opens under its trigger. | | Slider | A slider picks a number from a range by dragging, when the feel of the value matters more than its digits. | | Switch | A switch turns one setting on or off, and the change applies at once. | | Tag Input | A tag input takes several short values in one field: each becomes a chip that can be removed, and the caret waits after the last one. | | Textarea | A textarea takes several lines of text, in the same fill and corners as an input. | ### Navigation | Component | Use | | --- | --- | | Breadcrumb | A breadcrumb shows where a page sits and leads back up, one level per link. | | Command | Command is a search field over a list of destinations and actions: type a few letters, press Enter. | | Menubar | A menubar is the row of menus at the top of a working tool: File, Edit, View. | | Navigation Menu | The navigation menu is the header of a site: the wordmark, a strip of links, and one small primary action. | | Pagination | Pagination moves through a long list one page at a time. | | Sidebar | A sidebar is the navigation of an application: a tray down the side with groups of links, and the person's account at its foot. | | Stepper | A stepper shows where a person is in a short, fixed sequence: the steps as numbered marks over a bar that fills as they go. | | Tabs | Tabs switch between views of the same thing: a tray strip of 44px tabs, the current one in solid ink. | ### Overlays | Component | Use | | --- | --- | | Alert Dialog | An alert dialog stops a person before something that cannot be undone, and makes them choose. | | Context Menu | A context menu opens where something is right-clicked and offers the actions for that thing. | | Dialog | A dialog asks for one decision or one small task in a panel over the page, and holds the page still until it is done. | | Drawer | A drawer is a panel that rises from the bottom edge: the dialog of a phone. | | Dropdown Menu | A dropdown menu is a short list of actions that opens from a button. | | Hover Card | A hover card previews what is behind a link when the pointer rests on it: a person, an order, a note. | | Popover | A popover is a small panel that opens beside the button that asked for it, for a few controls or a short explanation. | | Sheet | A sheet is a panel that slides in from the side and keeps the page in view beside it. | | Tooltip | A tooltip is one short line that names a control when the pointer or the keyboard is on it. | ### Feedback | Component | Use | | --- | --- | | Alert | An alert is a message that stays in the page until its cause is gone: a tray row with an icon tile, a title and a sentence. | | Banner | A banner is one line across the top of a page or a section, about the whole product or the whole account: a trial that is ending, planned maintenance, a payment that failed. | | Empty | An empty state fills the place where content will be: an icon tile, a title, one sentence, and the action that makes the first item. | | Progress | A progress bar shows how much of a known whole is done: an 8px pill in `track`, filled in `ink`. | | Skeleton | A skeleton holds the place of content that is loading, in the shape of what will arrive. | | Spinner | A spinner says that something is in progress and its length is unknown. | | Toast | A toast confirms that something just happened, in a small panel at the corner of the screen that leaves by itself. | ### Data | Component | Use | | --- | --- | | Chart | A chart turns figures into thin marks on a quiet frame: a value axis in `tick` type, hairline gridlines, a strong baseline, a tooltip, and the same figures as a table. | | Data Table | A data table is a Table that can be searched, sorted, selected and paged. | | Table | A table sets figures in rows and columns: hairline rows, quiet heads, numbers aligned on the right. | ### Layout | Component | Use | | --- | --- | | Aspect Ratio | Aspect ratio keeps a box in a fixed proportion while its width changes, so media never shifts the layout as it loads. | | Carousel | A carousel is one row of cards that scrolls sideways and snaps to each card. | | Direction | Direction is how the system follows the reading direction of the language: set `dir="rtl"` and every component mirrors. | | Resizable | Resizable splits a box into two panes with a handle between them that can be dragged. | | Scroll Area | A scroll area keeps a long list or a wide row inside a fixed box, with a thin scrollbar in the system's rule colour. | | Separator | A separator is the one rule in the system: a 1px line in `hairline`. | ### Display | Component | Use | | --- | --- | | Accordion | An accordion is a list of questions that open one at a time: hairline rows, a bold question, a plus tile that turns into a cross. | | Avatar | An avatar stands for a person or a team: a softly squared tile with a photo or initials. | | Badge | A badge states one fact about the thing beside it in a word or two. It is not a control. | | Card | A card is a tray: a grey surface with 40px corners that groups what belongs together. Fill alone sets it apart. | | Collapsible | A collapsible shows and hides one block of detail under a short trigger. | | Description List | A description list sets out the facts about one thing as pairs: the name of the fact in soft ink at the start edge, its value beside it, a hairline between rows. | | Item | An item is one row of a list: a media tile, a title with a line of detail, and something at the end. | | Kbd | Kbd shows a key of the keyboard as a small cap in the mono face. | | Lightbox | A lightbox shows the pictures of a gallery one at a time, as large as the window allows, over the whole page. | | Typography | One grotesque, Onest, in two voices: weight 700 with tight tracking for anything that names, weight 400 with open leading for anything that explains. | | Video Player | A video player is a film with the system's controls under it: play, the place in the film, captions, sound and full screen. | ### Conversation | Component | Use | | --- | --- | | Attachment | An attachment is a file or an image that travels with a message: a small tray with a tile, a name and one line about it. | | Bubble | A bubble is the surface of a message: a soft block of fill around what was said. | | Code Block | A code block sets code apart from prose: a tray in the mono face with a header that names it and copies it. | | Marker | A marker is a line in a conversation that is not a message: a date, a status, something the system did. | | Message | A message is one row of a conversation: who spoke, what they said, and what happened to it. | | Message Scroller | The message scroller is the window a conversation lives in: it keeps the newest message in view, and steps aside when the reader scrolls back. | | Questionnaire | A questionnaire asks a few questions one at a time, when an assistant or a flow needs answers before it can go on. | | Trace | A trace shows what an agent did on the way to an answer: one line per step, with its state and how long it took. | ### App shell | Component | Use | | --- | --- | | App Shell | The app shell is the frame of a product: the sidebar on a tray at the start edge, the top bar over the content, and one centred column for the page. | | Filter Bar | The filter bar sits over a list or a table: search at the start, filters as menus, sorting and the view at the end, and a chip for every filter that is on. | | Notification Center | The notification centre is the panel behind the bell: what happened while you were away, newest first, unread ones marked and counted on the bell. | | Page Header | The page header names the page: its title in `title`, one line about it, the page's actions at the end edge, and tabs for its sections underneath. | | Top Bar | The top bar is the row above the content: where you are at the start edge; search, notifications and the account at the end edge. | | User Menu | The user menu opens from the avatar at the end of the top bar: who is signed in, then the account's pages, the theme, help and signing out. | | Workspace Switcher | The workspace switcher is the button at the top of the sidebar that says which workspace you are in and opens the list of the others. | ### Metrics | Component | Use | | --- | --- | | Activity Feed | An activity feed is the record of who did what, newest first: a mark, one sentence and the time for each event, joined by a hairline. | | Stat Card | A stat card shows one number that matters: what it counts, the figure, how it moved, and optionally the line of its last weeks. | | Uptime | Uptime shows whether a service is working now and how it did over the last 90 days: its state in words, a bar per day, and the share of time it was up. | | Usage Meter | A usage meter shows how much of a plan's allowance is used: a Progress bar per limit, the numbers in words, and a note once a limit is near. | ### Billing | Component | Use | | --- | --- | | Billing Summary | The billing summary opens the billing page: the plan the workspace is on, what it costs and when it renews on an ink card, with the facts of the next invoice beside it. | | Checkout Summary | The checkout summary is the card beside a payment form: what is being bought, line by line, a place for a promo code, the total in the largest type, and the button that pays. | | Invoice List | The invoice list is the table of past invoices: number, date, amount, whether it was paid, and a button to download each. | | Payment Method | Payment method lists the cards on file as choices, marks the one that is charged, and takes a new card in three fields. | | Plan Comparison | The plan comparison is the full table under the pricing cards: every feature as a row, every plan as a column, a check, a dash or a number in each cell. | | Pricing Table | The pricing table sets the plans side by side: a card each with the name, the price as the largest thing on it, who it is for, one button, and what is included. One plan is yellow. | | Upgrade Prompt | An upgrade prompt stands where a feature would be when the plan does not have it: what the feature does, which plan has it, and one button to get it. | ### Account | Component | Use | | --- | --- | | API Keys | API keys lists the keys of a workspace with the secret masked, and shows a new key in full once, at the moment it is made. | | Auth Form | The auth form is the card a person meets before the product: sign in, create an account, or ask for a new password. One column, one yellow button. | | Integration Card | An integration card stands for one outside service the product can work with: its mark, its name, what connecting it does, and the control that connects it. | | Invite Form | The invite form takes several emails at once, a role for all of them, and sends the invitations. | | Notification Preferences | Notification preferences is a grid of checkboxes: what can happen down the side, the ways to be told across the top. | | Settings Section | A settings section is one topic of a settings page: its name and a line of explanation in a narrow column at the start edge, its controls on a card beside it. | | Team Members | Team members is the table of people in a workspace: who they are, their role, whether they have joined, and when they were last seen. | ### Onboarding | Component | Use | | --- | --- | | Changelog | The changelog tells people what changed in the product: one entry per release, the date at the start edge, a title, a tag for the kind of change, and a short list. | | Cookie Consent | Cookie consent is a raised panel in the corner of the first visit: what is stored and why, and three equal ways to answer. | | Feedback Widget | The feedback widget asks one question with a row of numbers, then offers a box for the reason, then says thanks. | | Onboarding Checklist | The onboarding checklist gets a new workspace to its first real result: a short list of tasks, the next one opened with its button, a bar that fills as they are done. | | Tour | A tour points at parts of a screen one at a time: a small raised panel beside the part, with a count, a sentence or two, and "Next". | ### Marketing | Component | Use | | --- | --- | | Call to Action | The call to action closes a page: one yellow card with the offer in a headline and the button that takes it. | | Feature Grid | The feature grid tells what the product does in a few cards of unequal size: each one a small icon tile, a title, and two lines. | | Footer | The footer ends every public page: the name and a line about the product, the site's links in columns, and a last row for the legal lines. | | Hero | The hero is the first screen of a product's public page: what it is in one headline, one sentence, one yellow button, and something real to look at beside them. | | Testimonial | A testimonial is a customer's own sentence about the product, set large, with who said it underneath. | ## The guidelines of every component Each component with its markup, in the order of the index. ### Button A button starts an action; the yellow one is the single most important action in view. #### Variants | Class | Use | | --- | --- | | `tray-btn` | Primary: `accent` fill, `on-accent` text. One per view. | | `tray-btn tray-btn--dark` | Solid `ink`. The main action on a yellow surface, or a second strong action. | | `tray-btn tray-btn--quiet` | Secondary: grey on white, white on a tray. The default for everything that is not the main action. | | `tray-btn tray-btn--ghost` | No fill until hover. Toolbars, dialogs, "Cancel". | | `tray-btn tray-btn--danger` | Deletes or cancels something for good. Never the only way to back out. | | `tray-btn tray-btn--link` | An action that reads as a link inside text. | #### Sizes `tray-btn` is 64px (`size-lg`, type `action`). Add `tray-btn--md` (56px, sits in a row with inputs), `tray-btn--sm` (48px, headers and toolbars) or `tray-btn--xs` (40px, tables and dense rows). `tray-btn--icon` makes it square; `tray-btn--block` full width; `tray-btn--split` pushes a value to the far end ("Order a jar … $59"). #### You provide - The label: a verb first, sentence case, no full stop ("Order a jar", "Save changes"). - For an icon-only button, an `aria-label`. - Use `` when it goes somewhere, `
No city by that name.
``` Typing narrows the list; the first match is highlighted. The anchor fires `tray:change` with `detail.value` when an option is taken. #### You provide The options, and the sentence shown when nothing matches (`tray-list__empty`). Say what to do next: "No city by that name. Check the spelling." #### Accessibility Focus stays in the input. Down and up move the highlight, Enter takes it, Escape closes the list; down also opens a closed list, and typing opens it with the first match highlighted. The input gets `role="combobox"`, `aria-autocomplete="list"`, `aria-controls` naming the list and an `aria-expanded` that follows it, and the list becomes a `listbox` named as the input is. The highlight is `aria-activedescendant`, so a screen reader reads each option as it is reached, and the option taken gets `aria-selected="true"`. Give the input a visible `
` of native radios: the `` asks the question, each number names its radio, `Tab` enters the group and the arrow keys move the choice. The tile under focus shows the 3px ink ring. Choosing a number shows the reason box and leaves focus where it is. Sending moves focus to the thanks, so it is read at once. The named ends sit outside the fieldset, so each end is tied to its radio: give each word of `tray-scale__ends` an `id` and point the first and the last radio's `aria-describedby` at it, as the example does, so "0" is read with "Not at all" and "10" with "Very". #### Do and don't - Do ask after the person finished something, not while they work. - Do let it be closed without answering, and do not ask again for a few months. - Don't use faces or stars for the scale. Numbers with named ends are read the same by everyone. - Don't make the reason required. ### Onboarding Checklist The onboarding checklist gets a new workspace to its first real result: a short list of tasks, the next one opened with its button, a bar that fills as they are done. #### Markup ```html

Get ready for the first order

Done2 of 5
  1. Add your products
  2. …
    Choose the courier days

    Orders placed after the cut-off wait for the next day.

``` #### Behaviour `data-tray="checklist"`: the first task without `data-done` becomes the current one (`aria-current="step"`) and shows its text and button; the others show their title only. A button with `data-task-done` marks its task done and moves on. The Progress follows by itself, and the element with `data-checklist-done` appears at the end. It fires `tray:change` with `{ done, total }` and `tray:complete` after the last task. Usually a task is done by doing it elsewhere in the product: set `data-done` from your own state and leave `data-task-done` for tasks finished on the spot. #### Accessibility It is a `
` named by its heading through `aria-labelledby`, and the tasks are an `
    `. The task to do now carries `aria-current="step"` and is announced as the current step, and the others show their title only. A done task says so in words as well as by its check and its line-through: the behaviour puts a hidden ", done" after each title, which a screen reader hears only while the task carries `data-done`. To word it otherwise, write your own `` in the title. The bar is a `role="progressbar"` with an `aria-label`, and the behaviour keeps its `aria-valuenow`, `aria-valuemax` and `aria-valuetext` ("2 of 5") up to date. When a `data-task-done` button finishes a task, focus moves to the next task's button. After the last task, whose button goes, focus moves to the `data-checklist-done` line, so it is read (or to the section when there is no such line). #### Do and don't - Do keep it to three to five tasks, each done in a minute or two. - Do start with a task that is already done, such as creating the account. - Don't list features to look at. Every task ends in something the workspace needs. - Don't keep the card after it is complete: let it be dismissed, then remove it. ### Tour A tour points at parts of a screen one at a time: a small raised panel beside the part, with a count, a sentence or two, and "Next". #### Markup ```html
    …the screen, with ids on the parts the tour points at…
    ``` #### Behaviour `data-tray="tour"` on the area that holds both the screen and the steps. Each `tray-tour` names its target with `data-for`; the step that is not `hidden` is the one shown. The current target gets a 2px dashed ink ring (`data-tour-on`) and the panel is placed under it, or over it when there is no room. Buttons carry `data-tour="next"`, `"back"` or `"skip"`; "next" on the last step ends the tour. The count is written for you. It fires `tray:change` with `{ step }` and `tray:complete` with `{ finished }`: remember there that the tour was seen. #### Accessibility Each step is a non-modal `role="dialog"` named by its heading through `aria-labelledby`, and the steps not shown are `hidden`. Next and Back move focus to the Next button of the new step. `Escape` in a step closes the tour, as Skip does. When the tour ends (Skip, `Escape` or the last Next), focus moves to the part the last step pointed at, or to the first control inside it, so it is not dropped to the top of the page. The page behind stays usable, and the steps come after the screen in the markup, so `Tab` reaches a step after the parts it points at. The ring on the target (`data-tour-on`) is dashed and stands further out than the focus ring, so the two are not confused; while the target has focus, the focus ring shows instead. The ring is not read, so name the part in the words of the step. The count ("2 of 3") is plain text, not a live region. #### Do and don't - Do keep a tour to three or four steps, and let it be skipped from every step. - Do point at things the person will use today. - Don't start a tour over a screen that is still empty: show the Empty state or the Onboarding Checklist first. - Don't dim the page behind it. The ring is enough, and the screen stays usable. ### Call to Action The call to action closes a page: one yellow card with the offer in a headline and the button that takes it. #### Markup ```html

    Pack tomorrow's orders with Counter

    Free for 14 days. Your products and customers stay yours.

    ``` The text sits at the start edge, the buttons at the end edge on the same baseline; when there is no room the buttons drop under the text. On yellow the main button is `tray-btn--dark` and the second is quiet. To collect an email instead, replace the buttons with an Input Group whose button is the action: ```html
    ``` #### Accessibility It is a `
    ` opened by a heading, so the offer is in the page's list of headings. Its buttons are links when they lead to another page, and their words, not the yellow, say what happens. On the yellow card every colour keeps the light palette and the focus ring takes the card's own ink, so it shows in every theme. When the card collects an email, the field has a `