staffa 0.3.1 → 0.4.1

package/src/components/form.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Content, type ContentOptions, type Attributes } from "../core.js";
+import { type ContentOptions, type Attributes, type Slot, drawSlot } from "../core.js";
 
 /** Options for {@link form}. */
 export interface FormOptions extends ContentOptions {
@@ -18,7 +18,7 @@ export interface FormOptions extends ContentOptions {
 	/** Aberdeen attr/style string for the action bar. */
 	actionsAttrs?: Attributes;
 	/** Footer actions (typically a {@link import("./buttonGroup").buttonGroup} or buttons). */
-	actions?: Content;
+	actions?: Slot;
 }
 
 A.insertGlobalCss({
@@ -26,7 +26,7 @@ A.insertGlobalCss({
 		"&": "display:flex flex-direction:column gap:$3",
 		"&.grid": "display:grid grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); gap:$3",
 		"&.grid > .s-wide, &.grid > footer": "grid-column: 1 / -1;",
-		"> footer": "display:flex align-items:center gap:$2 flex-wrap:wrap margin-top:$1",
+		"> footer": "display:flex align-items:center justify-content:flex-end gap:$2 flex-wrap:wrap margin-top:$1",
 	},
 });
 
@@ -47,12 +47,12 @@ A.insertGlobalCss({
  *     S.textline({ label: "Name", required: true, bind: A.ref($u, "name") });
  *     S.textline({ label: "Email", type: "email", bind: A.ref($u, "email") });
  *   },
- *   actions: () => S.button({ text: "Save", type: "submit" }),
+ *   actions: () => S.button({ content: "Save", type: "submit" }),
  * });
  * ```
  */
-export function form(opts: FormOptions | Content = {}): void {
-	const o: FormOptions = typeof opts === "function" ? { content: opts } : opts;
+export function form(opts: FormOptions | Slot = {}): void {
+	const o: FormOptions = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
 
 	A(`form.s-form`, o.attrs, () => {
 		// Toggle grid class in its own scope so changing layout doesn't recreate
@@ -74,11 +74,11 @@ export function form(opts: FormOptions | Content = {}): void {
 			}
 		});
 
-		if (o.content) o.content();
+		drawSlot(o.content);
 
 		// Own scope so toggling actions doesn't recreate the fields above.
 		A(() => {
-			if (o.actions) A("footer", o.actionsAttrs, () => o.actions?.());
+			if (o.actions) A("footer", o.actionsAttrs, () => drawSlot(o.actions));
 		});
 	});
 }

package/src/components/main.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Content, type Slot, type Attributes, drawSlot } from "../core.js";
+import { type Slot, type Attributes, drawSlot } from "../core.js";
 import { type MenuOptions, menuButton, drawMenu } from "./menu.js";
 
 /** Options for {@link main}. */
@@ -13,9 +13,9 @@ export interface MainOptions {
 	/** Leading icon/logo in the top bar. */
 	icon?: Slot;
 	/** Action area on the right of the top bar (buttons, menu, ...). */
-	menu?: Content;
-	/** The scrollable page content. */
-	content?: Content;
+	menu?: Slot;
+	/** The scrollable page content. A string is rendered as rich text. */
+	content?: Slot;
 	/** Footer content, pinned below the scroll area. */
 	footer?: Slot;
 	/**
@@ -62,8 +62,9 @@ A.insertGlobalCss({
 		"> header .s-title": "font-weight:800 font-size:1.1em line-height:1.2 overflow:hidden text-overflow:ellipsis white-space:nowrap letter-spacing:-0.01em background: $s-gradient; -webkit-background-clip:text; background-clip:text; color:transparent; width:fit-content max-width:100%",
 		"> header .s-subtitle": "fg:$s-fg-muted font-size:0.85em overflow:hidden text-overflow:ellipsis white-space:nowrap",
 		"> header .s-menu": "display:flex align-items:center gap:$2",
-		// Body holds sidebar + separator + <main> side by side (only used in sidebar
-		// nav mode). It centres `.s-body-inner`, which caps the trio to maxWidth.
+		// Body always wraps <main> (with or without a sidebar) so max-width centering
+		// and scrollbar alignment work identically in both cases.
+		// .s-body centres .s-body-inner; .s-body-inner caps the content to maxWidth.
 		".s-body": "flex:1 overflow:hidden display:flex flex-direction:row min-height:0 justify-content:center",
 		".s-body-inner": "flex:1 display:flex flex-direction:row min-height:0",
 		// Put the sidebar on the right (content fills the left) for right-hand navs.
@@ -71,20 +72,19 @@ A.insertGlobalCss({
 		// A vertical hairline between sidebar and content, fading out at both ends —
 		// the vertical sibling of the menu's `hr.s-menu-sep`.
 		".s-nav-sep": "width:1px flex-shrink:0 align-self:stretch margin: 0.6rem 0; border:0 background: linear-gradient(to bottom, transparent, $s-border-strong 18%, $s-border-strong 82%, transparent);",
-		// Without a sidebar, <main> is a direct child; with one it lives in .s-body.
-		"> main, .s-body main": "flex:1 overflow-y:auto display:flex flex-direction:column",
-		// The content area fills the scroll region with comfortable padding. Without a
-		// sidebar it caps its own width to maxWidth and centres (applied inline in
-		// drawMainContent); with one, `.s-body-inner` does the capping for the trio.
+		// min-height:0 overrides the flex default of min-height:auto so <main> can
+		// shrink to fit the bounded container and show its own scrollbar.
+		".s-body main": "flex:1 min-height:0 overflow-y:auto display:flex flex-direction:column",
+		// The content area fills the scroll region with comfortable padding.
 		// It is deliberately NOT a boxed "sheet" — content brings its own boxes.
-		"> main > .s-content, .s-body main > .s-content": "width:100% flex:1 p:$3",
+		".s-body main > .s-content": "width:100% flex:1 p:$3",
 		// When <main> actually shows a vertical scrollbar (the `.s-scroll-y` class is
 		// toggled from JS by watchVerticalOverflow), inset it from the shell edge by
 		// $3 so the bar's right edge lines up with the header/footer content (which
 		// sits $3 inside the edge via `.s-bar` padding). The $3 gap between the content
 		// and the bar already comes from `.s-content`'s padding. Without a scrollbar
 		// there's no margin, so the content keeps its single $3 edge — not 2×$3.
-		"> main.s-scroll-y, .s-body main.s-scroll-y": "margin-right:$3",
+		".s-body main.s-scroll-y": "margin-right:$3",
 	},
 	// Sidebar nav panel. Items reuse the shared `.s-menu-item[-link]` /
 	// `.s-menu-sep` styles from menu.ts, so the sidebar and the floating
@@ -110,6 +110,9 @@ A.insertGlobalCss({
 		// On phones a top-level content box becomes a full-bleed block: pull it out
 		// to negate the content padding and drop the rounded corners.
 		".s-content > .s-box": "margin-inline: calc(-1 * $3); r:0 border-inline:0",
+		// At narrow widths, content boxes are full-bleed so there's no inset to
+		// align the scrollbar with — cancel the right margin.
+		".s-main .s-body main.s-scroll-y": "margin-right:0",
 	},
 });
 
@@ -133,7 +136,7 @@ A.insertGlobalCss({
  *     ],
  *   },
  *   navPosition: "left",
- *   menu: () => S.button({ text: "New", attrs: ".small" }),
+ *   menu: () => S.button({ content: "New", attrs: ".small" }),
  *   content: () => drawPage(),
  *   footer: "© 2026",
  * });
@@ -190,30 +193,28 @@ export function main(opts: MainOptions = {}): void {
 						});
 					});
 					A(() => {
-						if (opts.menu) A("div.s-menu", () => opts.menu?.());
+						if (opts.menu) A("div.s-menu", () => drawSlot(opts.menu));
 					});
 				});
 			});
 		});
 
-		// Body — wraps sidebar + separator + main when nav is in sidebar mode. The
-		// trio together caps to maxWidth (via .s-body-inner); main fills the rest.
-		if (hasNav && navPos !== "button") {
-			A("div.s-body", () => {
-				A("div.s-body-inner", () => {
-					A(() => {
-						if (opts.maxWidth != null) A("max-width:", opts.maxWidth);
-					});
+		// Body always wraps <main> so max-width centering and scrollbar alignment
+		// are identical with and without a sidebar nav.
+		A("div.s-body", () => {
+			A("div.s-body-inner", () => {
+				A(() => {
+					if (opts.maxWidth != null) A("max-width:", opts.maxWidth);
+				});
+				if (hasNav && navPos !== "button") {
 					A(`nav.s-nav-panel.s-s.raised.s-nav-${navPos}`, opts.navAttrs, () => {
 						drawMenu(nav.items);
 					});
 					A("div.s-nav-sep aria-hidden=true");
-					drawMainContent(opts, false);
-				});
+				}
+				drawMainContent(opts);
 			});
-		} else {
-			drawMainContent(opts, true);
-		}
+		});
 
 		// Footer — full-width background, content centred to maxWidth via .s-bar.
 		A(() => {
@@ -231,20 +232,10 @@ export function main(opts: MainOptions = {}): void {
 	});
 }
 
-/**
- * Draw the scrollable `<main>` + content area. When `capWidth` is true (no
- * sidebar), the content caps its own width to maxWidth and centres; in sidebar
- * mode the surrounding `.s-body-inner` already caps the sidebar+content trio.
- */
-function drawMainContent(opts: MainOptions, capWidth: boolean): void {
+function drawMainContent(opts: MainOptions): void {
 	const mainEl = A("main", () => {
 		A("div.s-content", opts.contentAttrs, () => {
-			if (capWidth) {
-				A(() => {
-					if (opts.maxWidth != null) A("margin-inline:auto max-width:", opts.maxWidth);
-				});
-			}
-			if (opts.content) opts.content();
+			drawSlot(opts.content);
 		});
 	}) as HTMLElement;
 	watchVerticalOverflow(mainEl);

package/src/components/menu.ts

@@ -1,6 +1,6 @@
 import A from "aberdeen";
 import { matchCurrent } from "aberdeen/route";
-import { type Content, type Slot, type Attributes, drawSlot } from "../core.js";
+import { type Slot, type Attributes, drawSlot, mountPortal } from "../core.js";
 import { button, type ButtonOptions } from "./button.js";
 
 /**
@@ -41,10 +41,10 @@ export interface MenuSeparator {
  * An entry in a menu or sidebar nav list. Three forms:
  * - `MenuItem` — a clickable/linkable row with label and optional icon.
  * - `MenuSeparator` — a visual divider (`{ separator: true }`).
- * - A draw function `() => void` — renders custom content (section header,
+ * - A slot (string or draw function) — renders custom content (section header,
  *   avatar, search box, …). Skipped by keyboard navigation.
  */
-export type MenuEntry = MenuItem | MenuSeparator | Content;
+export type MenuEntry = MenuItem | MenuSeparator | Slot;
 
 /** Options for {@link menuButton} and {@link MainOptions.nav}. */
 export interface MenuOptions {
@@ -148,7 +148,7 @@ export function drawMenu(items: MenuEntry[], onActivate?: () => void): void {
 	});
 
 	for (const entry of items) {
-		if (typeof entry === "function") { entry(); continue; }
+		if (typeof entry === "string" || typeof entry === "function") { drawSlot(entry); continue; }
 		if ("separator" in entry) { A("hr.s-menu-sep"); continue; }
 
 		A(entry.href ? "a.s-menu-item-link" : "button.s-menu-item type=button", entry.attrs, () => {
@@ -193,7 +193,7 @@ function positionMenu(menuEl: HTMLElement, rect: DOMRect): void {
 	menuEl.style.top  = Math.max(8, y) + "px";
 }
 
-A.mount(document.body, () => {
+mountPortal(() => {
 	const f = $floating.opts;
 	if (!f) return;
 
@@ -260,7 +260,7 @@ export function showFloatingMenu(opts: FloatingMenuOptions): () => void {
  * @example
  * ```ts
  * S.menuButton({
- *   button: { text: "Actions", attrs: ".neutral .outlined" },
+ *   button: { content: "Actions", attrs: ".neutral .outlined" },
  *   items: [
  *     { label: "Edit", icon: () => A("#✎"), click: () => edit() },
  *     { separator: true },
@@ -275,7 +275,9 @@ export function menuButton(opts: MenuOptions): void {
 
 	button({
 		icon: () => A("span aria-hidden=true #☰"),
-		ariaLabel: "Open menu",
+		// Only label the trigger "Open menu" when it has no visible text of its
+		// own — an aria-label would otherwise *hide* that text from AT.
+		...(opts.button?.content == null ? { ariaLabel: "Open menu" } : null),
 		attrs: ".neutral .outlined",
 		...opts.button,
 		click: (e: Event) => {

package/src/components/tabs.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Bindable, type Content, type Slot, type Attributes, drawSlot, uniqueId } from "../core.js";
+import { type Bindable, type Slot, type Attributes, drawSlot, uniqueId } from "../core.js";
 
 /** A single tab definition. */
 export interface Tab {
@@ -9,8 +9,8 @@ export interface Tab {
 	label: Slot;
 	/** Optional leading icon. */
 	icon?: Slot;
-	/** Content rendered in the panel when this tab is active. */
-	content?: Content;
+	/** Content rendered in the panel when this tab is active. A string is rendered as rich text. */
+	content?: Slot;
 	/** Disables selecting this tab. */
 	disabled?: boolean;
 }
@@ -101,7 +101,7 @@ export function tabs(opts: TabsOptions): void {
 				const tab = opts.tabs[index] ?? opts.tabs[0];
 				if (!tab) return;
 				A(`id=${groupId}-panel-${keyOf(tab, index)} aria-labelledby=${groupId}-tab-${keyOf(tab, index)}`);
-				tab.content?.();
+				drawSlot(tab.content);
 			});
 		});
 	});

package/src/components/toast.ts

@@ -1,7 +1,6 @@
 import A from "aberdeen";
 import { grow, shrink } from "aberdeen/transitions";
-import { type Slot, type Attributes, drawSlot } from "../core.js";
-import type { SurfaceRole } from "../theme.js";
+import { type Slot, type Attributes, drawSlot, mountPortal } from "../core.js";
 
 /** Options for {@link toast}. */
 export interface ToastOptions {
@@ -11,9 +10,8 @@ export interface ToastOptions {
 	title?: Slot;
 	/**
 	 * Colour role. Defaults to `"neutral"`.
-	 * Use `"success"` / `"danger"` / `"warning"` for semantic feedback.
 	 */
-	type?: SurfaceRole;
+	type?: "success" | "danger" | "warning" | "neutral"
 	/**
 	 * Auto-dismiss delay in milliseconds. Defaults to `4000`.
 	 * Pass `0` to make the toast persistent until dismissed manually.
@@ -55,7 +53,7 @@ let toastCount = 0;
 // Keyed by stable ID so A.onEach scopes are per-toast — removing one never re-renders others.
 const toasts = A.proxy({} as Record<number, ToastEntry>);
 
-A.mount(document.body, () => {
+mountPortal(() => {
 	A("div.s-toasts aria-live=polite aria-atomic=false", () => {
 		A.onEach(toasts, (entry) => {
 			const { opts } = entry;

package/src/components/tooltip.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Slot, type Attributes, drawSlot } from "../core.js";
+import { type Slot, type Attributes, drawSlot, mountPortal } from "../core.js";
 
 /** Options for {@link addTooltip}. */
 export interface TooltipOptions {
@@ -79,7 +79,7 @@ function scheduleHide(): void {
 
 // ─── Portal ──────────────────────────────────────────────────────────────────
 
-A.mount(document.body, () => {
+mountPortal(() => {
 	const active = $ttActive.value;
 	if (!active) return;
 	const { opts, anchor } = active;

package/src/core.ts

@@ -29,9 +29,6 @@ export type Attributes = string;
 /** A reactive "value box", such as the result of `A.proxy(x)` or `A.ref(obj, key)`. */
 export type Bindable<T> = { value: T };
 
-/** A content function. It runs inside the relevant element's reactive scope. */
-export type Content = () => void;
-
 /**
  * Something that renders a small piece of content: either a plain string or a
  * draw function (for icons, badges, custom markup, ...).
@@ -52,8 +49,8 @@ export type Slot<Args extends unknown[] = []> = string | ((...args: Args) => voi
 export interface ContentOptions {
 	/** Aberdeen attr/style string applied to the widget's outermost element. */
 	attrs?: Attributes;
-	/** Draws the children of this component. */
-	content?: Content;
+	/** Draws the children of this component. A string is rendered as rich text. */
+	content?: Slot;
 }
 
 let idCounter = 0;
@@ -72,3 +69,17 @@ export function drawSlot<Args extends unknown[] = []>(slot: Slot<Args> | undefin
 	if (typeof slot === "function") slot(...args);
 	else A("rich=", slot);
 }
+
+/**
+ * Mount a portal (tooltip, toast, menu, dialog, …) in its own dedicated
+ * container under `<body>`. Each portal gets a private parent element because
+ * two `A.mount`s sharing one parent can't tell their nodes apart: a redraw of
+ * one (e.g. a tooltip hiding) may sweep up nodes another portal inserted
+ * earlier in the same parent (e.g. an open menu).
+ */
+export function mountPortal(draw: () => void): void {
+	const container = document.createElement("div");
+	container.style.display = "contents";
+	document.body.appendChild(container);
+	A.mount(container, draw);
+}

package/src/index.ts

@@ -5,7 +5,7 @@
  * Import the default `S` object and call its component functions:
  *
  * ```ts
- * import S from "staffa";
+ * import * as S from "staffa";
  *
  * S.main({
  *   title: "Hello",
@@ -17,7 +17,7 @@
  *           S.textline({ label: "Email", type: "email", bind: A.ref($u, "email") });
  *           S.checkbox({ label: "Remember me", bind: A.ref($u, "remember") });
  *         },
- *         actions: () => S.button({ text: "Sign in", type: "submit" }),
+ *         actions: () => S.button({ content: "Sign in", type: "submit" }),
  *       });
  *     }});
  *   },
@@ -32,80 +32,25 @@
 // Importing the theme module installs spacing vars, the reactive theme and the
 // base stylesheet. Customise it from your app with A.insertGlobalCss (see
 // theme.ts); toggle modes with setDarkMode / getDarkMode.
-import { setDarkMode, getDarkMode } from "./theme.js";
-
-import { autocomplete } from "./components/autocomplete.js";
-import { box } from "./components/box.js";
-import { button } from "./components/button.js";
-import { buttonChooser } from "./components/buttonChooser.js";
-import { buttonGroup } from "./components/buttonGroup.js";
-import { checkbox } from "./components/checkbox.js";
-import { form } from "./components/form.js";
-import { main } from "./components/main.js";
-import { menuButton, showFloatingMenu } from "./components/menu.js";
-import { dialog, alert, confirm, prompt } from "./components/dialog.js";
-import { select } from "./components/select.js";
-import { tabs } from "./components/tabs.js";
-import { textarea } from "./components/textarea.js";
-import { textline } from "./components/textline.js";
-import { toast } from "./components/toast.js";
-import { addTooltip } from "./components/tooltip.js";
-
-/** The Staffa component namespace. */
-export const S = {
-	main,
-	box,
-	dialog,
-	alert,
-	confirm,
-	prompt,
-	form,
-	menuButton,
-	showFloatingMenu,
-	textline,
-	textarea,
-	checkbox,
-	tabs,
-	button,
-	buttonChooser,
-	buttonGroup,
-	autocomplete,
-	select,
-	toast,
-	addTooltip,
-	setDarkMode,
-	getDarkMode,
-};
-
-export default S;
+export { setDarkMode, getDarkMode } from "./theme.js";
+export { autocomplete, type AutocompleteOptions, type AutocompleteOptionInput } from "./components/autocomplete.js";
+export { box, type BoxOptions } from "./components/box.js";
+export { button, type ButtonOptions } from "./components/button.js";
+export { buttonChooser, type ButtonChooserOptions } from "./components/buttonChooser.js";
+export { buttonGroup, type ButtonGroupOptions } from "./components/buttonGroup.js";
+export { checkbox, type CheckboxOptions } from "./components/checkbox.js";
+export { form, type FormOptions } from "./components/form.js";
+export { main, type MainOptions } from "./components/main.js";
+export { menuButton, showFloatingMenu, type MenuOptions, type MenuEntry, type MenuItem, type MenuSeparator, type FloatingMenuOptions } from "./components/menu.js";
+export { dialog, alert, confirm, prompt, type DialogOptions } from "./components/dialog.js";
+export { select, type SelectOptions, type SelectOptionInput } from "./components/select.js";
+export { tabs, type Tab, type TabsOptions } from "./components/tabs.js";
+export { textarea, type TextareaOptions } from "./components/textarea.js";
+export { textline, type TextlineOptions, type TextlineType } from "./components/textline.js";
+export { toast, type ToastOptions } from "./components/toast.js";
+export { addTooltip, type TooltipOptions } from "./components/tooltip.js";
+export type { FieldOptions } from "./components/field.js";
 
 // Re-export theming and shared types for advanced use.
-export { setDarkMode, getDarkMode } from "./theme.js";
-export type { SurfaceRole, Variant } from "./theme.js";
-export type {
-	ContentOptions,
-	Bindable,
-	Content,
-	Slot,
-	Attributes as Styling,
-} from "./core.js";
-export { drawSlot, uniqueId } from "./core.js";
+export type {ContentOptions, Bindable, Slot, Attributes} from "./core.js";
 
-export type { FieldOptions } from "./components/field.js";
-export type { MainOptions } from "./components/main.js";
-export type { MenuOptions, MenuEntry, MenuItem, MenuSeparator, FloatingMenuOptions } from "./components/menu.js";
-export { drawMenu } from "./components/menu.js";
-export type { ToastOptions } from "./components/toast.js";
-export type { TooltipOptions } from "./components/tooltip.js";
-export type { BoxOptions } from "./components/box.js";
-export type { FormOptions } from "./components/form.js";
-export type { TextlineOptions, TextlineType } from "./components/textline.js";
-export type { TextareaOptions } from "./components/textarea.js";
-export type { CheckboxOptions } from "./components/checkbox.js";
-export type { Tab, TabsOptions } from "./components/tabs.js";
-export type { ButtonOptions } from "./components/button.js";
-export type { ButtonChooserOptions } from "./components/buttonChooser.js";
-export type { ButtonGroupOptions } from "./components/buttonGroup.js";
-export type { AutocompleteOptions, AutocompleteOptionInput } from "./components/autocomplete.js";
-export type { SelectOptions, SelectOptionInput } from "./components/select.js";
-export type { DialogOptions } from "./components/dialog.js";

package/src/theme.ts

@@ -1,14 +1,5 @@
 import A from "aberdeen";
 
-/**
- * The named accent roles for interactive elements (buttons, tabs, badges, …).
- * Each maps to a `.s-s.<role>` class that sets `--s-a` (ink) and `--s-b` (fill).
- */
-export type SurfaceRole = "primary" | "secondary" | "gradient" | "neutral" | "danger" | "success" | "warning";
-
-/** How a surface's two colours are rendered. `filled` is the default. */
-export type Variant = "filled" | "tonal" | "outlined";
-
 /**
  * Theming and global base styles for Staffa.
  *
@@ -48,7 +39,9 @@ export type Variant = "filled" | "tonal" | "outlined";
  * | `--s-fg-faint`   | placeholders, disabled                    |
  * | `--s-border` / `--s-border-strong` | borders                 |
  * | `--s-accent`     | brand "pop" colour (active indicators, etc.) |
- * | `--s-gradient`   | primary→secondary brand sweep (mark, primary buttons, active nav) |
+ * | `--s-gradient`   | full primary→secondary brand sweep (mark, active nav) |
+ * | `--s-gradient-surface` | compressed sweep for filled gradient surfaces (buttons) |
+ * | `--s-tint`       | brand mid colour; the hue the neutral greys lean toward |
  * | `--s-glow`       | soft coloured shadow for lit brand elements |
  * | `--s-link` / `--s-focus` | link & focus-ring colours         |
  * | `--s-radius` / `--s-radius-lg` / `--s-shadow` | shape tokens      |
@@ -145,13 +138,23 @@ export function getDarkMode(allowAuto = false): boolean | undefined {
 // names (--s-primary/-danger/-success/-warning) double as semantic *ink*
 // colours, legible as text/borders on neutral surfaces.
 // ---------------------------------------------------------------------------
+// The neutral fills/inks aren't hard-coded greys: each one mixes a small dose
+// of `--s-tint` (the brand's mid colour, defined in the static block below)
+// into a true-grey base. Re-skin the brand and every "grey" — page, panels,
+// ink, the neutral fill — drifts subtly toward the new brand hue, light and
+// dark alike. The percentages are deliberately small: a tint you'd only spot
+// in a side-by-side, never a colour cast.
 A(() => {
 	if (getDarkMode()) {
 		A.insertGlobalCss({
 			":root":
 				"--s-primary:#8b7bff --s-secondary:#ef7fd0 --s-danger:#ff6b6b --s-success:#46d39a --s-warning:#fbbf24 " +
-				"--s-neutral:#3c4352 --s-page:#0e1015 --s-panel:#181b22 --s-raised:#222632 " +
-				"--s-ink:#e8eaf0 --s-on-accent:#0c0a14 --s-focus:rgba(139,123,255,0.45) " +
+				"--s-neutral: color-mix(in oklab, #3d4047, $s-tint 14%); " +
+				"--s-page: color-mix(in oklab, #0e0f12, $s-tint 5%); " +
+				"--s-panel: color-mix(in oklab, #17181c, $s-tint 6%); " +
+				"--s-raised: color-mix(in oklab, #212327, $s-tint 8%); " +
+				"--s-ink: color-mix(in oklab, #e9eaec, $s-tint 8%); " +
+				"--s-on-accent:#0c0a14 --s-focus: color-mix(in srgb, $s-primary 45%, transparent); " +
 				"--s-radius:12px --s-radius-lg:18px --s-shadow: 0 10px 34px rgba(0,0,0,0.5);",
 			// Contextual link, restored across the neutral group (see static block).
 			":root, .s-s.base, .s-s.panel, .s-s.raised, .s-s.neutral": "--s-link:#6db3ff",
@@ -160,8 +163,12 @@ A(() => {
 		A.insertGlobalCss({
 			":root":
 				"--s-primary:#6c5ce7 --s-secondary:#d6459e --s-danger:#e23b3b --s-success:#1f9d6b --s-warning:#d97706 " +
-				"--s-neutral:#c7ccda --s-page:#f3f4f8 --s-panel:#ffffff --s-raised:#eceef4 " +
-				"--s-ink:#1b1e27 --s-on-accent:#0c0a14 --s-focus:rgba(108,92,231,0.35) " +
+				"--s-neutral: color-mix(in oklab, #c9cbd0, $s-tint 14%); " +
+				"--s-page: color-mix(in oklab, #f3f4f6, $s-tint 5%); " +
+				"--s-panel: color-mix(in oklab, #ffffff, $s-tint 2%); " +
+				"--s-raised: color-mix(in oklab, #edeef0, $s-tint 7%); " +
+				"--s-ink: color-mix(in oklab, #1d1f24, $s-tint 7%); " +
+				"--s-on-accent:#0c0a14 --s-focus: color-mix(in srgb, $s-primary 35%, transparent); " +
 				"--s-radius:12px --s-radius-lg:18px --s-shadow: 0 10px 30px rgba(20,24,40,0.13);",
 			":root, .s-s.base, .s-s.panel, .s-s.raised, .s-s.neutral": "--s-link:#2563eb",
 		});
@@ -189,13 +196,19 @@ A.setSpacingCssVars();
 A.insertGlobalCss({
 	// Derived brand tokens. These only reference the per-mode palette colours, so
 	// they're defined once here and track the active mode (and any re-skin):
-	// `--s-gradient` is the primary→secondary brand sweep used for the headline
-	// mark, primary buttons and the active nav pill; `--s-glow` is a soft coloured
-	// shadow that makes those same elements feel lit; `--s-page-bg` is a faint
+	// `--s-tint` is the brand's mid colour, the hue the neutral greys above lean
+	// toward; `--s-gradient` is the full primary→secondary sweep used where the
+	// brand should *show* (the headline mark, the active nav pill, tab edges);
+	// `--s-gradient-surface` is a compressed, near-vertical cut of that same sweep
+	// for *filled* gradient surfaces (buttons): it reads as one rich colour with
+	// depth rather than a two-colour banner; `--s-glow` is a soft coloured shadow
+	// that makes lit brand elements feel raised; `--s-page-bg` is a faint
 	// twin-corner aurora wash painted on the page surface.
 	":root":
+		"--s-tint: color-mix(in oklab, $s-primary, $s-secondary); " +
 		"--s-gradient: linear-gradient(135deg, $s-primary, $s-secondary); " +
-		"--s-glow: 0 8px 24px color-mix(in srgb, $s-primary 32%, transparent); " +
+		"--s-gradient-surface: linear-gradient(170deg, color-mix(in oklab, $s-primary 85%, $s-secondary), color-mix(in oklab, $s-primary 30%, $s-secondary)); " +
+		"--s-glow: 0 5px 16px color-mix(in srgb, $s-primary 26%, transparent); " +
 		"--s-page-bg: radial-gradient(120% 80% at 100% 0%, color-mix(in oklab, $s-secondary, transparent 86%), transparent 56%), radial-gradient(120% 80% at 0% 0%, color-mix(in oklab, $s-primary, transparent 87%), transparent 56%), $s-page;",
 
 	// Level/role modifier → anchors. Levels (neutral elevations) use the shared
@@ -250,10 +263,11 @@ A.insertGlobalCss({
 	// overrides a component's default `.tonal`/`.outlined` (resetting both the
 	// anchors and the painted background).
 	".s-s.filled": "--s-fg:$s-a --s-bg:$s-b background:$s-bg;",
-	// Paint the brand sweep for a filled `.gradient` surface. Sits after the
-	// variant rules and is keyed on `:not(.tonal):not(.outlined)`, so those
-	// variants keep their solid-primary tint/edge.
-	".s-s.gradient:not(.tonal):not(.outlined)": "background: $s-gradient;",
+	// Paint the brand sweep for a filled `.gradient` surface — the compressed
+	// surface cut, not the full banner sweep. Sits after the variant rules and is
+	// keyed on `:not(.tonal):not(.outlined)`, so those variants keep their
+	// solid-primary tint/edge.
+	".s-s.gradient:not(.tonal):not(.outlined)": "background: $s-gradient-surface;",
 
 	// Contextual accent: the brand pop colour on neutral surfaces. Declared on the
 	// whole neutral group so re-entering a neutral surface under a coloured one