/design-component

name: design-component
description: Design a UI component spec to the house quality bar (anatomy, variants, sizes, the 8 states, token mapping, and accessibility). Use when the user wants to design or document a component (button, input, tabs, toast, combobox, date picker, modal, etc.) at the spec level before or alongside code. For generating framework code, use design-code.

Skill: Design Component

Requirements

This skill needs the full UX/UI Agent Skills kit: the gates, the references and the design-system library. Install it with `npx ux-ui-agent-skills@3.1.0 init` or as the Claude Code plugin. `npx skills@1.7.6 add` copies the skill folder and nothing else. Installed that way, this skill runs in **guidance-only mode**: no gate runs, so it gives no verdict.

> **Step 0: is the kit here?** Check once: > `ls ${CLAUDE_SKILL_DIR}/../../../tokens >/dev/null 2>&1 && echo KIT_OK || echo KIT_MISSING` > On `KIT_MISSING`, open your reply with: "Guidance-only mode: the UX/UI Agent > Skills kit is not installed here, so no gate ran and nothing below is > measured." Then work from this file and general practice, under three rules. > Do not guess or cite the contents of a kit file you could not open. State no > measured number (no contrast ratio, no N/N, no "passes WCAG"): write "not > verified" where one would go. End with a line `Skipped (kit not installed):` > that names every gate script this file tells you to run, then the install > command above.

Produce a complete component specification matching the project format.

Steps

1. Read `${CLAUDE_SKILL_DIR}/../../../.claude/rules/components.md` → "Component Quality Bar" (the 8-state table) and "Atomic Design"; the always-on 8-state table is in `${CLAUDE_SKILL_DIR}/../../../CLAUDE.md` → Non-Negotiables. 2. Check if it already exists: `${CLAUDE_SKILL_DIR}/../../../components/atoms.md`, `molecules.md`, `organisms.md`, `templates.md`, `navigation.md`, `feedback.md`, `forms-advanced.md`, `overlays.md`. Match the existing spec format. 3. Pull the ARIA pattern from `${CLAUDE_SKILL_DIR}/../../../accessibility/aria-patterns.md` and contrast/target rules from `${CLAUDE_SKILL_DIR}/../../../accessibility/wcag-checklist.md`. 4. Map every value to tokens (`${CLAUDE_SKILL_DIR}/../../../tokens/*.json`): sizes via `sizing.json`, states via `states.json`. 5. Apply visual judgment from `${CLAUDE_SKILL_DIR}/../../../taste/design-taste.md` (states, focus, no slop). 6. Optional fast start: `python3 ${CLAUDE_SKILL_DIR}/../../../scripts/scaffold_component.py "<Name>"` to emit a stub, then fill it in.

Output

Spec with: anatomy diagram, variants table, sizes table, all 8 applicable states, token mapping, accessibility (role/keyboard/SR), and a note to render via `${CLAUDE_SKILL_DIR}/../../../frameworks/adapter-protocol.md`.

Accuracy: verify every state, don't assume (mandatory when code is produced)

A component is only "correct" when **every variant × state** renders right, not just the resting default. Build a **states harness**: render the component in each applicable state (default, hover, focus, active, disabled, loading `aria-busy`, error `aria-invalid`, selected `aria-pressed`/`aria-selected`) × each variant in one HTML file (see `${CLAUDE_SKILL_DIR}/../../../examples/component-states/button.html`). Then RUN the gates and report their real output (CLAUDE.md → Verification Protocol):

• `node ${CLAUDE_SKILL_DIR}/../../../scripts/gate.mjs verify_states.mjs <harness> [--dark]`: contrast of every element in default/hover/focus
• `node ${CLAUDE_SKILL_DIR}/../../../scripts/gate.mjs axe_audit.mjs <harness> [--dark]`: ARIA/role/name/label correctness
• `node ${CLAUDE_SKILL_DIR}/../../../scripts/gate.mjs measure_render.mjs <harness> [--dark]`: every text element AA
• overlays/modals also: `node ${CLAUDE_SKILL_DIR}/../../../scripts/gate.mjs verify_focustrap.mjs <harness> --open=<trigger>`

Every state must pass in light AND dark before the component is "done". Never claim a state is correct without a gate proving it.

Gates prove contrast/a11y. They do NOT prove pixels. RENDER AND LOOK.

The contrast/axe gates pass while the UI is still visibly broken: a checkbox that doesn't toggle, a dash sitting at the bottom of its box, a checkmark and an indeterminate dash with mismatched stroke weight, a control that's too heavy. **You must screenshot the harness and inspect it** before claiming done, for every state, and after interaction. Playwright + system Chrome:

const b = await chromium.launch({channel:'chrome'});
const p = await b.newPage({deviceScaleFactor:4});
await p.goto('file://'+abs); await p.addStyleTag({content:'*{transition:none!important}'});
await p.mouse.move(2000,2000);                 // park pointer OFF the component
await p.locator('.stack').first().screenshot({path:'/tmp/x.png'});

Read the PNG. Then look for, specifically:

• **Functional**: click each interactive element and assert the state actually changed (`await loc.click(); expect(await loc.isChecked())`). A custom control whose overlay box covers the real `<input>` will not toggle unless the box has `pointer-events:none` (or an enclosing `<label>` forwards the click).
• **Geometry**: glyphs centered, not stacked/offset. If a `display:grid` box holds an `opacity:0` sibling plus a `::after`, the pseudo lands in row 2 → use `display:none` on the hidden sibling, or one container child.
• **Stroke consistency**: a checkmark and its indeterminate dash must use the **same** rendering method (one `<svg>`, two `<path>` toggled by state, same `stroke-width`), never an svg check vs a CSS `::after` rect (they read as different weights).
• **Transition artifact**: screenshot WITHOUT disabling transitions and a just-clicked control looks half-faded mid-animation. That is not a bug. Always disable transitions and park the pointer before judging a state.

**Consistency across files is non-negotiable.** The same component (e.g. checkbox) must use byte-identical CSS + markup in every harn