division-ds 0.1.2 → 0.2.1

package/public/docs/components/multi-select.md

@@ -0,0 +1,202 @@
+# MultiSelect
+
+> Pick several choices from a list. The chosen ones sit inside the field as tags you can remove, followed by a text field that filters the list as you type. It's the many-values version of Select.
+
+- **Best for:** Any number of choices, including none, from a list too long to show all at once.
+- **Not for:** A single choice: use Select, or Radio when there are fewer than about five options. A handful that all fit: use Checkbox.
+- Molecule. Source: `src/components/molecules/multi-select/MultiSelect.tsx`
+- Rendered docs page: `/components/multi-select`
+
+## Import
+
+```tsx
+import { MultiSelect } from 'src/components/molecules/multi-select/MultiSelect'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Requires
+
+- A <FormField> around it. FormField supplies the visible label, the help and the error, and replaces the label prop with its own.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The name screen readers give the text field and the list. FormField replaces it with its own label. |
+| `options` | `SelectOption[]` |  | { value, label, disabled? }, the same rows Select takes. |
+| `value` | `string[]` |  | The current selection when the page keeps track of it (controlled), as option values in the order they were chosen. |
+| `defaultValue` | `string[]` |  | The starting selection when the component keeps track itself (uncontrolled). |
+| `onValueChange` | `(value: string[]) => void` |  | Runs with the whole new array every time an option is added or removed. |
+| `placeholder` | `string` | `'Select…'` | Shown while nothing is chosen. |
+| `emptyMessage` | `string` | `'No matches'` | Shown in the panel when the typed text matches no option. |
+| `inputSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Matches Input and Select: a minimum height of 32, 40 or 48px (pixels), with text at size xs, sm or base. It also sets the size of the typed text and of the option rows in the list (28, 32 or 40px). The tags come in one size, so sm fits a single row of them snugly, and md and lg add room around it. The field grows past the minimum as tags wrap. |
+| `invalid` | `boolean` | `false` | Sets aria-invalid (which tells screen readers the value has a problem) and the invalid border. FormField sets it from error. |
+| `disabled` | `boolean` | `false` | Turns the field off. The chosen tags stay visible, without their remove buttons. |
+| `required` | `boolean` | `false` | Sets aria-required on the text field, so screen readers say it's required. |
+| `name` | `string` |  | Sends each chosen value with the form as its own hidden input under this name. |
+| `className` | `string` |  | Extra CSS classes, merged onto the field. |
+| `ref` | `Ref<HTMLInputElement>` |  | Passed through to the text field. |
+| `id` | `string` |  | The text field’s id. FormField sets it. |
+| `aria-describedby` | `string` |  | The ids of the help and error text, put on the text field so screen readers read them. FormField sets it. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Default
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+<div className="w-full max-w-md">
+  <FormField label="Loadout">
+    <MultiSelect label="Loadout" options={LOADOUT} placeholder="Choose your kit…" />
+  </FormField>
+</div>
+```
+
+### Controlled: the page holds the chosen options
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+function ControlledExample() {
+  const [kit, setKit] = useState<string[]>(['mags', 'goggles', 'gloves'])
+  return (
+    <div className="flex flex-col gap-2 w-full max-w-md">
+      <FormField label="Loadout" help="Remove a tag and watch the others close the gap.">
+        <MultiSelect label="Loadout" options={LOADOUT} value={kit} onValueChange={setKit} />
+      </FormField>
+      <span className="font-mono text-xs text-[var(--color-text-secondary)]">value: [{kit.join(', ')}]</span>
+    </div>
+  )
+}
+
+<ControlledExample />
+```
+
+### Invalid
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+<div className="w-full max-w-md">
+  <FormField label="Loadout" error="Pick eye protection.">
+    <MultiSelect label="Loadout" options={LOADOUT} defaultValue={['mags']} />
+  </FormField>
+</div>
+```
+
+### Sizes
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+<div className="flex flex-col gap-3 w-full max-w-md">
+  <MultiSelect label="Small loadout" inputSize="sm" options={LOADOUT} defaultValue={['mags']} />
+  <MultiSelect label="Medium loadout" inputSize="md" options={LOADOUT} defaultValue={['mags']} />
+  <MultiSelect label="Large loadout" inputSize="lg" options={LOADOUT} defaultValue={['mags']} />
+</div>
+```
+
+### Disabled
+
+```tsx
+const LOADOUT = [
+  { value: 'mags', label: 'Spare magazines' },
+  { value: 'goggles', label: 'Full-seal goggles' },
+  { value: 'mesh', label: 'Mesh face guard' },
+  { value: 'radio', label: 'Team radio', disabled: true },
+  { value: 'gloves', label: 'Gloves' },
+  { value: 'loader', label: 'Speed loader' },
+  { value: 'tracer', label: 'Tracer unit' },
+  { value: 'pouch', label: 'Dump pouch' },
+]
+
+<div className="w-full max-w-md">
+  <MultiSelect label="Locked loadout" options={LOADOUT} defaultValue={['mags', 'gloves']} disabled />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `↓` `↑` | Opens the list, then moves the highlight, skipping rows that are turned off. |
+| `Enter` | Adds or removes the highlighted option. The list stays open. |
+| `Backspace` | When the text field is empty, removes the last tag. |
+| `Esc` | Closes the list. Press it again to clear the typed text. |
+| `Tab` | Moves through the tags’ remove buttons and the text field, and closes the list on the way out. |
+
+## Do
+
+- Use it when someone may pick any number of options, including none.
+- Wrap it in a FormField, like every other form control.
+- Keep option labels short. They become tags, and long tags wrap the field onto many lines.
+- Turn off (disable) an option that isn't available, instead of leaving it out.
+
+## Don't
+
+- Don't use it for a single choice. That's Select, or radios when there are fewer than about five options.
+- Don't use it for a handful of options that all fit on screen. Checkboxes show every choice at once.
+- Don't put actions in the list. It chooses values, and a command belongs in a DropdownMenu.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<Select label="Kit" options={kit} /> // then a second Select for the next item
+```
+
+Right:
+
+```tsx
+<MultiSelect label="Kit" options={kit} value={chosen} onValueChange={setChosen} />
+```
+
+Select holds one value. A list of picks is one MultiSelect, whose value is a string array (a list of text values).
+
+## Anatomy
+
+- **Field**: Looks like Input, but grows to fit: it wraps onto more lines as tags are added. Clicking anywhere on it puts focus in the text field and opens the list.
+- **Tag**: One for each chosen option, in the order they were chosen. Removing one fades it out and slides the tags after it into its place (M7). Focus goes back to the text field.
+- **Text field**: Has role="combobox", which tells screen readers it's a text field with a list attached. Typing filters the list. The placeholder only shows while nothing is chosen.
+- **Listbox**: The list, where several options can be chosen. It sits in a panel rendered in a portal (at the end of the page, so nothing clips it), with the same background as Select and the crosshair. It slides down out of the field and back up into it (M7). A tick marks every chosen row.

package/public/docs/components/navbar.md

@@ -0,0 +1,144 @@
+# Navbar
+
+> The top of a page: the brand, the main links and a few actions. When its container gets narrow, the links move into a menu sheet. Nothing gets cut off, and nothing is hidden for good.
+
+- **Best for:** The top of a site: the brand, up to about six main links and a few actions.
+- **Not for:** App navigation across many grouped pages: use Sidebar.
+- Organism. Source: `src/components/organisms/navbar/Navbar.tsx`
+- Rendered docs page: `/components/navbar`
+
+## Import
+
+```tsx
+import { Navbar } from 'src/components/organisms/navbar/Navbar'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The name screen readers give the navigation region. |
+| `brand` | `ReactNode` |  | Required. The wordmark or logo, usually a link to the home page. |
+| `items` | `NavbarItem[]` |  | Required. Each item has label, href and current. |
+| `actions` | `ReactNode` |  | Controls on the right: icon buttons, a cart link, an account menu. Keep them small, because they stay visible at every width. |
+| `renderLink` | `(props: LinkRenderProps) => ReactNode` | `a plain anchor` | Pass your router's link component here. Map href to its own prop, and pass className, aria-current and onClick through. |
+| `menuLabel` | `string` | `'Menu'` | The menu button's name for screen readers, and the sheet's title. |
+| `menuFooter` | `ReactNode` |  | Shown in the menu sheet under the links. Use it for an action that doesn't fit in actions on a narrow bar. Hide the matching copy in actions below the breakpoint by wrapping it in an element with the classes hidden @2xl:flex. |
+| `className` | `string` |  | Added to the root classes. Where two Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLElement>` |  | The header element. |
+
+## Types and helpers
+
+Exported beside the component, from the same file. Import a type with `import type { ... }`.
+
+```ts
+export type NavbarItem = { label: string; href: string; current?: boolean }
+```
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Store navigation
+
+```tsx
+const ITEMS = [
+  { label: 'Replicas', href: '#replicas' },
+  { label: 'Optics', href: '#optics', current: true },
+  { label: 'Parts', href: '#parts' },
+  { label: 'Care', href: '#care' },
+  { label: 'Field notes', href: '#field-notes' },
+]
+
+const BRAND = (
+  <a
+    href="#home"
+    className="inline-flex items-center min-h-10 font-display font-bold uppercase tracking-[0.14em] text-[var(--color-text-primary)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-focus-ring)]"
+  >
+    Hexline
+  </a>
+)
+
+const ACTIONS = (
+  <>
+    <IconButton label="Search" variant="ghost">
+      <Search aria-hidden="true" className="w-5 h-5" />
+    </IconButton>
+    <IconButton label="Cart, 2 items" variant="ghost" asChild>
+      <a href="#cart">
+        <ShoppingBag aria-hidden="true" className="w-5 h-5" />
+      </a>
+    </IconButton>
+  </>
+)
+
+<Navbar label="Store navigation" brand={BRAND} items={ITEMS} actions={ACTIONS} />
+```
+
+### A narrow container
+
+```tsx
+const ITEMS = [
+  { label: 'Replicas', href: '#replicas' },
+  { label: 'Optics', href: '#optics', current: true },
+  { label: 'Parts', href: '#parts' },
+  { label: 'Care', href: '#care' },
+  { label: 'Field notes', href: '#field-notes' },
+]
+
+const BRAND = (
+  <a
+    href="#home"
+    className="inline-flex items-center min-h-10 font-display font-bold uppercase tracking-[0.14em] text-[var(--color-text-primary)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-focus-ring)]"
+  >
+    Hexline
+  </a>
+)
+
+const ACTIONS = (
+  <>
+    <IconButton label="Search" variant="ghost">
+      <Search aria-hidden="true" className="w-5 h-5" />
+    </IconButton>
+    <IconButton label="Cart, 2 items" variant="ghost" asChild>
+      <a href="#cart">
+        <ShoppingBag aria-hidden="true" className="w-5 h-5" />
+      </a>
+    </IconButton>
+  </>
+)
+
+<div className="max-w-sm">
+  <Navbar label="Store navigation, narrow" brand={BRAND} items={ITEMS} actions={ACTIONS} />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the brand, each link and the actions, then the menu button when it shows. |
+| `Enter` | Follows a link, or opens the menu. |
+| `Esc` | Closes the menu and sends focus back to its button. |
+
+## Do
+
+- Mark exactly one item as current.
+- Keep actions to icon buttons with names, or one short button.
+- If a page has more than one navbar, give each its own label.
+
+## Don't
+
+- Don't put more than about six links in the bar. Group the rest under a page.
+- Don't hide an action inside the menu that the bar shows at wide widths only.
+- Don't mark a link as current with colour alone. The fill and aria-current both move with it.
+
+## Anatomy
+
+- **Header**: The page's banner landmark, a region screen readers can jump straight to, at the top level of the page.
+- **Brand**: The wordmark or logo, usually a link to the home page.
+- **Links**: A named navigation region. The current page gets the signal fill, plus aria-current, an ARIA attribute (Accessible Rich Internet Applications, the labels screen readers rely on) that tells screen readers this is the page you are on.
+- **Actions**: They stay visible at every width.
+- **Menu**: When the container is narrower than 42rem (rem is a unit based on the root text size, usually 16 pixels), an icon button opens the same links in a Sheet. If the container widens past that breakpoint while the sheet is open, the sheet stays open. It doesn't close itself when the links reappear in the bar.

package/public/docs/components/newsletter-form.md

@@ -0,0 +1,112 @@
+# NewsletterForm
+
+> An email field, a line saying what you're agreeing to, and a button. It checks input the same way every form here does, is honest about waiting while it sends, and tells you when it worked.
+
+- **Best for:** Collecting one email address for a newsletter, with a consent line.
+- **Not for:** Creating an account: use AuthForm.
+- Organism. Source: `src/components/organisms/newsletter-form/NewsletterForm.tsx`
+- Rendered docs page: `/components/newsletter-form`
+
+## Import
+
+```tsx
+import { NewsletterForm } from 'src/components/organisms/newsletter-form/NewsletterForm'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` |  | Required. The form's accessible name, the name screen readers say, e.g. "Newsletter sign-up". Leaving it out is a compile error. |
+| `onSubmit` | `(email: string) => void \| Promise<void>` |  | Required. Called with the trimmed address once it passes validation. Resolve (finish successfully) to show the success state. Reject (fail) to show the alert, and what was typed stays in the field. |
+| `consent` | `ReactNode` |  | Required. The consent line. Leaving it out is a compile error. |
+| `fieldLabel` | `string` | `'Email'` | The field's label and the name screen readers say for it, as one string. Say what the address is for when the page might have another email field, such as a footer under a sign-in form. |
+| `submitLabel` | `string` | `'Subscribe'` | The button text. |
+| `busyLabel` | `string` | `'Subscribing'` | What a screen reader hears while onSubmit is pending. |
+| `successTitle` | `string` | `'You are subscribed'` | The success heading. |
+| `successBody` | `(email: string) => ReactNode` | `email => `Updates go to ${email}.`` | The line under the success heading. It receives the subscribed address. |
+| `headingLevel` | `2 \| 3 \| 4` | `3` | The level of the error summary heading and the success heading. Make it one below the heading of the section the form sits in. |
+| `className` | `string` |  | Added to the root element. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed to the root element, which stays on the page when the success message replaces the form. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A sign-up that succeeds
+
+```tsx
+const wait = (ms: number) => new Promise(resolve => window.setTimeout(resolve, ms))
+
+const CONSENT = 'One email a month. Every one has an unsubscribe link.'
+
+async function accept() {
+  await wait(700)
+}
+
+<div className="flex w-full flex-col gap-3">
+  <p className="font-body text-sm text-[var(--color-text-secondary)]">
+    Demo: any address is accepted after a short wait. Nothing is sent.
+  </p>
+  <NewsletterForm label="Field notes by email" consent={CONSENT} onSubmit={accept} headingLevel={4} />
+</div>
+```
+
+### A sign-up that fails
+
+```tsx
+const wait = (ms: number) => new Promise(resolve => window.setTimeout(resolve, ms))
+
+async function refuse() {
+  await wait(700)
+  throw new Error('The demo server is switched off.')
+}
+
+<div className="flex w-full flex-col gap-3">
+  <p className="font-body text-sm text-[var(--color-text-secondary)]">
+    Demo: this one rejects every address, so you can see the alert, and the address you typed stays in the field.
+  </p>
+  <NewsletterForm
+    label="Restock alerts by email"
+    consent="An email when a sold-out replica is back. Nothing else."
+    submitLabel="Notify me"
+    busyLabel="Signing you up"
+    onSubmit={refuse}
+    headingLevel={4}
+  />
+</div>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the field, then the button. Screen readers read the consent line with the button. |
+| `Enter` | In the field or on the button, it submits, and it does nothing while a submit is pending. On the error summary entry, it moves focus to the field. |
+
+## Do
+
+- Say in the consent line how often you write and how to stop.
+- Start the section it sits in with a heading that says what the emails are about.
+- Reject onSubmit when the request fails. The form shows the alert and keeps the address.
+- Set headingLevel to one below the section heading above it.
+
+## Don't
+
+- Don't pre-tick anything, or sign people up as a side effect of another form.
+- Don't put network code in it. onSubmit belongs to you; the form handles busy, failure and success.
+- Don't place it on a raised panel and remove its fill. Field errors sit on surface.base.
+- Don't ask for a name. Having just one field is the point.
+
+## Anatomy
+
+- **Form**: Screen readers name it by the label prop. It sits on opaque surface.base, in a hairline frame with the corner crosshair.
+- **Error summary**: Appears when a submit fails and takes focus. Its entry moves focus to the field. It waits for someone to try submitting: leaving the field (a blur) never brings it up on its own.
+- **Email**: A FormField wrapped around an Input, set to type email, autocomplete email and required.
+- **Consent**: Required. What subscribing means and how to stop. Screen readers read it as the submit button's description.
+- **Submit**: A Button that keeps focus and shows it's busy while onSubmit is pending. aria-busy and aria-disabled, two ARIA attributes (Accessible Rich Internet Applications, the labels screen readers rely on), tell screen readers the same.
+- **Submit error**: An alert region that is always there and gets its text when onSubmit fails. The visible message only appears then. It clears before the next try.
+- **Success**: Takes the place of the form: a check icon, a heading that takes focus, and the address that was subscribed.
+- **Status**: Hidden from view and present from the start. It announces the success only if focus had already left the form.

package/public/docs/components/page-header.md

@@ -0,0 +1,151 @@
+# PageHeader
+
+> The top of a screen. It holds the page’s one h1 (the main, level-1 heading), and can add an eyebrow, a description, a breadcrumb trail and the page’s own actions at the far edge.
+
+- **Best for:** The top of every screen: its one h1, with eyebrow, description, breadcrumbs and page actions.
+- **Not for:** A section inside a page: use SectionHeading.
+- Molecule. Source: `src/components/molecules/page-header/PageHeader.tsx`
+- Rendered docs page: `/components/page-header`
+
+## Import
+
+```tsx
+import { PageHeader } from 'src/components/molecules/page-header/PageHeader'
+```
+
+Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` |  | Required. The page’s name, shown as its h1. |
+| `eyebrow` | `ReactNode` |  | A short label above the title: the area the page belongs to. |
+| `description` | `ReactNode` |  | One or two sentences under the title. |
+| `actions` | `ReactNode` |  | The page’s own actions, usually one or two Buttons. The component lays out the row and its gap. |
+| `breadcrumbs` | `ReactNode` |  | A Breadcrumbs element, drawn above the eyebrow. |
+| `id` | `string` |  | Goes on the h1, not the wrapper, so main can point aria-labelledby at it. That ARIA (Accessible Rich Internet Applications) attribute lets the main area take its name from the heading. |
+| `level` | `1 \| 2` | `1` | Use 2 only for a page-style header inside a page that already has its h1 (a pane, a tab panel). It looks the same either way. |
+| `className` | `string` |  | Extra CSS classes, merged onto the outer element. When two Tailwind classes clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the outer element. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Title and description
+
+```tsx
+<PageHeader level={2} title="Orders" description="Every order from the last 90 days, newest first." />
+```
+
+### With an eyebrow and actions
+
+```tsx
+<PageHeader
+  level={2}
+  eyebrow="Operations"
+  title="Inventory"
+  description="Stock across both depots, counted at close of day."
+  actions={
+    <>
+      <Button variant="secondary">Export</Button>
+      <Button>Add replica</Button>
+    </>
+  }
+/>
+```
+
+### Under a breadcrumb trail
+
+```tsx
+<PageHeader
+  level={2}
+  breadcrumbs={
+    <Breadcrumbs
+      items={[
+        { label: 'Account', href: '#account' },
+        { label: 'Settings', href: '#settings' },
+        { label: 'Notifications' },
+      ]}
+    />
+  }
+  title="Notifications"
+  description="What we send, and where."
+  actions={<Button variant="secondary">Reset to defaults</Button>}
+/>
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the breadcrumb links, then the actions. The header itself never takes keyboard focus. |
+
+## Do
+
+- Use one per screen, at the top, inside main.
+- Keep the eyebrow to the area’s name (“Operations”), and the title to the page’s.
+- Put the page’s primary action last in the actions row, so it lands at the far edge.
+- When the page has more than one landmark (a named region screen readers can jump to), give the h1 an id and use it to name main.
+
+## Don't
+
+- Don’t use it for a section inside a page. That’s a SectionHeading.
+- Don’t put the page’s filters or tabs in the actions slot. They belong to the content under it.
+- Don’t repeat the title in the eyebrow. The eyebrow names where the page sits, and the title names the page.
+- Don’t add a second h1 inside the description or the actions.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<PageHeader level={2} title="Orders" />
+```
+
+Right:
+
+```tsx
+<PageHeader title="Orders" />
+```
+
+The examples on this page pass level={2} only because they sit inside this docs page, which has its own h1. A screen’s own header is its h1, so leave level out.
+
+Wrong:
+
+```tsx
+<PageHeader title="Inventory" />
+<PageHeader title="Low stock" />
+```
+
+Right:
+
+```tsx
+<PageHeader title="Inventory" />
+<SectionHeading level={2} title="Low stock" />
+```
+
+A page has one h1. Every heading under it is a SectionHeading, at the level the page’s outline of headings needs.
+
+Wrong:
+
+```tsx
+<PageHeader title="Inventory" breadcrumbs={[{ label: "Operations" }]} />
+```
+
+Right:
+
+```tsx
+<PageHeader title="Inventory" breadcrumbs={<Breadcrumbs items={[{ label: "Operations", href: "/ops" }, { label: "Inventory" }]} />} />
+```
+
+breadcrumbs is a slot, not an array. Pass a Breadcrumbs element, which keeps its own renderLink and maxItems.
+
+## Anatomy
+
+- **Breadcrumbs**: Optional. A Breadcrumbs trail above everything else, first in reading order.
+- **Eyebrow**: Optional. A small label: JetBrains Mono, 12px (pixels), semibold, uppercase, in text.muted. It's a paragraph above the h1 and isn't part of the heading's name.
+- **Title**: The page’s h1. Oxanium, semibold, 24px, growing to 30px when the header gets 48rem or more of width (a rem is the base text size, usually 16px).
+- **Description**: Optional. 16px body text in text.secondary, with lines no longer than 64 characters.
+- **Actions**: Optional. The page’s own controls at the far edge, in a row with a 12px gap. The row drops under the title when it runs out of room.