@plexui/styles 0.0.0-stage → 0.1.1

package/dist/es/styles/variables-tokens-root.css

@@ -0,0 +1,40 @@
+/*
+ * Plex UI tokens that semantic + components tiers reference via var(...).
+ *
+ * These live in a plain `:root` block (NOT in `@theme static`), so Plex UI
+ * does not reset Tailwind's theme namespaces with `--radius-*: initial`.
+ * Being outside any cascade layer, they still win over the same names in
+ * Tailwind's `theme` layer: the consumer's `rounded-*`, `font-sans` and
+ * `font-*` weight utilities resolve to the Plex values (`rounded-md` is
+ * 8px). The installation guide documents this.
+ *
+ * The standalone `@plexui/ui/styles/variables-tailwind-theme.css` file also
+ * maps the rest of the Plex scale (text sizes, breakpoints, ...) onto
+ * Tailwind's theme (see /docs/installation).
+ */
+:root {
+  /* Radii */
+  --radius-2xs: 0.125rem; /* 2px */
+  --radius-xs: 0.25rem; /* 4px */
+  --radius-sm: 0.375rem; /* 6px */
+  --radius-md: 0.5rem; /* 8px */
+  --radius-lg: 0.625rem; /* 10px */
+  --radius-xl: 0.75rem; /* 12px */
+  --radius-2xl: 1rem; /* 16px */
+  --radius-3xl: 1.25rem; /* 20px */
+  --radius-4xl: 1.5rem; /* 24px */
+  --radius-full: 9999px;
+
+  /* Font stacks */
+  --font-sans: ui-sans-serif, -apple-system, system-ui, "Segoe UI", "Noto Sans", "Helvetica",
+    "Arial", "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", sans-serif;
+  --font-serif: ui-serif, Georgia, "Times New Roman", serif;
+  --font-mono: ui-monospace, "SFMono-Regular", "SF Mono", "Menlo", "Monaco", "Consolas",
+    "Liberation Mono", "DejaVu Sans Mono", "Courier New", monospace;
+
+  /* Font weights */
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+}

package/dist/es/types.js

@@ -0,0 +1,4 @@
+// Shared prop contract (sizes, colors, variants) for every Plex UI framework
+// package. Keep it free of framework imports.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/es/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,8CAA8C","sourcesContent":["// Shared prop contract (sizes, colors, variants) for every Plex UI framework\n// package. Keep it free of framework imports.\n\nexport type Size =\n  | \"5xs\"\n  | \"4xs\"\n  | \"3xs\"\n  | \"2xs\"\n  | \"xs\"\n  | \"sm\"\n  | \"md\"\n  | \"lg\"\n  | \"xl\"\n  | \"2xl\"\n  | \"3xl\"\n  | \"4xl\"\n  | \"5xl\"\n  | \"6xl\"\nexport type Sizes<T extends Size = Size> = T\n\nexport type ControlSize = Sizes<\"3xs\" | \"2xs\" | \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\" | \"2xl\" | \"3xl\">\n\nexport type Radius = \"2xs\" | \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\" | \"2xl\" | \"3xl\" | \"full\"\nexport type Radii<T extends Radius = Radius> = T\n\nexport type TextColor = \"base\" | \"emphasis\" | \"secondary\" | \"tertiary\"\nexport type TextColors<T extends TextColor = TextColor> = T\n\nexport type SemanticColor =\n  | \"primary\"\n  | \"secondary\"\n  | \"danger\"\n  | \"success\"\n  | \"warning\"\n  | \"caution\"\n  | \"discovery\"\n  | \"info\"\nexport type SemanticColors<T extends SemanticColor = SemanticColor> = T\n\nexport type Variant = \"solid\" | \"soft\" | \"outline\" | \"ghost\"\nexport type Variants<T extends Variant = Variant> = T\n\nexport type Alignment = \"start\" | \"center\" | \"end\"\nexport type Alignments<T extends Alignment = Alignment> = T\n\nexport type FontWeight = \"inherit\" | \"normal\" | \"medium\" | \"semibold\" | \"bold\"\nexport type FontWeights<T extends FontWeight = FontWeight> = T\n"]}

package/dist/es/vite/index.js

@@ -0,0 +1,54 @@
+/**
+ * Vite plugin for Plex UI.
+ *
+ * Importing `@plexui/styles/vite` (React apps can keep `@plexui/ui/vite`,
+ * which re-exports it) and adding `plexui()` to your `plugins` array
+ * eliminates every install-time gotcha documented in /docs/installation:
+ *
+ *   1. Pins `css.transformer = 'postcss'` so Lightning CSS doesn't
+ *      reorder cascade layers strict-by-first-occurrence.
+ *   2. Pins `build.cssMinify = 'esbuild'` so Vite 8's Lightning CSS
+ *      minifier doesn't strip the bare `@layer` declaration.
+ *   3. Injects `<style>@layer theme, base, components, utilities;</style>`
+ *      into <head> as a runtime failsafe — the browser sees the layer
+ *      order before any stylesheet rule arrives, regardless of how the
+ *      bundler shuffles things.
+ *
+ * Usage:
+ *
+ *     // vite.config.ts
+ *     import { defineConfig } from 'vite';
+ *     import plexui from '@plexui/styles/vite';
+ *
+ *     export default defineConfig({
+ *       plugins: [plexui()],
+ *     });
+ *
+ * That replaces the manual `@layer …;` declaration in main.css and the
+ * manual `css.transformer` / `build.cssMinify` overrides. Your global
+ * stylesheet still needs `@import "@plexui/styles/css"` and `@source` —
+ * those wire the runtime tokens and Tailwind class-extraction, which a
+ * Vite plugin can't do for you.
+ */
+const LAYER_DECLARATION = "<style>@layer theme, base, components, utilities;</style>";
+export default function plexui(options = {}) {
+    const { injectLayerOrder = true } = options;
+    return {
+        name: "@plexui/styles",
+        enforce: "pre",
+        config() {
+            return {
+                css: { transformer: "postcss" },
+                build: { cssMinify: "esbuild" },
+            };
+        },
+        transformIndexHtml(html) {
+            if (!injectLayerOrder)
+                return html;
+            // Place the layer declaration right after <head> so it lands
+            // before any bundler-injected <link rel="stylesheet">.
+            return html.replace(/(<head[^>]*>)/i, `$1\n    ${LAYER_DECLARATION}`);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/es/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/vite/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAkBH,MAAM,iBAAiB,GACrB,2DAA2D,CAAA;AAW7D,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,UAA+B,EAAE;IAC9D,MAAM,EAAE,gBAAgB,GAAG,IAAI,EAAE,GAAG,OAAO,CAAA;IAE3C,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,KAAK;QACd,MAAM;YACJ,OAAO;gBACL,GAAG,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE;gBAC/B,KAAK,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE;aAChC,CAAA;QACH,CAAC;QACD,kBAAkB,CAAC,IAAI;YACrB,IAAI,CAAC,gBAAgB;gBAAE,OAAO,IAAI,CAAA;YAClC,6DAA6D;YAC7D,uDAAuD;YACvD,OAAO,IAAI,CAAC,OAAO,CACjB,gBAAgB,EAChB,WAAW,iBAAiB,EAAE,CAC/B,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC","sourcesContent":["/**\n * Vite plugin for Plex UI.\n *\n * Importing `@plexui/styles/vite` (React apps can keep `@plexui/ui/vite`,\n * which re-exports it) and adding `plexui()` to your `plugins` array\n * eliminates every install-time gotcha documented in /docs/installation:\n *\n *   1. Pins `css.transformer = 'postcss'` so Lightning CSS doesn't\n *      reorder cascade layers strict-by-first-occurrence.\n *   2. Pins `build.cssMinify = 'esbuild'` so Vite 8's Lightning CSS\n *      minifier doesn't strip the bare `@layer` declaration.\n *   3. Injects `<style>@layer theme, base, components, utilities;</style>`\n *      into <head> as a runtime failsafe — the browser sees the layer\n *      order before any stylesheet rule arrives, regardless of how the\n *      bundler shuffles things.\n *\n * Usage:\n *\n *     // vite.config.ts\n *     import { defineConfig } from 'vite';\n *     import plexui from '@plexui/styles/vite';\n *\n *     export default defineConfig({\n *       plugins: [plexui()],\n *     });\n *\n * That replaces the manual `@layer …;` declaration in main.css and the\n * manual `css.transformer` / `build.cssMinify` overrides. Your global\n * stylesheet still needs `@import \"@plexui/styles/css\"` and `@source` —\n * those wire the runtime tokens and Tailwind class-extraction, which a\n * Vite plugin can't do for you.\n */\n\n// We deliberately do NOT import from \"vite\". Keeping vite out of the\n// build keeps it out of the runtime dependency graph entirely (the\n// plugin file is a few dozen lines and only describes the shape vite\n// expects). Consumers get full type-safety by declaring their config\n// `defineConfig({ plugins: [plexui()] })` — vite's own types cover the\n// `Plugin[]` slot, so our return value is just shaped to match it.\ntype ViteLikePlugin = {\n  name: string\n  enforce?: \"pre\" | \"post\"\n  config?: () => {\n    css?: { transformer?: \"postcss\" | \"lightningcss\" }\n    build?: { cssMinify?: boolean | \"esbuild\" | \"lightningcss\" }\n  }\n  transformIndexHtml?: (html: string) => string\n}\n\nconst LAYER_DECLARATION =\n  \"<style>@layer theme, base, components, utilities;</style>\"\n\nexport type PlexUIPluginOptions = {\n  /**\n   * Inject the cascade-layer `<style>` tag into <head> as a runtime\n   * failsafe. Defaults to `true`. Disable only if you've already added\n   * the equivalent `<style>` tag to your `index.html` by hand.\n   */\n  injectLayerOrder?: boolean\n}\n\nexport default function plexui(options: PlexUIPluginOptions = {}): ViteLikePlugin {\n  const { injectLayerOrder = true } = options\n\n  return {\n    name: \"@plexui/styles\",\n    enforce: \"pre\",\n    config() {\n      return {\n        css: { transformer: \"postcss\" },\n        build: { cssMinify: \"esbuild\" },\n      }\n    },\n    transformIndexHtml(html) {\n      if (!injectLayerOrder) return html\n      // Place the layer declaration right after <head> so it lands\n      // before any bundler-injected <link rel=\"stylesheet\">.\n      return html.replace(\n        /(<head[^>]*>)/i,\n        `$1\\n    ${LAYER_DECLARATION}`,\n      )\n    },\n  }\n}\n"]}

package/dist/types/types.d.ts

@@ -0,0 +1,15 @@
+export type Size = "5xs" | "4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl";
+export type Sizes<T extends Size = Size> = T;
+export type ControlSize = Sizes<"3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl">;
+export type Radius = "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "full";
+export type Radii<T extends Radius = Radius> = T;
+export type TextColor = "base" | "emphasis" | "secondary" | "tertiary";
+export type TextColors<T extends TextColor = TextColor> = T;
+export type SemanticColor = "primary" | "secondary" | "danger" | "success" | "warning" | "caution" | "discovery" | "info";
+export type SemanticColors<T extends SemanticColor = SemanticColor> = T;
+export type Variant = "solid" | "soft" | "outline" | "ghost";
+export type Variants<T extends Variant = Variant> = T;
+export type Alignment = "start" | "center" | "end";
+export type Alignments<T extends Alignment = Alignment> = T;
+export type FontWeight = "inherit" | "normal" | "medium" | "semibold" | "bold";
+export type FontWeights<T extends FontWeight = FontWeight> = T;

package/dist/types/vite/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Vite plugin for Plex UI.
+ *
+ * Importing `@plexui/styles/vite` (React apps can keep `@plexui/ui/vite`,
+ * which re-exports it) and adding `plexui()` to your `plugins` array
+ * eliminates every install-time gotcha documented in /docs/installation:
+ *
+ *   1. Pins `css.transformer = 'postcss'` so Lightning CSS doesn't
+ *      reorder cascade layers strict-by-first-occurrence.
+ *   2. Pins `build.cssMinify = 'esbuild'` so Vite 8's Lightning CSS
+ *      minifier doesn't strip the bare `@layer` declaration.
+ *   3. Injects `<style>@layer theme, base, components, utilities;</style>`
+ *      into <head> as a runtime failsafe — the browser sees the layer
+ *      order before any stylesheet rule arrives, regardless of how the
+ *      bundler shuffles things.
+ *
+ * Usage:
+ *
+ *     // vite.config.ts
+ *     import { defineConfig } from 'vite';
+ *     import plexui from '@plexui/styles/vite';
+ *
+ *     export default defineConfig({
+ *       plugins: [plexui()],
+ *     });
+ *
+ * That replaces the manual `@layer …;` declaration in main.css and the
+ * manual `css.transformer` / `build.cssMinify` overrides. Your global
+ * stylesheet still needs `@import "@plexui/styles/css"` and `@source` —
+ * those wire the runtime tokens and Tailwind class-extraction, which a
+ * Vite plugin can't do for you.
+ */
+type ViteLikePlugin = {
+    name: string;
+    enforce?: "pre" | "post";
+    config?: () => {
+        css?: {
+            transformer?: "postcss" | "lightningcss";
+        };
+        build?: {
+            cssMinify?: boolean | "esbuild" | "lightningcss";
+        };
+    };
+    transformIndexHtml?: (html: string) => string;
+};
+export type PlexUIPluginOptions = {
+    /**
+     * Inject the cascade-layer `<style>` tag into <head> as a runtime
+     * failsafe. Defaults to `true`. Disable only if you've already added
+     * the equivalent `<style>` tag to your `index.html` by hand.
+     */
+    injectLayerOrder?: boolean;
+};
+export default function plexui(options?: PlexUIPluginOptions): ViteLikePlugin;
+export {};

package/package.json

@@ -1,6 +1,111 @@
 {
   "name": "@plexui/styles",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Framework-agnostic CSS for Plex UI: design tokens, globals and component styles",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "sideEffects": [
+    "*.css"
+  ],
+  "homepage": "https://plexui.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/plex-ui/ui.git",
+    "directory": "packages/styles"
+  },
+  "keywords": [
+    "css",
+    "css-modules",
+    "design-system",
+    "design-tokens",
+    "tailwind",
+    "plexui",
+    "ui-kit"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/es/**",
+    "dist/types/**",
+    "postcss/*.mjs",
+    "!postcss/*.test.mjs",
+    "postcss.config.mjs"
+  ],
+  "exports": {
+    "./css": "./dist/es/styles/index.css",
+    "./styles/*": "./dist/es/styles/*",
+    "./components/*": "./dist/es/components/*",
+    "./vite": {
+      "types": "./dist/types/vite/index.d.ts",
+      "default": "./dist/es/vite/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/types.d.ts",
+      "default": "./dist/es/types.js"
+    },
+    "./postcss": "./postcss.config.mjs"
+  },
+  "scripts": {
+    "build:clean": "rm -rf dist",
+    "build:js": "tsc -p tsconfig.build.json",
+    "build:css": "node ./scripts/build-css.mjs",
+    "dev:js": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "dev:css": "node ./scripts/build-css.mjs --watch",
+    "dev": "npm run build:clean && npm run build:js && npm run build:css && (npm run dev:js & npm run dev:css & wait)",
+    "build": "npm run build:clean && npm run build:js && npm run build:css",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@tailwindcss/postcss": "^4.0.10",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8",
+    "postcss-functions": "^4.0.2",
+    "postcss-mixins": "^11.0.3",
+    "postcss-nested": "^7.0.2",
+    "postcss-selector-parser": "^7.1.0",
+    "postcss-value-parser": "^4.2.0",
+    "tailwindcss": "^4.0.10"
+  },
+  "peerDependenciesMeta": {
+    "@tailwindcss/postcss": {
+      "optional": true
+    },
+    "autoprefixer": {
+      "optional": true
+    },
+    "postcss": {
+      "optional": true
+    },
+    "postcss-functions": {
+      "optional": true
+    },
+    "postcss-mixins": {
+      "optional": true
+    },
+    "postcss-nested": {
+      "optional": true
+    },
+    "postcss-selector-parser": {
+      "optional": true
+    },
+    "postcss-value-parser": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "4.0.17",
+    "@types/postcss-functions": "4.0.4",
+    "@types/postcss-mixins": "9.0.6",
+    "autoprefixer": "10.4.20",
+    "postcss": "^8",
+    "postcss-functions": "^4.0.2",
+    "postcss-mixins": "^11.0.3",
+    "postcss-nested": "^7.0.2",
+    "postcss-selector-parser": "7.1.0",
+    "postcss-value-parser": "4.2.0",
+    "tailwindcss": "4.0.10",
+    "typescript": "5.7.3"
+  }
+}

package/postcss/functions.mjs

@@ -0,0 +1,23 @@
+import postcssFunctions from "postcss-functions"
+
+/** @type {import('postcss').PluginCreator} */
+export default function platformUIFunctions() {
+  return {
+    ...postcssFunctions({
+      functions: {
+        alpha: (value, amount) => {
+          const formattedAmount = amount.includes("%")
+            ? amount
+            : amount.startsWith(".") || amount.startsWith("0.")
+              ? `${parseFloat(amount) * 100}%`
+              : `${amount}%`
+          return `color-mix(in oklab, ${value} ${formattedAmount}, transparent)`
+        },
+        spacing: (value) => `calc(var(--spacing) * ${value})`,
+      },
+    }),
+    postcssPlugin: "plexui/components/postcss-functions",
+  }
+}
+
+platformUIFunctions.postcss = true

package/postcss/injectBreakpoints.mjs

@@ -0,0 +1,47 @@
+// @ts-check
+import postcss from "postcss"
+
+/**
+ * @typedef {import('postcss').PluginCreator<{ breakpoints: Record<string, number> }>} PostcssPluginCreator
+ */
+
+/**
+ * Injects the breakpoint variables into the CSS. Must run before tailwindcss.
+ *
+ * @type {PostcssPluginCreator}
+ */
+export default function injectBreakpoints(
+  /** @type {{ breakpoints: Record<string, number> }} */
+  { breakpoints },
+) {
+  return {
+    postcssPlugin: "plexui/components/inject-breakpoints",
+    Once(root) {
+      root.walkComments((comment) => {
+        // Look for comment containing "@inject_breakpoints"
+        if (comment.text.trim() === "@inject_breakpoints") {
+          // Generate breakpoint declarations
+          const declarations = []
+          for (const [key, value] of Object.entries(breakpoints)) {
+            declarations.push(
+              postcss.decl({
+                prop: `--breakpoint-${key}`,
+                value: `${value}px`,
+              }),
+            )
+          }
+
+          // Insert all declarations after the comment
+          declarations.reverse().forEach((decl) => {
+            comment.parent.insertAfter(comment, decl)
+          })
+
+          // Remove the comment
+          comment.remove()
+        }
+      })
+    },
+  }
+}
+
+injectBreakpoints.postcss = true

package/postcss/mixins.mjs

@@ -0,0 +1,100 @@
+// @ts-check
+import postcssMixins from "postcss-mixins"
+
+/**
+ * @typedef {import('postcss').PluginCreator<{ breakpoints: Record<string, number> }>} PostcssPluginCreator
+ */
+
+/** @type {PostcssPluginCreator} */
+export default function platformUIMixins(
+  /** @type {{ breakpoints: Record<string, number> }} */
+  { breakpoints },
+) {
+  /** @type {Record<string, string | undefined>} */
+  const mediaQueries = Object.entries(breakpoints).reduce((acc, [key, value]) => {
+    acc[key] = `(min-width: ${value}px)`
+    return acc
+  }, {})
+
+  const supportedBreakpoints = Object.keys(mediaQueries)
+    .join(", ")
+    .replace(/, ([^,]*)$/, " and $1")
+
+  return {
+    ...postcssMixins({
+      mixins: {
+        // @mixin breakpoint md { ... }            // scoped to current selector (default)
+        // @mixin breakpoint md global { ... }     // global (no selector wrapper)
+        breakpoint(_, targetBreakpointAndScope) {
+          const [breakpointName, scope = "scoped"] = targetBreakpointAndScope.trim().split(" ")
+
+          const mediaQuery = mediaQueries[breakpointName]
+
+          if (!mediaQuery) {
+            throw new Error(
+              `"${breakpointName}" is not a valid breakpoint. Supported breakpoints are ${supportedBreakpoints}.`,
+            )
+          }
+
+          const isGlobal = typeof scope === "string" && scope.toLowerCase() === "global"
+
+          return isGlobal
+            ? {
+                [`@media ${mediaQuery}`]: {
+                  "@mixin-content": {},
+                },
+              }
+            : {
+                [`@media ${mediaQuery}`]: {
+                  "&": {
+                    "@mixin-content": {},
+                  },
+                },
+              }
+        },
+
+        light() {
+          return {
+            ':where([data-theme="light"]) &': {
+              "@mixin-content": {},
+            },
+          }
+        },
+
+        dark() {
+          return {
+            ':where([data-theme="dark"]) &': {
+              "@mixin-content": {},
+            },
+          }
+        },
+
+        hover() {
+          return {
+            "@media (hover: hover) and (pointer: fine)": {
+              "&:hover": {
+                "@mixin-content": {},
+              },
+            },
+          }
+        },
+
+        autofill() {
+          return {
+            "&:-webkit-autofill, &:-webkit-autofill:focus, &:-webkit-autofill:hover": {
+              "@mixin-content": {},
+            },
+            // Identical to block above, but must keep separate for browsers to recognize their own selector
+            "&:-webkit-autofill-and-obscured, &:-webkit-autofill-strong-password, &:-webkit-autofill-strong-password-viewable":
+              {
+                "@mixin-content": {},
+              },
+          }
+        },
+      },
+    }),
+    postcssPlugin: "plexui/components/postcss-mixins",
+  }
+}
+
+platformUIMixins.postcss = true

package/postcss/parseLightDark.mjs

@@ -0,0 +1,174 @@
+import postcss from "postcss"
+import selectorParser from "postcss-selector-parser"
+import valueParser from "postcss-value-parser"
+
+/** @type {import('postcss').PluginCreator} */
+export default function platformUILightDark() {
+  return {
+    postcssPlugin: "plexui/components/parse-light-dark",
+    OnceExit(root) {
+      const stringifyThemeValue = (tokens, which) =>
+        tokens.map((tok) => (tok.isLD ? tok[which] : tok.raw)).join("")
+      // Split selector list into individual strings using selector parser
+      const splitSelectorList = (selector) => {
+        const list = []
+        selectorParser((rootSel) => {
+          rootSel.each((sel) => list.push(sel.toString().trim()))
+        }).processSync(selector)
+        return list
+      }
+
+      // Determine if selector is exactly :root or [data-theme], optionally wrapped in :where()
+      const isSimpleThemeScopeUsingParser = (selectorStr) => {
+        let result = false
+        selectorParser((rootSel) => {
+          if (rootSel.nodes.length !== 1) return
+          const sel = rootSel.nodes[0]
+          const onlyNode = () => (sel.nodes.length === 1 ? sel.nodes[0] : null)
+          const isSimpleNode = (node) =>
+            !!node &&
+            ((node.type === "pseudo" && node.value === ":root") ||
+              (node.type === "attribute" && node.attribute === "data-theme" && !node.operator))
+          // Direct simple
+          const n = onlyNode()
+          if (isSimpleNode(n)) {
+            result = true
+            return
+          }
+          // :where(simple)
+          if (n && n.type === "pseudo" && n.value === ":where" && n.nodes && n.nodes.length === 1) {
+            const innerSel = n.nodes[0]
+            if (innerSel.nodes.length === 1 && isSimpleNode(innerSel.nodes[0])) {
+              result = true
+            }
+          }
+        }).processSync(selectorStr)
+        return result
+      }
+      /** @type {Map<import('postcss').Rule, Array<{ prop: string; full: Array<any>; important: boolean }>>} */
+      const themeMap = new Map()
+
+      // 1) Collect & remove light-dark() decls, capturing !important
+      root.walkDecls((decl) => {
+        if (!decl.value.includes("light-dark(")) return
+
+        const parsed = valueParser(decl.value)
+        let sawLD = false
+        const tokens = []
+
+        for (const node of parsed.nodes) {
+          if (node.type === "function" && node.value === "light-dark") {
+            // inside node.nodes we expect [lightArg, comma, darkArg]
+            const [lightNode, , darkNode] = node.nodes
+            const light = valueParser.stringify(lightNode).trim()
+            const dark = valueParser.stringify(darkNode).trim()
+            tokens.push({ isLD: true, light, dark })
+            sawLD = true
+          } else {
+            tokens.push({ isLD: false, raw: valueParser.stringify(node) })
+          }
+        }
+        if (!sawLD) return
+
+        // store entries
+        const arr = themeMap.get(decl.parent) || []
+        arr.push({ prop: decl.prop, full: tokens, important: decl.important })
+        themeMap.set(decl.parent, arr)
+        decl.remove()
+      })
+
+      // 2) Emit transformed rules
+      const isSimpleThemeScope = (s) => isSimpleThemeScopeUsingParser(s)
+      const appendThemeRules = (parent, afterNode, entries, lightSelector, darkSelector) => {
+        const lightRule = postcss.rule({ selector: lightSelector })
+        const darkRule = postcss.rule({ selector: darkSelector })
+        for (const { prop, full, important } of entries) {
+          lightRule.append(
+            postcss.decl({ prop, value: stringifyThemeValue(full, "light"), important }),
+          )
+          darkRule.append(
+            postcss.decl({ prop, value: stringifyThemeValue(full, "dark"), important }),
+          )
+        }
+        parent.insertAfter(afterNode, lightRule)
+        parent.insertAfter(lightRule, darkRule)
+      }
+      for (const [rule, entries] of themeMap) {
+        const parent = rule.parent
+        if (!parent || !rule.selector) continue
+
+        // root selector
+        if (rule.selector === ":root") {
+          appendThemeRules(
+            parent,
+            rule,
+            entries,
+            ':where(:root), :where([data-theme="light"])',
+            ':where([data-theme="dark"])',
+          )
+
+          if (rule.nodes.length === 0) {
+            rule.remove()
+          }
+        } else {
+          // non-root selector: flatten to top-level grouped theme rules
+          const selList = splitSelectorList(rule.selector)
+
+          // Special-case: when selectors are only top-level theme scopes
+          // (:root and/or [data-theme]), treat them like :root by replacing
+          // with :where(:root) and :where([data-theme="light"]) instead of nesting.
+          const simpleScopes = selList.filter((s) => isSimpleThemeScope(s))
+          const otherSelectors = selList.filter((s) => !isSimpleThemeScope(s))
+          if (simpleScopes.length > 0 && otherSelectors.length === 0) {
+            appendThemeRules(
+              parent,
+              rule,
+              entries,
+              ':where(:root), :where([data-theme="light"])',
+              ':where([data-theme="dark"])',
+            )
+            if (rule.nodes.length === 0) {
+              rule.remove()
+            }
+          } else {
+            // Mixed or no simple scopes.
+            // - Include base selectors (light defaults) ONLY when there are no simple scopes.
+            // - Never nest simple scopes; instead add bare replacements.
+            const lightParts = []
+            const darkParts = []
+
+            // Base selectors (light defaults) only if no simple scopes are present
+            if (simpleScopes.length === 0) {
+              lightParts.push(...selList)
+            }
+
+            // Bare replacements for simple scopes
+            if (simpleScopes.includes(":root")) {
+              lightParts.push(":where(:root)")
+            }
+            if (simpleScopes.length > 0) {
+              lightParts.push(':where([data-theme="light"])')
+              darkParts.push(':where([data-theme="dark"])')
+            }
+
+            // Themed nested only for non-simple selectors
+            lightParts.push(...otherSelectors.map((s) => `:where([data-theme="light"]) ${s}`))
+            darkParts.push(...otherSelectors.map((s) => `:where([data-theme="dark"]) ${s}`))
+
+            // Dedupe while preserving order
+            const uniq = (arr) => Array.from(new Set(arr))
+            const lightSelector = uniq(lightParts).join(", ")
+            const darkSelector = uniq(darkParts).join(", ")
+
+            appendThemeRules(parent, rule, entries, lightSelector, darkSelector)
+            if (rule.nodes.length === 0) {
+              rule.remove()
+            }
+          }
+        }
+      }
+    },
+  }
+}
+
+platformUILightDark.postcss = true

package/postcss/wrapModulesInLayer.mjs

@@ -0,0 +1,21 @@
+// @ts-check
+import postcss from "postcss"
+
+/** @type {import('postcss').PluginCreator<{ layer?: string }>} */
+export default function wrapModulesInLayer({ layer = "components" } = {}) {
+  return {
+    postcssPlugin: "plexui/components/postcss-wrap-modules-in-layer",
+    Once(root, { result }) {
+      const file = result.opts.from
+      if (file && /\.module\.css$/.test(file)) {
+        const layerAtRule = postcss.atRule({ name: "layer", params: layer })
+        while (root.first) {
+          layerAtRule.append(root.first)
+        }
+        root.append(layerAtRule)
+      }
+    },
+  }
+}
+
+wrapModulesInLayer.postcss = true