# Two-Factor Setup Pattern

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

## Goal

Add a new Storybook pattern for a two-factor setup flow that captures the structure of the
reference UI while staying inside Cadence UI's lighter Material-tonal design direction and
reusing the existing component set instead of introducing a new public package component.

## Scope

- In scope:
  - add a new docs pattern under `apps/docs/src/patterns/`
  - compose the scene with existing components such as `Badge`, `Button`, `Card`, `Field`, `Input`,
    and `InputGroup`
  - document why this belongs in `Patterns` instead of `Components`
- Out of scope:
  - adding a new public `packages/ui` export
  - introducing a dedicated OTP primitive or authentication package
  - wiring real QR generation, API calls, or clipboard guarantees

## Constraints

- Keep the visual direction aligned with `DESIGN.md`: tonal, light, rounded, and calm.
- Avoid introducing a black, neon, or high-contrast security-console aesthetic.
- Reuse existing components wherever practical and keep one-off styling local to the story.
- Do not disturb unrelated in-flight work in the dirty worktree.

## Affected Surfaces

- `apps/docs/src/patterns`
- `docs/exec-plans`

## Plan

1. Add the execution plan and confirm this slice should live in `Patterns`.
2. Implement a new `Patterns/TwoFactorSetup` story that composes existing UI primitives into a
   modal-ready 2FA setup scene.
3. Add anatomy and accessibility-oriented review stories so placement and usage are explicit.
4. Run focused docs validation and record the result.

## Validation

- `pnpm build:docs`

## Orchestration Task Sketch

- `T1`: add the docs-only two-factor setup pattern story
- `T2 -> T1`: run focused docs validation and record outcomes

## Status Log

- `2026-03-25 22:10` started the slice after confirming the reference is better treated as a composed auth pattern than as a new base component or dialog variant
- `2026-03-25 22:18` added `Patterns/TwoFactorSetup` as a docs-only pattern story built from existing components with a lighter tonal treatment instead of the reference's dark security-console styling
- `2026-03-25 22:20` validated the new story with `pnpm build:docs`
- `2026-03-25 19:02` migrated the scene's split layout and accessibility review layout onto the shared `Row` / `Col` grid primitives so the pattern no longer depends on local fixed desktop column math