Inspect UI

Inspect UI

The one rule: a visual claim is settled by rendering, never by inference. A careful read of a style diff produces hypotheses — "these two classes may collide", "this might overflow at phone width", "this pair looks low-contrast" — and a hypothesis reported as a finding is a guess wearing evidence's clothing. This skill turns each one into a verdict with a screenshot behind it.

0. Scope the surfaces

From the range: git diff <base>...HEAD --name-only, keep the files a browser renders (HTML, CSS/styling, JSX/TSX/Vue/Svelte components, templates). None → report no rendered surface and stop. Map each kept file to the screen(s) or route(s) where its change shows. Done when: every changed rendered file has a named screen.

1. Get it running — live first

Read docs/agents/project.md Run locally (dev) and start the app; missing → discover the command, confirm the app loads, and write it back (same contract as validate-ui). Cannot run it (no browser, server broken) → the review degrades, loudly: the report's first line says cannot drive — static review only, and every visual conclusion below carries the label unverified (static). Static reading is admissible only under that label. Done when: the app is loaded in a browser, or the degraded mode is declared.

2. Deterministic floor passes

Run before opening the browser, record the output:

• Off-token color: grep -nE '#[0-9a-fA-F]{3,8}\b|rgba?\(' over the changed style files. When the repo has a token system, a hit outside the token-definition file(s) is an Important finding; no token system → note that instead.
• Suppressed focus: grep -nE 'outline: *(none|0)' over the changed styles. A hit with no visible replacement (:focus-visible rule, custom outline/box-shadow) in the same diff is an Important finding.

These are the floor, not the review. Done when: both passes ran and their hits are recorded.

3. Hold the contract

What does "right" look like, in precedence order: the feature's design.md ## UI design section (its States: lines are the case list for step 4, its tokens the palette of record) → an Approved docs/standards/design-tokens.md (stack, token vocabulary, numeric floors, forbidden patterns — its floors set severity) → else the repo's token/theme file plus the visual language of the screens around the change. Name which contract you hold. Done when: the contract source is named in the report.

4. Drive, capture, judge

Per changed surface, in the running app (the repo's e2e harness, a browser MCP tool, or npx playwright screenshot). Screenshots land under .skills/<CODE>/inspect-ui/ (no CODE → .skills/inspect-ui/<branch>/); the working tree stays untouched.

• Viewports — 1440×900, 768, 375. At each: screenshot, and check document.scrollingElement.scrollWidth <= window.innerWidth. Horizontal overflow, clipping, or overlap at any of the three is Important. Spec silence does not downgrade it: the requirement is the page, and the rest of the page reflows — a surface that breaks at a common width is broken.
• States. Exercise every reachable state: hover, keyboard focus (Tab to each new interactive element and screenshot — is focus visible?), selected/active, disabled, empty, error — and every composed state the code makes possible (two classes on one element, emphasis while selected). The collision a static read can only call "fragile" is settled here by producing it and looking.
• Contract walk. Each States: line in the UI design section gets exercised; a state the contract names but the screen cannot reach — or reaches looking wrong — is a finding. Colors on screen trace to tokens.
• Contrast. For each new text/background pair, compute the WCAG ratio from the actual rendered values. Defaults: body text below 4.5:1 is Important; below 1.5:1 the content is effectively invisible — Critical. An Approved design-tokens.md's floors override these defaults.
• Themes. WHEN the app's styles define a second theme (prefers-color-scheme media query or a data-theme selector) → capture each changed surface in both themes; a token redefined in one theme but not the other, or a new raw value that ignores the theme split, is a finding. No second theme in the styles → skip, note once.

Read every screenshot you capture. Done when: every changed surface has its three viewport shots plus one per exercised state, all read.

5. Report — fixed shape

• One block per finding: severity (Critical / Important / Minor), file:line, screenshot path, why it matters, the fix unless obvious. A visual finding with no screenshot path and no unverified (static) label is not done — go back and capture it.
• needs-human-eyes: — the genuine taste calls the running app cannot settle (does this feel right for the brand? is this treatment too loud?). Write none when empty; this line feeds the product-walk predicate in execute-common.
• Verdict line: UI: clean | findings | cannot drive (static only).

Rationalizations

Red Flags

• A visual verdict with no screenshot path and no unverified (static) label
• Skipping the 375px viewport
• Judging a composed state from declaration order instead of producing it
• outline: none passing because "the design never mentioned focus"
• Mutating the working tree, index, or branch state during review