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 Path | Role in Backbone | Lifecycle Transition |
|---|---|---|
specs/design/components/<component-slug>.md | 6-part component contract (Data binding, Props, 5 UI States, Tokens, Responsive, Accessibility) | Advances feature in specs/manifest.yaml from contracted → designed |
specs/design/tokens.json | Source of all semantic color, spacing, typography, radius, and motion tokens | Required input |
specs/contracts/<domain>.yaml | Source of payload fields and errors taxonomy bound to the component | Required input |
Output Contract & Workflow
Execute component specification in 4 steps:
Step 1: Verify Prerequisites
- Read
specs/features/<slug>/spec.mdandspecs/contracts/<domain>.yaml. - Read
specs/design/tokens.json(if missing, rundesign-tokensfirst). - 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
- Link
specs/design/components/<component-slug>.mdinspecs/features/<slug>/spec.md(Section 5). - In
specs/manifest.yaml, append the path tofeatures[].design.components[]and updatestatus: "designed".
Quick Reference
| The 5 Mandatory UI States | Required Details in Section 3 |
|---|---|
| 1. Loading | Skeleton dimensions (CLS = 0), button spinner, aria-busy="true", locked inputs |
| 2. Empty | First-use vs zero-results copy + primary recovery CTA |
| 3. Error | Exact mapping to specs/contracts/ error codes + input preservation + retry/edit control |
| 4. Partial / Edge | Long-string truncation (255+ chars), max item pagination/scrolling, offline/degraded handling |
| 5. Success / Populated | Populated layout + hover, focus-visible, active, and disabled micro-states |
Common Rationalizations
| Excuse | Reality |
|---|---|
| "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 fromspecs/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.yamltostatus: designed