What Are Astryx Design Tokens and How to Use Them

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). 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 parses the source tokens and generates 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:

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:

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:

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:

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 for Chinese documentation.

Summary

• Astryx design tokens are CSS custom properties defined in 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). 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}