# Pixel Audit > Strict per-page visual-conformance audit at the verify phase — ONE page/route against a source of truth (Figma MCP nodes, or reference screens when no Figma exists). Captures a full-size pixel inventory, writes a MISSING-vs-EXTRA defect list, fixes node-by-node reusing the project's UI library (never inlining), and refuses to say "verified" until a hard element-level gate passes — served assets confirmed, getBoundingClientRect/computed-style proof, every in-scope state checked. Use when a page must match its design pixel-for-pixel during feature work. Stays inside the given SCOPE; never auto-chains; distinct from /design-system's startup preview check. - Skill: `devarfeen/pixel-audit` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add devarfeen/pixel-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/devarfeen/pixel-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: devarfeen (https://skillmd.com/u/devarfeen) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/devarfeen/pixel-audit --- # Pixel audit Audit **one page** against its source of truth, fix the mismatches, and prove each fix at the element level before claiming "verified". `/design-system` checks the whole library once at project start via its preview; this skill checks one product page during feature work — reference the project's library, never rebuild components here. ## Inputs Infer from the request; interview only for what's missing: - **TARGET PROJECT-CODE** — full Project Matrix code; sets the stack idiom and UI library. - **SCOPE** — the single page/route plus the states to audit (list/detail, modals, forms, empty/error/loading, responsive breakpoints). **Scope is a hard boundary — never edit other pages, routes, or steps.** - **SOURCE OF TRUTH** — Figma node(s) via the Figma MCP companion, or reference screens / a reference implementation when no Figma exists. Name which is in use in the artifact. If neither is available, stop and ask — never audit against memory. - **Login / env** — local credentials only, if the page needs auth. ## Load first - The target's binding context: `CONTEXT.md` and `specs/adr/`. - The project's `*-ui-coding` skill if it exists — it owns the component catalog, tokens, and gotchas. **Reuse its components; never inline.** If absent, discover the tokens, library, and preview from `/design-system`'s docs or the project code. ## Process ### 1. Map the page Find the routes, view/template/component files, partials, in-scope states, data, and the DS components the page should use. Open the component preview (e.g. `/ui/preview/all`) if one exists. ### 2. Trace the asset pipeline Identify the build/asset pipeline, cache, and container/service — how a class/style/component change actually reaches the page. ### 3. Capture the pixel inventory Write the source of truth down **before editing**. Per node/region (frame, panel, card, row, filter, tab, modal, field, button, and every empty/error/loading/responsive variant), capture it **full-size including below the fold** — never rely on a single whole-frame screenshot. Record exact `x`/`y`, size, spacing, padding, gap, font, colour, border, radius, fill, icon size, alignment, opacity, shadow, and variant. Expected values: Figma MCP node metadata/variables (exact), or measured from reference screens and marked approximate — the gate then proves relative alignment and consistency, not absolute pixels. Capture calls per source: [`references/evidence-capture.md`](references/evidence-capture.md). ### 4. Audit expected vs actual Per node/state, classify each mismatch: - **MISSING** — a source item/state absent or wrong in the app. - **EXTRA** — an app item/state not in the source. Extra UI is a defect — report it for a decision (rules under Fixing). ## The defect list artifact Resolve ``: the `*.code-workspace` directory if one exists, else the per-context root (`CONTEXT-MAP.md` at repo root), else the repo root. The filename is keyed by PROJECT-CODE so two projects' same-named pages never collide: ```text /specs/pixel-audit/--defects.md ``` Inventory and screenshots sit beside it: `--inventory.md` and `shots/-/`. One row per defect: ```markdown # Pixel Audit — () Source of truth: Scope: | # | Node | URL / State | File / Component | Mismatch | Expected | Actual | Kind | Evidence | Status | | - | ---- | ----------- | ---------------- | -------- | -------- | ------ | ---- | -------- | ------ | | 1 | Filter bar, Search field | /assets · list | components/search-field | height off | 34px | 40px | MISSING | rect=…, computed=… | open | | 2 | Row actions, extra "Delete" | /assets · list | pages/assets/index | not in source | — | delete icon present | EXTRA | ref=…, screenshot | open | ``` **Evidence** is element-level per the verification gate — not "looks off". **Status** runs `open` → `fixed` → `verified`, or `reopened` when the gate fails. ## Fixing - **One node/page/state at a time.** Do not batch unrelated fixes. - **A MISSING defect that needs behaviour, data, or interface work is a slice, not a style fix.** Record the row, route it to `/to-tickets`, and do not build it here (the boundary `/polish-batch` draws). - **Reuse the project UI library's components.** No one-off UI unless justified and documented (per the `*-ui-coding` reuse-vs-new rule). - **If a shared component must change, suggest `/design-system` extend for the library, preview, and project `*-ui-coding` skill; never patch it page-local or auto-chain.** Confirm with the user first. Other pages consume it, and this page's frame may be the outlier. Until separately authorized, leave the row `open` under Needs user and continue; never rewrite a shared component unattended. - **Stay strictly inside SCOPE.** Cosmetic nits on other pages or flows are captured with `/polish-batch`, never fixed here. - **Report, don't decide, on EXTRA:** any icon/button/field/action present in the app but absent from the source is surfaced for a user decision, not silently kept, removed, or restyled. ## Verification gate "Verified/done/fixed" is a claim you must earn per fix. - **State the env:** host/URL and browser/session, or local app build and simulator/device. - **Cross the build pipeline:** rebuild/refresh after each change and confirm the changed classes/styles/components exist in the assets the page or app actually loaded, not just source files. - **Prove each fix with element-level evidence:** selector/ref, `getBoundingClientRect()`, relevant computed styles, DOM, and a clipped screenshot when alignment matters. Native apps require equivalent inspector geometry, resolved styles, rendered tree, and screenshots from the local simulator. Full-page shots are overview only. If the required automation is unavailable, list pending manual checks and do not mark any row `verified` on assumption. - **These count as failure:** hidden, zero-size, collapsed, clipped, misaligned, wrong-size, or ignored-class elements. - **Falsify before declaring verified:** actively look for the ways the fix could be wrong (wrong breakpoint, stale asset, class not applied, element off-screen) and rule them out. - **Do not say "verified / done / fixed" unless ALL hold:** env stated · build pipeline crossed · loaded assets contain the change · element proof captured · source captured full-size · expected-vs-actual compared · every in-scope state checked. Unattempted rows stay `open`; changed rows failing the gate become `reopened`. ## Rules - Zero attribution: never add or leave co-author, AI, or tool attribution in commits, PRs, issue comments, release notes, generated docs, settings, or code comments. - **Suggest, never auto-chain.** After the audit, suggest `/code-review` then `/commit-push-close` / `/commit-push-pr`, and stop. - Decisions are **artifacts** — inventory and defect list live on disk, not in chat. - Name the full PROJECT-CODE from the Project Matrix everywhere; never mix one project's conventions, tokens, or components into another. - **Local-only.** Local creds, local browser, no cloud agents. - Sub-agents: dispatch local lanes automatically for independent work — never cloud agents; announce the lane count at dispatch and report each lane as it completes. Lanes run only step 1 (Map the page); fixing, synthesis, and the gate stay with the main agent. - Emit `Stage / Found / Next / Needs user` at each phase transition — one line per field. Phases: mapped → inventory captured → audited → fixing → verified. ## Output After in-scope fixes: ```markdown Stage: pixel-audit — audited () vs ; wrote specs/pixel-audit/--defects.md. Found: defects ( MISSING, EXTRA); verified, reopened; EXTRA items awaiting your decision. Next: /code-review the diff, then /commit-push-*. Reopened rows and EXTRA decisions stay for the next pass. Needs user: . Suggested next skills (optional): - /code-review: eyeball the in-scope diff before shipping. - /commit-push-pr (or /commit-push-close): ship the verified fixes. ``` Do not proceed past the suggestion. ## Completion criteria - [ ] Defect list exists at `/specs/pixel-audit/--defects.md`, names its source of truth and scope, one row per defect - [ ] `--inventory.md` and `shots/-/` exist beside it - [ ] Every row's Status is `verified`, `open`, or `reopened` — none left `fixed` — and each `verified` row's Evidence cell holds element-level proof - [ ] The reply ends at the `Suggested next skills (optional)` footer — nothing after it