@yahoo/uds-create-config 4.57.2 → 5.0.0

package/dist/configs/react-native-system.d.ts

@@ -7,6 +7,7 @@ import { EntityClass } from "../framework/defineEntity.js";
 import { ConfigClass } from "../framework/defineConfig.js";
 import { Named } from "../framework/named.js";
 import { PackageClass } from "../entities/system/Package.js";
+import { CompositeClass } from "../entities/system/Composite.js";
 import { OverrideCondition } from "../entities/system/Token.js";
 import { StylePropValue } from "../entities/system/StyleProperty.js";
 import { ComponentClass } from "../entities/system/Component.js";
@@ -14,7 +15,6 @@ import { LinkedSystemClass } from "../entities/system/LinkedSystem.js";
 import { IconClass } from "../entities/system/Icon.js";
 import { NativeModifierClass } from "../entities/native/NativeModifier.js";
 import { CanvasRoleClass } from "../entities/system/CanvasRole.js";
-import { CompositeClass } from "../entities/system/Composite.js";
 import { DeviceClass } from "../entities/system/Device.js";
 import { FileClass } from "../entities/system/File.js";
 import { FontClass } from "../entities/system/Font.js";
@@ -105,14 +105,14 @@ declare const ReactNativeSystemDefinition: ConfigClass<{
     properties: _$zod.ZodArray<_$zod.ZodPipe<_$zod.ZodPipe<_$zod.ZodString, _$zod.ZodTransform<string, string>>, _$zod.ZodEnum<{
       transform: "transform";
       filter: "filter";
-      left: "left";
-      right: "right";
       color: "color";
       inset: "inset";
       position: "position";
       end: "end";
       start: "start";
       bottom: "bottom";
+      left: "left";
+      right: "right";
       top: "top";
       flex: "flex";
       cursor: "cursor";

package/dist/configs/system.d.ts

@@ -1,20 +1,20 @@
 import { ConfigClass } from "../framework/defineConfig.js";
 import { Named } from "../framework/named.js";
 import { PackageClass } from "../entities/system/Package.js";
+import { CompositeClass } from "../entities/system/Composite.js";
+import { ModifierClass } from "../entities/system/Modifier.js";
 import { TokenClass } from "../entities/system/Token.js";
 import { StylePropertyClass } from "../entities/system/StyleProperty.js";
 import { ComponentClass } from "../entities/system/Component.js";
 import { LinkedSystemClass } from "../entities/system/LinkedSystem.js";
 import { IconClass } from "../entities/system/Icon.js";
 import { CanvasRoleClass } from "../entities/system/CanvasRole.js";
-import { CompositeClass } from "../entities/system/Composite.js";
 import { DeviceClass } from "../entities/system/Device.js";
 import { FileClass } from "../entities/system/File.js";
 import { FontClass } from "../entities/system/Font.js";
 import { GlobalStyleClass } from "../entities/system/GlobalStyle.js";
 import { GuidanceClass } from "../entities/system/Guidance.js";
 import { GuidanceStyleClass } from "../entities/system/GuidanceStyle.js";
-import { ModifierClass } from "../entities/system/Modifier.js";
 import { MotionClass } from "../entities/system/Motion.js";
 import { OperationClass } from "../entities/system/Operation.js";
 import { SettingsClass } from "../entities/system/Settings.js";

package/dist/configs/system.js

@@ -54,6 +54,8 @@ import { styleRulesAsListMigration } from "../migrations/20261001112308_style_ru
 import { motionExitAndElementDuplicateMigration } from "../migrations/20261001130958_motion_exit_and_element_duplicate.js";
 import { layerStyleAndForwardOpsMigration } from "../migrations/20261001131000_layer_style_and_forward_ops.js";
 import { oklchAndEmitFieldsMigration } from "../migrations/20261001162046_oklch_and_emit_fields.js";
+import { globalStyleOnMigration } from "../migrations/20261005212405_global_style_on.js";
+import { addAndSubtractMigration } from "../migrations/20261005220312_add_and_subtract.js";
 const System = defineConfig({
 	name: WEB_CONFIG_NAME,
 	description: "A design system: the values, primitives and compositions an app is built from. A ref is written `{ \"__ref\": \"<kind>:<path>\" }`, so a token is `{ \"__ref\": \"token:<group>/<name>\" }` and a token group is `{ \"__ref\": \"token:<group>\" }`. Build it in this order. Tokens first, in groups by purpose (colors, spacing, radii, type sizes), since everything else names them. Then style properties, each with `values` holding one ref to the token group whose members it accepts (`{ \"__ref\": \"token:color\" }`), so a prop takes token names rather than raw CSS; add a string keyword only for a value no token holds. A style rule's bag holds a prop's values (`\"padding\": \"4\"`, `\"bg\": \"brand\"`), never raw CSS. Then a few primitive components, one layer each, whose props are style properties (a box for layout and surface, a text for type, a pressable for interaction). Then every other component composed from those primitives: its layers name a primitive or an element, its anatomy places them (a node renders a layer, a tag or `Slot` where a slot prop's content lands; `children` is the edge list; `visible` is `{ \"$state\": \"<prop>\" }`; a prop shown in a nested layer is a `forward` route, and `$state` never sits in a node's props), and its style rules set style-property values per layer, keyed by prop values when a variant changes them. Modes (a dark mode is `{ type: \"selector\", value: \".dark\" }`) change token values through a token's `overrides`, so a component never restyles for a mode; modifiers (hover, focus, disabled) name a state, and a style rule applies under one as a `_hover` block inside a layer bag. Composites bundle style values that recur. Last, register canvas roles: the canvas draws with them, one entity per tool (`frame` for the layout primitive, `text` for the text primitive, `image`) whose entries name the components that tool inserts, and a tool whose role is unregistered is disabled. Give each component a `preview` entry under `*` so it shows content, and never write a CSS property name where a style-property name belongs.",
@@ -119,5 +121,7 @@ if (!registeredSchemaMigrations().has(20261001112308)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261001130958)) registerSchemaMigrations(motionExitAndElementDuplicateMigration);
 if (!registeredSchemaMigrations().has(20261001131e3)) registerSchemaMigrations(layerStyleAndForwardOpsMigration);
 if (!registeredSchemaMigrations().has(20261001162046)) registerSchemaMigrations(oklchAndEmitFieldsMigration);
+if (!registeredSchemaMigrations().has(20261005212405)) registerSchemaMigrations(globalStyleOnMigration);
+if (!registeredSchemaMigrations().has(20261005220312)) registerSchemaMigrations(addAndSubtractMigration);
 //#endregion
 export { System };

package/dist/css/value-type.js

@@ -1,4 +1,4 @@
-import { evaluateCalc, isDivide, isMultiply } from "../entities/system/calc.js";
+import { evaluateCalc, isCalc } from "../entities/system/calc.js";
 import { composedValueFormOf } from "../entities/system/composed-values.js";
 //#region src/css/value-type.ts
 /**
@@ -89,7 +89,7 @@ function startsWithAny(value, heads) {
 function sniffValueType(value) {
 	const formType = composedValueFormOf(value)?.valueType;
 	if (formType) return formType;
-	if (isMultiply(value) || isDivide(value)) {
+	if (isCalc(value)) {
 		const literal = evaluateCalc(value, (part) => typeof part === "object" ? void 0 : part);
 		return literal === void 0 ? void 0 : sniffValueType(String(literal));
 	}

package/dist/entities/native/NativeStyleProperty.d.ts

@@ -8,14 +8,14 @@ import { z } from "zod";
 declare const rnStyleKey: z.ZodEnum<{
   transform: "transform";
   filter: "filter";
-  left: "left";
-  right: "right";
   color: "color";
   inset: "inset";
   position: "position";
   end: "end";
   start: "start";
   bottom: "bottom";
+  left: "left";
+  right: "right";
   top: "top";
   flex: "flex";
   cursor: "cursor";
@@ -180,14 +180,14 @@ declare const NativeStyleProperty: EntityClass<z.ZodObject<Omit<{
   properties: z.ZodArray<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodEnum<{
     transform: "transform";
     filter: "filter";
-    left: "left";
-    right: "right";
     color: "color";
     inset: "inset";
     position: "position";
     end: "end";
     start: "start";
     bottom: "bottom";
+    left: "left";
+    right: "right";
     top: "top";
     flex: "flex";
     cursor: "cursor";

package/dist/entities/system/GlobalStyle.d.ts

@@ -1,6 +1,7 @@
 import { DerivedColor, OklchColor } from "./color.js";
 import { EntityClass } from "../../framework/defineEntity.js";
 import { Named } from "../../framework/named.js";
+import { ModifierClass } from "./Modifier.js";
 import { z } from "zod";
 
 //#region src/entities/system/GlobalStyle.d.ts
@@ -17,6 +18,7 @@ declare const GlobalStyleDefinition: EntityClass<z.ZodObject<{
   selector: z.ZodString;
   declarations: z.ZodRecord<z.ZodString, z.ZodType<Declared, unknown, z.core.$ZodTypeInternals<Declared, unknown>>>;
   important: z.ZodOptional<z.ZodBoolean>;
+  on: z.ZodOptional<z.ZodUnion<readonly [ModifierClass, z.ZodArray<ModifierClass>]>>;
 }, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "global-style", {}, Record<never, never>, false, Record<never, never>, Record<never, never>>;
 interface GlobalStyleClass extends Named<typeof GlobalStyleDefinition> {}
 declare const GlobalStyle: GlobalStyleClass;

package/dist/entities/system/GlobalStyle.js

@@ -1,6 +1,7 @@
 import { refSchema } from "../../framework/utils/refs.js";
 import { derivedColor, oklchColor } from "./color.js";
 import { defineEntity } from "../../framework/defineEntity.js";
+import { overrideConditionSchema } from "./Token.js";
 import { z } from "zod";
 //#region src/entities/system/GlobalStyle.ts
 /**
@@ -41,7 +42,15 @@ const GlobalStyle = defineEntity({
 		* layered and a third party's stylesheet (React Flow, CodeMirror's injected theme) is not, so a
 		* rule meant to beat one has to say so; the flag lets it while its values stay refs.
 		*/
-		important: z.boolean().optional().describe("Emit every declaration `!important`, to beat a third party's unlayered stylesheet.")
+		important: z.boolean().optional().describe("Emit every declaration `!important`, to beat a third party's unlayered stylesheet."),
+		/**
+		* The modifier the rule applies under, or several that all hold at once — the same shape as a
+		* token override's `on`. The rule is written through each modifier's own activation, as a
+		* component rule is: a state composes onto the selector, a selector mode stands before it as its
+		* ancestor (`:root` takes the mode's selector itself), and a media query wraps it. A ref, so
+		* renaming the modifier cascades into the rule instead of leaving a hand-copied `.dark` behind.
+		*/
+		on: overrideConditionSchema.optional().describe("The modifier the rule applies under, or a list that all hold at once: `{ \"__ref\": \"modifier:colorMode/dark\" }`. A state composes onto the selector, a selector mode is its ancestor (`:root` takes the mode itself), a media query wraps the rule. Rules inside `@media` or `@supports` take it too; `@keyframes` and `@font-face` are written as they are.")
 	})
 });
 /**

package/dist/entities/system/Modifier.d.ts

@@ -1,8 +1,8 @@
 import { EntityClass } from "../../framework/defineEntity.js";
 import { Named } from "../../framework/named.js";
-import { Config } from "../../framework/Config.js";
 import { CompositeClass } from "./Composite.js";
 import { modifierAxis, modifierCategory } from "./modifier-axis.js";
+import { Config } from "../../framework/Config.js";
 import { z } from "zod";
 
 //#region src/entities/system/Modifier.d.ts

package/dist/entities/system/Token.js

@@ -1,4 +1,4 @@
-import { isRef, pathOf, ref, sourceOf } from "../../framework/utils/refs.js";
+import { isRef, pathOf, ref, refKey, sourceOf } from "../../framework/utils/refs.js";
 import { composedValueSchemas } from "./composed-values.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { defineSubEntity } from "../../framework/defineSubEntity.js";
@@ -6,7 +6,7 @@ import { Font } from "./Font.js";
 import { Modifier } from "./Modifier.js";
 import { WEB_CONFIG_NAME } from "../../configs/platform.js";
 import { authoringPhantom } from "../../framework/utils/authoring-phantom.js";
-import { TOKEN_READERS, spellTokenRead } from "./token-values.js";
+import { spellTokenRead } from "./token-values.js";
 import { prepareLinkedTokenBody } from "./linked-token-values.js";
 import { z } from "zod";
 //#region src/entities/system/Token.ts
@@ -156,16 +156,29 @@ const TokenEntity = defineEntity({
 const baseTokenRef = TokenEntity.ref.bind(TokenEntity);
 function tokenRef(path) {
 	const value = baseTokenRef(path);
-	for (const reader of TOKEN_READERS) Object.defineProperty(value, reader, {
+	const phantom = (reader) => () => authoringPhantom({ spelled: spellTokenRead({
+		path,
+		reader
+	}) });
+	for (const reader of [
+		"value",
+		"px",
+		"ms"
+	]) Object.defineProperty(value, reader, {
+		enumerable: false,
+		configurable: false,
+		value: phantom(reader)
+	});
+	Object.defineProperty(value, "cssVariable", {
 		enumerable: false,
 		configurable: false,
-		value: () => authoringPhantom({ spelled: spellTokenRead({
-			path,
-			reader
-		}) })
+		value: Object.freeze({
+			name: () => refKey(value.__ref),
+			var: phantom("cssVariable.var")
+		})
 	});
 	return value;
 }
 const Token = Object.assign(TokenEntity, { ref: tokenRef });
 //#endregion
-export { Token, defineOverride, overrideCondition, overrideKey, overrideKeyModifiers, overrideModifiers };
+export { Token, defineOverride, overrideCondition, overrideConditionSchema, overrideKey, overrideKeyModifiers, overrideModifiers };

package/dist/entities/system/calc.d.ts

@@ -2,27 +2,61 @@ import { Ref } from "../../framework/utils/refs.js";
 import { z } from "zod";
 
 //#region src/entities/system/calc.d.ts
-/** One side of the arithmetic: a number, a CSS length such as `0.25rem`, or a ref to a token. */
-type CalcOperand = number | string | Ref;
+/**
+ * One term of the arithmetic: a number, a CSS length such as `0.25rem`, a ref to a token, or more
+ * arithmetic — `add(Token.ref('gap'), multiply(Token.ref('spacing'), 2))`.
+ */
+type CalcOperand = number | string | Ref | Calc;
 interface Multiply {
   readonly multiply: readonly [CalcOperand, CalcOperand];
 }
 interface Divide {
   readonly divide: readonly [CalcOperand, CalcOperand];
 }
+/** The terms summed, in order: `calc(a + b + c)`. */
+interface Add {
+  readonly add: readonly CalcOperand[];
+}
+/** The first term less each of the rest, in order: `calc(a - b - c)`. */
+interface Subtract {
+  readonly subtract: readonly CalcOperand[];
+}
+/** Any arithmetic on values. */
+type Calc = Multiply | Divide | Add | Subtract;
 /** Whether a value is a `multiply(…)`. */
 declare function isMultiply(value: unknown): value is Multiply;
 /** Whether a value is a `divide(…)`. */
 declare function isDivide(value: unknown): value is Divide;
+/** Whether a value is an `add(…)`. */
+declare function isAdd(value: unknown): value is Add;
+/** Whether a value is a `subtract(…)`. */
+declare function isSubtract(value: unknown): value is Subtract;
+/** Whether a value is arithmetic of any kind. */
+declare function isCalc(value: unknown): value is Calc;
+/** The CSS operator an arithmetic value applies between its terms. */
+declare function calcOperator(value: Calc): '*' | '/' | '+' | '-';
+/** An arithmetic value's terms, in order. */
+declare function calcOperands(value: Calc): readonly CalcOperand[];
 /** `multiply(Token.ref('spacing'), 4)` — the first operand times the second. */
 declare function multiply(left: CalcOperand, right: CalcOperand): Multiply;
 /** `divide(1.25, 0.875)` — the first operand over the second. */
 declare function divide(left: CalcOperand, right: CalcOperand): Divide;
+/** `add(Token.ref('gap'), Token.ref('spacing'))` — every term summed, two or more. */
+declare function add(first: CalcOperand, second: CalcOperand, ...rest: CalcOperand[]): Add;
+/** `subtract(Token.ref('track'), Token.ref('handle'))` — the first term less each of the rest. */
+declare function subtract(first: CalcOperand, second: CalcOperand, ...rest: CalcOperand[]): Subtract;
 /**
  * What the arithmetic comes to, given each operand's literal — `1rem` for `0.25rem` times 4,
- * `1.4286` for `1.25` over `0.875` — or `undefined` when the operands are not plain quantities or
- * their units don't combine. `literal` resolves an operand (a ref to the token's value).
+ * `1.4286` for `1.25` over `0.875`, `1.5rem` for `1rem` plus `0.5rem` — or `undefined` when the
+ * operands are not plain quantities or their units don't combine. `literal` resolves an operand (a
+ * ref to the token's value); a term that is arithmetic itself is worked out first, with the same
+ * `literal`.
+ *
+ * A sum or a difference takes terms of one unit, since that is the only case that comes to one
+ * quantity here: `1rem + 4px` is real CSS the browser works out, and has no literal of its own.
+ * A plain number and a length don't add, in CSS or here: `calc(0 + 4px)` is invalid, so a zero
+ * term needs its unit (`'0px'`).
  */
-declare function evaluateCalc(value: Multiply | Divide, literal: (part: CalcOperand) => string | number | undefined): string | number | undefined;
+declare function evaluateCalc(value: Calc, literal: (part: Exclude<CalcOperand, Calc>) => string | number | undefined): string | number | undefined;
 //#endregion
-export { CalcOperand, Divide, Multiply, divide, evaluateCalc, isDivide, isMultiply, multiply };
+export { Add, Calc, CalcOperand, Divide, Multiply, Subtract, add, calcOperands, calcOperator, divide, evaluateCalc, isAdd, isCalc, isDivide, isMultiply, isSubtract, multiply, subtract };

package/dist/entities/system/calc.js

@@ -3,28 +3,65 @@ import { z } from "zod";
 //#region src/entities/system/calc.ts
 /**
 * A value that is arithmetic on others — `multiply(Token.ref('spacing'), 4)` is
-* `calc(var(--spacing) * 4)`, and `divide(1.25, 0.875)` is `calc(1.25 / 0.875)`.
+* `calc(var(--spacing) * 4)`, `divide(1.25, 0.875)` is `calc(1.25 / 0.875)`, and
+* `add(Token.ref('gap'), Token.ref('spacing'))` is `calc(var(--gap) + var(--spacing))`.
 *
 * Held as its operands rather than as the `calc()` string so a ref in it stays a ref: a rename
 * follows into it, the dependency graph sees it, and a reader can work out what it comes to
 * (`spacing` at `0.25rem` times 4 is `1rem`) where a string would only be text.
 */
-const operand = z.union([
+const operand = z.lazy(() => z.union([
 	z.number(),
 	z.string().min(1),
-	refSchema
-]);
+	refSchema,
+	multiplyValue,
+	divideValue,
+	addValue,
+	subtractValue
+]));
 const operands = z.tuple([operand, operand]);
+/** A sum or a difference takes two terms or more, so `add(a, b, c)` needs no nesting. */
+const terms = z.array(operand).min(2);
 const multiplyValue = z.strictObject({ multiply: operands });
 const divideValue = z.strictObject({ divide: operands });
+const addValue = z.strictObject({ add: terms });
+const subtractValue = z.strictObject({ subtract: terms });
 const isPair = (value) => Array.isArray(value) && value.length === 2;
+const isTerms = (value) => Array.isArray(value) && value.length >= 2;
+const isObject = (value) => typeof value === "object" && value !== null;
 /** Whether a value is a `multiply(…)`. */
 function isMultiply(value) {
-	return typeof value === "object" && value !== null && isPair(value.multiply);
+	return isObject(value) && isPair(value.multiply);
 }
 /** Whether a value is a `divide(…)`. */
 function isDivide(value) {
-	return typeof value === "object" && value !== null && isPair(value.divide);
+	return isObject(value) && isPair(value.divide);
+}
+/** Whether a value is an `add(…)`. */
+function isAdd(value) {
+	return isObject(value) && isTerms(value.add);
+}
+/** Whether a value is a `subtract(…)`. */
+function isSubtract(value) {
+	return isObject(value) && isTerms(value.subtract);
+}
+/** Whether a value is arithmetic of any kind. */
+function isCalc(value) {
+	return isMultiply(value) || isDivide(value) || isAdd(value) || isSubtract(value);
+}
+/** The CSS operator an arithmetic value applies between its terms. */
+function calcOperator(value) {
+	if (isMultiply(value)) return "*";
+	if (isDivide(value)) return "/";
+	if (isAdd(value)) return "+";
+	return "-";
+}
+/** An arithmetic value's terms, in order. */
+function calcOperands(value) {
+	if (isMultiply(value)) return value.multiply;
+	if (isDivide(value)) return value.divide;
+	if (isAdd(value)) return value.add;
+	return value.subtract;
 }
 /** `multiply(Token.ref('spacing'), 4)` — the first operand times the second. */
 function multiply(left, right) {
@@ -34,15 +71,33 @@ function multiply(left, right) {
 function divide(left, right) {
 	return { divide: [left, right] };
 }
-/** A `multiply(…)` as CSS — `calc(var(--spacing) * 4)` — with `render` resolving each operand. */
-function renderMultiply(value, render) {
-	const [left, right] = value.multiply;
-	return `calc(${render(left)} * ${render(right)})`;
+/** `add(Token.ref('gap'), Token.ref('spacing'))` — every term summed, two or more. */
+function add(first, second, ...rest) {
+	return { add: [
+		first,
+		second,
+		...rest
+	] };
+}
+/** `subtract(Token.ref('track'), Token.ref('handle'))` — the first term less each of the rest. */
+function subtract(first, second, ...rest) {
+	return { subtract: [
+		first,
+		second,
+		...rest
+	] };
 }
-/** A `divide(…)` as CSS — `calc(1.25 / 0.875)`. */
-function renderDivide(value, render) {
-	const [left, right] = value.divide;
-	return `calc(${render(left)} / ${render(right)})`;
+/**
+* Arithmetic as CSS — `calc(var(--spacing) * 4)`, `calc(var(--gap) + var(--spacing))` — with
+* `render` resolving each term. A term that is arithmetic itself is written as its parenthesised
+* expression rather than a second `calc()`, which says the same and reads as the formula it is:
+* `calc(var(--gap) + (var(--spacing) * 2))`. `+` and `-` are spaced, as CSS requires.
+*/
+function renderCalc(value, render) {
+	return `calc(${calcOperands(value).map((part) => {
+		const css = render(part);
+		return isCalc(part) && css.startsWith("calc(") ? css.slice(4) : css;
+	}).join(` ${calcOperator(value)} `)})`;
 }
 function multiplyAuthoring(value) {
 	return {
@@ -56,6 +111,18 @@ function divideAuthoring(value) {
 		args: [...value.divide]
 	};
 }
+function addAuthoring(value) {
+	return {
+		helper: "add",
+		args: [...value.add]
+	};
+}
+function subtractAuthoring(value) {
+	return {
+		helper: "subtract",
+		args: [...value.subtract]
+	};
+}
 const isDigit = (char) => char !== void 0 && char >= "0" && char <= "9";
 /**
 * The plain number a string starts with — an optional minus, digits, and an optional fraction
@@ -92,30 +159,54 @@ function quantityOf(value) {
 }
 /**
 * What the arithmetic comes to, given each operand's literal — `1rem` for `0.25rem` times 4,
-* `1.4286` for `1.25` over `0.875` — or `undefined` when the operands are not plain quantities or
-* their units don't combine. `literal` resolves an operand (a ref to the token's value).
+* `1.4286` for `1.25` over `0.875`, `1.5rem` for `1rem` plus `0.5rem` — or `undefined` when the
+* operands are not plain quantities or their units don't combine. `literal` resolves an operand (a
+* ref to the token's value); a term that is arithmetic itself is worked out first, with the same
+* `literal`.
+*
+* A sum or a difference takes terms of one unit, since that is the only case that comes to one
+* quantity here: `1rem + 4px` is real CSS the browser works out, and has no literal of its own.
+* A plain number and a length don't add, in CSS or here: `calc(0 + 4px)` is invalid, so a zero
+* term needs its unit (`'0px'`).
 */
 function evaluateCalc(value, literal) {
-	const [left, right] = isMultiply(value) ? value.multiply : value.divide;
-	const a = quantityOf(literal(left));
-	const b = quantityOf(literal(right));
-	if (!a || !b) return void 0;
-	let result;
-	if (isMultiply(value)) {
-		if (a.unit && b.unit) return void 0;
-		result = {
-			amount: a.amount * b.amount,
-			unit: a.unit || b.unit
-		};
-	} else {
+	const quantities = [];
+	for (const part of calcOperands(value)) {
+		const quantity = quantityOf(isCalc(part) ? evaluateCalc(part, literal) : literal(part));
+		if (!quantity) return void 0;
+		quantities.push(quantity);
+	}
+	const result = combine(value, quantities);
+	if (!result) return void 0;
+	const amount = Math.round(result.amount * 1e4) / 1e4;
+	return result.unit ? `${amount}${result.unit}` : amount;
+}
+/** The terms' quantities combined by the value's operator, or `undefined` when their units don't. */
+function combine(value, terms) {
+	if (isMultiply(value) || isDivide(value)) {
+		const [a, b] = terms;
+		if (isMultiply(value)) {
+			if (a.unit && b.unit) return void 0;
+			return {
+				amount: a.amount * b.amount,
+				unit: a.unit || b.unit
+			};
+		}
 		if (b.amount === 0 || b.unit && b.unit !== a.unit) return void 0;
-		result = {
+		return {
 			amount: a.amount / b.amount,
 			unit: b.unit ? "" : a.unit
 		};
 	}
-	const amount = Math.round(result.amount * 1e4) / 1e4;
-	return result.unit ? `${amount}${result.unit}` : amount;
+	const units = new Set(terms.map((term) => term.unit));
+	if (units.size > 1) return void 0;
+	const unit = [...units][0] ?? "";
+	const sign = isAdd(value) ? 1 : -1;
+	const [first, ...rest] = terms;
+	return {
+		amount: rest.reduce((sum, term) => sum + sign * term.amount, first.amount),
+		unit
+	};
 }
 //#endregion
-export { divide, divideAuthoring, divideValue, evaluateCalc, isDivide, isMultiply, leadingNumber, multiply, multiplyAuthoring, multiplyValue, renderDivide, renderMultiply };
+export { add, addAuthoring, addValue, calcOperands, calcOperator, divide, divideAuthoring, divideValue, evaluateCalc, isAdd, isCalc, isDivide, isMultiply, isSubtract, leadingNumber, multiply, multiplyAuthoring, multiplyValue, renderCalc, subtract, subtractAuthoring, subtractValue };

package/dist/entities/system/composed-values.d.ts

@@ -1,12 +1,12 @@
 import { ValueType } from "../../css/value-type.js";
-import { Divide, Multiply } from "./calc.js";
+import { Add, Divide, Multiply, Subtract } from "./calc.js";
 import { DerivedColor, Gradient, OklchColor } from "./color.js";
 import { Shadow } from "./shadow.js";
 import { Transition } from "./transition.js";
 import { z } from "zod";
 
 //#region src/entities/system/composed-values.d.ts
-type ComposedValue = Multiply | Divide | OklchColor | DerivedColor | Gradient | Transition | Shadow;
+type ComposedValue = Multiply | Divide | Add | Subtract | OklchColor | DerivedColor | Gradient | Transition | Shadow;
 /** How the write engine spells a stored value: the helper's name and its positional arguments. */
 interface ComposedValueAuthoring {
   readonly helper: string;

package/dist/entities/system/composed-values.js

@@ -1,11 +1,12 @@
-import { divideAuthoring, divideValue, evaluateCalc, isDivide, isMultiply, multiplyAuthoring, multiplyValue, renderDivide, renderMultiply } from "./calc.js";
+import { addAuthoring, addValue, calcOperands, divideAuthoring, divideValue, evaluateCalc, isAdd, isCalc, isDivide, isMultiply, isSubtract, multiplyAuthoring, multiplyValue, renderCalc, subtractAuthoring, subtractValue } from "./calc.js";
 import { derivedColor, derivedColorAuthoring, gradient, gradientAuthoring, isDerivedColor, isGradient, isOklchColor, oklchAuthoring, oklchColor, renderDerivedColor, renderGradient, renderOklch } from "./color.js";
 import { isShadow, renderShadow, shadowAuthoring, shadowValue } from "./shadow.js";
 import { isTransition, renderTransition, transitionAuthoring, transitionValue } from "./transition.js";
 //#region src/entities/system/composed-values.ts
-/** Arithmetic as a formula: `spacing × 4`, `1.25 ÷ 0.875`. */
-function describeCalc(operator, [left, right], describe) {
-	return `${describe(left)} ${operator} ${describe(right)}`;
+/** Arithmetic as a formula: `spacing × 4`, `1.25 ÷ 0.875`, `gap + (spacing × 2)`. A term that is
+*  arithmetic itself is parenthesised, so the formula reads the way it computes. */
+function describeCalc(operator, value, describe) {
+	return calcOperands(value).map((part) => isCalc(part) ? `(${describe(part)})` : describe(part)).join(` ${operator} `);
 }
 /** A derived colour as its op: `darken(brand, 10%)`, `mix(brand, white, 30%)`. */
 function describeDerivedColor(value, describe) {
@@ -23,19 +24,35 @@ const composedValueForms = [
 	form({
 		schema: multiplyValue,
 		is: isMultiply,
-		render: renderMultiply,
-		describe: (value, describe) => describeCalc("×", value.multiply, describe),
+		render: renderCalc,
+		describe: (value, describe) => describeCalc("×", value, describe),
 		evaluate: evaluateCalc,
 		authoring: multiplyAuthoring
 	}),
 	form({
 		schema: divideValue,
 		is: isDivide,
-		render: renderDivide,
-		describe: (value, describe) => describeCalc("÷", value.divide, describe),
+		render: renderCalc,
+		describe: (value, describe) => describeCalc("÷", value, describe),
 		evaluate: evaluateCalc,
 		authoring: divideAuthoring
 	}),
+	form({
+		schema: addValue,
+		is: isAdd,
+		render: renderCalc,
+		describe: (value, describe) => describeCalc("+", value, describe),
+		evaluate: evaluateCalc,
+		authoring: addAuthoring
+	}),
+	form({
+		schema: subtractValue,
+		is: isSubtract,
+		render: renderCalc,
+		describe: (value, describe) => describeCalc("−", value, describe),
+		evaluate: evaluateCalc,
+		authoring: subtractAuthoring
+	}),
 	form({
 		schema: oklchColor,
 		is: isOklchColor,

package/dist/entities/system/icon-library.js

@@ -1,5 +1,5 @@
 import { createSliceMemo } from "../../framework/memo.js";
-import { glyphComponentOf, glyphLibrariesOf, iconToolFor, iconToolsOf, resolveComponentProps } from "../../framework/projections.js";
+import { glyphComponentOf, glyphLibrariesOf, iconToolFor, iconToolsOf, isCustomPropertyKey, resolveComponentProps } from "../../framework/projections.js";
 import { isValueSlot } from "../../framework/prop-surface.js";
 import { Component } from "./Component.js";
 import { parseGlyphType } from "../../spec/glyph-jsx.js";
@@ -290,7 +290,7 @@ function isDeclaredElementProp(config, elementType, propName) {
 	const component = Component.get(config, elementType);
 	if (component) {
 		if (resolveComponentProps(config, component.path)[propName] !== void 0) return true;
-		if (propName.startsWith("--")) return false;
+		if (isCustomPropertyKey(propName)) return false;
 		return config.resolve("style-property", propName) === void 0;
 	}
 	const parsed = parseGlyphType(elementType);

package/dist/entities/system/linked-token-values.js

@@ -1,5 +1,5 @@
 import { hasRefMarker } from "../../framework/utils/refs.js";
-import { isDivide, isMultiply } from "./calc.js";
+import { isCalc } from "./calc.js";
 import { isOklchColor } from "./color.js";
 import { literalValueOf } from "../../framework/projections.js";
 import "../../configs/platform.js";
@@ -88,7 +88,7 @@ function prepareLinkedTokenBody({ path, body, source, config, destinationPlatfor
 */
 function nativeLiteral({ config, value, remBase }) {
 	const marked = typeof value === "string" && hasRefMarker(value);
-	const calc = isMultiply(value) || isDivide(value);
+	const calc = isCalc(value);
 	if (!marked && !calc && !isOklchColor(value)) return value;
 	const literal = literalValueOf(config, value);
 	if (literal === void 0) return value;

package/dist/entities/system/modifier-axis.d.ts

@@ -1,5 +1,5 @@
-import { Config } from "../../framework/Config.js";
 import { ModifierCategory, ModifierGroupMeta } from "./Modifier.js";
+import { Config } from "../../framework/Config.js";
 
 //#region src/entities/system/modifier-axis.d.ts
 /**

package/dist/entities/system/style-bag.js

@@ -4,7 +4,7 @@ import { defineSubEntity } from "../../framework/defineSubEntity.js";
 import { isCssProperty, kebabCase } from "../../css/values.js";
 import { valueSchemaOf } from "../../framework/value-domain.js";
 import { glyphLeafOf, glyphPackageRef } from "./glyph-identity.js";
-import { glyphPropsOfBody, refListOf, stylePropTokenPath } from "../../framework/projections.js";
+import { glyphPropsOfBody, isCustomPropertyKey, refListOf, stylePropTokenPath } from "../../framework/projections.js";
 import { z } from "zod";
 //#region src/entities/system/style-bag.ts
 /** The explicit type annotation breaks the `z.lazy` self-reference cycle and keeps the
@@ -211,6 +211,7 @@ function stylePropertyBehind(config, cssProperty) {
 */
 function bagKeyIssue(config, key, declared, { cssBehind = true } = {}) {
 	if (key.startsWith("data-") || key.startsWith("aria-")) return void 0;
+	if (isCustomPropertyKey(key)) return void 0;
 	if (key.includes("-")) {
 		const camel = camelCase(key);
 		if (config.resolve("style-property", camel)) return `\`${key}\` is not a style property; a layer key is the style-prop name, \`${camel}\`.`;