check

What this skill does

# Design System Compliance Checker

Audit files for FyrsmithLabs Terminal Elegance design system compliance. This skill identifies violations, reports them with severity levels, and provides auto-fix suggestions for simple issues.

## Supported Standards

- **W3C Design Tokens Community Group (DTCG)** format (2025.10 specification)
- **WCAG 2.2** Level AA compliance
- **Modern CSS** custom properties and component patterns
- **Terminal Elegance** design system v2.0.0

## Tool Integration

This skill integrates with industry-standard tools for comprehensive validation:

| Tool | Purpose | Integration |
|------|---------|-------------|
| **Stylelint** | CSS linting and rule enforcement | Recommends `stylelint-config-standard` rules |
| **axe-core** | Accessibility testing engine | WCAG 2.2 AA compliance checking |
| **Design Token Validator** | DTCG format validation | W3C Design Tokens spec compliance |

### Recommended Stylelint Rules

When violations are found, suggest these Stylelint rules for CI enforcement:

```json
{
  "rules": {
    "color-no-hex": true,
    "declaration-property-value-disallowed-list": {
      "z-index": ["/^(?!var\\(--z-).*/"],
      "font-size": ["/^(?!var\\(--text-|16px).*/"]
    },
    "custom-property-pattern": "^(color|bg|text|space|z|radius|duration|font)-",
    "selector-pseudo-class-no-unknown": [true, { "ignorePseudoClasses": ["focus-visible"] }]
  }
}
```

### axe-core Integration

For automated accessibility testing, recommend:

```javascript
// axe-core configuration for Terminal Elegance
{
  rules: {
    'color-contrast': { enabled: true },
    'focus-visible': { enabled: true },
    'image-alt': { enabled: true },
    'button-name': { enabled: true },
    'link-name': { enabled: true }
  }
}
```

## Invocation

```
/design-check [path] [--fix-suggestions] [--ci] [--format=json|text]
```

- `path` (optional): Specific file or directory to check. Defaults to scanning common locations.
- `--fix-suggestions`: Include auto-fix code snippets for simple violations
- `--ci`: Output in CI-friendly format (non-zero exit on CRITICAL/ERROR)
- `--format`: Output format (default: text)

## Execution Process

### 1. Determine Scope

When invoked:
- If a path argument is provided, check only that file or directory
- If no path, scan these default locations:
  - `static/css/` or `css/` for stylesheets
  - `internal/templates/` or `templates/` for template files
  - `*.md` files in project root for documentation

### 2. Locate Design System Reference

Find the design system documentation:
1. Check `DESIGN_SYSTEM.md` in project root
2. Check `tokens.json` or `design-tokens.json` for DTCG format tokens
3. Check `.claude/plugins/fyrsmithlabs/skills/design-check/references/design-tokens.md`

If no design system found, report error and exit.

### 2a. W3C Design Tokens (DTCG) Validation

If a `tokens.json` file exists, validate against W3C Design Tokens Community Group format (2025.10 specification):

**Token File Structure Validation**
```json
{
  "$schema": "https://design-tokens.github.io/community-group/format/",
  "color": {
    "primary": {
      "$value": "#ea580c",
      "$type": "color",
      "$description": "Primary brand color - burnt orange"
    }
  }
}
```

**DTCG Compliance Checks:**

| Check | Severity | Requirement |
|-------|----------|-------------|
| `$value` property present | ERROR | All tokens must have `$value` |
| `$type` specified | WARNING | Type should be explicit for tooling |
| Valid `$type` values | ERROR | Must be: `color`, `dimension`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `number`, `strokeStyle`, `border`, `transition`, `shadow`, `gradient`, `typography`, `fontStyle` |
| Token naming convention | WARNING | Use kebab-case for token names |
| Hierarchy depth | INFO | Max 4 levels recommended |
| `$description` present | INFO | Helps documentation generation |

**Token Hierarchy Validation:**
```
color/
  primary/       (group)
    base/        (token) -> $value required
    hover/       (token) -> $value required
  accent/        (group)
    base/        (token)
```

**Cross-Platform Token Usage:**
Validate tokens can generate valid output for:
- CSS custom properties
- iOS (Swift/UIKit)
- Android (Kotlin/Compose)
- JavaScript/TypeScript constants

### 3. Run Checks by File Type

Execute file-type-specific checks. Use grep/search to find patterns, then analyze results.

#### CSS Files (.css)

Check for these violations:

**CRITICAL - Hardcoded Colors**
```
Pattern: (?<!:root[^}]*)\b#[0-9a-fA-F]{3,8}\b
Excludes: Inside :root {} or comments
Should be: var(--color-*), var(--bg-*), var(--text-*), var(--border-*)
Note: Use negative lookbehind to exclude :root declarations
```

Known design system hex values (acceptable in :root only):
- Primary: `#ea580c`, `#f97316`, `#9a3412`
- Accent: `#c026d3`, `#d946ef`, `#86198f`
- Backgrounds: `#050505`, `#080808`, `#0a0a0a`, `#111111`, `#161616`
- Text: `#fafafa`, `#a3a3a3`, `#525252`
- Status: `#ef4444`, `#7f1d1d`, `#f59e0b`, `#78350f`, `#22c55e`, `#14532d`, `#3b82f6`, `#1e3a8a`

**ERROR - Hardcoded Spacing**
```
Pattern: (?<!var\(--[^)]*)(margin|padding|gap):\s*[2-9]\d*px
Excludes: 0px, 1px (borders), CSS variable definitions
Should be: var(--space-*)
Note: Use negative lookbehind to exclude var(--*) declarations
```

**ERROR - Hardcoded Font Sizes**
```
Pattern: (?<!var\(--[^)]*)(font-size:\s*(?!16px)\d+(\.\d+)?(px|rem|em))
Excludes: 16px (iOS zoom prevention), CSS variable definitions
Should be: var(--text-*)
Note: Use negative lookbehind to exclude var(--*) declarations
```

**WARNING - Hardcoded Z-Index**
```
Pattern: z-index:\s*\d+
Allowed values: 0, 100 (header special case)
Should be: var(--z-*)
```

**WARNING - Missing Focus States**
```
Check: Interactive elements (button, a, input, select, textarea, [role="button"])
Must have: :focus-visible or :focus styles
```

**WARNING - Non-standard Border Radius**
```
Pattern: border-radius:\s*\d+px
Allowed: 2px, 4px, 8px
Should be: var(--radius-sm), var(--radius-md), var(--radius-lg)
```

**WARNING - Non-standard Durations**
```
Pattern: transition.*\d+ms|animation.*\d+ms
Allowed: 150ms, 200ms, 0.01ms (reduced motion)
Should be: var(--duration-fast), var(--duration-normal)
```

**INFO - Decorative Animation Keywords**
```
Pattern: @keyframes|animation-name
Flag: Potential violation of minimal motion philosophy
```

**CRITICAL - CSS Custom Properties Audit**
```
Check: All var(--*) references resolve to defined properties
Pattern: var\(--[a-z-]+\) without matching :root definition
Auto-fix: Suggest nearest matching token
```

**ERROR - Dark Mode Support**
```
Check: @media (prefers-color-scheme: dark) or .dark class support
Pattern: Color tokens without dark mode variants
Should have: Both light and dark values defined
```

**WARNING - Component Library Consistency**
```
Check: Repeated patterns that should be componentized
Pattern: Same CSS block (>3 properties) appearing 3+ times
Suggest: Extract to shared component class
```

**WARNING - Modern CSS Compatibility**
```
Check: Browser support for used features
Pattern: Features requiring fallbacks (container queries, :has(), etc.)
Suggest: Add @supports or fallback values
```

#### Template Files (.templ, .html)

**ERROR - Missing Alt Text**
```
Pattern: <img[^>]*(?!alt=)[^>]*>
Should have: alt="descriptive text"
```

**ERROR - Non-semantic Structure**
```
Check for: <div> used where semantic element appropriate
Suggest: <header>, <nav>, <main>, <section>, <article>, <aside>, <footer>
```

**WARNING - Missing ARIA Labels**
```
Check: Interactive elements without visible text
Pattern: <button[^>]*>[^<]*<\/button> (empty or icon-only)
Should have: aria-label="description"
```

**WARNING - Missing Role Attributes**
```
Check: Custom interactive elements
Pattern: onclick without role="button"
```

**INFO - Form Accessibility**
```
Check: <input>, <select>, <textarea>
Should have: Associated <label> or aria-label
```

### WCAG 2.2 Accessibility Checks