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

package/dist/docs/skeleton.json

@@ -0,0 +1,356 @@
+{
+  "family": "skeleton",
+  "ui": "skeleton",
+  "binding": "react",
+  "catalog": {
+    "group": "Feedback",
+    "summary": "Placeholder shapes while content loads."
+  },
+  "axes": {
+    "shape": [
+      "text",
+      "block",
+      "circle",
+      "square"
+    ],
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg",
+      "xl"
+    ],
+    "animation": [
+      "shimmer",
+      "pulse",
+      "none"
+    ],
+    "live": [
+      "polite",
+      "off"
+    ]
+  },
+  "members": {
+    "skeleton": {
+      "nativeElement": "span",
+      "defaults": {
+        "shape": "text",
+        "size": "md",
+        "animation": "shimmer",
+        "loading": true,
+        "lines": 3,
+        "lastLineSize": "62%",
+        "live": "polite",
+        "delay": 0,
+        "minDuration": 0
+      },
+      "capabilities": [
+        "appearance",
+        "shape",
+        "size",
+        "loading",
+        "live"
+      ],
+      "states": [
+        "default",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "text",
+        "line",
+        "region",
+        "announcement"
+      ]
+    }
+  },
+  "docs": {
+    "skeleton": {
+      "imports": {
+        "source": "import { Skeleton, SkeletonText, SkeletonRegion, SkeletonDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "span",
+          "required": true,
+          "purpose": "One placeholder box, rendered by Skeleton. Empty it draws the geometry shape and size describe; with children it takes their geometry and covers them."
+        },
+        {
+          "part": "text",
+          "element": "div",
+          "required": true,
+          "purpose": "The rows of a paragraph, rendered by SkeletonText. A grid whose tracks are exactly one line box, so the rows occupy the lines the words will."
+        },
+        {
+          "part": "line",
+          "element": "span",
+          "required": true,
+          "purpose": "One row inside text, repeated lines times. The last of several is drawn short; a lone row is not."
+        },
+        {
+          "part": "region",
+          "element": "div",
+          "required": true,
+          "purpose": "The loading fact for a subtree, rendered by SkeletonRegion. Carries aria-busy, the timing, and the animation phase every placeholder inside it reads."
+        },
+        {
+          "part": "announcement",
+          "element": "span",
+          "required": true,
+          "purpose": "The one visually-hidden role=\"status\" per region. Holds the label while waiting and is emptied afterwards, so a load announces once."
+        }
+      ],
+      "api": [
+        {
+          "name": "shape",
+          "type": "'text' | 'block' | 'circle' | 'square'",
+          "defaultValue": "text",
+          "appliesTo": "Skeleton",
+          "description": "What the placeholder stands for: a line of type, a block of content, or an avatar"
+        },
+        {
+          "name": "size",
+          "type": "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
+          "defaultValue": "md",
+          "appliesTo": "Skeleton",
+          "description": "The avatar scale. Means nothing for text, which takes its height from the type, or for block"
+        },
+        {
+          "name": "inlineSize, blockSize",
+          "type": "number | string",
+          "defaultValue": "—",
+          "appliesTo": "Skeleton, SkeletonText",
+          "description": "The reserved geometry, in logical axes. A bare number is pixels. Ignored where content is covered and measured instead"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Skeleton, SkeletonText, SkeletonRegion",
+          "description": "Whether the content is still on its way. On a box, unset means the nearest region decides"
+        },
+        {
+          "name": "lines",
+          "type": "number",
+          "defaultValue": "3",
+          "appliesTo": "SkeletonText",
+          "description": "How many rows of the paragraph to reserve"
+        },
+        {
+          "name": "lastLineSize",
+          "type": "string",
+          "defaultValue": "62%",
+          "appliesTo": "SkeletonText",
+          "description": "How wide the last row is drawn, when there is more than one"
+        },
+        {
+          "name": "animation",
+          "type": "'shimmer' | 'pulse' | 'none'",
+          "defaultValue": "shimmer",
+          "appliesTo": "Skeleton, SkeletonText, SkeletonRegion",
+          "description": "How the wait moves. A region hands its value to everything inside it"
+        },
+        {
+          "name": "live",
+          "type": "'polite' | 'off'",
+          "defaultValue": "polite",
+          "appliesTo": "SkeletonRegion",
+          "description": "Whether the region announces the wait at all"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<SkeletonMessages>",
+          "defaultValue": "—",
+          "appliesTo": "SkeletonRegion",
+          "description": "Words laid over the language in force, key by key: what a screen reader hears once, while the region is waiting (label)"
+        },
+        {
+          "name": "loadedLabel",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SkeletonRegion",
+          "description": "What it hears when the content arrives. Silent unless set, so one load says one thing"
+        },
+        {
+          "name": "delay",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "SkeletonRegion",
+          "description": "Milliseconds the wait must last before anything is painted"
+        },
+        {
+          "name": "minDuration",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "SkeletonRegion",
+          "description": "Milliseconds a placeholder that did appear is held before it is withdrawn"
+        }
+      ],
+      "composition": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Skeleton",
+          "description": "Covered rather than replaced: the box takes the content’s own geometry, hides it, and reveals it untouched when loading ends"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Skeleton, SkeletonText, SkeletonRegion",
+          "description": "Substitutes the rendered element. Every data attribute and the geometry style are handed to it"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLSpanElement | HTMLDivElement>",
+          "defaultValue": "—",
+          "appliesTo": "all three",
+          "description": "Reaches the native element; each part’s props are that element’s, extended"
+        },
+        {
+          "name": "SkeletonDefaultsProvider",
+          "type": "SkeletonDefaults",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets animation, delay, minDuration, loadedLabel, lastLineSize and live once for everything below it; a prop on a region or a box still wins"
+        }
+      ],
+      "events": [
+        {
+          "name": "onReveal",
+          "payload": "void",
+          "when": "The placeholders are actually withdrawn — later than loading turning false whenever minDuration is still holding them. It is the moment an application moves focus on."
+        }
+      ],
+      "accessibility": [
+        "Every placeholder carries aria-hidden=\"true\" and inert while it is painted. Reading out the absence of something is noise, and focus must not fall into content that is not ready — a covered button is unreachable rather than reachable and useless.",
+        "aria-hidden=\"false\" written by hand is the escape hatch and survives, because React reads an undefined-valued prop as absent and the only way to remove a defaulted attribute is an explicit value.",
+        "The region carries aria-busy=\"true\" while it waits, which is the platform’s own answer: ARIA 1.2 asks an author to set it on the container before the first change and clear it when the last change is complete. There is no APG pattern for a skeleton — the index holds thirty patterns and none is this one.",
+        "One region is one announcement. A visually-hidden role=\"status\" holds the label while waiting and is emptied afterwards, and emptying a live region announces nothing, so twelve placeholders do not become twelve messages. loadedLabel opts into a second.",
+        "Under prefers-reduced-motion the loop stops rather than shortening: an infinite animation that hurries is still moving. animation=\"none\", set once through the provider, is the author-side mechanism WCAG 2.2 SC 2.2.2 asks for.",
+        "The placeholder is visible in all three colour schemes. The fill is the unavailable surface carried a little toward the text colour, and a hairline rim takes over in high contrast, where that surface is the page’s own white."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-avatar-size-lg",
+    "--slotted-avatar-size-md",
+    "--slotted-avatar-size-sm",
+    "--slotted-avatar-size-xl",
+    "--slotted-avatar-size-xs",
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-disabled-background",
+    "--slotted-duration-loop-slow",
+    "--slotted-radius-full",
+    "--slotted-radius-md",
+    "--slotted-skeleton-block-size",
+    "--slotted-skeleton-border-color",
+    "--slotted-skeleton-border-width",
+    "--slotted-skeleton-fill",
+    "--slotted-skeleton-highlight-color",
+    "--slotted-skeleton-inline-size",
+    "--slotted-skeleton-last-line-size",
+    "--slotted-skeleton-line-size",
+    "--slotted-skeleton-min-block-size",
+    "--slotted-skeleton-phase",
+    "--slotted-skeleton-radius",
+    "--slotted-skeleton-row-size",
+    "--slotted-skeleton-size",
+    "--slotted-skeleton-trough-color",
+    "--slotted-surface-sunken",
+    "--slotted-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "A member row, driven by the controls below the canvas. Turn loading off and nothing moves — the placeholders were the real content’s own boxes all along.",
+      "language": "tsx",
+      "source": "<Skeleton loading={pending} shape=\"circle\" size=\"md\">\n  <Avatar name=\"Ada Lovelace\" size=\"md\" />\n</Skeleton>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "shapes",
+      "title": "What the placeholder stands for",
+      "note": "Four relationships to the layout rather than four points on a scale: a line of type, a block of content, and the two boxes an avatar can be.",
+      "language": "tsx",
+      "source": "<Skeleton shape=\"text\" inlineSize=\"8rem\" />;\n<Skeleton shape=\"block\" blockSize=\"6rem\" />;\n<Skeleton shape=\"circle\" size=\"lg\" />;\n<Skeleton shape=\"square\" size=\"lg\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "text",
+      "title": "A paragraph that has not arrived",
+      "note": "The rows are exactly one line box each, so three rows are the three lines the words will take — at any type size, at any density, with no height typed anywhere.",
+      "language": "tsx",
+      "source": "<SkeletonText lines={3} />;\n\n// Ten rows of a list, and a shorter tail.\n<SkeletonText lastLineSize=\"40%\" lines={10} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The round placeholder and the avatar it replaces",
+      "note": "size reads the avatar scale, so a placeholder and the picture that lands in its place are the same box at every step and at every density.",
+      "language": "tsx",
+      "source": "<Skeleton shape=\"circle\" size=\"md\" />;\n\n// Once the person has loaded.\n<Avatar name=\"Ada Lovelace\" size=\"md\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "wrapping",
+      "title": "Covering content instead of describing it",
+      "note": "Give a placeholder children and it takes their box rather than one you typed, so the reserved space cannot disagree with what replaces it.",
+      "language": "tsx",
+      "source": "<Skeleton loading={pending}>\n  <Badge tone=\"success\">Paid in full</Badge>\n</Skeleton>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "region",
+      "title": "One wait, one announcement",
+      "note": "The region carries aria-busy and the single status message; every placeholder inside it is hidden, inert, and reads the region loading state instead of its own.",
+      "language": "tsx",
+      "source": "<SkeletonRegion messages={{ label: 'Loading members' }} loading={pending}>\n  {members.map((member) => (\n    <MemberRow key={member.id} member={member} />\n  ))}\n</SkeletonRegion>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "timing",
+      "title": "The flash, and the flash in reverse",
+      "note": "delay withholds the paint until the wait is worth reporting; minDuration holds a placeholder that did appear. Both are zero unless an application sets them.",
+      "language": "tsx",
+      "source": "<SkeletonDefaultsProvider delay={200} minDuration={400}>\n  <App />\n</SkeletonDefaultsProvider>;\n\n// onReveal fires when the placeholders actually go, not when loading does.\n<SkeletonRegion loading={pending} onReveal={() => table.focus()}>\n  <Rows />\n</SkeletonRegion>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "animation",
+      "title": "How the wait moves",
+      "note": "shimmer sends a band across the placeholder and is the default; pulse dims the fill and back for a quieter surface; none is still. Under reduced motion all three stop.",
+      "language": "tsx",
+      "source": "<SkeletonText animation=\"shimmer\" />;\n<SkeletonText animation=\"pulse\" />;\n<SkeletonText animation=\"none\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "A loading surface a product would ship",
+      "note": "An avatar, a name, a role and a status chip, each placeholder standing in the box its own family will occupy, all under one region that owns the wait.",
+      "language": "tsx",
+      "source": "<SkeletonRegion messages={{ label: 'Loading members' }} loading={pending}>\n  <Inline gap=\"5\">\n    <Skeleton shape=\"circle\" size=\"md\" />\n    <Stack gap=\"2\">\n      <Skeleton inlineSize=\"9rem\" shape=\"text\" />\n      <Skeleton inlineSize=\"5rem\" shape=\"text\" />\n    </Stack>\n  </Inline>\n</SkeletonRegion>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A narrow column, a right-to-left paragraph where the short row and the sweep both change ends, and a heading whose placeholder is a heading tall without being told what a heading is.",
+      "language": "tsx",
+      "source": "<Heading level={2}>\n  <Skeleton inlineSize=\"60%\" shape=\"text\" />\n</Heading>;\n\n<div dir=\"rtl\">\n  <SkeletonText lines={3} />\n</div>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears",
+      "note": "Every box is hidden and inert; the region says the label once and then falls silent. Tab through the loading half and focus skips it entirely.",
+      "language": "tsx",
+      "source": "<SkeletonRegion messages={{ label: 'Loading invoices' }} loadedLabel=\"Invoices loaded\">\n  <SkeletonText />\n</SkeletonRegion>;\n\n// A region the reader never waits on says nothing at all.\n<SkeletonRegion live=\"off\">\n  <Skeleton shape=\"circle\" />\n</SkeletonRegion>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/skeleton.md

@@ -0,0 +1,226 @@
+<!-- index: ./index.md -->
+# skeleton
+
+`data-ui="skeleton"` · Placeholder shapes while content loads.
+
+## Import
+
+```tsx
+import { Skeleton, SkeletonText, SkeletonRegion, SkeletonDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Skeleton loading={pending} shape="circle" size="md">
+  <Avatar name="Ada Lovelace" size="md" />
+</Skeleton>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | span | yes |
+| `text` | div | yes |
+| `line` | span | yes |
+| `region` | div | yes |
+| `announcement` | span | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `shape` | `'text' \| 'block' \| 'circle' \| 'square'` | text | Skeleton | What the placeholder stands for: a line of type, a block of content, or an avatar |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | md | Skeleton | The avatar scale. Means nothing for text, which takes its height from the type, or for block |
+| `inlineSize, blockSize` | `number \| string` | — | Skeleton, SkeletonText | The reserved geometry, in logical axes. A bare number is pixels. Ignored where content is covered and measured instead |
+| `loading` | `boolean` | true | Skeleton, SkeletonText, SkeletonRegion | Whether the content is still on its way. On a box, unset means the nearest region decides |
+| `lines` | `number` | 3 | SkeletonText | How many rows of the paragraph to reserve |
+| `lastLineSize` | `string` | 62% | SkeletonText | How wide the last row is drawn, when there is more than one |
+| `animation` | `'shimmer' \| 'pulse' \| 'none'` | shimmer | Skeleton, SkeletonText, SkeletonRegion | How the wait moves. A region hands its value to everything inside it |
+| `live` | `'polite' \| 'off'` | polite | SkeletonRegion | Whether the region announces the wait at all |
+| `messages` | `Partial<SkeletonMessages>` | — | SkeletonRegion | Words laid over the language in force, key by key: what a screen reader hears once, while the region is waiting (label) |
+| `loadedLabel` | `string` | — | SkeletonRegion | What it hears when the content arrives. Silent unless set, so one load says one thing |
+| `delay` | `number` | 0 | SkeletonRegion | Milliseconds the wait must last before anything is painted |
+| `minDuration` | `number` | 0 | SkeletonRegion | Milliseconds a placeholder that did appear is held before it is withdrawn |
+| `children` | `ReactNode` | — | Skeleton | Covered rather than replaced: the box takes the content’s own geometry, hides it, and reveals it untouched when loading ends |
+| `render` | `(props) => ReactNode` | — | Skeleton, SkeletonText, SkeletonRegion | Substitutes the rendered element. Every data attribute and the geometry style are handed to it |
+| `ref` | `Ref<HTMLSpanElement \| HTMLDivElement>` | — | all three | Reaches the native element; each part’s props are that element’s, extended |
+| `SkeletonDefaultsProvider` | `SkeletonDefaults` | — | Application | Sets animation, delay, minDuration, loadedLabel, lastLineSize and live once for everything below it; a prop on a region or a box still wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onReveal` | `void` | The placeholders are actually withdrawn — later than loading turning false whenever minDuration is still holding them. It is the moment an application moves focus on. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `shape` | `text`, `block`, `circle`, `square` | `text` |
+| `size` | `xs`, `sm`, `md`, `lg`, `xl` | `md` |
+| `animation` | `shimmer`, `pulse`, `none` | `shimmer` |
+| `live` | `polite`, `off` | `polite` |
+
+## Rules
+
+- Every placeholder carries aria-hidden="true" and inert while it is painted. Reading out the absence of something is noise, and focus must not fall into content that is not ready — a covered button is unreachable rather than reachable and useless.
+- aria-hidden="false" written by hand is the escape hatch and survives, because React reads an undefined-valued prop as absent and the only way to remove a defaulted attribute is an explicit value.
+- The region carries aria-busy="true" while it waits, which is the platform’s own answer: ARIA 1.2 asks an author to set it on the container before the first change and clear it when the last change is complete. There is no APG pattern for a skeleton — the index holds thirty patterns and none is this one.
+- One region is one announcement. A visually-hidden role="status" holds the label while waiting and is emptied afterwards, and emptying a live region announces nothing, so twelve placeholders do not become twelve messages. loadedLabel opts into a second.
+- Under prefers-reduced-motion the loop stops rather than shortening: an infinite animation that hurries is still moving. animation="none", set once through the provider, is the author-side mechanism WCAG 2.2 SC 2.2.2 asks for.
+- The placeholder is visible in all three colour schemes. The fill is the unavailable surface carried a little toward the text colour, and a hairline rim takes over in high contrast, where that surface is the page’s own white.
+
+## Tokens
+
+`--slotted-avatar-size-lg`, `--slotted-avatar-size-md`, `--slotted-avatar-size-sm`, `--slotted-avatar-size-xl`, `--slotted-avatar-size-xs`, `--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-disabled-background`, `--slotted-duration-loop-slow`, `--slotted-radius-full`, `--slotted-radius-md`, `--slotted-skeleton-block-size`, `--slotted-skeleton-border-color`, `--slotted-skeleton-border-width`, `--slotted-skeleton-fill`, `--slotted-skeleton-highlight-color`, `--slotted-skeleton-inline-size`, `--slotted-skeleton-last-line-size`, `--slotted-skeleton-line-size`, `--slotted-skeleton-min-block-size`, `--slotted-skeleton-phase`, `--slotted-skeleton-radius`, `--slotted-skeleton-row-size`, `--slotted-skeleton-size`, `--slotted-skeleton-trough-color`, `--slotted-surface-sunken`, `--slotted-text`
+
+## Examples
+
+### What the placeholder stands for
+
+Four relationships to the layout rather than four points on a scale: a line of type, a block of content, and the two boxes an avatar can be.
+
+Excerpt — not a complete module
+
+```tsx
+<Skeleton shape="text" inlineSize="8rem" />;
+<Skeleton shape="block" blockSize="6rem" />;
+<Skeleton shape="circle" size="lg" />;
+<Skeleton shape="square" size="lg" />;
+```
+
+### A paragraph that has not arrived
+
+The rows are exactly one line box each, so three rows are the three lines the words will take — at any type size, at any density, with no height typed anywhere.
+
+Excerpt — not a complete module
+
+```tsx
+<SkeletonText lines={3} />;
+
+// Ten rows of a list, and a shorter tail.
+<SkeletonText lastLineSize="40%" lines={10} />;
+```
+
+### The round placeholder and the avatar it replaces
+
+size reads the avatar scale, so a placeholder and the picture that lands in its place are the same box at every step and at every density.
+
+Excerpt — not a complete module
+
+```tsx
+<Skeleton shape="circle" size="md" />;
+
+// Once the person has loaded.
+<Avatar name="Ada Lovelace" size="md" />;
+```
+
+### Covering content instead of describing it
+
+Give a placeholder children and it takes their box rather than one you typed, so the reserved space cannot disagree with what replaces it.
+
+Excerpt — not a complete module
+
+```tsx
+<Skeleton loading={pending}>
+  <Badge tone="success">Paid in full</Badge>
+</Skeleton>;
+```
+
+### One wait, one announcement
+
+The region carries aria-busy and the single status message; every placeholder inside it is hidden, inert, and reads the region loading state instead of its own.
+
+Excerpt — not a complete module
+
+```tsx
+<SkeletonRegion messages={{ label: 'Loading members' }} loading={pending}>
+  {members.map((member) => (
+    <MemberRow key={member.id} member={member} />
+  ))}
+</SkeletonRegion>;
+```
+
+### The flash, and the flash in reverse
+
+delay withholds the paint until the wait is worth reporting; minDuration holds a placeholder that did appear. Both are zero unless an application sets them.
+
+Excerpt — not a complete module
+
+```tsx
+<SkeletonDefaultsProvider delay={200} minDuration={400}>
+  <App />
+</SkeletonDefaultsProvider>;
+
+// onReveal fires when the placeholders actually go, not when loading does.
+<SkeletonRegion loading={pending} onReveal={() => table.focus()}>
+  <Rows />
+</SkeletonRegion>;
+```
+
+### How the wait moves
+
+shimmer sends a band across the placeholder and is the default; pulse dims the fill and back for a quieter surface; none is still. Under reduced motion all three stop.
+
+Excerpt — not a complete module
+
+```tsx
+<SkeletonText animation="shimmer" />;
+<SkeletonText animation="pulse" />;
+<SkeletonText animation="none" />;
+```
+
+### A loading surface a product would ship
+
+An avatar, a name, a role and a status chip, each placeholder standing in the box its own family will occupy, all under one region that owns the wait.
+
+Excerpt — not a complete module
+
+```tsx
+<SkeletonRegion messages={{ label: 'Loading members' }} loading={pending}>
+  <Inline gap="5">
+    <Skeleton shape="circle" size="md" />
+    <Stack gap="2">
+      <Skeleton inlineSize="9rem" shape="text" />
+      <Skeleton inlineSize="5rem" shape="text" />
+    </Stack>
+  </Inline>
+</SkeletonRegion>;
+```
+
+### Content the family did not choose
+
+A narrow column, a right-to-left paragraph where the short row and the sweep both change ends, and a heading whose placeholder is a heading tall without being told what a heading is.
+
+Excerpt — not a complete module
+
+```tsx
+<Heading level={2}>
+  <Skeleton inlineSize="60%" shape="text" />
+</Heading>;
+
+<div dir="rtl">
+  <SkeletonText lines={3} />
+</div>;
+```
+
+### What a reader hears
+
+Every box is hidden and inert; the region says the label once and then falls silent. Tab through the loading half and focus skips it entirely.
+
+Excerpt — not a complete module
+
+```tsx
+<SkeletonRegion messages={{ label: 'Loading invoices' }} loadedLabel="Invoices loaded">
+  <SkeletonText />
+</SkeletonRegion>;
+
+// A region the reader never waits on says nothing at all.
+<SkeletonRegion live="off">
+  <Skeleton shape="circle" />
+</SkeletonRegion>;
+```