design-system-violation-detector

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:

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

✅ CORRECT:

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

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

✅ CORRECT:

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

❌ VIOLATION:

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

✅ CORRECT:

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

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

✅ CORRECT:

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

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

✅ CORRECT:

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

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

✅ CORRECT:

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

---

6. EFFECTS & TRANSITIONS (WARNING LEVEL)

Rule: Use consistent effects and transitions.

Backdrop Blur (Glassmorphism):

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:

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

✅ CORRECT:

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

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

✅ CORRECT:

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

❌ VIOLATION:

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

✅ CORRECT:

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

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

✅ CORRECT:

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

---

9. COMMON COMPONENT PATTERNS (INFO LEVEL)

Primary Button Pattern:

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

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

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

<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

1. Use Glob to find all React component files:

   src/components/**/*.tsx
   src/components/**/*.jsx
   

2. Exclude test files: **/*.test.tsx, **/__tests__/**
3. If user specifies files, only check those

Phase 2: Component Analysis

For each file:

1. Read file using Read tool
2. Extract className strings from JSX
3. Parse Tailwind classes (split by whitespace)
4. Run violation checks (see checklist below)
5. 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)

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

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

3. Arbitrary Colors Used

   • Scan for: bg-[#, text-[#, border-[#, hex color patterns
   • Flag: All arbitrary color values
   • Suggest: Use Tailwind theme colors

4. 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)

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

6. Spacing Inconsistencies

   • Scan for: p-3, p-4, p-7 on cards
   • Suggest: Use p-5 (cards) or p-6 (containers)

7. Typography Violations

   • Scan for: text-base, text-md, font-bold on buttons/body text
   • Suggest: Use text-sm (body) and font-semibold (emphasis)

8. Missing Transitions

   • Scan for: Interactive elements with hover but no transition
   • Suggest: Add transition-all duration-200

9. Shadow Misuse

   • Scan for: Non-standard shadow classes
   • Suggest: shadow-lg hover:shadow-xl (buttons), shadow-xs (cards)

ℹ️ INFO CHECKS (Consider)

10. Pattern Optimization

    • Detect: Components that could use common patterns
    • Suggest: Refactor to match established patterns

11. 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:

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

1. Add missing dark: variants (follow standard patterns)
2. Replace rounded-lg → rounded-xl on cards/buttons
3. Add transition-all duration-200 to interactive elements
4. 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:

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:

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

2. Quality Gate Integration

Update quality workflow:

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

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

Example 2: Check All Components

User Request:

"Scan all components for design violations"

Skill Actions:

1. Glob src/components/**/*.tsx
2. Exclude test files
3. Analyze each component (42 files)
4. Generate comprehensive report
5. Sort by severity (errors first)
6. Provide summary statistics

Example 3: Check Modified Components

User Request:

"Check design system compliance for components I just changed"

Skill Actions:

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

Example 4: Auto-Fix Mode

User Request:

"Check and fix design violations in Button.tsx"

Skill Actions:

1. Analyze Button.tsx
2. Identify violations
3. Separate auto-fixable vs manual
4. Ask user for permission to auto-fix
5. Apply fixes using Edit tool
6. Re-run check to verify
7. Report remaining manual fixes needed

---

Common Violation Patterns & Fixes

Pattern 1: New Component Without Dark Mode

Before:

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:

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:

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

After:

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

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

After:

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

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

After:

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

---

Output Format

Always structure output as:

1. Summary Statistics

   • Files checked
   • Total violations by severity
   • Quality gate status (PASS/FAIL)

2. Critical Errors (if any)

   • File path and line number
   • Current code
   • Problem description
   • Suggested fix
   • Documentation reference

3. Warnings (if any)

   • Same format as errors

4. Info (if any)

   • Same format as errors

5. Recommendations

   • Priority actions
   • Next steps
   • Links to documentation

6. Auto-Fix Options (if applicable)

   • List of auto-fixable violations
   • Ask for permission to apply fixes

---

Success Criteria

The skill is successful when:

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

---

Limitations & Caveats

1. Dynamic ClassNames: Cannot analyze runtime-generated classes

   // Cannot analyze
   <div className={`bg-${color}-500`}>
   

2. Component Libraries: External component libraries (if added) may have their own patterns

3. Inline Styles: While flagged, inline styles might be necessary for dynamic values

4. Context Required: Some violations need human judgment (e.g., when arbitrary values are justified)

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