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

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, 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.

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.

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.

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: Contains the core token definitions, stylex.defineVars exports, and helper TypeScript types.
• packages/core/src/theme/defineTheme.ts: Implements the runtime theming API that consumes the token maps.
• packages/core/src/theme/index.ts: Re-exports token maps for public consumption.
• 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 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.

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

Default values are defined in 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.

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