Design System Compliance Checker

Name: check
Rating: 76
Author: fyrsmithlabs

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

code

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

•Check DESIGN_SYSTEM.md in project root
•Check tokens.json or design-tokens.json for DTCG format tokens
•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:

code

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

code

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

code

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

code

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

code

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

WARNING - Missing Focus States

code

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

WARNING - Non-standard Border Radius

code

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

code

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

code

Pattern: @keyframes|animation-name
Flag: Potential violation of minimal motion philosophy

CRITICAL - CSS Custom Properties Audit

code

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

code

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

code

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

code

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

code

Pattern: <img[^>]*(?!alt=)[^>]*>
Should have: alt="descriptive text"

ERROR - Non-semantic Structure

code

Check for: <div> used where semantic element appropriate
Suggest: <header>, <nav>, <main>, <section>, <article>, <aside>, <footer>

WARNING - Missing ARIA Labels

code

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

WARNING - Missing Role Attributes

code

Check: Custom interactive elements
Pattern: onclick without role="button"

INFO - Form Accessibility

code

Check: <input>, <select>, <textarea>
Should have: Associated <label> or aria-label

WCAG 2.2 Accessibility Checks (a11y)

These checks ensure WCAG 2.2 Level AA compliance:

Color & Contrast

CRITICAL - Color Contrast (WCAG 1.4.3)

code

Check: Text color against background color
Normal text: Minimum 4.5:1 contrast ratio
Large text (18px+ or 14px bold): Minimum 3:1 contrast ratio
Tool: Use axe-core or color-contrast npm package

ERROR - Non-Text Contrast (WCAG 1.4.11)

code

Check: UI components and graphical objects
Minimum: 3:1 contrast ratio against adjacent colors
Applies to: Borders, icons, focus indicators, form controls

WARNING - Focus Indicator Contrast (WCAG 2.4.13 - New in 2.2)

code

Check: Focus indicators must have 3:1 contrast
Pattern: :focus-visible styles without sufficient contrast
Should have: Visible 2px+ outline or equivalent

Keyboard & Focus

CRITICAL - Focus Visible (WCAG 2.4.7)

code

Check: All interactive elements have visible focus state
Pattern: outline: none without alternative focus style
Auto-fix: Add outline: 2px solid var(--color-primary); outline-offset: 2px;

ERROR - Focus Not Obscured (WCAG 2.4.11 - New in 2.2)

code

Check: Focused element not hidden by sticky headers/footers
Pattern: position: sticky or position: fixed elements
Should have: Scroll margin or z-index management

ERROR - Target Size (WCAG 2.5.8 - New in 2.2)

code

Check: Interactive targets minimum 24x24 CSS pixels
Pattern: button, a, input with smaller dimensions
Exceptions: Inline links in text, browser-rendered controls
Auto-fix: min-width: 44px; min-height: 44px; (recommended)

ARIA & Semantics

CRITICAL - ARIA Valid Values (WCAG 4.1.2)

code

Check: aria-* attributes have valid values
Pattern: aria-expanded="yes" (should be "true")
Pattern: aria-level="high" (should be number)

ERROR - ARIA Hidden Focus (WCAG 4.1.2)

code

Check: Elements with aria-hidden="true" not focusable
Pattern: <div aria-hidden="true"><button>...</button></div>
Auto-fix: Add tabindex="-1" to focusable descendants

WARNING - Redundant ARIA (WCAG 4.1.2)

code

Check: ARIA roles that duplicate native semantics
Pattern: <button role="button">
Pattern: <nav role="navigation">
Auto-fix: Remove redundant role attribute

Motion & Animation

ERROR - Motion Preference (WCAG 2.3.3)

code

Check: Animations respect prefers-reduced-motion
Pattern: @keyframes or transition without media query check
Should have: @media (prefers-reduced-motion: reduce) { animation: none; }
Auto-fix: Wrap animations in motion preference query

3a. Terminal Elegance Specific Checks

Brand Color Validation

CRITICAL - Primary Color Context

code

var(--color-primary) = #ea580c
Usage: CTAs, active states, links, primary actions
Violation: Using accent color for primary actions

ERROR - Background Hierarchy

code

Layer order (darkest to lightest):
  Void (#050505) < Base (#080808) < Surface (#0a0a0a) < Elevated (#111111) < Overlay (#161616)
Check: Proper z-order layering maintained

Typography Scale Compliance

ERROR - Font Size Validation

code

Allowed: 12px, 14px, 16px, 18px, 20px, 24px, 32px, 44px, 56px
Use: var(--text-xs) through var(--text-5xl)
Violation: 15px, 22px, or other off-scale values

Spacing System Adherence

ERROR - 4px Grid Compliance

code

Allowed: 4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 80, 96 (pixels)
Use: var(--space-1) through var(--space-24)
Violation: 10px, 15px, 18px, or other off-grid values

Animation/Transition Standards

WARNING - Duration Values

code

Allowed: 0ms, 150ms, 200ms, 300ms
Use: var(--duration-instant|fast|normal|slow)

WARNING - Easing Functions

code

Use: var(--ease-out|ease-in|ease-in-out)
Exception: linear for progress indicators

Documentation Files (.md)

ERROR - Brand Name Inconsistency

code

Incorrect: "Fyrsmith Labs", "fyrsmithlabs", "fyrsmith-labs", "Fyrsmith labs"
Correct: "FyrsmithLabs" (PascalCase, one word)

WARNING - Undocumented Color References

code

Pattern: #[0-9a-fA-F]{6} not in design system
Pattern: Color names like "orange", "purple" without context

INFO - Design Token References

code

Check: References to specific pixel values
Suggest: Reference design token names instead

4. Generate Report

Output format:

code

================================================================================
                    DESIGN SYSTEM COMPLIANCE REPORT
================================================================================
Project: [project name]
Checked: [timestamp]
Scope: [path or "default scan"]
Design System: Terminal Elegance v2.0.0

--------------------------------------------------------------------------------
SUMMARY
--------------------------------------------------------------------------------
Files Scanned: [count]
  - CSS: [count]
  - Templates: [count]
  - Documentation: [count]

Violations Found: [total]
  - Critical: [count]
  - Error: [count]
  - Warning: [count]
  - Info: [count]

CI Status: [PASS/FAIL] (FAIL if Critical > 0 or Error > 0)

--------------------------------------------------------------------------------
VIOLATIONS BY FILE
--------------------------------------------------------------------------------

[filename.css]
  Line [N]: [CRITICAL] Hardcoded color #ea580c
            Found: background: #ea580c;
            Should be: background: var(--color-primary);
            Auto-fix: Replace #ea580c with var(--color-primary)

  Line [N]: [ERROR] Hardcoded spacing
            Found: padding: 24px;
            Should be: padding: var(--space-6);
            Auto-fix: Replace 24px with var(--space-6)

  Line [N]: [WARNING] Non-standard z-index
            Found: z-index: 999;
            Should be: var(--z-modal) or similar

[filename.templ]
  Line [N]: [ERROR] Missing alt text on image
            Found: <img src="/logo.png">
            Should be: <img src="/logo.png" alt="FyrsmithLabs logo">
            Auto-fix: Add alt="" attribute (fill in description)

  Line [N]: [WARNING] Missing aria-label on icon button
            Found: <button><svg>...</svg></button>
            Should be: <button aria-label="Close menu"><svg>...</svg></button>

[README.md]
  Line [N]: [ERROR] Brand name inconsistency
            Found: "Fyrsmith Labs"
            Should be: "FyrsmithLabs"

--------------------------------------------------------------------------------
AUTO-FIX SUGGESTIONS (--fix-suggestions)
--------------------------------------------------------------------------------
The following violations have auto-fix suggestions available:

1. [filename.css:15] Replace: background: #ea580c;
                     With:    background: var(--color-primary);

2. [filename.css:42] Replace: padding: 24px;
                     With:    padding: var(--space-6);

3. [filename.css:78] Replace: outline: none;
                     With:    outline: 2px solid var(--color-primary);
                              outline-offset: 2px;

To apply: Review each suggestion and update manually, or use Stylelint --fix

--------------------------------------------------------------------------------
CI PIPELINE INTEGRATION
--------------------------------------------------------------------------------
Exit code: [0 = pass, 1 = fail]

For GitHub Actions:
  - name: Design System Check
    run: npx @fyrsmithlabs/design-check --ci
    continue-on-error: false

For GitLab CI:
  design-check:
    script: npx @fyrsmithlabs/design-check --ci --format=json

--------------------------------------------------------------------------------
DESIGN TOKEN QUICK REFERENCE
--------------------------------------------------------------------------------
Colors:
  --color-primary: #ea580c (burnt orange)
  --color-accent: #c026d3 (fuchsia)
  --bg-void: #050505 (deepest background)
  --text-primary: #fafafa (main text)

Spacing (4px grid):
  --space-1: 4px   --space-6: 24px   --space-16: 64px
  --space-2: 8px   --space-8: 32px   --space-20: 80px
  --space-4: 16px  --space-12: 48px  --space-24: 96px

Font Sizes:
  --text-xs: 12px  --text-lg: 18px   --text-3xl: 32px
  --text-sm: 14px  --text-xl: 20px   --text-4xl: 44px
  --text-base: 16px --text-2xl: 24px --text-5xl: 56px

Z-Index Scale:
  --z-dropdown: 10  --z-modal: 50
  --z-sticky: 20    --z-popover: 60
  --z-fixed: 30     --z-tooltip: 70

================================================================================

4a. JSON Output Format (--format=json)

For CI integration and tooling:

json

{
  "project": "project-name",
  "timestamp": "2025-01-28T12:00:00Z",
  "designSystem": "Terminal Elegance v2.0.0",
  "summary": {
    "filesScanned": 15,
    "violations": {
      "critical": 2,
      "error": 5,
      "warning": 8,
      "info": 3
    },
    "pass": false
  },
  "violations": [
    {
      "file": "static/css/main.css",
      "line": 15,
      "severity": "critical",
      "rule": "hardcoded-color",
      "found": "background: #ea580c;",
      "expected": "background: var(--color-primary);",
      "autoFix": {
        "available": true,
        "replacement": "var(--color-primary)"
      }
    }
  ],
  "wcag": {
    "level": "AA",
    "violations": ["1.4.3", "2.4.7"]
  }
}

5. Severity Definitions

Severity	Meaning	Action Required	CI Behavior
CRITICAL	Direct design system violation affecting brand consistency	Must fix before merge	Fails build
ERROR	Accessibility or maintainability issue	Should fix promptly	Fails build
WARNING	Deviation from best practices	Consider fixing	Warning only
INFO	Suggestion for improvement	Optional	Informational

Implementation Notes

To perform the check:

•Use Glob to find files matching patterns
•Use Read to examine file contents
•Use Grep to search for violation patterns
•Compile findings into structured report
•Output report to user

Do NOT modify any files. This is a report-only tool (auto-fix suggestions are advisory).

CI Pipeline Integration

GitHub Actions

yaml

name: Design System Check
on: [push, pull_request]

jobs:
  design-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Design System Check
        run: |
          # Invoke via Claude Code or custom script
          npx @fyrsmithlabs/design-check --ci --format=json > report.json
      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: design-system-report
          path: report.json

GitLab CI

yaml

design-check:
  stage: lint
  script:
    - npx @fyrsmithlabs/design-check --ci
  allow_failure: false
  artifacts:
    reports:
      codequality: design-report.json

Pre-commit Hook

bash

#!/bin/bash
# .git/hooks/pre-commit
files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(css|templ|html|md)$')
if [ -n "$files" ]; then
  npx @fyrsmithlabs/design-check $files --ci
  exit $?
fi

Cross-Product Scope

This skill applies to all FyrsmithLabs products:

•Website (/website/): Go + Templ, single CSS file
•DevPilot (future): Electron/React, may have different file structure
•Other products: Adapt file patterns as needed

When checking a new product, first identify:

•CSS/styling file locations
•Template/component file locations
•Documentation locations

Reference

Full design system documentation: DESIGN_SYSTEM.md in project root.

Design token quick reference: See references/design-tokens.md in this skill directory.

W3C Design Tokens specification: https://design-tokens.github.io/community-group/format/

WCAG 2.2 guidelines: https://www.w3.org/TR/WCAG22/

axe-core rules: https://dequeuniversity.com/rules/axe/