build-design-system

Files (2)

• SKILL.md
• generate.mjs · scripts/

SKILL.md (first lines)

# 构建设计系统

从目标网页采集设计令牌，生成 DESIGN.md 设计规范 + Tailwind CSS 主题。

## 前置条件

- Node.js >= 18
- 已安装 `extract-page-data` 或 `clone-page` 技能（用于数据采集）

## 工作流

### Step 1: 采集设计数据 + 截图

使用 `extract-page-data` 或 `clone-page` 技能采集 theme.json + 多维度截图；也可以使用 Playwright、浏览器自动化、in-app Browser/Chrome 或其他等效工具替代，只要能稳定产出截图、响应式截图和 token/样式证据即可：

```bash
# 方式 A: extract-page-data（快速采集）
node <extract-page-data>/scripts/extract.mjs <url> --theme --screenshot --scroll -o ./theme-data

# 方式 B: clone-page（采集 + 多视口截图 + section 截图，推荐）
node <clone-page>/scripts/clone.mjs <url> quick -o ./theme-data --scroll
node <clone-page>/scripts/clone.mjs <url> responsive -o ./theme-data
# 按需采集关键 section 的截图
node <clone-page>/scripts/clone.mjs <url> styles -o ./theme-data --selector "header"
node <clone-page>/scripts/clone.mjs <url> styles -o ./theme-data --selector "main > section:nth-child(1)"
node <clone-page>/scripts/clone.mjs <url> styles -o ./theme-data --selector "footer"
```

采集后 `theme-data/` 中应有：
- `theme.json` — 设计令牌（颜色、字体、间距、圆角、阴影、动画…）
- `screenshot.png` — **全页截图（最重要的参考）**
- `responsive/` — 多视口截图（desktop/tablet/mobile）
- `sections/*/screenshot.png` — 各 section 的独立截图

### Step 2: 截图分析（最关键的一步）

**截图是设计规范的最终真相**。很多关键设计信息只存在于截图中，无法从 CSS 属性提取：

#### 必须从截图中观察的设计维度

| 维度 | 截图中观察什么 | theme.json 能否提供 |
|------|--------------|-------------------|
| 🎨 品牌调性 | 整体视觉风格——极简/科技/温暖/高端/活泼 | ❌ 无法 |
| 📐 布局节奏 | Section 之间的留白比例、内容密度、对齐方式 | ❌ 无法 |
| 🖼️ 视觉层级 | 哪些元素突出、视觉重心在哪里、信息优先级 | ❌ 无法 |
| 🎭 装饰元素 | 背景图案、渐变方向、毛玻璃效果、光影效果 | ⚠️ 部分 |
| 📱 响应式策略 | 不同视口下的布局变化、元素隐藏/重排规则 | ❌ 无法 |
| 🧩 组件风格 | 按钮形状/大小、卡片样式、导航模式、表单风格 | ⚠️ 部分 |
| 🔤 字体排版 | 标题层级视觉感受、段落间距、文本对齐 | ⚠️ 部分 |
| 🌈 渐变方向 | 从左到右/从上到下/径向，渐变色的过渡感 | ❌ 无法 |
| 📸 图片风格 | 摄影/插画/3D/图标风格、图片圆角、纵横比 | ❌ 无法 |
| ☀️ 明暗氛围 | 页面整体是亮色系还是暗色系、色彩饱和度倾向 | ⚠️ 部分 |

#### 截图分析步骤

1. **看全页截图** `screenshot.png`：
   - 判断品牌调性（3-5 个关键词描述）
   - 识别主色调和辅色调
   - 观察整体布局模式（单栏/双栏/网格/卡片流）
   - 注意装饰元素（渐变背景/噪点纹理/光效/几何图案）

2. **看响应式截图** `responsive/`：
   - 对比 desktop vs tablet vs mobile 的布局变化
   - 记录哪些元素在小屏隐藏/折叠
   - 观察导航模式变化（横排 → 汉堡菜单）

3. **看 section 截图** `sections/*/screenshot.png`：
   - 每个区域的独立视觉风格
   - 组件的具体形态（按钮样式、卡片样式、表单样式）
   - 图片和装饰的使用方式

**分析结果应直接写入 DESIGN.md 的「视觉主题与氛围」「布局与间距」「组件规范」「响应式行为」等章节。**

### Step 3: 分析 theme.json

读取 `theme.json`，对每个 token 类别进行分析和归类：

```bash
# 查看采集的设计令牌
cat theme-data/theme.json
```

理解要点：
- `colors.background[0]` — 主背景色
- `colors.text[0]` — 主文本色
- `typography.families[0]` — 主字体
- `spacing` — 间距体系
- `radius` — 圆角体系
- `shadow.box` — 阴影体系
- `transitions` — 过渡动画
- `animations` — CSS 动画
- `cssVariables` — 页面已有的 CSS 变量（如果有，优先使用）

**⚠️ 注意：** theme.json 的数据是机器提取的属性值，可能有遗漏或偏差。当 theme.json 的值与截图中观察到的视觉效果冲突时，**以截图为准**。

### Step 4: 生成产物

输出目录结构：

```
<output>/
├── DESIGN.md            # 设计规范文档（getdesign.md / DESIGN.md 9 段式标准）
├── globals.css          # Tailwind CSS v4 主题定义
└── screenshots/         # 视觉参考截图
    ├── full-page.png    # 全页截图
    ├── desktop.png      # 桌面视图
    ├── tablet.png       # 平板视图
    ├── mobile.png       # 手机视图
    ├── header.png       # 头部截图
    └── ...              # 其他 section 截图
```

---

## DESIGN.md 生成规范

**格式参考 getdesign.md / DESIGN.md 标准**：纯 Markdown，面向 AI 和人类双重可读。`DESIGN.md` 必须是可执行的设计规范，不能只写氛围描述。

### 强制 9 段式内容

From lintendo/Axhub-Skills, MIT.

More from lintendo/Axhub-Skills