@baloise/ds-tokens 19.10.2 → 20.0.0-next.10

package/dist/out-tsc/config.base.js

@@ -0,0 +1,210 @@
+const basePxFontSize = 16;
+const mode = 'Base';
+// Shared with config.brand.ts — a brand's css platform must transform every token type the same
+// way Base's own build does, since a brand's output is now a full merged set (see
+// docs/adr/0030-full-merge-brand-token-css.md), not a small diff. Keeping one list instead of two
+// prevents them silently drifting apart the way they had (config.brand.ts was missing 'ds/border'
+// and used 'ds/font-family' where this list uses the stock 'fontFamily/css').
+export const BASE_CSS_TRANSFORMS = [
+    'attribute/cti',
+    'name/kebab',
+    'time/seconds',
+    'html/icon',
+    'size/rem',
+    'color/css',
+    'asset/url',
+    'fontFamily/css',
+    'cubicBezier/css',
+    'strokeStyle/css/shorthand',
+    'transition/css/shorthand',
+    'ds/css/name',
+    'ds/color/rgba',
+    'ds/size/round',
+    'ds/size/rem',
+    'ds/font-weight',
+    'ds/shadow',
+    'ds/border',
+    'ds/typography',
+];
+const config = {
+    source: [`tokens/${mode}.tokens.json`],
+    platforms: {
+        css: {
+            // No transformGroup — the 'css' transformGroup's built-in 'shadow/css/shorthand' renders
+            // shadow colors as 'rgb(0% 0% 0% / 0.25)' (colorjs.io's default), not this codebase's
+            // '#hex'/'rgba(...)' convention (verified directly — see
+            // docs/plans/shadow-token-type-plan.md). Listed explicitly instead: every other 'css'
+            // transformGroup member is kept verbatim (so nothing else about this platform's output
+            // changes) — including 'fontFamily/css', which already produces correct output and is why
+            // there's no separate 'ds/font-family' transform anywhere — except 'shadow/css/shorthand',
+            // swapped for our own 'ds/shadow', and 'typography/css/shorthand', dropped entirely (not
+            // swapped) — it collapses a typography token's $value into a single `font` shorthand
+            // *string* before 'ds/typography' ever sees it, and there's no way to recover the original
+            // {fontFamily, fontSize, fontWeight, lineHeight} object from that string. This codebase wants
+            // 4 separate longhand custom properties per typography token, never a shorthand
+            // (docs/plans/typography-token-type-plan.md decision 5) — verified directly, same as
+            // shadow/border's own built-ins (the shorthand only became visible once a real
+            // $type: "typography" token existed to trigger its filter).
+            transforms: BASE_CSS_TRANSFORMS,
+            basePxFontSize,
+            buildPath: 'dist/',
+            prefix: 'ds',
+            files: [
+                {
+                    format: 'ds/css/variables-responsive',
+                    destination: `css/${mode.toLowerCase()}.tokens.css`,
+                },
+                {
+                    format: 'ds/css/variables-brand',
+                    destination: `css/${mode.toLowerCase()}.override.css`,
+                    options: {
+                        selector: `[data-theme="${mode.toLowerCase()}"], :host([data-theme="${mode.toLowerCase()}"])`,
+                        outputReferences: true,
+                    },
+                },
+            ],
+            options: {
+                outputReferences: true,
+            },
+        },
+        sass: {
+            // CSS custom properties can't appear inside an `@media` condition (`@media (min-width:
+            // var(--x))` is invalid per spec, not just unsupported) — so
+            // packages/styles/src/scss/mixins/breakpoint.mixin.scss needs real Sass variables, resolved at
+            // compile time, for its `@media` conditions and `- 1px` arithmetic. This platform exists
+            // solely to feed that: filtered to breakpoint tokens only (Global.Dimension.Breakpoint.* and
+            // Alias.Breakpoint.*, the latter referencing the former — both must ship together for the
+            // Sass `$var: $other-var` reference to resolve) — everything else in this design system is
+            // CSS-only. Transforms mirror the 'web' platform's (not 'css' platform's, which forces
+            // 'size/rem'): breakpoint tokens are defined with an explicit "px" unit, and 'ds/dimension'
+            // (unlike the stock 'size/rem') preserves that unit rather than converting it, which is what
+            // the mixin's px-based media queries need.
+            transforms: [
+                'attribute/cti',
+                'name/kebab',
+                'color/css',
+                'ds/css/name',
+                'ds/color/hex',
+                'ds/size/rem',
+                'ds/font-weight',
+                'ds/font-family',
+                'size/rem',
+                'ds/dimension',
+                'ds/shadow',
+                'ds/border',
+                'ds/typography',
+            ],
+            prefix: 'ds',
+            buildPath: 'dist/',
+            files: [
+                {
+                    format: 'ds/scss/variables',
+                    destination: `sass/${mode.toLowerCase()}.tokens.scss`,
+                    filter: token => token.path.some(segment => segment.includes('Breakpoint')),
+                },
+            ],
+            options: {
+                outputReferences: true,
+            },
+        },
+        web: {
+            // No transformGroup — the 'web' transformGroup's built-in 'size/px' unconditionally forces
+            // a "px" suffix without converting the number, which is wrong for a rem-unit dimension
+            // token (1.5rem would come out "1.5px": wrong unit label AND physically 24x smaller). Listed
+            // explicitly instead: 'attribute/cti'/'name/kebab'/'color/css' are 'web' transformGroup's
+            // other members, kept verbatim so nothing else about this platform's output changes;
+            // 'size/px' is dropped in favor of our own 'ds/dimension', which correctly preserves
+            // whichever unit the $value carries.
+            //
+            // The built-in 'size/rem' is added (harmlessly redundant with 'ds/dimension' for every
+            // standalone dimension token, since it already preserves an explicitly-provided unit the
+            // same way) because a border composite token's 'width' sub-value is a *reference* to a
+            // separate dimension token (see docs/plans/border-token-type-plan.md decision 4) — Style
+            // Dictionary only resolves that reference to its referenced token's already-transformed
+            // value when a transform *named* 'size/rem'/'color/css' is present, not an arbitrary
+            // custom-named dimension transform. Without it, 'ds/border' would see a null width for
+            // every Composite.* token on this platform.
+            transforms: [
+                'attribute/cti',
+                'name/kebab',
+                'color/css',
+                'ds/css/name',
+                'ds/color/hex',
+                'ds/size/rem',
+                'ds/font-weight',
+                'ds/font-family',
+                'size/rem',
+                'ds/dimension',
+                'ds/shadow',
+                'ds/border',
+                'ds/typography',
+            ],
+            prefix: 'ds',
+            buildPath: 'dist/',
+            files: [
+                {
+                    format: 'ds/json/flat',
+                    destination: `web/${mode.toLowerCase()}.tokens.json`,
+                },
+            ],
+            options: {
+                outputReferences: true,
+            },
+        },
+        docs: {
+            // See the 'web' platform's comment above — same fix, same reasoning.
+            transforms: [
+                'attribute/cti',
+                'name/kebab',
+                'color/css',
+                'ds/css/name',
+                'ds/color/hex',
+                'ds/size/rem',
+                'ds/font-weight',
+                'ds/font-family',
+                'size/rem',
+                'ds/dimension',
+                'ds/shadow',
+                'ds/border',
+                'ds/typography',
+            ],
+            prefix: 'ds',
+            buildPath: 'dist/',
+            files: [
+                {
+                    format: 'json',
+                    destination: `docs/${mode.toLowerCase()}.tokens.json`,
+                },
+            ],
+            options: {
+                outputReferences: true,
+            },
+        },
+        javascript: {
+            transformGroup: 'js',
+            transforms: [
+                'ds/js/name',
+                'ds/color/hex',
+                'ds/size/round',
+                'ds/dimension/js',
+                'ds/font-weight',
+                'ds/font-family',
+                'ds/shadow',
+                'ds/border',
+                'ds/typography',
+            ],
+            prefix: 'ds',
+            buildPath: 'dist/',
+            files: [
+                {
+                    format: 'ds/javascript/es6',
+                    destination: `js/${mode.toLowerCase()}.tokens.js`,
+                },
+            ],
+            options: {
+                outputReferences: true,
+            },
+        },
+    },
+};
+export default config;

package/dist/out-tsc/config.brand.js

@@ -0,0 +1,92 @@
+import { readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { BASE_CSS_TRANSFORMS } from './config.base.js';
+const basePxFontSize = 16;
+/**
+ * Recursively merges a brand's token tree onto Base's, returning the COMPLETE tree — every
+ * token Base defines, with the brand's own node substituted wherever the brand defines a
+ * `$value` leaf (keeping that leaf's own `$description`/`$extensions` as authored in the brand
+ * file). Unlike a diff, nothing is dropped: the result is self-sufficient and needs no `include`
+ * of Base to resolve references. See docs/adr/0030-full-merge-brand-token-css.md.
+ */
+export function mergeTokenTree(base, brand) {
+    const result = { ...base };
+    for (const key of new Set([...Object.keys(base), ...Object.keys(brand)])) {
+        const baseVal = base[key];
+        const brandVal = brand[key];
+        if (brandVal === undefined) {
+            result[key] = baseVal;
+            continue;
+        }
+        if (typeof brandVal !== 'object' || brandVal === null) {
+            result[key] = brandVal;
+            continue;
+        }
+        if ('$value' in brandVal) {
+            // Token leaf — the brand's own node wins outright.
+            result[key] = brandVal;
+        }
+        else {
+            // Group node — recurse so every sibling token, changed or not, ends up in the result.
+            result[key] = mergeTokenTree((baseVal ?? {}), brandVal);
+        }
+    }
+    return result;
+}
+/**
+ * Creates a Style Dictionary config for a brand's token CSS build.
+ *
+ * Merges the brand token file onto Base (see mergeTokenTree) so the build's source is already
+ * the complete, self-sufficient token tree for that brand — no `include` of Base needed. Emits
+ * two files: `<brand>.tokens.css` (`:host, :root`, for apps that commit to one brand) and
+ * `<brand>.override.css` (`[data-theme]`/`:host([data-theme])`, for scoping a brand to one
+ * element — e.g. Storybook's theme switcher). See docs/adr/0030-full-merge-brand-token-css.md.
+ *
+ * Returns the config and a `cleanup` function that removes the temporary merged-tree file that
+ * was written to disk so Style Dictionary can read it as `source`.
+ */
+export function createBrandConfig(mode) {
+    const brandLower = mode.toLowerCase();
+    const tmpFile = `tokens/.${brandLower}-full.tmp.json`;
+    const baseJson = JSON.parse(readFileSync(`tokens/Base.tokens.json`, 'utf8'));
+    const brandJson = JSON.parse(readFileSync(`tokens/${mode}.tokens.json`, 'utf8'));
+    const mergedTokens = mergeTokenTree(baseJson, brandJson);
+    writeFileSync(tmpFile, JSON.stringify(mergedTokens));
+    const config = {
+        source: [tmpFile],
+        platforms: {
+            css: {
+                transforms: BASE_CSS_TRANSFORMS,
+                basePxFontSize,
+                buildPath: 'dist/',
+                prefix: 'ds',
+                files: [
+                    {
+                        format: 'ds/css/variables-brand',
+                        destination: `css/${brandLower}.tokens.css`,
+                        options: {
+                            selector: ':host, :root',
+                            outputReferences: true,
+                        },
+                    },
+                    {
+                        format: 'ds/css/variables-brand',
+                        destination: `css/${brandLower}.override.css`,
+                        options: {
+                            selector: `[data-theme="${brandLower}"], :host([data-theme="${brandLower}"])`,
+                            outputReferences: true,
+                        },
+                    },
+                ],
+            },
+        },
+    };
+    const cleanup = () => {
+        try {
+            unlinkSync(tmpFile);
+        }
+        catch {
+            // ignore — file may already be gone
+        }
+    };
+    return { config, cleanup };
+}

package/dist/out-tsc/css-naming.js

@@ -0,0 +1,26 @@
+import { kebabCase } from 'change-case';
+/**
+ * Turns a token's path into its final CSS custom property name, matching Style Dictionary's
+ * `css` transformGroup (`name/kebab`, which itself uses `change-case`'s `kebabCase`) followed by
+ * the `ds/css/name` transform (`transformers.ts`). Returns the bare name (no leading `--`), the
+ * same shape Style Dictionary expects from a `name`-type transform - the SD transform is a thin
+ * wrapper around this function, and `apps/toky`'s live preview imports it directly so both stay
+ * in sync (see ADR-0021).
+ */
+export const tokenNameToCssVar = (pathSegments, prefix = 'ds') => {
+    let tokenName = kebabCase([prefix, ...pathSegments].join(' '));
+    const isComponent = pathSegments.includes('🧩 Component');
+    if (isComponent) {
+        tokenName = tokenName.replace('-component', '');
+    }
+    // we use t-shirt sizes and need to make sure that 2xl becomes 2xl and not 2-xl
+    // check if token names has number followed by xl or xs and replace it with numberxl without dash
+    if (/-?([0-9]+)-(xl|xs)/.test(tokenName)) {
+        tokenName = tokenName.replace(/-?([0-9]+)-(xl|xs)/, '-$1$2');
+    }
+    // check that no name has double dash and replace it with single dash
+    if (tokenName.includes('--')) {
+        tokenName = tokenName.replace(/--+/g, '-');
+    }
+    return tokenName;
+};

package/dist/out-tsc/css-preview.js

@@ -0,0 +1,8 @@
+/**
+ * Public subpath (`@baloise/ds-tokens/css-preview`) for consumers outside the build pipeline —
+ * currently `apps/toky`'s live token preview — that need to turn a token path/resolved value into
+ * the same CSS the build actually produces, without duplicating the Style Dictionary transforms.
+ * See ADR-0021.
+ */
+export { tokenNameToCssVar } from './css-naming.js';
+export { resolvedValueToCss, typographyValueToCss, TYPOGRAPHY_CSS_SUFFIXES, responsiveDimensionValueToCss, RESPONSIVE_DIMENSION_CSS_SUFFIXES, } from './css-value.js';

package/dist/out-tsc/css-value.js

@@ -0,0 +1,301 @@
+import { tokenNameToCssVar } from './css-naming.js';
+/**
+ * Mirrors the `ds/color/rgba` transform: DTCG color values already carry a `hex` field in this
+ * token set (see `tokens/Base.tokens.json`), so this only needs to add an `rgba()` wrapper when
+ * `alpha < 1`.
+ */
+export const colorValueToCss = (value) => {
+    if (typeof value !== 'object' || value === null || !('hex' in value)) {
+        return null;
+    }
+    const { hex, alpha } = value;
+    if (typeof hex !== 'string') {
+        return null;
+    }
+    if (typeof alpha === 'number' && alpha < 1) {
+        const stripped = hex.replace('#', '');
+        const r = parseInt(stripped.substring(0, 2), 16);
+        const g = parseInt(stripped.substring(2, 4), 16);
+        const b = parseInt(stripped.substring(4, 6), 16);
+        return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+    }
+    return hex;
+};
+const ROUND_TOKEN_NAME_MARKERS = ['line-height', 'lineheight', 'opacity'];
+/**
+ * Mirrors `ds/size/round`. Case-insensitive because callers pass different name casings
+ * depending on the platform's name transform - kebab-case for CSS/SCSS (`ds/css/name`), PascalCase
+ * for JS (`ds/js/name`).
+ */
+export const roundNumberValue = (value, tokenName) => {
+    const lowerName = tokenName.toLowerCase();
+    if (ROUND_TOKEN_NAME_MARKERS.some(marker => lowerName.includes(marker))) {
+        return Math.round(value * 10) / 10;
+    }
+    return value;
+};
+// The only categories still $type: "number" — everything unit-bearing (Space, Radius, Border,
+// FontSize, Breakpoint, Container, ...) migrated to $type: "dimension" (see
+// docs/plans/dimension-token-type-plan.md). What's left is always unitless; LineHeight/Opacity
+// round to 1 decimal, ZIndex/Interaction pass through as-is.
+const NUMBER_ONLY_PATH_MARKERS = [
+    'LineHeight',
+    'Opacity',
+    '🌫️ Opacity',
+    'ZIndex',
+    'Z-Index',
+    '🗂️ ZIndex',
+    '🗂️ Z-Index',
+    'Interaction',
+    '✨ Interaction',
+];
+/** Mirrors `ds/size/round`: rounds a LineHeight/Opacity-path number to 1 decimal; passes everything else through unchanged. */
+export const numberValueToCssSize = (value, path) => {
+    if (NUMBER_ONLY_PATH_MARKERS.some(marker => path.includes(marker))) {
+        return Math.round(value * 10) / 10;
+    }
+    return value;
+};
+const CSS_GENERIC_FONT_KEYWORDS = new Set([
+    'inherit',
+    'initial',
+    'unset',
+    'revert',
+    'revert-layer',
+    'serif',
+    'sans-serif',
+    'monospace',
+    'cursive',
+    'fantasy',
+    'system-ui',
+    'ui-serif',
+    'ui-sans-serif',
+    'ui-monospace',
+    'ui-rounded',
+    'math',
+    'emoji',
+    'fangsong',
+]);
+/** Quote iff the name isn't a bare CSS identifier and isn't a generic keyword (e.g. sans-serif, inherit). */
+const needsFontNameQuoting = (name) => !CSS_GENERIC_FONT_KEYWORDS.has(name.toLowerCase()) && /[^a-zA-Z0-9-]/.test(name);
+/**
+ * Joins a fontFamily token's array (or single string, per DTCG) into a CSS-ready font-family
+ * declaration, quoting only entries that need it. Generic keywords and simple identifiers stay
+ * bare — quoting `sans-serif` or `inherit` would make CSS look for a font literally named that,
+ * instead of the real generic fallback/keyword behavior.
+ */
+export const fontFamilyValueToCss = (value) => {
+    const names = Array.isArray(value) ? value : [value];
+    return names.map(name => (needsFontNameQuoting(String(name)) ? `"${name}"` : String(name))).join(', ');
+};
+/**
+ * Turns a dimension token's {value, unit} into a CSS-ready size, e.g. {value: 1.5, unit: 'rem'} ->
+ * '1.5rem'. A trivial passthrough — the source $value already holds the number in its own native
+ * unit (see docs/plans/dimension-token-type-plan.md), so there's no rem<->px conversion to do here;
+ * that only happens at the Figma push/pull boundary, where Figma's px-only reality lives.
+ */
+export const dimensionValueToCss = (value) => {
+    if (typeof value !== 'object' || value === null || !('value' in value) || !('unit' in value)) {
+        return null;
+    }
+    const { value: num, unit } = value;
+    if (typeof num !== 'number' || (unit !== 'px' && unit !== 'rem')) {
+        return null;
+    }
+    return `${num}${unit}`;
+};
+/**
+ * Paths of `$type: "shadow"` tokens that feed the CSS `text-shadow` property rather than
+ * `box-shadow`. Unlike box-shadow, `text-shadow` syntax has no `spread` term — only
+ * `offsetX offsetY [blur] color` is legal — so a `spread` value (even `0`) makes the whole
+ * declaration invalid and the browser silently drops it. These are the only tokens in the set
+ * that back a `text-shadow`; every other `shadow` token backs `box-shadow` and keeps its spread.
+ */
+const TEXT_SHADOW_PATHS = new Set([
+    '🌐 Global.🔤 Font.Shadow.0',
+    '🌐 Global.🔤 Font.Shadow.1',
+    '🔗 Alias.🌓 Shadow.Text',
+    '🔗 Alias.🔤 Text.Shadow.Elevated',
+    '🧩 Component.Heading.Shadow',
+    '🧩 Component.Text.Shadow',
+]);
+const isTextShadowPath = (path) => path !== undefined && TEXT_SHADOW_PATHS.has(path.join('.'));
+/**
+ * One shadow layer -> one CSS box-shadow value, e.g. 'inset 0px 4px 0.25rem 0px rgba(0, 0, 0, 0.15)'.
+ * Omits the `spread` term when `textShadow` is true, since `text-shadow` doesn't support it.
+ */
+const shadowLayerToCss = (layer, textShadow) => {
+    const color = colorValueToCss(layer.color);
+    const offsetX = dimensionValueToCss(layer.offsetX);
+    const offsetY = dimensionValueToCss(layer.offsetY);
+    const blur = dimensionValueToCss(layer.blur);
+    const spread = dimensionValueToCss(layer.spread);
+    if (color === null || offsetX === null || offsetY === null || blur === null || spread === null) {
+        return null;
+    }
+    const spreadTerm = textShadow ? '' : `${spread} `;
+    return `${layer.inset ? 'inset ' : ''}${offsetX} ${offsetY} ${blur} ${spreadTerm}${color}`;
+};
+/**
+ * Turns a shadow token's value (a single shadow object, an array of them, or an empty array for
+ * "no shadow") into a CSS-ready box-shadow (or text-shadow, see TEXT_SHADOW_PATHS) value. Reuses
+ * colorValueToCss/dimensionValueToCss per sub-value rather than Style Dictionary's own built-in
+ * shadow transform, which renders color as `rgb(0% 0% 0% / 0.25)` (colorjs.io's default) instead
+ * of this codebase's `rgba(0, 0, 0, 0.25)`/hex convention — see docs/plans/shadow-token-type-plan.md.
+ */
+export const shadowValueToCss = (value, path) => {
+    const textShadow = isTextShadowPath(path);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return 'none';
+        const layers = value.map(v => shadowLayerToCss(v, textShadow));
+        return layers.every((layer) => layer !== null) ? layers.join(', ') : null;
+    }
+    if (typeof value === 'object' && value !== null) {
+        return shadowLayerToCss(value, textShadow);
+    }
+    return null;
+};
+/**
+ * Turns a border token's {color, width, style} into a CSS-ready border shorthand value, e.g.
+ * '0.125rem solid #d8d8d8'. Reuses colorValueToCss/dimensionValueToCss per sub-value rather than
+ * Style Dictionary's own built-in `border/css/shorthand` transform, which renders each sub-value
+ * as a `var(--ds-*)` reference to its sibling custom property instead of a resolved literal —
+ * diverging from this codebase's convention (see shadowValueToCss, and
+ * docs/plans/border-token-type-plan.md decision 6).
+ *
+ * Unlike shadow's sub-values (always inline literals), border's `color`/`width` are references to
+ * separate real `color`/`dimension` tokens. By the time this transform runs in the actual build
+ * (after `color/css`/`size/rem` have processed those referenced tokens), Style Dictionary has
+ * already substituted their *post-transform* string value (e.g. '#d0d0d0', '0.125rem') into this
+ * composite's $value — so color/width may arrive pre-stringified rather than as raw DTCG objects.
+ * Toky's live preview (via resolvedValueToCss), which calls this directly on raw resolved values
+ * with no prior color/dimension transform, still needs the raw-object path.
+ */
+export const borderValueToCss = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const { color, width, style } = value;
+    const cssColor = typeof color === 'string' ? color : colorValueToCss(color);
+    const cssWidth = typeof width === 'string' ? width : dimensionValueToCss(width);
+    if (cssColor === null || cssWidth === null || typeof style !== 'string')
+        return null;
+    return `${cssWidth} ${style} ${cssColor}`;
+};
+// Suffix appended to a typography token's own CSS var name for each of its 4 longhand custom
+// properties, e.g. `--ds-typography-heading-1-font-family` (see
+// docs/plans/typography-token-type-plan.md decision 5 — 4 separate declarations, never a `font`
+// shorthand). Exported so both the real build's format step and Toky's live preview build the
+// exact same 4 names from one token path.
+export const TYPOGRAPHY_CSS_SUFFIXES = {
+    fontFamily: 'font-family',
+    fontSize: 'font-size',
+    fontWeight: 'font-weight',
+    lineHeight: 'line-height',
+};
+/**
+ * Turns a typography token's {fontFamily, fontSize, fontWeight, lineHeight} into 4 CSS-ready
+ * strings, one per sub-property. Reuses fontFamilyValueToCss/dimensionValueToCss per sub-value,
+ * same reasoning as shadowValueToCss/borderValueToCss.
+ *
+ * fontFamily/fontWeight are always references in this codebase (docs/plans/typography-token-type-
+ * plan.md decision 4), so by the time this runs in the real build (after `ds/font-family`/
+ * `ds/font-weight` have processed the referenced tokens), Style Dictionary has already substituted
+ * their *post-transform* string value — same "may arrive pre-stringified" duality borderValueToCss
+ * documents. fontSize/lineHeight are free literal-or-reference, so either sub-value may arrive as a
+ * raw DTCG value (literal, untouched by any sibling transform) or an already-transformed string
+ * (referenced a real Font.Size or Font.LineHeight token). Toky's live preview (via
+ * computePreviewTokens) always calls this on raw resolved values, never pre-stringified ones.
+ */
+export const typographyValueToCss = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const { fontFamily, fontSize, fontWeight, lineHeight } = value;
+    const cssFontFamily = typeof fontFamily === 'string' ? fontFamily : Array.isArray(fontFamily) ? fontFamilyValueToCss(fontFamily) : null;
+    const cssFontSize = typeof fontSize === 'string' ? fontSize : dimensionValueToCss(fontSize);
+    const cssFontWeight = typeof fontWeight === 'string' ? fontWeight : typeof fontWeight === 'number' ? `${fontWeight}` : null;
+    const cssLineHeight = typeof lineHeight === 'string' ? lineHeight : typeof lineHeight === 'number' ? `${lineHeight}` : null;
+    if (cssFontFamily === null || cssFontSize === null || cssFontWeight === null || cssLineHeight === null)
+        return null;
+    return { fontFamily: cssFontFamily, fontSize: cssFontSize, fontWeight: cssFontWeight, lineHeight: cssLineHeight };
+};
+// The $extensions key a responsive dimension token's breakpoint values live under — see
+// docs/plans/responsive-dimension-token-plan.md. Duplicated (not shared) from
+// apps/toky/src/tokens/types.ts's identical constant, since the two packages have no common
+// module to import it from — same "two independent implementations agree on a vocabulary" pattern
+// as `com.figma.variableId` (see packages/tokens/CONTEXT.md's Figma Sync section).
+export const RESPONSIVE_DIMENSION_EXTENSION_KEY = 'com.helvetia.responsive';
+// Suffix appended to a responsive dimension token's own CSS var name for each of its 3 breakpoint
+// declarations, e.g. `--ds-space-lg-mobile` — matches the -mobile/-tablet/-desktop convention the
+// pre-existing sibling-token responsive pattern already uses (see formatter.ts's
+// `ds/css/variables-responsive`), so that pattern's existing name-suffix-based -device media-query
+// splitting needs zero changes to also handle these (see docs/plans/responsive-dimension-token-
+// plan.md Phase 2's "key design win").
+export const RESPONSIVE_DIMENSION_CSS_SUFFIXES = {
+    mobile: 'mobile',
+    tablet: 'tablet',
+    desktop: 'desktop',
+};
+/**
+ * Turns a responsive dimension token's already-reference-resolved {mobile, tablet, desktop}
+ * breakpoint map into 3 CSS-ready size strings. "Already-resolved" mirrors typographyValueToCss's
+ * own precondition — this doesn't walk $extensions or resolve `{reference}` strings itself;
+ * callers do that first (Toky's flatten.ts via `resolvedResponsive`; formatter.ts's own
+ * dictionary-based lookup for the real build, since Style Dictionary never resolves references
+ * living inside $extensions the way it automatically does for $value — see the plan's "Open
+ * technical question"). Returns null (not a partial object) if any breakpoint is unresolvable,
+ * same "don't half-render" discipline as typographyValueToCss.
+ */
+export const responsiveDimensionValueToCss = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const { mobile, tablet, desktop } = value;
+    const cssMobile = dimensionValueToCss(mobile);
+    const cssTablet = dimensionValueToCss(tablet);
+    const cssDesktop = dimensionValueToCss(desktop);
+    if (cssMobile === null || cssTablet === null || cssDesktop === null)
+        return null;
+    return { mobile: cssMobile, tablet: cssTablet, desktop: cssDesktop };
+};
+/**
+ * Turns a resolved DTCG token value into a CSS-ready string, for the live token preview
+ * (`apps/toky`) to send as a `--ds-*` custom property value. Mirrors the `ds/color/rgba` /
+ * `ds/size/round` / `ds/size/rem` Style Dictionary transforms via the functions above, so the
+ * preview never drifts from what the build actually produces (see ADR-0021). Returns `null` for
+ * value shapes it doesn't recognize, so the caller can skip that token rather than send garbage.
+ *
+ * No `'typography'` branch: unlike every other type here, one typography token maps to 4 CSS
+ * custom properties, not 1 (decision 5) — this function's single-`string`-or-`null` return shape
+ * can't carry that. Callers needing typography go straight to `typographyValueToCss` instead and
+ * fan the result out to 4 `--ds-*-{font-family,font-size,font-weight,line-height}` names
+ * themselves (see `apps/toky/src/tokens/css-preview.ts` and the `ds/css/variables-*` formatters).
+ */
+export const resolvedValueToCss = (value, type, path) => {
+    if (type === 'color') {
+        return colorValueToCss(value);
+    }
+    if (type === 'number' && typeof value === 'number') {
+        const cssVarName = tokenNameToCssVar(path);
+        const rounded = roundNumberValue(value, cssVarName);
+        return `${numberValueToCssSize(rounded, path)}`;
+    }
+    if (type === 'fontWeight' && (typeof value === 'number' || typeof value === 'string')) {
+        return `${Number(value)}`;
+    }
+    if (type === 'fontFamily') {
+        return fontFamilyValueToCss(value);
+    }
+    if (type === 'dimension') {
+        return dimensionValueToCss(value);
+    }
+    if (type === 'shadow') {
+        return shadowValueToCss(value, path);
+    }
+    if (type === 'border') {
+        return borderValueToCss(value);
+    }
+    if (type === 'string' && typeof value === 'string') {
+        return value;
+    }
+    return null;
+};