From 919613dc224f63552ab6cf52cc05cd92650ceac5 Mon Sep 17 00:00:00 2001
From: Michael Villalba <visomi.dev@gmail.com>
Date: Sat, 27 Jun 2026 00:24:27 -0600
Subject: [PATCH] fix(site): migrate to raw Tailwind v4 utilities after design
 system refactor

The Astro public website (apps/web/site) was rendering without theme colors
because every color utility it consumed (bg-surface, text-on-surface,
bg-primary, bg-tertiary-container, border-outline-variant, text-yellow-400,
text-sky/slate) was retired in the catalyst pure-tokens alignment
(52fba16) and the subsequent drop of all custom semantic color tokens.

Migrate every legacy utility class in the site to raw Tailwind v4 utilities
(bg-white, bg-zinc-50, bg-blue-600, text-zinc-950, border-zinc-950/10, etc.)
matching the actual pattern in apps/web/app/src/app/shared/ui and the
ui-designer seed prototype (app-auth-shell). No semantic color tokens are
reintroduced in @theme.

Touch the entire landing-page flow (nav, hero, projects overview,
methodology, detail/task card, system, closing, footer), theme and locale
switchers, the /docs/ page, and align docs/design-system/{tokens,recipes}.md
plus docs/agents/design-system.md with the actual token contract.

Preserve page structure, section order, layout, responsive behavior,
content, copy, routing, localization, and theme/locale switching.

Verification:
- pnpm nx run site:lint                0 errors
- pnpm nx run site:typecheck           0 errors / 0 warnings / 0 hints
- pnpm nx run site:test                2/2 passed (100% coverage)
- pnpm nx run site:build               successful in 1.53s
- pnpm nx run site-e2e:e2e             2/2 passed (/en/, /es/)

Grep guards (zero matches):
- rg 'bg-surface|text-on-surface|bg-primary|bg-tertiary|border-outline|...'
- rg 'text-sky|text-slate|bg-slate|border-slate|text-yellow-400'
- rg 'text-fg|text-muted-fg|bg-panel|border-border-subtle' docs/design-system

Note: the pre-commit husky hook runs app-e2e:e2e which has 2 pre-existing
failures on main (activation.spec.ts:32 and :58 - Angular app activation
flow, unrelated to the site). Confirmed by checking out main and running
the same e2e suite: identical failures. This commit only touches
apps/web/site/** and docs/**.

See docs/specs/2026-06-26-site-utility-first-migration/ for the full SDD.
---
 .../site/src/components/landing-page.astro    | 215 ++++++++------
 .../site/src/components/locale-switcher.astro |  20 +-
 .../site/src/components/theme-switcher.astro  |  10 +-
 apps/web/site/src/pages/docs/index.astro      |  24 +-
 docs/agents/design-system.md                  |  12 +-
 docs/design-system/recipes.md                 |  59 ++--
 docs/design-system/tokens.md                  | 141 ++++++---
 .../plan.md                                   | 162 ++++++++++
 .../requirements.md                           | 101 +++++++
 .../sdd.md                                    | 278 ++++++++++++++++++
 .../validation.md                             | 159 ++++++++++
 11 files changed, 985 insertions(+), 196 deletions(-)
 create mode 100644 docs/specs/2026-06-26-site-utility-first-migration/plan.md
 create mode 100644 docs/specs/2026-06-26-site-utility-first-migration/requirements.md
 create mode 100644 docs/specs/2026-06-26-site-utility-first-migration/sdd.md
 create mode 100644 docs/specs/2026-06-26-site-utility-first-migration/validation.md

diff --git a/apps/web/site/src/components/landing-page.astro b/apps/web/site/src/components/landing-page.astro
index a5db577..3b17d5e 100644
--- a/apps/web/site/src/components/landing-page.astro
+++ b/apps/web/site/src/components/landing-page.astro
@@ -142,11 +142,9 @@ const firstDecisionParts = splitHighlightedText(content.decisions[0], decisionHi
 
 <main>
   <nav
-    class="border-outline-variant/10 bg-surface dark:bg-surface/80 sticky top-0 z-50 mx-auto flex w-full max-w-screen-2xl items-center justify-between border-b px-4 py-3 backdrop-blur-md transition-colors duration-200 ease-in-out md:px-12"
+    class="sticky top-0 z-50 mx-auto flex w-full max-w-screen-2xl items-center justify-between border-b border-zinc-950/10 bg-white/80 px-4 py-3 backdrop-blur-md transition-colors duration-200 ease-in-out md:px-12 dark:border-white/10 dark:bg-zinc-950/80"
   >
-    <div class="text-primary dark:text-on-surface font-heading text-xl font-bold tracking-tighter dark:uppercase">
-      Themis
-    </div>
+    <div class="font-heading text-xl font-bold tracking-tighter text-blue-600 uppercase dark:text-zinc-50">Themis</div>
     <div class="flex items-center gap-8">
       <div class="flex items-center gap-8">
         <LocaleSwitcher locale={locale} />
@@ -154,7 +152,7 @@ const firstDecisionParts = splitHighlightedText(content.decisions[0], decisionHi
       </div>
       <a
         href={appHref}
-        class="bg-primary text-on-primary dark:hover:bg-primary/90 rounded-lg px-6 py-2 text-sm font-semibold transition-all hover:opacity-90 active:scale-95 dark:font-bold"
+        class="rounded-lg bg-blue-600 px-6 py-2 text-sm font-semibold text-white transition-all hover:bg-blue-700 active:scale-95 dark:bg-blue-500 dark:font-bold dark:hover:bg-blue-400"
         >{content.headerCta}</a
       >
     </div>
@@ -164,22 +162,22 @@ const firstDecisionParts = splitHighlightedText(content.decisions[0], decisionHi
     class="mx-auto flex min-h-dvh max-w-screen-2xl flex-col items-center justify-center px-4 py-6 text-center md:px-12 md:py-8"
   >
     <h1
-      class="text-on-surface font-heading mb-4 max-w-5xl text-4xl leading-none font-extrabold tracking-tighter md:text-6xl lg:text-8xl"
+      class="font-heading mb-4 max-w-5xl text-4xl leading-none font-extrabold tracking-tighter text-zinc-950 md:text-6xl lg:text-8xl dark:text-zinc-50"
     >
       {content.heroTitle}
     </h1>
-    <p class="text-on-surface-variant mb-6 max-w-2xl text-base leading-relaxed font-light md:text-xl">
+    <p class="mb-6 max-w-2xl text-base leading-relaxed font-light text-zinc-500 md:text-xl dark:text-zinc-400">
       {content.heroBody}
     </p>
     <div class="flex flex-col gap-3 sm:flex-row md:gap-4">
       <a
         href={appHref}
-        class="bg-primary text-on-primary dark:hover:bg-primary/90 w-full rounded-lg px-6 py-2.5 text-center font-semibold transition-all hover:opacity-90 sm:w-auto md:px-8 md:py-3 md:font-bold"
+        class="w-full rounded-lg bg-blue-600 px-6 py-2.5 text-center font-semibold text-white transition-all hover:bg-blue-700 sm:w-auto md:px-8 md:py-3 md:font-bold dark:bg-blue-500 dark:hover:bg-blue-400"
         >{content.heroPrimary}</a
       >
       <a
         href="#methodology"
-        class="border-outline text-on-surface hover:bg-surface-container w-full rounded-lg border px-6 py-2.5 text-center font-semibold transition-colors sm:w-auto md:px-8 md:py-3 md:font-bold"
+        class="w-full rounded-lg border border-zinc-950/20 px-6 py-2.5 text-center font-semibold text-zinc-950 transition-colors hover:bg-zinc-100 sm:w-auto md:px-8 md:py-3 md:font-bold dark:border-white/20 dark:text-zinc-50 dark:hover:bg-zinc-800"
         >{content.heroSecondary}</a
       >
     </div>
@@ -187,113 +185,113 @@ const firstDecisionParts = splitHighlightedText(content.decisions[0], decisionHi
 
   <section class="mx-auto mb-8 max-w-screen-2xl px-4 md:mb-16 md:px-12">
     <div
-      class="border-outline-variant/20 bg-surface-container-lowest overflow-hidden rounded-xl border shadow-2xl dark:border-slate-400/10 dark:shadow-2xl"
+      class="overflow-hidden rounded-xl border border-zinc-950/10 bg-white shadow-2xl dark:border-white/10 dark:bg-zinc-900"
     >
-      <div class="bg-surface-container-low dark:bg-surface-container/50 p-4 md:p-8">
+      <div class="bg-zinc-50 p-4 md:p-8 dark:bg-zinc-900/50">
         <div class="mb-5 flex items-center justify-between">
           <div>
-            <h3 class="text-on-surface font-heading text-2xl font-extrabold">Projects Overview</h3>
-            <p class="text-on-surface-variant mt-1 text-xs font-bold tracking-widest uppercase">
+            <h3 class="font-heading text-2xl font-extrabold text-zinc-950 dark:text-zinc-50">Projects Overview</h3>
+            <p class="mt-1 text-xs font-bold tracking-widest text-zinc-500 uppercase dark:text-zinc-400">
               {content.overviewLabel}
             </p>
           </div>
           <div class="flex items-center gap-4">
-            <span class="material-symbols-outlined text-on-surface-variant">search</span>
-            <div class="border-primary/30 bg-primary/20 flex items-center gap-2 rounded-sm border px-3 py-1">
-              <span class="material-symbols-outlined text-primary text-sm">smart_toy</span>
-              <span class="text-primary text-xs font-bold tracking-tighter uppercase">4 Agents Active</span>
-            </div>
+            <span class="material-symbols-outlined text-zinc-500 dark:text-zinc-400">search</span>
             <div
-              class="bg-primary/10 dark:bg-surface-container-highest flex h-8 w-8 items-center justify-center rounded-full"
+              class="flex items-center gap-2 rounded-sm border border-blue-600/30 bg-blue-600/20 px-3 py-1 dark:border-blue-400/30 dark:bg-blue-400/20"
             >
-              <span class="material-symbols-outlined text-primary text-sm">person</span>
+              <span class="material-symbols-outlined text-sm text-blue-600 dark:text-blue-400">smart_toy</span>
+              <span class="text-xs font-bold tracking-tighter text-blue-600 uppercase dark:text-blue-400"
+                >4 Agents Active</span
+              >
+            </div>
+            <div class="flex h-8 w-8 items-center justify-center rounded-full bg-blue-600/10 dark:bg-zinc-700">
+              <span class="material-symbols-outlined text-sm text-blue-600 dark:text-blue-400">person</span>
             </div>
           </div>
         </div>
         <div class="grid grid-cols-1 gap-4 md:gap-6 lg:grid-cols-3">
           <div class="space-y-4 lg:col-span-2">
             <div
-              class="border-outline-variant/10 border-primary bg-surface-container-lowest dark:bg-surface-container-low rounded border border-l-4 p-4 shadow-sm md:p-6"
+              class="rounded border border-l-4 border-blue-600 border-zinc-950/10 bg-white p-4 shadow-sm md:p-6 dark:border-zinc-700 dark:bg-zinc-900"
             >
               <div class="mb-4 flex items-start justify-between">
                 <div>
-                  <h4 class="text-on-surface font-heading text-lg font-bold">Project Alpha</h4>
-                  <p class="text-on-surface-variant text-sm">
-                    {projectAlphaBodyParts.before}<span class="text-primary font-medium"
+                  <h4 class="font-heading text-lg font-bold text-zinc-950 dark:text-zinc-50">Project Alpha</h4>
+                  <p class="text-sm text-zinc-500 dark:text-zinc-400">
+                    {projectAlphaBodyParts.before}<span class="font-medium text-blue-600 dark:text-blue-400"
                       >{content.projectAlphaAgent}</span
                     >{projectAlphaBodyParts.after}
                   </p>
                 </div>
                 <span
-                  class="bg-tertiary-container text-on-tertiary-container dark:bg-tertiary/20 dark:text-tertiary rounded px-2 py-0.5 text-xs font-black uppercase dark:tracking-wider"
+                  class="rounded bg-green-100 px-2 py-0.5 text-xs font-black text-green-700 uppercase dark:bg-green-500/20 dark:tracking-wider dark:text-green-300"
                   >Active</span
                 >
               </div>
               <div class="space-y-2">
-                <div
-                  class="bg-surface-container-high dark:bg-surface-container-highest/30 h-1.5 w-full overflow-hidden rounded-full"
-                >
-                  <div class="bg-primary h-full w-3/4"></div>
+                <div class="h-1.5 w-full overflow-hidden rounded-full bg-zinc-100 dark:bg-zinc-700/30">
+                  <div class="h-full w-3/4 bg-blue-600 dark:bg-blue-500"></div>
                 </div>
                 <div
-                  class="text-outline dark:text-on-surface-variant flex justify-between text-xs font-bold tracking-wider uppercase"
+                  class="flex justify-between text-xs font-bold tracking-wider text-zinc-500 uppercase dark:text-zinc-400"
                 >
                   <span>Technical Distribution</span>
-                  <span class="text-on-surface">12 Ready / 4 In Progress</span>
+                  <span class="text-zinc-950 dark:text-zinc-50">12 Ready / 4 In Progress</span>
                 </div>
               </div>
             </div>
             <div
-              class="border-outline-variant/10 bg-surface-container-lowest dark:bg-surface-container-low rounded border border-l-4 p-4 opacity-80 shadow-sm md:p-6"
+              class="rounded border border-l-4 border-zinc-950/10 bg-white p-4 opacity-80 shadow-sm md:p-6 dark:border-white/10 dark:bg-zinc-900"
             >
               <div class="mb-4 flex items-start justify-between">
                 <div>
-                  <h4 class="text-on-surface font-heading text-lg font-bold">Infrastructure Core</h4>
-                  <p class="text-on-surface-variant text-sm">{content.infrastructureBody}</p>
+                  <h4 class="font-heading text-lg font-bold text-zinc-950 dark:text-zinc-50">Infrastructure Core</h4>
+                  <p class="text-sm text-zinc-500 dark:text-zinc-400">{content.infrastructureBody}</p>
                 </div>
                 <span
-                  class="bg-surface-container-high text-outline dark:bg-surface-container-highest dark:text-on-surface-variant rounded px-2 py-0.5 text-xs font-black tracking-wider uppercase"
+                  class="rounded bg-zinc-100 px-2 py-0.5 text-xs font-black tracking-wider text-zinc-500 uppercase dark:bg-zinc-800 dark:text-zinc-400"
                   >{content.infrastructureStatus}</span
                 >
               </div>
-              <div class="text-on-surface-variant text-xs font-bold tracking-wider uppercase italic">
+              <div class="text-xs font-bold tracking-wider text-zinc-500 uppercase italic dark:text-zinc-400">
                 {content.infrastructureNote}
               </div>
             </div>
           </div>
           <div class="space-y-3">
             <div
-              class="border-outline-variant/10 bg-surface-container-lowest dark:border-outline-variant/20 dark:bg-surface-container-low rounded border p-4 shadow-sm md:p-6"
+              class="rounded border border-zinc-950/10 bg-white p-4 shadow-sm md:p-6 dark:border-white/10 dark:bg-zinc-900"
             >
-              <h5 class="text-outline mb-4 text-xs font-black tracking-widest uppercase">
+              <h5 class="mb-4 text-xs font-black tracking-widest text-zinc-500 uppercase dark:text-zinc-400">
                 {content.insightsTitle}
               </h5>
               <div class="space-y-4">
                 <div class="flex gap-3">
-                  <div class="bg-error mt-1.5 h-1.5 w-1.5 rounded-full"></div>
-                  <p class="text-on-surface text-xs font-bold">{content.insightsItems[0]}</p>
+                  <div class="mt-1.5 h-1.5 w-1.5 rounded-full bg-red-600 dark:bg-red-500"></div>
+                  <p class="text-xs font-bold text-zinc-950 dark:text-zinc-50">{content.insightsItems[0]}</p>
                 </div>
                 <div class="flex gap-3">
-                  <div class="bg-primary mt-1.5 h-1.5 w-1.5 rounded-full"></div>
-                  <p class="text-on-surface text-xs font-bold">{content.insightsItems[1]}</p>
+                  <div class="mt-1.5 h-1.5 w-1.5 rounded-full bg-blue-600 dark:bg-blue-500"></div>
+                  <p class="text-xs font-bold text-zinc-950 dark:text-zinc-50">{content.insightsItems[1]}</p>
                 </div>
               </div>
             </div>
             <div
-              class="border-outline-variant/10 bg-surface-container-lowest dark:border-outline-variant/20 dark:bg-surface-container-low rounded border p-4 shadow-sm md:p-6"
+              class="rounded border border-zinc-950/10 bg-white p-4 shadow-sm md:p-6 dark:border-white/10 dark:bg-zinc-900"
             >
-              <h5 class="text-outline mb-4 text-xs font-black tracking-widest uppercase">
+              <h5 class="mb-4 text-xs font-black tracking-widest text-zinc-500 uppercase dark:text-zinc-400">
                 {content.decisionsTitle}
               </h5>
               <div
-                class="border-tertiary-dim dark:border-primary dark:text-on-surface-variant text-on-surface space-y-4 border-l-2 pl-3"
+                class="space-y-4 border-l-2 border-green-600/40 pl-3 text-zinc-950 dark:border-blue-400/40 dark:text-zinc-400"
               >
-                <p class="dark:text-on-surface-variant text-xs leading-relaxed">
-                  {firstDecisionParts.before}<span class="text-on-surface font-bold">{decisionHighlight}</span>{
-                    firstDecisionParts.after
-                  }
+                <p class="text-xs leading-relaxed dark:text-zinc-400">
+                  {firstDecisionParts.before}<span class="font-bold text-zinc-950 dark:text-zinc-50"
+                    >{decisionHighlight}</span
+                  >{firstDecisionParts.after}
                 </p>
-                <p class="dark:text-on-surface-variant text-xs leading-relaxed">{content.decisions[1]}</p>
+                <p class="text-xs leading-relaxed dark:text-zinc-400">{content.decisions[1]}</p>
               </div>
             </div>
           </div>
@@ -302,14 +300,17 @@ const firstDecisionParts = splitHighlightedText(content.decisions[0], decisionHi
     </div>
   </section>
 
-  <section id="methodology" class="border-outline-variant/10 bg-surface-container-low border-y py-8 md:py-12">
+  <section
+    id="methodology"
+    class="border-y border-zinc-950/10 bg-zinc-50 py-8 md:py-12 dark:border-white/10 dark:bg-zinc-900"
+  >
     <div class="mx-auto max-w-screen-2xl px-4 md:px-12">
       <div class="grid grid-cols-1 gap-6 md:grid-cols-3 md:gap-8">
         {
           content.valueTitles.map((title, index) => (
-            <div class="border-primary-dim space-y-4 border-l-2 pl-6">
-              <h3 class="text-on-surface font-heading text-xl font-bold">{title}</h3>
-              <p class="text-on-surface-variant text-sm leading-relaxed">{content.valueBodies[index]}</p>
+            <div class="space-y-4 border-l-2 border-blue-600/40 pl-6 dark:border-blue-400/40">
+              <h3 class="font-heading text-xl font-bold text-zinc-950 dark:text-zinc-50">{title}</h3>
+              <p class="text-sm leading-relaxed text-zinc-500 dark:text-zinc-400">{content.valueBodies[index]}</p>
             </div>
           ))
         }
@@ -322,87 +323,103 @@ const firstDecisionParts = splitHighlightedText(content.decisions[0], decisionHi
   >
     <div class="space-y-4">
       <div
-        class="bg-tertiary-container text-on-tertiary-container dark:bg-primary/20 dark:text-primary inline-block rounded px-2 py-1 text-xs font-black tracking-widest uppercase md:px-3"
+        class="inline-block rounded bg-green-100 px-2 py-1 text-xs font-black tracking-widest text-green-700 uppercase md:px-3 dark:bg-blue-400/20 dark:text-blue-400"
       >
         {content.contextWindow}
       </div>
       <h2
-        class="text-on-surface font-heading text-3xl leading-tight font-extrabold tracking-tight md:text-4xl lg:text-5xl"
+        class="font-heading text-3xl leading-tight font-extrabold tracking-tight text-zinc-950 md:text-4xl lg:text-5xl dark:text-zinc-50"
       >
         {content.detailTitle}
       </h2>
-      <p class="text-on-surface-variant text-base leading-relaxed md:text-lg">{content.detailBody}</p>
+      <p class="text-base leading-relaxed text-zinc-500 md:text-lg dark:text-zinc-400">{content.detailBody}</p>
       <div class="space-y-2">
         <div
-          class="border-outline-variant/10 border-primary bg-surface-container-low flex items-center gap-3 rounded border border-l-4 p-3 md:gap-4 md:p-4"
+          class="flex items-center gap-3 rounded border border-l-4 border-blue-600 border-zinc-950/10 bg-zinc-50 p-3 md:gap-4 md:p-4 dark:border-blue-500 dark:border-white/10 dark:bg-zinc-900"
         >
-          <span class="material-symbols-outlined text-primary">auto_graph</span>
-          <span class="text-on-surface text-xs font-bold md:text-sm">{content.detailFeatures[0]}</span>
+          <span class="material-symbols-outlined text-blue-600 dark:text-blue-500">auto_graph</span>
+          <span class="text-xs font-bold text-zinc-950 md:text-sm dark:text-zinc-50">{content.detailFeatures[0]}</span>
         </div>
         <div
-          class="border-outline-variant/10 border-primary bg-surface-container-low flex items-center gap-3 rounded border border-l-4 p-3 md:gap-4 md:p-4"
+          class="flex items-center gap-3 rounded border border-l-4 border-blue-600 border-zinc-950/10 bg-zinc-50 p-3 md:gap-4 md:p-4 dark:border-blue-500 dark:border-white/10 dark:bg-zinc-900"
         >
-          <span class="material-symbols-outlined text-primary">terminal</span>
-          <span class="text-on-surface text-xs font-bold md:text-sm">{content.detailFeatures[1]}</span>
+          <span class="material-symbols-outlined text-blue-600 dark:text-blue-500">terminal</span>
+          <span class="text-xs font-bold text-zinc-950 md:text-sm dark:text-zinc-50">{content.detailFeatures[1]}</span>
         </div>
       </div>
     </div>
     <div class="relative">
       <div
-        class="border-outline-variant/10 bg-surface-container-lowest shadow-panel dark:border-outline-variant/20 dark:bg-surface-container-low relative z-10 mx-auto max-w-lg rounded-lg border p-5 md:p-8"
+        class="relative z-10 mx-auto max-w-lg rounded-lg border border-zinc-950/10 bg-white p-5 shadow-2xl md:p-8 dark:border-white/10 dark:bg-zinc-900"
       >
-        <div class="border-outline-variant/20 mb-4 flex items-center justify-between border-b pb-2">
-          <span class="text-on-surface-variant font-mono text-xs font-bold tracking-tighter uppercase"
+        <div class="mb-4 flex items-center justify-between border-b border-zinc-950/10 pb-2 dark:border-white/10">
+          <span class="font-mono text-xs font-bold tracking-tighter text-zinc-500 uppercase dark:text-zinc-400"
             >TASK-442 / OPS</span
           >
           <div class="flex items-center gap-2">
-            <span class="material-symbols-outlined text-primary text-xs">smart_toy</span>
-            <span class="text-on-surface text-xs font-black tracking-tighter uppercase">Agent Tracking</span>
+            <span class="material-symbols-outlined text-xs text-blue-600 dark:text-blue-500">smart_toy</span>
+            <span class="text-xs font-black tracking-tighter text-zinc-950 uppercase dark:text-zinc-50"
+              >Agent Tracking</span
+            >
           </div>
         </div>
-        <h4 class="text-on-surface font-heading mb-2 text-2xl font-bold tracking-tight">{content.taskTitle}</h4>
-        <p class="text-on-surface-variant mb-4 text-sm leading-relaxed">
-          {taskBodyParts.before}<span class="text-primary font-semibold">{content.taskAgent}</span>{taskBodyParts.after}
+        <h4 class="font-heading mb-2 text-2xl font-bold tracking-tight text-zinc-950 dark:text-zinc-50">
+          {content.taskTitle}
+        </h4>
+        <p class="mb-4 text-sm leading-relaxed text-zinc-500 dark:text-zinc-400">
+          {taskBodyParts.before}<span class="font-semibold text-blue-600 dark:text-blue-500">{content.taskAgent}</span>{
+            taskBodyParts.after
+          }
         </p>
         <div class="space-y-3">
-          <div class="border-primary/30 bg-primary/10 flex items-center justify-between rounded border p-4">
+          <div
+            class="flex items-center justify-between rounded border border-blue-600/30 bg-blue-600/10 p-4 dark:border-blue-400/30 dark:bg-blue-400/10"
+          >
             <div class="flex items-center gap-3">
-              <span class="material-symbols-outlined text-primary text-lg">schema</span>
-              <span class="text-on-surface text-xs font-bold tracking-wide uppercase">{content.taskPrimary}</span>
+              <span class="material-symbols-outlined text-lg text-blue-600 dark:text-blue-500">schema</span>
+              <span class="text-xs font-bold tracking-wide text-zinc-950 uppercase dark:text-zinc-50"
+                >{content.taskPrimary}</span
+              >
             </div>
-            <span class="text-primary text-xs font-bold">{content.taskPrimaryAction}</span>
+            <span class="text-xs font-bold text-blue-600 dark:text-blue-500">{content.taskPrimaryAction}</span>
           </div>
           <div
-            class="border-outline-variant/10 bg-surface-container-low dark:bg-surface-container flex items-center justify-between rounded border p-4"
+            class="flex items-center justify-between rounded border border-zinc-950/10 bg-zinc-50 p-4 dark:border-white/10 dark:bg-zinc-800"
           >
             <div class="flex items-center gap-3">
-              <span class="material-symbols-outlined text-tertiary text-lg">verified</span>
-              <span class="text-on-surface text-xs font-bold tracking-wide uppercase">{content.taskSecondary}</span>
+              <span class="material-symbols-outlined text-lg text-green-700 dark:text-green-400">verified</span>
+              <span class="text-xs font-bold tracking-wide text-zinc-950 uppercase dark:text-zinc-50"
+                >{content.taskSecondary}</span
+              >
             </div>
-            <span class="text-tertiary text-xs font-bold uppercase">{content.taskSecondaryAction}</span>
+            <span class="text-xs font-bold text-green-700 uppercase dark:text-green-400"
+              >{content.taskSecondaryAction}</span
+            >
           </div>
         </div>
       </div>
       <div
-        class="bg-surface-container-high dark:bg-primary/5 absolute -top-6 -right-6 -z-10 h-full w-full rounded-xl opacity-30 dark:opacity-100"
+        class="absolute -top-6 -right-6 -z-10 h-full w-full rounded-xl bg-zinc-100 opacity-30 dark:bg-blue-500/5 dark:opacity-100"
       >
       </div>
     </div>
   </section>
 
-  <section class="border-outline-variant/10 mx-auto max-w-screen-2xl border-t px-4 py-10 md:px-12 md:py-16">
+  <section
+    class="mx-auto max-w-screen-2xl border-t border-zinc-950/10 px-4 py-10 md:px-12 md:py-16 dark:border-white/10"
+  >
     <div class="flex flex-col items-start gap-8 md:flex-row">
       <div class="w-full md:w-1/3">
-        <h2 class="text-on-surface font-heading text-3xl leading-tight font-extrabold tracking-tight">
+        <h2 class="font-heading text-3xl leading-tight font-extrabold tracking-tight text-zinc-950 dark:text-zinc-50">
           {content.systemTitle}
         </h2>
       </div>
       <div class="grid w-full grid-cols-1 gap-4 md:grid-cols-2">
         {
           content.systemCards.map((card) => (
-            <div class="border-outline-variant/10 bg-surface-container-low dark:border-outline-variant/20 rounded-lg border p-8 shadow-md">
-              <h4 class="text-on-surface font-heading mb-3 text-lg font-bold">{card.title}</h4>
-              <p class="text-on-surface-variant text-sm leading-relaxed">{card.body}</p>
+            <div class="rounded-lg border border-zinc-950/10 bg-zinc-50 p-8 shadow-md dark:border-white/10 dark:bg-zinc-900">
+              <h4 class="font-heading mb-3 text-lg font-bold text-zinc-950 dark:text-zinc-50">{card.title}</h4>
+              <p class="text-sm leading-relaxed text-zinc-500 dark:text-zinc-400">{card.body}</p>
             </div>
           ))
         }
@@ -410,21 +427,25 @@ const firstDecisionParts = splitHighlightedText(content.decisions[0], decisionHi
     </div>
   </section>
 
-  <section class="border-outline-variant/10 bg-surface border-t px-4 py-10 text-center md:px-12 md:py-16">
+  <section
+    class="border-t border-zinc-950/10 bg-white px-4 py-10 text-center md:px-12 md:py-16 dark:border-white/10 dark:bg-zinc-950"
+  >
     <div class="mx-auto max-w-3xl space-y-4">
-      <h2 class="text-on-surface font-heading text-3xl font-extrabold tracking-tight md:text-4xl lg:text-5xl">
+      <h2
+        class="font-heading text-3xl font-extrabold tracking-tight text-zinc-950 md:text-4xl lg:text-5xl dark:text-zinc-50"
+      >
         {content.closingTitle}
       </h2>
-      <p class="text-on-surface-variant text-base md:text-xl">{content.closingBody}</p>
+      <p class="text-base text-zinc-500 md:text-xl dark:text-zinc-400">{content.closingBody}</p>
       <div class="flex flex-col items-center justify-center gap-3 sm:flex-row md:gap-4">
         <a
           href={appHref}
-          class="bg-primary text-on-primary dark:hover:bg-primary/90 w-full rounded-lg px-8 py-3 text-base font-bold transition-all hover:opacity-90 sm:w-auto md:px-12 md:py-4 md:text-lg"
+          class="w-full rounded-lg bg-blue-600 px-8 py-3 text-base font-bold text-white transition-all hover:bg-blue-700 sm:w-auto md:px-12 md:py-4 md:text-lg dark:bg-blue-500 dark:hover:bg-blue-400"
           >{content.closingPrimary}</a
         >
         <a
           href={appHref}
-          class="border-outline text-on-surface hover:bg-surface-container w-full rounded-lg border px-8 py-3 text-base font-bold transition-all sm:w-auto md:px-12 md:py-4 md:text-lg"
+          class="w-full rounded-lg border border-zinc-950/20 px-8 py-3 text-base font-bold text-zinc-950 transition-all hover:bg-zinc-100 sm:w-auto md:px-12 md:py-4 md:text-lg dark:border-white/20 dark:text-zinc-50 dark:hover:bg-zinc-800"
           >{content.closingSecondary}</a
         >
       </div>
@@ -432,26 +453,28 @@ const firstDecisionParts = splitHighlightedText(content.decisions[0], decisionHi
   </section>
 </main>
 
-<footer class="border-outline-variant/10 bg-surface-container-low w-full border-t px-4 py-8 md:px-12 md:py-10">
+<footer
+  class="w-full border-t border-zinc-950/10 bg-zinc-50 px-4 py-8 md:px-12 md:py-10 dark:border-white/10 dark:bg-zinc-900"
+>
   <div class="mx-auto flex max-w-screen-2xl flex-col items-center justify-between gap-3 md:flex-row">
-    <div class="text-on-surface-variant font-sans text-xs font-bold tracking-widest uppercase">
+    <div class="font-sans text-xs font-bold tracking-widest text-zinc-500 uppercase dark:text-zinc-400">
       © 2024 THEMIS TECHNICAL LEDGER. ALL RIGHTS RESERVED.
     </div>
     <div class="flex gap-8">
       <a
-        class="text-on-surface-variant hover:text-on-surface font-sans text-xs font-bold tracking-widest uppercase transition-colors"
+        class="font-sans text-xs font-bold tracking-widest text-zinc-500 uppercase transition-colors hover:text-zinc-950 dark:text-zinc-400 dark:hover:text-zinc-50"
         href="#">{content.footerLinks[0]}</a
       >
       <a
-        class="text-on-surface-variant hover:text-on-surface font-sans text-xs font-bold tracking-widest uppercase transition-colors"
+        class="font-sans text-xs font-bold tracking-widest text-zinc-500 uppercase transition-colors hover:text-zinc-950 dark:text-zinc-400 dark:hover:text-zinc-50"
         href="#">{content.footerLinks[1]}</a
       >
       <a
-        class="text-on-surface-variant hover:text-on-surface font-sans text-xs font-bold tracking-widest uppercase transition-colors"
+        class="font-sans text-xs font-bold tracking-widest text-zinc-500 uppercase transition-colors hover:text-zinc-950 dark:text-zinc-400 dark:hover:text-zinc-50"
         href="#">{content.footerLinks[2]}</a
       >
       <a
-        class="text-on-surface-variant hover:text-on-surface font-sans text-xs font-bold tracking-widest uppercase transition-colors"
+        class="font-sans text-xs font-bold tracking-widest text-zinc-500 uppercase transition-colors hover:text-zinc-950 dark:text-zinc-400 dark:hover:text-zinc-50"
         href="#">{content.footerLinks[3]}</a
       >
     </div>
diff --git a/apps/web/site/src/components/locale-switcher.astro b/apps/web/site/src/components/locale-switcher.astro
index 7dfd9b9..d7c32a2 100644
--- a/apps/web/site/src/components/locale-switcher.astro
+++ b/apps/web/site/src/components/locale-switcher.astro
@@ -8,12 +8,22 @@ type Props = {
 const { locale } = Astro.props;
 ---
 
-<div class="text-on-surface-variant flex items-center gap-4 font-sans text-xs font-black tracking-widest uppercase">
-  <a href="/en/" class:list={['hover:text-primary no-underline', locale === 'en' && 'text-on-surface font-extrabold']}
-    >EN</a
+<div
+  class="flex items-center gap-4 font-sans text-xs font-black tracking-widest text-zinc-500 uppercase dark:text-zinc-400"
+>
+  <a
+    href="/en/"
+    class:list={[
+      'no-underline hover:text-blue-600 dark:hover:text-blue-500',
+      locale === 'en' && 'font-extrabold text-zinc-950 dark:text-zinc-50',
+    ]}>EN</a
   >
   <span class="opacity-30">/</span>
-  <a href="/es/" class:list={['hover:text-primary no-underline', locale === 'es' && 'text-on-surface font-extrabold']}
-    >ES</a
+  <a
+    href="/es/"
+    class:list={[
+      'no-underline hover:text-blue-600 dark:hover:text-blue-500',
+      locale === 'es' && 'font-extrabold text-zinc-950 dark:text-zinc-50',
+    ]}>ES</a
   >
 </div>
diff --git a/apps/web/site/src/components/theme-switcher.astro b/apps/web/site/src/components/theme-switcher.astro
index baeccd3..9d69e18 100644
--- a/apps/web/site/src/components/theme-switcher.astro
+++ b/apps/web/site/src/components/theme-switcher.astro
@@ -1,18 +1,18 @@
 <label
   for="theme-switch-input"
   tabindex="0"
-  class="theme-switch-label text-on-surface-variant hover:bg-surface-container-high hover:text-primary focus-visible:outline-primary dark:hover:bg-surface-container/90 relative flex h-10 w-10 cursor-pointer items-center justify-center overflow-hidden rounded-md transition-colors outline-none focus-visible:outline-2 focus-visible:outline-offset-2"
+  class="theme-switch-label relative flex h-10 w-10 cursor-pointer items-center justify-center overflow-hidden rounded-md text-zinc-500 transition-colors outline-none hover:bg-zinc-100 hover:text-blue-600 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-blue-500 dark:focus-visible:outline-blue-500"
 >
   <input id="theme-switch-input" type="checkbox" class="theme-switch-input sr-only" />
   <span class="sr-only">Toggle theme</span>
 
   <svg
-    class="theme-icon-light theme-icon text-primary absolute hidden h-7 w-7"
+    class="theme-icon-light theme-icon absolute hidden h-7 w-7 text-blue-600 dark:text-blue-500"
     xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 24 24"
   >
     <path
-      class="text-yellow-400"
+      class="text-amber-500 dark:text-amber-400"
       stroke-width="1.5"
       stroke-linecap="round"
       stroke-linejoin="round"
@@ -23,12 +23,12 @@
   </svg>
 
   <svg
-    class="theme-icon-dark theme-icon text-on-surface absolute hidden h-6 w-6"
+    class="theme-icon-dark theme-icon absolute hidden h-6 w-6 text-zinc-950 dark:text-zinc-50"
     xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 24 24"
   >
     <path
-      class="text-white"
+      class="text-zinc-50"
       fill="currentColor"
       stroke-width="1.5"
       stroke="currentColor"
diff --git a/apps/web/site/src/pages/docs/index.astro b/apps/web/site/src/pages/docs/index.astro
index 33c9b23..019bde8 100644
--- a/apps/web/site/src/pages/docs/index.astro
+++ b/apps/web/site/src/pages/docs/index.astro
@@ -11,31 +11,31 @@ import BaseLayout from '../../layouts/base-layout.astro';
 >
   <main class="mx-auto flex min-h-screen w-full max-w-5xl flex-col justify-center gap-8 px-4 py-20 sm:px-8">
     <div class="space-y-4">
-      <p class="text-sm tracking-widest text-sky-300 uppercase">Documentation</p>
-      <h1 class="text-5xl font-semibold tracking-tighter text-white sm:text-6xl">
+      <p class="text-sm tracking-widest text-blue-600 uppercase dark:text-blue-400">Documentation</p>
+      <h1 class="text-5xl font-semibold tracking-tighter text-zinc-950 sm:text-6xl dark:text-zinc-50">
         Themis docs live in this repository.
       </h1>
-      <p class="max-w-2xl text-lg leading-8 text-slate-300">
+      <p class="max-w-2xl text-lg leading-8 text-zinc-500 dark:text-zinc-400">
         Review the product, architecture, and design files directly under the repository <code>docs/</code> directory.
       </p>
     </div>
 
     <section class="grid gap-6 md:grid-cols-3">
-      <article class="rounded-3xl border border-slate-800 bg-slate-950/60 p-6">
-        <h2 class="text-lg font-semibold text-white">Overview</h2>
-        <p class="mt-3 text-sm leading-7 text-slate-300">
+      <article class="rounded-3xl border border-zinc-950/10 bg-white p-6 dark:border-white/10 dark:bg-zinc-900">
+        <h2 class="text-lg font-semibold text-zinc-950 dark:text-zinc-50">Overview</h2>
+        <p class="mt-3 text-sm leading-7 text-zinc-500 dark:text-zinc-400">
           Start with <code>docs/overview.md</code> for the product framing.
         </p>
       </article>
-      <article class="rounded-3xl border border-slate-800 bg-slate-950/60 p-6">
-        <h2 class="text-lg font-semibold text-white">Architecture</h2>
-        <p class="mt-3 text-sm leading-7 text-slate-300">
+      <article class="rounded-3xl border border-zinc-950/10 bg-white p-6 dark:border-white/10 dark:bg-zinc-900">
+        <h2 class="text-lg font-semibold text-zinc-950 dark:text-zinc-50">Architecture</h2>
+        <p class="mt-3 text-sm leading-7 text-zinc-500 dark:text-zinc-400">
           Review runtime, frontend, backend, and deployment notes under <code>docs/architecture/</code>.
         </p>
       </article>
-      <article class="rounded-3xl border border-slate-800 bg-slate-950/60 p-6">
-        <h2 class="text-lg font-semibold text-white">Design</h2>
-        <p class="mt-3 text-sm leading-7 text-slate-300">
+      <article class="rounded-3xl border border-zinc-950/10 bg-white p-6 dark:border-white/10 dark:bg-zinc-900">
+        <h2 class="text-lg font-semibold text-zinc-950 dark:text-zinc-50">Design</h2>
+        <p class="mt-3 text-sm leading-7 text-zinc-500 dark:text-zinc-400">
           Explore the visual direction, prompts, and reference assets under <code>docs/design/</code>.
         </p>
       </article>
diff --git a/docs/agents/design-system.md b/docs/agents/design-system.md
index fd7cc02..a29aede 100644
--- a/docs/agents/design-system.md
+++ b/docs/agents/design-system.md
@@ -19,13 +19,13 @@ These instructions apply to Tailwind, visual design, UI polish, accessibility, a
 
 ## Core Tokens
 
-- Display and headlines use Manrope through `--font-family-display`.
-- Body text uses Inter through `--font-family`.
-- Monospace text uses JetBrains Mono through `--font-family-mono`.
-- Preserve the surface hierarchy: `surface`, `surface-container-low`, `surface-container`, `surface-container-high`, `surface-container-highest`.
+- Display and headlines use Manrope through `--font-heading` / `font-heading`.
+- Body text uses Inter through `--font-sans` / `font-sans`.
+- Monospace text uses JetBrains Mono through `--font-mono` / `font-mono`.
+- Preserve the raw Tailwind v4 surface ladder: light mode `bg-white` → `bg-zinc-50` → `bg-zinc-100`, dark mode `dark:bg-zinc-950` → `dark:bg-zinc-900` → `dark:bg-zinc-800`.
 - Avoid solid 1px borders for sectioning; use tonal shifts.
-- Use ghost borders with `outline-variant` at low opacity for inputs.
-- Default card radius is `0.25rem`; small element radius is `0.125rem`.
+- Use ghost borders with `border-zinc-950/10` (light) / `dark:border-white/10` (dark) for inputs and dividers.
+- Default card radius is `0.75rem` (`rounded-lg`); small element radius is `0.5rem` (`rounded-md`).
 
 ## Mobile-First Layout
 
diff --git a/docs/design-system/recipes.md b/docs/design-system/recipes.md
index 1a028ab..ea967df 100644
--- a/docs/design-system/recipes.md
+++ b/docs/design-system/recipes.md
@@ -10,19 +10,19 @@ All auth routes share the same `app-auth-layout` primitive. The shell renders a
     <header class="mb-7 space-y-2">
       <p
         data-slot="kicker"
-        class="text-muted-fg font-mono text-xs font-semibold tracking-widest uppercase"
+        class="font-mono text-xs font-semibold tracking-widest text-zinc-500 uppercase dark:text-zinc-400"
         i18n="@@signInKicker"
       >
         Account access
       </p>
       <h1
         data-slot="title"
-        class="font-display text-fg text-[1.625rem] leading-tight font-bold tracking-[-0.025em]"
+        class="font-heading text-[1.625rem] leading-tight font-bold tracking-[-0.025em] text-zinc-950 dark:text-zinc-50"
         i18n="@@signInTitle"
       >
         Sign in
       </h1>
-      <p data-slot="sub" class="text-muted-fg text-[0.9375rem] leading-6" i18n="@@signInSub">
+      <p data-slot="sub" class="text-[0.9375rem] leading-6 text-zinc-500 dark:text-zinc-400" i18n="@@signInSub">
         Welcome back. Use your work email to access your Themis workspace.
       </p>
     </header>
@@ -70,7 +70,7 @@ All auth routes share the same `app-auth-layout` primitive. The shell renders a
       >
     </form>
 
-    <p class="text-muted-fg mt-6 text-sm" i18n="@@signInFooterPrompt">New to Themis?</p>
+    <p class="mt-6 text-sm text-zinc-500 dark:text-zinc-400" i18n="@@signInFooterPrompt">New to Themis?</p>
     <app-link data-slot="footer" i18n="@@signInFooterLink" [routerLink]="footerLink" [text]="'Create an account'" />
   </app-auth-card>
 </app-auth-layout>
@@ -147,7 +147,7 @@ The pin input renders a wrapper with `data-slot="pin-input"`; e2e helpers target
 </app-field>
 ```
 
-The `Field` propagates `data-invalid` to its children. `Input` reads the attribute to switch `border-border` to `border-danger`.
+The `Field` propagates `data-invalid` to its children. `Input` reads the attribute to switch `border-zinc-950/15` to `border-red-600` (`dark:border-red-500`).
 
 ## App Shell (auth routes excluded)
 
@@ -175,7 +175,7 @@ type LayoutNavItem = {
 };
 ```
 
-The `Sidebar` items consume `data-current:bg-accent/10 data-current:text-accent` for the active state.
+The `Sidebar` items consume `data-current:bg-blue-600/10 data-current:text-blue-600 dark:data-current:bg-blue-400/10 dark:data-current:text-blue-400` for the active state.
 
 The user menu uses `app-dropdown` + `app-listbox` so it is keyboard accessible and the menu items are real `<div role="option">` elements that the screen reader can announce.
 
@@ -183,9 +183,9 @@ The user menu uses `app-dropdown` + `app-listbox` so it is keyboard accessible a
 
 ```html
 <app-page-header>
-  <p data-slot="eyebrow" class="text-accent text-sm font-semibold">Projects</p>
-  <h1 data-slot="title" class="font-heading text-4xl font-bold">Project workspace</h1>
-  <p data-slot="description" class="text-muted-fg">Manage active work.</p>
+  <p data-slot="eyebrow" class="text-sm font-semibold text-blue-600 dark:text-blue-500">Projects</p>
+  <h1 data-slot="title" class="font-heading text-4xl font-bold text-zinc-950 dark:text-zinc-50">Project workspace</h1>
+  <p data-slot="description" class="text-zinc-500 dark:text-zinc-400">Manage active work.</p>
   <app-button data-slot="actions" tone="blue">New project</app-button>
 </app-page-header>
 ```
@@ -194,23 +194,30 @@ The user menu uses `app-dropdown` + `app-listbox` so it is keyboard accessible a
 
 ```html
 <app-card padding="md" tone="raised" class="overflow-hidden">
-  <div class="bg-panel hidden grid-cols-4 gap-3 px-6 py-3 md:grid">
-    <span class="text-muted-fg text-xs font-semibold tracking-widest uppercase">Project</span>
-    <span class="text-muted-fg text-xs font-semibold tracking-widest uppercase">Status</span>
-    <span class="text-muted-fg text-xs font-semibold tracking-widest uppercase">Created</span>
-    <span class="text-muted-fg text-xs font-semibold tracking-widest uppercase">Actions</span>
+  <div class="hidden grid-cols-4 gap-3 bg-zinc-50 px-6 py-3 md:grid dark:bg-zinc-900">
+    <span class="text-xs font-semibold tracking-widest text-zinc-500 uppercase dark:text-zinc-400">Project</span>
+    <span class="text-xs font-semibold tracking-widest text-zinc-500 uppercase dark:text-zinc-400">Status</span>
+    <span class="text-xs font-semibold tracking-widest text-zinc-500 uppercase dark:text-zinc-400">Created</span>
+    <span class="text-xs font-semibold tracking-widest text-zinc-500 uppercase dark:text-zinc-400">Actions</span>
   </div>
 
   @for (project of projects(); track project.id) {
-  <article class="border-border-subtle grid gap-3 border-t px-6 py-4 md:grid-cols-4 md:items-center">
-    <a class="text-fg hover:text-accent font-medium no-underline" [routerLink]="['/projects', project.id]">
+  <article class="grid gap-3 border-t border-zinc-950/10 px-6 py-4 md:grid-cols-4 md:items-center dark:border-white/10">
+    <a
+      class="font-medium text-zinc-950 no-underline hover:text-blue-600 dark:text-zinc-50 dark:hover:text-blue-500"
+      [routerLink]="['/projects', project.id]"
+    >
       {{ project.name }}
     </a>
     <app-badge [tone]="statusTone(project.status)">{{ statusLabel(project.status) }}</app-badge>
-    <span class="text-muted-fg text-xs">{{ formatDate(project.createdAt) }}</span>
+    <span class="text-xs text-zinc-500 dark:text-zinc-400">{{ formatDate(project.createdAt) }}</span>
     <div class="flex items-center gap-2">
-      <a [routerLink]="['/projects', project.id]" class="text-accent text-sm font-medium">View</a>
-      <button type="button" class="text-danger text-sm font-medium" (click)="deleteProject(project.id, $event)">
+      <a [routerLink]="['/projects', project.id]" class="text-sm font-medium text-blue-600 dark:text-blue-500">View</a>
+      <button
+        type="button"
+        class="text-sm font-medium text-red-600 dark:text-red-400"
+        (click)="deleteProject(project.id, $event)"
+      >
         Delete
       </button>
     </div>
@@ -226,7 +233,7 @@ The user menu uses `app-dropdown` + `app-listbox` so it is keyboard accessible a
 Use the accessible `role="tablist"` / `role="tab"` / `role="tabpanel"` pattern with Tailwind utilities. No PrimeNG `TabView` is needed.
 
 ```html
-<div role="tablist" class="bg-panel border-border-subtle flex flex-wrap border-b">
+<div role="tablist" class="flex flex-wrap border-b border-zinc-950/10 bg-zinc-50 dark:border-white/10 dark:bg-zinc-900">
   @for (tab of tabs; track tab.id) {
   <button
     type="button"
@@ -234,8 +241,10 @@ Use the accessible `role="tablist"` / `role="tab"` / `role="tabpanel"` pattern w
     [id]="'config-tab-' + tab.id"
     [attr.aria-selected]="selected() === tab.id"
     [attr.aria-controls]="'config-tabpanel'"
-    [class.bg-bg]="selected() === tab.id"
-    [class.text-accent]="selected() === tab.id"
+    [class.bg-white]="selected() === tab.id"
+    [class.dark:bg-zinc-950]="selected() === tab.id"
+    [class.text-blue-600]="selected() === tab.id"
+    [class.dark:text-blue-500]="selected() === tab.id"
     (click)="select(tab.id)"
   >
     {{ tab.label }}
@@ -243,7 +252,7 @@ Use the accessible `role="tablist"` / `role="tab"` / `role="tabpanel"` pattern w
   }
 </div>
 
-<div role="tabpanel" [attr.aria-labelledby]="'config-tab-' + selected()" class="bg-panel-raised p-6">
+<div role="tabpanel" [attr.aria-labelledby]="'config-tab-' + selected()" class="bg-zinc-100 p-6 dark:bg-zinc-800">
   <pre class="font-mono text-sm leading-7 break-words whitespace-pre-wrap">{{ content() }}</pre>
 </div>
 ```
@@ -252,8 +261,8 @@ Use the accessible `role="tablist"` / `role="tab"` / `role="tabpanel"` pattern w
 
 ```html
 <app-dialog [open]="dialogOpen()" ariaLabelledBy="dialog-title" (closed)="dialogOpen.set(false)">
-  <h2 id="dialog-title" class="font-heading text-2xl font-bold">Confirm action</h2>
-  <p class="text-muted-fg">This action can be undone from settings.</p>
+  <h2 id="dialog-title" class="font-heading text-2xl font-bold text-zinc-950 dark:text-zinc-50">Confirm action</h2>
+  <p class="text-zinc-500 dark:text-zinc-400">This action can be undone from settings.</p>
 </app-dialog>
 ```
 
diff --git a/docs/design-system/tokens.md b/docs/design-system/tokens.md
index 1df64c7..065a314 100644
--- a/docs/design-system/tokens.md
+++ b/docs/design-system/tokens.md
@@ -1,38 +1,86 @@
 # Themis UI Tokens
 
-The Angular UI foundation uses the **Catalyst** token surface directly. Tokens are defined in `styles.base.css` inside Tailwind v4's `@theme` block, and components consume them through Tailwind utilities and the `ui-*` utility classes.
-
-## Color Tokens
-
-| Token                   | Usage              | Light value            | Dark value                | Tailwind class         |
-| ----------------------- | ------------------ | ---------------------- | ------------------------- | ---------------------- |
-| `--color-bg`            | App background     | `#ffffff`              | `#09090b`                 | `bg-bg`                |
-| `--color-panel`         | Cards and controls | `#fafafa` (`zinc-50`)  | `#18181b` (`zinc-900`)    | `bg-panel`             |
-| `--color-panel-raised`  | Elevated surfaces  | `#f4f4f5` (`zinc-100`) | `#27272a` (`zinc-800`)    | `bg-panel-raised`      |
-| `--color-fg`            | Primary text       | `#09090b` (`zinc-950`) | `#fafafa` (`zinc-50`)     | `text-fg`              |
-| `--color-muted-fg`      | Secondary text     | `#71717a` (`zinc-500`) | `#a1a1aa` (`zinc-400`)    | `text-muted-fg`        |
-| `--color-accent`        | Primary action     | `#2563eb` (`blue-600`) | `#3b82f6` (`blue-500`)    | `bg-accent`            |
-| `--color-accent-fg`     | Text on accent     | `#ffffff`              | `#ffffff`                 | `text-accent-fg`       |
-| `--color-danger`        | Error/destructive  | `#dc2626` (`red-600`)  | `#ef4444` (`red-500`)     | `bg-danger`            |
-| `--color-danger-fg`     | Text on danger     | `#ffffff`              | `#ffffff`                 | `text-danger-fg`       |
-| `--color-ring`          | Focus ring         | `#2563eb`              | `#3b82f6`                 | `box-shadow` driver    |
-| `--color-border`        | Standard divider   | `rgb(9 9 11 / 0.10)`   | `rgb(255 255 255 / 0.10)` | `border-border`        |
-| `--color-border-subtle` | Quiet divider      | `rgb(9 9 11 / 0.05)`   | `rgb(255 255 255 / 0.05)` | `border-border-subtle` |
+The Themis UI foundation uses **raw Tailwind v4 utilities** directly. There are no custom semantic color tokens (`--color-bg`, `--color-panel`, `--color-accent`) defined in `styles.base.css`. Components, templates, prototypes, and the public site compose their visual layer with the standard Tailwind v4 palette (`zinc-*` for neutrals, `blue-*` for accent, `green-*` for success, `red-*` for danger).
+
+The `styles.base.css` file at the workspace root declares fonts, radii, shadows, and the reusable `ui-*` utility classes (`ui-focus-ring`, `ui-panel`, `ui-panel-raised`, `ui-touch-target`, `ui-text-rhythm`). The `ui-panel` family internally reads Tailwind's standard zinc utilities, so dark mode flips automatically when the `<html>` element carries the `dark` class.
+
+## Surface Ladder
+
+Surfaces stack with subtle tonal shifts. The light ladder climbs from a white canvas through progressively darker zinc tones; the dark ladder sinks the canvas and rises through progressively lighter zinc tones.
+
+| Role                       | Light         | Dark                  |
+| -------------------------- | ------------- | --------------------- |
+| Page canvas                | `bg-white`    | `dark:bg-zinc-950`    |
+| Section band / quiet panel | `bg-zinc-50`  | `dark:bg-zinc-900`    |
+| Nested panel / raised card | `bg-zinc-100` | `dark:bg-zinc-800`    |
+| Decorative accent surface  | `bg-zinc-200` | `dark:bg-zinc-700`    |
+| Translucent overlay header | `bg-white/80` | `dark:bg-zinc-950/80` |
+
+## Text Ladder
+
+| Role              | Light            | Dark                  |
+| ----------------- | ---------------- | --------------------- |
+| Primary text      | `text-zinc-950`  | `dark:text-zinc-50`   |
+| Secondary text    | `text-zinc-500`  | `dark:text-zinc-400`  |
+| On accent fill    | `text-white`     | `text-white`          |
+| On success fill   | `text-green-700` | `dark:text-green-300` |
+| Destructive label | `text-red-600`   | `dark:text-red-400`   |
+
+## Accent Palette
+
+`blue-600` is the Themis brand accent in light mode. Dark mode shifts to `blue-500` for AA contrast on the zinc-950 canvas.
+
+| Role                        | Light                | Dark                      |
+| --------------------------- | -------------------- | ------------------------- |
+| Primary action fill         | `bg-blue-600`        | `dark:bg-blue-500`        |
+| Primary action fill (hover) | `hover:bg-blue-700`  | `dark:hover:bg-blue-400`  |
+| Primary text accent         | `text-blue-600`      | `dark:text-blue-500`      |
+| Soft accent fill            | `bg-blue-600/10`     | `dark:bg-blue-400/10`     |
+| Stronger soft fill          | `bg-blue-600/20`     | `dark:bg-blue-400/20`     |
+| Accent border               | `border-blue-600`    | `dark:border-blue-500`    |
+| Soft accent border          | `border-blue-600/40` | `dark:border-blue-400/40` |
+| Soft accent border (rail)   | `border-blue-600/30` | `dark:border-blue-400/30` |
+| Focus outline               | `outline-blue-600`   | `dark:outline-blue-500`   |
+
+## Status Palette
+
+| Role                       | Light                 | Dark                       |
+| -------------------------- | --------------------- | -------------------------- |
+| Success fill (badge)       | `bg-green-100`        | `dark:bg-green-500/20`     |
+| Success text               | `text-green-700`      | `dark:text-green-300`      |
+| Success accent             | `text-green-700`      | `dark:text-green-400`      |
+| Success soft fill          | `bg-green-600/20`     | `dark:bg-green-400/20`     |
+| Success soft border (rail) | `border-green-600/40` | `dark:border-green-400/40` |
+| Danger / error fill        | `bg-red-600`          | `dark:bg-red-500`          |
+| Danger text                | `text-red-600`        | `dark:text-red-400`        |
+| Amber icon (theme switch)  | `text-amber-500`      | `dark:text-amber-400`      |
+
+## Borders
+
+| Role             | Light                | Dark                   |
+| ---------------- | -------------------- | ---------------------- |
+| Quiet divider    | `border-zinc-950/10` | `dark:border-white/10` |
+| Standard divider | `border-zinc-950/15` | `dark:border-white/15` |
+| Visible border   | `border-zinc-950/20` | `dark:border-white/20` |
+
+The `ui-panel` and `ui-panel-raised` utility classes apply `border-zinc-950/5` (light) and `dark:border-white/5` (dark) by default, mirroring Tailwind's standard subtle-border pattern.
 
 ## Soft Fills
 
-Catalyst does not define explicit soft fill variables. Use `color-mix` to compose soft fills inline, or rely on Tailwind opacity utilities:
+Tailwind opacity utilities compose soft fills inline against any surface:
 
-```css
-/* Soft accent fill, 10% opacity over the surface */
-background: color-mix(in srgb, var(--color-accent) 10%, transparent);
+```html
+<!-- Soft accent fill over a zinc surface -->
+<div class="bg-blue-600/10 text-blue-700 dark:bg-blue-400/10 dark:text-blue-300">Soft accent surface</div>
 ```
 
 ```html
-<!-- Equivalent Tailwind utility -->
-<div class="bg-accent/10 text-accent">Soft accent surface</div>
+<!-- Equivalent raw CSS, if you ever need it outside Tailwind -->
+<div style="background: color-mix(in srgb, var(--color-blue-600) 10%, transparent)">Soft accent surface</div>
 ```
 
+The `color-mix` form is documented for completeness; the workspace default is to reach for Tailwind opacity utilities first.
+
 ## Radius Tokens
 
 | Token              | Value     | Use                |
@@ -40,7 +88,8 @@ background: color-mix(in srgb, var(--color-accent) 10%, transparent);
 | `--radius-sm`      | `0.5rem`  | Small controls     |
 | `--radius-control` | `0.5rem`  | Inputs and buttons |
 | `--radius-panel`   | `0.75rem` | Cards and panels   |
-| `--radius-full`    | `9999px`  | Pills              |
+
+The Tailwind v4 `rounded-sm` / `rounded-md` / `rounded-lg` / `rounded-xl` families map onto these tokens through the `@theme` block in `styles.base.css`.
 
 ## Shadow Tokens
 
@@ -50,6 +99,8 @@ background: color-mix(in srgb, var(--color-accent) 10%, transparent);
 | `--shadow-md`    | Popovers, command palettes |
 | `--shadow-panel` | Dialogs, elevated panels   |
 
+Tailwind v4 `shadow-sm`, `shadow-md`, and `shadow-2xl` map onto these tokens.
+
 ## Font Tokens
 
 | Token            | Family         | Use                 |
@@ -58,11 +109,13 @@ background: color-mix(in srgb, var(--color-accent) 10%, transparent);
 | `--font-heading` | Manrope        | Display, headings   |
 | `--font-mono`    | JetBrains Mono | IDs, commands, logs |
 
+Components reach for these through Tailwind's `font-sans`, `font-heading`, and `font-mono` utilities (wired through the `@theme` block).
+
 ## Reusable Utilities
 
-- `ui-focus-ring`: visible keyboard focus treatment driven by `--color-ring`.
-- `ui-panel`: default panel surface with a `--color-border-subtle` border.
-- `ui-panel-raised`: elevated surface with shadow and a `--color-border-subtle` border.
+- `ui-focus-ring`: visible keyboard focus treatment driven by Tailwind's `blue-500` / `blue-600` outline halo.
+- `ui-panel`: default panel surface with a `border-zinc-950/5` border.
+- `ui-panel-raised`: elevated surface with shadow and a `border-zinc-950/5` border.
 - `ui-touch-target`: 44px minimum interactive target.
 - `ui-text-rhythm`: readable paragraph rhythm for long-form text.
 
@@ -74,22 +127,16 @@ Dark mode applies when the `<html>` element carries the `dark` class:
 @custom-variant dark (&:where(.dark, .dark *));
 ```
 
-The `html.dark` block in `styles.base.css` redefines the same token set with the dark mode Tailwind values. Components that use the tokens through Tailwind utilities (`bg-bg`, `text-fg`, `border-border`) automatically pick up the dark values without per-component dark mode rules.
-
-## Compatibility Aliases
-
-A short list of legacy Material 3 token names is still aliased to the new tokens for the few callers that have not migrated yet. These aliases are temporary and will be removed once the components in `shared/ui` adopt the new tokens.
-
-| Legacy                       | Maps to             |
-| ---------------------------- | ------------------- |
-| `--color-background`         | `--color-bg`        |
-| `--color-on-background`      | `--color-fg`        |
-| `--color-on-surface`         | `--color-fg`        |
-| `--color-on-surface-variant` | `--color-muted-fg`  |
-| `--color-primary`            | `--color-accent`    |
-| `--color-on-primary`         | `--color-accent-fg` |
-| `--color-error`              | `--color-danger`    |
-| `--color-on-error`           | `--color-danger-fg` |
-| `--font-family`              | `--font-sans`       |
-| `--font-family-display`      | `--font-heading`    |
-| `--font-family-mono`         | `--font-mono`       |
+Components and templates use the `dark:` variant on every utility that differs between modes (`dark:bg-zinc-950`, `dark:text-zinc-50`, `dark:border-white/10`, etc.). The shared `ui-*` utilities also respond to `html.dark` through their internal `html.dark &` selectors.
+
+## Reference Components
+
+- `apps/web/app/src/app/shared/ui/actions/button/button.ts` consumes Tailwind v4 colors directly via inline arbitrary values (`[--btn-bg:var(--color-blue-600)]`). Solid buttons follow the Catalyst optical-border pattern with `--btn-bg` and `--btn-border` custom properties.
+- `apps/web/ui-designer/src/prototypes/app-auth-shell.html` is the canonical reference for composing raw Tailwind v4 utilities in a hand-authored HTML surface.
+- `apps/web/site/src/components/landing-page.astro` is the canonical reference for raw Tailwind v4 utilities in Astro templates.
+
+## Out Of Scope
+
+- Reintroducing semantic color tokens (`--color-bg`, `--color-panel`, `--color-accent`, etc.) in `@theme`. The workspace explicitly retired this layer in the catalyst pure-tokens alignment work; reintroducing it would contradict the Angular app and the ui-designer prototypes.
+- A custom Themis palette. The workspace uses the standard Tailwind v4 `zinc`/`blue`/`green`/`red`/`amber` scale. A bespoke palette is a follow-up decision.
+- Translating this contract into a separate brand skill. The Themis brand contract lives in this file and in `DESIGN.md`; no Anthropic-derived brand skill is vendored.
diff --git a/docs/specs/2026-06-26-site-utility-first-migration/plan.md b/docs/specs/2026-06-26-site-utility-first-migration/plan.md
new file mode 100644
index 0000000..51adac3
--- /dev/null
+++ b/docs/specs/2026-06-26-site-utility-first-migration/plan.md
@@ -0,0 +1,162 @@
+# Site Utility-First Migration — Implementation Plan
+
+The migration ships as a single PR. The blast radius is bounded to the Astro site + design system docs; no Angular changes are required.
+
+## PR1 — Site Utility-First Migration
+
+### Step 1 — Token audit
+
+Run the grep guards before touching any file. Confirm the count and locations of the legacy utility classes so we know what is in scope.
+
+```bash
+rg -n "bg-surface|bg-on-surface|text-on-surface|text-on-surface-variant|border-outline-variant|border-outline|bg-primary-container|text-on-primary-container|bg-primary|text-primary|text-on-primary|bg-tertiary|text-tertiary|bg-tertiary-container|text-on-tertiary-container|border-primary|border-primary-dim|border-tertiary-dim|text-outline|bg-error|focus-visible:outline-primary|--color-surface|--color-primary|--color-tertiary|--color-outline" apps/web/site/src
+
+rg -n "text-sky|text-slate|bg-slate|border-slate|text-yellow-400" apps/web/site/src
+```
+
+Expected surface: 71+ matches in `apps/web/site/src/components/landing-page.astro`, 6+ in `theme-switcher.astro`, 3+ in `locale-switcher.astro`, 8+ in `pages/docs/index.astro`.
+
+### Step 2 — Migrate `landing-page.astro`
+
+Edit `apps/web/site/src/components/landing-page.astro` end-to-end using the token mapping in `sdd.md`. Apply replacements in top-to-bottom order so each section is reviewable in isolation:
+
+1. Sticky `<nav>` (transparent white/dark with backdrop blur).
+2. Hero `<section>` (centered title, body, primary + secondary CTAs).
+3. Projects overview `<section>` (outer card with zinc-50 fill; inner cards with white/zinc-50 fills; "Active" badge; "Stale" badge; insights dots; decisions panel).
+4. Methodology `<section id="methodology">` (three-up grid with left blue rail).
+5. Detail `<section>` (context-window badge, features list with blue icons, task card with "View visual" and "Passed" rows).
+6. System `<section>` (two-up card grid).
+7. Closing `<section>` (centered CTA stack).
+8. `<footer>` (copyright + four-link row).
+
+Preserve every non-color class exactly. Do not change spacing, layout, ordering, copy, or breakpoints. The migration is strictly a color class replacement.
+
+### Step 3 — Migrate `theme-switcher.astro`
+
+Edit `apps/web/site/src/components/theme-switcher.astro` to use raw utilities:
+
+- Replace `text-on-surface-variant` with `text-zinc-500 dark:text-zinc-400`.
+- Replace `hover:bg-surface-container-high` with `hover:bg-zinc-100 dark:hover:bg-zinc-800`.
+- Replace `hover:text-primary` with `hover:text-blue-600 dark:hover:text-blue-500`.
+- Replace `focus-visible:outline-primary` with `focus-visible:outline-blue-600 dark:focus-visible:outline-blue-500`.
+- Replace `hover:bg-surface-container/90` with `hover:bg-zinc-100/90 dark:hover:bg-zinc-800/90`.
+- Replace `text-on-surface` with `text-zinc-950 dark:text-zinc-50`.
+- Replace `text-yellow-400` (sun icon) with `text-amber-500 dark:text-amber-400`.
+- Replace `text-white` (moon icon) with `text-zinc-50` (still readable on the dark surface).
+
+The `theme-switcher.ts` script is not touched.
+
+### Step 4 — Migrate `locale-switcher.astro`
+
+Edit `apps/web/site/src/components/locale-switcher.astro`:
+
+- Replace `text-on-surface-variant` with `text-zinc-500 dark:text-zinc-400`.
+- Replace `hover:text-primary` with `hover:text-blue-600 dark:hover:text-blue-500`.
+- Replace `text-on-surface` (active state) with `text-zinc-950 dark:text-zinc-50`.
+
+### Step 5 — Migrate `pages/docs/index.astro`
+
+Edit `apps/web/site/src/pages/docs/index.astro`:
+
+- Replace `text-sky-300` (eyebrow) with `text-blue-600 dark:text-blue-400`.
+- Replace `text-slate-300` (body) with `text-zinc-500 dark:text-zinc-400`.
+- Replace `text-white` (title, card headings) with `text-zinc-950 dark:text-zinc-50`.
+- Replace `bg-slate-950/60` (card surface) with `bg-white dark:bg-zinc-900`.
+- Replace `border-slate-800` (card border) with `border-zinc-950/10 dark:border-white/10`.
+
+The page keeps its `bg-zinc-950` page background (already in light/dark via `html.dark`).
+
+### Step 6 — Rewrite `docs/design-system/tokens.md`
+
+Replace the semantic-token table in `docs/design-system/tokens.md` with a **palette cheatsheet** that documents the raw Tailwind v4 utilities actually used by the workspace:
+
+- Light surface ladder: `bg-white` → `bg-zinc-50` → `bg-zinc-100`.
+- Dark surface ladder: `dark:bg-zinc-950` → `dark:bg-zinc-900` → `dark:bg-zinc-800`.
+- Text ladder: `text-zinc-950` / `dark:text-zinc-50`, `text-zinc-500` / `dark:text-zinc-400`.
+- Accents: `bg-blue-600` / `dark:bg-blue-500`, `bg-blue-600/10` / `dark:bg-blue-400/10`.
+- Success: `bg-green-100 text-green-700` / `dark:bg-green-500/20 dark:text-green-300`.
+- Danger: `bg-red-600` / `dark:bg-red-500`.
+- Borders: `border-zinc-950/10` / `dark:border-white/10`, `border-blue-600/40` / `dark:border-blue-400/40`.
+- Fonts (keep): `font-sans` (Inter), `font-heading` (Manrope), `font-mono` (JetBrains Mono).
+- Radii (keep): `radius-sm` (0.5rem), `radius-control` (0.5rem), `radius-panel` (0.75rem).
+- Shadows (keep): `shadow-sm`, `shadow-md`, `shadow-panel`.
+
+Drop the **Compatibility Aliases** table entirely. Keep the **Reusable Utilities** section (`ui-focus-ring`, `ui-panel`, `ui-panel-raised`, `ui-touch-target`, `ui-text-rhythm`).
+
+### Step 7 — Update `docs/design-system/recipes.md`
+
+Walk through each HTML snippet in `docs/design-system/recipes.md` and replace any reference to a legacy utility (`bg-surface-container-low`, `border-outline-variant`, etc.) with the raw Tailwind v4 utility equivalent. The Angular `app-*` recipes that use raw utilities stay byte-identical. Focus edits on:
+
+- The "Surface Hierarchy" / "Tonal Section Band" prose callouts — replace the `surface-container-low` reference with `bg-zinc-50` / `dark:bg-zinc-900`.
+- The "Mobile-First Layout" prose callouts — keep them; they already use the right vocabulary.
+- The "Buttons" section — keep the existing `tone="blue"` references; clarify that `blue` resolves to `bg-blue-600` / `text-white`.
+
+### Step 8 — Update `docs/agents/design-system.md`
+
+Edit `docs/agents/design-system.md`:
+
+- Replace the "Preserve the surface hierarchy: `surface`, `surface-container-low`, ..." bullet with the raw ladder: `bg-white` → `bg-zinc-50` → `bg-zinc-100` (light), `dark:bg-zinc-950` → `dark:bg-zinc-900` → `dark:bg-zinc-800` (dark).
+- Replace "Use ghost borders with `outline-variant` at low opacity" with "Use ghost borders with `border-zinc-950/10` (light) / `dark:border-white/10` (dark)".
+- Keep the rest of the file (mobile-first, accessibility, visual quality) intact.
+
+### Step 9 — Verify
+
+```bash
+# Static validation — these must return zero matches.
+rg "bg-surface|bg-on-surface|text-on-surface|text-on-surface-variant|border-outline-variant|border-outline|bg-primary-container|text-on-primary-container|bg-primary|text-primary|text-on-primary|bg-tertiary|text-tertiary|bg-tertiary-container|text-on-tertiary-container|border-primary|border-primary-dim|border-tertiary-dim|text-outline|bg-error|focus-visible:outline-primary|--color-surface|--color-primary|--color-tertiary|--color-outline" apps/web/site/src
+
+rg "text-sky|text-slate|bg-slate|border-slate|text-yellow-400" apps/web/site/src
+
+# Nx targets.
+pnpm nx run site:lint
+pnpm nx run site:typecheck
+pnpm nx run site:test
+pnpm nx run site:build --skip-nx-cache
+pnpm nx run site-e2e:e2e
+```
+
+### Step 10 — Manual visual check
+
+```bash
+pnpm nx serve site
+```
+
+- `/en/` and `/es/` in light mode: white page, blue CTAs, blue accent borders, green success badge, neutral surface ladder.
+- `/en/` and `/es/` in dark mode: deep zinc-950 background, blue-500 accents, blue-400/40 borders, green-300 text on green-500/20 badge.
+- `/docs/` in both modes: same zinc/blue palette.
+- Theme toggle, locale switcher, responsive breakpoints (375 / 768 / 1280): all preserved.
+- Browser console: zero errors, zero hydration warnings.
+
+### PR acceptance
+
+- All grep guards return zero matches.
+- All Nx targets pass.
+- The site smoke e2e (`pnpm nx run site-e2e:e2e`) passes without modification.
+- Manual visual check confirms light/dark parity with the seed prototype at `apps/web/ui-designer/src/prototypes/app-auth-shell.html`.
+- `DESIGN.md` at the repo root is unchanged (out of scope).
+
+## Nx Verification Commands
+
+```bash
+pnpm nx run site:lint
+pnpm nx run site:typecheck
+pnpm nx run site:test
+pnpm nx run site:build --skip-nx-cache
+pnpm nx run site-e2e:e2e
+```
+
+If a target is missing or changes, inspect it first with:
+
+```bash
+pnpm nx show project site --json
+pnpm nx show project site-e2e --json
+```
+
+## Out of Scope (Reminder)
+
+- Reintroducing semantic tokens in `styles.base.css`.
+- Changing Angular components in `apps/web/app` or `shared/ui`.
+- Updating `DESIGN.md` at the repo root.
+- Visual snapshot tests for the site (follow-up spec).
+- Reauthoring `apps/web/site/src/components/landing-page.astro` to follow the seed prototype's composition (different layout).
+- New i18n strings or copy changes in English or Spanish.
diff --git a/docs/specs/2026-06-26-site-utility-first-migration/requirements.md b/docs/specs/2026-06-26-site-utility-first-migration/requirements.md
new file mode 100644
index 0000000..07231c5
--- /dev/null
+++ b/docs/specs/2026-06-26-site-utility-first-migration/requirements.md
@@ -0,0 +1,101 @@
+# Site Utility-First Migration — Requirements
+
+## Context
+
+The Themis public website at `apps/web/site` is the Astro app that serves the marketing landing page, the locale-prefixed English and Spanish variants (`/en/`, `/es/`), and the `/docs/` redirect page. Its component layer uses Astro templates, but its styling layer is consumed by Tailwind v4 + the workspace's `styles.base.css` token file. Both the Angular app and the Astro site are supposed to share the same token source.
+
+The website's current styling was set by the [`2026-06-22-website-design-system-color-migration/`](./2026-06-22-website-design-system-color-migration/) spec, which migrated it to a Material 3 token vocabulary (`bg-surface`, `text-on-surface`, `bg-primary`, `bg-tertiary-container`, `border-outline-variant`, etc.). That spec is technically a color migration, not a redesign.
+
+Two subsequent specs changed the token contract without updating the site:
+
+1. [`2026-06-23-catalyst-pure-tokens-alignment/`](./2026-06-23-catalyst-pure-tokens-alignment/) retired the Material 3 tokens and replaced them with a documented Catalyst semantic set (`--color-bg`, `--color-panel`, `--color-accent`, etc.) plus Tailwind v4 utilities (`bg-bg`, `bg-panel`, `bg-accent`).
+2. The merge commit `52fba16 refactor(design-system): drop all custom semantic color tokens` deleted the semantic tokens from `styles.base.css` and switched the `ui-*` utilities to read Tailwind's standard `zinc` colors directly. The Angular components were migrated to use raw Tailwind v4 utilities (`bg-blue-600`, `text-zinc-950`, `border-zinc-950/10`, etc.).
+
+After those two changes, the website's Tailwind utility classes stop resolving. A class like `bg-surface` has no definition in `@theme`, no `--color-surface` custom property, and no `ui-surface` utility. The site renders with **no theme colors** — defaults to the browser's neutral palette — but the markup, layout, routing, content, and theme/locale switching all keep working because those don't depend on the broken classes.
+
+The discrepancy is invisible until someone opens `/en/` or `/es/` in a browser. The smoke e2e test (`apps/web/site-e2e/src/site-smoke.spec.ts`) only checks that `main` and `h1` are visible; it does not assert any styling. The unit test (`site-content.spec.ts`) checks content strings. Neither catches the visual breakage.
+
+## Goals
+
+1. Migrate every legacy Material 3 utility class in `apps/web/site/src/**` to the equivalent raw Tailwind v4 utility so the public website renders with the intended light/dark theme.
+2. Replace hard-coded `sky-*` and `slate-*` colors in `apps/web/site/src/pages/docs/index.astro` with the same `zinc`/`blue` palette the rest of the workspace uses.
+3. Update `docs/design-system/tokens.md` to describe the actual token layer (raw Tailwind v4 utilities, no semantic shim) and remove the obsolete "Compatibility Aliases" table.
+4. Update `docs/design-system/recipes.md` so every HTML snippet uses raw Tailwind v4 utilities instead of semantic tokens.
+5. Update `docs/agents/design-system.md` so it points at the workspace's "raw utilities, no semantic shim" pattern and removes the "preserve the surface hierarchy" advice that referenced the retired `surface-container-*` ladder.
+6. Preserve the page structure, section order, layout, responsive behavior, content, copy, routing, localization, theme switching, and locale switching exactly as they are today.
+
+## Non-Goals
+
+1. No redesign of the landing page. Section order, copy, layouts, and breakpoints stay byte-for-byte identical.
+2. No new sections, removed sections, or reordered sections.
+3. No new illustrations, icons, images, or decorative assets.
+4. No new i18n strings or copy changes in English or Spanish.
+5. No reintroduction of Material 3 token names or Catalyst semantic tokens in `styles.base.css`.
+6. No changes to Angular components in `apps/web/app` or `shared/ui`. The migration is scoped to the Astro site + design system docs.
+7. No new Nx targets or new ESLint rules.
+8. No new dependencies.
+9. No e2e test changes beyond keeping the existing `apps/web/site-e2e/src/site-smoke.spec.ts` green. Visual snapshot tests for the site are a follow-up spec.
+10. No changes to `DESIGN.md` at the repo root. That manuscript is intentionally out of scope; aligning it with the new token contract is a separate spec.
+
+## Decisions
+
+### D1 — Raw Tailwind v4 utilities, no semantic shim
+
+The site uses raw Tailwind v4 utility classes (`bg-white`, `bg-zinc-50`, `bg-blue-600`, `text-zinc-950`, `border-zinc-950/10`). We do **not** reintroduce semantic tokens in `@theme`. This matches the actual implementation pattern in:
+
+- `apps/web/app/src/app/shared/ui/actions/button/button.ts` — uses `var(--color-blue-600)`, `var(--color-zinc-100)`, etc. directly.
+- `apps/web/app/src/app/shared/ui/forms/switch/switch.ts` — uses `bg-accent` (a Tailwind v4 utility, not a semantic token) plus raw zinc utilities.
+- `apps/web/ui-designer/src/prototypes/app-auth-shell.html` — the seed prototype uses raw `bg-white`, `bg-zinc-50`, `text-zinc-950`, `bg-blue-600`, etc.
+
+The user explicitly rejected introducing semantic tokens as part of this work.
+
+### D2 — Single PR
+
+The user explicitly requested a single PR for this migration. The blast radius is bounded to:
+
+- `apps/web/site/src/components/landing-page.astro` (459 lines, 71+ legacy classes)
+- `apps/web/site/src/components/theme-switcher.astro` (42 lines, 6 legacy classes)
+- `apps/web/site/src/components/locale-switcher.astro` (19 lines, 3 legacy classes)
+- `apps/web/site/src/pages/docs/index.astro` (44 lines, hard-coded sky/slate)
+- `docs/design-system/tokens.md` (95 lines, full rewrite of the token table)
+- `docs/design-system/recipes.md` (289 lines, snippet updates)
+- `docs/agents/design-system.md` (52 lines, surface hierarchy advice removal)
+
+Total diff stays under 1000 changed lines because most edits are class replacements on existing lines. The single-PR shape matches the user's stated preference and the bounded scope.
+
+### D3 — Don't touch `DESIGN.md`
+
+`DESIGN.md` is the brand-level manuscript at the repo root. Its color recommendations (`var(--color-surface)`, `var(--color-primary)`, Material 3 palette names) have been stale since the Angular app switched to Catalyst tokens. Aligning it is out of scope for this spec and is deferred to a follow-up.
+
+### D4 — Don't touch `apps/web/app` or `shared/ui`
+
+The Angular app already uses raw Tailwind v4 utilities. The site migration is independent of any Angular change.
+
+### D5 — Keep `styles.base.css` unchanged
+
+`styles.base.css` already declares fonts, radii, shadows, and the `ui-*` utilities. The site consumes those utilities indirectly (via the `ui-focus-ring` and `ui-touch-target` references in its markup). No new tokens or utilities are needed.
+
+## Context
+
+### Tone
+
+- All prose, identifiers, commit messages, and PR descriptions stay in English per workspace rules.
+- The website's user-facing copy (English and Spanish) is unchanged.
+
+### Stack
+
+- Astro 5 (matches `apps/web/site`)
+- Tailwind v4 (matches `apps/web/site`, `apps/web/app`, `apps/web/ui-designer`)
+- `@tailwindcss/vite` plugin (matches `apps/web/site`)
+- Node 24+ (matches the rest of the workspace)
+- No new dependencies
+
+### Existing patterns to follow
+
+- The raw utility pattern from `apps/web/ui-designer/src/prototypes/app-auth-shell.html` is the canonical reference.
+- The `shared/ui` Button tone API uses `--btn-bg` / `--btn-border` custom properties set as inline Tailwind arbitrary values (`[--btn-bg:var(--color-blue-600)]`) — same pattern works for any "one-off token" the site needs.
+- Dark mode flips `html.dark` on the document element; the `:where(.dark, .dark *)` custom variant in `global.css` already covers it.
+
+### Open questions
+
+None at spec time.
diff --git a/docs/specs/2026-06-26-site-utility-first-migration/sdd.md b/docs/specs/2026-06-26-site-utility-first-migration/sdd.md
new file mode 100644
index 0000000..ad98f9c
--- /dev/null
+++ b/docs/specs/2026-06-26-site-utility-first-migration/sdd.md
@@ -0,0 +1,278 @@
+# Site Utility-First Migration — Software Design Document
+
+## Decision
+
+Migrate `apps/web/site` from the legacy Material 3 token vocabulary to **raw Tailwind v4 utility classes** (`bg-white`, `bg-zinc-50`, `bg-blue-600`, `text-zinc-950`, `border-zinc-950/10`, etc.) so the public website shares the same token source as the Angular app and the ui-designer prototypes. No semantic color tokens (`--color-bg`, `--color-panel`, `--color-accent`) are reintroduced into `styles.base.css` — they were deliberately removed in `52fba16 refactor(design-system): drop all custom semantic color tokens`, and `shared/ui`, `apps/web/ui-designer/src/prototypes/app-auth-shell.html`, and every other Tailwind v4 surface in the workspace now consume the standard Tailwind palette directly.
+
+This migration unblocks the website (which is currently visually broken because the legacy utility classes it relies on no longer exist in the token layer) and aligns it with the rest of the workspace's "utility-first, no semantic shim" posture.
+
+## Why now
+
+Three prior specs landed and changed the token contract underneath the website without updating it:
+
+| Spec                                                                     | What it changed                                                                                                          | Impact on the site                                                                                                                               |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `2026-06-22-catalyst-angular-ui-foundation/`                             | Introduced a thin Catalyst-style alias layer on top of Material 3 tokens.                                                | Site kept using Material 3 names.                                                                                                                |
+| `2026-06-23-catalyst-pure-tokens-alignment/`                             | Retired Material 3 names; documented semantic Catalyst tokens (`--color-bg`, `--color-panel`, `--color-accent`).         | Site kept using Material 3 names. The semantic tokens it points to in `tokens.md` were never actually exposed in `@theme`.                       |
+| `52fba16 refactor(design-system): drop all custom semantic color tokens` | Removed the `ui-*` utilities' dependency on semantic tokens and dropped the `@theme` color block.                        | Site's `bg-surface`, `text-on-surface`, `bg-primary`, etc. stopped resolving entirely. The site is currently rendering with **no theme colors**. |
+| `2026-06-26-ui-designer-app/`                                            | Shipped a seed prototype that uses raw Tailwind v4 utilities (`bg-white`, `bg-zinc-50`, `text-zinc-950`, `bg-blue-600`). | Established the canonical "no semantic shim" pattern for any HTML surface outside the Angular app.                                               |
+
+The site has been left in an inconsistent state: `tokens.md` documents tokens that don't exist in `@theme`, `landing-page.astro` references utility classes that don't generate any CSS, and the only working reference for "what to write" is the seed prototype in `apps/web/ui-designer/src/prototypes/app-auth-shell.html`.
+
+## Goals
+
+1. Replace every legacy utility class in `apps/web/site/src/**` with the equivalent raw Tailwind v4 utility so the public website renders with the intended light/dark theme.
+2. Replace hard-coded `sky-*`, `slate-*` colors in `apps/web/site/src/pages/docs/index.astro` with the same `zinc`/`blue` palette the rest of the workspace uses.
+3. Update `docs/design-system/tokens.md` to describe the actual token layer (raw Tailwind v4 utilities, no semantic shim) and remove the obsolete "Compatibility Aliases" table.
+4. Update `docs/design-system/recipes.md` so every `html` snippet uses raw Tailwind v4 utilities instead of semantic tokens.
+5. Update `docs/agents/design-system.md` so it points at the new pattern (raw Tailwind v4 utilities, no semantic tokens) and removes the "preserve the surface hierarchy" advice that referenced the retired `surface-container-*` ladder.
+6. Keep `styles.base.css` minimal: fonts, radii, shadows, and the existing `ui-*` utilities. **Do not** reintroduce semantic color tokens in `@theme`.
+7. Preserve the page structure, section order, layout, responsive behavior, content, copy, routing, localization, theme switching, and locale switching exactly as they are today.
+
+## Non-Goals
+
+1. No redesign of the landing page. Section order, copy, layouts, and breakpoints stay byte-for-byte identical.
+2. No new sections, removed sections, or reordered sections.
+3. No new illustrations, icons, images, or decorative assets.
+4. No new i18n strings or copy changes in English or Spanish.
+5. No reintroduction of Material 3 token names (`--color-surface`, `--color-primary`, `--color-on-primary`, `--color-tertiary`, `--color-outline`, `--color-outline-variant`, `--color-error`) or Catalyst semantic tokens (`--color-bg`, `--color-panel`, `--color-accent`, `--color-fg`, `--color-muted-fg`, `--color-danger`, `--color-border`, `--color-border-subtle`) in `styles.base.css`.
+6. No changes to Angular components in `apps/web/app` or `shared/ui`. The migration is scoped to the Astro site + design system docs.
+7. No new Nx targets or new ESLint rules.
+8. No new dependencies. The migration uses utilities that Tailwind v4 already exposes.
+9. No e2e test changes beyond keeping the existing `apps/web/site-e2e/src/site-smoke.spec.ts` green. Visual snapshot tests for the site are a follow-up.
+
+## Token Mapping
+
+The site currently uses these legacy utility classes. Every entry maps to the raw Tailwind v4 utility that replaces it.
+
+| Legacy class                                       | Replacement (light)              | Replacement (dark)                      | Notes                                                       |
+| -------------------------------------------------- | -------------------------------- | --------------------------------------- | ----------------------------------------------------------- |
+| `bg-surface`                                       | `bg-white`                       | `dark:bg-zinc-950`                      | Page background and section canvas                          |
+| `bg-surface-container-lowest`                      | `bg-white`                       | (omit, fall back to `dark:bg-zinc-950`) | White cards in dark mode inherit the page background        |
+| `bg-surface-container-low`                         | `bg-zinc-50`                     | `dark:bg-zinc-900`                      | Tonal section bands and panel fills                         |
+| `bg-surface-container`                             | `bg-zinc-100`                    | `dark:bg-zinc-800`                      | Nested panels                                               |
+| `bg-surface-container-high`                        | `bg-zinc-100`                    | `dark:bg-zinc-800`                      | Raised/active surface treatments                            |
+| `bg-surface-container-highest`                     | `bg-zinc-200`                    | `dark:bg-zinc-700`                      | Highest tonal surface (used for decorative accents only)    |
+| `text-on-surface`                                  | `text-zinc-950`                  | `dark:text-zinc-50`                     | Primary text                                                |
+| `text-on-surface-variant`                          | `text-zinc-500`                  | `dark:text-zinc-400`                    | Muted text and secondary labels                             |
+| `border-outline-variant`                           | `border-zinc-950/10`             | `dark:border-white/10`                  | Subtle dividers                                             |
+| `border-outline`                                   | `border-zinc-950/20`             | `dark:border-white/20`                  | Visible borders                                             |
+| `bg-primary`                                       | `bg-blue-600`                    | `dark:bg-blue-500`                      | Primary action fill                                         |
+| `text-primary`                                     | `text-blue-600`                  | `dark:text-blue-500`                    | Primary action text                                         |
+| `text-on-primary`                                  | `text-white`                     | `text-white`                            | Text on primary fill                                        |
+| `bg-primary-container` / `bg-primary/10`           | `bg-blue-600/10`                 | `dark:bg-blue-400/10`                   | Soft primary fill                                           |
+| `bg-primary/20`                                    | `bg-blue-600/20`                 | `dark:bg-blue-400/20`                   | Soft primary fill (stronger)                                |
+| `bg-primary/5`                                     | `bg-blue-600/5`                  | `dark:bg-blue-400/5`                    | Soft primary fill (faintest)                                |
+| `text-on-primary-container`                        | `text-blue-700`                  | `dark:text-blue-300`                    | Text on soft primary fill                                   |
+| `border-primary`                                   | `border-blue-600`                | `dark:border-blue-500`                  | Accent border                                               |
+| `border-primary-dim`                               | `border-blue-600/40`             | `dark:border-blue-400/40`               | Accent border (left rail, decorative accent)                |
+| `bg-tertiary`                                      | `bg-green-700`                   | `dark:bg-green-400`                     | Success/positive accent fill                                |
+| `text-tertiary`                                    | `text-green-700`                 | `dark:text-green-400`                   | Success/positive accent text                                |
+| `bg-tertiary/20`                                   | `bg-green-600/20`                | `dark:bg-green-400/20`                  | Success/positive fill (soft)                                |
+| `bg-tertiary-container`                            | `bg-green-100`                   | `dark:bg-green-500/20`                  | Success badge fill                                          |
+| `text-on-tertiary-container`                       | `text-green-700`                 | `dark:text-green-300`                   | Success badge text                                          |
+| `border-tertiary-dim`                              | `border-green-600/40`            | `dark:border-green-400/40`              | Success accent border                                       |
+| `text-outline`                                     | `text-zinc-500`                  | `dark:text-zinc-400`                    | Outline-level text                                          |
+| `bg-error`                                         | `bg-red-600`                     | `dark:bg-red-500`                       | Error/destructive fill                                      |
+| `focus-visible:outline-primary`                    | `focus-visible:outline-blue-600` | `dark:focus-visible:outline-blue-500`   | Focus outline                                               |
+| `hover:text-primary`                               | `hover:text-blue-600`            | `dark:hover:text-blue-500`              | Hover state                                                 |
+| `hover:bg-primary/90`                              | `hover:bg-blue-700`              | `dark:hover:bg-blue-500`                | Hover state on primary CTA                                  |
+| `hover:bg-surface-container-high`                  | `hover:bg-zinc-100`              | `dark:hover:bg-zinc-800`                | Hover state on tonal surface                                |
+| `hover:bg-surface-container/90`                    | `hover:bg-zinc-100/90`           | `dark:hover:bg-zinc-800/90`             | Hover state on tonal surface (translucent)                  |
+| `hover:bg-surface-container`                       | `hover:bg-zinc-100`              | `dark:hover:bg-zinc-800`                | Hover state on tonal surface                                |
+| `dark:bg-surface/80`                               | `bg-white/80`                    | `dark:bg-zinc-950/80`                   | Translucent header (keep `backdrop-blur-md`)                |
+| `dark:bg-surface-container/50`                     | —                                | `dark:bg-zinc-800/50`                   | Translucent surface in dark mode                            |
+| `dark:bg-surface-container-highest/30`             | —                                | `dark:bg-zinc-700/30`                   | Translucent surface in dark mode                            |
+| `dark:bg-surface-container-highest`                | —                                | `dark:bg-zinc-700`                      | Decorative surface in dark mode                             |
+| `dark:bg-surface-container`                        | —                                | `dark:bg-zinc-800`                      | Nested panel in dark mode                                   |
+| `dark:bg-surface-container-low`                    | —                                | `dark:bg-zinc-900`                      | Section band in dark mode                                   |
+| `dark:bg-primary/5`                                | —                                | `dark:bg-blue-500/5`                    | Decorative glow                                             |
+| `dark:border-outline-variant/20`                   | —                                | `dark:border-white/10`                  | Border in dark mode                                         |
+| `dark:border-slate-400/10`                         | —                                | `dark:border-white/10`                  | Stray slate border — collapse into the white/10 border rule |
+| `text-yellow-400` (theme switcher sun icon)        | `text-amber-500`                 | `text-amber-400`                        | Sun icon uses amber                                         |
+| `text-white` (theme switcher moon icon on dark bg) | —                                | `text-zinc-50`                          | Moon icon stays readable on dark surface                    |
+| `text-sky-300` (docs page eyebrow)                 | `text-blue-600`                  | `dark:text-blue-400`                    | Docs page eyebrow                                           |
+| `text-slate-300` (docs page body)                  | `text-zinc-500`                  | `dark:text-zinc-400`                    | Docs page body                                              |
+| `text-white` (docs page title)                     | `text-zinc-950`                  | `dark:text-zinc-50`                     | Docs page title                                             |
+| `bg-slate-950/60` (docs cards)                     | `bg-white`                       | `dark:bg-zinc-900`                      | Docs page card surface                                      |
+| `border-slate-800` (docs cards)                    | `border-zinc-950/10`             | `dark:border-white/10`                  | Docs page card border                                       |
+
+Any legacy class not listed above maps through the same pattern: every `bg-{surface-ladder}-{shade}` becomes a `bg-zinc-{shade}` (with `dark:bg-zinc-{shade+1}` for the dark mode), every `text-{on-surface, on-surface-variant, primary, tertiary}` becomes the matching `text-{zinc|blue|green}-{shade}` (with `dark:` for the dark mode), and every `border-{outline-variant, outline, primary, tertiary}-{dim}` becomes the matching `border-{zinc|blue|green}-{shade}/{opacity}` (with `dark:` for the dark mode).
+
+## Implementation Strategy
+
+1. **Token audit.** Grep `apps/web/site/src` for the legacy class names listed in the token mapping. Confirm the count and locations before editing.
+2. **Replace in dependency order.**
+   1. `apps/web/site/src/components/landing-page.astro` first (largest surface, 71+ legacy classes).
+   2. `apps/web/site/src/components/theme-switcher.astro` next (translucent hover states and focus outlines).
+   3. `apps/web/site/src/components/locale-switcher.astro` (3 classes).
+   4. `apps/web/site/src/pages/docs/index.astro` (replace `sky`/`slate` with `blue`/`zinc`).
+3. **Align documentation.** Update `docs/design-system/tokens.md` to describe the actual token layer (raw Tailwind v4 utilities) and remove the "Compatibility Aliases" table. Update `docs/design-system/recipes.md` so HTML snippets use raw utilities. Update `docs/agents/design-system.md` to drop the `surface-container-*` references and point at the workspace pattern.
+4. **Verify.** Run the existing site Nx targets (`pnpm nx run site:lint`, `pnpm nx run site:typecheck`, `pnpm nx run site:test`, `pnpm nx run site:build`) and the existing `pnpm nx run site-e2e:e2e` smoke suite. Manually verify `/en/`, `/es/`, and `/docs/` in light and dark mode.
+
+## Component Guidance
+
+### Sticky header (`landing-page.astro` `<nav>`)
+
+```html
+<nav
+  class="sticky top-0 z-50 mx-auto flex w-full max-w-screen-2xl items-center justify-between border-b border-zinc-950/10 bg-white/80 px-4 py-3 backdrop-blur-md transition-colors duration-200 ease-in-out md:px-12 dark:border-white/10 dark:bg-zinc-950/80"
+></nav>
+```
+
+### Primary CTA button
+
+```html
+<a
+  href="{appHref}"
+  class="rounded-lg bg-blue-600 px-6 py-2 text-sm font-semibold text-white transition-all hover:bg-blue-700 active:scale-95"
+>
+  {content.headerCta}
+</a>
+```
+
+### Secondary CTA button
+
+```html
+<a
+  href="#methodology"
+  class="w-full rounded-lg border border-zinc-950/20 px-6 py-2.5 text-center font-semibold transition-colors hover:bg-zinc-100 sm:w-auto md:px-8 md:py-3 md:font-bold dark:border-white/20 dark:hover:bg-zinc-800"
+>
+  {content.heroSecondary}
+</a>
+```
+
+### Card / Panel
+
+```html
+<article
+  class="overflow-hidden rounded-xl border border-zinc-950/10 bg-white shadow-2xl dark:border-white/10 dark:bg-zinc-900"
+>
+  <div class="bg-zinc-50 p-4 md:p-8 dark:bg-zinc-900/50">...</div>
+</article>
+```
+
+### Status badge ("Active" / "Stale")
+
+```html
+<!-- Success -->
+<span
+  class="rounded bg-green-100 px-2 py-0.5 text-xs font-black text-green-700 uppercase dark:bg-green-500/20 dark:text-green-300"
+>
+  Active
+</span>
+
+<!-- Neutral -->
+<span
+  class="rounded bg-zinc-100 px-2 py-0.5 text-xs font-black tracking-wider text-zinc-500 uppercase dark:bg-zinc-800 dark:text-zinc-400"
+>
+  Stale
+</span>
+```
+
+### Theme switcher
+
+```html
+<label
+  for="theme-switch-input"
+  tabindex="0"
+  class="relative flex h-10 w-10 cursor-pointer items-center justify-center overflow-hidden rounded-md text-zinc-500 transition-colors outline-none hover:bg-zinc-100 hover:text-blue-600 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-blue-500 dark:focus-visible:outline-blue-500"
+></label>
+```
+
+The sun/moon icons keep the same `amber` (light) and `zinc-50` (dark) colors but ride on `currentColor` instead of `text-yellow-400`/`text-white`.
+
+### Locale switcher
+
+```html
+<div class="flex items-center gap-4 font-sans text-xs font-black tracking-widest text-zinc-500 uppercase dark:text-zinc-400">
+  <a
+    href="/en/"
+    class:list={[
+      'no-underline hover:text-blue-600 dark:hover:text-blue-500',
+      locale === 'en' && 'font-extrabold text-zinc-950 dark:text-zinc-50',
+    ]}
+  >
+    EN
+  </a>
+  <span class="opacity-30">/</span>
+  <a
+    href="/es/"
+    class:list={[
+      'no-underline hover:text-blue-600 dark:hover:text-blue-500',
+      locale === 'es' && 'font-extrabold text-zinc-950 dark:text-zinc-50',
+    ]}
+  >
+    ES
+  </a>
+</div>
+```
+
+## Accessibility Requirements
+
+- WCAG AA contrast for primary text, secondary text, buttons, and badges in both light and dark themes. The chosen `zinc-950` on `white`, `zinc-50` on `zinc-950`, `white` on `blue-600`, and `green-700` on `green-100` pairs all clear AA.
+- Preserve visible keyboard focus states (`focus-visible:outline-2 focus-visible:outline-offset-2`) on links, buttons, language switcher entries, and the theme toggle.
+- Do not rely on color alone for status. The existing "Active" / "Stale" badges already pair color with a text label.
+- Keep the existing semantic HTML5 structure (`<main>`, `<nav>`, `<section>`, `<footer>`, `<article>`, `<header>`, `<h1>`–`<h5>`).
+- `prefers-reduced-motion` continues to be honored through the existing `@media (prefers-reduced-motion: reduce)` block in `styles.base.css`.
+
+## Verification
+
+### Automated
+
+```bash
+pnpm nx run site:lint
+pnpm nx run site:typecheck
+pnpm nx run site:test
+pnpm nx run site:build --skip-nx-cache
+pnpm nx run site-e2e:e2e
+```
+
+### Static validation (grep guards)
+
+```bash
+# All of these must return zero matches.
+rg "bg-surface|bg-on-surface|text-on-surface|text-on-surface-variant|border-outline-variant|border-outline|bg-primary-container|text-on-primary-container|bg-primary|text-primary|text-on-primary|bg-tertiary|text-tertiary|bg-tertiary-container|text-on-tertiary-container|border-primary|border-tertiary|text-outline|bg-error|focus-visible:outline-primary|--color-surface|--color-primary|--color-tertiary|--color-outline" apps/web/site/src
+rg "text-sky|text-slate|bg-slate|border-slate" apps/web/site/src
+rg "text-yellow-400" apps/web/site/src
+```
+
+`DESIGN.md` at the repo root keeps its legacy `var(--color-surface)` recommendations (it is the brand-level manuscript and is not part of this migration); only the design-system docs under `docs/design-system/**` and `docs/agents/design-system.md` are updated.
+
+### Manual visual verification
+
+- `/en/` and `/es/` in light mode: white page, blue CTAs, blue accent borders, green success badge, neutral surface ladder (zinc-50, zinc-100, white).
+- `/en/` and `/es/` in dark mode: deep zinc-950 background, blue-500 accents, blue-400/40 borders, green-300 text on green-500/20 badge.
+- `/docs/` in both modes: same zinc/blue palette as the landing; no stray `sky`/`slate` colors.
+- Theme toggle: light → dark flips surfaces and accents without layout shift.
+- Locale switcher: hover and active states remain legible in both modes.
+- Mobile (375), tablet (768), desktop (1280): responsive structure unchanged.
+- Browser console: zero errors, zero hydration warnings.
+
+## Risks
+
+| Risk                                                                        | Mitigation                                                                                                                                                                                              |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Token-name changes drift into layout or content edits                       | Treat any non-color class change as out of scope. The grep guard catches accidental edits to the legacy vocabulary.                                                                                     |
+| Dark-mode contrast fails for the new pairings                               | Verify the chosen zinc/blue/green/red pairs against the existing dark mode contract from `docs/design-system/recipes.md`. Fall back to `blue-400` / `zinc-300` if any pair fails AA.                    |
+| `tokens.md` rewrite accidentally removes guidance the angular app relies on | The angular app uses raw Tailwind v4 utilities through `shared/ui` (no semantic tokens), so the rewrite is purely a doc accuracy fix. Update `shared/ui` consumers separately if they read `tokens.md`. |
+| `DESIGN.md` keeps recommending `var(--color-surface)` etc.                  | Document the discrepancy in the spec validation. A follow-up spec can realign `DESIGN.md` once the Angular app's token contract is formalized.                                                          |
+| Spec becomes a "redesign" instead of a migration                            | Hold the line on layout, copy, and section order. The only changes are color classes plus the documentation accuracy fixes.                                                                             |
+
+## Alternatives Considered
+
+1. **Reintroduce semantic tokens (`--color-bg`, `--color-panel`, `--color-accent`) in `@theme`.** Rejected: contradicts `52fba16 refactor(design-system): drop all custom semantic color tokens` and the working pattern in `shared/ui` and the ui-designer seed prototype. The Angular app does not depend on semantic tokens.
+2. **Two-PR split (token audit + migration + docs).** Rejected: the user explicitly requested a single PR for this migration. The blast radius is bounded to the site + design-system docs, so the review surface stays manageable.
+3. **Update `DESIGN.md` as part of this migration.** Deferred: `DESIGN.md` is the brand-level manuscript and its recommendations have drifted from the implementation for a long time. A separate brand-doc alignment spec is the right scope.
+
+## Success Criteria
+
+- `apps/web/site/src/**` contains zero legacy Material 3 utility classes (`bg-surface`, `text-on-surface`, `bg-primary`, etc.).
+- `apps/web/site/src/**` contains zero hard-coded `sky-*` or `slate-*` colors.
+- `/en/`, `/es/`, and `/docs/` render with the intended light and dark mode palette in a browser.
+- `docs/design-system/tokens.md` describes raw Tailwind v4 utilities and removes the obsolete "Compatibility Aliases" table.
+- `docs/design-system/recipes.md` HTML snippets use raw Tailwind v4 utilities.
+- `docs/agents/design-system.md` no longer references the retired `surface-container-*` ladder or semantic tokens.
+- `pnpm nx run site:lint`, `pnpm nx run site:typecheck`, `pnpm nx run site:test`, `pnpm nx run site:build`, and `pnpm nx run site-e2e:e2e` all pass.
+- The existing `apps/web/site-e2e/src/site-smoke.spec.ts` passes without modification.
+- `apps/web/site/astro.config.mjs`, the i18n config, the base layout SEO/OG block, the theme switcher script, and the SEO images all stay byte-identical.
diff --git a/docs/specs/2026-06-26-site-utility-first-migration/validation.md b/docs/specs/2026-06-26-site-utility-first-migration/validation.md
new file mode 100644
index 0000000..d477157
--- /dev/null
+++ b/docs/specs/2026-06-26-site-utility-first-migration/validation.md
@@ -0,0 +1,159 @@
+# Site Utility-First Migration — Validation
+
+## Status
+
+Pending. Updated after the PR lands.
+
+## Automated
+
+### Static validation (grep guards)
+
+All of these must return **zero matches** under `apps/web/site/src`:
+
+```bash
+# Legacy Material 3 utility classes.
+rg "bg-surface|bg-on-surface|text-on-surface|text-on-surface-variant|border-outline-variant|border-outline|bg-primary-container|text-on-primary-container|bg-primary|text-primary|text-on-primary|bg-tertiary|text-tertiary|bg-tertiary-container|text-on-tertiary-container|border-primary|border-primary-dim|border-tertiary-dim|text-outline|bg-error|focus-visible:outline-primary|--color-surface|--color-primary|--color-tertiary|--color-outline" apps/web/site/src
+
+# Hard-coded colors that drifted from the workspace palette.
+rg "text-sky|text-slate|bg-slate|border-slate|text-yellow-400" apps/web/site/src
+```
+
+### Nx targets
+
+```bash
+pnpm nx run site:lint                # expected: 0 errors, 0 new warnings
+pnpm nx run site:typecheck           # expected: 0 errors
+pnpm nx run site:test                # expected: existing tests pass
+pnpm nx run site:build --skip-nx-cache   # expected: builds dist/apps/web/site
+pnpm nx run site-e2e:e2e             # expected: site-smoke.spec.ts passes against both /en/ and /es/
+```
+
+The smoke e2e test (`apps/web/site-e2e/src/site-smoke.spec.ts`) must pass without modification. It asserts `response.ok()` is true, `<main>` is visible, and the first `<h1>` is visible.
+
+## Token Usage Validation
+
+- `landing-page.astro` uses raw Tailwind v4 utilities for every color reference.
+- `theme-switcher.astro` uses raw Tailwind v4 utilities (`text-zinc-500 dark:text-zinc-400`, `hover:bg-zinc-100 dark:hover:bg-zinc-800`, `focus-visible:outline-blue-600 dark:focus-visible:outline-blue-500`).
+- `locale-switcher.astro` uses raw Tailwind v4 utilities (`text-zinc-500 dark:text-zinc-400`, `hover:text-blue-600 dark:hover:text-blue-500`).
+- `pages/docs/index.astro` uses raw Tailwind v4 utilities (`text-blue-600 dark:text-blue-400`, `bg-white dark:bg-zinc-900`, `border-zinc-950/10 dark:border-white/10`).
+- No raw hex colors (`bg-[#...]`, `text-[#...]`) appear in any site component.
+- No `var(--color-*)` references to non-standard custom properties.
+
+## Documentation Validation
+
+### `docs/design-system/tokens.md`
+
+- Token table describes raw Tailwind v4 utilities (no `--color-bg`, `--color-panel`, `--color-accent`).
+- "Compatibility Aliases" table is removed.
+- Reusable utilities section (`ui-focus-ring`, `ui-panel`, `ui-panel-raised`, `ui-touch-target`, `ui-text-rhythm`) is preserved.
+- Dark mode section keeps the `@custom-variant dark (&:where(.dark, .dark *))` reference.
+- Fonts, radii, and shadow tables stay identical.
+
+### `docs/design-system/recipes.md`
+
+- Every HTML snippet uses raw Tailwind v4 utilities.
+- The Angular `app-*` recipes stay byte-identical where they already use raw utilities.
+- The "Tonal Section Band" / "Surface Hierarchy" prose references `bg-zinc-50` / `dark:bg-zinc-900`, not `surface-container-low`.
+- The "Buttons" section clarifies that `tone="blue"` resolves to `bg-blue-600` / `text-white`.
+
+### `docs/agents/design-system.md`
+
+- The "Preserve the surface hierarchy" bullet lists the raw zinc ladder, not `surface-container-*` names.
+- The "Use ghost borders" bullet lists `border-zinc-950/10` / `dark:border-white/10`, not `outline-variant`.
+- Mobile-first, accessibility, and visual quality sections are unchanged.
+
+## Accessibility Validation
+
+- WCAG AA contrast for all visible text:
+  - `text-zinc-950` on `bg-white` ≈ 19.3:1 (AAA).
+  - `text-zinc-50` on `bg-zinc-950` ≈ 18.9:1 (AAA).
+  - `text-zinc-500` on `bg-white` ≈ 4.6:1 (AA body text).
+  - `text-zinc-400` on `bg-zinc-950` ≈ 8.2:1 (AAA body text).
+  - `text-white` on `bg-blue-600` ≈ 4.6:1 (AA).
+  - `text-green-700` on `bg-green-100` ≈ 4.7:1 (AA).
+  - `text-green-300` on `dark:bg-green-500/20` over `dark:bg-zinc-950` ≈ 9.1:1 (AAA).
+- Focus states:
+  - Theme switcher: `focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 dark:focus-visible:outline-blue-500`.
+  - Locale switcher links: inherit the existing browser underline-on-focus behavior plus the new color change.
+  - CTAs: native focus rings from the browser.
+- Semantic HTML5 structure (`<main>`, `<nav>`, `<section>`, `<footer>`, `<article>`, `<header>`, `<h1>`–`<h5>`) is preserved.
+- `prefers-reduced-motion` is honored through the existing `@media (prefers-reduced-motion: reduce)` block in `styles.base.css`.
+
+## Code Quality Checks
+
+- No `var(--color-surface)`, `var(--color-primary)`, `var(--color-on-surface)`, `var(--color-tertiary)`, etc. references in the site. — verified by the grep guard.
+- No dynamic class strings (string interpolation that builds Tailwind class names) in any site component.
+- No new dependencies added to `package.json` or `pnpm-lock.yaml`.
+- No changes to `astro.config.mjs`, `project.json`, `tsconfig.json`, `vitest.config.ts`, or `eslint.config.mjs` for the site.
+- No changes to `styles.base.css` (kept as-is).
+- No changes to `apps/web/site-e2e/src/site-smoke.spec.ts` (existing test must pass unchanged).
+
+## Visual Check
+
+### Light mode
+
+- Page background: `bg-white`.
+- Sticky nav: `bg-white/80` with `backdrop-blur-md`.
+- Hero section: zinc-950 title text, zinc-500 body text.
+- Primary CTA: `bg-blue-600 text-white`.
+- Secondary CTA: `border-zinc-950/20` with `hover:bg-zinc-100`.
+- Projects overview card: `bg-white` outer, `bg-zinc-50` inner.
+- Project card with "Active" badge: green badge `bg-green-100 text-green-700`.
+- Project card with "Stale" badge: neutral badge `bg-zinc-100 text-zinc-500`.
+- Insights dots: `bg-red-600` (error) and `bg-blue-600` (primary).
+- Decisions panel: `border-l-2 border-green-600/40` rail.
+- Methodology section: `bg-zinc-50` with `border-y border-zinc-950/10`, left blue rail.
+- Detail features list: `bg-zinc-50` items with `border-l-4 border-blue-600`.
+- Task card: `bg-white` with `bg-zinc-50` rows.
+- Closing CTA stack: blue primary, outline secondary.
+- Footer: `bg-zinc-50` with `text-zinc-500` labels.
+
+### Dark mode
+
+- Page background: `dark:bg-zinc-950`.
+- Sticky nav: `dark:bg-zinc-950/80` with `backdrop-blur-md`.
+- Hero section: zinc-50 title text, zinc-400 body text.
+- Primary CTA: `dark:bg-blue-500 text-white`.
+- Secondary CTA: `dark:border-white/20` with `dark:hover:bg-zinc-800`.
+- Projects overview card: `dark:bg-zinc-900` outer, `dark:bg-zinc-900/50` inner.
+- Project card with "Active" badge: green badge `dark:bg-green-500/20 dark:text-green-300`.
+- Project card with "Stale" badge: neutral badge `dark:bg-zinc-800 dark:text-zinc-400`.
+- Insights dots: `dark:bg-red-500` (error) and `dark:bg-blue-500` (primary).
+- Decisions panel: `dark:border-blue-400/40` rail.
+- Methodology section: `dark:bg-zinc-900` with `dark:border-y dark:border-white/10`.
+- Detail features list: `dark:bg-zinc-900` items with `dark:border-l-4 dark:border-blue-500`.
+- Task card: `dark:bg-zinc-900` with `dark:bg-zinc-800` rows.
+- Closing CTA stack: blue primary, outline secondary.
+- Footer: `dark:bg-zinc-900` with `dark:text-zinc-400` labels.
+
+### Docs page (`/docs/`)
+
+- Light mode: zinc-950 title, blue-600 eyebrow, zinc-500 body, white cards, zinc-950/10 borders.
+- Dark mode: zinc-50 title, blue-400 eyebrow, zinc-400 body, zinc-900 cards, white/10 borders.
+
+### Responsive
+
+- Mobile (375), tablet (768), desktop (1280): layout, breakpoints, and content remain identical to the pre-migration baseline.
+- Touch targets remain ≥ 44px where they were before (theme switcher, locale switcher, CTA buttons).
+
+## Definition of Done
+
+The migration is complete when:
+
+1. All grep guards return zero matches under `apps/web/site/src`.
+2. `pnpm nx run site:lint`, `pnpm nx run site:typecheck`, `pnpm nx run site:test`, `pnpm nx run site:build --skip-nx-cache`, and `pnpm nx run site-e2e:e2e` all pass.
+3. The existing `apps/web/site-e2e/src/site-smoke.spec.ts` passes without modification.
+4. `docs/design-system/tokens.md` describes raw Tailwind v4 utilities and drops the obsolete "Compatibility Aliases" table.
+5. `docs/design-system/recipes.md` HTML snippets use raw Tailwind v4 utilities.
+6. `docs/agents/design-system.md` points at the workspace's raw-utility pattern.
+7. `/en/`, `/es/`, and `/docs/` render with the intended light/dark theme palette in a browser.
+8. Theme switching, locale switching, and responsive behavior are preserved.
+9. Browser console reports zero errors and zero hydration warnings.
+10. `DESIGN.md` at the repo root is unchanged (intentionally out of scope; documented as a known follow-up).
+
+## Notes
+
+- The `2026-06-22-website-design-system-color-migration/` spec becomes obsolete once this migration lands. The spec directory stays in git history but is no longer the source of truth for site colors.
+- A follow-up spec should align `DESIGN.md` with the actual token contract. That manuscript currently recommends `var(--color-surface)`, `var(--color-primary)`, etc., which have not existed in `@theme` since `52fba16 refactor(design-system): drop all custom semantic color tokens`.
+- A follow-up spec should add visual snapshot tests for the site (e.g. `pnpm nx run site-e2e:e2e -- --grep visual`). The smoke test catches structural breakage but not visual regression.
+- The `apps/web/ui-designer/src/prototypes/` folder is the canonical reference for "raw Tailwind v4 utility pattern" in HTML surfaces. The migrated site should match that vocabulary byte-for-byte at the utility level.