From 994cbd41cfb0e8702cd4535bf4c9af0929bff8f8 Mon Sep 17 00:00:00 2001
From: Austin1serb <serbaustin@gmail.com>
Date: Thu, 31 Jul 2025 23:47:16 -0700
Subject: [PATCH] added useScopedUI hook

---
 .gitignore                                    |   2 +-
 package.json                                  |   5 +-
 packages/core/__tests__/e2e/next.spec.js      |   3 +-
 packages/core/__tests__/e2e/vite.spec.js      |   3 +-
 .../fixtures/next/.zero-ui/attributes.js      |   3 -
 .../core/__tests__/fixtures/next/app/FAQ.tsx  |   7 +-
 .../__tests__/fixtures/next/app/layout.tsx    |  20 ++-
 .../core/__tests__/fixtures/next/app/page.tsx |  17 +-
 .../fixtures/vite/.zero-ui/attributes.d.ts    |   1 +
 .../fixtures/vite/.zero-ui/attributes.js      |   4 +-
 .../core/__tests__/fixtures/vite/src/App.css  |   4 -
 .../core/__tests__/fixtures/vite/src/App.tsx  |  30 +++-
 .../fixtures/vite/src/ChildComponent.tsx      |  20 +++
 .../fixtures/vite/src/ChildWithoutSetter.tsx  |  14 ++
 .../core/__tests__/fixtures/vite/src/FAQ.tsx  |   7 +-
 packages/core/package.json                    |   2 +-
 packages/core/src/cli/postInstall.ts          |   4 +-
 packages/core/src/index.ts                    | 145 ++++--------------
 packages/core/src/internal.ts                 |  71 +++++++++
 .../core/src/postcss/ast-generating.test.ts   |   2 +-
 packages/core/src/postcss/ast-parsing.test.ts |  35 ++++-
 packages/core/src/postcss/ast-parsing.ts      |  53 ++++---
 packages/core/src/postcss/helpers.test.ts     |  18 +--
 packages/core/src/postcss/helpers.ts          |  18 ++-
 packages/core/src/postcss/index.cts           |  14 +-
 packages/core/src/postcss/resolvers.test.ts   |   2 +-
 packages/core/src/{ => postcss}/utilities.ts  |   0
 27 files changed, 296 insertions(+), 208 deletions(-)
 create mode 100644 packages/core/__tests__/fixtures/vite/src/ChildComponent.tsx
 create mode 100644 packages/core/__tests__/fixtures/vite/src/ChildWithoutSetter.tsx
 create mode 100644 packages/core/src/internal.ts
 rename packages/core/src/{ => postcss}/utilities.ts (100%)

diff --git a/.gitignore b/.gitignore
index 2338da7..0091b38 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,7 +19,7 @@ yarn-error.log*
 
 # tarballs produced during local tests
 *.tgz
-
+t.*
 
 # keep these files
 !next-env.d.ts
diff --git a/package.json b/package.json
index 95ecbc9..6077bb1 100644
--- a/package.json
+++ b/package.json
@@ -34,7 +34,8 @@
 		"lint": "eslint .",
 		"lint:fix": "eslint . --fix",
 		"typecheck": "tsc --noEmit --project tsconfig.base.json",
-		"size": "npx esbuild ./packages/core/dist/index.js --bundle --minify --format=esm --external:react --define:process.env.NODE_ENV='\"production\"' | gzip -c | wc -c"
+		"size": "npx esbuild ./packages/core/dist/index.js --bundle --minify --format=esm --external:react --define:process.env.NODE_ENV='\"production\"' | gzip -c | wc -c",
+		"build-output": "npx esbuild ./packages/core/dist/index.js --bundle --minify --format=esm --external:react --define:process.env.NODE_ENV='\"production\"'"
 	},
 	"devDependencies": {
 		"@eslint/js": "^9.30.1",
@@ -48,4 +49,4 @@
 		"tsx": "^4.20.3",
 		"typescript": "^5.8.3"
 	}
-}
+}
\ No newline at end of file
diff --git a/packages/core/__tests__/e2e/next.spec.js b/packages/core/__tests__/e2e/next.spec.js
index d3d4c73..b8263a9 100644
--- a/packages/core/__tests__/e2e/next.spec.js
+++ b/packages/core/__tests__/e2e/next.spec.js
@@ -178,7 +178,8 @@ test.describe('Zero-UI Next.js Integration Tests', () => {
 
 		// Click scope toggle
 		await page.getByTestId('scope-toggle').click();
-		await expect(body).toHaveAttribute('data-scope', 'off');
+		const scope = page.getByTestId('scope-container');
+		await expect(scope).toHaveAttribute('data-scope', 'on');
 
 		// Verify other states are preserved
 		await expect(body).toHaveAttribute('data-theme', 'dark');
diff --git a/packages/core/__tests__/e2e/vite.spec.js b/packages/core/__tests__/e2e/vite.spec.js
index 335d58e..6e7b5b3 100644
--- a/packages/core/__tests__/e2e/vite.spec.js
+++ b/packages/core/__tests__/e2e/vite.spec.js
@@ -167,7 +167,8 @@ test.describe('Zero-UI Next.js Integration Tests', () => {
 
 		// Click scope toggle
 		await page.getByTestId('scope-toggle').click();
-		await expect(body).toHaveAttribute('data-scope', 'off');
+		const scope = page.getByTestId('scope-container');
+		await expect(scope).toHaveAttribute('data-scope', 'on');
 
 		// Verify other states are preserved
 		await expect(body).toHaveAttribute('data-theme', 'dark');
diff --git a/packages/core/__tests__/fixtures/next/.zero-ui/attributes.js b/packages/core/__tests__/fixtures/next/.zero-ui/attributes.js
index 025aec9..3db700f 100644
--- a/packages/core/__tests__/fixtures/next/.zero-ui/attributes.js
+++ b/packages/core/__tests__/fixtures/next/.zero-ui/attributes.js
@@ -1,10 +1,7 @@
 /* AUTO-GENERATED - DO NOT EDIT */
 export const bodyAttributes = {
   "data-child": "closed",
-  "data-faq": "closed",
-  "data-mobile": "false",
   "data-number": "1",
-  "data-scope": "off",
   "data-theme": "light",
   "data-theme-2": "light",
   "data-theme-three": "light",
diff --git a/packages/core/__tests__/fixtures/next/app/FAQ.tsx b/packages/core/__tests__/fixtures/next/app/FAQ.tsx
index 628ddee..1c69f77 100644
--- a/packages/core/__tests__/fixtures/next/app/FAQ.tsx
+++ b/packages/core/__tests__/fixtures/next/app/FAQ.tsx
@@ -1,12 +1,13 @@
-import { useUI } from '@react-zero-ui/core';
+import { useScopedUI } from '@react-zero-ui/core';
 
 function FAQ({ question, answer, index }) {
-	const [, setOpen] = useUI<'open' | 'closed'>('faq', 'closed'); // Same key everywhere!
+	const [open, setOpen] = useScopedUI<'open' | 'closed'>('faq', 'closed'); // Same key everywhere!
 
 	return (
 		<div
 			ref={setOpen.ref}
-			data-index={index}>
+			data-index={index}
+			data-faq={open}>
 			<button
 				data-testid={`faq-${index}-toggle`}
 				className="bg-blue-500 text-white p-2 rounded-md m-5"
diff --git a/packages/core/__tests__/fixtures/next/app/layout.tsx b/packages/core/__tests__/fixtures/next/app/layout.tsx
index 07f1e2c..e7d8a25 100644
--- a/packages/core/__tests__/fixtures/next/app/layout.tsx
+++ b/packages/core/__tests__/fixtures/next/app/layout.tsx
@@ -1,15 +1,13 @@
-import { bodyAttributes } from '@zero-ui/attributes';
-import './globals.css';
+import { bodyAttributes } from "@zero-ui/attributes";import './globals.css';
 
 export default function RootLayout({ children }) {
-	return (
-		<html lang="en">
-			<body
-				{...bodyAttributes}
-				className="bg-red test-ww this is to test the body tag"
-				id="88">
+  return (
+    <html lang="en">
+			<body {...bodyAttributes}
+      className="bg-red test-ww this is to test the body tag"
+      id="88">
 				{children}
 			</body>
-		</html>
-	);
-}
+		</html>);
+
+}
\ No newline at end of file
diff --git a/packages/core/__tests__/fixtures/next/app/page.tsx b/packages/core/__tests__/fixtures/next/app/page.tsx
index 0fbe89a..d19bd6b 100644
--- a/packages/core/__tests__/fixtures/next/app/page.tsx
+++ b/packages/core/__tests__/fixtures/next/app/page.tsx
@@ -1,19 +1,20 @@
 'use client';
-import { useUI } from '@react-zero-ui/core';
+import { useScopedUI, useUI } from '@react-zero-ui/core';
 import UseEffectComponent from './UseEffectComponent';
 import FAQ from './FAQ';
 import { ChildComponent } from './ChildComponent';
 import { ChildWithoutSetter } from './ChildWithoutSetter';
 
 export default function Page() {
+	const [scope, setScope] = useScopedUI<'off' | 'on'>('scope', 'off');
+
 	const [, setTheme] = useUI<'light' | 'dark'>('theme', 'light');
 	const [, setTheme2] = useUI<'light' | 'dark'>('theme-2', 'light');
 	const [, setThemeThree] = useUI<'light' | 'dark'>('theme-three', 'light');
 	const [, setToggle] = useUI<'true' | 'false'>('toggle-boolean', 'true');
 	const [, setNumber] = useUI<'1' | '2'>('number', '1');
-	const [, setOpen] = useUI<'open' | 'closed'>('faq', 'closed'); // Same key everywhere!
-	const [, setScope] = useUI<'off' | 'on'>('scope', 'off');
-	const [, setMobile] = useUI<'true' | 'false'>('mobile', 'false');
+	const [open, setOpen] = useScopedUI<'open' | 'closed'>('faq', 'closed');
+	const [mobile, setMobile] = useScopedUI<'true' | 'false'>('mobile', 'false');
 	const [, setChildOpen] = useUI<'open' | 'closed'>('child', 'closed');
 
 	const [, setToggleFunction] = useUI<'white' | 'black'>('toggle-function', 'white');
@@ -145,6 +146,7 @@ export default function Page() {
 					className="scope-off:bg-blue-100 scope-on:bg-blue-900 scope-on:text-white"
 					data-testid="scope-container"
 					//this ref tells the hook to flip the data key here
+					data-scope={scope}
 					ref={setScope.ref}>
 					<button
 						type="button"
@@ -166,7 +168,8 @@ export default function Page() {
 					className="mobile-false:bg-blue-100 mobile-true:bg-blue-900 mobile-true:text-white"
 					data-testid="mobile-container"
 					//this ref tells the hook to flip the data key here
-					ref={setMobile.ref}>
+					ref={setMobile.ref}
+					data-mobile={mobile}>
 					<button
 						type="button"
 						onClick={() => {
@@ -194,7 +197,9 @@ export default function Page() {
 
 			<hr />
 
-			<div ref={setOpen.ref}>
+			<div
+				ref={setOpen.ref}
+				data-faq={open}>
 				<button
 					className="bg-blue-500 text-white p-2 rounded-md m-5"
 					onClick={() => setOpen((prev) => (prev === 'open' ? 'closed' : 'open'))}>
diff --git a/packages/core/__tests__/fixtures/vite/.zero-ui/attributes.d.ts b/packages/core/__tests__/fixtures/vite/.zero-ui/attributes.d.ts
index f0f376e..7fc6fba 100644
--- a/packages/core/__tests__/fixtures/vite/.zero-ui/attributes.d.ts
+++ b/packages/core/__tests__/fixtures/vite/.zero-ui/attributes.d.ts
@@ -1,5 +1,6 @@
 /* AUTO-GENERATED - DO NOT EDIT */
 export declare const bodyAttributes: {
+  "data-child": "closed" | "open";
   "data-faq": "closed" | "open";
   "data-mobile": "false" | "true";
   "data-number": "1" | "2";
diff --git a/packages/core/__tests__/fixtures/vite/.zero-ui/attributes.js b/packages/core/__tests__/fixtures/vite/.zero-ui/attributes.js
index 2bbbf57..3db700f 100644
--- a/packages/core/__tests__/fixtures/vite/.zero-ui/attributes.js
+++ b/packages/core/__tests__/fixtures/vite/.zero-ui/attributes.js
@@ -1,9 +1,7 @@
 /* AUTO-GENERATED - DO NOT EDIT */
 export const bodyAttributes = {
-  "data-faq": "closed",
-  "data-mobile": "false",
+  "data-child": "closed",
   "data-number": "1",
-  "data-scope": "off",
   "data-theme": "light",
   "data-theme-2": "light",
   "data-theme-three": "light",
diff --git a/packages/core/__tests__/fixtures/vite/src/App.css b/packages/core/__tests__/fixtures/vite/src/App.css
index 4a3a51c..c462dde 100644
--- a/packages/core/__tests__/fixtures/vite/src/App.css
+++ b/packages/core/__tests__/fixtures/vite/src/App.css
@@ -4,7 +4,3 @@
 	--color-primary: #000000;
 	--color-secondary: #ffffff;
 }
-
-body {
-	@apply bg-primary text-secondary;
-}
diff --git a/packages/core/__tests__/fixtures/vite/src/App.tsx b/packages/core/__tests__/fixtures/vite/src/App.tsx
index 180fc03..ea305dd 100644
--- a/packages/core/__tests__/fixtures/vite/src/App.tsx
+++ b/packages/core/__tests__/fixtures/vite/src/App.tsx
@@ -1,18 +1,22 @@
 'use client';
-import { useUI } from '@react-zero-ui/core';
+import { useUI, useScopedUI } from '@react-zero-ui/core';
 import UseEffectComponent from './UseEffectComponent';
 import FAQ from './FAQ';
 import './App.css';
+import { ChildComponent } from './ChildComponent';
+import { ChildWithoutSetter } from './ChildWithoutSetter';
 
 export default function App() {
+	const [scope, setScope] = useScopedUI<'off' | 'on'>('scope', 'off');
+
 	const [, setTheme] = useUI<'light' | 'dark'>('theme', 'light');
 	const [, setTheme2] = useUI<'light' | 'dark'>('theme-2', 'light');
 	const [, setThemeThree] = useUI<'light' | 'dark'>('theme-three', 'light');
 	const [, setToggle] = useUI<'true' | 'false'>('toggle-boolean', 'true');
 	const [, setNumber] = useUI<'1' | '2'>('number', '1');
-	const [, setOpen] = useUI<'open' | 'closed'>('faq', 'closed'); // Same key everywhere!
-	const [, setScope] = useUI<'off' | 'on'>('scope', 'off');
-	const [, setMobile] = useUI<'true' | 'false'>('mobile', 'false');
+	const [open, setOpen] = useScopedUI<'open' | 'closed'>('faq', 'closed'); // Same key everywhere!
+	const [mobile, setMobile] = useScopedUI<'true' | 'false'>('mobile', 'false');
+	const [, setChildOpen] = useUI<'open' | 'closed'>('child', 'closed');
 
 	const [, setToggleFunction] = useUI<'white' | 'black'>('toggle-function', 'white');
 
@@ -22,7 +26,7 @@ export default function App() {
 
 	return (
 		<div
-			className="p-8 theme-light:bg-white theme-dark:bg-white bg-black text-black"
+			className="p-8 theme-light:bg-white theme-dark:bg-white bg-black"
 			data-testid="page-container">
 			<h1 className="text-2xl font-bold py-5">Global State</h1>
 			<hr />
@@ -129,9 +133,13 @@ export default function App() {
 						Function: <span className="toggle-function-white:block hidden">White</span> <span className="toggle-function-black:block hidden">Black</span>
 					</div>
 				</div>
+				<hr />
+				<ChildComponent setIsOpen={setChildOpen} />
 			</div>
 			<hr />
+
 			<h1 className="text-2xl font-bold py-5">Scoped Style Tests</h1>
+
 			<hr />
 
 			<div className="border-2 border-blue-500">
@@ -139,6 +147,7 @@ export default function App() {
 					className="scope-off:bg-blue-100 scope-on:bg-blue-900 scope-on:text-white"
 					data-testid="scope-container"
 					//this ref tells the hook to flip the data key here
+					data-scope={scope}
 					ref={setScope.ref}>
 					<button
 						type="button"
@@ -147,18 +156,21 @@ export default function App() {
 						data-testid="scope-toggle">
 						Toggle Scope
 					</button>
+					<ChildWithoutSetter />
 					<div className="scope-on:bg-blue-900 scope-off:bg-blue-100 ">
 						Scope: <span className="scope-off:block scope-on:hidden">False</span>
 						<span className="scope-on:block scope-off:hidden">True</span>
 					</div>
 				</div>
+
 				<hr />
 
 				<div
 					className="mobile-false:bg-blue-100 mobile-true:bg-blue-900 mobile-true:text-white"
 					data-testid="mobile-container"
 					//this ref tells the hook to flip the data key here
-					ref={setMobile.ref}>
+					ref={setMobile.ref}
+					data-mobile={mobile}>
 					<button
 						type="button"
 						onClick={() => {
@@ -184,7 +196,11 @@ export default function App() {
 				</div>
 			</div>
 
-			<div ref={setOpen.ref}>
+			<hr />
+
+			<div
+				ref={setOpen.ref}
+				data-faq={open}>
 				<button
 					className="bg-blue-500 text-white p-2 rounded-md m-5"
 					onClick={() => setOpen((prev) => (prev === 'open' ? 'closed' : 'open'))}>
diff --git a/packages/core/__tests__/fixtures/vite/src/ChildComponent.tsx b/packages/core/__tests__/fixtures/vite/src/ChildComponent.tsx
new file mode 100644
index 0000000..00d9d46
--- /dev/null
+++ b/packages/core/__tests__/fixtures/vite/src/ChildComponent.tsx
@@ -0,0 +1,20 @@
+import { type UISetterFn } from '@react-zero-ui/core';
+
+export function ChildComponent({ setIsOpen }: { setIsOpen: UISetterFn<'open' | 'closed'> }) {
+	return (
+		<div
+			className="child-closed:bg-gray-100 child-open:bg-gray-900 child-open:text-white"
+			data-testid="child-container">
+			<button
+				type="button"
+				onClick={() => setIsOpen((prev) => (prev === 'closed' ? 'open' : 'closed'))}
+				className="border-2 border-red-500"
+				data-testid="child-toggle">
+				Toggle Child
+			</button>
+			<div className="child-closed:bg-gray-100 child-open:bg-gray-900 flex">
+				Child: <span className="child-open:block child-closed:hidden">Open</span> <span className="child-closed:block child-open:hidden">Closed</span>
+			</div>
+		</div>
+	);
+}
diff --git a/packages/core/__tests__/fixtures/vite/src/ChildWithoutSetter.tsx b/packages/core/__tests__/fixtures/vite/src/ChildWithoutSetter.tsx
new file mode 100644
index 0000000..8c90e96
--- /dev/null
+++ b/packages/core/__tests__/fixtures/vite/src/ChildWithoutSetter.tsx
@@ -0,0 +1,14 @@
+export function ChildWithoutSetter() {
+	return (
+		<div className="border-2 border-blue-500">
+			<div
+				className="scope-on:bg-blue-900 scope-off:bg-blue-100  scope-on:text-white bg-red-500"
+				data-testid="child-scope-container">
+				<div className="scope-off:bg-blue-100 scope-on:bg-blue-900  ">
+					Child Scope: <span className="scope-off:block scope-on:hidden">False</span>
+					<span className="scope-on:block scope-off:hidden">True</span>
+				</div>
+			</div>
+		</div>
+	);
+}
diff --git a/packages/core/__tests__/fixtures/vite/src/FAQ.tsx b/packages/core/__tests__/fixtures/vite/src/FAQ.tsx
index c14fb9e..e29102b 100644
--- a/packages/core/__tests__/fixtures/vite/src/FAQ.tsx
+++ b/packages/core/__tests__/fixtures/vite/src/FAQ.tsx
@@ -1,12 +1,13 @@
-import { useUI } from '@react-zero-ui/core';
+import { useScopedUI } from '@react-zero-ui/core';
 
 function FAQ({ question, answer, index }: { question: string; answer: string; index: number }) {
-	const [, setOpen] = useUI<'open' | 'closed'>('faq', 'closed'); // Same key everywhere!
+	const [open, setOpen] = useScopedUI<'open' | 'closed'>('faq', 'closed'); // Same key everywhere!
 
 	return (
 		<div
 			ref={setOpen.ref}
-			data-index={index}>
+			data-index={index}
+			data-faq={open}>
 			<button
 				data-testid={`faq-${index}-toggle`}
 				className="bg-blue-500 text-white p-2 rounded-md m-5"
diff --git a/packages/core/package.json b/packages/core/package.json
index 1d4c0b0..cf2a32a 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "@react-zero-ui/core",
-	"version": "0.2.7",
+	"version": "0.2.8",
 	"description": "Zero re-render, global UI state management for React",
 	"private": false,
 	"type": "module",
diff --git a/packages/core/src/cli/postInstall.ts b/packages/core/src/cli/postInstall.ts
index e76114a..d8aeef3 100644
--- a/packages/core/src/cli/postInstall.ts
+++ b/packages/core/src/cli/postInstall.ts
@@ -20,10 +20,10 @@ export async function runZeroUiInit() {
 		}
 
 		// Process all variants using the shared helper
-		const { finalVariants, initialValues, sourceFiles } = await processVariants();
+		const { finalVariants, initialGlobalValues, sourceFiles } = await processVariants();
 
 		// Generate attribute files using the shared helper
-		await generateAttributesFile(finalVariants, initialValues);
+		await generateAttributesFile(finalVariants, initialGlobalValues);
 
 		console.log(`[Zero-UI] ✅ Initialized with ${finalVariants.length} variants from ${sourceFiles.length} files`);
 
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index d4ed088..5bb2049 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1,138 +1,57 @@
 'use client';
-import { useCallback, useRef, type RefObject } from 'react';
+import { useRef, type RefObject } from 'react';
+import { makeSetter } from './internal.js';
 
 type UIAction<T extends string> = T | ((prev: T) => T);
 
-interface UISetterFn<T extends string = string> {
+interface ScopedSetterFn<T extends string = string> {
 	(action: UIAction<T>): void; //  ← SINGLE source of truth
 	ref?: RefObject<any> | ((node: HTMLElement | null) => void);
 }
 
-interface GlobalThis {
-	__useUIRegistry?: Map<string, string>;
-}
-
-function useUI<T extends string = string>(key: string, initialValue: T): [T, UISetterFn<T>] {
-	/* ─ DEV-ONLY COLLISION GUARD (removed in production by modern bundlers) ─ */
-	if (process.env.NODE_ENV !== 'production') {
-		//validate key and initialValue make sure there are no spaces
-		if (key.includes(' ') || initialValue.includes(' ')) {
-			throw new Error(`[Zero-UI] useUI(key, initialValue); key and initialValue must not contain spaces, got "${key}" and "${initialValue}"`);
-		}
-
-		// enforce kebab-case for the key: lowercase letters, digits and single dashes
-		if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(key)) {
-			throw new Error(
-				`[Zero-UI] useUI(key, …); key must be kebab-case (e.g. "theme-dark"), got "${key}". ` + `Avoid camelCase or uppercase — they break variant generation.`
-			);
-		}
-
-		// Validate inputs with helpful error messages
-		if (!key || typeof key !== 'string' || key.trim() === '') {
-			throw new Error(`useUI(key, initialValue); key must be a non-empty string, got "${key}"`);
-		}
-		// force string type for initialValue
-		if (typeof initialValue !== 'string') {
-			throw new Error(`useUI(key, initialValue); initialValue must be or resolve to a string, got "${typeof initialValue}"`);
-		}
+type GlobalSetterFn<T extends string> = (action: UIAction<T>) => void;
 
-		if (initialValue === '' || initialValue == null) {
-			throw new Error(`useUI(key, initialValue); initialValue cannot be empty string, null, or undefined, got "${initialValue}"`);
-		}
-		// One shared registry per window / Node context
-		const registry = typeof globalThis !== 'undefined' ? ((globalThis as GlobalThis).__useUIRegistry ||= new Map()) : new Map();
-
-		const prev = registry.get(key);
-		// TODO try to add per page error boundaries
-		if (prev !== undefined && prev !== initialValue) {
-			console.error(
-				`[useUI] Inconsistent initial values for key "${key}": ` +
-					`expected "${prev}", got "${initialValue}". ` +
-					`Use the same initial value everywhere or namespace your keys.`
-			);
-		} else if (prev === undefined) {
-			registry.set(key, initialValue);
-		}
-	}
-	/* ───────────────────────────────────────────────────────────── */
+function useUI<T extends string>(key: string, initial: T): [T, GlobalSetterFn<T>] {
+	return [initial, useRef(makeSetter(key, initial, () => document.body)).current as GlobalSetterFn<T>];
+}
 
+function useScopedUI<T extends string = string>(key: string, initialValue: T): [T, ScopedSetterFn<T>] {
 	// Create a ref to hold the DOM element that will receive the data-* attributes
 	// This allows scoping UI state to specific elements instead of always using document.body
 	const scopeRef = useRef<HTMLElement | null>(null);
 
-	/* ─ DEV-ONLY MULTIPLE REF GUARD (removed in production by modern bundlers) ─ */
-	const refAttachCount = process.env.NODE_ENV !== 'production' ? useRef(0) : null;
-	/* ─────────────────────────────────────────────────────────────────────── */
-
-	// Convert kebab-case key to camelCase for dataset property access
-	// e.g., "my-key" becomes "myKey" since dataset auto-lowercases after dashes
-	const camelKey = key.replace(/-([a-z])/g, (_, l) => l.toUpperCase());
+	const setterFn = useRef(makeSetter(key, initialValue, () => scopeRef.current!)).current as ScopedSetterFn<T>;
 
-	// Memoized setter function that updates data-* attributes on the target element
-	// useCallback prevents recreation on every render, essential for useEffect dependencies
-	const setValue: UISetterFn<T> = useCallback(
-		(valueOrUpdater: UIAction<T>) => {
-			// SSR safety: bail out if running on server where window is undefined
-			if (typeof window === 'undefined') return;
-
-			// Use the scoped element if ref is attached, otherwise fall back to document.body
-			// This enables both scoped UI state (with ref) and global UI state (without ref)
-			const target = scopeRef.current ?? document.body;
-
-			let newValue: T;
-			// Check if caller passed an updater function (like React's setState(prev => prev === 'true' ? 'false' : 'true') pattern)
-			if (typeof valueOrUpdater === 'function') {
-				const value = target.dataset[camelKey] as T;
-
-				// Call the updater function with the parsed current value
-				newValue = valueOrUpdater(value ?? initialValue);
-			} else {
-				// Direct value assignment (no updater function)
-				newValue = valueOrUpdater;
-			}
-
-			// Write the new value to the data-* attribute
-			target.dataset[camelKey] = newValue;
-		},
-		// Recreate callback only when the key changes
-		// Note: initialValue intentionally excluded since it should be stable
-		[key] // camelKey depends on key, so no need to include it in the dependency array
-	);
-
-	//  -- DEV-ONLY MULTIPLE REF GUARD (removed in production by modern bundlers)  --
-	// Attach the ref to the setter function so users can write: <div ref={setValue.ref} />
-	// This creates a clean API where the ref and setter are bundled together
 	if (process.env.NODE_ENV !== 'production') {
+		//  -- DEV-ONLY MULTIPLE REF GUARD (removed in production by modern bundlers)  --
+		// Attach the ref to the setter function so users can write: <div ref={setterFn.ref} />
+		const refAttachCount = useRef(0);
 		// DEV: Wrap scopeRef to detect multiple attachments
-		(setValue as UISetterFn<T>).ref = useCallback(
-			(node: HTMLElement | null) => {
-				if (node) {
-					refAttachCount!.current++;
-					if (refAttachCount!.current > 1) {
-						// TODO add documentation link
-						throw new Error(
-							`[useUI] Multiple ref attachments detected for key "${key}". ` +
-								`Each useUI hook supports only one ref attachment per component. ` +
-								`Solution: Create separate component. and reuse.\n` +
-								`Example: <FAQ/> <FAQ/> instead of multiple refs in one component.`
-						);
-					}
-				} else {
-					// Handle cleanup when ref is detached
-					refAttachCount!.current = Math.max(0, refAttachCount!.current - 1);
+		(setterFn as ScopedSetterFn<T>).ref = (node: HTMLElement | null) => {
+			if (node) {
+				refAttachCount!.current++;
+				if (refAttachCount!.current > 1) {
+					// TODO add documentation link
+					throw new Error(
+						`[useUI] Multiple ref attachments detected for key "${key}". ` +
+							`Each useScopedUI hook supports only one ref attachment per component. ` +
+							`Solution: Create separate component. and reuse.\n`
+					);
 				}
-				scopeRef.current = node;
-			},
-			[key]
-		);
+			} else {
+				// Handle cleanup when ref is detached
+				refAttachCount!.current = Math.max(0, refAttachCount!.current - 1);
+			}
+			scopeRef.current = node;
+		};
 	} else {
 		// PROD: Direct ref assignment for zero overhead
-		setValue.ref = scopeRef;
+		setterFn.ref = scopeRef;
 	}
 
 	// Return tuple matching React's useState pattern: [initialValue, setter]
-	return [initialValue, setValue];
+	return [initialValue, setterFn];
 }
 
-export { useUI };
-export type { UIAction, UISetterFn };
+export { useUI, useScopedUI };
+export type { UIAction, ScopedSetterFn, GlobalSetterFn };
diff --git a/packages/core/src/internal.ts b/packages/core/src/internal.ts
new file mode 100644
index 0000000..2547f1e
--- /dev/null
+++ b/packages/core/src/internal.ts
@@ -0,0 +1,71 @@
+// internal.ts
+
+export function makeSetter<T extends string>(key: string, initialValue: T, getTarget: () => HTMLElement) {
+	const camelKey = key.replace(/-([a-z])/g, (_, l) => l.toUpperCase());
+
+	if (process.env.NODE_ENV !== 'production') {
+		if (key.includes(' ') || initialValue.includes(' ')) {
+			throw new Error(`[Zero-UI] useUI(key, initialValue); key and initialValue must not contain spaces, got "${key}" and "${initialValue}"`);
+		}
+
+		// enforce kebab-case for the key: lowercase letters, digits and single dashes
+		if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(key)) {
+			throw new Error(
+				`[Zero-UI] useUI(key, …); key must be kebab-case (e.g. "theme-dark"), got "${key}". ` + `Avoid camelCase or uppercase — they break variant generation.`
+			);
+		}
+
+		// Validate inputs with helpful error messages
+		if (!key || typeof key !== 'string' || key.trim() === '') {
+			throw new Error(`useUI(key, initialValue); key must be a non-empty string, got "${key}"`);
+		}
+		// force string type for initialValue
+		if (typeof initialValue !== 'string') {
+			throw new Error(`useUI(key, initialValue); initialValue must be or resolve to a string, got "${typeof initialValue}"`);
+		}
+
+		if (initialValue === '' || initialValue == null) {
+			throw new Error(`useUI(key, initialValue); initialValue cannot be empty string, null, or undefined, got "${initialValue}"`);
+		}
+		// One shared registry per window / Node context
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const registry = typeof globalThis !== 'undefined' ? ((globalThis as any).__useUIRegistry ||= new Map()) : new Map();
+
+		const prev = registry.get(key);
+		// TODO try to add per page error boundaries
+		if (prev !== undefined && prev !== initialValue) {
+			console.error(
+				`[useUI] Inconsistent initial values for key "${key}": ` +
+					`expected "${prev}", got "${initialValue}". ` +
+					`Use the same initial value everywhere or namespace your keys.`
+			);
+		} else if (prev === undefined) {
+			registry.set(key, initialValue);
+		}
+	}
+	return (valueOrFn: T | ((prev: T) => T)) => {
+		// SSR safety: bail out if running on server where window is undefined
+		if (typeof window === 'undefined') return;
+
+		const target = getTarget();
+		if (process.env.NODE_ENV !== 'production') {
+			if (target === null) {
+				throw new Error(
+					`[Zero-UI] useScopedUI(key, initialValue); targetRef is null. \n` +
+						`This is likely due to a missing ref attachment. \n` +
+						`Solution: Attach a ref to the component.\n` +
+						`Example: <div ref={setValue.ref} />`
+				);
+			}
+		}
+
+		// Write the new value to the data-* attribute
+		target.dataset[camelKey] =
+			// Check if caller passed an updater function (like React's setState(prev => prev === 'true' ? 'false' : 'true') pattern)
+			typeof valueOrFn === 'function'
+				? // Call the updater function with the parsed current value - fallback to initial value if not set
+					valueOrFn((target.dataset[camelKey] as T) ?? initialValue)
+				: // Direct value assignment (no updater function)
+					valueOrFn;
+	};
+}
diff --git a/packages/core/src/postcss/ast-generating.test.ts b/packages/core/src/postcss/ast-generating.test.ts
index c41617b..cbf0ed5 100644
--- a/packages/core/src/postcss/ast-generating.test.ts
+++ b/packages/core/src/postcss/ast-generating.test.ts
@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert';
-import { readFile, runTest } from '../utilities.js';
+import { readFile, runTest } from './utilities.js';
 import { parseAndUpdatePostcssConfig, parseAndUpdateViteConfig, parseJsonWithBabel, patchNextBodyTag } from './ast-generating.js';
 
 const zeroUiPlugin = '@react-zero-ui/core/postcss';
diff --git a/packages/core/src/postcss/ast-parsing.test.ts b/packages/core/src/postcss/ast-parsing.test.ts
index 414d7b3..213a84f 100644
--- a/packages/core/src/postcss/ast-parsing.test.ts
+++ b/packages/core/src/postcss/ast-parsing.test.ts
@@ -2,7 +2,7 @@ import { test } from 'node:test';
 import assert from 'node:assert';
 import { collectUseUIHooks, processVariants } from './ast-parsing.js';
 import { parse } from '@babel/parser';
-import { readFile, runTest } from '../utilities.js';
+import { readFile, runTest } from './utilities.js';
 
 test('collectUseUIHooks should collect setters from a component', async () => {
 	await runTest(
@@ -16,8 +16,8 @@ test('collectUseUIHooks should collect setters from a component', async () => {
 			const theme = ['true'];
 
 export function Component() {
-	const [isVisible, setIsVisible] = useUI('modal-visible', 'false');
-	const [isEnabled, setIsEnabled] = useUI(bool ?? featureEnabled, theme[0]);
+	const [isVisible, setIsVisible] = useUI<'modal-visible', 'false'>('modal-visible', 'false');
+	const [isEnabled, setIsEnabled] = useUI<'feature-enabled', 'true'>(bool ?? featureEnabled, theme[0]);
 return (
 	<div>
 		<div
@@ -32,11 +32,11 @@ return (
 			const src = readFile('app/boolean-edge-cases.tsx');
 			const ast = parse(src, { sourceType: 'module', plugins: ['jsx', 'typescript'] });
 			const setters = collectUseUIHooks(ast, src);
-			assert(setters[0].binding !== null, 'binding should not be null');
+			// assert(setters[0].binding !== null, 'binding should not be null');
 			assert(setters[0].initialValue === 'false');
 			assert(setters[0].stateKey === 'modal-visible');
 			assert(setters[0].setterFnName === 'setIsVisible');
-			assert(setters[1].binding !== null, 'binding should not be null');
+			// assert(setters[1].binding !== null, 'binding should not be null');
 			assert(setters[1].initialValue === 'true');
 			assert(setters[1].stateKey === 'feature-enabled');
 			assert(setters[1].setterFnName === 'setIsEnabled');
@@ -62,7 +62,7 @@ test('collectUseUIHooks should resolve const-based args for useScopedUI', async
         const DEFAULT = 'first';
 
         export function Tabs() {
-          const [, setTab] = useScopedUI(KEY, DEFAULT);
+          const [, setTab] = useScopedUI<'tabs', 'first'>(KEY, DEFAULT);
           return <div ref={setTab.ref} />;
         }
       `,
@@ -78,3 +78,26 @@ test('collectUseUIHooks should resolve const-based args for useScopedUI', async
 		}
 	);
 });
+
+test('collectUseUIHooks handles + both hooks', async () => {
+	const code = `
+    import { useUI, useScopedUI } from '@react-zero-ui/core';
+    export function Comp() {
+      const [, setTheme] = useUI<'theme', 'dark'>('theme','dark');
+      const [, setAcc] = useScopedUI<'accordion', 'closed'>('accordion','closed');
+      return <section ref={setAcc.ref} />;
+    }
+  `;
+	const ast = parse(code, { sourceType: 'module', plugins: ['jsx', 'typescript'] });
+	const hooks = collectUseUIHooks(ast, code);
+	console.log('hooks: ', hooks);
+
+	assert.equal(hooks.length, 2);
+	assert.deepEqual(
+		hooks.map((h) => [h.stateKey, h.scope]),
+		[
+			['theme', 'global'],
+			['accordion', 'scoped'],
+		]
+	);
+});
diff --git a/packages/core/src/postcss/ast-parsing.ts b/packages/core/src/postcss/ast-parsing.ts
index 30f11f2..f7d5beb 100644
--- a/packages/core/src/postcss/ast-parsing.ts
+++ b/packages/core/src/postcss/ast-parsing.ts
@@ -9,7 +9,7 @@ import { codeFrameColumns } from '@babel/code-frame';
 import { LRUCache as LRU } from 'lru-cache';
 import { scanVariantTokens } from './scanner.js';
 import { findAllSourceFiles, mapLimit, toKebabCase } from './helpers.js';
-import { Binding, NodePath, Node } from '@babel/traverse';
+import { NodePath, Node } from '@babel/traverse';
 import traverse from './traverse.cjs';
 
 const PARSE_OPTS = (f: string): Partial<ParserOptions> => ({
@@ -19,8 +19,8 @@ const PARSE_OPTS = (f: string): Partial<ParserOptions> => ({
 });
 
 export interface HookMeta {
-	/** Babel binding object — use `binding.referencePaths` in Pass 2 */
-	binding: Binding;
+	/** Babel binding object — use `binding.referencePaths` */
+	// binding: Binding;
 	/** Variable name (`setTheme`) */
 	setterFnName: string;
 	/** State key passed to `useUI` (`'theme'`) */
@@ -40,6 +40,7 @@ export interface HookMeta {
  * Throws if the key is dynamic or if the initial value cannot be
  * reduced to a space-free string.
  */
+const ALL_HOOK_NAMES = new Set([CONFIG.HOOK_NAME, CONFIG.LOCAL_HOOK_NAME]);
 
 export function collectUseUIHooks(ast: t.File, sourceCode: string): HookMeta[] {
 	const hooks: HookMeta[] = [];
@@ -59,8 +60,6 @@ export function collectUseUIHooks(ast: t.File, sourceCode: string): HookMeta[] {
 		return value;
 	}
 
-	const ALL_HOOK_NAMES = new Set([CONFIG.HOOK_NAME, CONFIG.LOCAL_HOOK_NAME]);
-
 	traverse(ast, {
 		VariableDeclarator(path: NodePath<t.VariableDeclarator>) {
 			const { id, init } = path.node;
@@ -110,14 +109,14 @@ export function collectUseUIHooks(ast: t.File, sourceCode: string): HookMeta[] {
 				);
 			}
 
-			const binding = path.scope.getBinding(setterEl.name);
-			if (!binding) {
-				throwCodeFrame(path, path.opts?.filename, sourceCode, `[Zero-UI] Could not resolve binding for setter "${setterEl.name}".`);
-			}
+			// const binding = path.scope.getBinding(setterEl.name);
+			// if (!binding) {
+			// 	throwCodeFrame(path, path.opts?.filename, sourceCode, `[Zero-UI] Could not resolve binding for setter "${setterEl.name}".`);
+			// }
 
 			const scope: 'global' | 'scoped' = init.callee.name === CONFIG.HOOK_NAME ? 'global' : 'scoped';
 
-			hooks.push({ binding, setterFnName: setterEl.name, stateKey, initialValue, scope });
+			hooks.push({ setterFnName: setterEl.name, stateKey, initialValue, scope });
 		},
 	});
 
@@ -131,6 +130,8 @@ export interface VariantData {
 	values: string[];
 	/** Literal initial value as string, or `null` if non-literal */
 	initialValue: string | null;
+	/** Whether the variant is global or scoped */
+	scope: 'global' | 'scoped';
 }
 
 /* ── LRU cache keyed by absolute file path ──────────────────────────── */
@@ -151,7 +152,7 @@ export function clearCache(): void {
 /* ── Main compiler ──────────────────────────────────────────────────── */
 export interface ProcessVariantsResult {
 	finalVariants: VariantData[];
-	initialValues: Record<string, string>;
+	initialGlobalValues: Record<string, string>;
 	sourceFiles: string[];
 }
 
@@ -209,16 +210,25 @@ export async function processVariants(changedFiles: string[] | null = null): Pro
 	/* Phase D — aggregate variant & initial-value maps */
 	const variantMap = new Map<string, Set<string>>();
 	const initMap = new Map<string, string>();
+	const scopeMap = new Map<string, 'global' | 'scoped'>();
 
 	for (const { hooks, tokens } of fileCache.values()) {
-		// initial values
 		hooks.forEach((h) => {
-			if (!h.initialValue) return;
-			const prev = initMap.get(h.stateKey);
-			if (prev && prev !== h.initialValue) {
-				throw new Error(`[Zero-UI] Conflicting initial values for '${h.stateKey}': '${prev}' vs '${h.initialValue}'`);
+			/* initial-value aggregation */
+			if (h.initialValue) {
+				const prev = initMap.get(h.stateKey);
+				if (prev && prev !== h.initialValue) {
+					throw new Error(`[Zero-UI] Conflicting initial values for '${h.stateKey}': '${prev}' vs '${h.initialValue}'`);
+				}
+				initMap.set(h.stateKey, h.initialValue);
+			}
+
+			/* scope aggregation — always run */
+			const prevScope = scopeMap.get(h.stateKey);
+			if (prevScope && prevScope !== h.scope) {
+				throw new Error(`[Zero-UI] Key "${h.stateKey}" used with both global and scoped hooks.`);
 			}
-			initMap.set(h.stateKey, h.initialValue);
+			scopeMap.set(h.stateKey, h.scope);
 		});
 
 		// tokens → variantMap
@@ -230,12 +240,15 @@ export async function processVariants(changedFiles: string[] | null = null): Pro
 
 	/* Phase E — final assembly */
 	const finalVariants: VariantData[] = [...variantMap]
-		.map(([key, set]) => ({ key, values: [...set].sort(), initialValue: initMap.get(key) ?? null }))
+		.map(([key, set]) => ({ key, values: [...set].sort(), initialValue: initMap.get(key) ?? null, scope: scopeMap.get(key)! }))
 		.sort((a, b) => a.key.localeCompare(b.key));
 
-	const initialValues = Object.fromEntries(finalVariants.map((v) => [`data-${toKebabCase(v.key)}`, v.initialValue ?? v.values[0] ?? '']));
+	const initialGlobalValues = Object.fromEntries(
+		// only include global variants in the initialGlobalValues object because scoped variants are handled by the component data-attributes
+		finalVariants.filter((v) => v.scope === 'global').map((v) => [`data-${toKebabCase(v.key)}`, v.initialValue ?? v.values[0] ?? ''])
+	);
 
-	return { finalVariants, initialValues, sourceFiles: srcFiles };
+	return { finalVariants, initialGlobalValues, sourceFiles: srcFiles };
 }
 
 /**
diff --git a/packages/core/src/postcss/helpers.test.ts b/packages/core/src/postcss/helpers.test.ts
index 3441ecf..f571f0d 100644
--- a/packages/core/src/postcss/helpers.test.ts
+++ b/packages/core/src/postcss/helpers.test.ts
@@ -10,10 +10,10 @@ import {
 	patchViteConfig,
 	toKebabCase,
 } from './helpers.js';
-import { readFile, runTest } from '../utilities.js';
+import { readFile, runTest } from './utilities.js';
 import { CONFIG } from '../config.js';
 import path from 'node:path';
-import { processVariants } from './ast-parsing.js';
+import { processVariants, VariantData } from './ast-parsing.js';
 
 test('toKebabCase should convert a string to kebab case', () => {
 	assert.equal(toKebabCase('helloWorld'), 'hello-world');
@@ -40,9 +40,9 @@ return (
 	</div>
 ); }`;
 
-const expectedVariants = [
-	{ key: 'feature-enabled', values: ['false'], initialValue: 'true' },
-	{ key: 'modal-visible', values: ['true'], initialValue: 'false' },
+const expectedVariants: VariantData[] = [
+	{ key: 'feature-enabled', values: ['false'], initialValue: 'true', scope: 'global' },
+	{ key: 'modal-visible', values: ['true'], initialValue: 'false', scope: 'global' },
 ];
 const initialValues = { 'data-feature-enabled': 'true', 'data-modal-visible': 'false' };
 
@@ -53,9 +53,9 @@ test('findAllSourceFiles Return *absolute* paths of every JS/TS file we care abo
 
 test('processVariants should process variants', async () => {
 	await runTest({ 'src/app/component.tsx': src }, async () => {
-		const { finalVariants, initialValues, sourceFiles } = await processVariants();
+		const { finalVariants, initialGlobalValues, sourceFiles } = await processVariants();
 		assert.deepStrictEqual(finalVariants, expectedVariants);
-		assert.deepStrictEqual(initialValues, initialValues);
+		assert.deepStrictEqual(initialGlobalValues, initialValues);
 		assert.equal(sourceFiles.length, 1);
 	});
 });
@@ -65,9 +65,7 @@ const norm = (s: string) => s.replace(/\r\n/g, '\n');
 
 test('buildCss emits @custom-variant blocks in stable order', () => {
 	const css = buildCss(expectedVariants);
-	const expected = `${CONFIG.HEADER}
-@custom-variant feature-enabled-false {&:where(body[data-feature-enabled="false"] *) { @slot; } [data-feature-enabled="false"] &, &[data-feature-enabled="false"] { @slot; }}
-@custom-variant modal-visible-true {&:where(body[data-modal-visible="true"] *) { @slot; } [data-modal-visible="true"] &, &[data-modal-visible="true"] { @slot; }}\n`;
+	const expected = `/* AUTO-GENERATED - DO NOT EDIT */\n@custom-variant feature-enabled-false { &:where(body[data-feature-enabled='false'] &) { @slot; } }\n@custom-variant modal-visible-true { &:where(body[data-modal-visible='true'] &) { @slot; } }\n`;
 	assert.strictEqual(norm(css), norm(expected), 'CSS snapshot mismatch');
 });
 
diff --git a/packages/core/src/postcss/helpers.ts b/packages/core/src/postcss/helpers.ts
index ec6686e..227e074 100644
--- a/packages/core/src/postcss/helpers.ts
+++ b/packages/core/src/postcss/helpers.ts
@@ -50,16 +50,30 @@ export function findAllSourceFiles(patterns: string[] = CONFIG.CONTENT, cwd: str
 		.map((p) => path.resolve(p)); // normalize on Windows
 }
 
+function buildLocalSelector(keySlug: string, valSlug: string): string {
+	return `[data-${keySlug}="${valSlug}"] &, &[data-${keySlug}="${valSlug}"] { @slot; }`;
+}
+
+function buildGlobalSelector(keySlug: string, valSlug: string): string {
+	return `&:where(body[data-${keySlug}='${valSlug}'] &) { @slot; }`;
+}
+
 export function buildCss(variants: VariantData[]): string {
-	const lines = variants.flatMap(({ key, values }) => {
+	const lines = variants.flatMap(({ key, values, scope }) => {
 		if (values.length === 0) return [];
 		const keySlug = toKebabCase(key);
 
 		// Double-ensure sorted order, even if extractor didn't sort
 		return [...values].sort().map((v) => {
 			const valSlug = toKebabCase(v);
+			let selector;
+			if (scope === 'scoped') {
+				selector = buildLocalSelector(keySlug, valSlug);
+			} else {
+				selector = buildGlobalSelector(keySlug, valSlug);
+			}
 
-			return `@custom-variant ${keySlug}-${valSlug} {&:where(body[data-${keySlug}="${valSlug}"] *) { @slot; } [data-${keySlug}="${valSlug}"] &, &[data-${keySlug}="${valSlug}"] { @slot; }}`;
+			return `@custom-variant ${keySlug}-${valSlug} { ${selector} }`;
 		});
 	});
 
diff --git a/packages/core/src/postcss/index.cts b/packages/core/src/postcss/index.cts
index 99fc1be..e383a86 100644
--- a/packages/core/src/postcss/index.cts
+++ b/packages/core/src/postcss/index.cts
@@ -9,9 +9,10 @@ import { processVariants } from './ast-parsing';
 
 const plugin: PluginCreator<void> = () => {
 	const DEV = process.env.NODE_ENV !== 'production';
+	const zeroUIPlugin = 'postcss-react-zero-ui';
 
 	return {
-		postcssPlugin: 'postcss-react-zero-ui',
+		postcssPlugin: zeroUIPlugin,
 
 		async Once(root: Root, { result }) {
 			try {
@@ -21,21 +22,20 @@ const plugin: PluginCreator<void> = () => {
 					initialValues: Record<string, string>; // key: initialValue
 					sourceFiles: string[]; // file paths (absolute)
 	      */
-				const { finalVariants, initialValues, sourceFiles } = await processVariants();
+				const { finalVariants, initialGlobalValues, sourceFiles } = await processVariants();
 
 				const cssBlock = buildCss(finalVariants);
 				if (cssBlock.trim()) root.prepend(cssBlock + '\n');
 
 				/* ── register file-dependencies for HMR ─────────────────── */
-				sourceFiles.forEach((file) => result.messages.push({ type: 'dependency', plugin: 'postcss-react-zero-ui', file, parent: result.opts.from }));
+				sourceFiles.forEach((file) => result.messages.push({ type: 'dependency', plugin: zeroUIPlugin, file, parent: result.opts.from }));
 
 				/* ── first-run bootstrap ────────────────────────────────── */
 				if (!isZeroUiInitialized()) {
 					console.log('[Zero-UI] Auto-initializing (first-time setup)…');
 					await runZeroUiInit();
 				}
-
-				await generateAttributesFile(finalVariants, initialValues);
+				await generateAttributesFile(finalVariants, initialGlobalValues);
 			} catch (err: unknown) {
 				/* ───────────────── error handling ─────────────────────── */
 				const error = err instanceof Error ? err : new Error(String(err));
@@ -61,10 +61,10 @@ const plugin: PluginCreator<void> = () => {
 				/* ❸ Dev = warn + keep server alive  |  Prod = fail build */
 				if (DEV) {
 					if (eWithLoc.loc?.file) {
-						result.messages.push({ type: 'dependency', plugin: 'postcss-react-zero-ui', file: eWithLoc.loc.file, parent: result.opts.from });
+						result.messages.push({ type: 'dependency', plugin: zeroUIPlugin, file: eWithLoc.loc.file, parent: result.opts.from });
 					}
 
-					result.warn(friendly, { plugin: 'postcss-react-zero-ui', ...(eWithLoc.loc && { line: eWithLoc.loc.line, column: eWithLoc.loc.column }) });
+					result.warn(friendly, { plugin: zeroUIPlugin, ...(eWithLoc.loc && { line: eWithLoc.loc.line, column: eWithLoc.loc.column }) });
 
 					console.error('[Zero-UI] Full error (dev-only):\n', error);
 					return; // ← do **not** abort dev-server
diff --git a/packages/core/src/postcss/resolvers.test.ts b/packages/core/src/postcss/resolvers.test.ts
index 4b7d5e3..f24706e 100644
--- a/packages/core/src/postcss/resolvers.test.ts
+++ b/packages/core/src/postcss/resolvers.test.ts
@@ -4,7 +4,7 @@ import { parse } from '@babel/parser';
 import * as t from '@babel/types';
 import { NodePath } from '@babel/traverse';
 import { literalFromNode, resolveLocalConstIdentifier, resolveTemplateLiteral, resolveMemberExpression, ResolveOpts } from './resolvers.js';
-import { runTest } from '../utilities.js';
+import { runTest } from './utilities.js';
 import traverse from './traverse.cjs';
 
 /*
diff --git a/packages/core/src/utilities.ts b/packages/core/src/postcss/utilities.ts
similarity index 100%
rename from packages/core/src/utilities.ts
rename to packages/core/src/postcss/utilities.ts