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/screens.md
View on GitHub# Screens: what they may say, and how to look at them
The two halves of a screen nobody's assertion covers: whether its sentences are true, and whether it looks right. The capture harness's own rules (the release set, where captures live, sweeps) are the `test-harness` skill's, `references/captures.md`.
## What a screen may claim
Read before changing what a screen says, not only before testing it.
- **A label guessed from a cookie may only choose between two names for the same link.** A public header may read a session hint, such as Clerk's `__client_uat` cookie, to say "Sign in" or "Dashboard"; that guess is never evidence of a session, never shows a member's data, and never changes where the button goes, so a stale cookie costs one extra redirect and nothing else.
- **A sentence is only as true as the chrome around it, and an empty state that borrows a populated one inherits its claims.** Borrow the typography, never the component's rank, count or badge: an empty state has no item to count. **A change that makes one surface honest is not finished until every surface saying the same thing has it** — look across the gallery, not only the diff. (`2026-09-17`, an empty state arrived numbered 01 with a count of 0, and a second surface still captioned a code nobody could use.)
- **A screen may claim only what its own feed can see — and an imperative is a claim.** A filtered public feed cannot distinguish no activity from activity it withholds. **Promise primacy only where the feed is unfiltered; read a guard against every state it runs in; keep the claim in one object both suites import.** Two regex copies are two invariants, and they drift. (`2026-09-17`, an invitation to be first survived one line below a title that had just stopped claiming it.)
- **A scope the person picks never hides an alarm outside it.** A view narrowed to one app, project or team names the scope in its heading; the global status, and every count of what needs attention, keep counting everything; and the scoped screen says what needs attention outside its scope, with a way back to all of it. (`2026-10-22`, a monitoring product: an overview scoped to a healthy app read "Everything is working" while another app was down, and on a phone nothing on the page named the filter.)
- **A sentence about *this* workspace, plan or resource is a claim the renderer must be handed something to check — a literal checks nothing.** Ask what the component would need as input to know the sentence is true; if the answer is "nothing, it is a string", it is a sentence about the product, so move it to the level where it is unconditionally true rather than widening a read to carry one adjective. **When a release makes a setting the user's to change, grep the copy for sentences that were true only because it was not**, and pin the replacement both ways: the true wording present, the stale claim absent. (`2026-09-21`, a banner announced a mode the same release had just stopped forcing, and no value reached the screen that a test could hold it against.)
- **Sell only what runs.** Every selling or promising surface uses one tested launch list, labels unbuilt items *Coming soon*, and keeps them unavailable. Apply `release-gate` § The paid-launch check before enabling billing or promoting. (`2026-10-22` to `2026-10-24`, a monitoring product: its footer named a check location nothing ran from; four features were sold as part of the paid plan while unbuilt, and the terms promised locations; and on the day production's checks started, the live site still said they hadn't.)
- **A form fills in only what the person told it, or a stated default; everything else starts empty, with an example as its placeholder.** A guessed value that looks real is a claim about the person's own system, and saved as typed it fails or checks nothing. No example on a first-run or empty screen names the author's own data: an address is `https://example.com`. (`2026-10-22`, a monitoring product: its add form appended `/api/health` to the address and prefilled an assertion on `$.db.ok`, a subdomain and a 06:00 schedule, and its first-run form offered the owner's own app names and URL to every new user.)
- **A control that screens one field has not screened the row it rides on, and the unscreened field arrives wearing the screened one's approval.** A reader cannot see which fields of a row were judged. When a surface carries a control — moderation, a classifier, a review step, a check on a model's output — list **every field the surface renders**, attached names and labels included, and ask which of them anything checks; pin or fix the rest. Key the fix on the field, never on one mode of the control, or the modes where nobody noticed stay open. (`2026-09-21`, a display name checked only for length reached every screen under content a classifier had approved, and the report came from a mode that a fix keyed on the classifier's mode would have left open.)
- **What a person reads is not the string the test read, and CSS is where the two part company.** A number or address is a token, never prose: `flex: none`, `white-space: nowrap`, and no inherited label transform. `innerText` applies `text-transform` and line breaking; `textContent` does not. Assert rendered text — better, fetch the address the screen actually displays. (`2026-09-17`, a wrapped counter and an uppercased URL passed text-node assertions.) **A general rule can break the next screen:** single-glyph cells sharing one budget fit only because they shrink, and `flex: none` would make them overflow. Name an exception like that where it lives, with the reason it is safe beside its number, and pin it — checked by re-adding `flex: none` and watching the pin go red. (`2026-09-20`, a row of code cells measured clear only because they shrink.)
- **A reset scoped by tag outranks the design system it precedes, and fails by element type.** `.screen button` outranks a single class; **write resets at zero specificity**, such as `:where(.screen button)`. Test the invariant: the same kit class on `<button>` and `<a>` has equal computed styles. **The reset also restyles every third party inside its scope.** Check the new pin against the old bug by restoring the bad rule on a running page and watching it go red; borrowed container rules can neutralise the property a probe compares. (`2026-09-17`, the reset overrode both the kit and Clerk while a first probe silently agreed.) **And a reset also wins where the kit has no rule at all:** an element no screen has used before — an ordered list, a table, a code block — is drawn by the reset, and no assertion sees it, because there is no wrong value to find. Check the kit for its selector first (`method.md`, the kit styles only the elements it has been asked for). (`2026-09-22`, a product's first ordered lists rendered with no numbers, no indent and no gaps while every text assertion passed.)
- **A stated invariant with no test is a comment.** When a file claims to be the single source of something, the test that proves it belongs beside the claim. (`2026-09-16`, a colour literal violated the token file's unenforced rule for months.)
- **A test that pins a rule has not pinned its call site, and when a component's contract changes, enumerating its callers is the work.** A registry can prove a class carries `nowrap` while nothing proves the screen puts the address inside that class: delete the wrapper and every gate stays green. Pin both, with a render assertion in the layer that ships. Splitting a component in two, or changing what a prop means, moves the subject to the call sites: types cannot see it when the prop survives, and unit tests cannot because the defect lives between a component and its caller — so list every caller before the change, not as a check afterwards. **When a requirement is spatial, pin the container, not the order:** an index comparison stays green for every wrong placement that keeps the sequence. (`2026-09-20`, a wrapper nothing pinned, and a split that left a settings panel saying a logo was saved while showing no image; `2026-09-21`, a logo "above" the title sat outside the panel that holds it.)
- **A test that pins a phrase has not pinned the claim.** `toContain` proves a true sentence exists, not that a false neighbour is absent; a forbidden literal dies when the lie is reworded. Assert the claim, and when two documents carry it, pin their agreement. (`2026-09-16`, a privacy-page phrase guard missed the same promise in the terms.)
- **A rename does not make an absence fail; it makes it vacuous.** After any copy or control rename, `grep` the **old** literal across `tests/`, suites outside the gate included, instead of re-running and reading green, and re-point each hit at the exported constant the copy now lives in. A sweep keyed on the control's name misses pins on prose *about* the control, such as the sentence shown to someone who cannot use it. **Before deleting a failing pin, read what it holds up:** it may be the positive control that makes an absence below it meaningful, because an absence is assertable only when the surface is proved present (`test-harness`, `references/vendor-surfaces.md`). (`2026-09-21`, six `not.toContain` absences went on passing against a string no longer in the tree, and deleting a prose pin a name-keyed sweep had missed would have hollowed out the permission absence below it.)
- **A correction can overshoot, and overshooting is not the safe direction.** A statement worse than the truth is a different false statement. Check the replacement against the code with the same suspicion as the original. (`2026-09-16`, a privacy correction claimed reads were stored when only actions wrote rows.)
## What to verify visually
**A custom page or section inside a vendor component takes the vendor's layout.** Measure the title row, section dividers, label column and responsive layout against built-in pages at every captured width. Measure the stacking breakpoint on the section itself. The navigation can collapse at a different width. Compose the product's kit inside the sections and retain its token where the vendor breaks a kit rule. Capture the custom page beside a built-in one at the same widths. For the worked example, see `clerk-production` § The organization modal and custom pages.
(`2026-11-18`, a live Q&A product had three custom pages in one vendor modal. Two older pages appeared in captures across several releases. The checks missed them until the owner compared them with a built-in page. The built-in title aligned with the close button. Navigation collapsed at 768 px and sections stacked at 992 px. A divider using about 3.5% text color was nearly invisible in dark mode.)
Assert that text and chart marks keep each block's inset floor, the kit's own inset token (12px on the receipt's page). Assert no text overlaps text or chart marks, and no text touches images. Assert image geometry and `object-fit` preserve intended content without unintended cropping. (`2026-11-07`, a static discovery page: geometry checks found 28 problems after a passed look, including everything the owner flagged by eye.)
This list is what the exploratory pass and the on-request sweep look for, not the size of the release capture set. Phone: 390 is a capture width, not the floor. The supported floor is **320px** (WCAG 1.4.10 Reflow), asserted with geometry rather than a picture: at 320, 360 and 390, `document.documentElement.scrollWidth === clientWidth`, stacked order holds, and the counts and primary controls stay visible. Never hide horizontal overflow (`overflow-x: hidden` on the page or a wrapper) to make that assertion pass — it hides the bug. At every phone width: targets ≥ 44px, the primary action above the fold, the longest input the product allows wraps inside its column — check the whole wrapped text, not the document width, because a clipped tail leaves the page width unchanged, so put a 300-character unbroken input on the busiest surface that shows typed text — and the real keyboard does not cover the primary control. (`2026-09-17`, a product's dashboard measured 363px wide at 320 and 360 and clean at 390, so a 390-only camera never saw it.) Every lifecycle state and every empty state, in every theme, as every role in one organization (in the individual shape, its user) and as nobody at all; third-party surfaces — Clerk's sign-in, and the organization modal and pricing table where the shape has them — included. Contrast measured, not eyeballed: composite alpha onto the real surface first, and never trust a passing number without checking that the thing is still visible. Any surface read from a distance at 1920 and wider — a page with no `max-width` runs edge to edge at 3840. Desktop lists with 0, 1 and 40 rows. Then the exploratory pass (`release-gate`, its release checklist), with no list at all.
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 |