F6 文心文档

文心文档（Wenxin Documentation）是文心设计语言的第六种输出形态。专为 API 文档、知识库、Wiki 和技术手册设计，以双栏布局为核心——左侧 240px 固定侧边栏提供导航，右侧内容区承载正文、代码示例和交互组件。

与一般文档站不同，文心文档继承了文心设计语言的全部灵魂：暖土调色板、衬线正文、极简交互、以及严格的 Accent 克制。即便是技术文档，也应该让人愿意读下去。

提示

文心文档的核心哲学与所有形态一致——文字即界面，留白即设计，克制即力量。文档本身不是装饰品，它是开发者阅读和查阅的工具。

核心特性

双栏布局：左侧 240px 固定侧边栏 + 右侧内容区，桌面端双栏，移动端折叠为抽屉
暖色调语法高亮：棕 / 金 / 红 / 灰四色方案，杜绝冷色调（蓝 / 绿 / 紫）
5 种提示框：tip / warning / danger / info / note，左侧彩色竖线 + 图标
增强代码块：标题栏、复制按钮、行号、暖色调高亮
目录跟踪：桌面端右侧 TOC 实时高亮当前章节
响应式：桌面双栏 → 平板折叠 → 移动端全屏抽屉
暗色模式：暖暗色底 + 暖象牙白文字，非简单反转

/* 导入文心 Token */
@import '@wanxing/tokens/wenxin-tokens.css';

/* 文档站使用 F6 profile */
@layer docs {
  .sidebar {
    width: var(--sidebar-width, 240px);
    background: var(--color-bg-base);
  }
}

安装与配置

万形文档站可以通过三种方式启动：一键初始化、从现有项目集成、或直接使用 CDN 加载文心 Token。

前提条件

Node.js ≥ 18
包管理器：npm / yarn / pnpm
现代浏览器（Chrome 90+ / Firefox 90+ / Safari 15+）

方式一：CLI 初始化（推荐）

万形 CLI 会引导你完成项目创建，自动生成文心文档站的完整骨架。

# 初始化新项目
npx create-wanxing@latest my-docs --template docs

# 进入项目目录
cd my-docs

# 启动开发服务器
npm run dev

说明

--template docs 会使用 F6 Documentation 的布局和组件预设。如果不指定模板，默认使用 F1 Web（通用内容站）。

方式二：手动配置

如果你已有项目，可以直接导入文心 Token CSS 和文档站组件：

/* 文心核心 Token */
@import '@wanxing/tokens/wenxin-tokens.css';

/* F6 文档站组件 */
@import '@wanxing/forms/f6-docs.css';

方式三：CDN

<link
  rel="stylesheet"
  href="https://cdn.wanxing.dev/tokens/v3/wenxin.css"
/>

第一个项目

以下示例展示如何用文心文档组件构建一个最小可用的 API 文档页面。你需要一个 .html 文件，内联或外链文心 Token。

<!DOCTYPE html>
<html lang="zh-CN"
      data-wanxing-profile="F6"
      data-wanxing-contract-version="1">
<head>
  <link rel="stylesheet"
        href="@wanxing/tokens/wenxin.css">
</head>
<body>
  <!-- 侧边栏 + 内容区 -->
</body>
</html>

以上代码标记了 data-wanxing-profile="F6" 后，文心运行时会自动加载文档站的布局引擎——双栏侧边栏、代码高亮、提示框组件。你只需编写 Markdown 内容，万形构建工具会编译为最终 HTML。

注意

请确保 data-wanxing-profile 值为 "F6"（大写 F + 数字）。错误的值会导致布局引擎无法正确加载，回退到默认的 F1 Web 单列布局。

设计哲学

文心设计语言的核心命题只有十二个字：文字即界面，留白即设计，克制即力量。

内容本身是最重要的视觉主体。所有 UI 决策服务于同一目标：让用户最自然、最安静地进入内容——而不是被界面打断。文心的设计结构分为两层：

灵魂层（Soul）——永远不变：色彩系统、字体哲学、留白密度、点睛之色、动效节奏。任何场景、任何产品类型，灵魂层不妥协。
形态层（Form）——随境而化：布局结构、导航形式、内容组织方式。跟随该类型产品的行业 UX 最佳惯例，不强行套用统一形状。

水的本质（H₂O）不因容器而改变，但在杯子里是杯子的形，在河道里是河道的形。用户感受到的不是「风格统一」，而是「说不出的舒服」。

三项灵魂原则

减法优先（Reduction First）——任何元素若无法让内容更清晰，就不应存在。没有装饰阴影，没有多余边框，没有视觉噪声。

克制的惊喜（Restrained Surprise）——动效的存在如同书页翻动时纸张的阻力：你感到用心，但不会停下来欣赏它。品牌标识符 ■ 是这一原则的具象化——全页唯一的几何强调，出现越少，力量越大。

点睛之色（Accent as Focal Point）——全页只允许一个强调色（砖红 --color-accent），它是整个设计的灵魂签名。全页出现 ≤ 2 处（图标激活 / 选中态除外）。

Accent 约束

砖红色 --color-accent 全页出现 不超过 2 处。图标激活 / 选中态不计入。如果你发现自己在 3 个以上的地方想用 Accent，说明你需要重新梳理信息层级，而非增加颜色。

色彩系统

文心色彩系统以 暖土调（Warm Earth） 为基调——暖白底 + 砖红 / 赭石强调，东方自然美学。色彩来自泥土、陶器、茶叶、宣纸。

语义色 Token

类别	Token	亮色模式	暗色模式
背景	`--color-bg-warm`	`#F2F0EB`	`#1A1816`
	`--color-bg-base`	`#FAFAF8`	`#201E1B`
	`--color-bg-pure`	`#FFFFFF`	`#242220`
文字	`--color-text-primary`	`#3A3837`	`#E8E3DC`
	`--color-text-secondary`	`#888580`	`#8A857D`
	`--color-text-heading`	`#2C2B29`	`#F0EBE3`
点睛	`--color-accent`	`#8B3525`	`#C4533E`

CSS 定义

:root {
  --color-accent: --color-accent;    /* 砖红·全页 ≤ 2 处 */
  --color-bg-warm: #F2F0EB;   /* 暖白·羊皮纸质感 */
  --color-bg-base: #FAFAF8;   /* 内页背景 */
  --color-bg-pure: #FFFFFF;   /* 纯白·正文区 */
}

/* 暗色模式 */
@media (prefers-color-scheme: dark) {
  :root {
    --color-accent: #C4533E;  /* 暗色下略亮 */
    --color-bg-warm: #1A1816; /* 暖暗色 */
  }
}

字体系统

文心采用 衬线优先（Serif-first） 策略。正文和标题使用有温度的衬线字体——Lora、EB Garamond、Noto Serif SC。UI 标签、元数据和导航辅助文字使用无衬线（system-ui、Noto Sans SC）。

字体栈

角色	字体栈	用途
Display	`Lora, Georgia, Noto Serif SC, serif`	标题、品牌名
Body	`EB Garamond, Noto Serif SC, serif`	正文、长文阅读
UI	`system-ui, Noto Sans SC, sans-serif`	导航、标签、按钮
Mono	`JetBrains Mono, Fira Code, monospace`	代码块、行内代码

字号阶梯

:root {
  /* 10 级字号阶梯 — Major Third (1.250) */
  --text-xs:   0.694rem;   /* ~11px */
  --text-sm:   0.833rem;   /* ~13px */
  --text-base: 1rem;        /* 16px  */
  --text-md:   1.0625rem;  /* 17px · 正文推荐 */
  --text-lg:   1.25rem;    /* 20px */
  --text-3xl:  2.25rem;    /* 36px · h1 */

  /* CJK 行高 */
  --leading-relaxed: 1.85;  /* 中文正文 ≥ 1.6 */
}

间距系统

文心间距基于 4px 网格，从 4px 到 128px 共 10 级。区块间距以 96px（--space-24）为默认，当感觉「是不是太空了」时，往往才是对的。

核心 Token

Token	值	典型用途
`--space-4`	16px	按钮内边距、引用块内边距
`--space-5`	20px	正文段落间距
`--space-8`	32px	标题与正文间距
`--space-16`	64px	h2 与上方内容
`--space-24`	96px	大区块间距
`--space-32`	128px	页面顶部内边距

内容宽度

:root {
  /* 流体响应式内容宽度 */
  --width-article:  clamp(520px, 55vw, 640px);
  --width-content:  clamp(620px, 65vw, 760px);
  --width-showcase: clamp(700px, 72vw, 920px);
}

动效系统

文心动效的核心理念是 「春雨润物，细节有声」——动效不负责表演，不制造戏剧性，也不抢夺阅读。它像春雨一样，只在细节处让界面变得更顺、更暖。

文档站（F6）使用 E9-0 静水 强度——仅保留必要的状态反馈动效：侧边栏展开 / 折叠、搜索结果淡入、代码复制按钮反馈。没有进场动画、没有 stagger、没有品牌呼吸。

动效 Token

Token	值	用途
`--duration-fast`	180ms	颜色、透明度过渡
`--duration-base`	260ms	侧边栏展开 / 折叠
`--ease-default`	`cubic-bezier(0.25, 0.1, 0.25, 1)`	通用缓动

/* 侧边栏展开/折叠 — F6 唯一显著动效 */
.sidebar {
  transition: transform var(--duration-base)
              var(--ease-default);
}

/* 尊重用户动效偏好 */
@media (prefers-reduced-motion: reduce) {
  * {
    transition-duration: 0.01ms !important;
  }
}

备注

F6 文档站禁止使用任何 进场动画、列表 stagger、品牌呼吸、旋转、弹跳。如果你需要这些效果，请考虑使用 F1 Web 或 F5 Presentation。

输出形态 F1–F9 概述

文心设计语言支持 9 种正式输出形态（F1–F9），每种形态在保持灵魂层不变的前提下，适配不同的媒介和场景。

形态	名称	适用场景	动效强度
F1	HTML Web	响应式网站、博客、作品集	E9-1 春雨
F2	Mobile App	原生 / 混合移动应用	E9-1 春雨
F3	Brand Identity	Logo + 品牌视觉识别系统	E9-2 微澜（■ 呼吸）
F4	Print & Editorial	书籍、论文、杂志、Zine	E8 静止
F5	Presentation	路演、会议演讲、课堂讲座	E9-1 春雨
F6	Documentation	API 文档、知识库、Wiki	E9-0 静水
F7	Poster & Cover	活动海报、书籍封面	E8 / E9-1
F8	Diagram & Knowledge Map	架构图、流程图、知识地图	E9-0 静水
F9	Report & LaTeX	研究报告、策略报告、白皮书	E9-0 静水

每种形态都有独立的规范文件（在 .opencode/agents/wenxin/ 目录下），定义了该形态特有的布局、组件、字体阶梯和色彩约束。选择形态时，请匹配你的产品类型和主要使用场景。

重要

文心正式输出形态固定为 F1–F9，不再继续扩张。Dashboard、电商、游戏、复杂 3D 展示、重 CRM 不进入正式形态——这些场景与文心「文字即界面」的核心哲学冲突。

Token API

文心设计 Token 以 CSS 自定义属性 + JSON 导出 两种形式提供。你可以在 CSS 中直接使用变量，也可以通过 JavaScript 读取 Token 值用于动态渲染。

CSS 用法

/* 使用文心语义色 */
.my-component {
  color: var(--color-text-primary);
  background: var(--color-bg-pure);
  font-family: var(--font-body);
  padding: var(--space-6);
  transition: color var(--duration-fast)
              var(--ease-default);
}

JavaScript 读取

// 读取单个 Token
const accent = getComputedStyle(
  document.documentElement
).getPropertyValue('--color-accent');

// 输出: "#8B3525" (亮色) / "#C4533E" (暗色)
console.log(accent);

JSON 导出

文心同时提供静态 JSON 导出，方便在 Node.js 环境或无 DOM 场景使用：

# 导出亮色 Token
npx wanxing tokens export --theme light > tokens-light.json

# 导出暗色 Token
npx wanxing tokens export --theme dark > tokens-dark.json

破坏性变更警告

Token 名称已从 v2.x 的 --wenxin-* 前缀迁移为 直接语义名（如 --color-accent）。如果你从 v2 升级到 v3，请运行 npx wanxing migrate 自动替换。

审计 API

万形审计系统采用 多层审计架构——Render Contract（机器事实层）+ Audit Agent（规则 + 截图 + 动效运行时）。每个文心输出在交付前必须通过审计闭环。

Render Contract 结构

每个 HTML 输出必须内嵌 wanxing-render-contract JSON，声明输出形态、Accent 预算、动效参数等结构化指标：

{
  "profile": "F6",
  "project": {
    "name": "万形文档",
    "slug": "wanxing-docs"
  },
  "theme": {
    "darkModeRequired": true,
    "accentBudget": 2
  },
  "motion": {
    "intensity": "E9-0",
    "maxDurationMs": 260,
    "allowsLoop": false
  }
}

审计命令

# 运行完整多层审计
npx wanxing audit dist/wanxing-docs/index.html

# 仅运行 Render Contract 审计
npx wanxing audit --contract-only dist/wanxing-docs/index.html

备注

审计报告中的 Hard Gate 失败会阻断交付流程。常见 Hard Gate 包括：Accent 超预算、缺少暗色模式、动效超限、缺少 data-animations-complete 信号。