Guide

Carbon v11 focuses on quality of life updates for designers and developers. The highlights of this release include:

With no changes to the IBM Design Language, v11 will not require any brand-driven product redesigns.

To learn more about everything included in this release, check out our Updates section. To get started migrating, visit out our Getting started section below.

Whether you are a designer or a developer, we have curated guidance ready for you as your team makes their migration. Dive in using one of the looks below to get started.

Watch Carbon developers Abbey Hart and Josh Black showcase some of the latest features and enhancements in v11, including theming and CSS Grid by catching the Carbon and IDL weekly design playback. In a collaboration with IBM Bluetalks, watch Josefina Mancilla show off layering and storybook among many other exciting new things that come with our latest version in her talk, Carbon v11: The One with the Cool Stuff.

This section covers the new features and updates that are introduced in Carbon v11. If you’re looking for how to migrate a project from v10 to v11, check out our Getting started section above.

You are not required to use any of the new features introduced in this release. Instead, they are meant to be gradually adopted over time when the use case comes up in your product. Each section will given an overview of the changes and will help you understand how to learn more about the feature in v11.

For an overview of all the changes in this release, check out our Migration Docs

One of the first areas we revisited in v11 was our color tokens. We heard from you all that the names of tokens can be confusing and hard to understand, making it difficult to accurately apply them without constantly referencing our site.

To address this, we investigated several ways to represent usage directly in the token name in order to make them more intuitive to use. After discussing these various options and going through rounds of feedback on GitHub, we decided on an approach that makes it easier to understand and apply tokens based on their usage.

To learn more about the new color tokens, check out our Color Guidelines. You can also learn more about concepts like layering here.

All of these updated color tokens are now shipped as CSS Custom Properties in v11. This technique makes it incredibly simple and performant to customize the theme of your product. We’re most excited about using this for Light & Dark Mode support in products.

This technique also can allow teams to customize a specific area of the page, a specific component, or other models within their product. The best part is that any component using our color tokens just works, regardless of the page or inline theme.

Type tokens are being updated in v11 along with the changes to color tokens. These changes involve mostly name changes. The values and roles of these tokens remain the same between v10 and v11.

To learn more about the new type tokens in v11, check out our Typography Guidelines. If you’re curious about specific changes to tokens, take a look at our v11 Migration Docs.

All v11 changes - including type and color token name updates - have been made in our Sketch kits. The same Sketch Cloud libraries that were used in v10 have been updated to include the v11 changes. The v11 update is available like any other Sketch library update. We recommend that you do not accept the library update until you are ready to work with v11. We have created separate v10 libraries due to team migration preferences. If you are still on v10, migrate to the v11 libraries when you are ready to do so.

All v11 theme libaries are now available in Figma to IBM’s internal users and the public community. We have leveraged Figmas latest features in this release which may result in breaking changes to some of our components. Like with Sketch, we have separate v11 and v10 libraries due to team migration preferences. If you are still on v10, migrate to the v11 libraries when you are ready to do so.

Carbon v11 introduces new code packages to simplify how you bring Carbon into your project. For many teams, you may be installing several packages in order to use Carbon, including:

Starting in v11, the styles, React components, and icons are all available under the @carbon/react package. Each of the packages above can still be downloaded individually but we brought them together to simplify bringing Carbon into your project.

The @carbon/styles package is also being introduced in v11. This package contains all of the Sass styles for our components and is being re-exported by @carbon/react. The Sass styles in this package have gone through a number of updates as we’ve shifted over to Dart Sass in order to improve our compile times by over 90%.

Sass files in Carbon now require Dart Sass in order to compile. The decision to move towards Dart Sass was made after the announcement in the blog post, LibSass is deprecated. Like many of you who use Sass, we’ve relied heavily on LibSass through projects like node-sass. We would not be where we are today without all the hard work and effort that went into these projects.

With the transition to using sass, Carbon has updated its Sass files to leverage Sass Modules. This new module system was introduced in 2019 and we knew that it would be a great fit for the way Carbon authors and ships Sass files.

This new module system created an opportunity to simplify how you bring styles into your project from Carbon, while drastically reducing compile times. The best part is that you can still @import any of the files from Carbon if you would like, there is no requirement for you and your project to move to Sass Modules in order to benefit from these changes.

One of the most common and frustrating challenges team can run into when using Carbon are long Sass compilation times. Parts of this were related to how Carbon was structured, other parts were related to toolchains, but overall we are incredibly excited to announce that we drastically improved the performance of compiling Carbon Sass files in v11.

Through moving to Dart Sass, migrating to Sass Modules, and changing our overall file structure we were able to achieve a 90% in average recompilation times when using sass-loader along with a 60% reduction in initial build times.

We’re shipping a brand new way to incorporate the 2x Grid in code using a technique in CSS called CSS Grid. This implementation ships alongside our Flexbox-based grid that currently exists in v10 and we will continue to support both in v11.

CSS Grid, along with CSS Custom Properties, makes it easier to build more resilient products on the Grid through CSS Grid-specific techniques or through new features that we’re able to bring like sub-grid for more complex products.

If you’re building on any of our Grid components in v10, every one of these will continue to be supported in v11. If you would like to learn more about how to use CSS Grid in your project, you can check out our documentation in React.

We’re shipping several new components in v11 to accompany the changes that we’re making to styles. Theming, layering, CSS Grid, and more are all available as components in our React library.

We’re also using this release to address some of the outstanding accessibility issues for components like Notification and Tooltip along with consistently applying how we name and define certain prop types in v11.

In order to support the new theming features coming to v11, we’re shipping components like GlobalTheme and Theme to make it as easy as possible to change the theme of an entire page or a sub-section of a page. These components are paired alongside the useTheme hook to allow component authors to access the current theme for a given context.

We’re also introducing a new Layer component to simplify how layering is accomplished in v11. Previously, we used the light prop to address the layering needs for the white and g10 themes. Now, the Layer component can be used along with contextual tokens to implement layering across themes.

The default grid in v11 is now implemented using CSS Grid. As a result, you’ll only need to use two components to build layouts on top of the 2x grid: Grid and Column. For teams that already have layouts built on the flexbox version of our grid components, rest assured you can update your code to use FlexGrid along with the existing Row and Column components and your layouts will continue to work as expected.

In order to ship accessible versions of some of our components, we’ve made updates or breaking changes to either change or remove inaccessible behavior.

For example, our Notification component no longer accepts interactive content as the semantics of this context would be stripped from users of Screen Readers. To better support common use cases of components where interactive content was needed, we are also shipping new components like Actionable Notification to offer a better, accessible experience for these use cases.

Tooltip, TooltipIcon, and TooltipDefinition are also receiving updates in v11 and mirror some of the changes seen in Notification. For example, Tooltips can now only contain interactive content. For situ