From c65314bdee1311aa27c0e11af07fdcd9bb6c270a Mon Sep 17 00:00:00 2001
From: Ivan Banov <ivanbanov@gmail.com>
Date: Sat, 18 Jul 2026 10:29:11 +0200
Subject: [PATCH 1/2] feat: add the Switch primitive

Adds @dunky.dev/switch (core machine) and @dunky.dev/react-switch
(React binding). Anatomy: Switch root owning checked state, with
Control (switch role) wrapping a visual Thumb, plus a Label whose
press also toggles.

A binary on/off control per the WAI-ARIA APG switch pattern:
controlled/uncontrolled checked state, press/Space toggles, disabled
gates user intent in the machine, and every part carries data-state.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .changeset/switch.md                          |  23 +++
 packages/core/switch/README.md                |  27 +++
 packages/core/switch/SPEC.md                  | 111 +++++++++++
 packages/core/switch/package.json             |  40 ++++
 packages/core/switch/src/connect.ts           | 100 ++++++++++
 packages/core/switch/src/index.ts             |  11 +
 packages/core/switch/src/machine.ts           |  64 ++++++
 packages/core/switch/src/types.ts             |  60 ++++++
 packages/core/switch/tests/machine.test.ts    | 188 ++++++++++++++++++
 packages/react/switch/README.md               |  32 +++
 packages/react/switch/SPEC.md                 |  77 +++++++
 packages/react/switch/package.json            |  51 +++++
 packages/react/switch/src/context.ts          |  19 ++
 packages/react/switch/src/effects.ts          |  31 +++
 packages/react/switch/src/index.ts            |   8 +
 packages/react/switch/src/switch.tsx          |  96 +++++++++
 packages/react/switch/src/use-switch.ts       |  17 ++
 .../react/switch/stories/switch.stories.tsx   | 127 ++++++++++++
 packages/react/switch/tests/switch.test.tsx   | 146 ++++++++++++++
 pnpm-lock.yaml                                |  37 ++++
 tsconfig.json                                 |   2 +
 tsdown.config.ts                              |   2 +
 22 files changed, 1269 insertions(+)
 create mode 100644 .changeset/switch.md
 create mode 100644 packages/core/switch/README.md
 create mode 100644 packages/core/switch/SPEC.md
 create mode 100644 packages/core/switch/package.json
 create mode 100644 packages/core/switch/src/connect.ts
 create mode 100644 packages/core/switch/src/index.ts
 create mode 100644 packages/core/switch/src/machine.ts
 create mode 100644 packages/core/switch/src/types.ts
 create mode 100644 packages/core/switch/tests/machine.test.ts
 create mode 100644 packages/react/switch/README.md
 create mode 100644 packages/react/switch/SPEC.md
 create mode 100644 packages/react/switch/package.json
 create mode 100644 packages/react/switch/src/context.ts
 create mode 100644 packages/react/switch/src/effects.ts
 create mode 100644 packages/react/switch/src/index.ts
 create mode 100644 packages/react/switch/src/switch.tsx
 create mode 100644 packages/react/switch/src/use-switch.ts
 create mode 100644 packages/react/switch/stories/switch.stories.tsx
 create mode 100644 packages/react/switch/tests/switch.test.tsx

diff --git a/.changeset/switch.md b/.changeset/switch.md
new file mode 100644
index 0000000..2f452dd
--- /dev/null
+++ b/.changeset/switch.md
@@ -0,0 +1,23 @@
+---
+'@dunky.dev/switch': minor
+'@dunky.dev/react-switch': minor
+---
+
+Add the Switch primitive — a binary on/off control following the WAI-ARIA APG
+pattern, shipped as an agnostic core (`@dunky.dev/switch`) plus a React binding
+(`@dunky.dev/react-switch`).
+
+```tsx
+import { Switch } from '@dunky.dev/react-switch'
+
+function App() {
+  return (
+    <Switch onCheckedChange={console.log}>
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Switch.Label>Airplane mode</Switch.Label>
+    </Switch>
+  )
+}
+```
diff --git a/packages/core/switch/README.md b/packages/core/switch/README.md
new file mode 100644
index 0000000..6a5d3a3
--- /dev/null
+++ b/packages/core/switch/README.md
@@ -0,0 +1,27 @@
+# @dunky.dev/switch
+
+The framework-agnostic switch interaction, modeled as a state machine on
+`@dunky.dev/state-machine`. Pure logic — no substrate, no framework. Consumers
+pair it with a substrate driver rather than driving the machine directly.
+
+The behavior contract — scenarios, guarantees, driver obligations — lives in
+[SPEC.md](./SPEC.md).
+
+## Install
+
+```sh
+npm install @dunky.dev/switch
+```
+
+## Usage
+
+```ts
+import { machine, connector } from '@dunky.dev/state-machine'
+import { switchMachine, switchConnect } from '@dunky.dev/switch'
+
+// `id` is substrate-minted (SSR-safe); the connect derives the per-part ids.
+const service = machine(switchMachine({ ...options, id: 'my-switch' }))
+connector(service, switchConnect, options) // wires the consumer callbacks
+service.start()
+service.send({ type: 'toggle' })
+```
diff --git a/packages/core/switch/SPEC.md b/packages/core/switch/SPEC.md
new file mode 100644
index 0000000..7ead151
--- /dev/null
+++ b/packages/core/switch/SPEC.md
@@ -0,0 +1,111 @@
+# SPEC / Switch
+
+## Reference
+
+- **W3C pattern**: [APG Switch](https://www.w3.org/WAI/ARIA/apg/patterns/switch/),
+  over the normative
+  [WAI-ARIA 1.2 `switch`](https://www.w3.org/TR/wai-aria-1.2/#switch) role
+  definition.
+- **State machine**: built on `@dunky.dev/state-machine`.
+- **Prior art**: API shape modeled on the Radix, Base UI, and Ark switches.
+
+## Overview
+
+A switch is a binary control that turns a setting on or off, taking effect
+immediately — airplane mode, notifications, dark theme. Unlike a checkbox it
+never collects a choice for later submission and never has a mixed state: it
+is always exactly on or off.
+
+## Anatomy
+
+```
+<Switch>          — root; owns checked state, renders nothing of its own
+  |_ <Control>    — the interactive element: carries the switch role and checked state
+  |  |_ <Thumb>   — the knob; purely visual, styled off data-state
+  |_ <Label>      — names the control; pressing it toggles
+```
+
+## Behavior
+
+Using the switch is a walkthrough of intent, not a prop list:
+
+- The **root** owns the checked state, exposed controlled and uncontrolled,
+  mirroring native patterns: an uncontrolled switch can be seeded checked,
+  while a controlled consumer drives it from outside — and every toggle intent
+  is reported back so the consumer stays in sync. Controlled is that sync
+  contract, not a hard gate: a toggle intent takes effect immediately and is
+  reported; the `checked` prop re-applies only when its value changes.
+- The **control** is the single interactive element. Pressing it toggles; it
+  carries the `switch` role and the checked state to assistive tech.
+- The **thumb** is purely visual — the knob consumers animate between the two
+  ends of the track. It carries no behavior, only the styling hooks.
+- The **label** names the control. Pressing it toggles too, matching native
+  label ergonomics. The control's ARIA name follows what is actually rendered
+  — an omitted Label never leaves a dangling reference.
+- **Disabled** blocks toggling — from the control and the label alike — and is
+  exposed to assistive tech and styling. It gates user intent only: a
+  controlled or programmatic change still applies while disabled, so the
+  consumer's state never desyncs.
+
+## States
+
+| State       | Behavior                                                                 |
+| ----------- | ------------------------------------------------------------------------ |
+| `unchecked` | The setting is off. A toggle intent moves to `checked` unless disabled.  |
+| `checked`   | The setting is on. A toggle intent moves to `unchecked` unless disabled. |
+
+### Disabled
+
+Disabled is a flag over both states, not a third state: the switch keeps its
+checked value while disabled and resumes toggling when re-enabled. The
+decision to block lives in the machine, so every substrate inherits it — a
+part's press binding never second-guesses it.
+
+### Label presence
+
+A Label can appear or disappear at any time — the ARIA name relationship on
+the Control always follows what is actually rendered.
+
+## Accessibility
+
+Per APG Switch:
+
+- **Role**: the control is `switch`, with `aria-checked` always present and
+  mirroring the state — `true` or `false`, never mixed (the switch is binary).
+- **Name**: the control is labelled by the rendered Label, or by an accessible
+  label the consumer puts on the control in the no-label case. One of the two
+  must be present.
+- **Keyboard**: the control is focusable and Space toggles (Enter as well on a
+  substrate whose native control activates on Enter). Substrates deliver this
+  by rendering a natively activatable element — activation stays a single
+  "press" intent.
+- **Disabled**: exposed as `aria-disabled`; every part also carries
+  `data-disabled` for styling.
+- **State styling**: every part carries `data-state="checked" | "unchecked"` —
+  the consumer's styling and animation hook.
+
+## Constraints
+
+- The control must always resolve an accessible name — from a rendered Label
+  or a consumer-supplied label — never neither.
+- ARIA labelled-by must only reference elements that are actually rendered.
+- `aria-checked` always mirrors the machine state; it is never `mixed`.
+- Every checked ⇄ unchecked transition, whatever its cause, is reported to
+  the consumer.
+- While disabled, no user intent changes the state; controlled and
+  programmatic changes still apply.
+- Form integration (name/value, hidden input, form reset) is out of scope for
+  v0 — the switch is a pure setting control.
+
+## Design
+
+- **The Label is not a substrate-native `<label>`.** A native label forwards
+  activation to its control, which would double-fire next to the part's own
+  press-to-toggle binding — and not every substrate has a label element. The
+  Label part instead carries its own press binding (toggling through the same
+  machine intent, so the disabled guard applies) and the name flows through
+  `aria-labelledby`.
+- **Toggle is one event, gated in the machine.** Control press, label press,
+  and keyboard activation all send the same `toggle` intent; the disabled
+  guard decides. Programmatic changes (`check` / `uncheck`) bypass the guard
+  on purpose — see Disabled under States.
diff --git a/packages/core/switch/package.json b/packages/core/switch/package.json
new file mode 100644
index 0000000..da38e86
--- /dev/null
+++ b/packages/core/switch/package.json
@@ -0,0 +1,40 @@
+{
+  "name": "@dunky.dev/switch",
+  "version": "0.0.0",
+  "description": "Framework-agnostic switch interaction, modeled as a state machine.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dunky-dev/ui.git",
+    "directory": "packages/core/switch"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown"
+  },
+  "dependencies": {
+    "@dunky.dev/state-machine": "^0.1.0",
+    "@dunky.dev/state-machine-bindings": "^0.1.0"
+  }
+}
diff --git a/packages/core/switch/src/connect.ts b/packages/core/switch/src/connect.ts
new file mode 100644
index 0000000..78a3541
--- /dev/null
+++ b/packages/core/switch/src/connect.ts
@@ -0,0 +1,100 @@
+import { makeReaction, type Connect } from '@dunky.dev/state-machine'
+import type { AttrBindings, EventBindings } from '@dunky.dev/state-machine-bindings'
+import type {
+  SwitchContext,
+  SwitchIds,
+  SwitchMachineEvent,
+  SwitchOptions,
+  SwitchStateName,
+} from './types'
+
+// The bindings a part carries, drawn from the shared agnostic vocabulary; the
+// index signature keeps parts assignable to the loose shape each substrate's
+// normalize() accepts. `data-state` is the styling/animation hook;
+// `data-disabled` is present (empty) while disabled, absent otherwise.
+export type SwitchPartBindings = EventBindings &
+  AttrBindings & { 'data-state'?: SwitchStateName; 'data-disabled'?: string } & Record<
+    string,
+    unknown
+  >
+
+// The cross-part ids derive from the one base id, so the Control's
+// aria-labelledby and the Label's id always agree.
+function switchIds(id: string): SwitchIds {
+  return { control: `${id}-control`, label: `${id}-label` }
+}
+
+/** The view-facing surface a driver reads from the running switch machine. */
+export interface SwitchApi {
+  checked: boolean
+  disabled: boolean
+  ids: SwitchIds
+  setChecked: (checked: boolean) => void
+  parts: {
+    control: SwitchPartBindings
+    thumb: SwitchPartBindings
+    label: SwitchPartBindings
+  }
+}
+
+export const switchConnect: Connect<
+  SwitchStateName,
+  SwitchContext,
+  SwitchMachineEvent,
+  SwitchOptions,
+  SwitchApi
+> = ({ state, context, send }) => {
+  const checked = state === 'checked'
+  const dataState: SwitchStateName = checked ? 'checked' : 'unchecked'
+  const dataDisabled = context.disabled ? '' : undefined
+  const ids = switchIds(context.id)
+
+  // Control press and label press are the same user intent; whether it flips
+  // the state is gated in the machine (disabled).
+  const toggle = (): void => send({ type: 'toggle' })
+
+  return {
+    checked,
+    disabled: context.disabled,
+    ids,
+    setChecked(next) {
+      if (checked === next) return
+      send({ type: next ? 'check' : 'uncheck' })
+    },
+    parts: {
+      control: {
+        role: 'switch',
+        id: ids.control,
+        // Always present, true or false — the switch is binary, never mixed.
+        checked,
+        disabled: context.disabled || undefined,
+        // A dangling aria-labelledby id is an a11y defect — only while rendered.
+        labelledBy: context.parts.label ? ids.label : undefined,
+        'data-state': dataState,
+        'data-disabled': dataDisabled,
+        onPress: toggle,
+      },
+      thumb: {
+        'data-state': dataState,
+        'data-disabled': dataDisabled,
+      },
+      label: {
+        id: ids.label,
+        'data-state': dataState,
+        'data-disabled': dataDisabled,
+        onPress: toggle,
+      },
+    },
+  }
+}
+
+const reaction = makeReaction<SwitchStateName, SwitchContext, SwitchMachineEvent, SwitchOptions>()
+
+// One reaction per consumer callback. Reactions fire in registration order within
+// a single setContext — that order is the callback-order contract. See SPEC.md.
+switchConnect.reactions = [
+  reaction(
+    m => m.matches('checked'),
+    (checked, props) => props.onCheckedChange?.(checked),
+  ),
+]
diff --git a/packages/core/switch/src/index.ts b/packages/core/switch/src/index.ts
new file mode 100644
index 0000000..4839282
--- /dev/null
+++ b/packages/core/switch/src/index.ts
@@ -0,0 +1,11 @@
+export { switchMachine, type SwitchMachine } from './machine'
+export { switchConnect, type SwitchApi, type SwitchPartBindings } from './connect'
+export type {
+  SwitchCallbacks,
+  SwitchContext,
+  SwitchIds,
+  SwitchMachineEvent,
+  SwitchOptions,
+  SwitchPart,
+  SwitchStateName,
+} from './types'
diff --git a/packages/core/switch/src/machine.ts b/packages/core/switch/src/machine.ts
new file mode 100644
index 0000000..608cc44
--- /dev/null
+++ b/packages/core/switch/src/machine.ts
@@ -0,0 +1,64 @@
+import {
+  setup,
+  type Action,
+  type Guard,
+  type Machine,
+  type TransitionConfig,
+} from '@dunky.dev/state-machine'
+import type { SwitchContext, SwitchMachineEvent, SwitchOptions, SwitchStateName } from './types'
+
+/** The running switch machine — what a substrate holds and sends events to. */
+export type SwitchMachine = Machine<SwitchStateName, SwitchContext, SwitchMachineEvent>
+
+type SwitchAction = Action<SwitchContext, SwitchMachineEvent>
+type SwitchGuard = Guard<SwitchContext, SwitchMachineEvent>
+
+// Disabled gates user intent (`toggle`) only — programmatic `check`/`uncheck`
+// stay open so a controlled consumer never desyncs while disabled.
+const canToggle: SwitchGuard = ({ context }) => !context.disabled
+
+const setDisabled: SwitchAction = ({ event, setContext }) => {
+  if (event.type !== 'set.disabled') return
+  setContext({ disabled: event.disabled })
+}
+
+const setPartPresence: SwitchAction = ({ event, context, setContext }) => {
+  if (event.type !== 'part.presence') return
+  setContext({ parts: { ...context.parts, [event.part]: event.present } })
+}
+
+export function switchMachine(
+  options: SwitchOptions,
+): TransitionConfig<SwitchStateName, SwitchContext, SwitchMachineEvent> {
+  // Annotated so createMachine infers Context as SwitchContext, not the narrowed literal.
+  const context: SwitchContext = {
+    disabled: options.disabled ?? false,
+    // The substrate supplies a unique id; `switch` is only a bare fallback.
+    id: options.id ?? 'switch',
+    parts: { label: false },
+  }
+
+  return setup.as<SwitchContext, SwitchMachineEvent>().createMachine({
+    initial: (options.checked ?? options.defaultChecked) === true ? 'checked' : 'unchecked',
+    context,
+    // Top-level: the disabled flag and part presence are settable from any state.
+    on: {
+      'set.disabled': { actions: setDisabled },
+      'part.presence': { actions: setPartPresence },
+    },
+    states: {
+      unchecked: {
+        on: {
+          toggle: { target: 'checked', guard: canToggle },
+          check: { target: 'checked' },
+        },
+      },
+      checked: {
+        on: {
+          toggle: { target: 'unchecked', guard: canToggle },
+          uncheck: { target: 'unchecked' },
+        },
+      },
+    },
+  })
+}
diff --git a/packages/core/switch/src/types.ts b/packages/core/switch/src/types.ts
new file mode 100644
index 0000000..ae4438b
--- /dev/null
+++ b/packages/core/switch/src/types.ts
@@ -0,0 +1,60 @@
+// Public + machine-facing types for the framework-agnostic switch primitive.
+// The state machine is substrate-free: all event reading lives in a
+// per-substrate driver.
+
+export type SwitchStateName = 'checked' | 'unchecked'
+
+/** The parts whose presence drives the ARIA relationships on Control. */
+export type SwitchPart = 'label'
+
+/**
+ * The cross-part ids, derived from the one `id` on context: the label's id
+ * renders on the Label and as `aria-labelledby` on the Control, and the
+ * connect wires both sides.
+ */
+export interface SwitchIds {
+  control: string
+  label: string
+}
+
+export interface SwitchContext {
+  disabled: boolean
+  // The base id (substrate-minted, SSR-safe); the connect derives the per-part
+  // ids from it.
+  id: string
+  // Which optional parts are currently present, so Control only references the
+  // ones actually rendered.
+  parts: Record<SwitchPart, boolean>
+}
+
+// `toggle` is the user intent (gated on disabled in the machine);
+// `check`/`uncheck` are programmatic and bypass the gate so a controlled
+// consumer can sync while disabled.
+export type SwitchMachineEvent =
+  | { type: 'toggle' }
+  | { type: 'check' }
+  | { type: 'uncheck' }
+  | { type: 'set.disabled'; disabled: boolean }
+  | { type: 'part.presence'; part: SwitchPart; present: boolean }
+
+export interface SwitchCallbacks {
+  /** Fired on every checked/unchecked transition with the new value. */
+  onCheckedChange?: (checked: boolean) => void
+}
+
+/**
+ * The agnostic switch options — the behavior a consumer configures. A
+ * substrate's props extend this with its own concerns (e.g. `children`).
+ */
+export interface SwitchOptions extends SwitchCallbacks {
+  /** Base id for the switch's parts; the substrate supplies a unique, SSR-safe
+   * one. The per-part ids (control/label) are derived from it. */
+  id?: string
+  /** Controlled checked state; every toggle intent is reported through `onCheckedChange`. */
+  checked?: boolean
+  /** Initial checked state for the uncontrolled switch. @default false */
+  defaultChecked?: boolean
+  /** Blocks toggling; the checked state is kept and stays consumer-settable.
+   * @default false */
+  disabled?: boolean
+}
diff --git a/packages/core/switch/tests/machine.test.ts b/packages/core/switch/tests/machine.test.ts
new file mode 100644
index 0000000..24d729f
--- /dev/null
+++ b/packages/core/switch/tests/machine.test.ts
@@ -0,0 +1,188 @@
+// The agnostic core of the Switch — machine + connect, no DOM, no framework.
+import { describe, expect, it, vi } from 'vitest'
+import { connector, machine, type Connector, type Machine } from '@dunky.dev/state-machine'
+import { switchMachine, switchConnect } from '@dunky.dev/switch'
+import type {
+  SwitchApi,
+  SwitchContext,
+  SwitchIds,
+  SwitchMachineEvent,
+  SwitchOptions,
+  SwitchStateName,
+} from '@dunky.dev/switch'
+
+// The per-part ids the connect derives from a base id of `sw`.
+const ids: SwitchIds = {
+  control: 'sw-control',
+  label: 'sw-label',
+}
+
+interface Harness {
+  service: Machine<SwitchStateName, SwitchContext, SwitchMachineEvent>
+  connection: Connector<SwitchStateName, SwitchContext, SwitchApi, SwitchOptions>
+}
+
+const build = (options: SwitchOptions = {}): Harness => {
+  const service = machine(switchMachine({ id: 'sw', ...options }))
+  const connection = connector(service, switchConnect, options)
+  service.start()
+  return { service, connection }
+}
+
+describe('switch machine — checked/unchecked', () => {
+  it('starts unchecked by default', () => {
+    const { service } = build()
+    expect(service.state).toBe('unchecked')
+  })
+
+  it('starts checked when defaultChecked', () => {
+    const { service } = build({ defaultChecked: true })
+    expect(service.state).toBe('checked')
+  })
+
+  it('starts checked when controlled checked=true', () => {
+    const { service } = build({ checked: true })
+    expect(service.state).toBe('checked')
+  })
+
+  it('toggle flips unchecked -> checked -> unchecked', () => {
+    const { service } = build()
+    service.send({ type: 'toggle' })
+    expect(service.state).toBe('checked')
+    service.send({ type: 'toggle' })
+    expect(service.state).toBe('unchecked')
+  })
+
+  it('check/uncheck are one-directional (check while checked is a no-op)', () => {
+    const { service } = build({ defaultChecked: true })
+    service.send({ type: 'check' })
+    expect(service.state).toBe('checked')
+    service.send({ type: 'uncheck' })
+    expect(service.state).toBe('unchecked')
+    service.send({ type: 'uncheck' })
+    expect(service.state).toBe('unchecked')
+  })
+})
+
+describe('switch machine — disabled gating', () => {
+  it('toggle is ignored while disabled', () => {
+    const { service } = build({ disabled: true })
+    service.send({ type: 'toggle' })
+    expect(service.state).toBe('unchecked')
+  })
+
+  it('set.disabled flips the gate at runtime', () => {
+    const { service } = build()
+    service.send({ type: 'set.disabled', disabled: true })
+    service.send({ type: 'toggle' })
+    expect(service.state).toBe('unchecked')
+
+    service.send({ type: 'set.disabled', disabled: false })
+    service.send({ type: 'toggle' })
+    expect(service.state).toBe('checked')
+  })
+
+  it('programmatic check/uncheck still applies while disabled', () => {
+    const { service } = build({ disabled: true })
+    service.send({ type: 'check' })
+    expect(service.state).toBe('checked')
+    service.send({ type: 'uncheck' })
+    expect(service.state).toBe('unchecked')
+  })
+})
+
+describe('switch machine — part registration', () => {
+  it('tracks label presence in context', () => {
+    const { service } = build()
+    expect(service.context.parts.label).toBe(false)
+
+    service.send({ type: 'part.presence', part: 'label', present: true })
+    expect(service.context.parts.label).toBe(true)
+
+    service.send({ type: 'part.presence', part: 'label', present: false })
+    expect(service.context.parts.label).toBe(false)
+  })
+})
+
+describe('switch connect — logical bindings', () => {
+  it('control carries the switch role, checked state, and identity', () => {
+    const { connection } = build()
+    const control = connection.snapshot.parts.control
+    expect(control.role).toBe('switch')
+    expect(control.checked).toBe(false) // always present — never a bare undefined
+    expect(control.id).toBe(ids.control)
+  })
+
+  it('control press toggles through the machine', () => {
+    const { service, connection } = build()
+    connection.snapshot.parts.control.onPress?.()
+    expect(service.state).toBe('checked')
+    expect(connection.snapshot.parts.control.checked).toBe(true)
+
+    connection.snapshot.parts.control.onPress?.()
+    expect(service.state).toBe('unchecked')
+  })
+
+  it('label press is the same toggle intent', () => {
+    const { service, connection } = build()
+    expect(connection.snapshot.parts.label.id).toBe(ids.label)
+    connection.snapshot.parts.label.onPress?.()
+    expect(service.state).toBe('checked')
+  })
+
+  it('labelledBy only references a rendered label', () => {
+    const { service, connection } = build()
+    expect(connection.snapshot.parts.control.labelledBy).toBeUndefined()
+
+    service.send({ type: 'part.presence', part: 'label', present: true })
+    expect(connection.snapshot.parts.control.labelledBy).toBe(ids.label)
+  })
+
+  it('disabled marks every part for assistive tech and styling', () => {
+    const { connection } = build({ disabled: true })
+    expect(connection.snapshot.disabled).toBe(true)
+    expect(connection.snapshot.parts.control.disabled).toBe(true)
+    expect(connection.snapshot.parts.control['data-disabled']).toBe('')
+    expect(connection.snapshot.parts.thumb['data-disabled']).toBe('')
+    expect(connection.snapshot.parts.label['data-disabled']).toBe('')
+
+    const enabled = build()
+    expect(enabled.connection.snapshot.parts.control.disabled).toBeUndefined()
+    expect(enabled.connection.snapshot.parts.control['data-disabled']).toBeUndefined()
+  })
+
+  it('parts expose data-state for styling/animation', () => {
+    const { connection } = build({ defaultChecked: true })
+    expect(connection.snapshot.parts.control['data-state']).toBe('checked')
+    expect(connection.snapshot.parts.thumb['data-state']).toBe('checked')
+    expect(connection.snapshot.parts.label['data-state']).toBe('checked')
+
+    connection.snapshot.setChecked(false)
+    expect(connection.snapshot.parts.thumb['data-state']).toBe('unchecked')
+  })
+
+  it('setChecked drives both directions', () => {
+    const { service, connection } = build()
+    connection.snapshot.setChecked(true)
+    expect(service.state).toBe('checked')
+    connection.snapshot.setChecked(false)
+    expect(service.state).toBe('unchecked')
+  })
+})
+
+describe('switch connect — reactions', () => {
+  it('fires onCheckedChange on every flip, whatever its cause, not on subscribe', () => {
+    const onCheckedChange = vi.fn()
+    const { service } = build({ onCheckedChange })
+    expect(onCheckedChange).not.toHaveBeenCalled()
+
+    service.send({ type: 'toggle' })
+    expect(onCheckedChange).toHaveBeenLastCalledWith(true)
+
+    // A programmatic flip reports too — even while disabled (the sync contract).
+    service.send({ type: 'set.disabled', disabled: true })
+    service.send({ type: 'uncheck' })
+    expect(onCheckedChange).toHaveBeenLastCalledWith(false)
+    expect(onCheckedChange).toHaveBeenCalledTimes(2)
+  })
+})
diff --git a/packages/react/switch/README.md b/packages/react/switch/README.md
new file mode 100644
index 0000000..03aa00f
--- /dev/null
+++ b/packages/react/switch/README.md
@@ -0,0 +1,32 @@
+# @dunky.dev/react-switch
+
+React binding for [`@dunky.dev/switch`](../../core/switch): a compound
+component — `Switch` plus its parts — that drives the framework-free switch
+machine. The root owns the machine; parts translate the core's logical
+bindings into DOM attributes and handlers.
+
+Behavior contract: [`../../core/switch/SPEC.md`](../../core/switch/SPEC.md).
+React-specific surface: [SPEC.md](./SPEC.md).
+
+## Install
+
+```sh
+npm install @dunky.dev/react-switch
+```
+
+## Usage
+
+```tsx
+import { Switch } from '@dunky.dev/react-switch'
+
+function AirplaneMode() {
+  return (
+    <Switch onCheckedChange={console.log}>
+      <Switch.Control>
+        <Switch.Thumb />
+      </Switch.Control>
+      <Switch.Label>Airplane mode</Switch.Label>
+    </Switch>
+  )
+}
+```
diff --git a/packages/react/switch/SPEC.md b/packages/react/switch/SPEC.md
new file mode 100644
index 0000000..30e799e
--- /dev/null
+++ b/packages/react/switch/SPEC.md
@@ -0,0 +1,77 @@
+# SPEC / React / Switch
+
+The React implementation of the [core spec](../../core/switch/SPEC.md).
+
+## Docs
+
+🔗 [`dunky.dev/ui/components/switch`](https://dunky.dev/ui/components/switch).
+
+## Install
+
+```sh
+npm install @dunky.dev/react-switch
+```
+
+## Usage
+
+```tsx
+import { Switch } from '@dunky.dev/react-switch'
+;<Switch>
+  <Switch.Control>
+    <Switch.Thumb />
+  </Switch.Control>
+  <Switch.Label>Airplane mode</Switch.Label>
+</Switch>
+```
+
+React-specific notes on top of the core contract:
+
+- **`Control`** renders a native `<button type="button">`, so Space and Enter
+  toggle natively — keyboard activation and pointer presses arrive as the same
+  click, and the machine's disabled guard gates both.
+- **`Label`** renders a `<span>`, not a `<label>` — per the core design the
+  name flows through `aria-labelledby` and the press-to-toggle binding is the
+  part's own, so activation never double-fires.
+- Everything ships headless — parts carry behavior, ARIA wiring, and the
+  `data-state` (`checked` / `unchecked`) and `data-disabled` attributes;
+  styling is the consumer's.
+
+## API
+
+### `Switch`
+
+The root: owns the checked state, renders no DOM. Accepts the core
+`SwitchOptions`.
+
+| Prop              | Type                         | Default        | Description                                                     |
+| ----------------- | ---------------------------- | -------------- | --------------------------------------------------------------- |
+| `checked`         | `boolean`                    | —              | Controlled checked state.                                       |
+| `defaultChecked`  | `boolean`                    | `false`        | Initial checked state for the uncontrolled switch.              |
+| `onCheckedChange` | `(checked: boolean) => void` | —              | Fired on every checked/unchecked transition with the new value. |
+| `disabled`        | `boolean`                    | `false`        | Blocks toggling; `aria-disabled` + `data-disabled` on parts.    |
+| `id`              | `string`                     | auto (`useId`) | Base id for the parts; per-part ids are derived from it.        |
+| `children`        | `ReactNode`                  | —              | The switch's parts.                                             |
+
+### `Switch.Control`
+
+The interactive element: `role="switch"`, `aria-checked`, toggles on press.
+
+| Prop       | Type                       | Default | Description                           |
+| ---------- | -------------------------- | ------- | ------------------------------------- |
+| `...props` | `ComponentProps<'button'>` | —       | Forwarded to the rendered `<button>`. |
+
+### `Switch.Thumb`
+
+The knob; purely visual, carries only the styling hooks.
+
+| Prop       | Type                     | Default | Description                         |
+| ---------- | ------------------------ | ------- | ----------------------------------- |
+| `...props` | `ComponentProps<'span'>` | —       | Forwarded to the rendered `<span>`. |
+
+### `Switch.Label`
+
+Names the control (wires `aria-labelledby` on Control); pressing it toggles.
+
+| Prop       | Type                     | Default | Description                         |
+| ---------- | ------------------------ | ------- | ----------------------------------- |
+| `...props` | `ComponentProps<'span'>` | —       | Forwarded to the rendered `<span>`. |
diff --git a/packages/react/switch/package.json b/packages/react/switch/package.json
new file mode 100644
index 0000000..5d09cc9
--- /dev/null
+++ b/packages/react/switch/package.json
@@ -0,0 +1,51 @@
+{
+  "name": "@dunky.dev/react-switch",
+  "version": "0.0.0",
+  "description": "React binding for @dunky.dev/switch.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dunky-dev/ui.git",
+    "directory": "packages/react/switch"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown"
+  },
+  "dependencies": {
+    "@dunky.dev/react-state-machine": "^0.1.0",
+    "@dunky.dev/switch": "workspace:^"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  },
+  "peerDependencies": {
+    "react": "*"
+  }
+}
diff --git a/packages/react/switch/src/context.ts b/packages/react/switch/src/context.ts
new file mode 100644
index 0000000..e155267
--- /dev/null
+++ b/packages/react/switch/src/context.ts
@@ -0,0 +1,19 @@
+import { createContext, useContext, type Context } from 'react'
+import type { SwitchApi, SwitchMachine } from '@dunky.dev/switch'
+
+export interface SwitchContextValue {
+  api: SwitchApi
+  machine: SwitchMachine
+}
+
+export const SwitchContext: Context<SwitchContextValue | undefined> = createContext<
+  SwitchContextValue | undefined
+>(undefined)
+
+export const useSwitchContext = (): SwitchContextValue => {
+  const context = useContext(SwitchContext)
+  if (context === undefined) {
+    throw new Error('Switch parts must be rendered within a <Switch> root')
+  }
+  return context
+}
diff --git a/packages/react/switch/src/effects.ts b/packages/react/switch/src/effects.ts
new file mode 100644
index 0000000..1c5bfc1
--- /dev/null
+++ b/packages/react/switch/src/effects.ts
@@ -0,0 +1,31 @@
+import type { ComponentEffect } from '@dunky.dev/react-state-machine'
+import type { SwitchMachine, SwitchOptions } from '@dunky.dev/switch'
+
+// Substrate effects: prop-driven or platform work the machine can't own.
+// useMachine runs one useEffect per entry, keyed on the listed prop deps.
+type SwitchEffect = ComponentEffect<SwitchMachine, SwitchOptions>
+
+// Controlled checked: follow the `checked` prop in both directions.
+const syncControlledChecked: SwitchEffect = [
+  (machine, props) => {
+    if (props.checked === undefined) return
+    if (props.checked !== machine.matches('checked')) {
+      machine.send({ type: props.checked ? 'check' : 'uncheck' })
+    }
+  },
+  ['checked'],
+]
+
+// Disabled lives in machine context so the toggle guard keeps working at
+// runtime — the machine never reads props.
+const syncDisabled: SwitchEffect = [
+  (machine, props) => {
+    const disabled = props.disabled ?? false
+    if (machine.context.disabled !== disabled) {
+      machine.send({ type: 'set.disabled', disabled })
+    }
+  },
+  ['disabled'],
+]
+
+export const switchEffects: SwitchEffect[] = [syncControlledChecked, syncDisabled]
diff --git a/packages/react/switch/src/index.ts b/packages/react/switch/src/index.ts
new file mode 100644
index 0000000..94d3e64
--- /dev/null
+++ b/packages/react/switch/src/index.ts
@@ -0,0 +1,8 @@
+export {
+  Switch,
+  type SwitchProps,
+  type SwitchControlProps,
+  type SwitchThumbProps,
+  type SwitchLabelProps,
+} from './switch'
+export type { SwitchCallbacks, SwitchOptions } from '@dunky.dev/switch'
diff --git a/packages/react/switch/src/switch.tsx b/packages/react/switch/src/switch.tsx
new file mode 100644
index 0000000..be4c005
--- /dev/null
+++ b/packages/react/switch/src/switch.tsx
@@ -0,0 +1,96 @@
+import {
+  forwardRef,
+  useEffect,
+  type ComponentPropsWithoutRef,
+  type ForwardRefExoticComponent,
+  type ReactNode,
+  type RefAttributes,
+} from 'react'
+import type { SwitchOptions } from '@dunky.dev/switch'
+
+import { mergeProps, normalize } from '@dunky.dev/react-state-machine'
+import { SwitchContext, useSwitchContext } from './context'
+import { useSwitch } from './use-switch'
+
+// Explicit so the exports satisfy --isolatedDeclarations (a bare forwardRef
+// call gives the variable no annotatable type).
+type PartComponent<Props, Element> = ForwardRefExoticComponent<Props & RefAttributes<Element>>
+
+// =============================================================================
+// <Switch> — root, owns the machine and renders no DOM
+// =============================================================================
+
+export interface SwitchProps extends SwitchOptions {
+  children?: ReactNode
+}
+
+export const Switch: ((props: SwitchProps) => ReactNode) & Parts = ({ children, ...options }) => {
+  const value = useSwitch(options)
+  return <SwitchContext.Provider value={value}>{children}</SwitchContext.Provider>
+}
+
+// =============================================================================
+// <Switch.Control> — the interactive element: switch role, checked state,
+// toggles on press
+// =============================================================================
+
+export interface SwitchControlProps extends ComponentPropsWithoutRef<'button'> {}
+
+export const Control: PartComponent<SwitchControlProps, HTMLButtonElement> = forwardRef<
+  HTMLButtonElement,
+  SwitchControlProps
+>((props, forwardedRef) => {
+  const { api } = useSwitchContext()
+  // A native button, so Space/Enter activation arrives as the same press.
+  const merged = mergeProps({ type: 'button' as const, ...props }, normalize(api.parts.control))
+  return <button {...merged} ref={forwardedRef} />
+})
+
+// =============================================================================
+// <Switch.Thumb> — the knob; purely visual, styled off data-state
+// =============================================================================
+
+export interface SwitchThumbProps extends ComponentPropsWithoutRef<'span'> {}
+
+export const Thumb: PartComponent<SwitchThumbProps, HTMLSpanElement> = forwardRef<
+  HTMLSpanElement,
+  SwitchThumbProps
+>((props, forwardedRef) => {
+  const { api } = useSwitchContext()
+  const merged = mergeProps(props as Record<string, unknown>, normalize(api.parts.thumb))
+  return <span {...merged} ref={forwardedRef} />
+})
+
+// =============================================================================
+// <Switch.Label> — the switch's accessible name; pressing it toggles
+// =============================================================================
+
+export interface SwitchLabelProps extends ComponentPropsWithoutRef<'span'> {}
+
+export const Label: PartComponent<SwitchLabelProps, HTMLSpanElement> = forwardRef<
+  HTMLSpanElement,
+  SwitchLabelProps
+>((props, forwardedRef) => {
+  const { api, machine } = useSwitchContext()
+
+  useEffect(() => {
+    machine.send({ type: 'part.presence', part: 'label', present: true })
+    return () => machine.send({ type: 'part.presence', part: 'label', present: false })
+  }, [machine])
+
+  const merged = mergeProps(props as Record<string, unknown>, normalize(api.parts.label))
+  return <span {...merged} ref={forwardedRef} />
+})
+
+// Parts
+// -----------------------------------------------------------------------------
+
+export interface Parts {
+  Control: typeof Control
+  Thumb: typeof Thumb
+  Label: typeof Label
+}
+
+Switch.Control = Control
+Switch.Thumb = Thumb
+Switch.Label = Label
diff --git a/packages/react/switch/src/use-switch.ts b/packages/react/switch/src/use-switch.ts
new file mode 100644
index 0000000..d3bbd3e
--- /dev/null
+++ b/packages/react/switch/src/use-switch.ts
@@ -0,0 +1,17 @@
+import { useId } from 'react'
+import { useMachine } from '@dunky.dev/react-state-machine'
+import { switchMachine, switchConnect } from '@dunky.dev/switch'
+import type { SwitchOptions } from '@dunky.dev/switch'
+
+import type { SwitchContextValue } from './context'
+import { switchEffects } from './effects'
+
+/**
+ * Owns one switch machine for the <Switch> root. `useMachine` creates it
+ * once (StrictMode-safe), re-syncs options each render, runs the substrate
+ * effects, and exposes the connected api.
+ */
+export function useSwitch(options: SwitchOptions): SwitchContextValue {
+  const id = useId()
+  return useMachine(switchMachine, switchConnect, switchEffects, { id, ...options })
+}
diff --git a/packages/react/switch/stories/switch.stories.tsx b/packages/react/switch/stories/switch.stories.tsx
new file mode 100644
index 0000000..e06d7db
--- /dev/null
+++ b/packages/react/switch/stories/switch.stories.tsx
@@ -0,0 +1,127 @@
+import { useState } from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Switch, type SwitchProps } from '@dunky.dev/react-switch'
+
+const meta: Meta<typeof Switch> = {
+  title: 'Primitives/Switch',
+  component: Switch,
+}
+
+export default meta
+type StoryType = StoryObj<typeof Switch>
+
+// The primitive ships headless — the story is the consumer, so it brings the
+// styles. `data-state` / `data-disabled` on every part are the real styling
+// hooks, so the story styles through a stylesheet rather than inline objects.
+const styles = `
+  .switch {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    font: 14px system-ui, sans-serif;
+  }
+  .switch-control {
+    position: relative;
+    width: 44px;
+    height: 24px;
+    padding: 0;
+    border: none;
+    border-radius: 12px;
+    background: #cbd0d9;
+    cursor: pointer;
+    transition: background 120ms ease;
+  }
+  .switch-control[data-state='checked'] {
+    background: #4a63e7;
+  }
+  .switch-control[data-disabled] {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  .switch-thumb {
+    position: absolute;
+    top: 2px;
+    left: 2px;
+    width: 20px;
+    height: 20px;
+    border-radius: 50%;
+    background: white;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3);
+    transition: transform 120ms ease;
+  }
+  .switch-thumb[data-state='checked'] {
+    transform: translateX(20px);
+  }
+  .switch-label {
+    cursor: pointer;
+  }
+  .switch-label[data-disabled] {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+`
+
+const DemoSwitch = ({ label, ...props }: SwitchProps & { label: string }) => (
+  <>
+    <style>{styles}</style>
+    <Switch {...props}>
+      <span className='switch'>
+        <Switch.Control className='switch-control'>
+          <Switch.Thumb className='switch-thumb' />
+        </Switch.Control>
+        <Switch.Label className='switch-label'>{label}</Switch.Label>
+      </span>
+    </Switch>
+  </>
+)
+
+export const standard: StoryType = {
+  render: () => <DemoSwitch label='Airplane mode' onCheckedChange={console.log} />,
+}
+
+export const checked: StoryType = {
+  render: () => <DemoSwitch label='Notifications' defaultChecked />,
+}
+
+export const disabled: StoryType = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+      <DemoSwitch label='Disabled off' disabled />
+      <DemoSwitch label='Disabled on (keeps its value)' disabled defaultChecked />
+    </div>
+  ),
+}
+
+// No Label part — the accessible name comes from an aria-label on the control.
+export const noLabel: StoryType = {
+  render: () => (
+    <>
+      <style>{styles}</style>
+      <Switch>
+        <Switch.Control className='switch-control' aria-label='Mute'>
+          <Switch.Thumb className='switch-thumb' />
+        </Switch.Control>
+      </Switch>
+    </>
+  ),
+}
+
+const ControlledSwitch = () => {
+  const [checked, setChecked] = useState(false)
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
+      <DemoSwitch
+        label={checked ? 'Dark theme on' : 'Dark theme off'}
+        checked={checked}
+        onCheckedChange={setChecked}
+      />
+      <button type='button' onClick={() => setChecked(next => !next)}>
+        Toggle from outside
+      </button>
+    </div>
+  )
+}
+
+export const controlled: StoryType = {
+  render: () => <ControlledSwitch />,
+}
diff --git a/packages/react/switch/tests/switch.test.tsx b/packages/react/switch/tests/switch.test.tsx
new file mode 100644
index 0000000..a1bc23d
--- /dev/null
+++ b/packages/react/switch/tests/switch.test.tsx
@@ -0,0 +1,146 @@
+// @vitest-environment jsdom
+// The React edge of the Switch — behavior only; the machine's own contract is
+// covered in @dunky.dev/switch's tests.
+import { act, cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Switch, type SwitchProps } from '@dunky.dev/react-switch'
+
+const DefaultSwitch = (props: SwitchProps) => (
+  <Switch {...props}>
+    <Switch.Control data-testid='control'>
+      <Switch.Thumb data-testid='thumb' />
+    </Switch.Control>
+    <Switch.Label data-testid='label'>Airplane mode</Switch.Label>
+  </Switch>
+)
+
+const user = userEvent.setup()
+
+const getControl = (): HTMLElement => screen.getByRole('switch')
+
+// RTL auto-cleanup needs vitest globals; this repo runs with globals: false.
+afterEach(cleanup)
+
+describe('Switch', () => {
+  describe('toggling', () => {
+    it('toggles on control press', async () => {
+      render(<DefaultSwitch />)
+      expect(getControl().getAttribute('aria-checked')).toBe('false')
+
+      await user.click(getControl())
+      expect(getControl().getAttribute('aria-checked')).toBe('true')
+
+      await user.click(getControl())
+      expect(getControl().getAttribute('aria-checked')).toBe('false')
+    })
+
+    it('toggles on Space when the control has focus', async () => {
+      render(<DefaultSwitch />)
+      act(() => getControl().focus())
+
+      await user.keyboard('[Space]')
+      expect(getControl().getAttribute('aria-checked')).toBe('true')
+    })
+
+    it('toggles on label press', async () => {
+      render(<DefaultSwitch />)
+      await user.click(screen.getByTestId('label'))
+      expect(getControl().getAttribute('aria-checked')).toBe('true')
+    })
+
+    it('renders checked when defaultChecked', () => {
+      render(<DefaultSwitch defaultChecked />)
+      expect(getControl().getAttribute('aria-checked')).toBe('true')
+    })
+
+    it('fires onCheckedChange with the new value on each toggle', async () => {
+      const onCheckedChange = vi.fn()
+      render(<DefaultSwitch onCheckedChange={onCheckedChange} />)
+
+      await user.click(getControl())
+      expect(onCheckedChange).toHaveBeenLastCalledWith(true)
+
+      await user.click(getControl())
+      expect(onCheckedChange).toHaveBeenLastCalledWith(false)
+      expect(onCheckedChange).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  describe('disabled', () => {
+    it('blocks toggling until re-enabled', async () => {
+      const onCheckedChange = vi.fn()
+      const { rerender } = render(<DefaultSwitch disabled onCheckedChange={onCheckedChange} />)
+
+      await user.click(getControl())
+      expect(getControl().getAttribute('aria-checked')).toBe('false')
+      expect(onCheckedChange).not.toHaveBeenCalled()
+
+      rerender(<DefaultSwitch onCheckedChange={onCheckedChange} />)
+      await user.click(getControl())
+      expect(getControl().getAttribute('aria-checked')).toBe('true')
+    })
+
+    it('marks every part for assistive tech and styling', () => {
+      render(<DefaultSwitch disabled />)
+      expect(getControl().getAttribute('aria-disabled')).toBe('true')
+      expect(getControl().hasAttribute('data-disabled')).toBe(true)
+      expect(screen.getByTestId('thumb').hasAttribute('data-disabled')).toBe(true)
+      expect(screen.getByTestId('label').hasAttribute('data-disabled')).toBe(true)
+    })
+  })
+
+  describe('controlled checked', () => {
+    it('follows the checked prop in both directions', () => {
+      const { rerender } = render(<DefaultSwitch checked={false} />)
+      expect(getControl().getAttribute('aria-checked')).toBe('false')
+
+      rerender(<DefaultSwitch checked />)
+      expect(getControl().getAttribute('aria-checked')).toBe('true')
+
+      rerender(<DefaultSwitch checked={false} />)
+      expect(getControl().getAttribute('aria-checked')).toBe('false')
+    })
+
+    it('reports the toggle intent through onCheckedChange', async () => {
+      const onCheckedChange = vi.fn()
+      render(<DefaultSwitch checked={false} onCheckedChange={onCheckedChange} />)
+
+      await user.click(getControl())
+      expect(onCheckedChange).toHaveBeenLastCalledWith(true)
+      // Controlled is a sync contract, not a hard gate: the flip applies
+      // immediately; the prop pulls it back only when its value changes.
+      expect(getControl().getAttribute('aria-checked')).toBe('true')
+    })
+  })
+
+  describe('aria wiring', () => {
+    it('control is labelled by the rendered Label', () => {
+      render(<DefaultSwitch />)
+      const control = screen.getByRole('switch', { name: 'Airplane mode' })
+      expect(control.getAttribute('aria-labelledby')).toBe(screen.getByTestId('label').id)
+    })
+
+    it('leaves no dangling label reference when no Label is rendered', () => {
+      render(
+        <Switch>
+          <Switch.Control aria-label='Mute'>
+            <Switch.Thumb />
+          </Switch.Control>
+        </Switch>,
+      )
+      const control = screen.getByRole('switch', { name: 'Mute' })
+      expect(control.hasAttribute('aria-labelledby')).toBe(false)
+    })
+
+    it('parts carry data-state as the styling hook', async () => {
+      render(<DefaultSwitch />)
+      expect(getControl().getAttribute('data-state')).toBe('unchecked')
+      expect(screen.getByTestId('thumb').getAttribute('data-state')).toBe('unchecked')
+      expect(screen.getByTestId('label').getAttribute('data-state')).toBe('unchecked')
+
+      await user.click(getControl())
+      expect(screen.getByTestId('thumb').getAttribute('data-state')).toBe('checked')
+    })
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2c9ff48..55794e9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -59,6 +59,15 @@ importers:
         specifier: ^0.1.0
         version: 0.1.0
 
+  packages/core/switch:
+    dependencies:
+      '@dunky.dev/state-machine':
+        specifier: ^0.1.0
+        version: 0.1.0
+      '@dunky.dev/state-machine-bindings':
+        specifier: ^0.1.0
+        version: 0.1.0
+
   packages/dom/utils/focus-trap: {}
 
   packages/dom/utils/scroll-lock: {}
@@ -162,6 +171,34 @@ importers:
         specifier: ^19.2.6
         version: 19.2.7(react@19.2.7)
 
+  packages/react/switch:
+    dependencies:
+      '@dunky.dev/react-state-machine':
+        specifier: ^0.1.0
+        version: 0.1.0(react@19.2.7)
+      '@dunky.dev/switch':
+        specifier: workspace:^
+        version: link:../../core/switch
+    devDependencies:
+      '@testing-library/react':
+        specifier: ^16.1.0
+        version: 16.3.2(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.17))(@types/react@19.2.17)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      '@testing-library/user-event':
+        specifier: ^14.6.1
+        version: 14.6.1(@testing-library/dom@10.4.1)
+      '@types/react':
+        specifier: ^19.2.15
+        version: 19.2.17
+      '@types/react-dom':
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.2.17)
+      react:
+        specifier: ^19.2.6
+        version: 19.2.7
+      react-dom:
+        specifier: ^19.2.6
+        version: 19.2.7(react@19.2.7)
+
 packages:
 
   '@adobe/css-tools@4.5.0':
diff --git a/tsconfig.json b/tsconfig.json
index cbffd69..757a343 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -14,6 +14,8 @@
     "skipLibCheck": true,
     "strict": true,
     "paths": {
+      "@dunky.dev/switch": ["./packages/core/switch/src"],
+      "@dunky.dev/react-switch": ["./packages/react/switch/src"],
       "@dunky.dev/dialog": ["./packages/core/dialog/src"],
       "@dunky.dev/react-dialog": ["./packages/react/dialog/src"],
       "@dunky.dev/dom-focus-trap": ["./packages/dom/utils/focus-trap/src"],
diff --git a/tsdown.config.ts b/tsdown.config.ts
index d2af0e4..1b91224 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -13,11 +13,13 @@ export default defineConfig({
   workspace: [
     'packages/core',
     'packages/core/dialog',
+    'packages/core/switch',
     'packages/dom/utils/focus-trap',
     'packages/dom/utils/scroll-lock',
     'packages/react/dialog',
     'packages/react/hooks/use-focus-trap',
     'packages/react/hooks/use-scroll-lock',
+    'packages/react/switch',
   ],
   entry: ['src/index.ts'],
   format: ['esm'],

From eeb2a8d56436e8ad18567648ee7e0765df397330 Mon Sep 17 00:00:00 2001
From: Ivan Banov <ivanbanov@gmail.com>
Date: Sat, 18 Jul 2026 11:57:55 +0200
Subject: [PATCH 2/2] docs(spec): rename the Design section to Internals

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/core/switch/SPEC.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/switch/SPEC.md b/packages/core/switch/SPEC.md
index 7ead151..6251e62 100644
--- a/packages/core/switch/SPEC.md
+++ b/packages/core/switch/SPEC.md
@@ -97,7 +97,7 @@ Per APG Switch:
 - Form integration (name/value, hidden input, form reset) is out of scope for
   v0 — the switch is a pure setting control.
 
-## Design
+## Internals
 
 - **The Label is not a substrate-native `<label>`.** A native label forwards
   activation to its control, which would double-fire next to the part's own