Update guidelines.md #2870
Open
Update guidelines.md #2870
+41
−27
Conversation
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
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
shleewhite
previously approved these changes
May 14, 2025
|
|
||
| Some common examples of surface colors include: | ||
| Examples of surface colors include: | ||
|
|
||
| - `Surface/Strong` for the neutral Badge. |
There was a problem hiding this comment.
Suggested change
| - `Surface/Strong` for the neutral Badge. | |
| - `Surface/Strong` for the neutral Badge |
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
|
|
||
| Some common examples of surface colors include: | ||
| 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
| - `Surface/Primary` for component containers. | |
| - `Surface/Primary` for component containers |
|
|
||
| Some common examples of surface colors include: | ||
| Examples of surface colors include: | ||
|
|
||
| - `Surface/Strong` for the neutral Badge. | ||
| - `Surface/Primary` for component containers. | ||
| - `Surface/Faint` for the secondary Button. |
There was a problem hiding this comment.
Suggested change
| - `Surface/Faint` for the secondary Button. | |
| - `Surface/Faint` for the secondary Button |
|
|
||
| - `Surface/Strong` for the neutral Badge. | ||
| - `Surface/Primary` for component containers. | ||
| - `Surface/Faint` for the secondary Button. | ||
| - `Surface/{Status color}` for Alert background. | ||
| - `Surface/{Status color}` for Alert backgrounds. |
There was a problem hiding this comment.
Suggested change
| - `Surface/{Status color}` for Alert backgrounds. | |
| - `Surface/{Status color}` for Alert backgrounds |
There was a problem hiding this comment.
Praise: Love this update to the diagram!
jorytindall
approved these changes
May 14, 2025
|
|
||
| Color-naming syntax and usage can vary depending on context and tooling. This overview will clarify what naming conventions are typically used and how they align with the HDS standards implemented in our libraries. | ||
| 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. |
There was a problem hiding this comment.
[non-blocking suggestion] This second sentence read slightly weird to me, what do you think about this addition?
Suggested change
| 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. | |
| Color-naming syntax and usage can vary depending on context and tooling. Usage-based naming conventions within our system allow us to implement consistent standards in our libraries. |
|
|
||
| In Figma, reusable colors are referred to as “Styles.” They are categorized and stored in the right sidebar for fills, borders, and other properties that accept color values. Styles directly reference a HEX value but cannot reference each other (known as aliasing for Tokens). This means when we provide Figma Styles for semantic usage (like `Foreground/Primary`), the HEX value (`#3B3D45`) is directly referenced instead of the Core Palette color (`Palette/Neutral/Neutral 600`). | ||
| 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
| 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. | |
| 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 (`foreground-primary`, `surface-faint`, `border-critical`). This alias connection allows us to designate multiple token uses for individual HEX values that lead back to the same Core Palette token. |
|
|
||
| In code, we refer to reusable colors as “Tokens.” They are generated from platform-agnostic files, in our case JSON, and create atomic colors regardless of what platform or framework is used. For example, Core Palette colors like `--token-color-palette-neutral-600` are directly referenced in `--token-color-foreground-primary`. | ||
| 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
| 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. | |
| 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 values are directly referenced in Semantic Palette values in the same way that Figma variables alias one another. |
|
|
||
| ## What are semantic colors? | ||
|
|
||
| The Semantic Palette helps ensure proper color usage across applications by embedding meaning directly into the name. | ||
| 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
| The Semantic Palette embeds meaning into color names, making it easier to select correct consistent values across applications. | |
| The Semantic Palette embeds meaning into color names, making it easier to select correct and consistent values across applications. |
| Semantic colors were designed to be used together, ensuring they meet accessibility standards and look visually pleasing. For example, foreground colors are intended to be used with surface or page colors. In many cases, it is important to use specific contextual naming conventions, such as status colors, together. Here are some examples of semantic color combinations with their respective contrast ratios: | ||
| 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
| - Status color values have "surface," "on-surface," and "high-contrast" options to meet accessibility standards when used together. | |
| - Status color values consist of "surface," "on-surface," and "high-contrast" options to meet accessibility standards when used together. |
| The **element** and the **role** are referenced in the name to help make more informed color decisions. | ||
| ### 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! 👏
|
|
||
| Foreground colors are used for elements such as text, links, and icons. | ||
| 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
| Foreground colors are used for decorative and informational elements such as text, links, and icons. | |
| Foreground colors are used for informational and decorative elements such as text, links, and icons. |
|
|
||
| Foreground colors are used for elements such as text, links, and icons. | ||
| Foreground colors are used for decorative and informational elements such as text, links, and icons. | ||
|
|
||
| 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/Faint` for less prominent text and UI elements. | |
| - `Foreground/Faint` for less prominent text and UI elements |
|
|
||
| - [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
| - [Badges](/components/badge#color). | |
| - [Badges](/components/badge#color) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
📌 Summary
If merged, this PR will update the Colors page of the Helios website to make the content more scannable and concise.
🔗 External links
Jira ticket: HDS-4421
👀 Component checklist
💬 Please consider using conventional comments when reviewing this PR.