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

package/docs/skeleton.json

@@ -0,0 +1,358 @@
+{
+  "family": "skeleton",
+  "ui": "skeleton",
+  "binding": "angular",
+  "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 { SlSkeleton, SlSkeletonText, SlSkeletonRegion, provideSkeletonDefaults } from '@slotted/angular/skeleton';",
+        "selector": "[slSkeleton] · [slSkeletonText] · [slSkeletonRegion]",
+        "exportAs": "slSkeleton · slSkeletonText · slSkeletonRegion"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "span",
+          "required": true,
+          "purpose": "One placeholder box, on whatever element you put slSkeleton on — the selector is a bare attribute, so a word’s placeholder lives in a span and a card’s lives in the card. Empty it draws the geometry shape and size describe; with projected content it takes that content’s geometry and covers it."
+        },
+        {
+          "part": "text",
+          "element": "div",
+          "required": true,
+          "purpose": "The rows of a paragraph, on your own element, from slSkeletonText. 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 by the component’s own template. 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, on your own element — a section, a tbody, a list item — from slSkeletonRegion. Carries aria-busy, the timing, and the animation phase every placeholder inside it reads through DI."
+        },
+        {
+          "part": "announcement",
+          "element": "span",
+          "required": true,
+          "purpose": "The one visually-hidden role=\"status\" per region, projected before the consumer’s own content. 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": "SlSkeleton",
+          "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": "SlSkeleton",
+          "description": "The avatar scale. Means nothing for text, which takes its height from the type, or for block"
+        },
+        {
+          "name": "inlineSize, blockSize",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SlSkeleton, SlSkeletonText",
+          "description": "The reserved geometry, in logical axes, written straight onto the family’s own custom properties. Ignored where content is covered and measured instead"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "SlSkeleton, SlSkeletonText, SlSkeletonRegion",
+          "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": "SlSkeletonText",
+          "description": "How many rows of the paragraph to reserve"
+        },
+        {
+          "name": "lastLineSize",
+          "type": "string",
+          "defaultValue": "62%",
+          "appliesTo": "SlSkeletonText",
+          "description": "How wide the last row is drawn, when there is more than one"
+        },
+        {
+          "name": "animation",
+          "type": "'shimmer' | 'pulse' | 'none'",
+          "defaultValue": "shimmer",
+          "appliesTo": "SlSkeleton, SlSkeletonText, SlSkeletonRegion",
+          "description": "How the wait moves. A region hands its value to everything inside it"
+        },
+        {
+          "name": "live",
+          "type": "'polite' | 'off'",
+          "defaultValue": "polite",
+          "appliesTo": "SlSkeletonRegion",
+          "description": "Whether the region announces the wait at all"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<SkeletonMessages>",
+          "defaultValue": "—",
+          "appliesTo": "SlSkeletonRegion",
+          "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": "SlSkeletonRegion",
+          "description": "What it hears when the content arrives. Silent unless set, so one load says one thing"
+        },
+        {
+          "name": "delay",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "SlSkeletonRegion",
+          "description": "Milliseconds the wait must last before anything is painted"
+        },
+        {
+          "name": "minDuration",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "SlSkeletonRegion",
+          "description": "Milliseconds a placeholder that did appear is held before it is withdrawn"
+        }
+      ],
+      "composition": [
+        {
+          "name": "<ng-content>",
+          "type": "—",
+          "defaultValue": "—",
+          "appliesTo": "SlSkeleton, SlSkeletonRegion",
+          "description": "Content is covered rather than replaced: the box takes its geometry, hides it, and reveals it untouched when loading ends"
+        },
+        {
+          "name": "the selector",
+          "type": "[slSkeleton], [slSkeletonText], [slSkeletonRegion]",
+          "defaultValue": "—",
+          "appliesTo": "all three",
+          "description": "Bare attributes, so the element stays yours — a span, a li, a tbody, a section — and your own attributes and listeners sit on it"
+        },
+        {
+          "name": "exportAs",
+          "type": "slSkeleton | slSkeletonText | slSkeletonRegion",
+          "defaultValue": "—",
+          "appliesTo": "all three",
+          "description": "Reaches the instance from a template, including painted(), which is not the same signal as loading"
+        },
+        {
+          "name": "provideSkeletonDefaults()",
+          "type": "SkeletonDefaults",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets the animation, the measure and the timing once through SKELETON_DEFAULTS_TOKEN; an input on a region or a box still wins"
+        }
+      ],
+      "events": [
+        {
+          "name": "(reveal)",
+          "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.",
+        "An aria-hidden you wrote on your own element is read once through HostAttributeToken and kept, so a placeholder that has to stay announced can be, and the host binding never writes over a static attribute.",
+        "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": "html",
+      "source": "<span slSkeleton shape=\"circle\" size=\"md\" [loading]=\"pending()\">\n  <span slAvatar name=\"Ada Lovelace\" size=\"md\"></span>\n</span>\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": "html",
+      "source": "<span slSkeleton shape=\"text\" inlineSize=\"8rem\"></span>\n<span slSkeleton shape=\"block\" blockSize=\"6rem\"></span>\n<span slSkeleton shape=\"circle\" size=\"lg\"></span>\n<span slSkeleton shape=\"square\" size=\"lg\"></span>\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": "html",
+      "source": "<div slSkeletonText [lines]=\"3\"></div>\n\n<!-- Ten rows of a list, and a shorter tail. -->\n<div slSkeletonText [lines]=\"10\" lastLineSize=\"40%\"></div>\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": "html",
+      "source": "<span slSkeleton shape=\"circle\" size=\"md\"></span>\n\n<!-- Once the person has loaded. -->\n<span slAvatar name=\"Ada Lovelace\" size=\"md\"></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "wrapping",
+      "title": "Covering content instead of describing it",
+      "note": "Project content into a placeholder and it takes that content’s box rather than one you typed, so the reserved space cannot disagree with what replaces it.",
+      "language": "html",
+      "source": "<span slSkeleton [loading]=\"pending()\">\n  <span slBadge tone=\"success\">Paid in full</span>\n</span>\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 through DI instead of its own input.",
+      "language": "html",
+      "source": "<section slSkeletonRegion [messages]=\"{ label: 'Loading members' }\" [loading]=\"pending()\">\n  @for (member of members(); track member.id) {\n    <app-member-row [member]=\"member\" />\n  }\n</section>\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": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideSkeletonDefaults({ delay: 200, minDuration: 400 })],\n});\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": "html",
+      "source": "<div slSkeletonText animation=\"shimmer\"></div>\n<div slSkeletonText animation=\"pulse\"></div>\n<div slSkeletonText animation=\"none\"></div>\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": "html",
+      "source": "<div slSkeletonRegion [messages]=\"{ label: 'Loading members' }\" [loading]=\"pending()\">\n  <div slInline gap=\"5\">\n    <span slSkeleton shape=\"circle\" size=\"md\"></span>\n    <div slStack gap=\"2\">\n      <span slSkeleton shape=\"text\" inlineSize=\"9rem\"></span>\n      <span slSkeleton shape=\"text\" inlineSize=\"5rem\"></span>\n    </div>\n  </div>\n</div>\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": "html",
+      "source": "<h2 slHeading [level]=\"2\">\n  <span slSkeleton shape=\"text\" inlineSize=\"60%\"></span>\n</h2>\n\n<div dir=\"rtl\">\n  <div slSkeletonText [lines]=\"3\"></div>\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": "html",
+      "source": "<div slSkeletonRegion [messages]=\"{ label: 'Loading invoices' }\" loadedLabel=\"Invoices loaded\">\n  <div slSkeletonText></div>\n</div>\n\n<!-- A region the reader never waits on says nothing at all. -->\n<div slSkeletonRegion live=\"off\">\n  <span slSkeleton shape=\"circle\"></span>\n</div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/skeleton.md

@@ -0,0 +1,223 @@
+<!-- index: ./index.md -->
+# skeleton
+
+`data-ui="skeleton"` · Placeholder shapes while content loads.
+
+## Import
+
+```ts
+import { SlSkeleton, SlSkeletonText, SlSkeletonRegion, provideSkeletonDefaults } from '@slotted/angular/skeleton';
+```
+
+Selector: `[slSkeleton] · [slSkeletonText] · [slSkeletonRegion]` · exportAs: `slSkeleton · slSkeletonText · slSkeletonRegion`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<span slSkeleton shape="circle" size="md" [loading]="pending()">
+  <span slAvatar name="Ada Lovelace" size="md"></span>
+</span>
+```
+
+## 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 | SlSkeleton | What the placeholder stands for: a line of type, a block of content, or an avatar |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | md | SlSkeleton | The avatar scale. Means nothing for text, which takes its height from the type, or for block |
+| `inlineSize, blockSize` | `string` | — | SlSkeleton, SlSkeletonText | The reserved geometry, in logical axes, written straight onto the family’s own custom properties. Ignored where content is covered and measured instead |
+| `loading` | `boolean` | true | SlSkeleton, SlSkeletonText, SlSkeletonRegion | Whether the content is still on its way. On a box, unset means the nearest region decides |
+| `lines` | `number` | 3 | SlSkeletonText | How many rows of the paragraph to reserve |
+| `lastLineSize` | `string` | 62% | SlSkeletonText | How wide the last row is drawn, when there is more than one |
+| `animation` | `'shimmer' \| 'pulse' \| 'none'` | shimmer | SlSkeleton, SlSkeletonText, SlSkeletonRegion | How the wait moves. A region hands its value to everything inside it |
+| `live` | `'polite' \| 'off'` | polite | SlSkeletonRegion | Whether the region announces the wait at all |
+| `messages` | `Partial<SkeletonMessages>` | — | SlSkeletonRegion | Words laid over the language in force, key by key: what a screen reader hears once, while the region is waiting (label) |
+| `loadedLabel` | `string` | — | SlSkeletonRegion | What it hears when the content arrives. Silent unless set, so one load says one thing |
+| `delay` | `number` | 0 | SlSkeletonRegion | Milliseconds the wait must last before anything is painted |
+| `minDuration` | `number` | 0 | SlSkeletonRegion | Milliseconds a placeholder that did appear is held before it is withdrawn |
+| `<ng-content>` | `—` | — | SlSkeleton, SlSkeletonRegion | Content is covered rather than replaced: the box takes its geometry, hides it, and reveals it untouched when loading ends |
+| `the selector` | `[slSkeleton], [slSkeletonText], [slSkeletonRegion]` | — | all three | Bare attributes, so the element stays yours — a span, a li, a tbody, a section — and your own attributes and listeners sit on it |
+| `exportAs` | `slSkeleton \| slSkeletonText \| slSkeletonRegion` | — | all three | Reaches the instance from a template, including painted(), which is not the same signal as loading |
+| `provideSkeletonDefaults()` | `SkeletonDefaults` | — | Application | Sets the animation, the measure and the timing once through SKELETON_DEFAULTS_TOKEN; an input on a region or a box still wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(reveal)` | `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.
+- An aria-hidden you wrote on your own element is read once through HostAttributeToken and kept, so a placeholder that has to stay announced can be, and the host binding never writes over a static attribute.
+- 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
+
+```html
+<span slSkeleton shape="text" inlineSize="8rem"></span>
+<span slSkeleton shape="block" blockSize="6rem"></span>
+<span slSkeleton shape="circle" size="lg"></span>
+<span slSkeleton shape="square" size="lg"></span>
+```
+
+### 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
+
+```html
+<div slSkeletonText [lines]="3"></div>
+
+<!-- Ten rows of a list, and a shorter tail. -->
+<div slSkeletonText [lines]="10" lastLineSize="40%"></div>
+```
+
+### 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
+
+```html
+<span slSkeleton shape="circle" size="md"></span>
+
+<!-- Once the person has loaded. -->
+<span slAvatar name="Ada Lovelace" size="md"></span>
+```
+
+### Covering content instead of describing it
+
+Project content into a placeholder and it takes that content’s box rather than one you typed, so the reserved space cannot disagree with what replaces it.
+
+Excerpt — not a complete module
+
+```html
+<span slSkeleton [loading]="pending()">
+  <span slBadge tone="success">Paid in full</span>
+</span>
+```
+
+### 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 through DI instead of its own input.
+
+Excerpt — not a complete module
+
+```html
+<section slSkeletonRegion [messages]="{ label: 'Loading members' }" [loading]="pending()">
+  @for (member of members(); track member.id) {
+    <app-member-row [member]="member" />
+  }
+</section>
+```
+
+### 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
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideSkeletonDefaults({ delay: 200, minDuration: 400 })],
+});
+```
+
+### 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
+
+```html
+<div slSkeletonText animation="shimmer"></div>
+<div slSkeletonText animation="pulse"></div>
+<div slSkeletonText animation="none"></div>
+```
+
+### 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
+
+```html
+<div slSkeletonRegion [messages]="{ label: 'Loading members' }" [loading]="pending()">
+  <div slInline gap="5">
+    <span slSkeleton shape="circle" size="md"></span>
+    <div slStack gap="2">
+      <span slSkeleton shape="text" inlineSize="9rem"></span>
+      <span slSkeleton shape="text" inlineSize="5rem"></span>
+    </div>
+  </div>
+</div>
+```
+
+### 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
+
+```html
+<h2 slHeading [level]="2">
+  <span slSkeleton shape="text" inlineSize="60%"></span>
+</h2>
+
+<div dir="rtl">
+  <div slSkeletonText [lines]="3"></div>
+</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
+
+```html
+<div slSkeletonRegion [messages]="{ label: 'Loading invoices' }" loadedLabel="Invoices loaded">
+  <div slSkeletonText></div>
+</div>
+
+<!-- A region the reader never waits on says nothing at all. -->
+<div slSkeletonRegion live="off">
+  <span slSkeleton shape="circle"></span>
+</div>
+```