An open source design system that's fully customizable and agent ready
TypeScript
refactor(core): rename theme-token helpers off the XDS name (#3026)
EJ Hammond0f8f57aea52c
diff --git a/.changeset/core-theme-token-fns-astryx.md b/.changeset/core-theme-token-fns-astryx.mdnew file mode 100644index 0000000000..9deb0e877c--- /dev/null+++ b/.changeset/core-theme-token-fns-astryx.md@@ -0,0 +1,13 @@+---+'@astryxdesign/core': patch+---++[breaking] Rename theme-token helpers off the XDS name+@ejhammond++The `@xds/core/theme` token helpers are renamed: `resolveXDSThemeTokens` ->+`resolveThemeTokens`, `resolveXDSThemeToken` -> `resolveThemeToken`,+`xdsTokenVar` -> `tokenVar`, `xdsTokenVars` -> `tokenVars`, and the option types+`ResolveXDSThemeToken(s)Options` -> `ResolveThemeToken(s)Options`. Update imports+from `@xds/core/theme` / `@xds/core/theme/tokens`. Part of removing `xds` naming+from the public API.diff --git a/packages/cli/docs/styling-libraries.doc.mjs b/packages/cli/docs/styling-libraries.doc.mjsindex 8cdca47b46..2d99e6bdad 100644--- a/packages/cli/docs/styling-libraries.doc.mjs+++ b/packages/cli/docs/styling-libraries.doc.mjs@@ -58,7 +58,7 @@ export const docs = {['Token resolver APIs','JavaScript needs token values for charts, canvas, SVG, or config objects',- "`resolveXDSThemeToken(theme, '--color-data-categorical-blue', {mode})`",+ "`resolveThemeToken(theme, '--color-data-categorical-blue', {mode})`",],],},@@ -367,16 +367,16 @@ tokens: {content: [{type: 'prose',- text: 'Use `resolveXDSThemeTokens()` or `resolveXDSThemeToken()` when code outside React needs token values for a known theme and mode. Use `useTheme()` inside client components when the values should come from the nearest Theme and active mode.',+ text: 'Use `resolveThemeTokens()` or `resolveThemeToken()` when code outside React needs token values for a known theme and mode. Use `useTheme()` inside client components when the values should come from the nearest Theme and active mode.',},{type: 'code',lang: 'ts',label: 'Resolve tokens without React context',- code: `import {resolveXDSThemeTokens} from '@astryxdesign/core/theme/tokens';+ code: `import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';import {defaultTheme} from '@astryxdesign/theme-default';-const tokens = resolveXDSThemeTokens(defaultTheme, {mode: 'light'});+const tokens = resolveThemeTokens(defaultTheme, {mode: 'light'});const chartOptions = {textColor: tokens['--color-text-primary'],diff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjsindex 9bcb5462b6..eb357f607d 100644--- a/packages/cli/docs/theme.doc.mjs+++ b/packages/cli/docs/theme.doc.mjs@@ -502,21 +502,21 @@ import './themes/ocean.css';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.',+ text: 'Use `tokenVar()` when a non-StyleX styling library wants a CSS variable reference, and `resolveThemeTokens()` 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 '@astryxdesign/core/theme/tokens';+ code: `import {tokenVar, tokenVars} from '@astryxdesign/core/theme/tokens';const pandaOrEmotionTheme = {colors: {- text: xdsTokenVar('--color-text-primary'),- surface: xdsTokenVars['--color-background-surface'],+ text: tokenVar('--color-text-primary'),+ surface: tokenVars['--color-background-surface'],},spacing: {- 4: xdsTokenVars['--spacing-4'],+ 4: tokenVars['--spacing-4'],},};`,},@@ -524,10 +524,10 @@ const pandaOrEmotionTheme = {type: 'code',lang: 'ts',label: 'Resolve token values without a hook',- code: `import {resolveXDSThemeTokens} from '@astryxdesign/core/theme/tokens';+ code: `import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';import {defaultTheme} from '@astryxdesign/theme-default';-const lightTokens = resolveXDSThemeTokens(defaultTheme, {mode: 'light'});+const lightTokens = resolveThemeTokens(defaultTheme, {mode: 'light'});const chartTheme = {textColor: lightTokens['--color-text-primary'],seriesColor: lightTokens['--color-data-categorical-blue'],@@ -545,7 +545,7 @@ const chartTheme = {content: [{type: 'prose',- text: '`useTheme()` uses the same token resolution as `resolveXDSThemeTokens()`, but reads the nearest Theme 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.',+ text: '`useTheme()` uses the same token resolution as `resolveThemeTokens()`, but reads the nearest Theme 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',diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.tsindex 0139cfea9f..ee376a9aa1 100644--- a/packages/core/src/theme/index.ts+++ b/packages/core/src/theme/index.ts@@ -135,14 +135,14 @@ export type {export {useTheme, ThemeContext} from './useTheme';export type {UseThemeReturn, ThemeContextValue} from './useTheme';export {- resolveXDSThemeToken,- resolveXDSThemeTokens,- xdsTokenVar,- xdsTokenVars,+ resolveThemeToken,+ resolveThemeTokens,+ tokenVar,+ tokenVars,} from './tokens';export type {- ResolveXDSThemeTokenOptions,- ResolveXDSThemeTokensOptions,+ ResolveThemeTokenOptions,+ ResolveThemeTokensOptions,ResolvedThemeMode,} from './tokens';diff --git a/packages/core/src/theme/tokens.test.ts b/packages/core/src/theme/tokens.test.tsindex 0c8ae26b4d..a6ed049f90 100644--- a/packages/core/src/theme/tokens.test.ts+++ b/packages/core/src/theme/tokens.test.ts@@ -3,10 +3,10 @@import {describe, expect, it} from 'vitest';import {defineTheme} from './defineTheme';import {- resolveXDSThemeToken,- resolveXDSThemeTokens,- xdsTokenVar,- xdsTokenVars,+ resolveThemeToken,+ resolveThemeTokens,+ tokenVar,+ tokenVars,} from './tokens';const testTheme = defineTheme({@@ -18,45 +18,45 @@ const testTheme = defineTheme({},});-describe('xdsTokenVar', () => {+describe('tokenVar', () => {it('returns a CSS var() reference for known token names', () => {- expect(xdsTokenVar('--color-text-primary')).toBe(+ expect(tokenVar('--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)');+ expect(tokenVar('--app-custom-token')).toBe('var(--app-custom-token)');});});-describe('xdsTokenVars', () => {+describe('tokenVars', () => {it('contains var() references for known tokens', () => {- expect(xdsTokenVars['--color-text-primary']).toBe(+ expect(tokenVars['--color-text-primary']).toBe('var(--color-text-primary)',);- expect(xdsTokenVars['--spacing-4']).toBe('var(--spacing-4)');+ expect(tokenVars['--spacing-4']).toBe('var(--spacing-4)');});});-describe('resolveXDSThemeTokens', () => {+describe('resolveThemeTokens', () => {it('resolves defaults when no theme is provided', () => {- const tokens = resolveXDSThemeTokens(null, {mode: 'light'});+ const tokens = resolveThemeTokens(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'});+ const light = resolveThemeTokens(testTheme, {mode: 'light'});+ const dark = resolveThemeTokens(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'});+ const light = resolveThemeTokens(testTheme, {mode: 'light'});+ const dark = resolveThemeTokens(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)');@@ -72,29 +72,29 @@ describe('resolveXDSThemeTokens', () => {},} as const;- const light = resolveXDSThemeTokens(builtTheme, {mode: 'light'});- const dark = resolveXDSThemeTokens(builtTheme, {mode: 'dark'});+ const light = resolveThemeTokens(builtTheme, {mode: 'light'});+ const dark = resolveThemeTokens(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'});+ const tokens = resolveThemeTokens(testTheme, {mode: 'light'});expect(tokens['--spacing-4']).toBe('20px');});});-describe('resolveXDSThemeToken', () => {+describe('resolveThemeToken', () => {it('resolves one token', () => {expect(- resolveXDSThemeToken(testTheme, '--color-accent', {mode: 'dark'}),+ resolveThemeToken(testTheme, '--color-accent', {mode: 'dark'}),).toBe('#FF5555');});it('returns fallback for unknown token names', () => {expect(- resolveXDSThemeToken(testTheme, '--missing-token', {+ resolveThemeToken(testTheme, '--missing-token', {mode: 'dark',fallback: 'fallback',}),@@ -103,7 +103,7 @@ describe('resolveXDSThemeToken', () => {it('returns empty string for unknown token names without fallback', () => {expect(- resolveXDSThemeToken(testTheme, '--missing-token', {mode: 'dark'}),+ resolveThemeToken(testTheme, '--missing-token', {mode: 'dark'}),).toBe('');});});diff --git a/packages/core/src/theme/tokens.ts b/packages/core/src/theme/tokens.tsindex 1828d98d88..503875a476 100644--- a/packages/core/src/theme/tokens.ts+++ b/packages/core/src/theme/tokens.ts@@ -26,13 +26,13 @@ import {export type ResolvedThemeMode = 'light' | 'dark';/** Options for resolving all tokens from a theme object. */-export interface ResolveXDSThemeTokensOptions {+export interface ResolveThemeTokensOptions {/** Effective mode to resolve. Pass an explicit value; this helper does not read media queries. */mode: ResolvedThemeMode;}/** Options for resolving one token from a theme object. */-export interface ResolveXDSThemeTokenOptions extends ResolveXDSThemeTokensOptions {+export interface ResolveThemeTokenOptions extends ResolveThemeTokensOptions {/** Value to return when the token name is unknown. Defaults to an empty string. */fallback?: string;}@@ -48,19 +48,19 @@ export interface ResolveXDSThemeTokenOptions extends ResolveXDSThemeTokensOption* ```ts* const theme = {* colors: {- * text: xdsTokenVar('--color-text-primary'),- * surface: xdsTokenVar('--color-background-surface'),+ * text: tokenVar('--color-text-primary'),+ * surface: tokenVar('--color-background-surface'),* },* };* ```*/-export function xdsTokenVar(name: TokenName | (string & {})): string {+export function tokenVar(name: TokenName | (string & {})): string {return `var(${name})`;}/** Flat map of every known XDS token name to its `var(--token-name)` reference. */-export const xdsTokenVars: Record<TokenName, string> = Object.fromEntries(- Object.keys(xdsTokenDefaults).map(name => [name, xdsTokenVar(name)]),+export const tokenVars: Record<TokenName, string> = Object.fromEntries(+ Object.keys(xdsTokenDefaults).map(name => [name, tokenVar(name)]),) as Record<TokenName, string>;/**@@ -155,9 +155,9 @@ function resolveXDSTokenValue(** Pass `theme` as null/undefined to resolve defaults only.*/-export function resolveXDSThemeTokens(+export function resolveThemeTokens(theme: DefinedTheme | null | undefined,- options: ResolveXDSThemeTokensOptions,+ options: ResolveThemeTokensOptions,): Record<string, string> {const {mode} = options;const resolved: Record<string, string> = {};@@ -186,11 +186,11 @@ export function resolveXDSThemeTokens(}/** Resolve one XDS token value for a theme and effective color mode. */-export function resolveXDSThemeToken(+export function resolveThemeToken(theme: DefinedTheme | null | undefined,name: TokenName | (string & {}),- options: ResolveXDSThemeTokenOptions,+ options: ResolveThemeTokenOptions,): string {- const tokens = resolveXDSThemeTokens(theme, options);+ const tokens = resolveThemeTokens(theme, options);return tokens[name] ?? options.fallback ?? '';}diff --git a/packages/core/src/theme/useTheme.doc.mjs b/packages/core/src/theme/useTheme.doc.mjsindex f84a9e4c83..5c673fab90 100644--- a/packages/core/src/theme/useTheme.doc.mjs+++ b/packages/core/src/theme/useTheme.doc.mjs@@ -43,7 +43,7 @@ export const docs = {name: 'tokens',type: 'Record<string, string>',description:- 'All tokens resolved for the current mode, including defaults and theme overrides. Stable until the active theme or mode changes; uses the same resolution logic as resolveXDSThemeTokens(theme, {mode}).',+ 'All tokens resolved for the current mode, including defaults and theme overrides. Stable until the active theme or mode changes; uses the same resolution logic as resolveThemeTokens(theme, {mode}).',},],usage: {@@ -58,7 +58,7 @@ export const docs = {{guidance: true,description:- 'Use resolveXDSThemeTokens(theme, {mode}) for the same token resolution outside React hooks.',+ 'Use resolveThemeTokens(theme, {mode}) for the same token resolution outside React hooks.',},{guidance: true,@@ -96,7 +96,7 @@ export const docsDense = {mode: 'resolved light/dark mode.',token: 'resolve one design token for effective mode.',tokens:- 'all tokens resolved for current mode; stable until theme/mode changes; same resolver as resolveXDSThemeTokens.',+ 'all tokens resolved for current mode; stable until theme/mode changes; same resolver as resolveThemeTokens.',},usage: {description:@@ -109,7 +109,7 @@ export const docsDense = {{guidance: true,description:- 'Use resolveXDSThemeTokens(theme, {mode}) outside React hooks.',+ 'Use resolveThemeTokens(theme, {mode}) outside React hooks.',},{guidance: true,diff --git a/packages/core/src/theme/useTheme.test.tsx b/packages/core/src/theme/useTheme.test.tsxindex 67ecc3c241..9f21d83ac0 100644--- a/packages/core/src/theme/useTheme.test.tsx+++ b/packages/core/src/theme/useTheme.test.tsx@@ -6,7 +6,7 @@ import React from 'react';import {Theme} from './Theme';import {defineTheme} from './defineTheme';import {useTheme} from './useTheme';-import {resolveXDSThemeTokens} from './tokens';+import {resolveThemeTokens} from './tokens';// Mock useMediaQuery — default to light modevi.mock('../hooks/useMediaQuery', () => ({@@ -113,13 +113,13 @@ describe('useTheme', () => {expect(tokens['--spacing-1']).toBe('4px');});- it('uses the same token resolution as resolveXDSThemeTokens', () => {+ it('uses the same token resolution as resolveThemeTokens', () => {const {result} = renderHook(() => useTheme(), {wrapper: ({children}) => wrapper({children, mode: 'dark'}),});expect(result.current.tokens).toEqual(- resolveXDSThemeTokens(testTheme, {mode: 'dark'}),+ resolveThemeTokens(testTheme, {mode: 'dark'}),);});});diff --git a/packages/core/src/theme/useTheme.ts b/packages/core/src/theme/useTheme.tsindex 755ca29442..5daf55ea61 100644--- a/packages/core/src/theme/useTheme.ts+++ b/packages/core/src/theme/useTheme.ts@@ -19,7 +19,7 @@import {createContext, use, useMemo} from 'react';import type {ThemeMode} from './types';import type {DefinedTheme} from './defineTheme';-import {resolveXDSThemeTokens} from './tokens';+import {resolveThemeTokens} from './tokens';import {useMediaQuery} from '../hooks/useMediaQuery';// =============================================================================@@ -125,7 +125,7 @@ export function useTheme(): UseThemeReturn {// Build the full resolved map, memoized on theme + effective modeconst tokens = useMemo(- () => resolveXDSThemeTokens(theme, {mode: effectiveMode}),+ () => resolveThemeTokens(theme, {mode: effectiveMode}),[theme, effectiveMode],);