boidushya · Oct 21, 2026 · Oct 19, 2026 · Oct 21, 2026 · Oct 21, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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);
   }