cadence-ui/docs/exec-plans/2026-03-25-segmented-control.md

Segmented Control

• Status: completed
• Owner: codex
• Date: 2026-03-25

Goal

Add a compact SegmentedControl component to @ai-ui/ui for lightweight dashboard-style view switching so consumers do not need to stretch Tabs into every small top-of-panel toggle.

Scope

• In scope:
  • add a new SegmentedControl component to packages/ui
  • expose the component from the package entrypoint
  • add unit coverage for controlled/uncontrolled behavior and stable contract hooks
  • add Storybook docs that explain when to choose SegmentedControl instead of Tabs
  • update the revenue dashboard story to use the new control for its contribution switcher
  • refresh registry/index.json so source-copy consumers can install the new component
• Out of scope:
  • redesigning the existing Tabs API
  • replacing every current Tabs usage across docs
  • adding icon-only, multi-select, or overflow handling variants in the first pass

Constraints

• Keep the API narrower than Tabs; this should solve lightweight switching, not become another generic navigation primitive.
• Reuse the current token and motion language from DESIGN.md instead of introducing a new visual style.
• Preserve stable data-slot and data-* hooks for docs and tests.
• Do not add a new dependency if the existing Radix stack is sufficient.

Affected Surfaces

• docs/exec-plans/2026-03-25-segmented-control.md
• packages/ui/src/components/segmented-control.tsx
• packages/ui/src/components/segmented-control.variants.ts
• packages/ui/src/components/segmented-control.test.tsx
• packages/ui/src/index.ts
• apps/docs/src/components/segmented-control.stories.tsx
• apps/docs/src/revenue-dashboard.stories.tsx
• registry/index.json

Plan

1. Add the execution plan and confirm the public contract for a compact single-select control.
2. Implement SegmentedControl in packages/ui with stable slots, disabled state, and controlled or uncontrolled value support.
3. Add Storybook docs that explain the intended usage boundary against Tabs.
4. Replace the revenue dashboard contribution switcher with SegmentedControl to prove the dashboard-friendly use case.
5. Run targeted validation and refresh registry metadata.

Validation

• pnpm test -- --runInBand segmented-control tabs
• pnpm harness:validate:docs
• pnpm registry:build

Orchestration Task Sketch

• T1: implement SegmentedControl source, variants, and exports
• T2 -> T1: add docs stories and migrate the revenue dashboard example
• T3 -> T1: add tests and refresh registry metadata

Status Log

• 2026-03-25 20:07 Read the system-of-record files and confirmed that Tabs is currently the only compact peer-switching primitive in the public surface.
• 2026-03-25 20:18 Started the segmented-control slice to cover lightweight dashboard toggles without expanding the Tabs API.
• 2026-03-25 23:32 Shipped the new SegmentedControl, migrated the revenue dashboard contribution switcher, refreshed registry/index.json, and cleared the existing InputGroup type blocker so build and docs validation could pass again.