layout-style-css 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to `layout-style-css` are documented here. This project follows semantic versioning.
 
+## [3.1.0] - 2026-08-25
+
+### Added
+
+- Added compact, normal, and spacious density contexts that can be applied at the root or to a nested layout subtree.
+- Added the `96rem` workspace Wrapper, all ten local gap utilities, explicit bounded and viewport-relative Scroll modifiers, and recipe-owned threshold metadata.
+
+### Changed
+
+- Made normal section spacing more conservative while retaining the former marketing rhythm through spacious density.
+- Made gap utilities local to the element carrying the class and made base Scroll rely on its containing layout for height constraints.
+
+### Migration
+
+- Use spacious density for the former section rhythm, explicit inherited gap tokens for a shared spacing context, and `ly-scroll--viewport` for the former viewport-relative Scroll behavior.
+
+### Tests
+
+- Added density, workspace utilization, nested-gap isolation, Scroll-mode, public-token liveness, threshold metadata, cross-height, generated-output, package, and Pages contracts.
+
+## [3.0.2] - 2026-08-25
+
+### Fixed
+
+- Matched App Shell row tracks to base, medium, wide, and personality-specific area topologies so primary content receives flexible height while headers and footers remain intrinsic.
+- Separated compact section spacing from normal section spacing and preserved the compact-smaller-than-normal invariant across regular, short, and shallow viewport heights.
+- Connected the documented page-padding and Wrapper-gutter tokens to rendered Wrapper padding while retaining safe-area handling.
+
+### Tests
+
+- Added static and rendered regression coverage for App Shell row counts, flexible workspace allocation, compact section ordering, public gutter overrides, generated CSS parity, package metadata, and Pages artifacts.
+
 ## [3.0.1] - 2026-08-09
 
 ### Changed

package/README.md

@@ -2,7 +2,7 @@
 
 Zero-configuration, dependency-free structural CSS that responds to the width and height a layout actually receives.
 
-`layout-style-css@3.0.1` is the current v3 patch release and preserves the clean-break structural contract introduced in 3.0.0. It provides intrinsic wrappers, composition primitives, seven semantic recipes, and sixteen spatial personalities. Layout owns structure; UI Style Kit owns paint; Interactive Surface owns interaction styling.
+`layout-style-css@3.1.0` is the current additive v3 release. It provides intrinsic wrappers, composition primitives, seven semantic recipes, explicit local density controls, and sixteen spatial personalities. Layout owns structure; UI Style Kit owns paint; Interactive Surface owns interaction styling.
 
 ## Requirements
 
@@ -13,7 +13,7 @@ Zero-configuration, dependency-free structural CSS that responds to the width an
 ## Install
 
 ```bash
-npm install layout-style-css@3.0.1
+npm install layout-style-css@3.1.0
 ```
 
 Most applications need one import:
@@ -44,6 +44,17 @@ Use `.ly-root` as the responsive boundary and keep the mobile DOM order authorit
 
 `.ly-root`, wrappers, and recipe roots establish the named `ly-scope` inline-size container. A recipe works directly in the root; when it is nested in a wrapper, it responds to that nearest wrapper.
 
+## Density Contexts
+
+Normal density is the zero-configuration default. Use `data-ly-density="compact"`, `data-ly-density="normal"`, or `data-ly-density="spacious"` on `.ly-root` or any nested layout subtree. A nested density explicitly resets inherited gaps and section rhythm, so task controls can remain compact inside a spacious marketing page.
+
+```html
+<main class="ly-root" data-ly-density="normal">
+  <section data-ly-density="compact">Dense application controls</section>
+  <section data-ly-density="spacious">Campaign presentation</section>
+</main>
+```
+
 ## Wrappers
 
 Wrappers are optional measure and nesting controls. Every wrapper uses logical properties, fluid container-relative gutters, safe-area compensation, and shrink-safe sizing.
@@ -54,6 +65,7 @@ Wrappers are optional measure and nesting controls. Every wrapper uses logical p
 | `.ly-wrapper--compact` | `40rem` compact measure |
 | `.ly-wrapper--prose` | `68ch` reading measure |
 | `.ly-wrapper--content` | `72rem` content measure |
+| `.ly-wrapper--workspace` | `96rem` task-oriented application measure |
 | `.ly-wrapper--wide` | `112rem` wide measure |
 | `.ly-wrapper--full` | Full available inline size |
 | `.ly-wrapper--breakout` | Clamped content, feature, and full lanes |
@@ -68,6 +80,8 @@ Wrappers are optional measure and nesting controls. Every wrapper uses logical p
 
 All lanes clamp to the available inline size, including allocations from 320px through ultrawide screens.
 
+`--ly-page-padding-inline` supplies the default `--ly-wrapper-gutter` value. Override `--ly-wrapper-gutter` on `.ly-root` or a narrower scope to control rendered Wrapper padding; safe-area compensation is still applied once at the Wrapper edge.
+
 ## Composition Primitives
 
 The core includes:
@@ -77,7 +91,9 @@ The core includes:
 - `.ly-panes` and `.ly-media`
 - `.ly-reel`, `.ly-frame`, and `.ly-scroll`
 
-Grid and flex primitives wrap intrinsically whenever track wrapping can replace a query. Page, cover, and bounded-scroll sizing use `vh` fallbacks followed by `100dvh`-aware behavior. Only `.ly-reel` deliberately scrolls horizontally; only `.ly-scroll` deliberately creates a bounded vertical scroll region.
+Grid and flex primitives wrap intrinsically whenever track wrapping can replace a query. Base `.ly-scroll` owns overflow but no height cap. Add `.ly-scroll--bounded` for the stable `--ly-scroll-max` cap or `.ly-scroll--viewport` for height-aware `--ly-scroll-viewport-max` behavior. Only `.ly-reel` deliberately scrolls horizontally; only the Scroll family deliberately creates vertical scrolling.
+
+Gap utilities `.ly-gap-0` through `.ly-gap-9` assign `gap` only on the element carrying the class. They do not alter inherited primitive gap variables. Override `--ly-gap`, `--ly-grid-gap`, `--ly-stack-gap`, or `--ly-cluster-gap` when a shared spacing context is intentional.
 
 ## Automatic Recipe Engine
 
@@ -93,6 +109,10 @@ Recipes use attributes only. The stacked semantic source order is always safe, a
 | `data-ly-recipe="gallery"` | Intrinsic tracks; no topology breakpoint |
 | `data-ly-recipe="card-grid"` | Intrinsic tracks; no topology breakpoint |
 
+The same ownership is available in `manifest.json` through `thresholds.recipes`, alongside the generic container-width and viewport-height arrays. Release checks verify every mapping against authored queries and require every public geometry token to reach a runtime CSS declaration.
+
+App Shell base, medium, and wide topologies own matching row definitions. This keeps the primary workspace flexible while header and footer tracks remain intrinsic, including personality-specific four-row topologies.
+
 Canonical regions use `data-ly-area`, including `header`, `sidebar`, `nav`, `main`, `aside`, `footer`, `content`, `media`, `actions`, `primary`, and `secondary`.
 
 Recipe class aliases such as `.ly-dashboard` no longer exist. Use:
@@ -129,6 +149,8 @@ The system responds to available block size without orientation queries:
 - At viewport heights of `30rem` or less, recipe-owned sticky behavior becomes normal flow, and cover/shell minimums stop forcing full-height regions.
 - Safe-area block insets remain available, and required regions are never hidden solely because the viewport is short.
 
+`--ly-section-padding-block` controls normal sections. `--ly-section-padding-block-compact` independently controls `.ly-section--compact`, preserving a smaller rhythm through the regular, short, and shallow height tiers.
+
 Use the public height, gap, measure, ratio, rail, media, card, and grid-minimum custom properties for advanced tuning. Defaults use `100vh` fallbacks followed by `100dvh`.
 
 ## Personalities
@@ -156,7 +178,7 @@ Each personality is a token/topology profile consumed by the shared recipe engin
 | `layout-style-css/personalities.json` | Public layout-to-visual pairing recommendations |
 | `layout-style-css/package.json` | Package metadata |
 
-The cascade order is `ly.reset`, `ly.tokens`, `ly.wrappers`, `ly.primitives`, `ly.recipes`, `ly.utilities`, and `ly.personalities`.
+The cascade order is `ly.reset`, `ly.tokens`, `ly.wrappers`, `ly.primitives`, `ly.recipes`, `ly.utilities`, `ly.personalities`, and `ly.context`. Unlayered application CSS remains stronger than every library layer.
 
 ## Ecosystem Imports
 
@@ -171,18 +193,18 @@ import "layout-style-css";
 
 This order lets UI Style Kit establish paint and theme roles, Interactive Surface add interaction states, and Layout apply structure.
 
-`data-ly-layout`, `data-ui`, `data-theme`, and `data-mode` are independently selectable. See [Layout Styles](docs/wiki/Layout-Styles.md#visual-pairing-guidance) for the full recommendation matrix; pairings are never dependencies.
+`data-ly-layout`, `data-ly-density`, `data-ui`, `data-theme`, and `data-mode` are independently selectable. See [Layout Styles](docs/wiki/Layout-Styles.md#visual-pairing-guidance) for the full recommendation matrix; pairings are never dependencies.
 
 ## CDN
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/layout-style-css@3.0.1/dist/layout-style-css.min.css">
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/layout-style-css@3.0.1/dist/layout-style-css.min.css">
+<link rel="stylesheet" href="https://unpkg.com/layout-style-css@3.1.0/dist/layout-style-css.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/layout-style-css@3.1.0/dist/layout-style-css.min.css">
 ```
 
 ## Clean-Break Migration
 
-v3 has no compatibility bundle. It removes `legacy.css`, the deprecated UI Style Kit structural bridge, v1/v2 aliases, responsive `ly-md-*` and `ly-lg-*` utilities, and all visual-order utilities. See [Migrating To 3.0](docs/wiki/Migrating-To-3.0.md) for exact mappings.
+v3 has no compatibility bundle. It removes `legacy.css`, the deprecated UI Style Kit structural bridge, v1/v2 aliases, responsive `ly-md-*` and `ly-lg-*` utilities, and all visual-order utilities. See [Migrating To 3.0](docs/wiki/Migrating-To-3.0.md) for the major-version mappings and [Migrating To 3.1](docs/wiki/Migrating-To-3.1.md) for density, local gap, and Scroll behavior changes.
 
 ## Demo And Verification
 
@@ -208,6 +230,7 @@ npm run release:verify
 - [Layout Recipes](docs/wiki/Layout-Recipes.md)
 - [Layout Styles](docs/wiki/Layout-Styles.md)
 - [Migrating To 3.0](docs/wiki/Migrating-To-3.0.md)
+- [Migrating To 3.1](docs/wiki/Migrating-To-3.1.md)
 - [Demo And GitHub Pages](docs/wiki/Demo-And-GitHub-Pages.md)
 - [Release And Publishing](docs/wiki/Release-And-Publishing.md)
 - [Security And Support](docs/wiki/Security-And-Support.md)

package/dist/core.css

@@ -1,4 +1,4 @@
-@layer ly.reset, ly.tokens, ly.wrappers, ly.primitives, ly.recipes, ly.utilities, ly.personalities;
+@layer ly.reset, ly.tokens, ly.wrappers, ly.primitives, ly.recipes, ly.utilities, ly.personalities, ly.context;
 
 @import url("./foundation.css");
 @import url("./wrappers.css");

package/dist/foundation.css

@@ -1,4 +1,4 @@
-@layer ly.reset, ly.tokens, ly.wrappers, ly.primitives, ly.recipes, ly.utilities, ly.personalities;
+@layer ly.reset, ly.tokens, ly.wrappers, ly.primitives, ly.recipes, ly.utilities, ly.personalities, ly.context;
 
 /*
   Foundation owns only shared spatial tokens, containment, and defensive
@@ -21,27 +21,30 @@
     --ly-wrapper-compact: 40rem;
     --ly-wrapper-prose: 68ch;
     --ly-wrapper-content: 72rem;
+    --ly-wrapper-workspace: 96rem;
     --ly-wrapper-wide: 112rem;
-    --ly-page-padding-inline: clamp(1rem, 4vw, 3rem);
+    --ly-page-padding-inline: clamp(1rem, 3vw, 3rem);
     --ly-safe-area-inline: max(
       env(safe-area-inset-left, 0px),
       env(safe-area-inset-right, 0px)
     );
     --ly-safe-area-block-start: env(safe-area-inset-top, 0px);
     --ly-safe-area-block-end: env(safe-area-inset-bottom, 0px);
-    --ly-wrapper-gutter: max(var(--ly-page-padding-inline), var(--ly-safe-area-inline));
+    --ly-wrapper-gutter: var(--ly-page-padding-inline);
 
     --ly-profile-gap: var(--ly-space-5);
     --ly-gap: var(--ly-profile-gap);
     --ly-grid-gap: var(--ly-gap);
     --ly-stack-gap: var(--ly-space-4);
     --ly-cluster-gap: var(--ly-space-3);
-    --ly-section-padding-block: clamp(3rem, 7vh, 6rem);
+    --ly-section-padding-block: clamp(2rem, 4vh, 4rem);
+    --ly-section-padding-block-compact: clamp(1rem, 2.5vh, 2rem);
     --ly-header-height: 4.5rem;
     --ly-sticky-position: sticky;
     --ly-cover-min: 100vh;
     --ly-shell-min: 100vh;
-    --ly-scroll-max: min(70vh, 50rem);
+    --ly-scroll-max: 50rem;
+    --ly-scroll-viewport-max: min(70vh, 50rem);
 
     --ly-switcher-threshold: 42rem;
     --ly-sidebar-size: 18rem;
@@ -64,11 +67,13 @@
     --ly-gallery-min: 12rem;
     --ly-card-grid-min: 16rem;
 
+    --ly-app-shell-base-rows: auto auto minmax(0, 1fr) auto auto;
     --ly-app-shell-medium-areas:
       "header header"
       "sidebar main"
       "aside main"
       "footer footer";
+    --ly-app-shell-medium-rows: auto auto minmax(0, 1fr) auto;
     --ly-app-shell-medium-columns:
       minmax(min(100%, var(--ly-recipe-rail)), auto)
       minmax(0, 1fr);
@@ -76,6 +81,7 @@
       "sidebar header header"
       "sidebar main aside"
       "sidebar footer footer";
+    --ly-app-shell-wide-rows: auto minmax(0, 1fr) auto;
     --ly-app-shell-wide-columns:
       minmax(min(100%, var(--ly-recipe-rail)), auto)
       minmax(0, 1fr)
@@ -125,12 +131,19 @@
     min-block-size: 0;
   }
 
+  /* Prefer the nearest layout scope for gutters when container units parse. */
+  @supports (width: 1cqi) {
+    :where(.ly-root) {
+      --ly-page-padding-inline: clamp(1rem, 3cqi, 3rem);
+    }
+  }
+
   /* Enhance viewport-bound tokens only when dynamic viewport units parse. */
   @supports (height: 100dvh) {
     :where(.ly-root) {
       --ly-cover-min: 100dvh;
       --ly-shell-min: 100dvh;
-      --ly-scroll-max: min(70dvh, 50rem);
+      --ly-scroll-viewport-max: min(70dvh, 50rem);
     }
   }
 }
@@ -161,17 +174,19 @@
       --ly-grid-gap: var(--ly-gap);
       --ly-stack-gap: min(var(--ly-space-4), 3vh);
       --ly-cluster-gap: min(var(--ly-space-3), 2vh);
-      --ly-section-padding-block: clamp(1.5rem, 6vh, 3rem);
+      --ly-section-padding-block: clamp(1.25rem, 4vh, 2rem);
+      --ly-section-padding-block-compact: clamp(0.75rem, 2vh, 1.25rem);
       --ly-header-height: 3.5rem;
-      --ly-scroll-max: min(62vh, 34rem);
+      --ly-scroll-viewport-max: min(62vh, 34rem);
     }
 
     @supports (height: 100dvh) {
       :where(.ly-root) {
         --ly-stack-gap: min(var(--ly-space-4), 3dvh);
         --ly-cluster-gap: min(var(--ly-space-3), 2dvh);
-        --ly-section-padding-block: clamp(1.5rem, 6dvh, 3rem);
-        --ly-scroll-max: min(62dvh, 34rem);
+        --ly-section-padding-block: clamp(1.25rem, 4dvh, 2rem);
+        --ly-section-padding-block-compact: clamp(0.75rem, 2dvh, 1.25rem);
+        --ly-scroll-viewport-max: min(62dvh, 34rem);
       }
     }
   }
@@ -181,14 +196,154 @@
       --ly-cover-min: auto;
       --ly-shell-min: auto;
       --ly-sticky-position: static;
-      --ly-section-padding-block: var(--ly-space-5);
-      --ly-scroll-max: max(12rem, calc(100vh - 8rem));
+      --ly-section-padding-block: var(--ly-space-4);
+      --ly-section-padding-block-compact: var(--ly-space-2);
+      --ly-scroll-viewport-max: max(12rem, calc(100vh - 8rem));
     }
 
     @supports (height: 100dvh) {
       :where(.ly-root) {
-        --ly-scroll-max: max(12rem, calc(100dvh - 8rem));
+        --ly-scroll-viewport-max: max(12rem, calc(100dvh - 8rem));
+      }
+    }
+  }
+}
+
+@layer ly.context {
+  :where(
+    .ly-root[data-ly-density="compact"],
+    .ly-root [data-ly-density="compact"]
+  ) {
+    --ly-gap: var(--ly-space-3);
+    --ly-grid-gap: var(--ly-space-3);
+    --ly-stack-gap: var(--ly-space-3);
+    --ly-cluster-gap: var(--ly-space-2);
+    --ly-section-padding-block: clamp(1rem, 2.5vh, 2rem);
+    --ly-section-padding-block-compact: clamp(0.5rem, 1.5vh, 1rem);
+  }
+
+  :where(
+    .ly-root[data-ly-density="normal"],
+    .ly-root [data-ly-density="normal"]
+  ) {
+    --ly-gap: var(--ly-profile-gap);
+    --ly-grid-gap: var(--ly-gap);
+    --ly-stack-gap: var(--ly-space-4);
+    --ly-cluster-gap: var(--ly-space-3);
+    --ly-section-padding-block: clamp(2rem, 4vh, 4rem);
+    --ly-section-padding-block-compact: clamp(1rem, 2.5vh, 2rem);
+  }
+
+  :where(
+    .ly-root[data-ly-density="spacious"],
+    .ly-root [data-ly-density="spacious"]
+  ) {
+    --ly-gap: max(var(--ly-profile-gap), var(--ly-space-6));
+    --ly-grid-gap: var(--ly-gap);
+    --ly-stack-gap: var(--ly-space-5);
+    --ly-cluster-gap: var(--ly-space-4);
+    --ly-section-padding-block: clamp(3rem, 7vh, 6rem);
+    --ly-section-padding-block-compact: clamp(1.5rem, 3.5vh, 3rem);
+  }
+
+  @media (max-height: 44rem) {
+    :where(
+      .ly-root[data-ly-density="compact"],
+      .ly-root [data-ly-density="compact"]
+    ) {
+      --ly-gap: var(--ly-space-3);
+      --ly-grid-gap: var(--ly-space-3);
+      --ly-stack-gap: var(--ly-space-3);
+      --ly-cluster-gap: var(--ly-space-2);
+      --ly-section-padding-block: clamp(0.75rem, 2vh, 1.25rem);
+      --ly-section-padding-block-compact: var(--ly-space-2);
+    }
+
+    :where(
+      .ly-root[data-ly-density="normal"],
+      .ly-root [data-ly-density="normal"]
+    ) {
+      --ly-gap: min(var(--ly-profile-gap), var(--ly-space-4));
+      --ly-grid-gap: var(--ly-gap);
+      --ly-stack-gap: var(--ly-space-4);
+      --ly-cluster-gap: var(--ly-space-3);
+      --ly-section-padding-block: clamp(1.25rem, 4vh, 2rem);
+      --ly-section-padding-block-compact: clamp(0.75rem, 2vh, 1.25rem);
+    }
+
+    :where(
+      .ly-root[data-ly-density="spacious"],
+      .ly-root [data-ly-density="spacious"]
+    ) {
+      --ly-gap: var(--ly-space-5);
+      --ly-grid-gap: var(--ly-space-5);
+      --ly-stack-gap: var(--ly-space-4);
+      --ly-cluster-gap: var(--ly-space-3);
+      --ly-section-padding-block: clamp(1.5rem, 6vh, 3rem);
+      --ly-section-padding-block-compact: clamp(0.75rem, 3vh, 1.25rem);
+    }
+
+    @supports (height: 100dvh) {
+      :where(
+        .ly-root[data-ly-density="compact"],
+        .ly-root [data-ly-density="compact"]
+      ) {
+        --ly-section-padding-block: clamp(0.75rem, 2dvh, 1.25rem);
+      }
+
+      :where(
+        .ly-root[data-ly-density="normal"],
+        .ly-root [data-ly-density="normal"]
+      ) {
+        --ly-section-padding-block: clamp(1.25rem, 4dvh, 2rem);
+        --ly-section-padding-block-compact: clamp(0.75rem, 2dvh, 1.25rem);
       }
+
+      :where(
+        .ly-root[data-ly-density="spacious"],
+        .ly-root [data-ly-density="spacious"]
+      ) {
+        --ly-section-padding-block: clamp(1.5rem, 6dvh, 3rem);
+        --ly-section-padding-block-compact: clamp(0.75rem, 3dvh, 1.25rem);
+      }
+    }
+  }
+
+  @media (max-height: 30rem) {
+    :where(
+      .ly-root[data-ly-density="compact"],
+      .ly-root [data-ly-density="compact"]
+    ) {
+      --ly-gap: var(--ly-space-2);
+      --ly-grid-gap: var(--ly-space-2);
+      --ly-stack-gap: var(--ly-space-2);
+      --ly-cluster-gap: var(--ly-space-1);
+      --ly-section-padding-block: var(--ly-space-3);
+      --ly-section-padding-block-compact: var(--ly-space-2);
+    }
+
+    :where(
+      .ly-root[data-ly-density="normal"],
+      .ly-root [data-ly-density="normal"]
+    ) {
+      --ly-gap: var(--ly-space-3);
+      --ly-grid-gap: var(--ly-space-3);
+      --ly-stack-gap: var(--ly-space-3);
+      --ly-cluster-gap: var(--ly-space-2);
+      --ly-section-padding-block: var(--ly-space-4);
+      --ly-section-padding-block-compact: var(--ly-space-2);
+    }
+
+    :where(
+      .ly-root[data-ly-density="spacious"],
+      .ly-root [data-ly-density="spacious"]
+    ) {
+      --ly-gap: var(--ly-space-4);
+      --ly-grid-gap: var(--ly-space-4);
+      --ly-stack-gap: var(--ly-space-4);
+      --ly-cluster-gap: var(--ly-space-3);
+      --ly-section-padding-block: var(--ly-space-5);
+      --ly-section-padding-block-compact: var(--ly-space-3);
     }
   }
 }