# Hack Cove UI

> An opinionated UI library that is fully integrated with its theming.

Hack Cove UI is strict on purpose. It fixes the look and feel, so a site built with it, by people or by agents, looks good every time. It is not an extensible framework with every option.

The components and the themes are designed together. Every theme remaps every palette utility the components use, and the library's tests enforce it for each theme. Switching theme reskins a whole site with no component change, and there is nothing to configure.

The aim is a site built only from Hack Cove components, configured through props, with no custom CSS or Tailwind.

Every component has one right way to use it. There are no extension recipes and no styling escape hatches: do not restyle a component, compose the parts.

## AppShell

Group: Layout

When to use: Every page of an app sits in one `AppShell`; it is the only place the page canvas, the font and the header live.

### The one right way
`AppShellBrand` makes the logo and the label one link, so the whole brand is the way home; `collapse` leaves only the logo below `sm`.
```tsx
import { Avatar, AppShellBrand } from "@hackcove/ui";

<AppShellBrand href="#" logo={<Avatar name="Quotes" size="sm" />} label="Quotes" collapse />
```

### Do
- Fill the slots and write no wrapper: `brand`, `nav` (a `NavTabs`), `controls` (a picker, a `ColourSchemeToggle`), then an optional `subnav` row and `footer`.
- `brand` is an `AppShellBrand`: logo and label in one link. `collapse` leaves only the logo below `sm`.
- With a router, give `AppShellBrand` a `render` that draws the app's own `<Link>` instead of an `href`.
- Header, main and footer each sit in a `Container`, so a page never sets its own width or padding. Do not add a `Container` inside the shell.
- `bleed` drops main's `Container` for a layout that needs the whole width (`FullBleedLayout`); `SidebarLayout` needs no `bleed`.
- `hideChromeInPrint` hides the header and footer and main's padding on paper; screen is unchanged.
- `header` is for a node no other slot covers. Prefer `brand`, `nav` and `controls`.
- Put `appShellRootClassFor(scheme)` on the app's own `<html>`. `AppShell` never touches `<html>`.
- A theme sets the canvas colour and the font; the app writes no page background or font rule.

### Don't
A logo and a name as two separate links are two targets, and the logo link has no name. Put both in `AppShellBrand`.
```tsx
import { Avatar, Cluster, TextLink } from "@hackcove/ui";

<Cluster gap="xs">
  <a href="#">
    <Avatar name="Quotes" size="sm" />
  </a>
  <TextLink href="#">Quotes</TextLink>
</Cluster>
```

### Accessibility
- The header is a `<header>` (the banner landmark), main is `<main>` and the footer is `<footer>`.
- `AppShellBrand` is one link named by its `label`; the logo is `aria-hidden`. With `collapse` the label is visually hidden below `sm` and still names the link.
- A header row that is wider than the screen (a long nav) scrolls sideways and never wraps; a link that takes focus scrolls into view, and the side with more to reach fades out.
- Give `nav` and `subnav` a `NavTabs` so each is a labelled `<nav>`.

### Props
### AppShell
The page frame: it paints the page canvas and sets the type face and ink, so an app writes no page-background or font rule of its own (a theme remaps the canvas and the font stacks). A sticky one-row header, an optional second `subnav` row, the main area and an optional footer. Header, main and footer each sit in a `Container`, so pages never set their own width or padding. `bleed` drops main's Container (the header keeps its own), for a layout that needs the whole width (`FullBleedLayout`). Main is a flex column. `SidebarLayout` needs no `bleed`: its rail and canvas share the header's Container. The header row is laid out by its slots, left to right: `brand`, `nav`, then `header` (anything the slots do not cover), then `controls`, pushed to the end. An app writes no wrapper or styling for any of them.
- bleed: boolean (default false). Main without a Container, for a full-bleed layout.
- brand: ReactNode. The brand: a logo and a name, in the header's brand type, with the gap between them. `AppShellBrand` makes both one link.
- controls: ReactNode. The end of the row: a picker, a theme toggle. Gap-2, vertically centred; no child shrinks, and a full-width control (a `Select` at its default) sizes to its content.
- footer: ReactNode
- header: ReactNode. The escape hatch: a free node in the header row, after `brand` and `nav`.
- hideChromeInPrint: boolean (default false). Print only the page: the header and footer are hidden, and main's Container drops its padding
(the page margin is then `@page`'s). Off by default, so a print is unchanged unless an app asks.
- nav: ReactNode. The main navigation, e.g. `NavTabs` (it is already a `<nav>`).
- subnav: ReactNode. A second fixed-height row under the header, e.g. `NavTabs`.

### AppShellBrand
The `brand` slot as one link: a logo and a label inside the same `<a>`, so the whole brand is the way home. The label names the link; the logo is decoration and hidden from assistive tech. `collapse` shows only the logo below `sm`, the label staying in the accessible name. With `render` it draws the app's own router `<Link>` (`render={(p) => <Link to="/" {...p} />}`).
- collapse: boolean (default false). Below `sm` only the logo shows; the label is visually hidden and still names the link. Needs a `logo`.
- href: string
- label: ReactNode (required). The name beside the logo. It is the link's accessible name.
- logo: ReactNode. The mark before the label, e.g. an `Avatar` or an `<img>`.
- render: LinkRender

### Functions
- appShellRootClass: The class for the app's own `<html>` that always reserves the scrollbar, so centred content does not shift between a short page and a long one.
- appShellRootClassFor: Everything the app's `<html>` takes from the scheme the server knows: that scheme's class and `appShellRootClass`, joined.

## Container

Group: Layout

When to use: Content outside an `AppShell`, such as a band in a `bleed` shell, that must start at the same x as the page.

### The one right way
One `Container` is the content edge: everything inside it starts at the same x.
```tsx
import { Body, Card, Container } from "@hackcove/ui";

<Container as="section" aria-label="Billing">
  <Card title="Plan">
    <Body>Team, billed monthly.</Body>
  </Card>
</Container>
```

### Do
- `Container` is the only place the page width (`max-w-6xl`) and side padding are defined; a header, a page and a footer inside one start at the same x.
- `AppShell` already wraps its header, main and footer in one. Use `Container` only for a part of a `bleed` shell that spans the page, so its content still keeps the edge.
- Never nest a `Container` in a `Container`: the padding doubles.
- `as` picks the element: `div` (default), `main`, `header`, `footer`, `section` or `nav`. A `section` or `nav` needs an `aria-label`.
- Space inside it with a `Stack`; a `Container` has no vertical padding or gap of its own.

### Don't
A `Container` inside a `Container` pads the content twice, so it no longer lines up with the page. `AppShell` already wraps its main in one.
```tsx
import { Body, Card, Container } from "@hackcove/ui";

<Container as="section" aria-label="Billing">
  <Container>
    <Card title="Plan">
      <Body>Team, billed monthly.</Body>
    </Card>
  </Container>
</Container>
```

### Accessibility
- A `Container` adds no role: a `div` is not a landmark. `as` picks `main`, `header`, `footer`, `section` or `nav` when the part should be one.
- `aria-*` and `data-*` go on the rendered element.

### Props
### Container
The one content edge: every page's width and side padding. This file is the only place they are defined, so a header, a page and a footer inside a Container start at the same x.
- as: "nav" | "header" | "footer" | "main" | "div" | "section"
- elementRef: ((element: HTMLElement | null) => void). The rendered element, for a parent that measures or scrolls it.

## PageHeader

Group: Layout

When to use: The first block of every page; it puts the page's first content at the same y on every page.

### The one right way
Breadcrumbs, title, subtitle, actions and tabs are slots of one `PageHeader`; each is optional.
```tsx
import { Breadcrumbs, Button, NavTabs, PageHeader } from "@hackcove/ui";

<PageHeader
  breadcrumbs={
    <Breadcrumbs
      crumbs={[
        { label: "Hack Cove", href: "#project" },
        { label: "Builds", href: "#builds" },
        "Build 412",
      ]}
    />
  }
  title="Build 412"
  subtitle="main · 3 changed"
  actions={
    <>
      <Button variant="outline">Reject</Button>
      <Button>Accept all</Button>
    </>
  }
  tabs={
    <NavTabs
      label="Build"
      items={[
        { label: "Changed", href: "#changed", active: true },
        { label: "New", href: "#new" },
      ]}
    />
  }
/>
```

### Do
- Pass `title`, and `subtitle`, `breadcrumbs`, `actions` and `tabs` as needed; never build a title row from a heading and a `Cluster`.
- `actions` sit beside the title from `sm` up and under it on a phone: a `Button` or two, one primary.
- `breadcrumbs` take a `Breadcrumbs`; `tabs` take a `NavTabs` (links to pages).
- Its fixed bottom margin gives every page the same first-block position. As a direct child of a `Stack` it has none and the Stack's `gap` is the only space, so do not wrap it in another element.
- One `PageHeader` per page: it holds the page's `<h1>`.

### Don't
A title row built from a heading, a subtitle and a `Cluster` is a second header that drifts from every other page's. Use `PageHeader`.
```tsx
import { Button, Cluster, PageHeading, Stack, Subtitle } from "@hackcove/ui";

<Cluster justify="between">
  <Stack gap="xs">
    <PageHeading>Build 412</PageHeading>
    <Subtitle>main · 3 changed</Subtitle>
  </Stack>
  <Button>Accept all</Button>
</Cluster>
```

Wrapped in a `div`, the header is no longer a direct child of the Stack, keeps its margin and doubles the space.
```tsx
import { Body, Card, PageHeader, Stack } from "@hackcove/ui";

<Stack gap="lg">
  <div>
    <PageHeader title="Members" subtitle="Who can see this project." />
  </div>
  <Card title="Active">
    <Body>3 members</Body>
  </Card>
</Stack>
```

### Accessibility
- The title is the page's `<h1>`; the subtitle is a paragraph.
- `Breadcrumbs` is a `<nav>` named Breadcrumb, with the last crumb marked `aria-current="page"`. Give `NavTabs` a `label`.
- On a narrow screen the actions move below the title.

### Props
### PageHeader
The top of a page: breadcrumbs, title, subtitle, actions and tabs. Its fixed bottom margin puts every page's first block at the same y; as a direct child of a `Stack` it has none, so the Stack's gap is the only space under it.
- actions: ReactNode. Right of the title on `sm` and up, below it on a phone.
- breadcrumbs: ReactNode. A `Breadcrumbs` above the title.
- subtitle: ReactNode
- tabs: ReactNode. A `NavTabs` (or similar) under the title.
- title: ReactNode (required)

## Stack

Group: Layout

When to use: Any blocks that follow each other: space is a Stack's `gap`, never a margin on a block.

### The one right way
Blocks that follow each other go in a `Stack`: the gap is one step of the scale, `md` by default.
```tsx
import { Body, Card, Stack } from "@hackcove/ui";

<Stack>
  <Card title="Build 412">
    <Body>3 changed</Body>
  </Card>
  <Card title="Build 411">
    <Body>No changes</Body>
  </Card>
</Stack>
```

### Do
- `gap` is a scale: `xs` between lines of text, `sm` inside a group, `md` (default) between blocks, `lg` between groups, `section` between a page's top-level blocks (the one responsive page rhythm).
- `width` caps the column at the left edge: `narrow` (a reading measure), `wide`, `full`, or `default` for the parent's width. It is never re-centred.
- `as` is `div` (default), `section`, `form`, `ul` or `ol`. `as="form"` takes the form props and spaces its fields; `as="ul"` and `as="ol"` draw no markers and their children are `<li>`s.
- A titled group is a `Section`: `title`, `actions` beside it, then the blocks, at gap `sm`. It takes `gap` and `width` as `Stack` does.
- A row of items is a `Cluster`, not a Stack.

### Don't
Blocks in a bare `div` touch each other. Space is the Stack's job, never left to the blocks.
```tsx
import { Body, Card } from "@hackcove/ui";

<div>
  <Card title="Build 412">
    <Body>3 changed</Body>
  </Card>
  <Card title="Build 411">
    <Body>No changes</Body>
  </Card>
</div>
```

A heading row built by hand is not tied to its group: nothing names the region and the row's spacing is a guess. Use `Section`.
```tsx
import { Body, Button, Card, Cluster, SectionHeading, Stack } from "@hackcove/ui";

<Stack gap="sm">
  <Cluster justify="between">
    <SectionHeading>Recent builds</SectionHeading>
    <Button variant="outline">All builds</Button>
  </Cluster>
  <Card>
    <Body>Build 412 · 3 changed</Body>
  </Card>
  <Card>
    <Body>Build 411 · no changes</Body>
  </Card>
</Stack>
```

The same cards in a plain Stack are two unrelated blocks: no list, no count, nothing to jump by.
```tsx
import { Body, Card, Stack } from "@hackcove/ui";

<Stack gap="sm">
  <Card>
    <Body>Build 412 · 3 changed</Body>
  </Card>
  <Card>
    <Body>Build 411 · no changes</Body>
  </Card>
</Stack>
```

### Accessibility
- `Section` is a `<section>` named by its `title` (`aria-labelledby`), so it is a region; with no `title` give it an `aria-label`.
- A `Stack` with `as="ul"` or `as="ol"` is a real list: give it an `aria-label` when more than one list is on the page.
- `as="form"` is a `<form>`; give it an `aria-label` or let a heading name it.
- A `div` Stack adds no role.

### Props
### Stack
A vertical column of blocks a fixed `gap` apart: `xs` between lines of text (a heading and the line under it), `sm` inside a group, `md` (default) between blocks, `lg` between groups, `section` between a page's top-level blocks (`gap-12`, `sm:gap-16`: the one responsive page rhythm). `width` caps the column: `narrow` is a reading measure (`max-w-3xl`), `wide` is `max-w-5xl`, `full` is the parent's whole width and `default` sets nothing. A capped Stack starts at its parent's left edge (it is never re-centred), so its first line lines up with every other block on the page. `as` is a closed set: `div` (default), `section`, `form`, `ul` or `ol`. A `form` takes the form props (`onSubmit`, `action`, `method`, `noValidate`, ...). A `ul` or `ol` is drawn with no markers and its children are `<li>`s, as in `BulletList` and `Timeline`: the Stack does not wrap them, so a child is one list item and `Body as="li"` or a bare `<li>` both work.
- as: "form" | "div" | "ol" | "section" | "ul" (default div)
- gap: "sm" | "md" | "lg" | "section" | "xs" (default md)
- width: "default" | "narrow" | "full" | "wide" (default default)

### Section
A `<section>` Stack with an optional `SectionHeading` title (which names it) and `actions` beside it.
- actions: ReactNode
- gap: "sm" | "md" | "lg" | "section" | "xs" (default sm)
- title: ReactNode
- width: "default" | "narrow" | "full" | "wide"

## Cluster

Group: Layout

When to use: Items in a line that are not buttons: a label beside a value, an input beside its actions, a row of pills.

### The one right way
The one item that should take the room left goes in `ClusterGrow`: the input fills the row and the buttons keep their size.
```tsx
import { Button, Cluster, ClusterGrow, Input } from "@hackcove/ui";

<Cluster>
  <ClusterGrow>
    <Input aria-label="Search" placeholder="Search invoices" />
  </ClusterGrow>
  <Button>Search</Button>
</Cluster>
```

### Do
- `gap` is `xs`, `sm` (default) or `md`, the first steps of the `Stack` scale.
- `align` is the cross axis: `center` (default), `baseline` for mixed text sizes, `start` or `end`. `justify` is the main axis: `start` (default), `between` for the two ends, `end`.
- `wrap` lets the items flow onto more lines on a phone; without it the row stays on one line.
- Wrap the one item that should fill the row in `ClusterGrow`; it can shrink to nothing, so a long value truncates and the others stay.
- An empty `ClusterGrow` is a spacer: what follows it goes to the end.
- A row of buttons is a `ButtonGroup`, which wraps on a phone and can pin an item to the end. Use `Cluster` for every other row.
- `justify="between"` is for two items; with more, the middle one floats, so use a spacer.

### Don't
Without `ClusterGrow` the input keeps a fixed width and the rest of the row sits empty. Wrap the input in `ClusterGrow` instead.
```tsx
import { Button, Cluster, Input } from "@hackcove/ui";

<Cluster>
  <Input aria-label="Search" placeholder="Search invoices" width="sm" />
  <Button>Search</Button>
</Cluster>
```

`Cluster` is for every other row; a row of buttons in it does not wrap and has no end slot.
```tsx
import { Button, Cluster } from "@hackcove/ui";

<Cluster>
  <Button>Send</Button>
  <Button variant="outline">Download</Button>
  <Button variant="outline">Back</Button>
</Cluster>
```

`justify="between"` spreads three items evenly, so the middle one floats away from the group it belongs to.
```tsx
import { BodyStrong, Button, Cluster } from "@hackcove/ui";

<Cluster justify="between">
  <BodyStrong>Invoice 1042</BodyStrong>
  <Button size="sm" variant="outline">
    Edit
  </Button>
  <Button size="sm" variant="outline" tone="danger">
    Remove
  </Button>
</Cluster>
```

### Accessibility
- A `Cluster` is a `div` and adds no role; the reading and tab order is the source order of its children.
- `ClusterGrow` is a `div` too: put the labelled control inside it, with its own `aria-label` or `Field`.

### Props
### Cluster
A horizontal row of items a fixed `gap` apart: the row counterpart of `Stack`. `align` is the cross axis (`center` default, `baseline` for mixed text sizes, `start`, `end`) and `justify` the main one (`start` default, `between` to push the first and last items to the two ends, `end`). `wrap` lets the items flow onto further lines on a narrow viewport (off by default, so a row stays on one line). Put one `ClusterGrow` around the item that takes the room left over, an input beside its buttons, say. An empty `ClusterGrow` is a spacer that pushes what follows it to the end. `ButtonGroup` is the row for buttons; use `Cluster` for any other row.
- align: "center" | "end" | "start" | "baseline" (default center)
- gap: "sm" | "md" | "xs" (default sm)
- justify: "end" | "start" | "between" (default start)
- wrap: boolean (default false)

### ClusterGrow
The one child of a `Cluster` that grows to the room left in the row. It can shrink to nothing (`min-w-0`), so the items beside it stay on the line and a long value truncates instead of pushing them out. Empty, it is a spacer.

## Divider

Group: Layout

When to use: One line between a heading and its content, or above a footer.

### The one right way
A `Divider` is one hairline between two parts of a page, here the content and its footer. The space around it is the `Stack`'s.
```tsx
import { Body, Caption, Divider, Stack } from "@hackcove/ui";

<Stack gap="lg">
  <Body as="p">The last paragraph of a page.</Body>
  <Divider />
  <Caption as="p">Hack Cove (Pty) Ltd</Caption>
</Stack>
```

### Do
- Use it between two parts of a page that are not bordered, such as the content and its footer.
- The space around it is the layout's: put it in a `Stack`, never add margin.
- Do not draw it between bordered blocks such as `Card`: their borders and the `gap` already separate them.
- For a rule under a section title, `SectionHeading` has `rule`.

### Don't
A `Divider` between two Cards is a second line on top of their borders and the gap.
```tsx
import { Body, Card, Divider, Stack } from "@hackcove/ui";

<Stack>
  <Card title="Build 412">
    <Body>3 changed</Body>
  </Card>
  <Divider />
  <Card title="Build 411">
    <Body>No changes</Body>
  </Card>
</Stack>
```

### Accessibility
- It is an `<hr>`, which assistive tech announces as a separator. Use it only where the content really changes.

### Props
### Divider
A hairline rule in the theme's line colour: between a heading and its content, or above a footer. Space around it is the layout's.

## ListLayout

Group: Page layouts

When to use: An index of quotes, builds, members or any other collection; a single record is `DetailLayout`.

### The one right way
`filters` sit under the header, then the rows: one `Card` per item.
```tsx
import {
  Body,
  Button,
  Card,
  FilterGroup,
  ListLayout,
  Pill,
  ToggleChip,
} from "@hackcove/ui";

<ListLayout
  title="Quotes"
  subtitle="Every quote you have sent."
  actions={<Button>New quote</Button>}
  filters={
    <FilterGroup legend="Status">
      <ToggleChip pressed>All</ToggleChip>
      <ToggleChip pressed={false}>Sent</ToggleChip>
    </FilterGroup>
  }
>
  <Card as="article" title="Naledi Mokoena" status={<Pill tone="emerald">Accepted</Pill>}>
    <Body as="p">Q-1042 · R 1 240 / mo</Body>
  </Card>
  <Card as="article" title="Pieter van Wyk" status={<Pill tone="slate">Sent</Pill>}>
    <Body as="p">Q-1041 · R 860 / mo</Body>
  </Card>
</ListLayout>
```

### Full page
A whole list page: the shell with its brand and nav, then the layout with its filters and rows.
```tsx
import {
  AppShell,
  Body,
  BodyStrong,
  Button,
  Card,
  FilterGroup,
  ListLayout,
  NavTabs,
  ToggleChip,
} from "@hackcove/ui";

<AppShell
  brand={<a href="#">Hack Cove</a>}
  nav={
    <NavTabs
      label="Main"
      items={[
        { label: "Quotes", href: "#quotes", active: true },
        { label: "Clients", href: "#clients" },
      ]}
    />
  }
>
  <ListLayout
    title="Quotes"
    subtitle="Every quote you have sent."
    actions={<Button>New quote</Button>}
    filters={
      <FilterGroup legend="Status">
        <ToggleChip pressed>All</ToggleChip>
        <ToggleChip pressed={false}>Sent</ToggleChip>
        <ToggleChip pressed={false}>Accepted</ToggleChip>
      </FilterGroup>
    }
  >
    <Card as="article">
      <BodyStrong as="p">Naledi Mokoena</BodyStrong>
      <Body as="p" color="secondary">
        Q-1042 · R 1 240 / mo
      </Body>
    </Card>
    <Card as="article">
      <BodyStrong as="p">Pieter van Wyk</BodyStrong>
      <Body as="p" color="secondary">
        Q-1041 · R 860 / mo
      </Body>
    </Card>
  </ListLayout>
</AppShell>
```

### Do
- Put the page's title, subtitle and primary `actions` in the header props; `breadcrumbs` and `tabs` go there too.
- `filters` sit between the header and the list: a `FilterGroup` of `ToggleChip`s.
- The items are the `children`, one `Card` per item, or a `Table`; the layout spaces them.
- Set `isEmpty` and give `empty` an `EmptyState` that says what is missing and what to do next; `isEmpty` without `empty` is a blank page.
- Do not build the header and the list by hand with `PageHeader` and `Stack`: the layout is the one right header, filters and list.

### Don't
A one-off header and stack drifts from every other list page; `ListLayout` is the one header, filters and list.
```tsx
import { Body, Card, PageHeader, Stack } from "@hackcove/ui";

<Stack>
  <PageHeader title="Quotes" subtitle="Every quote you have sent." />
  <Card as="article" title="Naledi Mokoena">
    <Body as="p">Q-1042 · R 1 240 / mo</Body>
  </Card>
</Stack>
```

`isEmpty` without `empty` leaves a blank page under the header.
```tsx
import { ListLayout } from "@hackcove/ui";

<ListLayout title="Quotes" subtitle="Every quote you have sent." isEmpty />

```

### Accessibility
- The title is the page's `h1`.
- `filters` and `children` render as given, so each filter group keeps its own `fieldset` and legend.
- `data-*` and `aria-*` go on the list's wrapper.

### Props
### ListLayout
A list page: header, an optional `filters` slot, then the list, or `empty` when `isEmpty`.
- actions: ReactNode. Right of the title on `sm` and up, below it on a phone.
- breadcrumbs: ReactNode. A `Breadcrumbs` above the title.
- empty: ReactNode. Shown in place of `children` when `isEmpty`.
- filters: ReactNode
- isEmpty: boolean (default false)
- subtitle: ReactNode
- tabs: ReactNode. A `NavTabs` (or similar) under the title.
- title: ReactNode (required)

## DetailLayout

Group: Page layouts

When to use: One quote, build or member, with its content in the main column and its facts in the aside.

### The one right way
The record's content is the main column; the facts about it go in `aside`.
```tsx
import { Body, Button, Card, DetailLayout, KeyValue, KeyValueList } from "@hackcove/ui";

<DetailLayout
  title="Quote Q-1042"
  subtitle="Naledi Mokoena"
  actions={<Button variant="outline">Edit</Button>}
  aside={
    <Card title="Details">
      <KeyValueList>
        <KeyValue label="Status">Sent</KeyValue>
        <KeyValue label="Premium">R 1 240 / mo</KeyValue>
      </KeyValueList>
    </Card>
  }
>
  <Card title="Cover">
    <Body as="p">Life cover of R 1 500 000, to age 65.</Body>
  </Card>
</DetailLayout>
```

### Full page
A whole record page: the shell with its brand and nav, then the layout with the record in `children` and its facts in `aside`.
```tsx
import {
  AppShell,
  Body,
  Button,
  Card,
  DetailLayout,
  KeyValue,
  KeyValueList,
  NavTabs,
} from "@hackcove/ui";

<AppShell
  brand={<a href="#">Hack Cove</a>}
  nav={
    <NavTabs
      label="Main"
      items={[
        { label: "Quotes", href: "#quotes", active: true },
        { label: "Clients", href: "#clients" },
      ]}
    />
  }
>
  <DetailLayout
    title="Quote Q-1042"
    subtitle="Naledi Mokoena"
    actions={<Button variant="outline">Edit</Button>}
    aside={
      <Card title="Details">
        <KeyValueList>
          <KeyValue label="Status">Sent</KeyValue>
          <KeyValue label="Premium">R 1 240 / mo</KeyValue>
        </KeyValueList>
      </Card>
    }
  >
    <Card title="Cover">
      <Body as="p">Life cover of R 1 500 000, to age 65.</Body>
    </Card>
    <Card title="Notes">
      <Body as="p">The client asked to be debited on the 25th.</Body>
    </Card>
  </DetailLayout>
</AppShell>
```

### Do
- The record's content is the `children`, in the main two thirds; they are spaced as a `Stack`, so give each block its own `Card`.
- The facts about the record go in `aside`, in the third beside it: a `Card` with a `KeyValueList`, a status, the people on it.
- Both columns are required: with nothing for the aside, use `ListLayout`.
- From `lg` the aside sits beside the content; below it, it stacks under the content.
- The header props are the same as `ListLayout`: `breadcrumbs`, `title`, `subtitle`, `actions`, `tabs`.

### Don't
`ListLayout` has no aside, so the facts become one more block under the content. Use `DetailLayout` for a record.
```tsx
import { Body, Button, Card, KeyValue, KeyValueList, ListLayout } from "@hackcove/ui";

<ListLayout
  title="Quote Q-1042"
  subtitle="Naledi Mokoena"
  actions={<Button variant="outline">Edit</Button>}
>
  <Card title="Cover">
    <Body as="p">Life cover of R 1 500 000, to age 65.</Body>
  </Card>
  <Card title="Details">
    <KeyValueList>
      <KeyValue label="Status">Sent</KeyValue>
      <KeyValue label="Premium">R 1 240 / mo</KeyValue>
    </KeyValueList>
  </Card>
</ListLayout>
```

### Accessibility
- The title is the page's `h1`.
- The aside is an `<aside>`, a complementary landmark; the main column is a plain `div`.
- In the DOM the content comes first and the aside second, so that is the reading and tab order on every screen.

### Props
### DetailLayout
A detail page: header, then `children` (two thirds from `lg`) beside `aside` (one third), which stacks below on a smaller screen.
- actions: ReactNode. Right of the title on `sm` and up, below it on a phone.
- aside: ReactNode (required)
- breadcrumbs: ReactNode. A `Breadcrumbs` above the title.
- subtitle: ReactNode
- tabs: ReactNode. A `NavTabs` (or similar) under the title.
- title: ReactNode (required)

## FormLayout

Group: Page layouts

When to use: Creating or editing a record on a page of its own.

### The one right way
The fields go in `children`; Save and Cancel go in `actions`, at the end of the form.
```tsx
import { Button, Card, Field, FormLayout, Input, Stack } from "@hackcove/ui";

<FormLayout
  title="New client"
  subtitle="Who is the quote for?"
  onSubmit={(event) => event.preventDefault()}
  actions={
    <>
      <Button type="submit">Save client</Button>
      <Button variant="ghost">Cancel</Button>
    </>
  }
>
  <Card title="Client">
    <Stack>
      <Field label="Full name" htmlFor="do-form-name">
        <Input id="do-form-name" placeholder="Naledi Mokoena" />
      </Field>
      <Field label="Email" htmlFor="do-form-email">
        <Input id="do-form-email" type="email" placeholder="naledi@example.com" />
      </Field>
    </Stack>
  </Card>
</FormLayout>
```

### Full page
A whole form page: the shell with its brand and nav, then the layout with the fields in `children` and Save and Cancel in `actions`.
```tsx
import {
  AppShell,
  Button,
  Card,
  Field,
  FormLayout,
  Input,
  NavTabs,
  Stack,
} from "@hackcove/ui";

<AppShell
  brand={<a href="#">Hack Cove</a>}
  nav={
    <NavTabs
      label="Main"
      items={[
        { label: "Quotes", href: "#quotes", active: true },
        { label: "Clients", href: "#clients" },
      ]}
    />
  }
>
  <FormLayout
    title="New client"
    subtitle="Who is the quote for?"
    onSubmit={(event) => event.preventDefault()}
    actions={
      <>
        <Button type="submit">Save client</Button>
        <Button variant="ghost">Cancel</Button>
      </>
    }
  >
    <Card title="Client">
      <Stack>
        <Field label="Full name" htmlFor="full-page-name">
          <Input id="full-page-name" placeholder="Naledi Mokoena" />
        </Field>
        <Field label="Email" htmlFor="full-page-email">
          <Input id="full-page-email" type="email" />
        </Field>
      </Stack>
    </Card>
  </FormLayout>
</AppShell>
```

### Do
- The fields are the `children`, grouped in `Card`s; the layout spaces them in a reading-width column.
- Save and Cancel go in `actions`, at the end of the form: a `type="submit"` Button first, then a ghost Cancel. The header has no `actions` here.
- Handle the submit with `onSubmit`: other props go on the `<form>` itself.
- A form in a small panel is a `Dialog` or `FieldDialog`; a sign-in is `CenteredLayout`.
- Do not put Save in the header of a `ListLayout`: that is not a form.

### Don't
`ListLayout` is not a form: Save sits in the header, away from the fields, and nothing submits on Enter. Use `FormLayout`.
```tsx
import { Button, Card, Field, Input, ListLayout, Stack } from "@hackcove/ui";

<ListLayout
  title="New client"
  subtitle="Who is the quote for?"
  actions={<Button>Save client</Button>}
>
  <Card title="Client">
    <Stack>
      <Field label="Full name" htmlFor="dont-form-name">
        <Input id="dont-form-name" placeholder="Naledi Mokoena" />
      </Field>
      <Field label="Email" htmlFor="dont-form-email">
        <Input id="dont-form-email" type="email" placeholder="naledi@example.com" />
      </Field>
    </Stack>
  </Card>
</ListLayout>
```

### Accessibility
- The root is a real `<form>`: Enter in a field submits it, and a `type="submit"` Button submits it.
- The title is the page's `h1`.
- Give each control a `Field` with `htmlFor`, so every input has a label.

### Props
### FormLayout
A form page: header (no header `actions`), then a `max-w-3xl` column that starts at the Container's left edge (it is not re-centred), with an `actions` row at the end. Other props go on the `<form>`.
- actions: ReactNode
- breadcrumbs: ReactNode. A `Breadcrumbs` above the title.
- subtitle: ReactNode
- tabs: ReactNode. A `NavTabs` (or similar) under the title.
- title: ReactNode (required)

## ProseLayout

Group: Page layouts

When to use: Privacy, terms, help or any page that is mostly paragraphs.

### The one right way
Text pages (privacy, terms, help) are one reading column; the header sits inside it.
```tsx
import { Body, ProseLayout, SectionHeading } from "@hackcove/ui";

<ProseLayout title="Privacy" subtitle="How we handle your data.">
  <SectionHeading>What we keep</SectionHeading>
  <Body as="p">We keep your account details and the quotes you send, and nothing else.</Body>
  <SectionHeading>Who sees it</SectionHeading>
  <Body as="p">Only you and the people you invite to your organisation.</Body>
</ProseLayout>
```

### Full page
A whole text page: the shell with its brand and nav, then one reading column with the header inside it.
```tsx
import { AppShell, Body, NavTabs, ProseLayout, SectionHeading } from "@hackcove/ui";

<AppShell
  brand={<a href="#">Hack Cove</a>}
  nav={
    <NavTabs
      label="Main"
      items={[
        { label: "Quotes", href: "#quotes", active: true },
        { label: "Clients", href: "#clients" },
      ]}
    />
  }
>
  <ProseLayout title="Privacy" subtitle="How we handle your data.">
    <SectionHeading>What we keep</SectionHeading>
    <Body as="p">We keep your account details and the quotes you send, and nothing else.</Body>
    <SectionHeading>Who sees it</SectionHeading>
    <Body as="p">Only you and the people you invite to your organisation.</Body>
  </ProseLayout>
</AppShell>
```

### Do
- The text is the `children`: `SectionHeading`s and `Body as="p"` paragraphs, spaced `md` apart.
- `gap` picks another spacing from the same scale (`xs` to `section`) for the whole page; the default is right for most pages.
- The header sits inside the column, so its `actions` stay beside the text.
- Data or cards in a grid are not prose: use `ListLayout` or `CardGrid`.

### Don't
`ListLayout` is for lists: its content runs the full width, so lines of text get too long to read. Use `ProseLayout`.
```tsx
import { Body, Card, ListLayout } from "@hackcove/ui";

<ListLayout title="Privacy" subtitle="How we handle your data.">
  <Card>
    <Body as="p">
      We keep your account details and the quotes you send, and nothing else. Only you and the
      people you invite to your organisation can see them.
    </Body>
  </Card>
</ListLayout>
```

### Accessibility
- The title is the page's `h1`.
- Use `SectionHeading` for sections so the outline runs h1 then h2.
- `data-*` and `aria-*` go on the column's wrapper.

### Props
### ProseLayout
A text page: header, then `children` stacked `gap` apart (`md` by default), all in one `narrow` (`max-w-3xl`) reading column that starts at the Container's left edge (it is not re-centred, so the title does not jump). Unlike `FormLayout` the header sits inside the column, so its `actions` stay beside the text instead of at the Container's far edge.
- actions: ReactNode. Right of the title on `sm` and up, below it on a phone.
- breadcrumbs: ReactNode. A `Breadcrumbs` above the title.
- gap: "sm" | "md" | "lg" | "section" | "xs"
- subtitle: ReactNode
- tabs: ReactNode. A `NavTabs` (or similar) under the title.
- title: ReactNode (required)

## CardGrid

Group: Page layouts

When to use: Several cards or `StatTile`s of the same weight that should sit side by side on a wide screen.

### The one right way
Tiles go in a `CardGrid`: one column on a phone, two from `sm`, `columns` from `lg`.
```tsx
import { CardGrid, StatTile } from "@hackcove/ui";

<CardGrid columns={3}>
  <StatTile label="Open" value="12" />
  <StatTile label="Won" value="8" tone="positive" />
  <StatTile label="Lost" value="3" tone="negative" />
</CardGrid>
```

### Full page
A whole dashboard page: the shell with its brand and nav, then a `PageHeader` and a `CardGrid` of tiles.
```tsx
import { AppShell, CardGrid, NavTabs, PageHeader, Stack, StatTile } from "@hackcove/ui";

<AppShell
  brand={<a href="#">Hack Cove</a>}
  nav={
    <NavTabs
      label="Main"
      items={[
        { label: "Quotes", href: "#quotes", active: true },
        { label: "Clients", href: "#clients" },
      ]}
    />
  }
>
  <Stack gap="section">
    <PageHeader title="Business" subtitle="This month at a glance." />
    <CardGrid columns={3}>
      <StatTile label="Open" value="12" />
      <StatTile label="Won" value="8" tone="positive" />
      <StatTile label="Lost" value="3" tone="negative" />
    </CardGrid>
  </Stack>
</AppShell>
```

### Do
- Use `columns` 2, 3 or 4 when you know how many; it is one column on a phone, two from `sm` and `columns` from `lg`.
- Use `columns="auto"` when the count varies: it fits as many per row as the width allows, none narrower than `minWidth` (`md`, the default, or `sm`).
- `align="start"` keeps each card its own height; by default every card stretches to the tallest in its row.
- `CardGrid` goes inside a page layout; it sets no page width of its own.
- A single column of blocks is a `Stack`, not a one-column `CardGrid`.

### Don't
A `Stack` is one column, so the tiles never sit side by side and the page runs long. Use a `CardGrid`.
```tsx
import { Stack, StatTile } from "@hackcove/ui";

<Stack>
  <StatTile label="Open" value="12" />
  <StatTile label="Won" value="8" tone="positive" />
  <StatTile label="Lost" value="3" tone="negative" />
</Stack>
```

### Accessibility
- The grid is a plain `div` with no role: the cards keep their own order and semantics.
- The order is the DOM order, so the tab order follows the reading order.

### Props
### CardGrid
A responsive grid of tiles: one column on a phone, two from `sm`, `columns` from `lg`. `columns="auto"` instead fits as many per row as the width allows, each at least `minWidth` wide: `md` (17rem, the default) or `sm` (12rem). `align="start"` keeps each card its own height instead of stretching it to the tallest in its row.
- align: "start" | "stretch" (default stretch). `start` keeps each card its own height; the default stretches every card to the tallest in its row.
- columns: "auto" | 2 | 3 | 4 (default 3)
- minWidth: "sm" | "md" (default md)

## SidebarLayout

Group: Page layouts

When to use: A section with several sub-pages, such as settings, where the rail is the way between them.

### The one right way
A vertical `NavTabs` is the rail: a short list of sections beside the page.
```tsx
import { Body, Card, NavTabs, PageHeader, SidebarLayout } from "@hackcove/ui";

<SidebarLayout
  rail={
    <NavTabs
      orientation="vertical"
      label="Settings"
      items={[
        { label: "Profile", href: "#profile", active: true },
        { label: "Billing", href: "#billing" },
        { label: "Team", href: "#team" },
      ]}
    />
  }
>
  <PageHeader title="Profile" subtitle="Your name and email." />
  <Card title="Account">
    <Body as="p">Naledi Mokoena, naledi@example.com</Body>
  </Card>
</SidebarLayout>
```

### Full page
A whole page with a rail: the shell with its brand and nav, then the layout with a vertical `NavTabs` in `rail` and the page in `children`.
```tsx
import {
  AppShell,
  Body,
  Button,
  Card,
  NavTabs,
  PageHeader,
  SidebarLayout,
} from "@hackcove/ui";

<AppShell
  brand={<a href="#">Hack Cove</a>}
  nav={
    <NavTabs
      label="Main"
      items={[
        { label: "Quotes", href: "#quotes", active: true },
        { label: "Clients", href: "#clients" },
      ]}
    />
  }
>
  <SidebarLayout
    rail={
      <NavTabs
        orientation="vertical"
        label="Organisations"
        items={[
          { label: "Hack Cove", href: "#hack-cove", active: true },
          { label: "Acme", href: "#acme" },
          { label: "Northwind", href: "#northwind" },
        ]}
      />
    }
  >
    <PageHeader
      title="Hack Cove"
      subtitle="3 projects"
      actions={<Button>New project</Button>}
    />
    <Card title="Projects">
      <Body as="p">Storybook, Dashboard, Site.</Body>
    </Card>
  </SidebarLayout>
</AppShell>
```

### Do
- The `rail` is a `NavTabs` with `orientation="vertical"`, one link per section and the current one `active`.
- The `children` are the section's page: its `PageHeader`, then the content.
- From `md` the rail is a fixed width beside the page; below it, the rail stacks above the page.
- The rail has no background or border: it is a list of links on the page.
- A long rail sets `railLabel`: below `md` it folds behind a closed disclosure of that name, so the page comes first on a phone; from `md` it is the same rail. A short rail leaves it out.
- Facts about one record go in `DetailLayout`'s aside, not a rail.

### Don't
The default, horizontal `NavTabs` wraps into a ragged block in the rail. Give the rail `orientation="vertical"`.
```tsx
import { Body, Card, NavTabs, PageHeader, SidebarLayout } from "@hackcove/ui";

<SidebarLayout
  rail={
    <NavTabs
      label="Settings"
      items={[
        { label: "Profile", href: "#profile", active: true },
        { label: "Billing", href: "#billing" },
        { label: "Team", href: "#team" },
      ]}
    />
  }
>
  <PageHeader title="Profile" subtitle="Your name and email." />
  <Card title="Account">
    <Body as="p">Naledi Mokoena, naledi@example.com</Body>
  </Card>
</SidebarLayout>
```

### Accessibility
- The rail is an `<aside>` holding the `NavTabs`, which is a `<nav>` named by its `label`.
- The current link has `aria-current="page"`.
- In the DOM the rail comes first, so it is first in the tab order; folded, the summary is that first stop and the links are skipped until it is opened.
- With `railLabel` the rail is a native `<details>` disclosure: its `<summary>` is the toggle, on the keyboard like any button.

### Props
### SidebarLayout
A `rail` of links beside the `children` canvas, in the Container the shell already gives every page (a plain `<AppShell>`, no `bleed`): the rail starts at the header logo's x and the canvas ends at the header's right edge. The rail has no background and no border, so it is a list of links on the page; a `NavTabs orientation="vertical"` is its content. From `md` it is `w-56` with the canvas filling the rest; below `md` it stacks above the canvas. A long rail sets `railLabel`: below `md` it then folds behind a disclosure of that name, closed, so the page comes first on a phone, and from `md` it is the same rail. Upgrading from 0.2: the rail no longer has a fill, a border or a fixed height, and it no longer sits beside the canvas on a phone.
- rail: ReactNode (required)
- railLabel: string. Folds the rail behind a disclosure with this name below `md` (a long rail). Left out, the rail is always open.

## FullBleedLayout

Group: Page layouts

When to use: A viewer that needs the whole width, such as a snapshot, a canvas or a player; an ordinary page is not.

### The one right way
A viewer that needs the whole width (a snapshot, a canvas, a player) fills it, with the facts in the `panel`.
```tsx
import { Body, FullBleedLayout, KeyValue, KeyValueList, Overline } from "@hackcove/ui";

<FullBleedLayout
  panel={
    <>
      <Overline as="h2">Snapshot</Overline>
      <KeyValueList>
        <KeyValue label="Story">Button / Primary</KeyValue>
        <KeyValue label="Changed">0.4%</KeyValue>
      </KeyValueList>
    </>
  }
>
  <Body as="p" color="secondary">
    The snapshot fills the width.
  </Body>
</FullBleedLayout>
```

### Full page
A whole viewer page: the shell with `bleed`, then the layout with the viewer in `children` and the facts in `panel`. The `EmptyState` stands in for the app's own viewer.
```tsx
import {
  AppShell,
  Body,
  EmptyState,
  FullBleedLayout,
  KeyValue,
  KeyValueList,
  NavTabs,
  Overline,
} from "@hackcove/ui";

<AppShell
  brand={<a href="#">Hack Cove</a>}
  nav={
    <NavTabs
      label="Main"
      items={[
        { label: "Quotes", href: "#quotes", active: true },
        { label: "Clients", href: "#clients" },
      ]}
    />
  }
  bleed
>
  <FullBleedLayout
    panel={
      <>
        <Overline as="h2">Snapshot</Overline>
        <KeyValueList>
          <KeyValue label="Story">Button / Primary</KeyValue>
          <KeyValue label="Changed">0.4%</KeyValue>
        </KeyValueList>
      </>
    }
  >
    <EmptyState title="Snapshot viewer">
      <Body as="p" color="secondary">
        Your viewer goes here and fills the width.
      </Body>
    </EmptyState>
  </FullBleedLayout>
</AppShell>
```

### Do
- Render it in an `AppShell` with `bleed`; the canvas starts at the left edge of the viewport.
- It adds no padding and has no page title; the canvas is the `children`.
- Put the facts about what is shown in `panel`, a `KeyValueList` under an `Overline`. From `lg` the panel is a fixed-width column on the right; below it, it stacks under the canvas.
- Omit `panel` when the canvas stands alone.
- A page with a title and content is `ListLayout` or `DetailLayout`.

### Don't
`FullBleedLayout` adds no padding, so an ordinary page lands on the screen edge. A page with a title is a `ListLayout` or `DetailLayout`.
```tsx
import { Body, Card, FullBleedLayout } from "@hackcove/ui";

<FullBleedLayout>
  <Card title="Quotes">
    <Body as="p">Every quote you have sent.</Body>
  </Card>
</FullBleedLayout>
```

### Accessibility
- The panel is an `<aside>`, a complementary landmark; give it a heading with `Overline as="h2"`.
- The canvas comes first in the DOM, then the panel.

### Props
### FullBleedLayout
Edge-to-edge `children` with an optional right `panel` (`lg:w-72`) that stacks below on a smaller screen. Render it in `<AppShell bleed>`. It deliberately breaks the shared left edge: a viewer that needs the whole width has no Container of its own, so `children` start at the viewport's left edge and add their own padding.
- panel: ReactNode

## CenteredLayout

Group: Page layouts

When to use: Sign-in, a landing page, or a not-found or error page.

### The one right way
Sign-in, landing, not-found and error pages are one narrow card, centred.
```tsx
import { Button, CenteredLayout, Field, Input } from "@hackcove/ui";

<CenteredLayout title="Sign in" subtitle="Use your Hack Cove account.">
  <Field label="Email" htmlFor="do-page-email">
    <Input id="do-page-email" type="email" placeholder="you@example.com" />
  </Field>
  <Button>Continue</Button>
</CenteredLayout>
```

### Full page
A whole sign-in page: the shell with its brand and nav, then one narrow card, centred.
```tsx
import { AppShell, Button, CenteredLayout, Field, Input, NavTabs } from "@hackcove/ui";

<AppShell
  brand={<a href="#">Hack Cove</a>}
  nav={
    <NavTabs
      label="Main"
      items={[
        { label: "Quotes", href: "#quotes", active: true },
        { label: "Clients", href: "#clients" },
      ]}
    />
  }
>
  <CenteredLayout title="Sign in" subtitle="Use your Hack Cove account.">
    <Field label="Email" htmlFor="full-page-email">
      <Input id="full-page-email" type="email" placeholder="you@example.com" />
    </Field>
    <Button>Continue</Button>
  </CenteredLayout>
</AppShell>
```

### Do
- Give it a `title` and a `subtitle`; the `children` are the card's content: a `Field` or two and a `Button`.
- It is the one layout that does not share the left edge: it is centred, at a fixed offset from the top.
- A form inside the app is `FormLayout`, not this.
- The ready-made status pages (not found, forbidden, offline, error, maintenance) are already built on it.

### Don't
`FormLayout` is for a form inside the app: its wide column hangs off the left edge, which is wrong for a sign-in. Use `CenteredLayout`.
```tsx
import { Button, Field, FormLayout, Input } from "@hackcove/ui";

<FormLayout
  title="Sign in"
  subtitle="Use your Hack Cove account."
  actions={<Button type="submit">Continue</Button>}
>
  <Field label="Email" htmlFor="dont-page-email">
    <Input id="dont-page-email" type="email" placeholder="you@example.com" />
  </Field>
</FormLayout>
```

### Accessibility
- The title is the page's `h1`.
- The card is a plain `div`, not a landmark; the shell's `main` holds it.
- Give each control a `Field` with `htmlFor`, so every input has a label.

### Props
### CenteredLayout
A narrow card (`max-w-md`) centred in the Container at a fixed offset from the top, for sign-in, landing, not-found and error pages. The one layout that does not share the left edge.
- subtitle: ReactNode
- title: ReactNode (required)

## Headings

Group: Text

When to use: Any title on a page: the public headline, the page title, a section, a subsection, a dialog.

### The one right way
One `PageHeading` names the page, `SectionHeading` its parts and `SubsectionHeading` what is inside a part.
```tsx
import {
  Body,
  PageHeading,
  SectionHeading,
  Stack,
  SubsectionHeading,
} from "@hackcove/ui";

<Stack gap="sm">
  <PageHeading>Quotes</PageHeading>
  <SectionHeading rule>Open</SectionHeading>
  <SubsectionHeading>Awaiting reply</SubsectionHeading>
  <Body as="p">Three quotes are waiting on the customer.</Body>
</Stack>
```

### Do
- A page has one title: `PageHeading` for an app page, `Display` for the headline of a public page. A `PageHeader` already draws the `PageHeading` and its subtitle, so use it for the top of a page.
- Name the parts of a page with `SectionHeading`; `rule` puts the hairline under it, with the space either side built in.
- Name what is inside a part with `SubsectionHeading`: `size` `sm` (default) is a form-group caption, `base` a card title in a header bar, `lg` a drawer title.
- `ModalHeading` is the title of a dialog or drawer, and `Dialog` and `Drawer` draw it from their `title`. Do not place one on a page.
- Put a `Lead` under a `Display`, and a `Subtitle` under any other heading.
- Pick the heading for its place in the outline, never for its size. `Display` is not a big `SectionHeading`.
- `color` takes `default`, `secondary`, `tertiary`, `muted` or `brand` for the hierarchy of the text. A heading's meaning is carried by its words, not a colour.
- `as` changes the element, only to keep the outline in order, and never the look.

### Don't
`PageHeading` is an `h1`, and a page has one. A second one for a section breaks the outline: use `SectionHeading`.
```tsx
import { Body, PageHeading, Stack } from "@hackcove/ui";

<Stack gap="sm">
  <PageHeading>Quotes</PageHeading>
  <Body as="p">Three quotes are waiting on the customer.</Body>
  <PageHeading>Open</PageHeading>
  <Body as="p">Two quotes are open.</Body>
</Stack>
```

`Display` is marketing scale, not a section title: inside a page it dwarfs everything around it. Use `SectionHeading`.
```tsx
import { Body, Display, PageHeading, Stack } from "@hackcove/ui";

<Stack gap="sm">
  <PageHeading>Dashboard</PageHeading>
  <Display as="h2">Recent activity</Display>
  <Body as="p">Nothing has changed since yesterday.</Body>
</Stack>
```

### Accessibility
- Each heading renders a real heading element: `Display` and `PageHeading` an `h1`, `SectionHeading` and `ModalHeading` an `h2`, `SubsectionHeading` an `h3`.
- `as` swaps the element and keeps the look, so the outline can follow the page without a visual change.
- `id`, `aria-*` and `data-*` go on the heading element.
- `Dialog` and `Drawer` draw their own `ModalHeading` and name themselves by it; an `EmptyState` draws its `SectionHeading` the same way.

### Props
### Display
Marketing-scale headline — the one line at the top of a public page. `h1`, text-4xl/tight semibold, primary text, growing to text-6xl on wider screens. `PageHeading`'s scale is deliberately dev-tool sized; a brochure hero needs a display scale, so it gets its own pinned role rather than callers overriding PageHeading's size.
- as: ElementType
- color: "brand" | "default" | "muted" | "secondary" | "tertiary". Colour token; each component sets a sensible default.

### PageHeading
Page title. `h1`, text-2xl/8 semibold, primary text.
- as: ElementType
- color: "brand" | "default" | "muted" | "secondary" | "tertiary". Colour token; each component sets a sensible default.

### SectionHeading
Top-level section header. `h2`, text-base/6 semibold, primary text. `rule` sets a hairline under it (the `Divider` line colour) with the space either side of the line built in.
- as: ElementType
- color: "brand" | "default" | "muted" | "secondary" | "tertiary". Colour token; each component sets a sensible default.
- rule: boolean

### SubsectionHeading
Nested header. `h3`, text-sm/5 semibold, primary text. `size` steps it up for a card, drawer or form-group title: `sm` (default), `base` (bold) or `lg`.
- as: ElementType
- color: "brand" | "default" | "muted" | "secondary" | "tertiary". Colour token; each component sets a sensible default.
- size: "sm" | "lg" | "base" (default sm)

### ModalHeading
Dialog/modal title. `h2`, text-base/6 semibold, primary text.
- as: ElementType
- color: "brand" | "default" | "muted" | "secondary" | "tertiary". Colour token; each component sets a sensible default.

## Body text

Group: Text

When to use: Every run of text that is not a heading: a paragraph, a supporting line, a note, a label.

### The one right way
Body copy is `Body as="p"`, with `BodyStrong` for emphasis inside it and `Caption` for the fine print.
```tsx
import { Body, BodyStrong, Caption, Stack } from "@hackcove/ui";

<Stack gap="xs">
  <Body as="p">
    Invoice <BodyStrong>INV-204</BodyStrong> is due on Friday.
  </Body>
  <Caption as="p">Sent 2 minutes ago</Caption>
</Stack>
```

### Do
- Set a paragraph in `Body as="p"`. `Body` is a `span` by default so it sits inside a sentence; a block of it stops at a readable line length.
- Emphasise a run with `BodyStrong` inside the `Body`. Use `Caption` for fine print and metadata, as `Caption as="p"` when it stands alone.
- Put `Subtitle` under a heading and `Lead` under a `Display`. `Overline` is the small all-caps label above a group, not a title.
- `tone` says what a run means: `positive`, `warn`, `danger`, `info` or `muted`. It beats `color`, and the words still say it, so colour is never the only signal. `color` is only the hierarchy of the text.
- `numeric` sets tabular figures so a column of amounts lines up, `mono` the monospace face for an id or a path, and `truncate` cuts a run to one line.
- `preserveNewlines` on `Body` keeps the line breaks of text a person typed, such as a note.
- Never write a bare `<p>`, `<span>`, `<strong>` or `<small>`: they carry none of the theme's type scale or colour.

### Don't
Plain HTML text elements carry no size, weight or colour of the theme. Every run of text is a typography part.
```tsx
import { Stack } from "@hackcove/ui";

<Stack gap="xs">
  <p>
    Invoice <strong>INV-204</strong> is due on Friday.
  </p>
  <small>Sent 2 minutes ago</small>
</Stack>
```

`color` is the hierarchy of text, not its meaning: an error in the accent colour reads as a link, and in muted grey as nothing at all.
```tsx
import { Body, Stack } from "@hackcove/ui";

<Stack gap="xs">
  <Body as="p" color="brand">
    Saved.
  </Body>
  <Body as="p" color="muted">
    Could not save: the name is taken.
  </Body>
</Stack>
```

An `Overline` is a `span`, not a heading: a section titled by one has no place in the page outline. Use `SectionHeading`.
```tsx
import { Body, Overline, Stack } from "@hackcove/ui";

<Stack gap="xs">
  <Overline>Invoices</Overline>
  <Body as="p">Two invoices are due this week.</Body>
</Stack>
```

### Accessibility
- `Body`, `BodyStrong`, `Caption` and `Overline` render a `span`, and `Lead` and `Subtitle` a `p`. `as` changes the element, for a `p` or an `li`, or a `label` for an `Overline` with `htmlFor`.
- `Overline` is a label, not a heading: it adds nothing to the page outline.
- `truncate` sets the full text as the `title` when the content is plain text, so a pointer user can read what was cut. Give a `title` of your own when the content is not.
- A `tone` changes only the colour. The wording has to carry the meaning.

### Props
### Body
Default running text. `span` (inline; `as="p"` for a paragraph), text-sm/5 normal, secondary. A block of it stops at a readable line length (`max-w-[72ch]`), wherever it sits. `preserveNewlines` keeps the line breaks in the text (a user-typed note); runs of spaces still collapse. `tone` colours it by meaning (`positive` for "Saved.", `danger` for an error; it wins over `color`), `numeric` sets tabular figures, `mono` the monospace face, and `truncate` cuts it to one line with an ellipsis (the full text becomes its `title`).
- as: any
- color: any. Colour token; each component sets a sensible default.
- mono: boolean. The monospace face, for an id, a path or a command.
- numeric: boolean. Tabular figures, so a column of amounts lines up.
- preserveNewlines: boolean
- tone: "positive" | "danger" | "info" | "warn" | "muted". A meaning's colour (see `TextTone`). Wins over `color`.
- truncate: boolean. One line, cut with an ellipsis where the container ends; the full text is the `title`.

### BodyStrong
Emphasised run of body text. `span`, text-sm/5 medium, primary text. Takes `tone`, `numeric`, `mono` and `truncate` like `Body`.
- as: any
- color: any. Colour token; each component sets a sensible default.
- mono: boolean. The monospace face, for an id, a path or a command.
- numeric: boolean. Tabular figures, so a column of amounts lines up.
- tone: "positive" | "danger" | "info" | "warn" | "muted". A meaning's colour (see `TextTone`). Wins over `color`.
- truncate: boolean. One line, cut with an ellipsis where the container ends; the full text is the `title`.

### Caption
Fine print / metadata. `span` (inline; `as="p"` for a block), text-xs/4 normal, tertiary. Takes `tone`, `numeric`, `mono` and `truncate` like `Body`.
- as: any
- color: any. Colour token; each component sets a sensible default.
- mono: boolean. The monospace face, for an id, a path or a command.
- numeric: boolean. Tabular figures, so a column of amounts lines up.
- tone: "positive" | "danger" | "info" | "warn" | "muted". A meaning's colour (see `TextTone`). Wins over `color`.
- truncate: boolean. One line, cut with an ellipsis where the container ends; the full text is the `title`.

### Overline
Small all-caps label above a group. `span`, text-xs semibold uppercase, tertiary. `tone`, `numeric`, `mono` and `truncate` are opt-in, as on `Body`.
- as: any
- color: any. Colour token; each component sets a sensible default.
- mono: boolean. The monospace face, for an id, a path or a command.
- numeric: boolean. Tabular figures, so a column of amounts lines up.
- tone: "positive" | "danger" | "info" | "warn" | "muted". A meaning's colour (see `TextTone`). Wins over `color`.
- truncate: boolean. One line, cut with an ellipsis where the container ends; the full text is the `title`.

### Lead
The supporting sentence under a `Display`. `p`, text-lg/7 normal, secondary.
- as: ElementType
- color: "brand" | "default" | "muted" | "secondary" | "tertiary". Colour token; each component sets a sensible default.

### Subtitle
Supporting line under a heading. `p`, text-sm/5 normal, secondary.
- as: ElementType
- color: "brand" | "default" | "muted" | "secondary" | "tertiary". Colour token; each component sets a sensible default.

## Code

Group: Text

When to use: A command, name or path inside a sentence is `Code`; several lines of code are a `CodeBlock`.

### The one right way
`Code` is one short run of code inside a sentence: a command, a name, a path.
```tsx
import { Body, Code } from "@hackcove/ui";

<Body as="p">
  Run <Code>bun install</Code> once, then <Code>bunx nx run-many -t test</Code> to check it.
</Body>
```

### Do
- Use `Code` for one short run inside a sentence. It takes the text colour and size around it, and keeps no line breaks.
- Use `CodeBlock` for several lines. Give the text as `children`, or as `lines` with one entry per line.
- `label` names the language or file (`bash`, `css`) in a caption above the code; `language` says what to colour, from `bash`, `css`, `tsx`, `ts` and `json`.
- A line a reader copies is a `CopyLine`, not a one-line `CodeBlock`. A rendered part shown with its code is a `CodeExample`.
- Without a `language` the code is one colour (`text`), which suits an error or a log; a long line wraps rather than scrolling.

### Don't
`Code` is inline, so its line breaks collapse into one run. Several lines are a `CodeBlock`.
```tsx
import { Body, Code } from "@hackcove/ui";

<Body as="p">
  <Code>{"bun install\nbun run build\nbun run test"}</Code>
</Body>
```

One line a reader copies is a `CopyLine`, which has the copy button. A `CodeBlock` of one line has none.
```tsx
import { CodeBlock } from "@hackcove/ui";

<CodeBlock language="bash">bun add @hackcove/ui</CodeBlock>

```

### Accessibility
- `Code` renders a `<code>`. `CodeBlock` renders a `<figure>` with the code in `<pre><code>`, so the line breaks are kept.
- `label` is the `<figcaption>`, which names the figure.
- `CodeBlock` takes `aria-*` and `data-*` on its figure.

### Props
### Code
Inline code: mono, on a subtle inset background. It takes the surrounding text colour and size (a touch smaller, for the mono face).

### CodeBlock
A static multi-line block of code: mono, in a bordered inset box, long lines wrap. No client JS; `language` colours it, and `label` names the language or file (`bash`, `css`) in a caption above the code. `text` (the default) leaves the code in one colour, for a block that is not a language. Give the text as `children` or as `lines`. Every other figure prop goes on the root `<figure>`. For one line a reader copies, use `CopyLine`.
- label: string
- language: "text" | "tsx" | "ts" | "json" | "bash" | "css" (default text). What the code is written in; `text` (the default) colours nothing.
- lines: string[]

## CodeExample

Group: Text

When to use: Documentation that shows a part and its source together.

### The one right way
`CodeExample` frames a rendered part with the code that makes it, in one box.
```tsx
import { Button, CodeExample } from "@hackcove/ui";

<CodeExample code={'<Button variant="primary">Save</Button>'}>
  <Button variant="primary">Save</Button>
</CodeExample>
```

### Do
- Put the rendered part in `children` and its source in `code`, a string with the newlines kept.
- `caption` is one note on the example, the last band of the frame.
- Side by side in a grid, each frame is its own height, so do not pad the previews to match.
- A wide preview or a long line of code scrolls inside the frame; it does not widen the page.
- Only for documentation. A command to copy is a `CopyLine`, and code alone is a `CodeBlock`.

### Don't
A loose preview with a `CodeBlock` under it is two unrelated things: no shared frame, and they drift apart.
```tsx
import { Button, CodeBlock, Stack } from "@hackcove/ui";

<Stack gap="sm">
  <Button variant="primary">Save</Button>
  <CodeBlock>{'<Button variant="primary">Save</Button>'}</CodeBlock>
</Stack>
```

### Accessibility
- A `<figure>` holds the preview and the code in `<pre><code>`; `caption` is its `<figcaption>`.
- `aria-*` and `data-*` go on the figure.

### Props
### CodeExample
One framed example: the rendered `children` on top and the `code` that makes them attached underneath, in a single bordered box with one divider between. No client JS. An optional `caption` is the frame's last band. The code is React, so it is coloured as TSX. The preview is its own height, never padded to match a neighbour, down to a shared minimum so two frames side by side start alike. A wide preview or a long line of code scrolls inside the frame instead of widening the page or wrapping.
- caption: ReactNode. One note on the example, under the code.
- code: string (required). The source shown under the preview, newlines kept.

## Kbd

Group: Text

When to use: A key or a shortcut the reader presses: `Esc`, `?`, `⌘S`.

### The one right way
`Kbd` is a key the reader presses: in a sentence, or as the shortcut on a button.
```tsx
import { Body, Kbd } from "@hackcove/ui";

<Body as="p">
  Press <Kbd>Esc</Kbd> to close this list, or <Kbd>⌘S</Kbd> to save.
</Body>
```

### Do
- Use `Kbd` for a key the reader presses, in a sentence or as the shortcut on a `Button`.
- A command or a name is `Code`, never `Kbd`.

### Don't
A command is `Code`, not a key. `Kbd` draws a keycap, which says "press this".
```tsx
import { Body, Kbd } from "@hackcove/ui";

<Body as="p">
  Run <Kbd>bun install</Kbd> to install.
</Body>
```

### Accessibility
- `Kbd` renders a `<kbd>` element, which marks the text as keyboard input.
- Its border takes the colour of the text around it, so it reads on plain text and on a filled button.

### Props
### Kbd
A keyboard key. Its border takes the surrounding text colour, so it reads on a filled button and on plain text.

## Markdown

Group: Text

When to use: Text that arrives as markdown, such as an agent's summary, shown on a page.

### The one right way
`Markdown` renders `##` and `###` headings, `-` bullets, `**bold**` and plain paragraphs, as text nodes and never as HTML.
```tsx
import { Markdown } from "@hackcove/ui";

<Markdown
  md={
    "## What I did\n- **HC-142** shipped the EmptyState\n- Fixed the Pill label wrap\n\n" +
    "### Next\nReview the Steps copy."
  }
/>
```

### Do
- Pass the markdown as `md`. It renders `##` as a label heading, `###` as a subheading, lines starting `- ` or `* ` as bullets, `**bold**` and plain paragraphs.
- Nothing else is supported: no `#` title, numbered list, link, code span, table or HTML. Those show as plain text.
- The text becomes React nodes and never HTML, so untrusted text cannot inject markup.
- Text you write yourself is not markdown: use `Body`, `BulletList` and the heading components.

### Don't
A `#` title, a numbered list, a link or a code span is not supported: each shows as literal text.
```tsx
import { Markdown } from "@hackcove/ui";

<Markdown
  md={
    "# What I did\n1. Shipped the EmptyState\n2. Fixed the Pill\n\n" +
    "See [the ticket](https://example.com) and `bun install`."
  }
/>
```

### Accessibility
- `##` renders an `h2` and `###` an `h3`, bullets render a `ul` with `li`s, bold a `strong` and a paragraph a `p`.
- The headings start at `h2`, so the page needs its own `h1` above.
- `aria-*` and `data-*` go on the root.

### Props
### Markdown

- md: string (required)

## TextLink

Group: Text

When to use: A link that sits in text. A link that is an action is a `ButtonLink`.

### The one right way
A link in running text is a `TextLink` inside a `Body`.
```tsx
import { Body, TextLink } from "@hackcove/ui";

<Body as="p">
  Questions? Email <TextLink href="mailto:hello@example.com">hello@example.com</TextLink>, or
  read the <TextLink href="#terms">terms</TextLink> first.
</Body>
```

### Do
- Use `TextLink` for every link in running text. Never a bare `<a>`.
- `external` is for another site: it opens a new tab with `rel="noreferrer"`.
- In an app with a router, `render` draws the router's own `<Link>`: `render={(p) => <Link to="/terms" {...p} />}`. The library has no router.
- `size` pins the type size to `xs` or `sm`; left out, the link takes the size of its text. `mono` sets the monospace face for a path or an id.
- `tone` gives the link a meaning's colour (`warn`, `danger`, `positive`, `info`, `muted`), underlined on hover. Use it for a link that is the message, like "3 failed".
- `stretch` makes the nearest `relative` ancestor the click target: a `Card` or a `TableRow`. Put it on the one link in that row.
- A router's own `<Link>` that must look like a `TextLink` takes `linkClass`, and a stretched one `linkStretchClass` as well.

### Don't
A bare `<a>` has none of the theme's link colour, weight or focus ring.
```tsx
import { Body } from "@hackcove/ui";

<Body as="p">
  Questions? Email <a href="mailto:hello@example.com">hello@example.com</a>, or read the{" "}
  <a href="#terms">terms</a> first.
</Body>
```

`target="_blank"` by hand leaves out the `rel`. Say `external` and the link gets both.
```tsx
import { TextLink } from "@hackcove/ui";

<TextLink href="https://example.com" target="_blank">
  example.com
</TextLink>
```

### Accessibility
- A `TextLink` is a native `<a>`, so it is in the tab order and opens with Enter.
- It has a focus ring from the component, so the keyboard focus is always visible.
- `external` sets `target="_blank"` and `rel="noreferrer"`.
- Every anchor prop (`aria-*`, `download`, `title`, a handler) goes on the `<a>`; `render` receives them as well.

### Props
### TextLink
An inline text link in the accent colour. Every anchor prop goes on the `<a>`. With `render` it draws the app's own router `<Link>` instead (`render={(p) => <Link to="/terms" {...p} />}`). `size` pins the type size (`xs` or `sm`), `tone` gives it a meaning's colour and `mono` sets the monospace face.
- external: boolean (default false). Opens in a new tab: adds `target="_blank"` and `rel="noreferrer"`.
- href: string
- mono: boolean (default false). The monospace face, for a path, an id or a command.
- render: LinkRender
- size: "sm" | "xs". The link's own type size. Left out, it takes the size of the text around it.
- stretch: boolean (default false). The link covers its nearest `relative` ancestor, so the whole row or card is the click target.
- tone: "positive" | "danger" | "info" | "warn" | "muted". A meaning's colour, as on the inline roles: `warn` for a warning link, `danger`, `positive`,
`info` or `muted`. Left out, the link is the accent colour.

### Functions
- linkClass: The classes of an inline text link, for a router's own `<Link>` that must look like a `TextLink`.
- linkStretchClass: Stretches a link's hit area over its nearest `relative` ancestor, so a whole row or card opens it; add it to the one link in the row.

## InlineLinks

Group: Text

When to use: A footer or a row of related links: Privacy, Terms, Contact.

### The one right way
A row of links is `InlineLinks`: it spaces them, wraps them and hides the separator from a screen reader.
```tsx
import { InlineLinks, TextLink } from "@hackcove/ui";

<InlineLinks>
  <TextLink href="#privacy">Privacy</TextLink>
  <TextLink href="#terms">Terms</TextLink>
  <TextLink href="#contact">Contact</TextLink>
</InlineLinks>
```

### Do
- Put one `TextLink` per child. The row wraps and spaces them.
- `separator` is `·` (default), `•` or `none`.
- Never type the separators yourself: they wrap onto the end of a line and a screen reader reads them.
- A row of facts that are not links is a `MetaList`.

### Don't
Separators typed by hand are read aloud and can wrap onto the end of a line.
```tsx
import { Body, TextLink } from "@hackcove/ui";

<Body as="p">
  <TextLink href="#privacy">Privacy</TextLink> | <TextLink href="#terms">Terms</TextLink> |{" "}
  <TextLink href="#contact">Contact</TextLink>
</Body>
```

### Accessibility
- The separators are `aria-hidden` and lead every link but the first, held to their link so a wrap never leaves one at the end of a line.
- Each link keeps its own focus ring; the row adds no extra tab stop.
- `aria-*` and `data-*` go on the root.

### Props
### InlineLinks
A wrapping row of links, small text, joined by a separator. The separator is `aria-hidden` and leads each link but the first, held to its link so a wrap never leaves one at a line's end.
- separator: "none" | "·" | "•" (default ·)

## BulletList

Group: Text

When to use: Items that read as a list of points: what changed, what to bring.

### The one right way
A list is a `BulletList` of `Body as="li"`: the list owns the discs, the indent and the gap.
```tsx
import { Body, BulletList } from "@hackcove/ui";

<BulletList>
  <Body as="li">Moved the nightly build from cron to a queue.</Body>
  <Body as="li">Cut the cold start from nine seconds to two.</Body>
  <Body as="li">Wrote the runbook the team still uses.</Body>
</BulletList>
```

### Do
- Give a `BulletList` `<li>` children, set in `Body as="li"`.
- Never type a hyphen into a paragraph to make a list.
- Items that have a label and a value are a `KeyValueList`; a list of records is a `Table` or a `ListRow`.

### Don't
Hyphens typed into paragraphs are not a list: no discs, no indent and no list for a screen reader.
```tsx
import { Body, Stack } from "@hackcove/ui";

<Stack gap="xs">
  <Body as="p">- Moved the nightly build from cron to a queue.</Body>
  <Body as="p">- Cut the cold start from nine seconds to two.</Body>
  <Body as="p">- Wrote the runbook the team still uses.</Body>
</Stack>
```

### Accessibility
- A `BulletList` renders a `<ul>`, so a screen reader announces a list and the number of items.
- `id`, `aria-*` and `data-*` go on the list.

### Props
### BulletList
A bulleted `<ul>`: discs, indented, a small gap between items. Its children are `<li>`s (e.g. `Body as="li"`).

## MetaList

Group: Text

When to use: The facts about a record under its title: branch, SHA, date.

### The one right way
A row of facts is a `MetaList`; an item is text, a `Code` or a `TextLink`.
```tsx
import { Code, MetaList, TextLink } from "@hackcove/ui";

<MetaList>
  <TextLink href="#hc-145">hc-145</TextLink>
  <Code>0f9d376</Code>
  <span>26 Oct 2026</span>
</MetaList>
```

### Do
- Each child is one fact: text, a `Code` or a `TextLink`.
- `mono` sets the whole row in the monospace face, for ids and paths.
- Never type the dots into one string: they wrap onto the end of a line and a screen reader reads them.
- A row of links is `InlineLinks`; a labelled fact is a `KeyValueList`.

### Don't
Dots typed into one string are one item to a screen reader and can wrap onto the end of a line.
```tsx
import { Caption } from "@hackcove/ui";

<Caption as="p">hc-145 · 0f9d376 · 26 Oct 2026</Caption>

```

### Accessibility
- A `MetaList` renders a `<ul>` with an `<li>` per fact.
- The `·` separators are `aria-hidden`, so a screen reader reads the facts alone.
- `aria-*` and `data-*` go on the list.

### Props
### MetaList
A wrapping row of facts in muted small text, joined by a `·`: branch · SHA · date. An item is text, a `Code` or a `TextLink`. The separator is `aria-hidden` and leads each item but the first, held to its item so a wrap never leaves one at a line's end. `mono` sets the whole row in the monospace face, for ids and paths.
- mono: boolean (default false)

## Card

Group: Content

When to use: A titled block of related content: a record, a status, a list, an empty state.

### The one right way
`status` puts a Pill directly beside the title; `actions` stays at the far end.
```tsx
import { Card, Empty, Pill } from "@hackcove/ui";

<Card title="PixelSlash" status={<Pill tone="amber">Coming soon</Pill>}>
  <Empty>Visual review for every pull request.</Empty>
</Card>
```

### Do
- Name the Card with `title`; add a `count` or a `status` and they sit beside the title.
- `actions` sit at the far end of the header; use `bar` to put the header in a tinted strip.
- Space several Cards with a `Stack` or a `CardGrid`; never stack them with nothing between.
- `flush` is for a table that runs edge to edge, and it needs a `bar` for its title.
- `footer` is a strip across the bottom for the card's own actions or a total; it stays at the foot of a stretched card in a `CardGrid`.
- `CardGrid` takes `columns` 2, 3 or 4, or `columns="auto"` with `minWidth` `sm` or `md` to fill by width; `align="start"` stops cards stretching to the tallest in their row.
- `dashed` is the empty state.

### Don't
A hand-built title row drifts from every other Card's: use `title` and `status`.
```tsx
import { Card, Empty, Pill, SubsectionHeading } from "@hackcove/ui";

<Card>
  <SubsectionHeading>PixelSlash</SubsectionHeading>
  <Pill tone="amber">Coming soon</Pill>
  <Empty>Visual review for every pull request.</Empty>
</Card>
```

Cards with nothing between them butt together. Space them with `Stack` or `CardGrid`.
```tsx
import { Card, Empty } from "@hackcove/ui";

<>
  <Card title="Open" count={3}>
    <Empty>Three things to do.</Empty>
  </Card>
  <Card title="Done" count={12}>
    <Empty>Twelve things finished.</Empty>
  </Card>
</>
```

### Accessibility
- A Card is a `<section>` by default and its `title` names it; `as` picks another element, e.g. `article`.
- `id`, `data-*` and `aria-*` go on the root element.

### Props
### Card
A bordered panel with an optional title, count and status; `as` picks the element (default `section`). Three opt-in forms for data views: `flush` drops the padding and clips the corners, for a table that runs edge to edge; `bar` puts the title, count and `actions` in a tinted strip across the top, over the body; `dashed` is an empty-state shell, a dashed outline with centred muted text. `dashed` stands alone: it ignores `flush` and `bar`; `dashed="filled"` is the same shell on a surface fill with more padding, for an empty state that must read as a panel. A flush card has no padding for a `title`, so give it a `bar`. `size="sm"` is the dense padding, the same on a `ListRow` and a `FileDrop`. `tone` is the Callout's set, for a data panel that carries a status (a soft fill and border, no shadow); a message is still a `Callout`, and `bar` and `dashed` have no tone. Other props (`id`, `data-*`, `aria-*`) go on the root. The root is `relative`, so a `TextLink stretch` inside it covers the card. `footer` is a tinted strip across the bottom, under a hairline, for the card's own actions or a total; in a `CardGrid` it stays at the foot of a card that is stretched to the row's height. It suits a panel, not a card that is a link, and `dashed` has none. `href` makes the whole card one link: the root is an `<a>` with a hover border and the focus ring, so it takes no `actions` and no `as`. With `render` it draws the app's own router `<Link>` (`render={(p) => <Link to="/shots/1" {...p} />}`). `external` opens it in a new tab.
- actions: ReactNode. Buttons or links at the end of the header: in the strip with `bar`, else beside the title.
A card that is a link has nothing else to click: no `actions`.
- as: "article" | "div" | "section". A card that is a link is the link: no `as`.
- bar: boolean. Put the title, count and actions in a tinted strip above the body, edge to edge.
- count: number
- dashed: boolean | "filled". An empty-state shell: dashed outline, no shadow, no fill, centred muted text. `"filled"` puts it on a surface fill with more padding.
- external: boolean. Opens in a new tab: adds `target="_blank"` and `rel="noreferrer"`.
- flush: boolean. No padding and `overflow-hidden`: the body (a table, a list) fills the card.
- footer: ReactNode. A tinted strip across the bottom of the card, under a hairline, for the card's own actions or a total. It stays at the foot when the card is stretched in a `CardGrid`. Ignored with `dashed`.
A card that is a link has nothing else to click: no `footer`.
- href: string
- render: LinkRender
- size: "sm" | "md". `sm` is dense padding on the body, heading and bar; a `dashed` shell keeps its own. Defaults to `md`.
- status: ReactNode. A `Pill` (or any node) directly beside the title and count, not at the far end like `actions`. Needs a `title`.
- title: string
- tone: "positive" | "danger" | "neutral" | "info" | "warn". A soft fill and border in the Callout's tones, for a data panel with a status. Ignored with `bar` and `dashed`.

## Empty

Group: Content

When to use: A short note inside a Card or a list that has nothing to show; a whole empty view is an `EmptyState`.

### The one right way
`Empty` is the one muted line inside a Card that has nothing to show yet.
```tsx
import { Card, Empty } from "@hackcove/ui";

<Card title="Done" count={0}>
  <Empty>Nothing finished yet.</Empty>
</Card>
```

### Do
- Use `Empty` for one short sentence in a muted tone: "Nothing finished yet."
- Put it inside a `Card` (give the Card its `title` and `count`) or under a list; do not style a paragraph by hand.
- A whole page or list with nothing in it, and a way forward, is an `EmptyState` with its `actions`, not an `Empty`.
- `Empty` is not a place for a button or a link; if the person needs to do something next, use `EmptyState`.

### Don't
A bare `<p>` in a Card has its own colour and size, so it drifts from every other empty Card: use `Empty`.
```tsx
import { Card } from "@hackcove/ui";

<Card title="Done" count={0}>
  <p>Nothing finished yet.</p>
</Card>
```

`Empty` is one muted line, not a view: with a button under it nothing says what the page is for. Use `EmptyState`.
```tsx
import { Button, Empty, Stack } from "@hackcove/ui";

<Stack>
  <Empty>No projects yet.</Empty>
  <Button>Create a project</Button>
</Stack>
```

### Accessibility
- `Empty` is a plain `<p>`: it is read in order with the rest of the Card, with no role of its own.
- `aria-*` and `data-*` props go on the paragraph.

### Props
### Empty


## EpicHeader

Group: Content

When to use: Heading a group of tasks that share an epic, in a list grouped by `groupByEpic`.

### The one right way
`groupByEpic` orders the groups, real epics first by ref and "No epic" last; an `EpicHeader` heads each one.
```tsx
import { Body, Card, EpicHeader, groupByEpic } from "@hackcove/ui";

<Card title="Open work" count={3}>
  {groupByEpic(
    [
      { task: "Record a voice note", epic: "HC-42", colour: "#cba6f7" },
      { task: "Tidy the settings page", epic: null, colour: "#9399b2" },
      { task: "Transcribe the note", epic: "HC-42", colour: "#cba6f7" },
    ],
    (item) => item.epic,
  ).map(([epic, items]) => (
    <div key={epic ?? "none"}>
      <EpicHeader color={items[0]?.colour ?? "#9399b2"} label={epic ?? "No epic"} />
      {items.map((item) => (
        <Body as="p" key={item.task}>
          {item.task}
        </Body>
      ))}
    </div>
  ))}
</Card>
```

### Do
- Group the items with `groupByEpic(items, (item) => item.epic)` and put one `EpicHeader` over each group.
- `color` is the epic's own colour, a CSS colour from your data; `label` is the epic's name. The no-epic group has a `null` key: give it a label such as "No epic".
- `EpicHeader` is a row of data, not a heading. Title a section with `SectionHeading` or a `Card` `title`.

### Don't
`EpicHeader` is a row of epic data with a dot in the epic's own colour, not a heading: a section is titled with `SectionHeading` or a Card `title`.
```tsx
import { Body, EpicHeader, Stack } from "@hackcove/ui";

<Stack>
  <EpicHeader color="#cba6f7" label="Settings" />
  <Body as="p">Choose how the site looks and what it tells you about.</Body>
</Stack>
```

### Accessibility
- The dot is decoration with no text alternative; the `label` carries the meaning, so the colour is never the only signal.
- The row is a `<div>`, not a heading element, so it does not appear in a screen reader's heading outline.
- `aria-*` and `data-*` props go on the root element.

### Props
### EpicHeader
A coloured epic header row: a dot in the epic's colour + its label.
- color: string (required)
- label: string (required)

### Functions
- groupByEpic: Groups items by their epic ref, real epics first in ref order and the items with no epic (`null`) last; returns `[epic, items][]` to map over.

## PageTitle

Group: Content

When to use: Never in new code: use `PageHeader`, which also takes breadcrumbs, actions and tabs.

### The one right way
`PageHeader` is the top of a page: a title, a subtitle, and the fixed margin that puts every page's first block at the same height.
```tsx
import { PageHeader } from "@hackcove/ui";

<PageHeader title="Status" subtitle="What is happening now" />

```

### Do
- Use `PageHeader` for the top of every page. `PageTitle` is the same title and subtitle without the bottom margin, so a page that uses it sits at a different height from the rest.
- Move existing `PageTitle` uses to `PageHeader`; it takes the same `title` and `subtitle`.

### Don't
`PageTitle` is deprecated and has no bottom margin, so a page that uses it sits at a different height. Use `PageHeader`.
```tsx
import { PageTitle } from "@hackcove/ui";

<PageTitle title="Status" subtitle="What is happening now" />

```

### Accessibility
- The `title` is the page's `<h1>`, with the `subtitle` under it, as in `PageHeader`.
- `aria-*` and `data-*` props go on the root element.

### Props
### PageTitle

- subtitle: string
- title: string (required)

## Avatar

Group: Content

When to use: Marking who did something or who owns something, next to their name.

### The one right way
Give the person's full name every time: the same name gets the same colour and initials in every list and header.
```tsx
import { Avatar, Cluster } from "@hackcove/ui";

<Cluster>
  <Avatar name="Ada Lovelace" />
  <Avatar name="Ada Lovelace" size="lg" />
  <Avatar name="Grace Hopper" />
</Cluster>
```

### Do
- Pass the person's full `name`, the same string everywhere: the colour and the initials are worked out from it, so one person looks the same in every list and header.
- `size` is `sm`, `md` (default), `lg`, `xl` or `2xl`; use `sm` or `md` in a row and a larger one at the head of a profile.
- `src` is the person's photo, as a path your app serves. It replaces the initials, and the Avatar never loads an image from another server on its own, so use your own local image.
- `ring` is for a stack of overlapping Avatars: each one overlaps the one before it, with a ring in the page colour. Leave it off a single Avatar.
- Put the person's name beside the Avatar as text; the Avatar is a mark, not a label.

### Don't
The colour comes from the name, so "Ada" in one place and "A. Lovelace" in another read as two different people.
```tsx
import { Avatar, Cluster } from "@hackcove/ui";

<Cluster>
  <Avatar name="Ada" />
  <Avatar name="A. Lovelace" />
</Cluster>
```

An initials Avatar on its own is `aria-hidden`: it names no one to a screen reader. Put the name beside it.
```tsx
import { Avatar } from "@hackcove/ui";

<Avatar name="Ada Lovelace" />

```

### Accessibility
- Initials are drawn in a `<span>` with `aria-hidden="true"` and a `title` of the name, so a screen reader skips them: the name has to be on the page as text.
- With `src` the Avatar is an `<img>` whose `alt` and `title` are the name.
- `aria-*` and `data-*` props go on the root element.

### Props
### Avatar
A person as a round badge of initials, or as their photo when `src` is given. It never loads a remote image on its own: that is a request to another server for decoration, and it makes a screenshot depend on the network. `src` is the app's own local path.
- name: string (required)
- ring: boolean (default false). A ring in the page colour, for a stack of overlapping avatars.
- size: "sm" | "md" | "lg" | "xl" | "2xl" (default md)
- src: string. The person's photo, a local path. It replaces the initials and is announced as `name`.

### Functions
- initialsOf: The up to two letters or digits of a name, upper-cased, or `?` when it has none: the same initials `Avatar` draws, for where you need them as text.
- avatarColourClass: The background class `Avatar` picks for a name, so the same name always gets the same colour. `Avatar` applies it for you; pass `name` to `Avatar` instead of using it.

## Badge

Group: Content

When to use: A count of unread or pending things that sits on an icon button.

### The one right way
`badge` on an `IconButton` pins the count to the corner and adds it to the button's name ("Alerts, 3").
```tsx
import { IconButton } from "@hackcove/ui";

<IconButton label="Alerts" badge={3}>
  <svg viewBox="0 0 20 20" width="20" height="20" fill="currentColor" aria-hidden="true">
    <path
      d="M10 2a5 5 0 0 0-5 5v2.6c0 .5-.2 1-.5 1.4L3.3 12.5a.75.75 0 0 0 .55 1.25
      h12.3a.75.75 0 0 0 .55-1.25L15.5 11a2 2 0 0 1-.5-1.4V7a5 5 0 0 0-5-5Z
      m-1.9 13.5a2 2 0 0 0 3.8 0H8.1Z"
    />
  </svg>
</IconButton>
```

### Do
- On an icon, give the `IconButton` a `badge` count; it pins the Badge to the corner and puts the count in the button's name.
- A `count` above 99 reads `99+`.
- Show a Badge only when there is something to count: a `count` of 0 still draws a `0`, so leave it out instead.
- A tinted label with words in it is a `Pill`, not a Badge.

### Don't
A Pill beside the button is not pinned to it and a screen reader never hears it as part of the button. Use `badge`.
```tsx
import { Cluster, IconButton, Pill } from "@hackcove/ui";

<Cluster>
  <IconButton label="Alerts">
    <svg viewBox="0 0 20 20" width="20" height="20" fill="currentColor" aria-hidden="true">
      <path
        d="M10 2a5 5 0 0 0-5 5v2.6c0 .5-.2 1-.5 1.4L3.3 12.5a.75.75 0 0 0 .55 1.25
        h12.3a.75.75 0 0 0 .55-1.25L15.5 11a2 2 0 0 1-.5-1.4V7a5 5 0 0 0-5-5Z
        m-1.9 13.5a2 2 0 0 0 3.8 0H8.1Z"
      />
    </svg>
  </IconButton>
  <Pill tone="red" round>
    3
  </Pill>
</Cluster>
```

### Accessibility
- A Badge is a `<span>` with the number as its text.
- Inside an `IconButton`, the Badge is `aria-hidden` and the count is part of the button's `aria-label` and `title` ("Alerts, 3"), so it is announced once.
- `corner` pins the Badge to its nearest positioned parent; `IconButton` already provides one.

### Props
### Badge
A small red count, 10px, for sitting on an icon. `corner` pins it to the top-right corner of its `relative` parent (wrap the icon button and the badge in a `relative inline-flex` element); a count above 99 reads `99+`. Name the control it sits on (`aria-label` on the button) for a screen reader. An `IconButton` takes `badge` itself and does all of this.
- corner: boolean (default false)
- count: number (required)

## Pill

Group: Content

When to use: A short word that says what state or kind something is: paid, draft, flaky.

### The one right way
The tone carries the meaning: emerald for done, amber for waiting, red for failed, slate for neutral.
```tsx
import { Cluster, Pill } from "@hackcove/ui";

<Cluster>
  <Pill tone="emerald" dot>
    Paid
  </Pill>
  <Pill tone="amber" dot>
    Due
  </Pill>
  <Pill tone="red" dot>
    Overdue
  </Pill>
  <Pill dot>Draft</Pill>
</Cluster>
```

### Do
- Choose `tone` by meaning: `emerald` for done or good, `amber` for waiting or at risk, `red` for failed, `slate` for neutral or draft; `blue`, `sky` and `violet` for kinds and categories.
- `dot` adds a leading dot in the Pill's colour; `round` swaps the rounded-square corners for a full pill shape. Use one look across a view.
- A Pill that goes somewhere takes `href` (or `render` for your router's `Link`, `external` for a new tab); one that does something takes `onClick`.
- A Pill beside a card's title is the Card's `status`, not a hand-built row.
- A message to read is a `Callout`, and an action is a `Button`.

### Don't
One tone for every status says nothing: a reader cannot tell Paid from Overdue at a glance. Pick the tone by what the status means.
```tsx
import { Cluster, Pill } from "@hackcove/ui";

<Cluster>
  <Pill tone="violet" dot>
    Paid
  </Pill>
  <Pill tone="violet" dot>
    Due
  </Pill>
  <Pill tone="violet" dot>
    Overdue
  </Pill>
</Cluster>
```

A Pill inside a `TextLink` is two parts doing one job, and the Pill's own hover dim and focus ring go unused. Give the Pill the `href`.
```tsx
import { Pill, TextLink } from "@hackcove/ui";

<TextLink href="#flakes">
  <Pill tone="amber" round>
    3 flaky
  </Pill>
</TextLink>
```

### Accessibility
- A plain Pill is a `<span>`; the dot is `aria-hidden`. The tone is colour only, so the text must say the status itself.
- With `href` it is a link and with `onClick` a `<button type="button">`; both dim on hover and show the focus ring.
- `external` adds `target="_blank"` and `rel="noreferrer"`.

### Props
### Pill
A small tinted label; `dot` adds a leading dot in the pill's own text colour, `round` swaps the rounded-md corners for a full pill shape. `href` makes it a link (a plain `<a>`, or with `render` the app's own router `<Link>`: `render={(p) => <Link to="/flakes" {...p} />}`; `external` opens a new tab) and `onClick` makes it a button, each with a hover dim and the focus ring.
- dot: boolean (default false)
- external: boolean (default false). Opens in a new tab: adds `target="_blank"` and `rel="noreferrer"`.
- href: string
- onClick: MouseEventHandler<HTMLButtonElement>. A Pill that is a button: runs `onClick`. Defaults to `type="button"`.
- render: LinkRender
- round: boolean (default false)
- tone: "slate" | "amber" | "emerald" | "blue" | "red" | "violet" | "sky" (default slate)

## Steps

Group: Content

When to use: The way into a product: install, log in, run.

### The one right way
`Steps` numbers itself: give each `Step` a `title` and a line of detail, in the order they are done.
```tsx
import { Code, Step, Steps } from "@hackcove/ui";

<Steps aria-label="Get started">
  <Step title="Install the CLI">
    Run <Code>bun add -d pixelslash</Code> in your repo.
  </Step>
  <Step title="Upload a build">
    Run <Code>pixelslash upload</Code>.
  </Step>
</Steps>
```

### Do
- Give each `Step` a `title` and, as its children, one line of detail. A step with only a `title` is fine.
- Do not type the numbers: `Steps` counts them, so a step can sit behind a condition and the rest still run 1, 2, 3.
- For things done in order only. Nothing here is done or current, so it is not a progress indicator.
- A list with no order is a `BulletList`.
- In an empty view, put `Steps` inside the `EmptyState` as the "get started" list.

### Don't
Typed numbers double up with the ones `Steps` draws, and drift when a step is added. Leave the numbering to `Steps`.
```tsx
import { Step, Steps } from "@hackcove/ui";

<Steps aria-label="Get started">
  <Step title="1. Install the CLI">Run bun add -d pixelslash in your repo.</Step>
  <Step title="2. Upload a build">Run pixelslash upload.</Step>
</Steps>
```

Numbering features that have no order tells the reader there is a sequence to follow. Use a `BulletList`.
```tsx
import { Step, Steps } from "@hackcove/ui";

<Steps>
  <Step title="Light and dark themes" />
  <Step title="Keyboard shortcuts" />
  <Step title="Email digests" />
</Steps>
```

### Accessibility
- `Steps` is an `<ol role="list">` and each `Step` an `<li>`, so a screen reader announces the list and each step's position.
- The drawn number is `aria-hidden`, so it is not read twice.
- Name the list with `aria-label`.

### Props
### Steps
A numbered list of things to do, in order: a `title` and, under it, a line of `children`. The numbers are counted by CSS, so `Step`s can sit in a fragment or behind a condition and still run 1, 2, 3. For the way into a product ("install, log in, run"), not for progress: nothing here is done or current. A wizard's progress indicator is a different part (HC-108, `Stepper`).

### Step
One step of `Steps`: a `title` in medium weight and the `children` as the detail under it.
- title: ReactNode (required)

## Timeline

Group: Content

When to use: A history of what happened and when: status changes, a record's activity.

### The one right way
A `title` (a Pill or a short label), the `time` already formatted for the reader, and a note under them.
```tsx
import { Pill, Timeline, TimelineItem } from "@hackcove/ui";

<Timeline label="Status history">
  <TimelineItem
    tone="positive"
    title={<Pill tone="emerald">accepted</Pill>}
    time="12 Oct 2026, 09:14"
  >
    Client confirmed by phone.
  </TimelineItem>
  <TimelineItem title={<Pill tone="amber">sent</Pill>} time="10 Oct 2026, 16:02" />
</Timeline>
```

### Do
- Name the list with `label`, and order the `TimelineItem`s yourself, newest or oldest first.
- A `TimelineItem` has a `title` (a `Pill` or a short label), a `time` you have already formatted for the reader, and an optional note as its children.
- `tone` colours the marker dot with the Callout's set (`neutral`, `info`, `positive`, `warn`, `danger`); `neutral` is a plain ring.
- Give the Timeline an `empty` to draw when there are no items; without one it draws nothing.
- Numbered instructions are `Steps`, not a Timeline.

### Don't
`time` is drawn as given: a raw ISO string reads as machine output. Format it before it gets here.
```tsx
import { Timeline, TimelineItem } from "@hackcove/ui";

<Timeline label="Status history">
  <TimelineItem title="accepted" time="2026-10-12T09:14:00.000Z">
    Client confirmed by phone.
  </TimelineItem>
  <TimelineItem title="sent" time="2026-10-10T16:02:00.000Z" />
</Timeline>
```

### Accessibility
- `Timeline` is an `<ol>` named by `label` (`aria-label`), and each `TimelineItem` is an `<li>`.
- The marker dot is `aria-hidden`, so `tone` is colour only: say the outcome in the `title`.
- `time` is plain text, as you formatted it.

### Props
### Timeline
A vertical list of events, newest or oldest first as the caller orders them. A named `<ol>` of `TimelineItem`s on a rail; with no children it draws `empty` instead of an empty list.
- empty: ReactNode. Drawn in place of the list when there are no items.
- label: string (required). Names the list (`aria-label`), e.g. "Status history".

### TimelineItem
One event: a `title` (a `Pill`, a heading), a `time` the app has already formatted, and the `children` as a note under them. `tone` colours the marker dot with the Callout's set.
- time: ReactNode
- title: ReactNode (required)
- tone: "positive" | "danger" | "neutral" | "info" | "warn" (default neutral). The marker dot's colour. Defaults to `neutral`, a plain ring.

## KeyValueList

Group: Content

When to use: A set of facts about one thing: size, status, dates, shortcut keys.

### The one right way
Label and value pairs are a `KeyValueList`: one row per fact, the label muted, the value in tabular figures.
```tsx
import { KeyValue, KeyValueList } from "@hackcove/ui";

<KeyValueList>
  <KeyValue label="Size">1280×720</KeyValue>
  <KeyValue label="Changed pixels">0.4%</KeyValue>
  <KeyValue label="Captured">2 min ago</KeyValue>
</KeyValueList>
```

### Do
- Put a `KeyValue` with a `label` for each fact; the value is its children.
- `align="end"` is the default: each label at the left and its value right-aligned. `align="start"` puts every value left-aligned in one column beside the labels, which suits long values.
- A value can be any content, such as a `Kbd` for a shortcut.
- Do not build the rows by hand from a `Cluster`; a grid of records is a `Table`.

### Don't
Rows built by hand from a `Cluster` and `Body` drift from the list's label colour and figures. Use `KeyValueList`.
```tsx
import { Body, Cluster, Stack } from "@hackcove/ui";

<Stack gap="xs">
  <Cluster justify="between">
    <Body>Size</Body>
    <Body>1280×720</Body>
  </Cluster>
  <Cluster justify="between">
    <Body>Changed pixels</Body>
    <Body>0.4%</Body>
  </Cluster>
</Stack>
```

### Accessibility
- `KeyValueList` is a `<dl>`; each `KeyValue` is a `<div>` holding a `<dt>` for the label and a `<dd>` for the value, so a screen reader announces them as terms and definitions.
- `id`, `data-*` and `aria-*` go on the list and on each row.

### Props
### KeyValueList
A definition list of label/value rows. By default each label is on the left and its value right-aligned. `align="start"` puts every value left-aligned in one column beside the labels, which are sized to the widest.
- align: "end" | "start" (default end)

### KeyValue
One row of a KeyValueList: a label on the left, a tabular value on the right (or beside it, in an `align="start"` list).
- label: ReactNode (required)

## Video

Group: Content

When to use: Showing a recording or a walkthrough that your app serves.

### The one right way
`captions` is a WebVTT file offered as the default track; `children` is the text for a browser that cannot play it.
```tsx
import { Video } from "@hackcove/ui";

<Video src="/media/walkthrough.webm" captions="/media/walkthrough.vtt">
  Your browser cannot play this video.
</Video>
```

### Do
- `src` is your own video file. It loads only the metadata until it is played, so the page does not pull the whole file.
- Give a `captions` WebVTT file for any video with speech; it is offered as the default track.
- `poster` is the image shown before play; use a local one.
- The children are the text for a browser that cannot play the video.

### Don't
A video with speech and no `captions` leaves out anyone who cannot hear it.
```tsx
import { Video } from "@hackcove/ui";

<Video src="/media/walkthrough.webm" />

```

### Accessibility
- A native `<video controls>`: play, seek, volume and fullscreen work by keyboard through the browser's controls.
- `captions` adds a `<track kind="captions" default>`, so captions are on by default.

### Props
### Video
A `<video>` with controls, full width and rounded; it loads metadata only, so the page does not pull the file until it is played. `src` is the app's own video; `captions` is a WebVTT file, offered as the default track. `children` is the fallback for a browser that cannot play it.
- captions: string
- src: string (required)

## Button

Group: Actions

When to use: An action that changes something in place: save, cancel, delete, retry.

### The one right way
One primary action per view: the quieter variants carry the rest.
```tsx
import { Button, ButtonGroup } from "@hackcove/ui";

<ButtonGroup>
  <Button>Save</Button>
  <Button variant="outline">Cancel</Button>
</ButtonGroup>
```

### Do
- Put one primary Button in a view. The other actions use `variant="outline"`, `"ghost"` or `"link"`; `variant="dashed"` is the full-width "add another" row at the foot of a list.
- Group the actions in a `ButtonGroup`, so the row spaces and wraps the same everywhere; `end` pushes one item, such as a Back link, to the far side, and `label` names the group.
- Say why a button cannot be pressed with `disabledReason`; use `busy` while the work is in flight.
- Going to another page is a `ButtonLink`, not a Button.
- A destructive action is `tone="danger"`, an accept is `tone="positive"`; `size="sm"` is for a button inside a row or a card header.
- `pressed` makes a toggle; `busyLabel` replaces the label while `busy`.
- An icon-only action is an `IconButton`, not a Button holding a glyph.

### Don't
Two primaries compete for the eye, and nobody can tell which action the view is about.
```tsx
import { Button, ButtonGroup } from "@hackcove/ui";

<ButtonGroup>
  <Button>Save</Button>
  <Button>Save and close</Button>
</ButtonGroup>
```

A bare `disabled` leaves the user guessing why nothing happens.
```tsx
import { Button } from "@hackcove/ui";

<Button disabled>Save</Button>

```

A button that sets `location` loses middle-click, the status-bar URL and crawlability.
```tsx
import { Button } from "@hackcove/ui";

<Button variant="outline" onClick={() => location.assign("#quotes")}>
  Open quotes
</Button>
```

A delete in the primary look reads as the safe, expected action; the tone is what warns.
```tsx
import { Button, ButtonGroup } from "@hackcove/ui";

<ButtonGroup>
  <Button>Delete quote</Button>
  <Button variant="outline">Cancel</Button>
</ButtonGroup>
```

Buttons loose in a div have no gap, do not wrap as one row, and the group has no name.
```tsx
import { Button, ButtonLink } from "@hackcove/ui";

<div>
  <Button>Save</Button>
  <Button variant="outline">Preview</Button>
  <ButtonLink href="#quotes" variant="ghost">
    Back
  </ButtonLink>
</div>
```

### Accessibility
- A Button is a native `<button>` and defaults to `type="button"`, so it never submits a form by accident.
- `disabledReason` disables the button and sets the reason as its `title`, so a pointer user sees why.
- `busy` sets `aria-busy` and disables the button until the work is done.
- Every Button has a focus ring from the component, so the keyboard focus is always visible.

### Props
### Button
A button in the primary, outline, ghost, link or dashed style (the link has no box: text with an underline on hover, for an in-line action; `dashed` is the full-width "add" row, a dashed outline with muted text that fills its container, with an optional leading icon in the children). `size="sm"` is compact; `tone="positive"` is green and `tone="danger"` is red; `pressed` makes it a toggle with a selected look. Defaults to `type="button"`. `disabledReason` and `busy` are the two disabled states that say more than a plain `disabled`, which keeps its half-opacity look.
- busy: boolean (default false). The work is in flight: disabled, `aria-busy`, keeps its colour. Wins over `disabledReason`.
- busyLabel: string. The label while `busy`, in place of the children.
- disabledReason: string. Why the button cannot be pressed: disables it, sets it as the `title`, and greys it flat.
- pressed: boolean. A toggle: sets `aria-pressed`, and when `true` draws the selected look (the tone's border and
tint) on the `outline` and `ghost` variants. Left out, the button is not a toggle and has no
`aria-pressed`.
- size: "sm" | "md" (default md). `sm` is compact, for table rows and toolbars.
- tone: "default" | "positive" | "danger" (default default). `positive` is green, for accept and approve; `danger` is red, for delete and clear. Not for
`dashed`, which has the one look.
- variant: "link" | "primary" | "outline" | "ghost" | "dashed" (default primary)

### ButtonLink
A link that looks like a Button. A plain `<a href>` by default; with `render` it draws the app's own router `<Link>` instead (`render={(p) => <Link to="/quotes" {...p} />}`), already carrying the button classes. `variant`, `size` and `tone` are the Button's.
- external: boolean (default false). Opens in a new tab: adds `target="_blank"` and `rel="noreferrer"`.
- href: string
- render: LinkRender
- size: "sm" | "md" (default md). `sm` is compact, for table rows and toolbars.
- tone: "default" | "positive" | "danger" (default default). `positive` is green, for accept and approve; `danger` is red, for delete and clear. Not for
`dashed`, which has the one look.
- variant: "link" | "primary" | "outline" | "ghost" | "dashed" (default primary)

### ButtonGroup
A wrapping row of buttons with one optional item pushed to the far end (a Back link, say). On a narrow viewport the row wraps and `end` stays at the end of the last line. `label` makes it a named `role="group"`. Directly in a `Card` footer it spans the footer, so `end` reaches the far edge.
- end: ReactNode. One item, pushed to the end of the row.
- label: string. The accessible name of the group: sets `role="group"` and `aria-label`.

### Functions
- buttonClass: The Button's look as a class string, for a router link that has to look like a Button when `ButtonLink`'s `render` cannot draw it.

## IconButton

Group: Actions

When to use: An action with a familiar icon and no room for a word: delete, settings, alerts.

### The one right way
`label` names the button for a screen reader and shows as its tooltip; the icon is only decoration.
```tsx
import { IconButton } from "@hackcove/ui";

<IconButton label="Delete quote" tone="danger" variant="ghost">
  <svg
    viewBox="0 0 24 24"
    width="16"
    height="16"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    aria-hidden="true"
  >
    <path d="M6 6l12 12M18 6L6 18" />
  </svg>
</IconButton>
```

### Do
- Always give the `label`: it is the accessible name and the tooltip, and the icon is only decoration.
- `variant="ghost"` is the quiet one for a row or a toolbar; `tone="danger"` is for delete and clear.
- An unread count is `badge`, never part of the label; it is not shown at 0.
- Going to another page is `href` (or `render` for the app's router link), which draws the same button as a link.
- An action that needs a word is a `Button`.

### Don't
A `Button` holding a glyph has no accessible name, no tooltip and the wrong box; an icon-only action is an `IconButton`.
```tsx
import { Button } from "@hackcove/ui";

<Button variant="ghost" tone="danger" size="sm">
  <span aria-hidden="true">x</span>
</Button>
```

A count typed into the label shows only in the tooltip, so a sighted user never sees it on the button.
```tsx
import { IconButton } from "@hackcove/ui";

<IconButton label="Alerts (3)">
  <svg
    viewBox="0 0 24 24"
    width="16"
    height="16"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    strokeLinejoin="round"
    aria-hidden="true"
  >
    <path d="M18 16v-5a6 6 0 1 0-12 0v5l-2 2h16l-2-2ZM10 21h4" />
  </svg>
</IconButton>
```

A button that sets `location` loses middle-click, the status-bar URL and crawlability.
```tsx
import { IconButton } from "@hackcove/ui";

<IconButton label="Settings" variant="ghost" onClick={() => location.assign("#settings")}>
  <svg
    viewBox="0 0 24 24"
    width="16"
    height="16"
    fill="none"
    stroke="currentColor"
    strokeWidth="2"
    strokeLinecap="round"
    aria-hidden="true"
  >
    <path d="M4 8h10M18 8h2M4 16h2M10 16h10" />
    <circle cx="16" cy="8" r="2" />
    <circle cx="8" cy="16" r="2" />
  </svg>
</IconButton>
```

### Accessibility
- `label` is set as `aria-label` and `title`; with a `badge` it reads `Alerts, 3`.
- The badge itself is `aria-hidden`, so the count is read once, through the name.
- As a button it defaults to `type="button"`; with `href` or `render` it is a real link, and `external` opens a new tab with `rel="noreferrer"`.
- It has the component's focus ring.

### Props
### IconButton
A square button holding one icon. `label` is its accessible name and tooltip. `variant="ghost"` drops the border for a quiet action in a row or a toolbar; `tone="danger"` is red, for delete and clear; `badge` pins a red count to the corner. Defaults to `type="button"`. `href` makes it a link instead (a plain `<a>`, or with `render` the app's own router `<Link>`: `render={(p) => <Link to="/settings" {...p} />}`; `external` opens a new tab), with the same look.
- badge: number. A red count on the top-right corner, for unread alerts. Not shown at 0; `label` carries it for a screen reader.
- external: boolean. Opens in a new tab: adds `target="_blank"` and `rel="noreferrer"`.
- href: string
- label: string (required)
- render: LinkRender
- tone: "default" | "danger" (default default). `danger` is red, for delete and clear.
- variant: "outline" | "ghost" (default outline). `outline` has a border; `ghost` has none, until the hover fill.

## CopyButton

Group: Actions

When to use: A value the page already shows that a reader will paste elsewhere.

### The one right way
`CopyButton` writes `text` to the clipboard and swaps its label to `copiedLabel`.
```tsx
import { CopyButton } from "@hackcove/ui";

<CopyButton text="hc_live_9f2c41" label="Copy token" copiedLabel="Token copied" />

```

### Do
- `text` is what is copied; the label swaps to `copiedLabel` once it is on the clipboard.
- Name what is copied in `label` and `copiedLabel` (`"Copy token"`, `"Token copied"`) when the page has more than one.
- A command or token in its own box is a `CopyLine`, which carries this button.
- Do not write the clipboard call by hand in a `Button`.

### Don't
A hand-rolled copy Button gives no feedback and does not survive a refused clipboard.
```tsx
import { Button } from "@hackcove/ui";

<Button
  variant="ghost"
  size="sm"
  onClick={() => {
    void navigator.clipboard.writeText("hc_live_9f2c41");
  }}
>
  Copy token
</Button>
```

### Accessibility
- A native `<button>` with `type="button"` and a focus ring from the component.
- The label text is the accessible name and changes to `copiedLabel` after the copy.
- A refused or missing clipboard leaves the label unchanged; nothing is announced.

### Props
### CopyButton
Writes `text` to the clipboard and swaps the label to `copiedLabel`. Defaults to `type="button"`. A refused or missing clipboard leaves the label on `label`. Every other button prop, `disabled` included, goes on the `<button>`.
- copiedLabel: string (default copied)
- label: string (default copy)
- text: string (required)

## CopyLine

Group: Actions

When to use: A command or token a reader pastes elsewhere.

### The one right way
One command or token to paste: `CopyLine` is the box and the copy button together.
```tsx
import { CopyLine } from "@hackcove/ui";

<CopyLine text="bun add @hackcove/ui" />

```

### Do
- Give the whole line as `text`; the box shows it and the button copies it.
- Several lines are a `CodeBlock`; `CopyLine` is one line.
- A long token wraps inside the box.
- `disabled` disables the button, for a line shown before the page is interactive.

### Don't
Inline code beside a loose `CopyButton` is two parts that drift apart; the text can differ from what is copied.
```tsx
import { Cluster, Code, CopyButton } from "@hackcove/ui";

<Cluster>
  <Code>bun add @hackcove/ui</Code>
  <CopyButton text="bun add @hackcove/ui" />
</Cluster>
```

`CopyLine` is one line of text: a newline in it collapses into a space and the box runs on.
```tsx
import { CopyLine } from "@hackcove/ui";

<CopyLine text={"bun install\nbun run build"} />

```

### Accessibility
- The text is a `<code>` element, so a reader can select it by hand as well.
- The button is a `CopyButton`: a native button labelled `copy`, then `copied`.

### Props
### CopyLine
One line of mono text in a box, with a `CopyButton`: a command or a token to paste elsewhere. `disabled` disables the button, e.g. until hydration. Every other div prop goes on the root `<div>`, so `data-testid` lands there; the `<code>` holds only `text`.
- disabled: boolean
- text: string (required)

## ColourSchemeToggle

Group: Actions

When to use: A site that offers both schemes: one toggle in the header or controls.

### The one right way
One `ColourSchemeToggle` in the page header: it switches `<html>`, remembers the choice and shows the scheme you would switch to.
```tsx
import { ColourSchemeToggle } from "@hackcove/ui";

<ColourSchemeToggle />

```

### Do
- Use one `ColourSchemeToggle` per site. It switches `<html>` between light and dark and remembers the choice in `localStorage`.
- Put `colourSchemeScript` inline in `<head>`, so the stored or system scheme is on `<html>` before first paint and a light visitor never sees a dark flash. It knows only the `dark` class.
- A light theme with a class of its own (thrifty-paper's `paper`) passes `schemes={{ light: "paper", dark: "dark" }}`; render the same class on `<html>` on the server with `schemeClass`.
- An app that knows the scheme on the server (from a cookie) passes `initial`, sets `store={false}` and persists from `onChange`. It then leaves the head script out.
- Do not build a switch from your own buttons; the functions below are what the toggle itself calls.

### Don't
Two hand-rolled buttons forget the choice, and nothing shows which scheme is on.
```tsx
import { applyColourScheme, Button, ButtonGroup } from "@hackcove/ui";

<ButtonGroup label="Colour scheme">
  <Button variant="outline" size="sm" onClick={() => applyColourScheme("light")}>
    Light
  </Button>
  <Button variant="outline" size="sm" onClick={() => applyColourScheme("dark")}>
    Dark
  </Button>
</ButtonGroup>
```

Without `schemes` the toggle only adds and removes `dark`, so the light theme's own class is never put back.
```tsx
import { ColourSchemeToggle } from "@hackcove/ui";

<ColourSchemeToggle />

```

### Accessibility
- It is an `IconButton` named `Switch to dark theme` or `Switch to light theme`, so the name says the action, and the icon is `aria-hidden`.
- The icon shown is the scheme you would switch to: the moon on a light page, the sun on a dark one. It follows the class on `<html>` through CSS, so it is right on the first frame.
- `applyColourScheme` also sets `color-scheme` on `<html>`, so native controls and scrollbars follow.

### Props
### ColourSchemeToggle
A sun/moon button that switches `<html>` between light and dark and remembers the choice. It shows the scheme you would switch to. Pair it with `colourSchemeScript` in `<head>`, unless you pass `schemes` or `initial`: the script knows only the `dark` class and the stored choice, so an app that sets the scheme itself leaves it out. An app whose light scheme has a class of its own passes `schemes` (`{ light: "paper", dark: "dark" }`); the toggle swaps those classes, and `schemeClass` gives the same one for the server to render on `<html>`. An app that knows the scheme on the server (from a cookie) passes it as `initial`, so the server markup, the hydrating client and the `<html>` class agree; persist a change from `onChange`. The icon follows the class on `<html>` through CSS, so even without `initial` a dark page shows the sun from the first frame; the button's name catches up once the client has hydrated. `store={false}` skips `localStorage`, for an app that keeps the choice in a server cookie and writes it from `onChange`. Every other button prop (`id`, `data-*`, `aria-*`) goes on the button.
- initial: "light" | "dark". The scheme the server rendered. What the server and the hydrating client show; the real state follows right after. Default `"light"`.
- onChange: (scheme: ColourScheme) => void
- schemes: ColourSchemeClasses (default { light: "", dark: "dark" }). The class each scheme puts on `<html>`. Default `{ light: "", dark: "dark" }`.
- store: boolean (default true). Remember the choice in `localStorage`. `false` leaves persisting to `onChange`. Default `true`.

### Functions
- applyColourScheme: Puts a scheme on `<html>`: its class, the other scheme's class taken off, and `color-scheme`.
- schemeClass: The class a scheme puts on `<html>`, for the server to render so the first paint is right; empty for the default light scheme.
- colourSchemeScript: A string of JavaScript to inline in `<head>` before first paint: applies the stored scheme, else the system one.
- readColourScheme: The stored choice, else the system preference, with a fallback (default light) when neither is available, as on the server.
- storeColourScheme: Remembers a scheme in `localStorage` for the next visit; a storage error is swallowed.

## Field

Group: Forms

When to use: Every text, select or file control: it gets a visible label.

### The one right way
Every control sits in a `Field`: the label is tied to the control by `htmlFor`, and the hint sits under it.
```tsx
import { Field, Input } from "@hackcove/ui";

<Field label="Display name" htmlFor="do-label-name" hint="Shown on your reviews.">
  <Input id="do-label-name" />
</Field>
```

### Do
- Wrap every `Input`, `Textarea`, `Select` and `FileDrop` in a `Field`; the `label` is always visible, and `htmlFor` is the control's `id`.
- A `hint` is the one line of help under the control.
- A validation message is `error`, not `hint`: it replaces the hint, in red.
- Inside a `FormGrid` a `Field` takes one column; `span="full"` runs it across both.
- A `Checkbox` and a `DatePicker` draw their own `label`; do not wrap them in a `Field`.

### Don't
A placeholder is not a label: it vanishes as soon as the person types, and it names nothing for a screen reader.
```tsx
import { Input } from "@hackcove/ui";

<Input placeholder="Display name" />

```

An error passed as the `hint` looks like help text: it is grey and is not announced.
```tsx
import { Field, Input } from "@hackcove/ui";

<Field label="Display name" htmlFor="dont-error-name" hint="Pick a shorter name.">
  <Input id="dont-error-name" defaultValue="A very long display name indeed" />
</Field>
```

### Accessibility
- The label is a real `<label>` tied to the control by `htmlFor`, so clicking the text focuses the control and a screen reader reads it as the control's name.
- An `error` is a `<p role="alert">`, so it is announced when it appears. The hint is plain text.
- `Field` does not add `aria-describedby` or `aria-invalid` to the control.

### Props
### Field
A label above a control, with a hint or an error line under it. An error replaces the hint. Inside a `FormGrid`, `span="full"` runs the field across both columns.
- error: ReactNode. Replaces the hint when set.
- hint: ReactNode
- htmlFor: string (required). The id of the control inside; the label's htmlFor.
- label: ReactNode (required)
- span: "full". `full` spans every column of a `FormGrid`; unset takes one. It does nothing outside a `FormGrid`.

## Input

Group: Forms

When to use: A short piece of text: a name, an amount, a search term.

### The one right way
An amount takes a `prefix` for the currency, `inputMode="decimal"` for the phone keypad and `align="end"` so the digits line up.
```tsx
import { Input } from "@hackcove/ui";

<Input
  prefix="R"
  inputMode="decimal"
  align="end"
  width="md"
  aria-label="Amount"
  defaultValue="49.90"
/>
```

### Do
- Put an `Input` in a `Field`. Without one, name it with `aria-label`.
- A search box is `type="search"` with an `icon`; the clear button appears by itself.
- `prefix` is short text inside the border before the value, such as a currency symbol. It is for a plain field, not one with an `icon` or `type="search"`. Pair it with `align="end"` and `inputMode="decimal"` for an amount.
- `size="sm"` is for a dense form or a table row.
- `width` is `full` by default; `xs`, `sm`, `md` and `lg` are fixed widths for a short value; `fill` grows to the room beside other items in a row; `auto` is as wide as the browser makes it.
- A paragraph is a `Textarea`; a choice from a list is a `Select`; a date is a `DatePicker`.

### Don't
A currency typed into the placeholder is gone as soon as the person types, and nothing keeps the digits aligned.
```tsx
import { Input } from "@hackcove/ui";

<Input placeholder="R 0.00" width="md" aria-label="Amount" />

```

A plain text input used for search has no icon and no way to clear it.
```tsx
import { Input } from "@hackcove/ui";

<Input aria-label="Search shops" placeholder="Search by name or suburb…" />

```

### Accessibility
- An `Input` is a native `<input>`: it takes `type`, `inputMode`, `autoComplete`, `required`, `disabled` and the `aria-*` and `data-*` props.
- A `type="search"` field shows a "Clear search" button while it has a value; the button is labelled and is hidden when the field is disabled or read-only.
- The `icon` is decorative and hidden from assistive tech.
- The focus ring comes from the component.

### Props
### Input
A text input. `icon` puts a leading icon inside the field (e.g. a search glass). `prefix` puts short text inside the border before the value, such as a currency symbol; it is for a plain field, not with an `icon` or `type="search"`. `align="end"` right-aligns the value, for a numeric field. `type="search"` drops the browser's own search look and shows a "Clear search" button at the trailing edge while the field has a value.
- align: "end" | "start" (default start). `end` right-aligns the value, for a numeric field. `start` (default) leaves it as typed.
- icon: ReactNode
- prefix: string
- size: "sm" | "md" (default md). `sm` is compact, `text-xs` with less padding, for dense forms and table rows.
- width: "auto" | "sm" | "md" | "lg" | "xs" | "fill" | "full" (default full). `full` (default) fills the parent; `fill` grows to fill the room left in a row beside other items (it can shrink to nothing, so buttons stay on the line); `xs`, `sm`, `md`, `lg` are fixed; `auto` is as wide as its content.

## Textarea

Group: Forms

When to use: Text that runs to a sentence or a paragraph: a review, a note, a message.

### The one right way
Text that runs to a paragraph is a `Textarea` in a `Field`, so the person can see what they wrote.
```tsx
import { Field, Textarea } from "@hackcove/ui";

<Field label="Review" htmlFor="do-review" hint="What did you find? How were the prices?">
  <Textarea id="do-review" rows={4} />
</Field>
```

### Do
- Put a `Textarea` in a `Field`, as with an `Input`.
- `rows` is 3 unless you set it; set more for a long answer.
- `size` and `width` are the same choices as on `Input`.
- One line of text is an `Input`.

### Don't
An `Input` is one line: a paragraph typed into it scrolls out of sight.
```tsx
import { Field, Input } from "@hackcove/ui";

<Field label="Review" htmlFor="dont-review" hint="What did you find? How were the prices?">
  <Input id="dont-review" />
</Field>
```

### Accessibility
- A `Textarea` is a native `<textarea>`: it takes `name`, `required`, `disabled`, `maxLength` and the `aria-*` props.
- The focus ring comes from the component.

### Props
### Textarea
A multi-line text input, styled like `Input`. `rows` defaults to 3. Takes `size` and `width` too.
- size: "sm" | "md" (default md). `sm` is compact, `text-xs` with less padding, for dense forms and table rows.
- width: "auto" | "sm" | "md" | "lg" | "xs" | "fill" | "full" (default full). `full` (default) fills the parent; `fill` grows to fill the room left in a row beside other items (it can shrink to nothing, so buttons stay on the line); `xs`, `sm`, `md`, `lg` are fixed; `auto` is as wide as its content.

## Select

Group: Forms

When to use: One choice from a list of about five or more: a category, a country, a rating.

### The one right way
Choosing one of several is a `Select` in a `Field`.
```tsx
import { Field, Select } from "@hackcove/ui";

<Field label="Category" htmlFor="do-category">
  <Select id="do-category" defaultValue="books">
    <option value="books">Books</option>
    <option value="clothes">Clothes</option>
    <option value="furniture">Furniture</option>
    <option value="records">Records</option>
    <option value="toys">Toys</option>
  </Select>
</Field>
```

### Do
- Put a `Select` in a `Field`, with `<option>` children; set `defaultValue` or control it with `value` and `onChange`.
- A yes or no is a `Checkbox`.
- Two to four modes switched in place are a `SegmentedControl`.
- `size` and `width` are the same choices as on `Input`.

### Don't
A yes or no is not a choice from a list: it is a `Checkbox`.
```tsx
import { Field, Select } from "@hackcove/ui";

<Field label="Open now" htmlFor="dont-open">
  <Select id="dont-open" defaultValue="yes">
    <option value="yes">Yes</option>
    <option value="no">No</option>
  </Select>
</Field>
```

### Accessibility
- A `Select` is a native `<select>`, so it keeps the browser's arrow, its keyboard handling and its mobile picker.
- The focus ring comes from the component.

### Props
### Select
A native `<select>` styled like `Input`, keeping the browser's own arrow. Takes `size` and `width` too.
- size: "sm" | "md" (default md). `sm` is compact, `text-xs` with less padding, for dense forms and table rows.
- width: "auto" | "sm" | "md" | "lg" | "xs" | "fill" | "full" (default full). `full` (default) fills the parent; `fill` grows to fill the room left in a row beside other items (it can shrink to nothing, so buttons stay on the line); `xs`, `sm`, `md`, `lg` are fixed; `auto` is as wide as its content.

## Checkbox

Group: Forms

When to use: An on/off option the person ticks: a setting, a filter, a row to select.

### The one right way
A yes or no is a `Checkbox` with its `label`: the whole label is the click target.
```tsx
import { Checkbox } from "@hackcove/ui";

<Checkbox label="Email me when a shop I follow posts" defaultChecked />

```

### Do
- Give a `Checkbox` a `label`; the whole label is the click target.
- In a table cell leave the `label` out, use `size="sm"` and name the box with `aria-label`.
- `align="start"` puts the box on the first line of a label that wraps onto several; the default centres it.
- Do not wrap a `Checkbox` in a `Field`; it is its own label.
- Choosing one of several is a `Select` or a `SegmentedControl`, not a row of checkboxes.

### Don't
A checkbox with the words beside it, not in it, names nothing: clicking the words does nothing.
```tsx
import { Body, Checkbox, Cluster } from "@hackcove/ui";

<Cluster gap="sm">
  <Checkbox />
  <Body>Email me when a shop I follow posts</Body>
</Cluster>
```

### Accessibility
- A native `<input type="checkbox">` inside a `<label>`, so clicking the text toggles it and the label is its name.
- A bare box has no name of its own: `aria-label` is required.
- The focus ring comes from the component.

### Props
### Checkbox
A native checkbox with its label. Every prop but the label goes on the input. `size="sm"` is `text-xs` and a smaller box, for a dense row. Leave `label` out for a bare box in a table cell, and name it with `aria-label`. `align="start"` puts the box on the label's first line, for a label that wraps onto several; the default centres it on the whole label. The box keeps its size either way.
- align: "center" | "start" (default center)
- label: ReactNode
- size: "sm" | "md" (default md)

## FileDrop

Group: Forms

When to use: Uploading a file: a statement, a photo, an import.

### The one right way
Name the file the zone wants in its prompt, restrict it with `accept`, and show the chosen file's name from `onChange`.
```tsx
import { useState } from "react";
import { FileDrop } from "@hackcove/ui";

function Example() {
  const [name, setName] = useState("");
  return (
    <FileDrop accept=".csv" onChange={(event) => setName(event.target.files?.[0]?.name ?? "")}>
      {name === "" ? "Drop a bank statement here or click to choose" : name}
    </FileDrop>
  );
}
```

### Do
- Say what the zone wants in its children, and restrict the type with `accept`.
- Show the chosen file's name in the children from `onChange`; the zone does not do it for you.
- `size="sm"` is a compact chip or tile.
- `multiple`, `name` and `disabled` go on the zone like any file input.
- Put a `FileDrop` in a `Field` when it needs a label of its own above it.

### Don't
A prompt that never changes leaves the person unsure the file was taken, and with no `accept` any file is.
```tsx
import { FileDrop } from "@hackcove/ui";

<FileDrop>Drop here</FileDrop>

```

### Accessibility
- A real `<input type="file">` covers the whole zone, invisible, so a click opens the file dialog, a dragged file is taken as by any file input, and the browser's keyboard handling applies.
- The zone is a `<label>`, so its children are the input's accessible name.
- The zone shows the keyboard focus ring while the input has focus.

### Props
### FileDrop
A dashed drop zone around a file input. The input covers the whole zone, invisible, so a click opens the file dialog and a file dragged onto it is taken by the browser as it is by any file input. `children` is the prompt; show the chosen file's name there from `onChange`. The label also shows the keyboard focus ring, the input being invisible. Every prop (`accept`, `multiple`, `name`, `disabled`, `onChange`) goes on the input.
- size: "sm" | "md" (default md). `sm` is a compact chip or tile: dense padding. Defaults to `md`.

## FormRow

Group: Forms

When to use: `FormGrid` lays Fields out in two columns; `FormRow` puts several controls and a save button on one line.

### The one right way
A row of controls with proportional widths, an `action` after them, and one `hint` under the whole row.
```tsx
import { Button, FormRow, FormRowField, Input } from "@hackcove/ui";

<FormRow hint="Press Save to apply the change." action={<Button>Save</Button>}>
  <FormRowField label="Description" htmlFor="do-row-desc" span={3}>
    <Input id="do-row-desc" defaultValue="Kitchen renovation" />
  </FormRowField>
  <FormRowField label="Amount" htmlFor="do-row-amount">
    <Input id="do-row-amount" defaultValue="12,400.00" align="end" />
  </FormRowField>
</FormRow>
```

### Do
- A form of several fields is a `FormGrid` of `Field`s: two columns from `md`, one below. A long control, such as a `Textarea`, takes `span="full"`.
- A line of controls to edit one record in place is a `FormRow` of `FormRowField`s, with the save `Button` as `action`.
- `FormRowField` `span` 1 to 4 is its share of the row's width.
- The `hint` or `error` goes on the `FormRow`, once, under the whole line. A `FormRowField` has no hint or error, and a `Field` does not belong inside a `FormRow`.
- A `FormRow` inside a `FormGrid` runs across both columns.

### Don't
A `Field` with its own hint inside a `FormRow` makes its column taller, so the controls drift out of line and the save button with them.
```tsx
import { Button, Field, FormRow, Input } from "@hackcove/ui";

<FormRow action={<Button>Save</Button>}>
  <Field label="Description" htmlFor="dont-row-desc" hint="Shown on the invoice.">
    <Input id="dont-row-desc" defaultValue="Kitchen renovation" />
  </Field>
  <Field label="Amount" htmlFor="dont-row-amount">
    <Input id="dont-row-amount" defaultValue="12,400.00" align="end" />
  </Field>
</FormRow>
```

Without `span="full"` a `Textarea` takes half the width and leaves a hole beside it.
```tsx
import { Field, FormGrid, Input, Textarea } from "@hackcove/ui";

<FormGrid>
  <Field label="First name" htmlFor="dont-grid-first">
    <Input id="dont-grid-first" />
  </Field>
  <Field label="Last name" htmlFor="dont-grid-last">
    <Input id="dont-grid-last" />
  </Field>
  <Field label="Notes" htmlFor="dont-grid-notes">
    <Textarea id="dont-grid-notes" />
  </Field>
</FormGrid>
```

### Accessibility
- `FormRowField` renders a `<label>` tied to its control by `htmlFor`, as `Field` does.
- The row's `error` is a `<p role="alert">`.
- Under `md` the fields and the action stack in reading order.

### Props
### FormRow
An inline-edit row: several controls side by side with proportional widths (`FormRowField` `span` 1 to 4), an optional `action` after them (a save button), and one `hint` or `error` line under the whole row. Every control sits on the bottom edge, so the action lines up with them whatever the labels do. Under `md` the fields and the action stack. The row owns the note, so the fields beside each other keep their height: a `FormRowField` has no `hint` or `error` of its own.
- action: ReactNode. A button or two after the last field. It keeps its own width.
- error: ReactNode. Replaces the hint when set, as `Field`'s does.
- hint: ReactNode

### FormRowField
A compact label over one control, for a `FormRow`. `span` is its share of the row (1 default).
- htmlFor: string (required). The id of the control inside; the label's htmlFor.
- label: ReactNode (required)
- span: 1 | 2 | 3 | 4 (default 1)

### FormGrid
Two columns of `Field`s from `md`, one below it. A `Field` takes one column; `span="full"` runs it across both, and a `FormRow` is always full width.

## DatePicker

Group: Forms

When to use: Any date a person enters; use `DateField` when a calendar is not wanted.

### The one right way
A date is a `DatePicker`: DD/MM/YYYY segments the person can type, and a calendar button for the rest.
```tsx
import { DatePicker } from "@hackcove/ui";

<DatePicker label="Date of birth" description="As on your ID document." />

```

### Do
- A date is a `DatePicker` or a `DateField`, never an `Input`. The format is always DD/MM/YYYY and weeks start on Monday, whatever the browser's locale.
- `DatePicker` adds a calendar button; `DateField` is the same input without it, for a date the person knows by heart (a birthday).
- These two draw their own label: give them `label` and `description`, and do not wrap them in a `Field`.
- A message from outside, a server's say, is `error`; it replaces the description. An impossible date, such as 31/02/1990, shows its own message. `isInvalid` alone marks the field with no reason, so pair it with `errorMessage`.
- The value is a `CalendarDate` (`value`, `defaultValue`, `onChange`, `minValue`, `maxValue`). `fromISODate` reads a stored `YYYY-MM-DD` and `toISODate` writes one.
- `name` posts the date as `YYYY-MM-DD` in a form, or an empty string.

### Don't
A text input takes any characters, so 17/5/90, 1990-05-17 and "May" all arrive, and nothing says which is meant.
```tsx
import { Input } from "@hackcove/ui";

<Input aria-label="Date of birth" placeholder="DD/MM/YYYY" />

```

`isInvalid` alone turns the field red and says nothing about why.
```tsx
import { DatePicker } from "@hackcove/ui";

<DatePicker label="Paid on" description="The day the money moved." isInvalid />

```

### Accessibility
- The label names a `role="group"`; each of day, month and year is its own editable segment (`role="spinbutton"`), so a person can type digits or use the arrow keys.
- The `description` is the field's `aria-describedby`; the `error` and the built-in messages replace it, and an `error` is `role="alert"`.
- The calendar button is labelled "Calendar" and opens a popover dialog, with a Month and a Year select, arrow-key movement across days and a Clear button.
- Inside a `Dialog` or `Drawer` the calendar opens inside it, so it still takes focus.
- The focus ring comes from the component.

### Props
### DatePicker
A `DateField` with a calendar button that opens a month view in a popover.
- defaultOpen: boolean. Open the calendar on mount.
- description: ReactNode. A hint under the field; an error replaces it.
- error: ReactNode. An error from outside the field (a server's, say). Shown in place of the description, in red with `role="alert"`, and marks the field invalid. Like `Field`'s `error`.
- errorMessage: ReactNode. Replaces the built-in error message (an impossible date, or one outside min/max).
- isInvalid: boolean. Marks the field invalid with no message of its own; pair it with `errorMessage`.
- label: ReactNode

### DateField
A segmented DD / MM / YYYY date input. Values are `CalendarDate`s; `name` posts it as `YYYY-MM-DD`.
- description: ReactNode. A hint under the field; an error replaces it.
- error: ReactNode. An error from outside the field (a server's, say). Shown in place of the description, in red with `role="alert"`, and marks the field invalid. Like `Field`'s `error`.
- errorMessage: ReactNode. Replaces the built-in error message (an impossible date, or one outside min/max).
- isInvalid: boolean. Marks the field invalid with no message of its own; pair it with `errorMessage`.
- label: ReactNode

### Functions
- fromISODate: Reads a stored `"YYYY-MM-DD"` into the `CalendarDate` a picker takes; `null` for an empty, malformed or impossible string.
- toISODate: Writes a `CalendarDate` as `"YYYY-MM-DD"`, or `""` for none, so it drops into a form field or storage.

## SegmentedControl

Group: Forms

When to use: A mode or a range chosen in place: daily or weekly, split or even.

### The one right way
A mode or a range chosen in place: the caller owns `value`, and `label` names the group.
```tsx
import { useState } from "react";
import { SegmentedControl } from "@hackcove/ui";

function Example() {
  const [value, setValue] = useState("week");
  return (
    <SegmentedControl
      label="Range"
      items={[
        { value: "day", label: "Daily" },
        { value: "week", label: "Weekly" },
        { value: "month", label: "Monthly" },
      ]}
      value={value}
      onChange={setValue}
    />
  );
}
```

### Do
- Two to five short options. The caller owns `value` and `onChange`; `label` names the group.
- An on/off setting is a `Checkbox`; a long list is a `Select`.
- Switching the panel under a row of headings is `Tabs`.
- A `count` sits muted after the label.
- A disabled option keeps a `title` as the reason; `disabled` on the group disables every option.
- Options that go to another page are links: `href` on each, or `render` to draw the app's own router link. `value` marks the current page.

### Don't
An on/off setting is a `Checkbox`, not a two-option SegmentedControl.
```tsx
import { useState } from "react";
import { SegmentedControl } from "@hackcove/ui";

function Example() {
  const [value, setValue] = useState("on");
  return (
    <SegmentedControl
      label="Email me"
      items={[
        { value: "on", label: "On" },
        { value: "off", label: "Off" },
      ]}
      value={value}
      onChange={setValue}
    />
  );
}
```

A disabled option with no `title` leaves the person guessing why it is greyed out.
```tsx
import { useState } from "react";
import { SegmentedControl } from "@hackcove/ui";

function Example() {
  const [value, setValue] = useState("split");
  return (
    <SegmentedControl
      label="Split"
      items={[
        { value: "split", label: "Split" },
        { value: "even", label: "Even" },
        { value: "custom", label: "Custom", disabled: true },
      ]}
      value={value}
      onChange={setValue}
    />
  );
}
```

### Accessibility
- Buttons form a `radiogroup` named by `label`; each option is a `radio` with `aria-checked`.
- The group is one tab stop. The arrow keys (all four), Home and End move to the next enabled option and choose it.
- A disabled option stays in the page as `aria-disabled`, so its `title` is read out; the arrow keys skip it.
- Links form a `<nav>` named by `label`, and the current one has `aria-current="page"`.
- The focus ring comes from the component.

### Props
### SegmentedControl
A joined pill group where one option is filled: a mode or a range chosen in place. `items` are `{ value, label }` buttons (`value` and `onChange` are the caller's state; the arrow keys, Home and End move the choice) or links (`href`, or `render` to draw the app's own router `<Link>`; `value` marks the current one, which gets `aria-current`). An item may carry a `count`, and a button one `disabled` (with a `title` for the reason); `disabled` on the group disables every option. `label` names the group.
- disabled: boolean. Every option is disabled, e.g. until the page has hydrated.
- items: SwitchButton[] | SwitchLink[] (required)
- label: string (required). The accessible name of the group.
- onChange: ((value: string) => void). Called with the option's `value` when one is chosen, by click or arrow key.
- value: string (required). The `value` of the current option.

## ToggleChip

Group: Forms

When to use: A filter the person switches on and off, usually one of several side by side.

### The one right way
A filter is a `ToggleChip`: `pressed` shows whether it is on, and the caller toggles it in `onClick`.
```tsx
import { useState } from "react";
import { Cluster, ToggleChip } from "@hackcove/ui";

function Example() {
  const [on, setOn] = useState(["Vintage"]);
  const toggle = (name: string) =>
    setOn((now) => (now.includes(name) ? now.filter((n) => n !== name) : [...now, name]));
  return (
    <Cluster gap="xs" wrap>
      {["Charity", "Vintage", "Books"].map((name) => (
        <ToggleChip key={name} pressed={on.includes(name)} onClick={() => toggle(name)}>
          {name}
        </ToggleChip>
      ))}
    </Cluster>
  );
}
```

### Do
- `pressed` is the state; the caller flips it in `onClick`.
- Put chips that filter one thing in a `FilterGroup`, so the set has a name.
- `dot` is a category colour before the label, for a chip that matches a marker elsewhere.
- An action is a `Button`; a setting in a form is a `Checkbox`.

### Don't
A chip that does something once, such as clearing the filters, is an action: use a `Button`.
```tsx
import { ToggleChip } from "@hackcove/ui";

<ToggleChip pressed={false}>Clear filters</ToggleChip>

```

### Accessibility
- A native `<button type="button">` with `aria-pressed`, so a screen reader announces it as a toggle button and its state.
- The `dot` is decorative and hidden from assistive tech.
- The focus ring comes from the component.

### Props
### ToggleChip
An on/off pill button for filters. `pressed` sets its state; `dot` adds a leading colour dot. The caller toggles it in onClick.
- dot: string. A CSS colour for a leading dot (e.g. a category colour); no dot when omitted.
- pressed: boolean (required)

## FilterGroup

Group: Forms

When to use: Two or more `ToggleChip`s that filter the same thing.

### The one right way
A `FilterGroup` names a set of chips with a `legend`, so the group is announced and the chips wrap together.
```tsx
import { FilterGroup, ToggleChip } from "@hackcove/ui";

<FilterGroup legend="Type of shop">
  <ToggleChip pressed dot="#7c3aed">
    Vintage
  </ToggleChip>
  <ToggleChip pressed={false} dot="#0891b2">
    Books
  </ToggleChip>
  <ToggleChip pressed={false} dot="#ca8a04">
    Furniture
  </ToggleChip>
</FilterGroup>
```

### Do
- The `legend` names the set, such as the type of shop; the chips below wrap onto further lines when they run out of room.
- One `FilterGroup` per facet; stack several in a `Stack`.
- The children are `ToggleChip`s.

### Don't
Chips with no group have no name: a screen reader hears a row of buttons and not what they filter.
```tsx
import { Cluster, ToggleChip } from "@hackcove/ui";

<Cluster gap="xs" wrap>
  <ToggleChip pressed>Vintage</ToggleChip>
  <ToggleChip pressed={false}>Books</ToggleChip>
  <ToggleChip pressed={false}>Furniture</ToggleChip>
</Cluster>
```

### Accessibility
- A `<fieldset>` with a `<legend>`, so a screen reader announces the group's name on entering it.
- `disabled` on the group disables every chip in it.

### Props
### FilterGroup
A labelled filter section: a small uppercase legend over a wrapped row of chips (e.g. ToggleChip). Other props go on the fieldset.
- legend: ReactNode (required)

## Table

Group: Data

When to use: Records that share columns, where a person compares values down a column.

### The one right way
A table is a head and a body: names in strong cells, amounts in `align="end" numeric` cells so the figures line up.
```tsx
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeaderCell,
  TableRow,
} from "@hackcove/ui";

<Table caption="Quotes">
  <TableHead>
    <TableRow>
      <TableHeaderCell>Client</TableHeaderCell>
      <TableHeaderCell align="end">Premium</TableHeaderCell>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableCell tone="strong">Naledi Dlamini</TableCell>
      <TableCell align="end" numeric>
        R 1 249.00
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell tone="strong">Pieter van Wyk</TableCell>
      <TableCell align="end" numeric>
        R 880.50
      </TableCell>
    </TableRow>
  </TableBody>
</Table>
```

### Do
- Compose a `Table` from `TableHead`, `TableBody` and, for totals, `TableFoot`. A `TableHead` holds one `TableRow` of `TableHeaderCell`s; give the `Table` a `caption` that names it.
- Right-align a column of amounts with `align="end"` on its header and its cells, and set `numeric` on the cells so the figures line up. A code or a type is `mono`.
- A cell's `tone` is `default`, `strong` for the name of the row, `muted` for the secondary column, or a Callout tone for an amount that carries a meaning; pair the tone with a sign or a word. `secondary` is a muted second line under a cell.
- Totals and subtotals are `TableFoot` rows, never body rows. A `TableFoot` row takes no `tone`.
- Mark a row's status with `tone` (a stripe and a soft fill, or `muted` to fade the row) or with `stripe` (the stripe alone, in the `StackedBar` tones, which keeps the row's hover). Give one of them, never both, and name the status in a cell as well (a `Pill`), or draw a `Legend` for the colours.
- Group rows with a `TableGroupRow` and give it `colSpan` equal to the table's column count; `trailing` is a count or a subtotal at the far end. A full-width note or empty state is a `TableCell` with `colSpan`.
- A column with nothing to say in its head (its actions) takes a `TableHeaderCell` with `srLabel="Actions"`. `variant="plain"` drops the card, for a table inside a `Card`.
- A prose cell wraps; a `numeric` or `mono` cell never breaks. `truncate` cuts a long value to one line and keeps its full text as a `title`; its content is plain text.
- To make a whole row clickable, put one router `<Link>` with `rowLinkClass` in its first cell. Keep an action that is not navigation a `Button` in an actions column.

### Don't
Amounts in plain start-aligned cells do not line up, so the eye cannot compare them.
```tsx
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeaderCell,
  TableRow,
} from "@hackcove/ui";

<Table caption="Quotes">
  <TableHead>
    <TableRow>
      <TableHeaderCell>Client</TableHeaderCell>
      <TableHeaderCell>Premium</TableHeaderCell>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableCell>Naledi Dlamini</TableCell>
      <TableCell>R 1 249.00</TableCell>
    </TableRow>
    <TableRow>
      <TableCell>Pieter van Wyk</TableCell>
      <TableCell>R 880.50</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

A total faked as one more body row, in a strong cell, reads like a line item and is not a `<tfoot>`.
```tsx
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeaderCell,
  TableRow,
} from "@hackcove/ui";

<Table caption="Budget">
  <TableHead>
    <TableRow>
      <TableHeaderCell>Line</TableHeaderCell>
      <TableHeaderCell align="end">Spent</TableHeaderCell>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableCell>Groceries</TableCell>
      <TableCell align="end" numeric>
        R 4 120.00
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell>Eating out</TableCell>
      <TableCell align="end" numeric>
        R 2 980.00
      </TableCell>
    </TableRow>
    <TableRow>
      <TableCell tone="strong">Total</TableCell>
      <TableCell align="end" numeric tone="strong">
        R 7 100.00
      </TableCell>
    </TableRow>
  </TableBody>
</Table>
```

A toned row whose cells never say what the tone means: colour alone tells nobody who cannot see it.
```tsx
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeaderCell,
  TableRow,
} from "@hackcove/ui";

<Table caption="Debit orders">
  <TableHead>
    <TableRow>
      <TableHeaderCell>Debit order</TableHeaderCell>
      <TableHeaderCell align="end">Amount</TableHeaderCell>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableCell tone="strong">Insurance</TableCell>
      <TableCell align="end" numeric>
        R 1 850.00
      </TableCell>
    </TableRow>
    <TableRow tone="danger">
      <TableCell tone="strong">Gym</TableCell>
      <TableCell align="end" numeric>
        R 349.00
      </TableCell>
    </TableRow>
  </TableBody>
</Table>
```

Stripes with no key and no status word in the row: the colour is the only signal, and it means nothing to anyone who cannot tell the colours apart.
```tsx
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeaderCell,
  TableRow,
} from "@hackcove/ui";

<Table caption="Pages">
  <TableHead>
    <TableRow>
      <TableHeaderCell>Page</TableHeaderCell>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow stripe="warn">
      <TableCell tone="strong">/pricing</TableCell>
    </TableRow>
    <TableRow stripe="danger">
      <TableCell tone="strong">/old-landing</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

An empty header cell leaves the column with no name, so a screen reader hears a column of unlabelled buttons.
```tsx
import {
  Button,
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeaderCell,
  TableRow,
} from "@hackcove/ui";

<Table caption="Clients">
  <TableHead>
    <TableRow>
      <TableHeaderCell>Client</TableHeaderCell>
      <TableHeaderCell align="end" />
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableCell tone="strong">Naledi Dlamini</TableCell>
      <TableCell align="end">
        <Button variant="outline" size="sm">
          Open
        </Button>
      </TableCell>
    </TableRow>
  </TableBody>
</Table>
```

### Accessibility
- A Table renders a native `<table>`; `caption` is its accessible name, visually hidden.
- A `TableHeaderCell` is a `<th scope="col">`; a `TableGroupRow` is a `<th scope="rowgroup">`.
- `srLabel` is hidden text inside the header cell, so an actions column still has a name for a screen reader.
- Colour alone never carries a row's or a cell's status; name it in text.
- A `truncate` cell puts its full text in a `title`.
- A `rowLinkClass` link is a real link and the only tab stop in its row; the row's whole area is its click target.
- On a narrow screen the card scrolls sideways instead of squeezing its columns.

### Props
### Table
A list of records in a rounded, bordered card that scrolls sideways on a narrow screen. Compose it from `TableHead`, `TableBody`, `TableFoot`, `TableRow`, `TableHeaderCell` and `TableCell`. `caption` names the table for assistive tech and is not drawn. `variant="plain"` drops the card (its border, fill and shadow), the head's tinted strip and the row hover, and keeps the row dividers; it is for a table that sits inside a card of its own. Other props (`id`, `data-*`, `aria-*`) go on the `<table>`.
- caption: string
- variant: "card" | "plain" (default card)

### TableHead
The `<thead>`: small uppercase column titles, on a tinted strip unless the table is `plain`. Holds one `TableRow` of `TableHeaderCell`s.

### TableBody
The `<tbody>`: the rows, each with a line above it and, unless the table is `plain`, a fill on hover.

### TableFoot
The `<tfoot>`: totals and subtotals. Its cells are strong by default and each row has a firmer line above it, in a card and in a `plain` table alike. Put it after `TableBody`; a row of it takes no `tone`.

### TableRow
A `<tr>`, `relative`: the anchor a `rowLinkClass` link stretches to. Use it in the head and the body. In the body it also draws the line above the row and, unless the table is `plain`, the hover fill. `tone` marks the row's status (see `RowTone`): a stripe on the leading edge and a soft fill, or `muted` to fade it. A toned row keeps its fill on hover (the status stays readable), so a linked row's link, not a hover fill, says it is clickable. `stripe` is the stripe alone, in the `TextTone` colours (the names a `StackedBar` segment takes), with no fill: the row keeps its hover and its own look. Give `tone` or `stripe`, not both. Body rows only; colour alone does not say it, so name the status in a cell too (a `Pill`). A bold subtotal is not a tone: it is a `TableFoot` row.
- stripe: "positive" | "danger" | "info" | "warn" | "muted"
- tone: "positive" | "danger" | "neutral" | "info" | "warn" | "muted"

### TableHeaderCell
A column title, `<th scope="col">`. A column with nothing to show in its head (a row's actions) takes `srLabel` instead of `children`: the name a screen reader hears ("Actions"), visually hidden so the head keeps its column.
- align: "end" | "start" (default start)
- srLabel: string

### TableCell
A `<td>`. `tone` is the text weight and colour (see `CellTone`; in a `TableFoot` it defaults to `strong`); `numeric` sets tabular figures, `mono` a small mono face. `secondary` is a second, muted line under the content. One rule for wrapping: prose wraps onto more lines (never narrower than `min-w-48`, so it scrolls the table before it becomes a sliver), and a `numeric` or `mono` cell (a figure, a code, a type) never breaks. `truncate` caps a long value's width, cuts it with an ellipsis on one line and puts the full text in a `title`; the content is then plain text (strings and numbers), since that is what the title shows. `colSpan` passes through: a cell that spans the row is a full-width panel (an empty state, a note under a group).
- align: "end" | "start" (default start)
- mono: boolean (default false)
- numeric: boolean (default false)
- secondary: ReactNode
- tone: "strong" | "default" | "positive" | "danger" | "neutral" | "info" | "warn" | "muted"
- truncate: boolean (default false)

### TableGroupRow
A full-width group header in the body: a tinted row with a `label` that spans the table's `colSpan` columns (its real column count), and optional `trailing` content at the far end (a count, a subtotal, a small button). The group's rows follow it. For a panel of other content across the whole row, use a `TableCell` with `colSpan` instead.
- colSpan: number (required)
- label: ReactNode (required)
- trailing: ReactNode

### Functions
- rowLinkClass: The one link in a row that stretches over the whole row, for a router's own `<Link>` in the row's first cell; a plain link is a `TextLink`.

## ListRow

Group: Data

When to use: A short list where each row opens something, toggles a section or holds its own buttons.

### The one right way
Rows sit in a `Card flush`, and `divided` draws the line between them on every row after the first.
```tsx
import { Card, ListRow } from "@hackcove/ui";

<Card flush>
  <ListRow trailing="R 9 500">Rent</ListRow>
  <ListRow divided trailing="R 1 850">
    Transport
  </ListRow>
  <ListRow divided href="#bills" trailing="3">
    Bills
  </ListRow>
</Card>
```

### Do
- Put the rows in a `Card flush` and set `divided` on every row after the first. `trailing` is a value, a count or a `Pill`; `leading` is an `Avatar` or an icon.
- A row with `onClick` is a button; with `href` (or `render`, for a router's link) it is a link. `external` opens a link in a new tab.
- `expanded` makes the row the header of a collapsible section: you own the state and the section, and pass `aria-controls` to name it.
- `selected` marks the one row whose detail is open; set it on a single row of a list.
- A row that holds its own buttons is `static`: the buttons go in `actions`, after `trailing`. `revealOnHover` shows them only on hover or focus, so a long list is not a wall of buttons.
- Never put a button or a link inside a button or link row. `size="sm"` is the dense padding for a list that must fit more rows.
- Records with several columns to compare are a `Table`, not rows.

### Don't
Rows in a Card that is not `flush` sit inside its padding, so the hover fill stops short of the edges and the lines do not run across.
```tsx
import { Card, ListRow } from "@hackcove/ui";

<Card>
  <ListRow trailing="R 9 500">Rent</ListRow>
  <ListRow divided trailing="R 1 850">
    Transport
  </ListRow>
</Card>
```

A button inside a link row is a control inside a control: the row opens a page and the button does something else, and a click can only mean one.
```tsx
import { Button, Card, ListRow } from "@hackcove/ui";

<Card flush>
  <ListRow href="#grace" trailing={<Button size="sm">Accept</Button>}>
    Grace Hopper
  </ListRow>
</Card>
```

### Accessibility
- A button row is a native `<button type="button">`; a link row is a real link; a `static` row is a plain `<div>` with no click target.
- `selected` sets `aria-current="true"` on the row.
- `expanded` sets `aria-expanded` and draws a chevron, which is hidden from assistive tech.
- A button or link row has a focus ring from the component; `disabled` fades the row and stops pointer events.
- `revealOnHover` actions appear when the row is hovered or has focus inside it, so a keyboard user can reach them, and they are always shown on a touch screen.

### Props
### ListRow
A full-width row that is a `<button>` (or, with `href` or `render`, a link) with a hover fill, a left-aligned label and `trailing` content at the far end. With `expanded` it is the header of a collapsible section: `aria-expanded` and a chevron. Rows sit in a `Card flush`; `divided` draws the line between them, on each row after the first. `leading` is content before the label, and `selected` marks the row in view. `static` makes the row a plain `<div>` for one that holds its own buttons (a button cannot sit inside a button or a link): `actions` follow `trailing`, and `revealOnHover` shows them only on hover or focus.
- actions: ReactNode. Buttons for this row, after `trailing`: `Button size="sm"`, `IconButton`.
- divided: boolean. A hairline above the row: set it on every row after the first.
- expanded: boolean. Makes the row a collapsible header: sets `aria-expanded` and shows a chevron that turns down
when open. The caller owns the state and the section; pass `aria-controls` to name it.
- external: boolean. Opens in a new tab: adds `target="_blank"` and `rel="noreferrer"`.
- href: string
- leading: ReactNode. Content before the label: an Avatar, a thumbnail, an icon.
- render: LinkRender
- revealOnHover: boolean. Hides `actions` until the row is hovered or something in it has focus, so a long list is not a
wall of buttons. A touch screen has no hover, so they are always shown there.
- selected: boolean. Marks the row in view, the one whose detail is open: a violet fill and `aria-current="true"`.
Set it on one row of a list.
- size: "sm" | "md". `sm` is dense padding. Defaults to `md`.
- static: true. A row that is neither a button nor a link, for one that holds its own controls: a `<div>` with
no click target and no hover fill (unless `revealOnHover`), taking `actions` as well.
- trailing: ReactNode. Content at the far end of the row: a value, a count, a Pill.

## StatTile

Group: Data

When to use: A single number a person should see first: a total, a date, a balance.

### The one right way
Pass the value already formatted, with its unit: `R 4 250`, `Mar 2029`, `12%`.
```tsx
import { CardGrid, StatTile } from "@hackcove/ui";

<CardGrid columns={2}>
  <StatTile label="Left over" value="R 4 250" hint="after all bills" />
  <StatTile label="Debt-free" value="Mar 2029" />
</CardGrid>
```

### Do
- Pass `value` already formatted, with its unit and grouping (`R 4 250`, `Mar 2029`); the tile does not format.
- `label` names the figure; `hint` is one short line under it.
- `tone` is `neutral`, `positive` or `negative`. A tone colours the value, so give it a sign or a `hint` that says the same; `accent` adds a bar in the same tone across the top.
- Lay several tiles out in a `CardGrid`. A tile is not a button or a link.

### Don't
A raw number has no unit or grouping, so the tile shows a figure nobody can read at a glance.
```tsx
import { CardGrid, StatTile } from "@hackcove/ui";

<CardGrid columns={2}>
  <StatTile label="Left over" value={4250.5} />
  <StatTile label="Savings" value={1250000} />
</CardGrid>
```

The same tones with no sign and no hint: red and green are the only difference, so the meaning is lost without colour.
```tsx
import { CardGrid, StatTile } from "@hackcove/ui";

<CardGrid columns={2}>
  <StatTile label="Left over" value="R 4 250" tone="positive" accent />
  <StatTile label="Total interest" value="R 12 400" tone="negative" accent />
</CardGrid>
```

### Accessibility
- A StatTile is plain text in a `<div>`: the caption, the value and the hint are read in that order.
- The `accent` bar is decoration and hidden from assistive tech.
- Colour alone never carries the tone; a sign or the hint says it.

### Props
### StatTile
One headline figure: an uppercase caption over a large tabular-nums value, with an optional hint line beneath. `tone` colours the value; `accent` adds a bar across the top edge in the same tone. Pass the value already formatted.
- accent: boolean (default false)
- hint: ReactNode
- label: ReactNode (required)
- tone: "positive" | "neutral" | "negative" (default neutral). Defaults to "neutral".
- value: ReactNode (required)

## ProgressBar

Group: Data

When to use: How far something has got toward a whole: money saved, steps done.

### The one right way
Say in words how far along it is, beside the bar. The bar shows the share and the words give the figures.
```tsx
import { Body, Caption, Cluster, ProgressBar, Stack } from "@hackcove/ui";

<Stack gap="xs">
  <Cluster justify="between">
    <Body>Kitchen funded</Body>
    <Caption>R 45 000 of R 75 000</Caption>
  </Cluster>
  <ProgressBar value={45000} max={75000} label="Kitchen funded" />
</Stack>
```

### Do
- `value` is on the scale of `max`, which is 100 unless you pass one: three of twelve is `value={3} max={12}`. A fraction such as `0.25` is read as a quarter of one percent. A value past `max` is held at full.
- `label` is required and names what the bar measures.
- Say the figures in words beside the bar; the bar draws none.
- `tone` is `accent`, `positive`, `warn` or `negative`; `size` is `sm` (default), `md` or `lg`.
- A share between two parties is a `SplitBar`; the parts of one whole are a `StackedBar`.

### Don't
A bare bar: nobody can tell what it measures or how much it holds.
```tsx
import { ProgressBar } from "@hackcove/ui";

<ProgressBar value={60} label="Kitchen funded" />

```

A fraction such as `0.25` is read as a quarter of one percent, not a quarter of the bar.
```tsx
import { ProgressBar } from "@hackcove/ui";

<ProgressBar value={0.25} label="Months saved" />

```

### Accessibility
- A ProgressBar has `role="progressbar"`, `aria-label` set to `label`, and `aria-valuemin`, `aria-valuemax` and `aria-valuenow` on a 0 to 100 scale.
- The announced percent is whole, and is never 0 or 100 unless the value truly is.
- The bar draws no text, so the words beside it carry the figures for everyone.

### Props
### ProgressBar
A thin horizontal bar with a filled share, for progress toward a total. `value` is held to 0–`max`. `label` names what it measures, for a screen reader, which also hears the percentage.
- label: string (required)
- max: number (default 100). Defaults to 100.
- size: "sm" | "md" | "lg" (default sm). Defaults to "sm".
- tone: "positive" | "warn" | "accent" | "negative" (default accent). Defaults to "accent".
- value: number (required)

## SplitBar

Group: Data

When to use: Two sides of one total: a pot split between two goals, for and against.

### The one right way
Give `names` so a screen reader hears whose share is whose, and draw the names under the bar for everyone else.
```tsx
import { Caption, Cluster, SplitBar, Stack } from "@hackcove/ui";

<Stack gap="xs">
  <SplitBar a={35} b={65} label="Pot split" names={["Debt", "Renos"]} />
  <Cluster justify="between">
    <Caption>Debt 35%</Caption>
    <Caption>Renos 65%</Caption>
  </Cluster>
</Stack>
```

### Do
- `a` is the left party and `b` the right; each is sized by its share of `a + b`.
- Give `names` as `[left, right]`, and draw the same names under the bar yourself; the bar draws no text.
- `toneA` defaults to `negative` and `toneB` to `positive`. Set both when neither side is good or bad, e.g. `accent` and `warn`. `size` is `sm`, `md` or `lg` (default).
- More than two parts are a `StackedBar`; progress toward a total is a `ProgressBar`.

### Don't
No `names` and nothing under the bar: the two colours are never explained, and a screen reader hears two bare percentages.
```tsx
import { SplitBar } from "@hackcove/ui";

<SplitBar a={35} b={65} label="Pot split" />

```

### Accessibility
- A SplitBar has `role="img"` and an `aria-label` of `label` followed by each side's whole percent.
- With `names` it hears each name before its percent; without, only two bare percentages.
- Colour alone does not name the parties, so draw their names under the bar.

### Props
### SplitBar
A bar split between two parties, `a` on the left and `b` on the right, each sized by its share of `a + b`. `label` names the split for a screen reader, which hears both percentages; give `names` (left, right) so it hears whose is whose. Put the parties' names under the bar yourself.
- a: number (required)
- b: number (required)
- label: string (required)
- names: readonly [string, string]. The left and right parties, spoken before their percentages.
- size: "sm" | "md" | "lg" (default lg). Defaults to "lg".
- toneA: "positive" | "warn" | "accent" | "negative" (default negative). Defaults to "negative".
- toneB: "positive" | "warn" | "accent" | "negative" (default positive). Defaults to "positive".

## StackedBar

Group: Data

When to use: The make-up of one whole in three or more parts: results by status, spend by group.

### The one right way
`legend` names every colour in words, with its value, under the bar.
```tsx
import { StackedBar } from "@hackcove/ui";

<StackedBar
  segments={[
    { label: "Changed", value: 24, tone: "warn" },
    { label: "New", value: 9, tone: "info" },
    { label: "Same", value: 163, tone: "muted" },
  ]}
  label="Screenshots by status"
  legend
/>
```

### Do
- `segments` are `{ label, value, tone }` in the order to draw; `tone` is `muted`, `positive`, `warn`, `danger` or `info`, and you map your own roles onto them.
- Set `legend` so every colour is named in words under the bar, with its value.
- `Legend` alone is the key for colours drawn elsewhere, such as a `TableRow` `stripe`.
- `size` is `sm`, `md` or `lg` (default). A part with no value is zero wide.
- Two parties are a `SplitBar`; progress toward a total is a `ProgressBar`.

### Don't
Without `legend` the colours are never named, so the bar cannot be read by anyone who cannot tell them apart.
```tsx
import { StackedBar } from "@hackcove/ui";

<StackedBar
  segments={[
    { label: "Changed", value: 24, tone: "warn" },
    { label: "New", value: 9, tone: "info" },
    { label: "Same", value: 163, tone: "muted" },
  ]}
  label="Screenshots by status"
/>
```

### Accessibility
- The bar has `role="img"` and an `aria-label` of `label` followed by every part's name and whole percent; rounded, they may not add up to exactly 100.
- A `Legend` is a list. Its swatches are hidden from assistive tech and its labels are always drawn, so colour is never the only signal.

### Props
### StackedBar
A bar of any number of parts, each sized by its share of the sum, in the order given. A part with no value is zero wide. `label` names the bar for a screen reader, which hears every part's name and whole percent (rounded, so they may not add up to exactly 100). `legend` draws a `Legend` under the bar, each part's label with its value, so the colours are named in words.
- label: string (required)
- legend: boolean (default false). Draw the key under the bar. Defaults to false.
- segments: readonly StackedSegment[] (required)
- size: "sm" | "md" | "lg" (default lg). Defaults to "lg".

### Legend
A key to the colours of a chart or a row stripe: a swatch in the `TextTone` colour, its `label` and an optional `detail` after it. Colour alone does not say it, so the label is always drawn. `StackedBar legend` draws one under the bar from its segments.
- items: readonly LegendItem[] (required)

## Callout

Group: Feedback

When to use: A message the reader should see in the page, without being made to answer it.

### The one right way
The tone matches how much the message matters: `warn` for a thing to check before going on.
```tsx
import { Callout, Stack } from "@hackcove/ui";

<Stack gap="sm">
  <Callout tone="info">The import runs overnight.</Callout>
  <Callout tone="warn" title="3 uncategorised.">
    Sort them before the month closes.
  </Callout>
</Stack>
```

### Do
- Pick the `tone` by how much the message matters: `neutral` for a note, `info` (the default) for something worth knowing, `positive` for a result, `warn` for a thing to check before going on, `danger` for a failure or something that cannot be undone. Keep `danger` for the real failure.
- Add a `title` for a short bold lead-in; the body carries the detail.
- Put the one action in `actions`, at the end of the row: a `Button size="sm"` or a `TextLink stretch`, which makes the whole callout the click target.
- `banner` is the flat strip at the top of a `Card flush`; do not use it anywhere else.
- A message that must be answered before the reader goes on is a `Dialog`; a field's own error is the `error` of its `Field`.

### Don't
`danger` on a plain note cries wolf: when everything is red, a real failure no longer stands out.
```tsx
import { Callout, Stack } from "@hackcove/ui";

<Stack gap="sm">
  <Callout tone="danger">The import runs overnight.</Callout>
  <Callout tone="danger" title="3 uncategorised.">
    Sort them before the month closes.
  </Callout>
</Stack>
```

A button inside the body drops under the text and leaves the row without its action.
```tsx
import { Button, Callout } from "@hackcove/ui";

<Callout tone="warn" title="Import failed.">
  The last file did not finish. <Button size="sm">Retry</Button>
</Callout>
```

### Accessibility
- A Callout is a plain `<div>` with no role and no live region, so a screen reader does not announce it when it appears; the tone is colour and text, so say what happened in the words.
- A `title` is a bold paragraph, not a heading, so it adds nothing to the heading outline.
- Buttons and links in `actions` keep their own focus ring and keyboard behaviour.

### Props
### Callout
A tinted notice box, with an optional bold title above its body. `actions` puts a button or link at the end of the row; `banner` makes it a flat strip (bottom border only, no radius) for the top of a `Card flush` (a padded card would inset it). With `actions` the box is `relative`, so a `TextLink stretch` there makes the whole callout its click target, like a link in a table row.
- actions: ReactNode. A button or link at the end of the row, beside the title and body.
- banner: boolean (default false). A flat strip: `border-b` only and no radius, to sit above a card body.
- title: ReactNode
- tone: "positive" | "danger" | "neutral" | "info" | "warn" (default info). Defaults to "info".

## EmptyState

Group: Feedback

When to use: A whole page or list with no content yet: say what belongs here and offer the first step.

### The one right way
An empty page says what belongs here and offers the first step as the primary action.
```tsx
import { Body, Button, EmptyState } from "@hackcove/ui";

<EmptyState title="No builds yet" actions={<Button>Create a project</Button>}>
  <Body as="p">Builds appear here once a project has uploaded its first capture.</Body>
</EmptyState>
```

### Do
- Give it a `title`, one `Body as="p"` that says what belongs here, and the first step as `actions`, with the primary `Button` first.
- For a get-started list, put `Steps` after the `Body` in the children.
- One muted line inside a card, for an empty table or list, is `Empty`, not an EmptyState.
- Do not leave it as a title alone: a page with nothing in it and nothing to do is a dead end.

### Don't
A bare "Nothing here" is a dead end: it does not say what belongs here or what to do next.
```tsx
import { EmptyState } from "@hackcove/ui";

<EmptyState title="Nothing here" />

```

`EmptyState` is for a whole page or list; inside a small card it is a block that dwarfs the card.
```tsx
import { Body, Card, EmptyState } from "@hackcove/ui";

<Card title="Builds">
  <EmptyState title="No builds yet">
    <Body as="p">Builds appear here once a project has uploaded its first capture.</Body>
  </EmptyState>
</Card>
```

### Accessibility
- An EmptyState is a `<section>` named by its `title`, which is an `h2`, so it is a landmark region a screen reader can jump to.
- The actions are ordinary buttons and links, in reading order after the explanation.

### Props
### EmptyState
What a list or a page shows when there is nothing in it yet: a centred `title`, the `children` as the explanation under it (a `Body as="p"`, then `Steps` for a "get started" list), and `actions` (buttons, links) in a centred row at the bottom. A named `<section>`. For one muted line inside a card, use `Empty`.
- actions: ReactNode
- title: ReactNode (required)

## Dialog

Group: Feedback

When to use: A confirmation or a short form the reader must answer before they go on.

### The one right way
A confirmation is a title that names the action, one line of consequence, and Cancel beside the action. It is rendered only while open.
```tsx
import { useState } from "react";
import { Button, Dialog } from "@hackcove/ui";

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Delete build
      </Button>
      {open && (
        <Dialog
          title="Delete build"
          description="This removes the build and every snapshot in it."
          onClose={() => setOpen(false)}
          footer={
            <>
              <Button variant="ghost" onClick={() => setOpen(false)}>
                Cancel
              </Button>
              <Button tone="danger" onClick={() => setOpen(false)}>
                Delete
              </Button>
            </>
          }
        />
      )}
    </>
  );
}
```

### Do
- Render it only while it is open: `{open && <Dialog … onClose={() => setOpen(false)} />}`. It opens itself on mount.
- A `title` that names the action, a `description` with the consequence, and the actions in `footer`: Cancel as `variant="ghost"` first, then the one action, `tone="danger"` when it destroys something.
- `size="sm"` is a short list; `md`, the default, holds a form. A submit button in the footer reaches a form in the body with its `form` attribute.
- One text field is a `FieldDialog`. A record or a long form is a `Drawer`. A message that needs no answer is a `Callout`.

### Don't
With no Cancel and no consequence, the only way out of the dialog is the one button that destroys the build.
```tsx
import { useState } from "react";
import { Button, Dialog } from "@hackcove/ui";

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Delete build
      </Button>
      {open && (
        <Dialog
          title="Are you sure?"
          onClose={() => setOpen(false)}
          footer={
            <Button tone="danger" onClick={() => setOpen(false)}>
              Delete
            </Button>
          }
        />
      )}
    </>
  );
}
```

A modal for a message makes the reader dismiss it before they can carry on.
```tsx
import { useState } from "react";
import { Button, Dialog } from "@hackcove/ui";

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Save
      </Button>
      {open && (
        <Dialog
          title="Saved"
          description="Your review is saved."
          onClose={() => setOpen(false)}
          footer={<Button onClick={() => setOpen(false)}>OK</Button>}
        />
      )}
    </>
  );
}
```

### Accessibility
- A Dialog is the browser's own `<dialog>` opened with `showModal()`: the page behind goes inert, focus stays inside it and Esc closes it.
- It is named by its `title`, an `h2`, through `aria-labelledby`.
- A click on the backdrop closes it, and so does a submit of a `<form method="dialog">`; every close calls `onClose`.
- The browser focuses the first focusable element in it when it opens; put `autoFocus` on the button that should have focus first.

### Props
### Dialog
A modal on the browser's own `<dialog>`: it is opened with `showModal()` on mount, so render it only while it is open. The page behind goes inert, Esc closes it and focus stays inside; a click on the backdrop (the `<dialog>` element itself, not its contents) closes it too.
- description: ReactNode
- footer: ReactNode. Actions under the body, right-aligned. A submit button here can reach a form in the body with its `form` attribute.
- onClose: () => void (required). Called when the dialog closes: Esc, a click on the backdrop, or a `<form method="dialog">` submit.
- size: "sm" | "md" (default md). `sm` is a list; `md` (the default) holds a form.
- title: ReactNode (required). The dialog's accessible name, shown as its heading.

## Drawer

Group: Feedback

When to use: A record or a form the reader works on beside the page, with actions that stay in view.

### The one right way
A record or a form beside the page: the title names it, the body scrolls and the actions stay pinned in `footer`.
```tsx
import { useState } from "react";
import { Button, Drawer, KeyValue, KeyValueList } from "@hackcove/ui";

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open HC-65
      </Button>
      {open && (
        <Drawer
          title="HC-65 · Tabs"
          onClose={() => setOpen(false)}
          footer={
            <>
              <Button variant="ghost" onClick={() => setOpen(false)}>
                Cancel
              </Button>
              <Button onClick={() => setOpen(false)}>Save</Button>
            </>
          }
        >
          <KeyValueList>
            <KeyValue label="Status">In progress</KeyValue>
            <KeyValue label="Owner">Jacobus</KeyValue>
          </KeyValueList>
        </Drawer>
      )}
    </>
  );
}
```

### Do
- Render it only while it is open: `{open && <Drawer … onClose={() => setOpen(false)} />}`. It opens itself on mount.
- Use it for a record to read or edit, or a form with several fields; a yes-or-no question is a `Dialog`.
- The actions go in `footer`, pinned under the body, which scrolls between the header and the footer.
- `size` is `sm`, `md` (the default) or `lg`; choose by the content, `sm` for one field and `lg` for a table.
- Set `closeLabel` to the reader's language when the page is not in English.

### Don't
A yes-or-no question is a `Dialog`: a full-height panel for one confirmation is more than it asks.
```tsx
import { useState } from "react";
import { Body, Button, Drawer } from "@hackcove/ui";

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Delete build
      </Button>
      {open && (
        <Drawer
          title="Delete build?"
          size="sm"
          onClose={() => setOpen(false)}
          footer={<Button onClick={() => setOpen(false)}>Delete</Button>}
        >
          <Body>This removes the build and every snapshot in it.</Body>
        </Drawer>
      )}
    </>
  );
}
```

A Save in the body scrolls out of view with a long form and leaves the footer empty.
```tsx
import { useState } from "react";
import { Button, Drawer, Field, Input, Stack } from "@hackcove/ui";

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        Rename
      </Button>
      {open && (
        <Drawer title="Rename" size="sm" onClose={() => setOpen(false)}>
          <Stack>
            <Field label="Name" htmlFor="drawer-rename-body">
              <Input id="drawer-rename-body" defaultValue="Hack Cove" />
            </Field>
            <Button onClick={() => setOpen(false)}>Save</Button>
          </Stack>
        </Drawer>
      )}
    </>
  );
}
```

### Accessibility
- A Drawer is the browser's own `<dialog>` opened with `showModal()`: the page behind goes inert, focus stays inside it and Esc closes it.
- It is named by its `title`, an `h2`, through `aria-labelledby`.
- The header's close button is an `IconButton` named by `closeLabel` ("Close" by default); a click on the scrim closes it too.
- Closing, or unmounting it, hands focus back to the element that opened it.
- The slide-in is switched off under `prefers-reduced-motion: reduce`.

### Props
### Drawer
A modal slide-over anchored to the right edge, on the browser's own `<dialog>`: it is opened with `showModal()` on mount, so render it only while it is open. The page behind goes inert, Esc closes it and focus stays inside; a click on the scrim (the `<dialog>` element itself, not its contents) closes it too. The header holds the title and a close button; the body scrolls between it and an optional pinned `footer`.
- closeLabel: string (default Close). The accessible name of the close button.
- footer: ReactNode. Actions pinned under the scrolling body, right-aligned.
- onClose: () => void (required). Called when the drawer closes: Esc, a click on the scrim or the close button.
- size: "sm" | "md" | "lg" (default md). `md` (the default) holds a form or a record; `sm` is narrower and `lg` wider.
- title: ReactNode (required). The drawer's accessible name, shown as its heading.

## FieldDialog

Group: Feedback

When to use: Asking for a single name or value: new project, rename, a label.

### The one right way
One value to ask for is a `FieldDialog`: it blocks an empty submit, shows the busy state and puts a rejection under the field.
```tsx
import { useState } from "react";
import { Button, FieldDialog } from "@hackcove/ui";

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        New project
      </Button>
      {open && (
        <FieldDialog
          title="New project"
          description="Projects hold your builds and their reviews."
          label="Name"
          inputLabel="Project name"
          placeholder="my-project"
          hint="Letters, numbers and dashes."
          emptyReason="Type a name first."
          submit="Create"
          busyLabel="Creating…"
          onSubmit={() => new Promise((resolve) => setTimeout(resolve, 600))}
          onClose={() => setOpen(false)}
        />
      )}
    </>
  );
}
```

### Do
- Render it only while it is open, and give every string it shows: `title`, `label`, `inputLabel`, `placeholder`, `hint`, `emptyReason`, `submit` and `busyLabel`.
- `onSubmit` gets the trimmed value and returns a promise. Resolving closes the dialog; rejecting shows the error message under the field and keeps the dialog open.
- More than one field is a `Dialog` with a `FormRow` or `Field`s, or a `Drawer`.

### Don't
A `Dialog` with a hand-built field has no empty check, no busy state and no error line, and each copy drifts from the next.
```tsx
import { useState } from "react";
import { Button, Dialog, Field, Input } from "@hackcove/ui";

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="outline" onClick={() => setOpen(true)}>
        New project
      </Button>
      {open && (
        <Dialog
          title="New project"
          onClose={() => setOpen(false)}
          footer={<Button onClick={() => setOpen(false)}>Create</Button>}
        >
          <Field label="Name" htmlFor="project-name">
            <Input id="project-name" placeholder="my-project" />
          </Field>
        </Dialog>
      )}
    </>
  );
}
```

### Accessibility
- It is a `Dialog`: native `<dialog>`, page behind inert, focus kept inside, Esc closes, named by its `title`.
- The input has focus when it opens and is named by `inputLabel`.
- While the field is empty the submit button is disabled and its `emptyReason` is the button's title and the field's hint.
- While `onSubmit` is pending the button is busy (`aria-busy`); a rejection shows in the field's error line, which is `role="alert"`.

### Props
### FieldDialog
A `Dialog` with one text field and Cancel / submit buttons. Render it only while open.
- busyLabel: string (required)
- description: string
- emptyReason: string (required). Said when the field is empty and the submit button is blocked.
- hint: string (required)
- inputLabel: string (required). The field's accessible name, when it says more than the visible label.
- label: string (required). The visible label above the field.
- onClose: () => void (required)
- onSubmit: (value: string) => Promise<unknown> (required). Gets the trimmed value. Resolving closes the dialog; a rejection shows its message in it.
- placeholder: string (required)
- submit: string (required)
- title: string (required)

## PageFade

Group: Feedback

When to use: A site where the frame stays put and only the content between pages should fade.

### The one right way
`PageFade` wraps only the content that changes between pages; the frame around it, with the control, stays put.
```tsx
import { useState } from "react";
import {
  Body,
  PageFade,
  SegmentedControl,
  Stack,
  startPageTransition,
} from "@hackcove/ui";

function Example() {
  const [value, setValue] = useState("overview");
  const items = [
    { value: "overview", label: "Overview" },
    { value: "activity", label: "Activity" },
  ];
  return (
    <Stack gap="sm">
      <SegmentedControl
        label="Page"
        items={items}
        value={value}
        onChange={(next) => startPageTransition(() => setValue(next))}
      />
      <PageFade>
        <Body>The {value} page.</Body>
      </PageFade>
    </Stack>
  );
}
```

### Do
- Wrap what changes between pages, once per page, and leave the header and footer outside it.
- Start the change inside a view transition: `startPageTransition(() => setPage(next))` for a state change, or the router's own option (TanStack Router `viewTransition`, React Router's `viewTransition`, Astro's `ClientRouter`). Without one nothing fades.
- Two PageFades on one page each need their own `name`.
- Portal an overlay such as a dropdown to the body: the fading area is a stacking context, so an overlay inside it cannot rise above a sticky header outside it.

### Don't
Wrapping the frame too makes the control fade with the content, so the page flickers instead of changing in place.
```tsx
import { useState } from "react";
import {
  Body,
  PageFade,
  SegmentedControl,
  Stack,
  startPageTransition,
} from "@hackcove/ui";

function Example() {
  const [value, setValue] = useState("overview");
  const items = [
    { value: "overview", label: "Overview" },
    { value: "activity", label: "Activity" },
  ];
  return (
    <PageFade>
      <Stack gap="sm">
        <SegmentedControl
          label="Page"
          items={items}
          value={value}
          onChange={(next) => startPageTransition(() => setValue(next))}
        />
        <Body>The {value} page.</Body>
      </Stack>
    </PageFade>
  );
}
```

A plain state change swaps the content at once: there is no transition to fade.
```tsx
import { useState } from "react";
import { Body, Button, PageFade, Stack } from "@hackcove/ui";

function Example() {
  const [value, setValue] = useState("overview");
  return (
    <Stack gap="sm">
      <Button
        variant="outline"
        onClick={() => setValue(value === "overview" ? "activity" : "overview")}
      >
        Switch page
      </Button>
      <PageFade>
        <Body>The {value} page.</Body>
      </PageFade>
    </Stack>
  );
}
```

### Accessibility
- A PageFade is a plain `<div>` with no role, so it changes nothing for assistive technology.
- Under `prefers-reduced-motion: reduce` the content swaps with no fade, and `startPageTransition` just runs the update.
- Where the browser has no View Transitions it is a plain `<div>` and the content swaps.

### Props
### PageFade
The page's content area, named for the View Transitions API so a route change cross-fades it while the frame around it (header, footer) stays put. Wrap what changes between pages, once per page: two on one page need a different `name` each, or the browser skips the transition. The fade runs only when the navigation is wrapped in a view transition: `startPageTransition`, or a router's own option (TanStack Router `viewTransition`, React Router's `viewTransition` prop, Astro's `ClientRouter`). Otherwise, or where the browser has no View Transitions, it renders and behaves as a plain `<div>`. A `view-transition-name` makes the div a stacking context, so a dropdown inside it cannot rise above a sticky header outside it: portal overlays to the body. Under `prefers-reduced-motion: reduce` this content swaps with no fade; a router's own transition of the rest of the page is the router's to quiet.
- name: string (default hc-page). The view-transition name, a CSS identifier (letters, digits, `-`, `_`).

### Functions
- startPageTransition: runs a synchronous state change inside a view transition, so a PageFade cross-fades; call it from an event handler.

## Tabs

Group: Navigation

When to use: Tabs switch a panel on the same page. A row of links to other pages is NavTabs.

### The one right way
`Tabs` switches a view in place; the panel it controls sits right under the row.
```tsx
import { useState } from "react";
import { Body, Stack, Tabs } from "@hackcove/ui";

function Example() {
  const [value, setValue] = useState("overview");
  return (
    <Stack>
      <Tabs
        label="Project views"
        value={value}
        onChange={setValue}
        items={[
          { value: "overview", label: "Overview", controls: "panel" },
          { value: "activity", label: "Activity", controls: "panel" },
          { value: "settings", label: "Settings", controls: "panel" },
        ]}
      />
      <Body id="panel" role="tabpanel">
        Showing {value}.
      </Body>
    </Stack>
  );
}
```

### Do
- `Tabs` switches a view in place; the caller owns `value` and `onChange`, and the panel sits right under the row.
- Going to another page is `NavTabs`: links, so the URL, the back button and a new tab all work.
- A `count` sits muted after the label and is read as part of the tab's name.
- `variant="pill"` fills the current tab, for under a `PageHeader`.
- A disabled tab keeps a `title` as the reason.
- `NavTabs` with `orientation="vertical"` is the rail of a `SidebarLayout`: one link per line.

### Don't
A `Tabs` row that only navigates leaves the URL, the back button and a new tab behind.
```tsx
import { useState } from "react";
import { Tabs } from "@hackcove/ui";

function Example() {
  const [value, setValue] = useState("quotes");
  return (
    <Tabs
      label="Sections"
      value={value}
      onChange={(next) => {
        setValue(next);
        location.assign(`#${next}`);
      }}
      items={[
        { value: "quotes", label: "Quotes" },
        { value: "invoices", label: "Invoices" },
      ]}
    />
  );
}
```

A count typed into the label is plain text: it does not mute, and it cannot be styled the same.
```tsx
import { useState } from "react";
import { Tabs } from "@hackcove/ui";

function Example() {
  const [value, setValue] = useState("shots");
  return (
    <Tabs
      label="Assets"
      value={value}
      onChange={setValue}
      items={[
        { value: "shots", label: "Shots (12)" },
        { value: "clips", label: "Clips (3)" },
      ]}
    />
  );
}
```

A stack of ghost `ButtonLink`s is not a nav landmark, and nothing marks the current page.
```tsx
import { ButtonLink, Stack } from "@hackcove/ui";

<Stack gap="xs">
  <ButtonLink href="#overview" variant="ghost">
    Overview
  </ButtonLink>
  <ButtonLink href="#button" variant="ghost">
    Button
  </ButtonLink>
  <ButtonLink href="#card" variant="ghost">
    Card
  </ButtonLink>
</Stack>
```

### Accessibility
- The row is a tab list named by `label`; the arrow keys, Home and End move between the tabs, and a disabled tab is skipped.
- Give the panel `role="tabpanel"` and a tab `controls` that points at its `id`.
- A tab is a `button` with `role="tab"` and `aria-selected`; only the current tab is in the tab order, and the arrow keys move and choose.
- `NavTabs` is a `<nav>` named by `label`; the current link gets `aria-current="page"`.

### Props
### Tabs
Underline tabs for switching a view in place: a row over a bottom rule, the current tab underlined in the accent. `items` are `{ value, label }` buttons (`value` and `onChange` are the caller's state; the arrow keys, Home and End move between tabs) or links (`href`, or `render` to draw the app's own router `<Link>`; `value` marks the current one, which gets `aria-current`). `variant="pill"` fills the current tab instead, with no rule, for under a `PageHeader`. An item may carry a `count`, and a button one `disabled` (with a `title` for the reason); `disabled` on the row disables every tab. `label` names the tab list. The panel is the caller's: give it `role="tabpanel"`, and a tab `controls` to point at it.
- disabled: boolean. Every option is disabled, e.g. until the page has hydrated.
- items: SwitchButton[] | SwitchLink[] (required)
- label: string (required). The accessible name of the group.
- onChange: ((value: string) => void). Called with the option's `value` when one is chosen, by click or arrow key.
- value: string (required). The `value` of the current option.
- variant: "underline" | "pill" (default underline). `underline` (default) is a row over a bottom rule; `pill` fills the current tab, as `NavTabs` does.

### NavTabs
A row of pill links where the active one is filled. Plain <a> by default; a tab's `render` draws a router's Link. `orientation="vertical"` stacks the same links in one column at the rail's width, for a `SidebarLayout` rail: the same pill, the same `aria-current`, one link per line.
- items: NavTab[] (required)
- label: string (required). The accessible name of the nav landmark.
- orientation: "horizontal" | "vertical" (default horizontal)

### Functions
- navTabClass: The classes of one NavTabs pill (current or not, disabled drops the hover fill), for a router link that has to look like a tab.

## Breadcrumbs

Group: Navigation

When to use: A page several levels deep that needs a way back up: org, project, build, snapshot.

### The one right way
A parent crumb is `{ label, href }` and the last is plain text: the trail that leads back up, ending at the current page.
```tsx
import { Breadcrumbs } from "@hackcove/ui";

<Breadcrumbs
  crumbs={[
    { label: "Projects", href: "#projects" },
    { label: "Launch film", href: "#launch-film" },
    "Shots",
  ]}
/>
```

### Do
- Give the trail in order, parents first. A parent that links is `{ label, href }` (or `{ label, render }` for the app's router link); the last crumb is the current page, plain text.
- Breadcrumbs show a hierarchy. Peer sections are `NavTabs`.
- Each crumb truncates, so a long name does not widen the row.
- Put the trail in the `breadcrumbs` slot of a `PageHeader`.

### Don't
Parents given as plain text look like the trail but lead nowhere, so a reader cannot go back up.
```tsx
import { Breadcrumbs } from "@hackcove/ui";

<Breadcrumbs crumbs={["Projects", "Launch film", "Shots"]} />

```

Siblings are not a hierarchy: switching between peer sections is `NavTabs`.
```tsx
import { Breadcrumbs } from "@hackcove/ui";

<Breadcrumbs
  crumbs={[
    { label: "Quotes", href: "#quotes" },
    { label: "Invoices", href: "#invoices" },
    "Receipts",
  ]}
/>
```

### Accessibility
- `<nav aria-label="Breadcrumb">` around an ordered list.
- The last item has `aria-current="page"` and is never a link.
- The `/` separators are `aria-hidden`.

### Props
### Breadcrumbs
`org / project / build / snapshot`: each crumb truncates, and the last is the current page. A crumb is a node, or a `Crumb` object when it links.
- crumbs: (ReactNode | Crumb)[] (required)

### Functions
- crumbLinkClass: The classes of a crumb that links, for a router link drawn outside `render`.

## Status pages

Group: Pages

When to use: A route that cannot show its content: use the status page that names the state.

### The one right way
A missing page is `NotFound`: the reader needs a way home, and a retry would load the same nothing.
```tsx
import { NotFound } from "@hackcove/ui";

<NotFound homeHref="#" />

```

### Do
- Pick the page by the state: `NotFound` for a missing page (404), `Forbidden` for a page the reader may not see (403), `ErrorPage` for a failure (500), `Offline` for no connection, `Maintenance` for a site that is down on purpose.
- The copy is fixed, so every site reads the same. Change the heading with `title` and the text with children only when the state needs a specific line.
- `homeHref` adds a "Back to home" button; with a router, `renderHome` draws it with the app's own `<Link>`.
- `onRetry` adds a "Try again" button on `ErrorPage` and `Offline`; `action` replaces it with the one action that fits, and the home link turns outline beside it. Do not offer a retry where trying again cannot help.
- On `ErrorPage`, `detail` is a request id or a short message a reader can quote. Never a stack trace.
- Render one as the content of an `AppShell`, or on its own in a `Container`.

### Don't
`ErrorPage` with a retry for a missing page promises that trying again helps, and it does not.
```tsx
import { ErrorPage } from "@hackcove/ui";

<ErrorPage onRetry={() => {}} homeHref="#" />

```

A stack trace shows the reader your internals and buries the one line they can act on.
```tsx
import { ErrorPage } from "@hackcove/ui";

<ErrorPage
  detail={
    "TypeError: Cannot read properties of undefined\n  at loadBuild (build.ts:42:9)\n" +
    "  at async handler (route.ts:17:3)"
  }
  onRetry={() => {}}
  homeHref="#"
/>
```

### Accessibility
- Each page is a `CenteredLayout` card, so the title is the page's `h1` and the copy under it is a paragraph.
- `detail` is shown in a `CodeBlock` labelled "Error".
- The buttons are a `Button` and a `ButtonLink`, with their own focus rings; "Back to home" is a real link.
- The pages do not set an HTTP status; send the 404, 403 or 500 from the server.

### Props
### NotFound
404: the page is not there.
- action: ReactNode. The primary action; the home link turns outline beside it.
- children: ReactNode. Replaces the default body copy.
- homeHref: string. Adds a "Back to home" button linking here. With neither this nor `renderHome` there is no home link.
- renderHome: LinkRender. Draws the home link with the app's own router `<Link>`, as on `ButtonLink`.
- title: ReactNode. Replaces the default heading.

### Forbidden
403: signed in, or not, but not allowed here.
- action: ReactNode. The primary action; the home link turns outline beside it.
- children: ReactNode. Replaces the default body copy.
- homeHref: string. Adds a "Back to home" button linking here. With neither this nor `renderHome` there is no home link.
- renderHome: LinkRender. Draws the home link with the app's own router `<Link>`, as on `ButtonLink`.
- title: ReactNode. Replaces the default heading.

### ErrorPage
500 or any failure. `detail` is the error text, shown in a `CodeBlock` under the copy; pass it only where a reader may see it (a request id, a message), never a stack trace. `onRetry` adds a "Try again" button, unless `action` replaces it.
- action: ReactNode. The primary action; the home link turns outline beside it.
- children: ReactNode. Replaces the default body copy.
- detail: string
- homeHref: string. Adds a "Back to home" button linking here. With neither this nor `renderHome` there is no home link.
- onRetry: () => void
- renderHome: LinkRender. Draws the home link with the app's own router `<Link>`, as on `ButtonLink`.
- title: ReactNode. Replaces the default heading.

### Offline
The device has no connection. `onRetry` adds a "Try again" button, unless `action` replaces it.
- action: ReactNode. The primary action; the home link turns outline beside it.
- children: ReactNode. Replaces the default body copy.
- homeHref: string. Adds a "Back to home" button linking here. With neither this nor `renderHome` there is no home link.
- onRetry: () => void
- renderHome: LinkRender. Draws the home link with the app's own router `<Link>`, as on `ButtonLink`.
- title: ReactNode. Replaces the default heading.

### Maintenance
The site is down on purpose and will be back.
- action: ReactNode. The primary action; the home link turns outline beside it.
- children: ReactNode. Replaces the default body copy.
- homeHref: string. Adds a "Back to home" button linking here. With neither this nor `renderHome` there is no home link.
- renderHome: LinkRender. Draws the home link with the app's own router `<Link>`, as on `ButtonLink`.
- title: ReactNode. Replaces the default heading.