design-screen

x-upstream-source	Maximepodgorski/agent-skills
x-adapter-version	2026-04-25.1
name	design-screen
description	Compose UI screens from existing components. Proposes ASCII wireframe layouts with real component mapping and coverage %, then specs the chosen layout. 6 actions: init, spec, spec-review, craft, ship, review. Core guarantee: zero component reinvented. Auto-activates on: "design-screen", "design-screen spec", "design-screen init", "design-screen craft", "design-screen ship", "design-screen build", "design-screen review", "design-screen spec-review", "compose screen", "screen layout", "compose ui", "design screen".
license	MIT
compatibility	Agent-agnostic. Works with Claude Code, OpenCode, Windsurf, Cursor, Codex, Aider, or any agent supporting SKILL.md.
metadata	{"version":"1.0"}

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