ai-design-expert
README.md
# 🎨 AI 设计专家 - Claude Code 技能
> 从需求��设计稿的自动化流水线 - 一个为 Claude Code 打造的设计专家 Skill
---
## 📖 简介
**AI 设计专家** 是一个 Claude Code 技能（Skill），通过 MCP (Model Context Protocol) 服务器提供强大的设计能力。
### 核心功能
| 功能 | 描述 |
|------|------|
| **需求解析** | 分析 Word/PDF/MD 文档，提取设计要求 |
| **视觉解码** | 从设计图提取 Design Tokens（颜色、间距、字体等） |
| **设计生成** | 根据需求和 Tokens 生成 HTML/Tailwind 代码 |
| **视觉审计** | 对比生成代码与参考图，提供改进建议 |
---
## 🚀 快速开始
### 1. 安装依赖
```bash
npm install
```
### 2. 构建项目
```bash
npm run build
```
### 3. 配置 Claude Code
在项目根目录的 `.claude.json` 中添加：
```json
{
"mcpServers": {
"ai-design-expert": {
"command": "node",
"args": ["dist/mcp/server.js"]
}
}
}
```
或使用绝对路径：
```json
{
"mcpServers": {
"ai-design-expert": {
"command": "node",
"args": ["/absolute/path/to/ai-design-expert/dist/mcp/server.js"]
}
}
}
```
### 4. 重启 Claude Code
配置完成后，重启 Claude Code 使 MCP 服务器生效。
### 5. 验证安装
在 Claude Code 中测试：
```
用户: 请分析 docs/requirements/raw/example-landing-page.md 并生成设计稿
```
---
## 💡 使用示例
### 示例 1: 从需求文档生成设计
```
用户: 请分析 docs/requirements/raw/example-landing-page.md 并生成设计稿
```
**AI 将执行**：
1. 调用 `analyze_requirement` 解析需求文档
2. 使用默认 Design Tokens（或要求提供参考图）
3. 调用 `generate_design` 生成 HTML/Tailwind 代码
4. 返回完整的设计稿
---
### 示例 2: 从参考图提取设计风格
```
用户: 请分析 docs/references/design.png 并提取 Design Tokens
```
**AI 将执行**：
1. 调用 `extract_tokens` 分析图片
2. 使用 Claude Code 的视觉分析能力（4.5v MCP）
3. 返回结构化的 Design Tokens JSON
---
### 示例 3: 完整工作流
```
用户: 根据 project-req.md 和 reference.png 生成设计稿，并进行视觉审计
```
**AI 将执行**：
1. `analyze_requirement("project-req.md")` → 需求分析
2. `extract_tokens("reference.png")` → 提取 Tokens
3. `generate_design({...}, {...}, "output/")` → 生成设计
4. `audit_visual({...}, "reference.png")` → 视觉审计
---
## 🛠 可用工具
### `analyze_requirement`
解析需求文档，提取设计要素。
**输入**:
```json
{
"filePath": "docs/requirements/raw/example.md"
}
```
**输出**: 需求分析 JSON
---
### `extract_tokens`
从设计图提取 Design Tokens。
**输入**:
```json
{
"imagePath": "docs/references/design.png"
}
```
**输出**: Design Tokens JSON
---
### `generate_design`
生成 HTML/Tailwind 设计稿。
**输入**:
```json
{
"requirement": {...},
"tokens": {...},
"outputPath": "output/"
}
```
**输出**: 完整的 HTML 代码
---
### `audit_visual`
视觉审计，对比代码与参考图。
**输入**:
```json
{
"designCode": "<html>...</html>",
"referenceImagePath": "docs/references/design.png"
}
```
**输出**: 审计报告（评分 + 问题列表）
---
## 📁 项目结构
```
ai-design-expert/
├── 📄 配置文件
│ ├── .claude.json # Claude Code 配置
�� ├── package.json # 项目依赖
│ ├── skill.json # Skill 定义
│ └── tsconfig.json # TypeScript 配置
│
├── 📚 文档
│ ├── CLAUDE.md # AI 行为指令
│ ├── README.md # 本文件
│ ├── INSTALL.md # 详细安装指南
│ └── PROGRESS.md # 进度追踪
│
├── 🔧 MCP 服务器 (src/mcp/)
│ ├── server.ts # 服务器入口
│ ├── tools/ # 4 个工具实现
│ │ ├── index.ts
│ │ ├── requirement-analyzer.ts
│ │ ├── token-extractor.ts
│ │ ├── design-generator.ts
│ │ └── visual-auditor.ts
│ └── utils/
│ └── vision-client.ts # 4.5v MCP 集成
│
├── 📦 工具库 (src/lib/)
│ ├── index.ts
│ ├── utils.ts # 通用工具函数
│ └── token-parser.ts # Token 解析器
│
├── 🎨 组件模板 (src/components/)
│ └── atoms/ # 原子组件参考
│ ├── Button.tsx
│ ├── Card.tsx
│ └── index.ts
│
├── 🎯 Design Tokens
│ └── src/theme/tokens.json # 默认设计变量
│
├── 📝 提示词模板 (prompts/)
│ ├── analyze-requirement.md
│ ├── extract-design-tokens.md
│ └── generate-design-spec.md
│
└── 📂 示例数据 (docs/requirements/)
└── raw/ # 需求文档
├── example-landing-page.md
└── example-dashboard.md
```
---
## 🔄 工作流程示例
```
用户输入
↓
1. analyze_requirement("docs/project-brief.md")
→ 需求分析 JSON
↓
2. extract_tokens("docs/reference-design.png")
→ Design Tokens JSON
↓
3. generate_design({ requirement, tokens, outputPath: "output/" })
→ 生成 index.html + tailwind.config.js
↓
4. audit_visual({ designCode, referenceImagePath })
→ 审计报告 + 改进建议
↓
最终交付：完整的设计稿
```
---
## 🧪 开发
```bash
# 开发模式（测试 MCP Server）
npm run dev
# 应该看到: ✅ AI 设计专家 MCP 服务器已启动
# 构建
npm run build
# 运行测试
npm test
# 代码检查
npm run lint
# 格式化代码
npm run format
```
---
## 🔧 故障排除
### MCP 服务器未启动
**检查**:
```bash
npm run dev
# 应该看到: ✅ AI 设计专家 MCP 服务器已启动
```
### 找不到模块
**解决**:
```bash
rm -rf node_modules package-lock.json
npm install
npm run build
```
### TypeScript 编译错误
**解决**:
```bash
npm run build
# 查看具体错误信息并修复
```
### Claude Code 无法识别工具
**检查**:
1. 确认 `.claude.json` 配置正确
2. 确认路径使用绝对路径或正确的相对路径
3. 重启 Claude Code
---
## 📝 示例数据
项目包含两个示例需求文档：
### 1. SaaS 产品着陆页 (`example-landing-page.md`)
- AI 写作助手产品 "WriteFlow"
- 包含 Hero、功能展示、社会证明、定价等模块
### 2. 电商数据分析仪表板 (`example-dashboard.md`)
- 实时销售数据监控
- 包含侧边栏导航、数据卡片、图表等
---
## 🎯 技术栈
| 技术 | 用途 |
|------|------|
| **TypeScript** | 类型安全 |
| **MCP SDK** | Model Context Protocol 集成 |
| **Tailwind CSS** | 样式生成 |
| **4.5v MCP** | 图片分析能力 |
---
## 📚 文档导航
| 文档 | 用途 |
|------|------|
| `README.md` | 项目介绍和功能说明（本文件） |
| `INSTALL.md` | 详细安装和配置指南 |
| `CLAUDE.md` | AI 行为规范和工作流程 |
| `PROGRESS.md` | 开发进度和待办事项 |
---
## 🔮 进阶功能
### 自定义 Design Tokens
编辑 `src/theme/tokens.json`：
```json
{
"colors": {
"primary": "#3b82f6",
"secondary": "#6366f1",
...
}
}
```
### 使用组件模板
`src/components/` 目录包含 React 组件模板，可作为代码生成参考：
- **Button.tsx** - 按钮组件（3 种样式，3 种尺寸）
- **Card.tsx** - 卡片组件（含 Header, Title, Content）
- **index.ts** - 统一导出
这些组件展示了 Design Tokens 的使用方式，可参考其实现生成类似组件。
### 扩展提示词模板
编辑 `prompts/` 目录下的 `.md` 文件，自定义 AI 的分析行为。
### 添加新的页面类型
在 `src/mcp/tools/design-generator.ts` 中添加新的 `generate*` 函数。
---
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
### 贡献方式
1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request
---
## 📊 项目统计
- **总文件数**: 28 个（精简后）
- **代码行数**: ~1800
- **工具数量**: 4 个 MCP 工具
- **示例文档**: 2 个
- **TypeScript 覆盖率**: 100%
- **文档文件**: 5 个
---
## 🔄 更新日志
### v1.0.0 (2025-01-29)
**重大更新**:
- ✅ 项目从 Next.js 重构为 Claude Code MCP Skill
- ✅ 实现完整的 MCP 服务器（4 个工具）
- ✅ 集成 4.5v MCP 图片分析能力
- ✅ 添加 2 个示例需求文档
- ✅ 完善文档（README, INSTALL, CLAUDE.md）
**清理优化**:
- 🗑️ 删除 setup.sh（已完成初始化）
- 🗑️ 删除 tailwind.config.ts（不再使用 Next.js）
- 🗑️ 删除 scripts/ 目录（旧脚本）
- 🗑️ 删除 PROGRESS_TASK.md（已有 PROGRESS.md）
- 📦 精简项目结构，保留 28 个核心文件
**功能特性**:
- 📋 需求文档解析（analyze_requirement）
- 🎨 视觉设计解码（extract_tokens）
- 💻 设计稿生成（generate_design）
- 🔍 视觉审计（audit_visual）
---
## 📝 许可证
ISC
---
## 📮 联系方式
如有问题或建议，请：
- 提交 GitHub Issue
- 查看 `CLAUDE.md` 了解使用规范
- 查看 `INSTALL.md` 了解安装详情
---
*由 AI 设计专家自动生成并维护*
TDQS
A3.5/5.0
Scored across 4 tools
Disambiguation5/5
Each tool targets a distinct stage of the design pipeline: requirement analysis, token extraction, design generation, and visual audit. Input types and outputs are clearly differentiated, leaving no ambiguity about which tool to use.
Naming Consistency5/5
All four tools follow a consistent snake_case verb_noun pattern: analyze_requirement, extract_tokens, generate_design, audit_visual. The naming is predictable and uniform throughout.
Tool Count5/5
Four tools map cleanly onto a coherent design workflow. The count sits well within the 3-15 sweet spot, and each tool has a clear, non-redundant role.
Completeness4/5
The surface covers the full end-to-end workflow: parse requirements, extract tokens, generate a design, and audit the visual result. A minor gap exists in that there is no explicit tool to refine or fix the design based on audit findings, though an agent could work around this by re-invoking generate_design.
Maintenance
ActivityInactive
ResponsivenessNo issues