@origingame/engine 0.1.1 → 0.3.0

package/src/ui-kit/huds.ts

@@ -2,11 +2,13 @@
 // set of anchored groups over the game in the safe area, plus the touch
 // controls they show on phones and tablets. HUDs turn keyboard and gamepad
 // navigation off (the keys move the player); Back still answers `paused`,
-// except under an open dialog, which keeps it (og.ui.back).
+// except under an open dialog, which keeps it (og.ui.back). Every word a HUD
+// draws or names is a field of its desc with the English default (og-i18n
+// §2), so a game in another language has none of the kit's English left.
 
 import type * as Api from "@origingame/engine";
 import { kit } from "./bind.ts";
-import { all, capsule, clock, fit, fmt, frame, grow, iconOr, lapTime, px, token } from "./util.ts";
+import { all, hudBox, clock, fit, fmt, frame, grow, iconOr, lapTime, px, token } from "./util.ts";
 
 type Hud = { paused: boolean; action: string | null; moveX: number; moveY: number; held: string[] };
 
@@ -15,7 +17,8 @@ function hud(): Hud {
   return { paused: kit.back(), action: null, moveX: 0, moveY: 0, held: [] };
 }
 
-function pauseButton(out: Hud, label = "Pause"): void {
+/** The pause button: its icon, named by the desc's `pauseLabel` (what a screen reader says). */
+function pauseButton(out: Hud, label: string): void {
   const r = kit.actionButton("Pause", label, { size: 44, icon: "pause" });
   if (r.clicked) out.paused = true;
 }
@@ -24,7 +27,7 @@ function pauseButton(out: Hud, label = "Pause"): void {
 function stat(id: string, value: string, caption: string, step: Api.TypeStepName = "xl3", align: Api.TextAlign = "start"): void {
   kit.column(id, { gap: 0, cross: align === "end" ? "end" : align === "center" ? "center" : "start" }, () => {
     kit.label("Value", value, { step, font: "mono", nowrap: true, align });
-    kit.label("Caption", caption, { step: "meta", color: token("fgMuted"), nowrap: true, align });
+    kit.label("Caption", caption, { step: "meta", color: token("inkMuted"), nowrap: true, align });
   });
 }
 
@@ -55,45 +58,45 @@ export function platformerHud(id: string, desc: Api.PlatformerHudDesc = {}): Api
   const { t, touch } = frame();
   const out = hud();
   // What the game leaves out is not drawn: no hearts with maxLives 0 (and
-  // no health bar), no coins or score capsule without coins or score.
+  // no health bar), no coins or score box without coins or score.
   const health = desc.health ?? null;
   const maxLives = desc.maxLives ?? 3;
   const coins = desc.coins ?? null;
   const score = desc.score ?? null;
   if (health !== null || maxLives > 0 || desc.level) {
     kit.anchor(`${id}.left`, { anchor: "topLeft", direction: "column", gap: t.sm }, () => {
-      if (health !== null) capsule("Lives", () => kit.meter("Health", health, 1, { width: px(120) }));
+      if (health !== null) hudBox("Lives", () => kit.meter("Health", health, 1, { width: px(120) }));
       else if (maxLives > 0) {
-        capsule("Lives", () => {
-          for (let i = 0; i < maxLives; i++) iconOr(kit.idi("Life", i), "heart", 20, token(i < (desc.lives ?? 0) ? "danger" : "fillStrong"));
+        hudBox("Lives", () => {
+          for (let i = 0; i < maxLives; i++) iconOr(kit.idi("Life", i), "heart", 20, token(i < (desc.lives ?? 0) ? "danger" : "controlStrong"));
         });
       }
-      if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("fgMuted"), nowrap: true });
+      if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("inkMuted"), nowrap: true });
     });
   }
   if (desc.timeLeft !== null && desc.timeLeft !== undefined) {
     const low = desc.timeLeft <= 10;
     kit.anchor(`${id}.top`, { anchor: "top" }, () => {
-      capsule("Timer", () => kit.label("Time", clock(desc.timeLeft!), { step: "lg", font: "mono", color: token(low ? "danger" : "fg"), nowrap: true }));
+      hudBox("Timer", () => kit.label("Time", clock(desc.timeLeft!), { step: "lg", font: "mono", color: token(low ? "danger" : "ink"), nowrap: true }));
     });
   }
   kit.anchor(`${id}.right`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
     if (coins !== null) {
-      capsule("Coins", () => {
-        iconOr("Coin", "coin", 20, token("accent"));
+      hudBox("Coins", () => {
+        iconOr("Coin", "coin", 20, token("gold"));
         kit.label("Count", fmt(coins), { font: "mono", nowrap: true });
       });
     }
-    if (score !== null) capsule("Score", () => kit.label("Points", fmt(score), { font: "mono", nowrap: true }));
-    pauseButton(out);
+    if (score !== null) hudBox("Score", () => kit.label("Points", fmt(score), { font: "mono", nowrap: true }));
+    pauseButton(out, desc.pauseLabel ?? "Pause");
   });
-  if ((desc.touch ?? false) && touch) touchControls(out, { dpad: true, buttons: [{ id: "jump", label: "Jump", primary: true }] });
+  if ((desc.touch ?? false) && touch) touchControls(out, { dpad: true, buttons: [{ id: "jump", label: desc.jumpLabel ?? "Jump", primary: true }] });
   return out;
 }
 
 /** A crosshair at the centre: four short strokes and a gap. */
 function crosshair(): void {
-  const ink = token("fg", 0.9);
+  const ink = token("ink", 0.9);
   const bar = (id: string, w: number, h: number): void => kit.image(id, { tint: ink, width: px(w), height: px(h) });
   kit.anchor("Crosshair", { anchor: "center", direction: "column", cross: "center", gap: 6 }, () => {
     bar("N", 2, 8);
@@ -118,20 +121,20 @@ export function shooterHud(id: string, desc: Api.ShooterHudDesc = {}): Api.HudRe
   });
   if (desc.map && !showTouch) kit.anchor(`${id}.map`, { anchor: "topLeft" }, () => kit.minimap("Map", desc.map!));
   kit.anchor(`${id}.top`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
-    capsule("Kills", () => {
+    hudBox("Kills", () => {
       kit.label("Count", fmt(desc.kills ?? 0), { font: "mono", nowrap: true });
-      kit.label("Unit", "kills", { step: "meta", color: token("fgMuted"), nowrap: true });
+      kit.label("Unit", desc.killsLabel ?? "kills", { step: "meta", color: token("inkMuted"), nowrap: true });
     });
-    pauseButton(out);
+    pauseButton(out, desc.pauseLabel ?? "Pause");
   });
  kit.anchor(`${id}.ammo`, { anchor: showTouch ? "topRight" : "bottomRight", offsetY: showTouch ? 56 : 0, direction: "column", cross: "end", gap: t.xs }, () => {
     const mag = desc.magazine ?? 0;
     const ammo = desc.ammo ?? 0;
     kit.row("Rounds", { gap: t.xs, cross: "end" }, () => {
-      kit.label("Ammo", `${ammo}`, { step: "xl5", font: "mono", color: token(mag > 0 && ammo <= Math.floor(mag / 4) ? "warn" : "fg"), nowrap: true });
-      kit.label("Reserve", `/ ${desc.reserve ?? 0}`, { step: "lg", font: "mono", color: token("fgMuted"), nowrap: true });
+      kit.label("Ammo", `${ammo}`, { step: "xl5", font: "mono", color: token(mag > 0 && ammo <= Math.floor(mag / 4) ? "warn" : "ink"), nowrap: true });
+      kit.label("Reserve", `/ ${desc.reserve ?? 0}`, { step: "lg", font: "mono", color: token("inkMuted"), nowrap: true });
     });
-    if (desc.weapon) kit.label("Weapon", desc.weapon, { step: "meta", color: token("fgMuted"), nowrap: true });
+    if (desc.weapon) kit.label("Weapon", desc.weapon, { step: "meta", color: token("inkMuted"), nowrap: true });
   });
   const abilities = desc.abilities ?? [];
   if (abilities.length > 0) {
@@ -144,7 +147,7 @@ export function shooterHud(id: string, desc: Api.ShooterHudDesc = {}): Api.HudRe
     });
   }
   if (desc.crosshair ?? true) crosshair();
-  if (showTouch) touchControls(out, { buttons: [{ id: "fire", label: "Fire", primary: true }] });
+  if (showTouch) touchControls(out, { buttons: [{ id: "fire", label: desc.fireLabel ?? "Fire", primary: true }] });
   return out;
 }
 
@@ -155,22 +158,22 @@ export function puzzleHud(id: string, desc: Api.PuzzleHudDesc = {}): Api.HudResu
   const score = desc.score ?? 0;
   const marks = desc.stars && desc.stars.length > 0 ? desc.stars : [Math.round(target / 3), Math.round((2 * target) / 3), target];
   kit.anchor(`${id}.left`, { anchor: "topLeft", direction: "column", gap: t.xs }, () => {
-    if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("fgMuted"), nowrap: true });
-    if (desc.moves !== null && desc.moves !== undefined) stat("Moves", `${desc.moves}`, "moves left", "xl3");
+    if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("inkMuted"), nowrap: true });
+    if (desc.moves !== null && desc.moves !== undefined) stat("Moves", `${desc.moves}`, desc.movesLabel ?? "moves left", "xl3");
   });
   kit.anchor(`${id}.score`, { anchor: "top", direction: "column", cross: "center", gap: t.xs, width: px(260) }, () => {
     kit.label("Score", fmt(score), { step: "displaySm", font: "display", align: "center", width: grow() });
-    kit.meter("Progress", score, target, { kind: "accent", width: grow(), segments: 3 });
+    kit.meter("Progress", score, target, { kind: "primary", width: grow(), segments: 3 });
     kit.row("Stars", { gap: t.sm, cross: "center" }, () => {
-      marks.slice(0, 3).forEach((m, i) => iconOr(kit.idi("Star", i), "star", 20, token(score >= m ? "accent" : "fillStrong")));
-      kit.label("Target", `Target ${fmt(target)}`, { step: "meta", color: token("fgMuted"), nowrap: true });
+      marks.slice(0, 3).forEach((m, i) => iconOr(kit.idi("Star", i), "star", 20, token(score >= m ? "primary" : "controlStrong")));
+      kit.label("Target", (desc.targetLabel ?? "Target {target}").replaceAll("{target}", fmt(target)), { step: "meta", color: token("inkMuted"), nowrap: true });
     });
   });
   kit.anchor(`${id}.right`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
     if (desc.timeLeft !== null && desc.timeLeft !== undefined) {
-      capsule("Timer", () => kit.label("Time", clock(desc.timeLeft!), { font: "mono", color: token(desc.timeLeft! <= 10 ? "danger" : "fg"), nowrap: true }));
+      hudBox("Timer", () => kit.label("Time", clock(desc.timeLeft!), { font: "mono", color: token(desc.timeLeft! <= 10 ? "danger" : "ink"), nowrap: true }));
     }
-    pauseButton(out);
+    pauseButton(out, desc.pauseLabel ?? "Pause");
   });
   return out;
 }
@@ -182,13 +185,13 @@ export function idleHud(id: string, desc: Api.IdleHudDesc = {}): Api.HudResult {
   const generators = desc.generators ?? [];
   kit.anchor(`${id}.wallet`, { anchor: "top", gap: t.sm, cross: "center" }, () => {
     currencies.forEach((c, i) => {
-      capsule(c.id ?? kit.idi("Currency", i), () => {
-        if (c.icon) iconOr("Icon", c.icon, 20, token("accent"));
+      hudBox(c.id ?? kit.idi("Currency", i), () => {
+        if (c.icon) iconOr("Icon", c.icon, 20, token("primary"));
         kit.label("Amount", fmt(c.amount ?? 0), { step: i === 0 ? "lg" : "body", font: "mono", nowrap: true });
-        if ((c.perSecond ?? 0) !== 0) kit.label("Rate", `+${fmt(c.perSecond ?? 0)}/s`, { step: "meta", color: token("success"), nowrap: true });
+        if ((c.perSecond ?? 0) !== 0) kit.label("Rate", (desc.rateLabel ?? "+{rate}/s").replaceAll("{rate}", fmt(c.perSecond ?? 0)), { step: "meta", color: token("success"), nowrap: true });
       }, { height: i === 0 ? t.controlLg : t.controlMd });
     });
-    pauseButton(out);
+    pauseButton(out, desc.pauseLabel ?? "Pause");
   });
   if (desc.tapLabel !== "") {
     kit.anchor(`${id}.tap`, { anchor: phone ? "top" : "center", offsetY: phone ? 96 : 0, offsetX: phone ? 0 : -150 }, () => {
@@ -201,13 +204,13 @@ export function idleHud(id: string, desc: Api.IdleHudDesc = {}): Api.HudResult {
     kit.panel("Generators", { width: grow(), padding: all(t.sm), gap: t.xs }, () => {
       kit.list("List", { count: generators.length, rowHeight: 64, gap: t.xs, height: fit(0, listHeight), width: grow() }, (i) => {
         const g = generators[i]!;
-        if (g.icon) iconOr("Icon", g.icon, 32, token("fg"));
+        if (g.icon) iconOr("Icon", g.icon, 32, token("ink"));
         kit.column("Text", { width: grow(), gap: t.xxs }, () => {
           kit.row("Head", { gap: t.sm, cross: "center", width: grow() }, () => {
             kit.label("Name", g.name ?? g.id ?? "", { step: "lg", nowrap: true, width: grow() });
-            kit.badge("Level", `Lv ${g.level ?? 0}`, "neutral");
+            kit.badge("Level", (desc.levelLabel ?? "Lv {level}").replaceAll("{level}", `${g.level ?? 0}`), "neutral");
           });
-          kit.meter("Cycle", g.progress ?? 0, 1, { kind: "accent", height: 4, width: grow() });
+          kit.meter("Cycle", g.progress ?? 0, 1, { kind: "primary", height: 4, width: grow() });
         });
         const buy = kit.button("Buy", fmt(g.cost ?? 0), { size: "small", variant: g.affordable ? "primary" : "secondary", disabled: !g.affordable }) as Api.Response;
         if (buy.clicked) out.action = `buy:${g.id ?? i}`;
@@ -226,7 +229,7 @@ function deltaText(seconds: number): string {
 
 /** A delta's ink: ahead (negative) success, behind danger, even muted. */
 function deltaInk(seconds: number): Api.Paint {
-  return token(seconds < 0 ? "success" : seconds > 0 ? "danger" : "fgMuted");
+  return token(seconds < 0 ? "success" : seconds > 0 ? "danger" : "inkMuted");
 }
 
 export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResult {
@@ -241,7 +244,7 @@ export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResu
     if (racers > 0) {
       kit.row("Position", { gap: t.xxs, cross: "end" }, () => {
         kit.label("Place", `${desc.position ?? 1}`, { step: "displayXl", font: "display", nowrap: true });
-        kit.label("Of", `/${racers}`, { step: "xl", font: "mono", color: token("fgMuted"), nowrap: true });
+        kit.label("Of", `/${racers}`, { step: "xl", font: "mono", color: token("inkMuted"), nowrap: true });
       });
     }
     stat("Lap", `${Math.min(desc.lap ?? 1, desc.laps ?? 3)}/${desc.laps ?? 3}`, desc.lapLabel ?? "lap", "xl3");
@@ -254,16 +257,17 @@ export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResu
     const delta = desc.delta ?? null;
     if (delta !== null) kit.label("Delta", deltaText(delta), { step: "lg", font: "mono", color: deltaInk(delta), nowrap: true });
     if (desc.best !== null && desc.best !== undefined) {
-      kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", clock(desc.best, true)), { step: "meta", font: "mono", color: token("fgMuted"), nowrap: true });
+      // A finished lap: m:ss.mmm as lapTime cuts it (30.717 s is 0:30.717, where the running clock's floor reads 0:30.716).
+      kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", lapTime(desc.best)), { step: "meta", font: "mono", color: token("inkMuted"), nowrap: true });
     }
     const splits = desc.splits ?? [];
     if (splits.length > 0) {
       kit.column("Splits", { gap: 0, cross: "end" }, () => {
         splits.forEach((sp, i) => {
           kit.row(kit.idi("Split", i), { gap: t.sm, cross: "center" }, () => {
-            kit.label("Label", sp.label ?? "", { step: "meta", color: token("fgMuted"), nowrap: true });
+            kit.label("Label", sp.label ?? "", { step: "meta", color: token("inkMuted"), nowrap: true });
             const time = sp.time ?? null;
-            kit.label("Time", time === null ? "-:--.---" : lapTime(time), { step: "meta", font: "mono", color: token(time === null ? "fgSubtle" : "fg"), nowrap: true });
+            kit.label("Time", time === null ? "-:--.---" : lapTime(time), { step: "meta", font: "mono", color: token(time === null ? "inkFaint" : "ink"), nowrap: true });
             const d = sp.delta ?? null;
             if (d !== null) kit.label("Delta", deltaText(d), { step: "meta", font: "mono", color: deltaInk(d), nowrap: true });
           });
@@ -276,11 +280,11 @@ export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResu
     kit.row("Speed", { gap: t.sm, cross: "end", width: grow(), align: "end" }, () => {
       kit.label("Value", `${Math.round(desc.speed ?? 0)}`, { step: "displayXl2", font: "display", nowrap: true });
       kit.column("Side", { cross: "end" }, () => {
-        kit.label("Gear", desc.gear ?? "N", { step: "xl", font: "mono", color: token("accentInk"), nowrap: true });
-        kit.label("Unit", desc.unit ?? "km/h", { step: "meta", color: token("fgMuted"), nowrap: true });
+        kit.label("Gear", desc.gear ?? "N", { step: "xl", font: "mono", color: token("highlight"), nowrap: true });
+        kit.label("Unit", desc.unit ?? "km/h", { step: "meta", color: token("inkMuted"), nowrap: true });
       });
     });
-    kit.meter("Rev", desc.speed ?? 0, desc.maxSpeed ?? 300, { kind: "accent", width: grow(), height: 6 });
+    kit.meter("Rev", desc.speed ?? 0, desc.maxSpeed ?? 300, { kind: "primary", width: grow(), height: 6 });
     if (boost !== null) kit.meter("Boost", boost, 1, { color: token("info"), label: boostLabel, width: grow(), segments: 4 });
   });
   if (showTouch) {

package/src/ui-kit/menus.ts

@@ -36,17 +36,17 @@ export function mainMenu(id: string, desc: Api.MainMenuDesc = {}): Api.MenuResul
     cross: "center",
     width: phone ? grow() : px(380),
     padding: all(phone ? t.lg : t.xl),
-    background: token("materialThick"),
+    background: token("hud"),
     radius: t.panel,
     instant: desc.instant ?? false,
   }, () => {
     kit.column("Heading", { gap: t.xs, cross: "center", width: grow() }, () => {
       kit.label("Title", desc.title ?? "", { step: phone ? "displayMd" : "displayLg", font: "display", align: "center", width: grow(), heading: true });
-      if (desc.subtitle) kit.label("Subtitle", desc.subtitle, { color: token("fgMuted"), align: "center", width: grow() });
+      if (desc.subtitle) kit.label("Subtitle", desc.subtitle, { color: token("inkMuted"), align: "center", width: grow() });
     });
     // A title menu is not a dialog, so it takes the focus itself: Enter and the pad's A answer at once.
     chosen = menuColumn("Items", items, grow(), true);
-    if (desc.footer) kit.label("Footer", desc.footer, { step: "meta", color: token("fgSubtle"), align: "center", width: grow() });
+    if (desc.footer) kit.label("Footer", desc.footer, { step: "meta", color: token("inkFaint"), align: "center", width: grow() });
   });
   if (chosen !== null) desc.onSelect?.(chosen);
   return { selected: chosen };
@@ -68,7 +68,7 @@ export function confirmDialog(id: string, desc: Api.ConfirmDesc = {}): Api.Confi
   let confirmed = false;
   let cancelled = false;
   const m = kit.modal(id, desc.open ?? false, { title: desc.title ?? "" }, () => {
-    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("fgMuted"), width: grow() });
+    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("inkMuted"), width: grow() });
     kit.row("Actions", { width: grow(), gap: t.sm, align: "end", padding: { left: 0, top: t.sm, right: 0, bottom: 0 } }, () => {
       if ((kit.button("Cancel", desc.cancelLabel ?? "Cancel", {}) as Api.Response).clicked) cancelled = true;
       if ((kit.button("Confirm", desc.confirmLabel ?? "Confirm", { variant: desc.danger ? "danger" : "primary" }) as Api.Response).clicked) confirmed = true;
@@ -82,7 +82,7 @@ export function alertDialog(id: string, desc: Api.AlertDesc = {}): boolean {
   const { t } = frame();
   let done = false;
   const m = kit.modal(id, desc.open ?? false, { title: desc.title ?? "" }, () => {
-    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("fgMuted"), width: grow() });
+    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("inkMuted"), width: grow() });
     kit.row("Actions", { width: grow(), align: "end", padding: { left: 0, top: t.sm, right: 0, bottom: 0 } }, () => {
       if ((kit.button("Ok", desc.okLabel ?? "OK", { variant: "primary" }) as Api.Response).clicked) done = true;
     });
@@ -94,7 +94,7 @@ export function loadingScreen(id: string, desc: Api.LoadingDesc = {}): void {
   const { t } = frame();
   const tips = desc.tips ?? [];
   const tip = tips.length > 0 ? tips[Math.floor(kit.seconds() / Math.max(1, desc.tipSeconds ?? 4)) % tips.length]! : "";
-  kit.modal(id, true, { locked: true, bare: true, backdrop: token("bg"), transition: "fade", width: px(Math.min(380, frame().viewport.width - 32)) }, () => {
+  kit.modal(id, true, { locked: true, bare: true, backdrop: token("backdrop"), transition: "fade", width: px(Math.min(380, frame().viewport.width - 32)) }, () => {
     kit.label("Title", desc.title ?? "Loading", { step: "xl", align: "center", width: grow(), heading: true });
     const p = desc.progress;
     if (p === null || p === undefined) {
@@ -103,10 +103,10 @@ export function loadingScreen(id: string, desc: Api.LoadingDesc = {}): void {
       // A real value only: the bar never runs ahead of what loaded.
       kit.row("Bar", { width: grow(), gap: t.md, cross: "center" }, () => {
         kit.progress("Progress", p, { width: grow() });
-        kit.label("Percent", `${Math.floor(Math.max(0, Math.min(1, p)) * 100)}%`, { step: "meta", font: "mono", color: token("fgMuted"), nowrap: true });
+        kit.label("Percent", `${Math.floor(Math.max(0, Math.min(1, p)) * 100)}%`, { step: "meta", font: "mono", color: token("inkMuted"), nowrap: true });
       });
     }
-    if (tip) kit.label("Tip", tip, { step: "reading", color: token("fgMuted"), align: "center", width: grow() });
+    if (tip) kit.label("Tip", tip, { step: "reading", color: token("inkMuted"), align: "center", width: grow() });
   });
 }
 
@@ -118,7 +118,7 @@ function stars(id: string, earned: number, max: number, since: number, size: num
       const shown = kit.seconds() - since >= 0.3 * (k + 1);
       const on = k < earned;
       kit.transition(kit.idi("Star", k), shown, { kind: "scale", instant: false }, () => {
-        iconOr("Mark", "star", size, token(on ? "accent" : "fillStrong"));
+        iconOr("Mark", "star", size, token(on ? "primary" : "controlStrong"));
         if (on) kit.burst({ delayMs: 120 });
       });
       if (!shown) kit.spacer(kit.idi("Gap", k), px(size));
@@ -147,7 +147,7 @@ export function resultsScreen(id: string, desc: Api.ResultsDesc = {}): Api.MenuR
     const max = desc.maxStars ?? 3;
     if (max > 0) kit.row("StarRow", { width: grow(), align: "center" }, () => stars("Stars", desc.stars ?? 0, max, since, 44));
     kit.column("ScoreBlock", { width: grow(), cross: "center", gap: t.xxs }, () => {
-      if (desc.scoreLabel) kit.label("ScoreLabel", desc.scoreLabel, { step: "meta", color: token("fgMuted"), align: "center", width: grow(), nowrap: true });
+      if (desc.scoreLabel) kit.label("ScoreLabel", desc.scoreLabel, { step: "meta", color: token("inkMuted"), align: "center", width: grow(), nowrap: true });
       if (time) {
         // A time counts up as a clock (ease-out cubic over the same 0.9 s), the headline in m:ss.mmm.
         const k = open ? Math.min(1, Math.max(0, (kit.seconds() - since) / 0.9)) : 1;
@@ -158,8 +158,8 @@ export function resultsScreen(id: string, desc: Api.ResultsDesc = {}): Api.MenuR
       }
       if (!time || best > 0 || desc.newBest) {
         kit.row("BestRow", { gap: t.sm, cross: "center" }, () => {
-          if (!time || best > 0) kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", time ? lapTime(best) : fmt(best)), { step: "meta", color: token("fgMuted"), nowrap: true });
-          if (desc.newBest) kit.transition("Reveal", landed, { kind: "pop" }, () => kit.badge("NewBest", desc.newBestLabel ?? "New best", "accent"));
+          if (!time || best > 0) kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", time ? lapTime(best) : fmt(best)), { step: "meta", color: token("inkMuted"), nowrap: true });
+          if (desc.newBest) kit.transition("Reveal", landed, { kind: "pop" }, () => kit.badge("NewBest", desc.newBestLabel ?? "New best", "primary"));
         });
       }
     });

package/src/ui-kit/settings.ts

@@ -40,7 +40,7 @@ function sliderRow(id: string, label: string, value: number, desc: Api.SliderDes
     kit.label("Label", label, { width: px(phone ? 96 : 140), nowrap: true });
     const r = kit.slider("Slider", value, desc) as Api.SliderResult;
     out = r.value;
-    kit.label("Value", shown, { width: px(48), align: "end", font: "mono", color: token("fgMuted"), nowrap: true });
+    kit.label("Value", shown, { width: px(48), align: "end", font: "mono", color: token("inkMuted"), nowrap: true });
   });
   return out;
 }
@@ -82,7 +82,7 @@ export function settingsScreen(id: string, desc: Api.SettingsDesc = {}): Api.Set
         }
         case "graphics": {
           const quality = desc.qualityLabel ?? "Quality";
-          kit.label("QualityLabel", quality, { step: "meta", color: token("fgMuted") });
+          kit.label("QualityLabel", quality, { step: "meta", color: token("inkMuted") });
           const levels = [desc.lowLabel ?? "Low", desc.mediumLabel ?? "Medium", desc.highLabel ?? "High"];
           const q = kit.radio("Quality", levels, QUALITIES.indexOf(s.quality), { horizontal: !phone, label: quality });
           s.quality = QUALITIES[q.selected] ?? "medium";

package/src/ui-kit/store.ts

@@ -4,7 +4,7 @@
 
 import type * as Api from "@origingame/engine";
 import { kit } from "./bind.ts";
-import { capsule, fit, fmt, frame, grow, iconOr, px, token } from "./util.ts";
+import { hudBox, fit, fmt, frame, grow, iconOr, px, token } from "./util.ts";
 
 /** A screen panel: a dialog over the game, wide on desktop, full width on a phone. With `scrim` a press on the backdrop closes it too. */
 function screen(id: string, title: string, width: number, build: () => void, scrim = false): boolean {
@@ -16,7 +16,7 @@ function screen(id: string, title: string, width: number, build: () => void, scr
 /** An item's picture: its icon, else its initial on the slot. */
 function picture(id: string, icon: string | undefined, name: string, size: number): void {
   if (icon && kit.hasIcon(icon)) kit.icon(id, icon, { size });
-  else kit.label(id, name.slice(0, 1).toUpperCase(), { step: "xl2", font: "display", color: token("fgMuted"), nowrap: true });
+  else kit.label(id, name.slice(0, 1).toUpperCase(), { step: "xl2", font: "display", color: token("inkMuted"), nowrap: true });
 }
 
 export function shopScreen(id: string, desc: Api.ShopDesc = {}): Api.ShopResult {
@@ -37,10 +37,10 @@ export function shopScreen(id: string, desc: Api.ShopDesc = {}): Api.ShopResult
       } else {
         kit.spacer("Gap", null);
       }
-      capsule("Balance", () => {
-        if (desc.currencyIcon) iconOr("Icon", desc.currencyIcon, 18, token("accent"));
+      hudBox("Balance", () => {
+        if (desc.currencyIcon) iconOr("Icon", desc.currencyIcon, 18, token("gold"));
         kit.counter("Amount", balance, { font: "mono", step: "base" });
-        kit.label("Unit", desc.currency ?? "coins", { step: "base", color: token("fgMuted"), nowrap: true });
+        kit.label("Unit", desc.currency ?? "coins", { step: "base", color: token("inkMuted"), nowrap: true });
       });
     });
     const body = (): void => {
@@ -49,17 +49,17 @@ export function shopScreen(id: string, desc: Api.ShopDesc = {}): Api.ShopResult
         picture("Picture", it.icon, it.name ?? "", 36);
         kit.label("Name", it.name ?? "", { step: "base", nowrap: true });
         if (it.owned) kit.badge("Owned", desc.ownedLabel ?? "Owned", "success");
-        else kit.label("Price", fmt(it.price ?? 0), { step: "meta", font: "mono", color: token(balance >= (it.price ?? 0) ? "accentInk" : "fgSubtle"), nowrap: true });
+        else kit.label("Price", fmt(it.price ?? 0), { step: "meta", font: "mono", color: token(balance >= (it.price ?? 0) ? "highlight" : "inkFaint"), nowrap: true });
       });
       if (g.clicked !== null && g.clicked !== undefined) sel = g.clicked;
       const it = items[sel];
       kit.column("Detail", { width: phone ? grow() : px(220), gap: t.sm }, () => {
         if (!it) {
-          kit.label("Empty", desc.emptyLabel ?? "Nothing for sale here", { color: token("fgMuted") });
+          kit.label("Empty", desc.emptyLabel ?? "Nothing for sale here", { color: token("inkMuted") });
           return;
         }
         kit.label("Name", it.name ?? "", { step: "lg", width: grow() });
-        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("fgMuted"), width: grow() });
+        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("inkMuted"), width: grow() });
         kit.keyValue("Price", desc.priceLabel ?? "Price", `${fmt(it.price ?? 0)} ${desc.currency ?? "coins"}`, true);
         const short = balance < (it.price ?? 0);
         // Short of the price, Buy still answers: it refuses, shaking with the error sound.
@@ -101,7 +101,7 @@ export function inventoryScreen(id: string, desc: Api.InventoryDesc = {}): Api.I
         const it = bySlot.get(i);
         if (!it) return;
         picture("Picture", it.icon, it.name ?? "", cell * 0.5);
-        if ((it.count ?? 0) > 1) kit.label("Count", `${it.count}`, { step: "xs", font: "mono", color: token("fgMuted"), nowrap: true });
+        if ((it.count ?? 0) > 1) kit.label("Count", `${it.count}`, { step: "xs", font: "mono", color: token("inkMuted"), nowrap: true });
       });
       if (g.clicked !== null && g.clicked !== undefined) sel = g.clicked;
       if (g.dropFrom !== null && g.dropFrom !== undefined && g.dropTo !== null && g.dropTo !== undefined && bySlot.has(g.dropFrom)) {
@@ -111,11 +111,11 @@ export function inventoryScreen(id: string, desc: Api.InventoryDesc = {}): Api.I
       const it = sel >= 0 ? bySlot.get(sel) : undefined;
       kit.column("Detail", { width: phone ? grow() : px(200), gap: t.sm }, () => {
         if (!it) {
-          kit.label("Hint", desc.hintLabel ?? "Select an item. Drag it to another slot to move it.", { step: "meta", color: token("fgMuted"), width: grow() });
+          kit.label("Hint", desc.hintLabel ?? "Select an item. Drag it to another slot to move it.", { step: "meta", color: token("inkMuted"), width: grow() });
           return;
         }
         kit.label("Name", it.name ?? "", { step: "lg", width: grow() });
-        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("fgMuted"), width: grow() });
+        if (it.description) kit.label("Description", it.description, { step: "meta", color: token("inkMuted"), width: grow() });
         if ((it.count ?? 0) > 1) kit.keyValue("Count", desc.countLabel ?? "Count", `${it.count}`, true);
         if (desc.useLabel !== "") {
           if ((kit.button("Use", desc.useLabel ?? "Use", { variant: "primary", width: grow() }) as Api.Response).clicked) out.used = it.id ?? null;
@@ -143,8 +143,8 @@ export function levelSelect(id: string, desc: Api.LevelSelectDesc = {}): Api.Lev
   // Back from every input: the button, a press on the scrim, Escape, B.
   out.closed = screen(id, desc.title ?? "Levels", 720, () => {
     kit.row("Total", { gap: t.xs, cross: "center" }, () => {
-      iconOr("Star", "star", 18, token("accent"), starsLabel(earned, levels.length * 3));
-      kit.label("Count", `${earned} / ${levels.length * 3}`, { font: "mono", color: token("fgMuted"), nowrap: true });
+      iconOr("Star", "star", 18, token("primary"), starsLabel(earned, levels.length * 3));
+      kit.label("Count", `${earned} / ${levels.length * 3}`, { font: "mono", color: token("inkMuted"), nowrap: true });
     });
     // A numeral is the card's face, in display type on a square card; a
     // name takes a wider card and a smaller step, wrapped to two lines (cut
@@ -157,14 +157,14 @@ export function levelSelect(id: string, desc: Api.LevelSelectDesc = {}): Api.Lev
       const l = levels[i]!;
       const name = l.name ?? `${i + 1}`;
       if (l.locked) {
-        iconOr("Lock", "lock", 28, token("fgSubtle"), (desc.lockedLabel ?? "{name}, locked").replaceAll("{name}", name));
+        iconOr("Lock", "lock", 28, token("inkFaint"), (desc.lockedLabel ?? "{name}, locked").replaceAll("{name}", name));
         return;
       }
       if ([...name].length > 3) kit.label("Name", name, { step: phone ? "base" : "lg", font: "display", align: "center", width: grow(), maxLines: 2, ellipsis: true });
       else kit.label("Name", name, { step: "xl3", font: "display", nowrap: true });
       const stars = Math.min(3, l.stars ?? 0);
       kit.row("Stars", { gap: 2 }, () => {
-        for (let k = 0; k < 3; k++) iconOr(kit.idi("Star", k), "star", 14, token(k < stars ? "accent" : "fillStrong"), k === 0 ? starsLabel(stars, 3) : "");
+        for (let k = 0; k < 3; k++) iconOr(kit.idi("Star", k), "star", 14, token(k < stars ? "primary" : "controlStrong"), k === 0 ? starsLabel(stars, 3) : "");
       });
     });
     if (g.clicked !== null && g.clicked !== undefined && !levels[g.clicked]?.locked) out.chosen = g.clicked;
@@ -176,7 +176,7 @@ export function levelSelect(id: string, desc: Api.LevelSelectDesc = {}): Api.Lev
   return out;
 }
 
-const MEDALS: readonly Api.ThemeColor[] = ["warn", "fgMuted", "accentInk"];
+const MEDALS: readonly Api.ThemeColor[] = ["warn", "inkMuted", "highlight"];
 
 export function leaderboardScreen(id: string, desc: Api.LeaderboardDesc = {}): Api.LeaderboardResult {
   const { t, phone } = frame();
@@ -203,14 +203,14 @@ export function leaderboardScreen(id: string, desc: Api.LeaderboardDesc = {}): A
       });
     } else if (entries.length === 0) {
       kit.column("Empty", { width: grow(), height, align: "center", cross: "center" }, () => {
-        kit.label("Message", desc.empty ?? "No scores yet", { color: token("fgMuted"), align: "center", width: grow() });
+        kit.label("Message", desc.empty ?? "No scores yet", { color: token("inkMuted"), align: "center", width: grow() });
       });
     } else {
       const player = entries.findIndex((e) => e.player);
       kit.list("Rows", { count: entries.length, rowHeight: t.row, height, width: grow(), selected: player >= 0 ? player : null }, (i) => {
         const e = entries[i]!;
         const rank = e.rank ?? i + 1;
-        kit.label("Rank", `${rank}`, { width: px(40), font: "mono", step: rank <= 3 ? "lg" : "body", color: token(rank <= 3 ? MEDALS[rank - 1]! : "fgMuted"), nowrap: true });
+        kit.label("Rank", `${rank}`, { width: px(40), font: "mono", step: rank <= 3 ? "lg" : "body", color: token(rank <= 3 ? MEDALS[rank - 1]! : "inkMuted"), nowrap: true });
         kit.label("Name", e.name ?? "", { width: grow(), nowrap: true });
         kit.label("Score", e.score ?? "", { font: "mono", nowrap: true });
       });

package/src/ui-kit/story.ts

@@ -15,8 +15,10 @@ export function cutscene(id: string, desc: Api.CutsceneDesc = {}): Api.CutsceneR
   kit.setNavigation(true);
   const letterbox = desc.letterbox ?? true;
   if (letterbox) {
+    // Cinematic bars are black in every style: not a token, which a light
+    // style (kestrel's paper) would turn into cream panels.
     for (const [name, anchor] of [["Top", "top"], ["Bottom", "bottom"]] as const) {
-      kit.anchor(`${id}.${name}`, { anchor, margin: 0, width: grow(), height: pct(0.1), background: token("stage") }, () => {});
+      kit.anchor(`${id}.${name}`, { anchor, margin: 0, width: grow(), height: pct(0.1), background: { color: { r: 0, g: 0, b: 0 } } }, () => {});
     }
   }
   const line = lines[index]!;
@@ -68,13 +70,13 @@ export function tutorialOverlay(id: string, desc: Api.TutorialDesc = {}): Api.Tu
     direction: "column",
     gap: t.sm,
     padding: all(t.lg),
-    background: token("surfaceRaised"),
+    background: token("panelRaised"),
     radius: t.panel,
   }, () => {
     const count = (desc.stepLabel ?? "{step} of {count}").replaceAll("{step}", `${index + 1}`).replaceAll("{count}", `${steps.length}`);
-    kit.label("Count", count, { step: "meta", color: token("fgMuted") });
+    kit.label("Count", count, { step: "meta", color: token("inkMuted") });
     if (step.title) kit.label("Title", step.title, { step: "lg", width: grow() });
-    if (step.text) kit.label("Text", step.text, { step: "reading", color: token("fgMuted"), width: grow() });
+    if (step.text) kit.label("Text", step.text, { step: "reading", color: token("inkMuted"), width: grow() });
     kit.row("Actions", { width: grow(), gap: t.sm, align: "spaceBetween", cross: "center" }, () => {
       if ((kit.button("Skip", desc.skipLabel ?? "Skip", { variant: "quiet", size: "small" }) as Api.Response).clicked) out.skipped = true;
       const lastStep = index + 1 >= steps.length;

package/src/ui-kit/util.ts

@@ -1,5 +1,5 @@
 // Small helpers the screen templates share: sizes, insets, the frame's
-// tokens, number and time formats, and HUD capsules. Nothing here keeps
+// tokens, number and time formats, and HUD boxes. Nothing here keeps
 // state: what must persist lives in the UI's memory (og.ui.memory).
 
 import type * as Api from "@origingame/engine";
@@ -25,7 +25,7 @@ export function frame(): { theme: Api.UiTheme; viewport: Api.Viewport; t: Tokens
 
 export interface Tokens {
   xxs: number; xs: number; sm: number; md: number; lg: number; xl: number; xxl: number; xl3: number;
-  card: number; panel: number; block: number; button: number;
+  small: number; control: number; bar: number; panel: number;
   controlSm: number; controlMd: number; controlLg: number; gutter: number; row: number;
 }
 
@@ -34,7 +34,7 @@ function tokens(t: Api.UiTheme): Tokens {
   const r = (k: string): number => t.radius[k] ?? 0;
   return {
     xxs: s("xxs"), xs: s("xs"), sm: s("sm"), md: s("md"), lg: s("lg"), xl: s("xl"), xxl: s("xxl"), xl3: s("xl3"),
-    card: r("card"), panel: r("panel"), block: r("block"), button: r("button"),
+    small: r("small"), control: r("control"), bar: r("bar"), panel: r("panel"),
     controlSm: t.sizes.controlSm, controlMd: t.sizes.controlMd, controlLg: t.sizes.controlLg, gutter: t.sizes.gutter, row: t.sizes.row,
   };
 }
@@ -73,17 +73,17 @@ export function lapTime(seconds: number): string {
   return `${m}:${s.toString().padStart(2, "0")}.${(ms % 1000).toString().padStart(3, "0")}`;
 }
 
-/** A HUD capsule: a translucent dark pill (material-thick) that keeps text legible over any art. */
-export function capsule(id: string, build: () => void, desc: { gap?: number; padX?: number; height?: number } = {}): Api.Response {
+/** A HUD box: the style's `hud` fill and frame, cornered by its control radius, that keeps text legible over any art. */
+export function hudBox(id: string, build: () => void, desc: { gap?: number; padX?: number; height?: number } = {}): Api.Response {
   const { t } = frame();
   return kit.row(id, {
     padding: xy(desc.padX ?? t.md, 0),
     height: px(desc.height ?? t.controlMd),
     gap: desc.gap ?? t.sm,
     cross: "center",
-    background: token("materialThick"),
-    radius: t.button,
-    frame: "capsule",
+    background: token("hud"),
+    radius: t.control,
+    frame: "hud",
   }, build) as Api.Response;
 }