braid-design-system
v33.3.0
Published
Themeable design system for the SEEK Group
Downloads
16,167
Readme
Setup
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>
);
Local Development
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
Building with Braid
Styling with Vanilla Extract
Braid uses Vanilla Extract for styling, enabling the authoring of CSS in TypeScript in a way that can be statically extracted at build time, generating reusable atomic CSS classes.
This requires use of a bundler plugin to collect the extracted styles (see Vanilla Extract’s integration documentation), either injecting them into the document or a separate CSS stylesheet.
At SEEK this is done via sku as part of the build process.
Assertions
To ensure correct usage of its components, Braid performs some precondition and invariant checking at runtime using the assert library.
To prevent these checks from being included in production builds and distrupting the end user experience, it is recommended that assert
calls are stripped at build time using the unassert library.
At SEEK this is done via sku as part of the build process via Babel with the babel-plugin-unassert plugin.
Dev-time Warnings
Additionally, Braid provides dev and build time warnings for softer communications such as deprecations — conditionally logging to the console based on the specified process.env.NODE_ENV
, expecting an environment of either development
or production
.
To prevent these checks from being included in production, it is recommended to strip them from the production bundle.
At SEEK this is done via sku as part of the build process, replacing process.env.NODE_ENV
with the configured environment as a string
via the webpack optimization configuration.
This gives the bundler the opportunity to remove the dead code at build time, if configured as part of the minification process.
Contributing
Refer to CONTRIBUTING.md.
Thanks
Chromatic for providing component screenshot testing, powered by Storybook.
License
MIT.