migrating-to-westpac-ui-v1

@westpac/ui v1.0 への移行

1.0 より前の @westpac/ui から v1.0 に既存のアプリケーションを移行するためのガイドです。新規インストールの場合は、代わりに installing-westpac-ui スキルを使用してください。

使用するタイミング

ユーザーが古いバージョンの @westpac/ui を使用していて（package.json を確認してください）、v1.0 へのアップグレードを希望している場合に、このガイドを参照してください。主な破壊的変更の理解、トークンの codemod の実行、Tailwind CSS 設定の更新、コンポーネント API の変更への対応が含まれます。

v0.x からの主な変更点

v1.0 では、UI コンポーネントとスタイル設定を分離する新しいアーキテクチャが導入されました。

• @westpac/style-config は、次の機能を提供する新しい必須パッケージです。
  • Tailwind トークン
  • ライト／ダークテーマ
  • CSS + W3C デザイントークン
• Tailwind CSS が v3 から v4 にアップグレードされました
• マルチブランド + デュアルテーマに対応するため、すべてのカラートークンの名前が変更されました

手順

1. Tailwind CSS を v4 にアップグレードする

既存の tailwind.config.js を削除し、Tailwind CSS v4 アップグレードガイドに従ってください。自動アップグレードコマンドが機能しない場合は、そのページに記載されている手動の手順に従ってください。

2. 更新された依存関係をインストールする

npm i @westpac/ui @westpac/style-config tailwindcss@4 postcss tailwind-variants@~3.1.1

3. CSS インポートを更新する

既存の Tailwind/GEL CSS の設定を次の内容に置き換えてください。

@import 'tailwindcss';
@import '@westpac/style-config/tailwind';

/* Import brand themes you need: */
@import '@westpac/style-config/themes/wbc';
@import '@westpac/style-config/themes/stg';
@import '@westpac/style-config/themes/bom';
@import '@westpac/style-config/themes/bsa';

/* Brand font @font-face declarations (update paths to your font files) */
/* WBC fonts */
@font-face {
  src:
    url('/fonts/Westpac-Bold-v2.007.woff2') format('woff2'),
    url('/fonts/Westpac-Bold-v2.007.woff') format('woff');
  font-family: 'Westpac';
  font-weight: 100 900;
  font-style: normal;
}

/* STG fonts */
@font-face {
  src:
    url('/fonts/dragonbold-bold-webfont.woff2') format('woff2'),
    url('/fonts/dragonbold-bold-webfont.woff') format('woff');
  font-family: 'Dragon Bold';
  font-weight: 100 900;
  font-style: normal;
}

4. ブランド属性を更新する

ブランド属性が data-theme から data-brand に変更されました。

変更前

<html data-theme="wbc"></html>

変更後

<html data-brand="wbc" data-theme="light"></html>

注： このリリースでは、ダークモード（data-theme="dark"）は無効になっています。

5. ESLint の設定を更新する（@westpac/eslint-config を使用している場合は省略可）

// eslint.config.mjs
import eslintConfig from '@westpac/eslint-config/nextjs';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  ...eslintConfig,
  {
    settings: {
      'better-tailwindcss': {
        entryPoint: 'src/globals.css',
      },
    },
  },
]);

6. トークンの codemod を実行する

# Install jscodeshift if needed
npm install -g jscodeshift

# Run the codemod against your source files
npx jscodeshift --parser=tsx -t node_modules/@westpac/ui/scripts/codemods/gel-tokens-tailwind-v1.cjs <path>/**/*.tsx

変更内容の参照先

1. トークンの更新
   • 1.1 更新例
   • 1.2 トークンの codemod の実行
2. インポートパスの変更
   • 2.1 スタイル定数
3. コンポーネント API の変更
   • 3.1 Accordion
   • 3.2 ButtonGroup
   • 3.3 DatePicker
   • 3.4 Compacta
   • 3.5 Repeater
   • 3.6 BottomSheet
   • 3.7 Pictogram
4. 非推奨のコンポーネントと API
5. フォームの移行例
6. 削除されたシンボルとロゴ
   • 6.1 ロゴ
   • 6.2 シンボル

1. トークンの更新

マルチブランド + デュアルテーマのシステムに対応するため、すべてのカラートークンの名前が変更されました。これは最も大きな変更であり、コードベース内のすべてのカスタム Tailwind クラスに影響します。

1.1 更新例

変更前

<div className="bg-white">
  <div className="bg-primary rounded-full">
    <AccountIcon color="white" />
  </div>
  <h2 className="text-text">
    My title
    <BankIcon color="link" className="ml-2" />
  </h2>
  <p className="text-text">Lorem ipsum dolor sit amet</p>
</div>

変更後

<div className="bg-background-white">
  <div className="bg-surface-primary rounded-full">
    <AccountIcon color="mono" />
  </div>
  <h2 className="text-text-body">
    My title
    <BankIcon color="primary" className="ml-2" />
  </h2>
  <p className="text-text-body">Lorem ipsum dolor sit amet</p>
</div>

1.2 トークンの codemod の実行

トークンの移行を自動化する codemod が用意されています。

# Install jscodeshift if needed
npm install -g jscodeshift

# Run the codemod against your source files
npx jscodeshift --parser=tsx -t node_modules/@westpac/ui/scripts/codemods/gel-tokens-tailwind-v1.cjs <path>/**/*.tsx

重要な注意事項：

• プロジェクトに応じて、--parser パラメーターを babel、flow、ts、または tsx にする必要がある場合があります
• プロジェクトの構造によっては、codemod を複数回実行する必要がある場合があります
• 自動的に対応付けられないクラスについては、codemod によって [REPLACE_TOKEN] が挿入されます。デザイナーと相談して、これらを適切なトークンに置き換えてください
• 一時的な対応として、不明なトークンを近い値や 16 進数値に置き換えることができます（例：text-black → text-[#000]）

codemod スクリプトのソース：gel-tokens-tailwind-v1.cjs

2. インポートパスの変更

2.1 スタイル定数

変更前

import { BREAKPOINTS, SPACING_UNIT } from '@westpac/ui/theme-constants';

変更後

import { BREAKPOINTS, SPACING_UNIT } from '@westpac/style-config/constants';

3. コンポーネント API の変更

3.1 Accordion — react-aria の useDisclose を使用

defaultExpandedKeys は、AccordionItem の id 値に基づいて動作するようになりました。

変更前

<Accordion defaultExpandedKeys={['FoR']}>
  <AccordionItem title="Founding of Rome">Content</AccordionItem>
</Accordion>

変更後

<Accordion defaultExpandedKeys={['FoR']}>
  <AccordionItem id="FoR" title="Founding of Rome">
    Content
  </AccordionItem>
</Accordion>

3.2 ButtonGroup — コンポジション API

変更前

<ButtonGroup
  value={value}
  buttons={[
    { value: 'Left', label: 'Left' },
    { value: 'Middle', label: 'Middle' },
    { value: 'Right', label: 'Right' },
  ]}
/>

変更後

<ButtonGroup selectedKeys={value}>
  <ButtonGroupButton id="Left">Left</ButtonGroupButton>
  <ButtonGroupButton id="Middle">Middle</ButtonGroupButton>
  <ButtonGroupButton id="Right">Right</ButtonGroupButton>
</ButtonGroup>

3.3 DatePicker — react-aria ベース

disableDates プロパティは isDateUnavailable 関数に置き換えられました。

変更前

<DatePicker disableDates={['2023-10-10']} />

変更後

import { DateValue } from '@internationalized/date';

const disableDates = ['2023-10-20'];
const isDateUnavailable = (date: DateValue) => disableDates.some(d => d.toString() === date.toString());

<DatePicker isDateUnavailable={isDateUnavailable} />;

3.4 Compacta — シンプルになった API

レンダープロップパターンから、CompactaItem を使用するコンポジション形式の子要素に変更されました。

変更前

<Compacta initialCompactas={[{ id: '1234', title: { primary: 'test' } }, {}]} onAdd={() => {}} onRemove={() => {}}>
  {({ id, setPrimaryTitle }) => (
    <Form>
      <FormGroup>
        <Label htmlFor={`primary-${id}`}>Primary</Label>
        <Input name={`primary-${id}`} onChange={e => setPrimaryTitle(e.target.value)} />
      </FormGroup>
    </Form>
  )}
</Compacta>

変更後

<Compacta onAdd={handleAdd}>
  {items.map((item, index) => (
    <CompactaItem
      key={index}
      title={{ primary: item.primary, secondary: item.secondary, tertiary: item.tertiary }}
      onRemove={() => removeItem(index)}
    >
      <Field label="Primary" hintMessage="Primary title text">
        <Input {...register(`items.${index}.primary`)} />
      </Field>
    </CompactaItem>
  ))}
</Compacta>

3.5 Repeater — Compacta と統一

Compacta と同様のパターン変更が行われ、RepeaterItem の子要素を使用します。

変更前

<Repeater>
  <FormGroup>
    <FormLabel htmlFor={`input${id}`}>Label</FormLabel>
    <Input name={`input${id}`} />
  </FormGroup>
</Repeater>

変更後

<Repeater onAdd={handleAdd}>
  {items.map((item, index) => (
    <RepeaterItem key={index} title={{ primary: item.primary }} onRemove={() => removeItem(index)}>
      <Field label="Label">
        <Input {...register(`items.${index}.label`)} />
      </Field>
    </RepeaterItem>
  ))}
</Repeater>

3.6 BottomSheet — isDismissable のデフォルト値は false

Modal の動作に合わせるようになりました。

Before

<BottomSheet title="Title">Content</BottomSheet>

After

<BottomSheet title="Title" isDismissable>
  Content
</BottomSheet>

3.7 ピクトグラム — mode プロパティの値を変更

Before

type PictogramMode = 'dark' | 'light' | 'duo';
<Pictogram mode="dark" />;

After

type PictogramMode = 'base' | 'mono' | 'duo';
<Pictogram mode="base" />;

4. 非推奨のコンポーネントと API

非推奨	置き換え先／備考
ButtonDropdown	Dropdown に置き換え
Form、FormGroup、FormChitChat、FormSection	削除 — <form> と className="flex flex-col gap-4"、Field コンポーネントを使用してください
Pagination pages={[]}	削除 — 代わりに totalPages={number} を使用してください

5. フォームの移行例

Before

<Form spacing="large" onSubmit={handleSubmit}>
  <FormGroup>
    <InputGroup size="large" label="Given name">
      <Input {...register('givenName')} />
    </InputGroup>
  </FormGroup>
  <FormGroup>
    <Field label="Comments:">
      <Textarea size="large" {...register('comment')} />
    </Field>
  </FormGroup>
</Form>

After

<form className="flex flex-col gap-4" onSubmit={handleSubmit}>
  <Field label="Given name">
    <InputGroup size="large">
      <Input {...register('givenName')} />
    </InputGroup>
  </Field>
  <Field label="Comments:">
    <Textarea size="large" {...register('comment')} />
  </Field>
</form>

6. 削除されたシンボルとロゴ

以下は削除されました。削除が誤りだと思われる場合は、GEL デザインチームにお問い合わせください。

6.1 ロゴ

• BTPanormaMultibrandLargeLogo
• BTPanormaMultibrandSmallLogo
• RedAvatarCircleLogo
• RedAvatarCircleReverseLogo
• RedAvatarLogo

6.2 シンボル

• GooglePlusSymbol
• MastercardAcceptedSymbol
• MastercardHorizontalSymbol
• MicrosoftStoreSymbol
• PayToBlackSymbol
• PayToDarkGreySymbol
• PayToLightGreySymbol
• PayToWhiteSymbol
• PayToWordmarkBlackSymbol
• PayToWordmarkDarkGreySymbol
• PayToWordmarkLightGreySymbol
• PayToWordmarkWhiteSymbol
• SlackSymbol
• TwitterSymbol
• VisaSymbol
• XMarkInverseSymbol
• XMarkSymbol
• YammerSymbol