vue-multiple-themes 6.0.2 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-multiple-themes",
-  "version": "6.0.2",
+  "version": "7.0.0",
   "description": "Vue 3 multi-theme engine: CSS custom properties, TailwindCSS opacity modifiers, white-label brand contexts, composable API",
   "author": "Pooya Golchian <pooya.golchian@gmail.com>",
   "license": "MIT",
@@ -30,6 +30,25 @@
     "dist",
     "src"
   ],
+  "scripts": {
+    "dev": "pnpm --filter playground dev",
+    "build": "vite build",
+    "build:check": "vue-tsc --noEmit",
+    "build:playground": "pnpm --filter playground build",
+    "preview": "pnpm --filter playground preview",
+    "generate:logo": "node scripts/generate-logo.mjs",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "prepublishOnly": "pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "pnpm build:check"
+  },
   "keywords": [
     "vue",
     "vue3",
@@ -52,8 +71,20 @@
     "nuxt",
     "white-label",
     "brand-context",
-    "namespace"
+    "namespace",
+    "accessibility",
+    "a11y",
+    "color-utilities",
+    "theme-generator",
+    "multi-tenant",
+    "micro-frontend",
+    "vite",
+    "zero-dependencies"
   ],
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/pooyagolchian"
+  },
   "homepage": "https://pooyagolchian.github.io/vue-multiple-themes",
   "repository": {
     "type": "git",
@@ -70,18 +101,21 @@
       "optional": false
     }
   },
-  "dependencies": {},
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
     "@types/node": "^20.14.0",
     "@vitejs/plugin-vue": "^6.0.0",
+    "@vue/test-utils": "^2.4.6",
     "autoprefixer": "^10.4.19",
+    "happy-dom": "^20.8.3",
     "postcss": "^8.4.38",
     "sharp": "^0.34.5",
     "tailwindcss": "^3.4.4",
     "typescript": "^5.7.0",
     "vite": "^6.0.0",
     "vite-plugin-dts": "^4.0.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^4.0.18",
     "vue": "^3.5.0",
     "vue-tsc": "^2.1.0"
   },
@@ -89,16 +123,5 @@
     "node": ">=18",
     "pnpm": ">=9"
   },
-  "scripts": {
-    "dev": "pnpm --filter playground dev",
-    "build": "vite build",
-    "build:check": "vue-tsc --noEmit",
-    "build:playground": "pnpm --filter playground build",
-    "preview": "pnpm --filter playground preview",
-    "generate:logo": "node scripts/generate-logo.mjs",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm build && changeset publish",
-    "test": "pnpm build:check"
-  }
+  "packageManager": "pnpm@9.4.0"
 }

package/readme.md

@@ -7,7 +7,37 @@
 > Dynamic multi-theme support for **Vue 3** — CSS custom properties, TailwindCSS (with full opacity modifier support), WCAG contrast utilities, white-label brand contexts, and a reactive composable API.
 
 [![npm version](https://img.shields.io/npm/v/vue-multiple-themes)](https://www.npmjs.com/package/vue-multiple-themes)
+[![npm downloads](https://img.shields.io/npm/dm/vue-multiple-themes)](https://www.npmjs.com/package/vue-multiple-themes)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Vue 3](https://img.shields.io/badge/Vue-3.5+-4FC08D?logo=vuedotjs&logoColor=white)](https://vuejs.org/)
+[![TailwindCSS](https://img.shields.io/badge/Tailwind_CSS-v3_%26_v4-38B2AC?logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/vue-multiple-themes)
+[![Tests](https://img.shields.io/badge/tests-116_passing-brightgreen)](https://github.com/pooyagolchian/vue-multiple-themes)
+
+---
+
+## Why vue-multiple-themes?
+
+Most Vue theming solutions only handle light/dark toggling. **vue-multiple-themes** is a complete multi-theme engine for production applications.
+
+### Comparison with Alternatives
+
+| Feature | vue-multiple-themes | @vueuse useColorMode | nuxt-color-mode |
+|---|:---:|:---:|:---:|
+| **Multiple themes (3+)** | ✅ Unlimited | ⚠️ Manual | ⚠️ Light/Dark only |
+| **TailwindCSS v3 & v4 plugin** | ✅ Built-in | ❌ | ❌ |
+| **Opacity modifiers** (`bg-primary/50`) | ✅ | ❌ | ❌ |
+| **WCAG contrast utilities** | ✅ 5+ functions | ❌ | ❌ |
+| **Theme generation from 1 color** | ✅ | ❌ | ❌ |
+| **White-label / namespace** | ✅ `createBrandContext()` | ❌ | ❌ |
+| **Color utility library** | ✅ 20+ functions | ❌ | ❌ |
+| **Preset themes** | ✅ 7 included | ❌ | ❌ |
+| **System preference** | ✅ | ✅ | ✅ |
+| **TypeScript** | ✅ Full | ✅ | ✅ |
+| **Zero dependencies** | ✅ | ❌ | ❌ |
+
+> 📖 **[Full documentation →](https://pooyagolchian.github.io/vue-multiple-themes/)**
 
 ---
 
@@ -436,6 +466,19 @@ Full documentation and live demos:
 
 **<https://pooyagolchian.github.io/vue-multiple-themes/>**
 
+- [Getting Started](https://pooyagolchian.github.io/vue-multiple-themes/guide/getting-started)
+- [API Reference](https://pooyagolchian.github.io/vue-multiple-themes/api/)
+- [TailwindCSS Integration](https://pooyagolchian.github.io/vue-multiple-themes/guide/tailwind)
+- [White-Label / Multi-Tenant](https://pooyagolchian.github.io/vue-multiple-themes/guide/brand-context)
+- [Theme Generation](https://pooyagolchian.github.io/vue-multiple-themes/guide/generation)
+- [Color Utilities](https://pooyagolchian.github.io/vue-multiple-themes/guide/color-utils)
+- [Nuxt / SSR](https://pooyagolchian.github.io/vue-multiple-themes/guide/nuxt-ssr)
+- [Comparison with Alternatives](https://pooyagolchian.github.io/vue-multiple-themes/guide/comparison)
+
+### For AI / LLMs
+
+This project includes an [`llms.txt`](llms.txt) file following the [llmstxt.org](https://llmstxt.org) specification, providing structured API documentation for AI assistants.
+
 ---
 
 ## License

package/src/composables/createBrandContext.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createBrandContext } from './createBrandContext'
+import { lightTheme, darkTheme } from '../themes/presets'
+import type { ThemeDefinition } from '../types'
+
+const testThemes: ThemeDefinition[] = [
+  {
+    name: 'brand-light',
+    label: 'Brand Light',
+    colors: {
+      primary: '#7c3aed',
+      background: '#ffffff',
+      text: '#111827',
+      surface: '#f8fafc',
+      border: '#e5e7eb',
+    },
+  },
+  {
+    name: 'brand-dark',
+    label: 'Brand Dark',
+    colors: {
+      primary: '#a78bfa',
+      background: '#0f172a',
+      text: '#f8fafc',
+      surface: '#1e293b',
+      border: '#334155',
+    },
+  },
+]
+
+describe('createBrandContext', () => {
+  it('creates a context with correct namespace', () => {
+    const ctx = createBrandContext({
+      namespace: 'acme',
+      themes: testThemes,
+      defaultTheme: 'brand-light',
+    })
+    expect(ctx.namespace).toBe('acme')
+  })
+
+  it('exposes useTheme as a function', () => {
+    const ctx = createBrandContext({
+      namespace: 'beta',
+      themes: testThemes,
+    })
+    expect(typeof ctx.useTheme).toBe('function')
+  })
+
+  it('exposes BrandPlugin with install method', () => {
+    const ctx = createBrandContext({
+      namespace: 'gamma',
+      themes: testThemes,
+    })
+    expect(typeof ctx.BrandPlugin.install).toBe('function')
+  })
+
+  it('two contexts with different namespaces are independent', () => {
+    const ctx1 = createBrandContext({
+      namespace: 'brand-a',
+      themes: testThemes,
+    })
+    const ctx2 = createBrandContext({
+      namespace: 'brand-b',
+      themes: [lightTheme, darkTheme],
+    })
+    expect(ctx1.namespace).not.toBe(ctx2.namespace)
+  })
+})

package/src/utils/color.test.ts

@@ -0,0 +1,395 @@
+import { describe, it, expect } from 'vitest'
+import {
+  hexToRgb,
+  rgbToHex,
+  rgbToHsl,
+  hslToRgb,
+  hexToHsl,
+  hslToHex,
+  parseColor,
+  lighten,
+  darken,
+  saturate,
+  rotateHue,
+  mix,
+  withAlpha,
+  luminance,
+  contrastRatio,
+  autoContrast,
+  ensureContrast,
+  generateColorScale,
+  complementary,
+  splitComplementary,
+  triadic,
+  analogous,
+  normalizeToRgbChannels,
+} from './color'
+
+// ─── Parsing / Conversion ─────────────────────────────────────────────────────
+
+describe('hexToRgb', () => {
+  it('converts 6-digit hex', () => {
+    expect(hexToRgb('#3b82f6')).toEqual([59, 130, 246])
+  })
+
+  it('converts 3-digit shorthand hex', () => {
+    expect(hexToRgb('#fff')).toEqual([255, 255, 255])
+  })
+
+  it('handles black', () => {
+    expect(hexToRgb('#000000')).toEqual([0, 0, 0])
+  })
+
+  it('works without # prefix', () => {
+    expect(hexToRgb('ff0000')).toEqual([255, 0, 0])
+  })
+})
+
+describe('rgbToHex', () => {
+  it('converts RGB to hex', () => {
+    expect(rgbToHex(59, 130, 246)).toBe('#3b82f6')
+  })
+
+  it('converts black', () => {
+    expect(rgbToHex(0, 0, 0)).toBe('#000000')
+  })
+
+  it('converts white', () => {
+    expect(rgbToHex(255, 255, 255)).toBe('#ffffff')
+  })
+
+  it('clamps out-of-range values', () => {
+    expect(rgbToHex(300, -10, 128)).toBe('#ff0080')
+  })
+})
+
+describe('rgbToHsl', () => {
+  it('converts pure red', () => {
+    expect(rgbToHsl(255, 0, 0)).toEqual([0, 100, 50])
+  })
+
+  it('converts grey', () => {
+    const [h, s, l] = rgbToHsl(128, 128, 128)
+    expect(s).toBe(0)
+    expect(l).toBe(50)
+  })
+
+  it('converts white', () => {
+    expect(rgbToHsl(255, 255, 255)).toEqual([0, 0, 100])
+  })
+})
+
+describe('hslToRgb', () => {
+  it('converts achromatic (grey)', () => {
+    const [r, g, b] = hslToRgb(0, 0, 50)
+    expect(r).toBe(g)
+    expect(r).toBe(b)
+    expect(r).toBe(128)
+  })
+
+  it('converts pure red', () => {
+    expect(hslToRgb(0, 100, 50)).toEqual([255, 0, 0])
+  })
+
+  it('roundtrips with rgbToHsl', () => {
+    const original: [number, number, number] = [59, 130, 246]
+    const hsl = rgbToHsl(...original)
+    const back = hslToRgb(...hsl)
+    // Allow ±1 for rounding
+    for (let i = 0; i < 3; i++) {
+      expect(Math.abs(back[i] - original[i])).toBeLessThanOrEqual(1)
+    }
+  })
+})
+
+describe('hexToHsl / hslToHex roundtrip', () => {
+  it('roundtrips #3b82f6', () => {
+    const hsl = hexToHsl('#3b82f6')
+    const hex = hslToHex(...hsl)
+    const [r1, g1, b1] = hexToRgb('#3b82f6')
+    const [r2, g2, b2] = hexToRgb(hex)
+    expect(Math.abs(r1 - r2)).toBeLessThanOrEqual(1)
+    expect(Math.abs(g1 - g2)).toBeLessThanOrEqual(1)
+    expect(Math.abs(b1 - b2)).toBeLessThanOrEqual(1)
+  })
+})
+
+describe('parseColor', () => {
+  it('parses hex', () => {
+    const [h, s, l] = parseColor('#ff0000')
+    expect(h).toBe(0)
+    expect(s).toBe(100)
+    expect(l).toBe(50)
+  })
+
+  it('parses rgb()', () => {
+    const [h, s, l] = parseColor('rgb(255, 0, 0)')
+    expect(h).toBe(0)
+    expect(s).toBe(100)
+    expect(l).toBe(50)
+  })
+
+  it('parses hsl()', () => {
+    const hsl = parseColor('hsl(220, 90%, 56%)')
+    expect(hsl).toEqual([220, 90, 56])
+  })
+
+  it('returns fallback for unknown format', () => {
+    const hsl = parseColor('not-a-color')
+    expect(hsl).toEqual([220, 90, 56])
+  })
+})
+
+// ─── Manipulation ─────────────────────────────────────────────────────────────
+
+describe('lighten', () => {
+  it('increases lightness', () => {
+    const result = lighten('#3b82f6', 20)
+    const [, , l] = hexToHsl(result)
+    const [, , originalL] = hexToHsl('#3b82f6')
+    expect(l).toBeGreaterThan(originalL)
+  })
+
+  it('does not exceed 100', () => {
+    const result = lighten('#ffffff', 50)
+    const [, , l] = hexToHsl(result)
+    expect(l).toBeLessThanOrEqual(100)
+  })
+})
+
+describe('darken', () => {
+  it('decreases lightness', () => {
+    const result = darken('#3b82f6', 20)
+    const [, , l] = hexToHsl(result)
+    const [, , originalL] = hexToHsl('#3b82f6')
+    expect(l).toBeLessThan(originalL)
+  })
+
+  it('does not go below 0', () => {
+    const result = darken('#000000', 50)
+    const [, , l] = hexToHsl(result)
+    expect(l).toBeGreaterThanOrEqual(0)
+  })
+})
+
+describe('saturate', () => {
+  it('increases saturation', () => {
+    const result = saturate('#808080', 20)
+    const [, s] = hexToHsl(result)
+    expect(s).toBeGreaterThan(0)
+  })
+
+  it('clamps to 100', () => {
+    const result = saturate('#ff0000', 200)
+    const [, s] = hexToHsl(result)
+    expect(s).toBeLessThanOrEqual(100)
+  })
+})
+
+describe('rotateHue', () => {
+  it('rotates hue by degrees', () => {
+    const complement = rotateHue('#ff0000', 180)
+    const [h] = hexToHsl(complement)
+    expect(h).toBe(180)
+  })
+
+  it('wraps around 360', () => {
+    const result = rotateHue('#ff0000', 400)
+    const [h] = hexToHsl(result)
+    expect(h).toBe(40)
+  })
+
+  it('handles negative degrees', () => {
+    const result = rotateHue('#ff0000', -90)
+    const [h] = hexToHsl(result)
+    expect(h).toBe(270)
+  })
+})
+
+describe('mix', () => {
+  it('mixes two colors at 50%', () => {
+    const result = mix('#000000', '#ffffff', 0.5)
+    const [r, g, b] = hexToRgb(result)
+    expect(r).toBeCloseTo(128, -1)
+    expect(g).toBeCloseTo(128, -1)
+    expect(b).toBeCloseTo(128, -1)
+  })
+
+  it('returns first color at weight 0', () => {
+    expect(mix('#ff0000', '#0000ff', 0)).toBe('#ff0000')
+  })
+
+  it('returns second color at weight 1', () => {
+    expect(mix('#ff0000', '#0000ff', 1)).toBe('#0000ff')
+  })
+})
+
+describe('withAlpha', () => {
+  it('returns rgba string', () => {
+    expect(withAlpha('#ff0000', 0.5)).toBe('rgba(255,0,0,0.5)')
+  })
+
+  it('handles full opacity', () => {
+    expect(withAlpha('#000000', 1)).toBe('rgba(0,0,0,1)')
+  })
+})
+
+// ─── Contrast & Accessibility ─────────────────────────────────────────────────
+
+describe('luminance', () => {
+  it('returns 0 for black', () => {
+    expect(luminance('#000000')).toBeCloseTo(0, 4)
+  })
+
+  it('returns 1 for white', () => {
+    expect(luminance('#ffffff')).toBeCloseTo(1, 4)
+  })
+
+  it('returns mid-range for mid-grey', () => {
+    const lum = luminance('#808080')
+    expect(lum).toBeGreaterThan(0.1)
+    expect(lum).toBeLessThan(0.5)
+  })
+})
+
+describe('contrastRatio', () => {
+  it('max contrast is 21:1 for black vs white', () => {
+    expect(contrastRatio('#000000', '#ffffff')).toBeCloseTo(21, 0)
+  })
+
+  it('same color has ratio 1:1', () => {
+    expect(contrastRatio('#3b82f6', '#3b82f6')).toBeCloseTo(1, 0)
+  })
+
+  it('is symmetric', () => {
+    const ab = contrastRatio('#3b82f6', '#ffffff')
+    const ba = contrastRatio('#ffffff', '#3b82f6')
+    expect(ab).toBeCloseTo(ba, 4)
+  })
+})
+
+describe('autoContrast', () => {
+  it('picks white text on dark background', () => {
+    expect(autoContrast('#0f172a')).toBe('#ffffff')
+  })
+
+  it('picks black text on light background', () => {
+    expect(autoContrast('#ffffff')).toBe('#000000')
+  })
+})
+
+describe('ensureContrast', () => {
+  it('adjusts text color until WCAG AA contrast is met', () => {
+    const adjusted = ensureContrast('#cccccc', '#ffffff', 4.5)
+    const ratio = contrastRatio(adjusted, '#ffffff')
+    expect(ratio).toBeGreaterThanOrEqual(4.5)
+  })
+
+  it('returns original if already passing', () => {
+    const result = ensureContrast('#000000', '#ffffff', 4.5)
+    expect(result).toBe('#000000')
+  })
+})
+
+// ─── Color Scale ──────────────────────────────────────────────────────────────
+
+describe('generateColorScale', () => {
+  it('returns 11 stops', () => {
+    const scale = generateColorScale('#3b82f6')
+    const keys = Object.keys(scale)
+    expect(keys).toHaveLength(11)
+    expect(keys).toContain('50')
+    expect(keys).toContain('500')
+    expect(keys).toContain('950')
+  })
+
+  it('50 is lightest, 950 is darkest', () => {
+    const scale = generateColorScale('#3b82f6')
+    const l50 = hexToHsl(scale['50'])[2]
+    const l950 = hexToHsl(scale['950'])[2]
+    expect(l50).toBeGreaterThan(l950)
+  })
+})
+
+// ─── Harmony ──────────────────────────────────────────────────────────────────
+
+describe('complementary', () => {
+  it('returns 180° opposite hue', () => {
+    const result = complementary('#ff0000')
+    const [h] = hexToHsl(result)
+    expect(h).toBe(180)
+  })
+})
+
+describe('splitComplementary', () => {
+  it('returns 3 colors', () => {
+    const result = splitComplementary('#ff0000')
+    expect(result).toHaveLength(3)
+    expect(result[0]).toBe('#ff0000')
+  })
+})
+
+describe('triadic', () => {
+  it('returns 3 colors at 120° intervals', () => {
+    const [, b, c] = triadic('#ff0000')
+    const hB = hexToHsl(b)[0]
+    const hC = hexToHsl(c)[0]
+    expect(hB).toBe(120)
+    expect(hC).toBe(240)
+  })
+})
+
+describe('analogous', () => {
+  it('returns 3 colors', () => {
+    const result = analogous('#ff0000')
+    expect(result).toHaveLength(3)
+    expect(result[0]).toBe('#ff0000')
+  })
+
+  it('respects custom angle', () => {
+    const [, b, c] = analogous('#ff0000', 45)
+    const hB = hexToHsl(b)[0]
+    const hC = hexToHsl(c)[0]
+    expect(hB).toBe(45)
+    expect(hC).toBe(315)
+  })
+})
+
+// ─── normalizeToRgbChannels ───────────────────────────────────────────────────
+
+describe('normalizeToRgbChannels', () => {
+  it('normalizes hex to R G B', () => {
+    expect(normalizeToRgbChannels('#3b82f6')).toBe('59 130 246')
+  })
+
+  it('normalizes 3-digit hex', () => {
+    expect(normalizeToRgbChannels('#fff')).toBe('255 255 255')
+  })
+
+  it('passthrough channel format', () => {
+    expect(normalizeToRgbChannels('59 130 246')).toBe('59 130 246')
+  })
+
+  it('normalizes rgb()', () => {
+    expect(normalizeToRgbChannels('rgb(59, 130, 246)')).toBe('59 130 246')
+  })
+
+  it('normalizes rgba()', () => {
+    expect(normalizeToRgbChannels('rgba(59, 130, 246, 0.5)')).toBe('59 130 246')
+  })
+
+  it('normalizes hsl()', () => {
+    const result = normalizeToRgbChannels('hsl(0, 100%, 50%)')
+    expect(result).toBe('255 0 0')
+  })
+
+  it('normalizes named colors', () => {
+    expect(normalizeToRgbChannels('red')).toBe('255 0 0')
+    expect(normalizeToRgbChannels('white')).toBe('255 255 255')
+    expect(normalizeToRgbChannels('black')).toBe('0 0 0')
+  })
+
+  it('handles hex without # prefix', () => {
+    expect(normalizeToRgbChannels('ff0000')).toBe('255 0 0')
+  })
+})

package/src/utils/css-injector.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { toKebab, buildCssVars, getStyleId, injectStyles, removeStyles } from './css-injector'
+import { lightTheme, darkTheme } from '../themes/presets'
+
+describe('toKebab', () => {
+  it('converts camelCase to kebab-case', () => {
+    expect(toKebab('primaryDark')).toBe('primary-dark')
+  })
+
+  it('handles single word', () => {
+    expect(toKebab('primary')).toBe('primary')
+  })
+
+  it('handles multiple capitals', () => {
+    expect(toKebab('surfaceElevated')).toBe('surface-elevated')
+  })
+
+  it('handles textInverse', () => {
+    expect(toKebab('textInverse')).toBe('text-inverse')
+  })
+})
+
+describe('getStyleId', () => {
+  it('returns default id without namespace', () => {
+    expect(getStyleId()).toBe('vmt-theme-styles')
+  })
+
+  it('returns namespaced id', () => {
+    expect(getStyleId('acme')).toBe('vmt-theme-styles-acme')
+  })
+})
+
+describe('buildCssVars', () => {
+  it('generates CSS with attribute selector', () => {
+    const css = buildCssVars([lightTheme, darkTheme], {
+      strategy: 'attribute',
+      attribute: 'data-theme',
+      classPrefix: 'theme-',
+      cssVarPrefix: '--vmt-',
+      target: 'html',
+    })
+    expect(css).toContain(':root[data-theme="light"]')
+    expect(css).toContain(':root[data-theme="dark"]')
+    expect(css).toContain('--vmt-primary:')
+    expect(css).toContain('--vmt-primary-color:')
+  })
+
+  it('generates CSS with class selector', () => {
+    const css = buildCssVars([lightTheme], {
+      strategy: 'class',
+      attribute: 'data-theme',
+      classPrefix: 'theme-',
+      cssVarPrefix: '--vmt-',
+      target: 'html',
+    })
+    expect(css).toContain(':root.theme-light')
+  })
+
+  it('generates CSS with both strategy', () => {
+    const css = buildCssVars([lightTheme], {
+      strategy: 'both',
+      attribute: 'data-theme',
+      classPrefix: 'theme-',
+      cssVarPrefix: '--vmt-',
+      target: 'html',
+    })
+    expect(css).toContain(':root[data-theme="light"]')
+    expect(css).toContain(':root.theme-light')
+  })
+
+  it('uses custom CSS var prefix', () => {
+    const css = buildCssVars([lightTheme], {
+      strategy: 'attribute',
+      attribute: 'data-theme',
+      classPrefix: 'theme-',
+      cssVarPrefix: '--brand-',
+      target: 'html',
+    })
+    expect(css).toContain('--brand-primary:')
+  })
+
+  it('includes RGB channels for Tailwind opacity modifiers', () => {
+    const css = buildCssVars([lightTheme], {
+      strategy: 'attribute',
+      attribute: 'data-theme',
+      classPrefix: 'theme-',
+      cssVarPrefix: '--vmt-',
+      target: 'html',
+    })
+    // Should have both channel format and rgb() format
+    expect(css).toContain('--vmt-primary:')
+    expect(css).toContain('--vmt-primary-color: rgb(')
+  })
+})
+
+describe('injectStyles / removeStyles', () => {
+  beforeEach(() => {
+    document.head.innerHTML = ''
+  })
+
+  it('injects a <style> tag', () => {
+    injectStyles('body { color: red }')
+    const el = document.getElementById('vmt-theme-styles')
+    expect(el).not.toBeNull()
+    expect(el?.textContent).toBe('body { color: red }')
+  })
+
+  it('updates existing <style> tag', () => {
+    injectStyles('a { color: blue }')
+    injectStyles('a { color: red }')
+    const els = document.querySelectorAll('#vmt-theme-styles')
+    expect(els).toHaveLength(1)
+    expect(els[0].textContent).toBe('a { color: red }')
+  })
+
+  it('uses namespaced id', () => {
+    injectStyles('body {}', 'acme')
+    expect(document.getElementById('vmt-theme-styles-acme')).not.toBeNull()
+  })
+
+  it('removeStyles removes the tag', () => {
+    injectStyles('body {}')
+    removeStyles()
+    expect(document.getElementById('vmt-theme-styles')).toBeNull()
+  })
+
+  it('removeStyles with namespace', () => {
+    injectStyles('body {}', 'acme')
+    removeStyles('acme')
+    expect(document.getElementById('vmt-theme-styles-acme')).toBeNull()
+  })
+})

package/src/utils/dom.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { applyThemeToDom, clearThemeFromDom, readStorage, writeStorage, getSystemPreference } from './dom'
+
+describe('applyThemeToDom', () => {
+  beforeEach(() => {
+    document.documentElement.removeAttribute('data-theme')
+    document.documentElement.className = ''
+  })
+
+  it('sets data-theme attribute with attribute strategy', () => {
+    applyThemeToDom('dark', null, { strategy: 'attribute' })
+    expect(document.documentElement.getAttribute('data-theme')).toBe('dark')
+  })
+
+  it('adds class with class strategy', () => {
+    applyThemeToDom('dark', null, { strategy: 'class' })
+    expect(document.documentElement.classList.contains('theme-dark')).toBe(true)
+  })
+
+  it('applies both strategies together', () => {
+    applyThemeToDom('dark', null, { strategy: 'both' })
+    expect(document.documentElement.getAttribute('data-theme')).toBe('dark')
+    expect(document.documentElement.classList.contains('theme-dark')).toBe(true)
+  })
+
+  it('removes old class when switching themes', () => {
+    applyThemeToDom('light', null, { strategy: 'class' })
+    applyThemeToDom('dark', 'light', { strategy: 'class' })
+    expect(document.documentElement.classList.contains('theme-dark')).toBe(true)
+    expect(document.documentElement.classList.contains('theme-light')).toBe(false)
+  })
+
+  it('uses custom attribute name', () => {
+    applyThemeToDom('dark', null, { strategy: 'attribute', attribute: 'data-color-scheme' })
+    expect(document.documentElement.getAttribute('data-color-scheme')).toBe('dark')
+  })
+
+  it('uses custom class prefix', () => {
+    applyThemeToDom('dark', null, { strategy: 'class', classPrefix: 'color-' })
+    expect(document.documentElement.classList.contains('color-dark')).toBe(true)
+  })
+})
+
+describe('clearThemeFromDom', () => {
+  beforeEach(() => {
+    document.documentElement.removeAttribute('data-theme')
+    document.documentElement.className = ''
+  })
+
+  it('removes attribute', () => {
+    document.documentElement.setAttribute('data-theme', 'dark')
+    clearThemeFromDom('dark', { strategy: 'attribute' })
+    expect(document.documentElement.getAttribute('data-theme')).toBeNull()
+  })
+
+  it('removes class', () => {
+    document.documentElement.classList.add('theme-dark')
+    clearThemeFromDom('dark', { strategy: 'class' })
+    expect(document.documentElement.classList.contains('theme-dark')).toBe(false)
+  })
+})
+
+describe('readStorage / writeStorage', () => {
+  beforeEach(() => {
+    localStorage.clear()
+    sessionStorage.clear()
+  })
+
+  it('writes and reads from localStorage', () => {
+    writeStorage('vmt-test', 'dark', 'localStorage')
+    expect(readStorage('vmt-test', 'localStorage')).toBe('dark')
+  })
+
+  it('writes and reads from sessionStorage', () => {
+    writeStorage('vmt-test', 'light', 'sessionStorage')
+    expect(readStorage('vmt-test', 'sessionStorage')).toBe('light')
+  })
+
+  it('returns null for missing key', () => {
+    expect(readStorage('nonexistent', 'localStorage')).toBeNull()
+  })
+})
+
+describe('getSystemPreference', () => {
+  it('returns light or dark', () => {
+    const pref = getSystemPreference()
+    expect(['light', 'dark']).toContain(pref)
+  })
+})

package/src/utils/generate-theme.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from 'vitest'
+import {
+  generateLightTheme,
+  generateDarkTheme,
+  generateThemePair,
+  generateThemeFromPalette,
+  generateSeasonalThemes,
+  buildCssMixTheme,
+  checkContrast,
+} from './generate-theme'
+import { contrastRatio } from './color'
+
+describe('generateLightTheme', () => {
+  it('returns a theme with all required color tokens', () => {
+    const theme = generateLightTheme('#7c3aed')
+    expect(theme.name).toBe('generated-light')
+    expect(theme.label).toBe('Light')
+    expect(theme.colors.primary).toBeDefined()
+    expect(theme.colors.background).toBeDefined()
+    expect(theme.colors.text).toBeDefined()
+    expect(theme.colors.surface).toBeDefined()
+    expect(theme.colors.border).toBeDefined()
+  })
+
+  it('accepts custom name and label', () => {
+    const theme = generateLightTheme('#3b82f6', { name: 'brand', label: 'Brand Light' })
+    expect(theme.name).toBe('brand')
+    expect(theme.label).toBe('Brand Light')
+  })
+
+  it('generates a light background', () => {
+    const theme = generateLightTheme('#3b82f6')
+    // Background should be very light (high lightness hex)
+    const bg = theme.colors.background!
+    expect(bg).toMatch(/^#[f-f][0-9a-f]{5}$/i)
+  })
+
+  it('generates WCAG-compliant text on background', () => {
+    const theme = generateLightTheme('#3b82f6')
+    const ratio = contrastRatio(theme.colors.text!, theme.colors.background!)
+    expect(ratio).toBeGreaterThanOrEqual(4.5)
+  })
+
+  it('uses custom accent color when provided', () => {
+    const theme = generateLightTheme('#3b82f6', { accentColor: '#ff6600' })
+    expect(theme.colors.accent).toBe('#ff6600')
+  })
+
+  it('disables tinted surfaces when tintedSurfaces=false', () => {
+    const tinted = generateLightTheme('#ff0000', { tintedSurfaces: true })
+    const plain = generateLightTheme('#ff0000', { tintedSurfaces: false })
+    // Both should produce valid light themes
+    expect(tinted.colors.background).toBeDefined()
+    expect(plain.colors.background).toBeDefined()
+  })
+})
+
+describe('generateDarkTheme', () => {
+  it('returns a theme with all required color tokens', () => {
+    const theme = generateDarkTheme('#7c3aed')
+    expect(theme.name).toBe('generated-dark')
+    expect(theme.label).toBe('Dark')
+    expect(theme.colors.primary).toBeDefined()
+    expect(theme.colors.background).toBeDefined()
+    expect(theme.colors.text).toBeDefined()
+  })
+
+  it('generates a dark background', () => {
+    const theme = generateDarkTheme('#3b82f6')
+    // Background should be very dark (low R value hex)
+    const bg = theme.colors.background!
+    expect(bg).toMatch(/^#[0-3][0-9a-f]{5}$/i)
+  })
+
+  it('accepts custom name and label', () => {
+    const theme = generateDarkTheme('#3b82f6', { name: 'brand-dark', label: 'Brand Dark' })
+    expect(theme.name).toBe('brand-dark')
+    expect(theme.label).toBe('Brand Dark')
+  })
+})
+
+describe('generateThemePair', () => {
+  it('returns exactly two themes', () => {
+    const pair = generateThemePair('#7c3aed')
+    expect(pair).toHaveLength(2)
+  })
+
+  it('first is light, second is dark', () => {
+    const [light, dark] = generateThemePair('#7c3aed')
+    expect(light.name).toBe('light')
+    expect(dark.name).toBe('dark')
+  })
+
+  it('accepts custom names', () => {
+    const [light, dark] = generateThemePair('#7c3aed', {
+      lightName: 'brand-light',
+      darkName: 'brand-dark',
+    })
+    expect(light.name).toBe('brand-light')
+    expect(dark.name).toBe('brand-dark')
+  })
+})
+
+describe('generateThemeFromPalette', () => {
+  it('generates light variant with palette overrides', () => {
+    const theme = generateThemeFromPalette(
+      { primary: '#3b82f6', secondary: '#8b5cf6', accent: '#f59e0b' },
+      'light',
+    )
+    expect(theme.colors.secondary).toBe('#8b5cf6')
+    expect(theme.colors.accent).toBe('#f59e0b')
+  })
+
+  it('generates dark variant', () => {
+    const theme = generateThemeFromPalette(
+      { primary: '#3b82f6' },
+      'dark',
+    )
+    expect(theme.colors.primary).toBeDefined()
+    expect(theme.colors.background).toBeDefined()
+  })
+})
+
+describe('generateSeasonalThemes', () => {
+  const seasons = ['spring', 'summer', 'autumn', 'winter', 'midnight', 'neon', 'pastel'] as const
+
+  for (const season of seasons) {
+    it(`generates ${season} theme pair`, () => {
+      const [light, dark] = generateSeasonalThemes(season)
+      expect(light.name).toBe(`${season}-light`)
+      expect(dark.name).toBe(`${season}-dark`)
+      expect(light.colors.primary).toBeDefined()
+      expect(dark.colors.primary).toBeDefined()
+    })
+  }
+})
+
+describe('buildCssMixTheme', () => {
+  it('returns CSS string with selector', () => {
+    const css = buildCssMixTheme('#7c3aed', 'brand')
+    expect(css).toContain('[data-theme="brand"]')
+    expect(css).toContain('--vmt-primary')
+    expect(css).toContain('color-mix')
+  })
+
+  it('supports dark variant', () => {
+    const css = buildCssMixTheme('#7c3aed', 'brand', 'dark')
+    expect(css).toContain('[data-theme="brand"]')
+    expect(css).toContain('#000000')
+  })
+})
+
+describe('checkContrast', () => {
+  it('black on white passes all levels', () => {
+    const report = checkContrast('#000000', '#ffffff')
+    expect(report.aa).toBe(true)
+    expect(report.aaLarge).toBe(true)
+    expect(report.aaa).toBe(true)
+    expect(report.aaaLarge).toBe(true)
+    expect(report.ratio).toBeCloseTo(21, 0)
+  })
+
+  it('same color fails all levels', () => {
+    const report = checkContrast('#808080', '#808080')
+    expect(report.aa).toBe(false)
+    expect(report.aaLarge).toBe(false)
+    expect(report.ratio).toBeCloseTo(1, 0)
+  })
+
+  it('reports correct intermediate values', () => {
+    const report = checkContrast('#767676', '#ffffff')
+    expect(report.aaLarge).toBe(true)
+    expect(report.ratio).toBeGreaterThanOrEqual(4.5)
+  })
+})