ui: Fix brand coloring for inline-code plus docs (#11578)

* ui: Fix brand coloring for inline-code plus docs

Also use --tones instead of --black/--white (#11601)

Co-authored-by: Evan Rowe <ev.rowe@gmail.com>

.changelog/11578.txt

@@ -0,0 +1,3 @@
+```release-note:bug
+ui: Fix inline-code brand styling
+```

ui/packages/consul-ui/.docfy-config.js

@@ -50,6 +50,12 @@ module.exports = {
       urlSchema: 'auto',
       urlPrefix: 'docs',
     },
+    {
+      root: path.resolve(__dirname, 'app/styles'),
+      pattern: '**/*.mdx',
+      urlSchema: 'auto',
+      urlPrefix: 'docs/styles',
+    },
     {
       root: path.resolve(__dirname, 'app/modifiers'),
       pattern: '**/*.mdx',

ui/packages/consul-ui/app/components/auth-form/skin.scss

@@ -8,5 +8,5 @@
 /* in the center so if the background color of what the */
 /* line is on is different, then this should be different */
 %auth-form-hr span {
-  background-color: rgb(var(--white));
+  background-color: rgb(var(--tone-gray-000));
 }

ui/packages/consul-ui/app/components/card/skin.scss

@@ -5,7 +5,7 @@
 %card {
   border: var(--decor-border-100);
   border-radius: var(--decor-radius-100);
-  background-color: rgb(var(--white) / 90%);
+  background-color: rgb(var(--tone-gray-000) / 90%);
 }
 %card > section,
 %card > ul > li {

ui/packages/consul-ui/app/components/certificate/index.scss

@@ -20,7 +20,7 @@
   }
   hr {
     border: 3px dashed rgb(var(--tone-gray-300));
-    background-color: rgb(var(--white));
+    background-color: rgb(var(--tone-gray-000));
     width: 150px;
     margin: auto;
     margin-top: 9px;

ui/packages/consul-ui/app/components/code-editor/layout.scss

@@ -11,7 +11,7 @@
   bottom: 0px;
   width: 100%;
   height: 25px;
-  background-color: var(--black);
+  background-color: rgb(var(--tone-gray-999));
   content: '';
   display: block;
 }

ui/packages/consul-ui/app/components/code-editor/skin.scss

@@ -46,7 +46,7 @@ $syntax-dark-gray: #535f73;
 .cm-s-hashi {
   &.CodeMirror {
     width: 100%;
-    background-color: rgb(var(--black)) !important;
+    background-color: rgb(var(--tone-gray-999)) !important;
     color: #cfd2d1 !important;
     border: none;
     font-family: var(--typo-family-mono);
@@ -81,7 +81,7 @@ $syntax-dark-gray: #535f73;
   .CodeMirror-line::-moz-selection,
   .CodeMirror-line > span::-moz-selection,
   .CodeMirror-line > span > span::-moz-selection {
-    background: rgb(var(--white) / 10%);
+    background: rgb(var(--tone-gray-000) / 10%);
   }
 
   span.cm-comment {
@@ -154,7 +154,7 @@ $syntax-dark-gray: #535f73;
 
   .CodeMirror-matchingbracket {
     text-decoration: underline;
-    color: rgb(var(--white)) !important;
+    color: rgb(var(--tone-gray-000)) !important;
   }
 }
 
@@ -178,7 +178,7 @@ $syntax-dark-gray: #535f73;
     }
 
     span.cm-property {
-      color: rgb(var(--white));
+      color: rgb(var(--tone-gray-000));
     }
 
     span.cm-variable-2 {

ui/packages/consul-ui/app/components/composite-row/index.scss

@@ -113,5 +113,5 @@
 %composite-row-header .policy-management dd::before,
 %composite-row-detail .policy-management::before {
   @extend %with-star-fill-mask, %as-pseudo;
-  background-color: rgb(var(--brand-600));
+  background-color: rgb(var(--tone-brand-600));
 }

ui/packages/consul-ui/app/components/confirmation-dialog/skin.scss

@@ -1,5 +1,5 @@
 table div.with-confirmation.confirming {
-  background-color: rgb(var(--white));
+  background-color: rgb(var(--tone-gray-000));
 }
 %confirmation-dialog-inline p {
   color: rgb(var(--tone-gray-400));

ui/packages/consul-ui/app/components/consul/auth-method/index.scss

@@ -27,7 +27,7 @@
       tbody {
         td {
           font-size: var(--typo-size-600);
-          color: var(--black);
+          color: rgb(var(--tone-gray-999));
         }
         tr {
           cursor: default;
@@ -74,7 +74,7 @@
   tbody {
     td {
       font-size: var(--typo-size-600);
-      color: var(--black);
+      color: rgb(var(--tone-gray-999));
     }
     tr {
       cursor: default;

ui/packages/consul-ui/app/components/consul/discovery-chain/index.hbs

@@ -3,7 +3,7 @@
     {{selected.nodes}} {
       opacity: 1 !important;
 
-      background-color: var(--white);
+      background-color: var(--tone-gray-000);
       border: var(--decor-border-100);
       border-radius: var(--decor-radius-200);
       border-color: rgb(var(--tone-gray-500));

ui/packages/consul-ui/app/components/consul/discovery-chain/skin.scss

@@ -63,7 +63,7 @@
 }
 %chain-node-active {
   opacity: 1;
-  background-color: rgb(var(--white));
+  background-color: rgb(var(--tone-gray-000));
   border-color: rgb(var(--tone-gray-500));
 }
 /* TODO: More text truncation, centralize */
@@ -99,7 +99,7 @@
 /**/
 %with-chain-outlet::before {
   @extend %as-pseudo;
-  background-color: rgb(var(--white));
+  background-color: rgb(var(--tone-gray-000));
 
   border-radius: var(--decor-radius-full);
   border: 2px solid rgb(var(--tone-gray-400));
@@ -107,5 +107,5 @@
 %discovery-chain circle {
   stroke-width: 2;
   stroke: rgb(var(--tone-gray-400));
-  fill: rgb(var(--white));
+  fill: rgb(var(--tone-gray-000));
 }

ui/packages/consul-ui/app/components/consul/loader/skin.scss

@@ -1,5 +1,5 @@
 %loader circle {
-  fill: rgb(var(--brand-100));
+  fill: rgb(var(--tone-brand-100));
 }
 %loader circle {
   animation: loader-animation 1.5s infinite ease-in-out;

ui/packages/consul-ui/app/components/expanded-single-select/skin.scss

@@ -14,5 +14,5 @@
 %expanded-single-select input[type='radio']:checked + *,
 %expanded-single-select input[type='radio']:hover + *,
 %expanded-single-select input[type='radio']:focus + * {
-  background-color: rgb(var(--white));
+  background-color: rgb(var(--tone-gray-000));
 }

ui/packages/consul-ui/app/components/freetext-filter/skin.scss

@@ -3,7 +3,7 @@
     border: var(--decor-border-100);
     border-radius: var(--decor-radius-100);
 
-    background-color: rgb(var(--white));
+    background-color: rgb(var(--tone-gray-000));
     border-color: rgb(var(--tone-gray-200));
     color: rgb(var(--tone-gray-400));
   }

ui/packages/consul-ui/app/components/hashicorp-consul/index.scss

@@ -7,7 +7,7 @@
     display: none;
   }
   [role='banner'] a svg {
-    fill: rgb(var(--brand-600));
+    fill: rgb(var(--tone-brand-600));
   }
   .docs-link a::after {
     @extend %with-docs-mask, %as-pseudo;

ui/packages/consul-ui/app/components/informed-action/skin.scss

@@ -3,7 +3,7 @@
     border-radius: var(--decor-radius-200);
     border: var(--decor-border-100);
     border-color: rgb(var(--tone-gray-300));
-    background-color: rgb(var(--white));
+    background-color: rgb(var(--tone-gray-000));
   }
   > div {
     border-top-left-radius: var(--decor-radius-200);
@@ -18,7 +18,7 @@
   }
   p {
     @extend %p2;
-    color: var(--black);
+    color: rgb(var(--tone-gray-999));
   }
   > ul {
     list-style: none;

ui/packages/consul-ui/app/components/inline-code/skin.scss

@@ -1,6 +1,6 @@
 %inline-code {
   border: 1px solid;
-  color: var(rgb(var(--brand-600)), inherit);
+  color: rgb(var(--tone-brand-600));
   background-color: rgb(var(--tone-gray-050));
   border-color: rgb(var(--tone-gray-200));
 }

ui/packages/consul-ui/app/components/list-row/skin.scss

@@ -13,7 +13,7 @@
   cursor: pointer;
 }
 %list-row-header {
-  color: var(--black);
+  color: rgb(var(--tone-gray-999));
 }
 %list-row-header * {
   color: inherit;

ui/packages/consul-ui/app/components/modal-dialog/skin.scss

@@ -15,7 +15,7 @@
   margin-right: 3px;
 }
 %modal-dialog-overlay {
-  background-color: rgb(var(--white) / 90%);
+  background-color: rgb(var(--tone-gray-000) / 90%);
 }
 %modal-window {
   box-shadow: var(--decor-elevation-800);

ui/packages/consul-ui/app/components/notice/skin.scss

@@ -1,7 +1,7 @@
 %notice {
   border-radius: var(--decor-radius-100);
   border: var(--decor-border-100);
-  color: var(--black);
+  color: rgb(var(--tone-gray-999));
 }
 %notice::before {
   @extend %as-pseudo;

ui/packages/consul-ui/app/components/overlay/none.scss

@@ -26,7 +26,7 @@
     transition-timing-function: cubic-bezier(0.54, 1.5, 0.38, 1.11);
   }
   & {
-    background-color: rgb(var(--white));
+    background-color: rgb(var(--tone-gray-000));
     border-radius: var(--decor-radius-100);
     box-shadow: var(--decor-elevation-400);
   }

ui/packages/consul-ui/app/components/overlay/square-tail.scss

@@ -4,7 +4,7 @@
     left: calc(0px - (var(--size) / 2)) !important;
   }
   .tippy-arrow::before {
-    background-color: rgb(var(--white));
+    background-color: rgb(var(--tone-gray-000));
     width: calc(1px + var(--size));
     height: calc(1px + var(--size));
     border: var(--decor-border-100);

ui/packages/consul-ui/app/components/radio-card/skin.scss

@@ -19,7 +19,7 @@
   margin-bottom: 0.5em;
 }
 %radio-card header {
-  color: var(--black);
+  color: rgb(var(--tone-gray-999));
 }
 %radio-card-with-icon > :last-child {
   padding-left: 47px;

ui/packages/consul-ui/app/components/skip-links/skin.scss

@@ -1,6 +1,6 @@
 %skip-links {
-  outline: 1px solid rgb(var(--white));
+  outline: 1px solid rgb(var(--tone-gray-000));
-  color: rgb(var(--white));
+  color: rgb(var(--tone-gray-000));
   background-color: rgb(var(--tone-blue-500));
 }
 %skip-links button,

ui/packages/consul-ui/app/components/sliding-toggle/skin.scss

@@ -18,7 +18,7 @@
   color: rgb(var(--tone-gray-900));
 }
 %sliding-toggle label span::after {
-  background-color: rgb(var(--white));
+  background-color: rgb(var(--tone-gray-000));
 }
 %sliding-toggle label input:checked + span::before,
 %sliding-toggle-negative label input + span::before {

ui/packages/consul-ui/app/components/tabular-details/skin.scss

@@ -14,7 +14,7 @@
 %tabular-detail::before,
 %tabular-detail > div,
 %tabular-detail > label {
-  background-color: rgb(var(--white));
+  background-color: rgb(var(--tone-gray-000));
 }
 %tabular-detail > label::before {
   transform: rotate(180deg);

ui/packages/consul-ui/app/components/tabular-dl/skin.scss

@@ -6,13 +6,13 @@
   dt,
   dd {
     border-color: rgb(var(--tone-gray-300)) !important;
-    color: var(--black) !important;
+    color: rgb(var(--tone-gray-999)) !important;
   }
   dt {
     font-weight: var(--typo-weight-bold);
   }
   dd .copy-button button::before {
-    background-color: var(--black);
+    background-color: rgb(var(--tone-gray-999));
   }
   dt.type + dd span::before {
     @extend %with-info-circle-outline-mask, %as-pseudo;

ui/packages/consul-ui/app/components/tooltip/index.scss

@@ -32,7 +32,7 @@
 %tooltip-bubble {
   & {
     background-color: rgb(var(--tone-gray-700));
-    color: rgb(var(--white));
+    color: rgb(var(--tone-gray-000));
   }
 }
 %tooltip-tail {

ui/packages/consul-ui/app/components/topology-metrics/card/index.scss

@@ -7,7 +7,7 @@
   display: block;
   color: rgb(var(--tone-gray-700));
   overflow: hidden;
-  background-color: rgb(var(--white));
+  background-color: rgb(var(--tone-gray-000));
   border-radius: var(--decor-radius-100);
   border: 1px solid rgb(var(--tone-gray-200));
   p {

ui/packages/consul-ui/app/components/topology-metrics/popover/index.scss

@@ -2,7 +2,7 @@
   > button {
     position: absolute;
     transform: translate(-50%, -50%);
-    background-color: rgb(var(--white));
+    background-color: rgb(var(--tone-gray-000));
     padding: 1px 1px;
     &:hover {
       cursor: pointer;

ui/packages/consul-ui/app/components/topology-metrics/skin.scss

@@ -24,7 +24,7 @@
 // Metrics Container
 #metrics-container {
   div:first-child {
-    background-color: rgb(var(--white));
+    background-color: rgb(var(--tone-gray-000));
   }
   .link {
     background-color: rgb(var(--tone-gray-100));
@@ -53,7 +53,7 @@
     fill: var(--transparent);
   }
   circle {
-    fill: rgb(var(--white));
+    fill: rgb(var(--tone-gray-000));
   }
   .allow-arrow {
     fill: rgb(var(--tone-gray-300));

ui/packages/consul-ui/app/modifiers/css-props.js

@@ -0,0 +1,39 @@
+import { modifier } from 'ember-modifier';
+const STYLE_RULE = 1;
+const getCustomProperties = function() {
+  return Object.fromEntries(
+    [...document.styleSheets].reduce(
+      (prev, item) =>
+        prev.concat(
+          [...item.cssRules]
+            .filter(item => item.type === STYLE_RULE)
+            .reduce((prev, rule) => {
+              const props = [...rule.style]
+                .filter(prop => prop.startsWith('--'))
+                .map(prop => [prop.trim(), rule.style.getPropertyValue(prop).trim()]);
+              return [...prev, ...props];
+            }, [])
+        ),
+      []
+    )
+  );
+};
+const props = getCustomProperties();
+export default modifier(function($element, [returns], hash) {
+    const re = new RegExp(`^--${hash.prefix || '.'}${hash.group || ''}+`);
+    const obj = {};
+    Object.entries(props).forEach(([key, value]) => {
+      const res = key.match(re);
+      if(res) {
+        let prop = res[0];
+        if (prop.charAt(prop.length - 1) === '-') {
+          prop = prop.substr(0, prop.length - 1);
+        }
+        if (typeof obj[prop] === 'undefined') {
+          obj[prop] = {};
+        }
+        obj[prop][key] = value;
+      }
+    });
+    returns(obj);
+});

ui/packages/consul-ui/app/styles/base/color/README.mdx

@@ -0,0 +1,81 @@
+# Colors
+
+All colors for the immediate future should _mostly_ use the following `tone`
+CSS properties, unless:
+
+1. We get around to eventually adding semantic colors names (or adding something else) in which case these docs should be updated.
+2. You are absolutely sure the color you want should never be changed by a theme. These should be very very few and far between so even if we get that wrong it should be easy to update.
+
+`tones` should always using the following form:
+
+```css
+property: rgb(var(--tone-gray-500));
+```
+
+In other words always use `rgb` this gives us the flexibility to easily use these variables with alpha if we ever need to.
+
+```css
+property: rgb(var(--tone-gray-500) / 50);
+```
+
+Currently, alphas are mainly used for shadows. Please avoid the use of alphas for adjusting hues as they can produce unpredictable results. We should be utilizing our pre-defined color palette or adding new colors to it with proper RGB values. If you do need to add a color with alpha, please include a code comment or a self-comment explaining the use case.
+
+Lastly, there is currently one non-color alias group which is `--tone-brand` which is a group of our current brand colors.
+
+
+## %theme-light (default)
+
+```hbs preview-template
+<ul
+  {{css-props (set this 'tones')
+    prefix='tone-'
+    group='[a-z\-]'
+  }}
+>
+{{#each-in this.tones as |prop value|}}
+  <li>
+    {{#each-in value as |prop value|}}
+    <figure
+      {{with-copyable (concat "rgb(var(" prop "));")}}
+      style={{concat "background-color: rgb(var(" prop "))"}}
+    >
+      <figcaption>{{prop}}</figcaption>
+    </figure>
+    {{/each-in}}
+  </li>
+{{/each-in}}
+</ul>
+```
+
+## %theme-dark
+
+If you need to build something (like a component or view) which begins in 'dark mode', you will need to switch your coloring and use
+
+```css
+%component-name {
+  @extend %theme-dark;
+}
+```
+
+```hbs preview-template
+<ul
+  {{css-props (set this 'tones')
+    prefix='tone-'
+    group='[a-z\-]'
+  }}
+>
+{{#each-in this.tones as |prop value|}}
+  <li>
+    {{#each-in value as |prop value|}}
+    <figure
+      {{with-copyable (concat "rgb(var(" prop "));")}}
+      style={{concat "background-color: rgb(var(" prop "))"}}
+    >
+      <figcaption>{{prop}}</figcaption>
+    </figure>
+    {{/each-in}}
+  </li>
+{{/each-in}}
+</ul>
+```
+

ui/packages/consul-ui/app/styles/base/color/ui/frame-placeholders.scss

@@ -9,8 +9,8 @@
 %frame-brand-300 {
   @extend %frame-border-000;
   background-color: var(--transparent);
-  border-color: rgb(var(--decor-brand-600, inherit));
+  border-color: rgb(var(--decor-brand-600));
-  color: rgb(var(--typo-brand-600, inherit));
+  color: rgb(var(--typo-brand-600));
 }
 
 /* possibly filter bar */

ui/packages/consul-ui/app/styles/base/color/ui/themes/dark-high-contrast.scss

@@ -95,22 +95,5 @@
   --tone-yellow-950: var(--yellow-950);
   --tone-yellow-999: var(--black);
 
-  --tone-yellow-000: var(--white);
-  --tone-yellow-050: var(--yellow-050);
-  --tone-yellow-100: var(--yellow-100);
-  --tone-yellow-150: var(--yellow-150);
-  --tone-yellow-200: var(--yellow-200);
-  --tone-yellow-300: var(--yellow-300);
-  --tone-yellow-400: var(--yellow-400);
-  --tone-yellow-500: var(--yellow-500);
-  --tone-yellow-600: var(--yellow-600);
-  --tone-yellow-700: var(--yellow-700);
-  --tone-yellow-800: var(--yellow-800);
-  --tone-yellow-850: var(--yellow-850);
-  --tone-yellow-900: var(--yellow-900);
-  --tone-yellow-950: var(--yellow-950);
-  --tone-yellow-999: var(--black);
-
   --tone-transparent: var(--transparent);
 }
-

ui/packages/consul-ui/app/styles/base/color/ui/themes/dark.scss

@@ -79,38 +79,21 @@
   --tone-orange-950: var(--orange-950);
   --tone-orange-999: var(--black);
 
-  --tone-yellow-000: var(--white);
+  --tone-yellow-000: var(--black);
-  --tone-yellow-050: var(--yellow-050);
+  --tone-yellow-050: var(--blue-950);
-  --tone-yellow-100: var(--yellow-100);
+  --tone-yellow-100: var(--yellow-900);
-  --tone-yellow-150: var(--yellow-150);
+  --tone-yellow-150: var(--yellow-850);
-  --tone-yellow-200: var(--yellow-200);
+  --tone-yellow-200: var(--yellow-800);
-  --tone-yellow-300: var(--yellow-300);
+  --tone-yellow-300: var(--yellow-700);
-  --tone-yellow-400: var(--yellow-400);
+  --tone-yellow-400: var(--yellow-600);
   --tone-yellow-500: var(--yellow-500);
-  --tone-yellow-600: var(--yellow-600);
+  --tone-yellow-600: var(--yellow-400);
-  --tone-yellow-700: var(--yellow-700);
+  --tone-yellow-700: var(--yellow-300);
-  --tone-yellow-800: var(--yellow-800);
+  --tone-yellow-800: var(--yellow-200);
-  --tone-yellow-850: var(--yellow-850);
+  --tone-yellow-850: var(--yellow-250);
-  --tone-yellow-900: var(--yellow-900);
+  --tone-yellow-900: var(--yellow-100);
-  --tone-yellow-950: var(--yellow-950);
+  --tone-yellow-950: var(--yellow-050);
-  --tone-yellow-999: var(--black);
+  --tone-yellow-999: var(--white);
-
-  --tone-yellow-000: var(--white);
-  --tone-yellow-050: var(--yellow-050);
-  --tone-yellow-100: var(--yellow-100);
-  --tone-yellow-150: var(--yellow-150);
-  --tone-yellow-200: var(--yellow-200);
-  --tone-yellow-300: var(--yellow-300);
-  --tone-yellow-400: var(--yellow-400);
-  --tone-yellow-500: var(--yellow-500);
-  --tone-yellow-600: var(--yellow-600);
-  --tone-yellow-700: var(--yellow-700);
-  --tone-yellow-800: var(--yellow-800);
-  --tone-yellow-850: var(--yellow-850);
-  --tone-yellow-900: var(--yellow-900);
-  --tone-yellow-950: var(--yellow-950);
-  --tone-yellow-999: var(--black);
 
   --tone-transparent: var(--transparent);
 }
-

ui/packages/consul-ui/app/styles/base/color/ui/themes/light-high-contrast.scss

@@ -95,21 +95,5 @@
   --tone-yellow-950: var(--yellow-950);
   --tone-yellow-999: var(--black);
 
-  --tone-yellow-000: var(--white);
-  --tone-yellow-050: var(--yellow-050);
-  --tone-yellow-100: var(--yellow-100);
-  --tone-yellow-150: var(--yellow-150);
-  --tone-yellow-200: var(--yellow-200);
-  --tone-yellow-300: var(--yellow-300);
-  --tone-yellow-400: var(--yellow-400);
-  --tone-yellow-500: var(--yellow-500);
-  --tone-yellow-600: var(--yellow-600);
-  --tone-yellow-700: var(--yellow-700);
-  --tone-yellow-800: var(--yellow-800);
-  --tone-yellow-850: var(--yellow-850);
-  --tone-yellow-900: var(--yellow-900);
-  --tone-yellow-950: var(--yellow-950);
-  --tone-yellow-999: var(--black);
-
   --tone-transparent: var(--transparent);
 }

ui/packages/consul-ui/app/styles/base/color/ui/themes/light.scss

@@ -95,21 +95,5 @@
   --tone-yellow-950: var(--yellow-950);
   --tone-yellow-999: var(--black);
 
-  --tone-yellow-000: var(--white);
-  --tone-yellow-050: var(--yellow-050);
-  --tone-yellow-100: var(--yellow-100);
-  --tone-yellow-150: var(--yellow-150);
-  --tone-yellow-200: var(--yellow-200);
-  --tone-yellow-300: var(--yellow-300);
-  --tone-yellow-400: var(--yellow-400);
-  --tone-yellow-500: var(--yellow-500);
-  --tone-yellow-600: var(--yellow-600);
-  --tone-yellow-700: var(--yellow-700);
-  --tone-yellow-800: var(--yellow-800);
-  --tone-yellow-850: var(--yellow-850);
-  --tone-yellow-900: var(--yellow-900);
-  --tone-yellow-950: var(--yellow-950);
-  --tone-yellow-999: var(--black);
-
   --tone-transparent: var(--transparent);
 }

ui/packages/consul-ui/app/styles/base/icons/README.mdx

@@ -0,0 +1,74 @@
+# Iconography
+
+Please prefer our Constructable `%placeholder` styles over singular CSS
+properties. If you need to drop back, to something not covered there then you
+can also use CSS properties directly.
+
+All icons use a `%with-` prefix for example `%with-alert-circle-fill-icon` or
+`%with-alert-circle-fill-mask`. We mostly use the `-mask` suffix and also use
+the `%as-pseudo` placeholder to tell CSS that we are using the background on a
+pseudo element:
+
+```css
+.selector::before {
+  @extend %with-alert-circle-fill-mask, %as-pseudo;
+}
+```
+
+If you are not using a pseudo element for whatever reason, then you do not need
+to use `%as-pseudo`.
+
+When using `-mask` icons, color will use the `currentColor` of the element. If
+you need the color of the icon to be different to the text you can define the
+color of the icon itself via the `color` CSS property (preferred) but you can
+also use `background-color`.
+
+```css
+.selector::before {
+  @extend %with-alert-circle-fill-mask, %as-pseudo;
+  color: rgb(var(--tone-strawberry-500));
+}
+```
+
+If you need to use a colored icon (usually an existing brand icon) then don't
+use `-mask`, use `-icon` instead:
+
+```css
+.selector::before {
+  @extend %with-logo-consul-color-icon, %as-pseudo;
+}
+```
+
+## Structure Icons + Consul Specific Icons
+
+```hbs preview-template
+<ul>
+{{#each (icons-debug 'structure') as |prop|}}
+  <li>
+    <figure
+      {{with-copyable (concat "@extend %" prop.placeholder ", %as-pseudo;")}}
+      class={{concat 'debug-' prop.placeholder '-before'}}
+    >
+      <figcaption>{{prop.name}}</figcaption>
+    </figure>
+  </li>
+{{/each}}
+</ul>
+```
+
+## Flight Icons
+
+```hbs preview-template
+<ul>
+{{#each (icons-debug 'flight') as |prop|}}
+  <li>
+    <figure
+      {{with-copyable (concat "@extend %" prop.placeholder ", %as-pseudo;")}}
+      class={{concat 'debug-' prop.placeholder '-before'}}
+    >
+      <figcaption>{{prop.name}}</figcaption>
+    </figure>
+  </li>
+{{/each}}
+</ul>
+```

ui/packages/consul-ui/app/styles/base/icons/base-placeholders.scss

@@ -3,6 +3,8 @@
   background-position: center;
 }
 %with-mask {
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
   mask-repeat: no-repeat;
   mask-position: center;
   background-color: currentColor;

ui/packages/consul-ui/app/styles/base/typography/README.mdx

@@ -0,0 +1,143 @@
+# Typography
+
+Please prefer our Constructable `%placeholder` styles over singular CSS
+properties. If you need to drop back, to something not covered there then you
+can also use CSS properties directly. Our constructable `%placeholder` should be
+revisted every so often to re-evaluate any areas we we use CSS properties over
+constructables. Naming is mostly set out to allow for future scales that land
+'inbetween' currently scales to aid in continously re-evaluating without getting
+stuck having to change everything every time we need to.
+
+The `%placeholder`s are currently a little inconsistent and styled following
+past specifications. Moving forwards these will become more consistent.
+
+## Constructable %placeholders
+
+### %h000 (headers)
+
+When authoring headers in markup, the correct semantic HTML tag should be used taking into account page order. Following that the correct `%placeholder` can be used to make that header look how it should.
+
+```html
+<h2>H2 Level meaning that looks like a h3 visually</h2>
+```
+```css
+.top-level-selector h2 {
+  /* make the h2 look like a h3 */
+  @extend %h300;
+}
+```
+
+```hbs preview-template
+<ul
+>
+{{#each (array 'h000' 'h100' 'h200' 'h300' 'h400' 'h500' 'h600') as |prop|}}
+  <li>
+    <figure
+      {{with-copyable (concat "@extend %" prop ";")}}
+      class={{concat 'debug-' prop}}
+    >
+        Ab
+      <figcaption>%{{prop}}</figcaption>
+    </figure>
+  </li>
+{{/each}}
+</ul>
+```
+
+### %p (body copy)
+
+```hbs preview-template
+<ul
+>
+{{#each (array 'p' 'p1' 'p2' 'p3') as |prop|}}
+  <li>
+    <figure
+      {{with-copyable (concat "@extend %" prop ";")}}
+      class={{concat 'debug-' prop}}
+    >
+        Ab
+      <figcaption>%{{prop}}</figcaption>
+    </figure>
+  </li>
+{{/each}}
+</ul>
+```
+
+
+## CSS props
+
+
+### Font sizes
+
+```hbs preview-template
+<ul
+  {{css-props (set this 'sizes')
+    prefix='typo-size'
+    group='[-]'
+  }}
+>
+{{#each-in this.sizes as |prop value|}}
+    {{#each-in value as |prop value|}}
+  <li>
+    <figure
+      {{with-copyable (concat "var(" prop ");")}}
+      style={{concat "font-size: var(" prop ")"}}
+    >
+        Ab
+      <figcaption style="font-size: 12px !important;">{{prop}} ({{value}})</figcaption>
+    </figure>
+  </li>
+    {{/each-in}}
+{{/each-in}}
+</ul>
+```
+
+### Font weights
+
+```hbs preview-template
+<ul
+  {{css-props (set this 'weights')
+    prefix='typo-weight'
+    group='[-]'
+  }}
+>
+{{#each-in this.weights as |prop value|}}
+    {{#each-in value as |prop value|}}
+  <li>
+    <figure
+      {{with-copyable (concat "var(" prop ");")}}
+      style={{concat "font-weight: var(" prop ")"}}
+    >
+        Ab
+      <figcaption style="font-weight: normal !important;">{{prop}} ({{value}})</figcaption>
+    </figure>
+  </li>
+    {{/each-in}}
+{{/each-in}}
+</ul>
+```
+
+### Font families
+
+```hbs preview-template
+<ul
+  {{css-props (set this 'families')
+    prefix='typo-family'
+    group='[-]'
+  }}
+>
+{{#each-in this.families as |prop value|}}
+    {{#each-in value as |prop value|}}
+  <li>
+    <figure
+      {{with-copyable (concat "var(" prop ");")}}
+      style={{concat "font-family: var(" prop ")"}}
+    >
+        Ab
+      <figcaption style="font-family: monospace !important;">{{prop}} ({{value}})</figcaption>
+    </figure>
+  </li>
+    {{/each-in}}
+{{/each-in}}
+</ul>
+```

ui/packages/consul-ui/app/styles/debug.scss

@@ -1,4 +1,5 @@
 @import './app';
+@import './base/icons/debug';
 @import 'prism-coldark-dark';
 
 // temporary component debugging setup
@@ -10,6 +11,91 @@
 @import 'consul-ui/components/inline-alert/debug';
 @import 'consul-ui/components/definition-table/debug';
 
+%debug-grid {
+  display: flex;
+  flex-wrap: wrap;
+}
+%debug-grid li {
+  margin-right: 20px;
+  margin-bottom: 20px;
+}
+%debug-grid figure {
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: space-between;
+  width: 140px;
+}
+%debug-grid figcaption {
+  @extend %p3;
+  text-align: center;
+}
+[id^="docfy-demo-preview-color"] ul,
+[id^="docfy-demo-preview-typography"] ul,
+[id^="docfy-demo-preview-icons"] ul {
+  @extend %debug-grid;
+}
+
+[id^="docfy-demo-preview-typography"] figure,
+[id^="docfy-demo-preview-icons"] figure {
+  border: var(--decor-border-100);
+  border-color: rgb(var(--tone-gray-300));
+  height: 80px;
+}
+[id^="docfy-demo-preview-icons"] figure::before {
+  position: relative;
+  top: 20px;
+}
+
+[id^="docfy-demo-preview-color"] figure {
+  height: 40px;
+}
+#docfy-demo-preview-color0 {
+  @extend %theme-light;
+  background-color: rgb(var(--white));
+}
+#docfy-demo-preview-color1 {
+  background-color: rgb(var(--black));
+  @extend %theme-dark;
+}
+
+[id^="docfy-demo-preview-typography"] {
+  .debug-h000 {
+    @extend %h000;
+  }
+  .debug-h100 {
+    @extend %h100;
+  }
+  .debug-h200 {
+    @extend %h200;
+  }
+  .debug-h300 {
+    @extend %h300;
+  }
+  .debug-h400 {
+    @extend %h400;
+  }
+  .debug-h500 {
+    @extend %h500;
+  }
+  .debug-h600 {
+    @extend %h600;
+  }
+  .debug-p {
+    @extend %p;
+  }
+  .debug-p1 {
+    @extend %p1;
+  }
+  .debug-p2 {
+    @extend %p2;
+  }
+  .debug-p3 {
+    @extend %p3;
+  }
+}
+
 html.is-debug body > .brand-loader {
   display: none !important;
 }
@@ -49,6 +135,9 @@ html.with-route-announcer .route-title {
   display: none;
 }
 .docs {
+  & {
+    background-color: rgb(var(--tone-gray-000));
+  }
   .tabular-collection,
   .list-collection {
     height: 300px !important;
@@ -78,7 +167,6 @@ html.with-route-announcer .route-title {
   }
   main {
     & {
-      background-color: white;
       margin-bottom: 2rem;
     }
     > ol,

ui/packages/consul-ui/app/styles/variables/skin.scss

@@ -5,27 +5,27 @@
 // unused CSS props
 :root {
   /* base brand colors */
-  --brand-050: var(--tone-magenta-050);
+  --tone-brand-050: var(--tone-magenta-050);
-  --brand-100: var(--tone-strawberry-100);
+  --tone-brand-100: var(--tone-strawberry-100);
-  // rgb(var(--brand-200)): #{rgb(var(--tone-magenta-200))};
+  /* --tone-brand-200: var(--tone-strawberry-200) */
-  // rgb(var(--brand-300)): #{rgb(var(--tone-magenta-300))};
+  /* --tone-brand-300: var(--tone-strawberry-300) */
-  // rgb(var(--brand-400)): #{rgb(var(--tone-magenta-400))};
+  /* --tone-brand-400: var(--tone-strawberry-400) */
-  // rgb(var(--brand-500)): #{rgb(var(--tone-magenta-500))};
+  /* --tone-brand-500: var(--tone-strawberry-500) */
-  /* temporary rose-like color until its replaced by a numbered one */
+  /* temporary strawberry-like color until its replaced by a numbered one */
-  --brand-600: 224 56 117;
+  --tone-brand-600: 224 56 117;
-  // rgb(var(--brand-700)): #{rgb(var(--tone-magenta-700))};
+  /* --tone-brand-700: var(--tone-strawberry-700) */
-  --brand-800: var(--tone-magenta-800);
+  --tone-brand-800: var(--tone-magenta-800);
-  // rgb(var(--brand-900)): #{rgb(var(--tone-magenta-900))};
+  /* --tone-brand-900: var(--tone-strawberry-900) */
 
   /* themeable ui colors */
-  --typo-action-500: var(--tone-blue-500);
+  --typo-action-500: rgb(var(--tone-blue-500));
-  --decor-error-500: var(--tone-red-500);
+  --decor-error-500: rgb(var(--tone-red-500));
-  --typo-contrast-999: var(--black);
+  --typo-contrast-999: rgb(var(--tone-gray-999));
 
   /* themeable brand colors */
-  --typo-brand-050: var(--brand-050);
+  --typo-brand-050: rgb(var(--tone-brand-050));
-  --typo-brand-600: var(--brand-600);
+  --typo-brand-600: rgb(var(--tone-brand-600));
-  --decor-brand-600: var(--brand-600);
+  --decor-brand-600: rgb(var(--tone-brand-600));
-  --swatch-brand-600: var(--brand-600);
+  --swatch-brand-600: rgb(var(--tone-brand-600));
-  --swatch-brand-800: var(--brand-800);
+  --swatch-brand-800: rgb(var(--tone-brand-800));
 }

ui/packages/consul-ui/app/templates/debug.hbs

@@ -6,6 +6,8 @@
 
     <DocfyOutput as |node|>
       <ul>
+
+{{!hardcode in docs first}}
           <li role="separator">Docs</li>
 {{#each node.children as |child|}}
   {{#each child.pages as |child|}}
@@ -17,7 +19,27 @@
             </DocfyLink>
           </li>
   {{/each}}
+
+{{!hardcode in styles next}}
+  {{#let (find-by 'label' 'styles' child.children) as |section|}}
+      <li role="separator">{{section.label}}</li>
+{{#each (flatten-property section 'pages') as |child|}}
+      <li
+        class={{concat
+          (slugify section.label) ' '
+          (if (is-href (to-route child.url)) 'is-active')
+        }}
+      >
+        <DocfyLink @to={{child.url}}>
+          {{classify child.title}}
+        </DocfyLink>
+      </li>
+{{/each}}
+  {{/let}}
+
+{{!print out the rest}}
   {{#each child.children as |section|}}
+{{#if (not-eq section.label 'styles')}}
           <li role="separator">{{section.label}}</li>
     {{#each (flatten-property section 'pages') as |child|}}
           <li
@@ -33,8 +55,10 @@
             </DocfyLink>
           </li>
     {{/each}}
+{{/if}}
   {{/each}}
 {{/each}}
+
       </ul>
     </DocfyOutput>
 

ui/packages/consul-ui/docs/index.mdx

@@ -32,8 +32,9 @@ The above will render the same code snippet in a box above the snippet.
 The location and name of markdown files within the project differs slightly depending on what you need to add documentation for:
 
 - **docs**: `docs/filename.mdx`
-- **components**: `components/your-component-name/README.mdx`
+- **styles**: `app/styles/*/*/README.mdx` (currently mostly in `app/styles/base`)
-- **helpers**: `helpers/your-helper-name.mdx`
+- **components**: `app/components/your-component-name/README.mdx`
-- **modifiers**: `modifiers/your-modifier-name.mdx`
+- **helpers**: `app/helpers/your-helper-name.mdx`
-- **services**: `services/your-service-name.mdx` (eventually these will partly use jsdoc code style generation)
+- **modifiers**: `app/modifiers/your-modifier-name.mdx`
+- **services**: `app/services/your-service-name.mdx` (eventually these will partly use jsdoc code style generation)
 

ui/packages/consul-ui/ember-cli-build.js

@@ -59,6 +59,8 @@ module.exports = function(defaults, $ = process.env) {
     excludeFiles = excludeFiles.concat([
       'instance-initializers/debug.js',
       'routing/**/*-debug.js',
+      'helpers/**/*-debug.js',
+      'modifiers/**/*-debug.js',
       'services/**/*-debug.js',
       'templates/debug.hbs',
       'components/debug/**/*.*'