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

package/docs/prompt-composer.md

@@ -0,0 +1,278 @@
+<!-- index: ./index.md -->
+# prompt-composer
+
+`data-ui="prompt-composer"` · Multi-line message input with send and tools.
+
+## Import
+
+```ts
+import {
+  providePromptComposerDefaults,
+  SlPromptComposer,
+  SlPromptComposerAction,
+  SlPromptComposerAttach,
+  SlPromptComposerFooter,
+  SlPromptComposerHeader,
+  SlPromptComposerInput,
+  SlPromptComposerSubmit,
+} from '@slotted/angular/prompt-composer';
+```
+
+Selector: `form[slPromptComposer]` · exportAs: `slPromptComposer`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<form slPromptComposer [status]="status()" (valueSubmit)="send($event.value)" (stop)="abort()">
+  <textarea
+    slPromptComposerInput
+    aria-label="Mensagem"
+    placeholder="Pergunte ao assistente"
+  ></textarea>
+  <div slPromptComposerFooter>
+    <button slPromptComposerAttach></button>
+    <button slPromptComposerSubmit></button>
+  </div>
+</form>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | form[slPromptComposer], the consumer’s own form | yes |
+| `header` | any element carrying slPromptComposerHeader | no |
+| `input` | textarea[slPromptComposerInput] | yes |
+| `footer` | any element carrying slPromptComposerFooter | no |
+| `action` | button[slPromptComposerAction] | no |
+| `attach` | button[slPromptComposerAttach] | no |
+| `submit` | button[slPromptComposerSubmit] | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | slPromptComposer | Present means the consumer owns the value. defaultValue is the uncontrolled half |
+| `defaultValue` | `string` | — | slPromptComposer | What an uncontrolled composer starts from |
+| `status` | `'ready' \| 'submitted' \| 'streaming' \| 'error'` | ready | slPromptComposer | Where the request stands. submitted is busy, streaming turns the send into a stop, error into a retry |
+| `submitOn` | `'enter' \| 'mod-enter'` | enter | slPromptComposer, providePromptComposerDefaults | Which key sends. Shift+Enter always breaks a line; Mod+Enter always sends |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slPromptComposer, providePromptComposerDefaults | The control step, read from the field first |
+| `variant` | `'raised' \| 'outline' \| 'subtle'` | raised | slPromptComposer, providePromptComposerDefaults | raised is the chat surface; outline and subtle sit inside a form |
+| `canSubmit` | `boolean` | the value is not blank | slPromptComposer | Whether the send is available; an application with attachments ready says true |
+| `accept / maxSize / maxFiles / multiple` | `string / number / number / boolean` | — / — / — / true | slPromptComposer | The selection rules upload applies, for the paperclip, a paste and a drop |
+| `disabled` | `boolean` | from the field, or false | slPromptComposer | 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 | slPromptComposer | The value stays focusable and copyable; the paperclip and the send are withdrawn |
+| `invalid` | `boolean` | from the field, or false | slPromptComposer | aria-invalid on the textarea and the danger edge on the frame |
+| `required` | `boolean` | from the field | slPromptComposer | aria-required on the textarea, never the native attribute, which would engage constraint validation |
+| `loading` | `derived` | false | slPromptComposer | data-loading on the frame while status is submitted or streaming; it is read from status, never set |
+| `rows` | `number` | 1 | slPromptComposerInput | The fewest lines the value shows |
+| `maxRows` | `number` | 8 | slPromptComposerInput | The most lines it grows to before it scrolls |
+| `showCount` | `boolean` | false | slPromptComposerInput | Publishes the length of the value to the field, which draws the count |
+| `messages` | `Partial<PromptComposerMessages>` | — | slPromptComposer | 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 |
+| `exportAs` | `slPromptComposer, slPromptComposerInput, slPromptComposerAction` | — | the directives | Reach the instance from a template; slPromptComposerInput.inputElement is the native textarea |
+| `button[slPromptComposerAction]` | `directive` | type="button" | a band | A button of the consumer’s; slMenuTriggerFor or slTooltipTrigger sit on the same element, and the part is written back after the first render |
+| `providePromptComposerDefaults` | `(defaults: Partial<PromptComposerDefaults>) => Provider` | — | an injector | The decisions an application takes once |
+| `ControlValueAccessor` | `formControl, ngModel` | — | slPromptComposerInput | The value belongs in a reactive or template-driven form as it stands |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(valueChange)` | `ChangeRequest<string>` | On slPromptComposerInput, before the value moves: reason "keyboard" for an edit, "submit" for the clearing after an accepted send. cancel() refuses the move. |
+| `(valueSubmit)` | `ChangeRequest<string>` | On slPromptComposer, before the message is sent from Enter, Mod+Enter or the send — reason "keyboard" or "pointer". cancel() keeps the value; otherwise it is cleared. |
+| `(stop)` | `PromptComposerStopEvent — { reason, source }` | The stop button, while status is "streaming". “Stopped” is announced. |
+| `(attach)` | `PromptComposerAttachEvent — { files, reason, rejected, source }` | Files from the paperclip ("pointer"), a paste ("paste") or a drop ("drop"), after accept, maxSize, maxFiles and multiple. |
+| `ControlValueAccessor` | `the form’s own value and touched state` | On slPromptComposerInput, whenever the value moves and the request was not cancelled — including the clearing after a send — and on blur for touched. |
+
+## 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 the consumer’s 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
+
+```html
+<form
+  slPromptComposer
+  [status]="chat.status()"
+  (valueSubmit)="chat.send($event.value)"
+  (stop)="chat.stop()"
+>
+  <textarea
+    slPromptComposerInput
+    aria-label="Mensagem"
+    placeholder="Pergunte ao assistente"
+  ></textarea>
+  <div slPromptComposerFooter>
+    <button slPromptComposerAttach></button>
+    <button slPromptComposerAction [slMenuTriggerFor]="models">{{ model() }}</button>
+    <button slPromptComposerSubmit></button>
+  </div>
+</form>
+<sl-menu #models>
+  <sl-menu-radio-group [(value)]="model">
+    <button slMenuRadioItem value="Claude Opus">Claude Opus</button>
+  </sl-menu-radio-group>
+</sl-menu>
+```
+
+### 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
+
+```html
+<form slPromptComposer variant="outline" submitOn="mod-enter" (valueSubmit)="post($event.value)">
+  <textarea slPromptComposerInput aria-label="Comentário" rows="3"></textarea>
+  <div slPromptComposerFooter>
+    <button slPromptComposerAction (click)="close()">Cancelar</button>
+    <button slPromptComposerSubmit>Comentar</button>
+  </div>
+</form>
+```
+
+### 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
+
+```html
+<form
+  slPromptComposer
+  accept="image/*,application/pdf"
+  [maxSize]="5000000"
+  [canSubmit]="files().length > 0 || undefined"
+  (attach)="add($event.files, $event.rejected)"
+>
+  <div slPromptComposerHeader>
+    <ul slAttachmentGroup layout="strip" size="sm" aria-label="Anexos">
+      @for (file of files(); track file.name) {
+        <li slAttachment [file]="file" removable (remove)="remove(file)">
+          <span slAttachmentPreview></span>
+          <div slAttachmentBody><span slAttachmentFilename></span></div>
+          <div slAttachmentActions><button slAttachmentRemove></button></div>
+        </li>
+      }
+    </ul>
+  </div>
+  <textarea slPromptComposerInput aria-label="Mensagem"></textarea>
+  <div slPromptComposerFooter>
+    <button slPromptComposerAttach></button>
+    <button slPromptComposerSubmit></button>
+  </div>
+</form>
+```
+
+### 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
+
+```html
+<form slPromptComposer status="ready"></form>
+<form slPromptComposer status="submitted"></form>
+<form slPromptComposer status="streaming" (stop)="abort()"></form>
+<form slPromptComposer status="error"></form>
+```
+
+### 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
+
+```html
+<form slPromptComposer size="sm"></form>
+<form slPromptComposer size="md" variant="outline"></form>
+<form slPromptComposer size="lg" variant="subtle"></form>
+```
+
+### 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
+
+```html
+<div slField [invalid]="true">
+  <label slFieldLabel>Mensagem</label>
+  <form slPromptComposer>
+    <textarea slPromptComposerInput></textarea>
+  </form>
+  <p slFieldError>A mensagem passa de 2 000 caracteres.</p>
+</div>
+<form slPromptComposer>
+  <textarea slPromptComposerInput readOnly defaultValue="Arquivado"></textarea>
+</form>
+```
+
+### 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
+
+```html
+<form slPromptComposer>
+  <textarea slPromptComposerInput aria-label="Mensagem" maxRows="6"></textarea>
+</form>
+```
+
+### Setting it once, and reaching past it
+
+providePromptComposerDefaults carries the variant and the send key, and the words come from the language in force; exportAs reaches the textarea, which already has select(); the value binds to a reactive form.
+
+Excerpt — not a complete module
+
+```html
+<form slPromptComposer>
+  <textarea
+    slPromptComposerInput
+    #mensagem="slPromptComposerInput"
+    [formControl]="texto"
+  ></textarea>
+  <div slPromptComposerFooter>
+    <button slPromptComposerAction (click)="mensagem.inputElement.select()">Selecionar</button>
+    <button slPromptComposerSubmit></button>
+  </div>
+</form>
+```
+
+### 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
+
+```html
+<form slPromptComposer submitOn="enter"></form>
+<form slPromptComposer submitOn="mod-enter"></form>
+```

package/docs/prose.json

@@ -0,0 +1,357 @@
+{
+  "family": "prose",
+  "ui": "prose",
+  "binding": "angular",
+  "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  provideProseDefaults,\n  SlProse,\n  SlProseAnchor,\n  SlProseExclude,\n  SlProseFootnotes,\n  SlProseLead,\n  SlProseScroll,\n} from '@slotted/angular/prose';",
+        "selector": "[slProse]",
+        "exportAs": "slProse"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element the page wrote — div, article, section",
+          "required": true,
+          "purpose": "The region. The selector is an attribute, so the page keeps its own element: a div claims nothing, and article or main is a claim the page makes. Carries data-ui=\"prose\", the two axes, and the container this family answers its own width with."
+        },
+        {
+          "part": "lead",
+          "element": "p, by slProseLead",
+          "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, by slProseAnchor",
+          "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, the word joiner before it 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, by slProseScroll",
+          "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. exportAs reaches refresh()."
+        },
+        {
+          "part": "exclude",
+          "element": "any element, by slProseExclude",
+          "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, by slProseFootnotes",
+          "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": "slProse",
+          "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": "slProse",
+          "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": "slProseScroll",
+          "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 input because a renderer’s component map cannot supply one per table"
+        },
+        {
+          "name": "labelledBy",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slProseScroll",
+          "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"
+        }
+      ],
+      "composition": [
+        {
+          "name": "the attribute selector",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Each part attaches to the element the template already has, so a page keeps its own tags and the family adds only its data attributes. Nothing is re-projected, and nothing needs NgTemplateOutlet"
+        },
+        {
+          "name": "exportAs",
+          "type": "slProse, slProseScroll",
+          "defaultValue": "—",
+          "appliesTo": "slProse, slProseScroll",
+          "description": "Reaches the instance from the template. On the scrolling block that is refresh() and isOverflowing(): content that arrived without Angular knowing — an image finishing, a renderer writing into the DOM — changes whether the block overflows after the observer measured"
+        },
+        {
+          "name": "provideProseDefaults",
+          "type": "{ size, flow }",
+          "defaultValue": "—",
+          "appliesTo": "a route or the application",
+          "description": "Sets both once for every region under it — Typeset’s presets, typed. An explicit input on one region still wins, and providing again on a route narrows the decision for part of an application"
+        },
+        {
+          "name": "role, aria-label",
+          "type": "static attribute",
+          "defaultValue": "—",
+          "appliesTo": "slProseScroll",
+          "description": "A name or a role the template wrote is read with HostAttributeToken before anything is bound over it, so a consumer who named the region itself keeps that name"
+        },
+        {
+          "name": "slContainer",
+          "type": "composition",
+          "defaultValue": "—",
+          "appliesTo": "around slProse",
+          "description": "The measure belongs to container and to it alone: size=\"measure\" is the maximum this family refuses to state. Tailwind bakes 65ch in and ships max-w-none to remove it"
+        },
+        {
+          "name": "slLink, slKbd, slCheckbox",
+          "type": "composition",
+          "defaultValue": "—",
+          "appliesTo": "inside slProse",
+          "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"
+        }
+      ],
+      "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 role the template wrote itself is kept.",
+        "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. The directive writes a word joiner before it so the last word of a title and its permalink wrap together.",
+        "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 family holds no mutable value, so it emits nothing and has no output 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. Angular’s own DomSanitizer and the renderer that produced the tree are where that 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": "html",
+      "source": "<article slProse size=\"lg\" flow=\"normal\" [innerHTML]=\"rendered\"></article>\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": "html",
+      "source": "<div slProse [innerHTML]=\"sanitized\"></div>\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": "html",
+      "source": "<div slProse size=\"md\">…</div>\n<div slProse size=\"lg\">…</div>\n<div slProse size=\"xl\">…</div>\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 input apart.",
+      "language": "html",
+      "source": "<div slProse flow=\"tight\">…</div>\n<div slProse flow=\"normal\">…</div>\n<div slProse flow=\"loose\">…</div>\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": "html",
+      "source": "<div slProse>\n  <h2>Deploying a service</h2>\n  <p slProseLead>Everything a team needs to move a service to production.</p>\n  <p>A deployment is three decisions…</p>\n</div>\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": "html",
+      "source": "<h2 id=\"deploying\">\n  Deploying a service<a slProseAnchor href=\"#deploying\" aria-label=\"Link to this section\">#</a>\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": "html",
+      "source": "<div slProseScroll labelledBy=\"environments\" #wide=\"slProseScroll\">\n  <table>\n    <caption id=\"environments\">\n      Environments and their gates\n    </caption>\n  </table>\n</div>\n<button type=\"button\" (click)=\"wide.refresh()\">Measure again</button>\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 directive.",
+      "language": "html",
+      "source": "<div slProse>\n  <p>Styled by the family.</p>\n  <div slProseExclude>\n    <div slCard>Untouched.</div>\n  </div>\n</div>\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": "html",
+      "source": "<div slProse flow=\"tight\">\n  @for (block of blocks(); track block.id) {\n    <p>{{ block.text }}</p>\n  }\n</div>\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": "html",
+      "source": "<div slProse>\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\">فقرة عربية داخل نفس المنطقة.</p>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "The families it sits with",
+      "note": "slContainer bounds the measure, and a real slLink inside the text wins on specificity — every content rule here is written to lose to a family placed inside it.",
+      "language": "html",
+      "source": "<div slContainer size=\"measure\">\n  <article slProse>\n    <p>Read <a slLink href=\"/guide\">the guide</a> first.</p>\n  </article>\n</div>\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": "html",
+      "source": "<div slProse>\n  <h2 id=\"gates\">Gates<a slProseAnchor href=\"#gates\" aria-label=\"Link to this section\">#</a></h2>\n  <div slProseScroll labelledBy=\"gates\">\n    <table></table>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}