@mitcsutt/kiln-ui 0.1.0

package/skills/layout-composition/references/app-shell.md

@@ -0,0 +1,141 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# AppShell
+
+> The frame of an app screen. A header, an optional sidebar, the main region, a footer and a phone-only bottom bar.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/layout/app-shell
+
+`AppShell` is the outermost frame of an app: landmarks in the right order, a skip link, a sticky header, and a hand-over between a phone's bottom bar and a desktop's sidebar or header nav. These docs are an `AppShell`.
+
+```tsx
+import {
+  AppShell,
+  ArrowRightIcon,
+  BottomNav,
+  CircleCheckIcon,
+  Container,
+  Heading,
+  Inline,
+  NavLinks,
+  SearchIcon,
+  Stack,
+  SystemIcon,
+  Text,
+} from '@mitcsutt/kiln-ui'
+
+const SECTIONS = ['Departures', 'Routes', 'Tickets', 'Account']
+const ICONS = [
+  <ArrowRightIcon key="d" />,
+  <SearchIcon key="r" />,
+  <CircleCheckIcon key="t" />,
+  <SystemIcon key="a" />,
+]
+
+export default function Usage() {
+  return (
+    <AppShell navBreakpoint="md">
+      <AppShell.Header>
+        <Container width="full">
+          <Inline justify="between">
+            <Text weight="strong">Bayline</Text>
+            <NavLinks label="Main" size="sm" hideBelow="md">
+              {SECTIONS.map((section, index) => (
+                <NavLinks.Item
+                  key={section}
+                  href={`#${section.toLowerCase()}`}
+                  active={index === 0}
+                >
+                  {section}
+                </NavLinks.Item>
+              ))}
+            </NavLinks>
+          </Inline>
+        </Container>
+      </AppShell.Header>
+      <AppShell.Main>
+        <Container width="text">
+          <Stack gap={4}>
+            <Heading level={2} size="2xl">
+              Departures from Harbour Square
+            </Heading>
+            {Array.from({ length: 12 }, (_, index) => (
+              <Text key={index}>
+                {String(7 + Math.floor(index / 2)).padStart(2, '0')}:{index % 2 ? '40' : '10'}{' '}
+                Coastal line to Kelso Bay
+              </Text>
+            ))}
+          </Stack>
+        </Container>
+      </AppShell.Main>
+      <AppShell.BottomBar>
+        <BottomNav position="static" hideAbove="md" label="Main">
+          {SECTIONS.map((section, index) => (
+            <BottomNav.Item
+              key={section}
+              href={`#${section.toLowerCase()}`}
+              icon={ICONS[index]}
+              label={section}
+              active={index === 0}
+            />
+          ))}
+        </BottomNav>
+      </AppShell.BottomBar>
+    </AppShell>
+  )
+}
+```
+
+The window above scrolls; narrow it below `md` and the header links give way to the bottom bar.
+
+## Slots
+
+`AppShell.Header`, `AppShell.Sidebar`, `AppShell.Main`, `AppShell.Footer` and `AppShell.BottomBar` place themselves, so their order in JSX doesn't affect the layout. Keep it the same as the reading order anyway: header, sidebar, main, footer, bottom bar.
+
+- **Header** is sticky by default (`sticky={false}` to scroll it away). Put a `Container` and an `Inline` inside.
+- **Sidebar** appears from `navBreakpoint` up. It sits at the start of the main region (`side="end"` for the other side), scrolls on its own, and stays below the header.
+- **Main** is the `<main>` landmark and the skip link's target.
+- **BottomBar** is pinned to the bottom of the viewport below `navBreakpoint`, and pads for the phone's home indicator.
+
+## Navigation hand-over
+
+`navBreakpoint` (`md` or `lg`, default `lg`) is the one width where phone navigation gives way to desktop navigation, so there's never a width with neither. Pair it with the same value on `BottomNav hideAbove` and the header's `NavLinks hideBelow`.
+
+## API
+
+`AppShellProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `skipLinkLabel` | `string` | `"Skip to content"` | Text of the skip link rendered before everything else. Default "Skip to content". |
+| `navBreakpoint` | `'md' \| 'lg'` |  | Where navigation hands over from phone to desktop: from this breakpoint up the `Sidebar` appears and the `BottomBar` is removed, so there is never a width with neither. `md` (48em) or `lg` (64em, default). Pair it with the same value on `BottomNav hideAbove` and header `NavLinks hideBelow`. |
+| `mainId` | `string` |  | Id given to `AppShell.Main` (the skip link target). Generated when omitted. |
+
+Also accepts every prop of `HTMLAttributes<HTMLDivElement>`.
+
+`AppShellHeaderProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sticky` | `boolean` | `true` | Stick to the top of the viewport while scrolling. Default `true`. |
+
+Also accepts every prop of `HTMLAttributes<HTMLElement>`.
+
+`AppShellSidebarProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side` | `'start' \| 'end'` | `start` | Which side of Main it sits on. Logical, so it follows writing direction. Default `start`. |
+
+Also accepts every prop of `HTMLAttributes<HTMLElement>`.
+
+### Component tokens
+
+Set these in a theme, or on one element, to change this component without touching the rest.
+
+| Token | Default and use |
+| --- | --- |
+| `--app-shell-header-height` | minimum header height, also the sidebar's sticky offset (default: control-lg + space-4) |
+| `--app-shell-sidebar-width` | default 16rem |
+| `--app-shell-header-bg` | default var(--color-canvas) — opaque, never glass |
+| `--app-shell-bar-rule` | rule under the header / above the bottom bar (default var(--color-line-strong): these are the frame's edges) |

package/skills/layout-composition/references/aspect-ratio.md

@@ -0,0 +1,49 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# AspectRatio
+
+> A frame that keeps its proportions, for images, video, maps and charts.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/layout/aspect-ratio
+
+`AspectRatio` holds a ratio as its width changes. Its child (an image, a video, an iframe, an SVG) fills it and is cropped with `object-fit: cover`. It has no edge or radius of its own: wrap it in `Media` or a `Card` for those.
+
+```tsx
+import { AspectRatio, Grid } from '@mitcsutt/kiln-ui'
+
+function Chart({ label }: { label: string }) {
+  return (
+    <svg viewBox="0 0 160 90" role="img" aria-label={label}>
+      <rect width="160" height="90" fill="var(--color-surface-sunken)" />
+      <path
+        d="M0 70 L40 52 L80 60 L120 28 L160 36"
+        fill="none"
+        stroke="var(--color-accent)"
+        strokeWidth="3"
+      />
+    </svg>
+  )
+}
+
+export default function Usage() {
+  return (
+    <Grid columns={{ base: 1, sm: 3 }} gap={4}>
+      {(['16/9', '4/3', '1/1'] as const).map((ratio) => (
+        <AspectRatio key={ratio} ratio={ratio}>
+          <Chart label={`Passengers per hour, framed ${ratio}`} />
+        </AspectRatio>
+      ))}
+    </Grid>
+  )
+}
+```
+
+## API
+
+`AspectRatioProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ratio` | `AspectRatioPreset \| number` | `16/9` | Width ÷ height, as a preset or a number (e.g. `1.91`). Default `16/9`. |
+
+Also accepts every prop of `HTMLAttributes<HTMLDivElement>`.

package/skills/layout-composition/references/box.md

@@ -0,0 +1,49 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Box
+
+> Padding, a surface and an edge, and nothing else. The escape hatch when no other layout fits.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/layout/box
+
+`Box` adds padding, a background surface, a border and a radius to its content. Reach for `Stack`, `Inline` or `Grid` to arrange things, and for `Card` when something is a self-contained object. `Box` is for the wells and frames left over.
+
+```tsx
+import { Box, Stack, Text } from '@mitcsutt/kiln-ui'
+
+export default function Usage() {
+  return (
+    <Stack gap={4}>
+      <Box padding={{ base: 4, md: 5 }} surface="sunken" radius="surface">
+        <Text>Sunken: a well for secondary content.</Text>
+      </Box>
+      <Box padding={5} border radius="surface">
+        <Text>Bordered: a hairline frame.</Text>
+      </Box>
+      <Box padding={5} surface="inverse" radius="surface">
+        <Text>Inverse: colour roles flip inside.</Text>
+      </Box>
+    </Stack>
+  )
+}
+```
+
+`surface="inverse"` flips the colour roles inside, like an inverse `Section`.
+
+## API
+
+`BoxProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `padding` | `Responsive<Space>` |  | Padding on every side. Responsive. |
+| `paddingX` | `Responsive<Space>` |  | Inline (left/right) padding; overrides `padding` on that axis. Responsive. |
+| `paddingY` | `Responsive<Space>` |  | Block (top/bottom) padding; overrides `padding` on that axis. Responsive. |
+| `surface` | `'none' \| 'surface' \| 'canvas' \| 'sunken' \| 'raised' \| 'inverse'` |  | Background fill. `inverse` also re-points ink and line colours for its children. |
+| `border` | `boolean` |  | Hairline border in `--color-line`. One edge treatment per element — a border *or* a fill. |
+| `radius` | `'none' \| 'surface' \| 'field' \| 'media'` |  | Corner radius, by role. |
+| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'li' \| 'span'` |  |  |
+| `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
+| `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
+
+Also accepts every prop of `HTMLAttributes<HTMLElement>`.

package/skills/layout-composition/references/checkout.md

@@ -0,0 +1,124 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Checkout
+
+> A short checkout with the order summary beside the form, choice cards for collection, and a total that lines up.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/patterns/checkout
+
+A checkout asks for as little as it can, shows the cost before the button that commits to it, and says what happens next. The order summary sits beside the form on wide screens and below it on a phone.
+
+```tsx
+import {
+  Amount,
+  Button,
+  ChoiceCardsField,
+  Container,
+  DataList,
+  Divider,
+  Heading,
+  Inline,
+  List,
+  Section,
+  Split,
+  Stack,
+  Text,
+  TextField,
+} from '@mitcsutt/kiln-ui'
+
+const BASKET = [
+  { name: 'Annual pass', detail: 'Unlimited 45-minute rides', price: 96 },
+  { name: 'Helmet, medium', detail: 'Collect at Harbour Square', price: 24.5 },
+] as const
+
+const subtotal = BASKET.reduce((sum, item) => sum + item.price, 0)
+
+export default function Checkout() {
+  return (
+    <Section space={7}>
+      <Container width="content">
+        <Split ratio="7/5" gap={8}>
+          <Stack gap={6}>
+            <Heading level={2} size="2xl">
+              Checkout
+            </Heading>
+            <TextField
+              label="Email"
+              type="email"
+              autoComplete="email"
+              placeholder="ines@example.com"
+            />
+            <ChoiceCardsField
+              label="Collection"
+              type="single"
+              defaultValue="station"
+              columns={{ base: 1, sm: 2 }}
+              options={[
+                {
+                  value: 'station',
+                  label: 'Collect at a station',
+                  description: 'Ready from tomorrow, 08:00',
+                  meta: 'Free',
+                },
+                {
+                  value: 'post',
+                  label: 'Post it to me',
+                  description: 'Two to three working days',
+                  meta: '£3.20',
+                },
+              ]}
+            />
+            <TextField
+              label="Discount code"
+              optional
+              description="From your employer's cycle scheme, if you have one."
+            />
+          </Stack>
+          <Stack gap={5}>
+            <Text weight="strong">Your order</Text>
+            <List divided>
+              {BASKET.map((item) => (
+                <List.Item key={item.name}>
+                  <List.Content>
+                    <Text weight="medium">{item.name}</Text>
+                    <List.Description>{item.detail}</List.Description>
+                  </List.Content>
+                  <List.Trailing>
+                    <Amount value={item.price} currency="GBP" />
+                  </List.Trailing>
+                </List.Item>
+              ))}
+            </List>
+            <Divider />
+            <DataList orientation="horizontal">
+              <DataList.Item label="Subtotal">
+                <Amount value={subtotal} currency="GBP" />
+              </DataList.Item>
+              <DataList.Item label="Collection">Free</DataList.Item>
+            </DataList>
+            <Inline justify="between" align="baseline">
+              <Text weight="strong">Total</Text>
+              <Amount value={subtotal} currency="GBP" size="2xl" />
+            </Inline>
+            <Button fullWidth size="lg">
+              Pay £120.50
+            </Button>
+            <Text size="sm" tone="muted">
+              Your pass starts the day you collect it, not the day you pay.
+            </Text>
+          </Stack>
+        </Split>
+      </Container>
+    </Section>
+  )
+}
+```
+
+## What it's made of
+
+- **`Split ratio="7/5"`**: form first in reading order, summary second, so the summary follows the form when the split stacks.
+- **`ChoiceCardsField`** for the collection choice, because each option carries a description and a price worth comparing. Use `RadioGroupField` for options that are just labels.
+- **`TextField optional`** marks the one optional field, rather than starring every required one.
+- **`List`** with `List.Trailing` amounts for the basket, and **`DataList`** for subtotal lines.
+- **`Amount`** formats every price with the currency and tabular figures, and the total uses a bigger step so it reads first.
+- **The button says the amount.** "Pay £120.50" leaves no doubt about what pressing it does.

package/skills/layout-composition/references/container.md

@@ -0,0 +1,59 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Container
+
+> Centres content at a readable maximum width, with a fluid gutter outside it.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/layout/container
+
+`Container` sets a maximum width and centres its content. The gutter sits _outside_ the width, so `width="text"` is a true reading measure at any screen size.
+
+```tsx
+import { Container, Stack, Text } from '@mitcsutt/kiln-ui'
+
+export default function Usage() {
+  return (
+    <Stack gap={4}>
+      {(['narrow', 'text', 'content'] as const).map((width) => (
+        <Container key={width} width={width}>
+          <Text size="sm" tone="muted">
+            width=&quot;{width}&quot;: the timetable for the coastal line, laid out to this width.
+          </Text>
+        </Container>
+      ))}
+    </Stack>
+  )
+}
+```
+
+| `width`   | Max width | For                                 |
+| --------- | --------- | ----------------------------------- |
+| `narrow`  | 32rem     | sign-in, short forms, confirmations |
+| `text`    | 42rem     | articles and long reading           |
+| `content` | 68rem     | most pages (the default)            |
+| `wide`    | 84rem     | dashboards and wide tables          |
+| `full`    | 100%      | edge to edge, inside the gutter     |
+
+Pass `gutter={false}` when the parent already pads its content.
+
+## API
+
+`ContainerProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `width` | `'content' \| 'narrow' \| 'text' \| 'wide' \| 'full'` |  | Maximum content width: `narrow` 32rem · `text` 42rem (prose measure) · `content` 68rem (default) · `wide` 84rem · `full` (no maximum). |
+| `gutter` | `boolean` | `true` | Keep the fluid page gutter on either side. Default `true`. |
+| `as` | `'div' \| 'section' \| 'article' \| 'header' \| 'footer' \| 'main' \| 'nav'` |  |  |
+| `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
+| `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
+
+Also accepts every prop of `HTMLAttributes<HTMLElement>`.
+
+### Component tokens
+
+Set these in a theme, or on one element, to change this component without touching the rest.
+
+| Token | Default and use |
+| --- | --- |
+| `--container-gutter` | default var(--gutter) (fluid, from foundation.css) |

package/skills/layout-composition/references/dashboard.md

@@ -0,0 +1,163 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Dashboard
+
+> A week of operations at a glance, built from stats, a table and a list. No tiles, no gradients, no cards that don't need to be cards.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/patterns/dashboard
+
+A dashboard's hero is the subject's most characteristic thing: here, the docking stations and which ones need a van. The figures above it are typographic `Stat`s on a hairline rule rather than three identical tiles with icons in tinted circles.
+
+```tsx
+import {
+  Badge,
+  Button,
+  Container,
+  Grid,
+  Inline,
+  List,
+  Meter,
+  Section,
+  SectionHeader,
+  Split,
+  Stack,
+  Stat,
+  StatusDot,
+  Table,
+  Text,
+} from '@mitcsutt/kiln-ui'
+
+const STATIONS = [
+  { name: 'Harbour Square', bikes: 18, docks: 24, status: 'ok' },
+  { name: 'Northpoint Library', bikes: 3, docks: 16, status: 'low' },
+  { name: 'Kelso Bay Pier', bikes: 11, docks: 20, status: 'ok' },
+  { name: 'Ferry Lane', bikes: 0, docks: 12, status: 'empty' },
+  { name: 'Old Quay Market', bikes: 9, docks: 14, status: 'ok' },
+] as const
+
+const STATUS = {
+  ok: { tone: 'positive', label: 'Stocked' },
+  low: { tone: 'caution', label: 'Running low' },
+  empty: { tone: 'critical', label: 'Empty' },
+} as const
+
+export default function Dashboard() {
+  return (
+    <Section space={7}>
+      <Container width="wide">
+        <Stack gap={7}>
+          <SectionHeader
+            level={2}
+            title="This week at Northpoint Cycle Hire"
+            description="Monday 13 to Sunday 19 October"
+            actions={
+              <Inline gap={3}>
+                <Button variant="outline" tone="neutral">
+                  Export CSV
+                </Button>
+                <Button>Schedule a rebalance</Button>
+              </Inline>
+            }
+          />
+          <Grid columns={{ base: 1, sm: 3 }} gap={6}>
+            <Stat
+              label="Rides"
+              value="2,418"
+              delta={{ value: '9%', direction: 'up', tone: 'positive' }}
+              rule
+            />
+            <Stat
+              label="Bikes in service"
+              value="164"
+              delta={{ value: '6', direction: 'down', tone: 'critical' }}
+              rule
+            />
+            <Stat
+              label="Revenue"
+              value="£6,935"
+              delta={{ value: '£410', direction: 'up', tone: 'positive' }}
+              rule
+            />
+          </Grid>
+          <Split ratio="7/5" gap={7}>
+            <Stack gap={4}>
+              <Text weight="strong">Docking stations</Text>
+              <Table density="compact" label="Docking stations">
+                <Table.Head>
+                  <Table.Row>
+                    <Table.HeaderCell>Station</Table.HeaderCell>
+                    <Table.HeaderCell numeric>Bikes</Table.HeaderCell>
+                    <Table.HeaderCell hideBelow="sm">Occupancy</Table.HeaderCell>
+                    <Table.HeaderCell>Status</Table.HeaderCell>
+                  </Table.Row>
+                </Table.Head>
+                <Table.Body>
+                  {STATIONS.map((station) => (
+                    <Table.Row key={station.name}>
+                      <Table.Cell rowHeader>{station.name}</Table.Cell>
+                      <Table.Cell numeric>
+                        {station.bikes} / {station.docks}
+                      </Table.Cell>
+                      <Table.Cell hideBelow="sm">
+                        <Meter
+                          value={station.bikes}
+                          max={station.docks}
+                          low={station.docks * 0.25}
+                          optimum={station.docks * 0.6}
+                          size="sm"
+                          label={`${station.name} occupancy`}
+                        />
+                      </Table.Cell>
+                      <Table.Cell>
+                        <StatusDot
+                          tone={STATUS[station.status].tone}
+                          label={STATUS[station.status].label}
+                        />
+                      </Table.Cell>
+                    </Table.Row>
+                  ))}
+                </Table.Body>
+              </Table>
+            </Stack>
+            <Stack gap={4}>
+              <Inline justify="between">
+                <Text weight="strong">Needs attention</Text>
+                <Badge tone="critical">2</Badge>
+              </Inline>
+              <List divided>
+                <List.Item>
+                  <List.Content>
+                    <Text weight="medium">Ferry Lane is empty</Text>
+                    <List.Description>
+                      Since 07:52. The nearest van is 12 minutes away.
+                    </List.Description>
+                  </List.Content>
+                </List.Item>
+                <List.Item>
+                  <List.Content>
+                    <Text weight="medium">Bike 0417 reported a flat tyre</Text>
+                    <List.Description>Left at Kelso Bay Pier, dock 6.</List.Description>
+                  </List.Content>
+                </List.Item>
+              </List>
+            </Stack>
+          </Split>
+        </Stack>
+      </Container>
+    </Section>
+  )
+}
+```
+
+## What it's made of
+
+- **`SectionHeader`** carries the title, the date range and both actions, so the header is one component with one alignment.
+- **`Stat` with `rule`**: label, number and change on one baseline. The change takes a tone only where the direction is good or bad news.
+- **`Table` with `numeric` cells** keeps the figures in tabular lining numerals that line up down the column. `hideBelow="sm"` drops the occupancy meters on a phone instead of squeezing them.
+- **`Meter`** shows a level within a known range (bikes in docks), with `low` and `optimum` so the tone follows the value. A `Progress` would claim the stations are heading somewhere.
+- **`StatusDot`** pairs colour with a word, so status never depends on colour alone.
+- **`Split ratio="7/5"`**: an asymmetric split, the table given the room and the alerts beside it.
+
+## Why it isn't cards
+
+Cards are for self-contained, interactive objects. A dashboard's numbers are one document read top to bottom, so they sit on the canvas, separated by rules and space. Put a `Card` around something only when it's a thing you'd pick up, open or drag.

package/skills/layout-composition/references/divider.md

@@ -0,0 +1,59 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Divider
+
+> A hairline rule between groups of content, optionally labelled, horizontal or vertical.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/layout/divider
+
+`Divider` separates groups. For a rule between every item of a list, use `Stack dividers` instead, which spaces the rules for you.
+
+```tsx
+import { Divider, Inline, Stack, Text } from '@mitcsutt/kiln-ui'
+
+export default function Usage() {
+  return (
+    <Stack gap={4}>
+      <Text>Morning departures</Text>
+      <Divider />
+      <Divider label="Afternoon" spacing={4} />
+      <Divider label="Evening" labelPosition="center" strong />
+      <Inline gap={3}>
+        <Text size="sm">Timetable</Text>
+        <Divider orientation="vertical" />
+        <Text size="sm">Fares</Text>
+        <Divider orientation="vertical" />
+        <Text size="sm">Accessibility</Text>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+A labelled divider names the group that follows. `spacing` adds space above and below from the space scale, `strong` uses the stronger line colour, and `decorative` hides the rule from assistive technology when it carries no meaning (it's a `separator` otherwise).
+
+## API
+
+`DividerProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | `horizontal` | Default `horizontal`. A vertical rule stretches to its flex/grid row. |
+| `strong` | `boolean` |  | Heavier rule in `--color-line-strong` at `--border-width-strong`. |
+| `label` | `ReactNode` |  | Text set into a horizontal rule, e.g. "Earlier this week". It also names the separator. |
+| `labelPosition` | `'start' \| 'center'` | `start` | Where the label sits. Default `start` (left-aligned by default); `center` for a lone break. |
+| `spacing` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12` |  | Margin on both sides of the rule (block axis if horizontal, inline if vertical). |
+| `decorative` | `boolean` |  | Purely visual: hide it from assistive tech. Use when the rule only repeats a boundary that headings or landmarks already convey. |
+| `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
+| `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
+
+Also accepts every prop of `HTMLAttributes<HTMLDivElement>`.
+
+### Component tokens
+
+Set these in a theme, or on one element, to change this component without touching the rest.
+
+| Token | Default and use |
+| --- | --- |
+| `--divider-color` | default var(--color-line) (var(--color-line-strong) when strong) |
+| `--divider-label-color` | default var(--color-ink-muted) |