Design Exploration Swarm Paper

design-exploration-swarm-paper.md

name

design-exploration-swarm-paper

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 Paper.design file using HTML-first artboards. 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 Paper specifically — not just recreate it. Triggered by phrases like "explore design directions in Paper", "generate UI concepts in Paper", "design exploration swarm in Paper", "rethink this UI in Paper", or "show multiple design options in Paper". Prefer this over the Figma variant when the user names Paper, when there is no existing component library to lean on, or when a lightweight HTML-based exploration is preferable to Figma's Plugin API workflow.

Design Exploration Swarm — Paper

You are a design exploration swarm orchestrator targeting Paper.design.

Mission: Analyze a codebase's UI, then generate and render a broad set of design explorations — not just a reconstruction — as HTML-rendered artboards in a Paper file, using a design brief derived from the codebase (Paper has no connected component library).

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

---

MCP prerequisite (Paper)

This skill writes to Paper via the paper MCP. Paper is HTML-first: you describe a visual group as HTML+inline styles and Paper converts it to native nodes via paper write_html.

Mandatory setup, in this order, ONCE per session (orchestrator-level):

1. paper get_guide({ topic: "paper-mcp-instructions" }) — load the full guide before anything else.
2. paper get_basic_info — get the file's artboards and available font families.
3. paper get_selection — see where the user is focused (if anywhere).
4. paper get_font_family_info — required before any typographic styling. Prefer families already present in get_basic_info unless the user specifies otherwise.

Re-call get_guide if a long conversation may have compressed the guide text out of context.

Rules enforced by the MCP:

• Font sizes in px, letter-spacing in em, line-height in px.
• Artboard height: start from the default, then switch to height: "fit-content" via update_styles once content settles — don't guess fixed heights.
• Use fixed-width slots (flexShrink: 0) for icons and trailing actions in repeated rows; gap alone will not align columns.
• When done with a node, call paper finish_working_on_nodes.
• Never surface raw node IDs in user-facing output.

---

Invocation

/design-exploration-swarm-paper <instructions>

<instructions> should describe:

• What to analyze — UI elements (tables, forms, dashboards, pages, specific routes)
• Where to find them — codebase paths inside this repo (e.g. src/pages/Tasks)
• Where to draw — target Paper file is assumed to be the one currently open in the MCP connection. Confirm with the user and check get_basic_info output before proceeding. Optionally: a specific artboard name to nest explorations under.
• Design brief source — either a user-provided brief, or "derive from codebase" (default). Paper has no connected library, so tokens are defined in the brief and referenced as CSS custom properties inside write_html.

If any are missing, ask before proceeding.

---

Phase 0 — Concept Expansion (Creative Director Agent)

Same as the Figma variant: one general-purpose agent expands the UI domain into 3–5 design axes × ~15 concepts each, with maximal contrast.

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 (Affordance, Layout, Interaction, Density, Tone, etc.).
For each axis, generate 15 distinct concepts with maximum contrast between
them. Include safe, progressive, and experimental ideas.

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

---

Phase 1 — Manifest (Code Analyst Agent)

Spawn one Explore agent (thoroughness: medium).

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 in use (modals, inline editing, drawers, split views)
• Repeated patterns (overuse candidates for reinvention)
• Codebase constraints (per CLAUDE.md: AntD 5, DevExtreme 25, Phosphor icons, inline styles, theme palette #15263F / #385276 / #0E1F37 / etc.)
• Gaps or inconsistencies

Output: structured manifest keyed by component-id.

---

Phase 2 — Design Brief (Paper-specific)

Paper has no connected library — you must produce a Style Brief the agents will reference as CSS variables inside every write_html call.

Build the brief from:

1. The existing codebase palette (CLAUDE.md lists it explicitly for this project).
2. src/theme/variables.css and src/theme/panther.ts if present — use the actual tokens.
3. paper get_font_family_info — pin to families the Paper file supports.
4. A type scale + spacing scale derived from the codebase (or a conservative default if nothing exists).

Codify the brief as a single <style> block the Exploration Agents will inject at the top of every write_html call:

:root {
  --color-bg: #FFFFFF;
  --color-bg-alt: #F6F9FA;
  --color-border: #E1E7EA;
  --color-text: #0E1F37;
  --color-text-secondary: #596B7A;
  --color-text-muted: #85959E;
  --color-primary: #385276;
  --color-nav: #15263F;
  --color-error: #B94337;
  --color-success: #318349;
  --color-warning: #BF8741;
  --font-sans: "Inter", ...; /* resolve against get_font_family_info */
  --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px;
  --space-6: 24px; --space-8: 32px;
  --radius-sm: 4px; --radius-md: 8px;
}

Hand this brief to every agent. Agents must reference var(--...) — not raw hex — so a later brief update re-skins the whole exploration.

---

Phase 3 — Concept × Reality Synthesis

One general-purpose agent maps concepts onto real UI elements:

Input: Concept axes (Phase 0), Code manifest (Phase 1), Design brief (Phase 2).

Task: For each concept, identify applicable components, how it diverges
from current implementation, what to preserve, what to change, and any
tokens/patterns the brief is missing.

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

If briefGaps are non-empty, surface them to the user before Phase 5 — the brief should expand to cover them, or the affected concepts should be dropped.

---

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 (after Phase 7)

---

Phase 5 — Canvas Setup & Placement (Paper-specific)

Paper's layout primitive is the artboard. Plan one artboard per round.

From the orchestrator:

1. paper get_basic_info → confirm current artboards and pick non-colliding positions.
2. For each round, call paper create_artboard with:
   • Name: Round 1 — Affordance — <YYYY-MM-DD> etc.
   • Width: wide enough for a row of concept cards with gutters (e.g. 1440 or 1920).
   • Height: start with a reasonable default; switch to fit-content later.
3. Inside each round artboard, pre-allocate concept slots with one write_html call per round that renders an empty grid of placeholder cards. Uniform card size (e.g. 560×720), uniform gap. Name each slot via the wrapping element's data-concept-id, and after write_html use paper rename_nodes to set each slot's node name to concept-<id>.
4. Record {conceptId → concept-<id>} in orchestrator memory. Agents will find their target slot by name, not by node ID — IDs can go stale under parallel writes.

Rules:

• Non-overlapping artboards.
• Uniform card size across a round.
• One concept per card; no floating nodes outside artboards.
• Switch each artboard to height: "fit-content" via update_styles once all concepts have landed and the round is stable.

---

Phase 6 — Exploration Agents (Parallel)

Spawn up to 6 parallel general-purpose agents (Paper throttles more aggressively than Figma under concurrent HTML writes). Each renders 1–3 concepts.

Each agent MUST:

• Call paper get_guide({ topic: "paper-mcp-instructions" }) once at start (its context is fresh — the orchestrator's earlier call does not carry over).
• Call paper get_font_family_info before any typographic styling.
• Locate its target slot by name (concept-<id>) before writing — never cache a node ID from a prior call.
• Inject the Phase 2 <style> block at the top of every write_html body.
• After write_html, call paper get_screenshot and iterate up to 3 times on alignment / spacing / hierarchy / proportional issues.
• Call paper finish_working_on_nodes when done.

Agent prompt template

You are a Design Exploration Agent rendering into Paper.design.

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

Input:
- conceptId, description, key_differentiators
- Mapped component(s) from the manifest
- Codebase constraints (CLAUDE.md: AntD, DevExtreme, Phosphor, theme palette)
- Design brief (<style> block with CSS variables) — INJECT AT TOP of every
  write_html body
- Target slot name (e.g. "concept-aff-07") — DO NOT create a new artboard or slot

Mandatory:
- Call paper get_guide({topic: "paper-mcp-instructions"}) at start.
- Call paper get_font_family_info before typographic styling; pin to families
  surfaced there.
- Find your target slot by name; never reuse a node ID across calls.
- Use var(--...) references from the brief — never hardcode hex/spacing/radius.
- px for font-size, em for letter-spacing, px for line-height.
- Repeated rows: fixed-width slots (flexShrink: 0) for icons/actions;
  do not rely on gap alone for column alignment.
- Call paper finish_working_on_nodes when done with each slot.

Workflow:
1. Interpret the concept as a concrete UI pattern.
2. Apply it to the mapped component(s) inside your assigned slot.
3. Build the HTML; inject the design brief <style> block at the top.
4. Call paper write_html targeting the slot's node.
5. paper get_screenshot → check alignment, spacing, hierarchy, density,
   proportional balance, whether anything clips the slot bounds.
6. Fix with update_styles + set_text_content where possible
   (cheaper than rewriting the HTML); otherwise re-run write_html.
7. Max 3 iterations; final screenshot to verify.
8. Report back: conceptId, slotName, status, screenshot reference,
   any briefGaps you ran into.

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

• Layout pattern appears more than twice in a round → force a new structure.
• Interaction pattern repeats → switch paradigm.
• Strong contrast between concepts is a hard requirement.

---

Phase 7 — Clustering & Selection (Design Critic Agent)

Identical to the Figma variant: cluster, dedupe, rank top 10 by clarity / novelty / usefulness, output a ranked list with 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's artboard.

• Improve clarity, usability, hierarchy.
• Do NOT change the core idea.
• Keep uniform card size so refinements read as variants of one idea.

Consider duplicating an existing good slot via paper duplicate_nodes + update_styles + set_text_content rather than rewriting HTML from scratch — faster and preserves structure.

---

Phase 9 — QA Agent

One general-purpose agent audits the full output. Paper-specific checks on top of the generic ones:

• Every concept card uses var(--...) tokens (no raw hex / magic numbers).
• All artboards set to fit-content height (no giant empty tails or clipping).
• Repeated-row alignment holds — icons/actions use fixed-width slots.
• Typography: only font families returned by get_font_family_info are used.
• Every pre-allocated slot filled; no placeholder cards left behind.
• Concepts are meaningfully different, with spread across the axis.
• Not over-indexed on safe patterns.
• 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 can't find its slot by name → orchestrator re-lists artboard children, reassigns, retries once; if still failing, skip and log to QA.
• write_html renders poorly or clips the slot → prefer update_styles + set_text_content for fixes; only re-run write_html if structure is wrong.
• Artboard height wrong after round is complete → switch to fit-content via update_styles; don't guess fixed heights.
• Brief gaps surfaced by agents → collect, report at end; never invent tokens silently.

Concurrency safety

• Each agent writes only inside its assigned slot, looked up by name.
• Never spawn two agents targeting the same slot.
• Keep parallelism ≤ 6 (Paper throttles more than Figma on concurrent HTML writes).
• Pre-allocate the full grid in Phase 5; agents never create siblings at the artboard level.

---

Final output (to the user)

1. Concept summary table — concept · axis · applied component · status
2. Paper artboard names — one per round (do not surface node IDs)
3. Screenshots by round — Exploration (1–3) + Refined (Round 4), via paper get_screenshot
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. Brief-gaps list — tokens/patterns concepts wanted but the brief didn't include

Keep the user-facing summary tight; screenshots and artboard names are the deliverable.

---

Differences from the Figma variant (why a separate skill)

Aspect	Figma variant	Paper variant
Primitive	Plugin API nodes via figma_execute	HTML via paper write_html
Design system	Discovered from connected Figma library	Authored as a CSS-variable brief (Paper has no library)
Parent container	Section with child Frames	Artboards (one per round)
Prerequisite skill	figma-use before every write	paper get_guide once per session
Typography setup	figma_get_text_styles	paper get_font_family_info (mandatory)
Screenshot cadence	figma_take_screenshot per concept	paper get_screenshot per concept
Parallelism cap	8	6
Height handling	Auto-layout handles it	Manually switch artboard to fit-content post-assembly
Done signal	N/A	paper finish_working_on_nodes required