Components: Generate Toggle Button

[JasonVMo]

Summary

Generate Toggle Button with its canonical contract, implementation, tests, stories, platform validation, and explicit package export so persistent on/off actions are covered. Button already provides the core interaction foundation; ingesting the missing local spec is the remaining prerequisite.

Observed. toggle-button is entry toggle-button in the canonical catalog and has no
implementation in packages/agentic/components. Upstream describes it as: Toggles a single option between two persistent on/off states. Covers the style hierarchy (Primary/Secondary/Outline/Subtle), layout modes, three sizes, the Shape axis (Rounded/Circular), the Selected state axis, independent leading and trailing icon slots, the Regular to Filled icon swap, and the font-weight swap for the on-state label.

Goal

Generate the toggle-button component in
packages/agentic/components/src/components against the
canonical Fluent Flex spec, with the colocated coverage, stories, and platform
validation the package requires, and export it explicitly from
src/index.ts.

Stage

Stage 2 (beta). Wave 1 - local component dependencies already generated.

Why it matters

Observed. The canonical catalog has 50 components and the agentic library has
generated 18. toggle-button is one of the 32 in the gap, enumerated in
the missing-components index.

Inferred. Every local dependency this component needs is already generated, so it is deliverable without new shared infrastructure and contributes directly to the beta catalog.

Observed current state

Canonical spec and source

Field	Value
Canonical spec	plugins/components/skills/toggle-button/SKILL.md with usage.md, web/tokens.yaml, web/accessibility.md, and web/interaction.md, at x3-design/fluent-design @ d334acf
Upstream tier	atom
Upstream catalog key	toggle-button in component-map.yaml
Local staged spec	None. No specs/toggle-button folder exists; the spec must be ingested first
Local implementation	None. No src/components/toggle-button directory exists

Closest existing FURN or V1 implementation

• packages/components/Button/src/ToggleButton - ToggleButton.tsx, useToggleButton.ts, ToggleButton.styling.ts, and SPEC.md. Desktop token overrides are ToggleButtonColorTokens.win32.ts and ToggleButtonColorTokens.windows.ts, with ToggleButtonColorTokens.ts as the cross-platform base; ToggleButton.android.tsx is mobile-only. Its public axis is checked / defaultChecked.

Note on platform canon. Where a legacy package has platform-specific files, the
desktop path (.win32, .windows, .macos, or the unsuffixed cross-platform file)
is the compatibility reference. .ios, .android, and .mobile variants are not
treated as the cross-platform canonical implementation.

Local dependencies

• src/components/button - Observed present (component).

Known blockers

Observed. There is no recorded blocker, because there is no local spec folder and therefore no
blockers.md. The absence of an ingested spec is itself the first blocker; see
spec-ingestion-and-generation.md.

Scope

• Ingest or promote the spec into the component directory in the generated shape
  (SPEC.md plus a spec/ folder), per
  spec-ingestion-and-generation.md.
• Establish the public contract first: variants, slots, native props, accessibility,
  interaction states, and platform behavior.
• Implement the required file structure from
  src/components/AGENTS.md:
  toggle-button.types.ts, toggle-button.styles.ts, use*.ts, use*Styles.ts, render*.tsx, and
  the assembly module with a displayName.
• Style from Flex tokens first and record genuine token gaps rather than substituting
  unrelated values.
• Export the component, its public types, and the state, style, and render stages
  explicitly from src/index.ts under component-qualified unstable names.
• Resolve the relationship with the existing agentic button, which still carries a selected prop and toggle-button accessibility semantics. Upstream moved that behavior out of button into this component.
• Classify the axis before wiring: a toggle button is self-driving, so it takes the selected / defaultSelected / onSelectedChange triple and useToggleState, unlike button's externally driven selected.
• Implement the independent leading and trailing icon slots that upstream button now also has, which the local button does not.

Out of scope

• Changing the contract of an existing generated component, unless this task explicitly
  calls for it above; raise it as its own item.
• Building shared infrastructure owned by another task: overlay hosting
  (popover), roving focus (focus-zone.md), spec
  ingestion (spec-ingestion-and-generation.md),
  or the coverage contract (component-test-strategy.md).
• Migrating any legacy FURN consumer onto this component.
• Mobile platform support; the applicable upstream companion is web, retargeted to
  React Native for Windows and macOS.

Deliverables

• src/components/toggle-button/ implementing the full required file structure.
• SPEC.md and a spec/ companion folder with provenance recording the upstream path,
  SHA, and ingestion date.
• Colocated toggle-button.test.tsx, toggle-button.types.test.ts, and toggle-button.stories.tsx.
• Snapshot coverage where the visual contract is state-dependent, or a recorded
  exemption.
• Explicit exports from src/index.ts, with src/index.test.ts updated.
• A changeset, per the repository's version management rules.
• A recorded readiness level with its supporting evidence.

Required coverage, stories, and platform validation

Runtime and type coverage:

• All four styles, both layout modes, all three sizes, and both shapes.
• Both directions of the self-driving axis: uncontrolled via defaultSelected and controlled via selected.
• The Regular to Filled icon swap and the font-weight swap, including that layout does not shift on toggle.
• Disabled wins over pressed and hovered.
• The controlled prop stays out of story args, per the package story rule for self-driving controls.
• User style and handler forwarding, and that user styles are applied after component
  styles.
• Compile-time slot acceptance and any mutually exclusive props.

Stories: a typed Meta titled Components/Toggle Button, an args-driven Default, a
grouped Overview when the contract has several axes, one focused story per variant
axis, and an interactive story for each stateful axis. Self-driving axes expose
default<State> as the control; externally driven selection is owned by the story with
React.useState. Identity-changing axes are not exposed as controls.

Platform validation: the component's stories render and behave correctly on macOS
and on React Native Windows Fabric through apps/storybook,
including hover, pressed, disabled, focus, optional-slot, and constrained-content
scenarios. Add a stable root testID if the component joins the automated smoke set.

Acceptance criteria

• src/components/toggle-button exists with the required file structure and a displayName.
• Every variant axis in the component's SPEC.md is implemented, or a deviation is recorded in the spec.
• The component styles from Flex tokens, with any genuine token gap recorded rather than approximated.
• Focus feedback renders through FocusVisual; no outline* props and no React Native Windows native focus visuals are introduced.
• State precedence is explicit: disabled wins over pressed, which wins over hovered.
• Every stateful axis is classified as self-driving or externally driven, and both paths are covered.
• Runtime, type, and story coverage satisfy the package coverage contract.
• The component, its public types, and its pipeline stages are exported explicitly from src/index.ts, and src/index.test.ts covers them.
• The component's stories render on macOS and on React Native Windows Fabric.
• yarn workspace @fluentui-react-native/components format, lint, build, and test pass, and the Storybook bundle succeeds for both desktop platforms.
• A readiness level is recorded with its supporting evidence.
• A changeset is included.

Dependencies and ordering

• Blocked by spec-ingestion-and-generation.md: the spec must be pulled from the pinned upstream revision before generation can start.
• Gated by component-test-strategy.md: the component must satisfy the coverage contract on arrival rather than being retrofitted.
• Gated by readiness-model.md: the target readiness level must be stated before the work starts.
• Consumes the Infrastructure workstream (storybook-e2e.md) for automated macOS and Windows Fabric validation; until it lands, platform validation is manual.

Risks and open decisions

1. This task and the button divergence are two halves of one decision. Landing toggle-button without deciding button's selected axis leaves two overlapping toggle APIs in one package.
2. The FURN V1 ToggleButton uses checked; the upstream contract uses Selected. Naming should follow the upstream spec, with the difference recorded for migration.

Evidence and references

• Upstream spec: plugins/components/skills/toggle-button/SKILL.md and
  components-index/SKILL.md
  at x3-design/fluent-design @ d334acf.
• Canonical implementations to follow: src/components/button
  for a styled higher-order component and src/primitives/icon
  for a primitive.
• Authoring rules: src/components/AGENTS.md and the
  agentic component authoring skill.
• Workstream context: Components README and
  the missing-components index.

Sources retrieved 2026-08-20.