Screens

Skill: screens

Turns the approved architecture into the screen manifest — the one artifact tasks, implement and review read for what every screen shows in every state. It runs between api and tasks: by then the states are derivable, not invented — default plus every state the spec §5 ACs, the sad.md §6 alt/else branches, and the contract error responses imply (loading / empty / error / success / validation). Per state it names the components to reuse from the docs/design-system.md inventory — a NEW: component only with a why-no-primitive-fits justification. The visuals are drawn per the canon's tool; whatever the tool, the manifest is the contract — downstream never reads the raw Figma/.pen file.

Optional by surface: its N/A condition (no UI surface in sad.md target_surfaces) lives in ../_shared/size-matrix.md and is evaluated by api's handoff (carried forward when api itself is N/A). Invoked directly, it always runs.

Question phrasing → ../_shared/ask-style.md. Manifest prose follows artifact_language — state tokens (default/loading/…), SCR ids, component names and source-refs stay English → ../_shared/artifact-language.md.

Owner

Designer + frontend lead. The PM confirms the states match the ACs; review later checks the built screens against this manifest.

Inputs

• <slug> — feature slug.
• Gate (hard-refuse if missing): docs/features/<slug>/sad.md — target_surfaces + the §6 branches feed the state derivation. Absent → STOP: «run design <slug> first».
• (Expected) docs/features/<slug>/ux-flows.md — the SCR inventory this manifest details. Absent → soft: offer /sdd:ux-flows <slug> first, or derive the inventory from spec §4 + the SAD with a noted gap in the manifest — never a silent invention.
• (Expected) docs/design-system.md — the tool + the component inventory. Absent → code mode
  • recommend /sdd:design-system in the handoff.
• (Read) docs/features/<slug>/contracts/ (error responses → error states), spec.md §5 (ACs → states), .size/.route (depth + handoff resolution; defaults stated loudly when missing).

Protocol

1. Gate + read. test -f docs/features/<slug>/sad.md → missing = refuse with the pointer above. Read target_surfaces (no UI surface declared → say so and STOP — this stage is for UI features; the upstream handoff normally skips it). Read ux-flows.md (or run the soft fallback above), docs/design-system.md (tool + inventory), sad.md §6, contracts/, spec §5. Read interview_depth (else medium; --depth= wins) — it governs the per-screen confirm volume.
2. Derive states per screen. For each SCR-NN from the inventory, list the full state set: default + every state the ACs / §6 branches / contract errors imply; a state class that genuinely doesn't apply gets one explicit N/A: <reason> row. Pick the components per state — from the design-system inventory by name; a NEW: <name> only when no existing primitive fits, with the one-line why. Confirm per screen Socratically (medium/hard: one AskUserQuestion per screen — Accept / Fix / Save-as-OQ / Drop; easy: derive + ledger, ask only where the AC↔state mapping is genuinely ambiguous).
3. Draw per the canon's tool. figma → draw into the canon's figma_file via the Figma MCP, record the node-id per state; pencil → batch_design into docs/features/<slug>/screens.pen, record node ids; code → inline markdown wireframes in the manifest. Degrade, don't block: the tool's MCP unavailable in this session → fall back to code mode and name the degradation in the manifest §Source + the handoff (→ ../_shared/tool-adapters.md).
4. Write the manifest + commit. Fill ./templates/screens.md → docs/features/<slug>/screens.md (frontmatter tool copied from the canon; §Source; one ### SCR-NN section per screen; §New components). Stamp updated_at; propose commit screens: <slug> manifest.
5. Structural self-check — per ../_shared/self-check.md: re-read the manifest from disk and verify 4 items: (1) every SCR-NN from ux-flows.md has a section (inventory fully covered — or the noted-gap fallback is stated); (2) every screen shows ≥ default + (error or empty) — or carries the explicit N/A: <reason> row; (3) every component name exists in the design-system inventory or sits in §New components with a justification; (4) for figma/pencil, every state row carries a source-ref (node-id) — for code, the wireframes are present. Fix + re-check ≤2 cycles; surface anything unresolved.
6. Handoff. Emit the stage-handoff block per ../_shared/handoff.md — What I did (tool used or the degradation, «self-check: 4/4 pass») + Review (docs/features/<slug>/screens.md, + screens.pen / the Figma file when tool-drawn) + Run next: /clear, then /sdd:tasks <slug> (each ui task will cite these SCR ids + states).