zabi-components 8.0.0 → 8.1.0

package/dist/create-theme/cli.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * zabi-theme — the command line over createTheme.
+ *
+ *   npx zabi-theme --brand "#0026EA" --out src/lib/brand.generated.css
+ *
+ * The stylesheet goes to --out, or to stdout. Everything else (warnings, the
+ * one-line summary) goes to stderr, so `zabi-theme … > file.css` stays clean.
+ *
+ * Exit codes: 0 done · 1 --strict and a role pair is below WCAG AA · 2 bad usage.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createTheme } from './index.js';
+
+const HELP = `zabi-theme: generate brand tokens for zabi-components
+
+Usage
+  zabi-theme --brand <hex> [--pin] [--accent <hex>] [--pin-accent] [--neutral <hex>]
+             [--neutral-chroma <n>]
+             [--out <file>] [--strict] [--set <token>=<value> ...]
+             [--set-light <token>=<value> ...] [--set-dark <token>=<value> ...]
+
+Options
+  --brand <hex>     Brand colour (required). Builds --zabi-brand-50 … 950.
+  --pin             Put the exact brand colour on primary buttons (see below).
+  --accent <hex>    Second brand colour. Builds --zabi-accent-50 … 950.
+  --pin-accent      The same for the solid accent fill. Needs --accent.
+  --neutral <hex>   Tints the 21-step neutral ramp, --zabi-base-50 … 950.
+  --neutral-chroma <n>
+                    Chroma at the neutral ramp's peak, 0 to 0.1 (OKLCH). Default: the
+                    hue of --neutral at most 0.03. Use 0.04 to 0.06 for a clearly
+                    tinted neutral. Needs --neutral. With it, the ink roles (secondary
+                    button, hover and pressed tints, overlay edge, shadow colour)
+                    follow the neutral ramp instead of staying grey.
+  --out <file>      Write the CSS here. Without it the CSS goes to stdout.
+  --strict          Exit 1 when any role pair is below WCAG AA.
+  --set <t>=<v>     Also write this declaration, e.g. --set "--color-link=var(--color-brand-800)".
+                    Repeatable. It applies in light and dark and is contrast-checked.
+  --set-light <t>=<v>
+                    The same, for light only. Dark keeps the library's own value for that
+                    token: the file restates it under the dark selectors. Repeatable.
+  --set-dark <t>=<v>
+                    The same, for dark only. Repeatable. A token given to --set and to
+                    --set-light or --set-dark: the mode-specific value wins in its mode.
+  --help            Show this text.
+
+Each ramp is built on the library's lightness curve. Your colour supplies hue
+and chroma and is not pinned to a step, so the exact hex may not appear in the
+file; the header says which step is closest.
+
+With --pin the ramp is the same, and the primary action is the exact colour in
+light: the fill, its hover and pressed states, and where they still pass, the
+focus ring and links. The label is white or the ramp's dark end, whichever
+reaches 4.5:1. Dark takes the colour only if it passes there; otherwise dark
+keeps the ramp, and the header says so. A pair that fails is reported, and
+the colour is never moved to make it pass.
+
+Import the file after the theme:
+  @import "zabi-components/theme-only";
+  @import "zabi-components/theme-dark-only";
+  @import "./brand.generated.css";
+`;
+
+const VALUE_OPTIONS = ['brand', 'accent', 'neutral', 'neutral-chroma', 'out'];
+const FLAG_OPTIONS = ['strict', 'help', 'pin', 'pin-accent'];
+
+function usageError(message) {
+    process.stderr.write(`zabi-theme: ${message}\nRun "zabi-theme --help" for usage.\n`);
+    process.exit(2);
+}
+
+function parseArgs(argv) {
+    const options = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '-h') { options.help = true; continue; }
+        if (!arg.startsWith('--')) usageError(`unexpected argument "${arg}"`);
+        const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
+        if (name === 'set' || name === 'set-light' || name === 'set-dark') {
+            // The value is itself a custom property name, so it starts with "--".
+            const pair = inline !== undefined ? inline : argv[(i += 1)];
+            const match = /^(--[\w-]+)\s*[=:]\s*(.+)$/s.exec(pair ?? '');
+            if (!match) usageError(`--${name} needs <token>=<value>, for example --${name} "--color-link=var(--color-brand-800)"`);
+            // `--set` alone stays the flat map; a mode flag adds its own map.
+            const key = name === 'set' ? 'both' : name === 'set-light' ? 'light' : 'dark';
+            options.modes = { ...options.modes, [key]: { ...options.modes?.[key], [match[1]]: match[2].trim() } };
+        } else if (FLAG_OPTIONS.includes(name)) {
+            if (inline !== undefined) usageError(`--${name} takes no value`);
+            options[name] = true;
+        } else if (VALUE_OPTIONS.includes(name)) {
+            const value = inline !== undefined ? inline : argv[(i += 1)];
+            if (value === undefined || value === '' || (inline === undefined && value.startsWith('--'))) {
+                usageError(`--${name} needs a value`);
+            }
+            options[name] = value;
+        } else {
+            usageError(`unknown option "--${name}"`);
+        }
+    }
+    return options;
+}
+
+function parseChroma(text) {
+    const value = Number(text);
+    if (text.trim() === '' || !Number.isFinite(value)) usageError(`--neutral-chroma must be a number such as 0.05 (got "${text}")`);
+    return value;
+}
+
+const options = parseArgs(process.argv.slice(2));
+
+if (options.help) {
+    process.stdout.write(HELP);
+    process.exit(0);
+}
+if (!options.brand) usageError('--brand is required, for example --brand "#0026EA"');
+
+let result;
+try {
+    result = createTheme({
+        brand: options.brand,
+        accent: options.accent,
+        neutral: options.neutral,
+        // Left out when not asked for, so the options are what they always were.
+        ...(options['neutral-chroma'] !== undefined ? { neutralChroma: parseChroma(options['neutral-chroma']) } : {}),
+        // `--set` alone is the flat map, as it always was; a mode flag makes it { light, dark, both }.
+        overrides: options.modes && (options.modes.light || options.modes.dark) ? options.modes : options.modes?.both,
+        // Left out when not asked for, so the options are what they always were.
+        ...(options.pin || options['pin-accent'] ? { pin: { brand: !!options.pin, accent: !!options['pin-accent'] } } : {}),
+    });
+} catch (error) {
+    if (error instanceof TypeError) usageError(error.message.replace(/^zabi-theme: /, ''));
+    throw error;
+}
+
+if (options.out) {
+    const target = path.resolve(options.out);
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, result.css, 'utf8');
+    } catch (error) {
+        usageError(`could not write ${options.out}: ${error.message}`);
+    }
+} else {
+    process.stdout.write(result.css);
+}
+
+const contrast = result.warnings.filter((warning) => warning.type === 'contrast');
+for (const warning of result.warnings) {
+    process.stderr.write(`zabi-theme: warning: ${warning.message}\n`);
+}
+const closest = Object.entries(result.closest)
+    .map(([name, c]) => `${name} closest to step ${c.step}`)
+    .join(', ');
+for (const [name, report] of Object.entries(result.pinned ?? {})) {
+    process.stderr.write(
+        `zabi-theme: ${name} ${report.hex} is pinned in light` +
+            (report.dark.pinned ? ' and in dark.\n' : '; dark keeps the ramp, because the colour fails there.\n'),
+    );
+}
+process.stderr.write(
+    `zabi-theme: ${options.out ? `wrote ${options.out}` : 'done'} (${closest}); ` +
+        (contrast.length === 0
+            ? 'every role pair passes WCAG AA in light and dark.\n'
+            : `${contrast.length} role pair${contrast.length === 1 ? '' : 's'} below WCAG AA.\n`),
+);
+
+if (options.strict && contrast.length > 0) process.exit(1);

package/dist/create-theme/index.d.ts

@@ -0,0 +1,176 @@
+/** A hex colour: `#rgb` or `#rrggbb`, with or without the `#`. */
+export type HexColor = string;
+
+/** A map of custom property names to values. */
+export type TokenMap = Record<string, string>;
+
+/**
+ * Either one map for both modes, or `light`, `dark` and `both` maps. The two
+ * forms may be mixed: a `--token` key beside them counts as `both`.
+ */
+export type Overrides = TokenMap | ({ light?: TokenMap; dark?: TokenMap; both?: TokenMap } & { [token: `--${string}`]: string });
+
+export interface CreateThemeOptions {
+    /**
+     * The brand colour. Supplies hue and chroma for `--zabi-brand-50 … 950`:
+     * primary actions, focus rings, links and brand tints.
+     */
+    brand: HexColor;
+    /** Second brand colour, for `--zabi-accent-50 … 950`. Omitted: the library's citron. */
+    accent?: HexColor;
+    /**
+     * Tints the neutral ramp, `--zabi-base-50 … 950` (21 steps), toward this
+     * hue: text, borders, the page, cards and the dark surface levels. Only the
+     * hue and a little chroma are used. Omitted: the library's greys.
+     */
+    neutral?: HexColor;
+    /**
+     * The OKLCH chroma at the neutral ramp's peak, `0` to `0.1`. Needs
+     * `neutral`, which still supplies the hue. Omitted: the ramp takes the hue
+     * of `neutral` at no more than 0.03 chroma, so it stays a tinted grey. For a
+     * clearly tinted neutral, such as a blue-slate UI, give 0.04 to 0.06. The
+     * profile across the 21 steps is the same; only its peak moves.
+     *
+     * With it, the translucent ink roles follow the neutral ramp instead of
+     * staying grey: `--color-action-secondary` (and `-hover`, `-active`),
+     * `--color-surface-hover`, `--color-surface-active` and
+     * `--color-border-overlay` become `color-mix()` of `--zabi-base-900` (light)
+     * or `--zabi-base-50` (dark) at their usual alphas, and `--shadow-color` is
+     * the ramp's step 900 in light. `--color-overlay` (the modal scrim) stays
+     * black. Dark values are written under the dark selectors, as with `pin`.
+     * Omitted: the output is exactly what it is without the option.
+     *
+     * The contrast check does not evaluate these translucent roles, with or
+     * without the option.
+     */
+    neutralChroma?: number;
+    /**
+     * Extra declarations written after the ramps, for example
+     * `{ "--color-link": "var(--color-brand-800)" }`. They apply in light and in
+     * dark, and take part in the contrast check and in the choice of the "on"
+     * colours.
+     *
+     * Or per mode: `{ light, dark, both }`, each a map of the same shape.
+     * `both` is the flat form (flat keys beside the three also count as `both`).
+     * A token in `light` goes on `:root`, and the file restates the library's
+     * own dark value for it under the dark selectors, so dark does not move; a
+     * token in `dark` is written only under the dark selectors. A token set in
+     * `both` and in a mode takes the mode's value in that mode. The contrast
+     * check uses each mode's own values. A token the library defines no dark
+     * value for (or one you invented) cannot be put back in dark: it stays what
+     * `light` says there unless you also set it in `dark`.
+     *
+     * @example
+     * overrides: { light: { "--color-surface-raised": "#f8faff" } }
+     */
+    overrides?: Overrides;
+    /**
+     * Put the exact colour on the solid fill, where the ramp would use its
+     * step 600. `true` pins the brand: in light, `--color-action-primary` is
+     * the hex you gave, with hover and pressed states derived from it and a
+     * label (white, or the ramp's dark end) that reaches 4.5:1 on all three.
+     * The focus ring and links take the colour too where every guarded pair
+     * still passes, and stay on the ramp where it would not. The ramp itself,
+     * and so every tint and border, is unchanged.
+     *
+     * Dark takes the colour only if nothing guarded fails with it; otherwise
+     * dark keeps the mirrored ramp step, as it does without `pin`.
+     *
+     * A pair that fails with the pinned colour is reported in `warnings`. The
+     * colour is never moved to make it pass.
+     *
+     * `{ accent: true }` does the same for `--color-accent` and needs `accent`.
+     * Omitted or `false`: the output is exactly what it is without the option.
+     */
+    pin?: boolean | { brand?: boolean; accent?: boolean };
+}
+
+/** A role pair below WCAG AA with the generated ramps in place. */
+export interface ContrastWarning {
+    type: 'contrast';
+    /** The pair, as the library's contrast guard names it, e.g. `"link on page"`. */
+    pair: string;
+    mode: 'light' | 'dark';
+    /** Measured ratio, to two decimals. */
+    ratio: number;
+    /** 4.5 for text, 3 for UI parts and focus rings. */
+    required: number;
+    foreground: { token: string; value: string };
+    background: { token: string; value: string };
+    message: string;
+}
+
+/** An input that will not give the ramp its author probably expects. */
+/** What `pin` did with one colour. */
+export interface PinReport {
+    /** The pinned colour, as `#rrggbb`. */
+    hex: string;
+    light: {
+        /** Role groups that took the colour besides the fill: `"focus ring"`, `"link"`, `"accent text"`. */
+        followed: string[];
+        /** Role groups left on the ramp, because the colour fails a guarded pair there. */
+        onRamp: string[];
+        /** Which way hover and pressed go from the fill. */
+        states: 'darker' | 'lighter';
+    };
+    dark: {
+        /** False when the colour fails in dark and dark keeps the ramp. */
+        pinned: boolean;
+        followed: string[];
+        onRamp: string[];
+        states?: 'darker' | 'lighter';
+        /** When not pinned: the pairs that would fail with the colour. */
+        failed?: string[];
+    };
+}
+
+export interface InputWarning {
+    type: 'input';
+    option: 'brand' | 'accent' | 'neutral';
+    message: string;
+}
+
+export type ThemeWarning = ContrastWarning | InputWarning;
+
+/** Where an input colour landed in the ramp built from it. */
+export interface ClosestStep {
+    step: number;
+    hex: string;
+    /** CIELAB ΔE*ab between the input and that step, to one decimal. */
+    deltaE: number;
+    exact: boolean;
+}
+
+export interface CreateThemeResult {
+    /**
+     * The stylesheet: a header comment and one `:root { … }` rule. With `pin`,
+     * `neutralChroma` or `light` / `dark` overrides, two more rules follow, with the dark values of those roles:
+     * `.dark, [data-theme="dark"] { … }` and the same declarations for
+     * `[data-theme="auto"]` inside `@media (prefers-color-scheme: dark)`.
+     */
+    css: string;
+    /** Every declaration of the `:root` rule, name to value, in output order. */
+    tokens: Record<string, string>;
+    /** Only with `pin`, `neutralChroma` or `light` / `dark` overrides: every declaration of the dark rules. */
+    darkTokens?: Record<string, string>;
+    /** Only with `pin`: what was pinned and which roles took the colour. */
+    pinned?: { brand?: PinReport; accent?: PinReport };
+    /** Contrast failures and input notes. Empty when everything passes. */
+    warnings: ThemeWarning[];
+    closest: { brand: ClosestStep; accent?: ClosestStep; neutral?: ClosestStep };
+}
+
+/**
+ * Builds the ramps for a brand on the library's lightness curve and checks
+ * every guarded role pair in light and dark. Deterministic: the same options
+ * give the same bytes.
+ *
+ * @throws {TypeError} when `brand` is missing, a colour is not a hex value, or `neutralChroma` is not a number from 0 to 0.1 or is given without `neutral`.
+ */
+export function createTheme(options: CreateThemeOptions): CreateThemeResult;
+export default createTheme;
+
+/** The steps of a chromatic ramp: 50, 100 … 900, 950. */
+export const RAMP_STEPS: number[];
+/** The 21 steps of the neutral ramp, half steps included. */
+export const BASE_STEPS: number[];