layout-style-css 3.0.0 → 3.0.2

package/dist/primitives.css

@@ -34,11 +34,11 @@
   }
 
   .ly-section--compact {
-    --ly-section-padding-block: var(--ly-space-7);
+    padding-block: var(--ly-section-padding-block-compact);
   }
 
   .ly-section--flush {
-    --ly-section-padding-block: 0;
+    padding-block: 0;
   }
 
   .ly-readable {

package/dist/recipes.css

@@ -42,7 +42,7 @@
       "main"
       "aside"
       "footer";
-    grid-template-rows: auto auto minmax(0, 1fr) auto auto;
+    grid-template-rows: var(--ly-app-shell-base-rows);
   }
 
   [data-ly-recipe="dashboard"],
@@ -173,6 +173,7 @@
     [data-ly-recipe="app-shell"]:not([data-ly-responsive="manual"]) {
       grid-template-areas: var(--ly-app-shell-medium-areas);
       grid-template-columns: var(--ly-app-shell-medium-columns);
+      grid-template-rows: var(--ly-app-shell-medium-rows);
     }
 
     [data-ly-recipe="dashboard"]:not([data-ly-responsive="manual"]) {
@@ -185,6 +186,7 @@
     [data-ly-recipe="app-shell"]:not([data-ly-responsive="manual"]) {
       grid-template-areas: var(--ly-app-shell-wide-areas);
       grid-template-columns: var(--ly-app-shell-wide-columns);
+      grid-template-rows: var(--ly-app-shell-wide-rows);
     }
 
     [data-ly-recipe="dashboard"]:not([data-ly-responsive="manual"]) {

package/dist/wrappers.css

@@ -5,7 +5,7 @@
 @layer ly.wrappers {
   .ly-wrapper {
     --ly-wrapper-max: var(--ly-personality-wrapper-max, var(--ly-wrapper-content));
-    --ly-wrapper-fluid-gutter: clamp(1rem, 3vw, 3rem);
+    --ly-wrapper-fluid-gutter: var(--ly-wrapper-gutter);
     --ly-wrapper-local-gutter: max(
       var(--ly-wrapper-fluid-gutter),
       var(--ly-safe-area-inline)
@@ -19,13 +19,6 @@
     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: var(--ly-wrapper-compact);
   }

package/docs/wiki/Contributing.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Contributions must preserve the package boundary: Layout Style owns structure, UI Style Kit owns visual paint, and Interactive Surface owns interaction states.
+
+## Workflow
+
+```bash
+npm ci
+npm run build
+npm run lint
+npm run check:demo-js
+npm test
+```
+
+Use `npm run test:demo:all` for rendered layout changes and `npm run release:verify` before release-facing work is merged.
+
+## Source And Generated Files
+
+- Edit authored modules in `styles/`.
+- Regenerate `dist/` with `npm run build`.
+- Keep the shared cascade-layer prelude in every public entry.
+- Never hand-edit generated CSS or Pages output.
+- Use professional comments for containment, accessibility, cascade, or build-safety decisions.
+
+## Layout Rules
+
+- 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 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.
+
+## Documentation
+
+Update README, migration guide, wiki, changelog, demo metadata, and contract tests whenever an export, selector, recipe, compatibility rule, browser baseline, or release command changes.

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

@@ -0,0 +1,44 @@
+# Demo And GitHub Pages
+
+The v3 demo is an intrinsic responsive workbench, not a fixed-device screenshot gallery.
+
+## Controls
+
+- 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
+
+Device presets cover the release allocations:
+
+- Phone portrait: `360 × 800`
+- Phone landscape: `800 × 360`
+- Tablet portrait: `768 × 1024`
+- Tablet landscape: `1024 × 768`
+- Desktop landscape: `1440 × 900`
+- Desktop portrait: `900 × 1440`
+
+Threshold controls also cover one rem below and above `42rem`, `44rem`, `48rem`, `52rem`, and `72rem`, plus the `30rem` and `44rem` height tiers.
+
+## Local Verification
+
+```bash
+npm run build
+npm run test:demo:quick
+npm run test:demo:all
+```
+
+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.
+
+## GitHub Pages
+
+```bash
+npm run pages:build
+npm run test:pages
+```
+
+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.
+
+`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

@@ -0,0 +1,63 @@
+# Getting Started
+
+Install `layout-style-css@3.0.2` and import the root bundle:
+
+```bash
+npm install layout-style-css@3.0.2
+```
+
+```js
+import "layout-style-css";
+```
+
+## First Automatic Layout
+
+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 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 recipe stays stacked below `42rem` and enhances automatically when its nearest `ly-scope` container has enough room.
+
+## Optional Wrapper
+
+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. */
+  }
+}
+```
+
+Keep mobile DOM order authoritative. The package never changes reading or focus order.
+
+## Next
+
+- [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

@@ -0,0 +1,27 @@
+# Layout Style CSS v3
+
+`layout-style-css@3.0.2` is a dependency-free, CSS-only structural system for layouts that adapt to available width and height.
+
+## Contract
+
+- `.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.
+
+Layout owns structure. UI Style Kit owns paint. Interactive Surface owns interaction styling.
+
+## Documentation
+
+- [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

@@ -0,0 +1,77 @@
+# Installation And CDN
+
+## Requirements
+
+- Node.js 20 or newer for development
+- Evergreen Chromium, Firefox, or WebKit
+- No runtime or peer dependencies
+
+## Package
+
+```bash
+npm install layout-style-css@3.0.2
+```
+
+```js
+import "layout-style-css";
+```
+
+The root import is the zero-configuration full bundle. Focused exports are:
+
+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`.
+
+- `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`
+
+`core.css` contains Foundation, Wrappers, Primitives, Recipes, and Utilities. The default bundle adds all personality profiles.
+
+## CDN
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/layout-style-css@3.0.2/dist/layout-style-css.min.css">
+```
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/layout-style-css@3.0.2/dist/layout-style-css.min.css">
+```
+
+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";
+import "ui-style-kit-css/interactive-surface-theme.css";
+import "interactive-surface-css/state-core.css";
+import "layout-style-css";
+```
+
+Layout owns structure. UI Style Kit owns paint. Interactive Surface owns interaction styling.
+
+## Cascade Layers
+
+The module order is:
+
+1. `ly.reset`
+2. `ly.tokens`
+3. `ly.wrappers`
+4. `ly.primitives`
+5. `ly.recipes`
+6. `ly.utilities`
+7. `ly.personalities`
+
+Application styles can override public custom properties without reordering the package modules.
+
+## Clean-Break Note
+
+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

@@ -0,0 +1,66 @@
+# Layout Primitives
+
+## Foundation And Containment
+
+`.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`.
+
+Every primitive applies `min-inline-size: 0` and `min-block-size: 0` where tracks or children need to shrink.
+
+## Wrappers
+
+Wrappers are optional local responsive scopes:
+
+- `.ly-wrapper--compact`
+- `.ly-wrapper--prose`
+- `.ly-wrapper--content`
+- `.ly-wrapper--wide`
+- `.ly-wrapper--full`
+- `.ly-wrapper--breakout`
+
+Breakout children select clamped lanes with `data-ly-lane="content"`, `data-ly-lane="feature"`, or `data-ly-lane="full"`.
+
+`--ly-page-padding-inline` supplies the default `--ly-wrapper-gutter` value. `--ly-wrapper-gutter` controls rendered Wrapper padding at the scope where it is overridden, while the Wrapper applies safe-area compensation once at its outer edge.
+
+## Flow
+
+- `.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.
+
+## Adaptive Tracks
+
+- `.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.
+
+## Frame And Overflow
+
+- `.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.
+
+`--ly-section-padding-block` controls normal `.ly-section` spacing. `--ly-section-padding-block-compact` controls `.ly-section--compact` independently and remains smaller than the normal value across regular, short, and shallow viewport heights.
+
+## 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.

package/docs/wiki/Layout-Recipes.md

@@ -0,0 +1,60 @@
+# Layout Recipes
+
+Recipes are attribute-only semantic layouts. The mobile DOM order is authoritative, and automatic container enhancement is the zero-configuration default.
+
+## Automatic Thresholds
+
+| Recipe | Nearest `ly-scope` threshold |
+| --- | --- |
+| `data-ly-recipe="split-hero"` | `42rem` |
+| `data-ly-recipe="list-detail"` | `44rem` |
+| `data-ly-recipe="docs"` | `48rem` |
+| `data-ly-recipe="app-shell"` | medium `52rem`, wide `72rem` |
+| `data-ly-recipe="dashboard"` | medium `52rem`, wide `72rem` |
+| `data-ly-recipe="gallery"` | intrinsic; no topology query |
+| `data-ly-recipe="card-grid"` | intrinsic; no topology query |
+
+Recipe roots also establish `ly-scope`, so child compositions can respond without extra setup.
+
+App Shell base, medium, and wide topologies own matching row definitions. Header and footer tracks remain intrinsic while the main workspace receives the flexible row, including personality-specific four-row topologies.
+
+## Areas
+
+Canonical `data-ly-area` values are:
+
+- App shell: `header`, `sidebar`, `main`, `aside`, `footer`
+- Dashboard and Docs: `header`, `nav`, `main`, `aside`, `footer`
+- List detail: `primary`, `secondary`, `actions`
+- Split hero: `content`, `media`, `actions`
+
+```html
+<section data-ly-recipe="docs">
+  <header data-ly-area="header">Docs</header>
+  <nav data-ly-area="nav" aria-label="Documentation">Navigation</nav>
+  <main data-ly-area="main">Article</main>
+  <aside data-ly-area="aside">On this page</aside>
+  <footer data-ly-area="footer">Next</footer>
+</section>
+```
+
+## Manual Responsiveness
+
+`data-ly-responsive="manual"` disables automatic topology rules while retaining the stacked fallback.
+
+```css
+@container ly-scope (min-width: 56rem) {
+  [data-ly-recipe="docs"][data-ly-responsive="manual"] {
+    /* Application-owned topology. */
+  }
+}
+```
+
+Use the nearest wrapper as the query boundary when a component needs a constrained local allocation. Use a recipe directly in `.ly-root` when no measure wrapper is needed.
+
+## Accessibility
+
+Write the source in mobile reading order and keep actions beside the content they control. Named grid areas can change visual placement, but they do not alter DOM, reading, keyboard, or focus order. Visual-order utilities are not part of v3.
+
+## Vertical Responsiveness
+
+Recipe gaps and scroll bounds tighten at `44rem` viewport height. At `30rem`, recipe-owned sticky positioning and forced shell height stop so navigation, main content, and actions remain reachable.

package/docs/wiki/Layout-Styles.md

@@ -0,0 +1,69 @@
+# Layout Styles
+
+The sixteen `data-ly-layout` values are focused token and topology profiles:
+
+`minimal-saas`, `bauhaus`, `tactile`, `cyberpunk`, `f-pattern`, `brutalism`, `neumorphism`, `y2k`, `retro-glass`, `z-pattern`, `retrofuturism`, `mondrian`, `synthwave`, `bento`, `maximalist`, and `split-screen`.
+
+```html
+<body class="ly-root" data-ly-layout="bento">
+  <main data-ly-recipe="dashboard">...</main>
+</body>
+```
+
+## Shared Engine
+
+Every profile feeds the same wrapper, primitive, and recipe engine. Profiles tune values such as:
+
+- wrapper measure
+- base and grid gaps
+- rail, pane, and media preferences
+- gallery and card minimums
+- frame ratio
+- shared recipe area and track templates
+
+A profile must remain visibly distinct through at least two spatial characteristics. Personality files may not declare their own `@container`, viewport, or orientation breakpoint systems.
+
+When a profile supplies an App Shell area template, its matching row definition must contain the same number of rows and keep the main workspace on the flexible track.
+
+## Ownership
+
+Layout owns structure. UI Style Kit owns paint. Interactive Surface owns interaction styling.
+
+The personality name does not promise colors, typography, borders, shadows, or interaction states. Pair the same name across libraries when desired, but import each library explicitly and let it own its layer.
+
+## Visual Pairing Guidance
+
+[`layout-style-css/personalities.json`](../../personalities.json) is the public, machine-readable pairing source used by the demo. Its entries are recommendations, never dependencies: `data-ly-layout`, `data-ui`, `data-theme`, and `data-mode` are independently selectable on the same document.
+
+| Layout personality | Visual pairing guidance |
+| --- | --- |
+| Minimal SaaS | Native match: `minimal-saas` |
+| Bento | Native match: `bento` |
+| Maximalist | Native match: `maximalist` |
+| Bauhaus | Native match: `bauhaus` |
+| Tactile | Native match: `tactile` |
+| Neumorphism | Native match: `neumorphism` |
+| Retrofuturism | Native match: `retrofuturism` |
+| Brutalism | Native match: `brutalism` |
+| Cyberpunk | Native match: `cyberpunk` |
+| Y2K | Native match: `y2k` |
+| Retro Glass | Native match: `retro-glass` |
+| F-pattern | Any visual preset; this is structure only |
+| Z-pattern | Any visual preset; this is structure only |
+| Split Screen | Any visual preset; this is structure only |
+| Mondrian | Any visual preset; this is structure only |
+| Synthwave | Recommended: `cyberpunk` or `retrofuturism`; the browser contract verifies each preset's distinct rendered article shadow while retaining `data-ly-layout="synthwave"` |
+
+## Customization
+
+Override public tokens at `.ly-root` or a narrower scope:
+
+```css
+.product-shell {
+  --ly-profile-gap: 1.25rem;
+  --ly-recipe-rail: 17rem;
+  --ly-card-grid-min: 18rem;
+}
+```
+
+Use `data-ly-responsive="manual"` plus an application-owned `@container ly-scope` query when token tuning is not enough.