Update guidelines.md #2870
+41
−27
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,94 +1,108 @@ | ||||||
| ## Color tokens | ||||||
|
|
||||||
| Color-naming syntax and usage can vary depending on context and tooling. Naming conventions within our system allow us to implement standards in our libraries. | ||||||
|
|
||||||
| In Figma, we use Variables to define and organize color values. Variables allow us to create palettes that reference (or alias) each other. Our Core Palette is a collection of HEX values and their color ramps (`neutral-50`, `neutral-100`,...`neutral-700`). These values are then connected to Semantic Variables. This alias connection allows us to designate multiple token uses for individual HEX values that lead back to the same Core Palette token. | ||||||
|
|
||||||
|
There was a problem hiding this comment. [non-blocking suggestion] since you're providing examples of the core palette, it might be useful to include examples of the semantic palette as well.
Suggested change
|
||||||
| Tokens in code are generated from platform-agnostic files, in our case JSON, and create atomic colors regardless of what platform or framework is used. Core Palette colors are directly referenced in Semantic Palette values in the same way that Figma variables alias one another. | ||||||
|
|
||||||
|
There was a problem hiding this comment. [suggestion] This would use "values" in a consistent manner when referencing each palette.
Suggested change
|
||||||
|  | ||||||
|
|
||||||
| ## What are semantic colors? | ||||||
|
|
||||||
| The Semantic Palette embeds meaning into color names, making it easier to select correct consistent values across applications. | ||||||
|
|
||||||
|
There was a problem hiding this comment. [non-blocking suggestion]
Suggested change
|
||||||
| Semantic colors should be used for the purpose in their name. These colors are designed to meet accessibility standards when used in combination with one another. | ||||||
| - Foreground colors are intended to be used with surface or page colors. | ||||||
| - Status color values have "surface," "on-surface," and "high-contrast" options to meet accessibility standards when used together. | ||||||
|
|
||||||
|
There was a problem hiding this comment. [non-blocking suggestion] This is a bit more formal compared to "have" but I'm not opinionated.
Suggested change
|
||||||
| Some examples of semantic color combinations with their respective contrast ratios are: | ||||||
| - `Foreground/Strong` on `Surface/Primary` nets a ratio of 19.54:1 | ||||||
| - `Foreground/Success-on Surface` on `Surface/Success` nets a ratio of 5.37:1 | ||||||
| - `Foreground/Primary` on `Surface/Primary` nets a ratio of 10.82:1 | ||||||
| - `Foreground/Action` on `Surface/Faint` nets a ratio of 4.86:1 | ||||||
|
|
||||||
|  | ||||||
|
|
||||||
| ### How are semantic names created | ||||||
|
|
||||||
| In semantic token naming, the **element** and the **role** are defined to make color decisions easier and more consistent. HDS organizes semantic tokens into **element** categories with **roles** appended. | ||||||
|
|
||||||
|
There was a problem hiding this comment. This is a great, concise breakdown! 👏 |
||||||
|  | ||||||
|
|
||||||
| Examples of **element** naming include: | ||||||
|
|
||||||
| - **Foreground** - For text, link, status, and icon elements | ||||||
| - **Border** - For borders (or strokes) on components, containers, or dividers | ||||||
| - **Surface** - For the background (or surface) of a component or container | ||||||
| - **Page** - For page backgrounds | ||||||
|
|
||||||
| Examples of **role** in naming include: | ||||||
|
|
||||||
| - Strong | ||||||
| - Primary | ||||||
| - Faint | ||||||
| - Action (not to be used outside of context) | ||||||
| - Disabled (not to be used outside of context) | ||||||
|
|
||||||
| ### Foreground | ||||||
|
|
||||||
| Foreground colors are used for decorative and informational elements such as text, links, and icons. | ||||||
|
|
||||||
|
There was a problem hiding this comment. [super nit] I think technically "informational" is the primary purpose with decorative being second, so it might be better to lead with that.
Suggested change
|
||||||
| Some common examples of semantic foreground colors include: | ||||||
|
|
||||||
| - `Foreground/Strong` for headings and secondary links | ||||||
| - `Foreground/Primary` for body text | ||||||
| - `Foreground/Faint` for less prominent text and UI elements. | ||||||
|
There was a problem hiding this comment. Connected to Lee's suggestion about removing the trailing period.
Suggested change
|
||||||
| - `Foreground/Action` for primary calls to action such as links | ||||||
|
|
||||||
|  | ||||||
|
|
||||||
| Status foreground colors contextualize responses from user actions or indicate status within a UI. These colors should be used sparingly and within the context of specific components, for example: | ||||||
|
|
||||||
| - [Alerts](/components/alert#color) | ||||||
| - [Toasts](/components/toast#color) | ||||||
| - [Badges](/components/badge#color). | ||||||
|
|
||||||
|
There was a problem hiding this comment. Same thing here (I think?)
Suggested change
|
||||||
|  | ||||||
|
|
||||||
| ### Border | ||||||
|
|
||||||
| Some examples of border colors include: | ||||||
|
|
||||||
| - `Border/Strong` for secondary Button border | ||||||
| - `Border/Primary` for Card border or divider | ||||||
| - `Border/{Status color}` for Alert borders | ||||||
|
|
||||||
|  | ||||||
|
|
||||||
| ### Surface | ||||||
|
|
||||||
| Surface colors are intended to be used for the background (or surface) of a component or container. | ||||||
|
|
||||||
| Examples of surface colors include: | ||||||
|
|
||||||
| - `Surface/Strong` for the neutral Badge. | ||||||
| - `Surface/Primary` for component containers. | ||||||
|
There was a problem hiding this comment.
Suggested change
There was a problem hiding this comment. Suggestion: Just because in most lists you don't have periods at the end of the list item |
||||||
| - `Surface/Faint` for the secondary Button. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| - `Surface/{Status color}` for Alert backgrounds. | ||||||
|
|
||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|  | ||||||
|
|
||||||
| ### Page | ||||||
|
|
||||||
| Page colors are used for page backgrounds. HDS components do not use these tokens; however, we recommend `Page/Primary` for all standard page backgrounds and `Page/Faint` as a means to create a secondary level on a page if necessary. | ||||||
|
|
||||||
| ## Accessible color combinations | ||||||
|
|
||||||
| We are conformant with WCAG 2.2 Level AA requirements. For color contrast, this means a luminosity ratio of 4.5:1 for normal sized text, and 3:1 for large text (commonly 22px). Further details are outlined on [WCAG’s understanding of Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html). | ||||||
|
|
||||||
| HDS semantic color tokens provide accessible color combinations out of the box when used according to their naming conventions (`Surface/{Status color}`is compliant in combination with `Foreground/{Status color on surface}`). Using other color token combinations requires manual validation. | ||||||
|
|
||||||
| It is important to note that we [do not recommend the usage of disabled elements](/patterns/disabled-patterns), especially isolating disabled colors out of context, as they are not accessible. | ||||||
|
|
||||||
| ### Using palette colors | ||||||
|
|
||||||
| If Semantic tokens do not meet your needs, the Core Palette is published for general use. These values are usage-agnostic, which can introduce challenges in consistently scaling designs but also allow more freedom and flexibility in color pairing. | ||||||
|
|
||||||
| When pairing colors from the Core Palette, check that adjacent colors meet accessible contrast ratios. To validate your color combinations, use free tools like the [WebAIM contrast checker](https://webaim.org/resources/contrastchecker/) or [Stark’s Figma plugin](https://www.figma.com/community/plugin/732603254453395948/stark-contrast-accessibility-checker). | ||||||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[non-blocking suggestion] This second sentence read slightly weird to me, what do you think about this addition?