williamzujkowski/UX Design System Validator

Purpose & When-To-Use

Trigger conditions:

• Design system audit or compliance review requested
• WCAG 2.2 AA/AAA compliance verification needed before launch
• Component library validation for accessibility and consistency
• Responsive design breakpoint review across devices
• Design token governance assessment
• Preparation for European Accessibility Act (EAA) 2025 compliance

Use this skill when:

• You need to validate that a design system meets accessibility standards
• Component libraries require consistency checks across platforms
• Design tokens need validation against brand guidelines
• Responsive design patterns must work across breakpoints
• Cross-platform design systems (web, iOS, Android) need alignment

Do NOT use when:

• Only generating new designs (use design tools instead)
• Conducting user research or usability testing
• Implementing code (this validates design artifacts, not implementation)

Pre-Checks

Time normalization:

NOW_ET = 2025-10-25T21:30:36-04:00 (NIST/time.gov semantics)

Required inputs validation:

1. At least one of: design_system_url, component_library, or design_tokens must be provided
2. If target_wcag_level specified, must be "AA" or "AAA"
3. If platforms array provided, validate against supported platforms: web, iOS, Android, react-native, flutter]

Source freshness checks:

• WCAG 2.2 is current standard (released October 2023, accessed 2025-10-25)
• Material Design 3 Expressive is latest version (2025, accessed 2025-10-25)
• Apple HIG unified guidelines current (2025 Liquid Glass update, accessed 2025-10-25)
• W3C Design Tokens Community Group spec is active standard (accessed 2025-10-25)

Abort conditions:

• No design artifacts provided for validation
• Design system format is proprietary and cannot be parsed
• Requested WCAG level is invalid

Procedure

T1: Quick Accessibility & Token Scan (≤2k tokens)

Fast-path for 80% of cases: basic WCAG and token checks

1. Parse design artifacts:

• Extract component definitions from provided source
• Load design tokens (JSON/YAML) if available
• Identify platform-specific guidelines (Material/HIG/custom)

1. Run automated WCAG 2.2 Level AA checks:

• Color contrast ratios (1.4.3 Contrast Minimum: 4.5:1 text, 3:1 large text)
• Focus indicators (2.4.7 Focus Visible, 2.4.11 Focus Not Obscured Minimum)
• Touch target sizes (2.5.8 Target Size Minimum: 24x24 CSS pixels)
• Text spacing (1.4.12 Text Spacing)
• Dragging alternatives (2.5.7 Dragging Movements)

1. Design token consistency scan:

• Verify token naming follows W3C spec (color, dimension, number, typography)
• Check for conflicting token values across files
• Validate semantic token references (e.g., color.button.primary references color.brand.blue)

1. Generate quick report:

• Critical violations (blockers for AA compliance)
• Token inconsistencies count
• Compliance score estimate
• Top 3 remediation priorities

Output: JSON summary with violation counts and quick-win recommendations.

Decision point: If critical violations > 5 OR user requests comprehensive audit → proceed to T2.

T2: Extended Design System Validation (≤6k tokens)

Includes T1 + responsive design + component library audit + design token validation

1. Responsive design pattern analysis:

• Verify breakpoints follow industry standards (320px, 768px, 1024px, 1440px)
• Check fluid typography scales (1rem base, 1.25 scale ratio)
• Validate touch-friendly controls across devices (min 44x44 iOS, 48x48 Material)
• Test grid system consistency (12-column, 8pt/4pt spacing grid)
• Review viewport meta tags and fluid layout patterns

1. Component library deep audit:

• Buttons: States (default, hover, focus, active, disabled), ARIA labels, keyboard navigation
• Forms: Labels, error messages, required field indicators, autocomplete attributes
• Navigation: Skip links, landmark roles, breadcrumb semantics
• Modals/Dialogs: Focus trapping, ESC key handling, ARIA roles (dialog, alertdialog)
• Images: Alt text guidance, decorative vs informative classification
• Cross-reference against Material Design 3 and Apple HIG patterns (accessed 2025-10-25)

1. Design token validation (W3C spec compliance):

• Type validation: Ensure color tokens use hex/rgb/hsl, dimensions use px/rem/em
• Semantic layering: Verify 3-tier structure (core → semantic → component)
• Accessibility tokens: Check contrast tokens meet WCAG thresholds
• Documentation: Validate each token has use-case and constraints
• Version control: Confirm tokens are versioned and change-logged
• Reference: W3C Design Tokens Community Group (accessed 2025-10-25)

1. WCAG 2.2 Level AA comprehensive check:

• All 50 Level A criteria + 20 Level AA criteria
• New 2.2 criteria: Focus Not Obscured (Minimum), Focus Appearance, Dragging Movements, Target Size (Minimum), Consistent Help, Redundant Entry, Accessible Authentication (Minimum)
• Reference: WCAG 2.2 (https://w3.org/WAI/WCAG22, accessed 2025-10-25)

1. Generate detailed remediation plan:

• Prioritize by impact (critical/high/medium/low)
• Group by category (color, typography, layout, interaction)
• Include code snippets or design token changes
• Estimate effort (quick win / medium / complex)
• Link to authoritative sources (WCAG, Material, HIG)

Output: Comprehensive validation report with prioritized remediation plan.

Decision point: If AAA compliance requested OR multi-platform alignment needed → optionally proceed to T3 (not implemented in this T2 skill).

T3: Not implemented (skill is T2)

T3 would include: full AAA audit, automated testing integration, cross-platform design system federation, advanced token tooling recommendations.

Decision Rules

Ambiguity thresholds:

• If color contrast is 4.4:1 (just below 4.5:1 threshold), flag as WARNING not ERROR
• If component has partial ARIA support, detail what's missing vs blanket fail
• If design tokens use custom naming (not W3C spec), flag as INFO not ERROR

Severity classification:

• CRITICAL: WCAG Level A violations (e.g., missing alt text, no keyboard access)
• HIGH: WCAG Level AA violations (e.g., contrast 3.5:1 for text, focus not visible)
• MEDIUM: Design token inconsistencies, non-standard breakpoints
• LOW: Documentation gaps, minor naming convention deviations
• INFO: Recommendations for AAA compliance, advanced patterns

Abort/stop conditions:

• Cannot parse design system format after 3 attempts → return error with format requirements
• Design system has 0 components defined → return error "No components found to validate"
• WCAG checks yield 0 results → likely parsing issue, return diagnostic report

Output Contract

Required fields (JSON schema):

json
{
  "validation_report": {
    "timestamp": "ISO-8601 timestamp",
    "wcag_level_tested": "AA | AAA",
    "overall_compliance_score": "0-100 integer",
    "dimensions": {
      "accessibility": {"score": 0-100, "violations": []},
      "responsive_design": {"score": 0-100, "issues": []},
      "design_tokens": {"score": 0-100, "inconsistencies": []},
      "component_library": {"score": 0-100, "findings": []}
    }
  },
  "wcag_violations": [
    {
      "criterion": "1.4.3 Contrast (Minimum)",
      "level": "AA",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW",
      "component": "Primary Button",
      "description": "Text contrast is 3.2:1, needs 4.5:1",
      "remediation": "Increase text color darkness or lighten background",
      "wcag_reference": "https://w3.org/WAI/WCAG22/Understanding/contrast-minimum"
    }
  ],
  "token_inconsistencies": [
    {
      "token_name": "color.button.primary",
      "issue": "Defined as #FF5733 in tokens.json but #FF5734 in components.css",
      "recommendation": "Synchronize to single source of truth"
    }
  ],
  "remediation_plan": {
    "quick_wins": ["Fix button contrast", "Add focus indicators"],
    "prioritized_actions": [
      {
        "priority": "CRITICAL | HIGH | MEDIUM | LOW",
        "category": "accessibility | responsive | tokens | components",
        "action": "Description of fix needed",
        "effort": "quick | medium | complex",
        "references": ["URL to WCAG/Material/HIG"]
      }
    ]
  }
}

Types:

• validation_report: Object (required)
• wcag_violations: Array of objects (required, may be empty)
• token_inconsistencies: Array of objects (required, may be empty)
• remediation_plan: Object (required)
• compliance_score: Integer 0-100 per dimension (required)

Examples

Example: Basic WCAG validation (T1)

json
INPUT:
{
  "design_system_url": "https://example.com/design-system",
  "target_wcag_level": "AA",
  "platforms": ["web"]
}

OUTPUT:
{
  "validation_report": {
    "timestamp": "2025-10-25T21:30:36-04:00",
    "wcag_level_tested": "AA",
    "overall_compliance_score": 72,
    "dimensions": {
      "accessibility": {"score": 65, "violations": 8}
    }
  },
  "wcag_violations": [
    {
      "criterion": "1.4.3 Contrast (Minimum)",
      "level": "AA",
      "severity": "HIGH",
      "component": "Secondary Button",
      "description": "Contrast ratio 3.8:1 (need 4.5:1)"
    }
  ],
  "remediation_plan": {
    "quick_wins": ["Darken secondary button text"]
  }
}

Quality Gates

Token budgets (enforced):

• T1 procedure: ≤2000 tokens (quick scan + report generation)
• T2 procedure: ≤6000 tokens (comprehensive audit + detailed remediation)
• T3 procedure: Not implemented (would be ≤12000 tokens)

Safety checks:

• Do not execute code from design system; parse declaratively only
• Do not store PII from design artifacts
• Redact any API keys or secrets found in token files (flag as security issue)

Auditability:

• Log all WCAG criteria checked with timestamps
• Include source references (URL + access date) for every guideline cited
• Version design system artifacts analyzed (git SHA, file hash, or timestamp)

Determinism:

• Same design system input → same validation output (no randomness)
• WCAG criteria are deterministic (contrast calculation, token parsing)
• If using LLM for component classification, use temperature=0

Quality metrics:

• Validation must complete in <30 seconds for T1, <2 minutes for T2
• False positive rate <5% (manual spot-check 20 random findings)
• Coverage: All WCAG 2.2 Level AA criteria (70 total success criteria)

Resources

Standards and specifications:

• WCAG 2.2 Guidelines: https://w3.org/WAI/WCAG22 (accessed 2025-10-25T21:30:36-04:00)
• WCAG 2.2 Understanding Docs: https://w3.org/WAI/WCAG22/Understanding (accessed 2025-10-25T21:30:36-04:00)
• W3C Design Tokens Community Group: https://github.com/design-tokens/community-group (accessed 2025-10-25T21:30:36-04:00)
• European Accessibility Act (EAA): https://ec.europa.eu/social/main.jsp?catId=1202 (accessed 2025-10-25T21:30:36-04:00)

Design system references:

• Material Design 3: https://m3.material.io (accessed 2025-10-25T21:30:36-04:00)
• Material Design 3 Expressive: https://m3.material.io/blog/material-3-expressive (accessed 2025-10-25T21:30:36-04:00)
• Apple Human Interface Guidelines: https://developer.apple.com/design/human-interface-guidelines (accessed 2025-10-25T21:30:36-04:00)
• Design Systems Repo: https://designsystemsrepo.com (accessed 2025-10-25T21:30:36-04:00)

Tools and validators:

• WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker (accessed 2025-10-25T21:30:36-04:00)
• axe DevTools: https://deque.com/axe/devtools (accessed 2025-10-25T21:30:36-04:00)
• Style Dictionary (design tokens): https://amzn.github.io/style-dictionary (accessed 2025-10-25T21:30:36-04:00)
• Figma Tokens Plugin: https://tokens.studio (accessed 2025-10-25T21:30:36-04:00)

Additional reading:

• WCAG 2.2 What's New: https://accessibe.com/blog/knowledgebase/wcag-two-point-two (accessed 2025-10-25T21:30:36-04:00)
• Design Tokens Best Practices 2025: https://howik.com/design-tokens-best-practices (accessed 2025-10-25T21:30:36-04:00)