feat: plan Stepper/Step component

[nathan2slime]

Context

We need to add a step-based component (Step / Stepper) to guide multi-step flows (sign-up, checkout, onboarding) with strong accessibility, a composable API, and integration with the current library theme system.

Goal

Design and implement a composition-oriented Step component with clear states, keyboard support, and complete documentation.

Implementation plan

1) API and modeling

• Define a compound API:
  • Stepper.Root
  • Stepper.List
  • Stepper.Item
  • Stepper.Indicator
  • Stepper.Title
  • Stepper.Description
  • Stepper.Separator
• Support both modes:
  • controlled (value, onValueChange)
  • uncontrolled (defaultValue)
• Support horizontal and vertical orientation.
• Define visual variants (e.g. default, compact) and sizes.

2) Accessibility

• Apply appropriate roles/attributes (list, listitem, aria-current, aria-disabled, etc.).
• Ensure visible focus and keyboard navigation (arrow keys, Home/End where applicable).
• Provide screen-reader-friendly state announcements (pending, active, completed, error).

3) Styling and theme

• Implement styles following existing component patterns.
• Integrate with existing semantic tokens (surface, border, brand, focus).
• Cover states: inactive, active, completed, error, disabled.

4) Internal implementation

• Extract orchestration/state logic into a dedicated hook (e.g. use-stepper-state).
• Keep components small and reusable; avoid complex inline JSX logic.
• Ensure strict typing without any, following AGENTS.md.

5) Tests

• Add unit tests for:
  • rendering and composition
  • controlled/uncontrolled behavior
  • keyboard interaction
  • accessibility attributes
  • state transitions

6) Storybook

• Add stories covering:
  • horizontal and vertical layouts
  • controlled and uncontrolled usage
  • visual states (active/completed/error/disabled)
  • a realistic flow example (e.g. simplified checkout)

7) Documentation

• Update docs in docs/ with usage guide, examples, and best practices.
• Add an accessibility section and UX recommendations for longer step flows.

8) Acceptance criteria

• Component is publicly exported and fully typed.
• Tests and lint pass.
• Storybook and docs are updated.
• API stays consistent with the rest of the library.

References

• Follow composition, typing, and TSDoc conventions defined in AGENTS.md.