@cssints/rybitten 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,47 @@
+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.
+
+---
+
+This package depends on RYBitten (https://github.com/meodai/RYBitten), distributed under this licence:
+
+    MIT License
+
+    Copyright (c) 2024 David Aerne
+
+    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,126 @@
-# Temporary Holding Version
+# @cssints/rybitten
 
-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.
+[RYBitten](https://rybitten.space/) colours for [cssints](../../README.md), computed at build time. RYBitten (by meodai, David Aerne in its
+licence; MIT) turns red-yellow-blue coordinates into RGB through a _cube_: the eight corners of a colour model (white, red, yellow,
+orange, blue, violet, green, black). It ships 36 of them, from Boutet (1708) and Goethe to Itten, Munsell and Albers, so
+the same hue is another colour in each. `color(hue, options)` gives one hex colour, `wheel(steps, options)` and
+`shades(hue, lightness, options)` return plain DTCG data (a colour group, steps `"1"` to `"N"`) that you pass to
+`createTokens` yourself, and `overrides(group)` turns a group into the override object of `createGlobalTheme`. The package
+has no runtime and no `scope()`: like [@cssints/ramp](../ramp/README.md) and the sets of
+[@cssints/tokens](../tokens/README.md), a group is data, so it goes under any 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, shades, wheel } from "@cssints/rybitten";
+
+export const t = createTokens({
+  hue: wheel(12, { cube: "itten" }),
+  paper: shades(0, [1, 0.96, 0], { cube: "itten", saturation: 0 }),
+});
+
+// the paper and the ink swap in the dark
+createGlobalTheme(t, media("(prefers-color-scheme: dark)"), {
+  paper: overrides(shades(0, [0, 0.04, 1], { cube: "itten", saturation: 0 })),
+});
+```
+
+```ts
+// text.ts
+import { bg, check, cn, color } from "cssints" with { type: "cssints" };
+
+import { t } from "./tokens.ts";
+
+check.contrast(t.paper._3, t.paper._1, { min: 12 }); // the ink on the paper, light and dark
+export const text = cn(color(t.hue._9), bg(t.paper._1));
+```
+
+The sheet of `text.ts`:
+
+```css
+@property --hue-9 {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: #1699da;
+}
+@property --paper-1 {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: #fdf6ed;
+}
+@layer _.k {
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --paper-1: #1d1c1c;
+      --paper-2: #1e1d1d;
+      --paper-3: #fdf6ed;
+    }
+  }
+}
+@layer _.a {
+  ._14bfx2y {
+    color: var(--hue-9);
+  }
+  ._1j4wng5 {
+    background-color: var(--paper-1);
+  }
+}
+```
+
+## The functions
+
+- **`color(hue, { cube?, saturation?, lightness? })`**: the hex colour of a hue. The hue is degrees on a painter's wheel,
+  not the HSL wheel: `0` red, `120` yellow, `240` blue (Itten: `#e32421`, `#f3e600`, `#1699da`), any number, `360` is `0`.
+  Saturation is `0` to `1` (default `1`; `0` gives the cube's greys). Lightness is `0` to `1` (default `0.5`): `1` is the
+  cube's white and `0` its black, because RYB is subtractive (RYBitten's `invertLightness`). The cube is a key of
+  RYBitten's `cubes` map (default `"itten"`) or your own eight corners.
+- **`wheel(steps, { from?, cube?, saturation?, lightness? })`**: `steps` hues evenly round the wheel from `from` degrees
+  (default `0`): `wheel(12)` is Itten's twelve-part circle, red, red-orange, orange, ... `"1"` to `"12"`.
+- **`shades(hue, lightness, { cube?, saturation? })`**: one hue at the lightnesses you list, in that order, `"1"` to
+  `"N"` for N values. With `saturation: 0` it is the cube's own grey scale, from its paper white to its ink black.
+- **`overrides(group)`**: `{ _1: hex, … }` for `createGlobalTheme`, as cssints reads a key that starts with a digit.
+
+A group is not a contrast ramp: the colours of a cube are what its makers painted, and no ratio is promised. For a
+colour that must pass `check.contrast`, use a hue of the wheel as the base of an `@cssints/ramp` contrast ramp, which
+finds the step with the ratio you need (the docs site does this for its accent, see below), or check the pair as above.
+
+## Cubes
+
+`cubes` is RYBitten's own map (`import { cubes } from "rybitten/cubes"`): `itten` (the default), `munsell`, `bezold`,
+`goethe`, `albers`, `apple90s`, `harris`, `cmy`, ... with title, author, year and reference. The hue `240` in four of them:
+
+| Cube      | Blue      | Paper     | Ink       |
+| --------- | --------- | --------- | --------- |
+| `itten`   | `#1699da` | `#fdf6ed` | `#1d1c1c` |
+| `munsell` | `#3b8fab` | `#e4dac5` | `#2e2c26` |
+| `albers`  | `#1161aa` | `#e7ebed` | `#000001` |
+| `goethe`  | `#5f9dbf` | `#efebe1` | `#08090d` |
+
+## Limits
+
+- **Pinned.** `rybitten` is a dependency at `1.3.0`: RYBitten's contract does not cover the numbers of a cube, which a
+  minor release may refine, so a colour can move with an upgrade (the tests pin Itten's corners).
+- **Errors are thrown** when the module is evaluated, so they are build errors: a cube that is not in the map
+  (`@cssints/rybitten: no cube "nope" in RYBitten's cubes`), a hue that is not a number, a saturation or lightness outside
+  0..1, `steps` that is not a whole number from 1.
+- **sRGB hex only.** A cube holds sRGB corners, so the colours are in sRGB (trilinear interpolation stays inside the
+  cube), and a hex is what `check.contrast` reads exactly and the types accept cheaply.
+- **No harmonies.** A complement is `hue + 180`, a triad `+ 120`: `color(h + 180)`, or the steps of a `wheel(3)`.
+- **The editor shows `` `#${string}` ``.** A value is computed when the module runs, so its type is a hex string, not the
+  literal (as for @cssints/ramp). The steps are known (`t.hue._13` of a twelve-step wheel is a type error).
+- **Type cost.** A step is a `` `#${string}` `` token like a step of @cssints/ramp: the whole type test (a wheel of twelve, a
+  run of four, their overrides in a theme) is 0.19 M instantiations in tsgo, as many as the type test of ramp.
+- **No runtime.** A hue picked in the browser needs one of the steps built ahead (the docs site builds a theme per step of
+  a twelve-hue wheel and switches them with an attribute) or `rybitten` itself in the page, which this package does not ship.
+
+## Credits
+
+Colour maths and the historical cubes are [RYBitten](https://github.com/meodai/RYBitten) by meodai (David Aerne; MIT), a
+dependency of this package, whose licence is reproduced in LICENSE here. The cubes
+cite their historical sources: see RYBitten's README.
+
+```bash
+cd packages/rybitten && bun run test        # the colours and the errors, then a module through the engine (check.contrast passes, a hue on paper fails)
+cd packages/rybitten && bun run typecheck   # the type test (test/types/rybitten.ts)
+```

package/dist/index.d.mts

@@ -0,0 +1,54 @@
+import { ColorCube } from "rybitten/cubes";
+//#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 group: `"1"` to `"N"` (`t.wheel._1` in code, `--wheel-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 colour group: a DTCG group whose tokens are the steps. */
+export type Palette<K extends string> = {
+  readonly $type: "color";
+} & { readonly [P in K]: {
+  readonly $value: Hex;
+}; };
+/** The overrides of a group for createGlobalTheme: a step `"1"` is `_1`, as cssints reads a key that starts with a digit. */
+export type PaletteOverrides<K extends string> = { readonly [P in K as `_${P}`]: Hex; };
+/** Which colours a hue becomes. */
+export interface Options {
+  /** A key of RYBitten's `cubes` (`"itten"`, `"munsell"`, `"albers"`, ...) or a cube of eight RGB corners; default `"itten"`. */
+  readonly cube?: string | ColorCube;
+  /** HSL saturation from 0 (the cube's greys) to 1; default 1. */
+  readonly saturation?: number;
+  /** HSL lightness from 0 (the cube's black) to 1 (its white); default 0.5. */
+  readonly lightness?: number;
+}
+/**
+ * The sRGB hex colour of a hue in a cube.
+ * @param {number} hue degrees on the RYB wheel, any number (360 is 0)
+ * @param {Options} options the cube, saturation and lightness
+ * @returns {Hex} `#rrggbb`
+ */
+export declare const color: (hue: number, options?: Options) => `#${string}`;
+/**
+ * `steps` hues evenly round the wheel, from `from` degrees (default 0, red), as a colour group `"1"` to `"N"`.
+ * @param {number} steps how many hues, a whole number from 1
+ * @param {Options & { from?: number }} options the cube, saturation and lightness of every step
+ * @returns {Palette<Keys<N>>} a DTCG colour group for createTokens
+ */
+export declare const wheel: <const N extends number>(steps: N, { from, ...options }?: Options & {
+  readonly from?: number;
+}) => Palette<Keys<N, []>>;
+/**
+ * One hue at several lightnesses, one step per value, in the order given (1 is the cube's white, 0 its black).
+ * @param {number} hue degrees on the RYB wheel
+ * @param {readonly number[]} lightness the lightness of each step, from 0 to 1
+ * @param {Omit<Options, "lightness">} options the cube and the saturation
+ * @returns {Palette<Keys<R["length"]>>} a DTCG colour group for createTokens
+ */
+export declare const shades: <const R extends readonly number[]>(hue: number, lightness: R, options?: Omit<Options, "lightness">) => Palette<Keys<R["length"], []>>;
+/**
+ * A group as the overrides of a theme: `createGlobalTheme(t.wheel, dark, overrides(wheel(12, { cube: "munsell" })))`.
+ * @param {Palette<K>} p a group of `wheel` or `shades`
+ * @returns {PaletteOverrides<K>} its steps as `{ _1: hex, … }`
+ */
+export declare const overrides: <K extends string>(p: Palette<K>) => PaletteOverrides<K>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,55 @@
+import { rybHsl2rgb } from "rybitten";
+import { cubes } from "rybitten/cubes";
+//#region src/index.ts
+const fail = (why) => {
+	throw new Error(`@cssints/rybitten: ${why}`);
+};
+const cubeOf = (cube = "itten") => typeof cube === "string" ? cubes.get(cube)?.cube ?? fail(`no cube "${cube}" in RYBitten's cubes`) : cube;
+const unit = (x, what) => x >= 0 && x <= 1 ? x : fail(`${what} is from 0 to 1, got ${x}`);
+const channel = (x) => Math.round(Math.min(1, Math.max(0, x)) * 255).toString(16).padStart(2, "0");
+const hex = (rgb) => `#${rgb.map(channel).join("")}`;
+/**
+* The sRGB hex colour of a hue in a cube.
+* @param {number} hue degrees on the RYB wheel, any number (360 is 0)
+* @param {Options} options the cube, saturation and lightness
+* @returns {Hex} `#rrggbb`
+*/
+const color = (hue, options = {}) => {
+	const { cube, saturation = 1, lightness = .5 } = options;
+	if (!Number.isFinite(hue)) fail(`hue is a number of degrees, got ${hue}`);
+	return hex(rybHsl2rgb([
+		(hue % 360 + 360) % 360,
+		unit(saturation, "saturation"),
+		unit(lightness, "lightness")
+	], { cube: cubeOf(cube) }));
+};
+const group = (colors) => Object.fromEntries([["$type", "color"], ...colors.map((c, i) => [String(i + 1), { $value: c }])]);
+/**
+* `steps` hues evenly round the wheel, from `from` degrees (default 0, red), as a colour group `"1"` to `"N"`.
+* @param {number} steps how many hues, a whole number from 1
+* @param {Options & { from?: number }} options the cube, saturation and lightness of every step
+* @returns {Palette<Keys<N>>} a DTCG colour group for createTokens
+*/
+const wheel = (steps, { from = 0, ...options } = {}) => {
+	if (!Number.isInteger(steps) || steps < 1) fail(`steps is a whole number from 1, got ${steps}`);
+	return group(Array.from({ length: steps }, (_, i) => color(from + 360 * i / steps, options)));
+};
+/**
+* One hue at several lightnesses, one step per value, in the order given (1 is the cube's white, 0 its black).
+* @param {number} hue degrees on the RYB wheel
+* @param {readonly number[]} lightness the lightness of each step, from 0 to 1
+* @param {Omit<Options, "lightness">} options the cube and the saturation
+* @returns {Palette<Keys<R["length"]>>} a DTCG colour group for createTokens
+*/
+const shades = (hue, lightness, options = {}) => group(lightness.map((l) => color(hue, {
+	...options,
+	lightness: l
+})));
+/**
+* A group as the overrides of a theme: `createGlobalTheme(t.wheel, dark, overrides(wheel(12, { cube: "munsell" })))`.
+* @param {Palette<K>} p a group of `wheel` or `shades`
+* @returns {PaletteOverrides<K>} its steps as `{ _1: hex, … }`
+*/
+const overrides = (p) => Object.fromEntries(Object.entries(p).flatMap(([k, v]) => k === "$type" ? [] : [[`_${k}`, v.$value]]));
+//#endregion
+export { color, overrides, shades, wheel };

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@cssints/rybitten",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "RYB palettes for cssints as DTCG data: a hue wheel and ramps in RYBitten's historical colour cubes, at build time",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/rybitten"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "rybitten": "1.3.0"
+  },
+  "peerDependencies": {
+    "cssints": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}