@gemboss/ui 0.1.0

package/src/shell.tsx

@@ -0,0 +1,212 @@
+"use client";
+
+/**
+ * The GemBoss shell as components: fixed 56px topbar, 240px rail, drawer at ≤760px.
+ *
+ * Every other surface in the fleet (gempress, gemcare, gemwatcher, content-radar…) used to rebuild
+ * this markup by hand from the class names in the exported CSS, and each copy drifted a little: a
+ * different hamburger, the selected pill missing because the item was not inside `.gnav-group`, a
+ * `<nav>` of buttons that a legacy `nav button {}` rule squashed to 60px. These components ARE the
+ * markup the CSS was written for, and the admin renders its own rail through them — so a change to
+ * the contract shows up in the admin first, not in a sibling repo weeks later.
+ *
+ * Styling is not here. It is `gemboss-ui.css` (tokens + kit + the shell extract), generated from the
+ * admin's own stylesheets by `apps/admin/scripts/export-ui-css.mjs`; the admin loads those sources
+ * directly. These components only emit classes.
+ *
+ * No router. `RailItem`/`RailSubItem` render an `<a>` unless given `as` — the admin passes
+ * `next/link`, a hash-routed SPA passes nothing. Every other prop is forwarded untouched.
+ */
+import React, { useEffect, useState } from "react";
+
+const cx = (...parts: Array<string | false | null | undefined>) => parts.filter(Boolean).join(" ");
+
+/** Own props + typed HTML attributes (so `onClick={(e) => …}` gets a MouseEvent, not `any`) + an
+ *  open index for whatever the `as` component takes (`prefetch`, `data-*`). */
+type Polymorphic<P> = P & { as?: React.ElementType; className?: string }
+  & Omit<React.AllHTMLAttributes<HTMLElement>, keyof P | "as" | "className">
+  & Record<string, unknown>;
+
+/** `div.gemboss-platform-shell`. `mobileNavOpen` is the ≤760px drawer; wider, nothing reads it. */
+export function Shell({ mobileNavOpen, className, children, ...rest }:
+  { mobileNavOpen?: boolean; className?: string; children?: React.ReactNode } & React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cx("gemboss-platform-shell", mobileNavOpen && "is-mobile-nav-open", className)} {...rest}>{children}</div>;
+}
+
+/** `header.gemboss-platform-topbar` — a three-column grid on desktop, one flex row at ≤760px. */
+export function Topbar({ className, children, ...rest }: React.HTMLAttributes<HTMLElement>) {
+  return <header className={cx("gemboss-platform-topbar", className)} {...rest}>{children}</header>;
+}
+
+/** The ≤760px hamburger. Hidden by the CSS on wider screens. */
+export function MobileMenuButton({ open, onToggle, labels = { open: "Open menu", close: "Close menu" }, ...rest }:
+  { open: boolean; onToggle: () => void; labels?: { open: string; close: string } } & React.ButtonHTMLAttributes<HTMLButtonElement>) {
+  return (
+    <button type="button" className="gemboss-mobile-menu-btn" aria-label={open ? labels.close : labels.open}
+            aria-expanded={open} onClick={onToggle} {...rest}>
+      <svg width="20" height="20" viewBox="0 0 20 20" aria-hidden="true">
+        <path d="M3 5.5h14M3 10h14M3 14.5h14" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" />
+      </svg>
+    </button>
+  );
+}
+
+/** The dimmed layer behind the open drawer; tapping it closes the drawer. */
+export function MobileNavBackdrop({ open, onClose, label = "Close menu" }:
+  { open: boolean; onClose: () => void; label?: string }) {
+  return (
+    <button type="button" className="gemboss-mobile-nav-backdrop" aria-label={label}
+            tabIndex={open ? 0 : -1} onClick={onClose} />
+  );
+}
+
+/** `nav.icon-nav`. */
+export function Rail({ label = "Main navigation", className, children, ...rest }:
+  { label?: string } & React.HTMLAttributes<HTMLElement>) {
+  return <nav className={cx("icon-nav", className)} aria-label={label} {...rest}>{children}</nav>;
+}
+
+/** The part of the rail that scrolls. */
+export function RailScroll({ children }: { children?: React.ReactNode }) {
+  return <div className="gnav-scroll">{children}</div>;
+}
+
+/** Pinned to the foot of the rail, below the scroll. */
+export function RailBottom({ children }: { children?: React.ReactNode }) {
+  return <div className="gnav-bottom">{children}</div>;
+}
+
+export function RailSep() {
+  return <div className="gnav-sep" />;
+}
+
+/**
+ * `div.gnav-group`. The selected PILL is defined only as
+ * `.gnav-group:not(.has-active-child) > .gnav-item.active` — an item outside a group gets the active
+ * text colour and no background. Wrap every top-level item in one (the admin does); set
+ * `hasActiveChild` when a sub-item is the real destination so the leaf carries the pill.
+ */
+export function RailGroup({ active, hasActiveChild, className, children }:
+  { active?: boolean; hasActiveChild?: boolean; className?: string; children?: React.ReactNode }) {
+  return <div className={cx("gnav-group", active && "active", hasActiveChild && "has-active-child", className)}>{children}</div>;
+}
+
+/**
+ * `.gnav-item`: icon + label (+ anything after, e.g. a count). Renders `<a>` by default; pass
+ * `as={Link}` for a router link or `as="button"` for an action. `aria-current="page"` follows
+ * `active` unless the caller sets it.
+ */
+export function RailItem({ as: Comp = "a", icon, label, active, className, children, ...rest }:
+  Polymorphic<{ icon?: React.ReactNode; label: React.ReactNode; active?: boolean; children?: React.ReactNode }>) {
+  return (
+    <Comp className={cx("gnav-item", active && "active", className)}
+          aria-current={active ? "page" : undefined} {...rest}>
+      <span className="gnav-ico">{icon}</span>
+      <span className="gnav-label">{label}</span>
+      {children}
+    </Comp>
+  );
+}
+
+/** `ul.gnav-sub` — a hub's children. */
+export function RailSub({ children }: { children?: React.ReactNode }) {
+  return <ul className="gnav-sub">{children}</ul>;
+}
+
+/** One `li` of `RailSub`. `soon` renders a disabled entry with a "Soon" tag instead of a link. */
+export function RailSubItem({ as: Comp = "a", active, soon, soonLabel = "Soon", className, children, ...rest }:
+  Polymorphic<{ active?: boolean; soon?: boolean; soonLabel?: string; children?: React.ReactNode }>) {
+  if (soon) return <li><span className="gnav-subitem is-soon">{children}<em>{soonLabel}</em></span></li>;
+  return (
+    <li>
+      <Comp className={cx("gnav-subitem", active && "active", className)}
+            aria-current={active ? "page" : undefined} {...rest}>{children}</Comp>
+    </li>
+  );
+}
+
+/** `.gemboss-platform-main`. `as="div"` when the pages render their own `<main>` — two nested
+ *  `<main>` elements are invalid HTML. */
+export function ShellMain({ as: Comp = "main", className, children, ...rest }:
+  Polymorphic<{ children?: React.ReactNode }>) {
+  return <Comp className={cx("gemboss-platform-main", className)} {...rest}>{children}</Comp>;
+}
+
+/**
+ * The whole frame for a surface that has no shell logic of its own (the admin composes the pieces
+ * above itself). Owns the drawer: open/close, Escape, and closing when a rail link is followed.
+ */
+/** What the assistant provider announces when a rail click opened its popup instead of navigating
+ *  (`dockedEvent` in ./assistant/provider — the same default). */
+export const ASSISTANT_DOCKED_EVENT = "gemboss:assistant-docked";
+
+export function AppShell({ brand, center, actions, rail, railBottom, railLabel, mainAs = "main", menuLabels,
+  drawerCloseEvent = ASSISTANT_DOCKED_EVENT, children }: {
+  /** Left of the topbar, after the hamburger. */
+  brand?: React.ReactNode;
+  /** Middle column of the topbar (search). */
+  center?: React.ReactNode;
+  /** Right column of the topbar. */
+  actions?: React.ReactNode;
+  /** Contents of the scrolling part of the rail. */
+  rail: React.ReactNode;
+  railBottom?: React.ReactNode;
+  railLabel?: string;
+  mainAs?: "main" | "div";
+  menuLabels?: { open: string; close: string };
+  /** A window event that closes the drawer. The rail's Assistant item can open the popup WITHOUT a
+   *  navigation (the provider intercepts the click and stops it), so "a followed link closes the
+   *  drawer" never fires, and on a phone the drawer stayed over the popup it had just opened —
+   *  measured on gemwatcher at 320 and 390, 28/09/2026. The admin closes its own drawer the same way. */
+  drawerCloseEvent?: string;
+  children?: React.ReactNode;
+}) {
+  const [open, setOpen] = useState(false);
+  useEffect(() => {
+    if (!open || !drawerCloseEvent) return;
+    const close = () => setOpen(false);
+    window.addEventListener(drawerCloseEvent, close);
+    return () => window.removeEventListener(drawerCloseEvent, close);
+  }, [open, drawerCloseEvent]);
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape") setOpen(false); };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open]);
+  // A followed link closes the drawer. Delegated, so the caller's items need no wiring.
+  const closeOnFollow = (e: React.MouseEvent) => {
+    if ((e.target as Element).closest?.(".gnav-item, .gnav-subitem")) setOpen(false);
+  };
+
+  return (
+    <Shell mobileNavOpen={open}>
+      <Topbar>
+        <div className="gemboss-topbar-start">
+          <MobileMenuButton open={open} onToggle={() => setOpen((o) => !o)} labels={menuLabels} />
+          {brand}
+        </div>
+        <div className="gemboss-topbar-center">{center}</div>
+        <div className="gemboss-topbar-end">{actions}</div>
+      </Topbar>
+      <Rail label={railLabel} onClick={closeOnFollow}>
+        <RailScroll>{rail}</RailScroll>
+        {railBottom ? <RailBottom>{railBottom}</RailBottom> : null}
+      </Rail>
+      <MobileNavBackdrop open={open} onClose={() => setOpen(false)} label={menuLabels?.close} />
+      <ShellMain as={mainAs}>{children}</ShellMain>
+    </Shell>
+  );
+}
+
+/** A small caps label over a run of rail items — how a rail with families of screens tells them
+ *  apart (gemwatcher: Nhịp / Thị trường / Trang thắng / Hệ). The admin rail does not use one. */
+export function RailHeading({ id, children }: { id?: string; children?: React.ReactNode }) {
+  return <div className="gnav-heading" id={id}>{children}</div>;
+}
+
+/** A count pill at the end of a `RailItem` (unread, drafts). Caps at 99+. */
+export function RailCount({ value, label }: { value: number; label?: string }) {
+  if (!value) return null;
+  return <span className="gnav-count" aria-label={label}>{value > 99 ? "99+" : value}</span>;
+}

package/src/ui.css

@@ -0,0 +1,403 @@
+/* ════════════════════════════════════════════════════════════════════════════
+   Tool/App UI kit — the shared primitive layer for the internal operator surfaces
+   (admin console, seller app chrome, theme-editor). ONE semantic token spine
+   (`--ui-*`) that every primitive reads, plus the primitive CSS itself.
+
+   Why this exists: buttons/cards/badges were forked into 4–8 hand-rolled class
+   families per surface, each re-deriving color/spacing/centering — so the same
+   primitive drifted (e.g. a link-button whose text wasn't vertically centered).
+   See docs/frontend-shared-system-plan.md.
+
+   The `--ui-*` layer is SEMANTIC and resolved per surface: components only read
+   `--ui-*`; each surface maps those to its own tokens (admin → `--adm-*` below),
+   so one <Button> looks native everywhere without hard-coding a palette.
+   ════════════════════════════════════════════════════════════════════════════ */
+
+:root {
+  --ui-surface: #ffffff;
+  /* --ui-* is a SEMANTIC layer resolved PER SURFACE — it references each surface's own base tokens
+     rather than guessing from the OS. The default (`:root`) maps onto the seller app's warm-ivory
+     `--gemboss-*` set; `.gemboss-admin-shell` below remaps onto the dark `--adm-*` set. Literal fallbacks
+     keep the kit usable if a surface's base stylesheet isn't loaded. This is the "unify under --ui-*"
+     backbone — one token spine, no duplicated palette. */
+  --ui-surface: var(--gemboss-surface, #ffffff);
+  --ui-surface-2: var(--gemboss-hover, #eceef2);
+  --ui-text: var(--gemboss-text, #1b1c1e);
+  --ui-text-muted: var(--gemboss-text-muted, #686b71);
+  --ui-border: var(--gemboss-divider, #e5e7ea);
+  --ui-accent: var(--gemboss-primary, #1b1c1e);
+  --ui-accent-hover: var(--gemboss-primary-dark, #000000);
+  --ui-accent-fg: #ffffff;
+  --ui-accent-soft: var(--gemboss-active-bg, #f0f1f4);   /* tinted bg for a selected/active state */
+  --ui-accent-strong: var(--gemboss-active-fg, #1b1c1e); /* readable accent text ON --ui-accent-soft */
+  --ui-text-strong: var(--gemboss-text-strong, #1b1c1e);
+  --ui-focus: var(--gemboss-primary, #1b1c1e);
+  --ui-radius-sm: 6px;
+  --ui-radius-md: 8px;
+  --ui-radius-lg: 12px;
+  --ui-space-1: 4px;
+  --ui-space-2: 8px;
+  --ui-space-3: 12px;
+  --ui-space-4: 16px;
+  --ui-control-h: 34px;
+  --ui-fs-body: 13px;
+  --ui-fs-caption: 12px;
+  /* Content column width for the seller app shell — ONE source of truth for every wide surface
+     right of the 240px sidebar (bare Page, .gemboss-w-dashboard, .gemboss-w-gallery, and the
+     navigation skeleton), so they cannot drift apart again. The /admin console is a SEPARATE
+     surface and still sets its own 1200px in admin/admin-shell.css; it does not read this token.
+     900px. Polaris' own cap is 998px — 41.375rem primary column + 20rem secondary + 1rem gutter,
+     read out of the installed @shopify/polaris stylesheet — and this sits deliberately BELOW it.
+
+     The reason is a measurement, not a preference about Shopify. The previous value was 1080/1040,
+     and moving to Polaris' 998 was the obvious "correct" answer, so that shipped first (#2250). Then
+     it turned out to be invisible: 1040 → 998 is 42px total, which is 21px of extra gutter per side.
+     Screenshotted side by side at 1440 on the same page seconds apart, the two rows were
+     indistinguishable, and Chris — who asked for this — could not see any change at all.
+
+     A cap only does its job if the breathing room it buys is legible. Measured gutters on
+     .Polaris-Page at 1440 beside the 240px sidebar:
+
+       1040px → 75 / 86      (before)
+        998px → 96 / 107     Polaris' number; +21px a side, not perceivable
+        960px → 115 / 126
+        900px → 145 / 156    +70px a side, roughly double the old gutter
+
+     900 is the first value where the column visibly stops leaning on the rail. The one cost, and it
+     was measured rather than guessed: card descriptions gain a line (Cart drawer 2 → 3). The 3-up
+     grid holds, and no width from 320 to 1920 overflows.
+
+     Still fixed px, no percentage, for the reason Polaris uses px: a % cap grows the reading measure
+     with the monitor (80% of 2560 is 2048px of line length). Responsiveness belongs to the padding
+     and to the secondary column dropping, not to the cap.
+
+     .gemboss-w-form stays 662px — that IS `.Polaris-Page--narrowWidth`, the primary column alone,
+     and a form is the one surface where Polaris' measure is about the input, not the page. */
+  --ui-content-max: 900px;
+}
+
+/* Admin console bridge: the black chrome defines `--adm-*`; remap `--ui-*` onto them so every
+   <Button>/<Select>/<Tag>/<Modal> inside .gemboss-admin-shell adopts the dark palette automatically. */
+.gemboss-admin-shell {
+  --ui-surface: var(--adm-surface);
+  --ui-surface-2: var(--adm-surface-2);
+  --ui-text: var(--adm-text);
+  --ui-text-muted: var(--adm-muted);
+  --ui-border: var(--adm-divider);
+  --ui-accent: var(--adm-accent);
+  --ui-accent-hover: var(--gemboss-primary-dark, #000000);
+  --ui-accent-fg: #ffffff;
+  --ui-accent-soft: var(--adm-accent-soft);
+  --ui-accent-strong: var(--adm-accent-fg);
+  --ui-text-strong: var(--adm-text-strong);
+  --ui-focus: var(--adm-accent);
+}
+
+/* ── Button ──────────────────────────────────────────────────────────────────
+   inline-flex + center so a <button> and an <a> render identically (anchors ignore
+   `height` as inline elements — the root cause of the misaligned link-buttons). */
+.ui-btn {
+  display: inline-flex; align-items: center; justify-content: center; gap: var(--ui-space-2);
+  height: var(--ui-control-h); padding: 0 var(--ui-space-4); box-sizing: border-box;
+  line-height: 1; white-space: nowrap; vertical-align: middle;
+  border-radius: var(--ui-radius-md); font-family: inherit; font-size: var(--ui-fs-body); font-weight: 550;
+  cursor: pointer; text-decoration: none; user-select: none;
+  border: 1px solid var(--ui-border); background: transparent; color: var(--ui-text);
+  transition: background .12s ease, border-color .12s ease;
+}
+.ui-btn:hover { background: var(--ui-surface-2); text-decoration: none; }
+.ui-btn:focus-visible { outline: 2px solid var(--ui-focus); outline-offset: 2px; }
+.ui-btn[disabled], .ui-btn[aria-disabled="true"] { opacity: .5; cursor: not-allowed; }
+.ui-btn--primary { background: var(--ui-accent); border-color: var(--ui-accent); color: var(--ui-accent-fg); }
+.ui-btn--primary:hover { background: var(--ui-accent-hover); border-color: var(--ui-accent-hover); }
+.ui-btn--ghost { border-color: transparent; background: transparent; color: var(--ui-text-muted); }
+.ui-btn--ghost:hover { background: var(--ui-surface-2); color: var(--ui-text); }
+.ui-btn--sm { height: 28px; padding: 0 var(--ui-space-3); font-size: var(--ui-fs-caption); }
+
+/* ── Card ──────────────────────────────────────────────────────────────────── */
+.ui-card {
+  background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius-lg);
+  padding: var(--ui-space-4); color: var(--ui-text);
+}
+.ui-card__title { font-size: 14px; font-weight: 600; margin: 0 0 var(--ui-space-2); }
+
+/* ── Select ──────────────────────────────────────────────────────────────────
+   Native <select> reskinned; custom caret as an inline SVG data-URI (caret color
+   uses the muted token via %-encoding fallback).
+   Its BOX is the text field's (29/09/2026, Chris): same --gemboss-field-* tokens for ground, line and
+   ink, same hover, same focus ring as `.gemboss-field`. Before, a grey --ui-surface-2 select stood next
+   to a bordered white field in the same form (gempress editor, admin forms), and `:focus` removed the
+   outline and only recoloured the border, so a keyboard user saw almost nothing. Height stays 36px
+   (--ui-control-h), because a select sits in toolbars beside 36px `.ui-btn`s. */
+.ui-select {
+  height: 36px; padding: 0 32px 0 12px; max-width: 100%;
+  background: var(--p-color-input-bg-surface, var(--gemboss-field-bg)) url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 20 20'><path fill='%239a9aa4' d='M5 7l5 5 5-5z'/></svg>") no-repeat right 10px center;
+  border: 1px solid var(--p-color-input-border, var(--gemboss-field-line)); border-radius: var(--ui-radius-md);
+  color: var(--p-color-text, var(--gemboss-field-ink)); font-family: inherit; font-size: var(--ui-fs-body); font-weight: 500;
+  appearance: none; -webkit-appearance: none; cursor: pointer;
+}
+.ui-select:hover:not(:disabled) {
+  border-color: var(--p-color-input-border-hover, var(--gemboss-field-line-hover));
+  background-color: var(--p-color-input-bg-surface-hover, var(--gemboss-field-bg-hover));
+}
+.ui-select:focus { outline: none; }
+.ui-select:focus-visible {
+  outline: 2px solid var(--p-color-border-focus, #005bd3); outline-offset: 1px;
+  border-color: var(--p-color-input-border-active, var(--gemboss-field-line-active));
+}
+.ui-select:disabled { opacity: .5; cursor: not-allowed; }
+.ui-select--slim { height: 30px; font-size: var(--ui-fs-caption); }
+
+/* ── Tag / Chip ──────────────────────────────────────────────────────────────
+   Small inline labels. `solid` = filled muted pill (was gemboss-vault-tag); `chip` =
+   bordered mono token (was gemboss-vault-chip). `accent` tone for the highlighted state. */
+.ui-tag {
+  display: inline-flex; align-items: center; gap: 6px;
+  font-size: 10px; font-weight: 600; letter-spacing: 0.03em; text-transform: uppercase;
+  padding: 1px 6px; border-radius: 6px; background: var(--ui-surface-2); color: var(--ui-text-muted);
+}
+.ui-tag--accent { background: var(--adm-accent-soft, rgba(20,22,26,.05)); color: var(--adm-accent-fg, var(--ui-accent)); }
+.ui-tag--chip {
+  text-transform: none; letter-spacing: 0; font-size: 11px; font-weight: 500;
+  padding: 2px 8px; background: transparent; border: 1px solid var(--ui-border);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+.ui-tag--chip.ui-tag--accent { color: var(--adm-accent-fg, var(--ui-accent)); border-color: var(--ui-accent); background: transparent; }
+
+/* ── Badge ────────────────────────────────────────────────────────────────────
+   Uppercase mono pill for a status/label (was gemboss-admin-storage-badge). */
+.ui-badge {
+  display: inline-flex; align-items: center;
+  font-size: 11px; font-weight: 700; letter-spacing: 0.03em; text-transform: uppercase;
+  padding: 1px 8px; border-radius: 6px; background: var(--ui-surface-2); color: var(--ui-text-muted);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+/* ── Modal ────────────────────────────────────────────────────────────────────
+   Rendered INLINE (not portaled): a portal escapes the .gemboss-admin-shell token
+   scope and would render light. Kept in-tree so --ui-* resolves to the surface. */
+.ui-overlay {
+  position: fixed; inset: 0; z-index: 500;
+  background: rgba(0, 0, 0, 0.6); backdrop-filter: blur(2px);
+  display: grid; place-items: center; padding: 20px;
+}
+.ui-modal {
+  width: min(460px, 100%);
+  background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: 16px;
+  box-shadow: var(--gemboss-shadow-overlay, 0 20px 60px rgba(0, 0, 0, 0.4)); overflow: hidden;
+}
+/* Head = title + the one close button every modal used to draw for itself. */
+.ui-modal__head {
+  display: flex; align-items: flex-start; gap: 16px;
+  padding: 16px 20px; border-bottom: 1px solid var(--ui-border);
+  font-size: 15px; font-weight: 620; color: var(--ui-text);
+}
+.ui-modal__title { min-width: 0; flex: 1 1 auto; }
+.ui-modal__close {
+  flex: 0 0 auto; display: inline-flex; align-items: center; justify-content: center;
+  width: 44px; height: 44px; margin: -8px -8px -8px 0;   /* a 44px target that does not grow the head */
+  border: 0; border-radius: var(--ui-radius-md, 8px); background: transparent;
+  color: var(--ui-text-muted); cursor: pointer;
+}
+.ui-modal__close svg { width: 20px; height: 20px; }
+.ui-modal__close:hover { background: var(--ui-surface-2); color: var(--ui-text); }
+.ui-modal__close:focus-visible { outline: 2px solid var(--ui-accent); outline-offset: -2px; }
+
+/* `size="lg"` — the screen-shaped dialog. Only the HOOK lives here: this sheet is imported by the
+   root layout, so every rule in it is paid on every screen, and the geometry of a dialog with one
+   consumer belongs in that consumer's chunk (see SettingsDialog.module.css). */
+.ui-modal--lg { position: relative; }
+
+.ui-textarea {
+  width: 100%; min-height: 96px; resize: vertical; box-sizing: border-box;
+  background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius-md);
+  padding: 12px; color: var(--ui-text); font-size: 14px; font-family: inherit; outline: none;
+}
+.ui-textarea:focus { border-color: var(--ui-accent); }
+
+/* ── Segmented control ────────────────────────────────────────────────────────
+   Grouped toggle: icon squares (.ui-seg button) or text tabs (.is-text). The
+   selected segment uses the accent-soft state. */
+.ui-seg { display: inline-flex; border: 1px solid var(--ui-border); border-radius: var(--ui-radius-md); overflow: hidden; }
+.ui-seg button {
+  display: inline-grid; place-items: center; width: 36px; height: 36px;
+  border: 0; background: transparent; color: var(--ui-text-muted); cursor: pointer; font-family: inherit;
+}
+.ui-seg button.is-text { width: auto; padding: 0 12px; font-size: var(--ui-fs-body); font-weight: 500; }
+.ui-seg button + button { border-left: 1px solid var(--ui-border); }
+.ui-seg button:hover { background: var(--ui-surface-2); color: var(--ui-text); }
+.ui-seg button.active { background: var(--ui-accent-soft); color: var(--ui-accent-strong); }
+.ui-seg svg { width: 16px; height: 16px; fill: currentColor; }
+
+/* ── Stat chip ────────────────────────────────────────────────────────────────
+   Count-led pill; clickable ones double as filters (active = accent-soft). */
+.ui-stats { display: flex; flex-wrap: wrap; gap: var(--ui-space-2); margin-bottom: 24px; }
+.ui-stat {
+  display: inline-flex; align-items: center; gap: var(--ui-space-2);
+  padding: 6px 12px; border-radius: 999px; font-family: inherit;
+  background: var(--ui-surface); border: 1px solid var(--ui-border);
+  font-size: var(--ui-fs-caption); color: var(--ui-text-muted);
+}
+.ui-stat b { color: var(--ui-text-strong); font-weight: 650; }
+.ui-stat.is-clickable { cursor: pointer; transition: border-color 0.14s ease, background-color 0.14s ease; }
+.ui-stat.is-clickable:hover { border-color: var(--ui-text-muted); background: var(--ui-surface-2); }
+.ui-stat.is-clickable.active { border-color: var(--ui-accent); background: var(--ui-accent-soft); color: var(--ui-accent-strong); }
+.ui-stat.is-clickable.active b { color: var(--ui-accent-strong); }
+
+/* ── Toast / notification bar ─────────────────────────────────────────────────
+   App-wide "done / failed" pill for async actions (delete/duplicate/publish…).
+   Polaris-style: dark pill, bottom-center, error variant in critical red. Lives
+   in <ToastProvider> (components/ui/Toast.tsx), portaled to <body>. */
+.gemboss-toast-viewport {
+  position: fixed; left: 50%; bottom: 24px; transform: translateX(-50%);
+  z-index: 2147483000; /* above every overlay/modal/popup */
+  display: flex; flex-direction: column; align-items: center; gap: 12px;
+  width: max-content; max-width: min(560px, calc(100vw - 32px)); pointer-events: none;
+}
+.gemboss-toast {
+  pointer-events: auto;
+  display: flex; align-items: center; gap: 12px;
+  min-width: 220px; max-width: 100%; padding: 12px 12px 12px 16px;
+  background: var(--ui-text-strong, #1a1917); color: #fff; border-radius: 12px;
+  font-size: var(--ui-fs-body, 13px); line-height: 1.4; font-weight: 500;
+  box-shadow: var(--gemboss-shadow-overlay, 0 8px 28px rgba(0, 0, 0, 0.24));
+  animation: gemboss-toast-in 240ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+.gemboss-toast.is-error { background: var(--gemboss-danger, #d72c0d); }
+.gemboss-toast-text { flex: 1 1 auto; min-width: 0; }
+.gemboss-toast-action {
+  flex: 0 0 auto; border: 0; background: transparent; color: #fff; cursor: pointer;
+  padding: 4px 8px; border-radius: 8px; font: inherit; font-weight: 650;
+  text-decoration: underline; text-underline-offset: 2px;
+  transition: background 0.14s ease;
+}
+.gemboss-toast-action:hover { background: rgba(255, 255, 255, 0.16); }
+.gemboss-toast-dismiss {
+  flex: 0 0 auto; display: inline-grid; place-items: center;
+  width: 24px; height: 24px; border: 0; border-radius: 8px; cursor: pointer;
+  background: rgba(255, 255, 255, 0.12); color: #fff;
+  transition: background 0.14s ease;
+}
+.gemboss-toast-dismiss:hover { background: rgba(255, 255, 255, 0.26); }
+.gemboss-toast-action:focus-visible,
+.gemboss-toast-dismiss:focus-visible { outline: 2px solid #fff; outline-offset: 2px; }
+@keyframes gemboss-toast-in {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+@media (prefers-reduced-motion: reduce) { .gemboss-toast { animation: none; } }
+
+/* ── The kit's controls under a thumb ─────────────────────────────────────────────────────────
+ * Measured by hit test on /admin/{theme-kernel,media,style-packs} at 390 and 1366 with a coarse
+ * pointer: segmented buttons 36x36, selects 30-36 tall, clickable stat tiles 29, the asset row's
+ * note button 30x30. §9.1 puts every one of them in the CONTROL tier (44px).
+ *
+ * HERE rather than in each surface's stylesheet, because this is the shared primitive layer — the
+ * same reason the kit exists at all. The admin console and the seller app both read it.
+ *
+ * `pointer: coarse` only: a mouse keeps the density these surfaces were designed at. Growing a box
+ * for every pointer is what #2147 did to a working width.
+ */
+@media (pointer: coarse) {
+  /* NOT `.ui-textarea`: it already declares `min-height: 96px` earlier in this file, so adding it to
+     a 44px group LOWERS it — same specificity, later line. The note dialog's box would have gone from
+     96 to ~58 on every touch device, inside a block whose whole point is bigger targets.
+     NOT `.ui-btn--sm` either: `min-height` always beats `height`, so a 44px floor voids the compact
+     variant — including four of them on the seller's own /app/settings/store. A density variant is a
+     decision, not an oversight; it gets its own measurement pass or none. */
+  .ui-btn:not(.ui-btn--sm),
+  .ui-stat.is-clickable,
+  .ui-seg button { min-height: 44px; }
+  /* A clickable stat whose label is one short token ("7d" on /admin/gem-intelligence) measured 40x44
+     in the 13/09/2026 sweep: the height floor held, the width did not. */
+  .ui-stat.is-clickable { min-width: 44px; justify-content: center; }
+  /* `--slim` is a second single class and lands later in this file, so it would win on order over a
+     bare `.ui-select`. Doubled here to decide it on specificity instead. */
+  .ui-select.ui-select,
+  .ui-select--slim.ui-select--slim { min-height: 44px; }
+  /* The icon-only segment is 36 WIDE as well — a target is an area. */
+  .ui-seg button { min-width: 44px; }
+}
+
+/* ── Skeleton ─────────────────────────────────────────────────────────────────
+   Vạch xám giữ chỗ cho nội dung chưa về. Ánh sáng chạy qua là gợi ý "đang chờ", không phải trang
+   trí — nên nó tắt hẳn với `prefers-reduced-motion`, giữ nguyên vạch tĩnh. */
+.ui-skeleton { display: flex; flex-direction: column; gap: var(--ui-space-2); }
+.ui-skeleton__line {
+  display: block; height: 12px; border-radius: 6px;
+  background: linear-gradient(90deg, var(--ui-surface-2) 25%, var(--ui-border) 37%, var(--ui-surface-2) 63%);
+  background-size: 400% 100%;
+  animation: ui-skeleton-sheen 1.4s ease-in-out infinite;
+}
+@keyframes ui-skeleton-sheen { 0% { background-position: 100% 50%; } 100% { background-position: 0 50%; } }
+@media (prefers-reduced-motion: reduce) {
+  .ui-skeleton__line { animation: none; background: var(--ui-surface-2); }
+}
+/* Nhãn cho trình đọc màn hình — thứ `<p>Loading…</p>` cũ vốn có và một khối hình thuần sẽ mất. */
+.ui-sr-only {
+  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+  overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0;
+
+}
+
+/* ── Tabs · Table · Empty state ───────────────────────────────────────────────
+   Plain-CSS primitives for surfaces that are NOT React (gemcare's vanilla dashboard reads this
+   file through `npm run export:ui-css`). The React app has Polaris <Tabs>/<DataTable>/<EmptyState>
+   for these; nothing in apps/admin uses the classes below, and they restyle no existing component.
+   Only `--ui-*` / `--gemboss-*` tokens, so the dark `.gemboss-admin-shell` bridge applies too.
+
+   Tabs: `<div class="ui-tabs" role="tablist"><button role="tab" aria-selected="true">…` — the
+   selected state IS `aria-selected`, so what a screen reader announces and what is painted cannot
+   disagree. 44px under EVERY pointer (§9.1 control tier), not only coarse: tabs sit 4px apart, and
+   that gap is only acceptable between targets that are already 44px. */
+.ui-tabs {
+  display: flex; gap: var(--ui-space-1); border-bottom: 1px solid var(--ui-border);
+  overflow-x: auto; scrollbar-width: none;
+}
+.ui-tabs > button {
+  position: relative; flex: 0 0 auto; display: inline-flex; align-items: center; gap: var(--ui-space-2);
+  min-height: 44px; padding: 0 var(--ui-space-3); border: 0; background: transparent; cursor: pointer;
+  border-radius: var(--ui-radius-sm) var(--ui-radius-sm) 0 0;
+  font-family: inherit; font-size: var(--gemboss-fs-body); font-weight: 500; white-space: nowrap;
+  color: var(--ui-text-muted);
+  transition: color var(--gemboss-transition-fast) ease, background-color var(--gemboss-transition-fast) ease;
+}
+.ui-tabs > button:hover { color: var(--ui-text); background: var(--ui-surface-2); }
+.ui-tabs > button:focus-visible { outline: 2px solid var(--ui-focus); outline-offset: -2px; }
+.ui-tabs > button[aria-selected="true"] { color: var(--ui-text-strong); font-weight: 600; }
+.ui-tabs > button[aria-selected="true"]::after {
+  content: ""; position: absolute; left: var(--ui-space-3); right: var(--ui-space-3); bottom: 0;
+  height: 2px; border-radius: var(--gemboss-radius-full); background: var(--ui-accent);
+}
+.ui-tabs > button:disabled { opacity: .5; cursor: not-allowed; }
+
+/* Table: wrap it — `<div class="ui-table-wrap"><table class="ui-table">` — so a wide table scrolls
+   inside its card instead of pushing the page sideways at 320px. Numeric cells take `.is-num`:
+   right-aligned tabular figures, so a column of numbers lines up digit for digit. */
+.ui-table-wrap {
+  overflow-x: auto; max-width: 100%;
+  background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius-lg);
+}
+.ui-table { width: 100%; border-collapse: collapse; font-size: var(--gemboss-fs-body); color: var(--ui-text); }
+.ui-table th,
+.ui-table td {
+  padding: var(--ui-space-2) var(--ui-space-3); text-align: left; vertical-align: middle;
+  border-bottom: 1px solid var(--ui-border);
+}
+.ui-table th {
+  font-size: var(--gemboss-fs-caption); font-weight: 600; color: var(--ui-text-muted); white-space: nowrap;
+}
+.ui-table tbody tr:last-child > td { border-bottom: 0; }
+.ui-table tbody tr:hover { background: var(--ui-surface-2); }
+.ui-table .is-num { text-align: right; font-variant-numeric: tabular-nums; white-space: nowrap; }
+
+/* Empty state: `<div class="ui-empty"><p class="ui-empty__title">…</p><p class="ui-empty__body">…</p>
+   <button class="ui-btn">…</button></div>`. Says what is missing and what to do next. */
+.ui-empty {
+  display: flex; flex-direction: column; align-items: center; justify-content: center; gap: var(--ui-space-2);
+  padding: var(--ui-space-4); padding-block: 40px; text-align: center;
+  color: var(--ui-text-muted); font-size: var(--gemboss-fs-body);
+}
+.ui-empty__title { margin: 0; font-size: var(--gemboss-fs-h3); font-weight: 600; color: var(--ui-text-strong); }
+.ui-empty__body { margin: 0; max-width: 48ch; line-height: 1.5; }
+.ui-empty > .ui-btn { margin-top: var(--ui-space-2); }