Skip to content

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.md
new file mode 100644
index 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.mjs
index 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.mjs
index 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.ts
index 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.ts
index 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.ts
index 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.mjs
index 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.tsx
index 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 mode
vi.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.ts
index 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 mode
const tokens = useMemo(
- () => resolveXDSThemeTokens(theme, {mode: effectiveMode}),
+ () => resolveThemeTokens(theme, {mode: effectiveMode}),
[theme, effectiveMode],
);