Carbon Design System: IBM's React and Web Components Library

What Carbon Actually Ships, and Who It Is For

Carbon is IBM's open-source design system, and the repository is a monorepo rather than a single library. The README states that it includes the React and web components libraries, Sass styles, design tokens, icons, pictograms, and tooling. That list matters more than it looks: the project is not one dependency but a family of packages, each published separately on npm and each versioned on its own.

The packages table in the README names twelve of them. @carbon/react carries React components and styles. @carbon/web-components carries standards-based web components. Below those sit the foundations: @carbon/colors for color scales and color token utilities, @carbon/elements for IBM Design Language foundations, @carbon/grid for layouts, @carbon/layout for spacing scale tokens, @carbon/type for type tokens designed to pair with IBM Plex, @carbon/themes for theme tokens, @carbon/motion for productive and expressive motion curves, @carbon/styles for the Sass, and @carbon/icons and @carbon/pictograms for the assets.

That split is the actual product decision. If you only want the spacing scale or the color tokens, you install a small package and never touch the component layer. If you want buttons and data tables, you install @carbon/react and inherit its expectations. The README also points at community-maintained packages for Angular, Svelte and Vue, hosted under the IBM and carbon-design-system GitHub organisations, so the React and web components builds are the ones this repository owns; the other frameworks are somebody else's maintenance problem.

How the Monorepo Is Wired: Lerna, Yarn Workspaces and Nx

The root package.json is private and versioned 0.0.0, which tells you the repository itself is never published. It declares workspaces for actions/*, config/* and packages/*, and requires Node >=20.x. Build orchestration is Lerna: the build script is lerna run build --stream --prefix followed by a task that generates the repository structure. Lerna also handles clean and the telemetry:config script. Alongside it, nx.json sits at the top level, and the repository carries jest.config.js, jest.e2e.config.js and playwright.config.js, so unit and end-to-end testing are both configured in-tree.

The practical consequence for a consumer is that the packages you install are built artifacts from this pipeline, not source you compile yourself. The lint and format scripts operate across actions, config and packages, with eslint.config.mjs and prettier.config.js at the root. Stylelint runs over the Sass with --report-needless-disables and --report-invalid-scope-disables, a stricter setting than a plain stylelint pass, which suggests the Sass layer is treated as a first-class deliverable rather than an afterthought.

The examples/ directory is the part worth reading before you install anything. It contains class-prefix, codesandbox-styles, custom-theme, id-prefix, incremental-migration-vite, light-dark-mode, nextjs, v10-token-compat-in-v11 and vite. Those names describe the integration problems the maintainers expect you to hit: prefixing class names and ids to avoid collisions, applying a custom theme, migrating from v10 tokens to v11, and running under Vite or Next.js. The presence of incremental-migration-vite and v10-token-compat-in-v11 is an admission that moving from v10 to v11 is not a drop-in change.

Getting Started From the Repository's Own Examples

The README does not include install commands. It links to the developing guides on carbondesignsystem.com and to the package directories, and the repository ships a set of runnable examples instead. The package names in the README's table are the ones to look up on npm: @carbon/react for React components and styles, and @carbon/styles for the Sass styles for Carbon components.

The repository layout is the part you can act on directly. The examples/ directory holds a Vite setup, a Next.js setup, a custom theme, a light and dark mode variant, class and id prefixing, a v10 token compatibility example for v11, and an incremental migration example for Vite. Those directories are the reference configurations the project maintains for the integration cases it expects you to encounter.

npx carbon-cli ci-check

The root package.json defines ci-check as carbon-cli ci-check, and the same file defines the repository's lint, format and test scripts. Those are scripts for working inside the monorepo, not for consuming the published packages, which is worth being clear about before you clone.

If a Carbon upgrade breaks your build, the README does not document a rollback path, so pinning versions before an upgrade is a decision you make yourself.

The Prefix and Theme Options Are the Real Customisation Surface

Two example directories, examples/class-prefix/ and examples/id-prefix/, exist because Carbon's generated class names and DOM ids can collide with whatever else is on the page. If you are embedding Carbon components into a host application that already has its own CSS conventions, or shipping a widget into someone else's page, those examples are the ones to read first. The same applies to examples/custom-theme/ and examples/light-dark-mode/: theming runs through the token layer, and @carbon/themes is published separately precisely so you can supply your own values.

This is a genuine strength of the architecture. Because tokens, grid, layout, type and motion are separate packages, you can adopt Carbon's spacing scale or IBM Plex type tokens while writing your own components. You are not forced into an all-or-nothing adoption, and the examples directory shows the seams deliberately.

The trade-off is that customisation happens at build time, through Sass and token overrides, not at runtime through a prop. If your product needs to swap visual themes per tenant at runtime without a rebuild, the token-override model is the wrong shape, and you will end up wrapping components or generating stylesheets yourself.

Where Carbon Is the Wrong Choice

Carbon carries IBM's design language, and the README is explicit that @carbon/type is designed to pair with IBM Plex. If your brand has its own typographic and color identity, you are not adopting a neutral component kit; you are adopting a system whose defaults encode somebody else's design decisions. Overriding enough of them to look like a different product is more work than starting from a smaller library.

The web components package is described in the README as standards-based web components, but it is not the same artifact as @carbon/react and does not have the same adoption story. The README documents community-maintained packages for Angular, Svelte and Vue, which means framework support outside React and web components is maintained by other people, not by this repository. If your team is on Angular or Vue, you are depending on a package this monorepo does not build.

Finally, the version history is a moving target. The releases listed span v11.115.0, v11.115.0-rc.0 and v11.114.0 within roughly two weeks, and the examples directory contains both incremental-migration-vite and v10-token-compat-in-v11. Frequent minor releases combined with a token migration path from v10 means upgrade work is recurring, not a one-time event.

Carbon Against a Headless Primitive Library

The closest alternative in approach is a headless primitive library such as Radix UI or React Aria: unstyled, accessible behaviour with no visual opinion, leaving all appearance to you. Carbon is the opposite bet. It ships the appearance, the tokens, the Sass and the assets, and it asks you to accept IBM's visual language in exchange for not having to design a data table, a date picker or a grid from scratch.

The difference shows up in what you spend time on. With a headless library you spend it on styling and on assembling your own design tokens. With Carbon you spend it on overriding tokens, prefixing class names and following the migration guide when tokens change between major versions. Neither is cheaper in the abstract; they are cheaper for different teams. A team with an existing brand system and a designer who owns it will find Carbon fights them. A team building an internal tool that needs a competent table, a modal and a form today will find Carbon gets there faster.

Licence, Maintenance and Upgrade Cost

Carbon is licensed under Apache-2.0, and the LICENSE file sits at the repository root. Apache-2.0 permits commercial and closed-source use and includes an express patent grant, which matters for larger organisations. It also carries attribution and notice requirements, so if you redistribute the packages you need to keep the licence and notice files intact. That is a summary of the licence text, not legal advice; have your own counsel read it if redistribution is part of your plan.

On maintenance: the repository is not archived, and the last push was on 2026-08-27, which is recent. The release cadence visible in the version list is high, with minor releases landing repeatedly. For a consumer this cuts both ways. Fixes arrive quickly, and so do the token and API changes that the migration examples exist to handle. The README links to a migrating guide at carbondesignsystem.com/migrating/guide/overview/, which is where the upgrade cost is documented rather than in the README itself.

Contributions are governed by CONTRIBUTING.md and a Code of Conduct, with discussion on GitHub Discussions and a Discord server. Security reporting has its own SECURITY.md. None of that tells you how quickly a pull request of yours would land, and the README does not make any commitment about that either.

Editorial conclusion

Adopt Carbon if your product already lives inside IBM's design language or needs the React and web components builds of the same system, with tokens and Sass shipped as separate packages you can consume without the component layer. Do not adopt it if you want a component library small enough to fork and own, or if you cannot accept that the visual language is dictated upstream. Before committing, verify one thing: that your bundler resolves the @carbon/styles Sass entry, because the failure mode that costs the most time is a build pipeline that cannot find the stylesheet rather than a missing component.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes