@rowkit/tokens 0.1.1 → 0.3.0

package/README.md

@@ -17,7 +17,7 @@ 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()`.
+**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.
 
@@ -30,13 +30,13 @@ As a Tailwind v4 theme:
 @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.
+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-surface-subtle);
+  background: var(--color-muted);
   border-radius: var(--radius-md);
 }
 ```
@@ -46,7 +46,7 @@ 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)'
+tokens.color.primary[800] // 'oklch(0.31 0.038 48)' — warm espresso
 
 const series = [tokens.color.primary[500], tokens.color.success[500]]
 ```
@@ -66,3 +66,5 @@ const series = [tokens.color.primary[500], tokens.color.success[500]]
 ## 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

@@ -41,19 +41,26 @@ export declare const neutral: {
     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. */
+/**
+ * Warm espresso graphite (hue ~48).
+ *
+ * Restrained and premium — not pure black, not a loud brand blue/teal.
+ * Enough warmth to feel intentional on a solid button; quiet enough that
+ * consumers can rebrand without scraping a chromatic default first.
+ */
 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)";
+    readonly 50: "oklch(0.975 0.01 48)";
+    readonly 100: "oklch(0.95 0.014 48)";
+    readonly 200: "oklch(0.90 0.02 48)";
+    readonly 300: "oklch(0.80 0.026 48)";
+    readonly 400: "oklch(0.68 0.032 48)";
+    readonly 500: "oklch(0.50 0.036 48)";
+    readonly 600: "oklch(0.40 0.037 48)";
+    readonly 700: "oklch(0.35 0.037 48)";
+    /** Solid actions — warm espresso, deep enough for white labels. */
+    readonly 800: "oklch(0.31 0.038 48)";
+    readonly 900: "oklch(0.26 0.032 48)";
+    readonly 950: "oklch(0.18 0.024 48)";
 };
 /** Green (hue 152). Reserved for successful outcomes, never for brand accent. */
 export declare const success: {
@@ -97,6 +104,177 @@ 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 / 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.
+ */
+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 +337,47 @@ 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-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)";
 };
@@ -172,17 +391,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 +429,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 +447,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. */
@@ -226,17 +457,25 @@ export declare const semanticColorLight: {
     /** Barely-there separation inside a dense group. */
     readonly 'border-subtle': `var(--color-${string})`;
     /**
-     * Boundary of an interactive control — text inputs, checkboxes, outlined
+     * Boundary of an interactive control — text inputs, selects, 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`).
+     * 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 'border-control': `var(--color-${string})`;
-    /** Focus ring. Never remove the ring — recolour it. */
-    readonly 'focus-ring': `var(--color-${string})`;
+    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.
+     */
+    readonly ring: `var(--color-${string})`;
     /** Base colour shadows are mixed from. */
     readonly shadow: `var(--color-${string})`;
     readonly 'neutral-solid': `var(--color-${string})`;
@@ -245,6 +484,10 @@ export declare const semanticColorLight: {
     readonly 'neutral-subtle': `var(--color-${string})`;
     readonly 'neutral-on-subtle': `var(--color-${string})`;
     readonly 'neutral-border': `var(--color-${string})`;
+    /**
+     * Warm espresso solid — premium brown-graphite, not a black brick.
+     * `primary-800` ≈ `oklch(0.31 0.038 48)`.
+     */
     readonly 'primary-solid': `var(--color-${string})`;
     readonly 'primary-solid-hover': `var(--color-${string})`;
     readonly 'primary-on-solid': `var(--color-${string})`;
@@ -273,30 +516,31 @@ export declare const semanticColorLight: {
 /**
  * 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.
+ * 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 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})`;
+    /**
+     * 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.
+     */
+    readonly ring: `var(--color-${string})`;
     readonly shadow: `var(--color-${string})`;
     readonly 'neutral-solid': `var(--color-${string})`;
     readonly 'neutral-solid-hover': `var(--color-${string})`;