@arraypress/theme-injector 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArrayPress Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# @arraypress/theme-injector
+
+CSS custom property theme engine. Injects theme configuration as CSS variables on `:root`. Supports background presets, auto-contrast colors, typography, border radius, surface styles, and custom CSS. Works with any CSS-variable-based design system.
+
+## Installation
+
+```bash
+npm install @arraypress/theme-injector
+```
+
+**Peer dependencies:**
+
+```bash
+npm install @arraypress/color-utils @arraypress/google-fonts
+```
+
+## Usage
+
+```js
+import { injectTheme } from '@arraypress/theme-injector';
+
+// Apply a dark theme with Inter font and green accent
+injectTheme({
+  font: 'inter',
+  headingFont: 'serif',
+  headingWeight: 'bold',
+  background: 'dark',
+  accentColor: '#06d6a0',
+  surface: 'shadow',
+  borderRadius: 'rounded',
+  contentWidth: 'standard',
+  sectionPadding: 'default',
+});
+
+// Custom background with auto-contrast
+injectTheme({
+  font: 'poppins',
+  background: 'custom',
+  customBg: '#1a1a2e',
+  accentColor: '#e94560',
+  surface: 'flat',
+  borderRadius: 'pill',
+});
+
+// Inject custom CSS
+injectTheme({
+  background: 'white',
+  customCSS: '.hero { min-height: 80vh; }',
+});
+```
+
+## Theme Config
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `font` | `string` | Body font key (e.g. `'inter'`, `'poppins'`, `'system'`) |
+| `headingFont` | `string` | Heading font key. `'inherit'` matches body font |
+| `headingWeight` | `string` | `'normal'`, `'bold'`, `'black'` |
+| `baseSize` | `string` | `'compact'` (14px), `'default'` (16px), `'large'` (18px), `'xlarge'` (20px) |
+| `headingSize` | `string` | `'small'` through `'massive'` (scale multiplier) |
+| `lineHeight` | `string` | `'tight'`, `'default'`, `'relaxed'`, `'loose'` |
+| `letterSpacing` | `string` | `'tight'`, `'default'`, `'wide'`, `'wider'` |
+| `background` | `string` | `'dark'`, `'soft-dark'`, `'light'`, `'white'`, `'custom'` |
+| `customBg` | `string` | Custom background hex (when `background: 'custom'`) |
+| `customCard` | `string` | Custom card hex (auto-generated if omitted) |
+| `customBorder` | `string` | Custom border color (auto-generated if omitted) |
+| `textColor` | `string` | Override foreground text color |
+| `mutedTextColor` | `string` | Override muted text color |
+| `accentColor` | `string` | Primary/accent hex. Default `'#06d6a0'` |
+| `buttonTextColor` | `string` | Button text color. Auto-calculated if omitted |
+| `surface` | `string` | `'bordered'`, `'shadow'`, `'flat'`, `'glass'` |
+| `borderRadius` | `string` | `'sharp'`, `'rounded'`, `'pill'` |
+| `buttonStyle` | `string` | `'rounded'`, `'sharp'`, `'pill'` |
+| `linkColor` | `string` | Link color |
+| `linkHoverColor` | `string` | Link hover color |
+| `contentWidth` | `string` | `'narrow'` (960px), `'standard'` (1200px), `'wide'` (1440px) |
+| `sectionPadding` | `string` | `'compact'` (2rem), `'default'` (3rem), `'spacious'` (5rem) |
+| `customCSS` | `string` | Raw CSS injected into `<style>` tag |
+
+## Exported Constants
+
+- `BACKGROUNDS` — 4 color scheme presets (dark, soft-dark, light, white)
+- `FONT_WEIGHTS` — Heading weight mappings (normal=500, bold=700, black=900)
+- `BASE_SIZES` — Root font sizes (compact, default, large, xlarge)
+- `HEADING_SCALES` — Heading size multipliers (small through massive)
+- `LINE_HEIGHTS` — Line height values (tight, default, relaxed, loose)
+- `LETTER_SPACINGS` — Letter spacing values (tight, default, wide, wider)
+- `CONTENT_WIDTHS` — Max content widths (narrow, standard, wide)
+- `SECTION_PADDINGS` — Section padding values (compact, default, spacious)
+- `RADII` — Border radius presets with xl/lg/md/sm/full values
+
+## CSS Variables Set
+
+The injector sets these CSS custom properties on `:root`:
+
+- `--font-sans` — Body font family
+- `--heading-font` — Heading font family
+- `--heading-weight` — Heading font weight
+- `--heading-scale` — Heading size multiplier
+- `--line-height` — Body line height
+- `--color-background`, `--color-foreground` — Page colors
+- `--color-card`, `--color-card-foreground` — Card colors
+- `--color-secondary`, `--color-secondary-foreground` — Secondary colors
+- `--color-muted`, `--color-muted-foreground` — Muted colors
+- `--color-border` — Border color
+- `--color-primary`, `--color-primary-foreground` — Accent colors
+- `--card-shadow` — Card shadow value
+- `--color-link`, `--color-link-hover` — Link colors
+- `--content-width` — Max content width
+- `--section-padding` — Section vertical padding
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@arraypress/theme-injector",
+  "version": "1.0.0",
+  "description": "CSS custom property theme engine. Injects theme configuration as CSS variables on :root. Supports background presets, auto-contrast colors, typography, border radius, surface styles, and custom CSS.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test tests/theme-injector.test.js"
+  },
+  "keywords": [
+    "theme",
+    "css-variables",
+    "custom-properties",
+    "dark-mode",
+    "light-mode",
+    "design-system",
+    "injector"
+  ],
+  "author": "David Sherlock",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arraypress/theme-injector.git"
+  },
+  "peerDependencies": {
+    "@arraypress/color-utils": ">=1",
+    "@arraypress/google-fonts": ">=1"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @arraypress/theme-injector — TypeScript definitions.
+ */
+
+/** Color scheme preset values. */
+export interface ColorScheme {
+  /** Background color. */
+  bg: string;
+  /** Card background color. */
+  card: string;
+  /** Secondary background color. */
+  secondary: string;
+  /** Muted background color. */
+  muted: string;
+  /** Border color (may be rgba). */
+  border: string;
+  /** Foreground (text) color. */
+  fg: string;
+  /** Muted foreground color. */
+  mutedFg: string;
+}
+
+/** Border radius preset values. */
+export interface RadiusPreset {
+  xl: string;
+  lg: string;
+  md: string;
+  sm: string;
+  full: string;
+}
+
+/** Background color scheme presets. */
+export declare const BACKGROUNDS: Record<'dark' | 'soft-dark' | 'light' | 'white', ColorScheme>;
+
+/** Heading font weight mappings. */
+export declare const FONT_WEIGHTS: Record<'normal' | 'bold' | 'black', string>;
+
+/** Base font size presets. */
+export declare const BASE_SIZES: Record<'compact' | 'default' | 'large' | 'xlarge', string>;
+
+/** Heading size scale multipliers. */
+export declare const HEADING_SCALES: Record<'small' | 'default' | 'large' | 'xlarge' | 'xxlarge' | 'massive', string>;
+
+/** Line height presets. */
+export declare const LINE_HEIGHTS: Record<'tight' | 'default' | 'relaxed' | 'loose', string>;
+
+/** Letter spacing presets. */
+export declare const LETTER_SPACINGS: Record<'tight' | 'default' | 'wide' | 'wider', string>;
+
+/** Content width presets. */
+export declare const CONTENT_WIDTHS: Record<'narrow' | 'standard' | 'wide', string>;
+
+/** Section vertical padding presets. */
+export declare const SECTION_PADDINGS: Record<'compact' | 'default' | 'spacious', string>;
+
+/** Border radius presets. */
+export declare const RADII: Record<'sharp' | 'rounded' | 'pill', RadiusPreset>;
+
+/** Theme configuration object. */
+export interface ThemeConfig {
+  /** Body font key (e.g. `'inter'`, `'poppins'`, `'system'`). */
+  font?: string;
+  /** Heading font key. Use `'inherit'` to match body font. */
+  headingFont?: string;
+  /** Heading weight: `'normal'`, `'bold'`, or `'black'`. */
+  headingWeight?: 'normal' | 'bold' | 'black';
+  /** Base font size: `'compact'`, `'default'`, `'large'`, `'xlarge'`. */
+  baseSize?: 'compact' | 'default' | 'large' | 'xlarge';
+  /** Heading scale: `'small'` through `'massive'`. */
+  headingSize?: 'small' | 'default' | 'large' | 'xlarge' | 'xxlarge' | 'massive';
+  /** Line height: `'tight'`, `'default'`, `'relaxed'`, `'loose'`. */
+  lineHeight?: 'tight' | 'default' | 'relaxed' | 'loose';
+  /** Letter spacing: `'tight'`, `'default'`, `'wide'`, `'wider'`. */
+  letterSpacing?: 'tight' | 'default' | 'wide' | 'wider';
+  /** Background preset or `'custom'`. */
+  background?: 'dark' | 'soft-dark' | 'light' | 'white' | 'custom';
+  /** Custom background hex color (when `background` is `'custom'`). */
+  customBg?: string;
+  /** Custom card hex color (when `background` is `'custom'`). Auto-generated if omitted. */
+  customCard?: string;
+  /** Custom border color (when `background` is `'custom'`). Auto-generated if omitted. */
+  customBorder?: string;
+  /** Override foreground text color. */
+  textColor?: string;
+  /** Override muted text color. */
+  mutedTextColor?: string;
+  /** Primary/accent color hex. Default `'#06d6a0'`. */
+  accentColor?: string;
+  /** Override button text color. Auto-calculated from accent luminance if omitted. */
+  buttonTextColor?: string;
+  /** Surface style: `'bordered'` (default), `'shadow'`, `'flat'`, `'glass'`. */
+  surface?: 'bordered' | 'shadow' | 'flat' | 'glass';
+  /** Border radius preset: `'sharp'`, `'rounded'`, `'pill'`. */
+  borderRadius?: 'sharp' | 'rounded' | 'pill';
+  /** Alias for `borderRadius`. */
+  radius?: 'sharp' | 'rounded' | 'pill';
+  /** Button style data attribute. */
+  buttonStyle?: 'rounded' | 'sharp' | 'pill';
+  /** Link color (any CSS color). */
+  linkColor?: string;
+  /** Link hover color (any CSS color). */
+  linkHoverColor?: string;
+  /** Content width: `'narrow'`, `'standard'`, `'wide'`. */
+  contentWidth?: 'narrow' | 'standard' | 'wide';
+  /** Section padding: `'compact'`, `'default'`, `'spacious'`. */
+  sectionPadding?: 'compact' | 'default' | 'spacious';
+  /** Raw CSS string injected into a `<style>` tag. */
+  customCSS?: string;
+}
+
+/**
+ * Inject a theme configuration as CSS custom properties on `:root`.
+ *
+ * Sets typography, colors, surface styles, border radius, layout, and custom CSS.
+ * SSR safe — no-op when `document` is not available.
+ *
+ * @param theme - Theme configuration object.
+ */
+export declare function injectTheme(theme: ThemeConfig | null | undefined): void;

package/src/index.js

@@ -0,0 +1,420 @@
+/**
+ * @arraypress/theme-injector
+ *
+ * CSS custom property theme engine. Injects theme configuration as CSS variables
+ * on `:root`. Supports background presets, auto-contrast colors, typography,
+ * border radius, surface styles, and custom CSS.
+ *
+ * Works with any CSS-variable-based design system. SSR safe.
+ */
+
+import { luminance, adjust } from '@arraypress/color-utils';
+import { getFontFamily, loadFont } from '@arraypress/google-fonts';
+
+/**
+ * Background color scheme presets.
+ *
+ * Each preset defines a complete color palette: background, card, secondary,
+ * muted, border, foreground, and muted foreground colors.
+ *
+ * @type {Record<string, { bg: string, card: string, secondary: string, muted: string, border: string, fg: string, mutedFg: string }>}
+ */
+export const BACKGROUNDS = {
+  dark: {
+    bg: '#09090b',
+    card: '#111113',
+    secondary: '#18181b',
+    muted: '#18181b',
+    border: 'rgba(255,255,255,0.06)',
+    fg: '#fafafa',
+    mutedFg: '#a1a1aa',
+  },
+  'soft-dark': {
+    bg: '#111113',
+    card: '#1a1a1e',
+    secondary: '#222226',
+    muted: '#222226',
+    border: 'rgba(255,255,255,0.08)',
+    fg: '#fafafa',
+    mutedFg: '#a1a1aa',
+  },
+  light: {
+    bg: '#fafafa',
+    card: '#ffffff',
+    secondary: '#f4f4f5',
+    muted: '#f4f4f5',
+    border: 'rgba(0,0,0,0.08)',
+    fg: '#09090b',
+    mutedFg: '#71717a',
+  },
+  white: {
+    bg: '#ffffff',
+    card: '#ffffff',
+    secondary: '#f4f4f5',
+    muted: '#f4f4f5',
+    border: 'rgba(0,0,0,0.06)',
+    fg: '#09090b',
+    mutedFg: '#71717a',
+  },
+};
+
+/**
+ * Heading font weight mappings.
+ *
+ * Maps human-readable weight names to CSS font-weight numeric values.
+ *
+ * @type {Record<string, string>}
+ */
+export const FONT_WEIGHTS = {
+  normal: '500',
+  bold: '700',
+  black: '900',
+};
+
+/**
+ * Base font size presets.
+ *
+ * Applied to the root element `font-size`, affecting all `rem`-based sizing.
+ *
+ * @type {Record<string, string>}
+ */
+export const BASE_SIZES = {
+  compact: '14px',
+  default: '16px',
+  large: '18px',
+  xlarge: '20px',
+};
+
+/**
+ * Heading size scale multipliers.
+ *
+ * Applied as `--heading-scale` CSS variable. Headings use
+ * `calc(base-heading-size * var(--heading-scale))` for proportional scaling.
+ *
+ * @type {Record<string, string>}
+ */
+export const HEADING_SCALES = {
+  small: '0.85',
+  default: '1',
+  large: '1.15',
+  xlarge: '1.3',
+  xxlarge: '1.5',
+  massive: '1.8',
+};
+
+/**
+ * Line height presets.
+ *
+ * @type {Record<string, string>}
+ */
+export const LINE_HEIGHTS = {
+  tight: '1.3',
+  default: '1.5',
+  relaxed: '1.7',
+  loose: '1.9',
+};
+
+/**
+ * Letter spacing presets.
+ *
+ * @type {Record<string, string>}
+ */
+export const LETTER_SPACINGS = {
+  tight: '-0.02em',
+  default: '0',
+  wide: '0.02em',
+  wider: '0.05em',
+};
+
+/**
+ * Content width presets for the main content container.
+ *
+ * @type {Record<string, string>}
+ */
+export const CONTENT_WIDTHS = {
+  narrow: '960px',
+  standard: '1200px',
+  wide: '1440px',
+};
+
+/**
+ * Section vertical padding presets.
+ *
+ * @type {Record<string, string>}
+ */
+export const SECTION_PADDINGS = {
+  compact: '2rem',
+  default: '3rem',
+  spacious: '5rem',
+};
+
+/**
+ * Border radius presets.
+ *
+ * Each preset defines radius values for xl, lg, md, sm, and full sizes.
+ *
+ * @type {Record<string, { xl: string, lg: string, md: string, sm: string, full: string }>}
+ */
+export const RADII = {
+  sharp: { xl: '0px', lg: '0px', md: '0px', sm: '0px', full: '0px' },
+  rounded: { xl: '12px', lg: '8px', md: '6px', sm: '4px', full: '9999px' },
+  pill: { xl: '24px', lg: '16px', md: '12px', sm: '8px', full: '9999px' },
+};
+
+/**
+ * Apply a complete color scheme to the document root.
+ *
+ * Sets CSS custom properties for background, foreground, card, secondary,
+ * muted, and border colors. Also sets `document.body` inline styles for
+ * background-color and color.
+ *
+ * @param {HTMLElement} root - The document root element (`document.documentElement`).
+ * @param {string} bg - Background color.
+ * @param {string} card - Card background color.
+ * @param {string} secondary - Secondary background color.
+ * @param {string} muted - Muted background color.
+ * @param {string} border - Border color.
+ * @param {string} fg - Foreground (text) color.
+ * @param {string} mutedFg - Muted foreground color.
+ * @returns {void}
+ */
+function applyColorScheme(root, bg, card, secondary, muted, border, fg, mutedFg) {
+  root.style.setProperty('--color-background', bg);
+  root.style.setProperty('--color-foreground', fg);
+  root.style.setProperty('--color-card', card);
+  root.style.setProperty('--color-card-foreground', fg);
+  root.style.setProperty('--color-secondary', secondary);
+  root.style.setProperty('--color-secondary-foreground', fg);
+  root.style.setProperty('--color-muted', muted);
+  root.style.setProperty('--color-muted-foreground', mutedFg);
+  root.style.setProperty('--color-border', border);
+  document.body.style.backgroundColor = bg;
+  document.body.style.color = fg;
+}
+
+/**
+ * Inject a theme configuration as CSS custom properties on `:root`.
+ *
+ * This is the main entry point. Pass a theme config object and it will:
+ * - Set typography CSS variables (font family, heading font, weights, sizes)
+ * - Load required Google Fonts
+ * - Apply background color schemes (preset or custom with auto-contrast)
+ * - Set accent/primary colors with auto-calculated foreground contrast
+ * - Configure surface styles (bordered, shadow, flat, glass)
+ * - Apply border radius presets
+ * - Set button style data attributes
+ * - Configure layout (content width, section padding)
+ * - Inject custom CSS
+ * - Write a `<style>` tag with `!important` overrides for cascade safety
+ *
+ * SSR safe — no-op when `document` is not available.
+ *
+ * @param {object} theme - Theme configuration object.
+ * @param {string} [theme.font] - Body font key (e.g. `'inter'`, `'poppins'`, `'system'`).
+ * @param {string} [theme.headingFont] - Heading font key. Use `'inherit'` to match body font.
+ * @param {string} [theme.headingWeight] - Heading weight: `'normal'`, `'bold'`, or `'black'`.
+ * @param {string} [theme.baseSize] - Base font size: `'compact'`, `'default'`, `'large'`, `'xlarge'`.
+ * @param {string} [theme.headingSize] - Heading scale: `'small'`, `'default'`, `'large'`, `'xlarge'`, `'xxlarge'`, `'massive'`.
+ * @param {string} [theme.lineHeight] - Line height: `'tight'`, `'default'`, `'relaxed'`, `'loose'`.
+ * @param {string} [theme.letterSpacing] - Letter spacing: `'tight'`, `'default'`, `'wide'`, `'wider'`.
+ * @param {string} [theme.background] - Background preset: `'dark'`, `'soft-dark'`, `'light'`, `'white'`, or `'custom'`.
+ * @param {string} [theme.customBg] - Custom background hex color (when `background` is `'custom'`).
+ * @param {string} [theme.customCard] - Custom card hex color (when `background` is `'custom'`). Auto-generated if omitted.
+ * @param {string} [theme.customBorder] - Custom border color (when `background` is `'custom'`). Auto-generated if omitted.
+ * @param {string} [theme.textColor] - Override foreground text color (any CSS color).
+ * @param {string} [theme.mutedTextColor] - Override muted text color (any CSS color).
+ * @param {string} [theme.accentColor] - Primary/accent color hex (default `'#06d6a0'`).
+ * @param {string} [theme.buttonTextColor] - Override button text color. Auto-calculated from accent luminance if omitted.
+ * @param {string} [theme.surface] - Surface style: `'bordered'` (default), `'shadow'`, `'flat'`, `'glass'`.
+ * @param {string} [theme.borderRadius] - Border radius preset: `'sharp'`, `'rounded'`, `'pill'`.
+ * @param {string} [theme.radius] - Alias for `borderRadius`.
+ * @param {string} [theme.buttonStyle] - Button style data attribute: `'rounded'`, `'sharp'`, `'pill'`.
+ * @param {string} [theme.linkColor] - Link color (any CSS color).
+ * @param {string} [theme.linkHoverColor] - Link hover color (any CSS color).
+ * @param {string} [theme.contentWidth] - Content width: `'narrow'`, `'standard'`, `'wide'`.
+ * @param {string} [theme.sectionPadding] - Section padding: `'compact'`, `'default'`, `'spacious'`.
+ * @param {string} [theme.customCSS] - Raw CSS string injected into a `<style>` tag.
+ * @returns {void}
+ */
+export function injectTheme(theme) {
+  if (!theme) return;
+  if (typeof document === 'undefined') return;
+
+  const root = document.documentElement;
+
+  // --- Typography ---
+
+  const fontFamily = getFontFamily(theme.font);
+  if (theme.font && fontFamily) {
+    root.style.setProperty('--font-sans', fontFamily);
+  } else if (theme.font) {
+    root.style.removeProperty('--font-sans');
+  }
+
+  // Heading font (separate from body)
+  if (theme.headingFont && theme.headingFont !== 'inherit') {
+    const headingFamily = getFontFamily(theme.headingFont);
+    if (headingFamily) {
+      root.style.setProperty('--heading-font', headingFamily);
+    }
+  } else {
+    root.style.removeProperty('--heading-font');
+  }
+
+  if (theme.headingWeight) {
+    root.style.setProperty('--heading-weight', FONT_WEIGHTS[theme.headingWeight] || '700');
+  }
+
+  if (theme.baseSize) {
+    root.style.fontSize = BASE_SIZES[theme.baseSize] || '16px';
+  }
+
+  if (theme.headingSize) {
+    root.style.setProperty('--heading-scale', HEADING_SCALES[theme.headingSize] || '1');
+  }
+
+  // Line height
+  if (theme.lineHeight && theme.lineHeight !== 'default') {
+    root.style.setProperty('--line-height', LINE_HEIGHTS[theme.lineHeight] || '1.5');
+    document.body.style.lineHeight = LINE_HEIGHTS[theme.lineHeight] || '1.5';
+  } else {
+    root.style.removeProperty('--line-height');
+    document.body.style.removeProperty('line-height');
+  }
+
+  // Letter spacing
+  if (theme.letterSpacing && theme.letterSpacing !== 'default') {
+    document.body.style.letterSpacing = LETTER_SPACINGS[theme.letterSpacing] || '0';
+  } else {
+    document.body.style.removeProperty('letter-spacing');
+  }
+
+  // --- Background & Colors ---
+
+  if (theme.background === 'custom') {
+    const bg = theme.customBg || '#09090b';
+    const isLight = luminance(bg) > 128;
+    const card = theme.customCard || (isLight ? adjust(bg, -8) : adjust(bg, 12));
+    const secondary = isLight ? adjust(bg, -15) : adjust(bg, 18);
+    const muted = secondary;
+    const border = theme.customBorder || (isLight ? 'rgba(0,0,0,0.08)' : 'rgba(255,255,255,0.06)');
+    const fg = isLight ? '#09090b' : '#fafafa';
+    const mutedFg = isLight ? '#71717a' : '#a1a1aa';
+    applyColorScheme(root, bg, card, secondary, muted, border, fg, mutedFg);
+  } else if (theme.background && BACKGROUNDS[theme.background]) {
+    const b = BACKGROUNDS[theme.background];
+    applyColorScheme(root, b.bg, b.card, b.secondary, b.muted, b.border, b.fg, b.mutedFg);
+  }
+
+  // Text color overrides (after background to allow custom override)
+  if (theme.textColor) {
+    root.style.setProperty('--color-foreground', theme.textColor);
+    root.style.setProperty('--color-card-foreground', theme.textColor);
+    document.body.style.color = theme.textColor;
+  }
+  if (theme.mutedTextColor) {
+    root.style.setProperty('--color-muted-foreground', theme.mutedTextColor);
+  }
+
+  // --- Accent/Primary Color ---
+
+  const accent = (theme.accentColor || '#06d6a0').trim();
+  root.style.setProperty('--color-primary', accent);
+  const primaryFg = theme.buttonTextColor || (luminance(accent) > 160 ? '#000000' : '#ffffff');
+  root.style.setProperty('--color-primary-foreground', primaryFg);
+
+  // --- Surface Style ---
+
+  const bgHex = theme.background === 'custom'
+    ? (theme.customBg || '#09090b')
+    : (theme.background === 'light' || theme.background === 'white') ? '#fafafa' : '#09090b';
+  const isLightTheme = luminance(bgHex) > 128;
+
+  if (theme.surface === 'glass') {
+    root.style.setProperty('--card-shadow', 'none');
+    document.body.setAttribute('data-card-style', 'glass');
+  } else if (theme.surface === 'shadow') {
+    const shadow = isLightTheme
+      ? '0 1px 3px rgba(0,0,0,0.08), 0 4px 12px rgba(0,0,0,0.06)'
+      : '0 2px 8px rgba(0,0,0,0.3), 0 1px 3px rgba(0,0,0,0.2)';
+    root.style.setProperty('--card-shadow', shadow);
+    document.body.setAttribute('data-card-style', 'shadow');
+  } else if (theme.surface === 'flat') {
+    root.style.setProperty('--card-shadow', 'none');
+    document.body.setAttribute('data-card-style', 'flat');
+  } else {
+    root.style.removeProperty('--card-shadow');
+    document.body.removeAttribute('data-card-style');
+  }
+
+  // --- Border Radius ---
+
+  const radiusKey = theme.borderRadius || theme.radius;
+  if (radiusKey && radiusKey !== 'rounded') {
+    document.body.setAttribute('data-radius', radiusKey);
+  } else {
+    document.body.removeAttribute('data-radius');
+  }
+
+  // --- Button Style ---
+
+  if (theme.buttonStyle && theme.buttonStyle !== 'rounded') {
+    document.documentElement.dataset.buttonStyle = theme.buttonStyle;
+  } else {
+    delete document.documentElement.dataset.buttonStyle;
+  }
+
+  // --- Link Colors ---
+
+  if (theme.linkColor) root.style.setProperty('--color-link', theme.linkColor);
+  if (theme.linkHoverColor) root.style.setProperty('--color-link-hover', theme.linkHoverColor);
+
+  // --- Layout ---
+
+  if (theme.contentWidth) {
+    root.style.setProperty('--content-width', CONTENT_WIDTHS[theme.contentWidth] || '1200px');
+  }
+
+  if (theme.sectionPadding) {
+    root.style.setProperty('--section-padding', SECTION_PADDINGS[theme.sectionPadding] || '3rem');
+  }
+
+  // --- Load Google Fonts ---
+
+  loadFont(theme.font);
+  loadFont(theme.headingFont);
+
+  // --- Cascade Override Style Tag ---
+
+  const overrides = [];
+  const props = root.style;
+  for (let i = 0; i < props.length; i++) {
+    const prop = props[i];
+    if (prop.startsWith('--')) {
+      overrides.push(`${prop}: ${props.getPropertyValue(prop)} !important`);
+    }
+  }
+  if (overrides.length > 0) {
+    let styleEl = document.getElementById('sugarcart-theme-overrides');
+    if (!styleEl) {
+      styleEl = document.createElement('style');
+      styleEl.id = 'sugarcart-theme-overrides';
+      document.head.appendChild(styleEl);
+    }
+    styleEl.textContent = `:root { ${overrides.join('; ')}; }`;
+  }
+
+  // --- Custom CSS ---
+
+  let customStyleEl = document.getElementById('sugarcart-custom-css');
+  if (theme.customCSS) {
+    if (!customStyleEl) {
+      customStyleEl = document.createElement('style');
+      customStyleEl.id = 'sugarcart-custom-css';
+      document.head.appendChild(customStyleEl);
+    }
+    customStyleEl.textContent = theme.customCSS;
+  } else if (customStyleEl) {
+    customStyleEl.textContent = '';
+  }
+}