division-ds 0.1.2 → 0.2.0

package/public/docs/components/dialog.md

@@ -0,0 +1,195 @@
+# Dialog
+
+> A panel for one focused task, shown on top of the page. The page dims and goes inert, meaning it can't be clicked or focused. Keyboard focus moves inside the dialog and stays there. Escape or the close button hands focus back to whatever opened the dialog.
+
+- **Best for:** A focused task on top of the page, such as an edit form.
+- **Not for:** A destructive confirm: use AlertDialog. A message that doesn't need a decision: use Toast.
+- Organism. Source: `src/components/organisms/dialog/Dialog.tsx`
+- Rendered docs page: `/components/dialog`
+
+## Import
+
+```tsx
+import { Dialog, DialogClose, DialogContent, DialogFooter, DialogTrigger } from 'src/components/organisms/dialog/Dialog'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open (Dialog)` | `boolean` |  | Whether it is open, when your code controls that (controlled mode). |
+| `defaultOpen (Dialog)` | `boolean` | `false` | Whether it starts open, when the component tracks its own state (uncontrolled mode). |
+| `onOpenChange (Dialog)` | `(open: boolean) => void` |  | Called on every open and close, including Escape and a click on the scrim. |
+| `asChild (Trigger)` | `boolean` |  | Uses its single child as the trigger instead of adding its own button. Pass a Button. |
+| `title (Content)` | `string` |  | Required. The visible heading, and the name screen readers say. |
+| `description (Content)` | `string` |  | Shown under the title. Screen readers read it as the accessible description. |
+| `size (Content)` | `'sm' \| 'md' \| 'lg'` | `'md'` | Maximum width: 24rem, 32rem or 42rem (rem is a unit based on the root text size, usually 16 pixels). |
+| `closeLabel (Content)` | `string` | `'Close'` | What screen readers call the close button. |
+| `className (Content)` | `string` |  | Added to the root classes. Where two Tailwind utility classes clash, the later one wins. |
+| `ref (Content)` | `Ref<HTMLDivElement>` |  | The element with the role dialog. |
+| `ref (Trigger)` | `Ref<HTMLButtonElement>` |  | The trigger button. |
+| `asChild (Close)` | `boolean` |  | Uses its single child as a control that closes the dialog. |
+| `className (Footer)` | `string` |  | Added to the root classes. Where two Tailwind utility classes clash, the later one wins. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A form in a dialog
+
+```tsx
+function FormInDialogExample() {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button>Edit depot</Button>
+      </DialogTrigger>
+      <DialogContent title="Edit depot" description="Changes apply to every open manifest.">
+        <div className="flex flex-col gap-4">
+          <FormField label="Depot name">
+            <Input defaultValue="Brasov north" />
+          </FormField>
+          <FormField label="Notes">
+            <Textarea placeholder="Anything the driver should know." />
+          </FormField>
+        </div>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="secondary">Cancel</Button>
+          </DialogClose>
+          <DialogClose asChild>
+            <Button>Save</Button>
+          </DialogClose>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+<FormInDialogExample />
+```
+
+### Confirm a destructive action, opened without a trigger
+
+```tsx
+function ArchiveExample() {
+  const [open, setOpen] = useState(false)
+  const [status, setStatus] = useState('')
+
+  return (
+    <div className="flex flex-col items-start gap-3">
+      <Button
+        variant="danger"
+        onClick={() => {
+          setStatus('')
+          setOpen(true)
+        }}
+      >
+        Archive manifest
+      </Button>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent title="Archive manifest?" size="sm">
+          {/* token-discipline: allow, a manifest number in copy, not a colour */}
+          <p>Manifest #482 moves to the archive. It stays recoverable there for 30 days.</p>
+          <DialogFooter>
+            <DialogClose asChild>
+              <Button variant="secondary">Keep it</Button>
+            </DialogClose>
+            <Button
+              variant="danger"
+              onClick={() => {
+                setStatus('Manifest archived.')
+                setOpen(false)
+              }}
+            >
+              Archive
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <p role="status" className={docsProse}>
+        {status}
+      </p>
+    </div>
+  )
+}
+
+<ArchiveExample />
+```
+
+### Long content
+
+```tsx
+function LongContentExample() {
+  const contentRef = useRef<HTMLDivElement>(null)
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="secondary">Read shipping terms</Button>
+      </DialogTrigger>
+      <DialogContent
+        ref={contentRef}
+        title="Shipping terms"
+        size="lg"
+        tabIndex={-1}
+        onOpenAutoFocus={event => {
+          event.preventDefault()
+          contentRef.current?.focus()
+        }}
+      >
+        <div className="flex flex-col gap-4">
+          <p>Orders placed before 14:00 local time ship the same day; anything after ships the next business day.</p>
+          <p>Every parcel leaves in double-walled board with corner protection; ask for crate packaging on anything over 30kg.</p>
+          <p>Photograph the box before opening and report damage within 48 hours; we replace or refund, never both.</p>
+          <p>Unopened stock returns within 30 days for a full refund; opened stock returns for store credit only.</p>
+          <p>Depots outside the primary freight lanes add one to three business days and a remote-area surcharge.</p>
+          <p>A single parcel tops out at 40kg; heavier loads split automatically at checkout.</p>
+          <p>Cross-border shipments carry the recipient's own duties and taxes, billed separately by the carrier.</p>
+          <p>Reach the shipping desk at shipping@example.com for anything this page does not answer.</p>
+        </div>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button>Done</Button>
+          </DialogClose>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+<LongContentExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves to the next control inside the dialog, looping from the last back to the first. |
+| `Shift` `Tab` | Moves back, looping from the first to the last. |
+| `Esc` | Closes it and sends focus back to whatever opened it. |
+
+## Do
+
+- Put the actions in DialogFooter. It lays them out in a row, aligned right, with the gap between buttons already set.
+- Write the body as plain elements inside DialogContent. It adds the padding and sets the body text (14px, meaning 14 pixels, in text.primary), so a bare paragraph already looks right.
+- Write the title as the task: 'Edit depot', not 'Edit'.
+- Put the safe action first in the footer.
+- Open it from a button, a trigger or a shortcut. Focus goes back to that control when it closes.
+- For long content with no field at the top, focus the panel itself when it opens (onOpenAutoFocus, tabIndex={-1}), not whatever button happens to come first.
+
+## Don't
+
+- Don't open a dialog from a dialog. Finish or replace the first one.
+- Don't open one from a dropdown menu item. The item is gone by the time the dialog closes, so focus has nowhere to go back to.
+- Don't use one for a message that doesn't need a decision. That's a toast.
+- Don't check an untouched field on blur (when focus leaves it) in a dialog's form, and don't show ErrorSummary before a submit. The first field has focus when the dialog opens, so pressing Cancel blurs it first. An error appearing at that moment pushes the footer down mid-click, and Cancel never closes the dialog.
+
+## Anatomy
+
+- **Scrim**: The dimmed layer over the page, coloured surface.scrim. The page under it is hidden from screen readers and can't take focus. Clicking the scrim closes the dialog.
+- **Surface**: surface.base, a strong hairline border and the corner crosshair. It's opaque, so every colour on it is measured against the page. Its motion is M7: it settles in with M1, and when it closes it shrinks slightly as it fades while the scrim fades behind it.
+- **Title**: Required. An h2 (a second-level heading), and the dialog's accessible name, the name screen readers say for it.
+- **Description**: Optional. The accessible description, which screen readers read after the name.
+- **Body**: Anything: fields, text, a list.
+- **Footer**: The actions, with the safe one first.
+- **Close**: A ghost icon button (no fill, just the icon) in the top right. It comes last when you move through with Tab.

package/public/docs/components/divider.md

@@ -0,0 +1,95 @@
+# Divider
+
+> A thin line, with an optional legend (a short text label). When it's only decoration, screen readers skip it. When it marks where a section starts, it's a real separator they announce.
+
+- **Best for:** A thin line between groups of content, labelled when it starts a new section.
+- **Not for:** Making space (use the spacing scale), or going between items that already have their own borders.
+- Atom. Source: `src/components/atoms/divider/Divider.tsx`
+- Rendered docs page: `/components/divider`
+
+## Import
+
+```tsx
+import { Divider } from 'src/components/atoms/divider/Divider'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Which way the line runs. |
+| `label` | `string` |  | Adds a legend and makes the divider more than decoration. |
+| `className` | `string` |  | Merged with the component's classes. When Tailwind utility classes clash, the later one wins. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the root element. |
+| `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'role' \| 'children'>` |  | Every native div prop except role and children. role is removed from the types rather than quietly overwritten when the page runs, because label already decides whether the divider is decorative or structural. children is removed because it behaved two different ways: with no label it rendered inside a decorative separator, and with one it disappeared. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Plain rule
+
+```tsx
+<div className="w-full max-w-sm">
+  <Divider />
+</div>
+```
+
+### With a legend
+
+```tsx
+<div className="w-full max-w-sm">
+  <Divider label="Section 02" />
+</div>
+```
+
+### Vertical, between inline items
+
+```tsx
+<span className="flex items-center gap-3 h-6">
+  <span className="text-sm">Kit list</span>
+  <Divider orientation="vertical" />
+  <span className="text-sm">Load-out</span>
+</span>
+```
+
+### Drawing on
+
+```tsx
+<div className="flex flex-col gap-4 w-full max-w-sm">
+  {/* The Button atom, not a bare <button>: a hand-rolled one here had no system focus
+      ring at all (the UA default, rgb(16, 16, 16) auto 1px) and no type, so it defaulted
+      to submit. */}
+  <Button variant="secondary" size="sm" wrapperClassName="w-fit" onClick={() => setReplayKey(k => k + 1)}>
+    Replay
+  </Button>
+  <Divider key={replayKey} className="anim-draw-on" />
+  <p className="text-xs text-[var(--color-text-muted)]">
+    This animation is switched off completely when someone has asked their device for
+    less motion (the prefers-reduced-motion: reduce setting).
+  </p>
+</div>
+```
+
+## Keyboard
+
+Not focusable. No keyboard behaviour of its own.
+
+## Do
+
+- Leave it decorative when it's only there for visual rhythm.
+- Label it when it really starts a new section, so screen readers announce the structure.
+- Add anim-draw-on when a section animates in. The line drawing itself is motion token M2.
+
+## Don't
+
+- Don't stack dividers to make space. That's what the spacing scale is for.
+- Don't label every divider. If everything is a landmark, nothing is.
+- Don't use a vertical divider between items that already have their own borders.
+- Don't pass role. It's removed from the types so nothing can override it, and label already decides none vs separator.
+
+## Anatomy
+
+- **Rule**: 1px (one pixel) in border.hairline.
+- **Legend**: JetBrains Mono, 10px, muted. Optional.
+- **role**: none when decorative, separator when labelled. role tells screen readers what an element is.

package/public/docs/components/dropdown-menu.md

@@ -0,0 +1,220 @@
+# DropdownMenu
+
+> A short list of actions behind a button. It uses the same background as Select, so the system's two pop-ups look like one family. The highlighted item gets a fill, as it does everywhere else.
+
+- **Best for:** A short list of actions, under about eight, behind a button.
+- **Not for:** Picking a value for a form: use Select.
+- Molecule. Source: `src/components/molecules/dropdown-menu/DropdownMenu.tsx`
+- Rendered docs page: `/components/dropdown-menu`
+
+## Import
+
+```tsx
+import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from 'src/components/molecules/dropdown-menu/DropdownMenu'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open (Root)` | `boolean` |  | Whether the menu is open, when the page keeps track of it (controlled). |
+| `defaultOpen (Root)` | `boolean` |  | Whether it starts open, when the menu keeps track itself (uncontrolled). |
+| `onOpenChange (Root)` | `(open: boolean) => void` |  | Called when the menu opens or closes. |
+| `modal (Root)` | `boolean` | `true` | While open, keyboard focus stays inside the menu and the page behind can't scroll. |
+| `align (Content)` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment against the trigger. |
+| `side (Content)` | `'top' \| 'right' \| 'bottom' \| 'left'` |  | Preferred side of the trigger. |
+| `sideOffset (Content)` | `number` | `4` | Gap between trigger and content, in pixels. |
+| `onSelect (Item)` | `(event: Event) => void` |  | Called when the item is chosen. |
+| `disabled (Item)` | `boolean` | `false` | The item can't be chosen, and typing letters (typeahead) skips it. |
+| `tone (Item)` | `'default' \| 'hostile'` | `'default'` | Use hostile for a destructive action: hostile-coloured text at rest, the hostile fill with ink text when highlighted. |
+| `icon (Item)` | `ReactNode` |  | A small icon before the text, hidden from screen readers (aria-hidden). |
+| `shortcut (Item)` | `string` |  | Shown on the right and passed to screen readers as aria-keyshortcuts. It only displays the key: the menu never makes the key work. |
+| `checked (Checkbox item)` | `boolean` |  | Whether the tick shows. |
+| `onCheckedChange (Checkbox item)` | `(checked: boolean) => void` |  | Called when the checkbox item is toggled. |
+| `value (RadioGroup)` | `string` |  | The checked radio item. |
+| `onValueChange (RadioGroup)` | `(value: string) => void` |  | Called with the chosen radio item value. |
+| `value (RadioItem)` | `string` |  | This radio item's own value. |
+| `icon (SubTrigger)` | `ReactNode` |  | A small icon before the text, hidden from screen readers, as on Item. |
+| `open / defaultOpen / onOpenChange (Sub)` | `boolean / boolean / (open: boolean) => void` |  | Whether the submenu is open, tracked by the page (controlled) or by the submenu (uncontrolled). You'll usually leave these alone. |
+| `alignOffset (SubContent)` | `number` | `-5` | Shifts the submenu so its first row lines up with its trigger. |
+| `className` | `string` |  | Extra CSS classes, merged with the part's own. When two Tailwind classes clash, the later one wins. Every part takes it. |
+| `ref` | `Ref<HTMLDivElement>` |  | Passed through to the rendered element (the DOM node). On Content, Item, Checkbox item, Radio item, Sub trigger and Sub content. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### Actions
+
+```tsx
+function ActionsExample() {
+  const [lastAction, setLastAction] = useState('No action yet.')
+  const [pinned, setPinned] = useState(false)
+
+  return (
+    <div className="flex flex-col items-start gap-3">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button variant="secondary">Manifest actions</Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent>
+          <DropdownMenuLabel>Manifest</DropdownMenuLabel>
+          <DropdownMenuItem shortcut="D" onSelect={() => setLastAction('Duplicated.')}>
+            Duplicate
+          </DropdownMenuItem>
+          <DropdownMenuCheckboxItem
+            checked={pinned}
+            onCheckedChange={checked => {
+              setPinned(checked)
+              setLastAction(checked ? 'Pinned to top.' : 'Unpinned.')
+            }}
+          >
+            Pin to top
+          </DropdownMenuCheckboxItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem tone="hostile" onSelect={() => setLastAction('Archived.')}>
+            Archive
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <p className={docsProse}>{lastAction}</p>
+    </div>
+  )
+}
+
+<ActionsExample />
+```
+
+### With icons and shortcuts
+
+```tsx
+function IconsAndShortcutsExample() {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="secondary">Depot manifest</Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent>
+        <DropdownMenuItem icon={<Copy />} shortcut="⌘C">
+          Copy
+        </DropdownMenuItem>
+        <DropdownMenuItem icon={<CopyPlus />} shortcut="⌘D">
+          Duplicate
+        </DropdownMenuItem>
+        <DropdownMenuItem icon={<Download />} shortcut="⌘E">
+          Export
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+<IconsAndShortcutsExample />
+```
+
+### Radio items and a submenu
+
+```tsx
+function RadioAndSubmenuExample() {
+  const [sort, setSort] = useState('newest')
+  const [moved, setMoved] = useState('Not moved.')
+
+  return (
+    <div className="flex flex-col items-start gap-3">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button variant="secondary">Replica options</Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent>
+          <DropdownMenuLabel>Sort by</DropdownMenuLabel>
+          <DropdownMenuRadioGroup value={sort} onValueChange={setSort}>
+            <DropdownMenuRadioItem value="newest">Newest</DropdownMenuRadioItem>
+            <DropdownMenuRadioItem value="price">Price</DropdownMenuRadioItem>
+            <DropdownMenuRadioItem value="weight">Weight</DropdownMenuRadioItem>
+          </DropdownMenuRadioGroup>
+          <DropdownMenuSeparator />
+          <DropdownMenuSub>
+            <DropdownMenuSubTrigger icon={<FolderInput />}>Move to</DropdownMenuSubTrigger>
+            <DropdownMenuSubContent>
+              <DropdownMenuItem onSelect={() => setMoved('Moved to the armoury.')}>Armoury</DropdownMenuItem>
+              <DropdownMenuItem onSelect={() => setMoved('Moved to the workshop.')}>Workshop</DropdownMenuItem>
+              <DropdownMenuItem onSelect={() => setMoved('Moved to the depot.')}>Depot</DropdownMenuItem>
+            </DropdownMenuSubContent>
+          </DropdownMenuSub>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <p className={docsProse}>
+        Sorted by {sort}. {moved}
+      </p>
+    </div>
+  )
+}
+
+<RadioAndSubmenuExample />
+```
+
+### From an icon button
+
+```tsx
+function IconButtonTriggerExample() {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <IconButton label="Depot actions" variant="secondary">
+          <MoreHorizontal aria-hidden="true" />
+        </IconButton>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end">
+        <DropdownMenuItem>View manifest</DropdownMenuItem>
+        <DropdownMenuItem>Reassign</DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem tone="hostile">Decommission</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+<IconButtonTriggerExample />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Enter` `Space` `ArrowDown` | On the trigger: opens, highlighting the first item. |
+| `ArrowUp` `ArrowDown` | Moves the highlight. |
+| `Home` `End` | Jumps to the first or last item. |
+| `Enter` `Space` | Runs the highlighted item. |
+| `Escape` | Closes the menu and puts focus back on the trigger. |
+| `ArrowRight` | On a sub trigger: opens the submenu, highlighting its first item. |
+| `ArrowLeft` | In a submenu: closes it, and you're back on its trigger. |
+| `A–Z` | Typeahead: jumps to the next item that starts with the letters you type. |
+
+## Do
+
+- Keep menus under about eight items.
+- Put the destructive item last, after a separator, with the hostile tone.
+- Name an icon-only trigger for what the menu holds: 'Manifest actions', not 'More'.
+- Use a radio group for a setting the menu shows the current value of: sort order, density.
+- Name a sub trigger for what it holds: 'Move to', 'Export as'.
+
+## Don't
+
+- Don't use a menu to pick a value for a form. That's what Select is for.
+- Don't put a submenu inside a submenu. One level at most.
+- Don't use radio items to run actions. A radio item sets a value, and the menu keeps showing it.
+- Don't make every item hostile to add weight. Hostile means it destroys something.
+
+## Anatomy
+
+- **Trigger**: A Button or IconButton, passed in through asChild. Radix (the library underneath) adds aria-haspopup and aria-expanded. These are ARIA (Accessible Rich Internet Applications) attributes that tell screen readers the button opens a menu and whether it's open.
+- **Content**: Rendered in a portal, at the end of the page, so nothing clips it. Sunken surface, a strong thin border, crosshair corners. M7: it slides down out of the trigger to open and back up into it to close (the other way round when it opens above).
+- **Item**: 36px (pixels) tall. When highlighted: the signal fill with ink-coloured text.
+- **Hostile item**: For a destructive action. Hostile-coloured text at rest, and the hostile fill with ink text when highlighted.
+- **Checkbox item**: Shows a tick when on. Screen readers get it as a menuitemcheckbox with aria-checked.
+- **Label**: Uses text.secondary, so it reads as a heading over the items. It doesn't use text.label: on this background (surface.sunken) that token fails SC 1.4.3, the contrast rule in WCAG (the Web Content Accessibility Guidelines).
+- **Separator**: A thin line.
+- **Radio item**: One choice in a RadioGroup. Screen readers get it as a menuitemradio with aria-checked. Its mark is a small filled square, never a dot.
+- **Sub trigger**: An item with a chevron that opens a submenu. While the highlight is inside the submenu, the sub trigger keeps a 1px strong line just inside its edge.
+- **Sub content**: The submenu: the same surface and M7 slide as Content, aligned so its first row sits level with its trigger.
+- **Shortcut**: Text on the right that screen readers skip (aria-hidden), plus aria-keyshortcuts on the item so they announce it once. It only displays the key: the page has to make the key work.

package/public/docs/components/empty-state.md

@@ -0,0 +1,143 @@
+# EmptyState
+
+> What a list, a table or a page region shows when it has nothing in it: an icon, a title that names what is empty, a sentence on why, and the action that fills it.
+
+- **Best for:** A list, table or region with nothing in it, along with the action that fills it.
+- **Not for:** A list that's still loading: use Skeleton or Spinner. A failed load: use Alert in the hostile tone.
+- Molecule. Source: `src/components/molecules/empty-state/EmptyState.tsx`
+- Rendered docs page: `/components/empty-state`
+
+## Import
+
+```tsx
+import { EmptyState } from 'src/components/molecules/empty-state/EmptyState'
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` |  | Required. What is empty, said plainly: “No orders yet”. |
+| `level` | `2 \| 3 \| 4` |  | Required, with no default. The heading level the page's outline of headings needs at this point. |
+| `description` | `ReactNode` |  | One or two sentences: why it's empty, or what fills it. |
+| `icon` | `ReactNode` |  | A lucide icon element. The component sizes it and wraps it in a tile that screen readers skip (aria-hidden). |
+| `actions` | `ReactNode` |  | One or two Buttons. The component lays out the row and its gap. |
+| `size` | `'sm' \| 'md'` | `'md'` | md for a page region. sm inside a table, a card or a panel. |
+| `framed` | `boolean` | `true` | The dashed frame. Turn it off where the container already draws an edge. |
+| `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. |
+| `...rest` | `Omit<HTMLAttributes<HTMLDivElement>, 'title'>` |  | Any other div attribute, put on the outer element. role="status" goes here when nothing else on the page tells screen readers that the list has emptied. |
+
+## Examples
+
+Each is compiled and rendered on the docs page. Imports are omitted; see above.
+
+### A page region, after a filter
+
+```tsx
+<EmptyState
+  level={4}
+  icon={<PackageSearch />}
+  title="No replicas match"
+  description="Nothing in stock matches all three filters. Remove one, or clear them and start again."
+  actions={
+    <>
+      <Button>Clear filters</Button>
+      <Button variant="secondary">Browse all replicas</Button>
+    </>
+  }
+/>
+```
+
+### First use, one action
+
+```tsx
+<EmptyState
+  level={4}
+  icon={<Heart />}
+  title="Your wishlist is empty"
+  description="Save a replica from its page and it waits here, with its price and stock."
+  actions={<Button variant="secondary">Browse replicas</Button>}
+/>
+```
+
+### Small and unframed, inside a card
+
+```tsx
+<Card as="div" className="max-w-md">
+  <CardBody>
+    <EmptyState
+      level={4}
+      size="sm"
+      framed={false}
+      icon={<StickyNote />}
+      title="No notes on this order"
+      description="Notes added at the counter show up here."
+    />
+  </CardBody>
+</Card>
+```
+
+### Title only
+
+```tsx
+<EmptyState level={4} size="sm" title="No returns yet" />
+```
+
+## Keyboard
+
+| Keys | Result |
+|---|---|
+| `Tab` | Moves through the actions, if there are any. The empty state itself never takes keyboard focus. |
+
+## Do
+
+- Name what is empty in the title (“No orders yet”), not the state (“Empty”).
+- Say in the description what fills it, or why a filter emptied it.
+- Offer the action that fixes it: “Clear filters” after a filter, “Browse replicas” on an empty wishlist.
+- Use size="sm" and framed={false} inside a table, a card or a panel.
+
+## Don't
+
+- Don’t use it for a list that’s still loading. Nothing has been found yet, so show a spinner or a skeleton.
+- Don’t use it for an error. A failed load is an Alert in the hostile tone, with a retry.
+- Don’t put more than two actions in it. A third belongs on the page, not in the empty region.
+- Don’t add role="status" when a count on the page already announces the change. A screen reader user would hear it twice.
+
+## Common mistakes
+
+Wrong:
+
+```tsx
+<EmptyState title="No orders yet" />
+```
+
+Right:
+
+```tsx
+<EmptyState level={2} title="No orders yet" />
+```
+
+The level is required, because only the page knows what the empty region is: a whole page (an h2, a level-2 heading, under the h1), a section (h3) or a card (h4).
+
+Wrong:
+
+```tsx
+<Card><EmptyState level={3} title="No notes" /></Card>
+```
+
+Right:
+
+```tsx
+<Card><EmptyState level={3} size="sm" framed={false} title="No notes" /></Card>
+```
+
+The card already draws an edge, so a dashed frame inside it makes a second one. And the md (medium) padding is sized for a page region.
+
+## Anatomy
+
+- **Frame**: A dashed edge in border.hairline-strong. It's the one border in the system that reads as an empty slot instead of a surface. Optional, through framed.
+- **Icon tile**: Optional. A square on surface.sunken with a thin edge, holding a lucide icon in text.secondary. Screen readers skip it (aria-hidden), because the title already says what the icon would.
+- **Title**: A heading element, h2 to h4. Oxanium, semibold, 18px (pixels) at md size and 16px at sm (small), in text.primary.
+- **Description**: Optional. 14px body text in text.secondary, with lines no longer than 48 characters.
+- **Actions**: Optional. One or two Buttons, centred, in a row that wraps onto a new line with a 12px gap.