Astryx Design System

Astryx is composed of several integrated systems:

• Distribution: Supports a simple pre-built stylesheet path or an advanced path building from TypeScript + StyleX source for optimized tree-shaking.
• Theming: A declarative configuration system for colors, typography, motion, and spacing that can customize component parts and variants.
• CLI: An operational interface for browsing documentation, scaffolding, building themes, and running automated upgrades. It is also designed to provide a reliable API reference for AI assistants.
• Vibe Tests: An evaluation harness used to measure how effectively humans and AI can build with the library.

The Astryx design system is distributed via several npm packages categorized by their purpose:

• Core UI & Utilities: @astryxdesign/core provides the fundamental UI components, theme system, and utilities.
• CLI Tooling: @astryxdesign/cli includes tools for component documentation, templates, scaffolding, and codemods.
• Build Infrastructure: @astryxdesign/build contains build plugins for StyleX source builds (supporting Babel, PostCSS, and Vite).
• Visual Themes: @astryxdesign/theme-* packages provide various visual styles such as default, neutral, daily, brutalist, meta, and whatsapp.
• Data Visualization (Canary only):
  • @astryxdesign/vega: A Vega/Vega-Lite chart wrapper.
  • @astryxdesign/charts: Themeable chart component wrappers over a peer engine.

The @astryxdesign/core package provides the foundational source code for core UI components. It serves as the central repository for components, hooks, types, and styling utilities used to build interfaces with Astryx. Key features include:

• Public API: Re-exported via index.ts.
• Styling: Includes a base CSS reset (reset.css) and centralized namespace-prefixing utilities (naming.ts) to ensure consistent CSS classes, data attributes, and CSS variables.
• Components: Includes ready-to-use components like Button with support for variants and loading states.

Astryx is an open-source, AI-fluent design system built on React and StyleX. It is designed to provide production-ready components while allowing for deep customization through token-level theming (color, typography, radius, motion) without inheriting a fixed brand identity.

Key features include:

• 150+ accessible components.
• Brand-level theming and dark mode support.
• Ready-to-ship templates.
• A dedicated CLI.
• AI-operable structure designed for both human developers and AI agents.

The /apps directory contains various application packages used for development, documentation, and visual testing of the Astryx design system. Depending on your needs, you can use different reference implementations:

• Documentation: The docs/ package hosts the official documentation website.
• Next.js Integration: Use example-nextjs/ as a reference for source distribution consumers using a Babel + PostCSS setup.
• Vite Integration: Use example-vite/ as a reference for source distribution consumers using the unplugin path.
• Local Development: The sandbox/ package provides a local development and testing environment.
• Visual Testing: The storybook/ package provides a Storybook environment for component development and visual documentation.

When using Astryx with Tailwind CSS, the system utilizes:

• Tailwind CSS utility classes for layout and custom styling.
• Astryx Tailwind bridge tokens (e.g., bg-surface, text-primary) to access design tokens.
• React 19.

The internal/vibe-tests/ directory is organized as follows:

• test-sets/: Contains the JSON prompt batteries.
• src/: Contains the core logic:
  • setup-nightly.mjs: Sets up the 4-target nightly environment.
  • universal-eval.ts: Performs static analysis scoring across 5 dimensions.
  • universal-aggregate.ts: Aggregates scores.
  • universal-compare.ts: Compares results across targets.
  • build-previews.ts: Compiles TSX to HTML and runs tsc.
  • screenshot-previews.ts: Generates Playwright screenshots.
  • build-report.ts: Generates a Vite HTML report.
  • deploy-report.ts: Deploys reports to GitHub Pages.
• .baseline/: Contains real shadcn/ui components used for baseline tsc checks.
• results/: Stores iteration results (gitignored).

Astryx components follow a lifecycle where they move from Lab to Core. It is important to choose the right package based on your stability requirements:

• @astryxdesign/lab: Experimental components. They have basic props and may include stories, but the API is subject to change. They are not accessibility-hardened, not fully themed, and offer no stability promise. They are only available via the @canary tag.
• @astryxdesign/core: Stable components. These include full keyboard/a11y support, hover guards, theming stories, status states, and spec compliance. They are shipped via the latest tag.

The CLI Discovery Vibe Test is a proposed experiment designed to measure how reliably AI agents discover the Astryx CLI when they land in a project that has only installed @astryxdesign/core without running astryx init.

It evaluates different 'passive channels' (methods of informing the agent about the CLI without requiring user action) to find the minimal set of features that can be shipped in an npm package to ensure agents consistently use the CLI instead of hallucinating component props or APIs.

Key Metrics:

• Discovery Funnel: Awareness $\rightarrow$ Invocation $\rightarrow$ Init $\rightarrow$ Doc retrieval.
• Reliability Rate: The fraction of independent runs where an agent successfully discovers and uses the CLI.
• Downstream Quality: Whether CLI discovery leads to better code correctness, accessibility, and lower hallucination rates.