@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/theme.ts

@@ -0,0 +1,527 @@
+/**
+ * Canonical design-token module for the vgai editor (editor-style-polish U0,
+ * `roadmaps/editor-style-polish/EDITOR-STYLE-AUDIT.md` §3 "Proposed Token
+ * Set"). Every color/spacing/radius/type/shadow/z-index value the editor's
+ * ~98 React components currently hand-roll as inline hex literals gets one
+ * home here. This module is imported by `theme-css.ts` (the injected global
+ * stylesheet) AND by plain TS/TSX call sites that still build inline `style`
+ * objects (e.g. `inspector-widgets/shared.tsx`, `primitives/Panel.tsx`) — so
+ * it must stay import-safe from any context: no DOM access, no side effects,
+ * just typed `const` data.
+ *
+ * The default theme values are the audit's §3 reconciliation decisions, not a fresh re-derive:
+ * accent is `#579EFF` (the plurality color actually on screen — 44 sites —
+ * NOT `inspector-widgets/shared.tsx`'s previously-independent `#3b82f6`,
+ * confined to 6 sites); the mono stack is the `ui-monospace` spelling with
+ * 2 independent votes, not `FONT_MONO`'s 1; the sans stack drops `'Inter'`
+ * (never loaded — zero `@font-face` hits repo-wide) in favor of the
+ * `-apple-system` chain already live in root `index.html`.
+ */
+
+const GRAPHITE_BG = {
+  0: '#1a1a1a',
+  1: '#242424',
+  2: '#2c2c2c',
+  3: '#333333',
+  inset: '#1e1e1e',
+} as const;
+const GRAPHITE_BORDER = { 1: '#333333', 2: '#444444' } as const;
+const GRAPHITE_TEXT = { 1: '#c5c8ce', 2: '#9aa0a6', 3: '#90959c' } as const;
+const GRAPHITE_ACCENT = '#579EFF';
+const GRAPHITE_ACCENT_MUTED = 'rgba(87,158,255,0.15)';
+const GRAPHITE_DANGER = '#FF6B6B';
+const GRAPHITE_WARN = '#e0a030';
+const GRAPHITE_SUCCESS = '#4caf50';
+const GRAPHITE_SUCCESS_MUTED = 'rgba(76,175,80,0.15)';
+const GRAPHITE_DANGER_MUTED = 'rgba(255,107,107,0.15)';
+const GRAPHITE_WARN_MUTED = 'rgba(224,160,48,0.12)';
+const GRAPHITE_DANGER_FAINT = 'rgba(255,107,107,0.06)';
+const GRAPHITE_SCRIM = 'rgba(0,0,0,0.5)';
+const GRAPHITE_DYNAMIC = '#ff79c6';
+const GRAPHITE_DYNAMIC_BG = 'rgba(255,121,198,0.08)';
+const GRAPHITE_FONT_SANS = '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+const GRAPHITE_FONT_MONO = 'ui-monospace, "SF Mono", Monaco, "Cascadia Code", monospace';
+const GRAPHITE_SHADOW = {
+  sm: '0 2px 8px rgba(0,0,0,0.6)',
+  md: '0 4px 12px rgba(0,0,0,0.5)',
+  lg: '0 8px 32px rgba(0,0,0,0.6)',
+} as const;
+
+/**
+ * Compatibility references used by existing DOM call sites. They resolve at
+ * paint time, so the whole existing editor participates in runtime themes.
+ * New code should prefer the semantic {@link themeVars} vocabulary.
+ */
+export const bg = {
+  /** App shell / loading screen (`AppRoot.tsx`, root `index.html` body). */
+  0: 'var(--vgai-surface-shell)',
+  /** Panel body (`Panel.tsx`'s content area, THEME.bg). */
+  1: 'var(--vgai-surface-panel)',
+  /** Surface: header / menu / dropdown / popover (THEME.surface). */
+  2: 'var(--vgai-surface-chrome)',
+  /** Raised / hover surface (THEME.surfaceHover). */
+  3: 'var(--vgai-surface-raised)',
+  /** Input well / recessed field background (THEME.inputBg). */
+  inset: 'var(--vgai-surface-inset)',
+} as const;
+
+/** Border ramp — same literal as `bg[3]` for `border[1]` by design (distinguished by CSS property, not value). */
+export const border = {
+  /** Default border. */
+  1: 'var(--vgai-boundary-default)',
+  /** Hover / emphasis border. */
+  2: 'var(--vgai-boundary-strong)',
+} as const;
+
+/** Text ramp — primary → tertiary/dim. */
+export const text = {
+  /** Primary text (THEME.text). */
+  1: 'var(--vgai-content-primary)',
+  /** Secondary / muted text (THEME.textMuted). */
+  2: 'var(--vgai-content-muted)',
+  /** Tertiary / dim text. */
+  3: 'var(--vgai-content-dim)',
+} as const;
+
+/** Canonical accent blue — the plurality color across the whole editor (44 census hits). */
+export const accent = 'var(--vgai-accent)';
+/** Accent tint for hover/active backgrounds behind accent-colored content. */
+export const accentMuted = 'var(--vgai-accent-muted)';
+
+/** Semantic tones. */
+export const danger = 'var(--vgai-danger)';
+export const warn = 'var(--vgai-warn)';
+export const success = 'var(--vgai-success)';
+
+/**
+ * Semantic background tints (U6, punch-list #1) — one family alpha (0.15,
+ * matching `accentMuted`) for chip/band/state backgrounds behind
+ * semantic-colored content. Converges the drifted hand-rolled alphas
+ * (0.12/0.15) that U3-U5 left behind in EnvironmentSection (stale-bake),
+ * ConsolePanel (entity chip), HistoryPanel (error band), AudioSection
+ * (stop state), and Dockview's unsaved-document treatment.
+ */
+export const successMuted = 'var(--vgai-success-muted)';
+export const dangerMuted = 'var(--vgai-danger-muted)';
+/** Resting warning surface used for unsaved/attention states. */
+export const warnMuted = 'var(--vgai-warn-muted)';
+/**
+ * Deliberately fainter danger tint for RESTING full-row backgrounds
+ * (ConsolePanel / DebugConsolePanel error rows): a run of consecutive error
+ * rows must read as a list, not a solid red wall, so rows sit at 0.06 while
+ * point-emphasis chips/bands use `dangerMuted`. Two files independently
+ * converged on this exact value — tokenized so they can't drift apart.
+ */
+export const dangerFaint = 'var(--vgai-danger-faint)';
+
+/**
+ * The one modal/backdrop dimming scrim. The canonical Dialog pattern and
+ * non-dialog modal surfaces share this semantic value.
+ */
+export const scrim = 'var(--vgai-scrim)';
+
+/** Kit-specific "reactive/bound value" indicator (inspector-widgets only — not otherwise contested). */
+export const dynamic = 'var(--vgai-dynamic)';
+export const dynamicBg = 'var(--vgai-dynamic-muted)';
+
+/** 4/8-based spacing scale — compose padding/margin/gap from these instead of ad hoc shorthand strings. */
+export const space = {
+  1: 2,
+  2: 4,
+  3: 6,
+  4: 8,
+  5: 10,
+  6: 12,
+  8: 16,
+  10: 20,
+  12: 24,
+} as const;
+
+/**
+ * Semantic editor-chrome dimensions. Different roles intentionally use
+ * different heights, but every instance of a role must consume the same
+ * token instead of retyping a nearby number.
+ */
+export const chromeSize = {
+  commandBar: 36,
+  panelHeader: 30,
+  localToolbar: 28,
+  treeRow: 24,
+  statusBar: 22,
+} as const;
+
+/** Reusable interactive-control heights. */
+export const controlSize = {
+  compact: 20,
+  default: 24,
+  comfortable: 28,
+} as const;
+
+/** Resting boundaries stay quiet; interaction affordances may strengthen. */
+export const strokeWidth = {
+  resting: 1,
+  active: 2,
+} as const;
+
+/** Named type scale (px). Covers the overwhelming majority of real fontSize call sites. */
+export const fontSize = {
+  xs: 9,
+  sm: 10,
+  base: 11,
+  md: 12,
+  lg: 13,
+  xl: 14,
+  '2xl': 16,
+  heading: 24,
+} as const;
+
+export const fontWeight = {
+  regular: 400,
+  semibold: 600,
+  bold: 700,
+} as const;
+
+/**
+ * Sans stack — the fallback chain already live everywhere else (originally
+ * declared in root `index.html`). `'Inter'` is intentionally NOT included:
+ * no `@font-face`/`<link>` for it exists anywhere in `packages/editor`, so it
+ * only ever silently fell back to this same chain.
+ */
+export const fontSans = 'var(--vgai-font-sans)';
+
+/**
+ * Canonical mono stack — replaces `FONT_MONO`/`MONO`/18 bare `'monospace'`
+ * sites. This spelling had 2 independent votes in the codebase vs. 1 each
+ * for the others.
+ */
+export const fontMono = 'var(--vgai-font-mono)';
+
+const DEFAULT_RADIUS = {
+  small: '3px',
+  medium: '6px',
+  large: '8px',
+  full: '50%',
+} as const;
+
+/**
+ * Runtime border-radius references. Like the color compatibility exports,
+ * these resolve at paint time so existing product surfaces participate in a
+ * custom theme instead of freezing the Graphite defaults into inline styles.
+ */
+export const radius = {
+  sm: 'var(--vgai-radius-sm)',
+  md: 'var(--vgai-radius-md)',
+  lg: 'var(--vgai-radius-lg)',
+  full: 'var(--vgai-radius-full)',
+} as const;
+
+/** Drop-shadow tiers. */
+export const shadow = {
+  /** Tooltip tier. */
+  sm: 'var(--vgai-shadow-sm)',
+  /** Dropdown / menu tier — already the dominant value pre-token. */
+  md: 'var(--vgai-shadow-md)',
+  /** Modal tier. */
+  lg: 'var(--vgai-shadow-lg)',
+} as const;
+
+/**
+ * `1px solid <accent>` — apply via a global `:focus-visible` rule for
+ * `className`-based controls (see `theme-css.ts`), and via a shared
+ * `onFocus`/`onBlur` handler for inline-`style` components that can't
+ * express the pseudo-class directly (out of scope for U0 — later units).
+ */
+export const focusRing = 'var(--vgai-focus-ring)';
+
+/**
+ * Runtime editor-theme contract. The compatibility exports above are CSS
+ * references so existing DOM chrome themes at paint time; concrete defaults
+ * live in {@link graphiteDarkEditorTheme}. New DOM code should consume
+ * {@link themeVars}' semantic names.
+ */
+export interface EditorTheme {
+  readonly id: string;
+  readonly color: {
+    readonly surface: {
+      readonly shell: string;
+      readonly panel: string;
+      readonly chrome: string;
+      readonly raised: string;
+      readonly inset: string;
+      /** Translucent editor HUD chrome drawn over a game/scene viewport. */
+      readonly overlay: string;
+    };
+    readonly boundary: { readonly default: string; readonly strong: string };
+    readonly content: {
+      readonly primary: string;
+      readonly muted: string;
+      readonly dim: string;
+      readonly onAccent: string;
+    };
+    readonly accent: { readonly default: string; readonly muted: string };
+    readonly semantic: {
+      readonly danger: string;
+      readonly dangerMuted: string;
+      readonly dangerFaint: string;
+      readonly warning: string;
+      readonly warningMuted: string;
+      readonly success: string;
+      readonly successMuted: string;
+      readonly dynamic: string;
+      readonly dynamicMuted: string;
+    };
+    readonly neutralOverlay: { readonly hover: string; readonly active: string };
+    readonly scrim: string;
+  };
+  readonly typography: { readonly sans: string; readonly mono: string };
+  readonly shape: {
+    readonly small: string;
+    readonly medium: string;
+    readonly large: string;
+    readonly full: string;
+  };
+  readonly elevation: { readonly small: string; readonly medium: string; readonly large: string };
+}
+
+export const graphiteDarkEditorTheme: EditorTheme = {
+  id: 'graphite-dark',
+  color: {
+    surface: {
+      shell: GRAPHITE_BG[0],
+      panel: GRAPHITE_BG[1],
+      chrome: GRAPHITE_BG[2],
+      raised: GRAPHITE_BG[3],
+      inset: GRAPHITE_BG.inset,
+      overlay: 'rgba(36,36,36,0.94)',
+    },
+    boundary: { default: GRAPHITE_BORDER[1], strong: GRAPHITE_BORDER[2] },
+    content: {
+      primary: GRAPHITE_TEXT[1],
+      muted: GRAPHITE_TEXT[2],
+      dim: GRAPHITE_TEXT[3],
+      onAccent: '#101820',
+    },
+    accent: { default: GRAPHITE_ACCENT, muted: GRAPHITE_ACCENT_MUTED },
+    semantic: {
+      danger: GRAPHITE_DANGER,
+      dangerMuted: GRAPHITE_DANGER_MUTED,
+      dangerFaint: GRAPHITE_DANGER_FAINT,
+      warning: GRAPHITE_WARN,
+      warningMuted: GRAPHITE_WARN_MUTED,
+      success: GRAPHITE_SUCCESS,
+      successMuted: GRAPHITE_SUCCESS_MUTED,
+      dynamic: GRAPHITE_DYNAMIC,
+      dynamicMuted: GRAPHITE_DYNAMIC_BG,
+    },
+    neutralOverlay: {
+      hover: 'rgba(255,255,255,0.08)',
+      active: 'rgba(255,255,255,0.14)',
+    },
+    scrim: GRAPHITE_SCRIM,
+  },
+  typography: { sans: GRAPHITE_FONT_SANS, mono: GRAPHITE_FONT_MONO },
+  shape: {
+    small: DEFAULT_RADIUS.small,
+    medium: DEFAULT_RADIUS.medium,
+    large: DEFAULT_RADIUS.large,
+    full: DEFAULT_RADIUS.full,
+  },
+  elevation: {
+    small: GRAPHITE_SHADOW.sm,
+    medium: GRAPHITE_SHADOW.md,
+    large: GRAPHITE_SHADOW.lg,
+  },
+};
+
+/**
+ * Production high-contrast theme. It deliberately preserves the editor's
+ * dark, low-glare character while increasing text/boundary separation and
+ * shifting the accent away from the default graphite palette.
+ */
+export const midnightHighContrastEditorTheme: EditorTheme = {
+  id: 'midnight-high-contrast',
+  color: {
+    surface: {
+      shell: '#0b0f14',
+      panel: '#111821',
+      chrome: '#17212c',
+      raised: '#223040',
+      inset: '#080c11',
+      overlay: 'rgba(17,24,33,0.96)',
+    },
+    boundary: { default: '#34465a', strong: '#71869d' },
+    content: {
+      primary: '#f2f5f8',
+      muted: '#bdc8d5',
+      dim: '#8493a5',
+      onAccent: '#071019',
+    },
+    accent: { default: '#65d1ff', muted: 'rgba(101,209,255,0.18)' },
+    semantic: {
+      danger: '#ff7b86',
+      dangerMuted: 'rgba(255,123,134,0.18)',
+      dangerFaint: 'rgba(255,123,134,0.08)',
+      warning: '#f3c969',
+      warningMuted: 'rgba(243,201,105,0.16)',
+      success: '#62d394',
+      successMuted: 'rgba(98,211,148,0.18)',
+      dynamic: '#e889ff',
+      dynamicMuted: 'rgba(232,137,255,0.12)',
+    },
+    neutralOverlay: {
+      hover: 'rgba(255,255,255,0.10)',
+      active: 'rgba(255,255,255,0.18)',
+    },
+    scrim: 'rgba(0,0,0,0.68)',
+  },
+  typography: { sans: GRAPHITE_FONT_SANS, mono: GRAPHITE_FONT_MONO },
+  shape: { small: '3px', medium: '6px', large: '8px', full: '50%' },
+  elevation: {
+    small: '0 2px 8px rgba(0,0,0,0.72)',
+    medium: '0 6px 18px rgba(0,0,0,0.68)',
+    large: '0 12px 40px rgba(0,0,0,0.76)',
+  },
+};
+
+export const editorThemes = {
+  'graphite-dark': graphiteDarkEditorTheme,
+  'midnight-high-contrast': midnightHighContrastEditorTheme,
+} as const satisfies Record<string, EditorTheme>;
+
+export type EditorThemeId = keyof typeof editorThemes;
+
+export function isEditorThemeId(value: unknown): value is EditorThemeId {
+  return typeof value === 'string' && Object.hasOwn(editorThemes, value);
+}
+
+/** Semantic CSS-variable references for rendered editor chrome. */
+export const themeVars = {
+  surface: {
+    shell: 'var(--vgai-surface-shell)',
+    panel: 'var(--vgai-surface-panel)',
+    chrome: 'var(--vgai-surface-chrome)',
+    raised: 'var(--vgai-surface-raised)',
+    inset: 'var(--vgai-surface-inset)',
+    overlay: 'var(--vgai-surface-overlay)',
+  },
+  boundary: {
+    default: 'var(--vgai-boundary-default)',
+    strong: 'var(--vgai-boundary-strong)',
+  },
+  content: {
+    primary: 'var(--vgai-content-primary)',
+    muted: 'var(--vgai-content-muted)',
+    dim: 'var(--vgai-content-dim)',
+    onAccent: 'var(--vgai-content-on-accent)',
+  },
+  accent: {
+    default: 'var(--vgai-accent)',
+    muted: 'var(--vgai-accent-muted)',
+  },
+  semantic: {
+    danger: 'var(--vgai-danger)',
+    dangerMuted: 'var(--vgai-danger-muted)',
+    dangerFaint: 'var(--vgai-danger-faint)',
+    warning: 'var(--vgai-warn)',
+    warningMuted: 'var(--vgai-warn-muted)',
+    success: 'var(--vgai-success)',
+    successMuted: 'var(--vgai-success-muted)',
+    dynamic: 'var(--vgai-dynamic)',
+    dynamicMuted: 'var(--vgai-dynamic-muted)',
+  },
+  neutralOverlay: {
+    hover: 'var(--vgai-neutral-hover)',
+    active: 'var(--vgai-neutral-active)',
+  },
+  scrim: 'var(--vgai-scrim)',
+  typography: {
+    sans: 'var(--vgai-font-sans)',
+    mono: 'var(--vgai-font-mono)',
+  },
+  shape: {
+    small: 'var(--vgai-radius-sm)',
+    medium: 'var(--vgai-radius-md)',
+    large: 'var(--vgai-radius-lg)',
+    full: 'var(--vgai-radius-full)',
+  },
+  elevation: {
+    small: 'var(--vgai-shadow-sm)',
+    medium: 'var(--vgai-shadow-md)',
+    large: 'var(--vgai-shadow-lg)',
+  },
+  focusRing: 'var(--vgai-focus-ring)',
+} as const;
+
+export type EditorThemeVariable = `--vgai-${string}`;
+
+/** Theme-derived native-select artwork; data URIs cannot inherit CSS `color`. */
+function chevronDataUri(color: string): string {
+  const svg =
+    `<svg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6'>` +
+    `<path d='M1 1L5 5L9 1' stroke='${color}' stroke-width='1.5' fill='none' stroke-linecap='round' stroke-linejoin='round'/>` +
+    `</svg>`;
+  return `url("data:image/svg+xml,${encodeURIComponent(svg)}")`;
+}
+
+/** Map one typed theme to the semantic variables consumed by editor chrome. */
+export function editorThemeVariables(theme: EditorTheme): Record<EditorThemeVariable, string> {
+  return {
+    '--vgai-surface-shell': theme.color.surface.shell,
+    '--vgai-surface-panel': theme.color.surface.panel,
+    '--vgai-surface-chrome': theme.color.surface.chrome,
+    '--vgai-surface-raised': theme.color.surface.raised,
+    '--vgai-surface-inset': theme.color.surface.inset,
+    '--vgai-surface-overlay': theme.color.surface.overlay,
+    '--vgai-boundary-default': theme.color.boundary.default,
+    '--vgai-boundary-strong': theme.color.boundary.strong,
+    '--vgai-content-primary': theme.color.content.primary,
+    '--vgai-content-muted': theme.color.content.muted,
+    '--vgai-content-dim': theme.color.content.dim,
+    '--vgai-content-on-accent': theme.color.content.onAccent,
+    '--vgai-accent': theme.color.accent.default,
+    '--vgai-accent-muted': theme.color.accent.muted,
+    '--vgai-danger': theme.color.semantic.danger,
+    '--vgai-danger-muted': theme.color.semantic.dangerMuted,
+    '--vgai-danger-faint': theme.color.semantic.dangerFaint,
+    '--vgai-warn': theme.color.semantic.warning,
+    '--vgai-warn-muted': theme.color.semantic.warningMuted,
+    '--vgai-success': theme.color.semantic.success,
+    '--vgai-success-muted': theme.color.semantic.successMuted,
+    '--vgai-dynamic': theme.color.semantic.dynamic,
+    '--vgai-dynamic-muted': theme.color.semantic.dynamicMuted,
+    '--vgai-neutral-hover': theme.color.neutralOverlay.hover,
+    '--vgai-neutral-active': theme.color.neutralOverlay.active,
+    '--vgai-scrim': theme.color.scrim,
+    '--vgai-font-sans': theme.typography.sans,
+    '--vgai-font-mono': theme.typography.mono,
+    '--vgai-radius-sm': theme.shape.small,
+    '--vgai-radius-md': theme.shape.medium,
+    '--vgai-radius-lg': theme.shape.large,
+    '--vgai-radius-full': theme.shape.full,
+    '--vgai-shadow-sm': theme.elevation.small,
+    '--vgai-shadow-md': theme.elevation.medium,
+    '--vgai-shadow-lg': theme.elevation.large,
+    '--vgai-focus-ring': `1px solid ${theme.color.accent.default}`,
+    '--vgai-select-chevron': chevronDataUri(theme.color.content.muted),
+  };
+}
+
+export const EDITOR_THEME_CLASS = 'vgai-editor-theme';
+
+/** Install or switch a theme on one editor-chrome root. */
+export function applyEditorTheme(
+  root: HTMLElement,
+  theme: EditorTheme = graphiteDarkEditorTheme,
+): void {
+  root.classList.add(EDITOR_THEME_CLASS);
+  root.dataset['vgaiTheme'] = theme.id;
+  for (const [name, value] of Object.entries(editorThemeVariables(theme))) {
+    root.style.setProperty(name, value);
+  }
+}
+
+/**
+ * Re-exported from `z-index.ts` so callers can import either module for the
+ * full token set. See that file's own doc comment for the scale rationale.
+ */
+export { zIndex } from './z-index';