communicating-in-mdx

name	communicating-in-mdx
description	Optional layer: write specs, plans, designs, and reports as MDX (Markdown + a component library) rendered locally via Vite — git-diffable, degrades to plain Markdown, no remote services.
when_to_use	Writing a spec/plan/design/recap/report the user will iterate on or decide from, where plain Markdown would lose layout, comparison, diagrams, or interaction. Use communicating-in-html instead for zero-dependency one-off files.

Communicating in MDX

An orthogonal enrichment layer — like a writing style, not a task. When this skill is loaded, prefer MDX over plain Markdown for documents the user will read, iterate on, or decide from: specs, plans, designs, recaps, reports. The .mdx is the artifact; a local runner renders it. Nothing leaves the machine.

It couples to nothing: it triggers on the activity, so whatever else you're doing (planning, designing, recapping) simply renders in MDX when that lands harder. Unloaded, nothing changes.

When MDX beats plain Markdown (and when it doesn't)

Reach for MDX when the content has any of: comparison (things side by side) · a plan with phased steps · architecture / flow / sequence that wants a diagram · code with margin notes or before/after · a UI idea that wants a wireframe · a recap with metrics · an intake form whose answers come back · or it would otherwise be a wall of flat Markdown.

Stay in plain Markdown / chat when: it's a short reply · code-only or terminal output · a disposable summary · or Node/the runner isn't available.

Full doctrine, and MDX-vs-HTML-vs-Markdown: references/when-mdx.md.

The core discipline

1. Prose-first, components-as-enhancement. Write real Markdown prose; drop in components only where they earn it. The raw .mdx must still read as Markdown when nobody renders it. A document that is mostly component tags is an anti-pattern.
2. No imports in documents. Components are registered globally — write the tag (<Callout>, <Mermaid>) directly, never import anything in a .mdx.
3. Author from the registry, not from memory. Before using components, read references/components.md (and references/wireframe.md for the canvas). It is the authoritative tag list and signatures.

The component vocabulary

Document components (full props + examples in references/components.md):

Tag	For
<Callout tone>	decisions, warnings, notes
<Steps> / <Timeline>	phased plans
<Diff>	before/after code
<DocDiff>	rendered diff of two MDX docs (split/inline/auto, word-level)
<DocInclude>	embed another doc's live content inline
<AnnotatedCode>	code with margin notes
<FileTree>	structure
<Mermaid>	architecture, flow, sequence
<Columns>	side-by-side comparison
<Tabs> / <Collapse>	progressive disclosure
<Checklist>	acceptance criteria, task lists
<MetricCard>	recap KPIs and results
<QuestionForm>	interviewing — answers POST back to the runner (token fallback)
<OptionGallery> / <Option>	offer visual mockups to pick from; pick streams back

Wireframe canvas for UI/design docs — <Canvas>, <Screen>, and low-fi primitives (<WBox> <WText> <WButton> <WInput> <WImage> <WRow> <WCol>): see references/wireframe.md.

Start from a template

Don't author from a blank file. assets/templates/ holds three worked starting points — copy one into the project's .work/, rename it, and replace the example content:

Template	Activity	Shows off
interview.mdx	intake / brainstorm	<QuestionForm> with answer streaming
change-spec.mdx	spec / plan	<Diagram> (hover tips + edge highlight), <Diff>, <Steps>, <Collapse>
pick-a-look.mdx	offer options	<OptionGallery> of wireframe mockups

assets/starter.mdx is a broader showcase of the whole component set. These are inspiration, not contracts — keep the structure that fits, drop the rest.

Using this from brainstorming, writing-plans, and other workflows

This skill is the medium; another skill is usually driving the activity. When a workflow asks for a spec, plan, design, recap, or intake — and the user wants it rich — render it as MDX instead of flat Markdown:

1. Copy the matching template from assets/templates/ into the project's .work/ (e.g. brainstorming intake → interview.mdx; a writing-plans plan or a design → change-spec.mdx; a layout choice → pick-a-look.mdx).
2. Write the real content into it, prose-first.
3. Serve it with the runner (below) and give the user the URL — that is the review surface. For brainstorming/option questions, the form or gallery streams answers back; you don't block on copy-paste.

The workflow's own discipline still applies (brainstorming asks one question at a time; writing-plans keeps tasks bite-sized) — MDX only changes how the artifact is rendered, not how the workflow is run.

Rendering — run the local runner

The runner is a Vite + React app bundled in this skill at runner/. Install once: cd runner && npm install.

Render a project's docs:

node <skill>/runner/bin/mdx-runner.mjs --dir <project>/.work --open

Start it as a background process and start/stop/restart it autonomously — no tmux required (the agent's shell can launch a detached process directly; tmux is optional if the user wants a window to attach to). It serves every .mdx in --dir at http://localhost:5173 with a sidebar index and hot reload. Flags and troubleshooting: references/runner.md.

Delivery + getting answers back

• Write kebab-case.mdx into the project's .work/ (or docs/ if no .work/). That directory is what the runner serves.
• The artifact is the .mdx — it is what you share, commit, and reopen. The rendered page is transient. Never produce HTML as a deliverable.
• Always leave a 3-5 bullet TL;DR in chat too — the file is the artifact, the chat keeps the headline.
• <QuestionForm> answers POST back to the runner's own /__mdx/answers endpoint (same-origin localhost — nothing leaves the machine) and land in runner/.answers.jsonl. Watch that file (a backgrounded watcher that wakes you on a new line) to pick them up with no copy-paste. Offline fallback: a pasteable ANSWERS<<< … >>>ANSWERS token.

Coexistence with communicating-in-html

Both are enrichment layers; pick per context.

• MDX — rich documents you and the user iterate on; anything using the component vocabulary or a wireframe; Node and the runner are available.
• HTML — zero-dependency one-offs; a single file for someone who will not run a runner. HTML's one irreplaceable virtue is that it needs no toolchain.

Anti-patterns

• A .mdx that's 90% component tags — it stops reading as Markdown unrendered.
• importing anything inside a .mdx document.
• Producing an HTML file as the deliverable (the MDX is the deliverable).
• Reaching for MDX in a plain terminal with no Node — degrade to Markdown.
• Using components you didn't confirm against references/components.md.