If you are looking for information/source code for version 0.x you can find it here. It is recommened you upgrade to 1.0 at your earliest convenience.
This section describes how to get started with Westpac GEL.
The Global Experience Language is our single source of truth, providing everything you need to deliver our brand promises and create consistent, coherent customer experiences across our entire digital landscape faster, and with less effort.
You can read more about GEL in https://gel.westpacgroup.com.au/articles/what-is-GEL
All GEL components have a couple of dependencies so please ensure the following are installed using your preferred package manager (npm, yarn or pnpm):
npm i react@^18.2.0
npm i -D tailwindcss @tailwindcss/postcss postcss
GEL is using Tailwind for styling. Visit the Tailwind docs and follow the relevant instructions for installation.
The GEL is separated out into 2 packages.
@westpac/ui- React components@westpac/style-config- Tailwind/CSS/tokens
Install the GEL packages using preferred package manager (npm, yarn or pnpm):
npm i @westpac/ui @westpac/style-config
Create a postcss.config.mjs on the root of your application as follows.
import { postcssConfig } from '@westpac/style-config/postcss';
export default postcssConfig;In your main CSS file, import the Tailwind directives and GEL styles:
@import 'tailwindcss';
/* Tailwind setup */
@import '@westpac/style-config/tailwind';
/* Register GEL components source for tailwind */
@source "<relative_path>/node_modules/@westpac/ui/src";For brand theming, import the required brand stylesheets:
@import '@westpac/style-config/themes/wbc';
@import '@westpac/style-config/themes/stg';
@import '@westpac/style-config/themes/bom';
@import '@westpac/style-config/themes/bsa';If you have initialized your project with Nx build system follow the official Nx tailwind documentation to configure tailwind.
To switch between brands, set the data-brand attribute on a parent element:
<div data-brand="wbc">
<!-- Your app content -->
</div>NOTE: Do not include code to activate dark mode if it hasn't been approved for your team yet
To toggle between light and dark mode, set the data-theme attribute:
<div data-brand="wbc" data-theme="dark">
<!-- Your app content -->
</div>Add a custom attribute tag data-brand="brand_name" to html tag. Note that instead of adding the custom attribute to html tag, you can add it to the parent tag of your application as well.
Following example shows adding wbc brand. You can add other valid brand names such as stg, bom, bsa etc. as the value.
<!doctype html>
<html lang="en" data-brand="wbc">
...
</html>NOTE: Do not include code to activate dark mode if it hasn't been approved for your team yet
For theme modes (light/dark), use the data-theme attribute:
<!doctype html>
<html lang="en" data-brand="wbc" data-theme="light">
...
</html>NOTE: There are some components that use portals Modal, BottomSheet, AutoComplete. These components will default their portal to where you add your data-brand attribute tag so these components can make use of branding. This can be overridden using their portalContainer props if you require the portal to be located elsewhere.
Now you can start using the GEL components in your React.js application. The following examples show how to use the Button component.
For detailed documentation refer to https://gel.westpacgroup.com.au/design-system.
All brand tokens are also exported in the W3C design tokens format
import { ALL_BRANDS } from '@westpac/style-config/tokens';All brand tokens have been mapped to a color theme variable in the tailwind config and can be used in the relevant tailwind classname e.g. bg-surface-mono text-text-body
All available color tokens can be viewed in the GEL storybook.
In order to use brand-fonts add the relevant font face declarations from the below example and update the src to the font file locations in your application.
/* 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;
}We recommended the individual package import approach if you have issues with Tree shaking.
import { Button } from '@westpac/ui/button';
export default function SampleApp() {
return (
<section>
<div className="space-x-4 mb-2">
<Button look="primary">Pay here</Button>
</div>
</section>
);
}Modern bundlers like Vite and latest webpack will automatically detect the individual components and only bundle the components you use.
However, use this approach with caution as it may cause issues with Tree shaking since not all bundlers have this advanced capability.
import { Button } from '@westpac/ui';
export default function SampleApp() {
return (
<section>
<div className="space-x-4 mb-2">
<Button look="primary">Pay here</Button>
</div>
</section>
);
}We recommend Vitest for unit testing since Vitest natively supports ES modules.
If you are using Jest for unit testing, you might encounter some issues since Jest does not support ES modules by default. Therefore, you will need to make following configuration changes.
Update the package.json file if you have initialized your project with Create React App.
{
"scripts": {
"test": "node scripts/test.js --transformIgnorePatterns \"node_modules/(?!(@westpac/ui)/)\""
}
}Update the jest.config.js file if you have initialized your project with Nx build system and Babel.
{
transform: {
'^.+\\.[tj]sx?$': ['babel-jest', { presets: ['@nrwl/react/babel'] }]
},
transformIgnorePatterns: ['node_modules/(?!(@westpac/ui|@westpac/style-config))']
}Codemods are provided to help migrate your codebase when GEL introduces breaking changes or API updates.
We use jscodeshift to run codemods.
To apply a codemod, install jscodeshift if you don’t already have it:
npm install -g jscodeshiftThen run the codemod against your source files. For example:
npx jscodeshift -t ./codemods/update-date-picker.js src/-t points to the codemod file.
src/ is the folder you want to transform (adjust as needed).
Example
npx jscodeshift --parser=tsx -t node_modules/@westpac/ui/scripts/codemods/gel-tokens-tailwind-v1.cjs <path>/**/*.tsxThis will apply the gel-tokens-v1 codemod to all .tsx files in your project.
Visit https://gel.westpacgroup.com.au/design-system to view the full documentation.
- The development branch is
develop. - All pull requests should be opened against
develop. - The changes on the
developbranch are published to thepreviewenvironment.
-
Install Node.js 22.x or above. We recommend https://github.com/nvm-sh/nvm to install Node.js.
-
Clone the Next.js repository:
git clone --single-branch --branch develop git@github.com:WestpacGEL/GEL-next.git -
Create a new branch:
git checkout -b MY_BRANCH_NAME origin/develop -
Enable pnpm:
corepack enable pnpm -
Install the dependencies with:
pnpm install -
Start developing and watch for code changes:
pnpm dev -
Run the unit tests with:
pnpm test -
Fix formatting and linting with:
pnpm format:fix && pnpm lint:fix -
Check formatting and linting with:
pnpm format && pnpm lint -
Check TypeScript compatibility with:
pnpm check-types
- You can build packages and apps with:
pnpm build
- You can add a changeset with:
pnpm changeset
- Change the working directory with:
cd packages/ui - Create a new
GELcomponent with:cd packages/ui pnpm generate:component - Start storybook with:
pnpm build && pnpm storybook - Run the unit tests in watch mode with:
When your changes are finished, commit them to the branch and push it to origin.
pnpm test:watch