| 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 nodeIdfigma.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
| 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)
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:
last_action: craft
last_action_status: COMPLETE
coverage_at_spec: 85%
coverage_at_craft: 70%
craft_figma_page: "settings — craft"
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:
Principles:
Templates (files):
Output (chat):
