MDX Component Map — real `@dmwd-io/design-system` components

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/docs-that-teach/component-map.md
Description	Not specified

Source Content

MDX Component Map — real @dmwd-io/design-system components

The prompt that inspired this standard invented components (<Terminal>, <BeforeAfter>, <DecisionTable>, <Diagram>, <Figure>, <CheckYourUnderstanding>). None of those exist. The design system already ships a real component for each need. This page maps the intent to the real export.

Before using any component, query the Storybook MCP — list-all-documentation then get-documentation with the component id — and copy the props from there. The shapes below were verified against the MCP on 2026-06-24, but props change; the MCP is the source of truth. Never invent a prop, tone, or variant.

How to look a component up

1. list-all-documentation            → find the entry and its id
2. get-documentation { id }          → real props + three example stories
3. get-documentation-for-story { id} → a specific variant if the examples miss your prop

Callout — notes, tips, warnings, security, decisions

Renders as an <aside> with a tone icon and border. Tones are semantic, not colors.

import { Callout } from "@dmwd-io/design-system";

<Callout tone="warning" title="Do not copy shared workflows into each repo">
  Copying the workflow makes the system harder to patch, audit, and improve.
</Callout>;

Prop	Type	Note
tone	"info" | "success" | "warning" | "danger"	Default "info". Maps the user’s “Note / Tip / Warning / Security” types.
title	ReactNode	Optional heading line.
children	ReactNode	Body — required.
role	"note" | "status" | "alert"	Use "alert" only for urgent must-announce content.
dismissible	boolean	Default false; pair with onDismiss.

There is no type prop — use tone. There is no security/performance tone — use warning/danger and say so in the title.

CodeBlock — static code and command+output

Static, syntax-highlighted, with a copy button and an optional filename header. Prints as readable text.

import { CodeBlock } from "@dmwd-io/design-system";

<CodeBlock
  code={`jobs:\n  call-shared-workflow:\n    uses: org/platform/.github/workflows/node-ci.yml@main\n    with:\n      node-version: 20`}
  language="yaml"
  filename=".github/workflows/ci.yml"
/>;

Prop	Type	Note
code	string	Required.
language	string	Default "tsx".
filename	string	Optional header label.
showLineNumbers	boolean	Default false.
maxHeight	string | number	Scrollable when set — beware print clipping.

For a command and its expected output, use a bash CodeBlock (it prints) — not a screenshot. InlineCode is the inline-prose sibling.

PodTerminal — live terminal sessions

Use only when a live, animated session genuinely teaches more than static text. It is interactive, so it needs a print fallback or an adjacent static CodeBlock showing the same command and output.

ComparisonTable — decision matrices and option comparisons

The real “DecisionTable”. Side-by-side options across shared dimensions, with one highlighted column.

import { ComparisonTable } from "@dmwd-io/design-system";

<ComparisonTable
  title="Workflow ownership"
  columns={[
    { id: "local", title: "Local config" },
    { id: "shared", title: "Shared workflow", highlighted: true },
    { id: "manual", title: "Manual process" },
  ]}
  rows={[
    { id: "consistency", label: "Consistent across repos", values: { local: false, shared: true, manual: false } },
    { id: "ownership", label: "Central ownership", values: { local: false, shared: true, manual: false } },
    { id: "judgment", label: "Allows expert judgment", values: { local: true, shared: false, manual: true } },
  ]}
/>;

Cell values accept true, false, or a string ("3%", "$8/user"). For a plain prose comparison, a Markdown table is fine — reach for ComparisonTable when the data is feature × option.

DiffDisplay — before / after

The real “BeforeAfter”. Change logs, version comparisons, audit diffs. Query the MCP for its current props before use.

InteractiveMermaid — diagrams

The real “Diagram”. Use the technical-writing skill’s diagram rules and linter to author and lint the chart, then pass it as a string. Mermaid renders in grayscale, so it is print-safe.

import { InteractiveMermaid } from "@dmwd-io/design-system";

export const ciFlow = `flowchart LR
  A[Open PR] --> B[CI runs]
  B --> C{Pass?}
  C -- Yes --> D[Review and merge]
  C -- No --> E[Fix issues]`;

<InteractiveMermaid chart={ciFlow} fileName="ci-flow.mmd" height="420px" />;

Prop	Type	Note
chart	string	Required Mermaid source — export const it at the top of the MDX file.
fileName	string	Default "diagram.mmd"; used for the download action.
height	string	Default "560px".

Always follow the diagram with a one-sentence “what to notice”.

Media — figures and screenshots

The real “Figure”. Renders an <img> inside a <figure> with a <figcaption>. alt is required.

import { Media } from "@dmwd-io/design-system";

<Media
  src="/images/storybook-controls.png"
  alt="Storybook controls panel showing prop descriptions generated from TSDoc comments."
  caption="TSDoc comments surface in Storybook controls so consumers understand each prop."
/>;

Only add an image when it teaches faster than text. Every image needs descriptive alt (never “screenshot”), a caption, and a print-friendly size.

Charts — trends and proportions

Real components: LineChart (trend over time), BarChart (compare categories), AreaChart/ComposedChart (composition), ScatterPlot (correlation), plus Sparkline and MetricCard for inline numbers. Query the MCP for the exact data shape of the one you pick. Every chart needs a title, labeled axes, units, and a “what to notice” sentence — never make the reader interpret a chart alone.

On-page navigation

Need	Component
Auto table of contents from headings	DocsAutoToc
Sticky rail TOC	TableOfContentsRail
Sticky in-article jump nav	ArticleJumpNav
Article masthead (title, byline)	ArticleHeader
Prose typography wrapper for rich content	RichText

Tabs and Accordion — the print trap

Tabs and Accordion exist and are fine for optional or secondary content. They are a trap for teaching docs because print flattens them — a reader on paper loses whatever is in a non-active tab or a collapsed panel.

• Tabs — only for genuinely optional or platform-specific alternatives (npm vs pnpm). Never the primary explanation.
• Accordion — only for secondary detail (FAQ tail, deep-dive footnotes). Never required steps, warnings, or decisions.

QuoteHighlight — voice callouts

For an expert aside, testimonial, or memorable quote. Distinct from Callout (which is for status/warnings).

No quiz component — build the pattern

There is no Quiz or CheckYourUnderstanding in the catalog. For a check-your-understanding beat: put the question in a Callout role="note", the answer in an Accordion — and because print collapses the accordion, also state the answer in prose so paper readers get both.