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.
  • 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?

  • As of September 30, 2024 all v10 assets are deprecated and will not receive any more updates.

What will the Carbon team be supporting for v10?

  • v10 reached it’s end of support on September 30, 2024.
  • carbon-components
    and 
    carbon-components-react
    are now deprecated.

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 from the v10 to v11 Figma kit?

The v10 Carbon libraries are separate from the new v11 Carbon libraries. We created separate Figma libraries for v10 and v11 based on user feedback for versioning purposes. The v10 libraries will not have a continuous update to migrate to v11. Migration to the new v11 Carbon libraries will be a manual process. For additional migration steps, head here.

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
    text-error: rebeccapurple,

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
).

What do I do with my old Feature flags?

If you were providing any configuration options before you imported Carbon you can now provide them using the 

with
syntax:

@use '@carbon/react' with (
  $css--default-type: true,
  $css--reset: true
);

If you were using any feature flags in v10, you can safely remove them in v11.

Note: you can also use 

@import
to bring in Carbon, if you prefer, although 
@use
is recommended.

Additional resources

Custom theme example
V10 token compatibility in V11 example
Light and dark mode example
Zoned theming example
Sass basics
v10 packages deprecation strategy
Edit this page on GitHub
Previous
Migrating: Guide
Next
Elements: 2x Grid