# Wtf.design Task

> This skill should be used when a designer is picking up a Task issue to add design coverage. Triggers on phrases like "I want to design task

- Skill: `xiduzo/wtf-design-task` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add xiduzo/wtf-design-task`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiduzo/wtf-design-task/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: xiduzo (https://skillmd.com/u/xiduzo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xiduzo/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`.

```bash
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:

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

Print the updated Task issue URL.

### 10. Offer to continue

Call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "What's next?"
- header: "Next step"
- options:
  - **Implement this Task** → run `wtf.implement-task` for this Task now (default)
  - **Design another Task** → design another Task for the same Feature
  - **Stop here** → exit. No further action

- **Implement this Task** → follow the `wtf.implement-task` process. Pass the Task number as context so the user is not asked for it again.
- **Design another Task** → restart this skill from step 1. Reuse the same Feature context.
- **Stop here** → exit.