Astryx

A React 19 design system by Meta. Accessible, themeable components with built-in spacing, dark mode, and StyleX styling. This skill covers installation, theming, styling, layout, CLI usage, AI integration, and migration.

When to Use

• Building React UIs with Astryx components from @astryxdesign/core
• Creating or customizing themes with defineTheme
• Styling components via StyleX (xstyle prop), Tailwind, or className
• Scaffolding pages from CLI templates
• Migrating existing Tailwind/shadcn/Radix apps to Astryx
• Using the Astryx CLI for component docs, tokens, and templates
• Connecting to the Astryx MCP server for AI-powered component discovery
• Validating Astryx code against system conventions

Packages at a Glance

Quick Start

Install core, StyleX, a theme, and the CLI:

npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral @astryxdesign/cli

Add theme CSS to your global stylesheet:

@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-neutral/theme.css';

Wrap your app in Theme and add a component:

import {Theme} from '@astryxdesign/core';
import {neutralTheme} from '@astryxdesign/theme-neutral';
import {Button} from '@astryxdesign/core/Button';
import {VStack} from '@astryxdesign/core/Layout';

function App() {
  return (
    <Theme theme={neutralTheme}>
      <VStack gap={2}>
        <Button label="Hello Astryx" onClick={() => alert('Hi!')} />
      </VStack>
    </Theme>
  );
}

Initialize AI agent docs (non-interactive, safe for CI):

npx @astryxdesign/cli init --features agents

Design Principles

1. Components over primitives — use components before raw HTML
2. Frame-first layout — pick shell and budget regions before content
3. Dense data as rows — Table/List with dividers; Card for widgets and settings
4. StyleX or Tailwind — both first-class; both resolve to same tokens
5. Semantic tokens, not hardcoded values — var(--color-*), not hex
6. CSS custom properties for colors — not hex values
7. Controlled form inputs — value + onChange
8. useLinkComponent() for navigation — framework router via LinkProvider

Anti-Patterns

• No style={{}} on raw wrappers — use xstyle on components
• No hardcoded colors (#fff) — use var(--color-*) or Tailwind semantic classes
• No hardcoded spacing (16px) — use spacing tokens or Tailwind utilities
• No wrapping components in <div> just for margin — use xstyle
• No Badge as decoration — reserve for counts and enumerated states
• No inventing props — read component docs first

Token System

Tokens are CSS custom properties that adapt to the active theme and color mode.

Spacing

4px base unit. Component gap props accept step values 0–12.

Color

Semantic tokens describe purpose, not appearance. All use light-dark() for automatic mode switching.

Surface hierarchy: body → surface → card → popover.

Key tokens: --color-text-primary, --color-text-secondary, --color-background-surface, --color-background-body, --color-background-card, --color-background-popover, --color-border, --color-accent, --color-on-accent, --color-success, --color-error, --color-warning.

Size

Control heights: --size-element-sm (28px), --size-element-md (32px), --size-element-lg (36px).

Radius

--radius-none (0px), --radius-inner (8px), --radius-element (12px), --radius-container (16px), --radius-page (32px), --radius-chat (28px), --radius-full (9999px).

Typography

Geometric type scale: round(14 × 1.2^step). Semantic tokens combine size, weight, line-height. Use Heading and Text components — don't set font-size manually.

Font families: --font-family-body (Figtree), --font-family-code ("SF Mono"), --font-family-heading (Figtree).

Using Tokens

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

const styles = stylex.create({
  card: {
    padding: spacingVars['--spacing-4'],
    backgroundColor: colorVars['--color-background-surface'],
    borderRadius: radiusVars['--radius-container'],
  },
});

See references/tokens.md for the complete token reference.

Styling

All approaches resolve to the same design tokens — theming and dark mode work regardless of choice.

xstyle

import * as stylex from '@stylexjs/stylex';

const overrides = stylex.create({
  save: { alignSelf: 'flex-end', marginTop: 16 },
});

<Button label="Save" xstyle={overrides.save} />

All xstyle values must come from stylex.create(). All :hover styles must use @media (hover: hover) guard.

Tailwind Bridge

Import @astryxdesign/core/tailwind-theme.css once. Utilities like text-primary, bg-surface, border-border, rounded-lg, shadow-md resolve to active theme tokens. Pure CSS, zero JS.

See references/styling.md for full styling guide and references/styling-libraries.md for library interop.

Layout

Build outside-in: scaffold the shell, structure content, tune spacing, then adapt across widths.

Shell

• AppShell — for nav apps (with SideNav and/or TopNav)
• Layout + LayoutPanel — for multi-pane tools
• Plain content column — for documents and forms

<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>}>
  <Layout
    content={<LayoutContent>{/* table fills region */}</LayoutContent>}
    end={<LayoutPanel width={380} hasDivider>{/* detail */}</LayoutPanel>}
  />
</AppShell>

Navigation

Default to SideNav — it absorbs unplanned destinations. Use TopNav for shallow nav that must stay visible. Use both for genuine suites.

Structure

One lead per region. Rank with weight and color, not size. Reach for the weakest container that reads as a group: spacing → Divider → Section → Card.

Spacing

Container owns padding and child gaps. One content line per region. Contrast tight and generous gaps so grouping reads without borders.

Breakpoints

Lock what each region does as width changes: divide, reveal, resize, swap. Side panel becomes Dialog/BottomSheet via useMediaQuery. Nav becomes MobileNav at AppShell mobileNav breakpoint.

See references/layout.md for the full layout guide.

Theme System

Setup

import {Theme} from '@astryxdesign/core';
import {neutralTheme} from '@astryxdesign/theme-neutral';

<Theme theme={neutralTheme} mode="system">
  <YourApp />
</Theme>

defineTheme

import {defineTheme} from '@astryxdesign/core/theme';

const myTheme = defineTheme({
  name: 'my-theme',
  color: { accent: ['#7B61FF', '#9B85FF'], neutralStyle: 'cool' },
  typography: { scale: { base: 14, ratio: 1.2 } },
  radius: { base: 4, multiplier: 1 },
  tokens: {
    '--color-background-body': ['#FFFFFF', '#0A0A0A'],
  },
  components: {
    button: { 'variant:primary': { color: 'white' } },
  },
});

Runtime vs Built

Extending

const brandTheme = defineTheme({
  name: 'brand',
  extends: neutralTheme,
  tokens: { '--color-accent': ['#7B61FF', '#9B85FF'] },
});

See references/theme.md for defineTheme, component overrides, custom variants, nesting, and token utilities.

CLI

Add to package.json for reliable invocation:

"scripts": {
  "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}

Key Commands

astryx component          # list all components
astryx component Button   # full docs for Button
astryx docs               # list all doc topics
astryx docs tokens        # token reference
astryx template --list    # available page templates
astryx template dashboard # emit full page source
astryx search button       # search across components, hooks, docs, templates
astryx theme list          # list bundled themes
astryx theme add stone     # copy a theme as editable source
astryx theme build ./src/themes/ocean.ts  # compile for production
astryx doctor              # diagnose setup issues
astryx init --features agents  # generate AI agent docs

Every command supports --json (typed envelope), --dense (token-efficient for AI), and --detail (brief/compact/full).

See references/cli.md for all commands, JSON API, programmatic API, and integrations.

Working with AI

Agent Docs

npx @astryxdesign/cli init --features agents

Generates AGENTS.md with component index, behavioral rules, and CLI reference. Run again after version bumps.

MCP Server

Astryx ships an MCP server for AI tools to query the design system directly:

{
  "mcpServers": {
    "xds": {
      "type": "url",
      "url": "https://astryx.atmeta.com/mcp"
    }
  }
}

Tools exposed: search(query) for discovering components/docs/templates, get(name) for full documentation with props and examples.

AI Workflow

1. astryx template --list — find a related page pattern
2. astryx template --skeleton — study the layout structure
3. astryx component <Name> — read props and examples for every component used

See references/working-with-ai.md for full AI integration guide.

Migration

Migrate incrementally: Theme + AppShell first, then one route at a time.

1. Install design system, run init
2. Wrap app root with Theme
3. Declare CSS layer order explicitly
4. Run foundation smoke test
5. Move app frame (AppShell, TopNav, SideNav)
6. Replace shared primitives (Button, TextInput, Dialog, etc.)
7. Replace global workflows (command palette, settings, theme toggle)
8. Remove legacy Tailwind classes from completed surfaces
9. Verify light/dark mode, keyboard nav, responsive layout

See references/migration.md for the full migration guide.

Common Gotchas

• React 19 required. @astryxdesign/core has react and react-dom >= 19.0.0 as peer deps.
• Cascade layer order matters. Unlayered styles and later layers both override astryx-base regardless of specificity. Declare layer order explicitly.
• bare astryx doesn't resolve until installed. Use npx @astryxdesign/cli for first-run/one-off.
• Swizzled components need StyleX compiler. Missing compiler = unstyled components, no error. Use SWC-based transform for Next.js App Router.
• Accent override caveat. Overriding --color-accent in tokens re-points related tokens but NOT --color-on-accent. Pass a [light, dark] tuple to color.accent instead.
• Astryx never loads font files. defineTheme only sets font-family. Loading webfonts is the app's job.
• Don't use --color-on-accent on non-accent backgrounds. It's specifically for accent surfaces.
• Use data-variant attributes for external CSS. Not bare prop/state classes (.primary, .sm are deprecated).

Validation

The bundled scripts/validate.py checks Astryx code for common mistakes:

uv run scripts/validate.py --input component.tsx

Or pipe via stdin:

cat component.tsx | uv run scripts/validate.py --stdin

Checks: hardcoded hex colors, raw pixel spacing, style={{}} on raw elements, missing Theme provider, bare <div> wrappers for layout, and deprecated class selectors.

Detailed References

• references/principles.md — Design philosophy, rules, anti-patterns
• references/tokens.md — Complete token reference (color, spacing, size, radius, shadow, motion, typography)
• references/styling.md — xstyle prop, Tailwind bridge, className, compound components, data attributes, StyleX build setup
• references/styling-libraries.md — Interop with Tailwind, StyleX, Panda, Chakra, MUI, Emotion, UnoCSS, CSS Modules, non-CSS
• references/layout.md — Shell, navigation, structure, spacing, density, breakpoints
• references/theme.md — defineTheme, extending, component overrides, custom variants, runtime vs built, nesting, token utilities, useTheme
• references/cli.md — All commands, JSON API, programmatic API, doctor, integrations, configuration
• references/migration.md — Migration order, CLI workflow, cascade layer safety, shadcn/Radix mapping, verification checklist
• references/working-with-ai.md — Agent docs, MCP server, --dense flag, AI workflow, Cursor setup

Available Scripts

• scripts/validate.py — Validates Astryx code against system conventions. Run with uv run scripts/validate.py --input <file> or --stdin.