generate-theme

Generate Theme

This capability has been migrated to $build-design-system. For new tasks, prefer the new name; the current entry point remains compatible with existing installations and calls.

Collect design tokens from the target web page and generate a DESIGN.md design specification + Tailwind CSS theme.

Prerequisites

• Node.js >= 18
• Installed extract-page-data or clone-page skill (for data collection)

Workflow

Step 1: Collect design data + screenshots

Use the extract-page-data or clone-page skill to collect theme.json + multi-dimensional screenshots; you may also use Playwright, browser automation, in-app Browser/Chrome, or other equivalent tools instead, as long as they can reliably produce screenshots, responsive screenshots, and token/style evidence:

# 方式 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"

After collection, theme-data/ should contain:

• theme.json — design tokens (colors, fonts, spacing, border radius, shadows, animations…)
• screenshot.png — Full-page screenshot (the most important reference)
• responsive/ — multi-viewport screenshots (desktop/tablet/mobile)
• sections/*/screenshot.png — individual screenshots of each section

Step 2: Screenshot analysis (the most critical step)

Screenshots are the ultimate truth of the design specification. Much key design information exists only in screenshots and cannot be extracted from CSS properties:

Design dimensions that must be observed from screenshots

Dimension	What to observe in the screenshot	Can theme.json provide it
🎨 Brand tone	Overall visual style—minimal/tech/warm/high-end/lively	❌ Cannot
📐 Layout rhythm	Whitespace ratio between sections, content density, alignment	❌ Cannot
🖼️ Visual hierarchy	Which elements stand out, where the visual focus is, information priority	❌ Cannot
🎭 Decorative elements	Background patterns, gradient direction, frosted glass effects, light and shadow effects	⚠️ Partial
📱 Responsive strategy	Layout changes across viewports, element hiding/reordering rules	❌ Cannot
🧩 Component style	Button shape/size, card style, navigation mode, form style	⚠️ Partial
🔤 Typography	Visual feel of heading hierarchy, paragraph spacing, text alignment	⚠️ Partial
🌈 Gradient direction	Left to right/top to bottom/radial, the transition feel of gradient colors	❌ Cannot
📸 Image style	Photography/illustration/3D/icon style, image border radius, aspect ratio	❌ Cannot
☀️ Light/dark atmosphere	Whether the page overall is light or dark, color saturation tendency	⚠️ Partial

Screenshot analysis steps

1. View the full-page screenshot screenshot.png：

   • Determine the brand tone (described with 3-5 keywords)
   • Identify the primary and secondary colors
   • Observe the overall layout pattern (single column/two column/grid/card flow)
   • Note the decorative elements (gradient backgrounds/noise textures/light effects/geometric patterns)

2. View the responsive screenshots responsive/：

   • Compare the layout changes across desktop vs tablet vs mobile
   • Record which elements are hidden/collapsed on small screens
   • Observe the navigation pattern changes (horizontal row → hamburger menu)

3. View the section screenshots sections/*/screenshot.png：

   • The independent visual style of each area
   • The specific forms of components (button styles, card styles, form styles)
   • How images and decorations are used

The analysis results should be written directly into the sections of DESIGN.md such as "Visual Theme and Atmosphere", "Layout and Spacing", "Component Specifications", and "Responsive Behavior".

Step 3: Analyze theme.json

Read theme.json, and analyze and categorize each token category:

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

Key points to understand:

• colors.background[0] — Primary background color
• colors.text[0] — Primary text color
• typography.families[0] — Primary font
• spacing — Spacing system
• radius — Border radius system
• shadow.box — Shadow system
• transitions — Transition animations
• animations — CSS animations
• cssVariables — Existing CSS variables on the page (if any, use them first)

⚠️ Note: The data in theme.json consists of machine-extracted property values and may have omissions or deviations. When the values in theme.json conflict with the visual effects observed in the screenshots,the screenshots shall prevail。

Step 4: Generate the artifacts

Output directory structure:

<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 generation specification

Format reference: getdesign.md / DESIGN.md standard: Pure Markdown, readable by both AI and humans.DESIGN.md It must be an executable design specification, not just atmosphere descriptions.

Mandatory 9-section content

The generated DESIGN.md must cover the following 9 parts; when source evidence is lacking, explicitly write "No clear rules were collected; handle with conservative defaults", and do not fabricate brand rules or component details.

1. Visual Theme and Atmosphere: Brand/product background, applicable scenarios, inapplicable scenarios, keywords, page temperament, information density, and brand expression boundaries.
2. Color System: Hex values, semantic roles, usage boundaries, prohibited scenarios, and Tailwind/CSS variable mappings.
3. Typography System: display/body/mono roles, font families, font size hierarchy, line height, font weight, letter spacing, and fallback.
4. Component Specifications: The dimensions, border radius, borders, states, and interaction behaviors of basic components such as buttons, input fields, cards, navigation, tables, tags, and modals.
5. Layout and Spacing: Container width, grid, section rhythm, density, default layout before breakpoints, spacing scale, and page-level whitespace.
6. Depth, Shadows, and Borders: Shadow hierarchy, borders/dividers, ring, elevation, surface stacking rules, and prohibited overly heavy decoration.
7. Motion: Duration, easing, transform patterns, appear/exit/hover rules, and available and prohibited motion effects.
8. Responsive behavior: desktop/tablet/mobile layout changes, navigation collapse, element show/hide, image/table/card reflow strategies.
9. Prompt guide: ready-made generation instructions for the LLM, including recommended approaches, prohibited approaches, and directly reusable UI generation prompts.

Document structure template

The template below is the basic structure; when generating, it must be completed according to the 9-section format above, and components, depth/borders, responsive behavior, and the Prompt guide must not be omitted.

# [品牌名] 设计系统

> 从 [原始 URL] 提取的设计规范

## 视觉风格

> 👁️ 以下内容基于截图观察总结，是本设计系统的灵魂。

- **品牌调性**: [从截图推断，如：科技感/极简/温暖/高端/活泼]
- **色彩氛围**: [亮色系/暗色系/高饱和/低饱和]
- **布局风格**: [宽松留白/紧凑密集/卡片式/列表式]
- **装饰特征**: [渐变背景/毛玻璃/几何图案/纯色块/无装饰]
- **图片风格**: [摄影/插画/3D/图标/无图]

## 设计原则

- [从截图和品牌调性推断 3-5 条设计原则]

---

## 🎨 色彩系统

### 基础色板

| 名称 | 值 | Tailwind | 用途 |
|------|----|---------|----- |
| Primary | #XXXX | `bg-primary` / `text-primary` | 品牌主色、CTA 按钮 |
| Secondary | #XXXX | `bg-secondary` | 辅助强调 |
| Background | #XXXX | `bg-background` | 页面底色 |
| Foreground | #XXXX | `text-foreground` | 主要文本 |
| Muted | #XXXX | `bg-muted` / `text-muted` | 次要文本、禁用态 |
| Border | #XXXX | `border-border` | 分割线、边框 |
| Accent | #XXXX | `bg-accent` | 高亮、标签 |
| Destructive | #XXXX | `bg-destructive` | 错误、删除 |

### 色彩规范

| 级别 | 规则 |
|------|------|
| ✅ 推荐 | 使用语义化变量 `bg-primary`, `text-foreground` 而非硬编码色值 |
| ✅ 推荐 | 深色模式通过 `.dark` 类切换，不使用 `prefers-color-scheme` |
| ⚠️ 允许 | 在特殊装饰场景下使用渐变色 |
| 🚫 禁止 | 硬编码 `#RRGGBB` 值，必须使用 CSS 变量 |
| 🚫 禁止 | 在文本上使用低对比度颜色（对比度 < 4.5:1） |

---

## 📝 字体系统

### 字体家族

| 名称 | 字体 | Tailwind | 用途 |
|------|------|---------|----- |
| Sans | Inter, system-ui, sans-serif | `font-sans` | 正文、UI 组件 |
| Mono | JetBrains Mono, monospace | `font-mono` | 代码块 |

### 文字样式

| 层级 | 大小 | 行高 | 字重 | Tailwind |
|------|------|------|------|---------|
| H1 | 36px | 44px | 700 | `text-4xl font-bold` |
| H2 | 30px | 36px | 600 | `text-3xl font-semibold` |
| H3 | 24px | 32px | 600 | `text-2xl font-semibold` |
| Body | 16px | 24px | 400 | `text-base` |
| Small | 14px | 20px | 400 | `text-sm` |
| Caption | 12px | 16px | 400 | `text-xs` |

### 字体规范

| 级别 | 规则 |
|------|------|
| ✅ 推荐 | 标题使用 font-semibold 或 font-bold |
| ✅ 推荐 | 正文行高 1.5（24px / 16px） |
| ⚠️ 允许 | 在 Hero 区域使用更大的标题（最大 48px） |
| 🚫 禁止 | 使用超过 3 种字体 |
| 🚫 禁止 | 正文字号低于 14px |

---

## 📏 间距系统

### 间距标尺

| 级别 | 值 | Tailwind | 用途 |
|------|----|---------|----- |
| xs | 4px | `p-1` / `gap-1` | 图标与文字间距 |
| sm | 8px | `p-2` / `gap-2` | 紧凑元素间距 |
| md | 16px | `p-4` / `gap-4` | 默认内边距 |
| lg | 24px | `p-6` / `gap-6` | Section 间距 |
| xl | 32px | `p-8` / `gap-8` | 大区块间隔 |
| 2xl | 48px | `p-12` / `gap-12` | Section 分隔 |

### 间距规范

| 级别 | 规则 |
|------|------|
| ✅ 推荐 | 使用 4px 的倍数（4, 8, 12, 16, 24, 32...） |
| ✅ 推荐 | 同级元素间距保持一致 |
| 🚫 禁止 | 使用奇数 px 值（如 5px, 7px, 13px） |

---

## 🔲 圆角系统

| 名称 | 值 | Tailwind | 用途 |
|------|----|---------|----- |
| None | 0 | `rounded-none` | 表格、分割线 |
| SM | 4px | `rounded-sm` | 小按钮、标签 |
| MD | 8px | `rounded-md` | 默认按钮、输入框 |
| LG | 12px | `rounded-lg` | 卡片、弹窗 |
| XL | 16px | `rounded-xl` | 大卡片、面板 |
| Full | 9999px | `rounded-full` | 头像、药丸按钮 |

### 圆角规范

| 级别 | 规则 |
|------|------|
| ✅ 推荐 | 按钮统一使用 `rounded-md` |
| ✅ 推荐 | 卡片统一使用 `rounded-lg` |
| 🚫 禁止 | 同一页面混用超过 4 种圆角值 |

---

## 🌑 阴影系统

| 名称 | 值 | Tailwind | 用途 |
|------|----|---------|----- |
| SM | 0 1px 2px rgba(0,0,0,0.05) | `shadow-sm` | 按钮默认态 |
| MD | 0 4px 6px rgba(0,0,0,0.1) | `shadow-md` | 卡片悬浮态 |
| LG | 0 10px 15px rgba(0,0,0,0.1) | `shadow-lg` | 弹窗、下拉菜单 |

### 阴影规范

| 级别 | 规则 |
|------|------|
| ✅ 推荐 | 交互元素 hover 时提升 1 级阴影 |
| ⚠️ 允许 | 在强调区域使用彩色阴影 |
| 🚫 禁止 | 使用黑色（opacity > 0.3）的重阴影 |

---

## 🎞️ 动画 & 过渡

### 过渡 Transition

| 属性 | 值 | Tailwind | 用途 |
|------|----|---------|----- |
| Default | all 0.2s ease | `transition-all duration-200` | 按钮、链接 hover |
| Slow | all 0.3s ease-out | `transition-all duration-300` | 卡片展开、面板 |

### 动画 Animation

| 名称 | 描述 | Tailwind |
|------|------|---------|
| fadeIn | 淡入（opacity 0→1） | `animate-in fade-in` |
| slideUp | 上滑进入 | `animate-in slide-in-from-bottom` |

### 动画规范

| 级别 | 规则 |
|------|------|
| ✅ 推荐 | 交互反馈使用 200ms 过渡 |
| ✅ 推荐 | 页面进场动画使用 300-500ms |
| ⚠️ 允许 | 在 Hero 区域使用循环动画 |
| 🚫 禁止 | 动画时长超过 1s（用户感知为卡顿） |
| 🚫 禁止 | 使用 `animation-delay` 超过 500ms |

---

## 📐 布局

### 容器宽度

| 断点 | 宽度 | Tailwind |
|------|------|---------|
| sm | 640px | `max-w-screen-sm` |
| md | 768px | `max-w-screen-md` |
| lg | 1024px | `max-w-screen-lg` |
| xl | 1280px | `max-w-screen-xl` |

### 布局规范

| 级别 | 规则 |
|------|------|
| ✅ 推荐 | 主容器使用 `max-w-screen-xl` 居中 |
| ✅ 推荐 | 使用 flexbox / grid 布局，不使用 float |
| 🚫 禁止 | 内容区宽度超过 1440px |

---

## 🧩 组件规范

### Button

| 变体 | 样式 |
|------|------|
| Primary | `bg-primary text-white rounded-md px-4 py-2 shadow-sm hover:shadow-md` |
| Secondary | `bg-secondary text-secondary-foreground rounded-md px-4 py-2` |
| Ghost | `bg-transparent hover:bg-muted text-foreground rounded-md px-4 py-2` |
| Destructive | `bg-destructive text-white rounded-md px-4 py-2` |

### Card

bg-background border border-border rounded-lg p-6 shadow-sm hover:shadow-md transition-shadow

### Input

bg-background border border-border rounded-md px-3 py-2 text-foreground focus:ring-2 focus:ring-primary/20 focus:border-primary transition-colors

---

## 使用约束

### ✅ 推荐

- 所有颜色使用 CSS 变量 / Tailwind 语义类
- 保持 4px 间距基准
- 交互元素添加 hover/focus 反馈
- 使用语义化 HTML 标签

### 🚫 禁止

- 硬编码色值
- 使用 `!important`
- 内联样式代替 Tailwind 类
- 未定义的 magic number（如 `margin: 13px`）

---

## Prompt guide

### 推荐指令

- 使用本 DESIGN.md 中的语义颜色、字体、圆角、阴影和间距 token。
- 先还原整体布局节奏，再微调组件状态。
- 按响应式行为处理 desktop/tablet/mobile，不让内容溢出。

### 禁止指令

- 不要硬编码未登记色值、字体、圆角、阴影或间距。
- 不要使用低对比度文本、过度阴影或与品牌无关的装饰。
- 不要忽略组件的 hover/focus/disabled 状态。

### 可直接复用的生成提示

- "Design a [页面/组件] using this DESIGN.md: apply the semantic palette, typography roles, layout rhythm, component states, and responsive behavior."
- "Before finalizing, check every visible color, font, radius, shadow, motion, and spacing against this DESIGN.md."

---

globals.css generation specification

Mandatory use of Tailwind CSS v4 syntax:

@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

:root {
  /* ── 色彩 ──────────────────── */
  --background: <从 theme.json colors.background[0] 提取>;
  --foreground: <从 theme.json colors.text[0] 提取>;
  --primary: <从 theme.json colors.text[1] 或 CSS 变量中推断>;
  --primary-foreground: <对比色计算>;
  --secondary: <从 theme.json 推断>;
  --secondary-foreground: <对比色>;
  --muted: <从 theme.json 推断浅色>;
  --muted-foreground: <次要文本色>;
  --accent: <强调色>;
  --accent-foreground: <对比色>;
  --destructive: <错误/危险色，若无则默认 #ef4444>;
  --border: <从 theme.json colors.border[0] 提取>;
  --ring: <焦点环色，通常 = primary 带透明度>;

  /* ── 圆角 ──────────────────── */
  --radius: <从 theme.json radius[0] 提取>;

  /* ── 字体 ──────────────────── */
  --font-sans: <从 theme.json typography.families[0] 提取>;
  --font-mono: <从 theme.json typography.families 提取 monospace>;
}

.dark {
  --background: <深色模式背景>;
  --foreground: <深色模式文本>;
  /* ... 所有变量的深色模式值 ... */
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-ring: var(--ring);
  --radius-sm: calc(var(--radius) * 0.5);
  --radius-md: var(--radius);
  --radius-lg: calc(var(--radius) * 1.5);
  --radius-xl: calc(var(--radius) * 2);
  --font-sans: var(--font-sans);
  --font-mono: var(--font-mono);
}

globals.css generation key points

1. CSS variable names follow the shadcn/ui naming convention（background, foreground, primary, muted, accent, destructive, border, ring）
2. Color values are mapped from theme.json：
   • colors.background[0].value → --background
   • colors.text[0].value → --foreground
   • cssVariables values are used with priority (preserving the original design system naming)
3. @theme inline mapped to Tailwind
4. Must include dark mode(if it cannot be inferred from theme.json, use inverted colors)
5. Border radius is extracted from radius[0] , and other levels are derived using calc

---

Token category mapping table

Mapping from theme.json to DESIGN.md:

theme.json field	DESIGN.md section	globals.css variable
colors.background	Color system > Base palette	--background
colors.text	Color system > Base palette	--foreground, --primary
colors.border	Color system > Base palette	--border
typography.families	Typography system > Font family	--font-sans, --font-mono
typography.textStyles	Typography system > Text styles	—
spacing	Spacing system	—
radius	Border radius system	--radius
shadow.box	Shadow system	—
shadow.text	Shadow system	—
transitions	Animation & transition	—
animations	Animation & transition	—
lineWidth	Borders	—
cssVariables	Global — reuse with priority	Use directly
assets.images	(reference)	—

---

Data source priority

Priority	Data source	What it provides	Reliability
⭐⭐⭐⭐⭐	Screenshots (full page + responsive + section)	Brand tone, layout rhythm, visual hierarchy, decorative elements, component forms	Highest — visual truth
⭐⭐⭐⭐	cssVariables (:root variables)	Naming and values of the original design system	High — developer intent
⭐⭐⭐	theme.json (colors/fonts/spacing/shadows)	Statistical frequency of property values	Medium — machine-extracted, may have omissions

Tips

• Screenshots are the final truth — when token data and screenshots conflict,always defer to the screenshots. Gradients, decorations, and typographic rhythm visible in screenshots cannot be extracted from CSS properties
• Look at screenshots first, then read data — in the workflow, screenshot analysis comes before theme.json analysis; this is intentional. Build visual intuition first, then verify with data
• Responsive screenshots reveal layout strategy — comparing the three desktop/tablet/mobile images can reveal breakpoint layout logic and element show/hide rules
• Section screenshots precisely locate component styles — full-page screenshots are too small to see details; section screenshots are key to observing button/card/form styles
• cssVariables are a goldmine — If the page already defines the :root variables, use them first, because this is the intent of the original design system
• The higher the count, the more important it is — The count field in theme.json indicates the number of times the value appears; a higher count = a core value of the design system
• Recommended/Allowed/Prohibited — Each token category must include a three-level specification table
• Tailwind class name mapping — Each token in DESIGN.md must be given its corresponding Tailwind class name