企业官网建设流程全解析

gstack DESIGN.md 实战解析：让设计系统文件成为 AI 设计决策的唯一事实来源

【免费下载链接】gstackUse Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack

DESIGN.md是 gstack 社区网站的设计系统规格文件，记录了字体、色彩、间距、布局与动效的完整决策。在 gstack 的工作流中，它更是一个被多套工具自动读取的“设计事实来源”：/design-consultation从零创建它，designCLI 的extract命令会把已批准设计稿的视觉语言写回它，/plan-design-review则要求所有设计决策以它为准校准。读完本文，你将掌握一份可直接复用的设计系统文档规范，以及 gstack 各模块如何通过源码消费这份文件的完整链路。

一、产品语境：DESIGN.md 为谁而写

gstack 自身的 DESIGN.md 开篇即声明产品语境，这是整份文档的第一节，也是 gstack 建议每个项目在设计系统中回答的问题：

• What this is:社区网站，面向正在发现 gstack（一个把 Claude Code 变成虚拟工程团队的 CLI 工具）的开发者与现有社区成员。
• Space/industry:开发者工具，参考坐标是 Linear、Raycast、Warp、Zed 这类产品。
• Project type:社区仪表盘 + 营销站点。

在产品定位之后，文档给出美学方向（Aesthetic Direction），这是后续所有 token 决策的依据：

• 方向：工业风/实用主义（Industrial/Utilitarian）——功能优先、数据密集，等宽字体作为性格字体（personality font）。
• 装饰程度：克制的刻意——在表面上叠加细微的噪点/颗粒纹理，赋予材质感。
• 情绪：一个“由在乎工艺的人打造的严肃工具”，温暖而非冰冷。CLI 血统本身就是品牌。
• 参考站点：formulae.brew.sh（竞品，但本站点更“活”、可交互）、Linear（深色 + 克制）、Warp（暖色强调）。

这一节的价值在于：它不是孤立的美术偏好，而是约束了后文每个具体数值——比如“等宽字体要醒目而非藏在代码块里”直接决定了 JetBrains Mono 在数据表格中被广泛使用的排版决策。

二、Typography：三段式字体体系与完整字号阶梯

gstack 的字体系统分五个角色，每类字体都标注了加载来源，这是很多设计系统文档缺失的工程细节：

加载策略：DM Sans 与 JetBrains Mono 走 Google Fonts，Satoshi 走 Fontshare，统一使用display=swap。

字号阶梯（Type Scale）完整继承自原文档：

注意 Hero 用了clamp()实现响应式缩放，而其余标题是固定值——这是“编辑感 hero + 仪表盘式正文”布局策略的排版映射。

三、Color：琥珀色强调 + 中性 zinc 的双模式色彩体系

色彩策略的核心一句话是“克制”（Restrained）：琥珀色强调很少出现、每次出现都有意义；数据区获得颜色，界面框架（chrome）保持中性。完整 token 如下：

主色（Primary，琥珀）：

中性色（Cool zinc grays）：

语义色（Semantic）：success#22C55E、warning#F59E0B、error#EF4444、info#3B82F6。

双模式规则：

• Dark mode（默认）：近黑底#0C0C0C，卡片面#141414，边框#262626。
• Light mode：暖 stone 底#FAFAF9，白色卡片，stone 边框#E7E5E4；强调色切换为 amber-600 以保证对比度。

四、Spacing 与 Layout：4px 基数、12 列网格与圆角分级

间距（Spacing）：

• 基数：4px。
• 密度定位：“舒适”——不拥挤（不是 Bloomberg 终端式），也不疏朗（不是营销页式）。
• 阶梯：2xs(2px) xs(4px) sm(8px) md(16px) lg(24px) xl(32px) 2xl(48px) 3xl(64px)。

布局（Layout）：

• 策略：仪表盘部分严格网格化，落地页 hero 区走编辑感（editorial）排版。
• 网格：lg 断点以上 12 列，移动端 1 列。
• 内容最大宽度：1200px（6xl）。
• 圆角分级（Border radius）：sm:4px、md:8px、lg:12px、full:9999px，并按组件分配——

五、Motion 与 Grain Texture：只保留“帮助理解”的动效

动效（Motion）原则：最小功能主义——只保留辅助理解的过渡；“仪表盘实时 feed 本身就是动效”。

• 缓动：enter 用ease-out（具体曲线cubic-bezier(0.16,1,0.3,1)），exit 用ease-in，move 用ease-in-out。
• 时长：micro(50-100ms)、short(150ms)、medium(250ms)、long(400ms)。
• 动画元素白名单：实时 feed 圆点脉冲（2s infinite）、技能条填充（600ms ease-out）、hover 状态（150ms）。

颗粒纹理（Grain Texture）：为整个页面叠加细微噪点，营造材质感、防止“千篇一律的 SaaS 模板”感。实现约束非常具体：

• Dark mode 不透明度 0.03，Light mode 0.02；
• 用 SVGfeTurbulence滤镜作为 CSSbackground-image挂在body::after上；
• pointer-events: none、position: fixed、z-index: 9999。

六、源码级链路：gstack 工具链如何自动消费 DESIGN.md

以上 token 是静态规范；DESIGN.md 在 gstack 中的真正威力在于它是多条工具链的输入。以下均为仓库源码可验证的事实。

6.1 /design-consultation：DESIGN.md 的生产者

design-consultation/SKILL.md 的职责是“从零创建 DESIGN.md 作为项目的设计事实来源”。它的 frontmatter 中声明了 gbrain 上下文查询，第一条就是直接以glob: "DESIGN.md"读取文件系统上的现有 DESIGN.md，并以## Existing DESIGN.md (if any)渲染进上下文——也就是说，每次咨询时技能都会先检查是否已有设计系统，避免重复设计。README 中对/design-consultation的描述是：从零构建你的设计系统、调研业界现状、提出有创造性的风险、并写出DESIGN.md。

6.2 design CLI 的 extract 命令：从设计稿反向写入 DESIGN.md

design/src/commands.ts 注册了extract子命令：Extract design language from approved mockup into DESIGN.md，用法为extract --image approved.png。其实现位于 design/src/memory.ts，调用链如下：

1. extractDesignLanguage(imagePath)将已批准的 mockup PNG 以 base64 形式发给 GPT-4o vision 接口，要求只返回 JSON，结构为colors / typography / spacing / layout / mood五字段（见 ExtractedDesign 接口），60 秒超时，失败时回退到空结构defaultDesign()而不中断流程；
2. updateDesignMd(repoRoot, extracted, sourceMockup)写入仓库根目录的DESIGN.md（memory.ts#L111）：
   • 文件已存在 → 若其中已有## Extracted Design Language标记段，则替换该段；否则追加到末尾；
   • 文件不存在 → 创建新的# Design System文档；
   • 每次写入都带日期与来源 mockup 文件名（*Source: xxx.png*），与本文开头 gstack 自己的 Decisions Log 表格是同一维护哲学：设计决策必须留痕。

CLI 分发逻辑在 design/src/cli.ts：case "extract"分支先调extractDesignLanguage，成功后updateDesignMd，再把提取结果以 JSON 打到 stdout——即该命令对脚本和人都友好。

6.3 design-to-code：DESIGN.md 作为实现约束

design/src/design-to-code.ts 在从已批准 mockup 生成“实现提示词”时，会先调用readDesignConstraints(repoRoot)：读取 DESIGN.md 全文并截断到前 2000 字符（memory.ts#L196-L203），然后注入 prompt：Existing DESIGN.md (use these as constraints): ...。这意味着 DESIGN.md 同时服务于“生成阶段”与“代码阶段”：无此文件时返回 null，模型“explore wide”（自由探索）；有此文件时，视觉细节必须与既定系统对齐。

与之呼应的是 design/src/brief.ts 中的DesignBrief接口，其reference字段注释明确写着DESIGN.md excerpt or style reference text——生成 mockup 的 brief 结构里就为 DESIGN.md 预留了位置。

6.4 评审与规划技能：以 DESIGN.md 校准一切设计决策

• plan-design-review/SKILL.md 规定“DESIGN.md — if it exists, ALL design decisions calibrate against it”（若存在，所有设计决策都以它校准），并在评审的 System Audit 维度检查其状态：存在则“所有设计决策将按你声明的设计系统校准”，不存在则标记为 gap 并建议先运行/design-consultation；在生成设计变体时，brief 由“计划描述 + DESIGN.md 约束”拼装，例如$D variants --brief "<由计划与 DESIGN.md 约束组装的描述>" --count 3 --output-dir ...。
• autoplan/sections/design-phase.md 的 Step 0 同样要求“Check DESIGN.md”，且规则是“如果 DESIGN.md 存在且修复明显，则自动修复设计系统对齐问题”。

6.5 使用 design CLI 的最小实操路径

从 design/src/cli.ts 的printUsage与runSetup可以确认完整用法：

# 1. 引导式 API key 配置 + 冒烟测试（key 存到 ~/.gstack/openai.json，0600 权限） $D setup # 2. 从已批准的设计稿提取设计语言并写回仓库根目录的 DESIGN.md $D extract --image approved.png # 3. 从已批准 mockup 生成结构化实现 prompt（会读取 DESIGN.md 作为约束） $D prompt --image approved.png # 4. 从 brief 生成 UI mockup $D generate --brief "..." --output /path.png # 5. 生成 N 个设计变体供评审 $D variants --brief "..." --count 3 --output-dir /path/

认证解析顺序为：先读~/.gstack/openai.json，其次OPENAI_API_KEY环境变量，都没有则进入引导式 setup；vision/生成类调用均依赖 OpenAI 图像权限。

七、Decisions Log：设计文档的维护约定

gstack 的 DESIGN.md 末尾是决策日志，每条决策记录日期、决策与理由：

这给出了 DESIGN.md 的第三种维护方式（除人工编辑与extract自动追加外）：每个偏离默认判断的决策都要记录理由。三条记录正好对应本文的三个章节——初始系统、浅模式强调色权衡、噪点纹理——展示了“token 从哪里来”的完整叙事。

八、小结：如何在自己项目中落地这套模式

结合 DESIGN.md 的结构与 gstack 工具链的消费方式，一份可被 AI 工具链消费的设计系统文档应包含：

1. Product Context——产品是什么、给谁、所处赛道，为所有 token 提供判断依据；
2. Aesthetic Direction——一句话美学方向 + 参考站点，约束后续选择；
3. 完整 token 表——字体（含加载来源与display=swap）、色彩（含明暗双模式）、间距、圆角、动效，全部落到具体数值；
4. 例外与材质细节——如 grain 纹理的具体 CSS 挂载方式；
5. Decisions Log——决策留痕表，配合/design-consultation创建、$D extract从 mockup 自动追加、评审技能校准使用。

gstack 仓库自身的 DESIGN.md 就是这套模式的示范样本；仓库中的 design/、design-consultation/、plan-design-review/ 目录则提供了从“文档”到“自动化消费”的全部源码证据。

【免费下载链接】gstackUse Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack