@welcome-back/brand 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,28 @@
 # @welcome-back/brand
 
-WelcomeBack brand assets for React apps. For now: `RunnerLoader`, the isotipo W
-running left with its legs crossing under the body.
+WelcomeBack brand assets for React apps.
+
+Today the package has one component: **`RunnerLoader`**, the isotipo W running
+left. Its legs swing on their hips and cross under the body while the body bobs.
+Use it for loading moments that mean "on the way to the next step".
+
+- React 18 or 19. Works in Next.js (App Router and Pages), Vite and plain React.
+- No CSS import, no Tailwind, no bundler setup: the animation ships inside the SVG.
+- Server-renderable: it shows before JavaScript loads. Works in React Server
+  Components (it uses only `useId`).
+- ESM and CommonJS builds, so Jest suites load it with no transform setup.
+
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [API](#api)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+- [Where to use it, and where not](#where-to-use-it-and-where-not)
+- [Troubleshooting](#troubleshooting)
+- [Release](#release)
+- [Source art](#source-art)
 
 ## Install
 
@@ -9,37 +30,295 @@ running left with its legs crossing under the body.
 npm i @welcome-back/brand
 ```
 
-React 18 or 19. No CSS import and no bundler setup: the animation ships inside
-the SVG. ESM and CommonJS builds, so Jest suites can load it too.
+The package is public on npm. No token or `.npmrc` is needed.
 
-## Use
+## Quick start
 
 ```tsx
 import { RunnerLoader } from "@welcome-back/brand";
 
-// Decorative (aria-hidden) — the surrounding element owns the label:
-<div role="status" aria-label={t("loading")}>
-  <RunnerLoader className="w-28" />
+export function Loading() {
+  return <RunnerLoader className="w-24" label="Loading" />;
+}
+```
+
+That is all. Set a width, and the height follows the art.
+
+## API
+
+### Props
+
+| Prop | Type | Default | What it does |
+|---|---|---|---|
+| `className` | `string` | — | Added after the built-in `wb-runner` class. Use it for size, color and the CSS variables below. |
+| `label` | `string` | — | Accessible name. With a label the SVG is `role="img"` and screen readers announce it. Without a label it is `aria-hidden`: use that when a parent element already names the loading state. |
+
+The component renders one `<svg>`. It takes no other props.
+
+### CSS custom properties
+
+You can set these in `className` (Tailwind arbitrary properties), in your own
+CSS class, or on any ancestor element. Values inherit, so one setting on a
+wrapper applies to all runners inside it.
+
+| Property | Controls | Default | Notes |
+|---|---|---|---|
+| `color` | Ink of the W, legs and shoes | `currentColor` | Any Tailwind `text-*` class works. |
+| `--wb-runner-pants` | Fill inside the pants | `Canvas` | Set it to the color **behind** the runner. The near leg covers the far leg when they cross, so the pants must be opaque. |
+| `--wb-runner-step` | Duration of one step | `0.32s` | A full stride is two steps (0.64 s). Lower is faster. |
+
+`Canvas` is the page background color that the browser uses for the current
+`color-scheme`: white in light mode, near-black in dark mode. On any other
+surface (a card, a tinted panel, a brand color) set `--wb-runner-pants`.
+
+### Size guide
+
+| Width | Use |
+|---|---|
+| 96–128 px | Full-screen or full-panel loading |
+| 48–64 px | Loading inside a card or a list area |
+| 32–40 px | Next to text ("Loading…") |
+| under 32 px | Not recommended: the legs become unreadable. Use a plain spinner. |
+
+## Examples
+
+### Tailwind: size, color and speed in one `className`
+
+```tsx
+<RunnerLoader className="w-16 text-foreground" />
+
+// Faster (0.2 s per step) and in the muted text color:
+<RunnerLoader className="w-16 text-muted-foreground [--wb-runner-step:0.2s]" />
+```
+
+### Plain CSS (no Tailwind)
+
+```css
+/* loading.css */
+.page-loader {
+  width: 112px;
+  color: #171717;
+  --wb-runner-pants: #ffffff;
+}
+```
+
+```tsx
+import "./loading.css";
+
+<RunnerLoader className="page-loader" label="Loading" />;
+```
+
+### Inline style on a wrapper
+
+`RunnerLoader` has no `style` prop. The CSS variables inherit, so put inline
+styles on a parent element. TypeScript does not know custom properties, so cast
+the style object:
+
+```tsx
+import type { CSSProperties } from "react";
+
+const runnerTheme = {
+  color: "#171717",
+  "--wb-runner-pants": "#F6F4E9",
+  "--wb-runner-step": "0.28s",
+} as CSSProperties;
+
+<div style={runnerTheme}>
+  <RunnerLoader className="w-24" label="Loading" />
+</div>;
+```
+
+### Match a shadcn / Tailwind 3 theme token
+
+shadcn stores colors as bare HSL values (`--background: 0 0% 100%`), so wrap
+them in `hsl()`:
+
+```tsx
+<div className="bg-background text-foreground [--wb-runner-pants:hsl(var(--background))]">
+  <RunnerLoader className="w-24" />
 </div>
+```
+
+In Tailwind 4 the tokens are full colors, so drop the `hsl()`:
+`[--wb-runner-pants:var(--background)]`.
+
+### On a card or a colored surface
 
-// Standalone, with its own accessible name:
-<RunnerLoader className="w-16" label={t("loading")} />
+The pants must match the surface directly behind the runner, not the page:
+
+```tsx
+// On a card
+<div className="rounded-xl bg-card p-8 [--wb-runner-pants:hsl(var(--card))]">
+  <RunnerLoader className="w-16" />
+</div>
+
+// On a brand-orange disc, with a cream runner
+<div className="grid size-32 place-items-center rounded-full bg-[#FF6E26] text-[#FFFAF0] [--wb-runner-pants:#FF6E26]">
+  <RunnerLoader className="w-20" label="Loading" />
+</div>
 ```
 
-Size it with a width; the height follows the art.
+### Dark mode
 
-## Theme
+With the defaults, no extra code is needed on the page background: `Canvas`
+follows `color-scheme`, and the ink follows your text color.
 
-| Set on the runner or an ancestor | Controls | Default |
-|---|---|---|
-| `color` | Ink | `currentColor` |
-| `--wb-runner-pants` | Pants fill: set it to the background behind the runner | `Canvas` (the page background) |
-| `--wb-runner-step` | One step; a stride is two steps | `0.32s` |
+```tsx
+<main className="bg-background text-foreground">
+  <RunnerLoader className="w-24" />
+</main>
+```
+
+If your dark mode is a `.dark` class and not `color-scheme`, set the pants from
+the token, as in the shadcn example above.
 
-Example for a shadcn/Tailwind 3 app on a tinted surface: put
-`style={{ "--wb-runner-pants": "hsl(var(--background))" }}` on the wrapping element.
+### Next to text
 
-With `prefers-reduced-motion: reduce`, the runner holds one pose.
+The label is on the wrapper, so the runner stays decorative:
+
+```tsx
+<div role="status" className="flex items-center gap-3 text-sm text-muted-foreground">
+  <RunnerLoader className="w-9" />
+  <span>Loading your rewards…</span>
+</div>
+```
+
+### Next.js route loading (`loading.tsx`)
+
+```tsx
+// app/dashboard/loading.tsx
+import { RunnerLoader } from "@welcome-back/brand";
+
+export default function Loading() {
+  return (
+    <div className="grid min-h-[60vh] place-items-center">
+      <RunnerLoader className="w-24" label="Loading" />
+    </div>
+  );
+}
+```
+
+This is a Server Component. It needs no `"use client"`.
+
+### React `Suspense` fallback
+
+```tsx
+<Suspense fallback={<RunnerLoader className="mx-auto w-20" label="Loading" />}>
+  <CustomerDetails id={id} />
+</Suspense>
+```
+
+### Show only if the wait is long
+
+On a fast request the runner can flash for a fraction of a stride. Wait before
+you show it:
+
+```tsx
+"use client";
+import { useEffect, useState } from "react";
+import { RunnerLoader } from "@welcome-back/brand";
+
+export function DelayedRunner({ delayMs = 200 }: { delayMs?: number }) {
+  const [visible, setVisible] = useState(false);
+  useEffect(() => {
+    const timer = setTimeout(() => setVisible(true), delayMs);
+    return () => clearTimeout(timer);
+  }, [delayMs]);
+  return visible ? <RunnerLoader className="w-16" label="Loading" /> : null;
+}
+```
+
+### Full-screen splash
+
+A server-rendered overlay covers the page before JavaScript runs. Hide it after
+the app hydrates. This is a short version of staff-ui's `AppSplash`, which also
+holds the splash for two strides on the first open of each session.
+
+```tsx
+"use client";
+import { useEffect, useState } from "react";
+import { RunnerLoader } from "@welcome-back/brand";
+
+export function Splash() {
+  const [leaving, setLeaving] = useState(false);
+  const [gone, setGone] = useState(false);
+
+  useEffect(() => {
+    setLeaving(true);
+    const timer = setTimeout(() => setGone(true), 300); // fade duration
+    return () => clearTimeout(timer);
+  }, []);
+
+  if (gone) return null;
+  return (
+    <div
+      role="status"
+      aria-label="Loading"
+      className={`fixed inset-0 z-50 grid place-items-center bg-background text-foreground
+        [--wb-runner-pants:hsl(var(--background))] transition-opacity duration-300
+        ${leaving ? "pointer-events-none opacity-0" : ""}`}
+    >
+      <RunnerLoader className="w-28" />
+    </div>
+  );
+}
+```
+
+### Vite / plain React
+
+Same import, no config:
+
+```tsx
+import { RunnerLoader } from "@welcome-back/brand";
+
+function App() {
+  const { data, isLoading } = useQuery(/* … */);
+  if (isLoading) return <RunnerLoader className="loader" label="Loading" />;
+  return <Dashboard data={data} />;
+}
+```
+
+### Jest and Testing Library
+
+Jest loads the CommonJS build automatically. The SVG always has the class
+`wb-runner`, so you can find it in tests:
+
+```tsx
+render(<Loading />);
+expect(screen.getByRole("img", { name: "Loading" })).toHaveClass("wb-runner");
+```
+
+## Accessibility
+
+- **Give exactly one accessible name per loading state.** Either put `label` on
+  the runner, or put `role="status"` and `aria-label` on its wrapper and leave
+  `label` out. Do not do both, or screen readers announce it twice.
+- **Translate the label.** Pass it from your i18n layer, for example
+  `label={t("loading")}`.
+- **Reduced motion is built in.** With `prefers-reduced-motion: reduce` the
+  runner holds one pose (legs apart, mid-stride), so the loading state is still
+  visible.
+
+## Where to use it, and where not
+
+| Use it | Do not use it |
+|---|---|
+| App open and splash screens | Inside buttons: at button size the legs cannot be read |
+| Moves to the next step (after a scan, before a customer page) | Pages where the customer sees a business's own brand first (enrollment, card download): our W would lead over their brand |
+| Route and Suspense fallbacks for a full page or panel | Every small wait: if it is everywhere, staff stop noticing it |
+
+A skeleton is better when the layout that is coming is known: it shows where
+the content will appear.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The legs show a light or dark rectangle | `--wb-runner-pants` does not match the surface behind the runner | Set it to that surface color |
+| The runner is invisible | Ink is the same color as the background | Set `color` / a `text-*` class |
+| The runner does not move | The OS asks for reduced motion | Nothing to fix; this is intended |
+| 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
 
@@ -50,7 +329,8 @@ With `prefers-reduced-motion: reduce`, the runner holds one pose.
 
 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`.
+GitHub Actions, `WelcomeBackLoyalty/brand`, workflow `publish.yml`, with
+**Allow npm publish** ticked.
 
 ## Source art
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@welcome-back/brand",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "WelcomeBack brand assets for React apps: the running-W loader.",
   "license": "UNLICENSED",
   "repository": {