@sableui/react 0.0.0-stage → 0.1.1

package/llms/components/accordion.md

@@ -0,0 +1,93 @@
+# Accordion
+
+**Status:** stable
+
+Stacked, collapsible disclosure sections over Base UI Accordion — roving focus, arrow-key navigation, ARIA region/heading/button wiring, and an animated height transition. Each item pairs a full-width trigger (with a rotating chevron) and a panel.
+
+**Keywords:** accordion, disclosure, collapse, faq
+
+## Usage
+
+Use Accordion to reveal a vertical set of related sections while keeping the surrounding page scannable.
+
+### Best practices
+
+- Do: Use concise trigger text that describes the content revealed below it.
+- Do: Keep section content focused so expanding one item does not feel like navigating to a new page.
+- Don't: Do not hide required fields, primary actions, or critical errors inside collapsed sections.
+- Don't: Do not nest an Accordion inside an Accordion. Two layers of roving focus fight each other, and the arrow keys become ambiguous — flatten the hierarchy or use a Tree.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| AccordionItem | yes | One expandable section in the group. |
+| AccordionTrigger | yes | The button-like control that opens the section. |
+| AccordionPanel | yes | The content revealed by the trigger. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| AccordionItem | Base UI Accordion.Item props + className (value, disabled, onOpenChange) | Pairs a header with its panel. Give each a stable `value` to control or set initial open state. |
+| AccordionTrigger | Base UI Accordion.Trigger props + className + indicator?: ReactNode | The header button (Header + Trigger composed). Renders children plus a chevron that rotates via data-[panel-open] by default; pass `indicator` to replace the icon and its open-state behavior entirely (e.g. a plus that becomes an × for a FAQ-style toggle). |
+| AccordionPanel | Base UI Accordion.Panel props + className (keepMounted, hiddenUntilFound) | The collapsible body. Animates height using the --accordion-panel-height CSS var; fades on data-[starting-style]/data-[ending-style]. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Accordion (Root) | Base UI Accordion.Root props (value, defaultValue, multiple, disabled, onValueChange, orientation, loopFocus, keepMounted, hiddenUntilFound) | — | Groups all items and owns the open value(s). Uncontrolled via defaultValue, controlled via value. |
+| defaultValue | Value[] | [] | Uncontrolled set of item values that start expanded (e.g. ['faq-1']). |
+| value | Value[] | — | Controlled set of expanded item values; pair with onValueChange. |
+| onValueChange | (value: Value[]) => void | — | Called with the new set of expanded item values when an item opens or closes. |
+| multiple | boolean | false | Whether more than one item can be open at the same time. When false, opening one closes the others. |
+
+## Tokens used
+
+`border`, `foreground`, `muted-foreground`, `ring`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — An accordion is page furniture that is present from first paint. Animating it in would stage content the reader is already scanning past.
+- **response** · AccordionTrigger · `motion-interactive` — The whole header row is the hit target, and it looks like a heading rather than a control. The hover shift is what tells the reader it can be clicked before they click it.
+- **transition** · AccordionPanel · `motion-disclosure` — Panel height is the only cue that content came from THIS header rather than appearing at the bottom of the page. Snapping it open moves everything below by a screenful with nothing connecting cause to effect.
+- **activity** · Root · _no motion_ — Nothing here is indeterminate — the panel content is already resident. A panel that loads on expand should put its own loader inside the panel.
+
+## Accessibility
+
+- Base UI renders the trigger inside an <h3> heading and wires aria-expanded / aria-controls to the panel region.
+- Arrow keys move roving focus between triggers; Home/End jump to the first/last; loopFocus wraps by default.
+- Each trigger toggles its panel with Enter/Space; the panel is announced as a labelled region.
+- A disabled AccordionItem dims and is skipped by keyboard focus while neighbouring items stay interactive.
+- The chevron rotation is driven by data-[panel-open] and the focus ring by focus-visible — both honor reduced-motion via the consumer's transitions.
+
+## Related
+
+- Components: Collapsible, Tabs
+
+## Examples
+
+### Single (default)
+
+```tsx
+import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger } from "@sableui/react"
+
+<Accordion defaultValue={["a"]}><AccordionItem value="a"><AccordionTrigger>Is it permanent?</AccordionTrigger><AccordionPanel>Yes — stored on Arweave.</AccordionPanel></AccordionItem><AccordionItem value="b"><AccordionTrigger>How much?</AccordionTrigger><AccordionPanel>A one-time mint fee.</AccordionPanel></AccordionItem></Accordion>
+```
+
+### Multiple open
+
+```tsx
+import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger } from "@sableui/react"
+
+<Accordion multiple defaultValue={["a", "b"]}><AccordionItem value="a"><AccordionTrigger>First</AccordionTrigger><AccordionPanel>One.</AccordionPanel></AccordionItem><AccordionItem value="b"><AccordionTrigger>Second</AccordionTrigger><AccordionPanel>Two.</AccordionPanel></AccordionItem></Accordion>
+```
+
+### Custom indicator (plus-becomes-×)
+
+```tsx
+import { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, Icon } from "@sableui/react"
+
+<Accordion defaultValue={["a"]}><AccordionItem value="a"><AccordionTrigger indicator={<Icon name="plus" className="text-xs text-muted-foreground transition-transform [[data-panel-open]_&]:rotate-45" />}>Is it permanent?</AccordionTrigger><AccordionPanel>Yes — stored on Arweave.</AccordionPanel></AccordionItem></Accordion>
+```

package/llms/components/app-header.md

@@ -0,0 +1,70 @@
+# AppHeader
+
+**Status:** stable
+
+Mobile top bar (sticky, hidden at lg) with leading / title / actions slots on a 3-column grid that keeps the title optically centered. Grows into the top safe-area.
+
+**Keywords:** app header, top bar, mobile header, chrome
+
+## Usage
+
+Use AppHeader for compact application chrome at the top of a screen, usually with navigation, identity, and a small action set. Pass it to AppShell's `header` slot so screen content clears it on mobile (it is sticky and hides itself at lg).
+
+### Best practices
+
+- Do: Keep the header actions narrow and predictable so the page title remains legible.
+- Do: Use it once per app view as chrome, not as repeated content inside page sections.
+- Don't: Do not overload it with filters, forms, or page-specific controls that belong in the content area.
+- Don't: Do not render more than one per app, or put a second one inside a route. It is sticky chrome, so two of them stack and permanently eat the top of the viewport.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| leading | ReactNode | — | Leading slot — back button, create action, or menu trigger. |
+| title | ReactNode | — | Center slot — brand wordmark or contextual page title. |
+| actions | ReactNode | — | Trailing slot — wallet trigger, action buttons. |
+
+## Tokens used
+
+`background`, `border`, `foreground`
+
+## Accessibility
+
+- Renders a <header> landmark.
+- Pair with a leading control that has an accessible label (e.g. a BackButton).
+
+## Related
+
+- Components: AppShell, PageHeader, BottomNav
+
+## Examples
+
+### Contextual header
+
+```tsx
+import { AppHeader, Button, Icon } from "@sableui/react"
+
+<AppHeader leading={<Button size="icon" variant="ghost" aria-label="Back"><Icon name="chevron-left" /></Button>} title="Notifications" />
+```
+
+### Choosing between AppHeader and PageHeader
+
+```tsx
+import { AppHeader, AppShell, PageHeader, Region } from "@sableui/react"
+
+// AppHeader is APP chrome — it persists across routes and holds global
+// affordances (brand, search, account). One per app.
+<AppShell header={<AppHeader title="Studio" />}>
+  <Region max="content">Route content</Region>
+</AppShell>
+
+// PageHeader is CONTENT — it introduces the current route and scrolls away
+// with it. One per page, INSIDE the region.
+<Region max="content">
+  <PageHeader title="Billing" description="Plans, invoices, payment methods." />
+</Region>
+
+// ✗ Putting route-specific actions in AppHeader. They then persist onto routes
+//   where they mean nothing, and the header becomes a dumping ground.
+```

package/llms/components/app-shell.md

@@ -0,0 +1,117 @@
+# AppShell
+
+**Status:** stable
+
+The application frame: slots for status banners, a mobile header, a desktop sidebar, main content, a mobile bottom nav, and floating overlays — plus a built-in skip link and #main-content target.
+
+**Keywords:** app shell, layout, frame, sidebar, header, bottom nav, mobile, banners, main
+
+## Usage
+
+Use AppShell as the outer product frame for authenticated or app-like experiences. It coordinates responsive chrome slots and guarantees a skip link plus main landmark; put route content inside the children and let AppHeader, Sidebar, BottomNav, and Banner own their own semantics.
+
+### Best practices
+
+- Do: Use AppShell once around the route tree or major app area so the skip link and main landmark stay stable.
+- Do: Pass app-wide outage or status messages through banners so they remain above the frame.
+- Do: Use Region inside the main content to choose each route's reading width.
+- Do: Wrap EVERY return of a route in its own Page or Region — including early returns for loading, empty and error states. AppShell's <main> deliberately carries no padding (it is a frame, and padding belongs to the region that chose the width), so a route that returns a bare spinner or error renders flush against the chrome. This is the most common conversion bug: the happy path gets a Page, the three early returns do not.
+- Don't: Nest AppShell inside route cards or panels. It is page chrome, not local content.
+- Don't: Put desktop-only navigation in the mobile header slot or mobile-only controls in the sidebar slot.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Banners | no | Full-width app status messages rendered above the shell. |
+| Header | no | Mobile top chrome, usually AppHeader. |
+| Sidebar | no | Desktop navigation chrome, usually Sidebar. |
+| Main | yes | The route content landmark with id main-content. |
+| Bottom nav | no | Mobile fixed navigation with reserved bottom space. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| banners | ReactNode | — | Full-width status banners pinned in flow above the frame (offline / chain-down). |
+| header | ReactNode | — | Mobile top header (e.g. AppHeader); expected to hide itself at lg. |
+| sidebar | ReactNode | — | Desktop side navigation (e.g. Sidebar); expected to hide itself below lg. Leading column of the body row. |
+| bottomNav | ReactNode | — | Mobile bottom navigation (e.g. BottomNav); fixed to the bottom edge. main reserves space for it. |
+| overlays | ReactNode | — | Floating overlays — a message launcher, FAB, or modal mount points. |
+
+## Tokens used
+
+`background`, `foreground`, `primary`, `primary-foreground`
+
+## Accessibility
+
+- Renders a skip link to #main-content as the first focusable element.
+- Wraps content in a <main id="main-content"> landmark.
+- Slot components own their own ARIA (nav landmarks, labels).
+
+## Related
+
+- Components: AppHeader, Sidebar, SideNav, BottomNav, Banner
+- Patterns: DashboardPage, FeedPage, SettingsPage
+
+## Examples
+
+### Full frame
+
+```tsx
+import { AppHeader, AppShell, Banner, BottomNav, BottomNavItem, Icon, PageHeader, Region, Sidebar, SidebarItem, SidebarNav } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<AppShell
+  banners={<Banner tone="warning">Network congested — mints may be slow.</Banner>}
+  header={<AppHeader title="Studio" />}
+  sidebar={
+    <Sidebar>
+      <SidebarNav>
+        <SidebarItem icon={<Icon name="home" />} label="Home" active render={<Link to="/" />} />
+        <SidebarItem icon={<Icon name="bell" />} label="Notifications" render={<Link to="/notifications" />} />
+        <SidebarItem icon={<Icon name="gear" />} label="Settings" render={<Link to="/settings" />} />
+      </SidebarNav>
+    </Sidebar>
+  }
+  bottomNav={
+    <BottomNav>
+      <BottomNavItem icon={<Icon name="home" />} label="Home" active render={<Link to="/" />} />
+      <BottomNavItem icon={<Icon name="bell" />} label="Alerts" render={<Link to="/notifications" />} />
+    </BottomNav>
+  }
+>
+  <Region max="feed">
+    <PageHeader title="Home" description="Latest posts from artists you follow." />
+  </Region>
+</AppShell>
+```
+
+### Minimal (sidebar + content only)
+
+```tsx
+import { AppShell, Icon, PageHeader, Region, Sidebar, SidebarItem, SidebarNav } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<AppShell
+  sidebar={
+    <Sidebar>
+      <SidebarNav>
+        <SidebarItem icon={<Icon name="home" />} label="Dashboard" active render={<Link to="/" />} />
+      </SidebarNav>
+    </Sidebar>
+  }
+>
+  <Region max="wide">
+    <PageHeader title="Dashboard" />
+  </Region>
+</AppShell>
+```
+
+### Route content width
+
+```tsx
+import { AppShell, Card, CardContent, CardHeader, CardTitle, Field, Icon, Input, PageHeader, Region, Sidebar, SidebarItem, SidebarNav } from "@sableui/react"
+
+<AppShell sidebar={<Sidebar><SidebarNav><SidebarItem icon={<Icon name="home" />} label="Home" active /></SidebarNav></Sidebar>}><Region max="content"><PageHeader title="Settings" description="Manage account and workspace preferences." /><Card><CardHeader><CardTitle>Profile</CardTitle></CardHeader><CardContent><Field label="Display name"><Input defaultValue="Nova" /></Field></CardContent></Card></Region></AppShell>
+```

package/llms/components/attachment.md

@@ -0,0 +1,105 @@
+# Attachment
+
+**Status:** stable
+
+A file or image attached to a message: media or icon lead, name and metadata, upload and error states, an actions slot, and a full-card trigger that keeps those actions separately clickable.
+
+**Keywords:** attachment, file, upload, image preview, chat file, document, drag and drop, file card
+
+## Usage
+
+The card a file takes in a conversation — in the composer while it uploads, and in the transcript once it has. It renders all four states an attachment actually moves through (queued, uploading, failed, delivered) rather than only the delivered one, because the other three are the states that are hard to get right and would otherwise fall back on every caller.
+
+### Best practices
+
+- Do: Use `variant="media"` for images and `variant="card"` for documents. A filename tells you nothing about a photo, and a thumbnail tells you nothing about a contract.
+- Do: Pass `onOpen` rather than wrapping the card in your own button. It renders a stretched trigger underneath the actions, so the card is one tab stop, each action is its own, and clicking "remove" never opens the file.
+- Do: Give `status="uploading"` a numeric `progress` when you have one and omit it when you do not — the bar goes indeterminate rather than lying about 0%.
+- Do: Put the reason in `meta` when `status="error"`. The card re-colors but keeps its shape, so a failed upload stays recognisable as the file it was — the text is what says why.
+- Don't: Do not nest interactive controls inside a card you have wrapped in a link or button yourself. That is invalid HTML and unreachable in the order it looks like; `onOpen` exists to avoid it.
+- Don't: Do not use it as a generic file-list row. `Tree` is the file listing; this one is shaped for a conversation, where an attachment is a message payload.
+- Don't: Do not rely on the error colour alone to signal failure. Colour is not a status for anyone who cannot see it — say what happened in `meta`.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Media | yes | Thumbnail crop or file glyph. Fills the tile in `media`, a lead square in `card`. |
+| Label | yes | Name and metadata. A row beside the media in `card`; a scrim strip over the picture in `media`, shown only when there is something to say. |
+| Actions | no | Remove / retry / download controls, stacked above the stretched trigger so they stay separately clickable. |
+| Progress | no | A hairline bar along the bottom edge while `status="uploading"`; determinate with `progress`, indeterminate without. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| name | string | — | File name. Truncated rather than wrapped — the stem truncates and a short extension stays visible — and used as the default label for the stretched trigger and the media tile's alt text. |
+| meta | ReactNode | — | Size, type, upload progress, or the failure reason — the quiet second line. |
+| thumbnail | string | — | Image preview URL. Present means the card shows a crop of the file instead of a glyph. |
+| icon | string | "file" | Semantic icon name for a non-image file (resolved through IconProvider). Defaults to "image-stack" when a thumbnail is set. |
+| variant | "card" \| "media" | "card" | `card` is a name-led horizontal row for documents; `media` is a square tile that is mostly picture. |
+| status | "idle" \| "uploading" \| "error" | "idle" | Transfer state. `uploading` adds a progress bar; `error` re-colors the card without changing its shape. |
+| progress | number | — | Percentage 0–100 while uploading. Omit for an indeterminate bar. |
+| actions | ReactNode | — | Remove / retry / download controls. Stay clickable when `onOpen` makes the card a trigger. On a `media` tile they float on the top-end corner over the picture, so pass `variant="floating"` buttons there. |
+| onOpen | () => void | — | Makes the whole card activate, via a stretched button rendered beneath the actions rather than by wrapping the card. |
+| openLabel | string | `Open ${name}` | Accessible label for that stretched trigger. |
+| ...div props | Omit<ComponentPropsWithRef<"div">, "onClick"> | — | Spread onto the card. Use `onOpen` rather than `onClick` — a click handler on a div is not a control. |
+
+## Variants
+
+- **variant**: card, media
+- **status**: idle, uploading, error
+
+## Tokens used
+
+`card`, `border`, `border-strong`, `muted`, `muted-foreground`, `foreground`, `destructive`, `overlay`, `overlay-foreground`, `ring`
+
+## Accessibility
+
+- The full-card trigger is a real stretched `<button>` with an accessible label, not a click handler on a div — so it is one tab stop, keyboard-activatable, and focus-ringed.
+- Actions sit above that trigger in the stacking order, which keeps them individually focusable and stops a click on `remove` from also opening the file. Text is only made click-through when a trigger is present, so a filename stays selectable otherwise.
+- A thumbnail is described as the attachment in `media` (where the picture is the only label) and left decorative in `card` (where the filename is right beside it), so AT never reads the same name twice.
+- The upload bar carries an accessible name via Progress; the error state is carried by text in `meta` as well as colour.
+- Label text on a media tile sits on `overlay` / `overlay-foreground` — a fixed pairing that stays legible over arbitrary imagery, where a theme surface token would not.
+
+## Related
+
+- Components: Message, Bubble, MessageScroller, Progress
+
+## Examples
+
+### Document with a remove action
+
+```tsx
+import { Attachment, Button, Icon } from "@sableui/react"
+
+<Attachment name="proposal.pdf" meta="2.4 MB · PDF" onOpen={() => open(file)} actions={<Button variant="ghost" size="icon-xs" aria-label="Remove"><Icon name="xmark" /></Button>} />
+```
+
+### Image tile, uploading
+
+```tsx
+import { Attachment } from "@sableui/react"
+
+<Attachment variant="media" name="cover.png" thumbnail={previewUrl} status="uploading" progress={62} meta="Uploading… 62%" />
+```
+
+### Failed upload with a retry
+
+```tsx
+import { Attachment, Button } from "@sableui/react"
+
+<Attachment name="recording.mov" meta="Upload failed — file is over the 50 MB limit" status="error" icon="warning" actions={<Button variant="ghost" size="xs" onClick={retry}>Retry</Button>} />
+```
+
+### Attachments as a message payload
+
+```tsx
+import { Attachment, Message, RelativeTime } from "@sableui/react"
+
+<Message messageId="m7" align="end" footer={<RelativeTime date={sentAt} />}>
+	<div className="flex flex-wrap gap-2">
+		{files.map((f) => (<Attachment key={f.id} variant="media" name={f.name} thumbnail={f.url} onOpen={() => open(f)} />))}
+	</div>
+</Message>
+```

package/llms/components/avatar.md

@@ -0,0 +1,141 @@
+# Avatar
+
+**Status:** stable
+
+Circular profile image over Base UI Avatar — automatic image-load tracking with an initials/glyph fallback. Ergonomic Avatar plus low-level AvatarRoot/AvatarImage/AvatarFallback parts, and AvatarGroup for an overlapping stack with a "+N" overflow count.
+
+**Keywords:** avatar, profile, user, identity, initials, fallback, group, team, stack, overflow, collaborators, facepile
+
+## Usage
+
+Use Avatar to represent a person, team, or account with a compact visual identity. Wrap several in AvatarGroup for collaborators, assignees, or attendees — it overlaps them, rings each in the surface colour, and collapses the rest into a "+N" count; use the low-level parts only when you need custom image/fallback layout.
+
+### Best practices
+
+- Do: Provide meaningful alt text for profile images, or an empty alt when the adjacent text already names the person.
+- Do: Use initials or a simple glyph fallback so missing images still communicate identity.
+- Do: Use consistent sizes within a group; reserve lg for profile headers or major identity moments.
+- Do: Use AvatarGroup for a stack of people, and give it an aria-label with the real count ("12 collaborators"). Set `surface` (or `--avatar-group-ring`) to whatever the group sits on, so the separating ring matches a card or popover, not the page. When it shares a row with actions, set `fit` so it gives up avatars to the "+N" count before the row has to wrap.
+- Don't: Hand-build a stack with negative margins and per-avatar ring classes, or fake the overflow as an Avatar with "+4" initials — screen readers hear "plus 4" with no context. Use AvatarGroup's `max`/`total`, or AvatarGroupCount.
+- Don't: Use avatars as decoration without nearby identity context. They should help users recognize a person or account.
+- Don't: Overload a dense table with large avatars; use sm or omit images when scanning data is more important.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Root | yes | The circular frame that clips the image, owns size, and contains image plus fallback. |
+| Image | no | The loaded profile image, cropped to fill the root. |
+| Fallback | yes | Initials, a glyph, or short text shown while loading, on error, or when no image exists. |
+| Group | no | AvatarGroup: the overlapping stack. Sets one size for every avatar and rings each in the surface colour. |
+| Count | no | AvatarGroupCount: the "+N" avatar ending a group, read as "and N more". Rendered automatically by `max`/`total`. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| AvatarRoot | Base UI Avatar.Root props + size + className | Low-level circular frame for full composition control — clips the image and holds the `size` axis. Wraps AvatarImage and AvatarFallback. |
+| AvatarImage | Base UI Avatar.Image props + className | The profile image. Fills and crops the frame; hidden by Base UI until it loads. |
+| AvatarFallback | Base UI Avatar.Fallback props (delay) + className | Shown when no image is available — typically initials or a glyph. Accepts a delay prop. |
+| AvatarGroup | { size?: "sm" \| "md" \| "lg"; surface?: "background" \| "card" \| "popover" \| "muted"; max?: number; fit?: boolean; total?: number; countLabel?: (count: number) => string; "aria-label"?: string; className?: string; children: ReactNode } | Overlapping stack (role=group) — name it with aria-label ("12 collaborators"). `size` applies to every avatar inside. `max` shows that many and collapses the rest into a "+N" count; `total` is the real head-count when you only pass some people. `fit` shows only as many avatars as fit the width the group is given (it fills the space left in a flex row) and folds the rest into the count, so a tight row reads "MO SR +5" instead of wrapping. The separating ring reads the inherited `--avatar-group-ring` (default: the page background); `surface` sets it to card, popover, or muted. |
+| AvatarGroupCount | { count: number; label?: string; size?: "sm" \| "md" \| "lg"; className?: string } | The "+N" avatar. Shows "+4" and reads "and 4 more" (override with label). AvatarGroup renders it for you from max/total; use it directly only when composing the stack yourself. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| src | string | — | Image source. When omitted, still loading, or failed, the fallback shows. |
+| alt | string | "" | Alt text for the image. Without an image it becomes the avatar's accessible name (role=img), so the initials are never read out as the name. |
+| fallback | ReactNode | — | Initials or a glyph rendered when no image is displayed. |
+| fallbackDelay | number | — | Delay before showing the fallback, in ms — avoids a flash on fast loads. |
+| status | ReactNode | — | A presence indicator pinned to the bottom-end edge, usually <StatusDot tone="success" />. It sits outside the clipped circle and wears a ring in the surface colour (--avatar-group-ring, else the page background). Use this instead of absolutely positioning a dot over an Avatar. |
+| size | "sm" \| "md" \| "lg" | "md" | Square footprint: 32px / 40px / 48px. |
+
+## Variants
+
+- **size**: sm, md, lg
+
+## Tokens used
+
+`muted`, `muted-foreground`, `background`, `card`, `popover`
+
+## Accessibility
+
+- Base UI tracks the image loading status and swaps to the fallback on missing/loading/error — no manual onError wiring.
+- Provide meaningful alt text via the alt prop; pass an empty alt for decorative avatars.
+- The fallback (initials/glyph) gives a non-image identity cue for screen readers and slow connections.
+- AvatarGroup renders role=group; give it an aria-label naming the whole set ("12 collaborators"), since the visible stack only shows some of them.
+- The "+N" count is hidden from screen readers and replaced by "and N more" (AvatarGroupCount `label`, or AvatarGroup `countLabel`).
+
+## Related
+
+- Components: Entity, StatusDot, Badge, Row
+- Patterns: DashboardPage, ListDetailPage
+
+## Examples
+
+### With image
+
+```tsx
+import { Avatar } from "@sableui/react"
+
+<Avatar src="/pfp.png" alt="Alex Morgan" fallback="AM" />
+```
+
+### Fallback only
+
+```tsx
+import { Avatar } from "@sableui/react"
+
+<Avatar fallback="AM" alt="Alex Morgan" />
+```
+
+### Sizes
+
+```tsx
+import { Avatar } from "@sableui/react"
+
+<Avatar src="/pfp.png" alt="Alex Morgan" fallback="AM" size="sm" />
+<Avatar src="/pfp.png" alt="Alex Morgan" fallback="AM" size="md" />
+<Avatar src="/pfp.png" alt="Alex Morgan" fallback="AM" size="lg" />
+```
+
+### Low-level parts
+
+```tsx
+import { AvatarFallback, AvatarImage, AvatarRoot } from "@sableui/react"
+
+<AvatarRoot size="lg"><AvatarImage src="/pfp.png" alt="Mara Okafor" /><AvatarFallback>MO</AvatarFallback></AvatarRoot>
+```
+
+### Group with overflow
+
+```tsx
+import { Avatar, AvatarGroup } from "@sableui/react"
+
+<AvatarGroup aria-label="6 collaborators" max={3} size="sm" surface="card"><Avatar src="/ana.png" alt="Ana Chen" fallback="AC" /><Avatar src="/mika.png" alt="Mika Lee" fallback="ML" /><Avatar fallback="JL" alt="Jo Lund" /><Avatar fallback="AK" alt="Ari Kim" /><Avatar fallback="SR" alt="Sam Reyes" /><Avatar fallback="MO" alt="Mo Ortiz" /></AvatarGroup>
+```
+
+### Group of a larger set
+
+```tsx
+import { Avatar, AvatarGroup } from "@sableui/react"
+
+<AvatarGroup aria-label="12 attendees" total={12} countLabel={(n) => `and ${n} more attendees`}><Avatar fallback="MO" alt="Mo Ortiz" /><Avatar fallback="SR" alt="Sam Reyes" /><Avatar fallback="JL" alt="Jo Lund" /></AvatarGroup>
+```
+
+### Composed count
+
+```tsx
+import { Avatar, AvatarGroup, AvatarGroupCount } from "@sableui/react"
+
+<AvatarGroup aria-label="7 reviewers"><Avatar fallback="AC" alt="Ana Chen" /><Avatar fallback="ML" alt="Mika Lee" /><AvatarGroupCount count={5} label="and 5 more reviewers" /></AvatarGroup>
+```
+
+### With status
+
+```tsx
+import { Avatar, Entity, StatusDot } from "@sableui/react"
+
+<Entity leading={<Avatar src="/pfp.png" alt="Nova Reed" fallback="NR" status={<StatusDot tone="success" />} />} title="Nova Reed" subtitle="Online" />
+```

package/llms/components/badge.md

@@ -0,0 +1,117 @@
+# Badge
+
+**Status:** stable
+
+Compact static label, set on two axes: appearance (soft, outline, solid, overlay on media, plain text) and tone (neutral or a semantic tone). An optional leading icon, or a status dot (with pulse) for state.
+
+**Keywords:** badge, tag, label, status, metadata, chip, pill, tone, category
+
+## Usage
+
+Use Badge for any short static label: metadata, categories, tone-coded labels, a label on artwork (appearance="overlay"), or a status line (appearance="plain" with dot). Use Pill for a chip someone clicks, NotificationBadge for an unread count on an icon, and Banner or Toast for messages that need attention.
+
+### Best practices
+
+- Do: Keep badge text short: one to three words or a compact count.
+- Do: Use tone variants when the badge carries meaning, such as success, warning, destructive, edition, or collectible.
+- Do: Pair icons with text; the icon reinforces meaning but should not be the only cue.
+- Do: Choose appearance and tone separately: appearance is how loud it is (soft by default, solid for emphasis, overlay on images, plain for a status line); tone is what it means.
+- Don't: Use a Badge as a button. If it triggers an action, use Button, Toggle, or a menu item.
+- Don't: Stack many loud tone badges in one row; too many semantic colors compete with the actual content.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Container | yes | The compact pill surface carrying the tone or neutral treatment. |
+| Label | yes | Short visible text that names the category, state, role, or metadata value. |
+| Icon | no | Optional leading Icon used to reinforce the label. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| appearance | "soft" \| "outline" \| "solid" \| "overlay" \| "plain" | "soft" | How it is drawn. soft: a tinted fill (neutral is the secondary surface). outline: a hairline. solid: the tone at full strength (neutral is the inverted chip). overlay: legible on images — a dark scrim, or the solid tone. plain: no fill or padding, a status line. |
+| tone | "neutral" \| "standard" \| "collectible" \| "edition" \| "info" \| "success" \| "warning" \| "destructive" | "neutral" | What it means. Every appearance takes every tone. |
+| size | "sm" \| "md" | "md" | "sm" uses tighter padding + text-label-sm; "md" is the default look. |
+| icon | ReactNode | — | Optional leading glyph (e.g. <Icon name="lock" />), rendered before the children with the base gap. Ignored when dot is set. |
+| dot | boolean | false | A leading status dot in the badge's tone. With appearance="plain" it is a status line (● Ready). |
+| pulse | boolean | false | Pulse the dot, for a state in progress. Needs dot. |
+
+## Variants
+
+- **appearance**: soft, outline, solid, overlay, plain
+- **tone**: neutral, standard, collectible, edition, info, success, warning, destructive
+- **size**: sm, md
+
+## Tokens used
+
+`secondary`, `secondary-foreground`, `border`, `foreground`, `background`, `muted`, `muted-foreground`, `tone-standard`, `tone-collectible`, `tone-edition`, `tone-info`, `success`, `tone-warning`, `destructive`, `overlay`, `overlay-foreground`, `tone-standard-foreground`, `tone-collectible-foreground`, `tone-edition-foreground`, `tone-info-foreground`, `success-foreground`, `tone-warning-foreground`, `destructive-foreground`
+
+## Accessibility
+
+- Badges are static text by default; do not rely on color alone for meaning.
+- Use clear label text for semantic tones so assistive tech receives the same status information sighted users see.
+
+## Related
+
+- Components: Pill, StatusDot, NotificationBadge, Banner, Toast
+- Patterns: DashboardPage, ListDetailPage
+
+## Examples
+
+### Tones
+
+```tsx
+import { Badge, Row } from "@sableui/react"
+
+<Row gap={1}><Badge tone="edition">Edition</Badge><Badge tone="collectible">Collectible</Badge><Badge tone="standard">Standard</Badge></Row>
+```
+
+### Solid
+
+```tsx
+import { Badge } from "@sableui/react"
+
+<Badge appearance="solid" size="sm">Admin</Badge>
+```
+
+### Success
+
+```tsx
+import { Badge } from "@sableui/react"
+
+<Badge tone="success">Resolved</Badge>
+```
+
+### With icon
+
+```tsx
+import { Badge, Icon } from "@sableui/react"
+
+<Badge size="sm" icon={<Icon name="lock" />}>Locked</Badge>
+```
+
+### Small
+
+```tsx
+import { Badge } from "@sableui/react"
+
+<Badge size="sm" tone="info">New</Badge>
+```
+
+### Metadata row
+
+```tsx
+import { Badge, Icon, Row } from "@sableui/react"
+
+<Row gap={1}><Badge>12 editions</Badge><Badge appearance="outline">Open edition</Badge><Badge tone="info" icon={<Icon name="info" />}>Curated</Badge></Row>
+```
+
+### Semantic state
+
+```tsx
+import { Badge, Row } from "@sableui/react"
+
+<Row gap={1}><Badge tone="success">Synced</Badge><Badge tone="warning">Review</Badge><Badge tone="destructive">Blocked</Badge></Row>
+```