installing-westpac-ui

用途

本指南用于在全新项目中搭建 Westpac 的 GEL 设计系统，包括安装所需软件包、配置 Tailwind CSS、设置品牌主题令牌以及添加品牌字体。当用户希望在项目中引入 GEL 设计系统时，可参考本指南。

主要能力

GEL 被拆分为两个软件包：

@westpac/ui —— 包含全部设计系统组件
@westpac/style-config —— 提供 Tailwind CSS 主题与设计令牌

安装命令：

npm i @westpac/ui @westpac/style-config

使用方式

安装 Tailwind CSS

GEL 组件使用 Tailwind CSS v4 进行样式处理，需按照 Tailwind CSS 的安装说明操作：

npm i tailwindcss @tailwindcss/postcss postcss

创建 postcss.config.mjs：

import { postcssConfig } from '@westpac/style-config/postcss';

export default postcssConfig;

设置样式

在主 CSS 文件中添加以下导入：

@import 'tailwindcss';
@import '@westpac/style-config/tailwind'; /* GEL 主题配置（排版、间距等） */
@import '@westpac/style-config/themes/wbc'; /* 品牌颜色令牌 —— 按需导入所需品牌 */

@source "./node_modules/@westpac/ui/src"; /* 使 Tailwind 能扫描组件类名 */

启用品牌主题

在 HTML 的父元素上添加 data-brand 属性：

<html lang="en" data-brand="wbc">
  <!-- 应用内容 -->
</html>

或添加到任意容器元素上：

<div data-brand="wbc">
  <!-- 应用内容 -->
</div>

可用品牌：

wbc —— Westpac Banking Corporation
stg —— St.George Bank
bom —— Bank of Melbourne
bsa —— BankSA

按需导入各品牌的主题 CSS：

@import '@westpac/style-config/themes/wbc';
@import '@westpac/style-config/themes/stg';
@import '@westpac/style-config/themes/bom';
@import '@westpac/style-config/themes/bsa';

多品牌应用可通过 data-brand 属性动态切换：

<div data-brand={currentBrand}>{/* 应用内容 */}</div>

注意：当前版本中深色模式（data-theme="dark"）已被禁用。

品牌字体

添加相应的 @font-face 声明，并将 src 路径更新为字体文件的实际位置：

/* BOM 字体 */
@font-face {
  src:
    url('/fonts/lineto-brown-pro-light.woff2') format('woff2'),
    url('/fonts/lineto-brown-pro-light.woff') format('woff');
  font-family: 'Brown Pro';
  font-weight: 100 300;
  font-style: normal;
}
@font-face {
  src:
    url('/fonts/lineto-brown-pro-regular.woff2') format('woff2'),
    url('/fonts/lineto-brown-pro-regular.woff') format('woff');
  font-family: 'Brown Pro';
  font-weight: 400 600;
  font-style: normal;
}
@font-face {
  src:
    url('/fonts/lineto-brown-pro-bold.woff2') format('woff2'),
    url('/fonts/lineto-brown-pro-bold.woff') format('woff');
  font-family: 'Brown Pro';
  font-weight: 700 900;
  font-style: normal;
}

/* BSA 字体 */
@font-face {
  src:
    url('/fonts/Aller_Lt.woff2') format('woff2'),
    url('/fonts/Aller_Lt.woff') format('woff');
  font-family: 'Aller';
  font-weight: 100 600;
  font-style: normal;
}
@font-face {
  src:
    url('/fonts/Aller_Bd.woff2') format('woff2'),
    url('/fonts/Aller_Bd.woff') format('woff');
  font-family: 'Aller';
  font-weight: 700 900;
  font-style: normal;
}

/* STG 字体 */
@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;
}

/* WBC 字体 */
@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;
}

ESLint 配置（需询问用户是否包含）

Next.js 项目：

// 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',
      },
    },
  },
]);

非 Next.js 项目可能需要禁用某些 Next.js 专属规则：

// .eslintrc.js
module.exports = {
  root: true,
  extends: ['@westpac/eslint-config/nextjs'],
  rules: {
    '@next/next/no-html-link-for-pages': 0,
  },
};

适用场景

适用于需要在新建项目中引入 GEL 设计系统的开发者，尤其是使用 Tailwind CSS v4 的项目。支持单品牌与多品牌应用，多品牌场景可通过 data-brand 属性动态切换。

限制

当前版本中深色模式（data-theme="dark"）已被禁用。其余限制信息暂未提供。

技能介绍

用途