Community程式設計與開發github.com

design-components

Shows an agent how to design, debug, or review "design components" so the concrete output is a design-system pass with tokens. The procedure moves through Design Components (`design-components`), Overview, Living Spec Integration. Use it when a new assignment calls for this craft.

design-components 是什麼?

design-components is a Claude Code agent skill that shows an agent how to design, debug, or review "design components" so the concrete output is a design-system pass with tokens. The procedure moves through Design Components (`design-components`), Overview, Living Spec Integration. Use it when a new assignment calls for this craft.

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/arthurkushman/total-ai-skills/tree/HEAD/skills/design-components

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Design Components (design-components)

Overview

design-components produces implementation-ready component and screen specifications in specs/design/components/<component-slug>.md. It binds backend schemas (specs/contracts/), user journeys (specs/design/flows/), and visual foundations (specs/design/tokens.json) into a deterministic 6-Part Component Specification that eliminates coder guesswork.

Core principle: A UI component specification is incomplete unless it defines all 5 Mandatory UI States (Loading, Empty, Error, Partial/Edge, Success), maps every visual property to a semantic token in specs/design/tokens.json (zero magic values), and specifies a concrete WCAG AA/AAA keyboard and ARIA contract.

Living Spec Integration

Artifact PathRole in BackboneLifecycle Transition
specs/design/components/<component-slug>.md6-part component contract (Data binding, Props, 5 UI States, Tokens, Responsive, Accessibility)Advances feature in specs/manifest.yaml from contracted → designed
specs/design/tokens.jsonSource of all semantic color, spacing, typography, radius, and motion tokensRequired input
specs/contracts/<domain>.yamlSource of payload fields and errors taxonomy bound to the componentRequired input

Output Contract & Workflow

Execute component specification in 4 steps:

Step 1: Verify Prerequisites

  1. Read specs/features/<slug>/spec.md and specs/contracts/<domain>.yaml.
  2. Read specs/design/tokens.json (if missing, run design-tokens first).
  3. Read specs/design/flows/<flow-slug>.md (if multi-step or stateful navigation applies).

Step 2: Author specs/design/components/<component-slug>.md

Every component spec MUST include all 6 sections below. No section may be omitted or marked "TBD".

# Component Specification: <Component Name> (`<component-slug>`)

- **Feature Spec:** `specs/features/<feature-slug>/spec.md`
- **Bound Data Contract:** `specs/contracts/<domain>.yaml#<OperationOrSchema>`
- **Flow Spec:** `specs/design/flows/<flow-slug>.md`
- **Target Source Path:** `<e.g., src/components/invoices/InvoiceForm.tsx>`

## 1. Data Contract Binding
| UI Element / Field | Contract Path / Field | Type & Validation Bounds | Error Codes Handled |
| :--- | :--- | :--- | :--- |
| Customer Selector | `request.customer_id` | `UUID (required)` | `CUSTOMER_NOT_FOUND (404)` |
| Line Items List | `request.line_items[]` | `Array (1..100 items)` | `INVOICE_EMPTY_ITEMS (422)` |
| Total Amount Badge | `Invoice.total_cents`, `Invoice.currency` | `int64 minor units + ISO-4217` | `n/a (read-only formatted)` |

## 2. Anatomy & Props / Events Interface
- **Composition Hierarchy:** `CardContainer` → `Header` + `LineItemRows[]` + `SummaryFooter` + `ActionToolbar`
- **Props / Inputs:**
  - `initialCustomerId?: string`
  - `onSuccess: (invoice: Invoice) => void`
  - `onCancel: () => void`

## 3. The 5 Mandatory UI States
Every component MUST implement all 5 states and have automated tests for each during `code-implement`:

| State | Trigger Predicate | Visual & Layout Specification | User Action / Recovery Control |
| :--- | :--- | :--- | :--- |
| **1. Loading** | Initial fetch or `Submitting` mutation in flight | Render skeleton placeholders matching exact row height (`48px` / `space.12`) for zero Cumulative Layout Shift (`CLS = 0`). Submit button shows inline spinner + `aria-busy="true"`. | Inputs locked (`readOnly`); Cancel remains available for fetches. |
| **2. Empty** | `line_items.length === 0` or zero query results | Centered empty-state container with heading `"No line items added"`, helper copy, and primary CTA `"Add First Line Item"`. Distinguish first-use empty from zero-search-results empty. | Clicking CTA appends a default row and focuses its `description` input. |
| **3. Error** | Contract error (`404`, `409`, `422`, `503`) or network failure | Field errors (`422 INVOICE_EMPTY_ITEMS`) bind inline below field with `status.danger.text` and `status.danger.border`. Upstream errors (`503 BILLING_UPSTREAM_TIMEOUT`) render top alert banner preserving all user-typed form values. | Inline edit clears field error immediately; banner includes `"Retry"` button reusing `Idempotency-Key`. |
| **4. Partial / Edge** | Long strings (`255 chars`), `100` line items, or offline/degraded state | Customer names truncate at 1 line (`text-overflow: ellipsis` + full title tooltip); description wraps up to 2 lines; list container scrolls cleanly after 10 items with sticky footer. | Sticky summary footer always keeps `"Create Invoice"` CTA visible. |
| **5. Success / Populated** | Valid data loaded or `201 Created` returned | Populated rows with interactive micro-states (`hover: surface.subtle`, `focus-visible: 2px solid border.focus`, `disabled: opacity 0.5`). | Emits `onSuccess(invoice)` and triggers screen-reader announcement. |

## 4. Semantic Token Mapping (`specs/design/tokens.json`)
Zero hardcoded hex colors (`#...`), `rgb()`, or off-grid pixel values are permitted.

| Element | Surface / Background | Text / Icon | Border / Focus | Spacing / Radius / Shadow |
| :--- | :--- | :--- | :--- | :--- |
| Root Card | `semantic.surface.card` | `semantic.text.primary` | `semantic.border.default` | `padding: primitive.space.6`, `radius: primitive.radius.lg`, `shadow: primitive.shadow.sm` |
| Primary CTA | `semantic.action.primary.bg` (hover: `bgHover`) | `semantic.action.primary.text` | `focus: 2px semantic.border.focus` | `padding: space.2 space.4`, `radius: radius.md`, `motion: motion.fast` |
| Error Banner / Field | `semantic.status.danger.bg` | `semantic.status.danger.text` | `semantic.status.danger.border` | `padding: primitive.space.3`, `gap: primitive.space.2` |

## 5. Responsive Breakpoint & Layout Rules
| Viewport Tier | Breakpoint Range | Layout Adaptation |
| :--- | :--- | :--- |
| **Mobile** | `< 640px` | Single-column stacked line-item cards; full-width sticky bottom CTA bar; minimum touch target `44x44px`. |
| **Tablet** | `640px – 1024px` | 2-column grid for customer metadata; compact table for line items. |
| **Desktop** | `> 1024px` | Max container width `960px`; 4-column inline grid (`Description 50% | Qty 15% | Price 20% | Remove 15%`). |

## 6. Accessibility (WCAG 2.2 AA) Contract
- **Semantic Landmarks & Elements:** Use native `<form>`, `<fieldset>`, `<legend>`, `<label for="...">`, and `<button type="submit|button">` (never `<div onClick>`).
- **ARIA Attributes:**
  - Invalid inputs set `aria-invalid="true"` and `aria-describedby="<field>-error"`.
  - Async submission sets `aria-busy="true"` on the form.
  - Error banner uses `role="alert"` (`aria-live="assertive"`); success toast uses `role="status"` (`aria-live="polite"`).
- **Keyboard Navigation Map:**
  - `Tab` / `Shift+Tab`: Moves linearly through Customer → Line Item fields → Add Row → Cancel → Submit.
  - `Enter` inside text input: Submits form (when valid) or moves focus to first invalid field.
  - `Escape` inside modal/popover: Closes overlay (or triggers discard confirmation if dirty) and restores focus to trigger button.
- **Focus Management:** On validation error, programmatic focus moves immediately to the first field with `aria-invalid="true"`.

Step 3: Advance Backbone Lifecycle State

  1. Link specs/design/components/<component-slug>.md in specs/features/<slug>/spec.md (Section 5).
  2. In specs/manifest.yaml, append the path to features[].design.components[] and update status: "designed".

Quick Reference

The 5 Mandatory UI StatesRequired Details in Section 3
1. LoadingSkeleton dimensions (CLS = 0), button spinner, aria-busy="true", locked inputs
2. EmptyFirst-use vs zero-results copy + primary recovery CTA
3. ErrorExact mapping to specs/contracts/ error codes + input preservation + retry/edit control
4. Partial / EdgeLong-string truncation (255+ chars), max item pagination/scrolling, offline/degraded handling
5. Success / PopulatedPopulated layout + hover, focus-visible, active, and disabled micro-states

Common Rationalizations

ExcuseReality
"I'll specify the happy-path layout; the coder knows how to add loading spinners and error messages"Left unspecified, coders render a jarring text "Loading..." (breaking layout stability) and a generic alert("Error") that wipes user input. All 5 states are mandatory.
"I'll use #dc2626 and padding: 15px directly in the component spec for clarity"Direct hex and off-grid pixel literals bypass specs/design/tokens.json, break dark mode, and trigger CONTRACT_VIOLATION in sdd-drift. Map to semantic tokens in Section 4.
"Standard HTML is accessible enough; we don't need an explicit Section 6 Accessibility Contract"Focus restoration on modal close, focus jump to the first invalid field on submit, and aria-describedby bindings for inline errors never happen unless specified in Section 6.

Red Flags

  • Writing a component spec with fewer than the 5 Mandatory UI States (Loading, Empty, Error, Partial/Edge, Success)
  • Putting raw hex codes (#...) or off-grid pixel values (13px, 15px) in the component spec instead of semantic token keys from specs/design/tokens.json
  • Failing to map UI error states to the specific error codes defined in specs/contracts/
  • Omitting keyboard focus management or ARIA attributes in Section 6
  • Forgetting to update specs/manifest.yaml to status: designed

相關技能