【技术干货】用 design.md 驯服 AI 生成前端：从 Awesome Design 到工程化落地实践

---

摘要

本文围绕 GitHub 仓库 Awesome Design（design.md 方案），系统拆解如何用"可读的设计系统描述"约束 AI Agent 生成前端 UI，解决常见的风格漂移、视觉割裂问题。文章从原理到实战，给出接入 AI 接口（基于 xuedingmao.com）的完整 Python 示例，并结合 agents.md、design.md 的双文件策略，构建可复用、可扩展的 AI 前端工作流。

---

一、背景介绍：AI 会写前端，但不会"做设计"

当前大模型 / AI Agents 生成前端代码已经不稀奇了：

React 组件、Tailwind 样式、Next.js 页面，一句 prompt 就能拉出来。

但实际落地时，大家普遍会遇到几个问题：

1. 结构能用，但视觉"一盘散沙"

   • Hero 区块还不错
   • 往下滚：间距随机、卡片样式杂乱、按钮像从别的站拷贝来的
   • 整个页面像"5 次不同 prompt 拼接"的结果

2. 提示词难以精确控制视觉

   • "做得简洁现代一点""像 Stripe 一点"这类描述，对模型来说过于模糊
   • 每次改动都要重新堆长 prompt，成本高且不可复用

3. 架构规则 + 设计规则混在一起

   • 在一个 prompt 里同时塞：
     • 技术栈要求（Next.js / Tailwind / TS...）
     • 行为逻辑（路由、状态管理）
     • 视觉风格（色板、字体、间距）
     • 文案语气
   • 模型极易"注意力分散"，导致 UI 风格漂移

视频中提到的 Awesome Design 仓库以及 design.md 方案，本质是在解决一个问题：

如何把"设计系统"变成模型可理解、可复用的文本规范，让 AI 生成的 UI 一致、可控、工程化。

---

二、核心原理：用 design.md 把"脑中的设计语言"写给模型看

2.1 design.md 到底是什么？

design.md 本质是一个 结构化的 Markdown 文档，以 AI Agent 易于读取的方式，描述完整的设计系统。典型内容包括：

• 视觉基调（Visual Mood）
  • 极简 / 高对比 / 暗色优先 / 极客风 等
• 色彩系统（Color Palette）
  • 主色 / 辅助色 / 背景 / 边框 / 状态色（Success / Warning / Error）
• 排版规则（Typography Rules）
  • 主字体 / 备选字体
  • 标题层级（H1/H2/H3）字号、行高、字重
  • 正文、辅助文案、代码字体
• 组件样式（Component Styling）
  • 按钮（主按钮 / 次按钮 / 文字按钮）
  • 卡片（阴影、圆角、边框策略）
  • 标签、输入框、表单、导航栏等
• 空间与布局（Spacing & Layout）
  • 基础间距单位（4/8/12/16...）
  • 栅格系统、内容最大宽度
  • 区块之间的层级关系与留白
• 层次与动效（Depth & Interaction）
  • 阴影层级、hover/active 状态
  • 悬浮卡片、模态框的层级规范
• 响应式行为（Responsive Behavior）
  • 不同断点的布局重排规则
  • 移动端优先 / 桌面端优先策略
• 设计护栏（Design Guard Rails）
  • 禁止使用的颜色、动效
  • 限制同时出现的组件组合
  • 避免的视觉反模式（如过多阴影、渐变堆砌）

这一点与我们常见的设计系统文档类似，只是 表达方式从设计稿 / Figma 文档变成了更"LLM 友好"的 Markdown 文本。

2.2 design.md 与 agents.md 的职责分离

仓库 README 中有一个非常关键的设计：

• agents.md：定义项目如何被构建
  • 技术栈：Next.js + React + Tailwind + TypeScript
  • 文件结构：pages / app 路由、组件组织
  • 代码规范：ESLint、命名约定
  • 业务行为：比如 Dashboard 如何调用 API
• design.md：定义项目看起来应该是什么样
  • 上面提到的视觉基调、组件样式、布局规则等

这种拆分带来的好处：

1. 提示词变短、变稳定
   • Prompt 不再反复描述"UI 要干净现代，颜色如何如何"，而是简单一句： "遵循根目录的 design.md 进行视觉实现"
2. 风格可复用
   • 同一套 design.md 可以作用于多个项目
   • 适合团队级别的"品牌设计系统"落地
3. 避免 UI 漂移
   • 多轮迭代时，模型总是回头读同一个 design.md
   • 二次 refinement 不会越改越跑偏

2.3 Awesome Design 仓库的价值

Awesome Design 做的事情是：

• 基于知名网站（Vercel、Linear、Stripe、Raycast、Supabase、Notion...）
• 为每种风格准备一套完整的：
  • design.md
  • preview.html
  • preview-dark.html

这意味着：

• 你可以在使用前，先打开 preview.html 看一眼视觉大致方向
• 再把对应 design.md 放到你的项目里，作为视觉"单一事实来源（Source of Truth）"

它不是魔法，也不是一键克隆网站，而是：

提供一套"设计纪律（design discipline）"的文本模板，让 AI 生成 UI 时有明确的依托。

---

三、实战演示：用 Python + 薛定猫 AI API 驱动 Agent 读取 design.md 生成前端

下面构造一个不依赖 Verdant 的通用工作流，用你自己的 Agent + Awesome Design 的 design.md 完成一次 Landing Page 生成，并给出可直接运行的 Python 示例。

3.1 前端项目准备思路

你可以用任意栈（Next.js、Vite、Astro 等），流程类似：

1. 初始化项目（例如 Next.js）
2. 从 Awesome Design 仓库里挑一个喜欢的设计风格，拷贝其 design.md
3. 把 design.md 放在项目根目录
4. 用 AI Agent（通过 API 调用）读取：
   • design.md
   • 你的需求描述（比如"生成一个 AI SaaS Landing Page"）
   • 约定代码格式（React + Tailwind / 纯 HTML 等）
5. 让 Agent 输出完整页面代码，写入项目文件

下面重点展示第 4、5 步：如何用 xuedingmao.com 的 OpenAI 兼容 API 驱动这个 Agent。

3.2 使用薛定猫 AI 的原因（技术选型视角）

在多模型前端生成场景下，有几个非常实际的需求：

• 需要频繁试验不同模型（Claude 4.6/GPT 5.4/Gemini 3 Pro 等）
• 希望新模型上线时能尽快用上
• 后端接入成本要低：不想为每个厂商写一套 SDK

薛定猫 AI（xuedingmao.com）的特点刚好比较适合这种需求：

• 聚合 500+ 主流大模型（含 GPT-5.4、Claude 4.6、Gemini 3 Pro 等），单一接口切换模型
• 新模型实时首发，适合追新能力的开发者
• 提供 OpenAI 兼容模式：就是 URL + KEY + model，代码层面基本按 OpenAI 写就行

这样，我们可以：

• 在同一套"design.md + prompt"基础上，横向对比不同模型生成 UI 的质量
• 根据效果和成本选择最适合自己团队的模型，而不用大改代码

3.3 完整 Python 示例：读取 design.md 生成 React Landing Page

下面是一个完整可用的示例，假设：

• 你本地有一个前端项目目录 ./my-landing
• 里面有从 Awesome Design 仓库拷贝来的 design.md
• 你希望生成 src/App.tsx 作为主页面（Vite + React 为例）
• 你使用薛定猫 AI 的 OpenAI 兼容 API，模型选用 claude-sonnet-4-6

import os
import textwrap
from typing import Optional
from openai import OpenAI

# =========================
# 配置区
# =========================

# 薛定猫 AI 平台的 API Key（从 xuedingmao.com 用户中心获取）
XDM_API_KEY = os.environ.get("XDM_API_KEY", "YOUR_XUEDINGMAO_API_KEY")

# OpenAI 兼容的 Base URL
XDM_BASE_URL = "https://xuedingmao.com/v1"

# 使用的模型，这里按要求默认使用 claude-sonnet-4-6
MODEL_NAME = "claude-sonnet-4-6"

# 前端项目根目录（包含 design.md）
PROJECT_ROOT = "./my-landing"

# 生成文件路径（以 Vite + React + TS 项目为例）
OUTPUT_FILE = os.path.join(PROJECT_ROOT, "src", "App.tsx")

# =========================
# 帮助函数
# =========================

def load_design_md(project_root: str) -> Optional[str]:
    """
    从项目根目录加载 design.md 内容。
    """
    design_path = os.path.join(project_root, "design.md")
    if not os.path.exists(design_path):
        print(f"[WARN] design.md not found at {design_path}")
        return None
    with open(design_path, "r", encoding="utf-8") as f:
        return f.read()


def build_system_prompt() -> str:
    """
    构造系统提示词：
    - 定义你的 Agent 行为
    - 指定技术栈和输出要求
    """
    # 这里采用 Vite + React + TypeScript + Tailwind 的组合，你可以根据项目修改
    system_prompt = textwrap.dedent("""
    你是一个资深前端工程师 + 设计系统专家，负责根据项目的 design.md 规范，
    生成高质量、可运行的 React + TypeScript 组件代码（Vite 项目结构）。

    关键要求：
    1. 使用 React 函数组件 + TypeScript（tsx）。
    2. 使用 Tailwind CSS 进行样式控制，不要写内联 style。
    3. 遵循项目根目录 design.md 中描述的：
       - 视觉基调
       - 色彩系统
       - 字体与排版层级
       - 组件样式（按钮、卡片、标签等）
       - 间距和布局原则
       - 响应式行为
       - 设计护栏
    4. 输出必须是一个完整的 React 组件文件 App.tsx：
       - 默认导出一个 App 组件：export default function App() { ... }
       - 不要包含多余说明性文本，只输出 TypeScript/JSX 代码。
    5. 确保结构具备典型 Landing Page 的主要区块：
       - Hero（主视觉区域）
       - 特性/优势板块（Feature Section）
       - 客户或使用场景简介
       - 最终 Call-to-Action（CTA）
    6. 保持代码整洁、有注释，但注释不要过多以免影响可读性。
    """).strip()
    return system_prompt


def build_user_prompt(design_md: str) -> str:
    """
    构造用户提示词，附带 design.md 内容。
    """
    user_prompt = textwrap.dedent(f"""
    下面是项目根目录中的 design.md 内容，请完整阅读并据此实现页面：

    ```markdown
    {design_md}
    ```

    需求：
    - 为一个 AI SaaS 产品生成 Landing Page 界面：
      - 产品定位：帮助开发者用 AI 生成高质量前端代码和 UI
      - 目标受众：前端工程师、全栈工程师、小型团队
      - 风格：与 design.md 保持一致（请严格遵循色彩、排版、组件规范）
    - 页面应为单页结构，由 App.tsx 组件渲染：
      - 包含导航栏、主视觉、特性列表、产品亮点、简单价格/方案概览、最终 CTA 区域
      - 需要考虑桌面端和移动端的响应式布局（通过 Tailwind 实现）
    - 不要输出解释或额外 Markdown，只输出完整的 App.tsx 源代码。
    """).strip()
    return user_prompt


def generate_landing_page():
    """
    主流程：
    1. 读取 design.md
    2. 通过薛定猫 AI 的 OpenAI 兼容接口调用大模型
    3. 将生成的 App.tsx 写入项目目录
    """
    design_md = load_design_md(PROJECT_ROOT)
    if not design_md:
        raise FileNotFoundError("design.md not found. Please put design.md in project root.")

    # 初始化 OpenAI 兼容客户端
    client = OpenAI(
        api_key=XDM_API_KEY,
        base_url=XDM_BASE_URL
    )

    system_prompt = build_system_prompt()
    user_prompt = build_user_prompt(design_md)

    print("[INFO] Calling model to generate App.tsx ...")

    # 调用大模型（兼容 Chat Completions 风格接口）
    response = client.chat.completions.create(
        model=MODEL_NAME,
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_prompt},
        ],
        temperature=0.3,   # 降低随机性，提高确定性和可复现性
        max_tokens=4096,
    )

    content = response.choices[0].message.content

    # 简单清洗：有些模型可能意外包裹 ```tsx ```代码块，这里做一次去除
    if "```" in content:
        # 尝试提取代码块内部内容
        parts = content.split("```")
        # 代码通常在第 2 段或第 3 段
        code_candidates = [p for p in parts if "export default function" in p or "export default" in p]
        if code_candidates:
            content = code_candidates[0]

    # 确保输出目录存在
    os.makedirs(os.path.dirname(OUTPUT_FILE), exist_ok=True)

    with open(OUTPUT_FILE, "w", encoding="utf-8") as f:
        f.write(content)

    print(f"[INFO] App.tsx generated at: {OUTPUT_FILE}")


if __name__ == "__main__":
    """
    使用方式：
    1. 在 xuedingmao.com 获取 API Key：
       - 设置环境变量：export XDM_API_KEY="your_key"
    2. 准备前端项目，并在项目根目录放置 design.md：
       - e.g. ./my-landing/design.md
    3. 运行本脚本：
       - python generate_landing.py
    4. 启动 Vite 项目，查看效果：
       - cd my-landing && npm run dev
    """
    generate_landing_page()

这个脚本实现了一个"轻量级 Verdant 思路"的最小版本：

• 委托模型自己阅读 design.md
• 通过系统提示词 + 用户需求组合，生成符合设计系统的前端页面代码
• design.md 作为视觉单一事实来源，后续你可以继续发起第二轮请求进行 refinement

如果你希望做多轮 refinement，可以在第一次生成后保留模型会话（传入所有历史 messages），每次只附加新的"优化指令"，而不要重复塞 design.md，改为一句"仍然遵循根目录 design.md"。

---

四、注意事项与实践经验

4.1 不要做"懒惰克隆"

Awesome Design 里很多风格都是基于知名网站（Vercel、Linear、Stripe...），攒得非常好用。但建议做法是：

• 借用设计规范，不要克隆内容结构和品牌
  • 替换文案、信息架构
  • 调整产品叙事和品牌细节
• 从法律和产品差异化角度，这一点都非常重要

4.2 结果质量仍然依赖模型与提示

即使 design.md 很详细，生成质量仍然取决于：

• 所选模型的指令遵从能力与代码生成能力
• system 和 user prompt 的清晰度
• 项目结构（你是否清楚告诉它文件要放在哪、如何组织）

实践中建议：

• 第一轮输出看"大局"：结构和风格是否跑偏
• 第二轮开始再做细化提示：
  • 精简 Hero 文案
  • 减少装饰性元素
  • 调整卡片平面化程度
  • 检查移动端布局表现并修正

4.3 复杂度 vs 需求匹配

• 对于简单内部工具（如内部报表、小脚本 UI）
  • 直接让模型"随便来一个好用的 UI"即可，没必要上完整 design.md
• 对于以下类型项目，则非常推荐：
  • Landing Page
  • 面向客户的后台 / Dashboard
  • Docs 站点
  • 对外 Demo / PoC

4.4 多模型实验：风格遵循 vs 创造性平衡

利用薛定猫 AI 的多模型聚合特点，你可以：

• 用同一份 design.md + 同一份 prompt
• 分别调用 Claude 系列、GPT 系列、Gemini 系列
• 对比：
  • 哪个模型在遵循 design.md 的同时，代码质量更好
  • 哪个模型在响应式布局、Tailwind 实践上更稳

这种 A/B 测试模式，是在单厂商 API 里很难低成本实现的。

---

五、技术资源与工具推荐

5.1 Awesome Design 仓库

• 关键词：awesome design.md / awesome-design
• 主要内容：
  • 超过 50 套基于真实网站的设计系统文本
  • 每套包含 design.md、preview.html、preview-dark.html
• 使用建议：
  • 先在浏览器打开预览 HTML，选中与自己产品气质接近的一套
  • 拷贝 design.md，结合自己品牌做定制化修改

5.2 技术选型

从纯技术选型的角度，xuedingmao.com 对本文工作流的价值在于：

1. 聚合 500+ 主流大模型 ：
   • GPT-5.4、Claude 4.6、Gemini 3 Pro 等主力模型统一接入
   • 适合做跨模型对比和性能评估
2. 新模型快速可用 ：
   • 前沿模型上线后无需等待各家 SDK 更新
   • 对需要尝鲜和追最新能力的前端 / 全栈开发者非常友好
3. 统一 OpenAI 兼容接口 ：
   • base_url + api_key + model 即可使用
   • 原有基于 OpenAI SDK 的项目几乎零改动迁移
   • 对多模型集成和切换成本极低

在"AI 驱动前端生成"的场景下，能稳且快地试验不同模型，比单一模型依赖更有工程价值。

---

总结

Awesome Design + design.md 方案，并没有引入什么"新魔法"，它做的事非常朴素：

• 把原本在设计师脑海、Figma、截图里的"设计语言"
• 转写成一个结构化 Markdown 文本，让 AI Agent 真正能读懂并遵循

配合 agents.md 将架构规则与视觉规则解耦，再通过类似本文的 Python + 薛定猫 AI API 调用，构建起这样一条可复制的工作流：

1. 打开项目，放入 design.md
2. 在 Agent 的系统提示中声明"所有 UI 必须遵循 design.md"
3. 用统一的 API 调用模型生成初版 UI
4. 在同一 design.md 约束下做多轮 refinement，而不是一遍遍重写长 prompt

如果你已经厌倦了那种"上半屏还行、往下滚就散架"的 AI 生成页面，这套工作流非常值得在团队里试一试。

---

#AI #大模型 #Python #机器学习 #技术实战