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

package/dist/docs/link.md

@@ -0,0 +1,194 @@
+<!-- index: ./index.md -->
+# link
+
+`data-ui="link"` · Text link to another page or resource.
+
+## Import
+
+```tsx
+import { Link, LinkDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<p>
+  Read the <Link href="/terms">terms of service</Link> before continuing.
+</p>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | a | yes |
+| `external-icon` | span | no |
+| `external-hint` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `underline` | `'always' \| 'hover' \| 'none'` | always | Link | When the underline is drawn |
+| `variant` | `'accent' \| 'neutral' \| 'inverse'` | accent | Link | Accent, the colour of the surrounding text, or a solid surface |
+| `external` | `boolean` | false | Link | Opens a new tab and warns that it does |
+| `messages` | `Partial<LinkMessages>` | — | Link | Words laid over the language in force: the wording of that warning (externalHint) |
+| `disabled` | `boolean` | false | Link | Withholds the destination, keeps the role, the state and the tab stop |
+| `visited` | `boolean` | false | Link | Paints a destination the reader already followed |
+| `href` | `string` | — | Link | The destination, and every other anchor attribute — target, rel, download, hreflang — reaches the element unchanged |
+| `render` | `(props: LinkRootProps) => ReactNode` | — | Link | Substitutes the rendered element. The destination and every data attribute are handed to it, so a router link keeps both. |
+| `ref` | `Ref<HTMLAnchorElement>` | — | Link | Reaches the anchor, and focus() with it |
+| `onClick, onAuxClick, onKeyDown` | `EventHandler` | — | Link | Composed rather than replaced. While disabled the family refuses first and the handler is not called. |
+| `LinkDefaultsProvider` | `underline \| variant \| visited` | — | Application | Sets those three once for everything below it; a prop on the link still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `underline` | `always`, `hover`, `none` | `always` |
+| `variant` | `accent`, `neutral`, `inverse` | `accent` |
+
+## Rules
+
+- The rendered element is a plain anchor with an href, so the link role, Enter, the context menu and every modified click come from the platform. Space does not activate a link, and nothing here makes it.
+- underline="always" is the default because colour alone does not distinguish a link: the accent text colour clears 4.5:1 against the surface and not 3:1 against the body text beside it.
+- variant="neutral" takes the colour of the text around it, so it belongs where nothing on the line could be mistaken for it — a cell, a title, a row — and never inside a sentence.
+- Whatever the underline axis says, the underline returns under forced-colors, where the palette flattens the colour contrast a bare link relies on.
+- A new browsing context is announced in the accessible name and marked with a glyph, and both follow the resolved target: a target="_blank" written by hand is warned about exactly like external.
+- external also sets rel="noopener noreferrer"; a rel or target the consumer passed is kept instead of rewritten.
+- A disabled link renders no href, which is what stops a middle click as well as a left one, and keeps role="link", aria-disabled and its place in the tab sequence so the state can be discovered.
+- The current page is painted from aria-current, the attribute a router already writes; the family invents no prop for it.
+
+## Tokens
+
+`--slotted-control-radius`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-width`, `--slotted-link-color`, `--slotted-link-color-active`, `--slotted-link-color-current`, `--slotted-link-color-disabled`, `--slotted-link-color-hover`, `--slotted-link-color-visited`, `--slotted-link-external-icon-gap`, `--slotted-link-external-icon-size`, `--slotted-link-focus-ring-offset`, `--slotted-link-radius`, `--slotted-link-underline-color`, `--slotted-link-underline-offset`, `--slotted-link-underline-thickness`, `--slotted-text`, `--slotted-text-inverse`, `--slotted-text-muted`, `--slotted-tone-accent-text`
+
+## Examples
+
+### When the underline is drawn
+
+always is the default and the only value safe inside a sentence: the accent text colour clears 4.5:1 against the surface but not 3:1 against the body text beside it.
+
+Excerpt — not a complete module
+
+```tsx
+<Link href="/invoices">Underlined always</Link>;
+<Link href="/invoices" underline="hover">
+  Underlined on hover
+</Link>;
+<Link href="/invoices" underline="none">
+  Never underlined
+</Link>;
+```
+
+### How the link is painted
+
+accent invites, neutral takes the colour of the text around it for a cell or a title, and inverse is the link on a solid surface. Hover moves each one toward the strongest text colour its context has.
+
+Excerpt — not a complete module
+
+```tsx
+<Link href="/history">payment history</Link>;
+<Link href="/invoices/0041" underline="hover" variant="neutral">
+  INV-2026-08-0041
+</Link>;
+<Link href="/plans" variant="inverse">
+  Choose a plan
+</Link>;
+```
+
+### Leaving the application
+
+One fact told three ways: the safe rel, the marker for the eye, the warning in the accessible name. All three follow the resolved target, so a target written by hand is announced the same way.
+
+Excerpt — not a complete module
+
+```tsx
+<Link external href="https://example.com/docs">
+  Documentation
+</Link>;
+
+// The same warning, from the attribute instead of the prop.
+<Link href="https://example.com/docs" target="_blank">
+  Documentation
+</Link>;
+```
+
+### States
+
+Hover darkens the text and fills the underline, press goes one step further, and an unavailable link keeps its underline so it still reads as a link rather than as plain text.
+
+Excerpt — not a complete module
+
+```tsx
+<Link href="/invoices">At rest</Link>;
+<Link href="/invoices" visited>
+  Followed before
+</Link>;
+<Link disabled href="/invoices/0042">
+  Unavailable until the invoice is issued
+</Link>;
+```
+
+### The page you are on
+
+aria-current is the input, because it is the attribute a router already writes. The link takes the body colour and keeps its underline, and no width changes, so the column beside it does not shift.
+
+Excerpt — not a complete module
+
+```tsx
+<nav aria-label="Workspace">
+  <Link aria-current="page" href="/invoices" underline="hover">
+    Invoices
+  </Link>
+  <Link href="/members" underline="hover">
+    Members
+  </Link>
+</nav>;
+```
+
+### Content the link did not choose
+
+A pasted URL with no spaces, a long German compound, and an Arabic sentence. The first two break inside the column instead of widening it; the third mirrors the marker without mirroring the Latin island beside it.
+
+Excerpt — not a complete module
+
+```tsx
+<Link href="/reconciliation">
+  https://billing.example.com/accounts/8412/invoices/2026-08/reconciliation-report
+</Link>;
+```
+
+### Composition
+
+render substitutes the element for a router link and hands it the destination, and LinkDefaultsProvider decides for a whole application what a link looks like. An explicit prop still wins over both.
+
+Excerpt — not a complete module
+
+```tsx
+<Link href="/invoices" render={(props) => <RouterLink {...props} to={props.href} />}>
+  Invoices
+</Link>;
+
+<LinkDefaultsProvider underline="hover">
+  <App />
+</LinkDefaultsProvider>;
+```
+
+### Keyboard and announcement
+
+Tab reaches every link including the unavailable one, Enter follows the one that has a destination, and Space does nothing because Space does not activate a link.
+
+Excerpt — not a complete module
+
+```tsx
+<Link href="/invoices">A link with a destination</Link>;
+<Link external href="https://example.com/status">
+  A link that leaves the application
+</Link>;
+<Link disabled href="/invoices/0042">
+  A link that is unavailable
+</Link>;
+```

package/dist/docs/list-item.json

@@ -0,0 +1,475 @@
+{
+  "family": "list-item",
+  "ui": "list-item",
+  "binding": "react",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Row with media, text, metadata and actions."
+  },
+  "axes": {
+    "tone": [
+      "secondary",
+      "accent",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "align": [
+      "center",
+      "start"
+    ]
+  },
+  "members": {
+    "listItem": {
+      "nativeElement": "li",
+      "defaults": {
+        "tone": "secondary",
+        "size": "md",
+        "align": "center",
+        "inset": false,
+        "truncate": false,
+        "selected": false,
+        "current": false,
+        "disabled": false,
+        "loading": false
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "disabled",
+        "loading",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "selected",
+        "current",
+        "loading",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "marker",
+        "content",
+        "start",
+        "body",
+        "label",
+        "description",
+        "end",
+        "actions"
+      ]
+    }
+  },
+  "docs": {
+    "listItem": {
+      "imports": {
+        "source": "import { ListItem, ListItemActions, ListItemBody, ListItemButton, ListItemContent, ListItemDefaultsProvider, ListItemDescription, ListItemEnd, ListItemLabel, ListItemLink, ListItemStart } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "li, or the element render returns",
+          "required": true,
+          "purpose": "The row. Carries data-ui=\"list-item\", every axis, data-selected, data-current, data-disabled, data-loading and aria-current. It is its own container, so the row reflows on its own inline size rather than the viewport."
+        },
+        {
+          "part": "marker",
+          "element": "span",
+          "required": false,
+          "purpose": "The bullet, rendered only when marker is bullet: the dot Glyph in the marker column, before content and hidden from assistive technology. A numbered marker is a counter the stylesheet writes, because it is text."
+        },
+        {
+          "part": "content",
+          "element": "div, button or a",
+          "required": true,
+          "purpose": "The box that is read, hovered, focused and — for two of the three — activated. Three elements rather than one as prop, because the three are three different accessibility trees."
+        },
+        {
+          "part": "start",
+          "element": "div",
+          "required": false,
+          "purpose": "The leading column: an icon, an avatar, a Checkbox. It is the slot and not the control, and the chooser here is also what announces a selection the row only paints."
+        },
+        {
+          "part": "body",
+          "element": "div",
+          "required": false,
+          "purpose": "The text column, and the one box in the row that may shrink — which is what lets an unbroken token break instead of pushing the metadata out of the row."
+        },
+        {
+          "part": "label",
+          "element": "div",
+          "required": false,
+          "purpose": "The title. It clips under truncate, isolates its own direction so another script does not reorder the row, and breaks a single unbroken token."
+        },
+        {
+          "part": "description",
+          "element": "div",
+          "required": false,
+          "purpose": "The lines under the title. They clip with it, never instead of it."
+        },
+        {
+          "part": "end",
+          "element": "div",
+          "required": false,
+          "purpose": "Trailing metadata that is part of what the row says — a timestamp, a count, a Badge. Below 22rem it leaves the inline axis and sits under the title."
+        },
+        {
+          "part": "actions",
+          "element": "div",
+          "required": false,
+          "purpose": "Independent targets, and a sibling of the box rather than its child: interactive content may not nest inside an a or a button."
+        }
+      ],
+      "api": [
+        {
+          "name": "tone",
+          "type": "'secondary' | 'accent' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "secondary",
+          "appliesTo": "ListItem",
+          "description": "The row ink, the wash under the pointer and the ground of a selected row. It never fills a resting row"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "ListItem",
+          "description": "The room the row gets. Falls back to the list, then the provider"
+        },
+        {
+          "name": "align",
+          "type": "'center' | 'start'",
+          "defaultValue": "center",
+          "appliesTo": "ListItem",
+          "description": "Where the leading visual and the metadata sit against a row of more than one line"
+        },
+        {
+          "name": "inset",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ListItem",
+          "description": "Takes the row inline padding away. Falls back to the list, then the provider"
+        },
+        {
+          "name": "truncate",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ListItem",
+          "description": "Clips the title and the lines under it to one line each. The whole string stays in the document"
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ListItem",
+          "description": "Mirrors a selection the page owns. The Checkbox in ListItemStart is what announces it"
+        },
+        {
+          "name": "current",
+          "type": "boolean | 'page' | 'step' | 'location' | 'date' | 'time'",
+          "defaultValue": "false",
+          "appliesTo": "ListItem",
+          "description": "The row the reader is on, written as aria-current — the one state of this shape a listitem may announce"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ListItem",
+          "description": "The row dims and refuses the activation. The attribute goes on the box, never on the li"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ListItem",
+          "description": "aria-busy on the box and the activation withdrawn. The width and the accessible name are kept"
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'ruled' | 'framed' | 'separated'",
+          "defaultValue": "—",
+          "appliesTo": "ListItem",
+          "description": "How the rows are told apart. Falls back to the list, then to plain"
+        },
+        {
+          "name": "marker",
+          "type": "'none' | 'bullet' | 'number'",
+          "defaultValue": "—",
+          "appliesTo": "ListItem",
+          "description": "What is painted in the marker column. Falls back to the list, then to none"
+        },
+        {
+          "name": "position / setSize",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "ListItem",
+          "description": "aria-posinset and aria-setsize, written only when the page knows them"
+        },
+        {
+          "name": "href",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "ListItemLink",
+          "description": "The destination of a row that is one destination, on the anchor that is the row box"
+        },
+        {
+          "name": "type",
+          "type": "'button' | 'submit' | 'reset'",
+          "defaultValue": "button",
+          "appliesTo": "ListItemButton",
+          "description": "The button own type, so a row inside a form can submit it"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Renders the wiring into another element — a router link, a heading, a label"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Reaches the native element; each part extends its own element props"
+        },
+        {
+          "name": "ListItemDefaultsProvider",
+          "type": "{ tone, size, align, inset, truncate }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets the five once for every row under it; an explicit prop still wins"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "The row is an li, and ARIA 1.2 is unusually specific about what a listitem may carry: aria-level, aria-posinset and aria-setsize are supported, aria-current and aria-busy are inherited, and aria-disabled, aria-invalid, aria-errormessage and aria-haspopup are deprecated on the role.",
+        "disabled is therefore painted from data-disabled on the row while the attribute that means it goes on the box — the native disabled on a button, aria-disabled on a link. No surveyed implementation makes the distinction; MUI writes aria-disabled on the row, where it is deprecated.",
+        "A disabled link keeps its destination in the document. aria-disabled means perceivable but not operable and leaves the element focusable, so a reader can still reach the row and hear the description that says why it is unavailable; the activation is refused instead, which covers both a pointer and Enter.",
+        "selected is painted and never announced, because aria-selected is not valid on a listitem. The control the page composes into ListItemStart — a Checkbox — is what carries the state for assistive technology, and a collection that moves a selection with the keyboard is Listbox or Table rather than this family.",
+        "current is announced, with aria-current and the token the page states. It is the one selection-shaped state the roles model lets a listitem say for itself, and page is what a navigation list wants.",
+        "position and setSize are written only when the page states them. ARIA 1.2 says both are unnecessary while every row is in the document and necessary the moment only part of the set is, so writing them always would make a filtered list disagree with itself.",
+        "ListItemActions is a sibling of the box and never its child, because interactive content may not nest inside an a or a button. A row that navigates and also deletes has to place its two targets side by side, and this is the arrangement the parts express.",
+        "A control inside ListItemActions is the page own to disable. A disabled row refuses its own box and nothing else: only the control can refuse its own interaction.",
+        "The row binds no key. Enter on a link, Enter and Space on a button, and the modified click a browser gives an anchor are the platform own behaviour, and Tab reaches the box and every control beside it.",
+        "The focus ring is drawn inside the row rather than around it, because a row runs the full width of its set: an outward ring on the first row of a framed list is drawn under the frame, and on the last row it is drawn outside the page.",
+        "Selection is said with a fill and an edge together. Every tone surface is the page own white in the high-contrast scheme, so a selection said with a fill alone is a selection that scheme cannot show.",
+        "The title isolates its own direction, so a title in another script does not reorder the row around it, and breaks a single unbroken token rather than pushing the metadata out of the row."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-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-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-regular",
+    "--slotted-line-height-md",
+    "--slotted-line-height-sm",
+    "--slotted-list-item-background",
+    "--slotted-list-item-background-active",
+    "--slotted-list-item-background-current",
+    "--slotted-list-item-background-hover",
+    "--slotted-list-item-background-selected",
+    "--slotted-list-item-body-gap",
+    "--slotted-list-item-border-color",
+    "--slotted-list-item-border-width",
+    "--slotted-list-item-color",
+    "--slotted-list-item-color-disabled",
+    "--slotted-list-item-color-muted",
+    "--slotted-list-item-control-size",
+    "--slotted-list-item-control-size-lg",
+    "--slotted-list-item-control-size-sm",
+    "--slotted-list-item-description-font-size",
+    "--slotted-list-item-font-size",
+    "--slotted-list-item-font-size-lg",
+    "--slotted-list-item-font-size-sm",
+    "--slotted-list-item-font-weight",
+    "--slotted-list-item-font-weight-current",
+    "--slotted-list-item-font-weight-selected",
+    "--slotted-list-item-gap",
+    "--slotted-list-item-gap-lg",
+    "--slotted-list-item-gap-sm",
+    "--slotted-list-item-icon-size",
+    "--slotted-list-item-icon-size-lg",
+    "--slotted-list-item-icon-size-sm",
+    "--slotted-list-item-min-block-size",
+    "--slotted-list-item-min-block-size-lg",
+    "--slotted-list-item-min-block-size-sm",
+    "--slotted-list-item-padding-block",
+    "--slotted-list-item-padding-block-lg",
+    "--slotted-list-item-padding-block-sm",
+    "--slotted-list-item-padding-inline",
+    "--slotted-list-item-padding-inline-lg",
+    "--slotted-list-item-padding-inline-sm",
+    "--slotted-list-item-radius",
+    "--slotted-radius-md",
+    "--slotted-selection-size-lg",
+    "--slotted-selection-size-md",
+    "--slotted-selection-size-sm",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-surface-raised",
+    "--slotted-surface-sunken",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-solid-active",
+    "--slotted-tone-accent-solid-hover",
+    "--slotted-tone-accent-subtle-active",
+    "--slotted-tone-accent-subtle-hover",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-danger-solid-active",
+    "--slotted-tone-danger-solid-hover",
+    "--slotted-tone-danger-subtle-active",
+    "--slotted-tone-danger-subtle-hover",
+    "--slotted-tone-danger-surface",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-border",
+    "--slotted-tone-secondary-solid-active",
+    "--slotted-tone-secondary-solid-hover",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-tone-secondary-surface",
+    "--slotted-tone-success-border",
+    "--slotted-tone-success-solid-active",
+    "--slotted-tone-success-solid-hover",
+    "--slotted-tone-success-subtle-active",
+    "--slotted-tone-success-subtle-hover",
+    "--slotted-tone-success-surface",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-border",
+    "--slotted-tone-warning-solid-active",
+    "--slotted-tone-warning-solid-hover",
+    "--slotted-tone-warning-subtle-active",
+    "--slotted-tone-warning-subtle-hover",
+    "--slotted-tone-warning-surface",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One row with every axis on it, driven by the controls below the canvas. Tab lands on the box and then on the control beside it; the family binds no key of its own.",
+      "language": "tsx",
+      "source": "<ListItem>\n  <ListItemLink href=\"/photos\">\n    <ListItemBody>\n      <ListItemLabel>Photos</ListItemLabel>\n    </ListItemBody>\n    <ListItemEnd>Yesterday</ListItemEnd>\n  </ListItemLink>\n</ListItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content-elements",
+      "title": "Three boxes, three trees",
+      "note": "A static row answers no pointer state because it promises no interaction. The other two are a real button and a real anchor, so Enter, Space and a modified click are the platform’s.",
+      "language": "tsx",
+      "source": "<ListItemContent />;\n<ListItemButton onClick={publish} />;\n<ListItemLink href=\"/photos\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anatomy",
+      "title": "Every part, and a row with almost none",
+      "note": "Every part but the box is optional, and an absent one leaves no column behind: each gap is a margin on the part rather than a track on the grid.",
+      "language": "tsx",
+      "source": "<ListItem>\n  <ListItemContent>\n    <ListItemStart>{icon}</ListItemStart>\n    <ListItemBody>\n      <ListItemLabel>Photos</ListItemLabel>\n      <ListItemDescription>128 files</ListItemDescription>\n    </ListItemBody>\n    <ListItemEnd>Yesterday</ListItemEnd>\n  </ListItemContent>\n  <ListItemActions>{remove}</ListItemActions>\n</ListItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "alignment",
+      "title": "Where the leading visual sits",
+      "note": "center is right while the block is one line and wrong as soon as it is three. start returns the mark and the metadata to the title own line, so a row of three lines reads from one corner.",
+      "language": "tsx",
+      "source": "<ListItem align=\"center\" />;\n<ListItem align=\"start\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "tone",
+      "title": "The five the theme carries",
+      "note": "A tone moves the ink, the wash under the pointer and the ground of a selected row, and never fills a resting row: forty rows each filled with a tone is a list nobody can read.",
+      "language": "tsx",
+      "source": "<ListItem tone=\"danger\">\n  <ListItemButton onClick={destroy}>Delete the workspace</ListItemButton>\n</ListItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the row paints",
+      "note": "Selection is the accent ground, the accent ink and a one-pixel edge together, because every tone surface is white in the high-contrast scheme. Current is the neutral ground with its own edge, so a row can be both at once and the selection is what shows without either of them being lost.",
+      "language": "tsx",
+      "source": "<ListItem selected />;\n<ListItem current=\"page\" />;\n<ListItem loading />;\n<ListItem disabled />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "actions",
+      "title": "Independent targets",
+      "note": "The two targets are siblings, so the row hit area stops before the button. A disabled row refuses its own box and nothing else: the control beside it is the page own to disable.",
+      "language": "tsx",
+      "source": "<ListItem>\n  <ListItemLink href={folder.href}>{folder.name}</ListItemLink>\n  <ListItemActions>\n    <Button aria-label=\"Remove\" onClick={remove} variant=\"ghost\" />\n  </ListItemActions>\n</ListItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "reflow",
+      "title": "The row answers its own width",
+      "note": "Below 22rem the metadata sits under the title and the independent targets take a line of their own, because a target never shrinks and the box beside it would shrink instead. The container is the row and not the set.",
+      "language": "css",
+      "source": "@container slotted-list-item (max-inline-size: 22rem) {\n  /* the metadata moves under the title */\n}\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "An unbroken token breaks inside the row; a translated title gives way and the timestamp does not; a title in another script keeps its own direction and leaves the row around it alone.",
+      "language": "tsx",
+      "source": "<ListItem truncate>\n  <ListItemContent>\n    <ListItemBody>\n      <ListItemLabel>{message.subject}</ListItemLabel>\n    </ListItemBody>\n  </ListItemContent>\n</ListItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "The families beside it",
+      "note": "Checkbox announces the selection the row paints, Badge carries the count, Button is the independent target, Icon is the leading visual. The row draws none of the four.",
+      "language": "tsx",
+      "source": "<ListItem selected>\n  <ListItemContent>\n    <ListItemStart>\n      <Checkbox aria-label=\"Select\" checked />\n    </ListItemStart>\n    <ListItemBody>\n      <ListItemLabel>Quarterly report</ListItemLabel>\n    </ListItemBody>\n    <ListItemEnd>\n      <Badge tone=\"accent\">3</Badge>\n    </ListItemEnd>\n  </ListItemContent>\n</ListItem>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the platform already does",
+      "note": "The family binds no key. A disabled button leaves the tab sequence, while a disabled link stays in it and refuses the activation — which is what keeps its description reachable to a reader.",
+      "language": "tsx",
+      "source": "<ListItem disabled>\n  <ListItemLink href=\"/exports\">\n    <ListItemBody>\n      <ListItemLabel>Exports</ListItemLabel>\n      <ListItemDescription>Unavailable while the index rebuilds</ListItemDescription>\n    </ListItemBody>\n  </ListItemLink>\n</ListItem>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}