---
artifact-status: draft   # draft | approved — approval state of this generated file (gate reads this)
---
# UI/UX Design: {Product / Surface}

> **Last Updated:** [Date]  ·  **Author:** [PE name]  ·  **PRD Reference:** docs/prd.md
> **Stage 02 is optional** — decided at kick-off and recorded in `tas.yaml`. A project with no UI (pure API / service / batch / pipeline) skips this whole artifact and its Design Spec.

> **What this file is:** the governance + traceability index for the UI. The **visual source of truth is the Generated Screens** — the actual HTML/code produced by Claude Design in `docs/ui/`. This document does NOT re-describe those screens in prose (that would drift); it assigns stable `SCR-NNN` IDs, maps each screen to the FRs it covers, and records the content/constraints the coding agent and testers need. The Design Token / Component / Breakpoint values are extracted downstream into `docs/design-spec.md`, not here.

---

## 1. Screen Inventory

> Every screen that covers the PRD user flows, each with a stable `SCR-NNN` ID, its navigation (entry from / exit to), the FR(s) it covers, and a pointer to its Generated Screen file. Navigation is folded in here — no separate flow diagram.
> **Coverage rule:** every `PRD.FR` that has a UI must be covered by ≥1 screen; every screen traces to ≥1 FR (no orphan screen). The coverage-auditor checks both directions at the UI/UX gate.

| ID | Screen | Covers FR | Entry from | Exit to | Generated Screen (file) |
|----|--------|-----------|------------|---------|-------------------------|
| SCR-001 | [e.g. Product List] | FR-001 | Home | SCR-002 | `docs/ui/product-list.html` |
| SCR-004 | [e.g. Checkout] | FR-005 | Cart | SCR-005 Order Confirmation | `docs/ui/checkout.html` |

---

## 2. Screen Content Map

> Per screen: what data is shown, what input is collected, the actions, the states that must be drawn, and the validation rules. This is the decision block that keeps Claude Design from inventing screens, and it is what functional/E2E tests verify against. Reference `E-NNN` (data), `FR-NNN` (action trigger), `BRU-NNN` (validation rule), and `BRD.Entity State` (states).

### SCR-004 Checkout
- **Shows:** {e.g. Order.items[] (E-003), order total}
- **Collects:** {e.g. shipping address, payment method}
- **Actions:** {e.g. Submit → triggers FR-005}
- **Validation:** {e.g. BRU-001 order confirmed only on payment success}
- **States:** {e.g. empty cart, processing, payment error, success — per E-003 Order states}

---

## 3. UI Constraints

> Design constraints: accessibility level, responsive target range, localization, browser support, any performance budget affecting UI, and the parts explicitly NOT to be designed (from PRD.Out of Scope). Sourced from PRD.NFR + PRD.Out of Scope.

- **Accessibility:** {e.g. WCAG 2.1 AA}
- **Responsive target:** {e.g. 360px → 1440px}
- **Localization:** {e.g. vi + en}
- **Browser support:** {e.g. last 2 versions of evergreen browsers}
- **Not designed (OOS):** {e.g. admin console}

---

## 4. Design System Seed

> The starting direction only — typography, color, spacing seed and the intended tone. This seeds Claude Design; the final, authoritative token/component values are extracted from the Generated Screens into `docs/design-spec.md`. Design intent (tone) comes from `PRD.Product Goal` + `PRD.User Persona`, not from BRD.

- **Primary / accent:** {e.g. #0057FF}
- **Type:** {e.g. Inter}
- **Spacing base:** {e.g. 8px}
- **Tone / intent:** {e.g. trustworthy, minimal, for a busy shopper — from PG-001}

---

## 5. Generated Screens

> The Design Brief (assembled by `/tas-design-uiux` from sections 1-4 plus framing) is fed to Claude Design, which produces the actual screens as HTML/code under `docs/ui/`. Those files are the **visual contract** and, when the customer wants pixel-perfect, the reuse source for coding (copy the file, wire data/state, do not redraw). Each `SCR-NNN` in the Screen Inventory maps to one file here.

| SCR-ID | Generated file | Status |
|--------|----------------|--------|
| SCR-001 | `docs/ui/product-list.html` | {pending / generated / customer-signed} |
| SCR-004 | `docs/ui/checkout.html` | {pending / generated / customer-signed} |

---

## Changelog

> The **Customer Sign-off Reference** column is required on any row that sets the version to Approved (the customer signs off the visual design).

| Date | Version | Changes | Author | Customer Sign-off Reference |
|------|---------|---------|--------|-----------------------------|
| [Date] | 1.0 | Initial draft | [Name] | — |