---
model: sonnet
---

# /tas-design-spec $ARGUMENTS

Role: PE - Product Engineer
Create or update the **Design Spec** (`docs/design-spec.md`) — the internal token / component / breakpoint system — by **extracting it from the Generated Screens** (`docs/ui/*.html`). Internal artifact; not sent to the customer.

> **Stage 02 is optional.** Skip when `workflow.ui_ux_stage: false` in `tas.yaml`. This command runs after `/tas-design-uiux` and after Claude Design has produced the HTML screens.

## Prerequisite
- `docs/design-uiux.md` must exist (run `/tas-design-uiux` first).
- `docs/ui/*.html` (Generated Screens) should exist — the Design Spec is extracted FROM them.

## Gate (run first)
1. If `workflow.gate_enforcement: true` in `tas.yaml` (default true): require `docs/design-uiux.md` frontmatter `artifact-status: approved`. Missing/not approved → **STOP** with the fix (approve it, or set `workflow.gate_enforcement: false`). If `false` → skip.
2. **HTML-exists gate:** if `docs/ui/` has no `*.html` yet, **STOP**: "🚫 No Generated Screens found in `docs/ui/`. The Design Spec is extracted from the Claude Design HTML. Produce the screens first (paste the Design Brief from `/tas-design-uiux` into Claude Design, save to `docs/ui/`), then re-run `/tas-design-spec`." Do NOT invent token values with no HTML to extract from.

## Actions
1. Read `tas.yaml`, `docs/design-uiux.md` (UI Constraints, Screen Content Map), and the Generated Screens in `docs/ui/*.html`.
2. Check if `docs/design-spec.md` already exists.

### CREATE mode (file doesn't exist):
3. Read `.tas/templates/Design-Spec.md`.
4. **Extract the real values from the HTML** (this is the point of the command — the seed only gave direction, the HTML gives the final values):
   - **Design Token** — pull every actual color / typography / spacing / radius / shadow / motion value used in the Generated Screens; normalize into stable tokens (`{colors.primary}`, `{spacing.md}`, `{rounded.lg}`…). The Design System Seed sets initial direction; the HTML sets the final value.
   - **Component Library** — inventory the components that actually appear in the HTML; document each as a token composition + interaction states (default + active/pressed; add focus/disabled for a11y per UI Constraints; empty/loading/error/success per Screen Content Map).
   - **Responsive Breakpoint** — the breakpoints + collapsing strategy the HTML uses, reconciled with UI Constraints' responsive target.
   - **Do's and Don'ts** — keep this section (kit convention): reference tokens only, never inline literals; plus product-specific rules.
5. Write `docs/design-spec.md` following the template end-to-end. Apply the `{token.refs}` convention throughout; record anything the HTML leaves unspecified under **Known Gaps** so `/tas-dev` flags rather than invents.
6. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — add `artifacts.design_spec`.

### UPDATE mode (file exists):
3. Read current `docs/design-spec.md` **in full first** — preserve human edits; merge, do not clobber.
4. `$ARGUMENTS` is the change description (e.g. new screens added to `docs/ui/`); if absent, re-reconcile the whole spec against the current HTML.
5. Re-extract only the affected tokens/components/breakpoints from the HTML; keep unchanged entries and any hand-tuning. Add a Changelog line.
6. Update `project-status.yaml` — update `artifacts.design_spec`.

## Downstream consumption (do not create tokens/components with no consumer)
- **Design Token / Component Library** → `Feature Spec.Design Reference` + `Feature-Technical.UI Binding` reference them **by ID**; `/tas-dev` implements each token **once** as a CSS variable / theme constant in the codebase design system and references it everywhere; `/tas-review` flags any literal that bypasses a token.
- **Responsive Breakpoint** → `Feature-Technical.UI Binding` + E2E/Responsive tests.
- The UI implementation rule (must use tokens, no inline hex/px/font) is surfaced to coding agents via `CLAUDE.md` (generated by `/tas-agents` from this Design Spec), not duplicated per feature.

## Principles
- The Design Spec is **derived from the Generated Screens**, not authored from imagination. Seed → direction; HTML → truth.
- Reference tokens only — never inline hex/px/font in Components or in code.
- Cross-artifact references use full `Main.Sub` names.
- Mermaid (if used): `:::mermaid` wrapper; no `()` in node labels (use `[]`); no `()` in edge labels; line breaks `<br />` not `\n`.

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