From c958d0c36395a497f43fda7124f15f6dd1243ecb Mon Sep 17 00:00:00 2001
From: Wibus <wibus_wee@outlook.com>
Date: Tue, 15 Sep 2026 09:04:21 +0000
Subject: [PATCH 1/2] feat(ui): add the @lody/ui Toggle, ToggleGroup and
 Toolbar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A control that stays pressed, a set of them answering to one value, and the
bar that holds them, sharing one `toggle` token group.

On is the well rather than ink. The rules give a stored state ink, and ink is
what a control that already sits in a well becomes when it is on — a Switch's
off state occupies the well, so on has to leave it. A toggle rests on nothing,
so the well is free, and sinking into it is the plainest thing this system can
say about a button that went down and stayed. It also keeps a bar of eight from
reading as eight primary buttons.

A set is not a Tabs strip with its track removed: a strip picks what you see,
so it is one control with one pill sliding across it, while a set stores what
is on and two of its members can be pressed at once. A bar draws nothing at all
— not even the line a table draws — and exists to make a row of controls one
tab stop the arrow keys walk.

Migrates the task body's format bar and the tasks view's "Show" chips, and
deletes the dead Radix `toggle.tsx` and its dependency.

Model: claude-opus-5[1m]
---
 .../feature/2026-09-15-ui-toggle-toolbar.md   | 280 ++++++++++++++++
 locales/en.json                               |   2 +
 locales/zh_CN.json                            |   2 +
 packages/components/package.json              |   1 -
 .../tasks/task-body-selection-toolbar.tsx     | 204 +++++++-----
 .../src/components/tasks/tasks-workspace.tsx  |  57 ++--
 packages/components/src/ui/toggle.tsx         |  44 ---
 packages/ui/AGENTS.md                         | 129 ++++---
 packages/ui/README.md                         | 143 ++++++--
 packages/ui/package.json                      |   3 +
 packages/ui/src/gallery/gallery.tsx           | 314 ++++++++++++++++++
 packages/ui/src/index.ts                      |   6 +
 packages/ui/src/separator/separator.tsx       |  11 +-
 packages/ui/src/theme/theme.tsx               |   2 +
 packages/ui/src/toggle/set.ts                 |  32 ++
 packages/ui/src/toggle/surface.ts             | 182 ++++++++++
 packages/ui/src/toggle/toggle-group.tsx       |  75 +++++
 .../ui/src/toggle/toggle.tokens.stylex.ts     |  86 +++++
 packages/ui/src/toggle/toggle.tsx             |  93 ++++++
 packages/ui/src/toggle/toolbar.tsx            | 130 ++++++++
 packages/ui/src/tokens/RULES.md               |  69 ++++
 packages/ui/test/gallery.test.tsx             |  21 ++
 packages/ui/test/toggle.test.tsx              | 251 ++++++++++++++
 pnpm-lock.yaml                                |  27 --
 specs/ui-primitives.md                        |  42 +++
 25 files changed, 1924 insertions(+), 282 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md
 delete mode 100644 packages/components/src/ui/toggle.tsx
 create mode 100644 packages/ui/src/toggle/set.ts
 create mode 100644 packages/ui/src/toggle/surface.ts
 create mode 100644 packages/ui/src/toggle/toggle-group.tsx
 create mode 100644 packages/ui/src/toggle/toggle.tokens.stylex.ts
 create mode 100644 packages/ui/src/toggle/toggle.tsx
 create mode 100644 packages/ui/src/toggle/toolbar.tsx
 create mode 100644 packages/ui/test/toggle.test.tsx

diff --git a/.agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md b/.agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md
new file mode 100644
index 000000000..fe107c02d
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md
@@ -0,0 +1,280 @@
+# UI toggle and toolbar: a control that stays pressed, and the row that holds it
+
+Status: implemented
+Translation: pending
+
+## Abstract
+
+`@lody/ui` had a control for every value a form stores and none for the state an
+interface holds without storing it — bold, wrapped lines, this filter — so
+twenty-two files in `packages/components` each drew their own `aria-pressed`
+button, and the fills they chose to mean "on" run to a dozen unrelated washes
+(`bg-muted-foreground/20`, `bg-primary/[0.12]`, `bg-white/14`, and several that
+change nothing but the text colour). This note records the family that replaces
+them — `Toggle`, `ToggleGroup` and `Toolbar`, sharing one `toggle` token group —
+and its single real design decision: **on is the well, not ink**, because ink is
+what a control that _already sits in a well_ becomes when it is on, and a toggle
+rests on nothing. It also records why a set of toggles is not a `Tabs` strip
+with the track removed, and why a bar that draws nothing at all is still a
+primitive. Two callers are migrated whole and the dead Radix `toggle.tsx` and
+its dependency are removed; the rest of the product's pressed buttons are left
+to the surfaces that own them, because a half-migrated row of controls is the
+inconsistency this work exists to remove. The board showed that in the dark
+palette it is the label colour rather than the fill that carries the state.
+
+## Problem
+
+Every rung of this system had a component except the one a person leaves pressed.
+
+`Switch`, `Checkbox` and `Radio` cover a value a form stores. `Tabs` covers one
+thing shown out of several. Neither is what a formatting bar, a file viewer's
+strip of actions or a row of filter chips needs: a button that is on right now,
+that has no name, belongs to no `Field.Root`, and cannot be invalid.
+
+So the product drew its own, twenty-two files of it, and the appearances had
+diverged as far as appearances can. A survey of the fills within six lines of an
+`aria-pressed` attribute in `packages/components/src` finds `bg-muted`,
+`bg-muted/30`, `bg-muted/40`, `bg-muted/60`, `bg-muted/80`,
+`bg-muted-foreground/20`, `bg-secondary`, `bg-secondary/50`, `bg-primary/10`,
+`bg-primary/15`, `bg-primary/[0.05]`, `bg-white/10` and `bg-white/14` — thirteen
+answers to one question. Two of the worst are in
+`sessions/session-file-content-view.tsx`, where "wrap long lines is on" and
+"annotation is on" are said with `text-foreground` against
+`text-muted-foreground` and nothing else: a 24px icon button whose entire state
+is a shade of gray, standing in a row of eight that are never pressed.
+
+`packages/components/src/ui/toggle.tsx` — the Radix wrapper with a `cva` of two
+variants — had reached zero in-repo callers some time earlier and had not been
+deleted, so `@radix-ui/react-toggle` was still a production dependency of a
+package that never imported it.
+
+## Decision
+
+One family, one token group, `toggle`: a control that stays pressed, a set of
+them answering to one value, and the bar that holds them. They are one family
+for the reason `disclosure` covers three layouts of one idea — how far apart two
+of these stand, and what "pressed" looks like, cannot become three decisions in
+three files.
+
+### On is the well, not ink
+
+This is the decision the rest follows from, and it is the elevation rules read
+carefully rather than literally.
+
+`src/tokens/RULES.md` says ink is for a stored state: the primary button,
+checked, on. A toggle does store a state, so the literal reading gives it ink —
+`label` fill under `background` text. That reading is wrong, and the reason is
+visible in the controls the rule was written for. A Switch's **off** state is
+already the well: `wellBackground` under `shadow.inset`. A Checkbox's empty box
+is the same. On has to leave the well, because the well is taken, and ink is
+where it goes. Ink is therefore not "what a stored state looks like" — it is
+what a control that already sits in a well _becomes_ when it is on.
+
+A toggle rests on nothing at all. It is a ghost Button when it is off: no fill,
+`secondaryLabel`, `hoverFill` under the pointer. The well is free, so it sinks
+into it, which is also the most literal thing this system can say about a button
+that went down and stayed down — depth without lines, which is the construction
+rule at the top of the same file. And it is what keeps a formatting bar of eight
+from reading as eight of the most important thing on the screen, which is what
+eight ink-filled buttons would be.
+
+The second half of the state is the label: `secondaryLabel` off, `label` on. A
+toggle that is off is _about_ the thing it acts on; one that is on **is** the
+thing. That pair matters more than it looks — see what the board showed.
+
+A toggle also does not bob. The motion rules give a press `translateY(1px)` and
+a dropped `shadow.inkEdge`, which is a raised thing going down and coming back.
+This one goes down and stays, so what changes is the surface under it.
+
+### The ladder, and where it comes from
+
+Sizes are `mini` 24, `small` 28, `medium` 32 and `large` 36 — the control ladder
+plus the 24px step a file viewer's strip of actions needs, which is the same
+ladder `Button` carries. It is taken from `control` in `scales.stylex.ts` rather
+than from `button`: a Button and a Toggle in one bar line up because both read
+the same scale, not because one component's group reads another's, which is the
+rule that keeps a menu from reaching for `field.background`.
+
+### A set is not a strip
+
+`ToggleGroup` and `Tabs` hold the same three words and are not the same part.
+
+A strip picks what a person **sees**. It is a single control, so it can be — and
+is — a sunken track with one thing raised out of it and one pill sliding between
+the choices. A set stores what is **on**, and two of its members can be pressed
+at once, which no single sliding pill can say. So a set has no track and each
+member sinks on its own. Asked for one choice out of several, with `multiple`
+left off, it _still_ draws no track: the same set with `multiple` on has to look
+like itself, and a component that changed its construction with a boolean would
+be two components sharing a name.
+
+The size and the shape are stated once on the set and read from a context in
+`src/toggle/set.ts`, the way `Tabs.List` states them for its tabs. The context
+lives in its own file because both parts need it and either importing the other
+to reach it would close a cycle.
+
+### A bar that draws nothing
+
+`Toolbar` has no fill, no shadow, no radius, and not even the line a table
+draws. It is a row of controls on whatever surface the product already had
+there, so a bar inside a popover is not a second surface inside one.
+
+It is a primitive anyway, and what it is for is the keyboard. A row of eight
+icon buttons is eight tab stops unless something says otherwise, and a person
+tabbing past a formatting bar should pass it rather than walk it. Base UI's
+composite makes the bar one stop, gives the arrow keys the walking, and steps
+over a control that cannot be used rather than stopping on it. That is the whole
+argument for it not being a `div` with a gap.
+
+Two gaps say what belongs with what: `toggle.groupGap` (4) between the members
+of one cluster or set, `toggle.barGap` (8) between clusters and either side of
+the line between two. The line is `Separator`'s — the one line these rules allow
+— and the bar states its orientation rather than the caller, so a horizontal bar
+cannot end up divided the wrong way. `separator.tsx` now exports its styles so
+there is one definition of that hairline rather than two.
+
+`Toolbar.Button` is Base UI's, unstyled, the way every trigger in this package
+is: joining the walk is all it does, and what arrives is `render={<Toggle …/>}`
+or `render={<Button variant="ghost" …/>}`. There is no `Toolbar.Input` or
+`Toolbar.Link`, though Base UI ships both: neither has an appearance of this
+system's to add, and an unused part is a contract to keep in step for nothing.
+
+### Alternatives considered
+
+**Ink for on.** The literal reading of the rule. Rejected above; a bar of eight
+would compete with the page's actual primary action, and the distinction between
+"this is the thing to press" and "this option is on" would be gone.
+
+**A `pressed` prop on `Button`.** Rejected because the state is Base UI's —
+controlled and uncontrolled `pressed`, `onPressedChange`, `value` inside a
+group, and `aria-pressed` — and none of it belongs to a button that acts once.
+A Button that could stay pressed would carry a state most of its call sites
+never use.
+
+**A `Tabs` strip with its track suppressed.** Rejected because the two are not
+one part with a flag: a strip cannot describe two members pressed at once, and
+the board row that puts them side by side is there to keep the next reader from
+trying it.
+
+**`toggle` as part of the `field` group.** Rejected: nothing here takes a name,
+answers to a `Field.Root` or can be invalid, and sharing the group would invite
+exactly the confusion between a Switch and a Toggle this note opens with.
+
+## What the board showed
+
+The pressed fill resolves to `rgb(232, 234, 237)` on the light panel and
+`rgb(28, 28, 28)` on the dark one, both under `shadow.inset`, measured off the
+rendered nodes. Two things follow that no unit test in this package sees.
+
+**In the dark palette the fill is a six-value step.** The board's panel is the
+card rung, `hsl(0 0% 8.6%)` — `rgb(22, 22, 22)` — and the well is
+`hsl(0 0% 11%)`, `rgb(28, 28, 28)`. With the inset shadow above it that reads as
+recessed, but it is not what a person notices first: the label going from
+`rgb(160, 160, 160)` to `rgb(255, 255, 255)` is. That is why the state is a fill
+**and** a colour rather than a fill alone, and why an implementation that
+changed only the background would have looked correct in the light palette and
+nearly stateless in the dark one — which is precisely the defect the deleted
+callers had, in reverse.
+
+**In the light palette a pressed toggle and a `Tabs` track are the same fill,**
+because they are the same rung. That is not a collision to fix; it is the point,
+and it is why the board puts a set and a strip on one row. A reader sees that
+the strip has a groove around all three choices and the set does not, which is
+the one difference between them.
+
+The bar rows confirmed the rest: the bar paints nothing (`background-color:
+rgba(0, 0, 0, 0)`, `box-shadow: none`), its gap resolves to 8px with 4px inside
+a cluster, and the separator is a 1px hairline stretched to the 28px row in both
+palettes.
+
+## Migration
+
+Two surfaces, each migrated whole, and between them they exercise every part of
+the family:
+
+- **`tasks/task-body-selection-toolbar.tsx`** — the whole bar. `role="toolbar"`
+  and a hand-built `ToolbarButton` become `Toolbar.Root`, two `Toolbar.Group`
+  clusters, `Toolbar.Separator`, and `FormatToggle` / `FormatAction` composing a
+  `Toggle` and a ghost `Button` through `render`. The link sub-state's bare
+  `<input>` becomes an `Input`. The bar is now one tab stop; it was nine.
+  `onPointerDown` preventDefault — the thing that keeps the editor's selection
+  alive — passes straight through to the composed control.
+- **`tasks/tasks-workspace.tsx`** — the set. The "Show" chips in the view menu
+  were already commented as "toggles, not menu items"; they are now a
+  `ToggleGroup multiple wrap`. `toggleProperty` became `setVisibleProperties`,
+  because a set reports every pressed member rather than the one that changed.
+
+`packages/components/src/ui/toggle.tsx` is deleted and `@radix-ui/react-toggle`
+removed from `packages/components/package.json`, per the rule that a Radix file
+goes when its in-repo callers reach zero. The lockfile entries were removed by
+hand rather than by re-resolving: `pnpm install --lockfile-only` on this branch
+also re-resolves `esbuild`, `better-auth` and `@stylexjs/unplugin` for unrelated
+reasons, and a 137-line lockfile diff for a 3-line removal is not reviewable.
+`pnpm install --frozen-lockfile` passes on the hand-edited file.
+
+### Deliberately not done
+
+- **The remaining twenty files that render `aria-pressed`.** Most are not
+  toggles wearing a disguise — a selected machine tab, a theme tile, a row in a
+  multi-select mode — and each needs its own decision about whether the thing is
+  a pressed control, a selected row or a radio. Migrating them by pattern-match
+  would put a well under a 200px card.
+- **The file viewer's action strip.** `session-file-content-view.tsx` holds the
+  two toggles whose whole state is a shade of gray, and they are the clearest
+  case this family has. They were migrated and then reverted: they sit in a row
+  of eight 24px buttons whose glyphs are 14px, and an icon-only control here
+  draws a 16px box, so moving two of eight puts two glyph sizes in one row —
+  the inconsistency this work exists to remove. The row has to move together,
+  and it cannot yet: its Save button turns `status-warning` while there are
+  unsaved edits, and these rules give `warning` to an outcome rather than to a
+  control a person presses. What an unsaved save button should look like is a
+  product decision, not this package's.
+- **The formatting bar's own surface.** `Toolbar` draws nothing, so the
+  popover's `rounded-lg border bg-popover shadow-md` stays on the caller. It
+  should become the floating rung when ProseKit's `InlinePopover` is reconciled
+  with this package's `Popover`; it is a border this system does not have.
+- **`open-source-attributions.generated.ts` and `THIRD_PARTY_NOTICES.md`.**
+  Removing the dependency makes them stale by two entries, and regenerating them
+  produces a 12,484-line diff: the file was last generated on 2026-09-04 and the
+  dependency tree has moved a long way since. That regeneration is its own
+  change.
+- **A focus sample on the board.** The ring is on the board as `toggle.ring` and
+  `toggle.ringWidth`; a focused sample would need the board to hold focus, which
+  no other section does either.
+
+### The seam this migration sits on
+
+Worth writing down because it will be read as a defect: the package's rungs and
+the product's Tailwind surfaces are not the same palette yet, and a well-rung
+control placed on a Tailwind surface can land on its own colour.
+
+The "Show" set is inside a Radix `DropdownMenuContent`, whose fill in the
+product's dark theme is `--popover: 220 54% 11.5%`
+(`packages/components/src/tailwind/index.css`). The package's well is
+`hsl(0 0% 11%)`. Those are half a percent of lightness apart, so on that one
+surface a pressed chip is carried almost entirely by its label going from
+`secondaryLabel` to `label`, plus the inset shadow's top edge — not by the fill.
+
+This is the staged migration's general seam rather than anything this family
+introduces: every `Input` already placed inside a Radix popover has it, and it
+closes when that menu becomes this package's `Menu`, which puts the chips on the
+floating rung (`hsl(0 0% 13.7%)`) where an 11% well reads as sunken. It is also
+the second reason the pressed state is a fill **and** a colour: the colour is
+what survives a surface the package did not choose.
+
+## Verification
+
+- `pnpm --filter @lody/ui test` — 276 tests, 22 files, all passing, including
+  the 13 new ones in `test/toggle.test.tsx` and the board's token coverage.
+- `pnpm --filter @lody/ui typecheck` and `pnpm --filter @lody/components
+typecheck` are clean.
+- The board was read in Chromium at both palettes, and the resolved values above
+  were measured off the rendered nodes rather than copied from the tokens.
+
+Limits: the two migrated surfaces were verified by type checking and by the
+primitives' own tests, not by driving them in the running app — the formatting
+bar lives inside a ProseKit inline popover anchored to a live text selection,
+which neither the package's jsdom suite nor its board can produce. The pressed
+appearance those callers now get is the appearance the board shows, since it is
+the same component; what is unverified is the layout around it, and the fill's
+reading on the Tailwind surface described above.
diff --git a/locales/en.json b/locales/en.json
index 57160d89c..aecad26fb 100644
--- a/locales/en.json
+++ b/locales/en.json
@@ -3648,6 +3648,8 @@
   "tasks.body.linkPlaceholder": "Paste or type a link",
   "tasks.body.format.link": "Link",
   "tasks.body.format.removeLink": "Remove link",
+  "tasks.body.format.marks": "Marks",
+  "tasks.body.format.blocks": "Blocks",
   "tasks.body.format.more": "More…",
   "tasks.actions.more": "More actions",
   "tasks.actions.copyUrl": "Copy task URL",
diff --git a/locales/zh_CN.json b/locales/zh_CN.json
index 17676b51c..9125fc307 100644
--- a/locales/zh_CN.json
+++ b/locales/zh_CN.json
@@ -3648,6 +3648,8 @@
   "tasks.body.linkPlaceholder": "粘贴或输入链接",
   "tasks.body.format.link": "链接",
   "tasks.body.format.removeLink": "移除链接",
+  "tasks.body.format.marks": "标记",
+  "tasks.body.format.blocks": "块",
   "tasks.body.format.more": "更多…",
   "tasks.actions.more": "更多操作",
   "tasks.actions.copyUrl": "复制任务链接",
diff --git a/packages/components/package.json b/packages/components/package.json
index 3a1eb92c5..93c7e5859 100644
--- a/packages/components/package.json
+++ b/packages/components/package.json
@@ -110,7 +110,6 @@
     "@radix-ui/react-scroll-area": "^1.2.9",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-tabs": "^1.0.4",
-    "@radix-ui/react-toggle": "^1.1.9",
     "@radix-ui/react-tooltip": "^1.2.9",
     "@react-three/fiber": "^9.7.0",
     "@sqlite.org/sqlite-wasm": "3.50.1-build1",
diff --git a/packages/components/src/components/tasks/task-body-selection-toolbar.tsx b/packages/components/src/components/tasks/task-body-selection-toolbar.tsx
index ae36ad983..5eca11fd7 100644
--- a/packages/components/src/components/tasks/task-body-selection-toolbar.tsx
+++ b/packages/components/src/components/tasks/task-body-selection-toolbar.tsx
@@ -19,7 +19,10 @@ import {
   InlinePopoverPositioner,
   InlinePopoverRoot,
 } from '@prosekit/react/inline-popover';
-import { cn } from '@/lib/utils';
+import { Button } from '@lody/ui/button';
+import { Input } from '@lody/ui/input';
+import { Toggle } from '@lody/ui/toggle';
+import { Toolbar } from '@lody/ui/toolbar';
 
 /**
  * Floating format toolbar over a text selection.
@@ -65,7 +68,15 @@ export type TaskBodySelectionToolbarProps = {
   onQuote?: () => void;
 };
 
-function ToolbarButton({
+/**
+ * A mark that stays on while the selection carries it.
+ *
+ * `Toolbar.Button` is what puts a control into the bar's roving focus, and
+ * `render` is how a control is composed into a Base UI part here — so the whole
+ * bar is one tab stop and the arrow keys walk it, rather than eight stops on
+ * the way past a text selection.
+ */
+function FormatToggle({
   icon: Icon,
   label,
   active = false,
@@ -77,24 +88,56 @@ function ToolbarButton({
   onTrigger: () => void;
 }) {
   return (
-    <button
-      type="button"
-      // The whole reason the toolbar can act on a selection: pointerdown would
-      // otherwise move focus out of the editor and collapse it before click.
-      onPointerDown={(event) => event.preventDefault()}
-      onClick={onTrigger}
-      aria-label={label}
-      aria-pressed={active}
-      title={label}
-      className={cn(
-        'flex h-7 w-7 items-center justify-center rounded transition-colors',
-        active
-          ? 'bg-muted-foreground/20 text-foreground'
-          : 'text-muted-foreground hover:bg-muted-foreground/10 hover:text-foreground'
-      )}
+    <Toolbar.Button
+      render={
+        <Toggle
+          size="small"
+          icon
+          pressed={active}
+          onPressedChange={onTrigger}
+          // The whole reason the toolbar can act on a selection: pointerdown
+          // would otherwise move focus out of the editor and collapse it
+          // before click.
+          onPointerDown={(event) => event.preventDefault()}
+          aria-label={label}
+          title={label}
+        />
+      }
     >
-      <Icon className="h-3.5 w-3.5" />
-    </button>
+      <Icon className="size-full" aria-hidden="true" />
+    </Toolbar.Button>
+  );
+}
+
+/**
+ * A command in the same bar: it acts and leaves nothing pressed behind, so it
+ * is a ghost Button rather than a Toggle.
+ */
+function FormatAction({
+  icon: Icon,
+  label,
+  onTrigger,
+}: {
+  icon: LucideIcon;
+  label: string;
+  onTrigger: () => void;
+}) {
+  return (
+    <Toolbar.Button
+      render={
+        <Button
+          variant="ghost"
+          size="small"
+          icon
+          onClick={onTrigger}
+          onPointerDown={(event) => event.preventDefault()}
+          aria-label={label}
+          title={label}
+        />
+      }
+    >
+      <Icon className="size-full" aria-hidden="true" />
+    </Toolbar.Button>
   );
 }
 
@@ -160,19 +203,22 @@ export function TaskBodySelectionToolbar({ onQuote }: TaskBodySelectionToolbarPr
         hoist
       >
         <InlinePopoverPopup>
-          <div
-            role="toolbar"
+          <Toolbar.Root
             aria-label={t('tasks.body.formatToolbar', 'Format selection')}
-            className="flex items-center gap-0.5 rounded-lg border border-border bg-popover p-1 shadow-md"
+            // The bar itself draws nothing, so the surface under it is this
+            // popover's and stays here until the popover is a primitive too.
+            className="rounded-lg border border-border bg-popover p-1 shadow-md"
             onPointerDown={(event) => event.preventDefault()}
           >
             {linkOpen ? (
               // Link is a sub-state of the same popover, not a second surface:
               // it replaces the row in place so the bar does not jump.
-              <div className="flex items-center gap-1 px-1">
-                <LinkIcon className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
-                <input
+              <Toolbar.Group className="px-1">
+                <LinkIcon className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden="true" />
+                <Input
                   ref={linkInputRef}
+                  size="small"
+                  className="w-56"
                   value={href}
                   onChange={(event) => setHref(event.target.value)}
                   onKeyDown={(event) => {
@@ -185,9 +231,8 @@ export function TaskBodySelectionToolbar({ onQuote }: TaskBodySelectionToolbarPr
                     }
                   }}
                   placeholder={t('tasks.body.linkPlaceholder', 'Paste or type a link')}
-                  className="h-6 w-56 bg-transparent text-[13px] outline-none placeholder:text-muted-foreground"
                 />
-                <ToolbarButton
+                <FormatAction
                   icon={Unlink}
                   label={t('tasks.body.format.removeLink', 'Remove link')}
                   onTrigger={() => {
@@ -195,63 +240,66 @@ export function TaskBodySelectionToolbar({ onQuote }: TaskBodySelectionToolbarPr
                     closeLink();
                   }}
                 />
-              </div>
+              </Toolbar.Group>
             ) : (
               <>
-                <ToolbarButton
-                  icon={Bold}
-                  label={t('tasks.body.format.bold', 'Bold')}
-                  active={isMarkActive('strong')}
-                  onTrigger={() => commands?.toggleStrong?.()}
-                />
-                <ToolbarButton
-                  icon={Italic}
-                  label={t('tasks.body.format.italic', 'Italic')}
-                  active={isMarkActive('em')}
-                  onTrigger={() => commands?.toggleEm?.()}
-                />
-                <ToolbarButton
-                  icon={Strikethrough}
-                  label={t('tasks.body.format.strike', 'Strikethrough')}
-                  active={isMarkActive('del')}
-                  onTrigger={() => commands?.toggleDel?.()}
-                />
-                <ToolbarButton
-                  icon={Code}
-                  label={t('tasks.body.format.code', 'Code')}
-                  active={isMarkActive('code')}
-                  onTrigger={() => commands?.toggleCode?.()}
-                />
-                <ToolbarButton
-                  icon={Highlighter}
-                  label={t('tasks.body.format.highlight', 'Highlight')}
-                  active={isMarkActive('highlight')}
-                  onTrigger={() => commands?.toggleHighlight?.()}
-                />
+                <Toolbar.Group aria-label={t('tasks.body.format.marks', 'Marks')}>
+                  <FormatToggle
+                    icon={Bold}
+                    label={t('tasks.body.format.bold', 'Bold')}
+                    active={isMarkActive('strong')}
+                    onTrigger={() => commands?.toggleStrong?.()}
+                  />
+                  <FormatToggle
+                    icon={Italic}
+                    label={t('tasks.body.format.italic', 'Italic')}
+                    active={isMarkActive('em')}
+                    onTrigger={() => commands?.toggleEm?.()}
+                  />
+                  <FormatToggle
+                    icon={Strikethrough}
+                    label={t('tasks.body.format.strike', 'Strikethrough')}
+                    active={isMarkActive('del')}
+                    onTrigger={() => commands?.toggleDel?.()}
+                  />
+                  <FormatToggle
+                    icon={Code}
+                    label={t('tasks.body.format.code', 'Code')}
+                    active={isMarkActive('code')}
+                    onTrigger={() => commands?.toggleCode?.()}
+                  />
+                  <FormatToggle
+                    icon={Highlighter}
+                    label={t('tasks.body.format.highlight', 'Highlight')}
+                    active={isMarkActive('highlight')}
+                    onTrigger={() => commands?.toggleHighlight?.()}
+                  />
+                </Toolbar.Group>
 
-                <span aria-hidden className="mx-0.5 h-4 w-px bg-border" />
+                <Toolbar.Separator />
 
-                <ToolbarButton
-                  icon={LinkIcon}
-                  label={t('tasks.body.format.link', 'Link')}
-                  onTrigger={() => setLinkOpen(true)}
-                />
-                <ToolbarButton
-                  icon={SquareCheck}
-                  label={t('tasks.body.format.task', 'Turn into task item')}
-                  onTrigger={() => commands?.wrapInSquareTask?.()}
-                />
-
-                <ToolbarButton
-                  icon={RemoveFormatting}
-                  label={t('tasks.body.format.clear', 'Clear formatting')}
-                  onTrigger={() => commands?.setParagraph?.()}
-                />
+                <Toolbar.Group aria-label={t('tasks.body.format.blocks', 'Blocks')}>
+                  <FormatAction
+                    icon={LinkIcon}
+                    label={t('tasks.body.format.link', 'Link')}
+                    onTrigger={() => setLinkOpen(true)}
+                  />
+                  <FormatAction
+                    icon={SquareCheck}
+                    label={t('tasks.body.format.task', 'Turn into task item')}
+                    onTrigger={() => commands?.wrapInSquareTask?.()}
+                  />
+                  <FormatAction
+                    icon={RemoveFormatting}
+                    label={t('tasks.body.format.clear', 'Clear formatting')}
+                    onTrigger={() => commands?.setParagraph?.()}
+                  />
+                </Toolbar.Group>
 
                 {onQuote ? (
                   <>
-                    <span aria-hidden className="mx-0.5 h-4 w-px bg-border" />
-                    <ToolbarButton
+                    <Toolbar.Separator />
+                    <FormatAction
                       icon={Quote}
                       label={t('tasks.body.quote', 'Quote selection')}
                       onTrigger={onQuote}
@@ -260,7 +308,7 @@ export function TaskBodySelectionToolbar({ onQuote }: TaskBodySelectionToolbarPr
                 ) : null}
               </>
             )}
-          </div>
+          </Toolbar.Root>
         </InlinePopoverPopup>
       </InlinePopoverPositioner>
     </InlinePopoverRoot>
diff --git a/packages/components/src/components/tasks/tasks-workspace.tsx b/packages/components/src/components/tasks/tasks-workspace.tsx
index 6c4a55e8a..188095710 100644
--- a/packages/components/src/components/tasks/tasks-workspace.tsx
+++ b/packages/components/src/components/tasks/tasks-workspace.tsx
@@ -31,6 +31,8 @@ import { useOrganization } from '@/hooks/useOrganization';
 import { useTaskActions } from '@/hooks/use-task-actions';
 import { useTaskSessionRollups } from '@/hooks/use-task-session-rollup';
 import { Button } from '@lody/ui/button';
+import { Toggle } from '@lody/ui/toggle';
+import { ToggleGroup } from '@lody/ui/toggle-group';
 import { ScrollArea } from '@/ui/scroll-area';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/ui/tooltip';
 import {
@@ -120,15 +122,11 @@ function DesktopTasksWorkspace({ activeTaskId }: { activeTaskId: TaskId | null }
   const layout = useAtomValue(tasksLayoutAtom);
   const [visibleByView, setVisibleByView] = useAtom(taskVisiblePropertiesAtom);
   const visibleProperties = visibleByView[layout] ?? [];
-  const toggleProperty = useCallback(
-    (property: TaskCardProperty) => {
-      setVisibleByView((previous: TaskVisibleProperties) => {
-        const current = previous[layout] ?? [];
-        const next = current.includes(property)
-          ? current.filter((item: TaskCardProperty) => item !== property)
-          : [...current, property];
-        return { ...previous, [layout]: next };
-      });
+  // The set reports every pressed member rather than the one that changed, so
+  // this stores the list it was handed instead of adding and removing from it.
+  const setVisibleProperties = useCallback(
+    (next: TaskCardProperty[]) => {
+      setVisibleByView((previous: TaskVisibleProperties) => ({ ...previous, [layout]: next }));
     },
     [layout, setVisibleByView]
   );
@@ -230,30 +228,23 @@ function DesktopTasksWorkspace({ activeTaskId }: { activeTaskId: TaskId | null }
               <p className="mb-1.5 text-[11px] font-medium text-muted-foreground">
                 {t('tasks.show.title', 'Show')}
               </p>
-              <div className="flex flex-wrap gap-1">
-                {TASK_CARD_PROPERTIES.map((property) => {
-                  const active = visibleProperties.includes(property);
-                  return (
-                    <button
-                      key={property}
-                      type="button"
-                      aria-pressed={active}
-                      onClick={() => toggleProperty(property)}
-                      className={cn(
-                        'rounded-md border px-2 py-1 text-[11px] transition-colors',
-                        active
-                          ? 'border-transparent bg-muted-foreground/20 text-foreground'
-                          : 'border-border/70 text-muted-foreground hover:bg-muted-foreground/10 hover:text-foreground'
-                      )}
-                    >
-                      {t(
-                        TASK_CARD_PROPERTY_LABELS[property].key,
-                        TASK_CARD_PROPERTY_LABELS[property].fallback
-                      )}
-                    </button>
-                  );
-                })}
-              </div>
+              <ToggleGroup
+                multiple
+                wrap
+                size="mini"
+                aria-label={t('tasks.show.title', 'Show')}
+                value={visibleProperties}
+                onValueChange={setVisibleProperties}
+              >
+                {TASK_CARD_PROPERTIES.map((property) => (
+                  <Toggle key={property} value={property}>
+                    {t(
+                      TASK_CARD_PROPERTY_LABELS[property].key,
+                      TASK_CARD_PROPERTY_LABELS[property].fallback
+                    )}
+                  </Toggle>
+                ))}
+              </ToggleGroup>
             </div>
           </DropdownMenuContent>
         </DropdownMenu>
diff --git a/packages/components/src/ui/toggle.tsx b/packages/components/src/ui/toggle.tsx
deleted file mode 100644
index e9659be29..000000000
--- a/packages/components/src/ui/toggle.tsx
+++ /dev/null
@@ -1,44 +0,0 @@
-import * as React from 'react';
-import * as TogglePrimitive from '@radix-ui/react-toggle';
-import { cva, type VariantProps } from 'class-variance-authority';
-
-import { cn } from '@/lib/utils';
-
-const toggleVariants = cva(
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium hover:bg-muted hover:text-muted-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-selection data-[state=on]:text-selection-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] outline-hidden transition-[color,box-shadow] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive whitespace-nowrap",
-  {
-    variants: {
-      variant: {
-        default: 'bg-transparent',
-        outline:
-          'border border-input-border bg-transparent shadow-xs hover:bg-hover hover:text-hover-foreground',
-      },
-      size: {
-        default: 'h-9 px-2 min-w-9',
-        sm: 'h-8 px-1.5 min-w-8',
-        lg: 'h-10 px-2.5 min-w-10',
-      },
-    },
-    defaultVariants: {
-      variant: 'default',
-      size: 'default',
-    },
-  }
-);
-
-function Toggle({
-  className,
-  variant,
-  size,
-  ...props
-}: React.ComponentProps<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants>) {
-  return (
-    <TogglePrimitive.Root
-      data-slot="toggle"
-      className={cn(toggleVariants({ variant, size, className }))}
-      {...props}
-    />
-  );
-}
-
-export { Toggle, toggleVariants };
diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md
index 2ef0fe833..5552a7877 100644
--- a/packages/ui/AGENTS.md
+++ b/packages/ui/AGENTS.md
@@ -2,116 +2,115 @@
 
 `CLAUDE.md` is a symlink to this file. Edit `AGENTS.md` only.
 
-Base UI + StyleX component library that `packages/components/src/ui` migrates
-into one component at a time. Source-consumed; consumers compile it through
-`@stylexjs/unplugin` with this package's `stylex-options.ts`.
+Base UI + StyleX library that `packages/components/src/ui` migrates into one
+component at a time. Consumers compile its source through `@stylexjs/unplugin`
+with this package's `stylex-options.ts`.
 
 - Package styles use StyleX: no Tailwind, `cn`, `cva`, `tailwind-merge` or
   `@source` scanning here. Component props own visual variants, sizes, tones and
-  shapes. A caller's `className` may carry layout or interaction constraints
-  during staged migration, never the deleted component's visual design.
+  shapes. A caller's `className` may carry layout or interaction constraints,
+  never the deleted component's visual design.
 - Depends on React, `@base-ui/react` and `@stylexjs/stylex` only; never on
-  `@lody/components`, `@lody/platform` or any cloud package.
+  `@lody/components`, `@lody/platform` or a cloud package.
 - No border token exists. Edges are wells, raised shadows, elevation shadows
   and the focus ring. Read `src/tokens/RULES.md` before adding a token or style.
 - A focus or invalid ring is a 2px `box-shadow` composed with the control's own
   shadow, never an `outline`: the shell resets every outline with `!important`,
-  which no layer order overrides. A control that changes its edge with its state
-  restates the ring with it; CSS cannot append to a box-shadow.
+  which no layer order overrides. A control whose edge changes with its state
+  restates the ring; CSS cannot append to a box-shadow.
 - Checkbox, Radio and Switch render a real `<button>` through Base UI's
-  `nativeButton`, so `:disabled` and `:focus-visible` reach them and a `<label>`
-  points at them.
+  `nativeButton`, so `:disabled`, `:focus-visible` and a `<label>` reach them.
 - Controls in the field family read validity and disabled from `Field.Root`
   through Base UI's state callback on `className`, never a prop of their own. The
   invalid ring follows `aria-invalid`, so it and what a screen reader announces
-  are one fact; `src/field/invalid.ts` owns that reading — StyleX cannot express
-  an attribute selector.
+  are one fact; `src/field/invalid.ts` owns it — StyleX has no attribute
+  selector.
 - A trigger reads `field` and the list it opens reads `popup`: different rungs,
-  and the list shares its vocabulary with a menu rather than an input.
-  `src/popup/surface.ts` holds what floating parts share, as `src/field/well.ts`
-  does for controls and `src/dialog/surface.ts` for modals.
+  and the list's vocabulary is a menu's, not an input's. `src/popup/surface.ts`
+  holds what floating parts share, as `src/field/well.ts` does for controls and
+  `src/dialog/surface.ts` for modals.
 - `Select.Value` resolves its text from `Select.Root items`, never the rows: a
   caller whose row text differs from its value states the list on the root too,
   or the trigger names the raw value (`test/select.test.tsx`).
 - Every floating part's `Content` assembles Base UI's portal, positioner and
-  popup and takes the positioning props outside. They mount into the nearest
-  `PopupContainerProvider`, switching to the absolute strategy: a container
-  centred with `translate` is the containing block for `fixed` descendants.
+  popup, taking the positioning props outside. They mount into the nearest
+  `PopupContainerProvider` on the absolute strategy: a container centred with
+  `translate` is the containing block for `fixed` descendants.
 - `Menu` is the dropdown; `ContextMenu` and `Menubar` restate only the way in
   and re-export its rows. A menu reads `popup` and replaces one declaration,
   `--anchor-width`; surface and rows come from `src/popup/surface.ts`.
 - Whatever holds a glyph gives it a box, because this package's glyphs state
   100% and StyleX has no descendant selector: a menu row's leading box, a
-  badge's, an avatar fallback's, an icon-only `Button`'s box. A caller's icon
-  states 100% too; a checkbox row's box holds its mark only.
+  badge's, an avatar's, an icon-only `Button`'s. A caller's icon states 100%
+  too; a checkbox row's box holds its mark only.
 - Every trigger here is Base UI's, unstyled: a surface opens a menu, popover or
   modal with what it had there, `render={<Button …/>}`. Post-close focus is the
-  product's, passed as `finalFocus`.
+  product's, as `finalFocus`.
 - `Popover` reads `popup` too and replaces five of a list's declarations (anchor
   width, row inset, the three making type prose); `test/popover.test.tsx` pins it.
 - Dialog, AlertDialog and Drawer are one family on the modal rung sharing
-  `dialog/surface.ts`; only the way in and what dismisses them differ. An outside
-  press does not answer an alert dialog, Escape does. `Content` names its panel
-  to `PopupContainerProvider` in **state, not a ref**: React attaches a child's
+  `dialog/surface.ts`; only their way in and dismissal differ. An outside press
+  does not answer an alert dialog; Escape does. `Content` names its panel to
+  `PopupContainerProvider` in **state, not a ref**: React attaches a child's
   refs first, so a popup mounting in the same commit lands on the body.
 - There is no `Sheet`: a panel arriving from an edge is Base UI's `Drawer`, whose
-  viewport lays it out so the panel's `transform` carries the drag. `side` is the
-  writing direction's edge, `inset` the second axis.
-- `Tooltip` is the one floating part that does not read `popup`: the ladder
-  inverts it, `label` under `shadow.medium`. Base UI makes it visual-only — no
+  viewport lays it out so the panel's `transform` carries the drag. `side` is
+  the writing direction's edge, `inset` the second axis.
+- `Tooltip` is the one floating part not reading `popup`: the ladder inverts
+  it, `label` under `shadow.medium`. Base UI makes it visual-only — no
   role, no `aria-describedby` — so every trigger states its `aria-label`.
 - Tabs, Accordion and Collapsible are one `disclosure` family sharing
   `disclosure/surface.ts`. `Tabs.List` draws its own indicator and states the
-  size once for every tab; a revealed panel's padding rides on a child, because
-  Base UI animates a height measured with `scrollHeight`, which counts it.
+  size once for every tab; a revealed panel's padding rides on a child: Base UI
+  animates a `scrollHeight`, which counts it.
 - Alert, Toast, Progress, Skeleton and Spinner are one `feedback` family. A tone
-  is a tint and a mark, never a fill; the mark is the part's, `feedback/tone.ts`
-  maps the four, and `feedback/surface.ts` mixes the tint from its rung's
-  background. `disabled` from Base UI state, not `:disabled`.
-- `Table` and `Pagination` are one `table` family; Base UI ships neither.
-  **A column is stated once** — `Table` takes `columns` and owns the width, the
-  ordering (one column, on the root), the selection (a `Checkbox`, never
-  `aria-selected`), the empty row's span, the sticky head, and the stack it
-  becomes when narrow. `table/parts.tsx` is the element layer. A table draws no
-  surface; `border-collapse: separate` lets its line, head and row ring all be
-  box-shadows.
+  is a tint and a mark, never a fill: the mark is the part's (`tone.ts`), the
+  tint mixed from its rung (`surface.ts`). `disabled` from Base UI state, not
+  `:disabled`.
+- `Table` and `Pagination` are one `table` family. **A column is stated once**:
+  `Table` takes `columns` and owns width, ordering (one column, on the root),
+  selection (a `Checkbox`, never `aria-selected`), the empty row's span, the
+  sticky head and the narrow stack. `table/parts.tsx` is the element layer. A
+  table draws no surface: `border-collapse: separate` lets its line, head and
+  row ring be box-shadows.
+- Toggle, ToggleGroup and Toolbar are one `toggle` family; a Toggle is not a
+  Switch (no name, no `Field.Root`, no validity). **On is the well, not ink**:
+  ink is what a control already in a well becomes; this rests on nothing. A
+  set is no `Tabs` strip — two can be on at once, so no track — and a bar draws
+  nothing at all, existing to be one tab stop.
 - Card, Badge and Separator answer "what is an edge?": a card's is its shadow
-  (the card rung with a Dialog's parts, no nesting; `interactive` only marks it
-  pressable), a badge is on **no rung** so its tone is a film and its word is
-  that tone pulled halfway to the ink, and a `Separator` _is_ the one allowed
-  line — no token group, announced, no margin.
-- Avatar and Kbd stand for something outside the interface — a person, a key —
-  so both take a gray. **An avatar's rung picks its letters**, and its box is a
-  ceiling as well as a floor: a flex item's automatic minimum would widen a 16px
-  circle holding two initials. A circle is a person, a tile a thing; an identity
-  colour arrives as a `style`. A `Kbd` is never a menu row's shortcut, and
+  (Dialog's parts, no nesting; `interactive` only marks it pressable), a badge
+  is on **no rung** — tone a film, word that tone halfway to ink — and a
+  `Separator` _is_ the one allowed line: no token group, announced, no margin.
+- Avatar and Kbd stand for something outside the interface, so both take a
+  gray. **An avatar's rung picks its letters**; its box is a ceiling too, or a
+  flex minimum widens a 16px circle. Circle is a person, tile a thing; identity
+  colour is a `style`. A `Kbd` is never a menu row's shortcut;
   `Tooltip.Content`'s `kbdOnInvertedTheme` inverts a cap on a chip.
 - A forced palette travels to a portalled popup: `ThemeRoot` publishes its mode
-  and `Content` re-declares it on the positioner, because a popup mounts outside
+  and `Content` re-declares it on the positioner, since a popup mounts outside
   the subtree declaring it — a light panel would otherwise open a dark list.
-- A part the shell may ring states no edge (`box-shadow: none` /
-  `outline: none`): the shell rings any focused `[tabindex]`. `Combobox.Empty`
+- A part the shell may ring states no edge (`box-shadow: none`,
+  `outline: none`): it rings any focused `[tabindex]`. `Combobox.Empty`
   stays mounted for its live region, collapsing through `:empty`.
 - Files calling `defineVars`, `createTheme` or `defineConsts` end in
   `.stylex.ts`. Their arguments are object literals; the compiler cannot
-  evaluate helpers. Vars are imported by a specifier ending in `.stylex`
-  (`@lody/ui/tokens/colors.stylex`), never through a barrel.
+  evaluate helpers. Vars are imported by a specifier ending in `.stylex`,
+  never via a barrel.
 - Component tokens live beside the component as
   `<name>/<name>.tokens.stylex.ts` and reference semantic tokens or literal px.
   One pointing at a semantic colour also belongs in that file's `createTheme`
-  palette theme, listed in `componentPaletteThemes` in `src/theme/theme.tsx`: a
+  palette theme and in `componentPaletteThemes` (`src/theme/theme.tsx`): a
   custom property declared only at the root keeps the root palette in a themed
-  subtree. A family shares one group (`field` the label, every
-  control and their messages; `popup` the lists they open), not one per
-  component.
-- `src/gallery` is the visual reference. A new token, variant, size, tone or
-  shape lands with its board entry in the same change, and the board reads
-  sample values off the rendered node rather than repeating one.
+  subtree. A family shares one group (`field` the label, every control and
+  their messages; `popup` the lists they open), not one per component.
+- `src/gallery` is the token board: a new token, variant, size, tone or shape
+  lands with its entry, read off the rendered node.
   `test/gallery.test.tsx` fails when a token has no entry. **A sample that is a
-  rung needs a different rung under it**: the panel is the card rung, and in dark
-  region and card are one value. No test sees this — open the board.
+  rung needs a different rung under it**: the panel is the card rung, and in
+  dark region and card are one value. No test sees this — open the board.
 - `corner.shape` goes wherever a radius goes, except `radius.full`: a pill or a
-  circle takes `corner.round`, since a squircle there is a superellipse. Round
-  corners outside Chromium are the fallback.
+  circle takes `corner.round`, since a squircle there is a superellipse; round
+  corners fall back outside Chromium.
 - A Radix file in `packages/components/src/ui` is deleted when its in-repo
   callers reach zero; private consumers sync on typecheck.
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 2ca66d4ad..a387f2b70 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -5,25 +5,26 @@ tokens. Product surfaces compose these primitives through
 `@lody/components`; the package does not contain product workflows or platform
 behavior.
 
-| Area                | Responsibility                                                      |
-| ------------------- | ------------------------------------------------------------------- |
-| `src/tokens`        | Semantic color, type, spacing, motion, radius, and elevation tokens |
-| `src/theme`         | Applies light or dark StyleX themes to a subtree                    |
-| `src/button`        | Base UI Button behavior and Lody variants, sizes, tones, and shapes |
+| Area                | Responsibility                                                                                                |
+| ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `src/tokens`        | Semantic color, type, spacing, motion, radius, and elevation tokens                                           |
+| `src/theme`         | Applies light or dark StyleX themes to a subtree                                                              |
+| `src/button`        | Base UI Button behavior and Lody variants, sizes, tones, and shapes                                           |
 | `src/field`         | Base UI Field composition: label, Input, Textarea, Checkbox, Radio, Switch, Select, Combobox, help, and error |
-| `src/popup`         | The floating surface a list, a menu or a popover opens on, and its tokens |
-| `src/menu`          | Menu, ContextMenu and Menubar: commands on that surface             |
-| `src/popover`       | The same surface holding content rather than rows                   |
-| `src/dialog`        | Dialog and AlertDialog: the modal rung, and its tokens               |
-| `src/drawer`        | The same rung, arriving from an edge and draggable back out          |
-| `src/tooltip`       | The inverted chip that names what is under the pointer               |
-| `src/disclosure`    | Tabs, Accordion and Collapsible: a trigger, and the thing it shows   |
-| `src/feedback`      | Alert, Toast, Progress, Skeleton and Spinner: what the system says back |
-| `src/card`          | The card rung as a component: a block of a page, and its tokens      |
-| `src/badge`         | A standing fact about the thing beside it, on no rung at all         |
-| `src/separator`     | The one line the rules allow: between the rows of a list or a table  |
-| `src/gallery`       | The token board: every token and primitive state, in both palettes  |
-| `stylex-options.ts` | Shared compiler configuration for source-consuming hosts            |
+| `src/popup`         | The floating surface a list, a menu or a popover opens on, and its tokens                                     |
+| `src/menu`          | Menu, ContextMenu and Menubar: commands on that surface                                                       |
+| `src/popover`       | The same surface holding content rather than rows                                                             |
+| `src/dialog`        | Dialog and AlertDialog: the modal rung, and its tokens                                                        |
+| `src/drawer`        | The same rung, arriving from an edge and draggable back out                                                   |
+| `src/tooltip`       | The inverted chip that names what is under the pointer                                                        |
+| `src/disclosure`    | Tabs, Accordion and Collapsible: a trigger, and the thing it shows                                            |
+| `src/toggle`        | Toggle, ToggleGroup and Toolbar: a control that stays pressed, and the bar holding it                         |
+| `src/feedback`      | Alert, Toast, Progress, Skeleton and Spinner: what the system says back                                       |
+| `src/card`          | The card rung as a component: a block of a page, and its tokens                                               |
+| `src/badge`         | A standing fact about the thing beside it, on no rung at all                                                  |
+| `src/separator`     | The one line the rules allow: between the rows of a list or a table                                           |
+| `src/gallery`       | The token board: every token and primitive state, in both palettes                                            |
+| `stylex-options.ts` | Shared compiler configuration for source-consuming hosts                                                      |
 
 Consumers compile this package's source with `@stylexjs/unplugin` and its exported
 StyleX options. Visual choices use component props. `className` is available for
@@ -83,7 +84,7 @@ const themes = [
       ))}
     </Select.Content>
   </Select.Root>
-</Field.Root>
+</Field.Root>;
 ```
 
 `Combobox` is the same list with a query in front of it. On its own the input is
@@ -102,7 +103,9 @@ had there, through Base UI's `render`:
     <MoreIcon />
   </Menu.Trigger>
   <Menu.Content>
-    <Menu.Item shortcut="⌘R" onClick={rename}>Rename</Menu.Item>
+    <Menu.Item shortcut="⌘R" onClick={rename}>
+      Rename
+    </Menu.Item>
     <Menu.Submenu>
       <Menu.SubmenuTrigger inset>Export</Menu.SubmenuTrigger>
       <Menu.Content>
@@ -110,7 +113,9 @@ had there, through Base UI's `render`:
       </Menu.Content>
     </Menu.Submenu>
     <Menu.Separator />
-    <Menu.Item tone="destructive" onClick={remove}>Delete</Menu.Item>
+    <Menu.Item tone="destructive" onClick={remove}>
+      Delete
+    </Menu.Item>
   </Menu.Content>
 </Menu.Root>
 ```
@@ -268,7 +273,7 @@ way a submenu's chevron is drawn by its row.
 
 The size is stated once, on the strip: a tab's height, its corner and its share
 of the width all follow from the track's. A strip that should take the width on
-offer says `stretch`, which stretches the track *and* splits it between the tabs
+offer says `stretch`, which stretches the track _and_ splits it between the tabs
 — stating only the first would leave a full-width groove with the choices
 huddled at its start. Arrow keys move between tabs without taking one, because a
 tab swaps a panel that may be expensive to build; a surface whose panels are
@@ -310,6 +315,67 @@ padding, so a padded panel is cropped by exactly its own padding under
 holds its prose in such a child; a caller migrating a panel that carried its own
 padding moves it inwards.
 
+A `Toggle` is a control that stays pressed, and it is **not** a `Switch`. A
+switch stores a value in a form: it takes a name, answers to a `Field.Root`, can
+be invalid, and is read as a setting. A toggle says an option is on _right now_
+— bold, wrapped lines, this filter — so it has no name, no validity and no
+message under it. Off it is a ghost `Button`, because that is what it is; on it
+sinks into the well.
+
+That is the family's one real decision, and it is the elevation rules read
+carefully rather than literally. The rules give a stored state ink — but ink is
+what a control that _already sits in a well_ becomes when it is on: a switch's
+off state occupies the well, so on has to leave it. A toggle rests on nothing at
+all, so the well is still free, and sinking into it is the plainest thing this
+system can say about a button that went down and stayed. It also keeps a bar of
+eight from reading as eight primary buttons.
+
+```tsx
+<Toggle size="small" icon pressed={wordWrap} onPressedChange={setWordWrap} aria-label="Wrap lines">
+  <WrapIcon />
+</Toggle>
+```
+
+A `ToggleGroup` is a set of them answering to one value, and it is **not** a
+`Tabs` strip. A strip picks what a person _sees_: it is one control, so it is a
+sunken track with one pill sliding between the choices. A set stores what is
+_on_, and two of its members can be pressed at once — which no sliding pill can
+say — so it has no track and each member sinks on its own. The size and the
+shape are stated once on the set, the way a strip states them for its tabs.
+
+```tsx
+<ToggleGroup multiple wrap size="mini" value={visible} onValueChange={setVisible}>
+  {properties.map((property) => (
+    <Toggle key={property} value={property}>
+      {label(property)}
+    </Toggle>
+  ))}
+</ToggleGroup>
+```
+
+A `Toolbar` is the bar that holds them, and it draws **nothing at all**: no
+fill, no shadow, no radius, not even the line a table draws. It is a row of
+controls on whatever surface the product already had there. What it is for is
+the keyboard — a row of eight icon buttons is eight tab stops unless something
+says otherwise, so the bar is one stop, the arrow keys do the walking, and a
+control that cannot be used is stepped over rather than stopped on.
+
+`Toolbar.Button` is Base UI's, unstyled, the way every trigger in this package
+is: joining the walk is all it does, and what arrives is whatever the surface
+already had there.
+
+```tsx
+<Toolbar.Root aria-label="Format selection">
+  <Toolbar.Group aria-label="Marks">
+    <Toolbar.Button render={<Toggle size="small" icon pressed={bold} aria-label="Bold" />}>
+      <BoldIcon />
+    </Toolbar.Button>
+  </Toolbar.Group>
+  <Toolbar.Separator />
+  <Toolbar.Button render={<Button variant="ghost" size="small" />}>Quote</Toolbar.Button>
+</Toolbar.Root>
+```
+
 `Alert`, `Toast`, `Progress`, `Skeleton` and `Spinner` are one family as well,
 and what they share is a sentence with two halves: what happened, and that it is
 not finished.
@@ -324,7 +390,9 @@ to be answered.
   <Alert.Title>Sync failed</Alert.Title>
   <Alert.Description>The machine did not answer in time.</Alert.Description>
   <Alert.Actions>
-    <Button size="small" onClick={retry}>Retry</Button>
+    <Button size="small" onClick={retry}>
+      Retry
+    </Button>
   </Alert.Actions>
 </Alert.Root>
 ```
@@ -395,7 +463,13 @@ record; the last record draws none.
 const columns: TableColumn<Session>[] = [
   { key: 'name', header: t('sessions.name'), cell: (s) => s.name, width: 220 },
   { key: 'agent', header: t('sessions.agent'), cell: (s) => s.agent },
-  { key: 'turns', header: t('sessions.turns'), cell: (s) => s.turns, numeric: true, sortable: true },
+  {
+    key: 'turns',
+    header: t('sessions.turns'),
+    cell: (s) => s.turns,
+    numeric: true,
+    sortable: true,
+  },
 ];
 
 <Table
@@ -409,12 +483,12 @@ const columns: TableColumn<Session>[] = [
   onRowPress={(session) => open(session.id)}
   maxHeight={320}
   empty={t('sessions.none')}
-/>
+/>;
 ```
 
 How wide a column is, which way it aligns, whether it holds figures, whether the
 table can be ordered by it, what a totals row holds under it — all facts about a
-*column*, and a column written twice (a name in the head, a cell in every row) is
+_column_, and a column written twice (a name in the head, a cell in every row) is
 a fact that can drift. Both surfaces in this repository that drew a table before
 this wrote their column template as a literal `grid-cols-[…]` string in the
 header and again in the row, by hand.
@@ -443,7 +517,7 @@ Everything else follows from having them in one place:
 
 **A table too narrow for its columns becomes a list of records**, each a stack of
 label-and-value lines, with the label being the head's own words. It asks about
-*its own* width rather than the window's — a table in a 360px side panel on a
+_its own_ width rather than the window's — a table in a 360px side panel on a
 27-inch screen is narrow — so it is a container query, and a table whose columns
 must stay a grid says `stack={false}`.
 
@@ -492,8 +566,12 @@ It takes the same `headline` a dialog's title does, because the rules reserve
   </Card.Header>
   <Input placeholder="pnpm install" />
   <Card.Footer>
-    <Button variant="ghost" size="small">Reset</Button>
-    <Button size="small" onClick={save}>Save</Button>
+    <Button variant="ghost" size="small">
+      Reset
+    </Button>
+    <Button size="small" onClick={save}>
+      Save
+    </Button>
   </Card.Footer>
 </Card.Root>
 ```
@@ -507,7 +585,7 @@ the caller's, because what a press does is a product decision.
 
 A `Badge` is a standing fact about the thing beside it, and the one part of this
 system on **no rung**: it sits on a page, a card, a menu row or a modal panel,
-so it takes no background from the ladder. Its tone is a *film* of that tone
+so it takes no background from the ladder. Its tone is a _film_ of that tone
 over whatever is underneath — 12% of `label` for neutral, 22% of its own colour
 for the rest — **and its word carries that tone as well**, as the tone pulled
 halfway to `label`.
@@ -633,7 +711,10 @@ rules allow are recorded in the
 [UI card, badge and separator note](../../.agents/notes/implemented/feature/2026-09-12-ui-card-badge-separator.md);
 the avatar ladder that picks its own letters, the key cap, and the token group
 that carries an inversion across a surface are recorded in the
-[UI avatar and kbd note](../../.agents/notes/implemented/feature/2026-09-13-ui-avatar-kbd.md).
+[UI avatar and kbd note](../../.agents/notes/implemented/feature/2026-09-13-ui-avatar-kbd.md);
+the well a pressed control sinks into, the set that is not a strip, and the bar
+that draws nothing are recorded in the
+[UI toggle and toolbar note](../../.agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md).
 
 Open the gallery with `pnpm storybook` and pick _Design System / UI Gallery_.
 It renders each sample once per palette and reads its values back off the
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 1ce255ac0..9661e72ad 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -40,8 +40,11 @@
     "./textarea": "./src/field/textarea.tsx",
     "./theme": "./src/theme/theme.tsx",
     "./toast": "./src/feedback/toast.tsx",
+    "./toggle": "./src/toggle/toggle.tsx",
+    "./toggle-group": "./src/toggle/toggle-group.tsx",
     "./tokens/colors.stylex": "./src/tokens/colors.stylex.ts",
     "./tokens/scales.stylex": "./src/tokens/scales.stylex.ts",
+    "./toolbar": "./src/toggle/toolbar.tsx",
     "./tooltip": "./src/tooltip/tooltip.tsx"
   },
   "scripts": {
diff --git a/packages/ui/src/gallery/gallery.tsx b/packages/ui/src/gallery/gallery.tsx
index c623e48e3..f6579e0c3 100644
--- a/packages/ui/src/gallery/gallery.tsx
+++ b/packages/ui/src/gallery/gallery.tsx
@@ -54,6 +54,10 @@ import { Select } from '../field/select';
 import { Separator } from '../separator/separator';
 import { Switch } from '../field/switch';
 import { Textarea } from '../field/textarea';
+import { Toggle, type ToggleSize } from '../toggle/toggle';
+import { ToggleGroup } from '../toggle/toggle-group';
+import { toggle as toggleTokens } from '../toggle/toggle.tokens.stylex';
+import { Toolbar } from '../toggle/toolbar';
 import { Pagination } from '../table/pagination';
 import { Popover } from '../popover/popover';
 import { popup } from '../popup/popup.tokens.stylex';
@@ -3194,6 +3198,291 @@ function KbdDimensions() {
   );
 }
 
+const TOGGLE_SIZES: { name: string; size: ToggleSize }[] = [
+  { name: 'mini · 24', size: 'mini' },
+  { name: 'small · 28', size: 'small' },
+  { name: 'medium · 32', size: 'medium' },
+  { name: 'large · 36', size: 'large' },
+];
+
+const TOGGLE_COLORS = [
+  {
+    name: 'toggle.label',
+    value: toggleTokens.label,
+    note: 'off: about the thing it acts on',
+  },
+  { name: 'toggle.hover', value: toggleTokens.hover, note: 'the pointer, on an off toggle' },
+  { name: 'toggle.activeLabel', value: toggleTokens.activeLabel, note: 'on: it is the thing' },
+  {
+    name: 'toggle.pressedBackground',
+    value: toggleTokens.pressedBackground,
+    note: 'on: the well, not ink',
+  },
+  { name: 'toggle.ring', value: toggleTokens.ring, note: 'where the keyboard is' },
+];
+
+/** A mark for the board's toggles, sized by the box the control gives it. */
+function BoldGlyph() {
+  return (
+    <svg
+      width="100%"
+      height="100%"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M5 3h4a2.5 2.5 0 0 1 0 5H5zM5 8h4.6a2.5 2.5 0 0 1 0 5H5z" />
+    </svg>
+  );
+}
+
+function WrapGlyph() {
+  return (
+    <svg
+      width="100%"
+      height="100%"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M2.5 4h11M2.5 12h4M2.5 8h8.5a2.25 2.25 0 0 1 0 4.5H9.5M11 11l-1.5 1.5L11 14" />
+    </svg>
+  );
+}
+
+/**
+ * The two states, side by side, and the edge the pressed one carries.
+ *
+ * This is the one row that has to be read rather than described: off is a ghost
+ * Button and on is the well rung, which is the decision the whole family rests
+ * on. Ink would have been the other answer — the rules give a stored state ink
+ * — and ink is what a control that already sits in a well becomes when it is
+ * on. A toggle rests on nothing, so the well is still free.
+ */
+function ToggleStateRow() {
+  const { ref, value } = useMeasured<HTMLButtonElement>('box-shadow');
+  return (
+    <Row>
+      <LegendKey>off and on</LegendKey>
+      <Cluster>
+        <Toggle size="small">Wrap lines</Toggle>
+        <Toggle ref={ref} size="small" defaultPressed>
+          Wrap lines
+        </Toggle>
+        <Toggle size="small" icon aria-label="Bold">
+          <BoldGlyph />
+        </Toggle>
+        <Toggle size="small" icon defaultPressed aria-label="Wrap lines">
+          <WrapGlyph />
+        </Toggle>
+      </Cluster>
+      <span {...stylex.props(styles.readout)}>toggle.pressedWell {value}</span>
+    </Row>
+  );
+}
+
+/** One rung of the ladder, pressed so the row reads as a row. */
+function ToggleSizeRow({ name, size }: { name: string; size: ToggleSize }) {
+  const { ref, value } = useMeasured<HTMLButtonElement>('height');
+  return (
+    <Row>
+      <LegendKey>{name}</LegendKey>
+      <Cluster>
+        <Toggle ref={ref} size={size} defaultPressed>
+          Running
+        </Toggle>
+        <Toggle size={size}>Archived</Toggle>
+        <Toggle size={size} icon aria-label="Bold">
+          <BoldGlyph />
+        </Toggle>
+      </Cluster>
+      <span {...stylex.props(styles.readout)}>{value}</span>
+    </Row>
+  );
+}
+
+/** The second shape: a filter a person scans a row of rather than a control. */
+function TogglePillRow() {
+  return (
+    <Row>
+      <LegendKey>pill</LegendKey>
+      <Cluster>
+        <Toggle size="small" shape="pill" defaultPressed>
+          Running
+        </Toggle>
+        <Toggle size="small" shape="pill">
+          Needs review
+        </Toggle>
+        <Toggle size="small" shape="pill">
+          Archived
+        </Toggle>
+      </Cluster>
+      <Note>
+        A pill takes `corner.round`, because a squircle at `radius.full` is a superellipse rather
+        than the stadium the shape is named for.
+      </Note>
+    </Row>
+  );
+}
+
+/** A toggle nobody can press, reporting the one opacity the family dims with. */
+function ToggleDisabledRow() {
+  const { ref, value } = useMeasured<HTMLButtonElement>('opacity');
+  return (
+    <Row>
+      <LegendKey>disabled</LegendKey>
+      <Cluster>
+        <Toggle size="small" disabled>
+          Wrap lines
+        </Toggle>
+        <Toggle ref={ref} size="small" defaultPressed disabled>
+          Wrap lines
+        </Toggle>
+      </Cluster>
+      <span {...stylex.props(styles.readout)}>toggle.disabledOpacity {value}</span>
+    </Row>
+  );
+}
+
+/**
+ * The same three choices as a strip and as a set, which is the comparison this
+ * section exists to make.
+ *
+ * A `Tabs` strip picks what a person *sees*: one control, so a sunken track
+ * with one thing raised out of it and a pill that slides. A `ToggleGroup`
+ * stores what is *on*: no track, and each member sinking on its own — because
+ * two of them can be pressed at once, and a sliding pill cannot say that.
+ */
+function ToggleSetRow() {
+  return (
+    <Row>
+      <LegendKey>set, and a strip</LegendKey>
+      <Cluster>
+        <ToggleGroup size="small" defaultValue={['board']}>
+          <Toggle value="board">Board</Toggle>
+          <Toggle value="list">List</Toggle>
+          <Toggle value="timeline">Timeline</Toggle>
+        </ToggleGroup>
+        <Tabs.Root defaultValue="board">
+          <Tabs.List size="small">
+            <Tabs.Tab value="board">Board</Tabs.Tab>
+            <Tabs.Tab value="list">List</Tabs.Tab>
+            <Tabs.Tab value="timeline">Timeline</Tabs.Tab>
+          </Tabs.List>
+        </Tabs.Root>
+      </Cluster>
+      <Note>
+        The set on the left and the strip on the right hold the same three words and are not the
+        same part. Only the strip is one control, so only the strip has a track.
+      </Note>
+    </Row>
+  );
+}
+
+/** Several at once, wrapping — the state no strip can describe. */
+function ToggleMultipleRow() {
+  return (
+    <Row>
+      <LegendKey>several at once</LegendKey>
+      <div {...stylex.props(styles.disclosureBlock)}>
+        <ToggleGroup multiple wrap size="mini" defaultValue={['status', 'assignee']}>
+          <Toggle value="status">Status</Toggle>
+          <Toggle value="assignee">Assignee</Toggle>
+          <Toggle value="labels">Labels</Toggle>
+          <Toggle value="due">Due date</Toggle>
+          <Toggle value="project">Project</Toggle>
+        </ToggleGroup>
+      </div>
+    </Row>
+  );
+}
+
+/**
+ * The bar, with two clusters and the one line between them.
+ *
+ * It draws nothing: what is under it here is the board's own panel. The gap
+ * between the clusters is wider than the gap inside one, which is the only
+ * thing the bar says about what belongs with what — beyond the line, and beyond
+ * making the whole row a single tab stop.
+ */
+function ToolbarRow() {
+  return (
+    <Row>
+      <LegendKey>bar</LegendKey>
+      <Cluster>
+        <Toolbar.Root aria-label="Format selection">
+          <Toolbar.Group aria-label="Marks">
+            <Toolbar.Button render={<Toggle size="small" icon aria-label="Bold" />}>
+              <BoldGlyph />
+            </Toolbar.Button>
+            <Toolbar.Button
+              render={<Toggle size="small" icon defaultPressed aria-label="Wrap lines" />}
+            >
+              <WrapGlyph />
+            </Toolbar.Button>
+          </Toolbar.Group>
+          <Toolbar.Separator />
+          <Toolbar.Group aria-label="Actions">
+            <Toolbar.Button
+              render={<Button variant="ghost" size="small" icon aria-label="Add a link" />}
+            >
+              <PlusGlyph />
+            </Toolbar.Button>
+            <Toolbar.Button render={<Button variant="ghost" size="small" />}>Quote</Toolbar.Button>
+          </Toolbar.Group>
+        </Toolbar.Root>
+      </Cluster>
+      <Note>
+        A bar is one tab stop and the arrow keys walk it, which is why it is a part rather than a
+        row with a gap: eight icon buttons are otherwise eight stops on the way past them.
+      </Note>
+    </Row>
+  );
+}
+
+function ToggleDimensions() {
+  const dimensions = [
+    { name: 'toggle.heightMini', value: toggleTokens.heightMini },
+    { name: 'toggle.heightSmall', value: toggleTokens.heightSmall },
+    { name: 'toggle.heightMedium', value: toggleTokens.heightMedium },
+    { name: 'toggle.heightLarge', value: toggleTokens.heightLarge },
+    { name: 'toggle.paddingXMini', value: toggleTokens.paddingXMini },
+    { name: 'toggle.paddingXSmall', value: toggleTokens.paddingXSmall },
+    { name: 'toggle.paddingXMedium', value: toggleTokens.paddingXMedium },
+    { name: 'toggle.paddingXLarge', value: toggleTokens.paddingXLarge },
+    { name: 'toggle.radiusMini', value: toggleTokens.radiusMini },
+    { name: 'toggle.radiusSmall', value: toggleTokens.radiusSmall },
+    { name: 'toggle.radiusMedium', value: toggleTokens.radiusMedium },
+    { name: 'toggle.textMini', value: toggleTokens.textMini },
+    { name: 'toggle.text', value: toggleTokens.text },
+    { name: 'toggle.gap', value: toggleTokens.gap },
+    { name: 'toggle.iconSize', value: toggleTokens.iconSize },
+    { name: 'toggle.groupGap', value: toggleTokens.groupGap },
+    { name: 'toggle.barGap', value: toggleTokens.barGap },
+    { name: 'toggle.ringWidth', value: toggleTokens.ringWidth },
+  ];
+  return (
+    <Row>
+      <LegendKey>dimensions</LegendKey>
+      <div {...stylex.props(styles.replicaCaption)}>
+        <dl {...stylex.props(styles.constList)}>
+          {dimensions.map((entry) => (
+            <WidthProbeRow key={entry.name} {...entry} />
+          ))}
+        </dl>
+      </div>
+    </Row>
+  );
+}
+
 function ButtonFocusRow() {
   const { ref, value } = useMeasured<HTMLDivElement>('box-shadow');
   return (
@@ -4202,6 +4491,31 @@ export function UiGallery({ palettes = 'both' }: UiGalleryProps) {
           </Grid>
         </PaletteSplit>
       </Section>
+
+      <Section
+        title="Toggle, ToggleGroup and Toolbar · a control that stays pressed"
+        rule="A Toggle is not a Switch, and the difference is what each is for. A Switch stores a value in a form: it takes a name, answers to a Field.Root, can be invalid, and is read as a setting. A Toggle says an option is on right now — bold, wrapped lines, this filter — so it has no name, no validity and no message under it. Off it is a ghost Button, because that is what it is; on it sinks into the well. The rules give a stored state ink, and this is where that rule is read carefully rather than literally: ink is what a control that already sits in a well becomes when it is on — a Switch's off state occupies the well, so on has to leave it — and a toggle rests on nothing at all, so the well is still free and sinking is the plainest thing this system can say about a button that went down and stayed. It also keeps a bar of eight from reading as eight primary buttons. A set of them is not a Tabs strip: a strip picks what you see, so it can be one control with one pill sliding across it, while a set stores what is on and two of its members can be pressed at once. And a bar draws nothing at all — no fill, no shadow, no radius, not even the line a table draws — because what it is for is the keyboard: it makes a row of eight controls one tab stop and gives the arrow keys the walking."
+      >
+        <PaletteSplit palettes={palettes}>
+          <Rows>
+            <ToggleStateRow />
+            {TOGGLE_SIZES.map((entry) => (
+              <ToggleSizeRow key={entry.name} {...entry} />
+            ))}
+            <TogglePillRow />
+            <ToggleDisabledRow />
+            <ToggleSetRow />
+            <ToggleMultipleRow />
+            <ToolbarRow />
+            <ToggleDimensions />
+          </Rows>
+          <Grid>
+            {TOGGLE_COLORS.map((token) => (
+              <Swatch key={token.name} {...token} />
+            ))}
+          </Grid>
+        </PaletteSplit>
+      </Section>
     </Board>
   );
 }
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 251eff25f..771420b4a 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -179,6 +179,12 @@ export type { TextareaProps, TextareaResize } from './field/textarea';
 export { Toast } from './feedback/toast';
 export type { ToastProviderProps, ToastViewportProps } from './feedback/toast';
 export type { FeedbackTone } from './feedback/tone';
+export { Toggle } from './toggle/toggle';
+export type { ToggleProps, ToggleShape, ToggleSize } from './toggle/toggle';
+export { ToggleGroup } from './toggle/toggle-group';
+export type { ToggleGroupProps } from './toggle/toggle-group';
+export { Toolbar } from './toggle/toolbar';
+export type { ToolbarGroupProps, ToolbarRootProps, ToolbarSeparatorProps } from './toggle/toolbar';
 export { ThemeRoot, forcedThemeClassNames } from './theme/theme';
 export type { ThemeMode } from './theme/theme';
 export { Tooltip } from './tooltip/tooltip';
diff --git a/packages/ui/src/separator/separator.tsx b/packages/ui/src/separator/separator.tsx
index 7fb0650a3..93278425a 100644
--- a/packages/ui/src/separator/separator.tsx
+++ b/packages/ui/src/separator/separator.tsx
@@ -10,7 +10,12 @@ export interface SeparatorProps extends Omit<BaseProps, 'className'> {
   className?: string;
 }
 
-const styles = stylex.create({
+/**
+ * The line itself, exported because `Toolbar.Separator` draws the same one: a
+ * second `stylex.create` for a hairline is a second place for the one edge this
+ * system allows to drift.
+ */
+export const separatorStyles = stylex.create({
   /**
    * The one line this system allows, and it has no token group of its own.
    *
@@ -60,8 +65,8 @@ export const Separator = forwardRef<HTMLDivElement, SeparatorProps>(function Sep
   ref
 ) {
   const sx = stylex.props(
-    styles.base,
-    orientation === 'vertical' ? styles.vertical : styles.horizontal
+    separatorStyles.base,
+    orientation === 'vertical' ? separatorStyles.vertical : separatorStyles.horizontal
   );
   return (
     <BaseSeparator
diff --git a/packages/ui/src/theme/theme.tsx b/packages/ui/src/theme/theme.tsx
index e7b298db0..a575f448b 100644
--- a/packages/ui/src/theme/theme.tsx
+++ b/packages/ui/src/theme/theme.tsx
@@ -11,6 +11,7 @@ import { fieldPaletteTheme } from '../field/field.tokens.stylex';
 import { kbdPaletteTheme } from '../kbd/kbd.tokens.stylex';
 import { popupPaletteTheme } from '../popup/popup.tokens.stylex';
 import { tablePaletteTheme } from '../table/table.tokens.stylex';
+import { togglePaletteTheme } from '../toggle/toggle.tokens.stylex';
 import { tooltipPaletteTheme } from '../tooltip/tooltip.tokens.stylex';
 import { darkShadowTheme, darkTheme, lightShadowTheme, lightTheme } from '../tokens/colors.stylex';
 
@@ -33,6 +34,7 @@ const componentPaletteThemes = [
   kbdPaletteTheme,
   popupPaletteTheme,
   tablePaletteTheme,
+  togglePaletteTheme,
   tooltipPaletteTheme,
 ];
 
diff --git a/packages/ui/src/toggle/set.ts b/packages/ui/src/toggle/set.ts
new file mode 100644
index 000000000..4e799603a
--- /dev/null
+++ b/packages/ui/src/toggle/set.ts
@@ -0,0 +1,32 @@
+import { createContext, useContext } from 'react';
+
+/** The control ladder a Button is on, plus the 24px step below it. */
+export type ToggleSize = 'mini' | 'small' | 'medium' | 'large';
+export type ToggleShape = 'default' | 'pill';
+
+export interface ToggleSet {
+  size: ToggleSize;
+  shape: ToggleShape;
+}
+
+/**
+ * What the set was told, for the members inside it.
+ *
+ * A member's height and shape follow from the set's, so both are stated once on
+ * the group rather than repeated on every Toggle, where two of them could
+ * disagree — the same reason `Tabs.List` states the strip's size for its tabs.
+ *
+ * It lives in its own file rather than beside either part because both need it:
+ * the group publishes it and the Toggle reads it, and a module that imported
+ * the other to reach it would close a cycle between them.
+ */
+export const ToggleSetContext = createContext<ToggleSet | null>(null);
+
+/**
+ * What a `Toggle` inherits from the set around it, or `null` when it stands
+ * alone. A Toggle reads this itself rather than taking it as a prop, the way a
+ * control in the field family reads validity from its `Field.Root`.
+ */
+export function useToggleSet(): ToggleSet | null {
+  return useContext(ToggleSetContext);
+}
diff --git a/packages/ui/src/toggle/surface.ts b/packages/ui/src/toggle/surface.ts
new file mode 100644
index 000000000..e4663edf9
--- /dev/null
+++ b/packages/ui/src/toggle/surface.ts
@@ -0,0 +1,182 @@
+import * as stylex from '@stylexjs/stylex';
+import { corner, duration, ease, radius, text } from '../tokens/scales.stylex';
+import { toggle } from './toggle.tokens.stylex';
+
+/**
+ * The ring this family draws, in the shape every other ring here takes: 2px,
+ * tight to the control, no offset, no glow, and a `box-shadow` rather than an
+ * `outline` because the product shell resets every outline with `!important`.
+ * A pressed toggle has an edge of its own, so it composes the ring onto it —
+ * CSS cannot append to a box-shadow list, so the pressed style restates both.
+ */
+const RING = `0 0 0 ${toggle.ringWidth} ${toggle.ring}`;
+
+/**
+ * What a toggle, a set of them and the bar holding them are made of.
+ *
+ * It lives here rather than beside each part for the reason
+ * `disclosure/surface.ts` holds the three disclosures' appearance: three parts
+ * of one family cannot each grow their own idea of how far apart two controls
+ * stand or what "pressed" looks like.
+ */
+export const toggleSurface = stylex.create({
+  /**
+   * The control itself, at rest. This is a ghost Button's reset, and
+   * deliberately so: a toggle that is off is a ghost Button that happens to
+   * remember, so the two cannot look different while they sit in one bar.
+   */
+  base: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: toggle.gap,
+    flexShrink: 0,
+    whiteSpace: 'nowrap',
+    boxSizing: 'border-box',
+    margin: 0,
+    borderWidth: 0,
+    borderStyle: 'none',
+    fontFamily: 'inherit',
+    fontWeight: 500,
+    letterSpacing: text.controlTracking,
+    lineHeight: 1,
+    cornerShape: corner.shape,
+    // Not an `outline`; see RING above.
+    outlineStyle: 'none',
+    cursor: { default: 'pointer', ':disabled': 'default' },
+    userSelect: 'none',
+    opacity: { default: 1, ':disabled': toggle.disabledOpacity },
+    pointerEvents: { default: 'auto', ':disabled': 'none' },
+    /**
+     * A toggle does not bob. The motion rules give a press
+     * `translateY(1px)` and a dropped highlight, and that is the report of a
+     * raised thing going down and coming back; this one goes down and stays, so
+     * what moves is the surface under it rather than the control itself.
+     */
+    transitionProperty: 'background-color, color, box-shadow, opacity',
+    transitionDuration: duration.fast,
+    transitionTimingFunction: ease.standard,
+  },
+  mini: {
+    height: toggle.heightMini,
+    paddingInline: toggle.paddingXMini,
+    borderRadius: toggle.radiusMini,
+    fontSize: toggle.textMini,
+  },
+  small: {
+    height: toggle.heightSmall,
+    paddingInline: toggle.paddingXSmall,
+    borderRadius: toggle.radiusSmall,
+    fontSize: toggle.text,
+  },
+  medium: {
+    height: toggle.heightMedium,
+    paddingInline: toggle.paddingXMedium,
+    borderRadius: toggle.radiusMedium,
+    fontSize: toggle.text,
+  },
+  large: {
+    height: toggle.heightLarge,
+    paddingInline: toggle.paddingXLarge,
+    borderRadius: toggle.radiusMedium,
+    fontSize: toggle.text,
+  },
+  iconMini: { width: toggle.heightMini, paddingInline: 0 },
+  iconSmall: { width: toggle.heightSmall, paddingInline: 0 },
+  iconMedium: { width: toggle.heightMedium, paddingInline: 0 },
+  iconLarge: { width: toggle.heightLarge, paddingInline: 0 },
+  /**
+   * The box an icon-only toggle gives what is in it, for the reason an
+   * icon-only Button draws one: this package's glyphs and icons state their
+   * size as 100% of whatever holds them, and StyleX has no descendant selector
+   * with which the control could reach one.
+   */
+  glyph: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    width: toggle.iconSize,
+    height: toggle.iconSize,
+  },
+  // A pill drops the base squircle: at `radius.full` a squircle is a
+  // superellipse rather than the stadium shape the name promises.
+  pill: { borderRadius: radius.full, cornerShape: corner.round },
+  /** Off: no fill of its own, and about the thing rather than the thing. */
+  rest: {
+    backgroundColor: { default: 'transparent', ':hover': toggle.hover },
+    color: { default: toggle.label, ':hover': toggle.activeLabel },
+    boxShadow: { default: 'none', ':focus-visible': RING },
+  },
+  /**
+   * On: the well rung, and the label colour of something that is the thing
+   * rather than about it. The hover steps away from the surface by the mix a
+   * secondary Button's hover and a popup's highlight already use, because the
+   * ladder's own named fills were tuned against a row on the page rather than
+   * against a control that has sunk into it.
+   */
+  pressed: {
+    backgroundColor: {
+      default: toggle.pressedBackground,
+      ':hover': `color-mix(in oklab, ${toggle.pressedBackground}, ${toggle.activeLabel} 4%)`,
+    },
+    color: toggle.activeLabel,
+    boxShadow: {
+      default: toggle.pressedWell,
+      ':focus-visible': `${toggle.pressedWell}, ${RING}`,
+    },
+  },
+
+  // ── The set ──────────────────────────────────────────────────────────────
+  /**
+   * A set of toggles answering to one value.
+   *
+   * It is a row with a gap and nothing else — no track, no indicator — and that
+   * is the whole difference between it and a `Tabs` strip. A strip picks what
+   * you *see*, so it can be one control with one pill sliding between the
+   * choices; a set stores what is *on*, and two of these can be on at once,
+   * which a sliding pill cannot say. Each member sinks on its own.
+   */
+  group: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: toggle.groupGap,
+    minWidth: 0,
+  },
+  groupVertical: { flexDirection: 'column', alignItems: 'stretch' },
+  /**
+   * A set too wide for its row runs onto a second one rather than overflowing.
+   * The members keep their width there — a toggle neither grows nor shrinks,
+   * the way a badge does not — and the row gap is already the one `gap` states,
+   * so wrapping costs a single declaration.
+   */
+  groupWrap: { flexWrap: 'wrap' },
+
+  // ── The bar ──────────────────────────────────────────────────────────────
+  /**
+   * The bar itself, which draws nothing at all: no fill, no shadow, no radius,
+   * and not even the line a table draws. It is a row of controls on whatever
+   * surface the product already had there, so a bar inside a popover is not a
+   * second surface inside one.
+   *
+   * What it is for is the keyboard. A row of eight icon buttons is eight tab
+   * stops unless something says otherwise, and a person tabbing through a page
+   * should pass a bar rather than walk it; Base UI makes the bar one stop and
+   * gives the arrow keys the walking.
+   */
+  bar: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: toggle.barGap,
+    minWidth: 0,
+  },
+  barVertical: { flexDirection: 'column', alignItems: 'stretch' },
+  /** A cluster inside a bar: related controls, at the set's tighter gap. */
+  barGroup: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: toggle.groupGap,
+    minWidth: 0,
+  },
+  barGroupVertical: { flexDirection: 'column', alignItems: 'stretch' },
+});
diff --git a/packages/ui/src/toggle/toggle-group.tsx b/packages/ui/src/toggle/toggle-group.tsx
new file mode 100644
index 000000000..c8197c242
--- /dev/null
+++ b/packages/ui/src/toggle/toggle-group.tsx
@@ -0,0 +1,75 @@
+import { ToggleGroup as BaseToggleGroup } from '@base-ui/react/toggle-group';
+import * as stylex from '@stylexjs/stylex';
+import { useMemo, type ReactNode, type Ref } from 'react';
+import { appendClassName } from '../internal/class-name';
+import { ToggleSetContext, type ToggleShape, type ToggleSize } from './set';
+import { toggleSurface as surface } from './surface';
+
+type BaseProps<Value extends string> = BaseToggleGroup.Props<Value>;
+
+export interface ToggleGroupProps<Value extends string> extends Omit<
+  BaseProps<Value>,
+  'className' | 'children'
+> {
+  children?: ReactNode;
+  /** The height every member takes. Stated once here. Defaults to medium. */
+  size?: ToggleSize;
+  /** The shape every member takes. Stated once here. */
+  shape?: ToggleShape;
+  /** Let a set too wide for its row run onto a second one. */
+  wrap?: boolean;
+  /**
+   * The ref arrives as a prop rather than through `forwardRef`, unlike the rest
+   * of this package. `forwardRef` types a component by its props alone, so a
+   * generic one keeps its type parameter only behind a cast — and this one is
+   * generic so that a caller's own union reaches `value` and `onValueChange`
+   * instead of widening to `string[]`. React 19 puts every ref in props anyway.
+   */
+  ref?: Ref<HTMLDivElement>;
+  className?: string;
+}
+
+/**
+ * A set of toggles answering to one value.
+ *
+ * It is **not** a `Tabs` strip, and the two cannot be folded together. A strip
+ * picks what a person *sees*: it is a single control, so it is a sunken track
+ * with one thing raised out of it and one pill sliding between the choices. A
+ * set stores what is *on*: two members can be pressed at once, which no sliding
+ * pill can say, so there is no track and each member sinks on its own. Asked
+ * for one choice out of several — `multiple` left off — it still draws no
+ * track, because the same set with `multiple` on has to look like itself.
+ *
+ * The value is the list of the pressed members' `value`s, so every member in a
+ * set states one; Base UI says so in development when one does not.
+ *
+ * Base UI makes the set one tab stop and gives the arrow keys the walking, so a
+ * person tabbing through a page passes a set of eight rather than walking it.
+ */
+export function ToggleGroup<Value extends string>({
+  size = 'medium',
+  shape = 'default',
+  wrap = false,
+  orientation = 'horizontal',
+  className,
+  ref,
+  ...rest
+}: ToggleGroupProps<Value>) {
+  const sx = stylex.props(
+    surface.group,
+    orientation === 'vertical' && surface.groupVertical,
+    wrap && surface.groupWrap
+  );
+  const set = useMemo(() => ({ size, shape }), [size, shape]);
+  return (
+    <ToggleSetContext.Provider value={set}>
+      <BaseToggleGroup
+        ref={ref}
+        orientation={orientation}
+        {...rest}
+        className={appendClassName(sx.className, className)}
+        style={sx.style}
+      />
+    </ToggleSetContext.Provider>
+  );
+}
diff --git a/packages/ui/src/toggle/toggle.tokens.stylex.ts b/packages/ui/src/toggle/toggle.tokens.stylex.ts
new file mode 100644
index 000000000..44d99adf5
--- /dev/null
+++ b/packages/ui/src/toggle/toggle.tokens.stylex.ts
@@ -0,0 +1,86 @@
+import * as stylex from '@stylexjs/stylex';
+import { colors, shadow } from '../tokens/colors.stylex';
+import { control, radius, space, text } from '../tokens/scales.stylex';
+
+/**
+ * One token group for a control that stays pressed, a set of them, and the bar
+ * that holds them.
+ *
+ * They are one family for the reason `disclosure` covers three layouts of one
+ * idea: a `ToggleGroup` is a row of `Toggle`s that answer to one value and a
+ * `Toolbar` is the row itself, so what a pressed control looks like and how far
+ * apart two of them stand cannot become three decisions in three files.
+ *
+ * It is deliberately not the `field` group. A Switch stores a value in a form —
+ * it takes a name, answers to a `Field.Root` and can be invalid — while a
+ * Toggle states that an option is on right now: bold, wrapped lines, this
+ * filter. Nothing here has a name, a validity or a message under it.
+ *
+ * The size ladder is `control`'s rather than `Button`'s, though a Button and a
+ * Toggle standing in one bar have to line up. They line up because both read
+ * the same scale, not because one reads the other's group: a component group is
+ * not another component's to name, which is the rule that keeps a menu from
+ * reaching for `field.background`. `mini` is off that ladder, so it is stated
+ * here the way `Button` states its own.
+ */
+export const toggle = stylex.defineVars({
+  heightMini: '24px',
+  heightSmall: control.small,
+  heightMedium: control.medium,
+  heightLarge: control.large,
+  paddingXMini: '8px',
+  paddingXSmall: '10px',
+  paddingXMedium: '12px',
+  paddingXLarge: '14px',
+  radiusMini: '6px',
+  radiusSmall: radius.small,
+  radiusMedium: radius.medium,
+  textMini: text.footnoteSize,
+  text: text.subheadlineSize,
+  gap: '6px',
+  // What a toggle holds: the 16 every other holder in this package gives a
+  // glyph, because this package's icons state 100% of whatever holds them.
+  iconSize: '16px',
+  // At rest a toggle is a ghost Button — it is about the thing it acts on — and
+  // under the pointer it becomes the thing.
+  label: colors.secondaryLabel,
+  hover: colors.hoverFill,
+  activeLabel: colors.label,
+  /**
+   * Pressed is the well rung: `wellBackground` under `shadow.inset`, which is
+   * the pair the ladder gives every sunken thing here.
+   *
+   * The rules say ink is for a stored state, and a toggle does store one — but
+   * ink is what a control that **already sits in a well** becomes when it is on.
+   * A Switch's off state occupies the well, so on has to leave it; a Checkbox's
+   * empty box is the same. A toggle rests on nothing at all, so the well is
+   * still free, and sinking into it is the plainest thing this system can say
+   * about a button that has been pressed and stayed down. It also keeps a bar
+   * of eight toggles from reading as eight primary buttons.
+   */
+  pressedBackground: colors.wellBackground,
+  pressedWell: shadow.inset,
+  // Between the members of one set: they answer to one value, so they stand
+  // closer than the clusters of a bar do.
+  groupGap: space[1],
+  // Between the clusters of a bar, and either side of the line between two.
+  barGap: space[2],
+  ring: colors.accent,
+  ringWidth: '2px',
+  // The family's one disabled value; the rules give the whole control 45%.
+  disabledOpacity: '0.45',
+});
+
+/**
+ * Re-declares the colour-valued tokens on the element carrying a forced
+ * palette; see `button.tokens.stylex.ts` for why a group declared only at the
+ * document root keeps the root palette inside a themed subtree.
+ */
+export const togglePaletteTheme = stylex.createTheme(toggle, {
+  label: colors.secondaryLabel,
+  hover: colors.hoverFill,
+  activeLabel: colors.label,
+  pressedBackground: colors.wellBackground,
+  pressedWell: shadow.inset,
+  ring: colors.accent,
+});
diff --git a/packages/ui/src/toggle/toggle.tsx b/packages/ui/src/toggle/toggle.tsx
new file mode 100644
index 000000000..dc0895478
--- /dev/null
+++ b/packages/ui/src/toggle/toggle.tsx
@@ -0,0 +1,93 @@
+import { Toggle as BaseToggle } from '@base-ui/react/toggle';
+import * as stylex from '@stylexjs/stylex';
+import { forwardRef } from 'react';
+import { appendClassName } from '../internal/class-name';
+import { useToggleSet, type ToggleShape, type ToggleSize } from './set';
+import { toggleSurface as surface } from './surface';
+
+export type { ToggleShape, ToggleSize } from './set';
+
+type BaseProps = BaseToggle.Props;
+
+export interface ToggleProps extends Omit<BaseProps, 'className'> {
+  /**
+   * How tall it is, and what it lines up with. Defaults to medium, or to
+   * whatever the set around it was told.
+   */
+  size?: ToggleSize;
+  /** A pill is for a filter a person scans a row of; the default is a control. */
+  shape?: ToggleShape;
+  /** Square at the size's height, holding one 16px glyph. */
+  icon?: boolean;
+  className?: string;
+}
+
+const SIZES = {
+  mini: surface.mini,
+  small: surface.small,
+  medium: surface.medium,
+  large: surface.large,
+} as const;
+
+const ICON_SIZES = {
+  mini: surface.iconMini,
+  small: surface.iconSmall,
+  medium: surface.iconMedium,
+  large: surface.iconLarge,
+} as const;
+
+/**
+ * A control that stays pressed.
+ *
+ * It is not a Switch, and what separates them is what each is for rather than
+ * how each looks. A Switch stores a value in a form: it takes a name, answers
+ * to a `Field.Root`, can be invalid, and is read as a setting. A Toggle says
+ * that an option is on **right now** — bold, wrapped lines, this filter — so it
+ * has no name, no validity and no message under it, and what it changes has
+ * usually already happened by the time a person looks away from it.
+ *
+ * Off it is a ghost Button, because that is what it is: a control with no fill,
+ * about the thing it acts on rather than the thing. On it sinks into the well,
+ * which is this ladder's way of saying something has gone down and stayed —
+ * and the reason it is not ink: ink is what a control that *already* sits in a
+ * well becomes when it is on, and this one rests on nothing at all.
+ *
+ * It renders a real `<button>` carrying `aria-pressed`, so the keyboard reaches
+ * it and a screen reader is told both what it is and whether it is on.
+ */
+export const Toggle = forwardRef<HTMLButtonElement, ToggleProps>(function Toggle(
+  { size, shape, icon = false, className, children, ...rest },
+  ref
+) {
+  const set = useToggleSet();
+  const resolvedSize = size ?? set?.size ?? 'medium';
+  const resolvedShape = shape ?? set?.shape ?? 'default';
+  const glyph = stylex.props(surface.glyph);
+  return (
+    <BaseToggle
+      ref={ref}
+      data-size={resolvedSize}
+      {...rest}
+      className={(state) =>
+        appendClassName(
+          stylex.props(
+            surface.base,
+            SIZES[resolvedSize],
+            icon && ICON_SIZES[resolvedSize],
+            resolvedShape === 'pill' && surface.pill,
+            state.pressed ? surface.pressed : surface.rest
+          ).className,
+          className
+        )
+      }
+    >
+      {icon ? (
+        <span className={glyph.className} style={glyph.style}>
+          {children}
+        </span>
+      ) : (
+        children
+      )}
+    </BaseToggle>
+  );
+});
diff --git a/packages/ui/src/toggle/toolbar.tsx b/packages/ui/src/toggle/toolbar.tsx
new file mode 100644
index 000000000..601dccb7d
--- /dev/null
+++ b/packages/ui/src/toggle/toolbar.tsx
@@ -0,0 +1,130 @@
+import { Toolbar as BaseToolbar } from '@base-ui/react/toolbar';
+import * as stylex from '@stylexjs/stylex';
+import { forwardRef, type ComponentProps } from 'react';
+import { appendClassName } from '../internal/class-name';
+import { separatorStyles } from '../separator/separator';
+import { toggleSurface as surface } from './surface';
+
+type RootBaseProps = ComponentProps<typeof BaseToolbar.Root>;
+type GroupBaseProps = ComponentProps<typeof BaseToolbar.Group>;
+type SeparatorBaseProps = ComponentProps<typeof BaseToolbar.Separator>;
+
+export interface ToolbarRootProps extends Omit<RootBaseProps, 'className'> {
+  className?: string;
+}
+export interface ToolbarGroupProps extends Omit<GroupBaseProps, 'className'> {
+  className?: string;
+}
+export interface ToolbarSeparatorProps extends Omit<SeparatorBaseProps, 'className'> {
+  className?: string;
+}
+
+/**
+ * A bar of controls.
+ *
+ * It draws nothing at all: no fill, no shadow, no radius, and not even the line
+ * a table draws. A bar is a row of controls on whatever surface the product
+ * already had there — a page, a card, the popup over a text selection — so a
+ * bar inside a panel is not a second panel inside one, and a surface that wants
+ * the bar to look like something gives it that itself.
+ *
+ * What it is for is the keyboard. A row of eight icon buttons is eight tab
+ * stops unless something says otherwise, and a person tabbing through a page
+ * should pass a bar rather than walk it. Base UI makes the bar one stop, gives
+ * the arrow keys the walking, and skips the controls that are disabled — which
+ * is the whole reason this part exists rather than a `div` with a gap.
+ */
+export const ToolbarRoot = forwardRef<HTMLDivElement, ToolbarRootProps>(function ToolbarRoot(
+  { className, orientation = 'horizontal', ...rest },
+  ref
+) {
+  const sx = stylex.props(surface.bar, orientation === 'vertical' && surface.barVertical);
+  return (
+    <BaseToolbar.Root
+      ref={ref}
+      orientation={orientation}
+      {...rest}
+      className={appendClassName(sx.className, className)}
+      style={sx.style}
+    />
+  );
+});
+
+/**
+ * A cluster inside a bar: controls that belong together, at the gap a set of
+ * toggles takes rather than the wider one between clusters. It says `group` to
+ * a screen reader, so a person hears where one cluster ends.
+ */
+export const ToolbarGroup = forwardRef<HTMLDivElement, ToolbarGroupProps>(function ToolbarGroup(
+  { className, ...rest },
+  ref
+) {
+  return (
+    <BaseToolbar.Group
+      ref={ref}
+      {...rest}
+      className={(state) =>
+        appendClassName(
+          stylex.props(
+            surface.barGroup,
+            state.orientation === 'vertical' && surface.barGroupVertical
+          ).className,
+          className
+        )
+      }
+    />
+  );
+});
+
+/**
+ * The line between two clusters of a bar — the same line `Separator` draws,
+ * because this system allows exactly one. It is the toolbar's own part rather
+ * than a `Separator` placed by hand for one reason: the orientation is the
+ * bar's turned ninety degrees, and a caller stating it twice is a caller who
+ * can get it wrong. It stretches to the row for the reason a vertical line
+ * always does here — a percentage would resolve against a height a flex row has
+ * not got.
+ */
+export const ToolbarSeparator = forwardRef<HTMLDivElement, ToolbarSeparatorProps>(
+  function ToolbarSeparator({ className, ...rest }, ref) {
+    return (
+      <BaseToolbar.Separator
+        ref={ref}
+        {...rest}
+        className={(state) =>
+          appendClassName(
+            stylex.props(
+              separatorStyles.base,
+              state.orientation === 'vertical'
+                ? separatorStyles.vertical
+                : separatorStyles.horizontal
+            ).className,
+            className
+          )
+        }
+      />
+    );
+  }
+);
+
+/**
+ * Toolbar: the bar, its clusters, the line between them, and the way a control
+ * joins the walk.
+ *
+ * `Toolbar.Button` is Base UI's, unstyled, the way every trigger in this
+ * package is: a bar holds whatever the surface already had there — a ghost
+ * `Button`, a `Toggle`, the trigger of a `Menu` — and registering it in the
+ * roving focus is all this part does. `render={<Button variant="ghost" icon/>}`
+ * is how one arrives.
+ *
+ * There is no `Toolbar.Input` or `Toolbar.Link` here. Base UI ships both, and
+ * neither has an appearance of this system's to add: an `Input` in a bar is
+ * this package's `Input`, and a link is a `Button variant="link"`. They can be
+ * added the day a surface needs one in the walk.
+ */
+export const Toolbar = {
+  Root: ToolbarRoot,
+  Button: BaseToolbar.Button,
+  Group: ToolbarGroup,
+  Separator: ToolbarSeparator,
+};
diff --git a/packages/ui/src/tokens/RULES.md b/packages/ui/src/tokens/RULES.md
index d59ec30db..c5853ea7c 100644
--- a/packages/ui/src/tokens/RULES.md
+++ b/packages/ui/src/tokens/RULES.md
@@ -320,6 +320,75 @@ exactly its own padding under `border-box` and overshoots by it under
 `content-box`. A caller migrating a panel that carried its own padding moves it
 inwards.
 
+## Pressed
+
+A control that stays pressed, a set of them, and the bar that holds them. One
+group, `toggle`, covers all three for the reason `disclosure` covers three
+layouts of one idea: what a pressed control looks like and how far apart two of
+them stand cannot become three decisions in three files.
+
+It is **not** the `field` group, and a Toggle is not a Switch. A Switch stores a
+value in a form: it takes a name, answers to a `Field.Root`, can be invalid, and
+is read as a setting. A Toggle says an option is on _right now_ — bold, wrapped
+lines, this filter — so it has no name, no validity and no message under it.
+
+| state    | what it is                                                                 |
+| -------- | -------------------------------------------------------------------------- |
+| off      | a ghost Button: no fill, `toggle.label`, `toggle.hover` under the pointer  |
+| on       | the well rung: `toggle.pressedBackground` under `toggle.pressedWell`       |
+| on hover | the rung mixed 4% toward the ink, the mix a secondary Button already uses  |
+| focus    | 2px `toggle.ring`, composed onto the pressed edge rather than replacing it |
+| disabled | `toggle.disabledOpacity` on the whole control, and the native attribute    |
+
+**On is the well, not ink**, and that is this family's one real decision. The
+rules give a stored state ink, and a toggle does store one — but ink is what a
+control that _already sits in a well_ becomes when it is on. A Switch's off
+state occupies the well, so on has to leave it; a Checkbox's empty box is the
+same. A toggle rests on nothing at all, so the well is still free, and sinking
+into it is the plainest thing this system can say about a button that went down
+and stayed there. It also keeps a bar of eight from reading as eight primary
+buttons, which is what ink would have made of it.
+
+A toggle does not bob either. The motion rules give a press `translateY(1px)`
+and a dropped highlight, and that is a raised thing going down and coming back;
+this one goes down and stays, so what moves is the surface under it.
+
+The ladder is `control`'s — 28, 32, 36, plus the 24 a file viewer's strip of
+actions needs — rather than `Button`'s. A Button and a Toggle in one bar line up
+because both read the same scale, not because one reads the other's group.
+
+### The set, and the strip
+
+A `ToggleGroup` is **not** a `Tabs` strip, and the two cannot be folded
+together. A strip picks what a person _sees_: it is one control, so it is a
+sunken track with one thing raised out of it and one pill sliding between the
+choices. A set stores what is _on_: two of its members can be pressed at once,
+which no sliding pill can say, so it has no track and each member sinks on its
+own. Asked for one choice out of several it still draws no track, because the
+same set with `multiple` on has to look like itself.
+
+The size and the shape are stated once, on the set, the way a tab strip states
+them for its tabs. A set too wide for its row wraps; its members keep their
+width there, because a toggle neither grows nor shrinks.
+
+### The bar
+
+A `Toolbar` draws **nothing at all**: no fill, no shadow, no radius, and not
+even the line a table draws. It is a row of controls on whatever surface the
+product already had there, so a bar inside a panel is not a second panel.
+
+What it is for is the keyboard. A row of eight icon buttons is eight tab stops
+unless something says otherwise, and a person tabbing through a page should pass
+a bar rather than walk it: the bar is one stop, the arrow keys do the walking,
+and a control that cannot be used is stepped over rather than stopped on. That
+is the whole reason it is a part rather than a `div` with a gap.
+
+Two gaps say what belongs with what. `toggle.groupGap` is between the members of
+one set or cluster; `toggle.barGap` is between the clusters, and either side of
+the line between two. The line is `Separator`'s, turned ninety degrees from the
+bar, and the bar states that rather than the caller — a horizontal bar cannot
+then end up with a horizontal line across it.
+
 ## Feedback
 
 What the system says back: what happened, and that it is still working. One
diff --git a/packages/ui/test/gallery.test.tsx b/packages/ui/test/gallery.test.tsx
index a67647cf9..54083fb23 100644
--- a/packages/ui/test/gallery.test.tsx
+++ b/packages/ui/test/gallery.test.tsx
@@ -11,6 +11,7 @@ import { kbd } from '../src/kbd/kbd.tokens.stylex';
 import { UiGallery } from '../src/gallery/gallery';
 import { popup } from '../src/popup/popup.tokens.stylex';
 import { table } from '../src/table/table.tokens.stylex';
+import { toggle } from '../src/toggle/toggle.tokens.stylex';
 import { tooltip } from '../src/tooltip/tooltip.tokens.stylex';
 import { surface } from '../src/popup/surface';
 import { forcedThemeClassNames } from '../src/theme/theme';
@@ -326,6 +327,26 @@ describe('UiGallery', () => {
     }
   });
 
+  test('shows a control that stays pressed, a set of them, and the bar holding them', () => {
+    // Nothing here is a stand-in. None of the three is portalled, so the board
+    // holds a real toggle in both of its states, a set in each of its two
+    // kinds, and a bar with the one line between its clusters.
+    expect(board).toContain('aria-pressed="true"');
+    expect(board).toContain('aria-pressed="false"');
+    expect(board).toContain('role="toolbar"');
+    // The 24px rung is this family's own: the ladder a Button is on starts at
+    // 28, and a toggle in a file viewer's strip of actions is smaller than that.
+    expect(board, "the toggle's 24px rung is missing from the board").toContain('mini \u00b7 24');
+    // The comparison the section exists to make, on one row: the same three
+    // choices as a set and as a Tabs strip, so a reader can see that only the
+    // strip — which is one control — has a track under it.
+    expect(board).toContain('Timeline');
+    expect(board).toContain('role="tablist"');
+    for (const name of tokenNames(toggle)) {
+      expect(board, `toggle.${name} is missing from the board`).toContain(`toggle.${name}`);
+    }
+  });
+
   test('renders one palette when asked for one', () => {
     const light = renderToStaticMarkup(<UiGallery palettes="light" />);
     expect(light).toContain('Lody Light');
diff --git a/packages/ui/test/toggle.test.tsx b/packages/ui/test/toggle.test.tsx
new file mode 100644
index 000000000..3a5bcefba
--- /dev/null
+++ b/packages/ui/test/toggle.test.tsx
@@ -0,0 +1,251 @@
+import * as stylex from '@stylexjs/stylex';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, test } from 'vitest';
+import { Button } from '../src/button/button';
+import { Separator } from '../src/separator/separator';
+import { Toggle } from '../src/toggle/toggle';
+import { ToggleGroup } from '../src/toggle/toggle-group';
+import { toggleSurface } from '../src/toggle/surface';
+import { Toolbar } from '../src/toggle/toolbar';
+import { all, classesOf, click, mount, one, press, step, until } from './dom';
+
+/** The classes one of the family's styles compiles to, for a state check. */
+function classesFor(style: (typeof toggleSurface)[keyof typeof toggleSurface]): string[] {
+  return (stylex.props(style).className ?? '').split(' ').filter(Boolean);
+}
+
+function toggles(): HTMLButtonElement[] {
+  return all('button[aria-pressed]') as HTMLButtonElement[];
+}
+
+describe('Toggle', () => {
+  test('it is a button that says whether it is on', async () => {
+    // A toggle is a real `<button>` carrying `aria-pressed`, so the keyboard
+    // reaches it and a screen reader is told both what it is and its state —
+    // which is the whole difference between this and a div a surface colours.
+    const mounted = await mount(<Toggle>Bold</Toggle>);
+    const button = one('button');
+    expect(button.tagName).toBe('BUTTON');
+    expect(button.getAttribute('aria-pressed')).toBe('false');
+    await click(button);
+    expect(button.getAttribute('aria-pressed')).toBe('true');
+    await mounted.unmount();
+  });
+
+  test('a controlled toggle reports the press and leaves the state to its caller', async () => {
+    const seen: boolean[] = [];
+    const mounted = await mount(
+      <Toggle pressed={false} onPressedChange={(next) => seen.push(next)}>
+        Bold
+      </Toggle>
+    );
+    const button = one('button');
+    await click(button);
+    expect(seen).toEqual([true]);
+    // The caller never changed `pressed`, so the control did not change either.
+    expect(button.getAttribute('aria-pressed')).toBe('false');
+    await mounted.unmount();
+  });
+
+  test('off is a ghost control and on is the well, which is the state pair', async () => {
+    // The two states are the whole design decision this part makes: off has no
+    // fill at all, and on sinks into the well rather than filling with ink,
+    // because ink is what a control that already sits in a well becomes.
+    const mounted = await mount(<Toggle>Wrap lines</Toggle>);
+    const button = one('button');
+    for (const name of classesFor(toggleSurface.rest)) {
+      expect(classesOf(button), `an off toggle is missing ${name}`).toContain(name);
+    }
+    await click(button);
+    for (const name of classesFor(toggleSurface.pressed)) {
+      expect(classesOf(button), `an on toggle is missing ${name}`).toContain(name);
+    }
+    for (const name of classesFor(toggleSurface.rest)) {
+      expect(classesOf(button), `an on toggle still carries ${name}`).not.toContain(name);
+    }
+    await mounted.unmount();
+  });
+
+  test('an icon-only toggle draws the box its glyph fills', () => {
+    // This package's icons state their size as 100% of whatever holds them and
+    // StyleX has no descendant selector, so the control draws the 16px box —
+    // the same contract an icon-only Button has.
+    const html = renderToStaticMarkup(
+      <Toggle icon aria-label="Bold">
+        <svg />
+      </Toggle>
+    );
+    for (const name of classesFor(toggleSurface.glyph)) {
+      expect(html, `the glyph box is missing ${name}`).toContain(name);
+    }
+  });
+
+  test('a disabled toggle is disabled to the platform, not just dimmed', () => {
+    const html = renderToStaticMarkup(<Toggle disabled>Bold</Toggle>);
+    expect(html).toContain('disabled=""');
+  });
+});
+
+describe('ToggleGroup', () => {
+  test('the set states the size once, and a member may still state its own', () => {
+    // A member's height follows from the set's, so a surface states one fact
+    // rather than one per member — and two of them cannot disagree by accident.
+    const html = renderToStaticMarkup(
+      <ToggleGroup size="mini">
+        <Toggle value="a">A</Toggle>
+        <Toggle value="b" size="large">
+          B
+        </Toggle>
+      </ToggleGroup>
+    );
+    expect(html).toContain('data-size="mini"');
+    expect(html).toContain('data-size="large"');
+  });
+
+  test('one out of several: taking a second releases the first', async () => {
+    const taken: string[][] = [];
+    const mounted = await mount(
+      <ToggleGroup defaultValue={['list']} onValueChange={(next) => taken.push(next)}>
+        <Toggle value="list">List</Toggle>
+        <Toggle value="board">Board</Toggle>
+      </ToggleGroup>
+    );
+    const [list, board] = toggles();
+    expect(list.getAttribute('aria-pressed')).toBe('true');
+    await click(board);
+    expect(board.getAttribute('aria-pressed')).toBe('true');
+    expect(list.getAttribute('aria-pressed')).toBe('false');
+    expect(taken.at(-1)).toEqual(['board']);
+    await mounted.unmount();
+  });
+
+  test('several at once: the set holds every pressed member', async () => {
+    // This is the state a Tabs strip cannot describe, and the reason this is a
+    // different part rather than a strip without its track: two members are on
+    // at the same time, and no single sliding pill can stand for both.
+    const mounted = await mount(
+      <ToggleGroup multiple defaultValue={['status']}>
+        <Toggle value="status">Status</Toggle>
+        <Toggle value="assignee">Assignee</Toggle>
+      </ToggleGroup>
+    );
+    const [status, assignee] = toggles();
+    await click(assignee);
+    expect(status.getAttribute('aria-pressed')).toBe('true');
+    expect(assignee.getAttribute('aria-pressed')).toBe('true');
+    await mounted.unmount();
+  });
+
+  test('the set is one tab stop, and the arrow keys walk it', async () => {
+    const mounted = await mount(
+      <ToggleGroup multiple>
+        <Toggle value="a">A</Toggle>
+        <Toggle value="b">B</Toggle>
+        <Toggle value="c">C</Toggle>
+      </ToggleGroup>
+    );
+    const members = toggles();
+    // One stop: a person tabbing through a page passes the set rather than
+    // walking it, which is what makes a set of eight bearable.
+    expect(members.filter((member) => member.tabIndex === 0)).toHaveLength(1);
+    await step(() => members[0].focus());
+    await press('ArrowRight');
+    await until(() => document.activeElement === members[1], 'the arrow key to move the focus');
+    await mounted.unmount();
+  });
+});
+
+describe('Toolbar', () => {
+  test('it says what it is, and draws nothing of its own', async () => {
+    const mounted = await mount(
+      <Toolbar.Root aria-label="Format">
+        <Toolbar.Button render={<Toggle icon aria-label="Bold" />}>
+          <svg />
+        </Toolbar.Button>
+      </Toolbar.Root>
+    );
+    const bar = one('[role="toolbar"]');
+    expect(bar.getAttribute('aria-orientation')).toBe('horizontal');
+    // The bar carries the row and the gap, and no fill, shadow or radius: what
+    // it stands on is the surface the product already had there.
+    expect(classesOf(bar)).toEqual(classesFor(toggleSurface.bar));
+    // A control joins the walk through `render`, and what it was given to hold
+    // arrives inside the box the control draws — the composition every caller
+    // writes, and the one place the two halves could fail to meet.
+    const glyph = one('[role="toolbar"] button > span');
+    for (const name of classesFor(toggleSurface.glyph)) {
+      expect(classesOf(glyph), `a composed toggle's glyph box is missing ${name}`).toContain(name);
+    }
+    expect(glyph.querySelector('svg')).not.toBeNull();
+    await mounted.unmount();
+  });
+
+  test('a toggle in a bar is still a toggle, and the bar is still one stop', async () => {
+    const mounted = await mount(
+      <Toolbar.Root aria-label="Format">
+        <Toolbar.Button render={<Toggle icon aria-label="Bold" />}>
+          <svg />
+        </Toolbar.Button>
+        <Toolbar.Button render={<Toggle icon aria-label="Italic" />}>
+          <svg />
+        </Toolbar.Button>
+        <Toolbar.Separator />
+        <Toolbar.Button render={<Button variant="ghost" icon aria-label="Quote" />}>
+          <svg />
+        </Toolbar.Button>
+      </Toolbar.Root>
+    );
+    const items = all('[role="toolbar"] button');
+    expect(items).toHaveLength(3);
+    expect(items.filter((item) => item.tabIndex === 0)).toHaveLength(1);
+    const bold = items[0];
+    expect(bold.getAttribute('aria-pressed')).toBe('false');
+    await click(bold);
+    expect(bold.getAttribute('aria-pressed')).toBe('true');
+    await step(() => bold.focus());
+    await press('ArrowRight');
+    await until(() => document.activeElement === items[1], 'the arrow key to walk the bar');
+    await mounted.unmount();
+  });
+
+  test('a control the bar cannot use is stepped over rather than stopped on', async () => {
+    const mounted = await mount(
+      <Toolbar.Root aria-label="Format">
+        <Toolbar.Button render={<Toggle icon aria-label="Bold" />}>
+          <svg />
+        </Toolbar.Button>
+        <Toolbar.Button disabled focusableWhenDisabled={false} render={<Button icon />}>
+          <svg />
+        </Toolbar.Button>
+        <Toolbar.Button render={<Toggle icon aria-label="Code" />}>
+          <svg />
+        </Toolbar.Button>
+      </Toolbar.Root>
+    );
+    const items = all('[role="toolbar"] button');
+    await step(() => items[0].focus());
+    await press('ArrowRight');
+    await until(
+      () => document.activeElement === items[2],
+      'the disabled control to be stepped over'
+    );
+    await mounted.unmount();
+  });
+
+  test("the bar's line is the one line this system allows, turned ninety degrees", () => {
+    // The orientation is the bar's turned, and it is the part's rather than a
+    // caller's so that a horizontal bar cannot end up with a horizontal line
+    // across it. What it draws is the very same hairline `Separator` draws.
+    const html = renderToStaticMarkup(
+      <Toolbar.Root>
+        <Toolbar.Separator />
+      </Toolbar.Root>
+    );
+    expect(html).toContain('role="separator"');
+    expect(html).toContain('aria-orientation="vertical"');
+    const line = renderToStaticMarkup(<Separator orientation="vertical" />);
+    for (const name of (/class="([^"]*)"/.exec(line)?.[1] ?? '').split(' ').filter(Boolean)) {
+      expect(html, `the bar's line is missing ${name}`).toContain(name);
+    }
+  });
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 77c0515a0..8e8d19f39 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -987,9 +987,6 @@ importers:
       '@radix-ui/react-tabs':
         specifier: ^1.0.4
         version: 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
-      '@radix-ui/react-toggle':
-        specifier: ^1.1.9
-        version: 1.1.10(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
       '@radix-ui/react-tooltip':
         specifier: ^1.2.9
         version: 1.2.9(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
@@ -4687,19 +4684,6 @@ packages:
       '@types/react-dom':
         optional: true
 
-  '@radix-ui/react-toggle@1.1.10':
-    resolution: {integrity: sha512-lS1odchhFTeZv3xwHH31YPObmJn8gOg7Lq12inrr0+BH/l3Tsq32VfjqH1oh80ARM3mlkfMic15n0kg4sD1poQ==}
-    peerDependencies:
-      '@types/react': '*'
-      '@types/react-dom': '*'
-      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      '@types/react-dom':
-        optional: true
-
   '@radix-ui/react-toggle@1.1.12':
     resolution: {integrity: sha512-AsAVsYNZIlRBsci7BhE+QyQeKd1h6TffJYt+lF0QQkd5OpQ3klfIByPsCb4G0h/Fq6PJwh1FYNluzBFYzhk4+w==}
     peerDependencies:
@@ -16346,17 +16330,6 @@ snapshots:
       '@types/react': 19.2.17
       '@types/react-dom': 19.2.3(@types/react@19.2.17)
 
-  '@radix-ui/react-toggle@1.1.10(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)':
-    dependencies:
-      '@radix-ui/primitive': 1.1.3
-      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
-      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.17)(react@19.2.0)
-      react: 19.2.0
-      react-dom: 19.2.0(react@19.2.0)
-    optionalDependencies:
-      '@types/react': 19.2.17
-      '@types/react-dom': 19.2.3(@types/react@19.2.17)
-
   '@radix-ui/react-toggle@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)':
     dependencies:
       '@radix-ui/primitive': 1.1.4
diff --git a/specs/ui-primitives.md b/specs/ui-primitives.md
index e14735fcf..2243bd391 100644
--- a/specs/ui-primitives.md
+++ b/specs/ui-primitives.md
@@ -132,6 +132,44 @@ is opened by whatever the surface already had there. What opens is animated from
 its own measured height, so what it holds keeps its spacing on something inside
 it rather than on the part being measured.
 
+A person may also leave a control pressed. That is not the control that stores a
+value in a form — the one with a name, a place in a field and the ability to be
+wrong — but a statement that an option is on at this moment: the words in front
+of them are bold, the long lines are wrapped, this filter is being applied. It
+is a button in every other way, so the keyboard reaches it and a person who
+cannot see it is told both what kind of control it is and whether it is on.
+
+What it looks like when it is on follows from where it rests. The system fills a
+control with ink when what it holds is stored, and that is right for the ones
+whose resting appearance already occupies the sunken place this system gives to
+anything you may put something into: on has to be somewhere else, so it is ink.
+A control that rests on nothing has that place free, so it goes down into it and
+stays there — which is also what keeps a row of eight of them from reading as
+eight of the most important thing on the screen. It goes down and stays rather
+than dipping and coming back, which is what this system's raised controls do
+when they are pressed.
+
+Several of them may answer to one value, and that is a different thing from the
+strip of choices above, not an arrangement of it. The strip picks what a person
+sees, so it can be a single control with one mark moving across it; a set of
+these stores what is on, and two of its members can be on at once, which no
+single moving mark can say. So the set has no track under it and each member
+goes down on its own — including when the surface asks for one choice out of
+several, because the same set with several allowed has to look like itself. How
+tall the members are and what shape they take is stated once, on the set.
+
+A row of controls is itself something the system names, and what it is for is
+the keyboard rather than the eye: it draws nothing at all — not even the line a
+table is allowed — because it is a row of controls on whatever the surface
+already was. A row of eight things a person can press is eight stops on the way
+past it unless something says otherwise, so the row is one stop and the arrow
+keys walk it, stepping over what cannot be used rather than stopping there. Two
+distances say what belongs with what: one between the controls of a cluster, a
+wider one between clusters and either side of the line that divides them. That
+line is the one line this system allows, turned across the row, and the row
+states that rather than the surface — a row laid out one way cannot then be
+divided the other.
+
 The system also speaks back. What it says is either what happened or that it is
 still working, and those are one family rather than five components. A message
 is the same block wherever it appears — a mark that names what kind of message
@@ -362,3 +400,7 @@ The avatar whose rung picks its own letters, the key cap, and the component
 token group that carries a surface's inversion into what is standing on it are
 recorded in the
 [UI avatar and kbd note](../.agents/notes/implemented/feature/2026-09-13-ui-avatar-kbd.md).
+The sunken place a pressed control goes into rather than filling with ink, the
+set of them that is not the strip of choices, and the row that draws nothing and
+exists for the keyboard are recorded in the
+[UI toggle and toolbar note](../.agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md).

From 147220fc3d1f62ef66ae8c9c4833201065d4bad2 Mon Sep 17 00:00:00 2001
From: Wibus <wibus_wee@outlook.com>
Date: Tue, 15 Sep 2026 09:06:05 +0000
Subject: [PATCH 2/2] docs(ui): link the toggle family note to its PR

Model: claude-opus-5[1m]
---
 .../notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md    | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md b/.agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md
index fe107c02d..c483d21a6 100644
--- a/.agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md
+++ b/.agents/notes/implemented/feature/2026-09-15-ui-toggle-toolbar.md
@@ -2,6 +2,7 @@
 
 Status: implemented
 Translation: pending
+PR: https://github.com/LodyAI/Lody/pull/727
 
 ## Abstract