From 55e61b22b147e83ac13a33f6e41a2ed7bdc4285e Mon Sep 17 00:00:00 2001
From: ramansgdeep <ramansg.deep@gmail.com>
Date: Mon, 19 Oct 2026 15:46:40 +0530
Subject: [PATCH 1/3] Add light theme, keep code dark

---
 src/components/BraccatoExample.tsx |   4 +-
 src/components/CodeExamples.tsx    |   2 +-
 src/components/CodeTabs.astro      |   2 +-
 src/components/Header.astro        |   2 +-
 src/components/LyricsPreview.tsx   |   6 +-
 src/components/MobileNav.tsx       |   2 +-
 src/components/PageActions.astro   |   2 +-
 src/components/Playground.tsx      |   4 +-
 src/components/Search.tsx          |   4 +-
 src/layouts/BaseLayout.astro       |   3 +-
 src/pages/docs/providers.astro     |   2 +-
 src/pages/docs/rate-limiting.astro |   6 +-
 src/styles/global.css              | 161 +++++++++++++++++++++++++----
 13 files changed, 160 insertions(+), 40 deletions(-)

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/CodeExamples.tsx b/src/components/CodeExamples.tsx
index 57c362b..b22ff4e 100644
--- a/src/components/CodeExamples.tsx
+++ b/src/components/CodeExamples.tsx
@@ -222,7 +222,7 @@ client.newCall(request).execute().use { response ->
   };
 
   return (
-    <div className="code-examples">
+    <div className="code-examples theme-dark">
       <div className="tabs-header">
         <SegmentedControl
           variant="underline"
diff --git a/src/components/CodeTabs.astro b/src/components/CodeTabs.astro
index d3b9640..a7ce417 100644
--- a/src/components/CodeTabs.astro
+++ b/src/components/CodeTabs.astro
@@ -8,7 +8,7 @@ interface Props {
 const { tabs } = Astro.props;
 ---
 
-<div class="code-tabs" data-code-tabs>
+<div class="code-tabs theme-dark" data-code-tabs>
   <div class="code-tabs-header" role="tablist">
     <span class="code-tabs-indicator" aria-hidden="true"></span>
     {tabs.map((tab, i) => (
diff --git a/src/components/Header.astro b/src/components/Header.astro
index 574a7ec..20a0633 100644
--- a/src/components/Header.astro
+++ b/src/components/Header.astro
@@ -30,7 +30,7 @@ const currentPath = currentPathOf(Astro.url);
     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);
   }
diff --git a/src/components/LyricsPreview.tsx b/src/components/LyricsPreview.tsx
index 7a47bba..63c2c7c 100644
--- a/src/components/LyricsPreview.tsx
+++ b/src/components/LyricsPreview.tsx
@@ -128,7 +128,7 @@ export default function LyricsPreview({ content, durationS }: LyricsPreviewProps
   }
 
   return (
-    <div className="preview">
+    <div className="preview theme-dark">
       <braccato-lyrics ref={elementRef} />
 
       <div className="preview-transport">
@@ -172,7 +172,7 @@ export default function LyricsPreview({ content, durationS }: LyricsPreviewProps
       </div>
 
       <style>{`
-        :root {
+        .preview {
           --blyrics-text-color: var(--text-primary);
           --blyrics-inactive-opacity: 0.2;
           --blyrics-font-size: 1.75rem;
@@ -224,7 +224,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/Playground.tsx b/src/components/Playground.tsx
index a4677d7..9817476 100644
--- a/src/components/Playground.tsx
+++ b/src/components/Playground.tsx
@@ -334,7 +334,7 @@ export default function Playground() {
       </form>
 
       {hasQuery && (
-        <div className="request-bar">
+        <div className="request-bar theme-dark">
           <span className="request-method">GET</span>
           <code className="request-url">{apiUrl}</code>
           {response && (
@@ -367,7 +367,7 @@ export default function Playground() {
       )}
 
       {response && (
-        <div className="output">
+        <div className="output theme-dark">
           <div className="output-tabs">
             <SegmentedControl variant="underline" ariaLabel="Output" options={outputTabs} value={activeTab} onChange={setTab} />
           </div>
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..7569c0e 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -29,7 +29,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 />
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..7fff7f3 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -1,30 +1,137 @@
 /* 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(#121115, #121115);
+  --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));
+}
+
+/* Fallback for light-dark() (browsers before 2024). Suggestion is to remove. */
+@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: #121115;
+  --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;
-
-  /* Colors */
   --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;
+  --shadow-key: rgba(0, 0, 0, 0.3);
+  --surface-panel: rgba(255, 255, 255, 0.02);
+  --surface-code: #121115;
+  --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);
+}
+}
 
+/* Code elements outside pre need theme-dark to be dark in light mode */
+.theme-dark, pre {
+  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;
+  --shadow-key: rgba(0, 0, 0, 0.3);
+  --surface-panel: rgba(255, 255, 255, 0.02);
+  --surface-code: #121115;
+  --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{
+  /* Code (Night Owl palette, same in both themes) */
   --code-text: #d6deeb;
-  --surface-panel: rgba(255, 255, 255, 0.02);
-  --surface-code: rgba(20, 19, 22, 0.5);
+  --ink-on-dark: #f5f5f7;
+  --code-comment: #637777;
+  --code-punctuation: #c792ea;
+  --code-property: #7fdbca;
+  --code-number: #f78c6c;
+  --code-string: #addb67;
+  --code-function: #82aaff;
+  --code-keyword: #c792ea;
+  --code-highlight: #ecc48d;
+
+  /* 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 +237,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 +371,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 +469,7 @@ kbd svg {
 }
 
 ::-webkit-scrollbar-thumb:hover {
-  background: rgba(255, 255, 255, 0.28);
+  background: var(--scrollbar-hover);
 }
 
 ::selection {
@@ -370,7 +477,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 +496,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 +509,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 +523,40 @@ 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);
+}
+
+
+/* Code elements outside pre need theme-dark to stay dark in light mode */
+.theme-dark, pre {
+  color-scheme: dark;
+}
+
+/* Fixed color: var(--text-primary) resolves to the light-theme value inside ::selection */
+pre::selection, pre *::selection,
+.theme-dark::selection, .theme-dark *::selection {
+  color: var(--ink-on-dark);
 }

From 7548a0067dd946bf53662c61e4c83427fd82ec7d Mon Sep 17 00:00:00 2001
From: Boidushya <boidushyabhattacharya@gmail.com>
Date: Wed, 21 Oct 2026 22:48:49 +0530
Subject: [PATCH 2/3] feat: add theme toggle and theme-aware code blocks

---
 src/components/CodeExamples.tsx  |  2 +-
 src/components/CodeTabs.astro    |  2 +-
 src/components/Header.astro      | 78 +++++++++++++++++++++++++++
 src/components/LyricsPreview.tsx |  7 +--
 src/components/Playground.tsx    |  4 +-
 src/layouts/BaseLayout.astro     |  6 +++
 src/styles/global.css            | 92 +++++++++++++-------------------
 src/theme.ts                     |  3 ++
 8 files changed, 133 insertions(+), 61 deletions(-)
 create mode 100644 src/theme.ts

diff --git a/src/components/CodeExamples.tsx b/src/components/CodeExamples.tsx
index b22ff4e..57c362b 100644
--- a/src/components/CodeExamples.tsx
+++ b/src/components/CodeExamples.tsx
@@ -222,7 +222,7 @@ client.newCall(request).execute().use { response ->
   };
 
   return (
-    <div className="code-examples theme-dark">
+    <div className="code-examples">
       <div className="tabs-header">
         <SegmentedControl
           variant="underline"
diff --git a/src/components/CodeTabs.astro b/src/components/CodeTabs.astro
index a7ce417..d3b9640 100644
--- a/src/components/CodeTabs.astro
+++ b/src/components/CodeTabs.astro
@@ -8,7 +8,7 @@ interface Props {
 const { tabs } = Astro.props;
 ---
 
-<div class="code-tabs theme-dark" data-code-tabs>
+<div class="code-tabs" data-code-tabs>
   <div class="code-tabs-header" role="tablist">
     <span class="code-tabs-indicator" aria-hidden="true"></span>
     {tabs.map((tab, i) => (
diff --git a/src/components/Header.astro b/src/components/Header.astro
index 20a0633..d562e33 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,9 +26,47 @@ 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();
+</script>
+
 <style>
   .header {
     position: sticky;
@@ -88,9 +131,44 @@ 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 svg {
+    width: 0.875rem;
+    height: 0.875rem;
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 1.5;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
+
   @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 63c2c7c..d813c8a 100644
--- a/src/components/LyricsPreview.tsx
+++ b/src/components/LyricsPreview.tsx
@@ -128,7 +128,7 @@ export default function LyricsPreview({ content, durationS }: LyricsPreviewProps
   }
 
   return (
-    <div className="preview theme-dark">
+    <div className="preview">
       <braccato-lyrics ref={elementRef} />
 
       <div className="preview-transport">
@@ -173,8 +173,9 @@ export default function LyricsPreview({ content, durationS }: LyricsPreviewProps
 
       <style>{`
         .preview {
-          --blyrics-text-color: var(--text-primary);
-          --blyrics-inactive-opacity: 0.2;
+          --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;
         }
 
diff --git a/src/components/Playground.tsx b/src/components/Playground.tsx
index 9817476..a4677d7 100644
--- a/src/components/Playground.tsx
+++ b/src/components/Playground.tsx
@@ -334,7 +334,7 @@ export default function Playground() {
       </form>
 
       {hasQuery && (
-        <div className="request-bar theme-dark">
+        <div className="request-bar">
           <span className="request-method">GET</span>
           <code className="request-url">{apiUrl}</code>
           {response && (
@@ -367,7 +367,7 @@ export default function Playground() {
       )}
 
       {response && (
-        <div className="output theme-dark">
+        <div className="output">
           <div className="output-tabs">
             <SegmentedControl variant="underline" ariaLabel="Output" options={outputTabs} value={activeTab} onChange={setTab} />
           </div>
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 7569c0e..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;
@@ -39,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/styles/global.css b/src/styles/global.css
index 7fff7f3..a67c82a 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -18,7 +18,17 @@
   --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(#121115, #121115);
+  --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));
@@ -28,6 +38,14 @@
   --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;
+}
+
 /* Fallback for light-dark() (browsers before 2024). Suggestion is to remove. */
 @supports not (color: light-dark(#000, #fff)) {
 @media (prefers-color-scheme: light) {
@@ -48,7 +66,16 @@
   --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: #121115;
+  --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);
@@ -77,6 +104,15 @@
   --shadow-key: rgba(0, 0, 0, 0.3);
   --surface-panel: rgba(255, 255, 255, 0.02);
   --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);
@@ -86,49 +122,9 @@
   --tint-error: rgba(239, 68, 68, 0.1);
 }
 }
-
-/* Code elements outside pre need theme-dark to be dark in light mode */
-.theme-dark, pre {
-  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;
-  --shadow-key: rgba(0, 0, 0, 0.3);
-  --surface-panel: rgba(255, 255, 255, 0.02);
-  --surface-code: #121115;
-  --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{
-  /* Code (Night Owl palette, same in both themes) */
-  --code-text: #d6deeb;
-  --ink-on-dark: #f5f5f7;
-  --code-comment: #637777;
-  --code-punctuation: #c792ea;
-  --code-property: #7fdbca;
-  --code-number: #f78c6c;
-  --code-string: #addb67;
-  --code-function: #82aaff;
-  --code-keyword: #c792ea;
-  --code-highlight: #ecc48d;
-
   /* Overlays, same in both themes) */
   --scrim: oklch(0% 0 0 / 0.6);
   --shadow-lift: oklch(0% 0 0 / 0.5);
@@ -548,15 +544,3 @@ code[class*="language-"] {
 .token.important {
   color: var(--code-highlight);
 }
-
-
-/* Code elements outside pre need theme-dark to stay dark in light mode */
-.theme-dark, pre {
-  color-scheme: dark;
-}
-
-/* Fixed color: var(--text-primary) resolves to the light-theme value inside ::selection */
-pre::selection, pre *::selection,
-.theme-dark::selection, .theme-dark *::selection {
-  color: var(--ink-on-dark);
-}
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';

From 2038b82bda5844268fbec8dd508696a56b566ad3 Mon Sep 17 00:00:00 2001
From: Boidushya <boidushyabhattacharya@gmail.com>
Date: Wed, 21 Oct 2026 23:01:05 +0530
Subject: [PATCH 3/3] fix: hide theme toggle on older browsers and skip icon
 animation on load

---
 src/components/Header.astro | 12 ++++++++++++
 src/styles/global.css       |  2 +-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/components/Header.astro b/src/components/Header.astro
index d562e33..024ba8a 100644
--- a/src/components/Header.astro
+++ b/src/components/Header.astro
@@ -65,6 +65,8 @@ const currentPath = currentPathOf(Astro.url);
 
   systemDark.addEventListener('change', render);
   render();
+  icon?.getBoundingClientRect();
+  icon?.setAttribute('data-ready', '');
 </script>
 
 <style>
@@ -152,6 +154,10 @@ const currentPath = currentPathOf(Astro.url);
     background-color: var(--bg-tertiary);
   }
 
+  .theme-toggle .morph:not([data-ready]) > * {
+    transition: none;
+  }
+
   .theme-toggle svg {
     width: 0.875rem;
     height: 0.875rem;
@@ -162,6 +168,12 @@ const currentPath = currentPathOf(Astro.url);
     stroke-linejoin: round;
   }
 
+  @supports not (color: light-dark(#000, #fff)) {
+    .theme-toggle {
+      display: none;
+    }
+  }
+
   @media (max-width: 1024px) {
     .nav {
       display: none;
diff --git a/src/styles/global.css b/src/styles/global.css
index a67c82a..c22d2dc 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -46,7 +46,7 @@
   color-scheme: dark;
 }
 
-/* Fallback for light-dark() (browsers before 2024). Suggestion is to remove. */
+/* Fallback for light-dark() (browsers before 2024) */
 @supports not (color: light-dark(#000, #fff)) {
 @media (prefers-color-scheme: light) {
 :root {