layout-style-css 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -0,0 +1,154 @@
+# Changelog
+
+All notable changes to `layout-style-css` are documented here. This project follows semantic versioning.
+
+## [3.0.1] - 2026-08-09
+
+### Changed
+
+- Corrected the GitHub Pages homepage used by npm, kept readable package defaults alongside explicit minified CDN metadata, and included the maintained packaged documentation.
+- Synchronized the package, lockfile, public manifest, demo metadata, Pages sitemap, release guidance, and current ecosystem contract while preserving the complete 13-export API and existing CSS behavior.
+
+### Security
+
+- Retained the audited dependency overrides and secure release tooling used by the protected publication workflow without adding runtime or peer dependencies.
+
+### Tests
+
+- Added version-sensitive package, manifest, layout, documentation, demo, Pages, release, packed-export, clean-install, and ecosystem checks for the patch candidate.
+
+## [3.0.0] - 2026-07-29
+
+### Breaking
+
+- Rebuilt the package as a clean-break intrinsic responsive system with attribute-only recipes and one shared container-query engine.
+- Removed `legacy.css`, the deprecated UI Style Kit structural bridge, v1/v2 aliases, recipe class aliases, extensionless export aliases, responsive/order utility families, and the scrollbar-unsafe `.ly-bleed` helper.
+- Reduced the npm tarball to the public generated CSS modules and personality profiles; package metadata, README, and license remain npm-standard package files.
+
+### Added
+
+- Added `foundation.css` for shared reset, tokens, named `ly-scope` containment, dynamic viewport sizing, and the `44rem`/`30rem` height tiers.
+- Made `.ly-root`, every wrapper, and every recipe root a named responsive scope so recipes work without wrappers and respond to the nearest wrapper when nested.
+- Added `data-ly-responsive="manual"` for application-owned topology with a safe stacked fallback.
+- Added device, independent width/height, automatic/manual, dimension, and active-topology controls to the demo.
+
+### Changed
+
+- Replaced breakpoint-heavy primitives with intrinsic Grid and Flexbox behavior and standardized shrink safety.
+- Moved Split Hero, List Detail, Docs, App Shell, and Dashboard topology to the shared `42rem`, `44rem`, `48rem`, `52rem`, and `72rem` query tiers.
+- Converted all sixteen personalities into breakpoint-free token/topology profiles with at least two distinguishing spatial characteristics.
+- Made dynamic viewport and container-relative tokens feature-detected enhancements over valid `vh` and `vw` fallbacks.
+- Made manual Gallery and Card Grid recipes single-column, isolated nested personality split ratios, and aligned gap utilities across Grid, Stack, and Cluster.
+- Restricted deliberate horizontal scrolling to Reel and deliberate bounded vertical scrolling to Scroll.
+- Corrected case-sensitive GitHub Pages metadata and versioned local demo assets to prevent stale v2/v3 asset combinations.
+
+### Tests
+
+- Added package/export/tarball, canonical-selector, removed-surface, generated-parity, ownership, and personality-engine contracts.
+- Added exact flattened/minified parity, actual tarball contents, complete v2 selector migration, nested-profile isolation, and fallback-enhancement contracts.
+- Added threshold-edge, six-device, short-height, root-direct, nearest-wrapper, manual-query, DOM/focus-order, overflow, wrapper, recipe, and all-personality rendered matrices.
+- Made Chromium, Firefox, and WebKit the complete release gate and retained the connected-browser interaction spot check.
+
+## [2.1.1] - 2026-07-27
+
+### Fixed
+
+- Made personality enhancements query the nearest inline-size container while preserving the named personality containment scope for compatibility.
+- Deferred three- and four-track application-shell signatures until their local container reaches `64rem`; existing safe two-track signatures retain their authored thresholds.
+- Gave the Docs recipe a distinct wide two-column shell with navigation spanning the left column and `header`, `main`, `aside`, and `footer` stacked in the right column.
+
+### Tests
+
+- Added root-wide, local-container fixtures at `47rem`, `49rem`, `63rem`, and `65rem` across all sixteen personalities, including internal overflow, zero-width region, DOM order, and keyboard order checks.
+- Added static contracts for nearest-container personality queries and distinct Dashboard and Docs wide geometry.
+
+### Security
+
+- Refreshed the development lockfile to patched `fast-uri` and `postcss` releases so the release audit reports no known vulnerabilities; the published CSS package remains dependency-free.
+
+## [2.1.0] - 2026-07-20
+
+### Changed
+
+- Updated the ecosystem demo and documentation to use `ui-style-kit-css@2.1.0` visual CSS, `ui-style-kit-css/interactive-surface-theme.css`, `interactive-surface-css@1.5.0` state core, and Layout core as the canonical import order.
+- Kept `layout-style-css/integrations/ui-style-kit.css` available as a frozen deprecated structural bridge for legacy UI-prefixed layout aliases.
+- Updated release metadata and the GitHub Pages demo to identify the 2.1.0 package line.
+
+### Tests
+
+- Switched demo fixtures to consume the staged UI Style Kit 2.1 manifest, visual bundle, and token bridge while locking Interactive Surface to the released 1.5.0 package.
+
+## [2.0.0] - 2026-07-19
+
+### Breaking
+
+- Rebuilt the package as a dependency-free, container-first layout system requiring Node.js 20 or newer for development scripts.
+- Replaced size-tier wrappers with compact, prose, content, wide, full, and breakout semantics; wrappers now include fluid logical gutters and safe-area compensation.
+- Standardized personalities, recipes, and regions on `data-ly-layout`, `data-ly-recipe`, and `data-ly-area`.
+- Replaced root personality exports and companion `all-with-ui-kit*` aggregates with focused modules under `personalities/` and `integrations/`.
+- Moved v1 containers, root hooks, columns, and recipe aliases into the opt-in `legacy.css` bundle for the v2 line; removal is scheduled for v3.
+
+### Added
+
+- Added stack, cluster, center, cover, switcher, sidebar, grid, split, panes, media, reel, frame, and bounded-scroll primitives.
+- Added seven functional recipes that preserve mobile DOM, reading, and focus order while rearranging named areas at `48rem` and `64rem` container thresholds.
+- Made every `data-ly-recipe` value a complete alternative to its matching class and kept explicit wrapper measures authoritative under all personalities.
+- Added sixteen spatially distinct personalities across left-rail, right-rail, three-zone, mosaic, and equal-split families.
+- Added explicit base, medium-container, and large-container order escape hatches with accessibility guidance.
+- Added a maintainable interactive layout lab with allowlisted query state, copyable snippets, ecosystem modes, and rendered coverage at 375px, 768px, 1280px, and 1440px.
+- Added a complete 1.x-to-2.0 migration guide, Node.js 20/22 CI, and Chromium, Firefox, and WebKit release verification.
+
+### Integration
+
+- Pinned `ui-style-kit-css@2.0.1` and `interactive-surface-css@1.4.0` as development fixtures only; the default package has no companion imports, peer dependencies, or runtime dependencies.
+- Documented the all-three import order as UI Style Kit bridge, Interactive Surface `state-core.css`, Layout integration bridge, then Layout core.
+- Kept the upcoming UI Style Kit revision as a follow-up outside this release.
+- Preserved structural v1 `.ly-content` and `.ly-divider` compatibility while leaving the removed paint-owned `.ly-surface--raised` selector to UI Style Kit or application themes.
+
+## [1.1.2] - 2026-07-08
+
+### Fixed
+
+- Reissued the release metadata, package lock, README install examples, wiki checklist, and publish workflow recovery tag under `1.1.2`.
+- Kept the additive `1.1.1` CSS and documentation contract intact while moving the publish target to a clean patch version.
+
+## [1.1.1] - 2026-07-05
+
+### Added
+
+- Added versioned wiki documentation under `docs/wiki` for installation, layout primitives, recipes, UI Style Kit compatibility, demo deployment, publishing, security, and contribution workflows.
+- Added UI Style Kit-compatible structural aliases for `saas`, `bento`, `max`, `bau`, `tactile`, `neo`, `retro`, `brutal`, `cyber`, `y2k`, and `rg` prefixes.
+- Added layout recipe helpers for button groups, card grids, card sizing, galleries, and carousels.
+- Added F-Pattern, Z-Pattern, Split-Screen, Mondrian, and Synthwave layout styles.
+- Added `layout-style-css/all-with-ui-kit-and-interactive-surface.css` for the three-library import path.
+- Added direct `./dist/*.css` package exports for consumers that need generated dist files.
+- Added `CHANGELOG.md`, `CONTRIBUTING.md`, and `SECURITY.md` to the release documentation set.
+
+### Changed
+
+- Reworked the demo mobile controls into a compact drawer so the sticky header does not consume the mobile viewport.
+- Expanded the demo to cover app shell, wrappers, split layouts, sidebars, panes, button groups, card grids, card sizes, galleries, carousels, frames, and scroll areas.
+- Updated README examples to use exported CSS entrypoints and valid CDN links.
+- Updated npm release metadata, package file allowlist, and release verification scripts for the `1.1.1` package.
+- Updated the npm publish workflow to publish from `release.published` events and explicit `workflow_dispatch` tags.
+
+### Fixed
+
+- Fixed README quick-start imports that referenced non-exported paths.
+- Fixed malformed UI Style Kit CDN link markup in the README.
+- Clarified responsive column utility documentation so class groups do not imply bare numeric class names.
+- Preserved GitHub Pages artifact generation with a Pages-root `index.html`.
+- Fixed the release automation path so draft releases can be published before the npm workflow runs.
+
+### Security
+
+- Kept the layout CSS contract free of visual properties owned by `ui-style-kit-css`.
+- Kept the package CSS-only at runtime with no network calls, dynamic script execution, or secret handling.
+- Added release verification coverage for npm pack contents and documentation completeness.
+
+## [1.0.0]
+
+### Added
+
+- Initial public release of layout primitives, layout style files, generated dist bundles, and demo coverage.
+

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.0` is a clean-break release. 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.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.
 
 ## 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.0
+npm install layout-style-css@3.0.1
 ```
 
 Most applications need one import:
@@ -24,6 +24,8 @@ import "layout-style-css";
 
 The full bundle includes the core modules and all personality profiles. No breakpoint configuration, wrapper, JavaScript, or companion library is required.
 
+Package and bundler defaults (`main`, `style`, and the root export) resolve to the readable `dist/layout-style-css.css` bundle for straightforward inspection and debugging. The `unpkg` and `jsdelivr` convenience fields remain minified, and `layout-style-css/min.css` is the explicit minified package import.
+
 ## Zero-Configuration Start
 
 Use `.ly-root` as the responsive boundary and keep the mobile DOM order authoritative:
@@ -151,6 +153,7 @@ Each personality is a token/topology profile consumed by the shared recipe engin
 | `layout-style-css/utilities.css` | Small structural utility set |
 | `layout-style-css/personalities.css` | All sixteen profiles |
 | `layout-style-css/personalities/minimal-saas.css` | One profile; substitute any public personality name |
+| `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`.
@@ -168,11 +171,13 @@ 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.
+
 ## CDN
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/layout-style-css@3.0.0/dist/layout-style-css.min.css">
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/layout-style-css@3.0.0/dist/layout-style-css.min.css">
+<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">
 ```
 
 ## Clean-Break Migration

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.1` and import the root bundle:
+
+```bash
+npm install layout-style-css@3.0.1
+```
+
+```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.1` 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.1
+```
+
+```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.1/dist/layout-style-css.min.css">
+```
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/layout-style-css@3.0.1/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,62 @@
+# 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"`.
+
+## 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.
+
+## 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,58 @@
+# 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.
+
+## 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,67 @@
+# 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.
+
+## 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.