phuryn/product-engineering / app-stack/skills/ui-design
ui-design
VerifiedMandatory for any product's screens, a builder's too, and any mock, prototype or artifact that shows them: its design system, colour, type, components; judging the look.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.6 KB |
| receipts.md | markdown | 2.9 KB |
| references/collections.md | markdown | 30.9 KB |
| references/method.md | markdown | 22.1 KB |
| references/review.md | markdown | 8.1 KB |
| references/screens.md | markdown | 12.6 KB |
| scripts/color.py | script | 2.5 KB |
references/method.md
View on GitHub# The method
Every kit and every screen satisfies these. They came from real products, each with its receipt; the kit binds and the collections advise (`SKILL.md`). "The kit" is the product's `tokens.css`, `kit.css` and kit README, its own design document (`SKILL.md § What binds`); "the design stage" is wherever the product first chooses its look, before screens are built.
## What binds
- **Keeping a brand's colours does not inherit a design system.** A decision that the look stays still runs the kit stage before any screen is built. The kit's floor is a type scale with line heights and weights, a spacing scale, at least two radii, an elevation scale, motion durations and easing, a z-index scale, control heights, and an icon set with sizes and stroke. Each value is a token, and a test asserts that every required token name exists in every set. (`2026-11-05`, an evals product treated keeping its colours as skipping direction and kept a kit of a few dozen utility rules: one radius, five type sizes, four hand-drawn icons, and no motion, elevation or z-index tokens.)
- **Compose, never invent.** If a screen needs something the kit does not have, add a modifier to an existing primitive here and use it. A one-off style in a screen is a bug — the second screen that needs it will not find it.
- **`tokens.css` is the only place a raw value may appear** — every colour, type size, space step, radius and duration. `kit.css` is built from tokens only, and a unit test refuses any colour literal in it, because a stated invariant with no test is a comment (`screens.md`). The one exception is a surface that cannot read CSS: `theme-color` metadata, a generated image (`opengraph-image`, a raster such as a QR code), a standalone `icon.svg` or favicon. Each is listed in the kit README: a literal that mirrors a token names it and is pinned by a test against it in every set, and fixed brand artwork that mirrors none says so; the colour-literal guard stays scoped to `kit.css`, where every colour can resolve from a token.
- **The artboards are the contract.** The kit's static specimen pages, every primitive and every screen drawn with fixture data, open in a browser with no build, no server and no keys, and every screen in the app is composed from the same kit they show.
- **How the app consumes the kit**, once screens are built in the app. `tokens.css` is imported once in the root layout and is the source of the Tailwind theme: utilities resolve to `var(--token)`, never to a literal, and a hex value in a component is a review failure. `kit.css` is imported next. Each primitive becomes a React component of the same name that keeps its class names, and screens compose components, not classes. The artboards are the reference for markup and copy, not code to port: their fixtures are fixtures, and the real model goes behind the same shapes.
## Theme
- **One palette or two, decided at the design stage.** Two token sets mean `<html data-theme>` rendered on the server from a first-party cookie, so the first paint is already the right one, and a contrast test that parses `tokens.css` and checks every stated floor for every set that exists — control edges composited onto their real surface before the 3:1 check. One set skips the second palette, not the test. Whichever it is, the browser harnesses pin one `colorScheme` and say why.
- **When no cookie means "follow the device", the server cannot know which palette is showing.** The set that is not the default is then written twice — under `:root[data-theme=…]` and inside `@media (prefers-color-scheme: …)` under `:root:not([data-theme])` — and the token test parses each block on its own and asserts the two declare the same names and values. Splitting the file at the first selector lumps both blocks into one, so a value edited in only one of them passes every contrast test and shows a different palette depending on how the reader got there. Every mark that changes with the theme (a logo variant, a toggle's sun and moon) ships both variants and is switched in CSS for all three states, never picked at render from a theme the server does not know; a toggle with no stored choice reads `matchMedia` before it flips. (`2026-10-21`, a monitoring product tested its duplicated dark block only as part of the first, so drift between them would have passed; a live Q&A product pins the two as equal.)
- **Some surfaces never follow the theme**, because the person who set the cookie is not the one looking. Anything a camera must read keeps identical paper and ink in every set; anything shown to a room on a shared display pins one set whatever the cookie says (in a live Q&A product: the QR code, and the projector view behind a speaker, which re-scopes the dark set). Name them in the kit README when they exist.
## Colour and state
- **State is form as well as text; colour is never the only carrier.** A status is a word plus a shape, a chip or a changed edge. A refusal belongs to the field that caused it and takes the place of that field's meta line, so nothing moves.
- **The accent acts; state colours report; a healthy screen says so in its own colour.** The accent is for what a person can press or has chosen in the content; where they are in the navigation is drawn neutral. A count of zero wears no alarm colour. Before calling a design done, list the most saturated things on the main screen when nothing is wrong and what each says: if they say *press* and *beware*, the product cannot feel reassuring however good its parts are. (`2026-10-22`, a monitoring product: its healthy overview's loudest colours were the accent button, an accent-tinted nav item, and amber and red icons on tiles counting zero.) What is neither an action nor a state wears neither: a callout that only informs is neutral (a grey wash, its icon in secondary ink), and the logo is the logo everywhere, never greyed, tinted or swapped to show a state. (`2026-10-22`, the same product: its info callout used the accent's wash and read lavender, and its owner, on the rail's grey mark: "Why this is gray? This is our logo.")
- **Action and state never share a colour.** On a product whose job is to report health, green is the answer to the product's own question: a green button says "fine" where it means "press". Pick the accent from a hue no state uses, and keep it there. (`2026-10-22`, a monitoring product weighed and kept a blue accent against a green one for exactly this.)
- **Tints keep their base hue, measured.** Compute the OKLCH hue of every wash, tint and dark-mode variant of the accent, not only the accent (`scripts/color.py`); one more than about 8° off its base reads as a different colour. (`2026-10-22`, a monitoring product: a 267° blue's wash sat at 280° and its owner asked why the product was violet.)
- **Before saturating a state colour, measure what colour-blind people keep.** A chart that tells healthy from warning by hue alone loses the difference for red-green colour blindness; lightness carries it. Compare the lightness contrast of the pair (`scripts/color.py`) before making a healthy bar "greener". (`2026-10-22`, a mid-green bar would have dropped the healthy/warning lightness ratio from 2.0:1 to 1.6:1.)
- **Every summary of one state comes from one function.** The headline, its icon, the counts, the sidebar and the row badges each restate the same state; when they are computed separately they disagree on the same screen. An icon added beside a sentence inherits that sentence's truth, and "never checked" and "checked, no verdict yet" are different words. An all-clear is a claim about every item: it needs each one checked and healthy, and paused is paused, never counted as up. (`2026-10-22`, a monitoring product: its public status page said "All systems operational" as soon as any one component was up, and drew a paused one as a green "Operational" row. The same day, a new green mark beside an existing all-clear headline showed for a monitor that had not been checked, and two review rounds found two more sentences on that screen disagreeing with it.)
## The cascade and the primitives
- **Resets at zero specificity.** `:where(.screen button)`, never `.screen button`: a tag-scoped reset outranks every single-class rule in the kit, restyles every third party inside its scope, and fails by element type, which is why nobody sees it. The invariant to test: the same kit class on a `<button>` and an `<a>` computes equal styles.
- **The kit styles only the elements it has been asked for.** When a page brings in an element no screen has used (an ordered list, a table, a definition list, a code block), grep `kit.css` for its selector first: if it is missing, the global reset is drawing it, and nothing goes red because the words are still right. Write the new rule beside its sibling (`.prose ol` beside `.prose ul`) and pin the pair against each other in a unit test, never against literals. (`2026-09-22`, a live Q&A product: a page of step-by-step instructions rendered its four ordered lists with no numbers, no indent and no gaps while every text assertion passed.)
- **One native top-layer primitive** for dialogs and popovers — `<dialog>` with `showModal()`, `popover="auto"` — whose `undismissable` state refuses accidental dismissal (Escape, backdrop and a vendor's key handler). Each call site says its reason in a comment. A Server Action in flight also refuses explicit close. A secret the server shows once keeps its head's close button: before the secret is copied, the first press shows an inline warning that closing loses it, and a second press discards it and closes. Pin these paths with a browser test. (`2026-09-20`, a live Q&A product: Escape inside the identity provider's organization modal destroyed a shown-once token. `2026-11-03`, an evals product's owner could not find how to close such a dialog and chose "Keep X with a warning".) Destructive actions confirm first. Initial focus is the native `autofocus` attribute, set before `showModal()`; React's `autoFocus` prop never renders it. An open modal dialog also takes Escape on `window` in the capture phase and stops propagation before a vendor hears it; an undismissable one also prevents default. **A vendor's menu inside a modal dialog renders inside it.** A menu portalled to `<body>` opens beneath the dialog's top layer, over a page the dialog has made inert, so nobody sees or reaches it: give the vendor the dialog as its portal container (for Clerk, `UNSAFE_PortalProvider` with `getContainer` returning the dialog; Clerk's docs, read `2026-10-25`). (`2026-10-24`, a monitoring product: on a phone, the workspace switcher's menu in the navigation drawer, a modal dialog, never appeared.) **Every dialog has a close button in its head**, an icon-only control with an `aria-label`, disabled while a Server Action is in flight, not only a Cancel in its footer. (`2026-11-03`, an evals product's definition dialog closed only from its footer.)
- **The primitive puts back what Tailwind's preflight takes away.** A modal `<dialog>` is centred only by the browser's own `margin: auto`, which preflight zeroes, so the dialog class sets it; a dialog also inherits text styles from wherever its trigger sits, top layer or not, so the class resets `text-align`, `white-space`, font size, weight and line height. A popover element carries no author `display` — layout goes on an inner wrapper — because any author `display` overrides the browser's `display: none` that hides a closed popover. A unit test reads `kit.css` and pins these declarations. A scroll box that holds a table with visually hidden (`.sr-only`) headers is `position: relative`, or the absolutely positioned headers escape it and widen the page. (`2026-10-21`, a monitoring product: every dialog opened at the top left, one opened from a table's actions cell came out right-aligned and unwrapped, and five pages scrolled sideways on a phone.)
- **A grid stretches what it holds.** A lone button or link placed straight in a grid container, as a card often is, fills its track; actions sit in a row primitive. A tag-scoped container rule (`.page-head > div { display: grid }`) outranks the row class inside it, the zero-specificity rule above by another name. (`2026-11-03`, an evals product: a link-button stretched across its card, and an action row stacked vertically.)
- **A column sized in `ch` is sized for one font.** `ch` is the advance of the digit zero in the element's font, not a character count, so a typeface change silently resizes every `ch` column. On a face change, grep the kit for `ch`, re-measure each column against the widest string it can hold at every size it renders, and write the measurement in a comment beside the value. (`2026-09-18`, a live Q&A product: a mono-to-proportional switch left `4ch` too narrow for `100%`.)
## Controls
- **Each button variant means one thing, and keeps it.** The kit README names the variants; whatever they are called, they rank how much an action matters: the action a group exists for (at most one per group), a secondary action that does something, and a quiet variant held to the allow-list below. **Cancel is always the secondary**, because a quiet Cancel reads as loose text beside boxed buttons. A destructive variant is the secondary's twin in the danger colour, and a destructive confirmation is never the primary. Every enabled variant answers hover with a token tint. **A button never changes variant because it is disabled**: the disabled rule makes it look unavailable before anyone tries it, and a swap to a lighter variant makes the unavailable control look more clickable than the available one. Variant rules are never scoped to the screen root, because a custom page inside a vendor's modal renders outside it. Pin the destructive variant against the secondary by parsing `kit.css`, not against literals. (`2026-09-16` and `2026-10-06`, a live Q&A product: disabled buttons that looked live, three primaries that swapped to a ghost while disabled, and a primary scoped to the screen that lost its fill inside Clerk's organization modal.) **The quiet variant creeps.** Hold it to an allow-list — icon-only buttons with an `aria-label`, and toggles in a panel's own head — with a unit test that scans every use in source, links included, so no other text control wears it. Text navigation is a link (`<a href>`) in the kit's link style or the primary or secondary variant, never the quiet one. (`2026-10-22`, a monitoring product: borderless Cancels and creation buttons in five places.) (`2026-11-07`, a live Q&A product: following this paragraph's first half produced eleven quiet text buttons, mostly navigation.)
- **A plan-gated control is something to press, so its mark wears the accent**, never a warning colour, which says something is wrong. Pressed, it opens one offer with the plan's own numbers and one way on, and that way lands on a page that opens with the plan and its button, not with usage or a summary. A limit nothing lifts is a disabled control with the sentence that says why. (`2026-10-24`, a monitoring product: every upgrade mark led to a billing page that opened with usage, and its owner, upgrading on a phone, found the plan table and its Subscribe button far below.)
- **A choice whose options need explaining is a list, not a segment.** A segmented control is right when the option names are the whole story (Light / Dark). When they are not, each option is a `<label>` holding a native radio, a name and a sentence, in a `fieldset` whose `legend` names the choice, so arrow keys and "1 of N" come free; the sentence is announced through `aria-describedby` rather than folded into the name; anything longer goes in a native `<details>`, never a tooltip, which has no touch equivalent. The picked option shows its state with a full border and a filled radio or check, plus a wash if wanted, never the primary action's fill and never a left bar: a left bar means *you are here* (navigation) or *how bad* (severity). Never draw any bar as an inset `box-shadow` on a rounded box: it bends at the corners, and forced-colours mode drops it, so the selection vanishes in Windows high contrast. A severity bar is a clipped `::before`. (`2026-09-21`, a live Q&A product: three one-word options told the person nothing about what each would do. `2026-10-22`, a monitoring product: its selected card's inset bar curved at both ends and disappeared under forced colours.)
- **Emulate forced colours on every selected, current and focused state.** `box-shadow` is dropped and backgrounds come from the system, so a state drawn only with either disappears in Windows high contrast. Borders, outlines and native controls survive.
- **An icon-only control holds an icon and nothing else.** It is a fixed 44px square, and a visible label put in it prints across whatever sits beside it; a labelled control sizes to its word and keeps the height. A label overflowing its control is tested as geometry (the `test-harness` skill, `references/rules-from-bugs.md`). (`2026-09-04`, a live Q&A product: three labelled actions shipped in the icon control and printed across each other while every DOM assertion passed.)
- **A setting keeps its native input.** Style a real `<input type="checkbox">` — the label, focus ring and form value come free — with a 44px hit area, never a `<div>` dressed as one. A toggle is for something that takes effect now, not for a setting that decides how a thing will behave later.
- **A secret that isn't a password is not a password field.** `type="password"` with `autocomplete="new-password"` is what asks the browser to offer a generated password. An API key goes in a plain text field with `autocomplete="off"` and `spellcheck="false"`, and once saved it is shown masked by the server (its last four characters), never put back in the field. (`2026-11-03`, an evals product: its API-key field asked Chrome to suggest a generated password.)
- **The focus ring is set once at the screen root and never removed.** Any ambient motion honours `prefers-reduced-motion` with a static fallback.
## Text and content
- **Numbers and addresses are tokens, never prose**: `flex: none`, `white-space: nowrap`, and no inherited text transform. An empty state borrows the typography of the populated one, never its rank, count or badge.
- **Text a person typed wraps completely, a word with no spaces included.** The screen root sets inherited `overflow-wrap: anywhere`, outside any media query, so every primitive added later inherits it; grid and flex text tracks can shrink (`min-width: 0`); no ellipsis, line clamp or hidden tail stands in for the text. `nowrap` is allowed only on machine text — fixed action labels, generated counts and dates, the tokens above, visually hidden labels — each a named selector with its reason. A unit test walks every declaration in `kit.css`, media queries included: it requires the root rule and refuses truncation, a weaker wrap, or a `nowrap` on a selector not in the list. The browser check measures the wrapped lines of the longest permitted input, because a clipped tail can leave the page width unchanged. (`2026-09-17`, a live Q&A product: a long unbroken word in a person-authored field ran past its column.)
- **Monospace is for code.** A URL, a host name or an email address in an input is not code, and a monospace face puts a visible gap after `https:`. Mono stays for what a person would paste into a terminal or a config: JSONPath, cron lines, header values, DNS answers, tokens.
- **Structure encodes something true.** Number a list only when it is ranked or a real sequence and the number is the item's position.
- **Flags are SVG, never emoji**, because Windows shows a flag emoji as two letters; a flag marks a real place only, and never sits beside an address the person supplied, where it reads as where their server is.
## Layout and the phone
- **Phone-first for anything public, and narrow is the kit's job, not the screen's**: 44px targets, the primary action above the fold, the longest permitted input wrapping inside its column (the rule above), and a `max-width` on every screen so nothing runs edge to edge on a wide display. State the supported floor in the kit README (a live Q&A product's is 320px) and assert at it; forms cap to their column, flex and grid ancestors allow shrinking, inputs are border-box, and horizontal overflow is never hidden to make a page-width assertion pass. What a person reads is checked with `innerText`, not `textContent`.
- **On a phone, the long column gives way, never the state.** A state word is machine text and never breaks across lines; the column holding a typed address takes the squeeze and wraps. Counts go into one strip, never a 2 × 2 grid of large numbers, and a short page does not stretch fixed chrome to fill the screen. Check at 390 and 360 as well as the floor. (`2026-10-22`, a monitoring product: "Not checked yet" broke over three lines in its monitor table, and four large count tiles filled a phone's first screen.)
- **A shell's `auto 1fr` rows give the `1fr` to whatever comes second.** A layout that adds a second bar takes that row and stretches to fill a short page; nest the bar inside the content row. (`2026-11-03`, an evals product: a large empty band under its menu.)
- **"Are the borders clear?" is usually about depth and grouping, not border strength.** Measure the hairline before darkening it. A surface reads as solid from a page a step off white, a faint resting shadow, and fewer boxes. Count the containers on a screen and the surface styles among them: bordered tiles, grey borderless cards and panels on one screen read as clutter. One stat strip beats five tiles, one panel of rows beats three cards, and settings read best as label-left, control-right rows in one card per section. (`2026-10-22`, a dashboard's hairline already measured 1.25:1 against the admired reference's 1.20:1; its monitor page had 12 boxes in three styles.)
## Vendor surfaces
- **Vendor surfaces wear the tokens through their appearance API** — for Clerk, `appearance.variables` referencing `var(--token)`, with a test that every referenced token exists in every set — and are measured on the rendered DOM, because which elements a vendor paints text with is not derivable from its docs. A kit token that shares its name with one of the vendor's own custom properties refers to itself inside the vendor's scope: alias it through a name only the product uses. (`2026-10-22`, a monitoring product: Clerk's primary button, handed the kit's `--accent`, a name Clerk also defines, went transparent.)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |