staffa 0.6.1 → 0.7.0

package/skill/SKILL.md

@@ -13,26 +13,31 @@ import * as S from "staffa";
 
 const $user = A.proxy({ name: "", email: "" });
 
-A.mount(document.body, () => {
-  S.main({
-    title: "Sign up",
-    maxWidth: "40rem",
-    content: () => {
-      S.form({
-        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") });
-        },
-        actions: () => S.button({ text: "Create account", type: "submit" }),
-      });
-    },
-  });
+S.main({
+  title: "Sign up",
+  maxWidth: "40rem",
+  content: () => {
+    S.form({
+      submit: () => S.dialog({
+        header: "Submitted",
+        content: () => A.dump($user)
+      }),
+      content: () => {
+        S.textline({ label: "Name", required: true, bind: A.ref($user, "name") });
+        S.textline({ label: "Email", type: "email", bind: A.ref($user, "email") });
+      },
+      actions: () => S.button({ content: "Create account", type: "submit" }),
+    });
+  },
 });
 ```
 
 Staffa is made to look decent out of the box, but easily customizable at runtime.
 
+## Screenshot
+
+![Screenshot](screenshot.png)
+
 ## Install
 
 ```sh
@@ -48,7 +53,7 @@ Aberdeen is a peer dependency. Staffa is published as ESM with TypeScript types.
 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:
 
 ```ts
-S.button({ text: "Save", disabled: false });
+S.button({ content: "Save", disabled: false });
 S.box({ header: "Settings", content: () => { ... } });
 ```
 
@@ -57,10 +62,11 @@ S.box({ header: "Settings", content: () => { ... } });
 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.
 
 ```ts
-const $btn = A.proxy({ text: "Save", disabled: false });
+const $btn = A.proxy({ content: "Save", disabled: false });
 S.button($btn);
-// ...later:
-$btn.disabled = true;  // button updates instantly
+setTimeout(() => // Later..
+  $btn.disabled = true;  // button updates instantly
+}, 3000);
 ```
 
 ### Rich text slots
@@ -68,26 +74,35 @@ $btn.disabled = true;  // button updates instantly
 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.
 
 ```ts
-S.button({ text: "Save **now**" });
+S.button({ content: "Save **now**" });
 S.box({ header: "See the [docs](/docs)", content: () => { ... } });
 ```
 
 ### Surfaces
 
-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:
+Staffa builds on **surfaces**: elements marked with `.s-s` that have their own background and derived text/border tokens. There are two families:
 
-- **level**: `.base`, `.panel`, `.raised`
-- **role**: `.primary`, `.secondary`, `.gradient`, `.neutral`, `.danger`, `.success`, `.warning`
-- **variant**: `.filled`, `.tonal`, `.outlined`
+- **Nesting surfaces** — `.nest` (and the implicit page at `:root`). A calm neutral whose shade steps automatically with nesting depth (page → panel → raised, capped). Use them for cards, bars, popovers — anything that just holds content. No variants.
+- **Solid surfaces** — `.primary`, `.danger`, `.success`, `.warning`, `.link` (a bare `.s-s` defaults to primary). A bright fill with white ink, painted as a subtle single-colour gradient. They take a **variant**: `.filled` (default), `.tonal`, or `.outlined`. A surface nested *inside* a solid surface is always rendered filled, so it can't bleed into the vivid parent.
 
-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:
+Components are built from these (`S.button` is a `.s-s.primary`, `S.box` a `.s-s.nest`, etc.). Because component options include an optional `attrs` string, which has Aberdeen `A()` string semantics, you can easily override it:
 
 ```ts
-S.button({ text: "Delete", attrs: ".danger" });
-S.box({ attrs: ".raised.outlined", content: () => { ... } });
+S.button({ content: "Delete", attrs: ".danger" });
+S.button({ content: "Cancel", attrs: ".nest" });          // neutral button
+S.box({ attrs: ".primary", content: () => { ... } });
 ```
 
-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.
+Inside any surface (including `:root`), CSS variables are defined for the background and a set of safe foreground colors: `$s-bg`, `$s-text` (also applied as `color`), `$s-muted`, `$s-accent` (the surface's "pop" — the brand primary on nesting surfaces, the ink on solid surfaces), and `$s-faint`. By using these, components adapt to wherever they're nested.
+
+The colour tokens are mode-independent and settable: `$s-primary` (the one brand colour — it tints the neutrals and defines `.s-s.primary`), `$s-danger`, `$s-success`, `$s-warning`, and `$s-link` (the link colour, which is also the fill of the `.s-s.link` surface). Links render in `$s-link` on nesting surfaces and in the ink on solid surfaces.
+
+**Borders & shadows.** Nesting surfaces carry a subtle hairline border on their own (so a card looks like a card without any component help). Any surface can be lifted with `.shadow` or `.extra-shadow`: on a nesting surface that's a neutral drop shadow, on a solid surface it's a self-coloured glow (a lit button is just a `.primary` surface with `.shadow`), and on `.tonal`/`.outlined` it's ignored. `.no-shadow` removes a component's built-in shadow:
+
+```ts
+S.box({ attrs: ".extra-shadow", content: () => { ... } });   // a more raised card
+S.button({ content: "Quiet", attrs: ".no-shadow" });          // drop the button glow
+```
 
 ### Dark and light modes
 
@@ -107,30 +122,30 @@ Staffa includes a lightweight CSS reset that makes bare semantic HTML look a bit
 
 ### 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:
+The first step in theming is just setting some CSS variables. Everything derives from a single brand colour, `s-primary` (the neutral surface shades are tinted toward it too), so often that's all you need. This can be done through CSS directly, or using Aberdeen:
 
 ```ts
 A.cssVars["s-primary"] = "#fdda58";
-A.cssVars["s-secondary"] = "#cc5624";
 A.cssVars["s-danger"] = "#ee4422";
 A.cssVars["s-radius"] = "4px";
 ```
 
 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:
+If you need further customization, just add some CSS to override the default styling. For instance, to add your own solid surface, set its background (and, if needed, its ink) — the subtle gradient and the rest of the tokens follow automatically:
 
 ```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"});
+A.insertGlobalCss({".s-s.my-surface": "--s-bg:#ef6b00 --s-text:#fff"});
 
 S.button({
-  text: "You'll want to click me",
+  content: "You'll want to click me",
   attrs: ".my-surface",
   click: () => S.alert("Good work!", {attrs: ".my-surface"})
 });
 ```
 
+Custom surface class names may be anything (other than the built-in modifiers `.tonal`, `.outlined`, `.small`, `.large`). The `.tonal` and `.outlined` variants work on your surface for free.
+
 Note that when changing CSS like this, things *may* break if you upgrade Staffa. The recommended update strategy is therefore: don't!
 
 If you want to make changes that are dependent upon the current light/dark mode setting, rely on Aberdeen reactivity:
@@ -139,10 +154,10 @@ If you want to make changes that are dependent upon the current light/dark mode
 A(() => {
   if (S.getDarkMode()) {
     A.cssVars["s-primary"] = "#aa9944";
-    A.insertGlobalCss({".s-s.my-surface": "--s-a:white --s-b:#444444"});
+    A.insertGlobalCss({".s-s.my-surface": "--s-bg:#444444 --s-text:#fff"});
   } else {
     A.cssVars["s-primary"] = "#fdda58";
-    A.insertGlobalCss({".s-s.my-surface": "--s-a:black --s-b:#cccccc"});
+    A.insertGlobalCss({".s-s.my-surface": "--s-bg:#cccccc --s-text:#000"});
   }
 });
 ```
@@ -182,14 +197,12 @@ Components share naming conventions for options: `attrs` (outermost element), `c
 
 Staffa ships the full [Lucide icon set](https://lucide.dev/icons/) as named exports. Import only the ones you use, so a bundler tree-shakes the rest (the whole set is ~82 kB gzipped):
 
-```ts
-import { sparkles, bell } from "staffa/icons.js";
-```
-
 Each icon is a draw function usable anywhere a slot is accepted (e.g. a button `icon`), or called directly. Customize per call, or globally via `setDefaults()`:
 
 ```ts
-S.button({ text: "Save", icon: bell });
+import * as S from "staffa";
+import { sparkles, bell } from "staffa/icons";
+S.button({ content: "Save", icon: bell });
 sparkles({ size: "1.5em", color: "var(--s-primary)", strokeWidth: 1.5 });
 ```
 
@@ -197,7 +210,7 @@ Options: `size`, `color` (defaults to `currentColor`), `strokeWidth`, `cap`, `jo
 
 ### Other
 
-- **`S.menuButton(opts)` / `S.showFloatingMenu(opts)`**: menu actions and floating menus, with keyboard navigation and submenus.
+- **`S.menuButton(opts)` / `S.addContextMenu(opts)` / `S.showFloatingMenu(opts)`**: dropdown menus from a button, right-click/long-press context menus, and the underlying floating menu primitive — with keyboard navigation.
 - **`S.toast(opts)`**: transient notification at the bottom of the viewport.
 - **`S.addTooltip(el, opts)`**: tooltip on hover, attached to an existing element.
 
@@ -237,7 +250,7 @@ Staffa is designed for extension. A component is simply a plain function taking
 
 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.
+4. **Build on surfaces.** Mark elements `.s-s` and add `.nest` (neutral) or a solid role (`.primary`, `.danger`, …) plus an optional variant. Inside them, use the contextual CSS variables (`$s-text`, `$s-bg`, `$s-muted`, `$s-accent`, `$s-faint`, ...) 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.
 
@@ -276,6 +289,40 @@ npx shotest review # review/accept the visual changes against the baseline
 
 The visual tests (`tests/*.spec.ts`) need a build first (`npm run build`); they serve the repo root themselves and click through every demo page. Accepted baselines live in `test-accepted/`.
 
+## AI skill
+
+If you use Claude Code, GitHub Copilot or another AI agents that supports Skills, Staffa includes a `skill/` directory that provides specialized knowledge to the AI about how to use the library effectively.
+
+To use this, it is recommended to symlink the skill into your project's `.claude/skills` directory:
+
+```sh
+mkdir -p .claude/skills
+ln -s ../../node_modules/staffa/skill .claude/skills/staffa
+```
+
+## Breaking changes
+
+- **0.7** — the surface model was simplified to two families: **nesting** (`.nest`) and **solid** (`.primary`/`.danger`/`.success`/`.warning`/`.link`).
+  - Surface levels `.base`/`.panel`/`.raised`/`.neutral` are replaced by a single `.nest` class whose shade steps with nesting depth. Replace them all with `.nest` (a neutral *button* is `.nest` too, in place of `.neutral .outlined`).
+  - `.secondary` and `.gradient` are gone: there is no more `s-secondary` colour, and the default button is `.primary` (which now carries a subtle auto-gradient). Drop `s-secondary` overrides.
+  - Solid surfaces now use **white** ink (was near-black), and the brand/semantic colours (`s-primary`/`s-danger`/`s-success`/`s-warning`) are now a single mode-independent value each.
+  - New: a `s-link` colour and a matching `.s-s.link` surface. Links use `s-link` on nesting surfaces, the ink on solid ones.
+  - Nesting surfaces now carry their own hairline border, and `.shadow`/`.extra-shadow`/`.no-shadow` utilities work on any surface. `S.box` no longer draws its own border/shadow (they come from the surface); pass `.no-shadow` to `S.box`/`S.button` to drop the default elevation.
+  - Contextual tokens were renamed/trimmed: `--s-fg`→`--s-text`, `--s-fg-muted`→`--s-muted`, `--s-border`→`--s-faint`; `--s-strong`, `--s-fg-faint`, `--s-border-strong`, `--s-on-accent`, `--s-ink`, `--s-page`/`--s-panel`/`--s-raised`, `--s-tint`, `--s-glow`, `--s-shadow`, `--s-gradient-surface`, and the `--s-a`/`--s-b` anchors were removed. Custom solid surfaces now set `--s-bg`/`--s-text`.
+
+- **0.6**: None.
+
+- **0.5**
+  - Surfaces (`.s-s`) now apply `border-radius` and — for `.tonal` and `.outlined` variants — `border` automatically. Custom surfaces or components that previously set these manually may see doubled or conflicting styles; remove the manual declarations.
+  - `border:0` is now applied to `.s-btn` by default (overriding the browser's 2px button border). Custom button-like components built on `.s-btn` that relied on the browser default border should add an explicit border.
+
+- **0.4**
+  - There is no default export anymore: replace `import S from "staffa"` with `import * as S from "staffa"`.
+  - `S.button` no longer has a `text` option: use `content` instead (it accepts a string or a draw function).
+  - The `Content` type is gone: use `Slot` instead. The `Styling` type alias is now exported as `Attributes`.
+  - `S.buttonChooser` uses `undefined` instead of `null` for "nothing selected" (in `bind` and with `allowDeselect`).
+  
+
 # API Reference
 
 ## setDarkMode · function
@@ -321,8 +368,8 @@ Options for `box`.
 
 ## [button](button.md) · function
 
-A button. Always carries at least a visible border so its affordance is
-obvious at a glance.
+A button. Tonal and outlined variants show a border; filled variants rely on
+their solid background for affordance.
 
 ## [ButtonOptions](ButtonOptions.md) · interface
 
@@ -391,6 +438,13 @@ Open a floating dropdown menu anchored to an element. Portals to
 no room below), and closes on Escape, Tab, item selection, or any click
 outside the panel and anchor. Returns a `close()` function.
 
+## [addContextMenu](addContextMenu.md) · function
+
+Attaches a context menu to the current element: adds a `contextmenu` handler
+via `A` so a | floating menu opens (instead of
+the browser's own menu) on right-click or long-press. The menu is anchored to
+the element and closes on Escape, Tab, item selection, or any click outside.
+
 ## [MenuOptions](MenuOptions.md) · interface
 
 Options for `menuButton` and `MainOptions.nav`.
@@ -421,6 +475,13 @@ A visual divider between groups of items.
 
 Options for `showFloatingMenu`.
 
+## ContextMenuOptions · type
+
+Options for `addContextMenu` — like `FloatingMenuOptions`, but
+the anchor is the element the handler is attached to.
+
+**Type:** `Omit<FloatingMenuOptions, "anchor">`
+
 ## [dialog](dialog.md) · function
 
 A dialog rendered into `document.body` via `A.mount`, with a dimming backdrop
@@ -479,7 +540,7 @@ Options for `tabs`.
 ## [textarea](textarea.md) · function
 
 A multi-line text input. Shares the field chrome and styling of
-`textline`, adding `rows` and `resize` controls.
+`textline`.
 
 ## [TextareaOptions](TextareaOptions.md) · interface
 
@@ -503,7 +564,7 @@ that need their own widget (`checkbox`, `radio`, `color`, `range`, `file`,
 ## [toast](toast.md) · function
 
 Show a toast notification. Returns a `dismiss()` function to remove it
-programmatically. Auto-dismisses after `duration` ms (default 4 000).
+programmatically. Auto-dismisses after `duration` ms (default 6 000).
 
 ## [ToastOptions](ToastOptions.md) · interface
 

package/skill/ToastOptions.md

@@ -22,7 +22,7 @@ Colour role. Defaults to `"neutral"`.
 
 ### toastOptions.duration · member
 
-Auto-dismiss delay in milliseconds. Defaults to `4000`.
+Auto-dismiss delay in milliseconds. Defaults to `6000`.
 Pass `0` to make the toast persistent until dismissed manually.
 
 **Type:** `number`

package/skill/addContextMenu.md

@@ -0,0 +1,28 @@
+## addContextMenu · function
+
+Attaches a context menu to the current element: adds a `contextmenu` handler
+via `A` so a | floating menu opens (instead of
+the browser's own menu) on right-click or long-press. The menu is anchored to
+the element and closes on Escape, Tab, item selection, or any click outside.
+
+**Signature:** `(opts: ContextMenuOptions) => void`
+
+**Parameters:**
+
+- `opts: ContextMenuOptions`
+
+**Examples:**
+
+```ts
+import * as icons from "staffa/icons";
+
+S.box(() => {
+  A("#Right-click / long-tap me!");
+  S.addContextMenu({
+    items: [
+      { label: "AI something", icon: icons.sparkles, click: () => ai() },
+      { label: "Launch missiles", icon: icons.rocket, click: () => launch() },
+    ],
+  });
+});
+```

package/skill/addTooltip.md

@@ -15,11 +15,15 @@ element's bounding rect and automatically flips when near the viewport edge.
 **Examples:**
 
 ```ts
-A("button #Save", () => {
+S.button(() => {
+  A("#Save");
   S.addTooltip({ tip: "Saves your work to the cloud" });
 });
 
-A("button #Delete", () => {
+A(" ");
+
+S.button(() => {
+  A(".danger #Delete");
   S.addTooltip({ tip: "Dangerous — cannot be undone", placement: "bottom" });
 });
 ```

package/skill/autocomplete.md

@@ -14,9 +14,16 @@ backspace-to-remove). Implements the ARIA combobox/listbox pattern.
 
 ```ts
 // Single select from a fixed list
+const $sel = A.proxy("Netherlands");
 S.autocomplete({ label: "Country", options: ["Belgium", "Netherlands"], bind: $sel });
 
 // Multi-select, disallowing custom items
-S.autocomplete({ label: "Tags", multi: true, allowCustom: false,
-  options: knownTags, bind: A.ref($post, "tags") });
+const $tags = A.proxy({value: [] as string[]});
+S.autocomplete({
+  label: "Tags",
+  multi: true,
+  allowCustom: false,
+  options: ["Rust", "JS", "C++", "Klingon", "Go"],
+  bind: A.ref($tags)
+});
 ```

package/skill/box.md

@@ -18,6 +18,7 @@ Shortcut: pass a function to use it directly as the body content.
 **Examples:**
 
 ```ts
+const $user = A.proxy({name: "Kvothe"});
 S.box({ header: "Profile", contentAttrs: "display:flex flex-direction:column", content: () => {
   S.textline({ label: "Name", bind: A.ref($user, "name") });
 }});

package/skill/button.md

@@ -1,7 +1,7 @@
 ## button · function
 
-A button. Always carries at least a visible border so its affordance is
-obvious at a glance.
+A button. Tonal and outlined variants show a border; filled variants rely on
+their solid background for affordance.
 
 Shortcut: pass a string to use it as the label, or a function for custom
 content.
@@ -9,6 +9,7 @@ content.
 **Tip:** pair `href` with Aberdeen's `interceptLinks()` (called once at app
 startup) for SPA-style navigation without manual click handlers:
 ```ts
+import {interceptLinks} from from "aberdeen/route";
 interceptLinks(); // once at root
 S.button({ href: "/dashboard", content: "Dashboard" }); // navigates via router
 ```
@@ -22,7 +23,8 @@ S.button({ href: "/dashboard", content: "Dashboard" }); // navigates via router
 **Examples:**
 
 ```ts
-S.button({ content: "Save", click: save });
+S.button({ content: "Save", click: S.alert("Saved.") });
+S.button({ content: "Cancel", attrs: ".nest", click: cancel }); // neutral button
 S.button({ content: "Delete", attrs: ".danger .outlined", click: del });
 S.button("Cancel");                        // shorthand for { content: "Cancel" }
 S.button({ href: "/docs", content: "Docs" }); // renders an <a role=button>

package/skill/buttonGroup.md

@@ -3,6 +3,8 @@
 Groups related buttons, either as a joined segmented control (`attached`) or
 spaced out. A `role=group` is applied for assistive tech.
 
+If you want a single button to be *selected*, use `buttonChooser`.
+
 **Signature:** `(opts?: ButtonGroupOptions) => void`
 
 **Parameters:**
@@ -13,8 +15,8 @@ spaced out. A `role=group` is applied for assistive tech.
 
 ```ts
 S.buttonGroup({ buttons: [
-  { text: "Day", attrs: ".neutral .outlined" },
-  { text: "Week", attrs: ".neutral .outlined" },
-  { text: "Month", attrs: ".neutral .outlined" },
+  { content: "Day", attrs: ".nest" },
+  { content: "Week", attrs: ".nest" },
+  { content: "Month", attrs: ".nest" },
 ]});
 ```

package/skill/checkbox.md

@@ -13,5 +13,6 @@ reader support.
 **Examples:**
 
 ```ts
+const $prefs = A.proxy({newsletter: true});
 S.checkbox({ label: "Subscribe to newsletter", bind: A.ref($prefs, "newsletter") });
 ```

package/skill/confirm.md

@@ -13,5 +13,5 @@ Shows a confirmation dialog with Cancel and OK buttons. Returns a
 **Examples:**
 
 ```ts
-if (await S.confirm("Delete this item?")) deleteItem();
+if (await S.confirm("Delete this item?")) S.alert("Gone!");
 ```

package/skill/dialog.md

@@ -21,8 +21,8 @@ S.dialog({
   header: "Confirm",
   content: (close) => {
     A("p #Are you sure?");
-    S.button({ content: "Yes", click: () => { doIt(); close(); } });
-    S.button({ content: "Cancel", attrs: ".neutral .outlined", click: close });
+    S.button({ content: "Yes", click: () => { S.alert("Nice!"); close(); } });
+    S.button({ content: "Cancel", attrs: ".nest", click: close });
   },
 });
 ```

package/skill/form.md

@@ -17,11 +17,12 @@ native validation runs, but the page never reloads.
 **Examples:**
 
 ```ts
+const $user = A.proxy({name: "Darth", email: "d.vader@example.com"});
 S.form({
   submit: () => save(),
   content: () => {
-    S.textline({ label: "Name", required: true, bind: A.ref($u, "name") });
-    S.textline({ label: "Email", type: "email", bind: A.ref($u, "email") });
+    S.textline({ label: "Name", required: true, bind: A.ref($user, "name") });
+    S.textline({ label: "Email", type: "email", bind: A.ref($user, "email") });
   },
   actions: () => S.button({ content: "Save", type: "submit" }),
 });

package/skill/main.md

@@ -27,7 +27,11 @@ S.main({
   },
   navPosition: "left",
   menu: () => S.button({ content: "New", attrs: ".small" }),
-  content: () => drawPage(),
+  content: drawPage,
   footer: "© 2026",
 });
+
+function drawPage() {
+  S.box({title: "Hello world", content: "Here's you app.."});
+}
 ```

package/skill/menuButton.md

@@ -17,7 +17,7 @@ for SPA navigation — active items are highlighted automatically.
 
 ```ts
 S.menuButton({
-  button: { text: "Actions", attrs: ".neutral .outlined" },
+  button: { content: "Actions", attrs: ".nest" },
   items: [
     { label: "Edit", icon: () => A("#✎"), click: () => edit() },
     { separator: true },

package/skill/prompt.md

@@ -15,5 +15,5 @@ the entered string if the user confirmed, or `null` if cancelled.
 
 ```ts
 const name = await S.prompt("Enter your name:", "Alice");
-if (name !== null) greet(name);
+if (name !== null) S.alert(`Hi ${name}!`);
 ```

package/skill/select.md

@@ -13,5 +13,6 @@ mobile-native picker behaviour to the browser.
 **Examples:**
 
 ```ts
+const $sel = A.proxy("Netherlands"); 
 S.select({ label: "Country", options: ["Belgium", "Netherlands"], bind: $sel });
 ```

package/skill/showFloatingMenu.md

@@ -5,6 +5,10 @@ Open a floating dropdown menu anchored to an element. Portals to
 no room below), and closes on Escape, Tab, item selection, or any click
 outside the panel and anchor. Returns a `close()` function.
 
+Menus are usually opened through `menuButton` or
+`addContextMenu`; reach for this primitive when you need to trigger a
+menu from some other event, anchored to an arbitrary element.
+
 **Signature:** `(opts: FloatingMenuOptions) => () => void`
 
 **Parameters:**
@@ -14,9 +18,4 @@ outside the panel and anchor. Returns a `close()` function.
 **Examples:**
 
 ```ts
-// Custom context menu:
-el.addEventListener("contextmenu", (e) => {
-  e.preventDefault();
-  S.showFloatingMenu({ items, anchor: el });
-});
-```
+// An

package/skill/tabs.md

@@ -13,7 +13,7 @@ for the selected tab. Supports keyboard navigation (left/right/home/end).
 
 ```ts
 S.tabs({ tabs: [
-  { label: "Overview", content: () => A("p#...") },
-  { label: "Settings", content: () => drawSettings() },
+  { label: "Overview", content: () => A("p#Let me give you an overview..") },
+  { label: "Settings", content: () => S.checkbox({label: "I agree to anything", checked: true}) },
 ]});
 ```

package/skill/textarea.md

@@ -1,7 +1,7 @@
 ## textarea · function
 
 A multi-line text input. Shares the field chrome and styling of
-`textline`, adding `rows` and `resize` controls.
+`textline`.
 
 **Signature:** `(opts?: TextareaOptions) => void`
 
@@ -12,5 +12,6 @@ A multi-line text input. Shares the field chrome and styling of
 **Examples:**
 
 ```ts
-S.textarea({ label: "Bio", rows: 6, bind: A.ref($user, "bio") });
+const $user = A.proxy({bio: ""});
+S.textarea({ label: "Bio", bind: A.ref($user, "bio") });
 ```

package/skill/textline.md

@@ -15,5 +15,6 @@ help/error), so it aligns cleanly inside a `form`.
 **Examples:**
 
 ```ts
+const $user = A.proxy({email: "test@example.com"});
 S.textline({ label: "Email", type: "email", required: true, bind: A.ref($user, "email") });
 ```

package/skill/toast.md

@@ -1,7 +1,7 @@
 ## toast · function
 
 Show a toast notification. Returns a `dismiss()` function to remove it
-programmatically. Auto-dismisses after `duration` ms (default 4 000).
+programmatically. Auto-dismisses after `duration` ms (default 6 000).
 
 **Signature:** `(opts: ToastOptions) => () => void`
 
@@ -15,6 +15,5 @@ programmatically. Auto-dismisses after `duration` ms (default 4 000).
 S.toast({ message: "Saved!", type: "success" });
 S.toast({ title: "Error", message: "Upload failed.", type: "danger", duration: 0 });
 const off = S.toast({ message: "Uploading…", duration: 0, dismissible: false });
-// later:
-off();
+setTimeout(off, 3000); // Later..
 ```

package/src/components/autocomplete.ts

@@ -35,20 +35,23 @@ export interface AutocompleteOptions extends FieldOptions {
 A.insertGlobalCss({
 	".s-ac": {
 		"&": "position:relative",
-		"> .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",
+		// Same light inset field as `.s-input` (see field.ts), derived from the surface.
+		"> .s-control": "display:flex flex-wrap:wrap align-items:center gap:$1 background: color-mix(in oklab, $s-bg, $s-text 4%); color:$s-text border: 1px solid $s-faint; r:$s-radius padding: 0.3em 0.4em; cursor:text; transition: border-color 0.15s, box-shadow 0.15s;",
+		"> .s-control:hover": "border-color: color-mix(in oklab, $s-text, $s-bg 55%);",
 		"> .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",
+		".s-chip": "display:inline-flex align-items:center gap:$1 font-size:0.85em background: color-mix(in oklab, $s-bg, $s-text 10%); border: 1px solid $s-faint; r:$s-radius padding: 0.1em 0.2em 0.1em 0.5em;",
+		".s-chip > button": "cursor:pointer border:0 background:transparent fg:$s-muted font-size:1.1em line-height:1 padding: 0 0.2em; r:4px",
+		".s-chip > button:hover": "fg:$s-text background:$s-faint",
 		"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",
+		// The popup is a `.s-s.neutral.shadow` surface (see below): background, border,
+		// radius and elevation all come from the surface.
+		"> .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",
 		"> .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-option[aria-selected=true]": "background: color-mix(in srgb, $s-text 10%, transparent);",
 		".s-add": "fg:$s-accent font-style:italic",
-		".s-empty": "padding: 0.45em 0.6em; fg:$s-fg-muted",
+		".s-empty": "padding: 0.45em 0.6em; fg:$s-muted",
 	},
 });
 
@@ -191,7 +194,7 @@ export function autocomplete(opts: AutocompleteOptions): void {
 				const q = $st.query.trim();
 				const showAdd = opts.allowCustom !== false && q !== "" && !list.some((o) => o.label.toLowerCase() === q.toLowerCase());
 
-				A("ul.s-menu role=listbox", `id=${menuId}`, () => {
+				A("ul.s-menu.s-s.neutral.shadow role=listbox", `id=${menuId}`, () => {
 					list.forEach((option, i) => {
 						A("li.s-option role=option", `id=${menuId}-opt-${i}`, () => {
 							A(() => A("aria-selected=", $st.active === i ? "true" : "false"));