design-screen

---
name: design-screen
description: |
license: MIT
---

# 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](references/actions/init.md) |
| `spec "{name}" [figma-link]` | Screen name + optional Figma link | Spec in `ds/screens/active/` | [spec.md](references/actions/spec.md) |
| `spec-review` | (reads active spec) | Multi-perspective review verdict | [spec-review.md](references/actions/spec-review.md) |
| `craft` | (reads active spec + Figma file) | Figma component placement draft | [craft.md](references/actions/craft.md) |
| `ship` | (reads active spec) | Implemented screen (ship loop) | [ship.md](references/actions/ship.md) |
| `review` | (reads built files + spec) | Compliance report | [review.md](references/actions/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](references/principles/layout-patterns.md) |
| Composition | Screen-level assembly rules | [composition.md](references/principles/composition.md) |
| Page States | Loading, empty, error, success | [page-states.md](references/principles/page-states.md) |
| Responsive | Breakpoint strategy, collapse patterns | [responsive.md](references/principles/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](references/templates/conventions.md) |
| Screen spec | `spec` | [spec.md](references/templates/spec.md) |

### Output Templates (chat messages)

| Template | Used by | Reference |
|----------|---------|-----------|
| Init output | `init` | [init-output.md](references/templates/outputs/init-output.md) |
| Spec output | `spec` | [spec-output.md](references/templates/outputs/spec-output.md) |
| Spec-review output | `spec-review` | [spec-review-output.md](references/templates/outputs/spec-review-output.md) |
| Craft output | `craft` | [craft-output.md](references/templates/outputs/craft-output.md) |
| Ship output | `ship` | [ship-output.md](references/templates/outputs/ship-output.md) |
| Review output | `review` | [review-output.md](references/templates/outputs/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:

```yaml
## 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](references/actions/init.md) | [Spec](references/actions/spec.md) | [Spec-Review](references/actions/spec-review.md) | [Craft](references/actions/craft.md) | [Ship](references/actions/ship.md) | [Review](references/actions/review.md)

Principles:
- [Layout Patterns](references/principles/layout-patterns.md) | [Composition](references/principles/composition.md) | [Page States](references/principles/page-states.md) | [Responsive](references/principles/responsive.md)

Templates (files):
- [Conventions](references/templates/conventions.md) | [Spec](references/templates/spec.md)

Output (chat):
- [Init](references/templates/outputs/init-output.md) | [Spec](references/templates/outputs/spec-output.md) | [Spec-Review](references/templates/outputs/spec-review-output.md) | [Craft](references/templates/outputs/craft-output.md) | [Ship](references/templates/outputs/ship-output.md) | [Review](references/templates/outputs/review-output.md)