Use for frontend phase work in two modes. (1) ui-phase before implementing — triggers on "design the UI", "spec the page", "frontend design contract", "what should this screen look like". (2) ui-review after implementing — triggers on "review the UI", "audit the implementation", "did it match the design", "compare to spec", "is the UI ready to ship". Works with any frontend tech stack (React, Vue, Blazor, Astro). Skip for pure backend or non-visual changes.
التثبيت
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Use for frontend phase work in two modes. (1) ui-phase before implementing — triggers on "design the UI", "spec the page", "frontend design contract", "what should this screen look like". (2) ui-review after implementing — triggers on "review the UI", "audit the implementation", "did it match the design", "compare to spec", "is the UI ready to ship". Works with any frontend tech stack (React, Vue, Blazor, Astro). Skip for pure backend or non-visual changes.
UI Workflow Skill
Three invariants apply to every step in this skill that produces or consumes a `ui-contract.md`:
The contract is the source of truth. Both ui-phase and ui-review operate against docs/plans/*-ui-contract.md on disk. Conversation memory is not the contract; the file is. If the file does not exist, neither sub-skill can proceed.
State changes use the Write or Edit tool, not narration. Saying "I've drafted the contract" without a tool call leaves nothing on disk. Every save MUST be a tool call followed by a Read-tool VERIFY pass that confirms the expected sections are present, and only then a commit.
Order is Write → Verify → Commit → Status check → Announce → (optional) chain. A git commit issued before VERIFY will commit the wrong state or fail with no diff. An announcement before the commit lets the user think state changed when it didn't. Chaining to writing-plans or regression-test before VERIFY proceeds on faith — re-confirm the artifact via Glob/Read before reading the next skill file end-to-end.
If the artifact is missing at a verify step, the previous step did not complete — return to it and retry the tool call. Do not proceed.
Prerequisites
ui-phase: No additional tools required — produces a markdown design contract.
ui-review: Requires the regression-test skill and its Playwright MCP prerequisite. See regression-test prerequisites.
Overview
This skill provides two complementary capabilities for frontend work:
Core principle: "Know what you're building before you build it. Verify what you built against what you designed."
ui-phase produces a structured design contract before implementation begins. ui-review audits the implemented UI against that contract after implementation. Together they close the design-implementation gap that causes frontend rework.
Sub-Skills
Use ui-phase when starting a frontend phase — it produces the design contract. Use ui-review when verifying a completed frontend phase — it audits the result against the contract. Both sub-skills are independent; either can run without the other, but they work best as a pair.
ui-phase
When to Use
Invoke after brainstorming approves a frontend design and before writing the implementation plan. Specifically:
When a phase involves UI components, pages, or layout work
When the design needs to be concrete enough for implementation
When the user says "let's design the UI" or "what should this look like?"
Before implementing any phase with significant visual surface area
Auto-invoked by project-orchestration:start-next-phase: when a phase in ROADMAP.md is tagged **Surface:** UI, the orchestration skill's Surface pre-plan hook runs ui-design-system first (if docs/design/MASTER.md is missing) and then ui-phase automatically before chaining to superpowers:writing-plans. Authors who use project-orchestration do not need to manually invoke this skill — they declare the surface on the phase and the routing fires ui-phase at the right moment. Manual invocation still works for ad-hoc UI design work outside the orchestration flow.
Do NOT invoke for:
Backend-only phases (API, database, services)
Configuration or infrastructure phases
Phases where UI is trivially simple (a single button with no layout)
Announce Line
"Starting ui-phase. I'll produce a UI design contract covering design system, components, layouts, interaction states, and accessibility. This will serve as the implementation spec and audit target."
Checklist
Design system — colors, typography, spacing, component library
Component inventory — list all components needed, their props, variants, states
Layout spec — desktop, tablet, mobile layouts with structure descriptions
Interaction states — loading, empty, error, success per component and page
Open questions — unresolved decisions flagged for the user
Save contract — written to docs/plans/YYYY-MM-DD-<phase>-ui-contract.md
User approval — contract reviewed and approved before implementation
Process
Read the design doc — read the relevant docs/plans/YYYY-MM-DD-*-design.md to understand the approved design. If no design doc exists yet, proceed from the brainstorming conversation context or ask the user to summarize the approved design intent before continuing.
Identify UI surface area — list all pages, routes, and components the phase will produce.
Establish design system — check in this order:
docs/design/MASTER.md exists → read it and use it as the design system. Do NOT ask the user for colors/typography — it's already defined. Note in the contract: "Design system sourced from docs/design/MASTER.md."
Existing frontend codebase → read relevant config files (Tailwind config, theme files, CSS variables, MudThemeProvider) to extract the active design system.
Neither exists → suggest running ui-design-system first: "No design system found. Run ui-design-system to generate one, or I'll ask you for the values now." Then ask: color palette, typography scale, component library.
Define components — for each identified component:
Name and purpose
Props API (what data does it accept?)
Variants (size, style, state variants)
Interaction states (loading, empty, error, success)
Visual notes (specific styling requirements)
Define layouts — for each page/route:
Desktop layout (1280px+) — describe or ASCII-diagram the structure
Tablet layout (768–1279px) — how it adapts
Mobile layout (<768px) — how it adapts
Define interaction states — page-level and form-level states, validation behavior, success/error feedback.
Present each section to the user — ask "does this look right?" after each major section. Be ready to revise.
Save the contract — use the Write tool to create docs/plans/YYYY-MM-DD-<phase-name>-ui-contract.md, structured per ui-contract-template.md. Do NOT narrate the contract content in conversation as a substitute — the file is the artifact. Saying "I've drafted the contract" without a Write tool call leaves nothing on disk for ui-review or writing-plans to read.
VERIFY the contract — re-read the file with the Read tool and confirm every required section is present (Components, Layouts at all three breakpoints, Interaction states, Design system tokens, Accessibility, Open questions). If any section is missing, the write was incomplete — re-write before committing.
Run git status and confirm a clean tree before continuing.
Transition to writing-plans — only after VERIFY and a clean commit. Confirm the contract file exists with one final Glob before chaining (docs/plans/*-ui-contract.md). Then read the superpowers:writing-plans skill file and follow it end-to-end. Do not loosely "invoke" — read the actual skill body.
ui-review
When to Use
Invoke after implementing a frontend phase to audit the result against the ui-contract. Specifically:
When a frontend phase is marked complete and needs visual verification
Before pre-push-review for branches containing frontend work
When the user says "review the UI" or "check if it matches the design"
As part of audit-milestone when the milestone includes frontend phases
Do NOT invoke when:
No ui-contract exists for the phase (no spec to audit against)
The phase has no frontend output
Announce Line
"Starting ui-review. I'll compare the implemented UI against the design contract using browser screenshots, then evaluate each contract criterion."
Checklist
Find the ui-contract — locate the relevant docs/plans/*-ui-contract.md
Invoke regression-test — get screenshots at desktop, tablet, mobile for all pages
Evaluate against contract — check each contract criterion against screenshots + code
Design system adherence — colors, typography, spacing match the contract tokens
Component coverage — all contracted components are implemented
Layout accuracy — layouts match the contracted structure at each breakpoint
Interaction states — all states (loading, empty, error, success) are implemented
Accessibility — ARIA roles, keyboard nav, contrast present as contracted
Anti-slop scan — implementation does not exhibit common AI-generated UI patterns
5-dimension critique — score the implementation against Philosophy / Hierarchy / Execution / Specificity / Restraint
Produce audit report — saved to docs/plans/YYYY-MM-DD-ui-review-<phase>.md
Process
Find the ui-contract — glob for docs/plans/*-ui-contract.md, match to the current phase by date or name. HARD GATE: if no contract is found, STOP. Do not proceed to regression-test — there is nothing to compare screenshots against. Announce: "No ui-contract found for this phase. Run ui-phase first to produce a contract, or fall back to bare regression-test if no design audit is needed." If multiple contracts exist, present the list and ask the user which applies.
Read the ui-contract — extract: components list, layout spec, design system tokens, interaction states, accessibility requirements. VERIFY: the file was readable and contains the expected sections — an empty or malformed contract is equivalent to no contract.
Invoke regression-test — only after the contract is confirmed loaded. Use the regression-test skill to capture screenshots at all three viewports (desktop: 1920×1080, tablet: 768×1024, mobile: 375×812) for all pages in the phase scope. Let regression-test handle authentication and browser automation.
Evaluate against contract — for each contracted criterion:
Criterion
How to Evaluate
Design system colors
Compare screenshot dominant colors against contract tokens; grep codebase for hardcoded hex values that aren't tokens
Typography
Inspect headings, body, captions in screenshots against font/size/weight spec
Component coverage
Verify each contracted component is present in the relevant pages
Layout (desktop)
Compare screenshot structure against contracted desktop layout
Layout (tablet)
Compare tablet screenshot against contracted tablet layout
Layout (mobile)
Compare mobile screenshot against contracted mobile layout
Loading states
Grep codebase for loading/skeleton implementations; verify visually if possible
Empty states
Grep codebase for empty state implementations
Error states
Grep codebase for error handling in UI layer
ARIA roles
Grep codebase for aria- attributes, role= — check against contract requirements
Keyboard navigation
Check for tabIndex, onKeyDown, focus management in interactive components
Color contrast
Flag any text on background color combinations that look low-contrast in screenshots
Rate each criterion:
✅ Pass — implemented as contracted
⚠️ Partial — implemented but deviates from contract
❌ Missing — contracted but not implemented
Anti-slop scan — independent of the contract, screen the implementation against the patterns that signal "AI improvised UI" rather than "a designer made decisions". The contract may be silent on these because they are expected to be obvious; in practice they slip through. Mark each as Pass (not present) or Fail (present in the implementation) with one-line evidence. Patterns to scan for:
#
Pattern
What to look for
1
Aggressive purple/violet gradient as default brand or hero
Screenshot dominant colors; check for purple-to-pink or purple-to-blue radial gradients spanning > 25% of the viewport
Grep markup for these characters in headings or feature lists
3
Rounded card with coloured left-border accent as default content block
Grep CSS/component code for border-left: on cards plus border-radius on the same element
4
Hand-drawn / cartoon SVG humans padding empty space
Inspect inline <svg> content for stylized human figures; check <img> alt text mentioning "illustration"
5
Inter / Roboto / Arial used as the display (heading) face
Check the contract's display font vs what's actually applied to h1/h2 in CSS
6
Invented metrics ("10× faster", "3× more productive") without citation
Grep marketing copy for \d+x or \d+% claims; flag any without a footnote or source
7
Filler copy in production paths ("Feature One", "Lorem ipsum", "Your headline here")
Grep content for these strings; flag any in components shipped to users
8
An icon next to every heading
Count headings that have an adjacent icon — if > 60% of headings, flag
9
A gradient on every full-width background
Count full-bleed sections; flag if gradients appear on > 1 per page
Record results in the report (see step 8 template). Each fail blocks PASS verdict regardless of contract adherence — anti-slop is a hard floor, not a contract criterion.
5-dimension critique — score the implementation 1-5 on each dimension below. This is independent of the contract; it grades the design quality, not the spec match. The contract can be honored and the result still feel cheap; this catches that.
Use the band labels strictly. Don't grade-inflate. The score is the worst sustained band, not the average — if hierarchy is 4 but execution is 2, the overall score is 2. Innovation is allowed to be low; restraint is allowed to be high.
Dimension
What it grades
1 — Broken
3 — Functional
5 — Exceptional
Philosophy
Does the UI have a coherent point of view?
No identity; could be any product
Recognizable category but generic
Unmistakable identity, every choice supports it
Hierarchy
Can the user's eye find the important thing first?
Equal weight everywhere; nothing reads as primary
One clear focal point per screen
Multiple ranks of attention, all working
Execution
Is the typography, spacing, alignment, color tight?
Are the choices grounded in this product, or generic SaaS defaults?
Could lift any dashboard skeleton from the internet
Some product-specific decisions
Almost every choice is specific to this product's voice
Restraint
What's been left out? Does anything feel "added because we could"?
Maximalist — every section uses every feature
Some restraint visible
Aggressive editing — most pages remove things rather than add
Record per-dimension scores (1-5) plus one-line evidence per dimension. Compute the floor score (worst band) and the average, both for the report. Any dimension scoring 1 or 2 is a regression that must be addressed before PASS — fix the weakest first, re-screenshot, re-score.
Produce audit report:
docs/plans/YYYY-MM-DD-ui-review-<phase>.md
Report structure:
# UI Review: Phase N.M — <Name>**Date:** YYYY-MM-DD
**Contract:**`docs/plans/YYYY-MM-DD-<phase>-ui-contract.md`**Verdict:** PASS | PARTIAL | FAIL
## Screenshots
(Embedded regression-test screenshots at each viewport)
## Contract Adherence
| Criterion | Status | Notes |
|---|---|---|
| Design system colors | ✅ Pass | — |
| Typography | ⚠️ Partial | H2 uses 20px, contract specifies 24px |
| Component coverage | ✅ Pass | All 4 contracted components present |
| Layout — desktop | ✅ Pass | Matches contract structure |
| Layout — tablet | ❌ Missing | Sidebar not collapsing at 768px |
| Layout — mobile | ✅ Pass | Single column, stacked correctly |
| Loading states | ✅ Pass | Skeleton implemented |
| Empty states | ⚠️ Partial | Missing CTA in empty state |
| Error states | ✅ Pass | Error banner with retry present |
| ARIA roles | ❌ Missing | nav and main roles not applied |
| Keyboard navigation | ✅ Pass | Tab order correct |
## Anti-Slop Scan
| # | Pattern | Status | Evidence |
|---|---|---|---|
| 1 | Purple/violet gradient default | ✅ Pass | — |
| 2 | Generic emoji feature icons | ❌ Fail | Feature row uses 🚀 ⚡ 🎯 — replace with custom icons or remove |
| 3 | Card with coloured left border | ✅ Pass | — |
| 4 | Hand-drawn SVG humans | ✅ Pass | — |
| 5 | Inter as display face | ✅ Pass | Display is Söhne |
| 6 | Invented metrics without citation | ⚠️ Fail | "10× faster" on hero — no source |
| 7 | Filler copy in production | ✅ Pass | — |
| 8 | Icon next to every heading | ✅ Pass | 30% of headings, below threshold |
| 9 | Gradient on every full-width bg | ✅ Pass | One hero gradient, rest flat |
## 5-Dimension Critique
| Dimension | Score (1-5) | Evidence |
|---|---|---|
| Philosophy | 4 | Clear "minimal observability" point of view in monochrome + signal green |
| Hierarchy | 3 | One focal point per screen but secondary rank flat |
| Execution | 4 | Clean alignment, consistent spacing rhythm |
| Specificity | 2 | Most components are generic SaaS skeletons; could be any dashboard |
| Restraint | 4 | Good — no decorative chrome |
| **Floor** | **2** | Specificity is the weakest |
| **Average** | **3.4** | — |
## Issues (prioritized)1. ❌ Tablet sidebar not collapsing — Major (contract)
2. ❌ ARIA roles missing on nav/main — Major (contract)
3. ❌ Generic emoji icons in feature row — Major (anti-slop #2)
4. ❌ Specificity score 2/5 — Major (critique floor)
5. ⚠️ Invented "10× faster" metric without source — Minor (anti-slop #6)
6. ⚠️ H2 font size 20px vs contracted 24px — Minor (contract)
7. ⚠️ Empty state missing CTA — Minor (contract)
## Verdict Rationale
FAIL — 2 missing contract criteria + 1 anti-slop fail + critique floor of 2 (Specificity). Anti-slop and critique-floor are hard floors regardless of contract adherence.
Verdict logic:
The verdict is the worst of the three sub-verdicts:
Sub-verdict
PASS
PARTIAL
FAIL
Contract adherence
No ❌ Missing
Only ⚠️ Partial
Any ❌ Missing
Anti-slop
All 9 patterns Pass
n/a
Any pattern Fail
5-dimension critique
Floor ≥ 3 and average ≥ 3.5
Floor = 3, average ≥ 3
Floor ≤ 2
Final verdict: take the worst of the three. If any sub-verdict is FAIL, the report is FAIL — fix the weakest before claiming PASS.
Announce verdict in conversation with issue count, anti-slop fails, critique floor, and top issues.
Red Flags
Skipping ui-phase "because it's simple" — Even simple UIs benefit from a contract. The contract is what makes ui-review possible.
Writing the ui-contract after implementation — The contract is a design input, not a documentation artifact. It must exist before implementation.
ui-review without screenshots — Screenshots are the primary evidence. Do not produce a review report without invoking regression-test first.
Grading against intent rather than contract — ui-review grades against the written contract. If the implementation looks good but deviates from the contract, that is a deviation — update the contract or fix the implementation.
Calling ui-review PASS when criteria are Missing — Missing is always a failing criterion. Partial deviations may be acceptable. Missing implementations never are.
Common Rationalizations
Rationalization
Why It's Wrong
Correct Action
"The design is clear in my head, no contract needed"
What's clear in the designer's head is not clear to the implementer
Write the contract
"Screenshots at one viewport are enough"
Responsive breakpoints are the most common source of layout bugs
Screenshot at all three viewports
"The implementation looks good enough"
"Good enough" is not the contract
Grade against the written contract
"I'll update the contract to match what was built"
The contract is a design input. If it needs changing, change it before implementation, not after
Fix the implementation or formally revise the contract with user approval
"Anti-slop is subjective, skip it"
The 9 patterns are concrete and gradeable. Skipping them is how generic-AI-dashboard slop ships
Run the scan; each pattern is binary Pass/Fail with one-line evidence
"The contract was met, the critique is overkill"
Contract match doesn't guarantee good design — generic implementations honor minimal contracts
Run both. They catch different failure modes.
"Average score is 3.5, that's a pass"
Average hides the worst dimension. A 5/1/5/5/2 averages to 3.6 but two dimensions are broken
Use the floor score, not the average. Fix the worst before accepting PASS.
"Innovation is low, downgrade Philosophy"
Innovation is allowed to be low; Philosophy grades coherence, not novelty
A boring product with strong identity scores 5 on Philosophy. Don't conflate.
