--- 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: ```text 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: ```text 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: ```text 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`