Design Sources

Nothing in the app's interface is designed from memory. A surface is laid out after looking at how the best shipped product arranges the same screen, drawn in tokens whose values come from a design system that explains why they work, and given the keyboard contract a published accessibility pattern describes. This page is the one list of those sources, with what each one gave the app, so an idea that shaped a surface is never lost when the surface is rewritten.

The rules that use these sources live elsewhere: where an action goes is the ux skill's, the design pass every unit of the UI library walks is the ui-library skill's, and the look itself is the design language's. This page only says where to look, and in what order.

The order they are consulted in

flowchart TD
  N[A surface to design or judge] --> R{Does a reference product do this screen?}
  R -->|yes| RP[Match its hierarchy, wording and interaction]
  R -->|no| G[A gallery of shipped screens: how several products arrange it]
  RP --> D[The design systems: what the look should be, drawn in our tokens]
  G --> D
  D --> B[Usability references: whether it interrupts, where it sits, how fast it answers]
  B --> A[Accessibility patterns: the keyboard and ARIA contract]
  A --> P[Platform documents: the browser feature that implements it]
  P --> C{Better than the reference, or only like it?}
  C -->|only like it| D
  C -->|better, and every flow kept| U[Handed to the user to check by eye]

The last gate is the design pass's own question. Matching the reference product is the floor; a departure from it has to say how it is better, and it is argued in the commit body with the source it came from.

Reference products

Each product area follows one product that already solved its domain, so its arrangement, its copy and its behaviour are taken rather than reinvented. A screenshot of the reference product handed over in a conversation is the specification for that surface (the ux skill).

Design systems

These are where the look comes from: the palette's structure, the surfaces, the type, the motion and the density. A value in the tokens is chosen against one of them, never picked by eye alone.

Galleries of shipped screens

• Mobbin — a library of real app and web screens and flows, for how several products arrange the same thing when no one reference product owns it.

Usability

Accessibility

• WAI-ARIA Authoring Practices — the keyboard contract of every library component: the menu button, listbox, combobox, modal dialog, grid, date picker dialog, breadcrumb and disclosure navigation patterns.
• WCAG 2.2 contrast minimum — the ratio every foreground token is tested against on every surface token.
• MDN on forced colours, reduced motion and colour scheme — why a shadow-drawn edge also carries a transparent border, why the motion tokens are the one reader of the preference, and how the theme follows the system.
• Game accessibility guidelines — the agent console's keys and its pause menu.

Platform

• The top layer — the Popover API, the top layer and anchor positioning, which every menu, select, tooltip and dialog is built on, and Chrome's entry and exit animations, for how they arrive and leave.
• The document's chrome — scrollbar colour, easing functions and the context menu event.
• The headless layer — Vuetify 0's building frameworks, styling, theming and testing guides: behaviour and ARIA in the primitive, the look in our wrapper, state reaching the style as data attributes.
• Dates — Temporal, whose plain dates every calendar walks so a time zone never moves a day.
• The icon engine — UnoCSS's icons preset, which turns a whole icon class into one masked SVG rule.

Notes

• A proposal lists the sources it draws on in its own Sources section, and they join this page when it ships, since this page names only what a shipped surface took from somewhere. A source weighed and not taken stays with the decision that weighed it, as Reka UI does on the UI library page.
• A new source is added the day a surface takes something from it, with the one line saying what it gave. A link without that line is a bookmark, and it is not kept.

Key files