@pieai/swimmer-ui-kit 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -3,6 +3,119 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 1.1.0 — 2026-07-13
+
+A design-system quality pass: fixes real bugs in the existing surface
+(radial menu, contrast, fonts) and starts paying down the "central kitchen"
+governance/packaging debt (token adoption checker, theme contract export,
+demo CSS split). No exported component or prop was removed or renamed.
+
+### Added
+
+- `GAME_UI_THEME_CONTRACT`, an exported `readonly string[]` of every
+  semantic token a complete theme (like the official `night` theme) must
+  override. Downstream custom themes (e.g. an `abyss` theme) can assert
+  their own CSS covers the same list instead of eyeballing the docs.
+- Optional `./fonts.css` subpath: `@font-face` rules + bundled Latin-subset
+  woff2 for Baloo 2 and Geist Variable (SIL OFL), the two families
+  `theme.css`'s font stack already names. Not loading it still works
+  (progressive enhancement, system-font fallback) but non-standard font
+  weights (620/860/930) collapse to 400/700 without it.
+- `swimmer-ui-check`, a zero-dependency bin (`npx swimmer-ui-check <dir>`)
+  that scans a consumer's own CSS/TSX for raw color literals outside
+  `:root`/`[data-*theme*]` blocks — the same "no bare colors in component
+  rules" rule `src/tokens.test.ts` enforces inside this repo, made runnable
+  against downstream code.
+- `GameModal` gained `position="bottom"`, a mobile action-sheet variant of
+  the same native `<dialog>` (unchanged focus trap/Esc/backdrop, only the
+  frame's placement/shape/entrance differ). Replaces the hand-rolled
+  backdrop+slide-up-panel pattern some consumers were building themselves
+  (a known source of missing focus-trap/Esc handling).
+- `GameRadialMenu` gained an `onSelect?: (id: string) => void` callback
+  (previously clicking an item did nothing).
+- Demo site and Storybook both gained a light/night theme toggle (demo site:
+  navbar control using the kit's own `GameToggle`-style button; Storybook:
+  a global toolbar entry that sets `data-game-ui-theme` for every story).
+
+### Changed
+
+- **`GameRadialMenu` is now actually styled.** It rendered as unstyled
+  browser-default buttons before (`.game-ui-radial-item` had no CSS rule at
+  all); it's now a real circular wheel using clock-position placement.
+  `role="menu"`/`role="menuitem"` (which had no working keyboard model)
+  changed to `role="group"` + plain buttons.
+- **Button/tab/badge text contrast, both themes.** WCAG-measured failures
+  as low as 2.52:1 on the primary button in the night theme (need 4.5:1).
+  Fixed at the token layer only (`theme.css`): `--game-ui-accent-contrast`
+  is now a dark-ink color shared by primary/danger/success buttons, the
+  active tab/segmented pill, avatar initials, and the checkbox check —
+  component rules did not change. Two further raw-brand-color-as-text
+  spots (`--game-ui-danger` on `.game-ui-field-error`/`-required`,
+  `--game-ui-accent` on the first-session step numbers) got their own new
+  `--game-ui-danger-ink`/`--game-ui-accent-ink` tokens. HUD-chip and
+  fact-chip secondary text (`.game-ui-hud-chip small/em`,
+  `.game-ui-fact-copy small/em`) stopped fading `--game-ui-text-on-dark` to
+  72% opacity, which dropped under 4.5:1 against realistic glass-chip
+  backdrops. All of the above are locked in by an expanded WCAG contrast
+  guard test (`src/tokens.test.ts`), not just fixed once.
+- `GameSlider`'s range input now has a token-styled clay thumb/track
+  (`::-webkit-slider-thumb`/`::-moz-range-thumb`) instead of bare
+  `accent-color`.
+- `GameTooltip` auto-generates `aria-describedby` linking the trigger to
+  the tooltip text (was visual-only). `GameTabs` accepts an optional `id` +
+  per-tab `panelId` to auto-populate `aria-controls`.
+- Interactive controls get a `@media (forced-colors: active)` fallback
+  (Windows High Contrast) — pressed/selected states get a real border
+  instead of relying on a `color-mix()` wash forced-colors mode ignores.
+- Storybook's `@storybook/addon-a11y` gate went from cosmetic
+  (`test: 'todo'`) to enforced (`test: 'error'`) — a real axe violation now
+  fails `pnpm test`, not just shows up in the Storybook UI.
+
+### Fixed
+
+- Three accessibility bugs the newly-enforced Storybook a11y gate caught:
+  `GameCardFan` used an invalid `role="listitem"` on an `<article>`
+  (changed to a plain `<li>`); two scrollable job-list containers in
+  `GameContractorTools` had no keyboard focus path; `GameContractorPanel`'s
+  mobile drawer rendered the selected job twice (drawer + standalone card)
+  when open, producing duplicate ARIA landmarks.
+- `vitest.config.ts`'s unit-test include glob was `src/**/*.test.ts` —
+  it silently excluded every `*.test.tsx` file. Five files and ~30 tests
+  had never actually run via `pnpm test` despite the command exiting 0.
+  Fixed the glob, which then surfaced (and fixed) two further dormant test
+  bugs it had been hiding.
+- The demo site's token ledger truncated every value to `var(--…` and
+  broke token names mid-word (`TOUCHMINIM UMPX`); values now wrap instead
+  of ellipsis-truncating, and cards no longer stretch to their tallest
+  sibling in the grid.
+
+### Breaking (packaging only — no component/prop/class/token removed)
+
+- **`GameUiPreview`'s demo-only CSS moved to a new optional `./preview.css`
+  subpath.** It was ~13KB of stage/showcase-only rules
+  (`.game-ui-preview-*`, `.game-ui-swatch`/`.game-ui-token-*`,
+  `.game-ui-stage-world`, `.game-ui-proof-frame`, the first-session demo
+  world) that every consumer paid for in `styles.css` even though
+  `GameUiPreview` is a kit-internal showcase component almost nobody
+  renders in production. If you render `<GameUiPreview />` (as TuringPact's
+  `/ui-preview` route does), add
+  `import '@pieai/swimmer-ui-kit/preview.css'` alongside `./styles.css` or
+  it renders unstyled. Everyone else needs no code change —
+  `.game-ui-*`/`--game-ui-*` names are unchanged, only which file the CSS
+  ships in. `dist/styles.css` dropped from 89.2KB to 77.8KB minified.
+
+## 1.0.1 — 2026-07-11
+
+### Added
+
+- `GameCallout`, a token-driven notice surface for wallet pitches, onboarding
+  hints, warnings, success messages, and other compact product notices.
+
+### Changed
+
+- `GameButton` keeps a 44px minimum hit target on coarse pointers while allowing
+  denser 40px controls for precise pointers.
+
 ## 1.0.0 — 2026-07-03
 
 1.0 is a stability contract, not a feature drop: exported components and

package/bin/swimmer-ui-check.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Scans consumer CSS for raw color literals living in component rules
+// instead of flowing through SwimmerUIKit tokens. Mirrors the guard check
+// the kit runs on its own styles.css in src/tokens.test.ts, packaged so
+// downstream products can hold their own component CSS to the same
+// "token-only" bar the design-system-guide asks for.
+//
+// Raw colors are expected (and fine) inside token-defining blocks —
+// :root { ... } or an attribute-selector theme block like
+// [data-game-ui-theme='night'] / [data-theme='dark'] — since that is
+// exactly how the design-system-guide tells consumers to re-theme. Only
+// raw colors inside *other* selectors (component rules) are flagged.
+//
+// Usage: swimmer-ui-check [dir] [--ext=css,tsx]
+//   dir      directory to scan, default "src"
+//   --ext    comma-separated extensions to scan, default "css"
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+
+const RAW_COLOR = /#[0-9a-fA-F]{3,8}\b|\brgba?\(|\bhsla?\(|\boklch\(/g;
+const TOKEN_BLOCK_SELECTOR = /:root\b|\[data-[\w-]*theme[\w-]*\s*=/i;
+const IGNORE_DIRS = new Set(['node_modules', 'dist', '.git', 'storybook-static', 'site-dist', 'build']);
+
+function walk(dir, exts, out) {
+  for (const entry of readdirSync(dir)) {
+    if (IGNORE_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) walk(full, exts, out);
+    else if (exts.has(extname(entry))) out.push(full);
+  }
+}
+
+function lineFinder(text) {
+  const offsets = [0];
+  for (let i = 0; i < text.length; i += 1) if (text[i] === '\n') offsets.push(i + 1);
+  return (index) => {
+    let lo = 0;
+    let hi = offsets.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (offsets[mid] <= index) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo + 1;
+  };
+}
+
+/**
+ * Brace-depth scan (not a real CSS parser, good enough for this lint):
+ * every `{`/`}` pushes/pops whether the block it opened is a token-defining
+ * selector, and raw colors are only reported for declarations whose
+ * innermost enclosing block is not one of those.
+ */
+function findViolations(css) {
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+  const lineOf = lineFinder(withoutComments);
+
+  const blockIsTokenScope = [];
+  let blockStart = 0;
+  let cursor = 0;
+  const violations = [];
+
+  while (cursor < withoutComments.length) {
+    const open = withoutComments.indexOf('{', cursor);
+    const close = withoutComments.indexOf('}', cursor);
+    if (open === -1 && close === -1) break;
+
+    if (open !== -1 && (close === -1 || open < close)) {
+      const selector = withoutComments.slice(blockStart, open);
+      blockIsTokenScope.push(TOKEN_BLOCK_SELECTOR.test(selector));
+      blockStart = open + 1;
+      cursor = open + 1;
+    } else {
+      const body = withoutComments.slice(blockStart, close);
+      const allowed = blockIsTokenScope.pop() ?? false;
+      if (!allowed) {
+        for (const match of body.matchAll(RAW_COLOR)) {
+          violations.push({ line: lineOf(blockStart + match.index), text: match[0] });
+        }
+      }
+      blockStart = close + 1;
+      cursor = close + 1;
+    }
+  }
+  return violations;
+}
+
+const args = process.argv.slice(2);
+const target = args.find((a) => !a.startsWith('--')) ?? 'src';
+const extArg = args.find((a) => a.startsWith('--ext='));
+const exts = new Set(
+  (extArg ? extArg.slice('--ext='.length).split(',') : ['css']).map((e) => (e.startsWith('.') ? e : `.${e}`)),
+);
+
+const files = [];
+try {
+  walk(target, exts, files);
+} catch (error) {
+  console.error(`swimmer-ui-check: cannot read "${target}": ${error.message}`);
+  process.exit(2);
+}
+
+let violationCount = 0;
+for (const file of files) {
+  const text = readFileSync(file, 'utf8');
+  for (const violation of findViolations(text)) {
+    console.log(`${relative(process.cwd(), file)}:${violation.line}: raw color literal "${violation.text}" — use var(--game-ui-*) instead`);
+    violationCount += 1;
+  }
+}
+
+if (violationCount > 0) {
+  console.error(
+    `\nswimmer-ui-check: ${violationCount} raw color literal(s) in ${files.length} file(s) under "${target}". ` +
+      'Raw colors are expected inside :root / [data-*theme*=...] token blocks (that is how you re-theme the kit) ' +
+      'but not inside component rules — see the design-system-guide "主题化配方" section.',
+  );
+  process.exit(1);
+}
+console.log(`swimmer-ui-check: 0 raw color literals in component rules across ${files.length} file(s) under "${target}". Clean.`);

package/dist/fonts/OFL-Baloo2.txt

@@ -0,0 +1,93 @@
+Copyright 2019 The Baloo 2 Project Authors (https://github.com/EkType/Baloo2)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/fonts/OFL-Geist.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2023 Vercel, in collaboration with basement.studio
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/fonts.css

@@ -0,0 +1 @@
+@font-face{font-family:"Baloo 2";font-style:normal;font-weight:400 800;font-display:swap;src:url(./fonts/baloo-2-latin-variable.woff2)format("woff2");unicode-range:U+??,U+131,U+152-153,U+2BB-2BC,U+2C6,U+2DA,U+2DC,U+304,U+308,U+329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD}@font-face{font-family:Geist Variable;font-style:normal;font-weight:100 900;font-display:swap;src:url(./fonts/geist-sans-latin-variable.woff2)format("woff2");unicode-range:U+??,U+131,U+152-153,U+2BB-2BC,U+2C6,U+2DA,U+2DC,U+304,U+308,U+329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD}

package/dist/index.d.ts

@@ -55,7 +55,7 @@ export declare const CLAY_ASSETS: {
 
 export declare const CLAY_COLOR_TOKENS: {
     readonly ink: "#3b2d23";
-    readonly inkMuted: "#7b6652";
+    readonly inkMuted: "#786250";
     readonly parchment: "#fff8ec";
     readonly parchmentDeep: "#f4e2c6";
     readonly cream: "#f3e8d8";
@@ -346,7 +346,7 @@ export declare const CLAY_TYPE_TOKENS: {
 export declare const CLAY_UI_TOKENS: {
     readonly colors: {
         readonly ink: "#3b2d23";
-        readonly inkMuted: "#7b6652";
+        readonly inkMuted: "#786250";
         readonly parchment: "#fff8ec";
         readonly parchmentDeep: "#f4e2c6";
         readonly cream: "#f3e8d8";
@@ -593,6 +593,17 @@ export declare const GAME_UI_TARGETS: {
     readonly mobileLandscapeProofHeightPx: 390;
 };
 
+/**
+ * The semantic `--game-ui-*` custom properties a *complete* theme must
+ * override for full fidelity — this is the same list the official
+ * `[data-game-ui-theme='night']` block in theme.css satisfies, enforced by
+ * a guard test in src/tokens.test.ts. A downstream product building its own
+ * full theme (e.g. `[data-game-ui-theme='abyss']`) can reuse this constant
+ * to check its own CSS for the same completeness instead of eyeballing it —
+ * see "自定义第三主题" in design-system-guide.md for a usage example.
+ */
+export declare const GAME_UI_THEME_CONTRACT: readonly ["--game-ui-bg", "--game-ui-surface", "--game-ui-surface-raised", "--game-ui-panel", "--game-ui-panel-strong", "--game-ui-panel-deep", "--game-ui-text", "--game-ui-text-muted", "--game-ui-accent", "--game-ui-accent-bright", "--game-ui-secondary", "--game-ui-success", "--game-ui-success-bright", "--game-ui-danger", "--game-ui-danger-bright", "--game-ui-warning", "--game-ui-focus-ring", "--game-ui-border-subtle", "--game-ui-border-strong", "--game-ui-disabled", "--game-ui-ink-deep", "--game-ui-border-ink", "--game-ui-wood", "--game-ui-ink-title", "--game-ui-ink-heading"];
+
 export declare const GAME_UI_TOKENS: {
     readonly iconSm: "var(--game-ui-asset-icon-sm)";
     readonly iconMd: "var(--game-ui-asset-icon-md)";
@@ -892,6 +903,21 @@ export declare interface GameButtonProps extends ButtonHTMLAttributes<HTMLButton
 
 export declare type GameButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger' | 'success';
 
+/**
+ * Compact product notice (wallet pitch, soft warnings, onboarding hints).
+ * Token-driven; products may still override cinema theme in host CSS.
+ */
+export declare function GameCallout({ heading, children, tone, className, ...props }: GameCalloutProps): ReactNode;
+
+export declare interface GameCalloutProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** Visible heading (not HTML title attribute). */
+    readonly heading?: ReactNode;
+    readonly children: ReactNode;
+    readonly tone?: GameCalloutTone;
+}
+
+export declare type GameCalloutTone = 'neutral' | 'info' | 'warning' | 'success' | 'danger';
+
 export declare function GameCardFan({ cards, className, label }: GameCardFanProps): ReactNode;
 
 export declare interface GameCardFanCard {
@@ -1300,7 +1326,7 @@ export declare interface GameMaterialSwatchesProps {
     'data-testid'?: string | undefined;
 }
 
-export declare function GameModal({ children, className, closeLabel, closeOnBackdrop, footer, onClose, open, size, title, }: GameModalProps): ReactNode;
+export declare function GameModal({ children, className, closeLabel, closeOnBackdrop, footer, onClose, open, position, size, title, }: GameModalProps): ReactNode;
 
 export declare interface GameModalProps {
     children: ReactNode;
@@ -1312,6 +1338,13 @@ export declare interface GameModalProps {
     /** Called for every close intent: Esc, backdrop click, and close button. */
     onClose: () => void;
     open: boolean;
+    /**
+     * `'bottom'` anchors the frame to the viewport's bottom edge (rounded top
+     * corners only, safe-area-aware padding, slide-up entrance) for mobile
+     * action sheets — same native <dialog> underneath, so focus trap/Esc/
+     * backdrop/top-layer come free either way. Defaults to `'center'`.
+     */
+    position?: 'center' | 'bottom';
     size?: 'sm' | 'md' | 'lg';
     title: string;
 }
@@ -1406,7 +1439,7 @@ export declare interface GamePromptProps {
     title: string;
 }
 
-export declare function GameRadialMenu({ items, label }: GameRadialMenuProps): ReactNode;
+export declare function GameRadialMenu({ items, label, onSelect }: GameRadialMenuProps): ReactNode;
 
 declare interface GameRadialMenuItem {
     id: string;
@@ -1416,6 +1449,7 @@ declare interface GameRadialMenuItem {
 export declare interface GameRadialMenuProps {
     items: readonly GameRadialMenuItem[];
     label: string;
+    onSelect?: (id: string) => void;
 }
 
 export declare interface GameRobotCrewMember {
@@ -1514,12 +1548,21 @@ export declare type GameSurfaceLayout = 'auto' | 'desktop' | 'mobile';
 export declare interface GameTabItem {
     id: string;
     label: string;
+    /** id of the tabpanel this tab controls; wires aria-controls when set. */
+    panelId?: string;
 }
 
-export declare function GameTabs({ activeId, onSelect, tabs }: GameTabsProps): ReactNode;
+export declare function GameTabs({ activeId, id, onSelect, tabs }: GameTabsProps): ReactNode;
 
 export declare interface GameTabsProps {
     activeId: string;
+    /**
+     * Base id for this tabs instance (defaults to a generated one). Each tab
+     * button's DOM id is `${id}-${tab.id}` — pass an explicit id so your own
+     * `role="tabpanel"` elements can reference it via aria-labelledby (and set
+     * GameTabItem.panelId so the tab points back via aria-controls).
+     */
+    id?: string;
     onSelect?: (id: string) => void;
     tabs: readonly GameTabItem[];
 }
@@ -1667,6 +1710,7 @@ export declare interface GameToggleProps extends Pick<ButtonHTMLAttributes<HTMLB
 export declare function GameTooltip({ children, label }: GameTooltipProps): ReactNode;
 
 export declare interface GameTooltipProps {
+    /** A single focusable trigger element (e.g. GameIconButton). */
     children: ReactNode;
     label: string;
 }