agentic-design-systems

Agentic Design Systems

触发此技能时，你需要帮助用户构建、扩展或审查一个主要面向 AI Agent 的组件库。目标是：面对类似 “构建一个包含破坏性操作的确认模态框” 这样的自然语言请求，Agent 能选对组件、变体和令牌，而不会自行发明模式。

此技能会提供架构、工作流和原则。请根据用户的实际情况灵活调整。

---

先诊断

在产出任何内容之前，先判断适用的模式：

• 从零开始 — 用户要启动一个面向 Agent 的新系统。按照构建工作流逐步进行。从架构和一个示例组件（Button 是典型示例）开始；不要试图一次搭建所有内容。
• 改造现有系统 — 用户已有组件库，并希望让 Agent 能读懂它。跳过工作区设置。添加 meta.types.ts，然后为每个组件编写一个 .meta.ts，最后构建索引和验证器。先处理反模式（参见第 5 步）。
• 审计 — 用户已有元数据。根据四大支柱和验证器检查项为每个组件评分。标出缺失的关系、文字反模式、原始全局令牌和缺乏依据的变体轴。
• 单个组件 — 用户只想添加或修复一个组件。按照第 3 步生成完整文件集。元数据要么随组件一起交付，要么就不交付。

如果提示不明确，提出一个有针对性的问题，不要猜测。

---

四大支柱

将每个组件视为四项内容的交集。大多数元数据架构只描述第一项，这就是 Agent 会误用组件的原因。

支柱	回答的问题	缺失时的失败模式
Props	要设置哪些内容	（始终存在）
变体	应选择哪种组合	Agent 选择无效组合
关系	组件在结构和无障碍方面应如何融入	Agent 生成的代码可以编译，但结构不正确
令牌（组件作用域）	哪些设计值与此组件绑定	Agent 自行编造颜色和间距

另外还有 aiHints——这是元层，用于告诉 Agent 何时使用组件、哪种变体适合哪种情境，以及绝对不能做什么。

架构中固化的四项设计决策

• 状态隐含在令牌中，而不是单独作为一个支柱。 编码 button-primary-bg-hover、button-primary-bg-disabled 等。主题切换只需替换令牌；保持单一事实来源。
• 变体是一个矩阵，而不是扁平枚举。 声明轴（appearance × size × density），让 Agent 选择其中一个单元格。对于不应交付的单元格，使用 invalidCombinations。
• 无障碍能力归入关系。 ARIA role、keyboardSupport 和 screenReader 描述组件如何融入文档和交互模型——这属于关系。不需要单独的无障碍支柱。
• 反模式是一等且结构化的内容。 不要使用散文。始终使用 {scenario, reason, alternative} 三元组——它们能确保描述精确。

---

架构（规范契约）

将其一次性写入 meta.types.ts。每个组件的 .meta.ts 都会导入它并进行类型检查。架构本身就是契约。

interface ComponentMeta {
  component: {
    name: string;
    category: "atoms" | "molecules" | "organisms";
    type: "interactive" | "display" | "container" | "input" | "navigation";
    description: string;
    path: string;
    figma?: { nodeId: string | null };
  };

  props: Record<string, PropDef>;

  variants: {
    axes: Record<string, readonly string[]>;
    purpose: Record<`${string}.${string}`, string>;
    invalidCombinations?: { axes: Record<string, string>; reason: string }[];
  };

  relationships: {
    requires?: string[];           // contexts/providers above
    mustBeChildOf?: string[];
    mustBeParentOf?: string[];
    optionalSibling?: string[];
    commonPartners?: string[];
    triggers?: string[];           // events emitted
    blocksWhen?: { when: string; effect: string }[];
    exposesState?: string[];       // state descendants can read
    role: string;                  // a11y
    keyboardSupport: string;
    screenReader: string;
  };

  tokens: {
    color?: Record<string, string>;
    spacing?: Record<string, string>;
    typography?: Record<string, string>;
    border?: Record<string, string>;
    motion?: Record<string, string>;
    elevation?: Record<string, string>;
  };

  aiHints: {
    priority: "high" | "medium" | "low";
    keywords: string[];
    selectionCriteria: Record<string, string>;
    usage: {
      useCases: string[];
      commonPatterns: { name: string; composition: string }[];
      antiPatterns: { scenario: string; reason: string; alternative: string }[];
    };
  };
}

生成组件的 .meta.ts 时，填写所有适用字段。空数组可以接受，但不能缺少键——这正是验证器要检查的内容。

---

构建工作流

第 1 步 — 工作区结构

建议在使用方应用的 monorepo 中创建一个同级包（packages/ui-next/）。之后切换时只需重写导入语句。只有在需要独立版本管理时，才适合使用单独的仓库。

第 2 步 — 将架构作为 TypeScript 契约

在编写任何组件之前，先编写 meta.types.ts。其他所有内容都以此为基础。

步骤 3 — 端到端构建一个组件

选择一个小巧且使用频率高的组件。Button 是典型示例。一次性交付完整套件：

Button/
  Button.tsx              ← implementation
  Button.meta.ts          ← four pillars + aiHints
  Button.tokens.css       ← component-scoped tokens
  Button.stories.tsx      ← visual test surface
  Button.test.tsx         ← behavior tests
  index.ts                ← single canonical export

尽早配置 Storybook（.storybook/main.ts 用于发现 story，.storybook/preview.ts 用于导入主题）。为变体矩阵中的每个单元格编写一个 story，一眼就能发现设计空间中的回归问题。

组件要么连同元数据一起交付，要么就不交付。不要把元数据留到以后再做。

步骤 4 — 两层设计令牌

• tokens/core.css — 原始品牌调色板和比例（--color-brand-600、--space-4）。
• tokens/themes/*.css — 将组件级设计令牌（--button-primary-bg）映射到核心值。

组件 CSS 只能引用组件级设计令牌。切换主题就能保持机械化。

步骤 5 — 先定义反模式

对每个组件，都要在编写实现代码之前编写 antiPatterns 数组。结构化三元组格式（scenario、reason、alternative）能强制要求精确——不能只写“不要过度使用主按钮”，而必须写清楚是哪种场景、为什么不合适、应该改用什么。反模式最终会推动 API 的设计。

步骤 6 — 将变体轴视为坐标系

变体不是一个扁平的字符串列表。声明各个轴（appearance × size × density），让 Agent 沿着相互独立的维度进行选择。使用 invalidCombinations 排除不应发布的单元格（例如 appearance: "ghost" × size: "xs"——尺寸太小，无法点击）。

步骤 7 — 将关系定义为可由机器检查的规则

• requires — 上层必须存在的提供者
• mustBeChildOf / mustBeParentOf — 结构约束
• triggers — 发出的事件
• blocksWhen — 依赖属性状态的行为
• exposesState — 后代可读取的内容

这是防止 Agent 生成虽能编译、结构却不正确的代码的关键支柱。

步骤 8 — 分层元数据索引

生成 metadata/index.json——一个包含 {name, category, path, keywords, priority} 的扁平列表。Agent 会先扫描该索引以筛选候选组件，然后只针对相关组件读取完整的 .meta.ts。发现成本低，深入成本高。

使用脚本（scripts/build-index.ts）构建索引：遍历每个 *.meta.ts，动态导入每个文件并写入 JSON。每次元数据变更时都运行该脚本，这样索引就不会错误反映已有内容。

步骤 9 — 元数据验证器

编写一个简短脚本（scripts/validate-metadata.ts），遍历每个 *.meta.ts（通过 fast-glob），动态导入每个文件，检查导出内容的结构，并断言：

• 每个变体轴单元格都出现在 aiHints.selectionCriteria 或 variants.purpose 中
• 每个 tokens.* 键都是组件级的（组件名称的 kebab-case 形式）
• priority: "high" 的组件必须具有非空的 antiPatterns
• relationships.role / keyboardSupport / screenReader 非空（强制落实“将无障碍要求纳入 Relationships”的决定）
• invalidCombinations 只引用已声明的轴值

在 CI 中运行。如果元数据有误，构建就会失败。该架构是强制执行的，而非仅供参考。

步骤 10 — 切换（按组件逐步进行，而非一次性整体切换）

不要等到最后才切换——每个组件达到平价时就切换。

• API 平价跟踪器 — 旧组件库导出内容 → 新组件库对应项的 Markdown 检查清单。
• 设计令牌桥接 — 将旧设计令牌映射到新的组件级设计令牌。
• Codemod — 按页面重写导入语句。

---

原则

• 精简优先，不依赖生成。 前约 10 个组件的元数据手动编写。只有在模式明显后才自动化。
• 直接导入，不用导出汇总文件。 每个组件只有一个规范路径。提供两种导入方式，Agent 就会选错。
• 所有内容就近放置。 组件、元数据、令牌、故事和测试都放在同一个文件夹中。
• 以反模式驱动设计。 先编写反模式，它们能揭示契约。
• 组件级令牌。 组件的 CSS 中绝不引用原始全局令牌。
• 状态写在令牌中。 不要添加 states 块，也不要添加 behavior.states 数组。
• 无障碍具有关系性。 它属于 Relationships，而非独立的支柱。
• Schema 就是契约。 验证器在 CI 中运行；元数据验证失败就会导致构建失败。

---

成功的标准

用户向 Agent 提供一张 Figma 截图或一段文字需求——“构建一个带有破坏性操作的确认模态框”——Agent 随后会：

1. 扫描 metadata/index.json，筛选出 Modal、Button 和 Heading。
2. 阅读每个入选组件的 .meta.ts。
3. 发现 Button.relationships.mustBeChildOf 包含 ModalFooter；根据 aiHints.selectionCriteria 选择 appearance: "danger"。
4. 因为 antiPatterns 标记了两个同级的 appearance: "primary" 按钮，所以会避开这种做法。
5. 引用组件级令牌，绝不臆造颜色。
6. 首次生成的代码就符合契约。

这就是标准。如果元数据无法引导 Agent 达到这一结果，就改进元数据。