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:

• ✅ This skill runs FIRST (audit phase)

• Then present findings to user

• Then optionally invoke ui-ux-designer agent (design critique)

• 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:

• ✅ READ FIRST, IMPLEMENT SECOND (enforced by Step 1)

• ✅ REDUNDANCY CHECK (enforced by Step 3)

• ✅ RESPECT DESIGN PHILOSOPHY (enforced by Step 5)

• ✅ MANDATORY AUDIT BEFORE UI/UX WORK (this entire skill)

• ✅ 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):

• Use SKILL.md (this file) for process

• Copy template from FORMS.md (Quick Audit Template)

• Follow 5 steps, fill in template

Comprehensive Audit (30+ minutes):

• Use SKILL.md for overall process

• Copy template from FORMS.md (Comprehensive Audit Template)

• Reference REFERENCE.md for detailed requirements

• Compare your work to resources/examples/good-audit-example.md

Learning/Training:

• Read resources/examples/good-audit-example.md (see gold standard)

• Read resources/examples/bad-audit-example.md (learn what to avoid)

• Read resources/case-studies/october-2025-incident.md (understand why this skill exists)

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