It’s easier than standing on one leg. We promise.

Carbon is moving to a monorepo

If you haven’t heard of the Carbon Design System before, check us out! We’re a design system built by IBM, shipping open-source styles and components in Vanilla, React, Angular, and Vue for anyone building on the web.

We’re excited to share an update about the Carbon Design System ecosystem on GitHub! Starting today, all core Carbon development happens in a single project: carbon-design-system/carbon. Everything we build is still open-source, and now it’s all happening in the same place.

What does this mean for you?

If you’re using Carbon today, you won’t have to change anything. The most notable changes will be for contributors, and for folks creating issues for bug fixes or enhancements.

At the end of the day, here’s what’s changing:

• The carbon-components, carbon-components-react, and carbon-elements projects are being consolidated into a single project (a monorepo)
• All existing issues from these repos will be moved over to the monorepo
• All existing pull requests from these repos will be migrated over
• We’ll be updating our contributing documentation to include information on how to work on specific packages
• We’ll be updating our issue templates with new fields and guidance to help you get help for specific packages that you are using

Why we’re excited

The Carbon team has been exploring moving all of Carbon’s core projects into one repo for a while now. When building out Carbon v10, we took the opportunity to try and validate some of the ideas we had with a new project called Carbon Elements.

This experiment worked, and helped to enable interesting possibilities for building and distributing the IBM Design Language in code. In particular, we could:

• Offer each design element as its own package. For example, we ship packages for: colors, type, grid, icons, and motion
• Offer packages that group related packages. This meant we could ship a single elements package so that users wouldn’t have to install all the element packages independently
• Automate generation of files for packaging and distribution
• Coordinating releases was a one-line step when using Lerna
• Developing in packages that depend on each other was seamless (mostly)

When reflecting on some of our experiences building Carbon v10, a lot of our frustrations mirror things that could be addressed by following a similar approach to Carbon Elements.

With this new setup, we can easily orchestrate releases across multiple projects. It will also make developing on specific packages simpler than our old workflow using yarn link to sync up each dependency. It will also allow us to consolidate our backlog of everything Carbon-related into a single GitHub project to help with issue triage and delivery.

What’s coming next

This first phase involves moving over the carbon-components, carbon-components-react, and carbon-elements packages directly, and we’re super excited about what’s next. Looking towards Carbon v11, we want to deliver on a couple key areas:

• Take full advantage of our @carbon scope by publishing our core packages to @carbon/components and @carbon/react
• Start shipping component packages directly, like @carbon/button and @carbon/button-react
• Update our core packages to include styles directly. This means only one install for all teams to get access to component styles and JavaScript

We want (need) your feedback

Going through this process will be a big change not only for our team, but for teams who are using the Carbon Design System. A big part of this will be making sure everything is backwards compatible.

If you run into any issues, or have feedback for us, please reach out on Slack or make an issue on GitHub and we’ll make sure to get back to you as soon as possible!

Check out our projects on GitHub! We’re always looking for contributors. If you have any questions or comments about the Carbon Design System, please reach out at carbon@us.ibm.com.