gravity-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building UI with Gravity UI

使用Gravity UI构建UI

Build UI on real Gravity UI components, not from memory. Gravity UI is a multi-package React design system (

@gravity-ui/*

), so the two things that go wrong are picking the wrong package and using an API from the wrong version. This skill routes you to the right package, grounds you in the installed version, and stops you from inventing APIs — match the installed versions and follow the ecosystem catalog instead of guessing.

基于真实的Gravity UI组件构建UI，而非凭记忆。Gravity UI是一个多包的React设计系统（

@gravity-ui/*

），常见问题有两个：选错包和使用错误版本的API。本技能会引导你选择正确的包，基于已安装的版本进行开发，避免虚构API——请匹配已安装的版本并遵循生态目录，而非猜测。

Step 0 — pick the right package first (ecosystem routing)

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

Before doing anything else, work out which

@gravity-ui/*

library the task needs. Do not guess from training data — the ecosystem has look-alike packages (

charts

chartkit

, uikit

Table

@gravity-ui/table

date-components

date-utils

, …) and picking the wrong one is the #1 failure.

Open

references/package-routing.md

and read its top: it is the ecosystem catalog, with the live-vs-offline source order, the "painful pairs" disambiguation, and a one-line "what it's for / what to use instead" per package. Use it to choose the package, then come back here for Step 1.

Only after the package is chosen, run Step 1 to ground in that package's installed version and API.

在开展任何工作前，先确定任务需要哪个

@gravity-ui/*

库。不要凭训练数据猜测——生态系统中有相似的包（

charts

chartkit

，uikit的

Table

@gravity-ui/table

，

date-components

date-utils

……），选错包是最常见的失败原因。

打开

references/package-routing.md

并阅读其顶部内容：这是生态目录，包含在线/离线资源优先级、易混淆包的区分说明，以及每个包的一行用途/替代方案说明。用它来选择包，然后回到这里进行步骤1。

只有在选定包后，再执行步骤1，基于该包的已安装版本和API开展开发。

Step 1 — ground in the installed version of the chosen package

步骤1 — 基于选定包的已安装版本开展开发

Read
package.json
. Note each installed
```
@gravity-ui/*
```
package and its version. The installed version is the source of truth, not your memory. Resolve ranges from
```
node_modules
```
(
```
<pkg>/package.json
```
```
version
```
field), not the range string in the root
```
package.json
```
.
Fetch the docs for the package you are about to use, in this order, stopping at the first source that answers your question:
(a) LOCAL — start with
```
node_modules/@gravity-ui/<pkg>/dist/docs/INDEX.md
```
or
```
node_modules/@gravity-ui/<pkg>/build/docs/INDEX.md
```
. If
```
INDEX.md
```
is absent for this package, fall back to the package's root
```
node_modules/@gravity-ui/<pkg>/README.md
```
. This is the exact installed version — always preferred for version-sensitive questions. (b) ONLINE — per-package llms.txt at the major line:
```
https://gravity-ui.com/llms/<pkg>/<major>/llms.txt
```
(e.g.
```
/llms/uikit/7/llms.txt
```
for
```
^7.2.1
```
). The major-line URL serves the latest minor of that major — it tracks the major but not the exact patch. Use it when LOCAL has no docs for the package.
Fallback rule — never silently proceed on a failed or empty source:
- If LOCAL has no README /
```
dist/docs
```
  /
```
build/docs
```
  for the package, or they are empty → fetch the ONLINE major-line llms.txt (b).
- If the ONLINE request fails — network timeout, DNS, connection refused (air-gapped / corporate proxy), HTTP 404 (major not hosted), or an empty / non-markdown body → fall back to LOCAL README + dist/docs or build/docs (a).
- Do NOT use the
  /llms/<pkg>/llms.txt
  "latest" alias as a fallback — it serves the newest major, which may differ from the installed one and have a different API. The major-line URL is the versioned fallback; below it, go LOCAL, not "latest".
- If BOTH are unreachable for a package → STOP and tell the user the package's docs are unreachable. Do not guess its API from training data.

阅读
package.json
。记录每个已安装的
```
@gravity-ui/*
```
包及其版本。已安装版本是唯一的依据，而非你的记忆。从
```
node_modules
```
中解析版本范围（查看
```
<pkg>/package.json
```
的
```
version
```
字段），而非根目录
```
package.json
```
中的版本范围字符串。
按以下顺序获取你要使用的包的文档，找到第一个能解答你问题的资源即停止：
(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
```
。这是精确匹配已安装版本的文档——对于版本敏感的问题，始终优先使用本地资源。 (b) 在线资源 — 对应主版本的包级llms.txt文件：
```
https://gravity-ui.com/llms/<pkg>/<major>/llms.txt
```
（例如，对于
```
^7.2.1
```
版本，使用
```
/llms/uikit/7/llms.txt
```
）。主版本URL提供该主版本的最新次版本——它跟踪主版本，但不匹配精确补丁版本。当本地资源没有该包的文档时使用此链接。
回退规则——永远不要在资源获取失败或为空时静默继续：
- 如果本地资源中该包没有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（
```
/llms/<pkg>/<major>/llms.txt
```
  ）；若此方案也不可用，则使用本地资源，而非“latest”。
- 如果某个包的本地和在线资源都无法访问 → 停止操作并告知用户该包的文档无法访问。不要凭训练数据猜测其API。

Step 2 — implement on the chosen packages, then typecheck

步骤2 — 基于选定包实现功能，然后进行类型检查

Implement using only the
@gravity-ui/*
packages chosen in Step 0 and confirmed installed in Step 1. Import from those packages exactly — do not substitute look-alike libraries (MUI, Ant, plain
```
<input>
```
) and do not reach for a
```
@gravity-ui/*
```
package that Step 1 did not confirm installed. Follow the prop APIs from the docs you just read, not memory; if a prop you want is not documented, it does not exist — use the documented one, or ask the user.
Apply the cross-cutting rules in
```
rules/hallucination-traps.md
```
while writing: typography variants, the flex contract, theming/ladders,
```
Button view
```
,
```
Icon data
```
. Per-component traps live in the package's own
```
dist/docs
```
.
Typecheck before declaring done. Run the project's typecheck command (typically
```
tsc --noEmit
```
; for monorepos, the workspace's typecheck script). Fix every error before reporting completion — a type error almost always means a wrong/invented prop, a wrong import path, or a version mismatch, which is precisely what Steps 0–1 were meant to prevent.
- If the typecheck surfaces a prop/path that contradicts the docs you read in Step 1, trust the installed version (the typechecker), not the docs snapshot — the docs may be from a different minor. Re-ground: read the package's
```
dist/docs/INDEX.md
```
  in
```
node_modules
```
  for the exact installed types.
- If the typecheck is unavailable (no TS in the project), say so explicitly and ask the user how they want to verify; do not silently skip verification.
- Escape hatch. If the user explicitly waived verification ("just sketch it", "quick prototype", "no need to check"), you may skip the typecheck — but state this plainly in your reply: "typecheck skipped by user request — code is not verified". Do not skip silently.

仅使用步骤0中选定且步骤1确认已安装的
@gravity-ui/*
包实现功能。严格从这些包导入——不要替换为相似的库（MUI、Ant、原生
```
<input>
```
），也不要使用步骤1未确认已安装的
```
@gravity-ui/*
```
包。遵循你刚查阅的文档中的属性API，而非记忆；如果你需要的属性未被文档记录，则它不存在——使用已记录的属性，或询问用户。
编写代码时应用
rules/hallucination-traps.md
中的通用规则：排版变体、flex约定、主题/层级、
```
Button view
```
、
```
Icon data
```
。各组件的注意事项在对应包的
```
dist/docs
```
中。
完成前进行类型检查。运行项目的类型检查命令（通常是
```
tsc --noEmit
```
；对于单仓项目，使用工作区的类型检查脚本）。在报告完成前修复所有错误——类型错误几乎总是意味着属性/导入路径错误，或版本不匹配，而这正是步骤0-1要避免的问题。
- 如果类型检查发现的属性/路径与步骤1中查阅的文档矛盾，请信任已安装版本（类型检查器），而非文档快照——文档可能来自不同的次版本。重新确认：查看
```
node_modules
```
  中该包的
```
dist/docs/INDEX.md
```
  获取精确匹配已安装版本的类型定义。
- 如果项目中没有TypeScript，无法进行类型检查，请明确告知用户并询问他们希望如何验证；不要静默跳过验证。
- 例外情况。如果用户明确要求跳过验证（“只需大致写一下”、“快速原型”、“无需检查”），你可以跳过类型检查——但需在回复中明确说明：“根据用户请求跳过类型检查——代码未经过验证”。不要静默跳过。

Hard rules

硬性规则

@gravity-ui/uikit
MUST be installed in every Gravity UI project. It is the base component + design-token library every other
```
@gravity-ui/*
```
package builds on; without it components render unstyled. If
```
package.json
```
lacks it, stop and have the user install and configure it first (setup:
```
https://gravity-ui.com/llms/uikit/llms.txt
```
).
Read
package.json
before importing any
@gravity-ui/*
package. Never assume a package is installed; never assume its major version.
Do not invent props or components. Before using a component API you are not 100% sure of, check
```
rules/hallucination-traps.md
```
(ecosystem patterns) and the component's README in
```
dist/docs
```
. If still unsure, ask the user rather than guessing.
Never guess icon names — they are hallucinated more often than not. To match an icon from a screenshot/photo/mock, run
```
scripts/icon-image-search.sh
```
(reverse image search). With only a description, look the name up on
```
gravity-ui.com/icons
```
or ask the user — do not invent one. Then pass it as an object (
```
<Icon data={CheckIcon} />
```
), never a string key. See
```
references/icons.md
```
.
Theming uses semantic
--g-*
tokens. Never hardcode colors (
```
#fff
```
,
```
blue-500
```
); never hand-write
```
dark:
```
overrides. Full token tables live in
```
references/theming.md
```
; the cross-cutting traps (partial brand overrides, scoped vs nested
```
ThemeProvider
```
, controls on a brand background) live in
```
rules/hallucination-traps.md
```
.
Required setup is package-specific (style imports,
```
ThemeProvider
```
, peer-deps). It lives in each package's root README under "Required setup" — read it once per package, do not rely on memory.

每个Gravity UI项目必须安装
@gravity-ui/uikit
。它是其他所有
```
@gravity-ui/*
```
包的基础组件+设计令牌库；没有它，组件将无样式渲染。如果
```
package.json
```
中缺少该包，请停止操作并让用户先安装并配置它（配置指南：
```
https://gravity-ui.com/llms/uikit/llms.txt
```
）。
在导入任何
@gravity-ui/*
包前，请先阅读
package.json
。永远不要假设某个包已安装；永远不要假设其主版本。
不要虚构属性或组件。在使用你并非100%确定的组件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
```
、对等依赖）。它位于每个包根目录README的“Required setup”部分——每个包都要阅读一次，不要依赖记忆。

What NOT to do

禁止操作

These are the five most common ways agents break Gravity UI code. They are already implied by the rules above; this section exists as an explicit stop-sign. If you are about to do any of these, stop and re-ground.

Do not substitute non-Gravity libraries. No MUI, Ant Design, plain
```
<input>
```
/
```
<button>
```
, or look-alike component libs. Use the
```
@gravity-ui/*
```
package the task needs.
Do not invent component APIs or props. If a prop is not in the docs you read in Step 1, it does not exist — do not write
```
variant=
```
,
```
color=
```
,
```
name=
```
(on
```
Icon
```
), or a
```
header-3
```
variant. Use the documented prop or ask the user. See
```
rules/hallucination-traps.md
```
.
Do not use the
/llms/<pkg>/llms.txt
"latest" alias as a fallback. It serves the newest major, which may differ from the installed one and have a different API. The versioned online fallback is the major-line URL (
```
/llms/<pkg>/<major>/llms.txt
```
); below that, go LOCAL.
Do not partial-brand. Setting only
```
--g-color-base-brand
```
leaves selection, focus, links and contrast on the default accent — a mismatched UI. Override the full brand token set, on each theme you support.
Do not override internal markup with
[class*='…']
/ ID selectors. That's written against one DOM structure and breaks silently when the component changes. Climb the customization ladder (global token → component CSS API → narrow flagged hack) before ever touching structure.

以下是Agent破坏Gravity UI代码的五种最常见方式。这些内容已隐含在上述规则中，本部分作为明确的警示。如果你即将执行以下任何操作，请停止并重新确认。

不要替换为非Gravity库。禁止使用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 → 有限的特殊技巧）。

Deeper material — read on demand

进阶资料——按需阅读

These files live alongside this SKILL.md and load only when relevant:

```
references/package-routing.md
```
— offline snapshot of the ecosystem catalog (
```
gravity-ui.com/llms.txt
```
), refreshed each skill release. Used as the offline fallback in Step 0.
```
references/theming.md
```
— verbatim copy of uikit's
```
docs/theming.md
```
:
```
--g-*
```
token layers,
```
ThemeProvider
```
, branding, custom themes, scoped themes,
```
uikit-themer
```
. The bundled copy may lag — read
```
node_modules/@gravity-ui/uikit/build/docs/guides/theming.md
```
for the version-matched file.

references/layout.md

— verbatim copy of uikit's

docs/layout.md

: spacing scale (

--g-spacing-*

Flex

Box

Row

Col

Container

grid, breakpoints,

useLayoutContext

```
references/icons.md
```
— finding an icon by image (
```
scripts/icon-image-search.sh
```
) or on gravity-ui.com/icons; the object-vs-string rendering rule.
```
rules/hallucination-traps.md
```
— Incorrect/Correct pairs for the most commonly invented APIs: typography variants (
```
header-3..6
```
don't exist, no
```
Heading
```
), the flex contract (
```
min-width:0
```
, who shrinks), theming traps (partial brand overrides, scoped vs nested
```
ThemeProvider
```
, customization ladder),
```
Button view
```
not
```
variant
```
,
```
Icon data
```
not
```
name
```
. Per-component traps live in each package's
```
dist/docs
```
, not here.

以下文件与本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
```
中，而非本文件。