Theme Token System

The theme token object (T), now var() references to the Material 3 roles, plus the alpha() helper. Drop in and theme with var(--md-sys-color-*) or T.*.

// ═══════════════════════════════════════════════════════
// DESIGN TOKENS: the T object over the theme contract
// ═══════════════════════════════════════════════════════
//
// Every color is a CSS custom property from src/styles/theme/tokens.css
// (generated by scripts/theme/build-tokens.mjs), never a hex. The roles flip
// with data-theme (light | dark) and the container fills and fonts with
// data-look (material | glass), so an inline style written with T follows the
// theme the reader picked. The legacy keys (bg0, tx3, red, ...) are kept so
// the 400-odd importers did not have to change; their mapping onto Material
// roles is the table in docs/design/theme-system.md. New code should prefer
// the role keys (T.primary, T.onSurface, ...).
//
// Code that needs a resolved color (Canvas2D, WebGL, three.js) goes through
// src/lib/theme/resolve.js, never by parsing these strings.
const role = (name) => `var(--md-sys-color-${name})`;
const fill = (n) => `var(--sys-surface-fill-${n})`;

export const T = {
  // Surfaces (fills are translucent under the Glass look)
  bg0: role("surface"),
  bg1: fill(1),
  bg2: fill(2),
  bg3: fill(3),

  // Card
  card: fill(0),
  border: role("outline-variant"),
  borderH: role("outline"),

  // Text
  tx: role("on-surface"),
  tx2: role("on-surface-variant"),
  tx3: role("outline"), // 3:1 on the surface: labels and rules, never body text
  tx4: role("text-faint"),
  tx5: role("outline-variant"),

  // The three accents (the former red / blue / yellow triad)
  red: role("primary"),
  blue: role("secondary"),
  yellow: role("tertiary"),
  orange: role("warning"),
  warnText: role("on-warning-container"),

  // Content clusters (extended roles, harmonized to the seed)
  ai: role("ai"),
  games: role("games"),
  writing: role("writing"),
  govtech: role("govtech"),
  other: role("outline"),

  // Status
  live: role("success"),
  wip: role("warning"),
  dim: role("outline-variant"),

  // Material roles, by name
  primary: role("primary"),
  onPrimary: role("on-primary"),
  primaryContainer: role("primary-container"),
  onPrimaryContainer: role("on-primary-container"),
  secondary: role("secondary"),
  onSecondary: role("on-secondary"),
  secondaryContainer: role("secondary-container"),
  onSecondaryContainer: role("on-secondary-container"),
  tertiary: role("tertiary"),
  onTertiary: role("on-tertiary"),
  tertiaryContainer: role("tertiary-container"),
  onTertiaryContainer: role("on-tertiary-container"),
  error: role("error"),
  onError: role("on-error"),
  errorContainer: role("error-container"),
  onErrorContainer: role("on-error-container"),
  success: role("success"),
  warning: role("warning"),
  info: role("info"),
  surface: role("surface"),
  surfaceVariant: role("surface-variant"),
  inverseSurface: role("inverse-surface"),
  inverseOnSurface: role("inverse-on-surface"),
  scrim: role("scrim"),
  shadow: role("shadow"),

  // Fonts: the look picks the family (Roboto for Material, Geist for Glass)
  ff: "var(--font-display), serif",
  fb: "var(--font-body), sans-serif",
  fm: "var(--font-mono), monospace",
};

export const FONT_KEYS = ["ff", "fb", "fm"];
/** Every key of T that is a color. */
export const COLOR_KEYS = Object.keys(T).filter((k) => !FONT_KEYS.includes(k));

// ═══════════════════════════════════════════════════════
// HELPERS
// ═══════════════════════════════════════════════════════

const HEX6 = /^#[0-9a-f]{6}$/i;
const byte = (a) =>
  typeof a === "string" ? parseInt(a, 16) : Math.round(Math.max(0, Math.min(1, a)) * 255);

// alpha(color, a): `color` at opacity `a` (0..1, or a two-digit hex byte as a
// string, the legacy hex-suffix form).
//
//   alpha(T.ai, 0.08)      -> "color-mix(in srgb, var(--md-sys-color-ai) 8%, transparent)"
//   alpha("#5b5bd6", 0.08) -> "#5b5bd614"   (a resolved hex keeps the hex form,
//                                            so canvas code and React Native work)
export const alpha = (color, a) => {
  const b = Math.max(0, Math.min(255, byte(a)));
  if (HEX6.test(color)) return `${color}${b.toString(16).padStart(2, "0")}`;
  return `color-mix(in srgb, ${color} ${Math.round((b / 255) * 100)}%, transparent)`;
};