layout-style-css 1.1.2 → 2.1.0

package/dist/utilities.css

@@ -0,0 +1,162 @@
+@layer ly.reset, ly.tokens, ly.wrappers, ly.primitives, ly.recipes, ly.utilities, ly.personalities, ly.integrations, ly.legacy;
+
+@layer ly.utilities {
+  .ly-cols-1 { --ly-grid-columns: 1; }
+  .ly-cols-2 { --ly-grid-columns: 2; }
+  .ly-cols-3 { --ly-grid-columns: 3; }
+  .ly-cols-4 { --ly-grid-columns: 4; }
+  .ly-cols-5 { --ly-grid-columns: 5; }
+  .ly-cols-6 { --ly-grid-columns: 6; }
+  .ly-cols-7 { --ly-grid-columns: 7; }
+  .ly-cols-8 { --ly-grid-columns: 8; }
+  .ly-cols-9 { --ly-grid-columns: 9; }
+  .ly-cols-10 { --ly-grid-columns: 10; }
+  .ly-cols-11 { --ly-grid-columns: 11; }
+  .ly-cols-12 { --ly-grid-columns: 12; }
+  .ly-cols-16 { --ly-grid-columns: 16; }
+
+  .ly-span-1 { grid-column: span 1; }
+  .ly-span-2 { grid-column: span 2; }
+  .ly-span-3 { grid-column: span 3; }
+  .ly-span-4 { grid-column: span 4; }
+  .ly-span-5 { grid-column: span 5; }
+  .ly-span-6 { grid-column: span 6; }
+  .ly-span-7 { grid-column: span 7; }
+  .ly-span-8 { grid-column: span 8; }
+  .ly-span-9 { grid-column: span 9; }
+  .ly-span-10 { grid-column: span 10; }
+  .ly-span-11 { grid-column: span 11; }
+  .ly-span-12 { grid-column: span 12; }
+  .ly-span-13 { grid-column: span 13; }
+  .ly-span-14 { grid-column: span 14; }
+  .ly-span-15 { grid-column: span 15; }
+  .ly-span-16 { grid-column: span 16; }
+  .ly-span-full { grid-column: 1 / -1; }
+
+  .ly-gap-0 { --ly-gap: var(--ly-space-0); --ly-grid-gap: var(--ly-space-0); --ly-stack-gap: var(--ly-space-0); --ly-cluster-gap: var(--ly-space-0); }
+  .ly-gap-1 { --ly-gap: var(--ly-space-1); --ly-grid-gap: var(--ly-space-1); --ly-stack-gap: var(--ly-space-1); --ly-cluster-gap: var(--ly-space-1); }
+  .ly-gap-2 { --ly-gap: var(--ly-space-2); --ly-grid-gap: var(--ly-space-2); --ly-stack-gap: var(--ly-space-2); --ly-cluster-gap: var(--ly-space-2); }
+  .ly-gap-3 { --ly-gap: var(--ly-space-3); --ly-grid-gap: var(--ly-space-3); --ly-stack-gap: var(--ly-space-3); --ly-cluster-gap: var(--ly-space-3); }
+  .ly-gap-4 { --ly-gap: var(--ly-space-4); --ly-grid-gap: var(--ly-space-4); --ly-stack-gap: var(--ly-space-4); --ly-cluster-gap: var(--ly-space-4); }
+  .ly-gap-5 { --ly-gap: var(--ly-space-5); --ly-grid-gap: var(--ly-space-5); --ly-stack-gap: var(--ly-space-5); --ly-cluster-gap: var(--ly-space-5); }
+  .ly-gap-6 { --ly-gap: var(--ly-space-6); --ly-grid-gap: var(--ly-space-6); --ly-stack-gap: var(--ly-space-6); --ly-cluster-gap: var(--ly-space-6); }
+  .ly-gap-7 { --ly-gap: var(--ly-space-7); --ly-grid-gap: var(--ly-space-7); --ly-stack-gap: var(--ly-space-7); --ly-cluster-gap: var(--ly-space-7); }
+  .ly-gap-8 { --ly-gap: var(--ly-space-8); --ly-grid-gap: var(--ly-space-8); --ly-stack-gap: var(--ly-space-8); --ly-cluster-gap: var(--ly-space-8); }
+  .ly-gap-9 { --ly-gap: var(--ly-space-9); --ly-grid-gap: var(--ly-space-9); --ly-stack-gap: var(--ly-space-9); --ly-cluster-gap: var(--ly-space-9); }
+
+  .ly-pad-0 { padding: var(--ly-space-0); }
+  .ly-pad-1 { padding: var(--ly-space-1); }
+  .ly-pad-2 { padding: var(--ly-space-2); }
+  .ly-pad-3 { padding: var(--ly-space-3); }
+  .ly-pad-4 { padding: var(--ly-space-4); }
+  .ly-pad-5 { padding: var(--ly-space-5); }
+  .ly-pad-6 { padding: var(--ly-space-6); }
+  .ly-pad-7 { padding: var(--ly-space-7); }
+  .ly-pad-8 { padding: var(--ly-space-8); }
+  .ly-pad-9 { padding: var(--ly-space-9); }
+
+  .ly-px-4 { padding-inline: var(--ly-space-4); }
+  .ly-px-6 { padding-inline: var(--ly-space-6); }
+  .ly-px-8 { padding-inline: var(--ly-space-8); }
+  .ly-py-4 { padding-block: var(--ly-space-4); }
+  .ly-py-6 { padding-block: var(--ly-space-6); }
+  .ly-py-8 { padding-block: var(--ly-space-8); }
+
+  .ly-mx-auto { margin-inline: auto; }
+  .ly-w-full { inline-size: 100%; }
+  .ly-h-full { block-size: 100%; }
+  .ly-min-h-screen { min-block-size: 100svh; }
+  .ly-bleed { inline-size: 100vw; margin-inline: calc(50% - 50vw); }
+  .ly-overflow-auto { overflow: auto; }
+  .ly-overflow-hidden { overflow: hidden; }
+
+  .ly-items-start { align-items: flex-start; }
+  .ly-items-center { align-items: center; }
+  .ly-items-end { align-items: flex-end; }
+  .ly-items-stretch { align-items: stretch; }
+  .ly-justify-start { justify-content: flex-start; }
+  .ly-justify-center { justify-content: center; }
+  .ly-justify-end { justify-content: flex-end; }
+  .ly-justify-between { justify-content: space-between; }
+
+  .ly-frame-1x1 { --ly-frame-ratio: 1 / 1; }
+  .ly-frame-2x1 { --ly-frame-ratio: 2 / 1; }
+  .ly-frame-3x2 { --ly-frame-ratio: 3 / 2; }
+  .ly-frame-4x3 { --ly-frame-ratio: 4 / 3; }
+  .ly-frame-16x9 { --ly-frame-ratio: 16 / 9; }
+  .ly-frame-21x9 { --ly-frame-ratio: 21 / 9; }
+
+  .ly-hidden { display: none !important; }
+
+  .ly-show-md-up,
+  .ly-show-lg-up {
+    display: none !important;
+  }
+
+  .ly-visually-hidden {
+    position: absolute !important;
+    inline-size: 1px !important;
+    block-size: 1px !important;
+    padding: 0 !important;
+    margin: -1px !important;
+    overflow: hidden !important;
+    clip: rect(0, 0, 0, 0) !important;
+    clip-path: inset(50%) !important;
+    white-space: nowrap !important;
+  }
+
+  /* Explicit escape hatches require consumers to verify focus and reading order. */
+  .ly-order-first { order: -1; }
+  .ly-order-normal { order: 0; }
+  .ly-order-last { order: 999; }
+  .ly-order-1 { order: 1; }
+  .ly-order-2 { order: 2; }
+  .ly-order-3 { order: 3; }
+  .ly-order-4 { order: 4; }
+  .ly-order-5 { order: 5; }
+  .ly-order-6 { order: 6; }
+
+  @container (min-width: 48rem) {
+    .ly-md-cols-1 { --ly-grid-columns: 1; }
+    .ly-md-cols-2 { --ly-grid-columns: 2; }
+    .ly-md-cols-3 { --ly-grid-columns: 3; }
+    .ly-md-cols-4 { --ly-grid-columns: 4; }
+    .ly-md-cols-6 { --ly-grid-columns: 6; }
+    .ly-md-cols-8 { --ly-grid-columns: 8; }
+    .ly-md-cols-12 { --ly-grid-columns: 12; }
+    .ly-md-cols-16 { --ly-grid-columns: 16; }
+    .ly-show-md-up { display: revert !important; }
+
+    .ly-md-order-first { order: -1; }
+    .ly-md-order-normal { order: 0; }
+    .ly-md-order-last { order: 999; }
+    .ly-md-order-1 { order: 1; }
+    .ly-md-order-2 { order: 2; }
+    .ly-md-order-3 { order: 3; }
+    .ly-md-order-4 { order: 4; }
+    .ly-md-order-5 { order: 5; }
+    .ly-md-order-6 { order: 6; }
+  }
+
+  @container (min-width: 64rem) {
+    .ly-lg-cols-1 { --ly-grid-columns: 1; }
+    .ly-lg-cols-2 { --ly-grid-columns: 2; }
+    .ly-lg-cols-3 { --ly-grid-columns: 3; }
+    .ly-lg-cols-4 { --ly-grid-columns: 4; }
+    .ly-lg-cols-6 { --ly-grid-columns: 6; }
+    .ly-lg-cols-8 { --ly-grid-columns: 8; }
+    .ly-lg-cols-12 { --ly-grid-columns: 12; }
+    .ly-lg-cols-16 { --ly-grid-columns: 16; }
+    .ly-show-lg-up { display: revert !important; }
+
+    .ly-lg-order-first { order: -1; }
+    .ly-lg-order-normal { order: 0; }
+    .ly-lg-order-last { order: 999; }
+    .ly-lg-order-1 { order: 1; }
+    .ly-lg-order-2 { order: 2; }
+    .ly-lg-order-3 { order: 3; }
+    .ly-lg-order-4 { order: 4; }
+    .ly-lg-order-5 { order: 5; }
+    .ly-lg-order-6 { order: 6; }
+  }
+}

package/dist/wrappers.css

@@ -0,0 +1,174 @@
+@layer ly.reset, ly.tokens, ly.wrappers, ly.primitives, ly.recipes, ly.utilities, ly.personalities, ly.integrations, ly.legacy;
+
+/*
+  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%;
+  }
+}
+
+@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));
+
+    /* Symmetric safe-area compensation keeps logical gutters stable in either direction. */
+    container-name: ly-wrapper;
+    container-type: inline-size;
+    inline-size: min(100%, calc(var(--ly-wrapper-max) + (var(--ly-wrapper-gutter) * 2)));
+    margin-inline: auto;
+    padding-inline: var(--ly-wrapper-gutter);
+  }
+
+  .ly-wrapper--compact {
+    --ly-wrapper-max: 40rem;
+  }
+
+  .ly-wrapper--prose {
+    --ly-wrapper-max: 68ch;
+  }
+
+  .ly-wrapper--content {
+    --ly-wrapper-max: 72rem;
+  }
+
+  .ly-wrapper--wide {
+    --ly-wrapper-max: 112rem;
+  }
+
+  .ly-wrapper--full {
+    --ly-wrapper-max: 100%;
+  }
+
+  .ly-wrapper--breakout {
+    --ly-breakout-content-size: min(
+      var(--ly-wrapper-content),
+      calc(100% - (var(--ly-wrapper-gutter) * 2))
+    );
+    --ly-breakout-feature-size: min(
+      var(--ly-wrapper-wide),
+      calc(100% - (var(--ly-wrapper-gutter) * 2))
+    );
+
+    display: grid;
+    grid-template-columns:
+      [full-start] minmax(min(100%, var(--ly-wrapper-gutter)), 1fr)
+      [feature-start] minmax(
+        0,
+        calc((var(--ly-breakout-feature-size) - var(--ly-breakout-content-size)) / 2)
+      )
+      [content-start] minmax(0, var(--ly-breakout-content-size)) [content-end]
+      minmax(
+        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];
+    inline-size: 100%;
+    padding-inline: 0;
+  }
+
+  .ly-wrapper--breakout > * {
+    grid-column: content;
+    min-inline-size: 0;
+  }
+
+  .ly-wrapper--breakout > :where(.ly-lane--content, [data-ly-lane="content"]) {
+    grid-column: content;
+  }
+
+  .ly-wrapper--breakout > :where(.ly-lane--feature, [data-ly-lane="feature"]) {
+    grid-column: feature;
+  }
+
+  .ly-wrapper--breakout > :where(.ly-lane--full, [data-ly-lane="full"]) {
+    grid-column: full;
+  }
+}

package/docs/wiki/Contributing.md

@@ -1,30 +1,36 @@
-# Contributing
-
-Contribution work should preserve the package boundary: `layout-style-css` owns structure, `ui-style-kit-css` owns visual styling.
-
-## Workflow
-
-```bash
-npm install
-npm run build
-npm run lint
-npm test
-```
-
-Use `npm run release:verify` before release-facing changes are merged.
-
-## CSS Guidelines
-
-- Keep source CSS in `styles/`.
-- Regenerate dist files with `npm run build`.
-- Prefix public layout classes with `ly-`.
-- Prefer layout variables and recipes before introducing new public classes.
-- Keep new grid tracks mobile-safe with `minmax(0, 1fr)` or guarded fixed floors.
-- Do not add colors, shadows, borders, typography, focus styling, or native control styling.
-
-## Documentation Guidelines
-
-Update README and wiki pages whenever a public export, selector, layout recipe, package file, release command, or deployment behavior changes.
-
-Update `CHANGELOG.md` for every release-facing change.
-
+# 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 below and above `48rem` and `64rem`.
+- 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

@@ -1,39 +1,53 @@
-# Demo And GitHub Pages
-
-The demo lives at `demo/index.html` and is packaged with the library. GitHub Pages deployment uses a generated root artifact so Pages can serve `index.html` from the site root.
-
-## Local Demo
-
-Run the demo through the test suite:
-
-```bash
-npm test
-```
-
-The Playwright smoke checks verify responsive behavior across mobile portrait, mobile landscape, tablet, and desktop conditions.
-
-## Pages Artifact
-
-Build the artifact:
-
-```bash
-npm run pages:build
-```
-
-The artifact is written to `output/github-pages/` and contains:
-
-- root `index.html`
-- copied assets and metadata
-- generated `dist/` CSS
-- `.nojekyll`
-
-## Repository Settings
-
-Before deployment, enable GitHub Pages in repository settings and select GitHub Actions as the source.
-
-The workflow verifies the package, builds the Pages artifact, uploads it, and deploys from `main` or `workflow_dispatch`.
-
-## Mobile Header Contract
-
-The demo header should remain compact on mobile. Controls are exposed through the drawer toggle rather than an always-expanded stack of full-width controls.
-
+# 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/`.
+
+## Local Gates
+
+The quick gate uses Chromium and a representative rendered matrix:
+
+```bash
+npm run test:demo:quick
+```
+
+Run one complete engine matrix:
+
+```bash
+npm run test:demo:chromium
+npm run test:demo:firefox
+npm run test:demo:webkit
+```
+
+Run all supported engines:
+
+```bash
+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`.
+
+## Pages Artifact
+
+```bash
+npm run pages:build
+node test/pages-artifact.test.mjs
+```
+
+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 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.

package/docs/wiki/Getting-Started.md

@@ -1,68 +1,51 @@
-# Getting Started
-
-Use `layout-style-css` when an application needs predictable page structure without duplicating a visual design system.
-
-## Install
-
-```bash
-npm install layout-style-css ui-style-kit-css@2.0.1
-```
-
-Optional Interactive Surface pairing:
-
-```bash
-npm install interactive-surface-css@1.2.5
-```
-
-## First Import
-
-Use the layout-only package entry when the app already imports UI styles:
-
-```js
-import "ui-style-kit-css/dist/ui-style-kit.css";
-import "layout-style-css";
-```
-
-Use the aggregate import when the project wants UI Style Kit and all layouts from one package entry:
-
-```js
-import "layout-style-css/all-with-ui-kit.css";
-```
-
-## First Shell
-
-```html
-<body class="ly-root" data-ui="minimal-saas" data-layout="minimal-saas" data-theme="arctic-indigo" data-mode="light">
-  <div class="ly-app-shell">
-    <aside class="ly-app-sidebar ly-pad-6">Navigation</aside>
-    <header class="ly-app-header ly-pad-4">Toolbar</header>
-    <main class="ly-app-main">
-      <section class="ly-wrapper ly-wrapper--wide ly-section ly-stack">
-        <h1>Workspace</h1>
-        <div class="ly-card-grid">
-          <article class="ly-surface ly-card-md ly-pad-6">Metric</article>
-          <article class="ly-surface ly-card-md ly-pad-6">Metric</article>
-          <article class="ly-surface ly-card-md ly-pad-6">Metric</article>
-        </div>
-      </section>
-    </main>
-  </div>
-</body>
-```
-
-## Switch Layout Personality
-
-Layout styles are selected independently from UI styles:
-
-```js
-const root = document.body;
-
-root.dataset.ui = "cyberpunk";
-root.dataset.layout = "synthwave";
-root.setAttribute("layout-style", "synthwave");
-root.dataset.theme = "cyber-lime";
-root.dataset.mode = "dark";
-```
-
-This lets a product test different spatial systems without rewriting the component paint layer.
-
+# 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.
+
+```bash
+npm install layout-style-css@2.1.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
+
+Place the recipe inside a `.ly-wrapper`. The wrapper supplies inline-size containment, fluid logical gutters, and safe-area compensation.
+
+```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>
+</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.
+
+## Switch Personality
+
+```js
+document.querySelector(".ly-root").dataset.lyLayout = "synthwave";
+```
+
+`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.
+
+## Migrate Existing Markup
+
+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.