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

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:

astryx component Button --dense

This command outputs a concise prop table directly from the source documentation in 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, 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) referenced in the 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:

<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 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.

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

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

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

// 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.

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, Astryx provides a pre-built UMD bundle (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) 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 index that teams can commit to track available components and deprecations.

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