Merge pull request #66 from pras75299/feat/phase-13-config-split

Feat/phase 13 config split

Author: pras75299

.agent/skills/frontend/skill.md

@@ -26,8 +26,8 @@ When creating a new component, you **MUST** create/update the following files co
    Create the primary source file for the component here.
 2. **`apps/www/components/ui/[component-name].tsx`**
    Create an exact copy of the source component here so it can be used in the docs/showcase site.
-3. **`registry/config.ts`**
-   Update the registry config to include the new component, specifying its dependencies (e.g., `["motion", "clsx", "tailwind-merge"]`), tailwind properties, and files.
+3. **`registry/components/[component-name].json`**
+   Create the per-component manifest with a `registry` block (dependencies e.g. `["motion", "clsx", "tailwind-merge"]`, `files`, optional tailwind config) and a `docs` block (name, props, scenarios). Add the slug to `order` and `docsOrder` in `registry/manifest.json`.
 4. **`apps/www/app/page.tsx`**
    Add a functional showcase/demo block of your new component on the main page.
 5. **(After Code Generation)**
@@ -118,7 +118,7 @@ export function ComponentName({ className, children, ...props }: ComponentNamePr
 ## 6. Anti-Patterns (Immediate Failure)
 
 ❌ Failing to create the file in BOTH `registry/` and `apps/www/components/ui/`.
-❌ Failing to update `registry/config.ts` and `apps/www/app/page.tsx`.
+❌ Failing to create `registry/components/[component].json` (+ `registry/manifest.json` order) and `apps/www/app/page.tsx`.
 ❌ Creating a standard static button without hover/tap spring feedback.
 ❌ Using standard CSS `transition-all` on everything instead of precise `motion` springs.
 
@@ -128,7 +128,7 @@ export function ComponentName({ className, children, ...props }: ComponentNamePr
 
 Before finalizing output:
 * [ ] Did I create `registry/[component].tsx` and mirror it to `apps/www/components/ui/`?
-* [ ] Did I update `registry/config.ts` with the new component metadata?
+* [ ] Did I create `registry/components/[component].json` and add the slug to `registry/manifest.json`?
 * [ ] Did I add a demo to `apps/www/app/page.tsx`?
 * [ ] Does the component have meaningful, purposeful, physics-based motion?
 * [ ] Is `motion/react` imported correctly and are styles built entirely with Tailwind CSS?

.github/pull_request_template.md

@@ -42,8 +42,8 @@ Skip this section if your PR doesn't add a component or block.
 **Registry sources**
 
 - [ ] `registry/<slug>/component.tsx` created (or `registry/blocks/<category>/<slug>/component.tsx` for blocks)
-- [ ] `registry/config.ts` entry added with `name`, `dependencies`, `files`, and `tailwindConfig` (v3) and/or `tailwindCss` (v4) as needed
-- [ ] `registry/docs.json` entry added (title, description, category, props)
+- [ ] `registry/components/<slug>.json` created — `registry` block (`dependencies`, `files`, `tailwindConfig` v3 and/or `tailwindCss` v4 as needed) + `docs` block (name, description, category, props)
+- [ ] Slug added to `order` and `docsOrder` in `registry/manifest.json`
 - [ ] `registry/demos.tsx` demo added
 - [ ] `pnpm build:registry` run — no `git diff` in `apps/www/public/registry/`, `apps/www/public/r/`, or `apps/www/components/ui/`
 

BUILD.md

@@ -85,7 +85,8 @@ pnpm test -- packages/cli/src/commands/add.test.ts
 `registry.json` is a **generated artifact** — never edit it manually.
 
 ```bash
-pnpm build:registry    # Reads registry/<slug>/component.tsx sources → writes registry.json
+pnpm build:registry    # Aggregates registry/components/<slug>.json + registry/manifest.json
+                       #    and registry/<slug>/component.tsx sources → writes registry.json
                        # Also writes apps/www/public/registry.json
                        # Also splits per-component files into apps/www/public/registry/
                        # Also writes shadcn-format registry items to apps/www/public/r/
@@ -96,13 +97,12 @@ pnpm build:registry    # Reads registry/<slug>/component.tsx sources → writes
 
 Always commit `registry.json` and the generated files under `apps/www/public/r/` (and the rest of the synced paths) after adding or modifying components, as required by your branch / CI.
 
-### Docs Metadata Storage Decision
+### Registry Metadata Storage Decision
 
-`registry/docs.json` remains centralized for now (single source authoring model). This aligns with the current build flow where one registry build command composes and syncs docs artifacts.
+Registry metadata is authored as **one manifest per component** under `registry/components/<slug>.json`, with cross-cutting config (demos `sourceFile`, install `order`, docs `docsOrder`) in `registry/manifest.json`. `pnpm build:registry` aggregates these into the generated artifacts.
 
-- Author docs metadata in the centralized file.
-- Generated runtime artifacts can still be split per component for delivery.
-- Revisit splitting authoring into per-component metadata files only when scaling triggers are hit (see `docs/adr/0001-registry-docs-metadata-storage.md`).
+- Each `registry/components/<slug>.json` holds a `registry` block (deps, files, tailwind) and a `docs` block (name, props, scenarios).
+- This supersedes the former centralized `registry/config.ts` + `registry/docs.json` model — see [`docs/adr/0002-per-slug-registry-manifests.md`](docs/adr/0002-per-slug-registry-manifests.md) (supersedes ADR 0001).
 
 ## Workspaces
 

CLAUDE.md

@@ -138,10 +138,13 @@ pnpm test -- packages/cli/src/commands/add.test.ts
 ### Component Data Flow
 
 ```
-registry/{component}/component.tsx ← source of truth for component code
-       ↓  (pnpm build:registry)
-registry/config.ts                ← declares name, npm deps, tailwindConfig per component
-       ↓
+registry/{component}/component.tsx   ← source of truth for component code
+registry/components/{slug}.json       ← per-component manifest: build config (deps,
+                                         files, tailwind) + docs metadata (name, props,
+                                         scenarios). See ADR 0002.
+registry/manifest.json                ← demos sourceFile + `order` (install order) +
+                                         `docsOrder` (docs-site display order)
+       ↓  (pnpm build:registry — aggregates the per-slug manifests)
 registry.json                     ← auto-generated root manifest
 apps/www/public/registry/*.json   ← auto-generated split docs registry artifacts (uniqueui add)
 apps/www/public/r/*.json          ← shadcn registry-item JSON (+ r/registry.json manifest)
@@ -174,9 +177,9 @@ Three config files drive the entire docs site:
 ### Adding a New Component
 
 1. Create `registry/{component-name}/component.tsx`
-2. Add entry to `registry/config.ts` (name, dependencies, files array, optional `tailwindConfig` for custom keyframes)
-3. Add docs metadata to `registry/docs.json`
-4. Add demo to `apps/www/config/demos.tsx` (`componentDemos`)
+2. Create `registry/components/{slug}.json` (see ADR 0002 for the shape): a `registry` block (`dependencies`, `files`, optional `tailwindConfig`/`tailwindCss` — do **not** list the shared `cn` util; the build script appends it) and a `docs` block (name, description, icon, props, optional `docs.overview`/`docs.scenarios`).
+3. Add the slug to both `order` and `docsOrder` in `registry/manifest.json`.
+4. Add demo to `apps/www/config/demos.tsx` (`componentDemos`) — via the `registry/demos.tsx` source.
 5. Add an entry to `registry/changelogs.json` under the new slug — at minimum `[{ "version": "1.0.0", "date": "YYYY-MM-DD", "changes": ["Initial release."] }]`. The build script reads `entries[0]` as the component's `meta.version`; entries must be newest-first (descending semver).
 6. Run `pnpm build:registry` from root to regenerate `registry.json`, refresh `apps/www/public/registry/*` and **`apps/www/public/r/*`**, sync `apps/www/components/ui/{component-name}.tsx`, and generate `apps/www/config/components.ts` plus `apps/www/config/docs-scenarios.ts`
 

COMPONENT_LIBRARY.md

@@ -189,8 +189,9 @@ Every component in UniqueUI follows a consistent architecture:
 
 ```
 registry/
-  └── {component-name}.tsx      ← Source component file
-registry/config.ts              ← Registry metadata (deps, tailwind config)
+  └── {slug}/component.tsx      ← Source component file
+registry/components/{slug}.json ← Per-component manifest (deps, tailwind config + docs metadata)
+registry/manifest.json          ← Demos sourceFile + order + docsOrder
 registry.json                   ← Auto-generated (via build:registry script)
 apps/www/components/ui/
   └── {component-name}.tsx      ← Copy used in the docs site
@@ -307,8 +308,8 @@ uniqueui add typewriter-text
 
 ## Contributing a New Component
 
-1. Create `registry/{component-name}.tsx`
-2. Add entry to `registry/config.ts` with dependencies and tailwind config
+1. Create `registry/{slug}/component.tsx`
+2. Create `registry/components/{slug}.json` (dependencies, tailwind config + docs metadata) and add the slug to `order`/`docsOrder` in `registry/manifest.json`
 3. Run `pnpm build:registry` to regenerate `registry.json`
 4. Add a showcase demo in `apps/www/app/page.tsx`
 5. Test with `uniqueui add {component-name}` in a fresh project

CONTRIBUTING.md

@@ -29,16 +29,17 @@ pnpm dev                   # Docs site at localhost:3000
 | Directory | Purpose |
 |-----------|---------|
 | `registry/` | Component source files — single source of truth |
-| `registry/config.ts` | Component registry definition (name, deps, tailwind config) |
+| `registry/components/<slug>.json` | Per-component manifest: build config (deps, files, tailwind) + docs metadata. See [ADR 0002](docs/adr/0002-per-slug-registry-manifests.md) |
+| `registry/manifest.json` | Demos `sourceFile` + `order` (install order) + `docsOrder` (docs-site display order) |
 | `packages/cli/` | `uniqueui-cli` npm package — handles `uniqueui add <component>` |
 | `apps/www/` | Next.js docs/showcase site |
 | `scripts/` | Build scripts (registry generation, pre-commit hook) |
 
 ## Adding a New Component
 
 1. Create `registry/<component-name>/component.tsx` with the component source
-2. Add an entry to `registry/config.ts` with `name`, `dependencies`, `files`, and optional `tailwindConfig`
-3. Add docs metadata to `registry/docs.json` for the component page and scenarios
+2. Create `registry/components/<slug>.json` — a `registry` block (`dependencies`, `files`, optional `tailwindConfig`/`tailwindCss`; the shared `cn` util is appended automatically, so don't list it) and a `docs` block (name, description, icon, props, optional `docs.overview`/`docs.scenarios`). See [ADR 0002](docs/adr/0002-per-slug-registry-manifests.md)
+3. Add the slug to both `order` and `docsOrder` in `registry/manifest.json`
 4. Add the live demo mapping to `registry/demos.tsx`
 5. Run `pnpm build:registry` from the root — this regenerates `registry.json`, refreshes `apps/www/public/registry/*` and **`apps/www/public/r/*`** (shadcn registry URLs), syncs `apps/www/components/ui/*`, and generates `apps/www/config/components.ts`, `apps/www/config/docs-scenarios.ts`, and `apps/www/config/demos.tsx`
 6. Test in the docs site: `cd apps/www && pnpm dev`
@@ -47,12 +48,12 @@ pnpm dev                   # Docs site at localhost:3000
 
 | Source (edit these) | Generated (do not edit by hand) |
 |---------------------|----------------------------------|
-| `registry/docs.json` | `apps/www/config/components.ts`, `apps/www/config/docs-scenarios.ts` |
+| `registry/components/<slug>.json` | `apps/www/config/components.ts`, `apps/www/config/docs-scenarios.ts` |
 | `registry/demos.tsx` | `apps/www/config/demos.tsx` |
 
-- **Policy:** Keep docs metadata authoring centralized in `registry/docs.json` unless a [documented migration](docs/adr/0001-registry-docs-metadata-storage.md) has happened. The ADR lists quantitative **migration triggers** (file size, conflict rate, ownership needs) and qualitative **friction signals** — open a discussion if friction grows, but do not split metadata files until triggers are met.
-- **When the model changes:** If an ADR supersedes 0001 (for example per-component `registry/<slug>/docs.json`), update this section, `BUILD.md`, and any `scripts/build-registry.ts` / CI drift checks in the same change series so contributors have a single coherent story.
-- After any edit to `registry/docs.json` or `registry/demos.tsx`, run `pnpm build:registry` and commit generated files under `apps/www/config/`, `apps/www/components/ui/`, `apps/www/public/registry/`, **`apps/www/public/r/`**, and root `registry.json` as required by CI.
+- **Model:** Registry metadata is authored as one manifest per component under `registry/components/<slug>.json`, aggregated by `scripts/build-registry.ts`. This supersedes the centralized `registry/docs.json` model — see [ADR 0002](docs/adr/0002-per-slug-registry-manifests.md) (which supersedes [ADR 0001](docs/adr/0001-registry-docs-metadata-storage.md)).
+- **When the model changes:** If a future ADR supersedes 0002, update this section, `BUILD.md`, and any `scripts/build-registry.ts` / CI drift checks in the same change series so contributors have a single coherent story.
+- After any edit under `registry/components/`, `registry/manifest.json`, or `registry/demos.tsx`, run `pnpm build:registry` and commit generated files under `apps/www/config/`, `apps/www/components/ui/`, `apps/www/public/registry/`, **`apps/www/public/r/`**, and root `registry.json` as required by CI.
 
 ## Component Design Rules
 

README.md

@@ -522,7 +522,7 @@ Registry (GitHub)
             Your project (shadcn components.json, @/lib/utils)
 ```
 
-1. **Registry** — Each component is defined in `registry/config.ts` and points at files like `registry/<slug>/component.tsx`. `build-registry.ts` outputs `registry.json`, split files under `apps/www/public/registry/`, **shadcn-format items under `apps/www/public/r/`**, and synced docs UI copies.
+1. **Registry** — Each component is defined in `registry/components/<slug>.json` (build config + docs metadata) and points at files like `registry/<slug>/component.tsx`. `build-registry.ts` aggregates these (ordered by `registry/manifest.json`) and outputs `registry.json`, split files under `apps/www/public/registry/`, **shadcn-format items under `apps/www/public/r/`**, and synced docs UI copies.
 2. **UniqueUI CLI** — Fetches the hosted registry, writes files to your project, and installs npm dependencies (and can add `utils/cn.ts`).
 3. **shadcn CLI** — Consumes the same component source via `public/r/<slug>.json` URLs; expects a standard shadcn project layout and `@/lib/utils` for `cn`.
 4. **Showcase** — The `apps/www` Next.js site serves as marketing landing page and component documentation with live previews and install commands.
@@ -570,8 +570,8 @@ node --version  # must be v18 or higher
 
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/my-component`)
-3. Add your component to `registry/` and update `registry/config.ts`
-4. Update `registry/docs.json` for docs metadata and `apps/www/config/demos.tsx` for the live demo
+3. Add your component to `registry/` and create `registry/components/<slug>.json` (build config + docs metadata), then add the slug to `order` and `docsOrder` in `registry/manifest.json`
+4. Add the live demo mapping in `registry/demos.tsx`
 5. Run `pnpm build:registry` to regenerate `registry.json`, refresh `apps/www/public/registry/*` and **`apps/www/public/r/*`**, sync `apps/www/components/ui/*`, and generate `apps/www/config/components.ts` plus `apps/www/config/docs-scenarios.ts`
 6. Run `pnpm build` to ensure everything compiles
 7. Submit a pull request

apps/www/README.md

@@ -85,7 +85,7 @@ When you ship an intentional visual change:
 If you are adding or changing a component, start in the repo root:
 
 - component source: `registry/<slug>/component.tsx`
-- docs metadata: `registry/docs.json`
+- build config + docs metadata: `registry/components/<slug>.json` (ordered by `registry/manifest.json`)
 - demo mappings: `registry/demos.tsx`
 
 Contributor workflow details live in the root [`CONTRIBUTING.md`](../../CONTRIBUTING.md) and [`BUILD.md`](../../BUILD.md).