@pieai/swimmer-ui-kit 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 All notable changes to `@pieai/swimmer-ui-kit`.
 Format: [Keep a Changelog](https://keepachangelog.com); versioning: semver.
 
+## 1.2.0 — 2026-07-18
+
+Purely additive: an official "overlay glass" HUD surface tone plus a compact
+density, for products that float kit chrome over a live scene (TuringPact 3D
+tavern, SupaLuv cinematic stage). No exported component, prop, class, or token
+was removed or renamed.
+
+### Added
+
+- Overlay glass scope: `data-game-ui-tone="glass"` (alias class
+  `.game-ui-overlay-scope`) re-scopes semantic surface/text/elevation tokens on
+  a subtree to dark translucent glass — fill `rgba(12,14,20,0.72)`, 1px light
+  border, no clay box-shadow, warm accent hover/primary, WCAG-visible warm
+  focus ring (`--game-ui-overlay-glass-focus-ring`). Nests inside light or
+  `night` page themes.
+- Compact density: `data-game-ui-density="compact"` (orthogonal to tone) —
+  34px control floor, tighter panel/chip padding for HUD clusters.
+- Primitive tokens `--game-ui-overlay-glass-*` in `theme.css`; TS mirrors
+  `CLAY_OVERLAY_GLASS_TOKENS` and `GAME_UI_OVERLAY` attr/class constants.
+- Clay `GameAssetIcon` gets a soft dark drop-shadow inside glass scope so
+  sculpted icons read on translucent dark chips.
+- Stories/preview compare: same HUD cluster in default clay vs overlay glass
+  over a busy scene background, light and night contexts.
+
+### Migration notes
+
+- Consumers opt in per subtree; nothing changes without the attribute.
+- SupaLuv can delete its `.vn-stage .game-ui-button` `!important` overrides
+  (stage.css ~217-360) after wrapping its HUD in the glass scope.
+
 ## 1.1.0 — 2026-07-13
 
 A design-system quality pass: fixes real bugs in the existing surface

package/bin/swimmer-ui-check.mjs

@@ -6,10 +6,11 @@
 // "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.
+// :root { ... } or an attribute-selector theme/tone block like
+// [data-game-ui-theme='night'] / [data-game-ui-tone='glass'] /
+// [data-theme='dark'] — since that is how the design-system-guide tells
+// consumers to re-theme or re-scope surface tones. Only raw colors inside
+// *other* selectors (component rules) are flagged.
 //
 // Usage: swimmer-ui-check [dir] [--ext=css,tsx]
 //   dir      directory to scan, default "src"
@@ -18,8 +19,15 @@ 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']);
+const TOKEN_BLOCK_SELECTOR = /:root\b|\[data-[\w-]*(?:theme|tone)[\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)) {
@@ -90,7 +98,9 @@ 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}`)),
+  (extArg ? extArg.slice('--ext='.length).split(',') : ['css']).map((e) =>
+    e.startsWith('.') ? e : `.${e}`,
+  ),
 );
 
 const files = [];
@@ -105,7 +115,9 @@ 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`);
+    console.log(
+      `${relative(process.cwd(), file)}:${violation.line}: raw color literal "${violation.text}" — use var(--game-ui-*) instead`,
+    );
     violationCount += 1;
   }
 }
@@ -113,9 +125,12 @@ for (const file of files) {
 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.',
+      'Raw colors are expected inside :root / [data-*theme*=...] / [data-*tone*=...] token blocks ' +
+      '(that is how you re-theme or re-scope 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.`);
+console.log(
+  `swimmer-ui-check: 0 raw color literals in component rules across ${files.length} file(s) under "${target}". Clean.`,
+);

package/dist/index.d.ts

@@ -72,6 +72,9 @@ export declare const CLAY_COLOR_TOKENS: {
     readonly shadow: "rgba(76, 52, 28, 0.24)";
     readonly glass: "rgba(255, 248, 236, 0.82)";
     readonly nightGlass: "rgba(31, 24, 18, 0.76)";
+    /** Official HUD-on-scene glass fill (matches SupaLuv stage chrome). */
+    readonly overlayGlass: "rgba(12, 14, 20, 0.72)";
+    readonly overlayGlassText: "#fff6ee";
 };
 
 export declare const CLAY_ELEVATION_TOKENS: {
@@ -268,6 +271,26 @@ export declare const CLAY_MOTION_TOKENS: {
     readonly reducedMotion: "var(--game-ui-reduced-motion-policy)";
 };
 
+/**
+ * Semantic CSS vars for the official overlay-glass HUD tone
+ * (`data-game-ui-tone="glass"` / `.game-ui-overlay-scope`).
+ */
+declare const CLAY_OVERLAY_GLASS_TOKENS: {
+    readonly bg: "var(--game-ui-overlay-glass-bg)";
+    readonly bgHover: "var(--game-ui-overlay-glass-bg-hover)";
+    readonly bgStrong: "var(--game-ui-overlay-glass-bg-strong)";
+    readonly bgPanel: "var(--game-ui-overlay-glass-bg-panel)";
+    readonly border: "var(--game-ui-overlay-glass-border)";
+    readonly borderHover: "var(--game-ui-overlay-glass-border-hover)";
+    readonly text: "var(--game-ui-overlay-glass-text)";
+    readonly textMuted: "var(--game-ui-overlay-glass-text-muted)";
+    readonly blur: "var(--game-ui-overlay-glass-blur)";
+    readonly focusRing: "var(--game-ui-overlay-glass-focus-ring)";
+    readonly primaryFill: "var(--game-ui-overlay-glass-primary-fill)";
+};
+export { CLAY_OVERLAY_GLASS_TOKENS }
+export { CLAY_OVERLAY_GLASS_TOKENS as GAME_UI_OVERLAY_GLASS_TOKENS }
+
 export declare const CLAY_RADIUS_TOKENS: {
     readonly bead: "var(--game-ui-radius-bead)";
     readonly control: "var(--game-ui-radius-control)";
@@ -363,6 +386,9 @@ export declare const CLAY_UI_TOKENS: {
         readonly shadow: "rgba(76, 52, 28, 0.24)";
         readonly glass: "rgba(255, 248, 236, 0.82)";
         readonly nightGlass: "rgba(31, 24, 18, 0.76)";
+        /** Official HUD-on-scene glass fill (matches SupaLuv stage chrome). */
+        readonly overlayGlass: "rgba(12, 14, 20, 0.72)";
+        readonly overlayGlassText: "#fff6ee";
     };
     readonly semantic: {
         readonly background: "var(--game-ui-bg)";
@@ -470,6 +496,19 @@ export declare const CLAY_UI_TOKENS: {
         readonly buildRailCardSize: "var(--game-ui-build-rail-card-size)";
         readonly brushNumberWidth: "var(--game-ui-brush-number-width)";
     };
+    readonly overlayGlass: {
+        readonly bg: "var(--game-ui-overlay-glass-bg)";
+        readonly bgHover: "var(--game-ui-overlay-glass-bg-hover)";
+        readonly bgStrong: "var(--game-ui-overlay-glass-bg-strong)";
+        readonly bgPanel: "var(--game-ui-overlay-glass-bg-panel)";
+        readonly border: "var(--game-ui-overlay-glass-border)";
+        readonly borderHover: "var(--game-ui-overlay-glass-border-hover)";
+        readonly text: "var(--game-ui-overlay-glass-text)";
+        readonly textMuted: "var(--game-ui-overlay-glass-text-muted)";
+        readonly blur: "var(--game-ui-overlay-glass-blur)";
+        readonly focusRing: "var(--game-ui-overlay-glass-focus-ring)";
+        readonly primaryFill: "var(--game-ui-overlay-glass-primary-fill)";
+    };
 };
 
 export declare type ClayAssetGroup = keyof typeof CLAY_ASSETS;
@@ -507,7 +546,7 @@ export declare type ClayIconStyle = 'game' | 'line';
 
 export declare type ClayTokenCategory = keyof typeof CLAY_UI_TOKENS;
 
-export declare function FirstSessionHud({ authenticated, batteryCount, className, dailyStreak, iconSlots, labels, onHistory, onSettings, onWardrobe, playerName }: FirstSessionHudProps): ReactNode;
+export declare function FirstSessionHud({ authenticated, batteryCount, className, dailyStreak, iconSlots, labels, onHistory, onSettings, onWardrobe, playerName, }: FirstSessionHudProps): ReactNode;
 
 export declare interface FirstSessionHudIconSlots {
     history?: ReactNode;
@@ -556,7 +595,7 @@ export declare interface FirstSessionHudProps {
     playerName: string;
 }
 
-export declare function FirstSessionOnboarding({ labels, onDismiss, open }: FirstSessionOnboardingProps): ReactNode;
+export declare function FirstSessionOnboarding({ labels, onDismiss, open, }: FirstSessionOnboardingProps): ReactNode;
 
 export declare interface FirstSessionOnboardingLabels {
     badge: string;
@@ -578,6 +617,15 @@ export declare interface FirstSessionOnboardingStep {
     title: string;
 }
 
+/** Opt-in attribute values for the official overlay-glass HUD scope. */
+export declare const GAME_UI_OVERLAY: {
+    readonly toneAttr: "data-game-ui-tone";
+    readonly toneGlass: "glass";
+    readonly densityAttr: "data-game-ui-density";
+    readonly densityCompact: "compact";
+    readonly scopeClass: "game-ui-overlay-scope";
+};
+
 export declare const GAME_UI_PREVIEW_MESSAGES: readonly GameUiHistoryEntry[];
 
 export declare const GAME_UI_TARGETS: {
@@ -681,7 +729,7 @@ export declare const GAME_UI_TOKENS: {
     readonly disabled: "var(--game-ui-disabled)";
 };
 
-export declare function GameActionGrid({ actions, className, density, iconLabelMode, label, style }: GameActionGridProps): ReactNode;
+export declare function GameActionGrid({ actions, className, density, iconLabelMode, label, style, }: GameActionGridProps): ReactNode;
 
 export declare interface GameActionGridProps {
     actions: readonly GameUiAction[];
@@ -736,7 +784,7 @@ export declare interface GameAssetGroup {
     source?: GameAssetSource;
 }
 
-export declare function GameAssetIcon({ className, icon, label, size, style, useSourceAsset }: GameAssetIconProps): ReactNode;
+export declare function GameAssetIcon({ className, icon, label, size, style, useSourceAsset, }: GameAssetIconProps): ReactNode;
 
 export declare interface GameAssetIconProps {
     className?: string;
@@ -773,7 +821,7 @@ export declare type GameAssetSource = 'starter' | 'generated' | 'imported';
 
 export declare type GameAssetStatus = 'ready' | 'generating' | 'missing' | 'placed' | 'selected' | 'error';
 
-export declare function GameAvatar({ className, name, size, src, status }: GameAvatarProps): ReactNode;
+export declare function GameAvatar({ className, name, size, src, status, }: GameAvatarProps): ReactNode;
 
 export declare interface GameAvatarProps {
     /** Display name — used as image alt text and for the initials fallback. */
@@ -1155,7 +1203,7 @@ export declare interface GameDialogProps {
     title: string;
 }
 
-export declare function GameEmptyState({ action, className, description, icon, title }: GameEmptyStateProps): ReactNode;
+export declare function GameEmptyState({ action, className, description, icon, title, }: GameEmptyStateProps): ReactNode;
 
 export declare interface GameEmptyStateProps {
     /** Optional clay icon shown above the title. */
@@ -1176,7 +1224,7 @@ export declare interface GameFactItem {
     value: ReactNode;
 }
 
-export declare function GameFactList({ className, density, facts, label, variant }: GameFactListProps): ReactNode;
+export declare function GameFactList({ className, density, facts, label, variant, }: GameFactListProps): ReactNode;
 
 export declare interface GameFactListProps {
     className?: string;
@@ -1186,7 +1234,7 @@ export declare interface GameFactListProps {
     variant?: 'facts' | 'stats';
 }
 
-export declare function GameField({ children, className, error, hint, label, required }: GameFieldProps): ReactNode;
+export declare function GameField({ children, className, error, hint, label, required, }: GameFieldProps): ReactNode;
 
 export declare interface GameFieldProps {
     /** The input/textarea this field labels. Rendered inside the <label>. */
@@ -1286,7 +1334,7 @@ export declare interface GameInteractionSoundOptions {
     sfxVolume?: number;
 }
 
-export declare function GameLanguageMenu({ className, currentLabel, label, options, value, defaultValue, onSelect }: GameLanguageMenuProps): ReactNode;
+export declare function GameLanguageMenu({ className, currentLabel, label, options, value, defaultValue, onSelect, }: GameLanguageMenuProps): ReactNode;
 
 export declare interface GameLanguageMenuProps {
     className?: string;
@@ -1377,7 +1425,7 @@ export declare const GameObjectToolbar: typeof GamePlacementToolbar;
 
 export declare type GameObjectToolbarProps = GamePlacementToolbarProps;
 
-export declare function GameOrientationGate({ body, cta, badgeLabel, manualHint, preview, title }: GameOrientationGateProps): ReactNode;
+export declare function GameOrientationGate({ body, cta, badgeLabel, manualHint, preview, title, }: GameOrientationGateProps): ReactNode;
 
 export declare interface GameOrientationGateProps {
     body: string;
@@ -1417,7 +1465,7 @@ export declare interface GamePlacementToolbarProps {
     title: string;
 }
 
-export declare function GameProgress({ className, label, max, showValue, tone, value }: GameProgressProps): ReactNode;
+export declare function GameProgress({ className, label, max, showValue, tone, value, }: GameProgressProps): ReactNode;
 
 export declare interface GameProgressProps {
     /** Current value, between 0 and `max`. */
@@ -1480,7 +1528,7 @@ export declare const GameSceneHudLayout: typeof GameShell;
 
 export declare type GameSceneHudLayoutProps = GameShellProps;
 
-export declare function GameSegmentedControl({ activeId, label, onSelect, options }: GameSegmentedControlProps): ReactNode;
+export declare function GameSegmentedControl({ activeId, label, onSelect, options, }: GameSegmentedControlProps): ReactNode;
 
 export declare interface GameSegmentedControlProps {
     activeId: string;