From a099912daca035c026a229c7a970e4dd52444b63 Mon Sep 17 00:00:00 2001 From: kurihada Date: Thu, 19 Mar 2026 12:12:19 +0800 Subject: [PATCH] docs: add roadmap --- roadmap.md | 478 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 roadmap.md diff --git a/roadmap.md b/roadmap.md new file mode 100644 index 0000000..ec04749 --- /dev/null +++ b/roadmap.md @@ -0,0 +1,478 @@ +# 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.