---
model: sonnet
---

# /tas-design-uiux $ARGUMENTS

Role: PE - Product Engineer
Create or update the **UI/UX Design** (`docs/design-uiux.md`) — the governance/traceability index for the UI — and assemble the **Design Brief** (the prompt for Claude Design that produces the Generated Screens).

> **Stage 02 is optional.** Read `workflow.ui_ux_stage` in `tas.yaml`. If `false` (pure API / service / batch / pipeline), do not run this — there is no UI/UX Design or Design Spec. If the key is missing, confirm with the user before proceeding.

## Prerequisite
- `docs/prd.md` must exist

## Gate (run first)
If `workflow.gate_enforcement: true` in `tas.yaml` (default true): require `docs/prd.md` frontmatter `artifact-status: approved` — grep only the `artifact-status:` line. Missing or not `approved` → **STOP**: "🚫 Gate: /tas-design-uiux needs PRD approved (docs/prd.md artifact-status = {value}). Set it to `approved`, or set `workflow.gate_enforcement: false` for solo mode." If `false` → skip.

## Relationship to /tas-design-spec (two passes, two commands)
```
/tas-design-uiux  → docs/design-uiux.md (Screen Inventory SCR-NNN, Content Map, Constraints, Seed) + Design Brief
        │
   (you) Claude Design → docs/ui/*.html  (Generated Screens = visual source of truth)
        │
/tas-design-spec  → docs/design-spec.md (Token / Component / Breakpoint, extracted from the HTML)
```
This command owns the first box. It runs many times as the PRD evolves. It does NOT produce `design-spec.md` — that is `/tas-design-spec`, run after the HTML exists.

## Actions
1. Read `tas.yaml` (project context, confirm UI is in scope) and `docs/prd.md`.
2. Check if `docs/design-uiux.md` already exists.

### CREATE mode (file doesn't exist):
3. Read `.tas/templates/UIUX-Design.md`.
4. `$ARGUMENTS` is UI scope description; if absent, base scope on the PRD.
5. Fill the artifact end-to-end, sourced by ID (never invent):
   - **Screen Inventory** — assign `SCR-NNN` per screen; cover **every PRD.FR that has a UI** (from PRD.User Flow + PRD.FR); record entry/exit navigation and the target Generated Screen file path (`docs/ui/{slug}.html`). No orphan screen (each traces to ≥1 FR).
   - **Screen Content Map** — per screen: data shown (`E-NNN`), inputs, actions (`FR-NNN` trigger), validation (`BRU-NNN`), states (BRD.Entity State). Sourced from PRD.FR+AC, PRD.Product Data Model, BRD.Entity State, BRD.Business Rule.
   - **UI Constraints** — from PRD.NFR + PRD.Out of Scope (a11y, responsive target, localization, browser, not-designed).
   - **Design System Seed** — direction only (type/color/spacing/tone); tone from PRD.Product Goal + PRD.User Persona. Do NOT source design intent from BRD.
6. **Assemble the Design Brief** (do not hand-write a prompt): concatenate Screen Inventory + Screen Content Map + UI Constraints + Design System Seed, plus framing (audience + intent pulled from PRD.User Persona, PRD.Product Goal, BRD.Glossary). Present it to the user as the prompt to paste into Claude Design.
7. **Coverage gate — run the `coverage-auditor` agent** (UI/UX gate): every PRD.FR with a UI is covered by ≥1 screen; every screen traces to ≥1 FR; every Screen Content Map references valid `E-NNN`/`FR-NNN`/`BRU-NNN`. `draft` → ⚠ warn; `approved` → hard-block.
8. **Instruct the next step** — tell the user: "Paste the Design Brief into Claude Design, save the exported screens as `docs/ui/{slug}.html` (matching the Screen Inventory paths), then run `/tas-design-spec` to extract the token/component system from them."
9. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — add `artifacts.ui_design`.

### UPDATE mode (file exists):
3. Read current `docs/design-uiux.md` **in full first** — preserve human edits; merge the change rather than overwriting sections.
4. `$ARGUMENTS` is the change description; if absent, ask which screen/section to update.
5. Update the affected screens/sections (keep `SCR-NNN` IDs stable — never reuse a retired ID), re-assemble the Design Brief for changed screens, re-run the coverage gate.
6. If a screen changed, warn that its Generated Screen (`docs/ui/*.html`) and downstream `Feature Spec.Design Reference` / `design-spec.md` may be stale (T7 Design Change cascade: UI/UX Design → Design Spec → Feature Spec.Design Reference → regenerate CLAUDE.md).
7. Add a Changelog line (with Customer Sign-off Reference if setting Approved). Update `project-status.yaml` — update `artifacts.ui_design`.

## Principles
- This artifact is a **thin index**, not a visual re-description. The HTML in `docs/ui/` is the visual source of truth; do not duplicate its layout in prose.
- Every screen has a stable `SCR-NNN`; `Feature Spec.Design Reference` and `Feature-Technical.UI Binding` point at these IDs.
- Cross-artifact references use full `Main.Sub` names (e.g. `UI/UX Design.Generated Screens`, `Design Spec.Component Library`).
- Mermaid (if used): `:::mermaid` wrapper; no `()` in node labels (use `[]`); no `()` in edge labels between `|...|`; line breaks use `<br />`, not `\n`.

## Final Step — Token Log
Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to `docs/design-uiux.md`.