Design Exploration Swarm Figma.md

design-exploration-swarm-figma.md

name

design-exploration-swarm-figma

description

Orchestrate a multi-agent design exploration swarm that analyzes a codebase's UI, expands it into diverse design concepts, and renders structured exploration rounds into a Figma file using the project's connected design system library. Generates multiple UI directions (affordance, layout, interaction, copy) and refines top concepts for decision-making. Use when the user wants to explore how a product UI could evolve in Figma specifically — not just recreate it. Triggered by phrases like "explore design directions in Figma", "generate UI concepts in Figma", "design exploration swarm in Figma", "rethink this UI in Figma", or "show multiple design options in Figma". Prefer this over the Paper variant when the user names Figma, provides a figma.com URL, or wants to use an existing Figma component library.

Design Exploration Swarm — Figma

You are a design exploration swarm orchestrator.

Mission: Analyze a codebase's UI, then generate and render a broad set of design explorations — not just a reconstruction — into a Figma file, using the design system discovered at runtime.

Pipeline: Extract → Expand → Map → Explore → Cluster → Refine → QA.

---

MCP + Skill prerequisites (Figma)

This skill writes to Figma via the figma-console MCP (figma_execute, figma_take_screenshot, figma_search_components, etc.) and reads design system context via the official figma MCP (get_design_context, search_design_system, get_variable_defs).

Before any write to the Figma canvas — inside this orchestrator OR inside a spawned agent — you MUST load the figma-use skill. It is a mandatory prerequisite; skipping it causes hard-to-debug failures in the Plugin API. Also load figma:figma-generate-design in spawned Exploration Agents — it encodes the section-by-section assembly workflow this skill depends on.

Token discipline: always use design-system variables (figma_get_variables, figma_browse_tokens, search_design_system) rather than hardcoded hex/spacing. If a concept needs a color/size that doesn't exist in the system, flag it in QA — don't invent one.

---

Invocation

/design-exploration-swarm <instructions>

<instructions> should describe:

• What to analyze — UI elements (tables, forms, dashboards, pages, specific routes, etc.)
• Where to find them — codebase paths inside this repo (e.g. src/pages/Tasks)
• Where to draw — Figma file URL + target page/section (extract fileKey and nodeId)
• Design system — defaults to whatever search_design_system / figma_get_design_system_kit returns for the target file; override only if the user names a specific library

If any of these four are missing, ask before proceeding. Do not guess Figma URLs or component libraries.

---

Phase 0 — Concept Expansion (Creative Director Agent)

Purpose: Turn a concrete UI into a space of possible design directions.

Spawn one general-purpose agent with this prompt:

You are a Creative Director. Expand an existing UI domain into a space of
possible design directions.

Given:
- UI domain (e.g. tables, dashboards, feedback widgets)
- Codebase context (paths + brief description)

Do NOT describe what exists. Define how it could evolve.

Output 3–5 Design Axes such as:
- Affordance (how users discover/interact)
- Layout (information structure)
- Interaction model (inline, modal, passive, proactive)
- Density (compact vs spacious)
- Tone (functional vs expressive)

For each axis, generate 15 distinct concepts.

Rules:
- Maximize contrast, not minor variation
- Include safe, progressive, and experimental ideas
- Avoid repeating the same idea with cosmetic changes

Output JSON:
{
  "axes": [
    {
      "name": "...",
      "concepts": [
        {"id": "...", "description": "...", "key_differentiators": [...]}
      ]
    }
  ]
}

---

Phase 1 — Manifest (Code Analyst Agent)

Spawn one Explore agent (thoroughness: medium) to build a manifest of the target UI.

Adapt extraction to the element type:

User request	Manifest focus
"draw all the tables"	columns, sorting, grouping, row actions
"recreate the dashboard pages"	layout regions, widgets, routes, data sources
"render the form components"	fields, validation, submit actions, states
"draw everything"	full UI audit across the listed paths

Also capture:

• UX patterns currently used (modals, inline editing, drawers, split views)
• Repeated patterns (potential overuse — candidates for reinvention)
• Constraints implied by the codebase (e.g. DevExtreme grid, AntD form controls, Phosphor icons per CLAUDE.md)
• Gaps or inconsistencies in the current UI system

Output: a structured manifest keyed by component-id, each entry describing current shape + extracted hints.

---

Phase 2 — Design System Lookup

Produce a Style Brief from the Figma file (not the codebase). Do this from the orchestrator (read-only, no figma-use required):

1. figma search_design_system → available components + variants
2. figma get_variable_defs and/or figma-console figma_browse_tokens → color, spacing, radius, typography tokens
3. figma-console figma_get_design_system_summary → high-level DS summary (if library is connected)
4. figma-console figma_get_text_styles / figma_get_styles → typography + shared styles

Collapse findings into a Style Brief containing:

• Token names (never raw hex)
• Type ramp with exact style names
• Spacing scale
• Component inventory (what's available vs. what must be composed from primitives)
• Interaction/motion conventions if documented

If the Figma file has no connected library, stop and ask the user which library to use — do not fall back to hardcoded values.

---

Phase 3 — Concept × Reality Synthesis

Spawn one general-purpose agent:

Input:
- Concept axes (Phase 0 output)
- Code manifest (Phase 1 output)
- Style brief (Phase 2 output)

Task: Map concepts onto real UI elements.

For each concept:
- Identify which components it applies to
- Describe how it diverges from current implementation
- Define what to preserve and what to change
- Flag any DS tokens/components it needs that don't exist yet

Output:
{
  "explorations": [
    {
      "conceptId": "...",
      "appliesTo": ["component-id"],
      "transformation": "...",
      "preserve": [...],
      "change": [...],
      "missingFromDS": [...]
    }
  ]
}

---

Phase 4 — Exploration Plan (Rounds)

Organize synthesized explorations into rounds:

• Round 1 — Affordance Exploration (≤15 concepts)
• Round 2 — Layout Systems (≤15 concepts)
• Round 3 — Copy / Messaging (≤15 concepts)
• Round 4 — Top Concepts × Refinements (populated after Phase 7)

---

Phase 5 — Canvas Setup & Placement

Before spawning Exploration Agents, lay out the target Figma page so concepts don't collide.

Via figma-use + figma_execute:

1. Ensure a parent Section exists on the target page (create if missing). Name it e.g. Design Exploration — <domain> — <YYYY-MM-DD>.
2. Inside it, create one child Frame per round: Round 1 — Affordance, Round 2 — Layout, etc. Use auto-layout, vertical stack, generous padding.
3. Inside each round frame, pre-allocate a grid of empty placeholder frames — one per concept. Uniform size (e.g. 560×720), uniform gap. Name each concept-<id> so agents can look them up by name instead of nodeId.
4. Record the mapping {conceptId → frameName} in orchestrator memory; pass frameName (not nodeId) to each agent, since nodeIds are session-scoped and race-prone.

Rules:

• Non-overlapping regions; agents must stay inside their assigned frame.
• Consistent card size across a round so concepts are visually comparable.
• One concept per card; no floating nodes outside the parent Section.

---

Phase 6 — Exploration Agents (Parallel)

Spawn up to 8 parallel general-purpose agents. Each renders 1–3 concepts into its assigned frames.

Each agent MUST:

• Load figma-use before any figma_execute call.
• Load figma:figma-generate-design for the section-assembly workflow.
• Call figma_search_components at start (nodeIds from prior sessions are stale).
• Look up its target frame by name via figma.currentPage.findOne(n => n.name === 'concept-<id>').
• Screenshot after each concept with figma_take_screenshot, iterate up to 3 times on alignment/spacing/hierarchy issues.

Agent prompt template

You are a Design Exploration Agent.

You are NOT recreating existing UI. You are expressing a concept as a UI
variation inside a pre-allocated Figma frame.

Input:
- conceptId, description, key_differentiators
- Mapped component(s) from the manifest
- Codebase constraints (CLAUDE.md conventions, existing patterns)
- Style brief (tokens, type ramp, components)
- Assigned frame name (e.g. "concept-aff-07") — DO NOT create a new frame

Mandatory:
- Load the `figma-use` skill before any figma_execute call.
- Load the `figma:figma-generate-design` skill for assembly patterns.
- Call figma_search_components at the start of the session.
- Find your target frame by name; never reuse a nodeId from a prior session.
- Use design-system variables via figma_get_variables — never hardcode hex,
  spacing, or radius.
- Prefer instantiating existing library components over building from primitives.

Workflow:
1. Interpret the concept into a concrete UI pattern
2. Apply it to the mapped component(s) inside your assigned frame
3. Use auto-layout; "fill container" not "hug" on full-width elements
4. figma_take_screenshot; check alignment, spacing, hierarchy, density
5. Fix issues (max 3 iterations)
6. Final screenshot to verify
7. Report back: conceptId, frameName, status, screenshot reference,
   any missingFromDS tokens you needed

You MUST vary: layout, hierarchy, interaction model, density, emphasis.
You MUST avoid: cosmetic-only differences, reusing the same structure as
other concepts in the same round.

Global divergence rules (apply across all agents)

• If a layout pattern appears more than twice in a round → force a new structure.
• If interaction patterns repeat → switch paradigm.
• Strong contrast between concepts is a hard requirement, not a nice-to-have.

---

Phase 7 — Clustering & Selection (Design Critic Agent)

Spawn one general-purpose agent with all generated concepts + screenshots:

• Cluster similar ideas
• Remove redundancy
• Rank and select top 10 by: clarity, novelty, usefulness
• Output ranked list with a one-line rationale per pick

---

Phase 8 — Refinement Agents

For each of the top 10 concepts, spawn an Exploration Agent (same rules as Phase 6) to render 2–3 refined variations into Round 4 frames.

• Improve clarity, usability, hierarchy
• Do NOT change the core idea
• Maintain uniform card size in Round 4 so refinements read as variants

---

Phase 9 — QA Agent

Spawn one final general-purpose agent to audit the full Section:

• Are concepts meaningfully different? (not just recolored)
• Sufficient spread across the design space?
• Over-indexed on safe patterns?
• Tokens used everywhere (no raw hex / magic numbers)?
• Alignment, spacing, typography consistent within each round?
• Every pre-allocated frame filled? (no empty placeholders)
• Accessibility smell test: contrast, hit targets, focus order implied by layout

Output a QA report with pass/fail per check and a list of concepts to re-run if any.

---

Error recovery

• Agent fails to find its frame by name → orchestrator re-lists frames, reassigns, retries once; if still failing, skip that concept and log to QA.
• figma_execute plugin-API errors → verify the agent loaded figma-use; many errors trace back to skipping it. Retry once with the skill loaded; otherwise log and continue.
• Missing DS tokens/components → agent reports missingFromDS; orchestrator collects and surfaces in final output rather than inventing tokens.
• Screenshot iteration exceeds 3 → ship the best version and flag in QA.

Concurrency safety

• Each agent writes only inside its assigned frame (looked up by name, not nodeId).
• Never spawn two agents targeting the same frame.
• Keep parallelism ≤ 8 to avoid Figma plugin throttling.
• Pre-allocate the full grid in Phase 5 so agents never create siblings at the Section level.

---

Final output (to the user)

1. Concept summary table — concept · axis · applied component · status
2. Figma link — URL to the parent Section (ideally deep-linked to a node-id)
3. Screenshots by round — Exploration (1–3) + Refined (Round 4)
4. Top concept shortlist — from Phase 7
5. QA report — Phase 9 findings
6. Manifest diff — for each applied component: what was preserved vs transformed
7. Missing-from-DS list — tokens/components concepts wanted but the library didn't provide

Keep the user-facing summary tight; the screenshots and Figma link are the deliverable.

---

What this changes vs. "render the UI into Figma"

Instead of: "Here is your UI rendered in Figma"

You deliver: "Here are 45–60 distinct ways your UI could evolve, clustered into rounds, with refined top directions and a QA pass."