@dreamboard-games/sdk 0.2.0

package/src/ui/theme/derive.ts

@@ -0,0 +1,240 @@
+import type { CSSProperties } from "react";
+import type { IntentColor, Theme } from "./tokens.js";
+
+/**
+ * Helpers that derive component-specific style fragments from a
+ * resolved {@link Theme}. They live alongside the theme module (rather
+ * than in each component) so that:
+ *
+ * - There is one canonical mapping of "intent → button style", "intent →
+ *   chip style", etc.
+ * - Component visuals stay aligned automatically when an author tweaks
+ *   the theme; nobody has to remember to update a bespoke calc inside
+ *   `<CardFace>` or `<ThemedButton>`.
+ *
+ * Each helper returns a plain {@link CSSProperties} fragment so the
+ * caller can spread it into an inline style (or pass it through to
+ * Framer Motion's `style` prop).
+ */
+
+/** Button visual variants derived from semantic intent slots. */
+export type ButtonVariant =
+  | "primary"
+  | "secondary"
+  | "danger"
+  | "submitted"
+  | "success"
+  | "warning"
+  | "info"
+  | "ghost";
+
+export type ButtonSize = "sm" | "md" | "lg";
+
+/**
+ * Compute the inline style for a button in `variant`/`size` from the
+ * theme. `disabled` and `pressed` are visual-only — they affect colour
+ * intensity and elevation but never touch interactivity (the consuming
+ * component owns `aria-disabled` and event wiring).
+ */
+export function buttonStyle(
+  theme: Theme,
+  options: {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    disabled?: boolean;
+    pressed?: boolean;
+  } = {},
+): CSSProperties {
+  const { variant = "primary", size = "md", disabled, pressed } = options;
+  const intent = intentForVariant(theme, variant);
+  const sizing = BUTTON_SIZE[size];
+  const visuallyDisabled = disabled && variant !== "submitted";
+
+  const baseShadow =
+    variant === "ghost"
+      ? "none"
+      : pressed
+        ? theme.elevation.rest
+        : theme.elevation.hover;
+
+  return {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: theme.space[2],
+    minHeight: sizing.minHeight,
+    paddingBlock: sizing.paddingBlock,
+    paddingInline: sizing.paddingInline,
+    borderRadius: theme.radius.md,
+    border:
+      variant === "ghost"
+        ? "1px solid transparent"
+        : `1px solid ${visuallyDisabled ? theme.semantic.border.subtle : intent.border}`,
+    background:
+      variant === "ghost"
+        ? "transparent"
+        : visuallyDisabled
+          ? theme.semantic.surface.inset
+          : intent.solid,
+    color: visuallyDisabled
+      ? theme.semantic.text.disabled
+      : variant === "ghost"
+        ? theme.semantic.text.primary
+        : intent.on,
+    fontFamily: theme.typography.fontFamily.body,
+    fontSize: sizing.fontSize,
+    fontWeight: theme.typography.fontWeight.bold,
+    lineHeight: theme.typography.lineHeight.tight,
+    letterSpacing: theme.typography.letterSpacing.normal,
+    cursor: disabled ? "not-allowed" : "pointer",
+    boxShadow: disabled ? "none" : baseShadow,
+    transition: `background-color ${theme.motion.duration.fast} ${theme.motion.easing.out}, transform ${theme.motion.duration.fast} ${theme.motion.easing.out}, box-shadow ${theme.motion.duration.normal} ${theme.motion.easing.out}`,
+    userSelect: "none",
+    WebkitTapHighlightColor: "transparent",
+  };
+}
+
+const BUTTON_SIZE: Record<
+  ButtonSize,
+  {
+    minHeight: number;
+    paddingBlock: string;
+    paddingInline: string;
+    fontSize: string;
+  }
+> = {
+  sm: {
+    minHeight: 32,
+    paddingBlock: "0.25rem",
+    paddingInline: "0.625rem",
+    fontSize: "0.8125rem",
+  },
+  md: {
+    minHeight: 40,
+    paddingBlock: "0.5rem",
+    paddingInline: "0.875rem",
+    fontSize: "0.9375rem",
+  },
+  lg: {
+    minHeight: 52,
+    paddingBlock: "0.75rem",
+    paddingInline: "1.125rem",
+    fontSize: "1.0625rem",
+  },
+};
+
+/**
+ * Soft-intent chip ("Your turn", "Largest army", "Waiting…"). Reads
+ * `intent.<variant>.soft` for background and `.onSoft` for text.
+ */
+export function chipStyle(
+  theme: Theme,
+  options: {
+    variant?: Exclude<ButtonVariant, "ghost">;
+    size?: "sm" | "md";
+  } = {},
+): CSSProperties {
+  const { variant = "secondary", size = "sm" } = options;
+  const intent = intentForVariant(theme, variant);
+  return {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: theme.space[1],
+    paddingBlock: size === "md" ? "0.25rem" : "0.125rem",
+    paddingInline: size === "md" ? "0.625rem" : "0.5rem",
+    borderRadius: theme.radius.pill,
+    border: `1px solid ${intent.border}`,
+    background: intent.soft,
+    color: intent.onSoft,
+    fontFamily: theme.typography.fontFamily.body,
+    fontSize:
+      size === "md"
+        ? theme.typography.fontSize.sm
+        : theme.typography.fontSize.xs,
+    fontWeight: theme.typography.fontWeight.bold,
+    letterSpacing: theme.typography.letterSpacing.wide,
+    textTransform: "uppercase",
+    whiteSpace: "nowrap",
+  };
+}
+
+/**
+ * Standard surface card (player card, action panel, hand drawer). The
+ * `tone` selects which `surface.*` slot to read; `interactive` adds
+ * the hover-elevation transition baseline.
+ */
+export function surfaceStyle(
+  theme: Theme,
+  options: {
+    tone?: keyof Theme["semantic"]["surface"];
+    interactive?: boolean;
+    /** Override radius to one of the theme tokens. Defaults to `lg`. */
+    radius?: keyof Theme["radius"];
+  } = {},
+): CSSProperties {
+  const { tone = "card", interactive, radius = "lg" } = options;
+  return {
+    background: theme.semantic.surface[tone],
+    color: theme.semantic.text.primary,
+    border: `1px solid ${theme.semantic.border.subtle}`,
+    borderRadius: theme.radius[radius],
+    boxShadow: theme.elevation.rest,
+    transition: interactive
+      ? `box-shadow ${theme.motion.duration.normal} ${theme.motion.easing.out}, transform ${theme.motion.duration.normal} ${theme.motion.easing.out}`
+      : undefined,
+  };
+}
+
+/** Resolve a {@link ButtonVariant} to its underlying {@link IntentColor}. */
+export function intentForVariant(
+  theme: Theme,
+  variant: ButtonVariant,
+): IntentColor {
+  switch (variant) {
+    case "primary":
+      return theme.semantic.intent.primary;
+    case "secondary":
+      return theme.semantic.intent.secondary;
+    case "danger":
+      return theme.semantic.intent.danger;
+    case "submitted":
+      return theme.semantic.intent.success;
+    case "success":
+      return theme.semantic.intent.success;
+    case "warning":
+      return theme.semantic.intent.warning;
+    case "info":
+      return theme.semantic.intent.info;
+    case "ghost":
+      return theme.semantic.intent.secondary;
+  }
+}
+
+/**
+ * Pick a {@link Theme.player} entry by 0-based seat slot, wrapping
+ * around when there are more players than palette entries (so a
+ * 7-player game cycles back to player 1's palette).
+ */
+export function playerColor(theme: Theme, slot: number) {
+  const length = theme.player.length;
+  const idx = ((slot % length) + length) % length;
+  // The {@link Theme.player} contract pins length === 6 at the type
+  // level, but indexing by a runtime-computed value widens the result
+  // to `PlayerColor | undefined`. Falling back to slot 0 (also typed
+  // `PlayerColor`) keeps the return type narrow without a non-null
+  // assertion.
+  return theme.player[idx] ?? theme.player[0];
+}
+
+/**
+ * Returns `theme.motion.duration.<key>` zeroed out when the theme has
+ * `motion.reducedMotion === "true"`. Use this in any component that
+ * starts an animation so `prefers-reduced-motion` is honoured uniformly.
+ */
+export function motionDuration(
+  theme: Theme,
+  key: keyof Theme["motion"]["duration"],
+): string {
+  if (theme.motion.reducedMotion === "true") return "0ms";
+  return theme.motion.duration[key];
+}

package/src/ui/theme/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Public theme surface for `@dreamboard-games/sdk/ui`.
+ *
+ * Authors who only consume the SDK never need to import from
+ * sub-modules — `<ThemeProvider>`, `useTheme()`, and the preset ids
+ * are the entire public API. Type-level exports cover advanced use
+ * (custom themes, deep overrides) without leaking internal token shape
+ * surfaces (CSS-var serializer, derive helpers) that may move.
+ *
+ * Module entry order is import-friendly: tokens (types) before
+ * presets (values) before provider (consumes both).
+ */
+
+export type {
+  ColorRamp,
+  ComponentTokens,
+  Elevation,
+  FoundationColor,
+  IntentColor,
+  Motion,
+  PlayerColor,
+  Radius,
+  SemanticColor,
+  Space,
+  Theme,
+  ThemeMeta,
+  ThemeOverride,
+  Typography,
+} from "./tokens.js";
+
+export { mergeTheme } from "./tokens.js";
+
+export { tabletopTheme } from "./presets/tabletop.js";
+export { arcadeTheme } from "./presets/arcade.js";
+export { studioTheme } from "./presets/studio.js";
+
+export {
+  ThemeProvider,
+  resolveTheme,
+  getThemePreset,
+  useTheme,
+  useThemeCssVars,
+  type ThemeContextValue,
+  type ThemePresetId,
+  type ThemeProviderProps,
+} from "./ThemeProvider.js";
+
+export { themeToCssVars, cssVar, cssVarOr } from "./css-vars.js";
+
+export {
+  buttonStyle,
+  chipStyle,
+  surfaceStyle,
+  intentForVariant,
+  playerColor,
+  motionDuration,
+  type ButtonSize,
+  type ButtonVariant,
+} from "./derive.js";
+
+export { useBoardTheme, deriveBoardTheme, type BoardTheme } from "./board.js";

package/src/ui/theme/presets/arcade.ts

@@ -0,0 +1,261 @@
+import type { Theme } from "../tokens.js";
+
+/**
+ * `arcade` — high-contrast neon theme for fast/competitive games.
+ *
+ * Visual identity: deep slate background, electric cyan/magenta
+ * intents, square-ish corners, sharp drop shadows. Designed to evoke
+ * action games and to keep critical CTAs popping at a glance.
+ */
+export const arcadeTheme: Theme = {
+  meta: {
+    id: "arcade",
+    name: "Arcade",
+    mode: "dark",
+  },
+  color: {
+    neutral: {
+      50: "#f5f7fb",
+      100: "#d6dde9",
+      200: "#a8b2c4",
+      400: "#5b6478",
+      600: "#2c3344",
+      800: "#161b27",
+      950: "#070912",
+    },
+    brand: {
+      50: "#e0fbff",
+      100: "#aef1fb",
+      200: "#62e0f0",
+      400: "#1bc4dc",
+      600: "#0d8ea1",
+      800: "#06525e",
+      950: "#03252b",
+    },
+    accent: {
+      50: "#ffe6f6",
+      100: "#ffb1de",
+      200: "#ff6cbf",
+      400: "#ff2891",
+      600: "#c80862",
+      800: "#73003a",
+      950: "#37001b",
+    },
+    success: {
+      50: "#dafdf2",
+      100: "#9af2cf",
+      200: "#52e1a3",
+      400: "#0fc171",
+      600: "#067a45",
+      800: "#024226",
+      950: "#001f10",
+    },
+    warning: {
+      50: "#fff4d8",
+      100: "#ffe198",
+      200: "#fbc739",
+      400: "#dba500",
+      600: "#9b7400",
+      800: "#5a4200",
+      950: "#291e00",
+    },
+    danger: {
+      50: "#ffdcdc",
+      100: "#ff9c9c",
+      200: "#ff5454",
+      400: "#e41e1e",
+      600: "#960a0a",
+      800: "#5a0202",
+      950: "#290000",
+    },
+    info: {
+      50: "#dceefe",
+      100: "#9ecdfb",
+      200: "#4f9ff5",
+      400: "#1d6fde",
+      600: "#0a4598",
+      800: "#03234f",
+      950: "#011024",
+    },
+  },
+  semantic: {
+    surface: {
+      app: "#070912",
+      board: "#0a0e1d",
+      hud: "#161b27",
+      card: "#1f2636",
+      sheet: "#161b27",
+      overlay: "rgba(7, 9, 18, 0.78)",
+      inset: "#0a0e1d",
+    },
+    text: {
+      primary: "#f5f7fb",
+      muted: "#a8b2c4",
+      onIntent: "#070912",
+      accent: "#62e0f0",
+      disabled: "#5b6478",
+    },
+    border: {
+      subtle: "#2c3344",
+      default: "#5b6478",
+      strong: "#a8b2c4",
+      focus: "#1bc4dc",
+    },
+    intent: {
+      primary: {
+        solid: "#1bc4dc",
+        on: "#070912",
+        soft: "rgba(27, 196, 220, 0.18)",
+        onSoft: "#aef1fb",
+        border: "#62e0f0",
+      },
+      secondary: {
+        solid: "#1f2636",
+        on: "#f5f7fb",
+        soft: "#161b27",
+        onSoft: "#a8b2c4",
+        border: "#5b6478",
+      },
+      success: {
+        solid: "#0fc171",
+        on: "#070912",
+        soft: "rgba(15, 193, 113, 0.18)",
+        onSoft: "#9af2cf",
+        border: "#52e1a3",
+      },
+      danger: {
+        solid: "#e41e1e",
+        on: "#ffffff",
+        soft: "rgba(228, 30, 30, 0.18)",
+        onSoft: "#ff9c9c",
+        border: "#ff5454",
+      },
+      warning: {
+        solid: "#fbc739",
+        on: "#070912",
+        soft: "rgba(251, 199, 57, 0.18)",
+        onSoft: "#ffe198",
+        border: "#dba500",
+      },
+      info: {
+        solid: "#4f9ff5",
+        on: "#070912",
+        soft: "rgba(79, 159, 245, 0.18)",
+        onSoft: "#9ecdfb",
+        border: "#1d6fde",
+      },
+    },
+  },
+  radius: {
+    none: "0px",
+    sm: "2px",
+    md: "4px",
+    lg: "6px",
+    hud: "10px",
+    pill: "9999px",
+  },
+  space: {
+    0: "0",
+    0.5: "0.125rem",
+    1: "0.25rem",
+    1.5: "0.375rem",
+    2: "0.5rem",
+    3: "0.75rem",
+    4: "1rem",
+    6: "1.5rem",
+    8: "2rem",
+    12: "3rem",
+  },
+  typography: {
+    fontFamily: {
+      display: '"Space Grotesk", "Inter", system-ui, -apple-system, sans-serif',
+      body: '"Inter", "SF Pro Text", system-ui, -apple-system, sans-serif',
+      tabular: '"JetBrains Mono", "SF Mono", ui-monospace, monospace',
+      mono: '"JetBrains Mono", "SF Mono", ui-monospace, monospace',
+    },
+    fontSize: {
+      xs: "0.6875rem",
+      sm: "0.8125rem",
+      md: "0.9375rem",
+      lg: "1.0625rem",
+      xl: "1.25rem",
+      "2xl": "1.5rem",
+      "3xl": "2rem",
+    },
+    fontWeight: {
+      regular: "400",
+      medium: "500",
+      bold: "700",
+    },
+    lineHeight: {
+      tight: "1.1",
+      normal: "1.35",
+      relaxed: "1.55",
+    },
+    letterSpacing: {
+      tight: "-0.01em",
+      normal: "0",
+      wide: "0.06em",
+      caps: "0.18em",
+    },
+  },
+  elevation: {
+    rest: "0 1px 0 rgba(0, 0, 0, 0.4), 0 2px 0 rgba(27, 196, 220, 0.15)",
+    hover:
+      "0 0 0 1px rgba(27, 196, 220, 0.4), 0 6px 16px rgba(27, 196, 220, 0.35)",
+    lifted:
+      "0 0 0 2px rgba(27, 196, 220, 0.6), 0 14px 28px rgba(27, 196, 220, 0.45)",
+    overlay: "0 20px 60px rgba(0, 0, 0, 0.7)",
+    inset: "inset 0 0 0 1px rgba(27, 196, 220, 0.18)",
+  },
+  motion: {
+    duration: {
+      fast: "60ms",
+      normal: "120ms",
+      slow: "220ms",
+      ambient: "1400ms",
+    },
+    easing: {
+      out: "cubic-bezier(0.22, 1, 0.36, 1)",
+      in: "cubic-bezier(0.36, 0, 1, 0.36)",
+      inOut: "cubic-bezier(0.7, 0, 0.3, 1)",
+      spring: "cubic-bezier(0.32, 1.6, 0.6, 1)",
+    },
+    reducedMotion: "false",
+  },
+  player: [
+    { solid: "#1bc4dc", soft: "rgba(27, 196, 220, 0.2)", on: "#070912" },
+    { solid: "#ff2891", soft: "rgba(255, 40, 145, 0.2)", on: "#ffffff" },
+    { solid: "#0fc171", soft: "rgba(15, 193, 113, 0.2)", on: "#070912" },
+    { solid: "#fbc739", soft: "rgba(251, 199, 57, 0.2)", on: "#070912" },
+    { solid: "#9b59ff", soft: "rgba(155, 89, 255, 0.2)", on: "#ffffff" },
+    { solid: "#ff7b3a", soft: "rgba(255, 123, 58, 0.2)", on: "#070912" },
+  ],
+  component: {
+    board: {
+      frameBorder: "#1bc4dc",
+      frameBackground: "#0a0e1d",
+      hoverRing: "#ff2891",
+      eligibleHint: "rgba(27, 196, 220, 0.55)",
+    },
+    card: {
+      border: "#1bc4dc",
+      backBorder: "#ff2891",
+      backBackground: "#161b27",
+      selectedRing: "#ff2891",
+    },
+    playerCard: {
+      activeBackground: "rgba(27, 196, 220, 0.18)",
+      activeBorder: "#1bc4dc",
+      activeGlow: "rgba(27, 196, 220, 0.5)",
+      youBadgeBackground: "rgba(27, 196, 220, 0.22)",
+      youBadgeForeground: "#aef1fb",
+    },
+    toast: {
+      successBackground: "#0fc171",
+      errorBackground: "#e41e1e",
+      infoBackground: "#1bc4dc",
+      foreground: "#070912",
+    },
+  },
+};