feat: add a typed component registry with registry-driven CLI scaffolding, docs metadata integration, and flat-config ESLint across the monorepo

Author: minkinad

README.md

@@ -6,6 +6,7 @@ tokens, releases, and governance into ad hoc tooling.
 
 The repository is intentionally structured as a product, not just a package:
 
+- `packages/registry` is the typed component registry shared by CLI and docs.
 - `packages/tokens` is the source of truth for design tokens and semantic themes.
 - `packages/ui` ships the baseline React component library.
 - `packages/utils` holds shared utilities with low abstraction overhead.
@@ -32,6 +33,7 @@ apps/
 packages/
   cli/                   CLI foundation for init/add workflows
   eslint-config/         Shared ESLint presets
+  registry/              Typed component manifests for docs and CLI
   tokens/                Design tokens, semantic themes, CSS variables
   tsconfig/              Shared TypeScript presets
   ui/                    React UI component package
@@ -45,6 +47,8 @@ tooling/                 Repo-level helper scripts and test setup
 
 - `@nim-ui/tokens`
   Primitive palette, semantic theme mapping, and exported CSS variables.
+- `@nim-ui/registry`
+  Typed component manifests, dependency metadata, and future registry surface.
 - `@nim-ui/ui`
   Baseline component library: `Button`, `Input`, `Card`, `Badge`.
 - `@nim-ui/utils`
@@ -123,6 +127,8 @@ ownership, domains, and environment configuration.
 
 The CLI package currently includes:
 
+- registry-driven component lookup
+- `nim-ui.config.ts` resolution with defaults
 - config resolution
 - `init`
 - local registry metadata
@@ -132,6 +138,20 @@ The CLI package currently includes:
 Future work can layer remote registry manifests, project adapters, and canary
 channels on top of the existing package boundaries without rewriting the CLI.
 
+## Canary Releases
+
+Canary publishing is intentionally not wired into default automation yet, but the
+repository is ready for it through Changesets pre mode. A practical next step is
+to add maintainer scripts for:
+
+- `changeset pre enter canary`
+- `changeset version`
+- `changeset publish --tag canary`
+- `changeset pre exit`
+
+That approach keeps stable releases and canary channels separate without forcing
+extra complexity into the default OSS workflow.
+
 ## Open-Source Baseline
 
 This repository includes:

apps/docs/.eslintrc.cjs

@@ -5,6 +5,7 @@ Next.js App Router docs and demo application for Nim UI.
 Goals:
 
 - show the path from tokens to semantic CSS variables to UI components
+- show registry metadata such as dependencies and token usage
 - keep documentation close to the code that maintainers ship
 - make content easy to extend without changing routing architecture
 - provide a polished demo surface for open-source adoption

apps/docs/README.md

@@ -1,4 +1,3 @@
-
 import { CodeBlock } from './code-block';
 import { ComponentPreview } from './component-preview';
 
@@ -35,6 +34,53 @@ export function ComponentPageTemplate({ page }: { page: ComponentPage }) {
         <CodeBlock code={page.code} label={`${page.title} example`} language="tsx" />
       </section>
 
+      <section className="space-y-5">
+        <h2 className="font-display text-3xl font-semibold">
+          System metadata
+        </h2>
+        <div className="grid gap-4 md:grid-cols-3">
+          <div className="rounded-[1.25rem] border border-border bg-white p-5">
+            <p className="text-xs font-semibold uppercase tracking-[0.18em] text-[var(--color-brand-red)]">
+              Registry
+            </p>
+            <p className="mt-3 text-lg font-semibold">{page.meta.registry}</p>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Category: {page.manifest.category}
+            </p>
+          </div>
+          <div className="rounded-[1.25rem] border border-border bg-white p-5">
+            <p className="text-xs font-semibold uppercase tracking-[0.18em] text-[var(--color-brand-red)]">
+              Tokens
+            </p>
+            <div className="mt-3 flex flex-wrap gap-2">
+              {page.meta.tokens.map((token) => (
+                <span
+                  className="rounded-full bg-accent px-3 py-1 text-xs font-medium text-accent-foreground"
+                  key={token}
+                >
+                  {token}
+                </span>
+              ))}
+            </div>
+          </div>
+          <div className="rounded-[1.25rem] border border-border bg-white p-5">
+            <p className="text-xs font-semibold uppercase tracking-[0.18em] text-[var(--color-brand-red)]">
+              Dependencies
+            </p>
+            <div className="mt-3 flex flex-wrap gap-2">
+              {page.meta.dependencies.map((dependency) => (
+                <span
+                  className="rounded-full border border-border px-3 py-1 text-xs font-medium text-foreground"
+                  key={dependency}
+                >
+                  {dependency}
+                </span>
+              ))}
+            </div>
+          </div>
+        </div>
+      </section>
+
       {page.sections.map((section) => (
         <section className="space-y-5" key={section.title}>
           <h2 className="font-display text-3xl font-semibold">

apps/docs/components/component-page-template.tsx

@@ -1,10 +1,16 @@
-import type { ComponentPage } from '../types';
+import { createComponentPage, defineComponentMeta } from '../types';
 
-export const badgePage: ComponentPage = {
-  slug: 'badge',
+export const meta = defineComponentMeta({
   title: 'Badge',
   description:
     'Badges provide compact labels for status, categorization, and lightweight emphasis.',
+  tokens: ['primary', 'primary-foreground', 'secondary', 'secondary-foreground', 'accent', 'accent-foreground', 'border', 'ring'],
+  dependencies: ['utils', 'tokens'],
+  registry: 'badge',
+});
+
+export const badgePage = createComponentPage(meta, {
+  slug: 'badge',
   eyebrow: 'Component',
   preview: 'badge',
   code: `import { Badge } from '@nim-ui/ui';\n\nexport function Example() {\n  return (\n    <div className="flex gap-2">\n      <Badge>Stable</Badge>\n      <Badge variant="secondary">Community</Badge>\n      <Badge variant="outline">Docs</Badge>\n    </div>\n  );\n}`,
@@ -16,4 +22,4 @@ export const badgePage: ComponentPage = {
       ],
     },
   ],
-};
+});

apps/docs/content/components/badge.ts

@@ -1,10 +1,16 @@
-import type { ComponentPage } from '../types';
+import { createComponentPage, defineComponentMeta } from '../types';
 
-export const buttonPage: ComponentPage = {
-  slug: 'button',
+export const meta = defineComponentMeta({
   title: 'Button',
   description:
     'Buttons provide semantic variants and size options with accessible focus styles and SSR-safe rendering.',
+  tokens: ['primary', 'primary-foreground', 'radius', 'ring', 'secondary', 'border'],
+  dependencies: ['utils', 'tokens'],
+  registry: 'button',
+});
+
+export const buttonPage = createComponentPage(meta, {
+  slug: 'button',
   eyebrow: 'Component',
   preview: 'button',
   code: `import { Button } from '@nim-ui/ui';\n\nexport function Example() {\n  return (\n    <div className="flex gap-3">\n      <Button>Primary</Button>\n      <Button variant="secondary">Secondary</Button>\n      <Button variant="outline">Outline</Button>\n    </div>\n  );\n}`,
@@ -16,4 +22,4 @@ export const buttonPage: ComponentPage = {
       ],
     },
   ],
-};
+});

apps/docs/content/components/button.ts

@@ -1,10 +1,16 @@
-import type { ComponentPage } from '../types';
+import { createComponentPage, defineComponentMeta } from '../types';
 
-export const cardPage: ComponentPage = {
-  slug: 'card',
+export const meta = defineComponentMeta({
   title: 'Card',
   description:
     'Card primitives help structure panels, settings surfaces, and summary blocks without introducing behavior-specific abstractions.',
+  tokens: ['background', 'card', 'card-foreground', 'border', 'muted-foreground', 'radius'],
+  dependencies: ['utils', 'tokens'],
+  registry: 'card',
+});
+
+export const cardPage = createComponentPage(meta, {
+  slug: 'card',
   eyebrow: 'Component',
   preview: 'card',
   code: `import {\n  Card,\n  CardContent,\n  CardDescription,\n  CardHeader,\n  CardTitle,\n} from '@nim-ui/ui';\n\nexport function Example() {\n  return (\n    <Card>\n      <CardHeader>\n        <CardTitle>Workspace analytics</CardTitle>\n        <CardDescription>Weekly delivery overview.</CardDescription>\n      </CardHeader>\n      <CardContent>Track releases and contributor activity.</CardContent>\n    </Card>\n  );\n}`,
@@ -16,4 +22,4 @@ export const cardPage: ComponentPage = {
       ],
     },
   ],
-};
+});

apps/docs/content/components/card.ts

@@ -1,10 +1,16 @@
-import type { ComponentPage } from '../types';
+import { createComponentPage, defineComponentMeta } from '../types';
 
-export const inputPage: ComponentPage = {
-  slug: 'input',
+export const meta = defineComponentMeta({
   title: 'Input',
   description:
     'Inputs stay lightweight and accessible while inheriting semantic focus, border, and placeholder behavior from the theme layer.',
+  tokens: ['background', 'foreground', 'input', 'muted-foreground', 'radius', 'ring'],
+  dependencies: ['utils', 'tokens'],
+  registry: 'input',
+});
+
+export const inputPage = createComponentPage(meta, {
+  slug: 'input',
   eyebrow: 'Component',
   preview: 'input',
   code: `import { Input } from '@nim-ui/ui';\n\nexport function Example() {\n  return <Input placeholder="[email protected]" type="email" />;\n}`,
@@ -16,4 +22,4 @@ export const inputPage: ComponentPage = {
       ],
     },
   ],
-};
+});

apps/docs/content/components/input.ts

@@ -11,6 +11,7 @@ export const themingPage: DocPage = {
       title: 'Token layers',
       paragraphs: [
         'Primitive colors live in the tokens package under brand, accent, neutral, and semantic groups. Applications consume semantic variables such as background, card, and primary instead of raw brand values.',
+        'The pipeline in this repository is explicit: registry metadata points to semantic tokens, the tokens package maps them to CSS variables, the UI package consumes those variables, and the docs app demonstrates the same system without a separate theme fork.',
       ],
       codeBlocks: [
         {
@@ -44,5 +45,18 @@ export const themingPage: DocPage = {
         },
       ],
     },
+    {
+      title: 'End-to-end pipeline',
+      paragraphs: [
+        'The docs are not a disconnected marketing surface. Each component page carries typed metadata that mirrors the registry, so tokens and dependencies shown in docs stay aligned with the component ecosystem contract.',
+      ],
+      codeBlocks: [
+        {
+          label: 'Pipeline',
+          language: 'bash',
+          code: `registry -> docs meta -> design tokens -> CSS variables -> @nim-ui/ui -> docs and consumer apps`,
+        },
+      ],
+    },
   ],
 };

apps/docs/content/docs/theming.ts

@@ -1,3 +1,11 @@
+import {
+  getRegistryComponent,
+  type RegistryComponentManifest,
+  type RegistryComponentName,
+  type RegistryDependency,
+  type RegistryTokenReference,
+} from '@nim-ui/registry';
+
 export interface CodeBlockContent {
   label: string;
   language: 'bash' | 'tsx' | 'css' | 'json';
@@ -20,6 +28,57 @@ export interface DocPage {
 }
 
 export interface ComponentPage extends DocPage {
-  preview: 'button' | 'input' | 'card' | 'badge';
+  manifest: RegistryComponentManifest;
+  meta: ComponentDocMeta;
+  preview: RegistryComponentName;
+  code: string;
+}
+
+export interface ComponentDocMeta {
+  title: string;
+  description: string;
+  tokens: RegistryTokenReference[];
+  dependencies: RegistryDependency[];
+  registry: RegistryComponentName;
+}
+
+export interface ComponentPageContent {
+  slug: RegistryComponentName;
+  eyebrow: string;
+  preview: RegistryComponentName;
   code: string;
+  sections: DocSection[];
+}
+
+export function defineComponentMeta(meta: ComponentDocMeta) {
+  const manifest = getRegistryComponent(meta.registry);
+
+  if (meta.dependencies.join('|') !== manifest.dependencies.join('|')) {
+    throw new Error(
+      `Component doc meta for "${meta.registry}" must mirror registry dependencies.`,
+    );
+  }
+
+  if (meta.tokens.join('|') !== manifest.tokens.join('|')) {
+    throw new Error(
+      `Component doc meta for "${meta.registry}" must mirror registry tokens.`,
+    );
+  }
+
+  return meta;
+}
+
+export function createComponentPage(
+  meta: ComponentDocMeta,
+  content: ComponentPageContent,
+): ComponentPage {
+  const manifest = getRegistryComponent(meta.registry);
+
+  return {
+    ...content,
+    description: meta.description,
+    manifest,
+    meta,
+    title: meta.title,
+  };
 }