@iveri/tokens 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# @iveri/tokens
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Iveri design tokens — **one** copy of the palette, the radii and the motion scale, readable
+from a browser bundle, a Tailwind theme and React Native alike. Zero runtime dependencies.
+Published as native ES modules only; Metro and Node 26 load it through `require` as well.
+
+```bash
+pnpm add @iveri/tokens
+```
+
+```ts
+import { color, productColor, radius, toRgbChannels } from '@iveri/tokens';
+
+color.accent; // '#1B2D72'
+toRgbChannels(color.accent); // '27 45 114' — the form a CSS custom property needs
+productColor.gold; // '#F6C76D'
+radius.card; // 12
+```
+
+## Why it exists
+
+Every panel used to declare the palette in its own `index.css`, and the six copies had already
+drifted into four variants. `@iveri/react-kit@0.6.0` reduced them to one — **for the web**. Both
+Expo apps kept a hand-maintained `theme.ts`, because the kit is a React **DOM** package whose
+stylesheet imports webfonts: depending on it from React Native pulls a `react-dom` peer and a CSS
+file Metro has no use for.
+
+So the fleet went from six copies to three, and the three could only be kept in step by a spec in
+each repository that said, in its own comment, **that it could not see drift against the others**.
+
+## What is in it, and what is not
+
+| Export                                         | For                                                                                |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `color`                                        | The semantic palette every surface draws from                                      |
+| `productColor`                                 | The navy hero and the gold that goes on it — a **product** voice, not panel chrome |
+| `radius`, `duration`, `easing`, `easingPoints` | The non-colour scales both platforms share                                         |
+| `toRgbChannels`                                | `#1B2D72` → `27 45 114`                                                            |
+
+**Hex is canonical and everything else is derived.** The web needs channel triplets so a custom
+property can take an alpha (`rgb(var(--color-accent) / 0.16)`); React Native needs a plain colour
+string. A package shipping triplets would make the mobile apps parse them; one shipping CSS would
+be unusable from React Native at all.
+
+**Not here:** typefaces, shadows and the type scale. A shadow is `box-shadow` on the web and
+`shadowOffset`/`elevation` on React Native — the same intent expressed twice, with nothing shared
+to extract — and a font stack is a list of family names on one platform and a chosen single face
+on the other. Those live in `@iveri/react-kit` and in each app's `typography.ts`, where they are
+honest.
+
+**`productColor` is a separate export on purpose.** An admin console does not open on a navy card
+with a gold rule, and should not start by accident.
+
+## The two deliberate collapses
+
+- **`productColor.hero` holds the same value as `color.accentHover`.** The two product web apps
+  had been writing `#17285d` inline — fourteen occurrences between them, a navy three parts in 255
+  from the one the palette already had. Keeping the near-miss would have made it a twenty-fifth
+  colour nobody chose.
+- **`positive` / `caution` / `critical`, not `success` / `warning` / `danger`.** The design
+  standard and six web panels already speak the first set, so the two mobile apps' local names
+  become aliases rather than the other way round.
+
+## Changing a value
+
+The radii and the motion scale are a **copy** of `design-system/tokens.json`, which is outside any
+package and is not published — so a change belongs in both places, deliberately. `color.spec.ts`
+pins them, which is what makes the next invented number fail a test rather than ship.

package/dist/color.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The Iveri palette, as hex.
+ *
+ * **Hex is the canonical form and the other shapes are derived from it.** The web needs channel
+ * triplets so a CSS custom property can be used with an alpha (`rgb(var(--color-accent) / 0.1)`),
+ * and React Native needs a plain colour string; a package that shipped triplets would make the
+ * mobile apps parse them, and one that shipped only CSS would be unusable from React Native at
+ * all. `toRgbChannels` is the one conversion, so there is one place to be wrong.
+ *
+ * **Why this package exists.** Every panel used to declare the palette in its own `index.css`,
+ * and `@iveri/react-kit@0.6.0` reduced six copies to one — for the web. Both Expo apps still kept
+ * a hand-maintained `theme.ts`, because the kit is a React **DOM** package whose stylesheet
+ * imports webfonts: depending on it from React Native pulls a `react-dom` peer and a CSS file
+ * Metro has no use for. So the fleet went from six copies to three, and the three could only be
+ * kept in step by a spec in each repo that said, in its own comment, that it could not see drift
+ * against the others.
+ */
+/** A `#rrggbb` string. Lowercase is not required; `toRgbChannels` accepts either. */
+export type HexColor = `#${string}`;
+/**
+ * The semantic palette every Iveri surface draws from.
+ *
+ * The names are the design standard's, which is why the two mobile apps' local `success` /
+ * `warning` / `danger` become aliases rather than the other way round: `design.md` and six web
+ * panels already speak `positive` / `caution` / `critical`, and a token package that renamed
+ * them would make the standard and the package disagree on the day it shipped.
+ */
+export declare const color: {
+    readonly canvas: "#F7F8FB";
+    readonly surface: "#FFFFFF";
+    readonly raised: "#F1F3F8";
+    /** A well *below* the surface — a table header, a grouped field, code. */
+    readonly sunken: "#EDEFF5";
+    readonly line: "#E4E7EF";
+    /** For a divider that has to be seen rather than felt, and an input border on hover. */
+    readonly lineStrong: "#CFD4E2";
+    readonly ink: "#111729";
+    readonly inkSoft: "#3A4257";
+    readonly muted: "#5C6579";
+    readonly faint: "#8A92A6";
+    readonly accent: "#1B2D72";
+    readonly accentHover: "#14235C";
+    readonly accentInk: "#FFFFFF";
+    /** The selected-row and hover wash. Navy at 10% alpha goes grey; a mixed tint stays blue. */
+    readonly accentSoft: "#EEF1FA";
+    readonly accentLine: "#C7CFE8";
+    /** A lighter navy for links: the brand navy at body size reads as near-black. */
+    readonly link: "#2A46A8";
+    readonly positive: "#157A4B";
+    readonly positiveSoft: "#E3F5EA";
+    readonly caution: "#9A6412";
+    readonly cautionSoft: "#FBF1DC";
+    readonly critical: "#BE2C3C";
+    readonly criticalSoft: "#FBE9EB";
+    readonly info: "#1F6FA8";
+    readonly infoSoft: "#E5F1FA";
+};
+/**
+ * The louder half of the system: the navy hero panel and the warm accent that goes on it.
+ *
+ * **These are a product voice, not panel chrome.** Taxi, Delivery and the shop open on a navy
+ * card with a gold rule; an admin console does not, and should not start. They are a separate
+ * export so a panel cannot reach for them by accident, and so the next product app has them.
+ *
+ * ⚠ **`hero` deliberately holds the same value as `color.accentHover`.** The two product web
+ * apps had been writing `#17285d` inline — eight occurrences in one, six in the other, a navy
+ * three parts in 255 away from the one the palette already had. Keeping the near-miss would have
+ * made it a twenty-fifth colour nobody chose; collapsing it onto the deep navy that already
+ * existed is the honest reading, and the difference is not visible.
+ */
+export declare const productColor: {
+    /** The deep navy a hero card is painted in. */
+    readonly hero: "#14235C";
+    /** Text and rules on `hero`. */
+    readonly heroInk: "#FFFFFF";
+    /** An error on a hero card, where `critical` would be unreadable. */
+    readonly heroCritical: "#FFD2DA";
+    /** Iveri's warm accent. Used sparingly, and never to carry status. */
+    readonly gold: "#F6C76D";
+    readonly goldHover: "#FFDA91";
+    /** The rule beside a page heading, and a route marker's ring. */
+    readonly goldLine: "#E3AD50";
+    readonly goldSoft: "#FFF2D6";
+    /** Text on `gold` and on `goldSoft`. */
+    readonly goldInk: "#8D5C16";
+};
+export type ColorName = keyof typeof color;
+export type ProductColorName = keyof typeof productColor;
+/**
+ * `#1B2D72` → `27 45 114`, the form a CSS custom property needs.
+ *
+ * Space-separated rather than comma-separated, because that is the syntax
+ * `rgb(var(--color-accent) / 0.16)` requires — a comma-separated triplet silently fails to parse
+ * there, and the browser drops the declaration, leaving the inherited colour. Which usually looks
+ * close enough to be deliberate.
+ */
+export declare function toRgbChannels(hex: HexColor): string;

package/dist/color.js

@@ -0,0 +1,112 @@
+/**
+ * The Iveri palette, as hex.
+ *
+ * **Hex is the canonical form and the other shapes are derived from it.** The web needs channel
+ * triplets so a CSS custom property can be used with an alpha (`rgb(var(--color-accent) / 0.1)`),
+ * and React Native needs a plain colour string; a package that shipped triplets would make the
+ * mobile apps parse them, and one that shipped only CSS would be unusable from React Native at
+ * all. `toRgbChannels` is the one conversion, so there is one place to be wrong.
+ *
+ * **Why this package exists.** Every panel used to declare the palette in its own `index.css`,
+ * and `@iveri/react-kit@0.6.0` reduced six copies to one — for the web. Both Expo apps still kept
+ * a hand-maintained `theme.ts`, because the kit is a React **DOM** package whose stylesheet
+ * imports webfonts: depending on it from React Native pulls a `react-dom` peer and a CSS file
+ * Metro has no use for. So the fleet went from six copies to three, and the three could only be
+ * kept in step by a spec in each repo that said, in its own comment, that it could not see drift
+ * against the others.
+ */
+/**
+ * The semantic palette every Iveri surface draws from.
+ *
+ * The names are the design standard's, which is why the two mobile apps' local `success` /
+ * `warning` / `danger` become aliases rather than the other way round: `design.md` and six web
+ * panels already speak `positive` / `caution` / `critical`, and a token package that renamed
+ * them would make the standard and the package disagree on the day it shipped.
+ */
+export const color = {
+    /* ---- Neutrals ---------------------------------------------------------------------
+     * Cool and very slightly blue-shifted, and deliberately **not** Tailwind's `slate`: that
+     * ramp is the most recognisable palette on the web, and a product wearing it reads as
+     * generated before a single word is read. */
+    canvas: '#F7F8FB',
+    surface: '#FFFFFF',
+    raised: '#F1F3F8',
+    /** A well *below* the surface — a table header, a grouped field, code. */
+    sunken: '#EDEFF5',
+    line: '#E4E7EF',
+    /** For a divider that has to be seen rather than felt, and an input border on hover. */
+    lineStrong: '#CFD4E2',
+    /* ---- Text -------------------------------------------------------------------------
+     * Four genuine levels. `faint` carried `muted`'s value in all six panels until 0.6.0, so
+     * the hierarchy the standard describes was two levels wearing three names. */
+    ink: '#111729',
+    inkSoft: '#3A4257',
+    muted: '#5C6579',
+    faint: '#8A92A6',
+    /* ---- Brand ------------------------------------------------------------------------ */
+    accent: '#1B2D72',
+    accentHover: '#14235C',
+    accentInk: '#FFFFFF',
+    /** The selected-row and hover wash. Navy at 10% alpha goes grey; a mixed tint stays blue. */
+    accentSoft: '#EEF1FA',
+    accentLine: '#C7CFE8',
+    /** A lighter navy for links: the brand navy at body size reads as near-black. */
+    link: '#2A46A8',
+    /* ---- Status -----------------------------------------------------------------------
+     * Each deepened enough to carry 14px text on its own subtle background, and `info` is a
+     * real blue rather than a second copy of the accent — which is what made an info badge and
+     * an accent badge the same badge. */
+    positive: '#157A4B',
+    positiveSoft: '#E3F5EA',
+    caution: '#9A6412',
+    cautionSoft: '#FBF1DC',
+    critical: '#BE2C3C',
+    criticalSoft: '#FBE9EB',
+    info: '#1F6FA8',
+    infoSoft: '#E5F1FA',
+};
+/**
+ * The louder half of the system: the navy hero panel and the warm accent that goes on it.
+ *
+ * **These are a product voice, not panel chrome.** Taxi, Delivery and the shop open on a navy
+ * card with a gold rule; an admin console does not, and should not start. They are a separate
+ * export so a panel cannot reach for them by accident, and so the next product app has them.
+ *
+ * ⚠ **`hero` deliberately holds the same value as `color.accentHover`.** The two product web
+ * apps had been writing `#17285d` inline — eight occurrences in one, six in the other, a navy
+ * three parts in 255 away from the one the palette already had. Keeping the near-miss would have
+ * made it a twenty-fifth colour nobody chose; collapsing it onto the deep navy that already
+ * existed is the honest reading, and the difference is not visible.
+ */
+export const productColor = {
+    /** The deep navy a hero card is painted in. */
+    hero: '#14235C',
+    /** Text and rules on `hero`. */
+    heroInk: '#FFFFFF',
+    /** An error on a hero card, where `critical` would be unreadable. */
+    heroCritical: '#FFD2DA',
+    /** Iveri's warm accent. Used sparingly, and never to carry status. */
+    gold: '#F6C76D',
+    goldHover: '#FFDA91',
+    /** The rule beside a page heading, and a route marker's ring. */
+    goldLine: '#E3AD50',
+    goldSoft: '#FFF2D6',
+    /** Text on `gold` and on `goldSoft`. */
+    goldInk: '#8D5C16',
+};
+/**
+ * `#1B2D72` → `27 45 114`, the form a CSS custom property needs.
+ *
+ * Space-separated rather than comma-separated, because that is the syntax
+ * `rgb(var(--color-accent) / 0.16)` requires — a comma-separated triplet silently fails to parse
+ * there, and the browser drops the declaration, leaving the inherited colour. Which usually looks
+ * close enough to be deliberate.
+ */
+export function toRgbChannels(hex) {
+    const value = hex.replace('#', '');
+    if (!/^[0-9a-f]{6}$/i.test(value)) {
+        throw new Error(`Not a six-digit hex colour: ${hex}`);
+    }
+    const channels = [value.slice(0, 2), value.slice(2, 4), value.slice(4, 6)];
+    return channels.map((channel) => Number.parseInt(channel, 16)).join(' ');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './color.js';
+export * from './scale.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './color.js';
+export * from './scale.js';

package/dist/scale.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The non-colour scales both platforms share.
+ *
+ * ⚠ **These values are `design-system/tokens.json`'s, by its own names**, and this package
+ * cannot read that file: the standard lives outside any package and is not published. So this is
+ * a copy, and a change belongs in both places deliberately — which is exactly the mistake
+ * `@iveri/react-kit`'s first preset made, inventing 10px, 14px, 180ms and 260ms where the
+ * standard already said 12px, 16px, 200ms and 320ms.
+ */
+/** Corner radii, in pixels. The web converts to rem; React Native wants the number. */
+export declare const radius: {
+    /** A button, an input, a badge. */
+    readonly control: 8;
+    /** A card. */
+    readonly card: 12;
+    /** A panel or a sheet. */
+    readonly panel: 16;
+};
+/** Transition durations, in milliseconds. */
+export declare const duration: {
+    /** A small state change — a hover, a focus ring. */
+    readonly fast: 120;
+    /** The standard transition. */
+    readonly normal: 200;
+    /** A panel or an overlay, and nothing smaller. */
+    readonly slow: 320;
+};
+/**
+ * The standard's easing, verbatim.
+ *
+ * A decelerating curve, so a thing arrives rather than coasting to a stop. React Native's
+ * `Easing.bezier` takes the same four numbers, which is why they are exported as numbers too.
+ */
+export declare const easing: {
+    readonly standard: "cubic-bezier(0.2, 0, 0, 1)";
+};
+/** `easing.standard`'s control points, for a platform that cannot parse the CSS form. */
+export declare const easingPoints: {
+    readonly standard: readonly [0.2, 0, 0, 1];
+};
+export type RadiusName = keyof typeof radius;
+export type DurationName = keyof typeof duration;

package/dist/scale.js

@@ -0,0 +1,40 @@
+/**
+ * The non-colour scales both platforms share.
+ *
+ * ⚠ **These values are `design-system/tokens.json`'s, by its own names**, and this package
+ * cannot read that file: the standard lives outside any package and is not published. So this is
+ * a copy, and a change belongs in both places deliberately — which is exactly the mistake
+ * `@iveri/react-kit`'s first preset made, inventing 10px, 14px, 180ms and 260ms where the
+ * standard already said 12px, 16px, 200ms and 320ms.
+ */
+/** Corner radii, in pixels. The web converts to rem; React Native wants the number. */
+export const radius = {
+    /** A button, an input, a badge. */
+    control: 8,
+    /** A card. */
+    card: 12,
+    /** A panel or a sheet. */
+    panel: 16,
+};
+/** Transition durations, in milliseconds. */
+export const duration = {
+    /** A small state change — a hover, a focus ring. */
+    fast: 120,
+    /** The standard transition. */
+    normal: 200,
+    /** A panel or an overlay, and nothing smaller. */
+    slow: 320,
+};
+/**
+ * The standard's easing, verbatim.
+ *
+ * A decelerating curve, so a thing arrives rather than coasting to a stop. React Native's
+ * `Easing.bezier` takes the same four numbers, which is why they are exported as numbers too.
+ */
+export const easing = {
+    standard: 'cubic-bezier(0.2, 0, 0, 1)',
+};
+/** `easing.standard`'s control points, for a platform that cannot parse the CSS form. */
+export const easingPoints = {
+    standard: [0.2, 0, 0, 1],
+};

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@iveri/tokens",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The Iveri design tokens — one copy of the palette, the radii and the motion scale, for the web and for React Native. Zero runtime dependencies.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iverihq/iveri-tokens.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=26"
+  },
+  "packageManager": "pnpm@12.18.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "pnpm clean && tsc -p tsconfig.build.json && node ./scripts/verify-zero-runtime-deps.mjs && node ./scripts/verify-loadable.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "prettier": "@iveri/prettier-config",
+  "devDependencies": {
+    "@iveri/eslint-config": "^0.2.3",
+    "@iveri/prettier-config": "^0.1.0",
+    "@iveri/tsconfig": "^0.2.1",
+    "eslint": "^10.14.0",
+    "prettier": "^3.9.10",
+    "rimraf": "^6.1.4",
+    "typescript": "~6.0.3",
+    "vitest": "^5.1.0"
+  }
+}