QuantEngineByItz/spec/66_component_taxonomy.md

# Component Taxonomy: 4-Layer Architecture for OMS·WMS·ERP SPA

**Status**: DRAFT (Phase 0, requires Figma finalization)  
**Date**: 2026-07-26  
**Related**: [ADR-001 (Spec 65)](spec/65_adr_001_monolithic_spa_architecture.md), [OpenAPI (Spec 63)](spec/63_oms_wms_erp_api_openapi.yaml)

---

## Overview

**Component Hierarchy**: 4 layers, 65 total components across OMS/WMS/ERP domains

```
┌─────────────────────────────────────────────────────────────────┐
│ Layer 4: Business Composite (11 CRUD Workflows)                │
│  └─ OrderForm, InventoryTransferWizard, VoucherEditor, etc.    │
├─────────────────────────────────────────────────────────────────┤
│ Layer 3: Domain Fields (12 Domain-Specific Inputs)             │
│  └─ OrderLineField, InventoryField, VoucherLineField, etc.     │
├─────────────────────────────────────────────────────────────────┤
│ Layer 2: Typed Fields (12 Type-Safe Inputs)                    │
│  └─ TextField, DateField, CurrencyField, StatusField, etc.     │
├─────────────────────────────────────────────────────────────────┤
│ Layer 1: Primitives (30 UI Building Blocks)                    │
│  └─ Button, Input, Select, Table, Card, Badge, etc.           │
└─────────────────────────────────────────────────────────────────┘
```

**Design System**: Tabler UI (Bootstrap 5) + Storybook 7.0+

---

## Layer 1: Primitive Components (30)

### Purpose
Reusable UI elements with **zero business logic**, full accessibility (WCAG 2.1 AA), typed props, consistent behavior.

### Folder Structure
```
src/components/primitives/
├─ Button/
│  ├─ ButtonBase.vue
│  ├─ ButtonBase.stories.ts
│  └─ ButtonBase.spec.ts
├─ Input/
│  ├─ InputBase.vue
│  ├─ InputBase.stories.ts
│  └─ InputBase.spec.ts
├─ Select/
│  ├─ SelectBase.vue
│  ├─ SelectBase.stories.ts
│  └─ SelectBase.spec.ts
├─ Table/
│  ├─ TableBase.vue
│  ├─ TableBase.stories.ts
│  └─ TableBase.spec.ts
├─ Card/
│  ├─ CardBase.vue
│  └─ CardBase.stories.ts
├─ Badge/
├─ Modal/
├─ Checkbox/
├─ Radio/
├─ Textarea/
├─ Pagination/
├─ Alert/
├─ Spinner/
├─ Tooltip/
├─ Dropdown/
├─ Tabs/
├─ Breadcrumb/
├─ NavBar/
├─ Sidebar/
├─ Icon/
└─ Link/
```

### Component Specifications

| Component | Props | Events | A11y | Story |
|-----------|-------|--------|------|-------|
| **ButtonBase** | variant (primary/secondary/danger), size (sm/md/lg), disabled, loading | click | aria-label, focus-visible | 12 stories |
| **InputBase** | type (text/email/number), placeholder, value, disabled, error, required | input, change, blur | label + aria-describedby (error) | 8 stories |
| **SelectBase** | options: Array<{value, label}>, value, disabled, multiple | change | aria-label, aria-expanded | 10 stories |
| **TableBase** | columns: Array<{key, header, sortable}>, data: any[], onSort | row-click, sort | semantic <table>, scope | 6 stories |
| **CardBase** | title, subtitle, footer, clickable | click | semantic <article> | 5 stories |
| **BadgeBase** | status (success/danger/warning/info), size | — | aria-label | 8 stories |
| **ModalBase** | isOpen, title, onClose | close | role="dialog", focus-trap | 6 stories |
| **CheckboxBase** | value, label, disabled, required | change | aria-label, aria-describedby | 6 stories |
| **RadioBase** | name, options, value, disabled | change | role="radiogroup" | 5 stories |
| **TextareaBase** | value, placeholder, rows, disabled, error | input, change | aria-describedby | 5 stories |
| **PaginationBase** | currentPage, totalPages, onPageChange | page-change | aria-label (next/prev) | 4 stories |
| **AlertBase** | type (success/error/warning), dismissible, onDismiss | dismiss | role="alert" | 8 stories |
| **SpinnerBase** | size, color | — | aria-busy | 4 stories |
| **TooltipBase** | text, position (top/bottom/left/right) | show, hide | aria-describedby | 5 stories |
| **DropdownBase** | trigger, items: Array<{label, action}>, onSelect | select | role="menu", role="menuitem" | 6 stories |
| **TabsBase** | tabs: Array<{id, label, disabled}>, activeId, onTabChange | tab-change | role="tablist", role="tab" | 6 stories |
| **BreadcrumbBase** | items: Array<{label, href}> | navigate | aria-label | 3 stories |
| **NavBarBase** | title, items: Array<{label, href}>, sticky | navigate | semantic <nav> | 4 stories |
| **SidebarBase** | collapsed, items, activeId, onNavigate | navigate | semantic <nav> | 4 stories |
| **IconBase** | name (Bootstrap Icons), size, color | — | aria-hidden or aria-label | 8 stories |
| **LinkBase** | href, external, disabled, active | click | semantic <a> | 5 stories |

**Total Layer 1**: 30 components × 6 stories (avg) = **180 Storybook stories**

---

## Layer 2: Typed Field Components (12)

### Purpose
Domain-aware input fields with **automatic validation**, **formatting**, **labels**, and **error messages**. Props are **strongly typed** via TypeScript.

### Folder Structure
```
src/components/fields/typed/
├─ TextField/
│  ├─ TextField.vue
│  ├─ TextField.stories.ts
│  └─ TextField.spec.ts
├─ DateField/
├─ DateRangeField/
├─ TimeField/
├─ CurrencyField/
├─ PercentageField/
├─ QuantityField/
├─ StatusField/
├─ SelectField/
├─ MultiSelectField/
├─ CheckboxField/
└─ SearchField/
```

### Component Specifications

| Component | Input Type | Validation | Formatting | Story Count |
|-----------|-----------|-----------|-----------|---|
| **TextField** | text/email/password | Length, pattern, required | Trim whitespace | 10 |
| **DateField** | date picker | Range, min/max, required | yyyy-MM-dd (ISO 8601) | 8 |
| **DateRangeField** | dual date picker | Start ≤ End, required | ISO 8601 pair | 6 |
| **TimeField** | time picker | Range, required | HH:mm (24h) | 6 |
| **CurrencyField** | number | Decimal (2 places), min (0) | 10,000.00 KRW with comma | 12 |
| **PercentageField** | number | Range (0-100), decimal (2) | 0-100% with % suffix | 8 |
| **QuantityField** | number | Positive integer, required | No decimal, min (1) | 10 |
| **StatusField** | select | Pre-defined enum | Badge-style display | 8 |
| **SelectField** | dropdown | Options validation, required | Label + value, search | 10 |
| **MultiSelectField** | multi-select | Max items, required | Tag pills, clear all | 8 |
| **CheckboxField** | checkbox | Boolean value | Label + description | 6 |
| **SearchField** | search input | Debounce (300ms), min length (2) | Real-time suggestion | 10 |

**TypeScript Interface Example** (TextField):

```typescript
interface TextFieldProps {
  modelValue: string;
  label: string;
  type?: 'text' | 'email' | 'password' | 'url';
  placeholder?: string;
  disabled?: boolean;
  required?: boolean;
  readonly?: boolean;
  maxLength?: number;
  pattern?: string;
  helpText?: string;
  errorMessage?: string;
  showCounter?: boolean; // Character count
  icon?: string; // Bootstrap Icon name
  variant?: 'outlined' | 'filled' | 'standard';
  size?: 'sm' | 'md' | 'lg';
  validation?: (value: string) => string | null; // Custom validator
  onUpdate:modelValue: (value: string) => void;
  onBlur: () => void;
  onFocus: () => void;
}
```

**Total Layer 2**: 12 components × 9 stories (avg) = **108 Storybook stories**

---

## Layer 3: Domain Field Components (12)

### Purpose
Business-domain-specific input components that **compose Layer 2 fields**, **enforce business rules**, and provide **inline lookups** (e.g., product autocomplete, customer search).

### Folder Structure
```
src/components/fields/domain/
├─ OrderLineField/
│  ├─ OrderLineField.vue
│  ├─ OrderLineField.stories.ts
│  └─ OrderLineField.spec.ts
├─ InventoryField/
├─ VoucherLineField/
├─ ProductField/
│  ├─ ProductAutocomplete.vue (lookup product by SKU)
│  └─ ProductField.vue (combines with price sync)
├─ CustomerField/
├─ SupplierField/
├─ GLAccountField/
├─ WarehouseField/
├─ StockTransferField/
├─ PriceField/
└─ DiscountField/
```

### Component Specifications

| Component | Composes | Business Rules | Lookup | Story |
|-----------|----------|-----------------|--------|-------|
| **OrderLineField** | CurrencyField, QuantityField, SelectField | Line total = qty × price, validate stock | Product lookup by SKU | 10 |
| **InventoryField** | QuantityField, StatusField, SelectField | qty_on_hand ≥ qty_reserved, warn low stock | Warehouse + product combo | 8 |
| **VoucherLineField** | CurrencyField, SelectField, Textarea | Debit XOR Credit (not both), balance check | GL account chart of accounts | 10 |
| **ProductField** | SearchField, SelectField | Validate SKU exists, sync category + price | Real-time SKU autocomplete | 12 |
| **CustomerField** | SearchField, SelectField | Validate customer active, load default terms | Customer name + code search | 10 |
| **SupplierField** | SearchField, SelectField | Validate supplier active, load payment terms | Supplier name + code search | 8 |
| **GLAccountField** | SelectField | Validate account type matches voucher | GL account hierarchy + balance | 10 |
| **WarehouseField** | SelectField | Validate warehouse active, check stock levels | Warehouse dropdown + capacity | 6 |
| **StockTransferField** | SelectField, QuantityField | From ≠ To, qty ≤ on_hand, require reason | Warehouse + qty validation | 10 |
| **PriceField** | CurrencyField | Validate precision (KIS tick rules), min/max | Price suggestions from history | 10 |
| **DiscountField** | PercentageField, CurrencyField | Mutually exclusive %, validate range | Auto-calculate from line total | 8 |
| **DateRangeFilterField** | DateRangeField | Start ≤ End, optional (both or neither) | Quick filters (Today, This Week, etc.) | 8 |

**Example: OrderLineField Props**

```typescript
interface OrderLineFieldProps {
  modelValue: {
    productId: string;
    productName: string;
    quantity: number;
    unitPrice: number;
    lineTotal: number;
  };
  orderId: string; // For stock validation
  warehouse?: string; // Default warehouse
  disabled?: boolean;
  errorFields?: Array<'quantity' | 'unitPrice' | 'product'>;
  onUpdate:modelValue: (line: OrderLine) => void;
  onProductChange: (productId: string) => Promise<Product>;
  onRemove: () => void;
}
```

**Total Layer 3**: 12 components × 9 stories (avg) = **108 Storybook stories**

---

## Layer 4: Business Composite Components (11)

### Purpose
Full **workflow components** for CRUD operations (List, Create, Read, Edit, Delete). Each maps to one entity in the OpenAPI spec. Orchestrates state, validation, approval workflows, and audit trails.

### Folder Structure
```
src/components/composites/
├─ Order/
│  ├─ OrderList.vue
│  ├─ OrderDetail.vue
│  ├─ OrderForm.vue
│  ├─ OrderForm.stories.ts
│  └─ OrderForm.spec.ts
├─ Inventory/
│  ├─ InventoryList.vue
│  ├─ InventoryDetail.vue
│  └─ InventoryTransferWizard.vue
├─ Product/
│  ├─ ProductList.vue
│  ├─ ProductForm.vue
│  └─ ProductDetail.vue
├─ Customer/
├─ Supplier/
├─ GLAccount/
├─ Voucher/
│  ├─ VoucherList.vue
│  ├─ VoucherEditor.vue (line-by-line editing)
│  └─ VoucherApprovalMatrix.vue
├─ User/
│  ├─ UserList.vue
│  ├─ UserForm.vue
│  └─ PermissionMatrix.vue
├─ Warehouse/
└─ StockTransfer/
```

### CRUD Template Pattern (ALL 11 follow same structure)

**Standard Workflow**:
```
List View (table + filters + pagination)
  ↓
  ├─→ Create (form + validation + submit)
  ├─→ Read (detail view, read-only)
  ├─→ Edit (form + validation + submit)
  └─→ Delete (confirmation + soft-delete + audit)
```

### Component Specifications (11 entities)

#### 1. **Order** (OMS)
```typescript
interface OrderForm {
  orderId?: string; // undefined = CREATE
  orderNo: string; // Auto-generate on CREATE
  customerId: string; // Required, lookup
  orderDate: string; // ISO date
  lineItems: OrderLineField[]; // Min 1, max 100
  totalAmount: number; // Computed from lines
  status: 'DRAFT' | 'CONFIRMED' | 'SHIPPED' | 'DELIVERED' | 'CANCELLED';
  createdBy: string; // Read-only
  createdAt: string; // Read-only
}

Workflow:
  - Create: Customer lookup → Line editor (add/edit/remove) → Confirm
  - Edit: Locked after CONFIRMED (read-only)
  - Delete: Soft-delete + audit trail
  - Approval: Required if total > 1M KRW (supervisor)
```

#### 2. **OrderLine** (Nested in Order)
```typescript
interface OrderLineField {
  lineNo: number;
  productId: string;
  quantity: number;
  unitPrice: number;
  lineTotal: number; // Computed
}

Rules:
  - Validate product exists + stock available
  - Auto-fetch price from product master
  - Auto-calculate line total
  - Block if product inactive
```

#### 3. **Inventory** (WMS)
```typescript
interface InventoryField {
  warehouseId: string;
  productId: string;
  qtyOnHand: number;
  qtyReserved: number;
  qtyAvailable: number; // Computed: on_hand - reserved
  lastAdjustmentDate: string;
}

Workflow:
  - Read: Dashboard + drill-down by product/warehouse
  - Adjust: Quantity adjustment form (reason + approval for >$5K impact)
  - Transfer: StockTransferWizard (from → to warehouse, approval)
  - Alert: Low stock warning (<minimum threshold)
```

#### 4. **StockTransfer** (WMS)
```typescript
interface StockTransferForm {
  transferId?: string;
  transferNo: string; // Auto-generate
  fromWarehouseId: string;
  toWarehouseId: string;
  productId: string;
  quantity: number;
  reason: string; // Required
  status: 'REQUESTED' | 'APPROVED' | 'SHIPPED' | 'RECEIVED' | 'CANCELLED';
}

Workflow:
  - Create: Wizard (select warehouses → select product → qty → reason)
  - Approve: Supervisor approval matrix
  - Ship: Mark shipped (creates WMS receipt task)
  - Receive: Confirm receipt (updates inventory)
```

#### 5. **Product** (ERP Master)
```typescript
interface ProductForm {
  productId?: string;
  sku: string; // Unique, required
  productName: string;
  categoryId: string;
  unitOfMeasure: 'EA' | 'KG' | 'M' | 'L' | 'BOX';
  status: 'ACTIVE' | 'INACTIVE' | 'OBSOLETE';
}

Workflow:
  - Create: SKU validation (uniqueness), category lookup
  - Edit: Locked after first inventory transaction (prevent SKU change)
  - Delete: Soft-delete if no inventory/orders reference
  - List: Search by SKU/name, filter by category + status
```

#### 6. **Customer** (OMS Master)
```typescript
interface CustomerForm {
  customerId?: string;
  customerCode: string; // Unique
  customerName: string;
  email: string;
  phone: string;
  businessRegistration: string;
  status: 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
}

Workflow:
  - Create: Email validation, duplicate check
  - Edit: Track customer credit history + order count
  - Delete: Soft-delete if orders reference
  - List: Search by code/name, filter by status
```

#### 7. **Supplier** (ERP Master)
```typescript
interface SupplierForm {
  supplierId?: string;
  supplierCode: string;
  supplierName: string;
  email: string;
  phone: string;
  businessRegistration: string;
  status: 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
}

Workflow:
  - Similar to Customer, but:
  - Track payment terms (COD, NET30, etc.)
  - List: Filter by payment terms
```

#### 8. **GLAccount** (ERP)
```typescript
interface GLAccountForm {
  accountId?: string;
  accountCode: string; // e.g., 1000 (assets), 2000 (liabilities)
  accountName: string;
  accountType: 'ASSET' | 'LIABILITY' | 'EQUITY' | 'REVENUE' | 'EXPENSE';
  status: 'ACTIVE' | 'INACTIVE';
}

Workflow:
  - Create: Validate account code format (numeric, hierarchical)
  - Edit: Locked after first GL posting (prevent type change)
  - Delete: Soft-delete if balances > 0
  - List: Filter by account type + status
```

#### 9. **Voucher** (ERP GL Entry)
```typescript
interface VoucherForm {
  voucherId?: string;
  voucherNo: string; // Auto-generate per document type
  documentDate: string;
  documentType: 'PURCHASE' | 'SALES' | 'JOURNAL' | 'ADJUSTMENT';
  voucherLines: VoucherLineField[]; // Min 2, must balance
  totalDebit: number; // Computed
  totalCredit: number; // Computed
  status: 'DRAFT' | 'POSTED' | 'APPROVED' | 'VOIDED';
}

Workflow:
  - Line Editor: Add line → select GL account → debit OR credit → auto-balance check
  - Validation: Total debit = total credit (must balance)
  - Posting: Change status DRAFT → POSTED (creates GL entries, irreversible)
  - Reversal: Create reversal voucher (new ID, status POSTED), don't delete
  - Approval: CFO approval for all POSTED vouchers (Phase 8+)
```

#### 10. **User** (Admin)
```typescript
interface UserForm {
  userId?: string;
  email: string; // Unique
  name: string;
  password: string; // Required on CREATE, optional on UPDATE
  role: 'ADMIN' | 'MANAGER' | 'OPERATOR' | 'VIEWER' | 'ANALYST';
  status: 'ACTIVE' | 'INACTIVE';
}

Workflow:
  - Create: Email validation, temp password or email reset link
  - Edit: Only admin + self can edit
  - Password Reset: Email-based reset link (60 min expiry)
  - Delete: Soft-delete, preserve audit trail (keep created_by reference)
  - Permissions: PermissionMatrix (role → resource → action)
```

#### 11. **Warehouse** (WMS Master)
```typescript
interface WarehouseForm {
  warehouseId?: string;
  warehouseCode: string; // e.g., WH-SEOUL
  warehouseName: string;
  location: string;
  status: 'ACTIVE' | 'INACTIVE';
}

Workflow:
  - Create: Validate location format
  - Edit: Locked after first inventory transaction (prevent location change)
  - Delete: Soft-delete if inventory records reference
  - List: Filter by status
```

**Total Layer 4**: 11 components × 5 stories (avg for CRUD workflows) + 50 E2E tests = **55 Storybook stories + 116 E2E scenarios**

---

## Folder Structure (Complete)

```
src/
├─ components/
│  ├─ primitives/
│  │  ├─ Button/
│  │  │  ├─ ButtonBase.vue
│  │  │  ├─ ButtonBase.stories.ts
│  │  │  ├─ ButtonBase.spec.ts
│  │  │  └─ types.ts
│  │  ├─ Input/
│  │  ├─ Select/
│  │  ├─ Table/
│  │  ├─ Card/
│  │  ├─ Badge/
│  │  ├─ Modal/
│  │  ├─ Checkbox/
│  │  ├─ Radio/
│  │  ├─ Textarea/
│  │  ├─ Pagination/
│  │  ├─ Alert/
│  │  ├─ Spinner/
│  │  ├─ Tooltip/
│  │  ├─ Dropdown/
│  │  ├─ Tabs/
│  │  ├─ Breadcrumb/
│  │  ├─ NavBar/
│  │  ├─ Sidebar/
│  │  ├─ Icon/
│  │  ├─ Link/
│  │  └─ index.ts (export all)
│  │
│  ├─ fields/
│  │  ├─ typed/
│  │  │  ├─ TextField/
│  │  │  ├─ DateField/
│  │  │  ├─ DateRangeField/
│  │  │  ├─ TimeField/
│  │  │  ├─ CurrencyField/
│  │  │  ├─ PercentageField/
│  │  │  ├─ QuantityField/
│  │  │  ├─ StatusField/
│  │  │  ├─ SelectField/
│  │  │  ├─ MultiSelectField/
│  │  │  ├─ CheckboxField/
│  │  │  ├─ SearchField/
│  │  │  └─ index.ts
│  │  │
│  │  └─ domain/
│  │     ├─ OrderLineField/
│  │     ├─ InventoryField/
│  │     ├─ VoucherLineField/
│  │     ├─ ProductField/
│  │     ├─ CustomerField/
│  │     ├─ SupplierField/
│  │     ├─ GLAccountField/
│  │     ├─ WarehouseField/
│  │     ├─ StockTransferField/
│  │     ├─ PriceField/
│  │     ├─ DiscountField/
│  │     ├─ DateRangeFilterField/
│  │     └─ index.ts
│  │
│  └─ composites/
│     ├─ Order/
│     │  ├─ OrderList.vue
│     │  ├─ OrderDetail.vue
│     │  ├─ OrderForm.vue
│     │  ├─ OrderForm.stories.ts
│     │  ├─ OrderForm.spec.ts
│     │  └─ types.ts
│     ├─ Inventory/
│     ├─ Product/
│     ├─ Customer/
│     ├─ Supplier/
│     ├─ GLAccount/
│     ├─ Voucher/
│     ├─ User/
│     ├─ Warehouse/
│     ├─ StockTransfer/
│     └─ index.ts
│
├─ stores/ (Pinia)
│  ├─ modules/
│  │  ├─ orders.ts
│  │  ├─ inventory.ts
│  │  ├─ products.ts
│  │  ├─ customers.ts
│  │  ├─ suppliers.ts
│  │  ├─ glAccounts.ts
│  │  ├─ vouchers.ts
│  │  ├─ users.ts
│  │  ├─ warehouses.ts
│  │  └─ stockTransfers.ts
│  ├─ useAuth.ts
│  ├─ useNotification.ts
│  ├─ useRouter.ts
│  └─ index.ts
│
├─ views/ (Page Components)
│  ├─ Order/
│  │  ├─ OrderListPage.vue
│  │  ├─ OrderDetailPage.vue
│  │  └─ OrderCreatePage.vue
│  ├─ Inventory/
│  ├─ Product/
│  ├─ Customer/
│  ├─ Supplier/
│  ├─ GLAccount/
│  ├─ Voucher/
│  ├─ User/
│  ├─ Warehouse/
│  └─ StockTransfer/
│
├─ layouts/
│  ├─ AdminLayout.vue (sidebar + topbar)
│  ├─ BlankLayout.vue (login page)
│  └─ ReportLayout.vue (full-width for exports)
│
├─ composables/ (Vue Composition API utilities)
│  ├─ useForm.ts (form state + validation)
│  ├─ useList.ts (pagination + filtering)
│  ├─ usePagination.ts (page navigation)
│  ├─ useApi.ts (API client wrapper)
│  ├─ useNotification.ts (toast/snackbar)
│  ├─ useValidation.ts (field validation rules)
│  └─ useApproval.ts (approval workflow)
│
├─ services/
│  ├─ api/ (auto-generated from OpenAPI)
│  │  ├─ orderApi.ts
│  │  ├─ inventoryApi.ts
│  │  ├─ productApi.ts
│  │  └─ ...
│  ├─ validators/
│  │  ├─ orderValidators.ts
│  │  ├─ inventoryValidators.ts
│  │  └─ ...
│  └─ formatters/
│     ├─ currencyFormatter.ts
│     ├─ dateFormatter.ts
│     └─ statusFormatter.ts
│
├─ types/
│  ├─ models.ts (OpenAPI models exported)
│  ├─ api.ts (API types)
│  └─ domain.ts (domain-specific types)
│
├─ styles/
│  ├─ global.scss
│  ├─ variables.scss
│  ├─ tabler-overrides.scss
│  └─ animations.scss
│
├─ App.vue
├─ main.ts
└─ router.ts
```

---

## Storybook Organization

### Storybook File Structure
```
.storybook/
├─ main.ts (config)
├─ preview.ts (global setup)
├─ preview-head.html (Tabler CDN + custom fonts)
├─ decorators/
│  ├─ withPinia.ts (global store)
│  ├─ withRouter.ts (mock routing)
│  ├─ withTheme.ts (light/dark mode)
│  └─ withViewport.ts (responsive preview)
└─ manager.ts (UI customization)
```

### Storybook Navigation
```
Storybook
├─ 📦 Primitives (Layer 1) — 30 components, 180 stories
│  ├─ Button (12 stories)
│  ├─ Input (8 stories)
│  ├─ Select (10 stories)
│  ├─ Table (6 stories)
│  ├─ Card (5 stories)
│  ├─ Badge (8 stories)
│  └─ ... (14 more)
│
├─ 📝 Typed Fields (Layer 2) — 12 components, 108 stories
│  ├─ TextField (10 stories)
│  ├─ DateField (8 stories)
│  ├─ CurrencyField (12 stories)
│  ├─ StatusField (8 stories)
│  └─ ... (8 more)
│
├─ 🎯 Domain Fields (Layer 3) — 12 components, 108 stories
│  ├─ OrderLineField (10 stories)
│  ├─ ProductField (12 stories)
│  ├─ CustomerField (10 stories)
│  └─ ... (9 more)
│
├─ 🏢 Business Composites (Layer 4) — 11 components, 55 stories
│  ├─ Order CRUD (5 stories: List, Create, Read, Edit, Delete)
│  ├─ Inventory CRUD (5 stories)
│  ├─ Product CRUD (5 stories)
│  └─ ... (8 more)
│
├─ 🎨 Design System (Typography, Colors, Icons)
│  ├─ Colors (Tabler palette + custom)
│  ├─ Typography (headings, body, mono)
│  └─ Icons (Bootstrap Icons 30 most-used)
│
└─ ✅ Accessibility (WCAG 2.1 AA checklist per component)
   ├─ Keyboard navigation test
   ├─ Screen reader verification
   └─ Color contrast validation
```

### Storybook Configuration (main.ts)
```typescript
export default {
  stories: [
    '../src/components/primitives/**/*.stories.ts',
    '../src/components/fields/typed/**/*.stories.ts',
    '../src/components/fields/domain/**/*.stories.ts',
    '../src/components/composites/**/*.stories.ts',
  ],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y', // Accessibility
    '@storybook/addon-viewport', // Responsive
    '@storybook/addon-interactions', // User interactions
    '@storybook/addon-controls', // Dynamic props
    '@storybook/addon-measure', // Inspect dimensions
  ],
  framework: '@storybook/vue3',
  docs: {
    autodocs: true, // Auto-generate docs from comments
  },
};
```

---

## Testing Strategy

### Test Distribution (Testing Pyramid — Principle 26)

```
        /\           E2E (20%)
       /  \          50 scenarios for full workflows
      /____\
     /      \        Integration (30%)
    /        \       150 tests for component interactions
   /_________ \
  /           \     Unit (50%)
 /             \    350 tests for individual components
/_____________\
```

### Unit Tests (Layer 1-3 components)
- **Primitives**: Button click, Input change events, Select options
- **Typed Fields**: Validation rules, formatting (date → ISO, currency → comma-sep)
- **Domain Fields**: Business rule checks, API call mocking

**File**: `src/components/**/*.spec.ts`  
**Runner**: Vitest + @testing-library/vue  
**Coverage Target**: 70%+

### Integration Tests (Layer 4 composites)
- **CRUD Workflows**: Create → Read → Update → Delete
- **Validation Chains**: Form validation + API error handling
- **State Management**: Pinia store mutations + selections

**File**: `src/components/composites/**/*.spec.ts`  
**Runner**: Vitest + MSW (Mock Service Worker)  
**Mocks**: OpenAPI endpoints

### E2E Tests (Full User Journeys)
- **Order Flow**: Create customer → Create order → Ship → Deliver
- **Approval Matrix**: High-value order → Supervisor approval → Finance review
- **Inventory Adjustment**: Adjust stock → Audit log verification

**File**: `tests/e2e/**/*.spec.ts`  
**Runner**: Playwright (6.0+)  
**Scenarios**: 116 total (11 CRUD × 10-15 scenarios per entity)

**Example E2E Test**:
```typescript
test('Order workflow: create → approve → ship', async ({ page }) => {
  // 1. Login
  await page.goto('/Account/Login');
  await page.fill('[name="email"]', 'manager@example.com');
  await page.fill('[name="password"]', 'password123!');
  await page.click('button[type="submit"]');
  
  // 2. Create order
  await page.goto('/admin/orders');
  await page.click('button:text("Create Order")');
  await page.selectOption('[name="customerId"]', 'CUST-001');
  await page.fill('[name="quantity"]', '100');
  await page.click('button:text("Submit")');
  await expect(page).toHaveURL(/\/admin\/orders\/\d+/);
  
  // 3. Supervisor approval
  await page.click('button:text("Request Approval")');
  await page.logout();
  
  // ... login as supervisor ...
  
  // 4. Approve
  await page.click('button:text("Approve")');
  await expect(page).toContainText('Order approved');
  
  // 5. Audit log verification
  await page.goto('/admin/audit-logs?entity=orders&entityId=123');
  await expect(page).toContainText('created_by: manager@example.com');
  await expect(page).toContainText('modified_by: supervisor@example.com');
});
```

---

## Figma Design System (Specification)

### Color Palette (Tabler Base)
- **Primary**: #0D6EFD (Bootstrap Blue)
- **Success**: #198754 (Bootstrap Green)
- **Danger**: #DC3545 (Bootstrap Red)
- **Warning**: #FFC107 (Bootstrap Amber)
- **Info**: #0DCAF0 (Bootstrap Cyan)
- **Dark**: #2C3E50 (Custom Sidebar)
- **Light**: #F5F7FB (Custom Background)

### Typography
- **Headings**: Inter Medium (600), 24px/20px/18px/16px/14px
- **Body**: Inter Regular (400), 14px/16px
- **Mono**: IBM Plex Mono, 12px (for GL account codes, order numbers)

### Component Sizes
- **Button**: sm (32px) / md (40px) / lg (48px)
- **Input**: sm (32px) / md (40px) / lg (48px)
- **Table Row**: 44px
- **Card Padding**: 20px
- **Border Radius**: 6px (default), 12px (card), 0px (table)

### Spacing (8px grid)
- Margins: 0, 8, 16, 24, 32, 40px
- Padding: 8, 12, 16, 20, 24px

### Interactive States
- **Hover**: 10% opacity overlay
- **Focus**: 2px outline, 4px blue (#0D6EFD)
- **Disabled**: 50% opacity, cursor not-allowed
- **Loading**: Spinner overlay, pointer-events none

---

## Accessibility Requirements (WCAG 2.1 AA)

### Per-Component Checklist

| Component | Keyboard | Screen Reader | Color | Focus |
|-----------|----------|---------------|-------|-------|
| **Button** | Tab + Enter | aria-label | 4.5:1 contrast | Visible outline |
| **Input** | Tab + Type | aria-label + aria-describedby (error) | Error text 4.5:1 | Visible outline |
| **Table** | Tab + arrows | scope + aria-sort | Text 4.5:1 | Row highlight |
| **Modal** | Tab + Escape | role="dialog", focus trap | Background 3:1 | Focused element |
| **Select** | Tab + arrows | aria-expanded + aria-controls | 4.5:1 contrast | Dropdown highlight |

### Automated Validation
- **Tool**: axe-core (Storybook addon)
- **Target**: 95+ axe score per component
- **CI Gate**: No accessibility violations in main branch

---

## Migration Path (Phase 1-4)

### Phase 1: Setup (Week 1-2)
- [ ] Vite scaffold + TypeScript strict mode
- [ ] Storybook 7.0 setup + Tabler theme
- [ ] ESLint + Prettier config
- [ ] Primitives folder structure created

### Phase 2: Primitives (Week 3-4)
- [ ] 30 Primitive components built
- [ ] 180 Storybook stories written
- [ ] Unit test: 70%+ coverage
- [ ] Accessibility audit: axe 95+
- [ ] Design system published (Figma library link)

### Phase 3: Typed + Domain Fields (Week 5-6)
- [ ] 12 Typed Field components built + 108 stories
- [ ] 12 Domain Field components built + 108 stories
- [ ] Integration tests for field validation chains
- [ ] API client auto-generated from OpenAPI spec

### Phase 4: Business Composites (Week 7-8)
- [ ] 11 full CRUD components built + 55 stories
- [ ] 116 E2E tests passing
- [ ] Responsive design verified (mobile, tablet, desktop)
- [ ] Performance: LCP <2.5s, TTI <3s, CLS <0.1

---

## Sign-Off

- **UX/Design Lead**: _________________ Date: _______
- **Frontend Tech Lead**: _________________ Date: _______
- **QA Lead**: _________________ Date: _______

---

**Document Version**: 1.0  
**Last Updated**: 2026-07-26  
**Figma Designs**: [Link to Figma project TBD]  
**Next Milestone**: Phase 1 Vite scaffold + ESLint setup (2026-08-02)