diff --git a/docs/_includes/sidebar.njk b/docs/_includes/sidebar.njk index 1e99e57e8..b834bc717 100644 --- a/docs/_includes/sidebar.njk +++ b/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 %} diff --git a/docs/_includes/svgs/theming/borders.njk b/docs/_includes/svgs/tokens/borders.njk similarity index 100% rename from docs/_includes/svgs/theming/borders.njk rename to docs/_includes/svgs/tokens/borders.njk diff --git a/docs/_includes/svgs/theming/color.njk b/docs/_includes/svgs/tokens/color.njk similarity index 100% rename from docs/_includes/svgs/theming/color.njk rename to docs/_includes/svgs/tokens/color.njk diff --git a/docs/_includes/svgs/theming/component-groups.njk b/docs/_includes/svgs/tokens/component-groups.njk similarity index 100% rename from docs/_includes/svgs/theming/component-groups.njk rename to docs/_includes/svgs/tokens/component-groups.njk diff --git a/docs/_includes/svgs/theming/focus.njk b/docs/_includes/svgs/tokens/focus.njk similarity index 100% rename from docs/_includes/svgs/theming/focus.njk rename to docs/_includes/svgs/tokens/focus.njk diff --git a/docs/_includes/svgs/theming/shadows.njk b/docs/_includes/svgs/tokens/shadows.njk similarity index 100% rename from docs/_includes/svgs/theming/shadows.njk rename to docs/_includes/svgs/tokens/shadows.njk diff --git a/docs/_includes/svgs/theming/space.njk b/docs/_includes/svgs/tokens/space.njk similarity index 100% rename from docs/_includes/svgs/theming/space.njk rename to docs/_includes/svgs/tokens/space.njk diff --git a/docs/_includes/svgs/theming/transitions.njk b/docs/_includes/svgs/tokens/transitions.njk similarity index 100% rename from docs/_includes/svgs/theming/transitions.njk rename to docs/_includes/svgs/tokens/transitions.njk diff --git a/docs/_includes/svgs/theming/typography.njk b/docs/_includes/svgs/tokens/typography.njk similarity index 100% rename from docs/_includes/svgs/theming/typography.njk rename to docs/_includes/svgs/tokens/typography.njk diff --git a/docs/docs/customizing.md b/docs/docs/customizing.md index 95782eac9..90fcbe211 100644 --- a/docs/docs/customizing.md +++ b/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), diff --git a/docs/docs/themes/index.njk b/docs/docs/themes/index.njk index 0c668f697..463251eba 100644 --- a/docs/docs/themes/index.njk +++ b/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. diff --git a/docs/docs/theming/index.njk b/docs/docs/theming/index.njk deleted file mode 100644 index 80c5acec7..000000000 --- a/docs/docs/theming/index.njk +++ /dev/null @@ -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: [] ---- diff --git a/docs/docs/theming/theming.json b/docs/docs/theming/theming.json deleted file mode 100644 index 3526f7655..000000000 --- a/docs/docs/theming/theming.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "layout": "page-outline.njk", - "tags": ["theming"], - "eleventyComputed": { - "icon": "theming/{{ page.fileSlug }}" - } -} diff --git a/docs/docs/theming/borders.md b/docs/docs/tokens/borders.md similarity index 99% rename from docs/docs/theming/borders.md rename to docs/docs/tokens/borders.md index 537534199..40399bd4b 100644 --- a/docs/docs/theming/borders.md +++ b/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` (2px) |
| | `--wa-border-width-l` | `0.1875rem` (3px) |
| -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` (6px) |
| | `--wa-border-radius-l` | `0.75rem` (12px) |
| -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. \ No newline at end of file +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. diff --git a/docs/docs/theming/color.md b/docs/docs/tokens/color.md similarity index 98% rename from docs/docs/theming/color.md rename to docs/docs/tokens/color.md index 1cf873d47..9526cce99 100644 --- a/docs/docs/theming/color.md +++ b/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 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/docs/theming/component-groups.md b/docs/docs/tokens/component-groups.md similarity index 100% rename from docs/docs/theming/component-groups.md rename to docs/docs/tokens/component-groups.md diff --git a/docs/docs/theming/focus.md b/docs/docs/tokens/focus.md similarity index 89% rename from docs/docs/theming/focus.md rename to docs/docs/tokens/focus.md index 900f7bb23..7bb472676 100644 --- a/docs/docs/theming/focus.md +++ b/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 | diff --git a/docs/docs/tokens/index.njk b/docs/docs/tokens/index.njk new file mode 100644 index 000000000..74337da3f --- /dev/null +++ b/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: [] +--- diff --git a/docs/docs/theming/shadows.md b/docs/docs/tokens/shadows.md similarity index 95% rename from docs/docs/theming/shadows.md rename to docs/docs/tokens/shadows.md index 9b1523e38..1e2952c26 100644 --- a/docs/docs/theming/shadows.md +++ b/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. diff --git a/docs/docs/theming/space.md b/docs/docs/tokens/space.md similarity index 100% rename from docs/docs/theming/space.md rename to docs/docs/tokens/space.md diff --git a/docs/docs/tokens/tokens.json b/docs/docs/tokens/tokens.json new file mode 100644 index 000000000..07e8f60c3 --- /dev/null +++ b/docs/docs/tokens/tokens.json @@ -0,0 +1,7 @@ +{ + "layout": "page-outline.njk", + "tags": ["tokens"], + "eleventyComputed": { + "icon": "tokens/{{ page.fileSlug }}" + } +} diff --git a/docs/docs/theming/transitions.md b/docs/docs/tokens/transitions.md similarity index 100% rename from docs/docs/theming/transitions.md rename to docs/docs/tokens/transitions.md diff --git a/docs/docs/theming/typography.md b/docs/docs/tokens/typography.md similarity index 97% rename from docs/docs/theming/typography.md rename to docs/docs/tokens/typography.md index 54ed6fdc9..069625d5a 100644 --- a/docs/docs/theming/typography.md +++ b/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 `` elements to signal their role as hyperlinks. +Together with [`--wa-color-link`](/docs/tokens/color/#text), these custom properties add text decoration to `` elements to signal their role as hyperlinks. | Custom Property | Default Value | | ------------------------------ | ---------------------------------------------------------------------------------- | diff --git a/docs/docs/utilities/color.md b/docs/docs/utilities/color.md index 564fb6125..01bf25901 100644 --- a/docs/docs/utilities/color.md +++ b/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). diff --git a/docs/docs/utilities/gap.md b/docs/docs/utilities/gap.md index 8191d30c4..5f2e0e5b2 100644 --- a/docs/docs/utilities/gap.md +++ b/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 | | ------------ | ---------------- | ----------------------------------------------------------------------------------------------------------- | diff --git a/docs/docs/utilities/rounding.md b/docs/docs/utilities/rounding.md index 7b310ebe8..3cc24f218 100644 --- a/docs/docs/utilities/rounding.md +++ b/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 | | ------------------------- | --------------------------- | --------------------------------------------------------------------------------------- | diff --git a/docs/docs/utilities/size.md b/docs/docs/utilities/size.md index fb5164206..4bb2ff812 100644 --- a/docs/docs/utilities/size.md +++ b/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: diff --git a/docs/docs/utilities/text.md b/docs/docs/utilities/text.md index 84bc65ef4..55cddf9c8 100644 --- a/docs/docs/utilities/text.md +++ b/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 | | ---------------- | -------------------- | ------------------------------------------------------------------------------ |