Use when validating design system token compliance, detecting visual regressions, or analyzing responsive design consistency across breakpoints and modes
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
1---2name: visual-consistency-validation3description: Use when validating design system token compliance, detecting visual regressions, or analyzing responsive design consistency across breakpoints and modes4---56# Visual Consistency Validation Skill78Systematic approach to validating design system compliance across all breakpoints, modes, and interactive states.910## Core Principle1112**Every violation must be: (1) mapped to a specific token, (2) quantified, (3) severity-categorized, and (4) provided with remediation. No rationalization allowed.**1314## When to Use1516- Validating component compliance against design system tokens17- Detecting visual regressions between baseline and updated designs18- Analyzing responsive design consistency (mobile, tablet, desktop)19- Validating dark mode and alternative state compliance2021## The Three Disciplines2223### 1. Systematic Token Mapping2425Every violation follows this template:26```27Property: [CSS property]28Current: [actual value]29Token: [token name from design system]30Expected: [token value]31Difference: [quantified: pixels, %, hex delta]32```3334### 2. Comprehensive Coverage3536Validate everything:37- [ ] All color properties (text, background, border, shadow, icon)38- [ ] All spacing (padding, margin, gap, position)39- [ ] All typography (size, weight, line-height, letter-spacing)40- [ ] All shapes (radius, borders, shadows)41- [ ] All animations (duration, easing)42- [ ] All breakpoints (mobile, tablet, desktop)43- [ ] All modes (light, dark, high-contrast)44- [ ] All interactive states (default, hover, focus, active, disabled)4546### 3. Severity Categorization4748| Level | When |49|-------|------|50| **CRITICAL** | Accessibility/layout failures (WCAG contrast, broken states, layout shifts) |51| **HIGH** | Token violations with user impact (colors, spacing, typography) |52| **MEDIUM** | Minor deviations (< 10% difference) |53| **LOW** | Very minor (< 5% difference) |5455**Rule:** All WCAG failures → CRITICAL (regardless of context).5657---5859## Red Flags - STOP and Reanalyze6061| Red Flag | What to Do |62|----------|-----------|63| "Close enough" | Measure it. Report every difference. |64| "Desktop is primary" | Analyze all breakpoints equally. |65| "Light mode is primary" | Analyze all modes equally. |66| "Minor refinement" | Categorize by severity and report. |67| "Typical for design systems" | Escalate accessibility failures to CRITICAL. |68| "Not evaluating hover states" | Validate all interactive states. |69| "Acceptable variance" | Quantify and report every deviation. |7071---7273## Validation Checklist7475Before completing analysis:7677- [ ] All visible properties analyzed78- [ ] All violations mapped to specific tokens79- [ ] All differences quantified (pixels, percentages, hex deltas)80- [ ] All breakpoints analyzed (mobile, tablet, desktop)81- [ ] All modes analyzed (light, dark, high-contrast)82- [ ] All interactive states validated83- [ ] Severity categorized for each violation84- [ ] Accessibility violations escalated to CRITICAL85- [ ] Complete remediation (CSS + testing approach) for each violation86- [ ] No violations rationalized away8788---8990## Reference Materials9192Detailed implementation guidance:9394- **[Execution Guide](references/execution-guide.md)** — How visual-consistency-tester implements this skill using Playwright and design tokens95- **[Implementation Patterns](references/implementation-patterns.md)** — Code patterns for token mapping, violation detection, severity calculation, remediation generation
Run npx skillmds@latest add tan-yong-sheng-ai-vision-mcp/visual-consistency-validation in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use when validating design system token compliance, detecting visual regressions, or analyzing responsive design consistency across breakpoints and modes It is listed under Design & Media on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
tan-yong-sheng (@tan-yong-sheng-ai-vision-mcp) published this skill. Their other Agent Skills are listed on their SkillMD profile.
tan-yong-sheng