@sableui/react 0.0.0-stage → 0.1.0

package/llms/components/banner.md

@@ -0,0 +1,119 @@
+# Banner
+
+**Status:** stable
+
+Full-width, page-level announcement bar. A tone (neutral, info, success, warning, edition, destructive) × an appearance (soft tint or loud solid fill), and an optional leading scope label. Centers its message, or — with a trailing action — switches to a leading-text + trailing-button layout. Optionally sticky and dismissible.
+
+**Keywords:** banner, announcement, alert, status, message, warning, success, offline, sticky
+
+## Usage
+
+Use Banner for page-level or app-level messages that affect the current experience: outages, maintenance, success confirmations, policy notices, or major warnings. Prefer Toast for transient feedback from a specific action, and prefer InlineStatus for local row or form state.
+
+### Best practices
+
+- Do: Use soft appearance for contextual notices and solid appearance for urgent, blocking, or system-wide states.
+- Do: Set live='polite' or live='assertive' only when the banner appears or changes dynamically.
+- Do: Include one clear action when the user can resolve or inspect the state.
+- Don't: Use multiple stacked solid banners unless the page is genuinely blocked by multiple independent states.
+- Don't: Use Banner for field-level validation, row status, or small local hints; use Field, InlineStatus, or Badge instead.
+- Don't: Use Banner inside a dialog, a form, or a section to qualify the content around it — that is Note. Banner is a full-width announcement strip for page- or app-level state, so in a modal it reads as a slab heavier than the fields it warns about, and its soft appearance has no border and no tone-colored icon: the severity survives only as a faint wash.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Message | yes | The short announcement text. It should explain the state in plain language. |
+| Action | no | Optional trailing action that changes the layout from centered copy to text plus action. |
+| Dismiss | no | Optional close control for notices the user can safely hide. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| tone | "neutral" \| "info" \| "success" \| "warning" \| "edition" \| "destructive" | "neutral" | Neutral surface or a tone that encodes the announcement's intent (info / success / warning / edition / destructive). |
+| appearance | "soft" \| "solid" | "soft" | "soft" is a quiet tinted fill; "solid" is the full tone with its paired ink — for loud, can't-miss states (offline, chain-down, RPC errors). |
+| label | ReactNode | — | A short scope label ("Preview", "Staging", a project name) in a leading chip — a Badge that reads on soft and solid fills. |
+| action | ReactNode | — | A trailing action (e.g. a Button). Switches the bar to leading text + trailing action instead of centered text. |
+| sticky | boolean | false | Stick the banner to the top of its scroll container (sticky top-0, z-30). |
+| live | "off" \| "polite" \| "assertive" | "off" | ARIA live-region politeness for banners shown/updated at runtime (offline, RPC-down, "N new posts"). "polite" → role=status; "assertive" → role=alert. "off" keeps a static labelled region. |
+| dismissible | boolean | false | Render a trailing close button that hides the banner when clicked. |
+| onDismiss | () => void | — | Called after the banner is dismissed. |
+
+## Variants
+
+- **tone**: neutral, info, success, warning, edition, destructive
+- **appearance**: soft, solid
+
+## Tokens used
+
+`secondary`, `secondary-foreground`, `foreground`, `background`, `tone-info`, `tone-info-foreground`, `success`, `success-foreground`, `tone-warning`, `tone-warning-foreground`, `tone-edition`, `tone-edition-foreground`, `destructive`, `destructive-foreground`
+
+## Accessibility
+
+- Static banners render as a labelled region (role=region); set `live` to announce dynamic status bars (role=status / role=alert) when they appear or change.
+- The dismiss control is Button (on-color-ghost, icon-xs) with an aria-label; it takes the bar's own ink, so its glyph and focus ring stay legible on soft and solid fills alike.
+- Solid fills pair each tone with its theme-adaptive ink token, so text stays legible in light and dark.
+
+## Related
+
+- Components: Note, AppShell, Toast, InlineStatus, EmptyState, Button
+- Patterns: DashboardPage
+
+## Examples
+
+### Tones
+
+```tsx
+import { Banner } from "@sableui/react"
+
+<Banner tone="info">Maintenance window tonight at 02:00 UTC.</Banner>
+```
+
+### Solid (loud)
+
+```tsx
+import { Banner } from "@sableui/react"
+
+<Banner tone="destructive" appearance="solid" live="assertive">Blockchain unavailable. Collect and buy are temporarily disabled.</Banner>
+```
+
+### Success
+
+```tsx
+import { Banner } from "@sableui/react"
+
+<Banner tone="success" live="polite">Credits authorized for Studio.</Banner>
+```
+
+### Action
+
+```tsx
+import { Banner, Button } from "@sableui/react"
+
+<Banner sticky action={<Button variant="outline" size="sm">Refresh</Button>}>12 new posts</Banner>
+```
+
+### Dismissible
+
+```tsx
+import { Banner } from "@sableui/react"
+
+<Banner tone="warning" dismissible>Your session expires soon.</Banner>
+```
+
+### Recoverable warning
+
+```tsx
+import { Banner, Button } from "@sableui/react"
+
+<Banner tone="warning" action={<Button variant="outline" size="sm">Reconnect</Button>}>Wallet connection paused.</Banner>
+```
+
+### App-shell outage
+
+```tsx
+import { AppShell, Banner, EmptyState, Region } from "@sableui/react"
+
+<AppShell banners={<Banner tone="destructive" appearance="solid" live="assertive">Uploads are temporarily unavailable.</Banner>}><Region max="feed"><EmptyState title="Uploads paused" description="Existing posts are still visible while the service recovers." /></Region></AppShell>
+```

package/llms/components/bottom-nav.md

@@ -0,0 +1,80 @@
+# BottomNav
+
+**Status:** stable
+
+Mobile bottom tab bar (fixed, hidden at lg), with home-indicator safe-area padding and evenly distributed BottomNavItem tabs. Items are router-agnostic via `render`.
+
+**Keywords:** bottom nav, mobile nav, tabs, app navigation
+
+## Usage
+
+Use BottomNav for a small set of top-level mobile destinations that should remain reachable with one thumb. Mount it through `<AppShell bottomNav={…}>` so the content area reserves matching bottom space; it hides at lg, where the Sidebar takes over.
+
+### Best practices
+
+- Do: Limit the nav to the primary destinations users switch between often.
+- Do: Give every item a clear label (it is the accessible name), and turn on showLabel when the icons alone are not obvious.
+- Don't: Do not use BottomNav for desktop navigation, dense menus, or page-local actions.
+- Don't: Do not omit the safe-area padding by overriding its padding-bottom. On a device with a home indicator the last row of targets ends up under the gesture area, where taps dismiss the app instead.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| BottomNav | yes | The fixed or anchored navigation container. |
+| BottomNavItem | yes | One destination with label, icon, and active state. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| BottomNavItem | { label: string; icon?: ReactNode; active?: boolean; badge?: ReactNode; showLabel?: boolean; render?: useRender.RenderProp } + button props | A single tab, placed as a child of BottomNav. `label` is the accessible name (aria-label) and optional visible label; `icon` is the glyph node (consumer swaps fill weight for the active state); `active` marks the current route (active ink + aria-current); `badge` overlays a corner dot/count on the icon; `showLabel` shows the label text beneath the icon — defaults to false (icon-only); turn it on when the icons alone are not self-evident; `render` renders as another element, e.g. render={<Link to="/x" />}. |
+
+## Tokens used
+
+`background`, `border`, `muted-foreground`, `foreground`, `ring`
+
+## Accessibility
+
+- BottomNav renders a <nav> landmark.
+- Each tab is a 44px minimum touch target with an aria-label.
+- Active tab carries aria-current="page".
+
+## Related
+
+- Components: Sidebar, SideNav, AppHeader
+
+## Examples
+
+### Tab bar
+
+```tsx
+import { BottomNav, BottomNavItem, Icon, NotificationBadge } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<BottomNav><BottomNavItem icon={<Icon name="home" />} label="Home" active render={<Link to="/" />} /><BottomNavItem icon={<Icon name="bell" />} label="Notifications" badge={<NotificationBadge dot />} render={<Link to="/notifications" />} /></BottomNav>
+```
+
+### When NOT to use it
+
+```tsx
+import { AppShell, BottomNav, BottomNavItem, Icon, Region } from "@sableui/react"
+
+// BottomNav is for 3–5 PEER destinations on a small viewport — the mobile
+// counterpart to SideNav, not an action bar.
+
+// ✗ Actions. A bottom bar of verbs (Save / Share / Delete) is a toolbar; it
+//   competes with the OS gesture area and has no "current" state to show.
+// ✗ More than five items. Past that, labels truncate and targets shrink below
+//   the 44px floor — use a "More" destination that opens a Sheet.
+// ✗ Nested navigation. BottomNav switches top-level sections only; drilling in
+//   happens inside the section, with Breadcrumbs or a back affordance.
+
+<AppShell bottomNav={<BottomNav>
+  <BottomNavItem label="Home" icon={<Icon name="home" />} active />
+  <BottomNavItem label="Search" icon={<Icon name="search" />} />
+  <BottomNavItem label="Account" icon={<Icon name="user" />} />
+</BottomNav>}>
+  <Region max="feed">Route content</Region>
+</AppShell>
+```

package/llms/components/breadcrumbs.md

@@ -0,0 +1,75 @@
+# Breadcrumbs
+
+**Status:** stable
+
+Navigation trail showing the path to the current page. A labelled <nav> wraps an inline <ol> of crumbs — interactive ancestor links, separators, and a non-interactive current page. No Base UI.
+
+**Keywords:** breadcrumbs, hierarchy, path, navigation
+
+## Usage
+
+Use Breadcrumbs to show the user's location inside a hierarchy and provide lightweight parent navigation.
+
+### Best practices
+
+- Do: Use breadcrumbs when users can arrive deep in a nested structure.
+- Do: Keep the current page as text so it reads as location, not another link.
+- Don't: Do not use breadcrumbs as a substitute for primary navigation or step progress.
+- Don't: Do not make the last crumb a link. It points at the page you are already on, and screen readers announce it as a destination; render it as the current page with aria-current.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| BreadcrumbItem | yes | A single step in the path. |
+| BreadcrumbLink | no | A linked ancestor destination. |
+| BreadcrumbPage | yes | The current non-linked page. |
+| BreadcrumbSeparator | no | The visual separator between steps. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| BreadcrumbItem | ComponentPropsWithRef<'li'> | A single crumb slot (<li>) holding a link or the current page. |
+| BreadcrumbLink | ComponentPropsWithRef<'a'> | An interactive ancestor crumb (<a>). Muted by default, brightens to foreground on hover/focus. |
+| BreadcrumbPage | ComponentPropsWithRef<'span'> | The current-page crumb (<span aria-current="page">). Non-interactive, full-contrast. |
+| BreadcrumbSeparator | ComponentPropsWithRef<'li'> + { children? } | Decorative divider (<li aria-hidden>) between crumbs. Defaults to a chevron-right icon; pass children to swap the glyph. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Breadcrumbs | ComponentPropsWithRef<'nav'> | — | The trail root. Renders <nav aria-label="Breadcrumb"> around a flex <ol>. Pass the crumb parts as children. |
+
+## Tokens used
+
+`muted-foreground`, `foreground`
+
+## Accessibility
+
+- The <nav> carries aria-label="Breadcrumb" so assistive tech announces the landmark.
+- Crumbs sit in an ordered list (<ol>) to convey hierarchy and position.
+- The current page uses aria-current="page" and is rendered as plain text, not a link.
+- Separators are aria-hidden so the chevron glyph is not announced.
+
+## Related
+
+- Components: SideNav, PageHeader
+
+## Examples
+
+### Three-level trail
+
+```tsx
+import { BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, Breadcrumbs, BreadcrumbSeparator } from "@sableui/react"
+
+<Breadcrumbs><BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem><BreadcrumbSeparator /><BreadcrumbItem><BreadcrumbLink href="/library">Library</BreadcrumbLink></BreadcrumbItem><BreadcrumbSeparator /><BreadcrumbItem><BreadcrumbPage>Editions</BreadcrumbPage></BreadcrumbItem></Breadcrumbs>
+```
+
+### Custom separator
+
+```tsx
+import { BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, Breadcrumbs, BreadcrumbSeparator } from "@sableui/react"
+
+<Breadcrumbs><BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem><BreadcrumbSeparator>/</BreadcrumbSeparator><BreadcrumbItem><BreadcrumbPage>Settings</BreadcrumbPage></BreadcrumbItem></Breadcrumbs>
+```

package/llms/components/browser.md

@@ -0,0 +1,67 @@
+# Browser
+
+**Status:** stable
+
+A generic, current browser window: one compact toolbar (window controls, back/forward/reload, a centered address field) around page content.
+
+**Keywords:** browser, mockup, preview, website
+
+## Usage
+
+Use Browser to frame a website or product surface preview when the browser chrome is part of the story.
+
+### Best practices
+
+- Do: Use it for documentation, product examples, and visual previews where the page context matters.
+- Do: Keep the framed content simple enough to remain legible at the rendered size.
+- Don't: Do not use Browser for real navigation, real forms, or arbitrary card decoration.
+- Don't: Do not put a real, working URL in the address pill. It reads as a link, is not one, and invites a click that does nothing.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| url | string | — | Address shown in the centered address pill. Omit for a blank pill. |
+| children | ReactNode | — | Page content rendered inside the content region. |
+
+## Tokens used
+
+`card`, `background`, `border`, `muted`, `muted-foreground`
+
+## Accessibility
+
+- Purely presentational chrome; the framed content carries its own semantics.
+- The toolbar is drawn, not interactive, and hidden from assistive technology; the address is decorative text.
+
+## Related
+
+- Components: Phone, Card
+
+## Examples
+
+### Framing a page
+
+```tsx
+import { Browser, PageHeader } from "@sableui/react"
+
+<Browser url="studio.example/explore"><div className="p-8"><PageHeader title="Explore" description="Trending posts from every chain." /></div></Browser>
+```
+
+### Mockup, not chrome
+
+```tsx
+import { Browser, Region } from "@sableui/react"
+
+// Browser is DECORATIVE framing for a screenshot or a demo — it belongs on a
+// marketing page, never around your actual app.
+
+<Region max="wide">
+  <Browser url="studio.example">
+    <img src="/screenshots/editor.png" alt="The editor" />
+  </Browser>
+</Region>
+
+// ✗ Wrapping live UI in it. The frame implies "this is a picture of software";
+//   putting real controls inside makes users hunt for a browser that isn't there.
+// ✗ Using it to fake a URL bar for credibility. Show the real product.
+```

package/llms/components/bubble.md

@@ -0,0 +1,119 @@
+# Bubble
+
+**Status:** stable
+
+The surface a message's content sits on: four treatments, an align-aware tail corner, a readable measure cap, and an optional row of reaction pills.
+
+**Keywords:** chat bubble, message bubble, speech bubble, reactions, conversation, messaging, ai chat
+
+## Usage
+
+The tinted (or untinted) surface a turn's content sits on. Kept separate from Message because the row's layout and the content's surface change independently — an assistant's markdown answer wants no surface at all in exactly the same row a one-line reply wants a bubble.
+
+### Best practices
+
+- Do: Use `muted` for the other party and `primary` for the reader's own messages. Two treatments is the whole vocabulary a conversation needs to say who is speaking.
+- Do: Reach for `variant="plain"` for long-form assistant output — rendered markdown, code blocks, tables. A tinted box around three paragraphs reads as a quote block rather than as a turn, and `plain` drops the measure cap with the surface.
+- Do: Pass the same `align` you gave the enclosing Message, so the flattened corner lands on the speaker's side.
+- Do: Set `tail={false}` on the continuation bubbles in a grouped run — the tail marks where a speaker starts, and repeating it on every line makes a block of one person's messages look like four separate turns.
+- Do: Let the register size it. Inside `<Density value="compact">` a Bubble sets itself in the workspace prose tier automatically — a docked agent panel needs no per-call-site sizing, and hardcoding one defeats the mechanism.
+- Don't: Do not remove the measure cap to fill a wide window. ~42rem is a reading measure; a bubble spanning a 1600px viewport is a paragraph at 140 characters per line.
+- Don't: Do not put the timestamp or the author name inside the bubble. Those are Message's `header` / `footer`, which stay outside the surface and so still work under `variant="plain"`.
+- Don't: Do not use a Bubble for a system note or a streaming status. Those are `Marker`, which is deliberately quieter than the message tier.
+- Don't: Do not render reactions as static text. `BubbleReaction` is a toggle and reports `aria-pressed`, which is how a screen-reader user knows whether pressing it adds or removes their own reaction.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Bubble | yes | The surface itself. Holds the variant, the side, and the flattened tail corner. |
+| BubbleReactions | no | The row of reaction pills, just under the bubble at the message column's small gap, so it reads as belonging to that message rather than the next row. |
+| BubbleReaction | no | One reaction pill — emoji, count (hidden at 1), and pressed state. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| BubbleReactions | { align?: "start" \| "end" } & ComponentPropsWithRef<"div"> | Row container for reaction pills. Match `align` to the Bubble so the row hangs off the same edge. |
+| BubbleReaction | { emoji: ReactNode; count?: number; active?: boolean } & ComponentPropsWithRef<"button"> | One reaction pill. A toggle, not a label: `active` drives `aria-pressed` as well as the styling, and `count` is hidden at 1 because the pill already says "one". |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| variant | "muted" \| "primary" \| "outline" \| "plain" | "muted" | Surface treatment. `muted` for the other party, `primary` for the reader's own messages, `outline` for a quieter own-side, `plain` for long-form output that should not sit in a box (also drops the measure cap and padding). |
+| align | "start" \| "end" | "start" | Which side of the conversation the bubble is on — flattens the corner nearest the speaker. Match it to the enclosing Message. |
+| tail | boolean | true | Flatten the speaker-side corner. A flattened corner rather than a drawn arrow, so it holds up in every theme's radius language (flat through fully pilled) with no per-theme geometry. Turn it off for the continuation bubbles in a grouped run. |
+| ...div props | ComponentPropsWithRef<"div"> | — | Spread onto the surface element. |
+
+## Variants
+
+- **variant**: muted, primary, outline, plain
+- **align**: start, end
+- **tail**: true, false
+
+## Tokens used
+
+`muted`, `foreground`, `primary`, `primary-foreground`, `border`, `card`, `card-foreground`, `accent`, `accent-foreground`, `muted-foreground`, `ring`
+
+## Accessibility
+
+- The surface is a plain container with no imposed role — a bubble is presentation, and announcing one as a region would put a landmark around every line of a conversation.
+- Reaction pills are real buttons reporting `aria-pressed`, so the reader's own reaction is state rather than colour alone; the emoji is hidden from AT and the count is left readable.
+- `whitespace-pre-wrap` and `break-words` keep pasted logs, long URLs, and hard-wrapped text inside the surface instead of overflowing the conversation.
+- Every variant meets AA against its own surface, including `primary`, which pairs the primary fill with its paired foreground token rather than a hardcoded white.
+
+## Related
+
+- Components: Message, MessageScroller, Marker, Attachment
+
+## Examples
+
+### Two sides
+
+```tsx
+import { Bubble, Message } from "@sableui/react"
+
+<>
+	<Message messageId="m1"><Bubble>Did the deploy finish?</Bubble></Message>
+	<Message messageId="m2" align="end"><Bubble variant="primary" align="end">Green across the board.</Bubble></Message>
+</>
+```
+
+### Long-form assistant output
+
+```tsx
+import { Avatar, Bubble, CodeBlock, Message } from "@sableui/react"
+
+<Message messageId="a1" avatar={<Avatar size="sm" fallback="AI" />}>
+	<Bubble variant="plain" className="space-y-3">
+		<p className="text-body-md text-foreground">Three things changed in this release:</p>
+		<CodeBlock code={diff} filename="CHANGELOG.md" />
+	</Bubble>
+</Message>
+```
+
+### With reactions
+
+```tsx
+import { Bubble, BubbleReaction, BubbleReactions, Message } from "@sableui/react"
+
+<Message messageId="m3">
+	<Bubble>Shipped 0.45.0.</Bubble>
+	<BubbleReactions>
+		<BubbleReaction emoji="🎉" count={3} active onClick={() => toggle("🎉")} />
+		<BubbleReaction emoji="👀" count={1} onClick={() => toggle("👀")} />
+	</BubbleReactions>
+</Message>
+```
+
+### A grouped run drops the repeated tail
+
+```tsx
+import { Bubble, Message } from "@sableui/react"
+
+<>
+	<Message messageId="m1" align="end"><Bubble variant="primary" align="end">One more thing.</Bubble></Message>
+	<Message messageId="m2" align="end" grouped><Bubble variant="primary" align="end" tail={false}>The staging cert expires Friday.</Bubble></Message>
+</>
+```

package/llms/components/button.md

@@ -0,0 +1,199 @@
+# Button
+
+**Status:** stable
+
+Pill-shaped action primitive (theme-driven radius via --button-radius, defaults to full). Neutral tiers (primary/secondary/ghost/outline), plus destructive and link, and three on-color tiers (on-color/on-color-outline/on-color-ghost) that paint with the surrounding ink so a button reads on any tone or brand fill. Optional loading state shows a spinner and disables the button.
+
+**Keywords:** button, action, cta, submit, save, cancel, destructive, loading, link, icon button, on color, inverse, band, brand fill, tone fill
+
+## Usage
+
+Use Button when the user commits an action, submits a form, opens UI, or confirms a decision. Use the visual tier to communicate priority: one primary action per local decision area, then secondary, ghost, outline, or link for lower-emphasis choices.
+
+### Best practices
+
+- Do: Use a single primary button in a view or dense panel so the action hierarchy stays obvious.
+- Do: Write labels as actions, such as "Save changes" or "Delete draft", instead of vague labels like "OK".
+- Do: Use loading with loadingLabel for async work so the action cannot double-fire and the state is announced.
+- Do: Put icons in iconStart / iconEnd rather than as children, so the button applies its optical padding. Start icons say what the action is (plus, share); end icons say where it goes (chevron-right, external).
+- Do: On a coloured fill — a solid Banner, a bg-tone-* or bg-primary band, an inverse (bg-foreground) section, a brand panel — use variant="on-color" for the main action and on-color-outline / on-color-ghost for the rest. They paint with the band's inherited ink (currentColor), so the surface must set its paired ink (text-tone-info-foreground, text-primary-foreground, text-background…), which it already should. Name the fill once on the surface, e.g. [--on-color-fill:var(--tone-info)], and the solid button's label takes the fill colour; unnamed, it falls back to black or white against the ink. Both clear 4.5:1 in every shipped theme and mode.
+- Don't: Use destructive for reversible or low-risk actions; reserve it for operations with real loss or danger.
+- Don't: Use a button for plain navigation. Compose with render={<a />} when the element should behave like a link.
+- Don't: Use secondary on a tinted surface — inside a Note, a soft Banner, or any tone fill. `secondary` is a near-background surface token (in some themes within 2% of the page), so on a tint it reads as a hole punched in the fill rather than as a control sitting on it. On a soft tint use outline or ghost; on a full-strength fill use the on-color tiers.
+- Don't: Use the on-color tiers on the page, a Card, a Note, or a soft tint — there the ink is the page foreground and the normal tiers already fit. And don't restyle a normal variant with bg-*/text-* classNames to make it read on a band; that hard-codes colours per theme and skips the contrast and focus handling on-color carries.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Container | yes | The rounded hit target that carries the visual tier, focus ring, disabled state, and loading affordance. |
+| Label | yes | Visible action text and the default accessible name. Icon-only buttons still need an aria-label. |
+| Leading icon | no | An optional semantic Icon that reinforces the label without replacing it. |
+| Spinner | no | Displayed during loading and paired with aria-busy plus disabled activation. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| variant | "primary" \| "secondary" \| "ghost" \| "outline" \| "destructive" \| "link" \| "floating" \| "on-color" \| "on-color-outline" \| "on-color-ghost" | "primary" | Visual emphasis tier. One primary per screen. The on-color tiers are for buttons ON a coloured fill: they paint with the inherited text colour (the fill's ink) — on-color is solid (ink background, fill-coloured label via the optional --on-color-fill var, else black/white), on-color-outline and on-color-ghost are transparent with an ink label. Never use them on page or card surfaces. floating is for a control that sits OVER content (carousel arrows, a marquee pause, a jump-to-latest over a conversation): its own edge, lift and translucent popover fill, so it reads on arbitrary content beneath. |
+| size | "xs" \| "sm" \| "md" \| "cta" \| "icon" \| "icon-sm" \| "icon-xs" | "md" | Reads the density ladder, so every value differs by register: page 28/32/40/44, workspace 24/28/32/36. xs and icon-xs were added in 0.31.0 for the workspace control floor and are the sizes tool chrome wants; md is the default everywhere. icon/icon-sm/icon-xs are square. |
+| render | ReactElement \| (props, state) => ReactElement | — | Compose with another element/component through the Base UI render prop. |
+| loading | boolean | false | Disable the button and show a leading Spinner while an action is in flight. Sets aria-busy; a native button is disabled, a render element (e.g. an <a>) gets aria-disabled. |
+| badge | ReactNode | — | A corner indicator (usually <NotificationBadge dot /> or a count) overlaid on the top-end corner of the glyph. For icon-only sizes; never hand-position a badge over a Button with absolute offsets. |
+| loadingLabel | ReactNode | — | Optional text shown in place of children while loading. |
+| iconStart | ReactNode | — | Icon before the label. The button takes one 2px step off its start padding so icon + label read as centred. Replaced by the spinner while loading. |
+| iconEnd | ReactNode | — | Icon after the label (disclosure, external link, next). Same optical correction on the end side. |
+
+## Variants
+
+- **variant**: primary, secondary, ghost, outline, destructive, link, floating, on-color, on-color-outline, on-color-ghost
+- **size**: xs, sm, md, cta, icon, icon-sm, icon-xs
+
+## Tokens used
+
+`primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `accent`, `accent-foreground`, `input`, `destructive`, `destructive-foreground`, `ring`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — A button belongs to the layout it ships in. Whatever staged that region owns the entrance; a button that fades in on its own is a button that is briefly un-clickable for no stated reason.
+- **response** · Root · `motion-interactive` — Hover, focus ring and disabled fade all ease on one declaration. This is the reference case for the whole recipe: it lists scale and translate alongside the colours specifically so motion-press can add a transform without a second, conflicting transition-property.
+- **response** · Root · `motion-press` — The 0.97 settle on pointer-down is the only confirmation the press registered before the action's own result arrives — which on a slow network is the difference between waiting and clicking again. It skips disabled elements, so a dead button stays visibly dead.
+- **transition** · Root · _no motion_ — A button has no state of its own to move between. A control that toggles is a Switch or a Toggle, and those carry the transition.
+- **activity** · Root · _no motion_ — Pending work is passed in via `loading`, which renders a Spinner — the activity motion lives there rather than being duplicated here.
+
+## Accessibility
+
+- Renders a native <button> by default (keyboard + role free).
+- Focus-visible ring uses the --ring token at 50% opacity.
+- Use render={<a/>} for link semantics rather than onClick navigation.
+- On-color tiers replace the --ring focus ring with one drawn in the band's ink past a transparent 2px gap, so focus stays visible on any fill (ink-on-fill is the theme's own tested pair).
+- On-color contrast is measured in button.test.tsx for every shipped theme and mode on each tone, primary, destructive, success, highlight and inverse fill: solid label at rest and hover, and outline/ghost label on the hover wash, all at least 4.5:1.
+- loading sets aria-busy and disables activation (disabled on a native button, aria-disabled on a render element) so the action can't double-fire.
+
+## Related
+
+- Components: Menu, DotsMenu, Icon, Banner
+- Patterns: SettingsPage, AuthPage, DashboardPage
+
+## Examples
+
+### Primary
+
+```tsx
+import { Button } from "@sableui/react"
+
+<Button>Collect</Button>
+```
+
+### Secondary + ghost
+
+```tsx
+import { Button, Row } from "@sableui/react"
+
+<Row gap={1}><Button variant="secondary">Cancel</Button><Button variant="ghost">Skip</Button></Row>
+```
+
+### Loading
+
+```tsx
+import { Button } from "@sableui/react"
+
+<Button loading loadingLabel="Saving…">Save</Button>
+```
+
+### Main action with options
+
+```tsx
+import { Button, Icon, Menu, MenuContent, MenuItem, MenuTrigger, Row } from "@sableui/react"
+
+<Row gap={2}><Button onClick={deploy}>Deploy</Button><Menu><MenuTrigger render={<Button variant="secondary" size="icon" aria-label="Deploy options"><Icon name="chevron-down" /></Button>} /><MenuContent align="end"><MenuItem>Deploy to preview</MenuItem><MenuItem>Deploy to production</MenuItem></MenuContent></Menu></Row>
+```
+
+### Copy to clipboard
+
+```tsx
+import { Button, Icon, useCopy } from "@sableui/react"
+
+const { copy, copied } = useCopy(address)
+<Button variant="ghost" size="icon-sm" aria-label="Copy address" onClick={copy}><Icon name={copied ? "check" : "copy"} /></Button>
+```
+
+### As link
+
+```tsx
+import { Button } from "@sableui/react"
+
+<Button render={<a href="/explore" />}>Explore</Button>
+```
+
+### Primary + secondary decision row
+
+```tsx
+import { Button, Row } from "@sableui/react"
+
+<Row gap={1}><Button>Publish</Button><Button variant="secondary">Save draft</Button><Button variant="ghost">Cancel</Button></Row>
+```
+
+### Destructive with confirmation copy
+
+```tsx
+import { Button, Row } from "@sableui/react"
+
+<Row gap={1}><Button variant="secondary">Cancel</Button><Button variant="destructive">Delete edition</Button></Row>
+```
+
+### Leading icon
+
+```tsx
+import { Button, Icon } from "@sableui/react"
+
+<Button iconStart={<Icon name="plus" />}>New project</Button>
+```
+
+### Trailing icon
+
+```tsx
+import { Button, Icon } from "@sableui/react"
+
+<Button variant="secondary" iconEnd={<Icon name="chevron-right" />}>Continue</Button>
+```
+
+### Both icons
+
+```tsx
+import { Button, Icon } from "@sableui/react"
+
+<Button variant="outline" iconStart={<Icon name="file" />} iconEnd={<Icon name="chevron-down" />}>Export</Button>
+```
+
+### Icon-only
+
+```tsx
+import { Button, Icon } from "@sableui/react"
+
+<Button size="icon" variant="ghost" aria-label="Share"><Icon name="share" /></Button>
+```
+
+### Icon button with an unread badge
+
+```tsx
+import { Button, Icon, NotificationBadge } from "@sableui/react"
+
+<Button size="icon" variant="ghost" aria-label="Notifications" badge={<NotificationBadge dot />}><Icon name="bell" /></Button>
+```
+
+### On a coloured band
+
+```tsx
+import { Button } from "@sableui/react"
+
+<div className="flex gap-3 bg-tone-info p-6 text-tone-info-foreground [--on-color-fill:var(--tone-info)]"><Button variant="on-color">Join the beta</Button><Button variant="on-color-outline">Read the notes</Button></div>
+```
+
+### Action in a solid Banner
+
+```tsx
+import { Banner, Button } from "@sableui/react"
+
+<Banner tone="warning" appearance="solid" action={<Button variant="on-color" size="sm">Reconnect</Button>}>Wallet connection paused.</Banner>
+```