how-to-guide

Available Astryx Theme Packages and How to Switch Them

July 2, 2026 facebook/astryx ↗

Astryx ships seven ready-made theme packages (Y2K, Stone, Neutral, Matcha, Gothic, Chocolate, and Butter) that you install via npm and apply using the <XDSTheme> provider from @astryxdesign/core/theme, switching between them at runtime by passing different theme objects to the provider.

The facebook/astryx repository provides a complete theming system for React applications built on StyleX. Each Astryx theme package bundles StyleX-compiled token sets, optional pre-built CSS, and font-loading recommendations into a consumable npm module under the @astryxdesign namespace.

Available Astryx Theme Packages

Astryx maintains seven distinct themes in packages/themes/<name>, each published as @astryxdesign/theme-<name>. The following table summarizes the design focus of each package:

Theme	Package name	Primary design focus
Y2K	`@astryxdesign/theme-y2k`	Playful periwinkle / holographic palette
Stone	`@astryxdesign/theme-stone`	Warm stone & slate, earthy neutrals
Neutral	`@astryxdesign/theme-neutral`	Minimal, system-font-only
Matcha	`@astryxdesign/theme-matcha`	Earthy green, custom typefaces
Gothic	`@astryxdesign/theme-gothic`	Dark-only atmospheric gothic
Chocolate	`@astryxdesign/theme-chocolate`	Rich brown / cozy beige
Butter	`@astryxdesign/theme-butter`	Soft pastel palette

Installing Astryx Theme Packages

Install any theme via npm using its scoped package name:

npm install @astryxdesign/theme-y2k

Replace y2k with stone, neutral, matcha, gothic, chocolate, or butter to install other variants.

Applying a Theme with XDSTheme

According to the source code in packages/core/src/theme/index.ts, the <XDSTheme> provider accepts a theme object and injects the corresponding CSS custom properties into your component tree.

Import the theme object from the built entry point (pre-compiled distribution) and wrap your application:

import { XDSTheme } from '@astryxdesign/core/theme';
import { y2kTheme } from '@astryxdesign/theme-y2k/built';

function App() {
  return (
    <XDSTheme theme={y2kTheme}>
      {/* your UI goes here */}
    </XDSTheme>
  );
}

If you are using the StyleX source compiler (@astryxdesign/build), import from the bare package path instead to allow tree-shaking and compilation:

import { y2kTheme } from '@astryxdesign/theme-y2k';

Adding Pre-built CSS (Optional)

When using the pre-built distribution, you can import the generated CSS file into a global stylesheet as shown in packages/themes/y2k/README.md:

@import '@astryxdesign/theme-y2k/theme.css';

Switching Themes at Runtime

Because <XDSTheme> accepts any theme object as a prop, you can switch Astryx theme packages dynamically using React state. The provider automatically re-renders with new token values and CSS classes.

import { XDSTheme } from '@astryxdesign/core/theme';
import { y2kTheme } from '@astryxdesign/theme-y2k/built';
import { stoneTheme } from '@astryxdesign/theme-stone/built';
import { useState } from 'react';

export function ThemedApp() {
  const [theme, setTheme] = useState(y2kTheme);

  return (
    <>
      <button onClick={() => setTheme(theme === y2kTheme ? stoneTheme : y2kTheme)}>
        Switch Theme
      </button>

      <XDSTheme theme={theme}>
        {/* app content */}
      </XDSTheme>
    </>
  );
}

Handling Dark-Only Themes

The Gothic theme forces dark mode regardless of system preference. As implemented in packages/themes/gothic/README.md, pass the mode="dark" prop to the provider to maintain consistent native scrollbar and form-control styling:

import { XDSTheme } from '@astryxdesign/core/theme';
import { gothicTheme } from '@astryxdesign/theme-gothic/built';

function App() {
  return (
    <XDSTheme theme={gothicTheme} mode="dark">
      {/* UI */}
    </XDSTheme>
  );
}

Loading Custom Fonts

Most themes (except Neutral) reference custom web fonts. Each theme's README in packages/themes/<name>/README.md specifies the required <link> elements for the HTML <head>. While optional, loading these fonts is recommended to achieve the intended visual design.

Core Theme Implementation Files

The theming system relies on several key files in the repository:

packages/core/src/theme/index.ts — Exports the <XDSTheme> component and public provider API.
packages/core/src/theme/useTheme.ts — Provides the useTheme hook for programmatic access to resolved token values.
packages/core/src/theme/types.ts — Defines TypeScript interfaces for theme objects (DefinedTheme, token overrides).
packages/core/src/theme/tokens.ts — Contains the core token resolver that powers CSS custom properties behind every theme.

Summary

Astryx provides seven official theme packages: Y2K, Stone, Neutral, Matcha, Gothic, Chocolate, and Butter.
Install themes via npm install @astryxdesign/theme-<name> and import the theme object from /built (or the bare path for source compilation).
Wrap your application with <XDSTheme> from @astryxdesign/core/theme and pass the theme object to apply it.
Switch themes at runtime by changing the theme object passed to the provider using React state.
Use mode="dark" for dark-only themes like Gothic to ensure consistent UI chrome.
Import optional pre-built CSS files and custom fonts listed in each theme's README for complete styling.

Frequently Asked Questions

What are the available Astryx theme packages?

Astryx maintains seven official theme packages: Y2K (playful periwinkle), Stone (warm neutrals), Neutral (system fonts only), Matcha (earthy green), Gothic (dark-only atmospheric), Chocolate (rich browns), and Butter (soft pastels). Each is published as @astryxdesign/theme-<name> under packages/themes/<name> in the facebook/astryx repository.

How do I switch between Astryx themes dynamically?

You switch themes by updating the theme prop passed to the <XDSTheme> provider. Store the current theme object in React state (or any state manager) and toggle between imported themes like y2kTheme and stoneTheme. The provider re-renders automatically, applying the new token values and CSS classes without requiring a page reload.

Should I import from `/built` or the bare package path?

Import from /built (e.g., @astryxdesign/theme-y2k/built) when using the pre-compiled distribution to get the theme object immediately. Import from the bare path (e.g., @astryxdesign/theme-y2k) when using @astryxdesign/build with the StyleX source compiler, allowing the build system to tree-shake and compile the theme tokens during your application's build process.

Do I need to import CSS files separately for Astryx themes?

Importing CSS is optional when using the pre-built distribution. If you want to include the generated CSS manually, add @import '@astryxdesign/theme-<name>/theme.css' to your global stylesheet. When using the source compiler path, StyleX handles the CSS injection automatically.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how facebook/astryx works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →