"
6,Flutter,Widget Composition,组合小部件而非继承,"Container(child: Column(children: []))"
```
---
## 三、实现原理
### 3.1 项目架构
UI UX Pro Max 的项目架构清晰分层，核心与适配层分离：
```
项目根目录/
├── .shared/ # 核心共享资源（所有 AI 助手共用）
│ └── ui-ux-pro-max/
│ ├── scripts/
│ │ ├── search.py # 命令行搜索工具（入口）
│ │ └── core.py # BM25 搜索引擎核心
│ └── data/
│ ├── styles.csv # 57 种 UI 风格
│ ├── colors.csv # 95 套配色方案
│ ├── typography.csv # 56 套字体组合
│ ├── charts.csv # 24 种图表类型
│ ├── ux-guidelines.csv # 98 条 UX 指南
│ └── stacks/ # 10 种技术栈指南
│
├── .kiro/ # Kiro 适配层
│ └── steering/
│ └── ui-ux-pro-max.yaml # Kiro Steering 工作流定义
│
├── .cursor/ # Cursor 适配层
│ └── commands/
│ └── ui-ux-pro-max.md # Cursor Commands 工作流定义
│
├── .claude/ # Claude Code 适配层
│ └── skills/
│ └── ui-ux-pro-max.md # Claude Code Skills 定义
│
└── .windsurf/ # Windsurf 适配层
└── workflows/
└── ui-ux-pro-max.yaml # Windsurf Workflows 定义
```
**架构设计原则：**
1. **核心共享**：`.shared/ui-ux-pro-max/` 目录包含核心的搜索脚本和数据文件，所有 AI 助手共享使用
2. **适配分离**：每种 AI 助手有独立的配置文件，互不干扰
3. **统一接口**：无论使用哪种 AI 助手，都通过 `/ui-ux-pro-max` 斜杠命令触发
4. **易于扩展**：添加新的 AI 助手支持只需创建对应的适配层配置
### 3.2 BM25 搜索算法原理
BM25（Best Matching 25）是一种经典的信息检索算法，被广泛应用于搜索引擎中。UI UX Pro Max 使用 BM25 来实现智能设计资源搜索。
#### 3.2.1 为什么选择 BM25
| 算法 | 优点 | 缺点 |
|-----|------|------|
| **关键词匹配** | 简单直接 | 无法处理同义词，匹配精度低 |
| **TF-IDF** | 考虑词频和文档频率 | 对词频饱和处理不够好 |
| **BM25** | 词频饱和处理好，文档长度归一化 | 计算复杂度略高 |
BM25 的优势在于：
- 考虑了词频饱和效应（词频增加到一定程度后不再显著提升相关性）
- 考虑了文档长度归一化（长文档不应该因为内容多而获得更高分数）
- IDF 权重合理（稀有词获得更高权重）
#### 3.2.2 BM25 算法实现
```python
# core.py - BM25 搜索引擎核心
import math
import re
from collections import Counter
class BM25:
"""
BM25 (Best Matching 25) 搜索引擎实现
BM25 是一种基于概率的相关性模型，广泛用于信息检索系统。
它比简单的关键词匹配更智能，能够考虑词频和文档长度的影响。
"""
def __init__(self, k1=1.5, b=0.75):
"""
初始化 BM25 搜索引擎
Args:
k1: 词频饱和参数，控制词频对相关性分数的影响程度
- 值越大，词频的影响越大
- 常用值范围: 1.2-2.0
b: 文档长度归一化参数
- 值越大，长文档的惩罚越明显
- 常用值范围: 0.5-1.0
"""
self.k1 = k1
self.b = b
self.documents = []
self.doc_lengths = {}
self.avg_doc_length = 0
self.idf = {}
self.vocabulary = set()
def _tokenize(self, text):
"""
文本分词处理
将文本转换为词列表，处理大小写、标点符号等
"""
if not isinstance(text, str):
text = str(text)
text = text.lower()
tokens = re.findall(r'\b\w+\b', text)
return [token for token in tokens if len(token) > 1]
def fit(self, documents):
"""
建立文档索引
Args:
documents: 文档列表，每个文档是一个字典
"""
self.documents = documents
# 计算文档长度
self.doc_lengths = {}
all_tokens = []
for idx, doc in enumerate(documents):
# 将文档的多个字段合并成一个搜索字符串
search_text = self._build_search_text(doc)
tokens = self._tokenize(search_text)
self.doc_lengths[idx] = len(tokens)
all_tokens.extend(tokens)
self.vocabulary.update(tokens)
# 计算平均文档长度
self.avg_doc_length = sum(self.doc_lengths.values()) / len(self.doc_lengths)
# 计算每个词的 IDF 值
total_docs = len(documents)
doc_freq = Counter(all_tokens)
for token in self.vocabulary:
# IDF 公式: log((N - n + 0.5) / (n + 0.5) + 1)
df = doc_freq[token]
self.idf[token] = math.log((total_docs - df + 0.5) / (df + 0.5) + 1)
def _build_search_text(self, doc):
"""
构建文档的搜索文本
将文档的多个相关字段合并成一个文本字符串用于搜索
"""
text_parts = []
# 根据文档类型添加相关字段
if 'name' in doc:
text_parts.append(doc['name'])
if 'description' in doc:
text_parts.append(doc['description'])
if 'keywords' in doc:
if isinstance(doc['keywords'], list):
text_parts.extend(doc['keywords'])
else:
text_parts.append(doc['keywords'])
if 'style_name' in doc:
text_parts.append(doc['style_name'])
if 'industry' in doc:
text_parts.append(doc['industry'])
return ' '.join(text_parts)
def _calculate_score(self, query_tokens, doc_idx):
"""
计算查询与单个文档的相关性分数
BM25 公式:
score = Σ IDF(qi) × (tf × (k1 + 1)) / (tf + k1 × (1 - b + b × dl/avgdl))
其中:
- IDF(qi): 词 qi 的逆文档频率
- tf: 词 qi 在文档中的词频
- dl: 文档长度
- avgdl: 平均文档长度
- k1: 词频饱和参数
- b: 文档长度归一化参数
"""
doc_length = self.doc_lengths[doc_idx]
score = 0
for token in query_tokens:
if token not in self.vocabulary:
continue
# 获取词在文档中的词频
search_text = self._build_search_text(self.documents[doc_idx])
doc_tokens = self._tokenize(search_text)
tf = doc_tokens.count(token)
if tf == 0:
continue
# BM25 公式计算
idf = self.idf[token]
numerator = tf * (self.k1 + 1)
denominator = tf + self.k1 * (1 - self.b + self.b * doc_length / self.avg_doc_length)
score += idf * numerator / denominator
return score
def search(self, query, top_k=3):
"""
执行搜索
Args:
query: 搜索查询
top_k: 返回前 K 个结果
Returns:
按相关性排序的文档列表
"""
query_tokens = self._tokenize(query)
scores = []
for idx in range(len(self.documents)):
score = self._calculate_score(query_tokens, idx)
scores.append((idx, score))
# 按分数降序排序
scores.sort(key=lambda x: x[1], reverse=True)
# 返回 Top K 结果
results = []
for idx, score in scores[:top_k]:
if score > 0: # 只返回有相关性分数的结果
result = {
**self.documents[idx],
'score': score
}
results.append(result)
return results
```
#### 3.2.3 搜索流程详解
```
┌─────────────────────────────────────────────────────────────┐
│ 1. 用户发起搜索请求 │
│ python3 search.py "SaaS" --domain color │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. search.py 解析命令行参数 │
│ • query = "SaaS" │
│ • domain = "color" │
│ • top_k = 3 (默认) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. 加载对应领域的 CSV 数据 │
│ data = load_csv("colors.csv") │
│ │
│ 将 CSV 转换为文档列表: │
│ [{industry: "SaaS", primary: "#3B82F6", ...}, ...] │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. 构建 BM25 索引 │
│ • 对每个文档进行分词 │
│ • 计算每个词的 IDF 值 │
│ • 存储文档长度信息 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 5. 执行搜索 │
│ • 对查询 "SaaS" 进行分词 │
│ • 计算每个文档的 BM25 分数 │
│ • 按分数排序，返回 Top K 结果 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 6. 格式化输出结果 │
│ 将结果转换为 Markdown 格式，便于 AI 理解 │
└─────────────────────────────────────────────────────────────┘
```
### 3.3 搜索脚本入口
```python
#!/usr/bin/env python3
# search.py - 命令行搜索工具入口
import argparse
import sys
import csv
import os
from pathlib import Path
from core import BM25
def load_csv_data(domain, data_dir):
"""
加载指定领域的 CSV 数据
Args:
domain: 数据领域 (styles, colors, typography, charts, ux, stacks)
data_dir: 数据目录路径
Returns:
文档列表
"""
domain_file_map = {
'style': 'styles.csv',
'color': 'colors.csv',
'typography': 'typography.csv',
'chart': 'charts.csv',
'ux': 'ux-guidelines.csv',
'stack': 'stacks.csv',
'product': 'styles.csv',
'landing': 'styles.csv'
}
filename = domain_file_map.get(domain, f'{domain}s.csv')
filepath = Path(data_dir) / filename
if not filepath.exists():
print(f"Error: Data file not found: {filepath}")
sys.exit(1)
documents = []
with open(filepath, 'r', encoding='utf-8') as f:
reader = csv.DictReader(f)
for row in reader:
documents.append(row)
return documents
def format_results(results, domain, query):
"""
格式化搜索结果为 Markdown 格式
"""
if not results:
return f"No results found for query: {query}"
output = []
output.append(f"## UI Pro Max Search Results")
output.append(f"**Domain:** {domain} | **Query:** {query}")
output.append(f"**Source:** {results[0].get('source', 'unknown')} | **Found:** {len(results)} results")
output.append("")
for idx, result in enumerate(results, 1):
output.append(f"### Result {idx}")
# 根据不同领域显示不同的字段
if domain == 'color':
output.append(f"- **Industry:** {result.get('industry', 'N/A')}")
output.append(f"- **Style:** {result.get('style', 'N/A')}")
output.append(f"- **Primary (Hex):** {result.get('primary', 'N/A')}")
output.append(f"- **Secondary (Hex):** {result.get('secondary', 'N/A')}")
output.append(f"- **CTA (Hex):** {result.get('cta', 'N/A')}")
output.append(f"- **Background (Hex):** {result.get('background', 'N/A')}")
output.append(f"- **Text (Hex):** {result.get('text', 'N/A')}")
elif domain == 'style':
output.append(f"- **Style Name:** {result.get('style_name', 'N/A')}")
output.append(f"- **Description:** {result.get('description', 'N/A')}")
output.append(f"- **Keywords:** {result.get('keywords', 'N/A')}")
output.append(f"- **Code Example:** {result.get('code_example', 'N/A')}")
elif domain == 'typography':
output.append(f"- **Pairing Name:** {result.get('pairing_name', 'N/A')}")
output.append(f"- **Heading Font:** {result.get('heading_font', 'N/A')}")
output.append(f"- **Body Font:** {result.get('body_font', 'N/A')}")
output.append(f"- **Google Import:** {result.get('google_import', 'N/A')}")
elif domain == 'ux':
output.append(f"- **Category:** {result.get('category', 'N/A')}")
output.append(f"- **Guideline:** {result.get('guideline', 'N/A')}")
output.append(f"- **Description:** {result.get('description', 'N/A')}")
output.append("")
return '\n'.join(output)
def auto_detect_domain(query):
"""
自动检测搜索领域
根据查询关键词判断用户想要搜索的数据领域
"""
query_lower = query.lower()
domain_keywords = {
"color": ["color", "palette", "hex", "rgb", "primary", "secondary", "cta"],
"chart": ["chart", "graph", "visualization", "trend", "pie", "bar", "line"],
"landing": ["landing", "page", "cta", "hero", "pricing", "features"],
"product": ["saas", "ecommerce", "fintech", "healthcare", "app", "platform"],
"style": ["style", "design", "glassmorphism", "minimalism", "brutalism", "dark mode"],
"typography": ["font", "typography", "serif", "heading", "body text", "readable"],
"ux": ["ux", "accessibility", "animation", "mobile", "responsive", "interaction"],
"stack": ["react", "vue", "next", "angular", "flutter", "tailwind", "css"]
}
for domain, keywords in domain_keywords.items():
for keyword in keywords:
if keyword in query_lower:
return domain
return "style" # 默认返回 style 领域
def main():
"""
主函数：解析参数并执行搜索
"""
parser = argparse.ArgumentParser(
description="UI UX Pro Max Search Tool - Search design resources using BM25 algorithm"
)
parser.add_argument(
"query",
help="Search query"
)
parser.add_argument(
"--domain",
"-d",
help="Search domain (color, style, typography, chart, ux, stack)",
default=None
)
parser.add_argument(
"--top-k",
"-k",
help="Number of results to return",
type=int,
default=3
)
parser.add_argument(
"--data-dir",
help="Directory containing data files",
default=".shared/ui-ux-pro-max/data"
)
args = parser.parse_args()
# 自动检测领域（如果未指定）
domain = args.domain if args.domain else auto_detect_domain(args.query)
# 加载数据
documents = load_csv_data(domain, args.data_dir)
# 构建 BM25 索引
bm25 = BM25(k1=1.5, b=0.75)
bm25.fit(documents)
# 执行搜索
results = bm25.search(args.query, top_k=args.top_k)
# 输出结果
formatted_output = format_results(results, domain, args.query)
print(formatted_output)
if __name__ == "__main__":
main()
```
### 3.4 数据模块化设计
UI UX Pro Max 的数据采用模块化设计，便于维护和扩展：
```
data/
├── styles.csv # UI 风格库
├── colors.csv # 配色方案
├── typography.csv # 字体配对
├── charts.csv # 图表类型
├── ux-guidelines.csv # UX 指南
├── stacks/ # 技术栈指南
│ ├── react.yaml
│ ├── vue.yaml
│ ├── nextjs.yaml
│ └── tailwindcss.yaml
└── industries/ # 行业特定配置
├── saas.yaml
├── healthcare.yaml
└── ecommerce.yaml
```
**模块化优势：**
- **易于更新**：添加或修改设计资源只需编辑对应的 CSV 文件
- **易于扩展**：添加新的数据领域只需创建新的 CSV 文件
- **便于维护**：每个模块职责单一，便于测试和验证
---
## 四、使用方法（以 Kiro 为例）
### 4.1 安装方式
#### 方式一：使用 CLI 工具（推荐）
```bash
# 全局安装 CLI 工具
npm install -g uipro-cli
# 进入你的项目目录
cd /path/to/your/project
# 为 Kiro 安装 UI UX Pro Max
uipro init --ai kiro
```
#### 方式二：手动安装
将以下文件夹复制到项目根目录：
```
项目根目录/
├── .kiro/
│ └── steering/
│ └── ui-ux-pro-max.yaml # Kiro Steering 工作流定义
│
└── .shared/
└── ui-ux-pro-max/
├── scripts/
│ ├── search.py # 命令行搜索工具
│ └── core.py # BM25 搜索引擎核心
└── data/
├── styles.csv # 57 种 UI 风格
├── colors.csv # 95 套配色方案
├── typography.csv # 56 套字体组合
├── charts.csv # 24 种图表类型
├── ux-guidelines.csv # 98 条 UX 指南
└── stacks/ # 10 种技术栈指南
```
### 4.2 使用方法
安装完成后，在 Kiro 的对话框中使用斜杠命令触发：
```
/ui-ux-pro-max 帮我做一个 SaaS 产品的落地页
```
### 4.3 使用示例
#### 示例 1：创建 SaaS 落地页
```
/ui-ux-pro-max 创建一个 SaaS 产品的登录页面
```
Kiro 会自动：
1. 加载 UI UX Pro Max 工作流定义
2. 分析用户需求，提取关键信息
3. 调用搜索脚本获取设计资源
4. 生成符合专业标准的 UI 代码
#### 示例 2：设计医疗数据仪表盘
```
/ui-ux-pro-max 设计一个医疗数据分析仪表盘
```
Kiro 会：
1. 搜索医疗行业配色方案
2. 获取仪表盘布局模式
3. 选择合适的数据可视化图表
4. 应用无障碍设计指南
#### 示例 3：美容 SPA 落地页
```
/ui-ux-pro-max 帮我做一个美容 SPA 的落地页
```
### 4.4 工作流程详解（Kiro 版本）
```
┌─────────────────────────────────────────────────────────────┐
│ 用户输入：/ui-ux-pro-max 帮我做一个 SaaS 落地页 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Kiro 加载 Steering 工作流定义 │
│ .kiro/steering/ui-ux-pro-max.yaml │
│ │
│ 该文件定义： │
│ • AI 角色：UI/UX 专家 │
│ • 工作流步骤：分析需求 → 搜索资源 → 生成代码 → 质量检查 │
│ • 约束条件：语义化 HTML、无障碍、可访问性 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ AI 分析用户需求，提取关键信息： │
│ • 产品类型：SaaS │
│ • 页面类型：登录页 │
│ • 风格关键词：modern professional │
│ • 技术栈：html-tailwind │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Kiro 执行搜索步骤（调用 search.py）： │
│ │
│ 步骤1: python3 search.py "SaaS" --domain product │
│ 步骤2: python3 search.py "modern professional" --domain style │
│ 步骤3: python3 search.py "tech SaaS" --domain color │
│ 步骤4: python3 search.py "professional" --domain typography│
│ 步骤5: python3 search.py "login" --domain landing │
│ 步骤6: python3 search.py "animation" --domain ux │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ AI 综合搜索结果，生成专业 UI 代码 │
│ • 应用推荐的配色方案（信任蓝 #3B82F6） │
│ • 使用推荐的字体组合（Sora + Inter） │
│ • 遵循 UX 最佳实践 │
│ • 按技术栈指南编写代码（html-tailwind） │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Kiro 执行质量检查： │
│ • 颜色对比度检查（WCAG AA） │
│ • 无障碍属性检查（ARIA labels） │
│ • 语义化 HTML 检查 │
│ • 响应式设计检查 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 输出最终代码并提供修改建议 │
└─────────────────────────────────────────────────────────────┘
```
### 4.5 Kiro Steering 配置文件示例
```yaml
# .kiro/steering/ui-ux-pro-max.yaml
apiVersion: kiro.ai/v1
kind: Steering
metadata:
name: ui-ux-pro-max
description: UI UX Pro Max Design Workflow
version: 1.0.0
inclusion: manual
steering:
context:
description: |
You are an expert UI/UX designer with deep knowledge of modern web design.
You have access to a comprehensive design knowledge base through the search.py script.
domain_knowledge:
- UI styles: Glassmorphism, Minimalism, Brutalism, Neumorphism
- Color schemes: SaaS, Healthcare, Beauty, Fintech, E-commerce
- Typography: Google Fonts pairings
- UX guidelines: Accessibility, Animation, Mobile
steps:
- name: analyze_requirements
description: Extract key information from user request
action: |
Analyze the request and extract:
- Product type (SaaS, e-commerce, healthcare, etc.)
- Page type (landing, dashboard, login, etc.)
- Style keywords (minimal, modern, elegant, etc.)
- Technology stack (React, Vue, html-tailwind)
- name: search_design_resources
description: Search for design resources
action: |
Use search.py to gather information:
python3 .shared/ui-ux-pro-max/scripts/search.py "
" --domain product
python3 .shared/ui-ux-pro-max/scripts/search.py "
"
4,Mobile,Touch Target Size,触摸目标至少为 44x44 像素,".button { min-height: 44px; min-width: 44px; }"
5,Mobile,Responsive Images,图片需要适配不同屏幕尺寸,"
"
6,Animation,Reduce Motion,尊重用户减少动画的偏好,"@media (prefers-reduced-motion: reduce) { * { animation: none; } }"
7,Animation,Smooth Performance,动画帧率应达到 60fps,"transform: translateZ(0); will-change: transform;"
```
### 2.6 技术栈指南详解
技术栈指南为每种主流前端框架提供了代码规范和最佳实践：
```csv
id,stack,guideline,description,code_example
1,React,Component Structure,遵循组件文件夹结构规范,"components/Button/index.tsx"
2,React,Hooks Usage,使用 Hooks 而非 class 组件,"const [count, setCount] = useState(0);"
3,Vue,Composition API,使用 Composition API 而非 Options API,""
4,Next.js,Image Optimization,使用 next/image 优化图片,"