gravity-ui

使用 Gravity UI 构建 UI

基于 真实的 Gravity UI 组件构建 UI，不要凭记忆编写。Gravity UI 是一个由多个包组成的 React 设计系统（@gravity-ui/*），因此常见的两个问题是选错包，以及使用了错误版本的 API。本技能会引导你找到正确的包，帮助你了解已安装的版本，并避免臆造 API——应匹配已安装的版本，并遵循生态系统目录，而不是猜测。

步骤 0 — 先选择正确的包（生态系统路由）

在做任何其他事情之前，先确定任务需要哪个 @gravity-ui/* 库。不要根据训练数据猜测——生态系统中有许多容易混淆的包（charts 与 chartkit、uikit Table 与 @gravity-ui/table、date-components 与 date-utils 等），选错包是最常见的失败原因。

打开 references/package-routing.md 并阅读开头部分：其中包含生态系统目录、在线与离线来源顺序、“容易混淆的配对”辨析，以及每个包的一句话“用途／替代方案”。根据这些信息选择包，然后返回此处继续步骤 1。

只有选定包后，才运行步骤 1，了解该包已安装的版本和 API。

步骤 1 — 了解所选包的已安装版本

1. 阅读 package.json。 记下每个已安装的 @gravity-ui/* 包及其版本。已安装的版本才是事实依据，而不是你的记忆。从 node_modules 中解析版本范围（<pkg>/package.json 的 version 字段），不要使用根目录 package.json 中的范围字符串。

2. 按以下顺序获取即将使用的包的文档，找到能回答问题的第一个来源后即停止：

   (a) 本地 — 首先查看 node_modules/@gravity-ui/<pkg>/dist/docs/INDEX.md 或 node_modules/@gravity-ui/<pkg>/build/docs/INDEX.md。 如果该包没有 INDEX.md，则退回到包根目录下的 node_modules/@gravity-ui/<pkg>/README.md。 这是与已安装版本 完全一致 的文档——对于与版本有关的问题，始终优先使用。 注意：随包提供的文档是近期才加入的——uikit 仅从 7.45.0 起提供 build/docs； 更早的安装版本没有本地文档，这是预期情况，不是错误。请继续查看 (b)。 (b) 在线 — 按主版本获取每个包的 llms.txt： https://gravity-ui.com/llms/<pkg>/<major>/llms.txt （例如，^7.2.1 对应 /llms/uikit/7/llms.txt）。主版本 URL 提供该主版本的最新次版本——它会跟随主版本更新，但不保证与确切的修订版本一致。 如果本地没有该包的文档，则使用此来源。

3. 回退规则 — 来源失败或内容为空时，绝不能默默继续：

   • 如果本地没有该包的 README、dist/docs 或 build/docs，或者这些内容为空 → 获取在线主版本 llms.txt（b）。
   • 如果在线请求失败——网络超时、DNS 错误、连接被拒绝 （无网络环境／企业代理）、HTTP 404（未托管该主版本），或响应内容为空／非 Markdown 格式 → 回退到本地 README 及 dist/docs 或 build/docs（a）。
   • 不要使用 /llms/<pkg>/llms.txt“latest”别名作为回退方案——它提供的是最新主版本，可能与已安装版本不同，API 也可能不同。带主版本号的 URL 是有版本区分的回退来源；如果它不可用，应改用本地文档，而不是“latest”。
   • 如果某个包的本地和在线文档都无法访问 → 停止，并告知用户该包的文档无法访问。不要根据训练数据猜测其 API。

步骤 2 — 使用选定的包实现，然后进行类型检查

1. 仅使用步骤 0 中选定且在步骤 1 中确认已安装的 @gravity-ui/* 包进行实现。 请严格从这些包导入——不要替换成外观相似的库（MUI、Ant、普通的 <input>），也不要使用步骤 1 未确认已安装的 @gravity-ui/* 包。请遵循刚刚阅读的文档中的属性 API，而非凭记忆操作；如果你想用的属性没有文档说明，就说明它不存在——请使用有文档说明的属性，或询问用户。

2. 编写代码时，应用 rules/hallucination-traps.md 中的跨组件规则：排版变体、弹性布局约定、主题／阶梯、Button view、Icon data。各组件的陷阱见包自身的 dist/docs。

3. 宣布完成前进行类型检查。 运行项目的类型检查命令（通常是 tsc --noEmit；对于单体仓库，则运行工作区的类型检查脚本）。报告完成前修复所有错误——类型错误几乎总是意味着使用了错误／臆造的属性、错误的导入路径或不匹配的版本，而这正是步骤 0–1 要避免的问题。

   • 如果类型检查发现某个属性／路径与步骤 1 中阅读的文档相矛盾，请以已安装的版本（类型检查器）为准，而不是文档快照——文档可能来自不同的小版本。请重新核实：阅读 node_modules 中该包的 dist/docs/INDEX.md，以确认已安装版本的确切类型。
   • 如果无法进行类型检查（项目中没有 TypeScript），请明确说明，并询问用户希望如何验证；不要悄悄跳过验证。
   • 例外情况。 如果用户明确表示可以不验证（“只做个草图”“快速原型”“不用检查”），可以跳过类型检查，但必须在回复中明确说明：“根据用户要求跳过类型检查——代码未经验证”。不要悄悄跳过。
   • 了解类型检查无法覆盖的内容。 tsc 检查通过只能证明 API 确实存在；无法说明布局或对比度是否合适。报告完成前，请说明这一点，并自行检查或列出需要用户手动检查的项目：light 和 dark 两种主题下的屏幕（尤其是彩色填充上的文本和控件）、窄（约 375px）和宽（约 1400px）视口下是否存在水平溢出，以及空白／加载中／错误状态。

硬性规则

• 每个 Gravity UI 项目都必须安装 @gravity-ui/uikit。 它是基础组件和设计令牌库，其他所有 @gravity-ui/* 包都构建于其上；没有它，组件将无法应用样式。如果 package.json 中没有该依赖，请暂停并让用户先安装和配置（设置说明：https://gravity-ui.com/llms/uikit/llms.txt）。
• 导入任何 @gravity-ui/* 包之前，先阅读 package.json。 切勿假设某个包已安装，也不要假设其主版本号。
• 不要臆造属性或组件。 使用自己没有十足把握的组件 API 前，请查阅 rules/hallucination-traps.md（生态系统模式）和 dist/docs 中该组件的 README。如果仍不确定，请询问用户，不要猜测。
• 绝不要猜测图标名称——图标名称经常会被臆造。要匹配截图、照片或样图中的图标，请运行 scripts/icon-image-search.sh（反向图片搜索）。如果只有文字描述，请在 gravity-ui.com/icons 上查找名称，或询问用户——不要臆造。之后将其作为对象传入（<Icon data={CheckIcon} />），绝不要传入字符串键。参见 references/icons.md。
• 主题使用语义化的 --g-* 令牌。 不要硬编码颜色（#fff、blue-500），也不要手动编写 dark: 覆盖规则。完整令牌表见 references/theming.md；跨领域陷阱（局部品牌覆盖、为整个页面设置主题的 ThemeProvider、品牌背景上的控件）见 rules/hallucination-traps.md。
• 必需的设置因包而异（样式导入、ThemeProvider、peer 依赖）。每个包根目录的 README 中都有“Required setup”一节——每个包都要读一次，不要依赖记忆。

不要做的事

以下是 Agent 最常以这五种方式破坏 Gravity UI 代码。上面的规则已经涵盖了这些内容；这里再次明确列出，以示警戒。如果你准备做其中任何一项，请先停下来，重新核实依据。

• 不要替换为非 Gravity UI 库。 不要使用 MUI、Ant Design、原生 <input>/<button> 或外观相似的组件库。请使用任务所需的 @gravity-ui/* 包。
• 不要臆造组件 API 或属性。 如果你在步骤 1 阅读的文档中找不到某个属性，它就不存在——不要写 variant=、color=、name=（用于 Icon）或 header-3 变体。请使用文档中列出的属性，或询问用户。参见 rules/hallucination-traps.md。
• 不要把 /llms/<pkg>/llms.txt 的“latest”别名当作后备方案。 它提供的是最新主版本，可能与已安装的版本不同，API 也可能不一致。在线后备方案应使用带版本的主版本 URL（/llms/<pkg>/<major>/llms.txt）；再往下，就查本地文件。
• 不要只覆盖部分品牌令牌。 只设置 --g-color-base-brand 会使选中态、焦点态、链接和对比度仍使用默认强调色，导致 UI 不一致。请在所支持的每种主题中覆盖完整的品牌令牌集。
• 不要使用 [class*='…'] 或 ID 选择器覆盖内部标记。 这类规则针对某一种 DOM 结构编写，组件结构变化时会悄然失效。应按定制优先级逐步尝试（全局令牌 → 组件 CSS API → 范围狭窄且明确标记的变通方案），最后才考虑修改结构。

深入材料 — 按需阅读

这些文件与此 SKILL.md 位于同一目录，仅在相关时加载：

• references/package-routing.md — 生态目录的离线快照 （gravity-ui.com/llms.txt），每次发布此技能时刷新。用作 步骤 0 中的离线备用方案。
• references/theming.md — uikit docs/theming.md 的逐字副本： --g-* 令牌层、ThemeProvider、品牌定制、自定义主题、作用域主题、 uikit-themer。随附副本可能滞后——请阅读 node_modules/@gravity-ui/uikit/build/docs/guides/theming.md 获取 与当前版本匹配的文件。
• references/layout.md — uikit docs/layout.md 的逐字副本： 间距刻度（--g-spacing-*）、Flex/Box、Row/Col/Container 网格、断点、useLayoutContext。
• references/icons.md — 通过图像查找图标 （scripts/icon-image-search.sh），或在 gravity-ui.com/icons 上查找；以及 对象与字符串的渲染规则。
• rules/hallucination-traps.md — 最常见臆造 API 的错误/正确示例：排版变体（不存在 header-3..6，也没有 Heading）、Flex 约定（min-width:0、由谁收缩）、主题陷阱（部分品牌覆盖、为整个页面设置主题的 ThemeProvider、定制层级）、Button 使用 view 而非 variant、Icon 使用 data 而非 name。各组件的陷阱请参阅对应软件包的 dist/docs，此处不作说明。