WIP - revising + extending background pattern styling

packages/webawesome/docs/503.md

@@ -33,9 +33,9 @@ unlisted: true
     --secondary-opacity: 1.0;
   }
 
-  wa-page.background-grid {
+  wa-page.background-overlay-grid {
-    --grid-line-color: color-mix(in oklab, var(--wa-color-text-normal), transparent 96%);
+    --grid-opacity: 0.04;
-    --subgrid-line-color: color-mix(in oklab, var(--wa-color-text-normal), transparent 98%);
+    --subgrid-opacity: 0.02;
   }
 
   wa-page > [slot='main-footer'] {
@@ -209,7 +209,7 @@ unlisted: true
   .vehicle wa-icon[name="bulldozer"] { animation: rumble-bulldozer 0.1s ease-in-out infinite; }
 </style>
 
-<wa-page disable-sticky="header" class="background-grid">
+<wa-page disable-sticky="header" class="background-overlay-grid">
   <header slot="header">
     <div class="header-content wa-split" style="flex-wrap: nowrap;">
       <wa-icon variant="brands" name="web-awesome" class="icon-brand-logo"></wa-icon>

packages/webawesome/docs/_includes/_dialog-wa-launch.njk

@@ -2,7 +2,7 @@
   {%- if req.stripe.discount.active and not currentUser.hasPro -%}
     <wa-dialog id="dialog-site" light-dismiss without-header>
 
-      <div class="background-wa-pattern" style="justify-content: center; margin-inline: calc(var(--spacing) * -1); margin-block-start: calc(var(--spacing) * -1); margin-block-end: var(--spacing); background: linear-gradient(to bottom, var(--wa-color-brand), var(--wa-color-brand-50)); color: var(--wa-color-brand-on-loud); padding: var(--wa-space-3xl) var(--spacing); --background-pattern-opacity: 0.2; --background-pattern-image: url('/assets/images/bg-wa-pattern.svg');">
+      <div class="background-overlay-wa-pattern" style="justify-content: center; margin-inline: calc(var(--spacing) * -1); margin-block-start: calc(var(--spacing) * -1); margin-block-end: var(--spacing); background: linear-gradient(to bottom, var(--wa-color-brand), var(--wa-color-brand-50)); color: var(--wa-color-brand-on-loud); padding: var(--wa-space-3xl) var(--spacing); --background-opacity: 0.2;">
 
         <div class="wa-stack wa-align-items-center" style="text-align: center;">
           <wa-icon name="party-horn" family="duotone" variant="solid" style="font-size: var(--wa-font-size-3xl); --secondary-color: var(--wa-color-brand-40); --secondary-opacity: 1.0;"></wa-icon>

packages/webawesome/docs/assets/styles/utils.css

@@ -178,76 +178,107 @@
     }
   }
 
-  /* grid background */
+  /* background overlay base */
-  .background-grid {
+  .background-overlay,
-    --grid-spacing: var(--wa-space-2xl);
+  .background-overlay-grid,
-    --grid-line-color: color-mix(in oklab, var(--wa-color-text-normal), transparent 90%);
+  .background-overlay-dot-grid,
-    --grid-line-width: var(--wa-border-width-s);
+  .background-overlay-wa-pattern {
-    --subgrid-spacing: calc(var(--grid-spacing) / 2);
+    --background-blend-mode: normal;
-    --subgrid-line-color: color-mix(in oklab, var(--wa-color-text-normal), transparent 95%);
+    --background-blend-mode-dark: var(--background-blend-mode);
-    --subgrid-line-width: var(--wa-border-width-s);
+    --background-color: transparent;
-
+    --background-overlay-content-z-index: 1;
-    background-image:
+    --background-overlay-z-index: 0;
-      /* main grid - vertical lines */
-      linear-gradient(to right, var(--grid-line-color) var(--grid-line-width), transparent var(--grid-line-width)),
-      /* main grid - horizontal lines */
-        linear-gradient(to bottom, var(--grid-line-color) var(--grid-line-width), transparent var(--grid-line-width)),
-      /* sub-grid - vertical lines (offset by half the main grid spacing) */
-        linear-gradient(
-          to right,
-          var(--subgrid-line-color) var(--subgrid-line-width),
-          transparent var(--subgrid-line-width)
-        ),
-      /* sub-grid - horizontal lines (offset by half the main grid spacing) */
-        linear-gradient(
-          to bottom,
-          var(--subgrid-line-color) var(--subgrid-line-width),
-          transparent var(--subgrid-line-width)
-        );
-
-    background-size:
-      var(--grid-spacing) var(--grid-spacing),
-      var(--grid-spacing) var(--grid-spacing),
-      var(--subgrid-spacing) var(--subgrid-spacing),
-      var(--subgrid-spacing) var(--subgrid-spacing);
-
-    background-position:
-      0 0,
-      0 0,
-      calc(var(--grid-spacing) / 2) calc(var(--grid-spacing) / 2),
-      calc(var(--grid-spacing) / 2) calc(var(--grid-spacing) / 2);
-  }
-
-  /* dot grid background */
-  .background-dot-grid {
-    --dot-spacing: 1.5rem;
-    --dot-radius: 1.5px;
-    --dot-color: color-mix(in oklab, var(--wa-color-text-normal), transparent 85%);
-
-    background-image: radial-gradient(circle, var(--dot-color) var(--dot-radius), transparent var(--dot-radius));
-    background-size: var(--dot-spacing) var(--dot-spacing);
-  }
-
-  /* wa illustration background pattern */
-  .background-wa-pattern {
     position: relative;
 
     & > * {
       position: relative;
-      z-index: 1;
+      z-index: var(--background-overlay-content-z-index);
+    }
+
+    &::before,
+    &::after {
+      background-color: var(--background-color);
+      content: '';
+      inset: 0;
+      mix-blend-mode: var(--background-blend-mode);
+      position: absolute;
+      z-index: var(--background-overlay-z-index);
+    }
+
+    .wa-dark & {
+      &::before,
+      &::after {
+        mix-blend-mode: var(--background-blend-mode-dark);
+      }
+    }
+  }
+
+  /* grid background overlay */
+  .background-overlay-grid {
+    --grid-line-color: var(--wa-color-text-normal);
+    --grid-line-width: var(--wa-border-width-s);
+    --grid-opacity: 0.1;
+    --grid-spacing: var(--wa-space-2xl);
+    --subgrid-line-color: var(--grid-line-color);
+    --subgrid-line-width: var(--grid-line-width);
+    --subgrid-opacity: 0.05;
+    --subgrid-spacing: calc(var(--grid-spacing) / 2);
+
+    &::before {
+      background-image:
+        linear-gradient(to right, var(--grid-line-color) var(--grid-line-width), transparent var(--grid-line-width)),
+        linear-gradient(to bottom, var(--grid-line-color) var(--grid-line-width), transparent var(--grid-line-width));
+      background-size: var(--grid-spacing) var(--grid-spacing);
+      opacity: var(--grid-opacity);
     }
 
     &::after {
-      --background-pattern-image: url('/assets/images/bg-wa-pattern.svg');
+      background-image:
+        linear-gradient(to right, var(--subgrid-line-color) var(--subgrid-line-width), transparent var(--subgrid-line-width)),
+        linear-gradient(to bottom, var(--subgrid-line-color) var(--subgrid-line-width), transparent var(--subgrid-line-width));
+      background-position: calc(var(--grid-spacing) / 2) calc(var(--grid-spacing) / 2);
+      background-size: var(--subgrid-spacing) var(--subgrid-spacing);
+      opacity: var(--subgrid-opacity);
+    }
 
-      position: absolute;
+    .wa-dark & {
-      inset: 0;
+      --grid-opacity: 0.15;
-      background-color: var(--background-pattern-color, transparent);
+      --subgrid-opacity: 0.08;
-      background-image: var(--background-pattern-image);
+    }
-      background-repeat: repeat;
+  }
-      content: '';
+
-      opacity: var(--background-pattern-opacity, 0.3);
+  /* dot grid background overlay */
-      z-index: 0;
+  .background-overlay-dot-grid {
+    --dot-color: var(--wa-color-text-normal);
+    --dot-opacity: 0.15;
+    --dot-radius: 1.5px;
+    --dot-spacing: 1.5rem;
+
+    &::after {
+      background-image: radial-gradient(circle, var(--dot-color) var(--dot-radius), transparent var(--dot-radius));
+      background-size: var(--dot-spacing) var(--dot-spacing);
+      opacity: var(--dot-opacity);
+    }
+
+    .wa-dark & {
+      --dot-opacity: 0.2;
+    }
+  }
+
+  /* wa illustration background pattern overlay */
+  .background-overlay-wa-pattern {
+    --background-image: url('/assets/images/bg-wa-pattern.svg');
+    --background-opacity: 0.15;
+    --background-size: 640px;
+
+    &::after {
+      background-image: var(--background-image);
+      background-size: var(--background-size);
+      opacity: var(--background-opacity);
+    }
+
+    .wa-dark & {
+      --background-opacity: 0.2;
     }
   }
   /* #endregion */

packages/webawesome/docs/docs/usage.md

@@ -4,6 +4,173 @@ description: Learn more about using custom elements.
 layout: page-outline
 ---
 
+  <!-- WA Pattern Background Examples -->
+  <div class="example">
+    <h3>WA Pattern: Default</h3>
+    <div class="background-overlay-wa-pattern example-content"
+         style="--background-color: var(--wa-color-neutral-border-quiet);">
+      <p>Default settings with normal blend mode</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>WA Pattern: Custom Opacity (Subtle)</h3>
+    <div class="background-overlay-wa-pattern example-content"
+         style="--background-color: var(--wa-color-neutral-border-quiet);
+                --background-opacity: 0.1;">
+      <p>Very subtle pattern with 0.1 opacity</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>WA Pattern: Custom Opacity (Prominent)</h3>
+    <div class="background-overlay-wa-pattern example-content"
+         style="--background-color: var(--wa-color-neutral-border-quiet);
+                --background-opacity: 0.3;">
+      <p>More prominent pattern with 0.3 opacity</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>WA Pattern: Background Color - Brand</h3>
+    <div class="background-overlay-wa-pattern example-content"
+         style="--background-color: var(--wa-color-brand-border-normal);">
+      <p>Pattern with brand color - automatically blends with multiply (light) or screen (dark)</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>WA Pattern: Multiply/Screen Blend Mode</h3>
+    <div class="background-overlay-wa-pattern example-content"
+         style="--background-blend-mode: multiply;
+                --background-blend-mode-dark: screen;
+                --background-color: var(--wa-color-neutral-border-quiet);
+                --background-opacity: 0.15;">
+      <p>Multiply blend mode in light mode, automatically switches to screen blend mode in dark mode. Set both <code>--background-blend-mode: multiply</code> and <code>--background-blend-mode-dark: screen</code>.</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>WA Pattern: Grayscale (Luminosity Blend Mode)</h3>
+    <div class="background-overlay-wa-pattern example-content"
+         style="--background-blend-mode: luminosity;
+                --background-color: transparent;
+                --background-opacity: 0.2;">
+      <p>Luminosity blend mode creates a grayscale effect that uses the pattern's brightness to modulate the content behind it, while preserving the color of the background content.</p>
+    </div>
+  </div>
+
+  <!-- Grid Background Examples -->
+  <div class="example">
+    <h3>Grid: Default</h3>
+    <div class="background-overlay-grid example-content">
+      <p>Default settings with normal blend mode</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Grid: Custom Opacity (Subtle)</h3>
+    <div class="background-overlay-grid example-content"
+         style="--grid-opacity: 0.05;
+                --subgrid-opacity: 0.025;">
+      <p>Very subtle grid with reduced opacity</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Grid: Custom Opacity (Prominent)</h3>
+    <div class="background-overlay-grid example-content"
+         style="--grid-opacity: 0.2;
+                --subgrid-opacity: 0.1;">
+      <p>More prominent grid with increased opacity</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Grid: Background Color - Brand</h3>
+    <div class="background-overlay-grid example-content"
+         style="--background-color: var(--wa-color-brand-fill-quiet);
+                --grid-line-color: var(--wa-color-brand-border-normal);
+                --subgrid-line-color: var(--wa-color-brand-border-normal);">
+      <p>Grid with brand background and line colors - automatically blends with multiply (light) or screen (dark)</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Grid: Multiply/Screen Blend Mode</h3>
+    <div class="background-overlay-grid example-content"
+         style="--background-blend-mode: multiply;
+                --background-blend-mode-dark: screen;
+                --grid-opacity: 0.15;
+                --subgrid-opacity: 0.08;">
+      <p>Multiply blend mode in light mode, automatically switches to screen blend mode in dark mode. Set both <code>--background-blend-mode: multiply</code> and <code>--background-blend-mode-dark: screen</code>.</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Grid: Grayscale (Luminosity Blend Mode)</h3>
+    <div class="background-overlay-grid example-content"
+         style="--background-blend-mode: luminosity;
+                --background-color: transparent;
+                --grid-opacity: 0.2;
+                --subgrid-opacity: 0.1;">
+      <p>Luminosity blend mode creates a grayscale effect that uses the grid's brightness to modulate the content behind it, while preserving the color of the background content.</p>
+    </div>
+  </div>
+
+  <!-- Dot Grid Background Examples -->
+  <div class="example">
+    <h3>Dot Grid: Default</h3>
+    <div class="background-overlay-dot-grid example-content">
+      <p>Default settings with normal blend mode</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Dot Grid: Custom Opacity (Subtle)</h3>
+    <div class="background-overlay-dot-grid example-content"
+         style="--dot-opacity: 0.05;">
+      <p>Very subtle dots with 0.05 opacity</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Dot Grid: Custom Opacity (Prominent)</h3>
+    <div class="background-overlay-dot-grid example-content"
+         style="--dot-opacity: 0.3;">
+      <p>More prominent dots with 0.3 opacity</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Dot Grid: Background Color - Brand</h3>
+    <div class="background-overlay-dot-grid example-content"
+         style="--background-color: var(--wa-color-brand-fill-quiet);
+                --dot-color: var(--wa-color-brand-border-normal);">
+      <p>Dots with brand background and dot colors - automatically blends with multiply (light) or screen (dark)</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Dot Grid: Multiply/Screen Blend Mode</h3>
+    <div class="background-overlay-dot-grid example-content"
+         style="--background-blend-mode: multiply;
+                --background-blend-mode-dark: screen;
+                --dot-opacity: 0.2;">
+      <p>Multiply blend mode in light mode, automatically switches to screen blend mode in dark mode. Set both <code>--background-blend-mode: multiply</code> and <code>--background-blend-mode-dark: screen</code>.</p>
+    </div>
+  </div>
+
+  <div class="example">
+    <h3>Dot Grid: Grayscale (Luminosity Blend Mode)</h3>
+    <div class="background-overlay-dot-grid example-content"
+         style="--background-blend-mode: luminosity;
+                --background-color: transparent;
+                --dot-opacity: 0.2;">
+      <p>Luminosity blend mode creates a grayscale effect that uses the dot grid's brightness to modulate the content behind it, while preserving the color of the background content.</p>
+    </div>
+  </div>
+
 Web Awesome components are just regular HTML elements, or [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) to be precise. You can use them like any other element. Each component has detailed documentation that describes its full API, including properties, events, methods, and more.
 
 If you're new to custom elements, often referred to as "web components," this section will familiarize you with how to use them.
@@ -225,3 +392,4 @@ If you are using types from multiple projects, you can add an array of reference
 ### Other Editors
 
 Most popular editors support custom code completion with a bit of configuration. Please [submit a feature request](https://github.com/shoelace-style/webawesome/issues/new/choose) for your editor of choice. PRs are also welcome!
+