SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsfigma-pixel-verify

figma-pixel-verify

Design & creation

View repository

Updated 10-16 08:47

About this skill

Figma Pixel Verify

Measure a running UI against a Figma living artifact (Inventory + Spec) and write pass/fail evidence into its Verify section (or a Spec source sibling). On a non-pass row, fix and remeasure in this run. Actual values come from a laid-out read. Do not overwrite Figma expected. Do not edit figma-pixel-implement skill prose.

When to use

  • After figma-pixel-implement (or any Figma implement pass that left a durable inventory + spec path)
  • User asks to check pixel alignment / design fidelity / acceptance against the design mockup
  • Standalone: user provides Figma URL + running preview URL/route; persist a minimal inventory + spec to the same path convention before measuring

Inputs

  1. Living artifact — File path from implement. Same columns as implement reference (state, mode, basis). After an implement run this session, do not silently rebuild a missing table and claim that handoff complete—FAIL and return to figma-pixel-implement.
  2. Runnable UI — Document surfaces, preferred first: a component-workbench story from the living artifact’s Stories subsection (or a detected Storybook-style workbench) → a lightweight isolated harness (stub out host/engine dependencies) → the in-product preview route → a full app/browser launch (heaviest, last resort). Surfaces with no computed-style API use layout-probe: a command that mounts the control in the shipping parent (the container the screen uses), runs layout, and prints frames. A command that lays out the control with no parent is not a measurement.
  3. Running-UI screenshot when the channel can open a UI (storybook, isolated-harness, preview, full-app): save a png, jpg, jpeg, or webp of that UI this run and cite its path. A layout-probe that cannot open a UI records Screenshot: not-openable and does not invent an image. The image is supporting evidence. It does not replace numeric checks.

Workflow (ordered)

  1. Preflight — Resolve the measurement channel per the ladder in reference.md. Document UIs: Stories-subsection story → detected component workbench → in-product preview → full app launch (last resort). Surfaces with no computed-style API, or with every document rung unavailable: layout-probe — a command this run executes that mounts the control inside the shipping parent (the same container the screen uses), runs one layout pass, and prints the control's width, height, and child frames. A command that lays out the control with no parent is not a measurement. Build the smallest probe the project toolchain can run when none exists, then run it. If no workbench exists, make one advisory adoption suggestion; if the workbench is broken, fall down the ladder and record it; declare the channel in the report (storybook | isolated-harness | preview | full-app | layout-probe). Confirm the chosen channel is reachable. Resolve Spec source (living-artifact path). The Inventory plus Spec is the list of rows to measure. If this run already implemented from Figma and the file is missing or critical rows are absent: Overall FAIL, return to figma-pixel-implement to complete the table—do not invent rows and claim handoff complete. If this is standalone (no implement this run): persist a minimal inventory + spec using implement’s path convention, then measure. Note theme scope (mode) and visual states. When multiple themes are in scope, identify how the running UI switches themes (data-theme, toggle, system preference) before measuring. Browser channel (quality gate): On macOS, if the ego-browser skill (or its install script) is available and the CLI is already usable, or the install finishes in this turn without waiting on a person, use it before other document channels. If install still needs GUI onboarding, record that and continue with the next reachable JS-eval or layout-probe channel in this turn. Do not copy that product’s TaskSpace/CLI API into this skill. If the OS is not macOS, the skill/install path is absent, or install is blocked, continue with another channel and record which one was used. Missing ego-browser does not abort verify.
  2. Vision — When the model can inspect images, capture UI vs Figma screenshot; note gross mismatches (wrong component, missing block, theme drift, fragment-cut / stacking look). Vision is supporting evidence. When JS-eval or a layout probe can run, vision-only comparison does not produce Overall PASS. On an openable channel, keep the saved running-UI file and cite it. On a layout probe that cannot open a UI, record not-openable.
  3. Numeric measurement — For each critical visual row, switch the running UI into that row’s state and mode (prefer a real pointer hover/click/theme control through the browser channel — a declarative story entry (test id, knob, auto-action) counts as reaching the state — then read computed style and/or bounding box). On layout-probe, actual is the printed frame from that command. A source literal written to match expected leaves the row unmeasured. Map selectors carefully; prefer stable test ids when present. Default-state readings do not satisfy a hover (or other state) row. Per-mode rows under different themes are separate verdicts. Skip numeric PASS claims for out-of-scope: behavior lines — list them as behavior, not pixel PASS.
  4. Compare — Apply tolerances in reference.md. Assign a verdict per row. Unmeasured critical visual rows (JS-eval was available but the row was skipped) are blocking, not a path to Overall PASS via residuals.
  5. Fix loop — On a non-pass row, fix the running UI and remeasure in this run, then update actual/verdict columns. Continue until overall PASS or the measurement command cannot be executed. Safety cap: about 8 iterations; hitting the cap is overall FAIL with residuals listed. When the measured box matches a platform control’s intrinsic size and not the spec, the next iteration switches that control to custom-layout and assigns the spec frames in the layout pass. Do not change Spec expected. Do not patch figma-pixel-implement skill files. Do not pause for a person to judge pixels.
  6. Report — Write the Verify section of the living artifact (or the sibling report named in Spec source). Template: reference.md. Include coverage (measured vs inventory), the channel declaration (Channel: storybook | isolated-harness | preview | full-app | layout-probe), and, when the project declares a host engine older than the workbench browser, an optional note of that difference. The note does not withhold geometric PASS and does not create a human step. Rows that depend on that engine's syntax are measured with a runtime or parser at that floor, or they stay unmeasured and overall is not PASS. Component-test results may be cited as supporting evidence. For multi-theme scope, report per theme. That Verify section is the measured report hosts require. Overall is PASS only when every critical visual row in scope is PASS or accepted-residual and each actual cites a laid-out read from this turn. Overall is not PASS if any critical row is unmeasured, MISSING-style, unaccepted DRIFT, HARDCODED when the spec required a token, the spec itself is incomplete, actual was copied from a source literal, or the running UI shows an invented solid fill against Spec transparent/none, a fragment-cut graphic against a single Assets export, a generic wrapper that does not match instance geometry, a self-invented text-color alias when Spec recorded a Figma variable, or a visible graphic still on a remote design URL. When the probe command cannot run, overall is FAIL and the report names that command. Before reporting PASS, run scripts/check-figma-verify-report.mjs in this skill directory on the living artifact. Exit 0 is required. The Verify section must include Mounted in, Measurement command, Screenshot, and a ### Measurement excerpt code block whose text contains every passing row's actual numbers and colors. For storybook, isolated-harness, preview, and full-app, Screenshot is a path to a non-empty png, jpg, jpeg, or webp saved this run. For layout-probe that cannot open a UI, Screenshot is not-openable. The checker resolves a relative path from the report file's directory and rejects a missing or empty file. A screenshot file does not replace the numeric pass.

Verdict taxonomy

Verdict Meaning
PASS Within tolerance of expected, measured in the correct state / mode
DRIFT Measurable but outside tolerance
HARDCODED Value matches by luck or literal, not via project token/variable when the spec required a token — flag when token mapping was part of the contract
VARIANT Matches a different documented variant (e.g. hover/dark) than the requested one
MISSING-style Property not measurable (no node, no style, or channel unavailable)
accepted-residual Explicit frozen deviation (owner + reason). Not PASS against the Figma expected

Tool intent (platform-agnostic)

Intent Agent may use
Open/preview UI Quality channel after the macOS install gate; otherwise another JS-eval / preview channel the Agent already has
Switch visual state Real pointer hover/click/theme control, then read styles
Read laid-out frames JS evaluate in page, DevTools-like APIs, or a layout-probe command that prints frames
Screenshots Browser or Figma screenshot tools (vision inspects them when the model can see images)
Apply fixes Native edit tools, then re-measure

After a successful quality-channel install, use that channel for measurement. When install is impossible, another JS-eval path is valid. Do not copy a third-party browser API into this skill.

If no document channel exists, run a layout probe and read its printed frames. If that command cannot be executed, label numeric rows MISSING-style, name the missing command, and do not claim pixel PASS.

Relationship

Skill Boundary
figma-pixel-implement Produces code + durable Inventory/Spec; does not own final verdict
Agent-native Figma→code guidance / MCP fetch Not a substitute for measurement
Host PDCA workflows Strong-depend at install; invoke when Figma UI is in scope; missing Verify section (or Spec source sibling) fails that verification stage; spec-gap FAIL re-enters implement
ego-browser (external, macOS) Quality measurement channel: install when the skill/install path exists; not a frontmatter dependency; degrade when not installable

Pitfalls

  • Declaring PASS from screenshots alone when measurement was possible.
  • Infinite tweak loops without re-measure.
  • Treating ±1 CSS px geometry noise on high-DPR as failure without noting DPR.
  • Silent skip of mask/currentColor issues — if implement violated asset rules, call that out as root cause of color DRIFT.
  • Marking per-mode rows PASS after measuring only the default theme — each theme in scope is measured under its own theme.
  • Marking hover rows PASS from default-state styles.
  • Overall PASS while critical rows sit only in residuals as “not measured yet”.
  • Treating a frozen 18px vs 16px as PASS instead of accepted-residual.
  • Keeping the report only in chat when a living-artifact path exists.
  • Overwriting Spec expected with measured actuals.
  • After this-run implement: silently rebuilding a missing spec and claiming the handoff was complete.
  • Marking PASS for an invented solid fill, stacked leaf-path icon, generic 16/24 shell, invented text-color alias, or remote design URL.
  • Skipping a usable quality-channel CLI on macOS, then measuring only through a weaker document channel.
  • Waiting on GUI onboarding while another channel or a layout probe can run in this turn.
  • Treating a source literal that matches expected as a measured actual.
  • Copying a third-party browser TaskSpace/CLI API into this skill.
  • Aborting verify because ego-browser is unavailable on a host that cannot install it.
  • Declaring Overall PASS from vision/screenshots alone when JS-eval was available.
  • Reporting a verdict without declaring the measurement channel used.
  • Treating a workbench/engine-floor note as a reason to withhold geometric PASS or to ask a person to finish those rows.
  • Treating a layout command that never mounts the shipping parent as a measurement.
  • Reporting PASS for an openable channel without a saved non-empty screenshot file.
  • Inventing an image for a layout probe that cannot open a UI.