Getting Started with Astryx Design System: Setup, CLI, and AI Integration

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 tutorial walks you through installation, basic usage, and the key principles you need to know.

Installation

Install three packages — the core library, a theme, and the CLI:

npm install @astryxdesign/core @astryxdesign/theme-matcha @astryxdesign/cli

Then initialize the AI agent documentation:

npx astryx init

For full theme and page-building workflows, use --all:

npx astryx init --all

CSS Setup

In your app entry point (e.g., main.tsx or globals.css), import exactly three CSS files in this order:

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

The cascade layers are: reset.css loads in @layer reset, astryx.css loads in @layer astryx-base. If you use Tailwind or other global CSS, declare layer order explicitly.

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>
  );
}

Components are imported from per-category subpath entrypoints (e.g., @astryxdesign/core/Button, @astryxdesign/core/Layout), not a single barrel file. This keeps bundles small.

The Three Golden Rules

1. No <div> — Components Handle All Layout

Never use raw <div> for layout. Use Astryx layout components instead:

// BAD
<div style={{ display: 'flex', gap: '16px' }}>
  <Button label="OK" />
</div>

// GOOD
<HStack gap={2}>
  <Button label="OK" />
</HStack>

2. Frame-First Layout

Before writing any content, decide your app shell. Choose between AppShell (top/side nav), Layout + LayoutPanel (multi-pane), or a plain content column. Define region dimensions in pixels upfront:

import { AppShell, Sidebar, Main } from '@astryxdesign/core/AppShell';

<AppShell>
  <Sidebar width={240}>
    {/* nav menu */}
  </Sidebar>
  <Main>
    {/* main content */}
  </Main>
</AppShell>

3. Semantic Tokens Over Hardcoded Values

Never use raw hex, px, or rem values. Use CSS custom properties from the token system:

/* BAD */
.my-class {
  color: #fff;
  margin-top: 16px;
  border-radius: 8px;
}

/* GOOD */
.my-class {
  color: var(--color-text-primary);
  margin-top: var(--spacing-4);
  border-radius: var(--radius-element);
}

Available Themes

Astryx ships with 7 built-in themes:

Theme	Package	Description
Matcha	@astryxdesign/theme-matcha	Earthy green, fresh, recommended for beginners
Neutral	@astryxdesign/theme-neutral	Muted, minimal, system fonts
Butter	@astryxdesign/theme-butter	Golden surfaces, blue accents
Chocolate	@astryxdesign/theme-chocolate	Warm brown/beige, Fraunces typeface
Gothic	@astryxdesign/theme-gothic	Dark-only, deep blue-gray
Stone	@astryxdesign/theme-stone	Warm stone/slate, Montserrat + Figtree
Y2K	@astryxdesign/theme-y2k	Retro pop, periwinkle, holographic

CLI Essentials

Add a convenient npm script to your package.json:

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

Then use these commands to explore the system:

npm run astryx component --list       # list all 150+ components
npm run astryx component Button       # props, usage, theming for Button
npm run astryx docs                   # list all doc topics
npm run astryx docs tokens            # view tokens reference
npm run astryx template --list        # list available page/block templates
npm run astryx template <name> --skeleton  # study a template structure
npm run astryx search "<keyword>"     # search components, hooks, docs

The Discovery Workflow

Before writing any UI, run this workflow:

1. astryx build "<idea>" — describe your idea, get back a kit of closest page + blocks + components
2. astryx template --list — find a matching page pattern
3. astryx template <name> --skeleton — study the layout structure
4. astryx component <Name> — read props and examples for every component you use

AI Integration

Astryx has first-class AI agent support. Generate context files for your AI tool:

# Claude Code
npx @astryxdesign/cli init --features agents --agent claude

# Cursor
npx @astryxdesign/cli init --features agents --agent cursor

Use the --dense flag for token-efficient output (ideal for AI context windows):

npx astryx component Dialog --dense
npx astryx docs styling --dense
npx astryx docs tokens --dense

MCP Server

Astryx provides a built-in MCP (Model Context Protocol) server at https://astryx.atmeta.com/mcp. Any MCP-compatible AI tool can connect:

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

The server exposes two tools:

• search(query) — discover components, doc topics, templates
• get(name) — retrieve full documentation with props, usage, and examples

Anti-Patterns to Avoid

Bad	Good
<div> for layout	VStack, HStack, AppShell, LayoutPanel
style={{ color: '#fff' }}	xstyle on component, or className
color: #fff	var(--color-text-primary)
margin-top: 16px	var(--spacing-4)
Every item in a Card	Dense data → Table/List; Card → widgets only
<Badge> for decoration	Badge = counts/states; StatusDot/Token = status

Next Steps

Now that you have the basics down, move on to exploring the design token system — color, typography, spacing, and more. Each token category is documented via npx astryx docs <topic>.