design-component
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.
plugin87 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add plugin87/ux-ui-agent-skills --skill 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. invocation: model
Skill: Design Component
Produce a complete component specification matching the project format.
Steps
- Read
.claude/rules/components.md→ "Component Quality Bar" (the 8-state table) and "Atomic Design"; the always-on 8-state table is inCLAUDE.md→ Non-Negotiables. - Check if it already exists:
components/atoms.md,molecules.md,organisms.md,templates.md,navigation.md,feedback.md,forms-advanced.md,overlays.md. Match the existing spec format. - Pull the ARIA pattern from
accessibility/aria-patterns.mdand contrast/target rules fromaccessibility/wcag-checklist.md. - Map every value to tokens (
tokens/*.json) — sizes viasizing.json, states viastates.json. - Apply visual judgment from
taste/design-taste.md(states, focus, no slop). - Optional fast start:
python3 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 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 examples/component-states/button.html). Then RUN the gates and report their real output (CLAUDE.md → Verification Protocol):
node scripts/verify_states.mjs <harness> [--dark]— contrast of every element in default/hover/focusnode scripts/axe_audit.mjs <harness> [--dark]— ARIA/role/name/label correctnessnode scripts/measure_render.mjs <harness> [--dark]— every text element AA- overlays/modals also:
node scripts/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 haspointer-events:none(or an enclosing<label>forwards the click). - Geometry: glyphs centered, not stacked/offset. If a
display:gridbox holds anopacity:0sibling plus a::after, the pseudo lands in row 2 → usedisplay:noneon 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 — samestroke-width), never an svg check vs a CSS::afterrect (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 harness/page. A checkbox that looks thin in form-controls and heavy (native accent-color) in data-table is a bug. Factor one pattern, reuse it verbatim.
Verified custom checkbox/radio pattern (thin, token-driven, gated + eyeballed)
Real <input> underneath (keeps native a11y + keyboard); a drawn .box overlay with pointer-events:none; check + dash as two <path> in one <svg> toggled by :checked / :indeterminate; 1.5px border-strong, .25rem radius, .62rem glyph, stroke-width:2 round caps. Reference: examples/component-states/form-controls.html and data-table.html (select-all uses indeterminate). Native accent-color renders too heavy — do not use it when the house look is "thin".
Responsive — every component, no sideways scroll (gated)
Build mobile-first; a fixed-px width that can't shrink is a bug. Run node scripts/verify_responsive.mjs <file|dir> — it loads each harness at 280/320/414px and fails on any horizontal overflow. The four recurring causes and their fixes:
- fixed
inline-size:Npx→inline-size:100%;max-inline-size:Npx(cap, don't pin). <ul>/<ol>default 40px inline-start padding (a*{margin:0}reset does NOT clear padding) →padding:0;margin:0on every list. This also silently mis-aligns a list's edge vs a sibling block (looks like unequal widths) — same fix.- non-wrapping flex rows (breadcrumb, stepper, tabs) →
flex-wrap:wrap, or for tabsoverflow-x:auto+.tab{flex:none}.