# facebook/astryx architecture

> Architecture diagram of the GitHub repository facebook/astryx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebook/astryx
- Repository: https://github.com/facebook/astryx

## Overview

Astryx is a pnpm monorepo centered on a published design-system core, with surrounding tooling that generates docs, templates, themes, and verification artifacts.

1. **Primary product surface**
   The main runtime package is `packages/core`, which exports the React component library, hooks, and theme system. This is the source of truth for most UI behavior. Consumers install prebuilt CSS and import typed React components; they do not need a custom build plugin or styling runtime.

2. **Core library structure**
   `packages/core/src` is organized by feature area: components such as `Button`, `Dialog`, `Table`, `TopNav`, `Chat`, `Calendar`, and shared primitives like `theme`, `hooks`, `utils`, and `BaseProps`. Many components have companion context files and helper hooks, which indicates a composition-heavy design rather than a single monolithic API.

3. **Theme system boundary**
   `packages/core/src/theme` contains the CSS-variable-driven theming model, including token generation, derived vars, media themes, and syntax themes. Theme packages in `packages/themes/*` are thin distributions of theme definitions that wrap or extend the core theme model. This means brand customization flows through theme overrides, not component forking.

4. **Doc/source coupling**
   Core components include `.doc.mjs` files alongside implementation files. These doc modules are consumed by docs generation and CLI tooling, so documentation is treated as a first-class artifact tied directly to component source. The repo also contains a large number of tests validating naming, behavior, and documentation conventions.

5. **CLI as the distribution and authoring tool**
   `packages/cli` is the command-line layer for discovery, docs, templates, scaffolding, codemods, and “doctor” checks. It reads component/package metadata, resolves themes, emits JSON contracts, and can generate or transform source. This package is the main bridge between the design system and developer workflows.

6. **Template and codemod pipeline**
   The CLI ships a very large template catalog under `packages/cli/templates`, covering component blocks, full pages, and themes. It also includes codemods that migrate older Astryx APIs to newer ones. The architecture here is “author once, then reuse”: canonical example code is generated, documented, and kept in sync with API evolution.

7. **Build tooling package**
   `packages/build` provides build plugins for StyleX-based source builds, with adapters for Babel, Next.js, and Vite. This is infrastructure for people building Astryx itself or integrating it in source-based environments, not the default consumer path. It sits between source authoring and bundling, while end users mostly consume compiled output.

8. **Experimental/adjacent packages**
   `packages/lab` contains experimental components such as charting, schedule, SVG icon, sankey, stepper, three-dimensional visualizations, and richer data-visualization primitives. `packages/vega` is a separate Vega/Vega-Lite wrapper. These are not the core design-system surface, but they extend Astryx into data/visualization scenarios and are used by internal apps and examples.

9. **Documentation and marketing applications**
   `apps/docsite` is the Next.js documentation and marketing site. It renders component docs, blog content, changelog pages, playgrounds, search, and an MCP endpoint. It pulls from core package metadata, content markdown, and generated data, so it acts as the public-facing read model for the repo.

10. **Interactive authoring surfaces**
   `apps/sandbox` is a Next.js-based internal playground for exploring layouts, palettes, documentation previews, and theme audits. It is used to prototype and validate patterns visually. `apps/storybook` provides story-driven component demos for the core and lab packages. Together these surfaces are the visual validation layer for the design system.

11. **Example consumer apps**
   The `apps/example-*` projects are small reference applications for different stacks: Next.js, Vite, Tailwind, and StyleX/source-based setups. They demonstrate how Astryx is consumed in real projects and help verify integration boundaries across runtimes and styling approaches.

12. **Internal quality and measurement tooling**
   `internal/eslint-plugin-astryx` encodes repo-specific conventions as lint rules. `internal/test-utils` supports shared test setup. `internal/vibe-tests` is a separate evaluation harness with screenshotting, accessibility manifests, and report generation. These internal tools show that component quality, accessibility, and design consistency are continuously measured, not just manually reviewed.

13. **Automation and release flow**
   The root `scripts/` directory contains repo-wide automation for CSS builds, UMD output, package source syncing, export verification, changelog formatting, theme generation, token doc generation, and branch cleanup. GitHub Actions in `.github/workflows` run CI, linting, release, deploys, smoke tests, and preview cleanup. Releases are managed with changesets, which matches the multi-package structure.

14. **Data and dependency flow**
   The dominant flow is: component source in `packages/core` and `packages/lab` feeds docs, stories, templates, and examples; CLI tooling consumes those same sources and docs for scaffolding, discovery, and codemods; themes provide CSS-variable overrides that layer on top of core; apps render the resulting packages for documentation, testing, and previews. The repo is designed so source, docs, templates, and verification stay synchronized.

15. **Architectural boundaries to preserve**
   Keep `packages/core` as the stable public API boundary, `packages/cli` as the developer workflow boundary, `packages/themes` as brand-layer overrides, and `apps/*` as consumption/validation surfaces. Internal tooling should remain outside the published API boundary so the repo can evolve conventions without forcing consumer changes.

Main entry points: [`packages/core`](https://github.com/facebook/astryx/tree/main/packages/core) (Core), [`packages/cli`](https://github.com/facebook/astryx/tree/main/packages/cli) (CLI), [`packages/cli/templates`](https://github.com/facebook/astryx/tree/main/packages/cli/templates) (Templates), [`scripts`](https://github.com/facebook/astryx/tree/main/scripts) (Scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_packages["Packages"]
  node_packages_core["Core<br/>design-system API"]
  node_packages_core_theme["Theme engine<br/>css-vars theme"]
  node_packages_core_table["Table system<br/>data table"]
  node_packages_core_chat["Chat system<br/>chat composition"]
  node_packages_core_nav["Nav shells<br/>navigation components"]
  node_packages_cli["CLI<br/>authoring tool"]
  node_packages_cli_templates["Templates<br/>scaffold catalog"]
  node_packages_cli_codemods["Codemods<br/>migration transforms"]
  node_packages_build["Build tools<br/>stylex build infra"]
  node_packages_themes["Themes"]
  node_packages_lab["Lab<br/>experimental UI"]
  node_packages_vega["Vega<br/>chart wrapper"]
end

subgraph group_group_apps["Apps"]
  node_apps_docsite["Docsite<br/>docs app"]
  node_apps_sandbox["Sandbox<br/>playground app"]
  node_apps_storybook["Storybook<br/>demo app"]
  node_apps_examples["Examples<br/>consumer apps"]
end

subgraph group_group_internal["Internal"]
  node_internal_lint["Lint rules<br/>eslint plugin"]
  node_internal_vibe["Vibe tests<br/>evaluation harness"]
end

subgraph group_group_automation["Automation"]
  node_automation_scripts["Scripts<br/>repo automation"]
  node_automation_ci["CI workflows<br/>github actions<br/>[workflows]"]
end

node_packages_core -->|"exports theme"| node_packages_core_theme
node_packages_core -->|"includes"| node_packages_core_table
node_packages_core -->|"includes"| node_packages_core_chat
node_packages_core -->|"includes"| node_packages_core_nav
node_packages_themes -->|"extends"| node_packages_core_theme
node_packages_cli -->|"reads source"| node_packages_core
node_packages_cli -->|"resolves themes"| node_packages_themes
node_packages_cli -->|"serves templates"| node_packages_cli_templates
node_packages_cli -->|"runs codemods"| node_packages_cli_codemods
node_packages_cli_templates -->|"references APIs"| node_packages_core
node_packages_cli_templates -->|"uses themes"| node_packages_core_theme
node_packages_build -->|"supports source builds"| node_packages_core
node_apps_docsite -->|"renders docs"| node_packages_core
node_apps_docsite -->|"shows generated data"| node_packages_cli
node_apps_sandbox -->|"prototypes against"| node_packages_core
node_apps_sandbox -->|"audits themes"| node_packages_themes
node_apps_storybook -->|"demos components"| node_packages_core
node_apps_storybook -->|"demos lab"| node_packages_lab
node_apps_examples -->|"consumes"| node_packages_core
node_apps_examples -->|"uses build infra"| node_packages_build
node_internal_lint -->|"enforces conventions"| node_packages_core
node_internal_vibe -->|"evaluates"| node_packages_core
node_automation_scripts -->|"builds and verifies"| node_packages_core
node_automation_scripts -->|"syncs tooling"| node_packages_cli
node_automation_ci -->|"runs"| node_automation_scripts
node_automation_ci -->|"executes checks"| node_internal_vibe

click node_packages_core "https://github.com/facebook/astryx/tree/main/packages/core"
click node_packages_core_theme "https://github.com/facebook/astryx/tree/main/packages/core/src/theme"
click node_packages_core_table "https://github.com/facebook/astryx/tree/main/packages/core/src/Table"
click node_packages_core_chat "https://github.com/facebook/astryx/tree/main/packages/core/src/Chat"
click node_packages_core_nav "https://github.com/facebook/astryx/tree/main/packages/core/src/TopNav"
click node_packages_cli "https://github.com/facebook/astryx/tree/main/packages/cli"
click node_packages_cli_templates "https://github.com/facebook/astryx/tree/main/packages/cli/templates"
click node_packages_cli_codemods "https://github.com/facebook/astryx/tree/main/packages/cli/src/codemods"
click node_packages_build "https://github.com/facebook/astryx/tree/main/packages/build"
click node_packages_themes "https://github.com/facebook/astryx/tree/main/packages/themes"
click node_packages_lab "https://github.com/facebook/astryx/tree/main/packages/lab"
click node_packages_vega "https://github.com/facebook/astryx/tree/main/packages/vega"
click node_apps_docsite "https://github.com/facebook/astryx/tree/main/apps/docsite"
click node_apps_sandbox "https://github.com/facebook/astryx/tree/main/apps/sandbox"
click node_apps_storybook "https://github.com/facebook/astryx/tree/main/apps/storybook"
click node_apps_examples "https://github.com/facebook/astryx/tree/main/apps/example-nextjs"
click node_internal_lint "https://github.com/facebook/astryx/tree/main/internal/eslint-plugin-astryx"
click node_internal_vibe "https://github.com/facebook/astryx/tree/main/internal/vibe-tests"
click node_automation_scripts "https://github.com/facebook/astryx/tree/main/scripts"
click node_automation_ci "https://github.com/facebook/astryx/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_packages_core,node_packages_core_theme,node_packages_core_table,node_packages_core_chat,node_packages_core_nav,node_packages_cli,node_packages_cli_templates,node_packages_cli_codemods,node_packages_build,node_packages_themes,node_packages_lab,node_packages_vega toneBlue
class node_apps_docsite,node_apps_sandbox,node_apps_storybook,node_apps_examples toneAmber
class node_internal_lint,node_internal_vibe toneMint
class node_automation_scripts,node_automation_ci toneRose
```

## Components

### Packages

Published libraries and theme distributions

- [Core](https://github.com/facebook/astryx/tree/main/packages/core): design-system API · Primary React component library, hooks, and theme system for consumer use. · `packages/core`
- [Theme engine](https://github.com/facebook/astryx/tree/main/packages/core/src/theme): css-vars theme · Core theming model, token generation, derived vars, and media/syntax themes. · `packages/core/src/theme`
- [Table system](https://github.com/facebook/astryx/tree/main/packages/core/src/Table): data table · Composable table core with filtering, pagination, sorting, selection, resize, and sticky-column plugins. · `packages/core/src/Table`
- [Chat system](https://github.com/facebook/astryx/tree/main/packages/core/src/Chat): chat composition · Chat UI surface with composer, message pipeline, dictation, tokenization, and streaming hooks. · `packages/core/src/Chat`
- [Nav shells](https://github.com/facebook/astryx/tree/main/packages/core/src/TopNav): navigation components · Top navigation, side navigation, mobile nav, menus, and related navigation primitives. · `packages/core/src/TopNav`
- [CLI](https://github.com/facebook/astryx/tree/main/packages/cli): authoring tool · Discovery, docs, scaffolding, templates, codemods, doctor checks, and JSON contracts. · `packages/cli`
- [Templates](https://github.com/facebook/astryx/tree/main/packages/cli/templates): scaffold catalog · Large catalog of reusable component blocks, pages, and theme templates. · `packages/cli/templates`
- [Codemods](https://github.com/facebook/astryx/tree/main/packages/cli/src/codemods): migration transforms · Versioned transforms that migrate older Astryx APIs to newer conventions. · `packages/cli/src/codemods`
- [Build tools](https://github.com/facebook/astryx/tree/main/packages/build): stylex build infra · Build plugins and adapters for Babel, Next.js, and Vite source-based builds. · `packages/build`
- [Themes](https://github.com/facebook/astryx/tree/main/packages/themes): brand themes · Published theme packages that wrap or extend the core theme model. · `packages/themes`
- [Lab](https://github.com/facebook/astryx/tree/main/packages/lab): experimental UI · Experimental components for charts, schedule, code editor, SVG icons, sankey, stepper, and 3D visuals. · `packages/lab`
- [Vega](https://github.com/facebook/astryx/tree/main/packages/vega): chart wrapper · Separate Vega and Vega-Lite wrapper package for chart integrations. · `packages/vega`

### Apps

Documentation, playground, demos, and examples

- [Docsite](https://github.com/facebook/astryx/tree/main/apps/docsite): docs app · Public Next.js docs and marketing site rendering component docs, blog, changelog, playground, search, and MCP. · `apps/docsite`
- [Sandbox](https://github.com/facebook/astryx/tree/main/apps/sandbox): playground app · Internal visual playground for layouts, palettes, docs previews, and theme audits. · `apps/sandbox`
- [Storybook](https://github.com/facebook/astryx/tree/main/apps/storybook): demo app · Story-driven component demos for core and lab packages. · `apps/storybook`
- [Examples](https://github.com/facebook/astryx/tree/main/apps/example-nextjs): consumer apps · Reference applications for Next.js, Vite, Tailwind, and StyleX/source-based integration paths. · `apps/example-nextjs`

### Internal

Repo-specific quality and evaluation tooling

- [Lint rules](https://github.com/facebook/astryx/tree/main/internal/eslint-plugin-astryx): eslint plugin · Repo-specific lint rules that enforce component and documentation conventions. · `internal/eslint-plugin-astryx`
- [Vibe tests](https://github.com/facebook/astryx/tree/main/internal/vibe-tests): evaluation harness · Screenshot, accessibility, and report-generation harness used to measure design quality. · `internal/vibe-tests`

### Automation

Repo-wide scripts and CI orchestration

- [Scripts](https://github.com/facebook/astryx/tree/main/scripts): repo automation · Repo-wide automation for builds, syncing, docs generation, export verification, and branch cleanup. · `scripts`
- [CI workflows](https://github.com/facebook/astryx/blob/main/.github/workflows): github actions · Continuous integration, smoke tests, releases, deploys, linting, and preview cleanup workflows. · `.github/workflows`

## Connections

- Core → Theme engine: exports theme · Core exposes the CSS-variable theme system used by consumers and theme packages.
- Core → Table system: includes · Table is a major subsystem inside the public core API.
- Core → Chat system: includes · Chat is a major subsystem inside the public core API.
- Core → Nav shells: includes · Navigation shells are a major subsystem inside the public core API.
- Themes → Theme engine: extends · Published themes layer brand variants on top of the core theme model.
- CLI → Core: reads source · CLI discovers components, docs, hooks, and metadata from core.
- CLI → Themes: resolves themes · CLI can resolve and emit theme-aware artifacts.
- CLI → Templates: serves templates · CLI uses the template catalog for scaffolding and generated examples.
- CLI → Codemods: runs codemods · CLI ships migrations that transform older Astryx usage.
- Templates → Core: references APIs · Templates are authored against the canonical component API.
- Templates → Theme engine: uses themes · Theme templates and previews depend on the core theme model.
- Build tools → Core: supports source builds · Build tooling adapts source-based builds for Astryx itself and integrators.
- Docsite → Core: renders docs · Docsite reads package metadata, docs modules, and component source contracts.
- Docsite → CLI: shows generated data · Docsite surfaces CLI-produced docs, templates, and generated metadata.
- Sandbox → Core: prototypes against · Sandbox previews layouts, themes, and component behavior from core.
- Sandbox → Themes: audits themes · Sandbox is used to inspect and validate theme variants.
- Storybook → Core: demos components · Storybook exercises the stable core surface.
- Storybook → Lab: demos lab · Storybook also showcases experimental lab components.
- Examples → Core: consumes · Example apps demonstrate consumer integration of the design system.
- Examples → Build tools: uses build infra · Source-based examples exercise the build plugin path.
- Lint rules → Core: enforces conventions · Custom lint rules encode design-system-specific API and docs rules.
- Vibe tests → Core: evaluates · Vibe tests compare Astryx implementations and measure quality/accessibility.
- Scripts → Core: builds and verifies · Repo scripts generate CSS, UMD output, exports, tokens, and docs artifacts.
- Scripts → CLI: syncs tooling · Scripts support CLI-generated docs, themes, templates, and contract checks.
- CI workflows → Scripts: runs · Workflows execute repo automation in CI and release pipelines.
- CI workflows → Vibe tests: executes checks · CI runs accessibility, screenshot, and preview verification jobs.
