plan-uiux-unificationPlan-only UI/UX and design-system audit that emits a unification burndown; no code until a phase is approved. Use when "audit UI without fixing", "UI burndown", or "IA audit before redesign". Apply now → housekeep-design.
Independent GitHub snapshot · Automated classification · Original documentation governs
Degree of freedom: MIXED — IA and unification plan are judgment; token greps and inventory globs run exactly. Stay plan-only. No UI edits until approved.
Role: Senior frontend/mobile architect + design-systems engineer.
Task: Deep, exhaustive, non-destructive audit. Built by many devs over time → expect inconsistent design system, layout, typography, and repo rules. Find every violation, document it, produce a burndown + enhancement plan. Enhance the existing design system; do not replace it, strip features, fabricate data, or rewrite UI in this pass.
| Skill | Does |
|---|---|
| plan-uiux-unification (this) | Plan only — full inventory, burndown, roadmap; no fixes |
audit-responsive | Linearized desktop / breakpoint IA — audit then fix |
audit-uiux-design-system | Visual/token/component audit; may recommend or fix |
audit-ux | Heuristics, flows, microcopy quality |
enhance-web-ui / enhance-web-ux | Implement visual/UX improvements |
design-system | Build or extend the design system itself |
Chain: Step 1 of six-skill plan loop — see docs/PLAN-LOOPS.md
Execute: audit-responsive (layout/IA) → enhance-web-ux / enhance-web-ui → test-playwright
Propose: replace raw
#1a1a1aon/pricingCTA with the documented primary token (bg-fgor equivalent). Risk: 14 hex literals on the highest-traffic page; brand-breaking vs the token SSOT. Keep-working:components/ui/Buttonalready uses semantic tokens. Phase: P0 — brand-breaking hex on a conversion surface. Canonical fix: value-for-value token swap; no copy or layout rewrite.
Read references/preservation-contract.md in full before Phase 0.
Acknowledge in output #1 — restate what you will NOT do:
0. Context & IA (before any layout talk)
1. Design-system ground truth
2. Full surface inventory
3. Per-surface deep audit
4. Burndown (prioritized + risk)
5. Unification & enhancement plan
6. Best-practice research (cite current year)
Detailed instructions: references/phase-workbook.md
Templates: references/output-templates.md
Before pixels: user goal, primary task, key action, IA map (primary/secondary/tertiary), content relationships, progressive disclosure.
Core anti-pattern to flag: flat vertical stacks + left-align + no hierarchy/grouping.
Only then propose layout using real content from the codebase — never invented examples.
Auto-detect (read actual files): [LOW freedom — run exactly]
Glob: **/tailwind.config.*
Glob: **/globals.css **/tokens.* **/theme.*
Glob: **/components/ui/**
Grep: "STYLEGUIDE|CONTRIBUTING" glob "**/*.md"
Critique: enhance (missing semantic tokens, thin scales) vs enforce (violations of existing rules). Multiple systems → name canonical vs legacy + collision points.
Output short design-system spec (current state + proposed enhancements).
Exhaustive checklist table — every route, modal, drawer, toast, empty/loading/error state, auth/onboarding, responsive + dark per surface. Mark audited only after Phase 3 review.
Delegate an inventory pass to a subagent only when it is sizeable, independent of the others, and its raw output (glob lists, token-grep counts) has no place in the plan; brief it with the exact commands and the columns to return. It edits nothing, like this pass. Long sweeps are expected — context compaction exists, so finish the inventory rather than wrapping up early.
See inventory template in references/output-templates.md.
For each surface, log violations by category:
Three buckets: violates documented rule · subjective improvement · needs DS enhancement
Token sweep (quantify for burndown): [LOW freedom — run exactly]
Grep: "#[0-9a-fA-F]{3,8}" glob "*.{tsx,jsx,vue,css}"
Grep: "style=\\{" glob "*.{tsx,jsx}" output_mode "count"
Grep: "className=.*\\b(p|m|gap|text|rounded)-\\[" glob "*.{tsx,jsx}" output_mode "count"
Optional visual verification: read protocol-browser-anti-stall and
references/playwright-session-coordination.md in that skill before playwright-cli.
Plan-only — screenshots for evidence, not fixes.
Table columns:
Surface | Violation | Category | Severity (P0–P3) | Effort (S/M/L) | Risk (Low/Med/High) | Canonical fix | File path(s)
P0 = broken/inaccessible/brand-breaking · P3 = cosmetic. Quantify where possible.
Firecrawl / web for current year best practices — search each named standard as written rather than answering from memory; cite sources:
Note where this app diverges from research.
audit-responsive; apply-now token cleanup → housekeep-design; per-page heuristics → audit-ux[NEEDS REAL CONTENT] stays open; never fabricate examples to fill IA[NEEDS REAL CONTENT] listDeliver as a single markdown doc (or canvas for large repos), then end the turn with a standalone recap in chat: the two or three highest-impact violations and the first phase to approve. The document is the deliverable — write it before the recap. Do not open PRs or edit UI code unless the user explicitly approves execution in a follow-up.
| MCP | Use |
|---|---|
| Firecrawl | Phase 6 research, anti-AI-slop patterns, WCAG/token governance |
| Playwright browser | Optional Phase 3 visual evidence; own named session (-s=…) per protocol-browser-anti-stall |
| Context7 | Component library / Tailwind docs when naming canonical primitives |
| Sequential Thinking | Not needed — the IA map and collision analysis go in the deliverable |