Theming -> Design Tokens

docs/_includes/sidebar.njk

@@ -25,7 +25,7 @@
   'utilities': 'Style Utilities',
   'layout': 'Layout',
   'patterns': 'Patterns',
-  'theming': 'Theming'
+  'tokens': 'Design Tokens'
 } %}
   {% include 'sidebar-group.njk' %}
 {% endfor %}

docs/docs/customizing.md

@@ -12,7 +12,7 @@ Web Awesome uses numerous CSS custom properties that make up a high-level themin
 
 Because these custom properties live at the page level, they're prefixed with `--wa-` to avoid collisions with other libraries or your own custom properties.
 
-To customize a theme, simply override any of these custom properties in your own stylesheet by scoping your styles to `:root`, `:host`, and, if needed, the class for the specific theme you want to override. Here's an example that changes the default brand color (blue) to violet in the light theme using existing [literal colors](/docs/theming/color/#literal-colors).
+To customize a theme, simply override any of these custom properties in your own stylesheet by scoping your styles to `:root`, `:host`, and, if needed, the class for the specific theme you want to override. Here's an example that changes the default brand color (blue) to violet in the light theme using existing [literal colors](/docs/tokens/color/#literal-colors).
 
 ```css
 :where(:root),

docs/docs/themes/index.njk

@@ -1,6 +1,6 @@
 ---
 title: Themes
-description: Themes are collections of pre-defined CSS custom properties that thread through every Web Awesome component and pattern.
+description: Themes are collections of predefined CSS custom properties that thread through every Web Awesome component and pattern.
 layout: overview
 override:tags: []
 forTag: theme
@@ -14,7 +14,7 @@ categories:
 
 ## What's a Theme?
 
-Themes are a collection of standardized [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) that cover a range of styles from colors to transitions. We use these custom properties throughout Web Awesome components for a cohesive look and feel. Our [Theming pages](/docs/theming/) document these styles so that you can use them freely throughout your project and customize them as needed.
+Themes are a collection of standardized [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) that cover a range of styles from colors to transitions. We use these custom properties throughout Web Awesome components for a cohesive look and feel. Our [Theming pages](/docs/tokens/) document these styles so that you can use them freely throughout your project and customize them as needed.
 
 Themes are scoped to unique classes, such as `wa-theme-default` or `wa-theme-classic`.
 Scoping to unique classes allows you to import multiple themes and use them interchangeably without collisions.

docs/docs/theming/index.njk

@@ -1,6 +0,0 @@
----
-title: Theming
-description: A theme is a collection of pre-defined CSS custom properties that control global styles from color to shadows. These custom properties thread through all Web Awesome components for a consistent look and feel.
-layout: overview
-override:tags: []
----

docs/docs/theming/theming.json

@@ -1,7 +0,0 @@
-{
-  "layout": "page-outline.njk",
-  "tags": ["theming"],
-  "eleventyComputed": {
-    "icon": "theming/{{ page.fileSlug }}"
-  }
-}

docs/docs/tokens/borders.md

@@ -21,7 +21,7 @@ Border widths use `rem` units in order to scale proportionately with the root fo
 | `--wa-border-width-m` | `0.125rem` <small>(2px)</small>  | <div class="swatch" style="border-width: var(--wa-border-width-m)"></div> |
 | `--wa-border-width-l` | `0.1875rem` <small>(3px)</small> | <div class="swatch" style="border-width: var(--wa-border-width-l)"></div> |
 
-To scale all borders at once, you can use the  `--wa-border-width-scale` property which specifies a multiplier on `border-width`. 
+To scale all borders at once, you can use the  `--wa-border-width-scale` property which specifies a multiplier on `border-width`.
 Values < 1 make all borders uniformly thinner, while values > 1 make them thicker.
 
 ## Radius
@@ -44,5 +44,5 @@ Size-based border radius properties allow you to customize the overall roundness
 | `--wa-border-radius-m`  | `0.375rem` <small>(6px)</small>  | <div class="swatch" style="border-radius: var(--wa-border-radius-m)"></div> |
 | `--wa-border-radius-l`  | `0.75rem` <small>(12px)</small>  | <div class="swatch" style="border-radius: var(--wa-border-radius-l)"></div> |
 
-To scale all border radii at once, you can use the  `--wa-border-radius-scale` property which specifies a multiplier on `border-radius`. 
-Values < 1 make corners sharper, while values > 1 make them rounder.
+To scale all border radii at once, you can use the  `--wa-border-radius-scale` property which specifies a multiplier on `border-radius`.
+Values < 1 make corners sharper, while values > 1 make them rounder.

docs/docs/tokens/color.md

@@ -486,7 +486,8 @@ Overlays provide a backdrop to isolate content, often allowing background contex
 
 ### Shadow
 
-Web Awesome uses a single color for all shadows. This is used alongside other [shadow properties](/docs/theming/shadows) to construct your theme's shadows.
+Web Awesome uses a single color for all shadows.
+This is used alongside other [shadow properties](/docs/tokens/shadows) to construct your theme's shadows.
 
 | Custom Property     | Preview                                                                     |
 | ------------------- | --------------------------------------------------------------------------- |
@@ -496,7 +497,7 @@ Web Awesome uses a single color for all shadows. This is used alongside other [s
 
 #### Focus
 
-Web Awesome uses a single focus color for predictable keyboard navigation. This is used alongside other [focus properties](/docs/theming/focus) to construct `--wa-focus-ring`. We recommend a minimum 3:1 contrast ratio against surface colors and background colors wherever possible.
+Web Awesome uses a single focus color for predictable keyboard navigation. This is used alongside other [focus properties](/docs/tokens/focus) to construct `--wa-focus-ring`. We recommend a minimum 3:1 contrast ratio against surface colors and background colors wherever possible.
 
 | Custom Property    | Preview                                                                                                                 |
 | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |

docs/docs/tokens/focus.md

@@ -3,7 +3,7 @@ title: Focus
 description: Configure recognizable focus states with Web Awesome's focus properties.
 ---
 
-A consistent focus ring helps with predictable keyboard navigation. Together with [`--wa-color-focus`](/docs/theming/color/#interactions), these custom properties create a uniform focus state for Web Awesome components.
+A consistent focus ring helps with predictable keyboard navigation. Together with [`--wa-color-focus`](/docs/tokens/color/#interactions), these custom properties create a uniform focus state for Web Awesome components.
 
 
 | Custom Property          |  Default Value                                                                |

docs/docs/tokens/index.njk

@@ -0,0 +1,6 @@
+---
+title: Design Tokens
+description: A theme is a collection of predefined CSS custom properties that control global styles from color to shadows. These custom properties thread through all Web Awesome components for a consistent look and feel.
+layout: overview
+override:tags: []
+---

docs/docs/tokens/shadows.md

@@ -3,7 +3,7 @@ title: Shadows
 description: Elevate your components with Web Awesome's shadow properties.
 ---
 
-Shadows indicate elevation and, often, interactivity. Web Awesome offers highly modular shadow properties to easily create custom shadow effects or transform elements based on specific shadow qualities. Together with [`--wa-color-shadow`](/docs/theming/color/#shadow), these custom properties create realistic shadows for Web Awesome components.
+Shadows indicate elevation and, often, interactivity. Web Awesome offers highly modular shadow properties to easily create custom shadow effects or transform elements based on specific shadow qualities. Together with [`--wa-color-shadow`](/docs/tokens/color/#shadow), these custom properties create realistic shadows for Web Awesome components.
 
 Shadows are constructed using corresponding offset-x, offset-y, blur, and spread properties, detailed in the sections below. In Web Awesome, shadows use a size-based scale where larger shadows have greater offset and blur values to indicate greater distance from the surface below.
 

docs/docs/tokens/tokens.json

@@ -0,0 +1,7 @@
+{
+  "layout": "page-outline.njk",
+  "tags": ["tokens"],
+  "eleventyComputed": {
+    "icon": "tokens/{{ page.fileSlug }}"
+  }
+}

docs/docs/tokens/typography.md

@@ -69,7 +69,7 @@ Line heights control the distance between lines of text and are unitless to scal
 
 ## Links
 
-Together with [`--wa-color-link`](/docs/theming/color/#text), these custom properties add text decoration to `<a>` elements to signal their role as hyperlinks.
+Together with [`--wa-color-link`](/docs/tokens/color/#text), these custom properties add text decoration to `<a>` elements to signal their role as hyperlinks.
 
 | Custom Property                | Default Value                                                                      |
 | ------------------------------ | ---------------------------------------------------------------------------------- |

docs/docs/utilities/color.md

@@ -1,7 +1,7 @@
 ---
 title: Color Variants
 description: Color utilities allow you to apply the brand, neutral, success, warning, and danger colors from your theme to any element.
-icon: theming/color
+icon: tokens/color
 snippets:
   - .wa-brand
   - .wa-neutral
@@ -27,7 +27,7 @@ You can create the same effect on any element by using the color variant utility
 - `.wa-danger`
 
 Using these classes is a two-way handshake:
-they do not directly apply styles, but define generic color tokens modeled after our [Semantic Colors](/docs/theming/color/#semantic-colors) but *without* the group identifier (`neutral`, `brand`, `success`, `warning`, `danger`), defaulting to `neutral`.
+they do not directly apply styles, but define generic color tokens modeled after our [Semantic Colors](/docs/tokens/color/#semantic-colors) but *without* the group identifier (`neutral`, `brand`, `success`, `warning`, `danger`), defaulting to `neutral`.
 This means that styles can be written to respond to variants by using e.g. `--wa-color-fill-loud` instead of e.g. `--wa-color-brand-fill-loud`,
 and all of our [native styles](/docs/native/) do so (where it made sense).
 

docs/docs/utilities/gap.md

@@ -16,7 +16,7 @@ tags: ["utilities", "layout"]
 Web Awesome includes classes to set the `gap` property of flex and grid containers. They can be used alongside other Web Awesome layout utilities, like [cluster](/docs/layout/cluster) and [stack](/docs/layout/stack), to change the space between items.
 Or even by themselves — all gap properties also set `display: flex` with a specificity of 0 so that it can be trivially overridden.
 
-Besides `wa-gap-0`, which sets `gap` to zero, each class corresponds to one of the [`--wa-space-*`](/docs/theming/space) properties in your theme.
+Besides `wa-gap-0`, which sets `gap` to zero, each class corresponds to one of the [`--wa-space-*`](/docs/tokens/space) properties in your theme.
 
 | Class Name   | `gap` Value      | Preview                                                                                                     |
 | ------------ | ---------------- | ----------------------------------------------------------------------------------------------------------- |

docs/docs/utilities/rounding.md

@@ -14,7 +14,7 @@ status: wip
 
 Web Awesome includes classes to set an element's `border-radius` property. They can be used alongside Web Awesome layout utilities, like [frame](/docs/layout/frame), to round all corners of an element.
 
-Each class corresponds to one of the [`--wa-border-radius-*`](/docs/theming/borders/#radius) properties in your theme.
+Each class corresponds to one of the [`--wa-border-radius-*`](/docs/tokens/borders/#radius) properties in your theme.
 
 | Class Name                | `border-radius` Value       | Preview                                                                                 |
 | ------------------------- | --------------------------- | --------------------------------------------------------------------------------------- |

docs/docs/utilities/size.md

@@ -1,7 +1,7 @@
 ---
 title: Size
 description: Size utilities give elements one of three preset sizes (small, medium, or large).
-icon: theming/space
+icon: tokens/space
 status: experimental
 snippets:
   - .wa-size-s
@@ -22,7 +22,7 @@ You can create the same effect on any element by using the size utility classes:
 - `.wa-size-l`
 
 Using these classes does two things:
-- It sets `font-size` to one of the [size tokens](/docs/theming/typography/#font-size).
+- It sets `font-size` to one of the [size tokens](/docs/tokens/typography/#font-size).
 You can use CSS `em` units to reference that size in other properties.
 - It calculates `--wa-form-control-height` based on the applied size, supporting consistent heights for elements like inputs and buttons.
 - It aliases a bunch of other properties that CSS can use:

docs/docs/utilities/text.md

@@ -13,7 +13,7 @@ Use body classes to style the main content of your pages. Each `wa-body-*` class
 - `font-weight: var(--wa-font-weight-body);`
 - `line-height: var(--wa-line-height-normal);`
 
-Additionally, each class specifies a `font-size` that corresponds to a [`--wa-font-size-*`](/docs/theming/typography/#font-size) property from your theme.
+Additionally, each class specifies a `font-size` that corresponds to a [`--wa-font-size-*`](/docs/tokens/typography/#font-size) property from your theme.
 
 | Class Name         | `font-size` Value    |  Preview                                                                  |
 | ------------------ | -------------------- | ------------------------------------------------------------------------- |
@@ -31,7 +31,7 @@ Use heading classes to style section titles and headings in your content. Each `
 - `line-height: var(--wa-line-height-condensed);`
 - `text-wrap: balance;`
 
-Additionally, each class specifies a `font-size` using a [`--wa-font-size-*`](/docs/theming/typography/#font-size) property from your theme. Heading classes are one font size larger than the corresponding `wa-body-*` class.
+Additionally, each class specifies a `font-size` using a [`--wa-font-size-*`](/docs/tokens/typography/#font-size) property from your theme. Heading classes are one font size larger than the corresponding `wa-body-*` class.
 
 | Class Name       | `font-size` Value    | Preview                                               |
 | ---------------- | -------------------- | ----------------------------------------------------- |
@@ -51,7 +51,7 @@ Use caption classes to style descriptions or auxiliary text in your content. Eac
 - `font-weight: var(--wa-font-weight-body);`
 - `line-height: var(--wa-line-height-condensed);`
 
-Additionally, each class specifies a `font-size` using a [`--wa-font-size-*`](/docs/theming/typography/#font-size) property from your theme. Caption classes are one font size smaller than the corresponding `wa-body-*` class.
+Additionally, each class specifies a `font-size` using a [`--wa-font-size-*`](/docs/tokens/typography/#font-size) property from your theme. Caption classes are one font size smaller than the corresponding `wa-body-*` class.
 
 | Class Name       | `font-size` Value    | Preview                                                                        |
 | ---------------- | -------------------- | ------------------------------------------------------------------------------ |