wtf.design-task

Design Task

Take an existing Task as a designer. Read the Gherkin scenarios. Find every UI state that needs design coverage. Document the design references in the issue so developers have one source of truth.

See references/component-spec-template.md for the structure when you scaffold a component spec without Figma frames.

Process

0. GitHub CLI setup

Run steps 1–2 of ../references/gh-setup.md (install check and auth check). Stop if gh is not installed or not authenticated. Extensions are not required for this skill.

Skip this step if invoked from wtf.write-task or another skill that already ran gh-setup this session.

1. Identify the Task

If the user gave an issue number, use it. Otherwise call AskUserQuestion (per ../references/questioning-style.md):

question: "Which Task are you designing?"
header: "Task"
options: from recent open issues labeled task

Walk Task → Feature per ../references/spec-hierarchy.md. Extract Functional Description, Gherkin, and Design Reference from the Task. Extract user stories, ACs, and visual context from the Feature.

2. Lifecycle check

Apply the present-label overwrite gate from ../references/lifecycle-labels.md for the designed label on the Task. Output is "Design Reference". Re-run verb is "Redesign". If the label is absent, continue.

3. Load the design steering document

Load docs/steering/DESIGN.md per the strict consumer-side load in ../references/steering-doc-process.md (recommended skill: wtf.steer-design). Apply its design principles, tokens, component patterns, and accessibility standards for this session.

4. Explore the design system

Use the Agent tool with these searches (run in parallel):

Glob('src/components/**/*', 'src/**/components/**/*', 'components/**/*') — existing UI components. Note file names that match domain objects or UI states in the Task
Glob('**/{tokens,theme,variables,design-tokens}.{css,scss,ts,js,json}') + Grep for CSS custom property declarations (--) or Tailwind config keys — design tokens in use (colors, spacing, typography)
Glob('src/**/*.{stories,story}.{ts,tsx,js,jsx,mdx}') — Storybook stories as pattern references for similar screens or flows
Grep for figma.com URLs across .md, .mdx, and issue body files — existing Figma references in related issues or docs

5. Identify UI states from Gherkin

For each Gherkin scenario in the Task:

Identify the UI state it represents (e.g. empty, loading, error, success, disabled, edge case)
Note any interaction or transition implied by the When/Then steps

List these states. This list is the design coverage checklist.

6. Ask about design assets

Call AskUserQuestion (per ../references/questioning-style.md):

question: "How would you like to handle design assets for this task?"
header: "Design assets"
options:
- I have Figma frames → provide frame URLs. Validate coverage against Gherkin scenarios (Path A)
- Generate designs for me → use Figma MCP to generate frames from the Gherkin scenarios and design system (Path B)
- Scaffold a spec only → no Figma. Produce a text component spec from the scenarios (Path C)
- Partial — some states designed → provide available frames. Send remaining states to generate or scaffold

Path A — Human provides frames: Collect frame URLs. For each Gherkin scenario from step 5, check whether a frame covers it. Flag any scenario with no matching frame as a gap. Present the coverage matrix: scenario → frame URL (or ⚠ gap). If gaps exist, call AskUserQuestion (per ../references/questioning-style.md):

question: "How should I handle the uncovered scenarios?"
header: "Gaps"
options:
- Generate missing frames → run Path B for the gaps
- Leave as pending → record gaps in the Design Reference and continue

Path B — AI generates via Figma MCP: Check whether the Figma MCP tool generate_figma_design is available. If it is unavailable, warn the user and use Path C (scaffold).

If available: for each uncovered UI state, call generate_figma_design with:

The Gherkin scenario as the design brief
Component patterns and tokens from docs/steering/DESIGN.md (loaded in step 3)
Any shared components from the parent Feature's Design Handoff (if available)

Collect the generated frame URLs. Treat them as Path A frames from this point.

Path C — Scaffold spec only: Draft a component spec with the structure in references/component-spec-template.md. List each state with its required UI elements and interactions. No Figma frames. This is a text-only design brief for the developer.

Partial: Collect available frame URLs. Run Path A validation on covered states. For uncovered states, call AskUserQuestion (per ../references/questioning-style.md):

question: "How should I handle the remaining states?"
header: "Remainder"
options:
- Generate → run Path B
- Scaffold → run Path C

7. Draft the Design Reference

Apply strict STE per ../references/ste-writing.md before you write any durable body.

Produce the content for the Design Reference section of the Task:

Frame URLs mapped to Gherkin scenarios (Path A/B), or scaffolded component spec (Path C)
Coverage matrix: scenario → frame URL or ⚠ pending
Component breakdown: which exist in codebase, which are new
Interaction notes: hover, focus, error states, transitions
Responsive behavior if applicable
Design tokens to apply

8. Review with user

Show the draft. Then call AskUserQuestion (per ../references/questioning-style.md):

question: "Does this cover all the states in the Gherkin?"
header: "Review"
options:
- Yes — looks complete → proceed to update the task
- Missing states → add more coverage
- Other changes → adjust something else

Apply edits. Then proceed.

9. Update the Task issue

Note: read the current body with the gh body helper. Replace only the Design Reference section with the new content (Read + Edit tools). Preserve all other sections. See ../references/gh-body-helper.md.

python3 .wtf/gh-body.py read <task_number>        # prints a temp path; Read it, edit the Design Reference section
python3 .wtf/gh-body.py edit <task_number> --body-file "<path-from-read>"

Add the designed lifecycle label to mark this step complete:

gh issue edit <task_number> --add-label "designed"

Print the updated Task issue URL.

10. Offer to continue