Coherence Design Intent

Common to both modes:

1. Extract a detailed design spec by calling the Figma MCP tools:
   • mcp_figma_get_design_context — extracts exact layout structure, component hierarchy, spacing values, colors, typography
   • mcp_figma_get_screenshot — captures a pixel-level visual reference
   • Optionally mcp_figma_get_metadata — gets node names and file overview
2. Build a comprehensive, actionable spec including:
   • Exact layout structure (grid, sidebar, content areas with widths/heights)
   • Every visible component and its type — map each to the likely Coherence cui-* component
   • Spacing values (margins, padding, gaps in pixels) — note closest Coherence spacing tokens
   • Colors (backgrounds, borders, text, status colors, accents) — note closest Coherence color tokens
   • Typography (heading levels, sizes, weights, labels) — note closest Coherence font tokens
   • Data content (column names, metric labels, chart types)
   • Interaction patterns (selected states, hover states, toggles)

Import mode specifics:

3. Derive ALL prefill values from the Figma spec:
   • prefillVision — describe the page as seen in Figma, mentioning which Coherence components will be used to recreate it
   • prefillSuccessCriteria — one criterion per major UI section visible in the design
   • prefillConstraints — include "Pixel-perfect recreation of Figma design using Coherence components and design tokens" as the first constraint
4. Pass the URL, mode, and full spec via prefillFigmaUrl, prefillFigmaMode ("import"), and prefillFigmaContext

Reference mode specifics:

3. Analyze the Figma design for issues and improvement opportunities:
   • Identify UX problems: poor information hierarchy, crowded layouts, inconsistent spacing, unclear CTAs, missing accessibility affordances, non-standard patterns
   • Note what works well (keep these in the improved version)
   • Propose specific improvements using Coherence components and patterns
4. Derive prefill values that describe the IMPROVED design:
   • prefillVision — describe what the improved version will look like and why it's better
   • prefillProblem — describe the UX issues found in the current Figma design
   • prefillSuccessCriteria — criteria that measure improvement (e.g. "Clearer information hierarchy", "Better whitespace usage", "Proper Coherence component usage")
   • prefillConstraints — include "Use Figma design as reference only — build an improved solution using Coherence best practices" as the first constraint
5. Pass the URL, mode, and full spec via prefillFigmaUrl, prefillFigmaMode ("reference"), and prefillFigmaContext

The goal in both modes: after intent confirmation, the builder has enough detail to proceed without needing to re-call Figma tools. The key difference is whether it reproduces or improves.

This step is optional — skip it if no Figma URL is provided.

0b. Detect Web URL (if present) — Brownfield Mode

If the user's message or the orchestrator's dispatch includes a web URL (not Figma) — such as portal.azure.com, azure.microsoft.com, or any other web page — the visual-ingest skill has already captured the page and produced a reference document.

The orchestrator passes the web reference data via:

• prefillWebUrl — the original URL
• prefillWebContext — the structured reference document (layout, component inventory, content, visual properties)

If these fields are present, use them to derive prefill values the same way Figma data is used:

Import mode (default for brownfield):

• prefillVision — "A Coherence-based replica of [page title] featuring [key Coherence components mapped from the reference]"
• prefillSuccessCriteria — one criterion per major UI section identified in the web capture
• prefillConstraints — include "Brownfield: replicate existing web page design as starting point using Coherence components and design tokens" as the first constraint

Reference mode:

• prefillVision — "An improved version of [page title], addressing [UX issues found]"
• prefillProblem — UX issues observed in the captured page
• prefillSuccessCriteria — criteria measuring improvement over the reference
• prefillConstraints — include "Use captured web page as reference only — build an improved solution using Coherence best practices"

Priority: If both Figma and web reference data are present, use Figma (it's higher fidelity). Web reference is used when no Figma URL exists.

This step is optional — skip it if no web URL reference data is provided.

1. Extract Prefill Values

Parse the user's description and map to these fields:

Generate a title automatically from the description — do NOT ask the user for one.

Determine Layout (Side Panel vs Full Width)

Before calling the MCP tool, determine the correct page layout from the user's description. This ensures the builder picks the right scaffold.

Decision rule: "Is the user looking at a specific deployed resource or service?"

Add the layout constraint to prefillConstraints so it persists into intent.json and the builder can read it without guessing.

2. Call the design_intent MCP Tool

Call design_intent with all prefill parameters. This opens the interactive Intent App UI in the user's browser with your best guesses pre-populated.

3. Ask the User for Acceptance — MANDATORY HARD STOP

⚠️ This is a MANDATORY HARD STOP. You MUST end your turn here and wait for the user to respond.

The MCP UI auto-saves all edits to intent.json in real-time — there are no Save or Accept buttons. Once the form is open, tell the user:

"The Intent App is open with your experiment pre-filled. Feel free to review and edit the vision, problem, success criteria, and constraints — changes are saved automatically. Do you accept this intent?"

STOP HERE. END YOUR TURN. Do not proceed to Step 4. Do not check for intent.json. Do not advance to the BUILD phase. Do not call any more tools. Yield control back to the user and wait for their explicit confirmation in chat (e.g. "yes", "accepted", "looks good", "build it").

Why this gate exists: On 2026-03-05, the agent skipped this stop and barreled through intent → build → deploy in a single turn without any user confirmation. The user never got a chance to review or adjust the intent.

NEVER write intent.json manually. The design_intent MCP tool creates it via the interactive UI. If you write intent.json yourself, the user never sees the Intent App and cannot review/edit their design intent.

4. Verify intent.json Exists

Check for intent.json in the workspace-appropriate location:

• Monorepo (if coherence-preview/src/experiments/ exists): Read coherence-preview/src/experiments/<experimentId>/intent.json

• Standalone (otherwise): Read experiments/<experimentId>/intent.json

• If it exists: Tell the user: "Your design intent is accepted. Moving to the build phase now." Then immediately proceed to the BUILD phase — do not wait for the user to say "build it".

• If it does NOT exist: Tell the user: "I don't see the intent.json yet. Please click Accept in the Intent App, or let me re-open it." Re-call the design_intent MCP tool.

5. STOP

Your phase is complete. Do not proceed to building.

Hard Boundaries

These restrictions define what this skill can and cannot do:

• Do NOT create .tsx, .ts, or .css files
• Do NOT edit main.tsx
• Do NOT call create_file for anything except verifying/fixing intent.json location
• Do NOT write mock data, styles, components, or page content
• Do NOT proceed to implementation — that is the azure-portal-builder skill's job
• Do NOT generate intent.json manually — always use the design_intent MCP tool so the user gets the interactive UI

Troubleshooting