using-westpac-ui

使用 @westpac/ui

提供有关如何在 Westpac Group 应用中使用 GEL（Global Experience Language）设计系统组件库的指导。此软件包也可能被称为“GEL-Next”、“GEL Next”或“GEL v1.0.0”。请务必检查 package.json 中的版本，以确认你参考的是正确的文档，因为有些使用者可能安装了功能和模式不同的 @westpac/ui v0.x。也可能安装了另一个完全不同、同样被称为“GEL”的软件包。

适用场景

当用户已安装 @westpac/ui，并询问与 @westpac/ui 或 GEL 相关的问题时，请参考此技能。提到 @westpac/ui 组件名称，或询问可通过 @westpac/ui 组件实现的 UI 模式时，也应使用此技能。

相关技能（可选）

• installing-westpac-ui — 新项目的完整设置指南（安装、CSS、主题、品牌字体、ESLint）
• migrating-to-westpac-ui-v1 — 从 1.0 之前的版本迁移到 v1.0 的指南（破坏性更改、令牌 codemod、组件 API 更改）

导入

组件可以从主软件包或单独导入：

// Main import (tree-shakable)
import { Button, Input, Modal } from '@westpac/ui';

// Individual imports (smaller bundles)
import { Button } from '@westpac/ui/button';
import { Input } from '@westpac/ui/input';
import { Modal, ModalBody, ModalFooter } from '@westpac/ui/modal';

// Hooks
import { useBreakpoint, useDarkMode } from '@westpac/ui/hook';

// Types (Component props are exported from the component where applicable)
import type { ResponsiveVariants } from '@westpac/ui/types';
import type { BrandKey } from '@westpac/ui/types';

核心概念

响应式变体

大多数组件的属性都支持响应式值——你可以传入单个值，也可以传入一个以断点为键的对象：

错误示例（断点键无效且使用了数组语法）

// Invalid breakpoint keys — use initial, xsl, sm, md, lg, xl
<Button size={{ mobile: 'small', desktop: 'large' }} />

// Responsive values are keyed objects, not arrays
<Button size={['small', 'large']} />

正确示例

// Single value
<Button size="large" />

// Responsive — different value per breakpoint
<Button
  size={{ initial: 'small', md: 'large', lg: 'xlarge' }}
  soft={{ initial: false, sm: true }}
/>

断点（移动优先）：

键	最小宽度	描述
initial	0px	基础 / 移动端
xsl	576px	超小横屏
sm	768px	小型（平板）
md	992px	中型（桌面）
lg	1200px	大型
xl	1584px	超大型

支持响应式值的属性类型为 ResponsiveVariants<T>。

多态 tag 属性

许多组件都接受 tag 属性，用于更改渲染的 HTML 元素：

错误示例（使用 as 代替 tag，且元素名称无效）

<Button as="a" href="/page">Link styled as button</Button>
<Badge tag="badge">Tag</Badge>

正确示例

<Button tag="a" href="/page">Link styled as button</Button>
<Button tag="span">Span styled as button</Button>
<Badge tag="span">Tag</Badge>

图标系统

图标以组件引用的形式传入（而不是已渲染的元素）：

import { ArrowRightIcon, BurgerIcon } from '@westpac/ui/icon';

// ✅ Correct — pass the component
<Button iconBefore={ArrowRightIcon}>Next</Button>

// ❌ Wrong — don't pass a rendered element
<Button iconBefore={<ArrowRightIcon />}>Next</Button>

图标支持 look（'filled' | 'outlined'）、size 和 color 属性。共有 260 多种图标可用。

焦点管理

组件使用 react-aria 实现无障碍焦点管理。仅在键盘导航时显示焦点环（点击时不会显示）。此功能会自动处理，无需配置。

设计令牌

设计令牌是来自 @westpac/style-config 的命名设计决策（颜色、字体排印、间距、边框圆角）。它们是所有品牌外观风格的唯一可信来源。在使用这些令牌的应用中，应将其用作由 CSS 变量支持的 Tailwind 实用类——绝不要直接引用原始值。

令牌以语义化、按用途命名的类的形式提供。常见分组：

分组	示例类	用途
表面	bg-surface-primary、bg-surface-muted、bg-surface-hero-faint	组件／元素背景
背景	bg-background-white、bg-background-pale、bg-background-hero	页面和分区背景
文本	text-text-body、text-text-heading、text-text-muted、text-text-danger	文本颜色
边框	border-border-muted、border-border-focus、border-border-primary	边框颜色
字体排印	typography-body-8、typography-brand-4	字号／行高组合
圆角	rounded-md、rounded-lg、rounded-full	边框圆角

由于令牌具有语义且适配品牌，同一个类名会自动解析为当前启用品牌（data-brand="wbc" | "stg" | "bom" | "bsa"）对应的正确值。这正是绝不能使用硬编码值的原因——它们会破坏品牌主题。

绝不要自行创建令牌或硬编码值。 只能使用 @westpac/style-config 提供的现有设计决策。不要使用十六进制代码、RGB 值、任意 Tailwind 值（例如 bg-[#da1710]）、自定义 CSS 变量，或自行编写的颜色、字体排印、间距或圆角实用类。如果需要的令牌似乎不存在，不要创建变通方案——这很可能是有意的设计决策。

错误（硬编码十六进制值、任意值和自行创建的令牌）

// Hardcoded hex — breaks brand theming and dark mode
<div className="bg-[#da1710] text-[#ffffff]">...</div>

// Arbitrary radius / spacing values instead of tokens
<Card className="rounded-[7px]" />

// Inline styles bypassing the token system
<div style={{ backgroundColor: '#1f1c4f', color: 'white' }}>...</div>

// Invented / custom token name that doesn't exist in the design system
<p className="text-brand-red-500">...</p>

正确（仅使用语义令牌）

// Semantic surface + text tokens — resolve per active brand
<div className="bg-surface-primary text-text-mono">...</div>

// Token-backed radius
<Card className="rounded-md" />

// Semantic hero background with body text
<section className="bg-surface-hero-faint text-text-body">...</section>

// Status colours via reserved semantic tokens
<p className="text-text-danger">Something went wrong</p>

样式与自定义

部分组件支持通过 className 设置自定义样式，但为保持设计一致，应优先使用内置属性。颜色不应使用任意值，且应始终使用设计系统令牌。不得使用元素选择器或全局 CSS 覆盖样式。

如何回答有关组件的问题

当用户问“组件 X 能否实现 Y？”时，请按以下流程操作：

1. 检查是否安装了正确的软件包 — 确认用户安装的是 @westpac/ui >= v1.0.0，而不是旧版本或另一个也被称为“GEL”的软件包。还要检查版本是否过时；如果是，建议更新到最新版本，因为较新版本可能已修复错误或添加了可以解决问题的功能。
2. 如果软件包不正确／未安装 — 明确说明不支持旧版本，并建议安装正确的软件包或更新到最新版本。必要时提供安装／迁移说明。
3. 查看组件参考文档 — 阅读 reference/components/ 中相关的文件（例如 reference/components/button.md），查找该组件及其属性。阅读 reference/components.md，了解 className 支持情况和自定义指南。
4. 检查是否存在相应属性 — 查找可直接支持所需功能或模式的属性（例如 color、look、iconBefore、block、tag 等）。
5. 如果存在相应属性 — 提供正确用法和代码示例。
6. 如果没有相应属性，但可以实现 — 说明实现方式（例如使用 className、组合组件或 tag 属性）。
7. 如果功能上不支持 — 明确说明不支持，并建议在内部 Teams 频道发布功能请求。
8. 如果不支持通过 className 设置样式 — 明确说明不支持，且不应覆盖样式。建议这可能是设计问题，并建议在内部 Teams 频道与 GEL 设计师讨论。
9. 如果涉及无障碍访问 — 阅读 reference/design-guidelines.md 中的无障碍访问说明，并确保推荐的模式符合最佳实践。

常见功能问题

“我可以更改颜色／外观吗？” → 检查 look、color 或 soft 属性
“我可以使用自定义颜色吗？” → 告知用户不应使用自定义颜色，应改用设计令牌。如果不存在所需的令牌，建议在内部 Teams 频道发布请求。
“我可以让它自适应吗？” → 检查属性类型是否包含 ResponsiveVariants
“我可以将它渲染为其他元素吗？” → 检查是否有 tag 属性
“我可以添加图标吗？” → 检查是否有 iconBefore、iconAfter 或 icon 属性
“我可以让它占满宽度吗？” → 检查是否有 block 属性
“我可以控制打开／关闭状态吗？” → 检查是否有 open、state 或 defaultExpandedKeys 属性
“我可以进行验证／显示错误吗？” → 检查是否有 invalid、errorMessage 属性
“我可以在表单中使用它吗？” → 检查它是否扩展了 HTML 表单元素属性、是否有 name 属性，或是否兼容来自 @westpac/ui/field 的 Field 组件
“我可以自定义样式吗？” → 检查是否有 className 属性，但样式设置应优先使用内置属性。不应使用元素选择器或全局 CSS 覆盖样式。如果不存在所需的样式选项，建议在内部 Teams 频道发布请求，因为这可能是设计问题。

可用的 Hook

useBreakpoint()

返回当前启用的断点（'initial' | 'xsl' | 'sm' | 'md' | 'lg' | 'xl'）。内部使用 zustand 和 matchMedia 监听器。

错误示例（条件调用 Hook，且断点值无效）

import { useBreakpoint } from '@westpac/ui/hook';

function MyComponent({ enabled }: { enabled: boolean }) {
  // Don't call hooks conditionally — breaks the Rules of Hooks
  if (enabled) {
    const breakpoint = useBreakpoint();
  }
  // 'mobile' isn't valid — values are initial | xsl | sm | md | lg | xl
  const isMobile = useBreakpoint() === 'mobile';
}

正确示例

import { useBreakpoint } from '@westpac/ui/hook';

function MyComponent() {
  const breakpoint = useBreakpoint();
  // breakpoint === 'initial' | 'xsl' | 'sm' | 'md' | 'lg' | 'xl'
}

useDarkMode()

返回深色模式辅助方法：getMode()、setMode()、toggleDarkMode()、getBrand()、getSystemPreference()。

注意： 当前版本已禁用深色模式。

参考文档

回答有关如何或何时使用组件的问题，或在集成中使用组件时，请查阅以下随附的参考资料：

• reference/components.md — 组件概览，以及 className 支持和自定义指南
• reference/components/ — 各组件的参考文件，包含属性、类型、默认值、功能和使用示例
• reference/design-guidelines.md — 每个组件的设计指南、建议与禁忌、UX 说明、无障碍指南和代码示例
• reference/integration-requirements.md — 集成要求和最佳实践，帮助使用平台确保 UI 一致性、易于维护，并与未来的系统更新保持一致。

组件目录

有关组件属性、默认值和功能，请阅读 reference/components/ 中相应的组件文件。

目录按字母顺序排列，包含：

• 所有导出的组件和类型
• 每个属性的类型、默认值和说明
• 组件是否支持响应式变体
• 复合组件的子组件
• 常见模式的使用示例