Skip to content

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

TypeScript

docs: link convention and rubric wiki pages from README, CONTRIBUTING, and package docs (#3794)

Cindy Zhangf0b9ca8fa743
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3fd604bbe1..a633af375b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,8 +5,12 @@ For the full contribution process — what we accept, how to propose new compone
Key pages:
- **[API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)** — naming, prop patterns, composition rules (read before submitting an RFC)
+- **[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions)** — the design-side bar: tokens, spacing, radius, elevation, type, color, motion, and state representations
- **[Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol)** — the 9-phase process for new components
+- **[Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle)** — how components move from lab → core and templates from hidden → visible
- **[API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)** — how we resolve API design questions
+- **[Contributing Templates](https://github.com/facebook/astryx/wiki/Contributing-Templates)** — building templates/blocks and the template grading rubric
+- **[Blog Review Rubric](https://github.com/facebook/astryx/wiki/Blog-Review-Rubric)** — how docsite blog posts are reviewed
- **[Contributing with AI](https://github.com/facebook/astryx/wiki/Contributing-with-AI-Assistants)** — safe zones, spec protocol, and working with AI tools
This file covers local development setup.
diff --git a/README.md b/README.md
index 630e38a204..f23111e245 100644
--- a/README.md
+++ b/README.md
@@ -95,6 +95,15 @@ Battle-tested design solutions for common interactions and workflows: table page
We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide.
+Our conventions and review rubrics live in the
+[Contributing wiki](https://github.com/facebook/astryx/wiki/Contributing) —
+including [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions),
+[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions),
+the [Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle),
+and the [Contributing Templates](https://github.com/facebook/astryx/wiki/Contributing-Templates)
+and [Blog Review](https://github.com/facebook/astryx/wiki/Blog-Review-Rubric)
+rubrics. Read the relevant one before opening a PR.
+
Quick start for contributors: this repo uses **Node 22+ on an active LTS line**
and **pnpm 11**. Install pnpm directly, or enable
[Corepack](https://nodejs.org/api/corepack.html) once so the pinned pnpm version
diff --git a/apps/docsite/src/content/blog/README.md b/apps/docsite/src/content/blog/README.md
index 015b625f12..3bec56cbb6 100644
--- a/apps/docsite/src/content/blog/README.md
+++ b/apps/docsite/src/content/blog/README.md
@@ -146,3 +146,16 @@ pnpm typecheck
That's it — no index pages to edit, no manual wiring. The post is discovered
automatically and sorted into place by date.
+
+## How posts are reviewed
+
+Blog posts are reviewed against the
+**[Blog Review Rubric](https://github.com/facebook/astryx/wiki/Blog-Review-Rubric)**.
+It's type-aware (a changelog `update`, an `engineering` deep-dive, and a
+`perspective` essay are judged by different profiles), gates on accuracy
+(verifiable claims — commands, APIs, numbers — are checked against the codebase,
+and a confirmed error blocks publish), and checks substance, efficiency, craft,
+and voice **without homogenizing your voice**. The same rubric powers the Copilot
+reviewer at `.github/instructions/blog.instructions.md`, so a blog-post PR gets
+the check automatically. Reading it before you write is the fastest way to land
+an A.
diff --git a/packages/lab/README.md b/packages/lab/README.md
index 19da15dea9..cb26aea437 100644
--- a/packages/lab/README.md
+++ b/packages/lab/README.md
@@ -12,6 +12,8 @@ Components in lab:
- Compose with `@astryxdesign/core` components (use the theme, follow naming conventions)
- Graduate to `@astryxdesign/core` after thorough engineering review
+See the **[Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle)** wiki for how a component moves from lab → core (and the promotion gates), and the **[Component Hardening Protocol](https://github.com/facebook/astryx/wiki/Component-Hardening-Protocol)** for the bar a component must clear to graduate.
+
## What's here vs what's in core
**Lab:** Works, has basic props, maybe has stories. API might change. Not accessibility-hardened, not vibe-tested, not fully themed. **Canary-only — no stability promise.**