Design Screen

Compose UI screens from existing components. Zero reinvention.

Agent Capabilities

Capability	Used For	Required	Fallback
File read/write	Conventions, specs, progress tracking	Yes	—
Code search (grep/glob)	Component scan, token detection, pattern discovery	Yes	—
Shell/command execution	Quality gates (lint, typecheck) during ship	Recommended	List commands for user to run
Task/todo tracking	Ship loop progress	Recommended	Track in spec Progress section
User interaction	Compose option selection, stuck escalation, gap decisions	Yes	—
Figma MCP	Design context extraction (spec), component placement draft (craft)	Optional (required for craft)	Text-only compose mode (spec), skip craft (ship directly)

Fallback rule: If Figma MCP is unavailable, the skill works from text input and codebase analysis. Warn the user and proceed.

Actions

Action	Input	Output	Reference
`init`	(none — scans project)	`ds/conventions.md`	init.md
`spec "{name}" [figma-link]`	Screen name + optional Figma link	Spec in `ds/screens/active/`	spec.md
`spec-review`	(reads active spec)	Multi-perspective review verdict	spec-review.md
`craft`	(reads active spec + Figma file)	Figma component placement draft	craft.md
`ship`	(reads active spec)	Implemented screen (ship loop)	ship.md
`review`	(reads built files + spec)	Compliance report	review.md

Flow

Recommended (new screen):
  init → spec "{name}" → spec-review → craft → ship → review

Daily use (existing project):
  spec "{name}" → ship

With Figma validation:
  spec "{name}" → craft → ship

Quick (simple screen, high coverage):
  spec "{name}" → ship

Complex screen:
  spec "{name}" → spec-review → craft → ship → review

Each action is standalone — usable independently. Each action suggests the next in its output.

Philosophy

Zero reinvention: If a component exists, reuse it. Never create what's already there.
Compose, don't create: The skill assembles screens from existing pieces, not from scratch.
Coverage honesty: Report real component-to-zone mapping. Don't inflate numbers.
Human-in-the-loop: User picks the layout. User decides on gaps. Agent proposes, user disposes.
Conventions over opinions: Adapt to the project's patterns, never impose.
ASCII-first proposals: Visual wireframes in chat, mapped to real components.
Stack-agnostic: Works with React, Vue, Svelte, Angular, Web Components.

Conventions Boundary

ds/conventions.md contains ONLY stable project DNA:

Stack, naming, token structure, folder paths, import patterns, layout patterns

Never persisted: Component inventory, token values, route lists. These are always live-scanned.

3-Layer Knowledge Model

Layer 1: references/principles/     Generic knowledge (any project)
         layout-patterns.md         "A sidebar pattern = SideNav fixed + content scrollable"
         composition.md             "Shell → Layout → Content hierarchy"
         page-states.md             "5 states: loading, success, empty, error, partial"
         responsive.md              "Sidebar collapses: full → icon-only → drawer"

Layer 2: ds/conventions.md          Project DNA (generated by init, stable)
                                    "Components in libs/ui/, PascalCase, tokens in CSS vars"

Layer 3: Live scan                  Real-time state (at spec/ship runtime)
                                    "47 components: Button, Input, FormField, DataTable..."

Figma Integration

When a Figma URL is provided to spec, the skill extracts design context:

Figma link provided?
  │
  ├─ YES → Call get_design_context(fileKey, nodeId)
  │         → Extract layout structure, components, spacing
  │         → Map Figma components to project inventory
  │         → Compose options are more precise (design-driven)
  │
  └─ NO  → Text-only compose (description-driven)

Figma MCP unavailable?
  → Warn: "Figma MCP not available. Continuing with text description."
  → Proceed in text mode

URL parsing:

figma.com/design/:fileKey/:fileName?node-id=:nodeId → convert - to : in nodeId
figma.com/design/:fileKey/branch/:branchKey/:fileName → use branchKey as fileKey

Component Skill Handoff

When a missing component is flagged during spec or ship:

Component gap detected
  │
  ├─ Propose solutions to user:
  │   1. Create via /component spec {name} → new component
  │   2. Adapt existing component → extend props/slots
  │   3. Use alternative existing component
  │   4. Proceed with gap (document in spec)
  │
  └─ User decides → action taken → resume design-screen flow

The design-screen skill delegates component creation to the component skill. It never creates components itself.

Action Router

User input
  │
  ├─ "init", "setup", "onboard"        → Load references/actions/init.md
  │
  ├─ "spec", "compose", "design screen",
  │  "screen layout"                    → Load references/actions/spec.md
  │
  ├─ "spec-review", "review spec",
  │  "challenge spec"                   → Load references/actions/spec-review.md
  │
  ├─ "craft", "design in figma",
  │  "figma draft", "craft screen"      → Load references/actions/craft.md
  │
  ├─ "ship", "build", "implement",
  │  "ship screen"                      → Load references/actions/ship.md
  │
  ├─ "review", "check screen",
  │  "compliance check"                → Load references/actions/review.md
  │
  └─ (no action / "help" / "status")   → Status (below)

Loading rule: Read the action file BEFORE executing. The action file contains all logic, principles references, and templates needed.

Auto-init: If any action detects missing ds/conventions.md, it auto-triggers init before proceeding.

Input detection:

Input contains figma.com URL?
  YES → Extract fileKey + nodeId, pass to spec action
  NO  → Treat input as screen name/description

Principles

Standards that inform composition. Loaded by actions as specified in the loading table.

Principle	Focus	Reference
Layout Patterns	SaaS/Mobile pattern catalog	layout-patterns.md
Composition	Screen-level assembly rules	composition.md
Page States	Loading, empty, error, success	page-states.md
Responsive	Breakpoint strategy, collapse patterns	responsive.md

Principles Loading Table

Action	Loads
init	layout-patterns (to detect existing patterns)
spec	all 4 principles
spec-review	none (agents receive spec + codebase context directly)
craft	layout-patterns + composition (to inform zone structure)
ship	composition + page-states
review	all 4 principles

Templates

File Templates (generated output files)

Template	Used by	Reference
Conventions	`init`	conventions.md
Screen spec	`spec`	spec.md

Output Templates (chat messages)

Template	Used by	Reference
Init output	`init`	init-output.md
Spec output	`spec`	spec-output.md
Spec-review output	`spec-review`	spec-review-output.md
Craft output	`craft`	craft-output.md
Ship output	`ship`	ship-output.md
Review output	`review`	review-output.md

Project Structure (in user's project)

ds/
├── conventions.md                    ← Project DNA (from init)
└── screens/
    ├── active/                       ← Current screen specs
    │   └── 2026-03-24-settings.md
    ├── shipped/                      ← Completed screens
    └── dropped/                      ← Abandoned screens

Workflow State

Each action updates the spec's ## Workflow section to track cross-action state:

## Workflow
last_action: craft           # init | spec | spec-review | craft | ship | review
last_action_status: COMPLETE  # COMPLETE | PARTIAL | ERROR | IN_PROGRESS
coverage_at_spec: 85%         # from spec compose phase
coverage_at_craft: 70%        # from craft mapping (if craft ran)
craft_figma_page: "settings — craft"  # Figma page name (if craft ran)

Rules:

Each action READS this section on load to understand prior state
Each action WRITES this section on exit with its result
If section is missing → first run, create it
Status section (below) uses this to suggest next action

Status (Default — No Action Specified)

When user runs /design-screen with no action:

1. Check ds/conventions.md → exists? stale?
2. Check ds/screens/active/ → any active spec?
3. Check recent ship progress → any in-progress?

State → Suggestion:
  No conventions.md         → "First time? Run: /design-screen init"
  Conventions, no spec      → "Ready. Run: /design-screen spec \"{screen name}\""
  Active spec, not shipped  → "Spec ready. Run: /design-screen craft (Figma draft) or /design-screen ship"
  Active spec, craft done   → "Craft done. Run: /design-screen ship"
  Active spec, ship WIP     → "In progress. Run: /design-screen ship (resumes)"
  Active spec, ship done    → "Shipped. Run: /design-screen review"
  All complete              → "Done. Run: /workflow done"

Configuration

All behavior is configurable by editing the skill files directly.

What to change	Edit
Action logic	`references/actions/{action}.md`
Screen principles	`references/principles/{principle}.md`
Output templates	`references/templates/outputs/{action}-output.md`
File templates	`references/templates/{template}.md`

References

Actions:

Init | Spec | Spec-Review | Craft | Ship | Review

Principles:

Layout Patterns | Composition | Page States | Responsive

Templates (files):

Conventions | Spec

Output (chat):

Init | Spec | Spec-Review | Craft | Ship | Review

design-screen