@tamsensedev/runner 0.10.0 → 0.18.0

package/library/skills/verification-before-completion/SKILL.md

@@ -1,113 +1,113 @@
----
-name: verification-before-completion
-description: Use right before saying work is done, fixed or passing, before the final commit, and before writing the final report or verdict: run the project's checks fresh, read their output, re-read the diff, check each acceptance criterion, and report only what the evidence shows.
----
-
-# Verification before completion
-
-Evidence before claims. A claim about the state of the work ("tests pass", "bug fixed", "criterion met") is allowed only if you ran the command that proves it in this run, after your last change, and read its output.
-
-```
-NO COMPLETION CLAIM WITHOUT FRESH EVIDENCE
-```
-
-## The gate, for every claim
-
-1. **Identify** the command that proves the claim.
-2. **Run** it in full, now, after your last edit.
-3. **Read** the output: exit code, number of failures, warnings, skipped tests.
-4. **Compare**: does the output actually support the claim?
-5. **Only then** state it, with the evidence. If not, state the real status.
-
-| Claim | Needs | Not enough |
-|---|---|---|
-| Tests pass | Test run with 0 failures, exit code 0 | An earlier run, "should pass" |
-| Lint is clean | Linter output with 0 errors | Type check passing |
-| Build works | Build command, exit code 0 | Lint and tests passing |
-| Bug is fixed | The original reproduction now passes | "The code changed" |
-| Regression test works | Seen failing without the fix, passing with it | Passing once |
-| Criterion met | A specific check per criterion | All tests green |
-| A helper agent did it | The diff and a check you ran yourself | The agent's summary |
-
-## Steps
-
-### 1. Run the project's checks
-
-Use the commands found during `project-orientation` (CI order is a good default): build, type check, lint, tests. Run them in every repository you changed. The `test-runner` agent can run them and return a summary if the logs are long.
-
-- Keep exit codes visible. When trimming output with a pipe, use `set -o pipefail` or check `$?` of the real command, so `| tail` does not turn a failure into success.
-- Count results: "412 passed, 0 failed, 3 skipped", not "tests look fine".
-- Compare with the baseline. A failure that was there before your change is pre-existing: report it, do not hide it, do not fix unrelated code for it. A new failure is yours: fix it and run again.
-- Watch for new warnings, unhandled errors or skipped tests that your change introduced.
-- If a check cannot run here, say which and why. Never report a check you did not run as passing.
-
-### 2. Re-read the full diff
-
-`git diff <base>...HEAD` plus `git diff` and `git status` for uncommitted work. Read it as a reviewer would:
-
-- Every changed line is needed for the task.
-- No debug output, `[DEBUG-` tags, commented-out code, stray files, temporary scripts.
-- No secrets, tokens, personal data, `.env` files or local paths.
-- Names, structure and style match the surrounding code and the project's rules.
-- Nothing unrelated slipped in (formatting churn, lock file changes you did not intend).
-
-### 3. Check each acceptance criterion
-
-Go through the spec's criteria one by one. For each: met, partly met or not met, and how you know (test name, command output, file:line). "All tests pass" does not prove a criterion unless a test covers it.
-
-### 4. Think about what you did not check
-
-Other callers of changed functions, migrations and their order, configuration and environment variables, permissions, empty and error states, narrow screens for UI. Check the risky ones; list the rest under "Not verified".
-
-### 5. Make sure the work is committed
-
-In every repository you changed: `git status` is clean (or the leftovers are explained), and `git log --oneline <base>..HEAD` shows your commits. See `clean-commits`.
-
-## The final report
-
-The report is evidence, not an impression. Use this shape and fill it with real commands and real results:
-
-```
-Changes
-- src/billing/tax.ts: default to the shop's country when the customer has none
-- src/billing/tax.test.ts: test for customers without a country
-
-Checks (run after the last change)
-- pnpm typecheck: exit 0
-- pnpm lint: exit 0, 0 warnings
-- pnpm test -- --run: 213 passed, 1 failed (src/date.test.ts "formats in local time zone": failed in the baseline too, unrelated, not touched)
-- new test seen failing before the fix: "expected 0.2, received NaN"
-
-Acceptance criteria
-1. Invoice is created for a customer without a country: met (tax.test.ts "no country")
-2. VAT uses the shop's country: met (same test, rate 0.2 for DE shop)
-
-Not verified
-- Real payment provider (no sandbox credentials)
-
-Assumptions
-- Shop country comes from settings.shop.country; the spec does not name the field
-
-Noticed, not changed
-- src/billing/currency.ts rounds half-even, the rest of billing rounds half-up
-```
-
-In review and test steps the same rules apply to the report you pass with the verdict: every statement about the code is backed by something you ran or read, with the command or file:line.
-
-## Red flags
-
-- Words like "should", "probably", "seems to" about the state of the work.
-- Saying "done" or "all good" before running anything.
-- Relying on a run from before your last edit.
-- Trusting a helper agent's "success" without looking at the diff.
-- Running only the new test and calling the suite green.
-- Leaving a failure out of the report because it was not yours.
-
-| Excuse | Reality |
-|---|---|
-| "It should work now" | Run it. |
-| "I'm confident" | Confidence is not evidence. |
-| "The linter passed" | The linter does not compile or run the code. |
-| "Partial check is enough" | It proves the part you checked, nothing more. Say which part. |
-
-Sources: obra/superpowers (MIT, commit bb92a77) verification-before-completion and affaan-m/ECC (MIT, commit 30b6892) verification-loop. Changed: merged with our own checklist, report template added.
+---
+name: verification-before-completion
+description: Use right before saying work is done, fixed or passing, before the final commit, and before writing the final report or verdict: run the project's checks fresh, read their output, re-read the diff, check each acceptance criterion, and report only what the evidence shows.
+---
+
+# Verification before completion
+
+Evidence before claims. A claim about the state of the work ("tests pass", "bug fixed", "criterion met") is allowed only if you ran the command that proves it in this run, after your last change, and read its output.
+
+```
+NO COMPLETION CLAIM WITHOUT FRESH EVIDENCE
+```
+
+## The gate, for every claim
+
+1. **Identify** the command that proves the claim.
+2. **Run** it in full, now, after your last edit.
+3. **Read** the output: exit code, number of failures, warnings, skipped tests.
+4. **Compare**: does the output actually support the claim?
+5. **Only then** state it, with the evidence. If not, state the real status.
+
+| Claim | Needs | Not enough |
+|---|---|---|
+| Tests pass | Test run with 0 failures, exit code 0 | An earlier run, "should pass" |
+| Lint is clean | Linter output with 0 errors | Type check passing |
+| Build works | Build command, exit code 0 | Lint and tests passing |
+| Bug is fixed | The original reproduction now passes | "The code changed" |
+| Regression test works | Seen failing without the fix, passing with it | Passing once |
+| Criterion met | A specific check per criterion | All tests green |
+| A helper agent did it | The diff and a check you ran yourself | The agent's summary |
+
+## Steps
+
+### 1. Run the project's checks
+
+Use the commands found during `project-orientation` (CI order is a good default): build, type check, lint, tests. Run them in every repository you changed. The `test-runner` agent can run them and return a summary if the logs are long.
+
+- Keep exit codes visible. When trimming output with a pipe, use `set -o pipefail` or check `$?` of the real command, so `| tail` does not turn a failure into success.
+- Count results: "412 passed, 0 failed, 3 skipped", not "tests look fine".
+- Compare with the baseline. A failure that was there before your change is pre-existing: report it, do not hide it, do not fix unrelated code for it. A new failure is yours: fix it and run again.
+- Watch for new warnings, unhandled errors or skipped tests that your change introduced.
+- If a check cannot run here, say which and why. Never report a check you did not run as passing.
+
+### 2. Re-read the full diff
+
+`git diff <base>...HEAD` plus `git diff` and `git status` for uncommitted work. Read it as a reviewer would:
+
+- Every changed line is needed for the task.
+- No debug output, `[DEBUG-` tags, commented-out code, stray files, temporary scripts.
+- No secrets, tokens, personal data, `.env` files or local paths.
+- Names, structure and style match the surrounding code and the project's rules.
+- Nothing unrelated slipped in (formatting churn, lock file changes you did not intend).
+
+### 3. Check each acceptance criterion
+
+Go through the spec's criteria one by one. For each: met, partly met or not met, and how you know (test name, command output, file:line). "All tests pass" does not prove a criterion unless a test covers it.
+
+### 4. Think about what you did not check
+
+Other callers of changed functions, migrations and their order, configuration and environment variables, permissions, empty and error states, narrow screens for UI. Check the risky ones; list the rest under "Not verified".
+
+### 5. Make sure the work is committed
+
+In every repository you changed: `git status` is clean (or the leftovers are explained), and `git log --oneline <base>..HEAD` shows your commits. See `clean-commits`.
+
+## The final report
+
+The report is evidence, not an impression. Use this shape and fill it with real commands and real results:
+
+```
+Changes
+- src/billing/tax.ts: default to the shop's country when the customer has none
+- src/billing/tax.test.ts: test for customers without a country
+
+Checks (run after the last change)
+- pnpm typecheck: exit 0
+- pnpm lint: exit 0, 0 warnings
+- pnpm test -- --run: 213 passed, 1 failed (src/date.test.ts "formats in local time zone": failed in the baseline too, unrelated, not touched)
+- new test seen failing before the fix: "expected 0.2, received NaN"
+
+Acceptance criteria
+1. Invoice is created for a customer without a country: met (tax.test.ts "no country")
+2. VAT uses the shop's country: met (same test, rate 0.2 for DE shop)
+
+Not verified
+- Real payment provider (no sandbox credentials)
+
+Assumptions
+- Shop country comes from settings.shop.country; the spec does not name the field
+
+Noticed, not changed
+- src/billing/currency.ts rounds half-even, the rest of billing rounds half-up
+```
+
+In review and test steps the same rules apply to the report you pass with the verdict: every statement about the code is backed by something you ran or read, with the command or file:line.
+
+## Red flags
+
+- Words like "should", "probably", "seems to" about the state of the work.
+- Saying "done" or "all good" before running anything.
+- Relying on a run from before your last edit.
+- Trusting a helper agent's "success" without looking at the diff.
+- Running only the new test and calling the suite green.
+- Leaving a failure out of the report because it was not yours.
+
+| Excuse | Reality |
+|---|---|
+| "It should work now" | Run it. |
+| "I'm confident" | Confidence is not evidence. |
+| "The linter passed" | The linter does not compile or run the code. |
+| "Partial check is enough" | It proves the part you checked, nothing more. Say which part. |
+
+Sources: obra/superpowers (MIT, commit bb92a77) verification-before-completion and affaan-m/ECC (MIT, commit 30b6892) verification-loop. Changed: merged with our own checklist, report template added.

package/library/skills/web-interface-guidelines/SKILL.md

@@ -1,202 +1,202 @@
----
-name: web-interface-guidelines
-description: Use when writing or reviewing web UI code for interaction and detail rules: accessibility basics, focus, forms, animation, typography details, long content, images, performance, URL state, touch, safe areas, dark mode, locale formatting, hover states and copy. A vendored checklist with file:line findings; project conventions override it.
----
-
-# Web interface guidelines
-
-A terse checklist of details that make web interfaces work well, vendored from Vercel's Web Interface Guidelines so it never changes under a run and needs no network. Use it in two ways:
-
-- **Code step:** after changing UI, check the files you touched against the rules and fix what applies.
-- **Review step:** check the changed UI files of the branch and report findings in the format below. Do not edit product code.
-
-## How these rules sit with the project
-
-- The project's own conventions win: its CLAUDE.md / AGENTS.md, DESIGN.md, lint rules, component library and existing copy style.
-- **Capitalization:** the original list asks for Title Case on headings and buttons. Our default is sentence case, unless the project already uses Title Case. Match the existing strings.
-- **Placeholders ending with an ellipsis** and **`&` instead of "and"** are Vercel house style. Follow the project.
-- Rules marked **[React]** use React or Next.js APIs. In other frameworks apply the idea with the framework's equivalent (Vue `v-model`, Svelte `bind:`, Angular forms, `<RouterLink>`, `<NuxtLink>`), or skip it if it has no equivalent.
-- "Keyboard handlers" below means custom interactive elements. Native `<button>`, `<a href>` and form controls already handle the keyboard.
-- Deeper accessibility work lives in the `accessibility` skill; visual design in `interface-design`; motion values in `motion-design`.
-
-## Rules
-
-### Accessibility
-
-- Icon-only buttons need `aria-label`
-- Form controls need `<label>` or `aria-label`
-- Custom interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp` or the framework's equivalent)
-- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
-- Images need `alt` (or `alt=""` if decorative)
-- Decorative icons need `aria-hidden="true"`
-- Async updates (toasts, validation) need `aria-live="polite"`
-- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
-- Headings hierarchical `<h1>` to `<h6>`; include skip link for main content
-- `scroll-margin-top` on heading anchors
-- Meaningful media needs captions, transcripts, or descriptions as applicable
-- Media controls need keyboard support; decorative media needs assistive-tech hiding
-
-### Focus states
-
-- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
-- Never `outline-none` / `outline: none` without focus replacement
-- Use `:focus-visible` over `:focus` (avoid focus ring on click)
-- Group focus with `:focus-within` for compound controls
-- Sticky headers/footers/overlays must not cover the focused element
-
-### Forms
-
-- Inputs need `autocomplete` and meaningful `name`
-- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
-- Never block paste (`onPaste` + `preventDefault`)
-- Labels clickable (`htmlFor` [React] / `for`, or wrapping control)
-- Disable spellcheck on emails, codes, usernames (`spellCheck={false}` [React] / `spellcheck="false"`)
-- Checkboxes/radios: label + control share single hit target (no dead zones)
-- Submit button stays enabled until request starts; spinner during request
-- Errors inline next to fields; focus first error on submit
-- Placeholders show an example pattern (Vercel style also ends them with `…`; follow the project)
-- `autocomplete="off"` on non-auth fields to avoid password manager triggers
-- Warn before navigation with unsaved changes (`beforeunload` or router guard)
-
-### Animation
-
-- Honor `prefers-reduced-motion` (provide reduced variant or disable)
-- Animate `transform`/`opacity` only (compositor-friendly)
-- Never `transition: all`; list properties explicitly
-- Set correct `transform-origin`
-- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
-- Animations interruptible: respond to user input mid-animation
-- Autoplay motion >5 seconds alongside other content needs pause, stop, or hide controls
-- Muted decorative loops must stop under `prefers-reduced-motion`
-
-### Typography
-
-- `…` not `...`
-- Curly quotes `“` `”` not straight `"`
-- Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
-- Loading states end with `…`: `"Loading…"`, `"Saving…"`
-- `font-variant-numeric: tabular-nums` for number columns/comparisons
-- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
-
-### Content handling
-
-- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
-- Flex children need `min-w-0` to allow text truncation
-- Handle empty states: don't render broken UI for empty strings/arrays
-- User-generated content: anticipate short, average, and very long inputs
-
-### Images
-
-- `<img>` needs explicit `width` and `height` (prevents CLS)
-- Below-fold images: `loading="lazy"`
-- Above-fold critical images: `priority` [Next.js] or `fetchpriority="high"`
-
-### Performance
-
-- Large lists (>50 items): virtualize (`virtua` [React], `content-visibility: auto`, or the framework's virtual list)
-- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
-- Batch DOM reads/writes; avoid interleaving
-- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke [React]
-- Add `<link rel="preconnect">` for CDN/asset domains
-- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
-- Prefer `<video autoplay muted loop playsinline>` over animated GIF; provide a still alternative
-- Short non-essential loops: Safari H.264 MP4 `<picture>` source, `prefers-reduced-motion` media condition, and still fallback
-
-### Navigation and state
-
-- URL reflects state: filters, tabs, pagination, expanded panels in query params
-- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
-- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar) [React]
-- Destructive actions need confirmation modal or undo window, never immediate
-
-### Touch and interaction
-
-- `touch-action: manipulation` (prevents double-tap zoom delay)
-- `-webkit-tap-highlight-color` set intentionally
-- `overscroll-behavior: contain` in modals/drawers/sheets
-- Page rubber-band suppression: `overscroll-behavior: none` on `<html>` inside `@media (pointer: fine)`; keep coarse-pointer page defaults for pull-to-refresh. Test hybrid touch devices: `pointer` describes the primary input, and `none` also disables scroll chaining and native swipe navigation
-- During drag: disable text selection, `inert` on dragged elements
-- Drag/swipe/pinch/path gestures need tap/click and keyboard alternatives unless essential
-- `autoFocus` sparingly: desktop only, single primary input; avoid on mobile
-
-### Safe areas and layout
-
-- Full-bleed layouts need `env(safe-area-inset-*)` for notches
-- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
-- Flex/grid over JS measurement for layout
-
-### Dark mode and theming
-
-- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
-- `<meta name="theme-color">` matches page background
-- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
-
-### Locale and i18n
-
-- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
-- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
-- Detect language via `Accept-Language` / `navigator.languages`, not IP
-- Brand names, code tokens, identifiers: wrap with `translate="no"` to prevent garbled auto-translation
-
-### Hydration safety [React, other SSR frameworks have the same class of issue]
-
-- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
-- Date/time rendering: guard against hydration mismatch (server vs client)
-- `suppressHydrationWarning` only where truly needed
-
-### Hover and interactive states
-
-- Buttons/links need `hover:` state (visual feedback)
-- Interactive states increase contrast: hover/active/focus more prominent than rest
-
-### Content and copy
-
-- Active voice: "Install the CLI" not "The CLI will be installed"
-- Sentence case for headings/buttons unless the project uses another style (Vercel's original: Title Case, Chicago style)
-- Numerals for counts: "8 deployments" not "eight"
-- Specific button labels: "Save API key" not "Continue"
-- Error messages include fix/next step, not just problem
-- Second person; avoid first person
-- `&` over "and" where space-constrained (house style; follow the project)
-
-### Anti-patterns (flag these)
-
-- `user-scalable=no` or `maximum-scale=1` disabling zoom
-- `onPaste` with `preventDefault`
-- `transition: all`
-- `outline-none` without focus-visible replacement
-- Inline `onClick` navigation without `<a>`
-- `<div>` or `<span>` with click handlers (should be `<button>`)
-- Images without dimensions
-- Large arrays `.map()` without virtualization
-- Form inputs without labels
-- Icon buttons without `aria-label`
-- Hardcoded date/number formats (use `Intl.*`)
-- `autoFocus` without clear justification
-- Animated GIF when compressed video is suitable
-- Gesture-only action without tap/click and keyboard alternative
-
-## Output format
-
-Group by file. Use `file:line`. Terse findings: the issue and the location; explain only when the fix is not obvious. No preamble.
-
-```text
-## src/Button.tsx
-
-src/Button.tsx:42 - icon button missing aria-label
-src/Button.tsx:55 - animation missing prefers-reduced-motion
-src/Button.tsx:67 - transition: all -> list properties
-
-## src/Modal.tsx
-
-src/Modal.tsx:12 - missing overscroll-behavior: contain
-src/Modal.tsx:34 - "..." -> "…"
-
-## src/Card.tsx
-
-pass
-```
-
-Only report rules that apply to the changed code, and only where the project does not deliberately do otherwise.
-
-Sources: rules text from vercel-labs/web-interface-guidelines command.md (MIT, Copyright (c) 2025 Vercel Labs; changed: vendored instead of fetched, React-specific rules marked, Title Case replaced by sentence case as the default, house-style rules marked, dashes and symbols normalised, intro and precedence notes added).
+---
+name: web-interface-guidelines
+description: Use when writing or reviewing web UI code for interaction and detail rules: accessibility basics, focus, forms, animation, typography details, long content, images, performance, URL state, touch, safe areas, dark mode, locale formatting, hover states and copy. A vendored checklist with file:line findings; project conventions override it.
+---
+
+# Web interface guidelines
+
+A terse checklist of details that make web interfaces work well, vendored from Vercel's Web Interface Guidelines so it never changes under a run and needs no network. Use it in two ways:
+
+- **Code step:** after changing UI, check the files you touched against the rules and fix what applies.
+- **Review step:** check the changed UI files of the branch and report findings in the format below. Do not edit product code.
+
+## How these rules sit with the project
+
+- The project's own conventions win: its CLAUDE.md / AGENTS.md, DESIGN.md, lint rules, component library and existing copy style.
+- **Capitalization:** the original list asks for Title Case on headings and buttons. Our default is sentence case, unless the project already uses Title Case. Match the existing strings.
+- **Placeholders ending with an ellipsis** and **`&` instead of "and"** are Vercel house style. Follow the project.
+- Rules marked **[React]** use React or Next.js APIs. In other frameworks apply the idea with the framework's equivalent (Vue `v-model`, Svelte `bind:`, Angular forms, `<RouterLink>`, `<NuxtLink>`), or skip it if it has no equivalent.
+- "Keyboard handlers" below means custom interactive elements. Native `<button>`, `<a href>` and form controls already handle the keyboard.
+- Deeper accessibility work lives in the `accessibility` skill; visual design in `interface-design`; motion values in `motion-design`.
+
+## Rules
+
+### Accessibility
+
+- Icon-only buttons need `aria-label`
+- Form controls need `<label>` or `aria-label`
+- Custom interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp` or the framework's equivalent)
+- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
+- Images need `alt` (or `alt=""` if decorative)
+- Decorative icons need `aria-hidden="true"`
+- Async updates (toasts, validation) need `aria-live="polite"`
+- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
+- Headings hierarchical `<h1>` to `<h6>`; include skip link for main content
+- `scroll-margin-top` on heading anchors
+- Meaningful media needs captions, transcripts, or descriptions as applicable
+- Media controls need keyboard support; decorative media needs assistive-tech hiding
+
+### Focus states
+
+- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
+- Never `outline-none` / `outline: none` without focus replacement
+- Use `:focus-visible` over `:focus` (avoid focus ring on click)
+- Group focus with `:focus-within` for compound controls
+- Sticky headers/footers/overlays must not cover the focused element
+
+### Forms
+
+- Inputs need `autocomplete` and meaningful `name`
+- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
+- Never block paste (`onPaste` + `preventDefault`)
+- Labels clickable (`htmlFor` [React] / `for`, or wrapping control)
+- Disable spellcheck on emails, codes, usernames (`spellCheck={false}` [React] / `spellcheck="false"`)
+- Checkboxes/radios: label + control share single hit target (no dead zones)
+- Submit button stays enabled until request starts; spinner during request
+- Errors inline next to fields; focus first error on submit
+- Placeholders show an example pattern (Vercel style also ends them with `…`; follow the project)
+- `autocomplete="off"` on non-auth fields to avoid password manager triggers
+- Warn before navigation with unsaved changes (`beforeunload` or router guard)
+
+### Animation
+
+- Honor `prefers-reduced-motion` (provide reduced variant or disable)
+- Animate `transform`/`opacity` only (compositor-friendly)
+- Never `transition: all`; list properties explicitly
+- Set correct `transform-origin`
+- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
+- Animations interruptible: respond to user input mid-animation
+- Autoplay motion >5 seconds alongside other content needs pause, stop, or hide controls
+- Muted decorative loops must stop under `prefers-reduced-motion`
+
+### Typography
+
+- `…` not `...`
+- Curly quotes `“` `”` not straight `"`
+- Non-breaking spaces: `10&nbsp;MB`, `⌘&nbsp;K`, brand names
+- Loading states end with `…`: `"Loading…"`, `"Saving…"`
+- `font-variant-numeric: tabular-nums` for number columns/comparisons
+- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
+
+### Content handling
+
+- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
+- Flex children need `min-w-0` to allow text truncation
+- Handle empty states: don't render broken UI for empty strings/arrays
+- User-generated content: anticipate short, average, and very long inputs
+
+### Images
+
+- `<img>` needs explicit `width` and `height` (prevents CLS)
+- Below-fold images: `loading="lazy"`
+- Above-fold critical images: `priority` [Next.js] or `fetchpriority="high"`
+
+### Performance
+
+- Large lists (>50 items): virtualize (`virtua` [React], `content-visibility: auto`, or the framework's virtual list)
+- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
+- Batch DOM reads/writes; avoid interleaving
+- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke [React]
+- Add `<link rel="preconnect">` for CDN/asset domains
+- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
+- Prefer `<video autoplay muted loop playsinline>` over animated GIF; provide a still alternative
+- Short non-essential loops: Safari H.264 MP4 `<picture>` source, `prefers-reduced-motion` media condition, and still fallback
+
+### Navigation and state
+
+- URL reflects state: filters, tabs, pagination, expanded panels in query params
+- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
+- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar) [React]
+- Destructive actions need confirmation modal or undo window, never immediate
+
+### Touch and interaction
+
+- `touch-action: manipulation` (prevents double-tap zoom delay)
+- `-webkit-tap-highlight-color` set intentionally
+- `overscroll-behavior: contain` in modals/drawers/sheets
+- Page rubber-band suppression: `overscroll-behavior: none` on `<html>` inside `@media (pointer: fine)`; keep coarse-pointer page defaults for pull-to-refresh. Test hybrid touch devices: `pointer` describes the primary input, and `none` also disables scroll chaining and native swipe navigation
+- During drag: disable text selection, `inert` on dragged elements
+- Drag/swipe/pinch/path gestures need tap/click and keyboard alternatives unless essential
+- `autoFocus` sparingly: desktop only, single primary input; avoid on mobile
+
+### Safe areas and layout
+
+- Full-bleed layouts need `env(safe-area-inset-*)` for notches
+- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
+- Flex/grid over JS measurement for layout
+
+### Dark mode and theming
+
+- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
+- `<meta name="theme-color">` matches page background
+- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
+
+### Locale and i18n
+
+- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
+- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
+- Detect language via `Accept-Language` / `navigator.languages`, not IP
+- Brand names, code tokens, identifiers: wrap with `translate="no"` to prevent garbled auto-translation
+
+### Hydration safety [React, other SSR frameworks have the same class of issue]
+
+- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
+- Date/time rendering: guard against hydration mismatch (server vs client)
+- `suppressHydrationWarning` only where truly needed
+
+### Hover and interactive states
+
+- Buttons/links need `hover:` state (visual feedback)
+- Interactive states increase contrast: hover/active/focus more prominent than rest
+
+### Content and copy
+
+- Active voice: "Install the CLI" not "The CLI will be installed"
+- Sentence case for headings/buttons unless the project uses another style (Vercel's original: Title Case, Chicago style)
+- Numerals for counts: "8 deployments" not "eight"
+- Specific button labels: "Save API key" not "Continue"
+- Error messages include fix/next step, not just problem
+- Second person; avoid first person
+- `&` over "and" where space-constrained (house style; follow the project)
+
+### Anti-patterns (flag these)
+
+- `user-scalable=no` or `maximum-scale=1` disabling zoom
+- `onPaste` with `preventDefault`
+- `transition: all`
+- `outline-none` without focus-visible replacement
+- Inline `onClick` navigation without `<a>`
+- `<div>` or `<span>` with click handlers (should be `<button>`)
+- Images without dimensions
+- Large arrays `.map()` without virtualization
+- Form inputs without labels
+- Icon buttons without `aria-label`
+- Hardcoded date/number formats (use `Intl.*`)
+- `autoFocus` without clear justification
+- Animated GIF when compressed video is suitable
+- Gesture-only action without tap/click and keyboard alternative
+
+## Output format
+
+Group by file. Use `file:line`. Terse findings: the issue and the location; explain only when the fix is not obvious. No preamble.
+
+```text
+## src/Button.tsx
+
+src/Button.tsx:42 - icon button missing aria-label
+src/Button.tsx:55 - animation missing prefers-reduced-motion
+src/Button.tsx:67 - transition: all -> list properties
+
+## src/Modal.tsx
+
+src/Modal.tsx:12 - missing overscroll-behavior: contain
+src/Modal.tsx:34 - "..." -> "…"
+
+## src/Card.tsx
+
+pass
+```
+
+Only report rules that apply to the changed code, and only where the project does not deliberately do otherwise.
+
+Sources: rules text from vercel-labs/web-interface-guidelines command.md (MIT, Copyright (c) 2025 Vercel Labs; changed: vendored instead of fetched, React-specific rules marked, Title Case replaced by sentence case as the default, house-style rules marked, dashes and symbols normalised, intro and precedence notes added).