seek-oss/braid-design-system

Themeable design system for the SEEK Group.

---

This guide is currently optimised for usage with sku, since it's configured to support Braid out of the box. If your project has a custom build setup, you'll need some extra guidance from project contributors to configure your bundler.

In your sku project, first install this library:

$ npm install --save braid-design-system

At the very top of your application, import the reset, required theme and the BraidProvider component.

WARNING: The reset styles must be imported first to avoid CSS ordering issues.

For example:

import 'braid-design-system/reset'; // <-- Must be first
import apacTheme from 'braid-design-system/themes/apac';
import { BraidProvider, Text } from 'braid-design-system';
// ...etc.

Finally, render the BraidProvider component, providing the imported theme via the theme prop:

import 'braid-design-system/reset';
import apacTheme from 'braid-design-system/themes/apac';
import { BraidProvider, Text } from 'braid-design-system';

export default () => (
  <BraidProvider theme={apacTheme}>
    <Text>Hello World!</Text>
  </BraidProvider>
);

If you're rendering within the context of another application, you may want to opt out of the provided body styles, which set the background color and reset margin and padding:

<BraidProvider theme={apacTheme} styleBody={false}>
  <Text>Hello World!</Text>
</BraidProvider>

If you'd like to customise the technical implementation of all Link and TextLink components from Braid, you can pass a custom component to the linkComponent prop on BraidProvider. For example, if you wanted to ensure that all relative links are React Router links:

import React from 'react';
import { Link as ReactRouterLink } from 'react-router-dom';
import { BraidProvider, makeLinkComponent } from 'braid-design-system';
import wireframe from 'braid-design-system/themes/wireframe';

// First create the custom link implementation:
const CustomLink = makeLinkComponent(({ href, ...restProps }, ref) =>
  href[0] === '/' ? (
    <ReactRouterLink ref={ref} to={href} {...restProps} />
  ) : (
    <a ref={ref} href={href} {...restProps} />
  ),
);

// Then pass it to BraidProvider:
export const App = () => (
  <BraidProvider theme={wireframe} linkComponent={CustomLink}>
    ...
  </BraidProvider>
);

This project uses pnpm for development dependencies.

Installing with pnpm is required to ensure dependencies match the current pnpm-lock.yaml.

$ pnpm install
$ pnpm start

Start a local Storybook server:

$ pnpm storybook

Refer to CONTRIBUTING.md.

Chromatic for providing component screenshot testing, powered by Storybook.

MIT.