Design Screen

/design-screen Skill

Purpose

Coordinates the human-in-the-loop visual design phase that lives between text-only flow specs (ux-agent) and code (flutter-agent / react-agent). Wraps the Claude Design ↔ codebase round-trip in two commands so the workflow is repeatable and the context survives session boundaries.

This skill does NOT replace human visual iteration in Claude Design — that's the value-add. It removes the boilerplate around it: prompt construction, state persistence, bundle fetching, agent briefing.

Reference architecture: agentteamland/workspace/.atl/docs/design-workflow.md (the canonical decision record). Pilot evidence: <test-project>/.claude/design/login/pilot-findings.md (2026-04-19).

Two Modes

The first arg switches mode: start or done.

/design-screen start "<one-line description of the screen>"
/design-screen done <handoff-url-from-claude-design>

Mode 1 — start

Flow

1. Derive slug. Take the description, produce a kebab-case slug (e.g., "tasks empty state with start CTA" → tasks-empty-state). Keep it short (3–5 words). On collision with an existing .claude/design/{slug}/ directory, append -2, -3, etc.

2. Read project context.

   • Tokens: locate flutter/lib/app/theme.dart (Flutter), web/tailwind.config.ts (React), or equivalent.
   • UX flow: scan .atl/docs/coding-standards/, .atl/wiki/, and any flow-*.md for related screen flows.
   • Existing design records: .claude/design/*/intent.md to detect related work.

3. AskUserQuestion to fill gaps (only ask what isn't already inferable):

   • Target platform: Flutter mobile / React admin / React public (if project has more than one and the description doesn't pin it down).
   • States to render: empty / loading / error / data / submitting / success / disabled / etc. (multiSelect; offer the typical set, let user add custom).
   • Actions on this screen: list (free text or multiSelect; mention things the screen lets the user do — submit, cancel, navigate, share, etc.).
   • Copy decisions: title, subtitle, CTA labels, error message tone (formal/friendly), placeholder text. Ask one question per copy slot if not in the description.
   • Reference screens: any existing screen the new one should visually echo.

4. Construct the Claude Design prompt. 5–8 sentences. Must include:

   • What screen + what app (so Claude Design grounds in identity).
   • Target platform explicitly.
   • States to render, listed.
   • User actions, listed.
   • Token reference path (e.g., "honor tokens in flutter/lib/app/theme.dart").
   • UX flow reference if one exists.
   • What NOT to invent (e.g., "use only icons available in Material 3"; pilot lesson).

5. Write .claude/design/{slug}/intent.md with status: pending-design and the schema below. Detailed, not summarized — verbatim user description, every AskUserQuestion answer as-given, full prompt text. A fresh Claude session reading this file later must be able to resume cold.

6. Print the prompt to the user, plus the next step:

   Prompt ready. Open https://claude.ai/design and paste this in. Iterate visually
   until you're satisfied. When you have the handoff URL (or you've downloaded
   the zip and have its file path), run:
   
       /design-screen done <handoff-url-or-zip-path>
   

intent.md schema (mandatory shape, all sections required)

---
status: pending-design
slug: {kebab-slug}
created: {ISO-8601 timestamp UTC}
description: "{user's verbatim one-liner from the start command}"
target: flutter | react-admin | react-public
---

# {Screen / surface display title}

## User's Original Description (verbatim)

> {exact quote of the description arg}

## Requirements (gathered via AskUserQuestion)

### States
- {as-given verbatim}

### Actions
- {as-given verbatim}

### Copy decisions
- title: "{verbatim}"
- subtitle: "{verbatim}"
- {other slots: verbatim}

### Target platform
{user-selected value}

### Reference screens
{list, or "none cited"}

## Token & flow references read

- tokens file: `{path}`
- ux flow doc: `{path or "none recorded"}`
- related design records: `{paths or "none"}`

## Derived prompt (sent to Claude Design)

{full prompt text — exactly what user pastes}

## Status log

- {ISO timestamp} — created (status: pending-design). Prompt handed to user.

No paraphrasing in the body. If the user said "users should be able to retry", do NOT write "supports retry" — write the verbatim quote. Detail discipline matters because the file is the only context bridge between Phase A and Phase B (sometimes weeks apart).

Mode 2 — done

Flow

1. Locate pending designs. Scan .claude/design/*/intent.md; collect every file with status: pending-design.

2. Resolve which one is being integrated:

   • 0 found → Error: "No pending designs. Did you mean /design-screen start \"<description>\"?" Stop.
   • 1 found → Use it. Tell the user: "Integrating design {slug} (created {date})." Proceed.
   • N found → AskUserQuestion: "Which pending design is this handoff for?" with options listing each {slug} — {description} ({created date}). Use the chosen one.

3. Read the chosen intent.md. Now you have full Phase A context: what the screen is, who it's for, what the prompt was, what tokens were referenced, every requirement.

4. Fetch the handoff bundle. The done arg is either:

   • A URL like https://api.anthropic.com/v1/design/h/{id}?open_file=... → use Bash curl -L -o {tempdir}/bundle.zip "{url}" to download.
   • A local file path to a downloaded zip → use it directly.

5. Extract to .claude/design/{slug}/{YYYY-MM-DD}-v{N}-extracted/ (where N is the next available version number). Save the original zip alongside as {YYYY-MM-DD}-v{N}-handoff.zip.

6. Save snapshot exports if the bundle includes a renderable HTML or PDF (per Q4 versioning convention from the design-workflow doc): .claude/design/{slug}/{YYYY-MM-DD}-v{N}.{html,pdf}.

7. Brief the implementation agent. Pick:

   • target: flutter → flutter-agent (Agent tool, subagent_type=flutter-agent)
   • target: react-admin or react-public → react-agent

   The brief MUST be self-contained. Do not say "implement this bundle" — the pilot established that blind briefs are insufficient. Include in the brief:

   • The screen name and intent (from intent.md).
   • The verbatim Phase A requirements (states, actions, copy decisions).
   • The extracted bundle path.
   • Pointer to the agent's own claude-design-handoff.md children file (which spells out translation rules — SVG icon substitution, idiomatic state mapping, token resolution, ARB key extraction for Flutter / namespace placement for React).
   • Any project-specific conventions worth flagging (e.g., "this project uses Riverpod; map React state to Notifier patterns").

8. Update intent.md:

   • Frontmatter: status: integrated.
   • Append to status log: {timestamp} — integrated (status: integrated). Handoff: {URL or zip path}. Extracted: {extracted-path}. Agent: {flutter-agent|react-agent}. Notes: {agent-output-summary or "see git diff"}.

9. Show the user a summary of what changed (agent output highlights, files touched, fidelity match if observable, any frictions encountered).

Important Rules

1. State lives in files. Never rely on conversation memory between start and done — the gap could be minutes or weeks. The intent.md file is the only contract.

2. Detail over summary in intent.md. Verbatim user input. Future-Claude readability is the test.

3. Slug derivation never asks the user. Pick a kebab-case slug from the description; collision suffix on conflict. Mirrors /brainstorm skill's auto-naming.

4. No new agent invented. This skill orchestrates; existing agents implement. The visual-iteration step is human-only by design.

5. Self-contained brief to the implementation agent. Pilot lesson: blind "implement this bundle" is insufficient. Always pass the intent + the agent's translation guidance pointer.

6. Versioning is per-screen, not global. Each screen's .claude/design/{slug}/ accumulates v1, v2, v3 over time as the design iterates.

7. Handoff bundle is React+HTML, not Dart. Even for Flutter targets. Translation is part of the workflow; flutter-agent's claude-design-handoff.md covers the patterns. Do NOT promise the user "Dart code is coming directly from Claude Design."

8. Don't promise visual perfection. Pilot showed 4/5 fidelity is the realistic target. Brand glyphs, animation curves, subpixel color blends will diverge by ~1–5%. This is fine.

What This Skill Does NOT Do

• Open claude.ai/design in a browser. (User does that manually after start. A future Phase 3 may add this via Chrome MCP if Claude Design's DOM stabilizes.)
• Iterate the design. (Human-in-the-loop; the value-add of the visual phase.)
• Decide platform target on user's behalf when ambiguous. (AskUserQuestion handles it.)
• Skip the AskUserQuestion gathering even when the description seems complete. (One question per slot is acceptable; better to over-capture than under-capture in intent.md.)
• Auto-trigger CI / lint / flutter gen-l10n after agent implementation. (Implementation agent's job per its own conventions.)

Accumulated Learnings

(Auto-rebuilt by /save-learnings from learnings/*.md frontmatter. Do not edit by hand. Initially empty — entries appear as the skill encounters reusable edge cases.)