westpacgel Installing @westpac/ui
Step-by-step setup for new projects using the GEL design system.
When to Use
Reference this guide when a user wants to set up the GEL design system in a new project. This includes installing the necessary packages, configuring Tailwind CSS, setting up theming with brand tokens, and adding brand fonts.
Steps
- Install Packages
GEL is split into two packages:
@westpac/ui— All design system components@westpac/style-config— Tailwind CSS themes and design tokens
npm i @westpac/ui @westpac/style-config
- Install Tailwind CSS
GEL components are styled with Tailwind CSS v4. Follow the Tailwind CSS installation instructions.
npm i tailwindcss @tailwindcss/postcss postcss
Create postcss.config.mjs:
import { postcssConfig } from '@westpac/style-config/postcss';
export default postcssConfig;
- Set Up Styles
In your main CSS file, add these imports:
@import 'tailwindcss';
@import '@westpac/style-config/tailwind'; /* GEL theme config (typography, spacing, etc.) */
@import '@westpac/style-config/themes/wbc'; /* Brand color tokens — import each brand you need */
@source "./node_modules/@westpac/ui/src"; /* Enable Tailwind to scan component class names */
- Enable Brand Theming
Add the data-brand attribute to a parent element in your HTML:
<html lang="en" data-brand="wbc">
<!-- Your app content -->
</html>
Or on any container element:
<div data-brand="wbc">
<!-- Your app content -->
</div>
Available brands:
wbc— Westpac Banking Corporationstg— St.George Bankbom— Bank of Melbournebsa— BankSA
Import each brand's theme CSS that 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';
For multi-brand applications, dynamically switch with the data-brand attribute:
<div data-brand={currentBrand}>{/* Your app content */}</div>
Note: Dark mode (
data-theme="dark") is disabled in the current release.
- Brand Fonts
Add the relevant @font-face declarations and update src paths to your font file locations:
/* BOM fonts */
@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 fonts */
@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 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;
}
/* 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;
}
- ESLint Configuration (Ask user if they want to include this)
For Next.js projects:
// 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',
},
},
},
]);
For non-Next.js projects, you may need to disable certain Next.js-specific rules:
// .eslintrc.js
module.exports = {
root: true,
extends: ['@westpac/eslint-config/nextjs'],
rules: {
'@next/next/no-html-link-for-pages': 0,
},
};