# Cadence 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 internal registry distribution ## Status Snapshot This document began as the build-out plan for the system. The current repo has already completed most of that baseline work: - phases 0 through 4 are effectively in place: workspace, tokens, authoring contract, core components, Storybook docs, and baseline tests - phase 5 has shipped its first advanced-pattern slice with `DataTable`, alongside `Command`, `Combobox`, `Sheet`, and `EmptyState` - phase 6 now covers package-first release automation, fixed-version package publishing, and the optional source-copy registry flow The next work is mostly hardening and distribution: - keep the registry metadata and consumer smoke flow reliable - keep package publish validation and tag automation reliable - expand advanced patterns only where real product usage justifies them ## 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 ```txt 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/ # internal source-copy registry ``` ### `packages/ui` structure ```txt 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 - one Morandi 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 Status: Baseline shipped. 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` Current shipped patterns: - `Form` - `Data Table` - `Command` - `Combobox` - `Sheet` - `Empty State` Exit criteria: - patterns reuse existing component contracts - no pattern introduces a competing API style ## Phase 6: Internal Registry and Distribution Status: Package-first publishing and optional source-copy distribution are both in place. 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 Delivered so far: - fixed-version package release pair for `@ai-ui/ui` and `@ai-ui/tokens` - package consumer smoke validation - tag-driven publish workflow - generated `registry/index.json` - local `pnpm registry:install` copy-in workflow - `pnpm test:registry:consumer` validation - Changesets status checks and version PR automation Remaining follow-up: - package registry operational hardening - any automation beyond source-copy installs Exit criteria: - package consumers can install the published packages - source-copy 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.