Apply flexbox by default with wa-align-items-* and wa-justify-content-* utils (#1943 )

* add `display: flex` with 0 specificity to utils * add changelog
abstracting layout docs example styling (#1935 )
2026-01-14 04:59:15 +00:00 · 2026-01-13 15:44:37 -05:00 · 2026-01-13 15:31:37 -05:00 · 2026-01-13 15:08:25 -05:00 · 2026-01-13 14:52:17 -05:00 · 2026-01-13 14:12:29 -05:00
16 changed files with 97 additions and 53 deletions
--- a/cspell.json
+++ b/cspell.json
@@ -70,6 +70,7 @@
    "exportparts",
    "fetchpriority",
    "fieldsets",
+    "flexbox",
    "focusin",
    "focusout",
    "fontawesome",
@@ -240,8 +241,6 @@
    "src/translations/!(en).ts",
    "**/*.min.js"
  ],
-  "ignoreRegExpList": [
-    "(^|[^a-z])sl[a-z]*(^|[^a-z])"
-  ],
+  "ignoreRegExpList": ["(^|[^a-z])sl[a-z]*(^|[^a-z])"],
  "useGitignore": true
 }
--- a/packages/webawesome/docs/assets/styles/docs.css
+++ b/packages/webawesome/docs/assets/styles/docs.css
@@ -10,6 +10,13 @@
 :root {
  --wa-brand-orange: #f36944;
  --wa-brand-grey: #30323b;
+
+  /* layout-based example style aspects */
+  --layout-example-border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
+  --layout-example-border-radius: var(--wa-border-radius-l);
+  --layout-example-padding: var(--wa-space-s);
+  --layout-example-element-background: var(--wa-color-indigo-60);
+  --layout-example-element-border-radius: var(--wa-border-radius-m);
 }

 .wa-dark .only-light,
--- a/packages/webawesome/docs/docs/components/divider.md
+++ b/packages/webawesome/docs/docs/components/divider.md
@@ -41,7 +41,7 @@ Use the `--spacing` custom property to change the amount of space between the di

 ### Orientation

-The default orientation for dividers is `horizontal`. Set `orientation` attribute to `vertical` to draw a vertical divider. The divider will span the full height of its container.
+The default orientation for dividers is `horizontal`. Set `orientation` attribute to `vertical` to draw a vertical divider. The divider will span the full height of its [Flexbox](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox) or [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/grid) container.

 ```html {.example}
 <div style="display: flex; align-items: center;">
@@ -53,6 +53,10 @@ The default orientation for dividers is `horizontal`. Set `orientation` attribut
 </div>
 ```

+:::info
+If your container isn't Flexbox or CSS Grid, you may need to set an explicit height for the divider.
+:::
+
 ### Dropdown Dividers

 Use dividers in [dropdowns](/docs/components/dropdown) to visually group dropdown items.
--- a/packages/webawesome/docs/docs/resources/changelog.md
+++ b/packages/webawesome/docs/docs/resources/changelog.md
@@ -14,10 +14,11 @@ Components with the <wa-badge variant="warning">Experimental</wa-badge> badge sh
 ## Next

 - Added `pointercancel` and `touchcancel` event handling to draggable elements to prevent drags from getting stuck
- Added `justify-content` CSS utilities [pr:1930]
- Added missing `.wa-gap-4xl` utility class [pr:1931]
+- Added `wa-justify-content-*` utility classes [pr:1930]
+- Added missing `wa-gap-4xl` utility class [pr:1931]
 - Fixed a bug in `<wa-combobox>` that prevented the listbox from opening when options were preselected [issue:1883]
 - Fixed a bug in draggable elements that caused a TypeError on `touchend` events when `event.touches` was empty
+- Modified `wa-align-items-*` utility classes to apply `display: flex` by default [pr:1943]

 ## 3.1.0

--- a/packages/webawesome/docs/docs/utilities/align-items.md
+++ b/packages/webawesome/docs/docs/utilities/align-items.md
@@ -7,15 +7,16 @@ tags: layoutUtilities

 <style>
  .preview-wrapper {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
+    border: var(--layout-example-border);
    border-radius: var(--wa-border-radius-m);
    min-block-size: 3em;
    min-inline-size: 5em;
    padding: var(--wa-space-2xs);
  }
+  
  .preview-block {
    aspect-ratio: 1 / 1;
-    background-color: var(--wa-color-neutral-fill-loud);
+    background-color: var(--layout-example-element-background);
    border-radius: var(--wa-border-radius-s);
    min-block-size: 1em;
  }
--- a/packages/webawesome/docs/docs/utilities/cluster.md
+++ b/packages/webawesome/docs/docs/utilities/cluster.md
@@ -7,14 +7,14 @@ tags: layoutUtilities

 <style>
  :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-cluster']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
  }

  [class*='wa-cluster'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
    min-block-size: 4rem;
    min-inline-size: 4rem;
  }
--- a/packages/webawesome/docs/docs/utilities/flank.md
+++ b/packages/webawesome/docs/docs/utilities/flank.md
@@ -7,14 +7,14 @@ tags: layoutUtilities

 <style>
  :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-flank']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
  }

  [class*='wa-flank'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
    min-block-size: 4rem;
    min-inline-size: 4rem;
  }
--- a/packages/webawesome/docs/docs/utilities/frame.md
+++ b/packages/webawesome/docs/docs/utilities/frame.md
@@ -7,13 +7,13 @@ tags: layoutUtilities

 <style>
  [class*='wa-frame']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    padding: var(--layout-example-padding);
  }

  [class*='wa-frame'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
    min-block-size: 4rem;
    min-inline-size: 4rem;
  }
--- a/packages/webawesome/docs/docs/utilities/gap.md
+++ b/packages/webawesome/docs/docs/utilities/gap.md
@@ -6,11 +6,19 @@ tags: layoutUtilities
 ---

 <style>
+  .preview-wrapper {
+    border: var(--layout-example-border);
+    border-radius: var(--wa-border-radius-m);
+    min-block-size: 3em;
+    min-inline-size: 5em;
+    padding: var(--wa-space-2xs);
+  }
+
  .preview-block {
    aspect-ratio: 1 / 1;
-    background-color: var(--wa-color-neutral-fill-loud);
+    background-color: var(--layout-example-element-background);
    border-radius: var(--wa-border-radius-s);
-    min-block-size: 1.5em;
+    min-block-size: 1em;
  }
 </style>

@@ -20,15 +28,15 @@ Besides `wa-gap-0`, which sets `gap` to zero, each class corresponds to one of t

 | Class Name   | `gap` Value      | Preview                                                                                                     |
 | ------------ | ---------------- | ----------------------------------------------------------------------------------------------------------- |
-| `wa-gap-0`   | `0`              | <div class="wa-cluster wa-gap-0"><div class="preview-block"></div><div class="preview-block"></div></div>   |
-| `wa-gap-3xs` | `--wa-space-3xs` | <div class="wa-cluster wa-gap-3xs"><div class="preview-block"></div><div class="preview-block"></div></div> |
-| `wa-gap-2xs` | `--wa-space-2xs` | <div class="wa-cluster wa-gap-2xs"><div class="preview-block"></div><div class="preview-block"></div></div> |
-| `wa-gap-xs`  | `--wa-space-xs`  | <div class="wa-cluster wa-gap-xs"><div class="preview-block"></div><div class="preview-block"></div></div>  |
-| `wa-gap-s`   | `--wa-space-s`   | <div class="wa-cluster wa-gap-s"><div class="preview-block"></div><div class="preview-block"></div></div>   |
-| `wa-gap-m`   | `--wa-space-m`   | <div class="wa-cluster wa-gap-m"><div class="preview-block"></div><div class="preview-block"></div></div>   |
-| `wa-gap-l`   | `--wa-space-l`   | <div class="wa-cluster wa-gap-l"><div class="preview-block"></div><div class="preview-block"></div></div>   |
-| `wa-gap-xl`  | `--wa-space-xl`  | <div class="wa-cluster wa-gap-xl"><div class="preview-block"></div><div class="preview-block"></div></div>  |
-| `wa-gap-2xl` | `--wa-space-2xl` | <div class="wa-cluster wa-gap-2xl"><div class="preview-block"></div><div class="preview-block"></div></div> |
-| `wa-gap-3xl` | `--wa-space-3xl` | <div class="wa-cluster wa-gap-3xl"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-gap-0`   | `0`              | <div class="preview-wrapper wa-cluster wa-gap-0"><div class="preview-block"></div><div class="preview-block"></div></div>   |
+| `wa-gap-3xs` | `--wa-space-3xs` | <div class="preview-wrapper wa-cluster wa-gap-3xs"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-gap-2xs` | `--wa-space-2xs` | <div class="preview-wrapper wa-cluster wa-gap-2xs"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-gap-xs`  | `--wa-space-xs`  | <div class="preview-wrapper wa-cluster wa-gap-xs"><div class="preview-block"></div><div class="preview-block"></div></div>  |
+| `wa-gap-s`   | `--wa-space-s`   | <div class="preview-wrapper wa-cluster wa-gap-s"><div class="preview-block"></div><div class="preview-block"></div></div>   |
+| `wa-gap-m`   | `--wa-space-m`   | <div class="preview-wrapper wa-cluster wa-gap-m"><div class="preview-block"></div><div class="preview-block"></div></div>   |
+| `wa-gap-l`   | `--wa-space-l`   | <div class="preview-wrapper wa-cluster wa-gap-l"><div class="preview-block"></div><div class="preview-block"></div></div>   |
+| `wa-gap-xl`  | `--wa-space-xl`  | <div class="preview-wrapper wa-cluster wa-gap-xl"><div class="preview-block"></div><div class="preview-block"></div></div>  |
+| `wa-gap-2xl` | `--wa-space-2xl` | <div class="preview-wrapper wa-cluster wa-gap-2xl"><div class="preview-block"></div><div class="preview-block"></div></div> |
+| `wa-gap-3xl` | `--wa-space-3xl` | <div class="preview-wrapper wa-cluster wa-gap-3xl"><div class="preview-block"></div><div class="preview-block"></div></div> |
 <!-- Pending 3.2.0 release -->
-<!-- | `wa-gap-4xl` | `--wa-space-4xl` | <div class="wa-cluster wa-gap-4xl"><div class="preview-block"></div><div class="preview-block"></div></div> | -->
+<!-- | `wa-gap-4xl` | `--wa-space-4xl` | <div class="preview-wrapper wa-cluster wa-gap-4xl"><div class="preview-block"></div><div class="preview-block"></div></div> | -->
--- a/packages/webawesome/docs/docs/utilities/grid.md
+++ b/packages/webawesome/docs/docs/utilities/grid.md
@@ -7,14 +7,14 @@ tags: layoutUtilities

 <style>
  :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-grid']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
  }

  [class*='wa-grid'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
    min-block-size: 4rem;
    min-inline-size: 4rem;
  }
--- a/packages/webawesome/docs/docs/utilities/justify-content.md
+++ b/packages/webawesome/docs/docs/utilities/justify-content.md
@@ -9,15 +9,16 @@ unlisted: true

 <style>
  .preview-wrapper {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
+    border: var(--layout-example-border);
    border-radius: var(--wa-border-radius-m);
    min-block-size: 3em;
    min-inline-size: 5em;
    padding: var(--wa-space-2xs);
  }
+
  .preview-block {
    aspect-ratio: 1 / 1;
-    background-color: var(--wa-color-neutral-fill-loud);
+    background-color: var(--layout-example-element-background);
    border-radius: var(--wa-border-radius-s);
    min-block-size: 1em;
  }
--- a/packages/webawesome/docs/docs/utilities/split.md
+++ b/packages/webawesome/docs/docs/utilities/split.md
@@ -7,14 +7,14 @@ tags: layoutUtilities

 <style>
  :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-split']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
  }

  [class*='wa-split'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
    min-block-size: 4rem;
    min-inline-size: 4rem;
  }
--- a/packages/webawesome/docs/docs/utilities/stack.md
+++ b/packages/webawesome/docs/docs/utilities/stack.md
@@ -7,14 +7,14 @@ tags: layoutUtilities

 <style>
  :is(.wa-flank, .wa-grid, .wa-stack) > [class*='wa-stack']:has(div:empty) {
-    border: var(--wa-border-width-s) dashed var(--wa-color-neutral-border-normal);
-    border-radius: var(--wa-border-radius-l);
-    padding: var(--wa-space-s);
+    border: var(--layout-example-border);
+    border-radius: var(--layout-example-border-radius);
+    padding: var(--layout-example-padding);
  }

  [class*='wa-stack'] div:empty {
-    background-color: var(--wa-color-indigo-60);
-    border-radius: var(--wa-border-radius-m);
+    background-color: var(--layout-example-element-background);
+    border-radius: var(--layout-example-element-border-radius);
    min-block-size: 4rem;
    min-inline-size: 4rem;
  }
--- a/packages/webawesome/src/components/tooltip/tooltip.ts
+++ b/packages/webawesome/src/components/tooltip/tooltip.ts
@@ -79,7 +79,7 @@ export default class WaTooltip extends WebAwesomeElement {
  /** The amount of time to wait before showing the tooltip when the user mouses in. */
  @property({ attribute: 'show-delay', type: Number }) showDelay = 150;

-  /** The amount of time to wait before hiding the tooltip when the user mouses out.. */
+  /** The amount of time to wait before hiding the tooltip when the user mouses out. */
  @property({ attribute: 'hide-delay', type: Number }) hideDelay = 0;

  /**
--- a/packages/webawesome/src/styles/utilities/align-items.css
+++ b/packages/webawesome/src/styles/utilities/align-items.css
@@ -1,4 +1,15 @@
@layer wa-utilities {
+  /* Apply Flexbox with 0 specificity to ensure an align-items util produces a visible change */
+  :where(
+    .wa-align-items-start,
+    .wa-align-items-end,
+    .wa-align-items-center,
+    .wa-align-items-stretch,
+    .wa-align-items-baseline
+  ) {
+    display: flex;
+  }
+
  .wa-align-items-start {
    align-items: flex-start;
  }
--- a/packages/webawesome/src/styles/utilities/justify-content.css
+++ b/packages/webawesome/src/styles/utilities/justify-content.css
@@ -1,4 +1,16 @@
@layer wa-utilities {
+  /* Apply Flexbox with 0 specificity to ensure a justify-content util produces a visible change */
+  :where(
+    .wa-justify-content-start,
+    .wa-justify-content-end,
+    .wa-justify-content-center,
+    .wa-justify-content-space-around,
+    .wa-justify-content-space-between,
+    .wa-justify-content-space-evenly
+  ) {
+    display: flex;
+  }
+
  .wa-justify-content-start {
    justify-content: flex-start;
  }
Author	SHA1	Message	Date
Lindsay M	46aa1429a7	Apply flexbox by default with `wa-align-items-` and `wa-justify-content-` utils (#1943 ) * add `display: flex` with 0 specificity to utils * add changelog	2026-01-13 15:44:37 -05:00
Brian Talbot	4b68a741bd	abstracting layout docs example styling (#1935 )	2026-01-13 15:31:37 -05:00
Cory LaViska	bd58f7f0a1	Divider docs (#1945 ) * don't you know me * clarify and add note	2026-01-13 15:08:25 -05:00
Alex Rao	e8f366835c	Update tooltip.ts (#1928 ) This removes the second period in the docs, which gets reflected on the website	2026-01-13 14:52:17 -05:00
Cory LaViska	70df6fea1f	fix drag bug; closes #1905 (#1908 )	2026-01-13 14:12:29 -05:00