# How Astryx Architecture Caters to AI Assistants: A Unified Design System > Discover how Astryx architecture empowers AI assistants with unified APIs and open internals for seamless code interaction, mirroring human developer workflows. Learn more! - Repository: [Meta/astryx](https://github.com/facebook/astryx) - Tags: architecture - Published: 2026-07-15 --- **Astryx is deliberately built as a single, cohesive system where unified APIs, open internals, and CLI-first tooling enable AI assistants to read, predict, and execute code using the same reference surface as human developers.** The facebook/astryx repository reimagines component library architecture by treating AI assistants as first-class citizens. Its design system eliminates the traditional gap between documentation and implementation, allowing large language models to consume the same TypeScript APIs and CLI utilities that human developers use. This architectural approach ensures that when an AI assistant generates or modifies Astryx components, it works from the exact source of truth found in `packages/core/src/components/` and related tooling. ## Unified API and CLI Surface for Human and Machine Access Astryx exposes all components, theming, and utilities through a single TypeScript API that the CLI also consumes. Because the CLI mirrors the library’s public surface, an AI assistant can reference the exact same documentation and code paths that a human developer uses. This eliminates knowledge gaps between the documented API and the underlying implementation. According to the repository structure, components live in `packages/core/src/components/`, while the CLI implementation provides programmatic access to the same functionality. When an AI assistant imports a component, it uses the same entry points as human developers: ```tsx // Human or AI can import a component directly import { Button } from '@astryxdesign/core'; ``` ## Open Internals and the Swizzle Command for Full Transparency The architecture does not hide implementation details behind opaque wrappers. Every building block—including styles, markers, and theme tokens—is exported directly from `packages/core/src/`. For AI assistants needing to inspect or modify underlying logic, the **swizzle** command ejects a component’s full source into the project. This transparency is critical for code generation tasks. Instead of guessing at internal implementations, an AI can read the exact code: ```bash # Swizzling a component to inspect its full source (useful for AI code generation) npx astryx swizzle Button # The command dumps the component's implementation into your project so the assistant # can read and modify the exact code instead of guessing. ``` ## Convention-Driven Architecture to Reduce LLM Hallucination Astryx employs strong, documented conventions for naming, props, and composition that make component behavior predictable. This predictability allows LLMs to infer how unfamiliar components work after learning a few examples, significantly reducing hallucination when generating code. The conventions are documented in [`packages/core/README.md`](https://github.com/facebook/astryx/blob/main/packages/core/README.md) and enforced across `packages/core/src/components/`. When an AI assistant encounters a new component, it can rely on consistent patterns—such as standard prop naming and composition rules—to generate accurate code without explicit training on every individual component. ## StyleX-Based Styling with Simple Override Mechanisms While styles are authored with StyleX, they remain invisible to consumers. AI assistants can rely on the simple `className` override mechanism—compatible with Tailwind, CSS modules, or custom CSS—without needing to understand StyleX internals. This abstraction is implemented in `packages/core/src/theme/` and demonstrated in the component API. Assistants can generate styling code using familiar patterns: ```tsx // Overriding styles without knowing StyleX internals ``` ## CLI-First Documentation and Scaffolding The CLI provides on-demand documentation, scaffolding, and theme utilities that AI assistants can invoke programmatically. Because an AI can execute the same commands a developer would—such as `astryx component` or `astryx docs`—it retrieves the same up-to-date reference surface. As documented in [`packages/cli/README.md`](https://github.com/facebook/astryx/blob/main/packages/cli/README.md), the CLI serves as the primary interface for both humans and machines: ```bash # Using the CLI to view docs for the same component npx astryx component Button --dense ``` Additionally, the [`scripts/sync-exports.js`](https://github.com/facebook/astryx/blob/main/scripts/sync-exports.js) file ensures the public API remains synchronized with documentation, guaranteeing that AI assistants reference current, accurate type definitions. ## Deterministic Project Structure for AI Navigation The repository organizes code into clear top-level folders (`apps/`, `packages/`, `internal/`) that make file discovery deterministic for AI agents. Components reside in `packages/core`, while the CLI, build plugins, and theme packages are co-located according to the structure outlined in [`README.md`](https://github.com/facebook/astryx/blob/main/README.md). This layout enables AI assistants to reliably locate source files, type definitions, and examples. Specialized AI tooling such as [`.claude/skills/create-component.md`](https://github.com/facebook/astryx/blob/main/.claude/skills/create-component.md) further provides concrete guidance on how assistants can generate components within this structure, while [`apps/docsite/src/content/blog/posts/how-astryx-works.md`](https://github.com/facebook/astryx/blob/main/apps/docsite/src/content/blog/posts/how-astryx-works.md) explains the LLM-first design philosophy behind the organization. ## Summary - **Unified API surface**: The TypeScript API and CLI share the same public interface, ensuring AI assistants use identical references to human developers. - **Open internals**: The `swizzle` command and direct exports in `packages/core/src/` allow AI to inspect and modify implementation details without abstraction barriers. - **Convention-driven design**: Predictable naming and composition patterns reduce hallucination when LLMs generate unfamiliar components. - **Style abstraction**: StyleX internals are hidden; AI can use standard `className` overrides with Tailwind or CSS modules. - **CLI parity**: AI assistants invoke `astryx component` and `astryx docs` to access the same live documentation and scaffolding tools as humans. - **Deterministic structure**: Clear folder separation (`apps/`, `packages/`, `internal/`) and synchronization via [`scripts/sync-exports.js`](https://github.com/facebook/astryx/blob/main/scripts/sync-exports.js) enable reliable file discovery. ## Frequently Asked Questions ### How does Astryx prevent AI assistants from generating outdated code? Astryx uses [`scripts/sync-exports.js`](https://github.com/facebook/astryx/blob/main/scripts/sync-exports.js) to keep the public API synchronized with documentation automatically. Since AI assistants can invoke the CLI (`npx astryx component`) to retrieve current type definitions and usage examples from `packages/core/src/components/`, they always reference the latest implementation rather than static documentation. ### What is the "swizzle" command and why is it important for AI code generation? The `swizzle` command, accessible via `npx astryx swizzle [Component]`, ejects a component's full source code into the consumer's project. This allows AI assistants to inspect the exact implementation details in `packages/core/src/components/` rather than inferring behavior from documentation, enabling accurate modifications and extensions. ### Can AI assistants use Astryx without understanding StyleX? Yes. While Astryx uses StyleX internally, the architecture exposes only standard `className` props for styling. AI assistants can generate styling code using Tailwind, CSS modules, or custom CSS classes without requiring knowledge of StyleX internals, as the complexity is abstracted away in `packages/core/src/theme/`. ### How does the project structure help AI assistants navigate the codebase? The repository follows a strict folder convention with `apps/`, `packages/`, and `internal/` directories. Components are located in `packages/core/src/components/`, CLI tools in `packages/cli/`, and AI-specific guidance in `.claude/skills/`. This deterministic layout allows AI assistants to reliably locate source files, types, and scaffolding examples without searching.