From 294ae3f818584796d75b17f43ce03e523e0dc8f0 Mon Sep 17 00:00:00 2001
From: somemorewater <oboyiloejeh@gmail.com>
Date: Thu, 25 Jun 2026 15:45:15 +0100
Subject: [PATCH] feat(theme-builder): implement theme marketplace,
 import/export, and share functionality

- Added MarketplacePanel component for fetching and installing themes from a marketplace.
- Introduced ShareButton component with a hint for future sharing capabilities.
- Created SpacingSlider component for adjusting spacing settings.
- Developed ThemeBuilder component to manage theme customization, including color, typography, and spacing.
- Implemented ThemeImportExport component for exporting and importing theme definitions as JSON.
- Added ThemePresets component to select from predefined themes.
- Established a mock marketplace data layer in marketplace.ts for theme management.
- Enhanced store management to include custom themes and theme builder drafts.
- Defined theme types and utilities in themeTypes.ts for better type safety and theme management.
---
 index.html                                    |  16 +-
 src/components/theme-builder/ColorPicker.jsx  |  59 ++
 src/components/theme-builder/FontSelector.jsx |  69 +++
 src/components/theme-builder/LivePreview.jsx  |  68 +++
 .../theme-builder/MarketplacePanel.jsx        | 118 ++++
 src/components/theme-builder/ShareButton.jsx  |  56 ++
 .../theme-builder/SpacingSlider.jsx           |  32 ++
 src/components/theme-builder/ThemeBuilder.jsx |  94 ++++
 .../theme-builder/ThemeImportExport.jsx       | 110 ++++
 src/components/theme-builder/ThemePresets.jsx |  56 ++
 src/lib/marketplace.ts                        | 144 +++++
 src/lib/store.ts                              |  35 +-
 src/styles/themeTypes.ts                      | 511 ++++++++++++++++++
 13 files changed, 1364 insertions(+), 4 deletions(-)
 create mode 100644 src/components/theme-builder/ColorPicker.jsx
 create mode 100644 src/components/theme-builder/FontSelector.jsx
 create mode 100644 src/components/theme-builder/LivePreview.jsx
 create mode 100644 src/components/theme-builder/MarketplacePanel.jsx
 create mode 100644 src/components/theme-builder/ShareButton.jsx
 create mode 100644 src/components/theme-builder/SpacingSlider.jsx
 create mode 100644 src/components/theme-builder/ThemeBuilder.jsx
 create mode 100644 src/components/theme-builder/ThemeImportExport.jsx
 create mode 100644 src/components/theme-builder/ThemePresets.jsx
 create mode 100644 src/lib/marketplace.ts
 create mode 100644 src/styles/themeTypes.ts

diff --git a/index.html b/index.html
index 31cf6783..0fe4149a 100644
--- a/index.html
+++ b/index.html
@@ -6,12 +6,26 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Stellar Developer Dashboard</title>
     <script>
-      // Blocking script to accurately set the theme dataset attribute before initial paint
+      // Blocking script to restore the theme before initial paint (FOUC prevention)
       (function () {
         try {
           var saved = localStorage.getItem('stellar-dashboard-theme');
           if (saved === 'light' || saved === 'dark') {
             document.documentElement.setAttribute('data-theme', saved);
+          } else if (saved === 'custom') {
+            // Restore custom theme CSS vars from localStorage
+            var varsRaw = localStorage.getItem('stellar-theme-vars');
+            if (varsRaw) {
+              try {
+                var vars = JSON.parse(varsRaw);
+                for (var key in vars) {
+                  if (vars.hasOwnProperty(key)) {
+                    document.documentElement.style.setProperty(key, vars[key]);
+                  }
+                }
+              } catch (e) {}
+            }
+            document.documentElement.setAttribute('data-theme', 'custom');
           } else {
             var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
             document.documentElement.setAttribute('data-theme', prefersDark ? 'dark' : 'light');
diff --git a/src/components/theme-builder/ColorPicker.jsx b/src/components/theme-builder/ColorPicker.jsx
new file mode 100644
index 00000000..c51458a6
--- /dev/null
+++ b/src/components/theme-builder/ColorPicker.jsx
@@ -0,0 +1,59 @@
+import React from 'react'
+
+const COLOR_LABELS = {
+  background: 'Background',
+  surface: 'Surface',
+  primary: 'Primary',
+  secondary: 'Secondary',
+  text: 'Text',
+}
+
+export default function ColorPicker({ colors, onChange }) {
+  return (
+    <div>
+      <div style={{ fontSize: '11px', color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.8px', marginBottom: '10px' }}>
+        Colors
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+        {Object.entries(COLOR_LABELS).map(([key, label]) => (
+          <div key={key} style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+            <span style={{ fontSize: '12px', color: 'var(--text-secondary)', fontFamily: 'var(--font-mono)', minWidth: '80px' }}>
+              {label}
+            </span>
+            <input
+              type="color"
+              value={colors[key]}
+              onChange={(e) => onChange('colors', { ...colors, [key]: e.target.value })}
+              style={{
+                width: '32px',
+                height: '32px',
+                padding: '2px',
+                border: '1px solid var(--border)',
+                borderRadius: 'var(--radius-sm)',
+                cursor: 'pointer',
+                background: 'none',
+                flexShrink: 0,
+              }}
+            />
+            <input
+              type="text"
+              value={colors[key]}
+              onChange={(e) => onChange('colors', { ...colors, [key]: e.target.value })}
+              style={{
+                flex: 1,
+                padding: '6px 8px',
+                background: 'var(--bg-elevated)',
+                border: '1px solid var(--border-bright)',
+                borderRadius: 'var(--radius-sm)',
+                color: 'var(--text-primary)',
+                fontSize: '12px',
+                fontFamily: 'var(--font-mono)',
+                outline: 'none',
+              }}
+            />
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
diff --git a/src/components/theme-builder/FontSelector.jsx b/src/components/theme-builder/FontSelector.jsx
new file mode 100644
index 00000000..61941b45
--- /dev/null
+++ b/src/components/theme-builder/FontSelector.jsx
@@ -0,0 +1,69 @@
+import React from 'react'
+
+const FONTS = [
+  { value: "'Syne', sans-serif", label: 'Syne' },
+  { value: "'Space Mono', monospace", label: 'Space Mono' },
+]
+
+export default function FontSelector({ fontFamily, fontScale, onChange }) {
+  return (
+    <div>
+      <div style={{ fontSize: '11px', color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.8px', marginBottom: '10px' }}>
+        Typography
+      </div>
+
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+        <div>
+          <div style={{ fontSize: '11px', color: 'var(--text-muted)', marginBottom: '6px' }}>
+            Font Family
+          </div>
+          <div style={{ display: 'flex', gap: '8px' }}>
+            {FONTS.map((f) => (
+              <button
+                key={f.value}
+                onClick={() => onChange('typography', { fontFamily: f.value, fontScale })}
+                style={{
+                  flex: 1,
+                  padding: '10px 16px',
+                  background: fontFamily === f.value ? 'var(--cyan-glow)' : 'var(--bg-elevated)',
+                  border: `1px solid ${fontFamily === f.value ? 'var(--cyan-dim)' : 'var(--border)'}`,
+                  borderRadius: 'var(--radius-sm)',
+                  color: fontFamily === f.value ? 'var(--cyan)' : 'var(--text-secondary)',
+                  fontSize: fontFamily === f.value ? '14px' : '12px',
+                  fontFamily: f.value,
+                  cursor: 'pointer',
+                  textAlign: 'center',
+                  transition: 'var(--transition)',
+                }}
+              >
+                {f.label}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <div>
+          <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '6px' }}>
+            <span style={{ fontSize: '11px', color: 'var(--text-muted)' }}>Font Scale</span>
+            <span style={{ fontSize: '11px', color: 'var(--text-secondary)', fontFamily: 'var(--font-mono)' }}>
+              {fontScale.toFixed(1)}x
+            </span>
+          </div>
+          <input
+            type="range"
+            min="0.75"
+            max="1.5"
+            step="0.05"
+            value={fontScale}
+            onChange={(e) => onChange('typography', { fontFamily, fontScale: parseFloat(e.target.value) })}
+            style={{ width: '100%', cursor: 'pointer', accentColor: 'var(--cyan)' }}
+          />
+          <div style={{ display: 'flex', justifyContent: 'space-between', fontSize: '10px', color: 'var(--text-muted)' }}>
+            <span>0.75×</span>
+            <span>1.5×</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/src/components/theme-builder/LivePreview.jsx b/src/components/theme-builder/LivePreview.jsx
new file mode 100644
index 00000000..c625bb4e
--- /dev/null
+++ b/src/components/theme-builder/LivePreview.jsx
@@ -0,0 +1,68 @@
+import React from 'react'
+import Card from '../dashboard/Card'
+
+export default function LivePreview({ colors, typography, spacing }) {
+  const borderColor = colors.primary + '33'
+
+  return (
+    <div>
+      <div style={{ fontSize: '11px', color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.8px', marginBottom: '10px' }}>
+        Preview
+      </div>
+      <Card
+        title="Theme Preview"
+        subtitle={`${spacing.baseUnit}px base · ${typography.fontScale.toFixed(1)}x scale`}
+        style={{
+          background: colors.surface,
+          borderColor: borderColor,
+          color: colors.text,
+          fontFamily: typography.fontFamily,
+          fontSize: `${14 * typography.fontScale}px`,
+        }}
+      >
+        <div style={{ padding: `calc(${spacing.baseUnit}px * 2)` }}>
+          <p style={{
+            color: colors.text,
+            opacity: 0.85,
+            fontSize: 'inherit',
+            lineHeight: 1.6,
+            marginBottom: `${spacing.baseUnit * 2}px`,
+          }}>
+            Sample body text rendered with the selected theme colors and typography.
+          </p>
+
+          <div style={{
+            background: colors.background,
+            border: `1px solid ${borderColor}`,
+            borderRadius: `${Math.max(4, spacing.baseUnit)}px`,
+            padding: `${spacing.baseUnit * 1.5}px`,
+            marginBottom: `${spacing.baseUnit * 2}px`,
+          }}>
+            <code style={{
+              fontFamily: "'Space Mono', monospace",
+              color: colors.primary,
+              fontSize: `${12 * typography.fontScale}px`,
+            }}>
+              const theme = {'{'} colors: {'{'}&quot;{colors.background}&quot; ... {'}'}{'}'}
+            </code>
+          </div>
+
+          <button style={{
+            background: colors.primary,
+            color: colors.background,
+            border: 'none',
+            borderRadius: `${Math.max(4, spacing.baseUnit / 2)}px`,
+            padding: `${spacing.baseUnit}px ${spacing.baseUnit * 2}px`,
+            fontFamily: typography.fontFamily,
+            fontSize: `${13 * typography.fontScale}px`,
+            fontWeight: 600,
+            cursor: 'pointer',
+            transition: 'opacity 150ms ease',
+          }}>
+            Action Button
+          </button>
+        </div>
+      </Card>
+    </div>
+  )
+}
diff --git a/src/components/theme-builder/MarketplacePanel.jsx b/src/components/theme-builder/MarketplacePanel.jsx
new file mode 100644
index 00000000..a544f0b8
--- /dev/null
+++ b/src/components/theme-builder/MarketplacePanel.jsx
@@ -0,0 +1,118 @@
+import React, { useEffect, useState } from 'react'
+import { fetchMarketplaceThemes, installMarketplaceTheme } from '../../lib/marketplace'
+import { THEME_COLOR_KEYS } from '../../styles/themeTypes'
+
+const swatchStyle = (color) => ({
+  width: '100%',
+  height: '6px',
+  background: color,
+  borderRadius: '2px',
+})
+
+export default function MarketplacePanel({ onInstall }) {
+  const [themes, setThemes] = useState([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+    fetchMarketplaceThemes()
+      .then((data) => {
+        if (!cancelled) setThemes(data)
+      })
+      .catch((err) => {
+        if (!cancelled) setError(err.message || 'Failed to load marketplace')
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+    return () => { cancelled = true }
+  }, [])
+
+  const handleInstall = async (themeId) => {
+    const theme = await installMarketplaceTheme(themeId)
+    if (theme) onInstall(theme)
+  }
+
+  return (
+    <div>
+      <div style={{ fontSize: '11px', color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.8px', marginBottom: '10px' }}>
+        Marketplace
+      </div>
+
+      {loading && (
+        <div style={{ display: 'flex', alignItems: 'center', gap: '8px', padding: '8px 0' }}>
+          <div className="spinner" />
+          <span style={{ fontSize: '11px', color: 'var(--text-muted)' }}>Loading themes...</span>
+        </div>
+      )}
+
+      {error && (
+        <div style={{ fontSize: '11px', color: 'var(--red)', padding: '8px 0' }}>
+          {error}
+        </div>
+      )}
+
+      {!loading && !error && themes.length === 0 && (
+        <div style={{ fontSize: '11px', color: 'var(--text-muted)', padding: '8px 0' }}>
+          No themes available.
+        </div>
+      )}
+
+      {!loading && themes.length > 0 && (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+          {themes.map((theme) => (
+            <div
+              key={theme.id}
+              style={{
+                background: 'var(--bg-elevated)',
+                border: '1px solid var(--border)',
+                borderRadius: 'var(--radius-md)',
+                overflow: 'hidden',
+              }}
+            >
+              {/* Color swatch strip */}
+              <div style={{ display: 'flex', gap: '2px', padding: '6px 8px 4px' }}>
+                {THEME_COLOR_KEYS.map((key) => (
+                  <div key={key} style={swatchStyle(theme.colors[key])} />
+                ))}
+              </div>
+
+              {/* Info row */}
+              <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '4px 8px 6px' }}>
+                <div style={{ minWidth: 0 }}>
+                  <div style={{ fontSize: '11px', fontWeight: 600, color: 'var(--text-primary)', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                    {theme.name}
+                  </div>
+                  <div style={{ fontSize: '10px', color: 'var(--text-muted)' }}>
+                    {theme.author} · {theme.downloads} downloads
+                  </div>
+                </div>
+                <button
+                  onClick={() => handleInstall(theme.id)}
+                  aria-label={`Install ${theme.name} theme`}
+                  style={{
+                    padding: '4px 10px',
+                    background: 'var(--cyan-glow)',
+                    border: '1px solid var(--cyan-dim)',
+                    borderRadius: 'var(--radius-sm)',
+                    color: 'var(--cyan)',
+                    fontSize: '10px',
+                    fontFamily: 'var(--font-mono)',
+                    cursor: 'pointer',
+                    whiteSpace: 'nowrap',
+                    flexShrink: 0,
+                  }}
+                >
+                  Install
+                </button>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/src/components/theme-builder/ShareButton.jsx b/src/components/theme-builder/ShareButton.jsx
new file mode 100644
index 00000000..e11661cc
--- /dev/null
+++ b/src/components/theme-builder/ShareButton.jsx
@@ -0,0 +1,56 @@
+import React, { useState } from 'react'
+
+export default function ShareButton() {
+  const [hint, setHint] = useState(null)
+
+  const handleClick = () => {
+    setHint('Share coming soon')
+    setTimeout(() => setHint(null), 2000)
+  }
+
+  return (
+    <div style={{ position: 'relative', display: 'inline-block' }}>
+      <button
+        onClick={handleClick}
+        style={{
+          padding: '8px 14px',
+          background: 'var(--bg-elevated)',
+          border: '1px solid var(--border)',
+          borderRadius: 'var(--radius-sm)',
+          color: 'var(--text-secondary)',
+          fontSize: '12px',
+          fontFamily: 'var(--font-mono)',
+          cursor: 'pointer',
+          transition: 'var(--transition)',
+          opacity: 0.6,
+        }}
+        title="Share theme — coming soon"
+      >
+        Share
+      </button>
+      {hint && (
+        <span
+          style={{
+            position: 'absolute',
+            top: '100%',
+            left: '50%',
+            transform: 'translateX(-50%)',
+            marginTop: '4px',
+            padding: '3px 8px',
+            background: 'var(--bg-card)',
+            border: '1px solid var(--border)',
+            borderRadius: 'var(--radius-sm)',
+            color: 'var(--text-muted)',
+            fontSize: '10px',
+            fontFamily: 'var(--font-mono)',
+            whiteSpace: 'nowrap',
+            zIndex: 10,
+            pointerEvents: 'none',
+          }}
+        >
+          {hint}
+        </span>
+      )}
+    </div>
+  )
+}
diff --git a/src/components/theme-builder/SpacingSlider.jsx b/src/components/theme-builder/SpacingSlider.jsx
new file mode 100644
index 00000000..6aeaca5d
--- /dev/null
+++ b/src/components/theme-builder/SpacingSlider.jsx
@@ -0,0 +1,32 @@
+import React from 'react'
+
+export default function SpacingSlider({ baseUnit, onChange }) {
+  return (
+    <div>
+      <div style={{ fontSize: '11px', color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.8px', marginBottom: '10px' }}>
+        Spacing
+      </div>
+      <div>
+        <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '6px' }}>
+          <span style={{ fontSize: '11px', color: 'var(--text-muted)' }}>Base Unit</span>
+          <span style={{ fontSize: '11px', color: 'var(--text-secondary)', fontFamily: 'var(--font-mono)' }}>
+            {baseUnit}px
+          </span>
+        </div>
+        <input
+          type="range"
+          min="4"
+          max="16"
+          step="1"
+          value={baseUnit}
+          onChange={(e) => onChange('spacing', { baseUnit: parseInt(e.target.value, 10) })}
+          style={{ width: '100%', cursor: 'pointer', accentColor: 'var(--cyan)' }}
+        />
+        <div style={{ display: 'flex', justifyContent: 'space-between', fontSize: '10px', color: 'var(--text-muted)' }}>
+          <span>4px</span>
+          <span>16px</span>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/src/components/theme-builder/ThemeBuilder.jsx b/src/components/theme-builder/ThemeBuilder.jsx
new file mode 100644
index 00000000..acf2ccdf
--- /dev/null
+++ b/src/components/theme-builder/ThemeBuilder.jsx
@@ -0,0 +1,94 @@
+import React, { useEffect } from 'react'
+import { useStore } from '../../lib/store'
+import { DEFAULT_THEME_DEFINITION, PRESET_THEMES, generateThemeId } from '../../styles/themeTypes'
+import ColorPicker from './ColorPicker'
+import FontSelector from './FontSelector'
+import SpacingSlider from './SpacingSlider'
+import LivePreview from './LivePreview'
+import ThemePresets from './ThemePresets'
+import ThemeImportExport from './ThemeImportExport'
+import MarketplacePanel from './MarketplacePanel'
+import ShareButton from './ShareButton'
+
+export default function ThemeBuilder() {
+  const draft = useStore((s) => s.themeBuilderDraft)
+  const customTheme = useStore((s) => s.customTheme)
+  const setDraft = useStore((s) => s.setThemeBuilderDraft)
+
+  useEffect(() => {
+    if (!draft) {
+      setDraft(customTheme || DEFAULT_THEME_DEFINITION)
+    }
+  }, [])
+
+  const safe = draft || customTheme || DEFAULT_THEME_DEFINITION
+  const colors = safe.colors
+  const typography = safe.typography
+  const spacing = safe.spacing
+
+  const handleChange = (section, value) => {
+    const updated = { ...safe }
+    if (section === 'colors') updated.colors = value
+    else if (section === 'typography') updated.typography = value
+    else if (section === 'spacing') updated.spacing = value
+    setDraft(updated)
+  }
+
+  const handlePresetSelect = (presetId) => {
+    if (presetId === 'custom') {
+      const source = customTheme || DEFAULT_THEME_DEFINITION
+      setDraft({ ...source, id: source.id, name: source.name })
+      return
+    }
+    const preset = PRESET_THEMES.find((p) => p.id === presetId)
+    if (preset) setDraft({ ...preset })
+  }
+
+  const handleImport = (theme) => {
+    setDraft({ ...theme, id: theme.id || generateThemeId() })
+  }
+
+  const handleMarketplaceInstall = (theme) => {
+    setDraft({
+      ...theme,
+      id: generateThemeId(),
+      name: theme.name,
+    })
+  }
+
+  return (
+    <div style={{
+      display: 'flex',
+      gap: '24px',
+      flexWrap: 'wrap',
+    }}>
+      <div style={{
+        flex: '1 1 280px',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '24px',
+        minWidth: '200px',
+      }}>
+        <ThemePresets draft={safe} onSelect={handlePresetSelect} />
+        <ColorPicker colors={colors} onChange={handleChange} />
+        <FontSelector
+          fontFamily={typography.fontFamily}
+          fontScale={typography.fontScale}
+          onChange={handleChange}
+        />
+        <SpacingSlider baseUnit={spacing.baseUnit} onChange={handleChange} />
+        <ThemeImportExport draft={safe} onImport={handleImport} />
+        <ShareButton />
+        <MarketplacePanel onInstall={handleMarketplaceInstall} />
+      </div>
+
+      <div style={{
+        flex: '1 1 280px',
+        minWidth: '200px',
+        alignSelf: 'flex-start',
+      }}>
+        <LivePreview colors={colors} typography={typography} spacing={spacing} />
+      </div>
+    </div>
+  )
+}
diff --git a/src/components/theme-builder/ThemeImportExport.jsx b/src/components/theme-builder/ThemeImportExport.jsx
new file mode 100644
index 00000000..db790644
--- /dev/null
+++ b/src/components/theme-builder/ThemeImportExport.jsx
@@ -0,0 +1,110 @@
+import React, { useRef, useState, useCallback } from 'react'
+import { exportTheme, importTheme } from '../../styles/themeTypes'
+
+export default function ThemeImportExport({ draft, onImport }) {
+  const fileRef = useRef(null)
+  const [error, setError] = useState(null)
+  const [success, setSuccess] = useState(null)
+
+  const handleExport = useCallback(() => {
+    if (!draft) return
+    const json = exportTheme(draft)
+    const name = draft.name
+      .toLowerCase()
+      .replace(/\s+/g, '-')
+      .replace(/[^a-z0-9-]/g, '') || 'theme'
+    const blob = new Blob([json], { type: 'application/json' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = `${name}.json`
+    document.body.appendChild(a)
+    a.click()
+    document.body.removeChild(a)
+    URL.revokeObjectURL(url)
+  }, [draft])
+
+  const handleImportClick = useCallback(() => {
+    setError(null)
+    setSuccess(null)
+    fileRef.current?.click()
+  }, [])
+
+  const handleFile = useCallback((e) => {
+    const file = e.target.files?.[0]
+    if (!file) return
+    setError(null)
+    setSuccess(null)
+    const reader = new FileReader()
+    reader.onload = (ev) => {
+      try {
+        const theme = importTheme(ev.target.result)
+        onImport(theme)
+        setSuccess(`Loaded "${theme.name}"`)
+        setTimeout(() => setSuccess(null), 2500)
+      } catch (err) {
+        setError(err.message || 'Failed to import theme')
+      }
+    }
+    reader.onerror = () => setError('Failed to read file')
+    reader.readAsText(file)
+    e.target.value = ''
+  }, [onImport])
+
+  const status = error || success
+  const statusColor = error ? 'var(--red)' : 'var(--green)'
+
+  return (
+    <div>
+      <div style={{ fontSize: '11px', color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.8px', marginBottom: '10px' }}>
+        Import / Export
+      </div>
+      <div style={{ display: 'flex', gap: '8px', alignItems: 'center', flexWrap: 'wrap' }}>
+        <button
+          onClick={handleExport}
+          style={{
+            padding: '8px 14px',
+            background: 'var(--bg-elevated)',
+            border: '1px solid var(--border)',
+            borderRadius: 'var(--radius-sm)',
+            color: 'var(--text-secondary)',
+            fontSize: '12px',
+            fontFamily: 'var(--font-mono)',
+            cursor: 'pointer',
+            transition: 'var(--transition)',
+          }}
+        >
+          Export JSON
+        </button>
+        <button
+          onClick={handleImportClick}
+          style={{
+            padding: '8px 14px',
+            background: 'var(--bg-elevated)',
+            border: '1px solid var(--border)',
+            borderRadius: 'var(--radius-sm)',
+            color: 'var(--text-secondary)',
+            fontSize: '12px',
+            fontFamily: 'var(--font-mono)',
+            cursor: 'pointer',
+            transition: 'var(--transition)',
+          }}
+        >
+          Import JSON
+        </button>
+        <input
+          ref={fileRef}
+          type="file"
+          accept=".json,application/json"
+          onChange={handleFile}
+          style={{ display: 'none' }}
+        />
+        {status && (
+          <span style={{ fontSize: '11px', color: statusColor, fontFamily: 'var(--font-mono)' }}>
+            {status}
+          </span>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/src/components/theme-builder/ThemePresets.jsx b/src/components/theme-builder/ThemePresets.jsx
new file mode 100644
index 00000000..580ef378
--- /dev/null
+++ b/src/components/theme-builder/ThemePresets.jsx
@@ -0,0 +1,56 @@
+import React from 'react'
+import { PRESET_THEMES, getActivePresetId } from '../../styles/themeTypes'
+
+const PRESET_META = [
+  { id: 'dark', label: 'Dark', getColor: () => PRESET_THEMES[0].colors.primary },
+  { id: 'light', label: 'Light', getColor: () => PRESET_THEMES[1].colors.primary },
+  { id: 'highContrast', label: 'High Contrast', getColor: () => PRESET_THEMES[2].colors.primary },
+  { id: 'custom', label: 'Custom', getColor: (colors) => colors?.primary || '#888' },
+]
+
+export default function ThemePresets({ draft, onSelect }) {
+  const activeId = getActivePresetId(draft.colors)
+
+  return (
+    <div>
+      <div style={{ fontSize: '11px', color: 'var(--text-muted)', textTransform: 'uppercase', letterSpacing: '0.8px', marginBottom: '10px' }}>
+        Presets
+      </div>
+      <div style={{ display: 'flex', gap: '6px', flexWrap: 'wrap' }}>
+        {PRESET_META.map((preset) => {
+          const isActive = activeId === preset.id
+          return (
+            <button
+              key={preset.id}
+              onClick={() => onSelect(preset.id)}
+              style={{
+                padding: '8px 14px',
+                background: isActive ? 'var(--cyan-glow)' : 'var(--bg-elevated)',
+                border: `1px solid ${isActive ? 'var(--cyan-dim)' : 'var(--border)'}`,
+                borderRadius: 'var(--radius-sm)',
+                color: isActive ? 'var(--cyan)' : 'var(--text-secondary)',
+                fontSize: '12px',
+                fontFamily: 'var(--font-mono)',
+                cursor: 'pointer',
+                display: 'flex',
+                alignItems: 'center',
+                gap: '6px',
+                transition: 'var(--transition)',
+              }}
+            >
+              <span style={{
+                width: '8px',
+                height: '8px',
+                borderRadius: '50%',
+                background: preset.getColor(draft.colors),
+                display: 'inline-block',
+                flexShrink: 0,
+              }} />
+              {preset.label}
+            </button>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
diff --git a/src/lib/marketplace.ts b/src/lib/marketplace.ts
new file mode 100644
index 00000000..d001faa2
--- /dev/null
+++ b/src/lib/marketplace.ts
@@ -0,0 +1,144 @@
+/**
+ * marketplace.ts — Theme Marketplace data layer
+ *
+ * Currently uses local mock data. Designed so the fetch/install functions
+ * can be swapped to real API calls without changing consumer code.
+ */
+import type { ThemeColors, ThemeTypography, ThemeSpacing } from '../styles/themeTypes'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface MarketplaceTheme {
+  id: string
+  name: string
+  author: string
+  description: string
+  colors: ThemeColors
+  typography: ThemeTypography
+  spacing: ThemeSpacing
+  downloads: number
+}
+
+// ─── Mock data ────────────────────────────────────────────────────────────────
+
+const MOCK_THEMES: MarketplaceTheme[] = [
+  {
+    id: 'ocean',
+    name: 'Ocean Depths',
+    author: 'Stellar Team',
+    description: 'Deep blue tones inspired by the ocean',
+    colors: {
+      background: '#0a1628',
+      surface: '#0f1f3d',
+      primary: '#38bdf8',
+      secondary: '#818cf8',
+      text: '#e0f2fe',
+    },
+    typography: { fontFamily: "'Syne', sans-serif", fontScale: 1.0 },
+    spacing: { baseUnit: 8 },
+    downloads: 1240,
+  },
+  {
+    id: 'forest',
+    name: 'Forest Canopy',
+    author: 'Community',
+    description: 'Earthy greens for a natural feel',
+    colors: {
+      background: '#0a1a0f',
+      surface: '#0f2418',
+      primary: '#4ade80',
+      secondary: '#fbbf24',
+      text: '#dcfce7',
+    },
+    typography: { fontFamily: "'Syne', sans-serif", fontScale: 1.0 },
+    spacing: { baseUnit: 8 },
+    downloads: 890,
+  },
+  {
+    id: 'sunset',
+    name: 'Sunset Glow',
+    author: 'Design Lab',
+    description: 'Warm sunset-inspired palette',
+    colors: {
+      background: '#1a0a0a',
+      surface: '#2a1212',
+      primary: '#fb923c',
+      secondary: '#e879f9',
+      text: '#ffedd5',
+    },
+    typography: { fontFamily: "'Syne', sans-serif", fontScale: 1.05 },
+    spacing: { baseUnit: 10 },
+    downloads: 2100,
+  },
+  {
+    id: 'mono',
+    name: 'Monochrome',
+    author: 'Minimalist',
+    description: 'Clean grayscale with a single accent',
+    colors: {
+      background: '#0a0a0a',
+      surface: '#141414',
+      primary: '#a3a3a3',
+      secondary: '#525252',
+      text: '#f5f5f5',
+    },
+    typography: { fontFamily: "'Space Mono', monospace", fontScale: 1.0 },
+    spacing: { baseUnit: 6 },
+    downloads: 560,
+  },
+  {
+    id: 'aurora',
+    name: 'Northern Aurora',
+    author: 'Stellar Team',
+    description: 'Purple and green aurora borealis theme',
+    colors: {
+      background: '#0a0a1a',
+      surface: '#14142a',
+      primary: '#a78bfa',
+      secondary: '#34d399',
+      text: '#ede9fe',
+    },
+    typography: { fontFamily: "'Syne', sans-serif", fontScale: 1.0 },
+    spacing: { baseUnit: 8 },
+    downloads: 340,
+  },
+  {
+    id: 'retro',
+    name: 'Retro Terminal',
+    author: 'Community',
+    description: 'CRT monitor inspired amber-on-black',
+    colors: {
+      background: '#0c0c00',
+      surface: '#1a1a00',
+      primary: '#ffb300',
+      secondary: '#ff8f00',
+      text: '#ffecb3',
+    },
+    typography: { fontFamily: "'Space Mono', monospace", fontScale: 1.0 },
+    spacing: { baseUnit: 8 },
+    downloads: 780,
+  },
+]
+
+// ─── Public API (async — swap to real HTTP calls in the future) ───────────────
+
+/**
+ * Fetch all available marketplace themes.
+ * Replace the implementation with a fetch() call when a real API exists.
+ */
+export async function fetchMarketplaceThemes(): Promise<MarketplaceTheme[]> {
+  // Simulate network latency
+  await new Promise((r) => setTimeout(r, 300))
+  return MOCK_THEMES
+}
+
+/**
+ * Install (download) a single marketplace theme by id.
+ * Returns null when the theme is not found.
+ */
+export async function installMarketplaceTheme(
+  id: string
+): Promise<MarketplaceTheme | null> {
+  await new Promise((r) => setTimeout(r, 100))
+  return MOCK_THEMES.find((t) => t.id === id) ?? null
+}
diff --git a/src/lib/store.ts b/src/lib/store.ts
index 93fa1751..64d17269 100644
--- a/src/lib/store.ts
+++ b/src/lib/store.ts
@@ -3,6 +3,7 @@ import { getStoredValue } from './storage'
 import { syncState, onStateChange } from '../utils/stateSync'
 import type { NetworkName, NetworkStats } from './stellar'
 import type { Horizon, SorobanRpc } from '@stellar/stellar-sdk'
+import { applyCustomThemeToDOM, removeCustomThemeFromDOM, saveThemeVarsToStorage, clearThemeVarsFromStorage, type ThemeDefinition } from '../styles/themeTypes'
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -67,8 +68,8 @@ export const DEFAULT_SEARCH_FILTERS: SearchFilters = {
 }
 
 const PERSIST_KEYS = [
-  'network', 'theme', 'activeTab', 'savedSearches', 'multiSigMode', 'searchFilters',
-  'notificationHistory', 'unreadNotificationCount',
+  'network', 'theme', 'customTheme', 'themeBuilderDraft', 'activeTab', 'savedSearches',
+  'multiSigMode', 'searchFilters', 'notificationHistory', 'unreadNotificationCount',
 ] as const
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -101,6 +102,10 @@ export interface StoreState {
   setNetwork: (network: NetworkName) => void
   theme: 'light' | 'dark'
   toggleTheme: () => void
+  customTheme: ThemeDefinition | null
+  setCustomTheme: (theme: ThemeDefinition | null) => void
+  themeBuilderDraft: ThemeDefinition | null
+  setThemeBuilderDraft: (draft: ThemeDefinition | null) => void
   isMobileMenuOpen: boolean
   setMobileMenuOpen: (open: boolean) => void
 
@@ -258,6 +263,24 @@ export const useStore = create<StoreState>((set) => ({
     return { theme: newTheme }
   }),
 
+  customTheme: null,
+  setCustomTheme: (theme) => {
+    if (theme && typeof localStorage !== 'undefined') saveThemeVarsToStorage(theme)
+    set({ customTheme: theme })
+  },
+
+  themeBuilderDraft: null,
+  setThemeBuilderDraft: (draft) => {
+    if (draft) {
+      applyCustomThemeToDOM(draft)
+      if (typeof localStorage !== 'undefined') saveThemeVarsToStorage(draft)
+    } else {
+      removeCustomThemeFromDOM()
+      if (typeof localStorage !== 'undefined') clearThemeVarsFromStorage()
+    }
+    set({ themeBuilderDraft: draft })
+  },
+
   isMobileMenuOpen: false,
   setMobileMenuOpen: (open) => set({ isMobileMenuOpen: open }),
 
@@ -451,7 +474,13 @@ if (typeof window !== 'undefined') {
     if (slice.searchFilters) {
       slice.searchFilters = { ...DEFAULT_SEARCH_FILTERS, ...slice.searchFilters }
     }
-    if (Object.keys(slice).length > 0) useStore.setState(slice)
+    if (Object.keys(slice).length > 0) {
+      useStore.setState(slice)
+      const restored = slice as Record<string, unknown>
+      if (restored.themeBuilderDraft) {
+        applyCustomThemeToDOM(restored.themeBuilderDraft as ThemeDefinition)
+      }
+    }
   }).catch(() => {})
 
   useStore.subscribe((state) => {
diff --git a/src/styles/themeTypes.ts b/src/styles/themeTypes.ts
new file mode 100644
index 00000000..b528d8f3
--- /dev/null
+++ b/src/styles/themeTypes.ts
@@ -0,0 +1,511 @@
+/**
+ * themeTypes.ts — Theme Builder data model
+ * Extends the binary light/dark system with a fully typed custom theme definition.
+ */
+
+// ─── Theme ID ──────────────────────────────────────────────────────────────────
+
+export type ThemeId = string
+
+// ─── Reference ─────────────────────────────────────────────────────────────────
+
+/** Built-in theme this custom theme was derived from */
+export type ThemePresetRef = 'light' | 'dark' | 'highContrast'
+
+// ─── Colors ────────────────────────────────────────────────────────────────────
+
+export interface ThemeColors {
+  background: string
+  surface: string
+  primary: string
+  secondary: string
+  text: string
+}
+
+// ─── Typography ────────────────────────────────────────────────────────────────
+
+export interface ThemeTypography {
+  fontFamily: string
+  fontScale: number
+}
+
+// ─── Spacing ───────────────────────────────────────────────────────────────────
+
+export interface ThemeSpacing {
+  baseUnit: number
+}
+
+// ─── Accessibility ─────────────────────────────────────────────────────────────
+
+export interface ThemeAccessibility {
+  score: number
+  contrastPass: boolean
+}
+
+// ─── Full Definition ───────────────────────────────────────────────────────────
+
+export interface ThemeDefinition {
+  id: ThemeId
+  name: string
+  preset?: ThemePresetRef
+  colors: ThemeColors
+  typography: ThemeTypography
+  spacing: ThemeSpacing
+  accessibility?: ThemeAccessibility
+}
+
+// ─── Storage key ───────────────────────────────────────────────────────────────
+
+export const CUSTOM_THEME_STORAGE_KEY = 'stellar-custom-theme'
+
+// ─── Built-in presets ──────────────────────────────────────────────────────────
+
+export const PRESET_THEMES: ThemeDefinition[] = [
+  {
+    id: 'dark',
+    name: 'Dark',
+    preset: 'dark',
+    colors: {
+      background: '#080c10',
+      surface: '#0d1318',
+      primary: '#00e5ff',
+      secondary: '#ffb300',
+      text: '#e8f4f8',
+    },
+    typography: {
+      fontFamily: "'Syne', sans-serif",
+      fontScale: 1.0,
+    },
+    spacing: {
+      baseUnit: 8,
+    },
+  },
+  {
+    id: 'light',
+    name: 'Light',
+    preset: 'light',
+    colors: {
+      background: '#f1f5f9',
+      surface: '#ffffff',
+      primary: '#0284c7',
+      secondary: '#ffb300',
+      text: '#0f172a',
+    },
+    typography: {
+      fontFamily: "'Syne', sans-serif",
+      fontScale: 1.0,
+    },
+    spacing: {
+      baseUnit: 8,
+    },
+  },
+  {
+    id: 'highContrast',
+    name: 'High Contrast',
+    preset: 'highContrast',
+    colors: {
+      background: '#000000',
+      surface: '#1a1a1a',
+      primary: '#ffff00',
+      secondary: '#00ffff',
+      text: '#ffffff',
+    },
+    typography: {
+      fontFamily: "'Syne', sans-serif",
+      fontScale: 1.15,
+    },
+    spacing: {
+      baseUnit: 10,
+    },
+  },
+]
+
+// ─── Defaults ──────────────────────────────────────────────────────────────────
+
+export const DEFAULT_THEME_DEFINITION: ThemeDefinition = PRESET_THEMES[0]
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Check if two color sets are identical */
+export function colorsMatch(a: ThemeColors, b: ThemeColors): boolean {
+  return a.background === b.background &&
+    a.surface === b.surface &&
+    a.primary === b.primary &&
+    a.secondary === b.secondary &&
+    a.text === b.text
+}
+
+/** Find which preset matches the given colors, or 'custom' if none */
+export function getActivePresetId(colors: ThemeColors): ThemePresetRef | 'custom' {
+  for (const preset of PRESET_THEMES) {
+    if (colorsMatch(preset.colors, colors)) return preset.preset || preset.id as ThemePresetRef
+  }
+  return 'custom'
+}
+
+export function generateThemeId(): ThemeId {
+  return `theme-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+export function isThemeDefinition(value: unknown): value is ThemeDefinition {
+  if (!value || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v.id === 'string' &&
+    typeof v.name === 'string' &&
+    typeof v.colors === 'object' &&
+    v.colors !== null &&
+    typeof (v.colors as Record<string, unknown>).background === 'string' &&
+    typeof (v.colors as Record<string, unknown>).surface === 'string' &&
+    typeof (v.colors as Record<string, unknown>).primary === 'string' &&
+    typeof (v.colors as Record<string, unknown>).secondary === 'string' &&
+    typeof (v.colors as Record<string, unknown>).text === 'string' &&
+    typeof v.typography === 'object' &&
+    v.typography !== null &&
+    typeof (v.typography as Record<string, unknown>).fontFamily === 'string' &&
+    typeof (v.typography as Record<string, unknown>).fontScale === 'number' &&
+    typeof v.spacing === 'object' &&
+    v.spacing !== null &&
+    typeof (v.spacing as Record<string, unknown>).baseUnit === 'number'
+  )
+}
+
+export function serializeTheme(theme: ThemeDefinition): string {
+  return JSON.stringify(theme, null, 2)
+}
+
+export function deserializeTheme(json: string): ThemeDefinition {
+  const parsed = JSON.parse(json)
+  if (!isThemeDefinition(parsed)) {
+    throw new Error('Invalid theme definition')
+  }
+  return parsed
+}
+
+// ─── Import / Export ───────────────────────────────────────────────────────────
+
+export interface ThemeExportMeta {
+  exportedAt: string
+  version: number
+}
+
+/** Wrap a theme with export metadata and serialize to JSON */
+export function exportTheme(theme: ThemeDefinition): string {
+  const wrapped = {
+    ...theme,
+    _meta: {
+      exportedAt: new Date().toISOString(),
+      version: 1,
+    } satisfies ThemeExportMeta,
+  }
+  return JSON.stringify(wrapped, null, 2)
+}
+
+/** Parse exported JSON, strip metadata, validate, and return the ThemeDefinition */
+export function importTheme(json: string): ThemeDefinition {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(json)
+  } catch {
+    throw new Error('Invalid file: not valid JSON')
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('Invalid theme: expected a JSON object')
+  }
+  const { _meta, ...themeData } = parsed as Record<string, unknown>
+  if (!isThemeDefinition(themeData)) {
+    throw new Error('Invalid theme: missing or invalid required fields')
+  }
+  return themeData
+}
+
+// ─── Storage key for FOUC prevention ──────────────────────────────────────────
+
+export const THEME_VARS_STORAGE_KEY = 'stellar-theme-vars'
+
+// ─── DOM application (CSS custom property injection) ─────────────────────────
+
+const THEME_CSS_KEYS = [
+  '--bg-base', '--bg-surface', '--bg-elevated', '--bg-card',
+  '--cyan', '--amber',
+  '--text-primary',
+  '--font-display', '--font-scale',
+  '--radius-sm', '--radius-md', '--radius-lg',
+] as const
+
+/** Extract CSS custom property map from a ThemeDefinition */
+export function getThemeCSSVars(theme: ThemeDefinition): Record<string, string> {
+  return {
+    '--bg-base': theme.colors.background,
+    '--bg-surface': theme.colors.surface,
+    '--bg-elevated': theme.colors.surface,
+    '--bg-card': theme.colors.surface,
+    '--cyan': theme.colors.primary,
+    '--amber': theme.colors.secondary,
+    '--text-primary': theme.colors.text,
+    '--font-display': theme.typography.fontFamily,
+    '--font-scale': String(theme.typography.fontScale),
+    '--radius-sm': `${Math.max(2, theme.spacing.baseUnit / 2)}px`,
+    '--radius-md': `${Math.max(4, theme.spacing.baseUnit)}px`,
+    '--radius-lg': `${theme.spacing.baseUnit * 2}px`,
+  }
+}
+
+/** Inject a ThemeDefinition into the document as CSS custom properties */
+export function applyCustomThemeToDOM(theme: ThemeDefinition): void {
+  const root = document.documentElement
+  if (!root) return
+  const vars = getThemeCSSVars(theme)
+  for (const [key, value] of Object.entries(vars)) {
+    root.style.setProperty(key, value)
+  }
+}
+
+/** Remove all custom theme CSS properties from the document */
+export function removeCustomThemeFromDOM(): void {
+  const root = document.documentElement
+  if (!root) return
+  for (const key of THEME_CSS_KEYS) root.style.removeProperty(key)
+}
+
+/** Persist CSS vars to localStorage for FOUC prevention on next page load */
+export function saveThemeVarsToStorage(theme: ThemeDefinition): void {
+  try {
+    const vars = getThemeCSSVars(theme)
+    localStorage.setItem(THEME_VARS_STORAGE_KEY, JSON.stringify(vars))
+    localStorage.setItem('stellar-dashboard-theme', 'custom')
+  } catch { /* quota exceeded or blocked */ }
+}
+
+/** Remove persisted theme vars from localStorage */
+export function clearThemeVarsFromStorage(): void {
+  try {
+    localStorage.removeItem(THEME_VARS_STORAGE_KEY)
+  } catch { /* ignore */ }
+}
+
+// ─── WCAG contrast (pure math, no DOM) ─────────────────────────────────────────
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace('#', '')
+  return [
+    parseInt(h.slice(0, 2), 16),
+    parseInt(h.slice(2, 4), 16),
+    parseInt(h.slice(4, 6), 16),
+  ]
+}
+
+function srgbChannel(c: number): number {
+  const s = c / 255
+  return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)
+}
+
+function relativeLuminance(hex: string): number {
+  const [r, g, b] = hexToRgb(hex)
+  return 0.2126 * srgbChannel(r) + 0.7152 * srgbChannel(g) + 0.0722 * srgbChannel(b)
+}
+
+export function calculateContrastRatio(foreground: string, background: string): number {
+  const l1 = relativeLuminance(foreground)
+  const l2 = relativeLuminance(background)
+  const lighter = Math.max(l1, l2)
+  const darker = Math.min(l1, l2)
+  return (lighter + 0.05) / (darker + 0.05)
+}
+
+const CRITICAL_PAIRS: [fg: keyof ThemeColors, bg: keyof ThemeColors][] = [
+  ['text', 'background'],
+  ['text', 'surface'],
+  ['primary', 'background'],
+  ['primary', 'surface'],
+  ['secondary', 'background'],
+  ['secondary', 'surface'],
+]
+
+export function getThemeAccessibility(theme: ThemeDefinition): ThemeAccessibility {
+  const ratios = CRITICAL_PAIRS.map(([fg, bg]) =>
+    calculateContrastRatio(theme.colors[fg], theme.colors[bg])
+  )
+  const minRatio = Math.min(...ratios)
+  return {
+    score: Math.round(minRatio * 10) / 10,
+    contrastPass: minRatio >= 4.5,
+  }
+}
+
+// ─── WCAG Levels ────────────────────────────────────────────────────────────────
+
+export type WCAGLevel = 'fail' | 'AA-large' | 'AA' | 'AAA'
+
+export function getWCAGLevel(ratio: number): WCAGLevel {
+  if (ratio >= 7) return 'AAA'
+  if (ratio >= 4.5) return 'AA'
+  if (ratio >= 3) return 'AA-large'
+  return 'fail'
+}
+
+// ─── Rich Accessibility Report ─────────────────────────────────────────────────
+
+export interface ContrastPairResult {
+  label: string
+  foreground: string
+  background: string
+  ratio: number
+  level: WCAGLevel
+  pass: boolean
+}
+
+export interface AccessibilityReport {
+  score: number
+  pairs: ContrastPairResult[]
+  pass: boolean
+  warnings: string[]
+}
+
+const PAIR_LABELS: Record<string, string> = {
+  'text/background': 'Body text on background',
+  'text/surface': 'Body text on surface',
+  'primary/background': 'Primary accent on background',
+  'primary/surface': 'Primary accent on surface',
+  'secondary/background': 'Secondary accent on background',
+  'secondary/surface': 'Secondary accent on surface',
+}
+
+function contrastScore(minRatio: number): number {
+  let score: number
+  if (minRatio < 3) {
+    score = (minRatio / 3) * 30
+  } else if (minRatio < 4.5) {
+    score = 30 + ((minRatio - 3) / 1.5) * 30
+  } else if (minRatio < 7) {
+    score = 60 + ((minRatio - 4.5) / 2.5) * 30
+  } else {
+    score = 90 + Math.min((minRatio - 7) / 14, 1) * 10
+  }
+  return Math.round(Math.min(100, Math.max(0, score)))
+}
+
+export function getAccessibilityReport(theme: ThemeDefinition): AccessibilityReport {
+  const pairs: ContrastPairResult[] = []
+  let minRatio = Infinity
+
+  for (const [fgKey, bgKey] of CRITICAL_PAIRS) {
+    const fg = theme.colors[fgKey]
+    const bg = theme.colors[bgKey]
+    const ratio = calculateContrastRatio(fg, bg)
+    const level = getWCAGLevel(ratio)
+    pairs.push({
+      label: PAIR_LABELS[`${fgKey}/${bgKey}`] || `${fgKey} on ${bgKey}`,
+      foreground: fg,
+      background: bg,
+      ratio,
+      level,
+      pass: level !== 'fail',
+    })
+    if (ratio < minRatio) minRatio = ratio
+  }
+
+  const score = contrastScore(minRatio)
+  const pass = pairs.every((p) => p.pass)
+
+  const warnings: string[] = []
+  for (const p of pairs) {
+    if (!p.pass) {
+      warnings.push(`${p.label}: fails WCAG AA (${p.ratio.toFixed(1)}:1)`)
+    } else if (p.level === 'AA-large') {
+      warnings.push(`${p.label}: passes for large text only (${p.ratio.toFixed(1)}:1)`)
+    }
+    if (p.ratio >= 4.5 && p.ratio < 5) {
+      warnings.push(`${p.label}: marginal AA pass (${p.ratio.toFixed(1)}:1)`)
+    }
+  }
+
+  return { score, pairs, pass, warnings }
+}
+
+// ─── Color Blindness Simulation ────────────────────────────────────────────────
+
+export type ColorBlindnessType = 'protanopia' | 'deuteranopia' | 'tritanopia'
+
+const CB_MATRICES: Record<ColorBlindnessType, readonly [number, number, number][]> = {
+  protanopia: [
+    [0.152, 0.848, 0.000],
+    [0.152, 0.848, 0.000],
+    [0.004, 0.000, 0.996],
+  ],
+  deuteranopia: [
+    [0.292, 0.708, 0.000],
+    [0.292, 0.708, 0.000],
+    [0.000, 0.000, 1.000],
+  ],
+  tritanopia: [
+    [0.967, 0.000, 0.033],
+    [0.000, 0.730, 0.270],
+    [0.000, 0.730, 0.270],
+  ],
+}
+
+export const CB_LABELS: Record<ColorBlindnessType, string> = {
+  protanopia: 'Protanopia (red-blind)',
+  deuteranopia: 'Deuteranopia (green-blind)',
+  tritanopia: 'Tritanopia (blue-blind)',
+}
+
+function linearizeSRGB(c: number): number {
+  const s = c / 255
+  return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)
+}
+
+function delinearizeSRGB(l: number): number {
+  const s = Math.max(0, Math.min(1, l))
+  const c = s <= 0.0031308 ? 12.92 * s : 1.055 * Math.pow(s, 1 / 2.4) - 0.055
+  return Math.round(Math.max(0, Math.min(255, c * 255)))
+}
+
+function applyCBMatrix(hex: string, matrix: readonly [number, number, number][]): string {
+  const [r, g, b] = hexToRgb(hex)
+  const [lr, lg, lb] = [r, g, b].map(linearizeSRGB)
+  const nr = matrix[0][0] * lr + matrix[0][1] * lg + matrix[0][2] * lb
+  const ng = matrix[1][0] * lr + matrix[1][1] * lg + matrix[1][2] * lb
+  const nb = matrix[2][0] * lr + matrix[2][1] * lg + matrix[2][2] * lb
+  const [cr, cg, cb] = [nr, ng, nb].map(delinearizeSRGB)
+  return `#${cr.toString(16).padStart(2, '0')}${cg.toString(16).padStart(2, '0')}${cb.toString(16).padStart(2, '0')}`
+}
+
+export function simulateColorBlindColor(hex: string, type: ColorBlindnessType): string {
+  return applyCBMatrix(hex, CB_MATRICES[type])
+}
+
+export const THEME_COLOR_KEYS: (keyof ThemeColors)[] = ['background', 'surface', 'primary', 'secondary', 'text']
+
+export function simulateColorBlindTheme(
+  theme: ThemeDefinition,
+  type: ColorBlindnessType
+): ThemeDefinition {
+  const colors = { ...theme.colors }
+  for (const key of THEME_COLOR_KEYS) {
+    colors[key] = simulateColorBlindColor(colors[key], type)
+  }
+  return { ...theme, colors }
+}
+
+export interface ColorBlindnessResult {
+  type: ColorBlindnessType
+  label: string
+  score: number
+  pairs: ContrastPairResult[]
+}
+
+export function getColorBlindnessResults(theme: ThemeDefinition): ColorBlindnessResult[] {
+  const types: ColorBlindnessType[] = ['protanopia', 'deuteranopia', 'tritanopia']
+  return types.map((type) => {
+    const simulated = simulateColorBlindTheme(theme, type)
+    const report = getAccessibilityReport(simulated)
+    return {
+      type,
+      label: CB_LABELS[type],
+      score: report.score,
+      pairs: report.pairs,
+    }
+  })
+}