企业官网建设流程全解析

1. Overview

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

2. Colors

3. Typography

4. Layout

5. Elevation & Depth

6. Shapes

7. Components

8. Do's and Don'ts

> 注意：规范顺序是本仓库文档给出的顺序；真实的 [demos/landing-demo/DESIGN.md](https://link.gitcode.com/i/dd488f075cc1922b8223c590e64e3d08) 示例省略了不相干小节（无 Layout、Shapes），并按“1. Overview、2. Colors、3. Typography、4. Elevation、5. Components、6. Do's and Don'ts”组织——这正是文档所说“**省略不相关小节，而不是用编造的规则填充**”的体现。未知小节格式会被保留（forward-compatible），但新视觉指导应优先使用规范结构。 各小节职责划分（摘自文档）： - **Overview**：Creative North Star（创意北极星，带引号的命名隐喻）+ 2~3 段整体描述（人格、密度、审美哲学），以 `**Key Characteristics:**` 要点列表收尾。只陈述确认过的视觉反参考（anti-references）。 - **Colors**：按角色分组（Primary / Secondary / Tertiary / Neutral），而不是按 hex 或色相排序。每个颜色给出描述性名称与使用场景（WHERE/WHY），可选 Named Rules。 - **Typography**：Display/Body/Label 字体配对 + 分层层级（Display/Headline/Title/Body/Label），每层注明字重、字号、行高、用途。 - **Layout**：网格或空间模型、容器行为、密度、响应式变化、间距节奏；只有观测到确切值时才给出精确值。 - **Elevation & Depth**：明确该系统用阴影、色调分层（tonal layering）还是混合方案；若是“无阴影”，要明确写出并说明深度如何传达。可选 Shadow Vocabulary。 - **Shapes**：角/圆角策略、边框、裁切与反复出现的造型语言。 - **Components**：每个组件先给一句性格描述，再说明造型、配色、状态与独特行为（Buttons、Chips、Cards、Inputs、Navigation 及可选 Signature Component）。 - **Do's and Don'ts**：以“Do/Don't”开头给出具体视觉护栏，只有已被既有实现或用户确认的条目才写；任务级的具体概念不应上升为系统级禁令。 **Named Rules 是全文的粘合剂**：`**The [Name] Rule.** [short doctrine]`（如 Stitch 输出中常见的 “The No-Line Rule”、“The Ghost Border Fallback”）。文档强调：它们“对 AI 消费者比项目符号更难忘、更可引用”，每节建议 1~3 条。demos 中落地了五个具名规则： - **The Cream-Family Rule**（colors）：所有中性面都向品牌色相靠拢，任何地方都没有纯白、纯黑或未着色的灰。 - **The 10% Accent Rule**（colors）：烧橙色覆盖不超过任何渲染表面的 10%，稀缺才是重点。 - **The One-Italic Rule**（typography）：斜体每页只出现一次，位于 hero 标题的单个强调词内。 - **The No-Gradient-Text Rule**（typography）：文字永远是纯色，hero 的奶油到桃色渐变只是区块背景。 - **The Flat-By-Default Rule**（elevation）：静止时表面是平的，hover 抬升用 `transform: translateY(-1px)`，绝不用阴影。 --- ## 四、何时运行 `document`：触发条件与覆盖保护 ### 4.1 触发时机 文档列出的四种典型场景： - new-work 发现存在自洽的既有视觉系统，但没有 `DESIGN.md`； - 新世界的首次实现完成，临时决定需要“碳化”（carbonize）为正式规范； - 现有 `DESIGN.md` 已过期（设计漂移，design drifted）； - 大型重设计之前，把当前状态作为参考基线固化下来。 ### 4.2 覆盖保护：绝不静默覆盖 **如果 `DESIGN.md` 已存在，绝不要静默覆盖。** 先向用户展示现有文件，然后给出 refresh / overwrite / merge 三种选择（`{{ask_instruction}}`）。 这条规则在仓库的 context 层有对应的状态信号支撑：例如 [crates/context/src/context_cli.rs](https://link.gitcode.com/i/925c4e34ca985aa50b5ce6c272c3ad8f) 中的 `NO_PRODUCT_MD`、`EXISTING_VISUAL_SYSTEM`、`INCUMBENT_WORLD_UNDOCUMENTED` 等指令，都会区分“已有视觉实现但缺文档”与“真正全新的项目”，并给出是否先走 init/new-work 的路由建议。 --- ## 五、两条生成路径：Scan mode 与 Seed mode `document` 有两种模式，**先扫描再决定**（Decide by scanning first）： | 模式 | 适用场景 | 产出 | |---|---|---| | **Scan mode**（默认） | 项目已有设计令牌、组件或渲染输出，有代码可分析 | 自动抽取令牌 → 向用户确认定性语言 → 写出完整 DESIGN.md + sidecar | | **Seed mode** | 项目尚在实现之前，没有可抽取的视觉系统 | 通过 new-work 的视觉世界工作坊确立方向，写出带 SEED 标记的方向性 DESIGN.md 种子 | 关键约束：**先扫描（Scan mode Step 1）。** 如果扫描发现没有令牌、没有组件文件、也没有渲染站点，才提供 seed mode；**不要静默切换**。`/impeccable document --seed` 会请求 new-work 的世界工作坊，但它不授权替换自洽的既有代码——当存在既有系统时，应提供 scan mode，或将明确的“身份替换”请求路由给 new-work。 --- ## 六、Scan mode 实战：从发现资产到确认定性语言 Scan mode 的完整工作流为：**发现资产 → 自动抽取 → 起草 frontmatter → 询问定性语言 → 写文件 → 确认精修**。 ### Step 1：按优先级发现设计资产 按文档给定的优先级顺序搜索代码库： 1. **CSS 自定义属性**：在 CSS 文件中 grep `--color-`、`--font-`、`--spacing-`、`--radius-`、`--shadow-`、`--ease-`、`--duration-` 声明（常见位置：`src/styles/`、`public/css/`、`app/globals.css`），记录名称、值与定义文件。 2. **Tailwind 配置**：若存在 `tailwind.config.{js,ts,mjs}`，读取 `theme.extend` 中的 colors、fontFamily、spacing、borderRadius、boxShadow。 3. **CSS-in-JS 主题文件**：styled-components、emotion、vanilla-extract、stitches，查找 `theme.ts`、`tokens.ts` 等。 4. **设计令牌文件**：`tokens.json`、`design-tokens.json`、Style Dictionary 输出、W3C token community group 格式。 5. **组件库**：扫描主按钮、卡片、输入框、导航、对话框组件，记录其变体 API 与默认样式。 6. **全局样式表**：根 CSS 通常承载基础排版与颜色分配。 7. **可见渲染输出**：若浏览器自动化可用，加载线上站点，对关键元素（body、h1、a、button、.card）采样 computed styles——这能捕捉令牌遗漏的值。 ### Step 2：自动抽取结构化草稿 对每类令牌执行抽取： - **Colors**：分组为 Primary / Secondary / Tertiary / Neutral（Stitch 使用的 Material 派生角色）。若项目只有一个强调色，就表达为 Primary + Neutral，**省略 Secondary/Tertiary 而不是编造**。 - **Typography**：将观测到的字号/字重映射到 Material 层级（display / headline / title / body / label），记录字体栈与缩放比。 - **Elevation**：清点阴影词汇表。如果项目是扁平风、用色调分层表达深度，那也是合法答案，要明确写出来。 - **Components**：对每个常见组件（button、card、input、chip、list item、tooltip、nav）抽取造型（圆角）、配色、hover/focus 处理、内边距。 - **Layout + spacing**：把网格、容器、断点、节奏、密度行为归入 Layout。 - **Shapes**：把圆角、边角、边框、裁切与反复出现的造型行为归入 Shapes。 ### Step 2b：起草 frontmatter（先于正文写作） - **Colors**：每个抽取到的颜色一条。键 = 描述性 slug（`oxblood-deep`、`editorial-magenta`，而不是 `blue-800`）；值 = 项目视为规范的格式（OKLCH 或 hex）。**不要拆分单一事实源**：frontmatter 用一种格式，正文不得用另一个值重新定义同一令牌。 - **Typography**：每个角色一条（`display`/`headline`/`title`/`body`/`label`）。typography 是对象，只包含项目真实存在的属性（`fontFamily`、`fontSize`、`fontWeight`、`lineHeight`、`letterSpacing`、`fontFeature`、`fontVariation`）。 - **Rounded / Spacing**：项目实际使用的刻度步进，键名沿用项目自有刻度名（`sm`/`md`/`lg`，或 `surface-sm`，或数字步进）。 - **Components**：每个变体一条（`button-primary`、`button-primary-hover`、`button-ghost`），通过 `{colors.X}`、`{rounded.Y}` 引用原语。若变体需要超出 8 属性集的能力（阴影、focus ring、backdrop-filter），把完整片段放进 sidecar。 原则：**跳过项目没有的东西。** 空的刻度键或捏造的令牌会污染规范。 ### Step 3：向用户询问定性语言（两轮，每轮最多三问） 以下内容无法自动抽取，需要创造性输入，**分两轮、每轮不超过三个问题**（或 harness 的更低上限），两轮之间等待用户回复： - **Creative North Star**：为整个系统命名的单个隐喻（如 “The Editorial Sanctuary”、“The Golden State Curator”、“The Lab Notebook”），提供 2~3 个尊重 PRODUCT.md 品牌人格的选项。 - **Overview voice**：情绪形容词、2~3 句审美哲学、确认过的视觉反参考。 - **Color character**：为自动抽取的颜色取描述性名称（“Deep Muted Teal-Navy”而非 “blue-800”），基于色相/饱和度建议每色 2~3 个选项。 - **Elevation philosophy**：flat / layered / lifted；若有阴影，其角色是 ambient（环境）还是 structural（结构）。 - **Component philosophy**：用一句话描述按钮、卡片、输入框的感觉（“tactile and confident” vs “refined and restrained”）。 只有 PRODUCT.md 中**持久性的品牌承诺**（约束视觉系统的部分）才可以被带入 DESIGN.md；页面策略与表面概念不属于这里。 ### Step 4：写 DESIGN.md 文件以 Step 2b 起草的 YAML frontmatter 开头，随后是规范结构的 Markdown 正文。文档给出了完整的正文模板（见第四节结构 + 完整示例模板），关键填充指引： - Overview 从 North Star 出发向外展开，只陈述确认过的视觉拒绝，以 `**Key Characteristics:**` 列表收尾； - 每个颜色条目遵循 `**Descriptive Name** (#HEX / oklch(...)): [Where and why this color is used]` 的格式，强调具体语境而非仅角色； - Do's and Don'ts 中的条目只有在既有实现或用户决定支撑时才写，一句话的审计测试胜过一段原则。 ### Step 5：确认与精修 1. 向用户展示完整的 DESIGN.md，突出非显而易见的创意选择（描述性颜色名、氛围语言、具名规则）。 2. 说明 `.impeccable/design.json` 也已一并写出，live panel 将渲染该项目的真实按钮/输入框/导航原语，而不是通用近似物。 3. 主动提供精修：“Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?”（可意译为：需要我修改某节、补充遗漏的组件模式，或调整氛围语言吗？） 本次会话中你自己写出的文件就是最新来源，后续命令无需 reload。 --- ## 七、Step 4b：`.impeccable/design.json` sidecar（扩展层） ### 7.1 分工与再生成原则 frontmatter 拥有令牌原语（colors、typography、rounded、spacing、components）；**sidecar 携带 Stitch schema 装不下的东西**： - 每个颜色的色调渐变（tonal ramps） - 阴影/抬升令牌、动效令牌、断点 - 完整组件 HTML/CSS 片段（panel 渲染进 shadow DOM） - 叙述层（north star、rules、do's/don'ts） sidecar **扩展** frontmatter，不重复它。每当重新生成根 `DESIGN.md` 时都要重新生成 sidecar；如果用户只想刷新 sidecar（例如 live panel 的 stale-hint 提示），则保留 `DESIGN.md`，只写 `.impeccable/design.json`。 ### 7.2 Schema（schemaVersion 2） ```json { "schemaVersion": 2, "generatedAt": "ISO-8601 string", "title": "Design System: [Project Title]", "extensions": { "colorMeta": { "primary": { "role": "primary", "displayName": "Editorial Magenta", "canonical": "oklch(60% 0.25 350)", "tonalRamp": ["...", "...", "..."] }, "cool-paper": { "role": "neutral", "displayName": "Cool Paper", "canonical": "oklch(96% 0.005 230)", "tonalRamp": ["...", "...", "..."] } }, "typographyMeta": { "display": { "displayName": "Display", "purpose": "Hero headlines only." } }, "shadows": [ { "name": "ambient-low", "value": "0 4px 24px rgba(0,0,0,0.12)", "purpose": "Diffuse hover glow under accent elements." } ], "motion": [ { "name": "ease-standard", "value": "cubic-bezier(0.4, 0, 0.2, 1)", "purpose": "Default easing for state transitions." } ], "breakpoints": [ { "name": "sm", "value": "640px" } ] }, "components": [ { "name": "Primary Button", "kind": "button | input | nav | chip | card | custom", "refersTo": "button-primary", "description": "One-line what and when.", "html": "<button class=\"ds-btn-primary\">SAVE CHANGES</button>", "css": ".ds-btn-primary { background: #191c1d; color: #fff; padding: 16px 48px; letter-spacing: 0.05em; text-transform: uppercase; font-weight: 500; border: none; border-radius: 0; transition: background 0.2s, transform 0.2s; } .ds-btn-primary:hover { background: oklch(60% 0.25 350); transform: translateY(-2px); }" } ], "narrative": { "northStar": "The Editorial Sanctuary", "overview": "2-3 paragraphs of the philosophy, pulled from DESIGN.md Overview section.", "keyCharacteristics": ["...", "..."], "rules": [{ "name": "The One Voice Rule", "body": "...", "section": "colors|typography|elevation" }], "dos": ["Do use ..."], "donts": ["Don't use ..."] } }

仓库的真实实现 demos/landing-demo/DESIGN.json 完整展示了这一 schema：8 个colorMeta条目（每个含role、displayName、canonicalOKLCH 值与 8 步tonalRamp）、6 个typographyMeta、2 个motion令牌、2 个breakpoints、7 个组件（含refersTo与可注入 shadow DOM 的html/css），以及完整的narrative（northStar、overview、5 条 rules、5 条 dos、5 条 donts）。

7.3 从 schemaVersion 1 到 2 的变化

旧版 sidecar 携带令牌原语数组（tokens.colors[]、tokens.typography[]等）。这些值现在移入 frontmatter；sidecar 只携带 frontmatter 放不下的元数据（色调渐变、当 hex 只是近似时的规范 OKLCH、显示名、角色提示），并以 frontmatter 令牌名为键（colorMeta.<token-name>、typographyMeta.<token-name>）。组件仍携带完整 HTML/CSS，因为 Stitch 的 8 属性集装不下它们。schema 版本常量对应实现：DESIGN_SIDECAR_SCHEMA_VERSION = 2（crates/context/src/artifact_schema.rs）。

7.4 组件翻译规则（自包含、可直接注入 shadow DOM）

html与css字段必须是自包含、即插即用的片段，注入 shadow DOM 后能正确渲染。panel 直接应用它们：无后处理、无框架运行时。六条硬规则：

1. Tailwind 展开：若源使用 Tailwind（className="bg-primary text-white rounded-lg px-6 py-3"），把每个工具类展开为css字符串中的字面 CSS 属性。不要引用 Tailwind 类，不要假设 Tailwind CSS bundle 已加载。每个组件都自包含。
2. 令牌解析：若项目在:root上暴露 CSS 自定义属性令牌（如--color-primary、--radius-md），通过var(--color-primary)引用——它们会穿透 shadow DOM 继承并保持 live-bound；若令牌只存在于 JS 主题对象（styled-components、CSS-in-JS），则在生成时解析为字面值。
3. 图标：内联为 SVG。不要引用 Lucide/Heroicons 包、图标字体或<img src="...">。典型图标 16–24px，直接复制 SVG path 数据。
4. 状态：内联包含:hover、:focus-visible，以及有意义的:active规则。只有静态默认快照会让 panel 显得死板；CSS 中的 hover + focus 规则让它有生命感。
5. 重置去冗余：只抽取组件的特色CSS（背景、颜色、内边距、圆角、排版、过渡）。跳过通用 reset（box-sizing: border-box、line-height: inherit、-webkit-font-smoothing）——panel 已有中性画布，不需要重新携带 reset。
6. 作用域类名：每个类以ds-前缀（如ds-btn-primary、ds-input-search），避免同一 shadow DOM 内组件间 CSS 冲突。

7.5 内容选择：5~10 个代表性组件

目标是精选 5~10 个最能代表视觉系统的组件：

• 规范原语（项目有则必含）：button（每个变体作为独立组件条目）、input/文本框、navigation、chip/tag、card。
• 签名组件（有特色才含）：定义已实现系统的反复出现的自定义模式。
• 跳过其余：工具组件、表单积木、包裹布局——除非视觉上有特色，否则不值得记录。

若项目还没有组件库（裸落地页、新项目），可从令牌出发、用与 DESIGN.md 规则一致的最佳实践默认值合成规范原语——每个.impeccable/design.json都至少有东西可渲染，哪怕是在第零天。

7.6 色调渐变（Tonal ramps）

对每个颜色令牌生成 8 步tonalRamp数组：从暗到亮，保持同一色相与色度（chroma），亮度从约 15% 步进到约 95%。panel 把渐变渲染为色卡下方的条带。若项目已定义自己的色调标尺（Materialsurface-container-low家族、Tailwind 风格blue-50..blue-900），使用这些值；否则在 OKLCH 中合成。demos 中的creamramp 从oklch(15% 0.012 80)到oklch(96.5% 0.012 80)即为典型示例。

7.7 叙述映射（Narrative mapping）

直接从刚写好的 DESIGN.md 搬运，不改写（panel 把它们作为次级可折叠上下文展示，与 Markdown 中相同的声音需要延续）：

八、Seed mode：实现之前的视觉世界种子

Seed mode 适用于还没有可抽取视觉系统的项目，产出的是“用户选择的视觉世界脚手架”，而不是编造的令牌规格。

Step 1：经由 new-work 的工作坊路由

PRODUCT.md 是前置条件。若缺失，先加载 skill/reference/init.md 完成产品访谈——没有持久的产品语境，不要创建视觉身份。

若 PRODUCT.md 存在，加载 skill/reference/new-work.md 解决视觉权威问题。Seed mode 需要一个具体的首面（first surface）：使用用户指定的 target，或询问用户想先做什么。运行 new-work 的Create or replace the visual world流程，然后Commit the world，让视觉世界与它的首面表达一起被选定。在方向性 DESIGN.md 种子与 surface brief 之后停止，不要实现。结构化的模拟用户也算用户，必须获得同样的选择权。

若本次会话中 new-work 已完成工作坊，直接使用其选定方向，不要重复询问。

Step 2：写 seed DESIGN.md

使用与 Scan mode 相同的规范小节顺序，填充选定的工作坊方向，未决的实现事实留作诚实的占位符。种子承诺一个世界及其不变量，不假装实现令牌已经存在。

文件以如下 SEED 标记开头：

<!-- SEED: established with the user before implementation; re-run /impeccable document once there's code to capture the actual tokens and components. -->

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable