Braid hands you a design system and three build-time chores: strip the assertions, define NODE_ENV, generate before you lint
Themeable design system for the SEEK Group. For example, if you wanted to ensure that all relative links are React Router links: Local Development This project uses pnpm for development dependencies.
At a glance
- What is it?
- seek-oss/braid-design-system gives React applications a reset, a theme and a provider component, but its runtime checks, its extracted styles and its generated files only disappear from a production bundle if your build pipeline does three specific things.
- Who is it for?
- Braid is a working choice when your build already goes through sku, or when you are prepared to reproduce what sku does: a Vanilla Extract bundler plugin, a Babel pass that strips assert calls, and a compile time constant for process.env.NODE_ENV. It is a poor fit for a project that cannot touch its bundler configuration, since the setup guide itself says a custom build setup needs guidance from project contributors.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- seek-oss/braid-design-system1,574 ★ · +3
| Repository | 2026-07-28 | 2026-11-15 |
|---|---|---|
| seek-oss/braid-design-system | 1.6k | 1.6k |
3 Stars in the last 110 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The reset import has to be the first line or the cascade order breaks
Braid ships its own reset and it has to be imported above everything else in your application entry point. The documented reason is CSS ordering, and the example marks the line with an inline comment saying it must be first. The order of the other two imports is flexible by comparison: a theme module, then the named exports you need. Themes are addressed by path rather than by a single entry point, and the two visible in the examples are `braid-design-system/themes/seekJobs` and `braid-design-system/themes/wireframe`, the latter used by the custom link example. The provider sits at the root of your tree and takes the theme object through its `theme` prop, so the shape is one provider wrapping the application rather than a theme object passed down through context by hand.
import 'braid-design-system/reset'; // <-- Must be first
import seekJobsTheme from 'braid-design-system/themes/seekJobs';
import { BraidProvider, Text } from 'braid-design-system';
export default () => (
<BraidProvider theme={seekJobsTheme}>
<Text>Hello World!</Text>
</BraidProvider>
);The consequence for a code review is that import order in the entry file is load bearing, and an automated formatter that alphabetises imports can quietly move the reset below the theme.
styleBody is the switch that decides who owns the page background
The provider sets body styles by default: a background colour, plus a margin and padding reset. That is the right behaviour for an application that owns the whole page and the wrong behaviour when your React tree is rendered inside somebody else's document, which is why `styleBody` exists and defaults to opting in. Passing `styleBody={false}` leaves the body untouched, so the colours the surrounding application already established survive.
<BraidProvider theme={seekJobsTheme} styleBody={false}>
<Text>Hello World!</Text>
</BraidProvider>This is the only global document level side effect the setup steps mention, and it is worth deciding explicitly rather than by default. Two other provider level decisions come from the same place in the documentation. The theme is passed as an imported object rather than chosen by name, so switching between `seekJobs` and `wireframe` is an import change. And the guide notes that it is written for sku, since sku is configured to support Braid out of the box; a project with a custom build setup is told to ask project contributors for the bundler configuration, which is the point at which the next three sections start to matter.
linkComponent swaps the implementation of every Link and TextLink at once
Braid's link components delegate their technical implementation to something you can replace. The provider takes a `linkComponent` prop, and `makeLinkComponent` is the factory that builds one from a render function. The published example makes relative links React Router links and leaves everything else as a plain anchor, deciding by testing the first character of `href`, so the routing behaviour applies to same origin paths only and absolute links stay untouched.
import { Link as ReactRouterLink } from 'react-router';
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} />
),
);Two details are worth noting in that snippet. The forward ref argument is part of the contract, so a custom implementation that drops it silently loses ref forwarding. And the example on the README page stops inside the closing tag of the provider, so the render half that passes the component in is not shown there even though the surrounding text describes it. Substituting the component at the provider means every link in the tree changes behaviour at once, which is convenient and also means a component level override cannot be scoped to one region.
Runtime assertions only leave your bundle if Babel strips them
Braid checks its own preconditions and invariants at runtime using the `assert` library. Those checks are a development aid and they are not removed automatically, so the recommendation is to strip every `assert` call at build time with the `unassert` library, which the documentation places at sku through Babel with the `babel-plugin-unassert` plugin. If your build does not do this, the assertion code ships.
The second mechanism is separate and easier to miss. Dev time warnings, the softer messages such as deprecations, are logged conditionally on `process.env.NODE_ENV`, which the documentation expects to be either `development` or `production`. The recommendation is again to strip them, and the way it is done at SEEK is through webpack's optimization configuration, which replaces `process.env.NODE_ENV` with the configured environment as a string. The stated purpose is to give the bundler the chance to drop the dead code during minification. That means the substitution has to be configured as part of minification, not merely defined; define the constant without minifying and the branch survives, still evaluated at runtime, in the shipped file.
Vanilla Extract means your bundler needs a plugin, and that is the step sku absorbs
Styling in Braid is authored in TypeScript and extracted statically at build time by Vanilla Extract, which produces reusable atomic CSS classes rather than a runtime CSS in JavaScript layer. The documentation is explicit that this requires a bundler plugin to collect the extracted styles, and it gives two shapes for the result: injecting them into the document, or emitting a separate CSS stylesheet. At SEEK the collection happens as part of the sku build.
So the three production chores are related rather than independent. The plugin produces the stylesheet or the injected style block, Babel removes the assert calls, and the compile time constant removes the environment branches, and all three are described as steps sku performs inside its build. A team adopting the library onto a different toolchain has to reproduce them by hand, which is why the setup page declines to describe a custom bundler configuration and sends those projects to project contributors instead. The atomic class output also means class names are not a stable API to write selectors against, since the names are generated from the source files rather than chosen by hand.
Four scripts run generate first, and test:integration is the one that does not
The root manifest is a workspace root, and most of its scripts are Nx calls into the packages under `packages/`. Four of them generate first, which is the detail that decides whether a fresh clone can run anything at all.
"storybook": "nx run braid-design-system:generate && nx run storybook:dev",
"test": "pnpm run generate && vitest run --project=!integration",
"test:integration": "vitest run --project=integration",
"lint:knip": "nx run braid-design-system:generate && knip --treat-config-hints-as-errors"The test script excludes the integration project explicitly, which lines up with `test:integration` selecting it instead. The asymmetry between the two is the part to know: `test` guarantees the generated files exist before running, `test:integration` does not, so on a clean checkout the integration run depends on generate having happened through some other route first. The same generation step gates the dead code check, and `postbuild` then runs the integration tests, the validate target and the storybook build together after a build completes.
The root manifest is private at 1.0.0 while the published packages sit in the thirties
The manifest at the repository root is named `braid`, marked private, and carries version `1.0.0`. That number is the workspace root's own placeholder and has nothing to do with what consumers install, because the versions that ship are far ahead: `[email protected]` was published on 2026-10-01 and `@braid-design-system/[email protected]` the same day, with `[email protected]` ten days earlier on 2026-09-11. Two packages carry independent version lines, and a third, the codemod, is built by its own script.
"build": "pnpm build:braid && pnpm build:docs-ui && pnpm build:codemod"The mechanism behind those numbers is in the tree: a `.changeset/` directory, a `lint:changesets` script scoped to the site package, and a renovate configuration for dependency updates. Version bumps are therefore driven by changeset files rather than by hand, so the version in the tag is a record of what has already been released and says nothing about how far the default branch has moved. The default branch is `master`, its most recent push is dated 2026-09-27, and the repository is not archived.
knip and manypkg turn dead code and version drift into build failures
Two of the checks in the lint group are stricter than a formatter or a type checker. `knip` runs with `--treat-config-hints-as-errors`, so anything knip would normally report as a hint, an unused file, an unused export or a dependency nothing imports, becomes a failure rather than advice. `manypkg check` exists because this is a monorepo: it compares internal dependency ranges across the workspace packages and fails when a package requires a sibling at a version the workspace does not agree on.
"lint:knip": "nx run braid-design-system:generate && knip --treat-config-hints-as-errors",
"lint:manypkg": "manypkg check"`lint` itself runs the `lint:*` scripts concurrently, and the set includes eslint, prettier, tsc across packages, knip, manypkg and the changesets check. `validate` is the same idea over the `validate` target in every package. For a consumer of the library this matters in one practical way: the published package is produced by a pipeline that holds itself to a zero tolerance for unused exports, so a component that is exported but unused inside the workspace tends to disappear rather than accumulate. The trade is that internal re-exports and deliberate public entry points need configuration to stay put.
Editorial conclusion
Braid is a working choice when your build already goes through sku, or when you are prepared to reproduce what sku does: a Vanilla Extract bundler plugin, a Babel pass that strips assert calls, and a compile time constant for process.env.NODE_ENV. It is a poor fit for a project that cannot touch its bundler configuration, since the setup guide itself says a custom build setup needs guidance from project contributors. Two smaller checks matter too. Import the reset first or the cascade order goes wrong, and decide whether styleBody should be true before you nest the provider inside another application. On the repository side, the published package version and the root manifest version are different numbers, so read the changesets before you assume the tag tells you anything.
Frequently asked questions
What has to be imported first when setting up Braid?
The reset. The example comments the line to say it must be first, because the reset styles need to win the CSS ordering, so braid-design-system/reset goes above the theme import and the component imports.
How do I stop Braid from resetting the body when I render inside another app?
Pass styleBody={false} to BraidProvider. By default the provider sets the body background colour and resets margin and padding, which is right when the application owns the page and wrong when it is rendered inside another document.
Why are Braid's assertion checks still in my production bundle?
Braid performs its precondition and invariant checking with the assert library at runtime, and those calls are only removed if the build strips them. The documented route is the unassert library, applied through Babel with the babel-plugin-unassert plugin, which sku does for you.
Do Braid's dev time warnings disappear on their own?
No. They log conditionally on process.env.NODE_ENV, which is expected to be development or production, and they have to be stripped. At SEEK the webpack optimization configuration replaces that expression with the configured environment as a string so minification can drop the branch.
Which Braid version should I expect to install from npm?
The published braid-design-system package was at 34.9.0 on 2026-10-01, with 34.8.2 released on 2026-09-11, while the private workspace root manifest in the repository carries the unrelated version 1.0.0. The docs UI package, @braid-design-system/docs-ui, has its own line at 5.0.0.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/seek-oss-braid-design-system)Star history chart for your README
[](https://hysenlabs.com/projects/seek-oss-braid-design-system)Was this useful?