@rowkit/tokens 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,70 @@
+# @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-card`, `--color-muted-foreground`, `--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-card`, `text-muted-foreground`, `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-muted);
+  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
+
+Design language based on [shadcn/ui](https://ui.shadcn.com) by shadcn, adapted for Vue. shadcn/ui is MIT licensed; rowkit adopts its token values and class recipes, not its code.

package/dist/blur.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Backdrop blur radii.
+ *
+ * One entry, and named for its job rather than a t-shirt size. Blur is not a
+ * scale rowkit designs with — it appears in exactly one place, behind a modal,
+ * and a second value would be a decision nobody has had to make yet.
+ *
+ * Deliberately small. The scrim separates the planes; the blur only stops the
+ * page behind from competing for the eye. Anything heavier reads as an effect
+ * and makes the content behind unrecognisable, which defeats the reason a
+ * modal shows its context at all.
+ */
+export declare const blur: {
+    /** The dialog scrim. The reference `backdrop-blur-xs`. */
+    readonly overlay: "4px";
+};
+/** Names of every blur token. */
+export type BlurName = keyof typeof blur;

package/dist/color.d.ts

@@ -97,6 +97,171 @@ export declare const danger: {
     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. Lighter than the reference `--border` (0.922) and
+     * barely tinted — table row rules and card outlines that stay visible without
+     * dividing the page into boxes.
+     */
+    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: {
+    /** 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)";
+};
+/**
+ * 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.
+ */
+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)";
+};
+/** 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%)";
+};
 /**
  * Every primitive colour, keyed by the CSS custom property it becomes.
  *
@@ -159,6 +324,44 @@ export declare const colorPrimitives: {
     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-520": string;
+    readonly "amber-880": string;
+    readonly "amber-850": string;
+    readonly "amber-550": string;
+    readonly "amber-350": string;
+    readonly "amber-260": string;
+    readonly "green-400": string;
+    readonly "green-950": string;
+    readonly "green-520": string;
+    readonly "green-880": string;
+    readonly "green-850": string;
+    readonly "green-550": string;
+    readonly "green-350": string;
+    readonly "green-260": string;
+    readonly "red-577": string;
+    readonly "red-520": 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)";
 };
@@ -172,17 +375,29 @@ export type ColorRef = `var(--color-${string})`;
  * hunting down hex codes. `semantic.test.ts` enforces this.
  */
 export declare const semanticColorLight: {
-    /** Page background, behind all surfaces. */
+    /**
+     * 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.
+     */
     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})`;
+    /** Cards, panels, table bodies — the plane content sits on. The reference `--card`. */
+    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.
+     */
+    readonly muted: `var(--color-${string})`;
     /** Row hover. */
-    readonly 'surface-hover': `var(--color-${string})`;
-    /** Row press / active. */
+    readonly accent: `var(--color-${string})`;
+    /** Row press / active. One step past hover; the reference design has no press token. */
     readonly 'surface-active': `var(--color-${string})`;
-    /** Selected table row. */
+    /**
+     * Selected table row. Quiet primary wash — distinct from hover, not a shout.
+     */
     readonly 'surface-selected': `var(--color-${string})`;
     /** Disabled control background. */
     readonly 'surface-disabled': `var(--color-${string})`;
@@ -198,18 +413,17 @@ export declare const semanticColorLight: {
      * 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})`;
+    /** Primary body and heading text. The reference `--foreground`. */
+    readonly foreground: `var(--color-${string})`;
     /**
-     * Secondary text, column labels, help text.
+     * Secondary text, column labels, help text. The reference `--muted-foreground`.
      *
-     * `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.
+     * `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.
      */
-    readonly 'text-muted': `var(--color-${string})`;
+    readonly 'muted-foreground': `var(--color-${string})`;
     /** Placeholders and de-emphasised metadata. */
     readonly 'text-subtle': `var(--color-${string})`;
     /** Text on a disabled control. */
@@ -217,8 +431,9 @@ export declare const semanticColorLight: {
     /**
      * 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']}.
+     * 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']}.
      */
     readonly border: `var(--color-${string})`;
     /** Emphasised decorative border: dividers that need to read as structure. */
@@ -229,14 +444,18 @@ export declare const semanticColorLight: {
      * 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`).
+     * Cooler and a touch lighter than the old pure `gray-635`, still ≥3:1 on the
+     * page, a card and a toolbar. Matches the cool hairline language without
+     * dropping below WCAG 1.4.11.
+     */
+    readonly input: `var(--color-${string})`;
+    /**
+     * Focus ring. Never remove the ring — recolour it.
+     *
+     * Matches the brand primary so focused controls and the primary button speak
+     * one language. Clears 1.4.11 against the page and recessed surfaces.
      */
-    readonly 'border-control': `var(--color-${string})`;
-    /** Focus ring. Never remove the ring — recolour it. */
-    readonly 'focus-ring': `var(--color-${string})`;
+    readonly ring: `var(--color-${string})`;
     /** Base colour shadows are mixed from. */
     readonly shadow: `var(--color-${string})`;
     readonly 'neutral-solid': `var(--color-${string})`;
@@ -281,22 +500,22 @@ export declare const semanticColorLight: {
  */
 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 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 text: `var(--color-${string})`;
-    readonly 'text-muted': `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 'border-control': `var(--color-${string})`;
-    readonly 'focus-ring': `var(--color-${string})`;
+    readonly input: `var(--color-${string})`;
+    readonly ring: `var(--color-${string})`;
     readonly shadow: `var(--color-${string})`;
     readonly 'neutral-solid': `var(--color-${string})`;
     readonly 'neutral-solid-hover': `var(--color-${string})`;