diff --git a/src/components/BraccatoExample.tsx b/src/components/BraccatoExample.tsx
index c10cf8a..e6cc8ca 100644
--- a/src/components/BraccatoExample.tsx
+++ b/src/components/BraccatoExample.tsx
@@ -203,7 +203,7 @@ export default function BraccatoExample({
           width: 40rem;
           height: 30rem;
           transform: translate(-50%, -50%);
-          background: radial-gradient(closest-side, rgba(255, 255, 255, 0.1), transparent);
+          background: radial-gradient(closest-side, var(--glow), transparent);
           pointer-events: none;
         }
 
@@ -382,7 +382,7 @@ export default function BraccatoExample({
           grid-column: 2;
           margin: 0;
           padding: 0;
-          background-color: var(--bg-primary);
+          background-color: var(--surface-code);
           border: none;
           border-radius: var(--radius-lg);
           overflow: hidden;
diff --git a/src/components/Header.astro b/src/components/Header.astro
index 574a7ec..024ba8a 100644
--- a/src/components/Header.astro
+++ b/src/components/Header.astro
@@ -1,6 +1,11 @@
 ---
 import { currentPathOf, headerLinks } from '../nav';
 
+const ICONS = {
+  sun: '<path d="M12 12m-4 0a4 4 0 1 0 8 0a4 4 0 1 0 -8 0" /><path d="M3 12h1m8 -9v1m8 8h1m-9 8v1m-6.4 -15.4l.7 .7m12.1 -.7l-.7 .7m0 11.4l.7 .7m-12.1 -.7l-.7 .7" />',
+  moon: '<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />',
+};
+
 const currentPath = currentPathOf(Astro.url);
 ---
 
@@ -21,16 +26,56 @@ const currentPath = currentPathOf(Astro.url);
         </a>
       ))}
     </nav>
+
+    <button type="button" class="theme-toggle" aria-label="Toggle color theme" data-theme-toggle>
+      <span class="morph" data-theme-icon>
+        <span data-morph="light" data-active="false" aria-hidden="true"><svg viewBox="0 0 24 24" aria-hidden="true" set:html={ICONS.sun} /></span>
+        <span data-morph="dark" data-active="true"><svg viewBox="0 0 24 24" aria-hidden="true" set:html={ICONS.moon} /></span>
+      </span>
+    </button>
   </div>
 </header>
 
+<script>
+  import { morphTo } from '../morph';
+  import { THEME_STORAGE_KEY, type Theme } from '../theme';
+
+  const toggle = document.querySelector<HTMLButtonElement>('[data-theme-toggle]');
+  const icon = document.querySelector<HTMLElement>('[data-theme-icon]');
+  const systemDark = window.matchMedia('(prefers-color-scheme: dark)');
+
+  const currentTheme = (): Theme => {
+    const chosen = document.documentElement.dataset.theme;
+    if (chosen === 'light' || chosen === 'dark') return chosen;
+    return systemDark.matches ? 'dark' : 'light';
+  };
+
+  const render = () => {
+    const theme = currentTheme();
+    if (icon) morphTo(icon, theme);
+    toggle?.setAttribute('aria-label', `Switch to ${theme === 'dark' ? 'light' : 'dark'} theme`);
+  };
+
+  toggle?.addEventListener('click', () => {
+    const next: Theme = currentTheme() === 'dark' ? 'light' : 'dark';
+    document.documentElement.dataset.theme = next;
+    localStorage.setItem(THEME_STORAGE_KEY, next);
+    render();
+  });
+
+  systemDark.addEventListener('change', render);
+  render();
+  icon?.getBoundingClientRect();
+  icon?.setAttribute('data-ready', '');
+</script>
+
 <style>
   .header {
     position: sticky;
     top: 0;
     z-index: 100;
     height: var(--header-height);
-    background-color: rgba(15, 14, 19, 0.8);
+    background-color: color-mix(in srgb, var(--bg-primary) 80%, transparent);
     backdrop-filter: blur(8px);
     border-bottom: 1px solid var(--border);
   }
@@ -88,9 +133,54 @@ const currentPath = currentPathOf(Astro.url);
     background-color: var(--bg-secondary);
   }
 
+  .theme-toggle {
+    margin-left: auto;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 32px;
+    height: 32px;
+    padding: 0;
+    border: none;
+    border-radius: var(--radius-md);
+    background: none;
+    color: var(--text-secondary);
+    cursor: pointer;
+    transition: color var(--transition-fast), background-color var(--transition-fast);
+  }
+
+  .theme-toggle:hover {
+    color: var(--text-primary);
+    background-color: var(--bg-tertiary);
+  }
+
+  .theme-toggle .morph:not([data-ready]) > * {
+    transition: none;
+  }
+
+  .theme-toggle svg {
+    width: 0.875rem;
+    height: 0.875rem;
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 1.5;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
+
+  @supports not (color: light-dark(#000, #fff)) {
+    .theme-toggle {
+      display: none;
+    }
+  }
+
   @media (max-width: 1024px) {
     .nav {
       display: none;
     }
+
+    .theme-toggle {
+      margin-right: 40px;
+    }
   }
 </style>
diff --git a/src/components/LyricsPreview.tsx b/src/components/LyricsPreview.tsx
index 7a47bba..d813c8a 100644
--- a/src/components/LyricsPreview.tsx
+++ b/src/components/LyricsPreview.tsx
@@ -172,9 +172,10 @@ export default function LyricsPreview({ content, durationS }: LyricsPreviewProps
       </div>
 
       <style>{`
-        :root {
-          --blyrics-text-color: var(--text-primary);
-          --blyrics-inactive-opacity: 0.2;
+        .preview {
+          --blyrics-ui-text-color: var(--text-primary);
+          --blyrics-lyric-active-color: var(--text-primary);
+          --blyrics-lyric-inactive-color: color-mix(in srgb, var(--text-primary) 20%, transparent);
           --blyrics-font-size: 1.75rem;
         }
 
@@ -224,7 +225,7 @@ export default function LyricsPreview({ content, durationS }: LyricsPreviewProps
         }
 
         .preview-play:hover {
-          background-color: rgba(255, 255, 255, 0.12);
+          background-color: var(--surface-hover);
         }
 
         .preview-play svg {
diff --git a/src/components/MobileNav.tsx b/src/components/MobileNav.tsx
index f5e9a08..1b7293c 100644
--- a/src/components/MobileNav.tsx
+++ b/src/components/MobileNav.tsx
@@ -138,7 +138,7 @@ export default function MobileNav({ currentPath }: Props) {
         .mobile-nav-backdrop {
           position: fixed;
           inset: 0;
-          background-color: rgba(0, 0, 0, 0.6);
+          background-color: var(--scrim);
           z-index: 200;
           animation: backdropFadeIn 0.2s ease-out forwards;
         }
diff --git a/src/components/PageActions.astro b/src/components/PageActions.astro
index ed33581..55b1aa1 100644
--- a/src/components/PageActions.astro
+++ b/src/components/PageActions.astro
@@ -218,7 +218,7 @@ const ITEMS = [
     background-color: var(--bg-secondary);
     border: 1px solid var(--border);
     border-radius: var(--radius-lg);
-    box-shadow: 0 16px 40px -12px rgba(0, 0, 0, 0.6);
+    box-shadow: 0 16px 40px -12px var(--scrim);
     transform-origin: top right;
     animation: page-actions-in 160ms cubic-bezier(0.2, 0, 0, 1);
   }
diff --git a/src/components/Search.tsx b/src/components/Search.tsx
index ff601e0..b943079 100644
--- a/src/components/Search.tsx
+++ b/src/components/Search.tsx
@@ -316,7 +316,7 @@ export default function Search() {
         .search-modal-backdrop {
           position: fixed;
           inset: 0;
-          background-color: rgba(0, 0, 0, 0.6);
+          background-color: var(--scrim);
           display: flex;
           align-items: flex-start;
           justify-content: center;
@@ -337,7 +337,7 @@ export default function Search() {
           background-color: var(--bg-secondary);
           border: 1px solid var(--border);
           border-radius: var(--radius-lg);
-          box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.5);
+          box-shadow: 0 25px 50px -12px var(--shadow-lift);
           overflow: hidden;
           animation: slideIn 0.15s ease-out;
         }
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 7f91b2c..45568e0 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -1,4 +1,6 @@
 ---
+import { THEME_STORAGE_KEY } from '../theme';
+
 interface Props {
   title: string;
   description?: string;
@@ -29,7 +31,8 @@ const pageTitle = Astro.url.pathname === '/' ? 'Better Lyrics API Documentation'
     <meta name="twitter:card" content="summary" />
     <meta name="twitter:title" content={pageTitle} />
     <meta name="twitter:description" content={description} />
-    <meta name="theme-color" content="#0f0e13" />
+    <meta name="theme-color" media="(prefers-color-scheme: light)" content="#faf9fe" />
+    <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0f0e13" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <link rel="preconnect" href="https://api.fontshare.com" crossorigin />
     <link rel="preconnect" href="https://cdn.fontshare.com" crossorigin />
@@ -38,6 +41,10 @@ const pageTitle = Astro.url.pathname === '/' ? 'Better Lyrics API Documentation'
     <link rel="stylesheet" href="https://api.fontshare.com/v2/css?f[]=satoshi@400,500,600,700&display=swap" />
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600&display=swap" />
     <title>{pageTitle}</title>
+    <script is:inline define:vars={{ themeStorageKey: THEME_STORAGE_KEY }}>
+      const savedTheme = localStorage.getItem(themeStorageKey);
+      if (savedTheme === 'light' || savedTheme === 'dark') document.documentElement.dataset.theme = savedTheme;
+    </script>
   </head>
   <body>
     <slot />
diff --git a/src/pages/docs/providers.astro b/src/pages/docs/providers.astro
index 13283e0..b3d5d37 100644
--- a/src/pages/docs/providers.astro
+++ b/src/pages/docs/providers.astro
@@ -189,7 +189,7 @@ import DocsLayout from '../../layouts/DocsLayout.astro';
   }
 
   .badge.default {
-    background-color: rgba(34, 197, 94, 0.1);
+    background-color: var(--tint-success);
     color: var(--success);
   }
 
diff --git a/src/pages/docs/rate-limiting.astro b/src/pages/docs/rate-limiting.astro
index 446f6c1..6a4b6bb 100644
--- a/src/pages/docs/rate-limiting.astro
+++ b/src/pages/docs/rate-limiting.astro
@@ -227,17 +227,17 @@ X-RateLimit-Type: bypass</code></pre>
   }
 
   .tier-badge.normal {
-    background-color: rgba(34, 197, 94, 0.1);
+    background-color: var(--tint-success);
     color: var(--success);
   }
 
   .tier-badge.cached {
-    background-color: rgba(245, 158, 11, 0.1);
+    background-color: var(--tint-warning);
     color: var(--warning);
   }
 
   .tier-badge.exceeded {
-    background-color: rgba(239, 68, 68, 0.1);
+    background-color: var(--tint-error);
     color: var(--error);
   }
 
diff --git a/src/styles/global.css b/src/styles/global.css
index 43cb56e..c22d2dc 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -1,30 +1,133 @@
 /* Better Lyrics API Documentation - Design Tokens (shared with Unison) */
-
 :root {
+  color-scheme: light dark;
+
+  /* each color - light-dark(light, dark) */
+  --bg-primary: light-dark(oklch(98.5% 0.006 294.412), #0f0e13);
+  --bg-secondary: light-dark(oklch(95.5% 0.007 294.412), #141316);
+  --bg-tertiary: light-dark(oklch(0% 0.0105 294.412 / 0.06), rgba(255, 255, 255, 0.06));
+  --text-primary: light-dark(oklch(20% 0.006 286.35), #f5f5f7);
+  --text-secondary: light-dark(oklch(36% 0.006 286.35), rgba(245, 245, 247, 0.72));
+  --text-muted: light-dark(oklch(48% 0.006 286.35), rgba(245, 245, 247, 0.48));
+  --accent: light-dark(oklch(50% 0.22 23.583), #f20c32);
+  --border: light-dark(oklch(0% 0.0105 294.412 / 0.1), rgba(255, 255, 255, 0.1));
+  --border-subtle: light-dark(oklch(0% 0.0105 294.412 / 0.05), rgba(255, 255, 255, 0.05));
+  --border-hover: light-dark(oklch(0% 0.0105 294.412 / 0.18), rgba(255, 255, 255, 0.18));
+  --success: light-dark(oklch(45% 0.15 150), #22c55e);
+  --warning: light-dark(oklch(52% 0.14 70), #f5a623);
+  --error: light-dark(oklch(45% 0.2 330), #ef4444);
+  --shadow-key: light-dark(oklch(0% 0 0 / 0.15), rgba(0, 0, 0, 0.3));
+  --surface-panel: light-dark(oklch(0% 0.0105 294.412 / 0.02), rgba(255, 255, 255, 0.02));
+  --surface-code: light-dark(oklch(96.5% 0.006 294.412), #121115);
+  /* Code: Night Owl Light, Night Owl */
+  --code-text: light-dark(#403f53, #d6deeb);
+  --code-comment: light-dark(#989fb1, #637777);
+  --code-punctuation: light-dark(#994cc3, #c792ea);
+  --code-property: light-dark(#0c969b, #7fdbca);
+  --code-number: light-dark(#aa0982, #f78c6c);
+  --code-string: light-dark(#c96765, #addb67);
+  --code-function: light-dark(#4876d6, #82aaff);
+  --code-keyword: light-dark(#994cc3, #c792ea);
+  --code-highlight: light-dark(#5ca7e4, #ecc48d);
+  --surface-inline-code: light-dark(oklch(0% 0.0105 294.412 / 0.06), rgba(20, 19, 22, 0.6));
+  --surface-hover: light-dark(oklch(0% 0.0105 294.412 / 0.08), rgba(255, 255, 255, 0.12));
+  --glow: light-dark(oklch(100% 0 0 / 0.1), rgba(255, 255, 255, 0.1));
+  --scrollbar-hover: light-dark(oklch(0% 0 0 / 0.28), rgba(255, 255, 255, 0.28));
+  --tint-success: light-dark(oklch(45% 0.15 150 / 0.1), rgba(34, 197, 94, 0.1));
+  --tint-warning: light-dark(oklch(52% 0.14 70 / 0.1), rgba(245, 158, 11, 0.1));
+  --tint-error: light-dark(oklch(45% 0.2 330 / 0.1), rgba(239, 68, 68, 0.1));
+}
+
+:root[data-theme='light'] {
+  color-scheme: light;
+}
+
+:root[data-theme='dark'] {
   color-scheme: dark;
+}
 
-  /* Colors */
+/* Fallback for light-dark() (browsers before 2024) */
+@supports not (color: light-dark(#000, #fff)) {
+@media (prefers-color-scheme: light) {
+:root {
+  color-scheme: light;
+  --bg-primary: oklch(98.254% 0.0056 84.442);
+  --bg-secondary: oklch(95.5% 0.0056 84.442);
+  --bg-tertiary: oklch(0% 0.0056 84.442 / 0.06);
+  --text-primary: oklch(18% 0.0056 84.442);
+  --text-secondary: oklch(34% 0.0056 84.442);
+  --text-muted: oklch(46% 0.0056 84.442);
+  --accent: oklch(50% 0.22 25);
+  --border: oklch(0% 0.0056 84.442 / 0.1);
+  --border-subtle: oklch(0% 0.0056 84.442 / 0.05);
+  --border-hover: oklch(0% 0.0056 84.442 / 0.18);
+  --success: oklch(45% 0.15 150);
+  --warning: oklch(52% 0.14 70);
+  --error: oklch(45% 0.2 330);
+  --shadow-key: oklch(0% 0 0 / 0.15);
+  --surface-panel: oklch(0% 0.0056 84.442 / 0.02);
+  --surface-code: oklch(96.5% 0.006 294.412);
+  --code-text: #403f53;
+  --code-comment: #989fb1;
+  --code-punctuation: #994cc3;
+  --code-property: #0c969b;
+  --code-number: #aa0982;
+  --code-string: #c96765;
+  --code-function: #4876d6;
+  --code-keyword: #994cc3;
+  --code-highlight: #5ca7e4;
+  --surface-inline-code: oklch(0% 0.0056 84.442 / 0.06);
+  --surface-hover: oklch(0% 0 0 / 0.08);
+  --glow: oklch(100% 0 0 / 0.1);
+  --scrollbar-hover: oklch(0% 0 0 / 0.28);
+  --tint-success: oklch(45% 0.15 150 / 0.1);
+  --tint-warning: oklch(52% 0.14 70 / 0.1);
+  --tint-error: oklch(45% 0.2 330 / 0.1);
+}
+}
+@media (prefers-color-scheme: dark) {
+:root {
+  color-scheme: dark;
   --bg-primary: #0f0e13;
   --bg-secondary: #141316;
   --bg-tertiary: rgba(255, 255, 255, 0.06);
-
   --text-primary: #f5f5f7;
   --text-secondary: rgba(245, 245, 247, 0.72);
   --text-muted: rgba(245, 245, 247, 0.48);
-
   --accent: #f20c32;
-
   --border: rgba(255, 255, 255, 0.1);
   --border-subtle: rgba(255, 255, 255, 0.05);
   --border-hover: rgba(255, 255, 255, 0.18);
-
   --success: #22c55e;
   --warning: #f5a623;
   --error: #ef4444;
-
-  --code-text: #d6deeb;
+  --shadow-key: rgba(0, 0, 0, 0.3);
   --surface-panel: rgba(255, 255, 255, 0.02);
-  --surface-code: rgba(20, 19, 22, 0.5);
+  --surface-code: #121115;
+  --code-text: #d6deeb;
+  --code-comment: #637777;
+  --code-punctuation: #c792ea;
+  --code-property: #7fdbca;
+  --code-number: #f78c6c;
+  --code-string: #addb67;
+  --code-function: #82aaff;
+  --code-keyword: #c792ea;
+  --code-highlight: #ecc48d;
+  --surface-inline-code: rgba(20, 19, 22, 0.6);
+  --surface-hover: rgba(255, 255, 255, 0.12);
+  --glow: rgba(255, 255, 255, 0.1);
+  --scrollbar-hover: rgba(255, 255, 255, 0.28);
+  --tint-success: rgba(34, 197, 94, 0.1);
+  --tint-warning: rgba(245, 158, 11, 0.1);
+  --tint-error: rgba(239, 68, 68, 0.1);
+}
+}
+}
+
+:root{
+  /* Overlays, same in both themes) */
+  --scrim: oklch(0% 0 0 / 0.6);
+  --shadow-lift: oklch(0% 0 0 / 0.5);
 
   /* Typography */
   --font-sans: 'Satoshi', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
@@ -130,7 +233,7 @@ code {
   font-family: var(--font-mono);
   font-size: 0.85em;
   color: var(--text-primary);
-  background-color: rgba(20, 19, 22, 0.6);
+  background-color: var(--surface-inline-code);
   padding: 0.125rem 0.25rem;
   border-radius: var(--radius-sm);
 }
@@ -264,7 +367,7 @@ kbd {
   padding: 0 0.25rem;
   border-radius: var(--radius-sm);
   background-color: color-mix(in srgb, currentColor 10%, transparent);
-  box-shadow: 0 2px 0 0 rgba(0, 0, 0, 0.3);
+  box-shadow: 0 2px 0 0 var(--shadow-key);
   font-family: var(--font-sans);
   font-size: 10px;
   font-weight: 500;
@@ -362,7 +465,7 @@ kbd svg {
 }
 
 ::-webkit-scrollbar-thumb:hover {
-  background: rgba(255, 255, 255, 0.28);
+  background: var(--scrollbar-hover);
 }
 
 ::selection {
@@ -370,7 +473,7 @@ kbd svg {
   color: var(--text-primary);
 }
 
-/* Prism tokens, night owl palette to match Unison */
+/* Prism tokens, Night Owl palette colors */
 code[class*="language-"] {
   font-family: var(--font-mono);
   text-shadow: none;
@@ -389,12 +492,12 @@ code[class*="language-"] {
 .token.prolog,
 .token.doctype,
 .token.cdata {
-  color: #637777;
+  color: var(--code-comment);
   font-style: italic;
 }
 
 .token.punctuation {
-  color: #c792ea;
+  color: var(--code-punctuation);
 }
 
 .token.property,
@@ -402,12 +505,12 @@ code[class*="language-"] {
 .token.constant,
 .token.symbol,
 .token.deleted {
-  color: #7fdbca;
+  color: var(--code-property);
 }
 
 .token.boolean,
 .token.number {
-  color: #f78c6c;
+  color: var(--code-number);
 }
 
 .token.selector,
@@ -416,28 +519,28 @@ code[class*="language-"] {
 .token.char,
 .token.builtin,
 .token.inserted {
-  color: #addb67;
+  color: var(--code-string);
 }
 
 .token.operator,
 .token.entity,
 .token.url,
 .token.variable {
-  color: #c792ea;
+  color: var(--code-punctuation);
 }
 
 .token.atrule,
 .token.attr-value,
 .token.function,
 .token.class-name {
-  color: #82aaff;
+  color: var(--code-function);
 }
 
 .token.keyword {
-  color: #c792ea;
+  color: var(--code-keyword);
 }
 
 .token.regex,
 .token.important {
-  color: #ecc48d;
+  color: var(--code-highlight);
 }
diff --git a/src/theme.ts b/src/theme.ts
new file mode 100644
index 0000000..a2a350c
--- /dev/null
+++ b/src/theme.ts
@@ -0,0 +1,3 @@
+export const THEME_STORAGE_KEY = 'blyrics-docs:theme';
+
+export type Theme = 'light' | 'dark';