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

package/dist/docs/stat-card.md

@@ -0,0 +1,305 @@
+<!-- index: ./index.md -->
+# stat-card
+
+`data-ui="stat-card"` · Key figure with label, change and trend.
+
+## Import
+
+```tsx
+import {
+  StatCard,
+  StatCardHeader,
+  StatCardLabel,
+  StatCardStatus,
+  StatCardAction,
+  StatCardFigure,
+  StatCardValue,
+  StatCardUnit,
+  StatCardDelta,
+  StatCardComparison,
+  StatCardPeriod,
+  StatCardTrend,
+  StatCardMessage,
+  StatCardDefaultsProvider,
+} from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<StatCard delta={0.124} goodWhen="up">
+  <StatCardHeader>
+    <StatCardLabel>Open orders</StatCardLabel>
+  </StatCardHeader>
+  <StatCardFigure>
+    <StatCardValue value={1510} />
+    <StatCardDelta />
+    <StatCardComparison>
+      from 1,343 <StatCardPeriod>last week</StatCardPeriod>
+    </StatCardComparison>
+  </StatCardFigure>
+  <StatCardTrend>
+    <Sparkline area data={orders} label="Open orders" />
+  </StatCardTrend>
+</StatCard>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `body` | div | yes |
+| `header` | div | no |
+| `label` | span | no |
+| `status` | span | no |
+| `action` | span | no |
+| `figure` | div | no |
+| `value` | span | no |
+| `unit` | span | no |
+| `delta` | span | no |
+| `indicator` | span | no |
+| `comparison` | p | no |
+| `period` | span | no |
+| `trend` | div | no |
+| `message` | p | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | StatCard | The figure’s type and the card’s inset |
+| `fill` | `'outline' \| 'elevated' \| 'subtle' \| 'plain'` | outline | StatCard | The frame: a hairline, a shadow, a sunken fill, or none at all |
+| `layout` | `'inline' \| 'stacked'` | inline | StatCard | The trend beside the figure, or on its own row under it |
+| `status` | `'ready' \| 'empty' \| 'error'` | ready | StatCard | Whether there is a value to show, and if not, why. The layout is kept either way |
+| `loading` | `boolean` | false | StatCard | The value is on its way: every part stands in with a placeholder and the root is aria-busy |
+| `goodWhen` | `'up' \| 'down' \| 'none'` | up | StatCard, StatCardDelta | Which way is good for this metric. The tone of a change is derived from it, never from the sign |
+| `delta` | `number` | — | StatCard | The change, as the first delta reads it: a fraction for a percentage. Stated on the root so the card knows its tone before its delta renders |
+| `tone` | `'neutral' \| 'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | — | StatCard, StatCardDelta | An explicit tone, which wins over the derived one. On the root it is what the trend hands its sparkline |
+| `locale` | `string` | — | StatCard | BCP 47, for every number the card formats; the language in force when absent |
+| `formatOptions` | `Intl.NumberFormatOptions` | — | StatCard, StatCardValue, StatCardDelta | How a number is written. On the root, the default for the value and the delta |
+| `messages` | `Partial<StatCardMessages>` | — | StatCard | Words laid over the language in force, key by key: up, down and flat, heard before the delta; empty, shown in place of a missing value |
+| `value` | `number \| string` | — | StatCardValue, StatCardDelta | A number the card formats, or text as written. On a delta, unset means the root’s delta |
+| `format` | `'percent' \| 'decimal'` | percent | StatCardDelta | percent reads the value as a fraction; decimal reads it as it is. The sign is shown except on nought |
+| `children` | `ReactNode` | — | StatCardValue, StatCardDelta | Your own rendering of the number, unit and all; wins over value |
+| `render` | `(props) => ReactNode` | — | every part | Substitutes the rendered element: a heading for the label, a link for the action, a figure for the root |
+| `ref` | `Ref<HTMLElement>` | — | every part | Reaches the native element; each part’s props are that element’s, extended |
+| `StatCardTrend` | `children` | — | StatCard | Takes a Sparkline and hands it the card’s tone through --slotted-sparkline-color and its ground for the marker’s ring; a tone or series on the sparkline still wins |
+| `StatCardStatus, StatCardAction` | `children` | — | StatCardHeader | Slots for a Badge or StatusIndicator, and for a Link or Button, kept as you wrote them |
+| `trendOf, toneOf` | `function` | — | Application | The two derivations, exported for a delta you format yourself |
+| `StatCardDefaultsProvider` | `StatCardDefaults` | — | Application | Sets goodWhen, size, fill, layout and formatOptions once for everything below it; a prop still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `fill` | `outline`, `elevated`, `subtle`, `plain` | `outline` |
+| `layout` | `inline`, `stacked` | `inline` |
+| `status` | `ready`, `empty`, `error` | `ready` |
+| `goodWhen` | `up`, `down`, `none` | `up` |
+| `tone` | `neutral`, `accent`, `secondary`, `success`, `warning`, `danger` | — |
+| `trend` | `up`, `down`, `flat` | — |
+
+## Rules
+
+- The root is a group named by its label through aria-labelledby, so a reader who lands on the action inside it hears which metric it belongs to. There is no APG pattern for a statistic; a group with a name is what the platform offers a labelled region that is not a landmark.
+- The delta reads its direction before its number — “up +12.4%” — from a visually hidden word, because a sign is a glyph some readers skip and “12.4%” alone does not say which way. The indicator is aria-hidden; it repeats what the word says.
+- The tone is never the only channel: the indicator turns, the word is read, the sign is written. A rise that is bad and a rise that is good differ in colour and in nothing a reader without colour loses.
+- While loading the root carries aria-busy="true" and every placeholder is a skeleton, hidden and inert. One announcement for a whole dashboard is a SkeletonRegion around it, which is the platform’s own answer rather than one per card.
+- A missing or failed value is a dash and a message, in the DOM and in the tree; a card never announces a stale number as current.
+- The value is never truncated. A number wider than the trend’s room takes the room; a number wider than the card breaks; nothing is clipped or hidden behind an ellipsis.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-font-family-sans`, `--slotted-font-size-2xl`, `--slotted-font-size-3xl`, `--slotted-font-size-4xl`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xl`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-2xl`, `--slotted-line-height-3xl`, `--slotted-line-height-4xl`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xl`, `--slotted-line-height-xs`, `--slotted-radius-lg`, `--slotted-radius-none`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-11`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-space-9`, `--slotted-sparkline-block-size`, `--slotted-sparkline-block-size-lg`, `--slotted-sparkline-block-size-sm`, `--slotted-stat-card-background`, `--slotted-stat-card-background-subtle`, `--slotted-stat-card-border-color`, `--slotted-stat-card-border-width`, `--slotted-stat-card-color`, `--slotted-stat-card-color-muted`, `--slotted-stat-card-delta-font-size`, `--slotted-stat-card-delta-font-size-lg`, `--slotted-stat-card-delta-font-size-sm`, `--slotted-stat-card-indicator-size`, `--slotted-stat-card-indicator-size-lg`, `--slotted-stat-card-label-font-size`, `--slotted-stat-card-label-font-size-lg`, `--slotted-stat-card-label-font-size-sm`, `--slotted-stat-card-label-line-height`, `--slotted-stat-card-label-line-height-lg`, `--slotted-stat-card-label-line-height-sm`, `--slotted-stat-card-min-inline-size`, `--slotted-stat-card-padding-block`, `--slotted-stat-card-padding-block-lg`, `--slotted-stat-card-padding-block-sm`, `--slotted-stat-card-padding-inline`, `--slotted-stat-card-padding-inline-lg`, `--slotted-stat-card-padding-inline-sm`, `--slotted-stat-card-prose-font-size`, `--slotted-stat-card-prose-font-size-lg`, `--slotted-stat-card-prose-line-height`, `--slotted-stat-card-prose-line-height-lg`, `--slotted-stat-card-radius`, `--slotted-stat-card-region-gap`, `--slotted-stat-card-region-gap-lg`, `--slotted-stat-card-region-gap-sm`, `--slotted-stat-card-shadow`, `--slotted-stat-card-shadow-elevated`, `--slotted-stat-card-trend-gap`, `--slotted-stat-card-trend-gap-lg`, `--slotted-stat-card-trend-gap-sm`, `--slotted-stat-card-trend-inline-size`, `--slotted-stat-card-trend-inline-size-lg`, `--slotted-stat-card-trend-inline-size-sm`, `--slotted-stat-card-value-font-size`, `--slotted-stat-card-value-font-size-lg`, `--slotted-stat-card-value-font-size-sm`, `--slotted-stat-card-value-line-height`, `--slotted-stat-card-value-line-height-lg`, `--slotted-stat-card-value-line-height-sm`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
+
+## Examples
+
+### Every part in its place
+
+A label with a live badge and a details link, a value with its unit, a delta, the comparison and its period, and a sparkline in the trend region: the whole family on one card, with the message part waiting for a status that needs it.
+
+Excerpt — not a complete module
+
+```tsx
+<StatCard delta={0.032} goodWhen="up">
+  <StatCardHeader>
+    <StatCardLabel>Fill rate</StatCardLabel>
+    <StatCardStatus>
+      <Badge tone="success" variant="soft">
+        Live
+      </Badge>
+    </StatCardStatus>
+    <StatCardAction>
+      <Link href="/reports/fill-rate">Details</Link>
+    </StatCardAction>
+  </StatCardHeader>
+  <StatCardFigure>
+    <StatCardValue>
+      96.1<StatCardUnit>%</StatCardUnit>
+    </StatCardValue>
+    <StatCardDelta />
+    <StatCardComparison>
+      from 92.9% <StatCardPeriod>vs. previous quarter</StatCardPeriod>
+    </StatCardComparison>
+  </StatCardFigure>
+  <StatCardTrend>
+    <Sparkline area data={fillRate} label="Fill rate" />
+  </StatCardTrend>
+  <StatCardMessage>No data for this period yet.</StatCardMessage>
+</StatCard>;
+```
+
+### The tone comes from the meaning, not the sign
+
+A rise in fill rate and a fall in stockouts are both success; a rise in lead time and a fall in orders are both danger; a flat change and a metric with no valence stay neutral, and the sparkline in the trend follows the delta.
+
+Excerpt — not a complete module
+
+```tsx
+<StatCard delta={0.18} goodWhen="down">
+  <StatCardHeader>
+    <StatCardLabel>Average lead time</StatCardLabel>
+  </StatCardHeader>
+  <StatCardFigure>
+    <StatCardValue>
+      4.6<StatCardUnit>days</StatCardUnit>
+    </StatCardValue>
+    <StatCardDelta />
+  </StatCardFigure>
+</StatCard>;
+
+// A count nobody wants more or less of.
+<StatCard delta={0.094} goodWhen="none">
+  …
+</StatCard>;
+```
+
+### Three sizes of figure
+
+sm sets the value at 20 pixels for a row of eight, md at 24 for the four a dashboard opens with, lg at 32 — the step the type scale gained for it — for the one metric a page leads with. The trend column widens with the step.
+
+Excerpt — not a complete module
+
+```tsx
+<StatCard size="sm">…</StatCard>;
+<StatCard size="md">…</StatCard>;
+<StatCard size="lg">…</StatCard>;
+```
+
+### Four frames
+
+outline is the hairline card; elevated lifts on a shadow and keeps the hairline for forced colours; subtle recedes onto the sunken surface; plain has no frame and no inset, for a table cell or a row divided by rules where a second edge would be a box in a box.
+
+Excerpt — not a complete module
+
+```tsx
+<StatCard fill="outline">…</StatCard>;
+<StatCard fill="elevated">…</StatCard>;
+<StatCard fill="subtle">…</StatCard>;
+<StatCard fill="plain">…</StatCard>;
+```
+
+### The trend beside the figure, or under it
+
+inline puts the sparkline in a column beside the value, centred on the figure; stacked gives it the full width on the last row, level with the bottom of every card in the row. Under 220 pixels a card stacks on its own and drops the value one step.
+
+Excerpt — not a complete module
+
+```tsx
+<StatCard layout="inline">…</StatCard>;
+<StatCard layout="stacked">…</StatCard>;
+```
+
+### The layout is kept while the value is on its way
+
+Every text part stands in with a placeholder of its own line height and the trend with a block the sparkline’s height, so nothing moves when the numbers arrive; the previous value is not shown as if it were current.
+
+Excerpt — not a complete module
+
+```tsx
+<StatCard loading={pending}>
+  <StatCardHeader>
+    <StatCardLabel>Open orders</StatCardLabel>
+  </StatCardHeader>
+  <StatCardFigure>
+    <StatCardValue value={orders.total} />
+    <StatCardDelta value={orders.delta} />
+  </StatCardFigure>
+  <StatCardTrend>
+    <Sparkline data={orders.series} />
+  </StatCardTrend>
+</StatCard>;
+```
+
+### A value that is missing, and one that failed
+
+empty and error keep the card’s frame and height, put a dash where the value was, drop the delta, the comparison and the trend, and show the message — in the danger tone when the metrics service did not answer.
+
+Excerpt — not a complete module
+
+```tsx
+<StatCard status={error ? 'error' : 'empty'}>
+  <StatCardHeader>
+    <StatCardLabel>Churn</StatCardLabel>
+  </StatCardHeader>
+  <StatCardFigure>
+    <StatCardValue />
+  </StatCardFigure>
+  <StatCardMessage>
+    {error ? 'The metrics service did not answer.' : 'No data for this period yet.'}
+  </StatCardMessage>
+</StatCard>;
+```
+
+### A row of metrics, as a dashboard opens
+
+Four cards in a grid with different content — a wrapped delta, no delta, bars instead of a line — keep their labels level at the top and their trends level at the bottom; below, three plain cards in one framed row separated by rules.
+
+Excerpt — not a complete module
+
+```tsx
+<Grid columns={4} gap={4}>
+  <StatCard delta={0.124}>…</StatCard>
+  <StatCard delta={0.032}>…</StatCard>
+  <StatCard delta={0.003} goodWhen="down">
+    …
+  </StatCard>
+  <StatCard delta={-0.012}>…</StatCard>
+</Grid>;
+
+<StatCardDefaultsProvider fill="plain" size="sm">
+  <StatCard delta={0.081}>…</StatCard>
+  <StatCard delta={-0.0004} goodWhen="down">
+    …
+  </StatCard>
+</StatCardDefaultsProvider>;
+```
+
+### Content the family did not choose
+
+A German label that wraps to three lines and keeps its badge on the first; a currency value too wide for the trend, which gives way instead of the number breaking; a card at 200 pixels that stacks; a right-to-left document where the sign stays in front and the marks turn.
+
+Excerpt — not a complete module
+
+```tsx
+<StatCardValue
+  formatOptions={{ style: 'currency', currency: 'BRL', notation: 'compact' }}
+  value={1234567890}
+/>;
+```
+
+### What a reader hears
+
+The card is a group named by its label, so the details link inside it is “Details, Fill rate”; the delta reads “up +3.2%” with the direction said before the sign; the sparkline is an image described in the same numbers; the words are those of the language in force.
+
+Excerpt — not a complete module
+
+```tsx
+<SlottedProvider locale="pt-BR" catalogs={{ 'pt-BR': PT_BR }}>
+  <Dashboard />
+</SlottedProvider>;
+```

package/dist/docs/status-indicator.json

@@ -0,0 +1,312 @@
+{
+  "family": "status-indicator",
+  "ui": "status-indicator",
+  "binding": "react",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Colored mark and label for a status."
+  },
+  "axes": {
+    "status": [
+      "neutral",
+      "info",
+      "success",
+      "warning",
+      "danger",
+      "unknown"
+    ],
+    "mark": [
+      "dot",
+      "icon"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "live": [
+      "off",
+      "polite",
+      "assertive"
+    ]
+  },
+  "members": {
+    "statusIndicator": {
+      "nativeElement": "span",
+      "defaults": {
+        "status": "neutral",
+        "mark": "dot",
+        "size": "md",
+        "live": "off",
+        "pulse": false
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "status",
+        "live"
+      ],
+      "states": [
+        "default",
+        "focus-visible"
+      ],
+      "parts": [
+        "root",
+        "mark",
+        "label",
+        "announcement"
+      ]
+    }
+  },
+  "docs": {
+    "statusIndicator": {
+      "imports": {
+        "source": "import { StatusIndicator, StatusIndicatorDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "span",
+          "required": true,
+          "purpose": "The whole indicator. Carries data-ui=\"status-indicator\", the axes as data attributes, data-pulse when the wave is drawn, the live role when live is on, and every native attribute the consumer passes."
+        },
+        {
+          "part": "mark",
+          "element": "span",
+          "required": true,
+          "purpose": "The disc or the glyph. A box one line tall, so the mark sits on the first line however far the label wraps. Hidden from assistive technology: it says nothing the label does not."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": true,
+          "purpose": "The words. It wraps rather than truncating, and breaks an unbroken token, so a deployment id does not widen the column it sits in."
+        },
+        {
+          "part": "announcement",
+          "element": "span",
+          "required": false,
+          "purpose": "The status’s own word, clipped from view by visually-hidden. Rendered only when the consumer supplied no visible label, so a bare mark is never nameless."
+        }
+      ],
+      "api": [
+        {
+          "name": "status",
+          "type": "'neutral' | 'info' | 'success' | 'warning' | 'danger' | 'unknown'",
+          "defaultValue": "neutral",
+          "appliesTo": "StatusIndicator",
+          "description": "The operational state. Each value owns a tone and a glyph; the vocabulary is closed, so a domain status maps onto one of the six and writes its own words"
+        },
+        {
+          "name": "mark",
+          "type": "'dot' | 'icon'",
+          "defaultValue": "dot",
+          "appliesTo": "StatusIndicator",
+          "description": "dot is the compact chromatic mark; icon carries a distinct silhouette per status and is the alternative that does not depend on colour"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "StatusIndicator",
+          "description": "Reads the control type and glyph scales, so all three steps answer density"
+        },
+        {
+          "name": "live",
+          "type": "'off' | 'polite' | 'assertive'",
+          "defaultValue": "off",
+          "appliesTo": "StatusIndicator",
+          "description": "Whether a change is announced. polite writes role=\"status\"; assertive writes role=\"alert\" and interrupts. A role the consumer wrote is never replaced"
+        },
+        {
+          "name": "pulse",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "StatusIndicator",
+          "description": "A wave leaving the dot, for a change happening now. Not drawn on an icon mark, and withdrawn under reduced motion and under forced colours, so it is never the only carrier"
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "StatusIndicator",
+          "description": "What a reader hears when there are no visible words. Ignored when there are. Falls back to the status’s word in the catalog"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<StatusIndicatorMessages>",
+          "defaultValue": "—",
+          "appliesTo": "StatusIndicator",
+          "description": "Words laid over the language in force, key by key: the word each status is heard as when there are no visible words (neutral, info, success, warning, danger, unknown)"
+        }
+      ],
+      "composition": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "StatusIndicator",
+          "description": "The visible words, which are also the accessible name — a status that shows its words needs no second copy of them"
+        },
+        {
+          "name": "render",
+          "type": "(props: StatusIndicatorRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "StatusIndicator",
+          "description": "Substitutes the rendered element. Every data attribute and both inner parts are handed to it, so a status can become a link without losing its mark"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLSpanElement>",
+          "defaultValue": "—",
+          "appliesTo": "StatusIndicator",
+          "description": "Reaches the root element. There is no imperative handle beyond it: the family has no action a page cannot express declaratively"
+        },
+        {
+          "name": "StatusIndicatorDefaultsProvider",
+          "type": "{ mark, size, live }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets the three once for everything below it. An explicit prop still wins"
+        },
+        {
+          "name": "events",
+          "type": "none",
+          "defaultValue": "—",
+          "appliesTo": "StatusIndicator",
+          "description": "The family emits nothing. status is the application’s fact about a system this component cannot see, so there is no value for it to request and no reason to carry"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "There is no status-indicator pattern in the WAI-ARIA Authoring Practices: the pattern index carries thirty entries and none of them is this family. The applicable guidance is the ARIA status role, WCAG 2.2 1.4.1 Use of Color and 1.4.11 Non-text Contrast, and each is answered below.",
+        "The name is always real text in the document — the visible words, or the status’s own word clipped by visually-hidden. role=\"img\" with an aria-label, which is Fluent’s answer, is deliberately not used: text is what lets a live region announce its own contents, lets an aria-labelledby elsewhere point at it, and lets a page search find the word.",
+        "Colour is never the only carrier. Every indicator has words, and mark=\"icon\" adds a distinct silhouette per status — six circles — so the six survive greyscale, the high-contrast scheme, and the operating system’s forced colours, where every author colour is replaced and the glyph is all that is left.",
+        "Every dot fill clears the 3:1 that WCAG 2.2 1.4.11 asks of a graphic against the surface in the light and dark schemes, except warning, whose yellow is 1.53:1 on white; that dot alone is rimmed in the warning border role, 2.94:1. The word beside the dot carries the status, so the dot is never the only carrier.",
+        "live=\"polite\" writes role=\"status\", which the platform gives an implicit aria-live=\"polite\" and aria-atomic=\"true\", so the mark and its word are announced as one thing rather than as two events. live=\"assertive\" writes role=\"alert\" and interrupts, which the APG reserves for a message needing immediate attention. Nothing here takes focus when the status changes.",
+        "The pulse is withdrawn under prefers-reduced-motion rather than shortened, because an endless animation has to stop; a wave frozen halfway through an expansion is a rendering fault rather than a state. Nothing is lost, since the tone, the glyph and the word were already carrying the status.",
+        "Nothing in the family is focusable on its own and no key is bound. The focus ring is painted for the case a consumer creates — a status that became a link through render — so the ring is never missing where focus can land."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-border-width-thick",
+    "--slotted-border-width-thin",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-duration-loop-slow",
+    "--slotted-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-line-height-md",
+    "--slotted-radius-full",
+    "--slotted-space-1",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-status-indicator-font-family",
+    "--slotted-status-indicator-mark-border-color",
+    "--slotted-status-indicator-mark-border-width",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-solid",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-text",
+    "--slotted-tone-success-solid",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-border",
+    "--slotted-tone-warning-solid",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One indicator with every axis on it, driven by the controls below the canvas. Switch mark to icon and the meaning survives with the colour switched off.",
+      "language": "tsx",
+      "source": "<StatusIndicator status=\"success\">Healthy</StatusIndicator>;\n\n// With no words, the status names itself.\n<StatusIndicator status=\"success\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "statuses",
+      "title": "The six operational states",
+      "note": "Each maps onto one of the library’s five tones and owns one glyph. neutral and unknown share a tone, so the mark is what tells “nothing is happening” from “nobody knows”.",
+      "language": "tsx",
+      "source": "<StatusIndicator status=\"neutral\">Draft</StatusIndicator>;\n<StatusIndicator status=\"info\">Live</StatusIndicator>;\n<StatusIndicator status=\"success\">Healthy</StatusIndicator>;\n<StatusIndicator status=\"warning\">Degraded</StatusIndicator>;\n<StatusIndicator status=\"danger\">Failed</StatusIndicator>;\n<StatusIndicator status=\"unknown\">No data</StatusIndicator>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "marks",
+      "title": "The dot, and the mark that does not need colour",
+      "note": "A dot is compact and chromatic, so the words beside it carry the meaning. An icon carries a distinct silhouette per status, which is what WCAG 2.2 1.4.1 asks for where the words cannot be shown.",
+      "language": "tsx",
+      "source": "<StatusIndicator status=\"warning\">Degraded</StatusIndicator>;\n<StatusIndicator mark=\"icon\" status=\"warning\">\n  Degraded\n</StatusIndicator>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "How large the indicator is",
+      "note": "Type and glyph read the control scales, the only ones the theme restates per density, so a status shrinks with the table row it sits in rather than pushing that row taller.",
+      "language": "tsx",
+      "source": "<StatusIndicator size=\"sm\" status=\"success\">\n  Healthy\n</StatusIndicator>;\n<StatusIndicator size=\"lg\" status=\"success\">\n  Healthy\n</StatusIndicator>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "pulse",
+      "title": "A change happening now",
+      "note": "A wave leaves the dot and fades, then rests before the next beat. An icon mark does not pulse. It is for a value moving while the reader watches — a deploy, a reindex, an error rate climbing — and never decoration on a status that settled a week ago.",
+      "language": "tsx",
+      "source": "<StatusIndicator pulse status=\"info\">\n  Deploying to production\n</StatusIndicator>;\n\n// Not this: nothing is changing.\n<StatusIndicator pulse status=\"success\">\n  Healthy since Tuesday\n</StatusIndicator>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "announcements",
+      "title": "What a screen reader hears when the status changes",
+      "note": "off by default, because a status already on the page when it loaded is not news. polite waits for a pause; assertive interrupts, and belongs to something a reader has to act on now.",
+      "language": "tsx",
+      "source": "<StatusIndicator status=\"success\">Healthy</StatusIndicator>;\n\n<StatusIndicator live=\"polite\" status=\"info\">\n  Deploying\n</StatusIndicator>;\n\n<StatusIndicator live=\"assertive\" status=\"danger\">\n  Region offline\n</StatusIndicator>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "context",
+      "title": "Where a status actually lives",
+      "note": "A column of services, and a header where one status stands for a whole page. The words take the page’s own colour, so the status column reads as easily as the one beside it.",
+      "language": "tsx",
+      "source": "<tr>\n  <td>checkout-api</td>\n  <td>\n    <StatusIndicator size=\"sm\" status=\"success\">\n      Healthy\n    </StatusIndicator>\n  </td>\n</tr>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A status that is a sentence, a container digest with nothing to break on, and a German label: the label wraps, the token breaks, and the mark stays on the first line of all three.",
+      "language": "tsx",
+      "source": "<StatusIndicator mark=\"icon\" status=\"warning\">\n  Waiting for approval from the security review board\n</StatusIndicator>;\n\n<StatusIndicator status=\"danger\">sha256:9f2b7c1de4a80b35c7f9a1e6d2408baf5c31</StatusIndicator>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "The provider decides for a whole application, render substitutes the element, and a mark on the corner of an avatar is badge’s anchor rather than a second answer here.",
+      "language": "tsx",
+      "source": "<StatusIndicatorDefaultsProvider mark=\"icon\" size=\"sm\">\n  <App />\n</StatusIndicatorDefaultsProvider>;\n\n<StatusIndicator render={(props) => <a href=\"/builds/4821\" {...props} />} status=\"danger\">\n  Build 4821 failed\n</StatusIndicator>;\n\n<BadgeAnchor overlap=\"circle\">\n  <Avatar name=\"Ada Lovelace\" />\n  <Badge shape=\"dot\" tone=\"success\">\n    <VisuallyHidden>Online</VisuallyHidden>\n  </Badge>\n</BadgeAnchor>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears",
+      "note": "A mark with no visible words still carries its own, clipped rather than absent — so it is announced, findable by a page search, and available to an aria-labelledby elsewhere.",
+      "language": "tsx",
+      "source": "// “Error”, from the family’s own table.\n<StatusIndicator status=\"danger\" />;\n\n// “Deploy failed”, from the application.\n<StatusIndicator label=\"Deploy failed\" status=\"danger\" />;\n\n// “Build 4821 failed”, from the words on the page.\n<StatusIndicator status=\"danger\">Build 4821 failed</StatusIndicator>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}