staffa 0.1.0 → 0.2.1

package/README.md

@@ -50,19 +50,26 @@ Staffa is published as ESM with TypeScript types.
 
 ## Components
 
-Every component takes a single typed options object. Common options are shared
-across all components:
-
-| 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                      |
+Every component takes a single typed options object. Common options follow a
+consistent naming convention:
+
+| 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 |
 
-`root`/`inner`/`control` are [Aberdeen style strings](https://aberdeenjs.org),
-e.g. `"display:flex gap:$3 .my-class"`. (Write `display:flex`, not bare `flex`.)
+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.
+
+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.
 
 ### Layout & containers
 
@@ -89,17 +96,19 @@ e.g. `"display:flex gap:$3 .my-class"`. (Write `display:flex`, not bare `flex`.)
 
 ### Dialogs
 
-- **`S.modal(opts)`** — dialog rendered into `document.body`, with a dimming
+- **`S.dialog(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.
+  (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.
 
 ### Actions
 
-- **`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.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.
 
 Two-way binding uses Aberdeen observables: pass `bind: A.ref($obj, "key")` (or
 any `{ value }` proxy) to fields.
@@ -116,20 +125,44 @@ S.button($opts);
 $opts.disabled = true;   // the button updates, nothing else re-renders
 ```
 
-## Theming
+## Rich text
 
-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:
+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.
 
 ```ts
-S.darkTheme.sPrimary = "#28c4a0";
-S.darkTheme.sPrimaryFg = "#08110d";
-S.lightTheme.sRadius = "6px";
+S.button({ text: "Save **now**" });
+S.box({ header: "See the [docs](/docs)", content: () => { ... } });
 ```
 
-See the `Theme` type for all variables (`sBg`, `sSurface`, `sFg`, `sBorder`,
-`sPrimary`, `sDanger`, `sSuccess`, `sRadius`, `sShadow`, ...).
+## Surfaces & theming
+
+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:
+
+- **level**: `.base` (page), `.panel` (card), `.raised` (chrome)
+- **role**: `.primary`, `.neutral`, `.danger`, `.success`, `.warning`
+- **variant**: `.filled` (default), `.tonal`, `.outlined`
+
+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" })`.
+
+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:
+
+```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
+```
+
+See `src/theme.ts` for the full token list and the palette.
 
 ### Dark / light mode
 
@@ -145,7 +178,7 @@ 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).
 
-All Staffa styles are **global** and use `S_`-prefixed class names, so you can
+All Staffa styles are **global** and use `s-`-prefixed class names, so you can
 also override anything from your own stylesheet.
 
 ## Browser (no bundler)
@@ -184,3 +217,8 @@ npx serve .        # then open /demo/ in a browser
 
 Contributing or extending Staffa? See [`AGENTS.md`](./AGENTS.md) for the design
 philosophy and the add-a-component checklist.
+
+## Changelog
+
+- 0.2.1 (2026-06-06): More flexible theming and component instance styling
+- 0.1.0 (2026-06-05): Initial release!

package/dist/components/autocomplete.js

@@ -2,21 +2,21 @@ 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-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",
     },
 });
 function normOption(o) {
@@ -93,17 +93,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 +152,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 +165,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,10 +1,14 @@
 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;",
+    ".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",
     },
@@ -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,10 +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. */
@@ -46,12 +19,16 @@ 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.
+     */
+    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.
@@ -59,7 +36,7 @@ export interface ButtonOptions extends BaseOptions {
  * @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>
  * ```

package/dist/components/button.js

@@ -1,35 +1,25 @@
 import A from "aberdeen";
 import { drawSlot } from "../core.js";
-// The color role sets a local `--c` (and `--cfg` for text on filled); the
-// variant rules consume them, so we avoid writing colour×variant rules.
+// The button is a `.s-s` surface (defaulting to `.primary` in button() below), so
+// its colours come from the surface classes in theme.ts. This rule only handles
+// layout, border, focus, hover and sizing.
 A.insertGlobalCss({
-    ".S_btn": {
-        "&": "--c:$sPrimary --cfg:$sPrimaryFg " +
-            "display:inline-flex align-items:center justify-content:center gap:$2 " +
+    ".s-btn": {
+        "&": "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 transparent; r:$sRadius padding: 0.5em 1em; " +
+            "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;",
-        "&:focus-visible": "outline:none box-shadow: 0 0 0 3px $sFocus;",
+        "&: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)",
-        // Colour roles.
-        "&.S_neutral": "--c:$sBorderStrong --cfg:$sFg",
-        "&.S_danger": "--c:$sDanger --cfg:#fff",
-        "&.S_success": "--c:$sSuccess --cfg:#08110d",
-        // Variants.
-        "&.S_filled": "background:$c color:$cfg border-color:$c",
-        "&.S_filled:hover": "filter:brightness(1.1)",
-        "&.S_tonal": "color:$c background: color-mix(in srgb, $c 20%, transparent); border-color: color-mix(in srgb, $c 30%, transparent);",
-        "&.S_tonal:hover": "background: color-mix(in srgb, $c 30%, transparent);",
-        "&.S_outlined": "color:$c background:transparent border-color: color-mix(in srgb, $c 55%, $sBorder);",
-        "&.S_outlined:hover": "background: color-mix(in srgb, $c 12%, transparent);",
-        // Sizes.
-        "&.S_sm": "padding: 0.32em 0.7em; font-size:0.85em",
-        "&.S_lg": "padding: 0.66em 1.3em; font-size:1.1em",
+        "&:hover": "filter: brightness(1.08)",
+        "&.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 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.
@@ -37,7 +27,7 @@ A.insertGlobalCss({
  * @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>
  * ```
@@ -45,15 +35,10 @@ 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 variant = o.variant ?? "filled";
-    const color = o.color ?? "primary";
-    const size = o.size === "sm" || o.size === "lg" ? `.S_${o.size}` : "";
-    // Semantic roles select a colour class (the CSS sets `--c`/`--cfg`); any other
-    // value is a raw CSS colour we assign to `--c`, which the variant rules consume
-    // via `var(--c)`. (`primary` is the base default — its class is a no-op.)
-    const semantic = color === "primary" || color === "neutral" || color === "danger" || color === "success";
-    const colorCls = semantic ? `.S_${color}` : "";
-    const el = A(`${tag}.S_btn.S_${variant}${colorCls}${size}`, o.root, o.inner, () => {
+    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, () => {
         if (o.href != null) {
             A(`href=${o.href} role=button`);
             if (o.disabled)
@@ -74,10 +59,4 @@ export function button(opts = {}) {
         else if (o.text != null)
             A("#", o.text);
     });
-    // Aberdeen's inline styler doesn't set CSS custom properties, so assign the
-    // custom accent on the element directly. A leading `$` is Aberdeen's shorthand
-    // for a CSS variable reference, so expand it to `var(--name)`.
-    if (!semantic && el instanceof HTMLElement) {
-        el.style.setProperty("--c", color.startsWith("$") ? `var(--${color.slice(1)})` : color);
-    }
 }

package/dist/components/buttonChooser.d.ts

@@ -0,0 +1,42 @@
+import { type Bindable, type Attributes } 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.
+     */
+    options: Record<string, string>;
+    /**
+     * Two-way binding for the selected id, or `null` when nothing is selected.
+     * Use an `A.proxy` or `A.ref`.
+     */
+    bind: Bindable<string | null>;
+    /**
+     * When `true`, clicking the already-selected button deselects it, setting
+     * `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;
+}
+/**
+ * A single-selection segmented control: an attached button group where exactly
+ * one button is active at a time. Optionally allows deselecting back to `null`.
+ *
+ * Renders a hidden `<input>` alongside (when `name` is set) so the selected
+ * value is included in native form submission.
+ *
+ * @example
+ * ```ts
+ * const $view = A.proxy({ value: "day" as string | null });
+ * S.buttonChooser({
+ *   options: { day: "Day", week: "Week", month: "Month" },
+ *   bind: $view,
+ * });
+ * ```
+ */
+export declare function buttonChooser(opts: ButtonChooserOptions): void;

package/dist/components/buttonChooser.js

@@ -0,0 +1,38 @@
+import A from "aberdeen";
+import { buttonGroup } from "./buttonGroup.js";
+/**
+ * A single-selection segmented control: an attached button group where exactly
+ * one button is active at a time. Optionally allows deselecting back to `null`.
+ *
+ * Renders a hidden `<input>` alongside (when `name` is set) so the selected
+ * value is included in native form submission.
+ *
+ * @example
+ * ```ts
+ * const $view = A.proxy({ value: "day" as string | null });
+ * S.buttonChooser({
+ *   options: { day: "Day", week: "Week", month: "Month" },
+ *   bind: $view,
+ * });
+ * ```
+ */
+export function buttonChooser(opts) {
+    A(() => {
+        const selected = opts.bind.value;
+        buttonGroup({
+            attrs: opts.attrs,
+            buttons: Object.entries(opts.options).map(([id, label]) => ({
+                text: label,
+                size: opts.size,
+                attrs: selected === id ? ".primary" : ".neutral .outlined",
+                click: () => {
+                    opts.bind.value = (opts.allowDeselect && selected === id) ? null : id;
+                },
+            })),
+        });
+    });
+    if (opts.name) {
+        // Hidden input carries the value into native form submission.
+        A(() => A(`input type=hidden name=${opts.name} value=`, opts.bind.value ?? ""));
+    }
+}

package/dist/components/buttonGroup.d.ts

@@ -22,9 +22,9 @@ export interface ButtonGroupOptions extends ContentOptions {
  * @example
  * ```ts
  * S.buttonGroup({ buttons: [
- *   { text: "Day", variant: "outlined", color: "neutral" },
- *   { text: "Week", variant: "outlined", color: "neutral" },
- *   { text: "Month", variant: "outlined", color: "neutral" },
+ *   { text: "Day", attrs: ".neutral .outlined" },
+ *   { text: "Week", attrs: ".neutral .outlined" },
+ *   { text: "Month", attrs: ".neutral .outlined" },
  * ]});
  * ```
  */