staffa 0.2.1 → 0.3.0

package/README.md

@@ -1,17 +1,12 @@
 # Staffa
 
-A small, opinionated component library for the
-[Aberdeen](https://aberdeenjs.org) reactive UI library.
-
-Staffa components are **plain functions** that draw DOM through Aberdeen — no JSX,
-no web components, no build step required. You import a single `S` object and
-call its methods:
+A small, opinionated TypeScript component library for the [Aberdeen](https://aberdeenjs.org) reactive UI library.
 
 ```ts
 import A from "aberdeen";
 import S from "staffa";
 
-const $user = A.proxy({ name: "", email: "", subscribe: false });
+const $user = A.proxy({ name: "", email: "" });
 
 A.mount(document.body, () => {
   S.main({
@@ -19,11 +14,10 @@ A.mount(document.body, () => {
     maxWidth: "40rem",
     content: () => {
       S.form({
-        submit: () => console.log("submit", A.unproxy($user)),
+        submit: () => console.log(A.unproxy($user)),
         content: () => {
           S.textline({ label: "Name", required: true, bind: A.ref($user, "name") });
           S.textline({ label: "Email", type: "email", bind: A.ref($user, "email") });
-          S.checkbox({ label: "Email me updates", bind: A.ref($user, "subscribe") });
         },
         actions: () => S.button({ text: "Create account", type: "submit" }),
       });
@@ -32,9 +26,7 @@ A.mount(document.body, () => {
 });
 ```
 
-Staffa ships a **dark theme** by default and looks reasonable out of the box.
-
-> **Pre-1.0 notice:** Staffa's API is likely to change fairly often before stabilising as 1.0. That shouldn't stop you from using it — the library is small enough that any breaking changes are easy to adapt to yourself.
+Staffa is made to look decent out of the box, but easily customizable at runtime.
 
 ## Install
 
@@ -42,150 +34,155 @@ Staffa ships a **dark theme** by default and looks reasonable out of the box.
 npm install staffa aberdeen
 ```
 
-Aberdeen is a **peer dependency** — Staffa builds on your app's single copy of
-Aberdeen rather than bundling its own (two copies of Aberdeen would mean two
-independent reactivity systems). So install `aberdeen` alongside `staffa`.
+Aberdeen is a peer dependency. Staffa is published as ESM with TypeScript types.
 
-Staffa is published as ESM with TypeScript types.
+## How it works
 
-## Components
+### Components are functions
 
-Every component takes a single typed options object. Common options follow a
-consistent naming convention:
+Every component takes a single typed options object and draws DOM via Aberdeen. No classes, no web components. The `S` object collects all component functions:
 
-| Option         | On                   | Meaning                                                   |
-| -------------- | -------------------- | --------------------------------------------------------- |
-| `attrs`        | most components      | attr/style string for the outermost element               |
-| `content`      | container components | a `() => void` draw function for the children             |
-| `contentAttrs` | container components | attr/style string for the element holding the children    |
-| `inputAttrs`   | form fields          | attr/style string for the actual input/control element    |
-| `<region>Attrs`| where relevant       | sub-region styling, e.g. `headerAttrs`, `footerAttrs`     |
-| `label` / `help` / `error` / `disabled` / `required` / `name` | form fields | standard field chrome |
+```ts
+S.button({ text: "Save", disabled: false });
+S.box({ header: "Settings", content: () => { ... } });
+```
 
-These are all [Aberdeen attr/style strings](https://aberdeenjs.org), e.g.
-`"display:flex gap:$3 .my-class"`. (Write `display:flex`, not bare `flex`.) As
-`attrs` is applied last, it can also override a component's default surface
-classes — pass `".danger"` or `".neutral .outlined"` to recolour a button, etc.
+### Options objects are typed and can be reactive
 
-Anywhere a component shows a small piece of text (a `label`, `header`, a button
-`text`, a dialog body, ...), you can pass either a **string** — rendered as
-[rich text](#rich-text) — or a `() => void` draw function for custom markup.
+All components get their options in a typed object. The object may be an Aberdeen proxy, if you want to update the component in-place.
 
-### Layout & containers
+```ts
+const $btn = A.proxy({ text: "Save", disabled: false });
+S.button($btn);
+// ...later:
+$btn.disabled = true;  // button updates instantly
+```
 
-- **`S.main(opts)`** — app shell: sticky top bar (`icon`, `title`, `subtitle`,
-  `menu`), a scrollable content area, and a `footer`. Set `maxWidth` to center
-  the content as a shadowed "sheet".
-- **`S.box(opts | content)`** — a surface with optional `header`/`footer` and a
-  padded body. Pass a function as a shorthand for `content`.
-- **`S.tabs(opts)`** — a `tablist` + live panel, with full keyboard navigation.
-- **`S.form(opts | content)`** — opinionated `<form>` that aligns fields in a
-  column (or a responsive `grid`) and provides an `actions` bar. Prevents the
-  default page reload.
+### Rich text slots
 
-### Form fields
+Anywhere a component takes content, a `label`, `header`, button `text`, dialog body, etc, you can pass either a string or a `() => void` draw function. Strings render as **rich text**: `*italic*`, `**bold**`, `` `code` ``, `[link](/path)`. All text is safely escaped.
 
-- **`S.textline(opts)`** — single-line `<input>` (`text`, `password`, `email`,
-  `number`, `tel`, `url`, `search`, dates, ...).
-- **`S.textarea(opts)`** — multi-line input.
-- **`S.checkbox(opts)`** — labelled checkbox.
-- **`S.select(opts)`** — single-select dropdown backed by a native `<select>`.
-  The control is styled; the OS renders the drop-down list.
-- **`S.autocomplete(opts)`** — a type-ahead combobox; supports `multi` (chips),
-  `allowCustom` (free text), `required`, and dynamic `options`.
+```ts
+S.button({ text: "Save **now**" });
+S.box({ header: "See the [docs](/docs)", content: () => { ... } });
+```
 
-### Dialogs
+### Surfaces
 
-- **`S.dialog(opts)`** — dialog rendered into `document.body`, with a dimming
-  backdrop and fade transition. Lifecycle is tied to the calling reactive scope
-  (the dialog disappears when that scope is cleaned up). The `content` slot's
-  draw function receives a `close()` function. Nested dialogs stack correctly.
-  `S.alert` / `S.confirm` / `S.prompt` are promise-returning shortcuts.
+Staffa builds on **surfaces**: elements marked with `.s-s` that have their own background and derived text/border tokens. Add modifier classes to colour them:
 
-### Actions
+- **level**: `.base`, `.panel`, `.raised`
+- **role**: `.primary`, `.secondary`, `.gradient`, `.neutral`, `.danger`, `.success`, `.warning`
+- **variant**: `.filled`, `.tonal`, `.outlined`
 
-- **`S.button(opts | "text")`** — a button surface; restyle it via `attrs`
-  (e.g. `".danger"`, `".neutral .outlined"`), plus `size`, `disabled`, `icon`,
-  and `href` (renders an `<a role=button>`). Defaults to a filled `.primary`.
-- **`S.buttonGroup(opts)`** — groups buttons, `attached` (segmented) or `spaced`.
-- **`S.buttonChooser(opts)`** — single-select segmented control bound to a value.
+Components are built from these (`S.button` is a `.s-s.primary.filled`, `S.box` a `.s-s.panel`, etc.). Because component options include an optional `attrs` string, which has Aberdeen `A()` string semantics, you can easily override it:
 
-Two-way binding uses Aberdeen observables: pass `bind: A.ref($obj, "key")` (or
-any `{ value }` proxy) to fields.
+```ts
+S.button({ text: "Delete", attrs: ".danger" });
+S.box({ attrs: ".raised.outlined", content: () => { ... } });
+```
 
-## Reactive options
+Inside any surface, CSS variables are defined for suitable foreground colors (`$s-fg`, `$s-bg`, `$s-fg-muted`, `$s-border`, `$s-accent`, ...), with `color` defaulting to `$s-fg`. By using these, components has access to various foreground colors that will look regardless of the surface it is drawing on.
 
-An options object — or any part of it — **may be an Aberdeen proxy**. Mutate it
-later and the affected part of the component re-renders in place:
+### Dark and light modes
+
+Dark/light mode is detected from OS preference by default. If you want to override this (based on user preferences), use:
 
 ```ts
-const $opts = A.proxy({ text: "Save", disabled: false });
-S.button($opts);
-// ...later:
-$opts.disabled = true;   // the button updates, nothing else re-renders
+S.setDarkMode(true);       // force dark
+S.setDarkMode(false);      // force light
+S.setDarkMode(undefined);  // follow OS
 ```
 
-## Rich text
+*Hint:* A `buttonChooser` is probably the right component for a color scheme selector.
 
-Wherever a component takes a text **slot** — a `label`, a `header`/`footer`, a
-button's `text`, a dialog body, ... — a plain string is rendered as **rich
-text**: a small markdown-like syntax with `*italic*`, `**bold**`, `` `code` ``
-and `[links](/path)`. All text is safely escaped. For anything more, pass a
-draw function instead of a string.
+### CSS reset
+
+Staffa includes a lightweight CSS reset that makes bare semantic HTML look a bit better but unsurprising without additional styling. 
+
+### Theming
+
+The first step in theming is just setting some CSS variables, most commonly the primary and secondary color. This can be done through CSS directly, or using Aberdeen:
 
 ```ts
-S.button({ text: "Save **now**" });
-S.box({ header: "See the [docs](/docs)", content: () => { ... } });
+A.cssVars["s-primary"] = "#fdda58";
+A.cssVars["s-secondary"] = "#cc5624";
+A.cssVars["s-danger"] = "#ee4422";
+A.cssVars["s-radius"] = "4px";
 ```
 
-## Surfaces & theming
+See `src/theme.ts` for what other CSS variables are being used.
+
+If you need further customization, just add some CSS to override the default styling. For instance, to add your own surface type:
 
-Staffa is built on **surfaces**. A surface is any element marked `.s-s`: it has
-its own background and a legible set of text/border tokens derived from it. Add
-modifier classes to colour it:
+```ts
+// In filled mode, 's-a' is the foreground and 's-b' is the background. "outlined" and "tonal" use the colors in different ways.
+A.insertGlobalCss({".s-s.my-surface": "--s-a:white --s-b:#ef6b00"});
 
-- **level**: `.base` (page), `.panel` (card), `.raised` (chrome)
-- **role**: `.primary`, `.neutral`, `.danger`, `.success`, `.warning`
-- **variant**: `.filled` (default), `.tonal`, `.outlined`
+S.button({
+  text: "You'll want to click me",
+  attrs: ".my-surface",
+  click: () => S.alert("Good work!", {attrs: ".my-surface"})
+});
+```
 
-Components are built from these (`S.button` is a `.s-s.primary`, `S.box` a
-`.s-s.panel`, ...), and because `attrs` is applied last you can override the look
-from the outside — `S.button({ attrs: ".danger .outlined" })`.
+Note that when changing CSS like this, things *may* break if you upgrade Staffa. The recommended update strategy is therefore: don't!
 
-Inside any surface, widgets read its tokens (`$s-fg`, `$s-bg`, `$s-fg-muted`,
-`$s-border`, `$s-accent`, `$s-link`, ...) so they adapt automatically to wherever
-they're nested. Colours all come from a small palette set on `:root` per mode —
-re-skin by overriding those custom properties:
+If you want to make changes that are dependent upon the current light/dark mode setting, rely on Aberdeen reactivity:
 
 ```ts
-A(() => A.insertGlobalCss({ ":root": S.getDarkMode() ? "--s-primary:#28c4a0" : "--s-primary:#1f9d6b" }));
-A.insertGlobalCss({ ".s-s.panel": "--s-b:#efe9dd" }); // restyle a level/role
+A(() => {
+  if (S.getDarkMode()) {
+    A.cssVars["s-primary"] = "#aa9944";
+    A.insertGlobalCss({".s-s.my-surface": "--s-a:white --s-b:#444444"});
+  } else {
+    A.cssVars["s-primary"] = "#fdda58";
+    A.insertGlobalCss({".s-s.my-surface": "--s-a:black --s-b:#cccccc"});
+  }
+});
 ```
 
-See `src/theme.ts` for the full token list and the palette.
+## Components
+
+Components share naming conventions for options: `attrs` (outermost element), `contentAttrs` (children-holding element), `inputAttrs` (form control element), and `<region>Attrs` (sub-regions like `headerAttrs`/`footerAttrs`). Form components consistently support `label`, `help`, `error`, `disabled`, `required`, `name` through the `drawField()` helper.
 
-### Dark / light mode
+### Layout & containers
 
-Staffa follows the OS preference by default. Override it at runtime:
+- **`S.main(opts)`**: app shell, a sticky header with `icon`, `title`, `subtitle`, `menu`; scrollable content area; footer. Set `maxWidth` to center the content.
+- **`S.box(opts | content)`**: surface with optional `header`/`footer` and padded body. Pass a function for shorthand `{ content }`.
+- **`S.tabs(opts)`**: tablist with live panels and keyboard navigation.
+- **`S.form(opts | content)`**: form aligning fields in a column or responsive grid, with an `actions` bar. Prevents the default page reload.
 
-```ts
-S.setDarkMode(true);      // force dark
-S.setDarkMode(false);     // force light
-S.setDarkMode(undefined); // follow OS again
-```
+### Form fields
+
+- **`S.textline(opts)`**: single-line input (`text`, `password`, `email`, `number`, `tel`, `url`, `search`, dates, ...).
+- **`S.textarea(opts)`**: multi-line input.
+- **`S.checkbox(opts)`**: labelled checkbox.
+- **`S.select(opts)`**: single-select dropdown backed by native `<select>` (styled control, OS dropdown).
+- **`S.autocomplete(opts)`**: type-ahead combobox with `multi` (chips), `allowCustom` (free text), `required`, and dynamic `options`.
+
+### Dialogs
 
-The choice is persisted to `localStorage` and applied before the first paint
-(no flash). `S.getDarkMode()` returns the resolved boolean; pass `true` to get
-`undefined` when in "auto" mode (useful for a dark/light/auto control).
+- **`S.dialog(opts)`**: modal dialog with backdrop and fade transition. The `content` slot receives a `close()` function. Lifecycle is tied to the calling scope (disappears when cleaned up). Nesting stacks correctly.
+- **`S.alert(msg)` / `S.confirm(msg)` / `S.prompt(msg, initial?)`**: promise-returning shortcuts.
 
-All Staffa styles are **global** and use `s-`-prefixed class names, so you can
-also override anything from your own stylesheet.
+### Actions
+
+- **`S.button(opts | text)`**: button surface; restyle via `attrs` (e.g. `.danger`, `.outlined`), plus `size`, `disabled`, `icon`, `href` (renders `<a role=button>`). Defaults to filled `.primary`.
+- **`S.buttonGroup(opts)`**: groups buttons, `attached` (segmented) or `spaced`.
+- **`S.buttonChooser(opts)`**: single-select segmented control bound to a value.
+
+### Other
+
+- **`S.menuButton(opts)` / `S.showFloatingMenu(opts)`**: menu actions and floating menus, with keyboard navigation and submenus.
+- **`S.toast(opts)`**: transient notification at the bottom of the viewport.
+- **`S.addTooltip(el, opts)`**: tooltip on hover, attached to an existing element.
+
+Two-way binding uses Aberdeen proxies: pass `bind: A.ref($obj, "key")` to form fields.
 
 ## Browser (no bundler)
 
-`staffa/all.js` is a pre-built ESM bundle that includes all of Staffa but keeps
-Aberdeen external. Use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap)
-to tell the browser where to find both:
+`staffa/all.js` is a pre-built ESM bundle. Use an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap):
 
 ```html
 <script type="importmap">
@@ -203,22 +200,51 @@ to tell the browser where to find both:
 </script>
 ```
 
-Aberdeen stays external so if your app already loads it you won't get two
-independent copies.
+It includes all components, but not the icons.
 
-## Demo & development
+## Extending Staffa
 
-```sh
-npm run build      # compile TypeScript to dist/
-npx serve .        # then open /demo/ in a browser
-```
+Staffa is designed for extension. A component is simply a plain function taking a typed options object and drawing Aberdeen DOM. This section explains the philosophy so extensions follow the same patterns.
 
-`npm run smoke` builds and renders every component in jsdom as a quick check.
+### Design principles
 
-Contributing or extending Staffa? See [`AGENTS.md`](./AGENTS.md) for the design
-philosophy and the add-a-component checklist.
+1. **Components are functions**. They take one typed options object, emit Aberdeen DOM, and *usually* return nothing.
 
-## Changelog
+2. **Reuse option types.** Define options by extending `ContentOptions` (for layout components) or `FieldOptions` (for form controls) from `src/core.ts` and `src/components/field.ts`. Don't reinvent fields like `attrs`, `label`, `help`, etc.
 
-- 0.2.1 (2026-06-06): More flexible theming and component instance styling
-- 0.1.0 (2026-06-05): Initial release!
+3. **Reach for reactivity deliberately.** Pass option strings straight to `A` as positional args (the caller's scope). Only wrap a dedicated `A(() => ...)` scope where it matters: input elements (recreation loses focus), or large subtrees you don't want to redraw. Use `A.peek(() => ...)` when you need a value but must not subscribe.
+
+4. **Build on surfaces.** Mark elements `.s-s` and add level/role/variant modifiers. Inside them, use the contextual foreground color CSS variables (`$s-fg`, `$s-bg`, `$s-border`, ...) so components adapt to wherever they're nested. Hard-coding colors in components shouldn't be needed, but if you must, make sure you set *both* foreground and background.
+
+5. **No outer margins.** Components don't margin themselves; spacing is the parent's job. Content components set default `padding` on the content element; `contentAttrs` overrides it.
+
+6. **Make everything styleable.** Provide `attrs`, `contentAttrs`, `inputAttrs`, and `<region>Attrs` hooks so callers can customize. Apply `attrs` last so it can override component classes.
+
+7. **Use semantic HTML and ARIA.** Prefer native elements (`<button>`, `<label>`, `<form>`, `<section>`) and native behaviour. Add ARIA only where semantics fall short (e.g. tabs, combobox).
+
+8. **Use CSS.** Use `A.insertGlobalCss({...})` at module top level to provide (nested) CSS styling for your component. Give your top-level element the `s-<component-name>` class. Avoid inventing further classes; lean on nesting (`&` for the element, bare key for descendants) and element/structural selectors.  
+
+9. **Reuse form controls.** Use `drawField()` and call `applyControlAttrs()`.
+
+10. **Function over form.** Provide enough contrast. Stick to UI conventions to help users; buttons have a rounded border, links are underlined, text input background is white, etc.
+
+### Adding a component to Staffa
+
+The previous section is good advice for any project-specific custom, but should definitely be followed for any new components to be included in Staffa. In addition, you'd want to: 
+
+1. Create `src/components/<name>.ts`.
+2. Define `<Name>Options` extending `ContentOptions`, `FieldOptions`, or a plain interface. Add TSDoc on every option.
+3. Add a TSDoc `@example` on the function.
+4. Register in `src/index.ts` (the `S` object + type re-export).
+5. Extend `smoke.mjs` to render it. Run `npm run smoke` and `npm run build`.
+
+See `src/components/button.ts` and `src/components/dialog.ts` for examples.
+
+## Commands
+
+```sh
+npm run build      # compile TypeScript to dist/
+npm run typecheck  # check types
+npm run smoke      # render every component in jsdom
+npx http-server    # allows demo to be viewed at http://localhost:8080/demo
+```

package/dist/components/autocomplete.js

@@ -13,8 +13,9 @@ A.insertGlobalCss({
         ".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:$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-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",
     },

package/dist/components/box.js

@@ -6,10 +6,10 @@ import { drawSlot } from "../core.js";
 // it's nested in.
 A.insertGlobalCss({
     ".s-box": {
-        "&": "display:flex flex-direction:column border: 1px solid $s-border; r: $s-radius; overflow:hidden",
+        "&": "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;",
-        // The body is the only plain <div> child; give it the default padding+gap.
         "> div": "p:$3 gap:$3",
     },
 });

package/dist/components/button.d.ts

@@ -9,8 +9,6 @@ export interface ButtonOptions {
     icon?: Slot;
     /** Click handler. */
     click?: (event: Event) => void;
-    /** Size. Defaults to `"md"`. */
-    size?: "sm" | "md" | "lg";
     /** Disables the button. */
     disabled?: boolean;
     /** Native button behaviour. Defaults to `"button"`. */
@@ -23,6 +21,10 @@ export interface ButtonOptions {
      * Aberdeen attr/style string applied to the button. A button is a surface, so
      * pass surface modifier classes here to restyle it, e.g. `".danger"`,
      * `".neutral .outlined"`. Defaults to a filled `.primary` surface.
+     *
+     * Size is set here too, with `.small` or `.large` (medium is the default and
+     * needs no class), e.g. `".danger .small"`. A `.small`/`.large` parent (such
+     * as a {@link buttonGroup}) also sizes its buttons, so you can set it once.
      */
     attrs?: Attributes;
 }
@@ -33,6 +35,13 @@ export interface ButtonOptions {
  * Shortcut: pass a string to use it as the label, or a function for custom
  * content.
  *
+ * **Tip:** pair `href` with Aberdeen's `interceptLinks()` (called once at app
+ * startup) for SPA-style navigation without manual click handlers:
+ * ```ts
+ * interceptLinks(); // once at root
+ * S.button({ href: "/dashboard", text: "Dashboard" }); // navigates via router
+ * ```
+ *
  * @example
  * ```ts
  * S.button({ text: "Save", click: save });

package/dist/components/button.js

@@ -8,15 +8,34 @@ A.insertGlobalCss({
         "&": "display:inline-flex align-items:center justify-content:center gap:$2 " +
             "font-weight:600 line-height:1.2 white-space:nowrap cursor:pointer text-decoration:none " +
             "border: 1px solid $s-border; r: $s-radius; padding: 0.5em 1em; " +
-            "transition: background 0.15s, border-color 0.15s, filter 0.15s, box-shadow 0.15s;",
+            "transition: background 0.15s, border-color 0.15s, color 0.15s, filter 0.15s, box-shadow 0.15s, transform 0.08s;",
         "&:focus-visible": "outline:none box-shadow: 0 0 0 3px $s-focus;",
         "&:disabled, &[aria-disabled=true]": "opacity:0.45 cursor:not-allowed pointer-events:none filter:saturate(0.6)",
-        "&:hover": "filter: brightness(1.08)",
+        // Every button lifts a little toward the cursor on hover (the transform is in
+        // the transition list above). The filled `.gradient` CTA below layers a deeper
+        // shadow on top of the same lift, so it still reads as the signature action.
+        "&:hover": "filter: brightness(1.08); transform: translateY(-1px)",
         "&.tonal:hover, &.outlined:hover": "background: color-mix(in srgb, $s-b 26%, transparent);",
-        "&.s-sm": "padding: 0.32em 0.7em; font-size:0.85em",
-        "&.s-lg": "padding: 0.66em 1.3em; font-size:1.1em",
+        // A filled `.gradient` button (the default) is the app's signature call to
+        // action: a borderless gradient with a soft glow that lifts on hover. The
+        // gradient fill itself comes from the `.s-s.gradient` surface rule in theme.ts.
+        // No border: a filled gradient reads as one solid shape. Dropping the border
+        // (rather than making it transparent) also sidesteps a Chromium artifact where
+        // a gradient clipped to a transparent rounded border fringes the edge with the
+        // gradient's far colour.
+        "&.gradient:not(.tonal):not(.outlined)": "border:0 box-shadow: $s-glow;",
+        "&.gradient:not(.tonal):not(.outlined):hover": "filter: brightness(1.06); box-shadow: 0 10px 28px color-mix(in srgb, $s-primary 42%, transparent); transform: translateY(-1px);",
+        // Subtle press feedback.
+        "&:active:not(:disabled):not([aria-disabled=true])": "transform: translateY(1px)",
+        // Size: set on the button itself, or inherited from a `.small`/`.large`
+        // parent (e.g. a buttonGroup), so a container can size all its buttons at once.
+        "&.small, .small > &": "padding: 0.32em 0.7em; font-size:0.85em",
+        "&.large, .large > &": "padding: 0.66em 1.3em; font-size:1.1em",
     },
 });
+// Surface-role classes a caller may pass in `attrs`. When one is present we skip
+// the default `.gradient` base so the two roles don't stack on one element.
+const ROLE_CLASS = /\.(gradient|primary|secondary|neutral|danger|success|warning|base|panel|raised)(\.|\s|$)/;
 /**
  * A button. Always carries at least a visible border so its affordance is
  * obvious at a glance.
@@ -24,6 +43,13 @@ A.insertGlobalCss({
  * Shortcut: pass a string to use it as the label, or a function for custom
  * content.
  *
+ * **Tip:** pair `href` with Aberdeen's `interceptLinks()` (called once at app
+ * startup) for SPA-style navigation without manual click handlers:
+ * ```ts
+ * interceptLinks(); // once at root
+ * S.button({ href: "/dashboard", text: "Dashboard" }); // navigates via router
+ * ```
+ *
  * @example
  * ```ts
  * S.button({ text: "Save", click: save });
@@ -35,10 +61,12 @@ A.insertGlobalCss({
 export function button(opts = {}) {
     const o = typeof opts === "string" ? { text: opts } : typeof opts === "function" ? { content: opts } : opts;
     const tag = o.href != null ? "a" : "button";
-    const sizeCls = o.size != null ? `.s-${o.size}` : "";
-    // A filled `.primary` surface by default; `attrs` (applied after) can override
-    // the role/variant with e.g. `.danger`, `.neutral .outlined`.
-    A(`${tag}.s-btn.s-s.primary${sizeCls}`, o.attrs, () => {
+    // A filled `.gradient` surface by default — the signature CTA. If the caller's
+    // `attrs` already names a surface role we omit the default, so `.danger`,
+    // `.neutral .outlined`, etc. fully take over (rather than stacking two roles).
+    // A bare variant/size (`.outlined`, `.small`) keeps the gradient base.
+    const role = o.attrs && ROLE_CLASS.test(o.attrs) ? "" : ".gradient";
+    A(`${tag}.s-btn.s-s${role}`, o.attrs, () => {
         if (o.href != null) {
             A(`href=${o.href} role=button`);
             if (o.disabled)

package/dist/components/buttonChooser.d.ts

@@ -1,13 +1,14 @@
-import { type Bindable, type Attributes } from "../core.js";
+import { type Bindable, type Attributes, type Slot } from "../core.js";
 /** Options for {@link buttonChooser}. */
 export interface ButtonChooserOptions {
     /** Aberdeen attr/style string applied to the button group. */
     attrs?: Attributes;
     /**
      * The options to display, as a plain object mapping id → display label.
-     * Buttons appear in insertion order.
+     * Buttons appear in insertion order. A label may be a plain (rich-text)
+     * string, or a draw-function for custom content such as an icon.
      */
-    options: Record<string, string>;
+    options: Record<string, Slot>;
     /**
      * Two-way binding for the selected id, or `null` when nothing is selected.
      * Use an `A.proxy` or `A.ref`.
@@ -18,8 +19,6 @@ export interface ButtonChooserOptions {
      * `bind.value` to `null`. Useful for "none / auto" states.
      */
     allowDeselect?: boolean;
-    /** Button size. Defaults to `"md"`. */
-    size?: "sm" | "md" | "lg";
     /** Name attribute for the hidden `<input>`, enabling form submission. */
     name?: string;
 }

package/dist/components/buttonChooser.js

@@ -22,8 +22,8 @@ export function buttonChooser(opts) {
         buttonGroup({
             attrs: opts.attrs,
             buttons: Object.entries(opts.options).map(([id, label]) => ({
-                text: label,
-                size: opts.size,
+                text: typeof label === "string" ? label : undefined,
+                content: typeof label === "function" ? label : undefined,
                 attrs: selected === id ? ".primary" : ".neutral .outlined",
                 click: () => {
                     opts.bind.value = (opts.allowDeselect && selected === id) ? null : id;

package/dist/components/buttonGroup.js

@@ -6,8 +6,6 @@ A.insertGlobalCss({
         "&.s-spaced": "gap:$2 flex-wrap:wrap",
         "&.s-vertical": "flex-direction:column",
         "&.s-attached": "gap:0",
-        // When attached, collapse the shared border and square off the touching
-        // corners, keeping only the outer ends of the group rounded.
         "&.s-attached:not(.s-vertical) > .s-btn:not(:first-child)": "margin-left:-1px",
         "&.s-attached:not(.s-vertical) > .s-btn:not(:first-child):not(:last-child)": "r:0",
         "&.s-attached:not(.s-vertical) > .s-btn:first-child:not(:last-child)": "border-top-right-radius:0 border-bottom-right-radius:0",
@@ -16,7 +14,6 @@ A.insertGlobalCss({
         "&.s-attached.s-vertical > .s-btn:not(:first-child):not(:last-child)": "r:0",
         "&.s-attached.s-vertical > .s-btn:first-child:not(:last-child)": "border-bottom-left-radius:0 border-bottom-right-radius:0",
         "&.s-attached.s-vertical > .s-btn:last-child:not(:first-child)": "border-top-left-radius:0 border-top-right-radius:0",
-        // Keep the hovered/focused button's border above its neighbours.
         "&.s-attached > .s-btn:hover, &.s-attached > .s-btn:focus-visible": "z-index:1",
     },
 });

package/dist/components/field.js

@@ -5,12 +5,9 @@ A.insertGlobalCss({
         "&": "display:flex flex-direction:column gap:$1",
         "> label": "font-weight:600 font-size:0.9em fg:$s-fg user-select:none",
     },
-    // Shared, reusable bits (also used by checkbox & autocomplete).
     ".s-req": "fg:$s-danger margin-left:2px",
     ".s-help": "font-size:0.82em fg:$s-fg-muted",
     ".s-error": "font-size:0.82em fg:$s-danger",
-    // Shared look for text-like controls: a panel fill with a contextual border,
-    // the brand accent for focus, and the semantic danger ink when invalid.
     ".s-input": {
         "&": "w:100% bg:$s-panel fg:$s-ink border: 1px solid $s-border; r:$s-radius padding: 0.55em 0.7em; transition: border-color 0.15s, box-shadow 0.15s;",
         "&:hover:not(:disabled)": "border-color:$s-border-strong",