Carbon Design System

General
Sass and package management
Additional resources

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?

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 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';
Copy to clipboard

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]';
Copy to clipboard

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,
Copy to clipboard

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 using	Sass 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;
}
Copy to clipboard

If you don’t include

as *

, then it would look like this:

@use '@carbon/react/scss/theme';

.some-class {
  background: theme.$layer;
}
Copy to clipboard

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
);
Copy to clipboard

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.

Elements: 2x Grid

FAQs

General

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

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

What are the benefits to my product’s customers?

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

What will the Carbon team be supporting for v10?

What is the rule for supporting deprecated assets?

Will I need to redesign my product?

Why rename things instead of leaving things as they are?

How big is the effort to migrate from the v10 to v11 Figma kit?

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

Sass and package management

What packages should I be installing?

What if I want to use a specific theme?

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

What if I want to use a custom theme?

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

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

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

What do I do with my old Feature flags?

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

FAQs

General

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

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

What are the benefits to my product’s customers?

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

What will the Carbon team be supporting for v10?

What is the rule for supporting deprecated assets?

Will I need to redesign my product?

Why rename things instead of leaving things as they are?

How big is the effort to migrate from the v10 to v11 Figma kit?

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

Sass and package management

What packages should I be installing?

What if I want to use a specific theme?

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

What if I want to use a custom theme?

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

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

What is the “as *” used at the end of some @useCopy to clipboard statements?

What do I do with my old Feature flags?

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

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