staffa 0.1.0 → 0.3.0

package/dist/theme.js

@@ -1,65 +1,89 @@
 import A from "aberdeen";
 /**
- * The default dark Skye theme: modern and intentionally a little vivid so it
- * stands out of the box.
+ * Theming and global base styles for Staffa.
  *
- * This is a live Aberdeen proxy — mutate it (e.g. `darkTheme.sPrimary = "..."`)
- * and, while dark mode is active, the change flows straight into the CSS
- * variables. Use this to retheme dark and {@link lightTheme} independently.
- */
-export const darkTheme = A.proxy({
-    sBg: "#0e1015",
-    sSurface: "#181b22",
-    sSurfaceHi: "#222632",
-    sFg: "#e8eaf0",
-    sFgMuted: "#a6acba",
-    sFgFaint: "#6b7280",
-    sBorder: "#2c313c",
-    sBorderStrong: "#3c4352",
-    sPrimary: "#8b7bff",
-    sPrimaryHover: "#a99dff",
-    sPrimaryFg: "#0c0a1a",
-    sDanger: "#ff6b6b",
-    sSuccess: "#46d39a",
-    sWarning: "#fbbf24",
-    sFocus: "rgba(139, 123, 255, 0.45)",
-    sRadius: "10px",
-    sRadiusLg: "16px",
-    sShadow: "0 8px 30px rgba(0, 0, 0, 0.45)",
-});
-/**
- * The light Skye theme — the same lavender brand, retuned for a bright,
- * modern surface: white cards on a soft grey page, a deeper primary so it
- * reads well on light backgrounds, and a softer elevation shadow.
+ * # The surface model
  *
- * Like {@link darkTheme}, a live proxy: mutate it to retheme light mode.
- */
-export const lightTheme = A.proxy({
-    sBg: "#f3f4f8",
-    sSurface: "#ffffff",
-    sSurfaceHi: "#eceef4",
-    sFg: "#1b1e27",
-    sFgMuted: "#5b6273",
-    sFgFaint: "#9aa1b2",
-    sBorder: "#e2e5ee",
-    sBorderStrong: "#c7ccda",
-    sPrimary: "#6c5ce7",
-    sPrimaryHover: "#5847d4",
-    sPrimaryFg: "#ffffff",
-    sDanger: "#e23b3b",
-    sSuccess: "#1f9d6b",
-    sWarning: "#d97706",
-    sFocus: "rgba(108, 92, 231, 0.35)",
-    sRadius: "10px",
-    sRadiusLg: "16px",
-    sShadow: "0 6px 24px rgba(20, 24, 40, 0.12)",
-});
-const STORAGE_KEY = "skye:darkMode";
-/**
- * The explicit dark-mode choice — `true` (force dark), `false` (force light) or
- * `undefined` (follow the OS via {@link A.darkMode}). A reactive proxy, seeded
- * from localStorage so the persisted preference applies on the first paint.
+ * A Staffa app is a tree of **surfaces**. A surface is anything with its own
+ * background and the text colour that goes on it — the page, a card, a raised
+ * header, a coloured button. Mark an element as a surface with the `.s-s` class,
+ * then add modifier classes to colour it. A surface carries two colours:
+ *
+ * - `--s-a` — its default **foreground** (ink)
+ * - `--s-b` — its default **background** (fill)
+ *
+ * set by a **level** modifier — `.base` (the page), `.panel` (the default card),
+ * `.raised` (elevated chrome) — or an **accent role** modifier — `.primary`,
+ * `.secondary`, `.gradient` (the brand sweep), `.neutral`, `.danger`,
+ * `.success`, `.warning`.
+ *
+ * A **variant** modifier — `.filled` (the default), `.tonal` or `.outlined` —
+ * decides how `--s-a`/`--s-b` map onto the tokens widgets read
+ * (`--s-fg`/`--s-bg`). A shared rule then derives muted/faint/border from that
+ * pair and paints the element. Because the derivation reads `$s-fg`/`$s-bg`,
+ * every surface gets its *own* legible secondary colours: drop a widget on any
+ * surface and it adapts. (`:root` is an implicit filled surface, so the page
+ * renders without extra classes.)
+ *
+ * Components build surfaces by combining classes, e.g.
+ * `A("div.s-s.panel.outlined", opts.attrs)` — and because `opts.attrs` is the
+ * caller's escape hatch, passing e.g. `.filled` or `.danger` overrides the
+ * default look.
+ *
+ * | token            | meaning                                  |
+ * | ---------------- | ---------------------------------------- |
+ * | `--s-fg`         | default text                              |
+ * | `--s-bg`         | background                                |
+ * | `--s-fg-muted`   | secondary text (subtitles, help)          |
+ * | `--s-fg-faint`   | placeholders, disabled                    |
+ * | `--s-border` / `--s-border-strong` | borders                 |
+ * | `--s-accent`     | brand "pop" colour (active indicators, etc.) |
+ * | `--s-gradient`   | primary→secondary brand sweep (mark, primary buttons, active nav) |
+ * | `--s-glow`       | soft coloured shadow for lit brand elements |
+ * | `--s-link` / `--s-focus` | link & focus-ring colours         |
+ * | `--s-radius` / `--s-radius-lg` / `--s-shadow` | shape tokens      |
+ *
+ * `--s-accent` and `--s-link` default to the brand / link colour, but on a
+ * bright coloured surface (`.primary`, `.danger`, …) they fall back to that
+ * surface's own ink so they stay legible.
+ *
+ * # The palette
+ *
+ * All colours come from a small set of named **palette** tokens on `:root`, set
+ * per mode — the only place colours live, and the single place to re-skin:
+ * `--s-primary`, `--s-secondary` (the two ends of `--s-gradient`), `--s-danger`,
+ * `--s-success`, `--s-warning` (accent fills, which
+ * double as semantic *ink* on neutral surfaces), `--s-neutral`, `--s-page`,
+ * `--s-panel`, `--s-raised` (neutral fills), `--s-ink` (text on neutral) and
+ * `--s-on-accent` (text on accent fills), plus `--s-link`/`--s-focus` and the
+ * shape tokens. Every surface rule is wired to these, so they adapt with the
+ * mode and with any override.
+ *
+ * # Variants
+ *
+ * Because the variant decides how `--s-a`/`--s-b` become `--s-fg`/`--s-bg`, the
+ * three looks are generic and work on *any* role: `.tonal` reads the fill colour
+ * as ink over a soft self-tint; `.outlined` reads it as ink over a transparent
+ * fill with a coloured edge (inheriting the parent's background, so its derived
+ * tokens read the real surroundings). Inside any of them `--s-fg`/`--s-bg` still
+ * describe the real, rendered colours.
+ *
+ * # Customising
+ *
+ * There's no JS theme object — the colours live in the palette `insertGlobalCss`
+ * call below, branched on {@link getDarkMode}. Re-skin from your app by
+ * overriding palette tokens (per mode if you like), or give a surface an
+ * image/gradient background (set `--s-b` to the dominant fallback colour so
+ * derived tokens stay sensible). Staffa uses global, `s-`-prefixed classes, so
+ * nothing is scoped away from you.
+ *
+ * ```ts
+ * A(() => A.insertGlobalCss({ ":root": getDarkMode() ? "--s-primary:#28c4a0" : "--s-primary:#1f9d6b" }));
+ * A.insertGlobalCss({ ".s-s.panel": "background: url(paper.png); --s-b: #efe9dd" });
+ * ```
  */
+const STORAGE_KEY = "staffa:darkMode";
+/** The explicit dark-mode choice; `undefined` follows the OS via {@link A.darkMode}. */
 const $override = A.proxy({ value: readStoredOverride() });
 /** Read the persisted dark-mode override from localStorage (defensively). */
 function readStoredOverride() {
@@ -77,8 +101,7 @@ function readStoredOverride() {
 }
 /**
  * Force dark mode (`true`), light mode (`false`), or follow the OS preference
- * (`undefined`). Takes effect immediately and is persisted to localStorage, so
- * the choice survives reloads.
+ * (`undefined`). Takes effect immediately and is persisted to localStorage.
  */
 export function setDarkMode(value) {
     $override.value = value;
@@ -96,40 +119,214 @@ export function setDarkMode(value) {
  * Whether dark mode is currently active. Reactive — read it inside a scope to
  * re-run on changes.
  *
- * @param allowAuto - When `true`, returns `undefined` (rather than resolving to
- *   a boolean) if the user is following the OS preference, so a dark/light/auto
- *   control can tell the three states apart.
+ * @param allowAuto - When `true`, returns `undefined` (rather than a boolean) if
+ *   the user is following the OS preference, so a dark/light/auto control can
+ *   tell the three states apart.
  */
 export function getDarkMode(allowAuto = false) {
     const v = $override.value;
     return v === undefined && !allowAuto ? A.darkMode() : v;
 }
-// Set up everything as this module loads. Spacing scale first ($1 = 0.25rem,
-// $2 = 0.5rem, $3 = 1rem, ...), then reactively merge the active theme into the
-// CSS variables. This scope runs synchronously now — before the first paint —
-// so the correct colors are in place immediately (no flash), and A.merge
-// subscribes to the theme it reads, so toggling the mode or mutating
-// darkTheme / lightTheme re-applies automatically.
-A.setSpacingCssVars();
+// ---------------------------------------------------------------------------
+// Reactive palette — the ONE place colours live, and the only thing that
+// differs between light and dark. Everything else is wired to these named
+// tokens, so an app can re-skin by overriding just a few of them. The accent
+// names (--s-primary/-danger/-success/-warning) double as semantic *ink*
+// colours, legible as text/borders on neutral surfaces.
+// ---------------------------------------------------------------------------
 A(() => {
-    A.merge(A.cssVars, getDarkMode() ? darkTheme : lightTheme);
+    if (getDarkMode()) {
+        A.insertGlobalCss({
+            ":root": "--s-primary:#8b7bff --s-secondary:#ef7fd0 --s-danger:#ff6b6b --s-success:#46d39a --s-warning:#fbbf24 " +
+                "--s-neutral:#3c4352 --s-page:#0e1015 --s-panel:#181b22 --s-raised:#222632 " +
+                "--s-ink:#e8eaf0 --s-on-accent:#0c0a14 --s-focus:rgba(139,123,255,0.45) " +
+                "--s-radius:12px --s-radius-lg:18px --s-shadow: 0 10px 34px rgba(0,0,0,0.5);",
+            // Contextual link, restored across the neutral group (see static block).
+            ":root, .s-s.base, .s-s.panel, .s-s.raised, .s-s.neutral": "--s-link:#6db3ff",
+        });
+    }
+    else {
+        A.insertGlobalCss({
+            ":root": "--s-primary:#6c5ce7 --s-secondary:#d6459e --s-danger:#e23b3b --s-success:#1f9d6b --s-warning:#d97706 " +
+                "--s-neutral:#c7ccda --s-page:#f3f4f8 --s-panel:#ffffff --s-raised:#eceef4 " +
+                "--s-ink:#1b1e27 --s-on-accent:#0c0a14 --s-focus:rgba(108,92,231,0.35) " +
+                "--s-radius:12px --s-radius-lg:18px --s-shadow: 0 10px 30px rgba(20,24,40,0.13);",
+            ":root, .s-s.base, .s-s.panel, .s-s.raised, .s-s.neutral": "--s-link:#2563eb",
+        });
+    }
 });
-// A deliberately light reset. It sets box-sizing and sensible colors/fonts, but
-// does NOT strip margins from headings/paragraphs/lists, so rendered rich
-// content (e.g. markdown-to-HTML) keeps reasonable default rhythm.
+// ---------------------------------------------------------------------------
+// Static structure — inserted once, all wired to the palette above.
+//
+// A surface is marked with `.s-s`. Its level/role modifier sets two anchors
+// (--s-a ink, --s-b fill); its variant modifier (`.filled` default, `.tonal`,
+// `.outlined`) decides how those anchors map onto the rendered fg/bg. `:root`
+// (the page) is an implicit filled surface. Every `.s-s` then runs the same
+// derive+paint step, reading the resolved fg/bg, so each one gets its own
+// legible secondary tokens regardless of variant.
+//
+// Rule order matters: the variant/role rules below all share specificity, so a
+// later one wins. `.filled` therefore comes *last* among the variants — that's
+// what lets a caller's `attrs: ".filled"` override a component's default
+// `.tonal`/`.outlined`.
+// ---------------------------------------------------------------------------
+A.setSpacingCssVars();
+A.insertGlobalCss({
+    // Derived brand tokens. These only reference the per-mode palette colours, so
+    // they're defined once here and track the active mode (and any re-skin):
+    // `--s-gradient` is the primary→secondary brand sweep used for the headline
+    // mark, primary buttons and the active nav pill; `--s-glow` is a soft coloured
+    // shadow that makes those same elements feel lit; `--s-page-bg` is a faint
+    // twin-corner aurora wash painted on the page surface.
+    ":root": "--s-gradient: linear-gradient(135deg, $s-primary, $s-secondary); " +
+        "--s-glow: 0 8px 24px color-mix(in srgb, $s-primary 32%, transparent); " +
+        "--s-page-bg: radial-gradient(120% 80% at 100% 0%, color-mix(in oklab, $s-secondary, transparent 86%), transparent 56%), radial-gradient(120% 80% at 0% 0%, color-mix(in oklab, $s-primary, transparent 87%), transparent 56%), $s-page;",
+    // Level/role modifier → anchors. Levels (neutral elevations) use the shared
+    // ink; accent roles use the on-accent ink over their named fill. The page
+    // (`.base`) additionally paints the aurora wash; `--s-b` keeps the solid
+    // fallback so every derived token stays sensible.
+    ":root, .s-s.base": "--s-a:$s-ink --s-b:$s-page",
+    ".s-s.base": "background: $s-page-bg;",
+    ".s-s.panel": "--s-a:$s-ink --s-b:$s-panel",
+    ".s-s.raised": "--s-a:$s-ink --s-b:$s-raised",
+    ".s-s.neutral": "--s-a:$s-ink --s-b:$s-neutral",
+    ".s-s.primary": "--s-a:$s-on-accent --s-b:$s-primary",
+    ".s-s.secondary": "--s-a:$s-on-accent --s-b:$s-secondary",
+    ".s-s.danger": "--s-a:$s-on-accent --s-b:$s-danger",
+    ".s-s.success": "--s-a:$s-on-accent --s-b:$s-success",
+    ".s-s.warning": "--s-a:$s-on-accent --s-b:$s-warning",
+    // `.gradient` is an accent role whose fill is the brand sweep. Its `--s-b`
+    // anchor stays the solid `--s-primary` so the derived tokens (muted ink,
+    // border, …) remain sensible; the gradient itself is painted further down,
+    // only in the filled context (tonal/outlined read the solid fallback instead).
+    ".s-s.gradient": "--s-a:$s-on-accent --s-b:$s-primary",
+    // Filled default (bare `.s-s` and `:root`): map the anchors to fg/bg, derive
+    // the secondary tokens from that pair, then paint. var() resolves at use time,
+    // so the tonal/outlined remaps below feed back into the derived tokens.
+    ":root, .s-s": "--s-fg:$s-a --s-bg:$s-b " +
+        "--s-fg-muted: color-mix(in oklab, $s-fg, $s-bg 42%); " +
+        "--s-fg-faint: color-mix(in oklab, $s-fg, $s-bg 64%); " +
+        "--s-border: color-mix(in oklab, $s-fg, $s-bg 82%); " +
+        "--s-border-strong: color-mix(in oklab, $s-fg, $s-bg 68%); " +
+        // Themed scrollbars (standard properties, honoured by Firefox and modern
+        // Chromium): the thumb uses the surface's derived border token, so the bar
+        // tracks the active mode/re-skin and a nested surface's own colours.
+        "scrollbar-width:thin scrollbar-color: $s-border-strong transparent; " +
+        "background:$s-bg color:$s-fg",
+    // WebKit/older-Chromium counterpart to the standard `scrollbar-*` props above:
+    // a transparent track and a rounded thumb (border-clipped to leave breathing
+    // room) that brightens on hover.
+    ".s-s::-webkit-scrollbar, .s-s ::-webkit-scrollbar": "width:10px height:10px",
+    ".s-s::-webkit-scrollbar-track, .s-s ::-webkit-scrollbar-track": "background:transparent",
+    ".s-s::-webkit-scrollbar-thumb, .s-s ::-webkit-scrollbar-thumb": "background:$s-border-strong border-radius:99px border: 2px solid transparent; background-clip:padding-box",
+    ".s-s::-webkit-scrollbar-thumb:hover, .s-s ::-webkit-scrollbar-thumb:hover": "background:$s-fg-faint background-clip:padding-box",
+    // Tonal: the fill colour becomes the ink, over a soft tint of itself.
+    ".s-s.tonal": "--s-fg:$s-b --s-bg: color-mix(in srgb, $s-b 16%, transparent);",
+    // Outlined: the fill colour is the ink; --s-bg *inherits* the parent's bg (the
+    // token the derivations read, so the edge mixes ink with the real surroundings)
+    // while the painted background is transparent, letting that parent fill — even
+    // a gradient or image — show through.
+    ".s-s.outlined": "--s-fg:$s-b --s-bg:inherit background:transparent --s-border: color-mix(in srgb, $s-fg 55%, $s-bg);",
+    // Filled, explicit — last among the variants so a caller's `attrs: ".filled"`
+    // overrides a component's default `.tonal`/`.outlined` (resetting both the
+    // anchors and the painted background).
+    ".s-s.filled": "--s-fg:$s-a --s-bg:$s-b background:$s-bg;",
+    // Paint the brand sweep for a filled `.gradient` surface. Sits after the
+    // variant rules and is keyed on `:not(.tonal):not(.outlined)`, so those
+    // variants keep their solid-primary tint/edge.
+    ".s-s.gradient:not(.tonal):not(.outlined)": "background: $s-gradient;",
+    // Contextual accent: the brand pop colour on neutral surfaces. Declared on the
+    // whole neutral group so re-entering a neutral surface under a coloured one
+    // restores it. (--s-link gets the same treatment in the reactive block, where
+    // its per-mode literal lives — it can't reference the palette, as the palette
+    // source and the contextual token share the name --s-link.)
+    ":root, .s-s.base, .s-s.panel, .s-s.raised, .s-s.neutral": "--s-accent:$s-primary",
+    // On a bright coloured surface those wouldn't be legible, so they fall back to
+    // the surface's own ink. (Keyed on the role modifier, so it holds across
+    // variants — and tracks the tonal/outlined fg remap.)
+    ".s-s.primary, .s-s.secondary, .s-s.danger, .s-s.success, .s-s.warning, .s-s.gradient": "--s-accent:$s-fg --s-link:$s-fg",
+});
+// A deliberately light reset. Colours/shape come from the contextual tokens, so
+// rich content (e.g. markdown-to-HTML) adapts to whatever surface holds it. The
+// vertical rhythm / typography of block elements is handled separately, below.
 A.insertGlobalCss({
     "*, *::before, *::after": "box-sizing:border-box",
     html: "text-size-adjust:100%",
-    body: "m:0 bg:$sBg fg:$sFg line-height:1.5 font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; -webkit-font-smoothing:antialiased",
-    a: "fg:$sPrimary text-decoration:underline text-underline-offset:2px",
-    "a:hover": "fg:$sPrimaryHover",
+    body: "m:0 line-height:1.5 font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; -webkit-font-smoothing:antialiased",
+    a: "color: $s-link; text-decoration:underline text-underline-offset:2px; transition: color 0.12s, filter 0.12s;",
+    "a:hover": "filter: brightness(1.15)",
     "input, button, textarea, select": "font:inherit color:inherit",
     "code, kbd, samp, pre": "font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;",
-    code: "bg:$sSurfaceHi padding: 0.12em 0.34em; r:4px font-size:0.9em",
-    pre: "bg:$sSurface p:$3 r:$sRadius overflow:auto",
-    "pre code": "bg:transparent p:0",
+    code: "background: color-mix(in oklab, $s-fg, $s-bg 86%); padding: 0.12em 0.34em; r:4px font-size:0.9em",
+    pre: "background: color-mix(in oklab, $s-fg, $s-bg 92%); p:$3 r: $s-radius; overflow:auto",
+    "pre code": "background:transparent p:0",
     "img, svg, video, canvas": "max-width:100% h:auto",
-    hr: "border:0 border-top: 1px solid $sBorder; margin: $3 0;",
-    "::placeholder": "fg:$sFgFaint opacity:1",
-    ":focus-visible": "outline: 2px solid $sFocus; outline-offset:2px",
+    hr: "border:0 border-top: 1px solid $s-border;",
+    "::placeholder": "color: $s-fg-faint; opacity:1",
+    ":focus-visible": "outline: 2px solid $s-focus; outline-offset:2px",
+    small: "color:$s-fg-muted font-size:0.9em",
+    // Respect users who prefer less motion: keep transitions essentially instant.
+    "@media (prefers-reduced-motion: reduce)": {
+        "*, *::before, *::after": "transition-duration: 0.01ms !important; animation-duration: 0.01ms !important; scroll-behavior: auto !important;",
+    },
+});
+// ── Suppress transitions during the initial load ─────────────────────────────
+// Buttons (and links) transition their colours, so a light↔dark switch animates
+// smoothly. On a *cold* load that's a liability: elements mount and paint in the
+// active theme in one pass, but a transitioning element animates from its
+// default (unstyled) colours into the theme — so a fresh button visibly slides
+// from light to dark while the rest of the page is already correct. Tag <html>
+// until the first frame has painted and hard-disable transitions under that tag,
+// so the initial render snaps straight to the right colours. Two rAFs: the first
+// runs before the paint that shows the themed UI, the second clears the tag just
+// after it — later theme switches then animate as normal.
+A.insertGlobalCss({
+    ".s-preload, .s-preload *, .s-preload *::before, .s-preload *::after": "transition: none !important; animation: none !important;",
+});
+if (typeof document !== "undefined" && typeof requestAnimationFrame === "function") {
+    const root = document.documentElement;
+    root.classList.add("s-preload");
+    requestAnimationFrame(() => requestAnimationFrame(() => root.classList.remove("s-preload")));
+}
+// ── Flow content: vertical rhythm & light typography ─────────────────────────
+// Sensible block defaults for *any* content — your own UI just as much as
+// markdown-rendered HTML. The rhythm: strip the browser's block margins, then
+// give every block a *top* margin only when it isn't its parent's first child.
+// Content sits flush against its container's edges, and space appears solely
+// *between* siblings. These are intentionally low-specificity defaults — a
+// component or utility that sets its own margin (or an inline `mt:` shortcut)
+// always wins, so a class only ever changes what it actually names.
+const BLOCK = "p, ul, ol, dl, blockquote, pre, table, figure, hr, h1, h2, h3, h4, h5, h6";
+A.insertGlobalCss({
+    [`${BLOCK}`]: {
+        "&": "margin:0",
+        "&:not(:first-child)": "margin-top:$3",
+    },
+    // Headings: bold, tight, balanced. Big levels get slightly negative tracking,
+    // small levels become spaced "labels" — so adjacent levels stay distinct. The
+    // em-based top margin gives larger headings a little more room above.
+    "h1, h2, h3, h4, h5, h6": {
+        "&": "line-height:1.15 font-weight:700 text-wrap:balance",
+        "&:not(:first-child)": "margin-top:1.4em",
+    },
+    h1: "font-size:2em font-weight:800 letter-spacing:-0.022em",
+    h2: "font-size:1.55em letter-spacing:-0.018em",
+    h3: "font-size:1.3em letter-spacing:-0.011em",
+    h4: "font-size:1.1em",
+    h5: "font-size:0.95em letter-spacing:0.005em",
+    h6: "font-size:0.8em fg:$s-fg-muted text-transform:uppercase letter-spacing:0.07em",
+    // Lists: markers, a sensible indent, gently spaced items, tight nesting.
+    "ul, ol": {
+        "&": "padding-left:1.5em",
+        "> li:not(:first-child), li > &:not(:first-child)": "margin-top:$1",
+    },
+    // Blockquote, tables, definition lists, figure captions.
+    blockquote: "border-left: 3px solid $s-border; padding-left: $3; fg: $s-fg-muted",
+    table: "border-collapse:collapse",
+    "th, td": "text-align:left padding: $1 $2; border-bottom: 1px solid $s-border; vertical-align:top",
+    th: "font-weight:600",
+    "thead th": "border-bottom: 2px solid $s-border-strong;",
+    dt: "font-weight:600",
+    dd: "margin-left: 1.5em",
+    figcaption: "fg:$s-fg-muted font-size:0.9em margin-top:$1 text-align:center",
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staffa",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "An opinionated component library for the Aberdeen reactive UI library.",
   "license": "ISC",
   "author": "",
@@ -12,6 +12,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./icons.js": {
+      "types": "./dist/icons.d.ts",
+      "default": "./dist/icons.js"
+    },
     "./all.js": "./dist/staffa.esm.js"
   },
   "files": [
@@ -19,17 +23,20 @@
     "src"
   ],
   "scripts": {
-    "build": "tsc && tsc -p demo && esbuild src/index.ts --bundle --external:aberdeen --minify --format=esm --outfile=dist/staffa.esm.js",
+    "build:icons": "node scripts/generate-icons.mjs",
+    "build": "npm run build:icons && tsc && tsc -p demo && esbuild src/index.ts --bundle --external:aberdeen --minify --format=esm --outfile=dist/staffa.esm.js",
     "typecheck": "tsc --noEmit && tsc -p demo --noEmit",
-    "smoke": "tsc && node smoke.mjs"
+    "smoke": "tsc && node smoke.mjs",
+    "prepublish": "npm run build"
   },
   "peerDependencies": {
-    "aberdeen": "^1.15.0"
+    "aberdeen": "^1.17.1"
   },
   "devDependencies": {
-    "aberdeen": "^1.15.0",
+    "aberdeen": "^1.17.1",
     "esbuild": "^0.28.0",
     "jsdom": "^29.1.1",
+    "lucide-static": "^1.17.0",
     "typescript": "^5.9.3"
   }
 }

package/src/components/autocomplete.ts

@@ -33,21 +33,22 @@ export interface AutocompleteOptions extends FieldOptions {
 }
 
 A.insertGlobalCss({
-	".S_ac": {
+	".s-ac": {
 		"&": "position:relative",
-		"> .S_control": "display:flex flex-wrap:wrap align-items:center gap:$1 bg:$sSurface fg:$sFg border: 1px solid $sBorder; r:$sRadius padding: 0.3em 0.4em; cursor:text; transition: border-color 0.15s, box-shadow 0.15s;",
-		"> .S_control:hover": "border-color:$sBorderStrong",
-		"> .S_control:focus-within": "border-color:$sPrimary box-shadow: 0 0 0 3px $sFocus;",
-		"&[aria-invalid=true] > .S_control": "border-color:$sDanger",
-		".S_chip": "display:inline-flex align-items:center gap:$1 font-size:0.85em bg:$sSurfaceHi border: 1px solid $sBorder; r:$sRadius padding: 0.1em 0.2em 0.1em 0.5em;",
-		".S_chip > button": "cursor:pointer border:0 background:transparent fg:$sFgMuted font-size:1.1em line-height:1 padding: 0 0.2em; r:4px",
-		".S_chip > button:hover": "fg:$sFg background:$sBorder",
+		"> .s-control": "display:flex flex-wrap:wrap align-items:center gap:$1 bg:$s-panel fg:$s-ink border: 1px solid $s-border; r:$s-radius padding: 0.3em 0.4em; cursor:text; transition: border-color 0.15s, box-shadow 0.15s;",
+		"> .s-control:hover": "border-color:$s-border-strong",
+		"> .s-control:focus-within": "border-color:$s-accent box-shadow: 0 0 0 3px $s-focus;",
+		"&[aria-invalid=true] > .s-control": "border-color:$s-danger",
+		".s-chip": "display:inline-flex align-items:center gap:$1 font-size:0.85em bg:$s-raised border: 1px solid $s-border; r:$s-radius padding: 0.1em 0.2em 0.1em 0.5em;",
+		".s-chip > button": "cursor:pointer border:0 background:transparent fg:$s-fg-muted font-size:1.1em line-height:1 padding: 0 0.2em; r:4px",
+		".s-chip > button:hover": "fg:$s-fg background:$s-border",
 		"input": "flex:1 min-width:6ch border:0 background:transparent color:inherit outline:none padding:0.25em",
-		"> .S_menu": "position:absolute top:100% left:0 right:0 z-index:20 margin-top:4px max-height:15rem overflow-y:auto list-style:none p:$1 margin-bottom:0 bg:$sSurface border: 1px solid $sBorder; r:$sRadius box-shadow:$sShadow",
-		".S_option": "padding: 0.45em 0.6em; r:6px cursor:pointer",
-		".S_option[aria-selected=true]": "background:$sSurfaceHi",
-		".S_add": "fg:$sPrimary font-style:italic",
-		".S_empty": "padding: 0.45em 0.6em; fg:$sFgMuted",
+		"> .s-menu": "position:absolute top:100% left:0 right:0 z-index:20 margin-top:4px max-height:15rem overflow-y:auto list-style:none p:$1 margin-bottom:0 bg:$s-panel border: 1px solid $s-border; r:$s-radius box-shadow:$s-shadow",
+		"> .s-menu li": "margin:0",
+		".s-option": "padding: 0.45em 0.6em; r:6px cursor:pointer transition: background 0.1s;",
+		".s-option[aria-selected=true]": "background: color-mix(in srgb, $s-fg 10%, transparent);",
+		".s-add": "fg:$s-accent font-style:italic",
+		".s-empty": "padding: 0.45em 0.6em; fg:$s-fg-muted",
 	},
 });
 
@@ -123,19 +124,19 @@ export function autocomplete(opts: AutocompleteOptions): void {
 	};
 
 	drawField(opts, (id, isInvalid) => {
-		A("div.S_ac", opts.control, () => {
+		A("div.s-ac", opts.inputAttrs, () => {
 			A(() => A("aria-invalid=", isInvalid() ? "true" : "false"));
 
 			let inputEl: HTMLInputElement | undefined;
 
-			A("div.S_control", () => {
+			A("div.s-control", () => {
 				A("click=", () => inputEl?.focus());
 
 				// Chips for multi-select.
 				A(() => {
 					if (!opts.multi) return;
 					for (const value of selectedValues()) {
-						A("span.S_chip", () => {
+						A("span.s-chip", () => {
 							A("span #", A.peek(() => labelFor(value)));
 							A("button type=button aria-label=", `Remove ${value}`, () => {
 								A("#×");
@@ -183,9 +184,9 @@ export function autocomplete(opts: AutocompleteOptions): void {
 				const q = $st.query.trim();
 				const showAdd = opts.allowCustom !== false && q !== "" && !list.some((o) => o.label.toLowerCase() === q.toLowerCase());
 
-				A("ul.S_menu role=listbox", `id=${menuId}`, () => {
+				A("ul.s-menu role=listbox", `id=${menuId}`, () => {
 					list.forEach((option, i) => {
-						A("li.S_option role=option", `id=${menuId}-opt-${i}`, () => {
+						A("li.s-option role=option", `id=${menuId}-opt-${i}`, () => {
 							A(() => A("aria-selected=", $st.active === i ? "true" : "false"));
 							A("#", option.label);
 							A("mousedown=", (e: Event) => e.preventDefault());
@@ -196,14 +197,14 @@ export function autocomplete(opts: AutocompleteOptions): void {
 						});
 					});
 					if (showAdd) {
-						A("li.S_option.S_add role=option", () => {
+						A("li.s-option.s-add role=option", () => {
 							A("#", `Add "${q}"`);
 							A("mousedown=", (e: Event) => e.preventDefault());
 							A("click=", () => commit(q, inputEl));
 						});
 					}
 					if (list.length === 0 && !showAdd) {
-						A("li.S_empty #No matches");
+						A("li.s-empty #No matches");
 					}
 				});
 			});

package/src/components/box.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Content, type ContentOptions, type Slot, type Styling, drawSlot } from "../core.js";
+import { type Content, type ContentOptions, type Slot, type Attributes, drawSlot } from "../core.js";
 
 /** Options for {@link box}. */
 export interface BoxOptions extends ContentOptions {
@@ -7,18 +7,24 @@ export interface BoxOptions extends ContentOptions {
 	header?: Slot;
 	/** Footer content, drawn in a styled bar below the body. */
 	footer?: Slot;
+	/** Aberdeen attr/style string applied to the body (content-holding) element. */
+	contentAttrs?: Attributes;
 	/** Aberdeen attr/style string applied to the header bar. */
-	headerInner?: Styling;
+	headerAttrs?: Attributes;
 	/** Aberdeen attr/style string applied to the footer bar. */
-	footerInner?: Styling;
+	footerAttrs?: Attributes;
 }
 
+// The box itself is a `.panel` surface; its header/footer are `.raised`
+// surfaces (classes set on the elements in `box()` below). Colours and borders
+// come from the contextual tokens, so a box stays legible on whatever surface
+// it's nested in.
 A.insertGlobalCss({
-	".S_box": {
-		"&": "display:flex flex-direction:column bg:$sSurface border: 1px solid $sBorder; r:$sRadius overflow:hidden",
-		"> header": "display:flex align-items:center gap:$2 padding: $2 $3; bg:$sSurfaceHi border-bottom: 1px solid $sBorder; font-weight:600",
-		"> footer": "display:flex align-items:center gap:$2 padding: $2 $3; bg:$sSurfaceHi border-top: 1px solid $sBorder;",
-		// The body is the only plain <div> child; give it the default padding+gap.
+	".s-box": {
+		"&": "display:flex flex-direction:column border: 1px solid $s-border; r: $s-radius-lg; overflow:hidden box-shadow: $s-shadow;",
+		"&:not(:first-child)": "margin-top: $3",
+		"> header": "display:flex align-items:center gap:$2 padding: $2 $3; border-bottom: 1px solid $s-border; font-weight:600",
+		"> footer": "display:flex align-items:center gap:$2 padding: $2 $3; border-top: 1px solid $s-border;",
 		"> div": "p:$3 gap:$3",
 	},
 });
@@ -28,14 +34,14 @@ A.insertGlobalCss({
  * header and footer, and a padded body that holds {@link ContentOptions.content}.
  *
  * The body gets default `padding` and matching `gap`; add `display:flex` via
- * {@link ContentOptions.inner | inner} if you want its children laid out as a
- * flex container.
+ * {@link BoxOptions.contentAttrs | contentAttrs} if you want its children laid
+ * out as a flex container.
  *
  * Shortcut: pass a function to use it directly as the body content.
  *
  * @example
  * ```ts
- * S.box({ header: "Profile", inner: "display:flex flex-direction:column", content: () => {
+ * S.box({ header: "Profile", contentAttrs: "display:flex flex-direction:column", content: () => {
  *   S.textline({ label: "Name", bind: A.ref($user, "name") });
  * }});
  * S.box(() => A("p#Just some content"));   // shorthand
@@ -44,19 +50,19 @@ A.insertGlobalCss({
 export function box(opts: BoxOptions | Content = {}): void {
 	const o: BoxOptions = typeof opts === "function" ? { content: opts } : opts;
 
-	A("section.S_box", o.root, () => {
+	A("section.s-box.s-s.panel", o.attrs, () => {
 		// Header and footer get their own scopes so toggling them doesn't recreate
 		// the body (which may hold focused inputs / lots of content).
 		A(() => {
-			if (o.header != null) A("header", o.headerInner, () => drawSlot(o.header));
+			if (o.header != null) A("header.s-s.raised", o.headerAttrs, () => drawSlot(o.header));
 		});
 
-		A("div", o.inner, () => {
+		A("div", o.contentAttrs, () => {
 			if (o.content) o.content();
 		});
 
 		A(() => {
-			if (o.footer != null) A("footer", o.footerInner, () => drawSlot(o.footer));
+			if (o.footer != null) A("footer.s-s.raised", o.footerAttrs, () => drawSlot(o.footer));
 		});
 	});
 }