Merge branch 'themer-rework' of https://github.com/shoelace-style/webawesome into themer-rework

packages/webawesome/docs/docs/color-palettes.njk

@@ -1,12 +1,16 @@
 ---
 title: Color Palettes
-description: Look at all the pretty colors
+description: 'Color palettes give you a full spectrum of colors to add life to your project.'
 layout: docs
 isPro: true
 ---
 
-{% set colors = ['red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'indigo', 'purple', 'pink', 'gray'] %}
-{% set levels = ['05', '10', '20', '30', '40', '50', '60', '70', '80', '90', '95'] %}
+<p>Color palettes give you a full spectrum of colors to add life to your project.</p>
+
+<p>Each palette defines 10 hues with a scale of 11 tints. While the tints have consistent lightness values across palettes, each palette has unique hue shifts and chroma to give it unique character so you can find just the right vibe to your project.</p>
+
+{% set hues = ['red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'indigo', 'purple', 'pink', 'gray'] %}
+{% set tints = ['95', '90', '80', '70', '60', '50', '40', '30', '20', '10', '05'] %}
 
 <link id="palette-stylesheet" rel="stylesheet" href="/dist/styles/color/default.css">
 
@@ -17,18 +21,18 @@ isPro: true
     {% endfor %}
   </wa-radio-group>
 
-  {% for color in colors %}
+  {% for hue in hues %}
   <div class="palette">
-    <div class="palette-label">{{ color }}</div>
+    <div class="palette-label">{{ hue }}</div>
     <div class="palette-swatches">
-      {% for level in levels %}
+      {% for tint in tints %}
       <wa-copy-button
         class="palette-swatch"
-        copy-label="{{ color }} {{ level }}"
-        value="var(--wa-color-{{ color }}-{{ level }})"
-        style="--color: var(--wa-color-{{ color }}-{{ level }}); --level: '{{ level }}'"
+        copy-label="{{ hue }} {{ tint }}"
+        value="var(--wa-color-{{ hue }}-{{ tint }})"
+        style="--color: var(--wa-color-{{ hue }}-{{ tint }}); --tint: '{{ tint }}'"
       >
-        <span class="sr-only">--wa-color-{{ color }}-{{ level }}</span>
+        <span class="sr-only">--wa-color-{{ hue }}-{{ tint }}</span>
       </wa-copy-button>
       {% endfor %}
     </div>
@@ -164,16 +168,15 @@ isPro: true
     display: grid;
     grid-template-columns: repeat(11, 1fr);
     gap: var(--wa-space-3xs);
-    width: 100%;
   }
 
   .palette-swatch {
     padding: 0;
-    aspect-ratio: 1.5 / 1; /* Wider than tall on desktop */
+    aspect-ratio: 1.75 / 1; /* Wider than tall on desktop */
     position: relative;
 
     &::before {
-      content: var(--level);
+      content: var(--tint);
       position: absolute;
       top: calc(-1 * var(--wa-space-l));
       left: 50%;

packages/webawesome/docs/docs/themes/awesome.md

@@ -1,6 +1,6 @@
 ---
 title: Awesome
-description: Bustling with plenty of luster and shine.
+description: Punchy and vibrant, the rockstar of themes.
 isPro: false
 ---
 

packages/webawesome/docs/docs/tokens/color.md

@@ -1,6 +1,7 @@
 ---
 title: Color
 description: Ensure consistent use of color and readable contrast with Web Awesome's color properties.
+hasOutline: true
 ---
 
 <style>
@@ -19,7 +20,12 @@ description: Ensure consistent use of color and readable contrast with Web Aweso
     align-items: start;
     display: flex;
     flex-wrap: nowrap;
-    gap: 0.25em;
+    gap: var(--wa-space-3xs);
+
+    & small {
+      font-size: var(--wa-font-size-xs);
+      color: var(--wa-color-text-quiet);
+    }
   }
   .color-group + * {
     margin-block-start: var(--wa-space-xl);
@@ -49,27 +55,27 @@ Web Awesome's color system is made up of CSS custom properties to help with cons
 
 Color is organized by three main categories:
 
-- [Literal colors](/#literal-colors) that give familiar names to your starting [color palette](/docs/palettes/)
+- [Color scales](/#color-scales) that gives you a full spectrum of hues to work with
 - [Foundational colors](/#foundational-colors) that lay the groundwork for your theme
 - [Semantic colors](/#semantic-colors) that draw attention and convey meaning
 
 
-## Literal Colors
+## Color Scales
 
-Literal colors are defined by your theme's [color palette](/docs/palettes/) and are the lowest level color tokens in your theme. Each token is identified by a name, like red or gray, and a number based on the color's lightness. On this scale, 100 is equal to pure white and 0 is equal to pure black.
+Color scales are determined by your [color palette](/docs/color-palettes) and are made up of the lowest level color tokens in your theme. Each token is identified by a name, like red or gray, and numerical tint based on the color's lightness. On this scale, 100 is equal to pure white and 0 is equal to pure black.
 
-You can use these numbers to ensure accessible color contrast per [WCAG 2.1 success criteria](https://www.w3.org/TR/WCAG21/#contrast-minimum):
+You can use these tints to ensure accessible color contrast per [WCAG 2.1 success criteria](https://www.w3.org/TR/WCAG21/#contrast-minimum):
 
 - A difference of 40 ensures a minimum 3:1 contrast ratio, suitable for large text and icons (AA)
 - A difference of 50 ensures a minimum 4.5:1 contrast ratio, suitable for normal text (AA) and large text (AAA)
 - A difference of 60 ensures a minimum 7:1 contrast ratio, suitable for all text (AAA)
 
-Each Web Awesome palette defines seven literal colors each with 11 lightness values using the format `--wa-color-{hue}-{tint}`.
+You have several hand-crafted [color palettes](/docs/color-palettes) to choose from. Each palette defines 10 hues each with a scale of 11 tints using the format `--wa-color-{hue}-{tint}`.
 
-{% for hue in hues -%}
+{% for hue in ['red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'indigo', 'purple', 'pink', 'gray'] -%}
 <div class="color-name">{{ hue | capitalize }}</div>
 <ul class="color-group">
-  {% for tint in ["95", "90", "80", "70", "60", "50", "40", "30", "20", "10", "05"] -%}
+  {% for tint in ['95', '90', '80', '70', '60', '50', '40', '30', '20', '10', '05'] -%}
     <li class="color-preview">
       <div class="color swatch" style="background-color: var(--wa-color-{{ hue }}-{{ tint }})">
         <wa-copy-button value="--wa-color-{{ hue }}-{{ tint }}" copy-label="--wa-color-{{ hue }}-{{ tint }}"></wa-copy-button>
@@ -80,6 +86,24 @@ Each Web Awesome palette defines seven literal colors each with 11 lightness val
 </ul>
 {%- endfor %}
 
+### Semantic Scales
+
+Any hue can be mapped to `brand`, `neutral`, `success`, `warning`, and `danger` scales. Like the tokens in a color scale, each token is identified by its semantic group and a numerical tint using the format `--wa-color-{group}-{tint}`.
+
+{% for group in ['brand', 'neutral', 'success', 'warning', 'danger'] -%}
+<div class="color-name">{{ group | capitalize }}</div>
+<ul class="color-group">
+  {% for tint in ['95', '90', '80', '70', '60', '50', '40', '30', '20', '10', '05'] -%}
+    <li class="color-preview">
+      <div class="color swatch" style="background-color: var(--wa-color-{{ group }}-{{ tint }})">
+        <wa-copy-button value="--wa-color-{{ group }}-{{ tint }}" copy-label="--wa-color-{{ group }}-{{ tint }}"></wa-copy-button>
+      </div>
+      <small>{{ tint }}</small>
+    </li>
+  {%- endfor %}
+</ul>
+{%- endfor %}
+
 ## Foundational Colors
 
 Foundational colors lay the groundwork for the content and structure of your project. These colors are named according to their role in your theme.