Core/dp 20570 design tokens

packages/core/stories/styles/index.scss

@@ -49,6 +49,10 @@
   }
 }
 
+small {
+	font-size: .9rem;
+}
+
 .sb-block.borderless {
 	margin: 3rem 0 !important;
 	padding: 0 !important;
@@ -64,7 +68,6 @@
   & > * {
 	  margin-bottom: 2rem;
   }
-
 }
 
 // Match row height

packages/core/stories/tokens/colors/ColorDisplay.js

@@ -8,7 +8,7 @@ const ColorSwatch = ({ name, value, variable, width='200px', height='4rem', copi
   return(
     <div style={{ display: 'flex', flexDirection: inline ? 'row' : 'column' }}>
       { name && <h6>{name}</h6>}
-      <div className="sg-swatch" style={{ background: value, borderRadius: 0, height, width, border: '1px solid #DCDCDC' }} />
+      <div className="sg-swatch" style={{ background: value, borderRadius: 0, height, width, border: '1px solid #EEEEEE' }} />
       <div className="sg-info">
         <span>{hexValue}</span>
         {copiable && <ButtonCopy content={hexValue} />}

packages/core/stories/tokens/colors/Colors.stories.mdx

@@ -1,36 +1,32 @@
 import { Meta } from '@storybook/addon-docs/blocks';
 import generateTitle from '../../util/generateTitle';
 import { ColorSwatch, GradientSpectrum } from './ColorDisplay';
-import { themeColors, grayScaleColors, utilityColors, primaryColors, primaryAltColors, highLightColors } from './colors.json';
+import { themeColors, grayScaleColors, utilityColors, primaryColors, primaryAltColors, highLightColors} from './colors.json';
 
 <Meta title={generateTitle('Colors')} />
 
-# Colors
-Color is a key component of a brand. A well defined suite of colors can effeciently convey the brand and empower visual consistency. Apply colors systemematically across can help users set expections of the meaning and hierarchies of the perceived information.
+# Color
 
+We use color to establish brand consistency across all Massachusetts digital experiences, but also to convey semantic meaning—for example in warnings and alerts—as well as to differentiate categories of information.
 
-## Brand Colors
-Mayflower brand colors are carefully selected to meet the brand pillars and adhere to specific accessibility standards.
-We encourage that all Commonwealth agencies use the same
-suite of colors in order to cement a cohesive image of the Commonwealth
-brand on all public-facing assets and documents.
-Organizations that have their own visual identity are invited to extend this color palette with additional colors that reflect their unique brand in conjunction with the shared Commonwealth identity.
+
+## Theme Colors
+
+The Mayflower brand colors were selected to meet our brand and accessibility standards. All Commonwealth agencies should use these colors—along with other brand imagery—to signal to users that they are seeing official Commonwealth content. Organizations with their own visual identities may extend this color palette with their unique brand colors, but we encourage you to make an effort to harmonize your color palette with Mayflower as much as possible.
 
 <ul className="sg-colors">
   {
     themeColors.map((color, i) => <li key={`themeColors${i}`}><ColorSwatch {...color} variable={color.token} /></li>)
   }
 </ul>
 
-## Theme Colors
-Theme colors are putting brand colors and their variants into use, and assigning them roles and contextual meaning. Think of theme colors as slots for color tokens to systematize color usage.
+### Color hierarchy
 
-### Primary Colors
+`$c-bay-blue` is the **Primary Color** is the default color for links and primary action buttons. Accompanying shades and tints can be used to create depth. It's also used in headings, titles, icons, graphics, and calls to action. `$c-berkshires-green` is the **Alternate Primary Color**, it usually does the same job as the primary color, but when the surrounding context is different, for example in a call-to-action block. `$c-duckling-ellow` is the **Highlight Color** and it's used for time sensitive information like updates and alerts.
 
-**Primary Color** is the default and most often used color on a page and throughout the site. Accompanying
-shades and tints can be used to create depth.
+### Primary Colors
 
-**Examples:** Headings, titles, icons, graphics, calls to action, buttons,
+**Primary Color** is the default and most often used color on a page and throughout the site. Accompanying shades and tints can be used to create depth. **Examples:** Headings, titles, icons, graphics, calls to action, buttons,
 and backgrounds.
 
 <ul className="sg-colors">
@@ -39,60 +35,58 @@ and backgrounds.
   }
 </ul>
 
-**Primary Alt Color** is an alternative primary color.
-It is used to balance the theme and create more variety to the color usage on a page and throughout the site.
-Examples: Headings, titles, icons, graphics, calls to action,
-buttons, and backgrounds.
+**Primary Alt Color** is an alternative primary color. It is used to balance the theme and create more variety to the color usage on a page and throughout the site. Examples: Headings, titles, icons, graphics, calls to action, buttons, and backgrounds.
 
 <ul className="sg-colors">
   {
     primaryAltColors.map((color, i) => <li key={`primaryAltColors${i}`}><ColorSwatch  {...color} /></li>)
   }
 </ul>
 
-### highLight Colors
-The purpose of the highlight colors are to to draw attention to key sections or
-information that usually is time sensitive.
-
-**Examples:** Updates, time changes, alerts.
+### Highlight Colors
+The purpose of the highlight colors are to to draw attention to key sections or information that usually is time sensitive. **Examples:** Updates, time changes, alerts.
 
 <ul className="sg-colors">
   {
     highLightColors.map((color, i) => <li key={`highLightColors${i}`}><ColorSwatch {...color} /></li>)
   }
 </ul>
 
-### Gray Scale Colors
-A set of neutral color used to complement and balance primary and secondary colors. It is the base color for all text on both print and digital materials for Mass.gov.
+### Gray Scale
 
-**Examples:** Body text, icons, and backgrounds.
+A range of neutral grays for text and backgrounds.
 
 <ul className="sg-colors">
   {
     grayScaleColors.map((color, i) => <li key={`grayScaleColors${i}`}><ColorSwatch {...color} /></li>)
   }
 </ul>
 
-### Utility Colors
-Colors that are to convey a specific meaning or serve a particular purpose.
+## Semantic Colors
+
+These colors add specific meanings bassed on UI conventions*. Red connotes "stop", "warning", or "danger"; green connotes "go", or "success". For accessibility avoid using color alone to convey meaning, semantic colors should augment text and images.
+
+Some brand colors like `$c-duckling-ellow` and `$c-berkshires-green` are doing double duty as Semantic colors while others like `$c-bay-blue` and `$c-independence-cranberry` are not. We wanted to keep our palette compact, but be careful not to use `$c-bay-blue` as a focus color or `$c-independence-cranberry` as a warning color.
 
 <ul className="sg-colors">
   {
     utilityColors.map((color, i) => <li key={`utilityColors${i}`}><ColorSwatch {...color} /></li>)
   }
 </ul>
 
-## Color Gradients
+<p>
+	<small>
+		<em>*Under some circumstances internationalized information may need to deviate from the standard if the meanings of colors differ.</em>
+	</small>
+</p>
 
-Gradients are programmatically generated as an extension of the Mayflower color palette in order to meet the needs of data visualization.
+## Tints and shades
 
-The "Light" and "Dark" spectrums are programmatically generated using functions `tint` and `shade` and a 10% percentage intervals for evenness and consistency. If a new color is added to the color system, the gradients can be generated following the same method.
+These are generated as an extension of the Mayflower color palette for places where added color differentiation is needed, for example in charts. They use the functions `tint`, which adds white, and `shade` which adds black, at 10% intervals. If a new color is added to the color system, the tints and shades are generated following the same method.
 
-### Light Gradients
+### Tints
 
-`tint` takes in a `$color` and mixes it with color white. It also takes in a percentage to define the percentage of `$color` in the mix.
-- 0% is the original `$color` and 100% is the color white.
-- Light Gradient Variants include 10%-90% with a 10% interval.
+A `tint` takes a `$color` and mixes it with white. A 0% `tint` is the original `$color` and 100% is white. The range of tints shown are 10% to 90%.
 
 <React.Fragment>
   {
@@ -110,13 +104,9 @@ The "Light" and "Dark" spectrums are programmatically generated using functions
   }
 </React.Fragment>
 
+### Shades
 
-
-### Dark Gradients
-
-`shade` takes in a `$color` and mixes it with color black. It also takes in a percentage to define the percentage of `$color` in the mix.
-- 0% is the original `$color` and 100% is the color black.
-- Dark Gradient Variants include 10%-50% with a 10% interval.
+A `shade` takes a `$color` and mixes it with black. A 0% `shade` is the original `$color` and 100% is black. Since shades above 50% are hard to distinguish and less useful, the range of shades are 10% to 50%.
 
 <React.Fragment>
   {

packages/core/stories/tokens/colors/_color-display.scss

@@ -20,7 +20,7 @@
       min-width: 7rem;
 
       h6 {
-        font-size: $fonts-small;
+        font-size: 1rem;
       }
     }
 

packages/core/stories/tokens/colors/colors.json

@@ -27,10 +27,9 @@
     {
       "variable": "$c-independence-cranberry",
       "token": "$c-independence-cranberry",
-      "name": "Independent Cranberry",
+      "name": "Independence Cranberry",
       "value": "#680A1D"
-    }
-  ],
+    }],
   "grayScaleColors":[
     {
       "variable": "$c-black",
@@ -56,19 +55,13 @@
       "variable": "$c-gray-lightest",
       "name": "Platinum Gray",
       "value": "#f2f2f2"
-    }
-  ],
+    }],
   "utilityColors": [
     {
       "variable": "$c-error-red",
       "name": "Error Red",
       "value": "#CD0D0D"
     },
-    {
-      "variable": "$c-focus",
-      "name": "Focus Hightlight",
-      "value": "#3e94cf"
-    },
     {
       "variable": "$c-warning",
       "name": "Warning Yellow",
@@ -78,54 +71,58 @@
       "variable": "$c-success",
       "name": "Success Green",
       "value": "#388557"
-    }
-  ],
-  "primaryColors": [
-    {
-      "variable": "$c-primary",
-      "name": "Bay Blue",
-      "value": "#14558f"
-    },
-    {
-      "variable": "$c-primary-lighter",
-      "name": "50% Bay Blue",
-      "value": "#8aaac7"
-    },
-    {
-      "variable": "$c-primary-lightest",
-      "name": "10% Bay Blue",
-      "value": "#e7eef4"
-    }],
-  "primaryAltColors": [
-    {
-      "variable": "$c-primary-alt",
-      "name": "Berkshires Green",
-      "value": "#388557"
-    },
-    {
-      "variable": "$c-primary-alt-lighter",
-      "name": "50% Berkshires Green",
-      "value": "#97c2a9"
     },
-    {
-      "variable": "$c-primary-alt-lightest",
-      "name": "10% Berkshires Green",
-      "value": "#EBF3EE"
+		{
+      "variable": "$c-focus",
+      "name": "Focus Hightlight",
+      "value": "#3e94cf"
     }],
-  "highLightColors": [
-    {
-      "variable": "$c-highlight",
-      "name": "Duckling Yellow",
-      "value": "#f6c51b"
-    },
-    {
-      "variable": "$c-highlight-lighter",
-      "name": "50% Duckling Yellow",
-      "value": "#fbe28d"
-    },
-    {
-      "variable": "$c-highlight-lightest",
-      "name": "10% Duckling Yellow",
-      "value": "#fef9e8"
-    }]
+	"primaryColors": [
+		{
+			"variable": "$c-primary",
+			"name": "Bay Blue",
+			"value": "#14558f"
+		},
+		{
+			"variable": "$c-primary-lighter",
+			"name": "50% Bay Blue",
+			"value": "#8aaac7"
+		},
+		{
+			"variable": "$c-primary-lightest",
+			"name": "10% Bay Blue",
+			"value": "#e7eef4"
+		}],
+	"primaryAltColors": [
+		{
+			"variable": "$c-primary-alt",
+			"name": "Berkshires Green",
+			"value": "#388557"
+		},
+		{
+			"variable": "$c-primary-alt-lighter",
+			"name": "50% Berkshires Green",
+			"value": "#97c2a9"
+		},
+		{
+			"variable": "$c-primary-alt-lightest",
+			"name": "10% Berkshires Green",
+			"value": "#EBF3EE"
+		}],
+	"highLightColors": [
+		{
+			"variable": "$c-highlight",
+			"name": "Duckling Yellow",
+			"value": "#f6c51b"
+		},
+		{
+			"variable": "$c-highlight-lighter",
+			"name": "50% Duckling Yellow",
+			"value": "#fbe28d"
+		},
+		{
+			"variable": "$c-highlight-lightest",
+			"name": "10% Duckling Yellow",
+			"value": "#fef9e8"
+		}]
 }