visual

Visual Questions Protocol (HUMAN-IN-THE-LOOP, NON-NEGOTIABLE)

You have access to two MCP tools on the PresentFast server: create_visual_question and wait_for_selection. These tools host a public, project-themed HTML page where the human can SEE and CLICK their answer instead of squinting at a 4-option terminal menu.

HOW THE TRIGGER ACTUALLY WORKS

Claude Code auto-injects a "Type something." free-text option into every AskUserQuestion call. When the user picks that option and types text, that literal text is returned to you as the answer string — with no wrapper, no "Other" label.

Therefore, the trigger fires in TWO places:

(A) In the answer to an AskUserQuestion call you just made — the answer string itself matches a trigger phrase below. (B) In a fresh user message before you've asked anything — the user typed /visual proactively. Treat the very next question as visual.

(A) is the primary path. (B) is a secondary convenience.

TRIGGER PHRASES (case-insensitive substring match)

If the user's answer string OR most-recent message contains any of these, the Visual Questions Protocol applies:

• /visual - /v
• "visually" - "visually show me"
• "show me visually" / "show visually"
• "let me see" - "I want to see"
• "show me the options" / "show the options"
• "show me the difference" / "compare visually"
• "preview them" - "open in browser"
• "use presentfast" / "use visual" / "visual mode"

HARD RULES (violating any of these is a bug)

0. ABSOLUTE FORBIDDEN PATHS — never do any of these for a visual question, no exceptions:

   • ✗ DO NOT generate or write an HTML file on disk for this question (e.g. mockup.html, options.html, anything you'd open afterwards).
   • ✗ DO NOT open a local HTML file in the browser (open foo.html, xdg-open …, start …).
   • ✗ DO NOT start a local web server (Python http.server, npx serve, the project's own npm run dev, or anything that binds to localhost / 127.0.0.1 / 0.0.0.0).
   • ✗ DO NOT use a file:// URL.
   • ✗ DO NOT paste raw HTML in the chat for the user to "save as a file".
   • ✗ DO NOT use ANY other backend, mock service, paste-bin, or third-party host.
   • ✗ DO NOT silently fall back to AskUserQuestion — see Rule 10.

   The ONLY sanctioned backend for visual questions is the PresentFast MCP server, reached via mcp__presentfast__create_visual_question and mcp__presentfast__wait_for_selection. If those tools are not available in this session, STOP and follow Rule 10. Do not improvise.

1. NEVER treat a trigger string as a literal answer. If AskUserQuestion returns "/visual" (or any trigger phrase) as the answer, that is NOT the user's substantive answer. It is a meta-instruction. Do not save a report named "/visual", do not pick the option whose label most resembles "/visual", do not interpret /v as "version". Re-issue the same question visually.

2. Re-issue the EXACT same question. When the trigger fires in an answer, call create_visual_question with the same question text and the same options list that you just asked via AskUserQuestion. The user did not change their mind about what's being asked — they changed how they want to see it.

3. Mandatory pre-step — scan the project for design tokens. BEFORE calling create_visual_question, inspect the current project to extract its design language. Required scan, in this order, stopping as soon as you have enough:

   a. tailwind.config.{ts,js,cjs,mjs} — read theme.extend.colors, fontFamily, borderRadius. b. CSS variable declarations matching --color-*, --font-*, --radius-* in *.css / *.scss files near the project root. c. design.md, DESIGN.md, STYLEGUIDE.md, brand.md at the project root — read any palette/typography sections. d. globals.css, app.css, theme.css — pull :root variables. e. Fallback: sample one real existing page or component and extract observed colors, fonts, and radii.

   Create a TodoWrite item "Scan project design tokens" before doing this so the step is visible.

   This plugin ships a scanner you can shell out to as a first pass:

   node "${CLAUDE_PLUGIN_ROOT}/skills/visual/scripts/scan-project-theme.mjs" \
     --cwd "$(pwd)" --name "<project-name>"
   

   It returns a JSON theme payload with palette, typography, and radii extracted from tailwind.config.* (falling back to sane defaults). Treat its output as a starting point; supplement from steps 3b-3e as needed.

4. Mandatory theme payload. The theme object you pass to create_visual_question MUST be populated from step 3 — not invented, not defaulted to generic colors. Required fields: project_name, palette.{primary,background,surface,text,muted}, typography.{heading_font_family,body_font_family}, radii.{sm,md,lg}. Missing fields cause the MCP tool to REJECT the call with a clear error — fix the scan and retry.

5. Mandatory project-themed preview_html. Each option's preview_html MUST use the colors, fonts, and component shapes you observed in step 3. The preview must look like it belongs to THIS project, not a generic mockup. Use Tailwind utility classes if the project uses Tailwind; use the project's CSS variables if it defines them. DO NOT inline <style> blocks that redeclare the theme — the page already injects it via CSS variables at :root.

6. Mandatory wait loop. Immediately after create_visual_question returns, print the URL to the user as a single short line, then call wait_for_selection in a loop. If it returns status: "pending", call it again. Continue until status: "selected" or status: "expired". Maximum total wait: 10 minutes.

7. Continue as if the user answered in the terminal. When wait_for_selection returns { status: "selected", option_id }, proceed with that option exactly as you would have if the user had picked it in the original terminal menu. The trigger detour is over.

8. No secrets in previews. The question page is publicly reachable by anyone with the URL. NEVER include API keys, customer data, internal hostnames, or proprietary source code in option labels, descriptions, or preview_html.

9. No fall-through. If wait_for_selection returns status: "expired", tell the user explicitly and ask if they want to retry. Do NOT silently fall back to AskUserQuestion.

10. MCP unreachable → STOP, do not improvise. If mcp__presentfast__create_visual_question errors out (any non-2xx response, timeout, or "tool not available"), report the error string to the user verbatim and STOP.

    • DO NOT generate a local HTML file as a workaround.
    • DO NOT use a localhost / 127.* / file:// URL as a workaround.
    • DO NOT silently fall back to AskUserQuestion.
    • DO NOT improvise any other backend.

    Tell the user the visual flow is unavailable and suggest they run /presentfast-setup to verify the PresentFast MCP server is wired and connected (or check npm view @presentfast/mcp-server version to confirm the package is installed). Then wait for instructions.

THE EXACT SEQUENCE (memorize this)

[ASK PATH — user couldn't decide from terminal labels]
  AskUserQuestion(question, options)
  → answer string returned to me
  → does answer string match a trigger phrase?  ─── no ──► proceed normally
                                                 │
                                                yes
                                                 ▼
  TodoWrite: "Scan project design tokens"
  → scan project (steps 3a-3e)
  → build theme + project-themed preview_html for SAME options
  → create_visual_question({ question, options, theme })   // same q+opts
  → print URL to user (one line)
  → loop: wait_for_selection({ question_id })
       until status ∈ {"selected","expired"}
  → continue work using the selected option_id

[PROACTIVE PATH — user said /visual before any question]
  User message contains a trigger phrase
  → next question I would have asked via AskUserQuestion
  → instead, go straight to the scan-and-create_visual_question flow above

EXAMPLES

Example A — answer-path trigger:

Me: AskUserQuestion("What output format do you prefer?", ["Markdown", "Terminal", "Both"])

User picks "Type something." and types /visual.

I receive: answer = "/visual"

WRONG: I save the report as a file named "/visual". WRONG: I pick "Markdown" because "/visual" sort-of-looks-like a format. RIGHT: I recognize the trigger, scan the project, build three themed preview cards for Markdown/Terminal/Both, call create_visual_question with the SAME question text and option list, then loop wait_for_selection.

Example B — proactive trigger:

User: "Redesign my hero section. /visual"

I would have called AskUserQuestion("Which hero style?", [...]). Instead I go straight to the scan-and-create_visual_question flow, asking the question visually.

WHEN THIS PROTOCOL DOES NOT APPLY

• The user's answer and most-recent message contain NO trigger phrase → use AskUserQuestion as normal. The "Type something." option is still present (Claude Code adds it), but it's not a Visual Questions trigger unless the user types one of the listed phrases.
• The MCP server is unreachable twice in a row → see rule 10.