# How Astryx Theming Works with CSS Custom Properties: A Complete Guide > Discover how Astryx theming leverages CSS custom properties for dynamic light/dark modes and theme inheritance. Explore runtime injection and build-time compilation. - Repository: [Meta/astryx](https://github.com/facebook/astryx) - Tags: deep-dive - Published: 2026-07-15 --- **Astryx converts TypeScript design tokens into CSS custom properties that are injected at runtime or compiled at build time, enabling automatic light/dark mode switching and theme inheritance without JavaScript overhead.** Astryx, an open-source design system by Meta (`facebook/astryx`), leverages **CSS custom properties** to create a type-safe, composable theming layer. The system transforms static token definitions into dynamic CSS variables using StyleX, allowing components to respond to theme changes instantly. This architecture separates design decisions from component logic while maintaining full TypeScript autocompletion for all theme values. ## Token Architecture in tokens.stylex.ts All design tokens originate in [`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts). This file declares core tokens—covering color, spacing, size, radius, shadow, motion, and typography—as plain objects where each key follows the `--token-name` syntax. The file exports token maps like `colorVars` and `spacingVars` via `stylex.defineVars`, which creates a mapping between TypeScript constants and CSS custom properties. For example, `--color-accent`, `--spacing-4`, and `--radius-container` are defined here and made available as typed variables throughout the system. ## Theme Creation with defineTheme The public API for creating themes is `defineTheme` in [`packages/core/src/theme/defineTheme.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/defineTheme.ts). This function accepts a configuration object containing token values that can be either static strings or light/dark tuples. When you call `defineTheme`, the input values are merged with default tokens and converted to CSS custom-property assignments. The function generates the final CSS rules—using `var(--token)` for consumption—and prepares them for injection or compilation. For tokens specified as arrays, the system automatically wraps them in the native `light-dark()` CSS function. ## Automatic Light/Dark Mode Handling Astryx handles dark mode without JavaScript runtime switching by utilizing the native CSS `light-dark()` function. When a token value is provided as a tuple `[lightValue, darkValue]` in `defineTheme`, the system wraps these values according to lines 11–14 of [`defineTheme.ts`](https://github.com/facebook/astryx/blob/main/defineTheme.ts). This means the same CSS custom property works for both color schemes automatically. The browser applies the appropriate value based on the user's system preferences or the `color-scheme` property, eliminating flash-of-unstyled-content issues common to JavaScript-based theme switching. ## Runtime Injection vs. Build-Time Compilation Astryx supports two modes for delivering CSS custom properties to the browser: **Unbuilt mode:** When using the runtime `` component from [`packages/core/src/theme/index.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/index.ts), `defineTheme` generates the CSS dynamically and injects it into a `