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 - - - +