layout-style-css 2.1.1 → 3.0.1

package/dist/wrappers.css

@@ -1,127 +1,45 @@
-@layer ly.reset, ly.tokens, ly.wrappers, ly.primitives, ly.recipes, ly.utilities, ly.personalities, ly.integrations, ly.legacy;
+@layer ly.reset, ly.tokens, ly.wrappers, ly.primitives, ly.recipes, ly.utilities, ly.personalities;
 
-/*
-  Shared structural tokens and wrapper geometry. Theme, type, borders, shadows,
-  and interactive states remain outside Layout Style's ownership boundary.
-*/
-
-@layer ly.tokens {
-  :where(.ly-root) {
-    --ly-space-0: 0;
-    --ly-space-1: 0.25rem;
-    --ly-space-2: 0.5rem;
-    --ly-space-3: 0.75rem;
-    --ly-space-4: 1rem;
-    --ly-space-5: 1.5rem;
-    --ly-space-6: 2rem;
-    --ly-space-7: 3rem;
-    --ly-space-8: 4rem;
-    --ly-space-9: 6rem;
-
-    --ly-wrapper-compact: 40rem;
-    --ly-wrapper-prose: 68ch;
-    --ly-wrapper-content: 72rem;
-    --ly-wrapper-wide: 112rem;
-    --ly-wrapper-max: var(--ly-wrapper-content);
-    --ly-page-padding-inline: clamp(1rem, 4vw, 3rem);
-    --ly-safe-area-inline: max(
-      env(safe-area-inset-left, 0px),
-      env(safe-area-inset-right, 0px)
-    );
-    --ly-wrapper-gutter: max(var(--ly-page-padding-inline), var(--ly-safe-area-inline));
-
-    --ly-section-padding-block: clamp(3rem, 7vw, 6rem);
-    --ly-gap: var(--ly-space-5);
-    --ly-grid-gap: var(--ly-gap);
-    --ly-stack-gap: var(--ly-space-4);
-    --ly-cluster-gap: var(--ly-space-3);
-    --ly-cover-min: 100svh;
-    --ly-switcher-threshold: 42rem;
-    --ly-sidebar-size: 18rem;
-    --ly-sidebar-content-min: 50%;
-    --ly-grid-columns: 12;
-    --ly-grid-min: 16rem;
-    --ly-pane-size: 22rem;
-    --ly-media-size: 14rem;
-    --ly-reel-item-min: 16rem;
-    --ly-reel-item-max: 28rem;
-    --ly-scroll-max: 70svh;
-    --ly-frame-ratio: 16 / 9;
-
-    --ly-recipe-rail: 18rem;
-    --ly-recipe-aside: 22rem;
-    --ly-card-grid-min: 16rem;
-    --ly-gallery-min: 12rem;
-    --ly-card-size-sm: 10rem;
-    --ly-card-size-md: 14rem;
-    --ly-card-size-lg: 18rem;
-    --ly-header-height: 4.5rem;
-    --ly-z-header: 20;
-
-    /* V1 token aliases remain available so legacy selectors can preserve sizing. */
-    --ly-container-sm: var(--ly-wrapper-compact);
-    --ly-container-md: 56rem;
-    --ly-container-lg: var(--ly-wrapper-content);
-    --ly-container-xl: 88rem;
-    --ly-container-wide: var(--ly-wrapper-wide);
-    --ly-container-max: var(--ly-container-lg);
-    --ly-content-readable: var(--ly-wrapper-prose);
-    --ly-carousel-item-min: var(--ly-reel-item-min);
-    --ly-carousel-item-max: var(--ly-reel-item-max);
-    --ly-sidebar-min: 14rem;
-    --ly-sidebar-width: var(--ly-recipe-rail);
-    --ly-sidebar-max: var(--ly-recipe-aside);
-    --ly-pane-fixed: var(--ly-pane-size);
-    --ly-z-sidebar: 10;
-  }
-}
-
-@layer ly.reset {
-  :where(.ly-root),
-  :where(.ly-root *) {
-    box-sizing: border-box;
-  }
-
-  :where(.ly-root) {
-    min-inline-size: 0;
-    margin: 0;
-  }
-
-  :where(.ly-root img),
-  :where(.ly-root svg),
-  :where(.ly-root video),
-  :where(.ly-root canvas) {
-    max-inline-size: 100%;
-  }
-}
+/* Wrappers provide fluid measures and become the nearest responsive scope. */
 
 @layer ly.wrappers {
   .ly-wrapper {
-    /* Personalities provide only the plain-wrapper default; explicit variants stay authoritative. */
     --ly-wrapper-max: var(--ly-personality-wrapper-max, var(--ly-wrapper-content));
+    --ly-wrapper-fluid-gutter: clamp(1rem, 3vw, 3rem);
+    --ly-wrapper-local-gutter: max(
+      var(--ly-wrapper-fluid-gutter),
+      var(--ly-safe-area-inline)
+    );
 
-    /* Symmetric safe-area compensation keeps logical gutters stable in either direction. */
-    container-name: ly-wrapper;
+    container-name: ly-scope;
     container-type: inline-size;
-    inline-size: min(100%, calc(var(--ly-wrapper-max) + (var(--ly-wrapper-gutter) * 2)));
+    inline-size: min(100%, calc(var(--ly-wrapper-max) + (var(--ly-wrapper-local-gutter) * 2)));
+    max-inline-size: 100%;
     margin-inline: auto;
-    padding-inline: var(--ly-wrapper-gutter);
+    padding-inline: var(--ly-wrapper-local-gutter);
+  }
+
+  /* Container-relative gutters enhance the universally valid viewport fallback. */
+  @supports (width: 1cqi) {
+    .ly-wrapper {
+      --ly-wrapper-fluid-gutter: clamp(1rem, 3cqi, 3rem);
+    }
   }
 
   .ly-wrapper--compact {
-    --ly-wrapper-max: 40rem;
+    --ly-wrapper-max: var(--ly-wrapper-compact);
   }
 
   .ly-wrapper--prose {
-    --ly-wrapper-max: 68ch;
+    --ly-wrapper-max: var(--ly-wrapper-prose);
   }
 
   .ly-wrapper--content {
-    --ly-wrapper-max: 72rem;
+    --ly-wrapper-max: var(--ly-wrapper-content);
   }
 
   .ly-wrapper--wide {
-    --ly-wrapper-max: 112rem;
+    --ly-wrapper-max: var(--ly-wrapper-wide);
   }
 
   .ly-wrapper--full {
@@ -129,18 +47,19 @@
   }
 
   .ly-wrapper--breakout {
+    --ly-wrapper-max: 100%;
     --ly-breakout-content-size: min(
       var(--ly-wrapper-content),
-      calc(100% - (var(--ly-wrapper-gutter) * 2))
+      calc(100% - (var(--ly-wrapper-local-gutter) * 2))
     );
     --ly-breakout-feature-size: min(
       var(--ly-wrapper-wide),
-      calc(100% - (var(--ly-wrapper-gutter) * 2))
+      calc(100% - (var(--ly-wrapper-local-gutter) * 2))
     );
 
     display: grid;
     grid-template-columns:
-      [full-start] minmax(min(100%, var(--ly-wrapper-gutter)), 1fr)
+      [full-start] minmax(min(100%, var(--ly-wrapper-local-gutter)), 1fr)
       [feature-start] minmax(
         0,
         calc((var(--ly-breakout-feature-size) - var(--ly-breakout-content-size)) / 2)
@@ -150,7 +69,7 @@
         0,
         calc((var(--ly-breakout-feature-size) - var(--ly-breakout-content-size)) / 2)
       )
-      [feature-end] minmax(min(100%, var(--ly-wrapper-gutter)), 1fr) [full-end];
+      [feature-end] minmax(min(100%, var(--ly-wrapper-local-gutter)), 1fr) [full-end];
     inline-size: 100%;
     padding-inline: 0;
   }
@@ -158,6 +77,7 @@
   .ly-wrapper--breakout > * {
     grid-column: content;
     min-inline-size: 0;
+    max-inline-size: 100%;
   }
 
   .ly-wrapper--breakout > :where(.ly-lane--content, [data-ly-lane="content"]) {

package/docs/wiki/Contributing.md

@@ -27,7 +27,9 @@ Use `npm run test:demo:all` for rendered layout changes and `npm run release:ver
 - Prefix public classes with `ly-`.
 - Keep the mobile DOM, reading, and focus order authoritative.
 - Use named areas in built-in recipes; never use `order` there.
-- Test nested containers below and above `48rem` and `64rem`.
+- Test nested containers one rem below and above each recipe threshold: `42rem`, `44rem`, `48rem`, `52rem`, and `72rem`.
+- Test viewport heights one rem below and above `30rem` and `44rem`.
+- Keep personality files free of `@container`, viewport, and orientation queries.
 - Use `minmax(0, 1fr)` or guarded floors for tracks that receive application content.
 - Do not add colors, typography, borders, shadows, component paint, focus styles, or native control styles.
 

package/docs/wiki/Demo-And-GitHub-Pages.md

@@ -1,53 +1,44 @@
 # Demo And GitHub Pages
 
-The interactive layout lab lives in `demo/index.html`, `demo/demo.css`, and `demo/demo.js`. GitHub Pages serves a generated artifact from `output/github-pages/`.
+The v3 demo is an intrinsic responsive workbench, not a fixed-device screenshot gallery.
 
-## Local Gates
+## Controls
 
-The quick gate uses Chromium and a representative rendered matrix:
+- Independent preview width and height
+- Automatic and manual recipe responsiveness
+- Wrapper, recipe, and all sixteen personality profiles
+- Layout-only, Layout plus UI, and all-three ecosystem modes
+- Live rendered dimensions and active topology
+- Copy-ready canonical attribute markup
 
-```bash
-npm run test:demo:quick
-```
+Device presets cover the release allocations:
 
-Run one complete engine matrix:
+- Phone portrait: `360 × 800`
+- Phone landscape: `800 × 360`
+- Tablet portrait: `768 × 1024`
+- Tablet landscape: `1024 × 768`
+- Desktop landscape: `1440 × 900`
+- Desktop portrait: `900 × 1440`
 
-```bash
-npm run test:demo:chromium
-npm run test:demo:firefox
-npm run test:demo:webkit
-```
+Threshold controls also cover one rem below and above `42rem`, `44rem`, `48rem`, `52rem`, and `72rem`, plus the `30rem` and `44rem` height tiers.
 
-Run all supported engines:
+## Local Verification
 
 ```bash
+npm run build
+npm run test:demo:quick
 npm run test:demo:all
 ```
 
-The full matrix exercises current evergreen Chromium, Firefox, and WebKit at 375px, 768px, 1280px, and 1440px, plus nested containers around the `48rem` and `64rem` core thresholds and the personality-specific signatures.
-
-## Rendered Contracts
-
-The smoke suite verifies:
-
-- all wrappers, recipes, and personalities
-- stable DOM and keyboard focus order
-- named-area transitions at both container thresholds
-- no meaningful horizontal overflow
-- bounded scrolling
-- accessible mobile controls
-- layout-only, Layout plus UI, and all-three ecosystem modes
-- pinned `ui-style-kit-css@2.1.0` visual, token bridge, and manifest behavior plus released `interactive-surface-css@1.5.0`
-
-The demo query parser uses explicit allowlists and writes generated imports and markup with `textContent`.
+The full matrix runs in Chromium, Firefox, and WebKit. It checks meaningful DOM, unchanged source/focus order, automatic and manual topologies, nearest-container behavior, short-height escape hatches, zero-width tracks, overlap, and unintended overflow.
 
-## Pages Artifact
+## GitHub Pages
 
 ```bash
 npm run pages:build
-node test/pages-artifact.test.mjs
+npm run test:pages
 ```
 
-The generated root contains the demo, metadata assets, `.nojekyll`, and `dist/`. The build rewrites only known parent-relative Layout Style paths, preserving external companion URLs and canonical metadata.
+The Pages artifact is written to `output/github-pages`, carries a root `index.html`, includes the generated v3 distribution, and rewrites the demo's parent-relative Layout import to the artifact-local `./dist` path.
 
-The Pages workflow installs Chromium, runs the quick package gate, builds and tests the artifact, then uploads it. Repository Pages must be enabled with GitHub Actions as the source before deployment.
+`pages.yml` verifies repository Pages configuration before package work, runs the package check, installs Chromium for the rendered gate, validates the artifact, and deploys the saved artifact. Deployment is separate from local implementation.

package/docs/wiki/Getting-Started.md

@@ -1,51 +1,63 @@
 # Getting Started
 
-Layout Style CSS 2.0 provides structural layout without prescribing theme or component paint.
-
-## Install
-
-Node.js 20 or newer is required for development scripts.
+Install `layout-style-css@3.0.1` and import the root bundle:
 
 ```bash
-npm install layout-style-css@2.1.1
+npm install layout-style-css@3.0.1
 ```
 
-## Import
-
 ```js
 import "layout-style-css";
 ```
 
-The package is dependency-free. Optional UI and interaction layers are installed and imported explicitly; see [Installation And CDN](Installation-And-CDN.md).
-
-## First Recipe
+## First Automatic Layout
 
-Place the recipe inside a `.ly-wrapper`. The wrapper supplies inline-size containment, fluid logical gutters, and safe-area compensation.
+The zero-configuration path needs only `.ly-root`, a recipe attribute, and semantic areas:
 
 ```html
 <body class="ly-root" data-ly-layout="minimal-saas">
-  <div class="ly-wrapper ly-wrapper--wide">
-    <section class="ly-dashboard" data-ly-recipe="dashboard">
-      <header data-ly-area="header">Dashboard</header>
-      <nav data-ly-area="nav" aria-label="Dashboard">Navigation</nav>
-      <main data-ly-area="main">Workspace</main>
-      <aside data-ly-area="aside">Details</aside>
-      <footer data-ly-area="footer">Status</footer>
-    </section>
+  <div data-ly-recipe="split-hero">
+    <main data-ly-area="content">Primary message</main>
+    <figure data-ly-area="media">Media</figure>
+    <div data-ly-area="actions">Actions</div>
   </div>
 </body>
 ```
 
-The single-column DOM order is authoritative for mobile reading and keyboard focus. Core named grid areas rearrange at `48rem` and `64rem` container widths without changing source order; a selected personality may apply its own personality-specific enhancement threshold.
+The recipe stays stacked below `42rem` and enhances automatically when its nearest `ly-scope` container has enough room.
 
-## Switch Personality
+## Optional Wrapper
 
-```js
-document.querySelector(".ly-root").dataset.lyLayout = "synthwave";
+Use wrappers when a composition needs a named measure or local responsive scope:
+
+```html
+<section class="ly-wrapper ly-wrapper--wide">
+  <div data-ly-recipe="card-grid">
+    <article>One</article>
+    <article>Two</article>
+  </div>
+</section>
+```
+
+Available measures are `.ly-wrapper--compact`, `.ly-wrapper--prose`, `.ly-wrapper--content`, `.ly-wrapper--wide`, `.ly-wrapper--full`, and `.ly-wrapper--breakout`.
+
+## Manual Topology
+
+Use `data-ly-responsive="manual"` only when application CSS must choose the topology:
+
+```css
+@container ly-scope (min-width: 56rem) {
+  [data-ly-recipe="docs"][data-ly-responsive="manual"] {
+    /* Application-owned topology. */
+  }
+}
 ```
 
-`data-ly-layout` accepts one of the sixteen values listed in [Layout Styles](Layout-Styles.md). UI attributes such as `data-ui`, `data-theme`, and `data-mode` remain independent.
+Keep mobile DOM order authoritative. The package never changes reading or focus order.
 
-## Migrate Existing Markup
+## Next
 
-Do not copy v1 root hooks or size-based wrappers into new code. Follow [Migrating To 2.0](Migrating-To-2.0.md), or use `layout-style-css/legacy.css` temporarily while converting an application.
+- [Layout Primitives](Layout-Primitives.md)
+- [Layout Recipes](Layout-Recipes.md)
+- [Layout Styles](Layout-Styles.md)
+- [Migrating To 3.0](Migrating-To-3.0.md)

package/docs/wiki/Home.md

@@ -1,33 +1,27 @@
-# Layout Style CSS Wiki
+# Layout Style CSS v3
 
-Version 2.1.1 is a container-first, dependency-free layout library. It ships semantic wrappers, composition primitives, seven recipes, sixteen layout personalities, focused exports, a v2-only compatibility bundle, and refreshed ecosystem fixtures for UI Style Kit CSS 2.1 and Interactive Surface CSS 1.5.
+`layout-style-css@3.0.1` is a dependency-free, CSS-only structural system for layouts that adapt to available width and height.
 
-## Start Here
+## Contract
 
-| Page | Purpose |
-| --- | --- |
-| [Getting Started](Getting-Started.md) | First wrapper, recipe, and personality. |
-| [Installation And CDN](Installation-And-CDN.md) | Exact package exports and ecosystem import order. |
-| [Layout Primitives](Layout-Primitives.md) | Wrappers and composition primitives. |
-| [Layout Recipes](Layout-Recipes.md) | Named recipes, areas, and mobile ordering. |
-| [Layout Styles](Layout-Styles.md) | Sixteen spatial personalities. |
-| [UI Style Kit Compatibility](UI-Style-Kit-Compatibility.md) | Structural bridge and ownership boundaries. |
-| [Migrating To 2.0](Migrating-To-2.0.md) | Complete 1.x selector and export mapping. |
-| [Demo And GitHub Pages](Demo-And-GitHub-Pages.md) | Interactive lab, browser matrix, and Pages artifact. |
-| [Release And Publishing](Release-And-Publishing.md) | Release verification and separately approved publish steps. |
-| [Security And Support](Security-And-Support.md) | Supported versions and reporting. |
-| [Contributing](Contributing.md) | Source, generated output, testing, and review rules. |
+- `.ly-root` is a usable layout and named `ly-scope` container.
+- Wrappers are optional measure and nesting controls.
+- Seven `data-ly-recipe` values enhance a semantic stacked fallback.
+- `data-ly-responsive="manual"` transfers topology ownership to application CSS.
+- Sixteen `data-ly-layout` profiles tune one shared responsive engine.
+- `100dvh` behavior and the `44rem`/`30rem` height tiers avoid short-screen traps.
+- The mobile DOM order remains the reading, keyboard, and focus order.
 
-## Ownership
+Layout owns structure. UI Style Kit owns paint. Interactive Surface owns interaction styling.
 
-Layout Style CSS owns spatial behavior: containment, wrappers, flow, grids, areas, spans, sizing, and responsive arrangement. UI Style Kit owns visual paint. Interactive Surface owns interaction-state styling.
+## Documentation
 
-The package has no runtime or peer dependencies. `ui-style-kit-css@2.1.0` and `interactive-surface-css@1.5.0` are released registry fixtures used to prove optional integration.
-
-## Supported Baseline
-
-- Node.js 20 or newer for package development
-- Current evergreen Chromium, Firefox, and WebKit
-- Mobile-first DOM order with core thresholds at `48rem` and `64rem`, nearest-container personality overrides, and `64rem` feasibility gates for three- and four-track application shells
-
-The deprecated UI structural bridge remains available for existing UI-prefixed layout aliases, but canonical 2.1 examples use UI Style Kit visual CSS, the UI token bridge, Interactive Surface `state-core.css`, and Layout core.
+- [Getting Started](Getting-Started.md)
+- [Installation And CDN](Installation-And-CDN.md)
+- [Layout Primitives](Layout-Primitives.md)
+- [Layout Recipes](Layout-Recipes.md)
+- [Layout Styles](Layout-Styles.md)
+- [Migrating To 3.0](Migrating-To-3.0.md)
+- [Demo And GitHub Pages](Demo-And-GitHub-Pages.md)
+- [Release And Publishing](Release-And-Publishing.md)
+- [Security And Support](Security-And-Support.md)

package/docs/wiki/Installation-And-CDN.md

@@ -1,47 +1,53 @@
 # Installation And CDN
 
-Layout Style CSS 2.0 is dependency-free and has no peer dependency contract. Node.js 20 or newer is required only for package development and verification.
+## Requirements
 
-## npm
+- Node.js 20 or newer for development
+- Evergreen Chromium, Firefox, or WebKit
+- No runtime or peer dependencies
+
+## Package
 
 ```bash
-npm install layout-style-css@2.1.1
+npm install layout-style-css@3.0.1
 ```
 
-## Focused Exports
+```js
+import "layout-style-css";
+```
 
-| Import | Purpose |
-| --- | --- |
-| `layout-style-css` | Full v2 core and all personalities. |
-| `layout-style-css/min.css` | Minified full bundle. |
-| `layout-style-css/core.css` | Wrappers, primitives, recipes, and utilities. |
-| `layout-style-css/wrappers.css` | Wrapper tokens and containment. |
-| `layout-style-css/primitives.css` | Composition primitives. |
-| `layout-style-css/recipes.css` | Seven recipe roots and named areas. |
-| `layout-style-css/utilities.css` | Structural utility layer. |
-| `layout-style-css/personalities.css` | All personalities. |
-| `layout-style-css/personalities/minimal-saas.css` | One personality; replace the name as needed. |
-| `layout-style-css/integrations/ui-style-kit.css` | Import-free structural UI bridge. |
-| `layout-style-css/legacy.css` | Full v2 bundle with v1 aliases. |
+The root import is the zero-configuration full bundle. Focused exports are:
 
-The old `all-with-ui-kit*`, `all.css`, `base.css`, `bridge.css`, and root personality exports do not exist in v2.
+Package and bundler defaults (`main`, `style`, and the root export) use the readable `dist/layout-style-css.css` file. The `unpkg` and `jsdelivr` convenience fields use `dist/layout-style-css.min.css`; package consumers can select the same minified output explicitly with `layout-style-css/min.css`.
 
-## Import Modes
+- `layout-style-css/min.css`
+- `layout-style-css/core.css`
+- `layout-style-css/foundation.css`
+- `layout-style-css/wrappers.css`
+- `layout-style-css/primitives.css`
+- `layout-style-css/recipes.css`
+- `layout-style-css/utilities.css`
+- `layout-style-css/personalities.css`
+- `layout-style-css/personalities/minimal-saas.css` and the other fifteen profile names
+- `layout-style-css/package.json`
 
-Standalone:
+`core.css` contains Foundation, Wrappers, Primitives, Recipes, and Utilities. The default bundle adds all personality profiles.
 
-```js
-import "layout-style-css";
-```
+## CDN
 
-Layout plus UI Style Kit:
+```html
+<link rel="stylesheet" href="https://unpkg.com/layout-style-css@3.0.1/dist/layout-style-css.min.css">
+```
 
-```js
-import "ui-style-kit-css/visual.css";
-import "layout-style-css";
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/layout-style-css@3.0.1/dist/layout-style-css.min.css">
 ```
 
-All three libraries, in required order:
+The CDN paths include `/dist/` because CDN clients address files in the published tarball, while package import maps use the public exports.
+
+## Ecosystem Order
+
+Layout has no companion imports. When all three libraries are installed, keep ownership explicit:
 
 ```js
 import "ui-style-kit-css/visual.css";
@@ -50,23 +56,22 @@ import "interactive-surface-css/state-core.css";
 import "layout-style-css";
 ```
 
-The first import block is deprecated compatibility for legacy UI-prefixed structural aliases. Canonical 2.1 imports use the released `ui-style-kit-css@2.1.0` visual CSS, `ui-style-kit-css/interactive-surface-theme.css`, released `interactive-surface-css@1.5.0` state core, and Layout core.
+Layout owns structure. UI Style Kit owns paint. Interactive Surface owns interaction styling.
 
-## CDN
-
-Layout only:
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/layout-style-css@2.1.1/dist/layout-style-css.min.css">
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/layout-style-css@2.1.1/dist/layout-style-css.min.css">
-```
+## Cascade Layers
 
-For optional companions, preserve the same order as the package imports: UI Style Kit visual CSS, UI Style Kit `interactive-surface-theme.css`, Interactive Surface 1.5.0 `state-core.css`, then Layout core. Load `layout-style-css/integrations/ui-style-kit.css` only for deprecated structural aliases.
+The module order is:
 
-## Browser Baseline
+1. `ly.reset`
+2. `ly.tokens`
+3. `ly.wrappers`
+4. `ly.primitives`
+5. `ly.recipes`
+6. `ly.utilities`
+7. `ly.personalities`
 
-Current evergreen Chromium, Firefox, and WebKit are supported. Core container-driven enhancements activate at `48rem` and `64rem`; personalities may use personality-specific thresholds. Unsupported container-query environments retain the mobile source-order fallback.
+Application styles can override public custom properties without reordering the package modules.
 
-## Source Ownership
+## Clean-Break Note
 
-`styles/` contains authored CSS. `dist/` is generated. Consumers should use package exports or CDN dist files, never internal source paths.
+v3 does not export a compatibility bundle, legacy aliases, the deprecated structural bridge, extensionless aliases, or responsive/order utility families. See [Migrating To 3.0](Migrating-To-3.0.md).

package/docs/wiki/Layout-Primitives.md

@@ -1,48 +1,62 @@
 # Layout Primitives
 
-V2 primitives are structural, mobile-first, and safe to use without a visual design system.
+## Foundation And Containment
 
-## Semantic Wrappers
+`.ly-root` supplies shared structural tokens, shrink safety, the named `ly-scope` inline-size container, and height-aware defaults. Reset and public tokens live in `layout-style-css/foundation.css`.
 
-`.ly-wrapper` defaults to the `72rem` content measure and establishes an inline-size container. Fluid logical gutters include safe-area insets.
+Every primitive applies `min-inline-size: 0` and `min-block-size: 0` where tracks or children need to shrink.
 
-Layout personalities can provide a distinct measure for the plain `.ly-wrapper`. Explicit semantic wrapper variants always keep the measures below, so changing the demo wrapper control produces a real structural change under every personality.
+## Wrappers
 
-| Selector | Measure or behavior |
-| --- | --- |
-| `.ly-wrapper--compact` | `40rem` |
-| `.ly-wrapper--prose` | `68ch` |
-| `.ly-wrapper--content` | `72rem`, also the default |
-| `.ly-wrapper--wide` | `112rem` |
-| `.ly-wrapper--full` | Full available inline size |
-| `.ly-wrapper--breakout` | Content, feature, and full lanes |
+Wrappers are optional local responsive scopes:
 
-Breakout children use `.ly-lane--content`, `.ly-lane--feature`, `.ly-lane--full`, or equivalent `data-ly-lane` attributes.
+- `.ly-wrapper--compact`
+- `.ly-wrapper--prose`
+- `.ly-wrapper--content`
+- `.ly-wrapper--wide`
+- `.ly-wrapper--full`
+- `.ly-wrapper--breakout`
 
-## Composition
+Breakout children select clamped lanes with `data-ly-lane="content"`, `data-ly-lane="feature"`, or `data-ly-lane="full"`.
 
-| Primitive | Contract |
-| --- | --- |
-| `.ly-stack` | Vertical flow with a shared stack gap. |
-| `.ly-cluster` | Wrapping inline group. |
-| `.ly-center` | Centered element with a bounded measure. |
-| `.ly-cover` | Full-height vertical composition with an optional centered child. |
-| `.ly-switcher` | Wrapping equal items based on available inline size. |
-| `.ly-sidebar` | Side and content regions that wrap safely. |
-| `.ly-grid` | Explicit structural grid; `.ly-grid--auto` uses auto-fit. |
-| `.ly-split` | One column, then two columns from `48rem`. |
-| `.ly-panes` | One column with two- and three-pane variants. |
-| `.ly-media` | Media, content, and action areas. |
-| `.ly-reel` | Bounded horizontal flow with scroll snapping. |
-| `.ly-frame` | Stable aspect-ratio frame. |
-| `.ly-scroll` | Bounded scrolling with overscroll containment. |
+## Flow
 
-Primitives respond to their nearest wrapper or recipe container at the `48rem` and `64rem` core thresholds. They do not set color, typography, borders, shadows, or interaction states.
+- `.ly-stack` creates vertical flow.
+- `.ly-cluster` wraps inline groups.
+- `.ly-center` centers a bounded composition.
+- `.ly-cover` fills available block size while preserving reachable normal flow.
 
-For v1 migrations, `legacy.css` keeps `.ly-content` as `min-inline-size: 0` and preserves only the minimum block size and spacing of `.ly-divider`. A visible divider is paint and must come from UI Style Kit or the application theme; `.ly-surface--raised` is removed for the same ownership reason.
+## Adaptive Tracks
 
-## Structural Utilities
+- `.ly-switcher` wraps when its intrinsic threshold is no longer feasible.
+- `.ly-sidebar` keeps a preferred rail while the content can meet its minimum.
+- `.ly-grid` uses auto-fit tracks and `--ly-grid-min`.
+- `.ly-split` creates balanced intrinsic regions.
+- `.ly-panes` creates a preferred workspace rail and flexible pane.
+- `.ly-media` wraps media and content without a viewport breakpoint.
 
-The utility module includes grid column variables, spans, gaps, padding, sizing, overflow, alignment, frame ratios, visibility, and explicit order escape hatches.
+## Frame And Overflow
 
-Ordering families are available at base, medium container (`ly-md-*`), and large container (`ly-lg-*`) sizes. They include first, normal, last, and numeric values 1 through 6. Visual reordering can conflict with reading and focus order; see [Migrating To 2.0](Migrating-To-2.0.md) before using them.
+- `.ly-frame` keeps a configurable aspect ratio.
+- `.ly-reel` is the deliberate horizontal-flow primitive.
+- `.ly-scroll` is the deliberate bounded vertical-scroll primitive.
+
+In normal use, only `.ly-reel` introduces intentional horizontal scrolling, and only `.ly-scroll` introduces intentional vertical scrolling. Other wrappers, primitives, and recipes clamp to their available inline size.
+
+## Height Behavior
+
+Page, cover, and bounded scroll behaviors use `vh` fallbacks followed by dynamic viewport units such as `100dvh`.
+
+At `44rem` viewport height or less, gaps and scroll maxima tighten. At `30rem` or less, forced cover/shell minimums and recipe-owned sticky positioning are removed. Required regions remain in normal document flow.
+
+## Public Tuning
+
+Advanced consumers can override stable custom properties for:
+
+- gaps and spacing
+- wrapper measures and gutters
+- sidebar, pane, media, reel, and grid minimums
+- frame ratios
+- shell, cover, and bounded-scroll sizing
+
+These tokens tune behavior without creating a second breakpoint system.