Theme System

bash
npm install @astryxdesign/theme-neutral

tsx
import {Theme} from '@astryxdesign/core';
import {neutralTheme} from '@astryxdesign/theme-neutral';
​
function App() {
  return (
    <Theme theme={neutralTheme}>
      <YourApp />
    </Theme>
  );
}

tsx
import {Theme} from '@astryxdesign/core';
import {neutralTheme} from '@astryxdesign/theme-neutral/built';
import '@astryxdesign/theme-neutral/theme.css';
​
function App() {
  return (
    <Theme theme={neutralTheme}>
      <YourApp />
    </Theme>
  );
}

Each theme ships as its own npm package. Install the one you want, then wrap your app in <Theme>. The same pattern works for every theme; just swap the package and import name.

The default import uses runtime style injection, which works everywhere with no build step. The /built import skips injection and relies on the pre-compiled CSS file for better performance and SSR support.

Install the theme package you want with npm install @astryxdesign/theme-{name}, then import its theme object as shown below.

All theme packages export from two subpaths: - @astryxdesign/theme-{name}: source theme (runtime injection) - @astryxdesign/theme-{name}/built: pre-built theme (pair with theme.css)

Start from a theme we ship, or write one from scratch with defineTheme. Only override tokens that differ from defaults; omitted tokens use the design system defaults.

bash
astryx theme list
astryx theme add stone

For an annotated map of the whole surface (every defineTheme field, the token families, and the component override syntax, each with the CLI command that prints its reference), run astryx theme template. It writes theme.template.ts into your project to read and copy from (astryx init --features theme writes it as part of project setup).

defineTheme creates a theme from token overrides and optional scale configs. Scale configs generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values, token by token. One caveat for the accent: overriding --color-accent in tokens re-points the reference tokens (--color-accent-muted, --color-text-accent, --color-icon-accent) but NOT --color-on-accent, which stays baked from the color.accent seed. To give each scheme its own accent with a consistent derived palette, pass a [light, dark] tuple to color.accent instead of overriding the token.

tsx
import {defineTheme} from '@astryxdesign/core/theme';
​
const myTheme = defineTheme({
  name: 'my-theme',
  // accent: single hex, or [light, dark] tuple to seed each scheme separately
  color: { accent: ['#7B61FF', '#9B85FF'], neutralStyle: 'cool' },
  typography: {
    scale: { base: 14, ratio: 1.2 },
    body: { family: 'Inter', fallbacks: '-apple-system, sans-serif' },
  },
  radius: { base: 4, multiplier: 1 },
  motion: { fast: 175, medium: 410, ratio: 0.75 },
  tokens: {
    // Explicit overrides take precedence over scale-generated values
    '--color-background-body': ['#FFFFFF', '#0A0A0A'],
  },
  components: {
    button: { 'variant:primary': { color: 'white' } },
  },
});

extends lets you derive a new theme from an existing one, inheriting its tokens, component overrides, icons, and fonts. Only specify what you want to change; everything else carries over from the base theme.

tsx
import {defineTheme} from '@astryxdesign/core/theme';
import {neutralTheme} from '@astryxdesign/theme-neutral';
import {myIcons} from './icons';
​
const brandTheme = defineTheme({
  name: 'brand',
  extends: neutralTheme,
  icons: myIcons,
  tokens: {
    '--color-accent': ['#7B61FF', '#9B85FF'],
  },
});

Inheritance is resolved when the theme is defined, so an extended theme is flat: astryx theme build emits one self-contained stylesheet holding everything the child inherited, and the base theme's CSS does not need to be loaded next to it. A base that is not a theme (most often an import that missed) is a build error rather than a theme that silently inherits nothing.

A theme can say what it looks like at each viewport width. The four tiers — mobile, tablet, desktop, wide — **partition** the width axis, so exactly one matches at any width and no two ever compete. Declaring a tier turns it on; a theme that declares none emits no tier CSS at all.

tsx
const acmeTheme = defineTheme({
  name: 'acme',
  typography: {scale: {base: 14, ratio: 1.2}},
  tokens: {'--spacing-4': '16px'},
​
  mobile: {
    maxWidth: 756,                      // optional; this is the default
    tokens: {'--spacing-4': '12px'},    // narrow, any pointer
    '@media (pointer: coarse)': {
      typography: {scale: {base: 16}},  // narrow AND touch; ratio inherited
    },
  },
​
  tablet: {extends: 'mobile'},          // start from mobile's values
});

A tier's value is a partial theme: the same axes as the theme itself (typography, color, radius, motion, tokens, components), resolved through the same pipeline. State only what differs — a scale that sets base and not ratio inherits the theme's ratio. Setting a maxWidth moves both of that tier's boundaries, since a tier's lower bound is always the tier below it. Widths no declared tier covers use the theme's own values.

**extends is value inheritance, not the cascade.** It defaults to the theme's own values; naming another tier starts from that tier's resolved values instead. tablet: {extends: 'mobile'} takes mobile's *values* — mobile's CSS still applies only at mobile widths.

**Precedence.** Tiers partition, so no two tiers can both match and the question never arises. Within a tier, explicit tokens beat values generated from a scale — the same rule the theme itself follows — and a nested pointer refinement wins over the tier it sits in.

Nest '@media (pointer: coarse)' (or '@media (pointer: fine)') for values that also require a pointer type. Keep width and pointer separate: a 16px body floor exists because iOS Safari zooms an input whose text is under 16px — a fact about the finger, true on a phone and an iPad alike and never true of a desktop window dragged narrow. Resizing a window is a layout gesture; the layout reflows and the type holds.

Tiers are plain CSS media queries inside the theme stylesheet, so they render correctly on the server with no hydration flash and need no useMediaQuery. Both distribution modes emit them from the same generator — but only a built theme (astryx theme build) is in the stylesheet at first paint, so prefer the built path for a responsive theme.

The components field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use base for all instances, variant:value or stateName for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in astryx docs styling.

tsx
components: {
  // Standard CSS properties are expanded automatically.
  // borderRadius also sets the internal radius var for concentric math.
  // padding on container components (card, section, dialog) expands to layout tokens.
  card: {
    base: { borderRadius: '20px', padding: '24px' },
  },
  button: {
    base: {
      borderRadius: '9999px',
      textTransform: 'uppercase',
      // Some components have public CSS vars for properties that don't map
      // to standard CSS. Set these directly. Take the name from
      // `astryx component <Name>` — a var the component does not define
      // compiles to CSS that never applies.
      '--button-focus-offset': '3px',
    },
    'variant:ghost': { borderWidth: '2px', borderStyle: 'solid' },
  },
}

Run astryx theme targets for every themeable key in the system (astryx theme targets <Name> to scope it, --json to lint a theme against it), and astryx component <Name> for one component's theming targets, public CSS variables, and which standard CSS properties are supported.

Themes can add new prop values to any component. Any prop:value key where the value isn't a built-in gets treated as a new variant. Use astryx theme build to generate TypeScript augmentations for type safety.

tsx
components: {
  button: {
    // Override an existing variant
    'variant:secondary': { backgroundColor: 'rgba(0,0,0,0.06)' },
    // Add a new variant — generates type augmentation on build
    'variant:primary-muted': {
      backgroundColor: 'light-dark(#F2F4F6, #28292C)',
      color: 'var(--color-text-primary)',
    },
  },
  banner: {
    // Any extensible prop axis works — not just variant
    'status:neutral': {
      backgroundColor: 'var(--color-muted)',
      color: 'var(--color-text-secondary)',
    },
  },
}

After building, the new values are type-safe in JSX:

tsx
// TypeScript knows about 'primary-muted' after astryx theme build
<Button variant="primary-muted" label="Save draft" />
<Banner status="neutral" title="Note" />

Custom variants only work when the theme that defines them is active. The component's variant map is extended via module augmentation, with no changes to the component source needed.

astryx theme build compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.

bash
astryx theme build ./src/themes/ocean.ts

This generates the following files alongside the source:

The __built: true flag tells Theme to skip runtime <style> injection; the CSS file handles it.

tsx
import {oceanTheme} from './themes/ocean';
import './themes/ocean.css';
​
<Theme theme={oceanTheme}>
  <App />
</Theme>

The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the <link>/@font-face to add. The built CSS only sets font-family, so loading the font files stays the app's job. See astryx docs typography for the full recipe.

Themes work in two modes:

Use [light, dark] tuples in token values for automatic mode switching. Use mode='system' (default) on Theme to follow OS preference.

tsx
'--color-accent': ['#0064E0', '#2694FE'],
//                   ^light     ^dark

tsx
const [mode, setMode] = useState<'light' | 'dark'>('light');
​
<Theme theme={myTheme} mode={mode}>
  <Button
    label={mode === 'light' ? 'Switch to Dark' : 'Switch to Light'}
    onClick={() => setMode(m => (m === 'light' ? 'dark' : 'light'))}
  />
</Theme>;

Wrap different sections in separate <Theme> providers.

tsx
<Theme theme={lightTheme} mode="light">
  <Layout
    header={<LayoutHeader>...</LayoutHeader>}
    start={
      <Theme theme={darkTheme} mode="dark">
        <LayoutPanel>{/* Dark sidebar */}</LayoutPanel>
      </Theme>
    }
    content={<LayoutContent>{/* Light content */}</LayoutContent>}
  />
</Theme>

Use tokenVar() when a non-StyleX styling library wants a CSS variable reference, and resolveThemeTokens() when JavaScript needs token values for a specific theme and mode without React context. Themes are also registered by name when created with defineTheme(); call registerTheme(theme) for prebuilt or object-literal themes that need name-based SSR lookup.

ts
import {tokenVar, tokenVars} from '@astryxdesign/core/theme/tokens';
​
const pandaOrEmotionTheme = {
  colors: {
    text: tokenVar('--color-text-primary'),
    surface: tokenVars['--color-background-surface'],
  },
  spacing: {
    4: tokenVars['--spacing-4'],
  },
};

ts
import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';
import {neutralTheme} from '@astryxdesign/theme-neutral';
​
const lightTokens = resolveThemeTokens(neutralTheme, {mode: 'light'});
const chartTheme = {
  textColor: lightTokens['--color-text-primary'],
  seriesColor: lightTokens['--color-data-categorical-blue'],
};

The @astryxdesign/core/theme/tokens subpath is server-safe and does not require React. The main @astryxdesign/core/theme barrel also re-exports these helpers for client code that already imports theme APIs.

useTheme() uses the same token resolution as resolveThemeTokens(), but reads the nearest Theme and effective color mode from React context and media query state. Use it inside client components for SVG, canvas, charts, maps, and third-party configuration objects that need token values in JavaScript instead of var(...) references.

tsx
import {useMemo} from 'react';
import {useTheme} from '@astryxdesign/core/theme';
​
function ChartConfig() {
  const {mode, tokens} = useTheme();
​
  const options = useMemo(
    () => ({
      mode,
      textColor: tokens['--color-text-primary'],
      gridColor: tokens['--color-border'],
      seriesColor: tokens['--color-data-categorical-blue'],
    }),
    [mode, tokens],
  );
​
  return <Chart options={options} />;
}

Prefer CSS variables, StyleX token imports, xstyle, or className for ordinary styling. To change the theme or mode, manage state at the app level and pass it to <Theme>.

See astryx docs styling-libraries for styling-library interop and astryx docs tokens for the full token reference.