staffa 0.1.0 → 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,117 +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 are shared
-across all components:
+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                                                              |
-| ---------- | ------------------------ | ------------------------------------------------------------------- |
-| `root`     | every component          | Aberdeen attr/style string for the outermost element                |
-| `content`  | container components     | a `() => void` draw function for the children                       |
-| `inner`    | container components     | attr/style string for the element holding the children             |
-| `control`  | form fields              | attr/style string for the actual input element                      |
-| `label` / `help` / `error` / `disabled` / `required` / `name` | form fields | standard field chrome |
+```ts
+S.button({ text: "Save", disabled: false });
+S.box({ header: "Settings", content: () => { ... } });
+```
 
-`root`/`inner`/`control` are [Aberdeen style strings](https://aberdeenjs.org),
-e.g. `"display:flex gap:$3 .my-class"`. (Write `display:flex`, not bare `flex`.)
+### Options objects are typed and can be reactive
 
-### Layout & containers
+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.
 
-- **`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.
+```ts
+const $btn = A.proxy({ text: "Save", disabled: false });
+S.button($btn);
+// ...later:
+$btn.disabled = true;  // button updates instantly
+```
 
-### Form fields
+### Rich text slots
 
-- **`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`.
+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.
 
-### Dialogs
+```ts
+S.button({ text: "Save **now**" });
+S.box({ header: "See the [docs](/docs)", content: () => { ... } });
+```
 
-- **`S.modal(opts)`** — dialog rendered into `document.body`, with a dimming
-  backdrop and fade transition. Lifecycle is tied to the calling reactive scope
-  (the modal disappears when that scope is cleaned up). The `content` callback
-  receives a `close()` function. Nested modals stack correctly.
+### Surfaces
 
-### Actions
+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:
+
+- **level**: `.base`, `.panel`, `.raised`
+- **role**: `.primary`, `.secondary`, `.gradient`, `.neutral`, `.danger`, `.success`, `.warning`
+- **variant**: `.filled`, `.tonal`, `.outlined`
 
-- **`S.button(opts | "text")`** — `variant` is `filled` | `tonal` | `outlined`;
-  `color` is `primary` | `neutral` | `danger` | `success`; plus `size`,
-  `disabled`, `icon`, and `href` (renders an `<a role=button>`).
-- **`S.buttonGroup(opts)`** — groups buttons, `attached` (segmented) or `spaced`.
+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
 ```
 
-## Theming
+*Hint:* A `buttonChooser` is probably the right component for a color scheme selector.
+
+### CSS reset
+
+Staffa includes a lightweight CSS reset that makes bare semantic HTML look a bit better but unsurprising without additional styling. 
 
-Staffa is themed via CSS custom properties. `S.darkTheme` and `S.lightTheme` are
-live Aberdeen proxies — mutate them to restyle either scheme; changes flow into
-the CSS variables immediately:
+### 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.darkTheme.sPrimary = "#28c4a0";
-S.darkTheme.sPrimaryFg = "#08110d";
-S.lightTheme.sRadius = "6px";
+A.cssVars["s-primary"] = "#fdda58";
+A.cssVars["s-secondary"] = "#cc5624";
+A.cssVars["s-danger"] = "#ee4422";
+A.cssVars["s-radius"] = "4px";
 ```
 
-See the `Theme` type for all variables (`sBg`, `sSurface`, `sFg`, `sBorder`,
-`sPrimary`, `sDanger`, `sSuccess`, `sRadius`, `sShadow`, ...).
+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:
+
+```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"});
+
+S.button({
+  text: "You'll want to click me",
+  attrs: ".my-surface",
+  click: () => S.alert("Good work!", {attrs: ".my-surface"})
+});
+```
 
-### Dark / light mode
+Note that when changing CSS like this, things *may* break if you upgrade Staffa. The recommended update strategy is therefore: don't!
 
-Staffa follows the OS preference by default. Override it at runtime:
+If you want to make changes that are dependent upon the current light/dark mode setting, rely on Aberdeen reactivity:
 
 ```ts
-S.setDarkMode(true);      // force dark
-S.setDarkMode(false);     // force light
-S.setDarkMode(undefined); // follow OS again
+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"});
+  }
+});
 ```
 
-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).
+## 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.
 
-All Staffa styles are **global** and use `S_`-prefixed class names, so you can
-also override anything from your own stylesheet.
+### Layout & containers
+
+- **`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.
+
+### 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
+
+- **`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.
+
+### 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">
@@ -170,17 +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.
+
+## Extending Staffa
+
+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.
+
+### Design principles
 
-## Demo & development
+1. **Components are functions**. They take one typed options object, emit Aberdeen DOM, and *usually* return nothing.
+
+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.
+
+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/
-npx serve .        # then open /demo/ in a browser
+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
 ```
-
-`npm run smoke` builds and renders every component in jsdom as a quick check.
-
-Contributing or extending Staffa? See [`AGENTS.md`](./AGENTS.md) for the design
-philosophy and the add-a-component checklist.

package/dist/components/autocomplete.js

@@ -2,21 +2,22 @@ import A from "aberdeen";
 import { uniqueId } from "../core.js";
 import { drawField } from "./field.js";
 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",
     },
 });
 function normOption(o) {
@@ -93,17 +94,17 @@ export function autocomplete(opts) {
         opts.bind.value = arr.filter((v) => v !== value);
     };
     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;
-            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("#×");
@@ -152,9 +153,9 @@ export function autocomplete(opts) {
                 const list = filtered();
                 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) => e.preventDefault());
@@ -165,14 +166,14 @@ export function autocomplete(opts) {
                         });
                     });
                     if (showAdd) {
-                        A("li.S_option.S_add role=option", () => {
+                        A("li.s-option.s-add role=option", () => {
                             A("#", `Add "${q}"`);
                             A("mousedown=", (e) => 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/dist/components/box.d.ts

@@ -1,28 +1,30 @@
-import { type Content, type ContentOptions, type Slot, type Styling } from "../core.js";
+import { type Content, type ContentOptions, type Slot, type Attributes } from "../core.js";
 /** Options for {@link box}. */
 export interface BoxOptions extends ContentOptions {
     /** Header content, drawn in a styled bar above the body. */
     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;
 }
 /**
  * A surface container — the workhorse layout primitive. Has an optional styled
  * 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

package/dist/components/box.js

@@ -1,11 +1,15 @@
 import A from "aberdeen";
 import { drawSlot } from "../core.js";
+// 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",
     },
 });
@@ -14,14 +18,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
@@ -29,20 +33,20 @@ A.insertGlobalCss({
  */
 export function box(opts = {}) {
     const o = 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));
+                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));
+                A("footer.s-s.raised", o.footerAttrs, () => drawSlot(o.footer));
         });
     });
 }

package/dist/components/button.d.ts

@@ -1,29 +1,6 @@
-import { type BaseOptions, type Content, type Slot, type Styling } from "../core.js";
-/**
- * Visual weight of a button.
- * - `filled`: solid background, highest emphasis.
- * - `tonal`: soft tinted background, medium emphasis.
- * - `outlined`: bordered, transparent background, lowest emphasis.
- *
- * Every variant carries at least a visible border, per Skye's "everything is
- * legible at a glance" principle.
- */
-export type ButtonVariant = "filled" | "tonal" | "outlined";
-/**
- * Color of a button.
- *
- * The four named **semantic roles** map to theme colours and are offered as
- * autocomplete suggestions. You may also pass *any* CSS colour the browser
- * understands and it becomes the button's accent directly: a literal like
- * `"#ef6b00"` / `"rgb(255 107 0)"`, or a theme custom-property reference like
- * `"$sWarning"` (Aberdeen's `$name` shorthand for `var(--name)`).
- *
- * The `(string & {})` member is what keeps the literal suggestions visible while
- * still allowing arbitrary strings — TypeScript only widens to `string` lazily.
- */
-export type ButtonColor = "primary" | "neutral" | "danger" | "success" | (string & {});
+import { type Content, type Slot, type Attributes } from "../core.js";
 /** Options for {@link button}. */
-export interface ButtonOptions extends BaseOptions {
+export interface ButtonOptions {
     /** Button label text. */
     text?: string;
     /** Custom content (overrides {@link ButtonOptions.text | text}). */
@@ -32,12 +9,6 @@ export interface ButtonOptions extends BaseOptions {
     icon?: Slot;
     /** Click handler. */
     click?: (event: Event) => void;
-    /** Visual weight. Defaults to `"filled"`. */
-    variant?: ButtonVariant;
-    /** Color role. Defaults to `"primary"`. */
-    color?: ButtonColor;
-    /** Size. Defaults to `"md"`. */
-    size?: "sm" | "md" | "lg";
     /** Disables the button. */
     disabled?: boolean;
     /** Native button behaviour. Defaults to `"button"`. */
@@ -46,20 +17,35 @@ export interface ButtonOptions extends BaseOptions {
     href?: string;
     /** Accessible label, when the button has only an icon. */
     ariaLabel?: string;
-    /** Aberdeen attr/style string applied to the button element. */
-    inner?: Styling;
+    /**
+     * 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;
 }
 /**
  * A button. Always carries at least a visible border so its affordance is
- * obvious at a glance, regardless of {@link ButtonVariant | variant}.
+ * obvious at a glance.
  *
  * 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 });
- * S.button({ text: "Delete", color: "danger", variant: "outlined", click: del });
+ * S.button({ text: "Delete", attrs: ".danger .outlined", click: del });
  * S.button("Cancel");                        // shorthand for { text: "Cancel" }
  * S.button({ href: "/docs", text: "Docs" }); // renders an <a role=button>
  * ```