@yahoo/uds 3.174.0 → 3.175.0

package/dist/automated-config/dist/utils/index.cjs

@@ -970,7 +970,7 @@ function generateConfigStyles(config, schema, theme, previewOptions, emit, gener
 * @param schema - Production schema with defaults and variables
 * @param theme - Tailwind theme function to resolve design tokens
 * @param previewOptions - Options for generating preview mode class modifiers
-* @returns CSS styles object with grouped selectors for default aliases
+* @returns CSS styles object with separate twin rules for default aliases
 */
 const generateStylesInner = (config, schema, theme, previewOptions, generateStylesContext) => {
 	const styles = generateConfigStyles(config, schema, theme, previewOptions, previewOptions.emit ?? "exhaustive", generateStylesContext);
@@ -1035,7 +1035,8 @@ const generateStylesInner = (config, schema, theme, previewOptions, generateStyl
 			finalStyles[selector] = declarations;
 			continue;
 		}
-		finalStyles[`${selector}, ${defaultsSelector}`] = declarations;
+		finalStyles[selector] = declarations;
+		finalStyles[defaultsSelector] = declarations;
 	}
 	return finalStyles;
 };

package/dist/automated-config/dist/utils/index.js

@@ -969,7 +969,7 @@ function generateConfigStyles(config, schema, theme, previewOptions, emit, gener
 * @param schema - Production schema with defaults and variables
 * @param theme - Tailwind theme function to resolve design tokens
 * @param previewOptions - Options for generating preview mode class modifiers
-* @returns CSS styles object with grouped selectors for default aliases
+* @returns CSS styles object with separate twin rules for default aliases
 */
 const generateStylesInner = (config, schema, theme, previewOptions, generateStylesContext) => {
 	const styles = generateConfigStyles(config, schema, theme, previewOptions, previewOptions.emit ?? "exhaustive", generateStylesContext);
@@ -1034,7 +1034,8 @@ const generateStylesInner = (config, schema, theme, previewOptions, generateStyl
 			finalStyles[selector] = declarations;
 			continue;
 		}
-		finalStyles[`${selector}, ${defaultsSelector}`] = declarations;
+		finalStyles[selector] = declarations;
+		finalStyles[defaultsSelector] = declarations;
 	}
 	return finalStyles;
 };

package/dist/css/dist/commands/css.cjs

@@ -27,6 +27,7 @@ const showHelp = () => {
 	require_print.print(`  ${require_colors.cyan("--verbose, -v")}     List every scanned file used for purging`);
 	require_print.print(`  ${require_colors.cyan("--workers <n>")}     Number of parallel workers (default: auto = CPU count - 1)`);
 	require_print.print(`  ${require_colors.cyan("--emit <mode>")}     Emission mode: exhaustive (default) | selective`);
+	require_print.print(`  ${require_colors.cyan("--utilities <mode>")} Utility ownership: emit (default) | app-sheet (omit app utilities; requires an onlyTheme app sheet with the same config)`);
 	require_print.print(`  ${require_colors.cyan("--include-dev-files")} Also scan test/spec/story files (excluded by default)`);
 	require_print.print(`  ${require_colors.cyan("--include-stories")}   Also scan story files, keeping test/spec excluded`);
 	require_print.print(`  ${require_colors.cyan("--force")}           Overwrite existing uds.theme.ts (for init)`);

package/dist/css/dist/commands/css.helpers.cjs

@@ -26,6 +26,11 @@ const parseEmitOption = (value) => {
 	if (value === "exhaustive" || value === "selective") return value;
 	throw new Error(`Invalid --emit "${String(value)}". Expected 'exhaustive' or 'selective'.`);
 };
+const parseUtilitiesOption = (value) => {
+	if (value === void 0 || value === null) return;
+	if (value === "emit" || value === "app-sheet") return value;
+	throw new Error(`Invalid --utilities "${String(value)}". Expected 'emit' or 'app-sheet'.`);
+};
 const getCssRunOptions = (workspaceDir, options) => {
 	return {
 		workspaceDir,
@@ -35,6 +40,7 @@ const getCssRunOptions = (workspaceDir, options) => {
 		entryOption: entryOption(options.entry),
 		configOption: stringOption(options.config),
 		emit: parseEmitOption(options.emit),
+		utilities: parseUtilitiesOption(options.utilities),
 		includeDevFiles: isTruthyFlag(options["include-dev-files"]) || isTruthyFlag(options.includeDevFiles) ? true : void 0,
 		includeStories: isTruthyFlag(options["include-stories"]) || isTruthyFlag(options.includeStories) ? true : void 0,
 		watch: isTruthyFlag(options.watch) || isTruthyFlag(options.w),

package/dist/css/dist/commands/css.helpers.js

@@ -26,6 +26,11 @@ const parseEmitOption = (value) => {
 	if (value === "exhaustive" || value === "selective") return value;
 	throw new Error(`Invalid --emit "${String(value)}". Expected 'exhaustive' or 'selective'.`);
 };
+const parseUtilitiesOption = (value) => {
+	if (value === void 0 || value === null) return;
+	if (value === "emit" || value === "app-sheet") return value;
+	throw new Error(`Invalid --utilities "${String(value)}". Expected 'emit' or 'app-sheet'.`);
+};
 const getCssRunOptions = (workspaceDir, options) => {
 	return {
 		workspaceDir,
@@ -35,6 +40,7 @@ const getCssRunOptions = (workspaceDir, options) => {
 		entryOption: entryOption(options.entry),
 		configOption: stringOption(options.config),
 		emit: parseEmitOption(options.emit),
+		utilities: parseUtilitiesOption(options.utilities),
 		includeDevFiles: isTruthyFlag(options["include-dev-files"]) || isTruthyFlag(options.includeDevFiles) ? true : void 0,
 		includeStories: isTruthyFlag(options["include-stories"]) || isTruthyFlag(options.includeStories) ? true : void 0,
 		watch: isTruthyFlag(options.watch) || isTruthyFlag(options.w),

package/dist/css/dist/commands/css.js

@@ -27,6 +27,7 @@ const showHelp = () => {
 	print(`  ${cyan("--verbose, -v")}     List every scanned file used for purging`);
 	print(`  ${cyan("--workers <n>")}     Number of parallel workers (default: auto = CPU count - 1)`);
 	print(`  ${cyan("--emit <mode>")}     Emission mode: exhaustive (default) | selective`);
+	print(`  ${cyan("--utilities <mode>")} Utility ownership: emit (default) | app-sheet (omit app utilities; requires an onlyTheme app sheet with the same config)`);
 	print(`  ${cyan("--include-dev-files")} Also scan test/spec/story files (excluded by default)`);
 	print(`  ${cyan("--include-stories")}   Also scan story files, keeping test/spec excluded`);
 	print(`  ${cyan("--force")}           Overwrite existing uds.theme.ts (for init)`);

package/dist/css/dist/css/generate.cjs

@@ -9,6 +9,7 @@ const require_nodeUtils = require("./nodeUtils.cjs");
 const require_spinner = require("../packages/cli/dist/lib/spinner.cjs");
 const require_index = require("../packages/config/dist/index.cjs");
 const require_safelist = require("../purger/optimized/utils/safelist.cjs");
+const require_filterUnusedVariantRules = require("../postcss/filterUnusedVariantRules.cjs");
 const require_generate_helpers = require("./generate.helpers.cjs");
 let node_fs = require("node:fs");
 node_fs = require_runtime.__toESM(node_fs, 1);
@@ -48,12 +49,14 @@ const generateCSS = async (safelist, config, options) => {
 			config,
 			enablePreflight: cssFlags.enablePreflight,
 			enableFontFaceDeclarations: cssFlags.enableFontFaceDeclarations,
-			emit: options?.cssOptions?.emit
+			emit: options?.cssOptions?.emit,
+			utilities: options?.cssOptions?.utilities
 		}),
 		shouldPruneVars: cssFlags.shouldPruneVars,
 		safeVarPrefixes: options?.safeVarPrefixes ?? [],
 		scopeClass,
-		otherBoundaryScopes: options?.otherBoundaryScopes ?? []
+		otherBoundaryScopes: options?.otherBoundaryScopes ?? [],
+		unusedVariantClasses: options?.variantClassMaps ? require_filterUnusedVariantRules.buildUnusedVariantClassSet(safelist, options.variantClassMaps) : void 0
 	});
 	const result = await require_perf.measureAsync("gen:postcss", () => (0, postcss.default)(plugins).process(sourceCSS, { from: void 0 }));
 	let css = await require_perf.measureAsync("gen:scoped-color-fix", () => require_generate_helpers.applyScopedColorModeFix(result.css, scopeClass));
@@ -106,6 +109,8 @@ const generateSimpleModeCSS = async (options) => {
 	]), tokensConfig, {
 		scope: options.scope,
 		contentDir: entryDirs,
+		variantClassMaps: [options.variants, options.autoVariants],
+		cssOptions: { utilities: options.utilities },
 		safeVarPrefixes: [...require_utils.getMotionVarPrefixes(options.componentData, [...allComponents]), ...require_utils.getConfigurableCssVariables()]
 	});
 	const outputPath = node_path.default.isAbsolute(options.outFile) ? options.outFile : node_path.default.join(options.workspaceDir, options.outFile);

package/dist/css/dist/css/generate.d.cts

@@ -1,6 +1,6 @@
 
 import { EmitMode } from "../packages/automated-config/dist/utils/index.cjs";
-import { TailwindSafelistConfig } from "./generate.helpers.cjs";
+import { TailwindSafelistConfig, UtilitiesMode } from "./generate.helpers.cjs";
 import { UDSCSSOptimizationOptions } from "./theme.cjs";
 
 //#region ../css/dist/css/generate.d.mts
@@ -27,6 +27,26 @@ interface UDSCSSOptions {
    * (`scoped` / `excludeBoundaries`) + the isolation fence for coexistence safety.
    */
   emit?: EmitMode;
+  /**
+   * Who owns utility (non-component) CSS in this bundle.
+   *
+   * - `'emit'` (default): compile utilities from the entry content scan into
+   *   this file using THIS theme's uds.config tokens — prefixed with `scope`
+   *   when set, so this theme's values win inside the scope even if the app
+   *   sheet's theme differs. Required when this file is the app's only
+   *   stylesheet, or when the root Tailwind config diverges from uds.config.
+   *
+   * - `'app-sheet'`: omit them — the app's root Tailwind sheet owns all
+   *   utilities, including inside `scope`. Only valid in the two-sheet
+   *   architecture where the root config uses
+   *   `tailwindPlugin({ onlyTheme: true })` with the SAME uds.config, so
+   *   utility values are identical and only specificity changes. Explicit
+   *   `css.safelist` entries are still emitted.
+   *
+   * Ignored (forced to `'emit'`, with a warning) for `scoped:` package
+   * bundles — their sources aren't part of any app sheet's content scan.
+   */
+  utilities?: UtilitiesMode;
   /**
    * Additional selectors whose subtrees this theme's bundles must not match.
    * Every emitted bundle (main and each `scoped:` entry) gets a

package/dist/css/dist/css/generate.d.ts

@@ -1,6 +1,6 @@
 
 import { EmitMode } from "../packages/automated-config/dist/utils/index.js";
-import { TailwindSafelistConfig } from "./generate.helpers.js";
+import { TailwindSafelistConfig, UtilitiesMode } from "./generate.helpers.js";
 import { UDSCSSOptimizationOptions } from "./theme.js";
 
 //#region ../css/dist/css/generate.d.mts
@@ -27,6 +27,26 @@ interface UDSCSSOptions {
    * (`scoped` / `excludeBoundaries`) + the isolation fence for coexistence safety.
    */
   emit?: EmitMode;
+  /**
+   * Who owns utility (non-component) CSS in this bundle.
+   *
+   * - `'emit'` (default): compile utilities from the entry content scan into
+   *   this file using THIS theme's uds.config tokens — prefixed with `scope`
+   *   when set, so this theme's values win inside the scope even if the app
+   *   sheet's theme differs. Required when this file is the app's only
+   *   stylesheet, or when the root Tailwind config diverges from uds.config.
+   *
+   * - `'app-sheet'`: omit them — the app's root Tailwind sheet owns all
+   *   utilities, including inside `scope`. Only valid in the two-sheet
+   *   architecture where the root config uses
+   *   `tailwindPlugin({ onlyTheme: true })` with the SAME uds.config, so
+   *   utility values are identical and only specificity changes. Explicit
+   *   `css.safelist` entries are still emitted.
+   *
+   * Ignored (forced to `'emit'`, with a warning) for `scoped:` package
+   * bundles — their sources aren't part of any app sheet's content scan.
+   */
+  utilities?: UtilitiesMode;
   /**
    * Additional selectors whose subtrees this theme's bundles must not match.
    * Every emitted bundle (main and each `scoped:` entry) gets a

package/dist/css/dist/css/generate.helpers.cjs

@@ -8,6 +8,7 @@ const require_entryPoints = require("../../../tailwind-internal/dist/utils/entry
 const require_pruneVars = require("../postcss/pruneVars.cjs");
 const require_safelist$1 = require("../purger/optimized/utils/safelist.cjs");
 const require_runner_helpers = require("./runner.helpers.cjs");
+const require_filterUnusedVariantRules = require("../postcss/filterUnusedVariantRules.cjs");
 const require_optimizeCSS = require("../utils/optimizeCSS.cjs");
 const require_postcss = require("./postcss.cjs");
 let node_fs = require("node:fs");
@@ -46,6 +47,10 @@ const getRawContentEntries = (rawContents) => rawContents.map((rawContent) => ({
 	raw: rawContent,
 	extension: "html"
 }));
+const getTailwindContentSources = (options) => {
+	const sources = [...options.utilities === "app-sheet" ? [] : getContentGlobs(options.contentDir), ...getRawContentEntries(options.rawContents)];
+	return sources.length > 0 ? sources : getRawContentEntries([""]);
+};
 const getTailwindEntrypointCandidates = () => [new URL("../../../tailwind-internal/dist/vendor/tailwindcss/lib/index.js", require("url").pathToFileURL(__filename).href), new URL("../vendor/tailwindcss/lib/index.js", require("url").pathToFileURL(__filename).href)];
 const loadTailwindcss = async () => {
 	for (const candidate of getTailwindEntrypointCandidates()) {
@@ -69,11 +74,11 @@ const getInternalIconModeCss = (scopeClass) => {
 };
 const createTailwindPlugin = async (options) => {
 	return (await loadTailwindcss())({
-		content: [
-			...getContentGlobs(options.contentDir),
-			...getRawContentEntries(getInternalSafelistRawContent(options.safelist)),
-			...getRawContentEntries(options.rawContents ?? [])
-		],
+		content: getTailwindContentSources({
+			contentDir: options.contentDir,
+			utilities: options.utilities,
+			rawContents: [...getInternalSafelistRawContent(options.safelist), ...options.rawContents ?? []]
+		}),
 		safelist: options.safelist,
 		corePlugins: { preflight: options.enablePreflight },
 		plugins: [require_tailwindPlugin.tailwindPlugin({
@@ -86,6 +91,7 @@ const createTailwindPlugin = async (options) => {
 };
 const buildPostcssPlugins = (options) => {
 	const plugins = [options.tailwindPlugin, (0, autoprefixer.default)()];
+	if (options.unusedVariantClasses && options.unusedVariantClasses.size > 0) plugins.splice(1, 0, require_filterUnusedVariantRules.filterUnusedVariantRulesPlugin(options.unusedVariantClasses));
 	if (options.shouldPruneVars) plugins.push(...require_pruneVars.getPruneVarPlugins(options.safeVarPrefixes));
 	if (options.scopeClass) plugins.push((0, postcss_scope.default)(options.scopeClass));
 	const otherBoundaryScopes = options.otherBoundaryScopes ?? [];

package/dist/css/dist/css/generate.helpers.d.cts

@@ -5,5 +5,11 @@ type TailwindSafelistConfig = string | {
   pattern: RegExp;
   variants?: string[];
 };
+/**
+ * Who owns utility (non-component) CSS in a generated bundle. `'emit'`
+ * compiles utilities from the entry content scan into the bundle;
+ * `'app-sheet'` omits them because the app's own Tailwind sheet supplies them.
+ */
+type UtilitiesMode = 'emit' | 'app-sheet';
 //#endregion
-export { TailwindSafelistConfig };
+export { TailwindSafelistConfig, UtilitiesMode };

package/dist/css/dist/css/generate.helpers.d.ts

@@ -7,5 +7,11 @@ type TailwindSafelistConfig = string | {
   pattern: RegExp;
   variants?: string[];
 };
+/**
+ * Who owns utility (non-component) CSS in a generated bundle. `'emit'`
+ * compiles utilities from the entry content scan into the bundle;
+ * `'app-sheet'` omits them because the app's own Tailwind sheet supplies them.
+ */
+type UtilitiesMode = 'emit' | 'app-sheet';
 //#endregion
-export { TailwindSafelistConfig };
+export { TailwindSafelistConfig, UtilitiesMode };

package/dist/css/dist/css/generate.helpers.js

@@ -7,6 +7,7 @@ import { hasAllowedEntryFileExtension } from "../../../tailwind-internal/dist/ut
 import { getPruneVarPlugins } from "../postcss/pruneVars.js";
 import { getInternalSafelistClasses } from "../purger/optimized/utils/safelist.js";
 import { formatCssDuration } from "./runner.helpers.js";
+import { filterUnusedVariantRulesPlugin } from "../postcss/filterUnusedVariantRules.js";
 import { optimizeCSS } from "../utils/optimizeCSS.js";
 import { appendIsolationExclusionPlugin, fixScopedColorModeSelectorsPlugin, fixScopedSelfOrParentSelectorsPlugin } from "./postcss.js";
 import fs from "node:fs";
@@ -40,6 +41,10 @@ const getRawContentEntries = (rawContents) => rawContents.map((rawContent) => ({
 	raw: rawContent,
 	extension: "html"
 }));
+const getTailwindContentSources = (options) => {
+	const sources = [...options.utilities === "app-sheet" ? [] : getContentGlobs(options.contentDir), ...getRawContentEntries(options.rawContents)];
+	return sources.length > 0 ? sources : getRawContentEntries([""]);
+};
 const getTailwindEntrypointCandidates = () => [new URL("../../../tailwind-internal/dist/vendor/tailwindcss/lib/index.js", import.meta.url), new URL("../vendor/tailwindcss/lib/index.js", import.meta.url)];
 const loadTailwindcss = async () => {
 	for (const candidate of getTailwindEntrypointCandidates()) {
@@ -63,11 +68,11 @@ const getInternalIconModeCss = (scopeClass) => {
 };
 const createTailwindPlugin = async (options) => {
 	return (await loadTailwindcss())({
-		content: [
-			...getContentGlobs(options.contentDir),
-			...getRawContentEntries(getInternalSafelistRawContent(options.safelist)),
-			...getRawContentEntries(options.rawContents ?? [])
-		],
+		content: getTailwindContentSources({
+			contentDir: options.contentDir,
+			utilities: options.utilities,
+			rawContents: [...getInternalSafelistRawContent(options.safelist), ...options.rawContents ?? []]
+		}),
 		safelist: options.safelist,
 		corePlugins: { preflight: options.enablePreflight },
 		plugins: [tailwindPlugin({
@@ -80,6 +85,7 @@ const createTailwindPlugin = async (options) => {
 };
 const buildPostcssPlugins = (options) => {
 	const plugins = [options.tailwindPlugin, autoprefixer()];
+	if (options.unusedVariantClasses && options.unusedVariantClasses.size > 0) plugins.splice(1, 0, filterUnusedVariantRulesPlugin(options.unusedVariantClasses));
 	if (options.shouldPruneVars) plugins.push(...getPruneVarPlugins(options.safeVarPrefixes));
 	if (options.scopeClass) plugins.push(postcssScope(options.scopeClass));
 	const otherBoundaryScopes = options.otherBoundaryScopes ?? [];

package/dist/css/dist/css/generate.js

@@ -8,6 +8,7 @@ import { loadConfigFile, scanDirectoriesForSafelist } from "./nodeUtils.js";
 import { spinStop } from "../packages/cli/dist/lib/spinner.js";
 import { defaultTokensConfig } from "../packages/config/dist/index.js";
 import { deduplicateSafelist, getInternalSafelistClasses, getThemeAndScaleClasses } from "../purger/optimized/utils/safelist.js";
+import { buildUnusedVariantClassSet } from "../postcss/filterUnusedVariantRules.js";
 import { applyScopedColorModeFix, buildPostcssPlugins, createTailwindPlugin, getCssFeatureFlags, getInternalIconModeCss, optimizeGeneratedCss, printSimpleModeStats } from "./generate.helpers.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -44,12 +45,14 @@ const generateCSS = async (safelist, config, options) => {
 			config,
 			enablePreflight: cssFlags.enablePreflight,
 			enableFontFaceDeclarations: cssFlags.enableFontFaceDeclarations,
-			emit: options?.cssOptions?.emit
+			emit: options?.cssOptions?.emit,
+			utilities: options?.cssOptions?.utilities
 		}),
 		shouldPruneVars: cssFlags.shouldPruneVars,
 		safeVarPrefixes: options?.safeVarPrefixes ?? [],
 		scopeClass,
-		otherBoundaryScopes: options?.otherBoundaryScopes ?? []
+		otherBoundaryScopes: options?.otherBoundaryScopes ?? [],
+		unusedVariantClasses: options?.variantClassMaps ? buildUnusedVariantClassSet(safelist, options.variantClassMaps) : void 0
 	});
 	const result = await measureAsync("gen:postcss", () => postcss(plugins).process(sourceCSS, { from: void 0 }));
 	let css = await measureAsync("gen:scoped-color-fix", () => applyScopedColorModeFix(result.css, scopeClass));
@@ -102,6 +105,8 @@ const generateSimpleModeCSS = async (options) => {
 	]), tokensConfig, {
 		scope: options.scope,
 		contentDir: entryDirs,
+		variantClassMaps: [options.variants, options.autoVariants],
+		cssOptions: { utilities: options.utilities },
 		safeVarPrefixes: [...getMotionVarPrefixes(options.componentData, [...allComponents]), ...getConfigurableCssVariables()]
 	});
 	const outputPath = path.isAbsolute(options.outFile) ? options.outFile : path.join(options.workspaceDir, options.outFile);

package/dist/css/dist/css/runner.cjs

@@ -151,6 +151,7 @@ const runSimpleMode = async (options, context) => {
 			autoVariants: context.autoVariants,
 			componentData: context.componentData,
 			scope: options.scope,
+			utilities: options.utilities,
 			configPath,
 			isWatch: options.watch,
 			silent: options.silent,
@@ -348,6 +349,8 @@ const runThemeMode = async (options, context) => {
 				]);
 				const allMotionComponents = [...inheritedComponents];
 				const emit = options.emit ?? themeConfig.css?.emit ?? "exhaustive";
+				const utilities = options.utilities ?? themeConfig.css?.utilities ?? "emit";
+				if (utilities === "app-sheet" && scopedPackageTargets.length > 0) genLog.warn(`css.utilities 'app-sheet' ignored for scoped bundles (${scopedPackageTargets.map((target) => target.packageName).join(", ")}): package sources aren't in any app sheet's content scan; utilities still emitted (scoped).`);
 				const allBoundarySelectors = [...emit === "selective" ? scopedPackageTargets.map((target) => target.scopeClass) : [], ...themeConfig.css?.excludeBoundaries ?? []];
 				require_perf.captureMemory("before-gen");
 				const mainCssResult = await require_perf.measureAsync("gen", () => require_generate.generateCSS([...themeConfig.css?.safelist ?? [], ...mainSafelist], appConfig, {
@@ -355,9 +358,11 @@ const runThemeMode = async (options, context) => {
 					contentDir: entryDirs,
 					cssOptions: {
 						...themeConfig.css,
-						emit
+						emit,
+						utilities
 					},
 					otherBoundaryScopes: allBoundarySelectors,
+					variantClassMaps: [context.variants, context.autoVariants],
 					safeVarPrefixes: [
 						...require_utils.getMotionVarPrefixes(context.componentData, allMotionComponents),
 						...require_utils.getConfigurableCssVariables(),
@@ -390,9 +395,11 @@ const runThemeMode = async (options, context) => {
 						contentDir: scopedPackageTarget.entryDirs,
 						cssOptions: {
 							...themeConfig.css,
-							emit
+							emit,
+							utilities: "emit"
 						},
 						otherBoundaryScopes: allBoundarySelectors.filter((selector) => selector !== scopedPackageTarget.scopeClass),
+						variantClassMaps: [context.variants, context.autoVariants],
 						referenceCss: themeConfig.css?.optimization?.deduplicateScopedCss === false ? void 0 : mainCssResult.css,
 						safeVarPrefixes: [
 							...require_utils.getMotionVarPrefixes(context.componentData, [...packageScanResult.components]),

package/dist/css/dist/css/runner.js

@@ -149,6 +149,7 @@ const runSimpleMode = async (options, context) => {
 			autoVariants: context.autoVariants,
 			componentData: context.componentData,
 			scope: options.scope,
+			utilities: options.utilities,
 			configPath,
 			isWatch: options.watch,
 			silent: options.silent,
@@ -346,6 +347,8 @@ const runThemeMode = async (options, context) => {
 				]);
 				const allMotionComponents = [...inheritedComponents];
 				const emit = options.emit ?? themeConfig.css?.emit ?? "exhaustive";
+				const utilities = options.utilities ?? themeConfig.css?.utilities ?? "emit";
+				if (utilities === "app-sheet" && scopedPackageTargets.length > 0) genLog.warn(`css.utilities 'app-sheet' ignored for scoped bundles (${scopedPackageTargets.map((target) => target.packageName).join(", ")}): package sources aren't in any app sheet's content scan; utilities still emitted (scoped).`);
 				const allBoundarySelectors = [...emit === "selective" ? scopedPackageTargets.map((target) => target.scopeClass) : [], ...themeConfig.css?.excludeBoundaries ?? []];
 				captureMemory("before-gen");
 				const mainCssResult = await measureAsync("gen", () => generateCSS([...themeConfig.css?.safelist ?? [], ...mainSafelist], appConfig, {
@@ -353,9 +356,11 @@ const runThemeMode = async (options, context) => {
 					contentDir: entryDirs,
 					cssOptions: {
 						...themeConfig.css,
-						emit
+						emit,
+						utilities
 					},
 					otherBoundaryScopes: allBoundarySelectors,
+					variantClassMaps: [context.variants, context.autoVariants],
 					safeVarPrefixes: [
 						...getMotionVarPrefixes(context.componentData, allMotionComponents),
 						...getConfigurableCssVariables(),
@@ -388,9 +393,11 @@ const runThemeMode = async (options, context) => {
 						contentDir: scopedPackageTarget.entryDirs,
 						cssOptions: {
 							...themeConfig.css,
-							emit
+							emit,
+							utilities: "emit"
 						},
 						otherBoundaryScopes: allBoundarySelectors.filter((selector) => selector !== scopedPackageTarget.scopeClass),
+						variantClassMaps: [context.variants, context.autoVariants],
 						referenceCss: themeConfig.css?.optimization?.deduplicateScopedCss === false ? void 0 : mainCssResult.css,
 						safeVarPrefixes: [
 							...getMotionVarPrefixes(context.componentData, [...packageScanResult.components]),

package/dist/css/dist/postcss/filterUnusedVariantRules.cjs

@@ -0,0 +1,71 @@
+/*! © 2026 Yahoo, Inc. UDS v0.0.0-development */
+//#region ../css/dist/postcss/filterUnusedVariantRules.mjs
+/*! © 2026 Yahoo, Inc. UDS CSS v0.0.0-development */
+const isPatternEntry = (entry) => typeof entry === "object" && entry !== null && entry.pattern instanceof RegExp;
+/**
+* Computes the variant classes that are enumerated by the variant class maps
+* but absent from the safelist, for every axis the scan DID find at least one
+* class of.
+*
+* Rationale: Tailwind v3 emits an `addComponents` rule when ANY class in its
+* selector matches a candidate, so variant-agnostic classes shared across
+* selectors (componentState classes like `…-value-checked-root`, default
+* aliases) ship rules for variants the app never uses. Restricting to axes
+* with at least one safelisted member keeps the filter conservative: an axis
+* the scanner never matched contributes nothing, so components that only
+* appear through another bundle or through raw `content` strings are left
+* untouched.
+*/
+const buildUnusedVariantClassSet = (safelist, variantClassMaps) => {
+	const safelistedClasses = new Set(safelist.filter((entry) => typeof entry === "string"));
+	const patterns = safelist.filter(isPatternEntry).map((entry) => entry.pattern);
+	const isSafelisted = (className) => safelistedClasses.has(className) || patterns.some((pattern) => pattern.test(className));
+	const axes = /* @__PURE__ */ new Map();
+	for (const map of variantClassMaps) for (const [axisKey, values] of Object.entries(map)) {
+		const axisClasses = axes.get(axisKey) ?? /* @__PURE__ */ new Set();
+		for (const className of Object.values(values)) if (typeof className === "string" && !/\s/.test(className)) axisClasses.add(className);
+		axes.set(axisKey, axisClasses);
+	}
+	const unused = /* @__PURE__ */ new Set();
+	for (const axisClasses of axes.values()) {
+		let axisIsScanned = false;
+		for (const className of axisClasses) if (isSafelisted(className)) {
+			axisIsScanned = true;
+			break;
+		}
+		if (!axisIsScanned) continue;
+		for (const className of axisClasses) if (!isSafelisted(className)) unused.add(className);
+	}
+	return unused;
+};
+const CLASS_TOKEN_RE = /\.((?:[a-zA-Z0-9_-]|\\.)+)/g;
+const selectorReferencesUnusedClass = (selector, unused) => {
+	for (const match of selector.matchAll(CLASS_TOKEN_RE)) if (unused.has(match[1])) return true;
+	return false;
+};
+/**
+* PostCSS plugin dropping selector alternatives (and whole rules) that
+* reference a variant class in `unused`. Runs on the Tailwind-generated
+* bundle, after which emptied `@media`/`@supports` blocks are removed. Placed
+* before var pruning so variables only referenced by dropped rules get pruned
+* too.
+*/
+const filterUnusedVariantRulesPlugin = (unused) => ({
+	postcssPlugin: "uds-filter-unused-variant-rules",
+	Once(root) {
+		if (unused.size === 0) return;
+		root.walkRules((rule) => {
+			if (!rule.selector.includes(".uds-")) return;
+			const kept = rule.selectors.filter((selector) => !selectorReferencesUnusedClass(selector, unused));
+			if (kept.length === rule.selectors.length) return;
+			if (kept.length === 0) rule.remove();
+			else rule.selector = kept.join(", ");
+		});
+		root.walkAtRules((atRule) => {
+			if ((atRule.name === "media" || atRule.name === "supports") && (atRule.nodes?.length ?? 0) === 0) atRule.remove();
+		});
+	}
+});
+//#endregion
+exports.buildUnusedVariantClassSet = buildUnusedVariantClassSet;
+exports.filterUnusedVariantRulesPlugin = filterUnusedVariantRulesPlugin;

package/dist/css/dist/postcss/filterUnusedVariantRules.js

@@ -0,0 +1,70 @@
+/*! © 2026 Yahoo, Inc. UDS v0.0.0-development */
+//#region ../css/dist/postcss/filterUnusedVariantRules.mjs
+/*! © 2026 Yahoo, Inc. UDS CSS v0.0.0-development */
+const isPatternEntry = (entry) => typeof entry === "object" && entry !== null && entry.pattern instanceof RegExp;
+/**
+* Computes the variant classes that are enumerated by the variant class maps
+* but absent from the safelist, for every axis the scan DID find at least one
+* class of.
+*
+* Rationale: Tailwind v3 emits an `addComponents` rule when ANY class in its
+* selector matches a candidate, so variant-agnostic classes shared across
+* selectors (componentState classes like `…-value-checked-root`, default
+* aliases) ship rules for variants the app never uses. Restricting to axes
+* with at least one safelisted member keeps the filter conservative: an axis
+* the scanner never matched contributes nothing, so components that only
+* appear through another bundle or through raw `content` strings are left
+* untouched.
+*/
+const buildUnusedVariantClassSet = (safelist, variantClassMaps) => {
+	const safelistedClasses = new Set(safelist.filter((entry) => typeof entry === "string"));
+	const patterns = safelist.filter(isPatternEntry).map((entry) => entry.pattern);
+	const isSafelisted = (className) => safelistedClasses.has(className) || patterns.some((pattern) => pattern.test(className));
+	const axes = /* @__PURE__ */ new Map();
+	for (const map of variantClassMaps) for (const [axisKey, values] of Object.entries(map)) {
+		const axisClasses = axes.get(axisKey) ?? /* @__PURE__ */ new Set();
+		for (const className of Object.values(values)) if (typeof className === "string" && !/\s/.test(className)) axisClasses.add(className);
+		axes.set(axisKey, axisClasses);
+	}
+	const unused = /* @__PURE__ */ new Set();
+	for (const axisClasses of axes.values()) {
+		let axisIsScanned = false;
+		for (const className of axisClasses) if (isSafelisted(className)) {
+			axisIsScanned = true;
+			break;
+		}
+		if (!axisIsScanned) continue;
+		for (const className of axisClasses) if (!isSafelisted(className)) unused.add(className);
+	}
+	return unused;
+};
+const CLASS_TOKEN_RE = /\.((?:[a-zA-Z0-9_-]|\\.)+)/g;
+const selectorReferencesUnusedClass = (selector, unused) => {
+	for (const match of selector.matchAll(CLASS_TOKEN_RE)) if (unused.has(match[1])) return true;
+	return false;
+};
+/**
+* PostCSS plugin dropping selector alternatives (and whole rules) that
+* reference a variant class in `unused`. Runs on the Tailwind-generated
+* bundle, after which emptied `@media`/`@supports` blocks are removed. Placed
+* before var pruning so variables only referenced by dropped rules get pruned
+* too.
+*/
+const filterUnusedVariantRulesPlugin = (unused) => ({
+	postcssPlugin: "uds-filter-unused-variant-rules",
+	Once(root) {
+		if (unused.size === 0) return;
+		root.walkRules((rule) => {
+			if (!rule.selector.includes(".uds-")) return;
+			const kept = rule.selectors.filter((selector) => !selectorReferencesUnusedClass(selector, unused));
+			if (kept.length === rule.selectors.length) return;
+			if (kept.length === 0) rule.remove();
+			else rule.selector = kept.join(", ");
+		});
+		root.walkAtRules((atRule) => {
+			if ((atRule.name === "media" || atRule.name === "supports") && (atRule.nodes?.length ?? 0) === 0) atRule.remove();
+		});
+	}
+});
+//#endregion
+export { buildUnusedVariantClassSet, filterUnusedVariantRulesPlugin };

package/dist/tailwind-internal/dist/packages/automated-config/dist/utils/index.cjs

@@ -956,7 +956,7 @@ function generateConfigStyles(config, schema, theme, previewOptions, emit, gener
 * @param schema - Production schema with defaults and variables
 * @param theme - Tailwind theme function to resolve design tokens
 * @param previewOptions - Options for generating preview mode class modifiers
-* @returns CSS styles object with grouped selectors for default aliases
+* @returns CSS styles object with separate twin rules for default aliases
 */
 const generateStylesInner = (config, schema, theme, previewOptions, generateStylesContext) => {
 	const styles = generateConfigStyles(config, schema, theme, previewOptions, previewOptions.emit ?? "exhaustive", generateStylesContext);
@@ -1021,7 +1021,8 @@ const generateStylesInner = (config, schema, theme, previewOptions, generateStyl
 			finalStyles[selector] = declarations;
 			continue;
 		}
-		finalStyles[`${selector}, ${defaultsSelector}`] = declarations;
+		finalStyles[selector] = declarations;
+		finalStyles[defaultsSelector] = declarations;
 	}
 	return finalStyles;
 };

package/dist/tailwind-internal/dist/packages/automated-config/dist/utils/index.js

@@ -955,7 +955,7 @@ function generateConfigStyles(config, schema, theme, previewOptions, emit, gener
 * @param schema - Production schema with defaults and variables
 * @param theme - Tailwind theme function to resolve design tokens
 * @param previewOptions - Options for generating preview mode class modifiers
-* @returns CSS styles object with grouped selectors for default aliases
+* @returns CSS styles object with separate twin rules for default aliases
 */
 const generateStylesInner = (config, schema, theme, previewOptions, generateStylesContext) => {
 	const styles = generateConfigStyles(config, schema, theme, previewOptions, previewOptions.emit ?? "exhaustive", generateStylesContext);
@@ -1020,7 +1020,8 @@ const generateStylesInner = (config, schema, theme, previewOptions, generateStyl
 			finalStyles[selector] = declarations;
 			continue;
 		}
-		finalStyles[`${selector}, ${defaultsSelector}`] = declarations;
+		finalStyles[selector] = declarations;
+		finalStyles[defaultsSelector] = declarations;
 	}
 	return finalStyles;
 };