From e496a844df765bb73a66bbc9242973b6993b5bd0 Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 15:25:47 -0500
Subject: [PATCH 01/10] feat(www): refresh UI theme and typography

- Update color scheme from nature tones to neutral grayscale palette
- Replace Montserrat font with Inter for cleaner typography
- Change headings from font-bold to font-semibold throughout
- Add text-balance and improved line-height for better readability
- Update registry JSON files to reflect component changes
---
 apps/www/public/r/hero.json                   |   2 +-
 apps/www/public/r/logo.json                   |   2 +-
 apps/www/public/r/promo.json                  |   2 +-
 apps/www/public/r/store.json                  |   2 +-
 apps/www/public/r/theme.json                  |   2 +-
 apps/www/src/app/(registry)/page.tsx          |  10 +-
 .../app/(registry)/registry/[name]/page.tsx   |   2 +-
 apps/www/src/app/(registry)/tokens/page.tsx   |  24 +--
 .../src/app/demo/[name]/blocks/store-page.tsx |   4 +-
 apps/www/src/app/error.tsx                    |   4 +-
 apps/www/src/app/globals.css                  | 141 +++++++++---------
 apps/www/src/app/layout.tsx                   |   8 +-
 apps/www/src/app/not-found.tsx                |   2 +-
 apps/www/src/components/hero.tsx              |   6 +-
 apps/www/src/components/logo.tsx              |   2 +-
 apps/www/src/components/promo.tsx             |   4 +-
 16 files changed, 114 insertions(+), 103 deletions(-)

diff --git a/apps/www/public/r/hero.json b/apps/www/public/r/hero.json
index 476bb5f..010e307 100644
--- a/apps/www/public/r/hero.json
+++ b/apps/www/public/r/hero.json
@@ -11,7 +11,7 @@
   "files": [
     {
       "path": "src/components/hero.tsx",
-      "content": "import Image from \"next/image\";\nimport Link from \"next/link\";\n\nimport { Badge } from \"@/components/ui/badge\";\nimport { Button } from \"@/components/ui/button\";\n\nexport function Hero({\n  title,\n  description,\n  buttonText,\n  buttonLink,\n  backgroundImage,\n}: {\n  title: string;\n  description: string;\n  buttonText: string;\n  buttonLink: string;\n  backgroundImage: string;\n}) {\n  return (\n    <div className=\"relative h-[600px] w-full bg-foreground/10\">\n      <div className=\"relative z-10 flex h-full flex-col items-center justify-center px-4 text-center sm:px-6 lg:px-8\">\n        <div className=\"mx-auto max-w-3xl\">\n          <Badge variant=\"secondary\" className=\"mb-4\">\n            Coming soon\n          </Badge>\n          <h1 className=\"font-bold text-4xl tracking-tight sm:text-5xl md:text-6xl\">\n            {title}\n          </h1>\n          <p className=\"mt-6 text-xl\">{description}</p>\n          <div className=\"mt-10\">\n            <Button\n              asChild\n              variant=\"secondary\"\n              size=\"lg\"\n              className=\"rounded-md px-8\"\n            >\n              <Link href={buttonLink}>{buttonText}</Link>\n            </Button>\n          </div>\n        </div>\n      </div>\n    </div>\n  );\n}\n",
+      "content": "import Image from \"next/image\";\nimport Link from \"next/link\";\n\nimport { Badge } from \"@/components/ui/badge\";\nimport { Button } from \"@/components/ui/button\";\n\nexport function Hero({\n  title,\n  description,\n  buttonText,\n  buttonLink,\n  backgroundImage,\n}: {\n  title: string;\n  description: string;\n  buttonText: string;\n  buttonLink: string;\n  backgroundImage: string;\n}) {\n  return (\n    <div className=\"relative h-[600px] w-full bg-foreground/10\">\n      <div className=\"relative z-10 flex h-full flex-col items-center justify-center px-4 text-center sm:px-6 lg:px-8\">\n        <div className=\"mx-auto max-w-3xl\">\n          <Badge variant=\"secondary\" className=\"mb-4\">\n            Coming soon\n          </Badge>\n          <h1 className=\"font-semibold text-4xl tracking-tight text-balance sm:text-5xl md:text-6xl\">\n            {title}\n          </h1>\n          <p className=\"mt-6 text-xl text-muted-foreground leading-7\">{description}</p>\n          <div className=\"mt-10\">\n            <Button\n              asChild\n              variant=\"secondary\"\n              size=\"lg\"\n              className=\"rounded-md px-8\"\n            >\n              <Link href={buttonLink}>{buttonText}</Link>\n            </Button>\n          </div>\n        </div>\n      </div>\n    </div>\n  );\n}\n",
       "type": "registry:component"
     },
     {
diff --git a/apps/www/public/r/logo.json b/apps/www/public/r/logo.json
index d37960f..0483b60 100644
--- a/apps/www/public/r/logo.json
+++ b/apps/www/public/r/logo.json
@@ -9,7 +9,7 @@
   "files": [
     {
       "path": "src/components/logo.tsx",
-      "content": "export function Logo() {\n  return (\n    <div className=\"flex items-center gap-2\">\n      <svg\n        xmlns=\"http://www.w3.org/2000/svg\"\n        viewBox=\"0 0 24 24\"\n        strokeWidth=\"2\"\n        strokeLinecap=\"round\"\n        strokeLinejoin=\"round\"\n        className=\"size-8\"\n        role=\"graphics-symbol\"\n      >\n        <circle className=\"fill-primary\" cx=\"13.5\" cy=\"6.5\" r=\"2.5\" />\n        <circle className=\"fill-primary\" cx=\"19\" cy=\"13\" r=\"2.5\" />\n        <circle className=\"fill-primary\" cx=\"13.5\" cy=\"19.5\" r=\"2.5\" />\n        <circle className=\"fill-primary\" cx=\"6.5\" cy=\"13\" r=\"2.5\" />\n      </svg>\n\n      <h1 className=\"font-bold\">Brand Name</h1>\n    </div>\n  );\n}\n",
+      "content": "export function Logo() {\n  return (\n    <div className=\"flex items-center gap-2\">\n      <svg\n        xmlns=\"http://www.w3.org/2000/svg\"\n        viewBox=\"0 0 24 24\"\n        strokeWidth=\"2\"\n        strokeLinecap=\"round\"\n        strokeLinejoin=\"round\"\n        className=\"size-8\"\n        role=\"graphics-symbol\"\n      >\n        <circle className=\"fill-primary\" cx=\"13.5\" cy=\"6.5\" r=\"2.5\" />\n        <circle className=\"fill-primary\" cx=\"19\" cy=\"13\" r=\"2.5\" />\n        <circle className=\"fill-primary\" cx=\"13.5\" cy=\"19.5\" r=\"2.5\" />\n        <circle className=\"fill-primary\" cx=\"6.5\" cy=\"13\" r=\"2.5\" />\n      </svg>\n\n      <h1 className=\"font-semibold\">Brand Name</h1>\n    </div>\n  );\n}\n",
       "type": "registry:component"
     },
     {
diff --git a/apps/www/public/r/promo.json b/apps/www/public/r/promo.json
index fc5ee09..c084c87 100644
--- a/apps/www/public/r/promo.json
+++ b/apps/www/public/r/promo.json
@@ -10,7 +10,7 @@
   "files": [
     {
       "path": "src/components/promo.tsx",
-      "content": "import Image from \"next/image\";\nimport Link from \"next/link\";\n\nimport { Button } from \"@/components/ui/button\";\n\nexport function Promo({\n  title,\n  description,\n  buttonText,\n  buttonLink,\n  backgroundImage,\n}: {\n  title: string;\n  description: string;\n  buttonText: string;\n  buttonLink: string;\n  backgroundImage: string;\n}) {\n  return (\n    <div className=\"relative h-[300px] w-full bg-foreground/10\">\n      <div className=\"relative z-10 flex h-full flex-col justify-center gap-3 px-8 py-3\">\n        <h1 className=\"font-bold text-3xl tracking-tight md:text-4xl\">\n          {title}\n        </h1>\n        <p>{description}</p>\n        <div>\n          <Button asChild size=\"lg\" className=\"rounded-md\">\n            <Link href={buttonLink}>{buttonText}</Link>\n          </Button>\n        </div>\n      </div>\n    </div>\n  );\n}\n",
+      "content": "import Image from \"next/image\";\nimport Link from \"next/link\";\n\nimport { Button } from \"@/components/ui/button\";\n\nexport function Promo({\n  title,\n  description,\n  buttonText,\n  buttonLink,\n  backgroundImage,\n}: {\n  title: string;\n  description: string;\n  buttonText: string;\n  buttonLink: string;\n  backgroundImage: string;\n}) {\n  return (\n    <div className=\"relative h-[300px] w-full bg-foreground/10\">\n      <div className=\"relative z-10 flex h-full flex-col justify-center gap-3 px-8 py-3\">\n        <h1 className=\"font-semibold text-3xl tracking-tight text-balance md:text-4xl\">\n          {title}\n        </h1>\n        <p className=\"leading-7\">{description}</p>\n        <div>\n          <Button asChild size=\"lg\" className=\"rounded-md\">\n            <Link href={buttonLink}>{buttonText}</Link>\n          </Button>\n        </div>\n      </div>\n    </div>\n  );\n}\n",
       "type": "registry:component"
     },
     {
diff --git a/apps/www/public/r/store.json b/apps/www/public/r/store.json
index 7a2f40e..cac6248 100644
--- a/apps/www/public/r/store.json
+++ b/apps/www/public/r/store.json
@@ -16,7 +16,7 @@
     },
     {
       "path": "src/app/demo/[name]/blocks/store-page.tsx",
-      "content": "import ProductGrid from \"@/components/product-grid\";\nimport { getCategories, getProducts } from \"@/lib/products\";\n\nexport default async function StorePage() {\n  const products = await getProducts();\n  const categories = await getCategories();\n\n  return (\n    <div className=\"flex min-h-screen flex-col\">\n      <main className=\"flex-1\">\n        <section className=\"py-12\">\n          <div className=\"container px-4 md:px-6\">\n            <div className=\"flex flex-col items-center justify-center space-y-4 text-center\">\n              <div className=\"space-y-2\">\n                <h1 className=\"font-bold text-3xl tracking-tighter sm:text-4xl md:text-5xl\">\n                  Welcome to Store\n                </h1>\n\n                <p className=\"mx-auto max-w-[700px] text-gray-500 md:text-xl\">\n                  Shop our unique collection of products. Free shipping on all\n                  orders!\n                </p>\n              </div>\n            </div>\n          </div>\n        </section>\n\n        <section className=\"py-8 md:py-12\">\n          <div className=\"container px-4 md:px-6\">\n            <ProductGrid products={products} categories={categories} />\n          </div>\n        </section>\n      </main>\n    </div>\n  );\n}\n",
+      "content": "import ProductGrid from \"@/components/product-grid\";\nimport { getCategories, getProducts } from \"@/lib/products\";\n\nexport default async function StorePage() {\n  const products = await getProducts();\n  const categories = await getCategories();\n\n  return (\n    <div className=\"flex min-h-screen flex-col\">\n      <main className=\"flex-1\">\n        <section className=\"py-12\">\n          <div className=\"container px-4 md:px-6\">\n            <div className=\"flex flex-col items-center justify-center space-y-4 text-center\">\n              <div className=\"space-y-2\">\n                <h1 className=\"font-semibold text-3xl tracking-tight text-balance sm:text-4xl md:text-5xl\">\n                  Welcome to Store\n                </h1>\n\n                <p className=\"mx-auto max-w-[700px] text-muted-foreground leading-7 md:text-xl\">\n                  Shop our unique collection of products. Free shipping on all\n                  orders!\n                </p>\n              </div>\n            </div>\n          </div>\n        </section>\n\n        <section className=\"py-8 md:py-12\">\n          <div className=\"container px-4 md:px-6\">\n            <ProductGrid products={products} categories={categories} />\n          </div>\n        </section>\n      </main>\n    </div>\n  );\n}\n",
       "type": "registry:page",
       "target": "app/page.tsx"
     }
diff --git a/apps/www/public/r/theme.json b/apps/www/public/r/theme.json
index 38877cc..c46a365 100644
--- a/apps/www/public/r/theme.json
+++ b/apps/www/public/r/theme.json
@@ -9,7 +9,7 @@
   "files": [
     {
       "path": "src/app/globals.css",
-      "content": "@import \"tailwindcss\";\n@import \"tw-animate-css\";\n\n@custom-variant dark (&:is(.dark *));\n\n:root {\n  --background: oklch(0.97 0.01 80.72);\n  --foreground: oklch(0.3 0.04 30.2);\n\n  --card: oklch(0.97 0.01 80.72);\n  --card-foreground: oklch(0.3 0.04 30.2);\n\n  --popover: oklch(0.97 0.01 80.72);\n  --popover-foreground: oklch(0.3 0.04 30.2);\n\n  --primary: oklch(0.52 0.13 144.17);\n  --primary-foreground: oklch(1.0 0 0);\n\n  --secondary: oklch(0.96 0.02 147.64);\n  --secondary-foreground: oklch(0.43 0.12 144.31);\n\n  --muted: oklch(0.94 0.01 74.42);\n  --muted-foreground: oklch(0.45 0.05 39.21);\n\n  --accent: oklch(0.9 0.05 146.04);\n  --accent-foreground: oklch(0.43 0.12 144.31);\n\n  --destructive: oklch(0.54 0.19 26.72);\n  --destructive-foreground: oklch(1.0 0 0);\n\n  --border: oklch(0.88 0.02 74.64);\n  --input: oklch(0.88 0.02 74.64);\n  --ring: oklch(0.52 0.13 144.17);\n\n  --chart-1: oklch(0.67 0.16 144.21);\n  --chart-2: oklch(0.58 0.14 144.18);\n  --chart-3: oklch(0.52 0.13 144.17);\n  --chart-4: oklch(0.43 0.12 144.31);\n  --chart-5: oklch(0.22 0.05 145.73);\n\n  --sidebar: oklch(0.94 0.01 74.42);\n  --sidebar-foreground: oklch(0.3 0.04 30.2);\n  --sidebar-primary: oklch(0.52 0.13 144.17);\n  --sidebar-primary-foreground: oklch(1.0 0 0);\n  --sidebar-accent: oklch(0.9 0.05 146.04);\n  --sidebar-accent-foreground: oklch(0.43 0.12 144.31);\n  --sidebar-border: oklch(0.88 0.02 74.64);\n  --sidebar-ring: oklch(0.52 0.13 144.17);\n\n  --radius: 0.5rem;\n}\n\n.dark {\n  --background: oklch(0.15 0.01 74.42);\n  --foreground: oklch(0.95 0.02 80.72);\n\n  --card: oklch(0.12 0.01 80.72);\n  --card-foreground: oklch(0.95 0.02 80.72);\n\n  --popover: oklch(0.12 0.01 80.72);\n  --popover-foreground: oklch(0.95 0.02 80.72);\n\n  --primary: oklch(0.58 0.15 144.17);\n  --primary-foreground: oklch(0.09 0.01 80.72);\n\n  --secondary: oklch(0.15 0.02 147.64);\n  --secondary-foreground: oklch(0.65 0.12 144.31);\n\n  --muted: oklch(0.18 0.01 74.42);\n  --muted-foreground: oklch(0.65 0.03 74.42);\n\n  --accent: oklch(0.22 0.04 146.04);\n  --accent-foreground: oklch(0.65 0.12 144.31);\n\n  --destructive: oklch(0.62 0.22 26.72);\n  --destructive-foreground: oklch(0.95 0.02 80.72);\n\n  --border: oklch(0.22 0.02 74.64);\n  --input: oklch(0.22 0.02 74.64);\n  --ring: oklch(0.58 0.15 144.17);\n\n  --chart-1: oklch(0.72 0.16 144.21);\n  --chart-2: oklch(0.63 0.14 144.18);\n  --chart-3: oklch(0.58 0.15 144.17);\n  --chart-4: oklch(0.48 0.12 144.31);\n  --chart-5: oklch(0.35 0.08 145.73);\n\n  --sidebar: oklch(0.15 0.01 74.42);\n  --sidebar-foreground: oklch(0.95 0.02 80.72);\n  --sidebar-primary: oklch(0.58 0.15 144.17);\n  --sidebar-primary-foreground: oklch(0.09 0.01 80.72);\n  --sidebar-accent: oklch(0.22 0.04 146.04);\n  --sidebar-accent-foreground: oklch(0.65 0.12 144.31);\n  --sidebar-border: oklch(0.22 0.02 74.64);\n  --sidebar-ring: oklch(0.58 0.15 144.17);\n}\n\n@theme inline {\n  --color-background: var(--background);\n  --color-foreground: var(--foreground);\n\n  --color-primary: var(--primary);\n  --color-primary-foreground: var(--primary-foreground);\n\n  --color-secondary: var(--secondary);\n  --color-secondary-foreground: var(--secondary-foreground);\n  --color-accent: var(--accent);\n  --color-accent-foreground: var(--accent-foreground);\n\n  --color-muted: var(--muted);\n  --color-muted-foreground: var(--muted-foreground);\n  --color-card: var(--card);\n  --color-card-foreground: var(--card-foreground);\n  --color-popover: var(--popover);\n  --color-popover-foreground: var(--popover-foreground);\n\n  --color-border: var(--border);\n  --color-input: var(--input);\n  --color-ring: var(--ring);\n\n  --color-destructive: var(--destructive);\n  --color-destructive-foreground: var(--destructive-foreground);\n\n  --color-chart-1: var(--chart-1);\n  --color-chart-2: var(--chart-2);\n  --color-chart-3: var(--chart-3);\n  --color-chart-4: var(--chart-4);\n  --color-chart-5: var(--chart-5);\n\n  --color-sidebar: var(--sidebar);\n  --color-sidebar-foreground: var(--sidebar-foreground);\n  --color-sidebar-primary: var(--sidebar-primary);\n  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);\n  --color-sidebar-accent: var(--sidebar-accent);\n  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);\n  --color-sidebar-border: var(--sidebar-border);\n  --color-sidebar-ring: var(--sidebar-ring);\n\n  --font-sans: var(--font-sans);\n  --font-serif: var(--font-serif);\n  --font-mono: var(--font-mono);\n\n  --radius-sm: calc(var(--radius) - 4px);\n  --radius-md: calc(var(--radius) - 2px);\n  --radius-lg: var(--radius);\n  --radius-xl: calc(var(--radius) + 4px);\n\n  --shadow-2xs: var(--shadow-2xs);\n  --shadow-xs: var(--shadow-xs);\n  --shadow-sm: var(--shadow-sm);\n  --shadow: var(--shadow);\n  --shadow-md: var(--shadow-md);\n  --shadow-lg: var(--shadow-lg);\n  --shadow-xl: var(--shadow-xl);\n  --shadow-2xl: var(--shadow-2xl);\n}\n\n@layer base {\n  *,\n  ::after,\n  ::before,\n  ::backdrop,\n  ::file-selector-button {\n    border-color: var(--color-border, currentColor);\n  }\n}\n",
+      "content": "@import \"tailwindcss\";\n@import \"tw-animate-css\";\n\n@custom-variant dark (&:is(.dark *));\n\n:root {\n  --radius: 0.625rem;\n  --background: oklch(1 0 0);\n  --foreground: oklch(0.145 0 0);\n\n  --card: oklch(1 0 0);\n  --card-foreground: oklch(0.145 0 0);\n\n  --popover: oklch(1 0 0);\n  --popover-foreground: oklch(0.145 0 0);\n\n  --primary: oklch(0.205 0 0);\n  --primary-foreground: oklch(0.985 0 0);\n\n  --secondary: oklch(0.97 0 0);\n  --secondary-foreground: oklch(0.205 0 0);\n\n  --muted: oklch(0.97 0 0);\n  --muted-foreground: oklch(0.556 0 0);\n\n  --accent: oklch(0.97 0 0);\n  --accent-foreground: oklch(0.205 0 0);\n\n  --destructive: oklch(0.577 0.245 27.325);\n  --destructive-foreground: oklch(0.985 0 0);\n\n  --border: oklch(0.922 0 0);\n  --input: oklch(0.922 0 0);\n  --ring: oklch(0.708 0 0);\n\n  --chart-1: oklch(0.646 0.222 41.116);\n  --chart-2: oklch(0.6 0.118 184.704);\n  --chart-3: oklch(0.398 0.07 227.392);\n  --chart-4: oklch(0.828 0.189 84.429);\n  --chart-5: oklch(0.769 0.188 70.08);\n\n  --sidebar: oklch(0.985 0 0);\n  --sidebar-foreground: oklch(0.145 0 0);\n  --sidebar-primary: oklch(0.205 0 0);\n  --sidebar-primary-foreground: oklch(0.985 0 0);\n  --sidebar-accent: oklch(0.97 0 0);\n  --sidebar-accent-foreground: oklch(0.205 0 0);\n  --sidebar-border: oklch(0.922 0 0);\n  --sidebar-ring: oklch(0.708 0 0);\n}\n\n.dark {\n  --background: oklch(0.145 0 0);\n  --foreground: oklch(0.985 0 0);\n\n  --card: oklch(0.205 0 0);\n  --card-foreground: oklch(0.985 0 0);\n\n  --popover: oklch(0.205 0 0);\n  --popover-foreground: oklch(0.985 0 0);\n\n  --primary: oklch(0.922 0 0);\n  --primary-foreground: oklch(0.205 0 0);\n\n  --secondary: oklch(0.269 0 0);\n  --secondary-foreground: oklch(0.985 0 0);\n\n  --muted: oklch(0.269 0 0);\n  --muted-foreground: oklch(0.708 0 0);\n\n  --accent: oklch(0.269 0 0);\n  --accent-foreground: oklch(0.985 0 0);\n\n  --destructive: oklch(0.704 0.191 22.216);\n  --destructive-foreground: oklch(0.985 0 0);\n\n  --border: oklch(1 0 0 / 10%);\n  --input: oklch(1 0 0 / 15%);\n  --ring: oklch(0.556 0 0);\n\n  --chart-1: oklch(0.488 0.243 264.376);\n  --chart-2: oklch(0.696 0.17 162.48);\n  --chart-3: oklch(0.769 0.188 70.08);\n  --chart-4: oklch(0.627 0.265 303.9);\n  --chart-5: oklch(0.645 0.246 16.439);\n\n  --sidebar: oklch(0.205 0 0);\n  --sidebar-foreground: oklch(0.985 0 0);\n  --sidebar-primary: oklch(0.488 0.243 264.376);\n  --sidebar-primary-foreground: oklch(0.985 0 0);\n  --sidebar-accent: oklch(0.269 0 0);\n  --sidebar-accent-foreground: oklch(0.985 0 0);\n  --sidebar-border: oklch(1 0 0 / 10%);\n  --sidebar-ring: oklch(0.556 0 0);\n}\n\n@theme inline {\n  --color-background: var(--background);\n  --color-foreground: var(--foreground);\n\n  --color-primary: var(--primary);\n  --color-primary-foreground: var(--primary-foreground);\n\n  --color-secondary: var(--secondary);\n  --color-secondary-foreground: var(--secondary-foreground);\n  --color-accent: var(--accent);\n  --color-accent-foreground: var(--accent-foreground);\n\n  --color-muted: var(--muted);\n  --color-muted-foreground: var(--muted-foreground);\n  --color-card: var(--card);\n  --color-card-foreground: var(--card-foreground);\n  --color-popover: var(--popover);\n  --color-popover-foreground: var(--popover-foreground);\n\n  --color-border: var(--border);\n  --color-input: var(--input);\n  --color-ring: var(--ring);\n\n  --color-destructive: var(--destructive);\n  --color-destructive-foreground: var(--destructive-foreground);\n\n  --color-chart-1: var(--chart-1);\n  --color-chart-2: var(--chart-2);\n  --color-chart-3: var(--chart-3);\n  --color-chart-4: var(--chart-4);\n  --color-chart-5: var(--chart-5);\n\n  --color-sidebar: var(--sidebar);\n  --color-sidebar-foreground: var(--sidebar-foreground);\n  --color-sidebar-primary: var(--sidebar-primary);\n  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);\n  --color-sidebar-accent: var(--sidebar-accent);\n  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);\n  --color-sidebar-border: var(--sidebar-border);\n  --color-sidebar-ring: var(--sidebar-ring);\n\n  --font-sans: var(--font-sans);\n  --font-inter: var(--font-inter);\n  --font-mono: var(--font-mono);\n\n  --radius-sm: calc(var(--radius) - 4px);\n  --radius-md: calc(var(--radius) - 2px);\n  --radius-lg: var(--radius);\n  --radius-xl: calc(var(--radius) + 4px);\n\n  --shadow-2xs: var(--shadow-2xs);\n  --shadow-xs: var(--shadow-xs);\n  --shadow-sm: var(--shadow-sm);\n  --shadow: var(--shadow);\n  --shadow-md: var(--shadow-md);\n  --shadow-lg: var(--shadow-lg);\n  --shadow-xl: var(--shadow-xl);\n  --shadow-2xl: var(--shadow-2xl);\n}\n\n@layer base {\n  *,\n  ::after,\n  ::before,\n  ::backdrop,\n  ::file-selector-button {\n    border-color: var(--color-border, currentColor);\n  }\n\n  body {\n    font-family: var(--font-sans);\n    font-synthesis-weight: none;\n    text-rendering: optimizeLegibility;\n    -webkit-font-smoothing: antialiased;\n    -moz-osx-font-smoothing: grayscale;\n  }\n}\n",
       "type": "registry:style",
       "target": "app/globals.css"
     },
diff --git a/apps/www/src/app/(registry)/page.tsx b/apps/www/src/app/(registry)/page.tsx
index 648e924..a2a7c34 100644
--- a/apps/www/src/app/(registry)/page.tsx
+++ b/apps/www/src/app/(registry)/page.tsx
@@ -20,10 +20,10 @@ export default function Home() {
     <main className="container mt-4 p-5 md:mt-8 md:p-10">
       <div className="mb-8">
         <div className="space-y-2">
-          <h1 className="font-bold text-3xl tracking-tight md:text-4xl">
+          <h1 className="text-balance font-semibold text-3xl tracking-tight md:text-4xl">
             Registry
           </h1>
-          <p className="text-muted-foreground">
+          <p className="text-muted-foreground leading-7">
             Distribute your design system tokens, custom components, hooks,
             pages, and other files to any React project.
           </p>
@@ -134,7 +134,7 @@ export default function Home() {
       <div className="mb-4 rounded-lg border bg-card p-6">
         <div className="flex flex-col gap-2">
           <h2 className="font-semibold text-xl">MCP</h2>
-          <p className="mb-4 text-muted-foreground">
+          <p className="mb-4 text-muted-foreground leading-7">
             Integrate this registry with AI IDEs using Model Context Protocol
             (MCP) using the following configuration. This utilizes this
             Registry's theme tokens and CSS variables with the Shadcn CLI. To
@@ -155,7 +155,7 @@ export default function Home() {
       <div className="rounded-lg border bg-card p-6">
         <div className="flex flex-col gap-2">
           <h2 className="font-semibold text-xl">About</h2>
-          <p className="text-muted-foreground">
+          <p className="text-muted-foreground leading-7">
             This registry serves as a central repository for all UI components
             and blocks used in your applications. It helps maintain consistency
             across your products and speeds up development by providing
@@ -164,7 +164,7 @@ export default function Home() {
             components, and view examples of how they are used in different
             contexts.
           </p>
-          <p className="mt-2 text-muted-foreground">
+          <p className="mt-2 text-muted-foreground leading-7">
             To get begin, start with a block{" "}
             <span className="italic">
               (like the{" "}
diff --git a/apps/www/src/app/(registry)/registry/[name]/page.tsx b/apps/www/src/app/(registry)/registry/[name]/page.tsx
index e5d7a3c..19b197b 100644
--- a/apps/www/src/app/(registry)/registry/[name]/page.tsx
+++ b/apps/www/src/app/(registry)/registry/[name]/page.tsx
@@ -37,7 +37,7 @@ export default async function RegistryItemPage({
               Back to Home
             </Link>
           </Button>
-          <h1 className="font-bold text-3xl tracking-tight">
+          <h1 className="text-balance font-semibold text-3xl tracking-tight">
             {component.title}
           </h1>
         </div>
diff --git a/apps/www/src/app/(registry)/tokens/page.tsx b/apps/www/src/app/(registry)/tokens/page.tsx
index 35c0968..50b54b1 100644
--- a/apps/www/src/app/(registry)/tokens/page.tsx
+++ b/apps/www/src/app/(registry)/tokens/page.tsx
@@ -19,8 +19,10 @@ export default function TokensPage() {
           </Link>
         </Button>
 
-        <h1 className="font-bold text-3xl tracking-tight">Design Tokens</h1>
-        <p className="mt-1 text-muted-foreground">
+        <h1 className="text-balance font-semibold text-3xl tracking-tight">
+          Design Tokens
+        </h1>
+        <p className="mt-1 text-muted-foreground leading-7">
           A comprehensive overview of all color tokens used in the design system
         </p>
       </div>
@@ -28,12 +30,12 @@ export default function TokensPage() {
       {/* Fonts */}
       <section className="mb-12">
         <h2 className="mb-4 font-semibold text-xl">Fonts</h2>
-        <p className="mb-6 text-muted-foreground">
+        <p className="mb-6 text-muted-foreground leading-7">
           The core font families that define the primary typography.
         </p>
         <div className="grid grid-cols-1 gap-4">
           <FontBlock className="font-sans" />
-          <FontBlock className="font-serif" />
+          <FontBlock className="font-[family-name:var(--font-inter)]" />
           <FontBlock className="font-mono" />
         </div>
       </section>
@@ -41,7 +43,7 @@ export default function TokensPage() {
       {/* Primary Theme */}
       <section className="mb-12">
         <h2 className="mb-4 font-semibold text-xl">Primary Theme</h2>
-        <p className="mb-6 text-muted-foreground">
+        <p className="mb-6 text-muted-foreground leading-7">
           The core colors that define the primary theme and overall look of the
           interface.
         </p>
@@ -59,7 +61,7 @@ export default function TokensPage() {
       {/* Secondary & Accent */}
       <section className="mb-12">
         <h2 className="mb-4 font-semibold text-xl">Secondary & Accent</h2>
-        <p className="mb-6 text-muted-foreground">
+        <p className="mb-6 text-muted-foreground leading-7">
           Colors used for secondary elements and accents throughout the
           interface.
         </p>
@@ -80,7 +82,7 @@ export default function TokensPage() {
       {/* UI Component */}
       <section className="mb-12">
         <h2 className="mb-4 font-semibold text-xl">UI Component</h2>
-        <p className="mb-6 text-muted-foreground">
+        <p className="mb-6 text-muted-foreground leading-7">
           Colors used for specific UI components like cards, popovers, and muted
           elements.
         </p>
@@ -100,7 +102,7 @@ export default function TokensPage() {
       {/* Utility & Form */}
       <section className="mb-12">
         <h2 className="mb-4 font-semibold text-xl">Utility & Form</h2>
-        <p className="mb-6 text-muted-foreground">
+        <p className="mb-6 text-muted-foreground leading-7">
           Colors used for borders, inputs, and other utility elements.
         </p>
         <div className="grid grid-cols-1 gap-4 md:grid-cols-3">
@@ -113,7 +115,7 @@ export default function TokensPage() {
       {/* Status & Feedback */}
       <section className="mb-12">
         <h2 className="mb-4 font-semibold text-xl">Status & Feedback</h2>
-        <p className="mb-6 text-muted-foreground">
+        <p className="mb-6 text-muted-foreground leading-7">
           Colors used to indicate different states and provide feedback to
           users.
         </p>
@@ -129,7 +131,7 @@ export default function TokensPage() {
       {/* Chart & Visualization */}
       <section className="mb-12">
         <h2 className="mb-4 font-semibold text-xl">Chart & Visualization</h2>
-        <p className="mb-6 text-muted-foreground">
+        <p className="mb-6 text-muted-foreground leading-7">
           Colors used for data visualization and charts.
         </p>
         <div className="grid grid-cols-1 gap-4 md:grid-cols-3 lg:grid-cols-5">
@@ -144,7 +146,7 @@ export default function TokensPage() {
       {/* Sidebar & Navigation */}
       <section className="mb-12">
         <h2 className="mb-4 font-semibold text-xl">Sidebar & Navigation</h2>
-        <p className="mb-6 text-muted-foreground">
+        <p className="mb-6 text-muted-foreground leading-7">
           Colors specific to the sidebar and navigation components.
         </p>
         <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
diff --git a/apps/www/src/app/demo/[name]/blocks/store-page.tsx b/apps/www/src/app/demo/[name]/blocks/store-page.tsx
index 2410cea..8601729 100644
--- a/apps/www/src/app/demo/[name]/blocks/store-page.tsx
+++ b/apps/www/src/app/demo/[name]/blocks/store-page.tsx
@@ -12,11 +12,11 @@ export default async function StorePage() {
           <div className="container px-4 md:px-6">
             <div className="flex flex-col items-center justify-center space-y-4 text-center">
               <div className="space-y-2">
-                <h1 className="font-bold text-3xl tracking-tighter sm:text-4xl md:text-5xl">
+                <h1 className="text-balance font-semibold text-3xl tracking-tight sm:text-4xl md:text-5xl">
                   Welcome to Store
                 </h1>
 
-                <p className="mx-auto max-w-[700px] text-gray-500 md:text-xl">
+                <p className="mx-auto max-w-[700px] text-muted-foreground leading-7 md:text-xl">
                   Shop our unique collection of products. Free shipping on all
                   orders!
                 </p>
diff --git a/apps/www/src/app/error.tsx b/apps/www/src/app/error.tsx
index 3aa65ef..d1e1bef 100644
--- a/apps/www/src/app/error.tsx
+++ b/apps/www/src/app/error.tsx
@@ -28,10 +28,10 @@ export default function ErrorPage({
       <RegistrySidebar />
       <main className="flex w-full justify-center">
         <div className="flex min-h-screen w-full flex-col items-center justify-center text-center">
-          <h1 className="font-bold text-6xl text-muted-foreground tracking-tight md:text-8xl">
+          <h1 className="font-semibold text-6xl text-muted-foreground tracking-tight md:text-8xl">
             500
           </h1>
-          <h2 className="mt-4 font-bold text-2xl tracking-tight md:text-3xl">
+          <h2 className="mt-4 font-semibold text-2xl tracking-tight md:text-3xl">
             Something went wrong
           </h2>
           <div className="mt-6 flex gap-3">
diff --git a/apps/www/src/app/globals.css b/apps/www/src/app/globals.css
index 42d0ea6..d8888b1 100644
--- a/apps/www/src/app/globals.css
+++ b/apps/www/src/app/globals.css
@@ -4,95 +4,94 @@
 @custom-variant dark (&:is(.dark *));
 
 :root {
-  --background: oklch(0.97 0.01 80.72);
-  --foreground: oklch(0.3 0.04 30.2);
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
 
-  --card: oklch(0.97 0.01 80.72);
-  --card-foreground: oklch(0.3 0.04 30.2);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
 
-  --popover: oklch(0.97 0.01 80.72);
-  --popover-foreground: oklch(0.3 0.04 30.2);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
 
-  --primary: oklch(0.52 0.13 144.17);
-  --primary-foreground: oklch(1.0 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
 
-  --secondary: oklch(0.96 0.02 147.64);
-  --secondary-foreground: oklch(0.43 0.12 144.31);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
 
-  --muted: oklch(0.94 0.01 74.42);
-  --muted-foreground: oklch(0.45 0.05 39.21);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
 
-  --accent: oklch(0.9 0.05 146.04);
-  --accent-foreground: oklch(0.43 0.12 144.31);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
 
-  --destructive: oklch(0.54 0.19 26.72);
-  --destructive-foreground: oklch(1.0 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.985 0 0);
 
-  --border: oklch(0.88 0.02 74.64);
-  --input: oklch(0.88 0.02 74.64);
-  --ring: oklch(0.52 0.13 144.17);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
 
-  --chart-1: oklch(0.67 0.16 144.21);
-  --chart-2: oklch(0.58 0.14 144.18);
-  --chart-3: oklch(0.52 0.13 144.17);
-  --chart-4: oklch(0.43 0.12 144.31);
-  --chart-5: oklch(0.22 0.05 145.73);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
 
-  --sidebar: oklch(0.94 0.01 74.42);
-  --sidebar-foreground: oklch(0.3 0.04 30.2);
-  --sidebar-primary: oklch(0.52 0.13 144.17);
-  --sidebar-primary-foreground: oklch(1.0 0 0);
-  --sidebar-accent: oklch(0.9 0.05 146.04);
-  --sidebar-accent-foreground: oklch(0.43 0.12 144.31);
-  --sidebar-border: oklch(0.88 0.02 74.64);
-  --sidebar-ring: oklch(0.52 0.13 144.17);
-
-  --radius: 0.5rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
 }
 
 .dark {
-  --background: oklch(0.15 0.01 74.42);
-  --foreground: oklch(0.95 0.02 80.72);
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
 
-  --card: oklch(0.12 0.01 80.72);
-  --card-foreground: oklch(0.95 0.02 80.72);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
 
-  --popover: oklch(0.12 0.01 80.72);
-  --popover-foreground: oklch(0.95 0.02 80.72);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
 
-  --primary: oklch(0.58 0.15 144.17);
-  --primary-foreground: oklch(0.09 0.01 80.72);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
 
-  --secondary: oklch(0.15 0.02 147.64);
-  --secondary-foreground: oklch(0.65 0.12 144.31);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
 
-  --muted: oklch(0.18 0.01 74.42);
-  --muted-foreground: oklch(0.65 0.03 74.42);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
 
-  --accent: oklch(0.22 0.04 146.04);
-  --accent-foreground: oklch(0.65 0.12 144.31);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
 
-  --destructive: oklch(0.62 0.22 26.72);
-  --destructive-foreground: oklch(0.95 0.02 80.72);
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.985 0 0);
 
-  --border: oklch(0.22 0.02 74.64);
-  --input: oklch(0.22 0.02 74.64);
-  --ring: oklch(0.58 0.15 144.17);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
 
-  --chart-1: oklch(0.72 0.16 144.21);
-  --chart-2: oklch(0.63 0.14 144.18);
-  --chart-3: oklch(0.58 0.15 144.17);
-  --chart-4: oklch(0.48 0.12 144.31);
-  --chart-5: oklch(0.35 0.08 145.73);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
 
-  --sidebar: oklch(0.15 0.01 74.42);
-  --sidebar-foreground: oklch(0.95 0.02 80.72);
-  --sidebar-primary: oklch(0.58 0.15 144.17);
-  --sidebar-primary-foreground: oklch(0.09 0.01 80.72);
-  --sidebar-accent: oklch(0.22 0.04 146.04);
-  --sidebar-accent-foreground: oklch(0.65 0.12 144.31);
-  --sidebar-border: oklch(0.22 0.02 74.64);
-  --sidebar-ring: oklch(0.58 0.15 144.17);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
 }
 
 @theme inline {
@@ -137,7 +136,7 @@
   --color-sidebar-ring: var(--sidebar-ring);
 
   --font-sans: var(--font-sans);
-  --font-serif: var(--font-serif);
+  --font-inter: var(--font-inter);
   --font-mono: var(--font-mono);
 
   --radius-sm: calc(var(--radius) - 4px);
@@ -163,4 +162,12 @@
   ::file-selector-button {
     border-color: var(--color-border, currentColor);
   }
+
+  body {
+    font-family: var(--font-sans);
+    font-synthesis-weight: none;
+    text-rendering: optimizeLegibility;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
 }
diff --git a/apps/www/src/app/layout.tsx b/apps/www/src/app/layout.tsx
index 7aa07aa..af17739 100644
--- a/apps/www/src/app/layout.tsx
+++ b/apps/www/src/app/layout.tsx
@@ -1,7 +1,7 @@
 import { Analytics } from "@vercel/analytics/next";
 import { SpeedInsights } from "@vercel/speed-insights/next";
 import type { Metadata } from "next";
-import { Geist, Geist_Mono, Montserrat } from "next/font/google";
+import { Geist, Geist_Mono, Inter } from "next/font/google";
 import type { ReactNode } from "react";
 
 import { cn } from "@/lib/utils";
@@ -24,9 +24,9 @@ const GeistMono = Geist_Mono({
   variable: "--font-mono",
 });
 
-const MontserratSerif = Montserrat({
+const InterFont = Inter({
   subsets: ["latin"],
-  variable: "--font-serif",
+  variable: "--font-inter",
 });
 
 export default function RootLayout({
@@ -40,7 +40,7 @@ export default function RootLayout({
       className={cn(
         GeistSans.variable,
         GeistMono.variable,
-        MontserratSerif.variable,
+        InterFont.variable,
         "bg-background text-foreground",
       )}
     >
diff --git a/apps/www/src/app/not-found.tsx b/apps/www/src/app/not-found.tsx
index 3deed0e..d26ee3c 100644
--- a/apps/www/src/app/not-found.tsx
+++ b/apps/www/src/app/not-found.tsx
@@ -15,7 +15,7 @@ export default function NotFound() {
       <RegistrySidebar />
       <main className="flex w-full justify-center">
         <div className="flex min-h-screen w-full flex-col items-center justify-center text-center">
-          <h1 className="font-bold text-6xl text-muted-foreground tracking-tight md:text-8xl">
+          <h1 className="font-semibold text-6xl text-muted-foreground tracking-tight md:text-8xl">
             404
           </h1>
           <h2 className="mt-8 font-semibold text-2xl tracking-tight md:text-3xl">
diff --git a/apps/www/src/components/hero.tsx b/apps/www/src/components/hero.tsx
index fd3bf18..a15ae75 100644
--- a/apps/www/src/components/hero.tsx
+++ b/apps/www/src/components/hero.tsx
@@ -24,10 +24,12 @@ export function Hero({
           <Badge variant="secondary" className="mb-4">
             Coming soon
           </Badge>
-          <h1 className="font-bold text-4xl tracking-tight sm:text-5xl md:text-6xl">
+          <h1 className="text-balance font-semibold text-4xl tracking-tight sm:text-5xl md:text-6xl">
             {title}
           </h1>
-          <p className="mt-6 text-xl">{description}</p>
+          <p className="mt-6 text-muted-foreground text-xl leading-7">
+            {description}
+          </p>
           <div className="mt-10">
             <Button
               asChild
diff --git a/apps/www/src/components/logo.tsx b/apps/www/src/components/logo.tsx
index 7d36802..b2df7ce 100644
--- a/apps/www/src/components/logo.tsx
+++ b/apps/www/src/components/logo.tsx
@@ -16,7 +16,7 @@ export function Logo() {
         <circle className="fill-primary" cx="6.5" cy="13" r="2.5" />
       </svg>
 
-      <h1 className="font-bold">Brand Name</h1>
+      <h1 className="font-semibold">Brand Name</h1>
     </div>
   );
 }
diff --git a/apps/www/src/components/promo.tsx b/apps/www/src/components/promo.tsx
index e258c79..90a2b0a 100644
--- a/apps/www/src/components/promo.tsx
+++ b/apps/www/src/components/promo.tsx
@@ -19,10 +19,10 @@ export function Promo({
   return (
     <div className="relative h-[300px] w-full bg-foreground/10">
       <div className="relative z-10 flex h-full flex-col justify-center gap-3 px-8 py-3">
-        <h1 className="font-bold text-3xl tracking-tight md:text-4xl">
+        <h1 className="text-balance font-semibold text-3xl tracking-tight md:text-4xl">
           {title}
         </h1>
-        <p>{description}</p>
+        <p className="leading-7">{description}</p>
         <div>
           <Button asChild size="lg" className="rounded-md">
             <Link href={buttonLink}>{buttonText}</Link>

From 60ccdfdc4c34f7d7f5475316a3483f405d6a56cc Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 16:14:18 -0500
Subject: [PATCH 02/10] feat(ui): add usage-meter components to registry

- Add UsageMeter (Radix) with full accessibility support
- Add UsageMeterBase (lightweight) without Radix dependency
- Update registry.json with both component entries
- Update branding: rename logo from "Registry" to "usage-ui"
- Add documentation strategy and redesign workflow
- Remove MONOREPO-MIGRATION.md (migration complete)
---
 .../005-component-documentation-strategy.md   |  226 +++
 .../prompt-kit-component-page-analysis.md     |  404 +++++
 .../implement-documentation-redesign.md       | 1387 +++++++++++++++++
 MONOREPO-MIGRATION.md                         | 1312 ----------------
 apps/www/public/r/hero.json                   |    2 +-
 apps/www/public/r/promo.json                  |    2 +-
 apps/www/public/r/store.json                  |    2 +-
 apps/www/public/r/usage-meter-base.json       |   17 +
 apps/www/public/r/usage-meter.json            |   19 +
 .../src/components/registry/registry-logo.tsx |    2 +-
 packages/ui/registry.json                     |   33 +-
 packages/ui/src/components/registry/index.ts  |    7 +-
 .../components/registry/usage-meter/index.ts  |    9 +
 .../registry/usage-meter/usage-meter-base.tsx |  114 ++
 .../registry/usage-meter/usage-meter.tsx      |  113 ++
 15 files changed, 2327 insertions(+), 1322 deletions(-)
 create mode 100644 .agents/context/decisions/005-component-documentation-strategy.md
 create mode 100644 .agents/context/research/prompt-kit-component-page-analysis.md
 create mode 100644 .agents/workflows/implement-documentation-redesign.md
 delete mode 100644 MONOREPO-MIGRATION.md
 create mode 100644 apps/www/public/r/usage-meter-base.json
 create mode 100644 apps/www/public/r/usage-meter.json
 create mode 100644 packages/ui/src/components/registry/usage-meter/index.ts
 create mode 100644 packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
 create mode 100644 packages/ui/src/components/registry/usage-meter/usage-meter.tsx

diff --git a/.agents/context/decisions/005-component-documentation-strategy.md b/.agents/context/decisions/005-component-documentation-strategy.md
new file mode 100644
index 0000000..fa2787d
--- /dev/null
+++ b/.agents/context/decisions/005-component-documentation-strategy.md
@@ -0,0 +1,226 @@
+# ADR-005: Component Documentation and Preview Strategy
+
+## Status
+
+**Accepted** - January 2025
+
+## Context
+
+To improve the documentation experience and align with industry standards (shadcn/ui, prompt-kit), we evaluated multiple approaches for:
+
+1. How to access component source code for "Code" tabs
+2. How to structure documentation pages
+3. How to render component previews
+4. How to document component props/API
+
+This decision follows research documented in `.agents/context/research/prompt-kit-component-page-analysis.md`.
+
+---
+
+## Decision 1: Source Code Access Strategy
+
+### Selected: Option A (filesystem) + Option B (registry.json) hybrid
+
+**Approach:**
+- **Docs site**: Read source files from filesystem at build time using `fs.readFileSync`
+- **Registry distribution**: Embed source in generated JSON files for shadcn CLI
+
+```typescript
+// lib/code.ts - For docs site
+import fs from "fs"
+import { cache } from "react"
+
+export const extractCodeFromFilePath = cache((filePath: string) => {
+  return fs.readFileSync(filePath, "utf-8")
+})
+```
+
+### Rationale
+
+| Consideration | Analysis |
+|---------------|----------|
+| **Prompt-kit precedent** | Uses filesystem reads for docs - proven, simple |
+| **shadcn/ui precedent** | Embeds source in registry JSON for CLI distribution |
+| **Maintenance** | Filesystem reads always reflect actual code (no drift) |
+| **Performance** | React cache + static generation = fast |
+| **Monorepo fit** | Works well - read from `packages/ui/src/components/` |
+
+### Alternatives Rejected
+
+- **Fetch from GitHub raw URLs**: Network dependency, rate limiting, slower
+- **Registry.json only**: Bloats JSON, harder to maintain, can drift
+
+---
+
+## Decision 2: Documentation Format
+
+### Selected: Option A (MDX-based docs)
+
+**Approach:**
+- Use MDX files for component documentation
+- Each component gets a dedicated MDX file with examples, usage, and API reference
+- Custom MDX components for Preview/Code tabs, API tables
+
+```
+apps/www/src/app/docs/
+├── usage-meter/
+│   ├── page.mdx                    # Main documentation
+│   ├── usage-meter-basic.tsx       # Example variant
+│   └── usage-meter-advanced.tsx    # Example variant
+```
+
+### Rationale
+
+| Consideration | Analysis |
+|---------------|----------|
+| **Industry standard** | shadcn/ui, Radix, prompt-kit, Chakra all use MDX |
+| **Rich content** | Supports prose, callouts, warnings, custom components |
+| **SEO** | Static content is better for search engines |
+| **Flexibility** | Mix markdown prose with React components |
+| **Scalability** | Well-suited for growing component libraries |
+
+### Alternatives Rejected
+
+- **Dynamic routes only**: Less flexible, harder to write custom prose
+- **Hybrid**: Two systems create confusion about where content lives
+
+### Migration Note
+
+Current implementation uses dynamic `[name]/page.tsx` routes. Migration path:
+1. Set up MDX infrastructure (@mdx-js/loader, mdx-components.tsx)
+2. Create MDX templates for new components
+3. Gradually migrate existing component pages
+
+---
+
+## Decision 3: Preview Rendering Strategy
+
+### Selected: Option C (Hybrid)
+
+**Approach:**
+- **Blocks** (full-page layouts): Render in iframe for complete isolation
+- **UI components** (buttons, meters, cards): Render directly in the page
+
+```tsx
+const isBlock = component.type === "registry:block"
+
+return isBlock ? (
+  <iframe src={`/demo/${name}`} className="h-[800px] w-full" />
+) : (
+  <div className="min-h-[350px] rounded-md border p-8">
+    <ComponentPreview component={component} />
+  </div>
+)
+```
+
+### Rationale
+
+| Component Type | Best Approach | Why |
+|----------------|---------------|-----|
+| **Blocks** (dashboards, pages) | iframe | Need full viewport, own CSS scope |
+| **UI components** (buttons, inputs) | Direct | Theme-aware, inspectable, lighter |
+
+This matches shadcn/ui's approach: simple components render inline, complex "blocks" get their own demo pages.
+
+### Alternatives Rejected
+
+- **iframe only**: Heavy for small components, theme doesn't sync
+- **Direct only**: Full-page blocks don't fit, layout breaks
+
+---
+
+## Decision 4: Props/API Documentation
+
+### Selected: Option A (Manual markdown tables in MDX)
+
+**Approach:**
+- Write API Reference tables manually in MDX files
+- Follow shadcn/ui's format: Prop | Type | Default columns
+
+```mdx
+## API Reference
+
+### UsageMeter
+
+| Prop | Type | Default |
+|------|------|---------|
+| `value` | `number` | Required |
+| `max` | `number` | `100` |
+| `variant` | `"default" \| "success" \| "warning" \| "danger"` | `"default"` |
+| `size` | `"sm" \| "default" \| "lg"` | `"default"` |
+```
+
+### Rationale
+
+**What shadcn/ui does:**
+shadcn/ui uses manual markdown tables in MDX files for API documentation. Example from their Button docs:
+
+```markdown
+## API Reference
+
+### Button
+
+| Prop | Type | Default |
+|------|------|---------|
+| `variant` | `"default" | "outline" | "ghost" | "destructive" | "secondary" | "link"` | `"default"` |
+| `size` | `"default" | "xs" | "sm" | "lg" | "icon"` | `"default"` |
+| `asChild` | `boolean` | `false` |
+```
+
+| Consideration | Analysis |
+|---------------|----------|
+| **shadcn/ui alignment** | Matches their approach exactly |
+| **Prompt-kit alignment** | Also uses manual markdown tables |
+| **Simplicity** | No tooling required, just markdown |
+| **Control** | Human-written descriptions are clearer |
+| **Trade-off** | Manual = can drift, but component count is manageable |
+
+### Alternatives Considered for Future
+
+As component count grows (10+), consider:
+- **JSDoc extraction**: Write docs in code, auto-generate tables
+- **TypeScript type extraction**: Use `react-docgen-typescript`
+
+These add build complexity but ensure docs stay in sync with code.
+
+---
+
+## Implementation Plan
+
+### Phase 1: Infrastructure
+1. Add Shiki for syntax highlighting
+2. Create code extraction utility (`lib/code.ts`)
+3. Set up MDX loader and components
+
+### Phase 2: Core Components
+4. Build `ComponentCodePreview` (Preview/Code tabs)
+5. Build `ApiTable` component
+6. Build `CodeRenderer` (Shiki wrapper)
+
+### Phase 3: Documentation
+7. Create MDX template for component docs
+8. Migrate existing component pages to MDX
+9. Add Previous/Next navigation
+
+---
+
+## Consequences
+
+### Positive
+- Aligns with shadcn/ui and prompt-kit patterns
+- Rich, flexible documentation format
+- Better developer experience for docs contributors
+- SEO benefits from static MDX content
+
+### Negative
+- Migration effort from current dynamic routes
+- MDX adds build complexity
+- Manual props tables require discipline to keep updated
+
+---
+
+## References
+
+- [prompt-kit component page analysis](./../research/prompt-kit-component-page-analysis.md)
+- [shadcn/ui Button docs](https://ui.shadcn.com/docs/components/button)
+- [prompt-kit GitHub](https://github.com/ibelick/prompt-kit)
diff --git a/.agents/context/research/prompt-kit-component-page-analysis.md b/.agents/context/research/prompt-kit-component-page-analysis.md
new file mode 100644
index 0000000..0c85e0e
--- /dev/null
+++ b/.agents/context/research/prompt-kit-component-page-analysis.md
@@ -0,0 +1,404 @@
+# Prompt-Kit Component Page Analysis
+
+> Research comparing prompt-kit's component documentation pages with usage-ui's current implementation.
+
+**Date:** 2026-01-29  
+**Source:** https://prompt-kit.com/docs/chain-of-thought  
+**Purpose:** Identify UI/UX patterns to improve usage-ui's registry component pages
+
+---
+
+## Executive Summary
+
+Prompt-kit has a polished, documentation-focused component page design that includes multiple example variants, code viewing, API documentation tables, and navigation between components. Usage-ui's current implementation is more minimal, focusing on a single iframe preview with basic copy/open actions.
+
+---
+
+## Layout & Structure Comparison
+
+### Grid System
+
+| Aspect | prompt-kit | usage-ui |
+|--------|------------|----------|
+| **Grid** | 12-column (`md:grid-cols-12`), content in cols 4-10 | Simple container with padding |
+| **Max Width** | `max-w-(--breakpoint-2xl)` | Container default |
+| **Typography** | `prose prose-zinc dark:prose-invert` wrapper | Manual styling |
+
+### prompt-kit Layout Structure
+
+```html
+<div class="relative mx-auto grid w-full max-w-(--breakpoint-2xl) grid-cols-6 md:grid-cols-12">
+  <div class="col-start-1 col-end-7 flex flex-col md:col-start-4 md:col-end-12 lg:col-end-10">
+    <main class="flex-1">
+      <div class="prose prose-zinc dark:prose-invert ...">
+        <!-- Content here -->
+      </div>
+    </main>
+  </div>
+</div>
+```
+
+### usage-ui Layout Structure
+
+```tsx
+<div className="container p-5 md:p-10">
+  <div className="mb-6 flex items-center justify-between">
+    <!-- Back button + title -->
+  </div>
+  <ComponentCard ... />
+</div>
+```
+
+---
+
+## Component Page Content Sections
+
+### prompt-kit Page Structure
+
+1. **Title** (`<h1>`) - Component name
+2. **Description** (`<p>`) - One-line summary
+3. **Examples Section** (`<h2>Examples</h2>`)
+   - Multiple example variants (Basic, Advanced, etc.)
+   - Each with Preview/Code tabs
+4. **Installation Section** (`<h2>Installation</h2>`)
+   - CLI/Manual tabs
+   - Copy-to-clipboard functionality
+5. **Component API Section** (`<h2>Component API</h2>`)
+   - Props tables for each sub-component
+6. **Previous/Next Navigation** - Links to adjacent components
+
+### usage-ui Page Structure
+
+1. **Back Button** - Returns to home
+2. **Title** - Component name
+3. **Preview Card**
+   - Description
+   - Copy command button
+   - Open in v0 button
+   - iframe preview (800px height)
+
+### Missing in usage-ui
+
+- [ ] Multiple example variants
+- [ ] Preview/Code tabs
+- [ ] API documentation tables
+- [ ] Installation section with CLI/Manual options
+- [ ] Previous/Next navigation
+- [ ] Prose typography wrapper
+
+---
+
+## Tab Component Implementation
+
+### prompt-kit Tab Design
+
+```html
+<div role="tablist" class="inline-flex h-10 w-full items-center justify-start border-b">
+  <button 
+    role="tab" 
+    data-state="active" 
+    class="relative inline-flex h-10 items-center justify-center px-4 py-1 pt-2 pb-3 text-sm font-medium"
+  >
+    <!-- Animated bottom indicator -->
+    <div class="absolute bottom-0 flex h-0.5 w-full justify-center" style="opacity: 1;">
+      <div class="bg-foreground h-0.5 w-4/5"></div>
+    </div>
+    Preview
+  </button>
+  <button role="tab" data-state="inactive" class="...">
+    Code
+  </button>
+</div>
+```
+
+**Key Features:**
+- Border-bottom on tab list container
+- Active tab has animated underline indicator (80% width, centered)
+- Inactive tabs show `text-muted-foreground`
+- Active tabs show `text-zinc-950 dark:text-white`
+
+### Tab Styling Classes
+
+```css
+/* Tab trigger base */
+.tab-trigger {
+  @apply relative inline-flex h-10 items-center justify-center;
+  @apply rounded-none bg-transparent px-4 py-1 pt-2 pb-3;
+  @apply text-sm font-medium whitespace-nowrap;
+  @apply text-muted-foreground transition-none;
+  @apply focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-hidden;
+  @apply disabled:pointer-events-none disabled:opacity-50;
+  @apply data-[state=active]:text-zinc-950;
+  @apply dark:text-zinc-500 dark:data-[state=active]:text-white;
+}
+```
+
+---
+
+## Preview Container
+
+### prompt-kit Preview
+
+```html
+<div class="border-border flex min-h-[350px] w-full items-center justify-center rounded-md border p-8">
+  <div class="w-full max-w-3xl">
+    <!-- Component renders directly here -->
+  </div>
+</div>
+```
+
+**Characteristics:**
+- Minimum height: 350px
+- Centered content with max-width
+- Generous padding (p-8)
+- Direct component rendering (not iframe)
+
+### usage-ui Preview
+
+```tsx
+<div className="h-[800px] w-full overflow-hidden rounded-md border border-border p-4">
+  <iframe src={`/demo/${component.name}`} className="h-full w-full" />
+</div>
+```
+
+**Characteristics:**
+- Fixed height: 800px
+- Uses iframe for isolation
+- Less padding (p-4)
+
+---
+
+## Code Display
+
+### prompt-kit Code Block
+
+```html
+<div class="group relative">
+  <!-- Copy button - appears on hover -->
+  <button class="bg-background absolute top-3 right-3 p-2 opacity-0 transition-opacity group-hover:opacity-100">
+    <div class="absolute inset-0 transform transition-all duration-300 scale-100 opacity-100">
+      <svg class="lucide lucide-copy h-4 w-4 text-zinc-400">...</svg>
+    </div>
+    <div class="absolute inset-0 transform transition-all duration-300 scale-0 opacity-0">
+      <svg class="lucide lucide-check h-4 w-4 text-zinc-400">...</svg>
+    </div>
+  </button>
+  
+  <!-- Syntax highlighted code -->
+  <div class="not-prose bg-background border-border overflow-auto rounded-md border p-2 text-[13px]">
+    <pre class="shiki github-light" style="background-color:#fff;color:#24292e">
+      <code>
+        <span class="line">
+          <span style="color:#6F42C1">npx</span>
+          <span style="color:#032F62"> shadcn</span>
+          ...
+        </span>
+      </code>
+    </pre>
+  </div>
+</div>
+```
+
+**Features:**
+- Shiki syntax highlighting (github-light theme)
+- Hover-to-reveal copy button
+- Animated copy/check icon transition
+- Dark mode support: `dark:[&_pre]:!bg-transparent dark:[&_span]:!text-white`
+
+---
+
+## API Documentation Tables
+
+### prompt-kit Table Structure
+
+```html
+<div class="not-prose border-border relative w-full table-auto overflow-auto rounded-lg border text-sm">
+  <table class="w-full">
+    <thead class="bg-secondary text-foreground">
+      <tr class="h-10">
+        <th class="px-4 pb-0 text-left align-middle font-[450]">Prop</th>
+        <th class="px-4 pb-0 text-left align-middle font-[450]">Type</th>
+        <th class="px-4 pb-0 text-left align-middle font-[450]">Default</th>
+        <th class="px-4 pb-0 text-left align-middle font-[450]">Description</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-zinc-200 dark:divide-zinc-600">
+      <tr class="h-10">
+        <td class="px-4 py-2 text-left align-middle">children</td>
+        <td class="px-4 py-2 text-left align-middle">React.ReactNode</td>
+        <td class="px-4 py-2 text-left align-middle"></td>
+        <td class="px-4 py-2 text-left align-middle">ChainOfThoughtStep components</td>
+      </tr>
+      <!-- More rows -->
+    </tbody>
+  </table>
+</div>
+```
+
+**Styling:**
+- `not-prose` to escape prose typography
+- Rounded corners with border
+- Secondary background on header
+- Dividers between rows
+- Font weight 450 for headers
+- Consistent padding and alignment
+
+---
+
+## Navigation Between Components
+
+### prompt-kit Previous/Next Links
+
+```html
+<div class="flex justify-between pt-12 pb-20">
+  <a class="hover:bg-primary-foreground inline-flex items-center gap-1 rounded-md border px-2 py-1 text-sm text-zinc-500 transition-colors duration-200" 
+     href="/docs/mcp">
+    <svg class="lucide lucide-chevron-left h-4 w-4">...</svg>
+    Model Context Protocol
+  </a>
+  <a class="hover:bg-primary-foreground inline-flex items-center gap-1 rounded-md border px-2 py-1 text-sm text-zinc-500 transition-colors duration-200" 
+     href="/docs/chat-container">
+    Chat Container
+    <svg class="lucide lucide-chevron-right h-4 w-4">...</svg>
+  </a>
+</div>
+```
+
+**Features:**
+- Flexbox with `justify-between`
+- Generous vertical spacing (pt-12 pb-20)
+- Bordered pill-style buttons
+- Hover background change
+- Chevron icons indicating direction
+
+---
+
+## Sidebar Comparison
+
+### Common Patterns
+
+Both use shadcn's Sidebar component with:
+- Collapsible groups
+- Active item highlighting
+- Mobile responsive behavior
+
+### prompt-kit Sidebar Enhancements
+
+1. **"new" badges** on recent components:
+```html
+<span class="text-primary text-xs leading-none">new</span>
+```
+
+2. **Dashed border** on content area:
+```html
+<div class="border-r border-dashed">...</div>
+```
+
+3. **Theme toggle** integrated in sidebar content
+
+4. **No search** visible in sidebar
+
+### usage-ui Sidebar Features
+
+1. **Search input** with icon
+2. **Collapsible groups** with icons
+3. **Theme toggle** in footer
+
+---
+
+## Typography (Prose) Configuration
+
+### prompt-kit Prose Classes
+
+```css
+.prose {
+  /* Headings */
+  @apply prose-h1:scroll-m-20 prose-h1:text-2xl prose-h1:font-semibold;
+  @apply prose-h2:mt-12 prose-h2:scroll-m-20 prose-h2:text-xl prose-h2:font-medium;
+  @apply prose-h3:scroll-m-20 prose-h3:text-base prose-h3:font-medium;
+  @apply prose-h4:scroll-m-20 prose-h4:text-base prose-h4:font-medium;
+  @apply prose-h5:scroll-m-20 prose-h5:text-sm;
+  @apply prose-h6:scroll-m-20 prose-h6:text-xs;
+  
+  /* Content */
+  @apply prose-strong:font-medium;
+  @apply prose-code:block prose-code:rounded-md prose-code:bg-gray-100 prose-code:p-1 prose-code:text-gray-800;
+  @apply prose-table:block prose-table:overflow-y-auto;
+  @apply prose-img:m-0;
+}
+```
+
+**Key Settings:**
+- `scroll-m-20` on headings for anchor link offset
+- h2 has `mt-12` for section spacing
+- Font weights: semibold (h1), medium (h2-h4)
+- Code blocks have background and padding
+
+---
+
+## Recommendations for usage-ui
+
+### High Priority
+
+1. **Add Preview/Code tabs** to component pages
+   - Show source code alongside preview
+   - Use Shiki for syntax highlighting
+
+2. **Add API documentation tables**
+   - Document props for each component
+   - Follow prompt-kit's table structure
+
+3. **Implement Previous/Next navigation**
+   - Help users browse components sequentially
+
+### Medium Priority
+
+4. **Use prose typography wrapper**
+   - Consistent heading sizes and spacing
+   - Better readability
+
+5. **Multiple example variants**
+   - Show different use cases per component
+   - Basic, Advanced, With Icons, etc.
+
+6. **Installation section**
+   - CLI/Manual tabs
+   - Clear copy-to-clipboard UX
+
+### Low Priority
+
+7. **"new" badges** for recent components
+8. **Animated tab indicators**
+9. **Direct component rendering** (vs iframe)
+
+---
+
+## Implementation Notes
+
+### Dependencies Needed
+
+- **Shiki** - Syntax highlighting
+- Already have: Radix Tabs, existing shadcn components
+
+### Files to Modify
+
+1. `apps/www/src/app/(registry)/registry/[name]/page.tsx` - Main component page
+2. Create new components:
+   - `ComponentTabs.tsx` - Preview/Code tabs
+   - `ApiTable.tsx` - Props documentation
+   - `ComponentNav.tsx` - Previous/Next links
+3. Add prose configuration to `globals.css`
+
+### Data Requirements
+
+- Source code for each component (for code view)
+- Props definitions (for API tables)
+- Component ordering (for prev/next nav)
+
+---
+
+## References
+
+- [prompt-kit Chain of Thought page](https://prompt-kit.com/docs/chain-of-thought)
+- [prompt-kit GitHub](https://github.com/ibelick/prompt-kit)
+- [shadcn/ui docs pattern](https://ui.shadcn.com/docs/components)
diff --git a/.agents/workflows/implement-documentation-redesign.md b/.agents/workflows/implement-documentation-redesign.md
new file mode 100644
index 0000000..6f721a3
--- /dev/null
+++ b/.agents/workflows/implement-documentation-redesign.md
@@ -0,0 +1,1387 @@
+# Workflow: Implement Component Documentation Redesign
+
+> Step-by-step procedure for implementing the enhanced component documentation system based on ADR-005 decisions.
+
+**Based on:** ADR-005: Component Documentation and Preview Strategy  
+**Reference:** `.agents/context/research/prompt-kit-component-page-analysis.md`
+
+---
+
+## Prerequisites
+
+- [ ] Monorepo setup is complete (Phase 0 in ARCHITECTURE.md)
+- [ ] At least one component exists in `packages/ui/src/components/registry/`
+- [ ] Current `pnpm build` passes without errors
+- [ ] Familiarity with ADR-005 decisions
+
+---
+
+## Phase Overview
+
+| Phase | Objective | Complexity | Estimated Files |
+|-------|-----------|------------|-----------------|
+| 1 | Infrastructure Setup | Medium | 4-5 new files |
+| 2 | Core Documentation Components | High | 4 new components |
+| 3 | Page Layout Components | Medium | 3 new components |
+| 4 | Preview System | Medium | 2-3 files |
+| 5 | Documentation Migration | Medium | Template + 1 pilot |
+| 6 | Validation & Documentation | Low | 2 workflow updates |
+
+---
+
+## Phase 1: Infrastructure Setup
+
+### Objective
+Set up the foundational dependencies and utilities for syntax highlighting and source code extraction.
+
+### Prerequisites
+- [ ] `pnpm build` passes
+
+### 1.1 Add Dependencies
+
+```bash
+# Add Shiki for syntax highlighting
+pnpm add shiki --filter=@usage-ui/www
+
+# Add MDX support
+pnpm add @next/mdx @mdx-js/loader @mdx-js/react --filter=@usage-ui/www
+
+# Add types for MDX
+pnpm add -D @types/mdx --filter=@usage-ui/www
+```
+
+### 1.2 Create Code Extraction Utility
+
+**Create:** `apps/www/src/lib/code.ts`
+
+```typescript
+import fs from "node:fs"
+import path from "node:path"
+import { cache } from "react"
+
+/**
+ * Extract source code from a file path at build time.
+ * Uses React cache for deduplication during SSG.
+ * 
+ * @param filePath - Relative path from packages/ui/
+ * @returns The file contents as a string
+ */
+export const extractCodeFromFilePath = cache((filePath: string): string => {
+  const absolutePath = path.join(process.cwd(), "..", "ui", filePath)
+  
+  try {
+    return fs.readFileSync(absolutePath, "utf-8")
+  } catch (error) {
+    console.error(`Failed to read file: ${absolutePath}`)
+    return `// Error: Could not load source code for ${filePath}`
+  }
+})
+
+/**
+ * Extract source code for a registry component by name.
+ * Looks up the path in registry.json and reads the file.
+ * 
+ * @param componentName - The component name from registry.json
+ * @returns The source code string
+ */
+export const getComponentSource = cache((componentName: string): string => {
+  const registryPath = path.join(process.cwd(), "..", "ui", "registry.json")
+  
+  try {
+    const registry = JSON.parse(fs.readFileSync(registryPath, "utf-8"))
+    const item = registry.items.find((i: { name: string }) => i.name === componentName)
+    
+    if (!item || !item.files?.[0]?.path) {
+      return `// Component "${componentName}" not found in registry`
+    }
+    
+    return extractCodeFromFilePath(item.files[0].path)
+  } catch (error) {
+    return `// Error loading registry for "${componentName}"`
+  }
+})
+```
+
+### 1.3 Create Shiki Highlighter Singleton
+
+**Create:** `apps/www/src/lib/shiki.ts`
+
+```typescript
+import { createHighlighter, type Highlighter } from "shiki"
+import { cache } from "react"
+
+let highlighterPromise: Promise<Highlighter> | null = null
+
+/**
+ * Get or create the Shiki highlighter singleton.
+ * Loads github-light and github-dark themes.
+ */
+export const getHighlighter = cache(async (): Promise<Highlighter> => {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighter({
+      themes: ["github-light", "github-dark"],
+      langs: ["typescript", "tsx", "javascript", "jsx", "bash", "json", "css"],
+    })
+  }
+  return highlighterPromise
+})
+
+/**
+ * Highlight code with Shiki.
+ * Returns HTML string with syntax highlighting.
+ * 
+ * @param code - The source code to highlight
+ * @param lang - The language for syntax highlighting
+ */
+export const highlightCode = cache(
+  async (code: string, lang: string = "tsx"): Promise<string> => {
+    const highlighter = await getHighlighter()
+    
+    return highlighter.codeToHtml(code, {
+      lang,
+      themes: {
+        light: "github-light",
+        dark: "github-dark",
+      },
+    })
+  }
+)
+```
+
+### 1.4 Configure MDX in Next.js
+
+**Update:** `apps/www/next.config.ts`
+
+```typescript
+import createMDX from "@next/mdx"
+import type { NextConfig } from "next"
+
+const nextConfig: NextConfig = {
+  pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
+  // ... existing config
+}
+
+const withMDX = createMDX({
+  options: {
+    remarkPlugins: [],
+    rehypePlugins: [],
+  },
+})
+
+export default withMDX(nextConfig)
+```
+
+### 1.5 Create MDX Components Configuration
+
+**Create:** `apps/www/src/mdx-components.tsx`
+
+```tsx
+import type { MDXComponents } from "mdx/types"
+
+// Import documentation components (created in Phase 2)
+// import { ComponentCodePreview } from "@/components/docs/component-code-preview"
+// import { ApiTable } from "@/components/docs/api-table"
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+  return {
+    // Override default elements with custom styling
+    h1: ({ children }) => (
+      <h1 className="scroll-m-20 text-3xl font-semibold tracking-tight">
+        {children}
+      </h1>
+    ),
+    h2: ({ children }) => (
+      <h2 className="mt-12 scroll-m-20 border-b pb-2 text-xl font-medium tracking-tight first:mt-0">
+        {children}
+      </h2>
+    ),
+    h3: ({ children }) => (
+      <h3 className="mt-8 scroll-m-20 text-lg font-medium tracking-tight">
+        {children}
+      </h3>
+    ),
+    p: ({ children }) => (
+      <p className="leading-7 [&:not(:first-child)]:mt-6">{children}</p>
+    ),
+    code: ({ children }) => (
+      <code className="relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm">
+        {children}
+      </code>
+    ),
+    // Add custom components (uncomment when created)
+    // ComponentCodePreview,
+    // ApiTable,
+    ...components,
+  }
+}
+```
+
+### Validation Steps
+
+```bash
+# Verify dependencies installed
+pnpm ls shiki --filter=@usage-ui/www
+pnpm ls @next/mdx --filter=@usage-ui/www
+
+# Verify build still works
+pnpm build --filter=@usage-ui/www
+
+# Verify dev server starts
+pnpm dev --filter=@usage-ui/www
+```
+
+---
+
+## Phase 2: Core Documentation Components
+
+### Objective
+Build the primary components for displaying component documentation with code previews.
+
+### Prerequisites
+- [ ] Phase 1 complete
+- [ ] Shiki and MDX dependencies installed
+
+### 2.1 Create Components Directory
+
+```bash
+mkdir -p apps/www/src/components/docs
+```
+
+### 2.2 Build CodeRenderer Component
+
+**Create:** `apps/www/src/components/docs/code-renderer.tsx`
+
+```tsx
+import { highlightCode } from "@/lib/shiki"
+
+interface CodeRendererProps {
+  code: string
+  lang?: string
+  className?: string
+}
+
+export async function CodeRenderer({
+  code,
+  lang = "tsx",
+  className,
+}: CodeRendererProps) {
+  const html = await highlightCode(code, lang)
+
+  return (
+    <div
+      className={cn(
+        "not-prose overflow-auto rounded-md border bg-background p-4 text-[13px]",
+        // Theme-aware styling for Shiki output
+        "[&_pre]:!bg-transparent [&_code]:!bg-transparent",
+        "dark:[&_span]:!text-[var(--shiki-dark)]",
+        className
+      )}
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  )
+}
+```
+
+### 2.3 Build ClientCodeWrapper Component
+
+**Create:** `apps/www/src/components/docs/client-code-wrapper.tsx`
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { Check, Copy } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+
+interface ClientCodeWrapperProps {
+  code: string
+  children: React.ReactNode
+  className?: string
+}
+
+export function ClientCodeWrapper({
+  code,
+  children,
+  className,
+}: ClientCodeWrapperProps) {
+  const [copied, setCopied] = React.useState(false)
+
+  const copyToClipboard = async () => {
+    await navigator.clipboard.writeText(code)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  return (
+    <div className={cn("group relative", className)}>
+      <Button
+        variant="ghost"
+        size="icon"
+        className="absolute right-3 top-3 h-8 w-8 opacity-0 transition-opacity group-hover:opacity-100"
+        onClick={copyToClipboard}
+      >
+        <div className="relative h-4 w-4">
+          <Copy
+            className={cn(
+              "absolute inset-0 h-4 w-4 transition-all duration-300",
+              copied ? "scale-0 opacity-0" : "scale-100 opacity-100"
+            )}
+          />
+          <Check
+            className={cn(
+              "absolute inset-0 h-4 w-4 text-green-500 transition-all duration-300",
+              copied ? "scale-100 opacity-100" : "scale-0 opacity-0"
+            )}
+          />
+        </div>
+      </Button>
+      {children}
+    </div>
+  )
+}
+```
+
+### 2.4 Build ComponentCodePreview Component
+
+**Create:** `apps/www/src/components/docs/component-code-preview.tsx`
+
+```tsx
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "radix-ui"
+import { cn } from "@/lib/utils"
+import { CodeRenderer } from "./code-renderer"
+import { ClientCodeWrapper } from "./client-code-wrapper"
+
+interface ComponentCodePreviewProps {
+  name: string
+  code: string
+  children: React.ReactNode
+  className?: string
+}
+
+export function ComponentCodePreview({
+  name,
+  code,
+  children,
+  className,
+}: ComponentCodePreviewProps) {
+  return (
+    <Tabs.Root defaultValue="preview" className={cn("w-full", className)}>
+      <Tabs.List className="inline-flex h-10 w-full items-center justify-start border-b">
+        <Tabs.Trigger
+          value="preview"
+          className={cn(
+            "relative inline-flex h-10 items-center justify-center px-4 py-1 pt-2 pb-3",
+            "text-sm font-medium text-muted-foreground",
+            "data-[state=active]:text-foreground",
+            "transition-none focus-visible:outline-none"
+          )}
+        >
+          <TabIndicator />
+          Preview
+        </Tabs.Trigger>
+        <Tabs.Trigger
+          value="code"
+          className={cn(
+            "relative inline-flex h-10 items-center justify-center px-4 py-1 pt-2 pb-3",
+            "text-sm font-medium text-muted-foreground",
+            "data-[state=active]:text-foreground",
+            "transition-none focus-visible:outline-none"
+          )}
+        >
+          <TabIndicator />
+          Code
+        </Tabs.Trigger>
+      </Tabs.List>
+
+      <Tabs.Content value="preview" className="mt-4">
+        <div className="flex min-h-[350px] w-full items-center justify-center rounded-md border p-8">
+          <div className="w-full max-w-3xl">{children}</div>
+        </div>
+      </Tabs.Content>
+
+      <Tabs.Content value="code" className="mt-4">
+        <ClientCodeWrapper code={code}>
+          <CodeRenderer code={code} />
+        </ClientCodeWrapper>
+      </Tabs.Content>
+    </Tabs.Root>
+  )
+}
+
+// Animated underline indicator for active tab
+function TabIndicator() {
+  return (
+    <div className="absolute bottom-0 flex h-0.5 w-full justify-center opacity-0 data-[state=active]:opacity-100 transition-opacity">
+      <div className="h-0.5 w-4/5 bg-foreground" />
+    </div>
+  )
+}
+```
+
+### 2.5 Build ApiTable Component
+
+**Create:** `apps/www/src/components/docs/api-table.tsx`
+
+```tsx
+import { cn } from "@/lib/utils"
+
+interface ApiTableProps {
+  data: Array<{
+    prop: string
+    type: string
+    default?: string
+    description?: string
+  }>
+  className?: string
+}
+
+export function ApiTable({ data, className }: ApiTableProps) {
+  return (
+    <div
+      className={cn(
+        "not-prose relative w-full overflow-auto rounded-lg border text-sm",
+        className
+      )}
+    >
+      <table className="w-full">
+        <thead className="bg-secondary text-foreground">
+          <tr className="h-10">
+            <th className="px-4 pb-0 text-left align-middle font-[450]">
+              Prop
+            </th>
+            <th className="px-4 pb-0 text-left align-middle font-[450]">
+              Type
+            </th>
+            <th className="px-4 pb-0 text-left align-middle font-[450]">
+              Default
+            </th>
+            {data.some((row) => row.description) && (
+              <th className="px-4 pb-0 text-left align-middle font-[450]">
+                Description
+              </th>
+            )}
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-border">
+          {data.map((row) => (
+            <tr key={row.prop} className="h-10">
+              <td className="px-4 py-2 text-left align-middle font-mono text-sm">
+                {row.prop}
+              </td>
+              <td className="px-4 py-2 text-left align-middle font-mono text-sm text-muted-foreground">
+                {row.type}
+              </td>
+              <td className="px-4 py-2 text-left align-middle font-mono text-sm">
+                {row.default || "—"}
+              </td>
+              {data.some((r) => r.description) && (
+                <td className="px-4 py-2 text-left align-middle">
+                  {row.description}
+                </td>
+              )}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+```
+
+### 2.6 Create Index Export
+
+**Create:** `apps/www/src/components/docs/index.ts`
+
+```typescript
+export { CodeRenderer } from "./code-renderer"
+export { ClientCodeWrapper } from "./client-code-wrapper"
+export { ComponentCodePreview } from "./component-code-preview"
+export { ApiTable } from "./api-table"
+```
+
+### Validation Steps
+
+```bash
+# Type check the new components
+pnpm typecheck --filter=@usage-ui/www
+
+# Lint the new components
+pnpm lint --filter=@usage-ui/www
+
+# Build to verify no compilation errors
+pnpm build --filter=@usage-ui/www
+```
+
+---
+
+## Phase 3: Page Layout Components
+
+### Objective
+Build navigation and installation components for complete documentation pages.
+
+### Prerequisites
+- [ ] Phase 2 complete
+- [ ] Core documentation components working
+
+### 3.1 Build ComponentNav Component
+
+**Create:** `apps/www/src/components/docs/component-nav.tsx`
+
+```tsx
+import Link from "next/link"
+import { ChevronLeft, ChevronRight } from "lucide-react"
+import { cn } from "@/lib/utils"
+import { getRegistryItems } from "@/lib/registry"
+
+interface ComponentNavProps {
+  currentName: string
+  className?: string
+}
+
+export function ComponentNav({ currentName, className }: ComponentNavProps) {
+  const items = getRegistryItems()
+  const currentIndex = items.findIndex((item) => item.name === currentName)
+  
+  const prev = currentIndex > 0 ? items[currentIndex - 1] : null
+  const next = currentIndex < items.length - 1 ? items[currentIndex + 1] : null
+
+  return (
+    <div className={cn("flex justify-between pt-12 pb-20", className)}>
+      {prev ? (
+        <Link
+          href={`/docs/${prev.name}`}
+          className={cn(
+            "inline-flex items-center gap-1 rounded-md border px-3 py-1.5",
+            "text-sm text-muted-foreground transition-colors",
+            "hover:bg-muted hover:text-foreground"
+          )}
+        >
+          <ChevronLeft className="h-4 w-4" />
+          {prev.title}
+        </Link>
+      ) : (
+        <div />
+      )}
+      
+      {next ? (
+        <Link
+          href={`/docs/${next.name}`}
+          className={cn(
+            "inline-flex items-center gap-1 rounded-md border px-3 py-1.5",
+            "text-sm text-muted-foreground transition-colors",
+            "hover:bg-muted hover:text-foreground"
+          )}
+        >
+          {next.title}
+          <ChevronRight className="h-4 w-4" />
+        </Link>
+      ) : (
+        <div />
+      )}
+    </div>
+  )
+}
+```
+
+### 3.2 Build InstallationTabs Component
+
+**Create:** `apps/www/src/components/docs/installation-tabs.tsx`
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { Tabs } from "radix-ui"
+import { cn } from "@/lib/utils"
+import { ClientCodeWrapper } from "./client-code-wrapper"
+
+interface InstallationTabsProps {
+  componentName: string
+  registryUrl?: string
+  className?: string
+}
+
+export function InstallationTabs({
+  componentName,
+  registryUrl = "https://usage-ui.vercel.app",
+  className,
+}: InstallationTabsProps) {
+  const cliCommand = `npx shadcn add ${registryUrl}/r/${componentName}.json`
+  
+  return (
+    <Tabs.Root defaultValue="cli" className={cn("w-full", className)}>
+      <Tabs.List className="inline-flex h-10 items-center justify-start gap-1 rounded-lg bg-muted p-1">
+        <Tabs.Trigger
+          value="cli"
+          className={cn(
+            "inline-flex items-center justify-center rounded-md px-3 py-1.5",
+            "text-sm font-medium transition-colors",
+            "data-[state=active]:bg-background data-[state=active]:shadow-sm",
+            "data-[state=inactive]:text-muted-foreground"
+          )}
+        >
+          CLI
+        </Tabs.Trigger>
+        <Tabs.Trigger
+          value="manual"
+          className={cn(
+            "inline-flex items-center justify-center rounded-md px-3 py-1.5",
+            "text-sm font-medium transition-colors",
+            "data-[state=active]:bg-background data-[state=active]:shadow-sm",
+            "data-[state=inactive]:text-muted-foreground"
+          )}
+        >
+          Manual
+        </Tabs.Trigger>
+      </Tabs.List>
+
+      <Tabs.Content value="cli" className="mt-4">
+        <ClientCodeWrapper code={cliCommand}>
+          <pre className="overflow-auto rounded-md border bg-muted p-4 text-sm">
+            <code>{cliCommand}</code>
+          </pre>
+        </ClientCodeWrapper>
+      </Tabs.Content>
+
+      <Tabs.Content value="manual" className="mt-4">
+        <div className="rounded-md border bg-muted p-4">
+          <p className="text-sm text-muted-foreground">
+            Copy the component source code from the{" "}
+            <a
+              href={`${registryUrl}/r/${componentName}.json`}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="font-medium text-foreground underline underline-offset-4"
+            >
+              registry JSON
+            </a>{" "}
+            and paste it into your project at{" "}
+            <code className="rounded bg-background px-1 py-0.5 text-xs">
+              components/ui/{componentName}.tsx
+            </code>
+          </p>
+        </div>
+      </Tabs.Content>
+    </Tabs.Root>
+  )
+}
+```
+
+### 3.3 Add Prose Typography to Globals
+
+**Update:** `apps/www/src/app/globals.css`
+
+Add the following prose configuration:
+
+```css
+/* Documentation Prose Typography */
+@layer components {
+  .prose-docs {
+    @apply prose prose-neutral dark:prose-invert max-w-none;
+    
+    /* Headings */
+    @apply prose-h1:scroll-m-20 prose-h1:text-3xl prose-h1:font-semibold prose-h1:tracking-tight;
+    @apply prose-h2:mt-12 prose-h2:scroll-m-20 prose-h2:border-b prose-h2:pb-2 prose-h2:text-xl prose-h2:font-medium;
+    @apply prose-h3:mt-8 prose-h3:scroll-m-20 prose-h3:text-lg prose-h3:font-medium;
+    
+    /* Content */
+    @apply prose-p:leading-7;
+    @apply prose-strong:font-medium;
+    @apply prose-code:rounded prose-code:bg-muted prose-code:px-1 prose-code:py-0.5 prose-code:text-sm;
+    @apply prose-code:before:content-none prose-code:after:content-none;
+    
+    /* Tables */
+    @apply prose-table:block prose-table:overflow-y-auto;
+    
+    /* Images */
+    @apply prose-img:m-0 prose-img:rounded-md;
+  }
+}
+```
+
+### 3.4 Update Index Export
+
+**Update:** `apps/www/src/components/docs/index.ts`
+
+```typescript
+export { CodeRenderer } from "./code-renderer"
+export { ClientCodeWrapper } from "./client-code-wrapper"
+export { ComponentCodePreview } from "./component-code-preview"
+export { ApiTable } from "./api-table"
+export { ComponentNav } from "./component-nav"
+export { InstallationTabs } from "./installation-tabs"
+```
+
+### Validation Steps
+
+```bash
+# Type check
+pnpm typecheck --filter=@usage-ui/www
+
+# Lint
+pnpm lint --filter=@usage-ui/www
+
+# Build
+pnpm build --filter=@usage-ui/www
+```
+
+---
+
+## Phase 4: Preview System
+
+### Objective
+Implement hybrid preview rendering based on component type (iframe for blocks, direct for UI components).
+
+### Prerequisites
+- [ ] Phase 3 complete
+- [ ] Core and layout components working
+
+### 4.1 Build ComponentPreview Wrapper
+
+**Create:** `apps/www/src/components/docs/component-preview.tsx`
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { cn } from "@/lib/utils"
+
+interface ComponentPreviewProps {
+  name: string
+  type: "registry:component" | "registry:block"
+  children?: React.ReactNode
+  className?: string
+}
+
+export function ComponentPreview({
+  name,
+  type,
+  children,
+  className,
+}: ComponentPreviewProps) {
+  const isBlock = type === "registry:block"
+
+  if (isBlock) {
+    return (
+      <div className={cn("w-full", className)}>
+        <iframe
+          src={`/demo/${name}`}
+          className="h-[800px] w-full rounded-md border"
+          title={`${name} preview`}
+        />
+      </div>
+    )
+  }
+
+  // Direct rendering for UI components
+  return (
+    <div
+      className={cn(
+        "flex min-h-[350px] w-full items-center justify-center rounded-md border p-8",
+        className
+      )}
+    >
+      <div className="w-full max-w-3xl">
+        {children || (
+          <p className="text-center text-muted-foreground">
+            Preview not available
+          </p>
+        )}
+      </div>
+    </div>
+  )
+}
+```
+
+### 4.2 Create Preview Error Boundary
+
+**Create:** `apps/www/src/components/docs/preview-error-boundary.tsx`
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { AlertCircle } from "lucide-react"
+import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
+
+interface PreviewErrorBoundaryProps {
+  children: React.ReactNode
+}
+
+interface PreviewErrorBoundaryState {
+  hasError: boolean
+  error?: Error
+}
+
+export class PreviewErrorBoundary extends React.Component<
+  PreviewErrorBoundaryProps,
+  PreviewErrorBoundaryState
+> {
+  constructor(props: PreviewErrorBoundaryProps) {
+    super(props)
+    this.state = { hasError: false }
+  }
+
+  static getDerivedStateFromError(error: Error): PreviewErrorBoundaryState {
+    return { hasError: true, error }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <Alert variant="destructive">
+          <AlertCircle className="h-4 w-4" />
+          <AlertTitle>Preview Error</AlertTitle>
+          <AlertDescription>
+            Failed to render component preview.
+            {this.state.error && (
+              <pre className="mt-2 text-xs">{this.state.error.message}</pre>
+            )}
+          </AlertDescription>
+        </Alert>
+      )
+    }
+
+    return this.props.children
+  }
+}
+```
+
+### 4.3 Update Index Export
+
+**Update:** `apps/www/src/components/docs/index.ts`
+
+```typescript
+export { CodeRenderer } from "./code-renderer"
+export { ClientCodeWrapper } from "./client-code-wrapper"
+export { ComponentCodePreview } from "./component-code-preview"
+export { ApiTable } from "./api-table"
+export { ComponentNav } from "./component-nav"
+export { InstallationTabs } from "./installation-tabs"
+export { ComponentPreview } from "./component-preview"
+export { PreviewErrorBoundary } from "./preview-error-boundary"
+```
+
+### Validation Steps
+
+```bash
+# Type check
+pnpm typecheck --filter=@usage-ui/www
+
+# Build
+pnpm build --filter=@usage-ui/www
+
+# Start dev server and test preview rendering
+pnpm dev --filter=@usage-ui/www
+```
+
+---
+
+## Phase 5: Documentation Migration
+
+### Objective
+Create MDX template and migrate one component as a pilot.
+
+### Prerequisites
+- [ ] Phase 4 complete
+- [ ] All documentation components working
+- [ ] At least one component exists in the registry
+
+### 5.1 Create Docs Route Structure
+
+```bash
+# Create docs directory structure
+mkdir -p apps/www/src/app/docs
+mkdir -p apps/www/src/content/docs
+```
+
+### 5.2 Create Docs Layout
+
+**Create:** `apps/www/src/app/docs/layout.tsx`
+
+```tsx
+import { RegistrySidebar } from "@/components/registry/registry-sidebar"
+
+export default function DocsLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <div className="relative mx-auto grid w-full max-w-screen-2xl grid-cols-6 md:grid-cols-12">
+      {/* Sidebar */}
+      <aside className="col-span-6 border-r md:col-span-3 lg:col-span-2">
+        <RegistrySidebar />
+      </aside>
+      
+      {/* Main content */}
+      <main className="col-span-6 md:col-span-9 lg:col-span-8">
+        <div className="px-6 py-10 lg:px-10">
+          <div className="prose-docs">{children}</div>
+        </div>
+      </main>
+    </div>
+  )
+}
+```
+
+### 5.3 Create MDX Documentation Template
+
+**Create:** `apps/www/src/app/docs/[slug]/page.tsx`
+
+```tsx
+import { notFound } from "next/navigation"
+import { getRegistryItem, getRegistryItems } from "@/lib/registry"
+import { getComponentSource } from "@/lib/code"
+import {
+  ComponentCodePreview,
+  ApiTable,
+  ComponentNav,
+  InstallationTabs,
+  ComponentPreview,
+  PreviewErrorBoundary,
+} from "@/components/docs"
+
+export async function generateStaticParams() {
+  const items = getRegistryItems()
+  return items.map((item) => ({ slug: item.name }))
+}
+
+export default async function ComponentDocPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>
+}) {
+  const { slug } = await params
+  const component = getRegistryItem(slug)
+
+  if (!component) {
+    notFound()
+  }
+
+  const sourceCode = getComponentSource(slug)
+
+  return (
+    <>
+      {/* Header */}
+      <h1>{component.title}</h1>
+      <p className="text-lg text-muted-foreground">{component.description}</p>
+
+      {/* Examples Section */}
+      <h2>Examples</h2>
+      
+      <h3>Basic</h3>
+      <ComponentCodePreview name={slug} code={sourceCode}>
+        <PreviewErrorBoundary>
+          <ComponentPreview name={slug} type={component.type}>
+            {/* Dynamic preview would be imported here */}
+          </ComponentPreview>
+        </PreviewErrorBoundary>
+      </ComponentCodePreview>
+
+      {/* Installation Section */}
+      <h2>Installation</h2>
+      <InstallationTabs componentName={slug} />
+
+      {/* API Reference Section */}
+      <h2>API Reference</h2>
+      <h3>{component.title}</h3>
+      
+      {/* 
+        API table data would come from MDX or be generated.
+        For now, show placeholder with instructions.
+      */}
+      <ApiTable
+        data={[
+          {
+            prop: "value",
+            type: "number",
+            default: "Required",
+            description: "The current value",
+          },
+          {
+            prop: "max",
+            type: "number",
+            default: "100",
+            description: "The maximum value",
+          },
+          {
+            prop: "variant",
+            type: '"default" | "success" | "warning" | "danger"',
+            default: '"default"',
+            description: "Visual variant",
+          },
+        ]}
+      />
+
+      {/* Navigation */}
+      <ComponentNav currentName={slug} />
+    </>
+  )
+}
+```
+
+### 5.4 Create Example MDX Documentation
+
+**Create:** `apps/www/src/content/docs/usage-meter.mdx`
+
+```mdx
+---
+title: Usage Meter
+description: A linear progress meter for displaying usage/quota with accessibility support.
+---
+
+# Usage Meter
+
+A linear progress meter component for displaying usage and quota information. Available in both Radix (accessible) and Base (lightweight) versions.
+
+## Examples
+
+### Basic Usage
+
+<ComponentCodePreview name="usage-meter">
+  {/* Preview content */}
+</ComponentCodePreview>
+
+### With Variants
+
+The meter supports four variants: `default`, `success`, `warning`, and `danger`.
+
+<ComponentCodePreview name="usage-meter-variants">
+  {/* Preview content */}
+</ComponentCodePreview>
+
+## Installation
+
+<InstallationTabs componentName="usage-meter" />
+
+## Usage
+
+```tsx
+import { UsageMeter } from "@/components/ui/usage-meter"
+
+export function MyComponent() {
+  return (
+    <UsageMeter
+      value={75}
+      max={100}
+      variant="warning"
+      label="API Requests"
+    />
+  )
+}
+```
+
+## API Reference
+
+### UsageMeter
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | Required | Current usage value |
+| `max` | `number` | `100` | Maximum value |
+| `variant` | `"default" \| "success" \| "warning" \| "danger"` | `"default"` | Visual variant |
+| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Size variant |
+| `label` | `string` | — | Optional label text |
+| `showPercentage` | `boolean` | `true` | Show percentage text |
+
+### UsageMeterBase
+
+Same props as `UsageMeter`, but without Radix dependency.
+
+## Accessibility
+
+The Radix version includes full accessibility support:
+- Proper `role="progressbar"` semantics
+- `aria-valuenow`, `aria-valuemin`, `aria-valuemax` attributes
+- `aria-valuetext` for screen readers
+```
+
+### Validation Steps
+
+```bash
+# Type check
+pnpm typecheck --filter=@usage-ui/www
+
+# Build
+pnpm build --filter=@usage-ui/www
+
+# Start dev server
+pnpm dev --filter=@usage-ui/www
+
+# Visit http://localhost:3000/docs/usage-meter
+```
+
+---
+
+## Phase 6: Validation & Documentation
+
+### Objective
+Update workflows and run full validation.
+
+### Prerequisites
+- [ ] Phase 5 complete
+- [ ] Pilot documentation page working
+
+### 6.1 Update add-registry-component.md Workflow
+
+**Update:** `.agents/workflows/add-registry-component.md`
+
+Add to the validation checklist:
+
+```markdown
+### 9. Create Documentation Page (After Component Complete)
+
+**Create:** `apps/www/src/content/docs/[component-name].mdx`
+
+Use the MDX template:
+
+\`\`\`mdx
+---
+title: Component Name
+description: Brief description of the component.
+---
+
+# Component Name
+
+[Description paragraph]
+
+## Examples
+
+### Basic Usage
+
+<ComponentCodePreview name="component-name">
+  {/* Preview content */}
+</ComponentCodePreview>
+
+## Installation
+
+<InstallationTabs componentName="component-name" />
+
+## API Reference
+
+### ComponentName
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| ... | ... | ... | ... |
+\`\`\`
+```
+
+### 6.2 Create add-component-documentation.md Workflow
+
+**Create:** `.agents/workflows/add-component-documentation.md`
+
+```markdown
+# Workflow: Add Component Documentation
+
+> Step-by-step procedure for adding documentation to an existing registry component.
+
+---
+
+## Prerequisites
+
+- [ ] Component exists in `packages/ui/src/components/registry/`
+- [ ] Component is registered in `packages/ui/registry.json`
+- [ ] Documentation infrastructure is set up (Phase 1-4 complete)
+
+---
+
+## Steps
+
+### 1. Create MDX File
+
+\`\`\`bash
+touch apps/www/src/content/docs/[component-name].mdx
+\`\`\`
+
+### 2. Add Frontmatter
+
+\`\`\`mdx
+---
+title: Component Name
+description: Brief description of the component.
+---
+\`\`\`
+
+### 3. Write Documentation Sections
+
+Include these sections in order:
+
+1. **Title & Description** - H1 and intro paragraph
+2. **Examples** - ComponentCodePreview for each variant
+3. **Installation** - InstallationTabs component
+4. **Usage** - Code example with import
+5. **API Reference** - Props table for each exported component
+6. **Accessibility** (if applicable) - ARIA details
+
+### 4. Add Props Documentation
+
+Document all props in the API Reference table:
+
+| Column | Content |
+|--------|---------|
+| Prop | Prop name in backticks |
+| Type | TypeScript type |
+| Default | Default value or "Required" |
+| Description | Brief description |
+
+### 5. Verify Documentation
+
+\`\`\`bash
+# Start dev server
+pnpm dev --filter=@usage-ui/www
+
+# Visit the page
+open http://localhost:3000/docs/[component-name]
+\`\`\`
+
+### 6. Build and Test
+
+\`\`\`bash
+pnpm build --filter=@usage-ui/www
+\`\`\`
+
+---
+
+## Validation Checklist
+
+- [ ] MDX file exists at correct path
+- [ ] Frontmatter has title and description
+- [ ] Examples section shows component in action
+- [ ] Installation section uses InstallationTabs
+- [ ] API Reference documents all exported components
+- [ ] All props are documented with types
+- [ ] Page renders without errors
+- [ ] Build succeeds
+
+---
+
+## Troubleshooting
+
+### MDX not rendering
+
+**Cause**: MDX loader not configured or file extension wrong.
+
+**Fix**: Verify `next.config.ts` has MDX configuration and file uses `.mdx` extension.
+
+### Component preview not showing
+
+**Cause**: Preview component not imported or type mismatch.
+
+**Fix**: Ensure ComponentPreview receives correct `type` prop.
+
+### Props table not displaying
+
+**Cause**: ApiTable data array malformed.
+
+**Fix**: Verify each row has `prop`, `type`, and `default` fields.
+```
+
+### 6.3 Run Full Validation
+
+```bash
+# Full validation suite
+pnpm lint && pnpm typecheck && pnpm build
+
+# Start dev server and test
+pnpm dev
+
+# Verify in browser:
+# - http://localhost:3000 (home)
+# - http://localhost:3000/docs/[component] (docs page)
+# - http://localhost:3000/registry/[component] (legacy)
+```
+
+### 6.4 Create Changeset
+
+```bash
+pnpm changeset
+
+# Select @usage-ui/www
+# Choose: minor
+# Description: Add component documentation system with MDX, Shiki highlighting, and preview/code tabs
+```
+
+---
+
+## Validation Checklist
+
+### Phase 1: Infrastructure
+- [ ] Shiki installed and working
+- [ ] MDX dependencies installed
+- [ ] `lib/code.ts` extracts source code
+- [ ] `lib/shiki.ts` highlights code
+- [ ] `mdx-components.tsx` configured
+- [ ] `next.config.ts` updated for MDX
+
+### Phase 2: Core Components
+- [ ] `CodeRenderer` highlights code with themes
+- [ ] `ClientCodeWrapper` has working copy button
+- [ ] `ComponentCodePreview` switches between tabs
+- [ ] `ApiTable` renders props documentation
+
+### Phase 3: Layout Components
+- [ ] `ComponentNav` shows previous/next links
+- [ ] `InstallationTabs` shows CLI/Manual options
+- [ ] Prose typography applied
+
+### Phase 4: Preview System
+- [ ] `ComponentPreview` handles both types
+- [ ] Blocks render in iframe
+- [ ] Components render directly
+- [ ] Error boundary catches failures
+
+### Phase 5: Migration
+- [ ] Docs route structure created
+- [ ] Template page working
+- [ ] One component documented as pilot
+
+### Phase 6: Final
+- [ ] Workflows updated
+- [ ] Full build passes
+- [ ] Changeset created
+
+---
+
+## Troubleshooting
+
+### Shiki theme not working in dark mode
+
+**Cause**: CSS not applying theme variables correctly.
+
+**Fix**: Ensure `dark:[&_span]:!text-[var(--shiki-dark)]` is applied to code container.
+
+### MDX not rendering custom components
+
+**Cause**: Components not exported from `mdx-components.tsx`.
+
+**Fix**: Add components to the return object in `useMDXComponents`.
+
+### Source code extraction failing
+
+**Cause**: Path resolution issue in monorepo.
+
+**Fix**: Verify `path.join` uses correct relative paths from `apps/www` to `packages/ui`.
+
+### Build fails with "Cannot find module"
+
+**Cause**: Missing peer dependencies or incorrect imports.
+
+**Fix**: Run `pnpm install` and verify all imports use `@/` aliases.
+
+### Preview shows "not available"
+
+**Cause**: Component type not detected or children not passed.
+
+**Fix**: Verify registry.json has correct `type` field and preview content is provided.
+
+---
+
+## References
+
+- ADR-005: `.agents/context/decisions/005-component-documentation-strategy.md`
+- Research: `.agents/context/research/prompt-kit-component-page-analysis.md`
+- Monorepo Ops: `.agents/workflows/monorepo-operations.md`
+- Component Creation: `.agents/workflows/add-registry-component.md`
diff --git a/MONOREPO-MIGRATION.md b/MONOREPO-MIGRATION.md
deleted file mode 100644
index 5f3a190..0000000
--- a/MONOREPO-MIGRATION.md
+++ /dev/null
@@ -1,1312 +0,0 @@
-# Monorepo Migration Guide
-
-> ✅ **MIGRATION COMPLETE** - January 2026
->
-> This guide documents the completed migration of Usage UI from single-app to monorepo structure.
-> It is preserved for reference and troubleshooting.
-
----
-
-> **Approach Used**: Hybrid method — used shadcn CLI as a configuration reference, executed manual migration to preserve git history and customizations.
-
-## Table of Contents
-
-1. [Prerequisites](#prerequisites)
-2. [Migration Strategy](#migration-strategy)
-3. [Phase 0: Pre-flight & Reference Generation](#phase-0-pre-flight--reference-generation)
-4. [Phase 1: Root Configuration](#phase-1-root-configuration)
-5. [Phase 2: Directory Structure](#phase-2-directory-structure)
-6. [Phase 3: Move App to apps/www](#phase-3-move-app-to-appswww)
-7. [Phase 4: Set Up packages/ui](#phase-4-set-up-packagesui)
-8. [Phase 5: Shared Tooling](#phase-5-shared-tooling)
-9. [Phase 6: CI/CD](#phase-6-cicd)
-10. [Phase 7: Install and Verify](#phase-7-install-and-verify)
-11. [Phase 7.5: Dependency Reconciliation](#phase-75-dependency-reconciliation)
-12. [Phase 8: Cleanup](#phase-8-cleanup)
-13. [Phase 9: Post-Migration Validation](#phase-9-post-migration-validation)
-14. [Troubleshooting](#troubleshooting)
-15. [Common Pitfalls](#common-pitfalls)
-
----
-
-## Prerequisites
-
-- [x] Node.js 22+ installed (`node --version`)
-- [x] pnpm 9.15+ installed (`pnpm --version`)
-- [x] Current codebase committed to git (clean working tree)
-- [x] Backup branch created: `git checkout -b pre-monorepo-backup && git checkout -`
-
----
-
-## Migration Strategy
-
-### Why Hybrid Approach?
-
-| Approach | Pros | Cons |
-|----------|------|------|
-| **Option A: CLI Scaffold** | Guaranteed correct config | Loses git history, requires manual code copy |
-| **Option B: Manual Only** | Preserves history | Prone to configuration errors |
-| **Hybrid (Recommended)** | Correct configs + preserved history | Slightly more setup time |
-
-### Hybrid Method
-
-1. **Generate reference**: Use `npx shadcn@latest init` in a temp directory to get correct configurations
-2. **Execute manually**: Migrate your project using the reference configs
-3. **Result**: Best of both worlds — correct configs AND preserved git history
-
----
-
-## Phase 0: Pre-flight & Reference Generation
-
-### 0.1 Verify Clean State
-
-```bash
-# Ensure working tree is clean
-git status
-
-# Create backup branch
-git checkout -b pre-monorepo-backup
-git checkout -
-```
-
-### 0.2 Generate Reference Configuration (Optional but Recommended)
-
-```bash
-# Create temporary directory for reference
-# macOS/Linux:
-mkdir -p /tmp/shadcn-monorepo-reference
-cd /tmp/shadcn-monorepo-reference
-
-# Windows (PowerShell):
-# mkdir $env:TEMP\shadcn-monorepo-reference
-# cd $env:TEMP\shadcn-monorepo-reference
-
-# Generate reference monorepo structure
-pnpm dlx shadcn@latest init
-# Select: "Next.js (Monorepo)"
-# This creates correct turbo.json, components.json, tsconfig.json
-
-# Keep this open for reference during migration
-# Key files to reference:
-# - turbo.json
-# - apps/web/components.json
-# - packages/ui/components.json
-# - pnpm-workspace.yaml
-```
-
-**Checkpoint:** `[x]` Reference generated or skipped
-
----
-
-## Phase 1: Root Configuration
-
-### 1.1 Create Workspace File
-
-Create `pnpm-workspace.yaml` at root:
-
-```yaml
-packages:
-  - "apps/*"
-  - "packages/*"
-  - "tooling/*"
-```
-
-### 1.2 Update Root package.json
-
-> **Note**: Both `turbo run <task>` and `turbo <task>` work in Turbo v2+. We use `turbo run` for explicitness.
-
-Replace current `package.json` with:
-
-```json
-{
-  "name": "usage-ui",
-  "version": "0.0.0",
-  "private": true,
-  "scripts": {
-    "build": "turbo run build",
-    "dev": "turbo run dev",
-    "lint": "turbo run lint",
-    "typecheck": "turbo run typecheck",
-    "clean": "turbo run clean && rm -rf node_modules .turbo",
-    "format": "biome format --write .",
-    "check": "biome check .",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "turbo run build --filter=./packages/* && changeset publish"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "@changesets/cli": "^2.27.0",
-    "lefthook": "^1.6.0",
-    "turbo": "^2.3.0",
-    "typescript": "^5.4.5"
-  },
-  "packageManager": "pnpm@9.15.2",
-  "engines": {
-    "node": ">=22"
-  }
-}
-```
-
-### 1.3 Create turbo.json
-
-```json
-{
-  "$schema": "https://turbo.build/schema.json",
-  "ui": "tui",
-  "tasks": {
-    "build": {
-      "dependsOn": ["^build"],
-      "outputs": [".next/**", "!.next/cache/**", "dist/**", "public/r/**"]
-    },
-    "dev": {
-      "cache": false,
-      "persistent": true
-    },
-    "lint": {},
-    "typecheck": {},
-    "clean": {
-      "cache": false
-    }
-  }
-}
-```
-
-### 1.4 Create lefthook.yml
-
-```yaml
-pre-commit:
-  parallel: true
-  commands:
-    lint:
-      glob: "*.{js,ts,tsx,json}"
-      run: pnpm biome check --staged --no-errors-on-unmatched {staged_files}
-    typecheck:
-      run: pnpm run typecheck
-
-commit-msg:
-  commands:
-    conventional:
-      run: |
-        message=$(cat {1})
-        pattern="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .+"
-        if ! echo "$message" | grep -qE "$pattern"; then
-          echo "Commit message must follow Conventional Commits format"
-          echo "Examples: feat: add usage meter, fix(ui): correct color"
-          exit 1
-        fi
-```
-
-### 1.5 Verify Root Config
-
-```bash
-# Verify files exist
-ls -la pnpm-workspace.yaml turbo.json lefthook.yml package.json
-```
-
-**Checkpoint:** `[x]` Root config files created and verified
-
----
-
-## Phase 2: Directory Structure
-
-### 2.1 Create All Directories
-
-```bash
-# Create monorepo directories
-mkdir -p apps/www
-mkdir -p packages/ui/src/{components/{ui,registry},hooks,lib,styles}
-mkdir -p tooling/typescript
-mkdir -p .changeset
-mkdir -p .github/workflows
-```
-
-### 2.2 Verify Structure
-
-```bash
-# Should show: apps, packages, tooling, .changeset, .github
-ls -la
-ls -la apps packages tooling
-```
-
-**Checkpoint:** `[x]` Directory structure created
-
----
-
-## Phase 3: Move App to apps/www
-
-### 3.1 Move Source Files
-
-```bash
-# Move app code (order matters!)
-mv src apps/www/
-mv public apps/www/
-mv next.config.ts apps/www/
-mv postcss.config.mjs apps/www/
-
-# Keep these at root:
-# - biome.json (shared)
-# - tsconfig.json (will be updated)
-# - registry.json (will move to packages/ui)
-# - components.json (will be updated)
-```
-
-### 3.2 Create apps/www/package.json
-
-> ⚠️ **Important**: If `apps/www/src/components/ui/` contains shadcn components, you need their dependencies here too. The list below includes all common shadcn/ui dependencies. Remove any you don't use.
-
-```json
-{
-  "name": "@usage-ui/www",
-  "version": "0.0.1",
-  "private": true,
-  "scripts": {
-    "dev": "next dev --turbopack",
-    "build": "next build",
-    "start": "next start",
-    "lint": "biome check src/",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@usage-ui/ui": "workspace:*",
-    "@hookform/resolvers": "^5.2.2",
-    "@tanstack/react-table": "^8.21.3",
-    "@vercel/analytics": "^1.6.1",
-    "@vercel/speed-insights": "^1.3.1",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "cmdk": "^1.1.1",
-    "date-fns": "^4.1.0",
-    "embla-carousel-react": "^8.6.0",
-    "input-otp": "^1.4.2",
-    "lucide-react": "^0.506.0",
-    "next": "^16.0.10",
-    "next-themes": "^0.4.6",
-    "radix-ui": "^1.4.3",
-    "react": "^19.2.3",
-    "react-day-picker": "^9.12.0",
-    "react-dom": "^19.2.3",
-    "react-hook-form": "^7.68.0",
-    "react-resizable-panels": "^3.0.6",
-    "recharts": "^2.15.4",
-    "sonner": "^2.0.7",
-    "tailwind-merge": "^3.4.0",
-    "vaul": "^1.1.2",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4.1.18",
-    "@types/node": "^22.19.3",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
-    "postcss": "^8.5.6",
-    "tailwindcss": "^4.1.18",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^5.4.5"
-  }
-}
-```
-
-### 3.3 Create apps/www/tsconfig.json
-
-```json
-{
-  "extends": "../../tooling/typescript/base.json",
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"],
-      "@usage-ui/ui": ["../../packages/ui/src"],
-      "@usage-ui/ui/*": ["../../packages/ui/src/*"]
-    },
-    "plugins": [{ "name": "next" }]
-  },
-  "include": ["src/**/*", "next-env.d.ts", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
-}
-```
-
-### 3.4 Create apps/www/components.json
-
-> ⚠️ **Critical**: This file tells the shadcn CLI where to install components and how to resolve imports. The CSS path must point to the shared styles in packages/ui.
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": true,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "../../packages/ui/src/styles/globals.css",
-    "baseColor": "neutral",
-    "cssVariables": true
-  },
-  "iconLibrary": "lucide",
-  "aliases": {
-    "components": "@/components",
-    "hooks": "@/hooks",
-    "lib": "@/lib",
-    "utils": "@usage-ui/ui/lib/utils",
-    "ui": "@usage-ui/ui/components"
-  }
-}
-```
-
-### 3.5 Verify apps/www Structure
-
-```bash
-ls -la apps/www/
-# Should show: src/, public/, next.config.ts, postcss.config.mjs, package.json, tsconfig.json, components.json
-```
-
-### 3.6 Ensure Site Registry File Exists
-
-> **Registry File Architecture**: This project uses **two registry files** with different purposes:
->
-> | File | Purpose | Used By |
-> |------|---------|---------|
-> | `packages/ui/registry.json` | Component manifest for shadcn CLI | External users installing components |
-> | `apps/www/src/registry.json` | Documentation site data | `apps/www/src/lib/registry.ts` for UI display |
-
-If your docs site imports from `@/registry.json` (check `apps/www/src/lib/registry.ts`), ensure the file exists:
-
-```bash
-# Check if registry.ts imports from @/registry.json
-if grep -q "@/registry.json" apps/www/src/lib/registry.ts 2>/dev/null; then
-  # Verify the file exists
-  if [ ! -f apps/www/src/registry.json ]; then
-    echo "⚠️  apps/www/src/registry.json is missing but required by registry.ts"
-    echo "   Copy from root or create: cp registry.json apps/www/src/registry.json"
-  else
-    echo "✅ apps/www/src/registry.json exists"
-  fi
-fi
-```
-
-If missing, copy from root before Phase 8 deletes it:
-
-```bash
-cp registry.json apps/www/src/registry.json
-```
-
-**Checkpoint:** `[x]` apps/www configured with all files
-**Checkpoint:** `[x]` Site registry file exists (if needed by registry.ts)
-
----
-
-## Phase 4: Set Up packages/ui
-
-### 4.1 Create packages/ui/package.json
-
-> ⚠️ **Important**: shadcn/ui components have many peer dependencies. The list below includes all common ones. Adjust based on which components exist in `packages/ui/src/components/ui/`.
-
-```json
-{
-  "name": "@usage-ui/ui",
-  "version": "0.1.0",
-  "private": false,
-  "sideEffects": false,
-  "exports": {
-    "./registry.json": "./registry.json",
-    "./components": "./src/components/index.ts",
-    "./components/*": "./src/components/*/index.ts",
-    "./hooks/*": "./src/hooks/*.ts",
-    "./lib/*": "./src/lib/*.ts",
-    "./styles/*": "./src/styles/*"
-  },
-  "scripts": {
-    "build": "pnpm dlx shadcn@latest build --output ../../apps/www/public/r",
-    "lint": "biome check src/",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "cmdk": "^1.1.1",
-    "embla-carousel-react": "^8.6.0",
-    "input-otp": "^1.4.2",
-    "lucide-react": "^0.506.0",
-    "next-themes": "^0.4.6",
-    "radix-ui": "^1.4.3",
-    "react-day-picker": "^9.12.0",
-    "react-hook-form": "^7.68.0",
-    "react-resizable-panels": "^3.0.6",
-    "recharts": "^2.15.4",
-    "sonner": "^2.0.7",
-    "tailwind-merge": "^3.4.0",
-    "vaul": "^1.1.2"
-  },
-  "devDependencies": {
-    "@types/react": "^19.2.7",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "typescript": "^5.4.5"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0",
-    "tailwindcss": "^4.0.0"
-  }
-}
-```
-
-<details>
-<summary>📦 Dependency Reference: Which packages are needed for which components</summary>
-
-| Package | Required By |
-|---------|-------------|
-| `class-variance-authority` | All components using `cva()` variants |
-| `clsx` | All components (via `cn()` utility) |
-| `tailwind-merge` | All components (via `cn()` utility) |
-| `radix-ui` | Most primitives (Dialog, Dropdown, Select, etc.) |
-| `lucide-react` | Components with icons |
-| `cmdk` | Command component |
-| `embla-carousel-react` | Carousel component |
-| `input-otp` | InputOTP component |
-| `next-themes` | ThemeProvider, theme toggle |
-| `react-day-picker` | Calendar, DatePicker components |
-| `react-hook-form` | Form component |
-| `react-resizable-panels` | Resizable component |
-| `recharts` | Chart components |
-| `sonner` | Sonner toast component |
-| `vaul` | Drawer component |
-
-</details>
-
-### 4.2 Create packages/ui/tsconfig.json
-
-```json
-{
-  "extends": "../../tooling/typescript/base.json",
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}
-```
-
-### 4.3 Create packages/ui/registry.json
-
-> ⚠️ **Critical**: This is the component manifest. Start clean, add components as you build them.
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema/registry.json",
-  "name": "usage-ui",
-  "homepage": "https://usage-ui.vercel.app",
-  "items": []
-}
-```
-
-### 4.4 Create packages/ui/components.json
-
-> ⚠️ **Critical**: Aliases must use the package name pattern for proper resolution.
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": true,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "src/styles/globals.css",
-    "baseColor": "neutral",
-    "cssVariables": true
-  },
-  "iconLibrary": "lucide",
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "hooks": "@/hooks",
-    "lib": "@/lib",
-    "ui": "@/components/ui"
-  }
-}
-```
-
-### 4.5 Copy Shared Code to packages/ui
-
-```bash
-# Copy utilities
-cp apps/www/src/lib/utils.ts packages/ui/src/lib/
-
-# Copy base shadcn components
-cp -r apps/www/src/components/ui/* packages/ui/src/components/ui/
-
-# Copy hooks if any exist
-if ls apps/www/src/hooks/*.ts 1>/dev/null 2>&1; then
-  cp apps/www/src/hooks/*.ts packages/ui/src/hooks/
-else
-  echo "No hooks to copy (this is fine)"
-fi
-```
-
-### 4.6 Create packages/ui/src/styles/globals.css
-
-> This contains only the meter-specific CSS variables. The full theme remains in apps/www.
-
-```css
-@import "tailwindcss";
-
-@theme inline {
-  /* Usage UI - Meter Status Colors */
-  --color-meter-success: oklch(0.723 0.191 142.5);
-  --color-meter-warning: oklch(0.795 0.184 86.047);
-  --color-meter-danger: oklch(0.637 0.237 25.331);
-  --color-meter-info: oklch(0.623 0.214 259.1);
-
-  /* Usage UI - Meter Track Colors */
-  --color-meter-track: oklch(0.928 0.006 264.5);
-  --color-meter-track-foreground: oklch(0.45 0.03 264.5);
-}
-
-@layer base {
-  :root {
-    /* Meter CSS variables for direct use */
-    --meter-success: var(--color-meter-success);
-    --meter-warning: var(--color-meter-warning);
-    --meter-danger: var(--color-meter-danger);
-    --meter-info: var(--color-meter-info);
-    --meter-track: var(--color-meter-track);
-    --meter-track-foreground: var(--color-meter-track-foreground);
-  }
-
-  .dark {
-    --meter-success: oklch(0.627 0.194 142.5);
-    --meter-warning: oklch(0.695 0.184 86.047);
-    --meter-danger: oklch(0.577 0.237 25.331);
-    --meter-info: oklch(0.523 0.214 259.1);
-    --meter-track: oklch(0.269 0.006 264.5);
-    --meter-track-foreground: oklch(0.708 0.03 264.5);
-  }
-}
-```
-
-### 4.7 Create Component Barrel Files
-
-> ⚠️ **Important**: TypeScript requires files to have at least one export to be valid modules. Since `registry/` is empty initially, we need a placeholder export.
-
-**First**, create the registry index with a valid empty export:
-
-```bash
-cat > packages/ui/src/components/registry/index.ts << 'EOF'
-// Registry components will be exported here as they are created
-// Example: export * from "./usage-meter";
-
-// Placeholder export to ensure this is a valid module
-export {};
-EOF
-```
-
-**Then**, create the main barrel file `packages/ui/src/components/index.ts`:
-
-```ts
-// Re-export component directories
-export * from "./ui";
-export * from "./registry";
-```
-
-### 4.8 Verify packages/ui Structure
-
-```bash
-ls -la packages/ui/
-# Should show: src/, package.json, tsconfig.json, registry.json, components.json
-
-ls -la packages/ui/src/
-# Should show: components/, hooks/, lib/, styles/
-
-ls -la packages/ui/src/components/
-# Should show: ui/, registry/
-```
-
-**Checkpoint:** `[x]` packages/ui configured with all files
-
----
-
-## Phase 5: Shared Tooling
-
-### 5.1 Create tooling/typescript/package.json
-
-> **Note**: Even though this folder only contains config files, pnpm requires a package.json for workspace recognition.
-
-```json
-{
-  "name": "@usage-ui/typescript-config",
-  "version": "0.0.0",
-  "private": true
-}
-```
-
-### 5.2 Create tooling/typescript/base.json
-
-```json
-{
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "compilerOptions": {
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "moduleResolution": "bundler",
-    "module": "ESNext",
-    "target": "ES2022",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "noEmit": true,
-    "jsx": "preserve",
-    "incremental": true
-  },
-  "exclude": ["node_modules"]
-}
-```
-
-### 5.3 Create .changeset/config.json
-
-```json
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": ["@usage-ui/www"]
-}
-```
-
-### 5.4 Update Root tsconfig.json
-
-Replace the root `tsconfig.json`:
-
-```json
-{
-  "extends": "./tooling/typescript/base.json",
-  "compilerOptions": {
-    "baseUrl": "."
-  },
-  "include": [],
-  "exclude": ["node_modules", "apps", "packages", "tooling"],
-  "references": [
-    { "path": "./apps/www" },
-    { "path": "./packages/ui" }
-  ]
-}
-```
-
-**Checkpoint:** `[x]` Shared tooling configured
-
----
-
-## Phase 6: CI/CD
-
-### 6.1 Create .github/workflows/ci.yml
-
-```yaml
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: "pnpm"
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Lint
-        run: pnpm run lint
-
-      - name: Type check
-        run: pnpm run typecheck
-
-      - name: Build
-        run: pnpm run build
-```
-
-**Checkpoint:** `[x]` CI/CD configured
-
----
-
-## Phase 7: Install and Verify
-
-### 7.1 Clean Install
-
-```bash
-# Remove old artifacts
-rm -rf node_modules pnpm-lock.yaml .turbo
-
-# Also remove from moved locations
-rm -rf apps/www/node_modules packages/ui/node_modules
-
-# Fresh install
-pnpm install
-```
-
-### 7.2 Verify Workspace Recognition
-
-```bash
-# Should show both packages
-pnpm ls --depth 0
-
-# Should list @usage-ui/www and @usage-ui/ui
-pnpm ls -r --depth 0
-```
-
-### 7.3 Test Build
-
-```bash
-# Build all packages
-pnpm run build
-
-# Expected: Both packages build successfully
-```
-
-### 7.4 Test Dev Server
-
-```bash
-# Start dev server
-pnpm run dev
-
-# Open http://localhost:3000 - should load
-```
-
-### 7.5 Test Individual Commands
-
-```bash
-# Lint all
-pnpm run lint
-
-# Type check all
-pnpm run typecheck
-
-# Test filter syntax
-pnpm run build --filter=@usage-ui/ui
-pnpm run build --filter=@usage-ui/www
-```
-
-**Checkpoint:** `[x]` All builds and commands succeed
-
----
-
-## Phase 7.5: Dependency Reconciliation
-
-> Even well-planned migrations often reveal missing dependencies during validation. This phase systematically identifies and fixes them.
-
-### 7.5.1 Identify Missing Dependencies
-
-If `pnpm install` succeeds but `pnpm build` or `pnpm typecheck` fails with import errors:
-
-```bash
-# Capture TypeScript errors for missing modules
-pnpm typecheck 2>&1 | grep "Cannot find module" | sort -u
-
-# Common patterns:
-# - "Cannot find module 'class-variance-authority'" → missing in package.json
-# - "Cannot find module '@/registry.json'" → missing file
-# - "File is not a module" → empty index.ts without exports
-```
-
-### 7.5.2 Fix apps/www Dependencies
-
-If UI components in `apps/www/src/components/ui/` fail to build, add their dependencies:
-
-```bash
-# Core shadcn dependencies (almost always needed)
-pnpm add class-variance-authority clsx radix-ui tailwind-merge --filter=@usage-ui/www
-
-# Data visualization
-pnpm add recharts --filter=@usage-ui/www
-
-# Component-specific (add as needed based on errors)
-pnpm add lucide-react --filter=@usage-ui/www  # Icons
-```
-
-### 7.5.3 Fix packages/ui Dependencies
-
-If components in `packages/ui/src/components/ui/` fail to build:
-
-```bash
-# Add missing shadcn component dependencies
-pnpm add lucide-react cmdk embla-carousel-react input-otp next-themes \
-  react-day-picker react-hook-form react-resizable-panels sonner vaul \
-  --filter=@usage-ui/ui
-```
-
-### 7.5.4 Fix Missing Registry File
-
-If `apps/www/src/lib/registry.ts` imports `@/registry.json` but the file doesn't exist:
-
-```bash
-# Check if the import exists
-grep -l "@/registry.json" apps/www/src/lib/*.ts
-
-# If found, copy from packages/ui or root
-cp packages/ui/registry.json apps/www/src/registry.json
-# OR if you have site-specific registry data:
-cp registry.json apps/www/src/registry.json
-```
-
-### 7.5.5 Fix Empty Module Exports
-
-If TypeScript errors with "File is not a module" for `packages/ui/src/components/registry/index.ts`:
-
-```bash
-# Create valid empty export
-cat > packages/ui/src/components/registry/index.ts << 'EOF'
-// Registry components will be exported here as they are created
-// Example: export * from "./usage-meter";
-
-// Placeholder export to ensure this is a valid module
-export {};
-EOF
-```
-
-### 7.5.6 Re-validate
-
-After fixes, re-run validation:
-
-```bash
-pnpm install        # Refresh dependencies
-pnpm typecheck      # Should pass
-pnpm build          # Should succeed
-pnpm dev            # Should start without errors
-```
-
-**Checkpoint:** `[x]` All TypeScript errors resolved
-**Checkpoint:** `[x]` Build succeeds without errors
-**Checkpoint:** `[x]` Dev server starts cleanly
-
----
-
-## Phase 8: Cleanup
-
-### 8.1 Remove Old Root Files
-
-```bash
-# Remove old files that were moved
-rm -f components.json  # Moved to apps/www/ and packages/ui/
-rm -f registry.json    # Replaced by packages/ui/registry.json
-
-# Keep at root:
-# - biome.json (shared)
-# - package.json (updated)
-# - tsconfig.json (updated)
-# - turbo.json (new)
-# - pnpm-workspace.yaml (new)
-# - lefthook.yml (new)
-```
-
-### 8.2 Enable Git Hooks
-
-```bash
-# Install lefthook hooks
-pnpm lefthook install
-```
-
-### 8.3 Remove Demo Components (Optional)
-
-If you want to start fresh without the Vercel Registry Starter demo components:
-
-```bash
-# Remove demo brand components
-rm -f apps/www/src/components/brand-header.tsx
-rm -f apps/www/src/components/brand-sidebar.tsx
-rm -f apps/www/src/components/hero.tsx
-rm -f apps/www/src/components/login.tsx
-rm -f apps/www/src/components/logo.tsx
-rm -f apps/www/src/components/product-grid.tsx
-rm -f apps/www/src/components/promo.tsx
-rm -f apps/www/src/lib/products.ts
-```
-
-### 8.4 Update apps/www/src/app/globals.css
-
-> ⚠️ **Important**: Choose ONE approach to avoid duplicate Tailwind base styles.
-
-**Option A: App owns Tailwind, package adds variables only**
-
-Keep your existing `globals.css` with `@import "tailwindcss"`, then add meter variables:
-
-```css
-@import "tailwindcss";
-
-/* Import meter-specific CSS variables (no Tailwind base) */
-@import "@usage-ui/ui/styles/meter-variables.css";
-
-/* Your existing theme variables... */
-```
-
-**Option B: Package owns shared styles (simpler)**
-
-Replace your `globals.css` to import everything from the package:
-
-```css
-/* Import complete shared styles including Tailwind */
-@import "@usage-ui/ui/styles/globals.css";
-
-/* App-specific overrides only */
-```
-
-If using Option A, rename `packages/ui/src/styles/globals.css` to `meter-variables.css` and remove the `@import "tailwindcss"` line from it.
-
-### 8.5 Update .gitignore
-
-Add monorepo-specific ignores:
-
-```bash
-# Add to .gitignore
-cat >> .gitignore << 'EOF'
-
-# Monorepo build artifacts
-apps/www/.next/
-apps/www/.turbo/
-packages/ui/dist/
-.turbo/
-
-# Generated registry files (optional - some prefer to commit these)
-# apps/www/public/r/
-EOF
-```
-
-**Checkpoint:** `[x]` Cleanup complete
-
----
-
-## Phase 9: Post-Migration Validation
-
-### 9.1 Final Verification Checklist
-
-```bash
-# Run all checks
-pnpm install          # ✅ Should complete without errors
-pnpm run build        # ✅ Should build all packages
-pnpm run dev          # ✅ Should start dev server
-pnpm run lint         # ✅ Should pass
-pnpm run typecheck    # ✅ Should pass
-```
-
-### 9.2 Test shadcn CLI Integration
-
-```bash
-# Navigate to apps/www
-cd apps/www
-
-# Test adding a component (should install to packages/ui)
-pnpm dlx shadcn@latest add button --dry-run
-
-# The CLI should recognize the monorepo structure
-```
-
-### 9.3 Verify Browser
-
-- [x] Open `http://localhost:3000`
-- [x] Site loads correctly
-- [x] No console errors
-- [x] Theme works (light/dark toggle if present)
-
-### 9.4 Test Git Hooks
-
-```bash
-# Create a test commit
-git add .
-git commit -m "test: verify hooks work"
-# Should run lint and typecheck before commit
-
-# If using conventional commits, this should fail:
-git commit -m "bad commit message"
-```
-
-### 9.5 Create First Component (Validates Setup)
-
-Create a minimal component to validate the entire pipeline:
-
-```bash
-# Create component directory
-mkdir -p packages/ui/src/components/registry/usage-meter
-
-# Create minimal component file
-cat > packages/ui/src/components/registry/usage-meter/usage-meter.tsx << 'EOF'
-"use client"
-
-import * as React from "react"
-import { cn } from "@/lib/utils"
-
-interface UsageMeterProps extends React.HTMLAttributes<HTMLDivElement> {
-  value: number
-  max?: number
-}
-
-function UsageMeter({ value, max = 100, className, ...props }: UsageMeterProps) {
-  const percentage = Math.min(100, Math.max(0, (value / max) * 100))
-  
-  return (
-    <div
-      role="progressbar"
-      aria-valuenow={value}
-      aria-valuemin={0}
-      aria-valuemax={max}
-      className={cn("relative h-3 w-full overflow-hidden rounded-full bg-secondary", className)}
-      {...props}
-    >
-      <div
-        className="h-full bg-primary transition-all"
-        style={{ width: `${percentage}%` }}
-      />
-    </div>
-  )
-}
-
-export { UsageMeter }
-export type { UsageMeterProps }
-EOF
-
-# Create index file
-cat > packages/ui/src/components/registry/usage-meter/index.ts << 'EOF'
-export { UsageMeter } from "./usage-meter"
-export type { UsageMeterProps } from "./usage-meter"
-EOF
-```
-
-Add to `packages/ui/registry.json`:
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema/registry.json",
-  "name": "usage-ui",
-  "homepage": "https://usage-ui.vercel.app",
-  "items": [
-    {
-      "name": "usage-meter",
-      "type": "registry:component",
-      "title": "Usage Meter",
-      "description": "A linear meter for displaying usage/quota percentages.",
-      "dependencies": [],
-      "registryDependencies": [],
-      "files": [
-        {
-          "path": "src/components/registry/usage-meter/usage-meter.tsx",
-          "target": "components/ui/usage-meter.tsx"
-        }
-      ]
-    }
-  ]
-}
-```
-
-Test the build:
-
-```bash
-# Build registry (outputs to apps/www/public/r/)
-pnpm run build --filter=@usage-ui/ui
-
-# Verify output exists
-ls apps/www/public/r/usage-meter.json
-```
-
-> **Note**: The `--output` flag in `packages/ui/package.json` build script tells shadcn where to generate the registry JSON files.
-
-**Checkpoint:** `[x]` Migration complete and validated
-
----
-
-## Troubleshooting
-
-### "Workspace package not found"
-
-**Cause**: `pnpm-workspace.yaml` missing or malformed.
-
-**Fix**:
-```bash
-# Verify file exists at root
-cat pnpm-workspace.yaml
-
-# Should contain:
-# packages:
-#   - "apps/*"
-#   - "packages/*"
-#   - "tooling/*"
-```
-
-### "Cannot find module @usage-ui/ui"
-
-**Cause**: TypeScript path mapping incorrect or pnpm not recognizing workspace.
-
-**Fix**:
-```bash
-# Check apps/www/tsconfig.json has:
-# "paths": {
-#   "@usage-ui/ui": ["../../packages/ui/src"],
-#   "@usage-ui/ui/*": ["../../packages/ui/src/*"]
-# }
-
-# Reinstall to refresh workspace links
-rm -rf node_modules pnpm-lock.yaml
-pnpm install
-```
-
-### "turbo: command not found"
-
-**Cause**: Turbo not installed in devDependencies.
-
-**Fix**:
-```bash
-pnpm install
-# or explicitly:
-pnpm add -D turbo -w
-```
-
-### "Recursive turbo invocations" (Turbo v1 only)
-
-**Cause**: In Turbo v1, script names conflicting with task names caused recursion.
-
-**Note**: Turbo v2+ handles this automatically. If you're on v2+, this is not an issue. For v1:
-
-**Fix**: Use `turbo run build` not `turbo build`:
-```json
-{
-  "scripts": {
-    "build": "turbo run build"  // Explicit form (works in all versions)
-  }
-}
-```
-
-### Build fails with type errors
-
-**Cause**: TypeScript config not extending shared base.
-
-**Fix**:
-```bash
-# Verify tooling/typescript/base.json exists
-cat tooling/typescript/base.json
-
-# Verify packages extend it:
-# apps/www/tsconfig.json: "extends": "../../tooling/typescript/base.json"
-# packages/ui/tsconfig.json: "extends": "../../tooling/typescript/base.json"
-```
-
-### "Cannot find CSS file" or styles not working
-
-**Cause**: CSS path in `components.json` is incorrect.
-
-**Fix**: Verify paths:
-```
-apps/www/components.json:
-  "css": "../../packages/ui/src/styles/globals.css"
-
-packages/ui/components.json:
-  "css": "src/styles/globals.css"
-```
-
-### shadcn CLI installs to wrong location
-
-**Cause**: `components.json` aliases not pointing to workspace package.
-
-**Fix**: In `apps/www/components.json`:
-```json
-{
-  "aliases": {
-    "utils": "@usage-ui/ui/lib/utils",
-    "ui": "@usage-ui/ui/components"
-  }
-}
-```
-
----
-
-## Common Pitfalls
-
-| Pitfall | Prevention |
-|---------|------------|
-| Script recursion (Turbo v1) | Use `turbo run <task>` in root scripts (v2+ handles this) |
-| CSS path wrong | Use relative paths from the file's location |
-| Missing workspace protocol | Use `workspace:*` for internal deps |
-| Forgetting `pnpm-workspace.yaml` | Create before running `pnpm install` |
-| Not copying `utils.ts` | Copy to `packages/ui/src/lib/utils.ts` |
-| Mismatched component.json aliases | Use `@usage-ui/ui/` prefix for shared code |
-| Old node_modules | Clean install after restructuring |
-| Missing shared tsconfig | Create `tooling/typescript/base.json` first |
-| Missing tooling package.json | Add minimal package.json to `tooling/typescript/` |
-| Duplicate Tailwind imports | Only ONE package should `@import "tailwindcss"` |
-| Export/alias mismatch | Ensure package exports match component.json aliases |
-| Missing shadcn dependencies | Include `cva`, `clsx`, `radix-ui`, `tailwind-merge` in packages with UI components |
-| Two registry files needed | `packages/ui/registry.json` (CLI) + `apps/www/src/registry.json` (site) |
-| Empty registry/index.ts | Add `export {};` placeholder until components exist |
-| Incomplete dependency analysis | Analyze imports in moved files before creating package.json |
-
----
-
-## Quick Reference
-
-### Package Names
-
-| Package | Name | Location |
-|---------|------|----------|
-| Docs Site | `@usage-ui/www` | `apps/www/` |
-| Component Library | `@usage-ui/ui` | `packages/ui/` |
-
-### Key Commands
-
-```bash
-# Development
-pnpm run dev                              # Start all
-pnpm run dev --filter=@usage-ui/www       # Start docs only
-
-# Building
-pnpm run build                            # Build all
-pnpm run build --filter=@usage-ui/ui      # Build UI only
-
-# Quality
-pnpm run lint
-pnpm run typecheck
-
-# Dependencies
-pnpm add <pkg> --filter=@usage-ui/ui      # Add to UI
-pnpm add <pkg> --filter=@usage-ui/www     # Add to docs
-pnpm add -D <pkg> -w                      # Add to root
-```
-
-### File Locations After Migration
-
-| What | Where |
-|------|-------|
-| Your meter components | `packages/ui/src/components/registry/` |
-| Base shadcn components | `packages/ui/src/components/ui/` |
-| Shared utilities | `packages/ui/src/lib/` |
-| Shared hooks | `packages/ui/src/hooks/` |
-| Shared styles | `packages/ui/src/styles/` |
-| Component manifest | `packages/ui/registry.json` |
-| Docs site | `apps/www/` |
-| Site-specific components | `apps/www/src/components/` |
-
----
-
-*Last updated: January 2026*
-*Based on shadcn/ui monorepo support (December 2024), Turborepo v2 best practices, and Tailwind CSS v4*
diff --git a/apps/www/public/r/hero.json b/apps/www/public/r/hero.json
index 010e307..3e659c9 100644
--- a/apps/www/public/r/hero.json
+++ b/apps/www/public/r/hero.json
@@ -11,7 +11,7 @@
   "files": [
     {
       "path": "src/components/hero.tsx",
-      "content": "import Image from \"next/image\";\nimport Link from \"next/link\";\n\nimport { Badge } from \"@/components/ui/badge\";\nimport { Button } from \"@/components/ui/button\";\n\nexport function Hero({\n  title,\n  description,\n  buttonText,\n  buttonLink,\n  backgroundImage,\n}: {\n  title: string;\n  description: string;\n  buttonText: string;\n  buttonLink: string;\n  backgroundImage: string;\n}) {\n  return (\n    <div className=\"relative h-[600px] w-full bg-foreground/10\">\n      <div className=\"relative z-10 flex h-full flex-col items-center justify-center px-4 text-center sm:px-6 lg:px-8\">\n        <div className=\"mx-auto max-w-3xl\">\n          <Badge variant=\"secondary\" className=\"mb-4\">\n            Coming soon\n          </Badge>\n          <h1 className=\"font-semibold text-4xl tracking-tight text-balance sm:text-5xl md:text-6xl\">\n            {title}\n          </h1>\n          <p className=\"mt-6 text-xl text-muted-foreground leading-7\">{description}</p>\n          <div className=\"mt-10\">\n            <Button\n              asChild\n              variant=\"secondary\"\n              size=\"lg\"\n              className=\"rounded-md px-8\"\n            >\n              <Link href={buttonLink}>{buttonText}</Link>\n            </Button>\n          </div>\n        </div>\n      </div>\n    </div>\n  );\n}\n",
+      "content": "import Image from \"next/image\";\nimport Link from \"next/link\";\n\nimport { Badge } from \"@/components/ui/badge\";\nimport { Button } from \"@/components/ui/button\";\n\nexport function Hero({\n  title,\n  description,\n  buttonText,\n  buttonLink,\n  backgroundImage,\n}: {\n  title: string;\n  description: string;\n  buttonText: string;\n  buttonLink: string;\n  backgroundImage: string;\n}) {\n  return (\n    <div className=\"relative h-[600px] w-full bg-foreground/10\">\n      <div className=\"relative z-10 flex h-full flex-col items-center justify-center px-4 text-center sm:px-6 lg:px-8\">\n        <div className=\"mx-auto max-w-3xl\">\n          <Badge variant=\"secondary\" className=\"mb-4\">\n            Coming soon\n          </Badge>\n          <h1 className=\"text-balance font-semibold text-4xl tracking-tight sm:text-5xl md:text-6xl\">\n            {title}\n          </h1>\n          <p className=\"mt-6 text-muted-foreground text-xl leading-7\">\n            {description}\n          </p>\n          <div className=\"mt-10\">\n            <Button\n              asChild\n              variant=\"secondary\"\n              size=\"lg\"\n              className=\"rounded-md px-8\"\n            >\n              <Link href={buttonLink}>{buttonText}</Link>\n            </Button>\n          </div>\n        </div>\n      </div>\n    </div>\n  );\n}\n",
       "type": "registry:component"
     },
     {
diff --git a/apps/www/public/r/promo.json b/apps/www/public/r/promo.json
index c084c87..852a194 100644
--- a/apps/www/public/r/promo.json
+++ b/apps/www/public/r/promo.json
@@ -10,7 +10,7 @@
   "files": [
     {
       "path": "src/components/promo.tsx",
-      "content": "import Image from \"next/image\";\nimport Link from \"next/link\";\n\nimport { Button } from \"@/components/ui/button\";\n\nexport function Promo({\n  title,\n  description,\n  buttonText,\n  buttonLink,\n  backgroundImage,\n}: {\n  title: string;\n  description: string;\n  buttonText: string;\n  buttonLink: string;\n  backgroundImage: string;\n}) {\n  return (\n    <div className=\"relative h-[300px] w-full bg-foreground/10\">\n      <div className=\"relative z-10 flex h-full flex-col justify-center gap-3 px-8 py-3\">\n        <h1 className=\"font-semibold text-3xl tracking-tight text-balance md:text-4xl\">\n          {title}\n        </h1>\n        <p className=\"leading-7\">{description}</p>\n        <div>\n          <Button asChild size=\"lg\" className=\"rounded-md\">\n            <Link href={buttonLink}>{buttonText}</Link>\n          </Button>\n        </div>\n      </div>\n    </div>\n  );\n}\n",
+      "content": "import Image from \"next/image\";\nimport Link from \"next/link\";\n\nimport { Button } from \"@/components/ui/button\";\n\nexport function Promo({\n  title,\n  description,\n  buttonText,\n  buttonLink,\n  backgroundImage,\n}: {\n  title: string;\n  description: string;\n  buttonText: string;\n  buttonLink: string;\n  backgroundImage: string;\n}) {\n  return (\n    <div className=\"relative h-[300px] w-full bg-foreground/10\">\n      <div className=\"relative z-10 flex h-full flex-col justify-center gap-3 px-8 py-3\">\n        <h1 className=\"text-balance font-semibold text-3xl tracking-tight md:text-4xl\">\n          {title}\n        </h1>\n        <p className=\"leading-7\">{description}</p>\n        <div>\n          <Button asChild size=\"lg\" className=\"rounded-md\">\n            <Link href={buttonLink}>{buttonText}</Link>\n          </Button>\n        </div>\n      </div>\n    </div>\n  );\n}\n",
       "type": "registry:component"
     },
     {
diff --git a/apps/www/public/r/store.json b/apps/www/public/r/store.json
index cac6248..2e393d5 100644
--- a/apps/www/public/r/store.json
+++ b/apps/www/public/r/store.json
@@ -16,7 +16,7 @@
     },
     {
       "path": "src/app/demo/[name]/blocks/store-page.tsx",
-      "content": "import ProductGrid from \"@/components/product-grid\";\nimport { getCategories, getProducts } from \"@/lib/products\";\n\nexport default async function StorePage() {\n  const products = await getProducts();\n  const categories = await getCategories();\n\n  return (\n    <div className=\"flex min-h-screen flex-col\">\n      <main className=\"flex-1\">\n        <section className=\"py-12\">\n          <div className=\"container px-4 md:px-6\">\n            <div className=\"flex flex-col items-center justify-center space-y-4 text-center\">\n              <div className=\"space-y-2\">\n                <h1 className=\"font-semibold text-3xl tracking-tight text-balance sm:text-4xl md:text-5xl\">\n                  Welcome to Store\n                </h1>\n\n                <p className=\"mx-auto max-w-[700px] text-muted-foreground leading-7 md:text-xl\">\n                  Shop our unique collection of products. Free shipping on all\n                  orders!\n                </p>\n              </div>\n            </div>\n          </div>\n        </section>\n\n        <section className=\"py-8 md:py-12\">\n          <div className=\"container px-4 md:px-6\">\n            <ProductGrid products={products} categories={categories} />\n          </div>\n        </section>\n      </main>\n    </div>\n  );\n}\n",
+      "content": "import ProductGrid from \"@/components/product-grid\";\nimport { getCategories, getProducts } from \"@/lib/products\";\n\nexport default async function StorePage() {\n  const products = await getProducts();\n  const categories = await getCategories();\n\n  return (\n    <div className=\"flex min-h-screen flex-col\">\n      <main className=\"flex-1\">\n        <section className=\"py-12\">\n          <div className=\"container px-4 md:px-6\">\n            <div className=\"flex flex-col items-center justify-center space-y-4 text-center\">\n              <div className=\"space-y-2\">\n                <h1 className=\"text-balance font-semibold text-3xl tracking-tight sm:text-4xl md:text-5xl\">\n                  Welcome to Store\n                </h1>\n\n                <p className=\"mx-auto max-w-[700px] text-muted-foreground leading-7 md:text-xl\">\n                  Shop our unique collection of products. Free shipping on all\n                  orders!\n                </p>\n              </div>\n            </div>\n          </div>\n        </section>\n\n        <section className=\"py-8 md:py-12\">\n          <div className=\"container px-4 md:px-6\">\n            <ProductGrid products={products} categories={categories} />\n          </div>\n        </section>\n      </main>\n    </div>\n  );\n}\n",
       "type": "registry:page",
       "target": "app/page.tsx"
     }
diff --git a/apps/www/public/r/usage-meter-base.json b/apps/www/public/r/usage-meter-base.json
new file mode 100644
index 0000000..bc23dc0
--- /dev/null
+++ b/apps/www/public/r/usage-meter-base.json
@@ -0,0 +1,17 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "usage-meter-base",
+  "title": "Usage Meter (Base)",
+  "description": "A lightweight linear progress meter for displaying usage/quota information without Radix dependency.",
+  "dependencies": [],
+  "registryDependencies": [],
+  "files": [
+    {
+      "path": "src/components/registry/usage-meter/usage-meter-base.tsx",
+      "content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-[--meter-success]\",\n  warning: \"bg-[--meter-warning]\",\n  danger: \"bg-[--meter-danger]\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterBaseProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeterBase = React.forwardRef<HTMLDivElement, UsageMeterBaseProps>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    const percentage = Math.round((value / max) * 100);\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-base-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-base-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-base-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-base-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <div\n          ref={ref}\n          data-slot=\"usage-meter-base\"\n          role=\"progressbar\"\n          tabIndex={0}\n          aria-valuenow={value}\n          aria-valuemin={0}\n          aria-valuemax={max}\n          aria-valuetext={`${clampedPercentage}%`}\n          aria-label={label}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-[--meter-track]\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <div\n            data-slot=\"usage-meter-base-indicator\"\n            className={cn(\n              \"h-full transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ width: `${clampedPercentage}%` }}\n          />\n        </div>\n      </div>\n    );\n  },\n);\nUsageMeterBase.displayName = \"UsageMeterBase\";\n\nexport {\n  UsageMeterBase,\n  meterVariants as meterBaseVariants,\n  meterSizes as meterBaseSizes,\n};\nexport type { UsageMeterBaseProps };\n",
+      "type": "registry:component",
+      "target": "components/ui/usage-meter-base.tsx"
+    }
+  ],
+  "type": "registry:component"
+}
\ No newline at end of file
diff --git a/apps/www/public/r/usage-meter.json b/apps/www/public/r/usage-meter.json
new file mode 100644
index 0000000..2c666c1
--- /dev/null
+++ b/apps/www/public/r/usage-meter.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "usage-meter",
+  "title": "Usage Meter",
+  "description": "A linear progress meter for displaying usage/quota information with full Radix accessibility support.",
+  "dependencies": [
+    "radix-ui"
+  ],
+  "registryDependencies": [],
+  "files": [
+    {
+      "path": "src/components/registry/usage-meter/usage-meter.tsx",
+      "content": "\"use client\";\n\nimport { Progress as ProgressPrimitive } from \"radix-ui\";\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-[--meter-success]\",\n  warning: \"bg-[--meter-warning]\",\n  danger: \"bg-[--meter-danger]\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterProps\n  extends Omit<\n    React.ComponentProps<typeof ProgressPrimitive.Root>,\n    \"value\" | \"max\"\n  > {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeter = React.forwardRef<\n  React.ComponentRef<typeof ProgressPrimitive.Root>,\n  UsageMeterProps\n>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    const percentage = Math.round((value / max) * 100);\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <ProgressPrimitive.Root\n          ref={ref}\n          data-slot=\"usage-meter\"\n          value={value}\n          max={max}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-[--meter-track]\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <ProgressPrimitive.Indicator\n            data-slot=\"usage-meter-indicator\"\n            className={cn(\n              \"h-full w-full flex-1 transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ transform: `translateX(-${100 - clampedPercentage}%)` }}\n          />\n        </ProgressPrimitive.Root>\n      </div>\n    );\n  },\n);\nUsageMeter.displayName = \"UsageMeter\";\n\nexport { UsageMeter, meterVariants, meterSizes };\nexport type { UsageMeterProps };\n",
+      "type": "registry:component",
+      "target": "components/ui/usage-meter.tsx"
+    }
+  ],
+  "type": "registry:component"
+}
\ No newline at end of file
diff --git a/apps/www/src/components/registry/registry-logo.tsx b/apps/www/src/components/registry/registry-logo.tsx
index 2ff61d2..010fbea 100644
--- a/apps/www/src/components/registry/registry-logo.tsx
+++ b/apps/www/src/components/registry/registry-logo.tsx
@@ -6,7 +6,7 @@ export function RegistryLogo() {
       <div className="flex-shrink-0 rounded-md bg-primary p-1">
         <Squirrel className="size-5 text-secondary" />
       </div>
-      <span className="font-semibold">Registry</span>
+      <span className="text-xl font-medium tracking-tight">usage-ui</span>
     </>
   );
 }
diff --git a/packages/ui/registry.json b/packages/ui/registry.json
index 28ce598..ca02623 100644
--- a/packages/ui/registry.json
+++ b/packages/ui/registry.json
@@ -2,5 +2,36 @@
   "$schema": "https://ui.shadcn.com/schema/registry.json",
   "name": "usage-ui",
   "homepage": "https://usage-ui.vercel.app",
-  "items": []
+  "items": [
+    {
+      "name": "usage-meter",
+      "type": "registry:component",
+      "title": "Usage Meter",
+      "description": "A linear progress meter for displaying usage/quota information with full Radix accessibility support.",
+      "dependencies": ["radix-ui"],
+      "registryDependencies": [],
+      "files": [
+        {
+          "path": "src/components/registry/usage-meter/usage-meter.tsx",
+          "type": "registry:component",
+          "target": "components/ui/usage-meter.tsx"
+        }
+      ]
+    },
+    {
+      "name": "usage-meter-base",
+      "type": "registry:component",
+      "title": "Usage Meter (Base)",
+      "description": "A lightweight linear progress meter for displaying usage/quota information without Radix dependency.",
+      "dependencies": [],
+      "registryDependencies": [],
+      "files": [
+        {
+          "path": "src/components/registry/usage-meter/usage-meter-base.tsx",
+          "type": "registry:component",
+          "target": "components/ui/usage-meter-base.tsx"
+        }
+      ]
+    }
+  ]
 }
diff --git a/packages/ui/src/components/registry/index.ts b/packages/ui/src/components/registry/index.ts
index af6c27f..fbebfa3 100644
--- a/packages/ui/src/components/registry/index.ts
+++ b/packages/ui/src/components/registry/index.ts
@@ -1,5 +1,2 @@
-// Registry components will be exported here as they are created
-// Example: export * from "./usage-meter";
-
-// Placeholder export to ensure this is a valid module
-export {};
+// Registry components
+export * from "./usage-meter";
diff --git a/packages/ui/src/components/registry/usage-meter/index.ts b/packages/ui/src/components/registry/usage-meter/index.ts
new file mode 100644
index 0000000..87816e1
--- /dev/null
+++ b/packages/ui/src/components/registry/usage-meter/index.ts
@@ -0,0 +1,9 @@
+export { UsageMeter, meterVariants, meterSizes } from "./usage-meter";
+export type { UsageMeterProps } from "./usage-meter";
+
+export {
+  UsageMeterBase,
+  meterBaseVariants,
+  meterBaseSizes,
+} from "./usage-meter-base";
+export type { UsageMeterBaseProps } from "./usage-meter-base";
diff --git a/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx b/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
new file mode 100644
index 0000000..ae187e0
--- /dev/null
+++ b/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
@@ -0,0 +1,114 @@
+"use client";
+
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+const meterVariants = {
+  default: "bg-primary",
+  success: "bg-[--meter-success]",
+  warning: "bg-[--meter-warning]",
+  danger: "bg-[--meter-danger]",
+} as const;
+
+const meterSizes = {
+  sm: "h-2",
+  default: "h-3",
+  lg: "h-4",
+} as const;
+
+interface UsageMeterBaseProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Current value (required) */
+  value: number;
+  /** Maximum value (default: 100) */
+  max?: number;
+  /** Visual variant */
+  variant?: keyof typeof meterVariants;
+  /** Size variant */
+  size?: keyof typeof meterSizes;
+  /** Optional label text */
+  label?: string;
+  /** Show percentage (default: true) */
+  showPercentage?: boolean;
+}
+
+const UsageMeterBase = React.forwardRef<HTMLDivElement, UsageMeterBaseProps>(
+  (
+    {
+      className,
+      value,
+      max = 100,
+      variant = "default",
+      size = "default",
+      label,
+      showPercentage = true,
+      ...props
+    },
+    ref,
+  ) => {
+    const percentage = Math.round((value / max) * 100);
+    const clampedPercentage = Math.min(100, Math.max(0, percentage));
+
+    return (
+      <div data-slot="usage-meter-base-root" className="w-full">
+        {(label || showPercentage) && (
+          <div
+            data-slot="usage-meter-base-header"
+            className="mb-1.5 flex items-center justify-between text-sm"
+          >
+            {label && (
+              <span
+                data-slot="usage-meter-base-label"
+                className="font-medium text-foreground"
+              >
+                {label}
+              </span>
+            )}
+            {showPercentage && (
+              <span
+                data-slot="usage-meter-base-percentage"
+                className="text-muted-foreground tabular-nums"
+              >
+                {clampedPercentage}%
+              </span>
+            )}
+          </div>
+        )}
+        <div
+          ref={ref}
+          data-slot="usage-meter-base"
+          role="progressbar"
+          tabIndex={0}
+          aria-valuenow={value}
+          aria-valuemin={0}
+          aria-valuemax={max}
+          aria-valuetext={`${clampedPercentage}%`}
+          aria-label={label}
+          className={cn(
+            "relative w-full overflow-hidden rounded-full bg-[--meter-track]",
+            meterSizes[size],
+            className,
+          )}
+          {...props}
+        >
+          <div
+            data-slot="usage-meter-base-indicator"
+            className={cn(
+              "h-full transition-all duration-300 ease-in-out",
+              meterVariants[variant],
+            )}
+            style={{ width: `${clampedPercentage}%` }}
+          />
+        </div>
+      </div>
+    );
+  },
+);
+UsageMeterBase.displayName = "UsageMeterBase";
+
+export {
+  UsageMeterBase,
+  meterVariants as meterBaseVariants,
+  meterSizes as meterBaseSizes,
+};
+export type { UsageMeterBaseProps };
diff --git a/packages/ui/src/components/registry/usage-meter/usage-meter.tsx b/packages/ui/src/components/registry/usage-meter/usage-meter.tsx
new file mode 100644
index 0000000..77c628c
--- /dev/null
+++ b/packages/ui/src/components/registry/usage-meter/usage-meter.tsx
@@ -0,0 +1,113 @@
+"use client";
+
+import { Progress as ProgressPrimitive } from "radix-ui";
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+const meterVariants = {
+  default: "bg-primary",
+  success: "bg-[--meter-success]",
+  warning: "bg-[--meter-warning]",
+  danger: "bg-[--meter-danger]",
+} as const;
+
+const meterSizes = {
+  sm: "h-2",
+  default: "h-3",
+  lg: "h-4",
+} as const;
+
+interface UsageMeterProps
+  extends Omit<
+    React.ComponentProps<typeof ProgressPrimitive.Root>,
+    "value" | "max"
+  > {
+  /** Current value (required) */
+  value: number;
+  /** Maximum value (default: 100) */
+  max?: number;
+  /** Visual variant */
+  variant?: keyof typeof meterVariants;
+  /** Size variant */
+  size?: keyof typeof meterSizes;
+  /** Optional label text */
+  label?: string;
+  /** Show percentage (default: true) */
+  showPercentage?: boolean;
+}
+
+const UsageMeter = React.forwardRef<
+  React.ComponentRef<typeof ProgressPrimitive.Root>,
+  UsageMeterProps
+>(
+  (
+    {
+      className,
+      value,
+      max = 100,
+      variant = "default",
+      size = "default",
+      label,
+      showPercentage = true,
+      ...props
+    },
+    ref,
+  ) => {
+    const percentage = Math.round((value / max) * 100);
+    const clampedPercentage = Math.min(100, Math.max(0, percentage));
+
+    return (
+      <div data-slot="usage-meter-root" className="w-full">
+        {(label || showPercentage) && (
+          <div
+            data-slot="usage-meter-header"
+            className="mb-1.5 flex items-center justify-between text-sm"
+          >
+            {label && (
+              <span
+                data-slot="usage-meter-label"
+                className="font-medium text-foreground"
+              >
+                {label}
+              </span>
+            )}
+            {showPercentage && (
+              <span
+                data-slot="usage-meter-percentage"
+                className="text-muted-foreground tabular-nums"
+              >
+                {clampedPercentage}%
+              </span>
+            )}
+          </div>
+        )}
+        <ProgressPrimitive.Root
+          ref={ref}
+          data-slot="usage-meter"
+          value={value}
+          max={max}
+          className={cn(
+            "relative w-full overflow-hidden rounded-full bg-[--meter-track]",
+            meterSizes[size],
+            className,
+          )}
+          {...props}
+        >
+          <ProgressPrimitive.Indicator
+            data-slot="usage-meter-indicator"
+            className={cn(
+              "h-full w-full flex-1 transition-all duration-300 ease-in-out",
+              meterVariants[variant],
+            )}
+            style={{ transform: `translateX(-${100 - clampedPercentage}%)` }}
+          />
+        </ProgressPrimitive.Root>
+      </div>
+    );
+  },
+);
+UsageMeter.displayName = "UsageMeter";
+
+export { UsageMeter, meterVariants, meterSizes };
+export type { UsageMeterProps };

From 5dc9f69aaf988614a8c319023813d6a416a8f778 Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 17:29:57 -0500
Subject: [PATCH 03/10] feat(www): add MDX support and documentation components
 infrastructure

Set up foundation for component documentation pages with MDX, Shiki syntax
highlighting, and reusable documentation components including code previews,
API tables, installation tabs, and component navigation.
---
 .../005-component-documentation-strategy.md   | 176 +++++++++-
 .../006-documentation-route-strategy.md       | 109 ++++++
 .../implement-documentation-redesign.md       |  58 ++++
 apps/www/next.config.ts                       |  11 +-
 apps/www/package.json                         |   8 +-
 apps/www/public/r/theme.json                  |   2 +-
 apps/www/src/app/globals.css                  |  55 +++
 apps/www/src/components/docs/api-table.tsx    |  63 ++++
 .../components/docs/client-code-wrapper.tsx   |  53 +++
 .../www/src/components/docs/code-renderer.tsx |  31 ++
 .../docs/component-code-preview.tsx           |  70 ++++
 .../www/src/components/docs/component-nav.tsx |  53 +++
 apps/www/src/components/docs/index.ts         |   6 +
 .../src/components/docs/installation-tabs.tsx |  77 +++++
 .../src/components/registry/registry-logo.tsx |   2 +-
 apps/www/src/lib/code.ts                      |  81 +++++
 apps/www/src/lib/extract-props.ts             | 316 +++++++++++++++++
 apps/www/src/lib/shiki.ts                     |  82 +++++
 apps/www/src/mdx-components.tsx               |  87 +++++
 pnpm-lock.yaml                                | 327 ++++++++++++++++++
 20 files changed, 1656 insertions(+), 11 deletions(-)
 create mode 100644 .agents/context/decisions/006-documentation-route-strategy.md
 create mode 100644 apps/www/src/components/docs/api-table.tsx
 create mode 100644 apps/www/src/components/docs/client-code-wrapper.tsx
 create mode 100644 apps/www/src/components/docs/code-renderer.tsx
 create mode 100644 apps/www/src/components/docs/component-code-preview.tsx
 create mode 100644 apps/www/src/components/docs/component-nav.tsx
 create mode 100644 apps/www/src/components/docs/index.ts
 create mode 100644 apps/www/src/components/docs/installation-tabs.tsx
 create mode 100644 apps/www/src/lib/code.ts
 create mode 100644 apps/www/src/lib/extract-props.ts
 create mode 100644 apps/www/src/lib/shiki.ts
 create mode 100644 apps/www/src/mdx-components.tsx

diff --git a/.agents/context/decisions/005-component-documentation-strategy.md b/.agents/context/decisions/005-component-documentation-strategy.md
index fa2787d..137bb36 100644
--- a/.agents/context/decisions/005-component-documentation-strategy.md
+++ b/.agents/context/decisions/005-component-documentation-strategy.md
@@ -185,22 +185,186 @@ These add build complexity but ensure docs stay in sync with code.
 
 ---
 
+## Decision 5: Theme Synchronization for Direct Rendering
+
+### Selected: CSS Variable Inheritance (No Additional Providers Needed)
+
+**Approach:**
+- Direct rendering of UI components inherits theme automatically via CSS variables
+- No additional context providers or wrapper components required
+- Dark mode toggle updates `:root` CSS variables, which automatically propagate to all descendants
+
+```tsx
+// Direct rendering - theme inherits naturally
+<div className="flex min-h-[350px] items-center justify-center rounded-md border p-8">
+  <UsageMeter value={75} variant="warning" />
+</div>
+```
+
+### Rationale
+
+| Consideration | Analysis |
+|---------------|----------|
+| **CSS variable cascade** | Variables on `:root` cascade to all descendants automatically |
+| **shadcn theme toggle** | Updates CSS variables on document element, affecting all components |
+| **prompt-kit pattern** | Uses direct rendering with CSS variable inheritance |
+| **No extra bundle** | Avoids React context overhead |
+| **Dark mode** | `dark:` Tailwind utilities + CSS variables work seamlessly |
+
+### How It Works
+
+1. **Theme CSS Variables** defined in `globals.css`:
+```css
+:root {
+  --background: oklch(1 0 0);
+  --primary: oklch(0.205 0 0);
+  --meter-success: oklch(0.723 0.191 142.5);
+}
+.dark {
+  --background: oklch(0.145 0 0);
+  --primary: oklch(0.922 0 0);
+}
+```
+
+2. **Components use variables**:
+```tsx
+<div className="bg-background text-foreground">
+  <div className="bg-[--meter-success]" />
+</div>
+```
+
+3. **Theme toggle** updates document class:
+```tsx
+// next-themes handles this automatically
+document.documentElement.classList.toggle("dark");
+```
+
+### When Iframe Isolation is Needed
+
+For **blocks** (full-page layouts), use iframe rendering:
+- Blocks may have their own layout/styles that conflict with docs page
+- Iframe provides complete CSS isolation
+- Demo pages (`/demo/[name]`) load full theme context
+
+```tsx
+// For registry:block type
+<iframe src={`/demo/${name}`} className="h-[800px] w-full" />
+```
+
+### No Provider Wrappers Needed
+
+Unlike some theming solutions that require context providers, shadcn/ui's CSS variable approach means:
+- ✅ No `<ThemeProvider>` wrapper around previews
+- ✅ No `useTheme()` hook needed in preview components
+- ✅ Components are portable - they just read CSS variables
+
+---
+
+## Decision 6: Auto-Generated API Documentation
+
+### Selected: Build-Time TypeScript Extraction with react-docgen-typescript
+
+**Approach:**
+- Use `react-docgen-typescript` to extract props from TypeScript interfaces at build time
+- Generate structured JSON data for `ApiTable` component consumption
+- Supplement with JSDoc comments for descriptions
+- Run as part of the build pipeline, not at runtime
+
+### Implementation Strategy
+
+**Phase 1: Infrastructure (Immediate)**
+
+1. Install dependency:
+```bash
+pnpm add -D react-docgen-typescript --filter=@usage-ui/www
+```
+
+2. Create extraction utility at `apps/www/src/lib/extract-props.ts`
+
+3. Extract at build time using `generateStaticParams` or a prebuild script
+
+**Phase 2: Integration**
+
+```tsx
+// In docs/[slug]/page.tsx
+import { extractComponentProps } from "@/lib/extract-props"
+
+const props = await extractComponentProps("usage-meter")
+// Returns: [{ prop: "value", type: "number", required: true, description: "Current value" }, ...]
+
+<ApiTable data={props} />
+```
+
+### Rationale
+
+| Consideration | Analysis |
+|---------------|----------|
+| **Source of truth** | TypeScript interfaces are the canonical API definition |
+| **Maintenance** | Docs auto-update when interfaces change |
+| **JSDoc support** | Extracts `/** comments */` as descriptions |
+| **Industry precedent** | Used by Storybook, Docz, React Styleguidist |
+| **shadcn approach** | Manual tables, but their component count justifies it |
+| **Our scale** | Automation justified even with small component count |
+
+### Props Extraction Output Format
+
+```typescript
+interface PropInfo {
+  prop: string        // "value"
+  type: string        // "number"
+  default?: string    // "100"
+  required: boolean   // true
+  description?: string // "Current usage value"
+}
+```
+
+### JSDoc Convention for Components
+
+Document props with JSDoc comments:
+
+```typescript
+interface UsageMeterProps {
+  /** Current value (required) */
+  value: number
+  /** Maximum value (default: 100) */
+  max?: number
+  /** Visual variant */
+  variant?: "default" | "success" | "warning" | "danger"
+}
+```
+
+### Trade-offs vs Manual Tables
+
+| Manual Tables | Auto-Generated |
+|---------------|----------------|
+| ✅ Full prose control | ✅ Always in sync with code |
+| ❌ Can drift from code | ✅ Extracts JSDoc descriptions |
+| ✅ No build dependency | ❌ Adds build-time processing |
+| ❌ Duplicate maintenance | ✅ Single source of truth |
+
+**Decision**: Auto-generation is worth the build complexity for consistency and reduced maintenance.
+
+---
+
 ## Implementation Plan
 
 ### Phase 1: Infrastructure
 1. Add Shiki for syntax highlighting
 2. Create code extraction utility (`lib/code.ts`)
 3. Set up MDX loader and components
+4. **Add `extract-props.ts` for auto-generated API docs**
 
 ### Phase 2: Core Components
-4. Build `ComponentCodePreview` (Preview/Code tabs)
-5. Build `ApiTable` component
-6. Build `CodeRenderer` (Shiki wrapper)
+5. Build `ComponentCodePreview` (Preview/Code tabs)
+6. Build `ApiTable` component
+7. Build `CodeRenderer` (Shiki wrapper)
 
 ### Phase 3: Documentation
-7. Create MDX template for component docs
-8. Migrate existing component pages to MDX
-9. Add Previous/Next navigation
+8. Create `/docs/[slug]` route with new template
+9. Create documentation pages for components
+10. Add Previous/Next navigation
+11. **Update sidebar links to use `/docs/` routes**
+12. **Remove old `/registry/[name]` route**
 
 ---
 
diff --git a/.agents/context/decisions/006-documentation-route-strategy.md b/.agents/context/decisions/006-documentation-route-strategy.md
new file mode 100644
index 0000000..048b622
--- /dev/null
+++ b/.agents/context/decisions/006-documentation-route-strategy.md
@@ -0,0 +1,109 @@
+# ADR-006: Documentation Route Strategy
+
+## Status
+
+**Accepted** - January 2025
+
+## Context
+
+The documentation redesign (ADR-005) introduces new `/docs/[slug]` routes with enhanced MDX-based documentation. The project currently uses `/registry/[name]` routes for component pages. We need to decide on the URL structure for documentation pages.
+
+### Current State Analysis
+
+**Existing routes:**
+- `/registry/[name]` - Component detail pages (e.g., `/registry/usage-meter`)
+- Internal links from sidebar, home page, and "About" section use `/registry/[name]`
+- `public/r/[name].json` files serve the shadcn CLI (separate from page routes)
+
+**Project status:**
+- New project, not yet publicly launched
+- `X-Robots-Tag: noindex` header prevents indexing
+- No external links to preserve
+- No backward compatibility requirements
+
+---
+
+## Decision
+
+### Selected: Direct replacement (no redirects needed)
+
+**Approach:**
+1. Create new `/docs/[slug]` routes as the documentation pages
+2. Remove the `/registry/[name]` route entirely
+3. Update all internal links to use `/docs/[name]`
+
+Since this is a new project with no external dependencies on the current URLs, there's no need for a transitional redirect period.
+
+### Implementation
+
+**Step 1: Create new docs route**
+
+Create `apps/www/src/app/docs/[slug]/page.tsx` with the new documentation template.
+
+**Step 2: Update internal links**
+
+Update all internal links to use `/docs/[name]`:
+
+1. `registry-sidebar.tsx`:
+   - Change `href={"/registry/${item.name}"}` → `href={"/docs/${item.name}"}`
+
+2. Home page `page.tsx`:
+   - Change `href={"/registry/${item.name}"}` → `href={"/docs/${item.name}"}`
+   - Change `href="/registry/blank"` → `href="/docs/blank"`
+
+**Step 3: Remove old route**
+
+Delete `apps/www/src/app/(registry)/registry/[name]/page.tsx` once the new route is working.
+
+---
+
+## Rationale
+
+### Why direct replacement?
+
+| Factor | Analysis |
+|--------|----------|
+| **New project** | No external links or bookmarks to preserve |
+| **Simplicity** | No redirect configuration needed |
+| **Clean codebase** | Single route, no transitional code |
+| **shadcn alignment** | shadcn/ui uses `/docs/components/[name]` pattern |
+
+### Why `/docs/` over `/registry/`?
+
+- Industry standard for documentation sites
+- Clearer intent - these are documentation pages, not registry endpoints
+- Registry JSON files live at `/r/[name].json` (different concern)
+
+---
+
+## Consequences
+
+### Positive
+
+- Clean URL structure aligned with industry standards (`/docs/`)
+- Single documentation source, no maintenance overhead
+- No redirect configuration complexity
+- Immediate clean slate
+
+### Neutral
+
+- Registry JSON files (`/r/[name].json`) are unaffected (separate concern)
+- Demo routes (`/demo/[name]`) remain unchanged
+
+---
+
+## Implementation Checklist
+
+- [ ] Create `/docs/[slug]/page.tsx` with new documentation template
+- [ ] Create `/docs/layout.tsx` for docs layout
+- [ ] Update `registry-sidebar.tsx` to use `/docs/` links
+- [ ] Update home `page.tsx` to use `/docs/` links
+- [ ] Delete `/registry/[name]/page.tsx`
+- [ ] Verify all links work correctly
+
+---
+
+## References
+
+- [ADR-005: Component Documentation and Preview Strategy](./005-component-documentation-strategy.md)
+- [shadcn/ui URL structure](https://ui.shadcn.com/docs/components)
diff --git a/.agents/workflows/implement-documentation-redesign.md b/.agents/workflows/implement-documentation-redesign.md
index 6f721a3..c8a9cd4 100644
--- a/.agents/workflows/implement-documentation-redesign.md
+++ b/.agents/workflows/implement-documentation-redesign.md
@@ -216,6 +216,64 @@ export function useMDXComponents(components: MDXComponents): MDXComponents {
 }
 ```
 
+### 1.6 Create Props Extraction Utility
+
+**Create:** `apps/www/src/lib/extract-props.ts`
+
+This utility extracts TypeScript interface definitions and JSDoc comments from component files for auto-generated API documentation.
+
+```typescript
+import fs from "node:fs"
+import path from "node:path"
+import { cache } from "react"
+
+export interface PropInfo {
+  prop: string
+  type: string
+  default?: string
+  required: boolean
+  description?: string
+}
+
+export interface ComponentDoc {
+  displayName: string
+  description?: string
+  props: PropInfo[]
+}
+
+/**
+ * Extract props for a registry component by name.
+ */
+export const getComponentProps = cache((componentName: string): ComponentDoc[] => {
+  // Implementation reads from packages/ui/registry.json
+  // then parses the TypeScript file for interface definitions
+  // See full implementation in apps/www/src/lib/extract-props.ts
+})
+
+/**
+ * Convert PropInfo to ApiTable-compatible format.
+ */
+export function formatPropsForApiTable(props: PropInfo[]) {
+  return props.map((p) => ({
+    prop: p.prop,
+    type: p.type,
+    default: p.required ? "Required" : p.default || "—",
+    description: p.description,
+  }))
+}
+```
+
+**JSDoc Convention:** Document component props with JSDoc comments:
+
+```typescript
+interface UsageMeterProps {
+  /** Current value (required) */
+  value: number
+  /** Maximum value (default: 100) */
+  max?: number
+}
+```
+
 ### Validation Steps
 
 ```bash
diff --git a/apps/www/next.config.ts b/apps/www/next.config.ts
index c1714c7..467bc4f 100644
--- a/apps/www/next.config.ts
+++ b/apps/www/next.config.ts
@@ -1,6 +1,8 @@
+import createMDX from "@next/mdx";
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
+  pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
   async headers() {
     return [
       {
@@ -16,4 +18,11 @@ const nextConfig: NextConfig = {
   },
 };
 
-export default nextConfig;
+const withMDX = createMDX({
+  options: {
+    remarkPlugins: [],
+    rehypePlugins: [],
+  },
+});
+
+export default withMDX(nextConfig);
diff --git a/apps/www/package.json b/apps/www/package.json
index 056549d..bba9bd5 100644
--- a/apps/www/package.json
+++ b/apps/www/package.json
@@ -11,9 +11,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@usage-ui/ui": "workspace:*",
     "@hookform/resolvers": "^5.2.2",
+    "@mdx-js/loader": "^3.1.1",
+    "@mdx-js/react": "^3.1.1",
+    "@next/mdx": "^16.1.6",
     "@tanstack/react-table": "^8.21.3",
+    "@usage-ui/ui": "workspace:*",
     "@vercel/analytics": "^1.6.1",
     "@vercel/speed-insights": "^1.3.1",
     "class-variance-authority": "^0.7.1",
@@ -32,18 +35,19 @@
     "react-hook-form": "^7.68.0",
     "react-resizable-panels": "^3.0.6",
     "recharts": "^2.15.4",
+    "shiki": "^3.21.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.4.0",
     "vaul": "^1.1.2",
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "shadcn": "3.7.0",
     "@tailwindcss/postcss": "^4.1.18",
     "@types/node": "^22.19.3",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "postcss": "^8.5.6",
+    "shadcn": "3.7.0",
     "tailwindcss": "^4.1.18",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.4.5"
diff --git a/apps/www/public/r/theme.json b/apps/www/public/r/theme.json
index c46a365..4fd64ce 100644
--- a/apps/www/public/r/theme.json
+++ b/apps/www/public/r/theme.json
@@ -9,7 +9,7 @@
   "files": [
     {
       "path": "src/app/globals.css",
-      "content": "@import \"tailwindcss\";\n@import \"tw-animate-css\";\n\n@custom-variant dark (&:is(.dark *));\n\n:root {\n  --radius: 0.625rem;\n  --background: oklch(1 0 0);\n  --foreground: oklch(0.145 0 0);\n\n  --card: oklch(1 0 0);\n  --card-foreground: oklch(0.145 0 0);\n\n  --popover: oklch(1 0 0);\n  --popover-foreground: oklch(0.145 0 0);\n\n  --primary: oklch(0.205 0 0);\n  --primary-foreground: oklch(0.985 0 0);\n\n  --secondary: oklch(0.97 0 0);\n  --secondary-foreground: oklch(0.205 0 0);\n\n  --muted: oklch(0.97 0 0);\n  --muted-foreground: oklch(0.556 0 0);\n\n  --accent: oklch(0.97 0 0);\n  --accent-foreground: oklch(0.205 0 0);\n\n  --destructive: oklch(0.577 0.245 27.325);\n  --destructive-foreground: oklch(0.985 0 0);\n\n  --border: oklch(0.922 0 0);\n  --input: oklch(0.922 0 0);\n  --ring: oklch(0.708 0 0);\n\n  --chart-1: oklch(0.646 0.222 41.116);\n  --chart-2: oklch(0.6 0.118 184.704);\n  --chart-3: oklch(0.398 0.07 227.392);\n  --chart-4: oklch(0.828 0.189 84.429);\n  --chart-5: oklch(0.769 0.188 70.08);\n\n  --sidebar: oklch(0.985 0 0);\n  --sidebar-foreground: oklch(0.145 0 0);\n  --sidebar-primary: oklch(0.205 0 0);\n  --sidebar-primary-foreground: oklch(0.985 0 0);\n  --sidebar-accent: oklch(0.97 0 0);\n  --sidebar-accent-foreground: oklch(0.205 0 0);\n  --sidebar-border: oklch(0.922 0 0);\n  --sidebar-ring: oklch(0.708 0 0);\n}\n\n.dark {\n  --background: oklch(0.145 0 0);\n  --foreground: oklch(0.985 0 0);\n\n  --card: oklch(0.205 0 0);\n  --card-foreground: oklch(0.985 0 0);\n\n  --popover: oklch(0.205 0 0);\n  --popover-foreground: oklch(0.985 0 0);\n\n  --primary: oklch(0.922 0 0);\n  --primary-foreground: oklch(0.205 0 0);\n\n  --secondary: oklch(0.269 0 0);\n  --secondary-foreground: oklch(0.985 0 0);\n\n  --muted: oklch(0.269 0 0);\n  --muted-foreground: oklch(0.708 0 0);\n\n  --accent: oklch(0.269 0 0);\n  --accent-foreground: oklch(0.985 0 0);\n\n  --destructive: oklch(0.704 0.191 22.216);\n  --destructive-foreground: oklch(0.985 0 0);\n\n  --border: oklch(1 0 0 / 10%);\n  --input: oklch(1 0 0 / 15%);\n  --ring: oklch(0.556 0 0);\n\n  --chart-1: oklch(0.488 0.243 264.376);\n  --chart-2: oklch(0.696 0.17 162.48);\n  --chart-3: oklch(0.769 0.188 70.08);\n  --chart-4: oklch(0.627 0.265 303.9);\n  --chart-5: oklch(0.645 0.246 16.439);\n\n  --sidebar: oklch(0.205 0 0);\n  --sidebar-foreground: oklch(0.985 0 0);\n  --sidebar-primary: oklch(0.488 0.243 264.376);\n  --sidebar-primary-foreground: oklch(0.985 0 0);\n  --sidebar-accent: oklch(0.269 0 0);\n  --sidebar-accent-foreground: oklch(0.985 0 0);\n  --sidebar-border: oklch(1 0 0 / 10%);\n  --sidebar-ring: oklch(0.556 0 0);\n}\n\n@theme inline {\n  --color-background: var(--background);\n  --color-foreground: var(--foreground);\n\n  --color-primary: var(--primary);\n  --color-primary-foreground: var(--primary-foreground);\n\n  --color-secondary: var(--secondary);\n  --color-secondary-foreground: var(--secondary-foreground);\n  --color-accent: var(--accent);\n  --color-accent-foreground: var(--accent-foreground);\n\n  --color-muted: var(--muted);\n  --color-muted-foreground: var(--muted-foreground);\n  --color-card: var(--card);\n  --color-card-foreground: var(--card-foreground);\n  --color-popover: var(--popover);\n  --color-popover-foreground: var(--popover-foreground);\n\n  --color-border: var(--border);\n  --color-input: var(--input);\n  --color-ring: var(--ring);\n\n  --color-destructive: var(--destructive);\n  --color-destructive-foreground: var(--destructive-foreground);\n\n  --color-chart-1: var(--chart-1);\n  --color-chart-2: var(--chart-2);\n  --color-chart-3: var(--chart-3);\n  --color-chart-4: var(--chart-4);\n  --color-chart-5: var(--chart-5);\n\n  --color-sidebar: var(--sidebar);\n  --color-sidebar-foreground: var(--sidebar-foreground);\n  --color-sidebar-primary: var(--sidebar-primary);\n  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);\n  --color-sidebar-accent: var(--sidebar-accent);\n  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);\n  --color-sidebar-border: var(--sidebar-border);\n  --color-sidebar-ring: var(--sidebar-ring);\n\n  --font-sans: var(--font-sans);\n  --font-inter: var(--font-inter);\n  --font-mono: var(--font-mono);\n\n  --radius-sm: calc(var(--radius) - 4px);\n  --radius-md: calc(var(--radius) - 2px);\n  --radius-lg: var(--radius);\n  --radius-xl: calc(var(--radius) + 4px);\n\n  --shadow-2xs: var(--shadow-2xs);\n  --shadow-xs: var(--shadow-xs);\n  --shadow-sm: var(--shadow-sm);\n  --shadow: var(--shadow);\n  --shadow-md: var(--shadow-md);\n  --shadow-lg: var(--shadow-lg);\n  --shadow-xl: var(--shadow-xl);\n  --shadow-2xl: var(--shadow-2xl);\n}\n\n@layer base {\n  *,\n  ::after,\n  ::before,\n  ::backdrop,\n  ::file-selector-button {\n    border-color: var(--color-border, currentColor);\n  }\n\n  body {\n    font-family: var(--font-sans);\n    font-synthesis-weight: none;\n    text-rendering: optimizeLegibility;\n    -webkit-font-smoothing: antialiased;\n    -moz-osx-font-smoothing: grayscale;\n  }\n}\n",
+      "content": "@import \"tailwindcss\";\n@import \"tw-animate-css\";\n\n@custom-variant dark (&:is(.dark *));\n\n:root {\n  --radius: 0.625rem;\n  --background: oklch(1 0 0);\n  --foreground: oklch(0.145 0 0);\n\n  --card: oklch(1 0 0);\n  --card-foreground: oklch(0.145 0 0);\n\n  --popover: oklch(1 0 0);\n  --popover-foreground: oklch(0.145 0 0);\n\n  --primary: oklch(0.205 0 0);\n  --primary-foreground: oklch(0.985 0 0);\n\n  --secondary: oklch(0.97 0 0);\n  --secondary-foreground: oklch(0.205 0 0);\n\n  --muted: oklch(0.97 0 0);\n  --muted-foreground: oklch(0.556 0 0);\n\n  --accent: oklch(0.97 0 0);\n  --accent-foreground: oklch(0.205 0 0);\n\n  --destructive: oklch(0.577 0.245 27.325);\n  --destructive-foreground: oklch(0.985 0 0);\n\n  --border: oklch(0.922 0 0);\n  --input: oklch(0.922 0 0);\n  --ring: oklch(0.708 0 0);\n\n  --chart-1: oklch(0.646 0.222 41.116);\n  --chart-2: oklch(0.6 0.118 184.704);\n  --chart-3: oklch(0.398 0.07 227.392);\n  --chart-4: oklch(0.828 0.189 84.429);\n  --chart-5: oklch(0.769 0.188 70.08);\n\n  --sidebar: oklch(0.985 0 0);\n  --sidebar-foreground: oklch(0.145 0 0);\n  --sidebar-primary: oklch(0.205 0 0);\n  --sidebar-primary-foreground: oklch(0.985 0 0);\n  --sidebar-accent: oklch(0.97 0 0);\n  --sidebar-accent-foreground: oklch(0.205 0 0);\n  --sidebar-border: oklch(0.922 0 0);\n  --sidebar-ring: oklch(0.708 0 0);\n}\n\n.dark {\n  --background: oklch(0.145 0 0);\n  --foreground: oklch(0.985 0 0);\n\n  --card: oklch(0.205 0 0);\n  --card-foreground: oklch(0.985 0 0);\n\n  --popover: oklch(0.205 0 0);\n  --popover-foreground: oklch(0.985 0 0);\n\n  --primary: oklch(0.922 0 0);\n  --primary-foreground: oklch(0.205 0 0);\n\n  --secondary: oklch(0.269 0 0);\n  --secondary-foreground: oklch(0.985 0 0);\n\n  --muted: oklch(0.269 0 0);\n  --muted-foreground: oklch(0.708 0 0);\n\n  --accent: oklch(0.269 0 0);\n  --accent-foreground: oklch(0.985 0 0);\n\n  --destructive: oklch(0.704 0.191 22.216);\n  --destructive-foreground: oklch(0.985 0 0);\n\n  --border: oklch(1 0 0 / 10%);\n  --input: oklch(1 0 0 / 15%);\n  --ring: oklch(0.556 0 0);\n\n  --chart-1: oklch(0.488 0.243 264.376);\n  --chart-2: oklch(0.696 0.17 162.48);\n  --chart-3: oklch(0.769 0.188 70.08);\n  --chart-4: oklch(0.627 0.265 303.9);\n  --chart-5: oklch(0.645 0.246 16.439);\n\n  --sidebar: oklch(0.205 0 0);\n  --sidebar-foreground: oklch(0.985 0 0);\n  --sidebar-primary: oklch(0.488 0.243 264.376);\n  --sidebar-primary-foreground: oklch(0.985 0 0);\n  --sidebar-accent: oklch(0.269 0 0);\n  --sidebar-accent-foreground: oklch(0.985 0 0);\n  --sidebar-border: oklch(1 0 0 / 10%);\n  --sidebar-ring: oklch(0.556 0 0);\n}\n\n@theme inline {\n  --color-background: var(--background);\n  --color-foreground: var(--foreground);\n\n  --color-primary: var(--primary);\n  --color-primary-foreground: var(--primary-foreground);\n\n  --color-secondary: var(--secondary);\n  --color-secondary-foreground: var(--secondary-foreground);\n  --color-accent: var(--accent);\n  --color-accent-foreground: var(--accent-foreground);\n\n  --color-muted: var(--muted);\n  --color-muted-foreground: var(--muted-foreground);\n  --color-card: var(--card);\n  --color-card-foreground: var(--card-foreground);\n  --color-popover: var(--popover);\n  --color-popover-foreground: var(--popover-foreground);\n\n  --color-border: var(--border);\n  --color-input: var(--input);\n  --color-ring: var(--ring);\n\n  --color-destructive: var(--destructive);\n  --color-destructive-foreground: var(--destructive-foreground);\n\n  --color-chart-1: var(--chart-1);\n  --color-chart-2: var(--chart-2);\n  --color-chart-3: var(--chart-3);\n  --color-chart-4: var(--chart-4);\n  --color-chart-5: var(--chart-5);\n\n  --color-sidebar: var(--sidebar);\n  --color-sidebar-foreground: var(--sidebar-foreground);\n  --color-sidebar-primary: var(--sidebar-primary);\n  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);\n  --color-sidebar-accent: var(--sidebar-accent);\n  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);\n  --color-sidebar-border: var(--sidebar-border);\n  --color-sidebar-ring: var(--sidebar-ring);\n\n  --font-sans: var(--font-sans);\n  --font-inter: var(--font-inter);\n  --font-mono: var(--font-mono);\n\n  --radius-sm: calc(var(--radius) - 4px);\n  --radius-md: calc(var(--radius) - 2px);\n  --radius-lg: var(--radius);\n  --radius-xl: calc(var(--radius) + 4px);\n\n  --shadow-2xs: var(--shadow-2xs);\n  --shadow-xs: var(--shadow-xs);\n  --shadow-sm: var(--shadow-sm);\n  --shadow: var(--shadow);\n  --shadow-md: var(--shadow-md);\n  --shadow-lg: var(--shadow-lg);\n  --shadow-xl: var(--shadow-xl);\n  --shadow-2xl: var(--shadow-2xl);\n}\n\n@layer base {\n  *,\n  ::after,\n  ::before,\n  ::backdrop,\n  ::file-selector-button {\n    border-color: var(--color-border, currentColor);\n  }\n\n  body {\n    font-family: var(--font-sans);\n    font-synthesis-weight: none;\n    text-rendering: optimizeLegibility;\n    -webkit-font-smoothing: antialiased;\n    -moz-osx-font-smoothing: grayscale;\n  }\n}\n\n/* Documentation Prose Typography */\n@layer components {\n  .prose-docs {\n    /* Headings */\n    & h1 {\n      @apply scroll-m-20 text-3xl font-semibold tracking-tight;\n    }\n\n    & h2 {\n      @apply mt-12 scroll-m-20 border-b pb-2 text-xl font-medium tracking-tight first:mt-0;\n    }\n\n    & h3 {\n      @apply mt-8 scroll-m-20 text-lg font-medium tracking-tight;\n    }\n\n    /* Content */\n    & p {\n      @apply leading-7 [&:not(:first-child)]:mt-6;\n    }\n\n    & strong {\n      @apply font-medium;\n    }\n\n    & code:not(pre code) {\n      @apply rounded bg-muted px-1 py-0.5 text-sm before:content-none after:content-none;\n    }\n\n    /* Tables */\n    & table {\n      @apply block overflow-y-auto;\n    }\n\n    /* Images */\n    & img {\n      @apply m-0 rounded-md;\n    }\n\n    /* Lists */\n    & ul {\n      @apply my-6 ml-6 list-disc [&>li]:mt-2;\n    }\n\n    & ol {\n      @apply my-6 ml-6 list-decimal [&>li]:mt-2;\n    }\n\n    /* Links */\n    & a {\n      @apply font-medium text-foreground underline underline-offset-4;\n    }\n  }\n}\n",
       "type": "registry:style",
       "target": "app/globals.css"
     },
diff --git a/apps/www/src/app/globals.css b/apps/www/src/app/globals.css
index d8888b1..1b8fc81 100644
--- a/apps/www/src/app/globals.css
+++ b/apps/www/src/app/globals.css
@@ -171,3 +171,58 @@
     -moz-osx-font-smoothing: grayscale;
   }
 }
+
+/* Documentation Prose Typography */
+@layer components {
+  .prose-docs {
+    /* Headings */
+    & h1 {
+      @apply scroll-m-20 text-3xl font-semibold tracking-tight;
+    }
+
+    & h2 {
+      @apply mt-12 scroll-m-20 border-b pb-2 text-xl font-medium tracking-tight first:mt-0;
+    }
+
+    & h3 {
+      @apply mt-8 scroll-m-20 text-lg font-medium tracking-tight;
+    }
+
+    /* Content */
+    & p {
+      @apply leading-7 [&:not(:first-child)]:mt-6;
+    }
+
+    & strong {
+      @apply font-medium;
+    }
+
+    & code:not(pre code) {
+      @apply rounded bg-muted px-1 py-0.5 text-sm before:content-none after:content-none;
+    }
+
+    /* Tables */
+    & table {
+      @apply block overflow-y-auto;
+    }
+
+    /* Images */
+    & img {
+      @apply m-0 rounded-md;
+    }
+
+    /* Lists */
+    & ul {
+      @apply my-6 ml-6 list-disc [&>li]:mt-2;
+    }
+
+    & ol {
+      @apply my-6 ml-6 list-decimal [&>li]:mt-2;
+    }
+
+    /* Links */
+    & a {
+      @apply font-medium text-foreground underline underline-offset-4;
+    }
+  }
+}
diff --git a/apps/www/src/components/docs/api-table.tsx b/apps/www/src/components/docs/api-table.tsx
new file mode 100644
index 0000000..37a4bca
--- /dev/null
+++ b/apps/www/src/components/docs/api-table.tsx
@@ -0,0 +1,63 @@
+import { cn } from "@/lib/utils";
+
+interface ApiTableProps {
+  data: Array<{
+    prop: string;
+    type: string;
+    default?: string;
+    description?: string;
+  }>;
+  className?: string;
+}
+
+export function ApiTable({ data, className }: ApiTableProps) {
+  return (
+    <div
+      className={cn(
+        "not-prose relative w-full overflow-auto rounded-lg border text-sm",
+        className,
+      )}
+    >
+      <table className="w-full">
+        <thead className="bg-secondary text-foreground">
+          <tr className="h-10">
+            <th className="px-4 pb-0 text-left align-middle font-[450]">
+              Prop
+            </th>
+            <th className="px-4 pb-0 text-left align-middle font-[450]">
+              Type
+            </th>
+            <th className="px-4 pb-0 text-left align-middle font-[450]">
+              Default
+            </th>
+            {data.some((row) => row.description) && (
+              <th className="px-4 pb-0 text-left align-middle font-[450]">
+                Description
+              </th>
+            )}
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-border">
+          {data.map((row) => (
+            <tr key={row.prop} className="h-10">
+              <td className="px-4 py-2 text-left align-middle font-mono text-sm">
+                {row.prop}
+              </td>
+              <td className="px-4 py-2 text-left align-middle font-mono text-muted-foreground text-sm">
+                {row.type}
+              </td>
+              <td className="px-4 py-2 text-left align-middle font-mono text-sm">
+                {row.default || "—"}
+              </td>
+              {data.some((r) => r.description) && (
+                <td className="px-4 py-2 text-left align-middle">
+                  {row.description}
+                </td>
+              )}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
diff --git a/apps/www/src/components/docs/client-code-wrapper.tsx b/apps/www/src/components/docs/client-code-wrapper.tsx
new file mode 100644
index 0000000..3d6f747
--- /dev/null
+++ b/apps/www/src/components/docs/client-code-wrapper.tsx
@@ -0,0 +1,53 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import { Check, Copy } from "lucide-react";
+import * as React from "react";
+
+interface ClientCodeWrapperProps {
+  code: string;
+  children: React.ReactNode;
+  className?: string;
+}
+
+export function ClientCodeWrapper({
+  code,
+  children,
+  className,
+}: ClientCodeWrapperProps) {
+  const [copied, setCopied] = React.useState(false);
+
+  const copyToClipboard = async () => {
+    await navigator.clipboard.writeText(code);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <div className={cn("group relative", className)}>
+      <Button
+        variant="ghost"
+        size="icon"
+        className="absolute top-3 right-3 h-8 w-8 opacity-0 transition-opacity group-hover:opacity-100"
+        onClick={copyToClipboard}
+      >
+        <div className="relative h-4 w-4">
+          <Copy
+            className={cn(
+              "absolute inset-0 h-4 w-4 transition-all duration-300",
+              copied ? "scale-0 opacity-0" : "scale-100 opacity-100",
+            )}
+          />
+          <Check
+            className={cn(
+              "absolute inset-0 h-4 w-4 text-green-500 transition-all duration-300",
+              copied ? "scale-100 opacity-100" : "scale-0 opacity-0",
+            )}
+          />
+        </div>
+      </Button>
+      {children}
+    </div>
+  );
+}
diff --git a/apps/www/src/components/docs/code-renderer.tsx b/apps/www/src/components/docs/code-renderer.tsx
new file mode 100644
index 0000000..8d7ce89
--- /dev/null
+++ b/apps/www/src/components/docs/code-renderer.tsx
@@ -0,0 +1,31 @@
+import { highlightCode } from "@/lib/shiki";
+import { cn } from "@/lib/utils";
+import type { BundledLanguage } from "shiki";
+
+interface CodeRendererProps {
+  code: string;
+  lang?: BundledLanguage;
+  className?: string;
+}
+
+export async function CodeRenderer({
+  code,
+  lang = "tsx",
+  className,
+}: CodeRendererProps) {
+  const html = await highlightCode(code, lang);
+
+  return (
+    <div
+      className={cn(
+        "not-prose overflow-auto rounded-md border bg-background p-4 text-[13px]",
+        // Theme-aware styling for Shiki output
+        "[&_pre]:!bg-transparent [&_code]:!bg-transparent",
+        "dark:[&_span]:!text-[var(--shiki-dark)]",
+        className,
+      )}
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: Shiki returns safe pre-rendered HTML
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  );
+}
diff --git a/apps/www/src/components/docs/component-code-preview.tsx b/apps/www/src/components/docs/component-code-preview.tsx
new file mode 100644
index 0000000..25c2757
--- /dev/null
+++ b/apps/www/src/components/docs/component-code-preview.tsx
@@ -0,0 +1,70 @@
+import { cn } from "@/lib/utils";
+import { Tabs } from "radix-ui";
+import { ClientCodeWrapper } from "./client-code-wrapper";
+import { CodeRenderer } from "./code-renderer";
+
+interface ComponentCodePreviewProps {
+  name: string;
+  code: string;
+  children: React.ReactNode;
+  className?: string;
+}
+
+export function ComponentCodePreview({
+  name,
+  code,
+  children,
+  className,
+}: ComponentCodePreviewProps) {
+  return (
+    <Tabs.Root defaultValue="preview" className={cn("w-full", className)}>
+      <Tabs.List className="inline-flex h-10 w-full items-center justify-start border-b">
+        <Tabs.Trigger
+          value="preview"
+          className={cn(
+            "relative inline-flex h-10 items-center justify-center px-4 py-1 pt-2 pb-3",
+            "font-medium text-muted-foreground text-sm",
+            "data-[state=active]:text-foreground",
+            "transition-none focus-visible:outline-none",
+          )}
+        >
+          <TabIndicator />
+          Preview
+        </Tabs.Trigger>
+        <Tabs.Trigger
+          value="code"
+          className={cn(
+            "relative inline-flex h-10 items-center justify-center px-4 py-1 pt-2 pb-3",
+            "font-medium text-muted-foreground text-sm",
+            "data-[state=active]:text-foreground",
+            "transition-none focus-visible:outline-none",
+          )}
+        >
+          <TabIndicator />
+          Code
+        </Tabs.Trigger>
+      </Tabs.List>
+
+      <Tabs.Content value="preview" className="mt-4">
+        <div className="flex min-h-[350px] w-full items-center justify-center rounded-md border p-8">
+          <div className="w-full max-w-3xl">{children}</div>
+        </div>
+      </Tabs.Content>
+
+      <Tabs.Content value="code" className="mt-4">
+        <ClientCodeWrapper code={code}>
+          <CodeRenderer code={code} />
+        </ClientCodeWrapper>
+      </Tabs.Content>
+    </Tabs.Root>
+  );
+}
+
+// Animated underline indicator for active tab
+function TabIndicator() {
+  return (
+    <div className="absolute bottom-0 flex h-0.5 w-full justify-center opacity-0 transition-opacity data-[state=active]:opacity-100">
+      <div className="h-0.5 w-4/5 bg-foreground" />
+    </div>
+  );
+}
diff --git a/apps/www/src/components/docs/component-nav.tsx b/apps/www/src/components/docs/component-nav.tsx
new file mode 100644
index 0000000..c951033
--- /dev/null
+++ b/apps/www/src/components/docs/component-nav.tsx
@@ -0,0 +1,53 @@
+import { getRegistryItems } from "@/lib/registry";
+import { cn } from "@/lib/utils";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import Link from "next/link";
+
+interface ComponentNavProps {
+  currentName: string;
+  className?: string;
+}
+
+export function ComponentNav({ currentName, className }: ComponentNavProps) {
+  const items = getRegistryItems();
+  const currentIndex = items.findIndex((item) => item.name === currentName);
+
+  const prev = currentIndex > 0 ? items[currentIndex - 1] : null;
+  const next = currentIndex < items.length - 1 ? items[currentIndex + 1] : null;
+
+  return (
+    <div className={cn("flex justify-between pt-12 pb-20", className)}>
+      {prev ? (
+        <Link
+          href={`/docs/${prev.name}`}
+          className={cn(
+            "inline-flex items-center gap-1 rounded-md border px-3 py-1.5",
+            "text-muted-foreground text-sm transition-colors",
+            "hover:bg-muted hover:text-foreground",
+          )}
+        >
+          <ChevronLeft className="h-4 w-4" />
+          {prev.title}
+        </Link>
+      ) : (
+        <div />
+      )}
+
+      {next ? (
+        <Link
+          href={`/docs/${next.name}`}
+          className={cn(
+            "inline-flex items-center gap-1 rounded-md border px-3 py-1.5",
+            "text-muted-foreground text-sm transition-colors",
+            "hover:bg-muted hover:text-foreground",
+          )}
+        >
+          {next.title}
+          <ChevronRight className="h-4 w-4" />
+        </Link>
+      ) : (
+        <div />
+      )}
+    </div>
+  );
+}
diff --git a/apps/www/src/components/docs/index.ts b/apps/www/src/components/docs/index.ts
new file mode 100644
index 0000000..79b85db
--- /dev/null
+++ b/apps/www/src/components/docs/index.ts
@@ -0,0 +1,6 @@
+export { CodeRenderer } from "./code-renderer";
+export { ClientCodeWrapper } from "./client-code-wrapper";
+export { ComponentCodePreview } from "./component-code-preview";
+export { ApiTable } from "./api-table";
+export { ComponentNav } from "./component-nav";
+export { InstallationTabs } from "./installation-tabs";
diff --git a/apps/www/src/components/docs/installation-tabs.tsx b/apps/www/src/components/docs/installation-tabs.tsx
new file mode 100644
index 0000000..b660422
--- /dev/null
+++ b/apps/www/src/components/docs/installation-tabs.tsx
@@ -0,0 +1,77 @@
+"use client";
+
+import { cn } from "@/lib/utils";
+import { Tabs } from "radix-ui";
+import * as React from "react";
+import { ClientCodeWrapper } from "./client-code-wrapper";
+
+interface InstallationTabsProps {
+  componentName: string;
+  registryUrl?: string;
+  className?: string;
+}
+
+export function InstallationTabs({
+  componentName,
+  registryUrl = "https://usage-ui.vercel.app",
+  className,
+}: InstallationTabsProps) {
+  const cliCommand = `npx shadcn add ${registryUrl}/r/${componentName}.json`;
+
+  return (
+    <Tabs.Root defaultValue="cli" className={cn("w-full", className)}>
+      <Tabs.List className="inline-flex h-10 items-center justify-start gap-1 rounded-lg bg-muted p-1">
+        <Tabs.Trigger
+          value="cli"
+          className={cn(
+            "inline-flex items-center justify-center rounded-md px-3 py-1.5",
+            "font-medium text-sm transition-colors",
+            "data-[state=active]:bg-background data-[state=active]:shadow-sm",
+            "data-[state=inactive]:text-muted-foreground",
+          )}
+        >
+          CLI
+        </Tabs.Trigger>
+        <Tabs.Trigger
+          value="manual"
+          className={cn(
+            "inline-flex items-center justify-center rounded-md px-3 py-1.5",
+            "font-medium text-sm transition-colors",
+            "data-[state=active]:bg-background data-[state=active]:shadow-sm",
+            "data-[state=inactive]:text-muted-foreground",
+          )}
+        >
+          Manual
+        </Tabs.Trigger>
+      </Tabs.List>
+
+      <Tabs.Content value="cli" className="mt-4">
+        <ClientCodeWrapper code={cliCommand}>
+          <pre className="overflow-auto rounded-md border bg-muted p-4 text-sm">
+            <code>{cliCommand}</code>
+          </pre>
+        </ClientCodeWrapper>
+      </Tabs.Content>
+
+      <Tabs.Content value="manual" className="mt-4">
+        <div className="rounded-md border bg-muted p-4">
+          <p className="text-muted-foreground text-sm">
+            Copy the component source code from the{" "}
+            <a
+              href={`${registryUrl}/r/${componentName}.json`}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="font-medium text-foreground underline underline-offset-4"
+            >
+              registry JSON
+            </a>{" "}
+            and paste it into your project at{" "}
+            <code className="rounded bg-background px-1 py-0.5 text-xs">
+              components/ui/{componentName}.tsx
+            </code>
+          </p>
+        </div>
+      </Tabs.Content>
+    </Tabs.Root>
+  );
+}
diff --git a/apps/www/src/components/registry/registry-logo.tsx b/apps/www/src/components/registry/registry-logo.tsx
index 010fbea..8c78999 100644
--- a/apps/www/src/components/registry/registry-logo.tsx
+++ b/apps/www/src/components/registry/registry-logo.tsx
@@ -6,7 +6,7 @@ export function RegistryLogo() {
       <div className="flex-shrink-0 rounded-md bg-primary p-1">
         <Squirrel className="size-5 text-secondary" />
       </div>
-      <span className="text-xl font-medium tracking-tight">usage-ui</span>
+      <span className="font-medium text-xl tracking-tight">usage-ui</span>
     </>
   );
 }
diff --git a/apps/www/src/lib/code.ts b/apps/www/src/lib/code.ts
new file mode 100644
index 0000000..10392e1
--- /dev/null
+++ b/apps/www/src/lib/code.ts
@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import path from "node:path";
+import { cache } from "react";
+
+/**
+ * Get the path to the packages/ui directory from apps/www.
+ */
+function getPackageUiPath(): string {
+  // In monorepo: apps/www -> packages/ui
+  return path.join(process.cwd(), "..", "..", "packages", "ui");
+}
+
+/**
+ * Extract source code from a file path at build time.
+ * Uses React cache for deduplication during SSG.
+ *
+ * @param filePath - Relative path from packages/ui/
+ * @returns The file contents as a string
+ */
+export const extractCodeFromFilePath = cache((filePath: string): string => {
+  const absolutePath = path.join(getPackageUiPath(), filePath);
+
+  try {
+    return fs.readFileSync(absolutePath, "utf-8");
+  } catch (error) {
+    console.error(`Failed to read file: ${absolutePath}`, error);
+    return `// Error: Could not load source code for ${filePath}`;
+  }
+});
+
+/**
+ * Extract source code for a registry component by name.
+ * Looks up the path in registry.json and reads the file.
+ *
+ * @param componentName - The component name from registry.json
+ * @returns The source code string
+ */
+export const getComponentSource = cache((componentName: string): string => {
+  const registryPath = path.join(getPackageUiPath(), "registry.json");
+
+  try {
+    const registryContent = fs.readFileSync(registryPath, "utf-8");
+    const registry = JSON.parse(registryContent);
+    const item = registry.items.find(
+      (i: { name: string }) => i.name === componentName,
+    );
+
+    if (!item || !item.files?.[0]?.path) {
+      return `// Component "${componentName}" not found in registry`;
+    }
+
+    return extractCodeFromFilePath(item.files[0].path);
+  } catch (error) {
+    console.error(`Error loading registry for "${componentName}"`, error);
+    return `// Error loading registry for "${componentName}"`;
+  }
+});
+
+/**
+ * Get the file path for a registry component.
+ *
+ * @param componentName - The component name from registry.json
+ * @returns The relative file path from packages/ui/, or null if not found
+ */
+export const getComponentFilePath = cache(
+  (componentName: string): string | null => {
+    const registryPath = path.join(getPackageUiPath(), "registry.json");
+
+    try {
+      const registryContent = fs.readFileSync(registryPath, "utf-8");
+      const registry = JSON.parse(registryContent);
+      const item = registry.items.find(
+        (i: { name: string }) => i.name === componentName,
+      );
+
+      return item?.files?.[0]?.path || null;
+    } catch {
+      return null;
+    }
+  },
+);
diff --git a/apps/www/src/lib/extract-props.ts b/apps/www/src/lib/extract-props.ts
new file mode 100644
index 0000000..c0af2c0
--- /dev/null
+++ b/apps/www/src/lib/extract-props.ts
@@ -0,0 +1,316 @@
+import fs from "node:fs";
+import path from "node:path";
+import { cache } from "react";
+
+/**
+ * Props information extracted from TypeScript interfaces.
+ */
+export interface PropInfo {
+  /** Property name */
+  prop: string;
+  /** TypeScript type as string */
+  type: string;
+  /** Default value (if any) */
+  default?: string;
+  /** Whether the prop is required */
+  required: boolean;
+  /** Description from JSDoc comment */
+  description?: string;
+}
+
+/**
+ * Component documentation extracted from TypeScript files.
+ */
+export interface ComponentDoc {
+  /** Component display name */
+  displayName: string;
+  /** Component description from JSDoc */
+  description?: string;
+  /** Extracted props */
+  props: PropInfo[];
+}
+
+// Registry types
+interface RegistryFile {
+  path: string;
+  type: string;
+  target: string;
+}
+
+interface RegistryItem {
+  name: string;
+  type: string;
+  title: string;
+  description?: string;
+  files?: RegistryFile[];
+}
+
+interface Registry {
+  items: RegistryItem[];
+}
+
+/**
+ * Get the path to the packages/ui directory from apps/www.
+ */
+function getPackageUiPath(): string {
+  // In monorepo: apps/www -> packages/ui
+  return path.join(process.cwd(), "..", "..", "packages", "ui");
+}
+
+/**
+ * Parse JSDoc comments from a line of code.
+ * Extracts the description text from /** comment * / blocks.
+ */
+function parseJSDocComment(comment: string): string {
+  return comment
+    .replace(/\/\*\*\s*/g, "")
+    .replace(/\s*\*\//g, "")
+    .replace(/^\s*\*\s?/gm, "")
+    .trim();
+}
+
+/**
+ * Extract default value from component implementation.
+ * Looks for destructuring patterns like: { value, max = 100 }
+ */
+function extractDefaultFromDestructuring(
+  content: string,
+  propName: string,
+): string | undefined {
+  // Match destructuring patterns: { propName = defaultValue }
+  const patterns = [
+    // { prop = value } pattern
+    new RegExp(`${propName}\\s*=\\s*([^,}]+)`, "m"),
+    // prop: defaultValue in object
+    new RegExp(`${propName}:\\s*([^,}]+)`, "m"),
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match?.[1]) {
+      const value = match[1].trim();
+      // Clean up the value - remove type annotations and trailing content
+      const cleanValue = value.split(",")[0].trim();
+      // Skip if it's a type annotation or complex expression
+      if (
+        !cleanValue.includes(":") &&
+        !cleanValue.includes("=>") &&
+        cleanValue.length < 50
+      ) {
+        return cleanValue;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extract props from a TypeScript interface definition.
+ * This is a lightweight parser that handles common patterns.
+ */
+function extractPropsFromInterface(
+  content: string,
+  interfaceName: string,
+): PropInfo[] {
+  const props: PropInfo[] = [];
+
+  // Find the interface definition
+  const interfaceRegex = new RegExp(
+    `interface\\s+${interfaceName}[^{]*\\{([^}]+(?:\\{[^}]*\\}[^}]*)*)\\}`,
+    "s",
+  );
+  const match = content.match(interfaceRegex);
+
+  if (!match) {
+    return props;
+  }
+
+  const interfaceBody = match[1];
+
+  // Split into individual property declarations
+  // Handle multi-line JSDoc comments
+  const propRegex = /(\/\*\*[\s\S]*?\*\/\s*)?([\w]+)(\?)?:\s*([^;]+);/g;
+
+  for (const propMatch of interfaceBody.matchAll(propRegex)) {
+    const [, jsDocComment, propName, optional, typeStr] = propMatch;
+
+    // Skip inherited props (from extends)
+    if (propName.startsWith("...") || propName === "className") {
+      continue;
+    }
+
+    const description = jsDocComment
+      ? parseJSDocComment(jsDocComment)
+      : undefined;
+
+    // Clean up type string
+    let cleanType = typeStr.trim();
+    // Remove React.ComponentProps extensions for cleaner display
+    cleanType = cleanType
+      .replace(/React\.\w+<[^>]+>/g, "")
+      .replace(/Omit<[^>]+>/g, "")
+      .trim();
+
+    // Try to extract default from JSDoc or implementation
+    let defaultValue: string | undefined;
+    const defaultMatch = description?.match(/\(default:\s*([^)]+)\)/i);
+    if (defaultMatch) {
+      defaultValue = defaultMatch[1].trim();
+    } else {
+      defaultValue = extractDefaultFromDestructuring(content, propName);
+    }
+
+    props.push({
+      prop: propName,
+      type: cleanType || "unknown",
+      required: !optional,
+      default: defaultValue,
+      description: description?.replace(/\(default:\s*[^)]+\)/i, "").trim(),
+    });
+  }
+
+  return props;
+}
+
+/**
+ * Extract component documentation from a TypeScript file.
+ *
+ * @param filePath - Relative path from packages/ui/
+ * @returns Array of component documentation
+ */
+export const extractComponentDoc = cache((filePath: string): ComponentDoc[] => {
+  const absolutePath = path.join(getPackageUiPath(), filePath);
+  const docs: ComponentDoc[] = [];
+
+  try {
+    const content = fs.readFileSync(absolutePath, "utf-8");
+
+    // Find all interface definitions that end with "Props"
+    const interfaceNames = content.match(/interface\s+(\w+Props)/g) || [];
+
+    for (const match of interfaceNames) {
+      const interfaceName = match.replace("interface ", "");
+      const componentName = interfaceName.replace("Props", "");
+
+      // Extract component JSDoc (if any) - look above the component definition
+      const componentJSDocRegex = new RegExp(
+        `(\\/\\*\\*[\\s\\S]*?\\*\\/)\\s*(?:export\\s+)?(?:const|function)\\s+${componentName}`,
+      );
+      const componentJSDocMatch = content.match(componentJSDocRegex);
+      const componentDescription = componentJSDocMatch?.[1]
+        ? parseJSDocComment(componentJSDocMatch[1])
+        : undefined;
+
+      const props = extractPropsFromInterface(content, interfaceName);
+
+      if (props.length > 0) {
+        docs.push({
+          displayName: componentName,
+          description: componentDescription,
+          props,
+        });
+      }
+    }
+
+    return docs;
+  } catch (error) {
+    console.error(`Failed to extract props from: ${absolutePath}`, error);
+    return [];
+  }
+});
+
+/**
+ * Extract props for a registry component by name.
+ * Looks up the file path in registry.json and extracts props.
+ *
+ * @param componentName - The component name from registry.json
+ * @returns Array of component documentation, or empty array if not found
+ */
+export const getComponentProps = cache(
+  (componentName: string): ComponentDoc[] => {
+    const registryPath = path.join(getPackageUiPath(), "registry.json");
+
+    try {
+      const registryContent = fs.readFileSync(registryPath, "utf-8");
+      const registry: Registry = JSON.parse(registryContent);
+      const item = registry.items.find((i) => i.name === componentName);
+
+      if (!item?.files?.[0]?.path) {
+        console.warn(`Component "${componentName}" not found in registry`);
+        return [];
+      }
+
+      return extractComponentDoc(item.files[0].path);
+    } catch (error) {
+      console.error(`Failed to load registry for "${componentName}"`, error);
+      return [];
+    }
+  },
+);
+
+/**
+ * Get all available component names from the registry.
+ *
+ * @returns Array of component names
+ */
+export const getComponentNames = cache((): string[] => {
+  const registryPath = path.join(getPackageUiPath(), "registry.json");
+
+  try {
+    const registryContent = fs.readFileSync(registryPath, "utf-8");
+    const registry: Registry = JSON.parse(registryContent);
+    return registry.items
+      .filter((item) => item.type === "registry:component")
+      .map((item) => item.name);
+  } catch (error) {
+    console.error("Failed to load registry", error);
+    return [];
+  }
+});
+
+/**
+ * Convert PropInfo array to ApiTable-compatible format.
+ * Formats types and defaults for display.
+ *
+ * @param props - Array of PropInfo from extraction
+ * @returns Formatted data for ApiTable component
+ */
+export function formatPropsForApiTable(props: PropInfo[]): Array<{
+  prop: string;
+  type: string;
+  default: string;
+  description?: string;
+}> {
+  return props.map((p) => ({
+    prop: p.prop,
+    type: formatType(p.type),
+    default: p.required ? "Required" : p.default || "—",
+    description: p.description,
+  }));
+}
+
+/**
+ * Format a TypeScript type for display.
+ * Handles union types, generics, etc.
+ */
+function formatType(type: string): string {
+  // Clean up keyof expressions
+  if (type.includes("keyof typeof")) {
+    const match = type.match(/keyof typeof (\w+)/);
+    if (match) {
+      // Try to resolve the actual values
+      return type;
+    }
+  }
+
+  // Format union types with quotes for string literals
+  if (type.includes("|")) {
+    return type
+      .split("|")
+      .map((t) => t.trim())
+      .join(" | ");
+  }
+
+  return type;
+}
diff --git a/apps/www/src/lib/shiki.ts b/apps/www/src/lib/shiki.ts
new file mode 100644
index 0000000..94e55b3
--- /dev/null
+++ b/apps/www/src/lib/shiki.ts
@@ -0,0 +1,82 @@
+import { cache } from "react";
+import {
+  type BundledLanguage,
+  type Highlighter,
+  createHighlighter,
+} from "shiki";
+
+/** Supported languages for syntax highlighting */
+export type SupportedLanguage =
+  | "typescript"
+  | "tsx"
+  | "javascript"
+  | "jsx"
+  | "bash"
+  | "json"
+  | "css";
+
+let highlighterPromise: Promise<Highlighter> | null = null;
+
+/**
+ * Get or create the Shiki highlighter singleton.
+ * Loads github-light and github-dark themes.
+ */
+export const getHighlighter = cache(async (): Promise<Highlighter> => {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighter({
+      themes: ["github-light", "github-dark"],
+      langs: [
+        "typescript",
+        "tsx",
+        "javascript",
+        "jsx",
+        "bash",
+        "json",
+        "css",
+      ] satisfies SupportedLanguage[],
+    });
+  }
+  return highlighterPromise;
+});
+
+/**
+ * Highlight code with Shiki.
+ * Returns HTML string with syntax highlighting.
+ *
+ * @param code - The source code to highlight
+ * @param lang - The language for syntax highlighting
+ */
+export const highlightCode = cache(
+  async (code: string, lang: BundledLanguage = "tsx"): Promise<string> => {
+    const highlighter = await getHighlighter();
+
+    return highlighter.codeToHtml(code, {
+      lang,
+      themes: {
+        light: "github-light",
+        dark: "github-dark",
+      },
+    });
+  },
+);
+
+/**
+ * Highlight code and return the HTML tokens for more control over rendering.
+ * Useful when you need to wrap lines or add line numbers.
+ *
+ * @param code - The source code to highlight
+ * @param lang - The language for syntax highlighting
+ */
+export const highlightCodeToTokens = cache(
+  async (code: string, lang: BundledLanguage = "tsx") => {
+    const highlighter = await getHighlighter();
+
+    return highlighter.codeToTokens(code, {
+      lang,
+      themes: {
+        light: "github-light",
+        dark: "github-dark",
+      },
+    });
+  },
+);
diff --git a/apps/www/src/mdx-components.tsx b/apps/www/src/mdx-components.tsx
new file mode 100644
index 0000000..45f40eb
--- /dev/null
+++ b/apps/www/src/mdx-components.tsx
@@ -0,0 +1,87 @@
+import type { MDXComponents } from "mdx/types";
+
+// Import documentation components (created in Phase 2)
+// import { ComponentCodePreview } from "@/components/docs/component-code-preview"
+// import { ApiTable } from "@/components/docs/api-table"
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+  return {
+    // Override default elements with custom styling
+    h1: ({ children }) => (
+      <h1 className="scroll-m-20 font-semibold text-3xl tracking-tight">
+        {children}
+      </h1>
+    ),
+    h2: ({ children }) => (
+      <h2 className="mt-12 scroll-m-20 border-b pb-2 font-medium text-xl tracking-tight first:mt-0">
+        {children}
+      </h2>
+    ),
+    h3: ({ children }) => (
+      <h3 className="mt-8 scroll-m-20 font-medium text-lg tracking-tight">
+        {children}
+      </h3>
+    ),
+    h4: ({ children }) => (
+      <h4 className="mt-6 scroll-m-20 font-medium text-base tracking-tight">
+        {children}
+      </h4>
+    ),
+    p: ({ children }) => (
+      <p className="leading-7 [&:not(:first-child)]:mt-6">{children}</p>
+    ),
+    a: ({ children, href }) => (
+      <a
+        href={href}
+        className="font-medium text-primary underline underline-offset-4"
+      >
+        {children}
+      </a>
+    ),
+    ul: ({ children }) => (
+      <ul className="my-6 ml-6 list-disc [&>li]:mt-2">{children}</ul>
+    ),
+    ol: ({ children }) => (
+      <ol className="my-6 ml-6 list-decimal [&>li]:mt-2">{children}</ol>
+    ),
+    li: ({ children }) => <li>{children}</li>,
+    blockquote: ({ children }) => (
+      <blockquote className="mt-6 border-l-2 pl-6 italic">
+        {children}
+      </blockquote>
+    ),
+    hr: () => <hr className="my-4 md:my-8" />,
+    table: ({ children }) => (
+      <div className="my-6 w-full overflow-y-auto">
+        <table className="w-full">{children}</table>
+      </div>
+    ),
+    tr: ({ children }) => (
+      <tr className="m-0 border-t p-0 even:bg-muted">{children}</tr>
+    ),
+    th: ({ children }) => (
+      <th className="border px-4 py-2 text-left font-bold [&[align=center]]:text-center [&[align=right]]:text-right">
+        {children}
+      </th>
+    ),
+    td: ({ children }) => (
+      <td className="border px-4 py-2 text-left [&[align=center]]:text-center [&[align=right]]:text-right">
+        {children}
+      </td>
+    ),
+    pre: ({ children }) => (
+      <pre className="mt-6 mb-4 overflow-x-auto rounded-lg border bg-muted px-4 py-4">
+        {children}
+      </pre>
+    ),
+    code: ({ children }) => (
+      <code className="relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm">
+        {children}
+      </code>
+    ),
+    // Add custom components (uncomment when created in Phase 2)
+    // ComponentCodePreview,
+    // ApiTable,
+    ...components,
+  };
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 34c687f..d6a55af 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -89,6 +89,9 @@ importers:
       recharts:
         specifier: ^2.15.4
         version: 2.15.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      shiki:
+        specifier: ^3.21.0
+        version: 3.21.0
       sonner:
         specifier: ^2.0.7
         version: 2.0.7(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -105,6 +108,9 @@ importers:
       '@tailwindcss/postcss':
         specifier: ^4.1.18
         version: 4.1.18
+      '@types/mdx':
+        specifier: ^2.0.13
+        version: 2.0.13
       '@types/node':
         specifier: ^22.19.3
         version: 22.19.7
@@ -1513,6 +1519,27 @@ packages:
   '@sec-ant/readable-stream@0.4.1':
     resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
 
+  '@shikijs/core@3.21.0':
+    resolution: {integrity: sha512-AXSQu/2n1UIQekY8euBJlvFYZIw0PHY63jUzGbrOma4wPxzznJXTXkri+QcHeBNaFxiiOljKxxJkVSoB3PjbyA==}
+
+  '@shikijs/engine-javascript@3.21.0':
+    resolution: {integrity: sha512-ATwv86xlbmfD9n9gKRiwuPpWgPENAWCLwYCGz9ugTJlsO2kOzhOkvoyV/UD+tJ0uT7YRyD530x6ugNSffmvIiQ==}
+
+  '@shikijs/engine-oniguruma@3.21.0':
+    resolution: {integrity: sha512-OYknTCct6qiwpQDqDdf3iedRdzj6hFlOPv5hMvI+hkWfCKs5mlJ4TXziBG9nyabLwGulrUjHiCq3xCspSzErYQ==}
+
+  '@shikijs/langs@3.21.0':
+    resolution: {integrity: sha512-g6mn5m+Y6GBJ4wxmBYqalK9Sp0CFkUqfNzUy2pJglUginz6ZpWbaWjDB4fbQ/8SHzFjYbtU6Ddlp1pc+PPNDVA==}
+
+  '@shikijs/themes@3.21.0':
+    resolution: {integrity: sha512-BAE4cr9EDiZyYzwIHEk7JTBJ9CzlPuM4PchfcA5ao1dWXb25nv6hYsoDiBq2aZK9E3dlt3WB78uI96UESD+8Mw==}
+
+  '@shikijs/types@3.21.0':
+    resolution: {integrity: sha512-zGrWOxZ0/+0ovPY7PvBU2gIS9tmhSUUt30jAcNV0Bq0gb2S98gwfjIs1vxlmH5zM7/4YxLamT6ChlqqAJmPPjA==}
+
+  '@shikijs/vscode-textmate@10.0.2':
+    resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
+
   '@sindresorhus/merge-streams@4.0.0':
     resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
     engines: {node: '>=18'}
@@ -1652,6 +1679,15 @@ packages:
   '@types/d3-timer@3.0.2':
     resolution: {integrity: sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==}
 
+  '@types/hast@3.0.4':
+    resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
+
+  '@types/mdast@4.0.4':
+    resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
+
+  '@types/mdx@2.0.13':
+    resolution: {integrity: sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw==}
+
   '@types/node@12.20.55':
     resolution: {integrity: sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==}
 
@@ -1669,9 +1705,15 @@ packages:
   '@types/statuses@2.0.6':
     resolution: {integrity: sha512-xMAgYwceFhRA2zY+XbEA7mxYbA093wdiW8Vu6gZPGWy9cmOyU9XesH1tNcEWsKFd5Vzrqx5T3D38PWx1FIIXkA==}
 
+  '@types/unist@3.0.3':
+    resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
+
   '@types/validate-npm-package-name@4.0.2':
     resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
 
+  '@ungap/structured-clone@1.3.0':
+    resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==}
+
   '@vercel/analytics@1.6.1':
     resolution: {integrity: sha512-oH9He/bEM+6oKlv3chWuOOcp8Y6fo6/PSro8hEkgCW3pu9/OiCXiUpRUogDh3Fs3LH2sosDrx8CxeOLBEE+afg==}
     peerDependencies:
@@ -1822,10 +1864,19 @@ packages:
   caniuse-lite@1.0.30001766:
     resolution: {integrity: sha512-4C0lfJ0/YPjJQHagaE9x2Elb69CIqEPZeG0anQt9SIvIoOH4a4uaRl73IavyO+0qZh6MDLH//DrXThEYKHkmYA==}
 
+  ccount@2.0.1:
+    resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
+
   chalk@5.6.2:
     resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
     engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
 
+  character-entities-html4@2.1.0:
+    resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
+
+  character-entities-legacy@3.0.0:
+    resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==}
+
   chardet@2.1.1:
     resolution: {integrity: sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ==}
 
@@ -1875,6 +1926,9 @@ packages:
   color-name@1.1.4:
     resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
 
+  comma-separated-tokens@2.0.3:
+    resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==}
+
   commander@11.1.0:
     resolution: {integrity: sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==}
     engines: {node: '>=16'}
@@ -2025,6 +2079,10 @@ packages:
     resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
     engines: {node: '>= 0.8'}
 
+  dequal@2.0.3:
+    resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
+    engines: {node: '>=6'}
+
   detect-indent@6.1.0:
     resolution: {integrity: sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==}
     engines: {node: '>=8'}
@@ -2036,6 +2094,9 @@ packages:
   detect-node-es@1.1.0:
     resolution: {integrity: sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==}
 
+  devlop@1.1.0:
+    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
+
   diff@8.0.3:
     resolution: {integrity: sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==}
     engines: {node: '>=0.3.1'}
@@ -2305,6 +2366,12 @@ packages:
     resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
     engines: {node: '>= 0.4'}
 
+  hast-util-to-html@9.0.5:
+    resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==}
+
+  hast-util-whitespace@3.0.0:
+    resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
+
   headers-polyfill@4.0.3:
     resolution: {integrity: sha512-IScLbePpkvO846sIwOtOTDjutRMWdXdJmXdMvk6gCBHxFO8d+QKOQedyZSxFTTFYRSmlgSTDtXqqq4pcenBXLQ==}
 
@@ -2312,6 +2379,9 @@ packages:
     resolution: {integrity: sha512-l7qMiNee7t82bH3SeyUCt9UF15EVmaBvsppY2zQtrbIhl/yzBTny+YUxsVjSjQ6gaqaeVtZmGocom8TzBlA4Yw==}
     engines: {node: '>=16.9.0'}
 
+  html-void-elements@3.0.0:
+    resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==}
+
   http-errors@2.0.1:
     resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
     engines: {node: '>= 0.8'}
@@ -2662,6 +2732,9 @@ packages:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
 
+  mdast-util-to-hast@13.2.1:
+    resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==}
+
   media-typer@1.1.0:
     resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
     engines: {node: '>= 0.8'}
@@ -2677,6 +2750,21 @@ packages:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
 
+  micromark-util-character@2.1.1:
+    resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
+
+  micromark-util-encode@2.0.1:
+    resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
+
+  micromark-util-sanitize-uri@2.0.1:
+    resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
+
+  micromark-util-symbol@2.0.1:
+    resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
+
+  micromark-util-types@2.0.2:
+    resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
+
   micromatch@4.0.8:
     resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
     engines: {node: '>=8.6'}
@@ -2808,6 +2896,12 @@ packages:
     resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
     engines: {node: '>=18'}
 
+  oniguruma-parser@0.12.1:
+    resolution: {integrity: sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w==}
+
+  oniguruma-to-es@4.3.4:
+    resolution: {integrity: sha512-3VhUGN3w2eYxnTzHn+ikMI+fp/96KoRSVK9/kMTcFqj1NRDh2IhQCKvYxDnWePKRXY/AqH+Fuiyb7VHSzBjHfA==}
+
   open@11.0.0:
     resolution: {integrity: sha512-smsWv2LzFjP03xmvFoJ331ss6h+jixfA4UUV/Bsiyuu4YJPfN+FIQGOIiv4w9/+MoHkfkJ22UIaQWRVFRfH6Vw==}
     engines: {node: '>=20'}
@@ -2940,6 +3034,9 @@ packages:
   prop-types@15.8.1:
     resolution: {integrity: sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==}
 
+  property-information@7.1.0:
+    resolution: {integrity: sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==}
+
   proxy-addr@2.0.7:
     resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
     engines: {node: '>= 0.10'}
@@ -3068,6 +3165,15 @@ packages:
       react: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
+  regex-recursion@6.0.2:
+    resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==}
+
+  regex-utilities@2.3.0:
+    resolution: {integrity: sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==}
+
+  regex@6.1.0:
+    resolution: {integrity: sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==}
+
   require-directory@2.1.1:
     resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
     engines: {node: '>=0.10.0'}
@@ -3148,6 +3254,9 @@ packages:
     resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
     engines: {node: '>=8'}
 
+  shiki@3.21.0:
+    resolution: {integrity: sha512-N65B/3bqL/TI2crrXr+4UivctrAGEjmsib5rPMMPpFp1xAx/w03v8WZ9RDDFYteXoEgY7qZ4HGgl5KBIu1153w==}
+
   side-channel-list@1.0.0:
     resolution: {integrity: sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==}
     engines: {node: '>= 0.4'}
@@ -3192,6 +3301,9 @@ packages:
     resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
     engines: {node: '>=0.10.0'}
 
+  space-separated-tokens@2.0.2:
+    resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
+
   spawndamnit@3.0.1:
     resolution: {integrity: sha512-MmnduQUuHCoFckZoWnXsTg7JaiLBJrKFj9UI2MbRPGaJeVpsLcVBu6P/IGZovziM/YBsellCmsprgNA+w0CzVg==}
 
@@ -3217,6 +3329,9 @@ packages:
     resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
     engines: {node: '>=18'}
 
+  stringify-entities@4.0.4:
+    resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==}
+
   stringify-object@5.0.0:
     resolution: {integrity: sha512-zaJYxz2FtcMb4f+g60KsRNFOpVMUyuJgA51Zi5Z1DOTC3S59+OQiVOzE9GZt0x72uBGWKsQIuBKeF9iusmKFsg==}
     engines: {node: '>=14.16'}
@@ -3298,6 +3413,9 @@ packages:
     resolution: {integrity: sha512-kXuRi1mtaKMrsLUxz3sQYvVl37B0Ns6MzfrtV5DvJceE9bPyspOqk9xxv7XbZWcfLWbFmm997vl83qUWVJA64w==}
     engines: {node: '>=16'}
 
+  trim-lines@3.0.1:
+    resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
+
   ts-morph@26.0.0:
     resolution: {integrity: sha512-ztMO++owQnz8c/gIENcM9XfCEzgoGphTv+nKpYNM1bgsdOVC/jRZuEBf6N+mLLDNg68Kl+GgUZfOySaRiG1/Ug==}
 
@@ -3365,6 +3483,21 @@ packages:
     resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
     engines: {node: '>=18'}
 
+  unist-util-is@6.0.1:
+    resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
+
+  unist-util-position@5.0.0:
+    resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==}
+
+  unist-util-stringify-position@4.0.0:
+    resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
+
+  unist-util-visit-parents@6.0.2:
+    resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
+
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+
   universalify@0.1.2:
     resolution: {integrity: sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==}
     engines: {node: '>= 4.0.0'}
@@ -3428,6 +3561,12 @@ packages:
       react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
       react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc
 
+  vfile-message@4.0.3:
+    resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
+
+  vfile@6.0.3:
+    resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
+
   victory-vendor@36.9.2:
     resolution: {integrity: sha512-PnpQQMuxlwYdocC8fIJqVXvkeViHYzotI+NJrCuav0ZYFoq912ZHBk3mCeuj+5/VpodOjPe1z0Fk2ihgzlXqjQ==}
 
@@ -3491,6 +3630,9 @@ packages:
   zod@3.25.76:
     resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
 
+  zwitch@2.0.4:
+    resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
+
 snapshots:
 
   '@alloc/quick-lru@5.2.0': {}
@@ -4942,6 +5084,39 @@ snapshots:
 
   '@sec-ant/readable-stream@0.4.1': {}
 
+  '@shikijs/core@3.21.0':
+    dependencies:
+      '@shikijs/types': 3.21.0
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+      hast-util-to-html: 9.0.5
+
+  '@shikijs/engine-javascript@3.21.0':
+    dependencies:
+      '@shikijs/types': 3.21.0
+      '@shikijs/vscode-textmate': 10.0.2
+      oniguruma-to-es: 4.3.4
+
+  '@shikijs/engine-oniguruma@3.21.0':
+    dependencies:
+      '@shikijs/types': 3.21.0
+      '@shikijs/vscode-textmate': 10.0.2
+
+  '@shikijs/langs@3.21.0':
+    dependencies:
+      '@shikijs/types': 3.21.0
+
+  '@shikijs/themes@3.21.0':
+    dependencies:
+      '@shikijs/types': 3.21.0
+
+  '@shikijs/types@3.21.0':
+    dependencies:
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+
+  '@shikijs/vscode-textmate@10.0.2': {}
+
   '@sindresorhus/merge-streams@4.0.0': {}
 
   '@standard-schema/utils@0.3.0': {}
@@ -5057,6 +5232,16 @@ snapshots:
 
   '@types/d3-timer@3.0.2': {}
 
+  '@types/hast@3.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/mdast@4.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/mdx@2.0.13': {}
+
   '@types/node@12.20.55': {}
 
   '@types/node@22.19.7':
@@ -5073,8 +5258,12 @@ snapshots:
 
   '@types/statuses@2.0.6': {}
 
+  '@types/unist@3.0.3': {}
+
   '@types/validate-npm-package-name@4.0.2': {}
 
+  '@ungap/structured-clone@1.3.0': {}
+
   '@vercel/analytics@1.6.1(next@16.1.6(@babel/core@7.28.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react@19.2.4)':
     optionalDependencies:
       next: 16.1.6(@babel/core@7.28.6)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -5183,8 +5372,14 @@ snapshots:
 
   caniuse-lite@1.0.30001766: {}
 
+  ccount@2.0.1: {}
+
   chalk@5.6.2: {}
 
+  character-entities-html4@2.1.0: {}
+
+  character-entities-legacy@3.0.0: {}
+
   chardet@2.1.1: {}
 
   ci-info@3.9.0: {}
@@ -5231,6 +5426,8 @@ snapshots:
 
   color-name@1.1.4: {}
 
+  comma-separated-tokens@2.0.3: {}
+
   commander@11.1.0: {}
 
   commander@14.0.2: {}
@@ -5336,12 +5533,18 @@ snapshots:
 
   depd@2.0.0: {}
 
+  dequal@2.0.3: {}
+
   detect-indent@6.1.0: {}
 
   detect-libc@2.1.2: {}
 
   detect-node-es@1.1.0: {}
 
+  devlop@1.1.0:
+    dependencies:
+      dequal: 2.0.3
+
   diff@8.0.3: {}
 
   dir-glob@3.0.1:
@@ -5639,10 +5842,30 @@ snapshots:
     dependencies:
       function-bind: 1.1.2
 
+  hast-util-to-html@9.0.5:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      comma-separated-tokens: 2.0.3
+      hast-util-whitespace: 3.0.0
+      html-void-elements: 3.0.0
+      mdast-util-to-hast: 13.2.1
+      property-information: 7.1.0
+      space-separated-tokens: 2.0.2
+      stringify-entities: 4.0.4
+      zwitch: 2.0.4
+
+  hast-util-whitespace@3.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
   headers-polyfill@4.0.3: {}
 
   hono@4.11.7: {}
 
+  html-void-elements@3.0.0: {}
+
   http-errors@2.0.1:
     dependencies:
       depd: 2.0.0
@@ -5904,6 +6127,18 @@ snapshots:
 
   math-intrinsics@1.1.0: {}
 
+  mdast-util-to-hast@13.2.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@ungap/structured-clone': 1.3.0
+      devlop: 1.1.0
+      micromark-util-sanitize-uri: 2.0.1
+      trim-lines: 3.0.1
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+
   media-typer@1.1.0: {}
 
   merge-descriptors@2.0.0: {}
@@ -5912,6 +6147,23 @@ snapshots:
 
   merge2@1.4.1: {}
 
+  micromark-util-character@2.1.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-encode@2.0.1: {}
+
+  micromark-util-sanitize-uri@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-encode: 2.0.1
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-symbol@2.0.1: {}
+
+  micromark-util-types@2.0.2: {}
+
   micromatch@4.0.8:
     dependencies:
       braces: 3.0.3
@@ -6038,6 +6290,14 @@ snapshots:
     dependencies:
       mimic-function: 5.0.1
 
+  oniguruma-parser@0.12.1: {}
+
+  oniguruma-to-es@4.3.4:
+    dependencies:
+      oniguruma-parser: 0.12.1
+      regex: 6.1.0
+      regex-recursion: 6.0.2
+
   open@11.0.0:
     dependencies:
       default-browser: 5.4.0
@@ -6160,6 +6420,8 @@ snapshots:
       object-assign: 4.1.1
       react-is: 16.13.1
 
+  property-information@7.1.0: {}
+
   proxy-addr@2.0.7:
     dependencies:
       forwarded: 0.2.0
@@ -6348,6 +6610,16 @@ snapshots:
       tiny-invariant: 1.3.3
       victory-vendor: 36.9.2
 
+  regex-recursion@6.0.2:
+    dependencies:
+      regex-utilities: 2.3.0
+
+  regex-utilities@2.3.0: {}
+
+  regex@6.1.0:
+    dependencies:
+      regex-utilities: 2.3.0
+
   require-directory@2.1.1: {}
 
   require-from-string@2.0.2: {}
@@ -6498,6 +6770,17 @@ snapshots:
 
   shebang-regex@3.0.0: {}
 
+  shiki@3.21.0:
+    dependencies:
+      '@shikijs/core': 3.21.0
+      '@shikijs/engine-javascript': 3.21.0
+      '@shikijs/engine-oniguruma': 3.21.0
+      '@shikijs/langs': 3.21.0
+      '@shikijs/themes': 3.21.0
+      '@shikijs/types': 3.21.0
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+
   side-channel-list@1.0.0:
     dependencies:
       es-errors: 1.3.0
@@ -6543,6 +6826,8 @@ snapshots:
 
   source-map@0.6.1: {}
 
+  space-separated-tokens@2.0.2: {}
+
   spawndamnit@3.0.1:
     dependencies:
       cross-spawn: 7.0.6
@@ -6568,6 +6853,11 @@ snapshots:
       get-east-asian-width: 1.4.0
       strip-ansi: 7.1.2
 
+  stringify-entities@4.0.4:
+    dependencies:
+      character-entities-html4: 2.1.0
+      character-entities-legacy: 3.0.0
+
   stringify-object@5.0.0:
     dependencies:
       get-own-enumerable-keys: 1.0.0
@@ -6625,6 +6915,8 @@ snapshots:
     dependencies:
       tldts: 7.0.19
 
+  trim-lines@3.0.1: {}
+
   ts-morph@26.0.0:
     dependencies:
       '@ts-morph/common': 0.27.0
@@ -6683,6 +6975,29 @@ snapshots:
 
   unicorn-magic@0.3.0: {}
 
+  unist-util-is@6.0.1:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-position@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-stringify-position@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-visit-parents@6.0.2:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+
+  unist-util-visit@5.1.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
   universalify@0.1.2: {}
 
   universalify@2.0.1: {}
@@ -6731,6 +7046,16 @@ snapshots:
       - '@types/react'
       - '@types/react-dom'
 
+  vfile-message@4.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-stringify-position: 4.0.0
+
+  vfile@6.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile-message: 4.0.3
+
   victory-vendor@36.9.2:
     dependencies:
       '@types/d3-array': 3.2.2
@@ -6802,3 +7127,5 @@ snapshots:
       zod: 3.25.76
 
   zod@3.25.76: {}
+
+  zwitch@2.0.4: {}

From 2fa47c0de20ef84d67b06deecd0218e4452567b3 Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 17:46:54 -0500
Subject: [PATCH 04/10] feat(www): migrate component pages to /docs route with
 new documentation system

- Add new /docs/[name] pages for component documentation
- Remove old /registry/[name] route in favor of /docs
- Update all sidebar and homepage links to use /docs route
- Add component-preview and preview-error-boundary components
- Update add-registry-component workflow with documentation step
- Add changeset for documentation system changes
---
 .../workflows/add-component-documentation.md  | 186 ++++++++++++++++++
 .agents/workflows/add-registry-component.md   |  55 ++++++
 .changeset/add-documentation-system.md        |  12 ++
 apps/www/src/app/(registry)/page.tsx          |   8 +-
 .../app/(registry)/registry/[name]/page.tsx   |  53 -----
 apps/www/src/app/docs/[slug]/page.tsx         | 135 +++++++++++++
 apps/www/src/app/docs/layout.tsx              |  25 +++
 .../src/components/docs/component-preview.tsx |  51 +++++
 apps/www/src/components/docs/index.ts         |   2 +
 .../docs/preview-error-boundary.tsx           |  47 +++++
 .../components/registry/registry-sidebar.tsx  |   6 +-
 11 files changed, 520 insertions(+), 60 deletions(-)
 create mode 100644 .agents/workflows/add-component-documentation.md
 create mode 100644 .changeset/add-documentation-system.md
 delete mode 100644 apps/www/src/app/(registry)/registry/[name]/page.tsx
 create mode 100644 apps/www/src/app/docs/[slug]/page.tsx
 create mode 100644 apps/www/src/app/docs/layout.tsx
 create mode 100644 apps/www/src/components/docs/component-preview.tsx
 create mode 100644 apps/www/src/components/docs/preview-error-boundary.tsx

diff --git a/.agents/workflows/add-component-documentation.md b/.agents/workflows/add-component-documentation.md
new file mode 100644
index 0000000..8e176d8
--- /dev/null
+++ b/.agents/workflows/add-component-documentation.md
@@ -0,0 +1,186 @@
+# Workflow: Add Component Documentation
+
+> Step-by-step procedure for adding documentation to an existing registry component.
+
+---
+
+## Prerequisites
+
+- [ ] Component exists in `packages/ui/src/components/registry/`
+- [ ] Component is registered in `packages/ui/registry.json`
+- [ ] Documentation infrastructure is set up (Phase 1-4 complete)
+
+---
+
+## Steps
+
+### 1. Create MDX File
+
+```bash
+touch apps/www/src/content/docs/[component-name].mdx
+```
+
+### 2. Add Frontmatter
+
+```mdx
+---
+title: Component Name
+description: Brief description of the component.
+---
+```
+
+### 3. Write Documentation Sections
+
+Include these sections in order:
+
+1. **Title & Description** - H1 and intro paragraph
+2. **Examples** - ComponentCodePreview for each variant
+3. **Installation** - InstallationTabs component
+4. **Usage** - Code example with import
+5. **API Reference** - Props table for each exported component
+6. **Accessibility** (if applicable) - ARIA details
+
+### 4. Add Props Documentation
+
+Document all props in the API Reference table:
+
+| Column | Content |
+|--------|---------|
+| Prop | Prop name in backticks |
+| Type | TypeScript type |
+| Default | Default value or "Required" |
+| Description | Brief description |
+
+### 5. Verify Documentation
+
+```bash
+# Start dev server
+pnpm dev --filter=@usage-ui/www
+
+# Visit the page
+open http://localhost:3000/docs/[component-name]
+```
+
+### 6. Build and Test
+
+```bash
+pnpm build --filter=@usage-ui/www
+```
+
+---
+
+## MDX Template
+
+```mdx
+---
+title: Component Name
+description: Brief description of the component.
+---
+
+# Component Name
+
+[Description paragraph explaining the component's purpose and use cases.]
+
+## Examples
+
+### Basic Usage
+
+<ComponentCodePreview name="component-name">
+  {/* Preview content */}
+</ComponentCodePreview>
+
+### With Variants
+
+[If the component has variants, show additional examples]
+
+<ComponentCodePreview name="component-name-variants">
+  {/* Variant preview content */}
+</ComponentCodePreview>
+
+## Installation
+
+<InstallationTabs componentName="component-name" />
+
+## Usage
+
+\`\`\`tsx
+import { ComponentName } from "@/components/ui/component-name"
+
+export function MyComponent() {
+  return (
+    <ComponentName
+      prop="value"
+    />
+  )
+}
+\`\`\`
+
+## API Reference
+
+### ComponentName
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | Required | The current value |
+| `max` | `number` | `100` | The maximum value |
+| `variant` | `"default" \| "success"` | `"default"` | Visual variant |
+| `className` | `string` | — | Additional CSS classes |
+
+## Accessibility
+
+[If using Radix primitives, document accessibility features:]
+
+- Proper semantic HTML elements
+- ARIA attributes (`aria-label`, `aria-valuenow`, etc.)
+- Keyboard navigation support
+- Screen reader announcements
+```
+
+---
+
+## Validation Checklist
+
+- [ ] MDX file exists at correct path
+- [ ] Frontmatter has title and description
+- [ ] Examples section shows component in action
+- [ ] Installation section uses InstallationTabs
+- [ ] API Reference documents all exported components
+- [ ] All props are documented with types
+- [ ] Page renders without errors
+- [ ] Build succeeds
+
+---
+
+## Troubleshooting
+
+### MDX not rendering
+
+**Cause**: MDX loader not configured or file extension wrong.
+
+**Fix**: Verify `next.config.ts` has MDX configuration and file uses `.mdx` extension.
+
+### Component preview not showing
+
+**Cause**: Preview component not imported or type mismatch.
+
+**Fix**: Ensure ComponentPreview receives correct `type` prop.
+
+### Props table not displaying
+
+**Cause**: ApiTable data array malformed.
+
+**Fix**: Verify each row has `prop`, `type`, and `default` fields.
+
+### "Cannot find module" error
+
+**Cause**: MDX components not exported from mdx-components.tsx.
+
+**Fix**: Add ComponentCodePreview and InstallationTabs to the useMDXComponents return object.
+
+---
+
+## References
+
+- Component Creation: `.agents/workflows/add-registry-component.md`
+- Documentation Strategy: `.agents/context/decisions/005-component-documentation-strategy.md`
+- Implementation Guide: `.agents/workflows/implement-documentation-redesign.md`
diff --git a/.agents/workflows/add-registry-component.md b/.agents/workflows/add-registry-component.md
index 883b368..d4a0171 100644
--- a/.agents/workflows/add-registry-component.md
+++ b/.agents/workflows/add-registry-component.md
@@ -128,6 +128,59 @@ pnpm changeset
 # Write description
 ```
 
+### 9. Create Documentation Page (After Component Complete)
+
+**Create:** `apps/www/src/content/docs/[component-name].mdx`
+
+Use the MDX template:
+
+```mdx
+---
+title: Component Name
+description: Brief description of the component.
+---
+
+# Component Name
+
+[Description paragraph]
+
+## Examples
+
+### Basic Usage
+
+<ComponentCodePreview name="component-name">
+  {/* Preview content */}
+</ComponentCodePreview>
+
+## Installation
+
+<InstallationTabs componentName="component-name" />
+
+## API Reference
+
+### ComponentName
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | Required | The current value |
+| `max` | `number` | `100` | The maximum value |
+| `variant` | `"default" \| "success" \| "warning" \| "danger"` | `"default"` | Visual variant |
+
+## Accessibility
+
+[Include ARIA details if component uses Radix primitives]
+```
+
+**Validation:**
+
+```bash
+# Start dev server
+pnpm dev --filter=@usage-ui/www
+
+# Visit documentation page
+open http://localhost:3000/docs/[component-name]
+```
+
 ---
 
 ## Validation Checklist
@@ -139,6 +192,8 @@ pnpm changeset
 - [ ] Build succeeds: `pnpm build`
 - [ ] Generated JSON exists in `apps/www/public/r/`
 - [ ] Installation works via shadcn CLI
+- [ ] Documentation page exists at `apps/www/src/content/docs/[component-name].mdx`
+- [ ] Documentation page renders without errors at `/docs/[component-name]`
 
 ---
 
diff --git a/.changeset/add-documentation-system.md b/.changeset/add-documentation-system.md
new file mode 100644
index 0000000..218d282
--- /dev/null
+++ b/.changeset/add-documentation-system.md
@@ -0,0 +1,12 @@
+---
+"@usage-ui/www": minor
+---
+
+Add component documentation system with MDX support, Shiki syntax highlighting, and preview/code tabs
+
+- Added documentation infrastructure with code extraction utilities
+- Created core documentation components: CodeRenderer, ComponentCodePreview, ApiTable
+- Added layout components: ComponentNav, InstallationTabs
+- Implemented hybrid preview system for components and blocks
+- Created /docs/[slug] route for component documentation pages
+- Added MDX configuration with custom typography styles
diff --git a/apps/www/src/app/(registry)/page.tsx b/apps/www/src/app/(registry)/page.tsx
index a2a7c34..210cfbd 100644
--- a/apps/www/src/app/(registry)/page.tsx
+++ b/apps/www/src/app/(registry)/page.tsx
@@ -51,7 +51,7 @@ export default function Home() {
                 className="flex items-center justify-between"
               >
                 <Link
-                  href={`/registry/${item.name}`}
+                  href={`/docs/${item.name}`}
                   className="text-sm hover:underline"
                 >
                   {item.title}
@@ -85,7 +85,7 @@ export default function Home() {
                   className="flex items-center justify-between"
                 >
                   <Link
-                    href={`/registry/${item.name}`}
+                    href={`/docs/${item.name}`}
                     className="text-sm hover:underline"
                   >
                     {item.title}
@@ -118,7 +118,7 @@ export default function Home() {
                   className="flex items-center justify-between"
                 >
                   <Link
-                    href={`/registry/${item.name}`}
+                    href={`/docs/${item.name}`}
                     className="text-sm hover:underline"
                   >
                     {item.title}
@@ -168,7 +168,7 @@ export default function Home() {
             To get begin, start with a block{" "}
             <span className="italic">
               (like the{" "}
-              <a href="/registry/blank" className="underline">
+              <a href="/docs/blank" className="underline">
                 blank block
               </a>
               )
diff --git a/apps/www/src/app/(registry)/registry/[name]/page.tsx b/apps/www/src/app/(registry)/registry/[name]/page.tsx
deleted file mode 100644
index 19b197b..0000000
--- a/apps/www/src/app/(registry)/registry/[name]/page.tsx
+++ /dev/null
@@ -1,53 +0,0 @@
-import { ArrowLeft } from "lucide-react";
-import Link from "next/link";
-import { notFound } from "next/navigation";
-
-import { ComponentCard } from "@/components/registry/component-card";
-import { Button } from "@/components/ui/button";
-import { getRegistryItem, getRegistryItems } from "@/lib/registry";
-import { getPrompt } from "@/lib/utils";
-
-export async function generateStaticParams() {
-  const components = getRegistryItems();
-
-  return components.map(({ name }) => ({
-    name,
-  }));
-}
-
-export default async function RegistryItemPage({
-  params,
-}: {
-  params: Promise<{ name: string }>;
-}) {
-  const { name } = await params;
-  const component = getRegistryItem(name);
-
-  if (!component) {
-    notFound();
-  }
-
-  return (
-    <div className="container p-5 md:p-10">
-      <div className="mb-6 flex items-center justify-between">
-        <div>
-          <Button variant="ghost" size="sm" asChild className="mb-4">
-            <Link href="/">
-              <ArrowLeft className="mr-2 size-4" />
-              Back to Home
-            </Link>
-          </Button>
-          <h1 className="text-balance font-semibold text-3xl tracking-tight">
-            {component.title}
-          </h1>
-        </div>
-      </div>
-
-      <ComponentCard
-        component={component}
-        baseUrl={process.env.VERCEL_PROJECT_PRODUCTION_URL ?? ""}
-        prompt={getPrompt()}
-      />
-    </div>
-  );
-}
diff --git a/apps/www/src/app/docs/[slug]/page.tsx b/apps/www/src/app/docs/[slug]/page.tsx
new file mode 100644
index 0000000..d20ad1a
--- /dev/null
+++ b/apps/www/src/app/docs/[slug]/page.tsx
@@ -0,0 +1,135 @@
+import { notFound } from "next/navigation";
+
+import {
+  ApiTable,
+  ComponentCodePreview,
+  ComponentNav,
+  ComponentPreview,
+  InstallationTabs,
+  PreviewErrorBoundary,
+} from "@/components/docs";
+import { getComponentSource } from "@/lib/code";
+import { getRegistryItem, getRegistryItems } from "@/lib/registry";
+
+export async function generateStaticParams() {
+  const items = getRegistryItems();
+  return items.map((item) => ({ slug: item.name }));
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const component = getRegistryItem(slug);
+
+  return {
+    title: `${component.title} | Usage UI`,
+    description: component.description,
+  };
+}
+
+export default async function ComponentDocPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const component = getRegistryItem(slug);
+
+  if (!component) {
+    notFound();
+  }
+
+  const sourceCode = getComponentSource(slug);
+  const componentType = component.type as
+    | "registry:component"
+    | "registry:block"
+    | "registry:ui";
+
+  return (
+    <>
+      {/* Header */}
+      <h1 className="scroll-m-20 font-semibold text-3xl tracking-tight">
+        {component.title}
+      </h1>
+      {component.description && (
+        <p className="mt-2 text-lg text-muted-foreground">
+          {component.description}
+        </p>
+      )}
+
+      {/* Examples Section */}
+      <h2 className="mt-12 scroll-m-20 border-b pb-2 font-medium text-xl tracking-tight">
+        Examples
+      </h2>
+
+      <h3 className="mt-8 scroll-m-20 font-medium text-lg tracking-tight">
+        Basic
+      </h3>
+      <div className="mt-4">
+        <ComponentCodePreview name={slug} code={sourceCode}>
+          <PreviewErrorBoundary>
+            <ComponentPreview
+              name={slug}
+              type={
+                componentType === "registry:ui"
+                  ? "registry:component"
+                  : componentType
+              }
+            >
+              {/* Dynamic preview rendered via iframe for blocks */}
+              {componentType !== "registry:block" && (
+                <iframe
+                  src={`/demo/${slug}`}
+                  className="h-[350px] w-full rounded-md border-0"
+                  title={`${slug} preview`}
+                />
+              )}
+            </ComponentPreview>
+          </PreviewErrorBoundary>
+        </ComponentCodePreview>
+      </div>
+
+      {/* Installation Section */}
+      <h2 className="mt-12 scroll-m-20 border-b pb-2 font-medium text-xl tracking-tight">
+        Installation
+      </h2>
+      <div className="mt-4">
+        <InstallationTabs componentName={slug} />
+      </div>
+
+      {/* API Reference Section */}
+      <h2 className="mt-12 scroll-m-20 border-b pb-2 font-medium text-xl tracking-tight">
+        API Reference
+      </h2>
+
+      <h3 className="mt-8 scroll-m-20 font-medium text-lg tracking-tight">
+        {component.title}
+      </h3>
+
+      <div className="mt-4">
+        <ApiTable
+          data={[
+            {
+              prop: "className",
+              type: "string",
+              default: "—",
+              description: "Additional CSS classes to apply",
+            },
+            {
+              prop: "...props",
+              type: "ComponentProps",
+              default: "—",
+              description: "All other props are passed to the root element",
+            },
+          ]}
+        />
+      </div>
+
+      {/* Navigation */}
+      <ComponentNav currentName={slug} />
+    </>
+  );
+}
diff --git a/apps/www/src/app/docs/layout.tsx b/apps/www/src/app/docs/layout.tsx
new file mode 100644
index 0000000..caf3b6b
--- /dev/null
+++ b/apps/www/src/app/docs/layout.tsx
@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+
+import {
+  MobileSidebarTrigger,
+  RegistrySidebar,
+} from "@/components/registry/registry-sidebar";
+import { SidebarProvider } from "@/components/ui/sidebar";
+import { Toaster } from "@/components/ui/sonner";
+
+export default function DocsLayout({
+  children,
+}: Readonly<{
+  children: ReactNode;
+}>) {
+  return (
+    <SidebarProvider>
+      <MobileSidebarTrigger />
+      <RegistrySidebar />
+      <main className="flex w-full justify-center">
+        <div className="w-full max-w-4xl px-6 py-10 lg:px-10">{children}</div>
+      </main>
+      <Toaster />
+    </SidebarProvider>
+  );
+}
diff --git a/apps/www/src/components/docs/component-preview.tsx b/apps/www/src/components/docs/component-preview.tsx
new file mode 100644
index 0000000..c49c529
--- /dev/null
+++ b/apps/www/src/components/docs/component-preview.tsx
@@ -0,0 +1,51 @@
+"use client";
+
+import type * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+interface ComponentPreviewProps {
+  name: string;
+  type: "registry:component" | "registry:block";
+  children?: React.ReactNode;
+  className?: string;
+}
+
+export function ComponentPreview({
+  name,
+  type,
+  children,
+  className,
+}: ComponentPreviewProps) {
+  const isBlock = type === "registry:block";
+
+  if (isBlock) {
+    return (
+      <div className={cn("w-full", className)}>
+        <iframe
+          src={`/demo/${name}`}
+          className="h-[800px] w-full rounded-md border"
+          title={`${name} preview`}
+        />
+      </div>
+    );
+  }
+
+  // Direct rendering for UI components
+  return (
+    <div
+      className={cn(
+        "flex min-h-[350px] w-full items-center justify-center rounded-md border p-8",
+        className,
+      )}
+    >
+      <div className="w-full max-w-3xl">
+        {children || (
+          <p className="text-center text-muted-foreground">
+            Preview not available
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/www/src/components/docs/index.ts b/apps/www/src/components/docs/index.ts
index 79b85db..dafe10d 100644
--- a/apps/www/src/components/docs/index.ts
+++ b/apps/www/src/components/docs/index.ts
@@ -4,3 +4,5 @@ export { ComponentCodePreview } from "./component-code-preview";
 export { ApiTable } from "./api-table";
 export { ComponentNav } from "./component-nav";
 export { InstallationTabs } from "./installation-tabs";
+export { ComponentPreview } from "./component-preview";
+export { PreviewErrorBoundary } from "./preview-error-boundary";
diff --git a/apps/www/src/components/docs/preview-error-boundary.tsx b/apps/www/src/components/docs/preview-error-boundary.tsx
new file mode 100644
index 0000000..e2e0381
--- /dev/null
+++ b/apps/www/src/components/docs/preview-error-boundary.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
+import { AlertCircle } from "lucide-react";
+import * as React from "react";
+
+interface PreviewErrorBoundaryProps {
+  children: React.ReactNode;
+}
+
+interface PreviewErrorBoundaryState {
+  hasError: boolean;
+  error?: Error;
+}
+
+export class PreviewErrorBoundary extends React.Component<
+  PreviewErrorBoundaryProps,
+  PreviewErrorBoundaryState
+> {
+  constructor(props: PreviewErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error): PreviewErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <Alert variant="destructive">
+          <AlertCircle className="h-4 w-4" />
+          <AlertTitle>Preview Error</AlertTitle>
+          <AlertDescription>
+            Failed to render component preview.
+            {this.state.error && (
+              <pre className="mt-2 text-xs">{this.state.error.message}</pre>
+            )}
+          </AlertDescription>
+        </Alert>
+      );
+    }
+
+    return this.props.children;
+  }
+}
diff --git a/apps/www/src/components/registry/registry-sidebar.tsx b/apps/www/src/components/registry/registry-sidebar.tsx
index 6ff08da..edf4a2c 100644
--- a/apps/www/src/components/registry/registry-sidebar.tsx
+++ b/apps/www/src/components/registry/registry-sidebar.tsx
@@ -189,7 +189,7 @@ export function RegistrySidebar() {
                         >
                           <Link
                             onClick={() => setOpenMobile(false)}
-                            href={`/registry/${item.name}`}
+                            href={`/docs/${item.name}`}
                           >
                             {item.title}
                           </Link>
@@ -227,7 +227,7 @@ export function RegistrySidebar() {
                         >
                           <Link
                             onClick={() => setOpenMobile(false)}
-                            href={`/registry/${item.name}`}
+                            href={`/docs/${item.name}`}
                           >
                             {item.title}
                           </Link>
@@ -264,7 +264,7 @@ export function RegistrySidebar() {
                         >
                           <Link
                             onClick={() => setOpenMobile(false)}
-                            href={`/registry/${item.name}`}
+                            href={`/docs/${item.name}`}
                           >
                             {item.title}
                           </Link>

From e6925f44f8f9ce2d42dcbed22c42c34aee8a4b55 Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 17:51:25 -0500
Subject: [PATCH 05/10] fix: update pnpm-lock.yaml to include MDX dependencies

The lockfile was out of sync with apps/www/package.json after adding
@mdx-js/loader, @mdx-js/react, and @next/mdx dependencies.
---
 pnpm-lock.yaml | 847 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 844 insertions(+), 3 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d6a55af..0c1c335 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -29,6 +29,15 @@ importers:
       '@hookform/resolvers':
         specifier: ^5.2.2
         version: 5.2.2(react-hook-form@7.71.1(react@19.2.4))
+      '@mdx-js/loader':
+        specifier: ^3.1.1
+        version: 3.1.1
+      '@mdx-js/react':
+        specifier: ^3.1.1
+        version: 3.1.1(@types/react@19.2.10)(react@19.2.4)
+      '@next/mdx':
+        specifier: ^16.1.6
+        version: 16.1.6(@mdx-js/loader@3.1.1)(@mdx-js/react@3.1.1(@types/react@19.2.10)(react@19.2.4))
       '@tanstack/react-table':
         specifier: ^8.21.3
         version: 8.21.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -108,9 +117,6 @@ importers:
       '@tailwindcss/postcss':
         specifier: ^4.1.18
         version: 4.1.18
-      '@types/mdx':
-        specifier: ^2.0.13
-        version: 2.0.13
       '@types/node':
         specifier: ^22.19.3
         version: 22.19.7
@@ -706,6 +712,23 @@ packages:
   '@manypkg/get-packages@1.1.3':
     resolution: {integrity: sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==}
 
+  '@mdx-js/loader@3.1.1':
+    resolution: {integrity: sha512-0TTacJyZ9mDmY+VefuthVshaNIyCGZHJG2fMnGaDttCt8HmjUF7SizlHJpaCDoGnN635nK1wpzfpx/Xx5S4WnQ==}
+    peerDependencies:
+      webpack: '>=5'
+    peerDependenciesMeta:
+      webpack:
+        optional: true
+
+  '@mdx-js/mdx@3.1.1':
+    resolution: {integrity: sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==}
+
+  '@mdx-js/react@3.1.1':
+    resolution: {integrity: sha512-f++rKLQgUVYDAtECQ6fn/is15GkEH9+nZPM3MS0RcxVqoTfawHvDlSCH7JbMhAM6uJ32v3eXLvLmLvjGu7PTQw==}
+    peerDependencies:
+      '@types/react': '>=16'
+      react: '>=16'
+
   '@modelcontextprotocol/sdk@1.25.3':
     resolution: {integrity: sha512-vsAMBMERybvYgKbg/l4L1rhS7VXV1c0CtyJg72vwxONVX0l4ZfKVAnZEWTQixJGTzKnELjQ59e4NbdFDALRiAQ==}
     engines: {node: '>=18'}
@@ -723,6 +746,17 @@ packages:
   '@next/env@16.1.6':
     resolution: {integrity: sha512-N1ySLuZjnAtN3kFnwhAwPvZah8RJxKasD7x1f8shFqhncnWZn4JMfg37diLNuoHsLAlrDfM3g4mawVdtAG8XLQ==}
 
+  '@next/mdx@16.1.6':
+    resolution: {integrity: sha512-PT5JR4WPPYOls7WD6xEqUVVI9HDY8kY7XLQsNYB2lSZk5eJSXWu3ECtIYmfR0hZpx8Sg7BKZYKi2+u5OTSEx0w==}
+    peerDependencies:
+      '@mdx-js/loader': '>=0.15.0'
+      '@mdx-js/react': '>=0.15.0'
+    peerDependenciesMeta:
+      '@mdx-js/loader':
+        optional: true
+      '@mdx-js/react':
+        optional: true
+
   '@next/swc-darwin-arm64@16.1.6':
     resolution: {integrity: sha512-wTzYulosJr/6nFnqGW7FrG3jfUUlEf8UjGA0/pyypJl42ExdVgC6xJgcXQ+V8QFn6niSG2Pb8+MIG1mZr2vczw==}
     engines: {node: '>= 10'}
@@ -1679,6 +1713,15 @@ packages:
   '@types/d3-timer@3.0.2':
     resolution: {integrity: sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==}
 
+  '@types/debug@4.1.12':
+    resolution: {integrity: sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==}
+
+  '@types/estree-jsx@1.0.5':
+    resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
+
+  '@types/estree@1.0.8':
+    resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
+
   '@types/hast@3.0.4':
     resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
 
@@ -1688,6 +1731,9 @@ packages:
   '@types/mdx@2.0.13':
     resolution: {integrity: sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw==}
 
+  '@types/ms@2.1.0':
+    resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+
   '@types/node@12.20.55':
     resolution: {integrity: sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==}
 
@@ -1705,6 +1751,9 @@ packages:
   '@types/statuses@2.0.6':
     resolution: {integrity: sha512-xMAgYwceFhRA2zY+XbEA7mxYbA093wdiW8Vu6gZPGWy9cmOyU9XesH1tNcEWsKFd5Vzrqx5T3D38PWx1FIIXkA==}
 
+  '@types/unist@2.0.11':
+    resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
+
   '@types/unist@3.0.3':
     resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
 
@@ -1767,6 +1816,16 @@ packages:
     resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
     engines: {node: '>= 0.6'}
 
+  acorn-jsx@5.3.2:
+    resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  acorn@8.15.0:
+    resolution: {integrity: sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==}
+    engines: {node: '>=0.4.0'}
+    hasBin: true
+
   agent-base@7.1.4:
     resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
     engines: {node: '>= 14'}
@@ -1820,6 +1879,13 @@ packages:
     resolution: {integrity: sha512-6t10qk83GOG8p0vKmaCr8eiilZwO171AvbROMtvvNiwrTly62t+7XkA8RdIIVbpMhCASAsxgAzdRSwh6nw/5Dg==}
     engines: {node: '>=4'}
 
+  astring@1.9.0:
+    resolution: {integrity: sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==}
+    hasBin: true
+
+  bail@2.0.2:
+    resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
+
   baseline-browser-mapping@2.9.19:
     resolution: {integrity: sha512-ipDqC8FrAl/76p2SSWKSI+H9tFwm7vYqXQrItCuiVPt26Km0jS+NzSsBWAaBusvSbQcfJG+JitdMm+wZAgTYqg==}
     hasBin: true
@@ -1877,6 +1943,12 @@ packages:
   character-entities-legacy@3.0.0:
     resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==}
 
+  character-entities@2.0.2:
+    resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
+
+  character-reference-invalid@2.0.1:
+    resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
+
   chardet@2.1.1:
     resolution: {integrity: sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ==}
 
@@ -1919,6 +1991,9 @@ packages:
   code-block-writer@13.0.3:
     resolution: {integrity: sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg==}
 
+  collapse-white-space@2.1.0:
+    resolution: {integrity: sha512-loKTxY1zCOuG4j9f6EPnuyyYkf58RnhhWTvRoZEokgB+WbdXehfjFviyOVYkqzEWz1Q5kRiZdBYS5SwxbQYwzw==}
+
   color-convert@2.0.1:
     resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
     engines: {node: '>=7.0.0'}
@@ -2051,6 +2126,9 @@ packages:
   decimal.js-light@2.5.1:
     resolution: {integrity: sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg==}
 
+  decode-named-character-reference@1.3.0:
+    resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
+
   dedent@1.7.1:
     resolution: {integrity: sha512-9JmrhGZpOlEgOLdQgSm0zxFaYoQon408V1v49aqTWuXENVlnCuY9JBZcXZiCsZQWDjTm5Qf/nIvAy77mXDAjEg==}
     peerDependencies:
@@ -2176,6 +2254,12 @@ packages:
     resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==}
     engines: {node: '>= 0.4'}
 
+  esast-util-from-estree@2.0.0:
+    resolution: {integrity: sha512-4CyanoAudUSBAn5K13H4JhsMH6L9ZP7XbLVe/dKybkxMO7eDyLsT8UHl9TRNrU2Gr9nz+FovfSIjuXWJ81uVwQ==}
+
+  esast-util-from-js@2.0.1:
+    resolution: {integrity: sha512-8Ja+rNJ0Lt56Pcf3TAmpBZjmx8ZcK5Ts4cAzIOjsjevg9oSXJnl6SUQ2EevU8tv3h6ZLWmoKL5H4fgWvdvfETw==}
+
   escalade@3.2.0:
     resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
     engines: {node: '>=6'}
@@ -2188,6 +2272,27 @@ packages:
     engines: {node: '>=4'}
     hasBin: true
 
+  estree-util-attach-comments@3.0.0:
+    resolution: {integrity: sha512-cKUwm/HUcTDsYh/9FgnuFqpfquUbwIqwKM26BVCGDPVgvaCl/nDCCjUfiLlx6lsEZ3Z4RFxNbOQ60pkaEwFxGw==}
+
+  estree-util-build-jsx@3.0.1:
+    resolution: {integrity: sha512-8U5eiL6BTrPxp/CHbs2yMgP8ftMhR5ww1eIKoWRMlqvltHF8fZn5LRDvTKuxD3DUn+shRbLGqXemcP51oFCsGQ==}
+
+  estree-util-is-identifier-name@3.0.0:
+    resolution: {integrity: sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==}
+
+  estree-util-scope@1.0.0:
+    resolution: {integrity: sha512-2CAASclonf+JFWBNJPndcOpA8EMJwa0Q8LUFJEKqXLW6+qBvbFZuF5gItbQOs/umBUkjviCSDCbBwU2cXbmrhQ==}
+
+  estree-util-to-js@2.0.0:
+    resolution: {integrity: sha512-WDF+xj5rRWmD5tj6bIqRi6CkLIXbbNQUcxQHzGysQzvHmdYG2G7p/Tf0J0gpxGgkeMZNTIjT/AoSvC9Xehcgdg==}
+
+  estree-util-visit@2.0.0:
+    resolution: {integrity: sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==}
+
+  estree-walker@3.0.3:
+    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
+
   etag@1.8.1:
     resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==}
     engines: {node: '>= 0.6'}
@@ -2221,6 +2326,9 @@ packages:
     resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
     engines: {node: '>= 18'}
 
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
   extendable-error@0.1.7:
     resolution: {integrity: sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg==}
 
@@ -2366,9 +2474,15 @@ packages:
     resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
     engines: {node: '>= 0.4'}
 
+  hast-util-to-estree@3.1.3:
+    resolution: {integrity: sha512-48+B/rJWAp0jamNbAAf9M7Uf//UVqAoMmgXhBdxTDJLGKY+LRnZ99qcG+Qjl5HfMpYNzS5v4EAwVEF34LeAj7w==}
+
   hast-util-to-html@9.0.5:
     resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==}
 
+  hast-util-to-jsx-runtime@2.3.6:
+    resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
+
   hast-util-whitespace@3.0.0:
     resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
 
@@ -2417,6 +2531,9 @@ packages:
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
+  inline-style-parser@0.2.7:
+    resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==}
+
   input-otp@1.4.2:
     resolution: {integrity: sha512-l3jWwYNvrEa6NTCt7BECfCm48GvwuZzkoeG3gBL2w4CHeOXW3eKFmf9UNYkNfYc3mxMrthMnxjIE07MT0zLBQA==}
     peerDependencies:
@@ -2431,9 +2548,18 @@ packages:
     resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
     engines: {node: '>= 0.10'}
 
+  is-alphabetical@2.0.1:
+    resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
+
+  is-alphanumerical@2.0.1:
+    resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==}
+
   is-arrayish@0.2.1:
     resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==}
 
+  is-decimal@2.0.1:
+    resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==}
+
   is-docker@3.0.0:
     resolution: {integrity: sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
@@ -2451,6 +2577,9 @@ packages:
     resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
     engines: {node: '>=0.10.0'}
 
+  is-hexadecimal@2.0.1:
+    resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==}
+
   is-in-ssh@1.0.0:
     resolution: {integrity: sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==}
     engines: {node: '>=20'}
@@ -2713,6 +2842,9 @@ packages:
     resolution: {integrity: sha512-i24m8rpwhmPIS4zscNzK6MSEhk0DUWa/8iYQWxhffV8jkI4Phvs3F+quL5xvS0gdQR0FyTCMMH33Y78dDTzzIw==}
     engines: {node: '>=18'}
 
+  longest-streak@3.1.0:
+    resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==}
+
   loose-envify@1.4.0:
     resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
     hasBin: true
@@ -2728,13 +2860,41 @@ packages:
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
+  markdown-extensions@2.0.0:
+    resolution: {integrity: sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==}
+    engines: {node: '>=16'}
+
   math-intrinsics@1.1.0:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
 
+  mdast-util-from-markdown@2.0.2:
+    resolution: {integrity: sha512-uZhTV/8NBuw0WHkPTrCqDOl0zVe1BIng5ZtHoDk49ME1qqcjYmmLmOf0gELgcRMxN4w2iuIeVso5/6QymSrgmA==}
+
+  mdast-util-mdx-expression@2.0.1:
+    resolution: {integrity: sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==}
+
+  mdast-util-mdx-jsx@3.2.0:
+    resolution: {integrity: sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==}
+
+  mdast-util-mdx@3.0.0:
+    resolution: {integrity: sha512-JfbYLAW7XnYTTbUsmpu0kdBUVe+yKVJZBItEjwyYJiDJuZ9w4eeaqks4HQO+R7objWgS2ymV60GYpI14Ug554w==}
+
+  mdast-util-mdxjs-esm@2.0.1:
+    resolution: {integrity: sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==}
+
+  mdast-util-phrasing@4.1.0:
+    resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
+
   mdast-util-to-hast@13.2.1:
     resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==}
 
+  mdast-util-to-markdown@2.1.2:
+    resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==}
+
+  mdast-util-to-string@4.0.0:
+    resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
+
   media-typer@1.1.0:
     resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
     engines: {node: '>= 0.8'}
@@ -2750,21 +2910,90 @@ packages:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
 
+  micromark-core-commonmark@2.0.3:
+    resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
+
+  micromark-extension-mdx-expression@3.0.1:
+    resolution: {integrity: sha512-dD/ADLJ1AeMvSAKBwO22zG22N4ybhe7kFIZ3LsDI0GlsNr2A3KYxb0LdC1u5rj4Nw+CHKY0RVdnHX8vj8ejm4Q==}
+
+  micromark-extension-mdx-jsx@3.0.2:
+    resolution: {integrity: sha512-e5+q1DjMh62LZAJOnDraSSbDMvGJ8x3cbjygy2qFEi7HCeUT4BDKCvMozPozcD6WmOt6sVvYDNBKhFSz3kjOVQ==}
+
+  micromark-extension-mdx-md@2.0.0:
+    resolution: {integrity: sha512-EpAiszsB3blw4Rpba7xTOUptcFeBFi+6PY8VnJ2hhimH+vCQDirWgsMpz7w1XcZE7LVrSAUGb9VJpG9ghlYvYQ==}
+
+  micromark-extension-mdxjs-esm@3.0.0:
+    resolution: {integrity: sha512-DJFl4ZqkErRpq/dAPyeWp15tGrcrrJho1hKK5uBS70BCtfrIFg81sqcTVu3Ta+KD1Tk5vAtBNElWxtAa+m8K9A==}
+
+  micromark-extension-mdxjs@3.0.0:
+    resolution: {integrity: sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==}
+
+  micromark-factory-destination@2.0.1:
+    resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
+
+  micromark-factory-label@2.0.1:
+    resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
+
+  micromark-factory-mdx-expression@2.0.3:
+    resolution: {integrity: sha512-kQnEtA3vzucU2BkrIa8/VaSAsP+EJ3CKOvhMuJgOEGg9KDC6OAY6nSnNDVRiVNRqj7Y4SlSzcStaH/5jge8JdQ==}
+
+  micromark-factory-space@2.0.1:
+    resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==}
+
+  micromark-factory-title@2.0.1:
+    resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
+
+  micromark-factory-whitespace@2.0.1:
+    resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
+
   micromark-util-character@2.1.1:
     resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
 
+  micromark-util-chunked@2.0.1:
+    resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
+
+  micromark-util-classify-character@2.0.1:
+    resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
+
+  micromark-util-combine-extensions@2.0.1:
+    resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
+
+  micromark-util-decode-string@2.0.1:
+    resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==}
+
   micromark-util-encode@2.0.1:
     resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
 
+  micromark-util-events-to-acorn@2.0.3:
+    resolution: {integrity: sha512-jmsiEIiZ1n7X1Rr5k8wVExBQCg5jy4UXVADItHmNk1zkwEVhBuIUKRu3fqv+hs4nxLISi2DQGlqIOGiFxgbfHg==}
+
+  micromark-util-html-tag-name@2.0.1:
+    resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
+
+  micromark-util-normalize-identifier@2.0.1:
+    resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
+
+  micromark-util-resolve-all@2.0.1:
+    resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
+
   micromark-util-sanitize-uri@2.0.1:
     resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
 
+  micromark-util-subtokenize@2.1.0:
+    resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
+
   micromark-util-symbol@2.0.1:
     resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
 
   micromark-util-types@2.0.2:
     resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
 
+  micromark@4.0.2:
+    resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
+
   micromatch@4.0.8:
     resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
     engines: {node: '>=8.6'}
@@ -2946,6 +3175,9 @@ packages:
     resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
     engines: {node: '>=6'}
 
+  parse-entities@4.0.2:
+    resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
+
   parse-json@5.2.0:
     resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==}
     engines: {node: '>=8'}
@@ -3165,6 +3397,20 @@ packages:
       react: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
       react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
 
+  recma-build-jsx@1.0.0:
+    resolution: {integrity: sha512-8GtdyqaBcDfva+GUKDr3nev3VpKAhup1+RvkMvUxURHpW7QyIvk9F5wz7Vzo06CEMSilw6uArgRqhpiUcWp8ew==}
+
+  recma-jsx@1.0.1:
+    resolution: {integrity: sha512-huSIy7VU2Z5OLv6oFLosQGGDqPqdO1iq6bWNAdhzMxSJP7RAso4fCZ1cKu8j9YHCZf3TPrq4dw3okhrylgcd7w==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  recma-parse@1.0.0:
+    resolution: {integrity: sha512-OYLsIGBB5Y5wjnSnQW6t3Xg7q3fQ7FWbw/vcXtORTnyaSFscOtABg+7Pnz6YZ6c27fG1/aN8CjfwoUEUIdwqWQ==}
+
+  recma-stringify@1.0.0:
+    resolution: {integrity: sha512-cjwII1MdIIVloKvC9ErQ+OgAtwHBmcZ0Bg4ciz78FtbT8In39aAYbaA7zvxQ61xVMSPE8WxhLwLbhif4Js2C+g==}
+
   regex-recursion@6.0.2:
     resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==}
 
@@ -3174,6 +3420,18 @@ packages:
   regex@6.1.0:
     resolution: {integrity: sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==}
 
+  rehype-recma@1.0.0:
+    resolution: {integrity: sha512-lqA4rGUf1JmacCNWWZx0Wv1dHqMwxzsDWYMTowuplHF3xH0N/MmrZ/G3BDZnzAkRmxDadujCjaKM2hqYdCBOGw==}
+
+  remark-mdx@3.1.1:
+    resolution: {integrity: sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==}
+
+  remark-parse@11.0.0:
+    resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==}
+
+  remark-rehype@11.1.2:
+    resolution: {integrity: sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==}
+
   require-directory@2.1.1:
     resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
     engines: {node: '>=0.10.0'}
@@ -3301,6 +3559,10 @@ packages:
     resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
     engines: {node: '>=0.10.0'}
 
+  source-map@0.7.6:
+    resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==}
+    engines: {node: '>= 12'}
+
   space-separated-tokens@2.0.2:
     resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
 
@@ -3356,6 +3618,12 @@ packages:
     resolution: {integrity: sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw==}
     engines: {node: '>=18'}
 
+  style-to-js@1.1.21:
+    resolution: {integrity: sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==}
+
+  style-to-object@1.0.14:
+    resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==}
+
   styled-jsx@5.1.6:
     resolution: {integrity: sha512-qSVyDTeMotdvQYoHWLNGwRFJHC+i+ZvdBRYosOFgC+Wg1vx4frN2/RG/NA7SYqqvKNLf39P2LSRA2pu6n0XYZA==}
     engines: {node: '>= 12.0.0'}
@@ -3416,6 +3684,9 @@ packages:
   trim-lines@3.0.1:
     resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
 
+  trough@2.2.0:
+    resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
+
   ts-morph@26.0.0:
     resolution: {integrity: sha512-ztMO++owQnz8c/gIENcM9XfCEzgoGphTv+nKpYNM1bgsdOVC/jRZuEBf6N+mLLDNg68Kl+GgUZfOySaRiG1/Ug==}
 
@@ -3483,9 +3754,15 @@ packages:
     resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
     engines: {node: '>=18'}
 
+  unified@11.0.5:
+    resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
+
   unist-util-is@6.0.1:
     resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
 
+  unist-util-position-from-estree@2.0.0:
+    resolution: {integrity: sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==}
+
   unist-util-position@5.0.0:
     resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==}
 
@@ -4233,6 +4510,49 @@ snapshots:
       globby: 11.1.0
       read-yaml-file: 1.1.0
 
+  '@mdx-js/loader@3.1.1':
+    dependencies:
+      '@mdx-js/mdx': 3.1.1
+      source-map: 0.7.6
+    transitivePeerDependencies:
+      - supports-color
+
+  '@mdx-js/mdx@3.1.1':
+    dependencies:
+      '@types/estree': 1.0.8
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdx': 2.0.13
+      acorn: 8.15.0
+      collapse-white-space: 2.1.0
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      estree-util-scope: 1.0.0
+      estree-walker: 3.0.3
+      hast-util-to-jsx-runtime: 2.3.6
+      markdown-extensions: 2.0.0
+      recma-build-jsx: 1.0.0
+      recma-jsx: 1.0.1(acorn@8.15.0)
+      recma-stringify: 1.0.0
+      rehype-recma: 1.0.0
+      remark-mdx: 3.1.1
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      source-map: 0.7.6
+      unified: 11.0.5
+      unist-util-position-from-estree: 2.0.0
+      unist-util-stringify-position: 4.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@mdx-js/react@3.1.1(@types/react@19.2.10)(react@19.2.4)':
+    dependencies:
+      '@types/mdx': 2.0.13
+      '@types/react': 19.2.10
+      react: 19.2.4
+
   '@modelcontextprotocol/sdk@1.25.3(hono@4.11.7)(zod@3.25.76)':
     dependencies:
       '@hono/node-server': 1.19.9(hono@4.11.7)
@@ -4266,6 +4586,13 @@ snapshots:
 
   '@next/env@16.1.6': {}
 
+  '@next/mdx@16.1.6(@mdx-js/loader@3.1.1)(@mdx-js/react@3.1.1(@types/react@19.2.10)(react@19.2.4))':
+    dependencies:
+      source-map: 0.7.6
+    optionalDependencies:
+      '@mdx-js/loader': 3.1.1
+      '@mdx-js/react': 3.1.1(@types/react@19.2.10)(react@19.2.4)
+
   '@next/swc-darwin-arm64@16.1.6':
     optional: true
 
@@ -5232,6 +5559,16 @@ snapshots:
 
   '@types/d3-timer@3.0.2': {}
 
+  '@types/debug@4.1.12':
+    dependencies:
+      '@types/ms': 2.1.0
+
+  '@types/estree-jsx@1.0.5':
+    dependencies:
+      '@types/estree': 1.0.8
+
+  '@types/estree@1.0.8': {}
+
   '@types/hast@3.0.4':
     dependencies:
       '@types/unist': 3.0.3
@@ -5242,6 +5579,8 @@ snapshots:
 
   '@types/mdx@2.0.13': {}
 
+  '@types/ms@2.1.0': {}
+
   '@types/node@12.20.55': {}
 
   '@types/node@22.19.7':
@@ -5258,6 +5597,8 @@ snapshots:
 
   '@types/statuses@2.0.6': {}
 
+  '@types/unist@2.0.11': {}
+
   '@types/unist@3.0.3': {}
 
   '@types/validate-npm-package-name@4.0.2': {}
@@ -5279,6 +5620,12 @@ snapshots:
       mime-types: 3.0.2
       negotiator: 1.0.0
 
+  acorn-jsx@5.3.2(acorn@8.15.0):
+    dependencies:
+      acorn: 8.15.0
+
+  acorn@8.15.0: {}
+
   agent-base@7.1.4: {}
 
   ajv-formats@3.0.1(ajv@8.17.1):
@@ -5320,6 +5667,10 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
+  astring@1.9.0: {}
+
+  bail@2.0.2: {}
+
   baseline-browser-mapping@2.9.19: {}
 
   better-path-resolve@1.0.0:
@@ -5380,6 +5731,10 @@ snapshots:
 
   character-entities-legacy@3.0.0: {}
 
+  character-entities@2.0.2: {}
+
+  character-reference-invalid@2.0.1: {}
+
   chardet@2.1.1: {}
 
   ci-info@3.9.0: {}
@@ -5420,6 +5775,8 @@ snapshots:
 
   code-block-writer@13.0.3: {}
 
+  collapse-white-space@2.1.0: {}
+
   color-convert@2.0.1:
     dependencies:
       color-name: 1.1.4
@@ -5518,6 +5875,10 @@ snapshots:
 
   decimal.js-light@2.5.1: {}
 
+  decode-named-character-reference@1.3.0:
+    dependencies:
+      character-entities: 2.0.2
+
   dedent@1.7.1: {}
 
   deepmerge@4.3.1: {}
@@ -5617,12 +5978,59 @@ snapshots:
     dependencies:
       es-errors: 1.3.0
 
+  esast-util-from-estree@2.0.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      devlop: 1.1.0
+      estree-util-visit: 2.0.0
+      unist-util-position-from-estree: 2.0.0
+
+  esast-util-from-js@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      acorn: 8.15.0
+      esast-util-from-estree: 2.0.0
+      vfile-message: 4.0.3
+
   escalade@3.2.0: {}
 
   escape-html@1.0.3: {}
 
   esprima@4.0.1: {}
 
+  estree-util-attach-comments@3.0.0:
+    dependencies:
+      '@types/estree': 1.0.8
+
+  estree-util-build-jsx@3.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      estree-walker: 3.0.3
+
+  estree-util-is-identifier-name@3.0.0: {}
+
+  estree-util-scope@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.8
+      devlop: 1.1.0
+
+  estree-util-to-js@2.0.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      astring: 1.9.0
+      source-map: 0.7.6
+
+  estree-util-visit@2.0.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/unist': 3.0.3
+
+  estree-walker@3.0.3:
+    dependencies:
+      '@types/estree': 1.0.8
+
   etag@1.8.1: {}
 
   eventemitter3@4.0.7: {}
@@ -5697,6 +6105,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  extend@3.0.2: {}
+
   extendable-error@0.1.7: {}
 
   fast-deep-equal@3.1.3: {}
@@ -5842,6 +6252,27 @@ snapshots:
     dependencies:
       function-bind: 1.1.2
 
+  hast-util-to-estree@3.1.3:
+    dependencies:
+      '@types/estree': 1.0.8
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-attach-comments: 3.0.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.1.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      zwitch: 2.0.4
+    transitivePeerDependencies:
+      - supports-color
+
   hast-util-to-html@9.0.5:
     dependencies:
       '@types/hast': 3.0.4
@@ -5856,6 +6287,26 @@ snapshots:
       stringify-entities: 4.0.4
       zwitch: 2.0.4
 
+  hast-util-to-jsx-runtime@2.3.6:
+    dependencies:
+      '@types/estree': 1.0.8
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.1.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
   hast-util-whitespace@3.0.0:
     dependencies:
       '@types/hast': 3.0.4
@@ -5900,6 +6351,8 @@ snapshots:
 
   inherits@2.0.4: {}
 
+  inline-style-parser@0.2.7: {}
+
   input-otp@1.4.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
       react: 19.2.4
@@ -5909,8 +6362,17 @@ snapshots:
 
   ipaddr.js@1.9.1: {}
 
+  is-alphabetical@2.0.1: {}
+
+  is-alphanumerical@2.0.1:
+    dependencies:
+      is-alphabetical: 2.0.1
+      is-decimal: 2.0.1
+
   is-arrayish@0.2.1: {}
 
+  is-decimal@2.0.1: {}
+
   is-docker@3.0.0: {}
 
   is-extglob@2.1.1: {}
@@ -5921,6 +6383,8 @@ snapshots:
     dependencies:
       is-extglob: 2.1.1
 
+  is-hexadecimal@2.0.1: {}
+
   is-in-ssh@1.0.0: {}
 
   is-inside-container@1.0.0:
@@ -6109,6 +6573,8 @@ snapshots:
       chalk: 5.6.2
       is-unicode-supported: 1.3.0
 
+  longest-streak@3.1.0: {}
+
   loose-envify@1.4.0:
     dependencies:
       js-tokens: 4.0.0
@@ -6125,8 +6591,81 @@ snapshots:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  markdown-extensions@2.0.0: {}
+
   math-intrinsics@1.1.0: {}
 
+  mdast-util-from-markdown@2.0.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      mdast-util-to-string: 4.0.0
+      micromark: 4.0.2
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-decode-string: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-stringify-position: 4.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-expression@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.2
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-jsx@3.2.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.2
+      mdast-util-to-markdown: 2.1.2
+      parse-entities: 4.0.2
+      stringify-entities: 4.0.4
+      unist-util-stringify-position: 4.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx@3.0.0:
+    dependencies:
+      mdast-util-from-markdown: 2.0.2
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdxjs-esm@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.2
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-phrasing@4.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      unist-util-is: 6.0.1
+
   mdast-util-to-hast@13.2.1:
     dependencies:
       '@types/hast': 3.0.4
@@ -6139,6 +6678,22 @@ snapshots:
       unist-util-visit: 5.1.0
       vfile: 6.0.3
 
+  mdast-util-to-markdown@2.1.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      longest-streak: 3.1.0
+      mdast-util-phrasing: 4.1.0
+      mdast-util-to-string: 4.0.0
+      micromark-util-classify-character: 2.0.1
+      micromark-util-decode-string: 2.0.1
+      unist-util-visit: 5.1.0
+      zwitch: 2.0.4
+
+  mdast-util-to-string@4.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+
   media-typer@1.1.0: {}
 
   merge-descriptors@2.0.0: {}
@@ -6147,23 +6702,212 @@ snapshots:
 
   merge2@1.4.1: {}
 
+  micromark-core-commonmark@2.0.3:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-factory-destination: 2.0.1
+      micromark-factory-label: 2.0.1
+      micromark-factory-space: 2.0.1
+      micromark-factory-title: 2.0.1
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-html-tag-name: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-mdx-expression@3.0.1:
+    dependencies:
+      '@types/estree': 1.0.8
+      devlop: 1.1.0
+      micromark-factory-mdx-expression: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-mdx-jsx@3.0.2:
+    dependencies:
+      '@types/estree': 1.0.8
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      micromark-factory-mdx-expression: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      vfile-message: 4.0.3
+
+  micromark-extension-mdx-md@2.0.0:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-extension-mdxjs-esm@3.0.0:
+    dependencies:
+      '@types/estree': 1.0.8
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-position-from-estree: 2.0.0
+      vfile-message: 4.0.3
+
+  micromark-extension-mdxjs@3.0.0:
+    dependencies:
+      acorn: 8.15.0
+      acorn-jsx: 5.3.2(acorn@8.15.0)
+      micromark-extension-mdx-expression: 3.0.1
+      micromark-extension-mdx-jsx: 3.0.2
+      micromark-extension-mdx-md: 2.0.0
+      micromark-extension-mdxjs-esm: 3.0.0
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-destination@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-label@2.0.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-mdx-expression@2.0.3:
+    dependencies:
+      '@types/estree': 1.0.8
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-events-to-acorn: 2.0.3
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-position-from-estree: 2.0.0
+      vfile-message: 4.0.3
+
+  micromark-factory-space@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-title@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-whitespace@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
   micromark-util-character@2.1.1:
     dependencies:
       micromark-util-symbol: 2.0.1
       micromark-util-types: 2.0.2
 
+  micromark-util-chunked@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-classify-character@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-combine-extensions@2.0.1:
+    dependencies:
+      micromark-util-chunked: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-decode-string@2.0.1:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      micromark-util-character: 2.1.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-symbol: 2.0.1
+
   micromark-util-encode@2.0.1: {}
 
+  micromark-util-events-to-acorn@2.0.3:
+    dependencies:
+      '@types/estree': 1.0.8
+      '@types/unist': 3.0.3
+      devlop: 1.1.0
+      estree-util-visit: 2.0.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      vfile-message: 4.0.3
+
+  micromark-util-html-tag-name@2.0.1: {}
+
+  micromark-util-normalize-identifier@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-resolve-all@2.0.1:
+    dependencies:
+      micromark-util-types: 2.0.2
+
   micromark-util-sanitize-uri@2.0.1:
     dependencies:
       micromark-util-character: 2.1.1
       micromark-util-encode: 2.0.1
       micromark-util-symbol: 2.0.1
 
+  micromark-util-subtokenize@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
   micromark-util-symbol@2.0.1: {}
 
   micromark-util-types@2.0.2: {}
 
+  micromark@4.0.2:
+    dependencies:
+      '@types/debug': 4.1.12
+      debug: 4.4.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-encode: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
   micromatch@4.0.8:
     dependencies:
       braces: 3.0.3
@@ -6349,6 +7093,16 @@ snapshots:
     dependencies:
       callsites: 3.1.0
 
+  parse-entities@4.0.2:
+    dependencies:
+      '@types/unist': 2.0.11
+      character-entities-legacy: 3.0.0
+      character-reference-invalid: 2.0.1
+      decode-named-character-reference: 1.3.0
+      is-alphanumerical: 2.0.1
+      is-decimal: 2.0.1
+      is-hexadecimal: 2.0.1
+
   parse-json@5.2.0:
     dependencies:
       '@babel/code-frame': 7.28.6
@@ -6610,6 +7364,35 @@ snapshots:
       tiny-invariant: 1.3.3
       victory-vendor: 36.9.2
 
+  recma-build-jsx@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.8
+      estree-util-build-jsx: 3.0.1
+      vfile: 6.0.3
+
+  recma-jsx@1.0.1(acorn@8.15.0):
+    dependencies:
+      acorn: 8.15.0
+      acorn-jsx: 5.3.2(acorn@8.15.0)
+      estree-util-to-js: 2.0.0
+      recma-parse: 1.0.0
+      recma-stringify: 1.0.0
+      unified: 11.0.5
+
+  recma-parse@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.8
+      esast-util-from-js: 2.0.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  recma-stringify@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.8
+      estree-util-to-js: 2.0.0
+      unified: 11.0.5
+      vfile: 6.0.3
+
   regex-recursion@6.0.2:
     dependencies:
       regex-utilities: 2.3.0
@@ -6620,6 +7403,38 @@ snapshots:
     dependencies:
       regex-utilities: 2.3.0
 
+  rehype-recma@1.0.0:
+    dependencies:
+      '@types/estree': 1.0.8
+      '@types/hast': 3.0.4
+      hast-util-to-estree: 3.1.3
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-mdx@3.1.1:
+    dependencies:
+      mdast-util-mdx: 3.0.0
+      micromark-extension-mdxjs: 3.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-parse@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.2
+      micromark-util-types: 2.0.2
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-rehype@11.1.2:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      mdast-util-to-hast: 13.2.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
   require-directory@2.1.1: {}
 
   require-from-string@2.0.2: {}
@@ -6826,6 +7641,8 @@ snapshots:
 
   source-map@0.6.1: {}
 
+  source-map@0.7.6: {}
+
   space-separated-tokens@2.0.2: {}
 
   spawndamnit@3.0.1:
@@ -6878,6 +7695,14 @@ snapshots:
 
   strip-final-newline@4.0.0: {}
 
+  style-to-js@1.1.21:
+    dependencies:
+      style-to-object: 1.0.14
+
+  style-to-object@1.0.14:
+    dependencies:
+      inline-style-parser: 0.2.7
+
   styled-jsx@5.1.6(@babel/core@7.28.6)(react@19.2.4):
     dependencies:
       client-only: 0.0.1
@@ -6917,6 +7742,8 @@ snapshots:
 
   trim-lines@3.0.1: {}
 
+  trough@2.2.0: {}
+
   ts-morph@26.0.0:
     dependencies:
       '@ts-morph/common': 0.27.0
@@ -6975,10 +7802,24 @@ snapshots:
 
   unicorn-magic@0.3.0: {}
 
+  unified@11.0.5:
+    dependencies:
+      '@types/unist': 3.0.3
+      bail: 2.0.2
+      devlop: 1.1.0
+      extend: 3.0.2
+      is-plain-obj: 4.1.0
+      trough: 2.2.0
+      vfile: 6.0.3
+
   unist-util-is@6.0.1:
     dependencies:
       '@types/unist': 3.0.3
 
+  unist-util-position-from-estree@2.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
   unist-util-position@5.0.0:
     dependencies:
       '@types/unist': 3.0.3

From a19a167d77cd9b82d30394a23a70dc0c16625865 Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 18:01:28 -0500
Subject: [PATCH 06/10] fix(www): add explicit type annotations to MDX
 components

Replace implicit types with explicit React.ReactNode annotations
for all MDX component overrides to improve type safety.
---
 apps/www/src/mdx-components.tsx | 39 +++++++++++++++++++--------------
 1 file changed, 22 insertions(+), 17 deletions(-)

diff --git a/apps/www/src/mdx-components.tsx b/apps/www/src/mdx-components.tsx
index 45f40eb..c7300b9 100644
--- a/apps/www/src/mdx-components.tsx
+++ b/apps/www/src/mdx-components.tsx
@@ -1,36 +1,41 @@
-import type { MDXComponents } from "mdx/types";
+import type * as React from "react";
 
 // Import documentation components (created in Phase 2)
 // import { ComponentCodePreview } from "@/components/docs/component-code-preview"
 // import { ApiTable } from "@/components/docs/api-table"
 
+type MDXComponents = Record<
+  string,
+  React.ComponentType<{ children?: React.ReactNode; [key: string]: unknown }>
+>;
+
 export function useMDXComponents(components: MDXComponents): MDXComponents {
   return {
     // Override default elements with custom styling
-    h1: ({ children }) => (
+    h1: ({ children }: { children?: React.ReactNode }) => (
       <h1 className="scroll-m-20 font-semibold text-3xl tracking-tight">
         {children}
       </h1>
     ),
-    h2: ({ children }) => (
+    h2: ({ children }: { children?: React.ReactNode }) => (
       <h2 className="mt-12 scroll-m-20 border-b pb-2 font-medium text-xl tracking-tight first:mt-0">
         {children}
       </h2>
     ),
-    h3: ({ children }) => (
+    h3: ({ children }: { children?: React.ReactNode }) => (
       <h3 className="mt-8 scroll-m-20 font-medium text-lg tracking-tight">
         {children}
       </h3>
     ),
-    h4: ({ children }) => (
+    h4: ({ children }: { children?: React.ReactNode }) => (
       <h4 className="mt-6 scroll-m-20 font-medium text-base tracking-tight">
         {children}
       </h4>
     ),
-    p: ({ children }) => (
+    p: ({ children }: { children?: React.ReactNode }) => (
       <p className="leading-7 [&:not(:first-child)]:mt-6">{children}</p>
     ),
-    a: ({ children, href }) => (
+    a: ({ children, href }: { children?: React.ReactNode; href?: string }) => (
       <a
         href={href}
         className="font-medium text-primary underline underline-offset-4"
@@ -38,43 +43,43 @@ export function useMDXComponents(components: MDXComponents): MDXComponents {
         {children}
       </a>
     ),
-    ul: ({ children }) => (
+    ul: ({ children }: { children?: React.ReactNode }) => (
       <ul className="my-6 ml-6 list-disc [&>li]:mt-2">{children}</ul>
     ),
-    ol: ({ children }) => (
+    ol: ({ children }: { children?: React.ReactNode }) => (
       <ol className="my-6 ml-6 list-decimal [&>li]:mt-2">{children}</ol>
     ),
-    li: ({ children }) => <li>{children}</li>,
-    blockquote: ({ children }) => (
+    li: ({ children }: { children?: React.ReactNode }) => <li>{children}</li>,
+    blockquote: ({ children }: { children?: React.ReactNode }) => (
       <blockquote className="mt-6 border-l-2 pl-6 italic">
         {children}
       </blockquote>
     ),
     hr: () => <hr className="my-4 md:my-8" />,
-    table: ({ children }) => (
+    table: ({ children }: { children?: React.ReactNode }) => (
       <div className="my-6 w-full overflow-y-auto">
         <table className="w-full">{children}</table>
       </div>
     ),
-    tr: ({ children }) => (
+    tr: ({ children }: { children?: React.ReactNode }) => (
       <tr className="m-0 border-t p-0 even:bg-muted">{children}</tr>
     ),
-    th: ({ children }) => (
+    th: ({ children }: { children?: React.ReactNode }) => (
       <th className="border px-4 py-2 text-left font-bold [&[align=center]]:text-center [&[align=right]]:text-right">
         {children}
       </th>
     ),
-    td: ({ children }) => (
+    td: ({ children }: { children?: React.ReactNode }) => (
       <td className="border px-4 py-2 text-left [&[align=center]]:text-center [&[align=right]]:text-right">
         {children}
       </td>
     ),
-    pre: ({ children }) => (
+    pre: ({ children }: { children?: React.ReactNode }) => (
       <pre className="mt-6 mb-4 overflow-x-auto rounded-lg border bg-muted px-4 py-4">
         {children}
       </pre>
     ),
-    code: ({ children }) => (
+    code: ({ children }: { children?: React.ReactNode }) => (
       <code className="relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm">
         {children}
       </code>

From 19a99a1b5af0c184f17619e2a37f9df46dae3726 Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 18:14:56 -0500
Subject: [PATCH 07/10] fix(www): resolve documentation system bugs and improve
 robustness

- Fix sidebar active state to match /docs/:slug route pattern
- Fix table overflow direction (use overflow-x-auto for horizontal scroll)
- Fix API table default value check using nullish coalescing
- Fix component-nav next button bounds check to handle missing items
- Add division-by-zero guard in usage-meter components
- Add error handling for clipboard API in code copy functionality
- Add "use client" directive to ComponentCodePreview
- Use SupportedLanguage type instead of BundledLanguage for consistency
- Add dynamicParams=false and try-catch for proper 404 handling
- Fix tab indicator styling with group-data-[state=active]
- Update ADR to clarify Decision 6 supersedes Decision 4
- Fix font class name in tokens page (font-inter)
---
 .../005-component-documentation-strategy.md   | 18 +++++++----
 .../implement-documentation-redesign.md       |  1 +
 apps/www/src/app/(registry)/tokens/page.tsx   |  2 +-
 apps/www/src/app/docs/[slug]/page.tsx         | 32 +++++++++++++------
 apps/www/src/components/docs/api-table.tsx    |  2 +-
 .../components/docs/client-code-wrapper.tsx   | 11 +++++--
 .../www/src/components/docs/code-renderer.tsx |  5 ++-
 .../docs/component-code-preview.tsx           |  8 +++--
 .../www/src/components/docs/component-nav.tsx |  5 ++-
 .../components/registry/registry-sidebar.tsx  |  6 ++--
 apps/www/src/lib/extract-props.ts             | 13 ++------
 apps/www/src/lib/shiki.ts                     | 10 ++----
 apps/www/src/mdx-components.tsx               |  2 +-
 .../registry/usage-meter/usage-meter-base.tsx |  3 +-
 .../registry/usage-meter/usage-meter.tsx      |  6 ++--
 15 files changed, 70 insertions(+), 54 deletions(-)

diff --git a/.agents/context/decisions/005-component-documentation-strategy.md b/.agents/context/decisions/005-component-documentation-strategy.md
index 137bb36..8155b4f 100644
--- a/.agents/context/decisions/005-component-documentation-strategy.md
+++ b/.agents/context/decisions/005-component-documentation-strategy.md
@@ -131,9 +131,11 @@ This matches shadcn/ui's approach: simple components render inline, complex "blo
 
 ## Decision 4: Props/API Documentation
 
-### Selected: Option A (Manual markdown tables in MDX)
+### ~~Initial: Option A (Manual markdown tables in MDX)~~ → Superseded by Decision 6
 
-**Approach:**
+> **Note:** This decision was initially selected but has been **superseded by Decision 6** (auto-generated API documentation). Manual tables remain as a fallback option documented here for reference.
+
+**Original Approach:**
 - Write API Reference tables manually in MDX files
 - Follow shadcn/ui's format: Prop | Type | Default columns
 
@@ -175,13 +177,13 @@ shadcn/ui uses manual markdown tables in MDX files for API documentation. Exampl
 | **Control** | Human-written descriptions are clearer |
 | **Trade-off** | Manual = can drift, but component count is manageable |
 
-### Alternatives Considered for Future
+### Alternatives (Now Selected)
 
-As component count grows (10+), consider:
+As component count grows, we reconsidered:
 - **JSDoc extraction**: Write docs in code, auto-generate tables
-- **TypeScript type extraction**: Use `react-docgen-typescript`
+- **TypeScript type extraction**: Use `react-docgen-typescript` ✅ **Selected in Decision 6**
 
-These add build complexity but ensure docs stay in sync with code.
+These add build complexity but ensure docs stay in sync with code. See **Decision 6** for the current selected approach.
 
 ---
 
@@ -262,6 +264,8 @@ Unlike some theming solutions that require context providers, shadcn/ui's CSS va
 
 ## Decision 6: Auto-Generated API Documentation
 
+> **Supersedes Decision 4.** After initial selection of manual tables, we decided auto-generation is worth the build complexity for consistency.
+
 ### Selected: Build-Time TypeScript Extraction with react-docgen-typescript
 
 **Approach:**
@@ -379,7 +383,7 @@ interface UsageMeterProps {
 ### Negative
 - Migration effort from current dynamic routes
 - MDX adds build complexity
-- Manual props tables require discipline to keep updated
+- Auto-generated props add build-time processing dependency
 
 ---
 
diff --git a/.agents/workflows/implement-documentation-redesign.md b/.agents/workflows/implement-documentation-redesign.md
index c8a9cd4..22c9c59 100644
--- a/.agents/workflows/implement-documentation-redesign.md
+++ b/.agents/workflows/implement-documentation-redesign.md
@@ -310,6 +310,7 @@ mkdir -p apps/www/src/components/docs
 **Create:** `apps/www/src/components/docs/code-renderer.tsx`
 
 ```tsx
+import { cn } from "@/lib/utils"
 import { highlightCode } from "@/lib/shiki"
 
 interface CodeRendererProps {
diff --git a/apps/www/src/app/(registry)/tokens/page.tsx b/apps/www/src/app/(registry)/tokens/page.tsx
index 50b54b1..1a08796 100644
--- a/apps/www/src/app/(registry)/tokens/page.tsx
+++ b/apps/www/src/app/(registry)/tokens/page.tsx
@@ -35,7 +35,7 @@ export default function TokensPage() {
         </p>
         <div className="grid grid-cols-1 gap-4">
           <FontBlock className="font-sans" />
-          <FontBlock className="font-[family-name:var(--font-inter)]" />
+          <FontBlock className="font-inter" />
           <FontBlock className="font-mono" />
         </div>
       </section>
diff --git a/apps/www/src/app/docs/[slug]/page.tsx b/apps/www/src/app/docs/[slug]/page.tsx
index d20ad1a..0e50d0a 100644
--- a/apps/www/src/app/docs/[slug]/page.tsx
+++ b/apps/www/src/app/docs/[slug]/page.tsx
@@ -1,5 +1,3 @@
-import { notFound } from "next/navigation";
-
 import {
   ApiTable,
   ComponentCodePreview,
@@ -9,25 +7,37 @@ import {
   PreviewErrorBoundary,
 } from "@/components/docs";
 import { getComponentSource } from "@/lib/code";
-import { getRegistryItem, getRegistryItems } from "@/lib/registry";
+import {
+  type Component,
+  getRegistryItem,
+  getRegistryItems,
+} from "@/lib/registry";
+import { notFound } from "next/navigation";
 
 export async function generateStaticParams() {
   const items = getRegistryItems();
   return items.map((item) => ({ slug: item.name }));
 }
 
+// Return 404 for slugs not in generateStaticParams instead of attempting runtime render
+export const dynamicParams = false;
+
 export async function generateMetadata({
   params,
 }: {
   params: Promise<{ slug: string }>;
 }) {
   const { slug } = await params;
-  const component = getRegistryItem(slug);
 
-  return {
-    title: `${component.title} | Usage UI`,
-    description: component.description,
-  };
+  try {
+    const component = getRegistryItem(slug);
+    return {
+      title: `${component.title} | Usage UI`,
+      description: component.description,
+    };
+  } catch {
+    notFound();
+  }
 }
 
 export default async function ComponentDocPage({
@@ -36,9 +46,11 @@ export default async function ComponentDocPage({
   params: Promise<{ slug: string }>;
 }) {
   const { slug } = await params;
-  const component = getRegistryItem(slug);
 
-  if (!component) {
+  let component: Component;
+  try {
+    component = getRegistryItem(slug);
+  } catch {
     notFound();
   }
 
diff --git a/apps/www/src/components/docs/api-table.tsx b/apps/www/src/components/docs/api-table.tsx
index 37a4bca..4799849 100644
--- a/apps/www/src/components/docs/api-table.tsx
+++ b/apps/www/src/components/docs/api-table.tsx
@@ -47,7 +47,7 @@ export function ApiTable({ data, className }: ApiTableProps) {
                 {row.type}
               </td>
               <td className="px-4 py-2 text-left align-middle font-mono text-sm">
-                {row.default || "—"}
+                {row.default ?? "—"}
               </td>
               {data.some((r) => r.description) && (
                 <td className="px-4 py-2 text-left align-middle">
diff --git a/apps/www/src/components/docs/client-code-wrapper.tsx b/apps/www/src/components/docs/client-code-wrapper.tsx
index 3d6f747..d3731b4 100644
--- a/apps/www/src/components/docs/client-code-wrapper.tsx
+++ b/apps/www/src/components/docs/client-code-wrapper.tsx
@@ -19,9 +19,14 @@ export function ClientCodeWrapper({
   const [copied, setCopied] = React.useState(false);
 
   const copyToClipboard = async () => {
-    await navigator.clipboard.writeText(code);
-    setCopied(true);
-    setTimeout(() => setCopied(false), 2000);
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Clipboard write can fail due to denied permissions or insecure context
+      // Silently fail - the UI simply won't show the "copied" state
+    }
   };
 
   return (
diff --git a/apps/www/src/components/docs/code-renderer.tsx b/apps/www/src/components/docs/code-renderer.tsx
index 8d7ce89..e609452 100644
--- a/apps/www/src/components/docs/code-renderer.tsx
+++ b/apps/www/src/components/docs/code-renderer.tsx
@@ -1,10 +1,9 @@
-import { highlightCode } from "@/lib/shiki";
+import { type SupportedLanguage, highlightCode } from "@/lib/shiki";
 import { cn } from "@/lib/utils";
-import type { BundledLanguage } from "shiki";
 
 interface CodeRendererProps {
   code: string;
-  lang?: BundledLanguage;
+  lang?: SupportedLanguage;
   className?: string;
 }
 
diff --git a/apps/www/src/components/docs/component-code-preview.tsx b/apps/www/src/components/docs/component-code-preview.tsx
index 25c2757..19fac2a 100644
--- a/apps/www/src/components/docs/component-code-preview.tsx
+++ b/apps/www/src/components/docs/component-code-preview.tsx
@@ -1,3 +1,5 @@
+"use client";
+
 import { cn } from "@/lib/utils";
 import { Tabs } from "radix-ui";
 import { ClientCodeWrapper } from "./client-code-wrapper";
@@ -22,7 +24,7 @@ export function ComponentCodePreview({
         <Tabs.Trigger
           value="preview"
           className={cn(
-            "relative inline-flex h-10 items-center justify-center px-4 py-1 pt-2 pb-3",
+            "group relative inline-flex h-10 items-center justify-center px-4 py-1 pt-2 pb-3",
             "font-medium text-muted-foreground text-sm",
             "data-[state=active]:text-foreground",
             "transition-none focus-visible:outline-none",
@@ -34,7 +36,7 @@ export function ComponentCodePreview({
         <Tabs.Trigger
           value="code"
           className={cn(
-            "relative inline-flex h-10 items-center justify-center px-4 py-1 pt-2 pb-3",
+            "group relative inline-flex h-10 items-center justify-center px-4 py-1 pt-2 pb-3",
             "font-medium text-muted-foreground text-sm",
             "data-[state=active]:text-foreground",
             "transition-none focus-visible:outline-none",
@@ -63,7 +65,7 @@ export function ComponentCodePreview({
 // Animated underline indicator for active tab
 function TabIndicator() {
   return (
-    <div className="absolute bottom-0 flex h-0.5 w-full justify-center opacity-0 transition-opacity data-[state=active]:opacity-100">
+    <div className="absolute bottom-0 flex h-0.5 w-full justify-center opacity-0 transition-opacity group-data-[state=active]:opacity-100">
       <div className="h-0.5 w-4/5 bg-foreground" />
     </div>
   );
diff --git a/apps/www/src/components/docs/component-nav.tsx b/apps/www/src/components/docs/component-nav.tsx
index c951033..4a68acd 100644
--- a/apps/www/src/components/docs/component-nav.tsx
+++ b/apps/www/src/components/docs/component-nav.tsx
@@ -13,7 +13,10 @@ export function ComponentNav({ currentName, className }: ComponentNavProps) {
   const currentIndex = items.findIndex((item) => item.name === currentName);
 
   const prev = currentIndex > 0 ? items[currentIndex - 1] : null;
-  const next = currentIndex < items.length - 1 ? items[currentIndex + 1] : null;
+  const next =
+    currentIndex >= 0 && currentIndex < items.length - 1
+      ? items[currentIndex + 1]
+      : null;
 
   return (
     <div className={cn("flex justify-between pt-12 pb-20", className)}>
diff --git a/apps/www/src/components/registry/registry-sidebar.tsx b/apps/www/src/components/registry/registry-sidebar.tsx
index edf4a2c..0ebf176 100644
--- a/apps/www/src/components/registry/registry-sidebar.tsx
+++ b/apps/www/src/components/registry/registry-sidebar.tsx
@@ -185,7 +185,7 @@ export function RegistrySidebar() {
                       <SidebarMenuItem key={item.name}>
                         <SidebarMenuButton
                           asChild
-                          isActive={pathname === item.name}
+                          isActive={pathname === `/docs/${item.name}`}
                         >
                           <Link
                             onClick={() => setOpenMobile(false)}
@@ -223,7 +223,7 @@ export function RegistrySidebar() {
                       <SidebarMenuItem key={item.name}>
                         <SidebarMenuButton
                           asChild
-                          isActive={pathname === item.name}
+                          isActive={pathname === `/docs/${item.name}`}
                         >
                           <Link
                             onClick={() => setOpenMobile(false)}
@@ -260,7 +260,7 @@ export function RegistrySidebar() {
                       <SidebarMenuItem key={item.name}>
                         <SidebarMenuButton
                           asChild
-                          isActive={pathname === item.name}
+                          isActive={pathname === `/docs/${item.name}`}
                         >
                           <Link
                             onClick={() => setOpenMobile(false)}
diff --git a/apps/www/src/lib/extract-props.ts b/apps/www/src/lib/extract-props.ts
index c0af2c0..e6408c0 100644
--- a/apps/www/src/lib/extract-props.ts
+++ b/apps/www/src/lib/extract-props.ts
@@ -135,8 +135,8 @@ function extractPropsFromInterface(
   for (const propMatch of interfaceBody.matchAll(propRegex)) {
     const [, jsDocComment, propName, optional, typeStr] = propMatch;
 
-    // Skip inherited props (from extends)
-    if (propName.startsWith("...") || propName === "className") {
+    // Skip className - it's inherited from React.ComponentProps and not useful in API docs
+    if (propName === "className") {
       continue;
     }
 
@@ -295,15 +295,6 @@ export function formatPropsForApiTable(props: PropInfo[]): Array<{
  * Handles union types, generics, etc.
  */
 function formatType(type: string): string {
-  // Clean up keyof expressions
-  if (type.includes("keyof typeof")) {
-    const match = type.match(/keyof typeof (\w+)/);
-    if (match) {
-      // Try to resolve the actual values
-      return type;
-    }
-  }
-
   // Format union types with quotes for string literals
   if (type.includes("|")) {
     return type
diff --git a/apps/www/src/lib/shiki.ts b/apps/www/src/lib/shiki.ts
index 94e55b3..53834a8 100644
--- a/apps/www/src/lib/shiki.ts
+++ b/apps/www/src/lib/shiki.ts
@@ -1,9 +1,5 @@
 import { cache } from "react";
-import {
-  type BundledLanguage,
-  type Highlighter,
-  createHighlighter,
-} from "shiki";
+import { type Highlighter, createHighlighter } from "shiki";
 
 /** Supported languages for syntax highlighting */
 export type SupportedLanguage =
@@ -47,7 +43,7 @@ export const getHighlighter = cache(async (): Promise<Highlighter> => {
  * @param lang - The language for syntax highlighting
  */
 export const highlightCode = cache(
-  async (code: string, lang: BundledLanguage = "tsx"): Promise<string> => {
+  async (code: string, lang: SupportedLanguage = "tsx"): Promise<string> => {
     const highlighter = await getHighlighter();
 
     return highlighter.codeToHtml(code, {
@@ -68,7 +64,7 @@ export const highlightCode = cache(
  * @param lang - The language for syntax highlighting
  */
 export const highlightCodeToTokens = cache(
-  async (code: string, lang: BundledLanguage = "tsx") => {
+  async (code: string, lang: SupportedLanguage = "tsx") => {
     const highlighter = await getHighlighter();
 
     return highlighter.codeToTokens(code, {
diff --git a/apps/www/src/mdx-components.tsx b/apps/www/src/mdx-components.tsx
index c7300b9..3296273 100644
--- a/apps/www/src/mdx-components.tsx
+++ b/apps/www/src/mdx-components.tsx
@@ -57,7 +57,7 @@ export function useMDXComponents(components: MDXComponents): MDXComponents {
     ),
     hr: () => <hr className="my-4 md:my-8" />,
     table: ({ children }: { children?: React.ReactNode }) => (
-      <div className="my-6 w-full overflow-y-auto">
+      <div className="my-6 w-full overflow-x-auto">
         <table className="w-full">{children}</table>
       </div>
     ),
diff --git a/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx b/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
index ae187e0..816b6f7 100644
--- a/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
+++ b/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
@@ -46,7 +46,8 @@ const UsageMeterBase = React.forwardRef<HTMLDivElement, UsageMeterBaseProps>(
     },
     ref,
   ) => {
-    const percentage = Math.round((value / max) * 100);
+    // Guard against max being 0 or negative to avoid NaN/Infinity
+    const percentage = max > 0 ? Math.round((value / max) * 100) : 0;
     const clampedPercentage = Math.min(100, Math.max(0, percentage));
 
     return (
diff --git a/packages/ui/src/components/registry/usage-meter/usage-meter.tsx b/packages/ui/src/components/registry/usage-meter/usage-meter.tsx
index 77c628c..02400d7 100644
--- a/packages/ui/src/components/registry/usage-meter/usage-meter.tsx
+++ b/packages/ui/src/components/registry/usage-meter/usage-meter.tsx
@@ -54,7 +54,9 @@ const UsageMeter = React.forwardRef<
     },
     ref,
   ) => {
-    const percentage = Math.round((value / max) * 100);
+    // Guard against max <= 0 to prevent division by zero and invalid progress state
+    const safeMax = Math.max(1, max);
+    const percentage = Math.round((value / safeMax) * 100);
     const clampedPercentage = Math.min(100, Math.max(0, percentage));
 
     return (
@@ -86,7 +88,7 @@ const UsageMeter = React.forwardRef<
           ref={ref}
           data-slot="usage-meter"
           value={value}
-          max={max}
+          max={safeMax}
           className={cn(
             "relative w-full overflow-hidden rounded-full bg-[--meter-track]",
             meterSizes[size],

From 56174fdd9d7ffe989605bc1e5545c9ad45c95d98 Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 18:30:54 -0500
Subject: [PATCH 08/10] fix(www): resolve hydration mismatches and improve
 component robustness

- Fix hydration issues in sidebar and mcp-tabs by deferring Radix component rendering until after mount
- Add guards against division by zero in usage-meter components when max <= 0
- Fix code.ts path resolution using __dirname for reliable monorepo paths
- Update registry.json to focus on usage-meter components
- Add demo components for usage-meter and usage-meter-base
- Pre-render code syntax highlighting on server to avoid client-side mismatch
- Fix conditional iframe rendering to check if demo exists
---
 apps/www/public/r/registry.json               | 804 +-----------------
 apps/www/public/r/usage-meter-base.json       |   2 +-
 apps/www/public/r/usage-meter.json            |   2 +-
 .../[name]/components/usage-meter-base.tsx    |  11 +
 .../demo/[name]/components/usage-meter.tsx    |  11 +
 apps/www/src/app/demo/[name]/index.tsx        |   4 +
 apps/www/src/app/docs/[slug]/page.tsx         |   7 +-
 .../docs/component-code-preview.tsx           |  13 +-
 apps/www/src/components/registry/mcp-tabs.tsx |  29 +-
 .../components/registry/registry-sidebar.tsx  | 372 ++++----
 apps/www/src/components/ui/sidebar.tsx        |  21 +-
 apps/www/src/lib/code.ts                      |   7 +-
 apps/www/src/registry.json                    |  30 +
 13 files changed, 360 insertions(+), 953 deletions(-)
 create mode 100644 apps/www/src/app/demo/[name]/components/usage-meter-base.tsx
 create mode 100644 apps/www/src/app/demo/[name]/components/usage-meter.tsx

diff --git a/apps/www/public/r/registry.json b/apps/www/public/r/registry.json
index d593b0b..ca02623 100644
--- a/apps/www/public/r/registry.json
+++ b/apps/www/public/r/registry.json
@@ -1,803 +1,35 @@
 {
   "$schema": "https://ui.shadcn.com/schema/registry.json",
-  "name": "Registry Starter",
-  "homepage": "https://registry-starter.vercel.app",
+  "name": "usage-ui",
+  "homepage": "https://usage-ui.vercel.app",
   "items": [
     {
-      "name": "theme",
-      "type": "registry:theme",
-      "title": "Nature Theme",
-      "description": "A nature theme and styles with greens and browns using Tailwind and shadcn/ui variable names",
-      "cssVars": {
-        "light": {
-          "background": "oklch(0.97 0.01 80.72)",
-          "foreground": "oklch(0.3 0.04 30.2)",
-          "card": "oklch(0.97 0.01 80.72)",
-          "card-foreground": "oklch(0.3 0.04 30.2)",
-          "popover": "oklch(0.97 0.01 80.72)",
-          "popover-foreground": "oklch(0.3 0.04 30.2)",
-          "primary": "oklch(0.52 0.13 144.17)",
-          "primary-foreground": "oklch(1.0 0 0)",
-          "secondary": "oklch(0.96 0.02 147.64)",
-          "secondary-foreground": "oklch(0.43 0.12 144.31)",
-          "muted": "oklch(0.94 0.01 74.42)",
-          "muted-foreground": "oklch(0.45 0.05 39.21)",
-          "accent": "oklch(0.9 0.05 146.04)",
-          "accent-foreground": "oklch(0.43 0.12 144.31)",
-          "destructive": "oklch(0.54 0.19 26.72)",
-          "destructive-foreground": "oklch(1.0 0 0)",
-          "border": "oklch(0.88 0.02 74.64)",
-          "input": "oklch(0.88 0.02 74.64)",
-          "ring": "oklch(0.52 0.13 144.17)",
-          "chart-1": "oklch(0.67 0.16 144.21)",
-          "chart-2": "oklch(0.58 0.14 144.18)",
-          "chart-3": "oklch(0.52 0.13 144.17)",
-          "chart-4": "oklch(0.43 0.12 144.31)",
-          "chart-5": "oklch(0.22 0.05 145.73)",
-          "sidebar": "oklch(0.94 0.01 74.42)",
-          "sidebar-foreground": "oklch(0.3 0.04 30.2)",
-          "sidebar-primary": "oklch(0.52 0.13 144.17)",
-          "sidebar-primary-foreground": "oklch(1.0 0 0)",
-          "sidebar-accent": "oklch(0.9 0.05 146.04)",
-          "sidebar-accent-foreground": "oklch(0.43 0.12 144.31)",
-          "sidebar-border": "oklch(0.88 0.02 74.64)",
-          "sidebar-ring": "oklch(0.52 0.13 144.17)",
-          "radius": "0.5rem"
-        },
-        "dark": {
-          "background": "oklch(0.15 0.01 74.42)",
-          "foreground": "oklch(0.95 0.02 80.72)",
-          "card": "oklch(0.12 0.01 80.72)",
-          "card-foreground": "oklch(0.95 0.02 80.72)",
-          "popover": "oklch(0.12 0.01 80.72)",
-          "popover-foreground": "oklch(0.95 0.02 80.72)",
-          "primary": "oklch(0.58 0.15 144.17)",
-          "primary-foreground": "oklch(0.09 0.01 80.72)",
-          "secondary": "oklch(0.15 0.02 147.64)",
-          "secondary-foreground": "oklch(0.65 0.12 144.31)",
-          "muted": "oklch(0.18 0.01 74.42)",
-          "muted-foreground": "oklch(0.65 0.03 74.42)",
-          "accent": "oklch(0.22 0.04 146.04)",
-          "accent-foreground": "oklch(0.65 0.12 144.31)",
-          "destructive": "oklch(0.62 0.22 26.72)",
-          "destructive-foreground": "oklch(0.95 0.02 80.72)",
-          "border": "oklch(0.22 0.02 74.64)",
-          "input": "oklch(0.22 0.02 74.64)",
-          "ring": "oklch(0.58 0.15 144.17)",
-          "chart-1": "oklch(0.72 0.16 144.21)",
-          "chart-2": "oklch(0.63 0.14 144.18)",
-          "chart-3": "oklch(0.58 0.15 144.17)",
-          "chart-4": "oklch(0.48 0.12 144.31)",
-          "chart-5": "oklch(0.35 0.08 145.73)",
-          "sidebar": "oklch(0.15 0.01 74.42)",
-          "sidebar-foreground": "oklch(0.95 0.02 80.72)",
-          "sidebar-primary": "oklch(0.58 0.15 144.17)",
-          "sidebar-primary-foreground": "oklch(0.09 0.01 80.72)",
-          "sidebar-accent": "oklch(0.22 0.04 146.04)",
-          "sidebar-accent-foreground": "oklch(0.65 0.12 144.31)",
-          "sidebar-border": "oklch(0.22 0.02 74.64)",
-          "sidebar-ring": "oklch(0.58 0.15 144.17)",
-          "radius": "0.5rem"
-        }
-      },
-      "dependencies": ["radix-ui"],
-      "files": [
-        {
-          "path": "src/app/globals.css",
-          "type": "registry:style",
-          "target": "app/globals.css"
-        },
-        {
-          "path": "postcss.config.mjs",
-          "type": "registry:file",
-          "target": "postcss.config.mjs"
-        }
-      ]
-    },
-    {
-      "name": "blank",
-      "type": "registry:block",
-      "title": "Blank",
-      "description": "A blank application with all brand components and code",
-      "registryDependencies": [
-        "https://registry-starter.vercel.app/r/brand-header.json",
-        "https://registry-starter.vercel.app/r/brand-sidebar.json",
-        "https://registry-starter.vercel.app/r/product-grid.json",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/app/demo/[name]/blocks/blank-page.tsx",
-          "type": "registry:page",
-          "target": "app/page.tsx"
-        }
-      ]
-    },
-    {
-      "name": "dashboard",
-      "type": "registry:block",
-      "title": "Dashboard",
-      "description": "A dashboard application with your brand themed components",
-      "registryDependencies": [
-        "https://registry-starter.vercel.app/r/sonner.json",
-        "https://registry-starter.vercel.app/r/brand-header.json",
-        "https://registry-starter.vercel.app/r/brand-sidebar.json",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/shell-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/app/demo/[name]/blocks/dashboard-page.tsx",
-          "type": "registry:page",
-          "target": "app/page.tsx"
-        }
-      ]
-    },
-    {
-      "name": "store",
-      "type": "registry:block",
-      "title": "Store",
-      "description": "A store application with your brand themed components",
-      "registryDependencies": [
-        "https://registry-starter.vercel.app/r/product-grid.json",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/app/demo/[name]/blocks/store-page.tsx",
-          "type": "registry:page",
-          "target": "app/page.tsx"
-        }
-      ]
-    },
-    {
-      "name": "brand-header",
+      "name": "usage-meter",
       "type": "registry:component",
-      "title": "Brand Header",
-      "description": "A styled, simple, reusable header",
-      "registryDependencies": [
-        "button",
-        "input",
-        "avatar",
-        "sidebar",
-        "https://registry-starter.vercel.app/r/sonner.json",
-        "https://registry-starter.vercel.app/r/logo.json",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/components/brand-header.tsx",
-          "type": "registry:component"
-        },
-        {
-          "path": "src/layouts/shell-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/app/demo/[name]/blocks/blank-page.tsx",
-          "type": "registry:page",
-          "target": "app/page.tsx"
-        }
-      ]
-    },
-    {
-      "name": "brand-sidebar",
-      "type": "registry:component",
-      "title": "Brand Sidebar",
-      "description": "A styled, simple, reusable sidebar",
-      "registryDependencies": [
-        "badge",
-        "button",
-        "sidebar",
-        "https://registry-starter.vercel.app/r/sonner.json",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/components/brand-sidebar.tsx",
-          "type": "registry:component"
-        },
-        {
-          "path": "src/layouts/shell-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/app/demo/[name]/blocks/blank-page.tsx",
-          "type": "registry:page",
-          "target": "app/page.tsx"
-        }
-      ]
-    },
-    {
-      "name": "login",
-      "type": "registry:component",
-      "title": "Login",
-      "description": "Username & password login section with customer quote.",
-      "registryDependencies": [
-        "badge",
-        "button",
-        "https://registry-starter.vercel.app/r/theme.json",
-        "https://registry-starter.vercel.app/r/logo.json"
-      ],
-      "files": [
-        {
-          "path": "src/components/login.tsx",
-          "type": "registry:component"
-        },
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/app/demo/[name]/blocks/blank-page.tsx",
-          "type": "registry:page",
-          "target": "app/page.tsx"
-        }
-      ]
-    },
-    {
-      "name": "logo",
-      "type": "registry:component",
-      "title": "Brand Logo",
-      "description": "A styled, simple, reusable logo",
-      "registryDependencies": [
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/components/logo.tsx",
-          "type": "registry:component"
-        },
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/app/demo/[name]/blocks/blank-page.tsx",
-          "type": "registry:page",
-          "target": "app/page.tsx"
-        }
-      ]
-    },
-    {
-      "name": "hero",
-      "type": "registry:component",
-      "title": "Hero",
-      "description": "Attention-grabbing section for the top of your landing pages.",
-      "registryDependencies": [
-        "badge",
-        "button",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/components/hero.tsx",
-          "type": "registry:component"
-        },
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/app/demo/[name]/blocks/blank-page.tsx",
-          "type": "registry:page",
-          "target": "app/page.tsx"
-        }
-      ]
-    },
-    {
-      "name": "promo",
-      "type": "registry:component",
-      "title": "Promo",
-      "description": "Attention-grabbing section to display the current promotional deal.",
-      "registryDependencies": [
-        "button",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
+      "title": "Usage Meter",
+      "description": "A linear progress meter for displaying usage/quota information with full Radix accessibility support.",
+      "dependencies": ["radix-ui"],
+      "registryDependencies": [],
       "files": [
         {
-          "path": "src/components/promo.tsx",
-          "type": "registry:component"
-        },
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/app/demo/[name]/blocks/blank-page.tsx",
-          "type": "registry:page",
-          "target": "app/page.tsx"
+          "path": "src/components/registry/usage-meter/usage-meter.tsx",
+          "type": "registry:component",
+          "target": "components/ui/usage-meter.tsx"
         }
       ]
     },
     {
-      "name": "product-grid",
+      "name": "usage-meter-base",
       "type": "registry:component",
-      "title": "Product Grid",
-      "description": "Product grid displaying all products with API to fetch data",
-      "registryDependencies": [
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/components/product-grid.tsx",
-          "type": "registry:component"
-        },
-        {
-          "path": "src/lib/products.ts",
-          "type": "registry:lib"
-        },
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "accordion",
-      "type": "registry:ui",
-      "title": "Accordion",
-      "description": "A vertically stacked set of interactive headings that each reveal a section of content.",
-      "registryDependencies": [
-        "accordion",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "alert",
-      "type": "registry:ui",
-      "title": "Alert",
-      "description": "Displays a callout for user attention.",
-      "registryDependencies": [
-        "alert",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "avatar",
-      "type": "registry:ui",
-      "title": "Avatar",
-      "description": "An image element with a fallback for representing the user.",
-      "registryDependencies": [
-        "avatar",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "badge",
-      "type": "registry:ui",
-      "title": "Badge",
-      "description": "Displays a small count or status indicator.",
-      "registryDependencies": [
-        "badge",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "breadcrumb",
-      "type": "registry:ui",
-      "title": "Breadcrumb",
-      "description": "Displays the path to the current resource using a hierarchy of links.",
-      "registryDependencies": [
-        "breadcrumb",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "button",
-      "type": "registry:ui",
-      "title": "Button",
-      "description": "Allows users to take actions with a single click or tap.",
-      "registryDependencies": [
-        "button",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "calendar",
-      "type": "registry:ui",
-      "title": "Calendar",
-      "description": "A date field component that allows users to enter and edit date.",
-      "registryDependencies": [
-        "calendar",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "card",
-      "type": "registry:ui",
-      "title": "Card",
-      "description": "Containers for displaying content and actions about a single subject.",
-      "registryDependencies": [
-        "card",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "chart",
-      "type": "registry:ui",
-      "title": "Chart",
-      "description": "Beautiful charts. Built using Recharts. Copy and paste into your apps.",
-      "registryDependencies": [
-        "chart",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "checkbox",
-      "type": "registry:ui",
-      "title": "Checkbox",
-      "description": "Allows users to select multiple items from a list of options.",
-      "registryDependencies": [
-        "checkbox",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "data-table",
-      "type": "registry:ui",
-      "title": "Data Table",
-      "description": "Powerful table and datagrids built using TanStack Table.",
-      "registryDependencies": [
-        "data-table",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "date-picker",
-      "type": "registry:ui",
-      "title": "Date Picker",
-      "description": "Displays the path to the current resource using a hierarchy of links.",
-      "registryDependencies": [
-        "date-picker",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "dialog",
-      "type": "registry:ui",
-      "title": "Dialog",
-      "description": "A modal dialog that interrupts the user with important content.",
-      "registryDependencies": [
-        "dialog",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "dropdown-menu",
-      "type": "registry:ui",
-      "title": "Dropdown",
-      "description": "Displays a menu to the user triggered by a button.",
-      "registryDependencies": [
-        "dropdown-menu",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "input",
-      "type": "registry:ui",
-      "title": "Input",
-      "description": "Displays a form input field or a component that looks like an input field.",
-      "registryDependencies": [
-        "input",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "menu-bar",
-      "type": "registry:ui",
-      "title": "Menu Bar",
-      "description": "A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands.",
-      "registryDependencies": [
-        "menu-bar",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "select",
-      "type": "registry:ui",
-      "title": "Select",
-      "description": "Displays a list of options for the user to pick from—triggered by a button.",
-      "registryDependencies": [
-        "select",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "separator",
-      "type": "registry:ui",
-      "title": "Separator",
-      "description": "Visually or semantically separates content.",
-      "registryDependencies": [
-        "separator",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "skeleton",
-      "type": "registry:ui",
-      "title": "Skeleton",
-      "description": "Use to show a placeholder while content is loading.",
-      "registryDependencies": [
-        "skeleton",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "slider",
-      "type": "registry:ui",
-      "title": "Slider",
-      "description": "An input where the user selects a value from within a given range.",
-      "registryDependencies": [
-        "slider",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "sonner",
-      "type": "registry:ui",
-      "title": "Sonner",
-      "description": "An opinionated toast component for React.",
-      "registryDependencies": [
-        "sonner",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        },
-        {
-          "path": "src/components/ui/sonner.tsx",
-          "type": "registry:file",
-          "target": "components/ui/sonner.tsx"
-        }
-      ]
-    },
-    {
-      "name": "switch",
-      "type": "registry:ui",
-      "title": "Switch",
-      "description": "A control that allows the user to toggle between checked and not checked.",
-      "registryDependencies": [
-        "switch",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "table",
-      "type": "registry:ui",
-      "title": "Table",
-      "description": "A responsive table component.",
-      "registryDependencies": [
-        "table",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "tabs",
-      "type": "registry:ui",
-      "title": "Tabs",
-      "description": "A set of layered sections of content—known as tab panels—that are displayed one at a time.",
-      "registryDependencies": [
-        "tabs",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "toggle-group",
-      "type": "registry:ui",
-      "title": "Toggle Group",
-      "description": "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.",
-      "registryDependencies": [
-        "toggle-group",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
-      "files": [
-        {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
-        }
-      ]
-    },
-    {
-      "name": "tooltip",
-      "type": "registry:ui",
-      "title": "Tooltip",
-      "description": "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.",
-      "registryDependencies": [
-        "tooltip",
-        "https://registry-starter.vercel.app/r/theme.json"
-      ],
+      "title": "Usage Meter (Base)",
+      "description": "A lightweight linear progress meter for displaying usage/quota information without Radix dependency.",
+      "dependencies": [],
+      "registryDependencies": [],
       "files": [
         {
-          "path": "src/layouts/minimal-layout.tsx",
-          "type": "registry:file",
-          "target": "app/layout.tsx"
+          "path": "src/components/registry/usage-meter/usage-meter-base.tsx",
+          "type": "registry:component",
+          "target": "components/ui/usage-meter-base.tsx"
         }
       ]
     }
diff --git a/apps/www/public/r/usage-meter-base.json b/apps/www/public/r/usage-meter-base.json
index bc23dc0..c55f287 100644
--- a/apps/www/public/r/usage-meter-base.json
+++ b/apps/www/public/r/usage-meter-base.json
@@ -8,7 +8,7 @@
   "files": [
     {
       "path": "src/components/registry/usage-meter/usage-meter-base.tsx",
-      "content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-[--meter-success]\",\n  warning: \"bg-[--meter-warning]\",\n  danger: \"bg-[--meter-danger]\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterBaseProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeterBase = React.forwardRef<HTMLDivElement, UsageMeterBaseProps>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    const percentage = Math.round((value / max) * 100);\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-base-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-base-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-base-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-base-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <div\n          ref={ref}\n          data-slot=\"usage-meter-base\"\n          role=\"progressbar\"\n          tabIndex={0}\n          aria-valuenow={value}\n          aria-valuemin={0}\n          aria-valuemax={max}\n          aria-valuetext={`${clampedPercentage}%`}\n          aria-label={label}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-[--meter-track]\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <div\n            data-slot=\"usage-meter-base-indicator\"\n            className={cn(\n              \"h-full transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ width: `${clampedPercentage}%` }}\n          />\n        </div>\n      </div>\n    );\n  },\n);\nUsageMeterBase.displayName = \"UsageMeterBase\";\n\nexport {\n  UsageMeterBase,\n  meterVariants as meterBaseVariants,\n  meterSizes as meterBaseSizes,\n};\nexport type { UsageMeterBaseProps };\n",
+      "content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-[--meter-success]\",\n  warning: \"bg-[--meter-warning]\",\n  danger: \"bg-[--meter-danger]\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterBaseProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeterBase = React.forwardRef<HTMLDivElement, UsageMeterBaseProps>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    // Guard against max being 0 or negative to avoid NaN/Infinity\n    const percentage = max > 0 ? Math.round((value / max) * 100) : 0;\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-base-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-base-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-base-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-base-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <div\n          ref={ref}\n          data-slot=\"usage-meter-base\"\n          role=\"progressbar\"\n          tabIndex={0}\n          aria-valuenow={value}\n          aria-valuemin={0}\n          aria-valuemax={max}\n          aria-valuetext={`${clampedPercentage}%`}\n          aria-label={label}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-[--meter-track]\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <div\n            data-slot=\"usage-meter-base-indicator\"\n            className={cn(\n              \"h-full transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ width: `${clampedPercentage}%` }}\n          />\n        </div>\n      </div>\n    );\n  },\n);\nUsageMeterBase.displayName = \"UsageMeterBase\";\n\nexport {\n  UsageMeterBase,\n  meterVariants as meterBaseVariants,\n  meterSizes as meterBaseSizes,\n};\nexport type { UsageMeterBaseProps };\n",
       "type": "registry:component",
       "target": "components/ui/usage-meter-base.tsx"
     }
diff --git a/apps/www/public/r/usage-meter.json b/apps/www/public/r/usage-meter.json
index 2c666c1..4dbad0f 100644
--- a/apps/www/public/r/usage-meter.json
+++ b/apps/www/public/r/usage-meter.json
@@ -10,7 +10,7 @@
   "files": [
     {
       "path": "src/components/registry/usage-meter/usage-meter.tsx",
-      "content": "\"use client\";\n\nimport { Progress as ProgressPrimitive } from \"radix-ui\";\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-[--meter-success]\",\n  warning: \"bg-[--meter-warning]\",\n  danger: \"bg-[--meter-danger]\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterProps\n  extends Omit<\n    React.ComponentProps<typeof ProgressPrimitive.Root>,\n    \"value\" | \"max\"\n  > {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeter = React.forwardRef<\n  React.ComponentRef<typeof ProgressPrimitive.Root>,\n  UsageMeterProps\n>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    const percentage = Math.round((value / max) * 100);\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <ProgressPrimitive.Root\n          ref={ref}\n          data-slot=\"usage-meter\"\n          value={value}\n          max={max}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-[--meter-track]\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <ProgressPrimitive.Indicator\n            data-slot=\"usage-meter-indicator\"\n            className={cn(\n              \"h-full w-full flex-1 transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ transform: `translateX(-${100 - clampedPercentage}%)` }}\n          />\n        </ProgressPrimitive.Root>\n      </div>\n    );\n  },\n);\nUsageMeter.displayName = \"UsageMeter\";\n\nexport { UsageMeter, meterVariants, meterSizes };\nexport type { UsageMeterProps };\n",
+      "content": "\"use client\";\n\nimport { Progress as ProgressPrimitive } from \"radix-ui\";\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-[--meter-success]\",\n  warning: \"bg-[--meter-warning]\",\n  danger: \"bg-[--meter-danger]\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterProps\n  extends Omit<\n    React.ComponentProps<typeof ProgressPrimitive.Root>,\n    \"value\" | \"max\"\n  > {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeter = React.forwardRef<\n  React.ComponentRef<typeof ProgressPrimitive.Root>,\n  UsageMeterProps\n>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    // Guard against max <= 0 to prevent division by zero and invalid progress state\n    const safeMax = Math.max(1, max);\n    const percentage = Math.round((value / safeMax) * 100);\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <ProgressPrimitive.Root\n          ref={ref}\n          data-slot=\"usage-meter\"\n          value={value}\n          max={safeMax}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-[--meter-track]\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <ProgressPrimitive.Indicator\n            data-slot=\"usage-meter-indicator\"\n            className={cn(\n              \"h-full w-full flex-1 transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ transform: `translateX(-${100 - clampedPercentage}%)` }}\n          />\n        </ProgressPrimitive.Root>\n      </div>\n    );\n  },\n);\nUsageMeter.displayName = \"UsageMeter\";\n\nexport { UsageMeter, meterVariants, meterSizes };\nexport type { UsageMeterProps };\n",
       "type": "registry:component",
       "target": "components/ui/usage-meter.tsx"
     }
diff --git a/apps/www/src/app/demo/[name]/components/usage-meter-base.tsx b/apps/www/src/app/demo/[name]/components/usage-meter-base.tsx
new file mode 100644
index 0000000..2c6b63d
--- /dev/null
+++ b/apps/www/src/app/demo/[name]/components/usage-meter-base.tsx
@@ -0,0 +1,11 @@
+import { UsageMeterBase } from "@usage-ui/ui/components/registry/usage-meter";
+
+export const usageMeterBase = {
+  name: "usage-meter-base",
+  components: {
+    Default: <UsageMeterBase value={65} label="Storage" />,
+    Success: <UsageMeterBase value={25} variant="success" label="API Calls" />,
+    Warning: <UsageMeterBase value={75} variant="warning" label="Bandwidth" />,
+    Danger: <UsageMeterBase value={95} variant="danger" label="Memory" />,
+  },
+};
diff --git a/apps/www/src/app/demo/[name]/components/usage-meter.tsx b/apps/www/src/app/demo/[name]/components/usage-meter.tsx
new file mode 100644
index 0000000..68a5618
--- /dev/null
+++ b/apps/www/src/app/demo/[name]/components/usage-meter.tsx
@@ -0,0 +1,11 @@
+import { UsageMeter } from "@usage-ui/ui/components/registry/usage-meter";
+
+export const usageMeter = {
+  name: "usage-meter",
+  components: {
+    Default: <UsageMeter value={65} label="Storage" />,
+    Success: <UsageMeter value={25} variant="success" label="API Calls" />,
+    Warning: <UsageMeter value={75} variant="warning" label="Bandwidth" />,
+    Danger: <UsageMeter value={95} variant="danger" label="Memory" />,
+  },
+};
diff --git a/apps/www/src/app/demo/[name]/index.tsx b/apps/www/src/app/demo/[name]/index.tsx
index 63bcb5a..8f9e406 100644
--- a/apps/www/src/app/demo/[name]/index.tsx
+++ b/apps/www/src/app/demo/[name]/index.tsx
@@ -13,6 +13,8 @@ import { login } from "@/app/demo/[name]/components/login";
 import { logo } from "@/app/demo/[name]/components/logo";
 import { productGrid } from "@/app/demo/[name]/components/product-grid";
 import { promo } from "@/app/demo/[name]/components/promo";
+import { usageMeter } from "@/app/demo/[name]/components/usage-meter";
+import { usageMeterBase } from "@/app/demo/[name]/components/usage-meter-base";
 
 // ui
 import { accordion } from "@/app/demo/[name]/ui/accordion";
@@ -63,6 +65,8 @@ export const demos: { [name: string]: Demo } = {
   "brand-header": brandHeader,
   "brand-sidebar": brandSidebar,
   "product-grid": productGrid,
+  "usage-meter": usageMeter,
+  "usage-meter-base": usageMeterBase,
 
   // ui
   accordion,
diff --git a/apps/www/src/app/docs/[slug]/page.tsx b/apps/www/src/app/docs/[slug]/page.tsx
index 0e50d0a..e29372c 100644
--- a/apps/www/src/app/docs/[slug]/page.tsx
+++ b/apps/www/src/app/docs/[slug]/page.tsx
@@ -1,3 +1,4 @@
+import { demos } from "@/app/demo/[name]";
 import {
   ApiTable,
   ComponentCodePreview,
@@ -12,6 +13,7 @@ import {
   getRegistryItem,
   getRegistryItems,
 } from "@/lib/registry";
+import { highlightCode } from "@/lib/shiki";
 import { notFound } from "next/navigation";
 
 export async function generateStaticParams() {
@@ -55,6 +57,7 @@ export default async function ComponentDocPage({
   }
 
   const sourceCode = getComponentSource(slug);
+  const codeHtml = await highlightCode(sourceCode, "tsx");
   const componentType = component.type as
     | "registry:component"
     | "registry:block"
@@ -81,7 +84,7 @@ export default async function ComponentDocPage({
         Basic
       </h3>
       <div className="mt-4">
-        <ComponentCodePreview name={slug} code={sourceCode}>
+        <ComponentCodePreview name={slug} code={sourceCode} codeHtml={codeHtml}>
           <PreviewErrorBoundary>
             <ComponentPreview
               name={slug}
@@ -92,7 +95,7 @@ export default async function ComponentDocPage({
               }
             >
               {/* Dynamic preview rendered via iframe for blocks */}
-              {componentType !== "registry:block" && (
+              {componentType !== "registry:block" && demos[slug] && (
                 <iframe
                   src={`/demo/${slug}`}
                   className="h-[350px] w-full rounded-md border-0"
diff --git a/apps/www/src/components/docs/component-code-preview.tsx b/apps/www/src/components/docs/component-code-preview.tsx
index 19fac2a..beda0b5 100644
--- a/apps/www/src/components/docs/component-code-preview.tsx
+++ b/apps/www/src/components/docs/component-code-preview.tsx
@@ -3,11 +3,11 @@
 import { cn } from "@/lib/utils";
 import { Tabs } from "radix-ui";
 import { ClientCodeWrapper } from "./client-code-wrapper";
-import { CodeRenderer } from "./code-renderer";
 
 interface ComponentCodePreviewProps {
   name: string;
   code: string;
+  codeHtml: string;
   children: React.ReactNode;
   className?: string;
 }
@@ -15,6 +15,7 @@ interface ComponentCodePreviewProps {
 export function ComponentCodePreview({
   name,
   code,
+  codeHtml,
   children,
   className,
 }: ComponentCodePreviewProps) {
@@ -55,7 +56,15 @@ export function ComponentCodePreview({
 
       <Tabs.Content value="code" className="mt-4">
         <ClientCodeWrapper code={code}>
-          <CodeRenderer code={code} />
+          <div
+            className={cn(
+              "not-prose overflow-auto rounded-md border bg-background p-4 text-[13px]",
+              "[&_pre]:!bg-transparent [&_code]:!bg-transparent",
+              "dark:[&_span]:!text-[var(--shiki-dark)]",
+            )}
+            // biome-ignore lint/security/noDangerouslySetInnerHtml: Shiki returns safe pre-rendered HTML
+            dangerouslySetInnerHTML={{ __html: codeHtml }}
+          />
         </ClientCodeWrapper>
       </Tabs.Content>
     </Tabs.Root>
diff --git a/apps/www/src/components/registry/mcp-tabs.tsx b/apps/www/src/components/registry/mcp-tabs.tsx
index 34c29cb..916296c 100644
--- a/apps/www/src/components/registry/mcp-tabs.tsx
+++ b/apps/www/src/components/registry/mcp-tabs.tsx
@@ -1,10 +1,11 @@
 "use client";
 
 import { Check, ClipboardIcon } from "lucide-react";
-import { useEffect, useState } from "react";
+import * as React from "react";
 
 import { AddToCursor } from "@/components/registry/add-to-cursor";
 import { Button } from "@/components/ui/button";
+import { Skeleton } from "@/components/ui/skeleton";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 
 export async function copyToClipboard(value: string) {
@@ -12,8 +13,10 @@ export async function copyToClipboard(value: string) {
 }
 
 export function MCPTabs({ rootUrl }: { rootUrl: string }) {
-  const [tab, setTab] = useState("cursor");
-  const [hasCopied, setHasCopied] = useState(false);
+  // Track mount state to prevent hydration mismatch with Radix Tabs
+  const [mounted, setMounted] = React.useState(false);
+  const [tab, setTab] = React.useState("cursor");
+  const [hasCopied, setHasCopied] = React.useState(false);
 
   const mcp = {
     command: "npx -y shadcn@canary registry:mcp",
@@ -32,7 +35,11 @@ export function MCPTabs({ rootUrl }: { rootUrl: string }) {
     2,
   );
 
-  useEffect(() => {
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  React.useEffect(() => {
     if (hasCopied) {
       setTimeout(() => {
         setHasCopied(false);
@@ -40,6 +47,20 @@ export function MCPTabs({ rootUrl }: { rootUrl: string }) {
     }
   }, [hasCopied]);
 
+  // Show skeleton during SSR to prevent hydration mismatch
+  if (!mounted) {
+    return (
+      <div className="flex flex-col gap-2">
+        <div className="flex gap-2">
+          <Skeleton className="h-9 w-20" />
+          <Skeleton className="h-9 w-20" />
+        </div>
+        <Skeleton className="mt-2 h-4 w-64" />
+        <Skeleton className="mt-4 h-32 w-full" />
+      </div>
+    );
+  }
+
   return (
     <Tabs value={tab} onValueChange={setTab}>
       <div className="flex items-center justify-between">
diff --git a/apps/www/src/components/registry/registry-sidebar.tsx b/apps/www/src/components/registry/registry-sidebar.tsx
index 0ebf176..eac9ca9 100644
--- a/apps/www/src/components/registry/registry-sidebar.tsx
+++ b/apps/www/src/components/registry/registry-sidebar.tsx
@@ -12,7 +12,7 @@ import {
 } from "lucide-react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
-import { useEffect, useState } from "react";
+import * as React from "react";
 
 import { RegistryLogo } from "@/components/registry/registry-logo";
 import { ModeToggle } from "@/components/registry/theme-toggle";
@@ -37,6 +37,7 @@ import {
   SidebarMenuItem,
   useSidebar,
 } from "@/components/ui/sidebar";
+import { Skeleton } from "@/components/ui/skeleton";
 import { getBlocks, getComponents, getUIPrimitives } from "@/lib/registry";
 
 const uiItems = getUIPrimitives();
@@ -48,6 +49,61 @@ export const gettingStartedItems = [
   { title: "Design Tokens", path: "/tokens" },
 ];
 
+// Skeleton fallback for SSR to prevent hydration mismatch with Radix components
+function SidebarSkeleton() {
+  return (
+    <div className="space-y-4 p-2">
+      {/* Getting Started */}
+      <div className="space-y-2">
+        <div className="flex items-center gap-2 px-2">
+          <Skeleton className="size-4" />
+          <Skeleton className="h-4 w-24" />
+        </div>
+        <div className="space-y-1 pl-6">
+          <Skeleton className="h-8 w-full" />
+          <Skeleton className="h-8 w-full" />
+        </div>
+      </div>
+      {/* Blocks */}
+      <div className="space-y-2">
+        <div className="flex items-center gap-2 px-2">
+          <Skeleton className="size-4" />
+          <Skeleton className="h-4 w-16" />
+        </div>
+        <div className="space-y-1 pl-6">
+          <Skeleton className="h-8 w-full" />
+          <Skeleton className="h-8 w-full" />
+          <Skeleton className="h-8 w-full" />
+        </div>
+      </div>
+      {/* Components */}
+      <div className="space-y-2">
+        <div className="flex items-center gap-2 px-2">
+          <Skeleton className="size-4" />
+          <Skeleton className="h-4 w-24" />
+        </div>
+        <div className="space-y-1 pl-6">
+          <Skeleton className="h-8 w-full" />
+          <Skeleton className="h-8 w-full" />
+          <Skeleton className="h-8 w-full" />
+        </div>
+      </div>
+      {/* UI Primitives */}
+      <div className="space-y-2">
+        <div className="flex items-center gap-2 px-2">
+          <Skeleton className="size-4" />
+          <Skeleton className="h-4 w-24" />
+        </div>
+        <div className="space-y-1 pl-6">
+          <Skeleton className="h-8 w-full" />
+          <Skeleton className="h-8 w-full" />
+          <Skeleton className="h-8 w-full" />
+        </div>
+      </div>
+    </div>
+  );
+}
+
 export function MobileSidebarTrigger() {
   const { setOpenMobile } = useSidebar();
 
@@ -65,12 +121,21 @@ export function RegistrySidebar() {
 
   const { setOpenMobile } = useSidebar();
 
-  const [searchTerm, setSearchTerm] = useState("");
-  const [filteredUiItems, setFilteredUiItems] = useState(uiItems);
-  const [filteredComponents, setFilteredComponents] = useState(componentItems);
-  const [filteredBlocks, setFilteredBlocks] = useState(blockItems);
+  // Track mount state to prevent hydration mismatch.
+  // Radix Collapsible components use useId for accessibility attributes,
+  // which can generate different IDs on server vs client due to streaming.
+  const [mounted, setMounted] = React.useState(false);
+  const [searchTerm, setSearchTerm] = React.useState("");
+  const [filteredUiItems, setFilteredUiItems] = React.useState(uiItems);
+  const [filteredComponents, setFilteredComponents] =
+    React.useState(componentItems);
+  const [filteredBlocks, setFilteredBlocks] = React.useState(blockItems);
+
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
 
-  useEffect(() => {
+  React.useEffect(() => {
     if (searchTerm) {
       setFilteredUiItems(
         uiItems.filter((item) =>
@@ -126,156 +191,163 @@ export function RegistrySidebar() {
 
       <SidebarContent>
         <ScrollArea className="h-full w-full pr-2">
-          <Collapsible defaultOpen={true} className="group/collapsible">
-            <SidebarGroup>
-              <CollapsibleTrigger className="w-full">
-                <SidebarGroupLabel className="flex cursor-pointer items-center justify-between">
-                  <div className="flex min-w-0 items-center">
-                    <Home className="size-4 flex-shrink-0" />
-                    <span className="ml-2 opacity-100 transition-all duration-200">
-                      Getting Started
-                    </span>
-                  </div>
-                  <ChevronDown className="size-4 flex-shrink-0 opacity-100 transition-all duration-200 group-data-[state=open]/collapsible:rotate-180" />
-                </SidebarGroupLabel>
-              </CollapsibleTrigger>
+          {!mounted ? (
+            // Show skeleton during SSR to prevent hydration mismatch
+            <SidebarSkeleton />
+          ) : (
+            <>
+              <Collapsible defaultOpen={true} className="group/collapsible">
+                <SidebarGroup>
+                  <CollapsibleTrigger className="w-full">
+                    <SidebarGroupLabel className="flex cursor-pointer items-center justify-between">
+                      <div className="flex min-w-0 items-center">
+                        <Home className="size-4 flex-shrink-0" />
+                        <span className="ml-2 opacity-100 transition-all duration-200">
+                          Getting Started
+                        </span>
+                      </div>
+                      <ChevronDown className="size-4 flex-shrink-0 opacity-100 transition-all duration-200 group-data-[state=open]/collapsible:rotate-180" />
+                    </SidebarGroupLabel>
+                  </CollapsibleTrigger>
 
-              <CollapsibleContent>
-                <SidebarGroupContent>
-                  <SidebarMenu>
-                    {gettingStartedItems.map((item) => (
-                      <SidebarMenuItem key={item.path}>
-                        <SidebarMenuButton
-                          asChild
-                          isActive={pathname === item.path}
-                        >
-                          <Link
-                            onClick={() => setOpenMobile(false)}
-                            href={item.path}
-                          >
-                            {item.title}
-                          </Link>
-                        </SidebarMenuButton>
-                      </SidebarMenuItem>
-                    ))}
-                  </SidebarMenu>
-                </SidebarGroupContent>
-              </CollapsibleContent>
-            </SidebarGroup>
-          </Collapsible>
+                  <CollapsibleContent>
+                    <SidebarGroupContent>
+                      <SidebarMenu>
+                        {gettingStartedItems.map((item) => (
+                          <SidebarMenuItem key={item.path}>
+                            <SidebarMenuButton
+                              asChild
+                              isActive={pathname === item.path}
+                            >
+                              <Link
+                                onClick={() => setOpenMobile(false)}
+                                href={item.path}
+                              >
+                                {item.title}
+                              </Link>
+                            </SidebarMenuButton>
+                          </SidebarMenuItem>
+                        ))}
+                      </SidebarMenu>
+                    </SidebarGroupContent>
+                  </CollapsibleContent>
+                </SidebarGroup>
+              </Collapsible>
 
-          <Collapsible defaultOpen={true} className="group/collapsible">
-            <SidebarGroup>
-              <CollapsibleTrigger className="w-full">
-                <SidebarGroupLabel className="flex cursor-pointer items-center justify-between">
-                  <div className="flex min-w-0 items-center">
-                    <Blocks className="size-4 flex-shrink-0" />
-                    <span className="ml-2 transition-all duration-200">
-                      Blocks
-                    </span>
-                  </div>
-                  <ChevronDown className="size-4 flex-shrink-0 transition-all duration-200 group-data-[state=open]/collapsible:rotate-180" />
-                </SidebarGroupLabel>
-              </CollapsibleTrigger>
+              <Collapsible defaultOpen={true} className="group/collapsible">
+                <SidebarGroup>
+                  <CollapsibleTrigger className="w-full">
+                    <SidebarGroupLabel className="flex cursor-pointer items-center justify-between">
+                      <div className="flex min-w-0 items-center">
+                        <Blocks className="size-4 flex-shrink-0" />
+                        <span className="ml-2 transition-all duration-200">
+                          Blocks
+                        </span>
+                      </div>
+                      <ChevronDown className="size-4 flex-shrink-0 transition-all duration-200 group-data-[state=open]/collapsible:rotate-180" />
+                    </SidebarGroupLabel>
+                  </CollapsibleTrigger>
 
-              <CollapsibleContent>
-                <SidebarGroupContent>
-                  <SidebarMenu>
-                    {filteredBlocks.map((item) => (
-                      <SidebarMenuItem key={item.name}>
-                        <SidebarMenuButton
-                          asChild
-                          isActive={pathname === `/docs/${item.name}`}
-                        >
-                          <Link
-                            onClick={() => setOpenMobile(false)}
-                            href={`/docs/${item.name}`}
-                          >
-                            {item.title}
-                          </Link>
-                        </SidebarMenuButton>
-                      </SidebarMenuItem>
-                    ))}
-                  </SidebarMenu>
-                </SidebarGroupContent>
-              </CollapsibleContent>
-            </SidebarGroup>
-          </Collapsible>
+                  <CollapsibleContent>
+                    <SidebarGroupContent>
+                      <SidebarMenu>
+                        {filteredBlocks.map((item) => (
+                          <SidebarMenuItem key={item.name}>
+                            <SidebarMenuButton
+                              asChild
+                              isActive={pathname === `/docs/${item.name}`}
+                            >
+                              <Link
+                                onClick={() => setOpenMobile(false)}
+                                href={`/docs/${item.name}`}
+                              >
+                                {item.title}
+                              </Link>
+                            </SidebarMenuButton>
+                          </SidebarMenuItem>
+                        ))}
+                      </SidebarMenu>
+                    </SidebarGroupContent>
+                  </CollapsibleContent>
+                </SidebarGroup>
+              </Collapsible>
 
-          <Collapsible defaultOpen={true} className="group/collapsible">
-            <SidebarGroup>
-              <CollapsibleTrigger className="w-full">
-                <SidebarGroupLabel className="flex cursor-pointer items-center justify-between">
-                  <div className="flex min-w-0 items-center">
-                    <Component className="size-4 flex-shrink-0" />
-                    <span className="ml-2 transition-all duration-200">
-                      Components
-                    </span>
-                  </div>
-                  <ChevronDown className="size-4 flex-shrink-0 transition-all duration-200 group-data-[state=open]/collapsible:rotate-180" />
-                </SidebarGroupLabel>
-              </CollapsibleTrigger>
+              <Collapsible defaultOpen={true} className="group/collapsible">
+                <SidebarGroup>
+                  <CollapsibleTrigger className="w-full">
+                    <SidebarGroupLabel className="flex cursor-pointer items-center justify-between">
+                      <div className="flex min-w-0 items-center">
+                        <Component className="size-4 flex-shrink-0" />
+                        <span className="ml-2 transition-all duration-200">
+                          Components
+                        </span>
+                      </div>
+                      <ChevronDown className="size-4 flex-shrink-0 transition-all duration-200 group-data-[state=open]/collapsible:rotate-180" />
+                    </SidebarGroupLabel>
+                  </CollapsibleTrigger>
 
-              <CollapsibleContent>
-                <SidebarGroupContent>
-                  <SidebarMenu>
-                    {filteredComponents.map((item) => (
-                      <SidebarMenuItem key={item.name}>
-                        <SidebarMenuButton
-                          asChild
-                          isActive={pathname === `/docs/${item.name}`}
-                        >
-                          <Link
-                            onClick={() => setOpenMobile(false)}
-                            href={`/docs/${item.name}`}
-                          >
-                            {item.title}
-                          </Link>
-                        </SidebarMenuButton>
-                      </SidebarMenuItem>
-                    ))}
-                  </SidebarMenu>
-                </SidebarGroupContent>
-              </CollapsibleContent>
-            </SidebarGroup>
-          </Collapsible>
+                  <CollapsibleContent>
+                    <SidebarGroupContent>
+                      <SidebarMenu>
+                        {filteredComponents.map((item) => (
+                          <SidebarMenuItem key={item.name}>
+                            <SidebarMenuButton
+                              asChild
+                              isActive={pathname === `/docs/${item.name}`}
+                            >
+                              <Link
+                                onClick={() => setOpenMobile(false)}
+                                href={`/docs/${item.name}`}
+                              >
+                                {item.title}
+                              </Link>
+                            </SidebarMenuButton>
+                          </SidebarMenuItem>
+                        ))}
+                      </SidebarMenu>
+                    </SidebarGroupContent>
+                  </CollapsibleContent>
+                </SidebarGroup>
+              </Collapsible>
 
-          <Collapsible defaultOpen={true} className="group/collapsible">
-            <SidebarGroup>
-              <CollapsibleTrigger className="w-full">
-                <SidebarGroupLabel className="flex cursor-pointer items-center justify-between">
-                  <div className="flex min-w-0 items-center">
-                    <ToyBrick className="size-4 flex-shrink-0" />
-                    <span className="ml-2 transition-all duration-200">
-                      UI Primitives
-                    </span>
-                  </div>
-                  <ChevronDown className="size-4 flex-shrink-0 transition-all duration-200 group-data-[state=open]/collapsible:rotate-180" />
-                </SidebarGroupLabel>
-              </CollapsibleTrigger>
-              <CollapsibleContent>
-                <SidebarGroupContent>
-                  <SidebarMenu>
-                    {filteredUiItems.map((item) => (
-                      <SidebarMenuItem key={item.name}>
-                        <SidebarMenuButton
-                          asChild
-                          isActive={pathname === `/docs/${item.name}`}
-                        >
-                          <Link
-                            onClick={() => setOpenMobile(false)}
-                            href={`/docs/${item.name}`}
-                          >
-                            {item.title}
-                          </Link>
-                        </SidebarMenuButton>
-                      </SidebarMenuItem>
-                    ))}
-                  </SidebarMenu>
-                </SidebarGroupContent>
-              </CollapsibleContent>
-            </SidebarGroup>
-          </Collapsible>
+              <Collapsible defaultOpen={true} className="group/collapsible">
+                <SidebarGroup>
+                  <CollapsibleTrigger className="w-full">
+                    <SidebarGroupLabel className="flex cursor-pointer items-center justify-between">
+                      <div className="flex min-w-0 items-center">
+                        <ToyBrick className="size-4 flex-shrink-0" />
+                        <span className="ml-2 transition-all duration-200">
+                          UI Primitives
+                        </span>
+                      </div>
+                      <ChevronDown className="size-4 flex-shrink-0 transition-all duration-200 group-data-[state=open]/collapsible:rotate-180" />
+                    </SidebarGroupLabel>
+                  </CollapsibleTrigger>
+                  <CollapsibleContent>
+                    <SidebarGroupContent>
+                      <SidebarMenu>
+                        {filteredUiItems.map((item) => (
+                          <SidebarMenuItem key={item.name}>
+                            <SidebarMenuButton
+                              asChild
+                              isActive={pathname === `/docs/${item.name}`}
+                            >
+                              <Link
+                                onClick={() => setOpenMobile(false)}
+                                href={`/docs/${item.name}`}
+                              >
+                                {item.title}
+                              </Link>
+                            </SidebarMenuButton>
+                          </SidebarMenuItem>
+                        ))}
+                      </SidebarMenu>
+                    </SidebarGroupContent>
+                  </CollapsibleContent>
+                </SidebarGroup>
+              </Collapsible>
+            </>
+          )}
         </ScrollArea>
       </SidebarContent>
 
diff --git a/apps/www/src/components/ui/sidebar.tsx b/apps/www/src/components/ui/sidebar.tsx
index 34b055b..5e938e3 100644
--- a/apps/www/src/components/ui/sidebar.tsx
+++ b/apps/www/src/components/ui/sidebar.tsx
@@ -164,6 +164,17 @@ function Sidebar({
   collapsible?: "offcanvas" | "icon" | "none";
 }) {
   const { isMobile, state, openMobile, setOpenMobile } = useSidebar();
+  const [mounted, setMounted] = React.useState(false);
+
+  // Track mount state to prevent hydration mismatch.
+  // Radix components use useId for accessibility attributes, and conditional
+  // rendering based on isMobile creates different component trees between
+  // server (where isMobile is always false) and client (where it may be true).
+  // By always rendering the desktop version first, then switching after mount,
+  // we ensure hydration succeeds with matching component trees.
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
 
   if (collapsible === "none") {
     return (
@@ -180,7 +191,8 @@ function Sidebar({
     );
   }
 
-  if (isMobile) {
+  // After mount, use the actual isMobile value for rendering
+  if (mounted && isMobile) {
     return (
       <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
         <SheetContent
@@ -606,10 +618,9 @@ function SidebarMenuSkeleton({
 }: React.ComponentProps<"div"> & {
   showIcon?: boolean;
 }) {
-  // Random width between 50 to 90%.
-  const width = React.useMemo(() => {
-    return `${Math.floor(Math.random() * 40) + 50}%`;
-  }, []);
+  // Use a fixed width to avoid hydration mismatch.
+  // Math.random() produces different values on server vs client.
+  const width = "70%";
 
   return (
     <div
diff --git a/apps/www/src/lib/code.ts b/apps/www/src/lib/code.ts
index 10392e1..3f788e9 100644
--- a/apps/www/src/lib/code.ts
+++ b/apps/www/src/lib/code.ts
@@ -1,13 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { cache } from "react";
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
 /**
  * Get the path to the packages/ui directory from apps/www.
  */
 function getPackageUiPath(): string {
-  // In monorepo: apps/www -> packages/ui
-  return path.join(process.cwd(), "..", "..", "packages", "ui");
+  // From apps/www/src/lib/ -> packages/ui (4 levels up, then into packages/ui)
+  return path.join(__dirname, "..", "..", "..", "..", "packages", "ui");
 }
 
 /**
diff --git a/apps/www/src/registry.json b/apps/www/src/registry.json
index d593b0b..793850d 100644
--- a/apps/www/src/registry.json
+++ b/apps/www/src/registry.json
@@ -800,6 +800,36 @@
           "target": "app/layout.tsx"
         }
       ]
+    },
+    {
+      "name": "usage-meter",
+      "type": "registry:component",
+      "title": "Usage Meter",
+      "description": "A linear progress meter for displaying usage/quota information with full Radix accessibility support.",
+      "dependencies": ["radix-ui"],
+      "registryDependencies": ["https://usage-ui.vercel.app/r/theme.json"],
+      "files": [
+        {
+          "path": "src/components/registry/usage-meter/usage-meter.tsx",
+          "type": "registry:component",
+          "target": "components/ui/usage-meter.tsx"
+        }
+      ]
+    },
+    {
+      "name": "usage-meter-base",
+      "type": "registry:component",
+      "title": "Usage Meter (Base)",
+      "description": "A lightweight linear progress meter for displaying usage/quota information without Radix dependency.",
+      "dependencies": [],
+      "registryDependencies": ["https://usage-ui.vercel.app/r/theme.json"],
+      "files": [
+        {
+          "path": "src/components/registry/usage-meter/usage-meter-base.tsx",
+          "type": "registry:component",
+          "target": "components/ui/usage-meter-base.tsx"
+        }
+      ]
     }
   ]
 }

From 14651725bbb97de101082832bd87bd7d92708a78 Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 18:32:27 -0500
Subject: [PATCH 09/10] refactor(www): update registry logo icon from Squirrel
 to Circle

Use a filled Circle icon for a cleaner, more abstract logo appearance.
---
 apps/www/src/components/registry/registry-logo.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/www/src/components/registry/registry-logo.tsx b/apps/www/src/components/registry/registry-logo.tsx
index 8c78999..1d64f95 100644
--- a/apps/www/src/components/registry/registry-logo.tsx
+++ b/apps/www/src/components/registry/registry-logo.tsx
@@ -1,10 +1,10 @@
-import { Squirrel } from "lucide-react";
+import { Circle } from "lucide-react";
 
 export function RegistryLogo() {
   return (
     <>
       <div className="flex-shrink-0 rounded-md bg-primary p-1">
-        <Squirrel className="size-5 text-secondary" />
+        <Circle className="size-5 text-secondary" fill="currentColor" />
       </div>
       <span className="font-medium text-xl tracking-tight">usage-ui</span>
     </>

From 7f3073465aa7e86c80addf8728adb8bb70b5ccd6 Mon Sep 17 00:00:00 2001
From: Andres Gonzalez <andresthedesigner@gmail.com>
Date: Thu, 29 Jan 2026 18:46:38 -0500
Subject: [PATCH 10/10] refactor(ui): simplify meter components to use standard
 shadcn CSS variables

- Replace custom meter CSS variables with standard shadcn tokens:
  - success: chart-2, warning: chart-4, danger: destructive, track: secondary
- Remove custom --meter-* CSS variable definitions from globals.css
- Update favicon from emoji to minimal circle SVG
- Improve code.ts to support dual registry lookup (packages/ui + apps/www)
- Add dynamic prop extraction for API documentation tables
- Update registry.json entries for usage-meter components
---
 apps/www/public/favicon.svg                   |   2 +-
 apps/www/public/r/usage-meter-base.json       |   2 +-
 apps/www/public/r/usage-meter.json            |   2 +-
 apps/www/src/app/docs/[slug]/page.tsx         |  28 ++--
 apps/www/src/lib/code.ts                      | 123 ++++++++++++------
 apps/www/src/registry.json                    |  28 ++--
 .../registry/usage-meter/usage-meter-base.tsx |   8 +-
 .../registry/usage-meter/usage-meter.tsx      |   8 +-
 packages/ui/src/styles/globals.css            |  37 +-----
 9 files changed, 130 insertions(+), 108 deletions(-)

diff --git a/apps/www/public/favicon.svg b/apps/www/public/favicon.svg
index 7c16de9..755347b 100644
--- a/apps/www/public/favicon.svg
+++ b/apps/www/public/favicon.svg
@@ -1,3 +1,3 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
-    <text y=".9em" font-size="90">🎨</text>
+  <circle cx="50" cy="50" r="45" fill="#171717"/>
 </svg>
diff --git a/apps/www/public/r/usage-meter-base.json b/apps/www/public/r/usage-meter-base.json
index c55f287..994ba2f 100644
--- a/apps/www/public/r/usage-meter-base.json
+++ b/apps/www/public/r/usage-meter-base.json
@@ -8,7 +8,7 @@
   "files": [
     {
       "path": "src/components/registry/usage-meter/usage-meter-base.tsx",
-      "content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-[--meter-success]\",\n  warning: \"bg-[--meter-warning]\",\n  danger: \"bg-[--meter-danger]\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterBaseProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeterBase = React.forwardRef<HTMLDivElement, UsageMeterBaseProps>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    // Guard against max being 0 or negative to avoid NaN/Infinity\n    const percentage = max > 0 ? Math.round((value / max) * 100) : 0;\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-base-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-base-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-base-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-base-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <div\n          ref={ref}\n          data-slot=\"usage-meter-base\"\n          role=\"progressbar\"\n          tabIndex={0}\n          aria-valuenow={value}\n          aria-valuemin={0}\n          aria-valuemax={max}\n          aria-valuetext={`${clampedPercentage}%`}\n          aria-label={label}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-[--meter-track]\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <div\n            data-slot=\"usage-meter-base-indicator\"\n            className={cn(\n              \"h-full transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ width: `${clampedPercentage}%` }}\n          />\n        </div>\n      </div>\n    );\n  },\n);\nUsageMeterBase.displayName = \"UsageMeterBase\";\n\nexport {\n  UsageMeterBase,\n  meterVariants as meterBaseVariants,\n  meterSizes as meterBaseSizes,\n};\nexport type { UsageMeterBaseProps };\n",
+      "content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-chart-2\",\n  warning: \"bg-chart-4\",\n  danger: \"bg-destructive\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterBaseProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeterBase = React.forwardRef<HTMLDivElement, UsageMeterBaseProps>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    // Guard against max being 0 or negative to avoid NaN/Infinity\n    const percentage = max > 0 ? Math.round((value / max) * 100) : 0;\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-base-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-base-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-base-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-base-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <div\n          ref={ref}\n          data-slot=\"usage-meter-base\"\n          role=\"progressbar\"\n          tabIndex={0}\n          aria-valuenow={value}\n          aria-valuemin={0}\n          aria-valuemax={max}\n          aria-valuetext={`${clampedPercentage}%`}\n          aria-label={label}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-secondary\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <div\n            data-slot=\"usage-meter-base-indicator\"\n            className={cn(\n              \"h-full transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ width: `${clampedPercentage}%` }}\n          />\n        </div>\n      </div>\n    );\n  },\n);\nUsageMeterBase.displayName = \"UsageMeterBase\";\n\nexport {\n  UsageMeterBase,\n  meterVariants as meterBaseVariants,\n  meterSizes as meterBaseSizes,\n};\nexport type { UsageMeterBaseProps };\n",
       "type": "registry:component",
       "target": "components/ui/usage-meter-base.tsx"
     }
diff --git a/apps/www/public/r/usage-meter.json b/apps/www/public/r/usage-meter.json
index 4dbad0f..ef1dfd6 100644
--- a/apps/www/public/r/usage-meter.json
+++ b/apps/www/public/r/usage-meter.json
@@ -10,7 +10,7 @@
   "files": [
     {
       "path": "src/components/registry/usage-meter/usage-meter.tsx",
-      "content": "\"use client\";\n\nimport { Progress as ProgressPrimitive } from \"radix-ui\";\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-[--meter-success]\",\n  warning: \"bg-[--meter-warning]\",\n  danger: \"bg-[--meter-danger]\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterProps\n  extends Omit<\n    React.ComponentProps<typeof ProgressPrimitive.Root>,\n    \"value\" | \"max\"\n  > {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeter = React.forwardRef<\n  React.ComponentRef<typeof ProgressPrimitive.Root>,\n  UsageMeterProps\n>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    // Guard against max <= 0 to prevent division by zero and invalid progress state\n    const safeMax = Math.max(1, max);\n    const percentage = Math.round((value / safeMax) * 100);\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <ProgressPrimitive.Root\n          ref={ref}\n          data-slot=\"usage-meter\"\n          value={value}\n          max={safeMax}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-[--meter-track]\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <ProgressPrimitive.Indicator\n            data-slot=\"usage-meter-indicator\"\n            className={cn(\n              \"h-full w-full flex-1 transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ transform: `translateX(-${100 - clampedPercentage}%)` }}\n          />\n        </ProgressPrimitive.Root>\n      </div>\n    );\n  },\n);\nUsageMeter.displayName = \"UsageMeter\";\n\nexport { UsageMeter, meterVariants, meterSizes };\nexport type { UsageMeterProps };\n",
+      "content": "\"use client\";\n\nimport { Progress as ProgressPrimitive } from \"radix-ui\";\nimport * as React from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\nconst meterVariants = {\n  default: \"bg-primary\",\n  success: \"bg-chart-2\",\n  warning: \"bg-chart-4\",\n  danger: \"bg-destructive\",\n} as const;\n\nconst meterSizes = {\n  sm: \"h-2\",\n  default: \"h-3\",\n  lg: \"h-4\",\n} as const;\n\ninterface UsageMeterProps\n  extends Omit<\n    React.ComponentProps<typeof ProgressPrimitive.Root>,\n    \"value\" | \"max\"\n  > {\n  /** Current value (required) */\n  value: number;\n  /** Maximum value (default: 100) */\n  max?: number;\n  /** Visual variant */\n  variant?: keyof typeof meterVariants;\n  /** Size variant */\n  size?: keyof typeof meterSizes;\n  /** Optional label text */\n  label?: string;\n  /** Show percentage (default: true) */\n  showPercentage?: boolean;\n}\n\nconst UsageMeter = React.forwardRef<\n  React.ComponentRef<typeof ProgressPrimitive.Root>,\n  UsageMeterProps\n>(\n  (\n    {\n      className,\n      value,\n      max = 100,\n      variant = \"default\",\n      size = \"default\",\n      label,\n      showPercentage = true,\n      ...props\n    },\n    ref,\n  ) => {\n    // Guard against max <= 0 to prevent division by zero and invalid progress state\n    const safeMax = Math.max(1, max);\n    const percentage = Math.round((value / safeMax) * 100);\n    const clampedPercentage = Math.min(100, Math.max(0, percentage));\n\n    return (\n      <div data-slot=\"usage-meter-root\" className=\"w-full\">\n        {(label || showPercentage) && (\n          <div\n            data-slot=\"usage-meter-header\"\n            className=\"mb-1.5 flex items-center justify-between text-sm\"\n          >\n            {label && (\n              <span\n                data-slot=\"usage-meter-label\"\n                className=\"font-medium text-foreground\"\n              >\n                {label}\n              </span>\n            )}\n            {showPercentage && (\n              <span\n                data-slot=\"usage-meter-percentage\"\n                className=\"text-muted-foreground tabular-nums\"\n              >\n                {clampedPercentage}%\n              </span>\n            )}\n          </div>\n        )}\n        <ProgressPrimitive.Root\n          ref={ref}\n          data-slot=\"usage-meter\"\n          value={value}\n          max={safeMax}\n          className={cn(\n            \"relative w-full overflow-hidden rounded-full bg-secondary\",\n            meterSizes[size],\n            className,\n          )}\n          {...props}\n        >\n          <ProgressPrimitive.Indicator\n            data-slot=\"usage-meter-indicator\"\n            className={cn(\n              \"h-full w-full flex-1 transition-all duration-300 ease-in-out\",\n              meterVariants[variant],\n            )}\n            style={{ transform: `translateX(-${100 - clampedPercentage}%)` }}\n          />\n        </ProgressPrimitive.Root>\n      </div>\n    );\n  },\n);\nUsageMeter.displayName = \"UsageMeter\";\n\nexport { UsageMeter, meterVariants, meterSizes };\nexport type { UsageMeterProps };\n",
       "type": "registry:component",
       "target": "components/ui/usage-meter.tsx"
     }
diff --git a/apps/www/src/app/docs/[slug]/page.tsx b/apps/www/src/app/docs/[slug]/page.tsx
index e29372c..51bea8a 100644
--- a/apps/www/src/app/docs/[slug]/page.tsx
+++ b/apps/www/src/app/docs/[slug]/page.tsx
@@ -8,6 +8,7 @@ import {
   PreviewErrorBoundary,
 } from "@/components/docs";
 import { getComponentSource } from "@/lib/code";
+import { formatPropsForApiTable, getComponentProps } from "@/lib/extract-props";
 import {
   type Component,
   getRegistryItem,
@@ -125,22 +126,17 @@ export default async function ComponentDocPage({
       </h3>
 
       <div className="mt-4">
-        <ApiTable
-          data={[
-            {
-              prop: "className",
-              type: "string",
-              default: "—",
-              description: "Additional CSS classes to apply",
-            },
-            {
-              prop: "...props",
-              type: "ComponentProps",
-              default: "—",
-              description: "All other props are passed to the root element",
-            },
-          ]}
-        />
+        {(() => {
+          const docs = getComponentProps(slug);
+          const props = docs[0]?.props ?? [];
+          return props.length > 0 ? (
+            <ApiTable data={formatPropsForApiTable(props)} />
+          ) : (
+            <p className="text-muted-foreground text-sm">
+              No props documentation available.
+            </p>
+          );
+        })()}
       </div>
 
       {/* Navigation */}
diff --git a/apps/www/src/lib/code.ts b/apps/www/src/lib/code.ts
index 3f788e9..0598ed4 100644
--- a/apps/www/src/lib/code.ts
+++ b/apps/www/src/lib/code.ts
@@ -13,72 +13,121 @@ function getPackageUiPath(): string {
   return path.join(__dirname, "..", "..", "..", "..", "packages", "ui");
 }
 
+/**
+ * Get the path to the apps/www directory.
+ */
+function getWwwPath(): string {
+  // From apps/www/src/lib/ -> apps/www (2 levels up)
+  return path.join(__dirname, "..", "..");
+}
+
+/**
+ * Registry item type for type safety.
+ */
+interface RegistryItem {
+  name: string;
+  files?: Array<{ path: string; type?: string }>;
+}
+
+/**
+ * Look up a component in a registry file.
+ *
+ * @param registryPath - Absolute path to the registry.json file
+ * @param componentName - The component name to find
+ * @returns The registry item if found, null otherwise
+ */
+function findInRegistry(
+  registryPath: string,
+  componentName: string,
+): RegistryItem | null {
+  try {
+    const registryContent = fs.readFileSync(registryPath, "utf-8");
+    const registry = JSON.parse(registryContent);
+    return (
+      registry.items.find((i: RegistryItem) => i.name === componentName) || null
+    );
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Extract source code from a file path at build time.
  * Uses React cache for deduplication during SSG.
  *
- * @param filePath - Relative path from packages/ui/
+ * @param filePath - Relative path from a base directory
+ * @param basePath - The base directory to resolve from
  * @returns The file contents as a string
  */
-export const extractCodeFromFilePath = cache((filePath: string): string => {
-  const absolutePath = path.join(getPackageUiPath(), filePath);
+export const extractCodeFromFilePath = cache(
+  (filePath: string, basePath?: string): string => {
+    const absolutePath = path.join(basePath || getPackageUiPath(), filePath);
 
-  try {
-    return fs.readFileSync(absolutePath, "utf-8");
-  } catch (error) {
-    console.error(`Failed to read file: ${absolutePath}`, error);
-    return `// Error: Could not load source code for ${filePath}`;
-  }
-});
+    try {
+      return fs.readFileSync(absolutePath, "utf-8");
+    } catch (error) {
+      console.error(`Failed to read file: ${absolutePath}`, error);
+      return `// Error: Could not load source code for ${filePath}`;
+    }
+  },
+);
 
 /**
  * Extract source code for a registry component by name.
- * Looks up the path in registry.json and reads the file.
+ * Looks up the path in registry.json files and reads the file.
+ *
+ * Checks packages/ui/registry.json first (distributable components),
+ * then falls back to apps/www/src/registry.json (legacy/demo components).
  *
  * @param componentName - The component name from registry.json
  * @returns The source code string
  */
 export const getComponentSource = cache((componentName: string): string => {
-  const registryPath = path.join(getPackageUiPath(), "registry.json");
+  const packageUiPath = getPackageUiPath();
+  const wwwPath = getWwwPath();
 
-  try {
-    const registryContent = fs.readFileSync(registryPath, "utf-8");
-    const registry = JSON.parse(registryContent);
-    const item = registry.items.find(
-      (i: { name: string }) => i.name === componentName,
-    );
+  // First, check packages/ui/registry.json (distributable components)
+  const packageRegistryPath = path.join(packageUiPath, "registry.json");
+  const packageItem = findInRegistry(packageRegistryPath, componentName);
 
-    if (!item || !item.files?.[0]?.path) {
-      return `// Component "${componentName}" not found in registry`;
-    }
+  if (packageItem?.files?.[0]?.path) {
+    return extractCodeFromFilePath(packageItem.files[0].path, packageUiPath);
+  }
 
-    return extractCodeFromFilePath(item.files[0].path);
-  } catch (error) {
-    console.error(`Error loading registry for "${componentName}"`, error);
-    return `// Error loading registry for "${componentName}"`;
+  // Fall back to apps/www/src/registry.json (legacy/demo components)
+  const wwwRegistryPath = path.join(wwwPath, "src", "registry.json");
+  const wwwItem = findInRegistry(wwwRegistryPath, componentName);
+
+  if (wwwItem?.files?.[0]?.path) {
+    return extractCodeFromFilePath(wwwItem.files[0].path, wwwPath);
   }
+
+  return `// Component "${componentName}" not found in registry`;
 });
 
 /**
  * Get the file path for a registry component.
  *
  * @param componentName - The component name from registry.json
- * @returns The relative file path from packages/ui/, or null if not found
+ * @returns The relative file path, or null if not found
  */
 export const getComponentFilePath = cache(
   (componentName: string): string | null => {
-    const registryPath = path.join(getPackageUiPath(), "registry.json");
+    const packageUiPath = getPackageUiPath();
+    const wwwPath = getWwwPath();
 
-    try {
-      const registryContent = fs.readFileSync(registryPath, "utf-8");
-      const registry = JSON.parse(registryContent);
-      const item = registry.items.find(
-        (i: { name: string }) => i.name === componentName,
-      );
-
-      return item?.files?.[0]?.path || null;
-    } catch {
-      return null;
+    // First, check packages/ui/registry.json
+    const packageRegistryPath = path.join(packageUiPath, "registry.json");
+    const packageItem = findInRegistry(packageRegistryPath, componentName);
+
+    if (packageItem?.files?.[0]?.path) {
+      return packageItem.files[0].path;
     }
+
+    // Fall back to apps/www/src/registry.json
+    const wwwRegistryPath = path.join(wwwPath, "src", "registry.json");
+    const wwwItem = findInRegistry(wwwRegistryPath, componentName);
+
+    return wwwItem?.files?.[0]?.path || null;
   },
 );
diff --git a/apps/www/src/registry.json b/apps/www/src/registry.json
index 793850d..a8168f5 100644
--- a/apps/www/src/registry.json
+++ b/apps/www/src/registry.json
@@ -803,31 +803,35 @@
     },
     {
       "name": "usage-meter",
-      "type": "registry:component",
+      "type": "registry:ui",
       "title": "Usage Meter",
       "description": "A linear progress meter for displaying usage/quota information with full Radix accessibility support.",
-      "dependencies": ["radix-ui"],
-      "registryDependencies": ["https://usage-ui.vercel.app/r/theme.json"],
+      "registryDependencies": [
+        "https://usage-ui.vercel.app/r/usage-meter.json",
+        "https://registry-starter.vercel.app/r/theme.json"
+      ],
       "files": [
         {
-          "path": "src/components/registry/usage-meter/usage-meter.tsx",
-          "type": "registry:component",
-          "target": "components/ui/usage-meter.tsx"
+          "path": "src/layouts/minimal-layout.tsx",
+          "type": "registry:file",
+          "target": "app/layout.tsx"
         }
       ]
     },
     {
       "name": "usage-meter-base",
-      "type": "registry:component",
+      "type": "registry:ui",
       "title": "Usage Meter (Base)",
       "description": "A lightweight linear progress meter for displaying usage/quota information without Radix dependency.",
-      "dependencies": [],
-      "registryDependencies": ["https://usage-ui.vercel.app/r/theme.json"],
+      "registryDependencies": [
+        "https://usage-ui.vercel.app/r/usage-meter-base.json",
+        "https://registry-starter.vercel.app/r/theme.json"
+      ],
       "files": [
         {
-          "path": "src/components/registry/usage-meter/usage-meter-base.tsx",
-          "type": "registry:component",
-          "target": "components/ui/usage-meter-base.tsx"
+          "path": "src/layouts/minimal-layout.tsx",
+          "type": "registry:file",
+          "target": "app/layout.tsx"
         }
       ]
     }
diff --git a/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx b/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
index 816b6f7..bf54947 100644
--- a/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
+++ b/packages/ui/src/components/registry/usage-meter/usage-meter-base.tsx
@@ -6,9 +6,9 @@ import { cn } from "@/lib/utils";
 
 const meterVariants = {
   default: "bg-primary",
-  success: "bg-[--meter-success]",
-  warning: "bg-[--meter-warning]",
-  danger: "bg-[--meter-danger]",
+  success: "bg-chart-2",
+  warning: "bg-chart-4",
+  danger: "bg-destructive",
 } as const;
 
 const meterSizes = {
@@ -86,7 +86,7 @@ const UsageMeterBase = React.forwardRef<HTMLDivElement, UsageMeterBaseProps>(
           aria-valuetext={`${clampedPercentage}%`}
           aria-label={label}
           className={cn(
-            "relative w-full overflow-hidden rounded-full bg-[--meter-track]",
+            "relative w-full overflow-hidden rounded-full bg-secondary",
             meterSizes[size],
             className,
           )}
diff --git a/packages/ui/src/components/registry/usage-meter/usage-meter.tsx b/packages/ui/src/components/registry/usage-meter/usage-meter.tsx
index 02400d7..56e2488 100644
--- a/packages/ui/src/components/registry/usage-meter/usage-meter.tsx
+++ b/packages/ui/src/components/registry/usage-meter/usage-meter.tsx
@@ -7,9 +7,9 @@ import { cn } from "@/lib/utils";
 
 const meterVariants = {
   default: "bg-primary",
-  success: "bg-[--meter-success]",
-  warning: "bg-[--meter-warning]",
-  danger: "bg-[--meter-danger]",
+  success: "bg-chart-2",
+  warning: "bg-chart-4",
+  danger: "bg-destructive",
 } as const;
 
 const meterSizes = {
@@ -90,7 +90,7 @@ const UsageMeter = React.forwardRef<
           value={value}
           max={safeMax}
           className={cn(
-            "relative w-full overflow-hidden rounded-full bg-[--meter-track]",
+            "relative w-full overflow-hidden rounded-full bg-secondary",
             meterSizes[size],
             className,
           )}
diff --git a/packages/ui/src/styles/globals.css b/packages/ui/src/styles/globals.css
index 5f642e4..36115f1 100644
--- a/packages/ui/src/styles/globals.css
+++ b/packages/ui/src/styles/globals.css
@@ -1,34 +1,7 @@
 @import "tailwindcss";
 
-@theme inline {
-  /* Usage UI - Meter Status Colors */
-  --color-meter-success: oklch(0.723 0.191 142.5);
-  --color-meter-warning: oklch(0.795 0.184 86.047);
-  --color-meter-danger: oklch(0.637 0.237 25.331);
-  --color-meter-info: oklch(0.623 0.214 259.1);
-
-  /* Usage UI - Meter Track Colors */
-  --color-meter-track: oklch(0.928 0.006 264.5);
-  --color-meter-track-foreground: oklch(0.45 0.03 264.5);
-}
-
-@layer base {
-  :root {
-    /* Meter CSS variables for direct use */
-    --meter-success: var(--color-meter-success);
-    --meter-warning: var(--color-meter-warning);
-    --meter-danger: var(--color-meter-danger);
-    --meter-info: var(--color-meter-info);
-    --meter-track: var(--color-meter-track);
-    --meter-track-foreground: var(--color-meter-track-foreground);
-  }
-
-  .dark {
-    --meter-success: oklch(0.627 0.194 142.5);
-    --meter-warning: oklch(0.695 0.184 86.047);
-    --meter-danger: oklch(0.577 0.237 25.331);
-    --meter-info: oklch(0.523 0.214 259.1);
-    --meter-track: oklch(0.269 0.006 264.5);
-    --meter-track-foreground: oklch(0.708 0.03 264.5);
-  }
-}
+/* Usage UI components use standard shadcn/ui CSS variables:
+ * - Variants: chart-2 (success), chart-4 (warning), destructive (danger)
+ * - Track: secondary
+ * Override these in your globals.css to customize meter appearance.
+ */