@welcome-back/brand 0.1.3 → 0.3.0

package/README.md

@@ -18,6 +18,8 @@ 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)
+- [Product image frames](#product-image-frames)
 - [Accessibility](#accessibility)
 - [Where to use it, and where not](#where-to-use-it-and-where-not)
 - [Troubleshooting](#troubleshooting)
@@ -289,6 +291,57 @@ 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.
+
+## Product image frames
+
+The frames a product photo is shown in: `1:1`, `4:3`, `3:2`, `16:9`. The
+dashboard cropper saves one square photo. The digital menu, the kiosk and the
+POS show it centered with `object-cover` in one of these frames, and the cropper
+draws a guide for each one. So what the owner crops is what each surface shows.
+
+A surface that shows a product photo in a frame outside this list breaks that
+promise. Add the frame here, or use one that is already here.
+
+```tsx
+import {
+  productImageAspectRatio,
+  productImageKeptArea,
+} from '@welcome-back/brand';
+
+<div style={{ aspectRatio: productImageAspectRatio('4:3') }}>…</div>;
+productImageKeptArea('16:9'); // { width: 1, height: 0.5625 } of the square, centered
+```
+
+`PRODUCT_IMAGE_FRAMES` holds the raw `{ width, height }` of each frame.
+
 ## Accessibility
 
 - **Give exactly one accessible name per loading state.** Either put `label` on

package/dist/cjs/index.js

@@ -1,5 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RunnerLoader = void 0;
+exports.productImageKeptArea = exports.productImageAspectRatio = exports.PRODUCT_IMAGE_FRAMES = 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; } });
+var productImageFrames_js_1 = require("./productImageFrames.js");
+Object.defineProperty(exports, "PRODUCT_IMAGE_FRAMES", { enumerable: true, get: function () { return productImageFrames_js_1.PRODUCT_IMAGE_FRAMES; } });
+Object.defineProperty(exports, "productImageAspectRatio", { enumerable: true, get: function () { return productImageFrames_js_1.productImageAspectRatio; } });
+Object.defineProperty(exports, "productImageKeptArea", { enumerable: true, get: function () { return productImageFrames_js_1.productImageKeptArea; } });

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/cjs/productImageFrames.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRODUCT_IMAGE_FRAMES = void 0;
+exports.productImageAspectRatio = productImageAspectRatio;
+exports.productImageKeptArea = productImageKeptArea;
+/**
+ * The frames a product photo is shown in. The dashboard cropper saves one
+ * square photo; the digital menu (catalog-ui), the kiosk and the POS show it
+ * centered with `object-cover` in one of these frames. The cropper draws a
+ * guide for each frame, so what the owner crops is what each surface shows.
+ *
+ * A surface that shows a product photo in a frame outside this list breaks
+ * that promise: add the frame here, or use one that is already here.
+ */
+exports.PRODUCT_IMAGE_FRAMES = {
+    "1:1": { width: 1, height: 1 },
+    "4:3": { width: 4, height: 3 },
+    "3:2": { width: 3, height: 2 },
+    "16:9": { width: 16, height: 9 },
+};
+/** CSS `aspect-ratio` value for a frame, e.g. `"4 / 3"`. */
+function productImageAspectRatio(frame) {
+    const { width, height } = exports.PRODUCT_IMAGE_FRAMES[frame];
+    return `${width} / ${height}`;
+}
+/**
+ * The part of the square photo a frame keeps, centered, as fractions of the
+ * square's side. Every frame is as wide as or wider than it is tall, so it
+ * keeps the full width and cuts the top and bottom equally.
+ */
+function productImageKeptArea(frame) {
+    const { width, height } = exports.PRODUCT_IMAGE_FRAMES[frame];
+    return { width: 1, height: height / width };
+}

package/dist/esm/index.d.ts

@@ -1,2 +1,6 @@
 export { RunnerLoader } from "./RunnerLoader.js";
 export type { RunnerLoaderProps } from "./RunnerLoader.js";
+export { POS_TOKENS, posTokensCss } from "./posTokens.js";
+export type { PosToken } from "./posTokens.js";
+export { PRODUCT_IMAGE_FRAMES, productImageAspectRatio, productImageKeptArea, } from "./productImageFrames.js";
+export type { ProductImageFrame } from "./productImageFrames.js";

package/dist/esm/index.js

@@ -1 +1,3 @@
 export { RunnerLoader } from "./RunnerLoader.js";
+export { POS_TOKENS, posTokensCss } from "./posTokens.js";
+export { PRODUCT_IMAGE_FRAMES, productImageAspectRatio, productImageKeptArea, } from "./productImageFrames.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/esm/productImageFrames.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The frames a product photo is shown in. The dashboard cropper saves one
+ * square photo; the digital menu (catalog-ui), the kiosk and the POS show it
+ * centered with `object-cover` in one of these frames. The cropper draws a
+ * guide for each frame, so what the owner crops is what each surface shows.
+ *
+ * A surface that shows a product photo in a frame outside this list breaks
+ * that promise: add the frame here, or use one that is already here.
+ */
+export declare const PRODUCT_IMAGE_FRAMES: {
+    readonly "1:1": {
+        readonly width: 1;
+        readonly height: 1;
+    };
+    readonly "4:3": {
+        readonly width: 4;
+        readonly height: 3;
+    };
+    readonly "3:2": {
+        readonly width: 3;
+        readonly height: 2;
+    };
+    readonly "16:9": {
+        readonly width: 16;
+        readonly height: 9;
+    };
+};
+export type ProductImageFrame = keyof typeof PRODUCT_IMAGE_FRAMES;
+/** CSS `aspect-ratio` value for a frame, e.g. `"4 / 3"`. */
+export declare function productImageAspectRatio(frame: ProductImageFrame): string;
+/**
+ * The part of the square photo a frame keeps, centered, as fractions of the
+ * square's side. Every frame is as wide as or wider than it is tall, so it
+ * keeps the full width and cuts the top and bottom equally.
+ */
+export declare function productImageKeptArea(frame: ProductImageFrame): {
+    width: number;
+    height: number;
+};

package/dist/esm/productImageFrames.js

@@ -0,0 +1,29 @@
+/**
+ * The frames a product photo is shown in. The dashboard cropper saves one
+ * square photo; the digital menu (catalog-ui), the kiosk and the POS show it
+ * centered with `object-cover` in one of these frames. The cropper draws a
+ * guide for each frame, so what the owner crops is what each surface shows.
+ *
+ * A surface that shows a product photo in a frame outside this list breaks
+ * that promise: add the frame here, or use one that is already here.
+ */
+export const PRODUCT_IMAGE_FRAMES = {
+    "1:1": { width: 1, height: 1 },
+    "4:3": { width: 4, height: 3 },
+    "3:2": { width: 3, height: 2 },
+    "16:9": { width: 16, height: 9 },
+};
+/** CSS `aspect-ratio` value for a frame, e.g. `"4 / 3"`. */
+export function productImageAspectRatio(frame) {
+    const { width, height } = PRODUCT_IMAGE_FRAMES[frame];
+    return `${width} / ${height}`;
+}
+/**
+ * The part of the square photo a frame keeps, centered, as fractions of the
+ * square's side. Every frame is as wide as or wider than it is tall, so it
+ * keeps the full width and cuts the top and bottom equally.
+ */
+export function productImageKeptArea(frame) {
+    const { width, height } = PRODUCT_IMAGE_FRAMES[frame];
+    return { width: 1, height: height / width };
+}

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.3",
-  "description": "WelcomeBack brand assets for React apps: the running-W loader.",
+  "version": "0.3.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"