企业官网建设流程全解析

• AI 应用
• 人工智能
• AI 技能
• 设计系统
• 媒体生成

本篇技术指南围绕 OpenDesign 仓库中的 Ant 设计系统包（Design System 2.0）展开，说明其作为「设计系统包（Design System Package）」的使用契约：如何按官方阅读顺序接入 tokens、组件清单与参考实现，如何在 Agent 生成界面时正确复用色彩、字体、间距等设计令牌，并避免破坏跨品牌切换的稳定性。读完本文，你将掌握 Ant 包的完整文件构成、56 个设计令牌的分层语义、组件分组与选择器契约，以及一套可直接照做的 Do / Avoid 纪律，能够在自己的设计产物（原型、落地页、仪表盘）中落地「data-dense、enterprise」风格的界面。

一、Ant 包在 OpenDesign 设计系统体系中的定位

Ant 是 OpenDesign 设计系统 2.0 体系下的一个内置（bundled）设计系统包。它的核心载体是 design-systems/ant/USAGE.md —— 一份面向「OpenDesign 的 Agent 与评审者（reviewers）」的包契约说明文档。它不讲解某个具体组件怎么写，而是定义了这个包如何被消费、如何被约束的完整规则。

从包清单 design-systems/ant/manifest.json 可以确认它的元信息：

• schemaVersion: od-design-system-project/v1，即本仓库设计系统工程的标准清单格式；
• category: Professional & Corporate，风格家族为「专业与企业」；
• source.type: bundled，来源是 OpenDesign 官方整理的捆绑 fixture（并非重新爬取上游品牌仓库）；
• importMode: normalized，导入模式为规范化导入；
• craft.suggested建议配套的工艺规范为color与accessibility-baseline，对应 craft/color.md 与 craft/accessibility-baseline.md；
• preview提供三个预览页（colors / typography / spacing）。

包的物理文件结构

design-systems/ant/ ├── USAGE.md # 包契约：阅读顺序、Do / Avoid（本文主体） ├── DESIGN.md # 视觉意图、约束与反模式 ├── manifest.json # 包清单（od-design-system-project/v1） ├── tokens.css # 设计令牌唯一事实源（:root 变量块） ├── design-tokens.json # 派生：TOKEN_SCHEMA 令牌合同 ├── tailwind-v4.css # 派生：Tailwind v4 @theme 绑定 ├── components.html # 参考组件 fixture（选择器与状态的权威来源） ├── components.manifest.json # 组件清单：分组、选择器、令牌引用审计 ├── source/ │ ├── evidence.md # 来源范围声明 │ ├── tokens.source.json # 令牌源数据 │ └── token-contract.report.json # 令牌合同映射报告 ├── system/ │ ├── index.html # 系统资产总览 │ ├── kit.html # 组件套件（亮色） │ └── kit.dark.html # 组件套件（暗色） └── preview/ ├── colors.html # 色彩预览 ├── typography.html # 排版预览 └── spacing.html # 间距预览

二、阅读顺序：Agent 与评审者的标准接入流程

design-systems/ant/USAGE.md 明确规定了接入该包的标准阅读顺序，这是整个使用契约的第一步，必须严格遵循：

1. 先读USAGE.md本身，理解包契约（即本文）；
2. 再读 design-systems/ant/DESIGN.md，理解视觉意图、约束与反模式；
3. 把tokens.css粘贴到第一个 artifact 的<style>块中，作为编写组件 CSS 之前的令牌基础；
4. 用 design-systems/ant/components.manifest.json 作为组件速查清单；当需要精确选择器或状态细节时，再打开 design-systems/ant/components.html；
5. 需要做视觉 sanity check 时，查看preview/下的 colors.html、typography.html、spacing.html 三个预览页。

这条路径的核心思想是「契约优先、清单优先、细节按需」：USAGE.md定义纪律，DESIGN.md定义风格意图，tokens.css提供唯一令牌事实源，components.manifest.json提供组件索引，components.html提供精确实现。

为什么必须先贴 tokens.css

tokens.css是整个包的设计令牌唯一事实源（source of truth）。design-systems/ant/tailwind-v4.css 第一行注释就写明：Derived from tokens.css. Keep tokens.css as the source of truth.。也就是说，Tailwind 绑定和 JSON 合同都是从tokens.css派生出来的，任何手改派生文件的尝试都会被后续的令牌合同校验打破。因此 USAGE.md 要求「先粘贴tokens.css再写组件 CSS」，本质上是保证你的输出与令牌事实源保持同步。

三、设计亮点：data-dense 企业风格的核心基调

design-systems/ant/USAGE.md 的 Design Highlights 定义了该包的身份标签，design-systems/ant/DESIGN.md 对此有更完整的展开：

• 视觉风格（Visual style）：data-dense（数据密集型）、enterprise（企业级）；
• 色彩立场（Color stance）：primary、neutral、success、warning、danger 五类语义色齐全；
• 设计意图（Design intent）：让输出对该风格家族保持可辨识度（recognizable），同时保留可用性与可读性（usability and readability）；
• 主色（Primary）：#1677FF，来自风格基础（style foundations）的令牌。

DESIGN.md 进一步给出了色彩、排版、间距、布局、组件、动效、语调与反模式八个维度的规范，详见下文「视觉意图」小节。

四、Do：必须遵守的包纪律

USAGE.md 列出的四条正面纪律，是保证包内一致性、跨品牌可切换性的关键：

1. 精确保留 schema token 名称（Preserve the schema token names exactly），这样跨品牌切换（cross-brand switching）才能保持可靠 —— 这与「设计令牌是跨品牌抽象层」的定位直接相关：令牌名称一旦被改写，品牌 B 的令牌就无法无缝替换品牌 A；
2. 使用--accent表达主操作、链接、焦点状态，以及页面上「一个明确的焦点元素」（one clear focal element）—— 即强调色只服务于单一视觉焦点，避免多重点缀分散注意力；
3. 优先复用 design-systems/ant/components.manifest.json 中的组件分组，而不是凭空发明新控件 —— 组件清单就是可复用资产的索引；
4. 把source/目录文件视为审计证据（audit evidence），用于支撑「捆绑 fixture 回填」（bundled fixture backfill）的可追溯性 —— 即 design-systems/ant/source/evidence.md 与 design-systems/ant/source/token-contract.report.json 是后续校验的取证依据。

为什么--accent是唯一焦点信号

从 design-systems/ant/components.html 的实际实现可以看出--accent的单一焦点用法：.btn-primary的background: var(--accent)、color: var(--accent-on)；.btn-secondary:hover用border-color: var(--accent)表达悬停信号；input:focus用border-color: var(--accent)配合var(--focus-ring)表达焦点；.swatch.accent作为调色板中的强调色样本。整页只有--accent一个强调变量在承担交互信号，这正是「one clear focal element」的落地形态。

五、Avoid：明确禁止的越界行为

USAGE.md 同时定义了四条「禁止」，它们与 source 证据边界、令牌事实源纪律一一对应：

1. 禁止在拷贝的:root令牌块之外使用裸 hex 颜色值（Avoid raw hex values outside the copied:roottoken block）—— 所有颜色必须走令牌间接层，这样换肤、暗色模式、无障碍对比度调整都只改一处；
2. 禁止脱离tokens.css独立重定义 Tailwind 或设计令牌值（Avoid redefining Tailwind or design-token values independently）—— design-systems/ant/tailwind-v4.css 就是「从tokens.css派生」的官方示范，任何旁路定义都会造成双源不一致；
3. 禁止声称拥有上游原始源码证据（Avoid claiming original upstream source evidence）—— 本包基于 OpenDesign 官方整理的捆绑 fixture 派生，design-systems/ant/source/evidence.md 明确声明「不声称对原始上游品牌仓库或网站进行了全新爬取（fresh crawl）」；
4. 禁止添加components.html或DESIGN.md中不存在的组件配方（Avoid adding new component recipes not represented）—— 组件语汇边界以两个权威文件为准，超出即视为破坏包契约。

六、令牌系统源码级拆解：56 个令牌与四层语义

6.1:root令牌块：唯一事实源

design-systems/ant/tokens.css 在:root中声明了完整令牌集合，全部 56 个令牌按语义可分为以下类别：

颜色令牌：--bg: #ffffff（页面背景）、--surface: #f7f8fa（卡片/面板表面）、--surface-warm: #fff1f0（暖色表面）、--fg: #1f1f1f（正文前景）、--fg-2: #4b5563（次级文本）、--muted: #697386（弱化文本）、--meta: #d32029（元信息强调）、--border: #d9dce3（常规描边）、--border-soft: #eef0f4（柔和描边）、--accent: #d32029（强调/主操作）、--accent-on: #ffffff（强调色上的前景）、--accent-hover/--accent-active（强调色悬停/激活态，用color-mix(in oklab, var(--accent), black 8%/14%)派生）、--success: #22a06b、--warn: #faad14、--danger: #cf1322。

字体令牌：--font-display/--font-body均为"Ant Sans", "Alibaba PuHuiTi", Inter, Arial, sans-serif，--font-mono为"SF Mono", ui-monospace, Menlo, monospace。

字号与行高：--text-xs: 12px、--text-sm: 14px、--text-base: 16px、--text-lg: 18px、--text-xl: 22px、--text-2xl: 32px、--text-3xl: 48px、--text-4xl: 64px；行高--leading-body: 1.52、--leading-tight: 1.08；字距--tracking-display: -0.018em。

间距令牌：--space-1: 4px到--space-12: 48px（4/8/12/16/20/24/32/48），以及区块纵向节奏--section-y-desktop: 96px、--section-y-tablet: 68px、--section-y-phone: 48px。

圆角与层级：--radius-sm: 6px、--radius-md: 10px、--radius-lg: 16px、--radius-pill: 9999px；阴影--elev-flat: none、--elev-ring: 0 0 0 1px var(--border)、--elev-raised: 0 18px 42px rgba(31,31,31,0.10)、--focus-ring: 0 0 0 4px rgba(211,32,41,0.22)。

动效与容器：--motion-fast: 140ms、--motion-base: 220ms、--ease-standard: cubic-bezier(0.2, 0, 0, 1)；--container-max: 1200px、--container-gutter-desktop/tablet/phone: 36/24/16px。

6.2 TOKEN_SCHEMA 合同：四层令牌语义

design-systems/ant/design-tokens.json 与 design-systems/ant/source/token-contract.report.json 都遵循TOKEN_SCHEMA合同，报告显示：56 个令牌全部声明、全部有源可查（sourceBackedTokens: 56）、合同评分score: 100、评级excellent、无需重建（recommendRebuild: false）。每个令牌记录还带sources字段精确指向 design-systems/ant/tokens.css 的声明行号（如tokens.css:7对应--bg）。

令牌按层级（layer）分为四类，这个分层是理解整个合同的关键：

从结构上可以推断：A1 两层是品牌与结构的基础契约，A2 是可替换的派生实现，B-slot 是供组件消费的语义槽位 —— 这解释了 USAGE.md 为什么强调「精确保留 schema token 名称」：跨品牌切换时，只需替换 A1-identity 层的值，结构、派生与槽位层即可整体继承。

6.3 组件清单：可复用资产索引

design-systems/ant/components.manifest.json 对 design-systems/ant/components.html 做了完整的机械化审计：fixture 包含 1 个<style>块、48 个选择器、26 个类、19 个元素；同时把声明的 56 个令牌与组件中实际引用的令牌做了比对，得出unusedDeclared（如--accent-active、--danger、--elev-flat、--motion-base、--space-1、--space-12、--warn）与undeclaredReferenced: []（无未声明引用，契约自洽）。

组件按 9 个分组（groups）组织，其中 6 个组在 fixture 中真实存在（present: true），每个组都列出了其选择器、类与令牌引用，这是 Agent 复用时最直接的索引：

（keyboard键盘提示与icons图标槽两个分组在 fixture 中present: false，即本包当前不提供这类资产。）

6.4 参考组件实现：选择器与状态的权威来源

当需要精确选择器或状态细节时，直接看 design-systems/ant/components.html。该文件是一个完整的「财务平台控制台（Financial platform console）」参考页面，其关键实现可提炼为可直接复制的模式：

• 页面骨架：body使用--bg背景、--fg文本、--font-body、--text-base、--leading-body；.page使用linear-gradient(135deg, #ffffff 0%, #fff1f0 100%)营造暖色到白色的层次；
• 容器与响应式：.container以--container-max: 1200px居中，padding-inline在三档断点（desktop/tablet/phone）分别取--container-gutter-desktop/tablet/phone；section的纵向节奏对应--section-y-*三档；< 860px时 hero、lower、metric-grid、card-row 塌缩为单列；
• 排版体系：h1用--text-4xl（64px）加font-weight: 760，h2用--text-3xl，h3用--text-xl；.eyebrow用--font-mono+--text-xs+0.12em字距 + 大写，--meta着色，形成「眉标」层；
• 按钮状态机：.btn最小高度 44px、--radius-md圆角、700 字重--text-sm，过渡统一--motion-fast+--ease-standard；:focus-visible使用--focus-ring且outline: none；primary 用--accent底色、hover 变--accent-hover并上移 1px；secondary 用--surface底、--elev-ring描边、hover 时边框与文字切到--accent；
• 数据组件：.metric-grid三列等宽、.metric之间用--border-soft分隔；.metric strong用--font-display+--text-2xl呈现指标数字，.metric span用--muted+--text-sm呈现标签 —— 这正是「data-dense」风格的典型形态；
• 状态徽章：.status用--meta+ 等宽字体 + 大写表达在线状态，:before用--success的 8px 圆点（--radius-pill）作状态灯；
• 输入控件：input46px 高、--radius-sm圆角、--surface底、:focus时border-color: var(--accent)+--focus-ring，配合 700 字重的label（--fg-2+--text-sm）。

七、Tailwind v4 派生绑定：如何在 Tailwind 项目中消费令牌

若项目使用 Tailwind v4，官方提供的桥接文件是 design-systems/ant/tailwind-v4.css。它先@import "tailwindcss"与@import "./tokens.css"，再通过@theme块把每个 CSS 变量重新映射为 Tailwind 主题键，形成两套命名空间：

• 颜色：--color-bg/surface/surface-warm/fg/fg-2/muted/meta/border/border-soft/accent/accent-on/accent-hover/accent-active/success/warn/danger；
• 字体：--font-display/body/sans/mono；
• 字号与行高：--text-xs至--text-4xl、--leading-body/tight、--tracking-display；
• 间距：--spacing-1至--spacing-12、--spacing-section-desktop/tablet/phone、--spacing-container-desktop/tablet/phone；
• 圆角/阴影/动效/容器：--radius-sm/md/lg/pill、--shadow-flat/ring/raised/focus-ring、--duration-fast/base、--ease-standard、--container-max。

注意该文件的头注释再次强调：这是从tokens.css派生的产物，tokens.css才是唯一事实源 —— 这也与 USAGE.md「Avoid redefining Tailwind or design-token values independently of tokens.css」的禁令互相印证。使用方式上，应当复制tokens.css的:root块作为基础，再按需引入@theme映射，不要单独改写任意一侧的值。

八、视觉意图（DESIGN.md）：从令牌到成品的八维规范

design-systems/ant/DESIGN.md 是视觉意图的权威文件，USAGE.md 要求在其之后阅读。它给出的风格基调是「结构化、企业聚焦，强调清晰、一致与效率，服务于数据密集型 Web 应用」，并逐维展开：

• 色彩：主色#1677FF、次要#8B5CF6、成功#16A34A、警告#D97706、危险#DC2626、表面#FFFFFF、文本#111827，中性色由表面令牌派生（#FFFFFF，为官方格式兼容而派生）；实践建议：CTA 强调用主色、大背景与卡片用表面色、正文保持文本色以获得可读性。注意：DESIGN.md 中的这些色值是「风格基础」层的描述，而tokens.css中的--accent: #d32029等是实际消费的令牌值 —— 两者分别对应「设计意图」与「工程实现」，这正是 Design System 2.0 中「契约（contract）与实现（implementation）」分离的体现；
• 排版：字号阶梯 12/14/16/20/24/32，主字体与展示字体均为 Plus Jakarta Sans，等宽字体 JetBrains Mono，字重覆盖 100–900；标题承载风格个性，正文优化扫读与对比；
• 间距与栅格：间距阶梯 4/8/12/16/24/32；保持纵向节奏一致，列与模块对齐到可预测的栅格，禁止随意偏移；
• 布局与构成：偏好带一致内边距的清晰内容块；层级保持「标题 → 支撑文本 → 主操作」的显式顺序；先用留白区分关注点，再考虑边框与阴影；
• 组件：按钮主操作用#1677FF、次操作保持中性；输入框有强 focus-visible 状态、清晰标签与可预测的错误提示；卡片/区块在全页使用一致的圆角、间距与抬升策略；
• 动效与交互：用微妙过渡突出主色作为交互信号；默认 150–250ms 的短促过渡与稳定缓动（对应令牌--motion-fast: 140ms、--motion-base: 220ms、--ease-standard）；hover、focus-visible、active、disabled、loading 状态必须显式表达；
• 语音与品牌：语调与视觉风格一致 —— 简洁、自信、产品化；微文案行动导向，避免空泛填充语；标题保留风格个性，UI 标签保持直白清晰；
• 反模式：禁止在已有令牌能解决问题时引入色盘外的颜色；禁止用相同字号/字重扁平化层级；禁止添加降低可读性或无障碍性的装饰效果；禁止在同一界面混用无关的视觉隐喻。

系统资产与暗色套件

system/目录提供整套系统资产视图：design-systems/ant/system/index.html 是系统资产总览（内部嵌入与tokens.css完全一致的 56 个令牌声明），另有 design-systems/ant/system/kit.html（亮色组件套件）与 design-systems/ant/system/kit.dark.html（暗色组件套件）。从文件名可以推断，暗色套件主要用于校验令牌在暗色表面的可读性 —— 由于全部颜色走:root令牌，换肤只需要替换令牌块即可实现。

九、实战落点：用 Ant 包产出企业级界面的最小工作流

综合包契约与实现细节，一次合规的 Ant 风格产出遵循如下最小工作流：

1. 读契约：依次读完 design-systems/ant/USAGE.md 与 design-systems/ant/DESIGN.md；
2. 贴令牌：把 design-systems/ant/tokens.css 的:root块原样粘贴到产物首个<style>块，之后一律通过var(--*)消费颜色、字号、间距、圆角、阴影、动效，禁止出现令牌块之外的裸 hex；
3. 选组件：对照 design-systems/ant/components.manifest.json 的分组与 design-systems/ant/components.html 的选择器，优先复用.btn/.btn-primary/.btn-secondary、.field/label/input、.panel/.tile/.card-row、.status、.metric-grid/.metric、.eyebrow/.lead等既有语汇；components.html中的「Financial platform console」页面本身就是一套可参照的完整构成示例；
4. 守纪律：--accent只服务单一焦点；交互状态（hover/focus-visible/active/disabled/loading）全部显式实现；不添加清单之外的组件配方；
5. 验证：需要视觉确认时打开preview/或system/页面；需要审计令牌时查看 design-systems/ant/source/token-contract.report.json，确认undeclaredReferenced为空、评分保持 100。

十、事实边界与适用前提

需要明确的是：本包基于 OpenDesign 官方整理的捆绑 fixture派生，design-systems/ant/source/evidence.md 明确声明其不包含对上游 Ant 品牌仓库或网站的新鲜爬取证据，因此引用本包时不应声称拥有上游原始源码证据（对应 USAGE.md 的 Avoid 第 3 条）。所有令牌值、选择器与组件语汇均以本仓库design-systems/ant/目录下的实际文件为准；若你需要的组件形态（如键盘提示、图标槽）在该包中present: false，应优先考虑换用其他设计系统包，而不是自行发明配方破坏包契约。设计令牌的消费方式（CSS 变量与 Tailwind v4@theme映射）以上述文件为唯一依据，其他框架的接入方式需要在此基础上自行封装。

• AI 应用
• 人工智能
• AI 技能
• 设计系统
• 媒体生成