Astryx Design System Complete Guide: From Setup to Production

Astryx is Meta’s design system — a collection of 150+ components, a semantic token system, CLI tooling, and AI integration designed to help you build UIs faster and more consistently. This guide walks you through everything from installation to building production-grade applications.

Getting Started

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

npm install @astryxdesign/core @astryxdesign/theme-matcha @astryxdesign/cli
npx astryx init --all

Import exactly three CSS files in your entry point:

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

Your first component:

import { Button } from '@astryxdesign/core/Button';
import { VStack } from '@astryxdesign/core/Layout';

export default function Page() {
  return (
    <VStack gap={2}>
      <Button label="Hello Astryx" onClick={() => alert('Hello!')} />
    </VStack>
  );
}

Three Golden Rules

1. No <div> — Components handle all layout. Use VStack, HStack, AppShell, LayoutPanel instead.
2. Frame-first layout — Decide the app shell before writing any content. Choose between AppShell, Layout + LayoutPanel, or a plain content column.
3. Semantic tokens over hardcoded values — Never use raw hex, px, or rem values. Use CSS custom properties from the token system.

Design Tokens

Astryx uses a comprehensive semantic token system — CSS custom properties named by purpose rather than appearance. There are 10 token categories:

Category	Prefix	Example
Color	--color-*	--color-accent
Spacing	--spacing-*	--spacing-4
Radius	--radius-*	--radius-container
Shadow	--shadow-*	--shadow-med
Typography	--text-*	--text-body-size
Font	--font-*	--font-family-body
Size	--size-*	--size-element-md
Duration	--duration-*	--duration-fast
Easing	--ease-*	--ease-standard
Border	--border-*	--border-width

Color System

The color system uses semantic tokens where names describe purpose, not appearance. All colors use CSS light-dark() for automatic light/dark mode switching — no manual prefers-color-scheme media query needed.

.my-component {
  color: var(--color-text-primary);
  background: var(--color-background-surface);
  padding: var(--spacing-4);
  border-radius: var(--radius-container);
  box-shadow: var(--shadow-low);
}

Typography

The type system uses a geometric scale: round(14 × 1.2^step). Base = 14px, ratio = 1.2. Semantic type levels include display-1, display-2, heading-1 through heading-6, body, large, supporting, label, and code.

Spacing

A 4px-base-unit scale. Standard spacing uses --spacing-4 (16px) for elements in the same group, --spacing-6 (24px) between sections, and --spacing-8 (32px) between major groups.

Component Architecture

Astryx ships over 150 components organized into 13 categories:

Category	Count	Purpose
Navigation	16	App shells, sidebars, top bars, breadcrumbs
Layout	12	Stacks, grids, centering, form layout
Buttons	5	Button variants, icon buttons, toggle groups
Inputs	18	Text inputs, selects, switches, file inputs
Selectors	10	Dropdowns, typeaheads, radio lists, tokenizers
Data Display	22	Tables, cards, lists, avatars, badges, code blocks
Overlays	13	Dialogs, popovers, tooltips, command palette
Feedback	5	Banners, toasts, progress bars, skeletons, spinners
Typography	8	Headings, text, blockquotes, keyboard, links
Tabs	3	Tab lists, tabs, tab menus
Chat	14	Chat composers, message bubbles, tool calls
Utilities	8	Collapsible, divider, theme switchers, providers
Tooling	4	Pagination, search, toolbar, overflow list

Key Patterns

Components are imported from per-category subpath entrypoints (no single barrel file). Every component accepts xstyle, className, and rest props. Props are reflected as data-* attributes on the root element for CSS selectors.

Theming and Layout

Astryx ships with 7 built-in themes: Matcha, Neutral, Butter, Chocolate, Gothic, Stone, and Y2K. Each is a separate npm package.

Wrap your app with <Theme> to activate a theme:

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

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

Create fully custom themes with defineTheme():

const myTheme = defineTheme({
  name: 'brand',
  color: { accent: '#7B61FF' },
  typography: { body: { family: 'Inter' } },
  components: {
    button: { base: { borderRadius: '9999px' } },
  },
});

Styling Approaches

Astryx supports three styling approaches:

Approach	Mechanism	Best For
StyleX	xstyle prop + stylex.create()	TypeScript-first, type-safe
Tailwind	Utility classes + Tailwind bridge	Tailwind-first projects
Plain CSS	className + CSS custom properties	Small/traditional projects

The core principle: component props first, then xstyle, then className. Never raw hex or px values.

Migration and Internationalization

Incremental Migration

Astryx is designed for incremental migration. Follow the 9-step plan:

1. Install and initialize
2. Wrap app root with <Theme>
3. Declare CSS layer order
4. Foundation smoke test
5. Migrate persistent frame (AppShell, SideNav)
6. Migrate shared primitives (Button, TextInput)
7. Migrate global workflows
8. Delete legacy classes last
9. Verify light/dark mode, keyboard navigation, responsive layout

Internationalization

import { InternationalizationProvider, useTranslator } from '@astryxdesign/core';

function SaveButton() {
  const t = useTranslator();
  return <button>{t('@myapp.actions.save')}</button>;
}

<InternationalizationProvider locale="en" messages={{ fr }}>
  <App />
</InternationalizationProvider>

Real-World Application Patterns

Six workshop patterns demonstrate production-grade interfaces:

• Chat UI — Dark/light theme toggle, artifact panel, responsive split-pane layout
• Kanban Board — Drag-and-drop with Pointer Events, color-coded columns, localStorage persistence
• Analytics Dashboard — KPI cards, Recharts integration, engagement tables
• Settings Page — State-based routing, editable inline fields, tab navigation
• Checkout Form — Shipping info, payment form, promo code, order summary sidebar
• Authentication Flow — Three-view auth (Login, Sign Up, Forgot Password) with form validation

Common Patterns Across All Workshops

1. Theme at the root — wrap everything with <Theme>
2. No <div> — every layout concern uses an Astryx component
3. State-based routing — no React Router needed for simple flows
4. Validation via the status prop — consistent error display across inputs
5. Responsive via component props — Stack direction, Collapsible, Grid
6. Token-based values — no hardcoded colors, spacing, or radii

CLI and AI Integration

Astryx provides built-in CLI tooling and AI agent support:

npx astryx component --list         # list all 150+ components
npx astryx component Button         # props, usage, theming
npx astryx template --list          # list page/block templates
npx astryx search "<keyword>"       # search components, hooks, docs

Generate context files for AI tools:

npx @astryxdesign/cli init --features agents --agent claude
npx @astryxdesign/cli init --features agents --agent cursor

Astryx also provides a built-in MCP server at https://astryx.atmeta.com/mcp for AI tool integration, exposing search() and get() tools for component discovery.

Browser Support

Astryx uses a 3-tier browser support system:

• Tier 1 (Full fidelity) — Baseline 2026, everything including CSS Anchor Positioning
• Tier 2 (Functional) — Baseline 2024, usable without anchor positioning
• Tier 3 (Best-effort) — Below Tier 2, won’t crash but colors may degrade

Always feature-detect rather than hardcoding version numbers.

Conclusion

Astryx provides everything you need to build production-grade UIs at scale: a comprehensive component library, semantic design tokens, flexible theming, multiple styling approaches, incremental migration support, internationalization, and AI tooling integration. The key to success is following the golden rules — let components handle layout, think frame-first, and always use semantic tokens over hardcoded values.