Design Let It Cook in Paper

| # Design Exploration Swarm — Paper (“Let it cook”) | | | 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. NOW INCLUDES “Let it cook” — one prompt auto-generates 2–6 variants and iterates them automatically (Layout or Style mode). Further iterations produce progressively more creative and informed results. Supports optional vibe image / starting style. Use when the user wants to explore how a product UI could evolve in Paper — especially when they say “let it cook”, “iterate automatically”, “multiple variations”, “give it taste”, or similar. Triggered by phrases like "explore design directions in Paper", "generate UI concepts in Paper", "design exploration swarm in Paper", "rethink this UI in Paper", "show multiple design options in Paper", or any “let it cook” request. 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. | | | --- | | | ## 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> [--let-it-cook] [--mode=Layout|Style] [--variants=2|3|4|5|6] [--vibe="..."] | | | <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). | | | Let it cook flags (optional): | | | - --let-it-cook → enables automatic variant generation + multi-pass iteration. | | | - --mode=Style (default) or Layout. | | | - --variants=4 (default; 2–6 allowed). | | | - --vibe="..." → optional vibe image / style description / color palette / reference screenshot description. Injected as visual reference for every agent. | | | If --let-it-cook is present, the swarm skips manual round planning and jumps straight into automatic cooking after Phase 3. | | | If any required info is missing, ask before proceeding. | | | --- | | | ## Pipeline: Extract → Expand → Brief → Map → [COOK or Rounds] → Cluster → Refine → QA. | | | --- | | | ## Phase 0 — Concept Expansion (Creative Director Agent) | | | 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 (see original table for examples). Also capture UX patterns, repeated patterns, codebase constraints (CLAUDE.md: icon library, inline styles, theme palette), and gaps. | | | Output: structured manifest keyed by component-id. | | | --- | | | ## Phase 2 — Design Brief (Paper-specific) | | | If Paper has no connected library — produce a Style Brief as a single <style> block that every agent will inject at the top of every write_html call. | | | Build from: | | | 1. Existing codebase palette (CLAUDE.md). | | | 2. src/theme/variables.css and src/theme/panther.ts if present. | | | 3. paper get_font_family_info. | | | 4. Type scale + spacing scale derived from the codebase (or conservative default). | | | Example: | | | ``` css | | | :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; | | | } | | | Phase 3 — Concept × Reality SynthesisOne general-purpose agent maps concepts onto real UI elements (same JSON format as original).If briefGaps are non-empty, surface them to the user before proceeding. | | | Phase 4 — Let it cook (replaces original Phase 4 when --let-it-cook is used)Orchestrator:After Phase 3, create one artboard named Let it cook — <Mode> — <YYYY-MM-DD>. | | | Pre-allocate N variant slots (uniform 560×720 cards in a clean grid) with a single write_html call. Use data-concept-id placeholders, then paper rename_nodes to name each slot concept-<id>. | | | Spawn N parallel Exploration Agents (max 6). | | | After agents finish, run Phase 7 (Clustering) inside the same artboard to rank the final cooked variants. | | | Phase 4 (fallback) — Exploration Plan (Rounds) — used only when --let-it-cook is NOT setOrganize into rounds (original behavior):Round 1 — Affordance Exploration (≤15 concepts) | | | Round 2 — Layout Systems (≤15 concepts) | | | Round 3 — Copy / Messaging (≤15 concepts) | | | Round 4 — Top Concepts × Refinements | | | Create one artboard per round (original Phase 5 logic). | | | Phase 5 — Canvas Setup & Placement (Paper-specific)When cooking: one artboard as described in new Phase 4. | | | When not cooking: original multi-round logic.Pre-allocate slots with uniform card size. Record {conceptId → concept-<id>} mapping. Agents locate slots by name only.Switch each artboard to height: "fit-content" once stable. | | | Phase 6 — Exploration Agents (Parallel)Spawn up to 6 parallel general-purpose agents.Each agent MUST:Call paper get_guide({ topic: "paper-mcp-instructions" }) once at start. | | | Call paper get_font_family_info before any typography. | | | Locate target slot by name. | | | Inject the Phase 2 <style> block at the top of every write_html. | | | After write_html, call paper get_screenshot and iterate up to 3 times on alignment / spacing / hierarchy / proportion. | | | 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. | | | When in "Let it cook" mode: | | | - You are iterating automatically. | | | - Iteration Mode: Layout OR Style (focus ONLY on this mode). | | | - Vibe reference: [injected here]. | | | Mandatory: | | | - Call paper get_guide({topic: "paper-mcp-instructions"}) at start. | | | - Call paper get_font_family_info before typographic styling. | | | - Find your target slot by name; never reuse a node ID across calls. | | | - Inject the full design brief <style> block (with var(--...)) at the top of every write_html. | | | - Use px for font-size, em for letter-spacing, px for line-height. | | | - Repeated rows: fixed-width slots (flexShrink: 0) for icons/actions. | | | - Call paper finish_working_on_nodes when done. | | | Workflow (standard): | | | 1. Interpret the concept. | | | 2. Build HTML + brief. | | | 3. write_html → get_screenshot → fix (max 3 iterations). | | | Workflow (“Let it cook”): | | | 1–3. Same as standard for first pass. | | | 4. Iterate up to 3 more times, focusing exclusively on the chosen mode: | | | - Layout mode → rethink structure, spacing, density, flow, hierarchy. | | | - Style mode → refine colors, typography, tone, affordances, micro-interactions. | | | 5. Further passes should feel more creative and informed than the first shot. | | | 6. Use update_styles + set_text_content for later iterations when possible. | | | 7. Final screenshot to verify. | | | Report back: conceptId, slotName, iterationCount (if cooking), status, screenshot reference, any briefGaps. | | | Phase 7 — Clustering & Selection (Design Critic Agent)Identical to original: cluster, dedupe, rank top 10 by clarity / novelty / usefulness. | | | Phase 8 — Refinement AgentsFor each of the top 10 (or top cooked variants when cooking), spawn agents to render 2–3 refined variations into a dedicated refinement area.Prefer paper duplicate_nodes + tweaks for speed. | | | Phase 9 — QA AgentOne general-purpose agent audits everything (original checks + new cooking-specific checks):Progressive improvement across iterations when cooking. | | | All variants use var(--...). | | | Artboards on fit-content. | | | Typography only from get_font_family_info. | | | Meaningful differences and spread. | | | Output QA report with pass/fail and list of concepts to re-run if needed. | | | Error recovery & Concurrency safety(Unchanged from original — slot-by-name, max 6 parallel, pre-allocate grids, etc.) | | | Final output (to the user)Concept summary table — concept · axis · applied component · status | | | Paper artboard names — one per round (or the single “Let it cook” artboard) | | | Screenshots by round (or cook batch) — via paper get_screenshot | | | Top concept shortlist — from Phase 7 | | | Let it cook summary (when used): Mode, variants, iterations per variant, vibe used | | | QA report | | | Manifest diff | | | Brief-gaps list | | | Keep the user-facing summary tight; screenshots and artboard names are the deliverable. | |