--- name: shine description: >- Design, build, or audit interfaces using real template structure, complete interaction contracts, measured craft rules, and browser proof. Use for any UI or UX work: web pages, dashboards, tables, forms, landing pages, charts, HTML artifacts, email, Salesforce Lightning, prototypes, mockups, wireframes, design reviews, or visual polish. --- # Shine — self-contained design authority All 30 Shine references are inlined below. Nothing to install, no corpus to clone, no other file to open. Adapted from Shine v4.0 (github.com/justinfowler925/shine, MIT). **Not in this file:** the 14 blueprint region maps (records, settings, wizards, marketing, checkout, blog, and the Salesforce Lightning set) and their four authored `page.tsx` sources. Rows marked *blueprint* in the template catalog name a real screen, but you build from the catalog row and the rules here rather than a bundled region map. Those files ship in the plugin bundle at github.com/justinfowler925/shine. ## Contents - [The loop — how to find what is wrong](#the-loop-how-to-find-what-is-wrong) - [Wireframe — discovery before build](#wireframe-discovery-before-build) - [Direction — art direction before code](#direction-art-direction-before-code) - [Templates — start from a real page](#templates-start-from-a-real-page) - [Component contracts — what every named control owes](#component-contracts-what-every-named-control-owes) - [Foundations — tokens, states, accessibility floor](#foundations-tokens-states-accessibility-floor) - [Taste — measured thresholds and failure tells](#taste-measured-thresholds-and-failure-tells) - [Color and type — the method](#color-and-type-the-method) - [Motion — durations, easing, reduced motion](#motion-durations-easing-reduced-motion) - [Layout — structure as information](#layout-structure-as-information) - [Patterns — screen archetypes](#patterns-screen-archetypes) - [Techniques — craft transfer](#techniques-craft-transfer) - [Interaction — keyboard and pointer behavior](#interaction-keyboard-and-pointer-behavior) - [Anti-patterns — lane-relative](#anti-patterns-lane-relative) - [Voices — three legal paints](#voices-three-legal-paints) - [Kits — which library, and worked recipes](#kits-which-library-and-worked-recipes) - [Dashboards — surfaces that answer questions](#dashboards-surfaces-that-answer-questions) - [Data visualization — encoding rules](#data-visualization-encoding-rules) - [AI surfaces — topologies](#ai-surfaces-topologies) - [Copy — the presentation layer as an argument](#copy-the-presentation-layer-as-an-argument) - [Adoption — will anyone open it](#adoption-will-anyone-open-it) - [Voice — surfaces that speak or listen](#voice-surfaces-that-speak-or-listen) - [Brand mode — the adapter](#brand-mode-the-adapter) - [Salesforce — Lightning and SLDS 2](#salesforce-lightning-and-slds-2) - [Performance — budgets and thresholds](#performance-budgets-and-thresholds) - [Imagery — anti-stock rules](#imagery-anti-stock-rules) - [Ecosystem — libraries, licenses, maintenance](#ecosystem-libraries-licenses-maintenance) - [Cross-media — decks, PDFs, reports, and email](#cross-media-decks-pdfs-reports-and-email) - [Usability proof — executable, not inferred](#usability-proof-executable-not-inferred) - [Audit — rubric and report template](#audit-rubric-and-report-template) Shine is a design authority: it replaces invented layouts, remembered APIs, and "looks good to me" with real template structure, explicit contracts, measured craft thresholds, and proof in a rendered browser. Build the interface directly in the current task; the sections below decide, you supply brief-specific judgment. ## Non-negotiables 1. **Render before opining.** Never diagnose, praise, or fix a screen you have not seen rendered in a browser. Screenshot it and read the screenshot. 2. **Match a template, never invent a page.** Every known job (dashboard, queue, record, settings, auth, checkout, landing, wizard…) has a row in [§ Templates](#templates-start-from-a-real-page). Clone the selected row's regions; put its id on the artifact as `data-cite`. 3. **Named controls owe their contract.** A data table, form, dialog, or select gets the full MUST list from [§ Component contracts](#component-contracts-what-every-named-control-owes). Every data grid includes search, sorting, filters, column visibility, pagination, selection, row actions, and loading/empty/filtered-empty/error states. A hand-built `` is allowed only for static presentation. 4. **Tokens, not raw values.** Declare colors, radii, shadows, tracking once as custom properties; usage sites say `var()`. In an existing repo, use the project's installed design system and tokens — never introduce a second one. 5. **One primary action per view.** Count the filled controls; more than one is a hierarchy defect. 6. **Usability is executable, not inferred from craft.** The primary job must be walkable in the browser and change observable state ([§ Usability proof](#usability-proof-executable-not-inferred)). 7. **Never invent a library API.** Fetch the official docs or read the installed source before writing a prop or component name. 8. **Direction is a contract.** Before paint, name the composition archetype, image strategy, signature moment, and the prior family or silhouette this output must not repeat. ## Route the request | Situation | Mode | Start at | |---|---|---| | New surface, no UI yet (or user says wireframe/sketch/low-fi) | **Wireframe** | [§ Wireframe](#wireframe-discovery-before-build) — discovery → gray-box → locked brief | | Locked brief exists, or building from an existing shell | **Build** | [§ Direction](#direction-art-direction-before-code), then build | | Existing surface, upgrade in place | **Polish** | [§ The loop](#the-loop-how-to-find-what-is-wrong) | | "Review / audit / what's wrong" — change nothing unless asked | **Audit** | [§ Audit](#audit-rubric-and-report-template) | | Persuasive or instructional words are the problem | **Copy** | [§ Copy](#copy-the-presentation-layer-as-an-argument) | | Internal tool nobody opens | **Adoption** | [§ Adoption](#adoption-will-anyone-open-it) | Default: Wireframe if new; otherwise Build unless the ask is clearly a review. ## The loop (Build / Polish) **LOOK → NAME → MATCH → RESTRUCTURE → REPAINT → PROVE** — the full procedure is [§ The loop](#the-loop-how-to-find-what-is-wrong). - LOOK: render, screenshot, read it. Identify the surface kind and lane (internal / saas / lex / marketing). - NAME: 3–8 evidence-backed defects across usability, completeness, composition, craft — fix in that priority order. Never paint while a usability or completeness hole is open. - MATCH: pick the [§ Templates](#templates-start-from-a-real-page) row for the job; open its real source (public shadcn registry, bundled blueprint region map, or public demo). - DIRECT: declare the archetype, image strategy, signature moment, and anti-repetition rule. Cap the page shortlist at one candidate per visual family; pages outrank component demos. - RESTRUCTURE: clone the template's regions, keep the focal object focal. - REPAINT: pick the voice ([§ Voices](#voices-three-legal-paints)) — kit-faithful by default, house as fallback, brand when locked ([§ Brand mode](#brand-mode-the-adapter)). - PROVE: see below. For a new standalone surface, write the information hierarchy and primary workflow down (a short `DESIGN.md`, per [§ Direction](#direction-art-direction-before-code)) before building. Ask discovery questions only when missing product decisions would materially change the result. ## Prove — before claiming anything is done 1. Render the result in a real browser (open the HTML file, or run the app). 2. Screenshot and **read** the screenshot — before/after for fixes. 3. Exercise the primary workflow yourself: click, fill, submit. The DOM must visibly change. A static dashboard, a decorative control, or a flow that changes nothing fails. 4. Check contrast by computing it on suspect pairs: text ≥4.5:1, non-text UI parts ≥3:1 (WCAG 1.4.3 / 1.4.11). Text over gradients or imagery gets checked against its worst-case pixel, not the average. 5. Compare the result against the cited template — they should read as relatives. 6. Report: the selected template id, workflow result, contrast findings, screenshot paths, and anything not completed. Report failures plainly; never claim an unrendered or unexercised surface works. ## Ten craft rules (measured, not asserted) Full evidence and the 90 failure tells: [§ Taste](#taste-measured-thresholds-and-failure-tells). 1. Accent chroma OKLCH 0.13–0.24 at L 55–65; large-area fills ≤0.08. (Tailwind's `-600` row at 0.245–0.288 is the "AI look" tell.) 2. Adjacent surfaces differ ~2pp lightness; borders carry separation, not fill jumps. ≥6pp is a smell. 3. Two type ratios: ~1.12 for the UI band, ~1.22 for display. One ratio is why generated scales feel wrong. 4. Tracking depends on size *and* weight: 0 in the 14–16px band, crossing negative at 20–24px, −0.02 to −0.035em by 48px; all-caps labels +0.05em. 5. Line-height peaks at body (~1.5 @16px) and falls both directions; floor 1.33. Dense UIs cut padding, never leading. 6. Shadows: ≥2 layers, top-layer alpha ≤6% light (~4× in dark), blur ≥8px carries spread ≈ −blur/4. Overlays open with a `0 0 0 1px` hairline ring. 7. Flat-with-border is the default in product UI; shadow only for things that float. 8. Radii nest: `child = parent − padding`. Enterprise/LEX data surfaces: radius none or host tokens. 9. Motion: 100–150ms micro, 150–250ms standard, 200–300ms overlays; exits ~20% faster; ease-out; honor `prefers-reduced-motion`. Never `transition: all`. 10. Dark mode is never `#000`; tinted near-black with raised surfaces. Neutrals are hue-consistent: either chroma-0 or a slight consistent cast — never mixed. --- ## The loop — how to find what is wrong The loop's procedure. Thresholds live in [§ Taste](#taste-measured-thresholds-and-failure-tells)/SKILL; this file is the order of operations so every fix starts from a named defect and ends with a source. #### 0. Route first - **No existing UI** (new screen/page/tool), or the user said wireframe/sketch/low-fi → [§ Wireframe](#wireframe-discovery-before-build) before anything here. - A `shine-wireframe/.brief.md` with `Status: LOCKED` → structure is given; do not invent a competing IA unless the user says `unlock structure`. - **Internal tool / cockpit / digest** → [§ Adoption](#adoption-will-anyone-open-it) before pixels. A surface nobody opens is a design defect, not a training problem. #### 1. LOOK — render before opining Render the page in a real browser and **take a screenshot, then read it**. For an HTML file, open it directly; for an app, run it and navigate to the surface. A page you have not seen gets no opinions. Note what you actually see — not what the source suggests. | Kind | Signals | First refs | |---|---|---| | Internal tool / cockpit | Auth'd app, queues, metrics for a ritual | [§ Adoption](#adoption-will-anyone-open-it) first | | Product app shell | Nav, tables, forms, settings | [§ Patterns](#patterns-screen-archetypes), [§ Component contracts](#component-contracts-what-every-named-control-owes) | | Dashboard / forecast | KPIs, charts, "what needs me" | [§ Dashboards](#dashboards-surfaces-that-answer-questions), [§ Data visualization](#data-visualization-encoding-rules) | | AI / agent surface | Model does work a human owns | [§ AI surfaces](#ai-surfaces-topologies) | | Marketing / landing | Hero, CTA, persuasion | [§ Patterns](#patterns-screen-archetypes) (hero budget), [§ Copy](#copy-the-presentation-layer-as-an-argument) | | Brand-locked | Client-facing or brand lock | [§ Brand mode](#brand-mode-the-adapter) | | Speaks or listens | TTS, mic, read-aloud | [§ Voice](#voice-surfaces-that-speak-or-listen) | | Native / macOS / iOS | Desktop chrome, HIG language | Apple HIG (fetch it) | | Lightning / LWC | Record page, console, datatable | [§ Salesforce](#salesforce-lightning-and-slds-2) | Two kinds → run the stricter first (adoption before craft; contracts before polish). #### 2. NAME — four buckets, usability first Write 3–6 defects, each in one bucket. Craft without a usability or completeness defect above it is the wrong pass. ##### Usability (can they finish the job?) - Primary action visible in ~3 seconds? Competing CTAs? - Path: notification → committed change — where does the user invent the next step? - Empty / error / loading as real states, not voids? - Hover-only actions; no keyboard path to finish? - The job of the screen vs what the layout actually offers. ##### Completeness (contracts) Named Table / Form / Dialog / Select loads [§ Component contracts](#component-contracts-what-every-named-control-owes) MUST **in this pass**. - A `
` with two or more header cells **is** a named Table. Missing `data-shine-contract="table"` does not exempt it. Only `data-shine-contract="layout"` (or `role="presentation"`) opts out. - Named control below MUST (bare `
`, unlabeled icon button, placeholder-as-label) - Missing states: loading / empty / filtered-empty / error - Destructive without confirm; double-submit; toast-only errors ##### Composition (what per-element gates cannot see) - **Scan order** — in 3 seconds, what do you read? Is that the job? - **Weight budget** — one primary, few secondary. Count filled controls. - **Focal object** — dashboards need one; six equal modules is an index. - **Chrome vs content**; largest region empty; sections with three jobs. - **Collisions** — one token two meanings; type steps that aren't distinguishable. ##### Craft (of the chosen voice) - Raw values at usage sites; off-scale spacing; tracking 0 on display type - House accent chroma outside 0.13–0.24; kit-faithful drifting back to house paint - Theme undeclared or non-switching; contrast fails; `transition: all` - Refs: SKILL ten rules, [§ Taste](#taste-measured-thresholds-and-failure-tells), [§ Color and type](#color-and-type-the-method), [§ Motion](#motion-durations-easing-reduced-motion), [§ Foundations](#foundations-tokens-states-accessibility-floor) #### 3. Prioritize 1. Usability — they cannot finish the job 2. Completeness Critical — a11y blockers, data-state triad, wrong primary 3. Composition that causes wrong actions or abandonment 4. Adoption blockers on internal tools 5. Craft that reads as slop for the chosen voice 6. Polish (density, optical alignment, micro-motion) Never spend a pass on craft while a Critical completeness hole is open. #### 4. MATCH — a template, not a vibe Open [§ Templates](#templates-start-from-a-real-page), find the rows whose Jobs match the screen's job in plain words, read the selected row's real structure (registry source, bundled blueprint, or public demo), pick one of the best 2–3 matches and say why. A page with no template cite is incomplete for a *known* job — dashboards, queues, records, settings, auth, checkout all have rows. No matching row → nearest row + [§ Patterns](#patterns-screen-archetypes), and say so. Technique cites ([§ Techniques](#techniques-craft-transfer)) are for craft transfer; they don't replace a structural match. A record list (queue, remainder, sources, admin rows) cites a DataGrid row (`untitled-table`, or `shadcn-dashboard-01` for the composed records page). A list/dashboard/app-shell cite is the wrong match for a record list even if it looks closer — re-check the datagrid rows. #### 5. RESTRUCTURE + REPAINT Clone the template's regions from its source; keep the focal object focal. Then paint by voice ([§ Voices](#voices-three-legal-paints)): kit-faithful uses the kit's real token values; house uses a dark-first single-accent editorial system; brand keeps regions and drops vendor chrome. Upgrade stubs to the contract ladder. Prefer one composition change over ten craft tweaks. #### 6. PROVE Render the result in a real browser and: 1. Screenshot before and after, and read both. 2. Walk the primary workflow yourself (click, fill, submit) — the DOM must visibly change. 3. Check contrast on every suspect text/background pair (compute it, don't eyeball it — text ≥4.5:1, non-text UI ≥3:1). 4. Compare the after-shot to the cited template's structure — the two should read as relatives. If they don't, the match or the paint is wrong. Report before/after evidence for every Critical/Major you claimed to fix, plus the shot paths. Never claim a defect fixed without having looked at the rendered result. #### Quick defect → next file | You see… | Open | |---|---| | No UI yet / need a sketch | [§ Wireframe](#wireframe-discovery-before-build) | | Known job, invented layout | [§ Templates](#templates-start-from-a-real-page) — match a row | | Nobody will open this | [§ Adoption](#adoption-will-anyone-open-it) | | Table/form missing states | [§ Component contracts](#component-contracts-what-every-named-control-owes) | | Queue / batch / empty | [§ Templates](#templates-start-from-a-real-page) `untitled-table` | | Wrong hierarchy / equal peers | [§ Techniques](#techniques-craft-transfer) §Hierarchy, [§ Kits](#kits-which-library-and-worked-recipes) | | Numbers undecidable | [§ Dashboards](#dashboards-surfaces-that-answer-questions) | | Chart encoding smell | [§ Data visualization](#data-visualization-encoding-rules) | | AI chat as default shell | [§ AI surfaces](#ai-surfaces-topologies) | | Words don't persuade | [§ Copy](#copy-the-presentation-layer-as-an-argument) | | Raw values / tokens | [§ Foundations](#foundations-tokens-states-accessibility-floor), [§ Color and type](#color-and-type-the-method) | | Need a library API | fetch the library's official docs — never invent an API | | Lightning host quirks | [§ Salesforce](#salesforce-lightning-and-slds-2) | --- ## Wireframe — discovery before build Default for a **new** surface with no existing UI. Explicit triggers: “wireframe”, “sketch”, “low-fi”, “discover the layout”, “new screen”. Wireframe discovers **structure** with the user by picking a catalog template ([§ Templates](#templates-start-from-a-real-page)), then citing kits. It emits a gray-box HTML artifact whose regions come from that template, then a **locked brief**. Build applies the cited template's DNA and does not invent a competing IA unless the user says `unlock structure`. **Not Wireframe:** craft (chroma, tracking, shadows), brand paint, real charts, or shipping React. Craft judgments wait until Build. --- #### When to enter / skip | Enter | Skip | |---|---| | New screen/page/tool, no UI yet | Polish/Audit of an existing surface | | User says wireframe / sketch / low-fi | Locked brief already exists and user wants paint only | | Redesign-from-scratch where structure is undecided | Tiny component stub inside a known shell | --- #### Discovery script **One question per turn** (or one tight cluster). Always end with **2–3 options + a recommendation** (mandatory default + cite). Max **~8 discovery turns**, then force a draft gray-box — do not interview to death. ##### Turn budget | Turns | Goal | |---|---| | 1–2 | Intent: job of the screen; who opens it; ritual if internal ([§ Adoption](#adoption-will-anyone-open-it) lite) | | 2–3 | **Catalog pick** — match the job to a [§ Templates](#templates-start-from-a-real-page) row (default start-from) + pattern from [§ Patterns](#patterns-screen-archetypes). Open the row's source (registry item, bundled blueprint, or public demo). | | 3–6 | Structure forks still undecided after the template (nav collapse, states) | | ≤8 | Emit/update gray-box; keep iterating on the HTML | | Lock | Write `*.brief.md`; hand off to Build | ##### Every suggestion must cite | Kind | Form | |---|---| | Catalog template | [§ Templates](#templates-start-from-a-real-page) id — **required on every region** | | Pattern | [§ Patterns](#patterns-screen-archetypes) § name | | Kit recipe | [§ Kits](#kits-which-library-and-worked-recipes) recipe + the kit's official docs | | Technique | [§ Techniques](#techniques-craft-transfer) § + product | | Novel only | nearest catalog row + [§ Patterns](#patterns-screen-archetypes) principle — name both | Banned: “we could do a sidebar” with no source. Gray-box regions come from the chosen template, not from anonymous layout ideas. `data-cite` on every region includes the [§ Templates](#templates-start-from-a-real-page) id. ##### Recommendation format (every fork) ``` Recommend:
` markup — unless user says simple/static/presentation. A `
` with two or more header cells is a named Table whether or not it carries `data-shine-contract="table"`. That attribute documents; it does not opt in. Opt out with `data-shine-contract="layout"` or `role="presentation"`. An unmarked data table still owes the full contract. ##### Anatomy (enterprise data table) 1. Title + optional description 2. Toolbar (global actions) 3. Column headers 4. Rows 5. Pagination bar (or virtualized scroll end) ##### MUST - **Chrome:** title (or page-level title); toolbar with search and/or filters; sticky header; horizontal scroll when needed; lead/primary column visually distinct - **Sort:** per-column asc/desc/unsorted; header indicator; header is a button - **Filter:** column filters and/or toolbar global search; clear path; filtered-empty distinct from true-empty - **Pagination** (page size, range text, total or equivalent) **or** virtualized scroll for large sets — pick one and complete it - **Column resize** (drag; keyboard when using Aria-style grid) - **Row actions:** inline if <3 actions, else overflow menu; not hover-only (persist on touch) - **States:** loading/skeleton (keep header); empty + CTA; filtered-empty; error + retry - **A11y:** consistent table or grid semantics; selection announced if present; keyboard path complete for chosen model - Client vs server mode for sort/filter/page made explicit when data is remote ##### SHOULD (app/admin default) - Row selection: none / single / multi; header select-all with **page vs all-filtered defined**; selected count; **batch action bar** - Column visibility menu (persist if app has prefs) - Density: compact / default / comfortable - Active filter chips + Clear all - Sticky first/lead column when horizontal scroll is heavy - Server-side hooks: total count, debounce, race-safe fetches ##### ASK (never silent) - Cell editing, tree/hierarchical rows, row expand detail panels - Column pin, drag-reorder rows/columns, multi-sort - Grouping, aggregation, pivot - Excel/CSV export, realtime push updates - Virtualization thresholds / infinite query design details ##### Presentation table (only when user opts out) - Semantic table, clear headers, responsive overflow, empty state — no fake toolbar chrome --- #### List / Virtualized list **MUST** - Stable keys; loading / empty / error - Selection model if selectable; keyboard operable **SHOULD** - Virtualize when N is large; infinite load with sentinel + busy + end - Typeahead for long selectable lists --- #### Tabs / Accordion / Disclosure **MUST — Tabs** - Tablist + tab + tabpanel; one selected; arrows + Home/End; manual or automatic activation - Disabled tabs; associated panels **MUST — Accordion** - `aria-expanded` / `aria-controls`; Enter/Space; single or multi expand explicit **SHOULD** - Tabs overflow (scroll or “more”); deep-linkable selected value --- #### Menu / Dropdown / Context menu / Command palette **MUST — Menu / Dropdown** - Trigger + portal; focus inside; Escape + outside dismiss; restore focus - Items: icons, shortcuts, separators, disabled, destructive styling, submenus - Typeahead; roving focus; `aria-haspopup` / `aria-expanded` **MUST — Context menu** - Secondary-click / long-press; position near pointer; same item model **MUST — Command palette** - Global shortcut (⌘K / Ctrl+K); fuzzy search; grouped commands; keyboard-only complete path; empty + loading states --- #### Navigation: Sidebar / TopNav / Breadcrumbs / Pagination / Stepper **MUST — Sidebar** - Active route; nested sections; expand/collapse; icon+label; keyboard; mobile drawer variant **MUST — TopNav** - Brand, primary links, utilities; active state; overflow strategy **MUST — Breadcrumbs** - Hierarchy links; current page non-link; collapse middle when long **MUST — Pagination (standalone)** - Page size, range text, disabled edges; compact on mobile **MUST — Stepper** - States: complete / current / upcoming / error; linear vs optional explicit --- #### Dialog / Modal / Drawer / Sheet / Popover / Tooltip / Toast **MUST — Dialog / Modal** - Role dialog; labelled title; focus trap; initial focus; Escape; restore focus - Explicit close; footer primary/secondary; scrollable body when needed - Scrim click: block or warn if dirty/destructive **MUST — Drawer / Sheet** - Same focus rules; edge anchor; mobile dismiss pattern **MUST — Popover** - Anchored; dismissable; don’t steal focus for pure info **MUST — Tooltip** - Hover/focus only; delay; never required info; no interactive content (use Popover) **MUST — Toast** - Short message; optional action; auto-dismiss + pause on hover/focus; `aria-live` by severity - Never the only channel for blocking errors --- #### Card / Panel / Section header **MUST** - Title; optional description; optional actions; content slot - If clickable: one clear target (whole card **or** nested buttons — not both competing) **SHOULD** - Section header aligned to page grid with consistent action placement --- #### Toolbar / Action bar / Filter bar / Batch bar **MUST** - Clear grouping: left = title/search/filters; right = primary actions - Overflow when actions > ~5 - Batch bar when selection > 0: count + actions + clear selection **SHOULD** - Sticky under page header when content scrolls - Active filters as dismissible chips + Clear all --- #### Avatar / Badge / Chip / Status **MUST** - **Avatar:** image / initials / icon fallback; sizes - **Badge:** numeric or dot; max (“99+”); never color-only meaning - **Chip/Tag:** label; dismissible when removable; selected state when toggles - **Status:** color **and** text/icon; semantic mapping (success/warn/error/info/neutral) --- #### Progress / Spinner / Skeleton **MUST** - Determinate vs indeterminate clear; labeled when meaningful - Skeleton mirrors layout; region `aria-busy` - Prefer skeleton for content panels; spinner for actions/buttons --- #### Empty / Error / Alert / Banner **MUST** - **Empty:** title, body, primary CTA (and optional secondary) - **Error:** what failed, retry/support; visually ≠ empty - **Alert:** severity, in-context, optional dismiss - **Banner:** page-level; critical banners not casually dismissible --- #### File upload **MUST** - Click + drag-drop; accept types; max size/count; multiple when needed - Per-file progress, cancel, remove; errors per file - Keyboard-operable drop zone **SHOULD** - Image preview; retry failed files; paste support where relevant --- #### Charts / metric cards **MUST** - Title, units, legend as needed; loading / empty / error - Tooltip or focus access to values; not color-only encoding - Metric card: value, context/period; optional delta **SHOULD** - Responsive container; tabular/summary fallback when chart is dense --- #### Chat / composer (OpenAI Apps SDK–informed) **MUST** - Composer always reachable in immersive views - Auto-grow textarea; send disabled when empty or streaming - Message list with roles; streaming state; failed-turn retry - Empty conversation state - Attachments affordance when product supports files - Markdown/code rendering with copy for code blocks when shown **SHOULD** - Stop/regenerate; virtualized history; attachment preview/progress **ASK:** retention, model picker, tool-call UX specifics --- #### Authority cheat-sheet | Need | Reference model | |---|---| | Interaction/a11y | React Aria + WAI-ARIA APG | | Enterprise form/table API | this file's § Form and § Table MUST lists | | Product table anatomy | this file's § Anatomy, proven by `untitled-table` | | React DataGrid batteries | TanStack Table ^8 | | Composable React stack | shadcn + Radix + TanStack Table/Form | | Visual variants | Untitled UI / Plus UI | | Chat embeds | OpenAI Apps SDK UI | --- ## Foundations — tokens, states, accessibility floor Visual and interaction floor for every UI. Behavior completeness lives in [§ Component contracts](#component-contracts-what-every-named-control-owes). Brand tokens override the neutrals in brand mode ([§ Brand mode](#brand-mode-the-adapter)). #### Tokens Prefer semantic CSS variables over scattered hex/Tailwind literals: ```css :root { --bg: /* canvas */; --bg-subtle: /* sections, zebra */; --fg: /* primary text */; --fg-muted: /* secondary text */; --border: /* dividers, inputs */; --primary: /* brand / main action */; --primary-fg: /* on primary */; --danger: /* destructive */; --success: /* positive */; --warning: /* caution */; --info: /* informational */; --ring: /* focus ring */; --radius-sm: 4px; --radius-md: 8px; --radius-lg: 16px; --radius-full: 999px; --shadow-sm: /* raised tile — 2 layers, no ring */; --shadow-md: /* dropdown, popover, toast */; --shadow-lg: /* modal, command palette */; --space-1: 4px; /* 8pt rhythm: 4/8/12/16/24/32/48/64 */ } ``` - Map project brand colors into these semantics; don’t invent a second palette mid-feature. - Support light (default) and dark only if the product already has dark — don’t add dark “for free.” - **One token, one meaning.** An accent that also marks the active filter, or a status color spent on a categorical chart series, is a vocabulary collapse that every per-element gate passes. If two things need to look different, they need two tokens. ##### Direction and data tokens ```css --direction-good /* sentiment, not arrow direction */ --direction-bad --direction-flat --chart-1 … --chart-8 /* Okabe–Ito colour-universal categorical set */ ``` - **Which way is good is a property of the metric, not the palette.** Up is bad for churn, DSO, cycle time, cost per lead, backlog. Every metric declares its own `goodDirection` and the *sentiment* gets the color — never hardcode up=green. - **Colour never carries direction alone.** ~8% of men have a red/green deficiency, and colour-only meaning is a WCAG 1.4.1 failure. Pair with a glyph (▲ ▼) and a word where space allows. - **Chart series are categorical, not semantic.** Never spend danger/success/warning on an ordinary series — readers will read alarm into it. Beyond 8 categories, use small multiples rather than more hues. - The `personal` lane ships light-mode variants for the chart ramp, because five of the eight published Okabe–Ito hexes fall below 3:1 on a light canvas. **The `brand` lane has no chart ramp** — that is an open token gap needing brand approval, not a licence to invent hexes. ##### Elevation tokens ```css --shadow-sm /* 2 layers, no ring — a raised tile */ --shadow-md /* hairline ring + 2 blur layers — dropdown, popover, toast */ --shadow-lg /* hairline ring + 3 blur layers — modal, command palette */ ``` - Each level **is** Rules 6 and 7, pre-satisfied: ≥2 layers, every layer blurred ≥8px carries `spread = −blur/4`, and `md`/`lg` open with the `0 0 0 1px` hairline ring so a token user cannot ship the mushy edge a bare drop shadow gives. - **`sm` has no ring on purpose.** A resting card takes `--border`; a ring there doubles the hairline. Flat-with-a-border stays the default in product UI — reach for `md`/`lg` when something genuinely floats. - The `personal` lane is dark-first, so the default value carries **4× the light alpha** (24% top layer vs 6%). Ship only the light values into a dark UI and every overlay reads flat. - The `brand` lane tints the shadow **anchor navy**, not black, per brand — and has no dark variant, because the lane has no dark mode. - Never hand-roll a `box-shadow` at a usage site. A focus ring (`0 0 0 Npx`) and an `inset` highlight are not elevation and are fine. ##### Tracking tokens ```css --tracking-xs /* 0.0078rem, +0.010em at 12px */ --tracking-sm /* 0 */ --tracking-base /* 0 — the neutral band is 14–16px */ --tracking-lg /* -0.0078rem */ --tracking-xl /* -0.0156rem */ --tracking-2xl /* -0.0344rem, −0.020em at 28px */ --tracking-caps /* +0.050em at 12px — all-caps labels (a brand whose UI face is uppercase may want 0.12em) */ ``` - **Keyed to the type scale, not named tight/normal/wide.** Rule 4 is a curve, so `tracking-lg` is the one that belongs with `text-lg`, and a mismatched pair is visible in a diff. `letter-spacing: 0` at every size is the tell this exists to remove. - `rem`, not `em`: DTCG's dimension type admits `px` and `rem` only, and the measured curve these come from is itself published per-size in rem. The em equivalents are in the comments so the tie back to Rule 4's figures stays checkable. - Never write a literal `letter-spacing` at a usage site. `normal`, `var()` and `calc()` are fine. ##### Known token gaps — say so, don't hardcode around them | Gap | Consequence | |---|---| | **No chart ramp in the `brand` lane** | The eight-series categorical set exists in `personal` only. A branded chart needs approved hues; inventing them here would be the vocabulary collapse this file warns about one section up. Say the gap out loud and ask. | Shadow, tracking and the `text-sm`/`text-base` collision were all on this list until 2026-08-09. Two of them mattered more than they read: **a missing token manufactures the escape hatch that blinds the gate.** With no shadow token, shipping any shadow meant a raw `rgba()` at the usage site, so the only route was ignoring the rules entirely — and once one rule is being ignored, colour and type discipline go with it. The gap did not just leave one rule unenforced; it taught people to disable the rest. Fill the gap at the token layer instead — that is the other half of the same fix. #### Typography - Define roles: display, title, body, label, caption, mono. - One UI sans for product chrome unless brand specifies otherwise. - Avoid Inter/Roboto/Arial as *expressive* marketing display when no brand is set — pick a distinctive pair. (Exception: a brand that licenses those faces — see brand.md.) - Body ~16px, line-height ~1.5–1.6; tight tracking on large display only. - Don’t size meaning with color alone; weight and size establish hierarchy. #### Spacing & layout - **8pt rhythm** (4px half-step allowed). - Page: consistent max-width or full-bleed app shell — don’t mix randomly. - Section gaps larger than component gaps (e.g. 48–96px marketing sections; 16–24px app content stacks). - Align columns to a grid; avoid one-off magic margins. - Density: comfortable for marketing; compact available for data-heavy app views. #### Hierarchy - One primary action per view (or per obvious region). - Progressive disclosure for density — hide advanced filters until needed. - Title → supporting → content → actions reading order. - Don’t compete: hero CTA vs five equal buttons = broken hierarchy. #### Elevation & surfaces - Flat by default; shadow only for overlays (menus, dialogs, popovers) or true floating panels. - Borders (`--border`) preferred over heavy shadows for cards/tables in product UI. - Overlay → `--shadow-md`, modal → `--shadow-lg`. Both already carry the hairline ring, so do not add a second `border` on top of them. - Z-index ladder: base → sticky → dropdown → modal → toast. Document in code if non-obvious. #### Motion - 150–250ms, `cubic-bezier(0.4, 0, 0.2, 1)` (or equivalent ease-out). - Purposeful only: open/close overlays, expand/collapse, feedback. - No bounce spam, no layout thrash, no decorative infinite motion on product chrome. - Respect `prefers-reduced-motion`. #### State matrix (visual) Every interactive surface should show: | State | Requirement | |---|---| | Default | Rest styles | | Hover | Clear affordance (not color-only if critical) | | Focus-visible | Ring using `--ring`; never remove without replacement | | Active/pressed | Immediate feedback | | Disabled | Reduced contrast + not activatable | | Loading | Spinner/skeleton + `aria-busy` | | Error | Token + text | | Success | Token + text when needed | #### Accessibility floor - Contrast: text ≥4.5:1 (WCAG 1.4.3); **non-text graphical objects and UI components ≥3:1** against their background *and* against adjacent objects (WCAG 1.4.11) — this covers chart marks, series lines, focus rings, borders that carry meaning, and icon glyphs. Text *inside* a chart (axis ticks, labels, legends) is text and needs the full 4.5:1; this is the most commonly missed contrast requirement on data surfaces. - Focus order matches reading order. - Don’t disable zoom / don’t trap scroll under modals incorrectly. - Status never color-only (pair icon or text). - Live regions for toasts and async results that aren’t focus-moving. #### Icons - One family per product (Lucide is a solid default). - Stroke weight consistent (~1.5–2px at 16–24px). - Icon-only controls require accessible names (+ tooltip or sr-only text). #### Imagery & texture - Real product/context imagery beats abstract gradients as the main idea. - Decorative gradients are atmosphere, not the hero concept. - Marketing: full-bleed hero as dominant plane when a hero exists (see [§ Patterns](#patterns-screen-archetypes)). --- ## Taste — measured thresholds and failure tells Measured, not asserted. Production CSS from 18 shipped products was fetched, extracted and analysed (~4.5 MB). Where a claim comes from measurement it says so. Where it comes from published literature it says that instead. The point of this file: every existing rule set answers *"does this violate a rule?"* This one answers *"is this good?"* — in terms a program can check. --- #### Part 1 — Reference token values Measured directly from shipped stylesheets. ##### Linear - **Type:** Inter Variable (UI), Tiempos Headline (serif display), Berkeley Mono - **Weights:** 300 / 400 / **510** / **590** / **680** — non-round variable instances - **Body:** 15px, line-height 1.6, tracking −0.011em - **Scale:** 10, 12, 13, 14, 15, 17, 18, 20, 24, 32, 40, 48, 56, 64, 72 - **Tracking curve:** −0.012em at 17–24px → −0.022em at 32px+ - **Leading curve:** 1.6 @15 · 1.4 @17 · 1.33 @20–24 · 1.125 @32 · 1.1 @40 · 1.0 @48 · 1.06 @64 - **Radius:** 4, 6, 8, 12, 16, 24, 32, 9999 — only 7 distinct px values - **Dark surfaces:** `#08090a #0f1011 #141516 #191a1b` — hue 210° throughout, ΔL = +2.7, +2.0, +2.0 - **Accent:** `#7170ff` = OKLCH(62.3%, 0.207, 279°) - **Motion:** 0.1s quick, 0.25s regular, 0.15s fade-out - **Widths:** page 1024px, **prose 624px**, homepage 1344px - **Other:** explicit 17-step z-index ladder; `--min-tap-size: 44px`; hairline 1px → 0.5px at 2dppx ##### Vercel / Geist - **Grays are chroma exactly 0** — `hsl(0, 0%, L)`. A deliberate counterexample to "grays must be tinted." - Parallel **alpha ramp** (4%…91%) for overlaying on unknown backgrounds - Palette authored natively in OKLCH — 173 declarations - **Shadow ladder:** `2xs 0 1px 1px #0000000a` (4%) → `2xl` three layers at 2/4/6%. Dark mode is identical geometry at **4× alpha** - **Composite elevation:** hairline ring + shadow + background-colored outer ring. Overlays never get a bare drop shadow - Focus: `0 0 0 2px var(--background), 0 0 0 4px var(--focus)` - Durations 0.15s (37×), 0.2s (37×), 0.25s (20×) · `:where()` 566× · `focus-visible` 259× ##### Notion - **Warm grays:** hue 26–60°, saturation 2–10% - **Line-heights ARE the spacing tokens** — `--font-line-height-200: var(--dimension-spacing-24)`. 100% land on the 4px grid - **Tracking curve:** +0.0078rem @12px → 0 @14–16 → −0.0078 @18–20 → −0.0156 @22 → −0.047 @32 → −0.156 @76 → −0.2875 @96 - **At the same size, regular takes ~1.6× more negative tracking than bold** (32px: −0.0625rem vs −0.046875rem) - `font-feature-settings` referenced **1,519 times**, per type role - `--shadow-200` = 4 layers, offsets/blurs growing ×2.3–2.8, alpha growing linearly 1.3% → 4% ##### Others, in brief - **Stripe:** headings ship at `font-weight: 300`. Radius 2, 4, 6, 16, 32 — **no 8px**. Border widths 1px, **1.25px**, 2px. Ships `calc(radius - 1px)` for nesting. 68 `prefers-reduced-motion` blocks, the most in the set. Measure capped in `ch`. - **Clerk:** 1,193 `color-mix(in oklab, …)` — the palette is derived, not picked. Shadows are hue-tinted `#212126`, not black. - **Liveblocks:** one base radius, everything else derived — `calc(.5 * r)`, `calc(.675 * r)`, `calc(r - .75 * 4px)`. `:where()` 770×. - **Raycast:** greys at hue 180–240° with **saturation rising 0% → 17.6% as lightness falls**. Heaviest shadow layering measured (mean 5.7). - **Superhuman:** `light-dark()` 101×, relative color syntax 106×. Dark background is a brand-tinted black, never `#000`. - **Things 3:** `em`-based radii, so radius scales with type size. "Grays" are translucent navies. --- #### Part 2 — 40 checkable rules ##### Color & surface 1. **Gray ramps must be hue-monotone.** Every step within ~35° of every other; saturation ≤12% or chroma ≤0.05. Either commit to a hue family or commit to chroma-0. Mixed-sign hue across a ramp is the defect. 2. **Adjacent surfaces differ 1.6–4 percentage points of lightness, mode ≈2.0.** ≥6pp is a smell. Borders carry separation. 3. **In a tinted dark ramp, saturation rises as lightness falls.** A linearly-desaturating ramp reads dead. 4. **Accent chroma lands in OKLCH 0.13–0.24 at L 55–65%.** Tailwind's `-600` row is 0.245–0.288 — above the entire reference set. 5. **Derive the palette, don't hand-pick it.** Ten hand-picked hexes won't stay in relationship; a `color-mix()` formula will. ##### Type 6. **The scale is two ratios.** ~1.10–1.15 in the UI band (11–24px), ~1.20–1.25 display. 7. **Line-height is a monotonically decreasing function of size, peaking at body size** — and it falls going smaller too. 8. **Floor: ≥1.33 at 12px, ≥1.40 at 14–15px.** Dense UIs cut padding, not leading. 9. **Tracking is a function of size AND weight.** Regular needs ~1.6× more negative tracking than bold at the same size. 10. **Display crosses to negative tracking at 20–24px, reaching −0.02 to −0.035em by 48px.** 11. **Use non-round variable weights** — 450, 510, 590, 680 — where the face supports them. 12. **One custom or licensed face, minimum.** 11 of 13 measured products use a non-Google face. 13. **Set `font-feature-settings` per role, not globally.** `tabular-nums` on every numeric column is a hard requirement. ##### Shape 14. **`child radius = parent radius − padding`, never child > parent.** Ships as literal `calc()` in production. 15. **Radius scales with element size.** Controls 4–6px, cards 10–12px, sheets 16–20px, pills full. One value everywhere is the tell. 16. **Consider deriving all radii from one base.** ##### Depth 17. **≥2 layers; overlays 3–5.** 18. **Offsets and blurs grow geometrically (×2–2.8 per layer); alpha grows linearly and stays low.** 19. **Top-layer alpha ≤6% in light mode.** Tailwind's `shadow-lg` is 10% on both layers. 20. **Any layer with blur ≥8px carries negative spread ≈ −blur/4 to −blur/2.** Without it the shadow haloes past the silhouette. 21. **Elevation = hairline ring + blur layers + background ring.** 22. **Dark mode: raise the surface and add a 1px top inner highlight.** Don't reuse the light shadow. Where dark shadows are used, alpha ≈4× light. 23. **Hairlines below 1px are real** — 847 occurrences of `0.5px` across the set. 24. **Separation preference order: spacing > background > shadow > border.** ##### Motion 25. **Duration mode across 4.5 MB is 150ms.** Plus a distinct 50/75/80ms micro-feedback band. 26. **By role:** 100–150 micro · 150–250 standard · 200–300 overlays. **Exits ~20% faster than entrances.** Match duration to distance. 27. **By role, easing:** entering/exiting → ease-out · moving on screen → ease-in-out · hover → ease · constant motion → linear (the one legitimate use). 28. **Press feedback is `scale(0.96–0.99)`.** Hover transforms are tiny — 2–3px. 29. **Never start an entrance at `scale(0)`.** 0.93–0.95; dialogs from ~0.8. 30. **Don't animate high-frequency keyboard-driven surfaces at all.** Command palettes, context menus, theme toggles. ##### Layout 31. **Optical alignment is real and shipped** — sub-pixel nudges appear throughout production CSS. 32. **Spacing is a 4px-base non-linear scale that goes coarse at the top.** 33. **Optionally snap line-height to the spacing grid.** Notion does this literally; its vertical rhythm is provably tighter. 34. **Prose caps at 45–75ch** — the intersection of Bringhurst (45–75) and Butterick (45–90). Vary content width by role. 35. **Ship an explicit z-index token ladder.** Ad-hoc `9999` is the alternative. ##### Interaction hygiene 36. **`focus-visible` + `outline-offset`, not `outline: none`.** Modern browsers respect `border-radius` on `outline` — this corrects older advice to use `box-shadow` instead. 37. **Guard hover behind `@media (hover: hover)`.** 38. **`prefers-reduced-motion` is table stakes** — present in 11 of 13. 39. **`text-wrap: balance` on headings, `pretty` on body.** 40. **Name your transition properties.** Never `transition: all`. --- #### Part 3 — Failure taxonomy Each written so it can be detected. The tell → the fix. ##### Color 1. `linear-gradient(135deg, …)` purple→blue → single flat surface, or same-hue with ΔL ≤12% 2. Computed color exactly equals a Tailwind default with no `@theme` override → override at minimum the accent ramp 3. `#000` on `#fff` → `oklch(21% .006 286)` on `oklch(98.5% 0 0)` 4. Accent chroma >0.24 as a large fill → ≤0.08 for large fills; reserve >0.2 for under 5% of pixels 5. Chroma-0 neutrals beside a chromatic accent → be consistent in either direction 6. `background-clip: text` gradient on an h1 → solid. If kept, you must unset the gradient on `::selection` 7. Shadow colored with the accent hue → tinted black, ambient + direct 8. Semantic colors picked ad hoc → use a documented 12-step family 9. Status by color alone → icon + text label 10. Large dark gradient banding → radial gradients, never a scaled/blurred filled rect 11. `:hover` computed color equals base color → every state must increase contrast ##### Type 12. Inter with zero tracking and zero feature settings → the single loudest AI signal 13. `letter-spacing: 0` at ≥36px → −0.025em at 36–48, −0.05em above 60 14. `line-height ≥1.4` at ≥30px → 0.95–1.1 display 15. Everything at 1rem → ≥3 roles with size, weight and color changing together 16. Hierarchy from size alone → change three axes at once 17. Weight jumping 400→700 → 500–600 for medium headings 18. Any weight below 400 in UI → floor at 400 19. `text-transform: uppercase` with tracking 0 → +0.025 to +0.1em 20. Measure >75ch → ~65ch 21. `text-align: center` on a paragraph >2 lines → left-align 22. `font-weight` change on hover → causes reflow; change color or add a ring 23. Literal `...` and straight quotes → `…` and curly quotes 24. Numeric columns without `tabular-nums` 25. Headings without `text-wrap: balance` 26. `` font-size <16px on mobile → iOS zooms on focus and it feels broken ##### Layout 27. `max-width: 1200px; margin: 0 auto` as the only layout decision → differentiate by content role 28. Three identical `grid-cols-3` feature cards → the universal AI landing page 29. Hero → 3 cards → CTA → footer, nothing else → lead with the actual artifact above the fold 30. One gap value used for >80% of gaps → three tiers: 8 intra-component, 16 intra-group, 64–96 inter-section 31. Any margin or padding not ≡ 0 mod 4px 32. Icon+label row with `items-center` and no optical nudge 33. Everything centered → left-align content-dense sections 34. Nothing happens above 1200px 35. Horizontal scrollbar leak → usually a flex child missing `min-w-0` 36. Interactive target <24px (mobile <44px) → expand hit area with a pseudo-element ##### Shape & depth 37. `border-radius: 8px` on every element regardless of size 38. `child_radius ≥ parent_radius` → corners visibly don't run parallel 39. Computed shadow exactly equals unmodified `shadow-lg` → author your own alphas 40. Single-layer shadow at large blur → no real object casts one shadow 41. Pure-black shadow on a hued background 42. `border: 1px solid rgba(0,0,0,0.1)` everywhere → muddy, and invisible in dark mode 43. `backdrop-filter: blur()` on anything not genuinely over content 44. Focus indicator that squares off a rounded element ##### Motion 45. `transition: all` 46. Animating `top`/`left`/`width`/`height`/`margin`/`padding` → transform and opacity only 47. `linear` on a transform, or shipping Tailwind's default easing on an entrance 48. Duration >300ms on hover or active 49. Entrance and exit at identical duration 50. `scale(0)` → `scale(1)` entrance 51. Default `transform-origin` on a popover → set it to the trigger 52. Keyframes where a transition would do → keyframes can't be interrupted mid-flight 53. No `prefers-reduced-motion` anywhere in the bundle 54. Hover that changes box dimensions → neighbors shift, pointer flickers out 55. Spring physics on discrete state changes → springs are for gesture-driven surfaces ##### Icons, imagery & content 56. Emoji inside a button or heading → renders per-OS, can't inherit `currentColor` 57. Two icon libraries in one bundle → detect via mixed viewBox conventions 58. Inconsistent `stroke-width` across icons 59. Icon sized to cap-height, dominating its label → icon box ≈1em, glyph ≈0.85em 60. **Stock photography.** Uniformity tell of exactly the same kind as default tokens. Use real product surfaces, generated texture, data as ornament, or typographic covers. 61. A "Trusted by" row of invented logos → fabricated social proof, an integrity problem 62. Blurred gradient mesh blob behind the hero → and if kept, it must have `pointer-events: none` 63. ✨ 🎉 🔥 in headings, buttons or badges → the most reliable generated-content marker 64. Badges on elements with no state to communicate 65. Vague button labels — "Continue", "Learn More", three "Get Started" on one page 66. Error message stating a problem with no next step ##### State 67. Click handler with no `:hover` rule 68. `outline: none` with no replacement 69. Disabled = `opacity: 0.5` and nothing else → usually drops below contrast minimums. And disabled buttons must not carry tooltips; they're unreachable 70. Submit disabled before the user has typed → hides which field is wrong 71. Loading button that replaces its label with a spinner → width jumps, verb lost 72. No empty state — a zero-row table renders as a bare header 73. Spinner where a skeleton belongs, or a skeleton whose shape doesn't match the loaded content 74. Corner toast for a local action → inline checkmark at the trigger 75. Destructive action fires immediately → confirmation or an undo window 76. State held only in component state, never in the URL ##### Dark mode 77. Dark palette produced by inverting light → hue relationships invert too 78. `background: #000` → OLED smearing, and elevation becomes inexpressible 79. `color: #fff` body text on dark → halation. Reserve pure white for one element 80. Light-mode shadows reused in dark → invisible on a near-black surface 81. Accent carried into dark at identical chroma → saturated hues bloom on dark 82. **Missing `color-scheme: dark` on ``** → the most common visible dark-mode defect. Scrollbars, native `
` behind a disclosure, or a one-line prose summary of the finding. This satisfies screen readers *and* is the thing most readers actually want. Writing it is also the fastest way to discover the chart has no finding in it. - **The title states the finding, not the fields.** "Pipeline coverage fell below 3x in EMEA" beats "Coverage by region". If no finding can be written, question the chart. #### Number formatting Consistency here does more for perceived quality than any visual treatment: - **`tabular-nums` everywhere a number can be compared vertically.** Non-tabular figures in a column make comparison physically impossible. - **Align numerals right, labels left.** Decimal-align when precision varies. - **One abbreviation rule per surface**, applied everywhere: `1.2K` / `1.2M` / `1.2B`, or full figures with thousands separators. Never mixed in one view. - **Significant digits by magnitude, not by default float.** `$1.2M` not `$1,234,567.89`; `3.2x` not `3.21759x`. Precision beyond decision-relevance is noise that costs scanning speed. - **Percentages: state the base.** "Up 12%" vs "up 12 points" are different claims and are confused constantly. Use `pp` for point differences. - **Zero, empty, and unknown are three different things.** `0`, `—`, and `n/a` must be visually distinct and used consistently. Rendering unknown as `0` is a data-integrity failure wearing a formatting costume. - **Currency: symbol and code when multi-currency is possible.** `$1.2M USD`. - **Dates: unambiguous.** `2026-08-08` or `8 Aug 2026`, never `08/08/26`. Relative time (`4h ago`) for recency, absolute on hover or beside it for the record. #### Interaction - **Tooltip is an enhancement, never the only carrier of a value.** It is unreachable by keyboard and touch users and invisible in a screenshot or an export. - **Hover reveals detail; click commits.** Never make hover the only path to a value. - **Brush-and-link over cross-filtering everything** — linked highlighting keeps the reader oriented; a global cross-filter silently changes every other number on the page. - **Every chart needs an underlying-data escape hatch** — view as table, copy, export. #### Cross-references - Page composition, metric cards, direction semantics → [§ Dashboards](#dashboards-surfaces-that-answer-questions) - Mark-count thresholds, SVG vs canvas, render budgets → [§ Performance](#performance-budgets-and-thresholds) - Library choice and maintenance status → [§ Ecosystem](#ecosystem-libraries-licenses-maintenance) - Contrast policy and OKLCH ramp construction → [§ Color and type](#color-and-type-the-method) --- ## AI surfaces — topologies Any interface where a model does work a human is accountable for. Chat is one topology among ten and usually the wrong one. The governing principle: **the interface's job is to make the model's work reviewable at the speed it is produced.** A surface that generates faster than a human can verify has moved the bottleneck rather than removed it, and it converts the human into a rubber stamp — which is exactly the failure mode that makes AI output untrustworthy in aggregate. #### Choose the topology before the components | Topology | Shape | Use when | |---|---|---| | **Inline / ghost** | Suggestion appears in place, Tab to accept | The output is small, local, and instantly verifiable | | **Sidecar** | Panel beside the artefact, both visible | The human keeps authorship; the model advises | | **Canvas** | Model and human edit a shared document | Output is long-form and iterated | | **Instrumented session** | A live run with visible steps, logs, interruptibility | Multi-step work the human must be able to stop | | **Inbox** | Completed work queued for review | Async, batchable, many small items | | **Shared timeline** | Append-only record of actions by both parties | Auditability matters more than speed | | **Review gate** | Diff + approve/reject before anything commits | The action is irreversible or expensive | | **Supervised autonomy** | Runs alone; escalates by exception | High volume, well-bounded, measurable error rate | | **Provenance-first** | Every claim carries its source inline | The output is a set of factual assertions | | **Evaluation console** | Runs, scores, regressions across a suite | Building the thing that does the work | **Chat is the default only because it is the easiest to build.** It is the worst topology for anything reviewable: linear, unstructured, no diff, no state, and the record of what happened is a transcript nobody rereads. Reach for chat when the interaction genuinely is open-ended dialogue, and for almost nothing else. #### Streaming and progress - **Stream tokens only where reading-as-produced has value** — prose. Streaming a JSON blob or a diff is animated noise; render it complete. - **Show the step, not a spinner.** "Reading 12 files" → "Drafting" → "Checking" is orders of magnitude better than an indeterminate bar, and it costs nothing but honesty about your own pipeline. - **Latency thresholds** (Miller 1968; Card, Robertson & Mackinlay 1991 — the actual sources behind the numbers everyone quotes): - **0.1s** — feels instantaneous; no indicator needed - **1s** — flow preserved; indicator unnecessary but harmless - **10s** — the limit of attention. Past this the human context-switches, and the surface owes them a progress signal they can leave and return to - **Past 10s, make the work leavable.** A notification, a persistent run record, a URL that survives a refresh. Anything that dies on tab-close will be babysat, which is the most expensive possible use of the human. - **Never let output reflow the page under the reader.** Reserve the space, or append below the fold-line of what has already been read. This is a CLS problem and a comprehension problem at once. - **Stopping must be instant and must be honoured.** A stop button that finishes the current step first is a lie; say "finishing current step" if that is what it does. #### Steerability - **Let the human correct mid-flight**, not only at the end. The cheapest correction is the earliest one. - **Make the plan editable before execution** for anything multi-step. A visible plan is also the best available explanation of what the model is about to do. - **Scope is a control, not a setting buried in a menu** — which files, which records, which date range. Show it where the run starts. - **Re-run with a modification** must be one action, preserving the prior result for comparison. Regenerating destructively is how people lose good output. #### Review and approval The highest-leverage surface in the whole category, and consistently the least designed. - **Diff, always.** Before/after with changes highlighted. A summary of changes is not a diff and cannot be checked. - **Approve must be more expensive than reject.** Bulk-approve with no per-item view is a rubber stamp with a progress bar — it manufactures the appearance of oversight while removing it. - **Partial acceptance.** Accept 4 of 7 changes. All-or-nothing forces a bad choice and usually gets "all". - **Show what the model was uncertain about** and route the human's attention there first. Ranking a review queue by model confidence is the single biggest multiplier on human review throughput. - **Reject must capture why**, in one click from a short list. This is the only training signal the system will ever get for free. - **Irreversible actions get a confirm that names the blast radius** — "Delete 25 records" not "Are you sure?". Destructive scale must appear in the confirm text. #### Trust and provenance - **Cite at the claim, not at the bottom.** A footnote list is unverifiable in practice; a source on the sentence is checkable in one glance. - **Distinguish retrieved from generated.** Different visual treatments, always. This is the single most useful trust affordance available and it is nearly free. - **Never render a confidence percentage you cannot defend.** A fabricated "94% confident" is worse than no number: it is precise, unfalsifiable, and readers anchor on it. Prefer a coarse band or the evidence itself. - **Show freshness.** "Data as of" on anything retrieved. - **Make the prompt/inputs inspectable.** "Why did it say that" is answered by showing what it was given, not by generating an explanation of itself — a post-hoc rationale from the same model is not evidence of its reasoning. #### Failure UX Failure is a design surface, not an exception path, and it is where trust is actually won: - **Distinguish the four failure types** — refusal, timeout, tool error, low-quality output — because the human's next action differs for each. A single "Something went wrong" forces a guess. - **Preserve the input.** Losing a user's prompt or a half-reviewed edit on failure is unforgivable and extremely common. - **Partial output is valuable — keep it**, marked as partial. - **Retry must be able to differ**: retry, retry with more context, retry with a different approach. An identical retry is often just a slower failure. - **Say what the model cannot do**, once, at the boundary — rather than letting it attempt and fail. A model narrating an action it has no means to take is the worst possible outcome and the surface can prevent it by showing which tools are actually attached. - **Never a toast as the only error channel.** It disappears, it is unreachable by keyboard, and it cannot hold a diagnosis. #### Handoff - **Hand off with state, not a summary.** The human should land in the work, with what was done, what is left, and what the model was unsure about. - **Name the confidence boundary explicitly** — "verified X, did not verify Y". The single most valuable sentence any AI surface can produce. - **The escalation must be a person, not a queue** for anything time-sensitive. #### Multi-agent - **A tree, not a chat log.** Parallel work needs a structure that shows what is running, what finished, and what depends on what. - **One accountable surface.** N agents must not produce N notification streams; converge to one queue the human owns. - **Show cost and elapsed time per branch.** Runaway parallel work is invisible without it. #### Anti-patterns - **Chat as the interface for structured work** — the default that survives because it is easy to build, not because it works - **Rubber-stamp approval** — bulk accept with no diff - **Fabricated confidence numbers** - **Anthropomorphic status theatre** — "Thinking…", "Pondering…" in place of the real step name. It is charming once and obstructive thereafter, and it hides genuinely useful progress information - **Sycophantic acknowledgement** in a work surface — "Great question!" costs a line of screen and a unit of credibility - **Infinite regeneration with no diff between attempts** — the human cannot tell whether anything changed - **Hiding the model's inputs** while claiming explainability - **Streaming as decoration** — token-by-token rendering of content nobody reads linearly - **A stop button that does not stop** - **Losing user input on error** - **Autonomy without an error rate.** Any surface that acts unsupervised must publish how often it is wrong, measured — or it is asking for trust it has not earned #### Cross-references - Composer, streaming and chat component baselines → [§ Component contracts](#component-contracts-what-every-named-control-owes) - Review queues, exception lists, alert rationale → [§ Dashboards](#dashboards-surfaces-that-answer-questions) - Spoken and listening surfaces → [§ Voice](#voice-surfaces-that-speak-or-listen) - Perceived-performance techniques → [§ Performance](#performance-budgets-and-thresholds) --- ## Copy — the presentation layer as an argument Read this before shipping any surface a user, buyer, or consumer *reads* — a landing page, a dashboard, a pricing section, an email, an artifact, a deck, an empty state. The visual audit checks whether the surface is well built; this pass checks whether it **answers the questions in the reader's head**, in the order they ask them, at the place their eyes land. Language, layout order, and the artifacts themselves are one presentation layer — tune them together. **The law: every surface is an argument. The reader arrives with questions; each element either answers one or costs attention. An element that answers no question is decoration; a question with no answering element is a copy gap — same status as a token gap. Say so; never pad around it.** --- #### First principle — the five beliefs (Hormozi) From the value equation in *$100M Offers* — Value = (Dream Outcome × Perceived Likelihood of Achievement) ÷ (Time Delay × Effort & Sacrifice) — rendered as what a buyer must actually feel before they act: | # | Belief | The question in their head | What carries it | |---|---|---|---| | 1 | **It gets me the outcome I care about** | "Will this make/save me money (or time, or standing)?" | Headline + hero. Outcome named in the reader's units, not the product's features. | | 2 | **It will work for *me*** | "People like me, in situations like mine, succeed with this?" | Proof adjacent to the claim: named results, numbers, the demo itself working. | | 3 | **I'll see results soon** | "How long until it pays off?" | Time-to-value stated: "live in an afternoon", "first brief in 5 minutes". | | 4 | **It's easy to implement** | "What will this cost me in effort and change?" | The on-ramp shown: steps count, what it plugs into, what it replaces vs. what it doesn't touch. | | 5 | **It's worth it, and I trust who's behind it** | "Is the value obviously bigger than the price — and who says so?" | Price anchored against the outcome, risk reversal, and trust signals near the ask. | Run the pass literally: for each belief, point at the element on the surface that carries it. State it like a measurement — "belief 3 is carried by the subhead's 'first kit in five minutes'; belief 5 has no carrying element." Feelings scale with proof shown, not claims made. #### Sequence — the reader's questions are the layout Order is copy. The eye answers questions in a fixed sequence, and each section gets one job (patterns.md already budgets the hero — this is why): 1. **What is this?** — answered in the first heading, in plain words. If a visitor can't say what the product is after the first screen, nothing below matters (Miller: *if you confuse, you lose*; Krug: self-evident beats self-explanatory). 2. **Is it for me?** — the named situation or job. Readers self-select on recognition of their problem, not on category jargon (JTBD: name the job it's hired for). 3. **Why this over what I do today?** — position against the *real* alternative, which is usually a spreadsheet, an intern, or doing nothing — not the competitor you fear (Dunford). "Better" only means something once the alternative is named. 4. **Will it work for me?** — proof, placed here, not ghettoized in a logo row. 5. **What exactly do I do next, and what happens when I do?** — one primary CTA. Match depth to **stage of awareness** (Schwartz): a problem-aware reader needs the problem named; a solution-aware reader needs differentiation; a product-aware reader needs the offer and the risk reversal. Writing most-aware copy for a least-aware reader is the commonest landing-page failure — it reads as "features for strangers." #### Checkable rules from the canon Distilled to what can be verified on the surface, not vibes: - **The headline does 80% of the work** (Ogilvy). It gets a real draft count — write 10+, ship the one a customer could have said. Specifics beat superlatives: "cuts screening from 3 weeks to 48 hours" outsells "revolutionary speed." - **The customer is the hero; the product is the guide** (Miller). Count sentence subjects: "you/your" should dominate "we/our/[product]". A surface that narrates itself is a mirror, not a window. - **Copy is found, not written** (Wiebe). The best lines are voice-of-customer — what users say in calls, tickets, reviews. If a headline couldn't come out of a customer's mouth, keep digging. - **Concrete beats abstract; one number beats three adjectives** (Heath, *Made to Stick*). Every abstract claim gets asked: "can I picture it? can I check it?" - **Proof sits next to the claim it supports** (Cialdini). A testimonial about ease belongs beside the implementation section, not in a carousel at the footer. Authority, social proof, and scarcity only work in context — and only honest. - **Sell the user's competence, not the product's features** (Sierra). "You'll walk in knowing their org chart" beats "AI-powered org-chart analysis." Feature lists answer questions nobody asked yet; capabilities become *their* superpowers. - **Front-load every heading, link, and button** (Krug / NN/g). Readers scan the first two words. "Pricing that scales" scans; "A flexible approach to pricing" doesn't. Same for CTA labels: verb + outcome ("Get the brief"), never "Submit." - **Address the anxiety at the point of action** (JTBD/Moesta). Every CTA has a silent "…and then what happens?" Answer it within 20px: "No card required", "Takes 2 minutes", "You can delete everything after." #### Copy slop tells The linguistic twin of the 12 visual tells in anti-patterns.md. Any of these is a flag; three or more means the copy was generated and never reflected on: 1. Unquantified power adjectives: *seamless, powerful, robust, effortless, cutting-edge, world-class, next-generation, game-changing*. 2. *Unlock / unleash / supercharge / elevate / empower / transform* as verbs. 3. "Whether you're X or Y" constructions trying to be for everyone. 4. Benefit triads with identical rhythm ("Faster. Smarter. Better."). 5. A headline that could sit on any competitor's site unchanged — the swap test. 6. Feature names Title-Cased As If Trademarked when they're just functions. 7. "We believe…" openings — the reader didn't ask for a creed. 8. Colon headlines restating themselves: "Speed: get results faster." 9. Exclamation marks doing the enthusiasm the evidence should. 10. Jargon naming the category instead of the outcome ("conversational intelligence platform"). #### Element checklist | Element | Its one job | Check | |---|---|---| | Headline | Answer "what is this / what do I get" | Swap test; a customer could say it; carries belief 1 | | Subhead | Qualify who it's for and how fast | Names the job or the time-to-value | | Primary CTA | Say what happens next | Verb + outcome; anxiety answered adjacent; one per screen | | Proof | Make belief 2 concrete | Named, numbered, adjacent to its claim | | Pricing | Anchor cost against outcome | Reader can compute their own ROI from what's on the page | | Section order | Match the question sequence | No answer appears before its question would arise | | Empty state | Sell the first action | Says what will be here and how to cause it — never just "No data" | | Error / microcopy | Say what to do next | Names the fix, not the fault | | Chart / artifact titles | State the finding, not the topic | "Churn halves after onboarding call" not "Churn rates" | | Buttons & labels | Front-loaded, outcome-voiced | First two words carry the meaning | #### Process 1. Name the reader (buyer, end user, exec skimming) and their awareness stage. 2. Read the surface top-to-bottom **as that reader**, writing down each question as it arises and whether the next element answers it. 3. Map the five beliefs to carrying elements. List the gaps. 4. Run the slop-tell scan and the element checklist. 5. Rewrite worst-first: gaps before wording, headlines before body, CTAs before microcopy. Keep layout changes on the table — moving proof next to its claim is a copy fix. 6. Report before/after lines side by side, and which belief or rule each change serves. "Tightened the copy" is not a report, same as "improved the spacing." #### Severity | Level | Meaning | |---|---| | **Critical** | A belief with no carrying element; a first screen that fails "what is this"; a CTA that doesn't say what happens | | **Major** | Proof detached from its claim; feature-voice where outcome-voice belongs; section order that answers questions out of sequence | | **Minor** | Slop tells, word economy, front-loading polish | #### Mode notes - Runs as part of **Audit** whenever the surface carries persuasive or instructional copy; standalone when asked to "review the copy", "tighten the messaging", or "does this land?" - **Brand-locked surfaces:** this pass governs the persuasion architecture; brand voice and terminology compliance still go through the brand`s own kit. Both must pass — on-brand copy that answers no question is still a fail here. - This pass changes words and element order. It does not restructure components — that's Build/Polish territory under contracts.md. --- ## Adoption — will anyone open it For an internal tool, the dominant failure mode is not ugliness. It is a well-built, well-tokenised, accessible surface that nobody opens. That outcome is decided before layout, by four questions, and it is a **design** defect — not a training problem, not a change-management problem, and never something a launch email fixes. Everything here applies to internal and workflow surfaces: dashboards, cockpits, consoles, admin tools, review queues, digests. Marketing surfaces are governed by [§ Copy](#copy-the-presentation-layer-as-an-argument); this file is about the thing someone has to open on a Tuesday. #### The four gates — answer before you draw anything | Gate | The question | Fail state | |---|---|---| | **Ritual** | Which recurring meeting or moment does this surface run? | A tool with no meeting is a hobby. | | **Private win** | Per persona, what one fact does this give them that they cannot get by asking a person? | A reporting burden with a UI. | | **Shortest path** | Is this the fastest route to something they already had to do, with no step where they must work out where to go? | A tax, paid in junk data. | | **Absence** | What breaks if nobody opens it for a week? | "Nothing" — so nobody will. | Write the four answers down. If any is weak, the fix is upstream of the design, and the honest report says so and names whose decision it is. #### 1. Ritual — attach every surface to a recurring meeting Adoption is downstream of ritual. If the forecast is read off your screen in the Monday call, every manager updates their deals before Monday — not because the UI is good, but because being wrong in public is expensive. - **Design backwards from the agenda.** Screen order matches the order items are discussed. The first thing on screen is the first thing said out loud. - **Whoever's screen is projected owns the narrative.** Pick that screen deliberately. - **The artifact must regenerate itself.** If anyone rebuilds the same numbers in a spreadsheet the night before, your surface already lost — the spreadsheet is the real tool and it will win every week. - **Name the human who is embarrassed when it is wrong.** A surface with no owner degrades to decoration in about three weeks. - **One question per surface.** Two surfaces answering the same question get neither adoption nor trust; people pick the one their boss quoted last. #### 2. Persona asymmetry — each role needs a different product Same data, three different questions. This is where most multi-persona tools die: the second persona's view is the first persona's view with a filter, so the second persona never opens it. **Checkable:** if two persona views share more than ~80% of their fields, columns and actions, it is a filter, not a product. Split the question or drop the view. | Persona | The question they actually have | What earns the open | |---|---|---| | Individual contributor | "What is about to embarrass me?" | Early warning — the thing their manager will raise, before it is raised. | | Manager | "Where do I spend the next hour?" | A ranked short list, with the reason for the rank. | | Exec | "What number can I defend, and why?" | A figure that drills to the records behind it. | - Lead the IC view with **exposure avoidance, not a score.** "Your manager will ask about these three on Monday" is a service. "You are at 62%" is a verdict. - The exec number must be traceable in one click to the rows that produced it, or it will be re-derived by hand and the surface is bypassed. - If a persona's only interaction is being measured, expect minimum-compliance data. #### 3. Shortest path — compliance is a byproduct, never the ask Nobody logs a call to be compliant. They log it if logging it is how the follow-up gets drafted. - **Walk the path from notification to committed change and count the steps where the user has to work out where to go next.** Those are the ones that cost. Raw click count does not predict success — the 3-click rule is debunked (UIE, 2003; see the myth table in [§ Dashboards](#dashboards-surfaces-that-answer-questions)) — but a step whose next move is not obvious is where people leave. - **The fix happens where the problem is named.** Inline edit on the card that flagged it. "Open the record, find the field, save" hides a search inside step two, and a search is where the session ends. - **Every required field owes the user something inside the same session.** A field that only feeds someone else's report is a tax, and taxes are paid in fiction. - **Never ask for what the system already knows.** Prefill, then let them correct. #### 4. Push and pull — consume in push, act in pull Executives and reps consume in **push** (email digest, Slack, the meeting artifact) and act in **pull** (one record, one decision). Build both halves; a surface that only exists as a destination depends on memory, and memory loses to an inbox. - A push message links to **a record or a filtered queue with the filter already applied** — never to a dashboard home. A landing page is where intent goes to die. - **Push arrives before the ritual, not after.** A digest that lands after the meeting is a newsletter. - **Content is the delta since last time**, not the standing state. A message that restates what the reader already knows trains them to skip the next one. - **One digest per persona per cadence.** A second daily notification roughly halves the first one's open rate. - Two channels max, and the same deep link in both. Slack for the people who live there, email for everyone else. #### 5. Visibility, and the shame trap People fight to use surfaces where their work becomes visible upward. They quietly sabotage surfaces whose only function is to expose them. - **Show effort and improvement, not only shortfall.** Rank on inputs the user controls. - **Public shortfall belongs in a 1:1**, not a leaderboard. A board that only lists who is behind produces data entry theatre within two cycles. The mechanics of doing a scorecard without backfire — personal-best over peer rank, disputable numbers, manager-visible by default — are in [§ Dashboards](#dashboards-surfaces-that-answer-questions) § Accountability surfaces. - Make the *good* path visible: the rep who cleared their queue should be legible to their manager without asking. That, not the scorecard, is what gets it opened daily. #### Measuring adoption — metrics that can fail State these as numbers, per the reporting rule. Every one of them can come back bad. | Metric | Definition | |---|---| | **Weekly active named users** | distinct eligible humans, not events, not page views | | **Time to first action** | grant of access → first committed change through the surface | | **Pushed-item completion** | items resolved / items pushed, per cadence | | **Ritual traceability** | share of the meeting's decisions that came off the surface | | **The honest one** | turn it off for a week — count who complains | Vanity, do not report: page views, "engagement", cards generated, sessions, deploys, number of dashboards shipped. **Rollout is gated on evidence, not calendar.** Do not widen access until at least one ritual has actually been run off the surface and pushed-item completion is non-zero for the pilot cohort. Widening a permset over a cohort with zero actions multiplies zero. #### Adoption slop — the failure taxonomy 1. Wall of KPI cards with no next action. 2. A "Reports" tab. 3. Persona views one filter apart. 4. A notification restating what the user already knew. 5. A link to a home page instead of a record. 6. Required fields that pay nothing back in-session. 7. A dashboard with no owner and no meeting. 8. A leaderboard that shows only shortfall. 9. The same numbers rebuilt by hand in a spreadsheet every week. 10. Access widened before a single user resolved a pushed item. 11. Two surfaces answering the same question. 12. "We'll do a training" as the adoption plan. 13. Stub routes shipped alongside live ones — one dead link teaches people the whole tool is unfinished. 14. An empty state that explains the feature instead of doing the first useful thing. #### Cross-references This file is about whether the surface is opened. Once someone is looking at it: - What goes on the screen, queue design, alert rationale, scorecards without backfire → [§ Dashboards](#dashboards-surfaces-that-answer-questions) - Screen composition → [§ Patterns](#patterns-screen-archetypes) · component baselines → [§ Component contracts](#component-contracts-what-every-named-control-owes) - The words on it → [§ Copy](#copy-the-presentation-layer-as-an-argument) #### Reporting an adoption finding Same bar as every other shine claim: the numbers, and what you did not do. Name the ritual, the persona, the measured step count, and the current active-user figure. If the blocker is organizational — no meeting owns this screen — say that plainly rather than shipping another tab and calling it done. --- ## Voice — surfaces that speak or listen Read this when a project adds any of: text-to-speech, a read-aloud mode, a spoken summary layer, voice commands, dictation. Every rule below was earned on 2026-08-05 building two of them in one day (the Stop-hook speaker and the Meeting Recon voice mode); the incidents are cited inline. **The law: a voice layer is a summarizer with manners, never a screen reader.** Nothing leaves the speaker that a colleague wouldn't say across a desk, and nothing the mic hears steers the app unless a human meant it to. --- #### Output — write for the mouth, not the eye - **Never read UI or agent text verbatim.** Summarize to one or two spoken sentences: what happened, what needs the listener. "Nothing needs you" is a valid and excellent ending. - **Ban from speech** — things no human says aloud: file paths, commit hashes, URLs, version strings, branch names, markdown syntax, emoji, code identifiers, raw ISO dates. If the fact matters, translate it ("the deploy finished", not "d-p-l underscore three-V-one…"). - **Homographs get rephrased, not trusted.** *live* → "deployed and running" / "up". Watch *read, lead, close, record, present, tear, wound* — a TTS engine picks the wrong one exactly when it's funniest. Incident: "Live." opened a status report and the voice said /lɪv/. - **Numbers are rounded and spoken with units.** "Contrast about twelve and a half to one", never "12.49:1". Four digits max out loud. - **Month abbreviations become month names before the mouth.** A TTS engine reads "Jul" as *Jewel* and "Aug" as a word. Expand Jan–Dec, speak ISO dates as dates, expand $1.2M-style suffixes, read ratios as "4.5 to 1". Ship it as a deterministic speechify() pass with unit tests — no model needed between the page and the voice. - **Strip eye-chrome at the DOM, not with regex.** Chips, status labels, citations and icons are for the eye; clone the row and remove them by class before extracting a word. And join sibling text blocks with a real space — textContent fuses "DDQ?" and "4 of 47" into one token. Incident: the brief read every tag on the bottom of the ticket. - **Sentence case, no lists.** Speech has no bullets; if the summary needs a list, it isn't a summary yet. - **The browser's speechSynthesis default is never the product's voice.** If a surface owns a voice, the product serves the audio: a server-side TTS proxy, key never in the client, gated to a verified session so it can't be farmed. Web Speech synthesis is only the fallback for when the proxy can't answer. Incident: the kit brief shipped on the OS robot lady while the brand voice sat one API call away. #### The summarizer harness (LLM → TTS) - System role in one breath: *you are the spoken-voice layer; reply with one or two short spoken sentences, casual, like a colleague leaning over; output only the sentences.* Put the write-for-the-mouth bans in the prompt. - **Disable reasoning traces.** Thinking-mode models leak deliberation as plain prose, not tags — `chat_template_kwargs: {enable_thinking: false}` for Qwen-class; `/no_think` in the prompt does NOT reliably work through a router. Incident: three minutes of chain-of-thought narrated through ElevenLabs in a warm baritone. - **Cap twice.** `max_tokens` ≈ 220 at the model AND a character truncation (~500) after extraction — the second cap is what saves you when the first lies. - **Timeout every leg** (LLM call, TTS call, playback) and run the whole thing async. A voice layer never blocks and never fails the host turn: log and go silent, don't throw. - **Kill switch is a file** (`touch …/voice.off`), not a setting behind a UI. - **Latency budget: first audio under ~8s.** Fast TTS tier for summaries (`eleven_flash_v2_5`-class); premium voices are for produced content, not turn chatter. #### Input — recognition - **Grammar over dictation.** Word-boundary regexes against a small command set; echo what was heard into the status live region so misses are visible. - **Playback-scoped grammar.** While TTS is speaking, honor ONLY the transport family — stop/mute/quiet/cancel · pause/hold on · resume/continue — and ignore everything else. The synthesized voice can pronounce your own nav keywords; without the scope, a brief that says "board" navigates mid-read. - **Keep the ear hot while speaking.** Engines end after one result; re-arm in `onend` while playback is live so "stop" always lands, and null the recognizer ref when it winds down or the next arm silently no-ops. - **A command with no target takes the obvious default.** "Brief me" with nothing open opens the first item and starts; voice users want motion, not a form error telling them to click something first. - **Accept synonyms.** stop = mute = quiet = cancel; pause = hold on; resume = continue = keep going. #### UI sync — the contract One control, three states, words at every step: ``` idle mic icon aria-label "Voice commands" aria-pressed false listening mic, live fill status: "Listening…" aria-pressed true speaking STOP square aria-label "Stop reading" aria-pressed true ``` - **The same button stops everything at every stage.** Never make a listener hunt for a second control while the thing is talking at them. - State is carried by icon shape + label + a `role="status"` region — never by color alone. - **Route change cancels speech and clears the speaking state**, or the stop button orphans on a page that isn't reading. - No Web Speech support → render nothing. A disabled mic is furniture. - First audio follows a user gesture. Never speak on page load. - **Teach the control with motion, not a scene.** A page that explains a voice feature shows the CONTROL cycling its states — a tight looping strip of idle → listening → reading captured from the running app — beside three numbered steps. A full-app screenshot "showing voice" teaches nothing; reviewers said so in exactly those words (2026-08-05). #### Test harness traps - Plain assignment to `window.speechSynthesis` silently loses to the native object — mock with `Object.defineProperty` (and mock the Utterance class too, or native `speak()` type-rejects yours). - Host "voice modes" may be input-only — Claude Code ships zero TTS; the robotic readback people complain about is the OS spoken-content layer. Build the speaker, then have the user turn the OS one off, or they duet. - Playback time counts against hook/harness timeouts — bound the utterance length, not the player. --- ## Brand mode — the adapter > **A private brand pack may install `brand.local.md` beside this file.** It is > gitignored, and it wins: read it instead of this one, which is the generic > adapter. Installing a real brand must never mean editing a tracked file — that > is how a brand value ends up in a public diff. Activate when the user names a brand, says "on-brand", or the work is clearly brand-facing (marketing site, demos, client decks-as-web, product UI carrying a company's identity). **A brand lane is a token override plus a small set of bans — not a second design system.** Everything in [§ Component contracts](#component-contracts-what-every-named-control-owes), [§ Patterns](#patterns-screen-archetypes), [§ Taste](#taste-measured-thresholds-and-failure-tells) and [§ Component contracts](#component-contracts-what-every-named-control-owes) still applies. This file is the adapter: what a brand kit has to tell you, and what changes once it has. #### Load order 1. **Read the brand's own kit before writing anything.** A brand skill, a PDF, a Figma export, a `colors_and_type.css` — whatever exists. Name the file you read. A remembered palette is a guess, and a guess in brand work is the one error a client always catches. 2. **Build the tokens, don't transcribe them.** Declare the brand palette once as custom properties in a single token block and reference it with `var()` everywhere else. Keep brand values out of public trees and shared examples. Hand-copied hexes are how five surfaces end up with five slightly different navies. 3. **Copy and terminology go to the brand's own voice authority**, if it has one. This skill owns layout, interaction, and component completeness. Don't fork messaging rules in here. 4. **Check the live site before shipping visuals.** WebFetch the brand's homepage. A kit describes intent; the site is what your work sits next to. #### What the kit must specify — and what to do when it doesn't | Needed | If absent | |---|---| | Canvas + one dark anchor | Derive from the primary's hue at fixed lightness; never invent a second accent | | Action color, and whether it may fill | Assume **action-only**. An accent used as a body fill at scale is the loudest off-brand tell | | Type roles: display / body / UI | Use the kit's faces only. No substituting Inter/Roboto/Arial for a licensed display face | | Case and tracking rules per role | UPPERCASE UI faces usually want positive tracking (~0.1em); read [§ Color and type](#color-and-type-the-method) | | Radii ladder | `child = parent − padding`; pick one ladder and hold it | | Motion | Cap at ~200ms, standard ease, no bounce | | Icon family + stroke | One family. Match stroke to the type weight; no emoji | | Logo misuse bans | Treat any logo gradient/lockup as **wordmark only** unless the kit explicitly permits it on chrome | | Status colors | **If the kit doesn't define them, the lane doesn't have them.** Borrow neutrals from the base lane rather than inventing brand-adjacent reds and greens | Anything the kit leaves silent is a decision you are making on the brand's behalf — say so in the handoff rather than leaving it implied. #### Marketing surfaces - Anchor sections in the brand's dark value; textures on dark only, low opacity - Any signal/pattern motif fades or bleeds — never hard-cut - Primary button: the action color, solid, in the brand's UI face - Secondary: outline in the brand's primary (inverted on dark) - Composition follows [§ Patterns](#patterns-screen-archetypes)'s marketing hero budget and brand-first test #### Product / app surfaces Same tokens and type roles, adapted for density: - No marketing hero inside a dashboard - Action color stays action-only — buttons, link emphasis, connectors; not fills - Tables/forms/menus keep the full [§ Component contracts](#component-contracts-what-every-named-control-owes) contract (a brand admin table is DataGrid-class) - Prefer bordered/flat elevation; a soft primary-tinted shadow only where brand cards call for one - Motifs stay in settings/marketing chrome, not every app panel - If an uppercase display face harms scanability in data-dense views, move dense labels to the body face and keep CTAs on-brand #### Completeness still applies Brand mode never excuses stubs. A branded admin table still gets toolbar, sort, filter, pagination, sticky header, empty/loading/error states, and a11y. #### Private brand lanes A real brand lane lives outside any public tree: the palette source + this file's brand-specific twin, distributed privately to the people who need it. Never let real brand values enter a public repo or a shared example. --- ## Salesforce — Lightning and SLDS 2 Verified 2026-08-04 against live docs and by inspecting the shipping npm artifacts. **Verdict up front: a constrained palette target, not a design target.** Budget for "our brand colors on Salesforce's design system," not "our design system on Salesforce." That's achievable, durable, officially supported, and roughly a day of emitter work. --- #### Status **SLDS 2** is the design system. **Cosmos** is the first *theme* built on it — the two are not synonyms and are often conflated. | Release | Event | |---|---| | Winter '25 | Beta, as "Enhanced Lightning User Interface" | | Spring '25 | Renamed SLDS 2 (beta). `lightningdesignsystem.com` now serves SLDS 2; SLDS 1 moved to `v1.lightningdesignsystem.com` | | **Winter '26** | **GA, all editions** | | Summer '26 (current) | Dark mode broadened; Themes and Branding UI expanded to typography, shadows, sizing, spacing | | Winter '27 | Group-based SLDS 2 activation *(roadmap preview, non-binding)* | **SLDS 1 is not deprecated and has no announced retirement date.** SLDS 2 is default for **new orgs only**; existing orgs opt in via Themes and Branding. **No SLDS 2 support planned** for: Salesforce mobile app, Flow Builder, Lightning App Builder, Lightning Out, **Experience Cloud**. **What *is* formally deprecated: SLDS 1 design tokens (`--lwc-*`).** The doc page title literally carries "(Deprecated)" — they still work in SLDS 1 themes but are **not included in SLDS 2 themes**. npm ships both in parallel — `@salesforce-ux/design-system` dist-tags: `summer-26: 2.30.4`, `winter-27: 2.264.0-beta.3`. --- #### The token architecture `--sds-*` is dead legacy. Live namespace is `--slds-` with a **tier letter** as the second segment. Counts extracted from `@salesforce-ux/design-tokens@4.1.0` (install it and read `flat.json` for the authoritative list): | Tier | Prefix | Count | Status for us | |---|---|---:|---| | **Reference** | `--slds-r-*` | **85** | **The only sanctioned override surface** | | Global | `--slds-g-*` | 524 | Consume only — **overriding is explicitly prohibited** | | Shared | `--slds-s-*` | 107 | Classified **private**, prohibited | | Component | `--slds-c-*` | — | Officially unsupported in SLDS 2 | | Private | `--_slds-*` | — | Prohibited | Cosmos theme total: **717 tokens** (524 global + 107 shared + 85 reference + 1 config flag), 42 flagged deprecated. The chain resolves `r → g → s → c`: ```css --slds-g-color-accent-1: var(--slds-r-color-brand-50); --slds-g-color-accent-2: light-dark(var(--slds-r-color-brand-40), var(--slds-r-color-brand-70)); ``` **This is the leverage point.** Because of that chain, overriding **17 `--slds-r-color-brand-*` steps recolors the entire accent system across every component.** The emitter's whole job for Salesforce is mapping a brand ramp onto ~85 reference tokens. ##### Shine's slds voice sheet is derived from this package Any SLDS fallback values you write must come from the package's own resolved values, re-checked against the installed `@salesforce-ux/design-tokens` version — never from memory. It has to be checked rather than trusted, because the sheet was previously written from values read off one rendered org. That org was still on SLDS 1, so every fallback was wrong — a font family of `"Salesforce Sans"` against SLDS 2's system stack, SLDS 1's `#0176d3` brand blue, `#ba0517` error, `#2e844a` success — and a measured value is indistinguishable from a correct one by inspection. **The trap worth naming: SLDS 2 numbers its text hooks by weight, not by importance.** `--slds-g-color-on-surface-1` is the *lightest* ink (body copy, placeholders, field labels) and `--slds-g-color-on-surface-3` is the *darkest* (titles). The old sheet mapped Shine's primary ink to `on-surface-1` and its muted ink to `on-surface-3` — exactly inverted. Both pairs pass a contrast check, which is why the test asserts the mapping directly. The prohibition, verbatim from *New Global Styling Hooks Guidance*: > "We don't support overriding the values of global styling hooks in your customizations." > "Re-assigning a new value to a global styling hook inside your component is prohibited. You will be subject to test failures and future breaking changes." ⚠️ Note a genuine contradiction: the token package README documents `--slds-s-*` as a normal public scope, while the guidance page classifies it as private and prohibits consumption. The package emits them; the guidance forbids using them. **Treat the guidance as controlling.** --- #### The token contract is first-class — better than most design systems ship `@salesforce-ux/design-tokens@4.1.0` (2026-08-08) ships per theme: - `*.global.tokens.raw.json` — DTCG-faithful (`$value`, `$type`, `$description`, `$extensions`) - `*.global.tokens.flat.json` — **717 entries, consumer-oriented** - `*.{global,reference,shared}.tokens.css` - iOS Swift + Android Kotlin outputs - `*.deprecated.tokens.raw.json` Every flat entry carries `name`, `value`, `originalValue`, `type`, `syntax`, `category`, `scope`, `namespace`, `description`, `inherits`, `themeOwned`, `darkValue`, `deprecated`, and **`cssProperties`** — the allowlist of CSS properties the hook is legal on. 628 of 717 are `themeOwned`; 287 carry a distinct `darkValue`. Built with Style Dictionary v5, with a dedicated `validate:dtcg` compliance check. Dark mode lives in `$extensions["com.salesforce-ux.mode"].dark`. **OKLCH is authoring-only.** README: *"Palette aliases defined in OKLCH perceptual color space, converted to hex for compatibility."* Grepping the shipped CSS: **zero** `oklch()`, `color-mix()` or P3 — 506 hex literals. Do not hand SLDS an OKLCH value and expect it to work. It does use **`light-dark()`** heavily — 302 occurrences in the Cosmos global file. **SLDS 2 decouples structure from style.** Confirmed in `@salesforce-ux/design-system-2@2.264.0`: `css/modular/slds2.base.css` (structure, no theme values) ships separately from `css/modular/slds2.theme.cosmos.css` (token values only), so themes swap by changing one ``. --- #### Override mechanics are unusually permissive All token declarations sit in: ```css @layer theme { :where(html) { /* … */ } } ``` `:where()` is zero-specificity **and** layered CSS loses to unlayered author CSS. So any custom property you set wins trivially — **no `!important`, no specificity fights.** That's a real gift and rare. **Custom properties pierce shadow boundaries** — they're inherited properties, so synthetic vs native shadow doesn't matter here. Synthetic remains the LEX default; native is per-component opt-in via `shadowSupportMode = 'native'`, still Beta, no announced date for flipping the default. --- #### The blunt part: you cannot deliver the overrides **There is no supported org-wide CSS injection point in internal Lightning Experience.** - `loadStyle` from `lightning/platformResourceLoader` is **scoped to the calling component**. - Experience Cloud has a real Custom CSS panel in Experience Builder. **Internal LEX has nothing equivalent.** - Appending `