{
  "markdown": "### Previous Version\n\nIf you are looking for information/source code for version 0.x you can find it [here](https://github.com/WestpacGEL/GEL-next/tree/version/0.x). It is recommened you upgrade to 1.0 at your earliest convenience.\n\n- [Storybook](https://gel-next-storybook-git-version-0x-westpacgel.vercel.app/?path=/story/attention--attention).\n- [Site](https://gel-next-site-git-version-0x-westpacgel.vercel.app/)\n\n## Getting Started\n\nThis section describes how to get started with Westpac GEL.\n\n### What is GEL?\n\nThe 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.\n\nYou can read more about GEL in [https://gel.westpacgroup.com.au/articles/what-is-GEL](https://gel.westpacgroup.com.au/articles/what-is-GEL)\n\n### Pre-requisites\n\nAll GEL components have a couple of dependencies so please ensure the following are installed using your preferred package manager (`npm`, `yarn` or `pnpm`):\n\n```\nnpm i react@^18.2.0\nnpm i -D tailwindcss @tailwindcss/postcss postcss\n```\n\nGEL is using [Tailwind](https://tailwindcss.com/) for styling. Visit the [Tailwind docs](https://tailwindcss.com/docs/installation/framework-guides) and follow the relevant instructions for installation.\n\n### Agent Skills\n\nWe have some skills available to use with AI agents:\n\n- `using-westpac-ui` - **Highly recommended**: Provides general context for all components in the library, has reference material generated from the [docs site](https://gel.westpacgroup.com.au/design-system/wbc) content and usage examples of components.\n- `installing-westpac-ui` - **Optional**: Skill that provides context for installing GEL Next in a fresh project.\n- `migrating-to-westpac-ui-v1` - **Optional**: Skill that provides context for migrating from pre-1.0 GEL Next to >1.0 GEL Next\n\n#### Skill Installation\n\nThe recommended way to install skills is to use the following command, from this you can select the skills you wish to install:\n`npx skills add https://github.com/WestpacGEL/GEL-next/tree/main/.agents/skills/consumer/`\n\nIf you can't use the `skills` cli for any reason you can just retrieve the skills manually from the [GEL Next GitHub](https://github.com/WestpacGEL/GEL-next/tree/main/.agents/skills/consumer/)\n\n### Installation\n\nThe GEL is separated out into 2 packages.\n\n- `@westpac/ui` - React components\n- `@westpac/style-config` - Tailwind/CSS/tokens\n\nInstall the GEL packages using preferred package manager (`npm`, `yarn` or `pnpm`):\n\n```\nnpm i @westpac/ui @westpac/style-config\n```\n\nCreate a `postcss.config.mjs` on the root of your application as follows.\n\n```js\nimport { postcssConfig } from '@westpac/style-config/postcss';\n\nexport default postcssConfig;\n```\n\nIn your main CSS file, import the Tailwind directives and GEL styles:\n\n```css\n@import 'tailwindcss';\n/* Tailwind setup */\n@import '@westpac/style-config/tailwind';\n/* Register GEL components source for tailwind */\n@source \"<relative_path>/node_modules/@westpac/ui/src\";\n```\n\nFor brand theming, import the required brand stylesheets:\n\n```css\n@import '@westpac/style-config/themes/wbc';\n@import '@westpac/style-config/themes/stg';\n@import '@westpac/style-config/themes/bom';\n@import '@westpac/style-config/themes/bsa';\n```\n\nIf you have initialized your project with Nx build system follow the official [Nx tailwind documentation](https://nx.dev/recipes/react/using-tailwind-css-in-react#manual-setup-instructions) to configure tailwind.\n\n### Theming\n\nTo switch between brands, set the `data-brand` attribute on a parent element:\n\n```html\n<div data-brand=\"wbc\">\n  <!-- Your app content -->\n</div>\n```\n\nNOTE: Do not include code to activate dark mode if it hasn't been approved for your team yet\n\nTo toggle between light and dark mode, set the `data-theme` attribute:\n\n```html\n<div data-brand=\"wbc\" data-theme=\"dark\">\n  <!-- Your app content -->\n</div>\n```\n\n### Usage\n\n#### Using brands\n\nAdd 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.\n\nFollowing example shows adding `wbc` brand. You can add other valid brand names such as `stg`, `bom`, `bsa` etc. as the value.\n\n```html\n<!doctype html>\n<html lang=\"en\" data-brand=\"wbc\">\n  ...\n</html>\n```\n\nNOTE: Do not include code to activate dark mode if it hasn't been approved for your team yet\n\nFor theme modes (light/dark), use the `data-theme` attribute:\n\n```html\n<!doctype html>\n<html lang=\"en\" data-brand=\"wbc\" data-theme=\"light\">\n  ...\n</html>\n```\n\n**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.\n\nNow you can start using the GEL components in your `React.js` application. The following examples show how to use the `Button` component.\n\nFor detailed documentation refer to [https://gel.westpacgroup.com.au/design-system](https://gel.westpacgroup.com.au/design-system).\n\n### Tokens\n\nAll brand tokens are also exported in the [W3C design tokens format](https://www.designtokens.org/tr/drafts/format/)\n\n```js\nimport { ALL_BRANDS } from '@westpac/style-config/tokens';\n```\n\n#### Tokens usage with Tailwind\n\nAll 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`\n\nAll available color tokens can be viewed in the [GEL storybook](https://gel-next-storybook-westpacgel.vercel.app/?path=/docs/foundation-colours--docs).\n\n### Brand fonts\n\nIn 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.\n\n```css\n/* BOM fonts */\n@font-face {\n  src:\n    url('/fonts/lineto-brown-pro-light.woff2') format('woff2'),\n    url('/fonts/lineto-brown-pro-light.woff') format('woff');\n  font-family: 'Brown Pro';\n  font-weight: 100 300;\n  font-style: normal;\n}\n@font-face {\n  src:\n    url('/fonts/lineto-brown-pro-regular.woff2') format('woff2'),\n    url('/fonts/lineto-brown-pro-regular.woff') format('woff');\n  font-family: 'Brown Pro';\n  font-weight: 400 600;\n  font-style: normal;\n}\n@font-face {\n  src:\n    url('/fonts/lineto-brown-pro-bold.woff2') format('woff2'),\n    url('/fonts/lineto-brown-pro-bold.woff') format('woff');\n  font-family: 'Brown Pro';\n  font-weight: 700 900;\n  font-style: normal;\n}\n\n/* BSA fonts */\n@font-face {\n  src:\n    url('/fonts/Aller_Lt.woff2') format('woff2'),\n    url('/fonts/Aller_Lt.woff') format('woff');\n  font-family: 'Aller';\n  font-weight: 100 600;\n  font-style: normal;\n}\n@font-face {\n  src:\n    url('/fonts/Aller_Bd.woff2') format('woff2'),\n    url('/fonts/Aller_Bd.woff') format('woff');\n  font-family: 'Aller';\n  font-weight: 700 900;\n  font-style: normal;\n}\n\n/* STG fonts */\n@font-face {\n  src:\n    url('/fonts/dragonbold-bold-webfont.woff2') format('woff2'),\n    url('/fonts/dragonbold-bold-webfont.woff') format('woff');\n  font-family: 'Dragon Bold';\n  font-weight: 100 900;\n  font-style: normal;\n}\n\n/* WBC fonts */\n@font-face {\n  src:\n    url('/fonts/Westpac-Bold-v2.007.woff2') format('woff2'),\n    url('/fonts/Westpac-Bold-v2.007.woff') format('woff');\n  font-family: 'Westpac';\n  font-weight: 100 900;\n  font-style: normal;\n}\n```\n\n#### Individual package import\n\nWe recommended the individual package import approach if you have issues with [Tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking).\n\n```tsx\nimport { Button } from '@westpac/ui/button';\n\nexport default function SampleApp() {\n  return (\n    <section>\n      <div className=\"space-x-4 mb-2\">\n        <Button look=\"primary\">Pay here</Button>\n      </div>\n    </section>\n  );\n}\n```\n\n#### Mono package import\n\nModern bundlers like [Vite](https://vitejs.dev/) and latest [webpack](https://webpack.js.org/) will automatically detect the individual components and only bundle the components you use.\n\nHowever, use this approach with caution as it may cause issues with [Tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) since not all bundlers have this advanced capability.\n\n```tsx\nimport { Button } from '@westpac/ui';\n\nexport default function SampleApp() {\n  return (\n    <section>\n      <div className=\"space-x-4 mb-2\">\n        <Button look=\"primary\">Pay here</Button>\n      </div>\n    </section>\n  );\n}\n```\n\n### Unit testing\n\nWe recommend [Vitest](https://vitest.dev/) for unit testing since [Vitest](https://vitest.dev/guide/why.html) natively supports [ES modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).\n\nIf you are using [Jest](https://jestjs.io/) for unit testing, you might encounter some issues since [Jest](https://jestjs.io/docs/ecmascript-modules) does not support [ES modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) by default. Therefore, you will need to make following configuration changes.\n\nUpdate the `package.json` file if you have initialized your project with [Create React App](https://create-react-app.dev/).\n\n```json\n{\n  \"scripts\": {\n    \"test\": \"node scripts/test.js --transformIgnorePatterns \\\"node_modules/(?!(@westpac/ui)/)\\\"\"\n  }\n}\n```\n\nUpdate the `jest.config.js` file if you have initialized your project with [Nx build system](https://nx.dev/) and [Babel](https://babeljs.io/).\n\n```js\n{\n   transform: {\n     '^.+\\\\.[tj]sx?$': ['babel-jest', { presets: ['@nrwl/react/babel'] }]\n   },\n   transformIgnorePatterns: ['node_modules/(?!(@westpac/ui|@westpac/style-config))']\n}\n```\n\n### Codemods\n\nCodemods are provided to help migrate your codebase when GEL introduces breaking changes or API updates.\n\n#### Running a codemod\n\nWe use [jscodeshift](https://github.com/facebook/jscodeshift) to run codemods.  \nTo apply a codemod, install `jscodeshift` if you don’t already have it:\n\n```bash\nnpm install -g jscodeshift\n```\n\nThen run the codemod against your source files. For example:\n\n```bash\nnpx jscodeshift -t ./codemods/update-date-picker.js src/\n```\n\n-t points to the codemod file.\n\nsrc/ is the folder you want to transform (adjust as needed).\n\nExample\n\n```bash\nnpx jscodeshift --parser=tsx -t node_modules/@westpac/ui/scripts/codemods/gel-tokens-tailwind-v1.cjs <path>/**/*.tsx\n```\n\nThis will apply the gel-tokens-v1 codemod to all .tsx files in your project.\n\n## Documentation\n\nVisit [https://gel.westpacgroup.com.au/design-system](https://gel.westpacgroup.com.au/design-system) to view the full documentation.\n\n## Contributing to GEL\n\n### Developing\n\n- The development branch is `develop`.\n- All pull requests should be opened against `develop`.\n- The changes on the `develop` branch are published to the `preview` environment.\n\n#### To develop locally (common for all the packages and apps)\n\n1. Install Node.js 22.x or above. We recommend [https://github.com/nvm-sh/nvm](https://github.com/nvm-sh/nvm) to install Node.js.\n\n2. Clone the Next.js repository:\n   ```\n   git clone --single-branch --branch develop git@github.com:WestpacGEL/GEL-next.git\n   ```\n3. Create a new branch:\n   ```\n   git checkout -b MY_BRANCH_NAME origin/develop\n   ```\n4. Enable pnpm:\n   ```\n   corepack enable pnpm\n   ```\n5. Install the dependencies with:\n   ```\n   pnpm install\n   ```\n6. Start developing and watch for code changes:\n   ```\n   pnpm dev\n   ```\n7. Run the unit tests with:\n   ```\n   pnpm test\n   ```\n8. Fix formatting and linting with:\n   ```\n   pnpm format:fix && pnpm lint:fix\n   ```\n9. Check formatting and linting with:\n   ```\n   pnpm format && pnpm lint\n   ```\n10. Check TypeScript compatibility with:\n\n```\npnpm check-types\n```\n\n11. You can build packages and apps with:\n\n```\npnpm build\n```\n\n12. You can add a changeset with:\n\n```\npnpm changeset\n```\n\n##### To develop a GEL UI component locally\n\n1. Change the working directory with:\n   ```\n   cd packages/ui\n   ```\n2. Create a new `GEL` component with:\n   ```\n   cd packages/ui\n   pnpm generate:component\n   ```\n3. Start storybook with:\n   ```\n   pnpm build && pnpm storybook\n   ```\n4. Run the unit tests in watch mode with:\n   ```\n   pnpm test:watch\n   ```\n   When your changes are finished, commit them to the branch and push it to origin.\n",
  "bytes": 12440,
  "sha": "19c8f1be055fe8325d1f4278ad60add010022af8bb6122d8c407af4a15b905c1",
  "repo_slug": "westpacgel/gel-next",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_westpacgel_gel_next_using_westpac_ui_d3416ac2/readme"
}