GitHub Trending 日榜第一，一天涨了 2,776 颗星，累计 25,340 颗星——这个项目叫 astryx。它是 Meta 官方维护的开源设计系统：MIT 协议、TypeScript、React 19 + StyleX，150+ 无障碍组件，README 自述支撑公司内部 13,000+ 个应用。
但真正值得读的不是组件清单，而是它对"文档"做的一次升级：把架构说明和规格说明写成带状态、带证据、带审批人的机器可检契约，再配一套路由脚本，让 AI 改代码时知道该守哪条规矩。这套治理思路不限于 React，也不限于设计系统——任何想用 AI 长期改自己仓库的团队，都能直接借鉴。
如果你正用 Claude Code 或 OpenClaw 这类工具写前端，或者团队在批量做活动页、商品详情页这类重复界面，这篇值得花十分钟读完；如果只想找一套现成的 UI 组件库，可以直接跳到最后两段。
它是什么：一套在 Meta 内部跑了八年的设计系统
astryx 的自述相当直接：它在 Meta 内部演进八年，是公司里使用面最广、体量最大的设计系统，支撑 13,000+ 个应用。对外提供 150+ 个无障碍组件、品牌级主题、深色模式、可直接投产的模板，外加一套命令行工具。
技术底座是 React 19+ 和 StyleX。StyleX 负责把样式编译成可组合的原子类，对使用方是不可见的：引入预构建 CSS 和带类型的 React 组件即可，不需要额外装构建插件，也不需要再引入一套样式库；想覆盖样式，用 className 配 Tailwind、CSS modules 或普通 CSS 都行。
仓库体量不小。GitHub 上报的 size 约 1.3 GB，packages 目录下有九个包。
packages/ build charts cli core lab native richtext themes vegadocs/specs 下有 82 个以 AST- 开头的规格目录，编号一路排到 AST-112，中间留了号；docs/architecture 下 22 个 Markdown 文件，含一份索引 README。当前版本 v0.7.14，MIT 协议，以 TypeScript 为主。状态还是 Beta，README 首屏就写明 Currently in Beta，公开 API 仍可能变。
数据快照（2026-11-12 12:57 CST 实测）：25,340 星、1,975 fork、677 条未关闭 issue（含 PR，纯 issue 300 条、PR 377 条），日榜第一当天新增 2,776 星。上游最近一次 release 是 v0.7.14，published_at 为 UTC 2026-11-11T19:54:54Z，换算北京时间是 11-12 凌晨 3:54；npm 上 @astryxdesign/cli 的稳定版同样是 0.7.14，更高版本目前只以 canary 预发布形式存在。
一句话讲清它的核心：文档不是散文，是带字段的记录
astryx 的 docs/architecture 和 docs/specs 下面，每篇说明的开头都不是散文，而是一段结构化字段。以 architecture:knowledge-contracts 这篇为例：
schema_version: 1
kind: architecture
id: architecture:knowledge-contracts
authority: current
approved_by: cixzhang
approved_at: 2026-08-30
owners: [cixzhang]
applies_to: [AGENTS.md, docs/, packages/]
verified_by:
[
scripts/check-knowledge.test.mjs,
scripts/specs-for-file.test.mjs,
scripts/lib/review-diff.test.mjs,
.github/scripts/change-scope.test.mjs
]读这段字段，你立刻能知道三件事：这份说明有没有人签字（approved_by、approved_at）、它管的是哪些文件（applies_to）、以及拿什么证明它说的事情真的成立（verified_by）。最后一项是整套做法的关键，下一节单独说。
authority 三态：治的是"合并不等于批准"
字段 authority 有三个取值，语义相当硬：draft 表示非权威，可能还缺证据或 owner 复核；current 表示已被显式批准、具备权威；archived 只作上下文保留，需要带上 superseded、withdrawn 或 historical 之类的归档理由，以及替代链接。
仓库根目录的 AGENTS.md 把这条规矩写成了硬性条款：
Only
currentrecords govern implementation and review. Never infer approval from merged code, silence, an old review, or an existing wiki page.
翻译过来就是：只有 current 状态的记录才能指导实现和评审，代码合进主干不等于批准、没人反对不等于批准、很久以前那次评审也不等于批准。
verified_by：证据不是"有测试"，而是具体文件名
大多数团队的规范文档写到"已通过测试"就停了。astryx 的做法是往下再走一步，把证据写死成一份可点开的文件清单。
architecture:cli-surface 这份记录的 verified_by 列了 27 项，其中 26 个是具体的测试文件，覆盖退出码、错误信封、JSON 契约、交互式守卫、路径安全、peer 版本检查这几类；剩下 1 项是一条 pnpm 结构检查命令。architecture:knowledge-contracts 那份则列了 13 个测试脚本。
这么写的价值很直接：验收方拿着清单可以一条条点开核对，缺了哪条一眼看得见；而"已验证"三个字，谁也定位不到证据。
改文件之前，先查"谁管这条路径"
光有记录还不够，还得能查。仓库根目录的 AGENTS.md 要求：动手改某个路径之前，先跑 pnpm specs:for <path>，列出当前生效的记录、决定它的规格，以及触发器路由到的全局主张；改完、提交或推送之前，再跑 pnpm specs:for --diff origin/main，把本次改动触发的所有关注点捞出来。底层脚本是 scripts/specs-for-file.mjs。
AGENTS.md 对这个命令的定性也很克制：它读的是工作区，所以在 PR 分支上看到的是这个分支提出的记录；它是一次查询，不是评审权威。
换成大白话：改哪个文件，该守哪条规矩，是脚本算出来的，不是靠人记的。
/vibe-test：给"AI 指令文件"本身写测量
这是整套东西里最值得单独讲的一节。
astryx 有个 AGENTS.md，也就是给 AI 看的仓库说明书。多数团队写完这类说明书就结束了，说明书好不好用，全靠人感觉。astryx 给它配了一套测试：/vibe-test。
流程是这样的：先准备一批任务文件，然后并行拉起子 agent，每个子 agent 只拿任务文件和自动注入的 AGENTS.md，去生成 Astryx 组件代码；生成后自己评估是顺利完成还是走了逃逸路径，写出 .tsx 结果和 .json 元数据；接着用 gh workflow run vibe-screenshots.yml 生成预览并截图；最后跑 pnpm -F @astryxdesign/vibe-tests aggregate 汇总结果。
日常用法有三种：/vibe-test 5 跑 5 个分层抽样测试，/vibe-test 跑全部 21 个测试，/vibe-test 5 –degradation 跑降级曲线。
降级模式是这里最有意思的部分：它跑 10 轮对话，在第 0、6、8、10 轮探测质量衰减，填充轮里塞进 filler、distractor、recovery 三类干扰，看的是"上下文越来越长之后，AI 还记不记得住该守哪条规矩"。
换句话说，它测的不是文档结构，而是"只给这份说明书，AI 到底能不能产出正确代码"。
AST-042：CLI 命令的"准入"本身就是治理对象
spec:AST-042 这份规格（2026-09-24 批准，状态 accepted）规定：每个命令、子命令、选项一旦发布，就是 AI 会依赖的公开表面，删掉就是破坏性变更；每个命令必须是一个"已文档化且已测试的可编程函数"的薄层。
配套的 architecture:cli-surface 记录，就用前面提到的 26 个测试文件把这个表面钉住。这套做法的意思是：不只是代码要测，命令行接口本身也是一份需要被保护的公开契约。
面向 AI 的技能资产
plugins/astryx/skills/astryx/SKILL.md 是另一份关键文件。
它的 description 是一串密集的触发词枚举：什么时候该想起这个技能（搭或改 UI、挑组件、做布局、写样式或主题、用设计系统、依赖 @astryxdesign 系列的包）。正文被一行 astryx-managed sha256 管理标记包裹着，可以校验完整性，防止被手改之后悄悄漂移。
工作流是强制顺序：astryx build "<想法>" 指明该从哪个模板起步、缺哪些件；astryx template <名称> <路径> 搭脚手架；astryx template
同一目录下还有 .claude/skills/dense-compression-protocol.md，规定了 docsDense 这种平行文档的写法：它是原文的翻译，不是另一份文档，信息一样，token 更省；并且和 docs.usage.bestPractices 一一对应，长度和顺序都得一样，压缩时不允许把两条并成一条。
同一份技能资产，分发到三个地方
仓库里有三处 marketplace 配置，把同一份技能资产同时铺到 Claude Code、agentskills.io 通用位和 Codex 上，根目录的 .claude-plugin 和 .agents/plugins 各有一份，plugins/astryx 下面另有 Codex 用的 .codex-plugin/plugin.json。三份描述文字完全一致，都是"告诉编码 agent Astryx 可以通过 astryx 命令使用、什么时候该用、从哪里开始"。
几条容易被忽略的边界
data-* 属性是公开 API。主题系统会基于 data 属性生成选择器，所以新增一个 data-* 属性，等于新增一条公开接口，必须有 current 级别的记录点名批准；如果只是内部需求，用私有的 data-astryx-* 前缀，或者干脆不用属性、改用 StyleX 的动态样式。
图层运行时只用 CSS anchor positioning。脚本永远不去移动图层来跟随锚点，按下时缩放的是触发元素自己的视觉，图层渲染在未变换的盒子之外。
集成贡献有专门规格（AST-039）。每个可发现的条目都要自己带一个强类型的同名 .doc.mjs 文件；根 manifest 只负责定位目录，永远不编目条目。AGENTS.md 里那句原话是："没有 catalog 文件（比如 themes/manifest.json），manifest 里永远不会有逐条目的映射。"
安全要求写在 AGENTS.md 的开头：这是公开的设计系统仓库，禁止提交内部链接、内部标识符、服务名、私有运维指令，以及其他 Meta-only 的上下文。
测试矩阵是 vitest 加 4 套 Playwright 配置（基础、interaction、perf、文档站各一套）。无障碍契约测试跑在基础配置加 chromium project 上，另有一条专门的 PR 门禁脚本 .github/scripts/a11y-pr-contracts.mjs；无障碍审计则对着 .github/a11y-baseline.json 基线跑，出现新的问题就让流水线失败。
贡献分布也值得说一句：提交最多的六位贡献者分别是 3,672、809、712、334、184、173 次提交，头部集中度不低。
这套东西对你有什么用
如果你在用 AI 写代码、或者在给团队维护知识库，下面几条是可以直接搬走的。
三态加"合并不等于批准"：给条目加上 draft、current、archived 三个状态，并明确写死"未经显式复核的记录一律是草案"，顺手治掉"已实现等于已验证"的默认推断。
证据写具体文件：不要写"已验证"，把验收脚本或测试文件名逐条列出来，缺口立刻可见。
给路径写路由：改哪个文件触发哪些强制检查，用脚本算出来，别靠人记。索引表手工维护的两份副本、发布清单的多个同步点，都是漂移高发区。
给 AI 说明书写行为测试：不是测结构，是测"只给这份说明书，AI 能不能产出正确产物"。上下文衰减可以用多轮加干扰项的方式单独测。
摘要和原文一一对应：压缩版必须和原文条目数严格对齐，否则校验器没法机械比对，"压缩过"这件事本身就失去了可验证性。
交付物是构建产物，不是描述：改完不验证等于没修，往前再进一层——交付的应该是能跑起来的东西本身。
什么时候你用不上它
先说清楚不适用的场景，比列优点更有用。
技术栈不匹配：astryx 要求 React 19 或更高，样式方案是 StyleX。如果你的项目技术栈完全不相干，引入它等于平白多出一套组件体系。
体量与节奏不匹配：仓库 1.3 GB，未关闭 issue 677 条，迭代面远超日常所需；而且提交高度集中在头几位贡献者身上。
状态不匹配：仍是 Beta，公开 API 可能变动。官方也明确禁止提交 Meta-only 上下文，生态边界对外部使用者没有增量。
所以更现实的做法是：把它的治理思路拿走，组件本身按需再评估。
电商场景里能用上哪部分
拿活动页、商品详情页这类重复界面来说，150+ 个无障碍组件加品牌级主题、深色模式、可直接投产的模板，能把"每个活动都重写一遍样式"这类重复劳动压下去，组件本身也自带无障碍，落地质量比临时凑一套更稳。
但更实用的是后面那层：当 agent 批量改页面时，"证据绑定到具体文件"、"改哪个路径触发哪些检查"这两条，能直接压住 AI 乱改的问题；而"只给说明书能不能写对"的行为测试，是很多团队完全没有的验收手段。
成本上也要算清楚：把整套组件体系引进来是一笔账，把治理思路拿走是另一笔账，后者的性价比通常高得多。
和传统组件库的差别在哪
和 Ant Design、MUI 这类传统组件库相比，astryx 的组件数量并不是它的卖点。真正的差别在治理层：它把规范写成带审批状态和证据清单的记录，把路径到规范的映射交给脚本，把 AI 说明书当成需要测试的产物，而不是一份写完就放着的文档。
换句话说，传统组件库解决的是"界面长什么样"，astryx 额外回答的是"人和 AI 一起改这套界面时，怎么保证不跑偏"。
数据时点说明
文中所有仓库数字都是 2026-11-12 12:57 CST 用 GitHub REST API 实测的：25,340 星、1,975 fork、677 条未关闭 issue、TypeScript、MIT 协议、建仓 2026-01-09、当天在 Trending 日榜新增 2,776 星。
issue 数字的口径说明一下：677 是包含 PR 的合计（GitHub 仓库侧边栏显示的就是这个数），纯 issue 是 300 条，PR 377 条，两个口径不要混。
release 的发布时间是 UTC 口径：v0.7.14 的 published_at 是 2026-11-11T19:54:54Z，换算北京时间是 11-12 凌晨 3:54。npm 上 @astryxdesign/cli 的稳定版同样是 0.7.14。
本期博客暂未配置封面图。