fix: use oklch colours in charts (#278)

Co-authored-by: Daniel Roe <[e-mail]>

app/components/PackageDownloadAnalytics.vue

···
 import type { VueUiXyDatasetItem } from 'vue-data-ui'
 import { VueUiXy } from 'vue-data-ui/vue-ui-xy'
 import { useDebounceFn, useElementSize } from '@vueuse/core'
+import { useCssVariables } from '../composables/useColors'
+import { OKLCH_NEUTRAL_FALLBACK, transparentizeOklch } from '../utils/colors'
 
 const {
   weeklyDownloads,
···
 const { width } = useElementSize(rootEl)
 
 onMounted(() => {
+  rootEl.value = document.documentElement
   resolvedMode.value = colorMode.value === 'dark' ? 'dark' : 'light'
 })
 
+const { colors } = useCssVariables(
+  ['--bg', '--bg-subtle', '--bg-elevated', '--fg-subtle', '--border', '--border-subtle'],
+  {
+    element: rootEl,
+    watchHtmlAttributes: true,
+    watchResize: false, // set to true only if a var changes color on resize
+  },
+)
+
 watch(
   () => colorMode.value,
   value => {
···
 
 const accent = computed(() => {
   const id = selectedAccentColor.value
-  return id ? (oklchToHex(accentColorValueById.value[id]!) ?? '#8A8A8A') : '#8A8A8A'
+  return id
+    ? (accentColorValueById.value[id] ?? colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK)
+    : (colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK)
 })
 
 const mobileBreakpointWidth = 640
 
 const isMobile = computed(() => {
   return width.value > 0 && width.value < mobileBreakpointWidth
-})
-
-onMounted(() => {
-  rootEl.value = document.documentElement
 })
 
 type ChartTimeGranularity = 'daily' | 'weekly' | 'monthly' | 'yearly'
···
   a.remove()
 }
 
-const config = computed(() => ({
-  theme: isDarkMode.value ? 'dark' : 'default',
-  chart: {
-    height: isMobile.value ? 850 : 600,
-    userOptions: {
-      buttons: {
-        pdf: false,
-        labels: false,
-        fullscreen: false,
-        table: false,
-        tooltip: false,
-      },
-      callbacks: {
-        img: ({ imageUri }: { imageUri: string }) => {
-          loadFile(
-            imageUri,
-            `${packageName}-${selectedGranularity.value}_${startDate.value}_${endDate.value}.png`,
-          )
+const config = computed(() => {
+  return {
+    theme: isDarkMode.value ? 'dark' : 'default',
+    chart: {
+      height: isMobile.value ? 850 : 600,
+      userOptions: {
+        buttons: {
+          pdf: false,
+          labels: false,
+          fullscreen: false,
+          table: false,
+          tooltip: false,
         },
-        csv: (csvStr: string) => {
-          const blob = new Blob([csvStr.replace('data:text/csv;charset=utf-8,', '')])
-          const url = URL.createObjectURL(blob)
-          loadFile(
-            url,
-            `${packageName}-${selectedGranularity.value}_${startDate.value}_${endDate.value}.csv`,
-          )
-          URL.revokeObjectURL(url)
-        },
-        svg: ({ blob }: { blob: Blob }) => {
-          const url = URL.createObjectURL(blob)
-          loadFile(
-            url,
-            `${packageName}-${selectedGranularity.value}_${startDate.value}_${endDate.value}.svg`,
-          )
-          URL.revokeObjectURL(url)
+        callbacks: {
+          img: ({ imageUri }: { imageUri: string }) => {
+            loadFile(
+              imageUri,
+              `${packageName}-${selectedGranularity.value}_${startDate.value}_${endDate.value}.png`,
+            )
+          },
+          csv: (csvStr: string) => {
+            const blob = new Blob([csvStr.replace('data:text/csv;charset=utf-8,', '')])
+            const url = URL.createObjectURL(blob)
+            loadFile(
+              url,
+              `${packageName}-${selectedGranularity.value}_${startDate.value}_${endDate.value}.csv`,
+            )
+            URL.revokeObjectURL(url)
+          },
+          svg: ({ blob }: { blob: Blob }) => {
+            const url = URL.createObjectURL(blob)
+            loadFile(
+              url,
+              `${packageName}-${selectedGranularity.value}_${startDate.value}_${endDate.value}.svg`,
+            )
+            URL.revokeObjectURL(url)
+          },
         },
       },
-    },
-    backgroundColor: isDarkMode.value ? '#0A0A0A' : '#FFFFFF',
-    grid: {
-      stroke: isDarkMode.value ? '#4A4A4A' : '#a3a3a3',
-      labels: {
-        axis: {
-          yLabel: $t('package.downloads.y_axis_label', {
-            granularity: $t(`package.downloads.granularity_${selectedGranularity.value}`),
-          }),
-          xLabel: packageName,
-          yLabelOffsetX: 12,
-          fontSize: 24,
-        },
-        xAxisLabels: {
-          values: chartData.value?.dates,
-          showOnlyAtModulo: true,
-          modulo: 12,
-        },
-        yAxis: {
-          formatter,
-          useNiceScale: true,
+      backgroundColor: colors.value.bg,
+      grid: {
+        stroke: colors.value.border,
+        labels: {
+          axis: {
+            yLabel: $t('package.downloads.y_axis_label', {
+              granularity: $t(`package.downloads.granularity_${selectedGranularity.value}`),
+            }),
+            xLabel: packageName,
+            yLabelOffsetX: 12,
+            fontSize: 24,
+          },
+          xAxisLabels: {
+            values: chartData.value?.dates,
+            showOnlyAtModulo: true,
+            modulo: 12,
+          },
+          yAxis: {
+            formatter,
+            useNiceScale: true,
+          },
         },
       },
-    },
-    highlighter: {
-      useLine: true,
-    },
-    legend: {
-      show: false, // As long as a single package is displayed
-    },
-    tooltip: {
-      borderColor: 'transparent',
-      backdropFilter: false,
-      backgroundColor: 'transparent',
-      customFormat: ({
-        absoluteIndex,
-        datapoint,
-      }: {
-        absoluteIndex: number
-        datapoint: Record<string, any>
-      }) => {
-        if (!datapoint) return ''
-        const displayValue = formatter({ value: datapoint[0]?.value ?? 0 })
-        return `<div class="flex flex-col font-mono text-xs p-3 border border-border rounded-md bg-white/10 dark:bg-[#0A0A0A]/10 backdrop-blur-md">
+      highlighter: {
+        useLine: true,
+      },
+      legend: {
+        show: false, // As long as a single package is displayed
+      },
+      tooltip: {
+        borderColor: 'transparent',
+        backdropFilter: false,
+        backgroundColor: 'transparent',
+        customFormat: ({
+          absoluteIndex,
+          datapoint,
+        }: {
+          absoluteIndex: number
+          datapoint: Record<string, any>
+        }) => {
+          if (!datapoint) return ''
+          const displayValue = formatter({ value: datapoint[0]?.value ?? 0 })
+          return `<div class="flex flex-col font-mono text-xs p-3 border border-border rounded-md bg-[var(--bg)]/10 backdrop-blur-md">
           <span class="text-fg-subtle">${chartData.value?.dates[absoluteIndex]}</span>
           <span class="text-xl">${displayValue}</span>
         </div>
         `
+        },
       },
-    },
-    zoom: {
-      maxWidth: 500,
-      customFormat:
-        displayedGranularity.value !== 'weekly'
-          ? undefined
-          : ({ absoluteIndex, side }: { absoluteIndex: number; side: 'left' | 'right' }) => {
-              const parts = extractDates(chartData.value.dates[absoluteIndex] ?? '')
-              return side === 'left' ? parts[0] : parts.at(-1)
-            },
-      highlightColor: isDarkMode.value ? '#2A2A2A' : '#E1E5E8',
-      minimap: {
-        show: true,
-        lineColor: '#FAFAFA',
-        selectedColor: accent.value,
-        selectedColorOpacity: 0.06,
-        frameColor: isDarkMode.value ? '#3A3A3A' : '#a3a3a3',
-      },
-      preview: {
-        fill: accent.value + 10,
-        stroke: accent.value + 60,
-        strokeWidth: 1,
-        strokeDasharray: 3,
+      zoom: {
+        maxWidth: 500,
+        customFormat:
+          displayedGranularity.value !== 'weekly'
+            ? undefined
+            : ({ absoluteIndex, side }: { absoluteIndex: number; side: 'left' | 'right' }) => {
+                const parts = extractDates(chartData.value.dates[absoluteIndex] ?? '')
+                return side === 'left' ? parts[0] : parts.at(-1)
+              },
+        highlightColor: colors.value.bgElevated,
+        minimap: {
+          show: true,
+          lineColor: '#FAFAFA',
+          selectedColor: accent.value,
+          selectedColorOpacity: 0.06,
+          frameColor: colors.value.border,
+        },
+        preview: {
+          fill: transparentizeOklch(accent.value, isDarkMode.value ? 0.95 : 0.92),
+          stroke: transparentizeOklch(accent.value, 0.5),
+          strokeWidth: 1,
+          strokeDasharray: 3,
+        },
       },
     },
-  },
-}))
+  }
+})
 </script>
 
 <template>

app/components/PackageWeeklyDownloadStats.vue

···
 <script setup lang="ts">
 import { ref, computed, onMounted, watch } from 'vue'
 import { VueUiSparkline } from 'vue-data-ui/vue-ui-sparkline'
+import { useCssVariables } from '../composables/useColors'
+import { OKLCH_NEUTRAL_FALLBACK, lightenOklch } from '../utils/colors'
 
 const { packageName } = defineProps<{
   packageName: string
···
 
 const resolvedMode = ref<'light' | 'dark'>('light')
 
+const rootEl = shallowRef<HTMLElement | null>(null)
+
 onMounted(() => {
+  rootEl.value = document.documentElement
   resolvedMode.value = colorMode.value === 'dark' ? 'dark' : 'light'
 })
 
···
   { flush: 'sync' },
 )
 
+const { colors } = useCssVariables(
+  [
+    '--bg',
+    '--fg',
+    '--bg-subtle',
+    '--bg-elevated',
+    '--border-hover',
+    '--fg-subtle',
+    '--border',
+    '--border-subtle',
+  ],
+  {
+    element: rootEl,
+    watchHtmlAttributes: true,
+    watchResize: false, // set to true only if a var changes color on resize
+  },
+)
+
 const isDarkMode = computed(() => resolvedMode.value === 'dark')
 
 const accentColorValueById = computed<Record<string, string>>(() => {
···
 
 const accent = computed(() => {
   const id = selectedAccentColor.value
-  return id ? (oklchToHex(accentColorValueById.value[id]!) ?? '#8A8A8A') : '#8A8A8A'
+  return id
+    ? (accentColorValueById.value[id] ?? colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK)
+    : (colors.value.fgSubtle ?? OKLCH_NEUTRAL_FALLBACK)
 })
 
 const pulseColor = computed(() => {
   if (!selectedAccentColor.value) {
-    return isDarkMode.value ? '#BFBFBF' : '#E0E0E0'
+    return colors.value.fgSubtle
   }
-  return isDarkMode.value ? accent.value : lightenHex(accent.value, 0.5)
+  return isDarkMode.value ? accent.value : lightenOklch(accent.value, 0.5)
 })
 
 const weeklyDownloads = ref<WeeklyDownloadPoint[]>([])
···
       backgroundColor: 'transparent',
       animation: { show: false },
       area: {
-        color: '#6A6A6A',
+        color: colors.value.borderHover,
         useGradient: false,
         opacity: 10,
       },
···
         offsetX: -10,
         fontSize: 28,
         bold: false,
-        color: isDarkMode.value ? '#8a8a8a' : '#696969',
+        color: colors.value.fg,
       },
       line: {
-        color: isDarkMode.value ? '#4a4a4a' : '#525252',
+        color: colors.value.borderHover,
         pulse: {
           show: true,
           loop: true, // runs only once if false
···
       },
       plot: {
         radius: 6,
-        stroke: isDarkMode.value ? '#FAFAFA' : '#0A0A0A',
+        stroke: isDarkMode.value ? 'oklch(0.985 0 0)' : 'oklch(0.145 0 0)',
       },
       title: {
         text: lastDatapoint.value,
         fontSize: 12,
-        color: isDarkMode.value ? '#8a8a8a' : '#696969',
+        color: colors.value.fgSubtle,
         bold: false,
       },
       verticalIndicator: {
         strokeDasharray: 0,
-        color: isDarkMode.value ? '#FAFAFA' : '#525252',
+        color: isDarkMode.value ? 'oklch(0.985 0 0)' : colors.value.fgSubtle,
       },
     },
   }

app/composables/useColors.ts

···
+import { computed, type ComputedRef, type Ref, unref } from 'vue'
+import { useMutationObserver, useResizeObserver, useSupported } from '@vueuse/core'
+
+type CssVariableSource = HTMLElement | null | undefined | Ref<HTMLElement | null | undefined>
+
+type UseCssVariableOptions = {
+  element?: CssVariableSource
+  watchResize?: boolean
+  watchHtmlAttributes?: boolean
+}
+
+function readCssVariable(element: HTMLElement, variableName: string): string {
+  return getComputedStyle(element).getPropertyValue(variableName).trim()
+}
+
+function toCamelCase(cssVariable: string): string {
+  return cssVariable.replace(/^--/, '').replace(/-([a-z0-9])/gi, (_, c) => c.toUpperCase())
+}
+
+function resolveElement(element?: CssVariableSource): HTMLElement | null {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return null
+  if (!element) return document.documentElement
+  const resolved = unref(element)
+  return resolved ?? document.documentElement
+}
+
+/**
+ * Read multiple CSS custom properties at once and expose them as a reactive object.
+ *
+ * Each CSS variable name is normalized into a camelCase key:
+ * - Leading `--` is removed
+ * - kebab-case is converted to camelCase
+ *
+ * Example:
+ * ```ts
+ * useCssVariables(['--bg', '--fg-subtle'])
+ * // => colors.value = { bg: '...', fgSubtle: '...' }
+ * ```
+ *
+ * The returned values are always resolved via `getComputedStyle`, meaning the
+ * effective value is returned (after cascade, theme classes, etc.).
+ *
+ * Reactivity behavior:
+ * - Updates automatically when the observed element changes
+ * - Can react to theme toggles via `watchHtmlAttributes`
+ * - Can react to responsive CSS variables via `watchResize`
+ *
+ * @param variables - List of CSS variable names (must include the leading `--`)
+ * @param options - Configuration options
+ * @param options.element - Element to read variables from (defaults to `:root`)
+ * @param options.watchResize - Re-evaluate values on resize (useful for media-query-driven variables)
+ * @param options.watchHtmlAttributes - Re-evaluate values when `<html>` attributes change
+ *
+ * @returns An object containing a reactive `colors` map, keyed by camelCase names
+ */
+export function useCssVariables(
+  variables: readonly string[],
+  options: UseCssVariableOptions = {},
+): { colors: ComputedRef<Record<string, string>> } {
+  const isClientSupported = useSupported(
+    () => typeof window !== 'undefined' && typeof document !== 'undefined',
+  )
+
+  const elementComputed = computed(() => resolveElement(options.element))
+
+  const colors = computed<Record<string, string>>(() => {
+    const element = elementComputed.value
+    if (!element) return {}
+
+    const result: Record<string, string> = {}
+    for (const variable of variables) {
+      result[toCamelCase(variable)] = readCssVariable(element, variable)
+    }
+    return result
+  })
+
+  if (options.watchResize) {
+    useResizeObserver(elementComputed, () => void colors.value)
+  }
+
+  if (options.watchHtmlAttributes && isClientSupported.value) {
+    useMutationObserver(document.documentElement, () => void colors.value, {
+      attributes: true,
+      attributeFilter: ['class', 'style', 'data-theme'],
+    })
+  }
+
+  return { colors }
+}

app/utils/colors.ts

···
 // Vue Data UI does not support CSS vars nor OKLCH for now
 
+/**
+ * Default neutral OKLCH color used as fallback when CSS variables are unavailable (e.g., during SSR).
+ * This matches the dark mode value of --fg-subtle defined in main.css.
+ */
+export const OKLCH_NEUTRAL_FALLBACK = 'oklch(0.633 0 0)'
+
 /** Converts a 0-255 RGB component to a 2-digit hex string */
 const componentToHex = (value: number): string =>
   Math.round(Math.min(Math.max(0, value), 255))
···
 
   return `#${linearToHex(linearToSrgb(r))}${linearToHex(linearToSrgb(g))}${linearToHex(linearToSrgb(bRgb))}`
 }
+
+/**
+ * Lighten an OKLCH color by a given factor.
+ *
+ * Works with strict TypeScript settings including `noUncheckedIndexedAccess`,
+ * where `match[n]` is typed as `string | undefined`.
+ *
+ * @param oklch - Color in the form "oklch(L C H)" or "oklch(L C H / A)"
+ * @param factor - Lightening force in range [0, 1]
+ * @returns Lightened OKLCH color string (0.5 = 50% lighter)
+ */
+export function lightenOklch(
+  oklch: string | null | undefined,
+  factor: number,
+): string | null | undefined {
+  if (oklch == null) {
+    return oklch
+  }
+
+  const input = oklch.trim()
+
+  const match = input.match(
+    /^oklch\(\s*([+-]?[\d.]+%?)\s+([+-]?[\d.]+)\s+([+-]?[\d.]+)(?:\s*\/\s*([+-]?[\d.]+%?))?\s*\)$/i,
+  )
+
+  if (!match) {
+    throw new Error('Invalid OKLCH color format')
+  }
+
+  const [, lightnessText, chromaText, hueText, alphaText] = match
+
+  if (lightnessText === undefined || chromaText === undefined || hueText === undefined) {
+    throw new Error('Invalid OKLCH color format')
+  }
+
+  let lightness = lightnessText.endsWith('%')
+    ? Number.parseFloat(lightnessText) / 100
+    : Number.parseFloat(lightnessText)
+  let chroma = Number.parseFloat(chromaText)
+  const hue = Number.parseFloat(hueText)
+  const alpha =
+    alphaText === undefined
+      ? null
+      : alphaText.endsWith('%')
+        ? Number.parseFloat(alphaText) / 100
+        : Number.parseFloat(alphaText)
+
+  const clampedFactor = Math.min(Math.max(factor, 0), 1)
+  lightness = lightness + (1 - lightness) * clampedFactor
+
+  // Reduce chroma slightly as lightness increases
+  chroma = chroma * (1 - clampedFactor * 0.3)
+
+  lightness = Math.min(Math.max(lightness, 0), 1)
+  chroma = Math.max(chroma, 0)
+
+  return alpha === null
+    ? `oklch(${lightness} ${chroma} ${hue})`
+    : `oklch(${lightness} ${chroma} ${hue} / ${alpha})`
+}
+
+/**
+ * Make an OKLCH color transparent by a given factor.
+ *
+ * @param oklch - Color in the form "oklch(L C H)" or "oklch(L C H / A)"
+ * @param factor - Transparency factor in range [0, 1]
+ * @returns OKLCH color string with adjusted alpha (0.5 = 50% transparency, 1 = fully transparent)
+ */
+export function transparentizeOklch(
+  oklch: string | null | undefined,
+  factor: number,
+  fallback = 'oklch(0 0 0 / 0)',
+): string {
+  if (oklch == null) return fallback
+
+  const input = oklch.trim()
+  if (!input) return fallback
+
+  const match = input.match(
+    /^oklch\(\s*([+-]?[\d.]+%?)\s+([+-]?[\d.]+)\s+([+-]?[\d.]+)(?:\s*\/\s*([+-]?[\d.]+%?))?\s*\)$/i,
+  )
+
+  if (!match) return fallback
+
+  const [, lightnessText, chromaText, hueText, alphaText] = match
+
+  if (lightnessText === undefined || chromaText === undefined || hueText === undefined) {
+    return fallback
+  }
+
+  const lightness = lightnessText.endsWith('%')
+    ? Math.min(Math.max(Number.parseFloat(lightnessText) / 100, 0), 1)
+    : Math.min(Math.max(Number.parseFloat(lightnessText), 0), 1)
+
+  const chroma = Math.max(0, Number.parseFloat(chromaText))
+  const hue = Number.parseFloat(hueText)
+
+  const originalAlpha =
+    alphaText === undefined
+      ? 1
+      : alphaText.endsWith('%')
+        ? Math.min(Math.max(Number.parseFloat(alphaText) / 100, 0), 1)
+        : Math.min(Math.max(Number.parseFloat(alphaText), 0), 1)
+
+  const clampedFactor = Math.min(Math.max(factor, 0), 1)
+  const alpha = Math.max(0, originalAlpha * (1 - clampedFactor))
+
+  return `oklch(${lightness} ${chroma} ${hue} / ${alpha})`
+}

package.json

···
     "validate-npm-package-name": "^7.0.2",
     "virtua": "^0.48.3",
     "vue": "3.5.27",
-    "vue-data-ui": "^3.13.5"
+    "vue-data-ui": "^3.13.6"
   },
   "devDependencies": {
     "@iconify-json/carbon": "1.2.18",

pnpm-lock.yaml

···
         specifier: 3.5.27
         version: 3.5.27(typescript@5.9.3)
       vue-data-ui:
-        specifier: ^3.13.5
-        version: 3.13.5(vue@3.5.27(typescript@5.9.3))
+        specifier: ^3.13.6
+        version: 3.13.6(vue@3.5.27(typescript@5.9.3))
     devDependencies:
       '@iconify-json/carbon':
         specifier: 1.2.18
···
     resolution: {integrity: sha512-GaHYm+c0O9MjZRu0ongGBRbinu8gVAMd2UZjji6jVmqKtZluZnptXGWhz1E8j8D2HJ3f/yMxKAUC0b+57wncIw==}
 
   '@lunariajs/core@https://pkg.pr.new/lunariajs/lunaria/@lunariajs/core@f07e1a3':
-    resolution: {tarball: https://pkg.pr.new/lunariajs/lunaria/@lunariajs/core@f07e1a3}
+    resolution: {integrity: sha512-gjrzNz3XLFOUrDcmBxgaaF8Flh2yDpn8/RQyt+kyQen3sCjT04BnqJXLweper+xWyfvpOFK4Cqmy3wHvTyC1ww==, tarball: https://pkg.pr.new/lunariajs/lunaria/@lunariajs/core@f07e1a3}
     version: 0.1.1
     engines: {node: '>=18.17.0'}
 
···
   vue-component-type-helpers@3.2.4:
     resolution: {integrity: sha512-05lR16HeZDcDpB23ku5b5f1fBOoHqFnMiKRr2CiEvbG5Ux4Yi0McmQBOET0dR0nxDXosxyVqv67q6CzS3AK8rw==}
 
-  vue-data-ui@3.13.5:
-    resolution: {integrity: sha512-RBdhoKAlraMoTU3ls7tRy9UCusNwBCvN9w0wF2R0Jwy/AX7cAejlfDDMKE4SN/Th/4ox2eFIZSCZ/CRco3nOxw==}
+  vue-data-ui@3.13.6:
+    resolution: {integrity: sha512-cfyL9kP4bOpbby2wvgCJvsKyRv/5aQHw2+UZIZ5/Vm4lt7yZe41ZU9kMMryd911hC6vuYLUB88bcIGFg1toWAA==}
     peerDependencies:
       jspdf: '>=3.0.1'
       vue: '>=3.3.0'
···
 
   vue-component-type-helpers@3.2.4: {}
 
-  vue-data-ui@3.13.5(vue@3.5.27(typescript@5.9.3)):
+  vue-data-ui@3.13.6(vue@3.5.27(typescript@5.9.3)):
     dependencies:
       vue: 3.5.27(typescript@5.9.3)
 

test/nuxt/composables/use-colors.spec.ts

···
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { computed, nextTick, defineComponent } from 'vue'
+import { mount } from '@vue/test-utils'
+import type * as VueUseCore from '@vueuse/core'
+
+const useSupportedMock = vi.hoisted(() => vi.fn())
+const useMutationObserverMock = vi.hoisted(() => vi.fn())
+const useResizeObserverMock = vi.hoisted(() => vi.fn())
+
+let lastMutationObserverInstance: {
+  observe: ReturnType<typeof vi.fn>
+  disconnect: ReturnType<typeof vi.fn>
+  takeRecords: ReturnType<typeof vi.fn>
+} | null = null
+
+const mutationObserverConstructorMock = vi.hoisted(() =>
+  vi.fn(function MutationObserver() {
+    lastMutationObserverInstance = {
+      observe: vi.fn(),
+      disconnect: vi.fn(),
+      takeRecords: vi.fn(),
+    }
+    return lastMutationObserverInstance
+  }),
+)
+
+vi.mock('@vueuse/core', async () => {
+  const actual = await vi.importActual<typeof VueUseCore>('@vueuse/core')
+  return {
+    ...actual,
+    useSupported: useSupportedMock,
+    useMutationObserver: useMutationObserverMock,
+    useResizeObserver: useResizeObserverMock,
+  }
+})
+
+function mockComputedStyle(values: Record<string, string>) {
+  vi.stubGlobal('getComputedStyle', () => {
+    return {
+      getPropertyValue: (name: string) => values[name] ?? '',
+    } as any
+  })
+}
+
+function mountWithSetup(run: () => void) {
+  return mount(
+    defineComponent({
+      name: 'TestHarness',
+      setup() {
+        run()
+        return () => null
+      },
+    }),
+    { attachTo: document.body },
+  )
+}
+
+describe('useCssVariables', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.resetModules()
+    lastMutationObserverInstance = null
+    vi.stubGlobal('MutationObserver', mutationObserverConstructorMock as any)
+  })
+
+  it('does not attach html mutation observer when client is not supported', async () => {
+    const { useCssVariables } = await import('../../../app/composables/useColors')
+
+    useSupportedMock.mockReturnValueOnce(computed(() => false))
+    mockComputedStyle({ '--bg': 'oklch(1 0 0)' })
+
+    const wrapper = mountWithSetup(() => {
+      const { colors } = useCssVariables(['--bg'], { watchHtmlAttributes: true })
+      expect(colors.value.bg).toBe('oklch(1 0 0)')
+    })
+
+    await nextTick()
+
+    expect(useMutationObserverMock).not.toHaveBeenCalled()
+    expect(lastMutationObserverInstance).not.toBeNull()
+    expect(lastMutationObserverInstance!.observe).toHaveBeenCalledTimes(1)
+
+    wrapper.unmount()
+  })
+
+  it('attaches html mutation observer when client is supported', async () => {
+    const { useCssVariables } = await import('../../../app/composables/useColors')
+
+    useSupportedMock.mockReturnValueOnce(computed(() => true))
+    mockComputedStyle({ '--bg': 'oklch(1 0 0)' })
+
+    const wrapper = mountWithSetup(() => {
+      useCssVariables(['--bg'], { watchHtmlAttributes: true })
+    })
+
+    await nextTick()
+
+    expect(lastMutationObserverInstance).not.toBeNull()
+    expect(lastMutationObserverInstance!.observe).toHaveBeenCalledTimes(1)
+
+    wrapper.unmount()
+  })
+})