diff --git a/docs/src/components/AttributeCard.astro b/docs/src/components/AttributeCard.astro
index 640db815..0ea6f2b6 100644
--- a/docs/src/components/AttributeCard.astro
+++ b/docs/src/components/AttributeCard.astro
@@ -91,7 +91,7 @@ const rawJson = JSON.stringify(attribute, null, 2);
     )}
     
     {isDeprecated && (
-      <div class="mt-3 p-3 bg-error/10 rounded-md border-l-[3px] border-error">
+      <div class="mt-3 p-3 bg-error-soft rounded-md border-l-[3px] border-error">
         {attribute.deprecation?.replacement ? (
           <p class="text-sm m-0">Use <code class="text-accent">{attribute.deprecation.replacement}</code> instead.</p>
         ) : (
diff --git a/docs/src/components/PiiBadge.astro b/docs/src/components/PiiBadge.astro
index bb6a2f94..98332e3e 100644
--- a/docs/src/components/PiiBadge.astro
+++ b/docs/src/components/PiiBadge.astro
@@ -13,9 +13,9 @@ const labels = {
 };
 
 const colorClasses = {
-  true: 'bg-pii-true/15 text-pii-true',
-  maybe: 'bg-pii-maybe/15 text-pii-maybe',
-  false: 'bg-pii-false/15 text-pii-false',
+  true: 'bg-pii-true-soft text-pii-true',
+  maybe: 'bg-pii-maybe-soft text-pii-maybe',
+  false: 'bg-pii-false-soft text-pii-false',
 };
 ---
 
diff --git a/docs/src/components/SearchModal.svelte b/docs/src/components/SearchModal.svelte
index 94a638f9..fc3dc5bc 100644
--- a/docs/src/components/SearchModal.svelte
+++ b/docs/src/components/SearchModal.svelte
@@ -323,7 +323,7 @@ function highlightMatch(key: string, searchQuery: string): { before: string; mat
             {#each attributeResults as attr, index}
               {@const highlighted = highlightMatch(attr.key, query)}
               <button
-                class="flex flex-col gap-1 w-full px-4 py-3 bg-transparent border-none border-b border-border last:border-b-0 text-left cursor-pointer transition-all duration-fast border-l-2 {index === selectedIndex ? 'bg-accent/15 border-l-accent selected shadow-[inset_0_0_0_1px_rgba(149,128,255,0.2)]' : 'border-l-transparent hover:bg-bg-hover hover:border-l-border-light'}"
+                class="flex flex-col gap-1 w-full px-4 py-3 bg-transparent border-none border-b border-border last:border-b-0 text-left cursor-pointer transition-all duration-fast border-l-2 {index === selectedIndex ? 'bg-accent-soft border-l-accent selected shadow-[inset_0_0_0_1px_var(--color-accent-soft)]' : 'border-l-transparent hover:bg-bg-hover hover:border-l-border-light'}"
                 onclick={() => navigateToAttribute(attr)}
                 onmouseenter={() => handleMouseEnter(index)}
                 onmousemove={handleMouseMove}
@@ -340,7 +340,7 @@ function highlightMatch(key: string, searchQuery: string): { before: string; mat
                     <span class="text-xs px-2 py-0.5 rounded-sm font-sans bg-bg-elevated text-text-muted">{attr.type}</span>
                     <span class="text-xs px-2 py-0.5 rounded-sm font-sans bg-bg-elevated text-text-secondary">{attr.category}</span>
                     {#if attr.deprecated}
-                      <span class="text-xs px-2 py-0.5 rounded-sm font-sans bg-error/15 text-error">deprecated</span>
+                      <span class="text-xs px-2 py-0.5 rounded-sm font-sans bg-error-soft text-error">deprecated</span>
                     {/if}
                   </div>
                 </div>
@@ -359,7 +359,7 @@ function highlightMatch(key: string, searchQuery: string): { before: string; mat
             {#each pageResults as result, index}
               {@const actualIndex = attributeResults.length + index}
               <button
-                class="flex flex-col gap-1 w-full px-4 py-3 bg-transparent border-none border-b border-border last:border-b-0 text-left cursor-pointer transition-all duration-fast border-l-2 {actualIndex === selectedIndex ? 'bg-accent/15 border-l-accent selected shadow-[inset_0_0_0_1px_rgba(149,128,255,0.2)]' : 'border-l-transparent hover:bg-bg-hover hover:border-l-border-light'}"
+                class="flex flex-col gap-1 w-full px-4 py-3 bg-transparent border-none border-b border-border last:border-b-0 text-left cursor-pointer transition-all duration-fast border-l-2 {actualIndex === selectedIndex ? 'bg-accent-soft border-l-accent selected shadow-[inset_0_0_0_1px_var(--color-accent-soft)]' : 'border-l-transparent hover:bg-bg-hover hover:border-l-border-light'}"
                 onclick={() => navigateToResult(result)}
                 onmouseenter={() => handleMouseEnter(actualIndex)}
                 onmousemove={handleMouseMove}
diff --git a/docs/src/components/ThemeToggle.svelte b/docs/src/components/ThemeToggle.svelte
new file mode 100644
index 00000000..a91b160b
--- /dev/null
+++ b/docs/src/components/ThemeToggle.svelte
@@ -0,0 +1,60 @@
+<script lang="ts">
+let isDark = $state(false);
+
+// Initialize theme state from document
+$effect(() => {
+  isDark = document.documentElement.classList.contains('dark');
+});
+
+// Listen for system preference changes
+$effect(() => {
+  const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+
+  function handleChange(e: MediaQueryListEvent) {
+    // Only apply system preference if user hasn't set a manual preference
+    if (!localStorage.getItem('theme')) {
+      isDark = e.matches;
+      document.documentElement.classList.toggle('dark', isDark);
+    }
+  }
+
+  mediaQuery.addEventListener('change', handleChange);
+
+  return () => {
+    mediaQuery.removeEventListener('change', handleChange);
+  };
+});
+
+function toggleTheme() {
+  isDark = !isDark;
+  document.documentElement.classList.toggle('dark', isDark);
+  localStorage.setItem('theme', isDark ? 'dark' : 'light');
+}
+</script>
+
+<button
+  onclick={toggleTheme}
+  class="flex items-center justify-center w-9 h-9 bg-bg-elevated border border-border rounded-md text-text-secondary cursor-pointer transition-all duration-fast hover:border-border-light hover:text-text-primary"
+  aria-label={isDark ? 'Switch to light mode' : 'Switch to dark mode'}
+  title={isDark ? 'Switch to light mode' : 'Switch to dark mode'}
+>
+  {#if isDark}
+    <!-- Sun icon (shown in dark mode to switch to light) -->
+    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <circle cx="12" cy="12" r="5"/>
+      <line x1="12" y1="1" x2="12" y2="3"/>
+      <line x1="12" y1="21" x2="12" y2="23"/>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/>
+      <line x1="1" y1="12" x2="3" y2="12"/>
+      <line x1="21" y1="12" x2="23" y2="12"/>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/>
+    </svg>
+  {:else}
+    <!-- Moon icon (shown in light mode to switch to dark) -->
+    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+    </svg>
+  {/if}
+</button>
diff --git a/docs/src/layouts/BaseLayout.astro b/docs/src/layouts/BaseLayout.astro
index c0ae994f..ea92c313 100644
--- a/docs/src/layouts/BaseLayout.astro
+++ b/docs/src/layouts/BaseLayout.astro
@@ -1,6 +1,7 @@
 ---
 import '../styles/global.css';
 import SearchModal from '../components/SearchModal.svelte';
+import ThemeToggle from '../components/ThemeToggle.svelte';
 import SearchIcon from '../components/icons/SearchIcon.astro';
 import ExternalLinkIcon from '../components/icons/ExternalLinkIcon.astro';
 
@@ -25,6 +26,14 @@ const currentPath = Astro.url.pathname;
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300..700;1,9..40,300..700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
     <title>{title} | Sentry Conventions</title>
+    <script is:inline>
+      // Initialize theme before render to prevent flash
+      const theme = localStorage.getItem('theme');
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+      if (theme === 'dark' || (!theme && prefersDark)) {
+        document.documentElement.classList.add('dark');
+      }
+    </script>
   </head>
   <body>
     <div class="flex flex-col min-h-screen">
@@ -80,17 +89,20 @@ const currentPath = Astro.url.pathname;
             </a>
           </nav>
           
-          <button
-            class="flex items-center gap-3 px-3 py-2 bg-bg-elevated border border-border rounded-md text-text-muted text-sm cursor-pointer transition-fast hover:border-border-light hover:text-text-secondary"
-            id="search-trigger"
-            aria-label="Search"
-          >
-            <SearchIcon />
-            <span class="hidden md:flex gap-1">
-              <kbd class="inline-flex items-center justify-center min-w-[20px] h-5 px-1 bg-bg-secondary border border-border rounded-sm font-sans text-xs font-medium">⌘</kbd>
-              <kbd class="inline-flex items-center justify-center min-w-[20px] h-5 px-1 bg-bg-secondary border border-border rounded-sm font-sans text-xs font-medium">K</kbd>
-            </span>
-          </button>
+          <div class="flex items-center gap-2">
+            <button
+              class="flex items-center gap-3 px-3 py-2 bg-bg-elevated border border-border rounded-md text-text-muted text-sm cursor-pointer transition-fast hover:border-border-light hover:text-text-secondary"
+              id="search-trigger"
+              aria-label="Search"
+            >
+              <SearchIcon />
+              <span class="hidden md:flex gap-1">
+                <kbd class="inline-flex items-center justify-center min-w-[20px] h-5 px-1 bg-bg-secondary border border-border rounded-sm font-sans text-xs font-medium">⌘</kbd>
+                <kbd class="inline-flex items-center justify-center min-w-[20px] h-5 px-1 bg-bg-secondary border border-border rounded-sm font-sans text-xs font-medium">K</kbd>
+              </span>
+            </button>
+            <ThemeToggle client:load />
+          </div>
         </div>
       </header>
       
diff --git a/docs/src/pages/names/index.astro b/docs/src/pages/names/index.astro
index dcd62db1..4b5de2ef 100644
--- a/docs/src/pages/names/index.astro
+++ b/docs/src/pages/names/index.astro
@@ -76,7 +76,7 @@ const totalOperations = allNames.reduce((acc, name) => acc + name.data.operation
               <p class="text-sm text-text-secondary mb-4">{op.brief}</p>
               
               {!op.is_in_otel && (
-                <div class="flex items-start gap-2 p-3 rounded-md text-sm mb-4 bg-warning/10 border border-warning/30 text-warning">
+                <div class="flex items-start gap-2 p-3 rounded-md text-sm mb-4 bg-warning-soft border border-warning text-warning">
                   <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="flex-shrink-0 mt-0.5">
                     <path d="M12 9v2m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"/>
                   </svg>
@@ -85,7 +85,7 @@ const totalOperations = allNames.reduce((acc, name) => acc + name.data.operation
               )}
               
               {op.is_in_otel && op.otel_notes && (
-                <div class="flex items-start gap-2 p-3 rounded-md text-sm mb-4 bg-info/10 border border-info/30 text-info">
+                <div class="flex items-start gap-2 p-3 rounded-md text-sm mb-4 bg-info-soft border border-info text-info">
                   <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="flex-shrink-0 mt-0.5">
                     <circle cx="12" cy="12" r="10"/>
                     <path d="M12 16v-4M12 8h.01"/>
diff --git a/docs/src/styles/global.css b/docs/src/styles/global.css
index ee9df5d8..a9742d7b 100644
--- a/docs/src/styles/global.css
+++ b/docs/src/styles/global.css
@@ -1,3 +1,80 @@
+/* Theme CSS Custom Properties */
+:root {
+  /* Light theme (default) */
+  --color-bg-primary: #ffffff;
+  --color-bg-secondary: #f8f9fa;
+  --color-bg-elevated: #f0f1f3;
+  --color-bg-hover: #e8e9eb;
+
+  --color-text-primary: #1a1d23;
+  --color-text-secondary: #4a5568;
+  --color-text-muted: #718096;
+
+  --color-accent: #7c3aed;
+  --color-accent-hover: #6d28d9;
+  --color-accent-soft: rgba(124, 58, 237, 0.12);
+
+  --color-border: #e2e8f0;
+  --color-border-light: #cbd5e1;
+
+  --color-success: #22c55e;
+  --color-success-soft: rgba(34, 197, 94, 0.15);
+  --color-warning: #eab308;
+  --color-warning-soft: rgba(234, 179, 8, 0.15);
+  --color-error: #ef4444;
+  --color-error-soft: rgba(239, 68, 68, 0.15);
+  --color-info: #3b82f6;
+  --color-info-soft: rgba(59, 130, 246, 0.15);
+
+  --color-code-string: #16a34a;
+  --color-code-number: #ea580c;
+
+  --color-pii-true: #ef4444;
+  --color-pii-true-soft: rgba(239, 68, 68, 0.15);
+  --color-pii-maybe: #eab308;
+  --color-pii-maybe-soft: rgba(234, 179, 8, 0.15);
+  --color-pii-false: #22c55e;
+  --color-pii-false-soft: rgba(34, 197, 94, 0.15);
+}
+
+.dark {
+  /* Dark theme */
+  --color-bg-primary: #111318;
+  --color-bg-secondary: #181b21;
+  --color-bg-elevated: #1f2329;
+  --color-bg-hover: #262b33;
+
+  --color-text-primary: #d4d7db;
+  --color-text-secondary: #8b919a;
+  --color-text-muted: #5c6370;
+
+  --color-accent: #9580ff;
+  --color-accent-hover: #a899ff;
+  --color-accent-soft: rgba(149, 128, 255, 0.12);
+
+  --color-border: #282d36;
+  --color-border-light: #343a45;
+
+  --color-success: #50a060;
+  --color-success-soft: rgba(80, 160, 96, 0.15);
+  --color-warning: #d4a72c;
+  --color-warning-soft: rgba(212, 167, 44, 0.15);
+  --color-error: #c25450;
+  --color-error-soft: rgba(194, 84, 80, 0.15);
+  --color-info: #5c9fd4;
+  --color-info-soft: rgba(92, 159, 212, 0.15);
+
+  --color-code-string: #98c379;
+  --color-code-number: #d19a66;
+
+  --color-pii-true: #c25450;
+  --color-pii-true-soft: rgba(194, 84, 80, 0.15);
+  --color-pii-maybe: #d4a72c;
+  --color-pii-maybe-soft: rgba(212, 167, 44, 0.15);
+  --color-pii-false: #50a060;
+  --color-pii-false-soft: rgba(80, 160, 96, 0.15);
+}
+
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
@@ -127,15 +204,15 @@
   }
 
   .badge-deprecated {
-    @apply bg-error/15 text-error;
+    @apply bg-error-soft text-error;
   }
 
   .badge-otel {
-    @apply bg-info/15 text-info;
+    @apply bg-info-soft text-info;
   }
 
   .badge-dynamic {
-    @apply bg-warning/15 text-warning;
+    @apply bg-warning-soft text-warning;
   }
 
   .badge-type {
diff --git a/docs/tailwind.config.mjs b/docs/tailwind.config.mjs
index 2bb4e52e..c581dba2 100644
--- a/docs/tailwind.config.mjs
+++ b/docs/tailwind.config.mjs
@@ -5,44 +5,59 @@ export default {
     extend: {
       colors: {
         // Background colors
-        'bg-primary': '#111318',
-        'bg-secondary': '#181b21',
-        'bg-elevated': '#1f2329',
-        'bg-hover': '#262b33',
+        'bg-primary': 'var(--color-bg-primary)',
+        'bg-secondary': 'var(--color-bg-secondary)',
+        'bg-elevated': 'var(--color-bg-elevated)',
+        'bg-hover': 'var(--color-bg-hover)',
 
         // Text colors
-        'text-primary': '#d4d7db',
-        'text-secondary': '#8b919a',
-        'text-muted': '#5c6370',
+        'text-primary': 'var(--color-text-primary)',
+        'text-secondary': 'var(--color-text-secondary)',
+        'text-muted': 'var(--color-text-muted)',
 
         // Accent
         accent: {
-          DEFAULT: '#9580ff',
-          hover: '#a899ff',
-          soft: 'rgba(149, 128, 255, 0.12)',
+          DEFAULT: 'var(--color-accent)',
+          hover: 'var(--color-accent-hover)',
+          soft: 'var(--color-accent-soft)',
         },
 
         // Border colors
         border: {
-          DEFAULT: '#282d36',
-          light: '#343a45',
+          DEFAULT: 'var(--color-border)',
+          light: 'var(--color-border-light)',
         },
 
         // Semantic colors
-        success: '#50a060',
-        warning: '#d4a72c',
-        error: '#c25450',
-        info: '#5c9fd4',
+        success: {
+          DEFAULT: 'var(--color-success)',
+          soft: 'var(--color-success-soft)',
+        },
+        warning: {
+          DEFAULT: 'var(--color-warning)',
+          soft: 'var(--color-warning-soft)',
+        },
+        error: {
+          DEFAULT: 'var(--color-error)',
+          soft: 'var(--color-error-soft)',
+        },
+        info: {
+          DEFAULT: 'var(--color-info)',
+          soft: 'var(--color-info-soft)',
+        },
 
         // Code syntax highlighting
-        'code-string': '#98c379',
-        'code-number': '#d19a66',
+        'code-string': 'var(--color-code-string)',
+        'code-number': 'var(--color-code-number)',
 
         // PII indicator colors
         pii: {
-          true: '#c25450',
-          maybe: '#d4a72c',
-          false: '#50a060',
+          true: 'var(--color-pii-true)',
+          'true-soft': 'var(--color-pii-true-soft)',
+          maybe: 'var(--color-pii-maybe)',
+          'maybe-soft': 'var(--color-pii-maybe-soft)',
+          false: 'var(--color-pii-false)',
+          'false-soft': 'var(--color-pii-false-soft)',
         },
       },
       fontFamily: {