Design Consistency Auditor

Design Consistency Auditor

Purpose

Audit and maintain design consistency across frontend applications. Before auditing, discover the project's frontend structure from documentation.

Ensures:

• Color palettes are used consistently
• UI/UX patterns follow best practices
• Components maintain visual harmony
• Accessibility standards are met
• Design system is properly applied
• No design debt accumulates

When to Use

• Auditing design consistency across apps
• Reviewing color palette usage
• Checking UI/UX patterns
• Validating component styling
• Ensuring accessibility compliance
• Identifying design inconsistencies
• Reviewing new features for design standards

Quick Reference

Color Rules

DO: Use semantic tokens (bg-primary, text-base-content, bg-base-100) DON'T: Hardcode hex colors (#000000) or arbitrary values (bg-[#123456])

Component Patterns

Discover the project's component class conventions from its design system or existing codebase. Common patterns to look for:

• Cards: project-specific card class or component (e.g. card, .card, design-system Card component)
• App shells / layouts: project-specific shell wrapper class
• Modals / dialogs: project dialog component pattern
• Inputs: project form input class or component
• Buttons: project button variants (primary, secondary, ghost)

Identify the actual class names from the codebase before auditing — do not assume a specific naming convention.

Spacing

DO: Use Tailwind scale (p-4, m-6, gap-4) DON'T: Use arbitrary values (p-[17px])

Accessibility

• Semantic HTML (<button>, <nav>, <main>)
• ARIA labels on interactive elements
• 4.5:1 contrast for text, 3:1 for UI
• Focus states: focus:outline-none focus:ring-2 focus:ring-primary

Responsive

• Mobile-first with sm:, md:, lg:, xl: modifiers
• Responsive typography: text-3xl sm:text-4xl

Audit Phases

1. Color Palette - Scan for hardcoded colors, verify theme tokens 2. Component Patterns - Check cards, buttons, forms use theme classes 3. Spacing & Layout - Verify consistent spacing scale 4. Typography - Check heading hierarchy and text styles 5. Accessibility - Run automated checks, keyboard testing

AI Slop Prevention

Audit for generic "AI-generated" aesthetics:

• Generic fonts (Inter, Roboto everywhere)
• Purple gradients on white
• Predictable layouts without character
• Safe, boring color choices

Push for distinctive, branded designs with personality.

---

For detailed checklists, examples, reporting templates, and audit commands, see: references/full-guide.md

Design Consistency Audit Report

Date: [YYYY-MM-DD] Scope: [App names or "Full Workspace"] Auditor: Claude Code + Design Consistency Auditor Skill

Executive Summary

• Total Issues Found: X
• Critical: X (accessibility, contrast violations)
• Major: X (hardcoded colors, pattern violations)
• Minor: X (spacing inconsistencies, minor deviations)

• Overall Score: X/100
• Color Consistency: X/20
• Typography: X/20
• Spacing & Layout: X/20
• Component Patterns: X/20
• Accessibility: X/20

Issues by Category

🎨 Color Consistency (X issues)

Critical

• [ ] apps/studio/pages/dashboard.tsx:42
• Issue: Hardcoded hex color #000000
• Impact: Breaks dark mode support
• Fix: Replace with bg-primary
• Priority: High

Major

• [ ] apps/publisher/components/Card.tsx:15
• Issue: Arbitrary Tailwind value bg-[#fafafa]
• Impact: Inconsistent with theme
• Fix: Use bg-base-100
• Priority: Medium

Minor

• [ ] apps/website/components/Hero.tsx:89
• Issue: Using bg-gray-100 instead of theme token
• Impact: Minor visual inconsistency
• Fix: Use bg-base-100
• Priority: Low

📝 Typography (X issues)

Major

• [ ] apps/dashboard/pages/analytics.tsx:23
• Issue: Custom font-family in inline style
• Impact: Breaks design system consistency
• Fix: Remove inline style (Inter is default)
• Priority: Medium

• [ ] apps/automation/components/WorkflowCard.tsx:56
• Issue: Arbitrary text size text-[18px]
• Impact: Not on typography scale
• Fix: Use text-lg
• Priority: Medium

Minor

• [ ] apps/manager/pages/team.tsx:34
• Issue: Inconsistent heading hierarchy (skips h3)
• Impact: Poor semantic structure
• Fix: Use proper heading order
• Priority: Low

📏 Spacing & Layout (X issues)

Major

• [ ] apps/publisher/components/Editor.tsx:78
• Issue: Arbitrary padding p-[17px]
• Impact: Breaks spacing scale
• Fix: Use p-4 or p-6
• Priority: Medium

Minor

• [ ] apps/analytics/pages/reports.tsx:45
• Issue: Inconsistent container spacing
• Impact: Visual inconsistency
• Fix: Use standard px-4 md:px-8
• Priority: Low

🧩 Component Patterns (X issues)

Major

• [ ] apps/dashboard/components/StatCard.tsx:12
• Issue: Custom card styling instead of .gf-card
• Impact: Duplicate patterns, harder maintenance
• Fix: Replace with <div className="gf-card">
• Priority: Medium

• [ ] apps/studio/components/Modal.tsx:34
• Issue: Missing .glass-modal class
• Impact: Inconsistent modal styling
• Fix: Add glass-modal class
• Priority: Medium

Minor

• [ ] apps/settings/components/Button.tsx:23
• Issue: Custom hover state instead of standard
• Impact: Inconsistent interaction
• Fix: Use btn-secondary for this use case
• Priority: Low

♿ Accessibility (X issues)

Critical

• [ ] apps/publisher/components/PostActions.tsx:67
• Issue: Color contrast ratio 2.8:1 (fails WCAG AA)
• Impact: Unusable for users with visual impairments
• Fix: Increase contrast to 4.5:1 minimum
• Priority: High

• [ ] apps/manager/components/TeamMemberCard.tsx:45
• Issue: Missing aria-label on icon button
• Impact: Unusable for screen reader users
• Fix: Add aria-label="Delete team member"
• Priority: High

Major

• [ ] apps/automation/pages/workflows.tsx:123
• Issue: <div onClick> instead of <button>
• Impact: Not keyboard accessible
• Fix: Use semantic <button> element
• Priority: Medium

• [ ] apps/analytics/components/Chart.tsx:89
• Issue: Missing focus states on interactive elements
• Impact: Poor keyboard navigation UX
• Fix: Add focus:outline-none focus:ring-2 focus:ring-primary
• Priority: Medium

Minor

• [ ] apps/dashboard/pages/home.tsx:34
• Issue: Heading hierarchy skip (h1 → h3)
• Impact: Confusing for screen readers
• Fix: Use proper h2 between h1 and h3
• Priority: Low

📱 Responsive Design (X issues)

Major

• [ ] apps/website/components/Pricing.tsx:56
• Issue: Fixed width w-[800px] without responsive variant
• Impact: Breaks on mobile devices
• Fix: Use w-full max-w-3xl
• Priority: Medium

Minor

• [ ] apps/studio/pages/projects.tsx:78
• Issue: Missing responsive typography on heading
• Impact: Suboptimal mobile experience
• Fix: Add text-2xl sm:text-3xl md:text-4xl
• Priority: Low

🎭 Animation & Transitions (X issues)

Minor

• [ ] apps/publisher/components/SaveButton.tsx:23
• Issue: Missing transition on hover state
• Impact: Jarring interaction
• Fix: Add transition-all duration-300
• Priority: Low

• [ ] apps/dashboard/components/Sidebar.tsx:45
• Issue: Arbitrary transition duration duration-[247ms]
• Impact: Inconsistent timing
• Fix: Use duration-300 or duration-500
• Priority: Low

Best Practice Violations

Component Duplication

• 5 card components not using .gf-card class
• apps/dashboard/components/StatCard.tsx
• apps/analytics/components/ReportCard.tsx
• apps/manager/components/TeamCard.tsx
• apps/publisher/components/PostCard.tsx
• apps/automation/components/WorkflowCard.tsx

Missing Theme Support

• 3 components hardcode colors that break dark mode
• apps/website/components/Hero.tsx
• apps/publisher/components/Editor.tsx
• apps/studio/pages/projects.tsx

Non-Semantic HTML

• 8 clickable divs should be buttons or links
• apps/manager/components/QuickAction.tsx:45
• apps/automation/pages/workflows.tsx:123
• apps/analytics/components/FilterButton.tsx:23
• (5 more...)

Recommendations

High Priority (Complete within 1 week)

1. Fix all accessibility violations

• Add missing ARIA labels (2 hours)
• Fix color contrast issues (3 hours)
• Replace non-semantic HTML with proper elements (2 hours)

2. Replace hardcoded colors

• Audit all TSX files for hex colors (1 hour)
• Replace with theme tokens (4 hours)
• Test light/dark mode (1 hour)

3. Add responsive modifiers

• Identify fixed-width components (1 hour)
• Add responsive variants (3 hours)
• Test on all breakpoints (2 hours)

Medium Priority (Complete within 2 weeks)

1. Consolidate card components

• Refactor 5 custom cards to use .gf-card (6 hours)
• Update documentation (1 hour)
• Test across apps (2 hours)

2. Standardize button patterns

• Audit button variants (2 hours)
• Apply .btn-secondary where appropriate (3 hours)
• Document button usage (1 hour)

3. Fix spacing inconsistencies

• Replace arbitrary spacing values (4 hours)
• Apply consistent container spacing (2 hours)

Low Priority (Complete within 1 month)

1. Optimize animations

• Add missing transitions (3 hours)
• Standardize durations (2 hours)
• Test performance (1 hour)

2. Improve typography hierarchy

• Fix heading order issues (2 hours)
• Standardize responsive typography (3 hours)

3. Create component library docs

• Document all theme classes (4 hours)
• Create usage examples (3 hours)
• Set up Storybook (optional, 8 hours)

Files Analyzed

Studio App (24 files)

• apps/studio/app/(protected)/layout.tsx
• apps/studio/app/(protected)/overview/page.tsx
• apps/studio/app/(protected)/g/videos/page.tsx
• [... 21 more files]

Dashboard App (18 files)

• apps/dashboard/app/(protected)/page.tsx
• apps/dashboard/components/Sidebar.tsx
• [... 16 more files]

Publisher App (16 files)

• apps/publisher/app/(protected)/composer/page.tsx
• apps/publisher/components/ThreadEditor.tsx
• [... 14 more files]

Website (12 files)

• apps/website/app/(public)/page.tsx
• apps/website/components/home/_pricing.tsx
• [... 10 more files]

Manager App (10 files)

• apps/manager/app/(protected)/page.tsx
• [... 9 more files]

Analytics App (8 files)

• apps/analytics/app/(protected)/page.tsx
• [... 7 more files]

Automation App (7 files)

• apps/automation/app/(protected)/page.tsx
• [... 6 more files]

Total: 95 files analyzed

Design System Health Score

Current State

Color Consistency:     ████████░░  68/100
Typography:            ███████░░░  72/100
Spacing & Layout:      ██████░░░░  65/100
Component Patterns:    █████░░░░░  58/100
Accessibility:         ████░░░░░░  45/100  ⚠️
Responsive Design:     ██████░░░░  62/100
Animations:            ███████░░░  75/100
-------------------------------------------
Overall Score:         █████░░░░░  63.5/100

Target State (3 months)

Color Consistency:     ██████████  95/100
Typography:            ██████████  90/100
Spacing & Layout:      █████████░  88/100
Component Patterns:    █████████░  92/100
Accessibility:         █████████░  85/100
Responsive Design:     █████████░  88/100
Animations:            █████████░  85/100
-------------------------------------------
Overall Score:         █████████░  89/100

Next Steps

This Week

• [ ] Fix critical accessibility violations
• [ ] Replace hardcoded colors in top 3 apps
• [ ] Add missing ARIA labels

This Month

• [ ] Refactor card components to use .gf-card
• [ ] Standardize button patterns across apps
• [ ] Fix all color contrast issues

This Quarter

• [ ] Create comprehensive design system documentation
• [ ] Set up automated design linting (Stylelint, ESLint plugins)
• [ ] Achieve 85+ accessibility score
• [ ] Reach 90+ overall design health score

Automated Checks

Suggested Tools to Integrate

• Stylelint - Catch hardcoded colors and arbitrary values
• axe-core - Automated accessibility testing
• Lighthouse CI - Performance and accessibility in CI/CD
• Chromatic - Visual regression testing (if using Storybook)

Pre-commit Hooks

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "stylelint --fix"
    ]
  }
}

---

Report Generated: [Date & Time] Skill Version: 1.0.0 Reviewed By: [Name] Sign-off: [ ] Approved [ ] Needs Revision

Quick Design Audit Checklist

Use this checklist for rapid design audits of new features or components.

Pre-Audit Setup

• [ ] Identify scope (app/component/page)
• [ ] Open in both light and dark themes
• [ ] Test on mobile, tablet, and desktop
• [ ] Have design system reference open

1. Color Audit (5 min)

Check for violations

• [ ] No hardcoded hex colors (#000000, #ffffff, etc.)
• [ ] No arbitrary Tailwind values (bg-[#fafafa])
• [ ] No inline color styles
• [ ] All colors use theme tokens (bg-primary, bg-base-100, etc.)
• [ ] Dark mode works correctly

Quick scan commands

# In the file/component directory
grep -n "#[0-9a-fA-F]\{6\}" *.tsx
grep -n "bg-\[#\|text-\[#" *.tsx
grep -n "style={{.*color" *.tsx

Score: ___/10

2. Typography Audit (3 min)

Check for violations

• [ ] No custom font families (Inter is default)
• [ ] No arbitrary text sizes (text-[18px])
• [ ] Proper heading hierarchy (h1 → h2 → h3)
• [ ] Responsive typography modifiers (text-3xl sm:text-4xl)
• [ ] Consistent font weights

Quick checks

# Check for arbitrary sizes
grep -n "text-\[" *.tsx
# Check for custom fonts
grep -n "fontFamily" *.tsx

Score: ___/10

3. Spacing Audit (3 min)

Check for violations

• [ ] No arbitrary spacing (p-[17px], m-[23px])
• [ ] Consistent padding/margin scale
• [ ] Proper container spacing (px-4 md:px-8)
• [ ] Responsive spacing modifiers
• [ ] No inline spacing styles

Quick checks

# Check for arbitrary spacing
grep -n "p-\[\|m-\[\|gap-\[" *.tsx

Score: ___/10

4. Component Patterns Audit (5 min)

Check for violations

• [ ] Cards use .gf-card class
• [ ] App shells use .gf-app
• [ ] Modals use .glass-modal
• [ ] Inputs use .glass-input or .form-focus
• [ ] Buttons use standard variants (.btn-secondary, etc.)

Manual inspection

• [ ] Count custom card implementations
• [ ] Check modal consistency
• [ ] Verify button patterns

Score: ___/10

5. Accessibility Audit (7 min)

Critical checks

• [ ] Semantic HTML (<button>, not <div onClick>)
• [ ] ARIA labels on icon buttons
• [ ] Color contrast ≥ 4.5:1 for text
• [ ] Color contrast ≥ 3:1 for UI elements
• [ ] Focus states visible
• [ ] Keyboard navigation works
• [ ] Screen reader tested (if critical feature)

Quick checks

# Check for non-semantic buttons
grep -n "<div.*onClick" *.tsx
# Check for missing ARIA labels
grep -n "<button" *.tsx | grep -v "aria-label"

Manual testing

• [ ] Tab through all interactive elements
• [ ] Check focus indicators visible
• [ ] Test with browser color contrast checker

Score: ___/10

6. Responsive Design Audit (4 min)

Check for violations

• [ ] No fixed widths without responsive variants
• [ ] Responsive modifiers on key elements (sm:, md:, lg:)
• [ ] Mobile-first approach
• [ ] All breakpoints tested (640px, 768px, 1024px)

Manual testing

• [ ] Resize browser to 375px (mobile)
• [ ] Resize browser to 768px (tablet)
• [ ] Resize browser to 1280px (desktop)

Score: ___/10

7. Animation Audit (2 min)

Check for violations

• [ ] Transitions on interactive elements
• [ ] Consistent durations (duration-300, duration-500)
• [ ] No arbitrary durations (duration-[247ms])
• [ ] Smooth hover states

Quick checks

# Check for arbitrary durations
grep -n "duration-\[" *.tsx

Score: ___/10

8. Dark Mode Audit (3 min)

Check for violations

• [ ] All components work in dark theme
• [ ] No hardcoded light/dark colors
• [ ] Images/icons adapt to theme
• [ ] Sufficient contrast in both themes

Manual testing

• [ ] Toggle to dark mode
• [ ] Check all components render correctly
• [ ] Verify readability

Score: ___/10

Total Score Calculation

Color:          ___/10 × 20% = ___
Typography:     ___/10 × 10% = ___
Spacing:        ___/10 × 10% = ___
Patterns:       ___/10 × 15% = ___
Accessibility:  ___/10 × 25% = ___
Responsive:     ___/10 × 10% = ___
Animation:      ___/10 × 5%  = ___
Dark Mode:      ___/10 × 5%  = ___
----------------------------------
Total:                       ___/100

Rating Scale

• 90-100: Excellent - Ready to ship
• 75-89: Good - Minor tweaks needed
• 60-74: Fair - Needs improvements
• Below 60: Poor - Requires major refactoring

Quick Fixes

If score is below 75, prioritize these quick wins:

5-Minute Fixes

1. Replace hardcoded colors with theme tokens 2. Add missing aria-label attributes 3. Fix arbitrary spacing values 4. Add transitions to buttons

15-Minute Fixes

1. Use .gf-card for custom cards 2. Add responsive modifiers to fixed-width elements 3. Fix semantic HTML (divs → buttons) 4. Add focus states

30-Minute Fixes

1. Fix color contrast violations 2. Implement proper keyboard navigation 3. Refactor duplicate component patterns 4. Test and fix dark mode issues

Notes

Component/Page: ___________________ Audited By: ___________________ Date: ___________________ Time Taken: ___ minutes

Critical Issues:

- - -

Quick Wins:

- - -

Follow-up Required:

- - -

Design Consistency Auditor Skill

A comprehensive Claude Code skill for auditing and maintaining design system consistency across frontend applications. Discovers project structure from documentation.

Quick Start

Running a Full Audit

# Audit a specific app
"Audit the Studio app for design consistency"

# Audit all apps
"Run a full design audit across all frontend apps" (discovers project structure)

# Focus on specific areas
"Check color palette consistency in Publisher app"
"Review accessibility compliance in Dashboard app"

Running a Quick Audit

Use the quick audit checklist for rapid reviews:

# Copy the checklist template
cp examples/quick-audit-checklist.md my-audit.md

# Fill it out while reviewing components
# Takes about 30 minutes for a full app audit

What This Skill Checks

1. Color Palette (20%)

• ✅ Theme token usage (bg-primary, bg-base-100, etc.)
• ❌ Hardcoded hex colors
• ❌ Arbitrary Tailwind values
• ✅ Dark mode compatibility

2. Typography (10%)

• ✅ Consistent font hierarchy
• ✅ Responsive text sizes
• ❌ Custom font families
• ❌ Arbitrary text sizes

3. Spacing & Layout (10%)

• ✅ Tailwind spacing scale
• ❌ Arbitrary spacing values
• ✅ Responsive spacing modifiers
• ✅ Consistent container patterns

4. Component Patterns (15%)

• ✅ .gf-card for cards
• ✅ .glass-modal for modals
• ✅ .btn-secondary for buttons
• ❌ Duplicate component styles

5. Accessibility (25%)

• ✅ Semantic HTML
• ✅ ARIA labels
• ✅ Color contrast ratios (4.5:1 text, 3:1 UI)
• ✅ Keyboard navigation
• ✅ Focus states

6. Responsive Design (10%)

• ✅ Mobile-first approach
• ✅ Responsive modifiers (sm:, md:, lg:)
• ❌ Fixed widths without alternatives
• ✅ All breakpoints tested

7. Animation (5%)

• ✅ Consistent transitions
• ✅ Standard durations (300ms, 500ms)
• ✅ Hover states

8. Dark Mode (5%)

• ✅ Theme-aware colors
• ✅ Both themes tested
• ❌ Hardcoded theme colors

Files Included

design-consistency-auditor/
├── SKILL.md                          # Main skill instructions
├── README.md                         # This file
└── examples/
    ├── audit-report-template.md      # Full audit report template
    └── quick-audit-checklist.md      # 30-minute quick audit

How to Use

For Quick Reviews (30 min)

1. Open examples/quick-audit-checklist.md 2. Copy it to your workspace 3. Go through each section while reviewing the code 4. Score each category out of 10 5. Calculate total score 6. Address critical issues first

For Comprehensive Audits (2-4 hours)

1. Use examples/audit-report-template.md 2. Run automated scans (grep commands in SKILL.md) 3. Manual testing for accessibility and responsiveness 4. Document all findings 5. Prioritize fixes (Critical → Major → Minor) 6. Create action items

Example Commands

Automated Scans

# Find hardcoded colors
grep -r "#[0-9a-fA-F]\{6\}" [frontend-project]/apps/[app-name] --include="*.tsx"  # Discover from project

# Find arbitrary Tailwind values
grep -r "bg-\[#\|text-\[#\|p-\[\|m-\[" [frontend-project]/apps --include="*.tsx"  # Discover from project

# Find inline styles
grep -r "style={{" [frontend-project]/apps --include="*.tsx"  # Discover from project

# Find non-semantic buttons
grep -r "<div.*onClick" [frontend-project]/apps --include="*.tsx"  # Discover from project

Manual Testing

1. Color Contrast: Use browser DevTools or WebAIM Contrast Checker 2. Keyboard Navigation: Tab through all interactive elements 3. Responsive Design: Resize to 375px, 768px, 1280px 4. Dark Mode: Toggle theme and check all components

Common Issues & Fixes

Issue: Hardcoded Colors

// ❌ BAD
<div className="bg-[#fafafa]">

// ✅ GOOD
<div className="bg-base-100">

Issue: Non-Semantic HTML

// ❌ BAD
<div onClick={handleClick}>Click me</div>

// ✅ GOOD
<button onClick={handleClick} aria-label="Action">Click me</button>

Issue: Custom Card Styling

// ❌ BAD
<div className="bg-white border border-gray-200 shadow rounded-lg">

// ✅ GOOD
<div className="gf-card">

Issue: Missing Responsive Modifiers

// ❌ BAD
<div className="w-[800px]">

// ✅ GOOD
<div className="w-full max-w-3xl">

Design System Reference

Color Tokens

Light Theme

• Primary: bg-primary (#000000)
• Background: bg-base-200 (#ffffff)
• Cards: bg-base-100 (#fafafa)
• Borders: border-base-300 (#e5e7eb)
• Text: text-base-content (#111111)

Dark Theme

• Primary: bg-primary (#ffffff)
• Background: bg-base-200 (#020202)
• Cards: bg-base-100 (#0f0f0f)
• Borders: border-base-300 (#1a1a1a)
• Text: text-base-content (#e5e7eb)

Custom Classes

• .gf-app - Main app shell
• .gf-card - Card component
• .glass-modal - Glass morphism modal
• .glass-input - Glass morphism input
• .btn-secondary - Secondary button style
• .form-focus - Form focus styling

Typography Scale

h1: text-4xl sm:text-5xl font-bold
h2: text-3xl sm:text-4xl font-bold
h3: text-2xl sm:text-3xl font-semibold
h4: text-xl sm:text-2xl font-semibold
body: text-base
large: text-lg
small: text-sm

Spacing Scale

Use Tailwind's default scale:

• p-4 = 1rem (16px)
• p-6 = 1.5rem (24px)
• p-8 = 2rem (32px)
• m-4, m-6, m-8 (same values)
• gap-4, gap-6, gap-8 (same values)

Breakpoints

• sm: - 640px
• md: - 768px
• lg: - 1024px
• xl: - 1280px

Success Metrics

Target Scores

• 90-100: Excellent - Production ready
• 75-89: Good - Minor improvements needed
• 60-74: Fair - Requires attention
• Below 60: Poor - Needs refactoring

Health Indicators

Good design consistency when:

• ✅ No hardcoded colors found
• ✅ All accessibility violations fixed
• ✅ 100% dark mode compatibility
• ✅ All components use theme classes
• ✅ Semantic HTML throughout
• ✅ Keyboard navigation works everywhere

Related Skills

This skill works well with:

• Accessibility (a11y) - For deeper accessibility audits
• Component Library Standards - For component architecture
• Copywriter - For content consistency

Maintenance

Update This Skill When

• New theme colors are added
• Custom classes are created
• Design patterns change
• New apps are added

Regular Schedule

• Weekly: Quick audits of new features
• Monthly: Full audit of one app
• Quarterly: Complete design system review

Resources

Tools

• Chrome DevTools (Inspect elements)
• axe DevTools (Accessibility)
• WebAIM Contrast Checker
• Tailwind CSS IntelliSense (VSCode)

Documentation

• @agenticindiedev/ui (check package README/docs)
• Tailwind CSS
• WCAG Guidelines
• Material Design

---

Created: 2025-10-22 Version: 1.0.0 Maintained by: Project Design Team

Need help? Ask Claude: "How do I use the Design Consistency Auditor skill?"

Design Consistency Auditor - Full Guide

Design System Overview

Technology Stack

Frontend Framework: Next.js 15.3.4 with App Router Styling: Tailwind CSS + @agenticindiedev/ui + SCSS Typography: Inter font family Themes: Light and Dark mode support State: React Context API

Color Palette

Light Theme

--color-primary: #000000          // Black
--color-primary-content: #ffffff  // White
--color-base-100: #fafafa         // Cards/menu background
--color-base-200: #ffffff         // App background
--color-base-300: #e5e7eb         // Borders
--color-base-content: #111111     // Dark gray text
--color-muted: #9ca3af            // Muted text
--color-muted-content: #f9fafb    // Muted background

Dark Theme

--color-primary: #ffffff          // White
--color-primary-content: #000000  // Black
--color-base-100: #0f0f0f         // Cards/menu background
--color-base-200: #020202         // App background
--color-base-300: #1a1a1a         // Dividers
--color-base-content: #e5e7eb     // Off-white text
--color-muted: #6b7280            // Muted text
--color-muted-content: #f3f4f6    // Muted background

Custom Theme Classes

Layout

• .gf-app - Main app shell with background and transitions
• .gf-card - Card component with hover effects
• .glass-modal - Glass morphism modal backdrop
• .glass-input - Glass morphism input fields

Buttons

• .btn-secondary - Soft ghost style with primary tint

Forms

• .form-focus - Consistent focus ring styling

Audit Checklist

1. Color Consistency

DO:

• Use @agenticindiedev/ui semantic tokens/classes (e.g. primary/surface/border)
• Use custom theme classes: .gf-app, .gf-card, .btn-secondary
• Apply colors through Tailwind utilities: bg-primary, text-base-content
• Use opacity modifiers for subtle effects: bg-primary/5, bg-primary/20

DON'T:

• Hardcode hex colors in components (#000000, #ffffff)
• Use arbitrary color values: bg-[#123456]
• Mix custom CSS colors with Tailwind classes
• Use inline styles for colors
• Skip theme-aware color tokens

Example Violations:

// BAD - Hardcoded colors
<div style={{ backgroundColor: '#000000' }}>
<div className="bg-[#fafafa]">

// GOOD - Theme-aware classes
<div className="bg-primary">
<div className="bg-base-100">

2. Typography Consistency

DO:

• Use Tailwind typography utilities: text-sm, text-lg, font-bold
• Apply Inter font family (auto-applied via globals.scss)
• Use consistent heading hierarchy: text-3xl sm:text-4xl for h2
• Apply consistent line heights and letter spacing

DON'T:

• Set custom font families (Inter is default)
• Use arbitrary font sizes: text-[14px]
• Skip responsive typography modifiers
• Mix different type scales across components

Example Violations:

// BAD - Custom fonts and sizes
<h2 style={{ fontFamily: 'Arial', fontSize: '32px' }}>

// GOOD - Consistent Tailwind classes
<h2 className="text-3xl sm:text-4xl font-bold mb-4 text-primary">

3. Spacing Consistency

DO:

• Use Tailwind spacing scale: p-4, m-8, gap-6, space-y-4
• Apply shared UI utilities for radius, spacing, and shadows from @agenticindiedev/ui
• Use consistent container padding: px-4 md:px-8
• Apply grid/flex gaps consistently

DON'T:

• Use arbitrary spacing values: p-[17px]
• Mix different spacing patterns
• Skip responsive spacing modifiers
• Use inline margin/padding styles

Example Violations:

// BAD - Arbitrary spacing
<div className="p-[17px] m-[23px]">

// GOOD - Consistent spacing scale
<div className="p-4 m-6">

4. Component Patterns

DO:

• Use .gf-card for card components
• Apply .gf-app to app shells
• Use .glass-modal for modals with backdrop
• Apply .glass-input for input fields
• Use .btn-secondary for secondary actions
• Apply .form-focus for form inputs

DON'T:

• Create duplicate card styles
• Skip custom theme classes
• Build modals without glass effects
• Ignore established button variants

Example Violations:

// BAD - Duplicate card styling
<div className="bg-white border border-gray-200 shadow rounded-lg">

// GOOD - Theme class
<div className="gf-card">

5. Accessibility (a11y)

DO:

• Use semantic HTML: <button>, <nav>, <main>, <article>
• Add ARIA labels to interactive elements
• Ensure 4.5:1 color contrast ratio (text)
• Ensure 3:1 color contrast ratio (UI elements)
• Support keyboard navigation
• Apply focus states: focus:outline-none focus:ring-2 focus:ring-primary
• Use sr-only for screen reader text

DON'T:

• Use <div> for buttons/links
• Skip ARIA labels on icons
• Use low-contrast colors
• Remove focus outlines without replacement
• Ignore keyboard navigation

Example Violations:

// BAD - No semantics or a11y
<div onClick={handleClick}>Click me</div>

// GOOD - Semantic button with focus
<button
  onClick={handleClick}
  className="btn btn-primary focus:outline-none focus:ring-2 focus:ring-primary"
  aria-label="Submit form"
>
  Click me
</button>

6. Responsive Design

DO:

• Use Tailwind responsive modifiers: sm:, md:, lg:, xl:
• Apply mobile-first design
• Test all breakpoints: 640px, 768px, 1024px, 1280px
• Use responsive typography: text-3xl sm:text-4xl
• Apply responsive spacing: px-4 md:px-8

DON'T:

• Use fixed widths without responsive alternatives
• Skip mobile testing
• Use max-w- without responsive variants
• Ignore tablet/desktop breakpoints

Example Violations:

// BAD - Fixed width
<div className="w-[800px]">

// GOOD - Responsive width
<div className="w-full max-w-3xl mx-auto">

7. Animation & Transitions

DO:

• Use consistent transition durations: duration-300, duration-500
• Apply smooth transitions: transition-all, transition-colors
• Use hover states: hover:shadow-md, hover:bg-primary/20
• Apply ease timing: ease-in-out

DON'T:

• Skip transitions on interactive elements
• Use arbitrary durations: duration-[247ms]
• Mix different timing functions
• Overuse animations

Example Violations:

// BAD - No transition
<button className="bg-primary">

// GOOD - Smooth transition
<button className="bg-primary transition-all duration-300 hover:bg-primary/80">

8. Dark Mode Support

DO:

• Test all components in both light and dark themes
• Use theme-aware color tokens
• Avoid hardcoded colors that don't adapt
• Apply data-theme attribute correctly

DON'T:

• Hardcode theme-specific colors
• Skip dark mode testing
• Use colors that don't have theme variants

Example Violations:

// BAD - Hardcoded white background
<div className="bg-white text-black">

// GOOD - Theme-aware
<div className="bg-base-100 text-base-content">

Audit Process

Phase 1: Color Palette Audit

1. Scan for hardcoded colors

• Search: #[0-9a-fA-F]{3,6} in TSX/JSX files
• Search: style={{.*color.*}} for inline styles
• Search: bg-\[#, text-\[# for arbitrary values

2. Verify theme tokens

• Ensure all colors use @agenticindiedev/ui tokens
• Check custom classes are applied correctly
• Validate light/dark theme consistency

3. Generate report

   Color Violations Found: X
   - File: path/to/component.tsx:42
     Issue: Hardcoded hex color #000000
     Fix: Use bg-primary instead

Phase 2: Component Pattern Audit

1. Check card components

• Verify .gf-card usage
• Validate hover states
• Check border and shadow consistency

2. Check button variants

• Primary buttons: btn btn-primary
• Secondary buttons: btn-secondary
• Ghost buttons: btn-ghost

3. Check form elements

• Verify .form-focus on inputs
• Check .glass-input for special inputs
• Validate label associations

Phase 3: Spacing & Layout Audit

1. Verify container spacing

• Check container mx-auto px-4 md:px-8 pattern
• Validate consistent padding
• Check responsive spacing

2. Check component spacing

• Verify space-y-* for vertical stacks
• Check gap-* for grids/flex
• Validate margin/padding scale usage

Phase 4: Typography Audit

1. Check heading hierarchy

   h1: text-4xl sm:text-5xl font-bold
   h2: text-3xl sm:text-4xl font-bold
   h3: text-2xl sm:text-3xl font-semibold
   h4: text-xl sm:text-2xl font-semibold

2. Verify body text

• Default: text-base-content
• Large: text-lg
• Small: text-sm
• Muted: text-muted

Phase 5: Accessibility Audit

1. Run automated checks

• Use axe-core or similar tool
• Check color contrast ratios
• Verify semantic HTML

2. Manual keyboard testing

• Tab through all interactive elements
• Verify focus states visible
• Check modal trap behavior

3. Screen reader testing

• Verify ARIA labels
• Check heading structure
• Validate form labels

Reporting Format

Design Audit Report Template

# Design Consistency Audit Report

**Date**: [Date]
**Scope**: [App/Component names]
**Auditor**: [Name/Agent]

## Summary

- Total Issues: X
- Critical: X
- Major: X
- Minor: X

## Issues by Category

### Color Consistency (X issues)

- [ ] `apps/studio/app/page.tsx:42` - Hardcoded #000000, use bg-primary
- [ ] `apps/dashboard/components/Card.tsx:15` - Arbitrary bg-[#fafafa], use bg-base-100

### Typography (X issues)

- [ ] `apps/website/components/Hero.tsx:23` - Custom font-size, use text-4xl

### Spacing (X issues)

- [ ] `apps/publisher/components/Editor.tsx:56` - Arbitrary p-[17px], use p-4

### Accessibility (X issues)

- [ ] `apps/manager/components/Button.tsx:12` - Missing aria-label
- [ ] `apps/analytics/pages/dashboard.tsx:78` - Low contrast ratio 2.8:1

## Best Practice Violations

### Component Patterns

- [ ] 5 card components not using `.gf-card`
- [ ] 3 modals missing `.glass-modal`

### Responsive Design

- [ ] 8 components without responsive modifiers

## Recommendations

1. **High Priority**

   - Fix all color contrast violations
   - Replace hardcoded colors with theme tokens
   - Add missing ARIA labels

2. **Medium Priority**

   - Consolidate card components to use `.gf-card`
   - Add responsive modifiers to fixed-width components

3. **Low Priority**
   - Standardize spacing scale usage
   - Optimize transition durations

## Files Analyzed

- [List of files]

## Next Steps

- [ ] Address critical issues
- [ ] Update component library documentation
- [ ] Create design system guidelines

Design Best Practices

Avoid "AI Slop" Aesthetic (CRITICAL)

Source: Claude 4 Best Practices - https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices

AI-generated frontends tend to converge on generic, "on distribution" outputs that create what users call the "AI slop" aesthetic. This skill audits for and prevents this pattern.

AI SLOP WARNING SIGNS:

• Generic fonts (Inter, Roboto, Arial, system fonts) used everywhere
• Clichéd purple gradients on white backgrounds
• Predictable component layouts with no character
• Cookie-cutter designs lacking context-specific style
• Overuse of the same patterns across all pages
• Safe, boring color choices that "just work"
• Space Grotesk and other trending AI-default fonts

DESIGN FOR DELIGHT:

• Typography: Choose fonts that are beautiful, unique, and interesting. Opt for distinctive choices that elevate the frontend's aesthetics over safe defaults
• Color & Theme: Commit to a cohesive aesthetic. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration
• Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions. Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions
• Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects

AUDIT FOR DISTINCTIVENESS:

When reviewing frontend code, ask:

• Does this look like it was designed specifically for THIS product?
• Would a user recognize this app from its visual style?
• Are we using the same fonts/colors as every other AI-generated app?
• Does the design have personality and character?
• Vary between light and dark themes across contexts
• Think outside the box - avoid converging on common AI choices

Visual Hierarchy

DO:

• Use size and weight to establish hierarchy
• Apply consistent heading scales
• Use whitespace to group related content
• Apply contrast to draw attention

Example:

<div className="space-y-6">
  <h1 className="text-4xl font-bold text-primary">Main Title</h1>
  <p className="text-lg text-base-content">Important description</p>
  <p className="text-sm text-muted">Secondary information</p>
</div>

Consistency Over Innovation

DO:

• Follow established patterns
• Reuse existing components
• Apply design system classes
• Maintain visual rhythm

DON'T:

• Create one-off designs
• Reinvent common components
• Skip design system review

Progressive Disclosure

DO:

• Show most important content first
• Use modals for secondary actions
• Apply tooltips for helper text
• Implement expand/collapse for details

Feedback & Affordance

DO:

• Show hover states on interactive elements
• Display loading states for async actions
• Provide error/success feedback
• Use disabled states for unavailable actions

Example:

<button
  className="btn btn-primary transition-all duration-300 hover:bg-primary/80 disabled:opacity-50"
  disabled={isLoading}
>
  {isLoading ? "Loading..." : "Submit"}
</button>

Performance

DO:

• Minimize custom CSS
• Use Tailwind JIT mode
• Optimize image assets
• Lazy load non-critical components

DON'T:

• Add unused Tailwind classes
• Import entire icon libraries
• Skip image optimization

Common Violations

Button Inconsistency

Common Issue:

// Different button styles across apps
<button className="px-4 py-2 bg-black text-white rounded">
<button className="bg-primary text-primary-content px-6 py-3 rounded-lg">
<a className="inline-block p-3 bg-gray-900 text-white">

Fix:

// Consistent button pattern
<button className="btn btn-primary">Primary Action</button>
<button className="btn-secondary">Secondary Action</button>
<button className="btn btn-ghost">Tertiary Action</button>

Card Duplication

Common Issue:

// Duplicate card styling
<div className="bg-white border border-gray-200 shadow rounded-lg p-6">
<div className="bg-base-100 border-base-300 border rounded-box p-4 shadow-sm">

Fix:

// Use theme class
<div className="gf-card p-6">

Spacing Chaos

Common Issue:

// Inconsistent spacing
<div className="p-[17px] mt-[23px] mb-[15px]">

Fix:

// Consistent spacing scale
<div className="p-4 my-6">

Tools & Resources

Audit Tools

• Chrome DevTools - Inspect elements, check colors
• axe DevTools - Accessibility testing
• Tailwind CSS IntelliSense - VSCode extension for validation
• Contrast Checker - WebAIM contrast checker

Design References

• @agenticindiedev/ui: Check the package README/docs
• Tailwind Docs: https://tailwindcss.com/
• WCAG Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
• Material Design: https://material.io/design

Codebase Locations

Design System Files

• [frontend-project]/packages/styles/globals.scss - Global styles (discover from project)
• [frontend-project]/packages/styles/theme.scss - Theme definitions
• [frontend-project]/packages/styles/animate.scss - Animations
• [frontend-project]/tailwind.config.ts - Tailwind configuration

Frontend Apps

• [frontend-project]/apps/[app-1]/ - App 1 (discover from project structure)
• [frontend-project]/apps/[app-2]/ - App 2
• [frontend-project]/apps/[app-3]/ - App 3

Audit Commands

Quick Audit Scripts

# Find hardcoded hex colors
grep -r "#[0-9a-fA-F]\{6\}" [frontend-project]/apps --include="*.tsx" --include="*.jsx"

# Find arbitrary Tailwind values
grep -r "bg-\[#\|text-\[#\|p-\[\|m-\[" [frontend-project]/apps --include="*.tsx"

# Find inline styles
grep -r "style={{" [frontend-project]/apps --include="*.tsx"

# Find missing theme classes
grep -r "className=\".*card" [frontend-project]/apps --include="*.tsx" | grep -v "[project-prefix]-card"

# Check for non-semantic buttons
grep -r "<div.*onClick" [frontend-project]/apps --include="*.tsx"

Maintenance

Regular Audits

Weekly: Quick spot checks on new features Monthly: Full design audit of one app Quarterly: Complete design system review

Documentation Updates

Keep this skill updated when:

• New theme colors are added
• Custom classes are created
• Design patterns change
• New apps are added to monorepo