boc/docs/design/foundations/COMPONENT_TEMPLATE.md

# COMPONENT TEMPLATE

**Template for All Component Specifications**

| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All Landvex & quiXzoom components |

---

## Instructions

Copy this template for each new component. Remove sections that do not apply. Add sections that are component-specific.

---

## [Component Name]

**Purpose:** One sentence describing what this component does.

**Design Goal:** One sentence describing the ideal user experience.

**Core Principle:** How does this component support "From Reality → Decision"?
- What decision does it help the user make?
- How does it reduce cognitive load?
- Can it be understood in 3 seconds?

**Tier:** [1 (Canonical) / 2 (Derived) / 3 (Domain)]

**Inherits From:** [Parent component, or "—" if canonical]

---

### Token Dependencies

| Token | Semantic Reference | Usage |
|-------|-------------------|-------|
| `component-token-1` | `semantic-token-1` | Description |
| `component-token-2` | `semantic-token-2` | Description |

---

### Layout

- Dimensions
- Padding
- Margins
- Border radius
- Internal structure

---

### Sizes

| Size | Dimensions | Usage |
|------|-----------|-------|
| Small | [dimensions] | [context] |
| Default | [dimensions] | [context] |
| Large | [dimensions] | [context] |

---

### Variants

| Variant | Visual | Usage |
|---------|--------|-------|
| Variant 1 | [description] | [context] |
| Variant 2 | [description] | [context] |

---

### States

| State | Visual | Motion |
|-------|--------|--------|
| Default | [description] | [animation] |
| Hover | [description] | [animation] |
| Focus | [description] | [animation] |
| Active | [description] | [animation] |
| Disabled | [description] | [animation] |
| Loading | [description] | [animation] |
| Error | [description] | [animation] |

---

### Keyboard

| Key | Action |
|-----|--------|
| `Tab` | [behavior] |
| `Enter` / `Space` | [behavior] |
| `Escape` | [behavior] |
| Arrow keys | [behavior] |

---

### Touch

- Touch target size
- Active state behavior
- Gesture support (if any)

---

### Accessibility

- ARIA roles
- ARIA states
- Screen reader behavior
- Focus management

---

### Motion

| Transition | Animation | Duration | Easing |
|-----------|-----------|----------|--------|
| [state change] | [description] | [duration] | [easing] |

---

### Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

---

### Anti-Patterns

- ❌ [What not to do]
- ❌ [What not to do]

---

### Related Components

- [Component A] — [relationship]
- [Component B] — [relationship]

---

### DDR References

- DDR-XXX: [Decision rationale]