How facebook/astryx works
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: core Core · cli CLI · templates Templates · scripts Scripts
Components 20
Packages
Published libraries and theme distributions
- Core · Primary React component library, hooks, and theme system for consumer use.
packages/core - Theme engine · Core theming model, token generation, derived vars, and media/syntax themes.
packages/core/src/theme - Table system · Composable table core with filtering, pagination, sorting, selection, resize, and sticky-column plugins.
packages/core/src/Table - Chat system · Chat UI surface with composer, message pipeline, dictation, tokenization, and streaming hooks.
packages/core/src/Chat - Nav shells · Top navigation, side navigation, mobile nav, menus, and related navigation primitives.
packages/core/src/TopNav - CLI · Discovery, docs, scaffolding, templates, codemods, doctor checks, and JSON contracts.
packages/cli - Templates · Large catalog of reusable component blocks, pages, and theme templates.
packages/cli/templates - Codemods · Versioned transforms that migrate older Astryx APIs to newer conventions.
packages/cli/src/codemods - Build tools · Build plugins and adapters for Babel, Next.js, and Vite source-based builds.
packages/build - Themes · Published theme packages that wrap or extend the core theme model.
packages/themes - Lab · Experimental components for charts, schedule, code editor, SVG icons, sankey, stepper, and 3D visuals.
packages/lab - Vega · Separate Vega and Vega-Lite wrapper package for chart integrations.
packages/vega
Apps
Documentation, playground, demos, and examples
- Docsite · Public Next.js docs and marketing site rendering component docs, blog, changelog, playground, search, and MCP.
apps/docsite - Sandbox · Internal visual playground for layouts, palettes, docs previews, and theme audits.
apps/sandbox - Storybook · Story-driven component demos for core and lab packages.
apps/storybook - Examples · 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 · Repo-specific lint rules that enforce component and documentation conventions.
internal/eslint-plugin-astryx - Vibe tests · Screenshot, accessibility, and report-generation harness used to measure design quality.
internal/vibe-tests
Automation
Repo-wide scripts and CI orchestration
- Scripts · Repo-wide automation for builds, syncing, docs generation, export verification, and branch cleanup.
scripts - CI workflows · Continuous integration, smoke tests, releases, deploys, linting, and preview cleanup workflows.
.github/workflows
Connections 26
- 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.