ai-design-expert

ai-design-expert

Provides design capabilities including requirement analysis, visual token extraction, design generation, and visual auditing.

Category
Visit Server

README

🎨 AI 设计专家 - Claude Code 技能

从需求��设计稿的自动化流水线 - 一个为 Claude Code 打造的设计专家 Skill

📖 简介

AI 设计专家 是一个 Claude Code 技能（Skill），通过 MCP (Model Context Protocol) 服务器提供强大的设计能力。

核心功能

功能 描述
需求解析 分析 Word/PDF/MD 文档，提取设计要求
视觉解码 从设计图提取 Design Tokens（颜色、间距、字体等）
设计生成 根据需求和 Tokens 生成 HTML/Tailwind 代码
视觉审计 对比生成代码与参考图，提供改进建议

🚀 快速开始

1. 安装依赖

npm install

2. 构建项目

npm run build

3. 配置 Claude Code

在项目根目录的 .claude.json 中添加：

{
  "mcpServers": {
    "ai-design-expert": {
      "command": "node",
      "args": ["dist/mcp/server.js"]
    }
  }
}

或使用绝对路径：

{
  "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

解析需求文档，提取设计要素。

输入:

{
  "filePath": "docs/requirements/raw/example.md"
}

输出: 需求分析 JSON

extract_tokens

从设计图提取 Design Tokens。

输入:

{
  "imagePath": "docs/references/design.png"
}

输出: Design Tokens JSON

generate_design

生成 HTML/Tailwind 设计稿。

输入:

{
  "requirement": {...},
  "tokens": {...},
  "outputPath": "output/"
}

输出: 完整的 HTML 代码

audit_visual

视觉审计，对比代码与参考图。

输入:

{
  "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 })
   → 审计报告 + 改进建议
  ↓
最终交付：完整的设计稿

🧪 开发

# 开发模式（测试 MCP Server）
npm run dev
# 应该看到: ✅ AI 设计专家 MCP 服务器已启动

# 构建
npm run build

# 运行测试
npm test

# 代码检查
npm run lint

# 格式化代码
npm run format

🔧 故障排除

MCP 服务器未启动

检查:

npm run dev
# 应该看到: ✅ AI 设计专家 MCP 服务器已启动

找不到模块

解决:

rm -rf node_modules package-lock.json
npm install
npm run build

TypeScript 编译错误

解决:

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：

{
  "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 设计专家自动生成并维护

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

Official
Featured
Local
TypeScript
VeyraX MCP

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official
Featured
Local
graphlit-mcp-server

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official
Featured
TypeScript
Kagi MCP Server

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official
Featured
Python
E2B

E2B

Using MCP to run code via e2b.

Official
Featured
Neon Database

Neon Database

MCP server for interacting with Neon Management API and databases

Official
Featured
Exa Search

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official
Featured
Qdrant Server

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official
Featured