An open source design system that's fully customizable and agent ready
TypeScript
feat(theme): add token resolution utilities (#2819)
Cindy Zhang92c39e93fdfd
diff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjsindex 6687fe6888..24e0954aa0 100644--- a/packages/cli/docs/theme.doc.mjs+++ b/packages/cli/docs/theme.doc.mjs@@ -171,7 +171,7 @@ const myTheme = defineTheme({],['radius',- '--radius-1 through --radius-4, --radius-container, --radius-page',+ '--radius-inner, --radius-element, --radius-container, --radius-page, --radius-chat','base (px), multiplier (0–2)',],[@@ -496,30 +496,87 @@ import './themes/ocean.css';},],},+ {+ title: 'Token Utilities',+ category: 'guide',+ content: [+ {+ type: 'prose',+ text: 'Use `xdsTokenVar()` when a non-StyleX styling library wants a CSS variable reference, and `resolveXDSThemeTokens()` when JavaScript needs token values for a specific theme and mode without React context.',+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'CSS var references for styling-library configs',+ code: `import {xdsTokenVar, xdsTokenVars} from '@xds/core/theme/tokens';++const pandaOrEmotionTheme = {+ colors: {+ text: xdsTokenVar('--color-text-primary'),+ surface: xdsTokenVars['--color-background-surface'],+ },+ spacing: {+ 4: xdsTokenVars['--spacing-4'],+ },+};`,+ },+ {+ type: 'code',+ lang: 'ts',+ label: 'Resolve token values without a hook',+ code: `import {resolveXDSThemeTokens} from '@xds/core/theme/tokens';+import {defaultTheme} from '@xds/theme-default';++const lightTokens = resolveXDSThemeTokens(defaultTheme, {mode: 'light'});+const chartTheme = {+ textColor: lightTokens['--color-text-primary'],+ seriesColor: lightTokens['--color-data-categorical-blue'],+};`,+ },+ {+ type: 'prose',+ text: 'The `@xds/core/theme/tokens` subpath is server-safe and does not require React. The main `@xds/core/theme` barrel also re-exports these helpers for client code that already imports theme APIs.',+ },+ ],+ },{title: 'useXDSTheme Hook',category: 'guide',content: [+ {+ type: 'prose',+ text: '`useXDSTheme()` uses the same token resolution as `resolveXDSThemeTokens()`, but reads the nearest XDSTheme and effective color mode from React context and media query state. Use it inside client components for SVG, canvas, charts, maps, and third-party configuration objects that need token values in JavaScript instead of `var(...)` references.',+ },{type: 'code',lang: 'tsx',- label: 'Access current theme',- code: `import {useXDSTheme} from '@xds/core';+ label: 'Access resolved token values in React',+ code: `import {useMemo} from 'react';+import {useXDSTheme} from '@xds/core/theme';++function ChartConfig() {+ const {mode, tokens} = useXDSTheme();++ const options = useMemo(+ () => ({+ mode,+ textColor: tokens['--color-text-primary'],+ gridColor: tokens['--color-border'],+ seriesColor: tokens['--color-data-categorical-blue'],+ }),+ [mode, tokens],+ );-function MyComponent() {- const ctx = useXDSTheme();- // ctx.theme — the XDSDefinedTheme object- // ctx.mode — 'system' | 'light' | 'dark'- return null;+ return <Chart options={options} />;}`,},{type: 'prose',- text: 'This is read-only. To change the theme/mode, manage state at the app level and pass it to <XDSTheme>.',+ text: 'Prefer CSS variables, StyleX token imports, xstyle, or className for ordinary styling. To change the theme or mode, manage state at the app level and pass it to <XDSTheme>.',},{type: 'prose',- text: 'See `npx xds docs styling` for component-level customization (xstyle, className, rest props). See `npx xds docs tokens` for the full token reference.',+ text: 'See `npx xds docs styling` for component-level customization and `npx xds docs tokens` for the full token reference.',},],},diff --git a/packages/core/package.json b/packages/core/package.jsonindex 1a6edf4dc6..9a56b7c229 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -51,6 +51,11 @@"types": "./src/tailwind-theme.css.d.ts","default": "./src/tailwind-theme.css"},+ "./theme/tokens": {+ "source": "./src/theme/tokens.ts",+ "types": "./dist/theme/tokens.d.ts",+ "default": "./dist/theme/tokens.js"+ },"./theme/tokens.stylex": {"source": "./src/theme/tokens.stylex.ts","types": "./dist/theme/tokens.stylex.d.ts",diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.tsindex 86e4a4389d..580e4352aa 100644--- a/packages/core/src/theme/index.ts+++ b/packages/core/src/theme/index.ts@@ -134,6 +134,17 @@ export type {export {useXDSTheme, XDSThemeContext} from './useXDSTheme';export type {UseXDSThemeReturn, XDSThemeContextValue} from './useXDSTheme';+export {+ resolveXDSThemeToken,+ resolveXDSThemeTokens,+ xdsTokenVar,+ xdsTokenVars,+} from './tokens';+export type {+ ResolveXDSThemeTokenOptions,+ ResolveXDSThemeTokensOptions,+ XDSResolvedThemeMode,+} from './tokens';export type {ThemeMode,diff --git a/packages/core/src/theme/tokens.test.ts b/packages/core/src/theme/tokens.test.tsnew file mode 100644index 0000000000..0c8ae26b4d--- /dev/null+++ b/packages/core/src/theme/tokens.test.ts@@ -0,0 +1,109 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it} from 'vitest';+import {defineTheme} from './defineTheme';+import {+ resolveXDSThemeToken,+ resolveXDSThemeTokens,+ xdsTokenVar,+ xdsTokenVars,+} from './tokens';++const testTheme = defineTheme({+ name: 'test',+ tokens: {+ '--color-accent': ['#AA0000', '#FF5555'],+ '--color-neutral': ['rgba(5, 54, 89, 0.1)', 'rgba(223, 226, 229, 0.2)'],+ '--spacing-4': '20px',+ },+});++describe('xdsTokenVar', () => {+ it('returns a CSS var() reference for known token names', () => {+ expect(xdsTokenVar('--color-text-primary')).toBe(+ 'var(--color-text-primary)',+ );+ });++ it('returns a CSS var() reference for custom token names', () => {+ expect(xdsTokenVar('--app-custom-token')).toBe('var(--app-custom-token)');+ });+});++describe('xdsTokenVars', () => {+ it('contains var() references for known tokens', () => {+ expect(xdsTokenVars['--color-text-primary']).toBe(+ 'var(--color-text-primary)',+ );+ expect(xdsTokenVars['--spacing-4']).toBe('var(--spacing-4)');+ });+});++describe('resolveXDSThemeTokens', () => {+ it('resolves defaults when no theme is provided', () => {+ const tokens = resolveXDSThemeTokens(null, {mode: 'light'});+ expect(tokens['--color-text-primary']).toBe('#0A1317');+ expect(tokens['--spacing-1']).toBe('4px');+ });++ it('resolves tuple overrides using original input tokens', () => {+ const light = resolveXDSThemeTokens(testTheme, {mode: 'light'});+ const dark = resolveXDSThemeTokens(testTheme, {mode: 'dark'});++ expect(light['--color-accent']).toBe('#AA0000');+ expect(dark['--color-accent']).toBe('#FF5555');+ });++ it('resolves tuple overrides with nested comma values', () => {+ const light = resolveXDSThemeTokens(testTheme, {mode: 'light'});+ const dark = resolveXDSThemeTokens(testTheme, {mode: 'dark'});++ expect(light['--color-neutral']).toBe('rgba(5, 54, 89, 0.1)');+ expect(dark['--color-neutral']).toBe('rgba(223, 226, 229, 0.2)');+ });++ it('resolves built theme light-dark() strings without __inputTokens', () => {+ const builtTheme = {+ name: 'built',+ __built: true,+ tokens: {+ '--color-neutral':+ 'light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))',+ },+ } as const;++ const light = resolveXDSThemeTokens(builtTheme, {mode: 'light'});+ const dark = resolveXDSThemeTokens(builtTheme, {mode: 'dark'});++ expect(light['--color-neutral']).toBe('rgba(5, 54, 89, 0.1)');+ expect(dark['--color-neutral']).toBe('rgba(223, 226, 229, 0.2)');+ });++ it('resolves single-value overrides unchanged', () => {+ const tokens = resolveXDSThemeTokens(testTheme, {mode: 'light'});+ expect(tokens['--spacing-4']).toBe('20px');+ });+});++describe('resolveXDSThemeToken', () => {+ it('resolves one token', () => {+ expect(+ resolveXDSThemeToken(testTheme, '--color-accent', {mode: 'dark'}),+ ).toBe('#FF5555');+ });++ it('returns fallback for unknown token names', () => {+ expect(+ resolveXDSThemeToken(testTheme, '--missing-token', {+ mode: 'dark',+ fallback: 'fallback',+ }),+ ).toBe('fallback');+ });++ it('returns empty string for unknown token names without fallback', () => {+ expect(+ resolveXDSThemeToken(testTheme, '--missing-token', {mode: 'dark'}),+ ).toBe('');+ });+});diff --git a/packages/core/src/theme/tokens.ts b/packages/core/src/theme/tokens.tsnew file mode 100644index 0000000000..73f5872b00--- /dev/null+++ b/packages/core/src/theme/tokens.ts@@ -0,0 +1,196 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file tokens.ts+ * @input XDSDefinedTheme objects and token names+ * @output Server-safe token helpers for resolving theme values and building CSS var references+ * @position Public theme utility; backs useXDSTheme and external styling-library adapters+ *+ * Use these helpers when code outside React hooks needs XDS token values:+ * build-time theme adapters, chart configuration, canvas/SVG rendering, tests,+ * or plain JS theme objects for other styling libraries.+ *+ * SYNC: When modified, update:+ * - /packages/core/src/theme/useXDSTheme.ts+ * - /packages/core/src/theme/index.ts+ */++import {+ xdsTokenDefaults,+ type XDSDefinedTheme,+ type XDSTokenName,+ type XDSTokenValue,+} from './defineTheme';++/** Resolved color mode used when choosing the side of light/dark token values. */+export type XDSResolvedThemeMode = 'light' | 'dark';++/** Options for resolving all tokens from a theme object. */+export interface ResolveXDSThemeTokensOptions {+ /** Effective mode to resolve. Pass an explicit value; this helper does not read media queries. */+ mode: XDSResolvedThemeMode;+}++/** Options for resolving one token from a theme object. */+export interface ResolveXDSThemeTokenOptions extends ResolveXDSThemeTokensOptions {+ /** Value to return when the token name is unknown. Defaults to an empty string. */+ fallback?: string;+}++/**+ * Return a CSS custom property reference for an XDS token name.+ *+ * Useful for non-StyleX styling-library configs (Panda, Chakra, MUI,+ * Emotion, styled-components, UnoCSS, CSS Modules) where the value should+ * stay connected to the active XDS theme through the CSS cascade.+ *+ * @example+ * ```ts+ * const theme = {+ * colors: {+ * text: xdsTokenVar('--color-text-primary'),+ * surface: xdsTokenVar('--color-background-surface'),+ * },+ * };+ * ```+ */+export function xdsTokenVar(name: XDSTokenName | (string & {})): string {+ return `var(${name})`;+}++/** Flat map of every known XDS token name to its `var(--token-name)` reference. */+export const xdsTokenVars: Record<XDSTokenName, string> = Object.fromEntries(+ Object.keys(xdsTokenDefaults).map(name => [name, xdsTokenVar(name)]),+) as Record<XDSTokenName, string>;++/**+ * Split the arguments of a CSS function body on the first top-level comma.+ * Handles nested functions such as rgba(), color-mix(), var(), and quoted strings.+ */+function splitTopLevelComma(input: string): [string, string] | null {+ let depth = 0;+ let quote: '"' | "'" | null = null;+ let isEscaped = false;++ for (let i = 0; i < input.length; i++) {+ const char = input[i];++ if (quote !== null) {+ if (isEscaped) {+ isEscaped = false;+ } else if (char === '\\') {+ isEscaped = true;+ } else if (char === quote) {+ quote = null;+ }+ continue;+ }++ if (char === '"' || char === "'") {+ quote = char;+ continue;+ }++ if (char === '(') {+ depth++;+ continue;+ }++ if (char === ')') {+ depth = Math.max(0, depth - 1);+ continue;+ }++ if (char === ',' && depth === 0) {+ return [input.slice(0, i).trim(), input.slice(i + 1).trim()];+ }+ }++ return null;+}++/** Parse a CSS light-dark(light, dark) function into its two argument values. */+function parseLightDark(value: string): [light: string, dark: string] | null {+ const trimmed = value.trim();+ const prefix = 'light-dark(';+ if (!trimmed.startsWith(prefix) || !trimmed.endsWith(')')) {+ return null;+ }++ const inner = trimmed.slice(prefix.length, -1);+ return splitTopLevelComma(inner);+}++/**+ * Resolve a token value for a specific mode.+ *+ * - `[light, dark]` tuple → picks the side for `mode`+ * - `light-dark(light, dark)` string → parses nested CSS values and picks the side+ * - any other string → returned unchanged+ */+function resolveXDSTokenValue(+ value: XDSTokenValue,+ mode: XDSResolvedThemeMode,+): string {+ if (Array.isArray(value)) {+ return mode === 'dark' ? value[1] : value[0];+ }++ const parsed = parseLightDark(value);+ if (parsed !== null) {+ return mode === 'dark' ? parsed[1] : parsed[0];+ }++ return value;+}++/**+ * Resolve all XDS token values for a theme and effective color mode.+ *+ * The result starts with `xdsTokenDefaults`, applies `theme.tokens`, then+ * reapplies `theme.__inputTokens` when available so explicit tuple overrides+ * retain their original light/dark sides instead of relying on CSS parsing.+ * This mirrors the token resolution used by `useXDSTheme()` but does not need+ * React context or media queries.+ *+ * Pass `theme` as null/undefined to resolve defaults only.+ */+export function resolveXDSThemeTokens(+ theme: XDSDefinedTheme | null | undefined,+ options: ResolveXDSThemeTokensOptions,+): Record<string, string> {+ const {mode} = options;+ const resolved: Record<string, string> = {};++ for (const [key, value] of Object.entries(xdsTokenDefaults)) {+ resolved[key] = resolveXDSTokenValue(value, mode);+ }++ if (theme == null) {+ return resolved;+ }++ for (const [key, value] of Object.entries(theme.tokens)) {+ resolved[key] = resolveXDSTokenValue(value, mode);+ }++ if (theme.__inputTokens) {+ for (const [key, value] of Object.entries(theme.__inputTokens)) {+ if (value !== undefined) {+ resolved[key] = resolveXDSTokenValue(value, mode);+ }+ }+ }++ return resolved;+}++/** Resolve one XDS token value for a theme and effective color mode. */+export function resolveXDSThemeToken(+ theme: XDSDefinedTheme | null | undefined,+ name: XDSTokenName | (string & {}),+ options: ResolveXDSThemeTokenOptions,+): string {+ const tokens = resolveXDSThemeTokens(theme, options);+ return tokens[name] ?? options.fallback ?? '';+}diff --git a/packages/core/src/theme/useXDSTheme.doc.mjs b/packages/core/src/theme/useXDSTheme.doc.mjsindex 0aaf7a9098..f1a589d200 100644--- a/packages/core/src/theme/useXDSTheme.doc.mjs+++ b/packages/core/src/theme/useXDSTheme.doc.mjs@@ -12,12 +12,13 @@ export const docs = {{name: 'name', type: 'string', description: 'Name of the nearest XDS theme, or default when no provider is present.'},{name: 'mode', type: "'light' | 'dark'", description: 'Resolved effective color mode. system mode is resolved to light or dark.'},{name: 'token', type: '(name: string) => string', description: 'Resolve a single design token to its concrete CSS value for the current mode.'},- {name: 'tokens', type: 'Record<string, string>', description: 'All tokens resolved for the current mode, including defaults and theme overrides.'},+ {name: 'tokens', type: 'Record<string, string>', description: 'All tokens resolved for the current mode, including defaults and theme overrides. Uses the same resolution logic as resolveXDSThemeTokens(theme, {mode}).'},],usage: {description: 'Programmatic access to resolved XDS theme tokens. Use it for non-CSS consumers like SVG, canvas, Vega, D3, or chart libraries that need concrete values instead of CSS custom property references.',bestPractices: [- {guidance: true, description: 'Use token(name) when integrating theme colors into SVG, canvas, or chart configuration objects.'},+ {guidance: true, description: 'Use token(name) when integrating theme colors into SVG, canvas, or chart configuration objects inside React components.'},+ {guidance: true, description: 'Use resolveXDSThemeTokens(theme, {mode}) for the same token resolution outside React hooks.'},{guidance: true, description: 'Prefer CSS variables or StyleX tokens for ordinary component styling; use this hook when values must be read in JavaScript.'},{guidance: false, description: 'Hardcode light/dark colors in data visualizations — resolve them through the current theme instead.'},],@@ -34,12 +35,13 @@ export const docsDense = {name: 'nearest XDS theme name or default.',mode: 'resolved light/dark mode.',token: 'resolve one design token to concrete CSS value.',- tokens: 'all resolved tokens for current mode.',+ tokens: 'all resolved tokens for current mode; same resolver as resolveXDSThemeTokens.',},usage: {description: 'Programmatic access to resolved XDS theme tokens for SVG/canvas/charts needing concrete values instead of CSS vars.',bestPractices: [- {guidance: true, description: 'Use token(name) for SVG/canvas/chart config theme colors.'},+ {guidance: true, description: 'Use token(name) for SVG/canvas/chart config theme colors in React.'},+ {guidance: true, description: 'Use resolveXDSThemeTokens(theme, {mode}) outside React hooks.'},{guidance: true, description: 'Prefer CSS vars / StyleX tokens for ordinary styling; use hook when JS needs values.'},{guidance: false, description: 'Hardcode light/dark chart colors — resolve from current theme.'},],diff --git a/packages/core/src/theme/useXDSTheme.test.tsx b/packages/core/src/theme/useXDSTheme.test.tsxindex 5723b52eb2..f01d5415a5 100644--- a/packages/core/src/theme/useXDSTheme.test.tsx+++ b/packages/core/src/theme/useXDSTheme.test.tsx@@ -6,6 +6,7 @@ import React from 'react';import {XDSTheme} from './XDSTheme';import {defineTheme} from './defineTheme';import {useXDSTheme} from './useXDSTheme';+import {resolveXDSThemeTokens} from './tokens';// Mock useMediaQuery — default to light modevi.mock('../hooks/useMediaQuery', () => ({@@ -111,4 +112,14 @@ describe('useXDSTheme', () => {expect(tokens['--spacing-4']).toBe('20px');expect(tokens['--spacing-1']).toBe('4px');});++ it('uses the same token resolution as resolveXDSThemeTokens', () => {+ const {result} = renderHook(() => useXDSTheme(), {+ wrapper: ({children}) => wrapper({children, mode: 'dark'}),+ });++ expect(result.current.tokens).toEqual(+ resolveXDSThemeTokens(testTheme, {mode: 'dark'}),+ );+ });});diff --git a/packages/core/src/theme/useXDSTheme.ts b/packages/core/src/theme/useXDSTheme.tsindex fb2d845804..2fa55eae4e 100644--- a/packages/core/src/theme/useXDSTheme.ts+++ b/packages/core/src/theme/useXDSTheme.ts@@ -9,7 +9,8 @@* @position Theme hook; used by data viz, canvas, and non-CSS consumers** Provides synchronous access to theme token values resolved for the- * current color mode — no DOM reads, no double render.+ * current color mode — no DOM reads, no double render. Token resolution+ * is shared with the server-safe helpers in ./tokens.ts.** SYNC: When modified, update:* - /packages/core/src/theme/index.ts@@ -17,8 +18,8 @@import {createContext, use, useMemo} from 'react';import type {ThemeMode} from './types';-import type {XDSDefinedTheme, XDSTokenValue} from './defineTheme';-import {xdsTokenDefaults} from './defineTheme';+import type {XDSDefinedTheme} from './defineTheme';+import {resolveXDSThemeTokens} from './tokens';import {useMediaQuery} from '../hooks/useMediaQuery';// =============================================================================@@ -82,65 +83,6 @@ export interface UseXDSThemeReturn {tokens: Record<string, string>;}-// =============================================================================-// Helpers-// =============================================================================--/**- * Resolve a single token value for a given mode.- * - [light, dark] tuple → picks the correct side- * - string → if it's a light-dark() CSS function, parse and pick; otherwise pass through- */-function resolveValue(value: XDSTokenValue, mode: 'light' | 'dark'): string {- if (Array.isArray(value)) {- return mode === 'dark' ? value[1] : value[0];- }- // For string values, try to parse light-dark(a, b) from defaults- const match = value.match(/^light-dark\(([^,]+),([^)]+)\)$/);- if (match) {- return mode === 'dark' ? match[2].trim() : match[1].trim();- }- return value;-}--/**- * Build the full resolved token map for a theme + mode.- */-function buildResolvedTokens(- theme: XDSDefinedTheme,- mode: 'light' | 'dark',-): Record<string, string> {- const resolved = buildDefaultTokens(mode);-- // Layer theme overrides on top- // Prefer __inputTokens (preserves tuples) over .tokens (already resolved to light-dark() strings)- if (theme.__inputTokens) {- for (const [key, value] of Object.entries(theme.__inputTokens)) {- if (value !== undefined) {- resolved[key] = resolveValue(value, mode);- }- }- } else {- // Fallback: parse light-dark() strings from .tokens- for (const [key, value] of Object.entries(theme.tokens)) {- resolved[key] = resolveValue(value, mode);- }- }-- return resolved;-}--/**- * Build the resolved token map from defaults only (no theme provider).- */-function buildDefaultTokens(mode: 'light' | 'dark'): Record<string, string> {- const resolved: Record<string, string> = {};- for (const [key, value] of Object.entries(xdsTokenDefaults)) {- resolved[key] = resolveValue(value, mode);- }- return resolved;-}-// =============================================================================// Hook// =============================================================================@@ -153,7 +95,8 @@ function buildDefaultTokens(mode: 'light' | 'dark'): Record<string, string> {* (e.g. Vega, D3, Chart.js) that need concrete values rather than* CSS custom property references.*- * Must be called inside an <XDSTheme> provider.+ * When called outside an <XDSTheme> provider, returns the default theme+ * tokens resolved against the current system color mode.** @example* ```@@ -182,10 +125,7 @@ export function useXDSTheme(): UseXDSThemeReturn {// Build the full resolved map, memoized on theme + effective modeconst tokens = useMemo(- () =>- theme- ? buildResolvedTokens(theme, effectiveMode)- : buildDefaultTokens(effectiveMode),+ () => resolveXDSThemeTokens(theme, {mode: effectiveMode}),[theme, effectiveMode],);diff --git a/scripts/sync-exports.js b/scripts/sync-exports.jsindex b7f8f9eb5a..7e56619eab 100644--- a/scripts/sync-exports.js+++ b/scripts/sync-exports.js@@ -62,6 +62,11 @@ const STATIC_EXPORTS = {types: './src/tailwind-theme.css.d.ts',default: './src/tailwind-theme.css',},+ './theme/tokens': {+ source: './src/theme/tokens.ts',+ types: './dist/theme/tokens.d.ts',+ default: './dist/theme/tokens.js',+ },'./theme/tokens.stylex': {source: './src/theme/tokens.stylex.ts',types: './dist/theme/tokens.stylex.d.ts',