# What Are Astryx Design Tokens and How to Use Them

> Discover Astryx design tokens, CSS custom properties from StyleX, that centralize your design system for consistent theming. Learn how to implement colorVars and spacingVars.

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

---

**Astryx design tokens are CSS custom properties generated via StyleX's `defineVars` API that serve as the single source of truth for all visual style values in the facebook/astryx design system, enabling consistent theming through exported variable objects like `colorVars` and `spacingVars`.**

Astryx is Meta's open-source design system built on top of StyleX. The token system centralizes every visual dimension—from colors and spacing to motion curves and typography—into type-safe CSS variables that components consume at runtime.

## How Astryx Design Tokens Work

Astryx tokens are implemented as **CSS custom properties** using StyleX's `defineVars` API. This architecture allows the design system to maintain a single source of truth while supporting runtime theme overrides without modifying component code.

The tokens are **light-dark aware** where appropriate, utilizing the `light-dark()` CSS helper so that a single variable adapts automatically to both light and dark color schemes.

## Token Architecture and Source Files

Understanding the file structure reveals how tokens flow from definition to documentation to consumption.

### Central Token Definition

All default token values live in a single source file: [[`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts)](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts). This file exports plain objects containing default values alongside CSS variable definitions created by `stylex.defineVars`.

Each category exports both the defaults and the StyleX variable objects:

- `colorVars` for color values
- `spacingVars` for spacing values  
- `sizeVars` for dimension values
- `borderVars`, `radiusVars`, `shadowVars` for decorative elements
- `durationVars`, `easeVars` for motion
- `typographyVars`, `textSizeVars`, `fontWeightVars`, `typeScaleVars` for text

### Generated Documentation

A dedicated script [`scripts/generate-token-docs.mjs`](https://github.com/facebook/astryx/blob/main/scripts/generate-token-docs.mjs) parses the source tokens and generates [`packages/cli/docs/tokens.doc.mjs`](https://github.com/facebook/astryx/blob/main/packages/cli/docs/tokens.doc.mjs). This generated module powers both the CLI documentation viewer and Storybook swatches, rendering human-readable tables and live previews of each token value.

### Runtime Consumption

When you import the token objects, StyleX injects the CSS custom properties into the global stylesheet. Components reference these variables at runtime, which means **theme overrides take effect immediately** without recompiling the components.

## How to Import and Use Design Tokens

Components consume tokens by importing the variable objects from `@astryxdesign/core` and referencing them in `stylex.create` style definitions.

### Basic Token Usage

Import the specific variable objects you need and reference them by their CSS variable name:

```tsx
import * as stylex from '@stylexjs/stylex';
import {
  colorVars,
  spacingVars,
  sizeVars,
  radiusVars,
} from '@astryxdesign/core';

const styles = stylex.create({
  card: {
    padding: spacingVars['--spacing-4'],
    backgroundColor: colorVars['--color-background-surface'],
    borderRadius: radiusVars['--radius-container'],
  },
  button: {
    height: sizeVars['--size-element-md'],
    backgroundColor: colorVars['--color-accent'],
    color: colorVars['--color-on-accent'],
  },
});

```

### Creating Custom Themes

Override any subset of tokens using `stylex.createTheme` (or the higher-level `defineTheme` helper). Because components read CSS variables at runtime, the new values propagate automatically:

```tsx
import { createTheme } from '@stylexjs/stylex';
import { colorVars } from '@astryxdesign/core';

const darkTheme = createTheme({
  '--color-accent': 'light-dark(#ff8c00, #ffb84d)',
  '--color-on-accent': '#000000',
});

function App() {
  return (
    <div className={darkTheme}>
      <MyButton />
    </div>
  );
}

```

### Accessing Tokens Programmatically

For JavaScript runtime access to computed values, query the CSS custom property directly:

```tsx
const accent = getComputedStyle(document.documentElement)
  .getPropertyValue(colorVars['--color-accent'])
  .trim();

console.log('Current accent token:', accent);

```

## Available Token Categories

The Astryx token system covers eleven distinct visual categories:

- **Colors** (`colorVars`): `--color-accent` defaults to `light-dark(#0064E0, #2694FE)`
- **Spacing** (`spacingVars`): `--spacing-4` equals `16px`
- **Size** (`sizeVars`): `--size-element-md` equals `32px`
- **Border** (`borderVars`): `--border-width` equals `1px`
- **Radius** (`radiusVars`): `--radius-container` equals `12px`
- **Shadow** (`shadowVars`): `--shadow-low` includes `light-dark` adaptive opacity values
- **Motion Duration** (`durationVars`): `--duration-fast` equals `175ms`
- **Motion Easing** (`easeVars`): `--ease-standard` uses `cubic-bezier(0.24, 1, 0.4, 1)`
- **Typography Family** (`typographyVars`): `--font-family-body` contains the system font stack
- **Typography Size** (`textSizeVars`): `--font-size-base` equals `0.875rem`
- **Typography Weight** (`fontWeightVars`): `--font-weight-medium` equals `500`
- **Type Scale** (`typeScaleVars`): `--text-heading-1-size` references `var(--font-size-2xl)`

## CLI Documentation Tools

Inspect available tokens using the Astryx CLI, which reads the generated documentation module:

```bash
npx astryx docs tokens

```

This command renders the complete token tables and interactive previews defined in `packages/cli/docs/tokens.doc.mjs`, including localized versions like [`tokens.doc.zh.mjs`](https://github.com/facebook/astryx/blob/main/packages/cli/docs/tokens.doc.zh.mjs) for Chinese documentation.

## Summary

- **Astryx design tokens** are CSS custom properties defined in [`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts) using StyleX's `defineVars` API.
- **Import patterns** require referencing specific variable objects (e.g., `colorVars`, `spacingVars`) from `@astryxdesign/core`.
- **Theming works** by calling `stylex.createTheme` to override token values; components automatically reflect changes because they read CSS variables at runtime.
- **Documentation is auto-generated** via `scripts/generate-token-docs.mjs` into `packages/cli/docs/tokens.doc.mjs` for CLI and Storybook consumption.
- **Light-dark mode** is built-in using the `light-dark()` CSS helper for applicable tokens.

## Frequently Asked Questions

### How do I override a specific token in my theme?

Call `stylex.createTheme` from `@stylexjs/stylex` and pass an object containing only the tokens you want to override. Import the variable object from `@astryxdesign/core` to ensure you reference the correct CSS custom property names. The theme class will override the default values for all child components without requiring code changes in the components themselves.

### Where are the default token values defined in the Astryx repository?

All default values live in [[`packages/core/src/theme/tokens.stylex.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts)](https://github.com/facebook/astryx/blob/main/packages/core/src/theme/tokens.stylex.ts). This file exports default value objects (like `colorDefaults`) and StyleX variable objects (like `colorVars`) that become CSS custom properties when the package is imported.

### Can I use Astryx tokens outside of StyleX components?

Yes. Because Astryx tokens are standard CSS custom properties, you can access them programmatically using `getComputedStyle(document.documentElement).getPropertyValue()` with the variable reference from the imported token objects (e.g., `colorVars['--color-accent']`). You can also use the tokens in regular CSS if the custom properties are defined in the DOM.

### How does the light-dark mode work with Astryx tokens?

Tokens use the `light-dark()` CSS function to specify different values for light and dark color schemes. For example, the accent color defaults to `light-dark(#0064E0, #2694FE)`, which renders as `#0064E0` in light mode and `#2694FE` in dark mode. This eliminates the need for separate token sets or manual theme switching logic in your components.