@dereekb/dbx-web 13.17.0 → 13.18.0

package/lib/layout/card/_card.scss

@@ -5,18 +5,57 @@
 // MARK: Mixin
 @mixin core() {
   /// @dbx-utility mat-card-dbx-color
-  /// @intent re-emits the dbx-color background paint at higher specificity than MDC's `.mat-mdc-card` `background-color` rule, so a host-level `[dbxColor]` on `<mat-card>` shows through every appearance variant (elevated / outlined / filled). Tonal opacity is honoured via the existing `--dbx-color-bg-tone` channel; in tonal mode the text color flips to the vibrant theme color so contrast survives the light wash.
+  /// @intent re-emits the dbx-color background paint at higher specificity than MDC's `.mat-mdc-card` `background-color` rule, so a host-level `[dbxColor]` on `<mat-card>` shows through every appearance variant (elevated / outlined / filled). Tonal opacity is honoured via the existing `--dbx-color-bg-tone` channel; in tonal mode the text color flips to the vibrant theme color so contrast survives the light wash. A zero-specificity `:where(:not(.dbx-card-color-accent))` guard exempts the `.dbx-card-color-accent` card so its body stays unpainted while only its left edge takes the bound color.
   /// @role color
-  /// @see-also color, color-bg, color-tonal
-  mat-card.dbx-color {
+  /// @see-also color, color-bg, color-tonal, card-color-accent
+  mat-card.dbx-color:where(:not(.dbx-card-color-accent)) {
     background: color-mix(in srgb, var(#{theming.$dbx-bg-color-var}) var(#{theming.$dbx-bg-tone-var}, 100%), transparent);
     color: var(#{theming.$dbx-color-var});
 
+    // outlined buttons inside the painted card follow the card's contrast color — the M3 default
+    // primary label/outline may be illegible on the painted surface (e.g. an inverse-surface card).
+    --mat-button-outlined-label-text-color: var(#{theming.$dbx-color-var});
+    --mat-button-outlined-outline-color: color-mix(in srgb, var(#{theming.$dbx-color-var}) 30%, transparent);
+
     &.dbx-color-tonal {
       color: var(#{theming.$dbx-bg-color-var});
+      --mat-button-outlined-label-text-color: var(#{theming.$dbx-bg-color-var});
+      --mat-button-outlined-outline-color: color-mix(in srgb, var(#{theming.$dbx-bg-color-var}) 30%, transparent);
     }
   }
 
+  /// @dbx-utility mat-card-content-flex-column
+  /// @intent re-emits the `.dbx-flex-column` display at higher specificity than MDC's `.mat-mdc-card-content` `display: block` rule, so the flex utilities work on `<mat-card-content>` — pair with `.dbx-flex-fill` on the content (fills the card's stretched height) and on a child (absorbs the remaining height).
+  /// @role flex
+  /// @see-also flex-column, flex-fill, mat-card-dbx-color
+  mat-card-content.dbx-flex-column {
+    display: flex;
+    flex-direction: column;
+  }
+
+  /// @dbx-utility card-accent
+  /// @intent accent-edged `<mat-card>` — paints a solid border down the card's left edge to flag or categorize the card. Defaults to the M3 primary color; override `--dbx-card-accent-color` for a different hue or `--dbx-card-accent-border-width` for thickness.
+  /// @role layout
+  /// @see-also card-banner, card-select, color
+  // The extra `mat-card.`-qualified selector out-specifies MDC's later-emitted
+  // `.mdc-card--outlined` border shorthand, which would otherwise reset the
+  // accent edge back to the 1px outline on outlined cards.
+  .dbx-card-accent,
+  mat-card.dbx-card-accent {
+    border-left: var(--dbx-card-accent-border-width, 4px) solid var(--dbx-card-accent-color, var(--mat-sys-primary));
+  }
+
+  /// @dbx-utility card-color-accent
+  /// @intent accent-edged status `<mat-card>` driven by `[dbxColor]` — the left edge paints from the bound color's `--dbx-bg-color-current` token while the card body keeps its normal unpainted surface (the `mat-card.dbx-color` surface paint exempts this class via its `:where()` guard). Always pair with `[dbxColor]` (e.g. `dbxColor="success"`); override `--dbx-card-accent-border-width` for thickness. Caveat: the theme root declares a default `--dbx-bg-color-current`, so without a bound `[dbxColor]` the edge shows that inherited default, not the `--mat-sys-primary` fallback.
+  /// @role layout
+  /// @see-also card-accent, color, mat-card-dbx-color
+  // `mat-card.`-qualified for the same `.mdc-card--outlined` border-shorthand
+  // reason as `.dbx-card-accent` above.
+  .dbx-card-color-accent,
+  mat-card.dbx-card-color-accent {
+    border-left: var(--dbx-card-accent-border-width, 4px) solid var(--dbx-bg-color-current, var(--dbx-card-accent-color, var(--mat-sys-primary)));
+  }
+
   /// @dbx-utility card-banner
   /// @intent banner-style `<mat-card>` — pair with `[dbxColor]` (+ `[dbxColorTone]`) for the tonal surface. Drop `<mat-card-header>` entirely; put the icon + `<mat-card-title>` row inside `<mat-card-content>` via a `.dbx-card-banner-header` child, and the action buttons inside `<mat-card-footer>`.
   /// @role layout
@@ -89,6 +128,155 @@
       --mat-outlined-card-outline-width: 2px;
     }
   }
+
+  /// @dbx-utility card-horizontal
+  /// @intent horizontally scrolling row of fixed-width, equal-height `.dbx-card-horizontal-item` cards — `align-items: stretch` keeps the cards equal-height while `overflow-x: auto` scrolls the row on narrow viewports. Because `overflow-x: auto` forces vertical overflow to clip, the row reserves headroom via `padding-top` so a `.dbx-card-horizontal-tab` chip poking above a card stays inside the scrollable padding box instead of being clipped; override `--dbx-card-horizontal-tab-overlap` to change the headroom together with the tab.
+  /// @role layout
+  /// @see-also card-horizontal-item, flex-bar, chip
+  .dbx-card-horizontal {
+    display: flex;
+    align-items: stretch;
+    gap: var(--dbx-padding-3);
+    overflow-x: auto;
+    // overflow-x:auto computes overflow-y to auto — anything above the row's
+    // padding box is scroll-clipped and unreachable, so a poking tab must live
+    // INSIDE the padding box: reserve its overlap height as top padding.
+    padding-top: calc(var(--dbx-card-horizontal-tab-overlap, 10px) + var(--dbx-padding-1));
+    padding-bottom: var(--dbx-padding-2);
+  }
+
+  /// @dbx-utility card-horizontal-item
+  /// @intent fixed-width card for a `.dbx-card-horizontal` row — apply to `<mat-card appearance="outlined">`. Children: an optional `.dbx-card-horizontal-tab` `<dbx-chip>` (absolutely positioned poking above the top edge), an optional full-bleed `.dbx-card-horizontal-header` status bar (plain `<div>` placed BEFORE `<mat-card-content>` — mat-card children stack in a padding-less flex column, so the bar is edge-to-edge for free), the `<mat-card-content>` body, and a `<mat-card-footer>` CTA pushed to the card bottom via `margin-top: auto` so stretch-aligned cards keep their buttons on one line. Toggle `.dbx-card-horizontal-item-highlight` to repaint the outlined-card border in the primary color. Override `--dbx-card-horizontal-item-width` for a different card width.
+  /// @role layout
+  /// @see-also card-horizontal, card-horizontal-header, card-select, chip, color
+  .dbx-card-horizontal-item {
+    position: relative;
+    flex: 0 0 var(--dbx-card-horizontal-item-width, 300px);
+    width: var(--dbx-card-horizontal-item-width, 300px);
+
+    // the header div is the first child, so MDC's
+    // `mat-card-content:first-child { padding-top: 16px }` no longer fires —
+    // restore the body's top inset.
+    > mat-card-content {
+      padding-top: var(--dbx-padding-3);
+    }
+
+    // mat-card is already a flex column — anchor the CTA to the card bottom.
+    > mat-card-footer {
+      margin-top: auto;
+      padding: var(--dbx-padding-2) var(--dbx-padding-3) var(--dbx-padding-3);
+
+      > button,
+      > a {
+        width: 100%;
+      }
+    }
+
+    // highlight (e.g. "today") — repaint the outlined-card border (same
+    // pattern as `.dbx-card-select.dbx-card-selected`).
+    &.dbx-card-horizontal-item-highlight {
+      --mat-outlined-card-outline-color: var(--mat-sys-primary);
+      --mat-outlined-card-outline-width: 2px;
+    }
+  }
+
+  /// @dbx-utility card-horizontal-header
+  /// @intent full-bleed status bar across the top of a `.dbx-card-horizontal-item` — a plain `<div>` direct child of `<mat-card>` before `<mat-card-content>`. Pair with `[dbxColor]` for a solid bar or `[dbxColor]` + `[dbxColorTone]` for a tonal wash (tonal mode flips the label to the vibrant theme color). Compose the label from `.dbx-text-label-medium .dbx-uppercase .dbx-tracked-wide`; lead with a `<mat-icon>` or a `.dbx-card-horizontal-header-dot`.
+  /// @role layout
+  /// @see-also card-horizontal-item, card-horizontal-header-dot, color, color-tonal
+  .dbx-card-horizontal-header {
+    display: flex;
+    align-items: center;
+    gap: var(--dbx-padding-2);
+    padding: var(--dbx-padding-2) var(--dbx-padding-3);
+    border-top-left-radius: inherit;
+    border-top-right-radius: inherit;
+  }
+
+  // `[dbxColor]` provides the tokens + the `.dbx-color` marker; the header paints
+  // itself from them (mirrors `mat-card.dbx-color`). The `:not(.dbx-default)` guard
+  // keeps an uncolored header from painting (the marker is always applied). Tonal
+  // mode flips the label to the vibrant color.
+  .dbx-card-horizontal-header.dbx-color:not(.dbx-default) {
+    background: color-mix(in srgb, var(#{theming.$dbx-bg-color-var}) var(#{theming.$dbx-bg-tone-var}, 100%), transparent);
+    color: var(#{theming.$dbx-color-var});
+
+    &.dbx-color-tonal {
+      color: var(#{theming.$dbx-bg-color-var});
+    }
+  }
+
+  /// @dbx-utility card-horizontal-header-dot
+  /// @intent small status dot inside a `.dbx-card-horizontal-header` — painted from `currentColor` so it follows the header's (tonal) text color with no extra color wiring.
+  /// @role layout
+  /// @see-also card-horizontal-header
+  .dbx-card-horizontal-header-dot {
+    flex-shrink: 0;
+    width: var(--dbx-card-horizontal-header-dot-size, 8px);
+    height: var(--dbx-card-horizontal-header-dot-size, 8px);
+    border-radius: 50%;
+    background: currentColor;
+  }
+
+  /// @dbx-utility card-horizontal-tab
+  /// @intent "TODAY"-style tab — apply to a `<dbx-chip [tone]="100" [small]="true">` inside a `.dbx-card-horizontal-item`; absolutely positioned so it pokes above the card's top edge by `--dbx-card-horizontal-tab-overlap` (which the `.dbx-card-horizontal` row also reserves as top padding so the scroll container does not clip it).
+  /// @role layout
+  /// @see-also card-horizontal, card-horizontal-item, chip
+  // Scoped under the item (0,2,0 specificity) so `position: absolute` beats
+  // `.dbx-chip`'s later-emitted `position: relative` (text.core() runs after
+  // card.core() in all-layout-core).
+  .dbx-card-horizontal-item .dbx-card-horizontal-tab {
+    position: absolute;
+    top: calc(-1 * var(--dbx-card-horizontal-tab-overlap, 10px));
+    left: var(--dbx-padding-3);
+    z-index: 1;
+  }
+
+  /// @dbx-utility card-horizontal-detail
+  /// @intent compact icon + text detail row (location / dates / time) inside a `.dbx-card-horizontal-item` body — muted `on-surface-variant` text with a small leading `<mat-icon>`; also fits a label/value row when composed with `.dbx-spacer`.
+  /// @role layout
+  /// @see-also card-horizontal-item, spacer, hint
+  .dbx-card-horizontal-detail {
+    display: flex;
+    align-items: center;
+    gap: var(--dbx-padding-2);
+    padding: var(--dbx-padding-1) 0;
+    color: var(--mat-sys-on-surface-variant);
+
+    > mat-icon {
+      flex-shrink: 0;
+      width: var(--dbx-card-horizontal-detail-icon-size, 18px);
+      height: var(--dbx-card-horizontal-detail-icon-size, 18px);
+      font-size: var(--dbx-card-horizontal-detail-icon-size, 18px);
+    }
+  }
+
+  /// @dbx-utility card-horizontal-divider
+  /// @intent hairline divider between `.dbx-card-horizontal-item` body sections — the standard `--mat-sys-outline-variant` border-bottom pattern with vertical rhythm baked in.
+  /// @role layout
+  /// @see-also card-horizontal-item
+  .dbx-card-horizontal-divider {
+    border-bottom: 1px solid var(--mat-sys-outline-variant);
+    margin: var(--dbx-padding-2) 0;
+  }
+
+  /// @dbx-utility card-horizontal-mini
+  /// @intent small outlined "mini card" row inside a `.dbx-card-horizontal-item` body (e.g. a recommended job: name + detail left, price right) — outline-variant border, corner-small radius, space-between flex row.
+  /// @role layout
+  /// @see-also card-horizontal-item, color-text
+  .dbx-card-horizontal-mini {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--dbx-padding-2);
+    padding: var(--dbx-padding-2) var(--dbx-padding-3);
+    border: 1px solid var(--mat-sys-outline-variant);
+    border-radius: var(--mat-sys-corner-small, 8px);
+
+    & + & {
+      margin-top: var(--dbx-padding-2);
+    }
+  }
 }
 
 @mixin theme($theme-config) {

package/lib/layout/column/_column.scss

@@ -4,7 +4,7 @@
 $two-column-left-width-var: theming.$two-column-left-width-var;
 $two-column-left-width: theming.$two-column-left-width;
 $two-column-navbar-height: theming.$content-navbar-height;
-$two-columns-right-padding-size: 6px;
+$two-columns-right-padding-size: var(--dbx-padding-2);
 
 // MARK: Mixin
 @mixin core() {
@@ -83,8 +83,8 @@ $two-columns-right-padding-size: 6px;
   }
 
   .dbx-two-column-head {
-    padding: 0 6px; // only padded on the left
-    border-bottom: 1px solid rgba(0, 0, 0, 0.14);
+    padding: 0 var(--dbx-padding-2); // only padded on the left
+    border-bottom: 1px solid var(--mat-sys-outline-variant);
     height: $two-column-navbar-height;
 
     display: flex;

package/lib/layout/content/_content.scss

@@ -57,18 +57,26 @@ $dbx-border-opacity-default: 20%;
   }
 
   /// @dbx-utility content-pit
-  /// @intent recessed surface pit — `--mat-sys-surface-container` background with a `padding-4` inset, used to visually nest content (e.g. logs, JSON, quoted blocks)
+  /// @intent recessed surface pit — `--mat-sys-surface-container` background with a `padding-4` inset, used to visually nest content (e.g. logs, JSON, quoted blocks); rounded by default, opt out with `.dbx-corners-none`
   /// @role layout
-  /// @see-also dbx-content-pit-rounded, dbx-content-pit-scrollable, dbx-content-border, dbx-content-elevate
+  /// @see-also dbx-content-pit-scrollable, dbx-content-border, dbx-content-elevate, dbx-corners-none
   .dbx-content-pit {
     padding: $pit-padding;
   }
 
+  // Pits round by default. Kept OUT of the `.dbx-content-pit` rule and wrapped
+  // in `:where()` so specificity stays at 0 — any single-class utility
+  // (`.dbx-corners-none`, `.dbx-corners-large`, or an app class) overrides it.
+  :where(.dbx-content-pit) {
+    border-radius: theming.$dbx-content-pit-rounded-border-radius;
+  }
+
   /// @dbx-utility content-pit-rounded
   /// @intent rounded modifier for `.dbx-content-pit` — applies the `theming.$dbx-content-pit-rounded-border-radius` corner radius
   /// @role layout
   /// @parent content-pit
-  /// @see-also dbx-content-pit
+  /// @see-also dbx-content-pit, dbx-corners-none
+  /// @deprecated Pits round by default now; this modifier is a harmless back-compat alias emitting the same radius. To square a pit use `.dbx-corners-none`.
   .dbx-content-pit-rounded {
     border-radius: theming.$dbx-content-pit-rounded-border-radius;
   }
@@ -135,7 +143,7 @@ $dbx-border-opacity-default: 20%;
   .dbx-content-scroll-lock {
     height: 100%;
     overflow: hidden;
-    padding: 0 2px; // Override padding
+    padding: 0 var(--dbx-padding-1); // Override padding
   }
 
   /// @dbx-utility content-container
@@ -153,7 +161,7 @@ $dbx-border-opacity-default: 20%;
     }
 
     &.container-padding-min {
-      padding: 0 2px;
+      padding: 0 var(--dbx-padding-1);
     }
 
     &.container-padding-small {
@@ -165,15 +173,15 @@ $dbx-border-opacity-default: 20%;
     }
 
     &.container-top-padding-min {
-      padding-top: 2px;
+      padding-top: var(--dbx-padding-1);
     }
 
     &.container-top-padding-small {
-      padding-top: 6px;
+      padding-top: var(--dbx-padding-2);
     }
 
     &.container-top-padding-normal {
-      padding-top: 12px;
+      padding-top: var(--dbx-padding-3);
     }
 
     // width
@@ -214,13 +222,20 @@ $dbx-border-opacity-default: 20%;
   /// @role spacing
   /// @see-also dbx-content-container, dbx-content-page, dbx-content-pit-scrollable
   .dbx-scroll-content {
-    padding-bottom: $scroll-content-bottom-padding;
+    padding-bottom: var(--dbx-scroll-content-bottom-padding, #{$scroll-content-bottom-padding});
   }
 
   .dbx-content-pit {
     background: var(--mat-sys-surface-container);
   }
 
+  // pits on a [dbxColor]-painted surface wash from the current contrast color instead of the
+  // surface-container token, which would clash with the painted background (e.g. a dark inverse
+  // card). Override --dbx-content-pit-color-tone (percentage) to tune the wash.
+  .dbx-color .dbx-content-pit {
+    background: color-mix(in srgb, #{theming.$dbx-color} var(--dbx-content-pit-color-tone, 11%), transparent);
+  }
+
   .dbx-content-border {
     border: 3px dashed color-mix(in srgb, var(--dbx-border-color, var(--mat-sys-outline-variant)) var(--dbx-border-opacity, $dbx-border-opacity-default), transparent);
   }

package/lib/layout/list/_list.scss

@@ -8,6 +8,50 @@ $list-item-padded-min-height: 42px;
   .dbx-list {
     overflow: hidden;
     height: 100%;
+
+    // dbx-list (selection/standard) rows default to an M3 medium corner via the overridable
+    // `--dbx-list-item-border-radius` token; `.dbx-list-square-items` zeroes it and the style-demo
+    // `list-corner-*` levers re-point it. Both shape tokens resolve to the same value, so no
+    // `border-radius` redeclaration is needed; the more specific `.dbx-list-card-items-list` item rule
+    // deliberately wins for card lists.
+    --mat-list-active-indicator-shape: var(--dbx-list-item-border-radius, var(--mat-sys-corner-medium, 12px));
+    --mat-list-list-item-container-shape: var(--dbx-list-item-border-radius, var(--mat-sys-corner-medium, 12px));
+
+    .mat-mdc-list-item {
+      --mat-focus-indicator-border-radius: var(--mat-list-list-item-container-shape);
+    }
+  }
+
+  // dbx-anchor-list (nav) rows default to an M3 medium corner via their OWN
+  // `--dbx-anchor-list-item-border-radius` token — separate from `.dbx-list` so the style-demo
+  // `anchor-list-corner-*` levers control anchor lists independently. `.dbx-list-square-items`
+  // zeroes this token too. The `.dbx-anchor-list` class lives on the inner `mat-nav-list`.
+  .dbx-anchor-list {
+    --mat-list-active-indicator-shape: var(--dbx-anchor-list-item-border-radius, var(--mat-sys-corner-medium, 12px));
+    --mat-list-list-item-container-shape: var(--dbx-anchor-list-item-border-radius, var(--mat-sys-corner-medium, 12px));
+
+    .mat-mdc-list-item {
+      --mat-focus-indicator-border-radius: var(--mat-list-list-item-container-shape);
+    }
+  }
+
+  // The sidenav anchor list rows sit flush against the left screen edge, so only the RIGHT corners round —
+  // the radius is composed into a `0 r r 0` shorthand (top-left / top-right / bottom-right / bottom-left),
+  // leaving the left corners square. The "how round" radius defaults to the regular anchor-list radius
+  // (`--dbx-anchor-list-item-border-radius`) so the sidenav tracks the `anchor-list-corner-*` lever by default,
+  // but `--dbx-sidenav-anchor-list-item-border-radius` overrides it for sidenav-specific tuning. Higher
+  // specificity than `.dbx-anchor-list`, so it wins for the inner nav-list inside a sidenav host.
+  .dbx-sidenav-anchor-list .dbx-anchor-list {
+    --mat-list-active-indicator-shape: 0 var(--dbx-sidenav-anchor-list-item-border-radius, var(--dbx-anchor-list-item-border-radius, var(--mat-sys-corner-medium, 12px))) var(--dbx-sidenav-anchor-list-item-border-radius, var(--dbx-anchor-list-item-border-radius, var(--mat-sys-corner-medium, 12px))) 0;
+    --mat-list-list-item-container-shape: 0 var(--dbx-sidenav-anchor-list-item-border-radius, var(--dbx-anchor-list-item-border-radius, var(--mat-sys-corner-medium, 12px))) var(--dbx-sidenav-anchor-list-item-border-radius, var(--dbx-anchor-list-item-border-radius, var(--mat-sys-corner-medium, 12px))) 0;
+  }
+
+  // MDC's two-line + leading-icon variant sizes the primary-text baseline-spacer `::before` to 32px, taller than
+  // the 28px the two-line (no-leading-icon) rule uses, which over-tall the title box and pushes the title/hint
+  // group off-center in dbx-anchor custom-anchor rows (reads as top-aligned). Pin the spacer back to 28px within
+  // anchor lists so the rows center vertically (selection lists, which keep MDC's structure, are untouched).
+  .dbx-anchor-list .mdc-list-item--with-leading-icon.mdc-list-item--with-two-lines .mdc-list-item__primary-text::before {
+    height: 28px;
   }
 
   .dbx-list-empty-content {
@@ -94,7 +138,7 @@ $list-item-padded-min-height: 42px;
   .dbx-list-view-group {
     .dbx-list-view-group-header {
       .dbx-list-two-line-item .dbx-list-two-line-item-with-icon {
-        padding: 2px 0; // override the padding when there is an icon
+        padding: var(--dbx-padding-1) 0; // override the padding when there is an icon
       }
     }
   }
@@ -122,8 +166,8 @@ $list-item-padded-min-height: 42px;
   /// @role spacing
   /// @see-also dbx-list-item-padded-thick, dbx-list-item-p0
   .dbx-list-item-padded {
-    min-height: $list-item-padded-min-height;
-    padding: 2px 6px;
+    min-height: var(--dbx-list-item-padded-min-height, #{$list-item-padded-min-height});
+    padding: var(--dbx-padding-1) var(--dbx-padding-2);
   }
 
   /// @dbx-utility list-item-padded-thick
@@ -131,10 +175,16 @@ $list-item-padded-min-height: 42px;
   /// @role spacing
   /// @see-also dbx-list-item-padded
   .dbx-list-item-padded-thick {
-    min-height: $list-item-padded-min-height;
+    min-height: var(--dbx-list-item-padded-min-height, #{$list-item-padded-min-height});
     padding: theming.$padding-3;
   }
 
+  // No side padding if the parent list component has the dbx-list-no-item-padding class.
+  .dbx-list-no-item-padding .dbx-list-item-padded {
+    padding-left: 0;
+    padding-right: 0;
+  }
+
   // Card-style list — each row becomes a tinted, rounded surface that lives
   // on the actual `.mat-mdc-list-item`, not on a nested template `<div>`.
   // Apply this modifier as the host class on the list wrapper component so
@@ -178,12 +228,26 @@ $list-item-padded-min-height: 42px;
     }
   }
 
+  // Opts a list out of the default medium-rounded rows back to square (0). Custom properties inherit, so
+  // applying this on a `dbx-list` / `dbx-anchor-list` host (or any ancestor) squares selection and nav rows
+  // alike by zeroing both the `.dbx-list` (`--dbx-list-item-border-radius`) and `.dbx-anchor-list`
+  // (`--dbx-anchor-list-item-border-radius`) row tokens. The sidenav keeps its own token; the card-list
+  // (`.dbx-list-card-items-list`) item rule is more specific and keeps its own shape.
+  /// @dbx-utility list-square-items
+  /// @intent opts a `.dbx-list` / `.dbx-anchor-list` out of the default medium-rounded rows back to square (0 radius) by zeroing their row radius tokens
+  /// @role layout
+  /// @see-also dbx-list-card-items-list
+  .dbx-list-square-items {
+    --dbx-list-item-border-radius: 0;
+    --dbx-anchor-list-item-border-radius: 0;
+  }
+
   // When the tile is the leading icon in a two-line list item, override the
   // default `.item-icon` flat spacing with tile-appropriate margins. The
   // base `.dbx-icon-tile` rule lives in `_text.scss` next to its component.
   .dbx-list-two-line-item .item-icon.dbx-icon-tile {
-    padding: 8px;
-    margin: 0 12px 0 4px;
+    padding: var(--dbx-icon-tile-padding, 8px);
+    margin: 0 var(--dbx-padding-3) 0 0;
   }
 
   /// @dbx-utility list-two-line-item
@@ -250,6 +314,19 @@ $list-item-padded-min-height: 42px;
     padding: 0;
   }
 
+  // `.dbx-list` defaults to `height: 100%` so it fills a fixed-height scroll
+  // container. When a list instead flows inline with other content (e.g. card
+  // content rendered below it), that percentage resolves against the stretched
+  // ancestor and pushes the trailing content out of the card. This modifier
+  // lets the list size to its rows.
+  /// @dbx-utility list-auto-height
+  /// @intent size a `.dbx-list` to its rows instead of filling its container — apply on the list wrapper host when content flows below the list (the default `height: 100%` would push that content out of a stretched card)
+  /// @role layout
+  /// @see-also list-no-hover-effects, list-no-item-padding
+  .dbx-list-auto-height .dbx-list {
+    height: auto;
+  }
+
   // Zeros all padding on the underlying Material list item. Per-item utility
   // (apply as host class on the value-list view) for templates that supply
   // their own padding/leading element — e.g. a `.dbx-icon-tile` in a

package/lib/layout/section/_section.scss

@@ -7,7 +7,6 @@ $content-navbar-height: theming.$content-navbar-height;
 
 $page-h1-height: 32px;
 
-$header-bottom-margin: 16px;
 $header-left-reserved-space: 200px;
 $header-left-reserved-space-small-screen: 120px;
 
@@ -33,7 +32,7 @@ $header-left-reserved-space-small-screen: 120px;
       h5 {
         padding-top: 4px;
         padding-bottom: 1px;
-        min-height: $page-h1-height;
+        min-height: var(--dbx-section-header-title-height, #{$page-h1-height});
         display: inline-flex;
         align-items: center;
         margin: 0;
@@ -41,8 +40,8 @@ $header-left-reserved-space-small-screen: 120px;
 
         > .mat-icon {
           flex-shrink: 0;
-          padding-right: 2px;
-          padding-bottom: 2px;
+          padding-right: var(--dbx-padding-1);
+          padding-bottom: var(--dbx-padding-1);
         }
       }
 
@@ -58,7 +57,7 @@ $header-left-reserved-space-small-screen: 120px;
       h3,
       h4,
       h5 {
-        height: $page-h1-height;
+        height: var(--dbx-section-header-title-height, #{$page-h1-height});
       }
     }
   }
@@ -78,7 +77,7 @@ $header-left-reserved-space-small-screen: 120px;
   .dbx-section-hint,
   .dbx-section-hint-inline {
     margin: 0;
-    font-size: 16px;
+    font-size: var(--mat-sys-body-large-size);
   }
 
   // MARK: Page
@@ -106,7 +105,7 @@ $header-left-reserved-space-small-screen: 120px;
         max-width: 100%;
 
         .dbx-section-header-content-title {
-          max-width: calc(80% - #{$header-left-reserved-space});
+          max-width: calc(80% - var(--dbx-section-page-header-reserved-space, #{$header-left-reserved-space}));
           min-width: 48px;
           flex-shrink: 1;
 
@@ -227,7 +226,7 @@ $header-left-reserved-space-small-screen: 120px;
     > .dbx-section-header > .dbx-section-header-content {
       .dbx-section-header-content-title {
         @include theming.if-small-screen($theme-config) {
-          max-width: calc(80% - #{$header-left-reserved-space-small-screen});
+          max-width: calc(80% - var(--dbx-section-page-header-reserved-space-small-screen, #{$header-left-reserved-space-small-screen}));
         }
       }
     }

package/lib/layout/style/_style.scss

@@ -160,28 +160,48 @@
     @include define-dbx-color-class($color, map.get($colorConfig, 'color'), map.get($colorConfig, 'contrast'));
   }
 
+  /// @dbx-utility color-bg
+  /// @intent the painting utility — paints `background` (a `color-mix` of `--dbx-bg-color-current` with `--dbx-color-bg-tone`) plus the contrast `color` from `--dbx-color-current`. Pair with `[dbxColor]` (or a static `dbx-{color}-bg` token class) on the same element to supply those tokens. `[dbxColor]` itself never paints; this class (or a component's own `.dbx-color`-scoped SCSS) is what turns the tokens into a visible surface.
+  /// @role color
+  /// @see-also color-text, color-tonal
+  .dbx-color-bg {
+    @include dbx-color-bg-body();
+  }
+
   // tonal mode: use the vibrant theme color as text instead of the contrast color.
   // Applied via CSS class (not [style.color]) to avoid conflicting with [ngStyle] on buttons.
+  // Declared after `.dbx-color-bg` so the tonal `color:` wins the same-specificity
+  // cascade when both classes are present on the painted surface.
   /// @dbx-utility color-tonal
-  /// @intent paint text with the vibrant `--dbx-bg-color` (tonal mode) instead of the contrast color — pair with `[dbxColor]` + `[dbxColorTone]` for the muted background variant
+  /// @intent paint text with the vibrant `--dbx-bg-color` (tonal mode) instead of the contrast color — pair with `.dbx-color-bg` + `[dbxColor]` + `[dbxColorTone]` for the muted background variant
   /// @role state
+  /// @see-also color-bg
   .dbx-color-tonal {
     color: var(#{theming.$dbx-bg-color-var});
   }
 
-  /// @dbx-utility color-bg
-  /// @intent generic themed-background class — pair with `[dbxColor]="config"` to drive `--dbx-bg-color-current` / `--dbx-color-current` from arbitrary CSS color values
-  /// @role color
-  .dbx-color-bg {
-    @include dbx-color-bg-body();
-  }
-
   /// @dbx-utility color-text
   /// @intent generic themed-text class — pair with `[dbxTextColor]="config"` to drive `--dbx-color-current` from an arbitrary CSS color value
   /// @role color
   .dbx-color-text {
     color: #{theming.$dbx-color};
   }
+
+  /// @dbx-utility color-border
+  /// @intent subtle themed solid border derived from the current dbxColor text color (`--dbx-color-current`) — pair with `[dbxColor]`/`[dbxTextColor]` on the element or any ancestor (custom properties inherit); override `--dbx-color-border-tone` (percentage) for subtlety or `--dbx-color-border-width` for thickness
+  /// @role color
+  /// @see-also color-bg, color-text, color-tonal
+  .dbx-color-border {
+    border: var(--dbx-color-border-width, 1px) solid color-mix(in srgb, #{theming.$dbx-color} var(--dbx-color-border-tone, 25%), transparent);
+  }
+
+  /// @dbx-utility color-text-dim
+  /// @intent de-emphasized themed text — paints text with a partially-transparent mix of the current dbxColor text color (`--dbx-color-current`), for secondary lines (eyebrows, hints, labels) on painted surfaces where a fixed grey would clash; override `--dbx-color-text-dim-tone` (percentage) to tune the emphasis
+  /// @role color
+  /// @see-also color-text, color-border, hint
+  .dbx-color-text-dim {
+    color: color-mix(in srgb, #{theming.$dbx-color} var(--dbx-color-text-dim-tone, 72%), transparent);
+  }
 }
 
 @mixin dbx-color-bg-body($default-bg-tone: 100%) {
@@ -190,6 +210,19 @@
   color: #{theming.$dbx-color};
 }
 
+// Paints a colored surface from the inherited dbx color tokens
+// (`--dbx-bg-color-current` / `--dbx-color-current` / `--dbx-color-bg-tone`).
+// Unlike `dbx-color-bg-body`, the tone fallback lives inside the `var(...)`
+// rather than being declared as a property, so the surface does not leak an
+// inheritable `--dbx-color-bg-tone` to nested elements. Scope this on a
+// `.dbx-color` marker (the model is `mat-card.dbx-color` in `_card.scss`) so
+// only hosts directly marked with `[dbxColor]` repaint — token inheritance
+// alone never triggers a repaint.
+@mixin dbx-color-surface($default-bg-tone: 100%) {
+  background: color-mix(in srgb, #{theming.$dbx-bg-color} var(#{theming.$dbx-bg-tone-var}, #{$default-bg-tone}), transparent);
+  color: #{theming.$dbx-color};
+}
+
 @mixin define-dbx-color-class($name, $color, $contrast, $swap-bg: false) {
   .dbx-#{$name} {
     #{theming.$dbx-color-var}: #{$color};
@@ -199,10 +232,12 @@
   $bg-color: if($swap-bg, $contrast, $color);
   $bg-text: if($swap-bg, $color, $contrast);
 
+  // Token-only: a `-bg` class declares the color tokens but paints nothing.
+  // Painting happens via the `.dbx-color-bg` utility or a component's own
+  // `.dbx-color`-scoped SCSS reading these tokens.
   .dbx-#{$name}-bg {
     #{theming.$dbx-color-var}: #{$bg-text};
     #{theming.$dbx-bg-color-var}: #{$bg-color};
-    @include dbx-color-bg-body();
   }
 }