design-doctrine

---
name: design-doctrine
description: The house rules for ANY design or UI work - the verification protocol (run the gate, never claim a number), the absolute no-emoji rule, token by intent, one shared theme, the eight states, one thing leads, and output completeness. Load this FIRST whenever building, reviewing, or theming a screen, component, or token set. Installed as a plugin, this skill carries what CLAUDE.md carries in the repo.
invocation: model
---

# 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."
2. **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.
3. **One command before reporting done:** `node scripts/accuracy_report.mjs`.
   Report the real `N/N` line. It is all-or-nothing.
4. **Build with the gates, not after them.** Fix and re-run until green; never
   announce success between failures.
5. **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.
6. **Responsive is gated too:** `node scripts/verify_responsive.mjs <file|dir>` -
   no horizontal overflow at 280/320/414px.
7. **Honest scope.** The gates prove objective correctness. They never prove taste.
   For that, run `/critique` and look at the work yourself.
8. **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`.
2. **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.
3. **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.
4. **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.
5. **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`.