Skip to content
← 返回套件

design-system 附加组件

为一个拥有面向用户界面表面的仓库提供一份 DESIGN.md——一个 Markdown 设计系统文件，任何编码代理都会读取它，以生成与仓库自身约定一致的界面输出，而不是在没有指引时退回到那种无样式、统计上常见的默认值。这是 Deep Work Plan 的第四个可选附加组件。

“界面表面”是复数的：一个渲染出来的可视化 UI、带样式的 CLI 输出，以及一个会话式表面（产品在聊天或电子邮件上说话）都各自算数。该附加组件把每一种都作为一个**配置档（profile）**独立检测，被采纳的各配置档则叠加进同一份单一的 DESIGN.md。

它添加了什么

  • 一份位于 docs/DESIGN.md 的 DESIGN.md（与仓库的其他规范并列；仅当没有 docs/ 目录树时才置于仓库根目录），并从 AGENTS.md 引用，使代理像发现其余文档那样发现它。一个仓库，一份文件——绝不按表面拆分出并列文件。
  • visual-ui 配置档 —— 各规范可视化小节：概览/氛围、配色与角色（浅色 + 深色）、排版、布局与间距、层级与纵深、形状、组件、响应式行为、宜与忌（含仓库的无障碍规则）。
  • cli-output 配置档 —— 带样式的终端界面：输出语态、语义化颜色与样式（success/error/warning/info/dim 映射到真实主题）、输出组件（面板、表格、加载指示器、交互式提示——以仓库真实的辅助函数命名）、布局约定，以及降级规则（TTY 与管道之别、NO_COLOR、stdout/stderr 纪律、退出码）。
  • conversational 配置档 —— 产品的消息表面：语态与语域（语气、简洁度、品牌命名规则）、消息结构（私信、频道帖子、线程回复、就地编辑），以及按平台的渲染（Slack mrkdwn、Discord Markdown、Teams 自适应卡片、电子邮件）及纯文本回退。
  • 一份共享的代理提示词指南，外加一个核查各配置档完整性的验证步骤：所记录的文本对比度满足 WCAG AA（可视化）、颜色绝不是含义的唯一载体（CLI）、富渲染注明纯文本回退（会话式），以及 token 引用能够解析。

行为

  • 推理，而非复制。 每一个值都从仓库真实的设计来源中推导而来——它的样式表、CSS 自定义属性、Tailwind 配置、token 文件、组件样式、它的 CLI 显示/主题模块，或它的消息组装辅助函数。它绝不会粘贴某个第三方品牌的 DESIGN.md，也不会整体引入另一个产品的约定；参考目录是结构上的灵感，绝非内容来源。
  • 调和，而非覆盖。 一份既有的 DESIGN.md 或 token 来源会以增量方式被调和，绝不被覆写；新增一个被采纳的配置档只会追加其小节，而不重写其余部分；破坏性更改需要批准。
  • 凭引用发现。 无论 DESIGN.md 位于何处，AGENTS.md（以及 CLAUDE.md）都会引用它——保证代理加载它的是那个指针，而非物理位置。
  • 务实，而非硬性绑定。 它把正在形成的 DESIGN.md 约定作为可遵循的形态来参照，将其扩展到非可视化表面，并保持以 Markdown 为先，不绑定于任何单一的 token 模式。

限定于界面范围，各配置档强度不同

这个附加组件面向至少拥有一个真实界面表面的仓库；它绝不会为没有任何界面表面的仓库提供（纯库、headless 服务、仅基础设施的仓库）。每个配置档都带有自己的推荐强度：

  • visual-ui 在检测到时默认开启 —— 一个带有 CSS 自定义属性的样式表、一份 Tailwind 配置或 @theme 块、UI 组件，或一份品牌/样式指南。接入会在信任模式下应用它，并在引导模式下强烈推荐它。
  • cli-output 与 conversational 在检测到时被推荐——并且始终先询问，绝不自动应用，即使在信任模式下也是如此。一个 CLI 渲染库外加一个刻意构建的显示层标志着前者；一个聊天平台 SDK 或消息组装层标志着后者。一个只做原始打印的简单参数解析器并不符合条件。

它从不是必需的——一个不带任何附加组件的仓库完全符合规范，你也始终可以拒绝任意配置档或整个附加组件。一份在配置档存在之前创建的 DESIGN.md 是一份有效的单配置档可视化文件：无需迁移。

可选命令

被采纳时，该附加组件可向仓库的 .agents/commands/ 中安装一个 /design-system 委派器，以便日后重新生成或刷新 DESIGN.md。安装该命令是可选的；被拒绝的附加组件不安装任何东西。

与按特性的设计文档的关系

这是一份仓库级、持久的设计系统文件——区别于按特性的技术设计文档（工具绑定式规范驱动工作流中那种“需求 → 设计 → 任务”的 design.md）。Deep Work Plan 刻意不附带任何独立的按特性设计文档原型：一份计划的 README、每项任务的验收标准，以及各验证关卡，已经覆盖了那一角色。这个附加组件填补了那一角色未覆盖的唯一空白：持久的、仓库原生的界面设计上下文。