design-system-quality

Design System Quality

Ensure code meets design system standards for consistency, accessibility, and brand compliance.

Purpose

This skill provides quality gates for UI code reviews, ensuring all frontend work adheres to established design system patterns, accessibility standards, and component conventions.

When to Activate

Use this skill when:

• Reviewing UI/frontend code
• Conducting PR reviews for components
• Checking design system compliance
• After any UI component work

---

Quality Dimensions

1. Design Token Compliance

Color Usage

CORRECT                           WRONG
var(--bg-primary)                    bg-white
var(--fg-secondary)                  text-gray-500
var(--border-primary)                border-slate-200
bg-bg-primary (Tailwind mapped)      #191919 (hardcoded)

Verification Command:

# Find hardcoded colors (should return empty)
grep -rE "#[0-9A-Fa-f]{3,6}|rgb\(|rgba\(" --include="*.tsx" --include="*.css" | grep -v "var(--"

# Find forbidden Tailwind classes
grep -rE "bg-white|bg-black|text-white|text-black" --include="*.tsx"

Token Categories

Category	Usage	Example
Background	Surface colors	var(--bg-primary), var(--bg-secondary)
Foreground	Text colors	var(--fg-primary), var(--fg-secondary)
Border	Line/divider colors	var(--border-primary), var(--border-secondary)
Brand	Accent/CTA colors	var(--brand-primary)

2. Component Patterns

Accessible Component Libraries

All interactive elements should use accessible component libraries:

// CORRECT - Using accessible components
import { Button, Input, Select } from 'react-aria-components';
// Or: Radix UI, Headless UI, etc.

// WRONG - Missing accessibility
<button onClick={...}>  // May miss keyboard/screen reader support
<input type="text" />   // May miss ARIA support

Card Pattern

// Standard Card
<div className={cn(
  "bg-bg-secondary",
  "border border-border-secondary",
  "rounded-xl",
  "hover:bg-bg-secondary-hover",
  "hover:border-border-primary",
  "transition-colors duration-150"
)}>

// Wrong patterns
<div className="bg-white rounded-lg shadow">  // Hardcoded colors
<div className="bg-gray-100 border-2">        // Wrong tokens