ui-doctor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: UI Doctor

技能：UI Doctor

Audit and review application UI for IDS compliance, accessibility, usability, and cognitive load. This skill helps AI agents perform comprehensive UI reviews covering component usage, accessibility (WCAG), usability heuristics (Nielsen's 10), cognitive load, and progressive disclosure — then produce actionable reports with prioritised recommendations.

针对IDS合规性、可访问性、易用性和认知负载，对应用程序UI进行审计与评审。本技能可帮助AI Agent执行全面的UI评审，涵盖组件使用、可访问性（WCAG）、易用性启发法（尼尔森十大原则）、认知负载和渐进式披露——并生成带有优先级建议的可执行报告。

When to Use

使用场景

Activate this skill when the user says things like:

"Review this page / component / file for accessibility"
"Check the usability of this UI"
"Audit this for IDS compliance"
"This feels like too much cognitive load"
"Are we following IDS guidelines?"
"Check for a11y issues"
"Review this UI"
"Is this form accessible?"
"Can you do a UX review?"

Or more generally:

Reviewing application UI code for IDS compliance
Validating accessibility (WCAG 2.1 AA)
Assessing usability and cognitive load
Evaluating design token usage and consistency
Generating a UI health report with a compliance score
Providing recommendations to improve UX, accessibility, and IDS adoption

当用户说出以下内容时激活本技能：

"评审这个页面/组件/文件的可访问性"
"检查这个UI的易用性"
"对此进行IDS合规性审计"
"这个的认知负载感觉太重了"
"我们是否遵循IDS指南？"
"检查a11y问题"
"评审这个UI"
"这个表单是否可访问？"
"你能做一次UX评审吗？"

或更宽泛的场景：

评审应用程序UI代码的IDS合规性
验证可访问性（WCAG 2.1 AA标准）
评估易用性和认知负载
评估设计令牌的使用情况与一致性
生成包含合规分数的UI健康报告
提供改进UX、可访问性和IDS采用率的建议

Audit Modes

审计模式

Default: Quick UX Review. Use this unless the user specifically asks for accessibility or full compliance. Escalate to a more thorough mode if the quick review reveals significant issues.

默认：快速UX评审。除非用户明确要求可访问性或全面合规性审计，否则使用此模式。如果快速评审发现重大问题，则升级为更深入的模式。

Quick UX Review (default)

快速UX评审（默认）

Use when the user asks for a general UI review, usability check, or "does this look right?"

Cognitive load & information architecture — Is the UI overwhelming? Are there too many items, options, or actions visible at once?
Usability heuristics — Evaluate against Nielsen's 10 (see audit checklist § Usability Heuristics)
Button hierarchy & layout consistency — One primary per section, consistent spacing
Quick component scan — Are obvious raw HTML elements used where IDS components exist?

当用户要求进行通用UI评审、易用性检查或询问“这个看起来正常吗？”时使用。

认知负载与信息架构——UI是否过于繁杂？是否同时显示了过多的条目、选项或操作？
易用性启发法——对照尼尔森十大原则进行评估（详见审计清单 § 易用性启发法）
按钮层级与布局一致性——每个区域仅有一个主按钮，间距保持一致
组件快速扫描——是否在有IDS组件可用的情况下使用了原始HTML元素？

Accessibility Review

可访问性评审

Use when the user asks about a11y, WCAG, keyboard navigation, or screen reader support.

Form accessibility — Labels, required indicators, validation messages, id/htmlFor pairing
Keyboard & focus — Skip links, focus trapping in modals/slideouts, visible focus indicators
Screen reader — ARIA landmarks, dynamic content announcements, accessible names on interactive elements
Colour & contrast — WCAG AA contrast ratios, no reliance on colour alone
Cognitive load — Progressive disclosure, information density (see audit checklist § Cognitive Load)

当用户询问a11y、WCAG、键盘导航或屏幕阅读器支持相关问题时使用。

表单可访问性——标签、必填标识、验证消息、id/htmlFor配对
键盘与焦点——跳转链接、模态框/侧边栏的焦点捕获、可见的焦点指示器
屏幕阅读器——ARIA地标、动态内容播报、交互元素的可访问名称
颜色与对比度——符合WCAG AA对比度标准，不单独依赖颜色传递信息
认知负载——渐进式披露、信息密度（详见审计清单 § 认知负载）

Full Compliance Audit

全面合规审计

Use when the user asks for a complete IDS audit or compliance report.

Run all checklist sections from the audit checklist
Validate component usage against replacement tables
Check design token usage and Provider/CSS setup
Evaluate patterns (forms, loading, navigation)
Assess usability and cognitive load
Generate a full report using the report template

当用户要求进行完整的IDS审计或合规报告时使用。

运行审计清单中的所有检查项
对照替换对照表验证组件使用情况
检查设计令牌使用情况以及Provider/CSS配置
评估模式（表单、加载、导航）
评估易用性和认知负载
使用报告模板生成完整报告

Scoped Audits

范围化审计

If the user asks about a specific file, component, or page, focus the audit on that scope only. Apply the same checklist items but only to the files in question. Do not scan the entire application unless asked.

Example: "Check the accessibility of

UserProfileForm.tsx

" → run the Accessibility Review mode on that single file.

如果用户要求针对特定文件、组件或页面进行审计，请仅聚焦该范围。应用相同的清单检查项，但仅针对指定文件。除非用户要求，否则不要扫描整个应用程序。

示例：“检查

UserProfileForm.tsx

的可访问性” → 针对该单个文件运行可访问性评审模式。

Audit Scope

审计范围

Before starting, determine which files to scan.

开始审计前，确定要扫描的文件。

Files to Scan

需扫描的文件

All
```
.tsx
```
,
```
.jsx
```
,
```
.ts
```
,
```
.js
```
files in
```
src/
```
(or the application source directory)
CSS/SCSS/styled-component files for hardcoded design values
Application entry point(s) for Provider and CSS import checks

Important: Always trace the component tree from the actual mount point (e.g.

main.tsx

index.tsx

) before evaluating Provider & Setup. The entry point may not be a route file — it could be a custom element wrapper, a shadow DOM host, or a separate bootstrap file that renders the router. Do not penalise missing Provider/CSS if a parent entry point already handles it.

```
src/
```
（或应用程序源码目录）下的所有
```
.tsx
```
、
```
.jsx
```
、
```
.ts
```
、
```
.js
```
文件
包含硬编码设计值的CSS/SCSS/styled-component文件
用于检查Provider和CSS导入的应用程序入口文件

重要提示： 在评估Provider与配置之前，务必从实际挂载点（如

main.tsx

、

index.tsx

）追溯组件树。入口文件可能不是路由文件——它可能是自定义元素包装器、Shadow DOM宿主或单独的引导文件，用于渲染路由器。如果父级入口文件已处理Provider/CSS，则不要因缺失而扣分。

Files to Exclude

需排除的文件

Test files (
```
*.test.tsx
```
,
```
*.spec.tsx
```
,
```
__tests__/
```
) — test mocks may legitimately use raw HTML
Storybook stories (
```
*.stories.tsx
```
) — may intentionally show raw HTML for comparison
Config files (
```
*.config.ts
```
,
```
*.config.js
```
) — not UI code
Type definitions (
```
*.d.ts
```
) — no runtime UI code
Third-party code (
```
node_modules/
```
, vendored libraries) — outside application control
Build output (
```
dist/
```
,
```
build/
```
) — generated code

测试文件（
```
*.test.tsx
```
、
```
*.spec.tsx
```
、
```
__tests__/
```
）——测试模拟可能合理使用原始HTML
Storybook故事文件（
```
*.stories.tsx
```
）——可能为了对比而故意展示原始HTML
配置文件（
```
*.config.ts
```
、
```
*.config.js
```
）——不属于UI代码
类型定义文件（
```
*.d.ts
```
）——无运行时UI代码
第三方代码（
```
node_modules/
```
、第三方库）——不在应用程序控制范围内
构建输出文件（
```
dist/
```
、
```
build/
```
）——生成的代码

Version-Aware Auditing

版本感知审计

IDS is currently on version 6. When auditing:

Check the installed version —
```
package.json
```
for
```
@iress-oss/ids-components
```
v6 — Apply all rules as-is
v5 — Flag v5-specific patterns as "migration opportunities" (key differences:
```
IressForm
```
uses
```
rules
```
prop,
```
react-hook-form
```
is a peer dependency, form state via
```
useWatch
```
/
```
ref
```
)
Pre-v5 — Flag as requiring major migration; prioritise Provider/CSS setup first
Always note the version in the audit report header

IDS当前为6版本。审计时：

检查已安装版本——查看
```
package.json
```
中的
```
@iress-oss/ids-components
```
版本
v6——直接应用所有规则
v5——将v5特定模式标记为“迁移机会”（主要差异：
```
IressForm
```
使用
```
rules
```
属性，
```
react-hook-form
```
为对等依赖，通过
```
useWatch
```
/
```
ref
```
管理表单状态）
v5之前版本——标记为需要重大迁移；优先处理Provider/CSS配置
始终在审计报告头部标注版本

Audit Process

审计流程

1. Evaluate UX, Accessibility & Cognitive Load

1. 评估UX、可访问性与认知负载

Start with what users experience — assess the UI's usability, accessibility, and information density before checking component compliance.

从用户体验入手——在检查组件合规性之前，先评估UI的易用性、可访问性和信息密度。

a. Usability Heuristics (Nielsen's 10)

a. 易用性启发法（尼尔森十大原则）

Evaluate the application against all 10 heuristics. Each has IDS-specific guidance in the audit checklist § Usability Heuristics. Key areas:

Visibility of system status — Loading states use
```
IressLoading
```
(preferred) or
```
IressSkeleton
```
(for custom content placeholder patterns); active states visible on tabs, nav, breadcrumbs
Match between system and real world — Labels use plain language; icons paired with text; status colours follow conventions
User control and freedom — Modals/slideouts dismissible; destructive actions require confirmation; forms have cancel
Consistency and standards — All components from IDS; tokens used consistently; same action = same pattern
Error prevention — Declarative
```
rules
```
validation; required fields marked; constraints communicated via
```
hint
```
Recognition rather than recall — Persistent navigation; visible breadcrumbs; labels always visible (not just placeholders)
Flexibility and efficiency — Keyboard shortcuts; skip links; searchable selects; autocomplete
Aesthetic and minimalist design — Clear visual hierarchy; consistent spacing; one primary action per section
Help users recognise/recover from errors — Human-readable validation; inline errors;
```
IressValidationSummary
```
for long forms
Help and documentation — Hint text; tooltips for non-obvious UI; placeholder supplementary to labels

对照全部10条原则评估应用程序。审计清单 § 易用性启发法中包含每条原则对应的IDS特定指南。重点领域：

系统状态可见性——加载状态使用
```
IressLoading
```
（首选）或
```
IressSkeleton
```
（用于自定义内容占位符模式）；选项卡、导航、面包屑的激活状态可见
系统与现实世界匹配——标签使用通俗语言；图标与文本配对；状态颜色遵循约定
用户控制与自由——模态框/侧边栏可关闭；破坏性操作需确认；表单有取消按钮
一致性与标准——所有组件均来自IDS；令牌使用一致；相同操作采用相同模式
错误预防——使用声明式
```
rules
```
验证；标记必填字段；通过
```
hint
```
传达约束条件
识别而非回忆——导航持久可见；面包屑可见；标签始终可见（而非仅占位符）
灵活性与效率——键盘快捷键；跳转链接；可搜索选择框；自动完成
美学与极简设计——清晰的视觉层级；一致的间距；每个区域仅有一个主操作
帮助用户识别/恢复错误——人性化的验证提示；内联错误；长表单使用
```
IressValidationSummary
```
帮助与文档——提示文本；非直观UI的工具提示；占位符作为标签的补充

b. Cognitive Load & Information Architecture

b. 认知负载与信息架构

Evaluate whether the UI presents too much information or too many choices at once.

Item count thresholds — Menus/dropdowns with >10 items should use
```
searchable
```
; long forms (>8 fields) should use
```
IressForm pattern="long"
```
; navigation with >7 top-level items should use grouping
Progressive disclosure — Use
```
IressExpander
```
or
```
IressTabSet
```
to hide secondary content until needed; multi-step flows break complex tasks into stages
Information density — Is the screen overwhelming? Use
```
IressCard
```
/
```
IressPanel
```
to group related content; use
```
IressStack
```
with adequate spacing
Batch action safety — Bulk operations (select-all + delete) need explicit confirmation via
```
IressModal
```
; show count of affected items
Focus management after state changes — After modal close, focus returns to trigger; after item deletion, focus moves to next/previous item; after form submission, focus moves to result or error
Visual hierarchy — Primary content is prominent; secondary content is de-emphasised; use
```
IressText textStyle
```
to establish hierarchy

评估UI是否同时呈现了过多信息或选项。

条目数量阈值——菜单/下拉列表条目>10个时应使用
```
searchable
```
；长表单（>8个字段）应使用
```
IressForm pattern="long"
```
；顶级导航条目>7个时应分组
渐进式披露——使用
```
IressExpander
```
或
```
IressTabSet
```
隐藏次要内容，直到用户需要；多步骤流程将复杂任务拆分为多个阶段
信息密度——屏幕是否过于繁杂？使用
```
IressCard
```
/
```
IressPanel
```
对相关内容分组；使用带有足够间距的
```
IressStack
```
批量操作安全性——批量操作（全选+删除）需通过
```
IressModal
```
明确确认；显示受影响条目的数量
状态变更后的焦点管理——模态框关闭后，焦点返回触发元素；条目删除后，焦点移动到下一个/上一个条目；表单提交后，焦点移动到结果或错误处
视觉层级——主内容突出显示；次要内容弱化；使用
```
IressText textStyle
```
建立层级

c. Accessibility (WCAG 2.1 AA)

c. 可访问性（WCAG 2.1 AA标准）

Check form accessibility, keyboard & focus, screen reader support, and colour/contrast. See audit checklist § Accessibility for the full list. Key checks:

All form inputs have labels (via
```
IressField
```
or
```
IressFormField
```
)
Skip links present (
```
IressSkipLink
```
)
Focus trapping in modals/slideouts (automatic with IDS)
ARIA landmarks (
```
<nav>
```
,
```
<main>
```
,
```
<aside>
```
)
Dynamic content announced to screen readers — choose the right tier:
- ```
IressAlert
```
  — persistent, inline status messages (no
```
aria-live
```
  ; already in the reading flow)
- ```
IressToaster
```
  — transient notifications demanding attention (
```
aria-live="assertive"
```
  ); avoid overuse
- Micro animations/interactions with colocated
```
aria-live="polite"
```
  — for subtle, user-initiated updates (save indicators, count badges, status changes) that don't warrant a toast; place the live region near the component, not globally
Colour contrast meets WCAG AA; no reliance on colour alone

检查表单可访问性、键盘与焦点、屏幕阅读器支持以及颜色/对比度。完整检查项详见审计清单 § 可访问性。重点检查：

所有表单输入均有标签（通过
```
IressField
```
或
```
IressFormField
```
）
存在跳转链接（
```
IressSkipLink
```
）
模态框/侧边栏的焦点捕获（IDS自动处理）
ARIA地标（
```
<nav>
```
、
```
<main>
```
、
```
<aside>
```
）
动态内容向屏幕阅读器播报——选择合适的层级：
- ```
IressAlert
```
  ——持久的内联状态消息（无需
```
aria-live
```
  ；已在阅读流中）
- ```
IressToaster
```
  ——短暂的通知，需引起注意（
```
aria-live="assertive"
```
  ）；避免过度使用
- 带有
```
aria-live="polite"
```
  的微动画/交互——用于细微的、用户触发的更新（保存指示器、计数徽章、状态变更），无需使用提示框；将实时区域放置在组件附近，而非全局
颜色对比度符合WCAG AA标准；不单独依赖颜色传递信息

d. Button Hierarchy

d. 按钮层级

One
```
mode="primary"
```
button per logical section
Destructive actions use
```
status="danger"
```
, not custom red styling
Icon-only buttons include accessible text

每个逻辑区域仅有一个
```
mode="primary"
```
按钮
破坏性操作使用
```
status="danger"
```
，而非自定义红色样式
仅含图标的按钮包含可访问文本

e. Layout Consistency

e. 布局一致性

Vertical stacks →
```
IressStack
```
; horizontal rows →
```
IressInline
```
; grids →
```
IressRow
```
/
```
IressCol
```
Spacing uses token values (0–10) on
```
gap
```
prop
```
IressCSSProps
```
(
```
m
```
,
```
mx
```
,
```
p
```
,
```
px
```
) instead of inline styles
Responsive:
```
hideFrom
```
/
```
hideBelow
```
props or
```
useBreakpoint
```
hook; grid layouts use responsive
```
span
```
(e.g.
```
span={{ xs: 12, md: 6 }}
```
); mobile view focuses on primary task with secondary content in
```
IressSlideout
```
or collapsible sections

垂直堆叠 →
```
IressStack
```
；水平行 →
```
IressInline
```
；网格 →
```
IressRow
```
/
```
IressCol
```
间距使用
```
gap
```
属性上的令牌值（0–10）
使用
```
IressCSSProps
```
（
```
m
```
、
```
mx
```
、
```
p
```
、
```
px
```
）而非内联样式
响应式：使用
```
hideFrom
```
/
```
hideBelow
```
属性或
```
useBreakpoint
```
钩子；网格布局使用响应式
```
span
```
（如
```
span={{ xs: 12, md: 6 }}
```
）；移动端视图聚焦于主任务，次要内容放在
```
IressSlideout
```
或可折叠区域

2. Validate IDS Component Usage

2. 验证IDS组件使用情况

Scan for raw HTML, third-party components, and custom implementations that have IDS equivalents. Use the replacement tables for the full mapping.

Quick checks:

No raw
```
<button>
```
,
```
<input>
```
,
```
<select>
```
,
```
<form>
```
,
```
<table>
```
— use IDS equivalents
No third-party UI library imports (MUI, Ant, Chakra, Bootstrap, Radix, Headless UI) where IDS equivalents exist
No custom modals, drawers, tabs, tooltips, alerts — use IDS patterns
No custom loading spinners — use
```
IressLoading
```
(preferred) or
```
IressSkeleton
```
for custom content placeholder patterns
Layout divs with flex/grid styles →
```
IressStack
```
,
```
IressInline
```
,
```
IressRow
```
/
```
IressCol
```

Acceptable exceptions (do NOT flag): raw elements in test files, third-party widgets the app cannot control,

<input type="hidden">

, custom components wrapping IDS internally. See replacement tables § Acceptable Exceptions.

扫描存在IDS等效组件的原始HTML、第三方组件和自定义实现。完整映射详见替换对照表。

快速检查：

不使用原始
```
<button>
```
、
```
<input>
```
、
```
<select>
```
、
```
<form>
```
、
```
<table>
```
——使用IDS等效组件
不导入第三方UI库（MUI、Ant、Chakra、Bootstrap、Radix、Headless UI），如有IDS等效组件可用
不使用自定义模态框、抽屉、选项卡、工具提示、警告——使用IDS模式
不使用自定义加载 spinner——使用
```
IressLoading
```
（首选）或
```
IressSkeleton
```
用于自定义内容占位符模式
带有flex/grid样式的布局div → 使用
```
IressStack
```
、
```
IressInline
```
、
```
IressRow
```
/
```
IressCol
```

可接受的例外情况（无需标记）：测试文件中的原始元素、应用程序无法控制的第三方小部件、

<input type="hidden">

、内部封装IDS的自定义组件。详见替换对照表 § 可接受的例外情况。

3. Validate IDS Principles & Setup

3. 验证IDS原则与配置

a. Provider & CSS Setup

a. Provider与CSS配置

IressProvider must wrap the application root — Required for fonts, CSS variables, and theming.
```
IressProvider
```
already includes
```
IressModalProvider
```
,
```
IressSlideoutProvider
```
,
```
IressToasterProvider
```
,
```
IressPopoverProvider
```
, and
```
IressIconProvider
```
— these should not be added separately. Similarly,
```
IressShadow
```
includes
```
IressProvider
```
internally, so no additional providers are needed when using
```
IressShadow
```
.
The IDS component CSS must be imported —
```
@iress-oss/ids-components/dist/style.css
```
contains all component styles
Users only need to install
```
@iress-oss/ids-components@beta
```
— the tokens are bundled within the component library and do not need to be installed separately. IDS v6 is currently in beta, so the
```
@beta
```
tag is required (e.g.
```
npm install @iress-oss/ids-components@beta
```
)
CSP must allowlist IDS external origins — If the app enforces a Content Security Policy,
```
fonts.googleapis.com
```
and
```
fonts.gstatic.com
```
must be in
```
style-src
```
/
```
font-src
```
. Add
```
cdn.iress.com
```
if using legacy Font Awesome icons or
```
IressTheme
```
. If using
```
IressShadow
```
and inline styles are blocked, add
```
<meta name="csp-nonce" content="...">
```
in
```
<head>
```
. See the CSP Guide at
```
node_modules/@iress-oss/ids-components/.ai/guides/get-started-content-security-policy.md
```
for details (requires
```
@iress-oss/ids-components
```
to be installed).
If using design tokens directly in application code (for custom styling), users should additionally install
```
@iress-oss/ids-tokens@beta
```
and import
```
@iress-oss/ids-tokens/build/css-vars.css
```

typescript

// ✅ Minimum required setup (option A — standard)
import '@iress-oss/ids-components/dist/style.css';
import { IressProvider } from '@iress-oss/ids-components';

function App() {
  return <IressProvider>{/* app content */}</IressProvider>;
}

typescript

// ✅ Minimum required setup (option B — IressShadow)
// IressShadow is a superset of IressProvider — it wraps children in a shadow DOM,
// injects style.css automatically, and provides the IressProvider context.
// No separate IressProvider or CSS import is needed when using IressShadow.
import { IressShadow } from '@iress-oss/ids-components';

function App() {
  return <IressShadow>{/* app content */}</IressShadow>;
}

typescript

// ✅ With direct token usage in application code (optional)
import '@iress-oss/ids-components/dist/style.css';
import '@iress-oss/ids-tokens/build/css-vars.css';
import { IressProvider } from '@iress-oss/ids-components';
import { cssVars } from '@iress-oss/ids-tokens';

function App() {
  return (
    <IressProvider>
      <div style={{ padding: cssVars.spacing[4] }}>{/* app content */}</div>
    </IressProvider>
  );
}

typescript

// ❌ Incorrect — missing component CSS
import { IressProvider } from '@iress-oss/ids-components';
// Components will render without styles!

// ❌ Incorrect — installing tokens separately just for provider setup
yarn add @iress-oss/ids-tokens@beta  // Not needed unless using tokens directly

// ❌ Incorrect — installing without @beta tag (will not resolve to v6)
yarn add @iress-oss/ids-components  // Must use @beta tag

IressProvider必须包裹应用程序根节点——字体、CSS变量和主题设置必备。
```
IressProvider
```
已包含
```
IressModalProvider
```
、
```
IressSlideoutProvider
```
、
```
IressToasterProvider
```
、
```
IressPopoverProvider
```
和
```
IressIconProvider
```
——无需单独添加。同样，
```
IressShadow
```
内部已包含
```
IressProvider
```
，因此使用
```
IressShadow
```
时无需额外的Provider。
必须导入IDS组件CSS——
```
@iress-oss/ids-components/dist/style.css
```
包含所有组件样式
用户只需安装
```
@iress-oss/ids-components@beta
```
——令牌已捆绑在组件库中，无需单独安装。IDS v6当前处于beta阶段，因此需要使用
```
@beta
```
标签（例如
```
npm install @iress-oss/ids-components@beta
```
）
CSP必须允许IDS外部源——如果应用程序强制执行内容安全策略，
```
fonts.googleapis.com
```
和
```
fonts.gstatic.com
```
必须加入
```
style-src
```
/
```
font-src
```
。如果使用旧版Font Awesome图标或
```
IressTheme
```
，需添加
```
cdn.iress.com
```
。如果使用
```
IressShadow
```
且阻止内联样式，需在
```
<head>
```
中添加
```
<meta name="csp-nonce" content="...">
```
。详情请见
```
node_modules/@iress-oss/ids-components/.ai/guides/get-started-content-security-policy.md
```
中的CSP指南（需安装
```
@iress-oss/ids-components
```
）。
如果在应用程序代码中直接使用设计令牌（用于自定义样式），用户应额外安装
```
@iress-oss/ids-tokens@beta
```
并导入
```
@iress-oss/ids-tokens/build/css-vars.css
```

typescript

// ✅ 最小必要配置（选项A — 标准）
import '@iress-oss/ids-components/dist/style.css';
import { IressProvider } from '@iress-oss/ids-components';

function App() {
  return <IressProvider>{/* 应用内容 */}</IressProvider>;
}

typescript

// ✅ 最小必要配置（选项B — IressShadow）
// IressShadow是IressProvider的超集——它将子组件包裹在Shadow DOM中，
// 自动注入style.css，并提供IressProvider上下文。
// 使用IressShadow时，无需单独的IressProvider或CSS导入。
import { IressShadow } from '@iress-oss/ids-components';

function App() {
  return <IressShadow>{/* 应用内容 */}</IressShadow>;
}

typescript

// ✅ 在应用代码中直接使用令牌（可选）
import '@iress-oss/ids-components/dist/style.css';
import '@iress-oss/ids-tokens/build/css-vars.css';
import { IressProvider } from '@iress-oss/ids-components';
import { cssVars } from '@iress-oss/ids-tokens';

function App() {
  return (
    <IressProvider>
      <div style={{ padding: cssVars.spacing[4] }}>{/* 应用内容 */}</div>
    </IressProvider>
  );
}

typescript

// ❌ 错误配置 — 缺少组件CSS
import { IressProvider } from '@iress-oss/ids-components';
// 组件将无样式渲染！

// ❌ 错误配置 — 仅为Provider配置单独安装令牌
yarn add @iress-oss/ids-tokens@beta  // 除非直接使用令牌，否则无需安装

// ❌ 错误配置 — 未使用@beta标签安装（无法获取v6版本）
yarn add @iress-oss/ids-components  // 必须使用@beta标签

b. Design Token Usage

b. 设计令牌使用

No hardcoded colour hex/rgb — use IDS colour tokens
No hardcoded pixel spacing — use IDS spacing tokens
No hardcoded font properties — use IDS typography tokens
No hardcoded border-radius — use IDS radius tokens

typescript

// ❌ Hardcoded values
<div style={{ color: '#003271', padding: '16px', borderRadius: '4px' }}>

// ✅ IDS tokens
import { cssVars } from '@iress-oss/ids-tokens';
<div style={{
  color: cssVars.colour.primary.fill,
  padding: cssVars.spacing[4],
  borderRadius: cssVars.radius[1]
}}>

不使用硬编码颜色十六进制/rgb值——使用IDS颜色令牌
不使用硬编码像素间距——使用IDS间距令牌
不使用硬编码字体属性——使用IDS排版令牌
不使用硬编码边框圆角——使用IDS圆角令牌

typescript

// ❌ 硬编码值
<div style={{ color: '#003271', padding: '16px', borderRadius: '4px' }}>

// ✅ IDS令牌
import { cssVars } from '@iress-oss/ids-tokens';
<div style={{
  color: cssVars.colour.primary.fill,
  padding: cssVars.spacing[4],
  borderRadius: cssVars.radius[1]
}}>

c. Form & Pattern Compliance

c. 表单与模式合规性

IDS provides patterns that ensure consistent UIs. Validate usage where appropriate.

Form Pattern (
IressForm
):

Use
```
IressForm
```
+
```
IressFormField
```
for all forms
```
rules
```
prop for validation;
```
useWatch
```
for conditional fields
```
pattern="long"
```
for forms with >8 fields
```
react-hook-form
```
as peer dependency

Loading Pattern (
IressLoading
/
IressSkeleton
):

```
page
```
,
```
component
```
,
```
start-up
```
,
```
validate
```
,
```
long
```
patterns
Handles timing thresholds automatically (no indicator <500ms, spinner at 500ms, message at 2s)
Prefer
```
IressLoading
```
for standard loading states — it handles timing, messaging, and accessibility automatically
```
IressSkeleton
```
is valid for custom content placeholder patterns where you need skeleton screens that mirror the page layout; use
```
IressLoading
```
if possible
When a page reads from a pre-populated cache (e.g. SWR, React Query, or TanStack Query cache populated by a previous page), a separate loading state may be unnecessary — check whether the data source is a cache read vs a fresh fetch before flagging

Navigation Patterns:

```
IressDropdownMenu
```
for filter/action triggers (not inside forms)
```
IressContextualMenu
```
for row-level actions with
```
ariaLabel
```
```
IressSideNav
```
for application shell navigation
```
IressBreadcrumbs
```
for hierarchy navigation

Error Boundary Pattern:

React error boundaries catch component crashes and should render IDS components as fallback UI — not custom error pages or raw HTML.

Error Scope	IDS Component	Why
Full-page crash (root error boundary)	`IressModal status="danger"` with retry/reload actions	Blocks interaction, demands attention, provides structured recovery
Section/feature crash (scoped boundary)	`IressAlert status="danger"` as inline fallback	Persistent, in-context — rest of the page still works
Transient API/network failure (not a crash)	`IressToaster`	Retryable, doesn't block the UI

Do NOT use
IressToaster
for error boundaries — toasts are transient and dismissible; if the user dismisses it, the broken component tree has no recovery UI
IressModal status="danger"
is the primary recommendation for root-level error boundaries — use
```
actions
```
prop to offer "Retry" or "Reload" buttons
IressAlert status="danger"
is preferred for scoped boundaries that wrap individual features — shows inline where the broken component was

Before flagging missing error handling: Check whether a parent component or layout route already provides an error boundary that covers the file being audited. Error boundaries are an app-wide pattern — a page component does not need its own error/empty state handling if a parent boundary already catches and renders IDS-based fallback UI (e.g.

IressModal status="danger"

with navigation-aware recovery). Only flag if no ancestor provides error handling.

Shadow DOM Pattern (
IressShadow
):

```
IressShadow
```
is a superset of
IressProvider
— it creates a shadow root, injects
```
style.css
```
into it, and provides the
```
IressProvider
```
context automatically. When an app uses
```
IressShadow
```
at its entry point, no separate
```
IressProvider
```
or CSS import is required.
Commonly used for microfrontend CSS isolation, but also valid as the sole Provider + CSS setup for any application
Creates a shadow root on a
```
<div>
```
— children are standard React components
The
```
slot
```
attribute is irrelevant; always use React props (
```
prepend
```
,
```
append
```
,
```
footer
```
, etc.)

IDS提供确保UI一致性的模式。在合适的场景下验证使用情况。

表单模式（
IressForm
）：

所有表单均使用
```
IressForm
```
+
```
IressFormField
```
使用
```
rules
```
属性进行验证；使用
```
useWatch
```
处理条件字段
字段>8个的表单使用
```
pattern="long"
```
```
react-hook-form
```
为对等依赖

加载模式（
IressLoading
/
IressSkeleton
）：

支持
```
page
```
、
```
component
```
、
```
start-up
```
、
```
validate
```
、
```
long
```
模式
自动处理时间阈值（<500ms无指示器，500ms显示spinner，2s显示消息）
标准加载状态首选
```
IressLoading
```
——它自动处理计时、消息和可访问性
```
IressSkeleton
```
适用于需要镜像页面布局的骨架屏自定义内容占位符模式；尽可能使用
```
IressLoading
```
当页面从预填充缓存读取数据（如SWR、React Query或TanStack Query缓存，由之前的页面填充）时，可能不需要单独的加载状态——标记前检查数据源是缓存读取还是全新请求

导航模式：

```
IressDropdownMenu
```
用于筛选/操作触发器（不用于表单内）
```
IressContextualMenu
```
用于行级操作，需带有
```
ariaLabel
```
```
IressSideNav
```
用于应用程序外壳导航
```
IressBreadcrumbs
```
用于层级导航

错误边界模式：

React错误边界捕获组件崩溃，应渲染IDS组件作为回退UI——而非自定义错误页面或原始HTML。

错误范围	IDS组件	原因
整页崩溃（根错误边界）	`IressModal status="danger"` 带有重试/刷新操作	阻止交互，引起注意，提供结构化恢复方式
区域/功能崩溃（范围化边界）	`IressAlert status="danger"` 作为内联回退	持久化、上下文相关——页面其余部分仍可正常工作
临时API/网络故障（非崩溃）	`IressToaster`	可重试，不阻塞UI

不要将
IressToaster
用于错误边界——提示框是短暂且可关闭的；如果用户关闭它，损坏的组件树将没有恢复UI
IressModal status="danger"
是根级错误边界的首要推荐——使用
```
actions
```
属性提供“重试”或“刷新”按钮
IressAlert status="danger"
适用于包裹单个功能的范围化边界——在损坏组件所在位置显示内联提示

标记缺失错误处理前： 检查父组件或布局路由是否已提供覆盖被审计文件的错误边界。错误边界是应用级模式——如果父边界已捕获并渲染基于IDS的回退UI（如带有导航感知恢复的

IressModal status="danger"

），则页面组件无需自身的错误/空状态处理。仅在没有祖先提供错误处理时标记。

Shadow DOM模式（
IressShadow
）：

```
IressShadow
```
是**
```
IressProvider
```
的超集**——它创建Shadow根，将
```
style.css
```
注入其中，并自动提供
```
IressProvider
```
上下文。当应用程序在入口点使用
```
IressShadow
```
时，无需单独的
```
IressProvider
```
或CSS导入。
常用于微前端CSS隔离，但也可作为任何应用程序的唯一Provider + CSS配置
在
```
<div>
```
上创建Shadow根——子组件为标准React组件
```
slot
```
属性无关紧要；始终使用React属性（
```
prepend
```
、
```
append
```
、
```
footer
```
等）

4. Provide Recommendations

4. 提供建议

Prioritise findings using these levels:

Priority	Description	Action
Critical	Missing Provider/CSS, raw inputs without labels, missing skip links, forms not using `IressForm`	Must fix immediately
High	Raw HTML elements with IDS equivalents, custom form handling, a11y failures, high cognitive load issues	Fix in current sprint
Medium	Hardcoded tokens, missing IressText, custom layout, missing ARIA landmarks, information density issues	Plan for next sprint
Low	Missing IressImage, custom badges, minor token inconsistencies, non-critical UX improvements	Backlog

For each finding, provide: (1) what was found, (2) why it matters, (3) how to fix (with before/after code), (4) priority level.

使用以下优先级对发现的问题进行排序：

优先级	描述	操作
Critical（严重）	缺失Provider/CSS、无标签的原始输入、缺失跳转链接、未使用 `IressForm` 的表单	必须立即修复
High（高）	使用原始HTML元素而未用IDS等效组件、自定义表单处理、可访问性失败、高认知负载问题	当前迭代修复
Medium（中）	硬编码令牌、缺失IressText、自定义布局、缺失ARIA地标、信息密度问题	计划在下一迭代修复
Low（低）	缺失IressImage、自定义徽章、令牌轻微不一致、非严重UX改进	放入待办列表

针对每个发现的问题，提供：(1) 问题内容，(2) 影响原因，(3) 修复方法（附带前后代码示例），(4) 优先级级别。

5. Generate Compliance Report

5. 生成合规报告

Use the report template to produce a structured report.

使用报告模板生成结构化报告。

Example Audit Output

审计输出示例

Quick Scan Summary

快速扫描摘要

IDS UI Doctor — Quick Scan
================================
Files scanned:     42
Components found:  18 IDS / 7 raw HTML
Patterns used:     3/7 available
Token compliance:  73%
Accessibility:     82%

Top Issues:
  ⚠ 3× raw <button> found (should be IressButton)
  ⚠ 2× hardcoded colours found (#333, #f5f5f5)
  ⚠ 1× <input> without IressField wrapper
  ⚠ 2× custom <form> found (should use IressForm)
  ⚠ 1× custom loading spinner (should use IressLoading)
  ⚠ 1× missing skip link for keyboard navigation
  ✓ IressProvider correctly configured
  ✓ Component CSS imported
  ✓ IressBreadcrumbs used for navigation hierarchy
  ✓ Colour contrast passes WCAG AA

IDS UI Doctor — 快速扫描
================================
扫描文件数:     42
发现组件数:  18个IDS组件 / 7个原始HTML组件
使用模式数:     7种可用模式中使用了3种
令牌合规率:  73%
可访问性得分:     82%

主要问题:
  ⚠ 发现3处原始<button>（应使用IressButton）
  ⚠ 发现2处硬编码颜色（#333, #f5f5f5）
  ⚠ 发现1处无IressField包裹的<input>
  ⚠ 发现2处自定义<form>（应使用IressForm）
  ⚠ 发现1处自定义加载spinner（应使用IressLoading）
  ⚠ 缺少键盘导航跳转链接
  ✓ IressProvider配置正确
  ✓ 已导入组件CSS
  ✓ 使用IressBreadcrumbs进行导航层级管理
  ✓ 颜色对比度符合WCAG AA标准

Reference

参考资料

Note: Component docs, pattern docs, and the manifest are within the package itself.

Component docs:

node_modules/@iress-oss/ids-components/.ai/components/

Pattern docs:

node_modules/@iress-oss/ids-components/.ai/patterns/

Index (full component list):

node_modules/@iress-oss/ids-components/.ai/index.json

Token usage skill:
```
.agents/skills/token-usage/SKILL.md
```
Figma mapping skill:
```
.agents/skills/figma-to-ids/SKILL.md
```
UI translation skill:
```
.agents/skills/ui-translation/SKILL.md
```
Storybook and Guidelines: https://main--691abcc79dfa560a36d0a74f.chromatic.com

Common mistakes guide:

node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md

(requires

@iress-oss/ids-components

to be installed)

注意： 组件文档、模式文档和清单均在包内。

组件文档:

node_modules/@iress-oss/ids-components/.ai/components/

模式文档:

node_modules/@iress-oss/ids-components/.ai/patterns/

索引（完整组件列表）:

node_modules/@iress-oss/ids-components/.ai/index.json

令牌使用技能:
```
.agents/skills/token-usage/SKILL.md
```
Figma映射技能:
```
.agents/skills/figma-to-ids/SKILL.md
```
UI转换技能:
```
.agents/skills/ui-translation/SKILL.md
```
Storybook与指南: https://main--691abcc79dfa560a36d0a74f.chromatic.com

常见错误指南:

node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md

（需安装

@iress-oss/ids-components

）

Common Mistakes to Flag in Audits

审计中需标记的常见错误

For the full list of common anti-patterns with code examples, read the Common Mistakes guide at

node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md

(requires

@iress-oss/ids-components

to be installed). When auditing, flag these with the following priorities and audit rules:

完整的常见反模式及代码示例，请阅读

node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md

中的常见错误指南（需安装

@iress-oss/ids-components

）。审计时，按以下优先级和审计规则标记这些错误：

disabled

attribute on IressButton — High priority

IressButton上的

disabled

属性 — 高优先级

Audit rule: Search for

disabled

on any

<IressButton

. Every match is a finding.

审计规则: 搜索所有

<IressButton

上的

disabled

属性。每一处匹配均为问题。

Redundant

textStyle

on IressText — Medium priority

IressText上冗余的

textStyle

— 中优先级

Audit rule: Search for

IressText

with both

element

and

textStyle

where the textStyle matches the element's default styling (e.g.

element="h1" textStyle="typography.heading.1"

审计规则: 搜索同时带有

element

和

textStyle

且textStyle与element默认样式匹配的

IressText

（例如

element="h1" textStyle="typography.heading.1"

）。

Legacy

slot

attributes (v4 pattern) — High priority

旧版

slot

属性（v4模式） — 高优先级

Audit rule: Search for

slot="

inside any

<Iress*>

component. Every match is a finding.

审计规则: 搜索所有

<Iress*>

组件内的

slot="

。每一处匹配均为问题。

ui-doctor

Original

Translation

Skill: UI Doctor

技能：UI Doctor

When to Use

使用场景

Audit Modes

审计模式

Quick UX Review (default)

快速UX评审（默认）

Accessibility Review

可访问性评审

Full Compliance Audit

全面合规审计

Scoped Audits

范围化审计

Audit Scope

审计范围

Files to Scan

需扫描的文件

Files to Exclude

需排除的文件

Version-Aware Auditing

版本感知审计

Audit Process

审计流程

1. Evaluate UX, Accessibility & Cognitive Load

1. 评估UX、可访问性与认知负载

a. Usability Heuristics (Nielsen's 10)

a. 易用性启发法（尼尔森十大原则）

b. Cognitive Load & Information Architecture

b. 认知负载与信息架构

c. Accessibility (WCAG 2.1 AA)

c. 可访问性（WCAG 2.1 AA标准）

d. Button Hierarchy

d. 按钮层级

e. Layout Consistency

e. 布局一致性

2. Validate IDS Component Usage

2. 验证IDS组件使用情况

3. Validate IDS Principles & Setup

3. 验证IDS原则与配置

a. Provider & CSS Setup

a. Provider与CSS配置

b. Design Token Usage

b. 设计令牌使用

c. Form & Pattern Compliance

c. 表单与模式合规性

4. Provide Recommendations

4. 提供建议

5. Generate Compliance Report

5. 生成合规报告

Example Audit Output

审计输出示例

Quick Scan Summary

快速扫描摘要

Reference

参考资料

Common Mistakes to Flag in Audits

审计中需标记的常见错误

disabled attribute on IressButton — High priority

IressButton上的disabled属性 — 高优先级

Redundant textStyle on IressText — Medium priority

IressText上冗余的textStyle — 中优先级

Legacy slot attributes (v4 pattern) — High priority

旧版slot属性（v4模式） — 高优先级

`disabled`
attribute on IressButton — High priority

IressButton上的
`disabled`
属性 — 高优先级

Redundant
`textStyle`
on IressText — Medium priority

IressText上冗余的
`textStyle`
— 中优先级

Legacy
`slot`
attributes (v4 pattern) — High priority

旧版
`slot`
属性（v4模式） — 高优先级