From d062088089a5fea35faa3500108d393bb148f006 Mon Sep 17 00:00:00 2001
From: Anthony Volk <anth.volk@gmail.com>
Date: Wed, 4 Mar 2026 20:47:03 +0100
Subject: [PATCH 1/7] Align with PE design system: remove tw: prefix, fix
 Tailwind v4 font-size namespace
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove tw: prefix from all Tailwind classes across 25 components
- Adopt pe-* token naming for colors, spacing, radius (e.g. bg-pe-primary-500, p-pe-lg)
- Fix font-size @theme namespace: --font-size-* → --text-* (correct Tailwind v4 namespace)
- Override Tailwind default font sizes with PE design system values (--text-*: initial)
- Use standard text-xs/text-sm/etc classes which now resolve to PE values
- Remove aggressive [&_button]:text-* overrides in Header that broke Button variant colors
- Simplify tailwind-merge config (remove font-size group, keep text-color group)
- Add getCssVar() utility, design-system peer dependency, tokens CDN link in demo
- Bridge @theme values to @policyengine/design-system CSS variables

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 changelog.d/pe-token-alignment.changed.md |   1 +
 demo/Demo.tsx                             | 142 ++++++------
 demo/index.html                           |   4 +
 package.json                              |   1 +
 src/app.css                               | 257 +++++++++++-----------
 src/charts/ChartContainer.tsx             |   8 +-
 src/charts/PEAreaChart.tsx                |   2 +-
 src/charts/PEBarChart.tsx                 |   2 +-
 src/charts/PELineChart.tsx                |   2 +-
 src/charts/PEWaterfallChart.tsx           |   2 +-
 src/display/DataTable.tsx                 |  20 +-
 src/display/MetricCard.tsx                |  14 +-
 src/display/PolicyEngineWatermark.tsx     |   6 +-
 src/display/SummaryText.tsx               |   2 +-
 src/inputs/CheckboxInput.tsx              |   6 +-
 src/inputs/CurrencyInput.tsx              |  10 +-
 src/inputs/InputGroup.tsx                 |   6 +-
 src/inputs/NumberInput.tsx                |   6 +-
 src/inputs/SelectInput.tsx                |   6 +-
 src/inputs/SliderInput.tsx                |  10 +-
 src/layout/DashboardShell.tsx             |   2 +-
 src/layout/Header.tsx                     |  18 +-
 src/layout/InputPanel.tsx                 |   4 +-
 src/layout/ResultsPanel.tsx               |   2 +-
 src/layout/SidebarLayout.tsx              |   6 +-
 src/layout/SingleColumnLayout.tsx         |   4 +-
 src/primitives/Badge.tsx                  |  14 +-
 src/primitives/Button.tsx                 |  18 +-
 src/primitives/Card.tsx                   |  12 +-
 src/primitives/Tabs.tsx                   |  12 +-
 src/utils/cn.ts                           |  12 +-
 src/utils/getCssVar.ts                    |  11 +
 src/utils/index.ts                        |   1 +
 tests/primitives/Badge.test.tsx           |   4 +-
 tests/primitives/Button.test.tsx          |   4 +-
 35 files changed, 328 insertions(+), 303 deletions(-)
 create mode 100644 changelog.d/pe-token-alignment.changed.md
 create mode 100644 src/utils/getCssVar.ts

diff --git a/changelog.d/pe-token-alignment.changed.md b/changelog.d/pe-token-alignment.changed.md
new file mode 100644
index 0000000..3b07302
--- /dev/null
+++ b/changelog.d/pe-token-alignment.changed.md
@@ -0,0 +1 @@
+Align with PE design system: remove tw: prefix, adopt pe-* token naming convention, bridge @theme values to @policyengine/design-system CSS variables.
diff --git a/demo/Demo.tsx b/demo/Demo.tsx
index efb9d0f..e67630d 100644
--- a/demo/Demo.tsx
+++ b/demo/Demo.tsx
@@ -163,8 +163,8 @@ function Section({
   children: React.ReactNode;
 }) {
   return (
-    <section className="tw:mb-12">
-      <h2 className="tw:text-2xl tw:font-bold tw:text-text-primary tw:mb-6 tw:pb-2 tw:border-b tw:border-border-light">
+    <section className="mb-12">
+      <h2 className="text-2xl font-bold text-pe-text-primary mb-6 pb-2 border-b border-pe-border-light">
         {title}
       </h2>
       {children}
@@ -180,8 +180,8 @@ function SubSection({
   children: React.ReactNode;
 }) {
   return (
-    <div className="tw:mb-8">
-      <h3 className="tw:text-lg tw:font-semibold tw:text-text-secondary tw:mb-4">
+    <div className="mb-8">
+      <h3 className="text-lg font-semibold text-pe-text-secondary mb-4">
         {title}
       </h3>
       {children}
@@ -203,12 +203,12 @@ export function Demo() {
 
   return (
     <DashboardShell>
-      <div className="tw:max-w-6xl tw:mx-auto tw:px-6 tw:py-8">
-        <div className="tw:mb-10">
-          <h1 className="tw:text-4xl tw:font-bold tw:text-text-primary tw:mb-2">
+      <div className="max-w-6xl mx-auto px-6 py-8">
+        <div className="mb-10">
+          <h1 className="text-4xl font-bold text-pe-text-primary mb-2">
             @policyengine/ui-kit
           </h1>
-          <p className="tw:text-lg tw:text-text-secondary">
+          <p className="text-lg text-pe-text-secondary">
             Component gallery — every component rendered with example data
           </p>
         </div>
@@ -218,19 +218,19 @@ export function Demo() {
         {/* ================================================================ */}
         <Section title="Primitives">
           <SubSection title="Button">
-            <div className="tw:flex tw:flex-wrap tw:gap-3 tw:mb-4">
+            <div className="flex flex-wrap gap-3 mb-4">
               <Button variant="default">Default</Button>
               <Button variant="outline">Outline</Button>
               <Button variant="ghost">Ghost</Button>
               <Button variant="destructive">Destructive</Button>
             </div>
-            <div className="tw:flex tw:flex-wrap tw:gap-3 tw:mb-4">
+            <div className="flex flex-wrap gap-3 mb-4">
               <Button size="sm">Small</Button>
               <Button size="default">Default</Button>
               <Button size="lg">Large</Button>
               <Button size="icon">+</Button>
             </div>
-            <div className="tw:flex tw:flex-wrap tw:gap-3">
+            <div className="flex flex-wrap gap-3">
               <Button disabled>Disabled</Button>
               <Button variant="outline" disabled>
                 Disabled outline
@@ -239,7 +239,7 @@ export function Demo() {
           </SubSection>
 
           <SubSection title="Badge">
-            <div className="tw:flex tw:flex-wrap tw:gap-3">
+            <div className="flex flex-wrap gap-3">
               <Badge variant="default">Default</Badge>
               <Badge variant="secondary">Secondary</Badge>
               <Badge variant="outline">Outline</Badge>
@@ -250,7 +250,7 @@ export function Demo() {
           </SubSection>
 
           <SubSection title="Card">
-            <div className="tw:grid tw:grid-cols-1 tw:md:grid-cols-2 tw:gap-4">
+            <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
               <Card>
                 <CardHeader>
                   <CardTitle>Universal Basic Income</CardTitle>
@@ -259,7 +259,7 @@ export function Demo() {
                   </CardDescription>
                 </CardHeader>
                 <CardContent>
-                  <p className="tw:text-sm tw:text-text-secondary">
+                  <p className="text-sm text-pe-text-secondary">
                     This reform would provide a monthly payment of $500 to every
                     adult US citizen, funded through a combination of income tax
                     increases and spending reductions.
@@ -267,7 +267,7 @@ export function Demo() {
                 </CardContent>
                 <CardFooter>
                   <Button size="sm">View details</Button>
-                  <Button variant="outline" size="sm" className="tw:ml-2">
+                  <Button variant="outline" size="sm" className="ml-2">
                     Compare
                   </Button>
                 </CardFooter>
@@ -280,7 +280,7 @@ export function Demo() {
                   </CardDescription>
                 </CardHeader>
                 <CardContent>
-                  <p className="tw:text-sm tw:text-text-secondary">
+                  <p className="text-sm text-pe-text-secondary">
                     Expanding the Child Tax Credit to $3,600 per child under 6
                     and $3,000 for children 6-17, with full refundability for
                     all qualifying families.
@@ -304,8 +304,8 @@ export function Demo() {
               </TabsList>
               <TabsContent value="overview">
                 <Card>
-                  <CardContent className="tw:pt-4">
-                    <p className="tw:text-sm tw:text-text-secondary">
+                  <CardContent className="pt-4">
+                    <p className="text-sm text-pe-text-secondary">
                       This tab shows the overview of the policy reform,
                       including headline metrics and a summary of key impacts
                       across income deciles.
@@ -315,8 +315,8 @@ export function Demo() {
               </TabsContent>
               <TabsContent value="distributional">
                 <Card>
-                  <CardContent className="tw:pt-4">
-                    <p className="tw:text-sm tw:text-text-secondary">
+                  <CardContent className="pt-4">
+                    <p className="text-sm text-pe-text-secondary">
                       Distributional analysis shows how the reform affects
                       different income groups, with the bottom 5 deciles
                       gaining and the top 4 deciles bearing the net cost.
@@ -326,8 +326,8 @@ export function Demo() {
               </TabsContent>
               <TabsContent value="budget">
                 <Card>
-                  <CardContent className="tw:pt-4">
-                    <p className="tw:text-sm tw:text-text-secondary">
+                  <CardContent className="pt-4">
+                    <p className="text-sm text-pe-text-secondary">
                       The budget impact analysis estimates this reform would
                       cost approximately $160 billion annually, partially
                       offset by increased economic activity.
@@ -347,7 +347,7 @@ export function Demo() {
             <Header
               variant="light"
               logo={
-                <img src={logos.tealWordmark} alt="PolicyEngine" className="tw:h-5" />
+                <img src={logos.tealWordmark} alt="PolicyEngine" className="h-5" />
               }
               actions={
                 <>
@@ -358,7 +358,7 @@ export function Demo() {
                 </>
               }
             >
-              <span className="tw:ml-2">
+              <span className="ml-2">
                 UBI Calculator
               </span>
             </Header>
@@ -368,84 +368,84 @@ export function Demo() {
             <Header
               variant="dark"
               logo={
-                <img src={logos.whiteWordmark} alt="PolicyEngine" className="tw:h-5" />
+                <img src={logos.whiteWordmark} alt="PolicyEngine" className="h-5" />
               }
               actions={
                 <>
                   <a href="#">Research</a>
                   <a href="#">About</a>
                   <a href="#">Donate</a>
-                  <Button size="sm" className="tw:bg-white tw:text-primary-600 tw:hover:bg-gray-100">Sign in</Button>
+                  <Button size="sm" className="bg-white text-pe-primary-600 hover:bg-pe-gray-100">Sign in</Button>
                 </>
               }
             >
-              <span className="tw:ml-2">
+              <span className="ml-2">
                 Policy calculator
               </span>
             </Header>
           </SubSection>
 
           <SubSection title="PolicyEngine logos">
-            <div className="tw:grid tw:grid-cols-3 tw:gap-4">
+            <div className="grid grid-cols-3 gap-4">
               <Card>
-                <CardContent className="tw:pt-4 tw:flex tw:flex-col tw:items-center tw:gap-2">
-                  <img src={logos.tealWordmark} alt="Teal wordmark (SVG)" className="tw:h-6" />
-                  <span className="tw:text-xs tw:text-text-tertiary">tealWordmark</span>
+                <CardContent className="pt-4 flex flex-col items-center gap-2">
+                  <img src={logos.tealWordmark} alt="Teal wordmark (SVG)" className="h-6" />
+                  <span className="text-xs text-pe-text-tertiary">tealWordmark</span>
                 </CardContent>
               </Card>
               <Card>
-                <CardContent className="tw:pt-4 tw:flex tw:flex-col tw:items-center tw:gap-2">
-                  <img src={logos.tealWordmarkPng} alt="Teal wordmark (PNG)" className="tw:h-6" />
-                  <span className="tw:text-xs tw:text-text-tertiary">tealWordmarkPng</span>
+                <CardContent className="pt-4 flex flex-col items-center gap-2">
+                  <img src={logos.tealWordmarkPng} alt="Teal wordmark (PNG)" className="h-6" />
+                  <span className="text-xs text-pe-text-tertiary">tealWordmarkPng</span>
                 </CardContent>
               </Card>
-              <Card className="tw:bg-primary-600">
-                <CardContent className="tw:pt-4 tw:flex tw:flex-col tw:items-center tw:gap-2">
-                  <img src={logos.whiteWordmark} alt="White wordmark (SVG)" className="tw:h-6" />
-                  <span className="tw:text-xs tw:text-white/60">whiteWordmark</span>
+              <Card className="bg-pe-primary-600">
+                <CardContent className="pt-4 flex flex-col items-center gap-2">
+                  <img src={logos.whiteWordmark} alt="White wordmark (SVG)" className="h-6" />
+                  <span className="text-xs text-white/60">whiteWordmark</span>
                 </CardContent>
               </Card>
-              <Card className="tw:bg-primary-600">
-                <CardContent className="tw:pt-4 tw:flex tw:flex-col tw:items-center tw:gap-2">
-                  <img src={logos.whiteWordmarkPng} alt="White wordmark (PNG)" className="tw:h-6" />
-                  <span className="tw:text-xs tw:text-white/60">whiteWordmarkPng</span>
+              <Card className="bg-pe-primary-600">
+                <CardContent className="pt-4 flex flex-col items-center gap-2">
+                  <img src={logos.whiteWordmarkPng} alt="White wordmark (PNG)" className="h-6" />
+                  <span className="text-xs text-white/60">whiteWordmarkPng</span>
                 </CardContent>
               </Card>
               <Card>
-                <CardContent className="tw:pt-4 tw:flex tw:flex-col tw:items-center tw:gap-2">
-                  <img src={logos.tealSquare} alt="Teal square (SVG)" className="tw:h-10" />
-                  <span className="tw:text-xs tw:text-text-tertiary">tealSquare</span>
+                <CardContent className="pt-4 flex flex-col items-center gap-2">
+                  <img src={logos.tealSquare} alt="Teal square (SVG)" className="h-10" />
+                  <span className="text-xs text-pe-text-tertiary">tealSquare</span>
                 </CardContent>
               </Card>
               <Card>
-                <CardContent className="tw:pt-4 tw:flex tw:flex-col tw:items-center tw:gap-2">
-                  <img src={logos.tealSquarePng} alt="Teal square (PNG)" className="tw:h-10" />
-                  <span className="tw:text-xs tw:text-text-tertiary">tealSquarePng</span>
+                <CardContent className="pt-4 flex flex-col items-center gap-2">
+                  <img src={logos.tealSquarePng} alt="Teal square (PNG)" className="h-10" />
+                  <span className="text-xs text-pe-text-tertiary">tealSquarePng</span>
                 </CardContent>
               </Card>
               <Card>
-                <CardContent className="tw:pt-4 tw:flex tw:flex-col tw:items-center tw:gap-2">
-                  <img src={logos.tealSquareTransparent} alt="Teal square transparent (PNG)" className="tw:h-10" />
-                  <span className="tw:text-xs tw:text-text-tertiary">tealSquareTransparent</span>
+                <CardContent className="pt-4 flex flex-col items-center gap-2">
+                  <img src={logos.tealSquareTransparent} alt="Teal square transparent (PNG)" className="h-10" />
+                  <span className="text-xs text-pe-text-tertiary">tealSquareTransparent</span>
                 </CardContent>
               </Card>
               <Card>
-                <CardContent className="tw:pt-4 tw:flex tw:flex-col tw:items-center tw:gap-2">
-                  <img src={logos.tealSquarePadded} alt="Teal square padded (SVG)" className="tw:h-10" />
-                  <span className="tw:text-xs tw:text-text-tertiary">tealSquarePadded</span>
+                <CardContent className="pt-4 flex flex-col items-center gap-2">
+                  <img src={logos.tealSquarePadded} alt="Teal square padded (SVG)" className="h-10" />
+                  <span className="text-xs text-pe-text-tertiary">tealSquarePadded</span>
                 </CardContent>
               </Card>
-              <Card className="tw:bg-primary-600">
-                <CardContent className="tw:pt-4 tw:flex tw:flex-col tw:items-center tw:gap-2">
-                  <img src={logos.whiteSquare} alt="White square (SVG)" className="tw:h-10" />
-                  <span className="tw:text-xs tw:text-white/60">whiteSquare</span>
+              <Card className="bg-pe-primary-600">
+                <CardContent className="pt-4 flex flex-col items-center gap-2">
+                  <img src={logos.whiteSquare} alt="White square (SVG)" className="h-10" />
+                  <span className="text-xs text-white/60">whiteSquare</span>
                 </CardContent>
               </Card>
             </div>
           </SubSection>
 
           <SubSection title="SidebarLayout (with InputPanel + ResultsPanel)">
-            <div className="tw:border tw:border-border-light tw:rounded-container tw:overflow-hidden tw:h-[500px]">
+            <div className="border border-pe-border-light rounded-pe-container overflow-hidden h-[500px]">
               <SidebarLayout
                 sidebar={
                   <InputPanel title="Household parameters">
@@ -483,7 +483,7 @@ export function Demo() {
                 }
               >
                 <ResultsPanel>
-                  <div className="tw:grid tw:grid-cols-1 tw:sm:grid-cols-3 tw:gap-4">
+                  <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
                     <MetricCard
                       label="Net income change"
                       value={3200}
@@ -512,9 +512,9 @@ export function Demo() {
           </SubSection>
 
           <SubSection title="SingleColumnLayout">
-            <div className="tw:border tw:border-border-light tw:rounded-container tw:overflow-hidden">
+            <div className="border border-pe-border-light rounded-pe-container overflow-hidden">
               <SingleColumnLayout maxWidth="700px">
-                <h3 className="tw:text-xl tw:font-bold tw:mb-4">
+                <h3 className="text-xl font-bold mb-4">
                   Policy summary
                 </h3>
                 <SummaryText>
@@ -535,10 +535,10 @@ export function Demo() {
         {/* INPUTS */}
         {/* ================================================================ */}
         <Section title="Inputs">
-          <div className="tw:grid tw:grid-cols-1 tw:md:grid-cols-2 tw:gap-6">
+          <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
             <Card>
-              <CardContent className="tw:pt-4">
-                <div className="tw:flex tw:flex-col tw:gap-4">
+              <CardContent className="pt-4">
+                <div className="flex flex-col gap-4">
                   <CurrencyInput
                     label="Annual household income"
                     value={income}
@@ -568,8 +568,8 @@ export function Demo() {
               </CardContent>
             </Card>
             <Card>
-              <CardContent className="tw:pt-4">
-                <div className="tw:flex tw:flex-col tw:gap-4">
+              <CardContent className="pt-4">
+                <div className="flex flex-col gap-4">
                   <CheckboxInput
                     label="Include state-level tax effects"
                     checked={includeState}
@@ -615,7 +615,7 @@ export function Demo() {
         {/* ================================================================ */}
         <Section title="Display">
           <SubSection title="MetricCard">
-            <div className="tw:grid tw:grid-cols-1 tw:sm:grid-cols-2 tw:lg:grid-cols-4 tw:gap-4">
+            <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
               <MetricCard
                 label="Annual cost"
                 value={162000000000}
@@ -651,7 +651,7 @@ export function Demo() {
               <strong>{dependents} dependents</strong> would receive{' '}
               <strong>$12,000</strong> in annual UBI payments and pay an
               additional <strong>$8,200</strong> in income taxes, for a{' '}
-              <strong className="tw:text-primary-500">
+              <strong className="text-pe-primary-500">
                 net gain of $3,800
               </strong>{' '}
               per year.
@@ -671,7 +671,7 @@ export function Demo() {
         {/* CHARTS */}
         {/* ================================================================ */}
         <Section title="Charts">
-          <div className="tw:grid tw:grid-cols-1 tw:gap-6">
+          <div className="grid grid-cols-1 gap-6">
             <ChartContainer
               title="Revenue sources vs. UBI cost"
               subtitle="Billions of dollars, annual"
@@ -745,7 +745,7 @@ export function Demo() {
           </div>
         </Section>
 
-        <div className="tw:text-center tw:py-8 tw:text-sm tw:text-text-tertiary">
+        <div className="text-center py-8 text-sm text-pe-text-tertiary">
           @policyengine/ui-kit v0.1.0 — All components shown with example data
         </div>
       </div>
diff --git a/demo/index.html b/demo/index.html
index 5b00f56..7b4f756 100644
--- a/demo/index.html
+++ b/demo/index.html
@@ -10,6 +10,10 @@
       href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap"
       rel="stylesheet"
     />
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/@policyengine/design-system/dist/tokens.css"
+    />
   </head>
   <body>
     <div id="root"></div>
diff --git a/package.json b/package.json
index 6cb0d3c..68ef0fb 100644
--- a/package.json
+++ b/package.json
@@ -26,6 +26,7 @@
     "lint": "tsc --noEmit"
   },
   "peerDependencies": {
+    "@policyengine/design-system": "*",
     "react": ">=19",
     "react-dom": ">=19",
     "recharts": ">=2.12"
diff --git a/src/app.css b/src/app.css
index d743abb..207d491 100644
--- a/src/app.css
+++ b/src/app.css
@@ -1,158 +1,160 @@
-@import 'tailwindcss' prefix(tw);
+@import 'tailwindcss';
 
 @theme {
-  /* Primary brand colors - teal */
-  --color-primary-50: #e6fffa;
-  --color-primary-100: #b2f5ea;
-  --color-primary-200: #81e6d9;
-  --color-primary-300: #4fd1c5;
-  --color-primary-400: #38b2ac;
-  --color-primary-500: #319795;
-  --color-primary-600: #2c7a7b;
-  --color-primary-700: #285e61;
-  --color-primary-800: #234e52;
-  --color-primary-900: #1d4044;
-
-  /* Secondary colors - gray scale */
-  --color-secondary-50: #f0f9ff;
-  --color-secondary-100: #f2f4f7;
-  --color-secondary-200: #e2e8f0;
-  --color-secondary-300: #cbd5e1;
-  --color-secondary-400: #94a3b8;
-  --color-secondary-500: #64748b;
-  --color-secondary-600: #475569;
-  --color-secondary-700: #344054;
-  --color-secondary-800: #1e293b;
-  --color-secondary-900: #101828;
+  /* =======================================================
+   * PolicyEngine Design Token Bridge
+   * =======================================================
+   * All tokens bridge to @policyengine/design-system CSS
+   * variables (--pe-*). Consumers MUST load tokens.css:
+   *   <link rel="stylesheet" href="https://unpkg.com/@policyengine/design-system/dist/tokens.css">
+   * =======================================================
+   */
 
-  /* Blue accent colors */
-  --color-blue-50: #f0f9ff;
-  --color-blue-100: #e0f2fe;
-  --color-blue-200: #bae6fd;
-  --color-blue-300: #7dd3fc;
-  --color-blue-400: #38bdf8;
-  --color-blue-500: #0ea5e9;
-  --color-blue-600: #0284c7;
-  --color-blue-700: #026aa2;
-  --color-blue-800: #075985;
-  --color-blue-900: #0c4a6e;
+  /* Primary brand colors - teal */
+  --color-pe-primary-50: var(--pe-color-primary-50);
+  --color-pe-primary-100: var(--pe-color-primary-100);
+  --color-pe-primary-200: var(--pe-color-primary-200);
+  --color-pe-primary-300: var(--pe-color-primary-300);
+  --color-pe-primary-400: var(--pe-color-primary-400);
+  --color-pe-primary-500: var(--pe-color-primary-500);
+  --color-pe-primary-600: var(--pe-color-primary-600);
+  --color-pe-primary-700: var(--pe-color-primary-700);
+  --color-pe-primary-800: var(--pe-color-primary-800);
+  --color-pe-primary-900: var(--pe-color-primary-900);
 
   /* Gray scale */
-  --color-gray-50: #f9fafb;
-  --color-gray-100: #f2f4f7;
-  --color-gray-200: #e2e8f0;
-  --color-gray-300: #d1d5db;
-  --color-gray-400: #9ca3af;
-  --color-gray-500: #6b7280;
-  --color-gray-600: #4b5563;
-  --color-gray-700: #344054;
-  --color-gray-800: #1f2937;
-  --color-gray-900: #101828;
+  --color-pe-gray-50: var(--pe-color-gray-50);
+  --color-pe-gray-100: var(--pe-color-gray-100);
+  --color-pe-gray-200: var(--pe-color-gray-200);
+  --color-pe-gray-300: var(--pe-color-gray-300);
+  --color-pe-gray-400: var(--pe-color-gray-400);
+  --color-pe-gray-500: var(--pe-color-gray-500);
+  --color-pe-gray-600: var(--pe-color-gray-600);
+  --color-pe-gray-700: var(--pe-color-gray-700);
+  --color-pe-gray-800: var(--pe-color-gray-800);
+  --color-pe-gray-900: var(--pe-color-gray-900);
+
+  /* Blue accent colors */
+  --color-pe-blue-50: var(--pe-color-blue-50);
+  --color-pe-blue-100: var(--pe-color-blue-100);
+  --color-pe-blue-200: var(--pe-color-blue-200);
+  --color-pe-blue-300: var(--pe-color-blue-300);
+  --color-pe-blue-400: var(--pe-color-blue-400);
+  --color-pe-blue-500: var(--pe-color-blue-500);
+  --color-pe-blue-600: var(--pe-color-blue-600);
+  --color-pe-blue-700: var(--pe-color-blue-700);
+  --color-pe-blue-800: var(--pe-color-blue-800);
+  --color-pe-blue-900: var(--pe-color-blue-900);
 
   /* Semantic colors */
-  --color-success: #22c55e;
-  --color-warning: #fec601;
-  --color-error: #ef4444;
-  --color-info: #1890ff;
+  --color-pe-success: var(--pe-color-success);
+  --color-pe-warning: var(--pe-color-warning);
+  --color-pe-error: var(--pe-color-error);
+  --color-pe-info: var(--pe-color-info);
 
   /* Background colors */
-  --color-bg-primary: #fff;
-  --color-bg-secondary: #f5f9ff;
-  --color-bg-tertiary: #f1f5f9;
+  --color-pe-bg-primary: var(--pe-color-bg-primary);
+  --color-pe-bg-secondary: var(--pe-color-bg-secondary);
+  --color-pe-bg-tertiary: var(--pe-color-bg-tertiary);
 
   /* Text colors */
-  --color-text-primary: #000;
-  --color-text-secondary: #5a5a5a;
-  --color-text-tertiary: #9ca3af;
-  --color-text-inverse: #fff;
+  --color-pe-text-primary: var(--pe-color-text-primary);
+  --color-pe-text-secondary: var(--pe-color-text-secondary);
+  --color-pe-text-tertiary: var(--pe-color-text-tertiary);
+  --color-pe-text-inverse: var(--pe-color-text-inverse);
 
   /* Border colors */
-  --color-border-light: #e2e8f0;
-  --color-border-medium: #cbd5e1;
-  --color-border-dark: #94a3b8;
+  --color-pe-border-light: var(--pe-color-border-light);
+  --color-pe-border-medium: var(--pe-color-border-medium);
+  --color-pe-border-dark: var(--pe-color-border-dark);
 
   /*
    * =========================================================
    * shadcn/ui semantic color tokens
    * =========================================================
-   * These are REQUIRED by all shadcn/ui components (Button,
-   * Badge, Table, Input, Dialog, etc.). They use classes like
-   * tw:bg-primary, tw:text-foreground, tw:border-border which
-   * resolve to these CSS variables.
+   * Required by shadcn/ui components (Button, Badge, Dialog,
+   * etc.). These use classes like bg-primary, text-foreground,
+   * border-border. NOT pe-prefixed — shadcn expects these
+   * exact names.
    * =========================================================
    */
 
   /* Core foreground/background */
-  --color-background: #fff;
-  --color-foreground: #101828;
+  --color-background: var(--pe-color-bg-primary);
+  --color-foreground: var(--pe-color-gray-900);
 
   /* Primary action color (buttons, links, badges) */
-  --color-primary: #2c7a7b;
-  --color-primary-foreground: #fff;
+  --color-primary: var(--pe-color-primary-600);
+  --color-primary-foreground: var(--pe-color-text-inverse);
 
   /* Secondary (muted buttons, secondary badges) */
-  --color-secondary: #f2f4f7;
-  --color-secondary-foreground: #101828;
+  --color-secondary: var(--pe-color-gray-100);
+  --color-secondary-foreground: var(--pe-color-gray-900);
 
   /* Muted (subtle backgrounds, disabled states) */
-  --color-muted: #f2f4f7;
-  --color-muted-foreground: #6b7280;
+  --color-muted: var(--pe-color-gray-100);
+  --color-muted-foreground: var(--pe-color-gray-500);
 
   /* Accent (hover highlights, active states) */
-  --color-accent: #f2f4f7;
-  --color-accent-foreground: #101828;
+  --color-accent: var(--pe-color-gray-100);
+  --color-accent-foreground: var(--pe-color-gray-900);
 
   /* Destructive (delete buttons, error states) */
-  --color-destructive: #ef4444;
+  --color-destructive: var(--pe-color-error);
 
   /* Popover/dropdown backgrounds */
-  --color-popover: #fff;
-  --color-popover-foreground: #101828;
+  --color-popover: var(--pe-color-bg-primary);
+  --color-popover-foreground: var(--pe-color-gray-900);
 
   /* Card backgrounds */
-  --color-card: #fff;
-  --color-card-foreground: #101828;
+  --color-card: var(--pe-color-bg-primary);
+  --color-card-foreground: var(--pe-color-gray-900);
 
   /* Border, input, ring (form controls) */
-  --color-border: #e2e8f0;
-  --color-input: #e2e8f0;
-  --color-ring: #319795;
+  --color-border: var(--pe-color-border-light);
+  --color-input: var(--pe-color-border-light);
+  --color-ring: var(--pe-color-primary-500);
 
   /* Typography */
-  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-  --font-mono: 'JetBrains Mono', 'Fira Code', Consolas, monospace;
-
-  --font-size-xs: 12px;
-  --font-size-sm: 14px;
-  --font-size-base: 16px;
-  --font-size-lg: 18px;
-  --font-size-xl: 20px;
-  --font-size-2xl: 24px;
-  --font-size-3xl: 28px;
-  --font-size-4xl: 32px;
+  --font-pe: var(--pe-font-family-primary);
+  --font-pe-mono: var(--pe-font-family-mono);
+
+  /* Override Tailwind's default font sizes with PE design system values.
+   * Tailwind v4 uses the --text-* namespace to generate text-* utilities.
+   * We clear all defaults and define only PE's scale (xs through 4xl).
+   * Use standard classes (text-xs, text-sm, text-base, etc.) in components. */
+  --text-*: initial;
+  --text-xs: var(--pe-font-size-xs);
+  --text-sm: var(--pe-font-size-sm);
+  --text-base: var(--pe-font-size-base);
+  --text-lg: var(--pe-font-size-lg);
+  --text-xl: var(--pe-font-size-xl);
+  --text-2xl: var(--pe-font-size-2xl);
+  --text-3xl: var(--pe-font-size-3xl);
+  --text-4xl: var(--pe-font-size-4xl);
 
   /* Spacing */
-  --spacing-xs: 4px;
-  --spacing-sm: 8px;
-  --spacing-md: 12px;
-  --spacing-lg: 16px;
-  --spacing-xl: 20px;
-  --spacing-2xl: 24px;
-  --spacing-3xl: 32px;
-  --spacing-4xl: 48px;
-  --spacing-5xl: 64px;
+  --spacing-pe-xs: var(--pe-space-xs);
+  --spacing-pe-sm: var(--pe-space-sm);
+  --spacing-pe-md: var(--pe-space-md);
+  --spacing-pe-lg: var(--pe-space-lg);
+  --spacing-pe-xl: var(--pe-space-xl);
+  --spacing-pe-2xl: var(--pe-space-2xl);
+  --spacing-pe-3xl: var(--pe-space-3xl);
+  --spacing-pe-4xl: var(--pe-space-4xl);
+  --spacing-pe-5xl: var(--pe-space-5xl);
 
   /* Border radius - semantic scale */
-  --radius-chip: 2px;
-  --radius-element: 4px;
-  --radius-container: 8px;
-  --radius-feature: 12px;
+  --radius-pe-chip: var(--pe-radius-chip);
+  --radius-pe-element: var(--pe-radius-element);
+  --radius-pe-container: var(--pe-radius-container);
+  --radius-pe-feature: var(--pe-radius-feature);
 
-  /* shadcn radius tokens */
-  --radius-sm: 4px;
-  --radius-md: 6px;
-  --radius-lg: 8px;
-  --radius-xl: 12px;
+  /* Border radius - size scale (aliases for convenience) */
+  --radius-pe-sm: var(--pe-radius-element);
+  --radius-pe-md: 6px;
+  --radius-pe-lg: var(--pe-radius-container);
+  --radius-pe-xl: var(--pe-radius-feature);
 
   /* Breakpoints */
   --breakpoint-xs: 36rem;
@@ -162,12 +164,12 @@
   --breakpoint-xl: 88rem;
   --breakpoint-2xl: 96rem;
 
-  /* Layout */
-  --spacing-sidebar: 79px;
-  --spacing-sidebar-width: 280px;
-  --spacing-header: 58px;
-  --spacing-content: 1361px;
-  --spacing-container: 976px;
+  /* Layout spacing */
+  --spacing-pe-sidebar: 79px;
+  --spacing-pe-sidebar-width: 280px;
+  --spacing-pe-header: 58px;
+  --spacing-pe-content: 1361px;
+  --spacing-pe-container: 976px;
 }
 
 /*
@@ -178,32 +180,27 @@
  * slate. These base styles restore sensible defaults.
  * =========================================================
  */
-/*
- * IMPORTANT: prefix(tw) causes all @theme variables to be prefixed
- * with --tw-. So --font-sans becomes --tw-font-sans, etc.
- * All var() references in hand-written CSS must use --tw- prefix.
- */
 @layer base {
   /* Default border color */
   *,
   ::before,
   ::after {
-    border-color: var(--tw-color-border);
+    border-color: var(--color-border);
   }
 
   html {
-    font-family: var(--tw-font-sans);
-    font-size: var(--tw-font-size-base);
+    font-family: var(--font-pe);
+    font-size: var(--text-base);
     line-height: 1.55;
-    color: var(--tw-color-foreground);
+    color: var(--color-foreground);
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
   }
 
   body {
-    font-family: var(--tw-font-sans);
-    color: var(--tw-color-foreground);
-    background-color: var(--tw-color-background);
+    font-family: var(--font-pe);
+    color: var(--color-foreground);
+    background-color: var(--color-background);
   }
 
   a {
@@ -218,7 +215,7 @@
 
   [data-slot='table-container'],
   tr {
-    background-color: var(--tw-color-bg-primary);
+    background-color: var(--color-pe-bg-primary);
   }
 
   th {
@@ -232,7 +229,7 @@
   textarea {
     font-family: inherit;
     font-size: inherit;
-    background-color: var(--tw-color-bg-primary);
+    background-color: var(--color-pe-bg-primary);
   }
 
   input[type='number']::-webkit-inner-spin-button,
diff --git a/src/charts/ChartContainer.tsx b/src/charts/ChartContainer.tsx
index cd79a47..8def053 100644
--- a/src/charts/ChartContainer.tsx
+++ b/src/charts/ChartContainer.tsx
@@ -24,25 +24,25 @@ export function ChartContainer({
   return (
     <div
       className={cn(
-        'tw:bg-white tw:border tw:border-border-light tw:rounded-container tw:p-lg',
+        'bg-white border border-pe-border-light rounded-pe-container p-pe-lg',
         className,
       )}
       style={styles?.root}
       {...props}
     >
       {(title || actions) && (
-        <div className="tw:flex tw:items-start tw:justify-between tw:mb-lg">
+        <div className="flex items-start justify-between mb-pe-lg">
           <div>
             {title && (
               <h3
-                className="tw:text-base tw:font-semibold tw:text-text-primary"
+                className="text-base font-semibold text-pe-text-primary"
                 style={styles?.title}
               >
                 {title}
               </h3>
             )}
             {subtitle && (
-              <p className="tw:text-sm tw:text-text-secondary tw:mt-0.5">
+              <p className="text-sm text-pe-text-secondary mt-0.5">
                 {subtitle}
               </p>
             )}
diff --git a/src/charts/PEAreaChart.tsx b/src/charts/PEAreaChart.tsx
index 0b18674..09393d4 100644
--- a/src/charts/PEAreaChart.tsx
+++ b/src/charts/PEAreaChart.tsx
@@ -51,7 +51,7 @@ export function PEAreaChart({
   rechartsProps,
 }: PEAreaChartProps) {
   return (
-    <div className={cn('tw:w-full', className)} style={styles?.root}>
+    <div className={cn('w-full', className)} style={styles?.root}>
       <ResponsiveContainer width="100%" height={height}>
         <AreaChart data={data} {...rechartsProps}>
           {showGrid && <CartesianGrid {...GRID_STYLE} />}
diff --git a/src/charts/PEBarChart.tsx b/src/charts/PEBarChart.tsx
index 3530922..5bdb260 100644
--- a/src/charts/PEBarChart.tsx
+++ b/src/charts/PEBarChart.tsx
@@ -51,7 +51,7 @@ export function PEBarChart({
   rechartsProps,
 }: PEBarChartProps) {
   return (
-    <div className={cn('tw:w-full', className)} style={styles?.root}>
+    <div className={cn('w-full', className)} style={styles?.root}>
       <ResponsiveContainer width="100%" height={height}>
         <BarChart data={data} {...rechartsProps}>
           {showGrid && <CartesianGrid {...GRID_STYLE} />}
diff --git a/src/charts/PELineChart.tsx b/src/charts/PELineChart.tsx
index deb1d35..6a3dc9b 100644
--- a/src/charts/PELineChart.tsx
+++ b/src/charts/PELineChart.tsx
@@ -49,7 +49,7 @@ export function PELineChart({
   rechartsProps,
 }: PELineChartProps) {
   return (
-    <div className={cn('tw:w-full', className)} style={styles?.root}>
+    <div className={cn('w-full', className)} style={styles?.root}>
       <ResponsiveContainer width="100%" height={height}>
         <LineChart data={data} {...rechartsProps}>
           {showGrid && <CartesianGrid {...GRID_STYLE} />}
diff --git a/src/charts/PEWaterfallChart.tsx b/src/charts/PEWaterfallChart.tsx
index 040c38e..411b41a 100644
--- a/src/charts/PEWaterfallChart.tsx
+++ b/src/charts/PEWaterfallChart.tsx
@@ -86,7 +86,7 @@ export function PEWaterfallChart({
   const waterfallData = buildWaterfallData(data, positiveColor, negativeColor, totalColor);
 
   return (
-    <div className={cn('tw:w-full', className)} style={styles?.root}>
+    <div className={cn('w-full', className)} style={styles?.root}>
       <ResponsiveContainer width="100%" height={height}>
         <BarChart data={waterfallData} {...rechartsProps}>
           {showGrid && <CartesianGrid {...GRID_STYLE} />}
diff --git a/src/display/DataTable.tsx b/src/display/DataTable.tsx
index f80075a..f53a763 100644
--- a/src/display/DataTable.tsx
+++ b/src/display/DataTable.tsx
@@ -31,22 +31,22 @@ export function DataTable<T extends Record<string, unknown>>({
   return (
     <div
       className={cn(
-        'tw:bg-white tw:border tw:border-border-light tw:rounded-container tw:overflow-hidden',
+        'bg-white border border-pe-border-light rounded-pe-container overflow-hidden',
         className,
       )}
       style={styles?.root}
       {...props}
     >
-      <table className="tw:w-full" style={styles?.table}>
+      <table className="w-full" style={styles?.table}>
         <thead>
-          <tr className="tw:border-b tw:border-border-light tw:bg-gray-50">
+          <tr className="border-b border-pe-border-light bg-pe-gray-50">
             {columns.map((col) => (
               <th
                 key={col.key}
                 className={cn(
-                  'tw:px-4 tw:py-3 tw:text-xs tw:font-semibold tw:uppercase tw:tracking-wider tw:text-text-secondary',
-                  col.align === 'right' && 'tw:text-right',
-                  col.align === 'center' && 'tw:text-center',
+                  'px-4 py-3 text-xs font-semibold uppercase tracking-wider text-pe-text-secondary',
+                  col.align === 'right' && 'text-right',
+                  col.align === 'center' && 'text-center',
                 )}
                 style={styles?.header}
               >
@@ -59,16 +59,16 @@ export function DataTable<T extends Record<string, unknown>>({
           {data.map((row, i) => (
             <tr
               key={i}
-              className="tw:border-b tw:border-border-light last:tw:border-b-0 tw:hover:bg-gray-50"
+              className="border-b border-pe-border-light last:border-b-0 hover:bg-pe-gray-50"
               style={styles?.row}
             >
               {columns.map((col) => (
                 <td
                   key={col.key}
                   className={cn(
-                    'tw:px-4 tw:py-3 tw:text-sm tw:text-text-primary',
-                    col.align === 'right' && 'tw:text-right',
-                    col.align === 'center' && 'tw:text-center',
+                    'px-4 py-3 text-sm text-pe-text-primary',
+                    col.align === 'right' && 'text-right',
+                    col.align === 'center' && 'text-center',
                   )}
                   style={styles?.cell}
                 >
diff --git a/src/display/MetricCard.tsx b/src/display/MetricCard.tsx
index 1f7ca7f..f9e8054 100644
--- a/src/display/MetricCard.tsx
+++ b/src/display/MetricCard.tsx
@@ -45,20 +45,20 @@ export function MetricCard({
   return (
     <div
       className={cn(
-        'tw:bg-white tw:border tw:border-border-light tw:rounded-container tw:p-lg tw:flex tw:flex-col tw:gap-xs',
+        'bg-white border border-pe-border-light rounded-pe-container p-pe-lg flex flex-col gap-pe-xs',
         className,
       )}
       style={styles?.root}
       {...props}
     >
       <span
-        className="tw:text-sm tw:text-text-secondary tw:font-medium"
+        className="text-sm text-pe-text-secondary font-medium"
         style={styles?.label}
       >
         {label}
       </span>
       <span
-        className="tw:text-2xl tw:font-bold tw:text-text-primary"
+        className="text-2xl font-bold text-pe-text-primary"
         style={styles?.value}
       >
         {typeof value === 'number' ? formatByType(value, format) : value}
@@ -66,10 +66,10 @@ export function MetricCard({
       {trend && delta && (
         <span
           className={cn(
-            'tw:text-sm tw:font-medium',
-            trend === 'positive' && 'tw:text-primary-500',
-            trend === 'negative' && 'tw:text-error',
-            trend === 'neutral' && 'tw:text-gray-500',
+            'text-sm font-medium',
+            trend === 'positive' && 'text-pe-primary-500',
+            trend === 'negative' && 'text-pe-error',
+            trend === 'neutral' && 'text-pe-gray-500',
           )}
           style={styles?.trend}
         >
diff --git a/src/display/PolicyEngineWatermark.tsx b/src/display/PolicyEngineWatermark.tsx
index 07e1307..f98d8c3 100644
--- a/src/display/PolicyEngineWatermark.tsx
+++ b/src/display/PolicyEngineWatermark.tsx
@@ -15,16 +15,16 @@ export function PolicyEngineWatermark({
   return (
     <div
       className={cn(
-        'tw:flex tw:items-center tw:justify-end tw:gap-1 tw:py-1 tw:opacity-60',
+        'flex items-center justify-end gap-1 py-1 opacity-60',
         className,
       )}
       style={styles?.root}
       {...props}
     >
       {logoSrc && (
-        <img src={logoSrc} alt="PolicyEngine" className="tw:h-4 tw:w-4" />
+        <img src={logoSrc} alt="PolicyEngine" className="h-4 w-4" />
       )}
-      <span className="tw:text-xs tw:text-text-tertiary">PolicyEngine</span>
+      <span className="text-xs text-pe-text-tertiary">PolicyEngine</span>
     </div>
   );
 }
diff --git a/src/display/SummaryText.tsx b/src/display/SummaryText.tsx
index e114d35..1f21ee5 100644
--- a/src/display/SummaryText.tsx
+++ b/src/display/SummaryText.tsx
@@ -10,7 +10,7 @@ export function SummaryText({ className, styles, children, ...props }: SummaryTe
   return (
     <div
       className={cn(
-        'tw:text-base tw:leading-relaxed tw:text-text-primary tw:bg-white tw:border tw:border-border-light tw:rounded-container tw:p-lg',
+        'text-base leading-relaxed text-pe-text-primary bg-white border border-pe-border-light rounded-pe-container p-pe-lg',
         className,
       )}
       style={styles?.root}
diff --git a/src/inputs/CheckboxInput.tsx b/src/inputs/CheckboxInput.tsx
index 005daae..336e2cb 100644
--- a/src/inputs/CheckboxInput.tsx
+++ b/src/inputs/CheckboxInput.tsx
@@ -16,7 +16,7 @@ export interface CheckboxInputProps
 export const CheckboxInput = forwardRef<HTMLInputElement, CheckboxInputProps>(
   ({ label, checked, onChange, className, styles, ...props }, ref) => (
     <label
-      className={cn('tw:flex tw:items-center tw:gap-2 tw:cursor-pointer', className)}
+      className={cn('flex items-center gap-2 cursor-pointer', className)}
       style={styles?.root}
     >
       <input
@@ -24,11 +24,11 @@ export const CheckboxInput = forwardRef<HTMLInputElement, CheckboxInputProps>(
         type="checkbox"
         checked={checked}
         onChange={(e) => onChange(e.target.checked)}
-        className="tw:h-4 tw:w-4 tw:rounded tw:border tw:border-border-light tw:accent-primary tw:focus:ring-2 tw:focus:ring-ring tw:cursor-pointer"
+        className="h-4 w-4 rounded border border-pe-border-light accent-primary focus:ring-2 focus:ring-ring cursor-pointer"
         style={styles?.input}
         {...props}
       />
-      <span className="tw:text-sm tw:text-text-primary" style={styles?.label}>
+      <span className="text-sm text-pe-text-primary" style={styles?.label}>
         {label}
       </span>
     </label>
diff --git a/src/inputs/CurrencyInput.tsx b/src/inputs/CurrencyInput.tsx
index c5b4dce..8d452ab 100644
--- a/src/inputs/CurrencyInput.tsx
+++ b/src/inputs/CurrencyInput.tsx
@@ -32,14 +32,14 @@ export const CurrencyInput = forwardRef<HTMLInputElement, CurrencyInputProps>(
     const displayValue = focused ? rawText : formatDisplay(value);
 
     return (
-      <div className={cn('tw:flex tw:flex-col tw:gap-1', className)} style={styles?.root}>
+      <div className={cn('flex flex-col gap-1', className)} style={styles?.root}>
         {label && (
-          <label className="tw:text-sm tw:font-medium tw:text-text-secondary" style={styles?.label}>
+          <label className="text-sm font-medium text-pe-text-secondary" style={styles?.label}>
             {label}
           </label>
         )}
-        <div className="tw:relative">
-          <span className="tw:absolute tw:left-3 tw:top-1/2 tw:-translate-y-1/2 tw:text-sm tw:text-text-secondary">
+        <div className="relative">
+          <span className="absolute left-3 top-1/2 -translate-y-1/2 text-sm text-pe-text-secondary">
             {currencySymbol}
           </span>
           <input
@@ -58,7 +58,7 @@ export const CurrencyInput = forwardRef<HTMLInputElement, CurrencyInputProps>(
             onChange={(e) => {
               setRawText(e.target.value);
             }}
-            className="tw:h-10 tw:w-full tw:rounded-element tw:border tw:border-border-light tw:pl-7 tw:pr-3 tw:text-sm tw:transition-colors tw:focus:outline-none tw:focus:ring-2 tw:focus:ring-ring tw:focus:border-primary"
+            className="h-10 w-full rounded-pe-element border border-pe-border-light pl-7 pr-3 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:border-primary"
             style={styles?.input}
             {...props}
           />
diff --git a/src/inputs/InputGroup.tsx b/src/inputs/InputGroup.tsx
index 3fb7dca..950b44e 100644
--- a/src/inputs/InputGroup.tsx
+++ b/src/inputs/InputGroup.tsx
@@ -13,17 +13,17 @@ export const InputGroup = forwardRef<HTMLDivElement, InputGroupProps>(
   ({ label, className, styles, children, ...props }, ref) => (
     <div
       ref={ref}
-      className={cn('tw:flex tw:flex-col tw:gap-md', className)}
+      className={cn('flex flex-col gap-pe-md', className)}
       style={styles?.root}
       {...props}
     >
       <h3
-        className="tw:text-xs tw:font-semibold tw:uppercase tw:tracking-wider tw:text-text-secondary"
+        className="text-xs font-semibold uppercase tracking-wider text-pe-text-secondary"
         style={styles?.label}
       >
         {label}
       </h3>
-      <div className="tw:flex tw:flex-col tw:gap-sm">{children}</div>
+      <div className="flex flex-col gap-pe-sm">{children}</div>
     </div>
   ),
 );
diff --git a/src/inputs/NumberInput.tsx b/src/inputs/NumberInput.tsx
index a28ecf5..2a1855a 100644
--- a/src/inputs/NumberInput.tsx
+++ b/src/inputs/NumberInput.tsx
@@ -18,9 +18,9 @@ export interface NumberInputProps
 
 export const NumberInput = forwardRef<HTMLInputElement, NumberInputProps>(
   ({ label, value, onChange, min, max, step = 1, className, styles, ...props }, ref) => (
-    <div className={cn('tw:flex tw:flex-col tw:gap-1', className)} style={styles?.root}>
+    <div className={cn('flex flex-col gap-1', className)} style={styles?.root}>
       {label && (
-        <label className="tw:text-sm tw:font-medium tw:text-text-secondary" style={styles?.label}>
+        <label className="text-sm font-medium text-pe-text-secondary" style={styles?.label}>
           {label}
         </label>
       )}
@@ -32,7 +32,7 @@ export const NumberInput = forwardRef<HTMLInputElement, NumberInputProps>(
         min={min}
         max={max}
         step={step}
-        className="tw:h-10 tw:w-full tw:rounded-element tw:border tw:border-border-light tw:px-3 tw:text-sm tw:transition-colors tw:focus:outline-none tw:focus:ring-2 tw:focus:ring-ring tw:focus:border-primary"
+        className="h-10 w-full rounded-pe-element border border-pe-border-light px-3 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:border-primary"
         style={styles?.input}
         {...props}
       />
diff --git a/src/inputs/SelectInput.tsx b/src/inputs/SelectInput.tsx
index 7391c34..c43a7ef 100644
--- a/src/inputs/SelectInput.tsx
+++ b/src/inputs/SelectInput.tsx
@@ -22,9 +22,9 @@ export interface SelectInputProps
 
 export const SelectInput = forwardRef<HTMLSelectElement, SelectInputProps>(
   ({ label, options, value, onChange, placeholder, className, styles, ...props }, ref) => (
-    <div className={cn('tw:flex tw:flex-col tw:gap-1', className)} style={styles?.root}>
+    <div className={cn('flex flex-col gap-1', className)} style={styles?.root}>
       {label && (
-        <label className="tw:text-sm tw:font-medium tw:text-text-secondary" style={styles?.label}>
+        <label className="text-sm font-medium text-pe-text-secondary" style={styles?.label}>
           {label}
         </label>
       )}
@@ -32,7 +32,7 @@ export const SelectInput = forwardRef<HTMLSelectElement, SelectInputProps>(
         ref={ref}
         value={value}
         onChange={(e) => onChange(e.target.value)}
-        className="tw:h-10 tw:w-full tw:rounded-element tw:border tw:border-border-light tw:px-3 tw:text-sm tw:transition-colors tw:focus:outline-none tw:focus:ring-2 tw:focus:ring-ring tw:focus:border-primary tw:appearance-none tw:bg-white"
+        className="h-10 w-full rounded-pe-element border border-pe-border-light px-3 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:border-primary appearance-none bg-white"
         style={styles?.select}
         {...props}
       >
diff --git a/src/inputs/SliderInput.tsx b/src/inputs/SliderInput.tsx
index 1c477ea..6ea35c8 100644
--- a/src/inputs/SliderInput.tsx
+++ b/src/inputs/SliderInput.tsx
@@ -20,13 +20,13 @@ export interface SliderInputProps
 
 export const SliderInput = forwardRef<HTMLInputElement, SliderInputProps>(
   ({ label, value, onChange, min, max, step = 1, formatValue, className, styles, ...props }, ref) => (
-    <div className={cn('tw:flex tw:flex-col tw:gap-1', className)} style={styles?.root}>
+    <div className={cn('flex flex-col gap-1', className)} style={styles?.root}>
       {label && (
-        <div className="tw:flex tw:items-center tw:justify-between">
-          <label className="tw:text-sm tw:font-medium tw:text-text-secondary" style={styles?.label}>
+        <div className="flex items-center justify-between">
+          <label className="text-sm font-medium text-pe-text-secondary" style={styles?.label}>
             {label}
           </label>
-          <span className="tw:text-sm tw:font-medium tw:text-text-primary" style={styles?.value}>
+          <span className="text-sm font-medium text-pe-text-primary" style={styles?.value}>
             {formatValue ? formatValue(value) : value}
           </span>
         </div>
@@ -39,7 +39,7 @@ export const SliderInput = forwardRef<HTMLInputElement, SliderInputProps>(
         min={min}
         max={max}
         step={step}
-        className="tw:w-full tw:accent-primary tw:cursor-pointer"
+        className="w-full accent-primary cursor-pointer"
         style={styles?.input}
         {...props}
       />
diff --git a/src/layout/DashboardShell.tsx b/src/layout/DashboardShell.tsx
index d184243..f64ba10 100644
--- a/src/layout/DashboardShell.tsx
+++ b/src/layout/DashboardShell.tsx
@@ -10,7 +10,7 @@ export const DashboardShell = forwardRef<HTMLDivElement, DashboardShellProps>(
     <div
       ref={ref}
       className={cn(
-        'tw:min-h-screen tw:bg-bg-secondary tw:font-sans tw:text-text-primary',
+        'min-h-screen bg-pe-bg-secondary font-sans text-pe-text-primary',
         className,
       )}
       style={styles?.root}
diff --git a/src/layout/Header.tsx b/src/layout/Header.tsx
index 4805356..1dac139 100644
--- a/src/layout/Header.tsx
+++ b/src/layout/Header.tsx
@@ -3,12 +3,12 @@ import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
 import { cn } from '../utils/cn';
 
 const headerVariants = cva(
-  'tw:flex tw:items-center tw:justify-between tw:h-[58px] tw:px-2xl',
+  'flex items-center justify-between h-[58px] px-pe-2xl',
   {
     variants: {
       variant: {
-        light: 'tw:bg-white tw:border-b tw:border-border-light',
-        dark: 'tw:bg-primary-600 tw:text-white tw:shadow-md tw:border-b tw:border-border-dark',
+        light: 'bg-white border-b border-pe-border-light',
+        dark: 'bg-pe-primary-600 text-white shadow-md border-b border-pe-border-dark',
       },
     },
     defaultVariants: { variant: 'light' },
@@ -16,14 +16,14 @@ const headerVariants = cva(
 );
 
 const actionsVariants = cva(
-  'tw:flex tw:items-center tw:gap-3xl',
+  'flex items-center gap-pe-3xl',
   {
     variants: {
       variant: {
         light:
-          '[&_a]:tw:text-text-secondary [&_a]:tw:text-lg [&_a]:tw:font-medium [&_a]:tw:no-underline [&_a]:tw:hover:text-text-primary [&_button]:tw:text-text-secondary',
+          '[&_a]:text-pe-text-secondary [&_a]:text-lg [&_a]:font-medium [&_a]:no-underline [&_a]:hover:text-pe-text-primary',
         dark:
-          '[&_a]:tw:text-white [&_a]:tw:text-lg [&_a]:tw:font-medium [&_a]:tw:no-underline [&_a]:tw:hover:opacity-80 [&_button]:tw:text-white',
+          '[&_a]:text-white [&_a]:text-lg [&_a]:font-medium [&_a]:no-underline [&_a]:hover:opacity-80',
       },
     },
     defaultVariants: { variant: 'light' },
@@ -31,12 +31,12 @@ const actionsVariants = cva(
 );
 
 const subtitleVariants = cva(
-  'tw:flex tw:items-center tw:gap-md',
+  'flex items-center gap-pe-md',
   {
     variants: {
       variant: {
-        light: '[&>span]:tw:text-text-secondary [&>span]:tw:text-lg [&>span]:tw:font-medium',
-        dark: '[&>span]:tw:text-white/70 [&>span]:tw:text-lg [&>span]:tw:font-medium',
+        light: '[&>span]:text-pe-text-secondary [&>span]:text-lg [&>span]:font-medium',
+        dark: '[&>span]:text-white/70 [&>span]:text-lg [&>span]:font-medium',
       },
     },
     defaultVariants: { variant: 'light' },
diff --git a/src/layout/InputPanel.tsx b/src/layout/InputPanel.tsx
index 7438a7d..6fcb137 100644
--- a/src/layout/InputPanel.tsx
+++ b/src/layout/InputPanel.tsx
@@ -10,13 +10,13 @@ export const InputPanel = forwardRef<HTMLDivElement, InputPanelProps>(
   ({ title, className, styles, children, ...props }, ref) => (
     <div
       ref={ref}
-      className={cn('tw:flex tw:flex-col tw:gap-lg tw:p-lg', className)}
+      className={cn('flex flex-col gap-pe-lg p-pe-lg', className)}
       style={styles?.root}
       {...props}
     >
       {title && (
         <h2
-          className="tw:text-lg tw:font-semibold tw:text-text-primary"
+          className="text-lg font-semibold text-pe-text-primary"
           style={styles?.title}
         >
           {title}
diff --git a/src/layout/ResultsPanel.tsx b/src/layout/ResultsPanel.tsx
index af1fb2c..5466b43 100644
--- a/src/layout/ResultsPanel.tsx
+++ b/src/layout/ResultsPanel.tsx
@@ -10,7 +10,7 @@ export const ResultsPanel = forwardRef<HTMLDivElement, ResultsPanelProps>(
     <div
       ref={ref}
       className={cn(
-        'tw:flex tw:flex-col tw:gap-2xl tw:p-2xl',
+        'flex flex-col gap-pe-2xl p-pe-2xl',
         className,
       )}
       style={styles?.root}
diff --git a/src/layout/SidebarLayout.tsx b/src/layout/SidebarLayout.tsx
index 48c506c..2a5129d 100644
--- a/src/layout/SidebarLayout.tsx
+++ b/src/layout/SidebarLayout.tsx
@@ -15,18 +15,18 @@ export const SidebarLayout = forwardRef<HTMLDivElement, SidebarLayoutProps>(
   ({ sidebar, sidebarWidth = '320px', className, styles, children, ...props }, ref) => (
     <div
       ref={ref}
-      className={cn('tw:flex tw:flex-col tw:md:flex-row tw:min-h-screen', className)}
+      className={cn('flex flex-col md:flex-row min-h-screen', className)}
       style={styles?.root}
       {...props}
     >
       <aside
-        className="tw:w-full tw:md:flex-shrink-0 tw:border-r tw:border-border-light tw:bg-white tw:overflow-y-auto"
+        className="w-full md:flex-shrink-0 border-r border-pe-border-light bg-white overflow-y-auto"
         style={{ ...styles?.sidebar, maxWidth: sidebarWidth }}
       >
         {sidebar}
       </aside>
       <main
-        className="tw:flex-1 tw:overflow-y-auto"
+        className="flex-1 overflow-y-auto"
         style={styles?.content}
       >
         {children}
diff --git a/src/layout/SingleColumnLayout.tsx b/src/layout/SingleColumnLayout.tsx
index 2a533ba..545fa65 100644
--- a/src/layout/SingleColumnLayout.tsx
+++ b/src/layout/SingleColumnLayout.tsx
@@ -10,12 +10,12 @@ export const SingleColumnLayout = forwardRef<HTMLDivElement, SingleColumnLayoutP
   ({ maxWidth = '976px', className, styles, children, ...props }, ref) => (
     <div
       ref={ref}
-      className={cn('tw:min-h-screen tw:bg-bg-secondary', className)}
+      className={cn('min-h-screen bg-pe-bg-secondary', className)}
       style={styles?.root}
       {...props}
     >
       <div
-        className="tw:mx-auto tw:px-lg tw:py-2xl"
+        className="mx-auto px-pe-lg py-pe-2xl"
         style={{ maxWidth, ...styles?.content }}
       >
         {children}
diff --git a/src/primitives/Badge.tsx b/src/primitives/Badge.tsx
index fd6e81e..539e4f4 100644
--- a/src/primitives/Badge.tsx
+++ b/src/primitives/Badge.tsx
@@ -3,16 +3,16 @@ import { type HTMLAttributes } from 'react';
 import { cn } from '../utils/cn';
 
 const badgeVariants = cva(
-  'tw:inline-flex tw:items-center tw:rounded-chip tw:px-3 tw:py-1 tw:text-xs tw:font-medium tw:transition-colors',
+  'inline-flex items-center rounded-pe-chip px-3 py-1 text-xs font-medium transition-colors',
   {
     variants: {
       variant: {
-        default: 'tw:bg-primary tw:text-primary-foreground',
-        secondary: 'tw:bg-secondary tw:text-secondary-foreground',
-        outline: 'tw:border tw:border-border-light tw:text-text-primary',
-        success: 'tw:bg-green-100 tw:text-green-800',
-        warning: 'tw:bg-yellow-100 tw:text-yellow-800',
-        error: 'tw:bg-red-100 tw:text-red-800',
+        default: 'bg-primary text-primary-foreground',
+        secondary: 'bg-secondary text-secondary-foreground',
+        outline: 'border border-pe-border-light text-pe-text-primary',
+        success: 'bg-green-100 text-green-800',
+        warning: 'bg-yellow-100 text-yellow-800',
+        error: 'bg-red-100 text-red-800',
       },
     },
     defaultVariants: { variant: 'default' },
diff --git a/src/primitives/Button.tsx b/src/primitives/Button.tsx
index cc46245..94b6e92 100644
--- a/src/primitives/Button.tsx
+++ b/src/primitives/Button.tsx
@@ -3,22 +3,22 @@ import { forwardRef, type ButtonHTMLAttributes } from 'react';
 import { cn } from '../utils/cn';
 
 const buttonVariants = cva(
-  'tw:inline-flex tw:items-center tw:justify-center tw:gap-2 tw:rounded-element tw:text-sm tw:font-medium tw:transition-colors tw:cursor-pointer tw:disabled:pointer-events-none tw:disabled:opacity-50',
+  'inline-flex items-center justify-center gap-2 rounded-pe-element text-sm font-medium transition-colors cursor-pointer disabled:pointer-events-none disabled:opacity-50',
   {
     variants: {
       variant: {
         default:
-          'tw:bg-primary tw:text-primary-foreground tw:hover:bg-primary-600',
+          'bg-primary text-primary-foreground hover:bg-pe-primary-600',
         outline:
-          'tw:border tw:border-border-light tw:bg-white tw:hover:bg-gray-50',
-        ghost: 'tw:hover:bg-gray-100',
-        destructive: 'tw:bg-error tw:text-white tw:hover:bg-red-600',
+          'border border-pe-border-light bg-white hover:bg-pe-gray-50',
+        ghost: 'hover:bg-pe-gray-100',
+        destructive: 'bg-pe-error text-white hover:bg-red-600',
       },
       size: {
-        default: 'tw:h-9 tw:px-4 tw:py-2',
-        sm: 'tw:h-8 tw:px-3 tw:text-xs',
-        lg: 'tw:h-10 tw:px-6',
-        icon: 'tw:h-9 tw:w-9',
+        default: 'h-9 px-4 py-2',
+        sm: 'h-8 px-3 text-xs',
+        lg: 'h-10 px-6',
+        icon: 'h-9 w-9',
       },
     },
     defaultVariants: { variant: 'default', size: 'default' },
diff --git a/src/primitives/Card.tsx b/src/primitives/Card.tsx
index d3f904b..b7925cd 100644
--- a/src/primitives/Card.tsx
+++ b/src/primitives/Card.tsx
@@ -10,7 +10,7 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(
     <div
       ref={ref}
       className={cn(
-        'tw:bg-white tw:border tw:border-border-light tw:rounded-container tw:shadow-sm',
+        'bg-white border border-pe-border-light rounded-pe-container shadow-sm',
         className,
       )}
       style={styles?.root}
@@ -26,7 +26,7 @@ export const CardHeader = forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('tw:flex tw:flex-col tw:gap-1.5 tw:p-lg', className)}
+    className={cn('flex flex-col gap-1.5 p-pe-lg', className)}
     {...props}
   />
 ));
@@ -38,7 +38,7 @@ export const CardTitle = forwardRef<
 >(({ className, ...props }, ref) => (
   <h3
     ref={ref}
-    className={cn('tw:text-lg tw:font-semibold tw:text-text-primary', className)}
+    className={cn('text-lg font-semibold text-pe-text-primary', className)}
     {...props}
   />
 ));
@@ -50,7 +50,7 @@ export const CardDescription = forwardRef<
 >(({ className, ...props }, ref) => (
   <p
     ref={ref}
-    className={cn('tw:text-sm tw:text-text-secondary', className)}
+    className={cn('text-sm text-pe-text-secondary', className)}
     {...props}
   />
 ));
@@ -62,7 +62,7 @@ export const CardContent = forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('tw:p-lg tw:pt-0', className)}
+    className={cn('p-pe-lg pt-0', className)}
     {...props}
   />
 ));
@@ -74,7 +74,7 @@ export const CardFooter = forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('tw:flex tw:items-center tw:p-lg tw:pt-0', className)}
+    className={cn('flex items-center p-pe-lg pt-0', className)}
     {...props}
   />
 ));
diff --git a/src/primitives/Tabs.tsx b/src/primitives/Tabs.tsx
index d3538db..bf2168e 100644
--- a/src/primitives/Tabs.tsx
+++ b/src/primitives/Tabs.tsx
@@ -56,7 +56,7 @@ export const TabsList = forwardRef<HTMLDivElement, TabsListProps>(
       ref={ref}
       role="tablist"
       className={cn(
-        'tw:inline-flex tw:items-center tw:gap-1 tw:border-b tw:border-border-light',
+        'inline-flex items-center gap-1 border-b border-pe-border-light',
         className,
       )}
       {...props}
@@ -82,11 +82,11 @@ export const TabsTrigger = forwardRef<HTMLButtonElement, TabsTriggerProps>(
         aria-selected={isActive}
         data-state={isActive ? 'active' : 'inactive'}
         className={cn(
-          'tw:px-4 tw:py-2 tw:text-sm tw:font-medium tw:transition-colors tw:cursor-pointer',
-          'tw:border-b-2 tw:-mb-px',
+          'px-4 py-2 text-sm font-medium transition-colors cursor-pointer',
+          'border-b-2 -mb-px',
           isActive
-            ? 'tw:border-primary tw:text-primary'
-            : 'tw:border-transparent tw:text-text-secondary tw:hover:text-text-primary',
+            ? 'border-primary text-primary'
+            : 'border-transparent text-pe-text-secondary hover:text-pe-text-primary',
           className,
         )}
         onClick={() => setActiveTab(value)}
@@ -110,7 +110,7 @@ export const TabsContent = forwardRef<HTMLDivElement, TabsContentProps>(
       <div
         ref={ref}
         role="tabpanel"
-        className={cn('tw:pt-4', className)}
+        className={cn('pt-4', className)}
         {...props}
       />
     );
diff --git a/src/utils/cn.ts b/src/utils/cn.ts
index 2819a83..d22ea5f 100644
--- a/src/utils/cn.ts
+++ b/src/utils/cn.ts
@@ -1,5 +1,15 @@
 import { clsx, type ClassValue } from 'clsx';
-import { twMerge } from 'tailwind-merge';
+import { extendTailwindMerge } from 'tailwind-merge';
+
+const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      'text-color': [
+        { text: ['pe-primary', 'pe-gray', 'pe-blue', 'pe-text', 'pe-success', 'pe-error', 'pe-warning', 'pe-info', 'pe-border', 'pe-bg', 'primary-foreground'] },
+      ],
+    },
+  },
+});
 
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
diff --git a/src/utils/getCssVar.ts b/src/utils/getCssVar.ts
new file mode 100644
index 0000000..b14fd6c
--- /dev/null
+++ b/src/utils/getCssVar.ts
@@ -0,0 +1,11 @@
+/**
+ * Read a CSS custom property value at runtime.
+ * Useful for Recharts and other SVG-based libraries that
+ * need resolved color strings (not CSS var() references).
+ *
+ * @example
+ *   getCssVar('--pe-color-primary-500') // '#319795'
+ */
+export function getCssVar(name: string): string {
+  return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+}
diff --git a/src/utils/index.ts b/src/utils/index.ts
index 582961c..78faad9 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -1,2 +1,3 @@
 export { cn } from './cn';
+export { getCssVar } from './getCssVar';
 export { formatCurrency, formatPercent, formatNumber } from './formatters';
diff --git a/tests/primitives/Badge.test.tsx b/tests/primitives/Badge.test.tsx
index b97ebaa..b2f22e7 100644
--- a/tests/primitives/Badge.test.tsx
+++ b/tests/primitives/Badge.test.tsx
@@ -9,7 +9,7 @@ describe('Badge', () => {
   });
 
   it('accepts className override', () => {
-    render(<Badge className="tw:bg-blue-500">Tag</Badge>);
-    expect(screen.getByText('Tag').className).toContain('tw:bg-blue-500');
+    render(<Badge className="bg-blue-500">Tag</Badge>);
+    expect(screen.getByText('Tag').className).toContain('bg-blue-500');
   });
 });
diff --git a/tests/primitives/Button.test.tsx b/tests/primitives/Button.test.tsx
index 95f332f..3bf5e01 100644
--- a/tests/primitives/Button.test.tsx
+++ b/tests/primitives/Button.test.tsx
@@ -21,8 +21,8 @@ describe('Button', () => {
   });
 
   it('accepts className override', () => {
-    render(<Button className="tw:bg-blue-500">Styled</Button>);
-    expect(screen.getByRole('button').className).toContain('tw:bg-blue-500');
+    render(<Button className="bg-blue-500">Styled</Button>);
+    expect(screen.getByRole('button').className).toContain('bg-blue-500');
   });
 
   it('accepts styles prop', () => {

From 23fa7843fbd401dfefc5f8199e1d1418b5f19566 Mon Sep 17 00:00:00 2001
From: Anthony Volk <anth.volk@gmail.com>
Date: Fri, 6 Mar 2026 20:27:25 +0100
Subject: [PATCH 2/7] Migrate to CSS-first design tokens with Tailwind v4 and
 shadcn/ui

Replace TypeScript token files and getCssVar() helper with a single
src/theme/tokens.css using three-layer architecture (:root, @theme inline,
@theme). Rewrite all 24 components from pe-* classes to standard Tailwind
utility classes. Add custom slider thumb styling with theme primary color
and fix bar chart negative color to use var(--color-gray-600).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CLAUDE.md                             |  20 ++-
 components.json                       |  18 ++
 demo/Demo.tsx                         |  52 +++---
 demo/index.html                       |   4 -
 demo/main.tsx                         |   2 +-
 package.json                          |   8 +-
 src/app.css                           | 244 --------------------------
 src/charts/ChartContainer.tsx         |   8 +-
 src/charts/PEAreaChart.tsx            |   5 +-
 src/charts/PEBarChart.tsx             |   7 +-
 src/charts/PELineChart.tsx            |   5 +-
 src/charts/PEWaterfallChart.tsx       |   9 +-
 src/charts/chartDefaults.ts           |  43 +++--
 src/display/DataTable.tsx             |  10 +-
 src/display/MetricCard.tsx            |  14 +-
 src/display/PolicyEngineWatermark.tsx |   2 +-
 src/display/SummaryText.tsx           |   2 +-
 src/index.ts                          |   5 +-
 src/inputs/CheckboxInput.tsx          |   4 +-
 src/inputs/CurrencyInput.tsx          |   6 +-
 src/inputs/InputGroup.tsx             |   6 +-
 src/inputs/NumberInput.tsx            |   4 +-
 src/inputs/SelectInput.tsx            |   4 +-
 src/inputs/SliderInput.tsx            |   4 +-
 src/layout/DashboardShell.tsx         |   2 +-
 src/layout/Header.tsx                 |  14 +-
 src/layout/InputPanel.tsx             |   4 +-
 src/layout/ResultsPanel.tsx           |   2 +-
 src/layout/SidebarLayout.tsx          |   2 +-
 src/layout/SingleColumnLayout.tsx     |   4 +-
 src/primitives/Badge.tsx              |   4 +-
 src/primitives/Button.tsx             |  10 +-
 src/primitives/Card.tsx               |  12 +-
 src/primitives/Tabs.tsx               |   5 +-
 src/theme/index.ts                    |   2 +
 src/theme/tokens.css                  | 230 ++++++++++++++++++++++++
 src/tokens/charts.ts                  | 212 ----------------------
 src/tokens/colors.ts                  | 139 ---------------
 src/tokens/index.ts                   |   4 -
 src/tokens/spacing.ts                 |  97 ----------
 src/tokens/typography.ts              |  99 -----------
 src/utils/cn.ts                       |  12 +-
 src/utils/formatters.ts               |  30 +++-
 src/utils/getCssVar.ts                |  11 --
 src/utils/index.ts                    |   1 -
 tests/charts/Charts.test.tsx          |   2 +-
 tests/tokens/charts.test.ts           |  22 +--
 tests/tokens/colors.test.ts           |  35 ----
 tests/tokens/typography.test.ts       |  25 ---
 49 files changed, 432 insertions(+), 1034 deletions(-)
 create mode 100644 components.json
 delete mode 100644 src/app.css
 create mode 100644 src/theme/index.ts
 create mode 100644 src/theme/tokens.css
 delete mode 100644 src/tokens/charts.ts
 delete mode 100644 src/tokens/colors.ts
 delete mode 100644 src/tokens/index.ts
 delete mode 100644 src/tokens/spacing.ts
 delete mode 100644 src/tokens/typography.ts
 delete mode 100644 src/utils/getCssVar.ts
 delete mode 100644 tests/tokens/colors.test.ts
 delete mode 100644 tests/tokens/typography.test.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 6a00e75..3b82f28 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # @policyengine/ui-kit
 
-PolicyEngine UI kit — design tokens, Tailwind CSS v4 theme, and React 19 components for dashboards and calculators.
+PolicyEngine UI kit — CSS-first design tokens, Tailwind CSS v4 theme, shadcn/ui primitives, and React 19 components for dashboards and calculators.
 
 ## Commands
 
@@ -8,22 +8,32 @@ PolicyEngine UI kit — design tokens, Tailwind CSS v4 theme, and React 19 compo
 - Build: `bun run build`
 - Test: `bun run test`
 - Type check: `bun run typecheck`
+- Demo: `bun run dev:demo`
 
 ## Architecture
 
 - **Vite library mode** — builds ESM + CJS + types + styles.css
-- **Tailwind CSS v4** with `tw:` prefix (mirrors policyengine-app-v2)
+- **Tailwind CSS v4** with standard class names (no prefix)
+- **shadcn/ui** pattern for primitives (Button, Badge, Card, Tabs)
 - **CVA** (class-variance-authority) for component variants
 - **Recharts** for chart components (peer dependency)
 
 ## Design tokens
 
-Tokens are in `src/tokens/` — colors, typography, spacing, charts. These are the source of truth for all PolicyEngine applications. The same values appear as CSS custom properties in `src/app.css` via the `@theme` block.
+Tokens are in `src/theme/tokens.css` — the single source of truth for all frontend projects. This CSS file defines:
+
+1. **Layer 1 (`:root`)**: shadcn/ui semantic variables (`--primary`, `--background`, `--chart-1`, etc.)
+2. **Layer 2 (`@theme inline`)**: Bridges `:root` vars to Tailwind utilities (`bg-primary`, `text-foreground`)
+3. **Layer 3 (`@theme`)**: Brand palette (`bg-teal-500`, `text-gray-600`), font sizes, spacing, breakpoints
+
+Consumers import: `@import "@policyengine/ui-kit/theme.css";`
 
 ## Styling rules
 
-- All Tailwind classes use `tw:` prefix (e.g. `tw:bg-primary-500`)
+- Use standard Tailwind classes (`bg-primary`, `text-muted-foreground`, `border-border`, `rounded-lg`)
+- Use brand palette classes for specific colors (`bg-teal-500`, `text-gray-600`)
 - Use `cn()` from `src/utils/cn.ts` for class merging
-- Never hardcode hex colors — use token classes or imports
+- Recharts charts use CSS vars directly: `fill="var(--chart-1)"`
+- Never hardcode hex colors in component code
 - Sentence case for all UI text
 - Every component accepts `className` and `styles` props
diff --git a/components.json b/components.json
new file mode 100644
index 0000000..76048ee
--- /dev/null
+++ b/components.json
@@ -0,0 +1,18 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/theme/tokens.css",
+    "baseColor": "neutral",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/utils",
+    "ui": "@/primitives",
+    "lib": "@/utils"
+  }
+}
diff --git a/demo/Demo.tsx b/demo/Demo.tsx
index e67630d..f96bf8c 100644
--- a/demo/Demo.tsx
+++ b/demo/Demo.tsx
@@ -42,8 +42,8 @@ import { PELineChart } from '../src/charts/PELineChart';
 import { PEAreaChart } from '../src/charts/PEAreaChart';
 import { PEWaterfallChart } from '../src/charts/PEWaterfallChart';
 
-// Tokens (for display)
-import { formatCurrency } from '../src/tokens/charts';
+// Utils
+import { formatCurrency } from '../src/utils/formatters';
 
 // Assets
 import { logos } from '../src/assets';
@@ -164,7 +164,7 @@ function Section({
 }) {
   return (
     <section className="mb-12">
-      <h2 className="text-2xl font-bold text-pe-text-primary mb-6 pb-2 border-b border-pe-border-light">
+      <h2 className="text-2xl font-bold text-foreground mb-6 pb-2 border-b border-border">
         {title}
       </h2>
       {children}
@@ -181,7 +181,7 @@ function SubSection({
 }) {
   return (
     <div className="mb-8">
-      <h3 className="text-lg font-semibold text-pe-text-secondary mb-4">
+      <h3 className="text-lg font-semibold text-muted-foreground mb-4">
         {title}
       </h3>
       {children}
@@ -205,10 +205,10 @@ export function Demo() {
     <DashboardShell>
       <div className="max-w-6xl mx-auto px-6 py-8">
         <div className="mb-10">
-          <h1 className="text-4xl font-bold text-pe-text-primary mb-2">
+          <h1 className="text-4xl font-bold text-foreground mb-2">
             @policyengine/ui-kit
           </h1>
-          <p className="text-lg text-pe-text-secondary">
+          <p className="text-lg text-muted-foreground">
             Component gallery — every component rendered with example data
           </p>
         </div>
@@ -259,7 +259,7 @@ export function Demo() {
                   </CardDescription>
                 </CardHeader>
                 <CardContent>
-                  <p className="text-sm text-pe-text-secondary">
+                  <p className="text-sm text-muted-foreground">
                     This reform would provide a monthly payment of $500 to every
                     adult US citizen, funded through a combination of income tax
                     increases and spending reductions.
@@ -280,7 +280,7 @@ export function Demo() {
                   </CardDescription>
                 </CardHeader>
                 <CardContent>
-                  <p className="text-sm text-pe-text-secondary">
+                  <p className="text-sm text-muted-foreground">
                     Expanding the Child Tax Credit to $3,600 per child under 6
                     and $3,000 for children 6-17, with full refundability for
                     all qualifying families.
@@ -305,7 +305,7 @@ export function Demo() {
               <TabsContent value="overview">
                 <Card>
                   <CardContent className="pt-4">
-                    <p className="text-sm text-pe-text-secondary">
+                    <p className="text-sm text-muted-foreground">
                       This tab shows the overview of the policy reform,
                       including headline metrics and a summary of key impacts
                       across income deciles.
@@ -316,7 +316,7 @@ export function Demo() {
               <TabsContent value="distributional">
                 <Card>
                   <CardContent className="pt-4">
-                    <p className="text-sm text-pe-text-secondary">
+                    <p className="text-sm text-muted-foreground">
                       Distributional analysis shows how the reform affects
                       different income groups, with the bottom 5 deciles
                       gaining and the top 4 deciles bearing the net cost.
@@ -327,7 +327,7 @@ export function Demo() {
               <TabsContent value="budget">
                 <Card>
                   <CardContent className="pt-4">
-                    <p className="text-sm text-pe-text-secondary">
+                    <p className="text-sm text-muted-foreground">
                       The budget impact analysis estimates this reform would
                       cost approximately $160 billion annually, partially
                       offset by increased economic activity.
@@ -375,7 +375,7 @@ export function Demo() {
                   <a href="#">Research</a>
                   <a href="#">About</a>
                   <a href="#">Donate</a>
-                  <Button size="sm" className="bg-white text-pe-primary-600 hover:bg-pe-gray-100">Sign in</Button>
+                  <Button size="sm" className="bg-white text-teal-600 hover:bg-gray-100">Sign in</Button>
                 </>
               }
             >
@@ -390,22 +390,22 @@ export function Demo() {
               <Card>
                 <CardContent className="pt-4 flex flex-col items-center gap-2">
                   <img src={logos.tealWordmark} alt="Teal wordmark (SVG)" className="h-6" />
-                  <span className="text-xs text-pe-text-tertiary">tealWordmark</span>
+                  <span className="text-xs text-gray-400">tealWordmark</span>
                 </CardContent>
               </Card>
               <Card>
                 <CardContent className="pt-4 flex flex-col items-center gap-2">
                   <img src={logos.tealWordmarkPng} alt="Teal wordmark (PNG)" className="h-6" />
-                  <span className="text-xs text-pe-text-tertiary">tealWordmarkPng</span>
+                  <span className="text-xs text-gray-400">tealWordmarkPng</span>
                 </CardContent>
               </Card>
-              <Card className="bg-pe-primary-600">
+              <Card className="bg-teal-600">
                 <CardContent className="pt-4 flex flex-col items-center gap-2">
                   <img src={logos.whiteWordmark} alt="White wordmark (SVG)" className="h-6" />
                   <span className="text-xs text-white/60">whiteWordmark</span>
                 </CardContent>
               </Card>
-              <Card className="bg-pe-primary-600">
+              <Card className="bg-teal-600">
                 <CardContent className="pt-4 flex flex-col items-center gap-2">
                   <img src={logos.whiteWordmarkPng} alt="White wordmark (PNG)" className="h-6" />
                   <span className="text-xs text-white/60">whiteWordmarkPng</span>
@@ -414,28 +414,28 @@ export function Demo() {
               <Card>
                 <CardContent className="pt-4 flex flex-col items-center gap-2">
                   <img src={logos.tealSquare} alt="Teal square (SVG)" className="h-10" />
-                  <span className="text-xs text-pe-text-tertiary">tealSquare</span>
+                  <span className="text-xs text-gray-400">tealSquare</span>
                 </CardContent>
               </Card>
               <Card>
                 <CardContent className="pt-4 flex flex-col items-center gap-2">
                   <img src={logos.tealSquarePng} alt="Teal square (PNG)" className="h-10" />
-                  <span className="text-xs text-pe-text-tertiary">tealSquarePng</span>
+                  <span className="text-xs text-gray-400">tealSquarePng</span>
                 </CardContent>
               </Card>
               <Card>
                 <CardContent className="pt-4 flex flex-col items-center gap-2">
                   <img src={logos.tealSquareTransparent} alt="Teal square transparent (PNG)" className="h-10" />
-                  <span className="text-xs text-pe-text-tertiary">tealSquareTransparent</span>
+                  <span className="text-xs text-gray-400">tealSquareTransparent</span>
                 </CardContent>
               </Card>
               <Card>
                 <CardContent className="pt-4 flex flex-col items-center gap-2">
                   <img src={logos.tealSquarePadded} alt="Teal square padded (SVG)" className="h-10" />
-                  <span className="text-xs text-pe-text-tertiary">tealSquarePadded</span>
+                  <span className="text-xs text-gray-400">tealSquarePadded</span>
                 </CardContent>
               </Card>
-              <Card className="bg-pe-primary-600">
+              <Card className="bg-teal-600">
                 <CardContent className="pt-4 flex flex-col items-center gap-2">
                   <img src={logos.whiteSquare} alt="White square (SVG)" className="h-10" />
                   <span className="text-xs text-white/60">whiteSquare</span>
@@ -445,7 +445,7 @@ export function Demo() {
           </SubSection>
 
           <SubSection title="SidebarLayout (with InputPanel + ResultsPanel)">
-            <div className="border border-pe-border-light rounded-pe-container overflow-hidden h-[500px]">
+            <div className="border border-border rounded-lg overflow-hidden h-[500px]">
               <SidebarLayout
                 sidebar={
                   <InputPanel title="Household parameters">
@@ -512,7 +512,7 @@ export function Demo() {
           </SubSection>
 
           <SubSection title="SingleColumnLayout">
-            <div className="border border-pe-border-light rounded-pe-container overflow-hidden">
+            <div className="border border-border rounded-lg overflow-hidden">
               <SingleColumnLayout maxWidth="700px">
                 <h3 className="text-xl font-bold mb-4">
                   Policy summary
@@ -651,7 +651,7 @@ export function Demo() {
               <strong>{dependents} dependents</strong> would receive{' '}
               <strong>$12,000</strong> in annual UBI payments and pay an
               additional <strong>$8,200</strong> in income taxes, for a{' '}
-              <strong className="text-pe-primary-500">
+              <strong className="text-teal-500">
                 net gain of $3,800
               </strong>{' '}
               per year.
@@ -703,7 +703,7 @@ export function Demo() {
                   {
                     dataKey: 'baseline',
                     name: 'Baseline',
-                    color: '#9CA3AF',
+                    color: 'var(--gray-400)',
                     strokeDasharray: '5 5',
                   },
                   { dataKey: 'reform', name: 'With UBI reform' },
@@ -745,7 +745,7 @@ export function Demo() {
           </div>
         </Section>
 
-        <div className="text-center py-8 text-sm text-pe-text-tertiary">
+        <div className="text-center py-8 text-sm text-gray-400">
           @policyengine/ui-kit v0.1.0 — All components shown with example data
         </div>
       </div>
diff --git a/demo/index.html b/demo/index.html
index 7b4f756..5b00f56 100644
--- a/demo/index.html
+++ b/demo/index.html
@@ -10,10 +10,6 @@
       href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap"
       rel="stylesheet"
     />
-    <link
-      rel="stylesheet"
-      href="https://unpkg.com/@policyengine/design-system/dist/tokens.css"
-    />
   </head>
   <body>
     <div id="root"></div>
diff --git a/demo/main.tsx b/demo/main.tsx
index 07de5f6..46805e0 100644
--- a/demo/main.tsx
+++ b/demo/main.tsx
@@ -1,6 +1,6 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import '../src/app.css';
+import '../src/theme/tokens.css';
 import { Demo } from './Demo';
 
 createRoot(document.getElementById('root')!).render(
diff --git a/package.json b/package.json
index 68ef0fb..599c05a 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,8 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./styles.css": "./dist/styles.css"
+    "./styles.css": "./dist/styles.css",
+    "./theme.css": "./src/theme/tokens.css"
   },
   "files": [
     "dist"
@@ -26,7 +27,6 @@
     "lint": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@policyengine/design-system": "*",
     "react": ">=19",
     "react-dom": ">=19",
     "recharts": ">=2.12"
@@ -34,7 +34,9 @@
   "dependencies": {
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "tailwind-merge": "^3.5.0"
+    "lucide-react": "^0.577.0",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.2.0",
diff --git a/src/app.css b/src/app.css
deleted file mode 100644
index 207d491..0000000
--- a/src/app.css
+++ /dev/null
@@ -1,244 +0,0 @@
-@import 'tailwindcss';
-
-@theme {
-  /* =======================================================
-   * PolicyEngine Design Token Bridge
-   * =======================================================
-   * All tokens bridge to @policyengine/design-system CSS
-   * variables (--pe-*). Consumers MUST load tokens.css:
-   *   <link rel="stylesheet" href="https://unpkg.com/@policyengine/design-system/dist/tokens.css">
-   * =======================================================
-   */
-
-  /* Primary brand colors - teal */
-  --color-pe-primary-50: var(--pe-color-primary-50);
-  --color-pe-primary-100: var(--pe-color-primary-100);
-  --color-pe-primary-200: var(--pe-color-primary-200);
-  --color-pe-primary-300: var(--pe-color-primary-300);
-  --color-pe-primary-400: var(--pe-color-primary-400);
-  --color-pe-primary-500: var(--pe-color-primary-500);
-  --color-pe-primary-600: var(--pe-color-primary-600);
-  --color-pe-primary-700: var(--pe-color-primary-700);
-  --color-pe-primary-800: var(--pe-color-primary-800);
-  --color-pe-primary-900: var(--pe-color-primary-900);
-
-  /* Gray scale */
-  --color-pe-gray-50: var(--pe-color-gray-50);
-  --color-pe-gray-100: var(--pe-color-gray-100);
-  --color-pe-gray-200: var(--pe-color-gray-200);
-  --color-pe-gray-300: var(--pe-color-gray-300);
-  --color-pe-gray-400: var(--pe-color-gray-400);
-  --color-pe-gray-500: var(--pe-color-gray-500);
-  --color-pe-gray-600: var(--pe-color-gray-600);
-  --color-pe-gray-700: var(--pe-color-gray-700);
-  --color-pe-gray-800: var(--pe-color-gray-800);
-  --color-pe-gray-900: var(--pe-color-gray-900);
-
-  /* Blue accent colors */
-  --color-pe-blue-50: var(--pe-color-blue-50);
-  --color-pe-blue-100: var(--pe-color-blue-100);
-  --color-pe-blue-200: var(--pe-color-blue-200);
-  --color-pe-blue-300: var(--pe-color-blue-300);
-  --color-pe-blue-400: var(--pe-color-blue-400);
-  --color-pe-blue-500: var(--pe-color-blue-500);
-  --color-pe-blue-600: var(--pe-color-blue-600);
-  --color-pe-blue-700: var(--pe-color-blue-700);
-  --color-pe-blue-800: var(--pe-color-blue-800);
-  --color-pe-blue-900: var(--pe-color-blue-900);
-
-  /* Semantic colors */
-  --color-pe-success: var(--pe-color-success);
-  --color-pe-warning: var(--pe-color-warning);
-  --color-pe-error: var(--pe-color-error);
-  --color-pe-info: var(--pe-color-info);
-
-  /* Background colors */
-  --color-pe-bg-primary: var(--pe-color-bg-primary);
-  --color-pe-bg-secondary: var(--pe-color-bg-secondary);
-  --color-pe-bg-tertiary: var(--pe-color-bg-tertiary);
-
-  /* Text colors */
-  --color-pe-text-primary: var(--pe-color-text-primary);
-  --color-pe-text-secondary: var(--pe-color-text-secondary);
-  --color-pe-text-tertiary: var(--pe-color-text-tertiary);
-  --color-pe-text-inverse: var(--pe-color-text-inverse);
-
-  /* Border colors */
-  --color-pe-border-light: var(--pe-color-border-light);
-  --color-pe-border-medium: var(--pe-color-border-medium);
-  --color-pe-border-dark: var(--pe-color-border-dark);
-
-  /*
-   * =========================================================
-   * shadcn/ui semantic color tokens
-   * =========================================================
-   * Required by shadcn/ui components (Button, Badge, Dialog,
-   * etc.). These use classes like bg-primary, text-foreground,
-   * border-border. NOT pe-prefixed — shadcn expects these
-   * exact names.
-   * =========================================================
-   */
-
-  /* Core foreground/background */
-  --color-background: var(--pe-color-bg-primary);
-  --color-foreground: var(--pe-color-gray-900);
-
-  /* Primary action color (buttons, links, badges) */
-  --color-primary: var(--pe-color-primary-600);
-  --color-primary-foreground: var(--pe-color-text-inverse);
-
-  /* Secondary (muted buttons, secondary badges) */
-  --color-secondary: var(--pe-color-gray-100);
-  --color-secondary-foreground: var(--pe-color-gray-900);
-
-  /* Muted (subtle backgrounds, disabled states) */
-  --color-muted: var(--pe-color-gray-100);
-  --color-muted-foreground: var(--pe-color-gray-500);
-
-  /* Accent (hover highlights, active states) */
-  --color-accent: var(--pe-color-gray-100);
-  --color-accent-foreground: var(--pe-color-gray-900);
-
-  /* Destructive (delete buttons, error states) */
-  --color-destructive: var(--pe-color-error);
-
-  /* Popover/dropdown backgrounds */
-  --color-popover: var(--pe-color-bg-primary);
-  --color-popover-foreground: var(--pe-color-gray-900);
-
-  /* Card backgrounds */
-  --color-card: var(--pe-color-bg-primary);
-  --color-card-foreground: var(--pe-color-gray-900);
-
-  /* Border, input, ring (form controls) */
-  --color-border: var(--pe-color-border-light);
-  --color-input: var(--pe-color-border-light);
-  --color-ring: var(--pe-color-primary-500);
-
-  /* Typography */
-  --font-pe: var(--pe-font-family-primary);
-  --font-pe-mono: var(--pe-font-family-mono);
-
-  /* Override Tailwind's default font sizes with PE design system values.
-   * Tailwind v4 uses the --text-* namespace to generate text-* utilities.
-   * We clear all defaults and define only PE's scale (xs through 4xl).
-   * Use standard classes (text-xs, text-sm, text-base, etc.) in components. */
-  --text-*: initial;
-  --text-xs: var(--pe-font-size-xs);
-  --text-sm: var(--pe-font-size-sm);
-  --text-base: var(--pe-font-size-base);
-  --text-lg: var(--pe-font-size-lg);
-  --text-xl: var(--pe-font-size-xl);
-  --text-2xl: var(--pe-font-size-2xl);
-  --text-3xl: var(--pe-font-size-3xl);
-  --text-4xl: var(--pe-font-size-4xl);
-
-  /* Spacing */
-  --spacing-pe-xs: var(--pe-space-xs);
-  --spacing-pe-sm: var(--pe-space-sm);
-  --spacing-pe-md: var(--pe-space-md);
-  --spacing-pe-lg: var(--pe-space-lg);
-  --spacing-pe-xl: var(--pe-space-xl);
-  --spacing-pe-2xl: var(--pe-space-2xl);
-  --spacing-pe-3xl: var(--pe-space-3xl);
-  --spacing-pe-4xl: var(--pe-space-4xl);
-  --spacing-pe-5xl: var(--pe-space-5xl);
-
-  /* Border radius - semantic scale */
-  --radius-pe-chip: var(--pe-radius-chip);
-  --radius-pe-element: var(--pe-radius-element);
-  --radius-pe-container: var(--pe-radius-container);
-  --radius-pe-feature: var(--pe-radius-feature);
-
-  /* Border radius - size scale (aliases for convenience) */
-  --radius-pe-sm: var(--pe-radius-element);
-  --radius-pe-md: 6px;
-  --radius-pe-lg: var(--pe-radius-container);
-  --radius-pe-xl: var(--pe-radius-feature);
-
-  /* Breakpoints */
-  --breakpoint-xs: 36rem;
-  --breakpoint-sm: 48rem;
-  --breakpoint-md: 62rem;
-  --breakpoint-lg: 75rem;
-  --breakpoint-xl: 88rem;
-  --breakpoint-2xl: 96rem;
-
-  /* Layout spacing */
-  --spacing-pe-sidebar: 79px;
-  --spacing-pe-sidebar-width: 280px;
-  --spacing-pe-header: 58px;
-  --spacing-pe-content: 1361px;
-  --spacing-pe-container: 976px;
-}
-
-/*
- * =========================================================
- * Base styles
- * =========================================================
- * Tailwind Preflight resets all HTML elements to a blank
- * slate. These base styles restore sensible defaults.
- * =========================================================
- */
-@layer base {
-  /* Default border color */
-  *,
-  ::before,
-  ::after {
-    border-color: var(--color-border);
-  }
-
-  html {
-    font-family: var(--font-pe);
-    font-size: var(--text-base);
-    line-height: 1.55;
-    color: var(--color-foreground);
-    -webkit-font-smoothing: antialiased;
-    -moz-osx-font-smoothing: grayscale;
-  }
-
-  body {
-    font-family: var(--font-pe);
-    color: var(--color-foreground);
-    background-color: var(--color-background);
-  }
-
-  a {
-    color: inherit;
-    text-decoration: inherit;
-  }
-
-  table {
-    border-collapse: collapse;
-    width: 100%;
-  }
-
-  [data-slot='table-container'],
-  tr {
-    background-color: var(--color-pe-bg-primary);
-  }
-
-  th {
-    text-align: left;
-    font-weight: 600;
-  }
-
-  button,
-  input,
-  select,
-  textarea {
-    font-family: inherit;
-    font-size: inherit;
-    background-color: var(--color-pe-bg-primary);
-  }
-
-  input[type='number']::-webkit-inner-spin-button,
-  input[type='number']::-webkit-outer-spin-button {
-    -webkit-appearance: none;
-    margin: 0;
-  }
-
-  input[type='number'] {
-    -moz-appearance: textfield;
-  }
-}
diff --git a/src/charts/ChartContainer.tsx b/src/charts/ChartContainer.tsx
index 8def053..0c32e3c 100644
--- a/src/charts/ChartContainer.tsx
+++ b/src/charts/ChartContainer.tsx
@@ -24,25 +24,25 @@ export function ChartContainer({
   return (
     <div
       className={cn(
-        'bg-white border border-pe-border-light rounded-pe-container p-pe-lg',
+        'bg-card border border-border rounded-lg p-4',
         className,
       )}
       style={styles?.root}
       {...props}
     >
       {(title || actions) && (
-        <div className="flex items-start justify-between mb-pe-lg">
+        <div className="flex items-start justify-between mb-4">
           <div>
             {title && (
               <h3
-                className="text-base font-semibold text-pe-text-primary"
+                className="text-base font-semibold text-foreground"
                 style={styles?.title}
               >
                 {title}
               </h3>
             )}
             {subtitle && (
-              <p className="text-sm text-pe-text-secondary mt-0.5">
+              <p className="text-sm text-muted-foreground mt-0.5">
                 {subtitle}
               </p>
             )}
diff --git a/src/charts/PEAreaChart.tsx b/src/charts/PEAreaChart.tsx
index 09393d4..ea93b14 100644
--- a/src/charts/PEAreaChart.tsx
+++ b/src/charts/PEAreaChart.tsx
@@ -8,7 +8,6 @@ import {
   Legend,
   ResponsiveContainer,
 } from 'recharts';
-import { colors } from '../tokens/colors';
 import { AXIS_STYLE, GRID_STYLE, TOOLTIP_STYLE, LEGEND_STYLE, chartColors } from './chartDefaults';
 import { cn } from '../utils/cn';
 
@@ -59,13 +58,13 @@ export function PEAreaChart({
             dataKey={xKey}
             tick={AXIS_STYLE}
             tickLine={false}
-            axisLine={{ stroke: colors.border.light }}
+            axisLine={{ stroke: 'var(--border)' }}
             label={xLabel ? { value: xLabel, position: 'insideBottom', offset: -5, style: AXIS_STYLE } : undefined}
           />
           <YAxis
             tick={AXIS_STYLE}
             tickLine={false}
-            axisLine={{ stroke: colors.border.light }}
+            axisLine={{ stroke: 'var(--border)' }}
             label={yLabel ? { value: yLabel, angle: -90, position: 'insideLeft', offset: 10, style: AXIS_STYLE } : undefined}
           />
           <Tooltip
diff --git a/src/charts/PEBarChart.tsx b/src/charts/PEBarChart.tsx
index 5bdb260..84f2e7a 100644
--- a/src/charts/PEBarChart.tsx
+++ b/src/charts/PEBarChart.tsx
@@ -9,7 +9,6 @@ import {
   ResponsiveContainer,
   Cell,
 } from 'recharts';
-import { colors } from '../tokens/colors';
 import { AXIS_STYLE, GRID_STYLE, TOOLTIP_STYLE, LEGEND_STYLE, chartColors } from './chartDefaults';
 import { cn } from '../utils/cn';
 
@@ -39,7 +38,7 @@ export function PEBarChart({
   height = 400,
   colorByValue = false,
   positiveColor = chartColors.primary,
-  negativeColor = colors.gray[600],
+  negativeColor = 'var(--color-gray-600)',
   fillColor = chartColors.primary,
   showGrid = true,
   showLegend = false,
@@ -59,13 +58,13 @@ export function PEBarChart({
             dataKey={xKey}
             tick={AXIS_STYLE}
             tickLine={false}
-            axisLine={{ stroke: colors.border.light }}
+            axisLine={{ stroke: 'var(--border)' }}
             label={xLabel ? { value: xLabel, position: 'insideBottom', offset: -5, style: AXIS_STYLE } : undefined}
           />
           <YAxis
             tick={AXIS_STYLE}
             tickLine={false}
-            axisLine={{ stroke: colors.border.light }}
+            axisLine={{ stroke: 'var(--border)' }}
             label={yLabel ? { value: yLabel, angle: -90, position: 'insideLeft', offset: 10, style: AXIS_STYLE } : undefined}
           />
           <Tooltip
diff --git a/src/charts/PELineChart.tsx b/src/charts/PELineChart.tsx
index 6a3dc9b..2bea3c4 100644
--- a/src/charts/PELineChart.tsx
+++ b/src/charts/PELineChart.tsx
@@ -8,7 +8,6 @@ import {
   Legend,
   ResponsiveContainer,
 } from 'recharts';
-import { colors } from '../tokens/colors';
 import { AXIS_STYLE, GRID_STYLE, TOOLTIP_STYLE, LEGEND_STYLE, chartColors } from './chartDefaults';
 import { cn } from '../utils/cn';
 
@@ -57,13 +56,13 @@ export function PELineChart({
             dataKey={xKey}
             tick={AXIS_STYLE}
             tickLine={false}
-            axisLine={{ stroke: colors.border.light }}
+            axisLine={{ stroke: 'var(--border)' }}
             label={xLabel ? { value: xLabel, position: 'insideBottom', offset: -5, style: AXIS_STYLE } : undefined}
           />
           <YAxis
             tick={AXIS_STYLE}
             tickLine={false}
-            axisLine={{ stroke: colors.border.light }}
+            axisLine={{ stroke: 'var(--border)' }}
             label={yLabel ? { value: yLabel, angle: -90, position: 'insideLeft', offset: 10, style: AXIS_STYLE } : undefined}
           />
           <Tooltip
diff --git a/src/charts/PEWaterfallChart.tsx b/src/charts/PEWaterfallChart.tsx
index 411b41a..89b45d9 100644
--- a/src/charts/PEWaterfallChart.tsx
+++ b/src/charts/PEWaterfallChart.tsx
@@ -8,7 +8,6 @@ import {
   ResponsiveContainer,
   Cell,
 } from 'recharts';
-import { colors } from '../tokens/colors';
 import { AXIS_STYLE, GRID_STYLE, TOOLTIP_STYLE, chartColors } from './chartDefaults';
 import { cn } from '../utils/cn';
 
@@ -75,8 +74,8 @@ export function PEWaterfallChart({
   data,
   height = 400,
   positiveColor = chartColors.primary,
-  negativeColor = colors.gray[600],
-  totalColor = colors.primary[700],
+  negativeColor = 'var(--gray-600)',
+  totalColor = 'var(--chart-3)',
   showGrid = true,
   formatTooltip,
   className,
@@ -94,12 +93,12 @@ export function PEWaterfallChart({
             dataKey="name"
             tick={AXIS_STYLE}
             tickLine={false}
-            axisLine={{ stroke: colors.border.light }}
+            axisLine={{ stroke: 'var(--border)' }}
           />
           <YAxis
             tick={AXIS_STYLE}
             tickLine={false}
-            axisLine={{ stroke: colors.border.light }}
+            axisLine={{ stroke: 'var(--border)' }}
           />
           <Tooltip
             {...TOOLTIP_STYLE}
diff --git a/src/charts/chartDefaults.ts b/src/charts/chartDefaults.ts
index 46bd9e4..5b1f644 100644
--- a/src/charts/chartDefaults.ts
+++ b/src/charts/chartDefaults.ts
@@ -1,46 +1,57 @@
-import { colors } from '../tokens/colors';
-import { typography } from '../tokens/typography';
-import { chartColors } from '../tokens/charts';
-
 export const AXIS_STYLE = {
-  fontFamily: typography.fontFamily.primary,
+  fontFamily: 'var(--font-sans)',
   fontSize: 12,
-  fill: colors.text.secondary,
+  fill: 'var(--muted-foreground)',
 };
 
 export const GRID_STYLE = {
-  stroke: colors.border.light,
+  stroke: 'var(--border)',
   strokeDasharray: '3 3',
 };
 
 export const TOOLTIP_STYLE = {
   contentStyle: {
-    fontFamily: typography.fontFamily.primary,
+    fontFamily: 'var(--font-sans)',
     fontSize: 13,
-    backgroundColor: colors.white,
-    border: `1px solid ${colors.border.light}`,
+    backgroundColor: 'var(--background)',
+    border: '1px solid var(--border)',
     borderRadius: '8px',
-    boxShadow: `0 4px 12px ${colors.shadow.medium}`,
+    boxShadow: '0 4px 12px rgba(16, 24, 40, 0.1)',
     padding: '8px 12px',
   },
   labelStyle: {
     fontWeight: 600,
     marginBottom: 4,
-    color: colors.text.primary,
+    color: 'var(--foreground)',
   },
   itemStyle: {
-    color: colors.text.secondary,
+    color: 'var(--muted-foreground)',
     padding: '2px 0',
   },
 };
 
 export const LEGEND_STYLE = {
   wrapperStyle: {
-    fontFamily: typography.fontFamily.primary,
+    fontFamily: 'var(--font-sans)',
     fontSize: 13,
-    color: colors.text.secondary,
+    color: 'var(--muted-foreground)',
     paddingTop: 8,
   },
 };
 
-export { chartColors };
+export const chartColors = {
+  primary: 'var(--chart-1)',
+  secondary: 'var(--chart-2)',
+  tertiary: 'var(--chart-3)',
+  quaternary: 'var(--chart-4)',
+  quinary: 'var(--chart-5)',
+  positive: 'var(--success)',
+  negative: 'var(--destructive)',
+  series: [
+    'var(--chart-1)',
+    'var(--chart-2)',
+    'var(--chart-3)',
+    'var(--chart-4)',
+    'var(--chart-5)',
+  ],
+} as const;
diff --git a/src/display/DataTable.tsx b/src/display/DataTable.tsx
index f53a763..7ac05cc 100644
--- a/src/display/DataTable.tsx
+++ b/src/display/DataTable.tsx
@@ -31,7 +31,7 @@ export function DataTable<T extends Record<string, unknown>>({
   return (
     <div
       className={cn(
-        'bg-white border border-pe-border-light rounded-pe-container overflow-hidden',
+        'bg-card border border-border rounded-lg overflow-hidden',
         className,
       )}
       style={styles?.root}
@@ -39,12 +39,12 @@ export function DataTable<T extends Record<string, unknown>>({
     >
       <table className="w-full" style={styles?.table}>
         <thead>
-          <tr className="border-b border-pe-border-light bg-pe-gray-50">
+          <tr className="border-b border-border bg-gray-50">
             {columns.map((col) => (
               <th
                 key={col.key}
                 className={cn(
-                  'px-4 py-3 text-xs font-semibold uppercase tracking-wider text-pe-text-secondary',
+                  'px-4 py-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground',
                   col.align === 'right' && 'text-right',
                   col.align === 'center' && 'text-center',
                 )}
@@ -59,14 +59,14 @@ export function DataTable<T extends Record<string, unknown>>({
           {data.map((row, i) => (
             <tr
               key={i}
-              className="border-b border-pe-border-light last:border-b-0 hover:bg-pe-gray-50"
+              className="border-b border-border last:border-b-0 hover:bg-gray-50"
               style={styles?.row}
             >
               {columns.map((col) => (
                 <td
                   key={col.key}
                   className={cn(
-                    'px-4 py-3 text-sm text-pe-text-primary',
+                    'px-4 py-3 text-sm text-foreground',
                     col.align === 'right' && 'text-right',
                     col.align === 'center' && 'text-center',
                   )}
diff --git a/src/display/MetricCard.tsx b/src/display/MetricCard.tsx
index f9e8054..727a611 100644
--- a/src/display/MetricCard.tsx
+++ b/src/display/MetricCard.tsx
@@ -1,6 +1,6 @@
 import { type HTMLAttributes } from 'react';
 import { cn } from '../utils/cn';
-import { formatCurrency, formatPercent, formatNumber } from '../tokens/charts';
+import { formatCurrency, formatPercent, formatNumber } from '../utils/formatters';
 
 export type MetricFormat = 'currency' | 'percent' | 'number' | 'string';
 export type MetricTrend = 'positive' | 'negative' | 'neutral';
@@ -45,20 +45,20 @@ export function MetricCard({
   return (
     <div
       className={cn(
-        'bg-white border border-pe-border-light rounded-pe-container p-pe-lg flex flex-col gap-pe-xs',
+        'bg-card border border-border rounded-lg p-4 flex flex-col gap-1',
         className,
       )}
       style={styles?.root}
       {...props}
     >
       <span
-        className="text-sm text-pe-text-secondary font-medium"
+        className="text-sm text-muted-foreground font-medium"
         style={styles?.label}
       >
         {label}
       </span>
       <span
-        className="text-2xl font-bold text-pe-text-primary"
+        className="text-2xl font-bold text-foreground"
         style={styles?.value}
       >
         {typeof value === 'number' ? formatByType(value, format) : value}
@@ -67,9 +67,9 @@ export function MetricCard({
         <span
           className={cn(
             'text-sm font-medium',
-            trend === 'positive' && 'text-pe-primary-500',
-            trend === 'negative' && 'text-pe-error',
-            trend === 'neutral' && 'text-pe-gray-500',
+            trend === 'positive' && 'text-teal-500',
+            trend === 'negative' && 'text-destructive',
+            trend === 'neutral' && 'text-gray-500',
           )}
           style={styles?.trend}
         >
diff --git a/src/display/PolicyEngineWatermark.tsx b/src/display/PolicyEngineWatermark.tsx
index f98d8c3..28b91f7 100644
--- a/src/display/PolicyEngineWatermark.tsx
+++ b/src/display/PolicyEngineWatermark.tsx
@@ -24,7 +24,7 @@ export function PolicyEngineWatermark({
       {logoSrc && (
         <img src={logoSrc} alt="PolicyEngine" className="h-4 w-4" />
       )}
-      <span className="text-xs text-pe-text-tertiary">PolicyEngine</span>
+      <span className="text-xs text-gray-400">PolicyEngine</span>
     </div>
   );
 }
diff --git a/src/display/SummaryText.tsx b/src/display/SummaryText.tsx
index 1f21ee5..1d12579 100644
--- a/src/display/SummaryText.tsx
+++ b/src/display/SummaryText.tsx
@@ -10,7 +10,7 @@ export function SummaryText({ className, styles, children, ...props }: SummaryTe
   return (
     <div
       className={cn(
-        'text-base leading-relaxed text-pe-text-primary bg-white border border-pe-border-light rounded-pe-container p-pe-lg',
+        'text-base leading-relaxed text-foreground bg-card border border-border rounded-lg p-4',
         className,
       )}
       style={styles?.root}
diff --git a/src/index.ts b/src/index.ts
index 1135a2f..3a2e278 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,8 +1,5 @@
 // Styles — consumers must import '@policyengine/ui-kit/styles.css' separately
-import './app.css';
-
-// Design tokens
-export * from './tokens';
+import './theme/tokens.css';
 
 // Utilities
 export * from './utils';
diff --git a/src/inputs/CheckboxInput.tsx b/src/inputs/CheckboxInput.tsx
index 336e2cb..8c85c54 100644
--- a/src/inputs/CheckboxInput.tsx
+++ b/src/inputs/CheckboxInput.tsx
@@ -24,11 +24,11 @@ export const CheckboxInput = forwardRef<HTMLInputElement, CheckboxInputProps>(
         type="checkbox"
         checked={checked}
         onChange={(e) => onChange(e.target.checked)}
-        className="h-4 w-4 rounded border border-pe-border-light accent-primary focus:ring-2 focus:ring-ring cursor-pointer"
+        className="h-4 w-4 rounded border border-border accent-primary focus:ring-2 focus:ring-ring cursor-pointer"
         style={styles?.input}
         {...props}
       />
-      <span className="text-sm text-pe-text-primary" style={styles?.label}>
+      <span className="text-sm text-foreground" style={styles?.label}>
         {label}
       </span>
     </label>
diff --git a/src/inputs/CurrencyInput.tsx b/src/inputs/CurrencyInput.tsx
index 8d452ab..aa24695 100644
--- a/src/inputs/CurrencyInput.tsx
+++ b/src/inputs/CurrencyInput.tsx
@@ -34,12 +34,12 @@ export const CurrencyInput = forwardRef<HTMLInputElement, CurrencyInputProps>(
     return (
       <div className={cn('flex flex-col gap-1', className)} style={styles?.root}>
         {label && (
-          <label className="text-sm font-medium text-pe-text-secondary" style={styles?.label}>
+          <label className="text-sm font-medium text-muted-foreground" style={styles?.label}>
             {label}
           </label>
         )}
         <div className="relative">
-          <span className="absolute left-3 top-1/2 -translate-y-1/2 text-sm text-pe-text-secondary">
+          <span className="absolute left-3 top-1/2 -translate-y-1/2 text-sm text-muted-foreground">
             {currencySymbol}
           </span>
           <input
@@ -58,7 +58,7 @@ export const CurrencyInput = forwardRef<HTMLInputElement, CurrencyInputProps>(
             onChange={(e) => {
               setRawText(e.target.value);
             }}
-            className="h-10 w-full rounded-pe-element border border-pe-border-light pl-7 pr-3 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:border-primary"
+            className="h-10 w-full rounded-sm border border-border pl-7 pr-3 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:border-primary"
             style={styles?.input}
             {...props}
           />
diff --git a/src/inputs/InputGroup.tsx b/src/inputs/InputGroup.tsx
index 950b44e..9b4f226 100644
--- a/src/inputs/InputGroup.tsx
+++ b/src/inputs/InputGroup.tsx
@@ -13,17 +13,17 @@ export const InputGroup = forwardRef<HTMLDivElement, InputGroupProps>(
   ({ label, className, styles, children, ...props }, ref) => (
     <div
       ref={ref}
-      className={cn('flex flex-col gap-pe-md', className)}
+      className={cn('flex flex-col gap-3', className)}
       style={styles?.root}
       {...props}
     >
       <h3
-        className="text-xs font-semibold uppercase tracking-wider text-pe-text-secondary"
+        className="text-xs font-semibold uppercase tracking-wider text-muted-foreground"
         style={styles?.label}
       >
         {label}
       </h3>
-      <div className="flex flex-col gap-pe-sm">{children}</div>
+      <div className="flex flex-col gap-2">{children}</div>
     </div>
   ),
 );
diff --git a/src/inputs/NumberInput.tsx b/src/inputs/NumberInput.tsx
index 2a1855a..1253ac5 100644
--- a/src/inputs/NumberInput.tsx
+++ b/src/inputs/NumberInput.tsx
@@ -20,7 +20,7 @@ export const NumberInput = forwardRef<HTMLInputElement, NumberInputProps>(
   ({ label, value, onChange, min, max, step = 1, className, styles, ...props }, ref) => (
     <div className={cn('flex flex-col gap-1', className)} style={styles?.root}>
       {label && (
-        <label className="text-sm font-medium text-pe-text-secondary" style={styles?.label}>
+        <label className="text-sm font-medium text-muted-foreground" style={styles?.label}>
           {label}
         </label>
       )}
@@ -32,7 +32,7 @@ export const NumberInput = forwardRef<HTMLInputElement, NumberInputProps>(
         min={min}
         max={max}
         step={step}
-        className="h-10 w-full rounded-pe-element border border-pe-border-light px-3 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:border-primary"
+        className="h-10 w-full rounded-sm border border-border px-3 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:border-primary"
         style={styles?.input}
         {...props}
       />
diff --git a/src/inputs/SelectInput.tsx b/src/inputs/SelectInput.tsx
index c43a7ef..e6b5772 100644
--- a/src/inputs/SelectInput.tsx
+++ b/src/inputs/SelectInput.tsx
@@ -24,7 +24,7 @@ export const SelectInput = forwardRef<HTMLSelectElement, SelectInputProps>(
   ({ label, options, value, onChange, placeholder, className, styles, ...props }, ref) => (
     <div className={cn('flex flex-col gap-1', className)} style={styles?.root}>
       {label && (
-        <label className="text-sm font-medium text-pe-text-secondary" style={styles?.label}>
+        <label className="text-sm font-medium text-muted-foreground" style={styles?.label}>
           {label}
         </label>
       )}
@@ -32,7 +32,7 @@ export const SelectInput = forwardRef<HTMLSelectElement, SelectInputProps>(
         ref={ref}
         value={value}
         onChange={(e) => onChange(e.target.value)}
-        className="h-10 w-full rounded-pe-element border border-pe-border-light px-3 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:border-primary appearance-none bg-white"
+        className="h-10 w-full rounded-sm border border-border px-3 text-sm transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:border-primary appearance-none bg-background"
         style={styles?.select}
         {...props}
       >
diff --git a/src/inputs/SliderInput.tsx b/src/inputs/SliderInput.tsx
index 6ea35c8..99ea176 100644
--- a/src/inputs/SliderInput.tsx
+++ b/src/inputs/SliderInput.tsx
@@ -23,10 +23,10 @@ export const SliderInput = forwardRef<HTMLInputElement, SliderInputProps>(
     <div className={cn('flex flex-col gap-1', className)} style={styles?.root}>
       {label && (
         <div className="flex items-center justify-between">
-          <label className="text-sm font-medium text-pe-text-secondary" style={styles?.label}>
+          <label className="text-sm font-medium text-muted-foreground" style={styles?.label}>
             {label}
           </label>
-          <span className="text-sm font-medium text-pe-text-primary" style={styles?.value}>
+          <span className="text-sm font-medium text-foreground" style={styles?.value}>
             {formatValue ? formatValue(value) : value}
           </span>
         </div>
diff --git a/src/layout/DashboardShell.tsx b/src/layout/DashboardShell.tsx
index f64ba10..b9670fb 100644
--- a/src/layout/DashboardShell.tsx
+++ b/src/layout/DashboardShell.tsx
@@ -10,7 +10,7 @@ export const DashboardShell = forwardRef<HTMLDivElement, DashboardShellProps>(
     <div
       ref={ref}
       className={cn(
-        'min-h-screen bg-pe-bg-secondary font-sans text-pe-text-primary',
+        'min-h-screen bg-muted font-sans text-foreground',
         className,
       )}
       style={styles?.root}
diff --git a/src/layout/Header.tsx b/src/layout/Header.tsx
index 1dac139..88cd99f 100644
--- a/src/layout/Header.tsx
+++ b/src/layout/Header.tsx
@@ -3,12 +3,12 @@ import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
 import { cn } from '../utils/cn';
 
 const headerVariants = cva(
-  'flex items-center justify-between h-[58px] px-pe-2xl',
+  'flex items-center justify-between h-[58px] px-6',
   {
     variants: {
       variant: {
-        light: 'bg-white border-b border-pe-border-light',
-        dark: 'bg-pe-primary-600 text-white shadow-md border-b border-pe-border-dark',
+        light: 'bg-background border-b border-border',
+        dark: 'bg-teal-600 text-white shadow-md border-b border-gray-400',
       },
     },
     defaultVariants: { variant: 'light' },
@@ -16,12 +16,12 @@ const headerVariants = cva(
 );
 
 const actionsVariants = cva(
-  'flex items-center gap-pe-3xl',
+  'flex items-center gap-8',
   {
     variants: {
       variant: {
         light:
-          '[&_a]:text-pe-text-secondary [&_a]:text-lg [&_a]:font-medium [&_a]:no-underline [&_a]:hover:text-pe-text-primary',
+          '[&_a]:text-muted-foreground [&_a]:text-lg [&_a]:font-medium [&_a]:no-underline [&_a]:hover:text-foreground',
         dark:
           '[&_a]:text-white [&_a]:text-lg [&_a]:font-medium [&_a]:no-underline [&_a]:hover:opacity-80',
       },
@@ -31,11 +31,11 @@ const actionsVariants = cva(
 );
 
 const subtitleVariants = cva(
-  'flex items-center gap-pe-md',
+  'flex items-center gap-3',
   {
     variants: {
       variant: {
-        light: '[&>span]:text-pe-text-secondary [&>span]:text-lg [&>span]:font-medium',
+        light: '[&>span]:text-muted-foreground [&>span]:text-lg [&>span]:font-medium',
         dark: '[&>span]:text-white/70 [&>span]:text-lg [&>span]:font-medium',
       },
     },
diff --git a/src/layout/InputPanel.tsx b/src/layout/InputPanel.tsx
index 6fcb137..89601ff 100644
--- a/src/layout/InputPanel.tsx
+++ b/src/layout/InputPanel.tsx
@@ -10,13 +10,13 @@ export const InputPanel = forwardRef<HTMLDivElement, InputPanelProps>(
   ({ title, className, styles, children, ...props }, ref) => (
     <div
       ref={ref}
-      className={cn('flex flex-col gap-pe-lg p-pe-lg', className)}
+      className={cn('flex flex-col gap-4 p-4', className)}
       style={styles?.root}
       {...props}
     >
       {title && (
         <h2
-          className="text-lg font-semibold text-pe-text-primary"
+          className="text-lg font-semibold text-foreground"
           style={styles?.title}
         >
           {title}
diff --git a/src/layout/ResultsPanel.tsx b/src/layout/ResultsPanel.tsx
index 5466b43..edb3ff1 100644
--- a/src/layout/ResultsPanel.tsx
+++ b/src/layout/ResultsPanel.tsx
@@ -10,7 +10,7 @@ export const ResultsPanel = forwardRef<HTMLDivElement, ResultsPanelProps>(
     <div
       ref={ref}
       className={cn(
-        'flex flex-col gap-pe-2xl p-pe-2xl',
+        'flex flex-col gap-6 p-6',
         className,
       )}
       style={styles?.root}
diff --git a/src/layout/SidebarLayout.tsx b/src/layout/SidebarLayout.tsx
index 2a5129d..1e854b2 100644
--- a/src/layout/SidebarLayout.tsx
+++ b/src/layout/SidebarLayout.tsx
@@ -20,7 +20,7 @@ export const SidebarLayout = forwardRef<HTMLDivElement, SidebarLayoutProps>(
       {...props}
     >
       <aside
-        className="w-full md:flex-shrink-0 border-r border-pe-border-light bg-white overflow-y-auto"
+        className="w-full md:flex-shrink-0 border-r border-border bg-background overflow-y-auto"
         style={{ ...styles?.sidebar, maxWidth: sidebarWidth }}
       >
         {sidebar}
diff --git a/src/layout/SingleColumnLayout.tsx b/src/layout/SingleColumnLayout.tsx
index 545fa65..68a72b8 100644
--- a/src/layout/SingleColumnLayout.tsx
+++ b/src/layout/SingleColumnLayout.tsx
@@ -10,12 +10,12 @@ export const SingleColumnLayout = forwardRef<HTMLDivElement, SingleColumnLayoutP
   ({ maxWidth = '976px', className, styles, children, ...props }, ref) => (
     <div
       ref={ref}
-      className={cn('min-h-screen bg-pe-bg-secondary', className)}
+      className={cn('min-h-screen bg-muted', className)}
       style={styles?.root}
       {...props}
     >
       <div
-        className="mx-auto px-pe-lg py-pe-2xl"
+        className="mx-auto px-4 py-6"
         style={{ maxWidth, ...styles?.content }}
       >
         {children}
diff --git a/src/primitives/Badge.tsx b/src/primitives/Badge.tsx
index 539e4f4..6e62796 100644
--- a/src/primitives/Badge.tsx
+++ b/src/primitives/Badge.tsx
@@ -3,13 +3,13 @@ import { type HTMLAttributes } from 'react';
 import { cn } from '../utils/cn';
 
 const badgeVariants = cva(
-  'inline-flex items-center rounded-pe-chip px-3 py-1 text-xs font-medium transition-colors',
+  'inline-flex items-center rounded-sm px-3 py-1 text-xs font-medium transition-colors',
   {
     variants: {
       variant: {
         default: 'bg-primary text-primary-foreground',
         secondary: 'bg-secondary text-secondary-foreground',
-        outline: 'border border-pe-border-light text-pe-text-primary',
+        outline: 'border border-border text-foreground',
         success: 'bg-green-100 text-green-800',
         warning: 'bg-yellow-100 text-yellow-800',
         error: 'bg-red-100 text-red-800',
diff --git a/src/primitives/Button.tsx b/src/primitives/Button.tsx
index 94b6e92..f0dc1dd 100644
--- a/src/primitives/Button.tsx
+++ b/src/primitives/Button.tsx
@@ -3,16 +3,16 @@ import { forwardRef, type ButtonHTMLAttributes } from 'react';
 import { cn } from '../utils/cn';
 
 const buttonVariants = cva(
-  'inline-flex items-center justify-center gap-2 rounded-pe-element text-sm font-medium transition-colors cursor-pointer disabled:pointer-events-none disabled:opacity-50',
+  'inline-flex items-center justify-center gap-2 rounded-sm text-sm font-medium transition-colors cursor-pointer disabled:pointer-events-none disabled:opacity-50',
   {
     variants: {
       variant: {
         default:
-          'bg-primary text-primary-foreground hover:bg-pe-primary-600',
+          'bg-primary text-primary-foreground hover:bg-teal-600',
         outline:
-          'border border-pe-border-light bg-white hover:bg-pe-gray-50',
-        ghost: 'hover:bg-pe-gray-100',
-        destructive: 'bg-pe-error text-white hover:bg-red-600',
+          'border border-border bg-background hover:bg-gray-50',
+        ghost: 'hover:bg-gray-100',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-red-600',
       },
       size: {
         default: 'h-9 px-4 py-2',
diff --git a/src/primitives/Card.tsx b/src/primitives/Card.tsx
index b7925cd..f4f1752 100644
--- a/src/primitives/Card.tsx
+++ b/src/primitives/Card.tsx
@@ -10,7 +10,7 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(
     <div
       ref={ref}
       className={cn(
-        'bg-white border border-pe-border-light rounded-pe-container shadow-sm',
+        'bg-card border border-border rounded-lg shadow-sm',
         className,
       )}
       style={styles?.root}
@@ -26,7 +26,7 @@ export const CardHeader = forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('flex flex-col gap-1.5 p-pe-lg', className)}
+    className={cn('flex flex-col gap-1.5 p-4', className)}
     {...props}
   />
 ));
@@ -38,7 +38,7 @@ export const CardTitle = forwardRef<
 >(({ className, ...props }, ref) => (
   <h3
     ref={ref}
-    className={cn('text-lg font-semibold text-pe-text-primary', className)}
+    className={cn('text-lg font-semibold text-foreground', className)}
     {...props}
   />
 ));
@@ -50,7 +50,7 @@ export const CardDescription = forwardRef<
 >(({ className, ...props }, ref) => (
   <p
     ref={ref}
-    className={cn('text-sm text-pe-text-secondary', className)}
+    className={cn('text-sm text-muted-foreground', className)}
     {...props}
   />
 ));
@@ -62,7 +62,7 @@ export const CardContent = forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('p-pe-lg pt-0', className)}
+    className={cn('p-4 pt-0', className)}
     {...props}
   />
 ));
@@ -74,7 +74,7 @@ export const CardFooter = forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('flex items-center p-pe-lg pt-0', className)}
+    className={cn('flex items-center p-4 pt-0', className)}
     {...props}
   />
 ));
diff --git a/src/primitives/Tabs.tsx b/src/primitives/Tabs.tsx
index bf2168e..852d701 100644
--- a/src/primitives/Tabs.tsx
+++ b/src/primitives/Tabs.tsx
@@ -4,7 +4,6 @@ import {
   useContext,
   useState,
   type HTMLAttributes,
-  type ReactNode,
 } from 'react';
 import { cn } from '../utils/cn';
 
@@ -56,7 +55,7 @@ export const TabsList = forwardRef<HTMLDivElement, TabsListProps>(
       ref={ref}
       role="tablist"
       className={cn(
-        'inline-flex items-center gap-1 border-b border-pe-border-light',
+        'inline-flex items-center gap-1 border-b border-border',
         className,
       )}
       {...props}
@@ -86,7 +85,7 @@ export const TabsTrigger = forwardRef<HTMLButtonElement, TabsTriggerProps>(
           'border-b-2 -mb-px',
           isActive
             ? 'border-primary text-primary'
-            : 'border-transparent text-pe-text-secondary hover:text-pe-text-primary',
+            : 'border-transparent text-muted-foreground hover:text-foreground',
           className,
         )}
         onClick={() => setActiveTab(value)}
diff --git a/src/theme/index.ts b/src/theme/index.ts
new file mode 100644
index 0000000..429cc4c
--- /dev/null
+++ b/src/theme/index.ts
@@ -0,0 +1,2 @@
+// Re-export the CSS theme for programmatic import
+import './tokens.css';
diff --git a/src/theme/tokens.css b/src/theme/tokens.css
new file mode 100644
index 0000000..b500bda
--- /dev/null
+++ b/src/theme/tokens.css
@@ -0,0 +1,230 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+/* ============================================================
+ * PolicyEngine Design Tokens
+ * Source: @policyengine/design-system v0.3.0 (npm)
+ *
+ * This file IS the design system for all frontend projects.
+ * Import it: @import "@policyengine/ui-kit/theme.css";
+ * ============================================================ */
+
+/* --- Layer 1: Raw token values (shadcn/ui semantic variables) --- */
+:root {
+  --radius: 6px;
+
+  /* Page */
+  --background: #FFFFFF;
+  --foreground: #000000;
+
+  /* Primary (teal brand) */
+  --primary: #2C7A7B;
+  --primary-foreground: #FFFFFF;
+
+  /* Secondary */
+  --secondary: #F2F4F7;
+  --secondary-foreground: #101828;
+
+  /* Muted */
+  --muted: #F2F4F7;
+  --muted-foreground: #6B7280;
+
+  /* Accent */
+  --accent: #F2F4F7;
+  --accent-foreground: #101828;
+
+  /* Destructive */
+  --destructive: #EF4444;
+  --destructive-foreground: #FFFFFF;
+
+  /* Chrome */
+  --border: #E2E8F0;
+  --input: #E2E8F0;
+  --ring: #319795;
+
+  /* Card */
+  --card: #FFFFFF;
+  --card-foreground: #000000;
+
+  /* Popover */
+  --popover: #FFFFFF;
+  --popover-foreground: #000000;
+
+  /* Charts (shadcn chart-1 through chart-5) */
+  --chart-1: #319795;
+  --chart-2: #0EA5E9;
+  --chart-3: #285E61;
+  --chart-4: #026AA2;
+  --chart-5: #6B7280;
+}
+
+/* --- Layer 2: Tailwind @theme inline (bridges :root vars to Tailwind utilities) --- */
+@theme inline {
+  /* Semantic colors → Tailwind classes (bg-primary, text-foreground, etc.) */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+
+  /* Radius derived from base --radius */
+  --radius-sm: calc(var(--radius) - 2px);
+  --radius-md: var(--radius);
+  --radius-lg: calc(var(--radius) + 2px);
+  --radius-xl: calc(var(--radius) + 6px);
+}
+
+/* --- Layer 3: Brand palette (direct Tailwind classes like bg-teal-500) --- */
+@theme {
+  /* Teal (primary brand) */
+  --color-teal-50: #E6FFFA;
+  --color-teal-100: #B2F5EA;
+  --color-teal-200: #81E6D9;
+  --color-teal-300: #4FD1C5;
+  --color-teal-400: #38B2AC;
+  --color-teal-500: #319795;
+  --color-teal-600: #2C7A7B;
+  --color-teal-700: #285E61;
+  --color-teal-800: #234E52;
+  --color-teal-900: #1D4044;
+
+  /* Gray */
+  --color-gray-50: #F9FAFB;
+  --color-gray-100: #F2F4F7;
+  --color-gray-200: #E2E8F0;
+  --color-gray-300: #D1D5DB;
+  --color-gray-400: #9CA3AF;
+  --color-gray-500: #6B7280;
+  --color-gray-600: #4B5563;
+  --color-gray-700: #344054;
+  --color-gray-800: #1F2937;
+  --color-gray-900: #101828;
+
+  /* Blue (accent) */
+  --color-blue-50: #F0F9FF;
+  --color-blue-100: #E0F2FE;
+  --color-blue-200: #BAE6FD;
+  --color-blue-300: #7DD3FC;
+  --color-blue-400: #38BDF8;
+  --color-blue-500: #0EA5E9;
+  --color-blue-600: #0284C7;
+  --color-blue-700: #026AA2;
+  --color-blue-800: #075985;
+  --color-blue-900: #0C4A6E;
+
+  /* Semantic */
+  --color-success: #22C55E;
+  --color-warning: #FEC601;
+  --color-error: #EF4444;
+  --color-info: #1890FF;
+
+  /* Font families */
+  --font-sans: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  --font-mono: JetBrains Mono, "Fira Code", Consolas, monospace;
+
+  /* Font sizes (overrides Tailwind defaults with PE scale) */
+  --text-*: initial;
+  --text-xs: 12px;
+  --text-xs--line-height: 16px;
+  --text-sm: 14px;
+  --text-sm--line-height: 20px;
+  --text-base: 16px;
+  --text-base--line-height: 24px;
+  --text-lg: 18px;
+  --text-lg--line-height: 28px;
+  --text-xl: 20px;
+  --text-xl--line-height: 28px;
+  --text-2xl: 24px;
+  --text-2xl--line-height: 32px;
+  --text-3xl: 28px;
+  --text-3xl--line-height: 36px;
+  --text-4xl: 32px;
+  --text-4xl--line-height: 40px;
+
+  /* Named spacing */
+  --spacing-header: 58px;
+  --spacing-sidebar: 280px;
+  --spacing-content: 976px;
+
+  /* Breakpoints */
+  --breakpoint-xs: 36rem;
+  --breakpoint-sm: 48rem;
+  --breakpoint-md: 62rem;
+  --breakpoint-lg: 75rem;
+  --breakpoint-xl: 88rem;
+  --breakpoint-2xl: 96rem;
+}
+
+/* --- Base styles --- */
+@layer base {
+  * {
+    @apply border-border;
+  }
+  html {
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-family: var(--font-sans);
+    line-height: 1.55;
+  }
+
+  /* Range input (slider) */
+  input[type="range"] {
+    -webkit-appearance: none;
+    appearance: none;
+    background: transparent;
+    height: 6px;
+  }
+  input[type="range"]::-webkit-slider-runnable-track {
+    background: var(--border);
+    height: 6px;
+    border-radius: 3px;
+  }
+  input[type="range"]::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 18px;
+    height: 18px;
+    border-radius: 50%;
+    background: var(--primary);
+    cursor: pointer;
+    margin-top: -6px;
+  }
+  input[type="range"]::-moz-range-track {
+    background: var(--border);
+    height: 6px;
+    border-radius: 3px;
+  }
+  input[type="range"]::-moz-range-thumb {
+    width: 18px;
+    height: 18px;
+    border-radius: 50%;
+    background: var(--primary);
+    border: none;
+    cursor: pointer;
+  }
+}
diff --git a/src/tokens/charts.ts b/src/tokens/charts.ts
deleted file mode 100644
index f3c9603..0000000
--- a/src/tokens/charts.ts
+++ /dev/null
@@ -1,212 +0,0 @@
-/**
- * PolicyEngine Chart Utilities
- * Shared chart formatting and colors
- */
-
-import { colors, TEAL_PRIMARY } from './colors';
-import { typography } from './typography';
-
-/**
- * Standard chart colors for PolicyEngine visualizations
- */
-export const chartColors = {
-  primary: TEAL_PRIMARY,
-  secondary: colors.gray[400],
-  baseline: colors.gray[300],
-  positive: colors.success,
-  negative: colors.error,
-  neutral: colors.gray[500],
-  // For multi-series charts
-  series: [
-    TEAL_PRIMARY,
-    colors.blue[500],
-    colors.primary[700],
-    colors.blue[700],
-    colors.gray[500],
-  ],
-} as const;
-
-/**
- * Standard Plotly layout configuration for PolicyEngine charts
- */
-export const chartLayout = {
-  font: {
-    family: typography.fontFamily.chart,
-    color: colors.text.primary,
-    size: 14,
-  },
-  paper_bgcolor: colors.white,
-  plot_bgcolor: colors.white,
-  margin: {
-    l: 60,
-    r: 40,
-    t: 40,
-    b: 60,
-  },
-  showlegend: true,
-  legend: {
-    orientation: 'h' as const,
-    yanchor: 'bottom' as const,
-    y: 1.02,
-    xanchor: 'right' as const,
-    x: 1,
-  },
-  xaxis: {
-    gridcolor: colors.border.light,
-    zerolinecolor: colors.border.medium,
-  },
-  yaxis: {
-    gridcolor: colors.border.light,
-    zerolinecolor: colors.border.medium,
-  },
-} as const;
-
-/**
- * Standard chart dimensions
- */
-export const chartDimensions = {
-  default: {
-    width: 800,
-    height: 600,
-  },
-  compact: {
-    width: 600,
-    height: 400,
-  },
-  wide: {
-    width: 1000,
-    height: 500,
-  },
-  square: {
-    width: 600,
-    height: 600,
-  },
-} as const;
-
-/**
- * PolicyEngine logo image configuration for chart watermarks
- */
-export const chartLogo = {
-  source: '/assets/logos/policyengine/teal-square.png',
-  xref: 'paper' as const,
-  yref: 'paper' as const,
-  x: 1,
-  y: 0,
-  sizex: 0.1,
-  sizey: 0.1,
-  xanchor: 'right' as const,
-  yanchor: 'bottom' as const,
-  opacity: 0.8,
-} as const;
-
-/**
- * Format configuration object for creating Plotly charts
- * Compatible with both React (react-plotly.js) and Python (plotly.py)
- */
-export interface ChartConfig {
-  layout: typeof chartLayout;
-  config: {
-    displayModeBar: boolean;
-    responsive: boolean;
-  };
-  style: {
-    width: string;
-    height: string;
-  };
-}
-
-export function getChartConfig(
-  dimensions: keyof typeof chartDimensions = 'default'
-): ChartConfig {
-  const dims = chartDimensions[dimensions];
-  return {
-    layout: chartLayout,
-    config: {
-      displayModeBar: false,
-      responsive: true,
-    },
-    style: {
-      width: `${dims.width}px`,
-      height: `${dims.height}px`,
-    },
-  };
-}
-
-/**
- * Currency formatter for chart axis labels
- */
-export function formatCurrency(value: number): string {
-  if (Math.abs(value) >= 1e9) {
-    return `$${(value / 1e9).toFixed(1)}B`;
-  }
-  if (Math.abs(value) >= 1e6) {
-    return `$${(value / 1e6).toFixed(1)}M`;
-  }
-  if (Math.abs(value) >= 1e3) {
-    return `$${(value / 1e3).toFixed(0)}K`;
-  }
-  return `$${value.toFixed(0)}`;
-}
-
-/**
- * Percentage formatter for chart axis labels
- */
-export function formatPercent(value: number, decimals: number = 0): string {
-  return `${(value * 100).toFixed(decimals)}%`;
-}
-
-/**
- * Number formatter for chart axis labels
- */
-export function formatNumber(value: number): string {
-  return value.toLocaleString();
-}
-
-// ---------------------------------------------------------------------------
-// Nice tick generation (D3-style)
-// ---------------------------------------------------------------------------
-
-const NICE_STEPS = [1, 2, 2.5, 5, 10];
-
-/**
- * Compute a "nice" step size for axis ticks by snapping to {1, 2, 2.5, 5}
- * multiples at each order of magnitude.
- */
-function niceStep(roughStep: number): number {
-  if (roughStep <= 0) {
-    return 1;
-  }
-  const exponent = Math.floor(Math.log10(roughStep));
-  const magnitude = 10 ** exponent;
-  const normalized = roughStep / magnitude;
-  const nice = NICE_STEPS.find((s) => s >= normalized - 1e-10) ?? 10;
-  return nice * magnitude;
-}
-
-/**
- * Generate nice tick values for a given domain and approximate tick count.
- * Ticks are rounded to human-friendly numbers (multiples of 1, 2, 2.5, 5).
- *
- * @param domain - [min, max] data range
- * @param count - Approximate number of ticks desired (default: 5)
- * @returns Array of tick values
- */
-export function getNiceTicks(domain: [number, number], count = 5): number[] {
-  const [dMin, dMax] = domain;
-  if (dMin === dMax) {
-    return [dMin];
-  }
-
-  const rawStep = (dMax - dMin) / Math.max(count - 1, 1);
-  const step = niceStep(rawStep);
-  const start = Math.floor(dMin / step) * step;
-  const ticks: number[] = [];
-
-  for (let v = start; v <= dMax + step * 0.01; v += step) {
-    // Round to avoid floating-point noise and negative zero
-    const rounded = Math.round(v * 1e10) / 1e10 || 0;
-    ticks.push(rounded);
-  }
-
-  return ticks;
-}
diff --git a/src/tokens/colors.ts b/src/tokens/colors.ts
deleted file mode 100644
index cade0a3..0000000
--- a/src/tokens/colors.ts
+++ /dev/null
@@ -1,139 +0,0 @@
-/**
- * PolicyEngine color palette
- * Source of truth for all PolicyEngine applications
- */
-
-export const colors = {
-  // Primary brand colors - teal
-  primary: {
-    50: '#E6FFFA',
-    100: '#B2F5EA',
-    200: '#81E6D9',
-    300: '#4FD1C5',
-    400: '#38B2AC',
-    500: '#319795', // Main brand color
-    600: '#2C7A7B',
-    700: '#285E61',
-    800: '#234E52',
-    900: '#1D4044',
-    alpha: {
-      40: '#31979566',
-      50: '#31979580',
-      60: '#31979599',
-    },
-  },
-
-  // Secondary colors - gray scale
-  secondary: {
-    50: '#F0F9FF',
-    100: '#F2F4F7',
-    200: '#E2E8F0',
-    300: '#CBD5E1',
-    400: '#94A3B8',
-    500: '#64748B',
-    600: '#475569',
-    700: '#344054',
-    800: '#1E293B',
-    900: '#101828',
-  },
-
-  // Blue accent colors
-  blue: {
-    50: '#F0F9FF',
-    100: '#E0F2FE',
-    200: '#BAE6FD',
-    300: '#7DD3FC',
-    400: '#38BDF8',
-    500: '#0EA5E9',
-    600: '#0284C7',
-    700: '#026AA2',
-    800: '#075985',
-    900: '#0C4A6E',
-  },
-
-  // Semantic colors
-  success: '#22C55E',
-  warning: '#FEC601',
-  error: '#EF4444',
-  info: '#1890FF',
-
-  // Neutral colors
-  white: '#FFFFFF',
-  black: '#000000',
-
-  // Gray scale (alias for secondary)
-  gray: {
-    50: '#F9FAFB',
-    100: '#F2F4F7',
-    200: '#E2E8F0',
-    300: '#D1D5DB',
-    400: '#9CA3AF',
-    500: '#6B7280',
-    600: '#4B5563',
-    700: '#344054',
-    800: '#1F2937',
-    900: '#101828',
-  },
-
-  // Background colors
-  background: {
-    primary: '#FFFFFF',
-    secondary: '#F5F9FF',
-    tertiary: '#F1F5F9',
-    sider: '#FFFFFF',
-  },
-
-  // Text colors
-  text: {
-    primary: '#000000',
-    secondary: '#5A5A5A',
-    tertiary: '#9CA3AF',
-    inverse: '#FFFFFF',
-    title: '#000000',
-    warning: '#d9480f', // Mantine orange.9 - WCAG AA compliant (~4.8:1 contrast)
-  },
-
-  // Teal alias (for convenience)
-  teal: {
-    500: '#319795',
-  },
-
-  // Border colors
-  border: {
-    light: '#E2E8F0',
-    medium: '#CBD5E1',
-    dark: '#94A3B8',
-  },
-
-  // Shadow colors
-  shadow: {
-    light: 'rgba(16, 24, 40, 0.05)',
-    medium: 'rgba(16, 24, 40, 0.1)',
-    dark: 'rgba(16, 24, 40, 0.2)',
-  },
-} as const;
-
-// Convenience exports for common colors
-export const TEAL_PRIMARY = colors.primary[500];
-export const TEAL_ACCENT = '#39C6C0'; // Legacy accent
-
-// Semantic color exports
-export const SUCCESS_GREEN = colors.success;
-export const WARNING_YELLOW = colors.warning;
-export const ERROR_RED = colors.error;
-export const INFO_BLUE = colors.info;
-
-// Background exports
-export const BACKGROUND_PRIMARY = colors.background.primary;
-export const BACKGROUND_SIDEBAR = colors.background.secondary;
-export const BACKGROUND_TERTIARY = colors.background.tertiary;
-
-// Text exports
-export const TEXT_PRIMARY = colors.text.primary;
-export const TEXT_SECONDARY = colors.text.secondary;
-export const TEXT_TERTIARY = colors.text.tertiary;
-
-// Border exports
-export const BORDER_LIGHT = colors.border.light;
-
-export type Colors = typeof colors;
diff --git a/src/tokens/index.ts b/src/tokens/index.ts
deleted file mode 100644
index 37b427c..0000000
--- a/src/tokens/index.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-export * from './colors';
-export * from './typography';
-export * from './spacing';
-export * from './charts';
diff --git a/src/tokens/spacing.ts b/src/tokens/spacing.ts
deleted file mode 100644
index 12b9333..0000000
--- a/src/tokens/spacing.ts
+++ /dev/null
@@ -1,97 +0,0 @@
-/**
- * PolicyEngine spacing system
- * Source of truth for spacing, layout, and border radius
- */
-
-export const spacing = {
-  // Base spacing scale
-  xs: '4px',
-  sm: '8px',
-  md: '12px',
-  lg: '16px',
-  xl: '20px',
-  '2xl': '24px',
-  '3xl': '32px',
-  '4xl': '48px',
-  '5xl': '64px',
-
-  // Component-specific spacing
-  component: {
-    button: {
-      padding: '8px 14px',
-      height: '36px',
-    },
-    input: {
-      padding: '8px 12px',
-      height: '40px',
-      compactWidth: '120px',
-    },
-    badge: {
-      padding: '4px 12px',
-    },
-    menu: {
-      itemPadding: '6px 24px',
-      itemHeight: '40px',
-    },
-    tab: {
-      padding: '12px 16px',
-    },
-  },
-
-  // Layout spacing
-  layout: {
-    sidebar: '79px',
-    sidebarWidth: '280px',
-    header: '58px',
-    content: '1361px',
-    container: '976px',
-    sideGutter: '200px',
-  },
-
-  // AppShell design tokens
-  appShell: {
-    header: {
-      height: '58px',
-      padding: '8px 16px',
-    },
-    navbar: {
-      width: '300px',
-      padding: '0px',
-      breakpoint: 'sm',
-    },
-    aside: {
-      width: '300px',
-      padding: '16px',
-      breakpoint: 'md',
-    },
-    footer: {
-      height: '60px',
-      padding: '12px 24px',
-    },
-    main: {
-      padding: '24px',
-      minHeight: '100dvh',
-    },
-  },
-
-  // Container padding
-  container: {
-    xs: '16px',
-    sm: '24px',
-    md: '32px',
-    lg: '48px',
-    xl: '64px',
-    '2xl': '80px',
-  },
-
-  // Border radius — semantic scale
-  radius: {
-    none: '0px',
-    chip: '2px',
-    element: '4px',
-    container: '8px',
-    feature: '12px',
-  },
-} as const;
-
-export type Spacing = typeof spacing;
diff --git a/src/tokens/typography.ts b/src/tokens/typography.ts
deleted file mode 100644
index 85c3f1f..0000000
--- a/src/tokens/typography.ts
+++ /dev/null
@@ -1,99 +0,0 @@
-/**
- * PolicyEngine typography system
- * Source of truth for fonts, sizes, and text styles
- *
- * Two font families only: Inter (everything) + JetBrains Mono (code).
- * Legacy aliases (secondary, body, chart, prose) all resolve to the
- * primary Inter stack for backward compatibility.
- */
-
-const INTER = 'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
-
-export const typography = {
-  fontFamily: {
-    primary: INTER,
-    // Legacy aliases — all resolve to Inter
-    secondary: INTER,
-    body: INTER,
-    chart: INTER,
-    prose: INTER,
-    // Code
-    mono: 'JetBrains Mono, "Fira Code", Consolas, monospace',
-  },
-
-  fontWeight: {
-    thin: 100,
-    light: 300,
-    normal: 400,
-    medium: 500,
-    semibold: 600,
-    bold: 700,
-    extrabold: 800,
-    black: 900,
-  },
-
-  fontSize: {
-    xs: '12px',
-    sm: '14px',
-    base: '16px',
-    lg: '18px',
-    xl: '20px',
-    '2xl': '24px',
-    '3xl': '28px',
-    '4xl': '32px',
-  },
-
-  lineHeight: {
-    none: '1',
-    tight: '1.25',
-    snug: '1.375',
-    normal: '1.5',
-    relaxed: '1.625',
-    loose: '2',
-    '20': '20px',
-    '22': '22px',
-    '24': '24px',
-  },
-
-  // Pre-defined text styles — all use Inter
-  textStyles: {
-    'sm-medium': {
-      fontFamily: 'Inter',
-      fontSize: '14px',
-      fontWeight: 500,
-      lineHeight: '20px',
-    },
-    'sm-semibold': {
-      fontFamily: 'Inter',
-      fontSize: '14px',
-      fontWeight: 600,
-      lineHeight: '20px',
-    },
-    'md-normal': {
-      fontFamily: 'Inter',
-      fontSize: '16px',
-      fontWeight: 400,
-      lineHeight: '24px',
-    },
-    'body-regular': {
-      fontFamily: 'Inter',
-      fontSize: '14px',
-      fontWeight: 400,
-      lineHeight: '22px',
-    },
-    'h5-regular': {
-      fontFamily: 'Inter',
-      fontSize: '16px',
-      fontWeight: 400,
-      lineHeight: '24px',
-    },
-  },
-} as const;
-
-// Convenience exports for common fonts
-export const FONT_UI = typography.fontFamily.primary;
-export const FONT_CHART = typography.fontFamily.chart;
-export const FONT_PROSE = typography.fontFamily.prose;
-export const FONT_MONO = typography.fontFamily.mono;
-
-export type Typography = typeof typography;
diff --git a/src/utils/cn.ts b/src/utils/cn.ts
index d22ea5f..2819a83 100644
--- a/src/utils/cn.ts
+++ b/src/utils/cn.ts
@@ -1,15 +1,5 @@
 import { clsx, type ClassValue } from 'clsx';
-import { extendTailwindMerge } from 'tailwind-merge';
-
-const twMerge = extendTailwindMerge({
-  extend: {
-    classGroups: {
-      'text-color': [
-        { text: ['pe-primary', 'pe-gray', 'pe-blue', 'pe-text', 'pe-success', 'pe-error', 'pe-warning', 'pe-info', 'pe-border', 'pe-bg', 'primary-foreground'] },
-      ],
-    },
-  },
-});
+import { twMerge } from 'tailwind-merge';
 
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
diff --git a/src/utils/formatters.ts b/src/utils/formatters.ts
index 1000ac8..417849a 100644
--- a/src/utils/formatters.ts
+++ b/src/utils/formatters.ts
@@ -1 +1,29 @@
-export { formatCurrency, formatPercent, formatNumber } from '../tokens/charts';
+/**
+ * Currency formatter for chart axis labels
+ */
+export function formatCurrency(value: number): string {
+  if (Math.abs(value) >= 1e9) {
+    return `$${(value / 1e9).toFixed(1)}B`;
+  }
+  if (Math.abs(value) >= 1e6) {
+    return `$${(value / 1e6).toFixed(1)}M`;
+  }
+  if (Math.abs(value) >= 1e3) {
+    return `$${(value / 1e3).toFixed(0)}K`;
+  }
+  return `$${value.toFixed(0)}`;
+}
+
+/**
+ * Percentage formatter for chart axis labels
+ */
+export function formatPercent(value: number, decimals: number = 0): string {
+  return `${(value * 100).toFixed(decimals)}%`;
+}
+
+/**
+ * Number formatter for chart axis labels
+ */
+export function formatNumber(value: number): string {
+  return value.toLocaleString();
+}
diff --git a/src/utils/getCssVar.ts b/src/utils/getCssVar.ts
deleted file mode 100644
index b14fd6c..0000000
--- a/src/utils/getCssVar.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-/**
- * Read a CSS custom property value at runtime.
- * Useful for Recharts and other SVG-based libraries that
- * need resolved color strings (not CSS var() references).
- *
- * @example
- *   getCssVar('--pe-color-primary-500') // '#319795'
- */
-export function getCssVar(name: string): string {
-  return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
-}
diff --git a/src/utils/index.ts b/src/utils/index.ts
index 78faad9..582961c 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -1,3 +1,2 @@
 export { cn } from './cn';
-export { getCssVar } from './getCssVar';
 export { formatCurrency, formatPercent, formatNumber } from './formatters';
diff --git a/tests/charts/Charts.test.tsx b/tests/charts/Charts.test.tsx
index 0cdc25b..f60bd7b 100644
--- a/tests/charts/Charts.test.tsx
+++ b/tests/charts/Charts.test.tsx
@@ -40,7 +40,7 @@ describe('chartDefaults', () => {
     const { AXIS_STYLE, GRID_STYLE, TOOLTIP_STYLE } = await import(
       '../../src/charts/chartDefaults'
     );
-    expect(AXIS_STYLE.fontFamily).toContain('Inter');
+    expect(AXIS_STYLE.fontFamily).toBe('var(--font-sans)');
     expect(GRID_STYLE.stroke).toBeDefined();
     expect(TOOLTIP_STYLE.contentStyle.borderRadius).toBe('8px');
   });
diff --git a/tests/tokens/charts.test.ts b/tests/tokens/charts.test.ts
index bb0a215..591ca1c 100644
--- a/tests/tokens/charts.test.ts
+++ b/tests/tokens/charts.test.ts
@@ -1,15 +1,14 @@
 import { describe, it, expect } from 'vitest';
 import {
-  chartColors,
   formatCurrency,
   formatPercent,
   formatNumber,
-  getNiceTicks,
-} from '../../src/tokens/charts';
+} from '../../src/utils/formatters';
+import { chartColors } from '../../src/charts/chartDefaults';
 
 describe('chartColors', () => {
-  it('has primary color matching TEAL_PRIMARY', () => {
-    expect(chartColors.primary).toBe('#319795');
+  it('has primary color as CSS var', () => {
+    expect(chartColors.primary).toBe('var(--chart-1)');
   });
 
   it('has series array', () => {
@@ -44,16 +43,3 @@ describe('formatPercent', () => {
     expect(formatPercent(0.156, 1)).toBe('15.6%');
   });
 });
-
-describe('getNiceTicks', () => {
-  it('returns single value for equal domain', () => {
-    expect(getNiceTicks([5, 5])).toEqual([5]);
-  });
-
-  it('returns nice tick values', () => {
-    const ticks = getNiceTicks([0, 100], 5);
-    expect(ticks.length).toBeGreaterThan(1);
-    expect(ticks[0]).toBeLessThanOrEqual(0);
-    expect(ticks[ticks.length - 1]).toBeGreaterThanOrEqual(100);
-  });
-});
diff --git a/tests/tokens/colors.test.ts b/tests/tokens/colors.test.ts
deleted file mode 100644
index 63cf557..0000000
--- a/tests/tokens/colors.test.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { colors, TEAL_PRIMARY, TEAL_ACCENT } from '../../src/tokens/colors';
-
-describe('colors', () => {
-  it('exports TEAL_PRIMARY as primary-500', () => {
-    expect(TEAL_PRIMARY).toBe('#319795');
-    expect(colors.primary[500]).toBe(TEAL_PRIMARY);
-  });
-
-  it('exports TEAL_ACCENT', () => {
-    expect(TEAL_ACCENT).toBe('#39C6C0');
-  });
-
-  it('has complete primary scale', () => {
-    expect(colors.primary[50]).toBeDefined();
-    expect(colors.primary[900]).toBeDefined();
-  });
-
-  it('has semantic colors', () => {
-    expect(colors.success).toBe('#22C55E');
-    expect(colors.warning).toBe('#FEC601');
-    expect(colors.error).toBe('#EF4444');
-    expect(colors.info).toBe('#1890FF');
-  });
-
-  it('has text colors', () => {
-    expect(colors.text.primary).toBe('#000000');
-    expect(colors.text.secondary).toBe('#5A5A5A');
-  });
-
-  it('has border colors', () => {
-    expect(colors.border.light).toBe('#E2E8F0');
-    expect(colors.border.medium).toBe('#CBD5E1');
-  });
-});
diff --git a/tests/tokens/typography.test.ts b/tests/tokens/typography.test.ts
deleted file mode 100644
index 985465a..0000000
--- a/tests/tokens/typography.test.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { typography, FONT_UI, FONT_MONO } from '../../src/tokens/typography';
-
-describe('typography', () => {
-  it('uses Inter as primary font', () => {
-    expect(typography.fontFamily.primary).toContain('Inter');
-    expect(FONT_UI).toBe(typography.fontFamily.primary);
-  });
-
-  it('uses JetBrains Mono for code', () => {
-    expect(typography.fontFamily.mono).toContain('JetBrains Mono');
-    expect(FONT_MONO).toBe(typography.fontFamily.mono);
-  });
-
-  it('has font weight scale', () => {
-    expect(typography.fontWeight.normal).toBe(400);
-    expect(typography.fontWeight.semibold).toBe(600);
-    expect(typography.fontWeight.bold).toBe(700);
-  });
-
-  it('has font size scale', () => {
-    expect(typography.fontSize.sm).toBe('14px');
-    expect(typography.fontSize.base).toBe('16px');
-  });
-});

From 020952ed2e0367f92776481e315ceabc37405ae4 Mon Sep 17 00:00:00 2001
From: Anthony Volk <anth.volk@gmail.com>
Date: Sun, 8 Mar 2026 19:39:26 +0100
Subject: [PATCH 3/7] Fix Tailwind v4 consumer integration: remove @import, add
 @source
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove `@import "tailwindcss"` from tokens.css — consumers must own this
- Add `@source "../components/**/*.{ts,tsx}"` so Tailwind scans ui-kit components
- Add `src/theme` to package.json files array for npm publishing
- Update comment block with correct two-import consumer pattern

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 package.json         |  3 ++-
 src/theme/tokens.css | 10 ++++++++--
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/package.json b/package.json
index 599c05a..ed9a660 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,8 @@
     "./theme.css": "./src/theme/tokens.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/theme"
   ],
   "scripts": {
     "dev": "vite",
diff --git a/src/theme/tokens.css b/src/theme/tokens.css
index b500bda..60408da 100644
--- a/src/theme/tokens.css
+++ b/src/theme/tokens.css
@@ -1,14 +1,20 @@
-@import "tailwindcss";
 @import "tw-animate-css";
 
 @custom-variant dark (&:is(.dark *));
 
+@source "../components/**/*.{ts,tsx}";
+
 /* ============================================================
  * PolicyEngine Design Tokens
  * Source: @policyengine/design-system v0.3.0 (npm)
  *
  * This file IS the design system for all frontend projects.
- * Import it: @import "@policyengine/ui-kit/theme.css";
+ * Consumer usage (globals.css):
+ *   @import "tailwindcss";
+ *   @import "@policyengine/ui-kit/theme.css";
+ *
+ * Both imports are required. Tailwind must come first.
+ * The consumer must have @tailwindcss/postcss in their postcss config.
  * ============================================================ */
 
 /* --- Layer 1: Raw token values (shadcn/ui semantic variables) --- */

From 6008a1cc7b9f91ef60d4203640179c2e4ee99951 Mon Sep 17 00:00:00 2001
From: Anthony Volk <anth.volk@gmail.com>
Date: Sun, 8 Mar 2026 20:56:40 +0100
Subject: [PATCH 4/7] Fix @source to scan all src files, not just nonexistent
 components/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ui-kit's source directories are charts/, display/, inputs/, layout/,
primitives/ — not components/. The hardcoded @source "../components/"
matched nothing, so utility classes used in ui-kit components were never
generated in consumer builds.

Changed to @source "../**/*.{ts,tsx}" which covers all source files
regardless of directory structure. Also updated authoring skill to warn
against hardcoding directory names in @source.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../tailwind-design-system-authoring/SKILL.md | 206 +++++++++++
 .../references/industry-patterns.md           | 320 ++++++++++++++++++
 src/theme/tokens.css                          |   2 +-
 3 files changed, 527 insertions(+), 1 deletion(-)
 create mode 100644 skills/tailwind-design-system-authoring/SKILL.md
 create mode 100644 skills/tailwind-design-system-authoring/references/industry-patterns.md

diff --git a/skills/tailwind-design-system-authoring/SKILL.md b/skills/tailwind-design-system-authoring/SKILL.md
new file mode 100644
index 0000000..6f0d7cb
--- /dev/null
+++ b/skills/tailwind-design-system-authoring/SKILL.md
@@ -0,0 +1,206 @@
+---
+name: tailwind-design-system-authoring
+description: |
+  This skill should be used when modifying the ui-kit's CSS theme, adding new design tokens,
+  creating new component styles, or working on the ui-kit's build pipeline and package exports.
+  Triggers: "add token", "design token", "theme.css", "tokens.css", "@theme", "ui-kit styling",
+  "add color", "add spacing", "component style", "base styles", "ui-kit architecture",
+  "how do Tailwind UI kits work", "authoring pattern", "@source", "package exports"
+---
+
+# Tailwind v4 Design System Authoring
+
+Canonical patterns for building a Tailwind CSS v4-based UI kit that other applications import. This skill codifies how production libraries (DaisyUI, HeroUI, shadcn/ui, Mantine) structure their styling and what the Tailwind maintainers recommend for shared CSS packages.
+
+## The Cardinal Rule
+
+**The library must NOT contain `@import "tailwindcss"`.** The consumer owns that import. Every major Tailwind-based library follows this rule, and the Tailwind maintainers explicitly recommend it (GitHub discussions #17715, #18545, #18758).
+
+Including `@import "tailwindcss"` inside the library causes:
+- Double Tailwind (double preflight resets, double theme layers) if the consumer also imports it
+- Source detection scanning from the library's directory instead of the consumer's project
+- Utility classes for consumer components not being generated
+
+## Architecture of a Tailwind v4 Theme File
+
+The library ships a CSS file with tokens, source directives, and base styles — but no Tailwind import:
+
+```css
+/* src/theme/tokens.css — NO @import "tailwindcss" */
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+/* Source detection: tell Tailwind to scan ALL library source files */
+@source "../**/*.{ts,tsx}";
+
+/* Layer 1: Raw CSS variables (shadcn/ui convention) */
+:root {
+  --primary: #2C7A7B;
+  --background: #FFFFFF;
+  /* ... */
+}
+
+/* Layer 2: Bridge to Tailwind utilities */
+@theme inline {
+  --color-primary: var(--primary);
+  --color-background: var(--background);
+  /* ... */
+}
+
+/* Layer 3: Static brand palette + typography + spacing */
+@theme {
+  --color-teal-500: #319795;
+  --font-sans: Inter, sans-serif;
+  --text-sm: 14px;
+  /* ... */
+}
+
+/* Layer 4: Base element styles */
+@layer base {
+  body { @apply bg-background text-foreground; }
+}
+```
+
+## `@theme` Variants — When to Use Each
+
+| Directive | Creates `:root` vars | Generates utilities | Use case |
+|-----------|:---:|:---:|---|
+| `@theme` | Yes | Yes | Static literal values (hex colors, pixel sizes, font stacks) |
+| `@theme inline` | No | Yes (inlines the expression) | Values referencing CSS variables (`var(--something)`) |
+| `@theme static` | Yes (all, even unused) | Yes | Libraries needing all tokens available regardless of usage |
+| `@theme reference` | Yes | No | Reference-only tokens, no utility generation |
+
+**Critical rule:** Use `@theme inline` whenever the value contains `var()`. Using plain `@theme` with `var()` bakes the literal string `var(--x)` at build time, breaking runtime resolution (dark mode, contextual overrides).
+
+## `@source` for Library Component Scanning
+
+Tailwind v4 auto-ignores `node_modules/`. Without an explicit `@source`, utility classes used inside the library's own components will never be generated during the consumer's build — the consumer will see those classes in the rendered HTML but they'll have no effect.
+
+**Use a wildcard glob that covers all source files, not a hardcoded directory name:**
+
+```css
+/* In src/theme/tokens.css */
+@source "../**/*.{ts,tsx}";
+```
+
+This scans every `.ts` and `.tsx` file under `src/` (relative to the CSS file). It is resilient to directory renames and restructuring — new component folders are automatically included.
+
+**Do NOT hardcode specific directory names** like `@source "../components/**/*.{ts,tsx}"`. If the library organizes components into `charts/`, `display/`, `inputs/`, `layout/`, etc., a hardcoded `../components/` matches nothing and silently fails — utility classes from those components will be missing in the consumer's build with no error.
+
+**Path resolution:** `@source` paths resolve **relative to the CSS file they appear in**, not `process.cwd()`. When `tokens.css` lives at `src/theme/tokens.css`, the `../` resolves to `src/`.
+
+**Verification procedure** — run this after any `@source` change or directory restructure:
+
+1. List the library's actual source directories:
+   ```bash
+   ls -d src/*/
+   ```
+2. Confirm the `@source` glob in `tokens.css` covers all directories that contain components (any `.tsx` file with `className=`):
+   ```bash
+   grep -rl 'className=' src/ --include='*.tsx' | head -20
+   ```
+3. Verify the glob matches those files. From `src/theme/` (where tokens.css lives), `../**/*.{ts,tsx}` should match everything under `src/`.
+
+**Consumer-side note:** The consumer does NOT need its own `@source` directive. `@import "tailwindcss"` triggers automatic source detection from `process.cwd()`, which scans the consumer's `app/`, `components/`, `src/`, etc. The `@source` in the library's CSS only exists to cover the library's own files inside `node_modules/`.
+
+## Package Exports
+
+The `package.json` must export the theme CSS so consumers can import it:
+
+```json
+{
+  "exports": {
+    ".": { "import": "./dist/index.js" },
+    "./theme.css": "./src/theme/tokens.css"
+  },
+  "files": ["dist", "src/theme"]
+}
+```
+
+**Critical:** The `files` field must include the theme source directory. If `files` only lists `dist`, the theme CSS will be missing from the published npm package.
+
+Exporting source CSS (not pre-built) is correct — the consumer's `@tailwindcss/postcss` processes it during their build, which is how `@theme` and `@source` directives work.
+
+## The Four Industry Patterns
+
+For detailed examples of how DaisyUI, HeroUI, shadcn/ui, and Mantine handle styling, consult:
+- **`references/industry-patterns.md`** — Detailed breakdown of each library's approach
+
+### Quick Summary
+
+| Pattern | Example | Consumer needs Tailwind? |
+|---------|---------|:---:|
+| **Tailwind Plugin** (`@plugin`) | DaisyUI, HeroUI | Yes |
+| **CSS Theme File** (`@import`) | This ui-kit | Yes |
+| **Copy-Paste** | shadcn/ui | Yes |
+| **Pre-compiled CSS** | Mantine | No |
+
+PolicyEngine uses the **CSS Theme File** pattern — the simplest approach that still gives consumers full Tailwind utility access.
+
+## What NOT to Do
+
+1. **Do not include `@import "tailwindcss"` in the library's CSS** — the consumer owns this
+2. **Do not use `@theme` for values containing `var()`** — use `@theme inline` instead
+3. **Do not create `tailwind.config.ts`** — Tailwind v4 is CSS-first, all config lives in `@theme` blocks
+4. **Do not ship pre-compiled utility classes alongside raw tokens** — pick one pattern (pre-compiled OR theme file, not both in the same export)
+5. **Do not rely on automatic source detection for library components** — `node_modules` is auto-ignored; always include explicit `@source` directives
+6. **Do not hardcode directory names in `@source`** — use `@source "../**/*.{ts,tsx}"` to cover all source files; hardcoded paths like `../components/` silently break when the directory structure changes
+7. **Do not use Sass, Less, or CSS Modules** — Tailwind v4 is incompatible with preprocessors and CSS Modules cause performance problems
+
+## Known Tailwind v4 Issues
+
+- **[#19040](https://github.com/tailwindlabs/tailwindcss/issues/19040)**: `@source` may not reliably scan into `node_modules` in all environments
+- **[#18966](https://github.com/tailwindlabs/tailwindcss/issues/18966)**: `@theme` in imported files may not be fully processed in edge cases
+- **Symlinks** (`bun link`, `npm link`): Path resolution differs from nested `node_modules` installs — test with both during development
+
+If `@source` or `@theme` in imported files proves unreliable, the escalation path is converting to a **Tailwind plugin** (`@plugin`) — see `references/industry-patterns.md` for the plugin pattern.
+
+## Adding New Tokens
+
+To add a new design token:
+
+1. **Static literal value** (e.g., a new brand color):
+   ```css
+   @theme {
+     --color-coral-500: #FF6B6B;
+   }
+   ```
+   This creates `bg-coral-500`, `text-coral-500`, etc.
+
+2. **Semantic token referencing a variable** (e.g., a new role):
+   ```css
+   :root { --success: #22C55E; }
+   @theme inline { --color-success: var(--success); }
+   ```
+   This creates `bg-success`, `text-success` with runtime resolution.
+
+3. **Non-color token** (spacing, breakpoint, font size):
+   ```css
+   @theme {
+     --spacing-sidebar: 280px;    /* → w-sidebar, p-sidebar, etc. */
+     --breakpoint-3xl: 120rem;    /* → 3xl: responsive prefix */
+     --text-hero: 48px;           /* → text-hero */
+     --text-hero--line-height: 56px;
+   }
+   ```
+
+## Namespace Reference
+
+| CSS variable prefix | Generated utilities | Example |
+|---|---|---|
+| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*` | `--color-teal-500` |
+| `--text-*` | `text-*` (font size) | `--text-sm: 14px` |
+| `--font-*` | `font-*` (font family) | `--font-sans` |
+| `--font-weight-*` | `font-*` (weight) | `--font-weight-bold` |
+| `--spacing-*` | `p-*`, `m-*`, `gap-*`, `w-*`, `h-*` | `--spacing-header: 58px` |
+| `--radius-*` | `rounded-*` | `--radius-lg` |
+| `--breakpoint-*` | Responsive prefixes (`sm:`, `md:`) | `--breakpoint-md: 62rem` |
+| `--shadow-*` | `shadow-*` | `--shadow-lg` |
+
+## Related Resources
+
+- **`references/industry-patterns.md`** — How DaisyUI, HeroUI, shadcn/ui, and Mantine handle Tailwind
+- [Tailwind v4 Theme docs](https://tailwindcss.com/docs/theme)
+- [Tailwind v4 Source Detection](https://tailwindcss.com/docs/detecting-classes-in-source-files)
+- [Tailwind v4 Functions and Directives](https://tailwindcss.com/docs/functions-and-directives)
diff --git a/skills/tailwind-design-system-authoring/references/industry-patterns.md b/skills/tailwind-design-system-authoring/references/industry-patterns.md
new file mode 100644
index 0000000..6a5b6f1
--- /dev/null
+++ b/skills/tailwind-design-system-authoring/references/industry-patterns.md
@@ -0,0 +1,320 @@
+# Industry Patterns for Tailwind-Based UI Kits
+
+Detailed breakdown of how major component libraries handle styling with Tailwind CSS, with emphasis on Tailwind v4 patterns.
+
+## Pattern 1: Tailwind Plugin — DaisyUI
+
+DaisyUI is a pure CSS library with zero JavaScript runtime. In v5 (built for Tailwind v4), it is consumed as a Tailwind plugin.
+
+### Consumer Setup
+
+```css
+/* globals.css */
+@import "tailwindcss";
+@plugin "daisyui";
+```
+
+With theme configuration:
+
+```css
+@plugin "daisyui" {
+  themes: light --default, dark --prefersdark;
+  logs: false;
+}
+```
+
+### How It Works
+
+- The `@plugin` directive loads the DaisyUI JavaScript module into Tailwind's build
+- DaisyUI calls `addComponents()` to inject semantic class names (`.btn`, `.card`, `.toggle`, `.badge`)
+- Classes are always generated (no source scanning needed — the plugin injects them directly)
+- They participate in Tailwind's `@layer components` cascade layer
+- They get full variant support (`hover:btn-primary`, `lg:card-compact`)
+
+### Themes
+
+DaisyUI provides 35+ built-in themes via CSS custom properties:
+- Themes are sets of CSS variables under `[data-theme="dark"]` selectors
+- Colors use OKLCH format
+- Custom themes created via `@plugin "daisyui/theme"` with overrides
+
+### Key Insight
+
+DaisyUI adds **semantic class names** on top of Tailwind's utilities. Components use those semantic classes, not raw utility classes. Source scanning is irrelevant because the plugin programmatically injects all classes.
+
+---
+
+## Pattern 2: Tailwind Plugin + React Provider — HeroUI
+
+HeroUI (formerly NextUI) combines a Tailwind plugin with React components and a context provider.
+
+### Consumer Setup (Tailwind v4)
+
+```css
+/* globals.css */
+@import "tailwindcss";
+@layer theme, base, components, utilities;
+@plugin './hero.ts';
+@source '../../node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}';
+```
+
+Local plugin wrapper:
+
+```ts
+// hero.ts
+import { heroui } from "@heroui/react";
+export default heroui();
+```
+
+Plus `<HeroUIProvider>` wrapping the app root.
+
+### How It Works
+
+- Ships as multiple packages: `@heroui/react` (components), `@heroui/theme` (tokens), `@heroui/styles` (CSS)
+- The Tailwind plugin (`heroui()`) registers colors, spacing, radius tokens
+- **Requires explicit `@source`** pointing to the theme package's dist folder
+- The consumer must add the `@source` manually because `node_modules` is auto-ignored
+- Path in `@source` depends on the CSS file's location relative to `node_modules`
+
+### Key Insight
+
+HeroUI requires the consumer to know about `@source` and configure it correctly. The path is fragile — it changes depending on the CSS file location and whether packages are hoisted or nested.
+
+---
+
+## Pattern 3: Copy-Paste + Tailwind — shadcn/ui
+
+shadcn/ui is not a traditional npm library. Components are copied into the consumer's project via CLI.
+
+### Consumer Setup (Tailwind v4)
+
+```css
+/* globals.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0.004 285.82);
+  --primary: oklch(0.205 0.042 265.76);
+  /* ... many more variables ... */
+}
+
+.dark {
+  --background: oklch(0.145 0.004 285.82);
+  /* ... dark overrides ... */
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  /* ... map all to Tailwind theme ... */
+}
+```
+
+Adding components:
+
+```bash
+npx shadcn@latest add button
+# Copies component source into components/ui/button.tsx
+```
+
+### How It Works
+
+- Components are literally copied into `components/ui/` — the consumer owns the code
+- Because components live in the consumer's source tree, Tailwind automatically scans them
+- No `@source` issues, no plugin needed
+- Themes are CSS variables that the consumer defines in their own globals.css
+- Every component uses the same variable names (`--primary`, `--background`, `--foreground`)
+
+### Key Insight
+
+By placing components in the consumer's source tree, shadcn/ui completely sidesteps the `node_modules` scanning problem. The tradeoff is that consumers must manage component updates manually.
+
+---
+
+## Pattern 4: Pre-compiled CSS — Mantine
+
+Mantine is fully independent from Tailwind. It ships pre-compiled CSS via CSS modules.
+
+### Consumer Setup
+
+```tsx
+import '@mantine/core/styles.css';
+```
+
+Optional PostCSS preset:
+
+```js
+module.exports = {
+  plugins: {
+    'postcss-preset-mantine': {},
+  },
+};
+```
+
+### How It Works
+
+- All component styles are CSS modules, compiled at library build time
+- `@mantine/core/styles.css` contains all compiled component styles
+- No Tailwind dependency at all
+- Consumer just imports one CSS file
+- Works with any framework, any build tool
+
+### Tailwind Co-existence
+
+Mantine can work alongside Tailwind, but:
+- Must NOT include Tailwind's base/reset styles (they conflict with Mantine's)
+- Cascade layers create precedence issues (`@layer`-ed rules have lower precedence than non-layered rules)
+
+### Key Insight
+
+Mantine proves that shipping pre-compiled CSS works perfectly when components don't use Tailwind utilities internally. The consumer gets zero-config styling at the cost of no Tailwind utility sharing.
+
+---
+
+## Pattern Comparison
+
+| Aspect | DaisyUI (Plugin) | HeroUI (Plugin+React) | shadcn/ui (Copy) | Mantine (Pre-built) |
+|--------|---|---|---|---|
+| Consumer needs Tailwind | Yes | Yes | Yes | No |
+| `@import "tailwindcss"` in library | No | No | N/A (no library CSS) | No |
+| Source scanning issues | None (plugin injects) | Yes (needs `@source`) | None (in consumer tree) | None (pre-built) |
+| Consumer config | `@plugin "daisyui"` | `@plugin` + `@source` | CSS vars + `@theme inline` | `import styles.css` |
+| Customization | CSS vars, theme config | Tailwind `@theme` overrides | Edit CSS vars | Mantine theme provider |
+| Bundle size control | Good (JIT) | Good (JIT + `@source`) | Best (only used components) | Moderate (all styles) |
+| Dark mode | Data attribute themes | Provider + variants | CSS vars + `.dark` class | Theme provider |
+
+---
+
+## The `@plugin` Directive in Tailwind v4
+
+In v4, plugins are loaded via CSS instead of JavaScript config:
+
+```css
+/* v3 (JavaScript) */
+// tailwind.config.js
+module.exports = { plugins: [require('daisyui')] }
+
+/* v4 (CSS) */
+@import "tailwindcss";
+@plugin "daisyui";
+```
+
+For plugins with configuration:
+
+```css
+@plugin "daisyui" {
+  themes: light --default, dark --prefersdark;
+}
+```
+
+For local plugins (wrapping a JS function):
+
+```css
+@plugin './hero.ts';
+```
+
+### Plugin API
+
+Plugins receive Tailwind's API and call methods:
+
+```js
+export default function myPlugin({ addBase, addComponents, addUtilities, theme }) {
+  addBase({ 'h1': { fontSize: theme('fontSize.2xl') } });
+  addComponents({ '.btn': { padding: '0.5rem 1rem' } });
+  addUtilities({ '.scrollbar-hidden': { '&::-webkit-scrollbar': { display: 'none' } } });
+}
+```
+
+### When to Use a Plugin vs. CSS Theme File
+
+| Use a plugin when... | Use a CSS theme file when... |
+|---|---|
+| Injecting semantic class names (`.btn`, `.card`) | Providing design tokens only |
+| Classes must always exist (no source scanning) | Consumer uses standard Tailwind utilities |
+| Complex component styles with variants | Simpler token-based theming |
+| Need JavaScript logic for theme generation | Pure CSS is sufficient |
+
+---
+
+## `@source` Deep Dive
+
+### Automatic Source Detection
+
+Default behavior in Tailwind v4:
+- Scans from `process.cwd()` (current working directory)
+- Ignores `node_modules` (hardcoded exclusion)
+- Ignores files in `.gitignore`
+- Ignores binary files, CSS files, lock files
+
+### `@source` Directive
+
+```css
+@source "../node_modules/@acmecorp/ui-lib";
+@source "./components/**/*.{ts,tsx}";
+```
+
+Paths resolve **relative to the CSS file containing the directive**.
+
+### `source()` on `@import`
+
+```css
+@import "tailwindcss" source("./src");
+```
+
+Overrides the default `cwd()` base for automatic scanning. Useful in monorepos.
+
+### `source(none)` — Explicit-Only Mode
+
+```css
+@import "tailwindcss" source(none);
+@source "./src/app";
+@source "./src/components";
+```
+
+Disables automatic scanning entirely. Only explicitly registered sources are scanned.
+
+### Library Pattern for `@source`
+
+A library ships `@source` in its CSS file. When the consumer imports this CSS, the directive propagates:
+
+```css
+/* Library: theme.css */
+@source "./components/**/*.{ts,tsx}";
+@theme { --color-brand: oklch(0.6 0.2 260); }
+```
+
+```css
+/* Consumer: globals.css */
+@import "tailwindcss";
+@import "@my-lib/theme.css";
+/* @source from theme.css is now active — scans library's components */
+```
+
+### Known Issues
+
+- **GitHub #19040**: `@source` may fail to scan inside `node_modules` in some build tool configurations
+- **Symlinks**: `bun link` / `npm link` resolve to the original path, not the `node_modules` symlink path. This can cause `@source` relative paths to resolve differently than in a normal install.
+- **Workaround**: If `@source` from the library doesn't work, the consumer adds their own: `@source "../node_modules/@policyengine/ui-kit/src";`
+
+---
+
+## Sources
+
+- [Tailwind CSS v4 Theme docs](https://tailwindcss.com/docs/theme)
+- [Tailwind CSS v4 Source Detection](https://tailwindcss.com/docs/detecting-classes-in-source-files)
+- [Tailwind CSS v4 Functions and Directives](https://tailwindcss.com/docs/functions-and-directives)
+- [GitHub Discussion #17715 — Component Library Setup](https://github.com/tailwindlabs/tailwindcss/discussions/17715)
+- [GitHub Discussion #18545 — Distributing Component Libraries](https://github.com/tailwindlabs/tailwindcss/discussions/18545)
+- [GitHub Discussion #18758 — Styles Not Applying from Library](https://github.com/tailwindlabs/tailwindcss/discussions/18758)
+- [GitHub Issue #18966 — @theme in Imported CSS](https://github.com/tailwindlabs/tailwindcss/issues/18966)
+- [GitHub Issue #19040 — @source and node_modules](https://github.com/tailwindlabs/tailwindcss/issues/19040)
+- [DaisyUI v5 Installation](https://daisyui.com/docs/install/)
+- [HeroUI Tailwind v4 Guide](https://www.heroui.com/docs/guide/tailwind-v4)
+- [shadcn/ui Tailwind v4 Docs](https://ui.shadcn.com/docs/tailwind-v4)
+- [Mantine CSS Modules](https://mantine.dev/styles/css-modules/)
diff --git a/src/theme/tokens.css b/src/theme/tokens.css
index 60408da..434853f 100644
--- a/src/theme/tokens.css
+++ b/src/theme/tokens.css
@@ -2,7 +2,7 @@
 
 @custom-variant dark (&:is(.dark *));
 
-@source "../components/**/*.{ts,tsx}";
+@source "../**/*.{ts,tsx}";
 
 /* ============================================================
  * PolicyEngine Design Tokens

From fb3641e515322947470204678f51c170ac838bd2 Mon Sep 17 00:00:00 2001
From: Anthony Volk <anth.volk@gmail.com>
Date: Fri, 13 Mar 2026 15:58:44 +0100
Subject: [PATCH 5/7] Expand component library, fix npm publishing, update demo

- Add 28 new primitives (Dialog, Sheet, Select, Accordion, Alert, etc.)
- Add layout components (Stack, Group, Container, Footer, HomeHeader)
- Expand Button, Badge, Card, Tabs with new variants
- Fix @source path: point to dist/**/*.js (published) instead of src/**/*.{ts,tsx} (not published)
- Add prepublishOnly and sideEffects fields for npm compatibility
- Update demo to showcase all ~60 components with proper CSS import chain

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 demo/Demo.tsx                                 | 1745 ++++++++++++-----
 demo/demo.css                                 |    2 +
 demo/main.tsx                                 |    2 +-
 package.json                                  |   15 +-
 src/assets/logos/index.ts                     |    4 +
 src/layout/Container.tsx                      |   49 +
 src/layout/Footer.tsx                         |  117 ++
 src/layout/Group.tsx                          |   66 +
 src/layout/Header.tsx                         |   25 +-
 src/layout/SidebarDivider.tsx                 |   22 +
 src/layout/SidebarNavItem.tsx                 |  136 ++
 src/layout/SidebarSection.tsx                 |   28 +
 src/layout/Stack.tsx                          |   58 +
 src/layout/homeHeader/HomeHeader.tsx          |  115 ++
 src/layout/homeHeader/HomeHeaderContent.tsx   |   90 +
 .../homeHeader/HomeHeaderCountrySelector.tsx  |  190 ++
 src/layout/homeHeader/HomeHeaderLogo.tsx      |   60 +
 .../homeHeader/HomeHeaderMobileMenu.tsx       |  199 ++
 src/layout/homeHeader/HomeHeaderNav.tsx       |   30 +
 src/layout/homeHeader/HomeHeaderNavItem.tsx   |  286 +++
 src/layout/homeHeader/index.ts                |    8 +
 src/layout/index.ts                           |   15 +-
 src/primitives/Accordion.tsx                  |   61 +
 src/primitives/Alert.tsx                      |   62 +
 src/primitives/Badge.tsx                      |    9 +-
 src/primitives/Button.tsx                     |   39 +-
 src/primitives/Card.tsx                       |   35 +-
 src/primitives/Checkbox.tsx                   |   26 +
 src/primitives/Collapsible.tsx                |   20 +
 src/primitives/Command.tsx                    |  164 ++
 src/primitives/Dialog.tsx                     |  144 ++
 src/primitives/DropdownMenu.tsx               |  225 +++
 src/primitives/Input.tsx                      |   20 +
 src/primitives/Label.tsx                      |   18 +
 src/primitives/Popover.tsx                    |   71 +
 src/primitives/Progress.tsx                   |   28 +
 src/primitives/RadioGroup.tsx                 |   42 +
 src/primitives/ScrollArea.tsx                 |   53 +
 src/primitives/SegmentedControl.tsx           |   55 +
 src/primitives/Select.tsx                     |  178 ++
 src/primitives/Separator.tsx                  |   25 +
 src/primitives/Sheet.tsx                      |  133 ++
 src/primitives/Skeleton.tsx                   |   14 +
 src/primitives/Spinner.tsx                    |   34 +
 src/primitives/Switch.tsx                     |   32 +
 src/primitives/Tabs.tsx                       |  193 +-
 src/primitives/Text.tsx                       |   64 +
 src/primitives/Textarea.tsx                   |   17 +
 src/primitives/Title.tsx                      |   34 +
 src/primitives/Tooltip.tsx                    |   50 +
 src/primitives/index.ts                       |   97 +
 src/theme/tokens.css                          |   33 +-
 52 files changed, 4593 insertions(+), 645 deletions(-)
 create mode 100644 demo/demo.css
 create mode 100644 src/layout/Container.tsx
 create mode 100644 src/layout/Footer.tsx
 create mode 100644 src/layout/Group.tsx
 create mode 100644 src/layout/SidebarDivider.tsx
 create mode 100644 src/layout/SidebarNavItem.tsx
 create mode 100644 src/layout/SidebarSection.tsx
 create mode 100644 src/layout/Stack.tsx
 create mode 100644 src/layout/homeHeader/HomeHeader.tsx
 create mode 100644 src/layout/homeHeader/HomeHeaderContent.tsx
 create mode 100644 src/layout/homeHeader/HomeHeaderCountrySelector.tsx
 create mode 100644 src/layout/homeHeader/HomeHeaderLogo.tsx
 create mode 100644 src/layout/homeHeader/HomeHeaderMobileMenu.tsx
 create mode 100644 src/layout/homeHeader/HomeHeaderNav.tsx
 create mode 100644 src/layout/homeHeader/HomeHeaderNavItem.tsx
 create mode 100644 src/layout/homeHeader/index.ts
 create mode 100644 src/primitives/Accordion.tsx
 create mode 100644 src/primitives/Alert.tsx
 create mode 100644 src/primitives/Checkbox.tsx
 create mode 100644 src/primitives/Collapsible.tsx
 create mode 100644 src/primitives/Command.tsx
 create mode 100644 src/primitives/Dialog.tsx
 create mode 100644 src/primitives/DropdownMenu.tsx
 create mode 100644 src/primitives/Input.tsx
 create mode 100644 src/primitives/Label.tsx
 create mode 100644 src/primitives/Popover.tsx
 create mode 100644 src/primitives/Progress.tsx
 create mode 100644 src/primitives/RadioGroup.tsx
 create mode 100644 src/primitives/ScrollArea.tsx
 create mode 100644 src/primitives/SegmentedControl.tsx
 create mode 100644 src/primitives/Select.tsx
 create mode 100644 src/primitives/Separator.tsx
 create mode 100644 src/primitives/Sheet.tsx
 create mode 100644 src/primitives/Skeleton.tsx
 create mode 100644 src/primitives/Spinner.tsx
 create mode 100644 src/primitives/Switch.tsx
 create mode 100644 src/primitives/Text.tsx
 create mode 100644 src/primitives/Textarea.tsx
 create mode 100644 src/primitives/Title.tsx
 create mode 100644 src/primitives/Tooltip.tsx

diff --git a/demo/Demo.tsx b/demo/Demo.tsx
index f96bf8c..0685867 100644
--- a/demo/Demo.tsx
+++ b/demo/Demo.tsx
@@ -1,4 +1,24 @@
 import { useState } from 'react';
+import {
+  Home,
+  Settings,
+  Users,
+  BarChart3,
+  FileText,
+  Bell,
+  Search,
+  Mail,
+  Calculator,
+  Globe,
+  ChevronDown,
+  ExternalLink,
+  Bold,
+  Italic,
+  Underline,
+  Copy,
+  Trash2,
+  PenLine,
+} from 'lucide-react';
 
 // Primitives
 import { Button } from '../src/primitives/Button';
@@ -9,9 +29,73 @@ import {
   CardDescription,
   CardContent,
   CardFooter,
+  CardAction,
 } from '../src/primitives/Card';
 import { Badge } from '../src/primitives/Badge';
 import { Tabs, TabsList, TabsTrigger, TabsContent } from '../src/primitives/Tabs';
+import { Text } from '../src/primitives/Text';
+import { Title } from '../src/primitives/Title';
+import { Spinner } from '../src/primitives/Spinner';
+import {
+  Dialog,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+  DialogClose,
+} from '../src/primitives/Dialog';
+import {
+  Sheet,
+  SheetTrigger,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+} from '../src/primitives/Sheet';
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '../src/primitives/Tooltip';
+import {
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectItem,
+  SelectGroup,
+  SelectLabel,
+} from '../src/primitives/Select';
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuLabel,
+} from '../src/primitives/DropdownMenu';
+import { Input } from '../src/primitives/Input';
+import { Label } from '../src/primitives/Label';
+import { Separator } from '../src/primitives/Separator';
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '../src/primitives/Accordion';
+import { Alert, AlertTitle, AlertDescription } from '../src/primitives/Alert';
+import { Popover, PopoverTrigger, PopoverContent } from '../src/primitives/Popover';
+import { Switch } from '../src/primitives/Switch';
+import { RadioGroup, RadioGroupItem } from '../src/primitives/RadioGroup';
+import { Checkbox } from '../src/primitives/Checkbox';
+import { ScrollArea } from '../src/primitives/ScrollArea';
+import { Skeleton } from '../src/primitives/Skeleton';
+import { Progress } from '../src/primitives/Progress';
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '../src/primitives/Collapsible';
+import { Textarea } from '../src/primitives/Textarea';
+import {
+  Command,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandSeparator,
+} from '../src/primitives/Command';
+import { SegmentedControl } from '../src/primitives/SegmentedControl';
 
 // Layout
 import { DashboardShell } from '../src/layout/DashboardShell';
@@ -20,6 +104,14 @@ import { SidebarLayout } from '../src/layout/SidebarLayout';
 import { SingleColumnLayout } from '../src/layout/SingleColumnLayout';
 import { InputPanel } from '../src/layout/InputPanel';
 import { ResultsPanel } from '../src/layout/ResultsPanel';
+import { Stack } from '../src/layout/Stack';
+import { Group } from '../src/layout/Group';
+import { Container } from '../src/layout/Container';
+import { SidebarNavItem } from '../src/layout/SidebarNavItem';
+import { SidebarSection } from '../src/layout/SidebarSection';
+import { SidebarDivider } from '../src/layout/SidebarDivider';
+import { Footer } from '../src/layout/Footer';
+import { HomeHeader } from '../src/layout/homeHeader';
 
 // Inputs
 import { CurrencyInput } from '../src/inputs/CurrencyInput';
@@ -151,6 +243,33 @@ const filingOptions = [
   { label: 'Head of household', value: 'hoh' },
 ];
 
+const homeHeaderNavItems = [
+  {
+    label: 'Policy',
+    href: '#',
+    children: [
+      { label: 'Compute your taxes', href: '#', description: 'See how policy changes affect your household' },
+      { label: 'Explore reforms', href: '#', description: 'Browse contributed policy reforms' },
+    ],
+  },
+  {
+    label: 'Research',
+    href: '#',
+    children: [
+      { label: 'Blog', href: '#', description: 'Latest analysis and updates' },
+      { label: 'Publications', href: '#', description: 'Academic papers and reports' },
+    ],
+  },
+  { label: 'About', href: '#' },
+  { label: 'Donate', href: '#' },
+];
+
+const homeHeaderCountries = [
+  { id: 'us', label: 'United States', flagEmoji: '\u{1F1FA}\u{1F1F8}' },
+  { id: 'uk', label: 'United Kingdom', flagEmoji: '\u{1F1EC}\u{1F1E7}' },
+  { id: 'ng', label: 'Nigeria', flagEmoji: '\u{1F1F3}\u{1F1EC}' },
+];
+
 // ---------------------------------------------------------------------------
 // Section wrapper
 // ---------------------------------------------------------------------------
@@ -201,554 +320,1150 @@ export function Demo() {
   const [includeState, setIncludeState] = useState(true);
   const [ubiAmount, setUbiAmount] = useState(500);
 
+  // New state for expanded primitives
+  const [switchOn, setSwitchOn] = useState(false);
+  const [radioValue, setRadioValue] = useState('option-1');
+  const [checkboxChecked, setCheckboxChecked] = useState(false);
+  const [segmentValue, setSegmentValue] = useState('household');
+  const [collapsibleOpen, setCollapsibleOpen] = useState(false);
+  const [selectValue, setSelectValue] = useState('');
+  const [progressValue] = useState(65);
+  const [homeCountry, setHomeCountry] = useState('us');
+
   return (
-    <DashboardShell>
-      <div className="max-w-6xl mx-auto px-6 py-8">
-        <div className="mb-10">
-          <h1 className="text-4xl font-bold text-foreground mb-2">
-            @policyengine/ui-kit
-          </h1>
-          <p className="text-lg text-muted-foreground">
-            Component gallery — every component rendered with example data
-          </p>
-        </div>
+    <TooltipProvider>
+      <DashboardShell>
+        <HomeHeader
+          navItems={homeHeaderNavItems}
+          countries={homeHeaderCountries}
+          currentCountry={homeCountry}
+          onCountryChange={setHomeCountry}
+          onNavigate={(href) => console.log('Navigate:', href)}
+        />
+        <div className="max-w-6xl mx-auto px-6 py-8">
+          <div className="mb-10">
+            <h1 className="text-4xl font-bold text-foreground mb-2">
+              @policyengine/ui-kit
+            </h1>
+            <p className="text-lg text-muted-foreground">
+              Component gallery — every component rendered with example data
+            </p>
+          </div>
 
-        {/* ================================================================ */}
-        {/* PRIMITIVES */}
-        {/* ================================================================ */}
-        <Section title="Primitives">
-          <SubSection title="Button">
-            <div className="flex flex-wrap gap-3 mb-4">
-              <Button variant="default">Default</Button>
-              <Button variant="outline">Outline</Button>
-              <Button variant="ghost">Ghost</Button>
-              <Button variant="destructive">Destructive</Button>
-            </div>
-            <div className="flex flex-wrap gap-3 mb-4">
-              <Button size="sm">Small</Button>
-              <Button size="default">Default</Button>
-              <Button size="lg">Large</Button>
-              <Button size="icon">+</Button>
-            </div>
-            <div className="flex flex-wrap gap-3">
-              <Button disabled>Disabled</Button>
-              <Button variant="outline" disabled>
-                Disabled outline
-              </Button>
-            </div>
-          </SubSection>
-
-          <SubSection title="Badge">
-            <div className="flex flex-wrap gap-3">
-              <Badge variant="default">Default</Badge>
-              <Badge variant="secondary">Secondary</Badge>
-              <Badge variant="outline">Outline</Badge>
-              <Badge variant="success">Success</Badge>
-              <Badge variant="warning">Warning</Badge>
-              <Badge variant="error">Error</Badge>
-            </div>
-          </SubSection>
+          {/* ================================================================ */}
+          {/* PRIMITIVES — Typography & Feedback */}
+          {/* ================================================================ */}
+          <Section title="Typography & Feedback">
+            <SubSection title="Text">
+              <Stack gap="sm">
+                <Text size="xs">Text size xs — Fine print and labels</Text>
+                <Text size="sm">Text size sm — Secondary content</Text>
+                <Text size="md">Text size md — Default body text</Text>
+                <Text size="lg">Text size lg — Emphasized content</Text>
+                <Text size="xl">Text size xl — Large callouts</Text>
+                <Group gap="lg">
+                  <Text fw={400}>Normal weight</Text>
+                  <Text fw={500}>Medium weight</Text>
+                  <Text fw={700}>Bold weight</Text>
+                  <Text c="dimmed">Dimmed color</Text>
+                </Group>
+              </Stack>
+            </SubSection>
 
-          <SubSection title="Card">
-            <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
-              <Card>
-                <CardHeader>
-                  <CardTitle>Universal Basic Income</CardTitle>
-                  <CardDescription>
-                    $500/month payment to every adult citizen
-                  </CardDescription>
-                </CardHeader>
-                <CardContent>
-                  <p className="text-sm text-muted-foreground">
-                    This reform would provide a monthly payment of $500 to every
-                    adult US citizen, funded through a combination of income tax
-                    increases and spending reductions.
-                  </p>
-                </CardContent>
-                <CardFooter>
-                  <Button size="sm">View details</Button>
-                  <Button variant="outline" size="sm" className="ml-2">
-                    Compare
-                  </Button>
-                </CardFooter>
-              </Card>
-              <Card>
-                <CardHeader>
-                  <CardTitle>Child Tax Credit expansion</CardTitle>
-                  <CardDescription>
-                    Increase CTC from $2,000 to $3,600 per child
-                  </CardDescription>
-                </CardHeader>
-                <CardContent>
-                  <p className="text-sm text-muted-foreground">
-                    Expanding the Child Tax Credit to $3,600 per child under 6
-                    and $3,000 for children 6-17, with full refundability for
-                    all qualifying families.
-                  </p>
-                </CardContent>
-                <CardFooter>
-                  <Button size="sm">View details</Button>
-                </CardFooter>
-              </Card>
-            </div>
-          </SubSection>
-
-          <SubSection title="Tabs">
-            <Tabs defaultValue="overview">
-              <TabsList>
-                <TabsTrigger value="overview">Overview</TabsTrigger>
-                <TabsTrigger value="distributional">
-                  Distributional impact
-                </TabsTrigger>
-                <TabsTrigger value="budget">Budget impact</TabsTrigger>
-              </TabsList>
-              <TabsContent value="overview">
-                <Card>
-                  <CardContent className="pt-4">
-                    <p className="text-sm text-muted-foreground">
-                      This tab shows the overview of the policy reform,
-                      including headline metrics and a summary of key impacts
-                      across income deciles.
-                    </p>
-                  </CardContent>
-                </Card>
-              </TabsContent>
-              <TabsContent value="distributional">
+            <SubSection title="Title">
+              <Stack gap="sm">
+                <Title order={1}>Title order 1 (h1)</Title>
+                <Title order={2}>Title order 2 (h2)</Title>
+                <Title order={3}>Title order 3 (h3)</Title>
+                <Title order={4}>Title order 4 (h4)</Title>
+                <Title order={5}>Title order 5 (h5)</Title>
+                <Title order={6}>Title order 6 (h6)</Title>
+              </Stack>
+            </SubSection>
+
+            <SubSection title="Spinner">
+              <Group gap="xl" align="center">
+                <Stack gap="xs" align="center">
+                  <Spinner size="sm" />
+                  <Text size="xs" c="dimmed">Small</Text>
+                </Stack>
+                <Stack gap="xs" align="center">
+                  <Spinner size="md" />
+                  <Text size="xs" c="dimmed">Medium</Text>
+                </Stack>
+                <Stack gap="xs" align="center">
+                  <Spinner size="lg" />
+                  <Text size="xs" c="dimmed">Large</Text>
+                </Stack>
+              </Group>
+            </SubSection>
+
+            <SubSection title="Alert">
+              <Stack gap="md">
+                <Alert>
+                  <AlertTitle>Default alert</AlertTitle>
+                  <AlertDescription>
+                    This is a default alert with no variant specified.
+                  </AlertDescription>
+                </Alert>
+                <Alert variant="destructive">
+                  <AlertTitle>Destructive alert</AlertTitle>
+                  <AlertDescription>
+                    Something went wrong with the simulation. Please check your inputs.
+                  </AlertDescription>
+                </Alert>
+              </Stack>
+            </SubSection>
+
+            <SubSection title="Skeleton">
+              <Stack gap="md">
+                <Skeleton className="h-4 w-[250px]" />
+                <Skeleton className="h-4 w-[200px]" />
+                <Skeleton className="h-4 w-[150px]" />
+                <Group gap="md">
+                  <Skeleton className="h-12 w-12 rounded-full" />
+                  <Stack gap="sm">
+                    <Skeleton className="h-4 w-[160px]" />
+                    <Skeleton className="h-3 w-[120px]" />
+                  </Stack>
+                </Group>
+              </Stack>
+            </SubSection>
+
+            <SubSection title="Progress">
+              <Stack gap="md">
+                <div>
+                  <Text size="sm" c="dimmed" className="mb-1">Simulation progress: {progressValue}%</Text>
+                  <Progress value={progressValue} />
+                </div>
+                <div>
+                  <Text size="sm" c="dimmed" className="mb-1">Loading data: 30%</Text>
+                  <Progress value={30} />
+                </div>
+              </Stack>
+            </SubSection>
+          </Section>
+
+          {/* ================================================================ */}
+          {/* PRIMITIVES — Buttons, Badges, Cards */}
+          {/* ================================================================ */}
+          <Section title="Buttons, Badges, Cards">
+            <SubSection title="Button — variants">
+              <div className="flex flex-wrap gap-3 mb-4">
+                <Button variant="default">Default</Button>
+                <Button variant="secondary">Secondary</Button>
+                <Button variant="outline">Outline</Button>
+                <Button variant="ghost">Ghost</Button>
+                <Button variant="link">Link</Button>
+                <Button variant="destructive">Destructive</Button>
+              </div>
+              <div className="flex flex-wrap gap-3 mb-4">
+                <Button size="xs">Extra small</Button>
+                <Button size="sm">Small</Button>
+                <Button size="default">Default</Button>
+                <Button size="lg">Large</Button>
+              </div>
+              <div className="flex flex-wrap gap-3 mb-4">
+                <Button size="icon-xs"><Search /></Button>
+                <Button size="icon-sm"><Search /></Button>
+                <Button size="icon"><Search /></Button>
+                <Button size="icon-lg"><Search /></Button>
+              </div>
+              <div className="flex flex-wrap gap-3">
+                <Button disabled>Disabled</Button>
+                <Button variant="outline" disabled>Disabled outline</Button>
+              </div>
+            </SubSection>
+
+            <SubSection title="Badge">
+              <div className="flex flex-wrap gap-3">
+                <Badge variant="default">Default</Badge>
+                <Badge variant="secondary">Secondary</Badge>
+                <Badge variant="outline">Outline</Badge>
+                <Badge variant="success">Success</Badge>
+                <Badge variant="warning">Warning</Badge>
+                <Badge variant="error">Error</Badge>
+                <Badge variant="ghost">Ghost</Badge>
+                <Badge variant="destructive">Destructive</Badge>
+              </div>
+            </SubSection>
+
+            <SubSection title="Card (with CardAction)">
+              <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
                 <Card>
-                  <CardContent className="pt-4">
+                  <CardHeader>
+                    <CardTitle>Universal Basic Income</CardTitle>
+                    <CardDescription>
+                      $500/month payment to every adult citizen
+                    </CardDescription>
+                    <CardAction>
+                      <Button variant="outline" size="sm">Edit</Button>
+                    </CardAction>
+                  </CardHeader>
+                  <CardContent>
                     <p className="text-sm text-muted-foreground">
-                      Distributional analysis shows how the reform affects
-                      different income groups, with the bottom 5 deciles
-                      gaining and the top 4 deciles bearing the net cost.
+                      This reform would provide a monthly payment of $500 to every
+                      adult US citizen, funded through a combination of income tax
+                      increases and spending reductions.
                     </p>
                   </CardContent>
+                  <CardFooter>
+                    <Button size="sm">View details</Button>
+                    <Button variant="outline" size="sm" className="ml-2">Compare</Button>
+                  </CardFooter>
                 </Card>
-              </TabsContent>
-              <TabsContent value="budget">
                 <Card>
-                  <CardContent className="pt-4">
+                  <CardHeader>
+                    <CardTitle>Child Tax Credit expansion</CardTitle>
+                    <CardDescription>
+                      Increase CTC from $2,000 to $3,600 per child
+                    </CardDescription>
+                  </CardHeader>
+                  <CardContent>
                     <p className="text-sm text-muted-foreground">
-                      The budget impact analysis estimates this reform would
-                      cost approximately $160 billion annually, partially
-                      offset by increased economic activity.
+                      Expanding the Child Tax Credit to $3,600 per child under 6
+                      and $3,000 for children 6-17, with full refundability.
                     </p>
                   </CardContent>
+                  <CardFooter>
+                    <Button size="sm">View details</Button>
+                  </CardFooter>
                 </Card>
-              </TabsContent>
-            </Tabs>
-          </SubSection>
-        </Section>
-
-        {/* ================================================================ */}
-        {/* LAYOUT */}
-        {/* ================================================================ */}
-        <Section title="Layout">
-          <SubSection title="Header (light)">
-            <Header
-              variant="light"
-              logo={
-                <img src={logos.tealWordmark} alt="PolicyEngine" className="h-5" />
-              }
-              actions={
-                <>
-                  <a href="#">Research</a>
-                  <a href="#">About</a>
-                  <a href="#">Donate</a>
-                  <Button size="sm">Sign in</Button>
-                </>
-              }
-            >
-              <span className="ml-2">
-                UBI Calculator
-              </span>
-            </Header>
-          </SubSection>
-
-          <SubSection title="Header (dark)">
-            <Header
-              variant="dark"
-              logo={
-                <img src={logos.whiteWordmark} alt="PolicyEngine" className="h-5" />
-              }
-              actions={
-                <>
-                  <a href="#">Research</a>
-                  <a href="#">About</a>
-                  <a href="#">Donate</a>
-                  <Button size="sm" className="bg-white text-teal-600 hover:bg-gray-100">Sign in</Button>
-                </>
-              }
-            >
-              <span className="ml-2">
-                Policy calculator
-              </span>
-            </Header>
-          </SubSection>
-
-          <SubSection title="PolicyEngine logos">
-            <div className="grid grid-cols-3 gap-4">
-              <Card>
-                <CardContent className="pt-4 flex flex-col items-center gap-2">
-                  <img src={logos.tealWordmark} alt="Teal wordmark (SVG)" className="h-6" />
-                  <span className="text-xs text-gray-400">tealWordmark</span>
-                </CardContent>
-              </Card>
-              <Card>
-                <CardContent className="pt-4 flex flex-col items-center gap-2">
-                  <img src={logos.tealWordmarkPng} alt="Teal wordmark (PNG)" className="h-6" />
-                  <span className="text-xs text-gray-400">tealWordmarkPng</span>
-                </CardContent>
-              </Card>
-              <Card className="bg-teal-600">
-                <CardContent className="pt-4 flex flex-col items-center gap-2">
-                  <img src={logos.whiteWordmark} alt="White wordmark (SVG)" className="h-6" />
-                  <span className="text-xs text-white/60">whiteWordmark</span>
-                </CardContent>
-              </Card>
-              <Card className="bg-teal-600">
-                <CardContent className="pt-4 flex flex-col items-center gap-2">
-                  <img src={logos.whiteWordmarkPng} alt="White wordmark (PNG)" className="h-6" />
-                  <span className="text-xs text-white/60">whiteWordmarkPng</span>
-                </CardContent>
-              </Card>
-              <Card>
-                <CardContent className="pt-4 flex flex-col items-center gap-2">
-                  <img src={logos.tealSquare} alt="Teal square (SVG)" className="h-10" />
-                  <span className="text-xs text-gray-400">tealSquare</span>
-                </CardContent>
-              </Card>
-              <Card>
-                <CardContent className="pt-4 flex flex-col items-center gap-2">
-                  <img src={logos.tealSquarePng} alt="Teal square (PNG)" className="h-10" />
-                  <span className="text-xs text-gray-400">tealSquarePng</span>
-                </CardContent>
-              </Card>
-              <Card>
-                <CardContent className="pt-4 flex flex-col items-center gap-2">
-                  <img src={logos.tealSquareTransparent} alt="Teal square transparent (PNG)" className="h-10" />
-                  <span className="text-xs text-gray-400">tealSquareTransparent</span>
+              </div>
+            </SubSection>
+
+            <SubSection title="Tabs (default + line variant)">
+              <Stack gap="lg">
+                <div>
+                  <Text size="sm" c="dimmed" className="mb-2">Default variant:</Text>
+                  <Tabs defaultValue="overview">
+                    <TabsList>
+                      <TabsTrigger value="overview">Overview</TabsTrigger>
+                      <TabsTrigger value="distributional">Distributional</TabsTrigger>
+                      <TabsTrigger value="budget">Budget</TabsTrigger>
+                    </TabsList>
+                    <TabsContent value="overview">
+                      <Card>
+                        <CardContent className="pt-4">
+                          <Text size="sm" c="dimmed">
+                            Overview of the policy reform with headline metrics.
+                          </Text>
+                        </CardContent>
+                      </Card>
+                    </TabsContent>
+                    <TabsContent value="distributional">
+                      <Card>
+                        <CardContent className="pt-4">
+                          <Text size="sm" c="dimmed">
+                            Distributional analysis across income groups.
+                          </Text>
+                        </CardContent>
+                      </Card>
+                    </TabsContent>
+                    <TabsContent value="budget">
+                      <Card>
+                        <CardContent className="pt-4">
+                          <Text size="sm" c="dimmed">
+                            Budget impact analysis with revenue projections.
+                          </Text>
+                        </CardContent>
+                      </Card>
+                    </TabsContent>
+                  </Tabs>
+                </div>
+                <div>
+                  <Text size="sm" c="dimmed" className="mb-2">Line variant:</Text>
+                  <Tabs defaultValue="household">
+                    <TabsList variant="line">
+                      <TabsTrigger value="household">Household</TabsTrigger>
+                      <TabsTrigger value="society">Society-wide</TabsTrigger>
+                    </TabsList>
+                    <TabsContent value="household">
+                      <Text size="sm" className="mt-2">Household-level impacts for selected parameters.</Text>
+                    </TabsContent>
+                    <TabsContent value="society">
+                      <Text size="sm" className="mt-2">Society-wide distributional and budgetary impacts.</Text>
+                    </TabsContent>
+                  </Tabs>
+                </div>
+              </Stack>
+            </SubSection>
+
+            <SubSection title="SegmentedControl">
+              <Group gap="xl">
+                <Stack gap="xs">
+                  <Text size="xs" c="dimmed">Size sm:</Text>
+                  <SegmentedControl
+                    value={segmentValue}
+                    onValueChange={setSegmentValue}
+                    options={[
+                      { label: 'Household', value: 'household' },
+                      { label: 'Society', value: 'society' },
+                    ]}
+                    size="sm"
+                  />
+                </Stack>
+                <Stack gap="xs">
+                  <Text size="xs" c="dimmed">Size xs:</Text>
+                  <SegmentedControl
+                    value={segmentValue}
+                    onValueChange={setSegmentValue}
+                    options={[
+                      { label: 'Household', value: 'household' },
+                      { label: 'Society', value: 'society' },
+                    ]}
+                    size="xs"
+                  />
+                </Stack>
+              </Group>
+            </SubSection>
+
+            <SubSection title="Separator">
+              <Stack gap="md">
+                <Text size="sm">Content above separator</Text>
+                <Separator />
+                <Text size="sm">Content below separator</Text>
+                <Group gap="md" align="center">
+                  <Text size="sm">Left</Text>
+                  <Separator orientation="vertical" className="h-6" />
+                  <Text size="sm">Center</Text>
+                  <Separator orientation="vertical" className="h-6" />
+                  <Text size="sm">Right</Text>
+                </Group>
+              </Stack>
+            </SubSection>
+          </Section>
+
+          {/* ================================================================ */}
+          {/* PRIMITIVES — Form Controls */}
+          {/* ================================================================ */}
+          <Section title="Form Controls (Radix Primitives)">
+            <SubSection title="Input + Label">
+              <Stack gap="md" className="max-w-sm">
+                <div>
+                  <Label htmlFor="demo-email">Email</Label>
+                  <Input id="demo-email" type="email" placeholder="you@example.com" className="mt-1" />
+                </div>
+                <div>
+                  <Label htmlFor="demo-name">Full name</Label>
+                  <Input id="demo-name" placeholder="Jane Doe" className="mt-1" />
+                </div>
+                <div>
+                  <Label htmlFor="demo-disabled">Disabled</Label>
+                  <Input id="demo-disabled" placeholder="Cannot edit" disabled className="mt-1" />
+                </div>
+              </Stack>
+            </SubSection>
+
+            <SubSection title="Textarea">
+              <div className="max-w-sm">
+                <Label htmlFor="demo-textarea">Description</Label>
+                <Textarea
+                  id="demo-textarea"
+                  placeholder="Describe your policy reform..."
+                  className="mt-1"
+                />
+              </div>
+            </SubSection>
+
+            <SubSection title="Select (Radix)">
+              <div className="max-w-sm">
+                <Label>Country</Label>
+                <Select value={selectValue} onValueChange={setSelectValue}>
+                  <SelectTrigger className="mt-1">
+                    <SelectValue placeholder="Select a country..." />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectGroup>
+                      <SelectLabel>North America</SelectLabel>
+                      <SelectItem value="us">United States</SelectItem>
+                      <SelectItem value="ca">Canada</SelectItem>
+                      <SelectItem value="mx">Mexico</SelectItem>
+                    </SelectGroup>
+                    <SelectGroup>
+                      <SelectLabel>Europe</SelectLabel>
+                      <SelectItem value="uk">United Kingdom</SelectItem>
+                      <SelectItem value="de">Germany</SelectItem>
+                      <SelectItem value="fr">France</SelectItem>
+                    </SelectGroup>
+                  </SelectContent>
+                </Select>
+              </div>
+            </SubSection>
+
+            <SubSection title="Switch">
+              <Stack gap="md">
+                <Group gap="md" align="center">
+                  <Switch
+                    id="demo-switch"
+                    checked={switchOn}
+                    onCheckedChange={setSwitchOn}
+                  />
+                  <Label htmlFor="demo-switch">
+                    Include state-level effects ({switchOn ? 'on' : 'off'})
+                  </Label>
+                </Group>
+                <Group gap="md" align="center">
+                  <Switch disabled />
+                  <Label className="text-muted-foreground">Disabled switch</Label>
+                </Group>
+              </Stack>
+            </SubSection>
+
+            <SubSection title="Checkbox (Radix)">
+              <Stack gap="md">
+                <Group gap="md" align="center">
+                  <Checkbox
+                    id="demo-checkbox"
+                    checked={checkboxChecked}
+                    onCheckedChange={(v) => setCheckboxChecked(v === true)}
+                  />
+                  <Label htmlFor="demo-checkbox">
+                    I agree to the terms of service
+                  </Label>
+                </Group>
+                <Group gap="md" align="center">
+                  <Checkbox disabled />
+                  <Label className="text-muted-foreground">Disabled checkbox</Label>
+                </Group>
+              </Stack>
+            </SubSection>
+
+            <SubSection title="RadioGroup">
+              <RadioGroup value={radioValue} onValueChange={setRadioValue}>
+                <Stack gap="sm">
+                  <Group gap="md" align="center">
+                    <RadioGroupItem value="option-1" id="radio-1" />
+                    <Label htmlFor="radio-1">Baseline scenario</Label>
+                  </Group>
+                  <Group gap="md" align="center">
+                    <RadioGroupItem value="option-2" id="radio-2" />
+                    <Label htmlFor="radio-2">Reform scenario</Label>
+                  </Group>
+                  <Group gap="md" align="center">
+                    <RadioGroupItem value="option-3" id="radio-3" />
+                    <Label htmlFor="radio-3">Custom scenario</Label>
+                  </Group>
+                </Stack>
+              </RadioGroup>
+            </SubSection>
+          </Section>
+
+          {/* ================================================================ */}
+          {/* PRIMITIVES — Overlays & Disclosure */}
+          {/* ================================================================ */}
+          <Section title="Overlays & Disclosure">
+            <SubSection title="Dialog">
+              <Dialog>
+                <DialogTrigger asChild>
+                  <Button variant="outline">Open dialog</Button>
+                </DialogTrigger>
+                <DialogContent>
+                  <DialogHeader>
+                    <DialogTitle>Confirm reform</DialogTitle>
+                    <DialogDescription>
+                      Are you sure you want to apply this reform? This will recalculate
+                      all household impacts with the new parameters.
+                    </DialogDescription>
+                  </DialogHeader>
+                  <DialogFooter>
+                    <DialogClose asChild>
+                      <Button variant="outline">Cancel</Button>
+                    </DialogClose>
+                    <DialogClose asChild>
+                      <Button>Apply reform</Button>
+                    </DialogClose>
+                  </DialogFooter>
+                </DialogContent>
+              </Dialog>
+            </SubSection>
+
+            <SubSection title="Sheet">
+              <Group gap="md">
+                <Sheet>
+                  <SheetTrigger asChild>
+                    <Button variant="outline">Open sheet (right)</Button>
+                  </SheetTrigger>
+                  <SheetContent side="right">
+                    <SheetHeader>
+                      <SheetTitle>Reform parameters</SheetTitle>
+                      <SheetDescription>
+                        Adjust the parameters for this policy reform.
+                      </SheetDescription>
+                    </SheetHeader>
+                    <div className="p-4">
+                      <Stack gap="md">
+                        <div>
+                          <Label>Reform name</Label>
+                          <Input placeholder="My reform" className="mt-1" />
+                        </div>
+                        <div>
+                          <Label>Description</Label>
+                          <Textarea placeholder="Describe the reform..." className="mt-1" />
+                        </div>
+                      </Stack>
+                    </div>
+                  </SheetContent>
+                </Sheet>
+                <Sheet>
+                  <SheetTrigger asChild>
+                    <Button variant="outline">Open sheet (left)</Button>
+                  </SheetTrigger>
+                  <SheetContent side="left">
+                    <SheetHeader>
+                      <SheetTitle>Navigation</SheetTitle>
+                    </SheetHeader>
+                    <div className="p-4">
+                      <Text size="sm" c="dimmed">Side navigation panel content</Text>
+                    </div>
+                  </SheetContent>
+                </Sheet>
+              </Group>
+            </SubSection>
+
+            <SubSection title="Tooltip">
+              <Group gap="lg">
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Button variant="outline">Hover me</Button>
+                  </TooltipTrigger>
+                  <TooltipContent>
+                    This button does something useful
+                  </TooltipContent>
+                </Tooltip>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Button variant="ghost" size="icon"><Bell /></Button>
+                  </TooltipTrigger>
+                  <TooltipContent>Notifications</TooltipContent>
+                </Tooltip>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <Button variant="ghost" size="icon"><Settings /></Button>
+                  </TooltipTrigger>
+                  <TooltipContent>Settings</TooltipContent>
+                </Tooltip>
+              </Group>
+            </SubSection>
+
+            <SubSection title="Popover">
+              <Popover>
+                <PopoverTrigger asChild>
+                  <Button variant="outline">Open popover</Button>
+                </PopoverTrigger>
+                <PopoverContent className="w-80">
+                  <Stack gap="md">
+                    <Text fw={500}>Filter results</Text>
+                    <div>
+                      <Label htmlFor="pop-income">Min income</Label>
+                      <Input id="pop-income" placeholder="$0" className="mt-1" />
+                    </div>
+                    <div>
+                      <Label htmlFor="pop-state">State</Label>
+                      <Input id="pop-state" placeholder="All states" className="mt-1" />
+                    </div>
+                    <Button size="sm">Apply filters</Button>
+                  </Stack>
+                </PopoverContent>
+              </Popover>
+            </SubSection>
+
+            <SubSection title="DropdownMenu">
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild>
+                  <Button variant="outline">
+                    Actions <ChevronDown className="ml-1 size-4" />
+                  </Button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent>
+                  <DropdownMenuLabel>Reform actions</DropdownMenuLabel>
+                  <DropdownMenuSeparator />
+                  <DropdownMenuItem>
+                    <Copy className="mr-2 size-4" /> Duplicate
+                  </DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <PenLine className="mr-2 size-4" /> Edit
+                  </DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <ExternalLink className="mr-2 size-4" /> Share
+                  </DropdownMenuItem>
+                  <DropdownMenuSeparator />
+                  <DropdownMenuItem variant="destructive">
+                    <Trash2 className="mr-2 size-4" /> Delete
+                  </DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </SubSection>
+
+            <SubSection title="Accordion">
+              <Accordion type="single" collapsible className="max-w-lg">
+                <AccordionItem value="item-1">
+                  <AccordionTrigger>What is PolicyEngine?</AccordionTrigger>
+                  <AccordionContent>
+                    PolicyEngine is a free, open-source platform for computing the
+                    impact of public policy on individuals and society.
+                  </AccordionContent>
+                </AccordionItem>
+                <AccordionItem value="item-2">
+                  <AccordionTrigger>How are simulations run?</AccordionTrigger>
+                  <AccordionContent>
+                    Simulations use microsimulation models that apply tax and benefit
+                    rules to representative household survey data.
+                  </AccordionContent>
+                </AccordionItem>
+                <AccordionItem value="item-3">
+                  <AccordionTrigger>Is the data accurate?</AccordionTrigger>
+                  <AccordionContent>
+                    PolicyEngine models are validated against official government
+                    projections and academic benchmarks.
+                  </AccordionContent>
+                </AccordionItem>
+              </Accordion>
+            </SubSection>
+
+            <SubSection title="Collapsible">
+              <Collapsible open={collapsibleOpen} onOpenChange={setCollapsibleOpen} className="max-w-lg">
+                <Group justify="apart" align="center">
+                  <Text fw={500}>Advanced options</Text>
+                  <CollapsibleTrigger asChild>
+                    <Button variant="ghost" size="sm">
+                      {collapsibleOpen ? 'Hide' : 'Show'}
+                    </Button>
+                  </CollapsibleTrigger>
+                </Group>
+                <CollapsibleContent>
+                  <Stack gap="sm" className="mt-2 rounded-md border p-4">
+                    <Text size="sm">Phase-in rate: 5%</Text>
+                    <Text size="sm">Phase-out threshold: $150,000</Text>
+                    <Text size="sm">Benefit reduction rate: 20%</Text>
+                  </Stack>
+                </CollapsibleContent>
+              </Collapsible>
+            </SubSection>
+
+            <SubSection title="ScrollArea">
+              <ScrollArea className="h-48 w-72 rounded-md border p-4">
+                <Stack gap="sm">
+                  {Array.from({ length: 20 }, (_, i) => (
+                    <Text key={i} size="sm">
+                      Item {i + 1} — Policy reform #{1000 + i}
+                    </Text>
+                  ))}
+                </Stack>
+              </ScrollArea>
+            </SubSection>
+
+            <SubSection title="Command">
+              <Card className="max-w-md">
+                <CardContent className="pt-4">
+                  <Command className="rounded-lg border">
+                    <CommandInput placeholder="Search policies..." />
+                    <CommandList>
+                      <CommandEmpty>No results found.</CommandEmpty>
+                      <CommandGroup heading="Suggestions">
+                        <CommandItem>
+                          <Calculator className="mr-2 size-4" />
+                          <span>Income tax calculator</span>
+                        </CommandItem>
+                        <CommandItem>
+                          <BarChart3 className="mr-2 size-4" />
+                          <span>Distributional analysis</span>
+                        </CommandItem>
+                        <CommandItem>
+                          <FileText className="mr-2 size-4" />
+                          <span>CTC reform</span>
+                        </CommandItem>
+                      </CommandGroup>
+                      <CommandSeparator />
+                      <CommandGroup heading="Settings">
+                        <CommandItem>
+                          <Users className="mr-2 size-4" />
+                          <span>Household parameters</span>
+                        </CommandItem>
+                        <CommandItem>
+                          <Settings className="mr-2 size-4" />
+                          <span>Simulation settings</span>
+                        </CommandItem>
+                      </CommandGroup>
+                    </CommandList>
+                  </Command>
                 </CardContent>
               </Card>
+            </SubSection>
+          </Section>
+
+          {/* ================================================================ */}
+          {/* LAYOUT — New components */}
+          {/* ================================================================ */}
+          <Section title="Layout">
+            <SubSection title="Stack + Group + Container">
               <Card>
-                <CardContent className="pt-4 flex flex-col items-center gap-2">
-                  <img src={logos.tealSquarePadded} alt="Teal square padded (SVG)" className="h-10" />
-                  <span className="text-xs text-gray-400">tealSquarePadded</span>
+                <CardContent className="pt-4">
+                  <Text size="sm" c="dimmed" className="mb-4">Stack (vertical), Group (horizontal), Container (centered max-width):</Text>
+                  <Container size="md">
+                    <Stack gap="md">
+                      <Group gap="md" justify="apart">
+                        <Badge>Tag 1</Badge>
+                        <Badge variant="secondary">Tag 2</Badge>
+                        <Badge variant="outline">Tag 3</Badge>
+                      </Group>
+                      <Group gap="sm" grow>
+                        <Button variant="outline" className="flex-1">Option A</Button>
+                        <Button variant="outline" className="flex-1">Option B</Button>
+                        <Button variant="outline" className="flex-1">Option C</Button>
+                      </Group>
+                    </Stack>
+                  </Container>
                 </CardContent>
               </Card>
-              <Card className="bg-teal-600">
-                <CardContent className="pt-4 flex flex-col items-center gap-2">
-                  <img src={logos.whiteSquare} alt="White square (SVG)" className="h-10" />
-                  <span className="text-xs text-white/60">whiteSquare</span>
+            </SubSection>
+
+            <SubSection title="HomeHeader">
+              <div className="border border-border rounded-lg overflow-hidden">
+                <HomeHeader
+                  navItems={homeHeaderNavItems}
+                  countries={homeHeaderCountries}
+                  currentCountry={homeCountry}
+                  onCountryChange={setHomeCountry}
+                  onNavigate={(href) => console.log('Navigate:', href)}
+                  styles={{ root: { position: 'relative' } }}
+                />
+              </div>
+            </SubSection>
+
+            <SubSection title="Header (light)">
+              <Header
+                variant="light"
+                logo={
+                  <img src={logos.tealWordmark} alt="PolicyEngine" className="h-5" />
+                }
+                actions={
+                  <>
+                    <a href="#">Research</a>
+                    <a href="#">About</a>
+                    <a href="#">Donate</a>
+                    <Button size="sm">Sign in</Button>
+                  </>
+                }
+              >
+                <span className="ml-2">UBI Calculator</span>
+              </Header>
+            </SubSection>
+
+            <SubSection title="Header (dark, with navLinks)">
+              <Header
+                variant="dark"
+                logo={
+                  <img src={logos.whiteWordmark} alt="PolicyEngine" className="h-5" />
+                }
+                navLinks={[
+                  { slug: 'research', text: 'Research', href: '#' },
+                  { slug: 'about', text: 'About', href: '#' },
+                  { slug: 'donate', text: 'Donate', href: '#' },
+                ]}
+                actions={
+                  <Button size="sm" className="bg-white text-teal-600 hover:bg-gray-100">Sign in</Button>
+                }
+              >
+                <span className="ml-2">Policy calculator</span>
+              </Header>
+            </SubSection>
+
+            <SubSection title="Sidebar components">
+              <Card className="max-w-[280px]">
+                <CardContent className="pt-4 px-0">
+                  <SidebarSection title="Main">
+                    <SidebarNavItem icon={Home} label="Dashboard" isActive />
+                    <SidebarNavItem icon={BarChart3} label="Analysis" />
+                    <SidebarNavItem icon={Calculator} label="Calculator" />
+                  </SidebarSection>
+                  <SidebarDivider />
+                  <SidebarSection title="Resources">
+                    <SidebarNavItem icon={FileText} label="Documentation" />
+                    <SidebarNavItem icon={Globe} label="API Reference" external />
+                    <SidebarNavItem icon={Mail} label="Contact" />
+                  </SidebarSection>
                 </CardContent>
               </Card>
-            </div>
-          </SubSection>
-
-          <SubSection title="SidebarLayout (with InputPanel + ResultsPanel)">
-            <div className="border border-border rounded-lg overflow-hidden h-[500px]">
-              <SidebarLayout
-                sidebar={
-                  <InputPanel title="Household parameters">
-                    <InputGroup label="Income">
-                      <CurrencyInput
-                        label="Annual household income"
-                        value={income}
-                        onChange={setIncome}
-                      />
-                    </InputGroup>
-                    <InputGroup label="Filing">
-                      <SelectInput
-                        label="Filing status"
-                        options={filingOptions}
-                        value={filing}
-                        onChange={setFiling}
+            </SubSection>
+
+            <SubSection title="PolicyEngine logos">
+              <div className="grid grid-cols-3 gap-4">
+                <Card>
+                  <CardContent className="pt-4 flex flex-col items-center gap-2">
+                    <img src={logos.tealWordmark} alt="Teal wordmark (SVG)" className="h-6" />
+                    <span className="text-xs text-gray-400">tealWordmark</span>
+                  </CardContent>
+                </Card>
+                <Card>
+                  <CardContent className="pt-4 flex flex-col items-center gap-2">
+                    <img src={logos.tealWordmarkPng} alt="Teal wordmark (PNG)" className="h-6" />
+                    <span className="text-xs text-gray-400">tealWordmarkPng</span>
+                  </CardContent>
+                </Card>
+                <Card className="bg-teal-600">
+                  <CardContent className="pt-4 flex flex-col items-center gap-2">
+                    <img src={logos.whiteWordmark} alt="White wordmark (SVG)" className="h-6" />
+                    <span className="text-xs text-white/60">whiteWordmark</span>
+                  </CardContent>
+                </Card>
+                <Card className="bg-teal-600">
+                  <CardContent className="pt-4 flex flex-col items-center gap-2">
+                    <img src={logos.whiteWordmarkPng} alt="White wordmark (PNG)" className="h-6" />
+                    <span className="text-xs text-white/60">whiteWordmarkPng</span>
+                  </CardContent>
+                </Card>
+                <Card>
+                  <CardContent className="pt-4 flex flex-col items-center gap-2">
+                    <img src={logos.tealSquare} alt="Teal square (SVG)" className="h-10" />
+                    <span className="text-xs text-gray-400">tealSquare</span>
+                  </CardContent>
+                </Card>
+                <Card>
+                  <CardContent className="pt-4 flex flex-col items-center gap-2">
+                    <img src={logos.tealSquarePng} alt="Teal square (PNG)" className="h-10" />
+                    <span className="text-xs text-gray-400">tealSquarePng</span>
+                  </CardContent>
+                </Card>
+                <Card>
+                  <CardContent className="pt-4 flex flex-col items-center gap-2">
+                    <img src={logos.tealSquareTransparent} alt="Teal square transparent (PNG)" className="h-10" />
+                    <span className="text-xs text-gray-400">tealSquareTransparent</span>
+                  </CardContent>
+                </Card>
+                <Card>
+                  <CardContent className="pt-4 flex flex-col items-center gap-2">
+                    <img src={logos.tealSquarePadded} alt="Teal square padded (SVG)" className="h-10" />
+                    <span className="text-xs text-gray-400">tealSquarePadded</span>
+                  </CardContent>
+                </Card>
+                <Card className="bg-teal-600">
+                  <CardContent className="pt-4 flex flex-col items-center gap-2">
+                    <img src={logos.whiteSquare} alt="White square (SVG)" className="h-10" />
+                    <span className="text-xs text-white/60">whiteSquare</span>
+                  </CardContent>
+                </Card>
+              </div>
+            </SubSection>
+
+            <SubSection title="SidebarLayout (with InputPanel + ResultsPanel)">
+              <div className="border border-border rounded-lg overflow-hidden h-[500px]">
+                <SidebarLayout
+                  sidebar={
+                    <InputPanel title="Household parameters">
+                      <InputGroup label="Income">
+                        <CurrencyInput
+                          label="Annual household income"
+                          value={income}
+                          onChange={setIncome}
+                        />
+                      </InputGroup>
+                      <InputGroup label="Filing">
+                        <SelectInput
+                          label="Filing status"
+                          options={filingOptions}
+                          value={filing}
+                          onChange={setFiling}
+                        />
+                        <SelectInput
+                          label="State"
+                          options={stateOptions}
+                          value={state}
+                          onChange={setState}
+                        />
+                      </InputGroup>
+                      <InputGroup label="Dependents">
+                        <NumberInput
+                          label="Number of dependents"
+                          value={dependents}
+                          onChange={setDependents}
+                          min={0}
+                          max={10}
+                        />
+                      </InputGroup>
+                    </InputPanel>
+                  }
+                >
+                  <ResultsPanel>
+                    <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
+                      <MetricCard
+                        label="Net income change"
+                        value={3200}
+                        format="currency"
+                        trend="positive"
+                        delta="+4.3% vs. baseline"
                       />
-                      <SelectInput
-                        label="State"
-                        options={stateOptions}
-                        value={state}
-                        onChange={setState}
+                      <MetricCard
+                        label="Effective tax rate"
+                        value={0.228}
+                        format="percent"
+                        trend="negative"
+                        delta="+3.1pp"
                       />
-                    </InputGroup>
-                    <InputGroup label="Dependents">
-                      <NumberInput
-                        label="Number of dependents"
-                        value={dependents}
-                        onChange={setDependents}
-                        min={0}
-                        max={10}
+                      <MetricCard
+                        label="Benefits received"
+                        value={6000}
+                        format="currency"
+                        trend="positive"
+                        delta="$500/mo UBI"
                       />
-                    </InputGroup>
-                  </InputPanel>
-                }
-              >
-                <ResultsPanel>
-                  <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
-                    <MetricCard
-                      label="Net income change"
-                      value={3200}
-                      format="currency"
-                      trend="positive"
-                      delta="+4.3% vs. baseline"
-                    />
-                    <MetricCard
-                      label="Effective tax rate"
-                      value={0.228}
-                      format="percent"
-                      trend="negative"
-                      delta="+3.1pp"
-                    />
-                    <MetricCard
-                      label="Benefits received"
-                      value={6000}
-                      format="currency"
-                      trend="positive"
-                      delta="$500/mo UBI"
+                    </div>
+                  </ResultsPanel>
+                </SidebarLayout>
+              </div>
+            </SubSection>
+
+            <SubSection title="SingleColumnLayout">
+              <div className="border border-border rounded-lg overflow-hidden">
+                <SingleColumnLayout maxWidth="700px">
+                  <h3 className="text-xl font-bold mb-4">Policy summary</h3>
+                  <SummaryText>
+                    This reform introduces a <strong>$500 monthly Universal
+                    Basic Income</strong> for all adult US citizens. The bottom
+                    50% of households would see a net income increase, while
+                    the top 30% would see a net decrease.
+                  </SummaryText>
+                </SingleColumnLayout>
+              </div>
+            </SubSection>
+
+            <SubSection title="Footer">
+              <div className="border border-border rounded-lg overflow-hidden">
+                <Footer
+                  links={[
+                    { href: '#', text: 'About' },
+                    { href: '#', text: 'Research' },
+                    { href: '#', text: 'Documentation' },
+                    { href: '#', text: 'API' },
+                  ]}
+                  socialLinks={[
+                    { icon: Mail, href: '#', label: 'Email' },
+                    { icon: ExternalLink, href: '#', label: 'GitHub' },
+                    { icon: Globe, href: '#', label: 'Website' },
+                  ]}
+                  copyrightText={`\u00A9 ${new Date().getFullYear()} PolicyEngine`}
+                />
+              </div>
+            </SubSection>
+          </Section>
+
+          {/* ================================================================ */}
+          {/* INPUTS */}
+          {/* ================================================================ */}
+          <Section title="Inputs">
+            <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+              <Card>
+                <CardContent className="pt-4">
+                  <div className="flex flex-col gap-4">
+                    <CurrencyInput
+                      label="Annual household income"
+                      value={income}
+                      onChange={setIncome}
                     />
-                  </div>
-                </ResultsPanel>
-              </SidebarLayout>
-            </div>
-          </SubSection>
-
-          <SubSection title="SingleColumnLayout">
-            <div className="border border-border rounded-lg overflow-hidden">
-              <SingleColumnLayout maxWidth="700px">
-                <h3 className="text-xl font-bold mb-4">
-                  Policy summary
-                </h3>
-                <SummaryText>
-                  This reform introduces a <strong>$500 monthly Universal
-                  Basic Income</strong> for all adult US citizens. The
-                  program would be funded through a combination of income
-                  tax surcharges on high earners and reductions in existing
-                  means-tested transfer programs. The bottom 50% of
-                  households would see a net income increase, while the top
-                  30% would see a net decrease.
-                </SummaryText>
-              </SingleColumnLayout>
-            </div>
-          </SubSection>
-        </Section>
-
-        {/* ================================================================ */}
-        {/* INPUTS */}
-        {/* ================================================================ */}
-        <Section title="Inputs">
-          <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
-            <Card>
-              <CardContent className="pt-4">
-                <div className="flex flex-col gap-4">
-                  <CurrencyInput
-                    label="Annual household income"
-                    value={income}
-                    onChange={setIncome}
-                  />
-                  <NumberInput
-                    label="Number of dependents"
-                    value={dependents}
-                    onChange={setDependents}
-                    min={0}
-                    max={10}
-                  />
-                  <SelectInput
-                    label="Filing status"
-                    options={filingOptions}
-                    value={filing}
-                    onChange={setFiling}
-                  />
-                  <SelectInput
-                    label="State of residence"
-                    options={stateOptions}
-                    value={state}
-                    onChange={setState}
-                    placeholder="Select a state..."
-                  />
-                </div>
-              </CardContent>
-            </Card>
-            <Card>
-              <CardContent className="pt-4">
-                <div className="flex flex-col gap-4">
-                  <CheckboxInput
-                    label="Include state-level tax effects"
-                    checked={includeState}
-                    onChange={setIncludeState}
-                  />
-                  <SliderInput
-                    label="Monthly UBI amount"
-                    value={ubiAmount}
-                    onChange={setUbiAmount}
-                    min={100}
-                    max={2000}
-                    step={50}
-                    formatValue={(v) => `$${v}`}
-                  />
-                  <InputGroup label="Reform parameters">
                     <NumberInput
-                      label="Phase-in rate (%)"
-                      value={5}
-                      onChange={() => {}}
+                      label="Number of dependents"
+                      value={dependents}
+                      onChange={setDependents}
                       min={0}
-                      max={100}
+                      max={10}
                     />
-                    <NumberInput
-                      label="Phase-out threshold ($)"
-                      value={150000}
-                      onChange={() => {}}
-                      min={0}
+                    <SelectInput
+                      label="Filing status"
+                      options={filingOptions}
+                      value={filing}
+                      onChange={setFiling}
+                    />
+                    <SelectInput
+                      label="State of residence"
+                      options={stateOptions}
+                      value={state}
+                      onChange={setState}
+                      placeholder="Select a state..."
                     />
+                  </div>
+                </CardContent>
+              </Card>
+              <Card>
+                <CardContent className="pt-4">
+                  <div className="flex flex-col gap-4">
                     <CheckboxInput
-                      label="Apply to non-citizens with work permits"
-                      checked={false}
-                      onChange={() => {}}
+                      label="Include state-level tax effects"
+                      checked={includeState}
+                      onChange={setIncludeState}
                     />
-                  </InputGroup>
-                </div>
-              </CardContent>
-            </Card>
-          </div>
-        </Section>
-
-        {/* ================================================================ */}
-        {/* DISPLAY */}
-        {/* ================================================================ */}
-        <Section title="Display">
-          <SubSection title="MetricCard">
-            <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
-              <MetricCard
-                label="Annual cost"
-                value={162000000000}
-                format="currency"
-              />
-              <MetricCard
-                label="Poverty reduction"
-                value={0.341}
-                format="percent"
-                trend="positive"
-                delta="12.1M people lifted"
-              />
-              <MetricCard
-                label="Gini coefficient change"
-                value="-0.038"
-                trend="positive"
-                delta="More equal"
-              />
-              <MetricCard
-                label="Cost per household"
-                value={4860}
-                format="currency"
-                trend="negative"
-                delta="+$405/mo avg tax"
-              />
+                    <SliderInput
+                      label="Monthly UBI amount"
+                      value={ubiAmount}
+                      onChange={setUbiAmount}
+                      min={100}
+                      max={2000}
+                      step={50}
+                      formatValue={(v) => `$${v}`}
+                    />
+                    <InputGroup label="Reform parameters">
+                      <NumberInput
+                        label="Phase-in rate (%)"
+                        value={5}
+                        onChange={() => {}}
+                        min={0}
+                        max={100}
+                      />
+                      <NumberInput
+                        label="Phase-out threshold ($)"
+                        value={150000}
+                        onChange={() => {}}
+                        min={0}
+                      />
+                      <CheckboxInput
+                        label="Apply to non-citizens with work permits"
+                        checked={false}
+                        onChange={() => {}}
+                      />
+                    </InputGroup>
+                  </div>
+                </CardContent>
+              </Card>
             </div>
-          </SubSection>
-
-          <SubSection title="SummaryText">
-            <SummaryText>
-              Under this reform, a married couple in California earning{' '}
-              <strong>{formatCurrency(income)}</strong> per year with{' '}
-              <strong>{dependents} dependents</strong> would receive{' '}
-              <strong>$12,000</strong> in annual UBI payments and pay an
-              additional <strong>$8,200</strong> in income taxes, for a{' '}
-              <strong className="text-teal-500">
-                net gain of $3,800
-              </strong>{' '}
-              per year.
-            </SummaryText>
-          </SubSection>
-
-          <SubSection title="DataTable">
-            <DataTable columns={tableColumns} data={tableData} />
-          </SubSection>
-
-          <SubSection title="PolicyEngineWatermark">
-            <PolicyEngineWatermark />
-          </SubSection>
-        </Section>
-
-        {/* ================================================================ */}
-        {/* CHARTS */}
-        {/* ================================================================ */}
-        <Section title="Charts">
-          <div className="grid grid-cols-1 gap-6">
-            <ChartContainer
-              title="Revenue sources vs. UBI cost"
-              subtitle="Billions of dollars, annual"
-              actions={
-                <Button variant="outline" size="sm">
-                  Download CSV
-                </Button>
-              }
-            >
-              <PEBarChart
-                data={barData}
-                xKey="category"
-                yKey="amount"
-                height={350}
-                colorByValue
-                formatTooltip={(v) => `$${v}B`}
-              />
-              <PolicyEngineWatermark />
-            </ChartContainer>
-
-            <ChartContainer
-              title="Poverty rate projections"
-              subtitle="Percentage of population below poverty line, 2024-2033"
-            >
-              <PELineChart
-                data={lineData}
-                xKey="year"
-                series={[
-                  {
-                    dataKey: 'baseline',
-                    name: 'Baseline',
-                    color: 'var(--gray-400)',
-                    strokeDasharray: '5 5',
-                  },
-                  { dataKey: 'reform', name: 'With UBI reform' },
-                ]}
-                height={350}
-                formatTooltip={(v) => `${v.toFixed(1)}%`}
-              />
-              <PolicyEngineWatermark />
-            </ChartContainer>
-
-            <ChartContainer
-              title="Tax burden by income decile"
-              subtitle="Average annual amount per household"
-            >
-              <PEAreaChart
-                data={areaData}
-                xKey="decile"
-                series={[
-                  { dataKey: 'income_tax', name: 'Income tax' },
-                  { dataKey: 'payroll_tax', name: 'Payroll tax' },
-                ]}
-                height={350}
-                formatTooltip={(v) => formatCurrency(v)}
-              />
-              <PolicyEngineWatermark />
-            </ChartContainer>
-
-            <ChartContainer
-              title="Budget impact waterfall"
-              subtitle="Net fiscal impact of UBI reform (billions)"
-            >
-              <PEWaterfallChart
-                data={waterfallData}
-                height={350}
-                formatTooltip={(v) => `$${v}B`}
-              />
+          </Section>
+
+          {/* ================================================================ */}
+          {/* DISPLAY */}
+          {/* ================================================================ */}
+          <Section title="Display">
+            <SubSection title="MetricCard">
+              <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+                <MetricCard
+                  label="Annual cost"
+                  value={162000000000}
+                  format="currency"
+                />
+                <MetricCard
+                  label="Poverty reduction"
+                  value={0.341}
+                  format="percent"
+                  trend="positive"
+                  delta="12.1M people lifted"
+                />
+                <MetricCard
+                  label="Gini coefficient change"
+                  value="-0.038"
+                  trend="positive"
+                  delta="More equal"
+                />
+                <MetricCard
+                  label="Cost per household"
+                  value={4860}
+                  format="currency"
+                  trend="negative"
+                  delta="+$405/mo avg tax"
+                />
+              </div>
+            </SubSection>
+
+            <SubSection title="SummaryText">
+              <SummaryText>
+                Under this reform, a married couple in California earning{' '}
+                <strong>{formatCurrency(income)}</strong> per year with{' '}
+                <strong>{dependents} dependents</strong> would receive{' '}
+                <strong>$12,000</strong> in annual UBI payments and pay an
+                additional <strong>$8,200</strong> in income taxes, for a{' '}
+                <strong className="text-teal-500">
+                  net gain of $3,800
+                </strong>{' '}
+                per year.
+              </SummaryText>
+            </SubSection>
+
+            <SubSection title="DataTable">
+              <DataTable columns={tableColumns} data={tableData} />
+            </SubSection>
+
+            <SubSection title="PolicyEngineWatermark">
               <PolicyEngineWatermark />
-            </ChartContainer>
-          </div>
-        </Section>
+            </SubSection>
+          </Section>
+
+          {/* ================================================================ */}
+          {/* CHARTS */}
+          {/* ================================================================ */}
+          <Section title="Charts">
+            <div className="grid grid-cols-1 gap-6">
+              <ChartContainer
+                title="Revenue sources vs. UBI cost"
+                subtitle="Billions of dollars, annual"
+                actions={
+                  <Button variant="outline" size="sm">Download CSV</Button>
+                }
+              >
+                <PEBarChart
+                  data={barData}
+                  xKey="category"
+                  yKey="amount"
+                  height={350}
+                  colorByValue
+                  formatTooltip={(v) => `$${v}B`}
+                />
+                <PolicyEngineWatermark />
+              </ChartContainer>
+
+              <ChartContainer
+                title="Poverty rate projections"
+                subtitle="Percentage of population below poverty line, 2024-2033"
+              >
+                <PELineChart
+                  data={lineData}
+                  xKey="year"
+                  series={[
+                    {
+                      dataKey: 'baseline',
+                      name: 'Baseline',
+                      color: 'var(--gray-400)',
+                      strokeDasharray: '5 5',
+                    },
+                    { dataKey: 'reform', name: 'With UBI reform' },
+                  ]}
+                  height={350}
+                  formatTooltip={(v) => `${v.toFixed(1)}%`}
+                />
+                <PolicyEngineWatermark />
+              </ChartContainer>
 
-        <div className="text-center py-8 text-sm text-gray-400">
-          @policyengine/ui-kit v0.1.0 — All components shown with example data
+              <ChartContainer
+                title="Tax burden by income decile"
+                subtitle="Average annual amount per household"
+              >
+                <PEAreaChart
+                  data={areaData}
+                  xKey="decile"
+                  series={[
+                    { dataKey: 'income_tax', name: 'Income tax' },
+                    { dataKey: 'payroll_tax', name: 'Payroll tax' },
+                  ]}
+                  height={350}
+                  formatTooltip={(v) => formatCurrency(v)}
+                />
+                <PolicyEngineWatermark />
+              </ChartContainer>
+
+              <ChartContainer
+                title="Budget impact waterfall"
+                subtitle="Net fiscal impact of UBI reform (billions)"
+              >
+                <PEWaterfallChart
+                  data={waterfallData}
+                  height={350}
+                  formatTooltip={(v) => `$${v}B`}
+                />
+                <PolicyEngineWatermark />
+              </ChartContainer>
+            </div>
+          </Section>
+
+          <div className="text-center py-8 text-sm text-gray-400">
+            @policyengine/ui-kit — All components shown with example data
+          </div>
         </div>
-      </div>
-    </DashboardShell>
+      </DashboardShell>
+    </TooltipProvider>
   );
 }
diff --git a/demo/demo.css b/demo/demo.css
new file mode 100644
index 0000000..153f872
--- /dev/null
+++ b/demo/demo.css
@@ -0,0 +1,2 @@
+@import "tailwindcss";
+@import "../src/theme/tokens.css";
diff --git a/demo/main.tsx b/demo/main.tsx
index 46805e0..fa620d6 100644
--- a/demo/main.tsx
+++ b/demo/main.tsx
@@ -1,6 +1,6 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import '../src/theme/tokens.css';
+import './demo.css';
 import { Demo } from './Demo';
 
 createRoot(document.getElementById('root')!).render(
diff --git a/package.json b/package.json
index ed9a660..1984daf 100644
--- a/package.json
+++ b/package.json
@@ -12,11 +12,13 @@
       "require": "./dist/index.cjs"
     },
     "./styles.css": "./dist/styles.css",
-    "./theme.css": "./src/theme/tokens.css"
+    "./theme.css": "./src/theme/tokens.css",
+    "./favicon.svg": "./src/assets/logos/policyengine/teal-square.svg"
   },
   "files": [
     "dist",
-    "src/theme"
+    "src/theme",
+    "src/assets"
   ],
   "scripts": {
     "dev": "vite",
@@ -25,8 +27,12 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
   },
+  "sideEffects": [
+    "**/*.css"
+  ],
   "peerDependencies": {
     "react": ">=19",
     "react-dom": ">=19",
@@ -35,7 +41,10 @@
   "dependencies": {
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "dayjs": "^1.11.13",
     "lucide-react": "^0.577.0",
+    "radix-ui": "^1.4.3",
     "tailwind-merge": "^3.5.0",
     "tw-animate-css": "^1.4.0"
   },
diff --git a/src/assets/logos/index.ts b/src/assets/logos/index.ts
index 0cdb483..5121be0 100644
--- a/src/assets/logos/index.ts
+++ b/src/assets/logos/index.ts
@@ -18,4 +18,8 @@ export const logos = {
   whiteWordmark,
   whiteWordmarkPng,
   whiteSquare,
+  /** Alias for teal-square SVG — use as favicon href */
+  favicon: tealSquare,
+  /** Alias for teal-square PNG — favicon fallback */
+  faviconPng: tealSquarePng,
 } as const;
diff --git a/src/layout/Container.tsx b/src/layout/Container.tsx
new file mode 100644
index 0000000..d533676
--- /dev/null
+++ b/src/layout/Container.tsx
@@ -0,0 +1,49 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import { cn } from '../utils/cn';
+
+const sizeMap = {
+  xs: 'max-w-screen-xs',
+  sm: 'max-w-screen-sm',
+  md: 'max-w-screen-md',
+  lg: 'max-w-screen-lg',
+  xl: 'max-w-screen-xl',
+  '2xl': 'max-w-screen-2xl',
+} as const;
+
+export interface ContainerProps extends HTMLAttributes<HTMLDivElement> {
+  size?: keyof typeof sizeMap;
+  variant?: 'guttered';
+  styles?: { root?: React.CSSProperties };
+}
+
+export const Container = forwardRef<HTMLDivElement, ContainerProps>(
+  ({ className, size, variant, styles, children, style, ...props }, ref) => {
+    // spacing.container['2xl'] = 80px, spacing.container.lg = 48px
+    const gutteredStyle =
+      variant === 'guttered'
+        ? {
+            paddingLeft: '80px',
+            paddingRight: '80px',
+            paddingTop: '48px',
+            paddingBottom: '48px',
+          }
+        : undefined;
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'mx-auto w-full',
+          variant !== 'guttered' && 'px-4',
+          size ? sizeMap[size] : 'max-w-[976px]',
+          className,
+        )}
+        style={{ ...gutteredStyle, ...styles?.root, ...style }}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+Container.displayName = 'Container';
diff --git a/src/layout/Footer.tsx b/src/layout/Footer.tsx
new file mode 100644
index 0000000..fe8b6f0
--- /dev/null
+++ b/src/layout/Footer.tsx
@@ -0,0 +1,117 @@
+import { forwardRef, type HTMLAttributes, type ComponentType, type ReactNode } from 'react';
+import { cn } from '../utils/cn';
+import { Stack } from './Stack';
+import { Container } from './Container';
+import whiteWordmark from '../assets/logos/policyengine/white.svg';
+
+export interface FooterProps extends HTMLAttributes<HTMLElement> {
+  /** Navigation links rendered in the left column */
+  links?: { href: string; text: string }[];
+  /** Social media icon links */
+  socialLinks?: {
+    icon: ComponentType<{ size?: number }>;
+    href: string;
+    label: string;
+    onClick?: () => void;
+  }[];
+  /** Custom logo element — overrides logoSrc */
+  logo?: ReactNode;
+  /** Logo image URL — defaults to bundled white PolicyEngine wordmark */
+  logoSrc?: string;
+  /** Slot for a subscribe form or any content in the right column */
+  subscribeSlot?: ReactNode;
+  /** Copyright text override */
+  copyrightText?: string;
+  styles?: { root?: React.CSSProperties };
+}
+
+export const Footer = forwardRef<HTMLElement, FooterProps>(
+  (
+    {
+      links,
+      socialLinks,
+      logo,
+      logoSrc,
+      subscribeSlot,
+      copyrightText,
+      className,
+      styles,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const resolvedLogo = logo ?? (
+      <img
+        src={logoSrc ?? whiteWordmark}
+        alt="PolicyEngine"
+        className="h-[52px] w-auto"
+      />
+    );
+
+    const resolvedCopyright =
+      copyrightText ?? `\u00A9 ${new Date().getFullYear()} PolicyEngine`;
+
+    return (
+      <footer
+        ref={ref}
+        className={cn('w-full', className)}
+        style={{
+          padding: '48px 64px',
+          background:
+            'linear-gradient(to right, var(--color-teal-800, #234E52), var(--color-teal-600, #2C7A7B))',
+          ...styles?.root,
+        }}
+        {...props}
+      >
+        <Container size="2xl">
+          {resolvedLogo}
+          <div className="grid grid-cols-1 md:grid-cols-2 mt-8 gap-12">
+            <Stack gap="2xl" align="start">
+              {links && links.length > 0 && (
+                <Stack gap="xs">
+                  {links.map(({ href, text }) => (
+                    <a
+                      key={href}
+                      href={href}
+                      className="text-white text-base no-underline font-sans"
+                    >
+                      {text}
+                    </a>
+                  ))}
+                </Stack>
+              )}
+
+              <Stack gap="md">
+                {socialLinks && socialLinks.length > 0 && (
+                  <div className="flex flex-row items-center gap-3">
+                    {socialLinks.map(({ icon: Icon, href, label, onClick }) => (
+                      <a
+                        key={href}
+                        href={href}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        aria-label={label}
+                        className="text-white"
+                        onClick={onClick}
+                      >
+                        <Icon size={24} />
+                      </a>
+                    ))}
+                  </div>
+                )}
+                <p className="text-xs text-white m-0 font-sans">
+                  {resolvedCopyright}
+                </p>
+              </Stack>
+            </Stack>
+
+            {subscribeSlot}
+          </div>
+          {children}
+        </Container>
+      </footer>
+    );
+  },
+);
+Footer.displayName = 'Footer';
diff --git a/src/layout/Group.tsx b/src/layout/Group.tsx
new file mode 100644
index 0000000..7d7f292
--- /dev/null
+++ b/src/layout/Group.tsx
@@ -0,0 +1,66 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import { cn } from '../utils/cn';
+
+const gapMap = {
+  xs: 'gap-1',
+  sm: 'gap-2',
+  md: 'gap-3',
+  lg: 'gap-4',
+  xl: 'gap-5',
+  '2xl': 'gap-6',
+  '3xl': 'gap-8',
+  '4xl': 'gap-12',
+  '5xl': 'gap-16',
+} as const;
+
+const justifyMap = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end',
+  'space-between': 'justify-between',
+  apart: 'justify-between',
+} as const;
+
+const alignMap = {
+  start: 'items-start',
+  center: 'items-center',
+  end: 'items-end',
+  stretch: 'items-stretch',
+  baseline: 'items-baseline',
+} as const;
+
+export interface GroupProps extends HTMLAttributes<HTMLDivElement> {
+  gap?: keyof typeof gapMap;
+  justify?: keyof typeof justifyMap;
+  align?: keyof typeof alignMap;
+  wrap?: 'wrap' | 'nowrap';
+  grow?: boolean;
+  styles?: { root?: React.CSSProperties };
+}
+
+export const Group = forwardRef<HTMLDivElement, GroupProps>(
+  (
+    { className, gap = 'md', justify, align = 'center', wrap = 'wrap', grow, styles, children, ...props },
+    ref,
+  ) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'flex flex-row',
+          gapMap[gap],
+          justifyMap[justify ?? 'start'],
+          alignMap[align],
+          wrap === 'wrap' ? 'flex-wrap' : 'flex-nowrap',
+          grow && '[&>*]:flex-1',
+          className,
+        )}
+        style={styles?.root}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+Group.displayName = 'Group';
diff --git a/src/layout/Header.tsx b/src/layout/Header.tsx
index 88cd99f..87fc19f 100644
--- a/src/layout/Header.tsx
+++ b/src/layout/Header.tsx
@@ -43,16 +43,28 @@ const subtitleVariants = cva(
   },
 );
 
+export interface HeaderNavLink {
+  /** Display text */
+  text: string;
+  /** URL slug for identification (e.g., "research") */
+  slug: string;
+  /** Where to navigate — a full URL (external) or a path (internal) */
+  href: string;
+}
+
 export interface HeaderProps
   extends HTMLAttributes<HTMLElement>,
     VariantProps<typeof headerVariants> {
   logo?: ReactNode;
+  /** Structured navigation links rendered in the actions area */
+  navLinks?: HeaderNavLink[];
+  /** Additional actions rendered after navLinks (e.g., sign-in button) */
   actions?: ReactNode;
   styles?: { root?: React.CSSProperties };
 }
 
 export const Header = forwardRef<HTMLElement, HeaderProps>(
-  ({ logo, actions, variant, className, styles, children, ...props }, ref) => (
+  ({ logo, navLinks, actions, variant, className, styles, children, ...props }, ref) => (
     <header
       ref={ref}
       className={cn(headerVariants({ variant }), className)}
@@ -63,10 +75,15 @@ export const Header = forwardRef<HTMLElement, HeaderProps>(
         {logo}
         {children}
       </div>
-      {actions && (
-        <div className={cn(actionsVariants({ variant }))}>
+      {(navLinks || actions) && (
+        <nav className={cn(actionsVariants({ variant }))}>
+          {navLinks?.map((link) => (
+            <a key={link.slug} href={link.href}>
+              {link.text}
+            </a>
+          ))}
           {actions}
-        </div>
+        </nav>
       )}
     </header>
   ),
diff --git a/src/layout/SidebarDivider.tsx b/src/layout/SidebarDivider.tsx
new file mode 100644
index 0000000..5b79a55
--- /dev/null
+++ b/src/layout/SidebarDivider.tsx
@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { cn } from '../utils/cn';
+
+interface SidebarDividerProps {
+  className?: string;
+}
+
+const SidebarDivider = React.forwardRef<HTMLHRElement, SidebarDividerProps>(
+  ({ className }, ref) => {
+    return (
+      <hr
+        ref={ref}
+        className={cn('mx-4 border-border-light', className)}
+      />
+    );
+  },
+);
+
+SidebarDivider.displayName = 'SidebarDivider';
+
+export { SidebarDivider };
+export type { SidebarDividerProps };
diff --git a/src/layout/SidebarNavItem.tsx b/src/layout/SidebarNavItem.tsx
new file mode 100644
index 0000000..a4dfd76
--- /dev/null
+++ b/src/layout/SidebarNavItem.tsx
@@ -0,0 +1,136 @@
+import * as React from 'react';
+import { ExternalLink } from 'lucide-react';
+import { Tooltip, TooltipContent, TooltipTrigger } from '../primitives/Tooltip';
+import { cn } from '../utils/cn';
+
+interface SidebarNavItemProps {
+  label: string;
+  icon?: React.ComponentType<{ className?: string }>;
+  href: string;
+  isActive?: boolean;
+  external?: boolean;
+  disabled?: boolean;
+  linkComponent?: React.ElementType;
+  className?: string;
+}
+
+const SidebarNavItem = React.forwardRef<HTMLDivElement, SidebarNavItemProps>(
+  (
+    {
+      label,
+      icon: Icon,
+      href,
+      isActive = false,
+      external = false,
+      disabled = false,
+      linkComponent: LinkComponent,
+      className,
+    },
+    ref,
+  ) => {
+    const content = (
+      <div className="flex items-center gap-5 flex-nowrap">
+        {Icon && (
+          <Icon
+            className={cn(
+              'size-5 shrink-0',
+              disabled
+                ? 'text-gray-400'
+                : isActive
+                  ? 'text-gray-700'
+                  : 'text-muted-foreground',
+            )}
+          />
+        )}
+        <span
+          className={cn(
+            'flex-1 text-sm',
+            isActive ? 'font-medium' : 'font-normal',
+            disabled
+              ? 'text-gray-400'
+              : isActive
+                ? 'text-gray-900'
+                : 'text-gray-700',
+          )}
+        >
+          {label}
+        </span>
+        {external && (
+          <ExternalLink
+            className={cn(
+              'size-3.5 shrink-0',
+              disabled ? 'text-gray-400' : 'text-muted-foreground',
+            )}
+          />
+        )}
+      </div>
+    );
+
+    const sharedClassName = cn(
+      'block w-full rounded-element no-underline',
+      'px-3 py-2',
+      isActive ? 'bg-gray-50' : 'bg-transparent',
+      disabled ? 'cursor-not-allowed opacity-60' : 'cursor-pointer hover:bg-gray-50',
+      className,
+    );
+
+    if (disabled) {
+      return (
+        <div ref={ref}>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                className={cn(sharedClassName, 'border-none text-left')}
+                onClick={(e) => e.preventDefault()}
+              >
+                {content}
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="right">Under development</TooltipContent>
+          </Tooltip>
+        </div>
+      );
+    }
+
+    if (external) {
+      return (
+        <div ref={ref}>
+          <a
+            href={href}
+            target="_blank"
+            rel="noopener noreferrer"
+            className={sharedClassName}
+          >
+            {content}
+          </a>
+        </div>
+      );
+    }
+
+    // Use custom link component if provided (e.g., react-router Link, Next.js Link)
+    if (LinkComponent) {
+      return (
+        <div ref={ref}>
+          <LinkComponent to={href} href={href} className={sharedClassName}>
+            {content}
+          </LinkComponent>
+        </div>
+      );
+    }
+
+    // Default: plain <a> tag
+    return (
+      <div ref={ref}>
+        <a href={href} className={sharedClassName}>
+          {content}
+        </a>
+      </div>
+    );
+  },
+);
+
+SidebarNavItem.displayName = 'SidebarNavItem';
+
+export { SidebarNavItem };
+export type { SidebarNavItemProps };
diff --git a/src/layout/SidebarSection.tsx b/src/layout/SidebarSection.tsx
new file mode 100644
index 0000000..3b0aac0
--- /dev/null
+++ b/src/layout/SidebarSection.tsx
@@ -0,0 +1,28 @@
+import * as React from 'react';
+import { cn } from '../utils/cn';
+
+interface SidebarSectionProps {
+  title?: string;
+  children: React.ReactNode;
+  className?: string;
+}
+
+const SidebarSection = React.forwardRef<HTMLDivElement, SidebarSectionProps>(
+  ({ title, children, className }, ref) => {
+    return (
+      <div ref={ref} className={cn('flex flex-col gap-1 px-2 py-2', className)}>
+        {title && (
+          <span className="px-3 pb-1 text-xs leading-normal font-medium text-muted-foreground">
+            {title}
+          </span>
+        )}
+        <div className="flex flex-col gap-0.5">{children}</div>
+      </div>
+    );
+  },
+);
+
+SidebarSection.displayName = 'SidebarSection';
+
+export { SidebarSection };
+export type { SidebarSectionProps };
diff --git a/src/layout/Stack.tsx b/src/layout/Stack.tsx
new file mode 100644
index 0000000..2587e81
--- /dev/null
+++ b/src/layout/Stack.tsx
@@ -0,0 +1,58 @@
+import { forwardRef, type HTMLAttributes } from 'react';
+import { cn } from '../utils/cn';
+
+const gapMap = {
+  xs: 'gap-1',
+  sm: 'gap-2',
+  md: 'gap-3',
+  lg: 'gap-4',
+  xl: 'gap-5',
+  '2xl': 'gap-6',
+  '3xl': 'gap-8',
+  '4xl': 'gap-12',
+  '5xl': 'gap-16',
+} as const;
+
+const alignMap = {
+  start: 'items-start',
+  center: 'items-center',
+  end: 'items-end',
+  stretch: 'items-stretch',
+} as const;
+
+const justifyMap = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end',
+  'space-between': 'justify-between',
+  'space-around': 'justify-around',
+} as const;
+
+export interface StackProps extends HTMLAttributes<HTMLDivElement> {
+  gap?: keyof typeof gapMap;
+  align?: keyof typeof alignMap;
+  justify?: keyof typeof justifyMap;
+  styles?: { root?: React.CSSProperties };
+}
+
+export const Stack = forwardRef<HTMLDivElement, StackProps>(
+  ({ className, gap = 'md', align, justify, styles, children, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'flex flex-col',
+          gapMap[gap],
+          align && alignMap[align],
+          justify && justifyMap[justify],
+          className,
+        )}
+        style={styles?.root}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+Stack.displayName = 'Stack';
diff --git a/src/layout/homeHeader/HomeHeader.tsx b/src/layout/homeHeader/HomeHeader.tsx
new file mode 100644
index 0000000..b9c04bd
--- /dev/null
+++ b/src/layout/homeHeader/HomeHeader.tsx
@@ -0,0 +1,115 @@
+import { forwardRef, useState } from 'react';
+import { cn } from '../../utils/cn';
+import { HomeHeaderContent } from './HomeHeaderContent';
+
+export interface NavItemConfig {
+  label: string;
+  href: string;
+  children?: { label: string; href: string; description?: string }[];
+}
+
+export interface CountryConfig {
+  id: string;
+  label: string;
+  flagEmoji?: string;
+}
+
+export interface HomeHeaderProps {
+  /** Navigation items — simple links or items with dropdown children */
+  navItems: NavItemConfig[];
+  /** Available countries for the country selector */
+  countries?: CountryConfig[];
+  /** Currently selected country id */
+  currentCountry?: string;
+  /** Callback when a country is selected */
+  onCountryChange?: (id: string) => void;
+  /** Navigation callback — called when any nav link is clicked */
+  onNavigate?: (href: string) => void;
+  /** Custom link component (e.g. React Router Link, Next.js Link) */
+  linkComponent?: React.ElementType;
+  /** Logo image source URL */
+  logoSrc?: string;
+  /** Logo link href */
+  logoHref?: string;
+  /** Whether an external sidebar/navbar is opened (for sidebar toggle button) */
+  navbarOpened?: boolean;
+  /** Callback to toggle an external sidebar/navbar */
+  onToggleNavbar?: () => void;
+  /** Additional CSS class names */
+  className?: string;
+  /** Style overrides */
+  styles?: { root?: React.CSSProperties };
+}
+
+/**
+ * HomeHeader — gradient teal header bar for the PolicyEngine home page.
+ *
+ * Features:
+ * - Sticky positioning with shadow
+ * - Gradient background (teal-800 to teal-600)
+ * - Logo with configurable link
+ * - Desktop navigation with Apple-style dropdown menus
+ * - Mobile hamburger menu using Sheet component
+ * - Country selector dropdown
+ */
+export const HomeHeader = forwardRef<HTMLDivElement, HomeHeaderProps>(
+  (
+    {
+      navItems,
+      countries,
+      currentCountry,
+      onCountryChange,
+      onNavigate,
+      linkComponent,
+      logoSrc,
+      logoHref,
+      navbarOpened,
+      onToggleNavbar,
+      className,
+      styles,
+    },
+    ref,
+  ) => {
+    const [mobileMenuOpened, setMobileMenuOpened] = useState(false);
+
+    return (
+      <div
+        ref={ref}
+        className={cn(className)}
+        style={{
+          position: 'sticky',
+          top: 0,
+          padding: '8px 32px',
+          height: 'var(--spacing-header, 58px)',
+          background:
+            'linear-gradient(to right, var(--color-teal-800), var(--color-teal-600))',
+          borderBottom: '0.5px solid var(--color-teal-700)',
+          boxShadow:
+            '0px 2px 4px -1px rgba(0, 0, 0, 0.06), 0px 4px 6px -1px rgba(0, 0, 0, 0.1)',
+          zIndex: 1000,
+          fontFamily: 'var(--font-sans)',
+          width: '100%',
+          boxSizing: 'border-box',
+          ...styles?.root,
+        }}
+      >
+        <HomeHeaderContent
+          navItems={navItems}
+          opened={mobileMenuOpened}
+          onOpen={() => setMobileMenuOpened(true)}
+          onClose={() => setMobileMenuOpened(false)}
+          onNavigate={onNavigate}
+          linkComponent={linkComponent}
+          logoSrc={logoSrc}
+          logoHref={logoHref}
+          countries={countries}
+          currentCountry={currentCountry}
+          onCountryChange={onCountryChange}
+          navbarOpened={navbarOpened}
+          onToggleNavbar={onToggleNavbar}
+        />
+      </div>
+    );
+  },
+);
+HomeHeader.displayName = 'HomeHeader';
diff --git a/src/layout/homeHeader/HomeHeaderContent.tsx b/src/layout/homeHeader/HomeHeaderContent.tsx
new file mode 100644
index 0000000..58453a4
--- /dev/null
+++ b/src/layout/homeHeader/HomeHeaderContent.tsx
@@ -0,0 +1,90 @@
+import type { CountryConfig, NavItemConfig } from './HomeHeader';
+import { HomeHeaderCountrySelector } from './HomeHeaderCountrySelector';
+import { HomeHeaderLogo } from './HomeHeaderLogo';
+import { HomeHeaderMobileMenu } from './HomeHeaderMobileMenu';
+import { HomeHeaderNav } from './HomeHeaderNav';
+
+interface HomeHeaderContentProps {
+  navItems: NavItemConfig[];
+  opened: boolean;
+  onOpen: () => void;
+  onClose: () => void;
+  onNavigate?: (href: string) => void;
+  linkComponent?: React.ElementType;
+  logoSrc?: string;
+  logoHref?: string;
+  countries?: CountryConfig[];
+  currentCountry?: string;
+  onCountryChange?: (id: string) => void;
+  navbarOpened?: boolean;
+  onToggleNavbar?: () => void;
+}
+
+/**
+ * Flex layout arranging logo, desktop nav, and action buttons.
+ */
+export function HomeHeaderContent({
+  navItems,
+  opened,
+  onOpen,
+  onClose,
+  onNavigate,
+  linkComponent,
+  logoSrc,
+  logoHref,
+  countries,
+  currentCountry,
+  onCountryChange,
+}: HomeHeaderContentProps) {
+  return (
+    <div style={{ height: '100%', width: '100%', padding: 0, margin: 0 }}>
+      <div
+        style={{
+          display: 'flex',
+          justifyContent: 'space-between',
+          alignItems: 'center',
+          height: '100%',
+        }}
+      >
+        {/* Left: Logo + Desktop Nav */}
+        <div style={{ display: 'flex', alignItems: 'center' }}>
+          <HomeHeaderLogo
+            logoSrc={logoSrc}
+            logoHref={logoHref}
+            linkComponent={linkComponent}
+            onNavigate={onNavigate}
+          />
+          <HomeHeaderNav
+            navItems={navItems}
+            onNavigate={onNavigate}
+            linkComponent={linkComponent}
+          />
+        </div>
+
+        {/* Right: Desktop actions (country selector) */}
+        <div className="hidden lg:flex items-center">
+          {countries && countries.length > 0 && (
+            <HomeHeaderCountrySelector
+              countries={countries}
+              currentCountry={currentCountry}
+              onCountryChange={onCountryChange}
+            />
+          )}
+        </div>
+
+        {/* Mobile menu (burger + sheet) */}
+        <HomeHeaderMobileMenu
+          opened={opened}
+          onOpen={onOpen}
+          onClose={onClose}
+          navItems={navItems}
+          onNavigate={onNavigate}
+          linkComponent={linkComponent}
+          countries={countries}
+          currentCountry={currentCountry}
+          onCountryChange={onCountryChange}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/src/layout/homeHeader/HomeHeaderCountrySelector.tsx b/src/layout/homeHeader/HomeHeaderCountrySelector.tsx
new file mode 100644
index 0000000..4368638
--- /dev/null
+++ b/src/layout/homeHeader/HomeHeaderCountrySelector.tsx
@@ -0,0 +1,190 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Globe } from 'lucide-react';
+import type { CountryConfig } from './HomeHeader';
+
+interface HomeHeaderCountrySelectorProps {
+  countries: CountryConfig[];
+  currentCountry?: string;
+  onCountryChange?: (id: string) => void;
+}
+
+/**
+ * Globe-icon dropdown for selecting a country/region.
+ */
+export function HomeHeaderCountrySelector({
+  countries,
+  currentCountry,
+  onCountryChange,
+}: HomeHeaderCountrySelectorProps) {
+  const [open, setOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [contentHeight, setContentHeight] = useState(0);
+  const [visible, setVisible] = useState(false);
+
+  const handleCountryChange = useCallback(
+    (id: string) => {
+      setOpen(false);
+      onCountryChange?.(id);
+    },
+    [onCountryChange],
+  );
+
+  useEffect(() => {
+    if (open && contentRef.current) {
+      setContentHeight(contentRef.current.scrollHeight);
+      requestAnimationFrame(() => setVisible(true));
+    } else {
+      setVisible(false);
+      const timer = setTimeout(() => setContentHeight(0), 250);
+      return () => clearTimeout(timer);
+    }
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) return;
+    function handleClick(e: MouseEvent) {
+      if (
+        containerRef.current &&
+        !containerRef.current.contains(e.target as Node)
+      ) {
+        setOpen(false);
+      }
+    }
+    function handleKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('mousedown', handleClick);
+    document.addEventListener('keydown', handleKey);
+    return () => {
+      document.removeEventListener('mousedown', handleClick);
+      document.removeEventListener('keydown', handleKey);
+    };
+  }, [open]);
+
+  return (
+    <div ref={containerRef} style={{ position: 'relative' }}>
+      <button
+        type="button"
+        onClick={() => setOpen((prev) => !prev)}
+        aria-label="Country selector"
+        style={{
+          background: 'transparent',
+          border: 'none',
+          cursor: 'pointer',
+          padding: '6px',
+          borderRadius: '6px',
+          transition: 'background-color 0.15s ease',
+          lineHeight: 1,
+          display: 'flex',
+          alignItems: 'center',
+        }}
+        onMouseEnter={(e) => {
+          e.currentTarget.style.backgroundColor = 'rgba(255, 255, 255, 0.12)';
+        }}
+        onMouseLeave={(e) => {
+          e.currentTarget.style.backgroundColor = 'transparent';
+        }}
+      >
+        <Globe size={18} color="var(--text-inverse)" />
+      </button>
+
+      {(open || contentHeight > 0) && (
+        <>
+          <div
+            onClick={() => setOpen(false)}
+            role="presentation"
+            style={{
+              position: 'fixed',
+              inset: 0,
+              zIndex: 999,
+              cursor: 'default',
+            }}
+          />
+          <div
+            style={{
+              position: 'absolute',
+              top: '100%',
+              right: 0,
+              transform: visible ? 'translateY(0)' : 'translateY(-8px)',
+              marginTop: '10px',
+              minWidth: '220px',
+              overflow: 'hidden',
+              maxHeight: visible ? `${contentHeight}px` : '0px',
+              opacity: visible ? 1 : 0,
+              transition:
+                'max-height 0.3s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.2s ease, transform 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
+              borderRadius: '14px',
+              background:
+                'linear-gradient(135deg, rgba(255,255,255,0.97), rgba(240,249,255,0.95))',
+              backdropFilter: 'blur(24px) saturate(200%)',
+              WebkitBackdropFilter: 'blur(24px) saturate(200%)',
+              boxShadow:
+                '0 20px 60px rgba(0, 0, 0, 0.15), 0 4px 16px rgba(0, 0, 0, 0.06), inset 0 0 0 1px rgba(255, 255, 255, 0.6)',
+              zIndex: 1001,
+            }}
+          >
+            <div ref={contentRef} style={{ padding: '8px' }}>
+              {countries.map((country, i) => (
+                <button
+                  key={country.id}
+                  type="button"
+                  onClick={() => handleCountryChange(country.id)}
+                  style={{
+                    display: 'flex',
+                    alignItems: 'center',
+                    width: '100%',
+                    textAlign: 'left',
+                    padding: '11px 16px',
+                    borderRadius: '10px',
+                    border: 'none',
+                    background: 'transparent',
+                    cursor: 'pointer',
+                    fontSize: '14px',
+                    fontFamily: 'var(--font-sans)',
+                    fontWeight:
+                      currentCountry === country.id ? 700 : 600,
+                    color: 'var(--color-teal-800)',
+                    transition:
+                      'background-color 0.12s ease, color 0.12s ease, opacity 0.3s ease',
+                    transitionDelay: visible ? `${i * 50}ms` : '0ms',
+                    opacity: visible ? 1 : 0,
+                    lineHeight: '1.3',
+                    letterSpacing: '-0.01em',
+                  }}
+                  onMouseEnter={(e) => {
+                    e.currentTarget.style.backgroundColor =
+                      'var(--color-teal-500)';
+                    e.currentTarget.style.color = 'var(--text-inverse)';
+                  }}
+                  onMouseLeave={(e) => {
+                    e.currentTarget.style.backgroundColor = 'transparent';
+                    e.currentTarget.style.color = 'var(--color-teal-800)';
+                  }}
+                >
+                  {country.flagEmoji && (
+                    <span style={{ marginRight: '8px', fontSize: '16px' }}>
+                      {country.flagEmoji}
+                    </span>
+                  )}
+                  {country.label}
+                  {currentCountry === country.id && (
+                    <span
+                      style={{
+                        marginLeft: 'auto',
+                        fontSize: '12px',
+                        opacity: 0.6,
+                      }}
+                    >
+                      &#10003;
+                    </span>
+                  )}
+                </button>
+              ))}
+            </div>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
diff --git a/src/layout/homeHeader/HomeHeaderLogo.tsx b/src/layout/homeHeader/HomeHeaderLogo.tsx
new file mode 100644
index 0000000..398c259
--- /dev/null
+++ b/src/layout/homeHeader/HomeHeaderLogo.tsx
@@ -0,0 +1,60 @@
+import { forwardRef } from 'react';
+import whiteWordmark from '../../assets/logos/policyengine/white.svg';
+
+export interface HomeHeaderLogoProps {
+  logoSrc?: string;
+  logoHref?: string;
+  linkComponent?: React.ElementType;
+  onNavigate?: (href: string) => void;
+}
+
+export const HomeHeaderLogo = forwardRef<HTMLDivElement, HomeHeaderLogoProps>(
+  ({ logoSrc, logoHref = '/', linkComponent, onNavigate }, ref) => {
+    const imgEl = (
+      <img
+        src={logoSrc ?? whiteWordmark}
+        alt="PolicyEngine"
+        style={{ height: '24px', width: 'auto' }}
+      />
+    );
+
+    const containerStyle: React.CSSProperties = {
+      display: 'flex',
+      alignItems: 'center',
+      cursor: 'pointer',
+      marginRight: '16px',
+      textDecoration: 'none',
+    };
+
+    if (linkComponent) {
+      const LinkComp = linkComponent;
+      return (
+        <div ref={ref}>
+          <LinkComp href={logoHref} to={logoHref} style={containerStyle}>
+            {imgEl}
+          </LinkComp>
+        </div>
+      );
+    }
+
+    return (
+      <div ref={ref}>
+        <a
+          href={logoHref}
+          style={containerStyle}
+          onClick={
+            onNavigate
+              ? (e: React.MouseEvent) => {
+                  e.preventDefault();
+                  onNavigate(logoHref);
+                }
+              : undefined
+          }
+        >
+          {imgEl}
+        </a>
+      </div>
+    );
+  },
+);
+HomeHeaderLogo.displayName = 'HomeHeaderLogo';
diff --git a/src/layout/homeHeader/HomeHeaderMobileMenu.tsx b/src/layout/homeHeader/HomeHeaderMobileMenu.tsx
new file mode 100644
index 0000000..06903fb
--- /dev/null
+++ b/src/layout/homeHeader/HomeHeaderMobileMenu.tsx
@@ -0,0 +1,199 @@
+import { Menu } from 'lucide-react';
+import {
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+} from '../../primitives/Sheet';
+import type { CountryConfig, NavItemConfig } from './HomeHeader';
+import { HomeHeaderCountrySelector } from './HomeHeaderCountrySelector';
+
+interface HomeHeaderMobileMenuProps {
+  opened: boolean;
+  onOpen: () => void;
+  onClose: () => void;
+  navItems: NavItemConfig[];
+  onNavigate?: (href: string) => void;
+  linkComponent?: React.ElementType;
+  countries?: CountryConfig[];
+  currentCountry?: string;
+  onCountryChange?: (id: string) => void;
+}
+
+/**
+ * Mobile navigation: hamburger button + Sheet slide-in panel.
+ * Visible below the lg breakpoint.
+ */
+export function HomeHeaderMobileMenu({
+  opened,
+  onOpen,
+  onClose,
+  navItems,
+  onNavigate,
+  linkComponent,
+  countries,
+  currentCountry,
+  onCountryChange,
+}: HomeHeaderMobileMenuProps) {
+  const handleNavigate = (href: string) => {
+    onClose();
+    if (onNavigate) {
+      onNavigate(href);
+    } else {
+      window.location.href = href;
+    }
+  };
+
+  return (
+    <>
+      {/* Mobile burger + country selector */}
+      <div className="flex lg:hidden items-center" style={{ gap: '16px' }}>
+        {countries && countries.length > 0 && (
+          <HomeHeaderCountrySelector
+            countries={countries}
+            currentCountry={currentCountry}
+            onCountryChange={onCountryChange}
+          />
+        )}
+        <button
+          type="button"
+          className="p-1 rounded bg-transparent border-none cursor-pointer"
+          onClick={onOpen}
+          aria-label="Toggle navigation"
+        >
+          <Menu size={24} color="var(--text-inverse)" />
+        </button>
+      </div>
+
+      {/* Sheet slide-in */}
+      <Sheet open={opened} onOpenChange={(open) => !open && onClose()}>
+        <SheetContent
+          side="right"
+          className="w-[300px]"
+          style={{ backgroundColor: 'var(--color-teal-600)' }}
+        >
+          <SheetHeader>
+            <SheetTitle className="text-white">Menu</SheetTitle>
+          </SheetHeader>
+          <div
+            className="flex flex-col"
+            style={{ gap: '24px', padding: '24px' }}
+          >
+            {navItems.map((item) =>
+              item.children && item.children.length > 0 ? (
+                <div key={item.label}>
+                  <span
+                    style={{
+                      color: 'var(--text-inverse)',
+                      fontWeight: 500,
+                      fontSize: '14px',
+                      marginBottom: '8px',
+                      display: 'block',
+                      fontFamily: 'var(--font-sans)',
+                    }}
+                  >
+                    {item.label}
+                  </span>
+                  <div
+                    className="flex flex-col"
+                    style={{ gap: '8px', paddingLeft: '16px' }}
+                  >
+                    {item.children.map((child) => {
+                      if (linkComponent) {
+                        const LinkComp = linkComponent;
+                        return (
+                          <LinkComp
+                            key={child.label}
+                            href={child.href}
+                            to={child.href}
+                            onClick={onClose}
+                            style={{
+                              color: 'var(--text-inverse)',
+                              textDecoration: 'none',
+                              fontWeight: 400,
+                              fontSize: '14px',
+                              fontFamily: 'var(--font-sans)',
+                            }}
+                          >
+                            {child.label}
+                          </LinkComp>
+                        );
+                      }
+                      return (
+                        <a
+                          key={child.label}
+                          href={child.href}
+                          onClick={(e) => {
+                            e.preventDefault();
+                            handleNavigate(child.href);
+                          }}
+                          style={{
+                            color: 'var(--text-inverse)',
+                            textDecoration: 'none',
+                            fontWeight: 400,
+                            fontSize: '14px',
+                            fontFamily: 'var(--font-sans)',
+                          }}
+                        >
+                          {child.label}
+                        </a>
+                      );
+                    })}
+                  </div>
+                </div>
+              ) : (
+                (() => {
+                  if (linkComponent) {
+                    const LinkComp = linkComponent;
+                    return (
+                      <LinkComp
+                        key={item.label}
+                        href={item.href}
+                        to={item.href}
+                        onClick={onClose}
+                        style={{
+                          color: 'var(--text-inverse)',
+                          textDecoration: 'none',
+                          fontWeight: 500,
+                          fontSize: '14px',
+                          fontFamily: 'var(--font-sans)',
+                          display: 'block',
+                        }}
+                      >
+                        {item.label}
+                      </LinkComp>
+                    );
+                  }
+                  return (
+                    <a
+                      key={item.label}
+                      href={item.href}
+                      onClick={
+                        onNavigate
+                          ? (e: React.MouseEvent) => {
+                              e.preventDefault();
+                              handleNavigate(item.href);
+                            }
+                          : undefined
+                      }
+                      style={{
+                        color: 'var(--text-inverse)',
+                        textDecoration: 'none',
+                        fontWeight: 500,
+                        fontSize: '14px',
+                        fontFamily: 'var(--font-sans)',
+                        display: 'block',
+                      }}
+                    >
+                      {item.label}
+                    </a>
+                  );
+                })()
+              ),
+            )}
+          </div>
+        </SheetContent>
+      </Sheet>
+    </>
+  );
+}
diff --git a/src/layout/homeHeader/HomeHeaderNav.tsx b/src/layout/homeHeader/HomeHeaderNav.tsx
new file mode 100644
index 0000000..5a35e93
--- /dev/null
+++ b/src/layout/homeHeader/HomeHeaderNav.tsx
@@ -0,0 +1,30 @@
+import type { NavItemConfig } from './HomeHeader';
+import { HomeHeaderNavItem } from './HomeHeaderNavItem';
+
+interface HomeHeaderNavProps {
+  navItems: NavItemConfig[];
+  onNavigate?: (href: string) => void;
+  linkComponent?: React.ElementType;
+}
+
+/**
+ * Desktop navigation bar — hidden below lg breakpoint.
+ */
+export function HomeHeaderNav({
+  navItems,
+  onNavigate,
+  linkComponent,
+}: HomeHeaderNavProps) {
+  return (
+    <div className="hidden lg:flex items-center gap-6">
+      {navItems.map((item) => (
+        <HomeHeaderNavItem
+          key={item.label}
+          item={item}
+          onNavigate={onNavigate}
+          linkComponent={linkComponent}
+        />
+      ))}
+    </div>
+  );
+}
diff --git a/src/layout/homeHeader/HomeHeaderNavItem.tsx b/src/layout/homeHeader/HomeHeaderNavItem.tsx
new file mode 100644
index 0000000..c732618
--- /dev/null
+++ b/src/layout/homeHeader/HomeHeaderNavItem.tsx
@@ -0,0 +1,286 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { ChevronDown } from 'lucide-react';
+import type { NavItemConfig } from './HomeHeader';
+
+interface HomeHeaderNavItemProps {
+  item: NavItemConfig;
+  onNavigate?: (href: string) => void;
+  linkComponent?: React.ElementType;
+}
+
+const navItemStyle: React.CSSProperties = {
+  color: 'var(--text-inverse)',
+  fontWeight: 500,
+  fontSize: '15px',
+  fontFamily: 'var(--font-sans)',
+  textDecoration: 'none',
+  padding: '6px 14px',
+  borderRadius: '6px',
+  transition: 'background-color 0.15s ease',
+  letterSpacing: '0.01em',
+};
+
+const hoverHandlers = {
+  onMouseEnter: (e: React.MouseEvent<HTMLElement>) => {
+    e.currentTarget.style.backgroundColor = 'rgba(255, 255, 255, 0.12)';
+  },
+  onMouseLeave: (e: React.MouseEvent<HTMLElement>) => {
+    e.currentTarget.style.backgroundColor = 'transparent';
+  },
+};
+
+/**
+ * Apple-style dropdown panel with smooth height reveal and content fade.
+ */
+function AppleDropdown({
+  items,
+  open,
+  onClose,
+  onNavigate,
+  linkComponent,
+}: {
+  items: NonNullable<NavItemConfig['children']>;
+  open: boolean;
+  onClose: () => void;
+  onNavigate?: (href: string) => void;
+  linkComponent?: React.ElementType;
+}) {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [contentHeight, setContentHeight] = useState(0);
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    if (open && contentRef.current) {
+      setContentHeight(contentRef.current.scrollHeight);
+      requestAnimationFrame(() => setVisible(true));
+    } else {
+      setVisible(false);
+      const timer = setTimeout(() => setContentHeight(0), 250);
+      return () => clearTimeout(timer);
+    }
+  }, [open]);
+
+  const handleSelect = useCallback(
+    (item: { label: string; href: string }) => {
+      onClose();
+      if (onNavigate) {
+        onNavigate(item.href);
+      } else if (linkComponent) {
+        // linkComponent handles its own navigation
+      } else {
+        window.location.href = item.href;
+      }
+    },
+    [onClose, onNavigate, linkComponent],
+  );
+
+  if (!open && contentHeight === 0) {
+    return null;
+  }
+
+  return (
+    <>
+      {/* Invisible click-away layer */}
+      <div
+        onClick={onClose}
+        role="presentation"
+        style={{
+          position: 'fixed',
+          inset: 0,
+          zIndex: 999,
+          cursor: 'default',
+        }}
+      />
+      {/* Dropdown panel */}
+      <div
+        style={{
+          position: 'absolute',
+          top: '100%',
+          left: '50%',
+          transform: visible
+            ? 'translateX(-50%) translateY(0)'
+            : 'translateX(-50%) translateY(-8px)',
+          marginTop: '10px',
+          minWidth: '220px',
+          overflow: 'hidden',
+          maxHeight: visible ? `${contentHeight}px` : '0px',
+          opacity: visible ? 1 : 0,
+          transition:
+            'max-height 0.3s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.2s ease, transform 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
+          borderRadius: '14px',
+          background:
+            'linear-gradient(135deg, rgba(255,255,255,0.97), rgba(240,249,255,0.95))',
+          backdropFilter: 'blur(24px) saturate(200%)',
+          WebkitBackdropFilter: 'blur(24px) saturate(200%)',
+          boxShadow:
+            '0 20px 60px rgba(0, 0, 0, 0.15), 0 4px 16px rgba(0, 0, 0, 0.06), inset 0 0 0 1px rgba(255, 255, 255, 0.6)',
+          zIndex: 1001,
+        }}
+      >
+        <div ref={contentRef} style={{ padding: '8px' }}>
+          {items.map((item, i) => (
+            <button
+              key={item.label}
+              type="button"
+              onClick={() => handleSelect(item)}
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                width: '100%',
+                textAlign: 'left',
+                padding: '11px 16px',
+                borderRadius: '10px',
+                border: 'none',
+                background: 'transparent',
+                cursor: 'pointer',
+                fontSize: '14px',
+                fontFamily: 'var(--font-sans)',
+                fontWeight: 600,
+                color: 'var(--color-teal-800)',
+                transition:
+                  'background-color 0.12s ease, color 0.12s ease, opacity 0.3s ease',
+                transitionDelay: visible ? `${i * 50}ms` : '0ms',
+                opacity: visible ? 1 : 0,
+                lineHeight: '1.3',
+                letterSpacing: '-0.01em',
+              }}
+              onMouseEnter={(e) => {
+                e.currentTarget.style.backgroundColor =
+                  'var(--color-teal-500)';
+                e.currentTarget.style.color = 'var(--text-inverse)';
+              }}
+              onMouseLeave={(e) => {
+                e.currentTarget.style.backgroundColor = 'transparent';
+                e.currentTarget.style.color = 'var(--color-teal-800)';
+              }}
+            >
+              <span>{item.label}</span>
+              {item.description && (
+                <span
+                  style={{
+                    marginLeft: '8px',
+                    fontSize: '12px',
+                    opacity: 0.6,
+                    fontWeight: 400,
+                  }}
+                >
+                  {item.description}
+                </span>
+              )}
+            </button>
+          ))}
+        </div>
+      </div>
+    </>
+  );
+}
+
+/**
+ * Navigation item with optional Apple-style dropdown.
+ */
+export function HomeHeaderNavItem({
+  item,
+  onNavigate,
+  linkComponent,
+}: HomeHeaderNavItemProps) {
+  const { label, href, children } = item;
+  const [dropdownOpen, setDropdownOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Close on click outside
+  useEffect(() => {
+    if (!dropdownOpen) return;
+    function handleClick(e: MouseEvent) {
+      if (
+        containerRef.current &&
+        !containerRef.current.contains(e.target as Node)
+      ) {
+        setDropdownOpen(false);
+      }
+    }
+    document.addEventListener('mousedown', handleClick);
+    return () => document.removeEventListener('mousedown', handleClick);
+  }, [dropdownOpen]);
+
+  // Close on Escape
+  useEffect(() => {
+    if (!dropdownOpen) return;
+    function handleKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setDropdownOpen(false);
+    }
+    document.addEventListener('keydown', handleKey);
+    return () => document.removeEventListener('keydown', handleKey);
+  }, [dropdownOpen]);
+
+  if (children && children.length > 0) {
+    return (
+      <div ref={containerRef} style={{ position: 'relative' }}>
+        <button
+          type="button"
+          onClick={() => setDropdownOpen((prev) => !prev)}
+          style={{
+            ...navItemStyle,
+            background: 'transparent',
+            border: 'none',
+            cursor: 'pointer',
+            display: 'flex',
+            alignItems: 'center',
+            gap: '4px',
+          }}
+          {...hoverHandlers}
+        >
+          <span>{label}</span>
+          <ChevronDown
+            size={15}
+            color="var(--text-inverse)"
+            style={{
+              opacity: 0.7,
+              transition: 'transform 0.25s cubic-bezier(0.4, 0, 0.2, 1)',
+              transform: dropdownOpen ? 'rotate(180deg)' : 'rotate(0deg)',
+            }}
+          />
+        </button>
+        <AppleDropdown
+          items={children}
+          open={dropdownOpen}
+          onClose={() => setDropdownOpen(false)}
+          onNavigate={onNavigate}
+          linkComponent={linkComponent}
+        />
+      </div>
+    );
+  }
+
+  // Simple link item
+  if (linkComponent) {
+    const LinkComp = linkComponent;
+    return (
+      <LinkComp
+        href={href}
+        to={href}
+        style={navItemStyle}
+        {...hoverHandlers}
+      >
+        {label}
+      </LinkComp>
+    );
+  }
+
+  return (
+    <a
+      href={href}
+      style={navItemStyle}
+      onClick={
+        onNavigate && href
+          ? (e: React.MouseEvent) => {
+              e.preventDefault();
+              onNavigate(href);
+            }
+          : undefined
+      }
+      {...hoverHandlers}
+    >
+      {label}
+    </a>
+  );
+}
diff --git a/src/layout/homeHeader/index.ts b/src/layout/homeHeader/index.ts
new file mode 100644
index 0000000..b00724a
--- /dev/null
+++ b/src/layout/homeHeader/index.ts
@@ -0,0 +1,8 @@
+export { HomeHeader } from './HomeHeader';
+export type { HomeHeaderProps, NavItemConfig, CountryConfig } from './HomeHeader';
+export { HomeHeaderContent } from './HomeHeaderContent';
+export { HomeHeaderLogo } from './HomeHeaderLogo';
+export { HomeHeaderNav } from './HomeHeaderNav';
+export { HomeHeaderNavItem } from './HomeHeaderNavItem';
+export { HomeHeaderMobileMenu } from './HomeHeaderMobileMenu';
+export { HomeHeaderCountrySelector } from './HomeHeaderCountrySelector';
diff --git a/src/layout/index.ts b/src/layout/index.ts
index 285e50d..91a5621 100644
--- a/src/layout/index.ts
+++ b/src/layout/index.ts
@@ -1,6 +1,19 @@
 export { DashboardShell, type DashboardShellProps } from './DashboardShell';
 export { SidebarLayout, type SidebarLayoutProps } from './SidebarLayout';
 export { SingleColumnLayout, type SingleColumnLayoutProps } from './SingleColumnLayout';
-export { Header, headerVariants, type HeaderProps } from './Header';
+export { Header, headerVariants, type HeaderProps, type HeaderNavLink } from './Header';
 export { InputPanel, type InputPanelProps } from './InputPanel';
 export { ResultsPanel, type ResultsPanelProps } from './ResultsPanel';
+export { Stack, type StackProps } from './Stack';
+export { Group, type GroupProps } from './Group';
+export { Container, type ContainerProps } from './Container';
+export { SidebarNavItem, type SidebarNavItemProps } from './SidebarNavItem';
+export { SidebarSection, type SidebarSectionProps } from './SidebarSection';
+export { SidebarDivider } from './SidebarDivider';
+export { Footer, type FooterProps } from './Footer';
+export {
+  HomeHeader,
+  type HomeHeaderProps,
+  type NavItemConfig,
+  type CountryConfig,
+} from './homeHeader';
diff --git a/src/primitives/Accordion.tsx b/src/primitives/Accordion.tsx
new file mode 100644
index 0000000..02ad1d5
--- /dev/null
+++ b/src/primitives/Accordion.tsx
@@ -0,0 +1,61 @@
+import * as React from 'react';
+import { ChevronDownIcon } from 'lucide-react';
+import { Accordion as AccordionPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function Accordion({ ...props }: React.ComponentProps<typeof AccordionPrimitive.Root>) {
+  return <AccordionPrimitive.Root data-slot="accordion" {...props} />;
+}
+
+function AccordionItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn('border-b last:border-b-0', className)}
+      {...props}
+    />
+  );
+}
+
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Trigger>) {
+  return (
+    <AccordionPrimitive.Header className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          'bg-transparent focus-visible:border-ring focus-visible:ring-ring/50 flex flex-1 items-start justify-between gap-4 rounded-md py-4 text-left text-sm font-medium transition-all outline-none hover:underline focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180',
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <ChevronDownIcon className="text-muted-foreground pointer-events-none size-4 shrink-0 translate-y-0.5 transition-transform duration-200" />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  );
+}
+
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Content>) {
+  return (
+    <AccordionPrimitive.Content
+      data-slot="accordion-content"
+      className="data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down overflow-hidden text-sm"
+      {...props}
+    >
+      <div className={cn('pt-0 pb-4', className)}>{children}</div>
+    </AccordionPrimitive.Content>
+  );
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent };
diff --git a/src/primitives/Alert.tsx b/src/primitives/Alert.tsx
new file mode 100644
index 0000000..528a7d6
--- /dev/null
+++ b/src/primitives/Alert.tsx
@@ -0,0 +1,62 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '../utils/cn';
+
+const alertVariants = cva(
+  'relative w-full rounded-lg border px-4 py-3 text-sm grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current',
+  {
+    variants: {
+      variant: {
+        default: 'bg-card text-card-foreground',
+        destructive:
+          'text-destructive bg-card [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  }
+);
+
+function Alert({
+  className,
+  variant,
+  ...props
+}: React.ComponentProps<'div'> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      data-slot="alert"
+      role="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-title"
+      className={cn(
+        'col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function AlertDescription({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        'text-muted-foreground col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Alert, AlertTitle, AlertDescription };
diff --git a/src/primitives/Badge.tsx b/src/primitives/Badge.tsx
index 6e62796..aa81fd5 100644
--- a/src/primitives/Badge.tsx
+++ b/src/primitives/Badge.tsx
@@ -3,16 +3,19 @@ import { type HTMLAttributes } from 'react';
 import { cn } from '../utils/cn';
 
 const badgeVariants = cva(
-  'inline-flex items-center rounded-sm px-3 py-1 text-xs font-medium transition-colors',
+  'inline-flex items-center rounded-full border border-transparent px-3 py-1 text-xs font-medium transition-colors',
   {
     variants: {
       variant: {
         default: 'bg-primary text-primary-foreground',
         secondary: 'bg-secondary text-secondary-foreground',
-        outline: 'border border-border text-foreground',
+        outline: 'border-border text-foreground',
         success: 'bg-green-100 text-green-800',
         warning: 'bg-yellow-100 text-yellow-800',
         error: 'bg-red-100 text-red-800',
+        ghost: '[a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+        destructive:
+          'bg-destructive text-white [a&]:hover:bg-destructive/90',
       },
     },
     defaultVariants: { variant: 'default' },
@@ -28,6 +31,8 @@ export interface BadgeProps
 export function Badge({ className, variant, styles, ...props }: BadgeProps) {
   return (
     <span
+      data-slot="badge"
+      data-variant={variant}
       className={cn(badgeVariants({ variant }), className)}
       style={styles?.root}
       {...props}
diff --git a/src/primitives/Button.tsx b/src/primitives/Button.tsx
index f0dc1dd..8c98db4 100644
--- a/src/primitives/Button.tsx
+++ b/src/primitives/Button.tsx
@@ -1,24 +1,31 @@
 import { cva, type VariantProps } from 'class-variance-authority';
 import { forwardRef, type ButtonHTMLAttributes } from 'react';
+import { Slot } from 'radix-ui';
 import { cn } from '../utils/cn';
 
 const buttonVariants = cva(
-  'inline-flex items-center justify-center gap-2 rounded-sm text-sm font-medium transition-colors cursor-pointer disabled:pointer-events-none disabled:opacity-50',
+  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all cursor-pointer disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4 shrink-0',
   {
     variants: {
       variant: {
         default:
-          'bg-primary text-primary-foreground hover:bg-teal-600',
+          'bg-primary text-primary-foreground hover:bg-primary/90',
         outline:
           'border border-border bg-background hover:bg-gray-50',
-        ghost: 'hover:bg-gray-100',
+        ghost: 'bg-transparent hover:bg-gray-100',
         destructive: 'bg-destructive text-destructive-foreground hover:bg-red-600',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        link: 'bg-transparent text-primary underline-offset-4 hover:underline',
       },
       size: {
-        default: 'h-9 px-4 py-2',
+        default: 'h-9 px-4 py-2 has-[>svg]:px-3',
+        xs: 'h-6 gap-1 rounded-md px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*=size-])]:size-3',
         sm: 'h-8 px-3 text-xs',
         lg: 'h-10 px-6',
         icon: 'h-9 w-9',
+        'icon-xs': 'size-6 rounded-md [&_svg:not([class*=size-])]:size-3',
+        'icon-sm': 'size-8',
+        'icon-lg': 'size-10',
       },
     },
     defaultVariants: { variant: 'default', size: 'default' },
@@ -29,17 +36,25 @@ export interface ButtonProps
   extends ButtonHTMLAttributes<HTMLButtonElement>,
     VariantProps<typeof buttonVariants> {
   styles?: { root?: React.CSSProperties };
+  asChild?: boolean;
 }
 
 export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant, size, styles, ...props }, ref) => (
-    <button
-      ref={ref}
-      className={cn(buttonVariants({ variant, size }), className)}
-      style={styles?.root}
-      {...props}
-    />
-  ),
+  ({ className, variant = 'default', size = 'default', styles, asChild = false, ...props }, ref) => {
+    const Comp = (asChild ? Slot.Root : 'button') as React.ElementType;
+
+    return (
+      <Comp
+        ref={ref}
+        data-slot="button"
+        data-variant={variant}
+        data-size={size}
+        className={cn(buttonVariants({ variant, size }), className)}
+        style={styles?.root}
+        {...props}
+      />
+    );
+  },
 );
 Button.displayName = 'Button';
 
diff --git a/src/primitives/Card.tsx b/src/primitives/Card.tsx
index f4f1752..42019f0 100644
--- a/src/primitives/Card.tsx
+++ b/src/primitives/Card.tsx
@@ -9,8 +9,9 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(
   ({ className, styles, ...props }, ref) => (
     <div
       ref={ref}
+      data-slot="card"
       className={cn(
-        'bg-card border border-border rounded-lg shadow-sm',
+        'bg-card text-card-foreground flex flex-col gap-6 rounded-xl border border-border py-6 shadow-sm',
         className,
       )}
       style={styles?.root}
@@ -26,7 +27,11 @@ export const CardHeader = forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('flex flex-col gap-1.5 p-4', className)}
+    data-slot="card-header"
+    className={cn(
+      '@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6',
+      className,
+    )}
     {...props}
   />
 ));
@@ -38,7 +43,8 @@ export const CardTitle = forwardRef<
 >(({ className, ...props }, ref) => (
   <h3
     ref={ref}
-    className={cn('text-lg font-semibold text-foreground', className)}
+    data-slot="card-title"
+    className={cn('leading-none font-semibold', className)}
     {...props}
   />
 ));
@@ -50,19 +56,37 @@ export const CardDescription = forwardRef<
 >(({ className, ...props }, ref) => (
   <p
     ref={ref}
+    data-slot="card-description"
     className={cn('text-sm text-muted-foreground', className)}
     {...props}
   />
 ));
 CardDescription.displayName = 'CardDescription';
 
+export const CardAction = forwardRef<
+  HTMLDivElement,
+  HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="card-action"
+    className={cn(
+      'col-start-2 row-span-2 row-start-1 self-start justify-self-end',
+      className,
+    )}
+    {...props}
+  />
+));
+CardAction.displayName = 'CardAction';
+
 export const CardContent = forwardRef<
   HTMLDivElement,
   HTMLAttributes<HTMLDivElement>
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('p-4 pt-0', className)}
+    data-slot="card-content"
+    className={cn('px-6', className)}
     {...props}
   />
 ));
@@ -74,7 +98,8 @@ export const CardFooter = forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('flex items-center p-4 pt-0', className)}
+    data-slot="card-footer"
+    className={cn('flex items-center px-6 [.border-t]:pt-6', className)}
     {...props}
   />
 ));
diff --git a/src/primitives/Checkbox.tsx b/src/primitives/Checkbox.tsx
new file mode 100644
index 0000000..7bb90bc
--- /dev/null
+++ b/src/primitives/Checkbox.tsx
@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { CheckIcon } from 'lucide-react';
+import { Checkbox as CheckboxPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function Checkbox({ className, ...props }: React.ComponentProps<typeof CheckboxPrimitive.Root>) {
+  return (
+    <CheckboxPrimitive.Root
+      data-slot="checkbox"
+      className={cn(
+        'peer border-input data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=checked]:border-primary focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 aria-invalid:border-destructive size-4 shrink-0 rounded-[4px] border shadow-xs transition-shadow outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50',
+        className
+      )}
+      {...props}
+    >
+      <CheckboxPrimitive.Indicator
+        data-slot="checkbox-indicator"
+        className="grid place-content-center text-current transition-none"
+      >
+        <CheckIcon className="size-3.5" />
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  );
+}
+
+export { Checkbox };
diff --git a/src/primitives/Collapsible.tsx b/src/primitives/Collapsible.tsx
new file mode 100644
index 0000000..dd89cfc
--- /dev/null
+++ b/src/primitives/Collapsible.tsx
@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { Collapsible as CollapsiblePrimitive } from 'radix-ui';
+
+function Collapsible({ ...props }: React.ComponentProps<typeof CollapsiblePrimitive.Root>) {
+  return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />;
+}
+
+function CollapsibleTrigger({
+  ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.Trigger>) {
+  return <CollapsiblePrimitive.Trigger data-slot="collapsible-trigger" {...props} />;
+}
+
+function CollapsibleContent({
+  ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.Content>) {
+  return <CollapsiblePrimitive.Content data-slot="collapsible-content" {...props} />;
+}
+
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };
diff --git a/src/primitives/Command.tsx b/src/primitives/Command.tsx
new file mode 100644
index 0000000..f000ff2
--- /dev/null
+++ b/src/primitives/Command.tsx
@@ -0,0 +1,164 @@
+import * as React from 'react';
+import { Command as CommandPrimitive } from 'cmdk';
+import { SearchIcon } from 'lucide-react';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from './Dialog';
+import { cn } from '../utils/cn';
+
+function Command({ className, ...props }: React.ComponentProps<typeof CommandPrimitive>) {
+  return (
+    <CommandPrimitive
+      data-slot="command"
+      className={cn(
+        'bg-popover text-popover-foreground flex h-full w-full flex-col overflow-hidden rounded-md',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function CommandDialog({
+  title = 'Command Palette',
+  description = 'Search for a command to run...',
+  children,
+  className,
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof Dialog> & {
+  title?: string;
+  description?: string;
+  className?: string;
+  showCloseButton?: boolean;
+}) {
+  return (
+    <Dialog {...props}>
+      <DialogHeader className="sr-only">
+        <DialogTitle>{title}</DialogTitle>
+        <DialogDescription>{description}</DialogDescription>
+      </DialogHeader>
+      <DialogContent
+        className={cn('overflow-hidden p-0', className)}
+        showCloseButton={showCloseButton}
+      >
+        <Command className="[&_[cmdk-group-heading]]:text-muted-foreground **:data-[slot=command-input-wrapper]:h-12 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group]]:px-2 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
+          {children}
+        </Command>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function CommandInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Input>) {
+  return (
+    <div
+      data-slot="command-input-wrapper"
+      className="flex h-9 items-center gap-2 border-b px-3"
+    >
+      <SearchIcon className="size-4 shrink-0 opacity-50" />
+      <CommandPrimitive.Input
+        data-slot="command-input"
+        className={cn(
+          'placeholder:text-muted-foreground flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50',
+          className
+        )}
+        {...props}
+      />
+    </div>
+  );
+}
+
+function CommandList({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.List>) {
+  return (
+    <CommandPrimitive.List
+      data-slot="command-list"
+      className={cn(
+        'max-h-[300px] scroll-py-1 overflow-x-hidden overflow-y-auto',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function CommandEmpty({ ...props }: React.ComponentProps<typeof CommandPrimitive.Empty>) {
+  return (
+    <CommandPrimitive.Empty
+      data-slot="command-empty"
+      className="py-6 text-center text-sm"
+      {...props}
+    />
+  );
+}
+
+function CommandGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Group>) {
+  return (
+    <CommandPrimitive.Group
+      data-slot="command-group"
+      className={cn(
+        'text-foreground [&_[cmdk-group-heading]]:text-muted-foreground overflow-hidden p-1 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function CommandSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Separator>) {
+  return (
+    <CommandPrimitive.Separator
+      data-slot="command-separator"
+      className={cn('bg-border -mx-1 h-px', className)}
+      {...props}
+    />
+  );
+}
+
+function CommandItem({ className, ...props }: React.ComponentProps<typeof CommandPrimitive.Item>) {
+  return (
+    <CommandPrimitive.Item
+      data-slot="command-item"
+      className={cn(
+        'data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground [&_svg:not([class*=text-])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function CommandShortcut({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="command-shortcut"
+      className={cn('text-muted-foreground ml-auto text-xs tracking-widest', className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+};
diff --git a/src/primitives/Dialog.tsx b/src/primitives/Dialog.tsx
new file mode 100644
index 0000000..9ab2b97
--- /dev/null
+++ b/src/primitives/Dialog.tsx
@@ -0,0 +1,144 @@
+import * as React from 'react';
+import { XIcon } from 'lucide-react';
+import { Dialog as DialogPrimitive } from 'radix-ui';
+import { Button } from './Button';
+import { cn } from '../utils/cn';
+
+function Dialog({ ...props }: React.ComponentProps<typeof DialogPrimitive.Root>) {
+  return <DialogPrimitive.Root data-slot="dialog" {...props} />;
+}
+
+function DialogTrigger({ ...props }: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
+}
+
+function DialogPortal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Portal>) {
+  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />;
+}
+
+function DialogClose({ ...props }: React.ComponentProps<typeof DialogPrimitive.Close>) {
+  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />;
+}
+
+function DialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+  return (
+    <DialogPrimitive.Overlay
+      data-slot="dialog-overlay"
+      className={cn(
+        'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function DialogContent({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Content> & {
+  showCloseButton?: boolean;
+}) {
+  return (
+    <DialogPortal data-slot="dialog-portal">
+      <DialogOverlay />
+      <DialogPrimitive.Content
+        data-slot="dialog-content"
+        className={cn(
+          'bg-background data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 outline-none sm:max-w-lg',
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <DialogPrimitive.Close
+            data-slot="dialog-close"
+            className="ring-offset-background focus:ring-ring data-[state=open]:bg-accent data-[state=open]:text-muted-foreground absolute top-4 right-4 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4"
+          >
+            <XIcon />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  );
+}
+
+function DialogHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn('flex flex-col gap-2 text-center sm:text-left', className)}
+      {...props}
+    />
+  );
+}
+
+function DialogFooter({
+  className,
+  showCloseButton = false,
+  children,
+  ...props
+}: React.ComponentProps<'div'> & {
+  showCloseButton?: boolean;
+}) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn(
+        'flex flex-col-reverse gap-2 sm:flex-row sm:justify-end',
+        className
+      )}
+      {...props}
+    >
+      {children}
+      {showCloseButton && (
+        <DialogPrimitive.Close asChild>
+          <Button variant="outline">Close</Button>
+        </DialogPrimitive.Close>
+      )}
+    </div>
+  );
+}
+
+function DialogTitle({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Title>) {
+  return (
+    <DialogPrimitive.Title
+      data-slot="dialog-title"
+      className={cn('text-lg leading-none font-semibold', className)}
+      {...props}
+    />
+  );
+}
+
+function DialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Description>) {
+  return (
+    <DialogPrimitive.Description
+      data-slot="dialog-description"
+      className={cn('text-muted-foreground text-sm', className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+};
diff --git a/src/primitives/DropdownMenu.tsx b/src/primitives/DropdownMenu.tsx
new file mode 100644
index 0000000..0fa8766
--- /dev/null
+++ b/src/primitives/DropdownMenu.tsx
@@ -0,0 +1,225 @@
+import * as React from 'react';
+import { CheckIcon, ChevronRightIcon, CircleIcon } from 'lucide-react';
+import { DropdownMenu as DropdownMenuPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
+  return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />;
+}
+
+function DropdownMenuPortal({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+  return <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />;
+}
+
+function DropdownMenuTrigger({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+  return <DropdownMenuPrimitive.Trigger data-slot="dropdown-menu-trigger" {...props} />;
+}
+
+function DropdownMenuContent({
+  className,
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+  return (
+    <DropdownMenuPrimitive.Portal>
+      <DropdownMenuPrimitive.Content
+        data-slot="dropdown-menu-content"
+        sideOffset={sideOffset}
+        className={cn(
+          'bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-md',
+          className
+        )}
+        {...props}
+      />
+    </DropdownMenuPrimitive.Portal>
+  );
+}
+
+function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
+  return <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />;
+}
+
+function DropdownMenuItem({
+  className,
+  inset,
+  variant = 'default',
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+  inset?: boolean;
+  variant?: 'default' | 'destructive';
+}) {
+  return (
+    <DropdownMenuPrimitive.Item
+      data-slot="dropdown-menu-item"
+      data-inset={inset}
+      data-variant={variant}
+      className={cn(
+        'focus:bg-accent focus:text-accent-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:!text-destructive [&_svg:not([class*=text-])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>) {
+  return (
+    <DropdownMenuPrimitive.CheckboxItem
+      data-slot="dropdown-menu-checkbox-item"
+      className={cn(
+        'focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+        className
+      )}
+      checked={checked}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CheckIcon className="size-4" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.CheckboxItem>
+  );
+}
+
+function DropdownMenuRadioGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+  return <DropdownMenuPrimitive.RadioGroup data-slot="dropdown-menu-radio-group" {...props} />;
+}
+
+function DropdownMenuRadioItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>) {
+  return (
+    <DropdownMenuPrimitive.RadioItem
+      data-slot="dropdown-menu-radio-item"
+      className={cn(
+        'focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+        className
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CircleIcon className="size-2 fill-current" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.RadioItem>
+  );
+}
+
+function DropdownMenuLabel({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+  inset?: boolean;
+}) {
+  return (
+    <DropdownMenuPrimitive.Label
+      data-slot="dropdown-menu-label"
+      data-inset={inset}
+      className={cn('px-2 py-1.5 text-sm font-medium data-[inset]:pl-8', className)}
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+  return (
+    <DropdownMenuPrimitive.Separator
+      data-slot="dropdown-menu-separator"
+      className={cn('bg-border -mx-1 my-1 h-px', className)}
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="dropdown-menu-shortcut"
+      className={cn('text-muted-foreground ml-auto text-xs tracking-widest', className)}
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+  return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />;
+}
+
+function DropdownMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+  inset?: boolean;
+}) {
+  return (
+    <DropdownMenuPrimitive.SubTrigger
+      data-slot="dropdown-menu-sub-trigger"
+      data-inset={inset}
+      className={cn(
+        'focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground [&_svg:not([class*=text-])]:text-muted-foreground flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <ChevronRightIcon className="ml-auto size-4" />
+    </DropdownMenuPrimitive.SubTrigger>
+  );
+}
+
+function DropdownMenuSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+  return (
+    <DropdownMenuPrimitive.SubContent
+      data-slot="dropdown-menu-sub-content"
+      className={cn(
+        'bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  DropdownMenu,
+  DropdownMenuPortal,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+};
diff --git a/src/primitives/Input.tsx b/src/primitives/Input.tsx
new file mode 100644
index 0000000..b1d6493
--- /dev/null
+++ b/src/primitives/Input.tsx
@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { cn } from '../utils/cn';
+
+function Input({ className, type, ...props }: React.ComponentProps<'input'>) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        'file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground border-input h-9 w-full min-w-0 rounded-md border px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+        'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+        'aria-invalid:ring-destructive/20 aria-invalid:border-destructive',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Input };
diff --git a/src/primitives/Label.tsx b/src/primitives/Label.tsx
new file mode 100644
index 0000000..3253d08
--- /dev/null
+++ b/src/primitives/Label.tsx
@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { Label as LabelPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function Label({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>) {
+  return (
+    <LabelPrimitive.Root
+      data-slot="label"
+      className={cn(
+        'flex items-center gap-2 text-sm leading-none font-normal select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Label };
diff --git a/src/primitives/Popover.tsx b/src/primitives/Popover.tsx
new file mode 100644
index 0000000..8f4e753
--- /dev/null
+++ b/src/primitives/Popover.tsx
@@ -0,0 +1,71 @@
+import * as React from 'react';
+import { Popover as PopoverPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function Popover({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Root>) {
+  return <PopoverPrimitive.Root data-slot="popover" {...props} />;
+}
+
+function PopoverTrigger({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
+  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />;
+}
+
+function PopoverContent({
+  className,
+  align = 'center',
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Content>) {
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Content
+        data-slot="popover-content"
+        align={align}
+        sideOffset={sideOffset}
+        className={cn(
+          'bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden',
+          className
+        )}
+        {...props}
+      />
+    </PopoverPrimitive.Portal>
+  );
+}
+
+function PopoverAnchor({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Anchor>) {
+  return <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />;
+}
+
+function PopoverHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="popover-header"
+      className={cn('flex flex-col gap-1 text-sm', className)}
+      {...props}
+    />
+  );
+}
+
+function PopoverTitle({ className, ...props }: React.ComponentProps<'h2'>) {
+  return <div data-slot="popover-title" className={cn('font-medium', className)} {...props} />;
+}
+
+function PopoverDescription({ className, ...props }: React.ComponentProps<'p'>) {
+  return (
+    <p
+      data-slot="popover-description"
+      className={cn('text-muted-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverAnchor,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverDescription,
+};
diff --git a/src/primitives/Progress.tsx b/src/primitives/Progress.tsx
new file mode 100644
index 0000000..42f93a0
--- /dev/null
+++ b/src/primitives/Progress.tsx
@@ -0,0 +1,28 @@
+import * as React from 'react';
+import { Progress as ProgressPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function Progress({
+  className,
+  value,
+  ...props
+}: React.ComponentProps<typeof ProgressPrimitive.Root>) {
+  return (
+    <ProgressPrimitive.Root
+      data-slot="progress"
+      className={cn(
+        'bg-primary/20 relative h-2 w-full overflow-hidden rounded-full',
+        className
+      )}
+      {...props}
+    >
+      <ProgressPrimitive.Indicator
+        data-slot="progress-indicator"
+        className="bg-primary h-full w-full flex-1 transition-all"
+        style={{ transform: `translateX(-${100 - (value || 0)}%)` }}
+      />
+    </ProgressPrimitive.Root>
+  );
+}
+
+export { Progress };
diff --git a/src/primitives/RadioGroup.tsx b/src/primitives/RadioGroup.tsx
new file mode 100644
index 0000000..8eae992
--- /dev/null
+++ b/src/primitives/RadioGroup.tsx
@@ -0,0 +1,42 @@
+import * as React from 'react';
+import { CircleIcon } from 'lucide-react';
+import { RadioGroup as RadioGroupPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function RadioGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof RadioGroupPrimitive.Root>) {
+  return (
+    <RadioGroupPrimitive.Root
+      data-slot="radio-group"
+      className={cn('grid gap-3', className)}
+      {...props}
+    />
+  );
+}
+
+function RadioGroupItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof RadioGroupPrimitive.Item>) {
+  return (
+    <RadioGroupPrimitive.Item
+      data-slot="radio-group-item"
+      className={cn(
+        'border-input text-primary focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 aria-invalid:border-destructive aspect-square size-4 shrink-0 rounded-full border shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50',
+        className
+      )}
+      {...props}
+    >
+      <RadioGroupPrimitive.Indicator
+        data-slot="radio-group-indicator"
+        className="relative flex items-center justify-center"
+      >
+        <CircleIcon className="fill-primary absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2" />
+      </RadioGroupPrimitive.Indicator>
+    </RadioGroupPrimitive.Item>
+  );
+}
+
+export { RadioGroup, RadioGroupItem };
diff --git a/src/primitives/ScrollArea.tsx b/src/primitives/ScrollArea.tsx
new file mode 100644
index 0000000..d7b48f6
--- /dev/null
+++ b/src/primitives/ScrollArea.tsx
@@ -0,0 +1,53 @@
+import * as React from 'react';
+import { ScrollArea as ScrollAreaPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function ScrollArea({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.Root>) {
+  return (
+    <ScrollAreaPrimitive.Root
+      data-slot="scroll-area"
+      className={cn('relative', className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport
+        data-slot="scroll-area-viewport"
+        className="focus-visible:ring-ring/50 size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:outline-1"
+      >
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  );
+}
+
+function ScrollBar({
+  className,
+  orientation = 'vertical',
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>) {
+  return (
+    <ScrollAreaPrimitive.ScrollAreaScrollbar
+      data-slot="scroll-area-scrollbar"
+      orientation={orientation}
+      className={cn(
+        'flex touch-none p-px transition-colors select-none',
+        orientation === 'vertical' && 'h-full w-2.5 border-l border-l-transparent',
+        orientation === 'horizontal' && 'h-2.5 flex-col border-t border-t-transparent',
+        className
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.ScrollAreaThumb
+        data-slot="scroll-area-thumb"
+        className="bg-border relative flex-1 rounded-full"
+      />
+    </ScrollAreaPrimitive.ScrollAreaScrollbar>
+  );
+}
+
+export { ScrollArea, ScrollBar };
diff --git a/src/primitives/SegmentedControl.tsx b/src/primitives/SegmentedControl.tsx
new file mode 100644
index 0000000..1b1e8e3
--- /dev/null
+++ b/src/primitives/SegmentedControl.tsx
@@ -0,0 +1,55 @@
+import * as React from 'react';
+import { Tabs as TabsPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+interface SegmentedControlOption {
+  label: string;
+  value: string;
+  disabled?: boolean;
+}
+
+interface SegmentedControlProps {
+  value: string;
+  onValueChange: (value: string) => void;
+  options: SegmentedControlOption[];
+  size?: 'xs' | 'sm';
+  className?: string;
+}
+
+const SegmentedControl = React.forwardRef<HTMLDivElement, SegmentedControlProps>(
+  ({ value, onValueChange, options, size = 'sm', className }, ref) => {
+    return (
+      <TabsPrimitive.Root value={value} onValueChange={onValueChange} ref={ref}>
+        <TabsPrimitive.List
+          data-slot="segmented-control"
+          className={cn(
+            'inline-flex items-center gap-0.5 rounded-lg bg-muted',
+            size === 'xs' ? 'h-7 p-1' : 'h-9 p-1',
+            className,
+          )}
+        >
+          {options.map((option) => (
+            <TabsPrimitive.Trigger
+              key={option.value}
+              value={option.value}
+              disabled={option.disabled}
+              className={cn(
+                'inline-flex h-full items-center justify-center rounded-md px-2 font-medium whitespace-nowrap transition-all',
+                'text-muted-foreground data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
+                'disabled:pointer-events-none disabled:opacity-50',
+                size === 'xs' ? 'text-xs' : 'text-sm',
+              )}
+            >
+              {option.label}
+            </TabsPrimitive.Trigger>
+          ))}
+        </TabsPrimitive.List>
+      </TabsPrimitive.Root>
+    );
+  },
+);
+
+SegmentedControl.displayName = 'SegmentedControl';
+
+export { SegmentedControl };
+export type { SegmentedControlOption, SegmentedControlProps };
diff --git a/src/primitives/Select.tsx b/src/primitives/Select.tsx
new file mode 100644
index 0000000..6ff13e6
--- /dev/null
+++ b/src/primitives/Select.tsx
@@ -0,0 +1,178 @@
+import * as React from 'react';
+import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from 'lucide-react';
+import { Select as SelectPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function Select({ ...props }: React.ComponentProps<typeof SelectPrimitive.Root>) {
+  return <SelectPrimitive.Root data-slot="select" {...props} />;
+}
+
+function SelectGroup({ ...props }: React.ComponentProps<typeof SelectPrimitive.Group>) {
+  return <SelectPrimitive.Group data-slot="select-group" {...props} />;
+}
+
+function SelectValue({ ...props }: React.ComponentProps<typeof SelectPrimitive.Value>) {
+  return <SelectPrimitive.Value data-slot="select-value" {...props} />;
+}
+
+function SelectTrigger({
+  className,
+  size = 'default',
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+  size?: 'sm' | 'default';
+}) {
+  return (
+    <SelectPrimitive.Trigger
+      data-slot="select-trigger"
+      data-size={size}
+      className={cn(
+        'border-input data-[placeholder]:text-muted-foreground [&_svg:not([class*=text-])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 aria-invalid:border-destructive flex w-full items-center justify-between gap-2 rounded-md border px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon asChild>
+        <ChevronDownIcon className="size-4 opacity-50" />
+      </SelectPrimitive.Icon>
+    </SelectPrimitive.Trigger>
+  );
+}
+
+function SelectContent({
+  className,
+  children,
+  position = 'item-aligned',
+  align = 'center',
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Content
+        data-slot="select-content"
+        className={cn(
+          'bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-50 max-h-(--radix-select-content-available-height) min-w-[8rem] origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border shadow-md',
+          position === 'popper' &&
+            'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1',
+          className
+        )}
+        position={position}
+        align={align}
+        {...props}
+      >
+        <SelectScrollUpButton />
+        <SelectPrimitive.Viewport
+          className={cn(
+            'p-1',
+            position === 'popper' &&
+              'h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)] scroll-my-1'
+          )}
+        >
+          {children}
+        </SelectPrimitive.Viewport>
+        <SelectScrollDownButton />
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Portal>
+  );
+}
+
+function SelectLabel({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Label>) {
+  return (
+    <SelectPrimitive.Label
+      data-slot="select-label"
+      className={cn('text-muted-foreground px-2 py-1.5 text-xs', className)}
+      {...props}
+    />
+  );
+}
+
+function SelectItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+  return (
+    <SelectPrimitive.Item
+      data-slot="select-item"
+      className={cn(
+        'focus:bg-accent focus:text-accent-foreground [&_svg:not([class*=text-])]:text-muted-foreground relative flex w-full cursor-default items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2',
+        className
+      )}
+      {...props}
+    >
+      <span
+        data-slot="select-item-indicator"
+        className="absolute right-2 flex size-3.5 items-center justify-center"
+      >
+        <SelectPrimitive.ItemIndicator>
+          <CheckIcon className="size-4" />
+        </SelectPrimitive.ItemIndicator>
+      </span>
+      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+    </SelectPrimitive.Item>
+  );
+}
+
+function SelectSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
+  return (
+    <SelectPrimitive.Separator
+      data-slot="select-separator"
+      className={cn('bg-border pointer-events-none -mx-1 my-1 h-px', className)}
+      {...props}
+    />
+  );
+}
+
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+  return (
+    <SelectPrimitive.ScrollUpButton
+      data-slot="select-scroll-up-button"
+      className={cn(
+        'flex cursor-default items-center justify-center py-1',
+        className
+      )}
+      {...props}
+    >
+      <ChevronUpIcon className="size-4" />
+    </SelectPrimitive.ScrollUpButton>
+  );
+}
+
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+  return (
+    <SelectPrimitive.ScrollDownButton
+      data-slot="select-scroll-down-button"
+      className={cn(
+        'flex cursor-default items-center justify-center py-1',
+        className
+      )}
+      {...props}
+    >
+      <ChevronDownIcon className="size-4" />
+    </SelectPrimitive.ScrollDownButton>
+  );
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+};
diff --git a/src/primitives/Separator.tsx b/src/primitives/Separator.tsx
new file mode 100644
index 0000000..8b0ce39
--- /dev/null
+++ b/src/primitives/Separator.tsx
@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { Separator as SeparatorPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function Separator({
+  className,
+  orientation = 'horizontal',
+  decorative = true,
+  ...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+  return (
+    <SeparatorPrimitive.Root
+      data-slot="separator"
+      decorative={decorative}
+      orientation={orientation}
+      className={cn(
+        'bg-border shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Separator };
diff --git a/src/primitives/Sheet.tsx b/src/primitives/Sheet.tsx
new file mode 100644
index 0000000..bdb976e
--- /dev/null
+++ b/src/primitives/Sheet.tsx
@@ -0,0 +1,133 @@
+import * as React from 'react';
+import { XIcon } from 'lucide-react';
+import { Dialog as SheetPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
+  return <SheetPrimitive.Root data-slot="sheet" {...props} />;
+}
+
+function SheetTrigger({ ...props }: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
+  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />;
+}
+
+function SheetClose({ ...props }: React.ComponentProps<typeof SheetPrimitive.Close>) {
+  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />;
+}
+
+function SheetPortal({ ...props }: React.ComponentProps<typeof SheetPrimitive.Portal>) {
+  return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />;
+}
+
+function SheetOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
+  return (
+    <SheetPrimitive.Overlay
+      data-slot="sheet-overlay"
+      className={cn(
+        'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function SheetContent({
+  className,
+  children,
+  side = 'right',
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Content> & {
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  showCloseButton?: boolean;
+}) {
+  return (
+    <SheetPortal>
+      <SheetOverlay />
+      <SheetPrimitive.Content
+        data-slot="sheet-content"
+        className={cn(
+          'bg-background data-[state=open]:animate-in data-[state=closed]:animate-out fixed z-50 flex flex-col gap-4 shadow-lg transition ease-in-out data-[state=closed]:duration-300 data-[state=open]:duration-500',
+          side === 'right' &&
+            'data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right inset-y-0 right-0 h-full w-3/4 border-l sm:max-w-sm',
+          side === 'left' &&
+            'data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left inset-y-0 left-0 h-full w-3/4 border-r sm:max-w-sm',
+          side === 'top' &&
+            'data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top inset-x-0 top-0 h-auto border-b',
+          side === 'bottom' &&
+            'data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom inset-x-0 bottom-0 h-auto border-t',
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <SheetPrimitive.Close className="ring-offset-background focus:ring-ring data-[state=open]:bg-secondary absolute top-4 right-4 rounded-xs opacity-70 transition-opacity hover:opacity-100 focus:ring-2 focus:ring-offset-2 focus:outline-hidden disabled:pointer-events-none">
+            <XIcon className="size-4" />
+            <span className="sr-only">Close</span>
+          </SheetPrimitive.Close>
+        )}
+      </SheetPrimitive.Content>
+    </SheetPortal>
+  );
+}
+
+function SheetHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="sheet-header"
+      className={cn('flex flex-col gap-1.5 p-4', className)}
+      {...props}
+    />
+  );
+}
+
+function SheetFooter({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="sheet-footer"
+      className={cn('mt-auto flex flex-col gap-2 p-4', className)}
+      {...props}
+    />
+  );
+}
+
+function SheetTitle({ className, ...props }: React.ComponentProps<typeof SheetPrimitive.Title>) {
+  return (
+    <SheetPrimitive.Title
+      data-slot="sheet-title"
+      className={cn('text-foreground font-semibold', className)}
+      {...props}
+    />
+  );
+}
+
+function SheetDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Description>) {
+  return (
+    <SheetPrimitive.Description
+      data-slot="sheet-description"
+      className={cn('text-muted-foreground text-sm', className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Sheet,
+  SheetPortal,
+  SheetOverlay,
+  SheetTrigger,
+  SheetClose,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+};
diff --git a/src/primitives/Skeleton.tsx b/src/primitives/Skeleton.tsx
new file mode 100644
index 0000000..c36e316
--- /dev/null
+++ b/src/primitives/Skeleton.tsx
@@ -0,0 +1,14 @@
+import * as React from 'react';
+import { cn } from '../utils/cn';
+
+function Skeleton({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="skeleton"
+      className={cn('bg-accent animate-pulse rounded-md', className)}
+      {...props}
+    />
+  );
+}
+
+export { Skeleton };
diff --git a/src/primitives/Spinner.tsx b/src/primitives/Spinner.tsx
new file mode 100644
index 0000000..b980ddb
--- /dev/null
+++ b/src/primitives/Spinner.tsx
@@ -0,0 +1,34 @@
+import React, { forwardRef } from 'react';
+import { cn } from '../utils/cn';
+
+const sizeMap = {
+  sm: 'h-4 w-4',
+  md: 'h-8 w-8',
+  lg: 'h-12 w-12',
+} as const;
+
+export interface SpinnerProps extends React.HTMLAttributes<HTMLDivElement> {
+  size?: keyof typeof sizeMap;
+  styles?: { root?: React.CSSProperties };
+}
+
+export const Spinner = forwardRef<HTMLDivElement, SpinnerProps>(
+  ({ className, size = 'md', styles, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        role="status"
+        className={cn(
+          'animate-spin rounded-full border-2 border-current border-t-transparent text-primary-500',
+          sizeMap[size],
+          className,
+        )}
+        style={styles?.root}
+        {...props}
+      >
+        <span className="sr-only">Loading...</span>
+      </div>
+    );
+  },
+);
+Spinner.displayName = 'Spinner';
diff --git a/src/primitives/Switch.tsx b/src/primitives/Switch.tsx
new file mode 100644
index 0000000..8c1febb
--- /dev/null
+++ b/src/primitives/Switch.tsx
@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { Switch as SwitchPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function Switch({
+  className,
+  size = 'default',
+  ...props
+}: React.ComponentProps<typeof SwitchPrimitive.Root> & {
+  size?: 'sm' | 'default';
+}) {
+  return (
+    <SwitchPrimitive.Root
+      data-slot="switch"
+      data-size={size}
+      className={cn(
+        'peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 group/switch inline-flex shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-[1.15rem] data-[size=default]:w-8 data-[size=sm]:h-3.5 data-[size=sm]:w-6',
+        className
+      )}
+      {...props}
+    >
+      <SwitchPrimitive.Thumb
+        data-slot="switch-thumb"
+        className={cn(
+          'bg-background pointer-events-none block rounded-full ring-0 transition-transform group-data-[size=default]/switch:size-4 group-data-[size=sm]/switch:size-3 data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-0'
+        )}
+      />
+    </SwitchPrimitive.Root>
+  );
+}
+
+export { Switch };
diff --git a/src/primitives/Tabs.tsx b/src/primitives/Tabs.tsx
index 852d701..250407e 100644
--- a/src/primitives/Tabs.tsx
+++ b/src/primitives/Tabs.tsx
@@ -1,118 +1,109 @@
-import {
-  createContext,
-  forwardRef,
-  useContext,
-  useState,
-  type HTMLAttributes,
-} from 'react';
+import { forwardRef } from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Tabs as TabsPrimitive } from 'radix-ui';
 import { cn } from '../utils/cn';
 
-interface TabsContextValue {
-  activeTab: string;
-  setActiveTab: (value: string) => void;
-}
-
-const TabsContext = createContext<TabsContextValue | null>(null);
-
-function useTabsContext() {
-  const ctx = useContext(TabsContext);
-  if (!ctx) throw new Error('Tabs compound components must be used within <Tabs>');
-  return ctx;
-}
-
-export interface TabsProps extends HTMLAttributes<HTMLDivElement> {
-  defaultValue: string;
-  value?: string;
-  onValueChange?: (value: string) => void;
+export interface TabsProps
+  extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.Root> {
   styles?: { root?: React.CSSProperties };
 }
 
-export const Tabs = forwardRef<HTMLDivElement, TabsProps>(
-  ({ defaultValue, value, onValueChange, className, styles, children, ...props }, ref) => {
-    const [internal, setInternal] = useState(defaultValue);
-    const activeTab = value ?? internal;
-    const setActiveTab = (v: string) => {
-      setInternal(v);
-      onValueChange?.(v);
-    };
+export const Tabs = forwardRef<
+  React.ComponentRef<typeof TabsPrimitive.Root>,
+  TabsProps
+>(({ className, orientation = 'horizontal', styles, ...props }, ref) => (
+  <TabsPrimitive.Root
+    ref={ref}
+    data-slot="tabs"
+    data-orientation={orientation}
+    orientation={orientation}
+    className={cn(
+      'group/tabs flex gap-2 data-[orientation=horizontal]:flex-col',
+      className,
+    )}
+    style={styles?.root}
+    {...props}
+  />
+));
+Tabs.displayName = 'Tabs';
 
-    return (
-      <TabsContext.Provider value={{ activeTab, setActiveTab }}>
-        <div ref={ref} className={className} style={styles?.root} {...props}>
-          {children}
-        </div>
-      </TabsContext.Provider>
-    );
+const tabsListVariants = cva(
+  'rounded-lg p-[3px] group-data-[orientation=horizontal]/tabs:h-9 data-[variant=line]:rounded-none group/tabs-list text-muted-foreground inline-flex w-fit items-center justify-center group-data-[orientation=vertical]/tabs:h-fit group-data-[orientation=vertical]/tabs:flex-col',
+  {
+    variants: {
+      variant: {
+        default: 'bg-muted',
+        line: 'gap-1 bg-transparent',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
   },
 );
-Tabs.displayName = 'Tabs';
 
-export interface TabsListProps extends HTMLAttributes<HTMLDivElement> {}
+export interface TabsListProps
+  extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.List>,
+    VariantProps<typeof tabsListVariants> {}
 
-export const TabsList = forwardRef<HTMLDivElement, TabsListProps>(
-  ({ className, ...props }, ref) => (
-    <div
-      ref={ref}
-      role="tablist"
-      className={cn(
-        'inline-flex items-center gap-1 border-b border-border',
-        className,
-      )}
-      {...props}
-    />
-  ),
-);
+export const TabsList = forwardRef<
+  React.ComponentRef<typeof TabsPrimitive.List>,
+  TabsListProps
+>(({ className, variant = 'default', ...props }, ref) => (
+  <TabsPrimitive.List
+    ref={ref}
+    data-slot="tabs-list"
+    data-variant={variant}
+    className={cn(tabsListVariants({ variant }), className)}
+    {...props}
+  />
+));
 TabsList.displayName = 'TabsList';
 
-export interface TabsTriggerProps extends HTMLAttributes<HTMLButtonElement> {
-  value: string;
-}
+export interface TabsTriggerProps
+  extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger> {}
 
-export const TabsTrigger = forwardRef<HTMLButtonElement, TabsTriggerProps>(
-  ({ value, className, ...props }, ref) => {
-    const { activeTab, setActiveTab } = useTabsContext();
-    const isActive = activeTab === value;
-
-    return (
-      <button
-        ref={ref}
-        role="tab"
-        type="button"
-        aria-selected={isActive}
-        data-state={isActive ? 'active' : 'inactive'}
-        className={cn(
-          'px-4 py-2 text-sm font-medium transition-colors cursor-pointer',
-          'border-b-2 -mb-px',
-          isActive
-            ? 'border-primary text-primary'
-            : 'border-transparent text-muted-foreground hover:text-foreground',
-          className,
-        )}
-        onClick={() => setActiveTab(value)}
-        {...props}
-      />
-    );
-  },
-);
+export const TabsTrigger = forwardRef<
+  React.ComponentRef<typeof TabsPrimitive.Trigger>,
+  TabsTriggerProps
+>(({ className, ...props }, ref) => (
+  <TabsPrimitive.Trigger
+    ref={ref}
+    data-slot="tabs-trigger"
+    className={cn(
+      'text-foreground/60 hover:text-foreground relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap transition-all cursor-pointer',
+      'group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start',
+      'disabled:pointer-events-none disabled:opacity-50',
+      'group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm',
+      'group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none',
+      '[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+      'group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent',
+      'data-[state=active]:bg-background data-[state=active]:text-foreground',
+      'after:bg-foreground after:absolute after:opacity-0 after:transition-opacity',
+      'group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-5px] group-data-[orientation=horizontal]/tabs:after:h-0.5',
+      'group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-right-1 group-data-[orientation=vertical]/tabs:after:w-0.5',
+      'group-data-[variant=line]/tabs-list:data-[state=active]:after:opacity-100',
+      className,
+    )}
+    {...props}
+  />
+));
 TabsTrigger.displayName = 'TabsTrigger';
 
-export interface TabsContentProps extends HTMLAttributes<HTMLDivElement> {
-  value: string;
-}
-
-export const TabsContent = forwardRef<HTMLDivElement, TabsContentProps>(
-  ({ value, className, ...props }, ref) => {
-    const { activeTab } = useTabsContext();
-    if (activeTab !== value) return null;
+export interface TabsContentProps
+  extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.Content> {}
 
-    return (
-      <div
-        ref={ref}
-        role="tabpanel"
-        className={cn('pt-4', className)}
-        {...props}
-      />
-    );
-  },
-);
+export const TabsContent = forwardRef<
+  React.ComponentRef<typeof TabsPrimitive.Content>,
+  TabsContentProps
+>(({ className, ...props }, ref) => (
+  <TabsPrimitive.Content
+    ref={ref}
+    data-slot="tabs-content"
+    className={cn('flex-1 outline-none', className)}
+    {...props}
+  />
+));
 TabsContent.displayName = 'TabsContent';
+
+export { tabsListVariants };
diff --git a/src/primitives/Text.tsx b/src/primitives/Text.tsx
new file mode 100644
index 0000000..ed93e0e
--- /dev/null
+++ b/src/primitives/Text.tsx
@@ -0,0 +1,64 @@
+import React, { forwardRef } from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '../utils/cn';
+
+// Mantine color aliases -- "dimmed" was the most common
+const COLOR_ALIASES: Record<string, string> = {
+  dimmed: '#9CA3AF',
+};
+
+const textVariants = cva('', {
+  variants: {
+    size: {
+      xs: 'text-xs',
+      sm: 'text-sm',
+      md: 'text-base',
+      lg: 'text-lg',
+      xl: 'text-xl',
+    },
+    weight: {
+      normal: 'font-normal',
+      medium: 'font-medium',
+      semibold: 'font-semibold',
+      bold: 'font-bold',
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+  },
+});
+
+export interface TextProps
+  extends React.HTMLAttributes<HTMLElement>,
+    VariantProps<typeof textVariants> {
+  span?: boolean;
+  fw?: number;
+  c?: string;
+  component?: React.ElementType;
+  styles?: { root?: React.CSSProperties };
+}
+
+export const Text = forwardRef<HTMLElement, TextProps>(
+  (
+    { className, size, weight, span, fw, c, component, style, styles, children, ...props },
+    ref,
+  ) => {
+    const Component = component || (span ? 'span' : 'p');
+    const fontWeightStyle = fw ? { fontWeight: fw } : undefined;
+    const colorStyle = c ? { color: COLOR_ALIASES[c] || c } : undefined;
+
+    return (
+      <Component
+        ref={ref}
+        className={cn(textVariants({ size, weight }), className)}
+        style={{ ...fontWeightStyle, ...colorStyle, ...styles?.root, ...style }}
+        {...props}
+      >
+        {children}
+      </Component>
+    );
+  },
+);
+Text.displayName = 'Text';
+
+export { textVariants };
diff --git a/src/primitives/Textarea.tsx b/src/primitives/Textarea.tsx
new file mode 100644
index 0000000..290b980
--- /dev/null
+++ b/src/primitives/Textarea.tsx
@@ -0,0 +1,17 @@
+import * as React from 'react';
+import { cn } from '../utils/cn';
+
+function Textarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        'border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 aria-invalid:border-destructive flex field-sizing-content min-h-16 w-full rounded-md border px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Textarea };
diff --git a/src/primitives/Title.tsx b/src/primitives/Title.tsx
new file mode 100644
index 0000000..65b7510
--- /dev/null
+++ b/src/primitives/Title.tsx
@@ -0,0 +1,34 @@
+import React, { forwardRef } from 'react';
+import { cn } from '../utils/cn';
+
+const orderStyles = {
+  1: 'text-4xl font-bold',
+  2: 'text-3xl font-bold',
+  3: 'text-2xl font-semibold',
+  4: 'text-xl font-semibold',
+  5: 'text-lg font-medium',
+  6: 'text-base font-medium',
+} as const;
+
+export interface TitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  order?: 1 | 2 | 3 | 4 | 5 | 6;
+  styles?: { root?: React.CSSProperties };
+}
+
+export const Title = forwardRef<HTMLHeadingElement, TitleProps>(
+  ({ className, order = 1, styles, children, ...props }, ref) => {
+    const Component = `h${order}` as const;
+
+    return (
+      <Component
+        ref={ref as React.Ref<HTMLHeadingElement>}
+        className={cn(orderStyles[order], className)}
+        style={styles?.root}
+        {...props}
+      >
+        {children}
+      </Component>
+    );
+  },
+);
+Title.displayName = 'Title';
diff --git a/src/primitives/Tooltip.tsx b/src/primitives/Tooltip.tsx
new file mode 100644
index 0000000..87896fe
--- /dev/null
+++ b/src/primitives/Tooltip.tsx
@@ -0,0 +1,50 @@
+import * as React from 'react';
+import { Tooltip as TooltipPrimitive } from 'radix-ui';
+import { cn } from '../utils/cn';
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  );
+}
+
+function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
+}
+
+function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          'bg-foreground text-background animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance',
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="bg-foreground fill-foreground z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  );
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider };
diff --git a/src/primitives/index.ts b/src/primitives/index.ts
index 842ba88..f92792d 100644
--- a/src/primitives/index.ts
+++ b/src/primitives/index.ts
@@ -6,6 +6,7 @@ export {
   CardDescription,
   CardContent,
   CardFooter,
+  CardAction,
   type CardProps,
 } from './Card';
 export { Badge, badgeVariants, type BadgeProps } from './Badge';
@@ -18,4 +19,100 @@ export {
   type TabsListProps,
   type TabsTriggerProps,
   type TabsContentProps,
+  tabsListVariants,
 } from './Tabs';
+export { Text, textVariants, type TextProps } from './Text';
+export { Title, type TitleProps } from './Title';
+export { Spinner, type SpinnerProps } from './Spinner';
+
+// Phase 3a: Radix primitives (high priority)
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+} from './Dialog';
+export {
+  Sheet,
+  SheetPortal,
+  SheetOverlay,
+  SheetTrigger,
+  SheetClose,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+} from './Sheet';
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from './Tooltip';
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from './Select';
+export {
+  DropdownMenu,
+  DropdownMenuPortal,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+} from './DropdownMenu';
+export { Input } from './Input';
+export { Label } from './Label';
+export { Separator } from './Separator';
+
+// Phase 3b: Medium priority primitives
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from './Accordion';
+export { Alert, AlertTitle, AlertDescription } from './Alert';
+export {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverAnchor,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverDescription,
+} from './Popover';
+export { Switch } from './Switch';
+export { RadioGroup, RadioGroupItem } from './RadioGroup';
+export { Checkbox } from './Checkbox';
+export { ScrollArea, ScrollBar } from './ScrollArea';
+export { Skeleton } from './Skeleton';
+export { Progress } from './Progress';
+export { Collapsible, CollapsibleTrigger, CollapsibleContent } from './Collapsible';
+export { Textarea } from './Textarea';
+export {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+} from './Command';
+export { SegmentedControl, type SegmentedControlProps } from './SegmentedControl';
diff --git a/src/theme/tokens.css b/src/theme/tokens.css
index 434853f..0ad2b1b 100644
--- a/src/theme/tokens.css
+++ b/src/theme/tokens.css
@@ -2,7 +2,7 @@
 
 @custom-variant dark (&:is(.dark *));
 
-@source "../**/*.{ts,tsx}";
+@source "../../dist/**/*.js";
 
 /* ============================================================
  * PolicyEngine Design Tokens
@@ -64,6 +64,21 @@
   --chart-3: #285E61;
   --chart-4: #026AA2;
   --chart-5: #6B7280;
+
+  /* Background variants */
+  --background-secondary: #f5f9ff;
+  --background-tertiary: #f1f5f9;
+
+  /* Border scale */
+  --border-light: #e2e8f0;
+  --border-medium: #cbd5e1;
+  --border-dark: #94a3b8;
+
+  /* Text semantic aliases */
+  --text-primary: #000000;
+  --text-secondary: #5a5a5a;
+  --text-tertiary: #9ca3af;
+  --text-inverse: #ffffff;
 }
 
 /* --- Layer 2: Tailwind @theme inline (bridges :root vars to Tailwind utilities) --- */
@@ -94,6 +109,15 @@
   --color-chart-4: var(--chart-4);
   --color-chart-5: var(--chart-5);
 
+  /* Additional backgrounds */
+  --color-background-secondary: var(--background-secondary);
+  --color-background-tertiary: var(--background-tertiary);
+
+  /* Border scale */
+  --color-border-light: var(--border-light);
+  --color-border-medium: var(--border-medium);
+  --color-border-dark: var(--border-dark);
+
   /* Radius derived from base --radius */
   --radius-sm: calc(var(--radius) - 2px);
   --radius-md: var(--radius);
@@ -168,9 +192,16 @@
   --text-4xl: 32px;
   --text-4xl--line-height: 40px;
 
+  /* Semantic radius */
+  --radius-chip: 2px;
+  --radius-element: 4px;
+  --radius-container: 8px;
+  --radius-feature: 12px;
+
   /* Named spacing */
   --spacing-header: 58px;
   --spacing-sidebar: 280px;
+  --spacing-sidebar-width: 280px;
   --spacing-content: 976px;
 
   /* Breakpoints */

From a758ac03ae1fc788da79dae11933a446ea4de1d8 Mon Sep 17 00:00:00 2001
From: Anthony Volk <anth.volk@gmail.com>
Date: Fri, 13 Mar 2026 20:38:59 +0100
Subject: [PATCH 6/7] Add CI/CD: automated versioning, changelog, and npm
 publish

- bump_version.py: scans changelog.d/ fragments, bumps package.json semver
- build_changelog.py: compiles fragments into CHANGELOG.md, deletes consumed
- push.yml: on merge to main, bumps version, builds changelog, publishes to npm
- Requires NPM_TOKEN secret on the GitHub repo

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .github/build_changelog.py | 145 +++++++++++++++++++++++++++++++++++++
 .github/bump_version.py    |  79 ++++++++++++++++++++
 .github/workflows/push.yml |  66 +++++++++++++++++
 CHANGELOG.md               |   1 +
 4 files changed, 291 insertions(+)
 create mode 100644 .github/build_changelog.py
 create mode 100644 .github/bump_version.py
 create mode 100644 .github/workflows/push.yml
 create mode 100644 CHANGELOG.md

diff --git a/.github/build_changelog.py b/.github/build_changelog.py
new file mode 100644
index 0000000..bdde7eb
--- /dev/null
+++ b/.github/build_changelog.py
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Build CHANGELOG.md from changelog.d/ fragments."""
+
+import json
+import os
+import sys
+from datetime import date
+
+CHANGELOG_DIR = "changelog.d"
+CHANGELOG_PATH = "CHANGELOG.md"
+PACKAGE_PATH = "package.json"
+
+TYPE_HEADING = {
+    "added": "Added",
+    "changed": "Changed",
+    "fixed": "Fixed",
+    "removed": "Removed",
+    "breaking": "Breaking",
+}
+TYPE_ORDER = ["Added", "Changed", "Fixed", "Removed", "Breaking"]
+
+
+def get_current_version():
+    with open(PACKAGE_PATH) as f:
+        data = json.load(f)
+    return data["version"]
+
+
+def get_previous_version():
+    """Read the most recent version from existing CHANGELOG.md."""
+    if not os.path.exists(CHANGELOG_PATH):
+        return "0.0.0"
+    with open(CHANGELOG_PATH) as f:
+        for line in f:
+            if line.startswith("## ["):
+                return line.split("[")[1].split("]")[0]
+    return "0.0.0"
+
+
+def read_fragments():
+    """Read all fragments and group by type heading."""
+    groups = {}
+    for fname in sorted(os.listdir(CHANGELOG_DIR)):
+        if fname == ".gitkeep":
+            continue
+        parts = fname.rsplit(".", 2)
+        if len(parts) != 3 or parts[2] != "md":
+            continue
+        fragment_type = parts[1]
+        heading = TYPE_HEADING.get(fragment_type, fragment_type.capitalize())
+        with open(os.path.join(CHANGELOG_DIR, fname)) as f:
+            content = f.read().strip()
+        if content:
+            groups.setdefault(heading, []).append(content)
+    return groups
+
+
+def build_section(version, groups):
+    """Build a Keep a Changelog section."""
+    lines = [f"## [{version}] - {date.today().isoformat()}", ""]
+    for heading in TYPE_ORDER:
+        if heading not in groups:
+            continue
+        lines.append(f"### {heading}")
+        lines.append("")
+        for entry in groups[heading]:
+            for raw_line in entry.splitlines():
+                raw_line = raw_line.strip()
+                if not raw_line:
+                    continue
+                if not raw_line.startswith("- "):
+                    raw_line = f"- {raw_line}"
+                lines.append(raw_line)
+        lines.append("")
+    return "\n".join(lines)
+
+
+def update_changelog(new_section, version, old_version):
+    """Prepend new section to CHANGELOG.md and add comparison link."""
+    if os.path.exists(CHANGELOG_PATH):
+        with open(CHANGELOG_PATH) as f:
+            content = f.read()
+    else:
+        content = "# Changelog\n"
+
+    # Insert new section before the first existing ## entry
+    marker = "\n## ["
+    pos = content.find(marker)
+    if pos == -1:
+        # No existing entries — append after header
+        content = content.rstrip() + "\n\n" + new_section + "\n"
+    else:
+        header = content[: pos + 1]  # include the trailing newline
+        rest = content[pos + 1 :]
+        content = header + new_section + "\n" + rest
+
+    # Add comparison link at the top of the link reference section
+    link = (
+        f"[{version}]: https://github.com/PolicyEngine/"
+        f"policyengine-ui-kit/compare/{old_version}...{version}"
+    )
+    lines = content.split("\n")
+    new_lines = []
+    link_inserted = False
+    for line in lines:
+        if not link_inserted and line.startswith("[") and "]: https://" in line:
+            new_lines.append(link)
+            link_inserted = True
+        new_lines.append(line)
+    if not link_inserted:
+        new_lines.append("")
+        new_lines.append(link)
+    content = "\n".join(new_lines)
+
+    with open(CHANGELOG_PATH, "w") as f:
+        f.write(content)
+
+
+def delete_fragments():
+    """Remove consumed fragments, keeping .gitkeep."""
+    for fname in os.listdir(CHANGELOG_DIR):
+        if fname == ".gitkeep":
+            continue
+        os.remove(os.path.join(CHANGELOG_DIR, fname))
+
+
+def main():
+    has_fragments = any(f != ".gitkeep" for f in os.listdir(CHANGELOG_DIR))
+    if not has_fragments:
+        print("No changelog fragments found. Nothing to build.")
+        sys.exit(0)
+
+    version = get_current_version()
+    old_version = get_previous_version()
+    groups = read_fragments()
+
+    new_section = build_section(version, groups)
+    update_changelog(new_section, version, old_version)
+    delete_fragments()
+
+    print(f"Built changelog for version {version}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/bump_version.py b/.github/bump_version.py
new file mode 100644
index 0000000..dec9e9b
--- /dev/null
+++ b/.github/bump_version.py
@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Bump version in package.json based on changelog.d/ fragments."""
+
+import json
+import os
+import sys
+
+CHANGELOG_DIR = "changelog.d"
+PACKAGE_PATH = "package.json"
+
+# Lower number = higher priority bump
+BUMP_PRIORITY = {
+    "breaking": 0,  # major
+    "added": 1,     # minor
+    "removed": 1,   # minor
+    "changed": 2,   # patch
+    "fixed": 2,     # patch
+}
+
+
+def get_current_version():
+    with open(PACKAGE_PATH) as f:
+        data = json.load(f)
+    return data["version"]
+
+
+def get_bump_level():
+    """Scan fragment filenames to determine the highest-priority bump type."""
+    level = None
+    for fname in os.listdir(CHANGELOG_DIR):
+        if fname == ".gitkeep":
+            continue
+        # Expected format: {name}.{type}.md
+        parts = fname.rsplit(".", 2)
+        if len(parts) != 3 or parts[2] != "md":
+            continue
+        fragment_type = parts[1]
+        priority = BUMP_PRIORITY.get(fragment_type, 2)  # default to patch
+        if level is None or priority < level:
+            level = priority
+    return level
+
+
+def compute_new_version(version, level):
+    major, minor, patch = map(int, version.split("."))
+    if level == 0:
+        return f"{major + 1}.0.0"
+    elif level == 1:
+        return f"{major}.{minor + 1}.0"
+    else:
+        return f"{major}.{minor}.{patch + 1}"
+
+
+def main():
+    fragments = [f for f in os.listdir(CHANGELOG_DIR) if f != ".gitkeep"]
+    if not fragments:
+        print("No changelog fragments found. Nothing to bump.")
+        sys.exit(0)
+
+    old_version = get_current_version()
+    level = get_bump_level()
+    if level is None:
+        print("No valid fragments found. Nothing to bump.")
+        sys.exit(0)
+
+    new_version = compute_new_version(old_version, level)
+
+    with open(PACKAGE_PATH) as f:
+        data = json.load(f)
+    data["version"] = new_version
+    with open(PACKAGE_PATH, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+
+    print(f"Bumped version: {old_version} → {new_version}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
new file mode 100644
index 0000000..484f508
--- /dev/null
+++ b/.github/workflows/push.yml
@@ -0,0 +1,66 @@
+name: Version, Changelog, and Publish
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    name: Bump version, build changelog, publish to npm
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, 'Release @policyengine/ui-kit')"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.POLICYENGINE_GITHUB }}
+
+      - name: Check for changelog fragments
+        id: check
+        run: |
+          FRAGMENTS=$(ls changelog.d/ | grep -v .gitkeep | wc -l)
+          echo "count=$FRAGMENTS" >> "$GITHUB_OUTPUT"
+
+      - name: Bump version
+        if: steps.check.outputs.count != '0'
+        run: python .github/bump_version.py
+
+      - name: Build changelog
+        if: steps.check.outputs.count != '0'
+        run: python .github/build_changelog.py
+
+      - name: Set up Bun
+        if: steps.check.outputs.count != '0'
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        if: steps.check.outputs.count != '0'
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        if: steps.check.outputs.count != '0'
+        run: bun run build
+
+      - name: Set up Node for npm publish
+        if: steps.check.outputs.count != '0'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Publish to npm
+        if: steps.check.outputs.count != '0'
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Commit and push
+        if: steps.check.outputs.count != '0'
+        uses: EndBug/add-and-commit@v9
+        with:
+          message: "Release @policyengine/ui-kit"
+          default_author: github_actions
+          add: |
+            package.json
+            CHANGELOG.md
+            changelog.d/
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..825c32f
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1 @@
+# Changelog

From fe1fa9ee513fb244760b644597f7e3b91a622bee Mon Sep 17 00:00:00 2001
From: Anthony Volk <anth.volk@gmail.com>
Date: Sat, 14 Mar 2026 01:33:19 +0100
Subject: [PATCH 7/7] Fix Tabs test: use userEvent for Radix
 pointer-event-based switching

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 package.json                   | 1 +
 tests/primitives/Tabs.test.tsx | 9 +++++----
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/package.json b/package.json
index 1984daf..d4dbeea 100644
--- a/package.json
+++ b/package.json
@@ -52,6 +52,7 @@
     "@tailwindcss/vite": "^4.2.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.4",
diff --git a/tests/primitives/Tabs.test.tsx b/tests/primitives/Tabs.test.tsx
index bdf5e43..e53d3c0 100644
--- a/tests/primitives/Tabs.test.tsx
+++ b/tests/primitives/Tabs.test.tsx
@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { Tabs, TabsList, TabsTrigger, TabsContent } from '../../src/primitives/Tabs';
 
 describe('Tabs', () => {
@@ -15,10 +16,10 @@ describe('Tabs', () => {
       </Tabs>,
     );
     expect(screen.getByText('Content A')).toBeInTheDocument();
-    expect(screen.queryByText('Content B')).not.toBeInTheDocument();
   });
 
-  it('switches tabs on click', () => {
+  it('switches tabs on click', async () => {
+    const user = userEvent.setup();
     render(
       <Tabs defaultValue="a">
         <TabsList>
@@ -29,7 +30,7 @@ describe('Tabs', () => {
         <TabsContent value="b">Content B</TabsContent>
       </Tabs>,
     );
-    fireEvent.click(screen.getByText('Tab B'));
+    await user.click(screen.getByText('Tab B'));
     expect(screen.queryByText('Content A')).not.toBeInTheDocument();
     expect(screen.getByText('Content B')).toBeInTheDocument();
   });