# 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
```
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: `