# /visual-plan

Turn ordinary implementation plans into rich interactive visual review surfaces.

`/visual-plan` turns the plan an agent would normally write in chat into a
human-optimized MDX document. In local-files mode, it writes and serves the MDX locally rather than publishing to the hosted Plan database. Instead of a long wall of prose, reviewers get
custom components built for understanding: architecture diagrams, wireframes,
interactive prototypes, file maps, annotated code, OpenAPI-style API specs,
visual schema maps, open questions, and comments.

It solves for plans that are too important to bury in chat. The output is
scannable, commentable, and intuitive enough for a human to approve before code
changes start.

<picture>
  <img alt="Visual plan review surface" src="../../media/visual-plan.png">
</picture>

Visual plans are MDX, customizable with your own components, and viewed with the
[Agent-Native plans app](https://www.agent-native.com/docs/template-plan). The
hosted app is 100% free and open source; local-files mode writes
MDX locally, starts a localhost bridge, and opens the hosted Plan UI with no
sharing.
[Source here](https://github.com/BuilderIO/agent-native/).

## What It Does

- Grounds plans in real repo files, schemas, actions, and symbols.
- Chooses the right visual surface: document-only, wireframe canvas, prototype,
  design direction, or visual intake.
- Uses MDX and custom components for diagrams, UI flows, API specs, schema maps,
  diffs, code annotations, and reviewer questions.
- Publishes the result as an interactive review document instead of inline chat Markdown.
- Keeps the plan as the approval gate before source edits begin.

## When To Use It

Use it for multi-file, ambiguous, risky, architecture-heavy, data-heavy, or
UI-heavy work where the wrong direction would be expensive. It is also useful
when a pasted text plan needs a richer review surface.

Skip it for trivial fixes, single-line changes, or anything whose diff is easier
to review than a plan.

## What Reviewers Get

Reviewers get a plan link that is built for scanning. Decisions, files,
diagrams, contracts, UI states, prototype behavior, schema shape, API boundaries,
and unresolved questions live in one consumable place.

For teams wiring visual plans into their review flow, the
[Plan app documentation](https://www.agent-native.com/docs/template-plan)
explains how the review surface is rendered and shared.

The point is not just prettier planning. It is a better medium for human review:
visual where visuals help, structured where structure helps, and grounded in the
actual codebase.

## Modes

`/visual-plan` can run in three modes:

- **Hosted Plans, shareable links (recommended):** uses the free, open-source
  Agent-Native plans app at plan.agent-native.com for shareable links, comments,
  and the browser editor.
- **Local files only:** writes a local MDX folder, starts a localhost bridge,
  and opens the hosted Plan UI against that local source. No sharing, all local,
  and no plan content is written to the hosted database. The skill must not
  create a hosted Plan first and export it back to local files.
- **Self-hosted/custom URL:** connects the skill to your own Plan app or local
  development tunnel.

Use hosted mode when you want comments and shareable links. Use local files mode
when the plan itself should live in source control or stay on your machine. Use
`plans/<slug>/` when you want to check the files in, or a temp/ignored folder
when you do not. The bridge URL works on the machine running it and is not a
share link.

## Install

```sh
npx @agent-native/skills@latest add --skill visual-plan
```

The interactive installer asks whether to use hosted Plans or local files. To
force the no-sharing local path:

```sh
npx @agent-native/skills@latest add --skill visual-plan --mode local-files
```

The skill expects the [Plan MCP connector](https://www.agent-native.com/docs/template-plan)
to be available when hosted mode is used.

# Canvas & artboard placement — single source of truth

This file is the canonical guide for how the visual-plan canvas works: artboard
placement, lane layout, annotations, patching, and the legacy kit tree. Read it
in full before authoring or editing any canvas/artboard content; do not author
canvas layouts from memory or paraphrase these rules per mode.

<!-- SHARED-CORE:canvas-surface START -->

**The coordinate rule.** The `surface` locks each artboard's footprint and
aspect — never set artboard width/height and never use coordinates inside the
wireframe HTML; board-level artboard `x`/`y` IS allowed when it creates clear
lanes. Let canvas auto-placement handle simple one-row boards.

**Lay out mixed canvases in lanes.** When a canvas contains broad browser /
desktop frames plus compact `mobile`, `popover`, or `panel` surfaces, do not put
everything in one horizontal strip. Use board-level artboard `x`/`y` to reserve
lanes with generous empty space: main flow on one row, compact surfaces in their
own column or row, and loading/error states in a lower row. Keep at least 96px
between rendered artboard rectangles plus room for annotation gutters; when a
broad browser/desktop frame sits beside a compact panel/popover, leave at least
160px so frame borders, labels, and hover controls never touch. Connect only
neighboring steps; never draw a long connector that skips across unrelated
frames. Connector labels must sit in open canvas space. If the label would touch
or cross either artboard, remove the label and explain the transition with a
nearby annotation instead. Before handoff, inspect the top canvas at default zoom
and move any frame whose label, connector, or annotation crosses another frame.

**Board-unit spacing defaults.** The canvas coordinate system uses approximately 2 board units per screen pixel. `browser` frames occupy roughly 700 × 600 board units; `desktop` frames roughly 900 × 700 board units. Apply these minimum x/y gaps when placing frames explicitly — any less and frames will touch or overlap:

- x-gap between `browser` frames: **≥ 1100** (700-unit frame + 400-unit gutter)
- x-gap between `desktop` frames: **≥ 1300** (900-unit frame + 400-unit gutter)
- y-gap between rows of any surface: **≥ 1400** (includes frame height + section header + buffer)

When in doubt, use larger values — the canvas auto-zooms to fit everything.

**Canvas annotations are designer notes on the artboard.** When a top canvas is
present, sprinkle design-review notes near the frames they explain: a short
heading, supporting text, and bullets — plain text layers, never bordered or
shadowed cards, and never a box around a frame. The renderer spaces notes away
from frames, so place each note by the frame it describes. Use an arrow only to
point at one specific control or transition; for a broad frame-level note, write
text beside the frame with no connector. Connectors are for real sequences only —
never fake "Step 1 → Step 2" lines between independent states.

**Do not create overlapping annotations.** Anchor each ordinary note to the
frame it explains with `targetId` + `placement` (top/right/bottom/left), and
omit `type` or use `type: "note"`. The renderer parks notes in a gutter beside
the frame and lays them out automatically. Do not use `type: "callout"`,
`type: "text"`, `type: "arrow"`, x/y, or points for ordinary notes; those are
freeform review-markup layers and must be reserved for intentional markup in
open canvas space. Reserve arrows for a note that must point at one specific
control inside a frame; a note that simply sits beside its frame needs no arrow.

**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted `contentPatches`
(for example `patch-wireframe-html`, `patch-diagram-html`, `update-block`,
`replace-blocks`, `update-canvas-annotation`) rather
than regenerating the whole plan. `contentPatches` are part of the public MCP
action schema, so Claude Code, Codex, Cursor, and other hosts can make surgical
edits. If an agent is working from exported source files, use
`read-visual-plan-source` / `patch-visual-plan-source`: `plan.mdx` holds
frontmatter plus markdown/document blocks, `canvas.mdx` holds
`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>`, and the
patch action normalizes the MDX back into the same JSON runtime model. JSON is
the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
In the browser, humans edit `rich-text` prose inline; agents should still use
`update-rich-text` content patches or source patches for prose, and use
comments/structured patches for canvas, artboard, wireframe, and diagram edits.
Never send a partial top-level `content` object as a shortcut to add a canvas,
frame, or block: `content` is a full structured replacement, so omitted blocks
or surfaces can disappear. If a full replacement is truly unavoidable, read the
complete source/JSON first, include every existing block and surface in the new
payload, and verify the source/export immediately after the update.

**Never emit a titled artboard with no interior wireframe content.** Every artboard
you place on the canvas must carry an `html` wireframe or reference a wireframe
block via `blockId`; when using `blockId`, the referenced `wireframe` /
`legacy-wireframe` block must remain in the plan. If you remove a duplicate
wireframe from the document body, first move its `data` inline onto the
corresponding `content.canvas.frames[*].wireframe` / `legacyWireframe`. A
label-only frame or a frame pointing at a deleted block renders empty and is
rejected at parse time. If you only have a title, write it as a section header or
annotation, not an empty artboard.

**UI mockups belong in the top visual review area.** Static UI/product visuals
live on the canvas; multi-step UI flows get both canvas wireframes and a
prototype. When the user asks for a mockup, UI state, loading state, layout,
screen, or visual comparison, make the canvas the primary home for that static
visual. When the user asks for a prototype or the plan contains a sequence the
reviewer must feel, keep the canvas artboards and add `content.prototype` so the
top surface shows Wireframes / Prototype tabs. Architecture/code diagrams stay
inline in the document (the SKILL.md Visual Surface Choice section owns that
rule) unless the user explicitly asks for a spatial board. Document blocks
can explain, compare, or map implementation, but they should not host the
primary UI mockup or prototype just because `custom-html`, screenshots, or prose
are easier to produce. If the canvas/prototype surface cannot represent the
requested UI fidelity, still keep the closest top-surface representation and
call out or extend the needed renderer capability. A skeleton/loading mockup
also lives in a canvas artboard — never move a mockup out of the canvas.

**Storyboards are canvas artifacts, not document diagrams.** When the requested
output is a product flow, onboarding journey, "light storyboard", or canvas
wireframe, author the flow as multiple top-canvas artboards with real screen
content and neighboring connectors. Keep document-body `diagram` blocks for
architecture and mechanics that are not themselves user-visible screens. A
storyboard made from a single inline HTML diagram is the wrong surface.

For abstract product concepts, use the canvas to create the first "I get it"
moment: one real app state near the top showing how the concept appears to a
user, followed by separate annotations or diagrams for mechanics. Do not make
the first artboard a hybrid of app UI and architecture notes; the app screen
should be inspectable as product UI on its own.

**Legacy kit tree.** Older plans set a `screen` array of `{ el, ...props }` kit
nodes instead of `html`; the renderer still accepts and displays it so saved
plans round-trip, but new plans emit `html`. Do not author fresh kit-tree
screens, and do not put nested kit components such as `<FrameScreen>`, `<Card>`,
`<Row>`, `<Title>`, or `<Btn>` inside a canvas `<Screen>`. A new canvas artboard
with kit-tree children is a defect: replace it with
`<Screen surface="..." html={...} />` using the HTML wireframe rules. The HTML
path is the one that gets the renderer-owned surface sizing, theme tokens,
sketch/clean toggle, and safe text layout used by good document-body
wireframes. Likewise, old or imported plans may carry coordinate-based regions
or free-float x/y on notes; those are legacy escape hatches the renderer still
shows but you must never produce. The gutter parks notes by `targetId` +
`placement`, and the coordinate rule at the top of this file governs all
new-plan placement.

<!-- SHARED-CORE:canvas-surface END -->

# Connecting & publishing — single source of truth

This file is the canonical rule for the never-inline deliverable, finding the
Plan MCP connector, and restoring it when its tools are missing. It is shared
word for word by `/visual-plan` and `/visual-recap`. Read it when you are about
to publish, or whenever a connector or auth error appears; do not improvise an
inline fallback from memory.

<!-- SHARED-CORE:connection START -->

**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat
content.** Do not hand the plan or recap to the user as Markdown prose, an ASCII
sketch, a table, a fenced "wireframe", or a "here's the summary" paragraph. The
entire value is the hosted, interactive, annotatable Plan; an inline summary is
the thing a Plan replaces, not a degraded version of one. The only supported
output is to publish through the Plan MCP connector and return its absolute URL.
Local-files privacy mode (`references/local-files.md`) is the one exception.

**The connector is usually the `plan` server**, but older installed agents may
expose the same hosted connector as `agent-native-plans` — both names are valid,
so never report the connector as missing just because it is named
`agent-native-plans` instead of `plan`. Some clients also lazy-load connector
tools through a deferred tool registry instead of showing the namespace upfront.
Before declaring the connector missing, search/load tools with the host's
discovery surface (`tool_search` when available) for `create_visual_plan`,
`create_visual_recap`, or `get_plan_blocks`, then use the tools it exposes.

**If the tools are still missing after discovery, do NOT fall back to inline
output.** The usual cause is a connector that did not finish connecting this
session (it registers zero tools), NOT necessarily an auth problem — so do not
assume the user must re-authenticate. Stop and give the user the exact restore
step for their current client:

- **Codex / Codex Desktop:** run
  `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
  and start a new Codex session.
- **Claude Code:** run `/mcp` and choose Authenticate/Reconnect, or run the same
  reconnect command with `--client claude-code` and restart Claude.

The same applies when a Plan tool returns `needs auth`, `Unauthorized`, or
`Session terminated`: stop retrying the tool and give the reconnect step instead.

Auth is stored per client config/session, so one client's reconnect does not make
another running client load tools. `--client all` refreshes every local client
config that already has the Plan entry, but each running client still has to
reload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling
and finds the entry by URL regardless of connector name — never reinstall from
scratch just to fix auth. Publish once the tool is reachable. Falling back to
inline content is a defect, not a degraded mode.

<!-- SHARED-CORE:connection END -->

# Plan document quality — single source of truth

This file is the canonical quality bar for the plan document below the canvas:
how it reads, which blocks to use, how open questions are surfaced, and the
pre-handoff check. Read it in full before authoring the plan document; it is the
quality bar. Do not write the document from memory or paraphrase these rules per
mode.

<!-- SHARED-CORE:document-quality START -->

**The document is a serious technical plan, not marketing.** Write it the way a
strong Claude or Codex implementation plan reads: outcome-first, prose-first,
self-contained, and specific. State the objective and what "done" means, the
scope and non-goals, the proposed approach with the key decisions and their
rationale, ordered steps that name real files, symbols, actions, and data
shapes, the risks, and a closing verification step (tests, build, or a checkable
behavior). Replace vague prose with specifics; never ship a step like "make it
work." No hero art, gradients, logos, nav bars, slogans, value props, giant
landing-page headings, or marketing cards unless the user explicitly asks.

**Every published plan must stand alone.** Even when the agent is revising an
existing plan, the output is a plan to do the work, not a changelog of the
conversation. Do not write phrases like "preserve the previous plan", "do not
drop the old idea", "as discussed above", "this revision", "unlike the prior
version", or "correction from the earlier plan". Fold the right decisions into
the plan as normal objective, architecture, scope, and roadmap prose. A reviewer
who opens the plan from a link with no chat history should understand it. Avoid
negative framing that only makes sense against absent context ("not the old
mode", "not just X") unless the contrast is defined in the plan and genuinely
helps; state the positive model directly.

**Make abstract plans instantly legible.** If the idea is broad, strategic, or
intended for a third-party reviewer, put one concrete product snapshot near the
top before dense architecture, mode tables, manifests, or roadmaps. For
UI-capable concepts, that snapshot is usually a top-canvas app state plus a
short paragraph that says what the user sees and what changes under the hood.
Then put mechanics, data flow, sync boundaries, and implementation detail in
separate diagrams or document sections.

**Preserve the user's level of abstraction.** A motivating use case is not
automatically the architecture. When the prompt describes a broader framework,
product mode, or reusable primitive, separate the reusable core from specific
apps, providers, customers, scripts, or launch examples. Use the concrete
example to make the plan understandable, then make clear which parts are core,
which are app-specific adapters, and which are future examples.

**When top visuals exist, they and the document never duplicate each other.**
For UI work, the UI story lives in the top visual surface: canvas artboards for
static inspection, plus prototype tabs when the flow should be functional. The
document carries the technical depth the visuals cannot show — concrete
file/symbol maps, API and data contracts, code snippets, migration or
implementation phases, risks, and validation. For architecture/code reviews,
invert that: the document is the visual surface, and each recommendation
carries its own nearby inline `diagram` / `data-model` block plus file
evidence (the `diagram` bullet below owns how to author those diagrams).
Repeat a wireframe in the document only for a genuinely new detail view or
comparison. Skip the visual surface entirely for non-visual work and write a
clean rich document. For a simple binary UI visual choice, show the two
directions in the canvas only; do not repeat the same options as body
wireframes or prose. Put the actual choice in the bottom "Open Questions" form.

**Use the right block, and make it carry substance.** For the authoritative,
machine-checked list of block types and their data schemas, call `get-plan-blocks`
— it returns the live registry vocabulary (type, MDX tag, placement, key fields)
so you never emit a block the editor cannot render or round-trip:

- `rich-text` for plan prose with real bold/italic/code/links and nested lists.
- `annotated-code` for the file map: when a load-bearing file is worth
  highlighting, prefer the annotated walkthrough over a bare `code` block — carry
  the real, syntax-highlighted code AND anchor short margin notes to the lines
  that actually change (the new action, the changed schema, the wiring point), so
  the reader sees what matters and why instead of code for code's sake. Each
  annotation is `{ lines: "12" | "12-18"; label?; note }`; keep a few high-signal
  notes per file, not one per line. Highlight only the files worth reading; never
  an exhaustive list of every touched file, and never a prose-only description of
  a file. Drop to a plain `code` block only for a throwaway snippet with nothing
  to call out. When more than one file matters, group the blocks in a vertical
  `tabs` block (the standard tab primitive) rather than a bespoke container. If
  the exact code is unknown, show the smallest plausible planned shape or a
  commented stub naming what to fill in. (`code-tabs` and `implementation-map`
  are legacy: their renderers stay for old plans, but do not author new ones.)
- For a decision: if the reviewer must still pick between a genuinely-open
  either/or, put it in the bottom Open Questions `question-form` as a `single`
  question — one option per real alternative, each with a short detail and
  `recommended: true` on the one you would choose; do not also restate the same
  choice elsewhere. If you have already committed to an approach, state it as
  settled prose or a `callout` with `tone="decision"`, optionally with a
  `columns` block for a side-by-side comparison of the options you weighed — not
  as a confusing mid-document form for a question you have already answered.
- `columns` for side-by-side before/after or current/target comparisons where
  each side needs real nested blocks; label the columns clearly and avoid
  stacking comparison blocks vertically when parallel reading is the point.
- `diagram` for two-dimensional architecture, dependency, data-flow, or state
  relationships, only when it clarifies something real. Prefer standard
  two-dimensional layouts — paired before/after panels, layered diagrams,
  swimlanes, dependency maps, matrices, or grouped regions; do not default to
  left-to-right chains, and use a line only when the relationship is truly a
  sequence. Do not use a body `diagram` as the primary artifact for a requested
  product canvas, light storyboard, UI flow, screen flow, or wireframe; those
  belong in the top canvas as artboards with `Screen` wireframes first. Use
  diagrams below that canvas only for architecture, data flow, or implementation
  mechanics. For architecture/code
  diagrams, prefer `data.html` / `data.css` with semantic HTML and inline SVG so
  the diagram can use panels, layers, matrices, arrows, annotations, and
  responsive layout directly. Author diagram HTML with renderer-owned primitives
  like `.diagram-panel`, `.diagram-card`, `.diagram-node`, `.diagram-box`,
  `.diagram-pill`, `.diagram-muted`, and `[data-rough]`; they map to the plan's
  Tailwind theme variables through `--wf-ink`, `--wf-muted`, `--wf-line`,
  `--wf-paper`, `--wf-card`, `--wf-accent`, `--wf-accent-soft`, `--wf-warn`, and
  `--wf-ok`, and switch to Excalifont plus rough.js outlines in sketchy mode. Do not
  set `font-family` and do not hard-code hex, rgb, or hsl colors in diagram HTML
  or CSS. Choose the outer `frame` intentionally: use `show` when the diagram
  stands alone in a recap, comparison, or prose section; use `hide` when the
  diagram sits inside docs chrome, columns, tabs, cards, a canvas surface, or
  already has visible `.diagram-panel` / `.diagram-box` structure. Leave room
  for the sketch font: keep labels short, give nodes generous width, and place
  boundary/annotation labels in unused space instead of over nodes; labels must
  not overlap nodes, connectors, or each other. For small text/SVG changes to an
  existing HTML diagram, use `patch-diagram-html` with a unique
  `find`/`replace` snippet instead of resending the whole `data.html` string.
  Use legacy `nodes` / `edges` only for small previews or truly
  sequential flows. In architecture/code plans, prefer a repeated section rhythm:
  recommendation title, confidence and category badges, code-path evidence, a
  local before/after or current/target spatial diagram, then concise
  Problem/Solution/Why text.
- `tabs` for multiple states, directions, or comparisons. A tab that reveals
  only prose usually means the plan is under-specified — include a relevant
  visual unless the tab is intentionally document-only.
- `table`, `checklist`, `callout` for scannable structure.

**Open questions live at the bottom as a form when answers would change the
plan.** Surface answerable unresolved decisions in a final `question-form`
block titled "Open Questions" so the renderer presents it as a distinct section.
That bottom form is the ONLY place that enumerates the open questions: never add
a second "Open Questions" heading, list, or recap of the same questions earlier
in the document. A one-line pointer in the overview prose ("a few decisions are
still open — see Open Questions below") is fine, but do not reproduce the
question list or a parallel questions/decisions section above it.
Use `single` or `multi` for clear choices, `freeform` for constraints,
`recommended: true` for the default you would pick, and option `wireframe` /
`diagram` previews only when the options are not already visible in the top
canvas. `single` and `multi` questions always render a write-in field so a
reviewer can answer with a custom option — never add an explicit "Other" option
yourself; set `allowOther: false` only when a free-text answer makes no sense.
Keep non-answerable assumptions or risks as concise `callout` blocks in
the relevant section. Never bury a questions/decisions wall inside the plan
narrative, and never ask the same question twice.

For complex plans, do not end without an open-question audit. If architecture,
scope, UX, data shape, rollout, provider mapping, or ownership still depends on
a choice, either commit to a recommendation with rationale or add it to the
bottom form with a recommended default. A complex plan with no open questions is
fine only when every meaningful decision has been explicitly made.

**Verification must exercise the real workflow.** The final verification section
should go beyond typecheck/unit tests when the plan changes UI, local files,
sync, providers, browser behavior, or multi-app flows. Include at least one
end-to-end smoke that matches the user journey, such as a fresh repo/folder,
real manifest or data fixture, browser interaction, save/sync action, and an
on-disk or database assertion. Name the command or manual browser path when it
is known.

**`custom-html` is a bounded escape hatch only** — a single complete fragment
inside a block, never `html`/`head`/`body`/`script` tags, never a generic
placeholder, density demo, or proof that custom HTML works. Prefer the native
blocks for normal plans. For architecture/code reviews, use `diagram`
`data.html` / `data.css` for rich local HTML/SVG diagrams instead of
`custom-html`. For UI/product work, `custom-html` is never the primary home for a
requested mockup, UI state, or visual comparison. If UI fidelity requires
HTML/CSS, image capture, or real React/CSS, the product fix is canvas support
for that artifact type, not moving the mockup into the document.
When `custom-html` is genuinely needed, author it against the sandbox-provided
theme tokens (`--wf-paper`, `--wf-card`, `--wf-ink`, `--wf-muted`,
`--wf-line`, `--wf-radius`, and the matching `--plan-*` aliases). Do not hardcode
hex/rgb/hsl light palettes such as white cards with dark ink; the same fragment
must read in dark mode without a plan-specific patch.

**Before handoff, open the plan and check it.** Fix overlap, excessive
whitespace, clipped fragments, misleading inactive controls, poor contrast, and
unreadable diagrams before asking for approval. Check the top canvas in the
current Plan theme, especially dark mode: white mockup panels, low-contrast
muted text, or invisible controls are defects. If a frame only works in one
theme, rewrite the HTML with `--wf-*` tokens and semantic helper classes before
surfacing the plan.

<!-- SHARED-CORE:document-quality END -->

# Good vs. bad exemplar — single source of truth

This file is the canonical worked example of a great plan (and the anti-patterns
to avoid). Read it alongside the document-quality and canvas references before
authoring a plan; it is the bar these plans must clear.

<!-- SHARED-CORE:exemplar START -->

**GOOD.** A UI-first plan for a todo app: a canvas with a `desktop` artboard whose
`data.html` is a real flex layout — a sidebar of links (`Inbox 12`, `Today 4`,
`Done`), a main column with an `<h1>Today</h1>`, accent `.wf-pill`s for the
filters, a muted section label `OVERDUE`, and `.wf-card` task rows carrying real
titles, due dates, and a primary `button.primary` — styled only through bare
elements, helper classes, and `--wf-*` tokens, so the renderer applies the
correct desktop footprint, theme, and one subtle whole-frame wobble. Plain-text
designer notes sit spaced off the frame, pointing only at the controls that need
explanation. Below it, a Claude/Codex-grade document: objective and
done-criteria, a few `code` blocks (grouped in a vertical `tabs` block when
more than one) showing the real shape of the load-bearing files, a `callout`
with `tone="decision"` stating the chosen approach with a `columns` block
weighing the two real options behind it,
and a validation step — none of it repeating the canvas. If the task also
changes a multi-step completion flow, the same top area includes a Prototype tab
whose screens use the same labels and states as the canvas artboards, with
`data-goto` controls for the sequence. This is the bar.

**GOOD.** A broad product-architecture plan opens with a plain recommendation
and one concrete app state before the abstraction. The first canvas artboard is
pure product UI that matches the current app shell; nearby notes explain the
user-visible delta. A separate diagram below shows the mechanics, such as file
or data flow. The document then separates the reusable core from app/provider
adapters and examples, covers contracts, folder or schema shape, sync
boundaries, roadmap, non-goals, a bottom Open Questions form for unresolved
decisions, and a verification section with at least one realistic end-to-end
smoke. A reviewer who was not in the chat gets the idea from the top snapshot
before reading the technical plan.

**GOOD.** A `/visual-plan` for a backend architecture review: no top canvas.
The document opens with context and a legend, then repeats recommendation cards:
title, confidence/category badges, a monospace grid of real file paths, one
inline two-dimensional before/after or layered architecture diagram, and terse
Problem/Solution/Why bullets using the codebase's vocabulary. The diagram uses
space to show boundaries, layers, and ownership; it is not a default
left-to-right chain. The plan ends with a top recommendation and a bottom
question-form only if the next architecture direction is genuinely open. This is
better than a top canvas because each diagram is local to the claim it supports.

**BAD.** A `data.html` with hard-coded hex colors, a `font-family`, or fixed
pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
frame; a forced desktop + mobile pair for a popover; floating bordered
annotation cards hugging the frames; a fresh hand-authored kit-tree `screen`
instead of `html`; a multi-step UI flow with only static frames and no prototype
tab; a mockup escaped into a document `custom-html` block; and a marketing-style
document with a hero heading and value props that just restates what the canvas
already shows. Also bad: an architecture-only plan forced into a top canvas of
labeled boxes with overlapping text, where the actual code evidence and
recommendations live elsewhere; a product wireframe that mixes a real screen
with repo names, file-contract arrows, architecture explanations, or a made-up
permanent inspector; and a plan that describes itself as a revision of a prior
conversation instead of a standalone proposal. Never produce this.

<!-- SHARED-CORE:exemplar END -->

# Local-files privacy mode — single source of truth

This file is the canonical contract for fully local, no-database planning and
recaps. It is shared word for word by `/visual-plan` and `/visual-recap`. Read it
in full before using local-files mode; do not call any hosted Plan tool for a
local plan/recap except the schema-only block-catalog lookup described below.

<!-- SHARED-CORE:local-files START -->

**When to use it.** Use local-files privacy mode when the user explicitly asks
for no DB writes, no hosted Plan database writes, no Plan MCP publish, fully local
files, offline/private work, or repo-owned/source-controlled artifacts, or when
`AGENT_NATIVE_PLANS_MODE=local-files` is set. Also use it when a user or repo
policy says the work must stay under their own brand, domain, source control, or
infrastructure. In this mode the plan/recap data must never be sent to the Plan
MCP server or the Plan app action surface. This is the only exception to the
always-publish rule in `references/connection.md`.

The local-files contract:

- **Read context locally.** Read source, diff, and stat context from local files
  and shell commands only. For recaps, the
  `npx @agent-native/core@latest recap collect-diff`, `scan`, and
  `build-prompt --local-files` helpers are safe — they operate on local files and
  do not write to the Plan database.
- **Fetch the block catalog first** (it sends no plan content). Use the MCP
  `get-plan-blocks` tool if it is already available, or run
  `npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that
  file before authoring MDX; it calls the public no-auth `get-plan-blocks` route.
  Use `--format schema` when you need exact nested fields. If network access is
  unavailable, use the bundled `references/*.md` and rely on `plan local check` to
  catch invalid tags. Copy the catalog examples verbatim for the fields the
  registry table cannot encode: `checklist` items need `id` and `label`;
  `question-form` questions need `id`, `title`, and `mode`, and each option needs
  `id` and `label`; and `Code` / `AnnotatedCode` / `Diff` are whitespace-sensitive
  — encode multiline code as JSON string attributes such as `code={"const x =\n  y"}`
  (a static template literal is accepted only when it has no `${...}`
  interpolation). `plan local check` is a quick OFFLINE lint (a subset of the
  renderer schema), so a green `check` does not guarantee the plan renders.
  `plan local verify` also stays on-device: it uses the offline lint unless it
  can reach a Plan renderer on an explicit loopback `--app-url`.
- **Write a local MDX folder.** Use `plans/<slug>/` to check the artifact into the
  repo, or a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/`
  or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The
  folder holds `plan.mdx`, optional `canvas.mdx`, optional `prototype.mdx`, and
  optional `.plan-state.json`. For a recap, set `kind: "recap"` and
  `localOnly: true` in the frontmatter/state. Use that exact folder as
  `<plan-dir>` in every command below.
- **Check, then serve.** Run
  `npx @agent-native/core@latest plan local check --dir <plan-dir>` before any
  preview, then
  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind <plan|recap> --open`
  (use `--kind plan` for plans, `--kind recap` for recaps). Report the local
  bridge URL from stdout or `<plan-dir>/.plan-url`; treat `.plan-url` as a local
  token file and do not commit it. The URL opens the hosted Plan UI but reads from
  the localhost bridge on this machine, so it is not shareable across machines.
  The token is carried in the URL fragment (which is not sent to the hosted
  origin), and the local-plan route disables DOM autocapture and session replay
  while retaining sanitized pageviews and error monitoring. On
  macOS `--open` prefers Chromium browsers; if Safari opens, switch to
  Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the
  HTTP localhost bridge. If the Plan app itself is running locally with the same
  `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route is also valid. In a truly
  offline environment, hand off the `<plan-dir>` path after `plan local check` and
  note that interactive preview requires network access to the hosted Plan UI or a
  running local Plan app.
- **Headless verify.** Run
  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>`.
  It starts the bridge and checks the private-network preflight and JSON payload
  entirely on loopback. It never sends MDX or assets to a remote validation
  action. When `--app-url` points to a loopback Plan app, verify also validates
  against that local app's real renderer schema via `validate-local-plan-source`.
  A non-`ok` result with
  `validation.valid: false` lists the renderer's exact schema-path issues (e.g.
  `blocks[1].data.tabs[0]...`); fix those before handing off. If `validation.ran`
  is `false`, verify used the offline lint because the app URL was remote or the
  local Plan app was unavailable. Run a local Plan app and pass
  `--app-url http://localhost:8096` for the authoritative check. If the browser hangs on
  "Loading plan", fetch the `bridgeUrl` from the verify/serve JSON to read the
  concrete validation error.
- **Never call hosted tools for that plan/recap.** Do not call
  `create-visual-plan`, `create-ui-plan`, `create-prototype-plan`,
  `create-plan-design`, `create-visual-recap`, `create-visual-questions`,
  `import-visual-plan-source`, `update-visual-plan`, `patch-visual-plan-source`,
  `get-plan-feedback`, `export-visual-plan`, `set-resource-visibility`, or any
  other hosted Plan tool — except the schema-only block-catalog lookup above.
- **Feedback is file/chat feedback.** Update the MDX files directly, rerun
  `plan local check`, and rerun `serve` or `verify` when that preview path is
  available. Summarize the new local URL when one exists; otherwise summarize the
  checked `<plan-dir>` path. Hosted comments, sharing, screenshots, history, usage
  attachment, and publish/export receipts are unavailable until the user
  explicitly opts into publishing.

Local-files mode prevents plan/recap content from being uploaded to the
Agent-Native Plan server or database. It does not by itself make the coding agent's language model local;
for that stronger boundary the host agent/model must also be local or otherwise
approved by the user.

<!-- SHARED-CORE:local-files END -->

# HTML wireframe quality — single source of truth

This file is the canonical quality bar for HTML wireframes / `<Screen>` /
`WireframeBlock` content, shared word for word by `/visual-plan` and
`/visual-recap`. Read it in full before authoring ANY wireframe; do not
author wireframes from memory or paraphrase these rules per command.

<!-- SHARED-CORE:wireframe-quality START -->

**A wireframe is an HTML mockup. The renderer owns the look; you write the
content.** Set `data.html` to a self-contained, semantic HTML fragment of the
screen and set `data.surface`. The renderer owns the surface footprint/aspect,
the dark/light theme, the hand-drawn font, and the rough.js sketch overlay — you
never write `<html>`/`<body>`/`<script>`/`<style>` tags or any
width/height/coordinates. You write real HTML layout and real product
content; the renderer styles and roughens it.

**A wireframe block's data is an HTML screen plus a surface:**

```json
{
  "surface": "browser",
  "html": "<div style=\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\"><h1>Sign in</h1><p class=\"wf-muted\">Use your work email to continue.</p><div class=\"wf-card\" style=\"display:flex;flex-direction:column;gap:10px\"><label>Email<input value=\"jane@acme.co\" /></label><label>Password<input value=\"••••••••\" /></label><label style=\"display:flex;align-items:center;gap:8px\"><input type=\"checkbox\" checked /> Remember me</label><button class=\"primary\">Sign in</button></div><a href=\"#\">Forgot password?</a></div>"
}
```

**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
(`h1`/`h2`/`h3`, `p`, `button`, `input`, `<input type="checkbox">`, `a`, `hr`)
are auto-themed — no classes needed. Helper classes carry the rest:

- `.wf-card` / `.wf-box` — a bordered, padded container (a panel, a list item).
- `.wf-pill` / `.wf-chip` — a rounded tag or filter; add `.accent`
  (`<span class="wf-pill accent">`) for the accent-filled variant.
- `.wf-muted` — secondary/muted text (or use `<small>`).
- `button.primary` or any element with `[data-primary]` — the accent-filled
  primary button.

**No decorative shadows around mockups.** Do not put `box-shadow`, `filter:
drop-shadow(...)`, Tailwind `shadow-*` classes, or other fake depth effects on a
wireframe frame, root container, `.wf-card` / `.wf-box`, or canvas artboard.
Mockups should read as flat, bordered surfaces; use spacing, borders, labels,
and annotations for separation. Only show a shadow when the real product UI
already has that shadow and it is essential to the change being reviewed.

**Use renderer icons, not visible icon words.** For icon-only buttons or leading
icons inside fields, chips, menu items, and toolbars, write an empty marker such
as `<span data-icon="mail" aria-label="Email"></span>` or
`<i data-icon="lock"></i>`. The renderer replaces it with a Tabler-style SVG and
the `.wf-icon` class sizes it to the surrounding text. Supported names and
aliases: `mail`/`email`, `lock`/`password`, `search`, `plus`/`add`, `x`/`close`,
`check`, `chevronDown`, `chevronUp`, `chevronLeft`, `chevronRight`, `dots`/`more`,
`chevron`/`caret`/`dropdown` (down chevron), `user`, `settings`, `calendar`,
`bell`, `send`, `edit`, `arrowLeft`, and `arrowRight`. Do not put visible words
like "email", "lock", "search", "chevron", or "more" where the product UI would
show an icon; use text only when it is a real label a user would read.

**Use the `--wf-*` tokens for any custom color, never hex.** The renderer flips
these on light/dark, so reading them is what keeps a mockup correct in both
themes. For any inline border, background, or text color, reference a token:
`style="border:1.4px solid var(--wf-line)"`. The tokens are `--wf-ink` (text),
`--wf-muted` (secondary text), `--wf-line` (borders/dividers), `--wf-paper`
(page background), `--wf-card` (container surface), `--wf-accent` /
`--wf-accent-fg` / `--wf-accent-soft` (brand action), `--wf-warn`, `--wf-ok`,
and `--wf-radius`. Never hard-code a hex color and never set `font-family` — the
renderer owns the sketch/clean font.

**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as
`bg-white`, `bg-zinc-50`, `bg-slate-950`, `text-zinc-950`,
`text-slate-400`, `border-zinc-200`, `hover:bg-slate-800`, `shadow-xl`,
or arbitrary color utilities like `bg-[#fff]` leak the host app's CSS into the
mockup and can make dark-mode canvas frames unreadable. Use bare semantic
elements, `.wf-*` helper classes, and `--wf-*` color tokens instead. Before
publishing, scan every wireframe `class` and `style` attribute: if a class sets
background, text, border, ring, fill, stroke, gradient, placeholder, decoration,
or shadow color, rewrite it to renderer tokens or remove it. Layout-only classes
are still discouraged; inline flex/grid styles are safer and easier to review.

**Keep Rough.js sparse.** The renderer sketches the outer frame, standard
`.wf-*` primitives, controls, and inline border dividers by default. Do not add
`data-rough` to broad root wrappers, dialog shells, page panels, grid cells, or
nested containers unless that single container is the visual point. Use
`data-rough` only for a deliberate one-off shape. If a mockup starts looking
like stacked/overlapping sketch lines, remove rough targets from parent
containers and let backgrounds plus spacing separate the surfaces.

**Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and
renderer-owned visual styling, not layout spacing. Do not use guessed spacing
tokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing
variables inside wireframe HTML; if a token is unavailable in the Plan renderer,
padding collapses and content hugs the border. Use explicit CSS lengths for
layout: `padding:16px`, `gap:12px`, `margin-top:18px`, `minmax(0,1fr)`.

**Lay out with inline `style` flex/grid.** You write the real layout —
`display:flex; flex-direction:column; gap:10px; padding:16px` and so on — and the
renderer never repositions anything. Compose the actual product: reproduce the
current screen, then show the modification. Real labels, real counts, real dates,
real button text grounded in the screen you read; not lorem or gray bars.

**Surface presets — match the real footprint, never default to desktop+mobile.**
Pick the `surface` that matches what the user will actually see:

- `browser`: a web page that needs a browser chrome frame around it.
- `desktop`: a full desktop app page or app shell.
- `mobile`: a phone screen, only when the work is genuinely mobile.
- `popover`: a small floating menu, dropdown, or inline popover.
- `panel`: a side panel, inspector, or sidebar widget.

A sidebar popover renders as a small surface, not a desktop page and a phone
frame. Do not emit `desktop` + `mobile` variants unless responsive behavior
actually changes the layout. For a component or widget, show one broader
app-context frame only when placement affects understanding, then the focused
component states.

**Model the actual component shell for small surfaces.** A rendered UI change
belongs in a wireframe; reserve `diagram` for architecture, dependency, state,
or data-flow relationships. Popovers, dropdown menus, command palettes, and
context menus use `surface: "popover"` unless the surrounding page placement is
the point of the change. Dialogs, sheets, inspectors, sidebars, and long
property panels use the matching `panel` / `desktop` surface as appropriate.
Show the real chrome: trigger or anchor when it matters, title/header row,
top-right actions, separators, fields, options, selected states, body content,
and footer actions that are visible in the workflow.

**Modify, don't redesign.** When the task changes an existing screen, reproduce
the current screen's real layout and footprint FIRST, then change only the delta
and call it out with a single annotation. Do not restack the page into a new
layout. For net-new surfaces, compose from the real app shell. Inspect the
actual app components before drawing an existing product: sidebar density,
toolbar actions, overflow menus, property panels, and framework chrome should
match the product unless the plan intentionally changes them.

**Keep product screens pure.** A product wireframe shows the app state a user
would actually see. Do not embed file contracts, architecture arrows, repo pills,
mode explanations, or implementation callouts inside the screen just to explain
the plan. Put those in canvas annotations, a separate diagram, or the document
body. Secondary UI such as properties, history, sync, export, or agent controls
should appear where the real product would put them: an overflow popover, sheet,
panel, or separate framework sidebar state, not a generic permanent right
inspector unless that inspector is the actual design.

**Classify mockup scope before implementation.** Before turning a plan mockup
into source code, decide whether each artboard represents the whole page/app
shell, a route body inside an existing shell, or a component/sub-surface. If an
artboard includes navigation, sidebars, auth banners, or a signup/login form,
map those pieces to the real shared shell/auth components instead of nesting the
entire mockup inside the current page. When a mockup references the product's
standard signup/login page, find and reuse that existing implementation; do not
approximate it from the wireframe.

**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
popover, menu, dialog, toast), show the full screen once, then add a small
separate artboard whose `html` contains ONLY that sub-surface — do not re-draw
the whole page around it, and do not scale a duplicate up. Pick the matching
`surface` (e.g. `popover`) so the footprint is right; never widen a popover to
page width.

**Loading / skeleton states.** Set `data.skeleton: true` on the wireframe and
fill the `html` with neutral, textless placeholder geometry — boxes and bars
built as `<div>`s with `background:var(--wf-line)` and explicit heights/widths,
no labels or copy. The renderer drops borders, sketch, and color into the
skeleton register automatically. Never escape to a `custom-html` document block
to fake a loader.

**Editing an existing mockup.** In hosted mode, to change one element, text, or
color in an existing html mockup, do not regenerate the frame — call
`update-visual-plan` with
`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
replace }] }]`. Each `find` is a unique snippet of the current html (read it
first with `get-visual-plan`); set `all: true` on an edit to replace every
occurrence. The result is re-sanitized. In local-files privacy mode, do not call
hosted Plan tools; edit the local MDX source directly and rerun the local
check/serve or verify command for `<plan-dir>`.

**Choose the outer frame deliberately.** Wireframe and diagram data accept
`frame: "auto" | "show" | "hide"` in block data (`<Screen frame="hide">` in
MDX wireframes, `<Diagram frame="hide">` for MDX diagrams). Leave it unset or
`auto` when the host context should decide: Plan and recap surfaces default to a
drawn outer frame; docs surfaces default to no outer frame. Use `show` for
standalone product screens, before/after recap comparisons, screenshot-like
artifacts, and visuals that need containment from surrounding prose. Use `hide`
when a docs page, tab, column, card, canvas artboard, or the visual's own
internal chrome already supplies the boundary. Do not use `hide` to compensate
for cramped content; fix the layout instead.

**Inner padding and borders still matter.** Always wrap HTML wireframe content
in a root container with real inner padding before drawing cards, fields, pills,
labels, or controls. Use at least 14-16px of padding, `box-sizing: border-box`,
`height: 100%`, and `gap` between child rows on the root node itself so the
first row never sits flush against the screen edge. Do not rely on padding on a
nested page section as the first visible inset; the outermost element must
create the breathing room. Keep text away from borders: every container, field,
button, menu item, and annotation needs enough padding and line-height to read
cleanly in the rendered Plan view.

**For feature-cloud or abundance visuals, optimize the composition over line-by-line
reading.** Some marketing/product sections need to feel like a large surface area
of capability rather than a precise app workflow. In those cases, use one padded
root with a short headline and a dense, aesthetic cloud of short feature labels,
chips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,
and let many labels be glanceable rather than individually essential. Do not
force dozens of features into equal cards with long wrapped sentences; that
usually creates a messy unreadable mockup.

**Lay out children safely so they never collide.** Use HTML flex/grid with
`gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute
positioning, or fixed child widths that can collide when the renderer switches
between light/dark, sketch/clean, or different zoom levels.

**Do not wrap intentionally single-line labels.** For toolbars, tab rails,
breadcrumbs, chip/filter rows, branch and file names, file chips, and code
filenames — any deliberately single-line row — do not let long text wrap. Put
`white-space: nowrap` on the row (and `overflow: hidden; text-overflow: ellipsis`
on the individual labels that can grow), so the wireframe demonstrates the actual
layout behavior instead of producing ugly stacked or vertical text. Use
horizontally scrollable or clipped rails for overflow.

**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (`flex:1`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).

**Persistent chrome bars span the full frame width.** Top bars, app headers,
toolbars, and bottom tab/nav bars are full-width chrome, not centered content.
Lay each one out as a single flex row that fills the frame
(`style="display:flex;align-items:center;width:100%"`) and push trailing actions
to the right edge with a flex spacer (`<div style="flex:1"></div>`) between the
leading group and the trailing group — never center a bar inside a narrow,
centered block, and never let it collapse to the width of its contents. In a
Before/After pair the bar stays full-width in BOTH states even when one state has
fewer controls; the spacer absorbs the difference so the remaining controls hold
their edge alignment instead of sliding to the center.

**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and
any persistent bottom action row, make the frame itself a flex column at
`height:100%` (`style="display:flex;flex-direction:column;height:100%"`), give the
scrolling body `flex:1` so it absorbs the slack, and place the bar as the LAST
child of the frame (or set `margin-top:auto` on it). The bar then sits flush at
the bottom of the surface instead of floating directly under the content with an
empty band beneath it.

**Before / after must be comparable.** When showing a state change, preserve the
unchanged controls in both states so the reviewer can see exactly what moved or
appeared; do not show an added control as a generic box floating elsewhere in
the surface. Place the new/changed affordance where the implementation puts it —
for example, a new `Edit with AI` action in a popover header belongs in the
top-right header slot, aligned with the title, not in the body or footer. Use
the same frame size, scale, outer padding, border radius, and visual density on
both sides unless the change itself alters those properties, and let the frame
height fit the content rather than leaving a tall empty lower half.

**Name the states with the column header, never inside the frame.** For
document-body wireframes (recaps), put the two
states in a `columns` block and set each column's `label` to `Before` and
`After` — the renderer draws that label as an `h4` heading above each frame. Do
NOT bake a `Before`/`After` pill, title, or heading into the wireframe `html`: a
label placed inside reads as part of the product UI, lands in a random corner,
and clutters the comparison. The column header is the one and only place the
state name belongs. On a canvas, place the two state artboards as neighbors with
frame labels — never encode Before/After inside the html.

**Let the surface choose side-by-side vs. stacked.** For document-body
wireframes (recaps), the `columns` renderer lays
narrow surfaces (`mobile`, `popover`, `panel`) out side by side, and
automatically stacks wide surfaces (`desktop`, `browser`) vertically at full
document width so a large frame is never crushed into a half-width column and
cropped. Author both wireframes with the real `surface` and the matching
`Before`/`After` column labels; do not hand-stack the pair into separate
top-level wireframes or duplicate the state name as body content.

**Good example — a contacts list, surface `browser`.** A small, real screen
composed from the helper classes and tokens, layout in inline flex, no fonts or
hex colors:

```html
<div
  style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"
>
  <div style="display:flex;align-items:center;justify-content:space-between">
    <h1>Contacts</h1>
    <button class="primary">New contact</button>
  </div>
  <div style="display:flex;gap:6px">
    <span class="wf-pill accent">All 128</span>
    <span class="wf-pill">Favorites</span>
    <span class="wf-pill">Archived</span>
  </div>
  <div
    class="wf-card"
    style="display:flex;flex-direction:column;gap:0;padding:0"
  >
    <div
      style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)"
    >
      <div
        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
      ></div>
      <div style="flex:1">
        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>
      </div>
      <span class="wf-pill">Lead</span>
    </div>
    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
      <div
        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
      ></div>
      <div style="flex:1">
        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>
      </div>
      <span class="wf-pill">Customer</span>
    </div>
  </div>
</div>
```

<!-- SHARED-CORE:wireframe-quality END -->