479 lines
9.6 KiB
Markdown
479 lines
9.6 KiB
Markdown
# 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
|
|
|
|
```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/ # future internal shadcn-like 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
|
|
- 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.
|