/design-score

description: "Quantitative 0–100 design quality score across Accessibility, Usability, Visual Quality, and Token Compliance."
argument-hint: "[url | file-path | nodeId | --screenshot <path>]"
allowed-tools: ["Read", "Glob", "Bash", "mcp__plugin_playwright_playwright__browser_navigate", "mcp__plugin_playwright_playwright__browser_take_screenshot", "mcp__plugin_playwright_playwright__browser_snapshot"]

/design-score

Score a design across four dimensions: Accessibility (25pts), Usability (25pts), Visual Quality (25pts), Token Compliance (25pts). Total: 0–100.

Scoring Model

Read `${CLAUDE_PLUGIN_ROOT}/skills/design/references/ux-researcher.md` — focus on "Nielsen's Heuristics" and "WCAG AA Checklist" sections before scoring.

Check for `.naksha/project.json` (search up to 3 directory levels). If found, read:

• **v4 fields**: `brand.primary`, `brand.secondary`, `brand.font`, and `tokenFormat` for Token Compliance scoring context.
• **v5 fields** (if present — all optional):
• `constraints.grid` → use as the expected spacing unit. In Token Compliance, check all spacing values against this grid.
• `constraints.min_contrast_ratio` → use as the required contrast ratio in Accessibility (overrides the default 4.5:1 if set higher).
• `constraints.accessibility_target` → `"WCAG AAA"` sets contrast floor to 7:1 for Accessibility scoring.
• `constraints.breakpoints` → in Token Compliance, verify responsive breakpoints match these values.
• `constraints.max_content_width` → flag if any container exceeds this.
• `component_patterns` → in Token Compliance, check that components named in patterns use the recorded structure (padding, radius, border matches the description).
• `browser_findings` (5 most recent, `mode: "inspect"` entries) → prior design-score snapshots give baseline context. If a prior score exists, note delta: "Previously {N}/100 on {date}."

Dimension 1: Accessibility (0–25 pts)

Score each criterion with partial credit proportional to how many elements pass:

| Criterion | Max | Score | |-----------|-----|-------| | Primary text contrast ≥ 4.5:1; large text ≥ 3:1 (WCAG SC 1.4.3) | 6 | | | UI component contrast ≥ 3:1 — buttons, inputs, focus rings (SC 1.4.11) | 4 | | | All interactive elements have visible focus state (SC 2.4.7) | 4 | | | Touch targets ≥ 44×44px on mobile interactive elements (SC 2.5.5) | 4 | | | No information conveyed by color alone (SC 1.4.1) | 4 | | | Form inputs have programmatic labels, not placeholder-only (SC 1.3.1) | 3 | |

Dimension 2: Usability (0–25 pts)

Score each of Nielsen's 10 heuristics 0–3:

• **3** = Pass: design consistently applies this principle
• **2** = Minor issue: mostly works, 1–2 friction points
• **1** = Major issue: frequent violations affecting most users
• **0** = Critical fail: heuristic is systematically violated

| # | Heuristic | Score (0–3) | |---|-----------|------------| | 1 | Visibility of system status | | | 2 | Match between system and real world | | | 3 | User control and freedom | | | 4 | Consistency and standards | | | 5 | Error prevention | | | 6 | Recognition rather than recall | | | 7 | Flexibility and efficiency of use | | | 8 | Aesthetic and minimalist design | | | 9 | Help users recognize, diagnose, and recover from errors | | | 10 | Help and documentation | |

Usability score = `round((sum / 30) × 25)`

Dimension 3: Visual Quality (0–25 pts)

Score each sub-criterion 0–5:

• **5** = Excellent: consistent, intentional, high craft
• **3–4** = Good: mostly consistent with minor lapses
• **1–2** = Weak: noticeable inconsistencies
• **0** = Poor: systematic problem

| Sub-criterion | Max | Score | |---------------|-----|-------| | Spacing consistency (8pt grid or consistent scale; no arbitrary values) | 5 | | | Typography hierarchy (H1/H2/body visually distinct in size and weight) | 5 | | | Color usage (limited palette, harmonious, brand-consistent) | 5 | | | Whitespace and visual noise (breathing room; no clutter; clear focus) | 5 | | | Primary action prominence (CTA clearly dominant over secondary actions) | 5 | |

Dimension 4: Token Compliance (0–25 pts)

**If `.naksha/project.json` exists** (check `tokenFormat`, `brand.primary`, `brand.font`):

| Sub-criterion | Max | Score | |---------------|-----|-------| | Color values from token system — no raw hex/rgb/hsl | 5 | | | Typography from token system — no hardcoded font-family or arbitrary px sizes | 5 | | | Spacing from token system — values on expected grid scale (use `constraints.grid` if set, else 8pt default) | 5 | | | Component variants consistent — same border-radius, padding across similar components (cross-check against `component_patterns` if set) | 5 | | | Interactive states consistent — hover/focus/active applied uniformly | 5 | |

**v5 scoring enhancements (apply when v5 constraints are present):**

• If `constraints.grid` is set: the Spacing sub-criterion checks against *that* grid unit, not the default 8pt. A `4px` grid means valid values are 4/8/12/16/20/24/28/32…; flag others.
• If `constraints.accessibility_target` is `"WCAG AAA"`: the Accessibility contrast criterion requires 7:1, not 4.5:1. Adjust the 6pt primary contrast criterion accordingly.
• If `component_patterns` is set: for each pattern entry, check the scored component. Full 5pts only if the component matches the recorded description (bg, border, radius, padding). Partial credit for partial match.
• If `browser_findings` has prior `score` mode entries for this URL: show score delta at the top of the output.

**If no project config:** Score visual consistency instead (same patterns used for same purposes throughout the design).

Input Handling

**URL:** Use `browser_navigate` to load the page, `browser_snapshot` for DOM structure, `browser_take_screenshot` for visual analysis.

**Local file path (.html, .css):** Read the file directly.

**`--screenshot <path>`:** Read the image file. Score visually — note that some accessibility criteria require code