@trading-game/design-intelligence-layer 0.12.3 → 0.13.0

package/guides/design-system-guide/trading-game-ds-guide.md

@@ -131,29 +131,43 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 | CSS Variable          | Tailwind Class      | Usage                     |
 | --------------------- | ------------------- | ------------------------- |
 | `--primary`           | `bg-primary` / `text-primary` | Primary CTA, brand color, interactive elements |
+| `--on-primary`        | `text-on-primary`             | Text/icon color paired with `bg-primary` (always white) |
 | `--primary-hover`     | `bg-primary-hover`  | Hover & pressed states on primary elements |
+| `--primary-inverse`   | `bg-primary-inverse`          | Inverted primary surface — white bg for use on dark/coloured areas |
+| `--on-primary-inverse`| `text-on-primary-inverse`     | Text/icon color paired with `bg-primary-inverse` (always blue) |
 
 ### 2.3 — Semantic (Trading Status)
 
+> **Naming convention:** every surface token has a paired `--on-<name>` foreground (text/icon) token. Use the pair together (`bg-semantic-X` + `text-on-semantic-X`) for guaranteed legibility on the saturated surface.
+
 | CSS Variable               | Tailwind Class                              | Usage                                         |
 | -------------------------- | ------------------------------------------- | --------------------------------------------- |
-| `--semantic-win`           | `text-semantic-win` / `bg-semantic-win`     | Win / Profit / Positive outcomes              |
-| `--semantic-loss`          | `text-semantic-loss` / `bg-semantic-loss`   | Loss / Negative outcomes                      |
-| `--semantic-warning`       | `text-semantic-warning` / `bg-semantic-warning` | Warning / Caution / Non-destructive alerts |
-| `--semantic-info`          | `text-semantic-info` / `bg-semantic-info`   | Informational alerts                          |
-| `--semantic-credit`        | `bg-semantic-credit`                        | Credit / bonus badge background (`#F9840F` amber-orange) |
-| `--semantic-credit-text`   | `text-semantic-credit-text`                 | Credit / bonus badge foreground (`#713813` dark amber) |
+| `--semantic-win`           | `bg-semantic-win` / `text-semantic-win`     | Win / Profit / Positive outcomes              |
+| `--on-semantic-win`        | `text-on-semantic-win`                      | Text/icon on `bg-semantic-win` surfaces (white) |
+| `--semantic-loss`          | `bg-semantic-loss` / `text-semantic-loss`   | Loss / Negative outcomes                      |
+| `--on-semantic-loss`       | `text-on-semantic-loss`                     | Text/icon on `bg-semantic-loss` surfaces (white) |
+| `--semantic-warning`       | `bg-semantic-warning` / `text-semantic-warning` | Warning / Caution / Non-destructive alerts |
+| `--on-semantic-warning`    | `text-on-semantic-warning`                  | Text/icon on `bg-semantic-warning` surfaces (white) |
+| `--semantic-info`          | `bg-semantic-info` / `text-semantic-info`   | Informational alerts                          |
+| `--semantic-boost`         | `bg-semantic-boost`                         | Boost / bonus badge background (`#F9840F` amber-orange) |
+| `--on-semantic-boost`      | `text-on-semantic-boost`                    | Boost / bonus badge foreground (`#713813` dark amber) |
 
 > All semantic tokens support opacity variants (e.g. `bg-semantic-warning/10` for tinted backgrounds). For structured alpha surfaces, use the primitive alpha scales — see Section 2.10.
 
 ### 2.4 — Text & Icon Colors
 
-| CSS Variable                    | Tailwind Class                          | Usage                     |
-| ------------------------------- | --------------------------------------- | ------------------------- |
-| `--on-prominent`                | `text-on-prominent`                     | Primary text (headings, body) |
-| `--on-prominent-static-inverse` | `text-on-prominent-static-inverse`      | Always-white text (e.g. on primary blue buttons) |
-| `--on-subtle`                   | `text-on-subtle`                        | Secondary text (descriptions, labels) |
-| `--on-disabled`                 | `text-on-disabled`                      | Disabled text (inactive controls, placeholders) |
+The system follows a Material-style `<surface>` / `on-<surface>` pair convention: no prefix = surface/background, `on-` prefix = the foreground (text/icon) color paired with that surface.
+
+| CSS Variable              | Tailwind Class                | Usage                     |
+| ------------------------- | ----------------------------- | ------------------------- |
+| `--prominent`             | `bg-prominent`                | Light surface (page chrome, cards) |
+| `--on-prominent`          | `text-on-prominent`           | Text/icon on `bg-prominent` (black) |
+| `--prominent-inverse`     | `bg-prominent-inverse`        | Dark surface for use on light pages (e.g. toasts) |
+| `--on-prominent-inverse`  | `text-on-prominent-inverse`   | Text/icon on `bg-prominent-inverse` (white) |
+| `--on-subtle`             | `text-on-subtle`              | Secondary text (descriptions, labels) — paired with `bg-subtle` |
+| `--on-disabled`           | `text-on-disabled`            | Disabled text (inactive controls, placeholders) |
+
+> **Deprecated aliases:** `--on-prominent-static-inverse` and `--surface-inverse-static` remain defined in CSS for backwards-compat with external consumers using raw `var()` references, but internal components no longer use them — prefer the explicit `on-<surface>` / `<surface>-inverse` pairs above.
 
 ### 2.5 — Borders & Inputs
 
@@ -275,7 +289,7 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 | Show WIN / profit / positive           | `text-semantic-win`               | Primary blue for profit                |
 | Show LOSS / negative                   | `text-semantic-loss`              | Any non-token red                      |
 | Show WARNING / caution                 | `text-semantic-warning`           | Raw orange hex or primary tint         |
-| Show a credit / bonus badge            | `<Badge variant="fill-credit">` (uses `bg-semantic-credit` + `text-semantic-credit-text`) | Hardcoded amber hex values |
+| Show a boost / bonus badge             | `<Badge variant="fill-boost">` (uses `bg-semantic-boost/16` + `text-on-semantic-boost`) | Hardcoded amber hex values |
 | Color a tab container background       | `bg-tabs`                         | `bg-subtle` for tabs                   |
 | Color an active/selected tab           | `bg-tabs-active`                  | `bg-prominent` for active tab          |
 | Color a page background                | `bg-prominent`                    | `bg-white` directly                    |
@@ -293,7 +307,9 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 | Pick a heading font                    | `font-display`                    | System fonts, raw font-family names    |
 | Pick a body font                       | `font-body`                       | Raw font-family names                  |
 | Style button text                      | `font-display font-bold`, sentence case | `uppercase` on buttons           |
-| Write white text on a dark surface     | `text-on-prominent-static-inverse`| `text-white` or raw white hex          |
+| Write text on a primary blue surface   | `text-on-primary`                 | `text-white` or `text-on-prominent-static-inverse` |
+| Write text on a dark inverse surface   | `text-on-prominent-inverse`       | `text-white` or raw white hex          |
+| Write text on a semantic surface       | `text-on-semantic-win` / `-loss` / `-warning` / `-boost` | `text-white` (the surface may not always be dark) |
 
 ---
 
@@ -393,13 +409,13 @@ The design system uses a custom radius scale (base = 10px). Use these named toke
 
 ### 6.1 — Variants
 
-| Variant              | Background                        | Text Color                         | Border                                   | Hover                                    | Use on         |
-| -------------------- | --------------------------------- | ---------------------------------- | ---------------------------------------- | ---------------------------------------- | -------------- |
-| `primary`            | `bg-primary`                      | `text-on-prominent-static-inverse` | none                                     | `bg-primary-hover`                       | Light surfaces |
-| `primary-inverse`    | `bg-on-prominent-static-inverse`  | `text-primary`                     | none                                     | `bg-on-prominent-static-inverse/80`      | Dark/coloured surfaces |
-| `secondary`          | transparent                       | `text-on-prominent`                | `border-[1.5px] border-border-prominent` | `bg-secondary-hover`                     | Light surfaces |
-| `secondary-inverse`  | transparent                       | `text-on-prominent-static-inverse` | `border-[1.5px] border-on-prominent-static-inverse` | `bg-on-prominent-static-inverse/10` | Dark/coloured surfaces |
-| `tertiary`           | transparent                       | `text-primary`                     | none                                     | `bg-primary/[0.08]`                      | Light surfaces |
+| Variant              | Background           | Text Color                  | Border                                   | Hover                       | Use on                 |
+| -------------------- | -------------------- | --------------------------- | ---------------------------------------- | --------------------------- | ---------------------- |
+| `primary`            | `bg-primary`         | `text-on-primary`           | none                                     | `bg-primary-hover`          | Light surfaces         |
+| `primary-inverse`    | `bg-primary-inverse` | `text-on-primary-inverse`   | none                                     | `bg-primary-inverse/80`     | Dark/coloured surfaces |
+| `secondary`          | transparent          | `text-on-prominent`         | `border-[1.5px] border-border-prominent` | `bg-secondary-hover`        | Light surfaces         |
+| `secondary-inverse`  | transparent          | `text-on-prominent-inverse` | `border-[1.5px] border-primary-inverse`  | `bg-primary-inverse/10`     | Dark/coloured surfaces |
+| `tertiary`           | transparent          | `text-primary`              | none                                     | `bg-primary/[0.08]`         | Light surfaces         |
 
 ### 6.2 — Sizes
 
@@ -551,7 +567,7 @@ import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, Dialog
 | Sidebar | [complex] | SidebarProvider, SidebarTrigger, SidebarInset, SidebarHeader, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupLabel, SidebarGroupContent, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarRail, useSidebar |
 | Skeleton | [simple] | — |
 | Slider | [simple] | — |
-| Sonner (Toaster) | [simple] | — (also import `toast` from `sonner`) |
+| Toast | [simple] | `Toaster`, `toast` — import both from `@trading-game/design-intelligence-layer` (the toaster wraps `sonner` internally; `toast` is re-exported so consumers don't need to import the underlying library) |
 | Spinner | [simple] | — |
 | Stepper | [simple] | — |
 | Switch | [simple] | — |
@@ -559,7 +575,7 @@ import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, Dialog
 | Tabs | [composed] | TabsList (`variant`: default/line, `size`: sm/md/lg), TabsTrigger (`iconPosition`: inline/top), TabsContent. Root accepts `orientation`: horizontal/vertical. |
 | Textarea | [simple] | — |
 | TicketCard | [composed] | — (`icon`, `label`, `value`, `currency`, `stubLabel`, `onStubClick`, `stubDisabled`, `compact`) |
-| CreditTicketCard | [composed] | — (`icon`, `label`, `value`, `currency`, `stubLabel`, `onStubClick`, `stubDisabled`, `creditAmount`, `creditCurrency`, `compact`) — use when a credit badge must appear below the value |
+| BoostTicketCard | [composed] | — (`icon`, `label`, `value`, `currency`, `stubLabel`, `onStubClick`, `stubDisabled`, `boostAmount`, `boostCurrency`, `compact`) — use when a boost badge must appear below the value |
 | Toggle | [simple] | — |
 | ToggleGroup | [composed] | ToggleGroupItem |
 | Tooltip | [composed] | TooltipTrigger, TooltipContent, TooltipProvider |
@@ -576,7 +592,7 @@ These are styling behaviors you can't discover from TypeScript types alone:
 | InputGroup | Wraps `Input` with inline addons (icons, buttons, text). **Sizes:** `sm` (h-8) / `md` (h-10, default) / `lg` (h-12) — pass `size` to `InputGroup`, it flows to `InputGroupInput` via context. **Padding:** when any `inline-start` or `inline-end` addon is present, input text gets equal `pl-2 pr-2` (8px) on both sides for visual symmetry. Without addons, Input's default `px-3`/`px-4` applies. |
 | InputOTP | **Variants:** OTP 4 digits (single group, 4 slots), OTP 6 digits (single group, 6 slots), OTP 6 split (two groups of 3 with `InputOTPSeparator`), OTP 8 digits (single group, 8 slots), OTP 6 separated (each slot in its own `InputOTPGroup` for individually spaced boxes). Slot: `h-9 w-9`, `border-border-subtle`, `rounded-sm` on first/last. Focus: `border-primary` + `ring-primary/[0.08]`. |
 | NavigationButton | Icon-only tertiary button for navigation. `text-on-prominent` (black icons), `hover:bg-secondary-hover`. **Sizes (8-point grid):** `lg` 48px / 24px icon, `md` 40px / 20px icon, `sm` 32px / 20px icon, `xs` 24px / 16px icon. States: focus `ring-ring/50`, active `opacity-60`, disabled `opacity-24`. Supports `asChild`. |
-| Tooltip | Bubble: `bg-primary` + `text-on-prominent-static-inverse` (not `bg-popover`). Always wrap in `<TooltipProvider>` |
+| Tooltip | Bubble: `bg-primary` + `text-on-primary` (not `bg-popover`). Always wrap in `<TooltipProvider>` |
 | Sidebar | Menu buttons use `rounded-sm`. Selection: `bg-secondary-hover` + `text-primary` + `font-semibold` |
 | Breadcrumb | Active page: `text-primary font-medium`. Links: `text-on-subtle` |
 | Tabs | **Variants:** `default` (pill, `bg-tabs`) and `line` (underline, transparent bg). **Sizes:** `sm` (h-8, text-xs), `md` (h-10, text-sm, default), `lg` (h-12, text-base). **Icon position:** `inline` (default) or `top` (stacks icon above label). **Orientation:** `horizontal` (default) or `vertical` (line variant renders left-edge indicator). Hover: `bg-secondary-hover` (default) / `text-primary` (line). Selected: `bg-tabs-active` + `text-primary font-semibold`. Line variant underline: `bg-primary`. |
@@ -588,9 +604,9 @@ These are styling behaviors you can't discover from TypeScript types alone:
 | Slider | Thumb: square `rounded-[4px]`, `bg-primary`. Track range: `bg-slider-range` |
 | Dialog/Sheet | Footer buttons should use `size="md"`. Overlay: `bg-overlay` |
 | Menubar | Hover: `bg-primary/[0.08]`. Open state: `bg-primary/10` |
-| Badge | Variants: `default` (solid blue), `default-success`, `default-fail`; `fill` (blue tint), `fill-success`, `fill-fail`, `fill-warning`; `fill-credit` (amber-orange tint — `bg-semantic-credit/16` bg + `text-semantic-credit-text` foreground — use for credit/bonus labels, always pair with a `TicketPlus` icon); `outline`; `ghost`, `ghost-success`, `ghost-fail`. Base class no longer applies `tracking-wide` — letter spacing is default. |
-| TicketCard | **Icon:** pass any `ReactNode` via `icon`. Icon container: `size-10` rounded-full, `border-2 border-primary`, `text-primary`. **Labels:** `label` (above value) and `stubLabel` (stub button) render in sentence case — do NOT apply `uppercase` or `tracking-widest`. Stub: `w-[100px]` `bg-primary` button, `text-on-prominent-static-inverse`, shimmer sweep animation. Disabled stub: `opacity-50`, `cursor-not-allowed`. Perforation notches sit outside the card box — do NOT put `overflow-hidden` on the card wrapper. **`compact`** (default `false`): `true` = mobile layout — reduces left-content horizontal padding from `px-4 gap-4` to `px-2 gap-2`. **For credit use cases:** use `CreditTicketCard` instead — it renders a `<Badge variant="fill-credit">` inline below the value. |
-| CreditTicketCard | Same visual shell as `TicketCard` (perforation notches, tear-line, shimmer stub). The card height is **variable** (grows with content via `py-4`) rather than fixed at `h-20`. Credit is displayed as an inline `<Badge variant="fill-credit" size="sm">` with a `TicketPlus` icon: *"Credit: {creditAmount} {creditCurrency}"*. Tokens used: `bg-subtle`, `bg-primary`, `bg-primary-hover`, `text-on-prominent-static-inverse`, `bg-semantic-credit/16`, `text-semantic-credit-text`. Supports `compact` prop for mobile layout (same padding reduction as `TicketCard`). |
+| Badge | Variants: `default` (solid blue), `default-success`, `default-fail`, `default-warning` (all use `bg-semantic-*` + matching `text-on-semantic-*` foreground); `fill` (blue tint), `fill-success`, `fill-fail`, `fill-warning`; `fill-boost` (amber-orange tint — `bg-semantic-boost/16` bg + `text-on-semantic-boost` foreground — use for boost/bonus labels, always pair with a `Rocket` icon); `outline`; `ghost`, `ghost-success`, `ghost-fail`. Base class no longer applies `tracking-wide` — letter spacing is default. |
+| TicketCard | **Icon:** pass any `ReactNode` via `icon`. Icon container: `size-10` rounded-full, `border-2 border-primary`, `text-primary`. **Labels:** `label` (above value) and `stubLabel` (stub button) render in sentence case — do NOT apply `uppercase` or `tracking-widest`. Stub: `w-[100px]` `bg-primary` button, `text-on-primary`, shimmer sweep animation. Disabled stub: `opacity-50`, `cursor-not-allowed`. Perforation notches sit outside the card box — do NOT put `overflow-hidden` on the card wrapper. **`compact`** (default `false`): `true` = mobile layout — reduces left-content horizontal padding from `px-4 gap-4` to `px-2 gap-2`. **For boost use cases:** use `BoostTicketCard` instead — it renders a `<Badge variant="fill-boost">` inline below the value. |
+| BoostTicketCard | Same visual shell as `TicketCard` (perforation notches, tear-line, shimmer stub). The card height is **variable** (grows with content via `py-4`) rather than fixed at `h-20`. The boost is displayed as an inline `<Badge variant="fill-boost" size="sm">` with a leading `Rocket` icon and a trailing `Info` icon: *"Boost: {boostAmount} {boostCurrency}"*. Tokens used: `bg-subtle`, `bg-primary`, `bg-primary-hover`, `text-on-primary`, `bg-semantic-boost/16`, `text-on-semantic-boost`. Supports `compact` prop for mobile layout (same padding reduction as `TicketCard`). |
 | Toggle | Pressed: `bg-primary/10` + `border-primary` + `text-primary` |
 | Calendar | Selected: `bg-secondary-hover` + `text-primary font-bold`. Today: primary dot below date |
 
@@ -674,7 +690,8 @@ A product app top header bar. Not a landing page component — used inside the t
 | Using `bg-white` or `bg-black` | Use `bg-prominent` or `bg-overlay` |
 | Using `border-border` | Use `border-border-subtle` or `border-border-prominent` |
 | Using `bg-hover` | Use `bg-primary/[0.08]` or `bg-secondary-hover` |
-| Using `text-primary-foreground` | Use `text-on-prominent-static-inverse` |
+| Using `text-primary-foreground` | Use `text-on-primary` (the paired foreground for `bg-primary`) |
+| Using `text-on-prominent-static-inverse` for new code | Pick the paired `text-on-<surface>` for whatever surface sits behind: `text-on-primary` for `bg-primary`, `text-on-prominent-inverse` for dark inverse surfaces, `text-on-semantic-win` / `-loss` / `-warning` / `-boost` for semantic colored surfaces. The static-inverse token is kept as a deprecated alias only. |
 | Using `text-on-decorative` | Use `text-on-subtle` |
 | Using `font-mono` expecting Plus Jakarta Sans | Use `font-display` or `font-body` |
 | Using `font-bold` for headings | Use `font-semibold` (600) for headings |

package/guides/rules/design-system-consuming-project.mdc

@@ -60,23 +60,38 @@ import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
 ✅ bg-overlay             — modal/dialog backdrop (black 50%) — ONLY for overlays
 ✅ bg-primary             — brand blue #2323FF — CTAs and primary actions
 ✅ bg-primary-hover       — darker blue #0B0BD2 — primary button hover
+✅ bg-primary-inverse     — white surface for use on dark/coloured areas
+✅ bg-prominent-inverse   — dark surface for use on light pages (toasts, etc.)
 ✅ bg-secondary-hover     — light grey #EEEEEE — outline/secondary button hover
 ✅ bg-semantic-win        — green — profit/positive
 ✅ bg-semantic-loss       — red — loss/negative
+✅ bg-semantic-warning    — orange — warning/caution
+✅ bg-semantic-boost      — amber-orange #F9840F — boost/bonus badge (tinted: bg-semantic-boost/16)
 ```
 
-#### Text tokens
+#### Text tokens — paired with a surface
+
+> Convention: `bg-<surface>` always has a paired `text-on-<surface>` foreground. Use them together for guaranteed legibility.
+
 ```
-✅ text-on-prominent                — primary text (black #000000)
-✅ text-on-prominent-static-inverse — always white — for text on dark/primary bg
-✅ text-on-subtle                   — secondary text (mid grey)
-✅ text-on-disabled                 — disabled / inactive text (light grey ~#BBBBBB)
+✅ text-on-prominent          — paired with bg-prominent (black #000000) — default body text
+✅ text-on-prominent-inverse  — paired with bg-prominent-inverse (white) — toast text, etc.
+✅ text-on-primary            — paired with bg-primary (white) — primary button label, tooltip text
+✅ text-on-primary-inverse    — paired with bg-primary-inverse (blue) — primary-inverse button label
+✅ text-on-semantic-win       — paired with bg-semantic-win (white)
+✅ text-on-semantic-loss      — paired with bg-semantic-loss (white)
+✅ text-on-semantic-warning   — paired with bg-semantic-warning (white)
+✅ text-on-semantic-boost     — paired with bg-semantic-boost (dark amber #713813)
+✅ text-on-subtle             — secondary text (mid grey)
+✅ text-on-disabled           — disabled / inactive text (light grey ~#BBBBBB)
 
-✅ text-primary                     — brand blue #2323FF
-✅ text-semantic-win                — green — profit/positive
-✅ text-semantic-loss               — red — loss/negative
+✅ text-primary               — brand blue #2323FF — inline brand text over neutral surfaces
+✅ text-semantic-win          — green — profit/positive inline text
+✅ text-semantic-loss         — red — loss/negative inline text
 ```
 
+> ⚠️ **Deprecated:** `text-on-prominent-static-inverse` still works (aliased to `--on-prominent-inverse`) but new code should pick the explicit `text-on-<surface>` for whatever background sits behind the text.
+
 #### Border tokens
 ```
 ✅ border-border-subtle    — light grey #EEEEEE — default UI borders, dividers, cards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trading-game/design-intelligence-layer",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "description": "Trading Game Design System — shadcn/ui components with Tailwind CSS v4",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/styles.css

@@ -18,6 +18,15 @@
   --color-prominent: var(--prominent);
   --color-on-prominent: var(--on-prominent);
   --color-on-prominent-static-inverse: var(--on-prominent-static-inverse);
+  --color-prominent-inverse: var(--prominent-inverse);
+  --color-on-prominent-inverse: var(--on-prominent-inverse);
+  --color-on-primary: var(--on-primary);
+  --color-primary-inverse: var(--primary-inverse);
+  --color-on-primary-inverse: var(--on-primary-inverse);
+  --color-on-semantic-win: var(--on-semantic-win);
+  --color-on-semantic-loss: var(--on-semantic-loss);
+  --color-on-semantic-warning: var(--on-semantic-warning);
+  --color-on-semantic-boost: var(--on-semantic-boost);
   --font-sans: var(--font-plus-jakarta-sans);
   --font-body: var(--font-plus-jakarta-sans);
   --font-display: var(--font-plus-jakarta-sans);
@@ -48,8 +57,7 @@
   --color-semantic-win: var(--semantic-win);
   --color-semantic-loss: var(--semantic-loss);
   --color-semantic-warning: var(--semantic-warning);
-  --color-semantic-credit: var(--semantic-credit);
-  --color-semantic-credit-text: var(--semantic-credit-text);
+  --color-semantic-boost: var(--semantic-boost);
   --color-alert-info-text: var(--alert-info-text);
   --color-alert-info-border: var(--alert-info-border);
   --color-alert-error-text: var(--alert-error-text);
@@ -168,11 +176,11 @@
 
   /* ── Amber ── */
   --primitive-amber-500: oklch(0.74 0.18 72);
-  /* #ef9f00 — golden amber; ticket credit progress fill */
+  /* #ef9f00 — golden amber; ticket boost progress fill */
   --primitive-amber-600: #F9840F;
-  /* #F9840F — warm orange-amber; credit badge background base */
+  /* #F9840F — warm orange-amber; boost badge background base */
   --primitive-amber-800: oklch(0.40 0.10 52);
-  /* #713813 — dark amber/brown; ticket credit label text */
+  /* #713813 — dark amber/brown; ticket boost label text */
 
   /* ── Violet ── */
   --primitive-violet-500: oklch(0.601 0.263 301.6);
@@ -246,11 +254,25 @@
    ══════════════════════════════════════════════════════════════ */
 :root {
   --prominent: var(--primitive-mono-50);
+  /* #FFFFFF — light surface (page chrome, cards) */
   --on-prominent: var(--primitive-mono-1000);
-  --on-prominent-static-inverse: var(--primitive-mono-50);
-  /* #FFFFFF — always white, never changes between themes */
+  /* #000000 — text/icon color for use on prominent surfaces */
+  --prominent-inverse: var(--primitive-mono-1000);
+  /* #000000 — dark surface for use on light pages (e.g. toasts) */
+  --on-prominent-inverse: var(--primitive-mono-50);
+  /* #FFFFFF — text/icon color for use on prominent-inverse surfaces */
   --primary: var(--primitive-blue-500);
+  /* #2323FF — brand primary surface */
+  --on-primary: var(--primitive-mono-50);
+  /* #FFFFFF — text/icon color for use on primary surfaces */
+  --primary-inverse: var(--primitive-mono-50);
+  /* #FFFFFF — inverted primary surface for use on dark/coloured areas */
+  --on-primary-inverse: var(--primitive-blue-500);
+  /* #2323FF — text/icon color for use on primary-inverse surfaces */
   --primary-hover: oklch(0.403 0.251 267.5);
+  /* @deprecated — use the on-X / X-inverse / on-X-inverse pairs above. Kept for backwards compat with external consumers referencing these via var(). */
+  --on-prominent-static-inverse: var(--on-prominent-inverse);
+  --surface-inverse-static: var(--primary-inverse);
   --subtle: oklch(0.96 0 0);
   --on-subtle: oklch(0.52 0 0);
   --on-disabled: var(--primitive-mono-400);
@@ -265,14 +287,20 @@
   --ring: var(--primitive-blue-500);
   --overlay: var(--primitive-black-50);
   --semantic-win: var(--primitive-green-400);
+  --on-semantic-win: var(--primitive-mono-50);
+  /* #FFFFFF — text/icon color for use on semantic-win surfaces */
   --semantic-loss: var(--primitive-red-500);
+  --on-semantic-loss: var(--primitive-mono-50);
+  /* #FFFFFF — text/icon color for use on semantic-loss surfaces */
   --semantic-info: var(--primitive-sky-600);
   --semantic-error: var(--primitive-red-600);
   --semantic-warning: var(--primitive-orange-500);
-  --semantic-credit: var(--primitive-amber-600);
-  /* #F9840F — credit badge background */
-  --semantic-credit-text: var(--primitive-amber-800);
-  /* #713813 — credit badge foreground */
+  --on-semantic-warning: var(--primitive-mono-50);
+  /* #FFFFFF — text/icon color for use on semantic-warning surfaces */
+  --semantic-boost: var(--primitive-amber-600);
+  /* #F9840F — boost badge surface */
+  --on-semantic-boost: var(--primitive-amber-800);
+  /* #713813 — text/icon color for use on semantic-boost surfaces */
   --tabs: var(--primitive-mono-alpha-4);
   --tabs-active: var(--primitive-mono-50);