@welcome-back/brand 0.1.2 → 0.2.0

package/README.md

@@ -18,10 +18,12 @@ Use it for loading moments that mean "on the way to the next step".
 - [Quick start](#quick-start)
 - [API](#api)
 - [Examples](#examples)
+- [POS design tokens](#pos-design-tokens)
 - [Accessibility](#accessibility)
 - [Where to use it, and where not](#where-to-use-it-and-where-not)
 - [Troubleshooting](#troubleshooting)
-- [Release](#release)
+- [Develop](#develop)
+- [Publish a change](#publish-a-change)
 - [Source art](#source-art)
 
 ## Install
@@ -288,6 +290,35 @@ render(<Loading />);
 expect(screen.getByRole("img", { name: "Loading" })).toHaveClass("wb-runner");
 ```
 
+## POS design tokens
+
+The WelcomeBack POS look: the `--wb-*` CSS custom properties that pos-ui paints
+with. **The POS is not themable** (owner decision, 2026-09-28): every business
+gets this same look, so nothing overrides these per tenant. The dashboard's POS
+and KDS previews read the same values, so a preview cannot drift from the
+register.
+
+The source is `src/posTokens.ts`. `npm run build` also writes
+`dist/pos-tokens.css` from it (`scripts/write-pos-tokens-css.mjs`), so the
+stylesheet and the TS export always agree. Change a value there, never in an app.
+
+In a stylesheet (pos-ui), before any other rule:
+
+```css
+@import '@welcome-back/brand/pos-tokens.css';
+```
+
+In React (the dashboard previews):
+
+```tsx
+import { POS_TOKENS } from '@welcome-back/brand';
+
+<div style={POS_TOKENS as React.CSSProperties}>…</div>;
+POS_TOKENS['--wb-accent']; // '#171717'
+```
+
+`posTokensCss(selector)` returns the same rule for another selector.
+
 ## Accessibility
 
 - **Give exactly one accessible name per loading state.** Either put `label` on
@@ -320,17 +351,146 @@ the content will appear.
 | The runner fills the whole container | No width is set | Give it a width (`w-24`, or `width` in CSS) |
 | A Tailwind arbitrary property has no effect | Tailwind does not scan the file | Check the `content` globs in the Tailwind config |
 
-## Release
+## Develop
+
+### Repo layout
+
+| Path | What it holds |
+|---|---|
+| `src/index.ts` | Public exports. Only what is exported here is part of the API. |
+| `src/RunnerLoader.tsx` | The component: SVG structure, clip paths, props |
+| `src/runnerCss.ts` | The animation: keyframes, timing, swing angles, reduced motion |
+| `src/runnerArt.ts` | Vector data: paths, pants fills, clip polygons |
+| `src/*.test.tsx` | Vitest tests (server render, no browser) |
+| `scripts/mark-cjs.mjs` | Marks `dist/cjs` as CommonJS after the build |
+| `.github/workflows/ci.yml` | Runs on every PR and on `main` |
+| `.github/workflows/publish.yml` | Runs on a `v*` tag and publishes to npm |
+
+### Commands
+
+Node 22 or later.
+
+```bash
+npm ci             # install
+npm run typecheck  # tsc, no output
+npm test           # vitest
+npm run build      # dist/esm (ESM + types) and dist/cjs (CommonJS)
+```
+
+CI runs all four, then loads both builds to prove that `import` and `require`
+work.
+
+### Try a change in an app before you publish
+
+Pack the package and install the tarball in the app:
+
+```bash
+# in brand/
+npm run build && npm pack          # writes welcome-back-brand-<version>.tgz
+
+# in the app, for example staff-ui/
+npm i ../brand/welcome-back-brand-<version>.tgz
+```
+
+Undo it in the app with `npm i @welcome-back/brand@latest`. Do not commit the
+tarball path in the app's `package.json`.
+
+Prefer `npm pack` to `npm link`. A linked package can load a second copy of
+React, and then hooks fail with "Invalid hook call".
+
+### Common changes
+
+| To change | Edit | Note |
+|---|---|---|
+| Speed | `--wb-runner-step-default` in `src/runnerCss.ts` | Apps can already override it per use with `--wb-runner-step` |
+| Stride length (swing angles) | `@keyframes wb-runner-swing-front` / `-back` in `src/runnerCss.ts` | Angles are measured from each leg drawing's rest pose. The front leg is vertical at `-36deg`, the back leg at `39deg`. Keep forward and back swings equal around those values. |
+| Where the legs join the body | `@keyframes wb-runner-hip-front` / `-back` | Values are in the art's coordinates (the 1500×1500 PDF page) |
+| What is hidden behind the W | `LEGS_CLIP` / `BODY_CLIP` in `src/runnerArt.ts` | See [Source art](#source-art) |
+| A new prop | `src/RunnerLoader.tsx`, plus a test and a row in the props table | |
+| A new asset (logo, icon, token) | A new file in `src/`, exported from `src/index.ts`, plus a test and a README section | |
+
+After a visual change, check it in a real app with `npm pack` (above) in light
+mode, dark mode and with reduced motion on.
+
+## Publish a change
+
+Every change reaches npm through a PR and a tag. Nobody publishes from a laptop,
+and there is no npm token: GitHub Actions publishes with npm trusted publishing.
+
+### 1. Pick the version
+
+The package follows [semver](https://semver.org). Apps install it with `^`, so
+they get minor and patch releases on their next install.
+
+| Change | Bump | Example |
+|---|---|---|
+| Docs, tests, or a fix with no visible change | patch | `0.1.2` → `0.1.3` |
+| A new prop, asset or CSS variable; a visual tweak that keeps the API | minor | `0.1.3` → `0.2.0` |
+| A removed or renamed prop, export or CSS variable | major | `0.9.0` → `1.0.0` |
+
+While the version is `0.x`, npm treats a minor bump as breaking for `^`
+ranges. Apps then need an explicit update to get it.
+
+### 2. Open a PR with the change and the new version
+
+```bash
+git switch main && git pull
+git switch -c <type>/<short-name>
+# make the change
+npm version <patch|minor|major> --no-git-tag-version   # edits package.json and package-lock.json
+git commit -am "<type>: <what changed> (v<new version>)"
+git push -u origin HEAD
+gh pr create --base main
+```
+
+CI must pass before you merge. Squash-merge the PR.
+
+### 3. Tag the merge commit
+
+```bash
+git switch main && git pull
+git tag v<new version>          # must equal "version" in package.json
+git push origin v<new version>
+```
+
+The tag starts the Publish workflow. It:
+
+1. checks that the tag equals `version` in `package.json`,
+2. runs typecheck, tests and build (`prepublishOnly`),
+3. publishes to npm through trusted publishing.
+
+Watch it with `gh run watch`, or in the repo's **Actions** tab.
+
+### 4. Check npm and update the apps
+
+```bash
+npm view @welcome-back/brand version     # the new version, after a few minutes
+```
+
+A new version can take up to about 3 minutes to show on the registry. Then, in
+each app:
+
+```bash
+npm i @welcome-back/brand@latest
+```
+
+### If the publish fails
+
+| Error in the workflow log | Cause | Fix |
+|---|---|---|
+| `Tag must match package.json version` step fails | The tag and `version` differ | Delete the tag (`git push origin :v<x>` and `git tag -d v<x>`), fix the version in a PR, tag again |
+| `403 … OIDC permission denied` | The trusted publisher on npmjs.com does not allow direct publish, or its fields do not match | npmjs.com → package → Settings → Trusted Publisher: `WelcomeBackLoyalty` / `brand` / `publish.yml`, no environment, **Allow npm publish** ticked |
+| `403 … cannot publish over the previously published versions` | That version is already on npm | Bump the version in a new PR and tag again. npm never allows a republish of a version. |
+| Typecheck or test fails | The tagged commit is broken | Fix it in a PR, bump the version, tag again |
+
+To rerun a failed publish without a new tag: `gh run rerun <run-id> --failed`.
 
-1. Bump `version` in `package.json` in a PR, and merge it to `main`.
-2. Tag the merge commit: `git tag v0.2.0 && git push origin v0.2.0`.
-3. The Publish workflow checks the tag against the version, runs typecheck,
-   tests and build, and publishes to npm.
+### npm settings (for maintainers)
 
-Publishing uses npm trusted publishing (GitHub OIDC): no npm token is stored.
-The trusted publisher is set on npmjs.com → `@welcome-back/brand` → Settings:
-GitHub Actions, `WelcomeBackLoyalty/brand`, workflow `publish.yml`, with
-**Allow npm publish** ticked.
+- Org: `welcome-back`. Package access: public.
+- Trusted publisher: GitHub Actions, `WelcomeBackLoyalty/brand`, `publish.yml`,
+  no environment, **Allow npm publish** ticked.
+- No provenance: npm cannot generate it for a private GitHub repo.
 
 ## Source art
 

package/dist/cjs/index.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RunnerLoader = void 0;
+exports.posTokensCss = exports.POS_TOKENS = exports.RunnerLoader = void 0;
 var RunnerLoader_js_1 = require("./RunnerLoader.js");
 Object.defineProperty(exports, "RunnerLoader", { enumerable: true, get: function () { return RunnerLoader_js_1.RunnerLoader; } });
+var posTokens_js_1 = require("./posTokens.js");
+Object.defineProperty(exports, "POS_TOKENS", { enumerable: true, get: function () { return posTokens_js_1.POS_TOKENS; } });
+Object.defineProperty(exports, "posTokensCss", { enumerable: true, get: function () { return posTokens_js_1.posTokensCss; } });

package/dist/cjs/posTokens.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POS_TOKENS = void 0;
+exports.posTokensCss = posTokensCss;
+/**
+ * The WelcomeBack POS look: the CSS custom properties pos-ui paints with, and
+ * the ones the dashboard's POS / KDS previews copy. One source, so a preview
+ * can never drift from the register.
+ *
+ * The POS is not themable (owner decision, 2026-09-28): every business gets
+ * this same look. Nothing overrides these per tenant.
+ *
+ * pos-ui imports the generated `@welcome-back/brand/pos-tokens.css`; React code
+ * reads `POS_TOKENS`.
+ */
+exports.POS_TOKENS = {
+    // Monochrome chrome on a warm ivory canvas (pos-ui DESIGN.md §3).
+    "--wb-primary": "#171717",
+    "--wb-accent": "#171717",
+    "--wb-on-accent": "#ffffff",
+    // Tonal fill for hover/selected. A `-soft` token exists because the theme
+    // tokens are complete colors — Tailwind's `/NN` alpha modifier on them
+    // compiles to an invalid rgb() and renders transparent.
+    "--wb-accent-soft": "rgba(23, 23, 23, 0.06)",
+    // Warm ivory neutrals — the identity. Never cool gray.
+    "--wb-bg": "#f6f4e9",
+    "--wb-surface": "#ffffff",
+    "--wb-surface2": "#f2f1ec",
+    "--wb-ticket-bg": "#f2f1ec",
+    "--wb-border": "#e5e2d6",
+    // Translucent ivory veil for overlays (e.g. "Agotado").
+    "--wb-veil": "rgba(246, 244, 233, 0.72)",
+    "--wb-text": "#000000",
+    "--wb-muted": "#404040",
+    "--wb-success": "#22c55e",
+    "--wb-amber": "#f59e0b",
+    "--wb-amber-soft": "rgba(245, 158, 11, 0.15)",
+    "--wb-error": "#ef4444",
+    "--wb-error-soft": "rgba(239, 68, 68, 0.15)",
+    "--wb-primary-soft": "rgba(23, 23, 23, 0.15)",
+    // The brand tone. Same as the primary: the POS is monochrome.
+    "--wb-brand": "#171717",
+    "--wb-radius": "12px",
+    "--wb-radius-lg": "16px",
+    "--wb-font": "'Montserrat'",
+};
+/** The tokens as one CSS rule, for apps that load them as a stylesheet. */
+function posTokensCss(selector = ":root") {
+    const lines = Object.entries(exports.POS_TOKENS).map(([name, value]) => `  ${name}: ${value};`);
+    return `${selector} {\n${lines.join("\n")}\n}\n`;
+}

package/dist/esm/index.d.ts

@@ -1,2 +1,4 @@
 export { RunnerLoader } from "./RunnerLoader.js";
 export type { RunnerLoaderProps } from "./RunnerLoader.js";
+export { POS_TOKENS, posTokensCss } from "./posTokens.js";
+export type { PosToken } from "./posTokens.js";

package/dist/esm/index.js

@@ -1 +1,2 @@
 export { RunnerLoader } from "./RunnerLoader.js";
+export { POS_TOKENS, posTokensCss } from "./posTokens.js";

package/dist/esm/posTokens.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The WelcomeBack POS look: the CSS custom properties pos-ui paints with, and
+ * the ones the dashboard's POS / KDS previews copy. One source, so a preview
+ * can never drift from the register.
+ *
+ * The POS is not themable (owner decision, 2026-09-28): every business gets
+ * this same look. Nothing overrides these per tenant.
+ *
+ * pos-ui imports the generated `@welcome-back/brand/pos-tokens.css`; React code
+ * reads `POS_TOKENS`.
+ */
+export declare const POS_TOKENS: {
+    readonly "--wb-primary": "#171717";
+    readonly "--wb-accent": "#171717";
+    readonly "--wb-on-accent": "#ffffff";
+    readonly "--wb-accent-soft": "rgba(23, 23, 23, 0.06)";
+    readonly "--wb-bg": "#f6f4e9";
+    readonly "--wb-surface": "#ffffff";
+    readonly "--wb-surface2": "#f2f1ec";
+    readonly "--wb-ticket-bg": "#f2f1ec";
+    readonly "--wb-border": "#e5e2d6";
+    readonly "--wb-veil": "rgba(246, 244, 233, 0.72)";
+    readonly "--wb-text": "#000000";
+    readonly "--wb-muted": "#404040";
+    readonly "--wb-success": "#22c55e";
+    readonly "--wb-amber": "#f59e0b";
+    readonly "--wb-amber-soft": "rgba(245, 158, 11, 0.15)";
+    readonly "--wb-error": "#ef4444";
+    readonly "--wb-error-soft": "rgba(239, 68, 68, 0.15)";
+    readonly "--wb-primary-soft": "rgba(23, 23, 23, 0.15)";
+    readonly "--wb-brand": "#171717";
+    readonly "--wb-radius": "12px";
+    readonly "--wb-radius-lg": "16px";
+    readonly "--wb-font": "'Montserrat'";
+};
+export type PosToken = keyof typeof POS_TOKENS;
+/** The tokens as one CSS rule, for apps that load them as a stylesheet. */
+export declare function posTokensCss(selector?: string): string;

package/dist/esm/posTokens.js

@@ -0,0 +1,47 @@
+/**
+ * The WelcomeBack POS look: the CSS custom properties pos-ui paints with, and
+ * the ones the dashboard's POS / KDS previews copy. One source, so a preview
+ * can never drift from the register.
+ *
+ * The POS is not themable (owner decision, 2026-09-28): every business gets
+ * this same look. Nothing overrides these per tenant.
+ *
+ * pos-ui imports the generated `@welcome-back/brand/pos-tokens.css`; React code
+ * reads `POS_TOKENS`.
+ */
+export const POS_TOKENS = {
+    // Monochrome chrome on a warm ivory canvas (pos-ui DESIGN.md §3).
+    "--wb-primary": "#171717",
+    "--wb-accent": "#171717",
+    "--wb-on-accent": "#ffffff",
+    // Tonal fill for hover/selected. A `-soft` token exists because the theme
+    // tokens are complete colors — Tailwind's `/NN` alpha modifier on them
+    // compiles to an invalid rgb() and renders transparent.
+    "--wb-accent-soft": "rgba(23, 23, 23, 0.06)",
+    // Warm ivory neutrals — the identity. Never cool gray.
+    "--wb-bg": "#f6f4e9",
+    "--wb-surface": "#ffffff",
+    "--wb-surface2": "#f2f1ec",
+    "--wb-ticket-bg": "#f2f1ec",
+    "--wb-border": "#e5e2d6",
+    // Translucent ivory veil for overlays (e.g. "Agotado").
+    "--wb-veil": "rgba(246, 244, 233, 0.72)",
+    "--wb-text": "#000000",
+    "--wb-muted": "#404040",
+    "--wb-success": "#22c55e",
+    "--wb-amber": "#f59e0b",
+    "--wb-amber-soft": "rgba(245, 158, 11, 0.15)",
+    "--wb-error": "#ef4444",
+    "--wb-error-soft": "rgba(239, 68, 68, 0.15)",
+    "--wb-primary-soft": "rgba(23, 23, 23, 0.15)",
+    // The brand tone. Same as the primary: the POS is monochrome.
+    "--wb-brand": "#171717",
+    "--wb-radius": "12px",
+    "--wb-radius-lg": "16px",
+    "--wb-font": "'Montserrat'",
+};
+/** The tokens as one CSS rule, for apps that load them as a stylesheet. */
+export function posTokensCss(selector = ":root") {
+    const lines = Object.entries(POS_TOKENS).map(([name, value]) => `  ${name}: ${value};`);
+    return `${selector} {\n${lines.join("\n")}\n}\n`;
+}

package/dist/pos-tokens.css

@@ -0,0 +1,25 @@
+/* Generated from src/posTokens.ts by scripts/write-pos-tokens-css.mjs. Do not edit. */
+:root {
+  --wb-primary: #171717;
+  --wb-accent: #171717;
+  --wb-on-accent: #ffffff;
+  --wb-accent-soft: rgba(23, 23, 23, 0.06);
+  --wb-bg: #f6f4e9;
+  --wb-surface: #ffffff;
+  --wb-surface2: #f2f1ec;
+  --wb-ticket-bg: #f2f1ec;
+  --wb-border: #e5e2d6;
+  --wb-veil: rgba(246, 244, 233, 0.72);
+  --wb-text: #000000;
+  --wb-muted: #404040;
+  --wb-success: #22c55e;
+  --wb-amber: #f59e0b;
+  --wb-amber-soft: rgba(245, 158, 11, 0.15);
+  --wb-error: #ef4444;
+  --wb-error-soft: rgba(239, 68, 68, 0.15);
+  --wb-primary-soft: rgba(23, 23, 23, 0.15);
+  --wb-brand: #171717;
+  --wb-radius: 12px;
+  --wb-radius-lg: 16px;
+  --wb-font: 'Montserrat';
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@welcome-back/brand",
-  "version": "0.1.2",
-  "description": "WelcomeBack brand assets for React apps: the running-W loader.",
+  "version": "0.2.0",
+  "description": "WelcomeBack brand assets for React apps: the running-W loader and the POS design tokens.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -17,13 +17,14 @@
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js"
-    }
+    },
+    "./pos-tokens.css": "./dist/pos-tokens.css"
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node scripts/mark-cjs.mjs",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && node scripts/mark-cjs.mjs && node scripts/write-pos-tokens-css.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"