Home

Astryx Wiki

Astryx is a design system for building internal tools. This wiki documents architecture decisions, design philosophy, and research that shaped the system.

Quick Links

Philosophy & Architecture

• Astryx Philosophy — Why Astryx exists, what we learned, and the principles that emerged
• System Architecture — Technical architecture: customization layers, tokens, AI-native design
• Container Padding System — How containers communicate padding to bleed children (Table, Divider, Section)
• Theming Infrastructure — Theme system internals: defineTheme, CSS custom properties, layer ordering, subcomponent overrides
• Chart System Architecture — Data visualization architecture: correctness guarantees, composition patterns, and design choices
• Distribution — Packages, versioning, source and dist bundles, pre-compiled CSS
• Docsite Architecture — Next.js docsite: generated registries, .doc.mjs content pipeline, component playgrounds

Contributing

• Contributing — How contributions work, what we accept, the RFC process, and what to expect
• Contributing with AI Assistants — How to contribute with Navi or other AI assistants. Start here if you're new.
• Contributing Templates — How to build and register full-page templates for the sandbox and CLI.
• Blog Review Rubric — How we review docsite blog posts: type-aware profiles, an accuracy gate, and a craft/voice check.
• Component Lifecycle — End-to-end guide: specification → build → hardening → ongoing maintenance
• Component Specification Protocol — How a new component is researched and specified before anyone builds it
• Component Build Protocol — The phase-by-phase build, from scaffold to the self-review on the PR
• Component Authoring Guide — File structure, StyleX patterns, token usage, and conventions
• Accessibility Checklist — The ten-item accessibility bar; a hard requirement for graduating a component to core
• Template Assets — Reusable demo media for templates and blocks, and when to add more
• Vibe Tests — Start here for vibe testing: which of the three workflows you want
• Designing Vibe Tests — The generic playbook for designing a vibe test for anything
• Vibe Test Scores — The running scoreboard from the nightly evaluation
• Testing Example Apps — How to test example apps as an external consumer

Decisions

• API Conventions — Naming, props, composition, and styling conventions for all components
• Design Conventions — Visual and interaction conventions: the intention behind token choices, state representations, and how design quality is evaluated
• API Arbitration — How we resolve API design disputes with data (vibe testing)
• Vibe Evaluation — Nightly benchmarks measuring Astryx vs alternatives
• RSC Compatibility — Why all components declare 'use client' and what changes when pre-compiled CSS lands
• Why StyleX — Why Astryx uses StyleX internally (and why consumers don't need it)
• Required Props Pattern — Why some props are required, and what that does to AI-generated usage

Hardening

• Component Audit Rubric — The graded checklist: eleven weighted sections, four ways to use it, and what counts as evidence. Reviewing a PR? Its guidance on reviewing a change sets the bar by change type — bug fix, feature, new component — and never runs the whole checklist on a diff.
• Component scores — The ledger: every component's audit grade, open BLOCKs, and when it was last graded. It lives as component-scores.json in this wiki and is the only stored form; there is deliberately no generated table. See Recording an audit for how to read and write it.
• Component Hardening Protocol — The Layer 3 human design review of a shipped component, and its form
• Hardening Audit Guide — Design quality audit: how to review components and file issues
• Bug Bash — Reusable quality checklist from the Feb 2026 bug bash

Night Watch

• Night Watch Overview — Automated repo stewardship during off-hours
• Night Watch Roles — Role assignments and responsibilities (individual role articles linked from here)
• Night Watch Adding Roles — How to create new Night Watch roles
• Night Watch Dead Code — Detecting and removing unused files, exports, types, and devDependencies
• Night Watch Figma Librarian — Keeping the OSS Figma Library in sync with code

Releasing

• Release Process — End-to-end release workflow: changesets, codemods, version bumps, publishing
• Distribution — Package structure, registry, and how Astryx ships to consumers

Research & Explorations

These pages capture design explorations and forward-looking research that informed Astryx decisions. They may describe features not yet implemented.

• Research Archive — Index of historical explorations, design investigations, and early-stage proposals

---

Note: For component-specific documentation, see the {Name}.doc.mjs file in each component's directory under packages/core/src/. Run astryx component <Name> to view formatted docs.