Color token for light gray background
The $layer-01 color token represents Gray 10 and is used for light gray backgrounds in Carbon designs.
color
37 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Sass color import and usage
The @carbon/colors package enables access to colors from the IBM Design Language in Sass. Import using @use '@carbon/colors' and access colors directly with the syntax colors.$blue-50. Individual colors can be accessed this way, and all colors can be accessed in a Map using the $colors variable to iterate through all swatches and grades.
Sass colors map structure
The $colors map in Sass organizes colors into groups called swatches. Each swatch key maps to a nested map where keys are color grades (10, 20, 30, 40, 50, 60, 70, 80, 90, 100) and values are hex codes. For example, the blue swatch contains: 10: #edf5ff, 20: #d0e2ff, 30: #a6c8ff, 40: #78a9ff, 50: #4589ff, 60: #0f62fe, 70: #0043ce, 80: #002d9c, 90: #001d6c, 100: #001141.
JavaScript color import methods
In JavaScript, import individual color swatches from @carbon/colors using ESM syntax: import { black, blue, warmGray } from '@carbon/colors'; or CommonJS syntax: const { black, blue, warmGray } = require('@carbon/colors');
JavaScript color access patterns
Color swatches are exported as variables and as objects callable by grade. Access colors using: the swatch variable directly (e.g., black), the swatch object with bracket notation specifying grade (e.g., blue[50]), or the combined variable name (e.g., warmGray100).
Carbon React includes color package
When using @carbon/react, the color package does not need to be installed separately as it is included in the React framework.
Two methods to implement layering model
There are two ways to implement the layering model in a theme: explicit layering tokens or contextual tokens. These techniques can be used independently or together. Both produce the same visual result, with the difference lying in how developers work with them. Designers only need to be concerned with the layering tokens.
Layering tokens definition and use
Layering tokens are explicit design tokens used to manually map the layering model onto components. Each layering token corresponds to a specific layer on the page and is used like any other token from Carbon. They come in predefined sets that coordinate with different layer levels. For each layer that a component needs to live on, a separate component variation must be built using the tokens from that layer set.
Contextual tokens definition and use
Contextual tokens are abstract code tokens used to automatically map the layering model onto components depending on where they are used on the page. A contextual token is aware of what layer it is placed on and will call the correct values for that layer. There is only one set of contextual tokens and they require only one component variant to be built.
When to use layering tokens
Use layering tokens as an easy starting point when first working with the layering model, since they work exactly like tokens you already know and love. Also use them when building components that may only need to be on one layer or have only one color variant.
When to use contextual tokens
Use contextual tokens when building reusable components that need to work across layers.
Four layers within a theme
There are four layers within a theme: base layer, layer 01, layer 02, and layer 03. Layers stack one on top of the other in a set order. Each step in UI color (excluding interaction colors) is another layer and will require the use of a different set of layering tokens.
Layer set token naming and organization
Layering tokens are divided into sets and identified by a number (-00, -01, -02, -03) attached to the end of the token name. Any token with a -01 ending belongs to the 01 layering set and so on. The exception is tokens in the base set which use background tokens without a number ending as well as tokens with -00 classification. Tokens from the same set are used together when building components.
Components in layer sets include border and field tokens
In addition to the $layer tokens, layer sets also include border and field tokens, as well as interactive states tokens. A field is considered a layer on top of the background it is placed on; for example a field placed on a $layer-02 background will use $field-03. Border tokens pair with their same number; for example $field-03 pairs with $border-strong-03 in a text input.
Tokens that work across layers
Not all color tokens are part of a layer set. Some token groups, like text and icon, work across layers and are the same across variants because they have enough contrast not to need a change with each layer.
Layer component for contextual tokens
The layer component is used to render a single component on different layers. Components built with contextual tokens when placed inside the layer component will automatically map to the correct layer based on where it sits in the layer structure. Components can be nested inside the layer component up to three levels, with the last level corresponding to the 03 layer set tokens. By default, tokens use the 01 layer set tokens in the first layer.
Layer component structure example
The layer component uses nesting to control which layer set tokens are applied. Example structure: <Layer><ChildComponent /><Layer><ChildComponent /><Layer><ChildComponent /></Layer></Layer></Layer>
Contextual tokens naming convention
Contextual tokens have similar names to layering tokens except contextual tokens do not have the number terminal. Contextual tokens keep the same name no matter which layer they sit on.
Converting layer set token to contextual token
To convert a layer set token to a contextual token, simply drop the numbers at the end of the token name. Contextual tokens are only available in code and are not a part of the design assets. Designers should use the layer set tokens when creating assets but can include contextual tokens in their specs and redlines.
Inline theming definition and use
Inline theming is used when a section of a UI needs to be a different theme from the rest of the page. Inline theming allows themes to be nested within each other without needing custom styles or overrides. A common use-case is applying a contrasting theme to the UI Shell or side panels, especially in light themed products.
When to use inline theming
Only use inline theming for major shifts in color, like high contrast moments. The more subtle transitions of color in a product are handled within each theme through the layering model tokens. It is unlikely that you'll need to inline a White theme within the Gray 10 theme or the Gray 90 theme within the Gray 100 theme.
How inline theming works
To implement inline theming, you must use the Carbon color tokens and themes. For the section of the product you want to inline theme, simply apply the core Carbon tokens like you were doing for the rest of the page, then wrap the targeted section in the Theme component to assign a new theme.
Theme component structure example
The theme component allows you to specify the theme for a page or a portion of a page. Example structure: <Theme theme="g100"><ChildComponent /></Theme>
Designing for inline theming
When designing for inline theming, pull assets that you want in your frame from other theme library files in Figma. Assets will have the same token names across libraries but will show different values. Specify in the design deliverables which sections of the page will be using an inline theme.
Light or dark mode definition
Light or dark mode is a theme setting that allows the end user to choose either a UI that is predominantly light or dark in color. The UI will automatically switch from using light color backgrounds with dark color text to using dark color backgrounds with light color text.
When to implement light or dark mode
Adding the ability to change between a light or dark mode in your product is not required as an IBM product but is highly encouraged. Attention to detail, customization, and being at the forefront of innovation separates IBM over competitors.
Benefits of dark mode
While research shows that unimpaired sighted users perform better in light mode, dark mode is better for people with cataracts and related disorders. Dark mode emits less light and can reduce eye strain and help prevent headaches and migraines. Most modern operating systems (MacOS, iOS, Windows, Android, Linux/GNOME 3) support dark and light modes with APIs so websites and applications can automatically match users' preferred mode.
How light and dark modes work with color tokens
The themes use color tokens to interpret which values are needed for each theme. It is the color tokens that allow a UI to easily switch from one mode to the next. You cannot implement light or dark mode without using color tokens everywhere in your product. Hard coded values will not change when the mode is switched.
Light and dark mode theme pairing
Your product will need to choose a light Carbon theme (White or Gray 10) and a dark Carbon theme (Gray 100 or Gray 90) to implement light or dark mode.
Designing for light and dark modes
All color in your designs and components whether Carbon, PAL or custom made should be redlined using the Carbon color tokens. It is advantageous to use the color token layer styles from the Carbon design asset libraries when designing. Redlining a design in one theme should be enough and not require duplicate designs. In Figma, duplicate your files then swap your current theme library for another to replace local instances with matching instances from the other library.
Creating a mode control
Since theme mode is a user preference, you need to add a control somewhere in your product for the user to make a theme mode selection. This is commonly done in a display setting, user profile, or account area. At the moment, the placement and design of this control is up to product teams.
Inline themes with modes
Mixing themes inline is still allowed with light or dark mode. Mixing inline theme contrast between elements in different modes is also allowed. It is very common for products to have side panels or UI shell elements be high contrast in light mode but low contrast in dark mode. These relationships can be mapped in code using the theme component. Smaller components built with inverse tokens (like tooltip) should remain high contrast when switching modes.
Illustrations and imagery in light and dark modes
You need to account for illustrations and other imagery like pictograms changing color between modes. Otherwise you may end up with very high contrast images in one mode versus the other. Whenever possible, switch out assets entirely between modes to reflect the theme either by using tokens in the SVG code or manually swapping out a PNG. When not possible, a low effort way to design images for modes is to use transparent backgrounds.
Best practice for illustrations in modes
Use light colored assets, tones, and backgrounds for illustrations in light themes and dark colored assets, tones, and backgrounds for illustrations in dark themes. This is the best solution.
Illustration pitfall in light and dark modes
Do not use images with colored backgrounds when switching between modes because they will appear broken and in high contrast in the opposite mode.
Fallback solution for single image across modes
If only one image is available between modes, use an image with a transparent background and swap the container color background to match the mode. This is an acceptable solution.
v11 token naming improvements
Token names have been updated in v11 for easier application. Names are more logical and easier to apply without needing to refer to a guide. For example, text-03 is now text-placeholder. Token names are largely a 1:1 update and very few tokens are keeping their v10 name.