@westpac/icon v2.3.0

GEL

The design system for Westpac GEL

npm scripts

root level

component level

Monorepo

.
├── LICENSE
├── README.md
├── package.json
├── yarn.lock
│
├── helper/
│   ├── example/
│   │   ├── index.js          # example wrapper for `bolt dev`
│   │   └── webpack.config.js # dynamic webpack config to run the `bolt dev` task
│   ├── docz/                 # Docz files to style the docs
│   │   ├── theme.js
│   │   └── wrapper.js
│   ├── tester.js             # Helps cypress testing of each component
│   └── cli.js                # helper file for cli like adding a new module
│
├── components/               # all ds components that will be published
│   ├── component1/
│   ├── component2/
│   └── component3/
│
├── brands/
│   ├── WBC/
│   │   ├── LICENSE
│   │   ├── README.md
│   │   ├── package.json
│   │   ├── index.js          # only for exports
│   │   ├── fonts/            # design tokens files
│   │   └── tokens/           # font files
│   ├── STG/
│   │   └── etc
│   └── BOM/
│       └── etc
│
├── examples/                 # complex examples like templates
│   ├── demo1/                # for testing multiple components
│   │   └── tests/            # each have test folders
│   ├── demo2/
│   └── demo3/
│
└── docs/                     # the built out files for the documentation

Component

.
├── README.md
├── LICENSE
├── package.json            # scope: `@westpac/`
│
├── src/                    # all the source
│   ├── index.js            # only for exports
│   ├── ComponentX.js       # only for the components, can be multiple files
│   ├── styled.js           # only for styles [optional]
│   ├── vanilla.js          # only for static site generation
│   └── _util.js            # for reused logic within the component [optional]
│
├── docs/                   # documentation for docz later
│   ├── thing1.mdx          # documenting features etc
│   └── thing2.mdx
│
├── examples/               # the demo folder is for seeing the components in action
│   ├── 00-example.js       # show-case props and variations
│   ├── 10-example.js       # all files not starting with a dot or an underscore
│   ├── 20-example.js       # will be processes with `bolt dev`
│   └── _util.js            # for reused logic within the examples [optional]
│
└── tests/                  # test includes all tests
    ├── unit/
    │   └── unit.spec.js    # jest test file for unit tests
    └── integration/
        └── test.cypress.js # cypress test file for integration tests

Decisions

• All scripts are run through the bolt command
• The helpers/ folder will include all helpers for builds/docs/testing
• We have two different example / doc concerns:
  1. Examples: they are for building components locally and to explain code
  2. Docs: this is a website that will be published for documenting APIs to devs (https://westpacgel.github.io/GEL/)

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

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

• Tokens and everything regarding consistent branding will be contained in the brand packages in brands/*

• Tokens will include at least the four categories:
  • breakpoints
  • colors
  • spacing
  • typography
• Brands will only have a default export containing the "tokens" object.
• All components (not brand packages) have at least one named export

• Each component has local tokens that can be overwritten with the object passed into <GEL/>

  import { GEL } from '@westpac/core';
  import brand from '@westpac/WBC';
  
  brand['@westpac/tabcordion'].heading.space = '2rem';
  brand['@westpac/tabcordion'].components.TabRow = <TabRow />;
  
  export const App = () => <GEL brand={brand}>Your app</GEL>;

• Each package can be addressed by its name as the key in the tokens

• The example/ folder is for documenting composition of several components together e.g. templates
• Fonts can't be shipped with npm so the tokens only define the path to the fonts
• css-in-js emotion will be used with the jsx pragma and babel plugin
• For css-in-js we use jsx by importing from @westpac/core and never depend on emotion directly other than inside core itself

Naming convention for files inside components

TODO

• create a GEL brand
• build out root examples
• create local default tokens
• add render props for visual internal components
• add helper for making new component
• make playground and docz multibrand