<!-- Protocore Design System — List -->
# List

- **Category:** Typography (`typography`)
- **Slug:** `typography/list`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { List } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/typography/list

> Styled ordered / unordered list with tokenised spacing and optional icon bullets.

## When to use it

`List` is for **linear prose lists** — a set of peer items where order may or may not matter. When each row is a *label → value* record, use **DefinitionList** instead. When the list is a *sequence the user walks through*, use **Steps**; when items are events on a time axis, use **Timeline**.

It is server-safe and purely presentational. The icon bullets are the one flourish — they replace the marker without breaking the semantic `ul`/`ol`, so screen readers still announce a list.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | `ReactNode` | no | — | `List.Item` children. |
| `className` | `string` | no | — | — |
| `icon` | `ReactNode` | no | — | Icon that replaces the bullet for every item (unless the item sets its own). |
| `mono` | `boolean` | no | — | Render item text in the monospace family. |
| `size` | `enum` | no | `md` | Text scale: sm 14 · md 16. |
| `spacing` | `enum` | no | `md` | Gap between items: sm 4 · md 8 · lg 12. |
| `style` | `CSSProperties` | no | — | — |
| `type` | `enum` | no | `unordered` | `unordered` renders a `ul` with markers; `ordered` renders an `ol` with numbers. |
| `withPadding` | `boolean` | no | `true` | Indent the list so markers/icons sit inside the content box. |

## Examples

### Basics

`List` renders a real `ul` (or `ol` when `type="ordered"`) with tokenised spacing and muted mono numerals. Compose rows with `List.Item`. Use it for prose bullet lists — feature rundowns, requirements, changelog points.

```tsx
import { List } from "@protocore/pds";

export default function ListBasics() {
  return (
    <List>
      <List.Item>Ingest the raw transaction feed</List.Item>
      <List.Item>Normalise currencies to the base ledger</List.Item>
      <List.Item>Reconcile against the bank statement</List.Item>
      <List.Item>Settle the cleared batch</List.Item>
    </List>
  );
}
```

### Icon bullets

Set a list-level `icon` to replace the bullet on every item with a glyph — a check mark for a done-list, a dot for a feature list. Each item can override with its own `icon`, so a single list can mix check and cross marks. The icon slot is decorative (`aria-hidden`); the item text carries the meaning.

```tsx
import { List } from "@protocore/pds";
import { Check, X } from "lucide-react";

export default function ListIcons() {
  return (
    <List icon={<Check />} spacing="md">
      <List.Item>Multi-tenant CMS wired</List.Item>
      <List.Item>Static export to S3 + CloudFront</List.Item>
      <List.Item icon={<X />}>Publish → rebuild webhook (pending)</List.Item>
      <List.Item>Per-tenant access control</List.Item>
    </List>
  );
}
```

## Usage

**Do**

- Use `ordered` when the sequence carries meaning; `unordered` otherwise.
- Use an `icon` bullet to signal item status (check / cross) at a glance.
- Keep item text meaningful on its own — the icon is decoration.

**Don't**

- Don't use `List` for label/value records — that's DefinitionList.
- Don't rely on a check vs cross icon alone to convey pass/fail without text.
- Don't nest interactive controls expecting list styling to lay them out — compose Stack.

## Accessibility

**Notes**

- Always renders a semantic `ul` or `ol` with `li` children, so assistive tech announces the list and its length.
- Icon bullets are `aria-hidden` decoration; the item's text is its accessible content.
- Ordered lists preserve native numbering semantics — the number is exposed by the platform, not faked in text.

## Related

`text`, `definition-list`, `steps`, `timeline`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/