tokens-to-css 1.0.0 → 1.1.0

package/README.md

@@ -57,6 +57,25 @@ stylesheet — the relationship survived instead of being flattened to `#191627`
 Change the primitive and everything pointing at it moves, which is the reason to
 keep tokens in a hierarchy at all.
 
+Composite tokens work too. Shadow, border, transition and gradient become one
+custom property each, and typography becomes one per property it describes:
+
+```css
+  --elevation-low: 0px 2px 6px 0px var(--color-shadow);
+  --motion-emphasized: 200ms cubic-bezier(0.2, 0, 0, 1) 0ms;
+  --type-body-font-size: 0.875rem;
+  --type-body-letter-spacing: 0.16px;
+```
+
+An aliased sub-value stays an alias there too, so a shadow still moves when its
+colour does. And where the token genuinely does not say something — a transition
+never says *which* property it animates — the missing part is yours to supply
+rather than ours to invent:
+
+```css
+.panel { transition: opacity var(--motion-emphasized); }
+```
+
 A URL works wherever a path does:
 
 ```js
@@ -136,7 +155,7 @@ addresses refused — including when the URL names one literally.
 | [Getting started](docs/getting-started.md) | Five steps from install to a stylesheet, including breaking it on purpose |
 | [What it accepts](docs/formats.md) | The three shapes, the order they are checked, and everything refused |
 | [The naming rule](docs/naming.md) | How `color.brand` becomes `--color-brand`, and why that is a promise |
-| [Failure codes](docs/failures.md) | The eight codes and what each one means |
+| [Failure codes](docs/failures.md) | The nine codes and what each one means |
 
 ## What it will not do
 
@@ -149,10 +168,14 @@ deferred, not forgotten.
 - **Evaluate expressions.** `{spacing.md} * 2` is refused rather than computed.
   There is no evaluator in this package. `calc()` and `clamp()` are valid CSS
   and pass through untouched.
-- **Convert composite tokens.** Typography, shadow, border, gradient and
-  transition are refused: a typography token is five CSS properties, and
-  accepting it would change what "one token, one custom property" means.
-  Deferred to a version after this one.
+- **Guess at a token it cannot write.** A composite missing a sub-property the
+  spec marks required, a border whose style is SVG geometry, a font weight that
+  is not a weight — each is **skipped**: left out of the stylesheet, listed in
+  `skipped` on the result, and named in a comment above `:root`, while the rest
+  of the file converts.
+- **Emit the `font` shorthand.** Used alone it drops `letter-spacing` in
+  silence, so a typography token becomes five properties rather than five plus a
+  trap.
 - **Pick a winner on a collision.** Two token paths that produce the same
   custom-property name fail the conversion rather than one quietly overwriting
   the other.

package/dist/index.d.ts

@@ -1,52 +1,3 @@
-//#region src/options.d.ts
-/**
- * What a caller passes in and gets back.
- *
- * These live apart from the public surface so the orchestrator can read them
- * without importing the entry point that calls it — a cycle between the two
- * would work in ESM and still be the wrong shape (AD-1).
- */
-/** How a remote Token Source is fetched. Ignored when the source is a local path. */
-interface HttpOptions {
-  /** Allow `http:` URLs. Off by default — only `https:` is fetched. */
-  readonly allowInsecure?: boolean;
-  /** Total budget for the request, in milliseconds. */
-  readonly timeoutMs?: number;
-  /** Largest response body accepted, in bytes. */
-  readonly maxBytes?: number;
-  /** How many redirects to follow before giving up. */
-  readonly maxRedirects?: number;
-}
-/** Everything a caller can adjust about a conversion. */
-interface GenerateCssOptions {
-  /** Directory the stylesheet is written to. Defaults to `assets/css`. */
-  readonly outDir?: string;
-  /** Filename inside that directory. Defaults to `tokens.css`. */
-  readonly fileName?: string;
-  /** Base for resolving relative paths. Defaults to the current working directory. */
-  readonly baseDir?: string;
-  /** Network policy for a URL Token Source. */
-  readonly http?: HttpOptions;
-}
-/** What a successful conversion reports back. Deliberately carries no CSS. */
-interface GenerateCssResult {
-  /** Absolute path of the stylesheet that was written. */
-  readonly outputPath: string;
-  /** How many custom properties it declares. */
-  readonly tokenCount: number;
-}
-/** The defaults a conversion uses when the caller says nothing. */
-declare const DEFAULTS: Readonly<{
-  outDir: "assets/css";
-  fileName: "tokens.css";
-  http: Readonly<{
-    allowInsecure: false;
-    timeoutMs: 10000;
-    maxBytes: 10000000;
-    maxRedirects: 3;
-  }>;
-}>;
-//#endregion
 //#region src/errors.d.ts
 /**
  * The failure contract — public surface, frozen by semver (AD-4).
@@ -72,15 +23,33 @@ declare const FailureCode: Readonly<{
   readonly ALIAS_CYCLE: 'ALIAS_CYCLE';
   /** An alias points at a token that does not exist. */
   readonly ALIAS_DANGLING: 'ALIAS_DANGLING';
-  /** A value is an object, array, boolean, or null rather than a scalar. */
+  /** A value is an object, array, boolean, or null rather than a scalar — reported as a skipped token, not a failure. */
   readonly COMPOSITE_VALUE: 'COMPOSITE_VALUE';
   /** Two or more tokens would emit the same custom-property name. */
   readonly NAME_COLLISION: 'NAME_COLLISION';
   /** The stylesheet could not be written. */
   readonly OUTPUT_WRITE_FAILED: 'OUTPUT_WRITE_FAILED';
+  /** Every token was skipped, so the stylesheet would declare nothing (FR-24). */
+  readonly NOTHING_EMITTED: 'NOTHING_EMITTED';
 }>;
-/** One of the eight failure codes. */
+/** One of the nine failure codes. */
 type FailureCode = (typeof FailureCode)[keyof typeof FailureCode];
+/**
+ * One token that was left out of the stylesheet (FR-24).
+ *
+ * A skip is not a failure: the conversion succeeded and the document is
+ * otherwise intact. It is reported here for callers, and in a comment block
+ * above `:root` for the humans who will read the generated file — which is the
+ * copy that shows up in a pull request when a token stops being emitted.
+ */
+interface SkippedToken {
+  /** Dotted path of the token, spelled as the document wrote it. */
+  readonly path: string;
+  /** Why, in the same vocabulary a failure would have used. */
+  readonly code: FailureCode;
+  /** The sentence a caller would have seen had this been fatal. Wording is not contract. */
+  readonly reason: string;
+}
 /** What a `TokenCssError` is constructed from. */
 interface TokenCssErrorInit {
   /** The failure class. */
@@ -109,20 +78,84 @@ declare class TokenCssError extends Error {
   constructor(message: string, init: TokenCssErrorInit);
 }
 //#endregion
+//#region src/options.d.ts
+/**
+ * What a caller passes in and gets back.
+ *
+ * These live apart from the public surface so the orchestrator can read them
+ * without importing the entry point that calls it — a cycle between the two
+ * would work in ESM and still be the wrong shape (AD-1).
+ */
+/** How a remote Token Source is fetched. Ignored when the source is a local path. */
+interface HttpOptions {
+  /** Allow `http:` URLs. Off by default — only `https:` is fetched. */
+  readonly allowInsecure?: boolean;
+  /** Total budget for the request, in milliseconds. */
+  readonly timeoutMs?: number;
+  /** Largest response body accepted, in bytes. */
+  readonly maxBytes?: number;
+  /** How many redirects to follow before giving up. */
+  readonly maxRedirects?: number;
+}
+/** Everything a caller can adjust about a conversion. */
+interface GenerateCssOptions {
+  /** Directory the stylesheet is written to. Defaults to `assets/css`. */
+  readonly outDir?: string;
+  /** Filename inside that directory. Defaults to `tokens.css`. */
+  readonly fileName?: string;
+  /** Base for resolving relative paths. Defaults to the current working directory. */
+  readonly baseDir?: string;
+  /** Network policy for a URL Token Source. */
+  readonly http?: HttpOptions;
+}
+/** What a successful conversion reports back. Deliberately carries no CSS. */
+interface GenerateCssResult {
+  /** Absolute path of the stylesheet that was written. */
+  readonly outputPath: string;
+  /** How many custom properties it declares. */
+  readonly tokenCount: number;
+  /**
+   * Tokens the document contained that the stylesheet could not (FR-24).
+   *
+   * Empty on a conversion that lost nothing, which is the ordinary case. A
+   * caller that wants a conversion to be all-or-nothing checks this and decides
+   * for itself; the library's own answer is to convert what it can and say what
+   * it could not.
+   */
+  readonly skipped: readonly SkippedToken[];
+}
+/** The defaults a conversion uses when the caller says nothing. */
+declare const DEFAULTS: Readonly<{
+  outDir: "assets/css";
+  fileName: "tokens.css";
+  http: Readonly<{
+    allowInsecure: false;
+    timeoutMs: 10000;
+    maxBytes: 10000000;
+    maxRedirects: 3;
+  }>;
+}>;
+//#endregion
 //#region src/index.d.ts
 /**
  * Convert a design-token document into a CSS custom-properties stylesheet.
  *
  * Reads the Token Source, validates it completely, and writes the stylesheet —
- * or throws a `TokenCssError` and writes nothing at all. There is no partial
- * success: a previous stylesheet at the target path is left untouched whenever
- * the conversion fails.
+ * or throws a `TokenCssError` and writes nothing at all. A failed conversion
+ * writes nothing: a previous stylesheet at the target path is left untouched.
+ *
+ * A token whose value cannot be written as CSS does not fail the conversion
+ * (FR-24). It is left out, listed in `skipped` on the result, and named in a
+ * comment above `:root` in the stylesheet itself. Everything else — an
+ * unreadable source, a document shaped in a way this version does not accept,
+ * an alias cycle, a dangling reference, a name collision — still fails whole.
  *
  * @param source Path to a single local file, or a URL.
  * @param options Output location and network policy.
- * @returns Where the stylesheet was written, and how many properties it holds.
+ * @returns Where the stylesheet was written, how many properties it holds, and
+ * which tokens it left out.
  * @throws {TokenCssError} With a `code` naming the failure class.
  */
 declare function generateCss(source: string | URL, options?: GenerateCssOptions): Promise<GenerateCssResult>;
 //#endregion
-export { DEFAULTS, FailureCode, type GenerateCssOptions, type GenerateCssResult, type HttpOptions, TokenCssError, type TokenCssErrorInit, generateCss };
+export { DEFAULTS, FailureCode, type GenerateCssOptions, type GenerateCssResult, type HttpOptions, type SkippedToken, TokenCssError, type TokenCssErrorInit, generateCss };

package/dist/index.js

@@ -21,6 +21,13 @@ function ref(path) {
 		path
 	};
 }
+/** Builds a value assembled from literal text and references. */
+function composite(parts) {
+	return {
+		kind: "composite",
+		parts
+	};
+}
 /** Builds a token node. */
 function token(path, value) {
 	return {
@@ -32,6 +39,22 @@ function token(path, value) {
 function isRef(value) {
 	return value.kind === "ref";
 }
+/** Narrows a value to a composite. */
+function isComposite(value) {
+	return value.kind === "composite";
+}
+/**
+* Every reference a token makes, in order.
+*
+* A scalar makes at most one; a composite makes as many as it has aliased
+* sub-values. Both validators read the graph through this, so neither has to
+* know that composites exist.
+*/
+function referencesOf(value) {
+	if (isRef(value)) return [value];
+	if (isComposite(value)) return value.parts.filter((part) => typeof part !== "string");
+	return [];
+}
 /**
 * Renders a path the way the token document wrote it, for humans.
 *
@@ -67,12 +90,14 @@ const FailureCode = Object.freeze({
 	ALIAS_CYCLE: "ALIAS_CYCLE",
 	/** An alias points at a token that does not exist. */
 	ALIAS_DANGLING: "ALIAS_DANGLING",
-	/** A value is an object, array, boolean, or null rather than a scalar. */
+	/** A value is an object, array, boolean, or null rather than a scalar — reported as a skipped token, not a failure. */
 	COMPOSITE_VALUE: "COMPOSITE_VALUE",
 	/** Two or more tokens would emit the same custom-property name. */
 	NAME_COLLISION: "NAME_COLLISION",
 	/** The stylesheet could not be written. */
-	OUTPUT_WRITE_FAILED: "OUTPUT_WRITE_FAILED"
+	OUTPUT_WRITE_FAILED: "OUTPUT_WRITE_FAILED",
+	/** Every token was skipped, so the stylesheet would declare nothing (FR-24). */
+	NOTHING_EMITTED: "NOTHING_EMITTED"
 });
 /**
 * The only error this library throws.
@@ -199,40 +224,58 @@ function customPropertyName(path, source) {
 }
 //#endregion
 //#region src/emit/css.ts
+/** Two spaces. Fixed: a configurable indent would make goldens negotiable. */
+const INDENT = "  ";
 /**
-* Writing the stylesheet (FR-9, FR-10, AD-10).
+* The block that announces skipped tokens (FR-24).
 *
-* The whole document becomes one string before anything reaches disk (AD-6), so
-* a failure late in emission cannot leave half a stylesheet behind.
+* This is the half of the skip report that reaches people rather than callers.
+* A generated stylesheet lives in a repository, so a token that stopped being
+* emitted shows up here in the next diff — where somebody is already looking —
+* instead of only in a return value most callers never read.
 *
-* The exact bytes produced here are the contract the golden files hold. Two
-* runs over the same document must produce identical text, which is why nothing
-* in this module reads the clock, the filesystem, the environment, or the
-* order a runtime happens to iterate keys — declaration order is the order of
-* the array it was handed, and that is document order.
+* Nothing is emitted when nothing was skipped. That is not a nicety: it is what
+* keeps every document that converted before this existed byte-identical.
 */
-/** Two spaces. Fixed: a configurable indent would make goldens negotiable. */
-const INDENT = "  ";
+function skipComment(skipped) {
+	if (skipped.length === 0) return [];
+	return [
+		`/* ${skipped.length === 1 ? "1 token was skipped:" : `${skipped.length} tokens were skipped:`}`,
+		...skipped.map((s) => ` *   ${s.reason}`),
+		" */"
+	];
+}
 /**
 * Renders a normalized document as a stylesheet.
 *
 * A token whose value points at another token is written as `var(--target)`,
 * never as the target's value. That is the whole point of the product: the
 * relationship the token file expressed survives into the CSS, so changing a
-* primitive still moves everything that referred to it.
+* primitive still moves everything that referred to it. A composite is the same
+* promise applied piecewise — an aliased sub-value stays `var(--target)` inside
+* the larger value, so a shadow still moves when its colour does.
+*
+* A document carrying skipped tokens is preceded by a comment naming them, so
+* the stylesheet says what it is missing rather than quietly being short.
 *
 * @param doc The normalized document, in document order.
+* @param skipped Tokens the document held that the stylesheet cannot, announced
+* in a comment above the rule. Empty for a document that lost nothing, and then
+* no comment is written at all.
 * @param source The Token Source, carried only so a naming failure can name it.
 * @returns The complete stylesheet text, ending in exactly one newline.
 */
-function emitStylesheet(doc, source) {
+function emitStylesheet(doc, skipped, source) {
+	const reference = (path) => `var(${customPropertyName(path, source)})`;
+	const declarations = doc.tokens.map((node) => {
+		const property = customPropertyName(node.path, source);
+		const value = isRef(node.value) ? reference(node.value.path) : isComposite(node.value) ? node.value.parts.map((part) => typeof part === "string" ? part : reference(part.path)).join("") : stringifyLiteral(node.value.value);
+		return `${INDENT}${property}: ${value};`;
+	});
 	return [
+		...skipComment(skipped),
 		":root {",
-		...doc.tokens.map((node) => {
-			const property = customPropertyName(node.path, source);
-			const value = isRef(node.value) ? `var(${customPropertyName(node.value.path, source)})` : stringifyLiteral(node.value.value);
-			return `${INDENT}${property}: ${value};`;
-		}),
+		...declarations,
 		"}",
 		""
 	].join("\n");
@@ -253,17 +296,20 @@ const DEFAULTS = Object.freeze({
 //#endregion
 //#region src/dialects/values.ts
 /**
-* Object-form scalar values (FR-23).
+* Scalars the spec writes in an expanded notation (FR-23, FR-26).
 *
-* The current DTCG spec writes a colour and a dimension as objects rather than
-* strings:
+* Four values in this format are one CSS value each, written as an object or an
+* array rather than a string:
 *
 *   { "colorSpace": "srgb", "components": [0, 0, 0], "alpha": 1, "hex": "#000" }
 *   { "value": 0.25, "unit": "rem" }
+*   ["Monaco", "Consolas", "monospace"]
+*   [0, 0, 1, 1]
 *
-* Both still describe **one** CSS value. They are scalars written with more
-* ceremony, not composites, and refusing them meant refusing every design
-* system published against the current spec.
+* All four are scalars written with more ceremony, not composites. FR-23
+* accepted the two written as objects, because refusing them meant refusing
+* every design system published against the current spec; the 2026-09-02 survey
+* found the same mistake still standing for the two written as arrays.
 *
 * Two properties of this module matter more than the conversion itself:
 *
@@ -373,22 +419,427 @@ function colorToCss(raw, path, source) {
 	return `color(${space} ${rendered.join(" ")}${suffix})`;
 }
 /**
-* Converts an object-form scalar into stylesheet text.
-*
-* @returns The CSS value, or `null` when the object is not a scalar in object
-* form — a typography or shadow block, which stays a composite and is refused
-* by the caller.
-* @throws {TokenCssError} `FORMAT_NOT_ALLOWED` when the object *is* one of these
-* shapes but is malformed or unusable in CSS.
+* Families CSS resolves itself. Quoting one turns the generic family into the
+* name of a font that does not exist, so these are never quoted.
 */
-function objectValueToCss(raw, path, source) {
-	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+const GENERIC_FAMILIES = /* @__PURE__ */ new Set([
+	"serif",
+	"sans-serif",
+	"monospace",
+	"cursive",
+	"fantasy",
+	"system-ui",
+	"ui-serif",
+	"ui-sans-serif",
+	"ui-monospace",
+	"ui-rounded",
+	"math",
+	"emoji",
+	"fangsong"
+]);
+/** Quoted, or they are read as the keyword rather than as a family name. */
+const CSS_WIDE_KEYWORDS = /* @__PURE__ */ new Set([
+	"inherit",
+	"initial",
+	"unset",
+	"revert",
+	"revert-layer",
+	"default"
+]);
+/** A name that needs no quotes: one identifier, no spaces, not starting with a digit. */
+const BARE_NAME = /^-?[a-zA-Z_][a-zA-Z0-9_-]*$/;
+/** A comma or a quote means the author already wrote CSS here, not one font name. */
+const ALREADY_CSS = /[,'"]/;
+/**
+* Renders one entry of a font family list.
+*
+* The 2026-09-02 survey found four notations in the wild, and two of them —
+* Microsoft Fluent's and GitHub Primer's — put an entire pre-quoted stack where
+* the spec says one name goes. A quoting rule applied to those would wrap the
+* whole stack in quotes and produce a single bogus font name, in silence. So an
+* entry that already contains a comma or a quote is passed through as written:
+* it is CSS the author wrote, and it is correct as it stands.
+*/
+function fontFamilyEntry(name) {
+	if (ALREADY_CSS.test(name)) return name;
+	if (GENERIC_FAMILIES.has(name.toLowerCase())) return name;
+	if (CSS_WIDE_KEYWORDS.has(name.toLowerCase())) return `"${name}"`;
+	return BARE_NAME.test(name) ? name : `"${name}"`;
+}
+/** An array of names — every element a non-empty string with no reference in it. */
+function isFontFamily(raw) {
+	return raw.length > 0 && raw.every((n) => typeof n === "string" && n.trim() !== "" && !/[{}]/.test(n));
+}
+/** Four finite numbers, and nothing else in DTCG is written that way. */
+function isCubicBezier(raw) {
+	return raw.length === 4 && raw.every((n) => typeof n === "number" && Number.isFinite(n));
+}
+/**
+* Converts a scalar written in an expanded notation into stylesheet text.
+*
+* Recognition reads the **shape** and never the declared `$type`, which is what
+* keeps "a `16` never becomes `16px`" true: `{colorSpace, components}` can only
+* be a colour, `{value, unit}` can only be a dimension, an array of names can
+* only be a font family, and four numbers can only be a curve.
+*
+* @returns The CSS value, or `null` when this is not a scalar in disguise — a
+* typography block, a shadow list, an array holding a reference. The caller
+* skips those (FR-24) rather than guessing at them.
+* @throws {TokenCssError} `FORMAT_NOT_ALLOWED` when the value *is* one of these
+* shapes but is malformed or unusable in CSS, which is a different thing from
+* being unrecognized and gets its own message.
+*/
+function scalarToCss(raw, path, source) {
+	if (typeof raw !== "object" || raw === null) return null;
+	if (Array.isArray(raw)) {
+		if (isFontFamily(raw)) return raw.map(fontFamilyEntry).join(", ");
+		if (isCubicBezier(raw)) return `cubic-bezier(${raw.join(", ")})`;
+		return null;
+	}
 	const record = raw;
 	if (isColor(record)) return colorToCss(record, path, source);
 	if (isDimension(record)) return dimensionToCss(record, path, source);
 	return null;
 }
 //#endregion
+//#region src/dialects/composites.ts
+/**
+* Composite tokens that fit one CSS value (FR-25).
+*
+* Four DTCG types describe several sub-values that CSS writes as a single
+* property: shadow, border, transition and gradient. Each becomes one custom
+* property here. The types that describe *several* CSS properties — typography,
+* and the object form of strokeStyle — cannot, and are not this module's
+* business.
+*
+* Two rules run through everything below.
+*
+* **Component order is public contract.** Once a shadow ships as
+* `offsetX offsetY blur spread color`, every stylesheet in the world holds that
+* order, and changing it is a major version. It is CSS's order, not ours, which
+* is the only defensible way to pick one.
+*
+* **Nothing absent is invented.** Every sub-property the spec marks `MUST` has
+* to be there or the token is skipped: a `spread` assumed to be `0` would be
+* this product's first inference, and there is no principled second place to
+* stop. Where the token genuinely does not say something — the axis of a
+* gradient, the property a transition animates — the emitted value is the part
+* it did say, and the consumer supplies the rest.
+*/
+/** A whole-string reference, matching the one the walk uses. */
+const WHOLE_REFERENCE$1 = /^\{([^{}]+)\}$/;
+/** Raised inside this module and caught at its edge; never escapes. */
+var Unwritable = class extends Error {};
+const unwritable = (why) => {
+	throw new Unwritable(why);
+};
+/**
+* Renders one sub-value: a reference stays a reference, anything else becomes
+* the CSS text for it.
+*
+* This is where "an aliased sub-value stays an alias" is implemented — the one
+* thing that keeps expansion from duplicating the primitives it was built from.
+*/
+function sub(raw, what) {
+	if (typeof raw === "string") {
+		const whole = WHOLE_REFERENCE$1.exec(raw.trim());
+		if (whole) return ref(whole[1].split("."));
+		if (/[{}]/.test(raw)) unwritable(`its ${what} has a reference inside a larger value`);
+		return raw;
+	}
+	if (typeof raw === "number") return String(raw);
+	const scalar = scalarToCss(raw, [], "");
+	if (scalar === null) unwritable(`its ${what} is not a value CSS can hold`);
+	return scalar;
+}
+/** Appends one part, merging it into the previous one when both are text. */
+function push(out, part) {
+	const last = out.at(-1);
+	if (typeof part === "string" && typeof last === "string") out[out.length - 1] = last + part;
+	else out.push(part);
+}
+/**
+* Joins groups of parts with a separator **between the groups**.
+*
+* A group is one sub-value, and it may already be several parts — a shadow's
+* colour is one group whether it is a literal or a reference. Flattening before
+* separating would put the separator between the pieces of a sub-value instead
+* of between sub-values, which is how a shadow list first came out as
+* `0, 1px, 2px, 0, #000`.
+*/
+function join$1(groups, separator) {
+	const out = [];
+	groups.forEach((group, index) => {
+		if (index > 0 && separator !== "") push(out, separator);
+		for (const part of Array.isArray(group) ? group : [group]) push(out, part);
+	});
+	return out;
+}
+/** Requires every sub-property the spec marks MUST. */
+function require_(value, keys, kind) {
+	const missing = keys.filter((k) => !(k in value));
+	if (missing.length > 0) unwritable(`its ${kind} is missing ${missing.map((m) => `"${m}"`).join(", ")}`);
+}
+/** `offsetX offsetY blur spread color`, with `inset` in front when true. */
+function shadowToParts(raw) {
+	require_(raw, [
+		"color",
+		"offsetX",
+		"offsetY",
+		"blur",
+		"spread"
+	], "shadow");
+	const parts = join$1([...[
+		"offsetX",
+		"offsetY",
+		"blur",
+		"spread"
+	].map((k) => sub(raw[k], k)), sub(raw["color"], "color")], " ");
+	return raw["inset"] === true ? join$1(["inset", ...parts], " ") : parts;
+}
+/** `width style color`. */
+function borderToParts(raw) {
+	require_(raw, [
+		"color",
+		"width",
+		"style"
+	], "border");
+	const style = raw["style"];
+	if (style !== null && typeof style === "object") unwritable("its style is written as an object, which a CSS border cannot express");
+	return join$1([
+		sub(raw["width"], "width"),
+		sub(style, "style"),
+		sub(raw["color"], "color")
+	], " ");
+}
+/**
+* `duration timingFunction delay` — the tail of the `transition` shorthand.
+*
+* The token never says *which* property is animated, so what is emitted is
+* everything else, used as `transition: opacity var(--…)`. In that shorthand
+* the first time is the duration and the second is the delay, which is why the
+* order is not the one the object is written in.
+*/
+function transitionToParts(raw) {
+	require_(raw, [
+		"duration",
+		"delay",
+		"timingFunction"
+	], "transition");
+	return join$1([
+		sub(raw["duration"], "duration"),
+		sub(raw["timingFunction"], "timing function"),
+		sub(raw["delay"], "delay")
+	], " ");
+}
+/**
+* The stop list of a gradient, without an axis.
+*
+* A DTCG gradient is stops and nothing else — no direction, no angle. Emitting
+* `linear-gradient(…)` would mean inventing an axis the token never stated, so
+* the value is the stops, used as `background: linear-gradient(to right, var(--…))`.
+*
+* `position` is 0–1 in the token and a percentage in CSS, and the spec says an
+* out-of-range number is clamped rather than refused.
+*/
+function gradientToParts(raw) {
+	if (raw.length === 0) unwritable("it is an empty gradient");
+	return join$1(raw.map((stop) => {
+		if (typeof stop === "string") {
+			const whole = WHOLE_REFERENCE$1.exec(stop.trim());
+			if (whole) return [ref(whole[1].split("."))];
+			return unwritable("one of its stops is neither a stop nor a reference");
+		}
+		if (stop === null || typeof stop !== "object" || Array.isArray(stop)) return unwritable("one of its stops is not a gradient stop");
+		const record = stop;
+		require_(record, ["color", "position"], "gradient stop");
+		const position = record["position"];
+		if (typeof position !== "number" || !Number.isFinite(position)) return unwritable("one of its stop positions is not a number");
+		const clamped = Math.min(1, Math.max(0, position));
+		return join$1([sub(record["color"], "colour"), `${clamped * 100}%`], " ");
+	}), ", ");
+}
+/** True for `[{...}, ...]` — a list of shadows rather than one. */
+const isObjectList = (raw) => raw.length > 0 && raw.every((e) => e !== null && typeof e === "object" && !Array.isArray(e));
+/** Dispatches on shape. Throws {@link Unwritable} for a recognized-but-broken value. */
+function build(raw) {
+	if (Array.isArray(raw)) {
+		if (!isObjectList(raw)) return null;
+		const first = raw[0];
+		if ("position" in first) return gradientToParts(raw);
+		if ("offsetX" in first || "offsetY" in first) return join$1(raw.map((s) => shadowToParts(s)), ", ");
+		return null;
+	}
+	if (raw === null || typeof raw !== "object") return null;
+	const record = raw;
+	if ("offsetX" in record || "offsetY" in record || "blur" in record) return shadowToParts(record);
+	if ("width" in record && "style" in record) return borderToParts(record);
+	if ("duration" in record || "timingFunction" in record) return transitionToParts(record);
+	return null;
+}
+/**
+* Converts a composite that fits one CSS value.
+*
+* Recognition is by shape, never by `$type` — the same rule the object and
+* array scalars follow. A shadow has offsets and a blur; a border has a width
+* and a style; a transition has a duration and a timing function; a gradient is
+* a list of stops. Nothing else is any of those.
+*/
+function compositeToParts(raw) {
+	try {
+		const parts = build(raw);
+		return parts === null ? { kind: "unrecognized" } : {
+			kind: "parts",
+			parts
+		};
+	} catch (err) {
+		if (err instanceof Unwritable) return {
+			kind: "unwritable",
+			reason: err.message
+		};
+		throw err;
+	}
+}
+/**
+* Sub-property to name suffix — public contract, seven entries.
+*
+* The 2026-09-02 design claimed the suffix would fall out of the existing
+* naming rule for free. It does not: that rule lowercases and splits on
+* non-alphanumerics, so `fontSize` becomes `fontsize`, and teaching it to split
+* camelCase would rename every token already emitted — a major version.
+*
+* So there is a table, and each entry is the **CSS property the sub-value
+* feeds**, which is the one mapping that is not arbitrary: the token is spelled
+* the way the declaration that uses it is spelled.
+*
+*   font-size: var(--type-body-font-size);
+*
+* Adding an entry later is additive. Changing one is a major version.
+*/
+const CSS_PROPERTY = Object.freeze({
+	fontFamily: "font-family",
+	fontSize: "font-size",
+	fontWeight: "font-weight",
+	letterSpacing: "letter-spacing",
+	lineHeight: "line-height",
+	dashArray: "dash-array",
+	lineCap: "line-cap"
+});
+/**
+* The spec's closed alias table for font weights.
+*
+* A word outside it skips the token. Passing it through would emit
+* `font-weight: regular`, which is invalid CSS a browser ignores in silence —
+* and inventing a number for an unknown word would be worse.
+*/
+const FONT_WEIGHTS = Object.freeze({
+	thin: 100,
+	hairline: 100,
+	"extra-light": 200,
+	"ultra-light": 200,
+	light: 300,
+	normal: 400,
+	regular: 400,
+	book: 400,
+	medium: 500,
+	"semi-bold": 600,
+	"demi-bold": 600,
+	bold: 700,
+	"extra-bold": 800,
+	"ultra-bold": 800,
+	black: 900,
+	heavy: 900,
+	"extra-black": 950,
+	"ultra-black": 950
+});
+/** A font weight: a number, a reference, or one of the spec's words. */
+function fontWeight(raw) {
+	if (typeof raw === "string" && !WHOLE_REFERENCE$1.test(raw.trim())) {
+		const mapped = FONT_WEIGHTS[raw.toLowerCase()];
+		if (mapped === void 0) unwritable(`its font weight is "${raw}", which is not a weight the spec defines`);
+		return [String(mapped)];
+	}
+	return [sub(raw, "font weight")];
+}
+/**
+* Typography: five CSS properties, so five custom properties.
+*
+* The `font` shorthand is not emitted, not even as an extra convenience
+* property. Used alone it drops `letter-spacing` in silence, which is the exact
+* failure this product exists to prevent.
+*/
+function typographyToExpansion(raw) {
+	require_(raw, [
+		"fontFamily",
+		"fontSize",
+		"fontWeight",
+		"letterSpacing",
+		"lineHeight"
+	], "typography");
+	return [
+		{
+			suffix: CSS_PROPERTY["fontFamily"],
+			parts: [sub(raw["fontFamily"], "font family")]
+		},
+		{
+			suffix: CSS_PROPERTY["fontSize"],
+			parts: [sub(raw["fontSize"], "font size")]
+		},
+		{
+			suffix: CSS_PROPERTY["fontWeight"],
+			parts: fontWeight(raw["fontWeight"])
+		},
+		{
+			suffix: CSS_PROPERTY["letterSpacing"],
+			parts: [sub(raw["letterSpacing"], "letter spacing")]
+		},
+		{
+			suffix: CSS_PROPERTY["lineHeight"],
+			parts: [sub(raw["lineHeight"], "line height")]
+		}
+	];
+}
+/** Stroke style in object form: two SVG properties, so two custom properties. */
+function strokeStyleToExpansion(raw) {
+	require_(raw, ["dashArray", "lineCap"], "stroke style");
+	const dashes = raw["dashArray"];
+	if (!Array.isArray(dashes) || dashes.length === 0) unwritable("its dash array is not a list of lengths");
+	return [{
+		suffix: CSS_PROPERTY["dashArray"],
+		parts: join$1(dashes.map((d) => [sub(d, "dash length")]), " ")
+	}, {
+		suffix: CSS_PROPERTY["lineCap"],
+		parts: [sub(raw["lineCap"], "line cap")]
+	}];
+}
+/**
+* Converts a composite that describes more than one CSS property (FR-25).
+*
+* Recognition is by shape, as everywhere else: only typography has a font size
+* and a line height, and only an object-form stroke style has a dash array.
+*/
+function compositeToExpansion(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return { kind: "unrecognized" };
+	const record = raw;
+	try {
+		if ("fontFamily" in record || "fontSize" in record || "lineHeight" in record) return {
+			kind: "expanded",
+			expanded: typographyToExpansion(record)
+		};
+		if ("dashArray" in record || "lineCap" in record) return {
+			kind: "expanded",
+			expanded: strokeStyleToExpansion(record)
+		};
+		return { kind: "unrecognized" };
+	} catch (err) {
+		if (err instanceof Unwritable) return {
+			kind: "unwritable",
+			reason: err.message
+		};
+		throw err;
+	}
+}
+//#endregion
 //#region src/dialects/walk.ts
 /**
 * The shared tree walk every dialect uses (AD-2, AD-9, AD-20).
@@ -443,27 +894,82 @@ function toTokenValue(raw, path, source) {
 		}
 		if (ANY_BRACE.test(raw)) fail(`token "${formatPath(path)}" has a reference inside a larger value ("${raw}"). This version emits a reference only when the whole value is one`, source, path);
 	}
-	const asObjectScalar = objectValueToCss(raw, path, source);
-	if (asObjectScalar !== null) return literal(asObjectScalar);
+	const asScalar = scalarToCss(raw, path, source);
+	if (asScalar !== null) return literal(asScalar);
+	const asComposite = compositeToParts(raw);
+	if (asComposite.kind === "parts") return composite(asComposite.parts);
+	if (asComposite.kind === "unwritable") throw new TokenCssError(`token "${formatPath(path)}" is a composite, but ${asComposite.reason}`, {
+		code: FailureCode.COMPOSITE_VALUE,
+		source,
+		tokenPaths: [formatPath(path)]
+	});
 	return literal(assertScalar(raw, path, source));
 }
 /**
+* Reads one token node into the custom properties it becomes.
+*
+* Almost always one. A composite that describes several CSS properties becomes
+* several (FR-25), each named by appending the sub-property's suffix to the
+* token's path — so naming, collision detection and the alias graph all keep
+* working on ordinary paths and never learn that expansion exists.
+*
+* @throws {TokenCssError} `COMPOSITE_VALUE` when the value cannot be written,
+* which the caller turns into a skip.
+*/
+function readToken(raw, path, source) {
+	const expansion = compositeToExpansion(raw);
+	if (expansion.kind === "expanded") return expansion.expanded.map((one) => token([...path, one.suffix], composite(one.parts)));
+	if (expansion.kind === "unwritable") throw new TokenCssError(`token "${formatPath(path)}" is a composite, but ${expansion.reason}`, {
+		code: FailureCode.COMPOSITE_VALUE,
+		source,
+		tokenPaths: [formatPath(path)]
+	});
+	return [token(path, toTokenValue(raw, path, source))];
+}
+/**
 * Walks a token document into a flat, ordered list of tokens.
 *
-* Nothing is dropped quietly. A scalar sitting where a group should be is a
-* failure, not a skipped entry, because a token that vanishes between the file
-* and the stylesheet is the silent breakage the Reliability requirement forbids.
+* Nothing is dropped quietly, but not everything is fatal any more (FR-24).
+* One code is skippable and the rest are not:
+*
+* **`COMPOSITE_VALUE`** — the value is an object, an array, a boolean or null,
+* so there is no CSS to write for it. That is scoped to one token and says
+* nothing about the document around it, so the token is left out and recorded
+* while the rest converts.
+*
+* **Everything else stays fatal**, including the token-scoped ones: a non-CSS
+* unit, a reference buried in a larger string, Tokens Studio arithmetic. Each
+* of those has its own message explaining the specific thing that is wrong, and
+* folding them into a generic skip would replace an explanation with a shrug —
+* arithmetic would be reported as an embedded reference, which is true and
+* useless. A document whose shape this version does not accept is refused by
+* name, the way it always has been.
+*
+* The line is drawn on the code rather than on where the failure was raised.
+* Raising position is an implementation detail that moves; the code is public
+* surface that cannot.
 *
 * @throws {TokenCssError} `FORMAT_NOT_ALLOWED` for unsafe keys, stray scalars,
-* and malformed references. Multi-file constructs are caught earlier, by the
-* registry, because they can appear in a document no dialect claims.
+* malformed references and values this version does not accept. Multi-file
+* constructs are caught earlier, by the registry, because they can appear in a
+* document no dialect claims.
 */
 function walkTokenTree(root, source, reader) {
 	const tokens = [];
+	const skipped = [];
 	const visit = (node, path) => {
 		const value = reader.read(node);
 		if (value.found) {
-			tokens.push(token(path, toTokenValue(value.raw, path, source)));
+			try {
+				tokens.push(...readToken(value.raw, path, source));
+			} catch (err) {
+				if (!(err instanceof TokenCssError) || err.code !== FailureCode.COMPOSITE_VALUE) throw err;
+				skipped.push({
+					path: formatPath(path),
+					code: err.code,
+					reason: err.message
+				});
+			}
 			return;
 		}
 		for (const key of Object.keys(node)) {
@@ -476,7 +982,10 @@ function walkTokenTree(root, source, reader) {
 		}
 	};
 	visit(root, []);
-	return tokens;
+	return {
+		tokens,
+		skipped
+	};
 }
 //#endregion
 //#region src/dialects/dtcg.ts
@@ -536,7 +1045,11 @@ function looksLikeDtcg(root) {
 }
 /** Normalizes a DTCG document into the internal representation. */
 function normalizeDtcg(root, source) {
-	return { tokens: walkTokenTree(root, source, reader$2) };
+	const { tokens, skipped } = walkTokenTree(root, source, reader$2);
+	return {
+		doc: { tokens },
+		skipped
+	};
 }
 //#endregion
 //#region src/dialects/sd-legacy.ts
@@ -575,7 +1088,11 @@ function looksLikeSdLegacy(root) {
 }
 /** Normalizes a Style Dictionary legacy document into the internal representation. */
 function normalizeSdLegacy(root, source) {
-	return { tokens: walkTokenTree(root, source, reader$1) };
+	const { tokens, skipped } = walkTokenTree(root, source, reader$1);
+	return {
+		doc: { tokens },
+		skipped
+	};
 }
 /**
 * Finds a token node that speaks both dialects at once.
@@ -690,9 +1207,12 @@ function normalizeTokensStudio(root, source) {
 		code: FailureCode.FORMAT_NOT_ALLOWED,
 		source
 	});
-	const tokens = walkTokenTree(set, source, reader);
+	const { tokens, skipped } = walkTokenTree(set, source, reader);
 	for (const node of tokens) refuseExpressions(node, source);
-	return { tokens };
+	return {
+		doc: { tokens },
+		skipped
+	};
 }
 //#endregion
 //#region src/dialects/registry.ts
@@ -757,9 +1277,16 @@ function normalizeDocument(root, source) {
 		tokenPaths: [mixed.join(".")]
 	});
 	for (const dialect of DIALECTS) if (dialect.matches(root)) {
-		const doc = dialect.normalize(root, source);
-		if (doc.tokens.length === 0) break;
-		return doc;
+		const read = dialect.normalize(root, source);
+		if (read.doc.tokens.length === 0) {
+			if (read.skipped.length > 0) throw new TokenCssError(`every token in this document was skipped, so the stylesheet would declare nothing:\n` + read.skipped.map((skip) => `  ${skip.reason}`).join("\n"), {
+				code: FailureCode.NOTHING_EMITTED,
+				source,
+				tokenPaths: read.skipped.map((skip) => skip.path)
+			});
+			break;
+		}
+		return read;
 	}
 	throw new TokenCssError(`no tokens were recognized in this document. This version reads: ${DIALECTS.map((d) => d.describedAs).join("; ")}`, {
 		code: FailureCode.FORMAT_NOT_ALLOWED,
@@ -1117,13 +1644,14 @@ function resolveOutputPath(outDir, fileName, baseDir) {
 * confusing half-cycles, and a developer with a typo should be told about the
 * typo rather than about a loop that only exists because of it.
 *
-* Every token has at most one outgoing edge — a value is either a literal or a
-* single reference — so the graph is a chain per token, and one linear sweep
-* finds every cycle.
+* A token has as many outgoing edges as its value has references: none for a
+* literal, one for an alias, and one per aliased sub-value for a composite
+* (FR-25). Both passes read those edges through `referencesOf`, so neither
+* needs to know which kind of value produced them.
 */
-/** Where a token's reference points, or `undefined` when it holds a literal. */
-function targetOf(node) {
-	return isRef(node.value) ? formatPath(node.value.path) : void 0;
+/** Every token this one points at, as dotted paths, in order. */
+function targetsOf(node) {
+	return referencesOf(node.value).map((r) => formatPath(r.path));
 }
 /**
 * Reports every reference whose target is not a token in this document.
@@ -1137,12 +1665,13 @@ function checkDangling(doc, byPath, source) {
 	const problems = [];
 	const offenders = [];
 	for (const node of doc.tokens) {
-		const target = targetOf(node);
-		if (target === void 0 || byPath.has(target)) continue;
 		const from = formatPath(node.path);
-		offenders.push(from);
-		const isGroup = [...byPath.keys()].some((known) => known.startsWith(`${target}.`));
-		problems.push(isGroup ? `"${from}" references "${target}", which is a group of tokens rather than a token` : `"${from}" references "${target}", which does not exist`);
+		for (const target of targetsOf(node)) {
+			if (byPath.has(target)) continue;
+			if (!offenders.includes(from)) offenders.push(from);
+			const isGroup = [...byPath.keys()].some((known) => known.startsWith(`${target}.`));
+			problems.push(isGroup ? `"${from}" references "${target}", which is a group of tokens rather than a token` : `"${from}" references "${target}", which does not exist`);
+		}
 	}
 	if (problems.length > 0) throw new TokenCssError(`${problems.length} ${problems.length === 1 ? "reference points" : "references point"} nowhere:\n  ${problems.join("\n  ")}`, {
 		code: FailureCode.ALIAS_DANGLING,
@@ -1156,6 +1685,11 @@ const SETTLED = 2;
 /**
 * Reports every cycle in the reference graph.
 *
+* Depth-first with three colours: a node still on the current path that is
+* reached again closes a cycle. This replaced a linear sweep when composites
+* arrived — the sweep followed one edge per token, which is correct only while
+* a token can make at most one reference, and a composite makes several.
+*
 * Iterative rather than recursive: a document is allowed to be a chain of ten
 * thousand tokens, and that is a stack overflow rather than a clear failure if
 * this walks itself.
@@ -1163,19 +1697,36 @@ const SETTLED = 2;
 function checkCycles(doc, byPath, source) {
 	const state = /* @__PURE__ */ new Map();
 	const cycles = [];
+	const seen = /* @__PURE__ */ new Set();
 	for (const start of doc.tokens) {
 		const startKey = formatPath(start.path);
-		if (state.get(startKey) !== void 0) continue;
-		const chain = [];
-		let cursor = startKey;
-		while (cursor !== void 0 && (state.get(cursor) ?? UNVISITED) === UNVISITED) {
-			state.set(cursor, ON_PATH);
-			chain.push(cursor);
-			const node = byPath.get(cursor);
-			cursor = node === void 0 ? void 0 : targetOf(node);
+		if ((state.get(startKey) ?? UNVISITED) !== UNVISITED) continue;
+		const path = [startKey];
+		const frames = [[...targetsOf(byPath.get(startKey))].reverse()];
+		state.set(startKey, ON_PATH);
+		while (path.length > 0) {
+			const next = frames[frames.length - 1].pop();
+			if (next === void 0) {
+				state.set(path.pop(), SETTLED);
+				frames.pop();
+				continue;
+			}
+			const node = byPath.get(next);
+			if (node === void 0) continue;
+			if (state.get(next) === ON_PATH) {
+				const cycle = path.slice(path.indexOf(next));
+				const key = [...cycle].sort().join("\0");
+				if (!seen.has(key)) {
+					seen.add(key);
+					cycles.push(cycle);
+				}
+				continue;
+			}
+			if (state.get(next) === SETTLED) continue;
+			state.set(next, ON_PATH);
+			path.push(next);
+			frames.push([...targetsOf(node)].reverse());
 		}
-		if (cursor !== void 0 && state.get(cursor) === ON_PATH) cycles.push(chain.slice(chain.indexOf(cursor)));
-		for (const key of chain) state.set(key, SETTLED);
 	}
 	if (cycles.length > 0) {
 		const described = cycles.map((cycle) => `  ${[...cycle, cycle[0]].join(" → ")}`);
@@ -1317,24 +1868,26 @@ async function writeStylesheet(targetPath, contents, source) {
 * divergence the fixed order exists to prevent.
 */
 function convertDocument(raw, source) {
-	const doc = normalizeDocument(raw, source);
+	const { doc, skipped } = normalizeDocument(raw, source);
 	validateAliasGraph(doc, source);
 	validateNoCollisions(doc, source);
 	return {
-		css: emitStylesheet(doc, source),
-		tokenCount: doc.tokens.length
+		css: emitStylesheet(doc, skipped, source),
+		tokenCount: doc.tokens.length,
+		skipped
 	};
 }
 async function runConversion(source, options = {}) {
 	const display = String(source);
 	const baseDir = options.baseDir ?? process.cwd();
 	const resolved = resolveSource(source, baseDir);
-	const { css, tokenCount } = convertDocument(parseTokenJson(resolved.kind === "url" ? await fetchTokenDocument(resolved.url, display, options.http ?? {}) : await readTokenFile(resolved.path, display), display), display);
+	const { css, tokenCount, skipped } = convertDocument(parseTokenJson(resolved.kind === "url" ? await fetchTokenDocument(resolved.url, display, options.http ?? {}) : await readTokenFile(resolved.path, display), display), display);
 	const outputPath = resolveOutputPath(options.outDir ?? DEFAULTS.outDir, options.fileName ?? DEFAULTS.fileName, baseDir);
 	await writeStylesheet(outputPath, css, display);
 	return {
 		outputPath,
-		tokenCount
+		tokenCount,
+		skipped
 	};
 }
 //#endregion
@@ -1350,13 +1903,19 @@ async function runConversion(source, options = {}) {
 * Convert a design-token document into a CSS custom-properties stylesheet.
 *
 * Reads the Token Source, validates it completely, and writes the stylesheet —
-* or throws a `TokenCssError` and writes nothing at all. There is no partial
-* success: a previous stylesheet at the target path is left untouched whenever
-* the conversion fails.
+* or throws a `TokenCssError` and writes nothing at all. A failed conversion
+* writes nothing: a previous stylesheet at the target path is left untouched.
+*
+* A token whose value cannot be written as CSS does not fail the conversion
+* (FR-24). It is left out, listed in `skipped` on the result, and named in a
+* comment above `:root` in the stylesheet itself. Everything else — an
+* unreadable source, a document shaped in a way this version does not accept,
+* an alias cycle, a dangling reference, a name collision — still fails whole.
 *
 * @param source Path to a single local file, or a URL.
 * @param options Output location and network policy.
-* @returns Where the stylesheet was written, and how many properties it holds.
+* @returns Where the stylesheet was written, how many properties it holds, and
+* which tokens it left out.
 * @throws {TokenCssError} With a `code` naming the failure class.
 */
 function generateCss(source, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokens-to-css",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Convert design-token JSON into a CSS custom-properties stylesheet.",
   "keywords": [
     "design-tokens",