Astryx 怎么给 AI 生成前端接入设计系统：React 组件、主题与验收约束

让 AI 生成一个页面并不难；难的是第二个、第三个页面仍然沿用正确的颜色、间距、组件状态、无障碍属性和交互边界。Astryx 是 Meta 开源的 React 设计系统，官方称其处于 Beta，提供 150 多个可访问组件、主题、暗色模式、模板和 CLI，并允许使用 CSS 自定义属性进行主题覆盖。官方仓库

把 Astryx 接给 Agent 的目的不是让模型“自由设计”，而是让人和 Agent 都使用同一套组件与文档。

先判断是否适合引入

适合的项目通常具备以下任一条件：

React 项目已经有多个后台页面，AI 生成的 UI 开始出现风格漂移；
团队需要统一按钮、表单、弹窗、空状态和深色模式；
希望 Agent 优先组合现有组件，而不是每次手写一套 CSS；
允许在 Beta 依赖上做隔离验证和版本锁定。

如果项目不是 React，或已有成熟的内部组件库，先不要为了追热点重构。更现实的做法是把“组件优先、token 优先、截图验收”这些方法迁移到现有设计系统。

安装与最小主题

官方示例的包名如下：

1
2


npm install @astryxdesign/core @astryxdesign/theme-neutral
npm install -D @astryxdesign/cli

先在一个独立分支或小页面验证构建、样式加载和深色模式，再扩展到应用入口。不要让 Agent 直接替换全局样式、路由壳或已有 token 文件。

主题应表达品牌约束，而不是让每个页面随意覆盖。可以把允许修改的颜色、圆角、字体和间距写在项目规则里，让 Agent 知道“应该复用什么”，而不只是告诉它“做得高级一点”。

先做一个小页面，而不是替换应用外壳

推荐从一个单独路由开始，例如设置页、筛选侧栏或数据详情卡片。先列出这个页面当前使用的字体、间距、色彩 token、交互状态和已有组件，再让 Agent 用 Astryx 重建其中一个区域。此时保留原来的路由、数据请求、权限判断和全局样式入口；设计系统只负责组件与主题，不承担业务迁移。

本地验证顺序可以固定为：安装依赖后启动开发服务器；分别查看浅色和深色模式；用键盘 Tab 走完表单、弹窗和按钮；将窗口缩窄到移动宽度；最后再运行现有测试或构建。每一步出现问题都应记录在该组件的改动中，避免等多个页面都接入后才发现 token 覆盖、CSS 优先级或焦点管理有冲突。

当小页面稳定后，把它作为参考实现：记录允许引入的包、主题入口、组件导入方式和不可改动的全局文件。后续 Agent 的任务只引用这份参考，而不是让每次生成都重新猜项目约定。

给 Agent 的项目级约束

把下面这类规则放进项目的 AGENTS.md、CLAUDE.md 或 Skill 中：

1
2
3
4
5


- 新页面优先使用 @astryxdesign 现有组件；新增自定义组件前先说明原因。
- 不新增全局 CSS reset，不修改既有主题 token。
- 所有表单字段必须有可见 label、错误态和禁用态。
- 完成后提供桌面和窄屏截图，并列出新增组件与交互状态。
- 不以截图相似为唯一验收；保留键盘操作和语义结构。

这比“用设计系统做一个仪表盘”更可执行。Agent 有明确的禁止项、复用路径和交付物，审查者也能快速看出它是否绕开了组件库。

把输入、输出和禁止项写进任务单

实际任务最好包含页面范围、可使用的数据、允许修改的文件和验收截图。比如：只修改 src/features/orders/FilterPanel.tsx；复用现有查询参数；不新增依赖、不改路由、不修改 theme.ts；完成后给出窄屏和桌面截图，并列出 Button、Select、Dialog 的状态。这能避免 Agent 为了完成视觉目标顺手改掉全局 reset、状态管理或 API 层。

对复杂组件，让 Agent 先提交结构草案：有哪些区块、分别对应什么 Astryx 组件、有哪些 loading/error/empty 状态。人工确认结构后再写代码，通常比一次生成整页后逐项返工更快。若设计稿与组件库能力不一致，应优先调整设计或明确新增组件的维护者，而不是塞一段无法复用的临时 CSS。

用四层验收减少 UI 漂移

层级	要检查什么
组件	是否复用 Button、Input、Dialog 等既有组件，状态是否齐全
主题	是否只通过允许的 token 或 CSS 变量改变视觉风格
交互	键盘焦点、加载态、错误态、空状态是否可用
交付	构建是否通过，截图是否覆盖关键页面，改动是否有组件清单

不要把“视觉一致”理解成复制像素。真正需要稳定的是可访问语义、状态机、主题来源和可维护的组件边界。

一个可重复的验收流程

每次合入前，先由开发者核对 diff：是否新增了绕过组件库的全局样式、是否把品牌颜色写死、是否修改了无关文件。然后在浏览器中验证四种状态：正常数据、加载中、空数据、接口失败；表单还要额外验证必填、格式错误、禁用和提交中。截图只覆盖正常态会掩盖大多数回归。

最后用键盘完成一次关键流程：Tab 是否按可理解的顺序移动、焦点是否进入并离开 Dialog、错误消息是否与字段关联、颜色是否仍有足够对比度。把检查项放进 PR 模板后，Agent 生成的页面也会被同一套标准约束，而不会因为“看起来差不多”就直接合并。

常见误区

把 Beta 当成全站重构理由：先锁版本，在单一功能域验证升级成本。
让 Agent 直接改组件内部：优先组合与主题覆盖；只有确有需要时才导出或接管源码。
每个页面写一套临时 CSS：这会让设计系统只剩包名，无法约束后续 Agent。
只验截图不验交互：截图无法发现 tab 顺序、错误反馈和不可点击的按钮。

小结

Astryx 适合用于建立“人和 Agent 使用同一套前端语言”的约束。先用少量页面验证组件、主题和验收流程，再把规则沉淀到项目文件；不要让新设计系统变成另一层无人维护的抽象。