Design Screen

Compose UI screens from existing components. Zero reinvention.

Agent Capabilities

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

Actions

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.

Principles Loading Table

Templates

File Templates (generated output files)

Output Templates (chat messages)

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.

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