@design-ai/cli 4.55.0

package/examples/component-toast.md

@@ -0,0 +1,224 @@
+# `Toast` (Snackbar) — spec
+
+> Status: example artifact for `component-spec-writer` skill
+> Generated by: `skills/component-spec-writer`, citing Ant Design `message`/`notification`, MUI `Snackbar`, shadcn-ui `sonner`
+
+## Purpose
+
+A toast is **transient feedback** about an action — "Saved", "Failed to send", "Copied to clipboard". It doesn't interrupt; it appears, optionally auto-dismisses, doesn't require user input.
+
+For interruption requiring decision → use `Modal` / `AlertDialog`.
+For persistent in-page status → use `Alert` / `Banner`.
+
+## Anatomy
+
+```
+ToastContainer (singleton, portal-mounted, fixed position)
+└── Toast[] (stacked)
+    └── Toast
+        ├── [iconStart]?       (status icon by intent: ✓, !, ⚠, ⊘)
+        ├── Body
+        │   ├── Title
+        │   └── [Description]?
+        ├── [Action]?          (button — undo, retry, view)
+        └── [CloseButton]?     (✕, optional)
+```
+
+| Part | Required | Notes |
+| --- | --- | --- |
+| Title | yes | the message; ≤ 60 chars ideal |
+| Description | optional | second line for detail |
+| iconStart | usually | matches intent — provides redundant cue beyond color |
+| Action | optional | one button max ("Undo", "Retry", "View") |
+| CloseButton | optional | always provide for `intent="error"` and persistent toasts |
+
+## API
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string \| ReactNode` | — | Primary message. Required. |
+| `description` | `string \| ReactNode` | — | Secondary detail line. |
+| `intent` | `"info" \| "success" \| "warning" \| "error"` | `"info"` | Sets icon, color, and ARIA role. |
+| `duration` | `number` | varies by intent (see below) | Auto-dismiss in ms. `0` or `Infinity` = persistent. |
+| `action` | `{ label: string, onClick: () => void }` | — | One action button. |
+| `dismissible` | `boolean` | `true` (always for `error`) | Show ✕ close button. |
+| `position` | `"top-right" \| "top-center" \| "bottom-right" \| "bottom-center" \| "bottom-left" \| "top-left"` | `"bottom-right"` (desktop) / `"top-center"` (mobile) | Container position. |
+| `id` | `string` | auto | For programmatic control (update/dismiss). |
+
+Imperative API (canonical):
+
+```ts
+toast(title, options?)
+toast.success(title, options?)
+toast.error(title, options?)
+toast.warning(title, options?)
+toast.info(title, options?)
+toast.loading(title, options?)         // returns id
+toast.dismiss(id?)                      // dismisses one or all
+toast.update(id, options)               // updates content (e.g., loading → success)
+
+// Promise wrapper — common pattern for async actions
+toast.promise(
+  fetchData(),
+  {
+    loading: 'Saving…',
+    success: 'Saved',
+    error: 'Could not save',
+  }
+)
+```
+
+This imperative API is **the** convention (sonner, react-hot-toast, ant `message`, MUI `useSnackbar`). Composition-style toasts (`<Toast>...</Toast>` rendered inline) are an anti-pattern — toasts come from any code path, not just JSX.
+
+## Default duration by intent
+
+| Intent | Duration | Reasoning |
+| --- | --- | --- |
+| `info` | 4000ms | Brief acknowledgement |
+| `success` | 3000ms | Slightly faster — confirms completion, less to read |
+| `warning` | 5000ms | More content typical, give time to absorb |
+| `error` | **Persistent** (`duration: Infinity`) | User must see and dismiss. Never auto-hide errors. |
+| `loading` | Persistent | Updated to success/error via `toast.update`. |
+
+Hovering pauses the timer. Resumes when mouse leaves.
+
+## States
+
+| State | Trigger | Behavior |
+| --- | --- | --- |
+| Entering | toast triggered | slide-in 250ms ease-out from edge, opacity 0→1 |
+| Visible | settled | duration timer ticks; pauses on hover/focus |
+| Action triggered | user clicks action button | optionally auto-dismiss after click |
+| Exiting | timer or click ✕ | slide-out 200ms ease-in, opacity 1→0 |
+| Hidden | unmounted | removed from DOM after exit transition |
+
+## Stacking and limits
+
+- New toasts stack on top of existing.
+- Max simultaneous: 3–5 (most systems cap at 3). Beyond that, oldest auto-dismisses.
+- Same `id` re-toasted: replaces in place rather than stacking. Useful for "still saving…" updates.
+
+## Position behavior
+
+- **Desktop**: bottom-right is conventional (least intrusive). Top-right for important info that must be seen.
+- **Mobile**: top-center, full-width minus 16px margin. Avoid bottom-anchored toasts on mobile — fingers cover them when toasting from a tap.
+- **Account for safe-area-inset** on iOS: `padding-bottom: max(16px, env(safe-area-inset-bottom))`.
+
+## Tokens consumed
+
+```
+--color-bg-elevated
+--color-text-primary
+--color-text-secondary
+--color-success         (intent="success")
+--color-warning         (intent="warning")
+--color-error           (intent="error")
+--color-info            (intent="info")
+--color-border-default
+--space-md
+--space-sm
+--radius-md
+--shadow-2
+--motion-default
+--easing-out
+--easing-in
+--z-toast               (above modals: typically z-modal + 100)
+```
+
+## Accessibility
+
+- **Role**:
+  - `role="status"` for `info` / `success` (polite — does not interrupt screen reader).
+  - `role="alert"` for `warning` / `error` (assertive — interrupts).
+- **`aria-live`** corresponding (`polite` / `assertive`) on the container.
+- **Don't auto-focus** the toast. It's transient feedback, not a modal.
+- **Action button** in the toast: keyboard-reachable when focus is in the page; tab order includes it.
+- **Pause on focus** as well as on hover — for keyboard users tabbing through the page, the toast shouldn't disappear before they reach it.
+- **Close button** must have `aria-label="Dismiss notification"`.
+- **Color is not the only signal**: every toast has an intent icon (`✓` `!` `⚠` `⊘`) — color-blind users see the icon.
+- **Don't put critical info only in toasts**: a toast that auto-dismisses is the wrong place for "Your file failed to save — re-upload required." Make `error` persistent and provide an action.
+
+## Code example
+
+```tsx
+// Setup at app root
+<ToastContainer position="bottom-right" />
+
+// Anywhere in code
+import { toast } from "@/components/toast";
+
+// Simple confirmation
+toast.success("Saved");
+
+// With description and action
+toast.success("Project deleted", {
+  description: "All project data has been removed.",
+  action: {
+    label: "Undo",
+    onClick: () => restoreProject(id),
+  },
+});
+
+// Persistent error with action
+toast.error("Could not save", {
+  description: "Check your network connection.",
+  action: {
+    label: "Retry",
+    onClick: () => save(),
+  },
+});
+
+// Promise wrapper (canonical async pattern)
+toast.promise(saveProject(data), {
+  loading: "Saving…",
+  success: "Saved",
+  error: (err) => `Could not save: ${err.message}`,
+});
+
+// Programmatic update (loading → success/error)
+const id = toast.loading("Uploading…");
+upload().then(
+  () => toast.success("Uploaded", { id }),
+  () => toast.error("Upload failed", { id }),
+);
+```
+
+## Edge cases
+
+- **Many toasts at once** (e.g., 10 errors fire in a row from a failed batch operation): collapse to one summary toast — "10 items failed to save. View errors." Don't blast 10 toasts.
+- **User navigates away** mid-toast: toast follows the user (lives in portal at root, persists across routes). Cancel only on full app exit.
+- **Network offline**: don't toast for every retry. One persistent "Connection lost" + auto-resolve when back online.
+- **Toast obscures the action that triggered it**: if user clicks "Save" at the bottom-right, a bottom-right toast covers their next click. Position to the opposite edge of the user's likely next interaction.
+- **Reduced motion**: skip slide-in/out, use opacity-only transition.
+- **Long text**: wrap, don't truncate. Keep on screen until dismissed.
+- **Action and dismissible together**: action button on left of body, ✕ on right. Don't stack actions.
+
+## Don't
+
+- Don't auto-dismiss errors. Ever. User must acknowledge.
+- Don't use toasts for **decisions**. "Are you sure?" → modal, not toast.
+- Don't show login/signup prompts as toasts.
+- Don't cover the bottom of the screen on mobile with persistent toasts — top-center.
+- Don't make the entire toast clickable. Click target should be the explicit action button, not the toast body — accidental dismissal is otherwise easy.
+- Don't combine `success` and `error` in the same `intent="info"` color — the intent is the cue, not just the message.
+- Don't toast on app load ("Welcome back!"). Friction with no value.
+
+## References
+
+- Ant Design:
+  - [`refs/ant-design/components/message/`](../refs/ant-design/components/message/) — single-line transient messages (closest to "toast").
+  - [`refs/ant-design/components/notification/`](../refs/ant-design/components/notification/) — multi-line, with title and description (closest to this spec's full toast). Ant separates these by line count — most other systems combine.
+- MUI: [`refs/mui/packages/mui-material/src/Snackbar/Snackbar.tsx`](../refs/mui/packages/mui-material/src/Snackbar/) — composition-style React component. The least ergonomic of the three for the imperative pattern; pair with `useSnackbar` hook from notistack or build a custom queue.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/sonner.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/sonner.tsx) — wraps `sonner` library. Sonner is the modern de-facto standard; its API (this spec mirrors it) is the cleanest of the three.
+
+API choices made:
+- **Imperative API as primary** (`toast.success(...)`) — matches user mental model. Composition (`<Toast>` JSX) is rejected — toasts come from any code path, not from render.
+- **Single component for `info` / `success` / `warning` / `error`** rather than separate `Notification` and `Message` (Ant's split): the line-count distinction is implementation, not interface.
+- **Default-persistent error**: deviates from MUI/Ant defaults but matches user need. Errors auto-hiding silently are how bugs go unnoticed.
+- **`toast.promise` adopted from sonner**: canonical async pattern. Saves consumers from writing the `.then(success).catch(error)` boilerplate.
+
+## Cross-reference
+
+- [knowledge/motion/principles.md](../knowledge/motion/principles.md) — toast enter/exit timing
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md) — `role="status"` vs `role="alert"`
+- [WAI-ARIA Live Region documentation](https://www.w3.org/WAI/ARIA/apg/practices/notifications/)

package/examples/component-toggle-button.md

@@ -0,0 +1,129 @@
+# `ToggleButton` — spec
+
+> Synthesized from MUI `ToggleButton`. A button that stays in a "pressed" state when activated, like the formatting buttons in a rich-text editor (B / I / U). Used inside `ToggleButtonGroup` for related options.
+
+## When to use
+
+- Single binary toggle (e.g., "show grid").
+- Set of mutually exclusive options (text alignment: left / center / right) — use inside `ToggleButtonGroup` with `exclusive`.
+- Set of multi-select options (text style: bold + italic) — `ToggleButtonGroup` without `exclusive`.
+
+## When NOT to use
+
+- For two states with text labels (filter chips), use `Chip` with `clickable`.
+- For toggling a setting on/off in a form, use `Switch` (more standard).
+
+## Anatomy
+
+```
+┌──────┬──────┬──────┐
+│  B   │  I   │  U   │   (pressed = filled bg)
+└──────┴──────┴──────┘
+```
+
+## API
+
+```tsx
+<ToggleButtonGroup
+  value={align}
+  exclusive
+  onChange={(_, v) => v && setAlign(v)}
+  aria-label="text alignment"
+>
+  <ToggleButton value="left" aria-label="왼쪽 정렬">
+    <FormatAlignLeftIcon />
+  </ToggleButton>
+  <ToggleButton value="center" aria-label="가운데 정렬">
+    <FormatAlignCenterIcon />
+  </ToggleButton>
+  <ToggleButton value="right" aria-label="오른쪽 정렬">
+    <FormatAlignRightIcon />
+  </ToggleButton>
+</ToggleButtonGroup>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `any` | required | Identifies this button to the parent group |
+| `selected` | `boolean` | derived | Whether this button is pressed (auto when inside group) |
+| `disabled` | `boolean` | `false` | Non-interactive; greyed |
+| `onChange` | `(e, value) => void` | — | Standalone use; group manages otherwise |
+| `color` | `'standard' \| 'primary' \| 'secondary' \| ...` | `'standard'` | Pressed color |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | |
+| `aria-label` | `string` | — | Required for icon-only buttons |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | transparent bg, fg-default border |
+| Hover | bg-subtle |
+| Focus-visible | 2px focus ring |
+| Pressed (selected) | bg-pressed (brand-tinted), fg-on-pressed |
+| Disabled | reduced opacity |
+
+## Tokens consumed
+
+```
+--toggle-bg-default
+--toggle-bg-hover
+--toggle-bg-pressed       /* brand-50 light, brand-900-30 dark */
+--toggle-fg-default
+--toggle-fg-on-pressed
+--toggle-border
+--toggle-min-height-32    /* small */
+--toggle-min-height-40    /* medium — touch-friendly */
+```
+
+## Accessibility
+
+- For icon-only: `aria-label` MUST be set ("왼쪽 정렬", not "Left").
+- `aria-pressed` on the button reflects selected state (MUI handles this).
+- Inside `ToggleButtonGroup` with `aria-label`, the group becomes a toolbar; arrow keys navigate between buttons.
+- For exclusive groups, `aria-pressed` shouldn't be all unset — at least one should be pressed (or set `value=null` explicitly).
+
+## Edge cases
+
+- **Exclusive group with no selection** — possible if `value=null`; user can deselect by clicking the active button. Decide if that's intentional (alignment: probably no — always have one).
+- **Long labels** — switch to text labels with icons. Avoid mixing icon-only and text-only in the same group.
+- **Disabled subset** — possible per-button, but visually confusing if scattered. Prefer disabling the entire group.
+
+## Code example
+
+```tsx
+function TextStyleToolbar({ formats, onChange }) {
+  return (
+    <ToggleButtonGroup
+      value={formats}
+      onChange={(_, next) => onChange(next)}
+      aria-label="텍스트 스타일"
+    >
+      <ToggleButton value="bold" aria-label="굵게">
+        <FormatBoldIcon />
+      </ToggleButton>
+      <ToggleButton value="italic" aria-label="기울임">
+        <FormatItalicIcon />
+      </ToggleButton>
+      <ToggleButton value="underline" aria-label="밑줄">
+        <FormatUnderlinedIcon />
+      </ToggleButton>
+    </ToggleButtonGroup>
+  );
+}
+```
+
+## Don't
+
+- Don't put 6+ ToggleButtons in a row — overflow into a menu.
+- Don't use as a primary CTA — it's a setting control, not an action.
+- Don't omit `aria-label` for icon-only.
+
+## References
+
+- MUI: [`ToggleButton`](../refs/mui/packages/mui-material/src/ToggleButton/) + [`ToggleButtonGroup`](../refs/mui/packages/mui-material/src/ToggleButtonGroup/)
+
+## Cross-reference
+
+- [`component-button.md`](component-button.md)
+- [`component-toggle.md`](component-toggle.md)
+- [`component-switch.md`](component-switch.md)

package/examples/component-toggle.md

@@ -0,0 +1,220 @@
+# `Toggle` and `ToggleGroup` — spec
+
+> Synthesized from shadcn-ui `toggle` + `toggle-group` (Radix). A two-state pressable button. `Toggle` is single; `ToggleGroup` is a set of mutually exclusive (radio) or independent (checkbox) toggles.
+
+## Toggle vs Switch vs Checkbox
+
+| | Toggle | Switch | Checkbox |
+| --- | --- | --- | --- |
+| Visual | Button-like | iOS slider | Square box + check |
+| Use | Bold/italic in editor; pressable filter chips | On/off setting | Form selection / accept |
+| Affordance | "Press" | "Slide" | "Check" |
+| State | Pressed / unpressed | On / off | Checked / unchecked |
+| Form? | No | Yes (input semantics) | Yes (input semantics) |
+
+Toggle is for **interactive controls** in toolbars and editors. Switch is for **settings**. Checkbox is for **forms**.
+
+## Toggle anatomy
+
+```
+[ B ]   [ I ]   [ U ]      <- toolbar with 3 toggles
+ ↑ pressed (B is bold-toggled on)
+```
+
+## API — Toggle
+
+```tsx
+<Toggle
+  pressed={isBold}
+  onPressedChange={setIsBold}
+  aria-label="Toggle bold"
+>
+  <BoldIcon />
+</Toggle>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `pressed` | `boolean` | controlled | Pressed state |
+| `defaultPressed` | `boolean` | `false` | Uncontrolled initial |
+| `onPressedChange` | `(pressed: boolean) => void` | — | Callback |
+| `disabled` | `boolean` | `false` | Disabled |
+| `variant` | `"default" \| "outline"` | `"default"` | Visual style |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size |
+| `aria-label` | `string` | required (for icon-only) | Accessible label |
+
+## ToggleGroup anatomy
+
+```
+[ Left | Center | Right ]   ← single-select (one active)
+       ↑ Center pressed
+
+[ B ] [ I ] [ U ]            ← multi-select (multiple can be pressed)
+ ↑ B and I both pressed
+```
+
+## API — ToggleGroup
+
+### Single
+
+```tsx
+<ToggleGroup type="single" value={align} onValueChange={setAlign}>
+  <ToggleGroup.Item value="left" aria-label="Align left"><AlignLeftIcon /></ToggleGroup.Item>
+  <ToggleGroup.Item value="center" aria-label="Align center"><AlignCenterIcon /></ToggleGroup.Item>
+  <ToggleGroup.Item value="right" aria-label="Align right"><AlignRightIcon /></ToggleGroup.Item>
+</ToggleGroup>
+```
+
+### Multiple
+
+```tsx
+<ToggleGroup type="multiple" value={formatting} onValueChange={setFormatting}>
+  <ToggleGroup.Item value="bold" aria-label="Bold"><BoldIcon /></ToggleGroup.Item>
+  <ToggleGroup.Item value="italic" aria-label="Italic"><ItalicIcon /></ToggleGroup.Item>
+  <ToggleGroup.Item value="underline" aria-label="Underline"><UnderlineIcon /></ToggleGroup.Item>
+</ToggleGroup>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `"single" \| "multiple"` | required | Selection model |
+| `value` | `string \| string[]` | controlled | Selected values |
+| `onValueChange` | function | — | Callback (signature depends on type) |
+| `disabled` | `boolean` | `false` | Disable all items |
+| `variant` | `"default" \| "outline"` | `"default"` | Visual style |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size |
+
+## Variants
+
+### `default`
+
+Filled when pressed; transparent when not.
+
+```
+Idle:    [ B ]    (transparent)
+Pressed: [ B ]    (brand-colored bg)
+```
+
+### `outline`
+
+Bordered when not pressed; bordered + filled when pressed.
+
+```
+Idle:    [ B ]    (border + bg-secondary)
+Pressed: [ B ]    (border + brand-bg)
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Idle | Per variant |
+| Hover | Bg shifts subtly |
+| Focus-visible | 2px focus ring |
+| Pressed (active) | Persistent visual indicating "on" state |
+| Disabled | Reduced opacity, no events |
+
+Don't confuse "active" (pressed-on) with "active" (mid-press). They're different states.
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-secondary           (outline idle bg)
+--color-bg-hover
+--color-bg-pressed             (when toggled-on)
+--color-fg-default
+--color-fg-on-pressed
+--color-border-default         (outline)
+--radius-md
+--space-xs, --space-sm
+--font-size-sm
+--motion-fast
+```
+
+## Accessibility
+
+### Toggle
+
+- `<button>` with `aria-pressed="true|false"`.
+- Icon-only: `aria-label` required.
+- Touch target ≥ 24×24 (web) / 44×44 (mobile primary).
+- Focus-visible ring.
+
+### ToggleGroup
+
+- `role="group"` with `aria-label="<purpose>"`.
+- For `type="single"`: items use `role="radio"` + `aria-checked`. Treat as radio group.
+- For `type="multiple"`: items use `role="button"` + `aria-pressed`.
+- Keyboard:
+  - Tab into group focuses first.
+  - Arrow keys navigate (single-select moves selection; multi-select moves focus).
+  - Space / Enter toggles.
+
+## Code example — Editor toolbar
+
+```tsx
+function EditorToolbar({ editor }: Props) {
+  return (
+    <div className="toolbar">
+      <ToggleGroup type="multiple" value={editor.activeFormats} onValueChange={editor.setFormats}>
+        <ToggleGroup.Item value="bold" aria-label="굵게">
+          <BoldIcon />
+        </ToggleGroup.Item>
+        <ToggleGroup.Item value="italic" aria-label="기울임">
+          <ItalicIcon />
+        </ToggleGroup.Item>
+        <ToggleGroup.Item value="underline" aria-label="밑줄">
+          <UnderlineIcon />
+        </ToggleGroup.Item>
+      </ToggleGroup>
+
+      <Separator orientation="vertical" />
+
+      <ToggleGroup type="single" value={editor.alignment} onValueChange={editor.setAlignment}>
+        <ToggleGroup.Item value="left" aria-label="왼쪽 정렬"><AlignLeftIcon /></ToggleGroup.Item>
+        <ToggleGroup.Item value="center" aria-label="가운데 정렬"><AlignCenterIcon /></ToggleGroup.Item>
+        <ToggleGroup.Item value="right" aria-label="오른쪽 정렬"><AlignRightIcon /></ToggleGroup.Item>
+      </ToggleGroup>
+    </div>
+  );
+}
+```
+
+## Korean labels
+
+For toolbar icons:
+- 굵게 (bold) / 기울임 (italic) / 밑줄 (underline) / 취소선 (strikethrough)
+- 왼쪽 / 가운데 / 오른쪽 / 양쪽 정렬
+- 글머리 기호 (bullet list) / 번호 매기기 (numbered list)
+
+Pretendard for label / Korean text in `aria-label`.
+
+## Edge cases
+
+- **No selection in single-select**: allow empty value (no item pressed). Some UIs require always-one — set initial value.
+- **All items disabled**: group still rendered for layout; aria-label communicates state.
+- **Loading state**: typically disable while async toggle pending; show spinner inside.
+- **Confirmation needed for destructive toggle**: don't fire on click; open confirmation dialog first.
+- **Tooltip integration**: pair Toggle with Tooltip for icon-only buttons.
+- **RTL**: text-direction-aware alignment toggles flip meaning (left ↔ right) but keep visual order.
+
+## Don't
+
+- Don't use Toggle for form submission state. That's Switch.
+- Don't omit `aria-label` on icon-only Toggle.
+- Don't make the pressed state too subtle (need clear visual difference).
+- Don't put 10+ items in a single ToggleGroup. Split or use a dropdown.
+- Don't conflate Toggle with Button — Toggle has persistent state.
+- Don't disable focus outline.
+
+## References
+
+- shadcn-ui: [`toggle`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/toggle.tsx), [`toggle-group`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/toggle-group.tsx) (Radix)
+- WAI-ARIA: [Toggle button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) + [Radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)
+
+## Cross-reference
+
+- [`examples/component-form-controls.md`](component-form-controls.md) — Switch + Checkbox + Radio
+- [`examples/component-segmented.md`](component-segmented.md) — segmented control variant
+- [`examples/component-button.md`](component-button.md) — non-toggle variant

package/examples/component-toolbar.md

@@ -0,0 +1,104 @@
+# `Toolbar` — spec
+
+> Synthesized from MUI `Toolbar`. A horizontal container for buttons + controls — the action row in app bars, editors, dialog footers.
+
+## When to use
+
+- Top-bar toolbar in app shells (next to logo).
+- Editor / canvas toolbar (formatting buttons, tools).
+- Dialog action footers (Confirm / Cancel buttons).
+- Anywhere a horizontal cluster of related controls lives.
+
+When NOT to use:
+- Single button (use Button alone).
+- Navigation menus (use NavigationMenu / Menubar).
+
+## Anatomy
+
+```
+[Logo]   [⚙][↶][↷][·][B][I][U][·][🔗]   [Save] [Close]
+   left              center                       right
+```
+
+Three slots: leading / main / trailing. Items spaced via gap or `space-between` justification.
+
+## API
+
+```tsx
+<Toolbar>
+  <IconButton aria-label="설정"><SettingsIcon /></IconButton>
+  <IconButton aria-label="실행 취소"><UndoIcon /></IconButton>
+  <Separator orientation="vertical" />
+  <ToggleGroup type="multiple">
+    <ToggleGroup.Item value="bold"><BoldIcon /></ToggleGroup.Item>
+    <ToggleGroup.Item value="italic"><ItalicIcon /></ToggleGroup.Item>
+  </ToggleGroup>
+  <Box flex={1} />  {/* push right */}
+  <Button>Save</Button>
+</Toolbar>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "compact" \| "dense"` | `"default"` | Padding density |
+| `disableGutters` | `boolean` | `false` | Remove horizontal padding |
+| `as` | element | `"div"` | Render as |
+
+## States
+
+Stateless. Children carry their own states.
+
+## Tokens consumed
+
+```
+--toolbar-bg
+--toolbar-fg
+--toolbar-border-bottom            (when used as app bar)
+--toolbar-min-height               (typically 56-64px)
+--space-sm                         (item gap)
+```
+
+## Accessibility
+
+- `role="toolbar" aria-label="..."` on the Toolbar wrapper. Required.
+- Each child remains independently focusable.
+- Roving tabindex (optional): only one child tabbable at a time; arrow keys move focus among children. Standard for editor toolbars.
+- Touch target ≥ 44pt for primary mobile.
+
+## Korean labels
+
+- 도구 모음 (toolbar) — Korean term, rarely user-visible
+- 편집 / 보기 / 삽입 — typical menu / toolbar action names
+- aria-label in Korean for icon-only buttons
+
+## Code example — editor toolbar
+
+```tsx
+<Toolbar role="toolbar" aria-label="텍스트 서식">
+  <IconButton aria-label="실행 취소" onClick={undo}><UndoIcon /></IconButton>
+  <IconButton aria-label="다시 실행" onClick={redo}><RedoIcon /></IconButton>
+  <Separator orientation="vertical" />
+  <ToggleGroup type="multiple" value={formats} onValueChange={setFormats}>
+    <ToggleGroup.Item value="bold" aria-label="굵게"><BoldIcon /></ToggleGroup.Item>
+    <ToggleGroup.Item value="italic" aria-label="기울임"><ItalicIcon /></ToggleGroup.Item>
+    <ToggleGroup.Item value="underline" aria-label="밑줄"><UnderlineIcon /></ToggleGroup.Item>
+  </ToggleGroup>
+</Toolbar>
+```
+
+## Don't
+
+- Don't omit `role="toolbar"` for accessibility.
+- Don't pile up 20+ controls — group via overflow menu.
+- Don't make Toolbar height inconsistent across pages.
+
+## References
+
+- MUI: [`Toolbar`](../refs/mui/packages/mui-material/src/Toolbar)
+- WAI-ARIA: [Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/)
+
+## Cross-reference
+
+- [`examples/component-app-bar.md`](component-app-bar.md) — top app bar pattern
+- [`examples/component-button-group.md`](component-button-group.md) — joined button cluster
+- [`examples/component-toggle.md`](component-toggle.md) — formatting toggles