visual-spec-review

name	visual-spec-review
description	This skill should be used after visual-to-spec has produced 03_visual_spec/ and before design-system-governor or frontend implementation begins. It independently reviews extracted visual specs against the reference screenshot, UI type, layout paradigm, visible-element evidence, rejected assumptions, and asset strategy, catching hallucinations, inconsistencies, and implementation blockers.
argument-hint	[visual-spec-directory]

Version: 2.0.0

visual-spec-review

Review visual-to-spec outputs before implementation.

This skill audits the seven files in 03_visual_spec/ and determines whether they form a reliable frontend implementation contract.

It must not only check internal consistency. It must also verify that the visual spec still matches the reference screenshot, UI type, visible element evidence, rejected assumptions, and asset strategy.

Trigger Conditions

Use this skill when:

• visual-to-spec has produced 03_visual_spec/
• the user asks to review or validate visual specs
• the user asks whether the UI spec is reliable before implementation
• the user asks to catch hallucinations in layout-spec or component-tree
• the user asks to validate screenshot-derived tokens, layout, or component tree
• the implementation should not start until visual spec quality is confirmed

Required Inputs

Read:

03_visual_spec/
  visual-analysis.md
  layout-spec.md
  component-tree.md
  DESIGN.md
  tokens.json
  implementation-risks.md
  human-review-needed.md

Do not look for separate files such as:

ui-type-classification.md
visible-element-inventory.md
rejected-assumptions.md
asset-manifest.md

Those concepts must be read from fixed sections inside the seven visual-to-spec files.

Source of Truth Hierarchy

1. reference.png — visual appearance and screenshot facts
2. visual-analysis.md / UI Type Classification — UI type and high-level interpretation
3. visual-analysis.md / Visible Element Inventory — reference-visible evidence and bbox mapping
4. visual-analysis.md / Rejected Assumptions — forbidden interpretations
5. layout-spec.md / Layout Paradigm — layout strategy
6. component-tree.md — implementation component structure
7. implementation-risks.md / Asset Strategy — asset and rendering strategy
8. DESIGN.md — readable summary contract
9. tokens.json — consumable token values
10. human-review-needed.md — unresolved review gates

Required Sections to Read

From visual-analysis.md:

• UI Type Classification
• Visible Element Inventory
• Rejected Assumptions

From layout-spec.md:

• Layout Paradigm
• Layer Model
• Region Layout
• Forbidden Layouts

From component-tree.md:

• Component Tree Type
• bboxRef for reference-visible components
• Prohibited Components

From implementation-risks.md:

• Asset Strategy
• UI Type Drift Risks
• Asset Misuse Risks
• Hallucinated Component Risks

From human-review-needed.md:

• high-impact structure risks
• UI type confidence
• layout paradigm confidence
• asset strategy confidence
• visible element inventory completeness

From DESIGN.md:

• UI Type and Rendering Strategy
• Asset Strategy
• Forbidden Assumptions
• Implementation Rules

From tokens.json:

• source
• confidence
• strictness
• usedBy
• bboxRef if present

Review Stages

Run all review stages:

1. R0 — UI Type Consistency Review
2. R1 — Visible Element Evidence Review
3. R2 — Rejected Assumptions Review
4. R3 — Asset Strategy Review
5. R4 — Token and Schema Review
6. R5 — Component Tree Feasibility Review
7. R6 — Layout Spec Consistency Review
8. R7 — PRD / Prompt Pack Alignment Review
9. R8 — Human Review Gate Review

Detailed rules are in references/review-checklists.md.

Hard Rules

• Do not treat internal spec consistency as sufficient.
• Always validate against UI Type, Layout Paradigm, Visible Element Inventory, Rejected Assumptions, and Asset Strategy.
• Do not pass a spec if panorama-scene, image-led, or scene-led UI has been converted into a dashboard layout.
• Any reference-visible component must have bbox, bboxRef, or visual evidence in visual-analysis.md / Visible Element Inventory.
• Any component or layout listed in Rejected Assumptions, Forbidden Layouts, or Prohibited Components must be blocking.
• If the UI requires raster/image asset usage, a CSS/SVG redraw strategy for the main visual is a failure.
• Do not silently repair source specs. Report required revisions and optionally provide patches.
• Do not rewrite the UI design.
• Do not create new visual-to-spec output files.
• Do not merge this skill with design-system-governor, spec-compliance-review, or visual-acceptance-review.

Output

Write:

04_visual_spec_review/
  spec-review-report.md
  conflict-log.md
  revised-files-needed.md
  optional-patches/
    visual-analysis.patch.md
    layout-spec.patch.md
    component-tree.patch.md
    DESIGN.patch.md
    tokens.patch.json
    implementation-risks.patch.md
    human-review-needed.patch.md

Only create optional patch files when the correction is clear. Otherwise, list the required revision in revised-files-needed.md.

Pass / Conditional Pass / Fail

Pass only when:

• UI Type matches the reference screenshot
• Layout Paradigm matches UI Type
• all reference-visible components have visible evidence
• no rejected assumptions are violated
• asset strategy exists and matches the UI type
• tokens.json is parseable
• component-tree is implementable and aligned with UI Type

Fail if any of the following occurs:

• UI Type mismatch
• Layout Paradigm mismatch
• panorama-scene / image-led / scene-led UI is abstracted as dashboard
• reference-visible component lacks bbox / bboxRef / visual evidence
• Rejected Assumptions / Prohibited Components are violated
• Asset Strategy is missing or conflicts with UI Type
• main visual should be raster asset but is specified as CSS/SVG redraw
• tokens.json cannot be parsed

Supporting Files

Read these references directly:

• references/review-workflow.md
• references/review-checklists.md
• references/ui-type-review-rules.md
• references/visible-evidence-rules.md
• references/rejected-assumptions-rules.md
• references/asset-strategy-review.md
• references/pass-fail-rules.md
• references/output-files.md

Examples:

• examples/spec-review-report.example.md
• examples/conflict-log.example.md
• examples/revised-files-needed.example.md
• examples/optional-patch.example.md