design-doctrine

Skill: Design Doctrine

A plugin's root CLAUDE.md is not loaded as project context, so the always-on

brief travels here instead. Read this before the first line of any design work,

then load the rule file for the territory you are actually in.

Verification protocol - run gates, never claim

1. Never state a number you did not measure. Any contrast ratio, "WCAG pass",

or "100%" must come from running a gate and reporting its real output. If you

have not run it, say "not verified yet."

1. Verify every state, not just resting. node scripts/verify_states.mjs <file> [--dark]

measures default, hover and focus - a button that passes at rest can fail on hover.

1. One command before reporting done: node scripts/accuracy_report.mjs.

Report the real N/N line. It is all-or-nothing.

1. Build with the gates, not after them. Fix and re-run until green; never

announce success between failures.

1. Render and LOOK. Gates pass while a UI is still visibly broken. Screenshot

the harness in both themes, click every control, and confirm the state changed.

1. Responsive is gated too: node scripts/verify_responsive.mjs <file|dir> -

no horizontal overflow at 280/320/414px.

1. Honest scope. The gates prove objective correctness. They never prove taste.

For that, run /critique and look at the work yourself.

1. SKIPPED is not a pass. With no browser installed a render gate prints

SKIPPED and exits 0, reporting nothing. Run single render gates behind

DS_REQUIRE_BROWSER=1 so that becomes REQUIRED, FAILING, and fix it with

npx playwright install chrome rather than by removing the flag.

> ABSOLUTE: zero emoji in any output - UI, code, JSON, copy, comments, commit

> messages. Not as an icon, a bullet, a status dot, or "polish". Emoji are the

> number-one tell of machine-generated work. Use a lucide icon (inline SVG,

> currentColor) or plain words. Enforced by scripts/check_no_emoji.py.

The five non-negotiables

1. Token by intent. Pick the token whose meaning matches the action.

Destructive actions (Delete, Remove, Revoke) wear action.destructive in every

place they appear - the trigger and the confirm dialog both. A blue Delete is a

bug. Measured by scripts/lint_intent.mjs.

1. One theme, one source of truth. Every page renders from the same

tokens/*.json through one CSS-variable layer imported once at the app root.

No per-page palette, no hardcoded hex, px, or timing.

1. Every interactive element ships eight states: default, hover, focus,

active, disabled, loading (if async), error (if input), and selected (if

selectable). The eighth is not optional when the thing can be selected.

1. One thing leads. Every screen has a first place for the eye, and display

type is at least 2.5x the body size. Four equal cards means the eye lands

nowhere and the screen reads as generated.

1. Output completeness. A partial output is a broken output. Deliver full

files, never placeholders. Asked for N components, deliver all N.

Decision framework

User needs, then accessibility, then consistency, then aesthetics, then developer

experience. Never sacrifice a higher tier for a lower one. Beautiful but

inaccessible is broken; consistent but confusing is the wrong pattern.

Where the depth lives

| Read it when | File |

|---|---|

| Tokens, palettes, theming, dark mode, any colour decision | .claude/rules/tokens-and-color.md |

| Type scale, line length, the 4px spacing rhythm | .claude/rules/typography-and-spacing.md |

| Building any screen or component, composition, empty states | .claude/rules/components.md |

| Auditing, or finishing any interactive element | .claude/rules/accessibility.md |

| Generating code for React, Next.js, SwiftUI, or any adapter | .claude/rules/frameworks.md |

| Design review, prototyping, research, handoff | .claude/rules/review-and-research.md |

| Aesthetic direction, motion, voice and tone, governance, QA | .claude/rules/brand-and-operations.md |

Then pick the runnable skill for the job: design-tokens, design-component,

design-code, design-review, a11y-audit, apply-aesthetic, brandkit,

image-to-code, redesign, and the rest. Interrogate the brief first with

/grill-me; prove the result with /gate; judge it with /critique.