@eos-ui/tokens 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eos contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @eos-ui/tokens
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The design tokens behind Eos (colour, spacing, radius, shadow, type, size, motion, layering) as CSS custom properties, typed values, and `defineTheme()`, which builds a theme from a brand colour and checks every promised contrast pair.
+
+```bash
+npm install @eos-ui/tokens
+```
+
+```ts
+import { defineTheme } from "@eos-ui/tokens";
+
+const theme = defineTheme({ name: "clinic", brand: "#8a2be2", accent: "#2e7d32", radius: "round" });
+theme.issues; // contrast pairs that fail (empty when sound)
+theme.css(); // the theme as CSS custom properties, for the server
+theme.apply(document.documentElement); // or set them in the browser
+```
+
+```css
+/* the default tokens as a stylesheet */
+@import "@eos-ui/tokens/tokens.css";
+```
+
+All variables are prefixed `--e-` (`--e-primary`, `--e-space-4`). Documentation: https://eos.dame.gg. MIT licensed.
+
+## Inputs
+
+`defineTheme()` takes 15 inputs and emits every token. Any token can also be set by name in `tokens`, which wins over everything derived. `name` labels the theme (`data-e-theme`), and `strict` throws on a contrast failure instead of listing it in `issues`.
+
+| Input                                                  | Derives                                                                                         |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `brand`, `accent`                                      | `primary`, `secondary`, their tints and `surface-tint`                                          |
+| `danger`, `warning`                                    | `danger`, `on-danger`, `danger-soft`; `warning-strong`, `warning-soft`                          |
+| `background`, `surface`, `foreground`                  | the grounds, `ink`, `muted`, `border`, `border-strong`; a dark surface lifts the action colours |
+| `fonts`, `radius`                                      | `font-sans`, `font-mono`; `radius-sm` to `radius-lg`                                            |
+| `textScale`, `spaceScale`                              | `text-xs` to `text-4xl`; `space-1` to `space-8` (1 is the default)                              |
+| `strokes` `{ hair, focus }`                            | `stroke-hair`, `stroke-edge`, `stroke-focus`, `focus-gap`, `focus-gap-field`                    |
+| `motion` `"default" \| "snappy" \| "gentle" \| "none"` | `duration-tap`, `duration-move`, `easing-out`                                                   |
+| `elevation` `"outline" \| "lifted" \| "bold"`          | `edge`, `well`, `float`; shadow tint follows `background`                                       |
+| `controlHeight`                                        | `control-height`, `chip-height`                                                                 |
+
+`derivedFrom`, `constants` and `inputTokens` say which input drives each token and which tokens are fixed. Fixed tokens include `depth`, the thickness of a raised or pressed edge.

package/dist/color.d.ts

@@ -0,0 +1,22 @@
+/** Colour maths for contrast checks and brand derivation. Hex in, hex out; sRGB with WCAG 2.x relative luminance and OKLCH for lightness steps. */
+export type RGB = [number, number, number];
+export declare function parseHex(hex: string): RGB;
+export declare function toHex([r, g, b]: RGB): string;
+export declare function luminance(hex: string): number;
+/** WCAG 2.x contrast ratio, 1 to 21. */
+export declare function contrast(a: string, b: string): number;
+export interface OKLCH {
+    l: number;
+    c: number;
+    h: number;
+}
+export declare function toOklch(hex: string): OKLCH;
+export declare function fromOklch({ l, c, h }: OKLCH): string;
+/** The colour nearest `hex` (same hue and chroma, stepping lightness) whose contrast with `against` reaches `target`. Darkens when `against` is light, lightens when it is dark. */
+export declare function reachContrast(hex: string, against: string, target: number): string;
+/** A very light tint of `hex`'s hue, for soft backgrounds. */
+export declare function tint(hex: string, lightness?: number, chroma?: number): string;
+/** The colour nearest `hex` (same hue and chroma, lightness stepped toward `against`) that still holds a contrast of `target` with `against`. Softens as far as the target allows; returns `hex` unchanged when it is already under the target. */
+export declare function settleContrast(hex: string, against: string, target: number): string;
+/** `hex` moved to OKLCH lightness `l`, optionally with a new chroma and hue, clamped to the sRGB gamut. */
+export declare function withLightness(hex: string, l: number, chroma?: number, hue?: number): string;

package/dist/color.js

@@ -0,0 +1,98 @@
+/** Colour maths for contrast checks and brand derivation. Hex in, hex out; sRGB with WCAG 2.x relative luminance and OKLCH for lightness steps. */
+export function parseHex(hex) {
+    const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        throw new Error(`Not a hex colour: ${hex}`);
+    let h = m[1];
+    if (h.length === 3)
+        h = [...h].map((c) => c + c).join("");
+    return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+export function toHex([r, g, b]) {
+    return ("#" +
+        [r, g, b]
+            .map((v) => Math.round(Math.min(255, Math.max(0, v)))
+            .toString(16)
+            .padStart(2, "0"))
+            .join(""));
+}
+const lin = (c) => {
+    const s = c / 255;
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+};
+const gam = (c) => 255 * (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+export function luminance(hex) {
+    const [r, g, b] = parseHex(hex).map(lin);
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** WCAG 2.x contrast ratio, 1 to 21. */
+export function contrast(a, b) {
+    const la = luminance(a);
+    const lb = luminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+export function toOklch(hex) {
+    const [r, g, b] = parseHex(hex).map(lin);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+    const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+    const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+    return { l: L, c: Math.hypot(A, B), h: (Math.atan2(B, A) * 180) / Math.PI };
+}
+export function fromOklch({ l, c, h }) {
+    const A = c * Math.cos((h * Math.PI) / 180);
+    const B = c * Math.sin((h * Math.PI) / 180);
+    const l_ = (l + 0.3963377774 * A + 0.2158037573 * B) ** 3;
+    const m_ = (l - 0.1055613458 * A - 0.0638541728 * B) ** 3;
+    const s_ = (l - 0.0894841775 * A - 1.291485548 * B) ** 3;
+    const r = 4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_;
+    const g = -1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_;
+    const bl = -0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_;
+    return toHex([gam(r), gam(g), gam(bl)]);
+}
+/** The colour nearest `hex` (same hue and chroma, stepping lightness) whose contrast with `against` reaches `target`. Darkens when `against` is light, lightens when it is dark. */
+export function reachContrast(hex, against, target) {
+    const start = toOklch(hex);
+    const darken = luminance(against) > 0.4;
+    let best = hex;
+    for (let step = 0; step <= 100; step++) {
+        const l = darken ? start.l - step * 0.01 : start.l + step * 0.01;
+        if (l < 0 || l > 1)
+            break;
+        best = fromOklch({ ...start, l });
+        if (contrast(best, against) >= target)
+            return best;
+    }
+    return best;
+}
+/** A very light tint of `hex`'s hue, for soft backgrounds. */
+export function tint(hex, lightness = 0.955, chroma = 0.025) {
+    const { h } = toOklch(hex);
+    return fromOklch({ l: lightness, c: chroma, h });
+}
+/** The colour nearest `hex` (same hue and chroma, lightness stepped toward `against`) that still holds a contrast of `target` with `against`. Softens as far as the target allows; returns `hex` unchanged when it is already under the target. */
+export function settleContrast(hex, against, target) {
+    const start = toOklch(hex);
+    const goal = toOklch(against).l;
+    const dir = goal >= start.l ? 1 : -1;
+    let best = hex;
+    if (contrast(hex, against) < target)
+        return best;
+    for (let step = 1; step <= 400; step++) {
+        const l = start.l + dir * step * 0.0025;
+        if ((dir > 0 && l > goal) || (dir < 0 && l < goal))
+            break;
+        const next = fromOklch({ ...start, l });
+        if (contrast(next, against) < target)
+            break;
+        best = next;
+    }
+    return best;
+}
+/** `hex` moved to OKLCH lightness `l`, optionally with a new chroma and hue, clamped to the sRGB gamut. */
+export function withLightness(hex, l, chroma, hue) {
+    const o = toOklch(hex);
+    return fromOklch({ l: Math.min(1, Math.max(0, l)), c: chroma ?? o.c, h: hue ?? o.h });
+}

package/dist/generated/defaults.d.ts

@@ -0,0 +1,85 @@
+export declare const defaults: {
+    readonly "brand-blue": "#2c95b4";
+    readonly "brand-green": "#72c451";
+    readonly primary: "#17586d";
+    readonly "on-primary": "#ffffff";
+    readonly secondary: "#2b5c1b";
+    readonly "on-secondary": "#ffffff";
+    readonly "secondary-soft": "#e8f5e1";
+    readonly danger: "#962019";
+    readonly "on-danger": "#ffffff";
+    readonly "danger-soft": "#fbe9e7";
+    readonly "warning-strong": "#714a00";
+    readonly "warning-soft": "#fdf3dc";
+    readonly background: "#ffffff";
+    readonly surface: "#ffffff";
+    readonly "surface-tint": "#eaf4f8";
+    readonly ink: "#000000";
+    readonly scrim: "rgb(11 40 52 / 0.55)";
+    readonly muted: "#515151";
+    readonly border: "#7f8f96";
+    readonly "border-strong": "#767676";
+    readonly "focus-ring": "var(--e-ink)";
+    readonly "focus-field": "var(--e-primary)";
+    readonly "space-1": "4px";
+    readonly "space-2": "8px";
+    readonly "space-3": "12px";
+    readonly "space-4": "16px";
+    readonly "space-6": "24px";
+    readonly "space-8": "32px";
+    readonly "radius-sm": "4px";
+    readonly "radius-md": "8px";
+    readonly "radius-lg": "16px";
+    readonly "radius-pill": "999px";
+    readonly edge: "0 0 0 1px #7f8f96";
+    readonly well: "inset 0 2px 0 0 rgba(0, 0, 0, 0.1)";
+    readonly float: "0 0 0 1px #7f8f96, 0 1px 2px 0px rgba(36, 36, 36, 0.08), 0 4px 8px -2px rgba(36, 36, 36, 0.1), 0 12px 24px -6px rgba(36, 36, 36, 0.14), 0 24px 48px -12px rgba(36, 36, 36, 0.18)";
+    readonly "text-xs": "12px";
+    readonly "text-sm": "14px";
+    readonly "text-md": "16px";
+    readonly "text-lg": "18px";
+    readonly "text-xl": "20px";
+    readonly "text-2xl": "24px";
+    readonly "text-3xl": "30px";
+    readonly "text-4xl": "36px";
+    readonly "control-height": "48px";
+    readonly "chip-height": "24px";
+    readonly measure: "62ch";
+    readonly "stroke-hair": "1px";
+    readonly "stroke-card": "1px";
+    readonly "stroke-edge": "1.5px";
+    readonly "stroke-focus": "2px";
+    readonly "focus-gap": "2px";
+    readonly "focus-gap-field": "-1px";
+    readonly depth: "2px";
+    readonly "duration-tap": "80ms";
+    readonly "duration-move": "220ms";
+    readonly "easing-out": "cubic-bezier(0.2, 0.8, 0.2, 1)";
+    readonly "z-raised": "1";
+    readonly "z-sticky": "5";
+    readonly "z-tooltip": "55";
+    readonly "z-modal": "40";
+    readonly "z-popover": "45";
+    readonly "z-toast": "50";
+    readonly "font-sans": "\"Jost\", Futura, \"Century Gothic\", \"Avenir Next\", system-ui, sans-serif";
+    readonly "font-mono": "\"Spline Sans Mono\", ui-monospace, Menlo, Consolas, monospace";
+};
+export declare const groups: {
+    readonly color: readonly ["brand-blue", "brand-green", "primary", "on-primary", "secondary", "on-secondary", "secondary-soft", "danger", "on-danger", "danger-soft", "warning-strong", "warning-soft", "background", "surface", "surface-tint", "ink", "scrim", "muted", "border", "border-strong", "focus-ring", "focus-field"];
+    readonly spacing: readonly ["space-1", "space-2", "space-3", "space-4", "space-6", "space-8"];
+    readonly radius: readonly ["radius-sm", "radius-md", "radius-lg", "radius-pill"];
+    readonly shadow: readonly ["edge", "well", "float"];
+    readonly fontSize: readonly ["text-xs", "text-sm", "text-md", "text-lg", "text-xl", "text-2xl", "text-3xl", "text-4xl"];
+    readonly size: readonly ["control-height", "chip-height", "measure"];
+    readonly stroke: readonly ["stroke-hair", "stroke-card", "stroke-edge", "stroke-focus", "focus-gap", "focus-gap-field", "depth"];
+    readonly duration: readonly ["duration-tap", "duration-move"];
+    readonly easing: readonly ["easing-out"];
+    readonly zIndex: readonly ["z-raised", "z-sticky", "z-tooltip", "z-modal", "z-popover", "z-toast"];
+    readonly font: readonly ["font-sans", "font-mono"];
+};
+export declare const usage: Record<string, string>;
+export declare const derivedFrom: Record<string, string>;
+export declare const constants: string[];
+export declare const inputTokens: string[];
+export type TokenName = keyof typeof defaults;
+export declare const colorNames: ReadonlySet<string>;

package/dist/generated/defaults.js

@@ -0,0 +1,279 @@
+// Generated by scripts/generate.mjs from src/tokens.json. Do not edit.
+export const defaults = {
+    "brand-blue": "#2c95b4",
+    "brand-green": "#72c451",
+    "primary": "#17586d",
+    "on-primary": "#ffffff",
+    "secondary": "#2b5c1b",
+    "on-secondary": "#ffffff",
+    "secondary-soft": "#e8f5e1",
+    "danger": "#962019",
+    "on-danger": "#ffffff",
+    "danger-soft": "#fbe9e7",
+    "warning-strong": "#714a00",
+    "warning-soft": "#fdf3dc",
+    "background": "#ffffff",
+    "surface": "#ffffff",
+    "surface-tint": "#eaf4f8",
+    "ink": "#000000",
+    "scrim": "rgb(11 40 52 / 0.55)",
+    "muted": "#515151",
+    "border": "#7f8f96",
+    "border-strong": "#767676",
+    "focus-ring": "var(--e-ink)",
+    "focus-field": "var(--e-primary)",
+    "space-1": "4px",
+    "space-2": "8px",
+    "space-3": "12px",
+    "space-4": "16px",
+    "space-6": "24px",
+    "space-8": "32px",
+    "radius-sm": "4px",
+    "radius-md": "8px",
+    "radius-lg": "16px",
+    "radius-pill": "999px",
+    "edge": "0 0 0 1px #7f8f96",
+    "well": "inset 0 2px 0 0 rgba(0, 0, 0, 0.1)",
+    "float": "0 0 0 1px #7f8f96, 0 1px 2px 0px rgba(36, 36, 36, 0.08), 0 4px 8px -2px rgba(36, 36, 36, 0.1), 0 12px 24px -6px rgba(36, 36, 36, 0.14), 0 24px 48px -12px rgba(36, 36, 36, 0.18)",
+    "text-xs": "12px",
+    "text-sm": "14px",
+    "text-md": "16px",
+    "text-lg": "18px",
+    "text-xl": "20px",
+    "text-2xl": "24px",
+    "text-3xl": "30px",
+    "text-4xl": "36px",
+    "control-height": "48px",
+    "chip-height": "24px",
+    "measure": "62ch",
+    "stroke-hair": "1px",
+    "stroke-card": "1px",
+    "stroke-edge": "1.5px",
+    "stroke-focus": "2px",
+    "focus-gap": "2px",
+    "focus-gap-field": "-1px",
+    "depth": "2px",
+    "duration-tap": "80ms",
+    "duration-move": "220ms",
+    "easing-out": "cubic-bezier(0.2, 0.8, 0.2, 1)",
+    "z-raised": "1",
+    "z-sticky": "5",
+    "z-tooltip": "55",
+    "z-modal": "40",
+    "z-popover": "45",
+    "z-toast": "50",
+    "font-sans": "\"Jost\", Futura, \"Century Gothic\", \"Avenir Next\", system-ui, sans-serif",
+    "font-mono": "\"Spline Sans Mono\", ui-monospace, Menlo, Consolas, monospace"
+};
+export const groups = {
+    "color": [
+        "brand-blue",
+        "brand-green",
+        "primary",
+        "on-primary",
+        "secondary",
+        "on-secondary",
+        "secondary-soft",
+        "danger",
+        "on-danger",
+        "danger-soft",
+        "warning-strong",
+        "warning-soft",
+        "background",
+        "surface",
+        "surface-tint",
+        "ink",
+        "scrim",
+        "muted",
+        "border",
+        "border-strong",
+        "focus-ring",
+        "focus-field"
+    ],
+    "spacing": [
+        "space-1",
+        "space-2",
+        "space-3",
+        "space-4",
+        "space-6",
+        "space-8"
+    ],
+    "radius": [
+        "radius-sm",
+        "radius-md",
+        "radius-lg",
+        "radius-pill"
+    ],
+    "shadow": [
+        "edge",
+        "well",
+        "float"
+    ],
+    "fontSize": [
+        "text-xs",
+        "text-sm",
+        "text-md",
+        "text-lg",
+        "text-xl",
+        "text-2xl",
+        "text-3xl",
+        "text-4xl"
+    ],
+    "size": [
+        "control-height",
+        "chip-height",
+        "measure"
+    ],
+    "stroke": [
+        "stroke-hair",
+        "stroke-card",
+        "stroke-edge",
+        "stroke-focus",
+        "focus-gap",
+        "focus-gap-field",
+        "depth"
+    ],
+    "duration": [
+        "duration-tap",
+        "duration-move"
+    ],
+    "easing": [
+        "easing-out"
+    ],
+    "zIndex": [
+        "z-raised",
+        "z-sticky",
+        "z-tooltip",
+        "z-modal",
+        "z-popover",
+        "z-toast"
+    ],
+    "font": [
+        "font-sans",
+        "font-mono"
+    ]
+};
+export const usage = {
+    "brand-blue": "The logo blue, exact. Decorative and brand surfaces only (the cover, illustrations). Never carries text: black on it is 6.1:1 but only APCA Lc 42, and white on it is 3.5:1. Use `primary` for anything interactive.",
+    "brand-green": "The logo green, exact. Decorative and brand surfaces only. Never carries text: white on it is 2.2:1.",
+    "primary": "Action blue: the fill of the primary Button and of every selected or checked state (selected day, page, segment, time slot, checkbox, switch), with `on-primary` (white) text at 7.9:1. Also small blue text and links on `surface` and `surface-tint` (7.9:1 and 7.1:1), the information tone, and the filled part of progress and loading bars. A deep teal derived from the logo blue (`brand-blue`) so that white text passes WCAG AAA.",
+    "on-primary": "White text and icons on `primary` fills (7.9:1).",
+    "secondary": "Action green: the fill of the secondary Button (a positive action), with `on-secondary` (white) text at 7.9:1. Also the success tone's text and outline. Derived from the logo green (`brand-green`).",
+    "on-secondary": "White text and icons on `secondary` fills (7.9:1).",
+    "secondary-soft": "Tinted backdrop of a paid chip or notice.",
+    "danger": "Danger red: the fill of the danger Button, with `on-danger` (white) text at 8.3:1. Also the danger tone's text and outline, error text and invalid input edges, on `surface` (8.3:1) and `danger-soft` (7.1:1). Derived from the `danger` input of `defineTheme`: deepened until `on-danger` text reaches 7:1.",
+    "on-danger": "White text and icons on `danger` fills (8.3:1).",
+    "danger-soft": "Tinted backdrop of a danger chip, stamp, notice or toast.",
+    "warning-strong": "Small amber text on `surface` (7.8:1) and `warning-soft` (7.1:1): AAA. Derived from the `warning` input of `defineTheme`.",
+    "warning-soft": "Tinted backdrop of a warning chip, stamp, notice or toast.",
+    "background": "The page ground: the colour behind everything, painted by the app shell and the page. White by default, the same as `surface`. The `background` input of `defineTheme` sets it; when only `surface` is given the page ground follows the surface.",
+    "surface": "What sits on the page: cards, fields, popovers, dialogs, panels and headers. Every screen starts on white. The `surface` input of `defineTheme` sets it, and with it derives `surface-tint`, the soft tone backdrops and, on a dark surface, the light action colours.",
+    "surface-tint": "The surface's second step: wells, hovered rows, table headers, footers, empty slots and the information tone's tint. Derived from `surface` by shifting its lightness 0.045 toward the foreground (0.06 the other way on a dark surface) in the brand hue. About 1.1:1 against white, so never a boundary on its own.",
+    "ink": "Body copy, headings and icons on `surface`, `surface-tint`, `primary`, `secondary`, `danger` and the soft tints. Also the neutral chip colour. Set by the `foreground` input of `defineTheme`, which also drives `muted`, `border` and `border-strong`.",
+    "scrim": "The dimmed backdrop behind a dialog or drawer.",
+    "muted": "Secondary text, kickers and captions on `surface` (7.9:1) and `surface-tint` (7.1:1): AAA. Close to the grey of the logo's tagline. From a `foreground` input, `ink` softened toward `surface` until it just holds 7:1.",
+    "border": "Hairlines between rows, the outline of cards and popovers, and the underside of clickable rows. 3.4:1 on `surface` and 3.0:1 on `surface-tint`, so every edge is visible on white. Control edges use `border-strong`. From a `foreground` input, `ink` softened toward `surface` until it just holds 3.4:1.",
+    "border-strong": "Input, checkbox and other control borders on `surface` (4.5:1, above the 3:1 floor). From a `foreground` input, `ink` softened toward `surface` until it just holds 4.5:1.",
+    "focus-ring": "Solid 2px focus outline with 2px offset on buttons, links, tabs, rows and every control that is not a text input; 3:1 or better on every surface and fill.",
+    "focus-field": "The focus outline and edge of text inputs and everything built on them (Field, Select, Combobox, DatePicker, NumberField, SearchBar, OtpField). Primary teal, 7.9:1 on `surface`. An invalid input keeps `danger`. Buttons and links use `focus-ring`.",
+    "space-1": "Icon-to-text gaps, gap inside a chip.",
+    "space-2": "Tight stacks, chip padding.",
+    "space-3": "Control padding, compact rows.",
+    "space-4": "Card padding, default gap, side gutter.",
+    "space-6": "Between related groups and parts of a statement.",
+    "space-8": "Section padding.",
+    "radius-sm": "Stamps and tags.",
+    "radius-md": "Buttons, inputs, cards, notices.",
+    "radius-lg": "Dialogs.",
+    "radius-pill": "Chips and round buttons, echoing the logo's round caps.",
+    "edge": "The flat outline of everything that is not clickable: cards, summaries, the SearchBar. A 1px `border` ring (3.4:1 on white), no depth.",
+    "well": "Inputs, meters and empty slots pressed into the page.",
+    "float": "Popovers, menus and toasts: the surfaces that float over the page. Four stacked, low-opacity shadows of growing size read as one soft shadow, so it never looks like a hard black edge. Nothing in the flow of the page uses it.",
+    "text-xs": "Kickers, chips, stamps, micro labels and other mono labels. Never smaller.",
+    "text-sm": "Secondary copy, table cells, helper text, small buttons.",
+    "text-md": "Body copy, input text and button labels. Inputs must stay at 16px or more so phones do not zoom in on focus.",
+    "text-lg": "The deck: a one-sentence reading of a statement. Calendar headings.",
+    "text-xl": "Card and panel titles (h3).",
+    "text-2xl": "Section titles (h2).",
+    "text-3xl": "The one amount a statement leads with.",
+    "text-4xl": "Page titles (h1).",
+    "control-height": "Height of every control that can be tapped: buttons, inputs, selects, date fields, slots, and one row of a multi-select. One height everywhere, so a Button beside an input lines up and a field never shifts when it changes type.",
+    "chip-height": "Height of a Chip or a small Stamp.",
+    "measure": "Longest comfortable line of copy.",
+    "stroke-hair": "Dividers and the rule between rows.",
+    "stroke-card": "The outline of a card, panel, table or other container that is not clickable, and of a chip or stamp. Follows the hairline; a bold elevation draws it at 2px.",
+    "stroke-edge": "The outline of a control, chip or stamp.",
+    "stroke-focus": "The focus outline.",
+    "focus-gap": "Space between a button or link and its focus outline.",
+    "focus-gap-field": "Space between a text input and its focus outline: a 1px overlap, so the outline sits over the border with no seam.",
+    "depth": "How far a raised or pressed edge reaches. A button, a statement row and a selected time slot stand out by this much of extra thickness on the bottom edge; a pressed button, the selected item of a list or segmented control and a notice are pressed in by the same amount on the top edge.",
+    "duration-tap": "Hover and press feedback.",
+    "duration-move": "Things that move: a progress fill, a drawer.",
+    "easing-out": "Fast start, soft landing. The only easing in the system.",
+    "z-raised": "A part that must sit above its sibling inside one component.",
+    "z-sticky": "Sticky table headers and columns.",
+    "z-tooltip": "Tooltip bubbles: above everything, including dialogs, popovers and toasts.",
+    "z-modal": "Dialogs and drawers with their scrim.",
+    "z-popover": "Popovers, menus and option lists. Above modals, so a Select inside a Dialog opens over it.",
+    "z-toast": "The toast region: above modals and popovers."
+};
+export const derivedFrom = {
+    "font-sans": "fonts",
+    "font-mono": "fonts",
+    "brand-blue": "brand",
+    "brand-green": "accent",
+    "primary": "brand,surface",
+    "on-primary": "surface",
+    "secondary": "accent,surface",
+    "on-secondary": "surface",
+    "secondary-soft": "accent,surface",
+    "danger": "danger,surface",
+    "on-danger": "danger,surface",
+    "danger-soft": "danger,surface",
+    "warning-strong": "warning,surface",
+    "warning-soft": "warning,surface",
+    "background": "background,surface",
+    "surface": "surface",
+    "surface-tint": "surface,brand",
+    "ink": "foreground,surface",
+    "scrim": "surface",
+    "muted": "foreground,surface",
+    "border": "foreground,surface",
+    "border-strong": "foreground,surface",
+    "focus-ring": "foreground",
+    "focus-field": "brand",
+    "space-1": "spaceScale",
+    "space-2": "spaceScale",
+    "space-3": "spaceScale",
+    "space-4": "spaceScale",
+    "space-6": "spaceScale",
+    "space-8": "spaceScale",
+    "radius-sm": "radius",
+    "radius-md": "radius",
+    "radius-lg": "radius",
+    "edge": "elevation,strokes,foreground,background",
+    "well": "elevation,surface",
+    "float": "elevation,strokes,foreground,surface,background",
+    "text-xs": "textScale",
+    "text-sm": "textScale",
+    "text-md": "textScale",
+    "text-lg": "textScale",
+    "text-xl": "textScale",
+    "text-2xl": "textScale",
+    "text-3xl": "textScale",
+    "text-4xl": "textScale",
+    "control-height": "controlHeight",
+    "chip-height": "controlHeight",
+    "stroke-hair": "strokes",
+    "stroke-card": "strokes,elevation",
+    "stroke-edge": "strokes",
+    "stroke-focus": "strokes",
+    "focus-gap": "strokes",
+    "focus-gap-field": "strokes",
+    "duration-tap": "motion",
+    "duration-move": "motion",
+    "easing-out": "motion"
+};
+export const constants = ["radius-pill", "measure", "depth", "z-raised", "z-sticky", "z-tooltip", "z-modal", "z-popover", "z-toast"];
+export const inputTokens = ["font-sans", "font-mono", "brand-blue", "brand-green", "background", "surface", "ink", "control-height", "stroke-hair", "stroke-focus"];
+export const colorNames = new Set(["brand-blue", "brand-green", "primary", "on-primary", "secondary", "on-secondary", "secondary-soft", "danger", "on-danger", "danger-soft", "warning-strong", "warning-soft", "background", "surface", "surface-tint", "ink", "scrim", "muted", "border", "border-strong", "focus-ring", "focus-field"]);

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { defineTheme, checkContrast, LAYER_ORDER, defaults, groups } from "./theme.js";
+export type { Theme, ThemeInput, MotionPreset, ElevationPreset, TokenValues, ContrastIssue, CssOptions, TokenName, } from "./theme.js";
+export { contrast, luminance, reachContrast, settleContrast, withLightness, tint, toOklch, fromOklch, parseHex, toHex, } from "./color.js";
+export { usage, derivedFrom, constants, inputTokens } from "./generated/defaults.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { defineTheme, checkContrast, LAYER_ORDER, defaults, groups } from "./theme.js";
+export { contrast, luminance, reachContrast, settleContrast, withLightness, tint, toOklch, fromOklch, parseHex, toHex, } from "./color.js";
+export { usage, derivedFrom, constants, inputTokens } from "./generated/defaults.js";

package/dist/theme.d.ts

@@ -0,0 +1,83 @@
+import { defaults, groups, type TokenName } from "./generated/defaults.js";
+export type TokenValues = Partial<Record<TokenName, string>>;
+export type MotionPreset = "default" | "snappy" | "gentle" | "none";
+export type ElevationPreset = "outline" | "lifted" | "bold";
+export interface ThemeInput {
+    /** Identifies the theme. It becomes the value of `data-e-theme` when the theme is scoped to an element. */
+    name?: string;
+    /** The brand colour. The deep action colour (`primary`) is derived from it so white text on it reaches 7:1; the tinted ground follows. */
+    brand?: string;
+    /** A second brand colour for positive actions (`secondary`), derived the same way. */
+    accent?: string;
+    /** The page ground: the colour behind everything. Sets `background`. When `surface` is given and this is not, the page ground follows the surface. */
+    background?: string;
+    /** Anything that sits on the page: cards, fields, popovers, panels. Sets `surface` and derives `surface-tint` (the second ground) and the soft tone backdrops from its lightness. A dark surface also switches the action colours and their `on-*` text to light variants. */
+    surface?: string;
+    /** Text and lines. Sets `ink` and derives `muted` (softened until it just holds 7:1 on the surface), `border` (3.4:1) and `border-strong` (4.5:1). Without it, a given `surface` picks black or white. */
+    foreground?: string;
+    /** The destructive action colour. Derives `danger` (deepened until `on-danger` text reaches 7:1, and 4.5:1 on the surface and on `danger-soft`), `on-danger` and `danger-soft`. */
+    danger?: string;
+    /** The caution colour. Derives `warning-strong` (4.5:1 or more on the surface and on `warning-soft`) and `warning-soft`. */
+    warning?: string;
+    /** Font stacks for body and mono text. Fonts are never bundled: load them yourself or import `@eos-ui/vue/fonts.css`. */
+    fonts?: {
+        sans?: string;
+        mono?: string;
+    };
+    /** Corner style: a preset or explicit values. */
+    radius?: "sharp" | "default" | "round" | {
+        sm?: string;
+        md?: string;
+        lg?: string;
+    };
+    /** Multiplier for the type scale, `text-xs` to `text-4xl`. 1 is the default scale; non-finite or non-positive values are ignored. */
+    textScale?: number;
+    /** Multiplier for the spacing scale, `space-1` to `space-8`. 1 is the default scale; non-finite or non-positive values are ignored. */
+    spaceScale?: number;
+    /** Line weights in px. `hair` sets `stroke-hair` and `stroke-edge` (1.5 times it); `focus` sets `stroke-focus`, `focus-gap` (the same) and `focus-gap-field` (a 1px overlap: a field's focus outline sits over its border). */
+    strokes?: {
+        hair?: number;
+        focus?: number;
+    };
+    /** How state changes feel: sets `duration-tap`, `duration-move` and `easing-out`. */
+    motion?: MotionPreset;
+    /** How depth is drawn: sets `edge`, `well` and `float` from the border, ink and hairline. `outline` is flat rings, `lifted` adds soft drops, `bold` uses heavy rings and a hard offset shadow. */
+    elevation?: ElevationPreset;
+    /** Height in px of every tappable control. Sets `control-height` and derives `chip-height` at half of it, rounded to an even number. */
+    controlHeight?: number;
+    /** Anything else, by token name. Wins over everything derived. */
+    tokens?: TokenValues;
+    /** Throw on a contrast failure instead of reporting it in `issues`. */
+    strict?: boolean;
+}
+export interface ContrastIssue {
+    pair: [string, string];
+    ratio: number;
+    min: number;
+    role: string;
+}
+export interface CssOptions {
+    /** Selector the tokens apply to. Default `:root`. */
+    selector?: string;
+    /** Wrap in `@layer e.tokens`, the layer the components expect. Default true. */
+    layer?: boolean;
+    /** Prepend the layer order statement and a generated-file comment. */
+    header?: boolean;
+}
+export interface Theme {
+    name: string;
+    /** Every token, by name without the leading `--`. */
+    tokens: Record<string, string>;
+    /** Failures of the contrast pairs the system promises (text 4.5, non-text 3). Empty when the theme is sound. */
+    issues: ContrastIssue[];
+    /** The theme as CSS custom properties on a selector, in the token layer. Render it into `<head>` on the server. */
+    css(options?: CssOptions): string;
+    /** Sets the tokens on an element as inline custom properties and marks it `data-e-theme`. Browser only. */
+    apply(el?: HTMLElement): void;
+}
+/** Cascade order of the library. Later layers win, and each layer only builds on the ones before it. */
+export declare const LAYER_ORDER = "e.reset, e.tokens, e.base, e.primitives, e.blocks, e.controls, e.composites, e.containers, e.account, e.page";
+export declare function checkContrast(tokens: Record<string, string>): ContrastIssue[];
+export declare function defineTheme(input?: ThemeInput): Theme;
+export { defaults, groups };
+export type { TokenName };