UI UX Audit

<!--
Created by: Madina Gbotoe (https://madinagbotoe.com/)
Project: Claude Code Skills - Professional Development Toolkit
Version: 1.0
Created: October 28, 2025
Last Updated: October 29, 2025
License: MIT License
Attribution Required: Yes - Include author name and link when sharing/modifying
GitHub: https://github.com/mgbotoe/claude-code-share
Find latest version: https://github.com/mgbotoe/claude-code-share/tree/main/claude-code-skills/ui-ux-audit

Purpose: UI/UX Audit skill - Prevents redundant implementations by auditing current state before UI/UX changes
-->

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?"