@wtfalch/design 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Tallis Falch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# @wtfalch/design
+
+Components on a fixed token vocabulary, so an app can look like itself without
+forking the stylesheet.
+
+```bash
+pnpm add @wtfalch/design
+```
+
+```ts
+import '@wtfalch/design/tokens.css'   // the vocabulary and its base values
+import '@wtfalch/design/styles.css'   // the components
+```
+
+## The idea
+
+A **theme is a set of values for a fixed vocabulary** — colour, surface,
+typography, shape, density, motion and interaction. It never ships a selector.
+
+That constraint is not a limitation, it is what makes the package safe to
+change: the moment a theme can write a rule, every theme becomes a fork of the
+stylesheet and no change to a component is safe again. What makes a theme
+expressive instead is a vocabulary wide enough that the thing you want to vary
+is already a value — a screen background, a hover lift, how fast things move.
+
+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
+
+```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
+```
+
+Name the tokens you change; the rest inherit from `tokens.css`. A theme naming
+three tokens is valid.
+
+**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.
+
+## The three kinds of token
+
+| | |
+|---|---|
+| **themeable** (47) | A theme may set it. `TOKEN_KEYS`, and the keys of `ThemeTokens`. |
+| **derived** (16) | `calc()` off a themeable token, and **not** settable. `--text-*` follow `--font-size`; `--space-*` follow `--density`. Move the input, not the output — a step written as a literal is a scale that stopped scaling. |
+| **fixed** (3) | Not themeable. `--tile-control` is geometry other things are measured against, `--nudge` is optical alignment rather than spacing, and `--tick-mask` is a glyph — an arbitrary SVG from a theme is a theme shipping markup. |
+
+`tokens.test.ts` holds all three lists to `tokens.css` in both directions. A
+token added to the stylesheet and to no list fails the suite rather than
+becoming a fourth, undocumented category.
+
+## The measurement ships
+
+```ts
+import { ratio } from '@wtfalch/design'
+ratio('#6d28d9', '#ffffff') // 6.30 -- the label on your primary button
+```
+
+`test/contrast.test.ts` measures every built-in theme, pair by pair, with the
+WCAG 2 formula: text on the page and on both panels, hints, the label on the
+primary button, all four status colours, and the two boundaries that want
+3:1. On its first run it found the built-in information blue at 3.96:1 on
+white. `ratio` and `luminance` are exported so the theme you write -- the one
+nobody here will ever look at -- can be held to the same numbers.
+
+## Two rules that outrank any theme
+
+**`prefers-reduced-motion` wins.** The motion tokens collapse to `0s` under it,
+whatever the theme says, and the hover and press transforms go with them. Motion
+is an accessibility setting before it is a style, so a theme may set the
+durations and may not decide whether they apply.
+
+**Contrast is measured, not judged.** 4.5:1 for text and 3:1 for a non-text
+boundary, in every theme. `--on-accent` exists because a hardcoded white button
+label vanishes under a pale accent, and `--border-strong` exists because a
+hairline divider and a control's outline have different thresholds and cannot
+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:
+
+```html
+<script>
+  try {
+    var t = localStorage.getItem('theme')
+    if (t) document.documentElement.dataset.theme = t
+  } catch (e) {}
+</script>
+```
+
+Your server stays the source of truth. `localStorage` only beats the paint.
+
+## Built-ins
+
+`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.
+
+## Status
+
+`0.1.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.
+
+Requires React 19. Behaviour comes from
+[React Aria Components](https://react-spectrum.adobe.com/react-aria/); every
+pixel is the stylesheet's, styled through `data-*` attributes off the token
+vocabulary. No Tailwind, no utility layer.
+
+## Source and issues
+
+[github.com/wtfalch/design](https://github.com/wtfalch/design) — the package
+under `packages/design`, the gallery under `gallery`, and the visual, axe and
+keyboard suites under `gallery-e2e`. The repository's `CLAUDE.md` carries the
+rules the components follow, each with the bug that produced it.
+
+## Licence
+
+MIT.

package/dist/components/Brand.d.ts

@@ -0,0 +1,10 @@
+export default function Brand({ className, title, cog, }: {
+    className?: string;
+    /** 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;
+}): import("react").JSX.Element;

package/dist/components/Brand.js

@@ -0,0 +1,212 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+/**
+ * The wordmark: the app icon's mark, without the tile.
+ *
+ * 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.
+ *
+ * `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.
+ */
+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" }))] }));
+}

package/dist/components/Button.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A button. The most-copied markup in the app, finally a component.
+ *
+ * Four kinds that look like four things, three sizes, and a busy state that is
+ * not a disabled one. None of that is new — all of it was in the stylesheet
+ * already, and every call site assembled it by hand from
+ * `<button className="primary size-sm">`. A page in the gallery documented that
+ * markup, which is how a catalogue teaches people to copy rather than import.
+ *
+ * **`type="button"` is the default, and that is the whole reason this exists
+ * rather than a class.** A `<button>` with no type is `type="submit"`: drop one
+ * inside a `<form>` and pressing it submits the form and reloads the page. That
+ * is not a thing anybody writes on purpose, it is a thing everybody forgets —
+ * fifty-eight of them here, found by a linter rather than by a person. A
+ * default cannot be forgotten. `type="submit"` is still available, and now it
+ * has to be asked for, which is the right way round.
+ *
+ * **Behaviour comes from React Aria.** Press handling that works with a mouse,
+ * a touch, a pen and a keyboard is more than `onClick`: it is pointer capture,
+ * the difference between a press that ends on the button and one that drags
+ * off it, and not firing twice on a touch screen. `data-pressed`,
+ * `data-hovered` and `data-focus-visible` land on the element, so the
+ * stylesheet keeps describing states rather than tracking them.
+ */
+import { type ButtonProps } from 'react-aria-components';
+export interface Props extends Omit<ButtonProps, 'className' | 'style' | 'children'> {
+    children?: React.ReactNode;
+    /** The same word every other control in the package uses. React Aria spells
+     *  it `isDisabled`, and that still works; this one exists so a consumer does
+     *  not have to remember which of the two a given component wants. */
+    disabled?: boolean;
+    /**
+     * What kind of thing pressing it does. `kind`, not `tone`: across the
+     * package `tone` is a semantic colour -- info, good, warn, bad -- and a
+     * button's primary/ghost/danger is a role, not a colour.
+     *
+     * `primary` is the one action the panel is for, and there is at most one.
+     * `ghost` is a secondary action that should not compete. `danger` is red
+     * before you hover it, because hover is the one moment it is too late to be
+     * told.
+     */
+    kind?: 'default' | 'primary' | 'ghost' | 'danger';
+    /** Asked for, never inherited. Size used to come from a descendant selector,
+     *  which made a button's size a fact about where somebody had put it. */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Working, not disabled.
+     *
+     * On `aria-busy`, so the styling and the screen reader read the same
+     * attribute. A busy button keeps its label — "Installing…" — because
+     * replacing the words with a spinner removes the only thing that says what is
+     * taking so long.
+     */
+    busy?: boolean;
+    /** Full width of whatever holds it. For a button that is the whole row. */
+    block?: boolean;
+    /** An icon and nothing else. The `aria-label` is then not optional, and
+     *  TypeScript cannot make it required here without a second component, so
+     *  `a11y.spec.ts` is what actually holds it. */
+    iconOnly?: boolean;
+    className?: string;
+}
+export default function Button({ kind, disabled, size, busy, block, iconOnly, className, children, ...rest }: Props): import("react").JSX.Element;

package/dist/components/Button.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A button. The most-copied markup in the app, finally a component.
+ *
+ * Four kinds that look like four things, three sizes, and a busy state that is
+ * not a disabled one. None of that is new — all of it was in the stylesheet
+ * already, and every call site assembled it by hand from
+ * `<button className="primary size-sm">`. A page in the gallery documented that
+ * markup, which is how a catalogue teaches people to copy rather than import.
+ *
+ * **`type="button"` is the default, and that is the whole reason this exists
+ * rather than a class.** A `<button>` with no type is `type="submit"`: drop one
+ * inside a `<form>` and pressing it submits the form and reloads the page. That
+ * is not a thing anybody writes on purpose, it is a thing everybody forgets —
+ * fifty-eight of them here, found by a linter rather than by a person. A
+ * default cannot be forgotten. `type="submit"` is still available, and now it
+ * has to be asked for, which is the right way round.
+ *
+ * **Behaviour comes from React Aria.** Press handling that works with a mouse,
+ * a touch, a pen and a keyboard is more than `onClick`: it is pointer capture,
+ * the difference between a press that ends on the button and one that drags
+ * off it, and not firing twice on a touch screen. `data-pressed`,
+ * `data-hovered` and `data-focus-visible` land on the element, so the
+ * stylesheet keeps describing states rather than tracking them.
+ */
+import { useEffect, useRef } from 'react';
+import { Button as AriaButton } from 'react-aria-components';
+export default function Button({ kind = 'default', disabled, size = 'md', busy, block, iconOnly, className, children, ...rest }) {
+    const classes = [
+        iconOnly ? 'icon-btn' : '',
+        kind === 'default' ? '' : kind,
+        size === 'md' ? '' : `size-${size}`,
+        block ? 'block' : '',
+        className ?? '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    /**
+     * `aria-busy`, set on the element rather than passed as a prop.
+     *
+     * React Aria runs everything through `filterDOMProps`, which forwards only
+     * the labelling aria attributes -- `aria-label`, `aria-labelledby`,
+     * `aria-describedby`, `aria-details`. `aria-busy` is dropped in silence, so
+     * the prop looked right, typechecked, and the countdown bar under a busy
+     * button simply stopped rendering.
+     *
+     * The obvious alternative is React Aria's own `isPending`, and it is the
+     * wrong one here: it marks the button `aria-disabled` and stops it being
+     * pressed. This component's whole documented distinction is that busy is
+     * *not* disabled -- "Working, not disabled", and the label stays because it
+     * is the only thing saying what is taking so long. Swapping the semantics to
+     * get a tidier call site would be changing behaviour nobody asked to change.
+     */
+    const ref = useRef(null);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        if (busy)
+            el.setAttribute('aria-busy', 'true');
+        else
+            el.removeAttribute('aria-busy');
+    }, [busy]);
+    return (_jsx(AriaButton, { ref: ref, 
+        /* The default, and the point of the component. React Aria sets this too;
+           stating it here means the prop is visible in the signature rather than
+           inherited from a library the caller has not read. */
+        type: "button", ...rest, isDisabled: rest.isDisabled ?? disabled, 
+        /* Always a string, never undefined. React Aria stamps its own
+           `react-aria-Button` class when `className` is absent, so an untoned
+           button arrived carrying a class from a library the stylesheet has never
+           heard of. */
+        className: classes, children: children }));
+}

package/dist/components/Callout.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Something the page needs to say, in the place it applies to.
+ *
+ * The third component the gallery documented and nobody could import — 31 call
+ * sites assembling `className="callout callout-bad"` by hand, and a `-mark`
+ * that was a letter somebody typed (`i`, `!`, `✓`) rather than the icon set the
+ * rest of the app draws from.
+ *
+ * **A Callout is not a Toast.** A toast floats over the page and takes no
+ * space; this sits in the flow, next to the thing it is about, and pushes what
+ * follows down. That is the point of it: "this server is not answering" belongs
+ * beside the server, not in the corner.
+ *
+ * **`timed` makes it a toast that stayed home.** A countdown bar, five seconds,
+ * then gone. The rule that comes with it: **anything that disappears on a timer
+ * must be safe to have missed.** "Saved" qualifies. "This download failed" does
+ * not, and neither does anything carrying a button — if the reader has to act,
+ * the message waits for them. The countdown pauses on hover for the same
+ * reason, because a message that expires while you are reading it was never
+ * really shown.
+ */
+import { type IconName } from './Icon';
+export default function Callout({ tone, children, icon, timed, onDismiss, className, }: {
+    tone?: 'info' | 'good' | 'warn' | 'bad';
+    children: React.ReactNode;
+    /** Off by default: most callouts are a sentence, and an icon beside every
+     *  sentence is noise. `true` uses the one that matches the tone. */
+    icon?: boolean | IconName;
+    /** `true` for five seconds, a number for that many milliseconds. */
+    timed?: boolean | number;
+    /** Told when the countdown runs out, for a caller that keeps its own state.
+     *  Optional: `timed` on its own is enough, and the callout removes itself.
+     *  Requiring a callback to make a timer work is a bar that counts down to
+     *  nothing when somebody forgets one. */
+    onDismiss?: () => void;
+    className?: string;
+}): import("react").JSX.Element | null;

package/dist/components/Callout.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Something the page needs to say, in the place it applies to.
+ *
+ * The third component the gallery documented and nobody could import — 31 call
+ * sites assembling `className="callout callout-bad"` by hand, and a `-mark`
+ * that was a letter somebody typed (`i`, `!`, `✓`) rather than the icon set the
+ * rest of the app draws from.
+ *
+ * **A Callout is not a Toast.** A toast floats over the page and takes no
+ * space; this sits in the flow, next to the thing it is about, and pushes what
+ * follows down. That is the point of it: "this server is not answering" belongs
+ * beside the server, not in the corner.
+ *
+ * **`timed` makes it a toast that stayed home.** A countdown bar, five seconds,
+ * then gone. The rule that comes with it: **anything that disappears on a timer
+ * must be safe to have missed.** "Saved" qualifies. "This download failed" does
+ * not, and neither does anything carrying a button — if the reader has to act,
+ * the message waits for them. The countdown pauses on hover for the same
+ * reason, because a message that expires while you are reading it was never
+ * really shown.
+ */
+import { useEffect, useRef, useState } from 'react';
+import Icon from './Icon';
+/** Long enough to read twice, which is how long it takes to notice something
+ *  appeared and then read it.
+ *
+ *  Not exported: nothing outside this file used it, and a non-component export
+ *  costs the whole module its Fast Refresh boundary -- editing the callout then
+ *  re-runs App instead of swapping this component in place. */
+const CALLOUT_TIMEOUT = 5000;
+const MARK = {
+    info: 'info',
+    good: 'check',
+    warn: 'warning',
+    bad: 'error',
+};
+export default function Callout({ tone, children, icon, timed, onDismiss, className, }) {
+    const total = typeof timed === 'number' ? timed : CALLOUT_TIMEOUT;
+    const [gone, setGone] = useState(false);
+    const running = Boolean(timed) && !gone;
+    const [paused, setPaused] = useState(false);
+    const left = useRef(total);
+    const since = useRef(0);
+    useEffect(() => {
+        if (!running || paused)
+            return;
+        since.current = Date.now();
+        const timer = setTimeout(() => {
+            setGone(true);
+            onDismiss?.();
+        }, left.current);
+        return () => {
+            clearTimeout(timer);
+            // What is left when a hover interrupts, so resuming does not restart the
+            // five seconds from the top every time the pointer crosses it.
+            left.current = Math.max(0, left.current - (Date.now() - since.current));
+        };
+    }, [running, paused, onDismiss]);
+    const mark = icon === true ? MARK[tone ?? 'info'] : typeof icon === 'string' ? icon : null;
+    if (gone)
+        return null;
+    return (_jsxs("div", { className: `callout${tone ? ` callout-${tone}` : ''}${running ? ' callout-timed' : ''}${className ? ` ${className}` : ''}`, 
+        /* An alert interrupts whatever is being read, which is right for bad news
+           and rude for "saved". */
+        role: tone === 'bad' ? 'alert' : 'status', onMouseEnter: () => running && setPaused(true), onMouseLeave: () => running && setPaused(false), onFocusCapture: () => running && setPaused(true), onBlurCapture: () => running && setPaused(false), children: [mark && (_jsx("span", { className: "callout-mark", "aria-hidden": "true", children: _jsx(Icon, { name: mark, size: 16 }) })), _jsx("div", { className: "grow", children: children }), running && (
+            /* Decoration: the time remaining is not information anybody can act on,
+               and a screen reader counting down a bar is noise on top of a message
+               it has already read out. */
+            _jsx("span", { className: `callout-clock${paused ? ' is-held' : ''}`, style: { animationDuration: `${total}ms` }, "aria-hidden": "true" }))] }));
+}