@zentauri-ui/zentauri-components 1.8.2 → 1.8.4

package/README.md

@@ -9,31 +9,46 @@ A React UI kit for building product interfaces with Tailwind CSS. Components are
 
 The library targets **React 18+** apps that use **Tailwind CSS v4** (or an equivalent setup where Tailwind can scan this package via `@source`). Styling uses utility classes; **class-variance-authority** powers variant APIs (size, appearance, and similar props), with **clsx** and **tailwind-merge** for predictable `className` composition. Component variants are light-theme ready by default and include paired `dark:` Tailwind classes for dark-mode surfaces, text, borders, focus rings, gradients, and form controls. **Framer Motion** backs motion where a feature ships animated variants, and **react-icons** is used for iconography where applicable.
 
-Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@zentauri-ui/zentauri-components/ui/<area>` for static UI, `@zentauri-ui/zentauri-components/ui/<area>/animated` where a motion bundle exists, `@zentauri-ui/zentauri-components/charts/<type>` for Recharts-powered chart primitives, and `@zentauri-ui/zentauri-components/hooks/<entry>` for React hooks (and shared helpers under `hooks/utils`). Base UI entries do **not** re-export animated components; motion lives on its own entry so optional `framer-motion` usage stays tree-shakeable and chunk-friendly. Each entry resolves to its own ESM (`.mjs`), CJS (`.js`), and types (`.d.ts`) so bundlers pull only what you import. Most apps rely on Tailwind scanning the package sources (see installation); a separate CSS import is not required for that setup.
+Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@zentauri-ui/zentauri-components/ui/<area>` for static UI, `@zentauri-ui/zentauri-components/ui/<area>/animated` where a motion bundle exists, `@zentauri-ui/zentauri-components/animations/<name>` for standalone Motion wrappers, `@zentauri-ui/zentauri-components/charts/<type>` for Recharts-powered chart primitives, and `@zentauri-ui/zentauri-components/hooks/<entry>` for React hooks (and shared helpers under `hooks/utils`). Base UI entries do **not** re-export animated components; motion lives on its own entry so optional `framer-motion` usage stays tree-shakeable and chunk-friendly. Each entry resolves to its own ESM (`.mjs`), CJS (`.js`), and types (`.d.ts`) so bundlers pull only what you import. Most apps rely on Tailwind scanning the package sources (see installation); a separate CSS import is not required for that setup.
+
+## Current package surface
+
+| Surface             | Count | Import shape                                          |
+| ------------------- | ----: | ----------------------------------------------------- |
+| Static UI entries   |    42 | `@zentauri-ui/zentauri-components/ui/<name>`          |
+| Animated UI entries |    27 | `@zentauri-ui/zentauri-components/ui/<name>/animated` |
+| Animation entries   |    41 | `@zentauri-ui/zentauri-components/animations/<name>`  |
+| Chart entries       |     9 | `@zentauri-ui/zentauri-components/charts/<type>`      |
+| Hook entries        |    28 | `@zentauri-ui/zentauri-components/hooks/<entry>`      |
+
+`spinner` is the only animated-only UI area. Import it from `@zentauri-ui/zentauri-components/ui/spinner/animated`; there is no `@zentauri-ui/zentauri-components/ui/spinner` static entry.
 
 ## Package status and test coverage
 
 | Metric     | Result           |
 | ---------- | ---------------- |
-| Test files | 75 passed (75)   |
-| Tests      | 507 passed (507) |
+| Test files | 77 passed (77)   |
+| Tests      | 591 passed (591) |
 
 | Area                        | Test files | Tests |
 | --------------------------- | ---------- | ----- |
-| Components and UI utilities | 45         | 397   |
+| Components and UI utilities | 46         | 433   |
+| Standalone animations       | 1          | 42    |
 | React hooks                 | 28         | 101   |
-| CLI and import rewriting    | 2          | 9     |
+| CLI and import rewriting    | 2          | 15    |
 
 ### Per-suite snapshot
 
 | Suite                                                                   | Tests |
 | ----------------------------------------------------------------------- | ----: |
 | `src/ui/dynamic-stepper/dynamic-stepper.test.tsx`                       |     8 |
-| `src/ui/select/select.test.tsx`                                         |     6 |
+| `src/ui/select/select.test.tsx`                                         |    10 |
 | `src/charts/charts.test.tsx`                                            |     6 |
-| `src/ui/modal/modal.test.tsx`                                           |     9 |
+| `src/ui/modal/modal.test.tsx`                                           |    10 |
 | `src/ui/drawer/drawer.test.tsx`                                         |     7 |
-| `cli/cli.integration.test.ts`                                           |     4 |
+| `src/ui/peer-isolation.test.ts`                                         |    29 |
+| `cli/cli.integration.test.ts`                                           |    10 |
+| `src/animations/animations.test.tsx`                                    |    42 |
 | `src/ui/buttons/button.test.tsx`                                        |    41 |
 | `src/ui/inputs/input.test.tsx`                                          |    40 |
 | `src/ui/marquee/marquee.test.tsx`                                       |    10 |
@@ -43,7 +58,7 @@ Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@ze
 | `src/ui/checkbox/checkbox.test.tsx`                                     |     6 |
 | `src/ui/popover/popover.test.tsx`                                       |     4 |
 | `src/ui/command/command.test.tsx`                                       |     7 |
-| `src/ui/context-menu/context-menu.test.tsx`                             |     8 |
+| `src/ui/context-menu/context-menu.test.tsx`                             |    10 |
 | `src/ui/copy-button/copy-button.test.tsx`                               |     8 |
 | `src/ui/kbd/kbd.test.tsx`                                               |     7 |
 | `src/ui/tooltip/tooltip.test.tsx`                                       |     4 |
@@ -106,12 +121,13 @@ Published artifacts live under `dist/`. Imports use **per-entry subpaths**: `@ze
 
 ## Package exports
 
-| Subpath                                               | Description                                                                                                                                    |
-| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@zentauri-ui/zentauri-components/ui/<name>`          | Single UI area: static primitives, compound parts, variants, and types. Does **not** include Framer Motion–based animated exports.             |
-| `@zentauri-ui/zentauri-components/ui/<name>/animated` | Motion entry for that area when published: animated components, motion presets, and related types (depends on **framer-motion**).              |
-| `@zentauri-ui/zentauri-components/charts/<type>`      | Responsive Recharts chart entry for `area`, `bar`, `stacked-bar`, `radar`, `scatter`, `bubble`, `funnel`, `line`, or `pie`, with shared variants, palettes, and exported chart prop types.  |
-| `@zentauri-ui/zentauri-components/hooks/<entry>`      | One hook module or `utils` (`cn`, `clampPage`, `range` from `src/lib/utils.ts`). Entries match files under `src/hooks/` (see **React hooks**). |
+| Subpath                                               | Description                                                                                                                                                                                |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@zentauri-ui/zentauri-components/ui/<name>`          | Single UI area: static primitives, compound parts, variants, and types. Does **not** include Framer Motion–based animated exports.                                                         |
+| `@zentauri-ui/zentauri-components/ui/<name>/animated` | Motion entry for that area when published: animated components, motion presets, and related types (depends on **framer-motion**).                                                          |
+| `@zentauri-ui/zentauri-components/animations/<name>`  | Standalone Motion wrapper and preset entry for reusable transitions such as `fade-in`, `scale-in`, and `blur-out` (depends on **framer-motion**).                                          |
+| `@zentauri-ui/zentauri-components/charts/<type>`      | Responsive Recharts chart entry for `area`, `bar`, `stacked-bar`, `radar`, `scatter`, `bubble`, `funnel`, `line`, or `pie`, with shared variants, palettes, and exported chart prop types. |
+| `@zentauri-ui/zentauri-components/hooks/<entry>`      | One hook module or `utils` (`cn`, `clampPage`, `range` from `src/lib/utils.ts`). Entries match files under `src/hooks/` (see **React hooks**).                                             |
 
 The UI `<name>` segment matches the folder under `src/ui/` (for example `accordion`, `select`, `empty-state`, `buttons` for `Button`, `inputs` for `Input`, `typography` for `Heading` / `Text` and related primitives). The hooks `<entry>` is the file stem (for example `useMediaQuery`, `usePagination`) or `utils`.
 
@@ -124,10 +140,39 @@ Only a subset of UI areas publish a `/animated` entry (see **Components**). Some
 
 Published motion entries (same `<name>` as the base UI folder):
 
-`accordion`, `alert`, `avatar`, `badge`, `buttons`, `card`, `checkbox`, `divider`, `drawer`, `empty-state`, `inputs`, `modal`, `popover`, `progress`, `radio-group`, `skeleton`, `spinner`, `table`, `tabs`, `toast`, `toggle`, `tooltip`, `tree-view`
+`accordion`, `alert`, `avatar`, `badge`, `buttons`, `card`, `checkbox`, `command`, `copy-button`, `divider`, `drawer`, `empty-state`, `inputs`, `kbd`, `modal`, `popover`, `progress`, `radio-group`, `skeleton`, `spinner`, `table`, `tabs`, `timeline`, `toast`, `toggle`, `tooltip`, `tree-view`
 
 **Spinner:** only the motion entry is built—import from `@zentauri-ui/zentauri-components/ui/spinner/animated` (there is no separate `ui/spinner` static bundle).
 
+## Animations
+
+Standalone animations live outside `ui/*` under `@zentauri-ui/zentauri-components/animations/<name>`. They are small **framer-motion** wrappers around `motion.div`, designed for composing page sections, cards, panels, list items, and route-level content without coupling the motion preset to a UI primitive.
+
+**Animation entries:** `fade-in`, `fade-out`, `fade-up`, `fade-down`, `fade-left`, `fade-right`, `scale-in`, `scale-out`, `pop-in`, `blur-in`, `blur-out`, `slide-up`, `slide-down`, `slide-left`, `slide-right`, `reveal-up`, `reveal-down`, `reveal-left`, `reveal-right`, `reveal-blur`, `text-reveal`, `text-shimmer`, `rotate-in`, `pulse`, `ping`, `shake`, `bounce`, `wiggle`, `float`, `spin`, `flip`, `flip-in`, `tilt`, `magnetic`, `hover-lift`, `hover-scale`, `press`, `reorder`, `skeleton-shimmer`, `progress`, `parallax`.
+
+Each entry exports a named component and its preset object, for example `FadeIn` and `fadeInPreset`. Components accept regular `HTMLMotionProps<"div">`, so you can pass `className`, `transition`, `initial`, `animate`, `exit`, and accessibility attributes directly.
+
+For lighter customization without replacing the whole Motion target, pass `from`, `to`, and `exitTo`. These override preset values for `opacity`, `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, and `blur`.
+
+```tsx
+import { FadeIn } from "@zentauri-ui/zentauri-components/animations/fade-in";
+import { ScaleIn } from "@zentauri-ui/zentauri-components/animations/scale-in";
+
+export function MotionPanel() {
+  return (
+    <FadeIn className="rounded-xl border border-white/10 bg-white/5 p-4">
+      <ScaleIn
+        from={{ scale: 0.92, blur: 8 }}
+        to={{ scale: 1, blur: 0 }}
+        transition={{ duration: 0.2 }}
+      >
+        Content with a nested scale entrance.
+      </ScaleIn>
+    </FadeIn>
+  );
+}
+```
+
 ## Requirements
 
 - **React** and **React DOM** `>= 18` (peer dependencies)
@@ -142,6 +187,7 @@ Import static primitives from `@zentauri-ui/zentauri-components/ui/<subpath>` wh
 | --------------- | ----------------- | ---------------------------------- |
 | Accordion       | `accordion`       | `accordion/animated`               |
 | Alert           | `alert`           | `alert/animated`                   |
+| Animated number | `animated-number` | —                                  |
 | Avatar          | `avatar`          | `avatar/animated`                  |
 | Badge           | `badge`           | `badge/animated`                   |
 | Breadcrumb      | `breadcrumb`      | —                                  |
@@ -169,7 +215,7 @@ Import static primitives from `@zentauri-ui/zentauri-components/ui/<subpath>` wh
 | Rating          | `rating`          | —                                  |
 | Radio group     | `radio-group`     | `radio-group/animated`             |
 | Scroll area     | `scroll-area`     | —                                  |
-| Search          | `search`          | -                                  |
+| Search          | `search`          | —                                  |
 | Select          | `select`          | —                                  |
 | Skeleton        | `skeleton`        | `skeleton/animated`                |
 | Slider          | `slider`          | —                                  |
@@ -177,6 +223,7 @@ Import static primitives from `@zentauri-ui/zentauri-components/ui/<subpath>` wh
 | Stepper         | `stepper`         | —                                  |
 | Table           | `table`           | `table/animated`                   |
 | Tabs            | `tabs`            | `tabs/animated`                    |
+| Timeline        | `timeline`        | `timeline/animated`                |
 | Toast           | `toast`           | `toast/animated`                   |
 | Toggle          | `toggle`          | `toggle/animated`                  |
 | Tooltip         | `tooltip`         | `tooltip/animated`                 |
@@ -430,7 +477,7 @@ yarn add react react-dom class-variance-authority clsx tailwind-merge
 
 #### Optional: animations, icons, and charts
 
-Add **`framer-motion`** when you import any `@zentauri-ui/zentauri-components/ui/<name>/animated` entry (including **Spinner**, which is only published under `ui/spinner/animated`). Add **`react-icons`** when using icon sets from that package. Add **`recharts`** when you import any `@zentauri-ui/zentauri-components/charts/<type>` entry or vendor charts with the CLI.
+Add **`framer-motion`** when you import any `@zentauri-ui/zentauri-components/ui/<name>/animated` entry, any `@zentauri-ui/zentauri-components/animations/<name>` entry, or **Spinner** (which is only published under `ui/spinner/animated`). Add **`react-icons`** when using icon sets from that package. Add **`recharts`** when you import any `@zentauri-ui/zentauri-components/charts/<type>` entry or vendor charts with the CLI.
 
 ```bash
 npm install framer-motion react-icons recharts
@@ -444,7 +491,7 @@ pnpm add framer-motion react-icons recharts
 yarn add framer-motion react-icons recharts
 ```
 
-Published `dist/` files **import** these packages; they are **not** vendored inside `@zentauri-ui/zentauri-components`. Static `ui/<name>` bundles do not depend on `framer-motion`; only `ui/<name>/animated` entries do. Chart bundles are isolated to `charts/<type>` entries and depend on `recharts`. Your app installs peers via `dependencies` where needed, and your bundler resolves them from `node_modules`.
+Published `dist/` files **import** these packages; they are **not** vendored inside `@zentauri-ui/zentauri-components`. Static `ui/<name>` bundles do not depend on `framer-motion`; only `ui/<name>/animated` and `animations/<name>` entries do. Chart bundles are isolated to `charts/<type>` entries and depend on `recharts`. Your app installs peers via `dependencies` where needed, and your bundler resolves them from `node_modules`.
 
 ### Next.js: smaller route chunks
 
@@ -512,7 +559,7 @@ Place these rules in your global stylesheet (for example `globals.css`) after Ta
 
 ### Step 4 — Import and use components and hooks
 
-Use **one subpath per UI area** (static and animated are separate entries: `ui/<name>` vs `ui/<name>/animated`) and **one subpath per hook module** so the bundler resolves only the entries you use.
+Use **one subpath per UI area** (static and animated are separate entries: `ui/<name>` vs `ui/<name>/animated`), **one subpath per animation**, and **one subpath per hook module** so the bundler resolves only the entries you use.
 
 #### Imports (single UI area)
 
@@ -557,6 +604,13 @@ import { ButtonAnimated } from "@zentauri-ui/zentauri-components/ui/buttons/anim
 import { Spinner } from "@zentauri-ui/zentauri-components/ui/spinner/animated";
 ```
 
+#### Imports (standalone animations)
+
+```tsx
+import { FadeUp } from "@zentauri-ui/zentauri-components/animations/fade-up";
+import { BlurIn } from "@zentauri-ui/zentauri-components/animations/blur-in";
+```
+
 #### Usage
 
 ```tsx
@@ -589,9 +643,9 @@ import { Spinner } from "@zentauri-ui/zentauri-components/ui/spinner/animated";
 
 ## CLI — copy component source into your app
 
-The package ships a small **Node CLI** (`zentauri-components` and `zentauri-ui` point to the same `cli/index.mjs`) that copies **selected** folders from this package’s `src/ui`, `src/charts`, and `src/hooks` into your repository—similar to shadcn/ui. You keep the files, control paths via `components.json`, and imports are rewritten to your path aliases (`@/components/ui`, `@/hooks`, `@/lib/utils`, and so on).
+The package ships a small **Node CLI** (`zentauri-components` and `zentauri-ui` point to the same `cli/index.mjs`) that copies **selected** folders from this package’s `src/ui`, `src/animations`, `src/charts`, and `src/hooks` into your repository—similar to shadcn/ui. You keep the files, control paths via `components.json`, and imports are rewritten to your path aliases (`@/components/ui`, `@/components/animations`, `@/hooks`, `@/lib/utils`, and so on).
 
-Which UI folders are valid for `add` is driven by **`cli/registry.json`**: a generated manifest listing every addable directory name (matching `src/ui/<name>` plus chart entries like `src/charts/area`) plus optional **`nameAliases`** so the CLI accepts friendly tokens (for example `button` → `buttons`).
+Which UI folders are valid for `add` is driven by **`cli/registry.json`**: a generated manifest listing every addable directory name (matching `src/ui/<name>`, animation entries like `animations/fade-in`, plus chart entries like `charts/area`) plus optional **`nameAliases`** so the CLI accepts friendly tokens (for example `button` → `buttons`).
 
 ### Commands
 
@@ -600,6 +654,7 @@ Call the published binary by name after the package (recommended so `npx` does n
 ```bash
 npx @zentauri-ui/zentauri-components init
 npx @zentauri-ui/zentauri-components add buttons inputs
+npx @zentauri-ui/zentauri-components add animations/fade-in
 npx @zentauri-ui/zentauri-components add charts/area charts/line
 npx @zentauri-ui/zentauri-components -h
 ```
@@ -655,9 +710,10 @@ Defaults look like this; edit `resolvedPaths` and `aliases` so they match your a
 
 ### Registry (`cli/registry.json`)
 
-- **`components`**: sorted list of folder names under **`src/ui/`**, plus chart entries from **`src/charts/<type>`**, that `add` may copy. The file is **generated**; the canonical build list lives in **`tsup.config.ts`** as `uiComponentNames` and `chartEntryNames`, and the generator always ensures **`spinner`** is included so the CLI stays aligned with the animated-only spinner bundle.
+- **`components`**: sorted list of folder names under **`src/ui/`**, plus chart entries from **`src/charts/<type>`**, that `add` may copy. The file is **generated**; the canonical build lists live in **`tsup.config.ts`** as `uiComponentNames`, `uiAnimatedComponentNames`, and `chartEntryNames`, so animated-only entries such as **`spinner`** stay aligned with the CLI.
 - **`hooks`**: sorted list of folder names under **`src/hooks/`** that `add hook` may copy; generated from **`hooksEntryNames`** in **`tsup.config.ts`** (same entries as published `…/hooks/<name>` subpaths).
-- **`nameAliases`**: optional map from a CLI token to a real folder name. Today: `button` → `buttons`, `input` → `inputs` (matching common singular names while folders stay plural).
+- **`nameAliases`**: optional map from a CLI token to a real folder name: `button` → `buttons`, `input` → `inputs` (singular forms while folders stay plural), and `chart-<type>` → `charts/<type>` for every chart (so `add chart-line` and `add charts/line` are equivalent).
+- **`peerHints`**: generated map from a component/chart name to the **optional peer dependencies** its source imports (`framer-motion` for components that ship an `animated/` variant, `react-icons` where icons are used, `recharts` for every chart). After `add`, the CLI prints a deduplicated install hint built from this map, so you never have to guess which peers a vendored component needs.
 
 Example: these are equivalent when `nameAliases` is configured:
 
@@ -668,6 +724,45 @@ zentauri-components add buttons
 
 After `add`, imports inside copied `.ts`/`.tsx` files are rewritten using your `aliases`; test files (`*.test.*`, `*.spec.*`) from the package are not copied.
 
+### Worked examples
+
+```bash
+# A static UI primitive — copies src/ui/buttons plus the shared design-system tokens it imports.
+zentauri-ui add button
+
+# A chart — copies src/charts/line and the shared chart frame; CLI hints `recharts`.
+zentauri-ui add charts/line
+
+# A hook on its own — copies src/hooks/useClipboard (plus any sibling hooks it imports).
+zentauri-ui add hook useClipboard
+```
+
+### Vendored destination structure
+
+Given the default `components.json`, running `zentauri-ui add button charts/line` then `add hook useClipboard` produces:
+
+```
+your-app/
+├── components.json
+└── src/
+    ├── components/
+    │   ├── design-system/        # shared token + variant strings (copied once, never overwritten)
+    │   │   └── button.ts
+    │   └── ui/
+    │       ├── buttons/          # the component folder (index.ts, button.tsx, variants.ts, …)
+    │       └── charts/
+    │           ├── shared/       # chart frame + helpers shared by every chart
+    │           └── line/         # the requested chart entry only
+    ├── hooks/
+    │   └── useClipboard/         # hooks pulled in by components or `add hook`
+    └── lib/
+        └── utils.ts              # cn() helper, created from the package template if missing
+```
+
+- `design-system/` lands beside `ui/` (one level up from `resolvedPaths.ui`) so vendored components keep their `../../design-system/*` imports working without a new alias. Existing files there are left untouched on re-add.
+- Charts always land under `<ui>/charts/`, with a single shared `charts/shared/` folder regardless of how many chart types you add.
+- Re-adding a component overwrites that component's files but preserves your `design-system/` and `lib/utils.ts` edits.
+
 ### When to use the CLI vs npm imports
 
 | Approach                                         | Best when                                                                                                                   |
@@ -681,14 +776,47 @@ Tailwind still needs to see the classes your **copied** files use—point `@sour
 
 https://zentauri-ui.vercel.app/
 
+## Accessibility checklist for contributors
+
+Every new or changed component should clear this bar before it merges. The
+highest-risk primitives (overlays and keyboard-heavy controls) are expected to
+have explicit tests for the items below.
+
+**Semantics & ARIA**
+
+- [ ] Correct landmark/role for the pattern (`dialog`, `menu`/`menuitem`, `listbox`/`option`, `tab`/`tabpanel`, `slider`, `tree`/`treeitem`, …).
+- [ ] State is announced: `aria-expanded`, `aria-selected`, `aria-checked`, `aria-disabled`, `aria-current` as appropriate.
+- [ ] Overlays set `aria-modal` and wire `aria-labelledby` / `aria-describedby` to the rendered title/description.
+- [ ] Compound parts are linked by id (`aria-controls`, `aria-haspopup`) rather than relying on DOM proximity.
+
+**Keyboard**
+
+- [ ] All interactive parts are reachable and operable by keyboard (Enter/Space activate; Arrow keys navigate where the role implies it).
+- [ ] Roving tabindex for composite widgets (one tab stop; arrows move within).
+- [ ] Dismissible surfaces close on `Escape`.
+- [ ] Focus moves into an opened overlay and **returns to the trigger** on close.
+
+**Disabled & edge states**
+
+- [ ] Disabled items are skipped by keyboard navigation and ignore pointer activation, and expose `aria-disabled`.
+- [ ] SSR-safe: no access to `window`/`document` during render (guard effects; the package targets React 18+ server rendering).
+
+**Motion**
+
+- [ ] Animated entries respect `prefers-reduced-motion` (use `usePrefersReducedMotion` / Framer Motion's `useReducedMotion`).
+- [ ] `framer-motion` stays out of static entries — enforced by `src/ui/peer-isolation.test.ts`. Charts stay isolated to `src/charts/*`.
+
+Add or extend the component's `*.test.tsx` to cover the items that apply; see
+`modal`, `select`, and `context-menu` tests for worked examples.
+
 ## Development
 
 From this package directory in the monorepo:
 
-- `pnpm build` (or `npm run build`) — production bundle via `tsup` (Rollup treeshake + `scripts/prepend-use-client.mjs` via `onSuccess` so each UI entry under `dist/ui/`, the chart entry under `dist/charts/`, and `dist/ui/<name>/animated.*` starts with `"use client"` where needed)
+- `pnpm build` (or `npm run build`) — production bundle via `tsup` (Rollup treeshake + `scripts/prepend-use-client.mjs` via `onSuccess` so each UI entry under `dist/ui/`, animation entry under `dist/animations/`, chart entry under `dist/charts/`, and `dist/ui/<name>/animated.*` starts with `"use client"` where needed)
 - `pnpm dev` — `tsup` watch mode (same `onSuccess` hook after each rebuild)
-- `pnpm test` / `pnpm test:watch` — **Vitest** and **Testing Library** unit tests // covered 507 test cases in total
-- **`pnpm run generate:registry`** — runs `scripts/generate-registry.mjs`, which reads **`uiComponentNames`**, **`chartEntryNames`**, and **`hooksEntryNames`** from `tsup.config.ts`, merges in **`spinner`**, applies fixed **`nameAliases`**, and writes **`cli/registry.json`** (`components` + `hooks`). Run this after adding or renaming UI/chart areas or hook entries so the CLI stays in sync (the script prints counts).
+- `pnpm test` / `pnpm test:watch` — **Vitest** and **Testing Library** unit tests // covered 591 test cases in total
+- **`pnpm run generate:registry`** — runs `scripts/generate-registry.mjs`, which reads **`uiComponentNames`**, **`uiAnimatedComponentNames`**, **`animationEntryNames`**, **`chartEntryNames`**, and **`hooksEntryNames`** from `tsup.config.ts`, applies fixed **`nameAliases`**, scans each component/chart source to build **`peerHints`**, and writes **`cli/registry.json`** (`components` + `animations` + `hooks` + `peerHints`). Run this after adding or renaming UI, animation, chart, or hook entries so the CLI stays in sync (the script prints counts).
 
 ## Github Release log
 

package/cli/cli.integration.test.ts

@@ -9,8 +9,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
 const cliEntry = join(packageRoot, "cli", "index.mjs");
 
-function runCli(cwd: string, args: string[]) {
-  execFileSync(process.execPath, [cliEntry, ...args], {
+function runCli(cwd: string, args: string[]): string {
+  return execFileSync(process.execPath, [cliEntry, ...args], {
     cwd,
     encoding: "utf8",
     stdio: ["pipe", "pipe", "pipe"],
@@ -84,4 +84,96 @@ describe("zentauri-ui CLI", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  it("should add a chart entry under charts/ and hint recharts", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-chart-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "charts/line"]);
+      expect(
+        existsSync(join(dir, "src/components/ui/charts/line/index.ts")),
+      ).toBe(true);
+      // chart-line alias resolves to charts/line as well
+      expect(out).toContain("recharts");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should add an animation entry under animations/ and hint framer-motion", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-animation-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "animations/fade-in"]);
+      expect(
+        existsSync(join(dir, "src/components/animations/fade-in/index.ts")),
+      ).toBe(true);
+      expect(
+        existsSync(join(dir, "src/components/animations/shared/index.ts")),
+      ).toBe(true);
+      expect(out).toContain("framer-motion");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should add multiple components in one run", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-multi-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "buttons", "card", "badge"]);
+      expect(
+        existsSync(join(dir, "src/components/ui/buttons/button.tsx")),
+      ).toBe(true);
+      expect(existsSync(join(dir, "src/components/ui/card/card.tsx"))).toBe(
+        true,
+      );
+      expect(existsSync(join(dir, "src/components/ui/badge/badge.tsx"))).toBe(
+        true,
+      );
+      expect(out).toContain("Adding buttons…");
+      expect(out).toContain("Adding badge…");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should print react-icons peer hint for components that use icons", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-peer-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "rating"]);
+      expect(out).toContain("Optional peer dependencies");
+      expect(out).toContain("react-icons");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should print Tailwind v4 source guidance after adding", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-tw-"));
+    try {
+      runCli(dir, ["init"]);
+      const out = runCli(dir, ["add", "buttons"]);
+      expect(out).toContain("Tailwind v4");
+      expect(out).toContain("@source");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("should not error when re-adding a component (existing files)", () => {
+    const dir = mkdtempSync(join(tmpdir(), "zentauri-cli-reAdd-"));
+    try {
+      runCli(dir, ["init"]);
+      runCli(dir, ["add", "buttons"]);
+      // Second add over existing files must succeed and keep the design-system.
+      expect(() => runCli(dir, ["add", "buttons"])).not.toThrow();
+      expect(
+        existsSync(join(dir, "src/components/design-system/button.ts")),
+      ).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

package/cli/index.mjs

@@ -22,6 +22,7 @@
  *        └── src/ui/<name>/     ← source copied by `add`
  *        └── src/design-system/ ← shared tokens/variant maps copied by `add`
  *        └── src/charts/<type>/ ← chart source copied by `add charts/area` etc.
+ *        └── src/animations/<name>/ ← animation source copied by `add animations/fade-in`
  *        └── src/hooks/<name>/  ← hooks pulled in as dependencies
  *        └── src/lib/utils.ts   ← template for `cn()` etc. if missing in app
  * ```
@@ -136,6 +137,7 @@ function loadRegistry() {
 function printHelp() {
   const reg = loadRegistry();
   const componentsList = (reg.components ?? []).join("\n");
+  const animationsList = (reg.animations ?? []).join("\n");
   const hooksList = (reg.hooks ?? []).join("\n");
 
   console.log(`Zentauri UI — copy component source into your app (shadcn-style)
@@ -148,6 +150,9 @@ Usage:
 List of components:
 ${componentsList}
 
+List of animations:
+${animationsList}
+
 List of hooks:
 ${hooksList}
 
@@ -278,11 +283,13 @@ function defaultConfig() {
   return {
     aliases: {
       ui: "@/components/ui",
+      animations: "@/components/animations",
       utils: "@/lib/utils",
       hooks: "@/hooks",
     },
     resolvedPaths: {
       ui: "src/components/ui",
+      animations: "src/components/animations",
       utils: "src/lib/utils.ts",
       hooks: "src/hooks",
     },
@@ -321,7 +328,7 @@ function validateConfig(cfg) {
 
 /**
  * Maps CLI input (any casing, optional registry alias) to a canonical folder name
- * under `src/ui/<name>` or `src/charts/<type>`.
+ * under `src/ui/<name>`, `src/animations/<name>`, or `src/charts/<type>`.
  *
  * Resolution order:
  * 1. Exact key in `registry.nameAliases`
@@ -425,10 +432,10 @@ async function collectHookTransitiveClosure(packageRoot, seedHooks) {
 }
 
 /**
- * Copies `packageRoot/src/ui/<componentName>` or `packageRoot/src/charts/<type>` into
- * `<configDir>/<resolvedPaths.ui>/<componentName>`, skipping tests, rewriting
- * imports in TS/JS files, and collecting hook folder names referenced by those
- * files for later copying.
+ * Copies `packageRoot/src/ui/<componentName>`,
+ * `packageRoot/src/animations/<name>`, or `packageRoot/src/charts/<type>` into
+ * the configured destination, skipping tests, rewriting imports in TS/JS files,
+ * and collecting hook folder names referenced by those files for later copying.
  *
  * @param {string} componentName — resolved registry name (directory under `src/ui`, or `charts/<type>`)
  * @param {object} config — validated `components.json`
@@ -444,26 +451,44 @@ async function collectHookTransitiveClosure(packageRoot, seedHooks) {
  */
 async function copyUiComponent(componentName, config, configDir, packageRoot) {
   const isChartEntry = componentName.startsWith("charts/");
+  const isAnimationEntry = componentName.startsWith("animations/");
+  const animationName = componentName.slice("animations/".length);
   const srcRoot = isChartEntry
     ? join(packageRoot, "src", "charts")
-    : join(packageRoot, "src", "ui", componentName);
+    : isAnimationEntry
+      ? join(packageRoot, "src", "animations")
+      : join(packageRoot, "src", "ui", componentName);
   if (!existsSync(srcRoot)) {
     throw new Error(
       `Missing package source: ${relative(packageRoot, srcRoot)}`,
     );
   }
+  const animationsPath =
+    config.resolvedPaths.animations ??
+    join(dirname(config.resolvedPaths.ui), "animations");
   const destRoot = isChartEntry
     ? join(configDir, config.resolvedPaths.ui, "charts")
-    : join(configDir, config.resolvedPaths.ui, componentName);
+    : isAnimationEntry
+      ? join(configDir, animationsPath)
+      : join(configDir, config.resolvedPaths.ui, componentName);
   const files = (await walkFiles(srcRoot)).filter((absSrc) => {
-    if (!isChartEntry) {
-      return true;
+    if (isAnimationEntry) {
+      const relFromAnimationsRoot = relative(srcRoot, absSrc);
+      return (
+        relFromAnimationsRoot.startsWith("shared/") ||
+        relFromAnimationsRoot.startsWith(`${animationName}/`)
+      );
     }
-    const relFromChartsRoot = relative(srcRoot, absSrc);
-    return (
-      relFromChartsRoot.startsWith("shared/") ||
-      relFromChartsRoot.startsWith(`${componentName.slice("charts/".length)}/`)
-    );
+    if (isChartEntry) {
+      const relFromChartsRoot = relative(srcRoot, absSrc);
+      return (
+        relFromChartsRoot.startsWith("shared/") ||
+        relFromChartsRoot.startsWith(
+          `${componentName.slice("charts/".length)}/`,
+        )
+      );
+    }
+    return true;
   });
   const usedHooks = new Set();
 
@@ -599,6 +624,63 @@ async function ensureUtilsFile(config, configDir, packageRoot) {
   console.log(`Created ${relative(configDir, dest)}`);
 }
 
+/**
+ * Human-readable note explaining why each optional peer dependency may be
+ * needed, so the install hint is self-explanatory.
+ */
+const PEER_HINT_REASONS = {
+  "framer-motion": "only if you use animated UI or animation entries",
+  "react-icons": "icons used by this component",
+  recharts: "required to render charts",
+};
+
+/**
+ * Prints optional peer-dependency install hints and Tailwind v4 scanning
+ * guidance after a successful `add`. Hints come from `registry.peerHints`
+ * (generated by scripts/generate-registry.mjs). Silent when nothing applies.
+ *
+ * @param {string[]} resolvedNames — canonical component/chart names that were added
+ * @param {object} registry — from `loadRegistry()`
+ * @param {object} config — validated `components.json` (for resolvedPaths.ui)
+ */
+function printAdoptionHints(resolvedNames, registry, config) {
+  const peerHints = registry.peerHints ?? {};
+  /** @type {Map<string, string[]>} peer -> component names that need it */
+  const needed = new Map();
+  for (const name of resolvedNames) {
+    for (const peer of peerHints[name] ?? []) {
+      if (!needed.has(peer)) {
+        needed.set(peer, []);
+      }
+      needed.get(peer).push(name);
+    }
+  }
+
+  if (needed.size > 0) {
+    console.log("\nOptional peer dependencies:");
+    for (const [peer, users] of needed) {
+      const reason = PEER_HINT_REASONS[peer] ?? "";
+      console.log(
+        `  - ${peer}${reason ? ` (${reason})` : ""} — used by ${users.join(", ")}`,
+      );
+    }
+    console.log(`  Install with: npm i ${[...needed.keys()].join(" ")}`);
+  }
+
+  const uiPath = config?.resolvedPaths?.ui ?? "your components directory";
+  const animationsPath =
+    config?.resolvedPaths?.animations ?? "your animations directory";
+  console.log(
+    `\nTailwind v4: vendored files live in ${uiPath}, so they are scanned automatically when inside your app's content sources.`,
+  );
+  if (resolvedNames.some((name) => name.startsWith("animations/"))) {
+    console.log(`  Animation files live in ${animationsPath}.`);
+  }
+  console.log(
+    `  If you placed them elsewhere, add: @source "${uiPath}";  (light + dark: classes are paired, so the whole tree must be scanned)`,
+  );
+}
+
 /**
  * `zentauri-components init` — writes default `components.json` next to `--cwd`.
  *
@@ -707,6 +789,7 @@ async function cmdAdd(names, cwd) {
   }
 
   console.log("Done.");
+  printAdoptionHints(resolvedNames, registry, config);
 }
 
 /**