---
name: plan-uiux-unification
description: >
  Non-destructive UI/UX and design-system audit that emits a unification
  burndown — no code until each phase is approved. Use when "audit UI without
  fixing", "UI burndown", or "IA audit before redesign". Apply-now token cleanup
  → housekeep-design. Per-page heuristics → audit-ux.
license: MIT
---

# UI/UX & Design-System Audit + Unification Plan

**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.**

## This skill vs neighbors

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

## How to reason (every plan item)

1. **Propose** — token, primitive, layout, or voice change against the existing DS
2. **Risk** — brand-break, a11y fail, or a rewrite that strips a feature
3. **Keep-working** — surfaces and tokens that already match the canonical system
4. **Phase** — P0 broken/a11y → structural → polish (do not execute)

## Worked example

> **Propose:** replace raw `#1a1a1a` on `/pricing` CTA with the documented primary token (`bg-fg` or equivalent).
> **Risk:** 14 hex literals on the highest-traffic page; brand-breaking vs the token SSOT.
> **Keep-working:** `components/ui/Button` already uses semantic tokens.
> **Phase:** P0 — brand-breaking hex on a conversion surface.
> **Canonical fix:** value-for-value token swap; no copy or layout rewrite.

---

## ⛔ Preservation Contract

Read `references/preservation-contract.md` in full before Phase 0.

**Acknowledge in output #1** — restate what you will NOT do:

- No feature/route/screen/state/prop/handler removal
- No fabricated data, content, copy, or API fields
- Every codebase claim cites a file path you read
- Preserve I/O boundaries + business logic unless explicitly proposed + approved
- No silent breaking changes to public APIs, props, or routes
- This pass **plans**; visual/UX changes are proposals only

---

## Phase flow (do not skip)  [HIGH freedom]

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

---

## Phase 0 — Context & IA FIRST  [HIGH freedom]

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.

---

## Phase 1 — Design-system ground truth  [HIGH freedom]

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).

---

## Phase 2 — Surface inventory  [HIGH freedom]

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.

See inventory template in `references/output-templates.md`.

---

## Phase 3 — Per-surface audit  [HIGH freedom]

For each surface, log violations by category:

- IA & hierarchy · Tokens · Typography · Layout/spacing
- Content & tone (rewrites preserve meaning)
- AI-generic aesthetic tells
- Components (duplicates → consolidation *proposals*)
- Interaction/states · Accessibility (WCAG 2.2)
- Conflicting/deprecated systems · Tech debt (removal needs confirmation)

**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.

---

## Phase 4 — Burndown  [HIGH freedom — plan only]

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.

---

## Phase 5 — Unification plan  [HIGH freedom — plan only]

- Consolidate DS conflicts; deprecate loser + migration path
- High-traffic layouts driven by Phase 0 IA + real content
- Content/voice guideline (tone, errors, CTAs, jargon glossary)
- Token migration / codemod strategy (value-for-value)
- Primitive consolidation as proposals with dependency checks
- Guardrails: lint rules, no raw hex, visual regression, PR checklist
- Phased roadmap: quick wins → structural → polish (each revertible)

---

## Phase 6 — Research  [HIGH freedom]

Firecrawl / web for **current year** best practices; cite sources:

- Token architecture (semantic/layered, W3C DTCG)
- IA + visual hierarchy · UX writing · anti-AI-slop aesthetics · WCAG 2.2

Note where this app diverges from research.

## Self-critique before the burndown  [LOW freedom — do not skip]

1. **evidenced-not-assumed** — every violation cites a path you read; no invented copy
2. **plan-only** — no UI/token edits, no PRs
3. **severity/phase justified** — P0 is broken/inaccessible/brand-breaking, not taste
4. **right-owner** — linearized breakpoint IA → `audit-responsive`; apply-now token cleanup → `housekeep-design`; per-page heuristics → `audit-ux`
5. **no-false-safety** — `[NEEDS REAL CONTENT]` stays open; never fabricate examples to fill IA

---

## Required output (in order)

1. Preservation-contract acknowledgment
2. Context & IA summary (per area)
3. Design-system spec (current + enhancements)
4. Surface inventory checklist
5. Per-surface violation log
6. Burndown table (with risk column)
7. Unification + enhancement plan + phased roadmap (+ content/voice guide)
8. Guardrails / tooling recommendations
9. Research notes + citations
10. Open questions / `[NEEDS REAL CONTENT]` list

Deliver as a single markdown doc (or canvas for large repos). **Do not open PRs or edit UI code**
unless the user explicitly approves execution in a follow-up.

---

## Rules

- **Plan only — do not fix yet.** User approves before execution.
- **IA before layout. Hierarchy first, pixels second.**
- **Enhance, don't replace.** Preserve every feature + all real content/data.
- **Never fabricate.** Cite real paths/lines. Unverifiable → say so.
- Surface unreachable or token source missing → say so, don't guess.
- Before proposing any file change: one line on what must keep working there.

---

## MCP integration

| 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 | Complex IA maps or multi-system collision analysis |