zabi-components 8.1.0 → 9.0.0

package/dist/create-theme/index.js

@@ -46,7 +46,7 @@ import {
     toOklch,
     toLab,
 } from './lib/ramp-math.js';
-import { resolveTokenColor } from './lib/resolve.js';
+import { resolveTokenColor, resolveTokenPaint, compositeOver, dimBackdrop, backdropBrightness } from './lib/resolve.js';
 
 /** The neutral ramp's 21 steps. */
 export const BASE_STEPS = [
@@ -252,28 +252,28 @@ function triplet(hex) {
 }
 
 /**
- * Light and dark declarations for the ink roles over a neutral ramp. Roles the
- * author overrides themselves are left out, so their override stays what both
- * modes show.
+ * Light and dark declarations for the ink roles over a neutral ramp. A role
+ * the author overrides in a mode (or in `both`) is left out for that mode, so
+ * their override is what it shows. The other mode keeps the ramp's ink: a role
+ * set in `light` alone is still the tinted mix in dark, not the library's grey.
  */
-function inkTokens(ramp, overrides) {
+function inkTokens(ramp, modes) {
     const light = {};
     const dark = {};
+    const setIn = (mode, role) => role in modes[mode] || role in modes.both;
     const mix = (step, percent) => `color-mix(in srgb, var(--zabi-base-${step}) ${percent}%, transparent)`;
     for (const role of INK_ROLES) {
-        if (role in overrides) continue;
         const lightPercent = alphaPercent(data.light[role]);
-        if (lightPercent !== null) light[role] = mix(900, lightPercent);
+        if (lightPercent !== null && !setIn('light', role)) light[role] = mix(900, lightPercent);
+        if (setIn('dark', role)) continue;
         const darkPercent = alphaPercent(data.darkOnly[role]);
         // A role the dark theme already points at a ramp step (the overlay edge)
         // keeps that: the light value on `:root` would otherwise win there too.
         if (darkPercent !== null) dark[role] = mix(50, darkPercent);
         else if (data.darkOnly[role] !== undefined) dark[role] = data.darkOnly[role];
     }
-    if (!('--shadow-color' in overrides)) {
-        light['--shadow-color'] = triplet(ramp[900]);
-        dark['--shadow-color'] = '0 0 0';
-    }
+    if (!setIn('light', '--shadow-color')) light['--shadow-color'] = triplet(ramp[900]);
+    if (!setIn('dark', '--shadow-color')) dark['--shadow-color'] = '0 0 0';
     return { light, dark };
 }
 
@@ -324,14 +324,37 @@ function themeMaps(tokens, darkTokens = {}) {
     };
 }
 
-function checkPairs(tokens, darkTokens = {}, extraPairs = []) {
+function checkPairs(tokens, darkTokens = {}, extraPairs = [], { gradients = true } = {}) {
     const maps = themeMaps(tokens, darkTokens);
     const warnings = [];
     let checked = 0;
     for (const mode of ['light', 'dark']) {
         for (const pair of [...data.pairs, ...extraPairs]) {
-            const bg = resolveTokenColor(maps[mode], pair.bg);
-            const fg = resolveTokenColor(maps[mode], pair.fg);
+            // `only`: a pair about one mode (the dark field is a translucent step; light's is opaque).
+            if (pair.only && pair.only !== mode) continue;
+            // The control veils are settled last (settleControlGradients), so a
+            // choice made before then must not be steered by them.
+            if (!gradients && pair.gradient) continue;
+            const behind = pair.behind ? (typeof pair.behind === 'string' ? pair.behind : pair.behind[mode]) : null;
+            let bg = resolveTokenColor(maps[mode], pair.bg);
+            if (behind) {
+                // A material: its fill (an alpha paint) laid over what is behind it.
+                const paint = resolveTokenPaint(maps[mode], pair.bg);
+                const flat = resolveTokenColor(maps[mode], behind);
+                // A material's filter dims what is behind it (D137); other `behind` pairs are not filtered.
+                const backdrop = flat && pair.material ? dimBackdrop(flat, backdropBrightness(maps[mode])) : flat;
+                bg = paint && backdrop ? backdrop : null;
+                // `layers`: the same paint stacked, each laid over the last (nested translucent cards).
+                for (let layer = 0; layer < (pair.layers ?? 1) && bg; layer += 1) bg = compositeOver(paint, bg);
+            }
+            let fg = resolveTokenColor(maps[mode], pair.fg);
+            if (behind && pair.fgPaint) {
+                // `fgPaint`: the foreground is a fill too (a pressed field against the resting one), laid over the same backdrop.
+                const fgPaint = resolveTokenPaint(maps[mode], pair.fg);
+                let under = resolveTokenColor(maps[mode], behind);
+                for (let layer = 0; layer < (pair.layers ?? 1) && under && fgPaint; layer += 1) under = compositeOver(fgPaint, under);
+                fg = fgPaint ? under : null;
+            }
             if (!bg || !fg) continue; // an alpha tint: not one flat colour
             checked += 1;
             const ratio = contrast(bg, fg);
@@ -347,7 +370,7 @@ function checkPairs(tokens, darkTokens = {}, extraPairs = []) {
                 required: pair.min,
                 foreground: { token: pair.fg, value: fg },
                 background: { token: pair.bg, value: bg },
-                message: `${mode} · ${pair.name}: ${fg} on ${bg} is ${ratio}:1, needs ${pair.min}:1 (${pair.fg} on ${pair.bg})`,
+                message: `${mode} · ${pair.name}: ${fg} on ${bg} is ${ratio}:1, needs ${pair.min}:1 (${pair.fg} on ${pair.bg}${behind ? ` over ${behind}` : ''})`,
             });
         }
     }
@@ -370,14 +393,18 @@ const ON_ROLES = {
 /**
  * The label for a solid fill: white or the ramp's dark end, whichever reaches
  * 4.5:1 on the fill, its hover and its active step. The library's own choice
- * for the mode is tried first; if neither passes, the better one is kept and
+ * for the role and mode is tried first (white, except the accent in dark); if neither passes, the better one is kept and
  * the pair check reports it.
  */
 function chooseOn(name, mode, tokens, darkTokens = {}) {
     const { role, fills } = ON_ROLES[name];
     const knob = mode === 'dark' ? `--zabi-on-${name}-dark` : `--zabi-on-${name}`;
     const darkEnd = `var(--zabi-${name}-950)`;
-    const candidates = mode === 'dark' ? [darkEnd, WHITE] : [WHITE, darkEnd];
+    // White first for the brand in both modes: the library's dark primary is the
+    // same mid step as light. A pale dark primary (an app's own override, or
+    // darkPrimary: 'mirror') fails white and keeps the ramp's dark end. The
+    // accent's dark fill is the light step, so its dark end still goes first.
+    const candidates = mode === 'dark' && name === 'accent' ? [darkEnd, WHITE] : [WHITE, darkEnd];
     let best = null;
     for (const value of candidates) {
         const map = themeMaps({ ...tokens, [knob]: value }, darkTokens)[mode];
@@ -393,6 +420,36 @@ function chooseOn(name, mode, tokens, darkTokens = {}) {
     return [knob, best.value];
 }
 
+/* ---------- dark primary ---------- */
+
+/**
+ * What `darkPrimary: 'mirror'` writes under the dark selectors: the 8.1 dark
+ * fills, which are the mirrored semantic steps (pale in dark), the danger
+ * aliases with the label they had, and the lighten-heavy control veil made for
+ * a pale fill. The label knob is chosen by chooseOn like any other.
+ */
+const MIRRORED_DARK = {
+    '--color-action-primary': 'var(--color-brand-600)',
+    '--color-action-primary-hover': 'var(--color-brand-700)',
+    '--color-action-primary-active': 'var(--color-brand-800)',
+    '--color-action-danger': 'var(--color-error-600)',
+    '--color-action-danger-hover': 'var(--color-error-700)',
+    '--color-action-danger-active': 'var(--color-error-800)',
+    '--color-action-danger-text': 'var(--color-error-50)',
+    '--gradient-control-top-strength': '22%',
+    '--gradient-control-bottom-strength': '6%',
+};
+
+function readDarkPrimary(value) {
+    if (value === undefined || value === null) return 'brand';
+    if (value !== 'brand' && value !== 'mirror') {
+        throw new TypeError(
+            `${TOOL}: darkPrimary must be "brand" or "mirror" (got ${typeof value === 'string' ? `"${value}"` : JSON.stringify(value)})`,
+        );
+    }
+    return value;
+}
+
 /* ---------- pinning ---------- */
 
 /**
@@ -508,10 +565,15 @@ const failing = (warnings, mode) => new Set(warnings.filter((w) => w.mode === mo
  * 3:1, and no label makes that a button. So dark takes the colour only when nothing guarded fails with it,
  * and otherwise keeps what it has without `pin`: the mirrored ramp step.
  */
-function pinColour(name, colour, tokens, earlierDark, userOverrides, extraPairs, skip) {
+function pinColour(name, colour, tokens, earlierDark, userOverrides, extraPairs, skip, darkPrimary = 'brand') {
     const roles = PIN_ROLES[name];
     const keep = (group) => Object.fromEntries(Object.entries(group).filter(([role]) => !skip.has(role)));
-    const libraryDark = (role) => data.darkOnly[role] ?? data.light[role];
+    // What dark has for a role without the pin: what the file already says for
+    // dark (the mirrored fills under darkPrimary: 'mirror'), then the library.
+    const libraryDark = (role) => earlierDark[role] ?? data.darkOnly[role] ?? data.light[role];
+    // The brand's dark fill is the light recipe (the same steps, darker states)
+    // unless it is mirrored; the accent's dark fill is still the pale step.
+    const recipe = (mode) => (mode === 'dark' && name === 'brand' && darkPrimary === 'brand' ? 'light' : mode);
     const light = {};
     const dark = {};
     const knobs = {};
@@ -522,7 +584,7 @@ function pinColour(name, colour, tokens, earlierDark, userOverrides, extraPairs,
         const root = { ...tokens, ...knobs, ...lightRoles, ...userOverrides };
         const darkRule = { ...earlierDark, ...darkRoles };
         const [knob, value] = chooseOn(name, mode, root, darkRule);
-        const result = checkPairs({ ...root, [knob]: value }, darkRule, extraPairs);
+        const result = checkPairs({ ...root, [knob]: value }, darkRule, extraPairs, { gradients: false });
         return { knob, value, failures: failing(result.warnings, mode) };
     };
     const noWorse = (after, before) => [...after].every((pair) => before.has(pair));
@@ -535,8 +597,8 @@ function pinColour(name, colour, tokens, earlierDark, userOverrides, extraPairs,
      */
     const bestFill = (mode, tryWith) => {
         let best = null;
-        for (const direction of SHADE_DIRECTIONS[mode]) {
-            const states = shades(colour, mode, direction);
+        for (const direction of SHADE_DIRECTIONS[recipe(mode)]) {
+            const states = shades(colour, recipe(mode), direction);
             if (!states) continue;
             const result = tryWith(keep(roles.fill(colour.hex, states)));
             if (!best || result.failures.size < best.result.failures.size) best = { direction, states, result };
@@ -600,13 +662,151 @@ function pinColour(name, colour, tokens, earlierDark, userOverrides, extraPairs,
     return { light, dark: { ...restated(), ...dark }, knobs, report };
 }
 
+/* ---------- links that follow the primary ---------- */
+
+/** What the app's overrides say a role is in `mode`, or undefined. */
+const overrideIn = (modes, mode, role) => modes[mode][role] ?? modes.both[role];
+
+/**
+ * Sets roles for one mode, answering a light value with the library's own
+ * dark one so that dark does not move (as overrideMaps does for `light`).
+ */
+function setRoles(tokens, darkTokens, mode, roles) {
+    if (mode === 'light') {
+        const dark = { ...darkTokens };
+        for (const role of Object.keys(roles)) if (!(role in dark)) dark[role] = data.darkOnly[role] ?? data.light[role];
+        return { tokens: { ...tokens, ...roles }, darkTokens: dark };
+    }
+    return { tokens, darkTokens: { ...darkTokens, ...roles } };
+}
+
+/** The pairs failing in `mode` with these tokens. */
+const failingIn = (tokens, darkTokens, mode) => failing(checkPairs(tokens, darkTokens).warnings, mode);
+
+/**
+ * `--color-link` follows an overridden primary, as a pinned colour's link
+ * does (PIN_ROLES): the library's link is the brand's step 700 because step
+ * 600, its primary, does not hold 4.5:1 as text on tints. An app that sets
+ * its own primary (a deeper step, say) otherwise has links beside buttons in
+ * a different blue. In each mode where the app sets `--color-action-primary`
+ * and not `--color-link`, link is that primary and, if the app set a primary
+ * hover too, link-hover is that (otherwise the ramp's link-hover stays: the
+ * library's hover is a step the app's primary does not use), but only if no
+ * guarded pair fails that did not fail before; otherwise the ramp's link
+ * stays in that mode.
+ * An explicit `--color-link` always wins.
+ */
+function followPrimaryWithLink(tokens, darkTokens, modes) {
+    for (const mode of ['light', 'dark']) {
+        const primary = overrideIn(modes, mode, '--color-action-primary');
+        if (primary === undefined || overrideIn(modes, mode, '--color-link') !== undefined) continue;
+        const hover = overrideIn(modes, mode, '--color-action-primary-hover');
+        const before = failingIn(tokens, darkTokens, mode);
+        for (const roles of [
+            ...(hover === undefined ? [] : [{ '--color-link': primary, '--color-link-hover': hover }]),
+            { '--color-link': primary },
+        ]) {
+            const next = setRoles(tokens, darkTokens, mode, roles);
+            const after = failingIn(next.tokens, next.darkTokens, mode);
+            if ([...after].every((pair) => before.has(pair))) {
+                ({ tokens, darkTokens } = next);
+                break;
+            }
+        }
+    }
+    return { tokens, darkTokens };
+}
+
+/**
+ * The edge of the Progress track (`--color-progress-track-border`) is the field
+ * edge by default, because the default track is the field fill and does not
+ * reach 3:1 against the page or a card (WCAG 1.4.11). An app that overrides
+ * the track so that it does reach 3:1 against both, in a mode, does not need
+ * an edge there: it is written as `transparent` for that mode, as the link
+ * follows an overridden primary. An edge the app sets itself, in either
+ * mode or both, is its decision, and is never moved (a `transparent` of its
+ * own draws no warning: a pair with no flat colour is skipped).
+ */
+const PROGRESS_TRACK = '--color-progress-track';
+const PROGRESS_TRACK_EDGE = '--color-progress-track-border';
+const MIN_TRACK_AGAINST_SURFACE = 3;
+
+function settleProgressTrackEdge(tokens, darkTokens, modes) {
+    for (const mode of ['light', 'dark']) {
+        if (overrideIn(modes, mode, PROGRESS_TRACK) === undefined) continue;
+        if (overrideIn(modes, mode, PROGRESS_TRACK_EDGE) !== undefined) continue;
+        const maps = themeMaps(tokens, darkTokens)[mode];
+        const track = resolveTokenColor(maps, PROGRESS_TRACK);
+        if (!track) continue; // an alpha tint: not one flat colour
+        const surfaces = ['--color-surface-base', '--color-surface-raised'].map((role) => resolveTokenColor(maps, role));
+        if (surfaces.some((surface) => !surface || contrast(track, surface) < MIN_TRACK_AGAINST_SURFACE)) continue;
+        ({ tokens, darkTokens } = setRoles(tokens, darkTokens, mode, { [PROGRESS_TRACK_EDGE]: 'transparent' }));
+    }
+    return { tokens, darkTokens };
+}
+
+/* ---------- control gradients ---------- */
+
+/** The strongest veil tried: the library's own cap. */
+const MAX_VEIL = 14;
+
+/**
+ * The veil of a solid control is a light stop on top and a dark one at the
+ * bottom, over the control's own fill. The library's light default darkens
+ * only (top 0, bottom 14%): a darker fill can only help a light label. An app
+ * whose fill takes a DARK label (a light accent, an amber) loses contrast to
+ * that darkening, so for each veil and each mode: if every pair passes, nothing
+ * is written; if not, the veil is flipped to lighten-only (the top at the
+ * largest whole percent up to 14 that passes, the bottom 0), or the other way
+ * if the label is the light one; if neither direction passes, both are 0%,
+ * which is no veil. A strength the app set itself is never moved: the pair
+ * check reports it. Primary and danger share one veil, so they flip together.
+ */
+function settleControlGradients(tokens, darkTokens, modes) {
+    const veils = new Map();
+    for (const control of data.controlGradients) {
+        const key = control.strengths.join('|');
+        if (!veils.has(key)) veils.set(key, { strengths: control.strengths, controls: [] });
+        veils.get(key).controls.push(control);
+    }
+    for (const mode of ['light', 'dark']) {
+        for (const { strengths, controls } of veils.values()) {
+            if (strengths.some((role) => overrideIn(modes, mode, role) !== undefined)) continue;
+            const failed = (t, d) =>
+                [...failingIn(t, d, mode)].filter((pair) => controls.some((control) => pair.startsWith(`${control.name} gradient `)));
+            if (failed(tokens, darkTokens).length === 0) continue;
+            const [top, bottom] = strengths;
+            const maps = themeMaps(tokens, darkTokens)[mode];
+            const labelIsDark = controls.some((control) => {
+                const label = resolveTokenColor(maps, control.on);
+                const fill = resolveTokenColor(maps, control.fills[0][1]);
+                return label && fill && luminance(label) < luminance(fill);
+            });
+            const directions = labelIsDark ? ['lighten', 'darken'] : ['darken', 'lighten'];
+            let chosen = { [top]: '0%', [bottom]: '0%' };
+            search: for (const direction of directions) {
+                for (let percent = MAX_VEIL; percent >= 1; percent -= 1) {
+                    const roles = direction === 'lighten' ? { [top]: `${percent}%`, [bottom]: '0%' } : { [top]: '0%', [bottom]: `${percent}%` };
+                    const next = setRoles(tokens, darkTokens, mode, roles);
+                    if (failed(next.tokens, next.darkTokens).length === 0) {
+                        chosen = roles;
+                        break search;
+                    }
+                }
+            }
+            ({ tokens, darkTokens } = setRoles(tokens, darkTokens, mode, chosen));
+        }
+    }
+    return { tokens, darkTokens };
+}
+
 /* ---------- output ---------- */
 
 function rampTokens(name, ramp, steps) {
     return Object.fromEntries(steps.map((step) => [`--zabi-${name}-${step}`, ramp[step]]));
 }
 
-function render({ inputs, closest, tokens, darkTokens, pinned, neutralChroma, contrastWarnings, checked }) {
+function render({ inputs, closest, tokens, darkTokens, pinned, neutralChroma, darkPrimary, contrastWarnings, checked }) {
     const describeInput = (name) =>
         inputs[name]
             ? `${inputs[name]}  closest step ${closest[name].step} (${closest[name].hex}, ` +
@@ -621,6 +821,12 @@ function render({ inputs, closest, tokens, darkTokens, pinned, neutralChroma, co
         ` *   brand    ${describeInput('brand')}`,
         ` *   accent   ${describeInput('accent')}`,
         ` *   neutral  ${describeInput('neutral')}`,
+        ...(darkPrimary === 'mirror'
+            ? [
+                  ' *   dark primary: mirror. The primary and danger fills use the mirrored (pale) steps in',
+                  ' *   dark, as in 8.1, with the label and control veil chosen for them.',
+              ]
+            : []),
         ...(neutralChroma === undefined
             ? []
             : [
@@ -679,8 +885,8 @@ function pinnedNotes(pinned) {
             if (report.dark.followed.length) lines.push(` *   dark, also this colour: ${list(report.dark.followed)}`);
             if (report.dark.onRamp.length) lines.push(` *   dark, left on the ramp: ${list(report.dark.onRamp)}`);
         } else {
-            lines.push(' *   dark: NOT pinned. The colour fails there, so dark keeps the mirrored ramp step, as it');
-            lines.push(' *   does without pin. With the colour, these would fail:');
+            lines.push(' *   dark: NOT pinned. The colour fails there, so dark keeps the ramp step it has');
+            lines.push(' *   without pin. With the colour, these would fail:');
             for (const pair of report.dark.failed) lines.push(` *     - ${pair}`);
             lines.push(' *   To force a dark value all the same, write the role in your own dark rule after this file.');
         }
@@ -689,7 +895,7 @@ function pinnedNotes(pinned) {
 }
 
 /**
- * @param {{ brand: string, accent?: string, neutral?: string, neutralChroma?: number, overrides?: Record<string, string> | { light?: Record<string, string>, dark?: Record<string, string>, both?: Record<string, string> } & Record<string, unknown>, pin?: boolean | { brand?: boolean, accent?: boolean } }} options
+ * @param {{ brand: string, accent?: string, neutral?: string, neutralChroma?: number, overrides?: Record<string, string> | { light?: Record<string, string>, dark?: Record<string, string>, both?: Record<string, string> } & Record<string, unknown>, pin?: boolean | { brand?: boolean, accent?: boolean }, darkPrimary?: 'brand' | 'mirror' }} options
  */
 export function createTheme(options) {
     if (options === null || typeof options !== 'object') {
@@ -699,10 +905,6 @@ export function createTheme(options) {
         throw new TypeError(`${TOOL}: brand is required, for example { brand: "#0026EA" }`);
     }
     const modes = readOverrides(options.overrides ?? {});
-    // Roles the app sets in any mode are left to it: no ink role or pin replaces them.
-    const overridden = {};
-    for (const map of [modes.both, modes.light, modes.dark]) Object.assign(overridden, map);
-
     const inputs = { brand: parseHex(options.brand, 'brand') };
     if (options.accent !== undefined && options.accent !== null) inputs.accent = parseHex(options.accent, 'accent');
     if (options.neutral !== undefined && options.neutral !== null) inputs.neutral = parseHex(options.neutral, 'neutral');
@@ -721,6 +923,7 @@ export function createTheme(options) {
         neutralChroma = value;
     }
 
+    const darkPrimary = readDarkPrimary(options.darkPrimary);
     const pin = readPin(options.pin);
     if (pin.accent && !inputs.accent) throw new TypeError(`${TOOL}: pin.accent needs an accent colour`);
     const pinning = pin.brand || pin.accent;
@@ -747,7 +950,7 @@ export function createTheme(options) {
                 message:
                     `${name} ${colour.hex} is not in the ramp built from it: the nearest step is ` +
                     `${closest[name].step} (${closest[name].hex}, ΔE ${closest[name].deltaE.toFixed(1)}). ` +
-                    'The ramp keeps its hue on the library\'s lightness curve; fills use step 600 in light and 400 in dark.',
+                    'The ramp keeps its hue on the library\'s lightness curve; fills use step 600 in light and in dark (400 in dark with darkPrimary: "mirror").',
             });
         }
         tokens = { ...tokens, ...rampTokens(name, ramp, RAMP_STEPS) };
@@ -766,12 +969,21 @@ export function createTheme(options) {
         tokens = { ...tokens, ...rampTokens('base', ramp, BASE_STEPS) };
         if (neutralChroma !== undefined) {
             // Opt-in: without it these roles are the library's grey tints, as before.
-            const ink = inkTokens(ramp, overridden);
+            const ink = inkTokens(ramp, modes);
             tokens = { ...tokens, ...ink.light };
             darkTokens = ink.dark;
         }
     }
 
+    // darkPrimary: 'mirror' writes the 8.1 dark fills under the dark selectors,
+    // except for a role the app sets itself in dark or in both modes.
+    if (darkPrimary === 'mirror') {
+        for (const [role, value] of Object.entries(MIRRORED_DARK)) {
+            if (role in modes.dark || role in modes.both) continue;
+            darkTokens = { ...darkTokens, [role]: value };
+        }
+    }
+
     // Overrides take part in choosing the labels, and are written last. Each
     // mode sees its own values.
     for (const name of ['brand', 'accent']) {
@@ -790,7 +1002,7 @@ export function createTheme(options) {
     for (const name of ['brand', 'accent']) {
         if (!pin[name]) continue;
         const own = overrideMaps(modes, tokens, darkTokens);
-        const result = pinColour(name, described[name], tokens, { ...darkTokens, ...own.dark }, own.root, extraPairs, own.skip);
+        const result = pinColour(name, described[name], tokens, { ...darkTokens, ...own.dark }, own.root, extraPairs, own.skip, darkPrimary);
         tokens = { ...tokens, ...result.knobs, ...result.light };
         darkTokens = { ...darkTokens, ...result.dark };
         pinned[name] = result.report;
@@ -799,11 +1011,16 @@ export function createTheme(options) {
     tokens = { ...tokens, ...own.root };
     darkTokens = { ...darkTokens, ...own.dark };
 
+    // What the generator settles once the app's own values are in place.
+    if (!pin.brand) ({ tokens, darkTokens } = followPrimaryWithLink(tokens, darkTokens, modes));
+    ({ tokens, darkTokens } = settleProgressTrackEdge(tokens, darkTokens, modes));
+    ({ tokens, darkTokens } = settleControlGradients(tokens, darkTokens, modes));
+
     const { warnings: contrastWarnings, checked } = checkPairs(tokens, darkTokens, extraPairs);
     warnings.push(...contrastWarnings);
 
-    const css = render({ inputs, closest, tokens, darkTokens, pinned: pinning ? pinned : null, neutralChroma, contrastWarnings, checked });
-    const hasDark = pinning || neutralChroma !== undefined || Object.keys(own.dark).length > 0;
+    const css = render({ inputs, closest, tokens, darkTokens, pinned: pinning ? pinned : null, neutralChroma, darkPrimary, contrastWarnings, checked });
+    const hasDark = pinning || neutralChroma !== undefined || Object.keys(darkTokens).length > 0;
     return {
         css,
         tokens,

package/dist/create-theme/lib/resolve.js

@@ -10,6 +10,8 @@
  * Supported, because it is all the stylesheet uses for a flat colour:
  *   - `var(--token)` and `var(--token, fallback)`, anywhere in a value
  *   - `color-mix(in srgb, <opaque> p%, <opaque>)` (either or both percentages)
+ *   - `color-mix(in srgb, <colour> p%, transparent)` and `rgba()`, as a colour
+ *     with an alpha (resolveTokenPaint), for the materials' fills
  * Anything else (`rgba()`, a mix with `transparent`) is returned as written,
  * for the caller to composite over a surface or to skip.
  */
@@ -139,3 +141,98 @@ export function resolveTokenColor(map, token) {
     const value = resolveTokenValue(map, token);
     return value && HEX.test(value) ? value.toLowerCase() : null;
 }
+
+/* ---------- colours with an alpha ---------- */
+
+/** `#rrggbb` + alpha, or null. `transparent` is alpha 0. */
+function parsePaint(text) {
+    const value = text.trim();
+    if (value === 'transparent') return { hex: '#000000', alpha: 0 };
+    if (HEX.test(value)) return { hex: value.toLowerCase().length === 4 ? toHex(parseHex(value)) : value.toLowerCase(), alpha: 1 };
+    const rgba = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)$/.exec(value);
+    if (rgba) {
+        const a = rgba[4] === undefined ? 1 : rgba[4].endsWith('%') ? Number.parseFloat(rgba[4]) / 100 : Number(rgba[4]);
+        return { hex: toHex([rgba[1], rgba[2], rgba[3]].map(Number)), alpha: a };
+    }
+    if (value.startsWith('color-mix(')) return mixPaint(value);
+    return null;
+}
+
+/**
+ * `color-mix(in srgb, A p%, B q%)` where either side may be `transparent` or
+ * carry an alpha. Premultiplied, as the browser mixes; a sum under 100% leaves
+ * the result that much more transparent. Null when it cannot be reduced.
+ */
+function mixPaint(value) {
+    const match = /^color-mix\(([\s\S]*)\)$/.exec(value.trim());
+    if (!match) return null;
+    const [space, first, second] = splitTopLevel(match[1]);
+    if (!space || !first || !second || space.replace(/\s+/g, ' ') !== 'in srgb') return null;
+    const operand = (text) => {
+        const t = text.trim();
+        let percent = null;
+        let colourText = t;
+        const trailing = /^([\s\S]*\S)\s+(-?[\d.]+)%$/.exec(t);
+        const leading = /^(-?[\d.]+)%\s+([\s\S]*)$/.exec(t);
+        if (trailing) [, colourText, percent] = trailing;
+        else if (leading) [, percent, colourText] = leading;
+        const paint = parsePaint(colourText);
+        return paint ? { paint, percent: percent === null ? null : Number(percent) } : null;
+    };
+    const a = operand(first);
+    const b = operand(second);
+    if (!a || !b) return null;
+    let pa = a.percent;
+    let pb = b.percent;
+    if (pa === null && pb === null) { pa = 50; pb = 50; }
+    else if (pa === null) pa = 100 - pb;
+    else if (pb === null) pb = 100 - pa;
+    const total = pa + pb;
+    if (total <= 0) return null;
+    const wa = (pa / total) * a.paint.alpha;
+    const wb = (pb / total) * b.paint.alpha;
+    const alpha = wa + wb;
+    if (alpha === 0) return { hex: '#000000', alpha: 0 };
+    const ca = parseHex(a.paint.hex);
+    const cb = parseHex(b.paint.hex);
+    return {
+        hex: toHex(ca.map((channel, i) => (channel * wa + cb[i] * wb) / alpha)),
+        alpha: alpha * Math.min(1, total / 100),
+    };
+}
+
+/**
+ * What a token paints, as `{ hex, alpha }`: a flat colour (alpha 1), a
+ * `color-mix()` with `transparent`, or an `rgba()` tint. Null when the token
+ * is not declared or is not one of those.
+ */
+export function resolveTokenPaint(map, token) {
+    if (map[token] === undefined) return null;
+    const substituted = substituteVars(map, map[token], new Set([token]));
+    return substituted === null ? null : parsePaint(substituted);
+}
+
+/** The colour `paint` makes laid source-over on the opaque `backdropHex`, as hex. */
+export function compositeOver(paint, backdropHex) {
+    const under = parseHex(backdropHex);
+    const over = parseHex(paint.hex);
+    return toHex(over.map((channel, i) => channel * paint.alpha + under[i] * (1 - paint.alpha)));
+}
+
+/**
+ * The backdrop a material's filter hands to its fill: `brightness()` multiplies
+ * the sRGB-encoded channels, so each channel of `backdropHex` is scaled by
+ * `factor` (a number; 1 is the identity). Material pairs only.
+ */
+export function dimBackdrop(backdropHex, factor) {
+    const f = Number(factor);
+    if (!Number.isFinite(f) || f === 1) return backdropHex;
+    return toHex(parseHex(backdropHex).map((channel) => channel * f));
+}
+
+/** The mode's `--material-backdrop-brightness` as a number; 1 when it is not declared or not a number. */
+export function backdropBrightness(map) {
+    const value = resolveTokenValue(map, '--material-backdrop-brightness');
+    const n = value === null ? NaN : Number(value);
+    return Number.isFinite(n) ? n : 1;
+}