This repository is no longer maintained. The new GEL design system can be found here

GEL

For the docs for the design system please go to

This repository consists of the following parts:

• /brands/* and /components/* - The react design system components (published to npm)
• /website - The nextjs website
• /website-backend - The keystonejs instance
• /helpers/* - Some utility scripts
• /nginx/* - The backend nginx configuration

Content

• Getting Started
• Development Workflow
• Design System
• Blender support

Getting Started

This repo is a monorepo.
Learn more about monorepos at https://monorepo.guide/.

To run this repo locally please use yarn.

cd path/to/repo
yarn && yarn prepare

Development Workflow

Here you’ll find our contributing guidelines as well as how to add or edit a component.

Contributing

To contribute to this repo please follow the steps listed below:

1. Fork the repository.

Fork the repo and checkout the develop branch.

2. Install the Dependencies.

Install the project dependencies with:

cd path/to/repo
yarn

3. Implement changes.

When implementing your changes please ensure that you follow modern web development best practices.

4. Format & Generate prop-types

Format your changes and Generate your Prop-Types for documentation:

yarn prop-types && yarn format

5. Test

Run the Format, Unit and Integration Tests with:

yarn test

6. Add a Changeset

Any Component changes will require a changeset
(This is how we manage versioning and changelogs).

To create a changeset run:

yarn changeset add

Make sure to follow SemVer convention and write a meaningful description of the change in the changelog.

7. Create a Pull Request

• Create a PR and target the “develop” branch.
• Write a meaningful title and description for your PR.
• Ensure the PR passess the GitHub Workflow.

8. Review

Wait for your changes to be reviewed and approved.

9. Merge

The Maintainer will merge the Pull Request into the Develop branch.

10. Publish

The Maintainer will publish changes to NPM.

Adding a new component

To add a new component (aka package), run the below command from the root of the project and then follow the prompts:

yarn new my-component-name

Note: replace my-component-name with the component you wish to add.

This will create a new entry in the /components directory with all of the files you need to get started and with all dependencies installed. Please note that this component will be TypeScript.

Editing an existing component

To edit a component, including if you’ve just added one using the steps above, use the below command from the root of the project:

yarn dev my-component-name

Note: replace my-component-name with the component you wish to run.

This component can now be viewed on http://localhost:8080/.

File structure

NPM scripts

Design System

The design system components are spread between two folders:

.
├── brands/     # The brand components
└── components/ # The design system components including core

There are two different ways you can run the components locally:

1. Component build
2. Docs build

Some high level decisions

• All components use named exports as the default, no default exports
• All brands components will have a default export containing the “tokens” objects in addition to the named exports of each.
• Fonts can’t be shipped with npm so the tokens only define the css declarations for the fonts
• For css-in-js we use jsx imported from @westpac/core and never depend on emotion directly other than inside core itself

Theming / Multi-brand

Multi-brand will be achieved by added a brand package that will be passed to the <GEL></GEL> component

import { GEL } from '@westpac/core';
import brand from '@westpac/WBC';
export const App = () => <GEL brand={brand}>Your app</GEL>;

The brand package includes tokens and overrides and will be available to all packages inside the <GEL></GEL> wrapper via context.
This allows us to be as consistent as can be within the same app.
It also separates out all things to do with theming into a single package.
The brand package does not need to know anything about its components.
But it can opt in.

Overrides

A consumer may choose to override a component in its build.
This can happen by adding the overrides into the same namespace as the component you wish to override.

import { Tabcordion } from '@westpac/tabcordion';
import { GEL } from '@westpac/core';
import brand from '@westpac/wbc';
brand['@westpac/tabcordion'].TabItem.styles = ( styles, state ) => { ...styles, border: 'red solid 2px' };
brand['@westpac/tabcordion'].TabRow.component = <TabRow ></TabRow>;
export const App = () => (
    <GEL brand={brand}>
        All instances of the <Tabcordion></Tabcordion> now include the override specified above.
        No matter how many there are.
    </GEL>
);

There may also a need to add an override only to a single instance of the component.
In that case you may add the override to the component directly via the overrides prop each component has.

import { Tabcordion } from '@westpac/tabcordion';
import { GEL } from '@westpac/core';
import brand from '@westpac/wbc';
brand['@westpac/tabcordion'].Tabcordion.styles = ( styles, state ) => { ...styles, border: 'red solid 2px' };
const overrides = {
    Tabcordion: {
        styles: ( styles, state ) => { ...styles, border: 'blue solid 2px' },
    },
};
export const App = () => (
    <GEL brand={brand}>
        <Tabcordion></Tabcordion> with red border
        <Tabcordion overrides={overrides} ></Tabcordion> with blue border
        <Tabcordion></Tabcordion> with red border
    </GEL>
);

(💡 Overrides will be reconciled as a cascade from less-specific to most-specific.)

Every single component (including root component) have three items in their override object:

overrides = {
    [name]: {
        styles: (base-styles, state-props) => styles,
        component: <React.Component></React.Component>
        attributes: (base-attributes, state-props) => Object,
    }
}

Data driven API

Components that are made up by other components like list, breadcrumb, button-group, input-group etc can be solely driven by the data prop.
We also offer declarative APIs in-case a consumer wants to wrap a component.

<Breadcrumb>
    <Crumb href="#/" text="Home" ></Crumb>
    <Crumb href="#/personal-banking/" text="Personal" ></Crumb>
    <Crumb href="#/credit-cards/" text="Credit cards" ></Crumb>
</Breadcrumb>

Is the same as:

<Breadcrumb
    data={[
        { href: '#/', text: 'Home' },
        { href: '#/personal-banking/', text: 'Personal' },
        { href: '#/credit-cards/', text: 'Credit cards' },
    ]}
/>

How we handle focus state

We use the useFocus hook in the GEL component.
You can @wilkowskidom/how-i-learned-to-stop-worrying-and-love-the-outline-7a35b3b49e7">read about the focus hook on medium.
The GEL also adds the global focus styling from our PACKS.focus token pack.
If you need to add it to something use:

':focus': {
    ...PACKS.focus,
},

However if you need a focus state that will persist across mouse users do something like this:

const { PACKS } = useBrand();
const focus = { ...PACKS.focus };
focus.outline += ' !important'; // adding `!important` will make sure the focus persists
<Component
    css={{
        ':focus': { ...focus },
    }}
></Component>;

Component build

This build is running all the components examples/demos directly and nothing else.
It’s for development of a component and for testing it.

You run it via:

cd path/to/root/of/repo
yarn dev [component name]

Blender support

The blender can generate human readable html and css from react and emotion components.

Read more about how you add blender support in the blender README.md.