feat(nuxt-ui): color mode aware token resolution via data-theme (#598)

Author: harlan-zw

docs/content/3.guides/7.styling.md

@@ -79,6 +79,66 @@ The module automatically detects your CSS framework:
 - **UnoCSS:** Active if you enable `@unocss/nuxt`.
 - **Nuxt UI v3:** Automatically imports colors and theme variables.
 
+## Theme Switching (`data-theme`)
+
+By default, OG images render with dark-mode semantic tokens (e.g. Nuxt UI's `bg-inverted`, `text-default`). To opt into theme-aware token resolution, set `data-theme` on the **root element** of your component. Tailwind v4 only.
+
+### Static `data-theme`
+
+Hard-code a theme on the root element:
+
+```vue [components/OgImage/MyImage.satori.vue]
+<template>
+  <div data-theme="light" class="w-full h-full bg-default text-default p-10">
+    <div class="bg-inverted text-inverted p-6 rounded-lg">
+      Light mode tokens
+    </div>
+  </div>
+</template>
+```
+
+Semantic tokens like `bg-inverted`, `text-muted`, `border-accented` resolve against the chosen theme: `data-theme="light"` produces light-mode values, `data-theme="dark"` produces dark-mode values.
+
+### Dynamic `data-theme` (per-image color mode)
+
+Bind `:data-theme` to a prop to swap themes per OG image:
+
+```vue [components/OgImage/MyImage.satori.vue]
+<script lang="ts" setup>
+defineProps<{ colorMode?: 'light' | 'dark' }>()
+</script>
+
+<template>
+  <div :data-theme="colorMode" class="w-full h-full bg-default text-default p-10">
+    <div class="bg-inverted text-inverted p-6 rounded-lg">
+      hello {{ colorMode }}
+    </div>
+  </div>
+</template>
+```
+
+```vue [pages/light.vue]
+<script setup lang="ts">
+defineOgImage('MyImage', { colorMode: 'light' })
+</script>
+```
+
+```vue [pages/dark.vue]
+<script setup lang="ts">
+defineOgImage('MyImage', { colorMode: 'dark' })
+</script>
+```
+
+When the build detects a `:data-theme` binding on the root element, it resolves classes for both themes at build time and emits paired `bg-[#...] dark:bg-[#...]` arbitrary classes. The renderer then picks the correct value based on the `colorMode` prop you pass to `defineOgImage`.
+
+::note
+The dynamic binding only works on the **root element** of the OG component. Nested elements inherit the resolved theme from the build pass.
+::
+
+::tip
+Templates that don't set `data-theme` keep the existing dark-mode default; this feature is opt-in and non-breaking.
+::
+
 ## Inline Styles
 
 Use the `:style` binding for dynamic values that change based on props.

docs/content/4.integrations/2.color-mode.md

@@ -23,3 +23,7 @@ export default defineNuxtConfig({
   },
 })
 ```
+
+## Per-image theme switching
+
+If you need to render the same component in different themes for different pages (e.g. a light variant and a dark variant of a hero image), bind `:data-theme` on the component's root element to a `colorMode` prop. See [Theme Switching](/docs/og-image/guides/styling#theme-switching-data-theme) in the styling guide.

src/build/css/css-utils.ts

@@ -401,6 +401,16 @@ function isRootOrHost(selectors: any[]): boolean {
     c.type === 'pseudo-class' && (c.kind === 'root' || c.kind === 'host'))
 }
 
+/**
+ * Check if a selector list contains a bare `.dark` or `.light` theme class
+ * (e.g., `.dark { ... }`). These are emitted by libraries like @nuxt/ui as
+ * the canonical dark-mode rule and act as :root-equivalent for theme vars.
+ */
+function isBareThemeClass(selectors: any[]): boolean {
+  return selectorsContain(selectors, c =>
+    c.type === 'class' && (c.name === 'dark' || c.name === 'light'))
+}
+
 function isUniversal(selectors: any[]): boolean {
   return selectorsContain(selectors, c => c.type === 'universal')
 }
@@ -526,7 +536,7 @@ export async function extractVarsFromCss(css: string): Promise<ExtractedCssVars>
             const selectors = rule.value.selectors
             const declarations = rule.value.declarations
 
-            if (isRootOrHost(selectors)) {
+            if (isRootOrHost(selectors) || isBareThemeClass(selectors)) {
               const vars = extractCustomProps(declarations)
               if (vars.size === 0)
                 return undefined