visual-consistency-validation

name	visual-consistency-validation
description	Use when validating design system token compliance, detecting visual regressions, or analyzing responsive design consistency across breakpoints and modes

Visual Consistency Validation Skill

Systematic approach to validating design system compliance across all breakpoints, modes, and interactive states.

Core Principle

Every violation must be: (1) mapped to a specific token, (2) quantified, (3) severity-categorized, and (4) provided with remediation. No rationalization allowed.

When to Use

• Validating component compliance against design system tokens
• Detecting visual regressions between baseline and updated designs
• Analyzing responsive design consistency (mobile, tablet, desktop)
• Validating dark mode and alternative state compliance

The Three Disciplines

1. Systematic Token Mapping

Every violation follows this template:

Property: [CSS property]
Current: [actual value]
Token: [token name from design system]
Expected: [token value]
Difference: [quantified: pixels, %, hex delta]

2. Comprehensive Coverage

Validate everything:

• All color properties (text, background, border, shadow, icon)
• All spacing (padding, margin, gap, position)
• All typography (size, weight, line-height, letter-spacing)
• All shapes (radius, borders, shadows)
• All animations (duration, easing)
• All breakpoints (mobile, tablet, desktop)
• All modes (light, dark, high-contrast)
• All interactive states (default, hover, focus, active, disabled)

3. Severity Categorization

Level	When
CRITICAL	Accessibility/layout failures (WCAG contrast, broken states, layout shifts)
HIGH	Token violations with user impact (colors, spacing, typography)
MEDIUM	Minor deviations (< 10% difference)
LOW	Very minor (< 5% difference)

Rule: All WCAG failures → CRITICAL (regardless of context).

---

Red Flags - STOP and Reanalyze

Red Flag	What to Do
"Close enough"	Measure it. Report every difference.
"Desktop is primary"	Analyze all breakpoints equally.
"Light mode is primary"	Analyze all modes equally.
"Minor refinement"	Categorize by severity and report.
"Typical for design systems"	Escalate accessibility failures to CRITICAL.
"Not evaluating hover states"	Validate all interactive states.
"Acceptable variance"	Quantify and report every deviation.

---

Validation Checklist

Before completing analysis:

• All visible properties analyzed
• All violations mapped to specific tokens
• All differences quantified (pixels, percentages, hex deltas)
• All breakpoints analyzed (mobile, tablet, desktop)
• All modes analyzed (light, dark, high-contrast)
• All interactive states validated
• Severity categorized for each violation
• Accessibility violations escalated to CRITICAL
• Complete remediation (CSS + testing approach) for each violation
• No violations rationalized away

---

Reference Materials

Detailed implementation guidance:

• Execution Guide — How visual-consistency-tester implements this skill using Playwright and design tokens
• Implementation Patterns — Code patterns for token mapping, violation detection, severity calculation, remediation generation