Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/seek-oss/braid-design-system
Themeable design system for the SEEK Group
https://github.com/seek-oss/braid-design-system
babel css-modules design-system front-end react style-guide webpack
Last synced: 7 days ago
JSON representation
Themeable design system for the SEEK Group
- Host: GitHub
- URL: https://github.com/seek-oss/braid-design-system
- Owner: seek-oss
- License: mit
- Created: 2018-10-01T00:27:10.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-01-08T00:23:56.000Z (13 days ago)
- Last Synced: 2025-01-09T21:44:40.114Z (11 days ago)
- Topics: babel, css-modules, design-system, front-end, react, style-guide, webpack
- Language: TypeScript
- Homepage: https://seek-oss.github.io/braid-design-system
- Size: 93.9 MB
- Stars: 1,525
- Watchers: 15
- Forks: 100
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-list - braid-design-system - oss | 1020 | (TypeScript)
README
Themeable design system for the SEEK Group.
[![npm](https://img.shields.io/npm/v/braid-design-system.svg?style=for-the-badge)](https://www.npmjs.com/package/braid-design-system)
## 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:
```bash
$ 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:
```js
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:
```js
import 'braid-design-system/reset';
import apacTheme from 'braid-design-system/themes/apac';
import { BraidProvider, Text } from 'braid-design-system';export default () => (
Hello World!
);
```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:
```js
Hello World!
```
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](https://reacttraining.com/react-router/) links:
```tsx
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] === '/' ? (
) : (
),
);// Then pass it to BraidProvider:
export const App = () => (
...
);
```## Local Development
This project uses [pnpm](https://pnpm.io/) for development dependencies.
Installing with `pnpm` is required to ensure dependencies match the current [pnpm-lock.yaml](./pnpm-lock.yaml).
```bash
$ pnpm install
$ pnpm start
```Start a local Storybook server:
```bash
$ 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.
[Vanilla Extract]: https://vanilla-extract.style/
[integration]: https://vanilla-extract.style/documentation/getting-started### 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](https://www.npmjs.com/package/unassert) library.
At SEEK this is done via [sku] as part of the build process via [Babel] with the [babel-plugin-unassert] plugin.
[assert]: https://www.npmjs.com/package/assert
[unassert]: https://www.npmjs.com/package/unassert
[Babel]: https://babeljs.io/
[babel-plugin-unassert]: https://github.com/unassert-js/babel-plugin-unassert### 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.[webpack optimization]: https://webpack.js.org/configuration/optimization/#optimizationnodeenv
## Contributing
Refer to [CONTRIBUTING.md](./CONTRIBUTING.md).
## Thanks
[Chromatic](https://www.chromaticqa.com) for providing component screenshot testing, powered by [Storybook](https://storybook.js.org/).
## License
MIT.
[sku]: https://github.com/seek-oss/sku