Wraps a subtree with a specific XDS theme. For static production themes, use npx astryx theme build and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime defineTheme() when themes are dynamic or for prototyping.
defineTheme accepts a tokens object whose keys are CSS custom property names (always prefixed with --). Common token names include --color-accent, --color-background-surface, --color-background-body, --color-text-primary, --color-text-secondary, --radius-container, --spacing-1 through --spacing-6. Values can be a string (same for light/dark) or a [light, dark] tuple.
Example: ts import {defineTheme} from '@astryxdesign/core/theme'; const myTheme = defineTheme({ name: 'ocean', tokens: { '--color-accent': ['#0077B6', '#48CAE4'], '--color-background-surface': ['#F0F8FF', '#0A1628'], '--color-text-primary': ['#0A1317', '#FFFFFF'], '--radius-container': '16px', }, });
ts
| Guidance | Practices |
|---|---|
| Do | Build app themes that are known ahead of time with npx astryx theme build, then import the generated CSS and built theme object. |
| Do | Use runtime themes when the theme is created or edited in the browser, such as theme editors, user branding, or prototypes. |
| Do | Token names always start with -- (e.g. --color-accent, --color-background-surface). Do not omit the prefix. |
| Don't | Default to runtime themes in SSR production apps. Component overrides inject after hydration instead of shipping as static CSS. |