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

• 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 — 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 Authoring Guide — File structure, StyleX patterns, token usage, and conventions
• Vibe Tests — Evaluating API decisions with structured LLM testing
• Testing Example Apps — How to test example apps as an external consumer

• 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)

• Component Hardening Protocol — Post-build quality pass: bugs, polish, and visual decisions
• 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 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

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

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.