diff --git a/src/pages/guidelines/themes/images/theme-1.png b/src/pages/guidelines/themes/images/theme-1.png
deleted file mode 100644
index b41552e9de6..00000000000
Binary files a/src/pages/guidelines/themes/images/theme-1.png and /dev/null differ
diff --git a/src/pages/guidelines/themes/images/theme-2.png b/src/pages/guidelines/themes/images/theme-2.png
deleted file mode 100644
index dd0a40f7161..00000000000
Binary files a/src/pages/guidelines/themes/images/theme-2.png and /dev/null differ
diff --git a/src/pages/guidelines/themes/images/themes-1.png b/src/pages/guidelines/themes/images/themes-1.png
new file mode 100644
index 00000000000..9519758cdce
Binary files /dev/null and b/src/pages/guidelines/themes/images/themes-1.png differ
diff --git a/src/pages/guidelines/themes/overview.mdx b/src/pages/guidelines/themes/overview.mdx
index c1a7a091b1f..b3faeb2539d 100755
--- a/src/pages/guidelines/themes/overview.mdx
+++ b/src/pages/guidelines/themes/overview.mdx
@@ -35,21 +35,21 @@ individual components.
### Theme terms
-| Term | Definition | |
-| ------- | ----------------------------------------------------------------------------------------------------------- | --- |
-| _Theme_ | The set of unique values assigned to the tokens of a Carbon interface | |
-| _Token_ | The code identifier for a unique role or set of roles. Tokens are universal and never change across themes. | |
-| _Role_ | The systematic usage(s) of a token. Roles cannot be changed between themes. | |
-| _Value_ | The actual style (i.e. hex code) assigned to a token | |
+| Term | Definition | |
+| ------- | ------------------------------------------------------------------------------------------------------------ | --- |
+| _Theme_ | A collection of visual attributes assigned to the tokens in order to create a specific aesthetic | |
+| _Token_ | A role-based identifier that assigns a value to a theme. Tokens are universal and never change across themes | |
+| _Role_ | The systematic usage(s) of a token. Roles cannot be changed between themes | |
+| _Value_ | The actual style (such as a hex code) assigned to a token | |
### Default theme
Carbon provides four themes as shown in the
[color usage](/guidelines/color/usage) page. When `carbon-components` is
-downloaded and installed, the components are preset to use the default (white)
+downloaded and installed, the components are preset to use the default (White)
theme.
-To use the gray 10, gray 90, or gray 100 theme as your default instead of white,
+To use the Gray 10, Gray 90, or Gray 100 theme as your default instead of White,
set the `$carbon--theme` variable to one of the available theme maps
(`$carbon--theme--g10`, `$carbon--theme--g90`, `$carbon--theme--g100`) and then
include your normal components in your Sass build. These need to be imported
@@ -84,71 +84,112 @@ stylesheet which will replace the values of the default theme.
1. Create a theme mixin that effectively mimics this structure, but changes up
- hex values as needed:
+ values as needed:
```scss
$carbon--theme--white: (
- interactive-01: #0062ff,
- interactive-02: #171717,
- interactive-03: #0062ff,
- interactive-04: #0062ff,
- ui-background: #ffffff,
- ui-01: #f3f3f3,
- ui-02: #ffffff,
- ui-03: #dcdcdc,
- ui-04: #8c8c8c,
- ui-05: #171717,
- text-01: #171717,
- text-02: #565656,
- text-03: #8c8c8c,
- text-04: #ffffff,
- icon-01: #171717,
- icon-02: #565656,
- icon-03: #ffffff,
- link-01: #0062ff,
- link-02: #0043ce,
- field-01: #f3f3f3,
- field-02: #ffffff,
- inverse-01: #ffffff,
- inverse-02: #3d3d3d,
- support-01: #da1e28,
- support-02: #24a148,
- support-03: #fdd13a,
- support-04: #054ada,
- inverse-support-01: #fb4b53,
- inverse-support-02: #3dbb61,
- inverse-support-03: #fdd13a,
- inverse-support-04: #408bfc,
- overlay-01: rgba(23, 23, 23, 0.5),
- focus: #0062ff,
- hover-primary: #0353e9,
- active-primary: #0530ad,
- hover-primary-text: #054ada,
- hover-secondary: #4c4c4c,
- active-secondary: #6f6f6f,
- hover-tertiary: #0353e9,
- active-tertiary: #0530ad,
- hover-ui: #e5e5e5,
- active-ui: #bebebe,
- selected-ui: #dcdcdc,
- hover-selected-ui: #cacaca,
- hover-danger: #ba1b23,
- active-danger: #750e13,
- hover-row: #e5e5e5,
- visited-link: #8a3ffc,
- disabled-01: #f3f3f3,
- disabled-02: #bebebe,
- disabled-03: #8c8c8c,
- highlight: #c9deff,
- skeleton-01: #e5e5e5,
- skeleton-02: #bebebe,
- brand-01: #0062ff,
- brand-02: #171717,
- brand-03: #0062ff,
- active-01: #bebebe,
- hover-field: #e5e5e5,
-) !default;
+ // Background
+ background: #ffffff,
+ background-active: #c6c6c6,
+ background-hover: #e5e5e5,
+ background-selected: #e0e0e0,
+ background-selected-hover: #cacaca,
+ background-inverse: #393939,
+ background-inverse-hover: #4c4c4c,
+ background-brand: #0f62fe,
+
+ // Layer
+ layer: #f4f4f4,
+ layer-active: #c6c6c6,
+ layer-hover: #e5e5e5,
+ layer-selected: #e0e0e0,
+ layer-selected-hover: #cacaca,
+ layer-selected-inverse: #161616,
+ layer-selected-disabled: #8d8d8d,
+ layer-accent: #e0e0e0,
+ layer-accent-active: #a8a8a8,
+ layer-accent-hover: #d1d1d1,
+ layer-disabled: #f4f4f4,
+
+ // Field
+ field: #f4f4f4,
+ field-hover: #e5e5e5,
+ field-disabled: #f4f4f4,
+
+ // Interactive
+ interactive: #0f62fe,
+
+ // Border
+ border-subtle: #e0e0e0,
+ border-subtle-selected: #c6c6c6,
+ border-strong: #8d8d8d,
+ border-inverse: #161616,
+ border-interactive: #0f62fe,
+ border-disabled: #f4f4f4,
+
+ // Text
+ text-primary: #161616,
+ text-secondary: #525252,
+ text-placeholder: #a8a8a8,
+ text-helper: #6f6f6f,
+ text-on-color: #ffffff,
+ text-inverse: #ffffff,
+ text-disabled: #c6c6c6,
+ text-on-color-disabled: #8d8d8d,
+
+ //Link
+ link-primary: #0f62fe,
+ link-primary-hover: #0043ce,
+ link-secondary: #0043ce,
+ link-visited: #8a3ffc,
+ link-inverse: #78a9ff,
+
+ //Icon
+ icon-primary: #161616,
+ icon-secondary: #525252,
+ icon-on-color: #ffffff,
+ icon-inverse: #ffffff,
+ icon-disabled: #c6c6c6,
+ icon-on-color-disabled: #8d8d8d,
+
+ // Support
+ support-error: #da1e28,
+ support-success: #198038,
+ support-warning: #f1c21b,
+ support-info: #0043ce,
+ support-error-inverse: #fa4d56,
+ support-success-inverse: #42be65,
+ support-warning-inverse: #f1c21b,
+ support-info-inverse: #4589ff,
+
+ // Misc.
+ overlay: rgba(22, 22, 22, 0.5),
+ toggle-off: #8d8d8d,
+
+ // Button
+ button-primary: #0f62fe,
+ button-primary-active: #002d9c,
+ button-primary-hover: #0353e9,
+ button-secondary: #393939,
+ button-secondary-active: #6f6f6f,
+ button-secondary-hover: #4c4c4c,
+ button-tertiary: #0f62fe,
+ button-tertiary-active: #002d9c,
+ button-tertiary-hover: #0353e9,
+ button-danger-primary: #da1e28,
+ button-danger-secondary: #da1e28,
+ button-danger-active: #750e13,
+ button-danger-hover: #b81921,
+ button-disabled: #c6c6c6,
+
+// Focus
+ focus-inset: #ffffff,
+ focus-inverse: #ffffff,
+
+// Skeleton
+ skeleton-background: #e5e5e5,
+ skeleton-element: #c6c6c6,
```
2. Name the mixin:
@@ -161,7 +202,7 @@ i.e., `$my-theme`
Alternatively, for relatively minor changes to an existing theme, a developer
can make changes on a per-token basis. For example, after importing an existing
-Carbon theme, she could just set something like `$interactive-01: hotpink;`.
+Carbon theme, she could just set something like `$interactive: hotpink;`.
## Tokens
@@ -170,9 +211,9 @@ system-wide. Tokens are used across all components and help keep global patterns
and styles consistent.
All tokens come pre-baked into the Carbon component source code. Tokens are
-denoted by the prefix `$` (e.g. `$ui-01`). Tokens can also be nested within
-other tokens. For example, `$interactive-01` calls the IBM Design Language color
-palette token `$ibm-color__blue--60` for its value in the default theme.
+denoted by the prefix `$` (e.g. `$layer-01`). Tokens can also be nested within
+other tokens. For example, `$interactive` calls the IBM Design Language color
+palette token `$blue-60` for its value in the default theme.
There are several token categories:
@@ -183,101 +224,126 @@ There are several token categories:
### Color
-Each theme is assigned 52 universal color variables, which are determined by
-[common roles and usage](/guidelines/color/usage). This allows for uniform color
-application across themes while maintaining full styling flexibility.
+Each theme is assigned universal color variables, which are determined by common
+roles and usage. This allows for uniform color application across themes while
+maintaining full styling flexibility. For more information, see the
+[color](/guidelines/color/overview) page.
```scss
-//// _theme-tokens.scss
-// White theme tokens
-$interactive-01: #0062ff !default;
-$interactive-02: #171717 !default;
-$interactive-03: #0062ff !default;
-$interactive-04: #0062ff !default;
-$ui-background: #ffffff !default;
-$ui-01: #f3f3f3 !default;
-$ui-02: #ffffff !default;
-$ui-03: #dcdcdc !default;
-$ui-04: #8c8c8c !default;
-$ui-05: #171717 !default;
-$text-01: #171717 !default;
-$text-02: #565656 !default;
-$text-03: #8c8c8c !default;
-$text-04: #ffffff !default;
-$icon-01: #171717 !default;
-$icon-02: #565656 !default;
-$icon-03: #ffffff !default;
-$link-01: #0062ff !default;
-$link-02: #0043ce !default;
-$field-01: #f3f3f3 !default;
-$field-02: #ffffff !default;
-$inverse-01: #ffffff !default;
-$inverse-02: #3d3d3d !default;
-$support-01: #da1e28 !default;
-$support-02: #24a148 !default;
-$support-03: #fdd13a !default;
-$support-04: #054ada !default;
-$overlay-01: rgba(23, 23, 23, 0.5) !default;
-$focus: #0062ff !default;
-$hover-primary: #0353e9 !default;
-$active-primary: #0530ad !default;
-$hover-primary-text: #054ada !default;
-$hover-secondary: #4c4c4c !default;
-$active-secondary: #6f6f6f !default;
-$hover-tertiary: #0353e9 !default;
-$active-tertiary: #0530ad !default;
-$hover-ui: #e5e5e5 !default;
-$active-ui: #bebebe !default;
-$selected-ui: #dcdcdc !default;
-$hover-selected-ui: #cacaca !default;
-$hover-danger: #ba1b23 !default;
-$active-danger: #750e13 !default;
-$hover-row: #e5e5e5 !default;
-$visited-link: #8a3ffc !default;
-$disabled-01: #f3f3f3 !default;
-$disabled-02: #bebebe !default;
-$disabled-03: #8c8c8c !default;
-$highlight: #c9deff !default;
-$brand-01: #0062ff !default;
-$brand-02: #171717 !default;
-$brand-03: #0062ff !default;
-$active-01: #bebebe !default;
-$hover-field: #e5e5e5 !default;
+$carbon--theme--white: (
+ // Background
+ background: #ffffff,
+ background-active: #c6c6c6,
+ background-hover: #e5e5e5,
+ background-selected: #e0e0e0,
+ background-selected-hover: #cacaca,
+ background-inverse: #393939,
+ background-inverse-hover: #4c4c4c,
+ background-brand: #0f62fe,
+ // Layer
+ layer: #f4f4f4,
+ layer-active: #c6c6c6,
+ layer-hover: #e5e5e5,
+ layer-selected: #e0e0e0,
+ layer-selected-hover: #cacaca,
+ layer-selected-inverse: #161616,
+ layer-selected-disabled: #8d8d8d,
+ layer-accent: #e0e0e0,
+ layer-accent-active: #a8a8a8,
+ layer-accent-hover: #d1d1d1,
+ layer-disabled: #f4f4f4,
+ // Field
+ field: #f4f4f4,
+ field-hover: #e5e5e5,
+ field-disabled: #f4f4f4,
+ // Interactive
+ interactive: #0f62fe,
+ // Border
+ border-subtle: #e0e0e0,
+ border-subtle-selected: #c6c6c6,
+ border-strong: #8d8d8d,
+ border-inverse: #161616,
+ border-interactive: #0f62fe,
+ border-disabled: #f4f4f4,
+ // Text
+ text-primary: #161616,
+ text-secondary: #525252,
+ text-placeholder: #a8a8a8,
+ text-helper: #6f6f6f,
+ text-on-color: #ffffff,
+ text-inverse: #ffffff,
+ text-disabled: #c6c6c6,
+ text-on-color-disabled: #8d8d8d,
+ //Link
+ link-primary: #0f62fe,
+ link-primary-hover: #0043ce,
+ link-secondary: #0043ce,
+ link-visited: #8a3ffc,
+ link-inverse: #78a9ff,
+ //Icon
+ icon-primary: #161616,
+ icon-secondary: #525252,
+ icon-on-color: #ffffff,
+ icon-inverse: #ffffff,
+ icon-disabled: #c6c6c6,
+ icon-on-color-disabled: #8d8d8d,
+ // Support
+ support-error: #da1e28,
+ support-success: #198038,
+ support-warning: #f1c21b,
+ support-info: #0043ce,
+ support-error-inverse: #fa4d56,
+ support-success-inverse: #42be65,
+ support-warning-inverse: #f1c21b,
+ support-info-inverse: #4589ff,
+ // Misc.
+ overlay: rgba(22, 22, 22, 0.5),
+ toggle-off: #8d8d8d,
+ // Button
+ button-primary: #0f62fe,
+ button-primary-active: #002d9c,
+ button-primary-hover: #0353e9,
+ button-secondary: #393939,
+ button-secondary-active: #6f6f6f,
+ button-secondary-hover: #4c4c4c,
+ button-tertiary: #0f62fe,
+ button-tertiary-active: #002d9c,
+ button-tertiary-hover: #0353e9,
+ button-danger-primary: #da1e28,
+ button-danger-secondary: #da1e28,
+ button-danger-active: #750e13,
+ button-danger-hover: #b81921,
+ button-disabled: #c6c6c6,
+ // Focus
+ focus-inset: #ffffff,
+ focus-inverse: #ffffff,
+ // Skeleton
+ skeleton-background: #e5e5e5,
+ skeleton-element: #c6c6c6
+);
```
### Spacing
-Carbon has two spacing scales, one for general spacing within components and the
-other for layout spacing. Both are designed to complement the components and
-typography throughout the system. Each scale has its own
-[distinct purpose](/guidelines/spacing/overview). The two scales have certain
-overlapping values that serve two different roles, so be mindful when choosing a
-spacing token.
+Use the spacing scale when building individual components. It includes small
+increments needed to create appropriate spatial relationships for detail-level
+designs. For more information, see the [spacing](/guidelines/spacing/overview/)
+page.
```scss
-//// _spacing.scss
-$spacing-baseline: 1rem !default;
-
-// Spacing scale
-$spacing-4xs: $spacing-baseline * 0.0625 !default;
-$spacing-3xs: $spacing-baseline * 0.125 !default;
-$spacing-2xs: $spacing-baseline * 0.25 !default;
-$spacing-xs: $spacing-baseline * 0.5 !default;
-$spacing-sm: $spacing-baseline * 0.75 !default;
-$spacing-md: $spacing-baseline !default;
-$spacing-lg: $spacing-baseline * 1.5 !default;
-$spacing-xl: $spacing-baseline * 2 !default;
-$spacing-2xl: $spacing-baseline * 2.5 !default;
-$spacing-3xl: $spacing-baseline * 3 !default;
-
-// Layout scale
-$layout-2xs: $spacing-baseline !default;
-$layout-xs: $spacing-baseline * 1.5 !default;
-$layout-sm: $spacing-baseline * 2 !default;
-$layout-md: $spacing-baseline * 3 !default;
-$layout-lg: $spacing-baseline * 4 !default;
-$layout-xl: $spacing-baseline * 6 !default;
-$layout-2xl: $spacing-baseline * 10 !default;
+ $spacing-01: 0.125rem,
+ $spacing-02: 0.25rem,
+ $spacing-03: 0.5rem,
+ $spacing-04: 0.75rem,
+ $spacing-05: 1rem,
+ $spacing-06: 1.5rem,
+ $spacing-07: 2rem,
+ $spacing-08: 2.5rem,
+ $spacing-09: 3rem,
+ $spacing-10: 4rem,
+ $spacing-11: 5rem,
+ $spacing-12: 6rem,
+ $spacing-13: 10rem,
```
### Typography
@@ -285,7 +351,8 @@ $layout-2xl: $spacing-baseline * 10 !default;
Typography has four categories of type styles (universal, productive, editorial,
and additional) that can be customized through tokens. These tokens are used
both within components and across layouts. Type tokens are determined by their
-[role](/guidelines/typography/productive) across the system.
+role across the system. For more information, see the
+[typography](/guidelines/typography/overview/) page.
```scss
// Universal
@@ -779,30 +846,25 @@ The following example demonstrates the relationship between the different
themes. Each theme shares the same variables and roles, with only the value
changing for each individual theme.
-![Default theme applied](images/themes-1.svg)
+
+
-| Key | Token | Role | White theme value | Dark theme value |
-| --- | ----------- | ------------------- | -------------------- | ------------------- |
-| 1 | `$text-02` | Label color | `#565656` / Gray 70 | `#bebebe` / Gray 30 |
-| 2 | `$text-01` | Primary text color | `#171717` / Gray 100 | `#f3f3f3` / Gray 10 |
-| 3 | `$ui-04` | Border bottom color | `#8c8c8c` / Gray 50 | `#a4a4a4` / Gray 40 |
-| 4 | `$icon-01` | Primary icon color | `#171717` / Gray 100 | `#f3f3f3` / Gray 10 |
-| 5 | `$field-01` | Field color | `#f3f3f3` / Gray 10 | `#3d3d3d` / Gray 80 |
-| 6 | `$ui-02` | Page background | `#ffffff` / White | `#282828` / Gray 90 |
+![Default theme applied](images/themes-1.png)
-## Resources
+
+
-
-
-
+| Key | Token | Role | White theme value | Gray 100 theme value |
+| --- | ----------------- | ------------------- | ----------------- | -------------------- |
+| 1 | `$text-secondary` | Label color | Gray 70 | Gray 30 |
+| 2 | `$text-primary` | Primary text color | Gray 100 | Gray 10 |
+| 3 | `$border-strong` | Border bottom color | Gray 50 | Gray 60 |
+| 4 | `$icon-primary` | Primary icon color | Gray 100 | Gray 10 |
+| 5 | `$field-01` | Field color | Gray 10 | Gray 90 |
+| 6 | `$background` | Page background | White | Gray 100 |
-)
+## Resources
-
-
-
+