@rowkit/tokens 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikolai Kushner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @rowkit/tokens
+
+[![npm](https://img.shields.io/npm/v/@rowkit/tokens?color=3b5bdb)](https://www.npmjs.com/package/@rowkit/tokens)
+[![license](https://img.shields.io/npm/l/@rowkit/tokens)](https://github.com/NikolaiKushner/rowkit/blob/main/LICENSE)
+
+The design tokens behind [rowkit](https://www.npmjs.com/package/rowkit) — colour, spacing, typography, radii, shadows, layers and motion.
+
+Usable on its own. Nothing here depends on Vue, so a chart library, a design tool or an email template can read the same values the components use.
+
+**[Live reference](https://rowkit.dev/foundations/tokens)** · **[GitHub](https://github.com/NikolaiKushner/rowkit)**
+
+## Install
+
+```bash
+npm i @rowkit/tokens
+```
+
+## Two layers
+
+**Primitives** are the raw ramps: `--color-primary-600` is one specific blue and means nothing on its own. **Semantic** tokens name a role — `--color-surface`, `--color-text-muted`, `--color-border` — and point at a primitive through `var()`.
+
+Only the semantic layer changes under `.dark`, which is what makes dark mode a matter of repointing references rather than hunting hex codes.
+
+## Use
+
+As a Tailwind v4 theme:
+
+```css
+@import 'tailwindcss';
+@import '@rowkit/tokens/css';
+```
+
+Every token becomes a theme value, so `bg-surface`, `text-text-muted`, `p-4`, `rounded-md` and `shadow-lg` resolve to the scales above.
+
+As CSS custom properties, for anything Tailwind does not cover:
+
+```css
+.my-thing {
+  background: var(--color-surface-subtle);
+  border-radius: var(--radius-md);
+}
+```
+
+Or in TypeScript, fully typed, when a value has to reach JavaScript:
+
+```ts
+import { tokens } from '@rowkit/tokens'
+
+tokens.color.primary[600] // 'oklch(0.546 0.209 259)'
+
+const series = [tokens.color.primary[500], tokens.color.success[500]]
+```
+
+`tokens` is grouped by scale rather than flattened, so `tokens.color.primary[600]` narrows to its literal type and autocompletes at every level.
+
+## Notes on the values
+
+**Colour is OKLCH, clamped to sRGB.** Every chromatic family shares one lightness ramp, so `primary-600`, `danger-600` and `success-600` carry the same perceptual weight. Chroma is clamped to the sRGB gamut on purpose: OKLCH can express colours outside it, and browsers gamut-map those by their own rules — which makes a token render differently on a P3 laptop than on an sRGB monitor.
+
+**Contrast is asserted, not claimed.** Every semantic pairing is checked against WCAG AA in the package's own tests, in both themes.
+
+**Spacing keys are multiples of 4px.** `4` is 1rem, `2` is 8px — the convention most Vue and Tailwind developers already carry.
+
+**Layer order is a build gate.** `z-index.test.ts` asserts a modal sits above an overlay, a tooltip above everything, and that consecutive layers stay at least 100 apart.
+
+## License
+
+MIT © Nikolai Kushner

package/dist/color.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Colour primitives and semantic mappings.
+ *
+ * ## How the scales were derived
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * `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)";
+};
+/** Brand blue (hue 259). Drives links, focus rings and primary actions. */
+export declare const primary: {
+    readonly 50: "oklch(0.97 0.014 259)";
+    readonly 100: "oklch(0.936 0.03 259)";
+    readonly 200: "oklch(0.885 0.055 259)";
+    readonly 300: "oklch(0.809 0.095 259)";
+    readonly 400: "oklch(0.715 0.147 259)";
+    readonly 500: "oklch(0.623 0.201 259)";
+    readonly 600: "oklch(0.546 0.209 259)";
+    readonly 700: "oklch(0.488 0.187 259)";
+    readonly 800: "oklch(0.442 0.165 259)";
+    readonly 900: "oklch(0.396 0.135 259)";
+    readonly 950: "oklch(0.282 0.086 259)";
+};
+/** 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)";
+};
+/**
+ * Every primitive colour, keyed by the CSS custom property it becomes.
+ *
+ * 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: "oklch(1 0 0)";
+    readonly black: "oklch(0 0 0)";
+};
+/** A reference to a primitive colour, as a CSS `var()` expression. */
+export type ColorRef = `var(--color-${string})`;
+/**
+ * Light-mode 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.
+ */
+export declare const semanticColorLight: {
+    /** Page background, behind all surfaces. */
+    readonly background: `var(--color-${string})`;
+    /** Cards, panels, table bodies — the plane content sits on. */
+    readonly surface: `var(--color-${string})`;
+    /** Table headers, toolbars: a surface that recedes slightly. */
+    readonly 'surface-subtle': `var(--color-${string})`;
+    /** Row hover. */
+    readonly 'surface-hover': `var(--color-${string})`;
+    /** Row press / active. */
+    readonly 'surface-active': `var(--color-${string})`;
+    /** Selected table row. */
+    readonly 'surface-selected': `var(--color-${string})`;
+    /** Disabled control background. */
+    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.
+     */
+    readonly skeleton: `var(--color-${string})`;
+    /** Primary body and heading text. */
+    readonly text: `var(--color-${string})`;
+    /**
+     * Secondary text, column labels, help text.
+     *
+     * `neutral-600`, not `500`. A table header is muted text on `surface-subtle`,
+     * and at `500` that pairing reached only 4.41:1 — passing on white, failing
+     * WCAG 1.4.3 on the recessed surface this token is most often used against.
+     * `600` clears it at 6.90:1 and is still 2.3× lighter than `text`, so the
+     * hierarchy survives.
+     */
+    readonly 'text-muted': `var(--color-${string})`;
+    /** Placeholders and de-emphasised metadata. */
+    readonly 'text-subtle': `var(--color-${string})`;
+    /** Text on a disabled control. */
+    readonly 'text-disabled': `var(--color-${string})`;
+    /**
+     * Decorative hairline: row separators, card outlines.
+     *
+     * Deliberately below 3:1 against the surface. Do not use it for the boundary
+     * of an interactive control — see {@link semanticColorLight['border-control']}.
+     */
+    readonly border: `var(--color-${string})`;
+    /** Emphasised decorative border: dividers that need to read as structure. */
+    readonly 'border-strong': `var(--color-${string})`;
+    /** Barely-there separation inside a dense group. */
+    readonly 'border-subtle': `var(--color-${string})`;
+    /**
+     * Boundary of an interactive control — text inputs, checkboxes, outlined
+     * buttons.
+     *
+     * WCAG 1.4.11 requires 3:1 against the adjacent surface for the visual
+     * boundary of a UI component. `border` manages only 1.24:1 and
+     * `border-strong` 1.49:1, so neither is legal here; this token is the
+     * lightest neutral that clears the bar (4.83:1 on `surface`).
+     */
+    readonly 'border-control': `var(--color-${string})`;
+    /** Focus ring. Never remove the ring — recolour it. */
+    readonly 'focus-ring': `var(--color-${string})`;
+    /** Base colour shadows are mixed from. */
+    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})`;
+    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`.
+ *
+ * Solid fills use the bright `400` step with dark text rather than mirroring
+ * light mode's `600` with white text. On a near-black page a `600` fill only
+ * reaches 3.6–4.4:1 against the background — the button itself becomes hard to
+ * locate even though its label is legible. The `400` fill scores 7.4–8.5:1 on
+ * both label and background.
+ */
+export declare const semanticColorDark: {
+    readonly background: `var(--color-${string})`;
+    readonly surface: `var(--color-${string})`;
+    readonly 'surface-subtle': `var(--color-${string})`;
+    readonly 'surface-hover': `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 text: `var(--color-${string})`;
+    readonly 'text-muted': `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 'border-control': `var(--color-${string})`;
+    readonly 'focus-ring': `var(--color-${string})`;
+    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})`;
+    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})`;
+};
+/** Names of every semantic colour token. */
+export type SemanticColorName = keyof typeof semanticColorLight;

package/dist/css.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Emits the Tailwind v4 `@theme` block for the rowkit token set.
+ *
+ * The TypeScript objects are the single source of truth; this function derives
+ * the stylesheet from them, so the two cannot drift. `css.test.ts` asserts that
+ * every token in every scale reaches the output.
+ *
+ * Dark mode works by repointing *semantic* tokens under `.dark`. Primitives are
+ * emitted once and never change — `--color-primary-600` is the same colour in
+ * both themes; what changes is which primitive `--color-primary-solid` points
+ * at. That is why the theme can flip without a single hardcoded colour moving.
+ *
+ * @returns The complete stylesheet, ready to write to disk.
+ */
+export declare function buildThemeCss(): string;