From d9f06657665fbfacd5f928294cd082a3b3d6798d Mon Sep 17 00:00:00 2001 From: lindsaym-fa Date: Thu, 6 Jun 2024 19:31:43 -0400 Subject: [PATCH] more touch ups on theming docs --- docs/docs/theming/color.md | 522 ++++++++++++++++++----------------- docs/docs/theming/shadows.md | 2 +- src/themes/default.css | 14 +- 3 files changed, 277 insertions(+), 261 deletions(-) diff --git a/docs/docs/theming/color.md b/docs/docs/theming/color.md index 9bb3620b4..fbb1f5495 100644 --- a/docs/docs/theming/color.md +++ b/docs/docs/theming/color.md @@ -9,11 +9,16 @@ layout: page.njk font-weight: var(--wa-font-weight-semibold); margin-block-end: var(--wa-space-2xs); } + ul.color-group { + list-style: none; + margin: 0; + padding: 0; + } .color-group { - display: flex; align-items: start; - gap: 0.25em; + display: flex; flex-wrap: nowrap; + gap: 0.25em; } .color-group + * { margin-block-start: var(--wa-space-xl); @@ -24,9 +29,21 @@ layout: page.njk .swatch { border: none; } + .color-mix-example { + background-image: + linear-gradient(to right, + color-mix(in oklab, transparent, var(--mix-color)) 25%, + color-mix(in oklab, var(--wa-color-brand-fill-loud), var(--mix-color)) 25%, + color-mix(in oklab, var(--wa-color-brand-fill-loud), var(--mix-color)) 75%, + var(--wa-color-brand-fill-loud) 75%, + var(--wa-color-brand-fill-loud)) + ; + color: var(--wa-color-brand-on-loud); + text-align: center; + } -Web Awesome's color system is made up of CSS custom properties to help ensure consistent color use throughout your project. +Web Awesome's color system is made up of CSS custom properties to help with consistent color use throughout your project. Color is organized by three main categories: @@ -48,340 +65,340 @@ Lightness values on this scale have a strong correlation to [relative luminance] Web Awesome defines seven literal colors each with 11 lightness values using the format `--wa-color-{name}-{#}`.
Red
-
-
+
    +
  • 95 -
-
+ +
  • 90 -
    • -
    + +
  • 80 -
    • -
    + +
  • 70 -
    • -
    + +
  • 60 -
    • -
    + +
  • 50 -
    • -
    + +
  • 40 -
    • -
    + +
  • 30 -
    • -
    + +
  • 20 -
    • -
    + +
  • 10 -
    • -
    + +
  • 05 -
    • -
    + +
    Yellow
    -
    -
    +
      +
    • 95 -
    -
    + +
  • 90 -
    • -
    + +
  • 80 -
    • -
    + +
  • 70 -
    • -
    + +
  • 60 -
    • -
    + +
  • 50 -
    • -
    + +
  • 40 -
    • -
    + +
  • 30 -
    • -
    + +
  • 20 -
    • -
    + +
  • 10 -
    • -
    + +
  • 05 -
    • -
    + +
    Green
    -
    -
    +
      +
    • 95 -
    -
    + +
  • 90 -
    • -
    + +
  • 80 -
    • -
    + +
  • 70 -
    • -
    + +
  • 60 -
    • -
    + +
  • 50 -
    • -
    + +
  • 40 -
    • -
    + +
  • 30 -
    • -
    + +
  • 20 -
    • -
    + +
  • 10 -
    • -
    + +
  • 05 -
    • -
    + +
    Blue
    -
    -
    +
      +
    • 95 -
    -
    + +
  • 90 -
    • -
    + +
  • 80 -
    • -
    + +
  • 70 -
    • -
    + +
  • 60 -
    • -
    + +
  • 50 -
    • -
    + +
  • 40 -
    • -
    + +
  • 30 -
    • -
    + +
  • 20 -
    • -
    + +
  • 10 -
    • -
    + +
  • 05 -
    • -
    + +
    Indigo
    -
    -
    +
      +
    • 95 -
    -
    + +
  • 90 -
    • -
    + +
  • 80 -
    • -
    + +
  • 70 -
    • -
    + +
  • 60 -
    • -
    + +
  • 50 -
    • -
    + +
  • 40 -
    • -
    + +
  • 30 -
    • -
    + +
  • 20 -
    • -
    + +
  • 10 -
    • -
    + +
  • 05 -
    • -
    + +
    Violet
    -
    -
    +
      +
    • 95 -
    -
    + +
  • 90 -
    • -
    + +
  • 80 -
    • -
    + +
  • 70 -
    • -
    + +
  • 60 -
    • -
    + +
  • 50 -
    • -
    + +
  • 40 -
    • -
    + +
  • 30 -
    • -
    + +
  • 20 -
    • -
    + +
  • 10 -
    • -
    + +
  • 05 -
    • -
    + +
    Gray
    -
    -
    +
      +
    • 95 -
    -
    + +
  • 90 -
    • -
    + +
  • 80 -
    • -
    + +
  • 70 -
    • -
    + +
  • 60 -
    • -
    + +
  • 50 -
    • -
    + +
  • 40 -
    • -
    + +
  • 30 -
    • -
    + +
  • 20 -
    • -
    + +
  • 10 -
    • -
    + +
  • 05 -
    • -
    + + ## Foundational Colors @@ -389,7 +406,7 @@ Foundational colors lay the groundwork for the content and structure of your pro ### Key Colors -We provide aliases for a pair of literal color groups to aid changing the key colors of your project: +Web Awesome provides aliases for two literal color groups to aid changing the key colors of your project: - **Primary** is used to draw attention and signify actions - **Base** makes up your project's body and structure @@ -397,177 +414,174 @@ We provide aliases for a pair of literal color groups to aid changing the key co By default, `--wa-color-primary-{#}` references `--wa-color-blue-{#}` and `--wa-color-base-{#}` references `--wa-color-gray-{#}`.
    Primary
    -
    -
    +
      +
    • 95 -
    -
    + +
  • 90 -
    • -
    + +
  • 80 -
    • -
    + +
  • 70 -
    • -
    + +
  • 60 -
    • -
    + +
  • 50 -
    • -
    + +
  • 40 -
    • -
    + +
  • 30 -
    • -
    + +
  • 20 -
    • -
    + +
  • 10 -
    • -
    + +
  • 05 -
    • -
    + +
    Base
    -
    -
    +
      +
    • 95 -
    -
    + +
  • 90 -
    • -
    + +
  • 80 -
    • -
    + +
  • 70 -
    • -
    + +
  • 60 -
    • -
    + +
  • 50 -
    • -
    + +
  • 40 -
    • -
    + +
  • 30 -
    • -
    + +
  • 20 -
    • -
    + +
  • 10 -
    • -
    + +
  • 05 -
    • -
    + + ### Surfaces -Surfaces are background layers that other components and content rest on. Surface colors help convey hierarchy through a sense of elevation, where `--wa-color-surface-raised` is the closest to the user (e.g., dialogs and popup menus) and `--wa-color-surface-lowered` is the farthest away (e.g., wells). +Surfaces are background layers that other content rests on. Surface colors help convey hierarchy through a sense of elevation, where `--wa-color-surface-raised` is the closest to the user (e.g., dialogs and popup menus) and `--wa-color-surface-lowered` is the farthest away (e.g., wells). -| Custom Property | Preview | -| ----------------------------- | ------------------------------- | -| `--wa-color-surface-raised` |
    | -| `--wa-color-surface-default` |
    | -| `--wa-color-surface-lowered` |
    | -| `--wa-color-surface-border` |
    | +| Custom Property | Preview | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `--wa-color-surface-raised` |
    | +| `--wa-color-surface-default` |
    | +| `--wa-color-surface-lowered` |
    | +| `--wa-color-surface-border` |
    | ### Text Text colors are used for standard text elements. We recommend a minimum 4.5:1 contrast ratio between text colors and surface colors. -| Custom Property | Preview | -| ----------------------------- | ------------------------------- | -| `--wa-color-text-normal` | AaBb | -| `--wa-color-text-quiet` | AaBb | -| `--wa-color-text-link` | AaBb | +| Custom Property | Preview | +| ------------------------ | ------------------------------------------------------------ | +| `--wa-color-text-normal` | AaBb | +| `--wa-color-text-quiet` | AaBb | +| `--wa-color-text-link` | AaBb | ### Overlays Overlays provide a backdrop to isolate content, often allowing background context to show through. -| Custom Property | Preview | -| ----------------------------- | ------------------------------- | -| `--wa-color-overlay-modal` |
    | -| `--wa-color-overlay-inline` |
    | +| Custom Property | Preview | +| --------------------------- | ----------------------------------------------------------------------------------- | +| `--wa-color-overlay-modal` |
    | +| `--wa-color-overlay-inline` |
    | ### Shadow -Shadows indicate elevation and, often, interactivity. `--wa-color-shadow` is used to construct your theme's [shadow properties](/docs/theming/shadows). +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. -| Custom Property | Preview | -| ----------------------------- | ------------------------------- | -| `--wa-color-shadow` |
    | +| Custom Property | Preview | +| ------------------- | --------------------------------------------------------------------------- | +| `--wa-color-shadow` |
    | ### Interactions #### Focus -Web Awesome uses a single, consistent focus color for predictable keyboard navigation. This is used alongside your [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/theming/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 | -| ----------------------------- | ------------------------------- | -| `--wa-color-focus` |
    | +| Custom Property | Preview | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `--wa-color-focus` |
    | #### Hover and Active -We leverage `color-mix()` to achieve consistent hover and active states across components without the need for dozens of handpicked colors. These custom properties are used in `color-mix()` functions to contextually generate hover and active colors based on the color of the component. +Web Awesome leverages `color-mix()` to achieve consistent hover and active states across components without the need for untold numbers of handpicked colors. Through `color-mix()`, these custom properties contextually generate hover and active colors based on the color of the component. -| Custom Property | Preview | -| ----------------------------- | ------------------------------- | -| `--wa-color-mix-hover` |
    mixed
    | -| `--wa-color-mix-active` |
    mixed
    | +| Custom Property | Preview | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `--wa-color-mix-hover` |
    mixed
    | +| `--wa-color-mix-active` |
    mixed
    | ## Semantic Colors -Semantic colors help reinforce a specific message, intended usage, or expected results through familiar, meaningful hues. Each color is identified by its semantic group, role, and attention using the format `--wa-color-{group}-{role}-{attention}`. There are five groups of semantic colors: - -- **Brand** to reinforce your brand color +Semantic colors reinforce a specific message, intended usage, or expected results through familiar, meaningful hues. Each color is identified by its semantic group, role, and attention using the format `--wa-color-{group}-{role}-{attention}`. There are five groups of semantic colors: +- **Brand** to emphasize your brand color - **Success** for validity or confirmation - **Neutral** for ordinary or inactive content - **Warning** for caution or uncertainty - **Danger** for errors or risk Each group defines colors for specific roles so that colors can be easily assembled with predictable results and readable contrast. There are three roles: - - **Fill** for background colors or areas larger than a few pixels - **Border** for borders, dividers, and other stroke-width elements - **On** for content displayed on a fill (e.g., pair `--wa-color-danger-on-loud` with `--wa-color-danger-fill-loud`) Finally, each color is named according to how much attention it draws. Here, we use noise as an analogy: a loud noise draws more attention than a quiet one. There are three levels of attention: - - **Quiet** draws the least attention - **Normal** draws some attention - **Loud** draws the most attention diff --git a/docs/docs/theming/shadows.md b/docs/docs/theming/shadows.md index bbbc45148..a1adbff31 100644 --- a/docs/docs/theming/shadows.md +++ b/docs/docs/theming/shadows.md @@ -4,7 +4,7 @@ description: Elevate your components with Web Awesome's shadow properties. layout: page.njk --- -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/theming/color/#shadow), these custom properties create realistic shadows for Web Awesome components. 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/src/themes/default.css b/src/themes/default.css index ccb68d235..522aad48b 100644 --- a/src/themes/default.css +++ b/src/themes/default.css @@ -100,7 +100,7 @@ */ /* Primary is a key color used to draw attention and signify actions. - * Primary colors should be a 1-to-1 map with colors in a literal color group. */ + * Primary colors should be a 1-to-1 map with a literal color group. */ --wa-color-primary-95: var(--wa-color-blue-95); --wa-color-primary-90: var(--wa-color-blue-90); --wa-color-primary-80: var(--wa-color-blue-80); @@ -114,7 +114,7 @@ --wa-color-primary-05: var(--wa-color-blue-05); /* Base is a key color that makes up your project's body and structure. - * Base colors should be a 1-to-1 map with colors in a literal color group, usually gray. */ + * Base colors should be a 1-to-1 map with a literal color group, usually gray. */ --wa-color-base-95: var(--wa-color-gray-95); --wa-color-base-90: var(--wa-color-gray-90); --wa-color-base-80: var(--wa-color-gray-80); @@ -127,7 +127,7 @@ --wa-color-base-10: var(--wa-color-gray-10); --wa-color-base-05: var(--wa-color-gray-05); - /* Surfaces are background layers that other components and content rest on. + /* Surfaces are background layers that other content rests on. * Surface colors help convey hierarchy through elevation, where raised is closest to the user and lowered is farthest away. */ --wa-color-surface-raised: white; --wa-color-surface-default: white; @@ -140,11 +140,13 @@ --wa-color-text-quiet: var(--wa-color-base-40); --wa-color-text-link: var(--wa-color-primary-40); - /* Overlays provide a backdrop for isolated content, often allowing background colors or content to show through. */ + /* Overlays provide a backdrop for isolated content, often allowing background context to show through. */ --wa-color-overlay-modal: color-mix(in oklab, var(--wa-color-base-10) 40%, transparent); --wa-color-overlay-inline: color-mix(in oklab, var(--wa-color-base-80) 20%, transparent); - /* Shadows indicate elevation. Shadow color is used in your theme's shadow properties. */ + /* Shadows indicate elevation. Shadow color is used in your theme's shadow properties. + * By default, the opacity of your shadow color is tied to the blur of shadows in your theme. + * Because solid shadows appear stronger in color than diffused shadows, this helps keep consistent color intensity. */ --wa-color-shadow: color-mix( in oklab, var(--wa-color-base-05) calc(var(--wa-shadow-blur-multiplier) * 24% + 8%), @@ -161,7 +163,7 @@ /** * Semantic Colors - * Five semantic groups - brand, success, neutral, warning, and danger - help reinforce a component's message, intended usage, or expected results. + * Five semantic groups - brand, success, neutral, warning, and danger - reinforce a component's message, intended usage, or expected results. * Within these groups, each color specifies a role - * * Fill for background colors or areas larger than a few pixels * * Border for borders, dividers, and other stroke-like elements