ui-ux-audit

name	ui-ux-audit
description	Mandatory audit workflow for UI/UX changes that reads current state FIRST, checks for redundancy, respects clean design philosophy, and identifies genuine gaps before implementation. Auto-invoked when user mentions UI, UX, design, layout, homepage, page improvements, visual changes, or interface modifications.

UI/UX Audit Skill

🚨 CRITICAL: This Skill Runs BEFORE Implementation

Purpose: Prevent redundant implementations and cluttered designs by auditing current state FIRST.

When to invoke: Automatically when user mentions:

• UI/UX work: "improve UI", "enhance UX", "better design", "update layout"
• Page work: "fix homepage", "improve page", "update interface", "redesign"
• Visual changes: "add visual elements", "enhance visuals", "improve appearance"
• Component work: "add component", "new feature", "improve section"
• General improvements: "make it better", "improve experience", "enhance site"

Order of execution:

1. ✅ This skill runs FIRST (audit phase)
2. Then present findings to user
3. Then optionally invoke ui-ux-designer agent (design critique)
4. Then implement approved changes

---

Mandatory Audit Process (READ FIRST, IMPLEMENT SECOND)

Step 1: Read Current State (Non-Negotiable)

Before making ANY recommendations, read these files:

# Target page file
Read: src/app/[target-page]/page.tsx

# Related components (if modifying existing sections)
Read: src/components/sections/[component].tsx

# Related data files
Read: src/data/[related-data].tsx
Read: src/data/page-content/[page]-content.ts

# Check for existing similar functionality
Grep: Search for keywords related to proposed feature

Example:

User: "Improve homepage"

MUST READ FIRST:
- src/app/page.tsx
- src/components/sections/Hero.tsx
- src/data/page-content/home-content.ts

THEN analyze what EXISTS before proposing anything

Step 2: Document What EXISTS (Evidence-Based)

Create inventory of current state:

## Current State Audit: [Page Name]

### Existing Components
- Component 1: [Description, location, purpose]
- Component 2: [Description, location, purpose]

### Existing Data Display
- Portfolio metrics: [Where shown, format]
- CTAs: [Location, text, purpose]
- Content sections: [List all sections]

### Design Characteristics
- Layout: [Grid, flex, columns]
- White space: [Generous, tight, balanced]
- Information density: [Minimal, moderate, dense]
- Visual style: [Clean, busy, colorful, minimal]

### Evidence
[Show actual code snippets proving what exists]

Step 3: Redundancy Check (Critical)

Before proposing ANY addition, verify:

• Is this data already displayed elsewhere on the page?
• Does similar functionality exist in different form?
• Would this duplicate existing content?
• Would this clutter a clean design?
• Is information shown more than once?

Anti-Patterns to Avoid (from October 2025 lessons):

❌ Portfolio Visualization when impact cards already show portfolio breakdown ❌ Large AI Assistant card when primary CTAs already exist in hero ❌ Metric sidebars on document-style pages (like /brief) ❌ Dashboards on intentionally minimal pages (like /ai-lab) ❌ Duplicate data displays in multiple sections ❌ Bulk additions without clear value proposition

Step 4: Identify GENUINE Gaps (Not Assumed Gaps)

Only propose additions for:

✅ Missing functionality (proven by code audit) ✅ Genuine UX problems (demonstrated, not assumed) ✅ Clear value add (specific benefit articulated) ✅ Respects clean design (doesn't add bulk)

Template:

## Genuine Gaps Identified

### Gap 1: [Specific missing element]
- Evidence: [Code shows this doesn't exist]
- User need: [Why user needs this]
- Value: [Specific benefit]
- Simple solution: [Minimal approach]
- No redundancy: [Confirmed doesn't duplicate X]

### Gap 2: [Next gap]
...

Step 5: Design Philosophy Check

This portfolio has a CLEAN, MINIMAL aesthetic by design:

Check against these principles:

• Simple, scannable layouts
• Strategic use of white space
• Information shown ONCE, not repeated
• Document-style pages stay document-like
• No bulk additions without clear need

Questions to ask:

• Does this ADD value or just ADD BULK?
• Is this the SIMPLEST solution?
• Does this respect the existing clean design?
• Would this survive user review or get reverted?

---

Audit Output Template

Present findings in this format:

# UI/UX Audit Report: [Page Name]

## Current State Summary
[2-3 sentences describing current design]

## What Already EXISTS
1. [Component/feature]: [Description with code location]
2. [Component/feature]: [Description with code location]
3. [Component/feature]: [Description with code location]

Evidence: [Code snippets proving these exist]

## Redundancy Check Results
✅ No redundancy detected: [Explain]
OR
⚠️ Potential redundancy: [Show what duplicates what]

## Genuine Gaps Identified
### Priority 1: [Most important gap]
- Evidence: [Why this is missing]
- User impact: [Specific problem it solves]
- Proposed solution: [Minimal approach]
- No redundancy: [Confirmed]

### Priority 2: [Next gap]
...

## NOT Recommended (Would Create Redundancy)
❌ [Proposed feature]: Already exists as [existing feature]
❌ [Proposed feature]: Would duplicate [existing data]

## Design Philosophy Compliance
✅ Respects clean, minimal aesthetic
✅ Adds value without adding bulk
✅ No information duplication
OR
⚠️ Concerns: [List any design philosophy violations]

## Recommendation
**Recommended:** Implement Priority 1 gap ([brief description])
**Not Recommended:** [List features that would add redundancy]

**Next Steps:**
1. User review of findings
2. (Optional) Invoke ui-ux-designer agent for design critique
3. Implement approved changes incrementally

---

Verification Checklist

Before completing audit, verify:

• Did I read all target page/component files FIRST?
• Did I document what EXISTS (not what I assume is missing)?
• Did I check for redundancy systematically?
• Did I identify GENUINE gaps (not assumed gaps)?
• Did I verify no information duplication?
• Does recommendation respect clean, minimal design?
• Did I propose SIMPLEST solution?
• Would this survive user review?

If any answer is NO, STOP and reassess.

---

Example: Good vs. Bad Audit

❌ BAD Audit (What NOT to do)

User: "Improve homepage"

Bad Response:
"I recommend adding:
1. Portfolio visualization showing $156M breakdown
2. Large dashboard with metrics
3. Section transitions between content
4. Enhanced testimonials with animations"

Problem: Didn't read current state, didn't check for redundancy

✅ GOOD Audit (What TO do)

User: "Improve homepage"

Good Response:
"Let me audit the current homepage first..."

[Reads src/app/page.tsx]

"Current State Audit:

What EXISTS:
- Impact cards already display portfolio breakdown ($156M, $91M, etc.)
- Hero has primary CTAs (View Work, See Skills, Get In Touch)
- Testimonials section exists
- EKG dividers separate sections

Redundancy Check:
⚠️ Adding portfolio visualization would DUPLICATE impact card data

GENUINE Gap:
✅ No CTA after testimonials section (natural conversion point)

Recommendation:
- Add single strategic CTA after testimonials
- Do NOT add portfolio visualization (redundant)
- Keep clean, minimal design

Would you like to proceed with the CTA addition?"

---

Integration with CLAUDE.md Rules

This skill enforces the mandatory rules from CLAUDE.md:

1. ✅ READ FIRST, IMPLEMENT SECOND (enforced by Step 1)
2. ✅ REDUNDANCY CHECK (enforced by Step 3)
3. ✅ RESPECT DESIGN PHILOSOPHY (enforced by Step 5)
4. ✅ MANDATORY AUDIT BEFORE UI/UX WORK (this entire skill)
5. ✅ VERIFICATION CHECKLIST (enforced by final checklist)

---

Trigger Keywords Reference

Auto-invoke this skill when user says:

UI/UX Terms:

• improve UI, enhance UX, better design, update layout
• improve user experience, enhance interface, better visuals
• redesign, refactor UI, update design, modernize
• make it look better, improve appearance, visual improvements

Page Terms:

• fix homepage, improve page, update page, enhance page
• homepage improvements, page redesign, layout changes
• improve landing page, better home screen

Component Terms:

• add component, new feature, improve section
• enhance hero, update header, improve footer
• add visualization, add dashboard, add metrics
• new UI element, add interface component

General Improvement:

• make it better, improve experience, enhance site
• improve portfolio, better showcase, enhance presentation
• improve conversion, better engagement, increase impact

Question Form:

• "How can I improve X?"
• "What should I add to X?"
• "Should I add X to the page?"

---

Remember: This Skill Prevents the October 2025 Session Mistakes

What went wrong that day:

• Implemented Phase 3 UI/UX recommendations without reading pages
• Added PortfolioVisualization despite impact cards showing same data
• Added large AI Assistant card overshadowing primary CTAs
• Added bulk to AI Lab page making it "look like two pages in one"
• User had to revert everything

This skill prevents those mistakes by:

• Reading current state FIRST (always)
• Checking for redundancy BEFORE proposing
• Respecting clean, minimal design philosophy
• Identifying genuine gaps (not assumed gaps)
• Presenting evidence-based findings to user BEFORE implementing

---

Supporting Files & Resources

This skill includes additional resources for comprehensive audits:

REFERENCE.md - Detailed UX Research

When to read:

• Need detailed WCAG 2.1 AA requirements
• Want UX research citations (Nielsen Norman Group, etc.)
• Understanding design patterns and anti-patterns
• Deep dive into audit methodology

Contains:

• Left-attention pattern research (80/20 rule)
• F-pattern reading principles
• Cognitive load principles (Miller's Law, Hick's Law)
• Complete WCAG 2.1 AA requirements
• Design pattern library
• Measurement frameworks

Read with: Read: [skill-directory]/REFERENCE.md

---

FORMS.md - Pre-Filled Templates

When to read:

• Starting a new audit (copy template)
• Need structured checklist format
• Want standardized audit output

Contains:

• Quick Audit Template (5-10 min)
• Comprehensive Audit Template (30+ min)
• Redundancy Checklist
• Gap Analysis Template
• WCAG Compliance Checklist
• Mobile Optimization Checklist
• Performance Audit Template

Read with: Read: [skill-directory]/FORMS.md

---

resources/ - Examples & Case Studies

When to read:

• First-time conducting UI/UX audit
• Unsure if approach is correct
• Learning from real examples
• Training others

Contains:

• examples/good-audit-example.md - Gold standard audit
• examples/bad-audit-example.md - What NOT to do
• case-studies/october-2025-incident.md - Real incident that inspired this skill
• README.md - Navigation guide

Read with: Read: [skill-directory]/resources/[filename]

---

Usage Guide for Supporting Files

Quick Audit (< 10 minutes):

1. Use SKILL.md (this file) for process
2. Copy template from FORMS.md (Quick Audit Template)
3. Follow 5 steps, fill in template

Comprehensive Audit (30+ minutes):

1. Use SKILL.md for overall process
2. Copy template from FORMS.md (Comprehensive Audit Template)
3. Reference REFERENCE.md for detailed requirements
4. Compare your work to resources/examples/good-audit-example.md

Learning/Training:

1. Read resources/examples/good-audit-example.md (see gold standard)
2. Read resources/examples/bad-audit-example.md (learn what to avoid)
3. Read resources/case-studies/october-2025-incident.md (understand why this skill exists)
4. Practice using FORMS.md templates

---

Final Note

This is not optional. When user mentions UI/UX work, this skill MUST run first to audit current state before any implementation begins.

The goal: Prevent redundant implementations, respect existing design, propose targeted improvements only.

New to UI/UX audits? Start with resources/examples/good-audit-example.md to see the process in action.