@cssints/ramp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+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,155 @@
-# Temporary Holding Version
+# @cssints/ramp
 
-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.
+OKLCH colour ramps for [cssints](../../README.md), computed at build time. `ramp(base, options)` returns plain DTCG data
+(a colour group, steps `"1"` to `"N"`, each a hex colour in sRGB) that you pass to `createTokens` yourself, and
+`overrides(ramp)` turns a ramp into the override object of `createGlobalTheme`. The package has no runtime and no
+`scope()`: like the sets of [@cssints/tokens](../tokens/README.md), a ramp is data, so it goes under any group name, sits
+beside other tokens in one call, and its steps get `@property` rules, themes and `check.contrast` from cssints.
+
+```ts
+// tokens.ts
+import { createGlobalTheme, createTokens, media } from "cssints" with { type: "cssints" };
+import { overrides, ramp } from "@cssints/ramp";
+
+const ratios = [1.2, 1.5, 3, 4.5, 7] as const;
+
+export const t = createTokens({
+  bg: { $type: "color", $value: "#ffffff" },
+  blue: ramp("#2563eb", { mode: "contrast", ratios, background: "#ffffff" }),
+  gray: ramp("#6b7280", { mode: "lightness", steps: 9 }),
+});
+
+// the same ratios on the dark background, under the same condition as it
+createGlobalTheme(t, media("(prefers-color-scheme: dark)"), {
+  bg: "#111111",
+  blue: overrides(ramp("#2563eb", { mode: "contrast", ratios, background: "#111111" })),
+});
+```
+
+```ts
+// text.ts
+import { bg, check, cn, color } from "cssints" with { type: "cssints" };
+
+import { t } from "./tokens.ts";
+
+check.contrast(t.blue._3, t.bg, { min: 3 }); // borders, large text
+check.contrast(t.blue._4, t.bg, { min: 4.5 }); // body text, light and dark
+export const text = cn(color(t.blue._4), bg(t.bg));
+```
+
+The sheet of `text.ts`:
+
+```css
+@property --bg {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: #ffffff;
+}
+@property --blue-4 {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: #356fec;
+}
+@layer _.k {
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #111111;
+      --blue-1: #041e59;
+      --blue-2: #092d7c;
+      --blue-3: #1855db;
+      --blue-4: #3d76ed;
+      --blue-5: #719df2;
+    }
+  }
+}
+@layer _.a {
+  ._1od4w7v {
+    color: var(--blue-4);
+  }
+  ._q77new {
+    background-color: var(--bg);
+  }
+}
+```
+
+## Modes
+
+Every step keeps the base's OKLCH hue and its chroma _relative to the sRGB gamut_ (nutelch's idea): the base's chroma
+over the most chroma sRGB holds at the base's lightness and hue. A step at another lightness takes the same share of the
+most sRGB holds there, so a vivid base stays vivid near its hue's cusp, thins out towards white and black, and every step
+is in sRGB by construction (the hex is the 8-bit rounding of an in-gamut colour, never a clipped one). A grey base gives a
+neutral ramp. The base itself need not be a step.
+
+- **`{ mode: "lightness", steps, lightness? }`**: `steps` colours spaced evenly in OKLCH lightness, from
+  `lightness[0]` to `lightness[1]` (default `[0.97, 0.25]`, lightest first). `#2563eb` with 9 steps: `#f1f5fe`,
+  `#c6d8f9`, `#9cbbf5`, `#719df2`, `#467cee`, `#1a59e6`, `#1143b2`, `#092f81`, `#041b53`.
+- **`{ mode: "contrast", ratios, background }`** (Leonardo's idea): one step per ratio, in the order given. A step's
+  lightness is searched (bisection, on the hex it outputs) for the colour nearest the background whose WCAG 2 ratio
+  against it is at or above the target. The steps go darker on a light background and lighter on a dark one (the side
+  with more room). `#2563eb` with `[1.2, 1.5, 3, 4.5, 7]`:
+
+  | Background | 1              | 2              | 3              | 4              | 5              |
+  | ---------- | -------------- | -------------- | -------------- | -------------- | -------------- |
+  | `#ffffff`  | `#e1ebfc` 1.20 | `#bfd3f9` 1.51 | `#6593f0` 3.00 | `#356fec` 4.52 | `#164ecc` 7.00 |
+  | `#111111`  | `#041e59` 1.20 | `#092d7c` 1.50 | `#1855db` 3.02 | `#3d76ed` 4.50 | `#719df2` 7.02 |
+
+The numbers are deterministic: the same base and options give the same hex on every machine (no randomness, a fixed
+number of bisection steps).
+
+## Contrast
+
+What a contrast ramp promises, exactly:
+
+- **Each step `i` has `ratio(step, background) >= ratios[i]`**, with the ratio computed as `check.contrast` computes it:
+  culori's `wcagLuminance` of each colour clipped to sRGB, `(L1 + 0.05) / (L2 + 0.05)`, not rounded. It is measured on
+  the hex the step outputs, so `check.contrast(t.blue._4, t.bg, { min: 4.5 })` passes when `t.bg` holds the same
+  `background`. The search only keeps colours that pass, so this does not rest on the search converging.
+- **By little.** The step is the passing colour nearest the background along the ramp, within an 8-bit step: in the tests
+  every step of 8 bases on 4 backgrounds is below `ratio * 1.02`. So a check held to more than the step was made for
+  fails: `check.contrast(t.blue._4, t.bg, { min: 4.6 })` is
+  `contrast 4.52 is below 4.6: blue.4 #356fec on bg #ffffff, in the default values`, and the same in the dark theme
+  (4.50). Check each step at its own ratio.
+- **Against that background only.** A ratio holds for the `background` the ramp was made for. On another background
+  (a theme), make a ramp for it with the same ratios and set both under the same condition or selector, as above;
+  `check.contrast` then checks each step against the theme's background.
+- **Lightness ramps promise no ratio**; check the pairs you use.
+- **WCAG 2 only**, not APCA. A WCAG 2 pass is not an APCA pass, especially for light text on dark.
+
+## Limits
+
+- **Errors are thrown** when the module is evaluated, so they are build errors: a base or background that is not a
+  colour (`@cssints/ramp: the base "banana" is not a colour`) or is translucent, `steps` that is not a whole number from
+  1, a lightness outside 0..1, and a ratio out of 1..21 or out of reach on the background
+  (`ratio 21 is out of reach on #111: at most 18.88 (white)`). A mid-grey background leaves little room on either side.
+- **Monotone for sorted ratios.** Ascending ratios give steps moving away from the background, but the ramp does not sort
+  them for you. The lightness is OKLCH lightness, not a luminance: two hues at one lightness have different ratios.
+- **sRGB only.** A P3 variant (`color(display-p3 …)`) is not shipped: `check.contrast` clips a colour to sRGB, so a P3
+  step would be checked as another colour than the one shown, and a `color()` value walks the colour grammar in the types
+  (thousands of instantiations a token) where a hex is cheap. A base outside sRGB is read with its share of chroma capped
+  at the gamut.
+- **The editor shows `#${string}`.** A step's value is computed when the module runs, so its type is `` `#${string}` ``,
+  not the literal hex (hover shows ``Token<"color", true, `#${string}`>``). Its type is still a colour token, the steps are
+  known (`t.blue._6` of a five-ratio ramp is a type error), and the build checks the values.
+- **Type cost** (tsgo, one file per row):
+
+  | Call                                             | Instantiations | Check time |
+  | ------------------------------------------------ | -------------- | ---------- |
+  | `color("red")` (the baseline)                    | 0.16 M         | 0.09 s     |
+  | 10 ramps of 10 steps (100 tokens)                | 0.15 M         | 0.09 s     |
+  | 100 ramps of 10 steps (1,000 tokens)             | 0.16 M         | 0.10 s     |
+  | the same 1,000 tokens and a theme of all of them | 0.24 M         | 0.13 s     |
+
+  A step costs about 10 instantiations as a token (every value has the one type `` `#${string}` ``), about 80 as a theme
+  override, so a ramp is as cheap as the hex sets of @cssints/tokens.
+
+```bash
+cd packages/ramp && bun run test        # the ramp maths, then a fixture through the engine (check.contrast passes, a tight pair fails)
+cd packages/ramp && bun run typecheck   # the type test (test/types/ramp.ts)
+```
+
+## Credits
+
+Two ideas, written here: the chroma relative to the sRGB gamut from [nutelch](https://github.com/meodai/nutelch) (MIT,
+David Aerne), and the search for a lightness that meets a contrast ratio from [Leonardo](https://github.com/adobe/leonardo)
+(Apache-2.0, Adobe). The colour maths is [culori](https://culorijs.org) (MIT, Dan Burzo), a dependency. No code is
+copied.

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+//#region src/index.d.ts
+/** A hex colour: cheap in the types (createTokens checks it without the walk of every colour syntax). */
+export type Hex = `#${string}`;
+/** The step names of an N-step ramp: `"1"` to `"N"` (`t.blue._1` in code, `--blue-1` in CSS). */
+export type Keys<N extends number, A extends string[] = []> = number extends N ? `${number}` : A["length"] extends N ? A[number] : Keys<N, [...A, `${[...A, 0]["length"]}`]>;
+/** A ramp: a DTCG colour group whose tokens are the steps, lightest first for a lightness ramp. */
+export type Ramp<K extends string> = {
+  readonly $type: "color";
+} & { readonly [P in K]: {
+  readonly $value: Hex;
+}; };
+/** The overrides of a ramp for createGlobalTheme: a step `"1"` is `_1`, as cssints reads a key that starts with a digit. */
+export type RampOverrides<K extends string> = { readonly [P in K as `_${P}`]: Hex; };
+/** A lightness ramp: `steps` colours from the first lightness to the second, evenly in OKLCH lightness. */
+export interface LightnessOptions<N extends number> {
+  readonly mode: "lightness";
+  readonly steps: N;
+  /** OKLCH lightness of the first and the last step, from 0 to 1; default `[0.97, 0.25]`. */
+  readonly lightness?: readonly [number, number];
+}
+/** A contrast ramp: one step per ratio, each the lowest WCAG 2 ratio at or above it against `background`. */
+export interface ContrastOptions<R extends readonly number[]> {
+  readonly mode: "contrast";
+  /** WCAG 2 contrast ratios against the background, from 1 to 21: `[1.2, 1.5, 3, 4.5, 7]`. */
+  readonly ratios: R;
+  /** An opaque CSS colour; the steps go darker on a light one and lighter on a dark one. */
+  readonly background: string;
+}
+/**
+ * The relative luminance of a colour as css.check.contrast reads it (clipped to sRGB).
+ * @param {string} text an opaque CSS colour
+ * @returns {number} the WCAG 2 relative luminance, from 0 to 1
+ */
+export declare const luminance: (text: string) => number;
+/**
+ * The WCAG 2 contrast ratio of two relative luminances, as css.check.contrast computes it (not rounded).
+ * @param {number} a a relative luminance
+ * @param {number} b the other
+ * @returns {number} the ratio, from 1 to 21
+ */
+export declare const ratio: (a: number, b: number) => number;
+/**
+ * An OKLCH ramp of `base` as a DTCG colour group for createTokens, steps `"1"` to `"N"`, each a hex colour in sRGB.
+ * `mode: "lightness"`: `steps` colours spaced evenly in OKLCH lightness. `mode: "contrast"`: one step per ratio, each the
+ * colour of the base's hue with the lowest WCAG 2 ratio at or above it against `background`, so
+ * `check.contrast(step, background, { min: ratio })` passes. Throws on a colour it cannot read or a ratio out of reach.
+ */
+export declare function ramp<const N extends number>(base: string, options: LightnessOptions<N>): Ramp<Keys<N>>;
+export declare function ramp<const R extends readonly number[]>(base: string, options: ContrastOptions<R>): Ramp<Keys<R["length"]>>;
+/**
+ * A ramp as the overrides of a theme: `createGlobalTheme(t.blue, dark, overrides(ramp(…)))`.
+ * @param {Ramp<K>} r a ramp
+ * @returns {RampOverrides<K>} its steps as `{ _1: hex, … }`
+ */
+export declare const overrides: <K extends string>(r: Ramp<K>) => RampOverrides<K>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,96 @@
+import { clampRgb, converter, formatHex, inGamut, parse, wcagLuminance } from "culori";
+//#region src/index.ts
+const toOklch = converter("oklch");
+const toRgb = converter("rgb");
+const inSrgb = inGamut("rgb");
+const fail = (why) => {
+	throw new Error(`@cssints/ramp: ${why}`);
+};
+const maxChroma = (l, h) => {
+	if (l <= 0 || l >= 1) return 0;
+	let lo = 0;
+	let hi = .5;
+	for (let i = 0; i < 24; i++) {
+		const mid = (lo + hi) / 2;
+		if (inSrgb({
+			mode: "oklch",
+			l,
+			c: mid,
+			h
+		})) lo = mid;
+		else hi = mid;
+	}
+	return lo;
+};
+const opaque = (text, what) => {
+	const c = parse(text);
+	if (!c) return fail(`${what} "${text}" is not a colour`);
+	if ((c.alpha ?? 1) < 1) return fail(`${what} "${text}" is translucent`);
+	return c;
+};
+const shape = (base) => {
+	const o = toOklch(opaque(base, "the base"));
+	const h = o.h ?? 0;
+	const max = maxChroma(o.l, h);
+	return {
+		h,
+		rel: max > 0 ? Math.min(1, o.c / max) : 0
+	};
+};
+const at = (l, { h, rel }) => formatHex(clampRgb(toRgb({
+	mode: "oklch",
+	l,
+	c: rel * maxChroma(l, h),
+	h
+})));
+/**
+* The relative luminance of a colour as css.check.contrast reads it (clipped to sRGB).
+* @param {string} text an opaque CSS colour
+* @returns {number} the WCAG 2 relative luminance, from 0 to 1
+*/
+const luminance = (text) => wcagLuminance(clampRgb(opaque(text, "the colour")));
+/**
+* The WCAG 2 contrast ratio of two relative luminances, as css.check.contrast computes it (not rounded).
+* @param {number} a a relative luminance
+* @param {number} b the other
+* @returns {number} the ratio, from 1 to 21
+*/
+const ratio = (a, b) => (Math.max(a, b) + .05) / (Math.min(a, b) + .05);
+const group = (steps) => Object.fromEntries([["$type", "color"], ...steps.map((hex, i) => [String(i + 1), { $value: hex }])]);
+const lightnessRamp = (base, { steps, lightness = [.97, .25] }) => {
+	if (!Number.isInteger(steps) || steps < 1) fail(`steps is a whole number from 1, got ${steps}`);
+	const [from, to] = lightness;
+	if (!(from >= 0 && from <= 1 && to >= 0 && to <= 1)) fail(`lightness is two numbers from 0 to 1, got [${from}, ${to}]`);
+	const s = shape(base);
+	return Array.from({ length: steps }, (_, i) => at(steps === 1 ? from : from + (to - from) * i / (steps - 1), s));
+};
+const contrastRamp = (base, { ratios, background }) => {
+	const bgL = toOklch(opaque(background, "the background")).l;
+	const bg = luminance(background);
+	const darker = ratio(0, bg) >= ratio(1, bg);
+	const s = shape(base);
+	return ratios.map((r) => {
+		if (!(r >= 1 && r <= 21)) fail(`a ratio is from 1 to 21, got ${r}`);
+		const passes = (l) => ratio(luminance(at(l, s)), bg) >= r;
+		let ok = darker ? 0 : 1;
+		let no = bgL;
+		if (!passes(ok)) fail(`ratio ${r} is out of reach on ${background}: at most ${ratio(darker ? 0 : 1, bg).toFixed(2)} (${darker ? "black" : "white"})`);
+		for (let i = 0; i < 32; i++) {
+			const mid = (ok + no) / 2;
+			if (passes(mid)) ok = mid;
+			else no = mid;
+		}
+		return at(ok, s);
+	});
+};
+function ramp(base, options) {
+	return group(options.mode === "contrast" ? contrastRamp(base, options) : lightnessRamp(base, options));
+}
+/**
+* A ramp as the overrides of a theme: `createGlobalTheme(t.blue, dark, overrides(ramp(…)))`.
+* @param {Ramp<K>} r a ramp
+* @returns {RampOverrides<K>} its steps as `{ _1: hex, … }`
+*/
+const overrides = (r) => Object.fromEntries(Object.entries(r).flatMap(([k, v]) => k === "$type" ? [] : [[`_${k}`, v.$value]]));
+//#endregion
+export { luminance, overrides, ramp, ratio };

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@cssints/ramp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "OKLCH colour ramps for cssints as DTCG data: a lightness ramp, or steps picked by WCAG 2 contrast against a background",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/ramp"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "culori": "^4.0.2"
+  },
+  "peerDependencies": {
+    "cssints": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}