---
name: ui-refactor-audit
description: >
  Conduct a structured visual design audit against Refactoring UI principles
  (Wathan & Schoger). Use when the user asks to audit, evaluate, or review UI
  code for visual design quality. Triggers on: "audit my UI", "refactoring UI
  review", "check my visual design", "UI debt", "polish my UI", "evaluate
  spacing/typography/color/hierarchy". Does NOT cover WCAG accessibility or
  Nielsen heuristics — those are separate skills.
---

# UI Refactoring Audit

Conduct a structured audit of the target UI files against Refactoring UI
principles. Produce a written report organized by the dimensions below.
For each finding: describe the issue, cite the relevant principle, and
suggest a specific remedy.

**Behavior: ANALYZE AND REPORT ONLY. Do not modify any files unless
explicitly instructed by the user.**

---

## Audit Dimensions

### 1. Visual Hierarchy

Evaluate whether the interface clearly communicates element importance
through contrast, weight, and color — not just size.

Check for:
- Primary content relying solely on font size rather than weight or color contrast
- Secondary content made tiny rather than de-emphasized through softer color
- Competing elements where everything appears equally weighted
- Labels used as a crutch where context or position could do the work
- Semantic HTML hierarchy misaligned with visual hierarchy
- Bold or color used inconsistently to signal importance

Severity: Rate each finding as **Critical / Moderate / Minor**

---

### 2. Layout and Spacing

Evaluate whether spacing is deliberate, systematic, and generous enough.

Check for:
- Spacing added reactively (minimum to avoid looking bad) rather than
  started generously and reduced
- No consistent spacing scale (e.g., 4px or 8px base unit)
- Elements stretched to fill width when a narrower layout would serve better
- Overreliance on grid where absolute widths would be more appropriate
- Relative sizing (%, em) causing unintended scaling behavior
- Ambiguous spacing where it's unclear which elements a gap belongs to

---

### 3. Typography

Evaluate whether type choices are systematic and readable.

Check for:
- Ad hoc font sizes with no underlying scale (more than 5–6 distinct sizes
  in a single view is a common symptom)
- Line length exceeding ~75 characters for body text
- Inconsistent alignment without clear rationale
- Line height that doesn't account for text density
- Links differentiated by color alone with no secondary affordance
- Letter-spacing misuse on body text
- Font choices that contradict the intended interface personality

---

### 4. Color

Evaluate whether color is systematic and communicates meaning.

Check for:
- Hex/RGB values defined inline rather than HSL-based design tokens
- Insufficient palette depth (missing mid-range shades)
- Grey text on colored backgrounds (contrast degrades unpredictably)
- Lightness increases without compensating saturation (washed-out result)
- Color as the only differentiator for meaningful UI states
- Greys with no warm or cool tint when surrounding palette has temperature

---

### 5. Depth and Elevation

Evaluate whether light, shadow, and layering communicate affordance.

Check for:
- Shadows not simulating a consistent light source
- Flat interactive elements with no elevation signal
- Ambiguous or inverted inset vs. raised states
- Heavy drop shadows where subtle layered shadows would read better
- Missed opportunities to use overlap to create depth

---

### 6. Finishing and Polish

Evaluate whether defaults have been considered and elevated.

Check for:
- Default bullets, checkboxes, or radio buttons with no visual treatment
- Unstyled blockquotes used for testimonials or pull quotes
- Links styled with color only and no weight or underline affordance
- Empty states that are blank rather than purposeful
- Borders used as separators where whitespace or color contrast would be cleaner
- Missed accent opportunities (left border on active nav, top accent on card)

---

## Output Format

```
# UI Refactoring Audit — [Component or View Name]
Date: [today]
Files reviewed: [list]

## Summary
[2–3 sentence overview of overall UI health]

## Findings by Dimension

### Visual Hierarchy
- [Finding]: [Description] — Severity: Critical/Moderate/Minor
  Remedy: [Specific actionable suggestion]

### Layout and Spacing
...

### Typography
...

### Color
...

### Depth and Elevation
...

### Finishing and Polish
...

## Priority Recommendations
[Top 3 highest-impact changes, ranked]

## What's Working
[Note dimensions already handled well]
```

---

## Scope Guidance

- Audit the component or view the user references
- If no file is named, ask: "Which component or view should I audit first?"
- Skip generated/vendor files (node_modules, dist, build)
- Note where design system tokens (Tailwind, MUI, etc.) are bypassed

---

## Constraints

- REPORT ONLY unless user explicitly asks for changes
- This skill does not cover WCAG accessibility — that is a separate skill
- This skill does not cover Nielsen heuristics — that is a separate skill
- Flag accessibility overlaps but keep remediation scoped to visual design