# How to Leverage Astryx's Design System for Large-Scale Applications

> Leverage Astryx's modular React design system with atomic CSS-in-JS and token-based themes to ensure consistent UI at scale for micro-frontends and monorepos.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-15

---

**Astryx provides a modular React-based design system with atomic CSS-in-JS via StyleX, a token-based theme engine, and a discovery CLI that enables consistent UI at scale across micro-frontends and monorepos.**

To leverage Astryx's design system for large-scale applications, teams must understand its three-pillar architecture implemented in the `facebook/astryx` repository. The system combines a strictly typed component library (`@astryxdesign/core`), a CSS custom property-driven theme engine, and the StyleX runtime to deliver atomic, conflict-free styling. This architecture supports both zero-build CDN deployments and compile-time optimization for enterprise React applications.

## Core Architecture of Astryx

Astryx is built around three foundational pillars that make it suitable for enterprise-grade applications. Understanding these pillars is essential for implementing the system correctly across distributed teams.

### Component Library

All UI elements reside under `@astryxdesign/core` and include components like `Button`, `Card`, and `TopNav`. Each component is fully typed and documented in dedicated `*.doc.mjs` files within the source tree.

Teams can discover component APIs using the Astryx CLI:

```bash
astryx component Button --dense

```

This command outputs a concise prop table directly from the source documentation in [`packages/core/README.md`](https://github.com/facebook/astryx/blob/main/packages/core/README.md), ensuring developers always reference the single source of truth rather than outdated documentation.

### Theme System

Astryx ships with pre-built themes such as `@astryxdesign/theme-neutral` and `@astryxdesign/themes/*`. The `ThemeProvider` component injects CSS custom properties (tokens) at runtime, exposing them as native CSS variables.

This centralized token management means a brand-wide redesign requires only a single theme change, propagating instantly to every component in the codebase. The theme system is documented in `packages/themes/*/README.md`.

### StyleX Runtime

Components use `stylex.create` and `stylex.props` to generate atomic CSS classes. According to the source code in [`packages/core/README.md`](https://github.com/facebook/astryx/blob/main/packages/core/README.md), this runtime can be bundled as UMD for CDN use or processed at compile-time via `@stylexjs/unplugin`.

Atomic classes provide deterministic specificity that prevents cascade wars, while the optional compile-time path removes runtime overhead for production builds.

## Integration Strategies for Large-Scale Applications

Astryx supports multiple integration patterns to accommodate different architectural constraints in large organizations.

### Zero-Build Integration via CDN

For applications that cannot modify their build pipeline, Astryx provides a pre-built UMD bundle ([`dist/astryx.umd.js`](https://github.com/facebook/astryx/blob/main/dist/astryx.umd.js)) referenced in the [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md). This bundle loads React and ReactDOM as peer globals, allowing you to drop the library into any existing React app with a simple script tag:

```html
<script src="https://cdn.jsdelivr.net/npm/@astryxdesign/core/dist/astryx.umd.js"></script>

```

This approach is ideal for legacy applications or micro-frontends with isolated deployment cycles.

### Compile-Time Integration with Vite or Next.js

When you control the build pipeline, import the source directly from `@astryxdesign/core` and configure the StyleX unplugin. The [`apps/example-vite/README.md`](https://github.com/facebook/astryx/blob/main/apps/example-vite/README.md) demonstrates the exact configuration needed to extract static CSS files and eliminate the runtime cost.

The CLI command `astryx doctor` verifies that your Vite or Next.js configuration supports the modern CSS features Astryx requires, such as `light-dark()` color functions.

### Tailwind Bridge for Hybrid Workflows

Teams using Tailwind can consume Astryx tokens directly via the bridge stylesheet at `@astryxdesign/core/tailwind-theme.css`. This registers all Astryx custom properties as Tailwind utilities, documented in [`apps/example-nextjs-tailwind/README.md`](https://github.com/facebook/astryx/blob/main/apps/example-nextjs-tailwind/README.md).

The bridge respects layer ordering, ensuring Astryx's atomic classes maintain priority when necessary while allowing Tailwind to handle layout utilities.

## Scaling Patterns for Enterprise Teams

Implementing Astryx at scale requires specific patterns for bundle optimization, micro-frontend coordination, and CI validation.

### Managing Bundle Size

Use the pre-built UMD for rapid prototyping and internal tools, then switch to source imports with StyleX extraction for production releases. This dual approach keeps initial bundles small while maximizing performance for customer-facing applications.

### Coordinating Micro-Frontends

Wrap each micro-frontend in its own `ThemeProvider` and ensure the Astryx base layer (`astryx-base`) loads after any local CSS. This guarantees proper cascade order across independently deployed applications. The `ThemeProvider` architecture supports nested themes without CSS variable collisions.

### CI/CD Validation

Add `astryx doctor --ci` to your continuous integration pipeline to catch configuration drift. Enable `eslint-plugin-astryx` (documented in [`internal/eslint-plugin-astryx/README.md`](https://github.com/facebook/astryx/blob/main/internal/eslint-plugin-astryx/README.md)) to enforce token usage and prevent hard-coded style values that violate design system standards.

### Component Discovery at Scale

Run `astryx init --features agents` on a regular schedule and commit the generated [`AGENTS.md`](https://github.com/facebook/astryx/blob/main/AGENTS.md) file. This keeps teams aware of new components and deprecations across a large organization, functioning as a living index of the design system.

## Practical Implementation Examples

The following patterns demonstrate how to integrate Astryx into large-scale React applications.

### Theme Switching Implementation

```tsx
import { ThemeProvider, useTheme } from '@astryxdesign/theme-neutral';
import { Switch } from '@astryxdesign/core';

function ThemeToggle() {
  const { theme, setTheme } = useTheme(); // 'light' | 'dark'
  
  return (
    <Switch
      checked={theme === 'dark'}
      onChange={() => setTheme(theme === 'light' ? 'dark' : 'light')}
      label="Dark mode"
    />
  );
}

export default function App() {
  return (
    <ThemeProvider>
      <ThemeToggle />
    </ThemeProvider>
  );
}

```

### Tailwind Integration Pattern

```tsx
import '@astryxdesign/core/tailwind-theme.css';
import { Card, Button } from '@astryxdesign/core';

export default function Dashboard() {
  return (
    <div className="grid gap-4 p-6 md:grid-cols-2 lg:grid-cols-4">
      <Card className="p-4" elevation="low">
        <h2 className="text-xl font-bold mb-2">Analytics</h2>
        <Button variant="secondary">View Report</Button>
      </Card>
    </div>
  );
}

```

### Next.js Server-Side Rendering Setup

```tsx
// pages/_app.tsx
import '@astryxdesign/core/dist/astryx.css';
import '@astryxdesign/theme-neutral/dist/theme.css';
import { ThemeProvider } from '@astryxdesign/theme-neutral';
import type { AppProps } from 'next/app';

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <ThemeProvider>
      <Component {...pageProps} />
    </ThemeProvider>
  );
}

```

For compile-time optimization in Next.js, exclude Astryx from Vite's dependency pre-bundling and configure the StyleX unplugin as shown in [`apps/example-vite/README.md`](https://github.com/facebook/astryx/blob/main/apps/example-vite/README.md).

## Summary

- **Astryx's three-pillar architecture** combines `@astryxdesign/core` components, a CSS custom property theme system, and StyleX atomic CSS to prevent styling conflicts at scale.
- **Multiple integration paths** support both zero-build CDN deployments and optimized compile-time workflows via the StyleX unplugin.
- **The Tailwind bridge** enables incremental adoption, allowing teams to maintain existing utility classes while migrating to Astryx components.
- **CLI tooling** (`astryx doctor`, `astryx component`) provides automated discovery and CI validation that keeps large teams synchronized.
- **Micro-frontend support** through nested `ThemeProvider` instances and explicit CSS layer ordering ensures consistent theming across distributed applications.

## Frequently Asked Questions

### How does Astryx handle CSS specificity in large codebases?

Astryx uses the StyleX runtime to generate atomic CSS classes via `stylex.create` and `stylex.props`. This approach produces deterministic specificity that eliminates cascade wars common in large-scale applications. Because each style rule is atomic, the risk of unintended overrides from legacy CSS or other micro-frontends is minimized.

### Can Astryx be used without modifying our existing build pipeline?

Yes. According to [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md), Astryx provides a pre-built UMD bundle ([`dist/astryx.umd.js`](https://github.com/facebook/astryx/blob/main/dist/astryx.umd.js)) that can be loaded via CDN with a standard script tag. This bundle expects React and ReactDOM as peer globals, making it suitable for legacy applications or environments where build configuration changes are not possible.

### How do we ensure design token consistency across multiple teams?

Astryx tokens are exposed as CSS custom properties injected by the `ThemeProvider`. Teams should reference these via `var(--color-...)` or use the Tailwind bridge (`@astryxdesign/core/tailwind-theme.css`) to access them as utility classes. Additionally, enabling `eslint-plugin-astryx` (documented in [`internal/eslint-plugin-astryx/README.md`](https://github.com/facebook/astryx/blob/main/internal/eslint-plugin-astryx/README.md)) prevents hard-coded values by enforcing token usage at the code level.

### What is the recommended way to discover available components and props?

Use the Astryx CLI command `astryx component <Name> --dense` to output prop tables directly from the component's `*.doc.mjs` file. For broader discovery, `astryx docs` surfaces the full design system wiki, while `astryx init --features agents` generates an [`AGENTS.md`](https://github.com/facebook/astryx/blob/main/AGENTS.md) index that teams can commit to track available components and deprecations.