# Understanding the `tokens.stylex` Typed Import in Astryx: Type-Safe Design Tokens

> Learn about the tokens.stylex typed import in Astryx. Access design tokens as CSS custom properties with StyleX defineVars for compile-time type checking in your design system.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: deep-dive
- Published: 2026-07-02

---

**The `tokens.stylex` import provides a strongly-typed source of design tokens that exposes CSS custom properties through StyleX's `defineVars` API, enabling compile-time type checking for design system values across the facebook/astryx repository.**

The `tokens.stylex` module serves as the central authority for design tokens in the Astryx design system from Meta. Located at [`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts), this file exports typed StyleX variable maps that bridge raw CSS custom property values with TypeScript's type system, ensuring component styles remain consistent and refactor-safe.

## What Is the tokens.stylex Typed Import?

The `tokens.stylex` file fulfills three essential roles in the design system architecture.

### Define Raw Token Values

The file declares default objects containing literal CSS custom-property values. Objects such as `colorDefaults`, `spacingDefaults`, and `sizeDefaults` establish the foundational values for the theme. According to the source code at lines 23-33, these defaults include declarations like `--color-accent: light-dark(#0064E0, #2694FE)`.

### Expose Typed CSS Variables

Each defaults object is passed to `stylex.defineVars`, which creates a typed variable map. The declaration `export const colorVars = stylex.defineVars(colorDefaults);` at lines 46-47 generates a map where TypeScript infers exact variable names from the keys of `colorDefaults`. Analogous exports exist for `spacingVars` and other token groups.

### Provide Helper TypeScript Types

The file exports utility types such as `ColorVarName` that allow developers to write type-safe APIs. Defined at lines 445-452, these types use `keyof typeof colorDefaults` to restrict function parameters to valid token names only, preventing runtime errors through static analysis.

## How the Typed Import Functions

The type safety relies on TypeScript's ability to infer literal types from `as const` assertions on the defaults objects. When `colorDefaults` is declared as a readonly record with literal string keys like `'--color-accent'`, `stylex.defineVars` preserves this type information. Consequently, accessing `colorVars['--color-foo']` results in a compile-time error because the key does not exist in the type definition.

At runtime, importing a token map provides CSS custom properties that StyleX automatically injects into the DOM. When a component references `colorVars['--color-accent']`, it resolves to `var(--color-accent)` at render time. Because StyleX generates these mappings at compile time, the resulting CSS classes benefit from static extraction and dead-code elimination.

## Consuming tokens.stylex in Components

### Basic Token Usage

Import the typed variable maps directly from the theme package to style components with design system values.

```tsx
import {colorVars, spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
import * as stylex from '@stylexjs/stylex';

const useStyles = stylex.create({
  button: {
    backgroundColor: colorVars['--color-accent'],
    padding: spacingVars['--spacing-4'],
    borderRadius: 'var(--radius-element)',
  },
});

export function PrimaryButton({children}: {children: React.ReactNode}) {
  return <button className={useStyles.button}>{children}</button>;
}

```

### Type-Safe Helper Functions

Use the exported type helpers to create utility functions that only accept valid token names.

```tsx
import {colorVars, type ColorVarName} from '@astryxdesign/core/theme/tokens.stylex';

function tokenColor(name: ColorVarName) {
  // Returns a CSS var() expression like "var(--color-accent)"
  return colorVars[name];
}

// TypeScript enforces valid token names at compile time
const bg = tokenColor('--color-background-surface');

```

### Theming and Token Overrides

Override specific tokens using the `defineTheme` utility from [`packages/core/src/theme/defineTheme.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/defineTheme.ts).

```tsx
import {defineTheme} from '@astryxdesign/core/theme/defineTheme';
import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';

const darkTheme = defineTheme({
  tokens: {
    '--color-background-body': 'light-dark(#111112, #0a0a0b)',
    '--color-text-primary': 'light-dark(#fff, #e0e0e0)',
  },
});

// Apply the theme at the application root
<ThemeProvider theme={darkTheme}>…</ThemeProvider>

```

## Key Source Files

The `tokens.stylex` system is implemented across several files in the facebook/astryx repository:

- **[`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts)**: Contains the core token definitions, `stylex.defineVars` exports, and helper TypeScript types.
- **[`packages/core/src/theme/defineTheme.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/defineTheme.ts)**: Implements the runtime theming API that consumes the token maps.
- **[`packages/core/src/theme/index.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/index.ts)**: Re-exports token maps for public consumption.
- **[`packages/lab/src/SVGIcon/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/lab/src/SVGIcon/tokens.stylex.ts)**: Demonstrates component-level token files using the same pattern.
- **`scripts/generate-token-docs.mjs`**: Generates documentation from default objects, maintaining the single source of truth.

## Summary

- The `tokens.stylex` import in [`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts) serves as the single source of truth for Astryx design tokens.
- **Type safety** is achieved through `stylex.defineVars` and TypeScript's `keyof typeof` inference on `as const` defaulted objects.
- The system exports **helper types** like `ColorVarName` that enable compile-time validation of token names in component APIs.
- At runtime, tokens resolve to **CSS custom properties** with automatic DOM injection and StyleX optimizations.
- Developers can **override tokens** per-theme using the `defineTheme` utility while maintaining type safety.

## Frequently Asked Questions

### What makes the tokens.stylex import "typed"?

The import is typed because the default token objects use `as const` assertions, allowing TypeScript to infer literal string keys. When processed through `stylex.defineVars`, the resulting variable maps preserve these literal types, preventing access to invalid token names at compile time.

### How do I override tokens for dark mode in Astryx?

Use the `defineTheme` function from `@astryxdesign/core/theme/defineTheme` to create a theme object with specific token overrides. Pass this theme to a `ThemeProvider` component high in your React tree, as implemented in [`packages/core/src/theme/defineTheme.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/defineTheme.ts).

### Where are the default token values defined in the source code?

Default values are defined in [`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts) at lines 23-33, where objects like `colorDefaults` and `spacingDefaults` contain the literal CSS custom-property values that serve as the design system's foundation.

### Can I use tokens.stylex outside of React components?

Yes. While the examples show React usage, the `stylex.defineVars` output is framework-agnostic CSS. The token maps can be consumed anywhere StyleX is used, as they ultimately resolve to standard CSS custom properties injected into the document.