token-usage

Skill：IDS Token 使用

目的

指导 AI Agent 在 React 组件和 CSS 中正确使用 IDS 设计 Token。本 Skill 涵盖导入模式、常见错误，以及各类 Token 的实用用法规则。

适用场景

• 生成需要使用颜色、间距、排版或圆角值的 React 组件
• 为基于 IDS 的应用编写自定义 CSS 或内联样式
• 检查或修复现有代码中的设计 Token 用法
• 在组件属性、CSS 变量和 cssVars JS 对象之间进行选择
• 解答有关可用 Token 值和命名约定的问题

工作流

1. 检查组件属性是否可以处理 — 大多数 IDS 组件都支持 IressCSSProps（例如 p、m、gap、bg、color、textStyle）。优先使用属性，再考虑直接使用 Token。
2. 确定 Token 类别 — 它属于颜色、间距、排版还是圆角？
3. 选择正确的导入方式 — 内联样式使用 cssVars，样式表使用 CSS 变量。请参阅下方的导入模式。
4. 查找对应值 — 如需查找特定值，请参阅 references/token-reference.md 中的完整可用 Token 列表。

快速入门

安装

重要提示： IDS v6 目前处于测试版。请使用 @beta 标签安装：

npm install @iress-oss/ids-tokens@beta
# 如果还要使用 IDS React 组件：
npm install @iress-oss/ids-components@beta

前提条件（仅适用于 React）

如果你使用 IDS React 组件，请用 IressProvider 包裹应用，并导入 CSS 变量样式表：

注意： IressProvider 已包含 IressModalProvider、IressSlideoutProvider、IressToasterProvider、IressPopoverProvider 和 IressIconProvider，无需单独添加。如果使用 IressShadow，则无需额外的 Provider，因为它内部已包含 IressProvider。

import '@iress-oss/ids-tokens/build/css-vars.css';
import { IressProvider } from '@iress-oss/ids-components';

function App() {
  return <IressProvider>{/* your UI */}</IressProvider>;
}

非 React 用法： Token 包无需 React 即可使用。在任何 JavaScript 或 CSS 环境中，都可以导入 CSS 样式表，或直接使用 cssVars / designTokens。

CSP 注意事项： IressProvider 在运行时会从 fonts.googleapis.com 和 fonts.gstatic.com 加载字体。如果应用启用了内容安全策略，请在 style-src 和 font-src 中将这些来源列入允许列表。如果使用 IressShadow，且 CSP 禁止内联样式，请添加 <meta name="csp-nonce" content="..."> 以支持 nonce。详情请参阅 node_modules/@iress-oss/ids-components/.ai/guides/get-started-content-security-policy.md 中的 CSP 指南（需要安装 @iress-oss/ids-components）。

CSS 变量样式表（推荐用于 CSS）

CSS 样式表是使用 Token 最简单的方式。只需导入一次，即可在 CSS 中任意位置使用 var() 引用。

重要提示： 使用 @iress-oss/ids-tokens/build/css-vars.css 中定义的变量名（例如 --colour-neutral-10）。请勿直接引用 --iress-* 变量——这些变量由主题文件设置，不属于公开的 Token API。

/* Import the stylesheet once in your app root */
@import '@iress-oss/ids-tokens/build/css-vars.css';

/* Use variables anywhere in your CSS */
.card {
  background: var(--colour-neutral-10);
  padding: var(--spacing-4);
  border-radius: var(--radius-3);
  color: var(--colour-neutral-90);
}

cssVars 对象（推荐用于 CSS-in-JS）

对于内联样式和 CSS-in-JS，请使用 cssVars 导出项。它与 Token 结构一致，但会返回带内嵌回退值的 var() 字符串，并提供完整的类型安全保障。

import { cssVars } from '@iress-oss/ids-tokens';

// Each leaf is a var() string with a fallback value
cssVars.colour.primary.fill; // 'var(--iress-colour-primary-fill, #003271)'
cssVars.spacing[4]; // 'var(--iress-spacing-4, calc(4 * var(--iress-spacing-100, .25rem)))'
cssVars.radius[1]; // 'var(--iress-radius-1, 0.25rem)'
cssVars.typography.heading[1]; // 'var(--iress-typography-heading-1, 500 calc(...) / 1.33 Ubuntu, ...)'

// Use in inline styles
<div
  style={{
    background: cssVars.colour.neutral[20],
    padding: cssVars.spacing[4],
  }}
>
  Themed content
</div>;

JavaScript Schema（用于元数据 / 工具）

仅当需要检查 Token 元数据（描述、类型、扩展项）或以编程方式遍历 Token 时，才使用原始 designTokens Schema。对于样式设置，请改用 cssVars 或 CSS 变量。

import { designTokens } from '@iress-oss/ids-tokens';

// Each token is an IressDesignToken object with $value, $type, $description, etc.
designTokens.colour.primary.fill.$value; // '#003271'
designTokens.spacing[4].$value; // 'calc(4 * {spacing.100 || .25rem})'
designTokens.radius[1].$value; // '0.25rem'
designTokens.typography.heading[1].$value; // { fontFamily, fontSize, fontWeight, lineHeight }

导入模式

用于 CSS 样式

/* In your app entry point */
@import '@iress-oss/ids-tokens/build/css-vars.css';

导入后，所有公开的 Token 变量（例如 --colour-*、--spacing-*、--radius-*、--typography-*）均可全局使用。

用于 CSS-in-JS / 内联样式

import { cssVars } from '@iress-oss/ids-tokens';

// Type-safe var() references with fallbacks — use anywhere you need a style value
cssVars.colour.neutral[10]; // 'var(--iress-colour-neutral-10, #FFFFFF)'
cssVars.spacing[4]; // 'var(--iress-spacing-4, ...)'

用于 Token 元数据 / 工具

import { designTokens } from '@iress-oss/ids-tokens';

// Access raw token objects for metadata inspection
const { colour, spacing, radius, typography } = designTokens;

内部辅助工具（仅供主题编辑器使用）

注意： 这些辅助工具用于主题编辑器（例如 Styler）等内部工具。使用者应改用 cssVars 或 CSS 变量。

// Convert token schema to a nested object of CSS variable references
import { mapTokensToCssVariables } from '@iress-oss/ids-tokens/mapTokensToCssVariables';

// Resolve `{colour.neutral.10}` token references to CSS vars
import { convertReferencesToVariables } from '@iress-oss/ids-tokens/convertReferencesToVariables';

按类别划分的使用规则

颜色

颜色始终使用颜色令牌——切勿硬编码十六进制、rgb 或 hsl 值。

用例	令牌	示例
页面背景	colour.neutral.10	bg="colour.neutral.10"
浅色背景	colour.neutral.20	bg="colour.neutral.20"
默认文本	colour.neutral.80	color="colour.neutral.80"
次要文本	colour.neutral.70	color="colour.neutral.70"
边框	colour.neutral.30	使用组件属性
主要操作	colour.primary.fill	使用 Button mode="primary"
成功指示	colour.system.success.fill	使用 Alert/Tag 状态
危险/错误	colour.system.danger.fill	使用 Alert/Tag 状态

// ✅ Correct
<IressText color="colour.neutral.80">Subtitle</IressText>
<IressStack bg="colour.neutral.20" p="spacing.4">...</IressStack>

// ❌ Wrong — hardcoded colours
<div style={{ color: '#384666' }}>Subtitle</div>
<div style={{ background: '#F5F6F8' }}>...</div>

间距

所有间距均使用间距令牌——包括间隙、内边距和外边距。

基本单位：4px（0.25rem）。令牌值 = 基本单位的倍数。

令牌	别名	值	用途
0	none	0	无间距
1	xs	4px	紧凑的行内间距
2	sm	8px	默认元素间距
3	—	12px	紧凑的区块间距
4	md	16px	标准区块间距
5	—	20px	中等区块间距
6	lg	24px	区块分隔
7	—	28px	大区块间距
8	—	32px	大组间距
10	xl	40px	页面级间距

// ✅ Correct — use full token path
<IressStack gap="spacing.4" p="spacing.6">...</IressStack>
<IressInline gap="spacing.2">...</IressInline>

// ✅ Also correct — use token aliases
<IressStack gap="md" p="lg">...</IressStack>
<IressInline gap="sm">...</IressInline>

// ❌ Wrong — arbitrary values
<div style={{ gap: '15px', padding: '25px' }}>...</div>

注意： 没有 spacing[9] 令牌。有效的间距值：spacing.0 至 spacing.10（不包括 9），或别名：none、xs、sm、md、lg、xl。

正向与负向间距： 内边距属性（p、px、py、pb、pl、pr、pt）仅接受正向间距令牌。外边距属性（m、mx、my、mb、ml、mr、mt）也接受负值（例如 -spacing.2、-sm），用于重叠元素。

边框圆角

所有圆角均使用圆角令牌。

令牌	值	语义用途
radius.0	0	方形/尖角
radius.1	4px	按钮、表单输入框、标签
radius.2	8px	通用场景
radius.3	12px	卡片、面板、布局容器
radius.4	16px	胶囊、徽章

// ✅ Correct — IDS components already have correct radius
<IressButton>Submit</IressButton>  // radius.1 built in
<IressCard>...</IressCard>         // radius.3 built in

// Manual radius only when building custom layout
<IressStack borderRadius="radius.3">Custom panel</IressStack>

字体排版

所有文本渲染都使用 IressText，而不是原始标题或段落。

元素	textStyle 值	字体	大小	字重
h1	typography.heading.1	Ubuntu	1.5rem (24px)	500
h2	typography.heading.2	Ubuntu	1.25rem (20px)	500
h3	typography.heading.3	Ubuntu	1.125rem (18px)	500
h4	typography.heading.4	Ubuntu	1rem (16px)	500
h5	typography.heading.5	Ubuntu	1rem (16px)	400
正文（默认）	typography.body.md	Inter	0.875rem (14px)	400
正文粗体	typography.body.md.strong	Inter	0.875rem (14px)	600
小号文本	typography.body.sm	Inter	0.75rem (12px)	400
小号粗体	typography.body.sm.strong	Inter	0.75rem (12px)	600
代码	typography.code	Space	1rem (16px)	400

所有 textStyle 值： typography.heading.1 – .5、typography.body.sm（+ .regular、.medium、.strong、.em）、typography.body.md（+ .regular、.medium、.strong、.em）、typography.code、inherit。

// ✅ Correct
<IressText element="h1">Page Title</IressText>
<IressText>Body paragraph text</IressText>
<IressText textStyle="typography.body.sm.strong">Small bold label</IressText>

// ❌ Wrong — raw HTML elements lose IDS typography
<h1>Page Title</h1>
<p style={{ fontFamily: 'Inter', fontSize: '14px' }}>Text</p>

自定义样式中的 CSS 变量

对于 IDS 组件属性未涵盖的自定义样式，推荐使用此方法。

使用 Panda CSS？ 如果你的项目使用 Panda CSS，请使用 @iress-oss/ids-theme-preset 包，而不是手动引用 CSS 变量。该包提供了一个 Panda CSS 预设，其中包含完整的 IDS 令牌系统，可通过 Panda 的 css() 函数、实用工具和配方，以类型安全的方式使用令牌。有关设置方法，请参阅 references/theme-preset.md。

在 CSS / SCSS 中

.custom-card {
  /* Colour tokens */
  background: var(--colour-neutral-10);
  border: 1px solid var(--colour-neutral-30);
  color: var(--colour-neutral-90);

  /* Spacing tokens */
  padding: var(--spacing-4);
  gap: var(--spacing-2);

  /* Radius tokens */
  border-radius: var(--radius-3);

  /* Typography tokens (composite shorthand) */
  font: var(--typography-body-md-regular);
}

在 CSS-in-JS / 内联样式中

import { cssVars } from '@iress-oss/ids-tokens';

// cssVars gives you the same var() references, but type-safe in JS
<div
  style={{
    background: cssVars.colour.neutral[10],
    border: `1px solid ${cssVars.colour.neutral[30]}`,
    color: cssVars.colour.neutral[80],
    padding: cssVars.spacing[4],
    gap: cssVars.spacing[2],
    borderRadius: cssVars.radius[3],
  }}
>
  Custom card
</div>;

CSS 变量命名约定

tokens/build/css-vars.css 中的变量遵循以下模式：

--{category}-{path}

示例：

• --colour-primary-fill
• --spacing-4
• --radius-1
• --typography-heading-1（简写）
• --typography-heading-_1-fontSize（分解形式，在令牌名称前加下划线前缀）

注意： 主题文件定义了 --iress-{category}-{path} 覆盖变量，这些变量会作为回退默认值，被公共 css-vars.css 变量引用。在自己的 CSS 中使用 --{category}-{path} 公共变量，切勿直接使用 --iress-* 主题覆盖变量。

常见错误

1. 使用硬编码值而非令牌

// ❌ Wrong
<div style={{ background: '#F5F6F8', padding: '16px', borderRadius: '12px' }}>

// ✅ Correct
<IressStack bg="colour.neutral.20" p="spacing.4" borderRadius="radius.3">

2. 使用原始 HTML 元素

// ❌ Wrong — loses IDS typography and theming
<h2>Section Title</h2>
<p>Body text</p>

// ✅ Correct — uses IDS tokens automatically
<IressText element="h2">Section Title</IressText>
<IressText>Body text</IressText>

3. 重新实现组件样式

// ❌ Wrong — manually styling a button
<button style={{
  background: '#003271',
  color: '#FFFFFF',
  borderRadius: '4px',
  padding: '8px 16px'
}}>Submit</button>

// ✅ Correct — IDS handles all styling via mode
<IressButton mode="primary">Submit</IressButton>

4. 使用错误的颜色语义

// ❌ Wrong — using primary fill for background
<IressStack bg="colour.primary.fill">Content</IressStack>

// ✅ Correct — use surface variants for backgrounds
<IressStack bg="colour.primary.surface">Content</IressStack>

5. 使用不存在的令牌值

// ❌ Wrong — spacing 9 doesn't exist
<IressStack gap="spacing.9">...</IressStack>

// ✅ Correct — use 8 or 10
<IressStack gap="spacing.8">...</IressStack>

响应式模式

布局组件的间距属性支持响应式对象：

// Responsive gap: 2 on mobile, 4 on tablet, 6 on desktop
<IressStack gap={{ base: 'spacing.2', md: 'spacing.4', lg: 'spacing.6' }}>
  ...
</IressStack>

// Or use aliases
<IressStack gap={{ base: 'sm', md: 'md', lg: 'lg' }}>
  ...
</IressStack>

// Hide on small screens
<IressStack hideBelow="md">Desktop only</IressStack>

决策表：组件 Props 与 CSS 变量及 cssVars

情况	使用
IDS 布局组件的间距	Props：gap、p、m
IDS 组件的颜色	Props：bg、color
自定义 CSS / SCSS	CSS 变量（var(--colour-*)、var(--spacing-*) 等）
内联样式 / CSS-in-JS	cssVars 对象（cssVars.colour.neutral[10]）
使用 Panda CSS 的自定义 CSS	@iress-oss/ids-theme-preset 预设
主题化 / 覆盖	自定义属性上的 CSS 变量
内部主题编辑器	mapTokensToCssVariables() 助手

一般规则： 优先使用可用的组件 Props。对于自定义样式，可在样式表中使用 CSS 变量，或在 JavaScript 中使用 cssVars。仅在主题编辑器等内部工具中使用 mapTokensToCssVariables / convertReferencesToVariables。

应避免的常见错误

如需查看常见反模式的完整列表（禁用按钮、冗余的 textStyle、旧版 slot 属性、原始 HTML、硬编码值），请阅读 node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md 中的《常见错误》指南（需安装 @iress-oss/ids-components）。

完整令牌参考

所有可用的颜色、间距、圆角和排版令牌，以及对应的 CSS 变量名称和默认值，请参阅 references/token-reference.md。

主题化

有关主题如何通过 CSS 变量覆盖令牌、作用域主题化以及面向 AI Agent 的指南，请参阅 references/theming.md。

交叉引用

有关样式 Props 指南、软件包参考以及组件级文档链接，请参阅 references/cross-references.md。这些内容需安装 @iress-oss/ids-components。