AuraDesign 是一个给 AI Coding Agent 使用的 UI 设计 skill。它让 Codex、Claude Code、Cursor 等先读懂产品和项目风格，再生成可评审的 HTML 设计稿、中文 polish 报告和中文工程交接文档。

这个包包含两部分：

• aura-design skill：Agent 真正使用的设计工作流。
• aura CLI：把 skill 安装、更新、诊断到 Codex / Claude Code 的小工具。

日常设计时，用户主要和 Agent 对话，例如“使用 aura-design draw 设计订单详情页”。aura CLI 只负责让这些 Agent 能读到最新版 skill。

当前仓库：

[email protected]:AuraDesign/AuraDesign.git

http://xingyun.jd.com/codingRoot/AuraDesign/AuraDesign/

什么时候用

AuraDesign 适合这些场景：

• 新项目需要先做一版高保真页面设计。
• 旧项目要新增页面，希望默认复用已有组件、tokens、布局密度和视觉风格。
• 旧页面要重构，但不想让 Agent 一上来直接改业务源码。
• 需要把一个页面的设计稿、截图、资产记录、无障碍和溢出检查集中放到项目里，方便评审和交接。

AuraDesign 不适合纯产品策略、品牌文案、logo / banner / 社媒图、普通代码实现建议、纯 DESIGN.md 清理、或不需要 UI 设计产物的泛化讨论。遇到这些请求时，Agent 应先说明不适配，并建议更合适的下一步，而不是强行创建 prototype.html。

它的核心原则很简单：先在 auraDesign/ 目录里做设计产物，确认后再决定是否进入业务代码。这个目录参考 baoyu-design 的 designs/ 模式，所有设计稿、原型、资产记录和交接材料都放在同一个根目录下。

aura CLI 是什么

aura 不是设计命令入口，它不负责直接画页面。它只做外层管理：

aura install     安装或替换 Codex / Claude Code 的 aura-design skill
aura update      更新全局 aura CLI，并同步更新已安装的 skill
aura env         查看 Agent 使用前的版本和更新状态
aura doctor      检查 CLI、Node、skill 源文件和安装路径
aura gallery     读取 AuraGallery registry / 本地路径 / URL，列出可用于新项目的 DESIGN.md 模板
aura project-mode 判定项目是 existing 还是 greenfield
aura product     把用户提供的产品描述写入 PRODUCT.md
aura version     查看当前 CLI 版本
aura help        查看命令和参数说明

默认情况下，aura install 只写入当前项目的项目级路径：

.agents/skills/aura-design/
.claude/skills/aura-design/
.joycode/skills/aura-design/

项目级目录默认会写入本地 .git/info/exclude，不会进入 git 追踪。需要全局安装时必须显式执行 aura install --scope global；需要项目级和全局级同时写入时执行 aura install --scope all。

快速开始

最短交付路径：

npm install -g @auradesign/skill
aura install

然后在 Codex / Claude Code 里说：

使用 aura-design init，学习当前项目的产品和设计风格。
使用 aura-design draw order-detail，设计订单详情页。

安装 CLI：

npm install -g @auradesign/skill
aura --help

进入业务项目根目录，安装 skill：

aura doctor
aura install

不想全局安装 CLI 时，也可以直接用 npx：

npx @auradesign/skill --help
npx -y @auradesign/skill@latest install --agent all --scope all

本仓库开发时，可以直接运行本地 CLI：

node bin/aura.mjs --help
node bin/aura.mjs install --cwd /path/to/business-project
node bin/aura.mjs project-mode --cwd /path/to/new-project
node bin/aura.mjs product apply --description "一个给门店管理预约和排班的工具" --cwd /path/to/new-project
node bin/aura.mjs gallery list --source http://localhost:3000/
node bin/aura.mjs gallery apply --template linear --cwd /path/to/new-project

AuraGallery 模板输入

/aura-design init 遇到新项目时，可以先用 AuraGallery 选择一个很薄的 DESIGN.md 起点。当前协议先读取并列出模板，再按用户选择把模板复制为项目根目录 DESIGN.md：

aura project-mode --cwd /path/to/new-project
aura product apply --description "用户对产品的描述" --cwd /path/to/new-project
aura gallery list
aura gallery list --source https://aura-gallery-eta.vercel.app/
aura gallery list --source /Users/qiumengbo.123/Documents/AuraGallery/examples
aura gallery list --source http://localhost:3000/
aura gallery apply --template linear --cwd /path/to/new-project

project-mode 返回 greenfield 时，不运行 kernel discovery，也不创建 auraDesign/_kernel/。这类项目没有足够的本地设计资产，正确流程是先让用户描述产品，再选择 Gallery 模板作为 DESIGN.md 起点。只有 existing 项目才学习本地组件、tokens、页面和资产。

支持三类输入：registry JSON、包含 <slug>/DESIGN.md 的本地目录、AuraGallery URL。默认先读取 https://aura-gallery-eta.vercel.app/；线上不可用时回退到 skill 内置 registry。URL 模式会优先找 registry；如果没有，就读取 /gallery 并映射到 /api/example/<brand>/DESIGN.md。

apply 默认保护已有项目化 DESIGN.md。只有目标文件缺失、为空、仍是 starter 模板，或已经是 AuraGallery 初始化模板时才会覆盖；确实要覆盖项目规则时再加 --force。

安装范围

只安装项目级或全局级：

aura install
aura install --scope project
aura install --scope global
aura install --scope all

只安装某一个 Agent：

aura install --agent codex
aura install --agent claude-code
aura install --agent joycode

如果要把项目级 skill 提交给团队，执行：

aura install --scope project --track

更新

aura update

aura update 会检查 npm 最新版本。发现新版本时，它会先更新全局 aura CLI，再覆盖 Codex / Claude Code 已安装的 skill。

如果本机的 aura 命令太旧或不可用，直接用 npm 兜底：

npm install -g @auradesign/skill@latest
aura install

在 Codex / Claude Code 里，也可以让 Agent 执行最新版包里的安装命令来刷新 skill：

npx -y @auradesign/skill@latest install --agent all --scope all

诊断本机 Node、skill 源文件、安装路径和 CLI 自检：

aura env
aura doctor

Agent 使用 aura-design 前应先执行 aura env。如果输出提示发现新版本，先执行 aura update，再继续设计或初始化流程。

这些命令只管理 CLI 和 AuraDesign skill，不会修改业务源码，也不会改业务项目的 package.json。

兼容安装方式：也可以继续使用通用 skills CLI，从 Git 仓库安装 skill。

npx skills add [email protected]:AuraDesign/AuraDesign.git --skill aura-design --agent codex
npx skills add [email protected]:AuraDesign/AuraDesign.git --skill aura-design --agent claude-code
npx skills add [email protected]:AuraDesign/AuraDesign.git --skill aura-design --agent cursor

临时试用时，也可以直接让 Agent 读取仓库：

Read [email protected]:AuraDesign/AuraDesign.git and follow skills/aura-design/SKILL.md to design the settings page.

怎么对 Agent 下指令

AuraDesign 当前提供这些主要命令：

/aura-design init
/aura-design draw <target>
/aura-design polish <target>
/aura-design build <target>

常见用法：

使用 aura-design init，基于产品需求文档和项目源码初始化设计契约与风格 kernel。

使用 aura-design draw order-detail，为订单详情页生成高保真设计稿。只产出 auraDesign/order-detail 下的设计文件，不要修改业务源码。

使用 aura-design polish order-detail，审计并修正设计稿，留下中文 polish 报告。

使用 aura-design build order-detail，基于已确认的设计稿生成实现交接文档。没有明确要求前，不要改业务源码。

旧项目里可以直接说清业务目标，不必反复提醒“遵循当前项目风格”。AuraDesign 的默认策略就是先看已有代码、组件、tokens、页面和截图证据。

产物在哪里

init 会在项目根目录创建或补齐两个设计契约文件，并生成项目风格内核：

PRODUCT.md
DESIGN.md
auraDesign/_kernel/
  kernel.md
  evidence.json
  design-draft.md

旧项目的根目录 DESIGN.md 应从 auraDesign/_kernel/design-draft.md 收敛而来，章节顺序和 AuraGallery 模板保持一致；kernel.md 只是证据清单，不应直接当最终设计契约。

draw <target> 默认生成页面设计稿：

auraDesign/<target>/
  _aura.json
  shape.md
  prototype.html

polish <target> 默认生成中文审计与修复记录：

auraDesign/<target>/
  polish.md
  polish-report.json

build <target> 默认生成工程交接：

auraDesign/<target>/
  implementation.md

这些文件是设计交付物，不是业务源码。只有用户明确要求“应用到业务代码”时，Agent 才应该去修改 src/、app/、pages/ 等目录。

三个典型流程

推荐主流程：

init -> draw <target> -> polish <target> -> build <target>

init 通常每个项目只需要跑一次；draw 先写 shape.md 再生成 prototype.html；polish 检查并修正设计稿，留下中文报告；build 在设计方向确认后生成中文工程交接。

新项目设计：

使用 aura-design init 初始化设计契约。
使用 aura-design draw dashboard 设计后台首页。
使用 aura-design polish dashboard 检查并修正设计稿。

旧项目新增页面：

使用 aura-design init 学习当前项目风格。
使用 aura-design draw order-detail 设计订单详情页，复用现有组件、tokens、素材和交互。
使用 aura-design polish order-detail 检查并修正设计稿。
使用 aura-design build order-detail 生成工程交接。

旧页面重构：

使用 aura-design init 学习当前页面和相关组件。
使用 aura-design draw settings-refactor 生成重构设计稿，不改业务源码。
使用 aura-design polish settings-refactor 检查并修正设计稿。
设计确认后，再明确要求 Agent 应用到业务代码。

内部脚本

大多数时候 Agent 会按 skill 指令自己调用脚本。手动调试设计产物时，使用 npm scripts：

npm run aura:learn-kernel
npm run aura:draw-init -- --target settings --title "Settings"
npm run aura:polish -- --target settings
npm run aura:check-target -- --dir auraDesign/settings --handoff --assets --portable
npm run aura:smoke

这些脚本是开发和调试入口，不是推荐给普通用户记忆的产品命令。普通用户只需要安装 aura CLI，然后在 Agent 里说 aura-design init/draw/polish/build。

本仓库开发

克隆仓库：

git clone [email protected]:AuraDesign/AuraDesign.git
cd AuraDesign

安装开发依赖：

npm install

npm test 会跑 CLI 和核心脚本的轻量回归检查，不需要下载 Playwright 浏览器。只有要运行 aura:screenshot、aura:a11y 或 aura:overflow 这类真实浏览器检查时，才需要额外执行 npx playwright install chromium。

跑基础检查：

npm test

打包前看一下会发布哪些文件：

npm pack --dry-run

仓库结构

docs/
  # ignored by git; local plans, todos, test logs, and work logs live here

skills/
  aura-design/
    SKILL.md
    system-prompt.md
    agents/
    built-in-skills/
    references/
    scripts/
    starter-components/

templates/
  PRODUCT.md
  DESIGN.md

参考来源

AuraDesign 参考了 JimLiu/baoyu-design 的 skill 分层、HTML-first 设计产物和部分 starter components。复制或改写的文件会在对应文件中保留来源说明。