@bamboocss/generator 1.28.1 → 1.30.0

package/dist/index.cjs

@@ -1373,15 +1373,35 @@ function generateSvaFn(ctx) {
 }
 //#endregion
 //#region src/artifacts/js/token.ts
+/**
+* `token()` hands back the variable reference for every token, and `token.value()` the
+* resolved literal.
+*
+* It used to be the other way round, decided per token: a base token resolved to its literal
+* and a virtual or conditional one to its `var()`. That made the return kind a property of
+* the *theme* rather than of the call, so adding `_dark` to a token silently changed what
+* every caller received — same call, same path, a colour before and a variable after, with
+* both typed `string` and nothing to catch it.
+*
+* Always-a-reference is the predictable half and the one that keeps working when a theme
+* switches, so it takes the short name. The literal is still reachable, but has to be asked
+* for — which is also the honest signal, since it is the form that stops responding to
+* conditions.
+*
+* `value` keeps the old per-token split rather than becoming `token.value` for everything:
+* a virtual or conditional token has no single literal to hand back, so its `var()` is still
+* the only truthful answer.
+*/
 function generateTokenJs(ctx) {
 	const { tokens } = ctx;
 	const map = /* @__PURE__ */ new Map();
 	tokens.allTokens.forEach((token) => {
 		const { varRef, isVirtual } = token.extensions;
-		const value = isVirtual || token.extensions.condition !== "base" ? varRef : token.value;
+		const variable = tokens.view.getVar(token.name) ?? varRef;
+		const value = tokens.view.get(token.name) ?? (isVirtual || token.extensions.condition !== "base" ? varRef : token.value);
 		map.set(token.name, {
 			value,
-			variable: varRef
+			variable
 		});
 	});
 	const obj = Object.fromEntries(map);
@@ -1389,22 +1409,40 @@ function generateTokenJs(ctx) {
 		js: outdent.default`
   const tokens = ${JSON.stringify(obj, null, 2)}
 
-  export function token(path, fallback) {
-    return tokens[path]?.value || fallback
+  // No fallback parameter: \`token(path) ?? fallback\` says the same thing in the language, and
+  // the parameter had to be proved side-effect-free before a build could fold the call away.
+  export function token(path) {
+    return tokens[path]?.variable
   }
 
-  function tokenVar(path, fallback) {
-    return tokens[path]?.variable || fallback
+  function tokenValue(path) {
+    return tokens[path]?.value
   }
 
-  token.var = tokenVar
+  token.value = tokenValue
   `,
 		dts: outdent.default`
-  ${ctx.file.importType("Token", "./tokens")}
+  ${ctx.file.importType("Token, LiteralToken", "./tokens")}
 
   export declare const token: {
-    (path: Token, fallback?: string): string
-    var: (path: Token, fallback?: string) => string
+    /**
+     * The css variable reference — \`var(--colors-red-300)\`. Stays correct across themes.
+     *
+     * The parameter is the closed set of tokens the theme declares, so this always answers.
+     * A path cast past that type does not, which is the usual bargain for a cast.
+     */
+    (path: Token): string
+    /**
+     * The resolved literal — \`#fca5a5\`. Use where css variables cannot be resolved, such as
+     * a canvas fill or a charting library.
+     *
+     * Restricted to the tokens that have one. A virtual or conditional token resolves to its
+     * \`var()\` because there is no single value to hand back, and a negative token to
+     * \`calc(var(--spacing-4) * -1)\` because it has no declaration of its own — so asking for
+     * a literal that cannot exist is a type error rather than a reference the caller then
+     * hands to a canvas.
+     */
+    value: (path: LiteralToken) => string
   }
 
   ${ctx.file.exportTypeStar("./tokens")}
@@ -2430,6 +2468,8 @@ const restrict = (key, value, config) => {
 };
 //#endregion
 //#region src/artifacts/types/token-types.ts
+/** A css function whose result only the browser can produce, so it is never a literal. */
+const COMPUTED_BY_CSS = /\b(?:var|env|attr)\s*\(/i;
 const categories = [
 	"aspectRatios",
 	"zIndex",
@@ -2459,6 +2499,7 @@ function generateTokenTypes(ctx) {
 	const { tokens } = ctx;
 	const set = /* @__PURE__ */ new Set();
 	const tokenSet = /* @__PURE__ */ new Set();
+	const literalTokenSet = /* @__PURE__ */ new Set();
 	const result = new Set(["export type Tokens = {"]);
 	if (tokens.isEmpty) result.add("[token: string]: string");
 	else {
@@ -2470,6 +2511,14 @@ function generateTokenTypes(ctx) {
 			tokenSet.add(`${key}.$\{${categoryName}}`);
 			result.add(`\t\t${key}: ${categoryName}`);
 		}
+		for (const token of tokens.allTokens) {
+			const { category, prop } = token.extensions;
+			if (!category || prop == null) continue;
+			const resolved = tokens.view.get(token.name);
+			if (resolved === void 0) continue;
+			if (typeof resolved === "string" && COMPUTED_BY_CSS.test(resolved)) continue;
+			literalTokenSet.add(`${category}.${prop}`);
+		}
 	}
 	result.add("} & { [token: string]: never }");
 	set.add(Array.from(result).join("\n"));
@@ -2478,7 +2527,7 @@ function generateTokenTypes(ctx) {
 	arr.unshift(`export type Token = ${(0, _bamboocss_shared.unionType)(tokenSet, {
 		stringify: (t) => `\`${t}\``,
 		fallback: "string"
-	})}`);
+	})}`, `export type LiteralToken = ${(0, _bamboocss_shared.unionType)(literalTokenSet, { fallback: tokenSet.size ? "never" : "string" })}`);
 	return outdent.outdent.string(arr.join("\n\n"));
 }
 //#endregion
@@ -3596,13 +3645,26 @@ const CATEGORY_PROPERTY_MAP = {
 const getCategoryProperty = (category) => {
 	return category ? CATEGORY_PROPERTY_MAP[category] ?? "color" : "color";
 };
-const generateTokenExamples = (token) => {
+/**
+* Whether `token.value()` would answer with an actual literal.
+*
+* Takes the *resolved* value rather than the token, because the token alone cannot answer.
+* A semantic token appears once per condition under one name, and `view.get` is last-write —
+* so `colors.button.thick` carries `value: '#fff'` on its base variant while the view returns
+* `var(--colors-button-thick)`, because a `_dark` sibling wrote after it. Asking the token's
+* own fields said "literal" and the `.d.ts` said otherwise; only the view knows.
+*/
+const hasLiteralValue = (resolved) => {
+	if (resolved === void 0) return false;
+	return typeof resolved !== "string" || !COMPUTED_BY_CSS.test(resolved);
+};
+const generateTokenExamples = (token, resolved) => {
 	const prop = getCategoryProperty(token.extensions?.category);
 	const tokenName = token.extensions.prop;
-	const fullTokenName = token.name;
+	const fullTokenName = token.extensions.category ? `${token.extensions.category}.${tokenName}` : token.name;
 	const functionExamples = [`css({ ${prop}: '${tokenName}' })`];
 	const tokenFunctionExamples = [`token('${fullTokenName}')`];
-	if (token.extensions.varRef) tokenFunctionExamples.push(`token.var('${fullTokenName}')`);
+	if (hasLiteralValue(resolved)) tokenFunctionExamples.push(`token.value('${fullTokenName}')`);
 	return {
 		functionExamples,
 		tokenFunctionExamples
@@ -3623,7 +3685,7 @@ const generateThemeTokenGroups = (ctx, themeName, filterFn) => {
 	return Array.from(byCategory.entries()).map(([category, typeTokens]) => {
 		if (!typeTokens.length) return null;
 		const firstToken = typeTokens[0];
-		const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+		const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 		return {
 			type: category,
 			values: typeTokens.map((token) => {
@@ -3670,7 +3732,7 @@ const generateTokensSpec = (ctx) => {
 			const typeTokens = Array.from(tokenMap.values()).filter((token) => !token.extensions.isSemantic && !token.extensions.isVirtual && !token.extensions.conditions && !token.extensions.isNegative);
 			if (!typeTokens.length) return null;
 			const firstToken = typeTokens[0];
-			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 			return {
 				type: category,
 				values: typeTokens.map((token) => ({
@@ -3693,7 +3755,7 @@ const generateSemanticTokensSpec = (ctx) => {
 			const typeTokens = Array.from(tokenMap.values()).filter((token) => (token.extensions.isSemantic || token.extensions.conditions) && !token.extensions.isVirtual);
 			if (!typeTokens.length) return null;
 			const firstToken = typeTokens[0];
-			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 			return {
 				type: category,
 				values: typeTokens.map((token) => {
@@ -3872,30 +3934,36 @@ var Generator = class extends _bamboocss_core.Context {
 		return names;
 	};
 	/**
-	* Tokens whose javascript value is a `var()` reference rather than a literal.
-	* `token('colors.text')` hands those to the caller as a reference, so the declaration
-	* has to survive whether or not the generated css mentions it. Ordinary tokens resolve
-	* to a literal in javascript and need no such exemption.
+	* The token declarations held open so a runtime `token()` can answer for any path.
+	*
+	* `token()` hands javascript the *variable reference* for every token, so a path the build
+	* cannot resolve could name any of them and every declaration has to survive. That is a
+	* blunt instrument, and deliberately so: the alternative failure is a `var()` with no
+	* declaration behind it, which resolves to the guaranteed-invalid value and inherits
+	* rather than falling back — silently wrong, which is worse than visibly large.
 	*
-	* The two cases mirror `generateTokenJs`, which is what decides the value javascript
-	* actually receives:
+	* It used to be narrower, because `token()` used to return a *literal* for a plain token
+	* and only a `var()` for virtual, conditional and negative ones. That split is gone, and
+	* narrowing this to match it would now strand exactly the base tokens the old split made
+	* safe.
 	*
-	* - A virtual token, or one carrying a condition, is handed its own `varRef`.
-	* - A negative token is handed `calc(var(--x) * -1)`, so it is a reference too — but to
-	*   the *positive* token's declaration. Its own var is never declared, so the name has
-	*   to come out of the value.
+	* So the gate below carries the whole saving. `styled-system/tokens` is generated into the
+	* project, so nothing outside it can import them -- if no file under `include` reaches for
+	* a token from javascript, no caller exists to serve and the declarations are as prunable
+	* as any other.
+	*
+	* That gate is all-or-nothing per project, which is the coarse part worth fixing next: a
+	* project whose token calls all resolve to string literals needs none of this, because
+	* `collectTokenReferences` already kept those paths by name. Deciding that needs the
+	* reference accounting the gate does not do yet -- see `tokensReachableFromJs`.
 	*/
 	getAlwaysKeptTokenVars = (tokensReachableFromJs) => {
 		const names = /* @__PURE__ */ new Set();
 		if (!tokensReachableFromJs) return names;
 		this.tokens.allTokens.forEach((token) => {
-			const { isVirtual, isNegative, condition, var: varName } = token.extensions;
-			if (isVirtual || condition !== "base") {
-				if (varName) names.add(varName.startsWith("--") ? varName : `--${varName}`);
-				return;
-			}
-			if (!isNegative) return;
-			for (const name of (0, _bamboocss_shared.cssVarRefs)(token.value)) names.add(name);
+			const { var: varName } = token.extensions;
+			if (varName) names.add(varName.startsWith("--") ? varName : `--${varName}`);
+			if (typeof token.value === "string") for (const name of (0, _bamboocss_shared.cssVarRefs)(token.value)) names.add(name);
 		});
 		return names;
 	};

package/dist/index.d.cts

@@ -93,18 +93,28 @@ declare class Generator extends Context {
    */
   private getThemeTokenVars;
   /**
-   * Tokens whose javascript value is a `var()` reference rather than a literal.
-   * `token('colors.text')` hands those to the caller as a reference, so the declaration
-   * has to survive whether or not the generated css mentions it. Ordinary tokens resolve
-   * to a literal in javascript and need no such exemption.
+   * The token declarations held open so a runtime `token()` can answer for any path.
    *
-   * The two cases mirror `generateTokenJs`, which is what decides the value javascript
-   * actually receives:
+   * `token()` hands javascript the *variable reference* for every token, so a path the build
+   * cannot resolve could name any of them and every declaration has to survive. That is a
+   * blunt instrument, and deliberately so: the alternative failure is a `var()` with no
+   * declaration behind it, which resolves to the guaranteed-invalid value and inherits
+   * rather than falling back — silently wrong, which is worse than visibly large.
    *
-   * - A virtual token, or one carrying a condition, is handed its own `varRef`.
-   * - A negative token is handed `calc(var(--x) * -1)`, so it is a reference too — but to
-   *   the *positive* token's declaration. Its own var is never declared, so the name has
-   *   to come out of the value.
+   * It used to be narrower, because `token()` used to return a *literal* for a plain token
+   * and only a `var()` for virtual, conditional and negative ones. That split is gone, and
+   * narrowing this to match it would now strand exactly the base tokens the old split made
+   * safe.
+   *
+   * So the gate below carries the whole saving. `styled-system/tokens` is generated into the
+   * project, so nothing outside it can import them -- if no file under `include` reaches for
+   * a token from javascript, no caller exists to serve and the declarations are as prunable
+   * as any other.
+   *
+   * That gate is all-or-nothing per project, which is the coarse part worth fixing next: a
+   * project whose token calls all resolve to string literals needs none of this, because
+   * `collectTokenReferences` already kept those paths by name. Deciding that needs the
+   * reference accounting the gate does not do yet -- see `tokensReachableFromJs`.
    */
   private getAlwaysKeptTokenVars;
   getParserCss: (decoder: StyleDecoder) => string;

package/dist/index.d.mts

@@ -93,18 +93,28 @@ declare class Generator extends Context {
    */
   private getThemeTokenVars;
   /**
-   * Tokens whose javascript value is a `var()` reference rather than a literal.
-   * `token('colors.text')` hands those to the caller as a reference, so the declaration
-   * has to survive whether or not the generated css mentions it. Ordinary tokens resolve
-   * to a literal in javascript and need no such exemption.
+   * The token declarations held open so a runtime `token()` can answer for any path.
    *
-   * The two cases mirror `generateTokenJs`, which is what decides the value javascript
-   * actually receives:
+   * `token()` hands javascript the *variable reference* for every token, so a path the build
+   * cannot resolve could name any of them and every declaration has to survive. That is a
+   * blunt instrument, and deliberately so: the alternative failure is a `var()` with no
+   * declaration behind it, which resolves to the guaranteed-invalid value and inherits
+   * rather than falling back — silently wrong, which is worse than visibly large.
    *
-   * - A virtual token, or one carrying a condition, is handed its own `varRef`.
-   * - A negative token is handed `calc(var(--x) * -1)`, so it is a reference too — but to
-   *   the *positive* token's declaration. Its own var is never declared, so the name has
-   *   to come out of the value.
+   * It used to be narrower, because `token()` used to return a *literal* for a plain token
+   * and only a `var()` for virtual, conditional and negative ones. That split is gone, and
+   * narrowing this to match it would now strand exactly the base tokens the old split made
+   * safe.
+   *
+   * So the gate below carries the whole saving. `styled-system/tokens` is generated into the
+   * project, so nothing outside it can import them -- if no file under `include` reaches for
+   * a token from javascript, no caller exists to serve and the declarations are as prunable
+   * as any other.
+   *
+   * That gate is all-or-nothing per project, which is the coarse part worth fixing next: a
+   * project whose token calls all resolve to string literals needs none of this, because
+   * `collectTokenReferences` already kept those paths by name. Deciding that needs the
+   * reference accounting the gate does not do yet -- see `tokensReachableFromJs`.
    */
   private getAlwaysKeptTokenVars;
   getParserCss: (decoder: StyleDecoder) => string;

package/dist/index.mjs

@@ -1347,15 +1347,35 @@ function generateSvaFn(ctx) {
 }
 //#endregion
 //#region src/artifacts/js/token.ts
+/**
+* `token()` hands back the variable reference for every token, and `token.value()` the
+* resolved literal.
+*
+* It used to be the other way round, decided per token: a base token resolved to its literal
+* and a virtual or conditional one to its `var()`. That made the return kind a property of
+* the *theme* rather than of the call, so adding `_dark` to a token silently changed what
+* every caller received — same call, same path, a colour before and a variable after, with
+* both typed `string` and nothing to catch it.
+*
+* Always-a-reference is the predictable half and the one that keeps working when a theme
+* switches, so it takes the short name. The literal is still reachable, but has to be asked
+* for — which is also the honest signal, since it is the form that stops responding to
+* conditions.
+*
+* `value` keeps the old per-token split rather than becoming `token.value` for everything:
+* a virtual or conditional token has no single literal to hand back, so its `var()` is still
+* the only truthful answer.
+*/
 function generateTokenJs(ctx) {
 	const { tokens } = ctx;
 	const map = /* @__PURE__ */ new Map();
 	tokens.allTokens.forEach((token) => {
 		const { varRef, isVirtual } = token.extensions;
-		const value = isVirtual || token.extensions.condition !== "base" ? varRef : token.value;
+		const variable = tokens.view.getVar(token.name) ?? varRef;
+		const value = tokens.view.get(token.name) ?? (isVirtual || token.extensions.condition !== "base" ? varRef : token.value);
 		map.set(token.name, {
 			value,
-			variable: varRef
+			variable
 		});
 	});
 	const obj = Object.fromEntries(map);
@@ -1363,22 +1383,40 @@ function generateTokenJs(ctx) {
 		js: outdent$1`
   const tokens = ${JSON.stringify(obj, null, 2)}
 
-  export function token(path, fallback) {
-    return tokens[path]?.value || fallback
+  // No fallback parameter: \`token(path) ?? fallback\` says the same thing in the language, and
+  // the parameter had to be proved side-effect-free before a build could fold the call away.
+  export function token(path) {
+    return tokens[path]?.variable
   }
 
-  function tokenVar(path, fallback) {
-    return tokens[path]?.variable || fallback
+  function tokenValue(path) {
+    return tokens[path]?.value
   }
 
-  token.var = tokenVar
+  token.value = tokenValue
   `,
 		dts: outdent$1`
-  ${ctx.file.importType("Token", "./tokens")}
+  ${ctx.file.importType("Token, LiteralToken", "./tokens")}
 
   export declare const token: {
-    (path: Token, fallback?: string): string
-    var: (path: Token, fallback?: string) => string
+    /**
+     * The css variable reference — \`var(--colors-red-300)\`. Stays correct across themes.
+     *
+     * The parameter is the closed set of tokens the theme declares, so this always answers.
+     * A path cast past that type does not, which is the usual bargain for a cast.
+     */
+    (path: Token): string
+    /**
+     * The resolved literal — \`#fca5a5\`. Use where css variables cannot be resolved, such as
+     * a canvas fill or a charting library.
+     *
+     * Restricted to the tokens that have one. A virtual or conditional token resolves to its
+     * \`var()\` because there is no single value to hand back, and a negative token to
+     * \`calc(var(--spacing-4) * -1)\` because it has no declaration of its own — so asking for
+     * a literal that cannot exist is a type error rather than a reference the caller then
+     * hands to a canvas.
+     */
+    value: (path: LiteralToken) => string
   }
 
   ${ctx.file.exportTypeStar("./tokens")}
@@ -2404,6 +2442,8 @@ const restrict = (key, value, config) => {
 };
 //#endregion
 //#region src/artifacts/types/token-types.ts
+/** A css function whose result only the browser can produce, so it is never a literal. */
+const COMPUTED_BY_CSS = /\b(?:var|env|attr)\s*\(/i;
 const categories = [
 	"aspectRatios",
 	"zIndex",
@@ -2433,6 +2473,7 @@ function generateTokenTypes(ctx) {
 	const { tokens } = ctx;
 	const set = /* @__PURE__ */ new Set();
 	const tokenSet = /* @__PURE__ */ new Set();
+	const literalTokenSet = /* @__PURE__ */ new Set();
 	const result = new Set(["export type Tokens = {"]);
 	if (tokens.isEmpty) result.add("[token: string]: string");
 	else {
@@ -2444,6 +2485,14 @@ function generateTokenTypes(ctx) {
 			tokenSet.add(`${key}.$\{${categoryName}}`);
 			result.add(`\t\t${key}: ${categoryName}`);
 		}
+		for (const token of tokens.allTokens) {
+			const { category, prop } = token.extensions;
+			if (!category || prop == null) continue;
+			const resolved = tokens.view.get(token.name);
+			if (resolved === void 0) continue;
+			if (typeof resolved === "string" && COMPUTED_BY_CSS.test(resolved)) continue;
+			literalTokenSet.add(`${category}.${prop}`);
+		}
 	}
 	result.add("} & { [token: string]: never }");
 	set.add(Array.from(result).join("\n"));
@@ -2452,7 +2501,7 @@ function generateTokenTypes(ctx) {
 	arr.unshift(`export type Token = ${unionType(tokenSet, {
 		stringify: (t) => `\`${t}\``,
 		fallback: "string"
-	})}`);
+	})}`, `export type LiteralToken = ${unionType(literalTokenSet, { fallback: tokenSet.size ? "never" : "string" })}`);
 	return outdent.string(arr.join("\n\n"));
 }
 //#endregion
@@ -3570,13 +3619,26 @@ const CATEGORY_PROPERTY_MAP = {
 const getCategoryProperty = (category) => {
 	return category ? CATEGORY_PROPERTY_MAP[category] ?? "color" : "color";
 };
-const generateTokenExamples = (token) => {
+/**
+* Whether `token.value()` would answer with an actual literal.
+*
+* Takes the *resolved* value rather than the token, because the token alone cannot answer.
+* A semantic token appears once per condition under one name, and `view.get` is last-write —
+* so `colors.button.thick` carries `value: '#fff'` on its base variant while the view returns
+* `var(--colors-button-thick)`, because a `_dark` sibling wrote after it. Asking the token's
+* own fields said "literal" and the `.d.ts` said otherwise; only the view knows.
+*/
+const hasLiteralValue = (resolved) => {
+	if (resolved === void 0) return false;
+	return typeof resolved !== "string" || !COMPUTED_BY_CSS.test(resolved);
+};
+const generateTokenExamples = (token, resolved) => {
 	const prop = getCategoryProperty(token.extensions?.category);
 	const tokenName = token.extensions.prop;
-	const fullTokenName = token.name;
+	const fullTokenName = token.extensions.category ? `${token.extensions.category}.${tokenName}` : token.name;
 	const functionExamples = [`css({ ${prop}: '${tokenName}' })`];
 	const tokenFunctionExamples = [`token('${fullTokenName}')`];
-	if (token.extensions.varRef) tokenFunctionExamples.push(`token.var('${fullTokenName}')`);
+	if (hasLiteralValue(resolved)) tokenFunctionExamples.push(`token.value('${fullTokenName}')`);
 	return {
 		functionExamples,
 		tokenFunctionExamples
@@ -3597,7 +3659,7 @@ const generateThemeTokenGroups = (ctx, themeName, filterFn) => {
 	return Array.from(byCategory.entries()).map(([category, typeTokens]) => {
 		if (!typeTokens.length) return null;
 		const firstToken = typeTokens[0];
-		const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+		const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 		return {
 			type: category,
 			values: typeTokens.map((token) => {
@@ -3644,7 +3706,7 @@ const generateTokensSpec = (ctx) => {
 			const typeTokens = Array.from(tokenMap.values()).filter((token) => !token.extensions.isSemantic && !token.extensions.isVirtual && !token.extensions.conditions && !token.extensions.isNegative);
 			if (!typeTokens.length) return null;
 			const firstToken = typeTokens[0];
-			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 			return {
 				type: category,
 				values: typeTokens.map((token) => ({
@@ -3667,7 +3729,7 @@ const generateSemanticTokensSpec = (ctx) => {
 			const typeTokens = Array.from(tokenMap.values()).filter((token) => (token.extensions.isSemantic || token.extensions.conditions) && !token.extensions.isVirtual);
 			if (!typeTokens.length) return null;
 			const firstToken = typeTokens[0];
-			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken);
+			const { functionExamples, tokenFunctionExamples } = generateTokenExamples(firstToken, ctx.tokens.view.get(firstToken.name));
 			return {
 				type: category,
 				values: typeTokens.map((token) => {
@@ -3846,30 +3908,36 @@ var Generator = class extends Context {
 		return names;
 	};
 	/**
-	* Tokens whose javascript value is a `var()` reference rather than a literal.
-	* `token('colors.text')` hands those to the caller as a reference, so the declaration
-	* has to survive whether or not the generated css mentions it. Ordinary tokens resolve
-	* to a literal in javascript and need no such exemption.
+	* The token declarations held open so a runtime `token()` can answer for any path.
+	*
+	* `token()` hands javascript the *variable reference* for every token, so a path the build
+	* cannot resolve could name any of them and every declaration has to survive. That is a
+	* blunt instrument, and deliberately so: the alternative failure is a `var()` with no
+	* declaration behind it, which resolves to the guaranteed-invalid value and inherits
+	* rather than falling back — silently wrong, which is worse than visibly large.
 	*
-	* The two cases mirror `generateTokenJs`, which is what decides the value javascript
-	* actually receives:
+	* It used to be narrower, because `token()` used to return a *literal* for a plain token
+	* and only a `var()` for virtual, conditional and negative ones. That split is gone, and
+	* narrowing this to match it would now strand exactly the base tokens the old split made
+	* safe.
 	*
-	* - A virtual token, or one carrying a condition, is handed its own `varRef`.
-	* - A negative token is handed `calc(var(--x) * -1)`, so it is a reference too — but to
-	*   the *positive* token's declaration. Its own var is never declared, so the name has
-	*   to come out of the value.
+	* So the gate below carries the whole saving. `styled-system/tokens` is generated into the
+	* project, so nothing outside it can import them -- if no file under `include` reaches for
+	* a token from javascript, no caller exists to serve and the declarations are as prunable
+	* as any other.
+	*
+	* That gate is all-or-nothing per project, which is the coarse part worth fixing next: a
+	* project whose token calls all resolve to string literals needs none of this, because
+	* `collectTokenReferences` already kept those paths by name. Deciding that needs the
+	* reference accounting the gate does not do yet -- see `tokensReachableFromJs`.
 	*/
 	getAlwaysKeptTokenVars = (tokensReachableFromJs) => {
 		const names = /* @__PURE__ */ new Set();
 		if (!tokensReachableFromJs) return names;
 		this.tokens.allTokens.forEach((token) => {
-			const { isVirtual, isNegative, condition, var: varName } = token.extensions;
-			if (isVirtual || condition !== "base") {
-				if (varName) names.add(varName.startsWith("--") ? varName : `--${varName}`);
-				return;
-			}
-			if (!isNegative) return;
-			for (const name of cssVarRefs(token.value)) names.add(name);
+			const { var: varName } = token.extensions;
+			if (varName) names.add(varName.startsWith("--") ? varName : `--${varName}`);
+			if (typeof token.value === "string") for (const name of cssVarRefs(token.value)) names.add(name);
 		});
 		return names;
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/generator",
-  "version": "1.28.1",
+  "version": "1.30.0",
   "description": "The css generator for css bamboo",
   "homepage": "https://bamboocss.com",
   "license": "MIT",
@@ -38,12 +38,12 @@
     "pluralize": "8.0.0",
     "postcss": "8.5.26",
     "ts-pattern": "5.9.0",
-    "@bamboocss/core": "1.28.1",
-    "@bamboocss/is-valid-prop": "^1.28.1",
-    "@bamboocss/logger": "1.28.1",
-    "@bamboocss/shared": "1.28.1",
-    "@bamboocss/token-dictionary": "1.28.1",
-    "@bamboocss/types": "1.28.1"
+    "@bamboocss/core": "1.30.0",
+    "@bamboocss/is-valid-prop": "^1.30.0",
+    "@bamboocss/logger": "1.30.0",
+    "@bamboocss/shared": "1.30.0",
+    "@bamboocss/token-dictionary": "1.30.0",
+    "@bamboocss/types": "1.30.0"
   },
   "devDependencies": {
     "@types/pluralize": "0.0.33"