Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(theme): support partial theme overrides (#318)

Cindy Zhang3953d3741c71
diff --git a/packages/cli/docs/theme.md b/packages/cli/docs/theme.md
index 07aef4c09a..1e16011f74 100644
--- a/packages/cli/docs/theme.md
+++ b/packages/cli/docs/theme.md
@@ -40,54 +40,49 @@ Run `npx xds theme --list` to see themes in your project.
npx xds theme
```
-Interactive wizard that generates a complete `.stylex.ts` theme file with your brand colors.
+Interactive wizard that generates a `.stylex.ts` theme file with your brand colors.
### Manual creation
-A theme is an object with `name`, `styles`, and `raw`:
+A theme is an object with `name` and `styles`. Only override token groups that differ from the defaults — omitted groups automatically use the `defineVars` defaults from `@xds/core`.
```tsx
import * as stylex from '@stylexjs/stylex';
import type {ThemeType as Theme} from '@xds/core/theme';
-import {
- colorVars,
- spacingVars,
- sizeVars,
- radiusVars,
- elevationVars,
- transitionVars,
- typographyVars,
- textSizeVars,
- lineHeightVars,
- fontWeightVars,
-} from '@xds/core/theme/tokens.stylex';
-
-// 1. Define raw values
-const colorRaw = {
+import {colorVars, colorDefaults} from '@xds/core/theme/tokens.stylex';
+
+// 1. Define your color overrides
+const colorOverrides = {
'--color-accent': 'light-dark(#7B61FF, #9B85FF)',
'--color-surface': 'light-dark(#FFFFFF, #1A1A2E)',
// ... all ~60 color tokens (see npx xds docs tokens)
-};
+} as const;
-// 2. Create StyleX theme overrides
+// 2. Create StyleX theme override
const colorTheme = stylex.createTheme(
colorVars,
- colorRaw as unknown as BaseColorRaw,
+ colorOverrides as unknown as typeof colorDefaults,
);
-// 3. Export the theme
+// 3. Export the theme — only include overridden groups
export const myTheme: Theme = {
name: 'my-theme',
- styles: {colors: colorTheme, spacing: spacingTheme /* ... all 10 */},
- raw: {colors: colorRaw, spacing: spacingRaw /* ... all 10 */},
+ styles: {
+ colors: colorTheme,
+ // spacing, radius, etc. omitted — uses defaults
+ },
+ raw: {
+ colors: colorOverrides,
+ // Include raw values for programmatic access (charting libs, theme editors)
+ },
};
```
-The `styles` field uses `stylex.createTheme()` for each token group. The `raw` field has the same values as plain objects for programmatic access.
-
-**Token groups** (all required in both `styles` and `raw`):
+**Token groups** (all optional in `styles`):
colors, spacing, size, radius, elevation, transition, typography, textSize, lineHeight, fontWeight
+Omitted groups use the `defineVars` defaults from `tokens.stylex.ts`.
+
### ⚠️ Static Analysis Constraint
StyleX's Babel plugin requires that **all values passed to `stylex.createTheme()` are inline object literals** — not variable references, spread expressions, or function return values. This is a compile-time constraint.
@@ -111,42 +106,19 @@ const spacingTheme = stylex.createTheme(spacingVars, {
});
```
-### Sharing values across multiple themes
+### Partial overrides
-When creating multiple themes that share token groups (e.g., same spacing, different colors), you **must duplicate the inline values** in each `createTheme()` call. This is required by StyleX's static analysis — there is no way to DRY up `createTheme` arguments.
+You only need to create `stylex.createTheme()` calls for token groups you want to change. For example, if your theme only changes colors and radius:
```tsx
-// ✅ Correct: each theme has its own inline createTheme calls
-// (values can be identical — that's fine, they must just be inline literals)
-
-// --- ocean theme ---
-const oceanSpacingTheme = stylex.createTheme(spacingVars, {
- '--spacing-1': '4px',
- '--spacing-2': '8px',
- // ... same values, written inline
-} as unknown as BaseSpacingRaw);
-
-// --- sunset theme ---
-const sunsetSpacingTheme = stylex.createTheme(spacingVars, {
- '--spacing-1': '4px',
- '--spacing-2': '8px',
- // ... same values, written inline
-} as unknown as BaseSpacingRaw);
-```
-
-The `raw` field (plain objects, not passed to StyleX) _can_ use shared variables:
-
-```tsx
-// ✅ raw values can be shared — they're not processed by StyleX
-const sharedSpacingRaw = {
- '--spacing-1': '4px',
- '--spacing-2': '8px',
-};
-
-export const oceanTheme: Theme = {
- name: 'ocean',
- styles: {spacing: oceanSpacingTheme /* ... */},
- raw: {spacing: sharedSpacingRaw /* ... */}, // ✅ OK — not a createTheme call
+export const myTheme: Theme = {
+ name: 'my-theme',
+ styles: {
+ colors: colorTheme,
+ radius: radiusTheme,
+ // All other groups (spacing, size, elevation, transition,
+ // typography, textSize, lineHeight, fontWeight) use defaults
+ },
};
```
@@ -261,10 +233,7 @@ const cardOverrides = stylex.create({
export const myTheme: Theme = {
name: 'my-theme',
styles: {
- /* ... */
- },
- raw: {
- /* ... */
+ colors: colorTheme,
},
components: {
card: {
diff --git a/packages/cli/src/commands/theme.mjs b/packages/cli/src/commands/theme.mjs
index e92a3b4bd6..e2066bf268 100644
--- a/packages/cli/src/commands/theme.mjs
+++ b/packages/cli/src/commands/theme.mjs
@@ -293,33 +293,16 @@ function generateThemeFile({name, exportName, colors, includeComponentOverrides,
*
* Generated by \`npx xds theme\`.
* Customize the values below, then import in your app.
+ *
+ * Only override token groups you want to change — omitted groups
+ * automatically use the defineVars defaults from @xds/core.
*/
import * as stylex from '@stylexjs/stylex';
import type {ThemeType as Theme} from '@xds/core/theme';
import {
colorVars,
- spacingVars,
- sizeVars,
- radiusVars,
- elevationVars,
- transitionVars,
- typographyVars,
- textSizeVars,
- lineHeightVars,
- fontWeightVars,
-} from '@xds/core/theme/tokens.stylex';
-import type {
- BaseColorRaw,
- BaseSpacingRaw,
- BaseSizeRaw,
- BaseRadiusRaw,
- BaseElevationRaw,
- BaseTransitionRaw,
- BaseTypographyRaw,
- BaseTextSizeRaw,
- BaseLineHeightRaw,
- BaseFontWeightRaw,
+ colorDefaults,
} from '@xds/core/theme/tokens.stylex';
// =============================================================================
@@ -328,112 +311,25 @@ import type {
// Edit these values to change your theme's color palette.
// Use light-dark(lightValue, darkValue) for automatic light/dark support.
-const colorRaw = {
+const colorOverrides = {
${colorEntries}
-};
+} as const;
// =============================================================================
-// Spacing, Size, Radius, Elevation, Transition, Typography
+// createTheme calls
// =============================================================================
-// These use XDS defaults. Override any values you want to customize.
-
-const spacingRaw = {
- '--spacing-0': '0px',
- '--spacing-0-5': '2px',
- '--spacing-1': '4px',
- '--spacing-2': '8px',
- '--spacing-3': '12px',
- '--spacing-4': '16px',
- '--spacing-5': '20px',
- '--spacing-6': '24px',
- '--spacing-7': '28px',
- '--spacing-8': '32px',
- '--spacing-9': '36px',
- '--spacing-10': '40px',
- '--spacing-11': '44px',
- '--spacing-12': '48px',
-};
-
-const sizeRaw = {
- '--size-sm': '28px',
- '--size-md': '32px',
- '--size-lg': '36px',
-};
-
-const radiusRaw = {
- '--radius-rounded': '9999px',
- '--radius-container': '12px',
- '--radius-element': '8px',
- '--radius-content': '4px',
- '--radius-inner': '0px',
-};
-
-const elevationRaw = {
- '--elevation-base': '0px 0px 1px light-dark(rgba(0, 0, 0, 0.1), #111112)',
- '--elevation-thumb': '0 1px 3px light-dark(rgba(0, 0, 0, 0.2), rgba(0, 0, 0, 0.4))',
- '--elevation-dialog': '0px 2px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 8px 24px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.3))',
- '--elevation-hover': '0px 1px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 12px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))',
- '--elevation-menu': '0px 1px 1px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 8px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))',
-};
-
-const transitionRaw = {
- '--transition-fast': '0.15s ease',
- '--transition-normal': '0.2s ease',
-};
-
-const typographyRaw = {
- '--font-body': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
- '--font-code': '"SF Mono", Monaco, Consolas, monospace',
- '--font-heading': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
-};
-
-const textSizeRaw = {
- '--text-4xs': '0.5rem',
- '--text-3xs': '0.625rem',
- '--text-2xs': '0.6875rem',
- '--text-xsm': '0.75rem',
- '--text-sm': '0.8125rem',
- '--text-base': '0.875rem',
- '--text-lg': '1rem',
- '--text-xl': '1.125rem',
- '--text-2xl': '1.25rem',
- '--text-3xl': '1.5rem',
- '--text-4xl': '2rem',
-};
-
-const lineHeightRaw = {
- '--leading-tight': '1.25',
- '--leading-snug': '1.375',
- '--leading-base': '1.4285714285714286',
- '--leading-normal': '1.5',
- '--leading-relaxed': '1.625',
-};
+// Only create themes for token groups you want to override.
+// Omitted groups (spacing, size, radius, elevation, transition, typography,
+// textSize, lineHeight, fontWeight) use the defineVars defaults automatically.
-const fontWeightRaw = {
- '--font-weight-normal': '400',
- '--font-weight-medium': '500',
- '--font-weight-semibold': '600',
- '--font-weight-bold': '700',
-};
+const colorTheme = stylex.createTheme(
+ colorVars,
+ colorOverrides as unknown as typeof colorDefaults,
+);
-// =============================================================================
-// createTheme calls
-// =============================================================================
-// ⚠️ StyleX CONSTRAINT: Each createTheme() call MUST receive an inline object
-// literal. Do NOT extract values into a shared variable and reference it here —
-// StyleX's Babel plugin cannot statically analyze variable references.
-// If you need multiple themes with the same tokens, duplicate the inline values.
-
-const colorTheme = stylex.createTheme(colorVars, colorRaw as unknown as BaseColorRaw);
-const spacingTheme = stylex.createTheme(spacingVars, spacingRaw as unknown as BaseSpacingRaw);
-const sizeTheme = stylex.createTheme(sizeVars, sizeRaw as unknown as BaseSizeRaw);
-const radiusTheme = stylex.createTheme(radiusVars, radiusRaw as unknown as BaseRadiusRaw);
-const elevationTheme = stylex.createTheme(elevationVars, elevationRaw as unknown as BaseElevationRaw);
-const transitionTheme = stylex.createTheme(transitionVars, transitionRaw as unknown as BaseTransitionRaw);
-const typographyTheme = stylex.createTheme(typographyVars, typographyRaw as unknown as BaseTypographyRaw);
-const textSizeTheme = stylex.createTheme(textSizeVars, textSizeRaw as unknown as BaseTextSizeRaw);
-const lineHeightTheme = stylex.createTheme(lineHeightVars, lineHeightRaw as unknown as BaseLineHeightRaw);
-const fontWeightTheme = stylex.createTheme(fontWeightVars, fontWeightRaw as unknown as BaseFontWeightRaw);
+// Uncomment and customize to override other token groups:
+// import { radiusVars, elevationVars, typographyVars, ... } from '@xds/core/theme/tokens.stylex';
+// const radiusTheme = stylex.createTheme(radiusVars, { '--radius-container': '16px', ... });
${componentOverrideSection}
// =============================================================================
// Theme Export
@@ -443,27 +339,11 @@ export const ${exportName}: Theme = {
name: '${name.toLowerCase().replace(/\s+/g, '-')}',
styles: {
colors: colorTheme,
- spacing: spacingTheme,
- size: sizeTheme,
- radius: radiusTheme,
- elevation: elevationTheme,
- transition: transitionTheme,
- typography: typographyTheme,
- textSize: textSizeTheme,
- lineHeight: lineHeightTheme,
- fontWeight: fontWeightTheme,
+ // Add overridden token groups here:
+ // radius: radiusTheme,
},
raw: {
- colors: colorRaw,
- spacing: spacingRaw,
- size: sizeRaw,
- radius: radiusRaw,
- elevation: elevationRaw,
- transition: transitionRaw,
- typography: typographyRaw,
- textSize: textSizeRaw,
- lineHeight: lineHeightRaw,
- fontWeight: fontWeightRaw,
+ colors: colorOverrides,
},
${componentsField}
};
@@ -793,8 +673,9 @@ export function registerTheme(program) {
}
p.note(
- 'Edit the colorRaw object to change colors.\n' +
- 'Edit spacingRaw, radiusRaw, etc. to customize other tokens.\n' +
+ 'Edit the colorOverrides object to change colors.\n' +
+ 'Add createTheme calls for other token groups you want to override.\n' +
+ 'Omitted groups use the defineVars defaults automatically.\n' +
(includeComponentOverrides
? 'Uncomment sections in "Component Style Overrides" to customize components.\n'
: 'Run `npx xds theme` again with component overrides to customize components.\n') +
diff --git a/packages/core/src/theme/README.md b/packages/core/src/theme/README.md
index 3655be2385..46ace94a1d 100644
--- a/packages/core/src/theme/README.md
+++ b/packages/core/src/theme/README.md
@@ -49,13 +49,17 @@ A theme provides:
```ts
interface Theme {
name: string;
- styles: ThemeStyles; // StyleX CSS variable overrides
- raw: ThemeRaw; // Raw CSS values for programmatic access
+ styles: ThemeStyles; // StyleX CSS variable overrides (all fields optional)
components?: ComponentStyles; // Component-level style overrides
icons?: Partial<XDSIconRegistry>; // Icon overrides for XDSIcon semantic names
+ raw?: ThemeRaw; // Raw token values for programmatic access
}
```
+The optional `raw` field provides actual token values (not CSS variable references) for programmatic access — useful for charting libraries, theme editors, or parsing `light-dark()` values.
+
+All fields in `ThemeStyles` are optional — omitted token groups use the `defineVars` defaults from `tokens.stylex.ts`. This enables partial theme overrides (e.g., only override colors and radius).
+
### Icons
Themes can provide icons for XDS's 12 semantic icon names. These are used internally by components (CloseButton, Calendar, inputs, etc.) and can also be used directly via `<XDSIcon icon="close" />`.
@@ -93,8 +97,7 @@ const myTheme: Theme = {
chevronDown: <MyChevronIcon width="1em" height="1em" aria-hidden />,
// ... provide as many or as few as needed
},
- styles: { /* ... */ },
- raw: { /* ... */ },
+ styles: { /* ... only overridden token groups */ },
};
```
diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsx
index 529adcf8b0..4290d09321 100644
--- a/packages/core/src/theme/XDSTheme.tsx
+++ b/packages/core/src/theme/XDSTheme.tsx
@@ -90,6 +90,7 @@ export function XDSTheme({
: wrapperStyles.system;
// Get StyleX props for all theme styles
+ // Optional/undefined groups are skipped gracefully by stylex.props
const stylexProps = stylex.props(
wrapperStyles.base,
colorSchemeStyle,
@@ -100,6 +101,9 @@ export function XDSTheme({
theme.styles.elevation,
theme.styles.transition,
theme.styles.typography,
+ theme.styles.textSize,
+ theme.styles.lineHeight,
+ theme.styles.fontWeight,
);
let content: React.ReactNode = children;
diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.ts
index a598d154d5..954cb772fb 100644
--- a/packages/core/src/theme/index.ts
+++ b/packages/core/src/theme/index.ts
@@ -13,19 +13,21 @@
export {XDSTheme, useXDSTheme, Theme, useTheme} from './XDSTheme';
-// Export tokens for use in custom components
+// Export token defaults and vars for use in custom components and themes
export {
- colorRaw,
- spacingRaw,
- radiusRaw,
- elevationRaw,
- transitionRaw,
- typographyRaw,
- textSizeRaw,
- lineHeightRaw,
- fontWeightRaw,
+ colorDefaults,
+ spacingDefaults,
+ sizeDefaults,
+ radiusDefaults,
+ elevationDefaults,
+ transitionDefaults,
+ typographyDefaults,
+ textSizeDefaults,
+ lineHeightDefaults,
+ fontWeightDefaults,
colorVars,
spacingVars,
+ sizeVars,
radiusVars,
elevationVars,
transitionVars,
@@ -35,10 +37,25 @@ export {
fontWeightVars,
} from './tokens.stylex';
+// Deprecated re-exports — use *Defaults instead
+export {
+ colorRaw,
+ spacingRaw,
+ sizeRaw,
+ radiusRaw,
+ elevationRaw,
+ transitionRaw,
+ typographyRaw,
+ textSizeRaw,
+ lineHeightRaw,
+ fontWeightRaw,
+} from './tokens.stylex';
+
// Export token key types for theme authoring
export type {
ColorVarName,
SpacingVarName,
+ SizeVarName,
RadiusVarName,
ElevationVarName,
TransitionVarName,
@@ -46,21 +63,12 @@ export type {
TextSizeVarName,
LineHeightVarName,
FontWeightVarName,
- BaseColorRaw,
- BaseSpacingRaw,
- BaseRadiusRaw,
- BaseElevationRaw,
- BaseTransitionRaw,
- BaseTypographyRaw,
- BaseTextSizeRaw,
- BaseLineHeightRaw,
- BaseFontWeightRaw,
} from './tokens.stylex';
export type {
Theme as ThemeType,
- ThemeMode,
ThemeRaw,
+ ThemeMode,
ComponentStyles,
ThemeStyles,
HeadingLevel,
diff --git a/packages/core/src/theme/tokens.stylex.ts b/packages/core/src/theme/tokens.stylex.ts
index a7ba88adf5..9bad33473e 100644
--- a/packages/core/src/theme/tokens.stylex.ts
+++ b/packages/core/src/theme/tokens.stylex.ts
@@ -2,7 +2,7 @@
* XDS Design Tokens
*
* Defines all design tokens using StyleX defineVars.
- * - *Raw: Plain objects with default values (can be reused by themes)
+ * - *Defaults: Plain objects with default values (used by defineVars and themes)
* - *Vars: CSS custom properties that themes can override via createTheme
*
* SYNC: When modified, update /packages/agent-tools/docs/tokens.md
@@ -14,7 +14,7 @@ import * as stylex from '@stylexjs/stylex';
// Color Tokens
// =============================================================================
-export const colorRaw = {
+export const colorDefaults = {
// Core semantic
'--color-accent': 'light-dark(#0064E0, #2694FE)',
'--color-accent-deemphasized': 'light-dark(#0082FB33, #0082FB3F)',
@@ -135,13 +135,16 @@ export const colorRaw = {
'--color-yellow-text': 'light-dark(#753F07, #FBCE03)',
} as const;
-export const colorVars = stylex.defineVars(colorRaw);
+/** @deprecated Use colorDefaults */
+export const colorRaw = colorDefaults;
+
+export const colorVars = stylex.defineVars(colorDefaults);
// =============================================================================
// Spacing Tokens
// =============================================================================
-export const spacingRaw = {
+export const spacingDefaults = {
'--spacing-0': '0px',
'--spacing-0-5': '2px',
'--spacing-1': '4px',
@@ -158,25 +161,31 @@ export const spacingRaw = {
'--spacing-12': '48px',
} as const;
-export const spacingVars = stylex.defineVars(spacingRaw);
+/** @deprecated Use spacingDefaults */
+export const spacingRaw = spacingDefaults;
+
+export const spacingVars = stylex.defineVars(spacingDefaults);
// =============================================================================
// Size Tokens
// =============================================================================
-export const sizeRaw = {
+export const sizeDefaults = {
'--size-sm': '28px',
'--size-md': '32px',
'--size-lg': '36px',
} as const;
-export const sizeVars = stylex.defineVars(sizeRaw);
+/** @deprecated Use sizeDefaults */
+export const sizeRaw = sizeDefaults;
+
+export const sizeVars = stylex.defineVars(sizeDefaults);
// =============================================================================
// Radius Tokens
// =============================================================================
-export const radiusRaw = {
+export const radiusDefaults = {
'--radius-rounded': '9999px',
'--radius-container': '12px',
'--radius-element': '8px',
@@ -184,13 +193,16 @@ export const radiusRaw = {
'--radius-inner': '0px',
} as const;
-export const radiusVars = stylex.defineVars(radiusRaw);
+/** @deprecated Use radiusDefaults */
+export const radiusRaw = radiusDefaults;
+
+export const radiusVars = stylex.defineVars(radiusDefaults);
// =============================================================================
// Elevation Tokens
// =============================================================================
-export const elevationRaw = {
+export const elevationDefaults = {
'--elevation-base': '0px 0px 1px light-dark(rgba(0, 0, 0, 0.1), #111112)',
'--elevation-thumb':
'0 1px 3px light-dark(rgba(0, 0, 0, 0.2), rgba(0, 0, 0, 0.4))',
@@ -209,24 +221,30 @@ export const elevationRaw = {
'inset 0px 0px 0px 2px rgba(227, 25, 59, 0.3)',
} as const;
-export const elevationVars = stylex.defineVars(elevationRaw);
+/** @deprecated Use elevationDefaults */
+export const elevationRaw = elevationDefaults;
+
+export const elevationVars = stylex.defineVars(elevationDefaults);
// =============================================================================
// Transition Tokens
// =============================================================================
-export const transitionRaw = {
+export const transitionDefaults = {
'--transition-fast': '0.15s ease',
'--transition-normal': '0.2s ease',
} as const;
-export const transitionVars = stylex.defineVars(transitionRaw);
+/** @deprecated Use transitionDefaults */
+export const transitionRaw = transitionDefaults;
+
+export const transitionVars = stylex.defineVars(transitionDefaults);
// =============================================================================
// Typography Tokens - Font Families
// =============================================================================
-export const typographyRaw = {
+export const typographyDefaults = {
'--font-body':
'-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
'--font-code': '"SF Mono", Monaco, Consolas, monospace',
@@ -234,13 +252,16 @@ export const typographyRaw = {
'-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
} as const;
-export const typographyVars = stylex.defineVars(typographyRaw);
+/** @deprecated Use typographyDefaults */
+export const typographyRaw = typographyDefaults;
+
+export const typographyVars = stylex.defineVars(typographyDefaults);
// =============================================================================
// Typography Tokens - Text Sizes
// =============================================================================
-export const textSizeRaw = {
+export const textSizeDefaults = {
'--text-4xs': '0.5rem', // 8px - citation
'--text-3xs': '0.625rem', // 10px - micro
'--text-2xs': '0.6875rem', // 11px - small micro
@@ -254,13 +275,16 @@ export const textSizeRaw = {
'--text-4xl': '2rem', // 32px - editorial h1, data viz
} as const;
-export const textSizeVars = stylex.defineVars(textSizeRaw);
+/** @deprecated Use textSizeDefaults */
+export const textSizeRaw = textSizeDefaults;
+
+export const textSizeVars = stylex.defineVars(textSizeDefaults);
// =============================================================================
// Typography Tokens - Line Heights
// =============================================================================
-export const lineHeightRaw = {
+export const lineHeightDefaults = {
'--leading-tight': '1.25', // Display text, headings
'--leading-snug': '1.375', // Compact body text, headings
'--leading-base': '1.4285714285714286', // Body text with --text-base (20px line / 14px font)
@@ -268,47 +292,38 @@ export const lineHeightRaw = {
'--leading-relaxed': '1.625', // Editorial body, reading text
} as const;
-export const lineHeightVars = stylex.defineVars(lineHeightRaw);
+/** @deprecated Use lineHeightDefaults */
+export const lineHeightRaw = lineHeightDefaults;
+
+export const lineHeightVars = stylex.defineVars(lineHeightDefaults);
// =============================================================================
// Typography Tokens - Font Weights
// =============================================================================
-export const fontWeightRaw = {
+export const fontWeightDefaults = {
'--font-weight-normal': '400', // body, captions, code
'--font-weight-medium': '500', // subheadlines, data viz
'--font-weight-semibold': '600', // emphasized body, titles
'--font-weight-bold': '700', // strong emphasis, headings
} as const;
-export const fontWeightVars = stylex.defineVars(fontWeightRaw);
+/** @deprecated Use fontWeightDefaults */
+export const fontWeightRaw = fontWeightDefaults;
+
+export const fontWeightVars = stylex.defineVars(fontWeightDefaults);
// =============================================================================
// Token Types
// =============================================================================
-export type ColorVarName = keyof typeof colorRaw;
-export type SpacingVarName = keyof typeof spacingRaw;
-export type SizeVarName = keyof typeof sizeRaw;
-export type RadiusVarName = keyof typeof radiusRaw;
-export type ElevationVarName = keyof typeof elevationRaw;
-export type TransitionVarName = keyof typeof transitionRaw;
-export type TypographyVarName = keyof typeof typographyRaw;
-export type TextSizeVarName = keyof typeof textSizeRaw;
-export type LineHeightVarName = keyof typeof lineHeightRaw;
-export type FontWeightVarName = keyof typeof fontWeightRaw;
-
-// Base raw types for createTheme casting
-// StyleX's createTheme requires exact literal types from defineVars.
-// Theme overrides have different values, so we cast through these types.
-// Type safety is maintained via `as const satisfies Record<*VarName, string>`.
-export type BaseColorRaw = typeof colorRaw;
-export type BaseSpacingRaw = typeof spacingRaw;
-export type BaseSizeRaw = typeof sizeRaw;
-export type BaseRadiusRaw = typeof radiusRaw;
-export type BaseElevationRaw = typeof elevationRaw;
-export type BaseTransitionRaw = typeof transitionRaw;
-export type BaseTypographyRaw = typeof typographyRaw;
-export type BaseTextSizeRaw = typeof textSizeRaw;
-export type BaseLineHeightRaw = typeof lineHeightRaw;
-export type BaseFontWeightRaw = typeof fontWeightRaw;
+export type ColorVarName = keyof typeof colorDefaults;
+export type SpacingVarName = keyof typeof spacingDefaults;
+export type SizeVarName = keyof typeof sizeDefaults;
+export type RadiusVarName = keyof typeof radiusDefaults;
+export type ElevationVarName = keyof typeof elevationDefaults;
+export type TransitionVarName = keyof typeof transitionDefaults;
+export type TypographyVarName = keyof typeof typographyDefaults;
+export type TextSizeVarName = keyof typeof textSizeDefaults;
+export type LineHeightVarName = keyof typeof lineHeightDefaults;
+export type FontWeightVarName = keyof typeof fontWeightDefaults;
diff --git a/packages/core/src/theme/types.ts b/packages/core/src/theme/types.ts
index 49387ba60c..3637058158 100644
--- a/packages/core/src/theme/types.ts
+++ b/packages/core/src/theme/types.ts
@@ -166,56 +166,49 @@ export interface ComponentStyles {
}
/**
- * Raw theme values - plain objects with the actual CSS values
- * Useful for programmatic access (e.g., parsing light-dark() values)
- */
-export interface ThemeRaw {
- /** Raw color values (e.g., 'light-dark(#0064E0, #2694FE)') */
- colors: Record<string, string>;
- /** Raw spacing values (e.g., '8px') */
- spacing: Record<string, string>;
- /** Raw size values (e.g., '32px') */
- size: Record<string, string>;
- /** Raw radius values (e.g., '12px') */
- radius: Record<string, string>;
- /** Raw elevation values (e.g., '0px 2px 4px rgba(0,0,0,0.1)') */
- elevation: Record<string, string>;
- /** Raw transition values (e.g., '0.2s ease') */
- transition: Record<string, string>;
- /** Raw typography values (e.g., font family strings) */
- typography: Record<string, string>;
- /** Raw text size values (e.g., '1rem') */
- textSize: Record<string, string>;
- /** Raw line height values (e.g., '1.5') */
- lineHeight: Record<string, string>;
- /** Raw font weight values (e.g., '400') */
- fontWeight: Record<string, string>;
-}
-
-/**
- * Theme styles - StyleX styles that set CSS variables
+ * Theme styles - StyleX styles that set CSS variables.
+ * All fields are optional — omitted groups use the defineVars defaults
+ * from tokens.stylex.ts, enabling partial theme overrides.
*/
export interface ThemeStyles {
/** Color CSS variables */
- colors: StyleXStyles;
+ colors?: StyleXStyles;
/** Spacing CSS variables */
- spacing: StyleXStyles;
+ spacing?: StyleXStyles;
/** Size CSS variables (component heights: sm, md, lg) */
- size: StyleXStyles;
+ size?: StyleXStyles;
/** Radius CSS variables */
- radius: StyleXStyles;
+ radius?: StyleXStyles;
/** Elevation CSS variables */
- elevation: StyleXStyles;
+ elevation?: StyleXStyles;
/** Transition CSS variables */
- transition: StyleXStyles;
+ transition?: StyleXStyles;
/** Typography (font family) CSS variables */
- typography: StyleXStyles;
+ typography?: StyleXStyles;
/** Text size CSS variables */
- textSize: StyleXStyles;
+ textSize?: StyleXStyles;
/** Line height CSS variables */
- lineHeight: StyleXStyles;
+ lineHeight?: StyleXStyles;
/** Font weight CSS variables */
- fontWeight: StyleXStyles;
+ fontWeight?: StyleXStyles;
+}
+
+/**
+ * Raw token values for programmatic access.
+ * Useful for charting libraries, theme editors, or parsing light-dark() values.
+ * All fields are optional — partial themes only include overridden groups.
+ */
+export interface ThemeRaw {
+ colors?: Record<string, string>;
+ spacing?: Record<string, string>;
+ size?: Record<string, string>;
+ radius?: Record<string, string>;
+ elevation?: Record<string, string>;
+ transition?: Record<string, string>;
+ typography?: Record<string, string>;
+ textSize?: Record<string, string>;
+ lineHeight?: Record<string, string>;
+ fontWeight?: Record<string, string>;
}
/**
@@ -226,10 +219,10 @@ export interface Theme {
name: string;
/** StyleX styles containing CSS variable definitions */
styles: ThemeStyles;
- /** Raw CSS values for programmatic access */
- raw: ThemeRaw;
/** Component-specific style overrides (optional) */
components?: ComponentStyles;
/** Optional icon registry for overriding built-in fallback icons */
icons?: Partial<XDSIconRegistry>;
+ /** Raw token values for programmatic access (optional) */
+ raw?: ThemeRaw;
}
diff --git a/packages/themes/default/src/defaultTheme.stylex.ts b/packages/themes/default/src/defaultTheme.stylex.ts
index 4faadd1a7f..02f0e2b5b2 100644
--- a/packages/themes/default/src/defaultTheme.stylex.ts
+++ b/packages/themes/default/src/defaultTheme.stylex.ts
@@ -1,19 +1,30 @@
/**
* XDS Default Theme
*
- * A complete theme template that can be copied and customized.
+ * The reference theme — provides all 10 token groups explicitly.
* Uses CSS light-dark() for automatic light/dark mode switching.
*
* To create a custom theme:
* 1. Copy this file
* 2. Rename it (e.g., myBrandTheme.stylex.ts)
- * 3. Update the values with your brand colors/spacing
- * 4. Export from index.ts
+ * 3. Update only the values you want to change
+ * 4. Remove token groups you don't override (they'll use defineVars defaults)
+ * 5. Export from index.ts
*/
import * as stylex from '@stylexjs/stylex';
import type {ThemeType as Theme} from '@xds/core/theme';
import {
+ colorDefaults,
+ spacingDefaults,
+ sizeDefaults,
+ radiusDefaults,
+ elevationDefaults,
+ transitionDefaults,
+ typographyDefaults,
+ textSizeDefaults,
+ lineHeightDefaults,
+ fontWeightDefaults,
colorVars,
spacingVars,
sizeVars,
@@ -25,302 +36,33 @@ import {
lineHeightVars,
fontWeightVars,
} from '@xds/core/theme/tokens.stylex';
-import type {
- ColorVarName,
- SpacingVarName,
- SizeVarName,
- RadiusVarName,
- ElevationVarName,
- TransitionVarName,
- TypographyVarName,
- TextSizeVarName,
- LineHeightVarName,
- FontWeightVarName,
- BaseColorRaw,
- BaseSpacingRaw,
- BaseSizeRaw,
- BaseRadiusRaw,
- BaseElevationRaw,
- BaseTransitionRaw,
- BaseTypographyRaw,
- BaseTextSizeRaw,
- BaseLineHeightRaw,
- BaseFontWeightRaw,
-} from '@xds/core/theme/tokens.stylex';
import {defaultIconRegistry} from './icons';
-// =============================================================================
-// Raw Theme Values
-// =============================================================================
-// Define raw values as plain objects first, then use in createTheme
-// This allows programmatic access to values (e.g., parsing light-dark())
-
-const colorRaw = {
- // Core semantic
- '--color-accent': 'light-dark(#0064E0, #2694FE)',
- '--color-accent-deemphasized': 'light-dark(#0082FB33, #0082FB3F)',
- '--color-accent-text': 'light-dark(#0143B5, #4BA9FE)',
- '--color-surface': 'light-dark(#FFFFFF, #1F1F22)',
- '--color-wash': 'light-dark(#F1F4F7, #111112)',
- '--color-overlay': 'light-dark(#01122866, #11111299)',
- '--color-hover-overlay': 'light-dark(#0536590C, #FFFFFF0C)',
- '--color-pressed-overlay': 'light-dark(#05365919, #FFFFFF19)',
- '--color-focus-outline': 'light-dark(#0171E3, #2694FE)',
- '--color-focus-outline-error': 'light-dark(#E3193B, #F5394F)',
- '--color-focus-outline-success': 'light-dark(#0D8626, #0D8626)',
- '--color-focus-outline-warning': 'light-dark(#F2C00B, #E9AF08)',
- '--color-deemphasized': 'light-dark(#0536590C, #1111127F)',
-
- // Text
- '--color-text-primary': 'light-dark(#0A1317, #DFE2E5)',
- '--color-text-secondary': 'light-dark(#4E606F, #AAAFB5)',
- '--color-text-disabled': 'light-dark(#A4B0BC, #6F747C)',
- '--color-text-link': 'light-dark(#0064E0, #3E9EFB)',
- '--color-text-placeholder': 'light-dark(#4E606F, #AAAFB5)',
- '--color-text-on-media': 'light-dark(#FFFFFF, #FFFFFF)',
-
- // Icon
- '--color-icon-primary': 'light-dark(#0A1317, #DFE2E5)',
- '--color-icon-secondary': 'light-dark(#4E606F, #AAAFB5)',
- '--color-icon-tertiary': 'light-dark(#748695, #8C939B)',
- '--color-icon-disabled': 'light-dark(#A4B0BC, #6F747C)',
- '--color-icon-on-media': 'light-dark(#FFFFFF, #FFFFFF)',
-
- // Surface variants
- '--color-card': 'light-dark(#FFFFFF, #1F1F22)',
- '--color-popover': 'light-dark(#FFFFFF, #28292C)',
- '--color-navbar': 'light-dark(#FFFFFF, #1F1F22)',
-
- // Status/Sentiment
- '--color-positive': 'light-dark(#0D8626, #0D8626)',
- '--color-positive-deemphasized': 'light-dark(#0B991F33, #0B991F3F)',
- '--color-negative': 'light-dark(#E3193B, #F5394F)',
- '--color-negative-deemphasized': 'light-dark(#E3193B33, #F5394F3F)',
- '--color-warning': 'light-dark(#E9AF08, #F2C00B)',
- '--color-warning-deemphasized': 'light-dark(#E2A40033, #E2A4003F)',
- '--color-educational': 'light-dark(#5B08D8, #6B1EFD)',
- '--color-educational-deemphasized': 'light-dark(#7952FF33, #5B08D83F)',
-
- // Divider
- '--color-divider': 'light-dark(#05365919, #F2F4F619)',
- '--color-divider-high-contrast': 'light-dark(#647685, #6F747C)',
- '--color-divider-emphasized': 'light-dark(#CCD3DB, #494D53)',
-
- // Disabled/Effects
- '--color-disabled-overlay': 'light-dark(#FFFFFF7F, #1F1F227F)',
- '--color-glimmer': 'light-dark(#CCD3DB, #5A5E66)',
- '--color-glimmer-high-contrast': 'light-dark(#A4B0BC, #8C939B)',
- '--color-shadow-elevation':
- 'light-dark(rgba(5, 54, 89, 0.1), rgba(0, 0, 0, 0.3))',
- // Hover tint: black in light mode, white in dark mode - used with color-mix for hover states
- '--color-hover-tint': 'light-dark(black, white)',
-
- // Literal color sets - Blue
- '--color-blue-background': 'light-dark(#0171E333, #0171E333)',
- '--color-blue-border': 'light-dark(#0171E3, #4BA9FE)',
- '--color-blue-icon': 'light-dark(#0064E0, #2694FE)',
- '--color-blue-text': 'light-dark(#042F97, #AFD7FF)',
-
- // Cyan
- '--color-cyan-background': 'light-dark(#00BCD433, #00BCD433)',
- '--color-cyan-border': 'light-dark(#00BCD4, #4DD0E1)',
- '--color-cyan-icon': 'light-dark(#00ACC1, #26C6DA)',
- '--color-cyan-text': 'light-dark(#006064, #B2EBF2)',
-
- // Gray
- '--color-gray-background': 'light-dark(#0A131733, #666A724C)',
- '--color-gray-border': 'light-dark(#647685, #8C939B)',
- '--color-gray-icon': 'light-dark(#4E606F, #AAAFB5)',
- '--color-gray-text': 'light-dark(#0A1317, #E7EAED)',
-
- // Green
- '--color-green-background': 'light-dark(#24BB5E33, #24BB5E33)',
- '--color-green-border': 'light-dark(#24BB5E, #4CD964)',
- '--color-green-icon': 'light-dark(#0D8626, #26A756)',
- '--color-green-text': 'light-dark(#09441F, #A5F690)',
-
- // Orange
- '--color-orange-background': 'light-dark(#F2790233, #F2790233)',
- '--color-orange-border': 'light-dark(#F27902, #FFA040)',
- '--color-orange-icon': 'light-dark(#E9690B, #FB8C00)',
- '--color-orange-text': 'light-dark(#6B2203, #FDB876)',
-
- // Pink
- '--color-pink-background': 'light-dark(#E91E6333, #E91E6333)',
- '--color-pink-border': 'light-dark(#E91E63, #F48FB1)',
- '--color-pink-icon': 'light-dark(#C2185B, #EC407A)',
- '--color-pink-text': 'light-dark(#880E4F, #F8BBD0)',
-
- // Purple
- '--color-purple-background': 'light-dark(#7952FF33, #7952FF33)',
- '--color-purple-border': 'light-dark(#7952FF, #9575CD)',
- '--color-purple-icon': 'light-dark(#5B08D8, #7952FF)',
- '--color-purple-text': 'light-dark(#3E0697, #B3B0FE)',
-
- // Red
- '--color-red-background': 'light-dark(#E3193B33, #E3193B33)',
- '--color-red-border': 'light-dark(#E3193B, #F5394F)',
- '--color-red-icon': 'light-dark(#D31130, #E3193B)',
- '--color-red-text': 'light-dark(#7B0210, #FFB2B8)',
-
- // Teal
- '--color-teal-background': 'light-dark(#0DB7AF33, #0DB7AF33)',
- '--color-teal-border': 'light-dark(#0DB7AF, #4DB6AC)',
- '--color-teal-icon': 'light-dark(#009688, #26A69A)',
- '--color-teal-text': 'light-dark(#083943, #40DCCD)',
-
- // Yellow
- '--color-yellow-background': 'light-dark(#FFEB3B33, #FFEB3B33)',
- '--color-yellow-border': 'light-dark(#FFEB3B, #FFF176)',
- '--color-yellow-icon': 'light-dark(#FBC02D, #FFEE58)',
- '--color-yellow-text': 'light-dark(#753F07, #FBCE03)',
-} as const satisfies Record<ColorVarName, string>;
-
-const spacingRaw = {
- '--spacing-0': '0px',
- '--spacing-0-5': '2px',
- '--spacing-1': '4px',
- '--spacing-2': '8px',
- '--spacing-3': '12px',
- '--spacing-4': '16px',
- '--spacing-5': '20px',
- '--spacing-6': '24px',
- '--spacing-7': '28px',
- '--spacing-8': '32px',
- '--spacing-9': '36px',
- '--spacing-10': '40px',
- '--spacing-11': '44px',
- '--spacing-12': '48px',
-} as const satisfies Record<SpacingVarName, string>;
-
-const sizeRaw = {
- '--size-sm': '28px',
- '--size-md': '32px',
- '--size-lg': '36px',
-} as const satisfies Record<SizeVarName, string>;
-
-const radiusRaw = {
- '--radius-rounded': '9999px',
- '--radius-container': '12px',
- '--radius-element': '8px',
- '--radius-content': '4px',
- '--radius-inner': '0px',
-} as const satisfies Record<RadiusVarName, string>;
-
-const elevationRaw = {
- '--elevation-base': '0px 0px 1px light-dark(rgba(0, 0, 0, 0.1), #111112)',
- '--elevation-thumb':
- '0 1px 3px light-dark(rgba(0, 0, 0, 0.2), rgba(0, 0, 0, 0.4))',
- '--elevation-dialog':
- '0px 2px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 8px 24px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.3))',
- '--elevation-hover':
- '0px 1px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 12px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))',
- '--elevation-menu':
- '0px 1px 1px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 8px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))',
- '--elevation-input-hover': 'inset 0px 0px 0px 2px rgba(1, 113, 227, 0.3)',
- '--elevation-input-hover-success':
- 'inset 0px 0px 0px 2px rgba(38, 167, 86, 0.3)',
- '--elevation-input-hover-warning':
- 'inset 0px 0px 0px 2px rgba(226, 164, 0, 0.3)',
- '--elevation-input-hover-error':
- 'inset 0px 0px 0px 2px rgba(227, 25, 59, 0.3)',
-} as const satisfies Record<ElevationVarName, string>;
-
-const transitionRaw = {
- '--transition-fast': '0.15s ease',
- '--transition-normal': '0.2s ease',
-} as const satisfies Record<TransitionVarName, string>;
-
-const typographyRaw = {
- '--font-body':
- '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
- '--font-code': '"SF Mono", Monaco, Consolas, monospace',
- '--font-heading':
- '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
-} as const satisfies Record<TypographyVarName, string>;
-
-const textSizeRaw = {
- '--text-4xs': '0.5rem', // 8px - citation
- '--text-3xs': '0.625rem', // 10px - micro
- '--text-2xs': '0.6875rem', // 11px - small micro
- '--text-xsm': '0.75rem', // 12px - supporting, badge
- '--text-sm': '0.8125rem', // 13px - secondary text
- '--text-base': '0.875rem', // 14px - body text (XDS default)
- '--text-lg': '1rem', // 16px - large body
- '--text-xl': '1.125rem', // 18px - h2
- '--text-2xl': '1.25rem', // 20px - h1
- '--text-3xl': '1.5rem', // 24px - editorial h2
- '--text-4xl': '2rem', // 32px - editorial h1, data viz
-} as const satisfies Record<TextSizeVarName, string>;
-
-const lineHeightRaw = {
- '--leading-tight': '1.25', // Display text, headings
- '--leading-snug': '1.375', // Compact body text, headings
- '--leading-base': '1.4285714285714286', // Body text with --text-base (20px line / 14px font)
- '--leading-normal': '1.5', // Body text, large body
- '--leading-relaxed': '1.625', // Editorial body, reading text
-} as const satisfies Record<LineHeightVarName, string>;
-
-const fontWeightRaw = {
- '--font-weight-normal': '400', // body, captions, code
- '--font-weight-medium': '500', // subheadlines, data viz
- '--font-weight-semibold': '600', // emphasized body, titles
- '--font-weight-bold': '700', // strong emphasis, headings
-} as const satisfies Record<FontWeightVarName, string>;
-
// =============================================================================
// Theme Overrides using createTheme
// =============================================================================
+// The default theme's values are identical to the defineVars defaults.
+// We still create explicit themes so the default is a complete reference.
-const colorTheme = stylex.createTheme(
- colorVars,
- colorRaw as unknown as BaseColorRaw,
-);
+const colorTheme = stylex.createTheme(colorVars, colorDefaults);
-const spacingTheme = stylex.createTheme(
- spacingVars,
- spacingRaw as unknown as BaseSpacingRaw,
-);
+const spacingTheme = stylex.createTheme(spacingVars, spacingDefaults);
-const sizeTheme = stylex.createTheme(
- sizeVars,
- sizeRaw as unknown as BaseSizeRaw,
-);
+const sizeTheme = stylex.createTheme(sizeVars, sizeDefaults);
-const radiusTheme = stylex.createTheme(
- radiusVars,
- radiusRaw as unknown as BaseRadiusRaw,
-);
+const radiusTheme = stylex.createTheme(radiusVars, radiusDefaults);
-const elevationTheme = stylex.createTheme(
- elevationVars,
- elevationRaw as unknown as BaseElevationRaw,
-);
+const elevationTheme = stylex.createTheme(elevationVars, elevationDefaults);
-const transitionTheme = stylex.createTheme(
- transitionVars,
- transitionRaw as unknown as BaseTransitionRaw,
-);
+const transitionTheme = stylex.createTheme(transitionVars, transitionDefaults);
-const typographyTheme = stylex.createTheme(
- typographyVars,
- typographyRaw as unknown as BaseTypographyRaw,
-);
+const typographyTheme = stylex.createTheme(typographyVars, typographyDefaults);
-const textSizeTheme = stylex.createTheme(
- textSizeVars,
- textSizeRaw as unknown as BaseTextSizeRaw,
-);
+const textSizeTheme = stylex.createTheme(textSizeVars, textSizeDefaults);
-const lineHeightTheme = stylex.createTheme(
- lineHeightVars,
- lineHeightRaw as unknown as BaseLineHeightRaw,
-);
+const lineHeightTheme = stylex.createTheme(lineHeightVars, lineHeightDefaults);
-const fontWeightTheme = stylex.createTheme(
- fontWeightVars,
- fontWeightRaw as unknown as BaseFontWeightRaw,
-);
+const fontWeightTheme = stylex.createTheme(fontWeightVars, fontWeightDefaults);
// =============================================================================
// Component Style Overrides
@@ -618,16 +360,16 @@ export const defaultTheme: Theme = {
fontWeight: fontWeightTheme,
},
raw: {
- colors: colorRaw,
- spacing: spacingRaw,
- size: sizeRaw,
- radius: radiusRaw,
- elevation: elevationRaw,
- transition: transitionRaw,
- typography: typographyRaw,
- textSize: textSizeRaw,
- lineHeight: lineHeightRaw,
- fontWeight: fontWeightRaw,
+ colors: colorDefaults,
+ spacing: spacingDefaults,
+ size: sizeDefaults,
+ radius: radiusDefaults,
+ elevation: elevationDefaults,
+ transition: transitionDefaults,
+ typography: typographyDefaults,
+ textSize: textSizeDefaults,
+ lineHeight: lineHeightDefaults,
+ fontWeight: fontWeightDefaults,
},
// Component style overrides — typed loosely here because ComponentStyles
// is augmented by individual components via `declare module`. The theme
diff --git a/packages/themes/neutral/src/neutralTheme.stylex.ts b/packages/themes/neutral/src/neutralTheme.stylex.ts
index cdfd42087e..7916ed4284 100644
--- a/packages/themes/neutral/src/neutralTheme.stylex.ts
+++ b/packages/themes/neutral/src/neutralTheme.stylex.ts
@@ -4,60 +4,35 @@
* A grayscale theme with neutral colors and modern aesthetics.
* Uses oklch color space for perceptually uniform colors.
*
- * Inspired by shadcn/ui's default color scheme.
- *
- * To create a custom theme:
- * 1. Copy this file
- * 2. Rename it (e.g., myBrandTheme.stylex.ts)
- * 3. Update the color values with your brand colors
- * 4. Export from index.ts
+ * Only overrides token groups that differ from the defaults:
+ * colors, radius, elevation, and typography.
+ * Spacing, size, textSize, lineHeight, fontWeight, and transition
+ * use the defineVars defaults automatically.
*/
import * as stylex from '@stylexjs/stylex';
import type {ThemeType as Theme} from '@xds/core/theme';
import {
colorVars,
- spacingVars,
- sizeVars,
radiusVars,
elevationVars,
- transitionVars,
typographyVars,
textSizeVars,
lineHeightVars,
fontWeightVars,
-} from '@xds/core/theme/tokens.stylex';
-import type {
- ColorVarName,
- SpacingVarName,
- SizeVarName,
- RadiusVarName,
- ElevationVarName,
- TransitionVarName,
- TypographyVarName,
- TextSizeVarName,
- LineHeightVarName,
- FontWeightVarName,
- BaseColorRaw,
- BaseSpacingRaw,
- BaseSizeRaw,
- BaseRadiusRaw,
- BaseElevationRaw,
- BaseTransitionRaw,
- BaseTypographyRaw,
- BaseTextSizeRaw,
- BaseLineHeightRaw,
- BaseFontWeightRaw,
+ spacingVars,
+ colorDefaults,
+ radiusDefaults,
+ elevationDefaults,
+ typographyDefaults,
} from '@xds/core/theme/tokens.stylex';
import {neutralIconRegistry} from './icons';
// =============================================================================
-// Raw Theme Values
+// Theme Overrides — only token groups that differ from defaults
// =============================================================================
-// Define raw values as plain objects first, then use in createTheme
-// This allows programmatic access to values (e.g., parsing light-dark())
-const colorRaw = {
+const colorOverrides = {
// Core semantic - neutral grayscale palette
'--color-accent': 'light-dark(oklch(0.205 0 0), oklch(0.922 0 0))',
'--color-accent-deemphasized':
@@ -126,7 +101,6 @@ const colorRaw = {
'light-dark(oklch(0.85 0 0), oklch(0.439 0 0))',
'--color-shadow-elevation':
'light-dark(oklch(0 0 0 / 10%), oklch(0 0 0 / 30%))',
- // Hover tint: black in light mode, white in dark mode - used with color-mix for hover states
'--color-hover-tint': 'light-dark(black, white)',
// Literal color sets - Blue
@@ -216,40 +190,17 @@ const colorRaw = {
'--color-yellow-icon':
'light-dark(oklch(0.828 0.189 84.429), oklch(0.769 0.188 70.08))',
'--color-yellow-text': 'light-dark(oklch(0.6 0.15 84), oklch(0.9 0.15 70))',
-} as const satisfies Record<ColorVarName, string>;
-
-const spacingRaw = {
- '--spacing-0': '0px',
- '--spacing-0-5': '2px',
- '--spacing-1': '4px',
- '--spacing-2': '8px',
- '--spacing-3': '12px',
- '--spacing-4': '16px',
- '--spacing-5': '20px',
- '--spacing-6': '24px',
- '--spacing-7': '28px',
- '--spacing-8': '32px',
- '--spacing-9': '36px',
- '--spacing-10': '40px',
- '--spacing-11': '44px',
- '--spacing-12': '48px',
-} as const satisfies Record<SpacingVarName, string>;
-
-const sizeRaw = {
- '--size-sm': '28px',
- '--size-md': '32px',
- '--size-lg': '36px',
-} as const satisfies Record<SizeVarName, string>;
-
-const radiusRaw = {
+} as const;
+
+const radiusOverrides = {
'--radius-rounded': '9999px',
'--radius-container': '0.75rem',
'--radius-element': '0.625rem',
'--radius-content': '0.375rem',
'--radius-inner': '0.25rem',
-} as const satisfies Record<RadiusVarName, string>;
+} as const;
-const elevationRaw = {
+const elevationOverrides = {
'--elevation-base':
'0 1px 2px light-dark(oklch(0 0 0 / 5%), oklch(0 0 0 / 20%))',
'--elevation-thumb':
@@ -267,117 +218,48 @@ const elevationRaw = {
'inset 0px 0px 0px 2px rgba(226, 164, 0, 0.3)',
'--elevation-input-hover-error':
'inset 0px 0px 0px 2px rgba(227, 25, 59, 0.3)',
-} as const satisfies Record<ElevationVarName, string>;
-
-const transitionRaw = {
- '--transition-fast': '0.15s ease',
- '--transition-normal': '0.2s ease',
-} as const satisfies Record<TransitionVarName, string>;
+} as const;
-const typographyRaw = {
+const typographyOverrides = {
'--font-body':
'Geist, "Geist Fallback", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
'--font-code': '"Geist Mono", "SF Mono", Monaco, Consolas, monospace',
'--font-heading':
'Geist, "Geist Fallback", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
-} as const satisfies Record<TypographyVarName, string>;
-
-const textSizeRaw = {
- '--text-4xs': '0.5rem', // 8px - citation
- '--text-3xs': '0.625rem', // 10px - micro
- '--text-2xs': '0.6875rem', // 11px - small micro
- '--text-xsm': '0.75rem', // 12px - supporting, badge
- '--text-sm': '0.8125rem', // 13px - secondary text
- '--text-base': '0.875rem', // 14px - body text (XDS default)
- '--text-lg': '1rem', // 16px - large body
- '--text-xl': '1.125rem', // 18px - h2
- '--text-2xl': '1.25rem', // 20px - h1
- '--text-3xl': '1.5rem', // 24px - editorial h2
- '--text-4xl': '2rem', // 32px - editorial h1, data viz
-} as const satisfies Record<TextSizeVarName, string>;
-
-const lineHeightRaw = {
- '--leading-tight': '1.25', // Display text, headings
- '--leading-snug': '1.375', // Compact body text, headings
- '--leading-base': '1.4285714285714286', // Body text with --text-base (20px line / 14px font)
- '--leading-normal': '1.5', // Body text, large body
- '--leading-relaxed': '1.625', // Editorial body, reading text
-} as const satisfies Record<LineHeightVarName, string>;
-
-const fontWeightRaw = {
- '--font-weight-normal': '400', // body, captions, code
- '--font-weight-medium': '500', // subheadlines, data viz
- '--font-weight-semibold': '600', // emphasized body, titles
- '--font-weight-bold': '700', // strong emphasis, headings
-} as const satisfies Record<FontWeightVarName, string>;
+} as const;
// =============================================================================
-// Theme Overrides using createTheme
+// createTheme calls — only for overridden token groups
// =============================================================================
const colorTheme = stylex.createTheme(
colorVars,
- colorRaw as unknown as BaseColorRaw,
-);
-
-const spacingTheme = stylex.createTheme(
- spacingVars,
- spacingRaw as unknown as BaseSpacingRaw,
-);
-
-const sizeTheme = stylex.createTheme(
- sizeVars,
- sizeRaw as unknown as BaseSizeRaw,
+ colorOverrides as unknown as typeof colorDefaults,
);
const radiusTheme = stylex.createTheme(
radiusVars,
- radiusRaw as unknown as BaseRadiusRaw,
+ radiusOverrides as unknown as typeof radiusDefaults,
);
const elevationTheme = stylex.createTheme(
elevationVars,
- elevationRaw as unknown as BaseElevationRaw,
-);
-
-const transitionTheme = stylex.createTheme(
- transitionVars,
- transitionRaw as unknown as BaseTransitionRaw,
+ elevationOverrides as unknown as typeof elevationDefaults,
);
const typographyTheme = stylex.createTheme(
typographyVars,
- typographyRaw as unknown as BaseTypographyRaw,
-);
-
-const textSizeTheme = stylex.createTheme(
- textSizeVars,
- textSizeRaw as unknown as BaseTextSizeRaw,
-);
-
-const lineHeightTheme = stylex.createTheme(
- lineHeightVars,
- lineHeightRaw as unknown as BaseLineHeightRaw,
-);
-
-const fontWeightTheme = stylex.createTheme(
- fontWeightVars,
- fontWeightRaw as unknown as BaseFontWeightRaw,
+ typographyOverrides as unknown as typeof typographyDefaults,
);
// =============================================================================
// Component Style Overrides
// =============================================================================
-// Theme-specific component customizations using stylex.create()
-// These styles are applied on top of default component variants
const buttonVariants = stylex.create({
- // Primary button text needs to contrast with accent color
- // In dark mode, accent is light so text should be dark
primary: {
color: 'light-dark(white, oklch(0.145 0 0))',
},
- // Add border to secondary button for shadcn-style appearance
secondary: {
borderWidth: '1px',
borderStyle: 'solid',
@@ -386,7 +268,6 @@ const buttonVariants = stylex.create({
});
const cardStyles = stylex.create({
- // Override card default padding to 12px for tighter layout
content: {
'--layout-padding-inner-x': spacingVars['--spacing-3'],
'--layout-padding-inner-y': spacingVars['--spacing-3'],
@@ -396,7 +277,6 @@ const cardStyles = stylex.create({
});
const sectionStyles = stylex.create({
- // Override section default padding to 12px for tighter layout
content: {
'--layout-padding-inner-x': spacingVars['--spacing-3'],
'--layout-padding-inner-y': spacingVars['--spacing-3'],
@@ -405,161 +285,146 @@ const sectionStyles = stylex.create({
},
});
-/**
- * Semantic heading styles (h1-h6) - default variant
- * Uses XDS dense scale for internal tools
- */
const headingStyles = stylex.create({
h1: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-2xl'], // 20px
+ fontSize: textSizeVars['--text-2xl'],
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: 1.2, // 24px
+ lineHeight: 1.2,
color: colorVars['--color-text-primary'],
margin: 0,
},
h2: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-xl'], // 18px
+ fontSize: textSizeVars['--text-xl'],
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: 1.3333333333333333, // 24px
+ lineHeight: 1.3333333333333333,
color: colorVars['--color-text-primary'],
margin: 0,
},
h3: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-lg'], // 16px
+ fontSize: textSizeVars['--text-lg'],
fontWeight: fontWeightVars['--font-weight-bold'],
- lineHeight: 1.25, // 20px
+ lineHeight: 1.25,
color: colorVars['--color-text-primary'],
margin: 0,
},
h4: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-base'], // 14px
+ fontSize: textSizeVars['--text-base'],
fontWeight: fontWeightVars['--font-weight-bold'],
- lineHeight: lineHeightVars['--leading-base'], // 20px
+ lineHeight: lineHeightVars['--leading-base'],
color: colorVars['--color-text-primary'],
margin: 0,
},
h5: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-base'], // 14px (same as h4)
+ fontSize: textSizeVars['--text-base'],
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: lineHeightVars['--leading-base'], // 20px
+ lineHeight: lineHeightVars['--leading-base'],
color: colorVars['--color-text-primary'],
margin: 0,
},
h6: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-xsm'], // 12px
+ fontSize: textSizeVars['--text-xsm'],
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: 1.3333333333333333, // 16px
+ lineHeight: 1.3333333333333333,
color: colorVars['--color-text-primary'],
margin: 0,
},
});
-/**
- * Editorial heading styles (h1-h4) - larger scale for content-heavy pages
- */
const headingEditorialStyles = stylex.create({
h1: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-4xl'], // 32px
+ fontSize: textSizeVars['--text-4xl'],
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: 1.5, // 48px
+ lineHeight: 1.5,
color: colorVars['--color-text-primary'],
margin: 0,
},
h2: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-3xl'], // 24px
+ fontSize: textSizeVars['--text-3xl'],
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: 1.3333333333333333, // 32px
+ lineHeight: 1.3333333333333333,
color: colorVars['--color-text-primary'],
margin: 0,
},
h3: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-2xl'], // 20px
+ fontSize: textSizeVars['--text-2xl'],
fontWeight: fontWeightVars['--font-weight-bold'],
- lineHeight: 1.4, // 28px
+ lineHeight: 1.4,
color: colorVars['--color-text-primary'],
margin: 0,
},
h4: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-lg'], // 16px
+ fontSize: textSizeVars['--text-lg'],
fontWeight: fontWeightVars['--font-weight-bold'],
- lineHeight: 1.5, // 24px
+ lineHeight: 1.5,
color: colorVars['--color-text-primary'],
margin: 0,
},
h5: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-base'], // 14px
+ fontSize: textSizeVars['--text-base'],
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: lineHeightVars['--leading-base'], // 20px
+ lineHeight: lineHeightVars['--leading-base'],
color: colorVars['--color-text-primary'],
margin: 0,
},
h6: {
fontFamily: typographyVars['--font-heading'],
- fontSize: textSizeVars['--text-xsm'], // 12px
+ fontSize: textSizeVars['--text-xsm'],
fontWeight: fontWeightVars['--font-weight-semibold'],
- lineHeight: 1.3333333333333333, // 16px
+ lineHeight: 1.3333333333333333,
color: colorVars['--color-text-primary'],
margin: 0,
},
});
-/**
- * Semantic text styles for body content
- */
const textStyles = stylex.create({
- /** Body text (14px, regular) - The bulk of content */
body: {
fontFamily: typographyVars['--font-body'],
- fontSize: textSizeVars['--text-base'], // 14px
+ fontSize: textSizeVars['--text-base'],
fontWeight: fontWeightVars['--font-weight-normal'],
- lineHeight: lineHeightVars['--leading-base'], // 20px
+ lineHeight: lineHeightVars['--leading-base'],
color: colorVars['--color-text-primary'],
margin: 0,
},
- /** Large body text (16px, regular) - Emphasized content, quotes */
large: {
fontFamily: typographyVars['--font-body'],
- fontSize: textSizeVars['--text-lg'], // 16px
+ fontSize: textSizeVars['--text-lg'],
fontWeight: fontWeightVars['--font-weight-normal'],
- lineHeight: 1.5, // 24px
+ lineHeight: 1.5,
color: colorVars['--color-text-primary'],
margin: 0,
},
- /** Emphasized text (14px, medium) - Labels for form/chart/table columns */
label: {
fontFamily: typographyVars['--font-body'],
- fontSize: textSizeVars['--text-base'], // 14px
+ fontSize: textSizeVars['--text-base'],
fontWeight: fontWeightVars['--font-weight-medium'],
- lineHeight: lineHeightVars['--leading-base'], // 20px
+ lineHeight: lineHeightVars['--leading-base'],
color: colorVars['--color-text-primary'],
margin: 0,
},
- /** Supporting/helper text (12px, regular) - Supplemental info */
supporting: {
fontFamily: typographyVars['--font-body'],
- fontSize: textSizeVars['--text-xsm'], // 12px
+ fontSize: textSizeVars['--text-xsm'],
fontWeight: fontWeightVars['--font-weight-normal'],
- lineHeight: 1.3333333333333333, // 16px
+ lineHeight: 1.3333333333333333,
color: colorVars['--color-text-secondary'],
margin: 0,
},
- /** Code/monospace text (14px, regular) */
code: {
fontFamily: typographyVars['--font-code'],
- fontSize: textSizeVars['--text-base'], // 14px
+ fontSize: textSizeVars['--text-base'],
fontWeight: fontWeightVars['--font-weight-normal'],
- lineHeight: lineHeightVars['--leading-base'], // 20px
+ lineHeight: lineHeightVars['--leading-base'],
color: colorVars['--color-text-primary'],
margin: 0,
},
@@ -574,32 +439,16 @@ export const neutralTheme: Theme = {
icons: neutralIconRegistry,
styles: {
colors: colorTheme,
- spacing: spacingTheme,
- size: sizeTheme,
radius: radiusTheme,
elevation: elevationTheme,
- transition: transitionTheme,
typography: typographyTheme,
- textSize: textSizeTheme,
- lineHeight: lineHeightTheme,
- fontWeight: fontWeightTheme,
},
raw: {
- colors: colorRaw,
- spacing: spacingRaw,
- size: sizeRaw,
- radius: radiusRaw,
- elevation: elevationRaw,
- transition: transitionRaw,
- typography: typographyRaw,
- textSize: textSizeRaw,
- lineHeight: lineHeightRaw,
- fontWeight: fontWeightRaw,
+ colors: colorOverrides,
+ radius: radiusOverrides,
+ elevation: elevationOverrides,
+ typography: typographyOverrides,
},
- // Component style overrides — typed loosely here because ComponentStyles
- // is augmented by individual components via `declare module`. The theme
- // package doesn't import those components, so the augmentations aren't
- // visible at compile time. The types are enforced at the consumer site.
components: {
button: {
variants: buttonVariants,