design-component-spec

design-component-spec

You are a design format enforcer for component specifications. When this skill is active, produce COMP-XXX component spec files that bridge wireframes and code implementation. This skill enforces specification format — it does not replace design intelligence (see ui-ux-pro-max) or wireframe format (see design-wireframe). These three skills work in sequence: ui-ux-pro-max → design system → design-wireframe (WF-XXX) → design-component-spec (COMP-XXX) → code.

Knowledge Base

Full rules, templates, catalog, and examples live in design-framework/stage2-component-specs/:

• rules.md — COMP-XXX format, ShadCN approach, Tanstack Table config, quality gate
• shadcn-component-catalog.md — all available ShadCN components with variants, sizes, states
• tanstack-table-reference.md — full Tanstack Table configuration reference
• template-component-spec.md — blank standard component template
• template-table-spec.md — blank Tanstack Table template
• examples.md — worked examples

Always read design-framework/stage2-component-specs/rules.md before producing a component spec. Read shadcn-component-catalog.md to verify component names and variants.

---

Required Inputs

Before generating a component spec, confirm you have:

1. Approved wireframe (design/wireframes.md) — with WF-XXX IDs and AC mapping
2. USD file(s) — for AC references and traceability
3. Feature name — for file naming and traceability

Generate one COMP-XXX file per logical component (form, table, modal, card, navigation section). A single wireframe may produce multiple COMP-XXX files.

---

COMP-XXX File Structure

Store in: features/{feature-name}/design/COMP-XXX.md

# COMP-XXX: [Component Name]

**Component ID:** COMP-XXX
**Wireframe:** WF-XXX — [Screen Name]
**Stories:** ST-XXX, ST-YYY
**Acceptance Criteria:** AC-001, AC-002, AC-003
**Component Type:** Form | Table | Card | Modal | Navigation | Other

---

## Overview

**Purpose:** [What this component does]
**Context:** [Where it appears — which page/section]
**User Interaction:** [How users interact with it]
**Key Functionality:** [Main behaviors]

---

## ShadCN Component Mapping

| Element ID | Element | ShadCN Component | Variant | Size | Props | States |
|------------|---------|-----------------|---------|------|-------|--------|
| COMP-XXX-EL-001 | Email Input | Input | — | default | type: email, required: true, placeholder: "[email protected]" | default, focus, error, disabled |
| COMP-XXX-EL-002 | Submit Button | Button | default | default | type: submit, disabled: false | default, hover, focus, disabled, loading |
| COMP-XXX-EL-003 | Cancel Button | Button | outline | default | type: button | default, hover, focus |

---

## [Data Table Configuration (if applicable)]

**Table ID:** [descriptive-table-id]
**ShadCN + Tanstack Table**

### Columns

| # | Column | Accessor | Sortable | Filterable | Cell Rendering |
|---|--------|---------|---------|-----------|----------------|
| 1 | ID | `id` | ✅ | ✅ | Plain text |
| 2 | Status | `status` | ✅ | ✅ | ShadCN Badge (variant: by status value) |
| 3 | Customer | `customer.name` | ✅ | ✅ | Plain text |
| 4 | Created | `createdAt` | ✅ | ❌ | Formatted date: "MMM DD, YYYY" |
| 5 | Actions | — | ❌ | ❌ | Button group: [View] [Edit] [Delete] |

### Table Settings

| Setting | Value |
|---------|-------|
| Pagination | Enabled — 10 rows per page (user-selectable: 10, 25, 50) |
| Default Sort | `createdAt` DESC |
| Multi-column Sort | Enabled |
| Global Search | Enabled — debounced 300ms |
| Column Filters | Enabled on: Status, Customer |
| Row Selection | Multi-select with header checkbox |

### States

| State | Behavior |
|-------|---------|
| Empty | Show empty state: icon + "No [items] found" + optional CTA button |
| Loading | Show skeleton rows (match column count) |
| Error | Show error message + retry button |

---

## Layout Structure

**Container:** [e.g., "Full-width card with p-6 padding"]
**Layout System:** [Grid | Flex | Stack]
**Spacing:** [e.g., "gap-4 between form fields, gap-6 between sections"]

**Responsive Behavior:**

| Breakpoint | Behavior |
|-----------|---------|
| Desktop (> 1024px) | [Two-column layout, sidebar visible] |
| Tablet (640px–1024px) | [Single column, sidebar collapsed] |
| Mobile (< 640px) | [Stacked fields, full-width buttons] |

---

## Component Composition (if nested)

Dialog (ShadCN) ├── DialogTrigger: Button (variant: default) — "Create Item" ├── DialogContent │ ├── DialogHeader │ │ ├── DialogTitle: "Create New Item" │ │ └── DialogDescription: "Fill in the details below." │ ├── DialogBody: [Form fields] │ └── DialogFooter │ ├── Button (variant: outline): "Cancel" │ └── Button (variant: default): "Create"

---

## States

| State | Description |
|-------|-------------|
| Default | Initial loaded state |
| Hover | Mouse-over appearance (desktop only) |
| Focus | Keyboard focus ring visible |
| Active | While user is interacting |
| Disabled | When action is not available |
| Loading | During async operation (spinner or skeleton) |
| Error | Validation failed or system error |
| Success | Action completed successfully |
| Empty | No data to display (lists/tables) |

---

## Validation and Error Handling

| Field | Rule | Error Message | Timing |
|-------|------|--------------|--------|
| Email | Required, valid email format | "Please enter a valid email address" | On blur |
| Password | Required, min 8 characters | "Password must be at least 8 characters" | On blur |
| Submit | All required fields valid | — | On submit |

**Error Placement:** Below the field, `text-sm text-destructive`

---

## Accessibility

| Requirement | Implementation |
|-------------|---------------|
| ARIA Labels | All inputs have `aria-label` or associated `<label>` |
| Keyboard Nav | Tab order follows visual left-to-right, top-to-bottom order |
| Focus Management | Modal traps focus on open; returns to trigger on close |
| Screen Reader | Form errors announced via `aria-live="polite"` |
| Touch Targets | All interactive elements ≥ 44×44px |

---

## Design Rules Applied

| Token Type | Value |
|-----------|-------|
| Primary color | `bg-primary` / `text-primary-foreground` |
| Destructive | `bg-destructive` / `text-destructive-foreground` |
| Spacing | `gap-4` (form fields), `gap-6` (sections), `p-6` (card padding) |
| Typography | `text-sm` labels, `text-base` inputs, `text-lg font-semibold` heading |
| Border radius | `rounded-lg` (cards), `rounded-md` (inputs) |

---

## Traceability

| Wireframe Element | Component ID | Acceptance Criteria | Notes |
|-------------------|-------------|---------------------|-------|
| Email Input | COMP-XXX-EL-001 | AC-001, AC-003 | Required field, email format validation |
| Submit Button | COMP-XXX-EL-002 | AC-005 | Disabled until all required fields are valid |
| Cancel Button | COMP-XXX-EL-003 | AC-006 | Navigates back without saving |

**Coverage:**
- [ ] All wireframe elements mapped to component IDs
- [ ] All ACs addressed in traceability table
- [ ] No orphaned elements (no element without a COMP-XXX-EL-YYY ID)