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 要素を変更できます。

誤り（tag の代わりに as を使用し、無効な要素名を指定）

<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 が公開する既存のスタイル上の決定事項のみを使用してください。色、タイポグラフィ、余白、角丸には、16 進数コード、RGB 値、任意の Tailwind 値（例：bg-[#da1710]）、カスタム CSS 変数、独自のユーティリティクラスを使用しないでください。必要なトークンが見つからない場合も、回避策を作成しないでください。これはデザイン上の決定である可能性が高いです。

誤り（16 進数のハードコード、任意の値、独自のトークン）

// 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. 正しいパッケージがインストールされているか確認する — ユーザーが古いバージョンや、「GEL」とも呼ばれる別のパッケージではなく、@westpac/ui >= v1.0.0 をインストールしていることを確認します。また、バージョンが古い場合は、新しいバージョンで問題が修正されていたり、解決に役立つ機能が追加されていたりする可能性があるため、最新版への更新を勧めます。
2. パッケージが間違っている／インストールされていない場合 — 古いバージョンはサポートされていないことを明確に伝え、正しいパッケージのインストールまたは最新版への更新を提案します。必要に応じて、インストールや移行の手順を案内します。
3. コンポーネントのリファレンスを確認する — reference/components/ 内の該当ファイル（例：reference/components/button.md）を読み、コンポーネントとその props を確認します。className のサポートとカスタマイズ方法については、reference/components.md を読みます。
4. prop があるか確認する - 要望された機能やパターンに直接対応する prop（例：color、look、iconBefore、block、tag など）があるか探します。
5. prop がある場合 — 正しい使い方をコード例で示します。
6. prop はないが実現可能な場合 — 方法（例：className、コンポジション、tag prop の使用）を説明します。
7. 機能としてサポートされていない場合 — サポートされていないことを明確に伝え、機能リクエストを内部 Teams チャネルに投稿するよう提案します。
8. className でスタイルをサポートできない場合 — サポートされておらず、上書きすべきでないことを明確に伝えます。デザイン上の問題である可能性があるため、GEL のデザイナーと相談するために内部 Teams チャネルへ投稿するよう提案します。
9. アクセシビリティが懸念される場合 — reference/design-guidelines.md でアクセシビリティに関する注意事項を確認し、推奨するパターンがベストプラクティスに従っていることを確かめます。

よくある機能に関する質問

「色／見た目を変更できますか？」 → look、color、または soft props を確認します。 「カスタムカラーを使えますか？」 → カスタムカラーは使用せず、代わりにデザイントークンを使用するよう伝えます。必要なトークンがない場合は、内部 Teams チャネルへの投稿を提案します。 「レスポンシブにできますか？」 → prop の型に ResponsiveVariants が含まれているか確認します。 「別の要素としてレンダリングできますか？」 → tag prop を確認します。 「アイコンを追加できますか？」 → iconBefore、iconAfter、または icon props を確認します。 「幅いっぱいにできますか？」 → block prop を確認します。 「開閉を制御できますか？」 → open、state、または defaultExpandedKeys props を確認します。 「バリデーションを行ったり、エラーを表示したりできますか？」 → invalid、errorMessage props を確認します。 「フォームで使えますか？」 → HTML フォーム要素の属性を拡張し、name prop があるか、または @westpac/ui/field の Field コンポーネントと互換性があるか確認します。 「スタイルをカスタマイズできますか？」 → className prop を確認します。ただし、スタイルには組み込みの props を優先してください。要素セレクターやグローバル CSS を使ってスタイルを上書きしてはいけません。必要なスタイル設定がない場合は、デザイン上の問題である可能性があるため、内部 Teams チャネルへの投稿を提案します。

利用可能なフック

useBreakpoint()

現在アクティブなブレークポイント（'initial' | 'xsl' | 'sm' | 'md' | 'lg' | 'xl'）を返します。内部では zustand と matchMedia リスナーを使用します。

誤り（条件付きのフック呼び出しと無効なブレークポイント値）

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/ — 各コンポーネントの props、型、デフォルト値、機能、使用例を記載したリファレンスファイル
• reference/design-guidelines.md — すべてのコンポーネントのデザインガイドライン、推奨事項と禁止事項、UX に関する注記、アクセシビリティ、コード例
• reference/integration-requirements.md — 一貫した UI、保守性、将来のシステム更新との整合性を確保するための、統合要件と利用プラットフォーム向けのベストプラクティス。

コンポーネントカタログ

コンポーネントの props、デフォルト値、機能については、reference/components/ 内の該当するコンポーネントファイルを参照してください。

カタログはアルファベット順に整理されており、以下が含まれています。

• エクスポートされているすべてのコンポーネントと型
• 各 prop の型、デフォルト値、説明
• コンポーネントがレスポンシブバリアントに対応しているかどうか
• 複合コンポーネントのサブコンポーネント
• 一般的なパターンの使用例