Skip to main contentCarbon Design System

FAQs

General

What are the benefits of Carbon v11 for me as a designer?

  • Token names have been updated for easier application. Names are more logical and easier to apply without always having to refer to a guide.

  • Nothing visually has changed in any of the components, and so no redesign work is required.

What are the benefits of Carbon v11 for me as a developer?

  • CSS grid provides easier implementation of layouts, support for sub-grid, and other features that come along with this new technology.

  • CSS custom properties for theming (light mode / dark mode).

  • A significant reduction in compile times for most projects with the update to Sass architecture.

  • Quality of life updates such as:

    • Consistent component API across the board.
    • Improvements to Sass structure for getting started and productive use experiences.
  • New components:

    • Cover a wider variety of use-cases in your product with some of our new components.
    • Easily build our more accessible experiences with our accessibility component primitives.

What are the benefits to my product’s customers?

  • Light/dark mode support.
  • Faster time to develop new features.
  • New components added that can be used instead of being newly developed.
  • Accessibility primitives to help build more accessible experiences as early as possible to the development process.
  • Faster load times due to smaller bundle sizes.
  • Faster time to develop new features
  • New components added that can be used to build off of instead of being newly developed
  • Accessibility primitives to help build more accessible experiences as early as possible in the development process

Do I need to update right away? If not, when will we need to update?

  • Carbon v11 includes functionality that may be a motivator for migration, but teams can migrate to v11 when they have the bandwidth.

  • Teams that are using v10 today can continue to stay on v10 and everything that is implemented will continue to work.

What will the Carbon team be supporting for v10?

  • No new functionality will be introduced in v10 after the v11 release.

  • We will continue to address high impact bugs that come up for the v10 release after the v11 release.

  • We will continue to accept any contributions that look to address issues in the v10 release if we are unable to get to them in time for your product roadmap.

What is the rule for supporting deprecated assets?

  • Assets that were deprecated from v9 to v10 will be removed in v11.

  • Assets that are deprecated in v10 will remain in v11 and will be removed in v12. While the timeline of v12 has not been set, the team’s intent is for major versions to be at minimum 12 months apart.

Will I need to redesign my product?

  • Visually, nothing is changing.

  • There are system-side changes that will require changes to design specs and code, like the token names update and inline theming.

  • Token names are largely a 1:1 update and very few tokens are keeping their v10 name. This means color tokens will have to be updated across assets.

  • We are hoping to be able to provide a script that can make these changes on the code side automatically, however this has not been built or tested yet.

Why rename things instead of leaving things as they are?

  • Making these updates now creates a better system user experience and it sets us up for growth and scale so new tokens can fit into the set more easily.

  • The new names imply the usage and so will be much easier to apply. For example, text-03 will be text-placeholder.

How big is the effort to migrate current Sketch designs to the v11 Sketch kit?

  • The Carbon Sketch files will automatically update to v11. Connected styles and symbols will automatically receive the v11 updates once the library update is accepted by the users in each design file.

  • If you’re not ready to update to v11, you can stop accepting library updates to that file until you are ready.

  • Sketch files for v10 will be available in the GitHub archive but will no longer be an attached library. There is no way to properly version Sketch Cloud files. There is only the latest version.

  • The effort to update local/PAL assets depends on the structure of files. If you are using the Carbon layer styles then the update will be automatic. If you’re using hard values and just specing the token names, then you will need to update your specs.

  • Read the Sketch documentation for more details.

How big is the expected effort to migrate code to v11?

We’ll have more on this once we have interviewed teams that have successfully migrated to v11.

Sass and package management

What packages should I be installing?

If you’re using our React components, @carbon/react will have everything you need to use along with it: component styles, icons, grid, theming and type. This package essentially includes all our most used code assets in Carbon. If you’ve installed this package, you should not have to install our styles, grid, theme, icons or type packages.

In order to use our styles with this package, all you need to include is the following in your index.scss:

@use '@carbon/react';

We understand that this can be a bit bulky, and sometimes you don’t want all of the styles that come with that. To include styles for something more specific, we suggest including them like so:

@use '@carbon/react/scss/components/[componentname]';

What if I want to use a specific theme?

In v11 we introduced a component called <GlobalTheme/>. This component makes it really easy to change the default theme by using it as a wrapper in your app, and passing in a theme prop value of white, g10, g90, or g100.

What if I want to do zoned theming or toggle themes?

We recommend using our <Theme/> component to include zoned themes. A great example of zoned theming using this component lives in our tutorial, where we themed the header differently than the application theme. If you are wanting to toggle themes, for a light and dark mode, we built an example for you using our GlobalTheme component.

What if I want to use a custom theme?

If you are creating a custom theme or overriding theme tokens, you would do that like so:

@use '@carbon/react/scss/themes' as *;
//overriding theme tokens and adding a custom token
@use '@carbon/react/scss/theme' with
(
$theme: (
// add a completely new token
custom-token: #bada44,
// redefine existing tokens to new values

Check out the full example we built here.

I’m not familiar with sass. How do I learn more?

Hey, we get it. Sass can be a little different if you’ve never worked with it, especially sass modules. We recommend reading through some of the Sass documentation to learn more. A great place to start is Sass Basics. To learn more about sass modules specifically (introduced in v11), we recommend reading the docs for @use.

How do I know what sass modules to include at the top of my files?

Some of our most used sass assets are included below, along with what you would need to have at the top of your file to use it. The @use example is specifically if you are using our @carbon/react package. If you are using our @carbon/styles the path would be the same, simply replace react with styles. Essentially, all we are doing is including the path where we would find these styles in our package.

Carbon sass I’m usingSass modules to include
Theme tokens@use '@carbon/react/scss/theme'
Theme mixins@use '@carbon/react/scss/themes'
Design language color tokens@use '@carbon/react/scss/colors'
Spacing tokens@use '@carbon/react/scss/spacing'
Breakpoint mixins@use '@carbon/react/scss/breakpoint'
Motion tokens and functions@use '@carbon/react/scss/motion'
Rem and other convert functions@use '@carbon/react/scss/utilities/convert'
Z-index helper@use '@carbon/react/scss/utilities/z-index'
Focus outline helper@use '@carbon/react/scss/utilities/focus-outline'
Transform rotate helper@use '@carbon/react/scss/utilities/rotate'
Skeleton animation helper@use '@carbon/react/scss/utilities/skeleton'

What is the “as *” used at the end of some @use statements?

This relates to the default namespace that sass provides to all modules. You can change this namespace, but it’s oftentimes more helpful to completely omit the namespace. as * accomplishes this.

For example, if you were using a color token like $layer, your scss file could look something like this:

@use '@carbon/react/scss/theme' as *;
.some-class {
background: $layer;
}

If you don’t include as *, then it would look like this:

@use '@carbon/react/scss/theme';
.some-class {
background: theme.$layer;
}

Where the token is prefixed by the name of the sass file (in this case theme).

Additional resources