Design System Violation Detector

Automated detection and enforcement of design system guidelines for React components in the My Prompt Manager Chrome extension.

Purpose

Scan React components (*.tsx, *.jsx) to identify violations of the design system guidelines documented in docs/DESIGN_GUIDELINES.md. Ensure consistency, accessibility, and adherence to the established purple-indigo visual language across all UI components.

When to Use This Skill

Use this skill:

•✅ After creating or modifying any React component
•✅ Before submitting a PR with UI changes
•✅ When reviewing existing components for compliance
•✅ As part of the quality workflow (alongside npm test and npm run lint)
•✅ When onboarding new components from external sources
•✅ During design system refactoring efforts

DO NOT use this skill for:

•❌ Non-UI files (services, utils, hooks without JSX)
•❌ Test files (*.test.tsx)
•❌ Configuration files
•❌ Content scripts without UI components

Design System Rules

1. DARK MODE (CRITICAL - ERROR LEVEL)

Rule: Every color class must have a dark: variant.

Checks:

•bg-* → must have dark:bg-*
•text-* → must have dark:text-*
•border-* → must have dark:border-*
•placeholder-* → must have dark:placeholder-*
•ring-* → must have dark:ring-*

Exceptions:

•bg-transparent, text-inherit, border-none don't need dark variants
•Utility classes like bg-linear-to-r don't need dark variants
•White text on colored backgrounds: text-white (no dark variant needed)

Examples:

❌ VIOLATION:

tsx

<div className="bg-white text-gray-900 border border-purple-200">

✅ CORRECT:

tsx

<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100 border border-purple-200 dark:border-gray-600">

2. COLORS & GRADIENTS (ERROR LEVEL)

Rule: Use only predefined color palette, no arbitrary colors.

Primary Actions:

•Must use: bg-linear-to-r from-purple-600 to-indigo-600
•Hover: hover:from-purple-700 hover:to-indigo-700
•Text: text-white (on gradient backgrounds)

Status Colors:

•Success: bg-green-600, text-green-600
•Error: bg-red-600, text-red-600
•Warning: bg-yellow-600, text-yellow-600
•Info: bg-blue-600, text-blue-600

Text Colors:

•Primary: text-gray-900 dark:text-gray-100
•Secondary: text-gray-600 dark:text-gray-400
•Tertiary: text-gray-500 dark:text-gray-500

Background Colors:

•Page: bg-white dark:bg-gray-900
•Section: bg-gray-50 dark:bg-gray-800
•Card: bg-white/70 dark:bg-gray-800/70 (glassmorphism)

Border Colors:

•Input: border-purple-200 dark:border-gray-600
•Divider: border-purple-100 dark:border-gray-700
•Error: border-red-300 dark:border-red-500

Examples:

❌ VIOLATION:

tsx

<button className="bg-blue-500 text-white">Save</button>

✅ CORRECT:

tsx

<button className="bg-linear-to-r from-purple-600 to-indigo-600 text-white">Save</button>

❌ VIOLATION:

tsx

<div className="bg-[#f3f4f6]">

✅ CORRECT:

tsx

<div className="bg-gray-50 dark:bg-gray-800">

3. BORDER RADIUS (WARNING LEVEL)

Rule: Use consistent border radius values.

Standard Sizes:

•Cards, inputs, buttons: rounded-xl (12px)
•Icons, small elements: rounded-lg (8px)
•Badges, pills: rounded-full

Examples:

⚠️ VIOLATION:

tsx

<div className="bg-white border rounded-lg p-5">

✅ CORRECT:

tsx

<div className="bg-white border rounded-xl p-5">

4. SPACING (WARNING LEVEL)

Rule: Use consistent spacing patterns.

Standard Spacing:

•Cards/sections: p-5
•Containers: p-6
•Button groups: space-x-3
•Vertical stacks: space-y-3 or space-y-4
•Form fields: gap-4

Examples:

⚠️ VIOLATION:

tsx

<div className="p-3 space-x-2">

✅ CORRECT:

tsx

<div className="p-5 space-x-3">

5. TYPOGRAPHY (WARNING LEVEL)

Rule: Use consistent typography scale.

Font Sizes:

•Body text, buttons: text-sm (14px)
•Helper text, badges: text-xs (12px)
•Large headings: text-lg (18px)

Font Weights:

•Emphasis: font-semibold
•Normal: no class (default 400)
•Light: font-light (rare)

Font Family:

•Use system fonts (no custom fonts)
•Applied globally via Tailwind config

Examples:

⚠️ VIOLATION:

tsx

<button className="text-base font-bold">Click me</button>

✅ CORRECT:

tsx

<button className="text-sm font-semibold">Click me</button>

6. EFFECTS & TRANSITIONS (WARNING LEVEL)

Rule: Use consistent effects and transitions.

Backdrop Blur (Glassmorphism):

tsx

className="bg-white/70 dark:bg-gray-800/70 backdrop-blur-sm"

Shadows:

•Buttons: shadow-lg hover:shadow-xl
•Cards: shadow-xs (subtle) or none
•Modals: shadow-xl

Transitions:

•Default: transition-all duration-200
•Color-only: transition-colors duration-200

Examples:

⚠️ VIOLATION:

tsx

<button className="bg-purple-600 hover:bg-purple-700">

✅ CORRECT:

tsx

<button className="bg-purple-600 hover:bg-purple-700 transition-all duration-200">

7. FOCUS STATES (ERROR LEVEL)

Rule: All interactive elements must have predefined focus classes.

Predefined Focus Classes:

•.focus-primary - Primary actions (buttons)
•.focus-secondary - Secondary actions
•.focus-danger - Destructive actions
•.focus-input - Input fields
•.focus-interactive - Links, icon buttons

DO NOT use raw Tailwind focus classes like focus:ring-2 focus:ring-purple-500.

Examples:

❌ VIOLATION:

tsx

<button className="bg-purple-600 focus:ring-2 focus:ring-purple-500">

✅ CORRECT:

tsx

<button className="bg-purple-600 focus-primary">

❌ VIOLATION:

tsx

<input className="border border-gray-300" />

✅ CORRECT:

tsx

<input className="border border-purple-200 dark:border-gray-600 focus-input" />

8. ACCESSIBILITY (ERROR LEVEL)

Rule: Ensure accessibility compliance.

Required Attributes:

•Interactive elements need aria-label or visible label
•Images need alt attribute
•Inputs need associated <label> or aria-label
•Buttons should have descriptive text or aria-label
•Toggles need role="switch" and aria-checked

Semantic HTML:

•Use <button> not <div onClick>
•Use <article> for cards
•Use <time> for dates
•Use <nav> for navigation

Color Contrast:

•Text on background: 4.5:1 minimum (WCAG AA)
•Large text (18px+): 3:1 minimum

Examples:

❌ VIOLATION:

tsx

<div onClick={handleClick} className="cursor-pointer">
  <svg>...</svg>
</div>

✅ CORRECT:

tsx

<button onClick={handleClick} aria-label="Delete prompt" className="focus-interactive">
  <svg>...</svg>
</button>

9. COMMON COMPONENT PATTERNS (INFO LEVEL)

Primary Button Pattern:

tsx

<button className="
  px-6 py-3 text-sm font-semibold text-white
  bg-linear-to-r from-purple-600 to-indigo-600
  rounded-xl hover:from-purple-700 hover:to-indigo-700
  transition-all duration-200 shadow-lg hover:shadow-xl
  disabled:opacity-50 focus-primary
">
  {text}
</button>

Text Input Pattern:

tsx

<input className="
  w-full px-4 py-3
  border border-purple-200 dark:border-gray-600
  rounded-xl focus-input
  bg-white/60 dark:bg-gray-700/60 backdrop-blur-sm
  transition-all duration-200
  text-gray-900 dark:text-gray-100
  placeholder-gray-500 dark:placeholder-gray-400
" />

Card Container Pattern:

tsx

<article className="
  bg-white/70 dark:bg-gray-800/70 backdrop-blur-sm
  border-b border-purple-100 dark:border-gray-700
  p-5 hover:bg-white/90 dark:hover:bg-gray-800/90
  transition-all duration-200
">
  {content}
</article>

Icon Button Pattern:

tsx

<button className="
  p-2 text-gray-400 dark:text-gray-500
  hover:text-purple-600 dark:hover:text-purple-400
  rounded-lg hover:bg-purple-50 dark:hover:bg-purple-900/20
  transition-colors focus-interactive
" aria-label="Action description">
  <svg>...</svg>
</button>

Execution Workflow

Phase 1: File Discovery

•
Use Glob to find all React component files:
code
```
src/components/**/*.tsx
src/components/**/*.jsx
```
•Exclude test files: **/*.test.tsx, **/__tests__/**
•If user specifies files, only check those

Phase 2: Component Analysis

For each file:

•Read file using Read tool
•Extract className strings from JSX
•Parse Tailwind classes (split by whitespace)
•Run violation checks (see checklist below)
•
Collect violations with metadata:
- •File path
- •Line number (if determinable)
- •Severity (ERROR/WARNING/INFO)
- •Rule violated
- •Current code snippet
- •Suggested fix
- •Documentation reference

Phase 3: Violation Detection Checklist

Run these checks in order:

🔴 CRITICAL CHECKS (ERROR - Must Fix)

•
Dark Mode Variants Missing
- •Scan for: bg-white, bg-gray-*, text-gray-*, border-gray-*, border-purple-*
- •Check: Does corresponding dark:* variant exist?
- •Exception: bg-transparent, text-white, border-none
•
Focus States Missing
- •Scan for: <button, <input, <a, role="button"
- •Check: Does it have a .focus-* class?
- •Required: .focus-primary, .focus-input, .focus-interactive, etc.
•
Arbitrary Colors Used
- •Scan for: bg-[#, text-[#, border-[#, hex color patterns
- •Flag: All arbitrary color values
- •Suggest: Use Tailwind theme colors
•
Accessibility Violations
- •Scan for: <button> without text/aria-label
- •Scan for: <img> without alt
- •Scan for: <input> without label/aria-label
- •Scan for: Interactive divs (onClick on <div>)
- •Scan for: Missing role="switch" on toggles

⚠️ WARNING CHECKS (Should Fix)

•
Border Radius Inconsistencies
- •Scan for: rounded-md, rounded-lg on cards/inputs/buttons (Note: rounded-xs doesn't exist in Tailwind v4 - use rounded-sm for small radii)
- •Suggest: Use rounded-xl for standard components, rounded-sm for small UI elements
•
Spacing Inconsistencies
- •Scan for: p-3, p-4, p-7 on cards
- •Suggest: Use p-5 (cards) or p-6 (containers)
•
Typography Violations
- •Scan for: text-base, text-md, font-bold on buttons/body text
- •Suggest: Use text-sm (body) and font-semibold (emphasis)
•
Missing Transitions
- •Scan for: Interactive elements with hover but no transition
- •Suggest: Add transition-all duration-200
•
Shadow Misuse
- •Scan for: Non-standard shadow classes
- •Suggest: shadow-lg hover:shadow-xl (buttons), shadow-xs (cards)

ℹ️ INFO CHECKS (Consider)

•
Pattern Optimization
- •Detect: Components that could use common patterns
- •Suggest: Refactor to match established patterns
•
Glassmorphism Pattern
- •Scan for: bg-white/ without backdrop-blur-sm
- •Suggest: Add backdrop blur for glassmorphism effect

Phase 4: Report Generation

Generate a structured report:

code

═══════════════════════════════════════════════════════════
DESIGN SYSTEM VIOLATION REPORT
═══════════════════════════════════════════════════════════

Files Checked: 42
Components Analyzed: 45

SUMMARY:
  🔴 ERRORS:   12 (Must fix)
  ⚠️  WARNINGS: 8  (Should fix)
  ℹ️  INFO:     3  (Consider)

═══════════════════════════════════════════════════════════
ERRORS (Must Fix)
═══════════════════════════════════════════════════════════

1. Missing Dark Mode Variant
   File: src/components/PromptCard.tsx:45

   Current:
   <div className="bg-white border border-purple-200">

   Problem: Missing dark mode variants for background and border

   Fix:
   <div className="bg-white dark:bg-gray-800 border border-purple-200 dark:border-gray-700">

   Docs: docs/DESIGN_GUIDELINES.md#dark-mode

   ─────────────────────────────────────────────────────────

2. Missing Focus State
   File: src/components/Button.tsx:23

   Current:
   <button className="bg-purple-600 rounded-xl">

   Problem: Interactive element missing focus state

   Fix:
   <button className="bg-purple-600 rounded-xl focus-primary">

   Docs: docs/DESIGN_GUIDELINES.md#focus-states

   ─────────────────────────────────────────────────────────

═══════════════════════════════════════════════════════════
WARNINGS (Should Fix)
═══════════════════════════════════════════════════════════

[Similar format for warnings...]

═══════════════════════════════════════════════════════════
INFO (Consider)
═══════════════════════════════════════════════════════════

[Similar format for info...]

═══════════════════════════════════════════════════════════
RECOMMENDATIONS
═══════════════════════════════════════════════════════════

Priority Actions:
1. Fix all 12 ERRORS before PR submission
2. Address 8 WARNINGS for consistency
3. Review 3 INFO suggestions for optimization

Next Steps:
- Run this check again after fixes: [command to re-run]
- Review design guidelines: docs/DESIGN_GUIDELINES.md
- Check existing components for patterns: src/components/

Quality Gate: ❌ FAILED (12 errors must be fixed)

Phase 5: Auto-Fix Suggestions (Optional)

For certain violations, offer to auto-fix:

Safe Auto-Fixes:

•Add missing dark: variants (follow standard patterns)
•Replace rounded-lg → rounded-xl on cards/buttons
•Add transition-all duration-200 to interactive elements
•Replace raw focus classes with predefined .focus-*

Manual Review Required:

•Color scheme changes (affects branding)
•Layout restructuring (affects functionality)
•Accessibility fixes (need context)

Auto-Fix Workflow:

code

1. Ask user: "Found 8 auto-fixable violations. Apply fixes? (y/n)"
2. If yes:
   - Use Edit tool for each fix
   - Show diff of changes
   - Re-run checks to verify fixes
3. If no:
   - Provide manual fix instructions

Integration with Existing Workflow

1. Manual Check Command

Add to package.json:

json

{
  "scripts": {
    "check-design": "echo 'Run Claude Code skill: design-violation-detector'"
  }
}

2. Quality Gate Integration

Update quality workflow:

bash

# Mandatory checks before commit
npm test                    # ✓ Existing
npm run lint               # ✓ Existing
# Run design check manually via Claude Code skill

3. Pre-PR Checklist

Before submitting PR with UI changes:

• npm test passes
• npm run lint passes
• Design violation check passes (0 errors)
• Warnings addressed or documented
• Accessibility verified

Usage Examples

Example 1: Check Single Component

User Request:

"Check PromptCard.tsx for design violations"

Skill Actions:

•Read src/components/PromptCard.tsx
•Extract and analyze className strings
•Run all violation checks
•Generate focused report for this file
•Suggest fixes with code snippets

Example 2: Check All Components

User Request:

"Scan all components for design violations"

Skill Actions:

•Glob src/components/**/*.tsx
•Exclude test files
•Analyze each component (42 files)
•Generate comprehensive report
•Sort by severity (errors first)
•Provide summary statistics

Example 3: Check Modified Components

User Request:

"Check design system compliance for components I just changed"

Skill Actions:

•Run git diff --name-only to find modified files
•Filter for src/components/**/*.tsx
•Analyze only changed components
•Generate targeted report
•Suggest fixes for new violations

Example 4: Auto-Fix Mode

User Request:

"Check and fix design violations in Button.tsx"

Skill Actions:

•Analyze Button.tsx
•Identify violations
•Separate auto-fixable vs manual
•Ask user for permission to auto-fix
•Apply fixes using Edit tool
•Re-run check to verify
•Report remaining manual fixes needed

Common Violation Patterns & Fixes

Pattern 1: New Component Without Dark Mode

Before:

tsx

const MyComponent = () => (
  <div className="bg-white border border-gray-200 text-gray-900">
    <h2 className="text-lg font-bold">Title</h2>
    <p className="text-gray-600">Description</p>
  </div>
);

After:

tsx

const MyComponent = () => (
  <div className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-700 text-gray-900 dark:text-gray-100">
    <h2 className="text-lg font-bold">Title</h2>
    <p className="text-gray-600 dark:text-gray-400">Description</p>
  </div>
);

Pattern 2: Button Without Focus State

Before:

tsx

<button className="px-6 py-3 bg-purple-600 text-white rounded-xl hover:bg-purple-700">
  Save
</button>

After:

tsx

<button className="px-6 py-3 bg-purple-600 text-white rounded-xl hover:bg-purple-700 transition-all duration-200 focus-primary">
  Save
</button>

Pattern 3: Arbitrary Colors

Before:

tsx

<div className="bg-[#f3f4f6] text-[#1a202c] border-[#e5e7eb]">

After:

tsx

<div className="bg-gray-50 dark:bg-gray-800 text-gray-900 dark:text-gray-100 border-gray-200 dark:border-gray-700">

Pattern 4: Div with onClick

Before:

tsx

<div onClick={handleClick} className="cursor-pointer">
  <TrashIcon />
</div>

After:

tsx

<button onClick={handleClick} aria-label="Delete item" className="focus-interactive">
  <TrashIcon />
</button>

Output Format

Always structure output as:

•
Summary Statistics
- •Files checked
- •Total violations by severity
- •Quality gate status (PASS/FAIL)
•
Critical Errors (if any)
- •File path and line number
- •Current code
- •Problem description
- •Suggested fix
- •Documentation reference
•
Warnings (if any)
- •Same format as errors
•
Info (if any)
- •Same format as errors
•
Recommendations
- •Priority actions
- •Next steps
- •Links to documentation
•
Auto-Fix Options (if applicable)
- •List of auto-fixable violations
- •Ask for permission to apply fixes

Success Criteria

The skill is successful when:

•✅ All design violations are identified
•✅ Specific fixes are provided with code snippets
•✅ Violations are categorized by severity
•✅ Documentation references are included
•✅ Report is actionable (developer knows exactly what to fix)
•✅ Quality gate status is clear (PASS/FAIL)

Limitations & Caveats

•
Dynamic ClassNames: Cannot analyze runtime-generated classes
tsx
```
// Cannot analyze
<div className={`bg-${color}-500`}>
```
•
Component Libraries: External component libraries (if added) may have their own patterns
•
Inline Styles: While flagged, inline styles might be necessary for dynamic values
•
Context Required: Some violations need human judgment (e.g., when arbitrary values are justified)
•
False Positives: Edge cases may trigger false alarms (user should verify)

References

•Design Guidelines: /Users/e0538224/Developer/My-Prompt-Manager/docs/DESIGN_GUIDELINES.md
•Component Catalog: /Users/e0538224/Developer/My-Prompt-Manager/docs/COMPONENTS.md
•Existing Components: /Users/e0538224/Developer/My-Prompt-Manager/src/components/
•Tailwind Config: /Users/e0538224/Developer/My-Prompt-Manager/tailwind.config.js

Implementation Notes

Tools Used:

•Glob: Find component files
•Read: Read component source
•Grep: Search for specific patterns (optional optimization)
•Edit: Apply auto-fixes (if user approves)

Performance:

•Check ~40 components in < 30 seconds
•Provide incremental feedback for large batches
•Cache results for re-checks

Testing:

•Test on known good components (PromptCard, AddPromptForm)
•Test on known violations (create test files)
•Verify auto-fix doesn't break components