diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 741d9826..b4d146ea 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -35,6 +35,7 @@ None.
 ## Checklist
 
 - [ ] Component(s) follow the conventions in [AGENTS.md](../AGENTS.md).
+- [ ] UI changes follow [DESIGN.md](../DESIGN.md). Deviations:
 - [ ] New exports added to `packages/ui/src/index.ts`.
 - [ ] Tests added (unit + visual, as applicable).
 - [ ] CHANGELOG note added under `[Unreleased]` for user-facing changes.
diff --git a/AGENTS.md b/AGENTS.md
index 9ce51f90..2ddc0d1f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,8 +64,9 @@ Repository-wide docs (audience = contributors, not just agents):
 
 ## Quick reference
 
-The two most-violated rules in PR review history:
+The most-violated rules in PR review history:
 
+0. **Design rules are mandatory for UI work.** Any UI suggestion or component/site change must follow [`DESIGN.md`](./DESIGN.md) and the machine-readable tokens in [`packages/design/tokens.json`](./packages/design/tokens.json). List any intentional deviation in the PR body.
 1. **Workspace gates green at HEAD** ([R6](./docs/agents/RULES.md#r6--workspace-gates-green-at-head)). Touched-file passes alone are not ship-OK. Run `pnpm -F @vllnt/ui lint && pnpm -F @vllnt/ui exec tsc --noEmit --project tsconfig.build.json && pnpm build && pnpm test:once` — all must be green.
 2. **PR body matches HEAD** ([R3](./docs/agents/RULES.md#r3--pr-body-matches-head)). After every push, rewrite the body to match the current head. Stale claims block ship.
 3. **Linked issue required** ([R5](./docs/agents/RULES.md#r5--linked-issue-required)). Every PR must reference a GitHub issue. Accepted keywords: `close` / `closes` / `closed`, `fix` / `fixes` / `fixed`, `resolve` / `resolves` / `resolved`, or repo phrases `Part of` / `Related to` — all case-insensitive, optional colon — followed by `#123` or `owner/repo#123`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0535cb88..46792c69 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,6 +7,7 @@ Thanks for wanting to contribute. This repo welcomes issues, bug reports, and PR
 - Be respectful. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
 - Security-sensitive reports go through [SECURITY.md](SECURITY.md), **not** public issues.
 - Every change keeps the repo shippable: lint, typecheck, tests, and build pass on `main`.
+- UI changes must follow [DESIGN.md](DESIGN.md) and the token contract in [packages/design/tokens.json](packages/design/tokens.json). Document intentional deviations in the PR body.
 
 ## Development setup
 
diff --git a/DESIGN.md b/DESIGN.md
index fbe9457b..548a0ea8 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -4,9 +4,9 @@
 > Humans read this file. Agents read it too — every UI suggestion must follow it.
 
 This is the **canonical** brand & design guideline for the library. The full
-machine-readable token set lives in `packages/design/tokens.json` (shipping in a
-follow-up to keep this PR scoped). Site renderings at `/design` will mirror this
-file once that route lands.
+machine-readable token set lives in `packages/design/tokens.json`, is documented
+in `packages/design/README.md`, and is mirrored publicly at `/r/design.json`.
+The site rendering at `/design` reads this file directly.
 
 ---
 
@@ -51,6 +51,10 @@ Tokens live as CSS variables in `packages/ui/themes/default.css`. Components
 **always** consume tokens — never raw hex. The token set is versioned with the
 library.
 
+Machine clients use `packages/design/tokens.json`. The JSON schema is
+documented in `packages/design/tokens.schema.json` and groups tokens by color,
+typography, spacing, radius, elevation, motion, and iconography.
+
 ### Semantic tokens (consumer-facing)
 
 | Token | Light role | Dark role |
diff --git a/apps/registry/app/design.txt/route.ts b/apps/registry/app/design.txt/route.ts
new file mode 100644
index 00000000..6d6cd852
--- /dev/null
+++ b/apps/registry/app/design.txt/route.ts
@@ -0,0 +1,20 @@
+import { getDesignGuideMarkdown } from "@/lib/design-guide";
+
+const TEXT_HEADERS = new Headers([
+  [
+    "Cache-Control",
+    "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
+  ],
+  ["Content-Type", "text/plain; charset=utf-8"],
+]);
+
+export const dynamic = "force-static";
+export const revalidate = 86_400;
+
+async function getDesignText(): Promise<Response> {
+  const body = await getDesignGuideMarkdown();
+
+  return new Response(body, { headers: TEXT_HEADERS });
+}
+
+export { getDesignText as GET };
diff --git a/apps/registry/app/design/page.tsx b/apps/registry/app/design/page.tsx
new file mode 100644
index 00000000..def120fb
--- /dev/null
+++ b/apps/registry/app/design/page.tsx
@@ -0,0 +1,180 @@
+import React, { type ComponentProps, type ReactNode } from "react";
+
+import { MDXContent, Sidebar } from "@vllnt/ui";
+import type { Metadata } from "next";
+
+import {
+  designTokens,
+  extractDesignGuideSections,
+  getDesignGuideMarkdown,
+  slugifyHeading,
+} from "@/lib/design-guide";
+import { jsonLdScript } from "@/lib/jsonld";
+import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
+import { canonical } from "@/lib/seo";
+import { getSidebarSections } from "@/lib/sidebar-sections";
+
+const DESCRIPTION =
+  "Canonical VLLNT UI design rules, tokens, component patterns, accessibility expectations, and agent-facing guidance.";
+
+export const dynamic = "force-static";
+export const revalidate = 86_400;
+
+export const metadata: Metadata = {
+  alternates: { canonical: canonical("/design") },
+  description: DESCRIPTION,
+  openGraph: generateOGMetadata({
+    description: DESCRIPTION,
+    title: "VLLNT UI Design Guide",
+    type: "docs",
+  }),
+  title: "Design Guide",
+  twitter: generateTwitterMetadata({
+    description: DESCRIPTION,
+    title: "VLLNT UI Design Guide",
+    type: "docs",
+  }),
+};
+
+function getNodeText(children: ReactNode): string {
+  return React.Children.toArray(children)
+    .map((child) => {
+      if (typeof child === "string" || typeof child === "number") {
+        return String(child);
+      }
+      return "";
+    })
+    .join(" ")
+    .trim();
+}
+
+function DesignHeadingTwo({ children, ...props }: ComponentProps<"h2">) {
+  const id = slugifyHeading(getNodeText(children));
+
+  return (
+    <h2
+      className="mt-10 scroll-mt-24 text-2xl font-semibold"
+      id={id}
+      {...props}
+    >
+      {children}
+    </h2>
+  );
+}
+
+function DesignHeadingThree({ children, ...props }: ComponentProps<"h3">) {
+  const id = slugifyHeading(getNodeText(children));
+
+  return (
+    <h3 className="mt-8 scroll-mt-24 text-xl font-semibold" id={id} {...props}>
+      {children}
+    </h3>
+  );
+}
+
+export default async function DesignPage() {
+  const markdown = await getDesignGuideMarkdown();
+  const sections = extractDesignGuideSections(markdown);
+  const semanticColorCount = Object.keys(designTokens.color.semantic).length;
+  const spacingCount = Object.keys(designTokens.spacing.scale).length;
+
+  const techArticleLd = {
+    "@context": "https://schema.org",
+    "@type": "TechArticle",
+    about: ["React component library", "design system", "accessibility"],
+    author: {
+      "@type": "Organization",
+      name: "VLLNT",
+    },
+    description: DESCRIPTION,
+    headline: "VLLNT UI Design Guide",
+    publisher: {
+      "@type": "Organization",
+      name: "VLLNT",
+    },
+    url: canonical("/design"),
+  };
+
+  return (
+    <>
+      <Sidebar sections={getSidebarSections()} />
+      <main className="flex-1 overflow-y-auto bg-background">
+        <script
+          dangerouslySetInnerHTML={{ __html: jsonLdScript(techArticleLd) }}
+          type="application/ld+json"
+        />
+        <div className="mx-auto grid max-w-7xl gap-8 px-4 py-12 lg:grid-cols-[minmax(0,1fr)_18rem] lg:px-8">
+          <article className="min-w-0">
+            <div className="mb-8 border-b border-border pb-8">
+              <p className="mb-3 text-sm font-medium text-muted-foreground">
+                Agent-consumable brand guide
+              </p>
+              <h1 className="text-4xl font-semibold">VLLNT UI Design Guide</h1>
+              <p className="mt-4 max-w-3xl text-lg leading-8 text-muted-foreground">
+                The canonical rules for brand, tokens, layout, motion,
+                accessibility, and component composition across the library.
+              </p>
+            </div>
+            <MDXContent
+              components={{
+                h2: DesignHeadingTwo,
+                h3: DesignHeadingThree,
+              }}
+              content={markdown}
+            />
+          </article>
+
+          <aside className="lg:sticky lg:top-8 lg:self-start">
+            <div className="rounded-lg border border-border bg-card p-4">
+              <h2 className="text-sm font-semibold">Contents</h2>
+              <nav aria-label="Design guide sections" className="mt-4">
+                <ol className="space-y-2">
+                  {sections.map((section) => (
+                    <li key={section.id}>
+                      <a
+                        className="text-sm text-muted-foreground hover:text-foreground"
+                        href={`#${section.id}`}
+                      >
+                        {section.title}
+                      </a>
+                    </li>
+                  ))}
+                </ol>
+              </nav>
+            </div>
+
+            <div className="mt-4 rounded-lg border border-border bg-card p-4">
+              <h2 className="text-sm font-semibold">Token contract</h2>
+              <dl className="mt-4 grid grid-cols-2 gap-3 text-sm">
+                <div>
+                  <dt className="text-muted-foreground">Version</dt>
+                  <dd className="font-medium">{designTokens.version}</dd>
+                </div>
+                <div>
+                  <dt className="text-muted-foreground">Colors</dt>
+                  <dd className="font-medium">{semanticColorCount}</dd>
+                </div>
+                <div>
+                  <dt className="text-muted-foreground">Spacing</dt>
+                  <dd className="font-medium">{spacingCount}</dd>
+                </div>
+                <div>
+                  <dt className="text-muted-foreground">Icons</dt>
+                  <dd className="font-medium">
+                    {designTokens.iconography.library}
+                  </dd>
+                </div>
+              </dl>
+              <a
+                className="mt-4 inline-flex text-sm font-medium text-primary underline underline-offset-4"
+                href="/r/design.json"
+              >
+                View design tokens JSON
+              </a>
+            </div>
+          </aside>
+        </div>
+      </main>
+    </>
+  );
+}
diff --git a/apps/registry/app/llms-full.txt/route.ts b/apps/registry/app/llms-full.txt/route.ts
index c1c5fb42..9df2894e 100644
--- a/apps/registry/app/llms-full.txt/route.ts
+++ b/apps/registry/app/llms-full.txt/route.ts
@@ -1,26 +1,39 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 
+import { getDesignGuideMarkdown } from "@/lib/design-guide";
+
 import registry from "../../registry.json";
 
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+const TEXT_HEADERS = new Headers([
+  [
+    "Cache-Control",
+    "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
+  ],
+  ["Content-Type", "text/plain; charset=utf-8"],
+]);
 
 type RegistryItem = {
-  readonly name: string;
-  readonly title: string;
-  readonly description: string;
   readonly category: string;
   readonly dependencies?: readonly string[];
+  readonly description: string;
+  readonly name: string;
   readonly registryDependencies?: readonly string[];
+  readonly title: string;
 };
 
-const DOC_PAGES: ReadonlyArray<{ slug: string; title: string }> = [
+const DOC_PAGES: readonly { slug: string; title: string }[] = [
   { slug: "home", title: "Get Started" },
   { slug: "docs", title: "Documentation" },
   { slug: "philosophy", title: "Philosophy" },
   { slug: "components", title: "Components Overview" },
 ];
 
+function getRegistryItems(): readonly RegistryItem[] {
+  return (registry as { readonly items: readonly RegistryItem[] }).items;
+}
+
 function stripFrontmatter(source: string): string {
   if (!source.startsWith("---")) return source;
   const end = source.indexOf("\n---", 3);
@@ -28,13 +41,8 @@ function stripFrontmatter(source: string): string {
   return source.slice(end + 4).replace(/^\n+/, "");
 }
 
-async function readDocPage(slug: string): Promise<string> {
-  const file = path.join(
-    process.cwd(),
-    "content",
-    "pages",
-    `${slug}.mdx`,
-  );
+async function readDocumentPage(slug: string): Promise<string> {
+  const file = path.join(process.cwd(), "content", "pages", `${slug}.mdx`);
   try {
     const raw = await readFile(file, "utf8");
     return stripFrontmatter(raw).trim();
@@ -43,78 +51,109 @@ async function readDocPage(slug: string): Promise<string> {
   }
 }
 
-async function buildLlmsFullTxt(): Promise<string> {
-  const items = (registry as { readonly items: readonly RegistryItem[] }).items;
-
-  const lines: string[] = [];
-
-  lines.push("# VLLNT UI — Full Reference");
-  lines.push("");
-  lines.push(
+function buildIntroLines(items: readonly RegistryItem[]): readonly string[] {
+  return [
+    "# VLLNT UI - Full Reference",
+    "",
     "> One-fetch, complete agent context for the VLLNT UI registry. " +
       `${items.length} components, install via shadcn CLI against /r/<name>.json. ` +
       `Site: ${SITE_URL}`,
+    "",
+  ];
+}
+
+function buildInstallLines(): readonly string[] {
+  return [
+    "## Install",
+    "",
+    "```bash",
+    `pnpm dlx shadcn@latest add ${SITE_URL}/r/<name>.json`,
+    `# Or with npm: npx shadcn@latest add ${SITE_URL}/r/<name>.json`,
+    "```",
+    "",
+  ];
+}
+
+async function buildDocumentLines(): Promise<readonly string[]> {
+  const pageSections = await Promise.all(
+    DOC_PAGES.map(async (page) => {
+      const body = await readDocumentPage(page.slug);
+      if (!body) return [];
+      const source = `${SITE_URL}/${page.slug === "home" ? "" : page.slug}`;
+      return [`## ${page.title}`, "", `Source: ${source}`, "", body, ""];
+    }),
   );
-  lines.push("");
-
-  lines.push("## Install");
-  lines.push("");
-  lines.push("```bash");
-  lines.push(`pnpm dlx shadcn@latest add ${SITE_URL}/r/<name>.json`);
-  lines.push(`# Or with npm: npx shadcn@latest add ${SITE_URL}/r/<name>.json`);
-  lines.push("```");
-  lines.push("");
-
-  for (const page of DOC_PAGES) {
-    const body = await readDocPage(page.slug);
-    if (!body) continue;
-    lines.push(`## ${page.title}`);
-    lines.push("");
-    lines.push(`Source: ${SITE_URL}/${page.slug === "home" ? "" : page.slug}`);
-    lines.push("");
-    lines.push(body);
-    lines.push("");
-  }
 
-  lines.push("## Components");
-  lines.push("");
-  lines.push(
+  return pageSections.flat();
+}
+
+async function buildDesignLines(): Promise<readonly string[]> {
+  const designGuide = await getDesignGuideMarkdown();
+  return [
+    "## Design Guide",
+    "",
+    `Source: ${SITE_URL}/design`,
+    `Tokens: ${SITE_URL}/r/design.json`,
+    "",
+    designGuide,
+    "",
+  ];
+}
+
+function buildComponentLines(item: RegistryItem): readonly string[] {
+  return [
+    `### ${item.title}`,
+    "",
+    `- Slug: \`${item.name}\``,
+    `- Category: \`${item.category}\``,
+    `- Description: ${item.description}`,
+    `- Page: ${SITE_URL}/components/${item.name}`,
+    `- Schema: ${SITE_URL}/r/${item.name}.json`,
+    ...(item.dependencies?.length
+      ? [`- npm deps: ${item.dependencies.join(", ")}`]
+      : []),
+    ...(item.registryDependencies?.length
+      ? [`- registry deps: ${item.registryDependencies.join(", ")}`]
+      : []),
+    `- Install: \`pnpm dlx shadcn@latest add ${SITE_URL}/r/${item.name}.json\``,
+    "",
+  ];
+}
+
+function buildComponentsReferenceLines(
+  items: readonly RegistryItem[],
+): readonly string[] {
+  return [
+    "## Components",
+    "",
     `${items.length} components total. Each entry links to a machine-readable JSON descriptor at /r/<name>.json.`,
-  );
-  lines.push("");
-
-  for (const item of [...items].sort((a, b) => a.name.localeCompare(b.name))) {
-    lines.push(`### ${item.title}`);
-    lines.push("");
-    lines.push(`- Slug: \`${item.name}\``);
-    lines.push(`- Category: \`${item.category}\``);
-    lines.push(`- Description: ${item.description}`);
-    lines.push(`- Page: ${SITE_URL}/components/${item.name}`);
-    lines.push(`- Schema: ${SITE_URL}/r/${item.name}.json`);
-    if (item.dependencies && item.dependencies.length > 0) {
-      lines.push(`- npm deps: ${item.dependencies.join(", ")}`);
-    }
-    if (item.registryDependencies && item.registryDependencies.length > 0) {
-      lines.push(`- registry deps: ${item.registryDependencies.join(", ")}`);
-    }
-    lines.push(
-      `- Install: \`pnpm dlx shadcn@latest add ${SITE_URL}/r/${item.name}.json\``,
-    );
-    lines.push("");
-  }
+    "",
+    ...[...items]
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .flatMap(buildComponentLines),
+  ];
+}
 
-  return lines.join("\n");
+async function buildLlmsFullTxt(): Promise<string> {
+  const items = getRegistryItems();
+  const documentLines = await buildDocumentLines();
+  const designLines = await buildDesignLines();
+
+  return [
+    ...buildIntroLines(items),
+    ...buildInstallLines(),
+    ...documentLines,
+    ...designLines,
+    ...buildComponentsReferenceLines(items),
+  ].join("\n");
 }
 
 export const dynamic = "force-static";
-export const revalidate = 86400;
+export const revalidate = 86_400;
 
-export async function GET(): Promise<Response> {
+async function getLlmsFullTxt(): Promise<Response> {
   const body = await buildLlmsFullTxt();
-  return new Response(body, {
-    headers: {
-      "Content-Type": "text/plain; charset=utf-8",
-      "Cache-Control": "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
-    },
-  });
+  return new Response(body, { headers: TEXT_HEADERS });
 }
+
+export { getLlmsFullTxt as GET };
diff --git a/apps/registry/app/llms.txt/route.ts b/apps/registry/app/llms.txt/route.ts
index 32130fb2..f1bbaf98 100644
--- a/apps/registry/app/llms.txt/route.ts
+++ b/apps/registry/app/llms.txt/route.ts
@@ -1,12 +1,19 @@
 import registry from "../../registry.json";
 
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+const TEXT_HEADERS = new Headers([
+  [
+    "Cache-Control",
+    "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
+  ],
+  ["Content-Type", "text/plain; charset=utf-8"],
+]);
 
 type RegistryItem = {
+  readonly category: string;
+  readonly description: string;
   readonly name: string;
   readonly title: string;
-  readonly description: string;
-  readonly category: string;
 };
 
 const CATEGORY_ORDER: readonly string[] = [
@@ -24,103 +31,125 @@ const CATEGORY_ORDER: readonly string[] = [
   "utility",
 ];
 
-const CATEGORY_LABEL: Record<string, string> = {
-  ai: "AI",
-  billing: "Billing & Plans",
-  content: "Content",
-  core: "Core primitives",
-  data: "Data",
-  "data-display": "Data display",
-  educational: "Educational",
-  form: "Form",
-  learning: "Learning",
-  navigation: "Navigation",
-  overlay: "Overlay",
-  utility: "Utility",
-};
+const CATEGORY_LABEL = new Map<string, string>([
+  ["ai", "AI"],
+  ["billing", "Billing & Plans"],
+  ["content", "Content"],
+  ["core", "Core primitives"],
+  ["data", "Data"],
+  ["data-display", "Data display"],
+  ["educational", "Educational"],
+  ["form", "Form"],
+  ["learning", "Learning"],
+  ["navigation", "Navigation"],
+  ["overlay", "Overlay"],
+  ["utility", "Utility"],
+]);
 
-function buildLlmsTxt(): string {
-  const items = (registry as { readonly items: readonly RegistryItem[] }).items;
+function getRegistryItems(): readonly RegistryItem[] {
+  return (registry as { readonly items: readonly RegistryItem[] }).items;
+}
 
-  const grouped = new Map<string, RegistryItem[]>();
-  for (const item of items) {
-    const bucket = grouped.get(item.category) ?? [];
-    bucket.push(item);
-    grouped.set(item.category, bucket);
-  }
+function groupItems(
+  items: readonly RegistryItem[],
+): ReadonlyMap<string, readonly RegistryItem[]> {
+  return items.reduce((groups, item) => {
+    const bucket = groups.get(item.category) ?? [];
+    groups.set(item.category, [...bucket, item]);
+    return groups;
+  }, new Map<string, readonly RegistryItem[]>());
+}
 
-  const sortedCategories = [
-    ...CATEGORY_ORDER.filter((c) => grouped.has(c)),
+function getSortedCategories(
+  grouped: ReadonlyMap<string, readonly RegistryItem[]>,
+): readonly string[] {
+  return [
+    ...CATEGORY_ORDER.filter((category) => grouped.has(category)),
     ...[...grouped.keys()]
-      .filter((c) => !CATEGORY_ORDER.includes(c))
+      .filter((category) => !CATEGORY_ORDER.includes(category))
       .sort(),
   ];
+}
 
-  const lines: string[] = [];
-
-  lines.push("# VLLNT UI");
-  lines.push("");
-  lines.push(
+function buildIntroLines(items: readonly RegistryItem[]): readonly string[] {
+  return [
+    "# VLLNT UI",
+    "",
     "> Agent-first React component registry. " +
       `${items.length} accessible components built on Radix UI, Tailwind CSS, and CVA. ` +
       "Install via the shadcn CLI against any /r/<name>.json endpoint.",
-  );
-  lines.push("");
+    "",
+  ];
+}
 
-  lines.push("## Docs");
-  lines.push("");
-  lines.push(`- [Get Started](${SITE_URL}/): install and use any component`);
-  lines.push(
+function buildDocumentationLines(): readonly string[] {
+  return [
+    "## Docs",
+    "",
+    `- [Get Started](${SITE_URL}/): install and use any component`,
     `- [Documentation](${SITE_URL}/docs): theming, registry usage, conventions`,
-  );
-  lines.push(
     `- [Philosophy](${SITE_URL}/philosophy): design principles and component patterns`,
-  );
-  lines.push(
+    `- [Design guide](${SITE_URL}/design): brand, tokens, accessibility, and UI rules`,
     `- [Components index](${SITE_URL}/components): browse all components by category`,
-  );
-  lines.push("");
+    "",
+  ];
+}
 
-  lines.push("## Registry API");
-  lines.push("");
-  lines.push(
+function buildRegistryLines(): readonly string[] {
+  return [
+    "## Registry API",
+    "",
     `- [Registry index](${SITE_URL}/r/registry.json): full machine-readable list of all components`,
-  );
-  lines.push(
+    `- [Design tokens](${SITE_URL}/r/design.json): machine-readable VLLNT UI token contract`,
     `- [Sitemap](${SITE_URL}/sitemap.xml): every public route, refreshed per deploy`,
-  );
-  lines.push(
     "- Install command: `pnpm dlx shadcn@latest add " +
       `${SITE_URL}/r/<name>.json` +
       "`",
-  );
-  lines.push("");
-
-  for (const category of sortedCategories) {
-    const bucket = grouped.get(category);
-    if (!bucket || bucket.length === 0) continue;
-    const label = CATEGORY_LABEL[category] ?? category;
-    lines.push(`## Components — ${label}`);
-    lines.push("");
-    for (const item of [...bucket].sort((a, b) => a.name.localeCompare(b.name))) {
-      lines.push(
+    "",
+  ];
+}
+
+function buildCategoryLines(
+  category: string,
+  grouped: ReadonlyMap<string, readonly RegistryItem[]>,
+): readonly string[] {
+  const bucket = grouped.get(category);
+  if (!bucket || bucket.length === 0) return [];
+  const label = CATEGORY_LABEL.get(category) ?? category;
+  const itemLines = [...bucket]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(
+      (item) =>
         `- [${item.title}](${SITE_URL}/components/${item.name}): ${item.description}`,
-      );
-    }
-    lines.push("");
-  }
+    );
 
-  return lines.join("\n");
+  return [`## Components - ${label}`, "", ...itemLines, ""];
+}
+
+function buildComponentLines(
+  items: readonly RegistryItem[],
+): readonly string[] {
+  const grouped = groupItems(items);
+  return getSortedCategories(grouped).flatMap((category) =>
+    buildCategoryLines(category, grouped),
+  );
+}
+
+function buildLlmsTxt(): string {
+  const items = getRegistryItems();
+  return [
+    ...buildIntroLines(items),
+    ...buildDocumentationLines(),
+    ...buildRegistryLines(),
+    ...buildComponentLines(items),
+  ].join("\n");
 }
 
 export const dynamic = "force-static";
-export const revalidate = 86400;
-
-export function GET(): Response {
-  return new Response(buildLlmsTxt(), {
-    headers: {
-      "Content-Type": "text/plain; charset=utf-8",
-      "Cache-Control": "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
-    },
-  });
+export const revalidate = 86_400;
+
+function getLlmsTxt(): Response {
+  return new Response(buildLlmsTxt(), { headers: TEXT_HEADERS });
 }
+
+export { getLlmsTxt as GET };
diff --git a/apps/registry/app/r/design.json/route.ts b/apps/registry/app/r/design.json/route.ts
new file mode 100644
index 00000000..3e60391e
--- /dev/null
+++ b/apps/registry/app/r/design.json/route.ts
@@ -0,0 +1,19 @@
+import { NextResponse } from "next/server";
+
+import { designTokens } from "@/lib/design-guide";
+
+const JSON_HEADERS = new Headers([
+  [
+    "Cache-Control",
+    "public, max-age=0, s-maxage=86400, stale-while-revalidate=604800",
+  ],
+]);
+
+export const dynamic = "force-static";
+export const revalidate = 86_400;
+
+function getDesignTokens(): Response {
+  return NextResponse.json(designTokens, { headers: JSON_HEADERS });
+}
+
+export { getDesignTokens as GET };
diff --git a/apps/registry/app/sitemap.ts b/apps/registry/app/sitemap.ts
index 816f585b..a8491529 100644
--- a/apps/registry/app/sitemap.ts
+++ b/apps/registry/app/sitemap.ts
@@ -8,59 +8,93 @@ type RegistryItem = {
   readonly name: string;
 };
 
-export default function sitemap(): MetadataRoute.Sitemap {
-  const lastModified = new Date();
+type SitemapEntry = MetadataRoute.Sitemap[number];
+type ChangeFrequency = NonNullable<SitemapEntry["changeFrequency"]>;
+type SitemapEntryInput = {
+  readonly changeFrequency: ChangeFrequency;
+  readonly lastModified: Date;
+  readonly priority: number;
+  readonly url: string;
+};
 
-  const staticRoutes: MetadataRoute.Sitemap = [
-    {
-      url: SITE_URL,
-      lastModified,
-      changeFrequency: "weekly",
-      priority: 1.0,
-    },
-    {
-      url: `${SITE_URL}/components`,
-      lastModified,
-      changeFrequency: "weekly",
-      priority: 1.0,
-    },
-    {
-      url: `${SITE_URL}/docs`,
-      lastModified,
-      changeFrequency: "weekly",
-      priority: 0.8,
-    },
+function getRegistryItems(): readonly RegistryItem[] {
+  return (registry as { readonly items: readonly RegistryItem[] }).items;
+}
+
+function entry({
+  changeFrequency,
+  lastModified,
+  priority,
+  url,
+}: SitemapEntryInput): SitemapEntry {
+  return { changeFrequency, lastModified, priority, url };
+}
+
+function staticRoutes(lastModified: Date): MetadataRoute.Sitemap {
+  const routes = [
+    { changeFrequency: "weekly", priority: 1, url: SITE_URL },
+    { changeFrequency: "weekly", priority: 1, url: `${SITE_URL}/components` },
+    { changeFrequency: "weekly", priority: 0.8, url: `${SITE_URL}/docs` },
     {
-      url: `${SITE_URL}/philosophy`,
-      lastModified,
       changeFrequency: "monthly",
       priority: 0.6,
+      url: `${SITE_URL}/philosophy`,
     },
-  ];
+    { changeFrequency: "monthly", priority: 0.8, url: `${SITE_URL}/design` },
+  ] satisfies readonly Omit<SitemapEntryInput, "lastModified">[];
 
-  const items = (registry as { readonly items: readonly RegistryItem[] }).items;
-
-  const componentRoutes: MetadataRoute.Sitemap = items.map((item) => ({
-    url: `${SITE_URL}/components/${item.name}`,
-    lastModified,
-    changeFrequency: "weekly",
-    priority: 0.7,
-  }));
+  return routes.map((route) => entry({ ...route, lastModified }));
+}
 
-  const registryEndpoints: MetadataRoute.Sitemap = [
-    {
-      url: `${SITE_URL}/r/registry.json`,
+function componentRoutes(
+  items: readonly RegistryItem[],
+  lastModified: Date,
+): MetadataRoute.Sitemap {
+  return items.map((item) =>
+    entry({
+      changeFrequency: "weekly",
       lastModified,
+      priority: 0.7,
+      url: `${SITE_URL}/components/${item.name}`,
+    }),
+  );
+}
+
+function registryRoutes(
+  items: readonly RegistryItem[],
+  lastModified: Date,
+): MetadataRoute.Sitemap {
+  return [
+    entry({
       changeFrequency: "weekly",
+      lastModified,
       priority: 0.3,
-    },
-    ...items.map((item) => ({
-      url: `${SITE_URL}/r/${item.name}.json`,
+      url: `${SITE_URL}/r/registry.json`,
+    }),
+    entry({
+      changeFrequency: "monthly",
       lastModified,
-      changeFrequency: "weekly" as const,
       priority: 0.3,
-    })),
+      url: `${SITE_URL}/r/design.json`,
+    }),
+    ...items.map((item) =>
+      entry({
+        changeFrequency: "weekly",
+        lastModified,
+        priority: 0.3,
+        url: `${SITE_URL}/r/${item.name}.json`,
+      }),
+    ),
   ];
+}
 
-  return [...staticRoutes, ...componentRoutes, ...registryEndpoints];
+export default function sitemap(): MetadataRoute.Sitemap {
+  const lastModified = new Date();
+  const items = getRegistryItems();
+
+  return [
+    ...staticRoutes(lastModified),
+    ...componentRoutes(items, lastModified),
+    ...registryRoutes(items, lastModified),
+  ];
 }
diff --git a/apps/registry/components/footer/footer.tsx b/apps/registry/components/footer/footer.tsx
index 1f4787bb..c20aab5e 100644
--- a/apps/registry/components/footer/footer.tsx
+++ b/apps/registry/components/footer/footer.tsx
@@ -12,50 +12,52 @@ const LICENSE_URL = "https://github.com/vllnt/ui/blob/main/LICENSE";
 const COC_URL = "https://github.com/vllnt/ui/blob/main/CODE_OF_CONDUCT.md";
 
 type FooterLink = {
+  readonly external?: boolean;
   readonly href: string;
   readonly label: string;
-  readonly external?: boolean;
 };
 
 type FooterColumn = {
-  readonly title: string;
   readonly links: readonly FooterLink[];
+  readonly title: string;
 };
 
 const COLUMNS: readonly FooterColumn[] = [
   {
-    title: "Library",
     links: [
       { href: "/components", label: "Components" },
       { href: "/docs", label: "Docs" },
       { href: "/philosophy", label: "Philosophy" },
+      { href: "/design", label: "Design" },
     ],
+    title: "Library",
   },
   {
-    title: "Resources",
     links: [
       { external: true, href: STORYBOOK_URL, label: "Storybook" },
       { href: "/r/registry.json", label: "Registry JSON" },
+      { href: "/r/design.json", label: "Design tokens" },
       { href: "/llms.txt", label: "llms.txt" },
       { href: "/mcp", label: "MCP" },
       { external: true, href: GITHUB_URL, label: "GitHub" },
     ],
+    title: "Resources",
   },
   {
-    title: "Community",
     links: [
       { external: true, href: REQUEST_URL, label: "Request a component" },
       { external: true, href: REPORT_URL, label: "Report a bug" },
       { external: true, href: DISCUSSIONS_URL, label: "Discussions" },
       { external: true, href: SPONSOR_URL, label: "Sponsor" },
     ],
+    title: "Community",
   },
   {
-    title: "Legal",
     links: [
       { external: true, href: LICENSE_URL, label: "License (MIT)" },
       { external: true, href: COC_URL, label: "Code of Conduct" },
     ],
+    title: "Legal",
   },
 ];
 
diff --git a/apps/registry/components/header/header.tsx b/apps/registry/components/header/header.tsx
index 54842b4b..3ca32ee7 100644
--- a/apps/registry/components/header/header.tsx
+++ b/apps/registry/components/header/header.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { NavbarSaas, SearchDialog } from "@vllnt/ui";
-import { Github } from "lucide-react";
+import { ExternalLink } from "lucide-react";
 import { useRouter } from "next/navigation";
 
 import registryData from "@/registry.json";
@@ -19,6 +19,7 @@ export function Header() {
   const navItems = [
     { href: "/", title: "Get Started" },
     { href: "/philosophy", title: "Philosophy" },
+    { href: "/design", title: "Design" },
     { href: "/components", title: "Components" },
   ];
 
@@ -53,7 +54,7 @@ export function Header() {
             rel="noreferrer"
             target="_blank"
           >
-            <Github className="h-4 w-4" />
+            <ExternalLink className="h-4 w-4" />
           </a>
         </div>
       }
diff --git a/apps/registry/lib/design-guide.ts b/apps/registry/lib/design-guide.ts
new file mode 100644
index 00000000..623b6577
--- /dev/null
+++ b/apps/registry/lib/design-guide.ts
@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export type DesignGuideSection = {
+  readonly id: string;
+  readonly title: string;
+};
+
+const DESIGN_FILE_CANDIDATES = [
+  path.join(process.cwd(), "DESIGN.md"),
+  path.join(process.cwd(), "..", "..", "DESIGN.md"),
+];
+
+export function slugifyHeading(value: string): string {
+  return value
+    .toLowerCase()
+    .replaceAll(/`|\*/g, "")
+    .replaceAll(/[^\da-z]+/g, "-")
+    .replaceAll(/^-|-$/g, "");
+}
+
+export function extractDesignGuideSections(
+  markdown: string,
+): DesignGuideSection[] {
+  return markdown
+    .split("\n")
+    .filter((line) => line.startsWith("## "))
+    .map((line) => line.replace(/^##\s+/, "").trim())
+    .filter(Boolean)
+    .map((title) => ({ id: slugifyHeading(title), title }));
+}
+
+export async function getDesignGuideMarkdown(): Promise<string> {
+  try {
+    return await Promise.any(
+      DESIGN_FILE_CANDIDATES.map(async (filePath) => {
+        const content = await readFile(filePath, "utf8");
+        return content.trim();
+      }),
+    );
+  } catch {
+    throw new Error("DESIGN.md could not be found");
+  }
+}
+
+export { default as designTokens } from "../../../packages/design/tokens.json";
diff --git a/apps/registry/registry.json b/apps/registry/registry.json
index 029360c6..1fb2d6ac 100644
--- a/apps/registry/registry.json
+++ b/apps/registry/registry.json
@@ -2291,7 +2291,10 @@
       ],
       "registryDependencies": [],
       "dependencies": [
-        "@vllnt/ui@^0.2.1"
+        "@vllnt/ui@^0.2.1",
+        "@mdx-js/mdx@^3.1.1",
+        "react-markdown@^10.1.0",
+        "remark-gfm@^4.0.1"
       ],
       "category": "content",
       "version": "0.2.1",
diff --git a/apps/registry/registry/default/mdx-content/mdx-content.tsx b/apps/registry/registry/default/mdx-content/mdx-content.tsx
index fe098d1a..9b268b12 100644
--- a/apps/registry/registry/default/mdx-content/mdx-content.tsx
+++ b/apps/registry/registry/default/mdx-content/mdx-content.tsx
@@ -2,6 +2,7 @@ import { evaluate } from "@mdx-js/mdx";
 import type React from "react";
 import * as runtime from "react/jsx-runtime";
 import ReactMarkdown, { type Components } from "react-markdown";
+import remarkGfm from "remark-gfm";
 
 import { CodeBlock } from "@vllnt/ui";
 
@@ -135,6 +136,8 @@ const proseClasses = [
   "prose-img:rounded-lg prose-img:border prose-img:border-border prose-img:shadow-lg",
 ].join(" ");
 
+const markdownPlugins = [remarkGfm];
+
 function removeImportStatements(
   content: string,
   componentNames: string[],
@@ -204,14 +207,21 @@ export async function MDXContent({
 
     return (
       <div className={proseClasses}>
-        <ReactMarkdown components={allComponents}>{content}</ReactMarkdown>
+        <ReactMarkdown
+          components={allComponents}
+          remarkPlugins={markdownPlugins}
+        >
+          {content}
+        </ReactMarkdown>
       </div>
     );
   }
 
   return (
     <div className={proseClasses}>
-      <ReactMarkdown components={allComponents}>{content}</ReactMarkdown>
+      <ReactMarkdown components={allComponents} remarkPlugins={markdownPlugins}>
+        {content}
+      </ReactMarkdown>
     </div>
   );
 }
diff --git a/packages/design/README.md b/packages/design/README.md
new file mode 100644
index 00000000..7491aa35
--- /dev/null
+++ b/packages/design/README.md
@@ -0,0 +1,23 @@
+# VLLNT UI Design Tokens
+
+`tokens.json` is the machine-readable companion to the root `DESIGN.md` guide.
+It mirrors the public CSS variables in `packages/ui/themes/default.css` and adds
+the typography, spacing, radius, elevation, motion, and iconography rules agents
+need for consistent generated UI.
+
+## Schema
+
+The token file follows `tokens.schema.json`:
+
+- `name`: fixed library name, `VLLNT UI`.
+- `version`: target library version for the token contract.
+- `source`: pointers back to the human guide and CSS theme implementation.
+- `color.semantic`: CSS variable names, light/dark HSL channels, and intended roles.
+- `typography.scale`: font size, line height, and weight for canonical text styles.
+- `spacing.scale`: 4-point spacing tokens mapped to rem values.
+- `radius`: allowed radius tokens.
+- `elevation`: allowed shadow tokens.
+- `motion`: allowed durations, easing, and reduced-motion behavior.
+- `iconography`: icon library, sizes, stroke, and color policy.
+
+The public registry mirrors this file at `/r/design.json`.
diff --git a/packages/design/tokens.json b/packages/design/tokens.json
new file mode 100644
index 00000000..292bd517
--- /dev/null
+++ b/packages/design/tokens.json
@@ -0,0 +1,225 @@
+{
+  "$schema": "./tokens.schema.json",
+  "name": "VLLNT UI",
+  "version": "0.3.0",
+  "source": {
+    "guide": "../../DESIGN.md",
+    "theme": "../ui/themes/default.css"
+  },
+  "color": {
+    "format": "hsl-channel",
+    "semantic": {
+      "background": {
+        "cssVariable": "--background",
+        "light": "0 0% 100%",
+        "dark": "0 0% 0%",
+        "role": "Page and app surface"
+      },
+      "foreground": {
+        "cssVariable": "--foreground",
+        "light": "0 0% 3.9%",
+        "dark": "0 0% 98%",
+        "role": "Primary text and icon color"
+      },
+      "card": {
+        "cssVariable": "--card",
+        "light": "0 0% 100%",
+        "dark": "0 0% 3.9%",
+        "role": "Card and contained surface"
+      },
+      "cardForeground": {
+        "cssVariable": "--card-foreground",
+        "light": "0 0% 3.9%",
+        "dark": "0 0% 98%",
+        "role": "Text on card surfaces"
+      },
+      "popover": {
+        "cssVariable": "--popover",
+        "light": "0 0% 100%",
+        "dark": "0 0% 3.9%",
+        "role": "Popover, menu, and floating surface"
+      },
+      "popoverForeground": {
+        "cssVariable": "--popover-foreground",
+        "light": "0 0% 3.9%",
+        "dark": "0 0% 98%",
+        "role": "Text on popover surfaces"
+      },
+      "primary": {
+        "cssVariable": "--primary",
+        "light": "0 0% 9%",
+        "dark": "0 0% 98%",
+        "role": "Primary action surface"
+      },
+      "primaryForeground": {
+        "cssVariable": "--primary-foreground",
+        "light": "0 0% 98%",
+        "dark": "0 0% 9%",
+        "role": "Text on primary action surfaces"
+      },
+      "secondary": {
+        "cssVariable": "--secondary",
+        "light": "0 0% 96.1%",
+        "dark": "0 0% 14.9%",
+        "role": "Secondary action surface"
+      },
+      "secondaryForeground": {
+        "cssVariable": "--secondary-foreground",
+        "light": "0 0% 9%",
+        "dark": "0 0% 98%",
+        "role": "Text on secondary action surfaces"
+      },
+      "muted": {
+        "cssVariable": "--muted",
+        "light": "0 0% 96.1%",
+        "dark": "0 0% 14.9%",
+        "role": "Subtle surface"
+      },
+      "mutedForeground": {
+        "cssVariable": "--muted-foreground",
+        "light": "0 0% 45.1%",
+        "dark": "0 0% 63.9%",
+        "role": "Secondary text"
+      },
+      "accent": {
+        "cssVariable": "--accent",
+        "light": "0 0% 96.1%",
+        "dark": "0 0% 14.9%",
+        "role": "Hover and active surface"
+      },
+      "accentForeground": {
+        "cssVariable": "--accent-foreground",
+        "light": "0 0% 9%",
+        "dark": "0 0% 98%",
+        "role": "Text on accent surfaces"
+      },
+      "destructive": {
+        "cssVariable": "--destructive",
+        "light": "0 84.2% 60.2%",
+        "dark": "0 62.8% 30.6%",
+        "role": "Destructive action and error surface"
+      },
+      "destructiveForeground": {
+        "cssVariable": "--destructive-foreground",
+        "light": "0 0% 98%",
+        "dark": "0 0% 98%",
+        "role": "Text on destructive surfaces"
+      },
+      "border": {
+        "cssVariable": "--border",
+        "light": "0 0% 89.8%",
+        "dark": "0 0% 14.9%",
+        "role": "Hairline divider"
+      },
+      "input": {
+        "cssVariable": "--input",
+        "light": "0 0% 89.8%",
+        "dark": "0 0% 14.9%",
+        "role": "Input border"
+      },
+      "ring": {
+        "cssVariable": "--ring",
+        "light": "0 0% 3.9%",
+        "dark": "0 0% 83.1%",
+        "role": "Focus ring"
+      }
+    }
+  },
+  "typography": {
+    "fontFamily": {
+      "sans": "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+      "mono": "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace"
+    },
+    "scale": {
+      "display": {
+        "fontSize": "3rem",
+        "lineHeight": "1.1",
+        "fontWeight": 600
+      },
+      "h2": {
+        "fontSize": "2rem",
+        "lineHeight": "1.2",
+        "fontWeight": 600
+      },
+      "h3": {
+        "fontSize": "1.5rem",
+        "lineHeight": "1.25",
+        "fontWeight": 600
+      },
+      "h4": {
+        "fontSize": "1.25rem",
+        "lineHeight": "1.3",
+        "fontWeight": 600
+      },
+      "bodyLarge": {
+        "fontSize": "1.125rem",
+        "lineHeight": "1.6",
+        "fontWeight": 400
+      },
+      "body": {
+        "fontSize": "1rem",
+        "lineHeight": "1.6",
+        "fontWeight": 400
+      },
+      "bodySmall": {
+        "fontSize": "0.875rem",
+        "lineHeight": "1.5",
+        "fontWeight": 400
+      },
+      "caption": {
+        "fontSize": "0.75rem",
+        "lineHeight": "1.4",
+        "fontWeight": 500
+      }
+    }
+  },
+  "spacing": {
+    "unit": "4px",
+    "scale": {
+      "1": "0.25rem",
+      "2": "0.5rem",
+      "3": "0.75rem",
+      "4": "1rem",
+      "6": "1.5rem",
+      "8": "2rem",
+      "12": "3rem",
+      "16": "4rem"
+    }
+  },
+  "radius": {
+    "none": "0",
+    "sm": "0.25rem",
+    "md": "0.5rem",
+    "lg": "0.75rem",
+    "full": "9999px"
+  },
+  "elevation": {
+    "none": "none",
+    "sm": "0 1px 2px rgba(0, 0, 0, 0.05)",
+    "md": "0 4px 6px -1px rgba(0, 0, 0, 0.1)",
+    "lg": "0 10px 15px -3px rgba(0, 0, 0, 0.1)"
+  },
+  "motion": {
+    "duration": {
+      "fast": "100ms",
+      "base": "200ms",
+      "slow": "300ms"
+    },
+    "easing": {
+      "enter": "ease-out",
+      "exit": "ease-in",
+      "layout": "ease-in-out"
+    },
+    "reducedMotion": "Collapse durations to 1ms or skip non-essential motion."
+  },
+  "iconography": {
+    "library": "lucide-react",
+    "size": {
+      "default": "1rem",
+      "compact": "0.875rem",
+      "large": "1.25rem"
+    },
+    "strokeWidth": 2,
+    "color": "currentColor"
+  }
+}
diff --git a/packages/design/tokens.schema.json b/packages/design/tokens.schema.json
new file mode 100644
index 00000000..7ef2a017
--- /dev/null
+++ b/packages/design/tokens.schema.json
@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "VLLNT UI design tokens",
+  "type": "object",
+  "required": ["name", "version", "source", "color", "typography", "spacing", "radius", "elevation", "motion", "iconography"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "name": {
+      "const": "VLLNT UI"
+    },
+    "version": {
+      "type": "string"
+    },
+    "source": {
+      "type": "object",
+      "required": ["guide", "theme"],
+      "properties": {
+        "guide": {
+          "type": "string"
+        },
+        "theme": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "color": {
+      "type": "object"
+    },
+    "typography": {
+      "type": "object"
+    },
+    "spacing": {
+      "type": "object"
+    },
+    "radius": {
+      "type": "object"
+    },
+    "elevation": {
+      "type": "object"
+    },
+    "motion": {
+      "type": "object"
+    },
+    "iconography": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/packages/ui/package.json b/packages/ui/package.json
index b58eac4b..24303b9f 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -143,6 +143,7 @@
     "react-day-picker": "^9.13.0",
     "react-hook-form": "^7.73.1",
     "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
     "react-resizable-panels": "^4.3.3",
     "react-syntax-highlighter": "^16.1.1",
     "sonner": "^1.7.4",
@@ -175,7 +176,6 @@
     "jsdom": "^26.1.0",
     "playwright": "^1.57.0",
     "postcss": "^8.5.6",
-    "remark-gfm": "^4.0.1",
     "storybook": "^10.2.17",
     "tailwindcss": "^3.4.17",
     "tailwindcss-animate": "^1.0.7",
diff --git a/packages/ui/src/components/mdx-content/mdx-content.test.tsx b/packages/ui/src/components/mdx-content/mdx-content.test.tsx
new file mode 100644
index 00000000..cf1fce88
--- /dev/null
+++ b/packages/ui/src/components/mdx-content/mdx-content.test.tsx
@@ -0,0 +1,26 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { MDXContent } from "./mdx-content";
+
+describe("MDXContent", () => {
+  it("renders GFM pipe tables as accessible tables", async () => {
+    const content = [
+      "| Name | Status |",
+      "| --- | --- |",
+      "| Design | Ready |",
+    ].join("\n");
+
+    render(await MDXContent({ content, enableMDX: false }));
+
+    expect(screen.getByRole("table")).toBeInTheDocument();
+    expect(
+      screen.getByRole("columnheader", { name: "Name" }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("columnheader", { name: "Status" }),
+    ).toBeInTheDocument();
+    expect(screen.getByRole("cell", { name: "Design" })).toBeInTheDocument();
+    expect(screen.getByRole("cell", { name: "Ready" })).toBeInTheDocument();
+  });
+});
diff --git a/packages/ui/src/components/mdx-content/mdx-content.tsx b/packages/ui/src/components/mdx-content/mdx-content.tsx
index bda9a461..f13ffce1 100644
--- a/packages/ui/src/components/mdx-content/mdx-content.tsx
+++ b/packages/ui/src/components/mdx-content/mdx-content.tsx
@@ -2,6 +2,7 @@ import { evaluate } from "@mdx-js/mdx";
 import type React from "react";
 import * as runtime from "react/jsx-runtime";
 import ReactMarkdown, { type Components } from "react-markdown";
+import remarkGfm from "remark-gfm";
 
 import { CodeBlock } from "../code-block/code-block";
 
@@ -135,6 +136,8 @@ const proseClasses = [
   "prose-img:rounded-lg prose-img:border prose-img:border-border prose-img:shadow-lg",
 ].join(" ");
 
+const markdownPlugins = [remarkGfm];
+
 function removeImportStatements(
   content: string,
   componentNames: string[],
@@ -204,14 +207,21 @@ export async function MDXContent({
 
     return (
       <div className={proseClasses}>
-        <ReactMarkdown components={allComponents}>{content}</ReactMarkdown>
+        <ReactMarkdown
+          components={allComponents}
+          remarkPlugins={markdownPlugins}
+        >
+          {content}
+        </ReactMarkdown>
       </div>
     );
   }
 
   return (
     <div className={proseClasses}>
-      <ReactMarkdown components={allComponents}>{content}</ReactMarkdown>
+      <ReactMarkdown components={allComponents} remarkPlugins={markdownPlugins}>
+        {content}
+      </ReactMarkdown>
     </div>
   );
 }
diff --git a/packages/ui/src/design-tokens.stories.tsx b/packages/ui/src/design-tokens.stories.tsx
new file mode 100644
index 00000000..7117e1ab
--- /dev/null
+++ b/packages/ui/src/design-tokens.stories.tsx
@@ -0,0 +1,122 @@
+import type { Meta, StoryObj } from "@storybook/react";
+
+import tokens from "../../design/tokens.json";
+
+function DesignTokensDocs() {
+  const colors = Object.entries(tokens.color.semantic);
+  const spacing = Object.entries(tokens.spacing.scale);
+  const radius = Object.entries(tokens.radius);
+
+  return (
+    <div className="max-w-5xl space-y-8 p-8">
+      <div>
+        <p className="text-sm font-medium text-muted-foreground">
+          VLLNT UI design system
+        </p>
+        <h1 className="mt-2 text-3xl font-semibold">Design tokens</h1>
+        <p className="mt-3 max-w-3xl text-sm leading-6 text-muted-foreground">
+          Storybook mirrors packages/design/tokens.json. The root DESIGN.md file
+          remains the human guide; this page exposes the same token contract for
+          component authors.
+        </p>
+      </div>
+
+      <section>
+        <h2 className="text-xl font-semibold">Semantic color</h2>
+        <div className="mt-4 grid gap-3 md:grid-cols-2">
+          {colors.map(([name, token]) => (
+            <div
+              className="rounded-lg border border-border bg-card p-4"
+              key={name}
+            >
+              <div className="flex items-start justify-between gap-4">
+                <div>
+                  <h3 className="font-medium">{name}</h3>
+                  <p className="mt-1 text-xs text-muted-foreground">
+                    {token.role}
+                  </p>
+                </div>
+                <code className="rounded bg-muted px-2 py-1 text-xs">
+                  {token.cssVariable}
+                </code>
+              </div>
+              <dl className="mt-3 grid grid-cols-2 gap-2 text-xs">
+                <div>
+                  <dt className="text-muted-foreground">Light</dt>
+                  <dd className="font-mono">{token.light}</dd>
+                </div>
+                <div>
+                  <dt className="text-muted-foreground">Dark</dt>
+                  <dd className="font-mono">{token.dark}</dd>
+                </div>
+              </dl>
+            </div>
+          ))}
+        </div>
+      </section>
+
+      <section className="grid gap-6 md:grid-cols-2">
+        <div>
+          <h2 className="text-xl font-semibold">Spacing</h2>
+          <div className="mt-4 overflow-hidden rounded-lg border border-border">
+            <table className="w-full text-sm">
+              <tbody>
+                {spacing.map(([name, value]) => (
+                  <tr
+                    className="border-b border-border last:border-b-0"
+                    key={name}
+                  >
+                    <th className="bg-muted p-3 text-left font-medium">
+                      space-{name}
+                    </th>
+                    <td className="p-3 font-mono">{value}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </div>
+
+        <div>
+          <h2 className="text-xl font-semibold">Radius</h2>
+          <div className="mt-4 overflow-hidden rounded-lg border border-border">
+            <table className="w-full text-sm">
+              <tbody>
+                {radius.map(([name, value]) => (
+                  <tr
+                    className="border-b border-border last:border-b-0"
+                    key={name}
+                  >
+                    <th className="bg-muted p-3 text-left font-medium">
+                      radius-{name}
+                    </th>
+                    <td className="p-3 font-mono">{value}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </div>
+      </section>
+    </div>
+  );
+}
+
+const meta = {
+  component: DesignTokensDocs,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Machine-readable VLLNT UI design tokens mirrored from packages/design/tokens.json.",
+      },
+    },
+  },
+  title: "Design/Design Tokens",
+} satisfies Meta<typeof DesignTokensDocs>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Tokens: Story = {};
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 40e57535..7b48cebb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -249,6 +249,9 @@ importers:
       react-syntax-highlighter:
         specifier: ^16.1.1
         version: 16.1.1(react@19.2.4)
+      remark-gfm:
+        specifier: ^4.0.1
+        version: 4.0.1
       sonner:
         specifier: ^1.7.4
         version: 1.7.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -334,9 +337,6 @@ importers:
       postcss:
         specifier: ^8.5.6
         version: 8.5.6
-      remark-gfm:
-        specifier: ^4.0.1
-        version: 4.0.1
       storybook:
         specifier: ^10.2.17
         version: 10.2.17(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)