diff --git a/app/src/WebsiteApp.tsx b/app/src/WebsiteApp.tsx
index 090624a77..5b6af9d1a 100644
--- a/app/src/WebsiteApp.tsx
+++ b/app/src/WebsiteApp.tsx
@@ -9,6 +9,7 @@ import { Provider } from 'react-redux';
 import DevTools from '@/components/DevTools';
 import { TooltipProvider } from '@/components/ui/tooltip';
 import { AppProvider } from './contexts/AppContext';
+import { ThemeProvider } from './contexts/ThemeContext';
 import { store } from './store';
 import { cacheMonitor } from './utils/cacheMonitor';
 import { WebsiteRouter } from './WebsiteRouter';
@@ -26,14 +27,16 @@ cacheMonitor.init(queryClient);
 export default function WebsiteApp() {
   return (
     <AppProvider mode="website">
-      <Provider store={store}>
-        <QueryClientProvider client={queryClient}>
-          <TooltipProvider>
-            <WebsiteRouter />
-          </TooltipProvider>
-          <DevTools />
-        </QueryClientProvider>
-      </Provider>
+      <ThemeProvider>
+        <Provider store={store}>
+          <QueryClientProvider client={queryClient}>
+            <TooltipProvider>
+              <WebsiteRouter />
+            </TooltipProvider>
+            <DevTools />
+          </QueryClientProvider>
+        </Provider>
+      </ThemeProvider>
     </AppProvider>
   );
 }
diff --git a/app/src/app.css b/app/src/app.css
index a658806fe..05819e209 100644
--- a/app/src/app.css
+++ b/app/src/app.css
@@ -161,6 +161,112 @@
   --spacing-container: 976px;
 }
 
+:root,
+:root[data-pe-theme='light'] {
+  color-scheme: light;
+  --pe-color-surface-accent: #e6fffa;
+  --pe-color-surface-overlay: rgb(255 255 255 / 0.9);
+  --pe-color-surface-hover: #f9fafb;
+  --pe-shadow-light: rgb(16 24 40 / 0.05);
+  --pe-shadow-medium: rgb(16 24 40 / 0.1);
+  --pe-shadow-dark: rgb(16 24 40 / 0.2);
+
+  /* Compatibility variables for existing arbitrary Tailwind values. */
+  --color-primary-400: var(--tw-color-primary-400);
+  --color-primary-500: var(--tw-color-primary-500);
+  --color-primary-600: var(--tw-color-primary-600);
+}
+
+:root[data-pe-theme='dark'] {
+  color-scheme: dark;
+
+  --tw-color-primary-50: #0f302f;
+  --tw-color-primary-100: #15504e;
+  --tw-color-primary-200: #1f6f6c;
+  --tw-color-primary-300: #2b918d;
+  --tw-color-primary-400: #38b2ac;
+  --tw-color-primary-500: #4fd1c5;
+  --tw-color-primary-600: #63d9cf;
+  --tw-color-primary-700: #81e6d9;
+  --tw-color-primary-800: #b2f5ea;
+  --tw-color-primary-900: #e6fffa;
+
+  --tw-color-secondary-50: #101a1c;
+  --tw-color-secondary-100: #142225;
+  --tw-color-secondary-200: #1e3337;
+  --tw-color-secondary-300: #2b484d;
+  --tw-color-secondary-400: #49666a;
+  --tw-color-secondary-500: #73898b;
+  --tw-color-secondary-600: #9fb0b0;
+  --tw-color-secondary-700: #c5d0cf;
+  --tw-color-secondary-800: #e1e8e7;
+  --tw-color-secondary-900: #f5f8f8;
+
+  --tw-color-gray-50: #0d1719;
+  --tw-color-gray-100: #132124;
+  --tw-color-gray-200: #1d3034;
+  --tw-color-gray-300: #2c454a;
+  --tw-color-gray-400: #587276;
+  --tw-color-gray-500: #8ca0a2;
+  --tw-color-gray-600: #b5c4c5;
+  --tw-color-gray-700: #d3dddc;
+  --tw-color-gray-800: #ebf0ef;
+  --tw-color-gray-900: #f7fafa;
+
+  --tw-color-bg-primary: #071112;
+  --tw-color-bg-secondary: #0d1c1e;
+  --tw-color-bg-tertiary: #13272a;
+  --tw-color-text-primary: #f7fafa;
+  --tw-color-text-secondary: #bdcaca;
+  --tw-color-text-tertiary: #899fa1;
+  --tw-color-text-inverse: #061314;
+  --tw-color-text-link: #63d9cf;
+  --tw-color-text-link-hover: #81e6d9;
+  --tw-color-border-light: #20383c;
+  --tw-color-border-medium: #315257;
+  --tw-color-border-dark: #537276;
+
+  --tw-color-background: #071112;
+  --tw-color-foreground: #f7fafa;
+  --tw-color-primary: #4fd1c5;
+  --tw-color-primary-foreground: #061314;
+  --tw-color-secondary: #132124;
+  --tw-color-secondary-foreground: #f7fafa;
+  --tw-color-muted: #132124;
+  --tw-color-muted-foreground: #bdcaca;
+  --tw-color-accent: #173235;
+  --tw-color-accent-foreground: #f7fafa;
+  --tw-color-popover: #0d1c1e;
+  --tw-color-popover-foreground: #f7fafa;
+  --tw-color-card: #0d1c1e;
+  --tw-color-card-foreground: #f7fafa;
+  --tw-color-border: #20383c;
+  --tw-color-input: #20383c;
+  --tw-color-ring: #4fd1c5;
+
+  --pe-color-surface-accent: #102d2c;
+  --pe-color-surface-overlay: rgb(13 28 30 / 0.9);
+  --pe-color-surface-hover: #173235;
+  --pe-shadow-light: rgb(0 0 0 / 0.28);
+  --pe-shadow-medium: rgb(0 0 0 / 0.36);
+  --pe-shadow-dark: rgb(0 0 0 / 0.48);
+}
+
+:root[data-pe-theme='dark'] .tw\:bg-white {
+  background-color: var(--tw-color-card);
+}
+
+:root[data-pe-theme='dark'] .tw\:text-gray-900,
+:root[data-pe-theme='dark'] .tw\:text-gray-800,
+:root[data-pe-theme='dark'] .tw\:text-gray-700 {
+  color: var(--tw-color-foreground);
+}
+
+:root[data-pe-theme='dark'] .tw\:bg-gray-50,
+:root[data-pe-theme='dark'] .tw\:bg-gray-100 {
+  background-color: var(--tw-color-bg-secondary);
+}
+
 /*
  * =========================================================
  * Base styles
diff --git a/app/src/components/IframeContent.tsx b/app/src/components/IframeContent.tsx
index d776eecd3..459cbac0a 100644
--- a/app/src/components/IframeContent.tsx
+++ b/app/src/components/IframeContent.tsx
@@ -88,7 +88,7 @@ export default function IframeContent({
             display: 'flex',
             alignItems: 'center',
             justifyContent: 'center',
-            backgroundColor: colors.gray[50],
+            backgroundColor: colors.background.secondary,
             zIndex: 1,
           }}
         >
@@ -97,14 +97,14 @@ export default function IframeContent({
               style={{
                 width: '48px',
                 height: '48px',
-                border: `4px solid ${colors.gray[200]}`,
+                border: `4px solid ${colors.border.light}`,
                 borderTop: `4px solid ${colors.primary[600]}`,
                 borderRadius: '50%',
                 margin: `0 auto ${spacing.lg}`,
                 animation: 'spin 1s linear infinite',
               }}
             />
-            <p style={{ color: colors.gray[500], fontSize: typography.fontSize.sm }}>
+            <p style={{ color: colors.text.secondary, fontSize: typography.fontSize.sm }}>
               Loading calculator...
             </p>
           </div>
@@ -121,7 +121,7 @@ export default function IframeContent({
             display: 'flex',
             alignItems: 'center',
             justifyContent: 'center',
-            backgroundColor: colors.gray[50],
+            backgroundColor: colors.background.secondary,
             zIndex: 1,
           }}
         >
@@ -132,10 +132,10 @@ export default function IframeContent({
               maxWidth: '500px',
             }}
           >
-            <h2 style={{ color: colors.gray[900], marginBottom: spacing.lg }}>
+            <h2 style={{ color: colors.text.primary, marginBottom: spacing.lg }}>
               Unable to load calculator
             </h2>
-            <p style={{ color: colors.gray[500], marginBottom: spacing.lg }}>
+            <p style={{ color: colors.text.secondary, marginBottom: spacing.lg }}>
               The embedded calculator could not be loaded. You can try opening it directly:
             </p>
             <a
@@ -146,7 +146,7 @@ export default function IframeContent({
                 display: 'inline-block',
                 padding: `${spacing.sm} ${spacing.lg}`,
                 backgroundColor: colors.primary[600],
-                color: colors.white,
+                color: colors.text.inverse,
                 textDecoration: 'none',
                 borderRadius: spacing.radius.element,
               }}
diff --git a/app/src/components/ThemeToggle.tsx b/app/src/components/ThemeToggle.tsx
new file mode 100644
index 000000000..d76f7d5fd
--- /dev/null
+++ b/app/src/components/ThemeToggle.tsx
@@ -0,0 +1,45 @@
+import { IconMoon, IconSun } from '@tabler/icons-react';
+import { useTheme } from '@/contexts/ThemeContext';
+import { colors, spacing } from '@/designTokens';
+
+const buttonSize = 32;
+
+export default function ThemeToggle() {
+  const { resolvedTheme, toggleTheme } = useTheme();
+  const isDark = resolvedTheme === 'dark';
+  const label = isDark ? 'Switch to light mode' : 'Switch to dark mode';
+  const Icon = isDark ? IconSun : IconMoon;
+
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      aria-pressed={isDark}
+      title={label}
+      onClick={toggleTheme}
+      style={{
+        width: buttonSize,
+        height: buttonSize,
+        borderRadius: spacing.radius.container,
+        border: `1px solid ${colors.primary.alpha[40]}`,
+        background: 'rgba(255, 255, 255, 0.1)',
+        color: colors.text.inverse,
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        cursor: 'pointer',
+        transition: 'background-color 0.15s ease, border-color 0.15s ease',
+      }}
+      onMouseEnter={(event) => {
+        event.currentTarget.style.backgroundColor = 'rgba(255, 255, 255, 0.18)';
+        event.currentTarget.style.borderColor = colors.primary[300];
+      }}
+      onMouseLeave={(event) => {
+        event.currentTarget.style.backgroundColor = 'rgba(255, 255, 255, 0.1)';
+        event.currentTarget.style.borderColor = colors.primary.alpha[40];
+      }}
+    >
+      <Icon size={18} aria-hidden="true" />
+    </button>
+  );
+}
diff --git a/app/src/components/TwoColumnView.tsx b/app/src/components/TwoColumnView.tsx
index a75ee63b1..1900a369c 100644
--- a/app/src/components/TwoColumnView.tsx
+++ b/app/src/components/TwoColumnView.tsx
@@ -11,12 +11,12 @@ interface TwoColumnViewProps {
 function TwoColumnView({ title, leftColumn, rightColumn, backgroundColor }: TwoColumnViewProps) {
   function getBackgroundColor(): string {
     if (backgroundColor === 'primary') {
-      return colors.primary[100];
+      return colors.background.accent;
     }
     if (backgroundColor === 'secondary') {
-      return colors.secondary[100];
+      return colors.background.secondary;
     }
-    return colors.white;
+    return colors.background.elevated;
   }
 
   return (
diff --git a/app/src/components/charts/tooltipStyle.ts b/app/src/components/charts/tooltipStyle.ts
index e32f84cca..e945d4b33 100644
--- a/app/src/components/charts/tooltipStyle.ts
+++ b/app/src/components/charts/tooltipStyle.ts
@@ -5,8 +5,8 @@ import { colors, spacing } from '@/designTokens';
  * Shared tooltip container style for all Recharts custom tooltips.
  */
 export const TOOLTIP_STYLE: CSSProperties = {
-  background: colors.white,
-  border: `1px solid ${colors.gray[200]}`,
+  background: colors.background.elevated,
+  border: `1px solid ${colors.border.light}`,
   borderRadius: spacing.radius.element,
   padding: `${spacing.sm} ${spacing.md}`,
 };
diff --git a/app/src/components/common/MetadataLoadingExperience.tsx b/app/src/components/common/MetadataLoadingExperience.tsx
index b9ef0bf76..860b2c8c3 100644
--- a/app/src/components/common/MetadataLoadingExperience.tsx
+++ b/app/src/components/common/MetadataLoadingExperience.tsx
@@ -18,14 +18,14 @@ export function MetadataLoadingExperience({ countryId }: MetadataLoadingExperien
   return (
     <Container>
       <Title order={2}>Loading</Title>
-      <Text className="tw:mb-sm" style={{ color: colors.gray[600] }}>
+      <Text className="tw:mb-sm" style={{ color: colors.text.secondary }}>
         Fetching {countryName} policy data
       </Text>
       <hr className="tw:border-border-light tw:my-sm" />
 
       <Stack className="tw:items-center tw:justify-center tw:py-20">
         <Spinner size="lg" />
-        <Text size="sm" className="tw:mt-md" style={{ color: colors.gray[600] }}>
+        <Text size="sm" className="tw:mt-md" style={{ color: colors.text.secondary }}>
           This may take a moment for first-time loads
         </Text>
       </Stack>
diff --git a/app/src/components/interactive/StreamlitEmbed.tsx b/app/src/components/interactive/StreamlitEmbed.tsx
index 2aa9bc424..01bb23824 100644
--- a/app/src/components/interactive/StreamlitEmbed.tsx
+++ b/app/src/components/interactive/StreamlitEmbed.tsx
@@ -67,11 +67,11 @@ export default function StreamlitEmbed({
             left: 0,
             right: 0,
             zIndex: 1000,
-            backgroundColor: colors.gray[100],
-            borderBottom: `1px solid ${colors.gray[300]}`,
+            backgroundColor: colors.background.secondary,
+            borderBottom: `1px solid ${colors.border.light}`,
             padding: `${spacing.sm} ${spacing.lg}`,
             fontSize: typography.fontSize.sm,
-            color: colors.gray[600],
+            color: colors.text.secondary,
             display: 'flex',
             justifyContent: 'space-between',
             alignItems: 'center',
@@ -92,12 +92,12 @@ export default function StreamlitEmbed({
               target="_blank"
               rel="noopener noreferrer"
               style={{
-                backgroundColor: colors.white,
-                border: `1px solid ${colors.gray[300]}`,
+                backgroundColor: colors.background.elevated,
+                border: `1px solid ${colors.border.light}`,
                 borderRadius: spacing.radius.element,
                 padding: `2px ${spacing.md}`,
                 fontSize: typography.fontSize.xs,
-                color: colors.gray[600],
+                color: colors.text.secondary,
                 textDecoration: 'none',
                 display: 'inline-block',
                 transition: 'all 0.2s',
@@ -107,8 +107,8 @@ export default function StreamlitEmbed({
                 e.currentTarget.style.color = colors.primary[500];
               }}
               onMouseLeave={(e) => {
-                e.currentTarget.style.borderColor = colors.gray[300];
-                e.currentTarget.style.color = colors.gray[600];
+                e.currentTarget.style.borderColor = colors.border.light;
+                e.currentTarget.style.color = colors.text.secondary;
               }}
             >
               Wake it up
@@ -120,7 +120,7 @@ export default function StreamlitEmbed({
             style={{
               background: 'none',
               border: 'none',
-              color: colors.gray[500],
+              color: colors.text.tertiary,
               cursor: 'pointer',
               fontSize: '16px',
               padding: `0 ${spacing.xs}`,
diff --git a/app/src/components/ui/Text.tsx b/app/src/components/ui/Text.tsx
index 60b2ca88d..a285eea8d 100644
--- a/app/src/components/ui/Text.tsx
+++ b/app/src/components/ui/Text.tsx
@@ -4,7 +4,7 @@ import { cn } from '@/lib/utils';
 
 // Mantine color aliases — "dimmed" was the most common
 const COLOR_ALIASES: Record<string, string> = {
-  dimmed: '#9CA3AF',
+  dimmed: 'var(--tw-color-text-tertiary)',
 };
 
 const textVariants = cva('', {
diff --git a/app/src/contexts/ThemeContext.tsx b/app/src/contexts/ThemeContext.tsx
new file mode 100644
index 000000000..7362b9492
--- /dev/null
+++ b/app/src/contexts/ThemeContext.tsx
@@ -0,0 +1,144 @@
+'use client';
+
+import {
+  createContext,
+  ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+
+export type ThemePreference = 'light' | 'dark' | 'system';
+export type ResolvedTheme = 'light' | 'dark';
+
+interface ThemeContextValue {
+  preference: ThemePreference;
+  resolvedTheme: ResolvedTheme;
+  setPreference: (preference: ThemePreference) => void;
+  toggleTheme: () => void;
+}
+
+const STORAGE_KEY = 'policyengine-theme';
+const MEDIA_QUERY = '(prefers-color-scheme: dark)';
+
+const fallbackThemeContext: ThemeContextValue = {
+  preference: 'system',
+  resolvedTheme: 'light',
+  setPreference: () => {},
+  toggleTheme: () => {},
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+function isThemePreference(value: string | null): value is ThemePreference {
+  return value === 'light' || value === 'dark' || value === 'system';
+}
+
+function getStoredPreference(): ThemePreference {
+  if (typeof window === 'undefined') {
+    return 'system';
+  }
+
+  try {
+    const storedPreference = window.localStorage.getItem(STORAGE_KEY);
+    return isThemePreference(storedPreference) ? storedPreference : 'system';
+  } catch {
+    return 'system';
+  }
+}
+
+function getSystemTheme(): ResolvedTheme {
+  if (typeof window === 'undefined') {
+    return 'light';
+  }
+
+  return window.matchMedia(MEDIA_QUERY).matches ? 'dark' : 'light';
+}
+
+function resolveTheme(preference: ThemePreference, systemTheme: ResolvedTheme): ResolvedTheme {
+  return preference === 'system' ? systemTheme : preference;
+}
+
+function applyTheme(theme: ResolvedTheme) {
+  if (typeof document === 'undefined') {
+    return;
+  }
+
+  document.documentElement.dataset.peTheme = theme;
+  document.documentElement.style.colorScheme = theme;
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [preference, setPreferenceState] = useState<ThemePreference>('system');
+  const [systemTheme, setSystemTheme] = useState<ResolvedTheme>('light');
+
+  useEffect(() => {
+    const storedPreference = getStoredPreference();
+    const currentSystemTheme = getSystemTheme();
+
+    setPreferenceState(storedPreference);
+    setSystemTheme(currentSystemTheme);
+    applyTheme(resolveTheme(storedPreference, currentSystemTheme));
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    const mediaQuery = window.matchMedia(MEDIA_QUERY);
+    const handleChange = () => {
+      const nextSystemTheme = mediaQuery.matches ? 'dark' : 'light';
+      setSystemTheme(nextSystemTheme);
+
+      if (preference === 'system') {
+        applyTheme(nextSystemTheme);
+      }
+    };
+
+    mediaQuery.addEventListener('change', handleChange);
+    return () => mediaQuery.removeEventListener('change', handleChange);
+  }, [preference]);
+
+  const resolvedTheme = resolveTheme(preference, systemTheme);
+
+  useEffect(() => {
+    applyTheme(resolvedTheme);
+  }, [resolvedTheme]);
+
+  const setPreference = useCallback((nextPreference: ThemePreference) => {
+    setPreferenceState(nextPreference);
+
+    try {
+      if (nextPreference === 'system') {
+        window.localStorage.removeItem(STORAGE_KEY);
+      } else {
+        window.localStorage.setItem(STORAGE_KEY, nextPreference);
+      }
+    } catch {
+      // Ignore storage failures and keep the in-memory preference.
+    }
+  }, []);
+
+  const toggleTheme = useCallback(() => {
+    setPreference(resolvedTheme === 'dark' ? 'light' : 'dark');
+  }, [resolvedTheme, setPreference]);
+
+  const value = useMemo(
+    () => ({
+      preference,
+      resolvedTheme,
+      setPreference,
+      toggleTheme,
+    }),
+    [preference, resolvedTheme, setPreference, toggleTheme]
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme() {
+  return useContext(ThemeContext) ?? fallbackThemeContext;
+}
diff --git a/app/src/designTokens/colors.ts b/app/src/designTokens/colors.ts
index 3d7b353f7..9f1327902 100644
--- a/app/src/designTokens/colors.ts
+++ b/app/src/designTokens/colors.ts
@@ -1,3 +1,5 @@
+const cssVar = (name: string) => `var(${name})`;
+
 /**
  * PolicyEngine color palette.
  *
@@ -58,20 +60,24 @@ export const colors = {
   },
 
   background: {
-    primary: '#FFFFFF',
-    secondary: '#F5F9FF',
-    tertiary: '#F1F5F9',
-    sider: '#FFFFFF',
+    primary: cssVar('--tw-color-bg-primary'),
+    secondary: cssVar('--tw-color-bg-secondary'),
+    tertiary: cssVar('--tw-color-bg-tertiary'),
+    sider: cssVar('--tw-color-bg-primary'),
+    elevated: cssVar('--tw-color-card'),
+    accent: cssVar('--pe-color-surface-accent'),
+    overlay: cssVar('--pe-color-surface-overlay'),
+    hover: cssVar('--pe-color-surface-hover'),
   },
 
   text: {
-    primary: '#000000',
-    secondary: '#5A5A5A',
-    tertiary: '#9CA3AF',
+    primary: cssVar('--tw-color-text-primary'),
+    secondary: cssVar('--tw-color-text-secondary'),
+    tertiary: cssVar('--tw-color-text-tertiary'),
     inverse: '#FFFFFF',
-    title: '#000000',
-    link: '#2C7A7B',
-    linkHover: '#285E61',
+    title: cssVar('--tw-color-text-primary'),
+    link: cssVar('--tw-color-text-link'),
+    linkHover: cssVar('--tw-color-text-link-hover'),
     warning: '#d9480f',
   },
 
@@ -80,15 +86,15 @@ export const colors = {
   },
 
   border: {
-    light: '#E2E8F0',
-    medium: '#CBD5E1',
-    dark: '#94A3B8',
+    light: cssVar('--tw-color-border-light'),
+    medium: cssVar('--tw-color-border-medium'),
+    dark: cssVar('--tw-color-border-dark'),
   },
 
   shadow: {
-    light: 'rgba(16, 24, 40, 0.05)',
-    medium: 'rgba(16, 24, 40, 0.1)',
-    dark: 'rgba(16, 24, 40, 0.2)',
+    light: cssVar('--pe-shadow-light'),
+    medium: cssVar('--pe-shadow-medium'),
+    dark: cssVar('--pe-shadow-dark'),
   },
 } as const;
 
diff --git a/app/src/pages/ClaudePlugins.page.tsx b/app/src/pages/ClaudePlugins.page.tsx
index cb2890699..f187541f4 100644
--- a/app/src/pages/ClaudePlugins.page.tsx
+++ b/app/src/pages/ClaudePlugins.page.tsx
@@ -317,7 +317,7 @@ export default function ClaudePluginsPage() {
         style={{
           paddingTop: 80,
           paddingBottom: 80,
-          backgroundColor: colors.white,
+          backgroundColor: colors.background.primary,
           ...SECTION_PX,
           borderBottom: `1px solid ${colors.border.light}`,
           overflow: 'hidden',
@@ -357,7 +357,7 @@ export default function ClaudePluginsPage() {
                     fontSize: 'clamp(32px, 4.5vw, 48px)',
                     fontWeight: typography.fontWeight.bold,
                     fontFamily: typography.fontFamily.primary,
-                    color: colors.gray[900],
+                    color: colors.text.primary,
                     lineHeight: 1.08,
                     letterSpacing: '-0.03em',
                     marginBottom: spacing.lg,
@@ -391,7 +391,7 @@ export default function ClaudePluginsPage() {
                   style={{
                     display: 'inline-block',
                     backgroundColor: colors.primary[500],
-                    color: colors.white,
+                    color: colors.text.inverse,
                     fontFamily: typography.fontFamily.primary,
                     fontWeight: typography.fontWeight.semibold,
                     fontSize: typography.fontSize.sm,
@@ -459,7 +459,7 @@ export default function ClaudePluginsPage() {
         style={{
           paddingTop: spacing['4xl'],
           paddingBottom: spacing['4xl'],
-          backgroundColor: colors.gray[50],
+          backgroundColor: colors.background.secondary,
           ...SECTION_PX,
           borderBottom: `1px solid ${colors.border.light}`,
         }}
@@ -492,7 +492,7 @@ export default function ClaudePluginsPage() {
                     border: `1px solid ${colors.border.light}`,
                     borderRadius: spacing.md,
                     padding: spacing.xl,
-                    backgroundColor: colors.white,
+                    backgroundColor: colors.background.elevated,
                     display: 'flex',
                     flexDirection: 'column',
                     height: '100%',
@@ -536,7 +536,7 @@ export default function ClaudePluginsPage() {
         style={{
           paddingTop: spacing['4xl'],
           paddingBottom: spacing['4xl'],
-          backgroundColor: colors.white,
+          backgroundColor: colors.background.primary,
           ...SECTION_PX,
           borderBottom: `1px solid ${colors.border.light}`,
         }}
@@ -576,7 +576,7 @@ export default function ClaudePluginsPage() {
                   width: '100%',
                   borderRadius: '12px',
                   overflow: 'hidden',
-                  boxShadow: '0 8px 32px -4px rgba(0,0,0,0.12)',
+                  boxShadow: `0 8px 32px -4px ${colors.shadow.medium}`,
                 }}
               >
                 {/* eslint-disable-next-line jsx-a11y/media-has-caption */}
@@ -620,7 +620,7 @@ export default function ClaudePluginsPage() {
         style={{
           paddingTop: spacing['4xl'],
           paddingBottom: spacing['4xl'],
-          backgroundColor: colors.white,
+          backgroundColor: colors.background.primary,
           ...SECTION_PX,
           borderBottom: `1px solid ${colors.border.light}`,
         }}
@@ -731,7 +731,7 @@ export default function ClaudePluginsPage() {
                 fontFamily: typography.fontFamily.primary,
                 fontWeight: typography.fontWeight.bold,
                 fontSize: typography.fontSize['3xl'],
-                color: colors.white,
+                color: colors.text.inverse,
                 textAlign: 'center',
                 marginBottom: spacing['3xl'],
               }}
@@ -787,7 +787,7 @@ export default function ClaudePluginsPage() {
                       fontWeight: typography.fontWeight.semibold,
                       fontFamily: typography.fontFamily.primary,
                       fontSize: typography.fontSize.sm,
-                      color: colors.white,
+                      color: colors.text.inverse,
                       marginBottom: 4,
                     }}
                   >
diff --git a/app/src/pages/NotFound.page.tsx b/app/src/pages/NotFound.page.tsx
index 0b62774e3..bf6ae85ac 100644
--- a/app/src/pages/NotFound.page.tsx
+++ b/app/src/pages/NotFound.page.tsx
@@ -8,7 +8,7 @@ export default function NotFoundPage() {
   return (
     <Container>
       <Title order={2}>Page not found</Title>
-      <Text className="tw:mb-sm" style={{ color: colors.gray[500] }}>
+      <Text className="tw:mb-sm" style={{ color: colors.text.secondary }}>
         The page you're looking for doesn't exist or has been moved.
       </Text>
       <hr className="tw:border-border-light tw:my-sm" />
@@ -21,7 +21,7 @@ export default function NotFoundPage() {
         >
           404
         </Text>
-        <Text size="sm" className="tw:mt-md" style={{ color: colors.gray[500] }}>
+        <Text size="sm" className="tw:mt-md" style={{ color: colors.text.secondary }}>
           Check the URL or head back to your reports.
         </Text>
         <Button className="tw:mt-md" asChild>
diff --git a/app/src/tests/unit/contexts/ThemeContext.test.tsx b/app/src/tests/unit/contexts/ThemeContext.test.tsx
new file mode 100644
index 000000000..7a44c8cfd
--- /dev/null
+++ b/app/src/tests/unit/contexts/ThemeContext.test.tsx
@@ -0,0 +1,71 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { ThemeProvider, useTheme } from '@/contexts/ThemeContext';
+
+function ThemeProbe() {
+  const { resolvedTheme, toggleTheme } = useTheme();
+
+  return (
+    <button type="button" onClick={toggleTheme}>
+      {resolvedTheme}
+    </button>
+  );
+}
+
+function mockMatchMedia(matches: boolean) {
+  Object.defineProperty(window, 'matchMedia', {
+    configurable: true,
+    writable: true,
+    value: vi.fn().mockImplementation((query) => ({
+      matches,
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  });
+}
+
+describe('ThemeProvider', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    document.documentElement.removeAttribute('data-pe-theme');
+    document.documentElement.style.colorScheme = '';
+  });
+
+  test('given no saved preference then follows system dark mode', async () => {
+    mockMatchMedia(true);
+
+    render(
+      <ThemeProvider>
+        <ThemeProbe />
+      </ThemeProvider>
+    );
+
+    await waitFor(() => {
+      expect(document.documentElement.dataset.peTheme).toBe('dark');
+      expect(screen.getByRole('button', { name: 'dark' })).toBeInTheDocument();
+    });
+  });
+
+  test('given dark mode then toggle stores a light preference', async () => {
+    mockMatchMedia(true);
+
+    render(
+      <ThemeProvider>
+        <ThemeProbe />
+      </ThemeProvider>
+    );
+
+    await screen.findByRole('button', { name: 'dark' });
+    fireEvent.click(screen.getByRole('button', { name: 'dark' }));
+
+    await waitFor(() => {
+      expect(document.documentElement.dataset.peTheme).toBe('light');
+      expect(localStorage.getItem('policyengine-theme')).toBe('light');
+    });
+  });
+});
diff --git a/app/src/utils/visualization/colorScales.ts b/app/src/utils/visualization/colorScales.ts
index 4e13b5939..b66159347 100644
--- a/app/src/utils/visualization/colorScales.ts
+++ b/app/src/utils/visualization/colorScales.ts
@@ -11,12 +11,12 @@ export interface ColorScale {
 
 /**
  * Diverging color scale for positive/negative values
- * Gray (negative) → Subtle background (neutral) → Teal (positive)
+ * Gray (negative) → Light gray (neutral) → Teal (positive)
  *
  * Uses design tokens from the primary brand palette:
  * - Dark gray (#344054) for most negative values
  * - Medium gray (#9CA3AF) for moderately negative values
- * - Light background (#F1F5F9) for neutral/near-zero values
+ * - Light gray (#F2F4F7) for neutral/near-zero values
  * - Light teal (#81E6D9) for moderately positive values
  * - Teal (#2C7A7B) for most positive values
  */
@@ -25,7 +25,7 @@ export const DIVERGING_GRAY_BLUE: ColorScale = {
   colors: [
     colors.gray[700],
     colors.gray[400],
-    colors.background.tertiary,
+    colors.gray[100],
     colors.primary[200],
     colors.primary[600],
   ],
@@ -34,7 +34,7 @@ export const DIVERGING_GRAY_BLUE: ColorScale = {
 
 /**
  * Diverging color scale for positive/negative values using teal primary
- * Gray (negative) → White (neutral) → Teal (positive)
+ * Gray (negative) → Light gray (neutral) → Teal (positive)
  *
  * Uses design tokens from the primary teal color palette
  */
@@ -43,7 +43,7 @@ export const DIVERGING_GRAY_TEAL: ColorScale = {
   colors: [
     colors.gray[700], // Dark gray (most negative)
     colors.gray[400], // Medium gray
-    colors.background.tertiary,
+    colors.gray[100],
     colors.primary[200], // Light teal
     colors.primary[600], // Teal (most positive)
   ],
diff --git a/app/test-utils/render.tsx b/app/test-utils/render.tsx
index 72288263b..cd4e8a2e0 100644
--- a/app/test-utils/render.tsx
+++ b/app/test-utils/render.tsx
@@ -6,6 +6,7 @@ import { AppProvider } from '../src/contexts/AppContext';
 import { CountryProvider } from '../src/contexts/CountryContext';
 import { LocationProvider } from '../src/contexts/LocationContext';
 import { NavigationProvider } from '../src/contexts/NavigationContext';
+import { ThemeProvider } from '../src/contexts/ThemeContext';
 import { store } from '../src/store';
 
 function RouterContextBridge({ children }: { children: React.ReactNode }) {
@@ -30,15 +31,17 @@ export function render(ui: React.ReactNode, countryId: string = 'us') {
   return testingLibraryRender(ui, {
     wrapper: ({ children }: { children: React.ReactNode }) => (
       <AppProvider mode="website">
-        <ReduxProvider store={store}>
-          <MemoryRouter>
-            <CountryProvider value={countryId as any}>
-              <RouterContextBridge>
-                <TooltipProvider>{children}</TooltipProvider>
-              </RouterContextBridge>
-            </CountryProvider>
-          </MemoryRouter>
-        </ReduxProvider>
+        <ThemeProvider>
+          <ReduxProvider store={store}>
+            <MemoryRouter>
+              <CountryProvider value={countryId as any}>
+                <RouterContextBridge>
+                  <TooltipProvider>{children}</TooltipProvider>
+                </RouterContextBridge>
+              </CountryProvider>
+            </MemoryRouter>
+          </ReduxProvider>
+        </ThemeProvider>
       </AppProvider>
     ),
   });
diff --git a/app/test-utils/renderWithCountry.tsx b/app/test-utils/renderWithCountry.tsx
index 3758b3bec..cc3c89076 100644
--- a/app/test-utils/renderWithCountry.tsx
+++ b/app/test-utils/renderWithCountry.tsx
@@ -6,6 +6,7 @@ import { AppMode, AppProvider } from '../src/contexts/AppContext';
 import { CountryProvider } from '../src/contexts/CountryContext';
 import { LocationProvider } from '../src/contexts/LocationContext';
 import { NavigationProvider } from '../src/contexts/NavigationContext';
+import { ThemeProvider } from '../src/contexts/ThemeContext';
 import { store } from '../src/store';
 
 function RouterContextBridge({ children }: { children: React.ReactNode }) {
@@ -35,20 +36,22 @@ export function renderWithCountry(
   return testingLibraryRender(ui, {
     wrapper: ({ children }: { children: React.ReactNode }) => (
       <AppProvider mode={appMode}>
-        <ReduxProvider store={store}>
-          <MemoryRouter initialEntries={[path]}>
-            <CountryProvider value={countryId as any}>
-              <RouterContextBridge>
-                <TooltipProvider>
-                  <Routes>
-                    <Route path="/:countryId" element={children} />
-                    <Route path="/:countryId/*" element={children} />
-                  </Routes>
-                </TooltipProvider>
-              </RouterContextBridge>
-            </CountryProvider>
-          </MemoryRouter>
-        </ReduxProvider>
+        <ThemeProvider>
+          <ReduxProvider store={store}>
+            <MemoryRouter initialEntries={[path]}>
+              <CountryProvider value={countryId as any}>
+                <RouterContextBridge>
+                  <TooltipProvider>
+                    <Routes>
+                      <Route path="/:countryId" element={children} />
+                      <Route path="/:countryId/*" element={children} />
+                    </Routes>
+                  </TooltipProvider>
+                </RouterContextBridge>
+              </CountryProvider>
+            </MemoryRouter>
+          </ReduxProvider>
+        </ThemeProvider>
       </AppProvider>
     ),
   });
diff --git a/app/website.html b/app/website.html
index ea65eb47b..b40f6ea58 100644
--- a/app/website.html
+++ b/app/website.html
@@ -18,6 +18,27 @@
       name="viewport"
       content="minimum-scale=1, initial-scale=1, width=device-width, user-scalable=no"
     />
+    <meta name="color-scheme" content="light dark" />
+    <script>
+      (function () {
+        try {
+          var storedPreference = window.localStorage.getItem('policyengine-theme');
+          var preference =
+            storedPreference === 'light' || storedPreference === 'dark'
+              ? storedPreference
+              : 'system';
+          var theme =
+            preference === 'system'
+              ? window.matchMedia('(prefers-color-scheme: dark)').matches
+                ? 'dark'
+                : 'light'
+              : preference;
+
+          document.documentElement.dataset.peTheme = theme;
+          document.documentElement.style.colorScheme = theme;
+        } catch (error) {}
+      })();
+    </script>
     <title>PolicyEngine</title>
     <meta
       name="description"
diff --git a/website/src/__tests__/components/theme.test.tsx b/website/src/__tests__/components/theme.test.tsx
new file mode 100644
index 000000000..a60fa08c7
--- /dev/null
+++ b/website/src/__tests__/components/theme.test.tsx
@@ -0,0 +1,98 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { ThemeProvider, useTheme } from "@/contexts/ThemeContext";
+
+function ThemeProbe() {
+  const { resolvedTheme, toggleTheme } = useTheme();
+
+  return (
+    <button type="button" onClick={toggleTheme}>
+      {resolvedTheme}
+    </button>
+  );
+}
+
+function mockMatchMedia(matches: boolean) {
+  Object.defineProperty(window, "matchMedia", {
+    configurable: true,
+    writable: true,
+    value: vi.fn().mockImplementation((query) => ({
+      matches,
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  });
+}
+
+function mockLocalStorage() {
+  const store = new Map<string, string>();
+  const storage = {
+    get length() {
+      return store.size;
+    },
+    key: (index: number) => Array.from(store.keys())[index] ?? null,
+    getItem: (key: string) => store.get(String(key)) ?? null,
+    setItem: (key: string, value: string) =>
+      store.set(String(key), String(value)),
+    removeItem: (key: string) => store.delete(String(key)),
+    clear: () => store.clear(),
+  };
+
+  Object.defineProperty(window, "localStorage", {
+    configurable: true,
+    writable: true,
+    value: storage,
+  });
+  Object.defineProperty(globalThis, "localStorage", {
+    configurable: true,
+    writable: true,
+    value: storage,
+  });
+}
+
+describe("ThemeProvider", () => {
+  beforeEach(() => {
+    mockLocalStorage();
+    localStorage.clear();
+    document.documentElement.removeAttribute("data-pe-theme");
+    document.documentElement.style.colorScheme = "";
+  });
+
+  test("given no saved preference then follows system dark mode", async () => {
+    mockMatchMedia(true);
+
+    render(
+      <ThemeProvider>
+        <ThemeProbe />
+      </ThemeProvider>,
+    );
+
+    await waitFor(() => {
+      expect(document.documentElement.dataset.peTheme).toBe("dark");
+      expect(screen.getByRole("button", { name: "dark" })).toBeInTheDocument();
+    });
+  });
+
+  test("given dark mode then toggle stores a light preference", async () => {
+    mockMatchMedia(true);
+
+    render(
+      <ThemeProvider>
+        <ThemeProbe />
+      </ThemeProvider>,
+    );
+
+    await screen.findByRole("button", { name: "dark" });
+    fireEvent.click(screen.getByRole("button", { name: "dark" }));
+
+    await waitFor(() => {
+      expect(document.documentElement.dataset.peTheme).toBe("light");
+      expect(localStorage.getItem("policyengine-theme")).toBe("light");
+    });
+  });
+});
diff --git a/website/src/app/[countryId]/brand/assets/page.tsx b/website/src/app/[countryId]/brand/assets/page.tsx
index fcc41dd36..b35e1d49f 100644
--- a/website/src/app/[countryId]/brand/assets/page.tsx
+++ b/website/src/app/[countryId]/brand/assets/page.tsx
@@ -2,11 +2,7 @@ import type { Metadata } from "next";
 import Link from "next/link";
 import { IconCheck, IconX } from "@tabler/icons-react";
 import { Button, Text, Title } from "@/components/ui";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 export const metadata: Metadata = {
   title: "Assets",
@@ -41,7 +37,7 @@ function LogoCard({
   return (
     <div
       style={{
-        background: colors.white,
+        background: colors.background.elevated,
         border: `1px solid ${colors.border.light}`,
         borderRadius: spacing.radius.container,
         overflow: "hidden",
@@ -81,13 +77,7 @@ function LogoCard({
   );
 }
 
-function UsageCard({
-  type,
-  items,
-}: {
-  type: "do" | "dont";
-  items: string[];
-}) {
+function UsageCard({ type, items }: { type: "do" | "dont"; items: string[] }) {
   const isDo = type === "do";
   return (
     <div
@@ -138,7 +128,10 @@ function ColorSwatch({ name, value }: { name: string; value: string }) {
       }}
     >
       <div style={{ height: 60, background: value }} />
-      <div className="tw:p-sm" style={{ background: colors.white }}>
+      <div
+        className="tw:p-sm"
+        style={{ background: colors.background.elevated }}
+      >
         <Text
           style={{
             fontSize: typography.fontSize.sm,
@@ -170,8 +163,8 @@ export default function BrandAssetsPage() {
         style={{
           paddingTop: spacing["4xl"],
           paddingBottom: spacing["4xl"],
-          backgroundColor: colors.primary[50],
-          borderBottom: `1px solid ${colors.border.dark}`,
+          backgroundColor: colors.background.accent,
+          borderBottom: `1px solid ${colors.border.light}`,
           paddingLeft: "6.125%",
           paddingRight: "6.125%",
         }}
@@ -303,7 +296,7 @@ export default function BrandAssetsPage() {
           <div
             className="tw:flex tw:justify-center tw:p-xl tw:mb-md"
             style={{
-              background: colors.white,
+              background: colors.background.elevated,
               border: `1px solid ${colors.border.light}`,
               borderRadius: spacing.radius.container,
             }}
diff --git a/website/src/app/[countryId]/brand/design/BrandDesignClient.tsx b/website/src/app/[countryId]/brand/design/BrandDesignClient.tsx
index 8114f0f7a..e9ec31ad4 100644
--- a/website/src/app/[countryId]/brand/design/BrandDesignClient.tsx
+++ b/website/src/app/[countryId]/brand/design/BrandDesignClient.tsx
@@ -14,12 +14,13 @@ import {
   IconWorld,
   IconX,
 } from "@tabler/icons-react";
-import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui";
 import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui";
+import { colors, spacing, typography } from "@/designTokens";
 
 const colorTokens = [
   {
@@ -93,34 +94,34 @@ function ColorSwatch({
 
   return (
     <TooltipProvider>
-    <Tooltip>
-      <TooltipTrigger asChild>
-        <button
-          type="button"
-          onClick={handleCopy}
-          className="tw:bg-transparent tw:border tw:border-border-light tw:rounded-container tw:overflow-hidden tw:cursor-pointer tw:p-0 tw:transition-all tw:duration-150 tw:hover:-translate-y-0.5 tw:hover:shadow-md"
-        >
-          <div
-            className="tw:h-20"
-            style={{
-              background: value,
-              borderBottom: isLight
-                ? `1px solid ${colors.border.light}`
-                : "none",
-            }}
-          />
-          <div className="tw:p-md tw:text-left">
-            <p className="tw:font-mono tw:text-sm tw:text-text-primary tw:mb-xs">
-              {label}
-            </p>
-            <p className="tw:font-mono tw:text-xs tw:text-text-tertiary">
-              {value}
-            </p>
-          </div>
-        </button>
-      </TooltipTrigger>
-      <TooltipContent>{copied ? "Copied!" : "Click to copy"}</TooltipContent>
-    </Tooltip>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <button
+            type="button"
+            onClick={handleCopy}
+            className="tw:bg-transparent tw:border tw:border-border-light tw:rounded-container tw:overflow-hidden tw:cursor-pointer tw:p-0 tw:transition-all tw:duration-150 tw:hover:-translate-y-0.5 tw:hover:shadow-md"
+          >
+            <div
+              className="tw:h-20"
+              style={{
+                background: value,
+                borderBottom: isLight
+                  ? `1px solid ${colors.border.light}`
+                  : "none",
+              }}
+            />
+            <div className="tw:p-md tw:text-left">
+              <p className="tw:font-mono tw:text-sm tw:text-text-primary tw:mb-xs">
+                {label}
+              </p>
+              <p className="tw:font-mono tw:text-xs tw:text-text-tertiary">
+                {value}
+              </p>
+            </div>
+          </button>
+        </TooltipTrigger>
+        <TooltipContent>{copied ? "Copied!" : "Click to copy"}</TooltipContent>
+      </Tooltip>
     </TooltipProvider>
   );
 }
@@ -153,7 +154,7 @@ export default function BrandDesignClient() {
       <div
         className="tw:py-4xl tw:border-b tw:border-border-dark"
         style={{
-          backgroundColor: colors.primary[50],
+          backgroundColor: colors.background.accent,
           paddingLeft: "6.125%",
           paddingRight: "6.125%",
         }}
@@ -296,9 +297,7 @@ export default function BrandDesignClient() {
               Tabler Icons
             </a>
             . Import from{" "}
-            <code className="tw:font-mono tw:text-sm">
-              @tabler/icons-react
-            </code>
+            <code className="tw:font-mono tw:text-sm">@tabler/icons-react</code>
             .
           </p>
 
diff --git a/website/src/app/[countryId]/brand/writing/page.tsx b/website/src/app/[countryId]/brand/writing/page.tsx
index 4a080ef27..85415b85a 100644
--- a/website/src/app/[countryId]/brand/writing/page.tsx
+++ b/website/src/app/[countryId]/brand/writing/page.tsx
@@ -2,11 +2,7 @@ import type { Metadata } from "next";
 import Link from "next/link";
 import { IconCheck, IconX } from "@tabler/icons-react";
 import { Text, Title } from "@/components/ui";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 export const metadata: Metadata = {
   title: "Writing guide",
@@ -74,9 +70,7 @@ function ExampleBox({
     <div
       className="tw:p-md"
       style={{
-        background: isGood
-          ? `${colors.primary[500]}10`
-          : `${colors.error}10`,
+        background: isGood ? `${colors.primary[500]}10` : `${colors.error}10`,
         border: `1px solid ${isGood ? colors.primary[500] : colors.error}30`,
         borderRadius: spacing.radius.container,
       }}
@@ -109,18 +103,12 @@ function ExampleBox({
   );
 }
 
-function TermItem({
-  term,
-  definition,
-}: {
-  term: string;
-  definition: string;
-}) {
+function TermItem({ term, definition }: { term: string; definition: string }) {
   return (
     <div
       className="tw:flex tw:items-center tw:p-md tw:gap-lg"
       style={{
-        background: colors.white,
+        background: colors.background.elevated,
         border: `1px solid ${colors.border.light}`,
         borderRadius: spacing.radius.container,
       }}
@@ -189,8 +177,8 @@ export default function BrandWritingPage() {
         style={{
           paddingTop: spacing["4xl"],
           paddingBottom: spacing["4xl"],
-          backgroundColor: colors.primary[50],
-          borderBottom: `1px solid ${colors.border.dark}`,
+          backgroundColor: colors.background.accent,
+          borderBottom: `1px solid ${colors.border.light}`,
           paddingLeft: "6.125%",
           paddingRight: "6.125%",
         }}
@@ -229,8 +217,8 @@ export default function BrandWritingPage() {
             maxWidth: 600,
           }}
         >
-          How PolicyEngine communicates. Voice, tone, and content guidelines
-          for research-oriented writing.
+          How PolicyEngine communicates. Voice, tone, and content guidelines for
+          research-oriented writing.
         </Text>
       </div>
 
@@ -255,16 +243,16 @@ export default function BrandWritingPage() {
               lineHeight: typography.lineHeight.relaxed,
             }}
           >
-            Always use sentence case for headings, not title case. This
-            follows the modern standard used by Apple, Google, Slack, Notion,
-            and GOV.UK.
+            Always use sentence case for headings, not title case. This follows
+            the modern standard used by Apple, Google, Slack, Notion, and
+            GOV.UK.
           </Text>
 
           <div className="tw:mb-xl">
             <RuleTitle>The rule</RuleTitle>
             <RuleDescription>
-              Capitalize only the first word of a heading and any proper
-              nouns. Everything else stays lowercase.
+              Capitalize only the first word of a heading and any proper nouns.
+              Everything else stays lowercase.
             </RuleDescription>
             <div className="tw:flex tw:flex-col tw:sm:flex-row tw:gap-md">
               <div className="tw:flex-1">
@@ -295,8 +283,7 @@ export default function BrandWritingPage() {
           <div className="tw:mb-xl">
             <RuleTitle>Proper nouns stay capitalized</RuleTitle>
             <RuleDescription>
-              Brand names, acronyms, and proper nouns keep their
-              capitalization.
+              Brand names, acronyms, and proper nouns keep their capitalization.
             </RuleDescription>
             <div className="tw:flex tw:flex-col tw:sm:flex-row tw:gap-md">
               <div className="tw:flex-1">
@@ -342,9 +329,7 @@ export default function BrandWritingPage() {
               <li style={{ marginBottom: spacing.xs }}>Navigation labels</li>
               <li style={{ marginBottom: spacing.xs }}>Button text</li>
               <li style={{ marginBottom: spacing.xs }}>Form labels</li>
-              <li style={{ marginBottom: spacing.xs }}>
-                Documentation titles
-              </li>
+              <li style={{ marginBottom: spacing.xs }}>Documentation titles</li>
               <li style={{ marginBottom: spacing.xs }}>Blog post titles</li>
               <li style={{ marginBottom: spacing.xs }}>Error messages</li>
             </ul>
@@ -371,8 +356,8 @@ export default function BrandWritingPage() {
           <div className="tw:mb-xl">
             <RuleTitle>Use active voice</RuleTitle>
             <RuleDescription>
-              Write in active voice. The subject should perform the action,
-              not receive it.
+              Write in active voice. The subject should perform the action, not
+              receive it.
             </RuleDescription>
             <div className="tw:flex tw:flex-col tw:sm:flex-row tw:gap-md">
               <div className="tw:flex-1">
@@ -438,9 +423,9 @@ export default function BrandWritingPage() {
           <div className="tw:mb-xl">
             <RuleTitle>Present numbers dispassionately</RuleTitle>
             <RuleDescription>
-              When presenting results from PolicyEngine, let the data speak
-              for itself. Avoid adjectives or adverbs that aren&apos;t backed
-              by the numbers themselves.
+              When presenting results from PolicyEngine, let the data speak for
+              itself. Avoid adjectives or adverbs that aren&apos;t backed by the
+              numbers themselves.
             </RuleDescription>
             <div className="tw:flex tw:flex-col tw:sm:flex-row tw:gap-md">
               <div className="tw:flex-1">
@@ -454,13 +439,11 @@ export default function BrandWritingPage() {
               </div>
               <div className="tw:flex-1">
                 <ExampleBox type="bad">
-                  The policy dramatically slashes poverty by an impressive
-                  15%.
+                  The policy dramatically slashes poverty by an impressive 15%.
                   <br />
                   Benefits skyrocket by a remarkable $2,400/year.
                   <br />
-                  The reform has a surprisingly modest cost of just $80
-                  billion.
+                  The reform has a surprisingly modest cost of just $80 billion.
                 </ExampleBox>
               </div>
             </div>
diff --git a/website/src/app/[countryId]/citations/CitationsClient.tsx b/website/src/app/[countryId]/citations/CitationsClient.tsx
index 65ee5e3c7..4c8e6a58a 100644
--- a/website/src/app/[countryId]/citations/CitationsClient.tsx
+++ b/website/src/app/[countryId]/citations/CitationsClient.tsx
@@ -6,11 +6,7 @@ import OptimisedImage from "@/components/ui/OptimisedImage";
 import { Container } from "@/components/ui/Container";
 import { Text } from "@/components/ui/Text";
 import citationsData from "@/data/citations.json";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 interface Citation {
   /** Headline or title of the citing article */
@@ -72,7 +68,7 @@ function CitationCard({
           border: `1px solid ${colors.border.light}`,
           transition: "box-shadow 0.2s ease, transform 0.2s ease",
           cursor: "pointer",
-          backgroundColor: colors.white,
+          backgroundColor: colors.background.elevated,
           height: "100%",
           display: "flex",
           flexDirection: "column",
@@ -85,7 +81,7 @@ function CitationCard({
             flex: large ? "1 1 0" : undefined,
             aspectRatio: large ? undefined : "16 / 9",
             minHeight: large ? "200px" : undefined,
-            backgroundColor: colors.gray[100],
+            backgroundColor: colors.background.secondary,
             overflow: "hidden",
           }}
         >
@@ -106,7 +102,7 @@ function CitationCard({
                 parent.style.alignItems = "center";
                 parent.style.justifyContent = "center";
                 parent.style.padding = "24px";
-                parent.innerHTML = `<span style="color: ${colors.gray[400]}; font-family: ${typography.fontFamily.primary}; font-size: 18px; font-weight: 600; text-align: center;">${citation.outlet}</span>`;
+                parent.innerHTML = `<span style="color: ${colors.text.tertiary}; font-family: ${typography.fontFamily.primary}; font-size: 18px; font-weight: 600; text-align: center;">${citation.outlet}</span>`;
               }
             }}
           />
@@ -127,7 +123,7 @@ function CitationCard({
           <Text
             size={large ? "md" : "sm"}
             style={{
-              color: colors.gray[800],
+              color: colors.text.primary,
               fontWeight: large ? 600 : 500,
               lineHeight: 1.4,
               marginBottom: spacing.sm,
@@ -139,7 +135,7 @@ function CitationCard({
           >
             {citation.title}
           </Text>
-          <Text size="xs" style={{ color: colors.gray[400] }}>
+          <Text size="xs" style={{ color: colors.text.tertiary }}>
             {formatDate(citation.date)}
           </Text>
         </div>
@@ -176,8 +172,10 @@ function LocationFilter({
               padding: `${spacing.xs} ${spacing.md}`,
               borderRadius: "999px",
               border: `1px solid ${isActive ? colors.primary[500] : colors.border.light}`,
-              backgroundColor: isActive ? colors.primary[500] : colors.white,
-              color: isActive ? colors.white : colors.gray[600],
+              backgroundColor: isActive
+                ? colors.primary[500]
+                : colors.background.elevated,
+              color: isActive ? colors.text.inverse : colors.text.secondary,
               fontSize: "14px",
               fontFamily: typography.fontFamily.primary,
               fontWeight: isActive ? 600 : 400,
@@ -302,11 +300,13 @@ export default function CitationsClient({ countryId }: { countryId: string }) {
             className="tw:text-center"
             style={{
               padding: spacing["3xl"],
-              backgroundColor: colors.gray[50],
+              backgroundColor: colors.background.secondary,
               borderRadius: spacing.radius.container,
             }}
           >
-            <Text style={{ color: colors.gray[500] }}>No citations yet.</Text>
+            <Text style={{ color: colors.text.secondary }}>
+              No citations yet.
+            </Text>
           </div>
         ) : (
           <>
@@ -317,7 +317,7 @@ export default function CitationsClient({ countryId }: { countryId: string }) {
                   size="lg"
                   style={{
                     fontWeight: 600,
-                    color: colors.gray[800],
+                    color: colors.text.primary,
                     marginBottom: spacing.xl,
                   }}
                 >
@@ -334,7 +334,7 @@ export default function CitationsClient({ countryId }: { countryId: string }) {
                   size="lg"
                   style={{
                     fontWeight: 600,
-                    color: colors.gray[800],
+                    color: colors.text.primary,
                     marginBottom: spacing.xl,
                   }}
                 >
diff --git a/website/src/app/[countryId]/claude-plugin/ClaudePluginClient.tsx b/website/src/app/[countryId]/claude-plugin/ClaudePluginClient.tsx
index 9d7ea4be1..d84395413 100644
--- a/website/src/app/[countryId]/claude-plugin/ClaudePluginClient.tsx
+++ b/website/src/app/[countryId]/claude-plugin/ClaudePluginClient.tsx
@@ -1,11 +1,7 @@
 "use client";
 
 import { useEffect, useRef, useState } from "react";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 /* ─── animation hook ─── */
 
@@ -438,7 +434,7 @@ export default function ClaudePluginClient({
         style={{
           paddingTop: 80,
           paddingBottom: 80,
-          backgroundColor: colors.white,
+          backgroundColor: colors.background.primary,
           ...SECTION_PX,
           borderBottom: `1px solid ${colors.border.light}`,
           overflow: "hidden",
@@ -478,7 +474,7 @@ export default function ClaudePluginClient({
                     fontSize: "clamp(32px, 4.5vw, 48px)",
                     fontWeight: typography.fontWeight.bold,
                     fontFamily: typography.fontFamily.primary,
-                    color: colors.gray[900],
+                    color: colors.text.primary,
                     lineHeight: 1.08,
                     letterSpacing: "-0.03em",
                     marginBottom: spacing.lg,
@@ -512,7 +508,7 @@ export default function ClaudePluginClient({
                   style={{
                     display: "inline-block",
                     backgroundColor: colors.primary[500],
-                    color: colors.white,
+                    color: colors.text.inverse,
                     fontFamily: typography.fontFamily.primary,
                     fontWeight: typography.fontWeight.semibold,
                     fontSize: typography.fontSize.sm,
@@ -586,7 +582,7 @@ export default function ClaudePluginClient({
         style={{
           paddingTop: spacing["4xl"],
           paddingBottom: spacing["4xl"],
-          backgroundColor: colors.gray[50],
+          backgroundColor: colors.background.secondary,
           ...SECTION_PX,
           borderBottom: `1px solid ${colors.border.light}`,
         }}
@@ -619,7 +615,7 @@ export default function ClaudePluginClient({
                     border: `1px solid ${colors.border.light}`,
                     borderRadius: spacing.md,
                     padding: spacing.xl,
-                    backgroundColor: colors.white,
+                    backgroundColor: colors.background.elevated,
                     display: "flex",
                     flexDirection: "column",
                     height: "100%",
@@ -663,7 +659,7 @@ export default function ClaudePluginClient({
         style={{
           paddingTop: spacing["4xl"],
           paddingBottom: spacing["4xl"],
-          backgroundColor: colors.white,
+          backgroundColor: colors.background.primary,
           ...SECTION_PX,
           borderBottom: `1px solid ${colors.border.light}`,
         }}
@@ -704,7 +700,7 @@ export default function ClaudePluginClient({
                   width: "100%",
                   borderRadius: "12px",
                   overflow: "hidden",
-                  boxShadow: "0 8px 32px -4px rgba(0,0,0,0.12)",
+                  boxShadow: `0 8px 32px -4px ${colors.shadow.medium}`,
                 }}
               >
                 <video
@@ -750,7 +746,7 @@ export default function ClaudePluginClient({
         style={{
           paddingTop: spacing["4xl"],
           paddingBottom: spacing["4xl"],
-          backgroundColor: colors.white,
+          backgroundColor: colors.background.primary,
           ...SECTION_PX,
           borderBottom: `1px solid ${colors.border.light}`,
         }}
@@ -862,7 +858,7 @@ export default function ClaudePluginClient({
                 fontFamily: typography.fontFamily.primary,
                 fontWeight: typography.fontWeight.bold,
                 fontSize: typography.fontSize["3xl"],
-                color: colors.white,
+                color: colors.text.inverse,
                 textAlign: "center",
                 marginBottom: spacing["3xl"],
               }}
@@ -912,7 +908,7 @@ export default function ClaudePluginClient({
                       fontWeight: typography.fontWeight.semibold,
                       fontFamily: typography.fontFamily.primary,
                       fontSize: typography.fontSize.sm,
-                      color: colors.white,
+                      color: colors.text.inverse,
                       marginBottom: 4,
                     }}
                   >
diff --git a/website/src/app/[countryId]/dev-tools/api-status/ApiStatusClient.tsx b/website/src/app/[countryId]/dev-tools/api-status/ApiStatusClient.tsx
index 2a8ab5526..4837fc19b 100644
--- a/website/src/app/[countryId]/dev-tools/api-status/ApiStatusClient.tsx
+++ b/website/src/app/[countryId]/dev-tools/api-status/ApiStatusClient.tsx
@@ -6,7 +6,13 @@ import {
   IconCircleCheck,
   IconCircleX,
 } from "@tabler/icons-react";
-import { Alert, AlertDescription, AlertTitle, Spinner, Text } from "@/components/ui";
+import {
+  Alert,
+  AlertDescription,
+  AlertTitle,
+  Spinner,
+  Text,
+} from "@/components/ui";
 import { colors, spacing, typography } from "@/designTokens";
 import type {
   DayRecord,
@@ -42,24 +48,33 @@ function getAggregateStatus(monitors: MonitorData[]): AggregateStatus {
 
 const STATUS_CONFIG: Record<
   AggregateStatus,
-  { label: string; bg: string; text: string; icon: typeof IconCircleCheck }
+  {
+    label: string;
+    bg: string;
+    text: string;
+    border: string;
+    icon: typeof IconCircleCheck;
+  }
 > = {
   operational: {
     label: "All systems operational",
-    bg: colors.primary[50],
-    text: colors.primary[700],
+    bg: colors.background.accent,
+    text: colors.text.link,
+    border: colors.border.light,
     icon: IconCircleCheck,
   },
   degraded: {
     label: "Some systems experiencing issues",
-    bg: "#FEF9E7",
-    text: "#92400E",
+    bg: colors.background.elevated,
+    text: colors.warning,
+    border: colors.warning,
     icon: IconAlertTriangle,
   },
   down: {
     label: "System outage detected",
-    bg: "#FEF2F2",
-    text: "#991B1B",
+    bg: colors.background.elevated,
+    text: colors.error,
+    border: colors.error,
     icon: IconCircleX,
   },
 };
@@ -96,7 +111,7 @@ const COLOR_STOPS: RGB[] = [
   hexToRgb(colors.error),
 ];
 
-const NO_DATA_COLOR = colors.gray[200];
+const NO_DATA_COLOR = colors.border.medium;
 
 function colorForDay(day: DayRecord): string {
   if (day.status === "no-data") {
@@ -149,9 +164,7 @@ function formatDowntime(minutes: number): string {
 
   const hours = Math.floor(minutes / 60);
   const remainingMinutes = Math.round(minutes % 60);
-  return remainingMinutes > 0
-    ? `${hours}h ${remainingMinutes}m`
-    : `${hours}h`;
+  return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
 }
 
 function formatDate(dateStr: string): string {
@@ -175,9 +188,10 @@ function formatLastUpdated(timestamp: string): string {
   });
 }
 
-function formatMonitorStatus(
-  status: MonitorStatus,
-): { label: string; color: string } {
+function formatMonitorStatus(status: MonitorStatus): {
+  label: string;
+  color: string;
+} {
   if (status === "up") {
     return { label: "Operational", color: colors.primary[500] };
   }
@@ -215,7 +229,7 @@ function AggregateStatusBanner({ monitors }: { monitors: MonitorData[] }) {
       style={{
         backgroundColor: config.bg,
         padding: spacing["2xl"],
-        border: `1px solid ${colors.border.light}`,
+        border: `1px solid ${config.border}`,
         borderRadius: spacing.radius.container,
       }}
     >
@@ -268,12 +282,11 @@ function DayBar({ day }: { day: DayRecord }) {
             bottom: "calc(100% + 8px)",
             left: "50%",
             transform: "translateX(-50%)",
-            background: colors.white,
-            border: `1px solid ${colors.gray[200]}`,
+            background: colors.background.elevated,
+            border: `1px solid ${colors.border.light}`,
             borderRadius: spacing.radius.element,
             padding: `${spacing.sm} ${spacing.md}`,
-            boxShadow:
-              "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
+            boxShadow: `0 8px 20px ${colors.shadow.medium}`,
             zIndex: 50,
             whiteSpace: "nowrap",
             pointerEvents: "none",
@@ -385,7 +398,7 @@ function MonitorRow({ monitor }: { monitor: MonitorData }) {
   return (
     <div
       style={{
-        backgroundColor: colors.white,
+        backgroundColor: colors.background.elevated,
         border: `1px solid ${colors.border.light}`,
         borderRadius: spacing.radius.container,
         padding: spacing["2xl"],
@@ -457,7 +470,9 @@ function useStatusData(): {
         const response = await fetch(
           `/api/betterstack?monitors=${MONITOR_IDS.join(",")}`,
         );
-        const data = (await response.json()) as StatusPageData | { error: string };
+        const data = (await response.json()) as
+          | StatusPageData
+          | { error: string };
 
         if (!response.ok) {
           throw new Error(
diff --git a/website/src/app/[countryId]/dev-tools/page.tsx b/website/src/app/[countryId]/dev-tools/page.tsx
index cda6b9d68..9d2457c2e 100644
--- a/website/src/app/[countryId]/dev-tools/page.tsx
+++ b/website/src/app/[countryId]/dev-tools/page.tsx
@@ -17,7 +17,7 @@ function DevToolCard({ href, title, description }: DevToolCardProps) {
       className="tw:block tw:no-underline tw:transition-all tw:duration-200 tw:hover:-translate-y-0.5"
       style={{
         padding: spacing["2xl"],
-        background: colors.white,
+        background: colors.background.elevated,
         border: `1px solid ${colors.border.light}`,
         borderRadius: spacing.radius.container,
       }}
diff --git a/website/src/app/[countryId]/research/ResearchClient.tsx b/website/src/app/[countryId]/research/ResearchClient.tsx
index b13bdef78..c3bc8073e 100644
--- a/website/src/app/[countryId]/research/ResearchClient.tsx
+++ b/website/src/app/[countryId]/research/ResearchClient.tsx
@@ -25,11 +25,7 @@ import {
   IconChevronDown,
   IconSearch,
 } from "@tabler/icons-react";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 import {
   Button,
   Checkbox,
@@ -143,150 +139,165 @@ function BlogPostCard({
   // <a> to force a full server request instead of client-side routing.
   const cardClassName = "tw:no-underline tw:text-inherit tw:group";
   const cardContent = (
-      <div className="tw:flex tw:flex-col tw:h-full tw:rounded-xl tw:overflow-hidden tw:bg-white tw:transition-all tw:duration-300 tw:ease-out tw:border tw:border-gray-200 tw:hover:shadow-[0_8px_30px_rgba(0,0,0,0.08)] tw:hover:border-gray-300 tw:hover:-translate-y-0.5">
-        {/* Image */}
-        <div className="tw:relative tw:h-[260px] tw:overflow-hidden tw:bg-gray-100">
-          {item.image && (
-            <OptimisedImage
-              src={
-                item.image.startsWith("http")
-                  ? item.image
-                  : `/assets/posts/${item.image}`
-              }
-              alt={item.title}
-              width={640}
-              className="tw:w-full tw:h-full tw:object-cover tw:transition-transform tw:duration-500 tw:ease-out tw:group-hover:scale-105"
-              onError={(e) => {
-                e.currentTarget.style.display = "none";
-              }}
-            />
-          )}
-          {/* Gradient overlay at bottom of image for depth */}
-          <div
-            style={{
-              position: "absolute",
-              bottom: 0,
-              left: 0,
-              right: 0,
-              height: "40px",
-              background: "linear-gradient(transparent, rgba(0,0,0,0.04))",
-              pointerEvents: "none",
+    <div
+      className="tw:flex tw:flex-col tw:h-full tw:rounded-xl tw:overflow-hidden tw:transition-all tw:duration-300 tw:ease-out tw:hover:shadow-lg tw:hover:-translate-y-0.5"
+      style={{
+        backgroundColor: colors.background.elevated,
+        border: `1px solid ${colors.border.light}`,
+        boxShadow: `0 1px 2px ${colors.shadow.light}`,
+      }}
+    >
+      {/* Image */}
+      <div className="tw:relative tw:h-[260px] tw:overflow-hidden tw:bg-gray-100">
+        {item.image && (
+          <OptimisedImage
+            src={
+              item.image.startsWith("http")
+                ? item.image
+                : `/assets/posts/${item.image}`
+            }
+            alt={item.title}
+            width={640}
+            className="tw:w-full tw:h-full tw:object-cover tw:transition-transform tw:duration-500 tw:ease-out tw:group-hover:scale-105"
+            onError={(e) => {
+              e.currentTarget.style.display = "none";
             }}
           />
-        </div>
+        )}
+        {/* Gradient overlay at bottom of image for depth */}
+        <div
+          style={{
+            position: "absolute",
+            bottom: 0,
+            left: 0,
+            right: 0,
+            height: "40px",
+            background: "linear-gradient(transparent, rgba(0,0,0,0.04))",
+            pointerEvents: "none",
+          }}
+        />
+      </div>
 
-        {/* Content */}
+      {/* Content */}
+      <div
+        style={{
+          padding: "16px 18px",
+          flex: 1,
+          display: "flex",
+          flexDirection: "column",
+        }}
+      >
+        {/* Tags + Date row */}
         <div
           style={{
-            padding: "16px 18px",
-            flex: 1,
             display: "flex",
-            flexDirection: "column",
+            alignItems: "center",
+            justifyContent: "space-between",
+            marginBottom: "10px",
+            fontSize: "11px",
+            fontFamily: typography.fontFamily.primary,
+            fontWeight: typography.fontWeight.medium,
+            color: colors.text.tertiary,
+            letterSpacing: "0.03em",
+            textTransform: "uppercase",
           }}
         >
-          {/* Tags + Date row */}
-          <div
-            style={{
-              display: "flex",
-              alignItems: "center",
-              justifyContent: "space-between",
-              marginBottom: "10px",
-              fontSize: "11px",
-              fontFamily: typography.fontFamily.primary,
-              fontWeight: typography.fontWeight.medium,
-              color: colors.gray[500],
-              letterSpacing: "0.03em",
-              textTransform: "uppercase",
-            }}
-          >
-            <div style={{ display: "flex", alignItems: "center" }}>
-              {displayTags.map((tag, i) => (
-                <span
-                  key={tag}
-                  style={{ display: "inline-flex", alignItems: "center" }}
-                >
-                  {tag}
-                  {i < displayTags.length - 1 && (
-                    <span
-                      style={{
-                        margin: "0 8px",
-                        color: colors.gray[400],
-                        fontSize: "9px",
-                      }}
-                    >
-                      &#9679;
-                    </span>
-                  )}
-                </span>
-              ))}
-            </div>
-            <span style={{ flexShrink: 0 }}>{formattedDate}</span>
+          <div style={{ display: "flex", alignItems: "center" }}>
+            {displayTags.map((tag, i) => (
+              <span
+                key={tag}
+                style={{ display: "inline-flex", alignItems: "center" }}
+              >
+                {tag}
+                {i < displayTags.length - 1 && (
+                  <span
+                    style={{
+                      margin: "0 8px",
+                      color: colors.border.medium,
+                      fontSize: "9px",
+                    }}
+                  >
+                    &#9679;
+                  </span>
+                )}
+              </span>
+            ))}
           </div>
+          <span style={{ flexShrink: 0 }}>{formattedDate}</span>
+        </div>
 
-          {/* Title */}
-          <p
-            style={{
-              fontWeight: typography.fontWeight.semibold,
-              fontSize: "15.5px",
-              lineHeight: "1.4",
-              color: colors.secondary[900],
-              marginBottom: "8px",
-              fontFamily: typography.fontFamily.primary,
-              display: "-webkit-box",
-              WebkitLineClamp: 2,
-              WebkitBoxOrient: "vertical",
-              overflow: "hidden",
-              letterSpacing: "-0.01em",
-            }}
-          >
-            {item.title}
-          </p>
+        {/* Title */}
+        <p
+          style={{
+            fontWeight: typography.fontWeight.semibold,
+            fontSize: "15.5px",
+            lineHeight: "1.4",
+            color: colors.text.primary,
+            marginBottom: "8px",
+            fontFamily: typography.fontFamily.primary,
+            display: "-webkit-box",
+            WebkitLineClamp: 2,
+            WebkitBoxOrient: "vertical",
+            overflow: "hidden",
+            letterSpacing: "-0.01em",
+          }}
+        >
+          {item.title}
+        </p>
 
-          {/* Description */}
-          <Text
-            size="sm"
-            style={{
-              color: colors.text.secondary,
-              flex: 1,
-              display: "-webkit-box",
-              WebkitLineClamp: 3,
-              WebkitBoxOrient: "vertical",
-              overflow: "hidden",
-              lineHeight: "1.6",
-            }}
-          >
-            {item.description}
-          </Text>
+        {/* Description */}
+        <Text
+          size="sm"
+          style={{
+            color: colors.text.secondary,
+            flex: 1,
+            display: "-webkit-box",
+            WebkitLineClamp: 3,
+            WebkitBoxOrient: "vertical",
+            overflow: "hidden",
+            lineHeight: "1.6",
+          }}
+        >
+          {item.description}
+        </Text>
 
-          {/* CTA */}
-          <div
-            style={{
-              display: "flex",
-              alignItems: "center",
-              justifyContent: "flex-end",
-              gap: "4px",
-              marginTop: "12px",
-              color: colors.primary[600],
-              fontFamily: typography.fontFamily.primary,
-              fontWeight: typography.fontWeight.medium,
-              fontSize: "13.5px",
-            }}
-            className="tw:transition-all tw:duration-200 tw:group-hover:gap-2"
-          >
-            <span>{item.isApp ? "Open" : "Read more"}</span>
-            <IconArrowRight
-              size={15}
-              className="tw:transition-transform tw:duration-200 tw:group-hover:translate-x-0.5"
-            />
-          </div>
+        {/* CTA */}
+        <div
+          style={{
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "flex-end",
+            gap: "4px",
+            marginTop: "12px",
+            color: colors.text.link,
+            fontFamily: typography.fontFamily.primary,
+            fontWeight: typography.fontWeight.medium,
+            fontSize: "13.5px",
+          }}
+          className="tw:transition-all tw:duration-200 tw:group-hover:gap-2"
+        >
+          <span>{item.isApp ? "Open" : "Read more"}</span>
+          <IconArrowRight
+            size={15}
+            className="tw:transition-transform tw:duration-200 tw:group-hover:translate-x-0.5"
+          />
         </div>
       </div>
+    </div>
   );
 
   if (item.isApp) {
-    return <a href={link} className={cardClassName}>{cardContent}</a>;
+    return (
+      <a href={link} className={cardClassName}>
+        {cardContent}
+      </a>
+    );
   }
-  return <Link href={link} className={cardClassName}>{cardContent}</Link>;
+  return (
+    <Link href={link} className={cardClassName}>
+      {cardContent}
+    </Link>
+  );
 }
 
 /* ─── BlogPostGrid ─── */
@@ -416,7 +427,9 @@ function FilterSection({
       style={{
         borderRadius: "12px",
         border: `1px solid ${isExpanded ? colors.primary[200] : colors.border.light}`,
-        backgroundColor: isExpanded ? "rgba(230, 255, 250, 0.3)" : colors.white,
+        backgroundColor: isExpanded
+          ? colors.background.accent
+          : colors.background.elevated,
         transition: "border-color 0.2s ease, background-color 0.2s ease",
         overflow: "hidden",
         // Collapsed sections must keep their full header height when a sibling
@@ -434,7 +447,7 @@ function FilterSection({
         onClick={onToggle}
         onMouseEnter={(e) => {
           if (!isExpanded) {
-            e.currentTarget.style.backgroundColor = colors.gray[50];
+            e.currentTarget.style.backgroundColor = colors.background.hover;
           }
         }}
         onMouseLeave={(e) => {
@@ -448,9 +461,7 @@ function FilterSection({
             fw={typography.fontWeight.semibold}
             size="sm"
             style={{
-              color: isExpanded
-                ? colors.primary[700]
-                : colors.secondary[800],
+              color: isExpanded ? colors.text.link : colors.text.primary,
             }}
           >
             {label}
@@ -465,7 +476,7 @@ function FilterSection({
                 height: "20px",
                 borderRadius: "10px",
                 backgroundColor: colors.primary[500],
-                color: colors.white,
+                color: colors.text.inverse,
                 fontSize: "11px",
                 fontWeight: typography.fontWeight.bold,
                 fontFamily: typography.fontFamily.primary,
@@ -478,7 +489,7 @@ function FilterSection({
         </div>
         <IconChevronDown
           size={16}
-          color={isExpanded ? colors.primary[600] : colors.text.tertiary}
+          color={isExpanded ? colors.text.link : colors.text.tertiary}
           style={{
             transition: "transform 0.25s cubic-bezier(0.4, 0, 0.2, 1)",
             transform: isExpanded ? "rotate(180deg)" : "rotate(0deg)",
@@ -488,9 +499,7 @@ function FilterSection({
 
       <div
         style={{
-          maxHeight: isExpanded
-            ? `${Math.min(height, maxHeight)}px`
-            : "0px",
+          maxHeight: isExpanded ? `${Math.min(height, maxHeight)}px` : "0px",
           opacity: isExpanded ? 1 : 0,
           transition:
             "max-height 0.3s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.2s ease",
@@ -525,7 +534,12 @@ function CheckboxRow({
       role="button"
       tabIndex={0}
       onClick={onChange}
-      onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onChange(); } }}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          onChange();
+        }
+      }}
       style={{
         display: "flex",
         alignItems: "center",
@@ -541,7 +555,7 @@ function CheckboxRow({
         textAlign: "left",
       }}
       onMouseEnter={(e) => {
-        e.currentTarget.style.backgroundColor = colors.gray[50];
+        e.currentTarget.style.backgroundColor = colors.background.hover;
       }}
       onMouseLeave={(e) => {
         e.currentTarget.style.backgroundColor = "transparent";
@@ -558,7 +572,7 @@ function CheckboxRow({
         style={{
           fontSize: "13.5px",
           fontFamily: typography.fontFamily.primary,
-          color: checked ? colors.primary[700] : colors.secondary[700],
+          color: checked ? colors.text.link : colors.text.secondary,
           fontWeight: checked
             ? typography.fontWeight.semibold
             : typography.fontWeight.normal,
@@ -605,8 +619,7 @@ function ResearchFilters({
   availableAuthors,
   countryId = "us",
 }: ResearchFiltersProps) {
-  const [expandedSection, setExpandedSection] =
-    useState<ExpandedSection>(null);
+  const [expandedSection, setExpandedSection] = useState<ExpandedSection>(null);
   const [usStatesExpanded, setUsStatesExpanded] = useState(false);
   const [availableHeight, setAvailableHeight] = useState<number>(400);
   const filterContainerRef = useRef<HTMLDivElement>(null);
@@ -800,11 +813,10 @@ function ResearchFilters({
                         }}
                         onMouseEnter={(e) => {
                           e.currentTarget.style.backgroundColor =
-                            colors.primary[50];
+                            colors.background.accent;
                         }}
                         onMouseLeave={(e) => {
-                          e.currentTarget.style.backgroundColor =
-                            "transparent";
+                          e.currentTarget.style.backgroundColor = "transparent";
                         }}
                       >
                         {usStatesExpanded ? "Hide states" : "Show states"}
@@ -855,11 +867,7 @@ function ResearchFilters({
 
 /* ─── Main Client Component ─── */
 
-export default function ResearchClient({
-  countryId,
-}: {
-  countryId: string;
-}) {
+export default function ResearchClient({ countryId }: { countryId: string }) {
   const searchParams = useSearchParams();
   const router = useRouter();
   const pathname = usePathname();
@@ -869,10 +877,7 @@ export default function ResearchClient({
   const allItems = useMemo(() => getResearchItems(), []);
 
   // Default locations based on country
-  const defaultLocations = useMemo(
-    () => [countryId, "global"],
-    [countryId],
-  );
+  const defaultLocations = useMemo(() => [countryId, "global"], [countryId]);
 
   // Filter state - initialize from URL params
   const [searchQuery, setSearchQuery] = useState(
@@ -1010,25 +1015,19 @@ export default function ResearchClient({
         <div
           style={{
             display: "flex",
-            flexDirection:
-              displayCategory === "desktop" ? "row" : "column",
+            flexDirection: displayCategory === "desktop" ? "row" : "column",
             gap: spacing.xl,
           }}
         >
           {/* Sidebar Filters */}
           <div
             style={{
-              flex:
-                displayCategory === "desktop" ? "0 0 250px" : "1",
-              position:
-                displayCategory === "desktop" ? "sticky" : "static",
-              top:
-                displayCategory === "desktop" ? "100px" : "auto",
+              flex: displayCategory === "desktop" ? "0 0 250px" : "1",
+              position: displayCategory === "desktop" ? "sticky" : "static",
+              top: displayCategory === "desktop" ? "100px" : "auto",
               alignSelf: "flex-start",
               height:
-                displayCategory === "desktop"
-                  ? "calc(100vh - 120px)"
-                  : "auto",
+                displayCategory === "desktop" ? "calc(100vh - 120px)" : "auto",
             }}
           >
             <ResearchFilters
@@ -1053,7 +1052,7 @@ export default function ResearchClient({
             <Text
               size="sm"
               className="tw:mb-md"
-              style={{ color: colors.gray[500] }}
+              style={{ color: colors.text.tertiary }}
             >
               {filteredItems.length}{" "}
               {filteredItems.length === 1 ? "result" : "results"}
@@ -1061,10 +1060,7 @@ export default function ResearchClient({
 
             {filteredItems.length > 0 ? (
               <>
-                <BlogPostGrid
-                  items={visibleItems}
-                  countryId={countryId}
-                />
+                <BlogPostGrid items={visibleItems} countryId={countryId} />
 
                 {/* Sentinel element for infinite scroll */}
                 {hasMore && (
@@ -1082,11 +1078,11 @@ export default function ResearchClient({
                 className="tw:text-center"
                 style={{
                   padding: spacing["3xl"],
-                  backgroundColor: colors.gray[50],
+                  backgroundColor: colors.background.secondary,
                   borderRadius: spacing.radius.container,
                 }}
               >
-                <Text style={{ color: colors.gray[500] }}>
+                <Text style={{ color: colors.text.secondary }}>
                   No results found. Try adjusting your filters.
                 </Text>
               </div>
diff --git a/website/src/app/[countryId]/research/[slug]/ArticleClient.tsx b/website/src/app/[countryId]/research/[slug]/ArticleClient.tsx
index b4e636cb2..870d2c85e 100644
--- a/website/src/app/[countryId]/research/[slug]/ArticleClient.tsx
+++ b/website/src/app/[countryId]/research/[slug]/ArticleClient.tsx
@@ -25,11 +25,7 @@ import {
 } from "@/data/posts/postTransformers";
 import { extractMarkdownFromNotebook } from "@/lib/notebookUtils";
 import authorsData from "@/data/posts/authors.json";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 const authors = authorsData as AuthorsCollection;
 
@@ -90,7 +86,7 @@ export default function ArticleClient({
   return (
     <>
       {/* Header section */}
-      <div style={{ backgroundColor: colors.gray[50] }}>
+      <div style={{ backgroundColor: colors.background.secondary }}>
         <Container
           size="xl"
           style={{
@@ -166,7 +162,7 @@ function PostHeading({
           <Text
             size="md"
             className="tw:uppercase"
-            style={{ letterSpacing: "0.05em", color: colors.gray[500] }}
+            style={{ letterSpacing: "0.05em", color: colors.text.tertiary }}
           >
             {readingTime}
           </Text>
@@ -193,7 +189,7 @@ function PostHeading({
             style={{
               marginTop: spacing["3xl"],
               fontSize: typography.fontSize.xl,
-              color: colors.gray[500],
+              color: colors.text.secondary,
             }}
           >
             {post.description}
@@ -239,7 +235,7 @@ function PostHeading({
       <Text
         size="lg"
         className="tw:mb-lg"
-        style={{ color: colors.gray[500] }}
+        style={{ color: colors.text.secondary }}
       >
         {post.description}
       </Text>
@@ -265,7 +261,7 @@ function PostHeading({
         <Text
           size="md"
           className="tw:uppercase"
-          style={{ letterSpacing: "0.05em", color: colors.gray[500] }}
+          style={{ letterSpacing: "0.05em", color: colors.text.tertiary }}
         >
           {readingTime}
         </Text>
@@ -327,7 +323,7 @@ function PostBody({
               size="sm"
               fw={typography.fontWeight.semibold}
               className="tw:uppercase tw:mb-xs"
-              style={{ letterSpacing: "0.1em", color: colors.primary[600] }}
+              style={{ letterSpacing: "0.1em", color: colors.text.link }}
             >
               Contents
             </Text>
@@ -362,7 +358,7 @@ function PostBody({
               size="sm"
               fw={typography.fontWeight.semibold}
               className="tw:uppercase tw:mb-xs"
-              style={{ letterSpacing: "0.1em", color: colors.primary[600] }}
+              style={{ letterSpacing: "0.1em", color: colors.text.link }}
             >
               Contents
             </Text>
@@ -387,7 +383,7 @@ function PostBody({
           size="sm"
           fw={typography.fontWeight.semibold}
           className="tw:uppercase tw:mb-xs"
-          style={{ letterSpacing: "0.1em", color: colors.primary[600] }}
+          style={{ letterSpacing: "0.1em", color: colors.text.link }}
         >
           Contents
         </Text>
@@ -418,7 +414,7 @@ function Authorship({
       <Link
         href={`/${countryId}/research?authors=${id}`}
         style={{
-          color: colors.primary[600],
+          color: colors.text.link,
           textDecoration: "none",
         }}
       >
@@ -511,14 +507,14 @@ function AuthorSection({
                 <Link
                   href={`/${countryId}/research?authors=${authorId}`}
                   style={{
-                    color: colors.primary[600],
+                    color: colors.text.link,
                     textDecoration: "none",
                   }}
                 >
                   {formatAuthorName(authorId)}
                 </Link>
               </Text>
-              <Text size="xs" style={{ color: colors.gray[500] }}>
+              <Text size="xs" style={{ color: colors.text.tertiary }}>
                 {author.title}
               </Text>
             </div>
@@ -547,7 +543,7 @@ function MoreOn({ post, countryId }: { post: BlogPost; countryId: string }) {
           <Link
             href={`/${countryId}/research?${isLocation ? "locations" : "topics"}=${tag}`}
             style={{
-              color: colors.gray[700],
+              color: colors.text.secondary,
               textDecoration: "none",
               fontSize: typography.fontSize.base,
               transition: "color 0.2s ease",
@@ -555,10 +551,10 @@ function MoreOn({ post, countryId }: { post: BlogPost; countryId: string }) {
               padding: "2px 0",
             }}
             onMouseEnter={(e) => {
-              e.currentTarget.style.color = colors.primary[600];
+              e.currentTarget.style.color = colors.text.link;
             }}
             onMouseLeave={(e) => {
-              e.currentTarget.style.color = colors.gray[700];
+              e.currentTarget.style.color = colors.text.secondary;
             }}
           >
             {label}
@@ -575,7 +571,7 @@ function MoreOn({ post, countryId }: { post: BlogPost; countryId: string }) {
         size="sm"
         fw={typography.fontWeight.semibold}
         className="tw:uppercase tw:mb-xs"
-        style={{ letterSpacing: "0.1em", color: colors.primary[600] }}
+        style={{ letterSpacing: "0.1em", color: colors.text.link }}
       >
         More on
       </Text>
@@ -591,8 +587,7 @@ function ShareLinks({
   post: BlogPost;
   displayCategory: string;
 }) {
-  const currentUrl =
-    typeof window !== "undefined" ? window.location.href : "";
+  const currentUrl = typeof window !== "undefined" ? window.location.href : "";
   const desktop = displayCategory === "desktop";
 
   const links = [
@@ -646,7 +641,7 @@ function ShareLinks({
             display: "flex",
             alignItems: "center",
             gap: spacing.sm,
-            color: colors.gray[600],
+            color: colors.text.secondary,
             textDecoration: "none",
             fontSize: typography.fontSize.xs,
           }}
@@ -659,11 +654,9 @@ function ShareLinks({
               display: "flex",
               alignItems: "center",
               justifyContent: "center",
-              backgroundColor: desktop ? colors.gray[500] : "transparent",
-              color: desktop ? colors.white : colors.gray[600],
-              border: desktop
-                ? "none"
-                : `1px solid ${colors.gray[400]}`,
+              backgroundColor: desktop ? colors.primary[500] : "transparent",
+              color: desktop ? colors.text.inverse : colors.text.secondary,
+              border: desktop ? "none" : `1px solid ${colors.border.medium}`,
               fontSize: typography.fontSize.xs,
               fontWeight: typography.fontWeight.semibold,
             }}
@@ -708,7 +701,7 @@ function LeftContents({ markdown }: { markdown: string }) {
             cursor: "pointer",
             paddingLeft: 8 * (level - 2),
             padding: "2px 0",
-            color: colors.gray[700],
+            color: colors.text.secondary,
             transition: "color 0.2s ease",
           }}
           onClick={() => {
@@ -723,10 +716,10 @@ function LeftContents({ markdown }: { markdown: string }) {
             }
           }}
           onMouseEnter={(e) => {
-            e.currentTarget.style.color = colors.primary[600];
+            e.currentTarget.style.color = colors.text.link;
           }}
           onMouseLeave={(e) => {
-            e.currentTarget.style.color = colors.gray[700];
+            e.currentTarget.style.color = colors.text.secondary;
           }}
         >
           {text}
diff --git a/website/src/app/globals.css b/website/src/app/globals.css
index acf657ad5..2a6a4d55a 100644
--- a/website/src/app/globals.css
+++ b/website/src/app/globals.css
@@ -1,4 +1,4 @@
-@import 'tailwindcss' prefix(tw);
+@import "tailwindcss" prefix(tw);
 @import "@policyengine/ui-kit/styles.css";
 
 @theme {
@@ -83,8 +83,9 @@
   --color-ring: #319795;
 
   /* Typography */
-  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-  --font-mono: 'JetBrains Mono', 'Fira Code', Consolas, monospace;
+  --font-sans:
+    "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  --font-mono: "JetBrains Mono", "Fira Code", Consolas, monospace;
 
   --font-size-xs: 12px;
   --font-size-sm: 14px;
@@ -134,6 +135,112 @@
   --spacing-container: 976px;
 }
 
+:root,
+:root[data-pe-theme="light"] {
+  color-scheme: light;
+  --pe-color-surface-accent: #e6fffa;
+  --pe-color-surface-overlay: rgb(255 255 255 / 0.9);
+  --pe-color-surface-hover: #f9fafb;
+  --pe-shadow-light: rgb(16 24 40 / 0.05);
+  --pe-shadow-medium: rgb(16 24 40 / 0.1);
+  --pe-shadow-dark: rgb(16 24 40 / 0.2);
+
+  /* Compatibility variables for existing arbitrary Tailwind values. */
+  --color-primary-400: var(--tw-color-primary-400);
+  --color-primary-500: var(--tw-color-primary-500);
+  --color-primary-600: var(--tw-color-primary-600);
+}
+
+:root[data-pe-theme="dark"] {
+  color-scheme: dark;
+
+  --tw-color-primary-50: #0f302f;
+  --tw-color-primary-100: #15504e;
+  --tw-color-primary-200: #1f6f6c;
+  --tw-color-primary-300: #2b918d;
+  --tw-color-primary-400: #38b2ac;
+  --tw-color-primary-500: #4fd1c5;
+  --tw-color-primary-600: #63d9cf;
+  --tw-color-primary-700: #81e6d9;
+  --tw-color-primary-800: #b2f5ea;
+  --tw-color-primary-900: #e6fffa;
+
+  --tw-color-secondary-50: #101a1c;
+  --tw-color-secondary-100: #142225;
+  --tw-color-secondary-200: #1e3337;
+  --tw-color-secondary-300: #2b484d;
+  --tw-color-secondary-400: #49666a;
+  --tw-color-secondary-500: #73898b;
+  --tw-color-secondary-600: #9fb0b0;
+  --tw-color-secondary-700: #c5d0cf;
+  --tw-color-secondary-800: #e1e8e7;
+  --tw-color-secondary-900: #f5f8f8;
+
+  --tw-color-gray-50: #0d1719;
+  --tw-color-gray-100: #132124;
+  --tw-color-gray-200: #1d3034;
+  --tw-color-gray-300: #2c454a;
+  --tw-color-gray-400: #587276;
+  --tw-color-gray-500: #8ca0a2;
+  --tw-color-gray-600: #b5c4c5;
+  --tw-color-gray-700: #d3dddc;
+  --tw-color-gray-800: #ebf0ef;
+  --tw-color-gray-900: #f7fafa;
+
+  --tw-color-bg-primary: #071112;
+  --tw-color-bg-secondary: #0d1c1e;
+  --tw-color-bg-tertiary: #13272a;
+  --tw-color-text-primary: #f7fafa;
+  --tw-color-text-secondary: #bdcaca;
+  --tw-color-text-tertiary: #899fa1;
+  --tw-color-text-inverse: #061314;
+  --tw-color-text-link: #63d9cf;
+  --tw-color-text-link-hover: #81e6d9;
+  --tw-color-border-light: #20383c;
+  --tw-color-border-medium: #315257;
+  --tw-color-border-dark: #537276;
+
+  --tw-color-background: #071112;
+  --tw-color-foreground: #f7fafa;
+  --tw-color-primary: #4fd1c5;
+  --tw-color-primary-foreground: #061314;
+  --tw-color-secondary: #132124;
+  --tw-color-secondary-foreground: #f7fafa;
+  --tw-color-muted: #132124;
+  --tw-color-muted-foreground: #bdcaca;
+  --tw-color-accent: #173235;
+  --tw-color-accent-foreground: #f7fafa;
+  --tw-color-popover: #0d1c1e;
+  --tw-color-popover-foreground: #f7fafa;
+  --tw-color-card: #0d1c1e;
+  --tw-color-card-foreground: #f7fafa;
+  --tw-color-border: #20383c;
+  --tw-color-input: #20383c;
+  --tw-color-ring: #4fd1c5;
+
+  --pe-color-surface-accent: #102d2c;
+  --pe-color-surface-overlay: rgb(13 28 30 / 0.9);
+  --pe-color-surface-hover: #173235;
+  --pe-shadow-light: rgb(0 0 0 / 0.28);
+  --pe-shadow-medium: rgb(0 0 0 / 0.36);
+  --pe-shadow-dark: rgb(0 0 0 / 0.48);
+}
+
+:root[data-pe-theme="dark"] .tw\:bg-white {
+  background-color: var(--tw-color-card);
+}
+
+:root[data-pe-theme="dark"] .tw\:text-gray-900,
+:root[data-pe-theme="dark"] .tw\:text-gray-800,
+:root[data-pe-theme="dark"] .tw\:text-gray-700 {
+  color: var(--tw-color-foreground);
+}
+
+:root[data-pe-theme="dark"] .tw\:bg-gray-50,
+:root[data-pe-theme="dark"] .tw\:bg-gray-100 {
+  background-color: var(--tw-color-bg-secondary);
+}
+
 @layer base {
   *,
   ::before,
@@ -166,7 +273,7 @@
     width: 100%;
   }
 
-  [data-slot='table-container'],
+  [data-slot="table-container"],
   tr {
     background-color: var(--tw-color-bg-primary);
   }
@@ -185,13 +292,13 @@
     background-color: var(--tw-color-bg-primary);
   }
 
-  input[type='number']::-webkit-inner-spin-button,
-  input[type='number']::-webkit-outer-spin-button {
+  input[type="number"]::-webkit-inner-spin-button,
+  input[type="number"]::-webkit-outer-spin-button {
     -webkit-appearance: none;
     margin: 0;
   }
 
-  input[type='number'] {
+  input[type="number"] {
     -moz-appearance: textfield;
   }
 }
diff --git a/website/src/app/layout.tsx b/website/src/app/layout.tsx
index 41aaa2447..01bc947bc 100644
--- a/website/src/app/layout.tsx
+++ b/website/src/app/layout.tsx
@@ -2,9 +2,26 @@ import type { Metadata } from "next";
 import Script from "next/script";
 import { Analytics } from "@vercel/analytics/react";
 import { SpeedInsights } from "@vercel/speed-insights/next";
+import { ThemeProvider } from "@/contexts/ThemeContext";
 import "./globals.css";
 
 const GA_MEASUREMENT_ID = "G-2YHG89FY0N";
+const THEME_INIT_SCRIPT = `
+(function() {
+  try {
+    var storedPreference = window.localStorage.getItem('policyengine-theme');
+    var preference = storedPreference === 'light' || storedPreference === 'dark'
+      ? storedPreference
+      : 'system';
+    var theme = preference === 'system'
+      ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+      : preference;
+
+    document.documentElement.dataset.peTheme = theme;
+    document.documentElement.style.colorScheme = theme;
+  } catch (error) {}
+})();
+`;
 
 export const metadata: Metadata = {
   metadataBase: new URL("https://www.policyengine.org"),
@@ -25,8 +42,14 @@ export default function RootLayout({
   children: React.ReactNode;
 }) {
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
       <head>
+        <meta name="color-scheme" content="light dark" />
+        <Script
+          id="theme-init"
+          strategy="beforeInteractive"
+          dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }}
+        />
         <Script
           src={`https://www.googletagmanager.com/gtag/js?id=${GA_MEASUREMENT_ID}`}
           strategy="afterInteractive"
@@ -52,9 +75,11 @@ export default function RootLayout({
           margin: 0,
         }}
       >
-        {children}
-        <Analytics />
-        <SpeedInsights />
+        <ThemeProvider>
+          {children}
+          <Analytics />
+          <SpeedInsights />
+        </ThemeProvider>
       </body>
     </html>
   );
diff --git a/website/src/app/releases/[version]/page.tsx b/website/src/app/releases/[version]/page.tsx
index cacfd5f47..220255e05 100644
--- a/website/src/app/releases/[version]/page.tsx
+++ b/website/src/app/releases/[version]/page.tsx
@@ -1,10 +1,6 @@
 import type { Metadata } from "next";
 import Link from "next/link";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 type ReleasePageProps = {
   params: Promise<{ version: string }>;
@@ -67,7 +63,7 @@ function ExternalLink({
         style={{
           fontSize: typography.fontSize.lg,
           fontWeight: typography.fontWeight.semibold,
-          color: colors.primary[700],
+          color: colors.text.link,
         }}
       >
         {label}
@@ -94,7 +90,7 @@ export default async function ReleasePage({ params }: ReleasePageProps) {
     <main
       style={{
         minHeight: "100vh",
-        backgroundColor: colors.gray[50],
+        backgroundColor: colors.background.tertiary,
         color: colors.text.primary,
         fontFamily: typography.fontFamily.primary,
       }}
@@ -108,7 +104,7 @@ export default async function ReleasePage({ params }: ReleasePageProps) {
         <Link
           href="/us"
           style={{
-            color: colors.white,
+            color: colors.text.inverse,
             fontWeight: typography.fontWeight.semibold,
             textDecoration: "none",
             letterSpacing: "0.01em",
@@ -122,7 +118,7 @@ export default async function ReleasePage({ params }: ReleasePageProps) {
         style={{
           padding: `${spacing["4xl"]} 6.125%`,
           borderBottom: `1px solid ${colors.border.light}`,
-          backgroundColor: colors.white,
+          backgroundColor: colors.background.elevated,
         }}
       >
         <p
@@ -145,7 +141,7 @@ export default async function ReleasePage({ params }: ReleasePageProps) {
             fontSize: "clamp(2.5rem, 7vw, 5.5rem)",
             lineHeight: 0.95,
             letterSpacing: "-0.06em",
-            color: colors.primary[800],
+            color: colors.text.primary,
           }}
         >
           PolicyEngine v{normalizedVersion}
@@ -205,7 +201,7 @@ export default async function ReleasePage({ params }: ReleasePageProps) {
           style={{
             border: `1px solid ${colors.border.light}`,
             borderRadius: spacing.radius.container,
-            backgroundColor: colors.white,
+            backgroundColor: colors.background.elevated,
             overflow: "hidden",
             boxShadow: `0 12px 30px ${colors.shadow.light}`,
           }}
diff --git a/website/src/components/Header.tsx b/website/src/components/Header.tsx
index 4189ba34c..5a39afbd8 100644
--- a/website/src/components/Header.tsx
+++ b/website/src/components/Header.tsx
@@ -9,12 +9,9 @@ import {
   IconWorld,
   IconX,
 } from "@tabler/icons-react";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 import OptimisedImage from "@/components/ui/OptimisedImage";
+import ThemeToggle from "@/components/ThemeToggle";
 import { useCountryId } from "@/hooks/useCountryId";
 
 const PolicyEngineLogo = "/assets/logos/policyengine/white.svg";
@@ -114,12 +111,11 @@ function DropdownPanel({
           transition:
             "max-height 0.3s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.2s ease, transform 0.3s cubic-bezier(0.4, 0, 0.2, 1)",
           borderRadius: "14px",
-          background:
-            "linear-gradient(135deg, rgba(255,255,255,0.97), rgba(240,249,255,0.95))",
+          background: colors.background.overlay,
           backdropFilter: "blur(24px) saturate(200%)",
           WebkitBackdropFilter: "blur(24px) saturate(200%)",
-          boxShadow:
-            "0 20px 60px rgba(0, 0, 0, 0.15), 0 4px 16px rgba(0, 0, 0, 0.06), inset 0 0 0 1px rgba(255, 255, 255, 0.6)",
+          border: `1px solid ${colors.border.light}`,
+          boxShadow: `0 20px 60px ${colors.shadow.medium}, 0 4px 16px ${colors.shadow.light}`,
           zIndex: 1001,
         }}
       >
@@ -140,7 +136,7 @@ function DropdownPanel({
                 fontSize: "14px",
                 fontFamily: typography.fontFamily.primary,
                 fontWeight: typography.fontWeight.semibold,
-                color: colors.primary[800],
+                color: colors.text.primary,
                 transition:
                   "background-color 0.12s ease, color 0.12s ease, opacity 0.3s ease",
                 transitionDelay: visible ? `${i * 50}ms` : "0ms",
@@ -154,7 +150,7 @@ function DropdownPanel({
               }}
               onMouseLeave={(e) => {
                 e.currentTarget.style.backgroundColor = "transparent";
-                e.currentTarget.style.color = colors.primary[800];
+                e.currentTarget.style.color = colors.text.primary;
               }}
             >
               {item.label}
@@ -349,12 +345,11 @@ function CountrySelector() {
               transition:
                 "max-height 0.3s cubic-bezier(0.4, 0, 0.2, 1), opacity 0.2s ease, transform 0.3s cubic-bezier(0.4, 0, 0.2, 1)",
               borderRadius: "14px",
-              background:
-                "linear-gradient(135deg, rgba(255,255,255,0.97), rgba(240,249,255,0.95))",
+              background: colors.background.overlay,
               backdropFilter: "blur(24px) saturate(200%)",
               WebkitBackdropFilter: "blur(24px) saturate(200%)",
-              boxShadow:
-                "0 20px 60px rgba(0, 0, 0, 0.15), 0 4px 16px rgba(0, 0, 0, 0.06), inset 0 0 0 1px rgba(255, 255, 255, 0.6)",
+              border: `1px solid ${colors.border.light}`,
+              boxShadow: `0 20px 60px ${colors.shadow.medium}, 0 4px 16px ${colors.shadow.light}`,
               zIndex: 1001,
             }}
           >
@@ -380,7 +375,7 @@ function CountrySelector() {
                       countryId === country.id
                         ? typography.fontWeight.bold
                         : typography.fontWeight.semibold,
-                    color: colors.primary[800],
+                    color: colors.text.primary,
                     transition:
                       "background-color 0.12s ease, color 0.12s ease, opacity 0.3s ease",
                     transitionDelay: visible ? `${i * 50}ms` : "0ms",
@@ -394,7 +389,7 @@ function CountrySelector() {
                   }}
                   onMouseLeave={(e) => {
                     e.currentTarget.style.backgroundColor = "transparent";
-                    e.currentTarget.style.color = colors.primary[800];
+                    e.currentTarget.style.color = colors.text.primary;
                   }}
                 >
                   {country.label}
@@ -430,7 +425,13 @@ const mobileNavLinkStyle: React.CSSProperties = {
   display: "block",
 };
 
-function MobileNavLink({ item, onClose }: { item: NavItemSetup; onClose: () => void }) {
+function MobileNavLink({
+  item,
+  onClose,
+}: {
+  item: NavItemSetup;
+  onClose: () => void;
+}) {
   const Tag = item.external ? "a" : Link;
   return (
     <Tag href={item.href || "#"} onClick={onClose} style={mobileNavLinkStyle}>
@@ -504,19 +505,24 @@ function MobileMenu({
           >
             Menu
           </span>
-          <button
-            type="button"
-            onClick={onClose}
-            aria-label="Close menu"
-            style={{
-              background: "transparent",
-              border: "none",
-              cursor: "pointer",
-              padding: "4px",
-            }}
+          <div
+            style={{ display: "flex", alignItems: "center", gap: spacing.sm }}
           >
-            <IconX size={20} color={colors.text.inverse} />
-          </button>
+            <ThemeToggle />
+            <button
+              type="button"
+              onClick={onClose}
+              aria-label="Close menu"
+              style={{
+                background: "transparent",
+                border: "none",
+                cursor: "pointer",
+                padding: "4px",
+              }}
+            >
+              <IconX size={20} color={colors.text.inverse} />
+            </button>
+          </div>
         </div>
 
         <div
@@ -585,9 +591,24 @@ export default function Header() {
 
   const navItems: NavItemSetup[] = [
     { label: "Research", href: `/${countryId}/research`, hasDropdown: false },
-    { label: "Model", href: `/${countryId}/model`, hasDropdown: false, external: true },
-    { label: "API", href: `/${countryId}/api`, hasDropdown: false, external: true },
-    { label: "Python", href: `/${countryId}/python`, hasDropdown: false, external: true },
+    {
+      label: "Model",
+      href: `/${countryId}/model`,
+      hasDropdown: false,
+      external: true,
+    },
+    {
+      label: "API",
+      href: `/${countryId}/api`,
+      hasDropdown: false,
+      external: true,
+    },
+    {
+      label: "Python",
+      href: `/${countryId}/python`,
+      hasDropdown: false,
+      external: true,
+    },
     {
       label: "About",
       hasDropdown: true,
@@ -660,7 +681,11 @@ export default function Header() {
         </div>
 
         {/* Right: country selector (desktop) */}
-        <div className="tw:hidden tw:lg:flex" style={{ alignItems: "center" }}>
+        <div
+          className="tw:hidden tw:lg:flex"
+          style={{ alignItems: "center", gap: spacing.sm }}
+        >
+          <ThemeToggle />
           <CountrySelector />
         </div>
 
@@ -670,6 +695,7 @@ export default function Header() {
           className="tw:flex tw:lg:hidden"
           style={{ alignItems: "center", gap: spacing.md }}
         >
+          <ThemeToggle />
           <CountrySelector />
           <button
             type="button"
diff --git a/website/src/components/ThemeToggle.tsx b/website/src/components/ThemeToggle.tsx
new file mode 100644
index 000000000..edb1b425c
--- /dev/null
+++ b/website/src/components/ThemeToggle.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import { IconMoon, IconSun } from "@tabler/icons-react";
+import { colors, spacing } from "@/designTokens";
+import { useTheme } from "@/contexts/ThemeContext";
+
+const buttonSize = 32;
+
+export default function ThemeToggle() {
+  const { resolvedTheme, toggleTheme } = useTheme();
+  const isDark = resolvedTheme === "dark";
+  const label = isDark ? "Switch to light mode" : "Switch to dark mode";
+  const Icon = isDark ? IconSun : IconMoon;
+
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      aria-pressed={isDark}
+      title={label}
+      onClick={toggleTheme}
+      style={{
+        width: buttonSize,
+        height: buttonSize,
+        borderRadius: spacing.radius.container,
+        border: `1px solid ${colors.primary.alpha[40]}`,
+        background: "rgba(255, 255, 255, 0.1)",
+        color: colors.text.inverse,
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        cursor: "pointer",
+        transition: "background-color 0.15s ease, border-color 0.15s ease",
+      }}
+      onMouseEnter={(event) => {
+        event.currentTarget.style.backgroundColor = "rgba(255, 255, 255, 0.18)";
+        event.currentTarget.style.borderColor = colors.primary[300];
+      }}
+      onMouseLeave={(event) => {
+        event.currentTarget.style.backgroundColor = "rgba(255, 255, 255, 0.1)";
+        event.currentTarget.style.borderColor = colors.primary.alpha[40];
+      }}
+    >
+      <Icon size={18} aria-hidden="true" />
+    </button>
+  );
+}
diff --git a/website/src/components/blog/LazyPlot.tsx b/website/src/components/blog/LazyPlot.tsx
index d77f36e21..0ba6e860b 100644
--- a/website/src/components/blog/LazyPlot.tsx
+++ b/website/src/components/blog/LazyPlot.tsx
@@ -17,7 +17,7 @@ const Plot = dynamic(() => import("react-plotly.js"), {
         display: "flex",
         alignItems: "center",
         justifyContent: "center",
-        color: colors.gray[400],
+        color: colors.text.tertiary,
       }}
     >
       Loading chart…
diff --git a/website/src/components/blog/blogStyles.ts b/website/src/components/blog/blogStyles.ts
index 3b3b702a5..e6187ce95 100644
--- a/website/src/components/blog/blogStyles.ts
+++ b/website/src/components/blog/blogStyles.ts
@@ -4,38 +4,34 @@
  * for markdown rendering in blog posts.
  */
 
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 export const blogColors = {
   primary: colors.primary[600],
-  primaryLight: colors.primary[100],
+  primaryLight: colors.background.accent,
   primaryHover: colors.primary[700],
 
-  textPrimary: colors.gray[800],
-  textSecondary: colors.gray[600],
-  textTertiary: colors.gray[500],
-  textHeading: colors.gray[900],
-  textHeading2: colors.gray[800],
-  textHeading3: colors.gray[700],
-  textHeading4: colors.gray[600],
+  textPrimary: colors.text.primary,
+  textSecondary: colors.text.secondary,
+  textTertiary: colors.text.tertiary,
+  textHeading: colors.text.title,
+  textHeading2: colors.text.title,
+  textHeading3: colors.text.primary,
+  textHeading4: colors.text.secondary,
 
-  backgroundPrimary: colors.white,
-  backgroundSecondary: colors.gray[50],
-  backgroundCode: colors.gray[100],
-  backgroundCodeLabel: colors.gray[100],
-  backgroundTable: colors.gray[100],
+  backgroundPrimary: colors.background.primary,
+  backgroundSecondary: colors.background.secondary,
+  backgroundCode: colors.background.tertiary,
+  backgroundCodeLabel: colors.background.tertiary,
+  backgroundTable: colors.background.secondary,
 
-  borderLight: colors.gray[100],
-  borderMedium: colors.gray[200],
-  borderDark: colors.gray[300],
+  borderLight: colors.border.light,
+  borderMedium: colors.border.medium,
+  borderDark: colors.border.dark,
 
   link: colors.primary[600],
   linkHover: colors.primary[700],
-  anchorLink: colors.gray[400],
+  anchorLink: colors.text.tertiary,
 } as const;
 
 export const blogTypography = {
diff --git a/website/src/components/home/HeroSection.tsx b/website/src/components/home/HeroSection.tsx
index fb56d7b40..f93346d0b 100644
--- a/website/src/components/home/HeroSection.tsx
+++ b/website/src/components/home/HeroSection.tsx
@@ -2,11 +2,7 @@
 
 import { useCallback, useMemo, useRef, useState } from "react";
 import { motion, useReducedMotion } from "framer-motion";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 import HeroCTA from "./HeroCTA";
 import HouseholdGraph, {
   generateGraph,
@@ -93,7 +89,7 @@ export default function HeroSection({ countryId }: { countryId: string }) {
         justifyContent: "center",
         gap: spacing["2xl"],
         padding: `${spacing["5xl"]} ${spacing.xl}`,
-        background: colors.white,
+        background: colors.background.primary,
         overflow: "hidden",
       }}
     >
@@ -152,7 +148,7 @@ export default function HeroSection({ countryId }: { countryId: string }) {
           left: 0,
           right: 0,
           height: 80,
-          background: `linear-gradient(to bottom, transparent, ${colors.white})`,
+          background: `linear-gradient(to bottom, transparent, ${colors.background.primary})`,
           pointerEvents: "none",
           zIndex: 2,
         }}
diff --git a/website/src/components/home/HomeBlogPreview.tsx b/website/src/components/home/HomeBlogPreview.tsx
index 950195c5a..9d8e1c79e 100644
--- a/website/src/components/home/HomeBlogPreview.tsx
+++ b/website/src/components/home/HomeBlogPreview.tsx
@@ -4,11 +4,7 @@ import Link from "next/link";
 import { Container, Group, Text } from "@/components/ui";
 import OptimisedImage from "@/components/ui/OptimisedImage";
 import { cn } from "@/lib/utils";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 import { getPostsSorted } from "@/data/posts/postTransformers";
 import type { BlogPost } from "@/types/blog";
 
@@ -65,14 +61,14 @@ function PrimaryCard({ post, countryId, flex }: PrimaryCardProps) {
       <div
         className={cn(
           "tw:flex tw:flex-col tw:h-full",
-          "tw:rounded-feature tw:overflow-hidden tw:bg-white tw:border tw:border-border-light",
+          "tw:rounded-feature tw:overflow-hidden tw:bg-card tw:border tw:border-border-light",
           "tw:transition-all tw:duration-300 tw:ease-out",
           "tw:hover:shadow-[0_8px_30px_rgba(16,24,40,0.1)] tw:hover:-translate-y-0.5",
           "tw:focus-within:shadow-[0_0_0_2px_var(--color-primary-500)] tw:focus-within:outline-none",
         )}
       >
         {imageUrl && (
-          <div className="tw:min-h-[200px] tw:flex-1 tw:overflow-hidden tw:bg-gray-100">
+          <div className="tw:min-h-[200px] tw:flex-1 tw:overflow-hidden tw:bg-muted">
             <OptimisedImage
               src={imageUrl}
               alt={post.title}
@@ -90,7 +86,7 @@ function PrimaryCard({ post, countryId, flex }: PrimaryCardProps) {
             {date}
           </p>
 
-          <p className="tw:text-2xl tw:font-bold tw:leading-tight tw:text-gray-900 tw:mb-md">
+          <p className="tw:text-2xl tw:font-bold tw:leading-tight tw:text-card-foreground tw:mb-md">
             {post.title}
           </p>
 
@@ -128,14 +124,14 @@ function SecondaryCard({ post, countryId }: SecondaryCardProps) {
       <div
         className={cn(
           "tw:flex tw:flex-col tw:h-full",
-          "tw:rounded-feature tw:overflow-hidden tw:bg-white tw:border tw:border-border-light",
+          "tw:rounded-feature tw:overflow-hidden tw:bg-card tw:border tw:border-border-light",
           "tw:transition-all tw:duration-300 tw:ease-out",
           "tw:hover:shadow-[0_6px_24px_rgba(16,24,40,0.1)] tw:hover:-translate-y-0.5",
           "tw:focus-within:shadow-[0_0_0_2px_var(--color-primary-500)] tw:focus-within:outline-none",
         )}
       >
         {imageUrl && (
-          <div className="tw:h-[180px] tw:overflow-hidden tw:bg-gray-100 tw:shrink-0">
+          <div className="tw:h-[180px] tw:overflow-hidden tw:bg-muted tw:shrink-0">
             <OptimisedImage
               src={imageUrl}
               alt={post.title}
@@ -153,7 +149,7 @@ function SecondaryCard({ post, countryId }: SecondaryCardProps) {
             {date}
           </p>
 
-          <p className="tw:text-base tw:font-semibold tw:leading-snug tw:text-gray-900 tw:line-clamp-2 tw:mb-sm">
+          <p className="tw:text-base tw:font-semibold tw:leading-snug tw:text-card-foreground tw:line-clamp-2 tw:mb-sm">
             {post.title}
           </p>
 
@@ -174,11 +170,7 @@ function SecondaryCard({ post, countryId }: SecondaryCardProps) {
 /*  HomeBlogPreview                                                    */
 /* ------------------------------------------------------------------ */
 
-export default function HomeBlogPreview({
-  countryId,
-}: {
-  countryId: string;
-}) {
+export default function HomeBlogPreview({ countryId }: { countryId: string }) {
   // getPostsSorted() returns posts sorted newest-first with slugs pre-computed
   const relevantPosts = getPostsSorted()
     .filter(
@@ -197,7 +189,7 @@ export default function HomeBlogPreview({
   return (
     <div
       style={{
-        backgroundColor: colors.gray[50],
+        backgroundColor: colors.background.secondary,
         paddingTop: spacing["5xl"],
         paddingBottom: spacing["5xl"],
       }}
@@ -213,7 +205,7 @@ export default function HomeBlogPreview({
             fw={typography.fontWeight.bold}
             style={{
               fontSize: typography.fontSize["3xl"],
-              color: colors.primary[800],
+              color: colors.text.title,
               fontFamily: typography.fontFamily.primary,
               lineHeight: typography.lineHeight.tight,
             }}
@@ -241,10 +233,7 @@ export default function HomeBlogPreview({
           style={{ gap: spacing["2xl"] }}
         >
           {/* Left column: 2 posts stacked, filling equal height */}
-          <div
-            className="tw:flex tw:flex-col"
-            style={{ gap: spacing["2xl"] }}
-          >
+          <div className="tw:flex tw:flex-col" style={{ gap: spacing["2xl"] }}>
             {leftPosts.map((post: BlogPost) => (
               <PrimaryCard
                 key={post.slug}
@@ -256,10 +245,7 @@ export default function HomeBlogPreview({
           </div>
 
           {/* Right column: 3 smaller posts stacked */}
-          <div
-            className="tw:flex tw:flex-col"
-            style={{ gap: spacing["2xl"] }}
-          >
+          <div className="tw:flex tw:flex-col" style={{ gap: spacing["2xl"] }}>
             {rightPosts.map((post: BlogPost) => (
               <SecondaryCard
                 key={post.slug}
diff --git a/website/src/components/home/HomeTrackerPreview.tsx b/website/src/components/home/HomeTrackerPreview.tsx
index 93a2b8fef..26cf720e0 100644
--- a/website/src/components/home/HomeTrackerPreview.tsx
+++ b/website/src/components/home/HomeTrackerPreview.tsx
@@ -1,11 +1,7 @@
 "use client";
 
 import Link from "next/link";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 export default function HomeTrackerPreview({
   countryId,
@@ -17,7 +13,7 @@ export default function HomeTrackerPreview({
   return (
     <div
       style={{
-        backgroundColor: colors.primary[50],
+        backgroundColor: colors.background.accent,
         paddingTop: spacing["5xl"],
         paddingBottom: spacing["5xl"],
       }}
@@ -42,7 +38,7 @@ export default function HomeTrackerPreview({
             style={{
               fontWeight: typography.fontWeight.bold,
               fontSize: typography.fontSize["3xl"],
-              color: colors.primary[800],
+              color: colors.text.title,
               fontFamily: typography.fontFamily.primary,
               lineHeight: typography.lineHeight.tight,
               margin: 0,
@@ -73,7 +69,7 @@ export default function HomeTrackerPreview({
             style={{
               borderRadius: spacing.radius.feature,
               overflow: "hidden",
-              backgroundColor: colors.white,
+              backgroundColor: colors.background.elevated,
               border: `1px solid ${colors.border.light}`,
               transition: "box-shadow 0.25s ease, transform 0.25s ease",
               cursor: "pointer",
@@ -139,7 +135,7 @@ export default function HomeTrackerPreview({
                     fontSize: typography.fontSize["2xl"],
                     lineHeight: typography.lineHeight.tight,
                     fontFamily: typography.fontFamily.primary,
-                    color: colors.gray[900],
+                    color: colors.text.title,
                     marginBottom: spacing.md,
                   }}
                 >
diff --git a/website/src/components/home/TypewriterPrompt.tsx b/website/src/components/home/TypewriterPrompt.tsx
index acb71e7bb..dcee2ddc2 100644
--- a/website/src/components/home/TypewriterPrompt.tsx
+++ b/website/src/components/home/TypewriterPrompt.tsx
@@ -1,11 +1,7 @@
 "use client";
 
 import { useCallback, useEffect, useRef, useState } from "react";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 export interface PromptData {
   text: string;
@@ -291,7 +287,7 @@ export default function TypewriterPrompt({
       <div
         style={{
           display: "inline-block",
-          background: `${colors.white}e6`,
+          background: colors.background.overlay,
           backdropFilter: "blur(8px)",
           borderRadius: spacing.radius.container,
           padding: `${spacing["2xl"]} ${spacing["3xl"]}`,
diff --git a/website/src/components/static/ActionButton.tsx b/website/src/components/static/ActionButton.tsx
index edb8f026c..649cb221f 100644
--- a/website/src/components/static/ActionButton.tsx
+++ b/website/src/components/static/ActionButton.tsx
@@ -2,11 +2,7 @@
 
 import { useEffect, useRef, useState } from "react";
 import { Text } from "@/components/ui";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 export interface ActionButtonProps {
   text: string;
@@ -33,24 +29,24 @@ export default function ActionButton({
   }, [text, multiline]);
   const styles = {
     primary: {
-      backgroundColor: colors.white,
+      backgroundColor: colors.background.elevated,
       color: colors.text.primary,
       border: `2px solid ${colors.border.light}`,
-      hoverBackground: colors.gray[50],
+      hoverBackground: colors.background.hover,
       hoverBorder: colors.black,
     },
     secondary: {
       backgroundColor: colors.primary[500],
-      color: colors.white,
+      color: colors.text.inverse,
       border: `2px solid ${colors.primary[500]}`,
       hoverBackground: colors.primary[600],
       hoverBorder: colors.primary[600],
     },
     inverted: {
-      backgroundColor: colors.white,
+      backgroundColor: colors.background.elevated,
       color: colors.text.primary,
-      border: `2px solid ${colors.white}`,
-      hoverBackground: colors.gray[50],
+      border: `2px solid ${colors.border.light}`,
+      hoverBackground: colors.background.hover,
       hoverBorder: colors.black,
     },
   };
diff --git a/website/src/components/static/CTASection.tsx b/website/src/components/static/CTASection.tsx
index a4f3e87fb..8ee398f7f 100644
--- a/website/src/components/static/CTASection.tsx
+++ b/website/src/components/static/CTASection.tsx
@@ -1,10 +1,6 @@
 import { ReactNode } from "react";
 import { Container, Title } from "@/components/ui";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 import ActionButton, { ActionButtonProps } from "./ActionButton";
 
 export interface CTASectionProps {
@@ -23,8 +19,8 @@ export default function CTASection({
   caption,
 }: CTASectionProps) {
   const backgrounds = {
-    primary: colors.white,
-    secondary: colors.gray[100],
+    primary: colors.background.primary,
+    secondary: colors.background.secondary,
     accent: colors.primary[700],
   };
 
@@ -63,9 +59,7 @@ export default function CTASection({
           </Title>
         )}
         <div className="tw:flex tw:flex-col tw:md:flex-row tw:items-stretch tw:md:items-center tw:gap-6 tw:md:gap-12">
-          <div style={{ flex: 1.5, color: textColors[variant] }}>
-            {content}
-          </div>
+          <div style={{ flex: 1.5, color: textColors[variant] }}>{content}</div>
           <div className="tw:flex tw:flex-1 tw:flex-col tw:items-center tw:justify-center">
             <ActionButton
               {...cta}
diff --git a/website/src/components/static/ContentSection.tsx b/website/src/components/static/ContentSection.tsx
index e96b854c8..fe7088a71 100644
--- a/website/src/components/static/ContentSection.tsx
+++ b/website/src/components/static/ContentSection.tsx
@@ -1,10 +1,6 @@
 import { ReactNode } from "react";
 import { Container, Title } from "@/components/ui";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 
 export interface ContentSectionProps {
   title?: string;
@@ -20,8 +16,8 @@ export default function ContentSection({
   centerTitle = false,
 }: ContentSectionProps) {
   const backgrounds = {
-    primary: colors.white,
-    secondary: colors.gray[100],
+    primary: colors.background.primary,
+    secondary: colors.background.secondary,
     accent: colors.primary[700],
   };
 
diff --git a/website/src/components/static/HeroSection.tsx b/website/src/components/static/HeroSection.tsx
index 7da6b2001..34131f40c 100644
--- a/website/src/components/static/HeroSection.tsx
+++ b/website/src/components/static/HeroSection.tsx
@@ -10,19 +10,19 @@ export default function HeroSection({ title, description }: HeroSectionProps) {
     <div
       className="tw:px-[6.125%] tw:py-14 tw:md:py-20"
       style={{
-        backgroundColor: colors.gray[50],
+        backgroundColor: colors.background.secondary,
         borderBottom: `1px solid ${colors.border.light}`,
       }}
     >
       <h1
         className="tw:text-3xl tw:md:text-4xl tw:font-bold tw:tracking-tight"
-        style={{ color: colors.primary[800] }}
+        style={{ color: colors.text.title }}
       >
         {title}
       </h1>
       <p
         className="tw:text-base tw:md:text-lg tw:leading-relaxed tw:mt-4"
-        style={{ color: colors.gray[500] }}
+        style={{ color: colors.text.secondary }}
       >
         {description}
       </p>
diff --git a/website/src/components/static/LegalPageLayout.tsx b/website/src/components/static/LegalPageLayout.tsx
index 5dcf87e0f..e53181b42 100644
--- a/website/src/components/static/LegalPageLayout.tsx
+++ b/website/src/components/static/LegalPageLayout.tsx
@@ -1,5 +1,5 @@
-import { Container, Title } from '@/components/ui';
-import { colors, spacing, typography } from '@/designTokens';
+import { Container, Title } from "@/components/ui";
+import { colors, spacing, typography } from "@/designTokens";
 
 export interface LegalSection {
   heading: string;
@@ -11,37 +11,40 @@ export interface LegalPageLayoutProps {
   sections: LegalSection[];
 }
 
-export default function LegalPageLayout({ title, sections }: LegalPageLayoutProps) {
+export default function LegalPageLayout({
+  title,
+  sections,
+}: LegalPageLayoutProps) {
   return (
     <div
       style={{
-        paddingTop: spacing['4xl'],
-        paddingBottom: spacing['4xl'],
-        backgroundColor: colors.white,
-        paddingLeft: '6.125%',
-        paddingRight: '6.125%',
+        paddingTop: spacing["4xl"],
+        paddingBottom: spacing["4xl"],
+        backgroundColor: colors.background.primary,
+        paddingLeft: "6.125%",
+        paddingRight: "6.125%",
       }}
     >
       <Container size="md" className="tw:px-0">
         <Title
           order={1}
           style={{
-            fontSize: typography.fontSize['4xl'],
+            fontSize: typography.fontSize["4xl"],
             fontWeight: typography.fontWeight.semibold,
             fontFamily: typography.fontFamily.primary,
             color: colors.text.primary,
-            marginBottom: spacing['3xl'],
+            marginBottom: spacing["3xl"],
           }}
         >
           {title}
         </Title>
 
         {sections.map((section, index) => (
-          <div key={index} style={{ marginBottom: spacing['2xl'] }}>
+          <div key={index} style={{ marginBottom: spacing["2xl"] }}>
             <Title
               order={2}
               style={{
-                fontSize: typography.fontSize['2xl'],
+                fontSize: typography.fontSize["2xl"],
                 fontWeight: typography.fontWeight.semibold,
                 fontFamily: typography.fontFamily.primary,
                 color: colors.text.primary,
diff --git a/website/src/components/static/SupportedProject.tsx b/website/src/components/static/SupportedProject.tsx
index 8eb1eec3f..0a6037887 100644
--- a/website/src/components/static/SupportedProject.tsx
+++ b/website/src/components/static/SupportedProject.tsx
@@ -1,10 +1,10 @@
-import { colors, spacing, typography } from '@/designTokens';
+import { colors, spacing, typography } from "@/designTokens";
 
 export interface SupportedProject {
   title: string;
   projectUrl?: string;
   amount: number;
-  currency: 'USD' | 'GBP';
+  currency: "USD" | "GBP";
   awardDate: string; // Format: YYYY-MM
   description: string;
   supporterId: string;
@@ -19,19 +19,19 @@ export interface SupportedProjectProps {
 
 // Utility to format YYYY-MM date to "Month YYYY"
 function formatDate(dateStr: string): string {
-  const [year, month] = dateStr.split('-');
+  const [year, month] = dateStr.split("-");
   const date = new Date(parseInt(year, 10), parseInt(month, 10) - 1);
-  return date.toLocaleDateString('en-US', { month: 'long', year: 'numeric' });
+  return date.toLocaleDateString("en-US", { month: "long", year: "numeric" });
 }
 
 export default function SupportedProject({ project }: SupportedProjectProps) {
   return (
     <div
       style={{
-        margin: '16px 0',
-        padding: '16px',
+        margin: "16px 0",
+        padding: "16px",
         borderLeft: `4px solid ${colors.primary[500]}`,
-        backgroundColor: colors.gray[50],
+        backgroundColor: colors.background.secondary,
       }}
     >
       <h3
@@ -50,7 +50,7 @@ export default function SupportedProject({ project }: SupportedProjectProps) {
             rel="noopener noreferrer"
             style={{
               color: colors.text.link,
-              textDecoration: 'none',
+              textDecoration: "none",
             }}
           >
             {project.title}
@@ -73,8 +73,8 @@ export default function SupportedProject({ project }: SupportedProjectProps) {
             fontFamily: typography.fontFamily.body,
           }}
         >
-          <strong>Award:</strong> {project.currency === 'GBP' ? '\u00a3' : '$'}
-          {project.amount.toLocaleString('en-US')}
+          <strong>Award:</strong> {project.currency === "GBP" ? "\u00a3" : "$"}
+          {project.amount.toLocaleString("en-US")}
         </span>
         <span
           style={{
diff --git a/website/src/components/static/TeamMemberCard.tsx b/website/src/components/static/TeamMemberCard.tsx
index c54edf1b8..186236c8d 100644
--- a/website/src/components/static/TeamMemberCard.tsx
+++ b/website/src/components/static/TeamMemberCard.tsx
@@ -1,5 +1,5 @@
-import OptimisedImage from '@/components/ui/OptimisedImage';
-import { cn } from '@/lib/utils';
+import OptimisedImage from "@/components/ui/OptimisedImage";
+import { cn } from "@/lib/utils";
 
 export interface TeamMember {
   name: string;
@@ -9,11 +9,14 @@ export interface TeamMember {
 
 export interface TeamMemberCardProps {
   member: TeamMember;
-  variant?: 'default' | 'inverted';
+  variant?: "default" | "inverted";
 }
 
-export default function TeamMemberCard({ member, variant = 'default' }: TeamMemberCardProps) {
-  const isInverted = variant === 'inverted';
+export default function TeamMemberCard({
+  member,
+  variant = "default",
+}: TeamMemberCardProps) {
+  const isInverted = variant === "inverted";
 
   return (
     <div className="tw:grid tw:grid-cols-1 tw:sm:grid-cols-[auto_1fr] tw:items-stretch tw:gap-[5vw] tw:mt-[50px]">
@@ -27,19 +30,22 @@ export default function TeamMemberCard({ member, variant = 'default' }: TeamMemb
 
       <div
         className={cn(
-          'tw:h-full tw:pb-[50px] tw:border-b',
-          isInverted ? 'tw:border-white' : 'tw:border-black'
+          "tw:h-full tw:pb-[50px] tw:border-b",
+          isInverted ? "tw:border-white" : "tw:border-border-dark",
         )}
       >
         <p
           className={cn(
-            'tw:text-base tw:leading-relaxed',
-            isInverted ? 'tw:text-text-inverse' : 'tw:text-text-primary'
+            "tw:text-base tw:leading-relaxed",
+            isInverted ? "tw:text-text-inverse" : "tw:text-text-primary",
           )}
         >
-          <span className="tw:font-semibold tw:uppercase" style={{ letterSpacing: '0.05em' }}>
+          <span
+            className="tw:font-semibold tw:uppercase"
+            style={{ letterSpacing: "0.05em" }}
+          >
             {member.name}
-          </span>{' '}
+          </span>{" "}
           {member.bio}
         </p>
       </div>
diff --git a/website/src/components/static/TeamSection.tsx b/website/src/components/static/TeamSection.tsx
index a75147257..fdfb32635 100644
--- a/website/src/components/static/TeamSection.tsx
+++ b/website/src/components/static/TeamSection.tsx
@@ -1,9 +1,5 @@
 import { Container, Title } from "@/components/ui";
-import {
-  colors,
-  spacing,
-  typography,
-} from "@/designTokens";
+import { colors, spacing, typography } from "@/designTokens";
 import TeamMemberCard, { TeamMember } from "./TeamMemberCard";
 
 export interface TeamSectionProps {
@@ -18,8 +14,8 @@ export default function TeamSection({
   variant = "primary",
 }: TeamSectionProps) {
   const backgrounds = {
-    primary: colors.white,
-    secondary: colors.gray[100],
+    primary: colors.background.primary,
+    secondary: colors.background.secondary,
     accent: colors.primary[700],
   };
 
diff --git a/website/src/components/ui/Text.tsx b/website/src/components/ui/Text.tsx
index 60b2ca88d..08e008072 100644
--- a/website/src/components/ui/Text.tsx
+++ b/website/src/components/ui/Text.tsx
@@ -1,34 +1,35 @@
-import React from 'react';
-import { cva, type VariantProps } from 'class-variance-authority';
-import { cn } from '@/lib/utils';
+import React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
 
 // Mantine color aliases — "dimmed" was the most common
 const COLOR_ALIASES: Record<string, string> = {
-  dimmed: '#9CA3AF',
+  dimmed: "var(--tw-color-text-tertiary)",
 };
 
-const textVariants = cva('', {
+const textVariants = cva("", {
   variants: {
     size: {
-      xs: 'tw:text-xs',
-      sm: 'tw:text-sm',
-      md: 'tw:text-base',
-      lg: 'tw:text-lg',
-      xl: 'tw:text-xl',
+      xs: "tw:text-xs",
+      sm: "tw:text-sm",
+      md: "tw:text-base",
+      lg: "tw:text-lg",
+      xl: "tw:text-xl",
     },
     weight: {
-      normal: 'tw:font-normal',
-      medium: 'tw:font-medium',
-      semibold: 'tw:font-semibold',
-      bold: 'tw:font-bold',
+      normal: "tw:font-normal",
+      medium: "tw:font-medium",
+      semibold: "tw:font-semibold",
+      bold: "tw:font-bold",
     },
   },
   defaultVariants: {
-    size: 'md',
+    size: "md",
   },
 });
 
-interface TextProps extends React.HTMLAttributes<HTMLElement>, VariantProps<typeof textVariants> {
+interface TextProps
+  extends React.HTMLAttributes<HTMLElement>, VariantProps<typeof textVariants> {
   span?: boolean;
   fw?: number;
   c?: string;
@@ -36,8 +37,22 @@ interface TextProps extends React.HTMLAttributes<HTMLElement>, VariantProps<type
 }
 
 const Text = React.forwardRef<HTMLElement, TextProps>(
-  ({ className, size, weight, span, fw, c, component, style, children, ...props }, ref) => {
-    const Component = component || (span ? 'span' : 'p');
+  (
+    {
+      className,
+      size,
+      weight,
+      span,
+      fw,
+      c,
+      component,
+      style,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const Component = component || (span ? "span" : "p");
     const fontWeightStyle = fw ? { fontWeight: fw } : undefined;
     const colorStyle = c ? { color: COLOR_ALIASES[c] || c } : undefined;
 
@@ -51,9 +66,9 @@ const Text = React.forwardRef<HTMLElement, TextProps>(
         {children}
       </Component>
     );
-  }
+  },
 );
-Text.displayName = 'Text';
+Text.displayName = "Text";
 
 export { Text, textVariants };
 export type { TextProps };
diff --git a/website/src/contexts/ThemeContext.tsx b/website/src/contexts/ThemeContext.tsx
new file mode 100644
index 000000000..4904bc30b
--- /dev/null
+++ b/website/src/contexts/ThemeContext.tsx
@@ -0,0 +1,149 @@
+"use client";
+
+import {
+  createContext,
+  ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+
+export type ThemePreference = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+
+interface ThemeContextValue {
+  preference: ThemePreference;
+  resolvedTheme: ResolvedTheme;
+  setPreference: (preference: ThemePreference) => void;
+  toggleTheme: () => void;
+}
+
+const STORAGE_KEY = "policyengine-theme";
+const MEDIA_QUERY = "(prefers-color-scheme: dark)";
+
+const fallbackThemeContext: ThemeContextValue = {
+  preference: "system",
+  resolvedTheme: "light",
+  setPreference: () => {},
+  toggleTheme: () => {},
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+function isThemePreference(value: string | null): value is ThemePreference {
+  return value === "light" || value === "dark" || value === "system";
+}
+
+function getStoredPreference(): ThemePreference {
+  if (typeof window === "undefined") {
+    return "system";
+  }
+
+  try {
+    const storedPreference = window.localStorage.getItem(STORAGE_KEY);
+    return isThemePreference(storedPreference) ? storedPreference : "system";
+  } catch {
+    return "system";
+  }
+}
+
+function getSystemTheme(): ResolvedTheme {
+  if (typeof window === "undefined") {
+    return "light";
+  }
+
+  return window.matchMedia(MEDIA_QUERY).matches ? "dark" : "light";
+}
+
+function resolveTheme(
+  preference: ThemePreference,
+  systemTheme: ResolvedTheme,
+): ResolvedTheme {
+  return preference === "system" ? systemTheme : preference;
+}
+
+function applyTheme(theme: ResolvedTheme) {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  document.documentElement.dataset.peTheme = theme;
+  document.documentElement.style.colorScheme = theme;
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [preference, setPreferenceState] = useState<ThemePreference>("system");
+  const [systemTheme, setSystemTheme] = useState<ResolvedTheme>("light");
+
+  useEffect(() => {
+    const storedPreference = getStoredPreference();
+    const currentSystemTheme = getSystemTheme();
+
+    setPreferenceState(storedPreference);
+    setSystemTheme(currentSystemTheme);
+    applyTheme(resolveTheme(storedPreference, currentSystemTheme));
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const mediaQuery = window.matchMedia(MEDIA_QUERY);
+    const handleChange = () => {
+      const nextSystemTheme = mediaQuery.matches ? "dark" : "light";
+      setSystemTheme(nextSystemTheme);
+
+      if (preference === "system") {
+        applyTheme(nextSystemTheme);
+      }
+    };
+
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, [preference]);
+
+  const resolvedTheme = resolveTheme(preference, systemTheme);
+
+  useEffect(() => {
+    applyTheme(resolvedTheme);
+  }, [resolvedTheme]);
+
+  const setPreference = useCallback((nextPreference: ThemePreference) => {
+    setPreferenceState(nextPreference);
+
+    try {
+      if (nextPreference === "system") {
+        window.localStorage.removeItem(STORAGE_KEY);
+      } else {
+        window.localStorage.setItem(STORAGE_KEY, nextPreference);
+      }
+    } catch {
+      // Ignore storage failures and keep the in-memory preference.
+    }
+  }, []);
+
+  const toggleTheme = useCallback(() => {
+    setPreference(resolvedTheme === "dark" ? "light" : "dark");
+  }, [resolvedTheme, setPreference]);
+
+  const value = useMemo(
+    () => ({
+      preference,
+      resolvedTheme,
+      setPreference,
+      toggleTheme,
+    }),
+    [preference, resolvedTheme, setPreference, toggleTheme],
+  );
+
+  return (
+    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  return useContext(ThemeContext) ?? fallbackThemeContext;
+}