@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/prompt-composer.md

@@ -0,0 +1,256 @@
+<!-- index: ./index.md -->
+# prompt-composer
+
+`data-ui="prompt-composer"` · Multi-line message input with send and tools.
+
+## Import
+
+```tsx
+import {
+  PromptComposer,
+  PromptComposerAction,
+  PromptComposerAttach,
+  PromptComposerFooter,
+  PromptComposerHeader,
+  PromptComposerInput,
+  PromptComposerSubmit,
+} from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<PromptComposer onValueSubmit={(value) => send(value)} status={status} onStop={abort}>
+  <PromptComposerInput aria-label="Mensagem" placeholder="Pergunte ao assistente" />
+  <PromptComposerFooter>
+    <PromptComposerAttach />
+    <PromptComposerSubmit />
+  </PromptComposerFooter>
+</PromptComposer>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | form, or the element render returns | yes |
+| `header` | div (PromptComposerHeader) | no |
+| `input` | textarea (PromptComposerInput) | yes |
+| `footer` | div (PromptComposerFooter) | no |
+| `action` | button (PromptComposerAction) | no |
+| `attach` | button (PromptComposerAttach), with a hidden file input beside it | no |
+| `submit` | button (PromptComposerSubmit) | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | PromptComposer | Present means the consumer owns the value. defaultValue is the uncontrolled half |
+| `defaultValue` | `string` | — | PromptComposer | What an uncontrolled composer starts from |
+| `status` | `'ready' \| 'submitted' \| 'streaming' \| 'error'` | ready | PromptComposer | Where the request stands. submitted is busy, streaming turns the send into a stop, error into a retry |
+| `submitOn` | `'enter' \| 'mod-enter'` | enter | PromptComposer, PromptComposerDefaultsProvider | Which key sends. Shift+Enter always breaks a line; Mod+Enter always sends |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | PromptComposer, PromptComposerDefaultsProvider | The control step, read from the field first |
+| `variant` | `'raised' \| 'outline' \| 'subtle'` | raised | PromptComposer, PromptComposerDefaultsProvider | raised is the chat surface; outline and subtle sit inside a form |
+| `canSubmit` | `boolean` | the value is not blank | PromptComposer | Whether the send is available; an application with attachments ready says true |
+| `accept / maxSize / maxFiles / multiple` | `string / number / number / boolean` | — / — / — / true | PromptComposer | The selection rules upload applies, for the paperclip, a paste and a drop |
+| `disabled` | `boolean` | from the field, or false | PromptComposer | Unstated rather than false, so the composer defers to its field. The native attribute on the textarea; the paperclip and the send leave the tab order with it |
+| `readOnly` | `boolean` | from the field, or false | PromptComposer | The value stays focusable and copyable; the paperclip and the send are withdrawn |
+| `invalid` | `boolean` | from the field, or false | PromptComposer | aria-invalid on the textarea and the danger edge on the frame |
+| `required` | `boolean` | from the field | PromptComposer | aria-required on the textarea, never the native attribute, which would engage constraint validation |
+| `loading` | `derived` | false | PromptComposer | data-loading on the frame while status is submitted or streaming; it is read from status, never set |
+| `rows` | `number` | 1 | PromptComposerInput | The fewest lines the value shows |
+| `maxRows` | `number` | 8 | PromptComposerInput | The most lines it grows to before it scrolls |
+| `showCount` | `boolean` | false | PromptComposerInput | Publishes the length of the value to the field, which draws the count |
+| `messages` | `Partial<PromptComposerMessages>` | — | PromptComposer | Words laid over the language in force, key by key: what the send says in each status, what is announced, and the paperclip’s name |
+| `render` | `(props) => ReactNode` | — | PromptComposer, PromptComposerHeader, PromptComposerFooter, PromptComposerAction | Substitutes the element and hands it every attribute and handler |
+| `ref` | `Ref<HTMLTextAreaElement>` | — | PromptComposerInput | Reaches the textarea; focus(), select() and setSelectionRange() are the element’s own |
+| `PromptComposerAction` | `ComponentPropsWithRef<"button">` | type="button" | header, footer | A button of the consumer’s; MenuTrigger, PopoverTrigger and TooltipTrigger hand it their wiring through their render |
+| `PromptComposerDefaultsProvider` | `{ size, variant, submitOn }` | — | a subtree | The decisions an application takes once |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: string, request: ChangeRequest<string>)` | Before the value moves: reason "keyboard" for an edit, "submit" for the clearing after an accepted send. cancel() refuses the move. |
+| `onValueSubmit` | `(value: string, request: ChangeRequest<string>)` | Before the message is sent, from Enter, Mod+Enter or the send button — reason "keyboard" or "pointer". cancel() keeps the value where it is; otherwise an uncontrolled composer clears it. |
+| `onStop` | `({ reason, source })` | The stop button, while status is "streaming". “Stopped” is announced. |
+| `onAttach` | `(files: File[], { reason, rejected, source })` | Files from the paperclip ("pointer"), a paste ("paste") or a drop ("drop"), after accept, maxSize, maxFiles and multiple. rejected lists what the rules refused, with the reason. |
+| `onSubmit, onKeyDown, onPaste, onDrop` | `the elements’ own events` | Whenever the elements fire them. The consumer’s handler runs first; preventing the default of a keydown stops the send. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `raised`, `outline`, `subtle` | `raised` |
+| `submitOn` | `enter`, `mod-enter` | `enter` |
+| `status` | `ready`, `submitted`, `streaming`, `error` | `ready` |
+
+## Rules
+
+- There is no APG pattern for a composer; the textarea supplies the textbox role, the field supplies the name, and the root is a form, so Enter in the value and the send button are the platform’s submission.
+- The send is named by the label for its status — Send, Sending, Stop, Retry — and the change of name is what a screen reader hears when the request moves; “Sending” and “Stopped” are announced once through the shared live announcer.
+- While the request is submitted the send is aria-disabled rather than disabled, so focus is not thrown out of it; Enter in the value does nothing until the status returns.
+- Enter never sends while an input method is composing (isComposing, keyCode 229): in Japanese and Chinese Enter confirms the composition.
+- The attachments are the application’s list and are drawn with attachment, which owns their names, their removal and the focus after a removal. Refused files are reported in onAttach so the application can say why.
+- The bands are not an APG toolbar: each button keeps its own tab stop, because there are few of them and they do different things.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-medium`, `--slotted-line-height-md`, `--slotted-prompt-composer-action-active-background`, `--slotted-prompt-composer-action-color`, `--slotted-prompt-composer-action-hover-background`, `--slotted-prompt-composer-action-label-color`, `--slotted-prompt-composer-background`, `--slotted-prompt-composer-border-color`, `--slotted-prompt-composer-caret-color`, `--slotted-prompt-composer-color`, `--slotted-prompt-composer-disabled-background`, `--slotted-prompt-composer-disabled-border-color`, `--slotted-prompt-composer-disabled-color`, `--slotted-prompt-composer-drop-background`, `--slotted-prompt-composer-drop-border-color`, `--slotted-prompt-composer-hover-border-color`, `--slotted-prompt-composer-invalid-border-color`, `--slotted-prompt-composer-invalid-edge-width`, `--slotted-prompt-composer-invalid-focus-ring-color`, `--slotted-prompt-composer-line-height`, `--slotted-prompt-composer-max-rows`, `--slotted-prompt-composer-placeholder-color`, `--slotted-prompt-composer-radius`, `--slotted-prompt-composer-raised-focus-shadow`, `--slotted-prompt-composer-raised-shadow`, `--slotted-prompt-composer-readonly-background`, `--slotted-prompt-composer-rows`, `--slotted-prompt-composer-selection-background`, `--slotted-prompt-composer-shadow`, `--slotted-prompt-composer-submit-active-background`, `--slotted-prompt-composer-submit-background`, `--slotted-prompt-composer-submit-color`, `--slotted-prompt-composer-submit-disabled-background`, `--slotted-prompt-composer-submit-hover-background`, `--slotted-prompt-composer-subtle-background`, `--slotted-prompt-composer-subtle-border-color`, `--slotted-radius-full`, `--slotted-radius-lg`, `--slotted-radius-xs`, `--slotted-shadow-lg`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-solid-active`, `--slotted-tone-accent-solid-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### An assistant that answers while you wait
+
+Send a question: the status goes to submitted, then streaming, and back to ready when the answer ends — the send turns into a ring, then a stop inside the ring. Press stop and the answer is cut short. The model is a menu on an action.
+
+Excerpt — not a complete module
+
+```tsx
+const { status, sendMessage, stop } = useChat();
+
+<PromptComposer status={status} onValueSubmit={(text) => sendMessage({ text })} onStop={stop}>
+  <PromptComposerInput aria-label="Mensagem" placeholder="Pergunte ao assistente" />
+  <PromptComposerFooter>
+    <PromptComposerAttach />
+    <Menu>
+      <MenuTrigger
+        render={(props) => <PromptComposerAction {...props}>{model}</PromptComposerAction>}
+      />
+      <MenuContent>{/* MenuRadioGroup of models */}</MenuContent>
+    </Menu>
+    <PromptComposerSubmit />
+  </PromptComposerFooter>
+</PromptComposer>;
+```
+
+### A comment box in a form
+
+The outline variant keeps a one-line control’s geometry beside the other fields. The send is named by its word, Comentar; Cancelar is an action. Enter breaks a line here, because a comment has paragraphs: Mod+Enter sends.
+
+Excerpt — not a complete module
+
+```tsx
+<PromptComposer variant="outline" submitOn="mod-enter" onValueSubmit={postComment}>
+  <PromptComposerInput aria-label="Comentário" rows={3} />
+  <PromptComposerFooter>
+    <PromptComposerAction onClick={close}>Cancelar</PromptComposerAction>
+    <PromptComposerSubmit>Comentar</PromptComposerSubmit>
+  </PromptComposerFooter>
+</PromptComposer>;
+```
+
+### Attaching by the paperclip, a paste and a drop
+
+Choose files, paste a screenshot into the value, or drag files over the frame — it washes in the accent and draws a dashed edge before you let go. Images and PDFs up to 5 MB are accepted; anything else is listed as refused. The attachments are the application’s list, drawn with attachment.
+
+Excerpt — not a complete module
+
+```tsx
+<PromptComposer
+  accept="image/*,application/pdf"
+  maxSize={5_000_000}
+  canSubmit={files.length > 0 || undefined}
+  onAttach={(added, { rejected }) => {
+    setFiles((list) => [...list, ...added]);
+    setRefused(rejected);
+  }}
+>
+  <PromptComposerHeader>
+    <AttachmentGroup layout="strip" size="sm" aria-label="Anexos">
+      {files.map((file) => (
+        <Attachment key={file.name} file={file} onRemove={() => remove(file)} />
+      ))}
+    </AttachmentGroup>
+  </PromptComposerHeader>
+  <PromptComposerInput aria-label="Mensagem" />
+  <PromptComposerFooter>
+    <PromptComposerAttach />
+    <PromptComposerSubmit />
+  </PromptComposerFooter>
+</PromptComposer>;
+```
+
+### The four statuses of the request
+
+ready sends; submitted is busy and refuses Enter; streaming stops; error offers a retry. The status is the application’s, because only the application knows whether an answer is on its way.
+
+Excerpt — not a complete module
+
+```tsx
+<PromptComposer status="ready" />;
+<PromptComposer status="submitted" />;
+<PromptComposer status="streaming" onStop={abort} />;
+<PromptComposer status="error" />;
+```
+
+### The step the composer sits at
+
+Three steps of the control scale, and three variants: raised lifts a chat surface off the page, outline and subtle sit inside a form. Switch the toolbar to dense and each step shrinks whole.
+
+Excerpt — not a complete module
+
+```tsx
+<PromptComposer size="sm" />;
+<PromptComposer size="md" variant="outline" />;
+<PromptComposer size="lg" variant="subtle" />;
+```
+
+### Invalid, read-only and disabled
+
+Invalid takes the danger edge and the field’s message says why; read-only keeps the value legible and copyable and withdraws the send; disabled mutes everything to the measured colour and takes the composer out of the tab order.
+
+Excerpt — not a complete module
+
+```tsx
+<Field invalid>
+  <FieldLabel>Mensagem</FieldLabel>
+  <PromptComposer />
+  <FieldError>A mensagem passa de 2 000 caracteres.</FieldError>
+</Field>;
+<PromptComposer readOnly defaultValue="Arquivado" />;
+<PromptComposer disabled />;
+```
+
+### Long, translated and right-to-left
+
+A long message grows to maxRows and then scrolls, with the band still under the thumb. Each paragraph takes its own direction, so an Arabic line and a Portuguese line sit in one value without either ending at the wrong margin.
+
+Excerpt — not a complete module
+
+```tsx
+<PromptComposer>
+  <PromptComposerInput aria-label="Mensagem" maxRows={6} />
+</PromptComposer>;
+```
+
+### Setting it once, and reaching past it
+
+The provider carries the variant and the send key, and the words come from the language in force; ref reaches the textarea; render substitutes the root, keeping every attribute and handler.
+
+Excerpt — not a complete module
+
+```tsx
+<PromptComposerDefaultsProvider submitOn="mod-enter">
+  <App />
+</PromptComposerDefaultsProvider>;
+
+const ref = useRef<HTMLTextAreaElement>(null);
+<PromptComposerInput ref={ref} />;
+
+<PromptComposer render={(props) => <form {...props} action="/mensagens" />} />;
+```
+
+### What the keyboard does
+
+Enter sends and Shift+Enter breaks a line; with submitOn="mod-enter" Enter breaks a line and Mod+Enter sends. Nothing is sent while an input method is composing, because there Enter confirms the composition. Escape is not bound.
+
+Excerpt — not a complete module
+
+```tsx
+<PromptComposer submitOn="enter" />;
+<PromptComposer submitOn="mod-enter" />;
+```

package/dist/docs/prose.json

@@ -0,0 +1,363 @@
+{
+  "family": "prose",
+  "ui": "prose",
+  "binding": "react",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Styles long-form HTML text."
+  },
+  "axes": {
+    "size": [
+      "md",
+      "lg",
+      "xl"
+    ],
+    "flow": [
+      "tight",
+      "normal",
+      "loose"
+    ]
+  },
+  "members": {
+    "prose": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "lg",
+        "flow": "normal"
+      },
+      "capabilities": [
+        "appearance",
+        "arrangement",
+        "size",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible"
+      ],
+      "parts": [
+        "root",
+        "lead",
+        "anchor",
+        "scroll",
+        "exclude",
+        "footnotes"
+      ]
+    }
+  },
+  "docs": {
+    "prose": {
+      "imports": {
+        "source": "import {\n  Prose,\n  ProseAnchor,\n  ProseDefaultsProvider,\n  ProseExclude,\n  ProseFootnotes,\n  ProseLead,\n  ProseScroll,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The region. Carries data-ui=\"prose\", the two axes, and the container this family answers its own width with. A div claims nothing; article, section or main is a claim the page makes through render."
+        },
+        {
+          "part": "lead",
+          "element": "p, or the element render returns",
+          "required": false,
+          "purpose": "The opening paragraph, one step up and in the muted role, with a wider gap after it than two ordinary paragraphs get. Tailwind’s equivalent is a class written into the Markdown; here it is contract, so a renderer’s component map can produce it."
+        },
+        {
+          "part": "anchor",
+          "element": "a",
+          "required": false,
+          "purpose": "A heading’s permalink. The destination is the consumer’s — rehype-autolink-headings writes it — and the family owns the placement, the 24-pixel target and the rule that it appears on hover and on focus. Hidden with opacity, never display, so a keyboard reaches it."
+        },
+        {
+          "part": "scroll",
+          "element": "div, or the element render returns",
+          "required": false,
+          "purpose": "A wide block — a table, a fence — that scrolls sideways instead of pushing the page over. It takes role=\"region\", tabindex=\"0\" and a name only while it actually overflows, measured through @slotted/core/overflow."
+        },
+        {
+          "part": "exclude",
+          "element": "div, or the element render returns",
+          "required": false,
+          "purpose": "A subtree the family does not style. Every content rule carries a guard against it, and the four properties inheritance still carried in — family, size, leading and wrapping — are returned to control type."
+        },
+        {
+          "part": "footnotes",
+          "element": "section, or the element render returns",
+          "required": false,
+          "purpose": "What GitHub Flavored Markdown emits at the end of a document: a rule, a step down in size and the muted role."
+        }
+      ],
+      "api": [
+        {
+          "name": "size",
+          "type": "'md' | 'lg' | 'xl'",
+          "defaultValue": "lg",
+          "appliesTo": "Prose",
+          "description": "The type-scale step the body text takes. Named for the scale’s own steps, so the offset from control type is visible: lg is one rem, and md is the size a button label is set in"
+        },
+        {
+          "name": "flow",
+          "type": "'tight' | 'normal' | 'loose'",
+          "defaultValue": "normal",
+          "appliesTo": "Prose",
+          "description": "The space between blocks, from which every other distance derives — the gap above a heading, between list rows, and around a rule. tight is a chat message, loose an article"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<ProseMessages>",
+          "defaultValue": "—",
+          "appliesTo": "ProseScroll",
+          "description": "Words laid over the language in force: the last resort name of a scrolling block (scroll), used when neither labelledBy nor aria-label names one. It comes from the catalog rather than a required prop because a renderer’s component map cannot supply one per table"
+        },
+        {
+          "name": "labelledBy",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "ProseScroll",
+          "description": "Names it from an element already on the page — the block’s own caption is the good answer, and the one Adrian Roselli’s pattern uses"
+        },
+        {
+          "name": "handleRef",
+          "type": "Ref<ProseScrollHandle>",
+          "defaultValue": "—",
+          "appliesTo": "ProseScroll",
+          "description": "Reaches refresh() and overflowing(). Content that arrived without React knowing — a renderer writing into the DOM, an image finishing — changes whether the block overflows after the observer measured"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Substitutes the rendered element of Prose, ProseLead, ProseAnchor, ProseScroll, ProseExclude or ProseFootnotes, and hands it every data attribute. A region rendered as an article is how a page makes the claim a div does not"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Reaches the native element. On ProseScroll the family answers the same callback that starts its observer, so a consumer keeps its element and the family keeps its measurement"
+        },
+        {
+          "name": "ProseDefaultsProvider",
+          "type": "{ size, flow }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets both once for every region under it — Typeset’s presets, typed. An explicit prop on one region still wins, and nesting a provider narrows the decision for part of a page"
+        },
+        {
+          "name": "Container",
+          "type": "composition",
+          "defaultValue": "—",
+          "appliesTo": "around Prose",
+          "description": "The measure belongs to container and to it alone: <Container size=\"measure\"> is the maximum this family refuses to state. Tailwind bakes 65ch in and ships max-w-none to remove it"
+        },
+        {
+          "name": "Link, Kbd, Checkbox",
+          "type": "composition",
+          "defaultValue": "—",
+          "appliesTo": "inside Prose",
+          "description": "Every content rule weighs 0-1-0, so a family placed inside the region wins on specificity and is left exactly as it is. A bare a, hr or kbd from the renderer reads the same theme tokens the family would"
+        },
+        {
+          "name": "code-block, table",
+          "type": "deferred",
+          "defaultValue": "—",
+          "appliesTo": "inside Prose",
+          "description": "Prose paints a fence and a table’s rhythm and nothing more. Highlighting, a copy control and line numbers belong to code-block; sorting, sticky headers and row selection to table"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "There is no APG pattern for this family: the Authoring Practices publish patterns for widgets a reader operates, and a region of rendered text is not one. The governing sources are the platform’s own semantics for the elements a renderer emits, SC 1.4.8 and SC 1.4.12 for how that text may be spaced, and the axe rule scrollable-region-focusable for the one block a reader has to move.",
+        "A wide block takes role=\"region\", tabindex=\"0\" and a name only while it actually overflows. The axe rule makes an unreachable scroller a level A failure, and anything that takes focus then needs a name and a role or it fails SC 4.1.2 — so both halves are written together, and neither is written on a block that fits. A tab stop on a table that needs no scrolling is a tab stop that does nothing.",
+        "The heading anchor is hidden with opacity, never with display: none or visibility: hidden. It stays in the tab sequence and in the accessible tree, appears on hover and on focus-visible, and holds a 24-pixel target — WCAG 2.2 SC 2.5.8 — so revealing it moves nothing on the line.",
+        "The family sets no fixed block size and clips no text box, so a reader raising line height to 1.5, paragraph spacing to 2 and tracking to 0.12 of the font size loses nothing — SC 1.4.12. Leading is stated once, at 1.5, rather than taken per step: the scale pairs 1.45 with its two largest steps because a control label is one line, and a paragraph is not.",
+        "Every rule is written in logical properties, so a right-to-left document is the same component mirrored rather than a second stylesheet. A fence is the exception and is forced left to right: the order of the characters is what the code means.",
+        "The native ::marker is kept. list-item draws its own because its row is a grid and CSS has no display that is both; an editorial li is not, and removing the marker costs the list semantics Safari drops with it.",
+        "The family holds no mutable value, so it emits nothing and has no event table. Which words appear here is the renderer’s decision, and so is whether they are announced: a region that announced every appended token would read a whole answer twice.",
+        "It does not sanitise. The renderer that produced the tree is where a sanitiser belongs, and a component that both styled and sanitised would hide which of the two failed."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-border-subtle",
+    "--slotted-border-width-thick",
+    "--slotted-border-width-thin",
+    "--slotted-divider-color",
+    "--slotted-divider-thickness",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-heading",
+    "--slotted-font-family-mono",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-lg",
+    "--slotted-font-size-md",
+    "--slotted-font-size-xl",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-semibold",
+    "--slotted-kbd-border-width",
+    "--slotted-kbd-font-family",
+    "--slotted-kbd-font-weight",
+    "--slotted-kbd-radius",
+    "--slotted-line-height-2xl",
+    "--slotted-line-height-3xl",
+    "--slotted-line-height-lg",
+    "--slotted-line-height-md",
+    "--slotted-link-color",
+    "--slotted-link-color-hover",
+    "--slotted-link-focus-ring-offset",
+    "--slotted-link-underline-color",
+    "--slotted-link-underline-offset",
+    "--slotted-link-underline-thickness",
+    "--slotted-prose-anchor-gap",
+    "--slotted-prose-caption-size",
+    "--slotted-prose-code-inset",
+    "--slotted-prose-code-size",
+    "--slotted-prose-flow-loose",
+    "--slotted-prose-flow-normal",
+    "--slotted-prose-flow-tight",
+    "--slotted-prose-focus-ring-offset",
+    "--slotted-prose-font-family",
+    "--slotted-prose-footnotes-size",
+    "--slotted-prose-h1-size",
+    "--slotted-prose-h1-size-narrow",
+    "--slotted-prose-h2-size",
+    "--slotted-prose-h2-size-narrow",
+    "--slotted-prose-h3-size",
+    "--slotted-prose-h4-size",
+    "--slotted-prose-h5-size",
+    "--slotted-prose-h6-size",
+    "--slotted-prose-h6-tracking",
+    "--slotted-prose-lead-line-height",
+    "--slotted-prose-lead-size",
+    "--slotted-prose-line-height",
+    "--slotted-prose-list-inset",
+    "--slotted-prose-list-inset-narrow",
+    "--slotted-prose-mark-inset",
+    "--slotted-prose-marker-gap",
+    "--slotted-prose-media-radius",
+    "--slotted-prose-quote-color",
+    "--slotted-prose-quote-inset",
+    "--slotted-prose-quote-thickness",
+    "--slotted-prose-small-size",
+    "--slotted-radius-md",
+    "--slotted-radius-sm",
+    "--slotted-radius-xs",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-surface-raised",
+    "--slotted-surface-sunken",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-warning-surface",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One region of rendered Markdown with both axes on it, driven by the controls below the canvas. Nothing inside carries an attribute the application wrote.",
+      "language": "tsx",
+      "source": "<Prose size=\"lg\" flow=\"normal\" dangerouslySetInnerHTML={{ __html: rendered }} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "elements",
+      "title": "Every element a renderer emits",
+      "note": "Headings, lists, a quotation, a fence, a table, media, a rule, a description list, a disclosure and the inline set — all bare tags, styled without a single attribute of their own.",
+      "language": "tsx",
+      "source": "<Prose>\n  <Markdown>{source}</Markdown>\n</Prose>;\n\n// Or, when the renderer hands back a string:\n<Prose dangerouslySetInnerHTML={{ __html: sanitized }} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "size",
+      "title": "Size",
+      "note": "The type-scale step the body takes. lg is one rem and is the default; md is the size a button label is set in, for a region inside dense product chrome.",
+      "language": "tsx",
+      "source": "<>\n  <Prose size=\"md\">{compact}</Prose>\n  <Prose size=\"lg\">{documentation}</Prose>\n  <Prose size=\"xl\">{article}</Prose>\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "flow",
+      "title": "Flow",
+      "note": "The one number that governs every gap on the page. Heading spacing, list spacing and the room around a rule all derive from it, so a chat message and an article are one prop apart.",
+      "language": "tsx",
+      "source": "<>\n  <Prose flow=\"tight\">{message}</Prose>\n  <Prose flow=\"normal\">{page}</Prose>\n  <Prose flow=\"loose\">{article}</Prose>\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "lead",
+      "title": "The lead paragraph",
+      "note": "The opening sentence set one step up, in the muted role, with a wider gap under it — so the opening reads as its own movement rather than as the first of several paragraphs.",
+      "language": "tsx",
+      "source": "<Prose>\n  <h2>Deploying a service</h2>\n  <ProseLead>Everything a team needs to move a service to production.</ProseLead>\n  <p>A deployment is three decisions…</p>\n</Prose>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anchor",
+      "title": "Heading anchors",
+      "note": "Hover a heading, then tab to its permalink: it appears for both, because a control that answers hover alone is a control a keyboard cannot find. It holds its box whether visible or not, so revealing it moves nothing.",
+      "language": "tsx",
+      "source": "<h2 id=\"deploying\">\n  Deploying a service\n  <ProseAnchor href=\"#deploying\" aria-label=\"Link to this section\">\n    #\n  </ProseAnchor>\n</h2>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "scroll",
+      "title": "A block wider than its column",
+      "note": "Tab into the table below: it takes a tab stop, a region role and a name only because it overflows. Widen the window until it fits and all three disappear, which is the point.",
+      "language": "tsx",
+      "source": "<ProseScroll labelledBy=\"environments\">\n  <table>\n    <caption id=\"environments\">Environments and their gates</caption>…\n  </table>\n</ProseScroll>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "exclude",
+      "title": "Opting a component out",
+      "note": "The card below sits inside the region and keeps its own type, rhythm and colour. Everything around it is still set by the family, and the boundary is one attribute.",
+      "language": "tsx",
+      "source": "<Prose>\n  <p>Styled by the family.</p>\n  <ProseExclude>\n    <Card>\n      <CardBody>Untouched.</CardBody>\n    </Card>\n  </ProseExclude>\n</Prose>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "streaming",
+      "title": "Content that is still arriving",
+      "note": "Press the button and blocks are appended one at a time, the way a language model answers. Nothing already on screen moves: no rule in this family selects forward, and every gap is on the block that arrives.",
+      "language": "tsx",
+      "source": "<Prose flow=\"tight\">\n  {blocks.map((block) => (\n    <p key={block.id}>{block.text}</p>\n  ))}\n</Prose>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A body that starts at h3, two headings with nothing between them, a pasted destination with no break in it, four levels of list, and a right-to-left paragraph in the middle of the page.",
+      "language": "tsx",
+      "source": "<Prose>\n  <h3>A body that does not start at the top level</h3>\n  <h4>Two headings with nothing between them</h4>\n  <p lang=\"ar\" dir=\"rtl\">\n    فقرة عربية داخل نفس المنطقة.\n  </p>\n</Prose>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "The families it sits with",
+      "note": "Container bounds the measure, Card frames the region and a Link inside the text wins on specificity — every content rule here is written to lose to a family placed inside it.",
+      "language": "tsx",
+      "source": "<Container size=\"measure\">\n  <Prose render={(props) => <article {...props} />}>\n    <p>\n      Read <Link href=\"/guide\">the guide</Link> first.\n    </p>\n  </Prose>\n</Container>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "Accessibility",
+      "note": "The two things in this family a reader operates: the permalink beside a heading, and the scrolling block. Tab through the region and both take focus in the order the document holds them.",
+      "language": "tsx",
+      "source": "<Prose>\n  <h2 id=\"gates\">\n    Gates\n    <ProseAnchor href=\"#gates\" aria-label=\"Link to this section\">\n      #\n    </ProseAnchor>\n  </h2>\n  <ProseScroll labelledBy=\"gates\">\n    <table>…</table>\n  </ProseScroll>\n</Prose>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}