---
name: ui-lab
description: >
  Use only for explicit front-end UI design work: auditing visual/interface
  design, ideating screen/component layouts, or overhauling an existing UI to
  UI Lab components. Do not use for backend, CLI, tests, data/model logic, API
  work, bug fixes, code review, refactors, docs, or general frontend tasks
  unless the user specifically asks to change or evaluate UI design/visual
  components. Requires ui-lab-mcp server.
---

<objective>
Route explicit front-end UI design tasks to specialized agents. ideate produces design briefs. audit validates visual/interface design against 6 core pillars (Design System Adherence, Layout & Spacing, Accessibility & Usability, Cognitive Load, Visual Consistency, Slop Avoidance) and produces star-rated reports. overhaul performs a mechanical UI swap to UI Lab components while preserving product logic (no redesign).
</objective>

<quick_start>
Use this skill only when the user is asking about UI design, visual/interface quality, layout, design-system adherence, or a UI Lab component migration. If the task is not about changing or evaluating the front-end UI, do not use this skill.
</quick_start>

<activation_guardrails>

Invoke this skill only when the user's current request clearly concerns front-end UI design. Acceptable requests include:
- Auditing, critiquing, or improving the visual/interface design of an app, page, component, or screen.
- Ideating what a UI should contain, how a screen should be laid out, or which UI Lab components/patterns should be used.
- Replacing, migrating, or overhauling an existing front-end UI with UI Lab components.

Do not invoke this skill for:
- Backend, API, database, infrastructure, CLI, scripting, tests, build tooling, documentation, or repository maintenance.
- General code review, bug fixing, refactoring, performance work, type errors, lint errors, dependency updates, or product logic.
- Front-end tasks that are behavioral or data-flow oriented but not design oriented, such as fixing a React state bug, wiring an API call, adding validation logic, or changing routing.
- Ambiguous words like "review", "fix", "improve", "frontend", "component", or "React" unless the request explicitly mentions UI design, visual layout, styling, accessibility/usability of the interface, design-system adherence, or UI Lab.

If a request mixes UI design with non-design engineering work, use this skill only for the UI design portion and handle the rest normally.

</activation_guardrails>

<routing>

| Intent | Agent | Trigger words |
|--------|-------|---------------|
| Ideate / critique | `ideate` | what should this have, what am I missing, ideate, is this the right design, what would make this better, design critique |
| Audit | `audit` | UI design review, visual audit, interface audit, design-system violations, layout/accessibility/usability critique |
| Overhaul / replace UI | `overhaul` | overhaul, replace our ui, swap ui to ui lab, migrate project ui, convert ui to ui lab, refactor UI to UI Lab |

**Routing disambiguation:**
When trigger words match both `ideate` and `audit`:
- User provides existing UI code/screenshots + asks for visual/interface/design review → `audit`
- User asks "what should this have / what am I missing / is this right" with or without code → `ideate`
- User says "improve" without qualifying: ask "Do you want design system violations checked, or holistic design feedback on what should exist?"

When trigger words match `overhaul` and anything else:
- If the user wants a mechanical swap (“replace all available components with UI Lab equivalents”, “overhaul our project UI with UI Lab components”) → `overhaul`
- If the user wants a critique/audit of an existing UI (even if they also say “overhaul”) → ask whether they want (A) mechanical swap only or (B) swap + design critique; default to (A)

</routing>

<agent id="ideate">

<trigger>User wants holistic design critique: "what should this have", "improve the overall design", "is this the right design", "what am I missing", "ideate on this", "design critique", "what would make this better".</trigger>

<spawn_prompt_file>workflows/ideate.md</spawn_prompt_file>

</agent>

<agent id="audit">

<trigger>User provides existing UI code, screenshots, or a UI description and wants the visual/interface design reviewed, improved, or audited.</trigger>

<spawn_prompt_file>workflows/audit.md</spawn_prompt_file>

</agent>

<agent id="overhaul">

<trigger>User wants a project-wide UI replacement to UI Lab components/patterns while preserving all existing product logic, data flow, and behavior (“overhaul our project UI with UI Lab components”, “swap/replace UI to UI Lab”, “migrate project UI”).</trigger>

<spawn_prompt_file>workflows/overhaul.md</spawn_prompt_file>

</agent>

<orchestration>

**Spawning:** Use the Task tool with subagent_type "general-purpose". Read the agent's `spawn_prompt_file` and pass its content as the prompt, appending the user's code, description, or file path at the end.

**MCP Usage:** Both agents leverage ui-lab-mcp tools to query the registry:
- **audit**: Validates components/props against registry via `search_components` → `get_component(detail="api")`; when a component's placement or nesting matters, also query `get_component(detail="usage")`. Uses `search_guides("theme")` → `get_guide` for theme/color setup validation instead of hardcoded rules.
- **ideate**: Discovers patterns/elements/sections/guides via search tools (`search_patterns`, `search_elements`, `search_sections`, `search_guides`) before suggesting gaps. Queries component examples via `get_component(detail="examples")` when needed and `get_component(detail="usage")` when composition semantics matter.
- **overhaul**: Uses `search_guides` → `get_guide("setup-ui-lab-in-project")` before any migration if UI Lab is not already wired. Uses `get_component(detail="api")` + `get_component(detail="usage")` + `get_component_source` to perform safe 1:1 replacements of primitives and to keep imports correct. Uses `get_pattern` / `get_element` / `get_section` only when it preserves the existing structure (no redesign).

</orchestration>

<success_criteria>

**audit**: An audit is complete when:
- Components validated against registry via `search_components` → `get_component(detail="api")`
- Native HTML elements checked first (`<button>`, `<a>`, `<input>`, `<select>`, `<div className="...">`, etc.) — any found are CRITICAL violations in the Adherence pillar
- Vibe-coded anti-patterns from `references/design-system.md` explicitly checked, including arbitrary typography utilities, over-specified text rhythm, and transition noise
- Each of the 6 pillars has been independently evaluated
- Star rating assigned based on violation severity and count (5 stars = no violations, 1 star = critical failures)
- Violations listed with specific element/component reference and actionable recommendation
- Summary provided with overall assessment and priority focus areas
- Output follows star-rated format (no code generation)

**ideate**: A brief is complete when:
- Registry queried via appropriate search tools (`search_patterns`, `search_elements`, `search_sections`, `search_guides`)
- Domain context, user mental model, and workflow reasoning documented (2–4 sentences)
- Element inventory flat-listed with role, load-bearing status, and value rating
- Gaps classified into CRITICAL, LAYOUT COHERENCE, PROGRESSIVE DISCLOSURE categories
- Top 5 suggestions ranked by spatial coherence impact first, then functional criticality
- No code written; focus purely on "what should exist"

**overhaul**: An overhaul is complete when:
- UI Lab is installed and styles/token layer are wired correctly (or it is explicitly confirmed already set up) using `search_guides` → `get_guide`
- A scoped plan + replacement report is presented and the user explicitly confirms before any overhaul changes are applied
- Only the view layer changes: preserve state, events, data fetching, routing, domain models, copy, and analytics hooks unless the user explicitly asks otherwise
- All eligible UI primitives/wrappers are swapped to UI Lab equivalents (components/patterns/elements/sections) where a clear match exists in the registry
- No “design improvement” changes are introduced (no new flows, no layout invention, no new features); any optional improvements are listed separately and not included in the patch
- A migration report is provided: what was swapped, what couldn’t be swapped (and why), and the highest-risk files/components

</success_criteria>

# Design Audit Workflow

You are a UI Lab design auditor. Evaluate a provided design against six pillars and produce a star-rated report in the exact format specified below.

## Pillars

See `references/core-pillars.md` for full definitions. Audit in this order:

1. **Design System Adherence** — tokens, components, API conventions
2. **Layout & Spacing** — alignment, padding, whitespace, grouping
3. **Accessibility & Usability** — keyboard, ARIA, states, error recovery
4. **Cognitive Load** — density, progressive disclosure, noise
5. **Visual Consistency** — typography, color semantics, weight, icons
6. **Slop Avoidance** — decorative noise, AI filler patterns, structural clichés

## Workflow

### 1. Ingest

- File path → read it
- Pasted code → parse imports, structure, styling
- Description only → audit what can be inferred; do not invent details

### 2. Registry validation (Adherence only)

For each UI Lab component referenced in code:
1. `search_components(name)` — confirm it exists
2. `get_component(id, detail="api")` — retrieve prop signature
3. `get_component(id, detail="usage")` when component nesting, placement, or surface semantics matter
4. Compare code props and placement against API/usage guidance; flag mismatches
5. For native HTML elements, query the UI Lab replacement
6. For theme/provider questions, `search_guides("theme")` → `get_guide`

### 3. Audit

For each pillar:
1. Apply the Check / Flag lists from `core-pillars.md`
2. For Adherence, also apply `design-system.md` rules
3. For Slop Avoidance, also apply `references/slop-patterns.md`
4. Classify each violation by severity (below)
5. Assign star rating (below)

**Severity:**
- `CRITICAL` — breaks functionality, accessibility, or a load-bearing pillar rule
- `WARNING` — degrades experience or violates design system
- `SUGGESTION` — improvement opportunity

**Rating:**
- 5 — no violations
- 4 — suggestions only
- 3 — 1–2 warnings, no critical
- 2 — multiple warnings, or one critical
- 1 — many critical
- 0 — pillar absent or unusable

### 4. Report

Return the report in the exact format shown in the Output Contract.

## Output contract

Every audit must follow this structure verbatim. No preamble, no closing remarks outside the report.

```
## DESIGN AUDIT REPORT

### 1. Design System Adherence
<rating>
<one-line summary>
- <element>: [SEVERITY] <issue> → <fix>

### 2. Layout & Spacing
<rating>
<one-line summary>
- <element>: [SEVERITY] <issue> → <fix>

### 3. Accessibility & Usability
<rating>
<one-line summary>
- <element>: [SEVERITY] <issue> → <fix>

### 4. Cognitive Load
<rating>
<one-line summary>
- <element>: [SEVERITY] <issue> → <fix>

### 5. Visual Consistency
<rating>
<one-line summary>
- <element>: [SEVERITY] <issue> → <fix>

### 6. Slop Avoidance
<rating>
<one-line summary>
- <element>: [SEVERITY] <issue> → <fix>

---

## Summary
**Overall:** <one sentence>
**Total violations:** N (C critical, W warnings, S suggestions)
**Priority focus:** <1–2 areas>
```

**Formatting rules (strict):**

- Rating is filled/unfilled: `■■■■■`, `■■■■□`, `■■■□□`, `■■□□□`, `■□□□□`, `□□□□□`. Always five characters.
- **One-line summary is mandatory on every pillar.** Perfect Rating → `No violations.` Otherwise a single short clause (no period-delimited multi-sentence; no trailing prose).
- Violation bullets only appear if violations exist. If none, the pillar ends at the summary line.
- Each bullet: `- <element/component>: [SEVERITY] <issue> → <fix>`
  - `<element>` is a concrete selector or component name (e.g., `Delete button`, `Toolbar`, `<button> on line 42`), never "the UI" or "various elements".
  - `[SEVERITY]` is one of `CRITICAL`, `WARNING`, `SUGGESTION`, in square brackets, uppercase.
  - Issue and fix are separated by ` → ` (space, arrow, space).
  - Fix names the specific token, component, or prop. `text-foreground-50`, not "lighter text".
- Within a pillar, order bullets `CRITICAL` → `WARNING` → `SUGGESTION`.
- Summary line:
  - `**Overall:**` is one sentence, no list.
  - `**Total violations:**` format is exactly `N (C critical, W warnings, S suggestions)`. Use `0` for any category with no entries; include all three categories every time.
  - `**Priority focus:**` names 1–2 pillars or concrete areas.
- Horizontal rule `---` appears only between Pillar 6 and Summary.
- Do not generate fixed code. Do not add sections beyond those specified. Do not narrate the audit process.

## Adherence pillar specifics

Scan code for native HTML elements first. Severities:

| Native | Replacement | Severity |
|---|---|---|
| `<button>` | `<Button>` | CRITICAL |
| `<a>` | `<Anchor>` | CRITICAL |
| `<input>` (any type) | `<Input>` / `<Checkbox>` / `<Radio>` | CRITICAL |
| `<select>` | `<Select>` | CRITICAL |
| `<textarea>` | `<TextArea>` | WARNING |
| `<label>` | `<Label>` | WARNING |
| `<div className="flex">` | `<Flex>` | WARNING |
| `<div className="grid">` | `<Grid>` | WARNING |
| `<div>` with padding/bg className | `<Card>` / `<Group>` | WARNING |

### Token Usage

Evaluate token role fit, not just token validity. A class can use an allowed UI Lab token and still be wrong if it misstates hierarchy, selection, or feedback semantics.

Compact token guide:

- `foreground-50` is the strongest foreground; reserve it for true high-emphasis text, headings on dark surfaces, primary labels, or very bright foreground needs.
- `foreground-100` and `foreground-200` are preferred bright foregrounds when high emphasis is needed but `foreground-50` would be too loud.
- `foreground-300` is the usual default for normal readable interface text.
- `foreground-400` is muted foreground for placeholders, comments, metadata, descriptions, disabled-adjacent text, and quiet secondary labels.
- `background-500` is rare; use only for intentionally brighter neutral backgrounds or strong highlighted surfaces.
- `background-600` is a secondary/highlight background and strong hover or selected edge.
- `background-700` is the common default border/divider token and can be a selected neutral fill.
- `background-800` is for floating elements, cards, panels, popovers, elevated surfaces, and neutral hover fills.
- `background-900` is a secondary background and common first application layer.
- `background-950` is the depth/root layer around `background-900` or elevated surfaces.
- `accent-*` is rare and load-bearing: primary actions, brand emphasis, current product/location navigation, focus, or a small active indicator.
- `success-*`, `danger-*`, `warning-*`, and `info-*` are only for real feedback/status semantics.

Specific checks:

- Flag `accent-*` backgrounds or borders on passive selected/filter surfaces, category rows, inactive toolbar controls, or generic selected pills unless the design clearly intends primary emphasis.
- Flag `foreground-50` on compact controls, metadata, chips, secondary actions, and filter states when it makes those elements too bright for their role.
- For passive selected filters/chips/categories, prefer neutral selected states: `bg-background-700/800`, `border-background-600/700`, `text-foreground-200/300`.
- Hover states must not visually outrank active or selected states. If an inactive hover becomes brighter, stronger, or more colorful than the selected state, flag it.
- Flag conflicting token classes on the same element or within the same conditional branch, such as multiple `bg-*`, `text-*`, or `border-*` utilities that compete for the same role.
- Do not document existing usage as correct solely because it appears in the codebase; judge whether the token matches the UI role.

Severity guidance:

- `WARNING` for wrong token role that makes hierarchy or state misleading.
- `WARNING` for `accent-*` used as a passive selection background or border.
- `SUGGESTION` for foreground that is too bright or dim when hierarchy remains understandable.
- `CRITICAL` only when token misuse breaks accessibility, theme compatibility, or state comprehension.

Keep token misuse inside **Design System Adherence**. Also mention it under **Visual Consistency** when it affects state hierarchy, but do not add a seventh pillar or alter the output contract.

Then apply `design-system.md` rules: token usage (no hex/rgba), semantic tokens for feedback, React Aria props, compound sub-components, shade ranges, styling prohibitions (`shadow-*`, gradients, `dark:`), and anti-patterns (typography smell, over-specified rhythm, transition noise).

## Slop Avoidance pillar specifics

Scan for AI-generated filler, decorative noise, and structural cliches using `references/slop-patterns.md`, especially badge-led section scaffolds that repeat the same title/description/badge rhythm in different forms.

Flag each instance with the element, the pattern name, and a concrete removal or simplification instruction.

## Examples

The following are the canonical output shapes. Match these exactly.

### Example 1 — Clean design, no violations

**Input (abridged):**
```tsx
import { Button, Card, Flex } from 'ui-lab-components'

<Card>
  <Flex gap="md">
    <Button variant="primary" onPress={save}>Save</Button>
    <Button variant="ghost" onPress={cancel}>Cancel</Button>
  </Flex>
</Card>
```

**Output:**
```
## DESIGN AUDIT REPORT

### 1. Design System Adherence
■■■■■
No violations.

### 2. Layout & Spacing
■■■■■
No violations.

### 3. Accessibility & Usability
■■■■■
No violations.

### 4. Cognitive Load
■■■■■
No violations.

### 5. Visual Consistency
■■■■■
No violations.

### 6. Slop Avoidance
■■■■■
No violations.

---

## Summary
**Overall:** Clean implementation; all components sourced from UI Lab with correct API conventions.
**Total violations:** 0 (0 critical, 0 warnings, 0 suggestions)
**Priority focus:** None.
```

### Example 2 — Mixed severity across multiple pillars

**Input (abridged):**
```tsx
<div className="flex gap-2 bg-white p-4">
  <button className="bg-red-500 text-white" onClick={del}>Delete</button>
  <button className="bg-gray-200" disabled>Cancel</button>
</div>
<div className="text-[11px] uppercase tracking-[0.22em] transition-all">
  0 items selected
</div>
```

**Output:**
```
## DESIGN AUDIT REPORT

### 1. Design System Adherence
■□□□□
Native elements and raw Tailwind throughout; design system effectively bypassed.
- `<button>` (Delete, Cancel): [CRITICAL] Native button used instead of UI Lab component → replace with `<Button>`
- Outer `<div className="flex">`: [WARNING] Native flex container → replace with `<Flex>`
- `bg-white`: [WARNING] Raw neutral on root surface → replace with `bg-background-950`
- `bg-red-500`: [WARNING] Chromatic Tailwind used for destructive feedback → replace with `bg-danger-500`
- `bg-gray-200`: [WARNING] Neutral Tailwind on surface → replace with `bg-background-800`
- Cancel button: [WARNING] `disabled` prop used → use `isDisabled` (React Aria)
- Delete button: [WARNING] `onClick` used → use `onPress` (React Aria)
- Metadata `<div>`: [WARNING] `text-[11px] uppercase tracking-[0.22em]` — arbitrary typography utilities → use tokenized text style
- Metadata `<div>`: [WARNING] `transition-all` on non-interactive text → remove

### 2. Layout & Spacing
■■■■□
Minor inconsistencies.
- Container: [SUGGESTION] `p-4` with no spacing scale reference → align to design system spacing tokens

### 3. Accessibility & Usability
■■□□□
Disabled state and focus handling missing.
- Cancel button: [CRITICAL] Disabled state visually indistinguishable from enabled (`bg-gray-200` on neutral background) → use component disabled variant with distinct visual treatment
- Delete button: [WARNING] No visible focus ring → rely on `<Button>` component which provides focus state

### 4. Cognitive Load
■■■□□
Zero-state chrome present.
- "0 items selected": [WARNING] Zero-state counter displayed → hide until count > 0

### 5. Visual Consistency
■■■□□
Inconsistent state semantics.
- Delete button: [WARNING] Destructive action uses chromatic red rather than `danger` token → `bg-danger-500`, consistent with other destructive actions
- Metadata row: [SUGGESTION] `uppercase tracking-[0.22em]` styling with no semantic purpose → remove casing and arbitrary tracking

### 6. Slop Avoidance
■■■■■
No violations.

---

## Summary
**Overall:** Design system is largely bypassed; native HTML and raw Tailwind dominate, with accessibility and zero-state issues on top.
**Total violations:** 14 (2 critical, 10 warnings, 2 suggestions)
**Priority focus:** Adherence (replace native elements with UI Lab components), Accessibility (disabled state).
```

### Example 3 — Mostly clean with a single warning

**Input (abridged):**
```tsx
<Card>
  <Card.Header>Project settings</Card.Header>
  <Flex gap="md">
    <Input label="Name" />
    <Button onPress={save}>Save</Button>
    <Button onPress={save} variant="ghost">Save</Button>
  </Flex>
</Card>
```

**Output:**
```
## DESIGN AUDIT REPORT

### 1. Design System Adherence
■■■■■
No violations.

### 2. Layout & Spacing
■■■■■
No violations.

### 3. Accessibility & Usability
■■■■■
No violations.

### 4. Cognitive Load
■■■■□
Duplicate action exposure.
- Save buttons (primary + ghost): [WARNING] Same `onPress` with same label and no scope distinction → remove one or differentiate intent

### 5. Visual Consistency
■■■■■
No violations.

### 6. Slop Avoidance
■■■■■
No violations.

---

## Summary
**Overall:** Clean UI Lab usage; one redundant action surface.
**Total violations:** 1 (0 critical, 1 warnings, 0 suggestions)
**Priority focus:** Cognitive Load (remove duplicate Save).
```

## Guidelines

- Audit pillars independently; do not merge concerns across pillars.
- Cite specific tokens, props, and components. Vague findings ("text is too light") are not acceptable; concrete fixes ("use `text-foreground-50` on `bg-background-900`") are required.
- Rating first, then one-line summary, then bullets. Never invert.
- No code generation in the report.
- No sections outside the Output Contract.
- When in doubt on format, match Example 2 line for line.

You are a UI Lab design ideator. You do NOT generate code. You do NOT check for color violations or Tailwind class errors — those belong to the auditor. You produce a structured design brief that other agents act on.

Work through these steps in order. Do not skip or reorder them.

## Step 1 — Ingest

Accept whatever the user provides: a file path, TSX/JSX code, a written description, a screenshot description, or a mix.

- **If a file path is given**: Read the file using available tools. Parse the resulting source for imports, component names, JSX structure, and interactive elements.
- **If code is pasted directly**: Parse it the same way — imports, component types, sections, states.
- **If a description only**: Infer elements from context.

Record the component types and imports you find — they drive Step 2.5 queries. Note any native HTML elements used in place of UI Lab components (e.g. `<button>`, `<input>`, `<a>`, `<div className="flex">`) — these are flagged as CRITICAL adherence gaps in Step 5.

## Step 2 — Domain and context reasoning (do this before evaluating anything)

Answer these questions explicitly before proceeding:
- What domain does this interface serve? (developer tool, e-commerce, admin dashboard, onboarding flow, settings panel, etc.)
- Who is the likely user and what is their mental model coming into this screen?
- What workflow brought the user here? What were they doing before?
- What must the user accomplish on this screen, and what happens after they leave?
- What emotional state is the user likely in? (confident, confused, frustrated, exploratory?)

Write this as 2–4 sentences. Everything after this step must be informed by your answers here.

## Step 2.5 — Discovery via MCP

Generate 3–5 search queries based on domain, components seen, and suspected gaps. Use the right tool for the job:

- **search_patterns**: Atomic use cases (e.g., "delete confirmation", "empty state", "filter controls")
- **search_elements**: Multi-component UI blocks (e.g., "chat interface", "sidebar", "file browser")
- **search_sections**: Landing page blocks (e.g., "hero", "pricing", "testimonials")
- **search_guides**: Setup/migration/theming workflows (e.g., "translate existing page", "add dark mode", "setup ui lab")
- **search_components**: Individual components (e.g., "button", "input", "checkbox")

For each result, note `purpose`, `codeStructureHint`, `bestFor`, and `variationsSummary`.

**Selective drill-down**: When a variation directly addresses a spotted gap, call the appropriate getter:
- `get_pattern(id)` for patterns
- `get_element(id)` for elements
- `get_section(id)` for sections
- `get_guide(id)` for guides
- `get_component(id, detail="examples")` for component usage examples
- `get_component(id, detail="usage")` when deciding whether a component is appropriate for a given surface, nesting level, or workflow role

Use sparingly — only when clearly applicable. Store findings as working material; weave into later reasoning naturally. If MCP calls fail, continue without them.

## Step 3 — Deconstruct into atomic elements

List every element as a flat inventory. For each:
- Name (e.g., "Submit button", "Empty state message", "Filter dropdown")
- Current implementation (what's there, or "ABSENT" if missing)
- Role in the interface (what job does it do for this specific user?)
- Load-bearing: YES (on the critical user path) or NO (decorative/secondary)

Where a gathered pattern from Step 2.5 is relevant to an element, note it in your thinking ("the filter controls here follow the same grouping structure as the Filter Toolbar variation").

Do not skip states. "No loading state" is itself an element to list as ABSENT.

## Step 4 — Value/impact assessment

For each element in your inventory, rate its value relative to the domain and user you identified in Step 2: HIGH / MEDIUM / LOW / REMOVE.

Ask yourself:
- Does it serve this user's specific need, or does it exist for the builder's convenience?
- Is it in the right place in this user's workflow, or does it appear too early/late?
- Does its visual prominence match its functional importance for this domain?
- Would removing it hurt or improve the interface?
- **Could this element group spatially with related controls (e.g., filters, view toggles, sort) to improve layout coherence?**
- **Is this element always necessary, or is it a candidate for progressive disclosure (dropdown, collapsible, Group.Select)?**
- **Does its placement feel connected to related workflows, or isolated from its functional peers?**
- **Does a gathered pattern suggest this element is under-utilizing available structure?** (e.g., a plain list when the List compound with Checkbox sub-component already handles selection)

REMOVE means: the element actively hurts by adding noise, creating false affordances, or conflicting with the user's workflow. LOW means: marginal value, does not harm. Elements rated REMOVE need a one-line justification.

## Step 5 — Gap identification

Identify elements the interface should have but doesn't. Classify each gap into one or more categories:

**CRITICAL gaps** (interface is broken or misleading without these):
- Native HTML elements instead of UI Lab components: `<button>` → `<Button>`, `<a>` → `<Anchor>`, `<input>` → `<Input>`/`<Checkbox>`/`<Radio>`, `<select>` → `<Select>`, `<div className="flex">` → `<Flex>` — list each one found during ingestion
- Missing feedback states: no empty state, no error state, no loading state, no success confirmation
- Missing workflow connections: no way to go back, no next-step affordance, no escape hatch
- Missing context: user can't tell where they are, what an action does, or what the data means

**LAYOUT COHERENCE gaps** (interface works but feels disconnected or spatially scattered):
- Spatially isolated elements that logically group with existing controls (e.g., search separated from filters, sort icon isolated from view toggles)
- Opportunities to use compound patterns (Group.Select, split buttons, inline grouping) to unify related controls
- Controls scattered across multiple UI regions when they should be proximate (discovery controls spread across top/sidebar instead of grouped)
- Visual hierarchy that obscures relationships between related actions

**PROGRESSIVE DISCLOSURE opportunities** (reduce visual load without losing functionality):
- Secondary or low-frequency controls always visible that could hide in dropdowns, collapsibles, or tabs
- Advanced options with marginal visibility that don't need permanent screen real estate
- Related controls that could share a disclosure pattern (Group.Select, compound menu, expandable section)
- Verbose explanatory text that could be abbreviated or hidden behind a "learn more" interaction

Where a gathered pattern directly addresses a gap, note the structure hint in your gap description (e.g., "→ List | List.Item | List.Checkbox enables managed selection here").

## Step 6 — Actionable brief

Return exactly this structure:
```
DESIGN BRIEF

DOMAIN CONTEXT
[2–4 sentences on domain, user, workflow, emotional state]

ELEMENT INVENTORY
[Name] | [Role] | [Load-bearing: YES/NO] | [Value: HIGH/MEDIUM/LOW/REMOVE]
... (one row per element, including ABSENT ones)

GAPS
CRITICAL:
- [Gap name]: [Why it matters for this specific domain/user]

LAYOUT COHERENCE:
- [Gap name]: [How spatial grouping or pattern unifies the interface] (→ codeStructureHint if a pattern applies)

PROGRESSIVE DISCLOSURE:
- [Gap name]: [How disclosure or compound pattern reduces visual load]

TOP 5 SUGGESTIONS
(Ranked by spatial coherence impact FIRST, then functional criticality. For each suggestion, explain how it improves layout unity, enables progressive disclosure, or connects related workflows—not just what it adds. Where a gathered pattern informed this suggestion, note it naturally.)
1. [Concrete suggestion: element + spatial grouping/pattern] — [Why this matters: spatial coherence benefit + user need]
2. ...
3. ...
4. ...
5. ...

DOWNSTREAM ACTIONS
- For audit: [What violation types to prioritize given this domain]

Do not write code. Do not reference Tailwind classes or UI Lab APIs. Focus on what the interface should do, not how to build it.

# UI Lab Overhaul (Mechanical UI Swap)

You are performing a project-wide UI overhaul to UI Lab. The goal is not to redesign or improve the UI; it is to mechanically replace existing UI primitives/wrappers with UI Lab equivalents while preserving all product logic and behavior.

## Hard constraints (do not violate)

- Change only the view layer. Preserve state, events, props contracts, data fetching, routing, domain models, copy, and analytics hooks unless the user explicitly requests otherwise.
- Do not “improve” the design. No new flows, no UX changes, no layout invention, no feature additions, no refactors unrelated to UI replacement.
- Prefer the narrowest safe replacement: UI Lab **components** first, then **patterns**, then **elements/sections** only if they preserve the existing structure.
- If there is no clear UI Lab equivalent, keep the existing implementation (or wrap UI Lab around it) and record it in the migration report.

## Two-phase workflow (plan → confirm → execute)

You must perform the overhaul in two phases:
1) Produce a scoped plan + replacement report.
2) Stop and ask the user to confirm.
Only after explicit confirmation, proceed with code changes.

## Phase 1: Determine scope, verify setup, and propose a plan

### 1) Determine the scope of the task

- Ask the user to confirm what should be included:
  - Which app(s)/package(s) in the repo
  - Which routes/screens are in scope (or “everything”)
  - Any directories to exclude (e.g., `apps/site`, storybook, internal tooling)
- If the user provides only “overhaul our project UI”, infer a safe default:
  - In-scope: the main product UI app
  - Out-of-scope: docs/demo sites, tests/fixtures, build output

### 2) See if UI Lab is set up

- Determine whether UI Lab is already wired:
  - `ui-lab-components` installed and used
  - Token layer present (theme CSS) and stylesheet import order correct
  - At least one route already renders a UI Lab component with tokens active
- If not set up, do not start the overhaul yet:
  - Use MCP: `search_guides("set up ui lab")` → `get_guide("setup-ui-lab-in-project")`
  - Propose the smallest setup patch needed (installation + stylesheet wiring + a single verification render)
  - Include setup as the first block in the plan (and still require confirmation before applying)

### 3) Present a refactor plan + replacement report (no code changes yet)

Build and present:

- **Execution plan** (ordered, incremental)
  - Start with shared primitives, then shared composites, then pages/routes
  - Include validation checkpoints (typecheck/tests/build) between milestones
- **Replacement report** (inventory)
  - Project-local UI components to replace (e.g., `Button`, `Input`, `Modal`, etc.)
  - Native HTML primitives used directly in UI contexts (`button`, `a`-as-button, `input`, `select`, `textarea`, etc.)
  - For each item: where it is, what it becomes (UI Lab target), and confidence (High/Medium/Low)

MCP guidance for mapping:
- Use `search_components` → `get_component(detail="api")` to select correct UI Lab primitives and props.
- Use `get_component(detail="usage")` when choosing between surface/layout components or when nesting one UI Lab component inside another.
- Use `get_component_source` to ensure imports are correct and to flag likely client components.
- Use `search_patterns` / `get_pattern` only when it matches the existing structure and does not imply a redesign.

### 4) Ask for confirmation

Stop after the plan + report and ask:
- “Do you want me to proceed with the overhaul exactly as planned?”
- If there are any Low-confidence mappings, ask whether to (A) skip them, (B) keep existing UI for those parts, or (C) proceed and iterate.

## Phase 2: Proceed with overhaul (only after confirmation)

### 5) Apply setup (if needed), then overhaul bottom-up

- If UI Lab setup was required, apply it first and re-verify tokens/styles are active.
- Replace primitives first (1:1 mechanical swaps), then composites/pages.
- Keep public contracts stable:
  - Preserve exported component names/paths in the app where possible (swap internals behind the same API)
  - Preserve event/callback semantics and state transitions
  - Preserve accessibility semantics and keyboard behavior

### 6) Validate and produce the migration report

- Run the repo’s validations (typecheck/tests/build) and fix only UI-swap-introduced failures.
- Provide a final report:
  - Swapped items (old → UI Lab target) + key files touched
  - Items skipped/blocked and why
  - Known risks or follow-ups (especially around client/server boundaries, portals, focus traps)

## MCP tool checklist (use these actively)

- `search_guides` → `get_guide` for setup + translation playbooks (especially `translate-existing-ui-to-ui-lab`)
- `search_components` → `get_component(detail="api")` for correct props/slots
- `get_component(detail="usage")` for composition rules, anti-patterns, and preferred alternatives
- `get_component_source` for correct imports and client/server notes
- `get_semantic_color` only when you must replace raw colors encountered during UI swap (do not “re-theme” the app)

## Output format

- Keep updates operational: what you’re doing, what you changed, what’s next.
- Avoid design critique language; focus on equivalence and risk management.

# Core Design Audit Pillars

Six orthogonal dimensions. Each pillar: what it measures, what to check, what to flag.

---

## 1. Design System Adherence

**Measures:** Use of UI Lab tokens, components, and patterns vs. raw HTML / custom styling.

**Check:**
- Native HTML elements replaced with UI Lab equivalents (`<button>` → `<Button>`, `<a>` → `<Anchor>`, `<input>` → `<Input>`/`<Checkbox>`/`<Radio>`, `<div className="flex">` → `<Flex>`, styled `<div>` → `<Card>` / `<Group>`)
- Tokens used for color (no hex, no rgba)
- Semantic tokens for feedback states (success/danger/warning/info), not chromatic Tailwind
- React Aria props (`isDisabled`, `onPress`, `isOpen`)
- Compound sub-components where available
- Theme provider from MCP `get_theme_setup`

**Flag:**
- Any native HTML element with className or style
- Styled `<div>` used as layout or container
- Hex or rgba colors
- `disabled`, `onClick`, `isVisible` on UI Lab components
- Chromatic Tailwind (`green`, `red`, etc.) used for feedback intent

See `design-system.md` for the full component mapping table and token rules.

---

## 2. Layout & Spacing

**Measures:** Alignment, padding consistency, spatial grouping, whitespace, vertical rhythm.

**Check:**
- Padding consistent within component families
- Margin reflects logical grouping (related elements close, unrelated apart)
- Text baselines, grid, and edges aligned
- Whitespace reinforces hierarchy
- Responsive spacing holds across breakpoints

**Flag:**
- Related elements spatially isolated, or unrelated elements crowded
- Inconsistent padding on similar components
- Whitespace that flattens hierarchy instead of reinforcing it
- Mixed spacing systems in one view (some tight, some loose, no pattern)

---

## 3. Accessibility & Usability

**Measures:** Keyboard support, ARIA, interactive state clarity, error recovery.

**Check:**
- ARIA labels and descriptions present where needed
- Tab order logical; focus managed on navigation/modal open
- Hover, active, disabled, focus states all visually distinct
- Error states include a recovery path
- Form validation is inline, not withheld until submit
- Loading states shown for async work
- Touch targets ≥ 44×44px on mobile
- Buttons and links visually distinguishable

**Flag:**
- Interactive element missing hover or focus state
- Disabled state indistinguishable from enabled
- Missing or cryptic ARIA labels
- Tab order jumps or skips
- Error messages with no action for the user to take
- Validation that only appears post-submit

---

## 4. Cognitive Load

**Measures:** Information density, progressive disclosure, visual noise, decision complexity.

**Check:**
- Critical info foregrounded; secondary info behind disclosure (dropdowns, collapsibles)
- Defaults clear when many options exist
- Hierarchy supports scanning
- Modals scoped to a single concern
- Decoration subordinate to content

**Flag:**
- All options flat on screen with weak hierarchy
- Redundant or verbose copy
- Multiple paths to the same task with no scope distinction
- Empty states with vague messaging
- Modals that compound a flow instead of simplifying it
- Decoration that competes with content

---

## 5. Visual Consistency

**Measures:** Consistent typography, color semantics, visual weight, iconography, state feedback.

**Check:**
- Typography roles (heading / body / label) follow one set of rules
- Same state always gets the same color (success = one token, danger = one token, etc.)
- Primary actions carry more weight than secondary
- Same concept uses the same icon
- Success / error / loading / disabled visually distinct
- Corner radii from a fixed set, not arbitrary
- Button variants (filled / outlined / ghost) applied by consistent rule

**Flag:**
- Primary and secondary actions at the same visual weight
- Same state rendered in different colors across views
- Icon + label saying the same thing with no hierarchy benefit
- Typography size/weight jumps without a hierarchy reason
- Mixed corner radii on sibling components
- Success vs. info indistinguishable

---

## 6. Slop Avoidance

**Measures:** AI-generated filler, decorative noise, structural cliches, and low-intent UI chrome.

**Check:**
- Decorative separators have a real section-boundary purpose
- Gradients and shadows communicate data, depth, or state rather than decoration
- Card and section copy avoids badge-led title/description scaffolds and other repeated metadata-first patterns
- Empty states include only the icon, heading, copy, and actions needed to disambiguate the state
- Icons add semantic value instead of merely decorating headings
- Badges communicate hierarchy and status rather than accumulating labels
- Surfaces avoid unnecessary nesting depth
- No placeholder chrome ships in non-dev surfaces

**Flag:**
- Decorative dots, repeated dividers, or separators without structural purpose
- Gratuitous gradients or shadows on non-data surfaces
- Badge-led section stacks and reflexive header + description patterns
- Over-labeled empty states
- Generic icon + generic heading pairs
- Lorem ipsum, `TODO`, `Coming soon`, or stub badges on production surfaces
- Badge stacking with no information hierarchy
- Card-in-card or Group-in-Card-in-Card without semantic or layout purpose

See `slop-patterns.md` for the canonical pattern list, severity levels, and reporting guidance.

---

## Scoring

Each pillar scored 0–5:

| Stars | Meaning |
|---|---|
| 5 | No violations |
| 4 | Minor only — suggestions, low-priority warnings |
| 3 | Moderate — real gaps, core intent intact |
| 2 | Significant — pillar compromised, fix soon |
| 1 | Critical — pillar fundamentally broken |
| 0 | Missing or unusable |

---

## Audit procedure

1. Read the pillar's **Measures** line
2. Walk the **Check** list against the design
3. Walk the **Flag** list for violations
4. Assign stars from count and severity
5. Group violations by severity: CRITICAL / WARNING / SUGGESTION
6. Tie each finding back to the pillar it came from

For Adherence specifics, defer to `design-system.md`. For Slop Avoidance specifics, defer to `slop-patterns.md`.

# UI Lab Design System Reference

Canonical rules for validating adherence to UI Lab tokens, components, and patterns. Each section lists rules; violations are flaggable.

## Color tokens

### Neutral palette

Tailwind neutrals are never allowed. Replace:

| Disallowed | Replacement |
|---|---|
| `bg-white`, `bg-gray-*`, `bg-zinc-*`, `bg-slate-*`, `bg-stone-*`, `bg-neutral-*` | `bg-background-{500–950}` |
| `bg-black` | `bg-background-950` |
| `text-gray-*`, `text-zinc-*`, `text-slate-*`, `text-stone-*`, `text-neutral-*` | `text-foreground-{50–400}` |

Surface is dark-first: higher shade = deeper surface.

| Role | Shade |
|---|---|
| Root container | `bg-background-950` or `-900` |
| Card / panel / modal | `bg-background-800` or `-900` |
| Toolbar / header | `bg-background-700` to `-800` |
| Hover | One shade lighter than base |

### Semantic tokens

Feedback states use semantic tokens, not chromatic Tailwind:

| Intent | Use | Not |
|---|---|---|
| Success | `text-success-*`, `bg-success-*` | `*-green-*` |
| Danger | `text-danger-*`, `bg-danger-*` | `*-red-*` |
| Warning | `text-warning-*`, `bg-warning-*` | `*-yellow-*`, `*-amber-*` |
| Info | `text-info-*`, `bg-info-*` | `*-blue-*` |

Chromatic Tailwind is allowed as intentional decoration (brand, file-type indicators, illustration). Only flag when it substitutes for a semantic token.

### Shade ranges

| Token | Valid range |
|---|---|
| `text-foreground-*` | 50–400 (500+ does not exist) |
| `bg-background-*` (surfaces) | 600–950 |
| `bg-background-*` (text/icon-on-dark only) | any |
| Semantic (`success`/`danger`/`warning`/`info`/`accent`) | max 600 |

`bg-background-{<600}` used as a surface fill is a depth inversion.

### Borders

Borders use `border-background-*`, not `border-foreground-*`. `foreground` tokens are for text and icons only.

| Role | Token |
|---|---|
| Default divider / table row / card edge | `border-background-700` |
| Subtle separator | `border-background-800` |
| Emphasis / input focus ring | `border-background-600` |

`border-foreground-*` is a [CRITICAL] violation — `foreground` tokens carry no border semantic and will render incorrectly across themes.

## Styling prohibitions

Never use:
- Hex: `#rrggbb`
- `rgba()` in className or inline style
- `shadow-*`, `drop-shadow-*`
- `from-*`, `to-*`, `via-*`, `bg-gradient-*`
- `dark:` prefixes (CSS variables handle theming)

## Components

Any native element with styling must be replaced with its UI Lab equivalent.

| Native | UI Lab |
|---|---|
| `<button>` | `<Button>` |
| `<a>` | `<Anchor>` |
| `<input type="text">` | `<Input>` |
| `<input type="checkbox">` | `<Checkbox>` |
| `<input type="radio">` | `<Radio>` |
| `<select>` | `<Select>` |
| `<textarea>` | `<TextArea>` |
| `<label>` | `<Label>` |
| `<form>` | `<Form>` |
| `<div className="flex">` | `<Flex>` |
| `<div className="grid">` | `<Grid>` |
| `<div>` (padded container) | `<Card>` |
| `<div>` (grouping controls) | `<Group>` |

Imports:
```js
import { ComponentName } from 'ui-lab-components'
```

Do not infer component APIs from memory. Fetch from MCP `get_component`. Theme provider must come verbatim from MCP `get_theme_setup`.

### Prop conventions (React Aria)

| Use | Not |
|---|---|
| `isDisabled` | `disabled` |
| `onPress` | `onClick` |
| `isOpen` / `onOpenChange` | `isVisible` / `onVisibilityChange` |

### Compound sub-components

Prefer compound forms over raw wrappers:
- `<Card.Header>`, `<Card.Footer>` over `<div>`
- `<Modal.Footer>` over footer wrapper
- `<List.Item>` with `<List.Checkbox>` for selectable lists
- `<Group.Select>` for grouped controls

## Interactive states

Every interactive element defines: hover, active/pressed, disabled (when applicable), focus (keyboard).

## Affordance rules

- **No zero-state chrome.** Hide counters/filters/results UI until count > 0 (`"0 items selected"`, `"No filters applied"`, `"0 results"` are violations).
- **No duplicate affordances.** Same action on the same element twice (icon button + text link for delete) — pick one or differentiate hierarchy.
- **No mode-leaking affordances.** In mutually exclusive modes (single vs. batch select), per-item actions hide in batch mode; batch actions hide in single mode.
- **No redundant action surfaces.** Two surfaces with the same intent under the same conditions — one is redundant.

## Anti-patterns

Flag these; they indicate hand-tuned utilities substituting for system tokens.

### Typography

- Arbitrary sizes: `text-[11px]`, `text-[10px]`, etc.
- Arbitrary tracking: `tracking-[0.22em]`, etc.
- `uppercase tracking-wide` and similar micro-label combos without semantic need
- `uppercase` used purely for visual flavor
- Stacked overrides like `font-bold leading-snug` on labels, chips, buttons, supporting text
- Manual line-height overrides without a real wrapping/density need

Prefer component defaults and tokenized text styles.

### Motion

- `transition-all` (flag by default)
- `transition-colors` on static containers, layout wrappers, non-interactive decoration
- Decorative `delay-*` with no state-change signal

Motion must be tied to state, feedback, or focus.

### Copy

- **Redundant labels.** Tooltip or aria-label identical to visible text (`<Button>Save</Button>` with `aria-label="Save"`).
- **Parasitic instructions.** Help text that persists after the described action (e.g. "Enter your email" still showing post-submit).
- **Heading/breadcrumb duplication.** Heading restates the last breadcrumb segment.
- **Icon+label parity.** Decorative prefix icon that restates the label with no hierarchy or indicator value.
- **Verbose empty states.** More than one short sentence + one CTA.

## Audit checklist

1. Colors: neutral palette, semantic tokens, shade ranges
2. Styling prohibitions (hex, rgba, shadow, gradient, `dark:`)
3. Component substitutions for styled native elements
4. Imports from `ui-lab-components`; theme from `get_theme_setup`
5. React Aria props; compound sub-components where available
6. Interactive states present
7. Affordance rules (zero-state, duplicates, mode-leaking, redundant surfaces)
8. Anti-patterns (typography, motion, copy)

# Slop Pattern Reference

Canonical slop patterns for the Slop Avoidance pillar. These are AI-generated filler, decorative noise, and structural cliches that make a UI feel less intentional.

Use this reference when auditing a page or component. For each finding, name the concrete element, the canonical pattern, the severity, and the simplest fix that removes or consolidates the slop.

## How to Read This File

- The patterns are grouped by intent, not by visual similarity.
- Use the exact pattern name when reporting findings.
- Prefer removal, consolidation, or hierarchy repair over restyling.
- Do not flag intentional separators, data-driven badges, or depth cues that carry real meaning.

## 1. Decorative Noise

These patterns add visual texture without adding structure, meaning, or state.

### Decorative dots / dividers

- Severity: `WARNING`
- What it is: Dots, dot rows, repeated bullets, or horizontal rules that do not mark a real boundary.
- Typical forms: `•`, `·`, `···`, ornamental rules, repeated separators.
- Fix: Remove the decoration or keep only the separator that reflects an actual section break.

### Gratuitous gradients

- Severity: `WARNING`
- What it is: Gradient styling on surfaces that do not need depth, flow, or data emphasis.
- Typical forms: `bg-gradient-*`, inline gradients, decorative fades on cards or panels.
- Fix: Replace the gradient with a flat token surface unless the gradient carries meaning.

### Gratuitous drop shadows

- Severity: `WARNING`
- What it is: Shadow styling used as decoration instead of elevation or focus.
- Typical forms: `shadow-*` on cards, panels, or text with no layering purpose.
- Fix: Remove the shadow or keep it only when it communicates hierarchy or lift.

## 2. Metadata-First Scaffolds

These patterns turn labels, badges, and headings into a repetitive shell instead of real hierarchy.

### Badge-led section stack

- Severity: `WARNING`
- What it is: A repeated scaffold where a section starts with badges, then a title, then a description, then more badges or metadata.
- Typical forms: `title + badge + description`, `header + description + badges`, `title + content + badges`.
- Fix: Keep the strongest hierarchy signal, remove redundant metadata, and move supporting detail into the body copy.

### Badge stacking

- Severity: `WARNING`
- What it is: Three or more badges grouped together without a clear priority or information hierarchy.
- Typical forms: badge rows, label clusters, status chips stacked as decoration.
- Fix: Collapse badges into one meaningful status, or replace the cluster with a single metadata line.

### Generic icon + generic heading pairs

- Severity: `SUGGESTION`
- What it is: A decorative icon placed beside a heading when the icon does not add meaning.
- Typical forms: icon plus label that restates the same idea, iconography chosen for flavor only.
- Fix: Remove the icon or replace it with one that adds semantic value, status, or direction.

## 3. Placeholder Chrome

These patterns signal unfinished work, mocked content, or production surfaces that still look provisional.

### Placeholder chrome

- Severity: `CRITICAL`
- What it is: Visible filler content or development leftovers shipped into a user-facing surface.
- Typical forms: `Lorem ipsum`, `TODO`, `Coming soon`, stub badges, mock copy in production.
- Fix: Replace the placeholder with real content or remove the surface until it is ready.

## 4. Hierarchy Inflation

These patterns make the UI feel heavier, noisier, or more complicated than the underlying task requires.

### Over-labeled empty states

- Severity: `WARNING`
- What it is: An empty state that uses icon, heading, subtext, and CTA all at once when fewer elements would be clearer.
- Typical forms: icon + heading + subtext + button, repeated explanatory copy that restates the state.
- Fix: Keep only the elements that disambiguate the state and support the next action.

### Unnecessary nesting depth

- Severity: `WARNING`
- What it is: Nested containers that do not add layout structure, semantic clarity, or progressive disclosure.
- Typical forms: card-in-card, group-in-card-in-card, wrapper layers with no distinct purpose.
- Fix: Flatten the hierarchy unless each layer changes layout, semantics, or interaction.

## Canonical Pattern List

Use these names exactly when logging findings:

- Decorative dots / dividers
- Gratuitous gradients
- Gratuitous drop shadows
- Badge-led section stack
- Badge stacking
- Generic icon + generic heading pairs
- Placeholder chrome
- Over-labeled empty states
- Unnecessary nesting depth

## Finding Format

Each Slop Avoidance finding should include:

- The concrete element or component.
- The canonical pattern name.
- The severity.
- A concrete fix that removes, consolidates, or simplifies the pattern.

Example:

`- Empty state panel: [WARNING] Over-labeled empty state with icon, heading, subtext, and CTA -> remove the decorative icon and keep one short sentence plus the primary action`