docs: publish v3 contract and migration guidance

Author: Foscat

.github/workflows/npm-publish.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
     inputs:
       release_tag:
-        description: "Release tag to publish, for example v2.1.1"
+        description: "Release tag to publish, for example v3.0.0"
         required: true
         type: string
 

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to `layout-style-css` are documented here. This project follows semantic versioning.
 
+## [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.
+- Restricted deliberate horizontal scrolling to Reel and deliberate bounded vertical scrolling to Scroll.
+
+### Tests
+
+- Added package/export/tarball, canonical-selector, removed-surface, generated-parity, ownership, and personality-engine 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

CONTRIBUTING.md

@@ -24,9 +24,11 @@ npm run release:verify
 - Regenerate `dist/` with `npm run build`; do not hand-edit generated dist files.
 - Keep public layout classes prefixed with `ly-`.
 - Leave colors, typography, borders, shadows, native controls, focus states, themes, and modes to `ui-style-kit-css`.
-- Add structural aliases in `styles/integrations/ui-style-kit.css` only when they map to layout primitives or layout recipes.
-- Preserve semantic mobile DOM, reading, and focus order; built-in recipes must use named areas instead of `order`.
-- Test container behavior below and above `48rem` and `64rem`.
+- Keep v3 on canonical hooks; do not add legacy, recipe-class, or companion structural aliases.
+- Preserve semantic mobile DOM, reading, and focus order; built-in recipes must use named areas instead of visual order.
+- Test container behavior below and above `42rem`, `44rem`, `48rem`, `52rem`, and `72rem`.
+- Test height behavior below and above `30rem` and `44rem`.
+- Keep personality files limited to tokens and topology templates; they must not declare breakpoints.
 - Update README, `docs/wiki`, and `CHANGELOG.md` when a public class, export, recipe, release workflow, or package behavior changes.
 
 ## Testing Expectations

README.md

@@ -1,7 +1,7 @@
 {
   "name": "layout-style-css",
   "short_name": "Layout CSS",
-  "description": "Container-first layout-style-css 2.1 lab for wrappers, recipes, personalities, and optional ecosystem integrations.",
+  "description": "Layout Style CSS v3 intrinsic responsive lab for width, height, wrappers, recipes, and personalities.",
   "start_url": "./index.html",
   "display": "standalone",
   "background_color": "#111827",

demo/site.webmanifest

@@ -2,7 +2,7 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://foscat.github.io/layout-style-css/</loc>
-    <lastmod>2026-07-27</lastmod>
+    <lastmod>2026-07-29</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.8</priority>
   </url>

demo/sitemap.xml

@@ -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.
 

docs/wiki/Contributing.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.

docs/wiki/Demo-And-GitHub-Pages.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.0` and import the root bundle:
 
 ```bash
-npm install layout-style-css@2.1.1
+npm install layout-style-css@3.0.0
 ```
 
-## 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)

docs/wiki/Getting-Started.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.0` 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)