From cb13637349d832a9682ccc897bb54065ad41df77 Mon Sep 17 00:00:00 2001 From: Adekunle Oduye Date: Tue, 21 Jun 2022 18:40:41 -0400 Subject: [PATCH 01/26] color: Init first draft --- technical-reports/color/color-type.md | 303 ++++++++++++++++- technical-reports/color/overview.md | 16 + technical-reports/color/token-naming.md | 412 ++++++++++++++++++++++++ 3 files changed, 720 insertions(+), 11 deletions(-) create mode 100644 technical-reports/color/overview.md create mode 100644 technical-reports/color/token-naming.md diff --git a/technical-reports/color/color-type.md b/technical-reports/color/color-type.md index bfa027e..cbd5287 100644 --- a/technical-reports/color/color-type.md +++ b/technical-reports/color/color-type.md @@ -1,22 +1,303 @@ -# The color type +### Color Type -Represents a 24bit RGB or 24+8bit RGBA color in the sRGB color space. The `$type` property MUST be set to the string `color`. The value MUST be a string containing a hex triplet/quartet including the preceding `#` character. To support other color spaces, such as HSL, export tools SHOULD convert color tokens to the equivalent value as needed. +Colors can be represented through various formats. For color, the type property must be set to the string “color”. For the value, the most common format to represent color through design tokens is a hex triplet. A hex triplet is a 6-digit, 24 bit, hexadecimal number that represents Red, Green, and Blue values as #RRGGBB. -For example, initially the color tokens MAY be defined as such: - + +Then, the output variables may look like: + + +``` +// colors-rgba.scss +$majestic-magenta: hsl(300, 100%, 50%, 1); +$simple-sage: hsl(152, 22%, 73%, 1); +``` + + + +##### Hex8 + +Hex8 uses two extra digits, known as the alpha value, to change the transparency of the color. The format follows #RRGGBBAA. [Learn more about alpha values in hex.](https://www.digitalocean.com/community/tutorials/css-hex-code-colors-alpha-values#adding-an-alpha-value-to-css-hex-codes) + + + + + + + + + + + +
Pros + Cons +
+
    + +
  • Can define alpha value with color +
    • +
+ 		+
    + +
  • Less commonly used + +
  • Alpha value is not immediately obvious (needs calculation) + +
  • Not available in older versions of internet explorer (caniuse reference) +
    • +
+
+ + +Example: + + +``` +{ + "Majestic magenta": { + "value": "#ff00ff80", + "type": "color" + }, + "Simple sage": { + "value": "#abcabc80", + "type": "color" + } +} +``` + + +Then, the output variables may look like: + + +``` +// colors-hex.scss +$majestic-magenta: #ff00ff80; +$simple-sage: #abcabc80; + +// colors-rgba.scss +$majestic-magenta: rgba(255, 0, 255, 0.5); +$simple-sage: rgba(171, 202, 188, 0.5); +``` + + + +##### LCH (Lightness Chroma Hue) + +Formated in L (lightness), C (chroma), H (hue) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). + + + + + + + + + + + +
Pros + Cons +
+
    + +
  • Access to 50% more colors (P3 color space) + +
  • Colors more perceptually uniform + +
  • +
    • +
+ 		+
    + +
  • No fully supported (only safari) +
    • +
+
+ + + +--- + + +#### Using [Experimental?] Color Spaces + + + +* Using color spaces like OKLCH, OKLAB, CAM16, Display P-3, etc. may result in lack of support from tools, so plan to have a hex back-up \ No newline at end of file diff --git a/technical-reports/color/overview.md b/technical-reports/color/overview.md new file mode 100644 index 0000000..9ba9c5f --- /dev/null +++ b/technical-reports/color/overview.md @@ -0,0 +1,16 @@ +## What + +For this specification, we consider a color type design token to be any token whose value represents a color. + +## Why + +(why it helps to have a specification for color tokens) + +Color tokens allow teams to manage color decisions at scale, streamline product consistency, reduce technical debt, and optimize the software development lifecycle. + +The goal is to manage color at scale for a product which at the end would reduce complexity and communicate the value to stakeholders. + +* Color Management at scale +* reduce complexity +* Standardize your product +* Have stakeholders understand the value diff --git a/technical-reports/color/token-naming.md b/technical-reports/color/token-naming.md new file mode 100644 index 0000000..30672c4 --- /dev/null +++ b/technical-reports/color/token-naming.md @@ -0,0 +1,412 @@ +### Token Naming + + +#### Categorization + +There are 3 main categories of design tokens that we will continue to reference in this specification. + + +##### Base + +Base tokens are the lowest level tokens and typically consist of a name and [hexadecimal](https://www.w3.org/TR/css-color-4/#hex-notation) value pair. + +Example: + + +``` +$color-green-500: #abcabc; +$color-shadow-translucent: #00000088; +``` + + + +##### Alias + +A design token’s value can be a _reference_ to another token. The same value can have multiple names or aliases. + +Example: + + +``` +$color-palette-black: #000000; +$color-text-base: $color-palette-black; +``` + + + +##### Component + +Component-specific tokens provide design decisions at the component level and improve the separation of concerns in your token architecture. + +Example: + + +``` +$color-button-primary: $color-brand-primary; +$color-banner-background: $color-palette-black; +``` + + + +#### Naming Strategies + +There are many naming options when it comes to design tokens, especially color type tokens. We’ve identified two that seem to be most commonly implemented, **descriptive and numerical**. + + +##### Base Tokens + + + +For **Base tokens**, here’s how they may be represented in each version: + + +###### Descriptive + +Descriptive names can be more emotional and human-friendly because they often relate to tangible things that people interact with, like grass or watermelons. + + + + + + + + + + + +
Pros + Cons +
Easier for people to identify with, could be used to distinguish Brand colors from product colors + Harder to determine the scale of colors (i.e. which ones are lighter vs. darker, and how they pair well together) +
+ + +Example: + + +``` +$color-grass: #abcabc; +$color-brand-watermelon: #; +``` + + + +###### Numerical + +**Ordered Scales** + +Numerical tokens often follow a scale to help delineate how the colors progress. For example, when using an ordered scale, $color-blue-500 may be the base color, where the lightest color value is $color-blue-100, and the darkest value could be $color-blue-900, and these values are ordered in increments of 100s in between. We recommend not using sequential numbers (ex: 1, 2, 3, 4) for scalability in case future colors need to be added in between two existing colors. + +Example: + + +``` +$color-green-400: #____; +$color-green-500: #268e6c; +$color-green-600: #12805c; +``` + + +Numerical token names can also allow for further specificity when needed. For example, when creating neutral palette tokens (like grays), the scale may increase by increments of 25 instead of 100 at the lightest values, and then increment by 100 thereafter. + +Example: + + +``` +$color-gray-25: #268e6c; +$color-gray-50: #12805c; +$color-gray-75: #12805c; +$color-gray-100: #12805c; +$color-gray-200: #_____; +``` + + +**Bounded Scales ** + +Numerical tokens can also be named through** bounded scales**. These tokens utilize a distinguishing value based on the actual color used for the token, such as in HSL’s lightness value to vary shades of a tint. + +Example: + + +``` +$color-gray-22: #268e6c; +$color-gray-49: #12805c; +$color-gray-73: #12805c; +$color-gray-99: #_____; +``` + + +**Computer Generated Scales** + +Token names may also be generated by tools, where the user specifies the base name, and the tool appends scale numbers based on changes to the underlying value. + +Example: + + +``` +// User specified name +$color-green + +// Tool generated names for 6 steps of opacity +$color-green-10: rgba(32,178,170, 0.10); +$color-green-20: rgba(32,178,170, 0.20); +$color-green-30: rgba(32,178,170, 0.30); +$color-green-40: rgba(32,178,170, 0.40); +$color-green-50: rgba(32,178,170, 0.50); +$color-green-60: rgba(32,178,170, 0.60); +``` + + + + + + + + + + + + +
Pros + Cons +
Easy mapping between different tokens for color contrast. For example, all 100-400 tokens pair with 500-900 tokens in order to create accessible color combinations. \ + \ +If using bounded scales, the token name can help indicate something about the underlying value + Less memorable and less obvious difference between tokens +
+ + + +##### Alias Tokens + +For **Alias tokens**, we recommend grouping tokens with similar intentions by prioritizing the category + property within the name. For example, all background color Alias tokens would likely start with** $color-background-XXX**. + +We recommend avoiding abbreviations. For example, use “background” instead of “bg”, to help with clarity. Some exceptions may be + +

>>>>> gd2md-html alert: undefined internal link (link text: "design system prefixes"). Did you generate a TOC?
(Back to top)(Next alert)
>>>>>

+ +[design system prefixes](#heading=h.279mf43yevt0). + +Here’s how alias tokens may be represented: + +Example: + + +``` +$color-background-error: $color-red-600; +$color-background-success: $color-green-400; +$color-text-base: $color-palette-black; // Token with variant +$color-text-error-hover: $color-red-700; // Token with variant and state +``` + + +Color alias tokens could also be grouped by concept, like so: + +Example: + + +``` +// These can be used for background, border, or text colors +$color-feedback-error: $color-red-600; +$color-feedback-success: $color-green-400; +``` + + + +##### Component Specific Tokens + +Component specific names should start with the component that they support, and be located close to the component code. They commonly refer to alias tokens under the hood, and can be helpful when trying to use consistent styles across components while still maintaining separation of concerns. + +Example: + + +``` +$badge-color-background-error: $color-background-error or $color-feedback-error; +$badge-color-background-success: $color-background-success; +$badge-color-text-error: $color-text-error or $color-feedback-error; +``` + + + +#### Supporting Color Modes + +Design tokens can be matched with multiple values to support various color modes, like a light mode and dark mode, as an example. This can be implemented in multiple ways, as demonstrated below. + + +##### Single declaration + +In this case, the **$color-text-default** token is defined once, and “value” is considered the default for light mode, and the “darkValue” is used in dark mode. + + +``` +// tokens/color/alias.json +{ + "color": { + "text": { + "default": { + "value": "#111111", + "darkValue": "#ffffff", + "comment": "Default text color" + } + } + } +} +``` + + + +##### Multi-file declaration + +In this case, the **$color-text-default** token is defined in two separate files, in different folders. + + +``` +// tokens/color/alias.json +{ + "color": { + "text": { + "default": { + "value": "#111111", + "comment": "Default text color" + } + } + } +} +``` + + + +``` +//tokens/theme/dark/color/alias.json +{ + "color": { + "text": { + "default": { + "value": "#ffffff", + "comment": "Default text color" + } + } + } +} +``` + + + +#### Example of Supporting Multiple Themes and Brands in React + + +``` +// _theme.less + +:root { + --color-interactive: #007c89; +} + +:global(.dark-mode) { + --color-interactive: #133232; +} + +// button.less + +.primary { + color-background-primary: var(--color-interactive); +} + + +``` + + +Theme.js + + +``` +import React, { useContext } from 'react'; + +export const ThemeContext = React.createContext(); +export const SubbrandContext = React.createContext(); + +const Theme = React.forwardRef(function Theme( + { theme = 'light', subbrand, children }, + forwardedRef, +) { + return ( + + +
+ {children} +
+ + + ); +}); + + +const useThemeContext = () => useContext(ThemeContext); +const useSubbrandContext = () => useContext(SubbrandContext); + +export default Theme; +export { useThemeContext, useSubbrandContext }; + +``` + + +Portal.js + + +``` +import Theme, { + useThemeContext, + useSubbrandContext, +} from '@mc/wink/components/Theme'; + + +const Portal = ({ children, ...props }) => { + const theme = useThemeContext(); + const subbrand = useSubbrandContext(); + + return ( + + + {children} + + + ); +}; + +export default Portal; + +``` + + +Consumer + + +``` +// subbrand.less + +.valentinesDay { + --color-interactive: #be0000; + --color-text-base: #313131; + + .dark-mode & { + --color-interactive: #470000; + --color-text-base: #cdbfbf; + } +} + +``` + + + +``` +import {Theme} from "@design-system" + +import subbrand from "subbrand.less"; + +…. +return ( + + {children} + +) +``` \ No newline at end of file From e674eeb886a4e42d1f04b466cf61766378682d57 Mon Sep 17 00:00:00 2001 From: Adekunle Oduye Date: Thu, 23 Jun 2022 08:45:43 -0400 Subject: [PATCH 02/26] fix: clean up format --- technical-reports/color/color-type.md | 97 +++++++------------------ technical-reports/color/token-naming.md | 62 +++++----------- 2 files changed, 46 insertions(+), 113 deletions(-) diff --git a/technical-reports/color/color-type.md b/technical-reports/color/color-type.md index cbd5287..735e081 100644 --- a/technical-reports/color/color-type.md +++ b/technical-reports/color/color-type.md @@ -1,8 +1,7 @@ -### Color Type +# Color Type Colors can be represented through various formats. For color, the type property must be set to the string “color”. For the value, the most common format to represent color through design tokens is a hex triplet. A hex triplet is a 6-digit, 24 bit, hexadecimal number that represents Red, Green, and Blue values as #RRGGBB. -
Pros @@ -20,10 +19,8 @@ Colors can be represented through various formats. For color, the type property
- For example, initially color tokens may be defined as such: - ``` { "Majestic magenta": { @@ -37,10 +34,8 @@ For example, initially color tokens may be defined as such: } ``` - Then, the output from a tool’s conversion to HSL may look something like: - ``` // colors-hex.scss $majestic-magenta: #ff00ff; @@ -50,16 +45,11 @@ $simple-sage: #abcabc; $majestic-magenta: ​hsl(300, 100%, 50%); $translucent-shadow: ​hsl(153, 23%, 73%); ``` +## Other value options: +### RGBA - -#### Other value options: - - -##### RGBA - -Formated in R (red), G (green), B (blue) and (A) alpha. Red, green, and blue values can range from 0 to 255 and alpha values can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity. - +Formatted in R (red), G (green), B (blue) and (A) alpha. Red, green, and blue values can range from 0 to 255 and alpha values can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity. @@ -69,24 +59,20 @@ Formated in R (red), G (green), B (blue) and (A) alpha. Red, green, and blue val + -
+
    +
  • Can define alpha value with color
    • +
  • Alpha value is easy to comprehend at a glance
    • +
+ 		-
    - -
  • Can define alpha value with color - -
  • Alpha value is easy to comprehend at a glance -
    • -
- 		? + ?
- For example, initially color tokens may be defined as such: - ``` { "Majestic magenta": { @@ -120,13 +106,9 @@ Then, the output from a tool’s conversion to RGBA may look something like: $majestic-magenta: rgba(255, 0, 255, 1.0); $translucent-shadow: rgba(171, 202, 188, 50%); ``` +### HSL - - -##### HSL - -Formated in H (hue), S (saturation), L (lightness) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). - +Formatted in H (hue), S (saturation), L (lightness) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). @@ -178,23 +160,18 @@ Example: } ``` - Then, the output variables may look like: - ``` // colors-rgba.scss $majestic-magenta: hsl(300, 100%, 50%, 1); $simple-sage: hsl(152, 22%, 73%, 1); ``` - - -##### Hex8 +### Hex8 Hex8 uses two extra digits, known as the alpha value, to change the transparency of the color. The format follows #RRGGBBAA. [Learn more about alpha values in hex.](https://www.digitalocean.com/community/tutorials/css-hex-code-colors-alpha-values#adding-an-alpha-value-to-css-hex-codes) -
- -
Pros @@ -203,31 +180,24 @@ Hex8 uses two extra digits, known as the alpha value, to change the transparency
-
    - -
  • Can define alpha value with color -
    • -
+ 		+
    +
  • Can define alpha value with color
    • +
-
    - -
  • Less commonly used - -
  • Alpha value is not immediately obvious (needs calculation) - -
  • Not available in older versions of internet explorer (caniuse reference) -
    • -
+ 		+
    +
  • Less commonly used +
  • Alpha value is not immediately obvious (needs calculation) +
  • Not available in older versions of internet explorer (caniuse reference) +
    • +
- Example: - ``` { "Majestic magenta": { @@ -241,10 +211,8 @@ Example: } ``` - Then, the output variables may look like: - ``` // colors-hex.scss $majestic-magenta: #ff00ff80; @@ -254,13 +222,9 @@ $simple-sage: #abcabc80; $majestic-magenta: rgba(255, 0, 255, 0.5); $simple-sage: rgba(171, 202, 188, 0.5); ``` +### LCH (Lightness Chroma Hue) - - -##### LCH (Lightness Chroma Hue) - -Formated in L (lightness), C (chroma), H (hue) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). - +Formatted in L (lightness), C (chroma), H (hue) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). @@ -291,13 +255,8 @@ Formated in L (lightness), C (chroma), H (hue) and an optional (A) alpha. Hue v
- - --- - -#### Using [Experimental?] Color Spaces - - +## Using [Experimental?] Color Spaces * Using color spaces like OKLCH, OKLAB, CAM16, Display P-3, etc. may result in lack of support from tools, so plan to have a hex back-up \ No newline at end of file diff --git a/technical-reports/color/token-naming.md b/technical-reports/color/token-naming.md index 30672c4..5e88455 100644 --- a/technical-reports/color/token-naming.md +++ b/technical-reports/color/token-naming.md @@ -1,40 +1,32 @@ -### Token Naming +# Token Naming - -#### Categorization +## Categorization There are 3 main categories of design tokens that we will continue to reference in this specification. - -##### Base +### Base Base tokens are the lowest level tokens and typically consist of a name and [hexadecimal](https://www.w3.org/TR/css-color-4/#hex-notation) value pair. Example: - ``` $color-green-500: #abcabc; $color-shadow-translucent: #00000088; ``` - - -##### Alias +### Alias A design token’s value can be a _reference_ to another token. The same value can have multiple names or aliases. Example: - ``` $color-palette-black: #000000; $color-text-base: $color-palette-black; ``` - - -##### Component +### Component Component-specific tokens provide design decisions at the component level and improve the separation of concerns in your token architecture. @@ -48,19 +40,15 @@ $color-banner-background: $color-palette-black; -#### Naming Strategies +## Naming Strategies There are many naming options when it comes to design tokens, especially color type tokens. We’ve identified two that seem to be most commonly implemented, **descriptive and numerical**. - -##### Base Tokens - - +### Base Tokens For **Base tokens**, here’s how they may be represented in each version: - -###### Descriptive +#### Descriptive Descriptive names can be more emotional and human-friendly because they often relate to tangible things that people interact with, like grass or watermelons. @@ -80,18 +68,14 @@ Descriptive names can be more emotional and human-friendly because they often re - Example: - ``` $color-grass: #abcabc; $color-brand-watermelon: #; ``` - - -###### Numerical +#### Numerical **Ordered Scales** @@ -121,13 +105,12 @@ $color-gray-200: #_____; ``` -**Bounded Scales ** +**Bounded Scales** Numerical tokens can also be named through** bounded scales**. These tokens utilize a distinguishing value based on the actual color used for the token, such as in HSL’s lightness value to vary shades of a tint. Example: - ``` $color-gray-22: #268e6c; $color-gray-49: #12805c; @@ -135,14 +118,12 @@ $color-gray-73: #12805c; $color-gray-99: #_____; ``` - **Computer Generated Scales** Token names may also be generated by tools, where the user specifies the base name, and the tool appends scale numbers based on changes to the underlying value. Example: - ``` // User specified name $color-green @@ -156,8 +137,6 @@ $color-green-50: rgba(32,178,170, 0.50); $color-green-60: rgba(32,178,170, 0.60); ``` - - -
Pros @@ -166,8 +145,8 @@ $color-green-60: rgba(32,178,170, 0.60);
Easy mapping between different tokens for color contrast. For example, all 100-400 tokens pair with 500-900 tokens in order to create accessible color combinations. \ - \ + Easy mapping between different tokens for color contrast. For example, all 100-400 tokens pair with 500-900 tokens in order to create accessible color combinations. + If using bounded scales, the token name can help indicate something about the underlying value Less memorable and less obvious difference between tokens @@ -175,9 +154,7 @@ If using bounded scales, the token name can help indicate something about the un
- - -##### Alias Tokens +### Alias Tokens For **Alias tokens**, we recommend grouping tokens with similar intentions by prioritizing the category + property within the name. For example, all background color Alias tokens would likely start with** $color-background-XXX**. @@ -211,9 +188,7 @@ $color-feedback-error: $color-red-600; $color-feedback-success: $color-green-400; ``` - - -##### Component Specific Tokens +### Component Specific Tokens Component specific names should start with the component that they support, and be located close to the component code. They commonly refer to alias tokens under the hood, and can be helpful when trying to use consistent styles across components while still maintaining separation of concerns. @@ -228,12 +203,12 @@ $badge-color-text-error: $color-text-error or $color-feedback-error; -#### Supporting Color Modes +### Supporting Color Modes Design tokens can be matched with multiple values to support various color modes, like a light mode and dark mode, as an example. This can be implemented in multiple ways, as demonstrated below. -##### Single declaration +#### Single declaration In this case, the **$color-text-default** token is defined once, and “value” is considered the default for light mode, and the “darkValue” is used in dark mode. @@ -255,7 +230,7 @@ In this case, the **$color-text-default** token is defined once, and “value” -##### Multi-file declaration +#### Multi-file declaration In this case, the **$color-text-default** token is defined in two separate files, in different folders. @@ -292,7 +267,7 @@ In this case, the **$color-text-default** token is defined in two separate files -#### Example of Supporting Multiple Themes and Brands in React +### Example of Supporting Multiple Themes and Brands in React ``` @@ -397,7 +372,6 @@ Consumer ``` - ``` import {Theme} from "@design-system" From fd0e930730629e0fd256bf29dd268c43002f8a4a Mon Sep 17 00:00:00 2001 From: Kaelig Deloumeau-Prigent Date: Thu, 8 Sep 2022 00:09:41 +0000 Subject: [PATCH 03/26] Markdown lobster party! Co-authored-by: Ayesha Mazumdar Co-authored-by: Adekunle Oduye Co-authored-by: Kathleen McMahon --- technical-reports/color/color-type.md | 247 ++++++++++++------------ technical-reports/color/index.html | 10 +- technical-reports/color/overview.md | 15 +- technical-reports/color/token-naming.md | 225 +++++++++++---------- technical-reports/index.html | 2 +- 5 files changed, 242 insertions(+), 257 deletions(-) diff --git a/technical-reports/color/color-type.md b/technical-reports/color/color-type.md index 735e081..c67551f 100644 --- a/technical-reports/color/color-type.md +++ b/technical-reports/color/color-type.md @@ -1,27 +1,16 @@ -# Color Type +# Color type -Colors can be represented through various formats. For color, the type property must be set to the string “color”. For the value, the most common format to represent color through design tokens is a hex triplet. A hex triplet is a 6-digit, 24 bit, hexadecimal number that represents Red, Green, and Blue values as #RRGGBB. +Colors can be represented through various formats. For color, the type property must be set to the string “color”. For the value, the most common format to represent color through design tokens is a hex triplet. A hex triplet is a 6-digit, 24 bit, hexadecimal number that represents Red, Green, and Blue values as `#RRGGBB`. - - - - - - - - - -
Pros - Cons -
Easily recognized among tools and browsers -

-?? -

Cannot specify alpha value for opacity -
+| Pros | Cons | +| ------------------------------------------ | -------------------------------------- | +| Easily recognized among tools and browsers | Cannot specify alpha value for opacity | For example, initially color tokens may be defined as such: -``` + -``` +Then, the output from a tool’s conversion to HSL may look something like: + + + +## Other value options ### RGBA @@ -53,10 +49,8 @@ Formatted in R (red), G (green), B (blue) and (A) alpha. Red, green, and blue va - - + + - +
Pros - Cons - ProsCons
@@ -65,140 +59,143 @@ Formatted in R (red), G (green), B (blue) and (A) alpha. Red, green, and blue va
  • Alpha value is easy to comprehend at a glance
    		•  - ? - ?
    For example, initially color tokens may be defined as such: -``` + -Then, the output from a tool’s conversion to RGBA may look something like: +Then, the output from a tool’s conversion to RGBA may look something like: + + ### HSL -Formatted in H (hue), S (saturation), L (lightness) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). +Formatted in H (hue), S (saturation), L (lightness) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). - - + + - - + +
    Pros - Cons - ProsCons
    -
      - -
    • It is easy to understand compare to other formats - -
    • Easy to predict value changes -
      • -
    -     		-
      - -
    • No supported in older browsers -
      • -
    -     		+
      +
    • It is easy to understand compare to other formats
      • +
    • Easy to predict value changes
      • +
    +     		+
      +
    • No supported in older browsers
      • +
    +
    + -``` +Then, the output variables may look like: + + + ### Hex8 -Hex8 uses two extra digits, known as the alpha value, to change the transparency of the color. The format follows #RRGGBBAA. [Learn more about alpha values in hex.](https://www.digitalocean.com/community/tutorials/css-hex-code-colors-alpha-values#adding-an-alpha-value-to-css-hex-codes) +Hex8 uses two extra digits, known as the alpha value, to change the transparency of the color. The format follows `#RRGGBBAA`. [Learn more about alpha values in hex.](https://www.digitalocean.com/community/tutorials/css-hex-code-colors-alpha-values#adding-an-alpha-value-to-css-hex-codes) - - + + - +
      +
    • Can define alpha value with color
      • +
    + +
    Pros - Cons - ProsCons
    -
      -
    • Can define alpha value with color
      • -
    -     		-
      -
    • Less commonly used -
    • Alpha value is not immediately obvious (needs calculation) -
    • Not available in older versions of internet explorer (caniuse reference) -
      • -
    -     		+
      +
    • Less commonly used
      • +
    • Alpha value is not immediately obvious (needs calculation)
      • +
    • + Not available in older versions of internet explorer (caniuse reference) +
      • +
    +
    -Example: + -``` +Then, the output variables may look like: + + + ### LCH (Lightness Chroma Hue) -Formatted in L (lightness), C (chroma), H (hue) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). +Formatted in L (lightness), C (chroma), H (hue) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). - - + + - - + +
    Pros - Cons - ProsCons
    -
      - -
    • Access to 50% more colors (P3 color space) - -
    • Colors more perceptually uniform - -
    • -
      • -
    -     		-
      - -
    • No fully supported (only safari) -
      • -
    -     		+
      +
    • Access to 50% more colors (P3 color space)
      • +
    • Colors more perceptually uniform
      • +
    +     		+
      +
    • No fully supported (only safari)
      • +
    +
    --- -## Using [Experimental?] Color Spaces +## Using [Experimental?] color spaces -* Using color spaces like OKLCH, OKLAB, CAM16, Display P-3, etc. may result in lack of support from tools, so plan to have a hex back-up \ No newline at end of file +- Using color spaces like OKLCH, OKLAB, CAM16, Display P-3, etc. may result in lack of support from tools, so plan to have a hex back-up diff --git a/technical-reports/color/index.html b/technical-reports/color/index.html index 39766d8..8b5d2f7 100644 --- a/technical-reports/color/index.html +++ b/technical-reports/color/index.html @@ -80,9 +80,17 @@

    Introduction

    This section is non normative

    -

    Work in progress.

    +
    +
    +
    -``` +```scss $color-green-500: #abcabc; $color-shadow-translucent: #00000088; ``` + + ### Alias A design token’s value can be a _reference_ to another token. The same value can have multiple names or aliases. -Example: + + ### Component Component-specific tokens provide design decisions at the component level and improve the separation of concerns in your token architecture. -Example: - + - -## Naming Strategies +## Naming strategies There are many naming options when it comes to design tokens, especially color type tokens. We’ve identified two that seem to be most commonly implemented, **descriptive and numerical**. ### Base Tokens -For **Base tokens**, here’s how they may be represented in each version: +For **Base tokens**, here’s how they may be represented in each version: #### Descriptive Descriptive names can be more emotional and human-friendly because they often relate to tangible things that people interact with, like grass or watermelons. +| Pros | Cons | +| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| Easier for people to identify with, could be used to distinguish Brand colors from product colors | Harder to determine the scale of colors (i.e. which ones are lighter vs. darker, and how they pair well together) | - - - - - - - - - -
    Pros - Cons -
    Easier for people to identify with, could be used to distinguish Brand colors from product colors - Harder to determine the scale of colors (i.e. which ones are lighter vs. darker, and how they pair well together) -
    - -Example: + -**Ordered Scales** +#### Numerical -Numerical tokens often follow a scale to help delineate how the colors progress. For example, when using an ordered scale, $color-blue-500 may be the base color, where the lightest color value is $color-blue-100, and the darkest value could be $color-blue-900, and these values are ordered in increments of 100s in between. We recommend not using sequential numbers (ex: 1, 2, 3, 4) for scalability in case future colors need to be added in between two existing colors. +**Ordered scales** -Example: +Numerical tokens often follow a scale to help delineate how the colors progress. For example, when using an ordered scale, $color-blue-500 may be the base color, where the lightest color value is $color-blue-100, and the darkest value could be $color-blue-900, and these values are ordered in increments of 100s in between. We recommend not using sequential numbers (ex: 1, 2, 3, 4) for scalability in case future colors need to be added in between two existing colors. + -Numerical token names can also allow for further specificity when needed. For example, when creating neutral palette tokens (like grays), the scale may increase by increments of 25 instead of 100 at the lightest values, and then increment by 100 thereafter. - -Example: +Numerical token names can also allow for further specificity when needed. For example, when creating neutral palette tokens (like grays), the scale may increase by increments of 25 instead of 100 at the lightest values, and then increment by 100 thereafter. + -**Bounded Scales** +**Bounded scales** -Numerical tokens can also be named through** bounded scales**. These tokens utilize a distinguishing value based on the actual color used for the token, such as in HSL’s lightness value to vary shades of a tint. +Numerical tokens can also be named through **bounded scales**. These tokens utilize a distinguishing value based on the actual color used for the token, such as in HSL’s lightness value to vary shades of a tint. -Example: + + +**Computer generated scales** Token names may also be generated by tools, where the user specifies the base name, and the tool appends scale numbers based on changes to the underlying value. -Example: +
    From 0e2cc98880836c959f6d4f5a1bfce56ec4f80634 Mon Sep 17 00:00:00 2001 From: Ayesha Date: Mon, 26 Sep 2022 15:25:45 -0700 Subject: [PATCH 04/26] Updates for future section and tables --- technical-reports/color/color-type.md | 109 ++++++------------------ technical-reports/color/token-naming.md | 11 +-- 2 files changed, 32 insertions(+), 88 deletions(-) diff --git a/technical-reports/color/color-type.md b/technical-reports/color/color-type.md index c67551f..99dec44 100644 --- a/technical-reports/color/color-type.md +++ b/technical-reports/color/color-type.md @@ -1,6 +1,8 @@ # Color type -Colors can be represented through various formats. For color, the type property must be set to the string “color”. For the value, the most common format to represent color through design tokens is a hex triplet. A hex triplet is a 6-digit, 24 bit, hexadecimal number that represents Red, Green, and Blue values as `#RRGGBB`. +## Hex - required support + +Colors can be represented through various formats. For color tokens, the type property must be set to the string “color”. For the value, the most common format to represent color through design tokens is a hex triplet. A hex triplet is a 6-digit, 24 bit, hexadecimal number that represents Red, Green, and Blue values as `#RRGGBB`. For the initial version of this spec, we expect tools to support Hex values, at minimum. | Pros | Cons | | ------------------------------------------ | -------------------------------------- | @@ -47,21 +49,10 @@ $translucent-shadow: ​hsl(153, 23%, 73%); Formatted in R (red), G (green), B (blue) and (A) alpha. Red, green, and blue values can range from 0 to 255 and alpha values can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity. - - - - - - - - - -
    ProsCons
    -
      -
    • Can define alpha value with color
      • -
    • Alpha value is easy to comprehend at a glance
      • -
    -     		?
    +| Pros | Cons | +| --------------------------------------------- | ---- | +| Can define alpha value with color | ? | +| Alpha value is easy to comprehend at a glance | | For example, initially color tokens may be defined as such: @@ -108,25 +99,9 @@ $translucent-shadow: rgba(171, 202, 188, 50%); Formatted in H (hue), S (saturation), L (lightness) and an optional (A) alpha. Hue values range from 0 to 360, saturation and lightness are percentage values that go from 0% to 100%, and alpha value can range from 0 and 1 (i.e 0.5) or a percentage (i.e 50%) where 1 or %100 is full opacity (which is the default value if a value isn’t provided). - - - - - - - - - -
    ProsCons
    -
      -
    • It is easy to understand compare to other formats
      • -
    • Easy to predict value changes
      • -
    -     		-
      -
    • No supported in older browsers
      • -
    -
    +| Pros | Cons | +| ----------------------------------------------------- | ------------------------------------ | +| It is easy to understand and compare to other formats | Limited browser support (XXXXX only) |