playbooks

home / skills / shipshitdev / library / design-consistency-auditor

design-consistency-auditor skill

/bundles/frontend/skills/design-consistency-auditor

This skill audits design system consistency across frontend apps, ensuring color tokens, patterns, accessibility, and typography align with branding.

npx playbooks add skill shipshitdev/library --skill design-consistency-auditor

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
2.5 KB
---
name: design-consistency-auditor
description: Audit and maintain design system consistency, UX/UI patterns, color palettes, and design best practices across frontend applications
version: 1.0.0
tags:
  - design
  - ux
  - ui
  - consistency
  - audit
  - tailwind
  - agenticindiedev-ui
  - accessibility
---

# 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

- Cards: `.gf-card`
- App shells: `.gf-app`
- Modals: `.glass-modal`
- Inputs: `.glass-input`, `.form-focus`
- Buttons: `btn btn-primary`, `.btn-secondary`, `btn-ghost`

### 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`

Overview

This skill audits and maintains design system consistency across frontend applications. It finds mismatches in color palettes, UI patterns, spacing, typography, and accessibility to reduce design debt and keep interfaces cohesive. The auditor produces actionable reports and remediation guidance developers and designers can apply quickly.

How this skill works

The auditor scans project files and documentation to discover the frontend structure, then runs a phased audit: color palette checks, component pattern verification, spacing and layout validation, typography hierarchy review, and accessibility testing. It flags hardcoded values, non-semantic markup, inconsistent utility usage, and common "AI-generated" aesthetic issues, and suggests concrete fixes using semantic tokens and approved classes.

When to use it

  • Before release to ensure new screens follow the design system
  • During design reviews to catch inconsistent components or spacing
  • When integrating a third-party UI library or component
  • Periodically to prevent accumulation of design debt
  • While validating accessibility compliance and focus states

Best practices

  • Prefer semantic tokens (e.g., bg-primary, text-base-content) over hex values
  • Use the design system component classes for cards, shells, modals, inputs, and buttons
  • Follow the established spacing scale (Tailwind scale like p-4, gap-4) and avoid arbitrary values
  • Adopt mobile-first responsive modifiers and responsive typography
  • Enforce semantic HTML, ARIA attributes on interactive controls, and sufficient contrast ratios

Example use cases

  • Scan a new feature branch to ensure buttons, cards, and forms use theme classes
  • Detect and replace hardcoded color hexes with semantic tokens across the codebase
  • Produce an accessibility report highlighting missing ARIA labels and low-contrast text
  • Audit spacing inconsistencies introduced by vendor components and recommend scale-compliant fixes
  • Review overall aesthetic for generic AI-generated patterns and suggest distinctive, branded alternatives

FAQ

Can the auditor automatically fix issues?

It can auto-suggest fixes and generate patchable lists; full automatic replacement should be reviewed and applied per-team policy.

Which accessibility standards are checked?

It checks semantic HTML, ARIA usage, keyboard focus, and contrast ratios (text 4.5:1, UI elements 3:1), plus automated WCAG-style heuristics.