@loidolt/theme-tokens 0.5.0 → 0.7.0

package/README.md

@@ -14,3 +14,15 @@ import { colors, semantic, spacing, tokens } from '@loidolt/theme-tokens';
 @import '@loidolt/theme-tokens/css';
 @import '@loidolt/theme-tokens/css/dark';
 ```
+
+WCAG contrast arithmetic, for colours chosen at runtime:
+
+```ts
+import { getContrastRatio, getContrastTextColor, meetsContrast } from '@loidolt/theme-tokens';
+
+meetsContrast('#767676', '#ffffff'); // true — AA for body text
+getContrastTextColor(userColour); // the theme ink that reads best on it
+```
+
+Named media frames live in `aspectRatio` (`square`, `video`, `photo`, `portrait`, `wide`) and as
+`--loidolt-aspect-*`.

package/dist/dark-auto.css

@@ -36,6 +36,44 @@
   --loidolt-focus-ring: #f0895c;
   --loidolt-shadow-color: #000000;
   --loidolt-scrim: color-mix(in srgb, var(--loidolt-shadow-color) 78%, transparent);
+  --loidolt-chart-1: #e0672f;
+  --loidolt-chart-2: #6ea5bd;
+  --loidolt-chart-3: #93b287;
+  --loidolt-chart-4: #d9ab63;
+  --loidolt-chart-5: #c49ac0;
+  --loidolt-chart-6: #b8ad96;
+  --loidolt-chart-7: #6fb8a6;
+  --loidolt-chart-8: #c79a78;
+  --loidolt-chart-sequential-1: #3a2a1d;
+  --loidolt-chart-sequential-2: #6b4225;
+  --loidolt-chart-sequential-3: #a4602f;
+  --loidolt-chart-sequential-4: #d98a4d;
+  --loidolt-chart-sequential-5: #f2bd8a;
+  --loidolt-chart-diverging-1: #85b6ca;
+  --loidolt-chart-diverging-2: #5a8ea3;
+  --loidolt-chart-diverging-3: #35596a;
+  --loidolt-chart-diverging-4: #3a3d34;
+  --loidolt-chart-diverging-5: #7a4428;
+  --loidolt-chart-diverging-6: #bf6a3a;
+  --loidolt-chart-diverging-7: #f0895c;
+  --loidolt-chart-positive: #93b287;
+  --loidolt-chart-negative: #e88b81;
+  --loidolt-map-land: #161814;
+  --loidolt-map-water: #1d2b31;
+  --loidolt-map-park: #1f271c;
+  --loidolt-map-road: #2b2e26;
+  --loidolt-map-road-major: #3a3d34;
+  --loidolt-map-building: #24271f;
+  --loidolt-map-boundary: #787c6b;
+  --loidolt-map-label: #ebe7dc;
+  --loidolt-map-label-halo: #161814;
+  --loidolt-syntax-keyword: #a9441d;
+  --loidolt-syntax-string: #3f5139;
+  --loidolt-syntax-comment: #5f5b50;
+  --loidolt-syntax-constant: #7c4d17;
+  --loidolt-syntax-function: #265162;
+  --loidolt-syntax-parameter: #7a4a78;
+  --loidolt-syntax-punctuation: #474a42;
 }
 
 @media (prefers-color-scheme: dark) {
@@ -76,5 +114,43 @@
     --loidolt-focus-ring: #f0895c;
     --loidolt-shadow-color: #000000;
     --loidolt-scrim: color-mix(in srgb, var(--loidolt-shadow-color) 78%, transparent);
+    --loidolt-chart-1: #e0672f;
+    --loidolt-chart-2: #6ea5bd;
+    --loidolt-chart-3: #93b287;
+    --loidolt-chart-4: #d9ab63;
+    --loidolt-chart-5: #c49ac0;
+    --loidolt-chart-6: #b8ad96;
+    --loidolt-chart-7: #6fb8a6;
+    --loidolt-chart-8: #c79a78;
+    --loidolt-chart-sequential-1: #3a2a1d;
+    --loidolt-chart-sequential-2: #6b4225;
+    --loidolt-chart-sequential-3: #a4602f;
+    --loidolt-chart-sequential-4: #d98a4d;
+    --loidolt-chart-sequential-5: #f2bd8a;
+    --loidolt-chart-diverging-1: #85b6ca;
+    --loidolt-chart-diverging-2: #5a8ea3;
+    --loidolt-chart-diverging-3: #35596a;
+    --loidolt-chart-diverging-4: #3a3d34;
+    --loidolt-chart-diverging-5: #7a4428;
+    --loidolt-chart-diverging-6: #bf6a3a;
+    --loidolt-chart-diverging-7: #f0895c;
+    --loidolt-chart-positive: #93b287;
+    --loidolt-chart-negative: #e88b81;
+    --loidolt-map-land: #161814;
+    --loidolt-map-water: #1d2b31;
+    --loidolt-map-park: #1f271c;
+    --loidolt-map-road: #2b2e26;
+    --loidolt-map-road-major: #3a3d34;
+    --loidolt-map-building: #24271f;
+    --loidolt-map-boundary: #787c6b;
+    --loidolt-map-label: #ebe7dc;
+    --loidolt-map-label-halo: #161814;
+    --loidolt-syntax-keyword: #a9441d;
+    --loidolt-syntax-string: #3f5139;
+    --loidolt-syntax-comment: #5f5b50;
+    --loidolt-syntax-constant: #7c4d17;
+    --loidolt-syntax-function: #265162;
+    --loidolt-syntax-parameter: #7a4a78;
+    --loidolt-syntax-punctuation: #474a42;
   }
 }

package/dist/dark.css

@@ -36,4 +36,42 @@
   --loidolt-focus-ring: #f0895c;
   --loidolt-shadow-color: #000000;
   --loidolt-scrim: color-mix(in srgb, var(--loidolt-shadow-color) 78%, transparent);
+  --loidolt-chart-1: #e0672f;
+  --loidolt-chart-2: #6ea5bd;
+  --loidolt-chart-3: #93b287;
+  --loidolt-chart-4: #d9ab63;
+  --loidolt-chart-5: #c49ac0;
+  --loidolt-chart-6: #b8ad96;
+  --loidolt-chart-7: #6fb8a6;
+  --loidolt-chart-8: #c79a78;
+  --loidolt-chart-sequential-1: #3a2a1d;
+  --loidolt-chart-sequential-2: #6b4225;
+  --loidolt-chart-sequential-3: #a4602f;
+  --loidolt-chart-sequential-4: #d98a4d;
+  --loidolt-chart-sequential-5: #f2bd8a;
+  --loidolt-chart-diverging-1: #85b6ca;
+  --loidolt-chart-diverging-2: #5a8ea3;
+  --loidolt-chart-diverging-3: #35596a;
+  --loidolt-chart-diverging-4: #3a3d34;
+  --loidolt-chart-diverging-5: #7a4428;
+  --loidolt-chart-diverging-6: #bf6a3a;
+  --loidolt-chart-diverging-7: #f0895c;
+  --loidolt-chart-positive: #93b287;
+  --loidolt-chart-negative: #e88b81;
+  --loidolt-map-land: #161814;
+  --loidolt-map-water: #1d2b31;
+  --loidolt-map-park: #1f271c;
+  --loidolt-map-road: #2b2e26;
+  --loidolt-map-road-major: #3a3d34;
+  --loidolt-map-building: #24271f;
+  --loidolt-map-boundary: #787c6b;
+  --loidolt-map-label: #ebe7dc;
+  --loidolt-map-label-halo: #161814;
+  --loidolt-syntax-keyword: #a9441d;
+  --loidolt-syntax-string: #3f5139;
+  --loidolt-syntax-comment: #5f5b50;
+  --loidolt-syntax-constant: #7c4d17;
+  --loidolt-syntax-function: #265162;
+  --loidolt-syntax-parameter: #7a4a78;
+  --loidolt-syntax-punctuation: #474a42;
 }

package/dist/index.d.ts

@@ -1,3 +1,53 @@
+/**
+ * WCAG 2.x contrast arithmetic, shared by the token tests and by applications that need to pick
+ * or validate a colour at runtime (a user-chosen swatch, a generated label). Pure functions over
+ * hex strings, so they run anywhere — build scripts, servers, and the browser.
+ *
+ * @see https://www.w3.org/TR/WCAG22/#dfn-relative-luminance
+ */
+type ContrastLevel = 'AA' | 'AAA';
+type TextSize = 'normal' | 'large';
+interface ContrastValidation {
+    ratio: number;
+    /** `ratio` to two decimals, e.g. `'4.52:1'`. */
+    ratioString: string;
+    passesAANormal: boolean;
+    passesAALarge: boolean;
+    passesAAANormal: boolean;
+    passesAAALarge: boolean;
+}
+/** Minimum ratio per level and text size. Large text is 18.66px bold or 24px regular and up. */
+declare const contrastRequirements: {
+    readonly AA: {
+        readonly normal: 4.5;
+        readonly large: 3;
+    };
+    readonly AAA: {
+        readonly normal: 7;
+        readonly large: 4.5;
+    };
+};
+/** Relative luminance, from 0 (black) to 1 (white). Accepts `#rgb` and `#rrggbb`. */
+declare function getLuminance(hex: string): number;
+/** Contrast ratio between two colours, from 1 to 21. Order does not matter. */
+declare function getContrastRatio(foreground: string, background: string): number;
+/** Whether a pair clears the WCAG threshold for the given level and text size. */
+declare function meetsContrast(foreground: string, background: string, { level, size }?: {
+    level?: ContrastLevel;
+    size?: TextSize;
+}): boolean;
+/** Every threshold at once, for reporting. */
+declare function validateContrast(foreground: string, background: string): ContrastValidation;
+/**
+ * Whichever of two inks reads better on `background` — by measured ratio, not a luminance
+ * cut-off, so it stays right for any pair you pass. Defaults to the theme's own deep ink and
+ * panel, rather than pure black and white.
+ */
+declare function getContrastTextColor(background: string, { dark, light }?: {
+    dark?: string;
+    light?: string;
+}): string;
+
 /**
  * Design tokens for Loidolt applications.
  *
@@ -11,7 +61,10 @@
 type TokenRef = {
     readonly $ref: string;
 };
-/** `['font', 'lineHeight', 'tight']` → `--loidolt-font-line-height-tight`. */
+/**
+ * `['font', 'lineHeight', 'tight']` → `--loidolt-font-line-height-tight`; a trailing number is its
+ * own segment, so `chart1` → `--loidolt-chart-1`.
+ */
 declare const cssVarName: (path: readonly string[]) => string;
 declare const colors: {
     readonly paper: "#ebe7dc";
@@ -32,6 +85,59 @@ declare const colors: {
     readonly success: "#3f5139";
     readonly warning: "#7c4d17";
     readonly info: "#265162";
+    /**
+     * Categorical series for charts, in the order they are handed out. Earth tones that stay apart
+     * from each other and hold 3:1 against every surface, so a line or bar needs no outline.
+     */
+    readonly series: {
+        readonly 1: "#c65224";
+        readonly 2: "#2f6f8a";
+        readonly 3: "#5b7a3a";
+        readonly 4: "#9a6a12";
+        readonly 5: "#7a4a78";
+        readonly 6: "#4d5a6a";
+        readonly 7: "#2f7d6d";
+        readonly 8: "#8a5a3c";
+    };
+    /** One warm hue from little to most: heatmaps, choropleths, cluster sizes. */
+    readonly sequential: {
+        readonly 1: "#ecd3b8";
+        readonly 2: "#dea67a";
+        readonly 3: "#c97a45";
+        readonly 4: "#a4521f";
+        readonly 5: "#6e3314";
+    };
+    /** Below and above a midpoint: slate for below, orange for above, the neutral paper between. */
+    readonly diverging: {
+        readonly 1: "#265162";
+        readonly 2: "#4f8196";
+        readonly 3: "#9cbac3";
+        readonly 4: "#ddd7c9";
+        readonly 5: "#e0a986";
+        readonly 6: "#c96f3d";
+        readonly 7: "#9b3a17";
+    };
+    /**
+     * Code highlighting. Code sits on the inverse surface — dark in the light theme — so these are
+     * the light inks; the dark theme's code block is light, and takes dark ones.
+     */
+    readonly syntax: {
+        readonly keyword: "#f0895c";
+        readonly string: "#a3c197";
+        readonly comment: "#b5ae9c";
+        readonly constant: "#e2b56c";
+        readonly function: "#8fc0d4";
+        readonly parameter: "#d3a8cf";
+        readonly punctuation: "#d8d2c4";
+    };
+    /** Basemap fills. Quiet by design: the data drawn on top carries the colour. */
+    readonly map: {
+        readonly water: "#b9cdd3";
+        readonly park: "#d3d8bd";
+        readonly road: "#f5f2e9";
+        readonly roadMajor: "#ffffff";
+        readonly building: "#d8d3c7";
+    };
 };
 declare const typography: {
     readonly display: "\"Jost\", \"Avenir Next\", sans-serif";
@@ -120,6 +226,17 @@ declare const breakpoints: {
     readonly expanded: "1024px";
     readonly wide: "1400px";
 };
+/**
+ * Named frames for media, as CSS `aspect-ratio` values. `Thumbnail`, `AspectRatio` and the media
+ * components accept these names so a gallery and its lightbox agree on shape.
+ */
+declare const aspectRatio: {
+    readonly square: "1 / 1";
+    readonly video: "16 / 9";
+    readonly photo: "4 / 3";
+    readonly portrait: "3 / 4";
+    readonly wide: "21 / 9";
+};
 /**
  * The role layer. Every value links to a primitive, so overriding a primitive propagates and
  * overriding a role restyles every component that plays it.
@@ -163,6 +280,45 @@ declare const semanticDefs: {
     readonly focusRing: TokenRef;
     readonly shadowColor: TokenRef;
     readonly scrim: "color-mix(in srgb, var(--loidolt-shadow-color) 72%, transparent)";
+    readonly chart1: TokenRef;
+    readonly chart2: TokenRef;
+    readonly chart3: TokenRef;
+    readonly chart4: TokenRef;
+    readonly chart5: TokenRef;
+    readonly chart6: TokenRef;
+    readonly chart7: TokenRef;
+    readonly chart8: TokenRef;
+    readonly chartSequential1: TokenRef;
+    readonly chartSequential2: TokenRef;
+    readonly chartSequential3: TokenRef;
+    readonly chartSequential4: TokenRef;
+    readonly chartSequential5: TokenRef;
+    readonly chartDiverging1: TokenRef;
+    readonly chartDiverging2: TokenRef;
+    readonly chartDiverging3: TokenRef;
+    readonly chartDiverging4: TokenRef;
+    readonly chartDiverging5: TokenRef;
+    readonly chartDiverging6: TokenRef;
+    readonly chartDiverging7: TokenRef;
+    /** Gains and losses: candlestick up/down, positive/negative bars. */
+    readonly chartPositive: TokenRef;
+    readonly chartNegative: TokenRef;
+    readonly mapLand: TokenRef;
+    readonly mapWater: TokenRef;
+    readonly mapPark: TokenRef;
+    readonly mapRoad: TokenRef;
+    readonly mapRoadMajor: TokenRef;
+    readonly mapBuilding: TokenRef;
+    readonly mapBoundary: TokenRef;
+    readonly mapLabel: TokenRef;
+    readonly mapLabelHalo: TokenRef;
+    readonly syntaxKeyword: TokenRef;
+    readonly syntaxString: TokenRef;
+    readonly syntaxComment: TokenRef;
+    readonly syntaxConstant: TokenRef;
+    readonly syntaxFunction: TokenRef;
+    readonly syntaxParameter: TokenRef;
+    readonly syntaxPunctuation: TokenRef;
 };
 /** Every custom property the package emits, in declaration order. */
 declare function flattenTokens(): Array<[string, string | TokenRef]>;
@@ -215,7 +371,121 @@ declare const darkSemantic: {
     readonly focusRing: "#f0895c";
     readonly shadowColor: "#000000";
     readonly scrim: "color-mix(in srgb, var(--loidolt-shadow-color) 78%, transparent)";
+    readonly chart1: "#e0672f";
+    readonly chart2: "#6ea5bd";
+    readonly chart3: "#93b287";
+    readonly chart4: "#d9ab63";
+    readonly chart5: "#c49ac0";
+    readonly chart6: "#b8ad96";
+    readonly chart7: "#6fb8a6";
+    readonly chart8: "#c79a78";
+    readonly chartSequential1: "#3a2a1d";
+    readonly chartSequential2: "#6b4225";
+    readonly chartSequential3: "#a4602f";
+    readonly chartSequential4: "#d98a4d";
+    readonly chartSequential5: "#f2bd8a";
+    readonly chartDiverging1: "#85b6ca";
+    readonly chartDiverging2: "#5a8ea3";
+    readonly chartDiverging3: "#35596a";
+    readonly chartDiverging4: "#3a3d34";
+    readonly chartDiverging5: "#7a4428";
+    readonly chartDiverging6: "#bf6a3a";
+    readonly chartDiverging7: "#f0895c";
+    readonly chartPositive: "#93b287";
+    readonly chartNegative: "#e88b81";
+    readonly mapLand: "#161814";
+    readonly mapWater: "#1d2b31";
+    readonly mapPark: "#1f271c";
+    readonly mapRoad: "#2b2e26";
+    readonly mapRoadMajor: "#3a3d34";
+    readonly mapBuilding: "#24271f";
+    readonly mapBoundary: "#787c6b";
+    readonly mapLabel: "#ebe7dc";
+    readonly mapLabelHalo: "#161814";
+    readonly syntaxKeyword: "#a9441d";
+    readonly syntaxString: "#3f5139";
+    readonly syntaxComment: "#5f5b50";
+    readonly syntaxConstant: "#7c4d17";
+    readonly syntaxFunction: "#265162";
+    readonly syntaxParameter: "#7a4a78";
+    readonly syntaxPunctuation: "#474a42";
 };
+type ColorScheme = 'light' | 'dark';
+type SemanticRole = keyof typeof semanticDefs;
+/** The custom property a semantic role is published as: `chart1` → `--loidolt-chart-1`. */
+declare const roleVar: (role: SemanticRole) => string;
+/**
+ * A role's concrete value in the reference light or dark theme. Canvas and WebGL renderers cannot
+ * read `var()`, and neither can the server: this is what they fall back to when the live value
+ * cannot be read from the page.
+ */
+declare const roleValue: (role: SemanticRole, scheme?: ColorScheme) => string;
+/** Names roles — singly or as an ordered list — under keys a renderer understands. */
+type RoleSpec = {
+    readonly [key: string]: SemanticRole | readonly SemanticRole[];
+};
+type ResolvedRoles<S extends RoleSpec> = {
+    -readonly [K in keyof S]: S[K] extends readonly SemanticRole[] ? string[] : string;
+};
+/**
+ * Resolves every role in `spec`. `read` defaults to the reference theme; a runtime passes one
+ * that reads the page, so a consumer's own theme reaches the canvas too.
+ */
+declare function resolveRoles<S extends RoleSpec>(spec: S, scheme?: ColorScheme, read?: (role: SemanticRole) => string): ResolvedRoles<S>;
+/** The roles a chart is painted with. */
+declare const chartRoles: {
+    readonly categorical: readonly ["chart1", "chart2", "chart3", "chart4", "chart5", "chart6", "chart7", "chart8"];
+    readonly sequential: readonly ["chartSequential1", "chartSequential2", "chartSequential3", "chartSequential4", "chartSequential5"];
+    readonly diverging: readonly ["chartDiverging1", "chartDiverging2", "chartDiverging3", "chartDiverging4", "chartDiverging5", "chartDiverging6", "chartDiverging7"];
+    readonly positive: "chartPositive";
+    readonly negative: "chartNegative";
+    readonly text: "text";
+    readonly muted: "textMuted";
+    readonly axis: "border";
+    readonly grid: "borderSoft";
+    readonly surface: "surface";
+    readonly background: "background";
+    readonly accent: "accent";
+};
+/** The roles a basemap and map overlays are painted with. */
+declare const mapRoles: {
+    readonly land: "mapLand";
+    readonly water: "mapWater";
+    readonly park: "mapPark";
+    readonly road: "mapRoad";
+    readonly roadMajor: "mapRoadMajor";
+    readonly building: "mapBuilding";
+    readonly boundary: "mapBoundary";
+    readonly label: "mapLabel";
+    readonly labelHalo: "mapLabelHalo";
+    readonly accent: "accent";
+    readonly text: "text";
+    readonly surface: "surface";
+    readonly focus: "focusRing";
+    readonly categorical: readonly ["chart1", "chart2", "chart3", "chart4", "chart5", "chart6", "chart7", "chart8"];
+    readonly sequential: readonly ["chartSequential1", "chartSequential2", "chartSequential3", "chartSequential4", "chartSequential5"];
+};
+/** The roles code is highlighted with, and the surface it sits on. */
+declare const syntaxRoles: {
+    readonly background: "surfaceInverse";
+    readonly text: "textInverse";
+    readonly keyword: "syntaxKeyword";
+    readonly string: "syntaxString";
+    readonly comment: "syntaxComment";
+    readonly constant: "syntaxConstant";
+    readonly function: "syntaxFunction";
+    readonly parameter: "syntaxParameter";
+    readonly punctuation: "syntaxPunctuation";
+};
+type SyntaxColors = ResolvedRoles<typeof syntaxRoles>;
+/** Syntax colours in the reference theme. */
+declare const syntaxColors: (scheme?: ColorScheme) => SyntaxColors;
+type ChartColors = ResolvedRoles<typeof chartRoles>;
+type MapColors = ResolvedRoles<typeof mapRoles>;
+/** Chart colours in the reference theme. */
+declare const chartColors: (scheme?: ColorScheme) => ChartColors;
+/** Map colours in the reference theme. */
+declare const mapColors: (scheme?: ColorScheme) => MapColors;
 /**
  * Dark theme CSS. `scope` picks how it activates:
  * - `attribute` (default): `[data-theme='dark']` only — the app drives it.
@@ -243,6 +513,59 @@ declare const tokens: {
         readonly success: "#3f5139";
         readonly warning: "#7c4d17";
         readonly info: "#265162";
+        /**
+         * Categorical series for charts, in the order they are handed out. Earth tones that stay apart
+         * from each other and hold 3:1 against every surface, so a line or bar needs no outline.
+         */
+        readonly series: {
+            readonly 1: "#c65224";
+            readonly 2: "#2f6f8a";
+            readonly 3: "#5b7a3a";
+            readonly 4: "#9a6a12";
+            readonly 5: "#7a4a78";
+            readonly 6: "#4d5a6a";
+            readonly 7: "#2f7d6d";
+            readonly 8: "#8a5a3c";
+        };
+        /** One warm hue from little to most: heatmaps, choropleths, cluster sizes. */
+        readonly sequential: {
+            readonly 1: "#ecd3b8";
+            readonly 2: "#dea67a";
+            readonly 3: "#c97a45";
+            readonly 4: "#a4521f";
+            readonly 5: "#6e3314";
+        };
+        /** Below and above a midpoint: slate for below, orange for above, the neutral paper between. */
+        readonly diverging: {
+            readonly 1: "#265162";
+            readonly 2: "#4f8196";
+            readonly 3: "#9cbac3";
+            readonly 4: "#ddd7c9";
+            readonly 5: "#e0a986";
+            readonly 6: "#c96f3d";
+            readonly 7: "#9b3a17";
+        };
+        /**
+         * Code highlighting. Code sits on the inverse surface — dark in the light theme — so these are
+         * the light inks; the dark theme's code block is light, and takes dark ones.
+         */
+        readonly syntax: {
+            readonly keyword: "#f0895c";
+            readonly string: "#a3c197";
+            readonly comment: "#b5ae9c";
+            readonly constant: "#e2b56c";
+            readonly function: "#8fc0d4";
+            readonly parameter: "#d3a8cf";
+            readonly punctuation: "#d8d2c4";
+        };
+        /** Basemap fills. Quiet by design: the data drawn on top carries the colour. */
+        readonly map: {
+            readonly water: "#b9cdd3";
+            readonly park: "#d3d8bd";
+            readonly road: "#f5f2e9";
+            readonly roadMajor: "#ffffff";
+            readonly building: "#d8d3c7";
+        };
     };
     readonly typography: {
         readonly display: "\"Jost\", \"Avenir Next\", sans-serif";
@@ -322,6 +645,13 @@ declare const tokens: {
         readonly expanded: "1024px";
         readonly wide: "1400px";
     };
+    readonly aspectRatio: {
+        readonly square: "1 / 1";
+        readonly video: "16 / 9";
+        readonly photo: "4 / 3";
+        readonly portrait: "3 / 4";
+        readonly wide: "21 / 9";
+    };
     readonly semantic: {
         readonly background: string;
         readonly surface: string;
@@ -358,6 +688,44 @@ declare const tokens: {
         readonly focusRing: string;
         readonly shadowColor: string;
         readonly scrim: string;
+        readonly chart1: string;
+        readonly chart2: string;
+        readonly chart3: string;
+        readonly chart4: string;
+        readonly chart5: string;
+        readonly chart6: string;
+        readonly chart7: string;
+        readonly chart8: string;
+        readonly chartSequential1: string;
+        readonly chartSequential2: string;
+        readonly chartSequential3: string;
+        readonly chartSequential4: string;
+        readonly chartSequential5: string;
+        readonly chartDiverging1: string;
+        readonly chartDiverging2: string;
+        readonly chartDiverging3: string;
+        readonly chartDiverging4: string;
+        readonly chartDiverging5: string;
+        readonly chartDiverging6: string;
+        readonly chartDiverging7: string;
+        readonly chartPositive: string;
+        readonly chartNegative: string;
+        readonly mapLand: string;
+        readonly mapWater: string;
+        readonly mapPark: string;
+        readonly mapRoad: string;
+        readonly mapRoadMajor: string;
+        readonly mapBuilding: string;
+        readonly mapBoundary: string;
+        readonly mapLabel: string;
+        readonly mapLabelHalo: string;
+        readonly syntaxKeyword: string;
+        readonly syntaxString: string;
+        readonly syntaxComment: string;
+        readonly syntaxConstant: string;
+        readonly syntaxFunction: string;
+        readonly syntaxParameter: string;
+        readonly syntaxPunctuation: string;
     };
     readonly darkSemantic: {
         readonly background: "#161814";
@@ -395,8 +763,46 @@ declare const tokens: {
         readonly focusRing: "#f0895c";
         readonly shadowColor: "#000000";
         readonly scrim: "color-mix(in srgb, var(--loidolt-shadow-color) 78%, transparent)";
+        readonly chart1: "#e0672f";
+        readonly chart2: "#6ea5bd";
+        readonly chart3: "#93b287";
+        readonly chart4: "#d9ab63";
+        readonly chart5: "#c49ac0";
+        readonly chart6: "#b8ad96";
+        readonly chart7: "#6fb8a6";
+        readonly chart8: "#c79a78";
+        readonly chartSequential1: "#3a2a1d";
+        readonly chartSequential2: "#6b4225";
+        readonly chartSequential3: "#a4602f";
+        readonly chartSequential4: "#d98a4d";
+        readonly chartSequential5: "#f2bd8a";
+        readonly chartDiverging1: "#85b6ca";
+        readonly chartDiverging2: "#5a8ea3";
+        readonly chartDiverging3: "#35596a";
+        readonly chartDiverging4: "#3a3d34";
+        readonly chartDiverging5: "#7a4428";
+        readonly chartDiverging6: "#bf6a3a";
+        readonly chartDiverging7: "#f0895c";
+        readonly chartPositive: "#93b287";
+        readonly chartNegative: "#e88b81";
+        readonly mapLand: "#161814";
+        readonly mapWater: "#1d2b31";
+        readonly mapPark: "#1f271c";
+        readonly mapRoad: "#2b2e26";
+        readonly mapRoadMajor: "#3a3d34";
+        readonly mapBuilding: "#24271f";
+        readonly mapBoundary: "#787c6b";
+        readonly mapLabel: "#ebe7dc";
+        readonly mapLabelHalo: "#161814";
+        readonly syntaxKeyword: "#a9441d";
+        readonly syntaxString: "#3f5139";
+        readonly syntaxComment: "#5f5b50";
+        readonly syntaxConstant: "#7c4d17";
+        readonly syntaxFunction: "#265162";
+        readonly syntaxParameter: "#7a4a78";
+        readonly syntaxPunctuation: "#474a42";
     };
 };
 type ThemeTokens = typeof tokens;
 
-export { type ThemeTokens, type TokenRef, borders, breakpoints, colors, cssVarName, darkSemantic, tokens as default, flattenTokens, generateCss, generateDarkCss, motion, semantic, shadows, sizing, spacing, tokens, typography, zIndex };
+export { type ChartColors, type ColorScheme, type ContrastLevel, type ContrastValidation, type MapColors, type ResolvedRoles, type RoleSpec, type SemanticRole, type SyntaxColors, type TextSize, type ThemeTokens, type TokenRef, aspectRatio, borders, breakpoints, chartColors, chartRoles, colors, contrastRequirements, cssVarName, darkSemantic, tokens as default, flattenTokens, generateCss, generateDarkCss, getContrastRatio, getContrastTextColor, getLuminance, mapColors, mapRoles, meetsContrast, motion, resolveRoles, roleValue, roleVar, semantic, shadows, sizing, spacing, syntaxColors, syntaxRoles, tokens, typography, validateContrast, zIndex };

package/dist/index.js

@@ -1,7 +1,50 @@
+// src/contrast.ts
+var contrastRequirements = {
+  AA: { normal: 4.5, large: 3 },
+  AAA: { normal: 7, large: 4.5 }
+};
+var channels = (hex, caller) => {
+  const match = /^#?([\da-f]{3}|[\da-f]{6})$/i.exec(hex.trim());
+  if (!match) throw new RangeError(`${caller}: invalid hex colour ${JSON.stringify(hex)}`);
+  const digits = match[1].length === 3 ? [...match[1]].map((digit) => digit + digit).join("") : match[1];
+  return [0, 2, 4].map((index) => parseInt(digits.slice(index, index + 2), 16));
+};
+var luminanceOf = (hex, caller) => {
+  const [r, g, b] = channels(hex, caller).map((channel) => channel / 255).map((channel) => channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+function getLuminance(hex) {
+  return luminanceOf(hex, "getLuminance");
+}
+function getContrastRatio(foreground, background) {
+  const [high, low] = [
+    luminanceOf(foreground, "getContrastRatio"),
+    luminanceOf(background, "getContrastRatio")
+  ].sort((a, b) => b - a);
+  return (high + 0.05) / (low + 0.05);
+}
+function meetsContrast(foreground, background, { level = "AA", size = "normal" } = {}) {
+  return getContrastRatio(foreground, background) >= contrastRequirements[level][size];
+}
+function validateContrast(foreground, background) {
+  const ratio = getContrastRatio(foreground, background);
+  return {
+    ratio,
+    ratioString: `${ratio.toFixed(2)}:1`,
+    passesAANormal: ratio >= contrastRequirements.AA.normal,
+    passesAALarge: ratio >= contrastRequirements.AA.large,
+    passesAAANormal: ratio >= contrastRequirements.AAA.normal,
+    passesAAALarge: ratio >= contrastRequirements.AAA.large
+  };
+}
+function getContrastTextColor(background, { dark = "#20231d", light = "#f5f2e9" } = {}) {
+  return getContrastRatio(dark, background) >= getContrastRatio(light, background) ? dark : light;
+}
+
 // src/index.ts
 var ref = (name) => ({ $ref: `--loidolt-${name}` });
 var isRef = (value) => typeof value === "object" && value !== null && "$ref" in value;
-var kebab = (value) => value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+var kebab = (value) => value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`).replace(/([a-z])(\d)/g, "$1-$2");
 var cssVarName = (path) => `--loidolt-${kebab(path.join("-"))}`;
 var colors = {
   paper: "#ebe7dc",
@@ -23,7 +66,60 @@ var colors = {
   errorDark: "#7f1f1a",
   success: "#3f5139",
   warning: "#7c4d17",
-  info: "#265162"
+  info: "#265162",
+  /**
+   * Categorical series for charts, in the order they are handed out. Earth tones that stay apart
+   * from each other and hold 3:1 against every surface, so a line or bar needs no outline.
+   */
+  series: {
+    1: "#c65224",
+    2: "#2f6f8a",
+    3: "#5b7a3a",
+    4: "#9a6a12",
+    5: "#7a4a78",
+    6: "#4d5a6a",
+    7: "#2f7d6d",
+    8: "#8a5a3c"
+  },
+  /** One warm hue from little to most: heatmaps, choropleths, cluster sizes. */
+  sequential: {
+    1: "#ecd3b8",
+    2: "#dea67a",
+    3: "#c97a45",
+    4: "#a4521f",
+    5: "#6e3314"
+  },
+  /** Below and above a midpoint: slate for below, orange for above, the neutral paper between. */
+  diverging: {
+    1: "#265162",
+    2: "#4f8196",
+    3: "#9cbac3",
+    4: "#ddd7c9",
+    5: "#e0a986",
+    6: "#c96f3d",
+    7: "#9b3a17"
+  },
+  /**
+   * Code highlighting. Code sits on the inverse surface — dark in the light theme — so these are
+   * the light inks; the dark theme's code block is light, and takes dark ones.
+   */
+  syntax: {
+    keyword: "#f0895c",
+    string: "#a3c197",
+    comment: "#b5ae9c",
+    constant: "#e2b56c",
+    function: "#8fc0d4",
+    parameter: "#d3a8cf",
+    punctuation: "#d8d2c4"
+  },
+  /** Basemap fills. Quiet by design: the data drawn on top carries the colour. */
+  map: {
+    water: "#b9cdd3",
+    park: "#d3d8bd",
+    road: "#f5f2e9",
+    roadMajor: "#ffffff",
+    building: "#d8d3c7"
+  }
 };
 var typography = {
   display: '"Jost", "Avenir Next", sans-serif',
@@ -88,6 +184,13 @@ var zIndex = {
   skipLink: "1000"
 };
 var breakpoints = { compact: "760px", expanded: "1024px", wide: "1400px" };
+var aspectRatio = {
+  square: "1 / 1",
+  video: "16 / 9",
+  photo: "4 / 3",
+  portrait: "3 / 4",
+  wide: "21 / 9"
+};
 var semanticDefs = {
   background: ref("color-paper"),
   surface: ref("color-panel"),
@@ -131,7 +234,52 @@ var semanticDefs = {
   textInfo: ref("color-info"),
   focusRing: ref("color-orange"),
   shadowColor: ref("color-deep"),
-  scrim: "color-mix(in srgb, var(--loidolt-shadow-color) 72%, transparent)"
+  scrim: "color-mix(in srgb, var(--loidolt-shadow-color) 72%, transparent)",
+  /*
+   * Data visualisation. `chart1`…`chart8` are categorical series; the ramps run from "least" (1)
+   * to "most" (last), whatever the theme; the diverging midpoint (4) is the neutral.
+   */
+  chart1: ref("color-series-1"),
+  chart2: ref("color-series-2"),
+  chart3: ref("color-series-3"),
+  chart4: ref("color-series-4"),
+  chart5: ref("color-series-5"),
+  chart6: ref("color-series-6"),
+  chart7: ref("color-series-7"),
+  chart8: ref("color-series-8"),
+  chartSequential1: ref("color-sequential-1"),
+  chartSequential2: ref("color-sequential-2"),
+  chartSequential3: ref("color-sequential-3"),
+  chartSequential4: ref("color-sequential-4"),
+  chartSequential5: ref("color-sequential-5"),
+  chartDiverging1: ref("color-diverging-1"),
+  chartDiverging2: ref("color-diverging-2"),
+  chartDiverging3: ref("color-diverging-3"),
+  chartDiverging4: ref("color-diverging-4"),
+  chartDiverging5: ref("color-diverging-5"),
+  chartDiverging6: ref("color-diverging-6"),
+  chartDiverging7: ref("color-diverging-7"),
+  /** Gains and losses: candlestick up/down, positive/negative bars. */
+  chartPositive: ref("color-success"),
+  chartNegative: ref("color-error"),
+  /* Basemap roles, read by the map style generator. */
+  mapLand: ref("color-paper"),
+  mapWater: ref("color-map-water"),
+  mapPark: ref("color-map-park"),
+  mapRoad: ref("color-map-road"),
+  mapRoadMajor: ref("color-map-road-major"),
+  mapBuilding: ref("color-map-building"),
+  mapBoundary: ref("color-line-strong"),
+  mapLabel: ref("color-deep"),
+  mapLabelHalo: ref("color-panel"),
+  /* Code highlighting, on the inverse surface where code blocks sit. */
+  syntaxKeyword: ref("color-syntax-keyword"),
+  syntaxString: ref("color-syntax-string"),
+  syntaxComment: ref("color-syntax-comment"),
+  syntaxConstant: ref("color-syntax-constant"),
+  syntaxFunction: ref("color-syntax-function"),
+  syntaxParameter: ref("color-syntax-parameter"),
+  syntaxPunctuation: ref("color-syntax-punctuation")
 };
 var PRIMITIVE_GROUPS = [
   ["color", colors],
@@ -141,7 +289,8 @@ var PRIMITIVE_GROUPS = [
   ["border", borders],
   ["shadow", shadows],
   ["motion", motion],
-  ["z", zIndex]
+  ["z", zIndex],
+  ["aspect", aspectRatio]
 ];
 var flattenInto = (prefix, tree, out) => {
   for (const [key, value] of Object.entries(tree)) {
@@ -211,8 +360,115 @@ var darkSemantic = {
   textInfo: "#85b6ca",
   focusRing: "#f0895c",
   shadowColor: "#000000",
-  scrim: "color-mix(in srgb, var(--loidolt-shadow-color) 78%, transparent)"
+  scrim: "color-mix(in srgb, var(--loidolt-shadow-color) 78%, transparent)",
+  chart1: "#e0672f",
+  chart2: "#6ea5bd",
+  chart3: "#93b287",
+  chart4: "#d9ab63",
+  chart5: "#c49ac0",
+  chart6: "#b8ad96",
+  chart7: "#6fb8a6",
+  chart8: "#c79a78",
+  chartSequential1: "#3a2a1d",
+  chartSequential2: "#6b4225",
+  chartSequential3: "#a4602f",
+  chartSequential4: "#d98a4d",
+  chartSequential5: "#f2bd8a",
+  chartDiverging1: "#85b6ca",
+  chartDiverging2: "#5a8ea3",
+  chartDiverging3: "#35596a",
+  chartDiverging4: "#3a3d34",
+  chartDiverging5: "#7a4428",
+  chartDiverging6: "#bf6a3a",
+  chartDiverging7: "#f0895c",
+  chartPositive: "#93b287",
+  chartNegative: "#e88b81",
+  mapLand: "#161814",
+  mapWater: "#1d2b31",
+  mapPark: "#1f271c",
+  mapRoad: "#2b2e26",
+  mapRoadMajor: "#3a3d34",
+  mapBuilding: "#24271f",
+  mapBoundary: "#787c6b",
+  mapLabel: "#ebe7dc",
+  mapLabelHalo: "#161814",
+  syntaxKeyword: "#a9441d",
+  syntaxString: "#3f5139",
+  syntaxComment: "#5f5b50",
+  syntaxConstant: "#7c4d17",
+  syntaxFunction: "#265162",
+  syntaxParameter: "#7a4a78",
+  syntaxPunctuation: "#474a42"
+};
+var roleVar = (role) => cssVarName([role]);
+var roleValue = (role, scheme = "light") => scheme === "dark" ? darkSemantic[role] : semantic[role];
+function resolveRoles(spec, scheme = "light", read = (role) => roleValue(role, scheme)) {
+  return Object.fromEntries(
+    Object.entries(spec).map(([key, value]) => [
+      key,
+      typeof value === "string" ? read(value) : value.map((role) => read(role))
+    ])
+  );
+}
+var chartRoles = {
+  categorical: ["chart1", "chart2", "chart3", "chart4", "chart5", "chart6", "chart7", "chart8"],
+  sequential: [
+    "chartSequential1",
+    "chartSequential2",
+    "chartSequential3",
+    "chartSequential4",
+    "chartSequential5"
+  ],
+  diverging: [
+    "chartDiverging1",
+    "chartDiverging2",
+    "chartDiverging3",
+    "chartDiverging4",
+    "chartDiverging5",
+    "chartDiverging6",
+    "chartDiverging7"
+  ],
+  positive: "chartPositive",
+  negative: "chartNegative",
+  text: "text",
+  muted: "textMuted",
+  axis: "border",
+  grid: "borderSoft",
+  surface: "surface",
+  background: "background",
+  accent: "accent"
+};
+var mapRoles = {
+  land: "mapLand",
+  water: "mapWater",
+  park: "mapPark",
+  road: "mapRoad",
+  roadMajor: "mapRoadMajor",
+  building: "mapBuilding",
+  boundary: "mapBoundary",
+  label: "mapLabel",
+  labelHalo: "mapLabelHalo",
+  accent: "accent",
+  text: "text",
+  surface: "surface",
+  focus: "focusRing",
+  categorical: chartRoles.categorical,
+  sequential: chartRoles.sequential
+};
+var syntaxRoles = {
+  background: "surfaceInverse",
+  text: "textInverse",
+  keyword: "syntaxKeyword",
+  string: "syntaxString",
+  comment: "syntaxComment",
+  constant: "syntaxConstant",
+  function: "syntaxFunction",
+  parameter: "syntaxParameter",
+  punctuation: "syntaxPunctuation"
 };
+var syntaxColors = (scheme = "light") => resolveRoles(syntaxRoles, scheme);
+var chartColors = (scheme = "light") => resolveRoles(chartRoles, scheme);
+var mapColors = (scheme = "light") => resolveRoles(mapRoles, scheme);
 var darkDeclarations = () => Object.entries(darkSemantic).map(([name, value]) => `  ${cssVarName([name])}: ${value};`);
 function generateDarkCss(scope = "attribute") {
   const body = ["  color-scheme: dark;", ...darkDeclarations()];
@@ -245,26 +501,43 @@ var tokens = {
   motion,
   zIndex,
   breakpoints,
+  aspectRatio,
   semantic,
   darkSemantic
 };
 var index_default = tokens;
 export {
+  aspectRatio,
   borders,
   breakpoints,
+  chartColors,
+  chartRoles,
   colors,
+  contrastRequirements,
   cssVarName,
   darkSemantic,
   index_default as default,
   flattenTokens,
   generateCss,
   generateDarkCss,
+  getContrastRatio,
+  getContrastTextColor,
+  getLuminance,
+  mapColors,
+  mapRoles,
+  meetsContrast,
   motion,
+  resolveRoles,
+  roleValue,
+  roleVar,
   semantic,
   shadows,
   sizing,
   spacing,
+  syntaxColors,
+  syntaxRoles,
   tokens,
   typography,
+  validateContrast,
   zIndex
 };

package/dist/tokens.css

@@ -18,6 +18,38 @@
   --loidolt-color-success: #3f5139;
   --loidolt-color-warning: #7c4d17;
   --loidolt-color-info: #265162;
+  --loidolt-color-series-1: #c65224;
+  --loidolt-color-series-2: #2f6f8a;
+  --loidolt-color-series-3: #5b7a3a;
+  --loidolt-color-series-4: #9a6a12;
+  --loidolt-color-series-5: #7a4a78;
+  --loidolt-color-series-6: #4d5a6a;
+  --loidolt-color-series-7: #2f7d6d;
+  --loidolt-color-series-8: #8a5a3c;
+  --loidolt-color-sequential-1: #ecd3b8;
+  --loidolt-color-sequential-2: #dea67a;
+  --loidolt-color-sequential-3: #c97a45;
+  --loidolt-color-sequential-4: #a4521f;
+  --loidolt-color-sequential-5: #6e3314;
+  --loidolt-color-diverging-1: #265162;
+  --loidolt-color-diverging-2: #4f8196;
+  --loidolt-color-diverging-3: #9cbac3;
+  --loidolt-color-diverging-4: #ddd7c9;
+  --loidolt-color-diverging-5: #e0a986;
+  --loidolt-color-diverging-6: #c96f3d;
+  --loidolt-color-diverging-7: #9b3a17;
+  --loidolt-color-syntax-keyword: #f0895c;
+  --loidolt-color-syntax-string: #a3c197;
+  --loidolt-color-syntax-comment: #b5ae9c;
+  --loidolt-color-syntax-constant: #e2b56c;
+  --loidolt-color-syntax-function: #8fc0d4;
+  --loidolt-color-syntax-parameter: #d3a8cf;
+  --loidolt-color-syntax-punctuation: #d8d2c4;
+  --loidolt-color-map-water: #b9cdd3;
+  --loidolt-color-map-park: #d3d8bd;
+  --loidolt-color-map-road: #f5f2e9;
+  --loidolt-color-map-road-major: #ffffff;
+  --loidolt-color-map-building: #d8d3c7;
   --loidolt-font-display: "Jost", "Avenir Next", sans-serif;
   --loidolt-font-utility: "Archivo", "Helvetica Neue", sans-serif;
   --loidolt-font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
@@ -71,6 +103,11 @@
   --loidolt-z-toast: 80;
   --loidolt-z-tooltip: 90;
   --loidolt-z-skip-link: 1000;
+  --loidolt-aspect-square: 1 / 1;
+  --loidolt-aspect-video: 16 / 9;
+  --loidolt-aspect-photo: 4 / 3;
+  --loidolt-aspect-portrait: 3 / 4;
+  --loidolt-aspect-wide: 21 / 9;
   --loidolt-background: var(--loidolt-color-paper);
   --loidolt-surface: var(--loidolt-color-panel);
   --loidolt-surface-alt: var(--loidolt-color-panel-alt);
@@ -106,4 +143,42 @@
   --loidolt-focus-ring: var(--loidolt-color-orange);
   --loidolt-shadow-color: var(--loidolt-color-deep);
   --loidolt-scrim: color-mix(in srgb, var(--loidolt-shadow-color) 72%, transparent);
+  --loidolt-chart-1: var(--loidolt-color-series-1);
+  --loidolt-chart-2: var(--loidolt-color-series-2);
+  --loidolt-chart-3: var(--loidolt-color-series-3);
+  --loidolt-chart-4: var(--loidolt-color-series-4);
+  --loidolt-chart-5: var(--loidolt-color-series-5);
+  --loidolt-chart-6: var(--loidolt-color-series-6);
+  --loidolt-chart-7: var(--loidolt-color-series-7);
+  --loidolt-chart-8: var(--loidolt-color-series-8);
+  --loidolt-chart-sequential-1: var(--loidolt-color-sequential-1);
+  --loidolt-chart-sequential-2: var(--loidolt-color-sequential-2);
+  --loidolt-chart-sequential-3: var(--loidolt-color-sequential-3);
+  --loidolt-chart-sequential-4: var(--loidolt-color-sequential-4);
+  --loidolt-chart-sequential-5: var(--loidolt-color-sequential-5);
+  --loidolt-chart-diverging-1: var(--loidolt-color-diverging-1);
+  --loidolt-chart-diverging-2: var(--loidolt-color-diverging-2);
+  --loidolt-chart-diverging-3: var(--loidolt-color-diverging-3);
+  --loidolt-chart-diverging-4: var(--loidolt-color-diverging-4);
+  --loidolt-chart-diverging-5: var(--loidolt-color-diverging-5);
+  --loidolt-chart-diverging-6: var(--loidolt-color-diverging-6);
+  --loidolt-chart-diverging-7: var(--loidolt-color-diverging-7);
+  --loidolt-chart-positive: var(--loidolt-color-success);
+  --loidolt-chart-negative: var(--loidolt-color-error);
+  --loidolt-map-land: var(--loidolt-color-paper);
+  --loidolt-map-water: var(--loidolt-color-map-water);
+  --loidolt-map-park: var(--loidolt-color-map-park);
+  --loidolt-map-road: var(--loidolt-color-map-road);
+  --loidolt-map-road-major: var(--loidolt-color-map-road-major);
+  --loidolt-map-building: var(--loidolt-color-map-building);
+  --loidolt-map-boundary: var(--loidolt-color-line-strong);
+  --loidolt-map-label: var(--loidolt-color-deep);
+  --loidolt-map-label-halo: var(--loidolt-color-panel);
+  --loidolt-syntax-keyword: var(--loidolt-color-syntax-keyword);
+  --loidolt-syntax-string: var(--loidolt-color-syntax-string);
+  --loidolt-syntax-comment: var(--loidolt-color-syntax-comment);
+  --loidolt-syntax-constant: var(--loidolt-color-syntax-constant);
+  --loidolt-syntax-function: var(--loidolt-color-syntax-function);
+  --loidolt-syntax-parameter: var(--loidolt-color-syntax-parameter);
+  --loidolt-syntax-punctuation: var(--loidolt-color-syntax-punctuation);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loidolt/theme-tokens",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Typed design tokens for Loidolt applications",
   "license": "MIT",
   "type": "module",