@wtfalch/design 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # @wtfalch/design
 
-Components on a fixed token vocabulary, so an app can look like itself without
-forking the stylesheet.
+wtfalch's design system: components on a fixed token vocabulary, so every
+product can look like itself without forking the stylesheet.
 
 ```bash
 pnpm add @wtfalch/design
@@ -27,38 +27,70 @@ Where a theme genuinely needs a layer that values cannot reach — a paper grain
 a vignette — the base CSS pre-declares the slot and the theme fills it. The rule
 is always ours.
 
-## Writing a theme
+## Products
+
+A site is one product, so it imports its product and everything it touches is
+its own:
 
 ```ts
-import { applyTheme, defineTheme } from '@wtfalch/design'
-
-export const brand = defineTheme({
-  name: 'Brand',
-  note: 'Warm, roomy, and slower than the default',
-  scheme: 'light',
-  tokens: {
-    '--bg': '#faf7f2',
-    '--panel': '#ffffff',
-    '--accent': '#7c3aed',
-    '--on-accent': '#ffffff',
-    '--density': '1.15',      // every --space-* step follows
-    '--font-size': '15px',    // every --text-* step follows
-    '--dur-md': '320ms',
-  },
-})
-
-applyTheme(brand)                      // the object, straight from defineTheme
-applyTheme(brand, myEl)                // or on a subtree
-applyTheme('paper')                    // or a built-in, by name
+import '@wtfalch/design/valet.css'   // the vocabulary, valet's identity, the components, valet's themes
+import { Brand, Button, applyTheme } from '@wtfalch/design/valet'
+// the same components; Brand is valet's badge, applyTheme knows valet's themes
 ```
 
-Name the tokens you change; the rest inherit from `tokens.css`. A theme naming
-three tokens is valid.
+Three layers, each falling back to the one under it:
+
+| | |
+|---|---|
+| **the system** | The components, the base values in `tokens.css`, the shared icons and illustrations. |
+| **the product** | Its mark, and its identity: the tokens that make it itself under every theme — font, shape, density. On `:root` in the product's stylesheet, so a theme that is silent on them gets the product, not tf. `src/products/<name>.ts`. |
+| **the theme** | A palette and a colour scheme, plus anything it deliberately changes. One `:root[data-theme='<id>']` rule each, generated from the object. |
+
+The middle layer is what lets a theme be shared between products: it names its
+colours and inherits the identity of whichever product wears it. Before it
+existed, valet's two palettes each restated valet's font and corners, and a
+palette written for two products would have shown tf's font on valet wherever
+it kept quiet.
+
+The product's default theme is also written on `:root` when no `data-theme` is
+set, so the first paint is right with no attribute at all; set the attribute
+before the bundle loads only to restore a theme somebody picked (see First
+paint). tf's default is `system`, a `prefers-color-scheme` rule rather than a
+palette, so tf still sets the attribute.
+
+The main entry is the neutral view of all of it: `PRODUCTS` by name, `THEMES`
+as the union every product's picker and the contrast test read,
+`productTheme(product, id)` for a theme as a product wears it, `bindProduct`
+for a product defined outside this package, and `productStylesheet` for its
+CSS.
+
+```ts
+import { PRODUCTS, applyTheme, productTheme } from '@wtfalch/design'
+
+applyTheme(productTheme(PRODUCTS.valet, 'valet-night'))   // valet night, on valet's identity
+applyTheme('valet-night')                                  // the palette alone, over the base
+applyTheme(productTheme(PRODUCTS.valet), myEl)             // valet's default, on a subtree
+```
+
+### Writing a theme
+
+A theme is a `Partial<ThemeTokens>` with a name, a note and a scheme: name the
+tokens you change, the rest inherit from the product's identity and then from
+`tokens.css`. A theme naming three tokens is valid. A product's themes go in
+`src/products/<name>.ts` beside its identity, keyed by the id `applyTheme`
+derives from the name (lowercased, spaces to hyphens); `products.test.ts`
+refuses a key that disagrees, a palette that restates its product's identity,
+and a default that is not one of the product's themes. `build-products.mjs`
+writes `dist/<name>.css` from the objects at build time.
 
 **A typo is a compile error.** `tokens` is a `Partial<ThemeTokens>`, so
 `'--densty'` fails to build rather than silently doing nothing — which is the
-failure a string-keyed map produces at run time, invisibly. This is the main
-reason the type is exported at all.
+failure a string-keyed map produces at run time, invisibly.
+
+**A product names its font and does not ship it.** valet's identity sets
+`--font` to read a `--font-sans` variable the app defines with whatever loads
+its fonts, and falls back to the family by name. The gallery vendors the two
+families valet names so the specimens are photographed in them.
 
 ## The three kinds of token
 
@@ -101,9 +133,10 @@ share a value.
 
 ## First paint
 
-React mounts after the stylesheet, so a theme applied in an effect flashes the
-default. Cache the name and apply it from a blocking script before the bundle
-loads:
+Your product's stylesheet paints its default theme with no attribute set, so
+this is for restoring a choice. React mounts after the stylesheet, so a theme
+applied in an effect flashes the default. Cache the name and apply it from a
+blocking script before the bundle loads:
 
 ```html
 <script>
@@ -116,19 +149,33 @@ loads:
 
 Your server stays the source of truth. `localStorage` only beats the paint.
 
-## Built-ins
+## Marks
+
+Every product's mark, by name, in `brandMarks.ts`. tf's is one stroke. valet's
+is a filled badge: the jacket with the shirt cut out of it and a bow tie in the
+cut, one path under `evenodd` so the surface shows through the shirt. Both are
+`currentColor`, so the stylesheet decides the colour and a theme can move it.
+
+```tsx
+import { BRAND_MARKS, Brand } from '@wtfalch/design'
+
+<Brand name="valet" />   // anywhere; a product entry's Brand defaults to its own
+BRAND_MARKS.valet.d      // the path, for a favicon or an app icon cut from the same drawing
+```
 
-`system`, `night` and `paper` ship as **examples, not as the menu** — an app
-that installs this is expected to bring its own. `system` is a theme rather than
-a mode: it is the only one scoped to `prefers-color-scheme`, so choosing a dark
-theme on a light-mode laptop is not silently repainted.
+Icons and illustrations are the system's, shared by every product the way
+`Button` is. A product wanting its own inside the package's components is a
+case nobody has had; when it comes, the product entry is where to bind it.
 
 ## Status
 
-`0.1.0`. Twenty-eight components, every one of the 70 gallery specimens
+`0.3.0`. Twenty-eight components, every one of the 70 gallery specimens
 photographed in four themes, the open windows photographed too, and the
 contrast, reduced-motion and keyboard rules are tests rather than sentences.
-The first consumer is [tf](https://github.com/wtfalch/tf), the app it came from.
+It came out of [tf](https://github.com/wtfalch/tf), which is its first consumer;
+valet is the second. A product is a layer: tf and valet each ship as one
+stylesheet and one entry, with their identity under their themes and their
+mark in the table.
 
 Requires React 19. Behaviour comes from
 [React Aria Components](https://react-spectrum.adobe.com/react-aria/); every

package/dist/components/Brand.d.ts

@@ -1,10 +1,39 @@
-export default function Brand({ className, title, cog, }: {
-    className?: string;
+import { type BrandName } from './brandMarks';
+/**
+ * A product's mark, at header size.
+ *
+ * One component for every wtfalch product: `name` picks the mark out of
+ * `brandMarks.ts`, and adding a product is adding a row there. The default is
+ * `tf` because it is the first, not because it is special.
+ *
+ * `currentColor`, so the stylesheet decides the colour and a theme can move
+ * it; the mark itself knows nothing about green. No `width` or `height`
+ * attributes either: the viewBox is the ink box, measured, and `.brand` sets
+ * a height off the type scale so the width follows the aspect.
+ *
+ * Still, on purpose. Until 0.2.0 this component also morphed tf's mark into a
+ * cog under the pointer, which made a shared package carry one product's
+ * animation. That morph is tf's own `Brand` now, layered over this path; a
+ * product that wants its mark to move does the same in its own code, and the
+ * package stays the source of the still shape every product's icon is drawn
+ * from.
+ *
+ * Stroked or filled, whichever the mark is. tf's is one line at a weight;
+ * valet's is a filled badge with the shirt cut out of it and the bow inside
+ * the cut, one path under `evenodd` so the surface shows through the shirt.
+ * Both are `currentColor`, so `.brand` still decides the colour and a theme
+ * can still move it -- a second colour would be the one thing a theme could
+ * not reach.
+ *
+ * A product's entry, `@wtfalch/design/<product>`, exports this with the
+ * product's name as the default, so a header there writes `<Brand />` and
+ * gets its own mark. Here the default is the first row.
+ */
+export default function Brand({ name, title, className, }: {
+    /** Which product's mark. */
+    name?: BrandName;
     /** The product's name, which is what a screen reader should say the header
      *  starts with. There is no text beside this to repeat it. */
     title?: string;
-    /** Show the cog. Given, the caller decides -- the settings button wraps
-     *  the mark and hovers as a whole; left out, the mark watches its own
-     *  pointer. */
-    cog?: boolean;
+    className?: string;
 }): import("react").JSX.Element;

package/dist/components/Brand.js

@@ -1,212 +1,37 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { BRAND_MARKS, BRAND_NAMES } from './brandMarks';
 /**
- * The wordmark: the app icon's mark, without the tile.
+ * A product's mark, at header size.
  *
- * A lowercase tf in one unbroken stroke -- down the t, round the foot, up the
- * f, over its head, and back along the crossbar through both stems. The path
- * is the one `desktop/build/icon.html` draws, and `test/brandMark.test.ts`
- * fails the moment the two differ. The header used to typeset "TF" to match
- * an icon that did the same, and the pair only stayed in step because a
- * comment in the icon asked the header to follow it.
+ * One component for every wtfalch product: `name` picks the mark out of
+ * `brandMarks.ts`, and adding a product is adding a row there. The default is
+ * `tf` because it is the first, not because it is special.
  *
  * `currentColor`, so the stylesheet decides the colour and a theme can move
  * it; the mark itself knows nothing about green. No `width` or `height`
  * attributes either: the viewBox is the ink box, measured, and `.brand` sets
  * a height off the type scale so the width follows the aspect.
  *
- * **Under the pointer it becomes a cog and turns.** The mark is one stroke
- * and a cog's outline is one stroke, so the two are sampled at the same
- * number of points along their length and the points are slid from one
- * shape to the other, frame by frame -- CSS cannot morph them, because a
- * path animation needs the same commands in the same order and a `V A V A A
- * H` has nothing in common with a hundred `L`s round a gear. Honoured by
- * `prefers-reduced-motion`: the mark stays the mark.
+ * Still, on purpose. Until 0.2.0 this component also morphed tf's mark into a
+ * cog under the pointer, which made a shared package carry one product's
+ * animation. That morph is tf's own `Brand` now, layered over this path; a
+ * product that wants its mark to move does the same in its own code, and the
+ * package stays the source of the still shape every product's icon is drawn
+ * from.
+ *
+ * Stroked or filled, whichever the mark is. tf's is one line at a weight;
+ * valet's is a filled badge with the shirt cut out of it and the bow inside
+ * the cut, one path under `evenodd` so the surface shows through the shirt.
+ * Both are `currentColor`, so `.brand` still decides the colour and a theme
+ * can still move it -- a second colour would be the one thing a theme could
+ * not reach.
+ *
+ * A product's entry, `@wtfalch/design/<product>`, exports this with the
+ * product's name as the default, so a header there writes `<Brand />` and
+ * gets its own mark. Here the default is the first row.
  */
-const D = 'M372 262V620A100 100 0 0 0 572 620V330A92 92 0 0 1 756 330A100 100 0 0 1 656 430H296';
-/* The stroke's outer bounds, not the canvas: x 248..804, y 190..768. The
-   stroke is 96 wide, so 48 of cap and arc on every side is already in these. */
-const VIEW = '248 190 556 578';
-/* The cog, in the mark's own coordinates: centred on the ink box, teeth to
-   the box's edge. Six teeth, each a flat tip on two flanks over a root, as
-   one closed outline of `N` points -- the same `N` the mark is sampled at,
-   which is the whole trick. The stroke ends where it starts, and a round cap
-   on each end makes the seam invisible.
-
-   Eight teeth at two-thirds of the mark's weight -- the first version, and
-   the one kept. Six at full weight (#172) and seven at nearly full were
-   tried on William's "fatter, fewer teeth"; both lost the wheel: a thick
-   stroke fills the ring and the teeth become petals. "Can you not make it
-   look like the wheel we had?" This is that wheel.
-
-   Solid, since 2026-09-03. A stroked outline of a cog is a drawing of a
-   cog, and at header size it read as one -- "the uncanny valley where it
-   looks like a settings icon but isn't one". The morph is still stroke to
-   stroke, because that is the only way the points can slide; what changed
-   is the end of it: over the last quarter a fill comes up inside the
-   outline, with a round hole growing at the centre, and the stroke thins
-   to an edge. The result is the plain cog everyone recognises -- body,
-   hole, square teeth -- and the flanks are steeper than before so the
-   teeth are teeth and not petals once they are filled. Eight teeth again since
-   2026-09-03 -- nine and ten were tried once the cog was solid and both taken
-   back; 144 samples divide by eight. */
-const N = 144;
-const TEETH = 8;
-/* Every radius and stroke below is 0.9 of what it was on 2026-09-03: the
-   cog at the mark's full height read large beside the mark, 0.8 read
-   small, so a tenth off, proportions kept. */
-const CENTRE = { x: 526, y: 479 };
-const R_ROOT = 158;
-const R_TIP = 236;
-/* The hole, as a share of the tip radius: the reference cog's is about 0.42. */
-const R_HOLE = 104;
-/* The outline stroke rounds every corner of the filled polygon by half its
-   width -- a round join at each vertex. 40 left the teeth square; 64 was the
-   reference's rounding and a touch heavy. 48 now, sized with the teeth so
-   that a tooth is as wide as the mark's stroke: the tip arc at the outline's
-   outer edge is 0.22 of 2*pi*(262+24)/8 = 49, plus the outline's 48, is 97
-   against the mark's 96. The ring, root to hole, is 176+24-116 = 84. */
-const COG_STROKE = 43;
-/* A thin ring inside the hole, concentric, with clear ground between it and
-   the body -- the hub a cog wheel has and a plain disc with a hole does not.
-   Radius to the ring's centreline, and its stroke. */
-const R_HUB = 56;
-const HUB_STROKE = 20;
-const MARK_STROKE = 96;
-/* Where along the morph the fill starts coming up. Earlier and the fill
-   shows under a shape that is still mostly the mark, which is a blot. */
-const FILL_FROM = 0.72;
-function cogPoints() {
-    const out = [];
-    for (let i = 0; i < N; i++) {
-        const u = i / N;
-        const a = u * Math.PI * 2 - Math.PI / 2;
-        // Where in its tooth this point is: root, up the flank, along the tip,
-        // down the flank. The flanks are ramps rather than steps so the sampled
-        // outline has no corners the interpolation would cut.
-        const t = (u * TEETH) % 1;
-        let r;
-        // A tooth as wide as the mark's stroke -- see COG_STROKE.
-        // The base of a tooth spans 0.40 of its period and the tip 0.22, so each
-        // tooth narrows towards its tip -- the flanks lean in.
-        if (t < 0.3)
-            r = R_ROOT;
-        else if (t < 0.39)
-            r = R_ROOT + ((t - 0.3) / 0.09) * (R_TIP - R_ROOT);
-        else if (t < 0.61)
-            r = R_TIP;
-        else if (t < 0.7)
-            r = R_TIP - ((t - 0.61) / 0.09) * (R_TIP - R_ROOT);
-        else
-            r = R_ROOT;
-        out.push([CENTRE.x + r * Math.cos(a), CENTRE.y + r * Math.sin(a)]);
-    }
-    return out;
-}
-const COG = cogPoints();
-/* The cog's outline, started at the tooth and run in the direction that
-   keeps the points' journeys shortest. Point `i` of the mark slides to point
-   `i` of the cog, so where the cog's `i = 0` falls -- and which way round it
-   goes -- decides whether the mark unwinds into the ring or crumples through
-   it on the way. Every start and both directions are tried once, against
-   the mark as measured, and the one with the least total travel wins. */
-function aligned(mark) {
-    let best = COG;
-    let least = Number.POSITIVE_INFINITY;
-    for (const dir of [1, -1]) {
-        for (let start = 0; start < N; start++) {
-            let travel = 0;
-            for (let i = 0; i < N; i++) {
-                const c = COG[(((start + dir * i) % N) + N) % N];
-                const dx = c[0] - mark[i][0];
-                const dy = c[1] - mark[i][1];
-                travel += dx * dx + dy * dy;
-            }
-            if (travel < least) {
-                least = travel;
-                best = mark.map((_, i) => COG[(((start + dir * i) % N) + N) % N]);
-            }
-        }
-    }
-    return best;
-}
-function toPath(points, close) {
-    const body = points.map(([x, y], i) => `${i ? 'L' : 'M'}${x.toFixed(1)} ${y.toFixed(1)}`).join('');
-    return close ? `${body}Z` : body;
-}
-const ease = (t) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2);
-/* 180 ms, from 520: William asked for much faster. It is the time the eye
-   needs to see it happen, not a beat to admire. */
-const MORPH_MS = 180;
-export default function Brand({ className, title = 'tf', cog, }) {
-    const still = useRef(null);
-    /* The mark sampled along its own length, once, off the real path -- the
-       browser does the arc arithmetic -- and the cog aligned to it. Null
-       until it has. */
-    const mark = useRef(null);
-    const ring = useRef(COG);
-    /* 0 is the mark, 1 is the cog; what is drawn is the point between. */
-    const [t, setT] = useState(0);
-    const [hovered, setHovered] = useState(false);
-    const hover = cog ?? hovered;
-    const frame = useRef(0);
-    useEffect(() => {
-        const el = still.current;
-        if (!el || mark.current)
-            return;
-        const len = el.getTotalLength();
-        const pts = [];
-        for (let i = 0; i < N; i++) {
-            const p = el.getPointAtLength((len * i) / (N - 1));
-            pts.push([p.x, p.y]);
-        }
-        mark.current = pts;
-        ring.current = aligned(pts);
-    }, []);
-    // biome-ignore lint/correctness/useExhaustiveDependencies: `t` is the starting point of a run, read once when `hover` flips -- listing it would restart the morph on every frame it sets.
-    useEffect(() => {
-        if (typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches)
-            return;
-        const from = t;
-        const to = hover ? 1 : 0;
-        if (from === to)
-            return;
-        const started = performance.now();
-        const step = (now) => {
-            const k = Math.min(1, (now - started) / (MORPH_MS * Math.abs(to - from)));
-            setT(from + (to - from) * ease(k));
-            if (k < 1)
-                frame.current = requestAnimationFrame(step);
-        };
-        frame.current = requestAnimationFrame(step);
-        return () => cancelAnimationFrame(frame.current);
-    }, [hover]);
-    /* Bound once, narrowed once. `mark.current` is set by the layout effect
-       above and `t > 0` only after that, so inside the morph it is never
-       undefined -- but TypeScript cannot carry that across a `&&`, and a `!` is
-       the thing the linter rightly refuses. A named binding says the same
-       thing without asserting it. */
-    const points = t > 0 ? mark.current : null;
-    const morphing = points !== null;
-    const d = points
-        ? toPath(points.map(([x, y], i) => [
-            x + (ring.current[i][0] - x) * t,
-            y + (ring.current[i][1] - y) * t,
-        ]), t >= 1)
-        : D;
-    const width = MARK_STROKE + (COG_STROKE - MARK_STROKE) * t;
-    /* The body: 0 until FILL_FROM, 1 at the cog. The hole grows with it, so
-       the fill arrives as a disc that opens rather than a ring that appears. */
-    const body = Math.max(0, Math.min(1, (t - FILL_FROM) / (1 - FILL_FROM)));
-    const hole = R_HOLE * body;
-    const holePath = body > 0
-        ? ` M${CENTRE.x + hole} ${CENTRE.y} A${hole} ${hole} 0 1 0 ${CENTRE.x - hole} ${CENTRE.y}` +
-            ` A${hole} ${hole} 0 1 0 ${CENTRE.x + hole} ${CENTRE.y} Z`
-        : '';
-    return (_jsxs("svg", { 
-        /* `brand-turning` -- the slow spin once the cog is complete -- is not
-           applied since 2026-09-03: William asked to try it without. The rule
-           is still in the stylesheet; putting the class back is the whole
-           change. */
-        className: className, viewBox: VIEW, fill: "none", role: "img", "aria-label": title, onPointerEnter: cog === undefined ? () => setHovered(true) : undefined, onPointerLeave: cog === undefined ? () => setHovered(false) : undefined, children: [_jsx("title", { children: title }), _jsx("path", { ref: still, d: D, stroke: "currentColor", strokeWidth: "96", strokeLinecap: "round", strokeLinejoin: "round", style: morphing ? { opacity: 0 } : undefined }), morphing && body > 0 && (_jsx("path", { d: d + holePath, fill: "currentColor", fillRule: "evenodd", fillOpacity: body })), morphing && body > 0 && (_jsx("circle", { cx: CENTRE.x, cy: CENTRE.y, r: R_HUB * body, stroke: "currentColor", strokeWidth: HUB_STROKE, strokeOpacity: body })), morphing && (_jsx("path", { d: d, stroke: "currentColor", strokeWidth: width, strokeLinecap: "round", strokeLinejoin: "round" }))] }));
+export default function Brand({ name = BRAND_NAMES[0], title, className, }) {
+    const mark = BRAND_MARKS[name];
+    const said = title ?? name;
+    return (_jsxs("svg", { className: `brand${className ? ` ${className}` : ''}`, viewBox: mark.view, fill: "none", role: "img", "aria-label": said, children: [_jsx("title", { children: said }), 'fill' in mark ? (_jsx("path", { d: mark.d, fill: "currentColor", fillRule: mark.fill })) : (_jsx("path", { d: mark.d, stroke: "currentColor", strokeWidth: mark.stroke, strokeLinecap: "round", strokeLinejoin: "round" }))] }));
 }

package/dist/components/Icon.d.ts

@@ -61,4 +61,4 @@ export default function Icon({ name, size, className, title, }: {
     /** Given only when the icon is the whole message. An icon beside a label it
      *  repeats is decoration, and decoration announced twice is noise. */
     title?: string;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;