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

package/dist/docs/list-item.md

@@ -0,0 +1,240 @@
+<!-- index: ./index.md -->
+# list-item
+
+`data-ui="list-item"` · Row with media, text, metadata and actions.
+
+## Import
+
+```tsx
+import { ListItem, ListItemActions, ListItemBody, ListItemButton, ListItemContent, ListItemDefaultsProvider, ListItemDescription, ListItemEnd, ListItemLabel, ListItemLink, ListItemStart } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<ListItem>
+  <ListItemLink href="/photos">
+    <ListItemBody>
+      <ListItemLabel>Photos</ListItemLabel>
+    </ListItemBody>
+    <ListItemEnd>Yesterday</ListItemEnd>
+  </ListItemLink>
+</ListItem>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | li, or the element render returns | yes |
+| `marker` | span | no |
+| `content` | div, button or a | yes |
+| `start` | div | no |
+| `body` | div | no |
+| `label` | div | no |
+| `description` | div | no |
+| `end` | div | no |
+| `actions` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `'secondary' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | secondary | ListItem | The row ink, the wash under the pointer and the ground of a selected row. It never fills a resting row |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | ListItem | The room the row gets. Falls back to the list, then the provider |
+| `align` | `'center' \| 'start'` | center | ListItem | Where the leading visual and the metadata sit against a row of more than one line |
+| `inset` | `boolean` | false | ListItem | Takes the row inline padding away. Falls back to the list, then the provider |
+| `truncate` | `boolean` | false | ListItem | Clips the title and the lines under it to one line each. The whole string stays in the document |
+| `selected` | `boolean` | false | ListItem | Mirrors a selection the page owns. The Checkbox in ListItemStart is what announces it |
+| `current` | `boolean \| 'page' \| 'step' \| 'location' \| 'date' \| 'time'` | false | ListItem | The row the reader is on, written as aria-current — the one state of this shape a listitem may announce |
+| `disabled` | `boolean` | false | ListItem | The row dims and refuses the activation. The attribute goes on the box, never on the li |
+| `loading` | `boolean` | false | ListItem | aria-busy on the box and the activation withdrawn. The width and the accessible name are kept |
+| `variant` | `'plain' \| 'ruled' \| 'framed' \| 'separated'` | — | ListItem | How the rows are told apart. Falls back to the list, then to plain |
+| `marker` | `'none' \| 'bullet' \| 'number'` | — | ListItem | What is painted in the marker column. Falls back to the list, then to none |
+| `position / setSize` | `number` | — | ListItem | aria-posinset and aria-setsize, written only when the page knows them |
+| `href` | `string` | — | ListItemLink | The destination of a row that is one destination, on the anchor that is the row box |
+| `type` | `'button' \| 'submit' \| 'reset'` | button | ListItemButton | The button own type, so a row inside a form can submit it |
+| `render` | `(props) => ReactNode` | — | every part | Renders the wiring into another element — a router link, a heading, a label |
+| `ref` | `Ref<HTMLElement>` | — | every part | Reaches the native element; each part extends its own element props |
+| `ListItemDefaultsProvider` | `{ tone, size, align, inset, truncate }` | — | a subtree | Sets the five once for every row under it; an explicit prop still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `tone` | `secondary`, `accent`, `success`, `warning`, `danger` | `secondary` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `align` | `center`, `start` | `center` |
+
+## Rules
+
+- 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
+
+### Three boxes, three trees
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ListItemContent />;
+<ListItemButton onClick={publish} />;
+<ListItemLink href="/photos" />;
+```
+
+### Every part, and a row with almost none
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ListItem>
+  <ListItemContent>
+    <ListItemStart>{icon}</ListItemStart>
+    <ListItemBody>
+      <ListItemLabel>Photos</ListItemLabel>
+      <ListItemDescription>128 files</ListItemDescription>
+    </ListItemBody>
+    <ListItemEnd>Yesterday</ListItemEnd>
+  </ListItemContent>
+  <ListItemActions>{remove}</ListItemActions>
+</ListItem>;
+```
+
+### Where the leading visual sits
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ListItem align="center" />;
+<ListItem align="start" />;
+```
+
+### The five the theme carries
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ListItem tone="danger">
+  <ListItemButton onClick={destroy}>Delete the workspace</ListItemButton>
+</ListItem>;
+```
+
+### Every state the row paints
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ListItem selected />;
+<ListItem current="page" />;
+<ListItem loading />;
+<ListItem disabled />;
+```
+
+### Independent targets
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ListItem>
+  <ListItemLink href={folder.href}>{folder.name}</ListItemLink>
+  <ListItemActions>
+    <Button aria-label="Remove" onClick={remove} variant="ghost" />
+  </ListItemActions>
+</ListItem>;
+```
+
+### The row answers its own width
+
+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.
+
+Excerpt — not a complete module
+
+```css
+@container slotted-list-item (max-inline-size: 22rem) {
+  /* the metadata moves under the title */
+}
+```
+
+### Content the family did not choose
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ListItem truncate>
+  <ListItemContent>
+    <ListItemBody>
+      <ListItemLabel>{message.subject}</ListItemLabel>
+    </ListItemBody>
+  </ListItemContent>
+</ListItem>;
+```
+
+### The families beside it
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ListItem selected>
+  <ListItemContent>
+    <ListItemStart>
+      <Checkbox aria-label="Select" checked />
+    </ListItemStart>
+    <ListItemBody>
+      <ListItemLabel>Quarterly report</ListItemLabel>
+    </ListItemBody>
+    <ListItemEnd>
+      <Badge tone="accent">3</Badge>
+    </ListItemEnd>
+  </ListItemContent>
+</ListItem>;
+```
+
+### What the platform already does
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ListItem disabled>
+  <ListItemLink href="/exports">
+    <ListItemBody>
+      <ListItemLabel>Exports</ListItemLabel>
+      <ListItemDescription>Unavailable while the index rebuilds</ListItemDescription>
+    </ListItemBody>
+  </ListItemLink>
+</ListItem>;
+```

package/dist/docs/list.json

@@ -0,0 +1,325 @@
+{
+  "family": "list",
+  "ui": "list",
+  "binding": "react",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Vertical list of items with sections."
+  },
+  "axes": {
+    "variant": [
+      "plain",
+      "ruled",
+      "framed",
+      "separated"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "marker": [
+      "none",
+      "bullet",
+      "number"
+    ]
+  },
+  "members": {
+    "list": {
+      "nativeElement": "ul",
+      "defaults": {
+        "variant": "plain",
+        "size": "md",
+        "marker": "none",
+        "ordered": false,
+        "inset": false,
+        "loading": false,
+        "level": "3",
+        "sticky": false
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "loading",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "section",
+        "section-label",
+        "section-list",
+        "empty"
+      ]
+    }
+  },
+  "docs": {
+    "list": {
+      "imports": {
+        "source": "import { List, ListDefaultsProvider, ListEmpty, ListSection } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "ul or ol, or the element render returns",
+          "required": true,
+          "purpose": "The set. Carries data-ui=\"list\", the three axes, data-inset, data-loading and role=\"list\" — which is not redundant, because the family draws its own marker and Safari drops list semantics when CSS removes one."
+        },
+        {
+          "part": "section",
+          "element": "li",
+          "required": false,
+          "purpose": "One group: the li that holds a heading and the rows under it, which is the grouping HTML already has."
+        },
+        {
+          "part": "section-label",
+          "element": "h1 to h6, or a div",
+          "required": false,
+          "purpose": "The group name. It carries the id the nested list names itself by, and data-sticky when it has to hold still while its own rows scroll past."
+        },
+        {
+          "part": "section-list",
+          "element": "ul or ol",
+          "required": false,
+          "purpose": "The rows of one group. It takes the element of the set around it, carries role=\"list\" for the same reason the root does, and names itself by the heading above it."
+        },
+        {
+          "part": "empty",
+          "element": "li",
+          "required": false,
+          "purpose": "What the set says when it holds nothing. Inside the list, so a reader hears the message rather than \"zero items\" and then silence."
+        }
+      ],
+      "api": [
+        {
+          "name": "variant",
+          "type": "'plain' | 'ruled' | 'framed' | 'separated'",
+          "defaultValue": "plain",
+          "appliesTo": "List",
+          "description": "How the rows are told apart: by rhythm, by a rule, by a box around them, or by a surface each"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "List",
+          "description": "The room a row gets. Density is the application's choice; this is this list's"
+        },
+        {
+          "name": "marker",
+          "type": "'none' | 'bullet' | 'number'",
+          "defaultValue": "none",
+          "appliesTo": "List",
+          "description": "What is painted in the marker column. The family draws it, so it never disappears with the semantics"
+        },
+        {
+          "name": "ordered",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "List",
+          "description": "Renders an ol, so the reading order of the set is a fact rather than a look"
+        },
+        {
+          "name": "inset",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "List",
+          "description": "Takes the rows inline padding away, for a list inside a box that already pads its content"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "List",
+          "description": "Writes aria-busy on the set. What stands in for the rows is Skeleton, composed by the page"
+        },
+        {
+          "name": "level",
+          "type": "'none' | '1' | '2' | '3' | '4' | '5' | '6'",
+          "defaultValue": "3",
+          "appliesTo": "ListSection",
+          "description": "The heading a group name is set as. none renders a div and announces no heading"
+        },
+        {
+          "name": "sticky",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ListSection",
+          "description": "Keeps a group name in place while its own rows scroll past it"
+        },
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "ListSection",
+          "description": "The group name, which the nested list is named by"
+        },
+        {
+          "name": "labelProps / listProps",
+          "type": "HTMLAttributes",
+          "defaultValue": "—",
+          "appliesTo": "ListSection",
+          "description": "Reach the heading and the nested list, for an id or a class the page owns"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "List, ListSection, ListEmpty",
+          "description": "Renders the wiring into another element — a nav, a router own list"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Reaches the native element; each part extends its own element props"
+        },
+        {
+          "name": "aria-label / aria-labelledby",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "List",
+          "description": "The set own name, passed through to the element. The family adds no label of its own"
+        },
+        {
+          "name": "ListDefaultsProvider",
+          "type": "{ variant, size, marker, inset }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets the four once for every list under it; an explicit prop still wins"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "The Authoring Practices publish no pattern for a static list. They name Listbox and Grid for interactive collections and nothing between those and plain content, so what governs here is HTML and the ARIA roles model.",
+        "role=\"list\" is written on the root and on every nested group, and it is not redundant. The family draws its own marker — a row is a content box beside its independent targets, and CSS has no display that is both list-item and a grid — and Safari with VoiceOver drops list semantics the moment CSS removes the marker. A role the page wrote itself, a menu or a listbox it is wiring, survives untouched.",
+        "A group is an li holding a heading and a nested list, which is the grouping HTML already has, and the nested list names itself by that heading. A reader who lands inside a group is told which group it is; the four surveyed libraries that ship groups each leave the heading loose among the rows instead.",
+        "loading writes aria-busy on the set, which ARIA 1.2 §5.2.6 asks of a container whose rows have not arrived yet. It draws no spinner and no placeholder: Skeleton owns that geometry and goes inside the rows.",
+        "The empty message is an li inside the list. Outside it, a reader hears \"list, zero items\" and then nothing, and the words fall outside the box a framed set paints.",
+        "The set binds no key. Arrows, Home, End and typeahead belong to a collection, and a role=\"list\" that answers them is the invented keyboard the feature guide refuses — that model is Listbox and Table in wave 6. The cost is that a hundred rows are a hundred Tab presses, which is the platform own behaviour for any page of links; a nav the page labels is what a screen reader jumps by instead.",
+        "The set holds no state a consumer can own, so it emits no event and declares no state model. A selection is painted by the row and announced by the Checkbox the page composes into it."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-semibold",
+    "--slotted-line-height-sm",
+    "--slotted-list-background",
+    "--slotted-list-border-color",
+    "--slotted-list-border-width",
+    "--slotted-list-empty-color",
+    "--slotted-list-empty-padding",
+    "--slotted-list-empty-padding-lg",
+    "--slotted-list-empty-padding-sm",
+    "--slotted-list-gap",
+    "--slotted-list-gap-lg",
+    "--slotted-list-gap-sm",
+    "--slotted-list-padding-inline",
+    "--slotted-list-padding-inline-lg",
+    "--slotted-list-padding-inline-sm",
+    "--slotted-list-radius",
+    "--slotted-list-section-color",
+    "--slotted-list-section-font-size",
+    "--slotted-list-section-font-weight",
+    "--slotted-list-section-letter-spacing",
+    "--slotted-list-section-padding-block",
+    "--slotted-list-section-padding-block-lg",
+    "--slotted-list-section-padding-block-sm",
+    "--slotted-radius-md",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-space-8",
+    "--slotted-space-9",
+    "--slotted-surface",
+    "--slotted-text-muted",
+    "--slotted-z-index-sticky"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One set with every axis on it, driven by the controls below the canvas. The rows are ListItem, a family of its own; what this page decides is how they are told apart.",
+      "language": "tsx",
+      "source": "<List aria-label=\"Folders\" variant=\"ruled\">\n  <ListItem>\n    <ListItemLink href=\"/photos\">\n      <ListItemBody>\n        <ListItemLabel>Photos</ListItemLabel>\n      </ListItemBody>\n      <ListItemEnd>128</ListItemEnd>\n    </ListItemLink>\n  </ListItem>\n</List>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variant",
+      "title": "Telling the rows apart",
+      "note": "Four words, and they are accordion’s four so that two families cannot mean different things by one of them. Only separated spends a gap; the other three separate with a line or with nothing.",
+      "language": "tsx",
+      "source": "<List variant=\"plain\" />;\n<List variant=\"ruled\" />;\n<List variant=\"framed\" />;\n<List variant=\"separated\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "marker",
+      "title": "The mark, and the order",
+      "note": "The element carries the reading order and the axis carries the painted mark, which is why an ordered set can paint its own badges and still read in order. The bullet is drawn geometry rather than a character.",
+      "language": "tsx",
+      "source": "<List marker=\"bullet\" />;\n<List marker=\"number\" ordered />;\n<List ordered />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sections",
+      "title": "Groups",
+      "note": "A group is an li holding a heading and a nested list, and the nested list names itself by that heading. sticky keeps the name in place while its own rows scroll past it.",
+      "language": "tsx",
+      "source": "<List aria-label=\"Library\" variant=\"ruled\">\n  <ListSection label=\"Folders\" level=\"3\" sticky>\n    {folderRows}\n  </ListSection>\n</List>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "inset",
+      "title": "A set inside a padded box",
+      "note": "inset takes the rows inline padding away so the titles line up with the box around them. The rule and the hover fill still run edge to edge, which is the half disableGutters leaves out elsewhere.",
+      "language": "tsx",
+      "source": "<List aria-label=\"Members\" inset variant=\"ruled\">\n  {memberRows}\n</List>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Loading, and empty",
+      "note": "loading writes aria-busy and draws nothing: Skeleton stands in for the rows. The empty message is an li inside the set, so a reader hears it rather than hearing zero items and then silence.",
+      "language": "tsx",
+      "source": "<List aria-label=\"Folders\" loading variant=\"ruled\">\n  {placeholderRows}\n</List>;\n\n<List aria-label=\"Results\" variant=\"framed\">\n  <ListEmpty>No matches</ListEmpty>\n</List>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A page of a larger set says where the reader is with position and setSize, and only then. A set in another script mirrors its marker column, its inset and its metadata, because every rule is a logical property.",
+      "language": "tsx",
+      "source": "<List aria-label=\"Results 41 to 43 of 128\" variant=\"ruled\">\n  <ListItem position={41} setSize={128} />\n</List>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "The families beside it",
+      "note": "The set supplies the box and the rhythm. Checkbox announces the selection a row paints, Badge carries a count, and ListDefaultsProvider sets the four axes once for a whole application.",
+      "language": "tsx",
+      "source": "<ListDefaultsProvider size=\"sm\" variant=\"ruled\">\n  <Inbox />\n</ListDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "The role, and the landmark",
+      "note": "The family writes role=\"list\" because it draws its own marker, and never over a role the page wrote itself. A nav is the page decision, so the family writes none and the row says which one is current.",
+      "language": "tsx",
+      "source": "<nav aria-label=\"Sections\">\n  <List>\n    <ListItem current=\"page\">\n      <ListItemLink href=\"/billing\">Billing</ListItemLink>\n    </ListItem>\n  </List>\n</nav>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}