| name | installing-westpac-ui |
| description | Guides setup and installation of @westpac/ui and @westpac/style-config in a new project. Use when setting up GEL, installing the design system, configuring Tailwind CSS, theming, or brand fonts. |
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';
@import '@westpac/style-config/themes/wbc';
@source "./node_modules/@westpac/ui/src";
- Enable Brand Theming
Add the data-brand attribute to a parent element in your HTML:
<html lang="en" data-brand="wbc">
</html>
Or on any container element:
<div data-brand="wbc">
</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}>{}</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:
@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;
}
@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;
}
@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;
}
@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:
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:
module.exports = {
root: true,
extends: ['@westpac/eslint-config/nextjs'],
rules: {
'@next/next/no-html-link-for-pages': 0,
},
};
Resources
