# Markdown

> Model or editorial Markdown painted with atoms; app pieces through render slots.

- **Level**: molecule · **Status**: experimental (R15: may change or be removed; J-11) · **Role**: content
- **Import**: `import { Markdown } from "@rrios-forge/ui/molecules/markdown";`
- **Source**: `packages/ui/src/molecules/markdown`

**Purpose** — render the Markdown a model or an editor writes (paragraphs, headings, lists with one nested level, quotes, strong, emphasis, inline code, links) with Poesía atoms only. The source is text: HTML inside it renders literally and nothing goes through `dangerouslySetInnerHTML`.
**When to use** — an assistant's answer (`size="sm"`, `headings="flatten"`, `streaming` while it arrives), an article or help body (`size="md"`, `headingLevel` under the page's own heading).
**When NOT** — UI copy you author in code (use `Text`, `Heading` directly); tables, images or embedded HTML (out of the subset on purpose).
**Composes with** — app pieces through render slots: `renderLink` (client-side routing via `<Link asChild>`, a decorated citation), `renderMarker` (an app's `[[kind:target|label]]` chip), `renderText` (a glossary that decorates terms). `allowLink` narrows the link policy — a model should not choose where the reader goes.
**Accessibility** — semantic elements throughout (`p`, `h2`–`h6`, `ul`/`ol`, `blockquote`, `strong`, `em`, `code`, `a`); the component says no words of its own (an external link's hint comes from the labels provider, ADR-034).
**Related patterns** — Decision Matrix · ComponentChoice, Composition · AtomToMolecule, Information Architecture · BasicHierarchy.

## Use it for

- Markdown a model or an editor wrote (an answer, an article body) → `Markdown` (ADR-046): atoms only, never `dangerouslySetInnerHTML`; app pieces (routing, glossary, chips) through `renderLink` / `renderMarker` / `renderText`, link policy through `allowLink`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` | `md` | Ergonomic scale, in three families (control, text, container). |

## Stories

- [Playground](/?path=/story/components-molecules-markdown--playground) · frame: `/iframe.html?id=components-molecules-markdown--playground&viewMode=story`
- [Sizes](/?path=/story/components-molecules-markdown--sizes) · frame: `/iframe.html?id=components-molecules-markdown--sizes&viewMode=story`
- [Headings](/?path=/story/components-molecules-markdown--headings) · frame: `/iframe.html?id=components-molecules-markdown--headings&viewMode=story`
- [States](/?path=/story/components-molecules-markdown--states) · frame: `/iframe.html?id=components-molecules-markdown--states&viewMode=story`
- [In Context](/?path=/story/components-molecules-markdown--in-context) · frame: `/iframe.html?id=components-molecules-markdown--in-context&viewMode=story`

## Patterns consulted

- Patterns/Decision Matrix · ComponentChoice
- Patterns/Composition · AtomToMolecule
- Patterns/Information Architecture · BasicHierarchy
- Patterns/Density & Growth · ContentGrowth

## Decisions that name it

- ADR-003 — Storybook editorial convention and pattern↔component bidirectionality
- ADR-046 — Markdown is painted with atoms, and apps fill its slots

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).