cadence-ui/docs/exec-plans/2026-03-25-two-factor-setup-pattern.md

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