@gemboss/ui 0.6.5 → 0.7.1

package/src/kit-plain.js

@@ -85,7 +85,7 @@
       if (o.onClose) o.onClose(value);
     }
     function onKey(e) {
-      if (MODALS[MODALS.length - 1] !== m) return;
+      if (e === opening || MODALS[MODALS.length - 1] !== m) return;
       // Escape while an IME is composing (zh, ja, vi telex) cancels the composition, not the dialog.
       if (e.key === "Escape") { if (e.isComposing || e.keyCode === 229) return; e.preventDefault(); m.close(null); return; }
       if (e.key !== "Tab") return;
@@ -103,13 +103,26 @@
     overlay.addEventListener("click", function (e) { if (e.target === overlay && downOnBackdrop) m.close(null); downOnBackdrop = false; });
     var x = panel.querySelector(".ui-modal__head .ui-modal__close");
     if (x) x.onclick = function () { m.close(null); };
-    // On the NEXT task, not now: a popup opened from a keydown handler (content-radar's composer asks "close without
-    // saving?" on Escape) would otherwise receive that same Escape when it bubbles up to window, and close itself at
-    // once (0.5.1). A listener added during a dispatch still runs if its target has not been reached yet.
-    setTimeout(function () { if (MODALS.indexOf(m) >= 0) addEventListener("keydown", onKey); }, 0);
+    // Keys belong to the popup from the moment it opens (0.6.4). 0.5.1 attached this listener a task later, and on a busy
+    // page the browser runs input before timers: Escape or Tab pressed right after opening was lost, the popup stayed open
+    // or Tab left the trap (CI lost "stacked popups" three runs in a row, 03/10/2026). The one key it must NOT take is the
+    // keydown that is opening it: a popup opened from a keydown handler (content-radar's composer asks "close without
+    // saving?" on Escape) would receive that same Escape when it bubbles up to window — a listener added during a dispatch
+    // still runs if its target has not been reached yet — and close at once. `window.event` is that event while it runs.
+    var opening = window.event;
+    addEventListener("keydown", onKey);
     if (!MODALS.length) savedOverflow = document.body.style.overflow;
     MODALS.push(m);
-    document.body.append(overlay);
+    // Inside the top open MODAL <dialog>, not <body> (0.6.9, 03/10/2026). A `<dialog class="ui-modal">` opened with
+    // showModal() sits in the top layer and makes the rest of the page inert, so a confirm appended to <body> drew
+    // BEHIND it and could not be clicked: GemCommunity's lesson editor asked "Discard changes?" into a dead layer and
+    // had to move the overlay by hand. Appended inside that dialog, the overlay rides the top layer with it.
+    var host = document.body;
+    try {
+      var open = document.querySelectorAll("dialog[open]");
+      for (var di = open.length - 1; di >= 0; di--) { if (open[di].matches(":modal")) { host = open[di]; break; } }
+    } catch (_) { /* a browser without :modal keeps <body> */ }
+    host.append(overlay);
     document.body.style.overflow = "hidden";
     setTimeout(function () { (panel.querySelector("[autofocus]") || panel).focus(); }, 0);
     return m;

package/src/portal.css

@@ -0,0 +1,187 @@
+/* ═══ Portal pieces — @gemboss/ui 0.7.0 (04/10/2026) ════════════════════════════════════════════
+   TopbarNav, Avatar, Leaderboard, Podium (portal.tsx), SearchDialog (dialog.tsx), ThemeToggle and the
+   dark palette (theme.tsx). Tokens only: every colour comes from --gemboss-* / --ui-*, so the dark
+   palette at the end reaches these too. */
+
+/* ── TopbarNav: section tabs in the topbar, after the brand (Featurebase's "Feedback · Roadmap"). The
+   active tab is underlined on the topbar's bottom edge. 44px targets under a finger, 36 under a mouse
+   (the kit's two-tier rule, as TopbarSearch). A phone scrolls the row sideways rather than wrapping it. */
+.gb-topnav { display: flex; align-items: stretch; gap: 4px; min-width: 0; height: 100%; margin-left: 12px; padding-left: 12px;
+  border-left: 1px solid var(--gemboss-divider); overflow-x: auto; scrollbar-width: none; }
+.gb-topnav::-webkit-scrollbar { display: none; }
+/* Each tab is as tall as the topbar, so its underline lands on the topbar's bottom edge. */
+.gb-topnav-link { position: relative; display: inline-flex; align-items: center; align-self: stretch; flex: 0 0 auto; min-height: 36px; padding: 0 10px;
+  border-radius: 8px; color: var(--gemboss-text-muted); font-size: 14px; font-weight: 520; text-decoration: none; white-space: nowrap; }
+.gb-topnav-link:hover { color: var(--gemboss-text-strong); background: var(--gemboss-hover); }
+.gb-topnav-link:focus-visible { outline: 2px solid var(--gemboss-accent); outline-offset: -2px; }
+.gb-topnav-link[aria-current="page"] { color: var(--gemboss-text-strong); font-weight: 640; }
+.gb-topnav-link[aria-current="page"]::after { content: ""; position: absolute; left: 10px; right: 10px; bottom: -1px; height: 2px;
+  border-radius: 2px; background: var(--gemboss-text-strong); }
+@media (pointer: coarse) { .gb-topnav-link { min-height: 44px; } }
+/* A topbar that carries tabs has no centre search: brand + tabs take the room, actions sit right. The
+   default columns keep 280–560px for a search box, which cut "Roadmap" to "Ro" and the brand to "G…". */
+.gemboss-platform-topbar:has(.gb-topnav):has(> .gemboss-topbar-center:empty) { grid-template-columns: minmax(0, 1fr) auto; }
+.gemboss-platform-topbar:has(.gb-topnav) > .gemboss-topbar-center:empty { display: none; }
+.gemboss-topbar-start:has(.gb-topnav) { min-width: 0; height: 100%; }
+.gemboss-topbar-start:has(.gb-topnav) > .gb-brand { flex: 0 0 auto; }
+@media (max-width: 760px) { .gb-topnav { margin-left: 8px; padding-left: 8px; } .gb-topnav-link { min-height: 44px; padding: 0 8px; }
+}
+.gb-topnav-row { display: flex; align-items: stretch; gap: 4px; min-width: 0; height: 100%; }
+/* The folded form (under 600px): one button naming the open tab, the tabs in a popover under it. */
+.gb-topnav-fold { display: none; position: relative; align-self: stretch; }
+.gb-topnav-fold > summary { list-style: none; cursor: pointer; gap: 4px; height: 100%; }
+.gb-topnav-fold > summary::-webkit-details-marker { display: none; }
+.gb-topnav-fold-btn[aria-current="page"]::after { display: none; }
+.gb-topnav-chevron { flex: 0 0 auto; transition: transform .15s ease; }
+.gb-topnav-fold[open] .gb-topnav-chevron { transform: rotate(180deg); }
+.gb-topnav-pop { position: fixed; top: 56px; left: 8px; min-width: 200px; padding: 6px; display: grid; gap: 2px; z-index: 60; }
+.gb-topnav-item { display: flex; align-items: center; min-height: 44px; padding: 0 12px; border-radius: 8px;
+  color: var(--gemboss-text); font-size: 14px; font-weight: 520; text-decoration: none; }
+.gb-topnav-item:hover { background: var(--gemboss-hover); }
+.gb-topnav-item:focus-visible { outline: 2px solid var(--gemboss-accent); outline-offset: -2px; }
+.gb-topnav-item[aria-current="page"] { color: var(--gemboss-active-fg); background: var(--gemboss-active-bg); font-weight: 640; }
+@media (max-width: 600px) {
+  .gb-topnav { overflow: visible; }
+  .gb-topnav-row { display: none; }
+  .gb-topnav-fold { display: flex; }
+}
+@media (prefers-reduced-motion: reduce) { .gb-topnav-chevron { transition: none; } }
+
+/* ── Avatar: picture or initials on one of eight tones picked from the name. */
+.gb-avatar { display: inline-flex; align-items: center; justify-content: center; flex: 0 0 auto; border-radius: 50%; overflow: hidden;
+  font-weight: 700; line-height: 1; letter-spacing: .01em; user-select: none; }
+.gb-avatar--24 { width: 24px; height: 24px; font-size: 9.5px; }
+.gb-avatar--32 { width: 32px; height: 32px; font-size: 11px; }
+.gb-avatar--40 { width: 40px; height: 40px; font-size: 13px; }
+.gb-avatar--56 { width: 56px; height: 56px; font-size: 18px; }
+.gb-avatar-img { width: 100%; height: 100%; object-fit: cover; display: block; }
+/* One hue per tone; the disc and the initials are both mixed from it (light: dark initials on a pale
+   disc; dark: light initials on a deep disc). portal.test.tsx checks every tone clears 4.5:1 in both. */
+.gb-avatar[data-tone] { background: color-mix(in srgb, var(--gb-tone) 16%, #ffffff); color: color-mix(in srgb, var(--gb-tone) 70%, #000000); }
+.gb-avatar[data-tone="0"] { --gb-tone: #5661f5; }
+.gb-avatar[data-tone="1"] { --gb-tone: #0a8f6a; }
+.gb-avatar[data-tone="2"] { --gb-tone: #c26a04; }
+.gb-avatar[data-tone="3"] { --gb-tone: #db2777; }
+.gb-avatar[data-tone="4"] { --gb-tone: #0891b2; }
+.gb-avatar[data-tone="5"] { --gb-tone: #7c3aed; }
+.gb-avatar[data-tone="6"] { --gb-tone: #dc2626; }
+.gb-avatar[data-tone="7"] { --gb-tone: #6b7280; }
+
+/* ── Leaderboard: medals 1–3, then the rank; avatar, name, count; the leader's count in gold. Rows are
+   44px, so neighbours need no gap (§9.1). */
+.gb-leaderboard { display: grid; gap: 6px; min-width: 0; }
+.gb-leaderboard-title { margin: 0; display: flex; align-items: center; gap: 6px; font-size: 12px; font-weight: 650; letter-spacing: .04em;
+  text-transform: uppercase; color: var(--gemboss-text-muted); }
+.gb-leaderboard-caption { margin: -2px 0 2px; font-size: 12px; color: var(--gemboss-text-muted); }
+.gb-leaderboard-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 0; }
+.gb-leaderboard-link { display: flex; align-items: center; gap: 10px; min-height: 44px; padding: 0 6px; border-radius: 8px;
+  color: var(--gemboss-text); text-decoration: none; }
+a.gb-leaderboard-link:hover { background: var(--gemboss-hover); }
+a.gb-leaderboard-link:focus-visible { outline: 2px solid var(--gemboss-accent); outline-offset: -2px; }
+.gb-leaderboard-rank { width: 20px; flex: 0 0 auto; text-align: center; font-size: 15px; line-height: 1; }
+.gb-leaderboard-rank.is-number { font-size: 12px; font-weight: 700; color: var(--gemboss-text-muted); font-variant-numeric: tabular-nums; }
+.gb-leaderboard-name { flex: 1 1 auto; min-width: 0; font-size: 13px; font-weight: 560; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.gb-leaderboard-value { flex: 0 0 auto; font-size: 13px; font-weight: 650; color: var(--gemboss-text-muted); font-variant-numeric: tabular-nums; }
+.gb-leaderboard-row.is-first .gb-leaderboard-value { color: #8a5a00; font-weight: 750; }
+.gb-leaderboard-all { justify-self: center; display: inline-flex; align-items: center; min-height: 24px; font-size: 12px; font-weight: 600;
+  color: var(--gemboss-text-muted); text-decoration: none; }
+.gb-leaderboard-all:hover { color: var(--gemboss-text-strong); text-decoration: underline; }
+
+/* ── Podium: second · first · third, the first raised. */
+.gb-podium { list-style: none; margin: 0; padding: 0; display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; align-items: end; }
+.gb-podium-link { display: grid; justify-items: center; gap: 6px; padding: 14px 8px; border: 1px solid var(--gemboss-divider); border-radius: 12px;
+  background: var(--gemboss-surface); color: var(--gemboss-text); text-decoration: none; text-align: center; }
+a.gb-podium-link:hover { background: var(--gemboss-hover); }
+.gb-podium-slot { min-width: 0; }
+.gb-podium-slot--1 .gb-podium-link { padding-top: 22px; padding-bottom: 20px; border-color: color-mix(in srgb, #d4a017 45%, var(--gemboss-divider)); }
+.gb-podium-slot--2 .gb-podium-link { padding-bottom: 12px; }
+.gb-podium-slot--3 .gb-podium-link { padding-bottom: 8px; }
+.gb-podium-medal { font-size: 22px; line-height: 1; }
+.gb-podium-name { max-width: 100%; font-size: 13px; font-weight: 620; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.gb-podium-value { font-size: 15px; font-weight: 750; font-variant-numeric: tabular-nums; }
+.gb-podium-slot--1 .gb-podium-value { color: #8a5a00; }
+.gb-podium-unit { font-size: 11px; font-weight: 500; color: var(--gemboss-text-muted); }
+
+/* ── SearchDialog: the topbar's search button, and the popup (640 wide, near the top, like Featurebase's). */
+.gb-search-trigger, .gb-theme-toggle { display: inline-flex; align-items: center; justify-content: center; width: 36px; height: 36px; flex: 0 0 auto;
+  border: 0; border-radius: 8px; background: transparent; color: var(--gemboss-text-muted); cursor: pointer; }
+.gb-search-trigger:hover, .gb-theme-toggle:hover { background: var(--gemboss-hover); color: var(--gemboss-text-strong); }
+.gb-search-trigger:focus-visible, .gb-theme-toggle:focus-visible { outline: 2px solid var(--gemboss-accent); outline-offset: -2px; }
+@media (pointer: coarse), (max-width: 760px) { .gb-search-trigger, .gb-theme-toggle { width: 44px; height: 44px; } }
+dialog.ui-modal.gb-search { width: min(640px, 100%); margin-top: 8vh; max-height: min(560px, calc(100dvh - 16vh)); }
+.gb-search-box { position: relative; display: flex; align-items: center; border-bottom: 1px solid var(--ui-border); }
+.gb-search-icon { position: absolute; left: 18px; color: var(--ui-text-muted); pointer-events: none; }
+.gb-search-input { flex: 1 1 auto; min-width: 0; height: 52px; padding: 0 18px 0 46px; border: 0; background: transparent; color: var(--ui-text);
+  font: inherit; font-size: 15px; outline: none; }
+.gb-search-input::-webkit-search-cancel-button { display: none; }
+.gb-search-results { flex: 1 1 auto; min-height: 0; overflow: auto; padding: 8px; }
+.gb-search-section + .gb-search-section { margin-top: 8px; }
+.gb-search-section-title { padding: 6px 10px; font-size: 12px; font-weight: 600; color: var(--ui-text-muted); }
+.gb-search-item { display: grid; gap: 2px; min-height: 44px; align-content: center; padding: 6px 10px; border-radius: 8px; color: var(--ui-text); text-decoration: none; }
+.gb-search-item.is-active { background: var(--ui-surface-2); }
+.gb-search-item-title { font-size: 14px; font-weight: 520; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.gb-search-item-meta { display: flex; gap: 8px; align-items: center; font-size: 12px; color: var(--ui-text-muted); }
+.gb-search-empty { margin: 0; padding: 18px 18px 0; font-size: 13px; color: var(--ui-text-muted); }
+.gb-search-empty:empty { padding: 0; }
+.gb-search-foot { display: flex; gap: 16px; justify-content: flex-end; padding: 8px 14px; border-top: 1px solid var(--ui-border);
+  font-size: 12px; color: var(--ui-text-muted); }
+@media (max-width: 760px) { dialog.ui-modal.gb-search { margin-top: 12px; } .gb-search-foot { display: none; } }
+
+/* ── Dark palette. `ThemeToggle` / `themeScript` set data-theme on <html>; a surface without them stays
+   light. Only colours change: the components above and every kit class read these tokens. */
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  --gemboss-primary: #f2f3f5;
+  --gemboss-primary-dark: #ffffff;
+  --gemboss-primary-soft: #23242a;
+  --gemboss-on-primary: #0d0d12;
+  --gemboss-accent: #7c84ff;
+  --gemboss-accent-strong: #a3a9ff;
+  --gemboss-accent-soft: #1f2140;
+  --gemboss-text-strong: #f2f3f5;
+  --gemboss-text: #e3e4e8;
+  --gemboss-text-muted: #9a9ca6;
+  --gemboss-surface: #16171d;
+  --gemboss-canvas: #0d0d12;
+  --gemboss-app-bg: #0d0d12;
+  --gemboss-rail-bg: #0d0d12;
+  --gemboss-panel-bg: #16171d;
+  --gemboss-topbar-bg: rgba(13, 13, 18, 0.96);
+  --gemboss-nav-bg: #0d0d12;
+  --gemboss-nav-hover: rgba(255, 255, 255, 0.06);
+  --gemboss-divider: #2a2b33;
+  --gemboss-divider-soft: #22232a;
+  --gemboss-hover: #22232b;
+  --gemboss-active-bg: #262833;
+  --gemboss-active-fg: #f2f3f5;
+  --gemboss-field-bg: #121318;
+  --gemboss-field-bg-hover: #17181e;
+  --gemboss-field-ink: #e3e4e8;
+  --gemboss-field-placeholder: #8a8c96;
+  --gemboss-field-line: #3a3c46;
+  --gemboss-field-line-hover: #50525e;
+  --gemboss-field-line-active: #c9cbd3;
+  --gemboss-chip-ink: #d6d8de;
+  --gemboss-chip-line: #3a3c46;
+  --gemboss-chip-line-hover: #50525e;
+  --gemboss-chip-bg-hover: #22232b;
+  --gemboss-success: #34c38f;
+  --gemboss-success-strong: #5fd6a8;
+  --gemboss-success-soft: #13291f;
+  --gemboss-success-border: #22533e;
+  --gemboss-warning: #e0b341;
+  --gemboss-warning-soft: #2b2412;
+  --gemboss-warning-border: #5a4a1d;
+  --gemboss-danger: #ff6b5a;
+  --gemboss-danger-strong: #ff8a7c;
+  --gemboss-danger-soft: #2e1714;
+  --gemboss-danger-border: #5c2a24;
+  --ui-accent-fg: #0d0d12;
+  --ui-warning-fg: #e8c063;
+  --gb-brand-ink: #f2f3f5;
+}
+/* Avatar initials in dark: the tone's light end, so the text clears 4.5:1 on its tinted disc. */
+:root[data-theme="dark"] .gb-avatar[data-tone] { background: color-mix(in srgb, var(--gb-tone) 30%, #16171d); color: color-mix(in srgb, var(--gb-tone) 35%, #ffffff); }
+:root[data-theme="dark"] body { background: var(--gemboss-app-bg); color: var(--gemboss-text); }
+:root[data-theme="dark"] .gb-leaderboard-row.is-first .gb-leaderboard-value,
+:root[data-theme="dark"] .gb-podium-slot--1 .gb-podium-value { color: #e0b341; }

package/src/portal.tsx

@@ -0,0 +1,161 @@
+/**
+ * Pieces of a public portal — @gemboss/ui (04/10/2026).
+ *
+ * GemFeedback (feedback.gemboss.ai) copies the layout of the GemPages Featurebase board, and
+ * GemCommunity has drawn the same "top people" list by hand since its sidebar was built (Chris
+ * 04/10/2026: "leader board … cần đồng bộ giữa gemcommunity và gemfeedback và chuẩn hoá nó vào gemboss
+ * ui … có huy chương"). One owner for each:
+ *
+ * - `TopbarNav`: the section tabs INSIDE the topbar, beside the brand (Featurebase: "Feedback ·
+ *   Roadmap · Changelog"), instead of a second row under it. Chris: "đưa feedback roadmap lên menu
+ *   top bar để tiết kiệm không gian".
+ * - `Avatar`: a person's picture, or their initials on a tone picked from their name (the same name
+ *   always gets the same tone, so a list of people reads as people, not a column of grey dots).
+ * - `Leaderboard`: medals for the first three, then the rank, the avatar, the name and the count; the
+ *   leader's count in gold. GemCommunity's "Top contributors", GemFeedback's "Most helpful".
+ * - `Podium`: the first three as a podium (GemCommunity's leaderboard page), second · first · third.
+ *
+ * Server components: no state, no hooks. Links are `<a>` unless a router link is passed as `as`.
+ */
+import React from "react";
+import { initialsOf } from "./initials";
+
+type LinkLike = React.ElementType;
+const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
+
+export type TopbarNavItem = { href: string; label: React.ReactNode; active?: boolean };
+
+/**
+ * The section tabs in the topbar's start column, after the brand. The active tab carries aria-current.
+ *
+ * Under 600px the row does not fit beside the brand and the topbar's actions (measured at 390: room for
+ * about 180px, three tabs need 250), and a row that scrolls sideways hides the tabs past the edge with no
+ * sign they are there. There the tabs fold into one button naming the open tab, and a list under it, as
+ * Featurebase's board does on a phone. A <details>, so it opens without JavaScript; keyed by the active
+ * tab, so following a link (a client-side navigation keeps the element) closes it.
+ */
+export function TopbarNav({ items, as: L = "a", label = "Sections", className }: {
+  items: TopbarNavItem[]; as?: LinkLike; label?: string; className?: string;
+}) {
+  const current = items.find((it) => it.active) ?? items[0];
+  const links = (cls: string) => items.map((it) => (
+    <L key={it.href} href={it.href} className={cls} aria-current={it.active ? "page" : undefined}>{it.label}</L>
+  ));
+  return (
+    <nav className={cx("gb-topnav", className)} aria-label={label}>
+      <div className="gb-topnav-row">{links("gb-topnav-link")}</div>
+      {current ? (
+        <details className="gb-topnav-fold" key={current.href}>
+          <summary className="gb-topnav-link gb-topnav-fold-btn" aria-current="page">
+            {current.label}
+            <svg className="gb-topnav-chevron" width="12" height="12" viewBox="0 0 12 12" aria-hidden="true" focusable="false">
+              <path d="M3 4.5 6 7.5 9 4.5" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
+            </svg>
+          </summary>
+          <div className="gb-topnav-pop gemboss-popover-surface">{links("gb-topnav-item")}</div>
+        </details>
+      ) : null}
+    </nav>
+  );
+}
+
+/** Eight tones, picked by a hash of the name: stable across pages and renders. */
+export function avatarTone(name: string): number {
+  let h = 0;
+  for (const ch of name) h = (h * 31 + ch.codePointAt(0)!) >>> 0;
+  return h % 8;
+}
+
+export type AvatarSize = 24 | 32 | 40 | 56;
+// Whole class names, not `gb-avatar--${size}`: the admin's orphan-class gate reads markup for classes,
+// and an interpolated stem exempts everything under it from that check.
+const AVATAR_SIZE: Record<AvatarSize, string> = { 24: "gb-avatar--24", 32: "gb-avatar--32", 40: "gb-avatar--40", 56: "gb-avatar--56" };
+
+/** A person: their picture when there is one, else their initials (the account chip's rule). */
+export function Avatar({ name, src, size = 24, className }: { name: string; src?: string | null; size?: AvatarSize; className?: string }) {
+  return (
+    <span className={cx("gb-avatar", AVATAR_SIZE[size], className)} data-tone={avatarTone(name)} aria-hidden="true">
+      {src ? <img className="gb-avatar-img" src={src} alt="" loading="lazy" width={size} height={size} /> : initialsOf(name)}
+    </span>
+  );
+}
+
+export type LeaderRow = { key: string | number; name: string; value: number; avatar?: string | null; href?: string };
+
+const MEDALS = ["🥇", "🥈", "🥉"];
+const PODIUM_SLOT = ["gb-podium-slot--1", "gb-podium-slot--2", "gb-podium-slot--3"];
+
+/**
+ * A ranked list of people. Rows are links when they carry `href`; `unit` is read after the count by
+ * screen readers ("163 votes") and can be shown with `showUnit`. Empty → nothing (a "top" list of
+ * zeros looks dead; GemCommunity hides it the same way).
+ */
+export function Leaderboard({ title, caption, rows, unit, showUnit = false, viewAll, as: L = "a", className, headingLevel = 2, id }: {
+  title: React.ReactNode; caption?: React.ReactNode; rows: LeaderRow[]; unit?: string; showUnit?: boolean;
+  viewAll?: { href: string; label: React.ReactNode }; as?: LinkLike; className?: string; headingLevel?: 2 | 3;
+  /** The heading's id. Pass one when two leaderboards share a page or the title is not plain text. */
+  id?: string;
+}) {
+  if (!rows.length) return null;
+  const H = `h${headingLevel}` as "h2" | "h3";
+  // From the title's letters (any script) and a hash of it, so "Most helpful" and a Vietnamese or
+  // Chinese title each get their own; two boards with the same title need `id`.
+  const text = typeof title === "string" ? title : "leaderboard";
+  let h = 0;
+  for (const ch of text) h = (h * 31 + ch.codePointAt(0)!) >>> 0;
+  const headingId = id ?? `gb-lb-${text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-|-$/g, "")}-${h.toString(36)}`;
+  return (
+    <section className={cx("gb-leaderboard", className)} aria-labelledby={headingId}>
+      <H className="gb-leaderboard-title" id={headingId}>{title}</H>
+      {caption ? <p className="gb-leaderboard-caption">{caption}</p> : null}
+      <ol className="gb-leaderboard-list">
+        {rows.map((r, i) => {
+          const inner = (
+            <>
+              <span className={cx("gb-leaderboard-rank", !MEDALS[i] && "is-number")}>
+                <span aria-hidden="true">{MEDALS[i] ?? i + 1}</span><span className="ui-sr-only">Rank {i + 1}: </span>
+              </span>
+              <Avatar name={r.name} src={r.avatar} />
+              <span className="gb-leaderboard-name">{r.name}</span>
+              <span className="gb-leaderboard-value">
+                {r.value}{unit ? (showUnit ? <> {unit}</> : <span className="ui-sr-only"> {unit}</span>) : null}
+              </span>
+            </>
+          );
+          return (
+            <li key={r.key} className={cx("gb-leaderboard-row", i === 0 && "is-first")}>
+              {r.href ? <L href={r.href} className="gb-leaderboard-link">{inner}</L> : <div className="gb-leaderboard-link">{inner}</div>}
+            </li>
+          );
+        })}
+      </ol>
+      {viewAll ? <L href={viewAll.href} className="gb-leaderboard-all">{viewAll.label}</L> : null}
+    </section>
+  );
+}
+
+/** The first three as a podium, drawn second · first · third. */
+export function Podium({ rows, unit, as: L = "a", className }: { rows: LeaderRow[]; unit?: string; as?: LinkLike; className?: string }) {
+  if (!rows.length) return null;
+  return (
+    <ol className={cx("gb-podium", className)} aria-label="Top three">
+      {[1, 0, 2].map((idx) => {
+        const r = rows[idx];
+        if (!r) return <li key={idx} className="gb-podium-slot is-empty" aria-hidden="true" />;
+        const body = (
+          <>
+            <span className="gb-podium-medal"><span aria-hidden="true">{MEDALS[idx]}</span><span className="ui-sr-only">Rank {idx + 1}: </span></span>
+            <Avatar name={r.name} src={r.avatar} size={56} />
+            <span className="gb-podium-name">{r.name}</span>
+            <span className="gb-podium-value">{r.value}{unit ? <span className="gb-podium-unit"> {unit}</span> : null}</span>
+          </>
+        );
+        return (
+          <li key={r.key} className={cx("gb-podium-slot", PODIUM_SLOT[idx])}>
+            {r.href ? <L href={r.href} className="gb-podium-link">{body}</L> : <div className="gb-podium-link">{body}</div>}
+          </li>
+        );
+      })}
+    </ol>
+  );
+}

package/src/shell.css

@@ -406,8 +406,8 @@
 .gnav-item:focus-visible { outline: 2px solid var(--gemboss-accent); outline-offset: -2px; } /* the one iris ring (0.5.1): had none, the browser drew its own */
 
    /* neutral gray on white (Polaris-like) */
-/* Active hub: a full coral pill when you're ON the hub's own page. But when a deeper
-   LEAF is the destination, the hub quiets to coral text only — so the leaf below carries
+/* Active hub: the neutral selected pill (--gemboss-active-bg) when you're ON the hub's own page. But when a deeper
+   LEAF is the destination, the hub quiets to bold text only — so the leaf below carries
    the strong "you are here" and the two don't compete. */
 .gnav-item.active { color: var(--gemboss-active-fg); font-weight: 600; }
 
@@ -450,7 +450,7 @@
 
 .gnav-subitem:hover { background: var(--gemboss-nav-hover); color: var(--gemboss-text); }
 
-/* Active leaf — the strong "you are here": coral pill + a coral accent bar on the tree line. */
+/* Active leaf — the strong "you are here": the neutral selected pill + a near-black bar on the tree line. */
 .gnav-subitem.active { color: var(--gemboss-active-fg); font-weight: 600; background: var(--gemboss-active-bg); }
 
 .gnav-subitem.active:hover { background: var(--gemboss-active-bg); color: var(--gemboss-active-fg); }
@@ -470,19 +470,21 @@
 /* section separator (Assistant · Settings) */
 .gnav-sep { height: 1px; background: var(--gemboss-divider); margin: 8px 6px; }
 
-/* Assistant = the AI front door, not just another row. A coral-tinted pill that stands
+/* Assistant = the AI front door, not just another row. An iris-tinted pill that stands
    apart from the neutral hubs above; deepens on hover; becomes the standard active pill
-   when it's the current page. */
+   when it's the current page. It was a --gemboss-primary mix, which turned grey (#ececed)
+   once primary went near-black and read as a second selected row next to #f0f1f4 (0.6.8).
+   Contrast on --gemboss-accent-soft: label 6.05:1, icon and the iris focus ring 4.19:1 (16% hover: 5.56 / 3.84). */
 .gnav-item.gnav-assistant {
-  /* Label uses the DARKER coral for WCAG AA (4.77:1 on the 8% pill; the lighter
-     --gemboss-primary was 2.87, failed). Icon + pill keep --gemboss-primary as the accent. */
-  color: var(--gemboss-primary-dark); font-weight: 600;
-  background: color-mix(in srgb, var(--gemboss-primary) 8%, #fff);
+  color: var(--gemboss-accent-strong); font-weight: 600;
+  /* The kit's iris tint token, not a mix with #fff: a dark surface remaps -soft and -strong together, so the label keeps
+     its contrast there too (review #3710: a #fff mix under gempress's dark -strong would be 1.8:1). */
+  background: var(--gemboss-accent-soft);
 }
 
-.gnav-item.gnav-assistant .gnav-ico svg { fill: var(--gemboss-primary); }
+.gnav-item.gnav-assistant .gnav-ico svg { fill: var(--gemboss-accent); }
 
-.gnav-item.gnav-assistant:hover { background: color-mix(in srgb, var(--gemboss-primary) 15%, #fff); }
+.gnav-item.gnav-assistant:hover { background: color-mix(in srgb, var(--gemboss-accent) 16%, var(--gemboss-surface)); }
 
 .gnav-item.gnav-assistant.active { background: var(--gemboss-active-bg); color: var(--gemboss-active-fg); }
 

package/src/theme.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+/**
+ * Light and dark — @gemboss/ui (04/10/2026).
+ *
+ * Until now the kit had dark colours only on the sign-in screen, following the OS (auth.css). The
+ * GemPages board has a sun/moon button in its topbar and remembers the choice (Chris 04/10/2026: "xem
+ * kỹ các mode của nó … chuyển chế độ sáng tối"). `ThemeToggle` sets `data-theme="dark|light"` on
+ * <html> and stores it; portal.css redefines the `--gemboss-*` colours under `[data-theme="dark"]`, so
+ * every kit class (cards, tags, fields, buttons, the topbar) follows without a rule of its own.
+ *
+ * Opt-in: a surface without the toggle (the admin) never gets the attribute and stays light.
+ * `themeScript` goes in <head> (`<script dangerouslySetInnerHTML={{ __html: themeScript }} />`): it applies
+ * the stored choice, else the OS's, before the first paint, so a dark page never flashes white.
+ */
+import React, { useEffect, useState } from "react";
+import { Icon } from "./icons";
+
+export const THEME_KEY = "gemboss-theme";
+
+export const themeScript = `(function(){try{var t=localStorage.getItem("${THEME_KEY}");if(t!=="dark"&&t!=="light"){t=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}document.documentElement.setAttribute("data-theme",t)}catch(e){}})();`;
+
+export function ThemeToggle({ labels = { toDark: "Switch to dark mode", toLight: "Switch to light mode" } }: {
+  labels?: { toDark: string; toLight: string };
+}) {
+  // Unknown on the server; the script in <head> has already set the attribute by hydration.
+  const [dark, setDark] = useState<boolean | null>(null);
+  useEffect(() => { setDark(document.documentElement.getAttribute("data-theme") === "dark"); }, []);
+  const flip = () => {
+    const next = !(document.documentElement.getAttribute("data-theme") === "dark");
+    document.documentElement.setAttribute("data-theme", next ? "dark" : "light");
+    try { localStorage.setItem(THEME_KEY, next ? "dark" : "light"); } catch { /* private mode: the choice lasts this page */ }
+    setDark(next);
+  };
+  return (
+    // The label says what a press does; no aria-pressed as well (two states for one control).
+    <button type="button" className="gb-theme-toggle" onClick={flip}
+      aria-label={dark ? labels.toLight : labels.toDark} title={dark ? labels.toLight : labels.toDark}>
+      <Icon name={dark ? "sun" : "moon"} size={18} />
+    </button>
+  );
+}

package/src/ui.css

@@ -384,7 +384,7 @@ a.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-offset:
   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;
+  background: var(--ui-text-strong, #1a1917); color: var(--gemboss-on-primary, #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);
@@ -392,7 +392,7 @@ a.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-offset:
 .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;
+  flex: 0 0 auto; border: 0; background: transparent; color: var(--gemboss-on-primary, #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;
@@ -401,12 +401,12 @@ a.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-offset:
 .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;
+  background: rgba(255, 255, 255, 0.12); color: var(--gemboss-on-primary, #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; }
+.gemboss-toast-dismiss:focus-visible { outline: 2px solid var(--gemboss-on-primary, #fff); outline-offset: 2px; }
 @keyframes gemboss-toast-in {
   from { opacity: 0; transform: translateY(12px); }
   to { opacity: 1; transform: translateY(0); }