@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.0b5b49f

package/dist/theme/hct.js

@@ -0,0 +1,221 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file hct.ts
+ * @input Hex color string (#RRGGBB)
+ * @output HCT color representation (Hue, Chroma, Tone)
+ * @position Theme utility; consumed by expandColorScale.ts
+ *
+ * Minimal HCT (Hue, Chroma, Tone) color space implementation.
+ * Ported from Google's material-color-utilities (Apache-2.0).
+ * Zero runtime dependencies — all math is self-contained.
+ *
+ * HCT combines:
+ * - Hue from CIELab (perceptually uniform hue)
+ * - Chroma approximated via CIELab C*ab (colorfulness)
+ * - Tone from L* (CIE Lightness, 0=black, 100=white)
+ */
+
+// =============================================================================
+// Types
+// =============================================================================
+
+// =============================================================================
+// sRGB <-> Linear RGB
+// =============================================================================
+
+function srgbToLinear(c) {
+  const s = c / 255;
+  return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+}
+function linearToSrgb(c) {
+  const s = c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+  return Math.round(Math.min(255, Math.max(0, s * 255)));
+}
+
+// =============================================================================
+// Linear RGB <-> XYZ (D65 illuminant)
+// =============================================================================
+
+function linearRgbToXyz(r, g, b) {
+  return [0.4124564 * r + 0.3575761 * g + 0.1804375 * b, 0.2126729 * r + 0.7151522 * g + 0.072175 * b, 0.0193339 * r + 0.119192 * g + 0.9503041 * b];
+}
+function xyzToLinearRgb(x, y, z) {
+  return [3.2404542 * x - 1.5371385 * y - 0.4985314 * z, -0.969266 * x + 1.8760108 * y + 0.041556 * z, 0.0556434 * x - 0.2040259 * y + 1.0572252 * z];
+}
+
+// =============================================================================
+// XYZ <-> L*a*b*
+// =============================================================================
+
+const D65_WHITE = [0.95047, 1.0, 1.08883];
+function labF(t) {
+  const delta = 6 / 29;
+  return t > delta * delta * delta ? Math.cbrt(t) : t / (3 * delta * delta) + 4 / 29;
+}
+function labFInv(t) {
+  const delta = 6 / 29;
+  return t > delta ? t * t * t : 3 * delta * delta * (t - 4 / 29);
+}
+function xyzToLab(x, y, z) {
+  const fx = labF(x / D65_WHITE[0]);
+  const fy = labF(y / D65_WHITE[1]);
+  const fz = labF(z / D65_WHITE[2]);
+  return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+}
+function labToXyz(L, a, b) {
+  const fy = (L + 16) / 116;
+  const fx = a / 500 + fy;
+  const fz = fy - b / 200;
+  return [labFInv(fx) * D65_WHITE[0], labFInv(fy) * D65_WHITE[1], labFInv(fz) * D65_WHITE[2]];
+}
+
+// =============================================================================
+// Tone <-> Y (CIE Luminance)
+// =============================================================================
+
+export function toneToY(tone) {
+  return labFInv((tone + 16) / 116);
+}
+export function yToTone(y) {
+  return 116 * labF(y) - 16;
+}
+
+// =============================================================================
+// Hex <-> RGB
+// =============================================================================
+
+function hexToRgb(hex) {
+  const h = hex.replace('#', '');
+  const full = h.length === 3 ? h[0] + h[0] + h[1] + h[1] + h[2] + h[2] : h.slice(0, 6);
+  const n = parseInt(full, 16);
+  return [n >> 16 & 0xff, n >> 8 & 0xff, n & 0xff];
+}
+function rgbToHex(r, g, b) {
+  return '#' + [r, g, b].map(c => c.toString(16).padStart(2, '0')).join('').toUpperCase();
+}
+
+// =============================================================================
+// Core: Hex <-> HCT
+// =============================================================================
+
+/**
+ * Convert a hex color to HCT.
+ * Hue: 0-360, Chroma: 0-~120, Tone: 0-100.
+ */
+export function hexToHct(hex) {
+  const [r, g, b] = hexToRgb(hex);
+  const lr = srgbToLinear(r);
+  const lg = srgbToLinear(g);
+  const lb = srgbToLinear(b);
+  const [x, y, z] = linearRgbToXyz(lr, lg, lb);
+  const [L, a, bLab] = xyzToLab(x, y, z);
+  const hueRad = Math.atan2(bLab, a);
+  let hue = hueRad * 180 / Math.PI;
+  if (hue < 0) {
+    hue += 360;
+  }
+  const chroma = Math.sqrt(a * a + bLab * bLab);
+  const tone = L;
+  return {
+    hue,
+    chroma,
+    tone: Math.max(0, Math.min(100, tone))
+  };
+}
+
+/**
+ * Convert HCT to hex, with gamut mapping.
+ * Uses chroma reduction to find the closest in-gamut sRGB color.
+ */
+export function hctToHex(hct) {
+  const {
+    hue,
+    chroma,
+    tone
+  } = hct;
+  if (tone <= 0) {
+    return '#000000';
+  }
+  if (tone >= 100) {
+    return '#FFFFFF';
+  }
+  if (chroma < 0.5) {
+    const gray = toneToGray(tone);
+    return rgbToHex(gray, gray, gray);
+  }
+  let lo = 0;
+  let hi = chroma;
+  let bestHex = '#000000';
+  for (let i = 0; i < 16; i++) {
+    const mid = (lo + hi) / 2;
+    const candidate = hctComponentToHex(hue, mid, tone);
+    if (candidate !== null) {
+      bestHex = candidate;
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+  return bestHex;
+}
+function toneToGray(tone) {
+  const y = toneToY(tone);
+  return linearToSrgb(y);
+}
+function hctComponentToHex(hue, chroma, tone) {
+  const hueRad = hue * Math.PI / 180;
+  const a = Math.cos(hueRad) * chroma;
+  const b = Math.sin(hueRad) * chroma;
+  const L = tone;
+  const [x, y, z] = labToXyz(L, a, b);
+  const [lr, lg, lb] = xyzToLinearRgb(x, y, z);
+  const r = linearToSrgb(lr);
+  const g = linearToSrgb(lg);
+  const bVal = linearToSrgb(lb);
+  const rLin = srgbToLinear(r);
+  const gLin = srgbToLinear(g);
+  const bLin = srgbToLinear(bVal);
+  const tolerance = 0.02;
+  if (Math.abs(rLin - lr) > tolerance || Math.abs(gLin - lg) > tolerance || Math.abs(bLin - lb) > tolerance) {
+    return null;
+  }
+  if (r < 0 || r > 255 || g < 0 || g > 255 || bVal < 0 || bVal > 255) {
+    return null;
+  }
+  return rgbToHex(r, g, bVal);
+}
+
+// =============================================================================
+// Tonal Palette
+// =============================================================================
+
+const PALETTE_TONES = [0, 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100];
+
+/**
+ * Generate a tonal palette: hex colors at standard tones
+ * for a given hue and chroma.
+ */
+export function tonalPalette(hue, chroma) {
+  const result = {};
+  for (const tone of PALETTE_TONES) {
+    result[tone] = hctToHex({
+      hue,
+      chroma,
+      tone
+    });
+  }
+  return result;
+}
+
+// =============================================================================
+// Utility: hex with alpha
+// =============================================================================
+
+/**
+ * Append alpha (0-1) to a hex color as a 2-digit hex suffix.
+ */
+export function hexWithAlpha(hex, alpha) {
+  const alphaHex = Math.round(alpha * 255).toString(16).padStart(2, '0').toUpperCase();
+  return hex + alphaHex;
+}

package/dist/theme/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Astryx Theme System
+ *
+ * Exports:
+ * - Theme: Provider component that applies theme
+ * - defineTheme: Create themes with token + component overrides
+ * - Token exports for direct use in StyleX
+ *
+ * Themes are in separate packages:
+ *   import { neutralTheme } from '@astryxdesign/theme-neutral';
+ *   import { neutralTheme } from '@astryxdesign/theme-neutral';
+ */
+export { Theme } from './Theme';
+export { MediaTheme } from './MediaTheme';
+export type { MediaThemeProps } from './MediaTheme';
+export { defineTheme, generateThemeCSS, generateThemeCSSFlat, generateOnMediaCSS, generateThemeRules, generateThemeRulesSplit, type ThemeCSSOutput, type ThemeRulesSplit, isDefinedTheme, xdsTokenDefaults, } from './defineTheme';
+export type { DefineThemeInput, DefinedTheme, CoreTokenName, TokenName, TokenValue, ComponentStyleMap, StyleOverrides, } from './defineTheme';
+export type { SyntaxTokenName, DomainTokenName, DataTokenName, } from './domainTokens';
+export { syntaxTokenDefaults, domainTokenDefaults, dataTokenDefaults, } from './domainTokens';
+export { defineSyntaxTheme } from './syntax';
+export type { SyntaxThemeDefinition, SyntaxThemeInput, SyntaxThemeTokenKey, SyntaxThemeTokenMap, SyntaxThemeTokenInput, SyntaxTokenValue, } from './syntax';
+export { SyntaxTheme, useSyntaxTheme } from './syntax';
+export type { UseSyntaxThemeReturn } from './syntax';
+export { expandTypeScale, generateTypeScaleComponents } from './expandTypeScale';
+export type { TypeScaleConfig, TypeScaleTokens } from './expandTypeScale';
+export { expandRadiusScale } from './expandRadiusScale';
+export type { RadiusScaleConfig, RadiusScaleTokens, } from './expandRadiusScale';
+export { expandColorScale } from './expandColorScale';
+export type { ColorScaleConfig, ColorScaleTokens } from './expandColorScale';
+export { expandMotionScale } from './expandMotionScale';
+export type { MotionScaleConfig, MotionScaleTokens, } from './expandMotionScale';
+export { colorDefaults, spacingDefaults, sizeDefaults, borderDefaults, radiusDefaults, shadowDefaults, durationDefaults, easeDefaults, transitionDefaults, typographyDefaults, textSizeDefaults, fontWeightDefaults, typeScaleDefaults, colorVars, spacingVars, sizeVars, borderVars, radiusVars, shadowVars, durationVars, easeVars, transitionVars, typographyVars, textSizeVars, fontWeightVars, typeScaleVars, } from './tokens.stylex';
+export type { ColorVarName, SpacingVarName, SizeVarName, BorderVarName, RadiusVarName, ShadowVarName, DurationVarName, EaseVarName, TransitionVarName, TypographyVarName, TextSizeVarName, FontWeightVarName, TypeScaleVarName, } from './tokens.stylex';
+export { useTheme, ThemeContext } from './useTheme';
+export type { UseThemeReturn, ThemeContextValue } from './useTheme';
+export { resolveThemeToken, resolveThemeTokens, tokenVar, tokenVars, } from './tokens';
+export type { ResolveThemeTokenOptions, ResolveThemeTokensOptions, ResolvedThemeMode, } from './tokens';
+export type { ThemeMode, HeadingTag, TextType, BuiltinTextType, CustomTextTypes, TextSize, TextWeight, TextColor, TypographyConfig, TypographyRole, FontWeight, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/theme/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,KAAK,EAAC,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,YAAY,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,eAAe,EACf,eAAe,EACf,aAAa,GACd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAC,iBAAiB,EAAC,MAAM,UAAU,CAAC;AAC3C,YAAY,EACV,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAC,WAAW,EAAE,cAAc,EAAC,MAAM,UAAU,CAAC;AACrD,YAAY,EAAC,oBAAoB,EAAC,MAAM,UAAU,CAAC;AAEnD,OAAO,EAAC,eAAe,EAAE,2BAA2B,EAAC,MAAM,mBAAmB,CAAC;AAC/E,YAAY,EAAC,eAAe,EAAE,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAExE,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EACV,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AACpD,YAAY,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAC,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AACtD,YAAY,EACV,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,EACd,aAAa,GACd,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAC,QAAQ,EAAE,YAAY,EAAC,MAAM,YAAY,CAAC;AAClD,YAAY,EAAC,cAAc,EAAE,iBAAiB,EAAC,MAAM,YAAY,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,EACR,SAAS,GACV,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,QAAQ,EACR,UAAU,EACV,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,UAAU,GACX,MAAM,SAAS,CAAC"}

package/dist/theme/index.js

@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * Astryx Theme System
+ *
+ * Exports:
+ * - Theme: Provider component that applies theme
+ * - defineTheme: Create themes with token + component overrides
+ * - Token exports for direct use in StyleX
+ *
+ * Themes are in separate packages:
+ *   import { neutralTheme } from '@astryxdesign/theme-neutral';
+ *   import { neutralTheme } from '@astryxdesign/theme-neutral';
+ */
+export { Theme } from "./Theme.js";
+export { MediaTheme } from "./MediaTheme.js";
+export { defineTheme, generateThemeCSS, generateThemeCSSFlat, generateOnMediaCSS, generateThemeRules, generateThemeRulesSplit, isDefinedTheme, xdsTokenDefaults } from "./defineTheme.js";
+export { syntaxTokenDefaults, domainTokenDefaults, dataTokenDefaults } from "./domainTokens/index.js";
+
+// Syntax theme API
+export { defineSyntaxTheme } from "./syntax/index.js";
+// SyntaxTheme provider
+export { SyntaxTheme, useSyntaxTheme } from "./syntax/index.js";
+export { expandTypeScale, generateTypeScaleComponents } from "./expandTypeScale.js";
+export { expandRadiusScale } from "./expandRadiusScale.js";
+export { expandColorScale } from "./expandColorScale.js";
+export { expandMotionScale } from "./expandMotionScale.js";
+// Export token defaults and vars for use in custom components and themes
+export { colorDefaults, spacingDefaults, sizeDefaults, borderDefaults, radiusDefaults, shadowDefaults, durationDefaults, easeDefaults, transitionDefaults, typographyDefaults, textSizeDefaults, fontWeightDefaults, typeScaleDefaults, colorVars, spacingVars, sizeVars, borderVars, radiusVars, shadowVars, durationVars, easeVars, transitionVars, typographyVars, textSizeVars, fontWeightVars, typeScaleVars } from "./tokens.stylex.js";
+
+// Export token key types for theme authoring
+
+export { useTheme, ThemeContext } from "./useTheme.js";
+export { resolveThemeToken, resolveThemeTokens, tokenVar, tokenVars } from "./tokens.js";

package/dist/theme/onMediaTokens.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @file onMediaTokens.ts
+ * @input Theme token values from defineTheme
+ * @output Default on-dark / on-light token overrides for MediaTheme
+ * @position Theme system utility; consumed by defineTheme and generateThemeRules
+ *
+ * Generates semantic token overrides for content rendered on inverted surfaces.
+ * "onDark" = content on a dark background (light text, white-tinted interactions)
+ * "onLight" = content on a light background (dark text, black-tinted interactions)
+ *
+ * The primary mechanism is `color-scheme` — setting `color-scheme: dark` on the
+ * media element makes all `light-dark()` tokens resolve to their dark-side values.
+ * Only a small set of tokens need explicit overrides (text/icon primary use
+ * `var(--color-on-dark)` instead of the dark-mode grey, accent collapses to
+ * on-color, etc.).
+ *
+ * Themes can provide additional token and component overrides via the
+ * `onDark`/`onLight` fields in `defineTheme()`.
+ */
+import type { TokenValue, ComponentStyleMap } from './defineTheme';
+/**
+ * On-media theme overrides — same shape as the main theme but scoped
+ * to a surface luminance context.
+ */
+export interface OnMediaOverrides {
+    /** Token overrides for this surface context */
+    tokens?: Partial<Record<string, TokenValue>>;
+    /** Component style overrides for this surface context */
+    components?: ComponentStyleMap;
+}
+/**
+ * Resolved on-media overrides stored on DefinedTheme.
+ * @internal
+ */
+export interface ResolvedOnMedia {
+    /** Resolved token CSS values */
+    tokens: Record<string, string>;
+    /** Component style overrides (passthrough from input) */
+    components?: ComponentStyleMap;
+}
+/**
+ * Default token overrides for content on a dark surface.
+ *
+ * Most tokens work automatically via `color-scheme: dark` which flips
+ * `light-dark()` values. These overrides handle the tokens that need
+ * different values on an inverted surface vs a dark page background.
+ */
+export declare const defaultOnDarkTokens: Record<string, string>;
+/**
+ * Default token overrides for content on a light surface.
+ */
+export declare const defaultOnLightTokens: Record<string, string>;
+/**
+ * Resolve on-media overrides: merge user tokens with defaults,
+ * pass through component overrides.
+ */
+export declare function resolveOnMedia(surface: 'dark' | 'light', input?: OnMediaOverrides): ResolvedOnMedia;
+//# sourceMappingURL=onMediaTokens.d.ts.map

package/dist/theme/onMediaTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onMediaTokens.d.ts","sourceRoot":"","sources":["../../src/theme/onMediaTokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7C,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yDAAyD;IACzD,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAStD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CASvD,CAAC;AAYF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,GAAG,OAAO,EACzB,KAAK,CAAC,EAAE,gBAAgB,GACvB,eAAe,CAkBjB"}

package/dist/theme/onMediaTokens.js

@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file onMediaTokens.ts
+ * @input Theme token values from defineTheme
+ * @output Default on-dark / on-light token overrides for MediaTheme
+ * @position Theme system utility; consumed by defineTheme and generateThemeRules
+ *
+ * Generates semantic token overrides for content rendered on inverted surfaces.
+ * "onDark" = content on a dark background (light text, white-tinted interactions)
+ * "onLight" = content on a light background (dark text, black-tinted interactions)
+ *
+ * The primary mechanism is `color-scheme` — setting `color-scheme: dark` on the
+ * media element makes all `light-dark()` tokens resolve to their dark-side values.
+ * Only a small set of tokens need explicit overrides (text/icon primary use
+ * `var(--color-on-dark)` instead of the dark-mode grey, accent collapses to
+ * on-color, etc.).
+ *
+ * Themes can provide additional token and component overrides via the
+ * `onDark`/`onLight` fields in `defineTheme()`.
+ */
+
+/**
+ * On-media theme overrides — same shape as the main theme but scoped
+ * to a surface luminance context.
+ */
+
+/**
+ * Resolved on-media overrides stored on DefinedTheme.
+ * @internal
+ */
+
+/**
+ * Default token overrides for content on a dark surface.
+ *
+ * Most tokens work automatically via `color-scheme: dark` which flips
+ * `light-dark()` values. These overrides handle the tokens that need
+ * different values on an inverted surface vs a dark page background.
+ */
+export const defaultOnDarkTokens = {
+  'color-scheme': 'dark',
+  // Text/icon primary — pure on-color, not dark-mode grey
+  '--color-text-primary': 'var(--color-on-dark)',
+  '--color-icon-primary': 'var(--color-on-dark)',
+  // Accent collapses to on-color in inverted context
+  '--color-accent': 'var(--color-on-dark)'
+};
+
+/**
+ * Default token overrides for content on a light surface.
+ */
+export const defaultOnLightTokens = {
+  'color-scheme': 'light',
+  // Text/icon primary — pure on-color, not light-mode dark
+  '--color-text-primary': 'var(--color-on-light)',
+  '--color-icon-primary': 'var(--color-on-light)',
+  // Accent collapses to on-color
+  '--color-accent': 'var(--color-on-light)'
+};
+
+/**
+ * Resolve a token value to a CSS string.
+ */
+function resolveValue(value) {
+  if (Array.isArray(value)) {
+    return `light-dark(${value[0]}, ${value[1]})`;
+  }
+  return value;
+}
+
+/**
+ * Resolve on-media overrides: merge user tokens with defaults,
+ * pass through component overrides.
+ */
+export function resolveOnMedia(surface, input) {
+  const defaults = surface === 'dark' ? defaultOnDarkTokens : defaultOnLightTokens;
+  const tokens = {
+    ...defaults
+  };
+  if (input?.tokens) {
+    for (const [key, value] of Object.entries(input.tokens)) {
+      if (value !== undefined) {
+        tokens[key] = resolveValue(value);
+      }
+    }
+  }
+  return {
+    tokens,
+    components: input?.components
+  };
+}

package/dist/theme/syntax/SyntaxTheme.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file SyntaxTheme.tsx
+ * @input SyntaxTheme from defineSyntaxTheme.ts
+ * @output SyntaxTheme provider, useSyntaxTheme hook
+ * @position Provider component; wraps code surfaces to apply syntax coloring
+ *
+ * @see https://github.com/facebookexperimental/xds/issues/1148
+ */
+import React from 'react';
+import { type SyntaxThemeDefinition, type SyntaxThemeTokenKey } from './defineSyntaxTheme';
+export interface UseSyntaxThemeReturn {
+    /** Syntax theme name */
+    name: string;
+    /** Resolved effective mode ('light' | 'dark') */
+    mode: 'light' | 'dark';
+    /**
+     * Resolve a syntax token to its raw CSS value for the current color mode.
+     *
+     * @example
+     * const keywordColor = token('keyword'); // "#0064E0" in light mode
+     */
+    token: (name: SyntaxThemeTokenKey) => string;
+    /**
+     * All syntax tokens resolved for the current color mode.
+     */
+    tokens: Record<SyntaxThemeTokenKey, string>;
+}
+/**
+ * Access the current syntax theme's token values, resolved for the active
+ * color mode. Returns null if no SyntaxTheme provider is present.
+ *
+ * @example
+ * function CodeCanvas() {
+ *   const syntax = useSyntaxTheme();
+ *   if (!syntax) {
+ *     return null;
+ *   }
+ *   ctx.fillStyle = syntax.token('keyword');
+ * }
+ */
+export declare function useSyntaxTheme(): UseSyntaxThemeReturn | null;
+interface SyntaxThemeProps {
+    theme: SyntaxThemeDefinition;
+    children: React.ReactNode;
+}
+/**
+ * Syntax theme provider. Sets CSS custom properties on a wrapper div
+ * so child code components inherit via cascade.
+ */
+export declare function SyntaxTheme({ theme, children, }: SyntaxThemeProps): React.ReactElement;
+export declare namespace SyntaxTheme {
+    var displayName: string;
+}
+export {};
+//# sourceMappingURL=SyntaxTheme.d.ts.map

package/dist/theme/syntax/SyntaxTheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyntaxTheme.d.ts","sourceRoot":"","sources":["../../../src/theme/syntax/SyntaxTheme.tsx"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,KAAoC,MAAM,OAAO,CAAC;AACzD,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAmB7B,MAAM,WAAW,oBAAoB;IACnC,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB;;;;;OAKG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,MAAM,CAAC;IAC7C;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;CAC7C;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,oBAAoB,GAAG,IAAI,CA6B5D;AAMD,UAAU,gBAAgB;IACxB,KAAK,EAAE,qBAAqB,CAAC;IAC7B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,QAAQ,GACT,EAAE,gBAAgB,GAAG,KAAK,CAAC,YAAY,CAWvC;yBAde,WAAW"}

package/dist/theme/syntax/SyntaxTheme.js

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file SyntaxTheme.tsx
+ * @input SyntaxTheme from defineSyntaxTheme.ts
+ * @output SyntaxTheme provider, useSyntaxTheme hook
+ * @position Provider component; wraps code surfaces to apply syntax coloring
+ *
+ * @see https://github.com/facebookexperimental/xds/issues/1148
+ */
+import React, { createContext, use, useMemo } from 'react';
+import { syntaxThemeStyle, resolveSyntaxTokenForMode, ALL_SYNTAX_KEYS } from "./defineSyntaxTheme.js";
+import { useMediaQuery } from "../../hooks/useMediaQuery.js";
+
+// =============================================================================
+// Context
+// =============================================================================
+
+/** @internal */
+import { jsx as _jsx } from "react/jsx-runtime";
+const SyntaxThemeContext = /*#__PURE__*/createContext(null);
+SyntaxThemeContext.displayName = 'SyntaxThemeContext';
+
+// =============================================================================
+// Return type
+// =============================================================================
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Access the current syntax theme's token values, resolved for the active
+ * color mode. Returns null if no SyntaxTheme provider is present.
+ *
+ * @example
+ * function CodeCanvas() {
+ *   const syntax = useSyntaxTheme();
+ *   if (!syntax) {
+ *     return null;
+ *   }
+ *   ctx.fillStyle = syntax.token('keyword');
+ * }
+ */
+export function useSyntaxTheme() {
+  const ctx = use(SyntaxThemeContext);
+  const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
+  const effectiveMode = prefersDark ? 'dark' : 'light';
+  const tokens = useMemo(() => {
+    if (!ctx) {
+      return null;
+    }
+    const resolved = {};
+    for (const key of ALL_SYNTAX_KEYS) {
+      resolved[key] = resolveSyntaxTokenForMode(ctx.theme.__inputTokens[key], effectiveMode);
+    }
+    return resolved;
+  }, [ctx, effectiveMode]);
+  if (!ctx || !tokens) {
+    return null;
+  }
+  return {
+    name: ctx.theme.name,
+    mode: effectiveMode,
+    token: name => tokens[name] ?? '',
+    tokens
+  };
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Syntax theme provider. Sets CSS custom properties on a wrapper div
+ * so child code components inherit via cascade.
+ */
+export function SyntaxTheme({
+  theme,
+  children
+}) {
+  const style = useMemo(() => syntaxThemeStyle(theme), [theme]);
+  const value = useMemo(() => ({
+    theme
+  }), [theme]);
+  return /*#__PURE__*/_jsx(SyntaxThemeContext, {
+    value: value,
+    children: /*#__PURE__*/_jsx("div", {
+      style: style,
+      "data-astryx-syntax-theme": theme.name,
+      children: children
+    })
+  });
+}
+SyntaxTheme.displayName = 'SyntaxTheme';

package/dist/theme/syntax/defineSyntaxTheme.d.ts

@@ -0,0 +1,58 @@
+/** Human-readable syntax token name (without CSS custom property prefix). */
+export type SyntaxThemeTokenKey = 'keyword' | 'string' | 'comment' | 'number' | 'function' | 'type' | 'variable' | 'operator' | 'constant' | 'tag' | 'attribute' | 'property' | 'punctuation' | 'background';
+/**
+ * Token value — either a single string or a [light, dark] tuple.
+ * Tuples are converted to CSS light-dark() at theme creation time.
+ */
+export type SyntaxTokenValue = string | [light: string, dark: string];
+/** Token map for defineSyntaxTheme input — values can be strings or tuples. */
+export type SyntaxThemeTokenInput = Record<SyntaxThemeTokenKey, SyntaxTokenValue>;
+/** Resolved token map — all values are CSS strings (tuples resolved to light-dark()). */
+export type SyntaxThemeTokenMap = Record<SyntaxThemeTokenKey, string>;
+/** Input to defineSyntaxTheme. */
+export interface SyntaxThemeInput {
+    name: string;
+    tokens: SyntaxThemeTokenInput;
+}
+/** A defined syntax theme — tokens are resolved to CSS strings. */
+export interface SyntaxThemeDefinition {
+    /** Theme name */
+    name: string;
+    /** Resolved token values (light-dark() CSS strings) */
+    tokens: SyntaxThemeTokenMap;
+    /** Original input tokens (preserves tuples for mode resolution) */
+    __inputTokens: SyntaxThemeTokenInput;
+}
+/** All valid human-readable token keys, derived from the defaults. */
+export declare const ALL_SYNTAX_KEYS: SyntaxThemeTokenKey[];
+/**
+ * Resolve a token value for a specific color mode.
+ * - [light, dark] tuple → picks the correct side
+ * - light-dark(a, b) string → parses and picks
+ * - plain string → pass through
+ */
+export declare function resolveSyntaxTokenForMode(value: SyntaxTokenValue, mode: 'light' | 'dark'): string;
+/**
+ * Create a syntax theme from a complete token map.
+ *
+ * Token values can be:
+ * - A string: used as-is (e.g. '#ff79c6' or 'light-dark(#0064E0, #2694FE)')
+ * - A [light, dark] tuple: converted to light-dark(light, dark)
+ *
+ * @example
+ * const myTheme = defineSyntaxTheme({
+ *   name: 'my-theme',
+ *   tokens: {
+ *     keyword: ['#0064E0', '#2694FE'],     // [light, dark] tuple
+ *     string: '#98c379',                    // same in both modes
+ *     comment: 'light-dark(#666, #999)',    // CSS light-dark() string
+ *     // ... all 14 tokens
+ *   },
+ * });
+ */
+export declare function defineSyntaxTheme(input: SyntaxThemeInput): SyntaxThemeDefinition;
+/** Generate a CSS custom property style object for React's style prop. */
+export declare function syntaxThemeStyle(theme: SyntaxThemeDefinition): Record<string, string>;
+/** Convert a syntax theme to CSS declarations (no selector wrapper). */
+export declare function syntaxThemeToCSS(theme: SyntaxThemeDefinition): string;
+//# sourceMappingURL=defineSyntaxTheme.d.ts.map