staffa 0.1.0 → 0.2.1

package/dist/theme.d.ts

@@ -1,87 +1,21 @@
 /**
- * Theming and global base styles for Skye.
- *
- * Skye is themed entirely through CSS custom properties (via Aberdeen's
- * {@link A.cssVars}). Components reference these with `var(--sPrimary)` etc., so
- * changing a single variable restyles the whole app — at runtime, reactively.
- *
- * Unlike typical Aberdeen apps (which use component-local `insertCss`), Skye uses
- * **global** CSS (`insertGlobalCss`) with class names prefixed `S_`. This is a
- * deliberate trade-off: it lets application authors override any Skye style from
- * their own stylesheet without fighting scoped class names.
- */
-/**
- * The set of CSS custom properties Skye understands. All are plain CSS color /
- * length strings. Override any subset by mutating {@link darkTheme} /
- * {@link lightTheme}.
- */
-export interface Theme {
-    /** Page background — the darkest surface. */
-    sBg: string;
-    /** Default surface for cards, inputs, menus. */
-    sSurface: string;
-    /** Raised surface for headers, footers, chips, hover states. */
-    sSurfaceHi: string;
-    /** Primary foreground / text color. */
-    sFg: string;
-    /** Muted text (help text, subtitles). */
-    sFgMuted: string;
-    /** Faint text (placeholders, disabled). */
-    sFgFaint: string;
-    /** Default border color. */
-    sBorder: string;
-    /** Stronger border / neutral control color. */
-    sBorderStrong: string;
-    /** Brand / accent color. */
-    sPrimary: string;
-    /** Brand color, hover/brighter. */
-    sPrimaryHover: string;
-    /** Text drawn on top of {@link Theme.sPrimary}. */
-    sPrimaryFg: string;
-    /** Destructive / error color. */
-    sDanger: string;
-    /** Positive / success color. */
-    sSuccess: string;
-    /** Caution color. */
-    sWarning: string;
-    /** Focus-ring color (usually a translucent primary). */
-    sFocus: string;
-    /** Default corner radius. */
-    sRadius: string;
-    /** Larger corner radius (e.g. the {@link import("./components/main").main} sheet). */
-    sRadiusLg: string;
-    /** Elevation shadow for menus, dialogs, the framed content sheet. */
-    sShadow: string;
-}
-/**
- * The default dark Skye theme: modern and intentionally a little vivid so it
- * stands out of the box.
- *
- * 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 declare const darkTheme: Theme;
-/**
- * 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.
- *
- * Like {@link darkTheme}, a live proxy: mutate it to retheme light mode.
+ * The named accent roles for interactive elements (buttons, tabs, badges, …).
+ * Each maps to a `.s-s.<role>` class that sets `--s-a` (ink) and `--s-b` (fill).
  */
-export declare const lightTheme: Theme;
+export type SurfaceRole = "primary" | "neutral" | "danger" | "success" | "warning";
+/** How a surface's two colours are rendered. `filled` is the default. */
+export type Variant = "filled" | "tonal" | "outlined";
 /**
  * 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 declare function setDarkMode(value: boolean | undefined): void;
 /**
  * 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 declare function getDarkMode(allowAuto?: boolean): boolean | undefined;

package/dist/theme.js

@@ -1,65 +1,85 @@
 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`,
+ * `.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-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-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 +97,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 +115,117 @@ 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-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:10px --s-radius-lg:16px --s-shadow: 0 8px 30px rgba(0,0,0,0.45);",
+            // 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-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:#ffffff --s-focus:rgba(108,92,231,0.35) " +
+                "--s-radius:10px --s-radius-lg:16px --s-shadow: 0 6px 24px rgba(20,24,40,0.12);",
+            ":root, .s-s.base, .s-s.panel, .s-s.raised, .s-s.neutral": "--s-link:#2563eb",
+        });
+    }
+});
+// ---------------------------------------------------------------------------
+// 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({
+    // Level/role modifier → anchors. Levels (neutral elevations) use the shared
+    // ink; accent roles use the on-accent ink over their named fill.
+    ":root, .s-s.base": "--s-a:$s-ink --s-b:$s-page",
+    ".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.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",
+    // 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%); " +
+        "background:$s-bg color:$s-fg",
+    // 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;",
+    // 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.danger, .s-s.success, .s-s.warning": "--s-accent:$s-fg --s-link:$s-fg",
 });
-// 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.
+// 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. It
+// does NOT strip margins from headings/paragraphs/lists.
 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",
+    "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; margin: $3 0;",
+    "::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",
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staffa",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "An opinionated component library for the Aberdeen reactive UI library.",
   "license": "ISC",
   "author": "",
@@ -21,7 +21,8 @@
   "scripts": {
     "build": "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"

package/src/components/autocomplete.ts

@@ -33,21 +33,21 @@ 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-option": "padding: 0.45em 0.6em; r:6px cursor:pointer",
+		".s-option[aria-selected=true]": "background:$s-raised",
+		".s-add": "fg:$s-accent font-style:italic",
+		".s-empty": "padding: 0.45em 0.6em; fg:$s-fg-muted",
 	},
 });
 
@@ -123,19 +123,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 +183,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 +196,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,17 +7,23 @@ 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;",
+	".s-box": {
+		"&": "display:flex flex-direction:column border: 1px solid $s-border; r: $s-radius; overflow:hidden",
+		"> 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;",
 		// The body is the only plain <div> child; give it the default padding+gap.
 		"> 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));
 		});
 	});
 }