@rowkit/tokens 0.4.0 → 1.0.0-beta.1

package/dist/color.d.ts

@@ -1,577 +1,333 @@
 /**
- * Colour primitives and semantic mappings.
+ * Colour primitives and semantic mappings — the Windows 98 palette.
  *
- * ## How the scales were derived
+ * ## Where the values come from
  *
- * Every chromatic family shares one lightness ramp and one chroma envelope, so
- * `primary-600`, `danger-600` and `success-600` are the same perceptual weight
- * and can be swapped without relayering the design. Families differ only by
- * hue and a chroma factor.
+ * The primitives are the sixteen-colour VGA palette Windows 98 was drawn in,
+ * plus the handful of system colours the default "Windows Standard" scheme
+ * added on top of it: the light bevel grey, the title-bar gradient ends and
+ * the tooltip yellow. They are written as the exact sRGB hex values, not
+ * converted to another space: these colours are defined by their eight-bit
+ * channels, and a round trip through OKLCH would only add rounding to values
+ * that are already exact.
  *
- * Chroma at each step is clamped to the sRGB gamut boundary. OKLCH can express
- * colours outside sRGB, and browsers gamut-map them per their own rules — that
- * makes a token render differently on a P3 laptop than on an sRGB monitor.
- * Clamping trades a little vividness for identical output everywhere.
+ * The names and values mirror the Figma file's `primitives` collection, and
+ * the semantic map mirrors its `semantic` collection token for token, so a
+ * colour picked in the design is the colour the component paints.
  *
- * `warning` carries a lightness bump through its midtones: at a shared
- * lightness, yellow is far less saturated than blue or red, so the unbumped
- * steps read as muddy brown rather than amber.
- *
- * Contrast for every semantic pair is asserted in `contrast.test.ts` — the
- * ratios are a build gate, not a claim in a comment.
- */
-/** The eleven steps every colour family provides. */
-export declare const colorSteps: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
-/** One step of a colour family. */
-export type ColorStep = (typeof colorSteps)[number];
-/**
- * Cool-slate neutral (hue 264). Roughly 70% of the pixels in a data table:
- * page background, row borders, muted labels, table chrome.
- */
-export declare const neutral: {
-    readonly 50: "oklch(0.984 0.003 264)";
-    readonly 100: "oklch(0.968 0.004 264)";
-    readonly 200: "oklch(0.928 0.006 264)";
-    readonly 300: "oklch(0.869 0.01 264)";
-    readonly 400: "oklch(0.704 0.018 264)";
-    readonly 500: "oklch(0.551 0.024 264)";
-    readonly 600: "oklch(0.446 0.027 264)";
-    readonly 700: "oklch(0.373 0.028 264)";
-    readonly 800: "oklch(0.279 0.03 264)";
-    readonly 900: "oklch(0.21 0.033 264)";
-    readonly 950: "oklch(0.13 0.036 264)";
-};
-/**
- * Ink blue (hue 255).
- *
- * Cool and current — the step after warm espresso. Chroma stays low so a
- * solid button is ink, not a brand shout, and the selected-row wash
- * (`primary-50`) reads as a cool mist instead of a pink one.
- */
-export declare const primary: {
-    readonly 50: "oklch(0.975 0.011 255)";
-    readonly 100: "oklch(0.948 0.022 255)";
-    readonly 200: "oklch(0.90 0.034 255)";
-    readonly 300: "oklch(0.80 0.05 255)";
-    readonly 400: "oklch(0.68 0.07 255)";
-    readonly 500: "oklch(0.52 0.09 255)";
-    readonly 600: "oklch(0.44 0.095 255)";
-    readonly 700: "oklch(0.38 0.095 255)";
-    /** Solid actions — ink blue, deep enough for white labels. */
-    readonly 800: "oklch(0.32 0.09 255)";
-    readonly 900: "oklch(0.27 0.075 255)";
-    readonly 950: "oklch(0.19 0.05 255)";
-};
-/** Green (hue 152). Reserved for successful outcomes, never for brand accent. */
-export declare const success: {
-    readonly 50: "oklch(0.97 0.014 152)";
-    readonly 100: "oklch(0.936 0.036 152)";
-    readonly 200: "oklch(0.885 0.064 152)";
-    readonly 300: "oklch(0.809 0.097 152)";
-    readonly 400: "oklch(0.715 0.145 152)";
-    readonly 500: "oklch(0.623 0.162 152)";
-    readonly 600: "oklch(0.546 0.142 152)";
-    readonly 700: "oklch(0.488 0.127 152)";
-    readonly 800: "oklch(0.442 0.115 152)";
-    readonly 900: "oklch(0.396 0.103 152)";
-    readonly 950: "oklch(0.282 0.073 152)";
-};
-/** Amber (hue 75), lightness-bumped through the midtones. See the module note. */
-export declare const warning: {
-    readonly 50: "oklch(0.97 0.016 75)";
-    readonly 100: "oklch(0.936 0.04 75)";
-    readonly 200: "oklch(0.885 0.071 75)";
-    readonly 300: "oklch(0.849 0.108 75)";
-    readonly 400: "oklch(0.785 0.162 75)";
-    readonly 500: "oklch(0.723 0.15 75)";
-    readonly 600: "oklch(0.616 0.128 75)";
-    readonly 700: "oklch(0.528 0.11 75)";
-    readonly 800: "oklch(0.442 0.092 75)";
-    readonly 900: "oklch(0.396 0.082 75)";
-    readonly 950: "oklch(0.282 0.059 75)";
-};
-/** Red (hue 25). Destructive actions and error states. */
-export declare const danger: {
-    readonly 50: "oklch(0.97 0.014 25)";
-    readonly 100: "oklch(0.936 0.032 25)";
-    readonly 200: "oklch(0.885 0.06 25)";
-    readonly 300: "oklch(0.809 0.107 25)";
-    readonly 400: "oklch(0.715 0.17 25)";
-    readonly 500: "oklch(0.623 0.214 25)";
-    readonly 600: "oklch(0.546 0.218 25)";
-    readonly 700: "oklch(0.488 0.195 25)";
-    readonly 800: "oklch(0.442 0.165 25)";
-    readonly 900: "oklch(0.396 0.135 25)";
-    readonly 950: "oklch(0.282 0.086 25)";
-};
-/**
- * Greys keyed by OKLCH lightness × 1000, so `gray-922` is lightness 0.922.
- *
- * Most steps stay zero-chroma — the reference design's quiet base. A few carry
- * a cool cast (hue 264, the same as {@link neutral}): lighter hairlines and
- * soft recessed surfaces. That is rowkit's own signal inside an otherwise
- * clean, reference-shaped palette — enough to read as itself on a long session,
- * not enough to look like a tinted theme.
- */
-export declare const gray: {
-    /** Soft cool page. Slightly off pure white so a day of table work is less glare. */
-    readonly 988: "oklch(0.988 0.002 264)";
-    /** the reference `--primary-foreground`, `--foreground` (dark). */
-    readonly 985: "oklch(0.985 0 0)";
-    /**
-     * Cool recessed surface — muted toolbars, row hover, quiet chips.
-     *
-     * Lighter and cooler than the reference `--muted` (0.97 0 0): same job, less
-     * ink on the page.
-     */
-    readonly 972: "oklch(0.972 0.003 264)";
-    /** the reference `--secondary`, `--muted`, `--accent` — kept for dark primary fill. */
-    readonly 970: "oklch(0.97 0 0)";
-    /**
-     * Cool decorative hairline / recessed fill step. Lighter than the reference
-     * `--border` (0.922) — table rules, card outlines, and secondary button fill
-     * (`surface-active`) that must read as a surface next to white outline chrome.
-     */
-    readonly 940: "oklch(0.940 0.004 264)";
-    /** the reference `--border`. Kept for pressed fills that still need a step of weight. */
-    readonly 922: "oklch(0.922 0 0)";
-    /**
-     * Cool emphasised hairline. rowkit's; the reference design has no "strong border".
-     * Softer than the old 0.87 step so structure reads without shouting.
-     */
-    readonly 905: "oklch(0.905 0.006 264)";
-    /** Emphasised hairline (legacy weight). Prefer {@link gray[905]} for new chrome. */
-    readonly 870: "oklch(0.87 0 0)";
-    /** the reference `--muted-foreground` (dark), where it clears AA at 7.63:1. */
-    readonly 708: "oklch(0.708 0 0)";
-    /**
-     * rowkit's correction to the reference `--ring` and `--input` in light mode.
-     *
-     * the reference design puts them at 0.708 and 0.922, which measure 2.59:1 and 1.26:1
-     * against a white page — a focus ring and a control boundary that both fail
-     * WCAG 1.4.11.
-     *
-     * Not the mathematical minimum. Solving in floating point gave 0.669 and a
-     * tidy 3.00:1; the browser paints `#959595` and axe measured **2.995:1**,
-     * because a colour is quantised to eight bits per channel before anyone sees
-     * it. Anything solved exactly onto a threshold lands on whichever side the
-     * rounding chooses. 0.635 is 3.45:1 against the page and 3.17:1 against
-     * `surface-subtle`, which clears the bar on both sides of the rounding.
-     */
-    readonly 635: "oklch(0.635 0 0)";
-    /**
-     * Cool control boundary. Softer and cooler than the a11y floor at 0.635, still
-     * clears 3:1 on the page, a card and a recessed toolbar — so inputs speak the
-     * same language as the cool hairlines without failing WCAG 1.4.11.
-     */
-    readonly 642: "oklch(0.642 0.012 264)";
-    /** the reference `--ring` (dark), 4.18:1 against the dark page. */
-    readonly 556: "oklch(0.556 0 0)";
-    /**
-     * rowkit's correction to the reference `--muted-foreground` in light mode.
-     *
-     * The reference design's 0.556 is 4.73:1 on white but only 4.34:1 on `--muted`, the
-     * recessed surface a table header sits on — and a table header is the single
-     * most common use this token has.
-     *
-     * 0.547 was the first attempt and shipped 4.51:1 in floating point; axe,
-     * reading the painted `#717171`, called it 4.47:1 and failed twenty-four
-     * stories. See {@link gray[635]} — same lesson, same cause. 0.535 measures
-     * 4.75:1 on `--muted` and 5.17:1 on the page.
-     */
-    readonly 535: "oklch(0.535 0 0)";
-    /** Pressed row in dark mode. */
-    readonly 371: "oklch(0.371 0 0)";
-    /** the reference `--secondary`, `--muted`, `--accent` (dark). */
-    readonly 269: "oklch(0.269 0 0)";
-    /** the reference `--primary` (light), `--card` and `--popover` (dark). */
-    readonly 205: "oklch(0.205 0 0)";
-    /** the reference `--foreground` (light), `--background` (dark). */
-    readonly 145: "oklch(0.145 0 0)";
-};
-/**
- * The reference design's destructive red, clamped into sRGB. Keyed by lightness, like `gray`.
- *
- * the reference design publishes `oklch(0.577 0.245 27.325)`, and that chroma **does not fit
- * in sRGB** — 0.235 is the maximum at this lightness and hue. The difference is
- * invisible; what it buys is a colour that renders identically on an sRGB
- * monitor and a P3 laptop, instead of one each browser gamut-maps by its own
- * rules. rowkit clamps every chromatic primitive for this reason, and
- * `color.test.ts` enforces it.
- *
- * One red serves both themes. The reference design's dark `--destructive` is a lighter
- * `oklch(0.704 …)`, which carries its white label at **2.86:1** — the single
- * worst failure in the reference design's default set. Reusing the light value gives 4.90:1
- * on the label in both themes and still clears 4.04:1 against the dark page.
- */
-export declare const red: {
-    /** Soft text on a dark subtle wash. Chroma clamped for sRGB. */
-    readonly 850: "oklch(0.85 0.08 25)";
-    /** Destructive fill. The reference design's lightness, chroma clamped. */
-    readonly 577: "oklch(0.577 0.235 27.325)";
-    /** Destructive hover — darkens in both themes, so the white label improves. */
-    readonly 520: "oklch(0.52 0.212 27.325)";
-    /** Soft border on a dark subtle wash. */
-    readonly 350: "oklch(0.38 0.055 25)";
-    /** Soft fill in dark mode — quiet red wash, not a solid brick. */
-    readonly 260: "oklch(0.32 0.045 25)";
-};
-/**
- * Success and warning, at the reference design's weight. Keyed by lightness, like `gray`.
- *
- * the reference design has no equivalent to copy, so the rule is consistency rather than
- * fidelity: the solid step sits at the same lightness band as `red-577` and
- * carries a white label, so a success, a warning and a destructive button are
- * the same perceptual weight and only differ in hue.
- *
- * That is a real change for warning, which used to be bright amber with dark
- * text. Bright amber is the loudest thing on a the reference design page — the language is
- * built on restraint, and one saturated chip undoes it. Chroma is clamped to
- * the sRGB boundary at every step, as everywhere else.
+ * Contrast for every semantic pair a component produces is asserted in
+ * `contrast.test.ts` — the ratios are a build gate, not a claim in a comment.
  */
-export declare const green: {
-    /** Badge fill, light. */
-    readonly 950: "oklch(0.95 0.05 152)";
-    /** Badge border, light. */
-    readonly 880: "oklch(0.88 0.05 152)";
-    /** Badge text, dark. */
-    readonly 850: "oklch(0.85 0.12 152)";
-    /** Solid fill, both themes. White label at 4.56:1. */
-    readonly 550: "oklch(0.55 0.144 152)";
-    /** Solid hover — darkens, so the white label improves. */
-    readonly 520: "oklch(0.52 0.136 152)";
-    /** Badge text, light. */
-    readonly 400: "oklch(0.4 0.105 152)";
-    /** Badge border, dark. */
-    readonly 350: "oklch(0.35 0.092 152)";
-    /** Badge fill, dark. */
-    readonly 260: "oklch(0.26 0.068 152)";
+/** The sixteen-colour VGA palette, as Windows 98 used it. Only the twelve the design uses are listed. */
+export declare const vga: {
+    readonly black: "#000000";
+    readonly white: "#ffffff";
+    /** The face of every window, button and dialog. */
+    readonly silver: "#c0c0c0";
+    /** Bevel shadows, disabled text, the borders of a field. */
+    readonly gray: "#808080";
+    /** Selection, the active title bar, the default primary. */
+    readonly navy: "#000080";
+    /** Hyperlinks. */
+    readonly blue: "#0000ff";
+    /** The desktop. */
+    readonly teal: "#008080";
+    readonly green: "#008000";
+    readonly olive: "#808000";
+    readonly yellow: "#ffff00";
+    readonly maroon: "#800000";
+    readonly red: "#ff0000";
 };
-/** Warning, mirroring {@link green} step for step. */
-export declare const amber: {
-    readonly 950: "oklch(0.95 0.04 75)";
-    readonly 880: "oklch(0.88 0.05 75)";
-    readonly 850: "oklch(0.85 0.12 75)";
-    /** Solid fill, both themes. White label at 4.96:1. */
-    readonly 550: "oklch(0.55 0.116 75)";
-    readonly 520: "oklch(0.52 0.109 75)";
-    readonly 400: "oklch(0.4 0.084 75)";
-    readonly 350: "oklch(0.35 0.074 75)";
-    readonly 260: "oklch(0.26 0.055 75)";
-};
-/**
- * White at a fraction of opacity, for dark-mode borders.
- *
- * Alpha, not a solid grey: a grey tuned for `--background` draws too hard a
- * line once the same border sits on `--card`. The reference uses 10% / 15%;
- * rowkit softens the decorative hairline to 8% so dense tables stay quiet in
- * dark mode the same way the cool light hairline does.
- */
-export declare const whiteAlpha: {
-    /** Soft decorative hairline in dark mode. */
-    readonly 8: "oklch(1 0 0 / 8%)";
-    /** the reference dark `--border`. */
-    readonly 10: "oklch(1 0 0 / 10%)";
-    /** Emphasised dark hairline / the reference dark `--input`. */
-    readonly 15: "oklch(1 0 0 / 15%)";
+/** The system colours Windows 98 added on top of VGA. */
+export declare const win98: {
+    /** The inner light edge of a raised bevel (`3D Light`). */
+    readonly light: "#dfdfdf";
+    /** Secondary text a step lighter than black. */
+    readonly 'dark-gray': "#404040";
+    /** The light end of the active title-bar gradient. */
+    readonly 'title-blue': "#1084d0";
+    /** The light end of the inactive title-bar gradient. */
+    readonly 'title-gray': "#b5b5b5";
+    /** Tooltip background (`Info`). */
+    readonly info: "#ffffe1";
 };
 /**
- * Every primitive colour, keyed by the CSS custom property it becomes.
+ * Every primitive colour, keyed by the CSS custom property it becomes:
+ * `--color-vga-silver`, `--color-win98-info`.
  *
  * These are the only place a literal colour value appears in rowkit. Everything
  * else — semantic tokens, component variants — references one of these.
  */
 export declare const colorPrimitives: {
-    readonly "danger-50": string;
-    readonly "danger-100": string;
-    readonly "danger-200": string;
-    readonly "danger-300": string;
-    readonly "danger-400": string;
-    readonly "danger-500": string;
-    readonly "danger-600": string;
-    readonly "danger-700": string;
-    readonly "danger-800": string;
-    readonly "danger-900": string;
-    readonly "danger-950": string;
-    readonly "warning-50": string;
-    readonly "warning-100": string;
-    readonly "warning-200": string;
-    readonly "warning-300": string;
-    readonly "warning-400": string;
-    readonly "warning-500": string;
-    readonly "warning-600": string;
-    readonly "warning-700": string;
-    readonly "warning-800": string;
-    readonly "warning-900": string;
-    readonly "warning-950": string;
-    readonly "success-50": string;
-    readonly "success-100": string;
-    readonly "success-200": string;
-    readonly "success-300": string;
-    readonly "success-400": string;
-    readonly "success-500": string;
-    readonly "success-600": string;
-    readonly "success-700": string;
-    readonly "success-800": string;
-    readonly "success-900": string;
-    readonly "success-950": string;
-    readonly "primary-50": string;
-    readonly "primary-100": string;
-    readonly "primary-200": string;
-    readonly "primary-300": string;
-    readonly "primary-400": string;
-    readonly "primary-500": string;
-    readonly "primary-600": string;
-    readonly "primary-700": string;
-    readonly "primary-800": string;
-    readonly "primary-900": string;
-    readonly "primary-950": string;
-    readonly "neutral-50": string;
-    readonly "neutral-100": string;
-    readonly "neutral-200": string;
-    readonly "neutral-300": string;
-    readonly "neutral-400": string;
-    readonly "neutral-500": string;
-    readonly "neutral-600": string;
-    readonly "neutral-700": string;
-    readonly "neutral-800": string;
-    readonly "neutral-900": string;
-    readonly "neutral-950": string;
-    readonly "white-alpha-8": string;
-    readonly "white-alpha-10": string;
-    readonly "white-alpha-15": string;
-    readonly "amber-400": string;
-    readonly "amber-950": string;
-    readonly "amber-850": string;
-    readonly "amber-520": string;
-    readonly "amber-350": string;
-    readonly "amber-260": string;
-    readonly "amber-880": string;
-    readonly "amber-550": string;
-    readonly "green-400": string;
-    readonly "green-950": string;
-    readonly "green-850": string;
-    readonly "green-520": string;
-    readonly "green-350": string;
-    readonly "green-260": string;
-    readonly "green-880": string;
-    readonly "green-550": string;
-    readonly "red-850": string;
-    readonly "red-577": string;
-    readonly "red-520": string;
-    readonly "red-350": string;
-    readonly "red-260": string;
-    readonly "gray-988": string;
-    readonly "gray-985": string;
-    readonly "gray-972": string;
-    readonly "gray-970": string;
-    readonly "gray-940": string;
-    readonly "gray-922": string;
-    readonly "gray-905": string;
-    readonly "gray-870": string;
-    readonly "gray-708": string;
-    readonly "gray-635": string;
-    readonly "gray-642": string;
-    readonly "gray-556": string;
-    readonly "gray-535": string;
-    readonly "gray-371": string;
-    readonly "gray-269": string;
-    readonly "gray-205": string;
-    readonly "gray-145": string;
-    readonly white: "oklch(1 0 0)";
-    readonly black: "oklch(0 0 0)";
+    readonly "win98-light": "#dfdfdf";
+    readonly "win98-dark-gray": "#404040";
+    readonly "win98-title-blue": "#1084d0";
+    readonly "win98-title-gray": "#b5b5b5";
+    readonly "win98-info": "#ffffe1";
+    readonly "vga-black": "#000000";
+    readonly "vga-white": "#ffffff";
+    readonly "vga-silver": "#c0c0c0";
+    readonly "vga-gray": "#808080";
+    readonly "vga-navy": "#000080";
+    readonly "vga-blue": "#0000ff";
+    readonly "vga-teal": "#008080";
+    readonly "vga-green": "#008000";
+    readonly "vga-olive": "#808000";
+    readonly "vga-yellow": "#ffff00";
+    readonly "vga-maroon": "#800000";
+    readonly "vga-red": "#ff0000";
 };
 /** A reference to a primitive colour, as a CSS `var()` expression. */
 export type ColorRef = `var(--color-${string})`;
 /**
- * Light-mode semantic colours.
+ * Semantic colours.
  *
  * Semantic tokens never hold a literal colour — each one points at a primitive
  * through `var()`, so re-theming means repointing references rather than
- * hunting down hex codes. `semantic.test.ts` enforces this.
+ * hunting down hex codes. `color.test.ts` enforces this.
+ *
+ * Windows 98 is a grey world: most surfaces are the same silver, and depth
+ * comes from bevels rather than from a lighter or darker fill. So several
+ * surface tokens below share a value. They stay separate tokens because they
+ * are separate override points — a theme that wants a hovered row to change
+ * colour repoints `accent` without touching `muted`.
  */
-export declare const semanticColorLight: {
-    /**
-     * Page background, behind all surfaces.
-     *
-     * Soft cool off-white rather than the reference pure white — less glare over
-     * a long session, and enough lift that a white `card` still reads as a plane.
-     */
+export declare const semanticColor: {
+    /** The face of a window: the page behind the content. */
     readonly background: `var(--color-${string})`;
-    /** Cards, panels, table bodies — the plane content sits on. The reference `--card`. */
+    /** The desktop a window sits on. Docs and demo backdrops. */
+    readonly desktop: `var(--color-${string})`;
+    /** Panels and dialogs. Same face as the window; the bevel separates them. */
     readonly card: `var(--color-${string})`;
-    /**
-     * Table headers, toolbars: a surface that recedes slightly.
-     *
-     * Cool and a touch lighter than the reference `--muted`. Same role as
-     * `accent` out of the box — separate override points, not different colours.
-     */
+    /** Toolbars and table headers. */
     readonly muted: `var(--color-${string})`;
-    /** Row hover. */
+    /** Row hover. Windows 98 has none — the token is here to be repointed. */
     readonly accent: `var(--color-${string})`;
-    /** Row press / active. One step past hover; the reference design has no press token. */
+    /** A pressed row or toggle. The pressed bevel carries the state, not the fill. */
     readonly 'surface-active': `var(--color-${string})`;
-    /**
-     * Selected table row. Quiet primary wash — distinct from hover, not a shout.
-     */
+    /** A selected row or list item: navy, with `on-selected` text. */
     readonly 'surface-selected': `var(--color-${string})`;
-    /** Disabled control background. */
+    /** A disabled control keeps the face colour; its text goes grey and embossed. */
     readonly 'surface-disabled': `var(--color-${string})`;
     /**
      * Loading placeholder fill.
      *
-     * Its own token rather than a reuse of `surface-active`, which means "this
-     * row is being pressed". A skeleton is never interactive, so borrowing an
-     * interaction token would tie the two together for any future re-theme.
-     *
-     * Exempt from contrast rules: skeletons are `aria-hidden` decoration
-     * standing in for content that has not arrived, so there is nothing for a
-     * reader to perceive and WCAG 1.4.11 does not apply.
+     * Exempt from contrast rules: skeletons are `aria-hidden` decoration standing
+     * in for content that has not arrived, so WCAG 1.4.11 does not apply.
      */
     readonly skeleton: `var(--color-${string})`;
-    /** Primary body and heading text. The reference `--foreground`. */
+    /** The inside of a text field, list or table body: white inside a sunken bevel. */
+    readonly input: `var(--color-${string})`;
+    /** Tooltip bubble. */
+    readonly 'tooltip-bg': `var(--color-${string})`;
+    /** Body and heading text. */
     readonly foreground: `var(--color-${string})`;
     /**
-     * Secondary text, column labels, help text. The reference `--muted-foreground`.
-     *
-     * `gray-535`, not the reference design's 0.556. The same trap the old `neutral-500` fell
-     * into: a table header is muted text on `surface-subtle`, and the reference design's value
-     * reaches 4.73:1 on white but only 4.34:1 on the recessed surface this token
-     * is most often used against. Nine thousandths of lightness buy the pass.
+     * Secondary text. Black, like body text: Windows 98 never greys out text
+     * that can still be read and acted on — grey means disabled.
      */
     readonly 'muted-foreground': `var(--color-${string})`;
     /** Placeholders and de-emphasised metadata. */
     readonly 'text-subtle': `var(--color-${string})`;
-    /** Text on a disabled control. */
+    /** Disabled text, always drawn with {@link semanticColor['text-disabled-emboss']} under it. */
     readonly 'text-disabled': `var(--color-${string})`;
-    /**
-     * Decorative hairline: row separators, card outlines.
-     *
-     * Cool and lighter than the reference 0.922. Deliberately below 3:1 — do not
-     * use it for the boundary of an interactive control; see
-     * {@link semanticColorLight['input']}.
-     */
+    /** The white copy, one pixel right and down, that embosses disabled text. */
+    readonly 'text-disabled-emboss': `var(--color-${string})`;
+    /** Text on a selected row. */
+    readonly 'on-selected': `var(--color-${string})`;
+    /** Hyperlinks. */
+    readonly link: `var(--color-${string})`;
+    /** Separators and the frame of a group. Decorative, below 3:1 on purpose. */
     readonly border: `var(--color-${string})`;
-    /** Emphasised decorative border: dividers that need to read as structure. */
+    /** A frame that has to read as an edge: the outline of a default button. */
     readonly 'border-strong': `var(--color-${string})`;
-    /** Barely-there separation inside a dense group. */
+    /** The faintest rule, inside a dense group. */
     readonly 'border-subtle': `var(--color-${string})`;
     /**
-     * Boundary of an interactive control — text inputs, selects, outlined
-     * buttons.
-     *
-     * Quiet on purpose (structure without severity). Resting edges sit near the
-     * decorative hairline; the focus treatment (`border-ring` + ring) is what
-     * carries WCAG 1.4.11. Matching the reference design's soft resting edge
-     * rather than a 3:1 ink outline that shouted next to every field.
-     */
-    readonly input: `var(--color-${string})`;
-    /**
-     * Focus ring. Never remove the ring — recolour it.
-     *
-     * Soft silver — the payment-form / shadcn weight (`gray-708`), not ink.
-     * Intentionally under 3:1 as a solid; the visible treatment is
-     * `border-ring` plus a translucent outer ring, not a black halo.
-     * Every control that focuses (Button, Input, Select, Dialog close,
-     * Pagination, FilterBar chips, DataTable, Toast) reads this same token.
+     * Focus. Drawn as a 1px dotted ring inside the control, around its label.
+     * Black, so it clears 3:1 on every surface rowkit paints.
      */
     readonly ring: `var(--color-${string})`;
-    /** Base colour shadows are mixed from. */
+    /** Base colour for shadows. */
     readonly shadow: `var(--color-${string})`;
-    readonly 'neutral-solid': `var(--color-${string})`;
-    readonly 'neutral-solid-hover': `var(--color-${string})`;
-    readonly 'neutral-on-solid': `var(--color-${string})`;
-    readonly 'neutral-subtle': `var(--color-${string})`;
-    readonly 'neutral-on-subtle': `var(--color-${string})`;
-    readonly 'neutral-border': `var(--color-${string})`;
+    /** Outer light edge of a raised bevel, inner one of a sunken bevel. */
+    readonly 'bevel-highlight': `var(--color-${string})`;
+    /** Inner light edge of a raised bevel. */
+    readonly 'bevel-light': `var(--color-${string})`;
+    /** Inner dark edge of a raised bevel. */
+    readonly 'bevel-shadow': `var(--color-${string})`;
     /**
-     * Ink-blue solid — cool, not a black brick and not a saturated brand blue.
-     * `primary-800` ≈ `oklch(0.32 0.09 255)`.
+     * Outer dark edge of a raised bevel. Being black, it is what gives every
+     * control a boundary of well over 3:1 against the face (WCAG 1.4.11).
      */
-    readonly 'primary-solid': `var(--color-${string})`;
-    readonly 'primary-solid-hover': `var(--color-${string})`;
-    readonly 'primary-on-solid': `var(--color-${string})`;
-    readonly 'primary-subtle': `var(--color-${string})`;
-    readonly 'primary-on-subtle': `var(--color-${string})`;
-    readonly 'primary-border': `var(--color-${string})`;
-    readonly 'success-solid': `var(--color-${string})`;
-    readonly 'success-solid-hover': `var(--color-${string})`;
-    readonly 'success-on-solid': `var(--color-${string})`;
-    readonly 'success-subtle': `var(--color-${string})`;
-    readonly 'success-on-subtle': `var(--color-${string})`;
-    readonly 'success-border': `var(--color-${string})`;
-    readonly 'warning-solid': `var(--color-${string})`;
-    readonly 'warning-solid-hover': `var(--color-${string})`;
-    readonly 'warning-on-solid': `var(--color-${string})`;
-    readonly 'warning-subtle': `var(--color-${string})`;
-    readonly 'warning-on-subtle': `var(--color-${string})`;
-    readonly 'warning-border': `var(--color-${string})`;
-    readonly 'danger-solid': `var(--color-${string})`;
-    readonly 'danger-solid-hover': `var(--color-${string})`;
-    readonly 'danger-on-solid': `var(--color-${string})`;
-    readonly 'danger-subtle': `var(--color-${string})`;
-    readonly 'danger-on-subtle': `var(--color-${string})`;
-    readonly 'danger-border': `var(--color-${string})`;
-};
-/**
- * Dark-mode semantic colours, applied under `.dark`.
- *
- * Soft ink fills invert on dark pages: a near-white solid with dark type,
- * rather than a mid-grey that disappears into the chrome.
- */
-export declare const semanticColorDark: {
-    readonly background: `var(--color-${string})`;
-    readonly card: `var(--color-${string})`;
-    readonly muted: `var(--color-${string})`;
-    readonly accent: `var(--color-${string})`;
-    readonly 'surface-active': `var(--color-${string})`;
-    readonly 'surface-selected': `var(--color-${string})`;
-    readonly 'surface-disabled': `var(--color-${string})`;
-    readonly skeleton: `var(--color-${string})`;
-    readonly foreground: `var(--color-${string})`;
-    readonly 'muted-foreground': `var(--color-${string})`;
-    readonly 'text-subtle': `var(--color-${string})`;
-    readonly 'text-disabled': `var(--color-${string})`;
-    readonly border: `var(--color-${string})`;
-    readonly 'border-strong': `var(--color-${string})`;
-    readonly 'border-subtle': `var(--color-${string})`;
-    readonly input: `var(--color-${string})`;
+    readonly 'bevel-dark': `var(--color-${string})`;
+    /** Active title bar, left end of the gradient. The title text sits on this end. */
+    readonly 'titlebar-from': `var(--color-${string})`;
+    /** Active title bar, right end of the gradient. */
+    readonly 'titlebar-to': `var(--color-${string})`;
+    /** Inactive title bar, left end of the gradient. */
+    readonly 'titlebar-inactive-from': `var(--color-${string})`;
+    /** Inactive title bar, right end of the gradient. */
+    readonly 'titlebar-inactive-to': `var(--color-${string})`;
+    /** Active title text. */
+    readonly 'titlebar-foreground': `var(--color-${string})`;
     /**
-     * Soft focus — white at the same quiet weight as the control border, not a
-     * bright primary wash. Reads as a silver edge on dark surfaces.
+     * Inactive title text. Black, not Windows 98's silver: silver on the grey
+     * gradient is about 2:1 and fails 4.5:1; black is 5.3:1 on `#808080` and
+     * 11:1 on `#b5b5b5`.
      */
-    readonly ring: `var(--color-${string})`;
-    readonly shadow: `var(--color-${string})`;
+    readonly 'titlebar-inactive-foreground': `var(--color-${string})`;
+    /** Neutral fill: a solid neutral badge, and anything filled in the neutral colour. */
     readonly 'neutral-solid': `var(--color-${string})`;
+    /** Neutral fill under the pointer. */
     readonly 'neutral-solid-hover': `var(--color-${string})`;
+    /** Text and icons on the neutral fill. */
     readonly 'neutral-on-solid': `var(--color-${string})`;
+    /** Neutral tint: the face of a subtle neutral badge or callout. */
     readonly 'neutral-subtle': `var(--color-${string})`;
+    /** Neutral text and icons, on its tint and on the page. */
     readonly 'neutral-on-subtle': `var(--color-${string})`;
+    /** The edge of a subtle or outlined neutral badge. */
     readonly 'neutral-border': `var(--color-${string})`;
+    /** Primary fill — the accent: a solid primary badge, a selected item, the default action in a theme that colours it. */
     readonly 'primary-solid': `var(--color-${string})`;
+    /** Primary fill under the pointer. */
     readonly 'primary-solid-hover': `var(--color-${string})`;
+    /** Text and icons on the primary fill. */
     readonly 'primary-on-solid': `var(--color-${string})`;
+    /** Primary tint: the face of a subtle primary badge or callout. */
     readonly 'primary-subtle': `var(--color-${string})`;
+    /** Primary text and icons, on its tint and on the page. */
     readonly 'primary-on-subtle': `var(--color-${string})`;
+    /** The edge of a subtle or outlined primary badge. */
     readonly 'primary-border': `var(--color-${string})`;
+    /** Success fill: a solid success badge, and anything filled in the success colour. */
     readonly 'success-solid': `var(--color-${string})`;
+    /** Success fill under the pointer. */
     readonly 'success-solid-hover': `var(--color-${string})`;
+    /** Text and icons on the success fill. */
     readonly 'success-on-solid': `var(--color-${string})`;
+    /** Success tint: the face of a subtle success badge or callout. */
     readonly 'success-subtle': `var(--color-${string})`;
+    /** Success text and icons, on its tint and on the page. */
     readonly 'success-on-subtle': `var(--color-${string})`;
+    /** The edge of a subtle or outlined success badge. */
     readonly 'success-border': `var(--color-${string})`;
+    /**
+     * Warning fill: a solid warning badge, and anything filled in the warning colour. Yellow carries black, never white: white on `#ffff00` is 1.07:1;
+     * its edge is olive, because yellow on silver has almost no edge of its own.
+     */
     readonly 'warning-solid': `var(--color-${string})`;
+    /** Warning fill under the pointer. */
     readonly 'warning-solid-hover': `var(--color-${string})`;
+    /** Text and icons on the warning fill. */
     readonly 'warning-on-solid': `var(--color-${string})`;
+    /** Warning tint: the face of a subtle warning badge or callout. */
     readonly 'warning-subtle': `var(--color-${string})`;
+    /** Warning text and icons, on its tint and on the page. */
     readonly 'warning-on-subtle': `var(--color-${string})`;
+    /** The edge of a subtle or outlined warning badge. */
     readonly 'warning-border': `var(--color-${string})`;
+    /** Danger fill: a solid danger badge, and anything filled in the danger colour. */
     readonly 'danger-solid': `var(--color-${string})`;
+    /** Danger fill under the pointer. */
     readonly 'danger-solid-hover': `var(--color-${string})`;
+    /** Text and icons on the danger fill. */
     readonly 'danger-on-solid': `var(--color-${string})`;
+    /** Danger tint: the face of a subtle danger badge or callout. */
     readonly 'danger-subtle': `var(--color-${string})`;
+    /** Danger text and icons, on its tint and on the page. */
     readonly 'danger-on-subtle': `var(--color-${string})`;
+    /** The edge of a subtle or outlined danger badge. */
     readonly 'danger-border': `var(--color-${string})`;
+    /** A plain button, a spin or drop button, a table's sort header. */
+    readonly control: `var(--color-${string})`;
+    /** Text and icons on a plain button. */
+    readonly 'control-foreground': `var(--color-${string})`;
+    /** A plain button under the pointer. */
+    readonly 'control-hover': `var(--color-${string})`;
+    /** A plain button while it is held. */
+    readonly 'control-active': `var(--color-${string})`;
+    /** The default button of a form or dialog — Enter's target. */
+    readonly 'control-primary': `var(--color-${string})`;
+    /** Text and icons on the default button. */
+    readonly 'control-primary-foreground': `var(--color-${string})`;
+    /** The default button under the pointer. */
+    readonly 'control-primary-hover': `var(--color-${string})`;
+    /** The default button while it is held. */
+    readonly 'control-primary-active': `var(--color-${string})`;
+    /** A flat toolbar button while hovered and while held. */
+    readonly 'control-ghost-hover': `var(--color-${string})`;
+    readonly 'control-ghost-active': `var(--color-${string})`;
+    /** The face of a latched toggle, under its pattern. */
+    readonly 'control-latched': `var(--color-${string})`;
+    /** A latched default button. A toggle is never the default, but if one latches it keeps its colour. */
+    readonly 'control-primary-latched': `var(--color-${string})`;
+    /** The box of a checked checkbox or radio, and the mark inside it. */
+    readonly checked: `var(--color-${string})`;
+    readonly 'on-checked': `var(--color-${string})`;
+    /** A list that drops from a trigger: a select's options. */
+    readonly popover: `var(--color-${string})`;
+    readonly 'popover-border': `var(--color-${string})`;
+    /** The ring a theme draws around a focused control, outside its edge. */
+    readonly 'focus-ring': `var(--color-${string})`;
+    /** A window's caption buttons; one fill per button, for themes that colour them. */
+    readonly caption: `var(--color-${string})`;
+    readonly 'caption-foreground': `var(--color-${string})`;
+    readonly 'caption-close': `var(--color-${string})`;
+    readonly 'caption-minimize': `var(--color-${string})`;
+    readonly 'caption-maximize': `var(--color-${string})`;
+    readonly 'caption-inactive': `var(--color-${string})`;
+    /** A data table's column headers. */
+    readonly 'table-header': `var(--color-${string})`;
+    readonly 'table-header-foreground': `var(--color-${string})`;
+    /** Every other row of a data table. Windows 98 does not stripe. */
+    readonly 'table-stripe': `var(--color-${string})`;
+    /** A data table row under the pointer. Windows 98 does not highlight it. */
+    readonly 'table-row-hover': `var(--color-${string})`;
+    /** The channel a progress bar or a scroll thumb runs in, and what fills it. */
+    readonly track: `var(--color-${string})`;
+    readonly progress: `var(--color-${string})`;
+    readonly 'scroll-thumb': `var(--color-${string})`;
+    /** The channel a scroll bar's thumb runs in, under its pattern. */
+    readonly 'scroll-track': `var(--color-${string})`;
+    /** The frame of a tooltip. */
+    readonly 'tooltip-border': `var(--color-${string})`;
+    /**
+     * The inside of a group box's frame, and the face around it — behind the
+     * legend and the frame's edge. Both the window's silver in Windows 98.
+     */
+    readonly groupbox: `var(--color-${string})`;
+    readonly 'groupbox-face': `var(--color-${string})`;
+    /** A toast's ✕: the caption button's silver in Windows 98, a soft grey disc elsewhere. */
+    readonly 'toast-close': `var(--color-${string})`;
+    readonly 'toast-close-foreground': `var(--color-${string})`;
+    /** «Loading…» in a dropped list: plain text in Windows 98, the subtle grey elsewhere. */
+    readonly 'loading-foreground': `var(--color-${string})`;
+    /** The strip that holds a searchable list's search box: the window face in Windows 98, nothing elsewhere. */
+    readonly 'select-search': `var(--color-${string})`;
+    /** A pager's buttons: raised command buttons in Windows 98, flat elsewhere. */
+    readonly pager: `var(--color-${string})`;
+    readonly 'pager-hover': `var(--color-${string})`;
+    readonly 'pager-active': `var(--color-${string})`;
+    /** The strip a filter bar sits on. */
+    readonly 'filter-bar': `var(--color-${string})`;
+    /** A filter chip: its face, its edge and its text. */
+    readonly chip: `var(--color-${string})`;
+    readonly 'chip-border': `var(--color-${string})`;
+    readonly 'chip-foreground': `var(--color-${string})`;
+    /** The face of a chip's ✕ at rest: the chip's own white in Windows 98. */
+    readonly 'chip-remove': `var(--color-${string})`;
+    /**
+     * The value of a read-only field that holds focus — a drop-down list's —
+     * highlighted the way Windows 98 marks it, and the text on it.
+     */
+    readonly 'field-highlight': `var(--color-${string})`;
+    readonly 'on-field-highlight': `var(--color-${string})`;
+    /** The text caret in a field. */
+    readonly 'field-caret': `var(--color-${string})`;
+    /** The buttons inside a field: a select's drop button, a number's spin buttons. */
+    readonly 'field-button': `var(--color-${string})`;
 };
 /** Names of every semantic colour token. */
-export type SemanticColorName = keyof typeof semanticColorLight;
+export type SemanticColorName = keyof typeof semanticColor;