cadence-ui/roadmap.md

AI UI Roadmap

Goal

Build a long-term maintainable component system inspired by shadcn/ui, but owned by this repo:

• keep the Radix + Tailwind + source-owned components model
• replace default styling with our own tokens and component rules
• make motion a first-class system layer, not ad hoc transitions
• support theming, accessibility, testing, and future internal registry distribution

Product Principles

1. Source owned Components live in our codebase and are modified directly.
2. Token first Visual and motion decisions are defined as tokens before being embedded in components.
3. Component contract over component count Stable API patterns matter more than shipping many components quickly.
4. Accessibility by default Keyboard, focus, ARIA, and reduced motion are baseline requirements.
5. Motion with purpose Animation must communicate state, feedback, and hierarchy.
6. Incremental adoption Start from a small core and expand only after patterns are stable.

Recommended Stack

Core

• React
• TypeScript
• pnpm workspace
• Tailwind CSS
• CSS variables
• Radix UI
• class-variance-authority
• clsx
• tailwind-merge

Motion

• CSS transitions and keyframes for default interactions
• motion or framer-motion for advanced choreography only
• prefers-reduced-motion support from day one

Docs and DX

• Storybook
• Lucide React
• react-hook-form
• zod

Quality and Release

• Vitest
• @testing-library/react
• Playwright
• axe-core or jest-axe
• tsup
• Changesets

Target Repository Structure

apps/
  docs/                  # Storybook or docs app
packages/
  ui/                    # component source
  tokens/                # design + motion tokens
  icons/                 # optional icon wrappers
  config/                # shared ts/eslint/tailwind config, optional
registry/                # future internal shadcn-like registry

packages/ui structure

src/
  lib/
    cn.ts
    cva.ts
    motion.ts
  styles/
    base.css
    tokens.css
    motion.css
  primitives/
  components/
    button/
    input/
    dialog/
    dropdown-menu/
    tabs/
    toast/
  patterns/
    form/
    data-table/

System Layers

1. Tokens

Define semantic tokens instead of hardcoded visual values.

Visual token groups:

• colors
• typography
• radius
• shadow
• border
• spacing when needed beyond Tailwind defaults

Motion token groups:

• --dur-fast
• --dur-base
• --dur-slow
• --ease-standard
• --ease-emphasized
• --distance-xs
• --distance-sm
• --scale-press

2. Primitives

Use Radix UI as the accessibility and interaction base where appropriate.

Examples:

• dialog
• popover
• dropdown-menu
• tabs
• toast
• checkbox
• radio-group
• switch

3. Motion Recipes

Reusable motion patterns that components consume instead of redefining animation logic.

Initial recipe set:

• fade-in
• fade-out
• slide-up-sm
• slide-down-sm
• overlay-enter
• overlay-exit
• press-feedback
• focus-ring-transition
• accordion-expand
• toast-enter
• toast-exit

4. Components

Components compose tokens, primitives, and motion recipes into a stable public API.

Component Contract

All components should follow a consistent contract where relevant:

• support className
• forward ref
• use variant only where it adds actual semantic value
• use size only where it is meaningful
• support asChild for composable primitives
• expose controlled and uncontrolled APIs when appropriate
• expose stable states through attributes such as data-state, data-disabled, and data-invalid
• include loading, disabled, error, and focus behaviors where applicable

Design Rules

Keep from shadcn

• source-distributed component ownership model
• composable React API patterns
• Radix + Tailwind + CVA implementation style
• pragmatic developer experience

Replace from shadcn

• default visual tokens
• default component variants
• default color and radius assumptions
• default animation choices
• package and registry conventions when our patterns stabilize

Motion Rules

Default timing guidance:

• press feedback: 100-140ms
• hover and focus: 160-200ms
• popover, dropdown, tooltip: 180-240ms
• dialog and drawer: 220-320ms
• section entrance: 320-480ms
• exits should generally be faster than entrances

Implementation rules:

• prefer animating transform and opacity
• avoid transition-all
• avoid animating width, height, top, left, padding, margin
• use data-state driven animation where possible
• support prefers-reduced-motion
• use JS animation only for interactions CSS cannot express cleanly

Delivery Phases

Phase 0: Foundation Setup

Objective: Create the monorepo foundation and install the baseline tooling.

Deliverables:

• pnpm workspace
• root package.json
• packages/ui
• packages/tokens
• apps/docs
• Tailwind, TypeScript, ESLint, and build setup

Exit criteria:

• workspace installs cleanly
• docs app boots
• packages/ui builds

Phase 1: Token System

Objective: Define the first stable visual and motion token layer.

Deliverables:

• tokens.css
• motion.css
• semantic color scale
• radius, shadow, border, typography tokens
• motion duration, easing, distance, and scale tokens
• light theme baseline
• dark theme baseline
• one optional brand theme scaffold

Exit criteria:

• components can consume tokens without hardcoded brand values
• theme switching works at token level
• reduced motion rules exist globally

Phase 2: Core Utilities and Contracts

Objective: Standardize the implementation patterns every component will use.

Deliverables:

• cn.ts
• cva.ts conventions
• shared component authoring guidelines
• state naming and slot naming conventions
• motion helper conventions

Exit criteria:

• new components can follow one repeatable implementation pattern
• API expectations are documented

Phase 3: Core Component Set

Objective: Ship the first stable component layer.

Priority components:

• Button
• Input
• Textarea
• Checkbox
• Radio Group
• Switch
• Select
• Dialog
• Dropdown Menu
• Tabs
• Toast
• Form

Exit criteria:

• all core components support tokens and motion recipes
• all core components have docs stories
• all core components have baseline tests

Phase 4: Documentation and QA

Objective: Make the system safe to use and safe to evolve.

Deliverables:

• Storybook stories for all component states
• accessibility checks
• interaction tests
• visual review process
• contribution guide for new components

Exit criteria:

• docs cover variants, sizes, states, themes, and reduced motion
• core components pass accessibility and interaction checks

Phase 5: Advanced Patterns

Objective: Build higher-level patterns only after the base layer is stable.

Candidate patterns:

• Form
• Data Table
• Command
• Combobox
• Date Picker
• Drawer
• Sheet
• Empty State

Exit criteria:

• patterns reuse existing component contracts
• no pattern introduces a competing API style

Phase 6: Internal Registry and Distribution

Objective: Create an internal distribution model similar to shadcn, but based on our own rules.

Deliverables:

• internal registry format
• code generation or copy-in workflow
• documentation for install and upgrade paths
• versioning and release process

Exit criteria:

• consumers can pull components from our registry
• upgrades are documented and reproducible

Testing Strategy

Unit and Interaction

• Vitest
• @testing-library/react
• state and variant coverage
• controlled and uncontrolled behavior coverage

Accessibility

• axe-core or jest-axe
• keyboard and focus-path checks
• reduced motion validation

End-to-End

• Playwright
• open and close behavior
• keyboard navigation
• form submission flows

Documentation Requirements

Every core component should document:

• purpose
• anatomy
• variants
• sizes
• states
• accessibility notes
• motion behavior
• reduced motion fallback
• example usage

Risks to Manage

• over-customizing too early before contracts stabilize
• building too many components before token patterns settle
• letting business code create parallel component wrappers
• tying all animation to a JS library unnecessarily
• skipping docs and tests until later

Initial Execution Plan

Sprint 1

Goal: Set up the workspace and foundation.

Tasks:

• initialize pnpm workspace
• create apps/docs
• create packages/ui
• create packages/tokens
• add Tailwind and TypeScript setup
• add Storybook

Sprint 2

Goal: Lock the first token layer and first motion layer.

Tasks:

• create tokens.css
• create motion.css
• define base semantic palette
• define duration and easing tokens
• add global reduced motion rules

Sprint 3

Goal: Ship the first reference components.

Tasks:

• implement Button
• implement Input
• implement Dialog
• add stories
• add tests

Sprint 4

Goal: Expand the core set using the same contract.

Tasks:

• implement Dropdown Menu
• implement Tabs
• implement Toast
• validate API consistency

Definition of Done

A component is considered done only when:

• implementation is in packages/ui
• tokens are used instead of hardcoded presentation values
• motion follows shared recipes or shared timing rules
• documentation exists
• tests exist
• accessibility behavior is validated
• reduced motion behavior is defined

First Build Target

The first meaningful milestone is:

• monorepo running
• tokens and motion tokens defined
• Button, Input, and Dialog shipped
• Storybook stories available
• baseline tests passing

This is the point where the system stops being an idea and becomes a reusable foundation.