Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(cli): say who packages/cli/assets/docs is written for (#5368)

Cindy Zhangad3eb9bc8806
diff --git a/.claude/skills/writing-component-docs.md b/.claude/skills/writing-component-docs.md
index 93a8d9d450..8f9ef867b1 100644
--- a/.claude/skills/writing-component-docs.md
+++ b/.claude/skills/writing-component-docs.md
@@ -4,6 +4,8 @@
Every component directory has a `{Name}.doc.mjs` file with structured documentation. The Astryx CLI reads these files to generate agent-friendly docs, skill files, and reference material.
+These docs are for people **building with** Astryx, not for people building Astryx. Before adding process material — a rubric, a readiness gate, an audit checklist, lab→core criteria — read [`packages/cli/assets/docs/README.md`](../../packages/cli/assets/docs/README.md), which carries the test and the wiki page each kind goes to.
+
## Exports
| Export | Type | Purpose | Required? |
@@ -122,7 +124,7 @@ astryx --detail compact --lang dense component Button # Compact + compressed
Reference docs (tokens, principles, theme) use a different type: `ReferenceDoc` from `@astryxdesign/cli/authoring`.
-They live in `packages/cli/docs/` as `.doc.mjs` files with translations in `*.doc.dense.mjs` and `*.doc.zh.mjs`.
+They live in `packages/cli/assets/docs/` as `.doc.mjs` files with translations in `*.doc.dense.mjs` and `*.doc.zh.mjs`.
Content is structured as sections with ordered content blocks:
@@ -131,7 +133,7 @@ Content is structured as sections with ordered content blocks:
- `table` — data tables (not translated)
- `list` — rules, anti-patterns, tips (translatable)
-To add a new reference doc: create `packages/cli/docs/mytopic.doc.mjs` exporting a `docs` constant. It auto-discovers.
+To add a new reference doc: create `packages/cli/assets/docs/mytopic.doc.mjs` exporting a `docs` constant. It auto-discovers.
```bash
astryx docs # list topics
diff --git a/CLAUDE.md b/CLAUDE.md
index fa8649a5f7..1a7b6a36a5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -68,6 +68,8 @@ Documentation lives in two places:
**Update Protocol**: When modifying code, update the file's header comment. Look for `SYNC:` comments as reminders.
+**Audience**: every `.doc.mjs`, and everything under `packages/cli/assets/docs/`, is written for people **building with** Astryx — not for people building Astryx. Rubrics, readiness gates, audit checklists and lab→core criteria belong in the wiki. [`packages/cli/assets/docs/README.md`](packages/cli/assets/docs/README.md) has the test and the page each kind of material goes to.
+
## Quick Reference
- **Package manager**: pnpm 11, pinned by the `packageManager` field (see
diff --git a/packages/cli/assets/docs/README.md b/packages/cli/assets/docs/README.md
new file mode 100644
index 0000000000..dbd59235ab
--- /dev/null
+++ b/packages/cli/assets/docs/README.md
@@ -0,0 +1,50 @@
+# /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…"
+- **rubric, readiness, gate, audit, checklist, sign-off, promotion, evidence** as things the reader must produce
+- 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**.
+
+## Where the rest goes
+
+The material is usually good; the finding is placement, not quality. It goes in the [wiki](https://github.com/facebook/astryx/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](https://github.com/facebook/astryx/wiki/Component-Audit-Rubric) |
+| lab → core promotion, what a component must satisfy | [Component-Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle) |
+| how to build a new component | [Component-Authoring-Guide](https://github.com/facebook/astryx/wiki/Component-Authoring-Guide), [Creating-New-Components](https://github.com/facebook/astryx/wiki/Creating-New-Components) |
+| what a component must be hardened against | [Component-Hardening-Protocol](https://github.com/facebook/astryx/wiki/Component-Hardening-Protocol), [Hardening-Audit-Guide](https://github.com/facebook/astryx/wiki/Hardening-Audit-Guide) |
+| a11y requirements as checks we run | [Accessibility-Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist) |
+| how the system is put together | [System-Architecture](https://github.com/facebook/astryx/wiki/System-Architecture), [Theming-Infrastructure](https://github.com/facebook/astryx/wiki/Theming-Infrastructure) |
+| API naming and shape decisions | [API-Conventions](https://github.com/facebook/astryx/wiki/API-Conventions), [API-Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration) |
+| contributor workflow, PR process | [Contributing](https://github.com/facebook/astryx/wiki/Contributing), [Contributing-with-AI-Assistants](https://github.com/facebook/astryx/wiki/Contributing-with-AI-Assistants) |
+| release mechanics | [Release-Process](https://github.com/facebook/astryx/wiki/Release-Process) |
+| what a nightly agent role does | the Night-Watch pages, from [Night-Watch-Overview](https://github.com/facebook/astryx/wiki/Night-Watch-Overview) |
+
+**Fits no row?** It is still not caller-facing. Default it to [Contributing](https://github.com/facebook/astryx/wiki/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.