@loidolt/theme-tokens 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -1,53 +1,3 @@
-/**
- * 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.
  *
@@ -61,7 +11,10 @@ declare function getContrastTextColor(background: string, { dark, light }?: {
 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";
@@ -82,6 +35,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";
@@ -224,13 +230,215 @@ 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;
+};
+/**
+ * The shape-and-voice layer: the non-colour roles a preset restyles. Like the colour roles, each
+ * names a *job* (the corner of a control, the padding of a table cell, the case of a label) rather
+ * than a component, so one value moves every component that does that job.
+ *
+ * Every default reproduces the original hand-written value exactly; a preset that sets none of
+ * them looks identical to the base system.
+ */
+declare const roleDefs: {
+    /** Buttons, boxed fields, toggle groups, switches, swatches, tooltips. */
+    readonly radiusControl: TokenRef;
+    /** Rows and items inside a rounded container (menu items, list rows, filmstrip frames). */
+    readonly radiusInner: "0px";
+    /** Cards, panels, tables, alerts, code blocks, thumbnails. */
+    readonly radiusSurface: TokenRef;
+    /** Dialogs, popovers, menus, toasts. Drawers stay square: they are anchored to an edge. */
+    readonly radiusOverlay: TokenRef;
+    /** Width of the keyboard focus ring. WCAG 2.4.13 wants at least 2px; keep it there. */
+    readonly strokeFocus: "2px";
+    /** Selected-tab, active-nav and selected-row indicators. */
+    readonly strokeIndicator: "2px";
+    /** The status bar on the leading edge of an alert or toast. */
+    readonly strokeAccent: "3px";
+    readonly padControlX: "0.85rem";
+    readonly padControlXSm: "0.65rem";
+    readonly padControlXLg: "1.2rem";
+    readonly padControlY: "0.5rem";
+    readonly padControlYSm: "0.38rem";
+    /** Underlined fields: vertical, then horizontal. Boxed fields use `pad-control-x-sm` inline. */
+    readonly padField: "0.45rem 0.15rem";
+    readonly padItem: "0.65rem 0.55rem";
+    readonly padCell: "0.7rem 0.8rem";
+    readonly padCallout: "0.8rem 1rem";
+    readonly padSurface: TokenRef;
+    readonly padOverlay: "1rem 1.25rem";
+    readonly padPopover: "0.45rem";
+    readonly padBarX: "1.35rem";
+    readonly padPane: "1.25rem";
+    readonly padPage: TokenRef;
+    /** Between a field's label, control and help text. */
+    readonly gapField: "0.35rem";
+    /** Between the buttons of a dialog footer or an empty state. */
+    readonly gapActions: TokenRef;
+    readonly labelTransform: "uppercase";
+    readonly labelTracking: TokenRef;
+    readonly labelTrackingWide: TokenRef;
+    readonly labelWeight: "400";
+    readonly controlTransform: "uppercase";
+    readonly controlTracking: "0.08em";
+    readonly controlWeight: "400";
+    readonly headingWeight: "500";
+    readonly strongWeight: "600";
 };
 /** Every custom property the package emits, in declaration order. */
 declare function flattenTokens(): Array<[string, string | TokenRef]>;
 /** Serializes the token set to CSS. The build writes this to `dist/tokens.css`. */
 declare function generateCss(): string;
 /** Semantic roles with their refs resolved to concrete values, for TS/JS consumers. */
-declare const semantic: { readonly [K in keyof typeof semanticDefs]: string; };
+declare const semantic: {
+    readonly background: string;
+    readonly surface: string;
+    readonly surfaceAlt: string;
+    readonly surfaceSunken: string;
+    readonly surfacePaper: string;
+    readonly surfaceInverse: string;
+    readonly surfaceInput: string;
+    readonly text: string;
+    readonly textMuted: string;
+    readonly textInverse: string;
+    readonly textAccent: string;
+    readonly border: string;
+    readonly borderSoft: string;
+    readonly borderStrong: string;
+    readonly borderControl: string;
+    readonly borderSunken: string;
+    readonly accent: string;
+    readonly accentHover: string;
+    readonly onAccent: string;
+    readonly danger: string;
+    readonly dangerHover: string;
+    readonly onDanger: string;
+    readonly textDanger: string;
+    readonly success: string;
+    readonly onSuccess: string;
+    readonly textSuccess: string;
+    readonly warning: string;
+    readonly onWarning: string;
+    readonly textWarning: string;
+    readonly info: string;
+    readonly onInfo: string;
+    readonly textInfo: string;
+    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;
+};
+/** Shape and voice roles with their refs resolved to concrete values. */
+declare const roles: {
+    readonly radiusControl: string;
+    readonly radiusInner: string;
+    readonly radiusSurface: string;
+    readonly radiusOverlay: string;
+    readonly strokeFocus: string;
+    readonly strokeIndicator: string;
+    readonly strokeAccent: string;
+    readonly padControlX: string;
+    readonly padControlXSm: string;
+    readonly padControlXLg: string;
+    readonly padControlY: string;
+    readonly padControlYSm: string;
+    readonly padField: string;
+    readonly padItem: string;
+    readonly padCell: string;
+    readonly padCallout: string;
+    readonly padSurface: string;
+    readonly padOverlay: string;
+    readonly padPopover: string;
+    readonly padBarX: string;
+    readonly padPane: string;
+    readonly padPage: string;
+    readonly gapField: string;
+    readonly gapActions: string;
+    readonly labelTransform: string;
+    readonly labelTracking: string;
+    readonly labelTrackingWide: string;
+    readonly labelWeight: string;
+    readonly controlTransform: string;
+    readonly controlTracking: string;
+    readonly controlWeight: string;
+    readonly headingWeight: string;
+    readonly strongWeight: string;
+};
 /**
  * Reference dark theme. Only the semantic tier is redefined — the primitives stay put — which
  * is the same move a consumer makes for their own theme. Values are literal rather than linked
@@ -276,7 +484,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.
@@ -304,6 +626,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";
@@ -426,6 +801,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";
@@ -463,8 +876,316 @@ 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";
+    };
+    readonly roles: {
+        readonly radiusControl: string;
+        readonly radiusInner: string;
+        readonly radiusSurface: string;
+        readonly radiusOverlay: string;
+        readonly strokeFocus: string;
+        readonly strokeIndicator: string;
+        readonly strokeAccent: string;
+        readonly padControlX: string;
+        readonly padControlXSm: string;
+        readonly padControlXLg: string;
+        readonly padControlY: string;
+        readonly padControlYSm: string;
+        readonly padField: string;
+        readonly padItem: string;
+        readonly padCell: string;
+        readonly padCallout: string;
+        readonly padSurface: string;
+        readonly padOverlay: string;
+        readonly padPopover: string;
+        readonly padBarX: string;
+        readonly padPane: string;
+        readonly padPage: string;
+        readonly gapField: string;
+        readonly gapActions: string;
+        readonly labelTransform: string;
+        readonly labelTracking: string;
+        readonly labelTrackingWide: string;
+        readonly labelWeight: string;
+        readonly controlTransform: string;
+        readonly controlTracking: string;
+        readonly controlWeight: string;
+        readonly headingWeight: string;
+        readonly strongWeight: string;
     };
 };
 type ThemeTokens = typeof tokens;
 
-export { type ContrastLevel, type ContrastValidation, type TextSize, type ThemeTokens, type TokenRef, aspectRatio, borders, breakpoints, colors, contrastRequirements, cssVarName, darkSemantic, tokens as default, flattenTokens, generateCss, generateDarkCss, getContrastRatio, getContrastTextColor, getLuminance, meetsContrast, motion, semantic, shadows, sizing, spacing, tokens, typography, validateContrast, zIndex };
+/**
+ * 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;
+/** A full set of colour roles as concrete values — a preset's `resolved.light` or `.dark`. */
+type ColorRoles = {
+    readonly [K in SemanticRole]: string;
+};
+interface ContrastCheck {
+    /** What the pair is, e.g. `muted text on surface`. */
+    name: string;
+    foreground: string;
+    background: string;
+    ratio: number;
+    /** 4.5 for text (WCAG 1.4.3), 3 for control boundaries and focus rings (WCAG 1.4.11). */
+    required: number;
+    pass: boolean;
+}
+/**
+ * Every pairing the stylesheets actually draw, with the ratio WCAG AA asks of it.
+ *
+ * Small utility text (`--loidolt-font-size-xs`) is well under 18.66px, so every text pair needs
+ * the full 4.5:1 rather than the large-text allowance. Decorative hairlines (`border`,
+ * `border-soft`) are deliberately lighter and exempt; `border-control` is not, because it is the
+ * only thing identifying an input.
+ */
+declare function contrastPairs(t: ColorRoles): Array<[name: string, fg: string, bg: string, required: number]>;
+/**
+ * Checks a colour role set against WCAG AA. Run it in a test over your own preset's
+ * `resolved.light` and `resolved.dark`:
+ *
+ * ```ts
+ * expect(auditContrast(myPreset.resolved.dark).filter((check) => !check.pass)).toEqual([]);
+ * ```
+ */
+declare function auditContrast(colors: ColorRoles): ContrastCheck[];
+
+/** A colour role: `surface`, `textMuted`, `onAccent`, … */
+type ColorRole = keyof typeof semanticDefs;
+/** A shape or voice role: `radiusControl`, `padCell`, `labelTransform`, … */
+type Role = keyof typeof roleDefs;
+type Overrides<T> = {
+    readonly [K in keyof T]?: T[K] extends string ? string : Overrides<T[K]>;
+};
+/**
+ * The primitive scales a preset may move. Colour primitives are deliberately absent: colour is
+ * restyled through the colour *roles*, which is also the only way it survives subtree scoping
+ * (a `var()` resolves where it is declared, so a role declared on `:root` would never see a
+ * primitive overridden further down).
+ */
+interface PresetPrimitives {
+    readonly typography?: Overrides<typeof typography>;
+    readonly spacing?: Overrides<typeof spacing>;
+    readonly sizing?: Overrides<typeof sizing>;
+    readonly borders?: Overrides<typeof borders>;
+    readonly shadows?: Overrides<typeof shadows>;
+    readonly motion?: Overrides<typeof motion>;
+}
+type ColorOverrides = {
+    readonly [K in ColorRole]?: string;
+};
+interface PresetDefinition<Light extends ColorOverrides = ColorOverrides> {
+    /** Lowercase identifier, used in `data-preset="…"` and file names. */
+    name: string;
+    /** Human-readable name for pickers. Defaults to the capitalised `name`. */
+    label?: string;
+    description?: string;
+    /** Start from another preset instead of the base system, then apply this definition on top. */
+    extends?: Preset;
+    primitives?: PresetPrimitives;
+    roles?: {
+        readonly [K in Role]?: string;
+    };
+    /**
+     * One knob for every padding and gap role (`pad-*`, `gap-*`) this definition does not set
+     * itself: `0.75` is a quarter tighter, `1.2` a fifth roomier. Between 0.5 and 1.5.
+     */
+    density?: number;
+    /**
+     * Colour roles for each scheme. `dark` must restate every role `light` changes — a light-only
+     * override would leave the dark scheme pairing the new colour with the old one.
+     */
+    colors?: {
+        light: Light;
+        dark: {
+            readonly [K in keyof Light]-?: string;
+        } & ColorOverrides;
+    };
+    /** Stylesheet URLs `@import`ed ahead of the preset, typically webfonts the preset names. */
+    fontImport?: string | readonly string[];
+}
+interface Preset {
+    readonly name: string;
+    readonly label: string;
+    readonly description: string | undefined;
+    readonly fontImports: readonly string[];
+    /** Custom property declarations per block, values as they are written to CSS. */
+    readonly declarations: {
+        /** Primitives and shape/voice roles — scheme-independent. */
+        readonly shape: ReadonlyArray<readonly [name: string, value: string]>;
+        readonly light: ReadonlyArray<readonly [name: string, value: string]>;
+        readonly dark: ReadonlyArray<readonly [name: string, value: string]>;
+    };
+    /** Every role with its references followed to a concrete value, for JS consumers and tests. */
+    readonly resolved: {
+        readonly roles: {
+            readonly [K in Role]: string;
+        };
+        readonly light: ColorRoles;
+        readonly dark: ColorRoles;
+    };
+}
+/**
+ * Defines a named style set: colours for both schemes plus the shape and voice of every
+ * component, compiled to a stylesheet by {@link generatePresetCss}.
+ *
+ * ```ts
+ * export const studio = definePreset({
+ *   name: 'studio',
+ *   roles: { radiusControl: '4px', labelTransform: 'none' },
+ *   colors: {
+ *     light: { accent: '#0b6bcb', accentHover: '#0956a3' },
+ *     dark: { accent: '#5aa7f0', accentHover: '#7ab8f3' },
+ *   },
+ * });
+ * ```
+ *
+ * Every preset is complete: whatever it does not set comes from the base system (or from the
+ * preset it `extends`), so nesting one preset inside another restyles the subtree fully rather
+ * than blending the two.
+ */
+declare function definePreset<const Light extends ColorOverrides & {
+    readonly [K in Exclude<keyof Light, ColorRole>]: never;
+} = Record<never, never>>(definition: PresetDefinition<Light>): Preset;
+interface PresetCssOptions {
+    /**
+     * - `attribute` (default): applies under `[data-preset="<name>"]`, on `<html>` or any subtree,
+     *   so several presets can ship side by side and switch at runtime.
+     * - `root`: applies to `:root` outright, for an app that only ever uses this one preset.
+     */
+    scope?: 'attribute' | 'root';
+    /**
+     * Which block to emit, mirroring the base `tokens` / `dark` / `dark-auto` trio:
+     * - `light` (default): shape, voice and the light colours, plus any `fontImport`.
+     * - `dark`: the dark colours under `data-theme="dark"`.
+     * - `dark-auto`: the same, plus a `prefers-color-scheme` rule an explicit light choice overrides.
+     */
+    scheme?: 'light' | 'dark' | 'dark-auto';
+}
+/** Serializes one block of a preset to CSS. See {@link presetStylesheets} for the full set. */
+declare function generatePresetCss(preset: Preset, options?: PresetCssOptions): string;
+/**
+ * Every stylesheet a preset ships, keyed by file name: `<name>.css`, `<name>-dark.css` and
+ * `<name>-dark-auto.css` scoped to `data-preset`, and the same three with `.root` for a
+ * single-preset app. Write them from a build script to ship your own preset the way the
+ * built-in ones are shipped.
+ */
+declare function presetStylesheets(preset: Preset): Record<string, string>;
+
+/**
+ * The Loidolt look, packed tighter for data-dense tools. Coarse pointers still get their 44px
+ * targets: those rules key off the pointer, not the preset.
+ */
+declare const compact: Preset;
+
+/** The base system as a preset: square, uppercase utility voice, warm paper and orange. */
+declare const loidolt: Preset;
+
+/** Rounded corners, sentence-case labels and a cool neutral palette with a blue accent. */
+declare const soft: Preset;
+
+/** The presets this package ships, default first. */
+declare const builtInPresets: readonly [Preset, Preset, Preset];
+/** Names of the built-in presets, for `createTheme({ presets })` and pickers. */
+type BuiltInPresetName = (typeof builtInPresets)[number]['name'];
+
+/**
+ * Design tokens for Loidolt applications.
+ *
+ * Three tiers:
+ * - **Primitives** (`--loidolt-color-*`, `--loidolt-space-*`, …) are the raw palette and scales.
+ * - **Colour roles** (`--loidolt-surface`, `--loidolt-text`, `--loidolt-chart-1`, …) name what a
+ *   colour is *for*.
+ * - **Shape and voice roles** (`--loidolt-radius-control`, `--loidolt-pad-cell`, …) do the same
+ *   for corners, strokes, density and typographic voice.
+ *
+ * Stylesheets and components consume only the role tiers, so a consumer can restyle the
+ * system — or add a dark mode, or a whole preset — by redefining roles alone.
+ */
+
+export { type BuiltInPresetName, type ChartColors, type ColorOverrides, type ColorRole, type ColorRoles, type ColorScheme, type ContrastCheck, type ContrastLevel, type ContrastValidation, type MapColors, type Preset, type PresetCssOptions, type PresetDefinition, type PresetPrimitives, type ResolvedRoles, type Role, type RoleSpec, type SemanticRole, type SyntaxColors, type TextSize, type ThemeTokens, type TokenRef, aspectRatio, auditContrast, borders, breakpoints, builtInPresets, chartColors, chartRoles, colors, compact, contrastPairs, contrastRequirements, cssVarName, darkSemantic, tokens as default, definePreset, flattenTokens, generateCss, generateDarkCss, generatePresetCss, getContrastRatio, getContrastTextColor, getLuminance, loidolt, mapColors, mapRoles, meetsContrast, motion, presetStylesheets, resolveRoles, roleValue, roleVar, roles, semantic, shadows, sizing, soft, spacing, syntaxColors, syntaxRoles, tokens, typography, validateContrast, zIndex };