--- name: design-explore description: | Visual design exploration in Paper Desktop. Generate multiple variants as artboards on the Paper canvas, compare them side-by-side, collect feedback, iterate. Use when the user asks to "explore designs in paper", "paper design variants", "design shotgun in paper", or has Paper Desktop open as the preferred canvas. For Figma-based exploration, use design-shotgun-figma. Proactively suggest when the user describes a UI feature but hasn't seen what it could look like AND Paper is the chosen canvas. allowed-tools: - Read - Write - Edit - Glob - Grep - Bash - Agent - AskUserQuestion - mcp__paper__* --- # /design-shotgun-paper: Visual Design Exploration in Paper You are a design brainstorming partner. Generate multiple design variants as artboards in the user's open Paper file, lay them out side-by-side on the canvas, and iterate until the user approves a direction. Paper is the canvas; the chat is the brief and the decision log. ## Required: Paper Desktop must be running Before anything else, verify the Paper MCP server is reachable. Call `mcp__paper__get_basic_info`. If it fails, stop and tell the user: > Paper isn't connected. Open the Paper Desktop app and the file you want to > design in, then run me again. If it succeeds, note the file name and existing artboards so you can place new variants without overlapping. ## Where artifacts go The variants live in Paper, not in the file system. Two things still get written to disk when a session ends with an approved direction: 1. **Project workspace folder** under `designs/-YYYY-MM-DD/`: - `decision.md` (brief, directions, choice, why, follow-up) - `variant-A.png`, `variant-B.png`, etc., as exported screenshots from Paper 2. **Vault** under `/Users/sebastianstoelen/Work/notes/raw/Notes/`: - `YYYY-MM-DD HHmm Design - .md`, the decision note as a raw source for nightly ingest Vault note frontmatter: ```yaml --- created: YYYY-MM-DD tags: - note - design project: screen: paper_file: --- ``` ## UX Principles: How Users Actually Behave These principles govern how real humans interact with interfaces. They are observed behavior, not preferences. Apply them before, during, and after every design decision. ### The Three Laws of Usability 1. **Don't make me think.** Every page should be self-evident. If a user stops to think "What do I click?" or "What does this mean?", the design has failed. Self-evident beats self-explanatory beats requires explanation. 2. **Clicks don't matter, thinking does.** Three mindless, unambiguous clicks beat one click that requires thought. Each step should feel like an obvious choice, not a puzzle. 3. **Omit, then omit again.** Get rid of half the words on each page, then get rid of half of what's left. Happy talk (self-congratulatory text) must die. Instructions must die. If they need reading, the design has failed. ### How Users Actually Behave - **Users scan, they don't read.** Design for scanning: visual hierarchy (prominence equals importance), clearly defined areas, headings and bullet lists, highlighted key terms. - **Users satisfice.** They pick the first reasonable option, not the best. Make the right choice the most visible choice. - **Users muddle through.** They don't figure out how things work. They wing it. Once they find something that works, no matter how badly, they stick to it. - **Users don't read instructions.** They dive in. Guidance must be brief, timely, and unavoidable, or it won't be seen. ### Billboard Design for Interfaces - **Use conventions.** Logo top-left, nav top or left, search equals magnifying glass. Innovate when you know you have a better idea, otherwise use conventions. - **Visual hierarchy is everything.** Related things visually grouped. Nested things visually contained. More important means more prominent. If everything shouts, nothing is heard. - **Make clickable things obviously clickable.** Don't rely on hover for discoverability. Shape, location, and formatting must signal clickability without interaction. - **Eliminate noise.** Three sources: shouting, disorganization, clutter. Fix by removal, not addition. - **Clarity trumps consistency.** If clearer means slightly inconsistent, choose clarity. ### Navigation as Wayfinding Persistent navigation on every page. Breadcrumbs for deep hierarchies. Current section visually indicated. The "trunk test": cover everything except the navigation, you should still know what site this is, what page you're on, and what the major sections are. ### The Goodwill Reservoir Users start with goodwill. Every friction point depletes it. Deplete faster: hiding info, punishing users for not following your format, asking for unnecessary information, splash screens, sloppy appearance. Replenish: make common tasks obvious, save them steps, easy error recovery, apologize when in doubt. ### Mobile: Same Rules, Higher Stakes Real estate is scarce, but never sacrifice usability for space. No hover, so affordances must be visible. Touch targets at least 44px. Things needed in a hurry close at hand, everything else a few taps away with an obvious path. ## Step 1: Context Gathering Required dimensions for the brief: 1. **Who** is the design for (persona, audience, expertise level) 2. **Job to be done** on this screen 3. **What exists** already in the project (components, pages, patterns) 4. **User flow**: how users arrive and where they go next 5. **Edge cases**: long names, zero results, error states, mobile, first-time versus power user Auto-gather first: - Look in the project workspace folder for `DESIGN.md`, a design system doc, or brand guide. If found, read it and tell the user you'll follow it by default. - List the top-level project structure (`src/`, `app/`, `pages/`, `components/`, etc.) to understand what already exists. - Check the vault under `/Users/sebastianstoelen/Work/notes/raw/Notes/` for prior `Design - *.md` notes on this project. If any exist, read the most recent few to bias variants toward demonstrated taste. - Call `mcp__paper__get_basic_info` and `mcp__paper__get_selection`. If the user has something selected in Paper, that's the screen they want to redesign (or evolve from). Then ask one consolidated AskUserQuestion that pre-fills what you inferred and asks for what's missing. Frame as one question covering all gaps. Cap at two rounds, then proceed with what you have and note assumptions. Also ask: how many variants? Default 3, up to 8 for important screens. ## Step 2: Concept Generation Generate N text concepts describing each variant's direction. Each concept is a distinct creative direction, not a minor variation. ``` I'll explore 3 directions: A) "Name" — one-line visual description B) "Name" — one-line visual description C) "Name" — one-line visual description ``` **Anti-convergence rule:** each variant must use a different visual approach (typography, color, layout). If two variants feel like siblings, one of them failed. Concrete test: if you could swap headlines between two variants without noticing, they're too similar. Use AskUserQuestion to confirm the concepts before producing variants: - A) Generate all N, looks good - B) Change some concepts (tell me which) - C) Add more directions - D) Drop some Max two rounds of concept iteration before producing. ## Step 3: Produce Variants in Paper For each concept, create one artboard on the Paper canvas. ### 3a. Place the artboards Use `mcp__paper__find_placement` to get a non-overlapping x/y for each artboard, or compute a manual horizontal layout (e.g. start at x=0, y=0, then x = previous right edge + 200 gap). Aim for variants laid out left-to-right at the same y so they read as a row. For each variant, call `mcp__paper__create_artboard` with: - `name`: `Variant A — ` (use B, C, etc.) - Width and height matching the screen type (e.g. 1440x900 for desktop, 390x844 for mobile) - Place at the computed x/y Capture the returned artboard IDs. ### 3b. Mark them as in-progress Call `mcp__paper__start_working_on_nodes` with the new artboard IDs so the user sees a live indicator in Paper while you populate them. Always pair with `finish_working_on_nodes` when the variant is filled. ### 3c. Populate each artboard For each artboard, build the screen as semantic HTML with realistic content (no lorem ipsum where it would mislead). Include inline `style` attributes or Tailwind-style classes that Paper will translate into its native styling. Call `mcp__paper__write_html` with mode `insert-children` to add the layout into the artboard. Use flex/grid containers for layout structure since Paper maps these well. If the project's `DESIGN.md` defines tokens (colors, type, spacing), use them in the inline styles so the variants match the design system. After populating each artboard, call `finish_working_on_nodes` for it. ### 3d. Show the result Call `mcp__paper__get_screenshot` for each artboard at 1x scale and read the images inline so the user sees all variants at once in chat without switching to Paper. Tell the user: > All N variants are on the canvas in Paper, laid out left-to-right. The > screenshots are above. Open Paper to compare them at full size. If any artboard failed to populate, report it explicitly. Don't silently skip. ## Step 4: Feedback and Iteration Wait via AskUserQuestion: > "Look at the variants in Paper or in the screenshots above. Which direction > works? Any specific feedback per variant? Want me to remix elements between > them?" Don't use AskUserQuestion to force a multiple-choice pick, leave it open so the user can give nuanced feedback ("B's layout, A's colors, C's typography is too playful"). When feedback comes back, summarize: ``` Here's what I understood: PREFERRED: Variant X NOTES: DIRECTION: Is this right? ``` Confirm with AskUserQuestion before iterating or saving. ### Iteration moves Pick the right Paper MCP tool for the change: - **Tweak text** in a variant: `mcp__paper__set_text_content` with the node IDs - **Tweak styles** (color, size, spacing): `mcp__paper__update_styles` - **Remix** ("A's layout with B's colors"): `mcp__paper__duplicate_nodes` to clone the chosen base, then `update_styles` and `write_html` to mix in the donor elements. Place the remix as a new artboard alongside the others. - **Generate a fresh round**: repeat Step 3 with new concepts. Place the new artboards in a second row (offset y by previous artboard height + 200 gap) so the iteration history stays visible on the canvas. - **Drop a variant** the user has rejected: `mcp__paper__delete_nodes` after confirming. Always wrap edits in `start_working_on_nodes` / `finish_working_on_nodes` so the user sees what's changing. After each iteration, screenshot the affected artboards again and show inline. Repeat until the user picks a direction. ## Step 5: Save and Dual-Write When the user approves a direction, do two writes plus an export. ### 5a. Export the chosen variant Call `mcp__paper__get_screenshot` at 2x scale for the approved artboard, plus 1x for each rejected variant (for the record). Save them as PNG files to: ``` /designs/-YYYY-MM-DD/ variant-A.png variant-B.png variant-C.png approved.png (copy of the chosen one at 2x) ``` Use a kebab-case `` derived from the brief. ### 5b. Project decision note Save `decision.md` in the same folder: ```markdown # Design - Paper file: Approved variant: Date: YYYY-MM-DD ## Brief ## Directions explored - A) — - B) — - C) — ## Chosen direction ## Feedback that shaped it ## Follow-up ## Files - approved.png - variant-A.png, variant-B.png, variant-C.png ``` ### 5c. Vault decision note (dual-write) Save to: ``` /Users/sebastianstoelen/Work/notes/raw/Notes/YYYY-MM-DD HHmm Design - .md ``` Frontmatter: ```yaml --- created: YYYY-MM-DD tags: - note - design project: screen: paper_file: --- ``` Body uses the same shape as `decision.md` but as a raw vault note. Do not write into `wiki/`. Nightly ingest will promote it later if worth promoting. ## Step 6: Next Steps Offer via AskUserQuestion: - A) Iterate more, refine the approved variant with specific feedback - B) Build it, hand off to implementation (the Paper artboard is the spec) - C) Done, I'll use this later If B and the project has a code stack, you can offer to use the approved artboard's `mcp__paper__get_jsx` or `get_computed_styles` to seed component code. ## Rules 1. Paper is the canvas. Variants are artboards, not files. 2. The user must have Paper Desktop running with their file open. If `get_basic_info` fails, stop and tell them. 3. Lay variants out spatially on the canvas (row for current round, new row for next iteration) so history stays visible. 4. Always wrap edits in `start_working_on_nodes` / `finish_working_on_nodes` so the user sees activity in Paper. 5. Show screenshots inline in chat after every round so the user doesn't have to switch windows just to see what changed. 6. Confirm feedback before saving. Always summarize what you understood. 7. Two rounds max on context gathering. Proceed with assumptions and note them. 8. `DESIGN.md` (or equivalent) is the default constraint unless the user says otherwise. 9. Each variant must be visually distinct. The headline-swap test is the bar. 10. On approval, dual-write: project workspace `decision.md` + vault decision note. Variant PNGs go to the project workspace only.