An open source design system that's fully customizable and agent ready
/packages/cli/assets/docs
Reference topics for people building with Astryx. Not docs about building Astryx itself.
One {topic}.doc.mjs per topic, plus optional {topic}.doc.dense.mjs / {topic}.doc.zh.mjs prose overlays. foundation/discovery/docs-discovery.mjs picks up any {topic}.doc.mjs here with no registration; api/docs/_adapter.mjs merges the overlays.
What you add reaches astryx docs <topic>, astryx search, the --json API, the agent-docs block and the doc site — and ships on npm.
Who you are writing for
Someone building a product with Astryx. Their questions:
- what a component is for, and when to reach for something else
- the props, their defaults, and what each does to what they see
- how to compose it, and the pattern to copy
- what it costs — bundle size, the a11y obligations they inherit
- how to theme it, and which targets are stable
The test for anything you add: does a caller act on it? They are not reviewing a PR, promoting a component out of lab, or attaching evidence to a checklist.
Tells that you are writing for us instead
- second person aimed at the wrong reader — "reviewers should…", "before promoting a component…", "attach evidence for…"
- an internal rubric, readiness gate, audit checklist, or sign-off that the reader must satisfy for Astryx maintainers
- a table of things to verify rather than things to use
- anything about lab → core, which is our lifecycle, not theirs
- Storybook, Playwright, CI or the Simulator named as tools the reader runs
One subtlety: a statement about the system's behavior is caller-facing even when it sounds like process. "A component's theme targets are stable once published" tells a caller what they can rely on; "reviewers must check that theme targets are stable" is ours. Same fact, different reader — rewrite it rather than move it.
A public authoring-quality rubric is also caller-facing when it helps someone evaluate an artifact they create through Astryx. It must be complete and actionable from public inputs. It must not include Astryx's internal approval, promotion, evidence-publication, or CI process. A current system spec must assign the shipped guide as the rubric's owner.
Where the rest goes
The material is usually good; the finding is placement, not quality. It goes in the wiki — as a section on the page that already covers it, not a new page. The wiki is at nearly 60 pages, several of them overlapping, because every stray section got its own.
| what you wrote | where it goes |
|---|---|
| how a component is graded — checks, scoring | Component-Audit-Rubric |
| lab → core promotion, what a component must satisfy | Component-Lifecycle |
| how to build a new component | Component-Authoring-Guide, Creating-New-Components |
| what a component must be hardened against | Component-Hardening-Protocol, Hardening-Audit-Guide |
| a11y requirements as checks we run | Accessibility-Checklist |
| how the system is put together | System-Architecture, Theming-Infrastructure |
| API naming and shape decisions | API-Conventions, API-Arbitration |
| contributor workflow, PR process | Contributing, Contributing-with-AI-Assistants |
| release mechanics | Release-Process |
| what a nightly agent role does | the Night-Watch pages, from Night-Watch-Overview |
Fits no row? It is still not caller-facing. Default it to Contributing, or CONTRIBUTING.md when it is a step someone follows with the repo cloned. Never default it back to this directory.
Worked example: a responsive-and-interaction readiness rubric is grading criteria → Component-Audit-Rubric, or Component-Lifecycle if it is a promotion gate.
Imports in code samples
Import each Core export from the path astryx component <Name> prints: the
component's own entry when Core has one (@astryxdesign/core/VStack,
@astryxdesign/core/Heading), and @astryxdesign/core/theme for Theme,
defineTheme and the rest of the theme API. A reader copies one sample and then
reads astryx component, and two paths for one export read as two different
things. The no-build CDN page is the exception: its import map names only the
package root.
Sections are read one at a time
astryx docs <topic> --index lists a topic's sections, and readers then open
one section by its key. A section's key is its id, or a key derived from its
title when it has none. Give a section an id when its title may change, since
readers and extensions link to the key. Two sections in one topic cannot share
a key. Keep each section small enough to read on its own: astryx doctor warns on
any section over 32 KB.