prototype-audit ยท diff
v1.0.0 to v1.0.0
68 added, 261 removed. Audit A to A.
---
name: "prototype-audit"
description: 'Mechanically audit a UX prototype or front-end build through ten self-healing passes -- deterministic design-language conformance, accessibility, performance, content, responsive layout, routes, build hygiene, usability heuristics, visual regression, and anti-slop critique. Use before declaring any prototype review-ready, or whenever the prototype-auditor sub-agent is invoked. Each pass follows check -> diagnose -> fix -> verify with a maximum of three fix cycles per pass before escalating.'
metadata:
author: "Frontier"
version: "1.0.0"
created: "2026-05-12"
updated: "2026-08-27"
compatibility:
agents: ["ux-designer", "reviewer", "prototype-auditor", "engineer"]
frameworks: ["html-css", "react", "vue", "tailwind"]
output-formats: ["markdown"]
---
# Prototype Audit
- > WHEN: A UX prototype (static HTML or working SPA) is about to be reviewed, demoed, or shipped to stakeholders. This skill is the mechanical procedure the `prototype-auditor` internal sub-agent runs. The output is a structured report at `docs/artifacts/reviews/PROTOTYPE-AUDIT-<issue>.md`.
+ > WHEN: A static HTML or SPA prototype is about to be reviewed, demoed, or shipped
+ > to stakeholders, or the `prototype-auditor` internal sub-agent is invoked.
## Inputs
- Prototype root directory (static HTML folder or SPA `dist/`).
- A live preview URL or a pinned project-local preview server over the build
output (for example, `npm exec --offline -- serve`).
- Issue number for the report filename.
- - The `accessibility/SKILL.md` checklist as ground truth for Pass 1.
+ - The [accessibility checklist](../accessibility/SKILL.md) as ground truth for Pass 1.
- `DESIGN.md` and the project-local Impeccable detector for Pass 0, when present.
+ ## Prerequisites
+
+ Identify primary tasks, design artifacts and the build representing reviewed
+ source. Browser, axe and native detector are external prerequisites; unavailable
+ checks are DEGRADED. Continue source inspection.
+
+ ## Decision Guide
+
+ Source inspection checks static contracts; browsers check interaction/layout;
+ the pinned detector checks design drift. None substitutes for another.
+
+ ## Core Rules
+
+ Report all passes 0-9 with actual execution evidence and source identity. Missing
+ tools do not mean zero findings. Waivers are separate decisions, not raw detector
+ success. A delegated auditor MUST NOT start, reset, iterate or complete the
+ parent-owned loop or change its baseline/approval history; return scoped evidence.
+ Run checks affected by a fix again, not unrelated suites.
+
+ ## Workflow
+
+ 1. Define user tasks and verify the target build and design artifacts.
+ 2. Execute passes 0-9 in order using the MUST-read recipes below.
+ 3. Repair only owned source; rerun affected checks, retaining unchanged results
+ without claiming reruns. Return evidence; the reviewer owns approval.
+
+ ## Error Handling and Pitfalls
+
+ Timeout, malformed output or unstable viewport -> DEGRADED with conditions.
+ Reproducible defects -> BLOCKED until fixed or explicitly accepted by the reviewer.
+ Never crop desktop as mobile, suppress output or copy prefilled axe/PASS claims.
+ MUST read [failure and handoff rules](references/report-template.md#failure-handling)
+ when a check fails or returning evidence; after three failed fixes, escalate.
+
## Output
`docs/artifacts/reviews/PROTOTYPE-AUDIT-<issue>.md` with one section per pass:
```markdown
## Pass <N>: <Name>
- Status: PASS | FIXED | BLOCKED | DEGRADED
- Cycles used: 0..3
- Findings:
- <finding> -- <fix applied or escalation reason>
- Verification: <how it was reconfirmed>
```
## Loop contract
Each pass runs at most three fix cycles:
- 1. **Check** -- run the tool or inspection for this pass.
- 2. **Diagnose** -- map each failure to a known recipe in the auto-fix library or mark it `escalate`.
- 3. **Fix** -- apply the recipe or open a finding entry.
- 4. **Verify** -- re-run the check. Stop on PASS. If still failing after three cycles, mark BLOCKED and continue to the next pass.
+ 1. Check: run the tool or inspection for this pass.
+ 2. Diagnose: map each failure to a recipe or mark it `escalate`.
+ 3. Fix: apply the recipe or open a finding entry.
+ 4. Verify: re-run the check. Stop on PASS. After three unsuccessful cycles,
+ mark BLOCKED and continue to the next pass.
A BLOCKED finding does not stop the audit; it surfaces in the report and blocks the eventual review approval.
## Pass 0: Design-language conformance (deterministic)
- Reference: `design/impeccable-integration/SKILL.md`.
-
- Runs first, before any LLM judgement, so later passes critique a surface that
- already conforms to its own design language.
-
- Tool: the project-local Impeccable detector (pinned devDependency, not bare
- `npx`).
-
- ```bash
- npm exec --offline -- impeccable detect --json <prototype-root>
- ```
-
- Status for this pass is `PASS`, `FIXED`, `BLOCKED`, or `DEGRADED`:
-
- - Exit `0`, or all findings waived -> `PASS`
- - Exit `2`, findings fixed within three cycles -> `FIXED`
- - Exit `2`, findings unresolved and unwaived -> `BLOCKED`
- - Detector could not run -> `DEGRADED`, and the audit continues on Frontier-only
- checks with the reason recorded verbatim
-
- `DEGRADED` is not a pass. It records that 59 deterministic rules and the 4
- design-system conformance rules did not run, so a reader can tell which bar
- this prototype was actually held to.
-
- Waivers go through the `anti-slop` Waiver Protocol, never through
- `impeccable ignores` alone. See
- [Impeccable Integration](../impeccable-integration/SKILL.md) for the rule.
-
- ## Pass 1: Accessibility
-
- Reference: `design/accessibility/SKILL.md`.
-
- Tools: axe-core (CLI or playwright), manual keyboard pass, manual screen-reader smoke test.
-
- Check list (mechanical):
-
- - axe-core `serious` + `critical` violations
- - Missing `alt` on `<img>` and meaningful `<svg role="img">`
- - Icon-only buttons missing `aria-label`
- - Progress / loading regions missing `role="progressbar"` with valuenow/min/max
- - `outline: none` without a `:focus-visible` replacement
- - Modal without focus trap
- - Color contrast under 4.5:1 (body) or 3:1 (large text)
- - Reduced-motion guard CSS present and effective
- - Skip link as first focusable element
-
- Auto-fix recipes:
-
- | Symptom | Recipe |
- |---------|--------|
- | `<img>` missing alt | Generate from filename or visible caption; mark decorative if purely ornamental |
- | Icon-only `<button>` | Add `aria-label` from the parent action label |
- | Missing progressbar role | Wrap with `role="progressbar"` + `aria-valuenow/min/max` |
- | `outline: none` | Add `:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 2px; }` |
- | Glass surface with poor contrast | Add `@supports not (backdrop-filter: blur(1px)) { ... }` fallback to solid surface |
- | Touch target under 44 px | Add `min-height: 44px; min-width: 44px;` to the rule |
-
- ## Pass 2: Performance
-
- Tools: Lighthouse (preferable in CI), `npm run build` bundle stats.
-
- Check list:
-
- - Initial route bundle <= 250 KB gzip
- - Lighthouse Performance >= 85 on the production preview
- - No render-blocking custom font; use `font-display: swap`
- - Images below the fold use `loading="lazy"`
- - Heavy routes split with `React.lazy` + `Suspense`
- - No layout shift on initial render (CLS = 0)
-
- Auto-fix recipes:
-
- | Symptom | Recipe |
- |---------|--------|
- | Route bundle bloated | Replace barrel imports (`import { X } from "lib"`) with deep imports |
- | Lazy route missing fallback | Wrap with `<Suspense fallback={<Skeleton />}>` |
- | Image without `loading="lazy"` | Add the attribute below the fold; remove above the fold |
- | Font flash | Add `font-display: swap` and preload the WOFF2 |
-
- ## Pass 3: Content
-
- Check list:
-
- - No `Lorem ipsum`, `TODO`, `FIXME`, `lorem`, `xxx`, or placeholder copy in shipped surfaces
- - No broken `<a href>` to internal routes
- - All headings form a sequential outline (no skipped levels)
- - Page titles unique per route
- - Form labels match field intent
-
- Auto-fix recipes:
-
- | Symptom | Recipe |
- |---------|--------|
- | Placeholder copy | Replace with reviewed copy from `src/data/` or open a content finding |
- | Broken internal link | Update to canonical route OR add to the 404 list for content review |
- | Skipped heading level | Demote/promote heading to fit the outline |
- | Duplicate page titles | Add a `<Title>` component that combines page name + app name |
-
- ## Pass 4: Responsive layout
-
- Test breakpoints: 360, 640, 1024, 1440, 1920 px.
-
- Check list:
-
- - No horizontal scroll on any breakpoint (except inside explicit `overflow-x: auto` containers like `<pre>`)
- - Touch targets remain >= 44x44 on small breakpoints
- - Navigation collapses gracefully (hamburger or stacked) below 640 px
- - Tables wrap or scroll horizontally with a visible affordance below 1024 px
-
- Auto-fix recipes:
-
- | Symptom | Recipe |
- |---------|--------|
- | Horizontal scroll from a `<pre>` | Add `overflow-x: auto; max-width: 100%;` to the rule |
- | Image overflows | Add `max-width: 100%; height: auto;` |
- | Nav overflows | Switch to a stacked or sheet pattern below 640 px |
- | Table overflows | Wrap with `<div style="overflow-x:auto">` and add a scroll-hint shadow |
-
- ## Pass 5: Routes
-
- For SPAs only. Skip for static HTML.
-
- Check list:
-
- - Every link in the rendered DOM resolves to a known route
- - A catch-all `*` route renders a real 404 page (not blank)
- - Each route has a unique `<title>`
- - Deep-linking works: opening a non-root route directly does not 404 against the static server
-
- Auto-fix recipes:
-
- | Symptom | Recipe |
- |---------|--------|
- | No `*` route | Add `<Route path="*" element={<NotFound />} />` |
- | Static host 404 on refresh | Add a SPA rewrite (`/* -> /index.html`) in `vercel.json` / `_redirects` / `staticwebapp.config.json` |
- | Missing per-route title | Adopt a `<Helmet>` or `<Title>` component pattern |
-
- ## Pass 6: Build hygiene
-
- Check list:
-
- - `npm run build` exits 0 with zero TypeScript errors and zero warnings
- - `npm run lint` exits 0
- - No `console.log` left in shipped code
- - No committed secrets (API keys, tokens) -- scan with the Frontier secret-scan tool
- - `package.json` and lockfile are in sync
-
- Auto-fix recipes:
-
- | Symptom | Recipe |
- |---------|--------|
- | TypeScript error | Fix locally; never disable strict mode for the audit |
- | Stray `console.log` | Remove or guard with `if (import.meta.env.DEV)` |
- | Lockfile drift | Run `npm install` and commit the updated lock |
- | Committed secret | Rotate the secret upstream first, then remove from history |
-
- ## Pass 7: Usability heuristics
-
- Reference: `design/usability-heuristics/SKILL.md`.
-
- Check list:
-
- - Each of Nielsen H1-H10 inspected against the top 3-5 user tasks
- - Every finding scored on the 0-4 severity rubric
- - No severity 3 (major) or 4 (catastrophic) finding left unfixed without an explicit accepted waiver
- - Content failures (vague errors, missing empty states, jargon) cross-checked against `design/content-design`
-
- Auto-fix recipes: defer to the heuristic-specific patterns in `design/usability-heuristics/SKILL.md` -- this audit only enforces that the inspection was run and scored, not how each fix is implemented.
-
- ## Pass 8: Visual regression (optional, recommended)
-
- Reference: `design/visual-regression/SKILL.md`.
-
- Skip only when the prototype is a single throwaway HTML file with no iteration planned.
-
- Check list:
-
- - Baselines exist for every primary route at mobile (360), tablet (768), and desktop (1440)
- - Playwright `toHaveScreenshot` suite runs to completion with `maxDiffPixelRatio <= 0.01`
- - Determinism rules applied (animations disabled, fonts settled, volatile content masked)
- - Any baseline update in this audit cycle is reviewable in the PR diff with a justification
-
- Auto-fix recipes:
-
- | Symptom | Recipe |
- |---------|--------|
- | Animation flake | Add `vr-mode` class + `animations: "disabled"` and re-run |
- | Font flake | `await page.evaluate(() => document.fonts.ready)` before screenshot |
- | Live data flake | Mask the volatile region with `data-vr-mask` and re-run |
- | Intentional layout change | Update baseline with `--update-snapshots`; document in audit report |
+ MUST read [Impeccable Integration](../impeccable-integration/SKILL.md) first.
+ Before LLM judgement, use the installed bridge and target-local native engine
+ with verified version and SHA-256, never a downloading shim. Missing bridge/pin
+ is DEGRADED. Retain advisories and raw BLOCKED findings; review waivers separately.
+ Timeouts, malformed reports and incomplete coverage cannot be waived to PASS.
+ Record actual fallback execution with evidence, not template assertions.
<!--
Source: 5-dimension pre-emit self-critique rubric and anti-slop pass
adapted from alchaincyf/huashu-design via nexu-io/open-design
(Apache-2.0). See repository NOTICE.
-->
- ## Pass 9: Anti-slop self-critique (pre-emit hard gate)
-
- Before the prototype is emitted for review, run the 5-dimension self-critique
- from the `anti-slop` skill. Each dimension is scored 1-5; anything under 3/5
- on any axis is a P0 hard-gate finding and the prototype must be revised
- before Pass 9 is re-run. Anything at 3/5 is a P1 (should-fix). 4/5 and 5/5
- are passing.
-
- **Severity convention** (applies to all 10 passes):
-
- - **P0** -- hard gate. Prototype is not review-ready until resolved.
- - **P1** -- should-fix before review unless explicitly waived in the audit
- report with rationale.
- - **P2** -- nice-to-have. Logged for follow-up.
-
- ### The five dimensions
-
- 1. **Philosophy** -- Does the surface have a defended point of view? Generic
- SaaS template = 1. Clearly derived from a brand spec or visual direction
- = 5.
- 2. **Hierarchy** -- Can a first-time viewer name the primary action within
- one second? Every element competing = 1. One CTA wins decisively = 5.
- 3. **Execution** -- Spacing, alignment, contrast, and typography quality.
- Default Tailwind everywhere with no scale = 1. Disciplined tokens and
- intentional rhythm = 5.
- 4. **Specificity** -- Does the prototype use real (or honestly-placeholder)
- content and product-specific concepts? Lorem ipsum + stock metrics = 1.
- Product-true content with cited placeholders = 5.
- 5. **Restraint** -- Did the build avoid the tells Pass 0 cannot see? Scope
- this to the Frontier-retained set: emoji as iconography (T2), fabricated
- metrics and testimonials (T3), unearned trust badges (T8), and
- emoji-prefixed headings (T10), plus judgement-only glassmorphism,
- hierarchy, and composition concerns. Visual tells with a deterministic
- rule, including extreme radius and hand-drawn SVG, are Pass 0's job -- do
- not re-litigate them here. Any retained violation present unwaived = 1.
- None present = 5.
-
- ### Procedure
-
- 1. Confirm Pass 0 status. Run the Frontier-retained tell check (T2, T3, T8,
- T10) and the honest-placeholders check. If Pass 0 was `DEGRADED`, also
- run the full T1-T10 list, since no deterministic rule covered them.
- 2. Score each of the five dimensions 1-5 with a one-line justification
- each.
- 3. If a brand-spec exists for the issue, score against the brand-spec
- prohibited-patterns list, not generic taste.
- 4. Any dimension below 3/5 = P0; fix and re-run from step 1.
- 5. Record final scores and justifications in the audit report under
- "Pass 9: Anti-slop self-critique".
+ ## Pass Order and Required Recipes
- Maximum three revision cycles before escalating to the user.
+ MUST read [passes 0-4](references/passes-0-4.md) before running any of those
+ passes, and [passes 5-9](references/passes-5-9.md) before running any of those
+ passes or assigning severity.
- ## Reporting template
+ | Pass | Check |
+ |------|-------|
+ | 0 | Design-language conformance, deterministic first |
+ | 1 | Accessibility |
+ | 2 | Performance |
+ | 3 | Content |
+ | 4 | Responsive layout |
+ | 5 | Routes (SPAs only; skip static HTML) |
+ | 6 | Build hygiene |
+ | 7 | Usability heuristics |
+ | 8 | Visual regression (skip only single throwaway HTML with no iteration) |
+ | 9 | Anti-slop self-critique, pre-emit hard gate |
- Write `docs/artifacts/reviews/PROTOTYPE-AUDIT-<issue>.md` using the
- [prototype audit report template](references/report-template.md).
+ MUST read the [report template](references/report-template.md) when writing the
+ audit. Pass 9 scores five axes: below 3/5 is P0; 3/5 is P1; 4-5/5 pass. Across
+ all passes, P0 blocks readiness; P1 needs a fix or reasoned waiver; P2 is follow-up.
## Done Criteria
- All passes have a status of PASS or FIXED; Pass 0 may be DEGRADED only when
the report records the reason and the full Frontier fallback checks, and any
BLOCKED findings must be explicitly accepted in the review document.
- No severity 3 or 4 usability finding (Pass 7) remains open without a documented waiver.
- Auto-fix recipes were applied through the prototype source, not by patching the build output.
- Verification step recorded for every fix.
- - Report committed to `docs/artifacts/reviews/`.
-
- ## Skills to Compose With
+ - Report committed to `docs/artifacts/reviews/` by the authorized owner.
- - `design/accessibility` (Pass 1 ground truth)
- - `design/usability-heuristics` (Pass 7 ground truth)
- - `design/content-design` (cross-check for Pass 3 and Pass 7)
- - `design/visual-regression` (Pass 8 ground truth)
- - `development/browser-automation` (runtime for axe, Lighthouse, Playwright)
- - `design/working-prototype-app` (route + build context)
- - `design/prototype-craft` (visual fixes for contrast / motion)
- - `development/browser-automation` (axe-core + Lighthouse automation)
- - `development/error-handling` (auto-fix loop discipline)