layout-style-css 1.1.2 → 2.0.0

package/README.md

@@ -1,636 +1,231 @@
-# layout-style-css
-
-Responsive CSS layout primitives for shell-first interfaces.
-
-`layout-style-css` gives applications a small, predictable composition layer: wrappers, app shells, grids, panes, sidebars, split sections, spacing utilities, and switchable layout personalities. It is designed to pair with `ui-style-kit-css@2.0.1`, while keeping layout decisions independent from visual theme decisions.
-
-## Documentation And Wiki
-
-The versioned wiki source lives in this repository so docs can be reviewed with code changes and shipped with the npm package:
-
-| Resource | Use it for |
-| --- | --- |
-| [Wiki home](docs/wiki/Home.md) | Release overview and navigation. |
-| [Getting started](docs/wiki/Getting-Started.md) | First install, first shell, and switching layouts. |
-| [Installation and CDN](docs/wiki/Installation-And-CDN.md) | npm, bundler, CDN, and package entrypoint guidance. |
-| [Layout primitives](docs/wiki/Layout-Primitives.md) | Wrapper, shell, grid, pane, frame, and utility contracts. |
-| [Layout recipes](docs/wiki/Layout-Recipes.md) | Copyable app shell, button group, card grid, gallery, and carousel patterns. |
-| [Layout styles](docs/wiki/Layout-Styles.md) | All layout personalities, including F-Pattern, Z-Pattern, Split-Screen, Mondrian, and Synthwave. |
-| [UI Style Kit compatibility](docs/wiki/UI-Style-Kit-Compatibility.md) | Prefix aliases and the boundary between structure and visual styling. |
-| [Demo and GitHub Pages](docs/wiki/Demo-And-GitHub-Pages.md) | Demo QA, Pages artifact behavior, and deployment setup. |
-| [Release and publishing](docs/wiki/Release-And-Publishing.md) | v1.1.2 release checklist, npm verification, and tag guidance. |
-| [Security and support](docs/wiki/Security-And-Support.md) | Security model, supported versions, and reporting path. |
-| [Contributing](docs/wiki/Contributing.md) | Local development, CSS rules, and review expectations. |
-| [Wiki sidebar source](docs/wiki/_Sidebar.md) | Navigation file for a GitHub Wiki mirror. |
-| [Changelog](CHANGELOG.md) | Version history. |
-| [Project contributing guide](CONTRIBUTING.md) | Repository-level contribution workflow. |
-| [Security policy](SECURITY.md) | Repository-level security policy. |
-
-## Why It Exists
-
-Modern UI systems often mix two concerns:
-
-- visual design: color, typography, borders, shadows, native controls, focus states, and modes
-- spatial design: wrappers, page width, shell regions, pane ratios, sidebar placement, grid behavior, and responsive collapse
-
-This package owns the spatial layer only. That separation lets you change layout personality without rewriting markup or duplicating your theme system.
-
-## Install
-
-Use as a standalone layout system with all styles or just one layout personality.
-
-```bash
-# Install the full layout system
-npm install layout-style-css@1.1.2
-```
-
-Then import whichever CSS entrypoints you need:
-
-```js
-import "layout-style-css/base.css";
-import "layout-style-css/minimal-saas.css";
-```
-
-Pair with UI Style Kit CSS for a complete layout and visual system. Themes and layouts can mix and match UI styles.  Set the vibe with color schemes that offer a range of moods, from minimal to maximal, from Bauhaus to Brutalism.
-
-```bash
-npm install layout-style-css@1.1.2 ui-style-kit-css@2.0.1
-```
-
-Additionally installing Interactive Surface CSS sets you up with a complete reactive layout and surface system.
-
-```bash
-npm install layout-style-css@1.1.2 ui-style-kit-css@2.0.1 interactive-surface-css@1.2.5
-```
-
-## Quick Start
-
-Import UI Style Kit first, then the layout CSS:
-
-```js
-import "interactive-surface-css/interactive-surface.css";
-import "ui-style-kit-css/with-bridge.css";
-import "layout-style-css/bridge.css";
-```
-
-For a direct three-library setup, import each CSS entrypoint explicitly:
-
-```js
-import "ui-style-kit-css/with-bridge.css";
-import "interactive-surface-css/interactive-surface.css";
-import "layout-style-css/bridge.css";
-import "layout-style-css";
-```
-
-Use one root element for UI style, layout style, theme, and mode:
-
-```html
-<body
-  class="ly-root"
-  data-ui="retro-glass"
-  data-layout="cyberpunk"
-  data-theme="ocean-steel"
-  data-mode="auto"
->
-  <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>Dashboard</h1>
-        <div class="ly-grid ly-grid--auto">
-          <article class="ly-surface ly-pad-6">Revenue</article>
-          <article class="ly-surface ly-pad-6">Pipeline</article>
-          <article class="ly-surface ly-pad-6">Retention</article>
-        </div>
-      </section>
-    </main>
-  </div>
-</body>
-```
-
-## CDN Usage
-
-Layout-only CDN entry:
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/layout-style-css@1/dist/layout-style-css.min.css">
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/layout-style-css@1/dist/layout-style-css.min.css">
-```
-
-Recommended CDN pairing with UI Style Kit and Interactive Surface:
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/ui-style-kit-css@2.0.1/dist/ui-style-kit.with-bridge.min.css">
-<link rel="stylesheet" href="https://unpkg.com/layout-style-css@1/dist/layout-style-css.min.css">
-<link rel="stylesheet" href="https://unpkg.com/interactive-surface-css@1.2.5/dist/interactive-surface.min.css">
-```
-
-## Import Options
-
-| Import | Use case |
-| --- | --- |
-| `import "layout-style-css";` | Full flattened layout-only CSS. |
-| `import "layout-style-css/min.css";` | Minified layout-only CSS. |
-| `import "layout-style-css/all.css";` | Import-based bundle for all layout files. |
-| `import "layout-style-css/base.css";` | Base primitives only. |
-| `import "layout-style-css/minimal-saas.css";` | One layout personality; the same pattern works for every layout style export. |
-| `import "layout-style-css/all-with-ui-kit.css";` | UI Style Kit plus all layouts. |
-| `import "layout-style-css/all-with-ui-kit-and-interactive-surface.css";` | UI Style Kit, Interactive Surface, and all layouts. |
-
-The three-library aggregate imports in this order:
-
-```css
-@import url("ui-style-kit-css/with-bridge.css");
-@import url("interactive-surface-css/interactive-surface.css");
-@import url("./layout-all.css");
-```
-
-## UI Style Kit Naming Compatibility
-
-Use the aggregate import when a project wants UI Style Kit visuals and Layout Style CSS structure from one package entry:
-
-```js
-import "layout-style-css/all-with-ui-kit.css";
-```
-
-The bridge intentionally aliases structural classes and layout recipes only. UI Style Kit still owns component paint, typography, borders, shadows, native controls, focus states, themes, and modes.
-
-Supported UI-style prefixes are `saas`, `bento`, `max`, `bau`, `tactile`, `neo`, `retro`, `brutal`, `cyber`, `y2k`, and `rg`.
-
-| Alias pattern | Maps to |
-| --- | --- |
-| `<prefix>-container` | `.ly-wrapper` |
-| `<prefix>-section` | `.ly-section` |
-| `<prefix>-stack` | `.ly-stack` |
-| `<prefix>-cluster` | `.ly-cluster` |
-| `<prefix>-grid` | `.ly-grid` |
-| `<prefix>-split` | `.ly-split` |
-| `<prefix>-button-group` | `.ly-button-group` |
-| `<prefix>-card-grid` | `.ly-card-grid` |
-| `<prefix>-card-sm`, `<prefix>-card-md`, `<prefix>-card-lg` | `.ly-card-sm`, `.ly-card-md`, `.ly-card-lg` |
-| `<prefix>-gallery` | `.ly-gallery` |
-| `<prefix>-carousel` | `.ly-carousel` |
-
-Example:
-
-```html
-<section class="saas-container saas-section">
-  <div class="saas-card-grid">
-    <article class="saas-card ly-card-md">Metric</article>
-    <article class="saas-card ly-card-md">Metric</article>
-    <article class="saas-card ly-card-md">Metric</article>
-  </div>
-
-  <div class="saas-button-group">
-    <button class="saas-button">Save</button>
-    <button class="saas-button-secondary">Export</button>
-  </div>
-</section>
-```
-
-## Responsive Wrapper API
-
-Use `.ly-wrapper` for new markup. `.ly-container` remains supported for compatibility.
-
-| Class | Purpose |
-| --- | --- |
-| `.ly-wrapper` / `.ly-container` | Responsive centered content wrapper. |
-| `.ly-wrapper--sm` / `.ly-container--sm` | Small wrapper, up to `40rem`. |
-| `.ly-wrapper--md` / `.ly-container--md` | Medium wrapper, up to `56rem`. |
-| `.ly-wrapper--lg` / `.ly-container--lg` | Large wrapper, up to `72rem`. |
-| `.ly-wrapper--xl` / `.ly-container--xl` | Extra-large wrapper, up to `88rem`. |
-| `.ly-wrapper--wide` / `.ly-container--wide` | Wide wrapper, up to `112rem`. |
-| `.ly-wrapper--fluid` / `.ly-container--fluid` | Full-width wrapper with responsive inline padding. |
-| `.ly-wrapper--readable` | Readable content wrapper based on `68ch`. |
-
-Wrappers are mobile-first and tested against:
-
-- mobile portrait and landscape
-- tablet portrait and landscape
-- desktop resize behavior
-- wide desktop
-
-## Layout Recipes
-
-Recipes are recommended class combinations, not separate theme files. They keep the public API small while making common layouts easy to copy.
-
-### App Shell
-
-Use for dashboards, admin tools, and multi-region product screens.
-
-```html
-<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">Workspace</section>
-  </main>
-</div>
-```
-
-### Content Page
-
-Use for docs, articles, policy pages, and focused editorial content.
-
-```html
-<main class="ly-main">
-  <article class="ly-wrapper ly-wrapper--readable ly-section ly-stack">
-    <h1>Documentation</h1>
-    <p>Readable content stays centered and responsive.</p>
-  </article>
-</main>
-```
-
-### Dashboard Grid
-
-Use for metric cards and repeated operational surfaces.
-
-```html
-<section class="ly-wrapper ly-wrapper--wide ly-section">
-  <div class="ly-grid ly-grid--auto">
-    <article class="ly-surface ly-pad-6">Metric</article>
-    <article class="ly-surface ly-pad-6">Metric</article>
-    <article class="ly-surface ly-pad-6">Metric</article>
-  </div>
-</section>
-```
-
-### Split Hero
-
-Use when a message needs a supporting panel, preview, form, or media frame.
-
-```html
-<section class="ly-wrapper ly-wrapper--xl ly-section">
-  <div class="ly-split">
-    <div class="ly-stack">
-      <h1>Primary message</h1>
-      <p>Supporting copy.</p>
-    </div>
-    <aside class="ly-frame ly-surface ly-pad-6">Preview</aside>
-  </div>
-</section>
-```
-
-### Docs Sidebar
-
-Use for local filters, table of contents, and secondary navigation.
-
-```html
-<section class="ly-wrapper ly-wrapper--wide ly-section">
-  <div class="ly-sidebar-layout">
-    <aside class="ly-sidebar ly-surface ly-pad-5">Contents</aside>
-    <article class="ly-content ly-surface ly-pad-6">Documentation body</article>
-  </div>
-</section>
-```
-
-### List Detail
-
-Use for inboxes, editors, queues, and preview workflows.
-
-```html
-<section class="ly-wrapper ly-wrapper--wide ly-section">
-  <div class="ly-panes ly-panes--two">
-    <aside class="ly-surface ly-pad-5 ly-scroll-area">List</aside>
-    <article class="ly-surface ly-pad-6">Detail</article>
-  </div>
-</section>
-```
-
-### Button Group
-
-Use for responsive action rows that should wrap without forcing buttons to full-width.
-
-```html
-<div class="ly-button-group">
-  <button class="saas-button">Save</button>
-  <button class="saas-button-secondary">Preview</button>
-  <button class="saas-button-secondary">Export</button>
-</div>
-```
-
-### Card Grid
-
-Use for repeated cards that need a resilient auto-fit layout.
-
-```html
-<div class="ly-card-grid">
-  <article class="saas-card ly-card-md">Plan</article>
-  <article class="saas-card ly-card-md">Plan</article>
-  <article class="saas-card ly-card-md">Plan</article>
-</div>
-```
-
-The same structure can use UI-prefix aliases such as `.saas-card-grid`:
-
-```html
-<div class="saas-card-grid">
-  <article class="saas-card saas-card-md">Plan</article>
-  <article class="saas-card saas-card-md">Plan</article>
-</div>
-```
-
-### Card Size
-
-Use card size helpers when a repeated surface needs consistent minimum block sizing.
-
-```html
-<article class="ly-surface ly-card-sm">Compact card</article>
-<article class="ly-surface ly-card-md">Standard card</article>
-<article class="ly-surface ly-card-lg">Feature card</article>
-```
-
-### Gallery
-
-Use for responsive media or object grids. Pair it with `.ly-frame` to keep ratios stable.
-
-```html
-<div class="ly-gallery">
-  <figure class="ly-frame ly-frame-4x3">Media</figure>
-  <figure class="ly-frame ly-frame-4x3">Media</figure>
-  <figure class="ly-frame ly-frame-4x3">Media</figure>
-</div>
-```
-
-### Carousel
-
-Use for horizontal groups that need scroll snapping without adding visual chrome.
-
-```html
-<div class="ly-carousel">
-  <article class="ly-surface ly-card-md">Step one</article>
-  <article class="ly-surface ly-card-md">Step two</article>
-  <article class="ly-surface ly-card-md">Step three</article>
-</div>
-```
-
-### Frame And Scroll
-
-Use frames for predictable media ratios and scroll areas for bounded panes.
-
-```html
-<div class="ly-frame ly-frame-16x9">Preview</div>
-<aside class="ly-scroll-area ly-overflow-auto">Scrollable content</aside>
-```
-
-## Base Primitives
-
-| Class | Purpose |
-| --- | --- |
-| `.ly-root` | Scope root for layout variables and resets. |
-| `.ly-page` | Full-height page wrapper. |
-| `.ly-header`, `.ly-footer`, `.ly-main` | Basic document regions. |
-| `.ly-wrapper`, `.ly-container` | Responsive content wrappers. |
-| `.ly-section` | Vertical section spacing. |
-| `.ly-stack` | Vertical rhythm. |
-| `.ly-cluster` | Wrapping horizontal group. |
-| `.ly-grid` | CSS Grid foundation. |
-| `.ly-grid--auto` | Responsive auto-fit grid. |
-| `.ly-button-group` | Wrapping action group with stable child sizing. |
-| `.ly-card-grid` | Auto-fit card grid recipe. |
-| `.ly-card-sm`, `.ly-card-md`, `.ly-card-lg` | Consistent minimum card block sizes. |
-| `.ly-gallery` | Responsive gallery grid recipe. |
-| `.ly-carousel` | Horizontal scroll-snap recipe. |
-| `.ly-row`, `.ly-col`, `.ly-col-*` | Flex row and column utilities. |
-| `.ly-app-shell` | Header/sidebar/main shell. |
-| `.ly-app-header`, `.ly-app-sidebar`, `.ly-app-main` | App shell regions. |
-| `.ly-sidebar-layout` | Local content/sidebar layout. |
-| `.ly-split` | Responsive two-part split. |
-| `.ly-panes`, `.ly-panes--two`, `.ly-panes--three` | Adaptive pane layouts. |
-| `.ly-surface` | Layout wrapper surface; paint remains owned by the UI system. |
-| `.ly-frame` | Aspect-ratio media or content frame. |
-
-## Utility API
-
-Utilities are composition-only. They set layout variables, spacing, flow, visibility, overflow, or frame ratios without introducing colors, fonts, shadows, borders, or theme-specific visuals.
-
-### Grid Columns And Spans
-
-| Class group | Purpose |
-| --- | --- |
-| `.ly-cols-1` through `.ly-cols-12`, `.ly-cols-16` | Set the base grid column count. |
-| `.ly-md-cols-{1,2,3,4,6,8,12,16}` | Change grid column count from the tablet breakpoint up. |
-| `.ly-lg-cols-{1,2,3,4,6,8,12,16}` | Change grid column count from the desktop breakpoint up. |
-| `.ly-span-1` through `.ly-span-16` | Span a grid item across a fixed number of tracks. |
-| `.ly-span-full` | Span a grid item across the full grid. |
-
-### Flex Columns
-
-| Class group | Purpose |
-| --- | --- |
-| `.ly-row` | Flex row with wrapped columns and negative gutter compensation. |
-| `.ly-col` | Flexible column that shares available space. |
-| `.ly-col-1` through `.ly-col-12` | Percentage-based column widths on the 12-column scale. |
-
-### Spacing
-
-| Class group | Purpose |
-| --- | --- |
-| `.ly-gap-0` through `.ly-gap-9` | Set shared layout, grid, stack, and cluster gaps. |
-| `.ly-pad-0` through `.ly-pad-9` | Set all-side padding from the layout spacing scale. |
-| `.ly-px-4`, `.ly-px-6`, `.ly-px-8` | Set inline padding. |
-| `.ly-py-4`, `.ly-py-6`, `.ly-py-8` | Set block padding. |
-| `.ly-mx-auto` | Center with automatic inline margins. |
-
-### Sizing, Overflow, And Alignment
-
-| Class group | Purpose |
-| --- | --- |
-| `.ly-w-full`, `.ly-h-full` | Force full inline or block size. |
-| `.ly-min-h-screen` | Set minimum viewport-height section sizing with `100svh`. |
-| `.ly-bleed` | Break a section out to viewport width. |
-| `.ly-overflow-auto`, `.ly-overflow-hidden` | Control overflow behavior. |
-| `.ly-items-start`, `.ly-items-center`, `.ly-items-end`, `.ly-items-stretch` | Align children on the cross axis. |
-| `.ly-justify-start`, `.ly-justify-center`, `.ly-justify-end`, `.ly-justify-between` | Distribute children on the main axis. |
-
-### Frames And Visibility
-
-| Class group | Purpose |
-| --- | --- |
-| `.ly-frame-1x1`, `.ly-frame-2x1`, `.ly-frame-3x2`, `.ly-frame-4x3`, `.ly-frame-16x9`, `.ly-frame-21x9` | Set common media/content aspect ratios. |
-| `.ly-hidden` | Hide an element. |
-| `.ly-show-md-up` | Reveal an element from the tablet breakpoint up. |
-| `.ly-show-lg-up` | Reveal an element from the desktop breakpoint up. |
-| `.ly-visually-hidden` | Hide content visually while keeping it available to assistive technology. |
-
-## Layout Styles
-
-Each layout style file targets layout selectors only. It does not key off `data-ui`, so `data-ui="cyberpunk"` can pair with `data-layout="maximalist"` without forcing a cyberpunk shell.
-
-| Layout style | File | Shell behavior |
-| --- | --- | --- |
-| `minimal-saas` | `layout-style-minimal-saas.css` | Steady left-rail SaaS shell with compact content bands and predictable pane ratios. |
-| `bento` | `layout-style-bento.css` | Modular dashboard shell with staged mosaic zones, dense grids, and tile-like support panels. |
-| `maximalist` | `layout-style-maximalist.css` | Editorial shell with oversized hero splits, offset support rails, and staggered regions. |
-| `bauhaus` | `layout-style-bauhaus.css` | Strict framed column shell with visible structural rails, square surfaces, and modular panes. |
-| `tactile` | `layout-style-tactile.css` | Instrument-panel shell with a heavier support dock, control-deck panes, and chunky spacing. |
-| `neumorphism` | `layout-style-neumorphism.css` | Centered island shell with detached support regions and roomy split composition. |
-| `retrofuturism` | `layout-style-retrofuturism.css` | Panoramic bridge shell with wide stages, symmetric pods, and horizontal workspace flow. |
-| `brutalism` | `layout-style-brutalism.css` | Full-bleed slab shell with hard sectional breaks, abrupt pane cuts, and raw support rails. |
-| `cyberpunk` | `layout-style-cyberpunk.css` | Narrow utility rail with dense command workspace, compact gutters, and clipped panels. |
-| `y2k` | `layout-style-y2k.css` | Centered hub shell with floating window rhythm and dock-like support regions. |
-| `retro-glass` | `layout-style-retro-glass.css` | Top-framed glass shell with a floating right utility rail and layered panes. |
-| `f-pattern` | `layout-style-f-pattern.css` | F-Pattern scan path with a top band, persistent left rail, and heavier early content rows. |
-| `z-pattern` | `layout-style-z-pattern.css` | Z-Pattern scan path that leads from a broad header into primary content and a right support rail. |
-| `split-screen` | `layout-style-split-screen.css` | Split-Screen shell that gives main and support regions equal competing weight. |
-| `mondrian` | `layout-style-mondrian.css` | Mondrian block composition with asymmetrical rectangular spans and compact gaps. |
-| `synthwave` | `layout-style-synthwave.css` | Synthwave stage composition with wide cinematic content, dock-like support areas, and horizontal preview rhythm. |
-
-## Mix And Match Contract
-
-Matching UI and layout names are good defaults:
-
-```html
-data-ui="bento" data-layout="bento"
-```
-
-Mixed combinations are supported:
-
-```html
-data-ui="cyberpunk" data-layout="maximalist" data-theme="arctic-indigo" data-mode="dark"
-data-ui="bauhaus" data-layout="retro-glass" data-theme="graphite-cyan" data-mode="dark"
-data-ui="minimal-saas" data-layout="bento" data-theme="ocean-steel" data-mode="light"
-data-ui="brutalism" data-layout="cyberpunk" data-theme="midnight-gold" data-mode="contrast"
-data-ui="cyberpunk" data-layout="synthwave" data-theme="cyber-lime" data-mode="dark"
-data-ui="bauhaus" data-layout="mondrian" data-theme="graphite-cyan" data-mode="contrast"
-```
-
-Supported layout selectors:
-
-```html
-data-layout="maximalist"
-layout-style="maximalist"
-class="ly-layout-maximalist"
-class="ly-style-maximalist"
-```
-
-Runtime switching:
-
-```js
-const root = document.body;
-
-root.dataset.ui = "cyberpunk";
-root.dataset.layout = "maximalist";
-root.setAttribute("layout-style", "maximalist");
-root.dataset.theme = "arctic-indigo";
-root.dataset.mode = "dark";
-```
-
-## Demo And GitHub Pages
-
-The demo lives in `demo/index.html` for local development and package distribution.
-
-Build the GitHub Pages artifact:
-
-```bash
-npm run pages:build
-```
-
-The artifact is written to `output/github-pages/` and contains:
-
-- `index.html` at the Pages root
-- copied demo assets and metadata
-- generated `dist/` CSS
-- `.nojekyll`
-
-Before the workflow can deploy, enable GitHub Pages in repository Settings > Pages and set the source to GitHub Actions.
-
-The repository includes a GitHub Actions workflow that verifies the package, builds the artifact, uploads it, and deploys it to GitHub Pages from `main` or `workflow_dispatch`.
-
-## Package Files
-
-```txt
-styles/
-  layout-base.css
-  layout-ui-style-kit-bridge.css
-  layout-style-*.css
-dist/
-  layout-style-css.css
-  layout-style-css.min.css
-  layout-all.css
-  layout-all-with-ui-kit.css
-  layout-all-with-ui-kit-and-interactive-surface.css
-  layout-base.css
-  layout-ui-style-kit-bridge.css
-  layout-style-*.css
-demo/
-  index.html
-  assets/
-scripts/
-  build.mjs
-  build-pages.mjs
-docs/wiki/
-  Home.md
-  *.md
-CHANGELOG.md
-CONTRIBUTING.md
-SECURITY.md
-```
-
-`styles/` is the authored source. `dist/` and `output/github-pages/` are generated.
-
-## Development
-
-```bash
-npm install
-npm run build
-npm run lint
-npm test
-```
-
-Run the complete release gate:
-
-```bash
-npm run check
-```
-
-The check command builds `dist/`, runs Stylelint, runs contract tests, runs responsive Playwright smoke checks against `demo/index.html`, validates the GitHub Pages artifact, and performs an npm pack dry-run.
-
-## Publishing
-
-Before publishing:
-
-```bash
-npm view layout-style-css@1.1.2 version --json
-npm run release:verify
-npm audit --audit-level=moderate
-```
-
-Publish and verify:
-
-```bash
-npm login
-npm publish --access public
-npm view layout-style-css@1.1.2
-```
-
-After publish, verify these CDN URLs:
-
-```txt
-https://unpkg.com/layout-style-css@1/dist/layout-style-css.min.css
-https://cdn.jsdelivr.net/npm/layout-style-css@1/dist/layout-style-css.min.css
-```
-
-Tag the release as `v1.1.2` in `Foscat/layout-style-css`. The npm publish workflow runs when that release is published and can be recovered manually from Actions with `release_tag` set to `v1.1.2`.
-
-## Compatibility
-
-- `ui-style-kit-css`: pinned peer at `2.0.1`
-- `interactive-surface-css`: optional peer at `1.2.5`
-- default npm and CDN entries: layout-only
-
-## Extension Rules
-
-1. Keep public layout classes prefixed with `ly-`.
-2. Let `ui-style-kit-css` own colors, native controls, component look, focus states, typography, borders, shadows, and modes.
-3. Put shared composition behavior in `styles/layout-base.css`.
-4. Put layout-style-specific shell behavior in the matching `styles/layout-style-*.css` file.
-5. Prefer changing layout variables before adding new public classes.
-6. Treat recipes as documentation and demo patterns unless a repeated production need justifies a new class.
-7. Test mobile portrait, mobile landscape, tablet portrait, tablet landscape, desktop resize, and wide desktop before promoting a new layout pattern.
-
-## References
-
-- UI Style Kit CSS: https://github.com/Foscat/ui-style-kit-css
-- Interactive Surface CSS: https://github.com/Foscat/Interactive-Surface-CSS/
+# layout-style-css
+
+Container-first, dependency-free structural CSS for responsive application layouts.
+
+`layout-style-css@2.0.0` provides semantic wrappers, composition primitives, seven functional recipes, ordering escape hatches, and sixteen spatial personalities. It owns layout only; color, typography, borders, shadows, component paint, and interactive states belong to other libraries.
+
+## Requirements
+
+- Node.js 20 or newer for development and package scripts
+- Current evergreen Chromium, Firefox, or WebKit for consumers
+- No runtime or peer dependencies
+
+`ui-style-kit-css@2.0.1` and `interactive-surface-css@1.4.0` are exact development and integration fixtures. They are not installed for consumers. A separate UI Style Kit revision is a follow-up and is not part of this release.
+
+## Install
+
+```bash
+npm install layout-style-css@2.0.0
+```
+
+Standalone use needs one import:
+
+```js
+import "layout-style-css";
+```
+
+The default and minified bundles contain the v2 core plus all personalities. Import focused modules when an application needs a smaller surface.
+
+## Ecosystem Imports
+
+Layout Style never imports companion packages. Install and import each layer explicitly.
+
+Layout plus UI Style Kit:
+
+```js
+import "ui-style-kit-css/with-bridge.css";
+import "layout-style-css/integrations/ui-style-kit.css";
+import "layout-style-css";
+```
+
+Layout plus UI Style Kit and Interactive Surface must use this order:
+
+```js
+import "ui-style-kit-css/with-bridge.css";
+import "interactive-surface-css/state-core.css";
+import "layout-style-css/integrations/ui-style-kit.css";
+import "layout-style-css";
+```
+
+The UI Style Kit bridge establishes its visual tokens, Interactive Surface contributes interaction states, the Layout integration maps structural UI aliases, and Layout core applies spatial behavior.
+
+## Public Exports
+
+| Import | Contents |
+| --- | --- |
+| `layout-style-css` | Full v2 core plus all personalities. |
+| `layout-style-css/min.css` | Minified full v2 bundle. |
+| `layout-style-css/core.css` | Wrappers, primitives, recipes, and utilities. |
+| `layout-style-css/wrappers.css` | Tokens, reset, and semantic wrappers. |
+| `layout-style-css/primitives.css` | Composition primitives. |
+| `layout-style-css/recipes.css` | Seven named responsive recipes. |
+| `layout-style-css/utilities.css` | Structural utilities and ordering escape hatches. |
+| `layout-style-css/personalities.css` | All sixteen personalities. |
+| `layout-style-css/personalities/minimal-saas.css` | One personality; substitute any public personality name. |
+| `layout-style-css/integrations/ui-style-kit.css` | Import-free structural bridge for UI Style Kit names. |
+| `layout-style-css/legacy.css` | Full v2 bundle plus v1 compatibility aliases. |
+
+The old root-level personality files and `all-with-ui-kit*` aggregates were removed. See [Migrating To 2.0](docs/wiki/Migrating-To-2.0.md) for exact mappings.
+
+## Container-First Wrappers
+
+Every `.ly-wrapper` has fluid logical gutters, safe-area compensation, and `container-type: inline-size`. The default is the `72rem` content measure. Personalities may change only the plain-wrapper default; an explicit semantic wrapper variant always retains its documented measure.
+
+| Wrapper | Measure |
+| --- | --- |
+| `.ly-wrapper--compact` | `40rem` |
+| `.ly-wrapper--prose` | `68ch` |
+| `.ly-wrapper--content` | `72rem` and the default |
+| `.ly-wrapper--wide` | `112rem` |
+| `.ly-wrapper--full` | Full available inline size |
+| `.ly-wrapper--breakout` | Content, feature, and full-width grid lanes |
+
+```html
+<main class="ly-wrapper ly-wrapper--breakout">
+  <article data-ly-lane="content">Readable content</article>
+  <figure data-ly-lane="feature">Feature media</figure>
+  <section data-ly-lane="full">Full-width stage</section>
+</main>
+```
+
+Wrappers and recipe roots respond to the nearest container. The mobile single-column fallback is authoritative; core recipes and primitives enhance at the `48rem` and `64rem` core thresholds, not viewport widths. Personalities may introduce personality-specific thresholds to create a distinct spatial rhythm while preserving source order.
+
+## Recipes And Areas
+
+Use `data-ly-recipe` as the semantic public hook. Each value is independently functional without a matching class; matching classes remain available as an equivalent direct-composition API.
+
+- `app-shell`
+- `dashboard`
+- `docs`
+- `list-detail`
+- `split-hero`
+- `gallery`
+- `card-grid`
+
+Named regions use `data-ly-area`: `header`, `nav`, `main`, `aside`, `footer`, `content`, `media`, `actions`, `primary`, and `secondary`.
+
+```html
+<section class="ly-wrapper ly-wrapper--wide">
+  <div 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">Primary workspace</main>
+    <aside data-ly-area="aside">Supporting details</aside>
+    <footer data-ly-area="footer">Status</footer>
+  </div>
+</section>
+```
+
+Keep markup in the correct mobile DOM, reading, and focus order. Built-in recipes rearrange named grid areas at wider container sizes and never use CSS `order`.
+
+## Composition Primitives
+
+The v2 composition layer includes:
+
+| Primitive | Purpose |
+| --- | --- |
+| `.ly-stack`, `.ly-cluster`, `.ly-center`, `.ly-cover` | Flow, grouping, centering, and full-height composition. |
+| `.ly-switcher`, `.ly-sidebar`, `.ly-grid`, `.ly-split` | Adaptive multi-item layouts. |
+| `.ly-panes`, `.ly-media` | Workspaces and media-object arrangements. |
+| `.ly-reel`, `.ly-frame`, `.ly-scroll` | Horizontal flow, stable ratios, and bounded scrolling. |
+
+All primitives are structural. Pair them with a paint library or application CSS for visuals.
+
+## Layout Personalities
+
+Set one canonical `data-ly-layout` value on `.ly-root`:
+
+```html
+<body class="ly-root" data-ly-layout="synthwave">
+  <!-- recipes and primitives -->
+</body>
+```
+
+| Family | Personalities |
+| --- | --- |
+| Left-rail applications | Minimal SaaS, Bauhaus, Tactile, Cyberpunk, F-Pattern |
+| Right-rail workspaces | Brutalism, Neumorphism, Y2K, Retro Glass, Z-Pattern |
+| Three-zone layouts | Retrofuturism, Mondrian, Synthwave |
+| Full-width mosaics | Bento, Maximalist |
+| Equal split | Split Screen |
+
+Each personality changes at least two spatial characteristics while leaving UI paint and DOM order unchanged.
+
+## Ordering Utilities And Accessibility
+
+The base, `ly-md-*`, and `ly-lg-*` families expose `order-first`, `order-normal`, `order-last`, and numeric order `1` through `6`. For example: `.ly-order-first`, `.ly-md-order-3`, and `.ly-lg-order-last`.
+
+These are escape hatches. Visual reordering can diverge from screen-reader reading order and keyboard focus order. Prefer correct source order plus recipe named areas; verify assistive-technology and keyboard behavior whenever an order utility is used. Built-in recipes never use order utilities.
+
+## UI Style Kit Naming Compatibility
+
+Import `layout-style-css/integrations/ui-style-kit.css` after the UI and interaction layers. The bridge maps structural aliases such as `.saas-container`, `.bento-grid`, and `.cyber-split` without importing packages or redefining visual tokens.
+
+Supported UI prefixes are `saas`, `bento`, `max`, `bau`, `tactile`, `neo`, `retro`, `brutal`, `cyber`, `y2k`, and `rg`.
+
+## Legacy Compatibility
+
+Applications that cannot migrate all selectors at once may temporarily use:
+
+```js
+import "layout-style-css/legacy.css";
+```
+
+This one import includes the full v2 bundle and aliases for v1 containers, size names, root personality hooks, columns, carousel, button group, sidebar, pane, card, scroll recipes, `.ly-content` shrink safety, and structural `.ly-divider` spacing. It is supported for the v2 line only, with removal in v3. New code should use canonical v2 exports and hooks.
+
+The v1 `.ly-surface--raised` selector is intentionally removed, including from `legacy.css`: raised radius, border, background, and shadow treatment belongs to UI Style Kit or application theme styling. See [Migrating To 2.0](docs/wiki/Migrating-To-2.0.md) for the complete selector mapping.
+
+## CDN
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/layout-style-css@2.0.0/dist/layout-style-css.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/layout-style-css@2.0.0/dist/layout-style-css.min.css">
+```
+
+Companion CDN styles must appear in the same order as the package imports: UI Style Kit bridge, Interactive Surface `state-core.css`, Layout integration bridge, then Layout core.
+
+## Development And Verification
+
+```bash
+npm ci
+npm run build
+npm run lint
+npm run check:demo-js
+npm run test:demo:quick
+npm test
+```
+
+`npm test` is the local Chromium gate. `npm run test:demo:all` runs Chromium, Firefox, and WebKit. `npm run release:verify` runs the full build, lint, static, Pages, cross-browser, tarball, `npm audit --audit-level=moderate`, and publish-dry-run checks. It does not publish.
+
+## Documentation And Wiki
+
+| Resource | Purpose |
+| --- | --- |
+| [Wiki home](docs/wiki/Home.md) | Versioned documentation navigation. |
+| [Getting Started](docs/wiki/Getting-Started.md) | First v2 wrapper and recipe. |
+| [Installation And CDN](docs/wiki/Installation-And-CDN.md) | Exact exports and import order. |
+| [Layout Primitives](docs/wiki/Layout-Primitives.md) | Wrapper and composition contracts. |
+| [Layout Recipes](docs/wiki/Layout-Recipes.md) | Recipe and area markup. |
+| [Layout Styles](docs/wiki/Layout-Styles.md) | Sixteen personality families. |
+| [UI Style Kit Compatibility](docs/wiki/UI-Style-Kit-Compatibility.md) | Ownership and bridge rules. |
+| [Migrating To 2.0](docs/wiki/Migrating-To-2.0.md) | Complete 1.x-to-2.0 mapping. |
+| [Demo And GitHub Pages](docs/wiki/Demo-And-GitHub-Pages.md) | Rendered QA and Pages artifact. |
+| [Release And Publishing](docs/wiki/Release-And-Publishing.md) | Local verification and separately approved release steps. |
+| [Security And Support](docs/wiki/Security-And-Support.md) | Supported versions and reporting. |
+| [Contributing](docs/wiki/Contributing.md) | Source, generated output, and review rules. |
+| [Wiki sidebar source](docs/wiki/_Sidebar.md) | Navigation source for a GitHub Wiki mirror. |
+| [Changelog](CHANGELOG.md) | Release history. |
+| [Repository contributing guide](CONTRIBUTING.md) | Contribution workflow. |
+| [Security policy](SECURITY.md) | Security policy. |
+
+## Ownership Boundary
+
+- `layout-style-css` owns wrappers, flow, grids, areas, measures, spans, containment, and structural responsiveness.
+- `ui-style-kit-css` owns theme and component paint.
+- `interactive-surface-css` owns interaction-state styling.
+
+Authored CSS lives in `styles/`; `dist/` is generated. Keep public layout classes prefixed with `ly-`, add tests before changing contracts, and never edit generated CSS directly.
+
+## License
+
+MIT