id3-cli 0.9.1

package/templates/skills/id3-design-ui/references/step2-visual-contract.md

@@ -0,0 +1,257 @@
+# Step 2: Visual Design Contract
+
+This reference details how to detect the frontend stack and establish design tokens. The lead agent executes this step conversationally with the user.
+
+---
+
+## Inputs
+
+| File | Purpose |
+|------|---------|
+| `specs/ui-structure.md` | Finalized screen inventory from Step 1 |
+| `specs/entity-catalog.md` | Entity attributes for widget-to-token mapping |
+| `docs/business-rules.md` | BR-xxx rules for validation message templates |
+
+---
+
+## Framework Detection
+
+Scan the project root to detect the existing frontend stack. Check each indicator in order:
+
+| Detect Target | File Patterns | Result |
+|--------------|---------------|--------|
+| React | `package.json` contains `react`, `*.jsx`/`*.tsx` files | React detected |
+| Vue | `package.json` contains `vue`, `*.vue` files | Vue detected |
+| Svelte | `package.json` contains `svelte`, `*.svelte` files | Svelte detected |
+| Next.js | `next.config.*`, `app/` or `pages/` directory | Next.js detected |
+| Nuxt | `nuxt.config.*` | Nuxt detected |
+| Tailwind CSS | `tailwind.config.*` | Tailwind detected |
+| shadcn/ui | `components.json`, `@/components/ui/` directory | shadcn detected |
+| Radix UI | `@radix-ui/*` in package.json dependencies | Radix detected |
+| MUI | `@mui/*` in package.json dependencies | MUI detected |
+| None | No frontend files found | Greenfield |
+
+### User Confirmation
+
+After detection, confirm with the user:
+- **Detected stack:** "React + Tailwind + shadcn/ui detected. Proceed with this stack?"
+- **Greenfield:** "No frontend stack detected. Please choose: (A) React + Tailwind + shadcn/ui, (B) Vue + Tailwind, (C) Svelte + Tailwind, (D) Specify your own"
+
+Record the confirmed stack in the contract.
+
+---
+
+## 5 Design Token Areas
+
+### 1. Spacing Scale
+
+Default proposal: **8-point grid**
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| space-0.5 | 2px | Hairline gaps |
+| space-1 | 4px | Inline padding, icon gaps |
+| space-2 | 8px | Input padding, small gaps |
+| space-3 | 12px | Card padding (compact) |
+| space-4 | 16px | Section gaps, form field margins |
+| space-6 | 24px | Card padding (standard) |
+| space-8 | 32px | Section separators |
+| space-12 | 48px | Page section gaps |
+| space-16 | 64px | Major layout gaps |
+
+**Rule:** All spacing values in the project MUST be multiples of the base unit (4px). Arbitrary pixel values are rejected by the 7-Pillar gate.
+
+### 2. Typography Scale
+
+Default proposal: **4-level hierarchy** with maximum 2 font weights.
+
+| Token | Size | Weight | Line Height | Usage |
+|-------|------|--------|-------------|-------|
+| display | 36px | 700 | 1.2 | Page titles, hero headings |
+| heading | 24px | 600 | 1.3 | Section headings, card titles |
+| body | 16px | 400 | 1.5 | Body text, form labels, table cells |
+| caption | 14px | 400 | 1.4 | Help text, timestamps, metadata |
+| mono | 14px | 400 | 1.4 | Code snippets, IDs, technical values |
+
+**Rule:** Do not exceed 4 sizes and 2 weights. Additional variation creates visual noise. If more levels are needed, ask the user to justify.
+
+### 3. Color System
+
+Default proposal: **60/30/10 ratio**
+
+| Token | Light Mode | Dark Mode | Ratio | Usage |
+|-------|-----------|-----------|-------|-------|
+| surface | #ffffff | #0a0a0b | 60% | Page backgrounds, card backgrounds |
+| secondary | #6b7280 | #9ca3af | 30% | Borders, inactive text, dividers |
+| accent | _(user choice)_ | _(user choice)_ | 10% | CTAs, active states, links, focus rings |
+
+**Semantic Colors** (fixed):
+
+| Token | Light | Dark | Usage |
+|-------|-------|------|-------|
+| success | #22c55e | #4ade80 | Confirmation, completed states |
+| warning | #eab308 | #facc15 | Caution, pending states |
+| error | #ef4444 | #f87171 | Validation errors, destructive actions |
+| info | #3b82f6 | #60a5fa | Informational messages, tips |
+
+**Rule:** Only one accent color. Using multiple accent colors dilutes focus. The 7-Pillar gate blocks contracts with more than 1 accent.
+
+### 4. Copywriting Standards
+
+Define text patterns for all common UI scenarios. Every user-facing string follows a template.
+
+| Pattern | Template | Example |
+|---------|----------|---------|
+| CTA Primary | "Create [Entity]" | "Create User" |
+| CTA Secondary | "Save [Entity]" | "Save User" |
+| CTA Destructive | "Delete [Entity]" | "Delete User" |
+| Empty State | "No [entities] yet. Create your first [entity]." | "No users yet. Create your first user." |
+| Error Required | "[Field] is required." | "Email is required." |
+| Error Format | "[Field] must be a valid [type]." | "Email must be a valid email address." |
+| Error Unique | "[Field] already exists." | "Email already exists." |
+| Danger Confirm | "This will permanently delete [entity]. This cannot be undone." | "This will permanently delete this user. This cannot be undone." |
+| Success | "[Entity] [action] successfully." | "User created successfully." |
+| Loading | "Loading [entities]..." | "Loading users..." |
+
+**Tone:** Confirm with user -- Professional (formal), Friendly (casual), or Terse (minimal).
+
+**Rule:** Generic labels like "Submit", "Click here", or "OK" are rejected by the 7-Pillar gate. Every CTA must use a specific verb + entity name.
+
+### 5. Component Registry
+
+Map each widget type (from Step 1's attribute-to-widget mapping) to a concrete framework component.
+
+**Example (shadcn/ui):**
+
+| Widget | Component | Import Path |
+|--------|-----------|-------------|
+| Text Input | `<Input />` | `@/components/ui/input` |
+| Textarea | `<Textarea />` | `@/components/ui/textarea` |
+| Select Dropdown | `<Select />` | `@/components/ui/select` |
+| Toggle/Checkbox | `<Switch />` | `@/components/ui/switch` |
+| Number Input | `<Input type="number" />` | `@/components/ui/input` |
+| Date Picker | `<DatePicker />` | `@/components/ui/date-picker` |
+| DateTime Picker | `<DateTimePicker />` | `@/components/ui/datetime-picker` |
+| Autocomplete | `<Combobox />` | `@/components/ui/combobox` |
+| Hidden/Read-only | _(not rendered)_ | -- |
+| File Upload | `<FileUpload />` | `@/components/ui/file-upload` |
+| Specialized Input | `<Input type="email" />` | `@/components/ui/input` |
+| JSON Editor | `<Textarea />` or custom | `@/components/ui/textarea` |
+
+**Example (MUI):**
+
+| Widget | Component | Import Path |
+|--------|-----------|-------------|
+| Text Input | `<TextField />` | `@mui/material/TextField` |
+| Select Dropdown | `<Select />` | `@mui/material/Select` |
+| Toggle/Checkbox | `<Switch />` | `@mui/material/Switch` |
+| ... | ... | ... |
+
+**Example (plain HTML + Tailwind):**
+
+| Widget | Component | CSS Classes |
+|--------|-----------|-------------|
+| Text Input | `<input type="text" />` | `border rounded px-3 py-2` |
+| Textarea | `<textarea />` | `border rounded px-3 py-2 min-h-24` |
+| ... | ... | ... |
+
+**Rule:** Every widget from the attribute-to-widget mapping MUST have a corresponding component entry. Unmapped widgets are rejected by the 7-Pillar gate.
+
+---
+
+## Entity Attribute to Design Token Connection (IDDD Differentiator)
+
+For each attribute in every entity, trace the full chain from information model to visual representation. This is what makes IDDD unique -- every visual decision is justified by the data model.
+
+```
+Entity: User
+  Attribute: email (VARCHAR, NOT NULL, UNIQUE)
+    -> Widget: Specialized Input (email type)         [from Attribute-to-Widget rule #12]
+    -> Component: <Input type="email" />              [from Component Registry]
+    -> Validation: required + unique check             [from NOT NULL + UNIQUE constraints]
+    -> BR-003: "Email must be unique"                  [from business-rules.md]
+    -> Spacing: mb-16px (token: space-4)               [from Spacing Scale]
+    -> Typography: Body (16px/400)                     [from Typography Scale]
+    -> Error Messages:
+       - "Email is required."                          [from Copywriting: Error Required]
+       - "Email already exists."                       [from Copywriting: Error Unique]
+       - "Email must be a valid email address."        [from Copywriting: Error Format]
+```
+
+Document this chain for every attribute in the Per-Screen Design Spec section of the contract.
+
+---
+
+## Output: `specs/ui-design-contract.md`
+
+Write the finalized design contract using this format:
+
+```markdown
+---
+version: "1.0"
+framework: "React + Next.js"
+ui_library: "shadcn/ui"
+css: "Tailwind CSS"
+derived_from: "ui-structure.md v1.0"
+---
+
+# UI Design Contract
+
+## Tech Stack
+- **Framework:** React 19 + Next.js 15 (App Router)
+- **UI Library:** shadcn/ui (Radix primitives)
+- **Styling:** Tailwind CSS v4
+- **Icons:** Lucide React
+
+## Design Tokens
+
+### Spacing
+| Token | Value | Usage |
+|-------|-------|-------|
+| space-1 | 4px | Inline padding, icon gaps |
+| space-2 | 8px | Input padding, small gaps |
+| ...
+
+### Typography
+| Token | Size | Weight | Line Height | Usage |
+|-------|------|--------|-------------|-------|
+| display | 36px | 700 | 1.2 | Page titles |
+| ...
+
+### Colors
+| Token | Light | Dark | Usage |
+|-------|-------|------|-------|
+| surface | #ffffff | #0a0a0b | Backgrounds |
+| accent | #3b82f6 | #60a5fa | CTAs, active states |
+| ...
+
+### Copywriting
+| Pattern | Template | Example |
+|---------|----------|---------|
+| CTA Primary | "Create [Entity]" | "Create User" |
+| ...
+
+## Component Mapping
+| Widget | Component | Import |
+|--------|-----------|--------|
+| Text Input | <Input /> | @/components/ui/input |
+| ...
+
+## Per-Screen Design Spec
+
+### User List (/users)
+| Attribute | Widget | Component | Tokens | Validation |
+|-----------|--------|-----------|--------|------------|
+| name | Text Input | <Input /> | body, space-4 | required |
+| email | Specialized Input | <Input type="email" /> | body, space-4 | required, unique, BR-003 |
+| ...
+```
+
+### Completeness Check
+
+Before writing the file, verify:
+- [ ] Tech stack is confirmed with user
+- [ ] All 5 design token areas are populated
+- [ ] Every widget from ui-structure.md has a component mapping
+- [ ] Per-screen design spec covers all screens from ui-structure.md
+- [ ] Entity-attribute-to-token chain is documented for every visible attribute

package/templates/skills/id3-design-ui/references/step3-gate-and-mockup.md

@@ -0,0 +1,177 @@
+# Step 3: Pre-Implementation Gate + Visual Mockup Review
+
+This reference details the 7-Pillar quality gate, HTML mockup generation, and user approval process. The lead agent executes the gate automatically, then presents mockups for user review.
+
+---
+
+## Inputs
+
+| File | Purpose |
+|------|---------|
+| `specs/ui-structure.md` | Screen inventory and traceability matrix |
+| `specs/ui-design-contract.md` | Design tokens, component mapping, copywriting |
+| `specs/entity-catalog.md` | Entity list for coverage verification |
+
+---
+
+## 7-Pillar Verification
+
+Run each pillar check against the design artifacts. ALL pillars must PASS before mockup generation proceeds.
+
+| # | Pillar | Source Document | PASS Condition | BLOCKED Condition |
+|---|--------|----------------|----------------|-------------------|
+| 1 | Structure Completeness | ui-structure.md | Every entity in entity-catalog.md has at least 1 screen mapped. Entity coverage = 100%. | Entity coverage < 100% |
+| 2 | Spacing | ui-design-contract.md | All spacing values are multiples of the base unit (default: 4px in an 8-point grid). | Any arbitrary value not in the spacing scale |
+| 3 | Typography | ui-design-contract.md | 4 or fewer font sizes defined. 2 or fewer font weights defined. | More than 4 sizes or more than 2 weights |
+| 4 | Color | ui-design-contract.md | Exactly 1 accent color with usage documented. All 4 semantic colors (success, warning, error, info) defined. | Accent undefined, or more than 1 accent, or missing semantic colors |
+| 5 | Copywriting | ui-design-contract.md | CTA, empty state, error, and danger patterns defined. No generic text ("Submit", "Click here", "OK"). | Missing patterns or generic text found |
+| 6 | Component Registry | ui-design-contract.md | Every widget type from ui-structure.md has a mapped component with import path or CSS classes. | Any widget without a component mapping |
+| 7 | Traceability | Both documents | Every screen in ui-structure.md has an entity source. Every widget in the per-screen spec has an attribute source. | Any screen or widget without traceable origin |
+
+### Gate Result Format
+
+Write the gate result to `.iddd/ui-gate-result.md`:
+
+```markdown
+---
+timestamp: "YYYY-MM-DDTHH:MM:SS"
+verdict: "PASS"  # or "BLOCKED"
+---
+
+# UI Gate Result
+
+| # | Pillar | Status | Details |
+|---|--------|--------|---------|
+| 1 | Structure Completeness | PASS | 12/12 entities covered (100%) |
+| 2 | Spacing | PASS | All values on 8-point grid |
+| 3 | Typography | PASS | 4 sizes, 2 weights |
+| 4 | Color | PASS | 1 accent (#3b82f6), 4 semantic colors |
+| 5 | Copywriting | PASS | 4 patterns defined, no generic text |
+| 6 | Component Registry | PASS | 12/12 widgets mapped |
+| 7 | Traceability | PASS | 15/15 screens traced, 48/48 widgets traced |
+
+**Verdict: PASS** -- Proceed to mockup generation.
+```
+
+If BLOCKED, list the specific violations under each failing pillar and fix them before re-running the gate.
+
+---
+
+## Mockup Generation
+
+After the 7-Pillar gate passes, generate HTML mockup files from `ui-structure.md` and `ui-design-contract.md`.
+
+### Generation Principle
+
+```
+Entity: User
+  ui-structure.md -> List View, Detail View, Create Form, Edit Form
+  ui-design-contract.md -> shadcn Table, Card, Input + spacing 8pt + accent blue
+
+  -> mockup-users.html:
+    - List View: styled Table with actual column headers from entity attributes
+    - Detail View: Card layout with attribute grouping + relationship tabs
+    - Create Form: Input/Select/Toggle with validation message placeholders
+    - All views apply design tokens (colors, spacing, typography)
+```
+
+### 3 Fidelity Levels
+
+Each entity mockup file contains 3 switchable tabs:
+
+| Level | Content | Purpose |
+|-------|---------|---------|
+| **Wireframe** | Layout structure only -- gray boxes, monospace labels, no color | Verify screen structure and field ordering |
+| **Styled** | Design tokens applied -- accent colors, typography scale, spacing grid | Verify visual design contract compliance |
+| **Interactive** | Sample data populated + state transitions simulated | Verify data presentation and user flow |
+
+Users switch between levels using tabs at the top of each mockup page.
+
+### Sample Data Auto-Generation
+
+Populate the Interactive tab with realistic sample data based on attribute types:
+
+| Attribute Type | Sample Data Examples |
+|---------------|---------------------|
+| VARCHAR (name) | "Alice Johnson", "Bob Smith", "Carol Williams" |
+| Email | "alice@example.com", "bob@example.com" |
+| ENUM (status) | "Active", "Inactive", "Pending" (from enum values) |
+| TIMESTAMP | "2026-04-05 14:30", "2026-03-28 09:15" |
+| INTEGER (count) | 42, 128, 7 |
+| DECIMAL (price) | 19.99, 149.50, 9.95 |
+| FK (organization_id) | "Acme Corp", "Globex Inc", "Initech" |
+| BOOLEAN | Toggle ON/OFF states |
+| DATE | "2026-04-05", "2026-03-28" |
+| UUID (PK) | Hidden from display |
+
+Generate at least 3 sample rows for list views and 1 complete record for detail/form views.
+
+### Mockup File Structure
+
+| File | Content |
+|------|---------|
+| `.iddd/preview/mockup-index.html` | Index page with left navigation listing all screens grouped by entity. Links to per-entity mockups. |
+| `.iddd/preview/mockup-{entity}.html` | Per-entity mockup with 3 fidelity tabs. Includes all screen patterns for that entity (list, detail, create, edit, dashboard, etc.). |
+
+### Preview Server UI Layout
+
+The mockup preview provides a specific layout optimized for design review:
+
+- **Left panel:** Screen navigation grouped by entity. Click to navigate between entity mockups.
+- **Center panel:** Active mockup with 3 fidelity tabs (Wireframe / Styled / Interactive).
+- **Bottom panel:** Traceability information showing:
+  - Entity and Attribute source for each UI element
+  - Design token values applied (spacing, typography, color)
+  - BR-xxx rule references for validation logic
+  - Widget-to-Component mapping used
+
+This bottom traceability panel is the IDDD differentiator. It makes visible why each UI element exists and how it is styled -- all traceable to the information model.
+
+---
+
+## User Approval Process
+
+### Presenting for Review
+
+1. Start the preview server: files are served from `.iddd/preview/`.
+2. Display the preview URL in the terminal.
+3. Announce: "Mockup preview is ready at [URL]. Please review all screens across 3 fidelity levels. The traceability panel shows the Entity/Attribute source for each element."
+
+### Collecting Feedback
+
+The user responds with one of:
+
+- **`approve`** -- All mockups are acceptable. Proceed to Step 4 (Implementation).
+- **`reject`** + specific feedback -- The user describes what needs to change. Examples:
+  - "Move the status filter above the table in User List"
+  - "Add a confirmation dialog before delete"
+  - "Change the dashboard layout to 2-column grid"
+  - "The Create Form should group personal info and contact info separately"
+
+### Handling Rejection
+
+When the user rejects with feedback:
+
+1. **Analyze the feedback** against ui-structure.md and ui-design-contract.md.
+2. **Update the relevant spec file:**
+   - Screen structure changes -> update ui-structure.md
+   - Design token changes -> update ui-design-contract.md
+   - New screens -> add to ui-structure.md with Source = "User-requested"
+3. **Re-run the 7-Pillar gate** to verify changes maintain compliance.
+4. **Regenerate mockups** for affected entities.
+5. **Present again** for approval.
+
+Repeat until the user approves.
+
+### Approval Record
+
+When approved, update `.iddd/ui-gate-result.md`:
+
+```markdown
+## User Approval
+
+- **Status:** Approved
+- **Timestamp:** YYYY-MM-DDTHH:MM:SS
+- **Review rounds:** N
+- **Changes from review:** [summary of changes made during rejection cycles]
+```

package/templates/skills/id3-design-ui/references/step4-implementation.md

@@ -0,0 +1,244 @@
+# Step 4: Implementation + Post-Audit
+
+This reference details the Agent Teams implementation strategy and post-implementation visual audit. The lead agent orchestrates team members and performs the final audit.
+
+---
+
+## Inputs
+
+| File | Purpose |
+|------|---------|
+| `specs/ui-structure.md` | Screen inventory and navigation structure |
+| `specs/ui-design-contract.md` | Design tokens, component mapping, per-screen specs |
+| `specs/entity-catalog.md` | Entity definitions and relationships |
+| `specs/data-model.md` | ERD for FK dependency ordering |
+| `docs/business-rules.md` | BR-xxx rules for validation implementation |
+| `.iddd/ui-gate-result.md` | Approved gate result with user sign-off |
+
+---
+
+## Agent Teams Composition
+
+The lead agent spawns a team with these roles after the user approves mockups in Step 3:
+
+| Role | Count | Responsibility | Reference Files |
+|------|-------|---------------|----------------|
+| ui-implementer-N | 1 per entity group (1-3 entities) | Implement screen code for assigned entities | ui-structure.md, ui-design-contract.md, entity-catalog.md, data-model.md, business-rules.md |
+| ui-reviewer | 1 | Verify design token consistency and traceability across ALL screens | ui-design-contract.md, ui-gate-result.md |
+
+### Team Member Context Files
+
+When spawning each team member, provide these files:
+
+1. `specs/entity-catalog.md`
+2. `specs/data-model.md`
+3. `specs/ui-structure.md`
+4. `specs/ui-design-contract.md`
+5. `docs/business-rules.md`
+6. `steering/data-conventions.md`
+7. `CLAUDE.md`
+
+---
+
+## Task Division Rules
+
+### Entity-Based Splitting
+
+Each ui-implementer handles all screens for 1-3 entities. An entity's screens (List, Detail, Create, Edit, Dashboard, Child Tab) are never split across team members.
+
+### FK Dependency Ordering
+
+1. Read the ERD from `specs/data-model.md` to build a dependency graph.
+2. **Independent entities** (no FK to other project entities) can be implemented in parallel.
+3. **Dependent entities** wait for their parent entity's screens to be complete.
+4. Within each dependency wave, assign entity groups to team members for parallel execution.
+
+### Common Layout First
+
+The **first ui-implementer** (assigned the most-connected or root entity) is responsible for creating shared layout components before their entity screens:
+
+1. Root layout (HTML shell, global CSS, font loading)
+2. Navigation component (sidebar/header matching the navigation structure from ui-structure.md)
+3. Shared UI primitives (if not using a component library)
+
+Other implementers wait for the common layout to be committed before starting.
+
+### Example Task Assignment
+
+```
+Entity dependency graph:
+  Organization (root, no FK)
+  User (FK -> Organization)
+  Post (FK -> User)
+  Comment (FK -> Post, FK -> User)
+  Tag (no FK)
+  PostTag (FK -> Post, FK -> Tag)
+
+Wave 1 (parallel):
+  ui-implementer-1: Organization (+ common layout) + Tag
+  ui-implementer-2: (waits for layout from implementer-1)
+
+Wave 2 (parallel, after Organization + Tag):
+  ui-implementer-2: User
+  ui-implementer-3: Post
+
+Wave 3 (parallel, after User + Post):
+  ui-implementer-2: Comment
+  ui-implementer-3: PostTag
+```
+
+---
+
+## Implementation Principles (5 Rules)
+
+Every ui-implementer MUST follow these rules:
+
+### 1. Follow the Component Mapping Exactly
+
+Use the exact component and import path specified in ui-design-contract.md's Component Mapping table. Do not substitute alternative components without lead agent approval.
+
+### 2. Apply Design Tokens Directly
+
+Translate design tokens to code:
+- **Tailwind:** Use utility classes that map to token values (e.g., `mb-4` for space-4 = 16px)
+- **CSS Variables:** Define tokens as CSS custom properties and reference them
+- **Inline styles:** Only as a last resort, and only using token values
+
+Never use arbitrary pixel values. Every spacing, font size, and color MUST come from the design token table.
+
+### 3. Add Traceability Comments
+
+For each major UI section, add a comment linking to the information model:
+
+```tsx
+{/* Entity: User | Attribute: email | Widget: Specialized Input | BR-003 */}
+<Input type="email" placeholder="Email" required />
+```
+
+These comments enable post-audit traceability verification.
+
+### 4. Implement BR-xxx Validation
+
+For each business rule referenced in the per-screen design spec:
+- Add client-side validation matching the rule description
+- Use the copywriting templates from the design contract for error messages
+- Reference the BR-xxx identifier in a code comment
+
+```tsx
+// BR-003: Email must be unique
+const validateEmail = async (email: string) => {
+  if (!email) return "Email is required."; // Copywriting: Error Required
+  const exists = await checkEmailExists(email);
+  if (exists) return "Email already exists."; // Copywriting: Error Unique
+  return null;
+};
+```
+
+### 5. Atomic Commits Per Entity
+
+Each entity's screen group is committed as a single atomic unit:
+- Commit message: `feat(ui): implement {Entity} screens (list/detail/create/edit)`
+- Include all files for that entity: components, routes, validation, styles
+- Do NOT commit partial screen implementations
+
+---
+
+## Implementation Order (Within Each Entity)
+
+Each ui-implementer follows this sequence for their assigned entity:
+
+1. **Layout + Routing:** Set up the route/page structure for all screens of this entity.
+2. **Data Fetching:** Connect to API endpoints or create mock data providers.
+3. **UI Component Placement:** Build the screen layout using components from the registry, applying design tokens.
+4. **Validation:** Implement BR-xxx rules with copywriting-compliant error messages.
+5. **State Transitions:** If the entity has state transitions, implement status change UI (buttons, confirmations, status badges).
+6. **Responsive Handling:** Ensure screens work on mobile (stack layout) and desktop (side-by-side).
+
+---
+
+## Post-Implementation Audit
+
+After ALL ui-implementers have committed their work and the ui-reviewer has verified consistency, the lead agent performs a visual audit.
+
+### Audit Procedure
+
+1. **Start the development server** (e.g., `npm run dev`).
+2. **Navigate to each implemented screen** in the browser.
+3. **Compare actual rendering against the mockup HTML** from Step 3.
+4. **Score each pillar on a 1-4 scale** per the criteria below.
+
+### Audit Scoring Criteria
+
+| Pillar | 4 (Excellent) | 3 (Good) | 2 (Fair) | 1 (Poor) |
+|--------|---------------|----------|----------|----------|
+| Structure | 100% of screens implemented | >90% implemented | >70% implemented | <70% implemented |
+| Spacing | All values match design tokens | 1-2 violations | 3-5 violations | >5 violations |
+| Typography | Exact match with contract | 1 deviation | 2 deviations | >2 deviations |
+| Color | All colors correct | 1 misuse | 2-3 misuses | >3 misuses |
+| Copywriting | All text matches templates | 1-2 generic labels | 3-5 generic labels | >5 generic labels |
+| Component Registry | All specified components used | 1-2 substitutions | 3-5 substitutions | >5 substitutions |
+| Traceability | All elements have source comments | >80% traced | >50% traced | <50% traced |
+
+### Audit Result: Top 3 Priority Fixes
+
+After scoring, identify the **3 most impactful fixes** based on:
+1. **User visibility:** Issues on frequently visited screens rank higher
+2. **Severity:** Structural issues > visual issues > comment issues
+3. **Fix effort:** Quick fixes are prioritized for immediate resolution
+
+Format each fix as:
+
+```markdown
+### Fix 1: [Description]
+- **Pillar:** [affected pillar]
+- **Screen:** [affected screen URL]
+- **Current:** [what is wrong]
+- **Expected:** [what the contract specifies]
+- **Action:** [specific steps to fix]
+```
+
+### Audit Verdict
+
+| Average Score | Verdict | Action |
+|--------------|---------|--------|
+| >= 3.0 | **PASS** | "UI implementation complete. Proceed to Phase 3-5." |
+| < 3.0 | **NEEDS FIXES** | Apply Top 3 fixes, then re-audit. |
+
+### Re-Audit Process
+
+If the average score is below 3.0:
+
+1. The lead agent assigns the Top 3 fixes to the appropriate ui-implementer(s).
+2. Implementers apply fixes and commit.
+3. The lead agent re-audits only the affected screens.
+4. Repeat until average >= 3.0.
+
+---
+
+## Audit Report Output
+
+Write the audit report to `.iddd/preview/ui-audit.html` as an interactive dashboard:
+
+- **Header:** Overall score (average across all pillars) with pass/fail badge
+- **Pillar Cards:** One card per pillar showing score (1-4), status indicator, and specific findings
+- **Screen-by-Screen Breakdown:** Each implemented screen with its individual pillar scores
+- **Top 3 Fixes:** Highlighted section with the priority fixes described above
+- **Comparison View:** Side-by-side panels showing mockup screenshot vs actual rendering (if available)
+
+Also update `specs/ui-structure.md` YAML frontmatter:
+
+```yaml
+audit_status: "clean"  # or "needs-fixes"
+audit_score: "3.5"
+audit_date: "YYYY-MM-DD"
+```
+
+---
+
+## Completion
+
+When the audit passes (average >= 3.0):
+
+1. Update `specs/ui-structure.md` frontmatter with `audit_status: "clean"`.
+2. Add entry to `docs/model-changelog.md`.
+3. The lead agent announces: "UI implementation complete. N screens implemented, audit score X.X/4.0. Proceed to Phase 3-5 (/id3-spawn-team) for backend implementation."