layout-style-css 3.0.0 → 3.0.2

package/docs/wiki/Migrating-To-2.0.md

@@ -0,0 +1,186 @@
+# Migrating To 2.0
+
+Version 2.0 rebuilds Layout Style CSS as a container-first, dependency-free structural layout system. This guide maps the complete 1.x public surface to v2 and identifies the compatibility window.
+
+## Runtime And Tooling Contract
+
+- Development and release scripts require Node.js 20 or newer.
+- The package has no runtime dependencies and no peer dependencies.
+- `ui-style-kit-css@2.1.0` and `interactive-surface-css@1.5.0` are released registry fixtures; neither is a consumer dependency.
+- Current evergreen Chromium, Firefox, and WebKit are supported.
+- Responsive recipes use core thresholds at `48rem` and `64rem`; personalities may add personality-specific thresholds.
+
+Install companions explicitly only when the application uses them:
+
+```bash
+npm install layout-style-css@2.1.1
+npm install ui-style-kit-css@2.1.0 interactive-surface-css@1.5.0
+```
+
+Layout Style CSS 2.1 keeps the v2 layout contract and updates the optional companion fixture path to UI Style Kit visual CSS, its Interactive Surface token bridge, and Interactive Surface 1.5 state core.
+
+## Export Changes
+
+The v2 package exports are focused and companion-free:
+
+| V2 import | Purpose |
+| --- | --- |
+| `layout-style-css` | Default full bundle: core plus all personalities. |
+| `layout-style-css/min.css` | Minified full bundle. |
+| `layout-style-css/core.css` | Wrappers, primitives, recipes, and utilities. |
+| `layout-style-css/wrappers.css` | Tokens, reset, safe-area gutters, and wrappers. |
+| `layout-style-css/primitives.css` | Composition primitives. |
+| `layout-style-css/recipes.css` | Functional recipes and named areas. |
+| `layout-style-css/utilities.css` | Structural and order utilities. |
+| `layout-style-css/personalities.css` | All personalities. |
+| `layout-style-css/personalities/minimal-saas.css` | One personality; replace the filename with any of the sixteen names. |
+| `layout-style-css/integrations/ui-style-kit.css` | Import-free UI Style Kit structural bridge. |
+| `layout-style-css/legacy.css` | Full v2 bundle plus v1 selector aliases. |
+
+The following v1 exports were removed from the default contract:
+
+- `layout-style-css/base.css` and the old `layout-base.css` dist file
+- `layout-style-css/bridge.css` and `layout-ui-style-kit-bridge.css`
+- `layout-style-css/all.css`
+- `layout-style-css/all-with-ui-kit.css`
+- `layout-style-css/all-with-ui-kit-and-interactive-surface.css`
+- duplicated root personality exports such as `layout-style-css/minimal-saas.css`
+- root dist files named `layout-style-*.css`
+
+Replace a root personality import with its `personalities/` path. Replace old aggregates with explicit companion imports and the v2 default or focused core.
+
+## Import Recipes
+
+Standalone Layout Style CSS:
+
+```js
+import "layout-style-css";
+```
+
+Layout plus UI Style Kit:
+
+```js
+import "ui-style-kit-css/visual.css";
+import "layout-style-css/integrations/ui-style-kit.css";
+import "layout-style-css";
+```
+
+All three libraries must be imported in this exact order:
+
+```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";
+```
+
+The first layer supplies UI paint, the second interaction states, the third structural name mappings, and the fourth the layout system. The Layout integration file contains no package imports.
+
+## Wrapper Mapping
+
+V2 wrapper names communicate intent rather than a generic size tier. `.ly-wrapper` now defaults to the `72rem` content measure and establishes an inline-size container. A personality may change that plain-wrapper default, but an explicit compact, prose, content, wide, full, or breakout variant always wins.
+
+| 1.x selector | V2 selector | V2 measure or behavior |
+| --- | --- | --- |
+| `.ly-container`, `.ly-wrapper` | `.ly-wrapper` or `.ly-wrapper--content` | Default `72rem` content wrapper |
+| `.ly-container--sm`, `.ly-wrapper--sm` | `.ly-wrapper--compact` | `40rem` |
+| `.ly-container--md`, `.ly-wrapper--md` | Local `--ly-wrapper-max: 56rem` override, or temporary `legacy.css` | No canonical v2 tier |
+| `.ly-wrapper--readable` | `.ly-wrapper--prose` | `68ch` |
+| `.ly-container--lg`, `.ly-wrapper--lg` | `.ly-wrapper--content` | `72rem` |
+| `.ly-container--xl`, `.ly-wrapper--xl` | `.ly-wrapper--wide` | `112rem` in the new semantic scale |
+| `.ly-container--wide`, `.ly-wrapper--wide` | `.ly-wrapper--wide` | `112rem` |
+| `.ly-container--fluid`, `.ly-wrapper--fluid` | `.ly-wrapper--full` | Full available width with safe-area gutters |
+| No v1 equivalent | `.ly-wrapper--breakout` | Content, feature, and full-width lanes |
+
+The v1 medium `56rem` and extra-large `88rem` measures do not have canonical v2 names. Use a local `--ly-wrapper-max` override if those exact measures are product requirements, or load `legacy.css` while migrating.
+
+Breakout markup defaults to the content lane:
+
+```html
+<div class="ly-wrapper ly-wrapper--breakout">
+  <article data-ly-lane="content">Article</article>
+  <figure data-ly-lane="feature">Feature media</figure>
+  <section data-ly-lane="full">Full-width stage</section>
+</div>
+```
+
+Every wrapper uses fluid logical gutters and safe-area insets. Test the containing element around the `48rem` and `64rem` core thresholds and around any selected personality threshold; viewport width alone no longer determines layout changes.
+
+## Canonical Hooks
+
+V2 standardizes three attributes:
+
+- `data-ly-layout` selects one of the sixteen personalities.
+- `data-ly-recipe` identifies `app-shell`, `dashboard`, `docs`, `list-detail`, `split-hero`, `gallery`, or `card-grid`.
+- `data-ly-area` identifies `header`, `nav`, `main`, `aside`, `footer`, `content`, `media`, `actions`, `primary`, or `secondary`.
+
+Every `data-ly-recipe` value is a complete alternative to its matching recipe class. For example, `data-ly-recipe="dashboard"` works without `.ly-dashboard`; applications may keep the class API, use the attribute API, or include both during migration.
+
+```html
+<body class="ly-root" data-ly-layout="minimal-saas">
+  <div class="ly-dashboard" data-ly-recipe="dashboard">
+    <header data-ly-area="header">Header</header>
+    <nav data-ly-area="nav">Navigation</nav>
+    <main data-ly-area="main">Main</main>
+    <aside data-ly-area="aside">Aside</aside>
+    <footer data-ly-area="footer">Footer</footer>
+  </div>
+</body>
+```
+
+The v1 personality hooks `data-layout`, `layout-style`, `.ly-layout-*`, and `.ly-style-*` are legacy-only. Move the personality value to `data-ly-layout` on `.ly-root`.
+
+## Primitive And Recipe Mapping
+
+The v2 composition set is stack, cluster, center, cover, switcher, sidebar, grid, split, panes, media, reel, frame, and bounded scroll.
+
+| 1.x API | V2 API |
+| --- | --- |
+| `.ly-row` plus `.ly-col-*` | `.ly-grid` plus `.ly-cols-*` and `.ly-span-*`, or `.ly-cluster` for wrapping flow |
+| `.ly-carousel` | `.ly-reel` |
+| `.ly-scroll-area` | `.ly-scroll` |
+| `.ly-sidebar-layout` | `.ly-sidebar` or the `docs` recipe |
+| `.ly-panes--two` | `.ly-panes--2` |
+| `.ly-panes--three` | `.ly-panes--3` |
+| Ad hoc shell class combinations | A matching `data-ly-recipe` root with named `data-ly-area` children |
+| `.ly-button-group` | `.ly-cluster` |
+| `.ly-card-grid` | `data-ly-recipe="card-grid"` or `.ly-card-grid` |
+| `.ly-gallery` | `data-ly-recipe="gallery"` or `.ly-gallery` |
+| `.ly-content` | V2 primitives and recipe areas already apply shrink safety; `legacy.css` preserves the structural `min-inline-size: 0` alias for ad hoc v1 content regions. |
+| `.ly-divider` | Replace spacing with a stack gap or spacing utility and source the visual divider from UI Style Kit or the application theme. `legacy.css` preserves only its `1px` minimum block geometry and block spacing, never paint. |
+| `.ly-surface--raised` | Removed. Raised radius, border, background, and shadow treatment belongs to UI Style Kit or application theme styling, so `legacy.css` intentionally does not restore this selector. |
+
+The v1 column, carousel, button-group, sidebar, pane, card-size, app-area, scroll, content, and structural divider aliases remain functional only through `legacy.css`. The paint-owned `.ly-surface--raised` API is removed rather than aliased.
+
+## Mobile Order And Accessibility
+
+DOM order is authoritative on mobile and must match the intended reading order and focus order. Built-in recipes never use CSS `order`; they rearrange named grid areas at wider containers without changing source order.
+
+V2 provides `.ly-order-first`, `.ly-order-normal`, `.ly-order-last`, and `.ly-order-1` through `.ly-order-6`. Equivalent `ly-md-order-*` and `ly-lg-order-*` utilities activate at the `48rem` and `64rem` container thresholds.
+
+These utilities are explicit escape hatches. They can make visual order disagree with assistive-technology reading order or keyboard focus order. Prefer semantic source order. When an escape hatch is unavoidable, test the complete keyboard sequence, screen-reader reading order, and mobile fallback.
+
+## Temporary Legacy Bundle
+
+Use one import during an incremental migration:
+
+```js
+import "layout-style-css/legacy.css";
+```
+
+`legacy.css` imports the full v2 bundle and adds functional aliases for old wrapper names, root hooks, layout aliases, 12-column utilities, carousel, button groups, sidebar layouts, pane names, card sizing, app regions, scroll areas, `.ly-content`, and structural `.ly-divider` geometry. It does not restore `.ly-surface--raised`, companion imports, or removed package exports.
+
+Legacy compatibility is supported for the v2 line only and is scheduled for removal in v3. Treat it as a transition tool: migrate markup and imports before upgrading to the next major version.
+
+## Migration Checklist
+
+1. Upgrade the development runtime to Node.js 20 or newer.
+2. Remove companion packages from peer assumptions and install only the layers the application uses.
+3. Replace removed aggregate and root personality imports with focused v2 exports.
+4. Change wrapper size names to semantic wrapper names.
+5. Move personality selection to `data-ly-layout`.
+6. Add `data-ly-recipe` and `data-ly-area` hooks while preserving correct mobile source order.
+7. Replace v1 column and recipe aliases, or temporarily switch to `legacy.css`.
+8. Audit every base, `ly-md-*`, and `ly-lg-*` order utility for reading and focus-order impact.
+9. Test below and above both core container thresholds and the selected personality threshold in Chromium, Firefox, and WebKit.
+10. Remove `legacy.css` before the v3 upgrade.

package/docs/wiki/Migrating-To-3.0.md

@@ -0,0 +1,205 @@
+# Migrating To 3.0
+
+`layout-style-css@3.0.0` is an intentional clean break from v2. There is no compatibility bundle. Migrate markup and imports before upgrading the package.
+
+## Package Imports
+
+| Removed v2 surface | v3 replacement |
+| --- | --- |
+| `layout-style-css/legacy.css` | Canonical v3 hooks; `legacy.css` is not shipped |
+| `layout-style-css/integrations/ui-style-kit.css` | Import UI Style Kit paint explicitly; `integrations/ui-style-kit.css` is not shipped |
+| `layout-style-css/bridge.css` | Removed; compose UI Style Kit paint explicitly because `bridge.css` is not shipped |
+| `layout-style-css/css` (`./css`) | `layout-style-css` |
+| `layout-style-css/css.css` (`./css.css`) | `layout-style-css` |
+| `layout-style-css/min` (`./min`) | `layout-style-css/min.css` |
+
+Focused exports remain available for `foundation.css`, `wrappers.css`, `primitives.css`, `recipes.css`, `utilities.css`, `personalities.css`, and `personalities/*.css`.
+
+## Recipe Hooks
+
+Recipe classes were aliases in v2 and are removed in v3. Replace them with the canonical attribute:
+
+| Removed class | Canonical v3 hook |
+| --- | --- |
+| `.ly-app-shell` | `data-ly-recipe="app-shell"` |
+| `.ly-dashboard` | `data-ly-recipe="dashboard"` |
+| `.ly-docs` | `data-ly-recipe="docs"` |
+| `.ly-list-detail` | `data-ly-recipe="list-detail"` |
+| `.ly-split-hero` | `data-ly-recipe="split-hero"` |
+| `.ly-gallery` | `data-ly-recipe="gallery"` |
+| `.ly-card-grid` | `data-ly-recipe="card-grid"` |
+
+Before:
+
+```html
+<section class="ly-dashboard" data-ly-recipe="dashboard">...</section>
+```
+
+After:
+
+```html
+<section data-ly-recipe="dashboard">...</section>
+```
+
+Keep canonical `data-ly-area` values on regions. App shell uses `sidebar`; Dashboard and Docs use `nav`.
+
+## Automatic And Manual Responsiveness
+
+Missing `data-ly-responsive` means automatic enhancement. To own topology yourself, opt out:
+
+```html
+<section data-ly-recipe="docs" data-ly-responsive="manual">...</section>
+```
+
+```css
+@container ly-scope (min-width: 56rem) {
+  [data-ly-recipe="docs"][data-ly-responsive="manual"] {
+    /* Application-owned topology. */
+  }
+}
+```
+
+The manual form retains the safe single-column fallback until the application query applies.
+
+## Containers And Wrappers
+
+`.ly-root`, every `.ly-wrapper`, and every recipe root now establishes the named `ly-scope` inline-size container. Recipes can be direct children of `.ly-root`; nested recipes respond to the nearest wrapper.
+
+The v3 wrapper names remain:
+
+- `.ly-wrapper--compact`
+- `.ly-wrapper--prose`
+- `.ly-wrapper--content`
+- `.ly-wrapper--wide`
+- `.ly-wrapper--full`
+- `.ly-wrapper--breakout`
+
+Breakout lanes remain `data-ly-lane="content"`, `data-ly-lane="feature"`, and `data-ly-lane="full"`.
+
+## Utilities And Source Order
+
+Remove all v2 responsive utility families:
+
+- `ly-md-*`
+- `ly-lg-*`
+
+Remove all visual-order utilities, including `.ly-order-first`, `.ly-order-normal`, `.ly-order-last`, and numbered order classes. There is no v3 replacement.
+
+Fix the DOM instead. The mobile DOM order is the reading and keyboard order; named grid areas enhance presentation without moving focus. Built-in recipes never use Flexbox or Grid ordering.
+
+The v3 utility module keeps only stable structural sizing, gap, padding, ratio, alignment, overflow, visibility, span, and column helpers.
+
+Remove `.ly-bleed`. Its `100vw` technique could overflow documents with classic scrollbars. Use the clamped `data-ly-lane="feature"` or `data-ly-lane="full"` breakout lanes, or an application-owned technique that accounts for its actual containing block.
+
+## Complete V2 Selector Index
+
+This index compares the `2.1.1` default bundle with v3. Selectors not named below remain available with their canonical v3 meaning.
+
+### Structural Aliases
+
+Replace application-shell region classes with canonical areas:
+
+| Removed classes | v3 replacement |
+| --- | --- |
+| `.ly-app-header`, `.ly-app-sidebar`, `.ly-app-main`, `.ly-app-aside`, `.ly-app-footer` | `data-ly-area="header"`, `data-ly-area="sidebar"`, `data-ly-area="main"`, `data-ly-area="aside"`, `data-ly-area="footer"` |
+
+Replace every removed area class with its same-named attribute:
+
+- `.ly-area--header` → `data-ly-area="header"`
+- `.ly-area--nav` → `data-ly-area="nav"`
+- `.ly-area--main` → `data-ly-area="main"`
+- `.ly-area--aside` → `data-ly-area="aside"`
+- `.ly-area--footer` → `data-ly-area="footer"`
+- `.ly-area--content` → `data-ly-area="content"`
+- `.ly-area--media` → `data-ly-area="media"`
+- `.ly-area--actions` → `data-ly-area="actions"`
+- `.ly-area--primary` → `data-ly-area="primary"`
+- `.ly-area--secondary` → `data-ly-area="secondary"`
+
+`.ly-grid--auto` becomes `.ly-grid`; intrinsic `auto-fit` tracks are now the default. Replace `.ly-panes--2` and `.ly-panes--3` with `.ly-panes`, then tune `--ly-pane-min`, `--ly-pane-size`, or application CSS if an exact fixed topology is required.
+
+The removed `.ly-media__asset` and `.ly-media__content` aliases become correctly ordered children of `.ly-media`. Keep `.ly-media__actions` when its existing action sizing is useful; use application-owned hooks if asset and content children need additional semantics.
+
+### Columns And Spans
+
+The stable column utilities retained by v3 are `.ly-cols-1`, `.ly-cols-2`, `.ly-cols-3`, `.ly-cols-4`, `.ly-cols-6`, and `.ly-cols-12`. Replace the removed `.ly-cols-5`, `.ly-cols-7`, `.ly-cols-8`, `.ly-cols-9`, `.ly-cols-10`, `.ly-cols-11`, and `.ly-cols-16` with a local `--ly-grid-columns` override:
+
+```css
+.application-grid {
+  --ly-grid-columns: 8;
+}
+```
+
+All responsive column aliases are removed:
+
+- `.ly-md-cols-1`, `.ly-md-cols-2`, `.ly-md-cols-3`, `.ly-md-cols-4`, `.ly-md-cols-6`, `.ly-md-cols-8`, `.ly-md-cols-12`, `.ly-md-cols-16`
+- `.ly-lg-cols-1`, `.ly-lg-cols-2`, `.ly-lg-cols-3`, `.ly-lg-cols-4`, `.ly-lg-cols-6`, `.ly-lg-cols-8`, `.ly-lg-cols-12`, `.ly-lg-cols-16`
+
+Put a retained base utility or `--ly-grid-columns` override inside an application-owned `@container ly-scope` query when a fixed responsive column count is genuinely required.
+
+V3 retains `.ly-span-1` through `.ly-span-4` and `.ly-span-full`. Replace `.ly-span-5`, `.ly-span-6`, `.ly-span-7`, `.ly-span-8`, `.ly-span-9`, `.ly-span-10`, `.ly-span-11`, `.ly-span-12`, `.ly-span-13`, `.ly-span-14`, `.ly-span-15`, and `.ly-span-16` with application CSS such as `grid-column: span 8`.
+
+### Spacing And Ratio Utilities
+
+V3 keeps the even spacing steps. Replace `.ly-gap-1`, `.ly-gap-3`, `.ly-gap-5`, `.ly-gap-7`, and `.ly-gap-9` with the closest retained utility or set `--ly-gap`, `--ly-grid-gap`, `--ly-stack-gap`, and `--ly-cluster-gap` together in application CSS.
+
+Replace `.ly-pad-1`, `.ly-pad-3`, `.ly-pad-5`, `.ly-pad-7`, and `.ly-pad-9` with a retained even padding step or application padding. The directional `.ly-px-4`, `.ly-px-6`, `.ly-px-8`, `.ly-py-4`, `.ly-py-6`, and `.ly-py-8` aliases have no v3 utility; use logical `padding-inline` or `padding-block`.
+
+Replace `.ly-frame-2x1` with an application token override:
+
+```css
+.application-frame {
+  --ly-frame-ratio: 2 / 1;
+}
+```
+
+### Responsive Visibility And Visual Order
+
+`.ly-show-md-up` and `.ly-show-lg-up` are removed. Prefer content that remains available at every allocation; if conditional rendering is a product requirement, own it in application CSS and preserve an accessible reading experience.
+
+All visual-order selectors are removed with no v3 replacement:
+
+- `.ly-order-first`, `.ly-order-normal`, `.ly-order-last`, `.ly-order-1`, `.ly-order-2`, `.ly-order-3`, `.ly-order-4`, `.ly-order-5`, `.ly-order-6`
+- `.ly-md-order-first`, `.ly-md-order-normal`, `.ly-md-order-last`, `.ly-md-order-1`, `.ly-md-order-2`, `.ly-md-order-3`, `.ly-md-order-4`, `.ly-md-order-5`, `.ly-md-order-6`
+- `.ly-lg-order-first`, `.ly-lg-order-normal`, `.ly-lg-order-last`, `.ly-lg-order-1`, `.ly-lg-order-2`, `.ly-lg-order-3`, `.ly-lg-order-4`, `.ly-lg-order-5`, `.ly-lg-order-6`
+
+## Vertical Responsiveness
+
+v3 adds height-aware defaults:
+
+- At `44rem` high or less, spacing, header height, and scroll bounds tighten.
+- At `30rem` high or less, recipe-owned sticky positioning and forced cover/shell heights are removed.
+- `100vh` fallbacks are followed by `100dvh`.
+
+Delete application orientation workarounds that existed only to make v2 shells usable in short landscape, then test actual available width and height.
+
+## Personalities
+
+All sixteen `data-ly-layout` values remain. Personality files are now token/topology profiles consumed by one shared responsive engine. They do not own independent `@container` or viewport breakpoint systems.
+
+If application CSS targeted personality-specific topology thresholds, move that topology to a manual recipe query against `ly-scope`.
+
+## Ecosystem Ownership
+
+Layout owns structure. UI Style Kit owns paint. Interactive Surface owns interaction styling.
+
+```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";
+```
+
+Do not recreate the removed structural bridge with UI-prefixed aliases. Put canonical Layout hooks in markup and let companion libraries style their own responsibilities.
+
+## Migration Checklist
+
+1. Replace removed package exports.
+2. Remove recipe class aliases.
+3. Remove responsive and order utilities.
+4. Confirm the mobile DOM, reading, keyboard, and focus order.
+5. Use automatic recipes by default.
+6. Add `data-ly-responsive="manual"` only where application topology is genuinely required.
+7. Test all recipes directly in `.ly-root` and inside their nearest wrapper.
+8. Test narrow, wide, tall, and short-landscape allocations.
+9. Run `npm run test:full` in Chromium, Firefox, and WebKit.

package/docs/wiki/Release-And-Publishing.md

@@ -0,0 +1,62 @@
+# Release And Publishing
+
+This guide describes the release gate for `layout-style-css@3.0.2`. Running verification does not publish, tag, push, create a GitHub Release, or change the npm registry.
+
+## Local Candidate Gate
+
+```bash
+npm ci
+npm run build
+npm run lint
+npm run test:full
+npm run release:verify
+git diff --check
+```
+
+`npm run release:verify` includes `npm audit --audit-level=moderate`, the cross-engine browser matrix, Pages verification, tarball dry-run, publish dry-run, and `npm run release:preflight`. It does not publish.
+
+The read-only ecosystem preflight uses the immutable UI fixture in `ecosystem-release-fixture.json`, overrides Layout Style with the candidate tarball, queries npm for every exact documented minimum/current version, resolves all packed exports (including personality modules), validates maintained documentation, and runs the reviewed clean-install matrices. Pull requests execute this same gate without enabling publish, tag, release, or deployment mutations.
+
+The package's `prepublishOnly` script runs `npm run release:verify`, so a direct npm publish uses the same full gate.
+
+## Coordinated Bootstrap Sequence
+
+The immutable cross-repository pins require this exact remote sequence:
+
+1. Push a stable UI bootstrap ref containing `33e3c834aec62b85650dd14aea9d7d388abef191`.
+2. Push and merge Interactive Surface CSS and Layout Style CSS with merge commits so their reviewed commit SHAs remain reachable.
+3. Update and verify the final UI companion pins against those merged companion commits.
+4. Push the final UI branch, rerun its ecosystem preflight, and merge UI with a merge commit.
+5. Do not squash, rebase, or delete the only remote refs until every pinned commit is reachable through merged ancestry.
+
+The bootstrap SHA is deliberately stable: companion workflows use it to load the reviewed preflight implementation before the final UI commit can reference the companion heads.
+
+## Candidate Inspection
+
+Confirm:
+
+- package version is `3.0.2`
+- intended tag would be `v3.0.2`
+- runtime and peer dependencies are empty
+- exact exports and tarball files match the v3 contract
+- generated CSS matches authored sources
+- Chromium, Firefox, and WebKit are green
+- `desktop.ini` and other local-only files are absent from the tarball
+
+## Separately Approved Publication
+
+Only after explicit approval:
+
+1. Commit the verified candidate.
+2. Push the intended branch.
+3. Merge through the repository's normal review policy.
+4. Create the exact `v3.0.2` tag from the protected release commit.
+5. Publish the GitHub Release.
+6. Let the protected npm workflow verify the tag and publish with provenance.
+7. Confirm the GitHub Release, tag, and npm registry state independently.
+
+The npm job uses the protected `npm` environment, required reviewers, least-privilege permissions, strict tag validation, exact tag checkout, main-ancestry verification, and an immutable commit sha. Prefer npm trusted publishing when the registry setup supports it.
+
+## Recovery
+
+If verification fails, fix the candidate and rerun the complete gate. Do not move or overwrite an existing release tag. Use a new semantic version when a published artifact must be corrected.

package/docs/wiki/Security-And-Support.md

@@ -0,0 +1,32 @@
+# Security And Support
+
+## Supported Lines
+
+| Version | Supported |
+| --- | --- |
+| `3.x` | Yes |
+| `2.x` | Security fixes only during the v3 transition |
+| `1.x` | No |
+
+v3 is dependency-free at runtime. Development dependencies and release automation remain subject to the repository security policy.
+
+## Reporting
+
+Use the private process in the repository [SECURITY.md](../../SECURITY.md). Do not publish exploit details in a public issue before maintainers can assess them.
+
+## Release Trust
+
+The npm workflow uses:
+
+- a protected npm environment with required reviewers
+- exact `refs/tags/v*` checkout
+- main-branch ancestry verification
+- least-privilege workflow permissions
+- registry provenance
+- an immutable commit sha
+
+Use npm trusted publishing when configured. A local green `release:verify` is evidence for a candidate, not authority to publish.
+
+## Structural Security Boundary
+
+Layout CSS has no network calls, script execution, runtime dependencies, secrets, or user data processing. Security-sensitive application behavior remains outside this package.

package/docs/wiki/UI-Style-Kit-Compatibility.md

@@ -0,0 +1,40 @@
+# Companion Library Compatibility
+
+Layout Style CSS v3 has no bridge, peer dependency, or companion import.
+
+## Ownership
+
+Layout owns structure. UI Style Kit owns paint. Interactive Surface owns interaction styling.
+
+- Layout: wrappers, containment, measures, flow, tracks, grid areas, ratios, overflow bounds, and responsive topology
+- UI Style Kit: color, typography, borders, radii, shadows, component paint, and theme roles
+- Interactive Surface: hover, focus, pressed, selected, disabled, loading, and other interaction-state styling
+
+## Explicit Imports
+
+```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";
+```
+
+Applications may use Layout alone, Layout plus UI Style Kit, or all three. The default Layout bundle never imports or assumes either companion.
+
+## Markup
+
+Put canonical structural hooks in markup:
+
+```html
+<body class="ly-root" data-ly-layout="minimal-saas" data-ui="minimal-saas">
+  <main class="ly-wrapper" data-ly-recipe="dashboard">
+    <header data-ly-area="header" class="saas-card">Dashboard</header>
+  </main>
+</body>
+```
+
+The `ly-*` hooks control structure. Companion classes and data attributes can paint or animate the same elements without taking over layout.
+
+## v3 Boundary
+
+The deprecated v2 UI-prefixed structural bridge is not shipped. Migrate bridge aliases to canonical Layout hooks; do not copy the bridge into application CSS. See [Migrating To 3.0](Migrating-To-3.0.md).

package/docs/wiki/_Sidebar.md

@@ -0,0 +1,12 @@
+- [Home](Home)
+- [Getting Started](Getting-Started)
+- [Installation And CDN](Installation-And-CDN)
+- [Layout Primitives](Layout-Primitives)
+- [Layout Recipes](Layout-Recipes)
+- [Layout Styles](Layout-Styles)
+- [Companion Compatibility](UI-Style-Kit-Compatibility)
+- [Migrating To 3.0](Migrating-To-3.0)
+- [Demo And GitHub Pages](Demo-And-GitHub-Pages)
+- [Release And Publishing](Release-And-Publishing)
+- [Security And Support](Security-And-Support)
+- [Contributing](Contributing)

package/manifest.json

@@ -0,0 +1,99 @@
+{
+  "schemaVersion": 1,
+  "schemaPolicy": {
+    "compatibility": "additive-within-major",
+    "breakingChange": "increment-schemaVersion-before-removing-or-renaming-fields"
+  },
+  "name": "layout-style-css",
+  "version": "3.0.2",
+  "entrypoints": {
+    "default": "./dist/layout-style-css.css",
+    "minified": "./dist/layout-style-css.min.css",
+    "core": "./dist/core.css",
+    "foundation": "./dist/foundation.css",
+    "wrappers": "./dist/wrappers.css",
+    "primitives": "./dist/primitives.css",
+    "recipes": "./dist/recipes.css",
+    "utilities": "./dist/utilities.css",
+    "personalities": "./dist/personalities.css",
+    "personalityModules": "./dist/personalities/*.css",
+    "personalityMetadata": "./personalities.json"
+  },
+  "selectors": {
+    "stable": [".ly-root", ".ly-wrapper"],
+    "deprecated": []
+  },
+  "wrappers": ["compact", "prose", "content", "wide", "full", "breakout"],
+  "primitives": ["page", "header", "footer", "main", "section", "surface", "readable", "stack", "cluster", "center", "cover", "switcher", "sidebar", "grid", "split", "panes", "media", "reel", "frame", "scroll"],
+  "recipes": ["app-shell", "dashboard", "docs", "list-detail", "split-hero", "gallery", "card-grid"],
+  "areas": ["header", "nav", "sidebar", "main", "aside", "footer", "content", "media", "actions", "primary", "secondary"],
+  "personalities": ["minimal-saas", "bento", "maximalist", "bauhaus", "tactile", "neumorphism", "retrofuturism", "brutalism", "cyberpunk", "y2k", "retro-glass", "f-pattern", "z-pattern", "split-screen", "mondrian", "synthwave"],
+  "personalityPairings": [
+    { "id": "minimal-saas", "label": "Minimal SaaS", "visualCompatibility": "native", "recommendedVisualPresets": ["minimal-saas"] },
+    { "id": "bento", "label": "Bento", "visualCompatibility": "native", "recommendedVisualPresets": ["bento"] },
+    { "id": "maximalist", "label": "Maximalist", "visualCompatibility": "native", "recommendedVisualPresets": ["maximalist"] },
+    { "id": "bauhaus", "label": "Bauhaus", "visualCompatibility": "native", "recommendedVisualPresets": ["bauhaus"] },
+    { "id": "tactile", "label": "Tactile", "visualCompatibility": "native", "recommendedVisualPresets": ["tactile"] },
+    { "id": "neumorphism", "label": "Neumorphism", "visualCompatibility": "native", "recommendedVisualPresets": ["neumorphism"] },
+    { "id": "retrofuturism", "label": "Retrofuturism", "visualCompatibility": "native", "recommendedVisualPresets": ["retrofuturism"] },
+    { "id": "brutalism", "label": "Brutalism", "visualCompatibility": "native", "recommendedVisualPresets": ["brutalism"] },
+    { "id": "cyberpunk", "label": "Cyberpunk", "visualCompatibility": "native", "recommendedVisualPresets": ["cyberpunk"] },
+    { "id": "y2k", "label": "Y2K", "visualCompatibility": "native", "recommendedVisualPresets": ["y2k"] },
+    { "id": "retro-glass", "label": "Retro Glass", "visualCompatibility": "native", "recommendedVisualPresets": ["retro-glass"] },
+    { "id": "f-pattern", "label": "F-pattern", "visualCompatibility": "any", "recommendedVisualPresets": [] },
+    { "id": "z-pattern", "label": "Z-pattern", "visualCompatibility": "any", "recommendedVisualPresets": [] },
+    { "id": "split-screen", "label": "Split Screen", "visualCompatibility": "any", "recommendedVisualPresets": [] },
+    { "id": "mondrian", "label": "Mondrian", "visualCompatibility": "any", "recommendedVisualPresets": [] },
+    {
+      "id": "synthwave",
+      "label": "Synthwave",
+      "visualCompatibility": "recommended",
+      "recommendedVisualPresets": ["cyberpunk", "retrofuturism"],
+      "visualVerification": {
+        "method": "rendered-computed-style",
+        "test": "test/demo-smoke.test.mjs",
+        "computedProperties": {
+          "cyberpunk": { "boxShadow": "0px 0px 18px" },
+          "retrofuturism": { "boxShadow": "0px 10px 30px" }
+        },
+        "assertion": "A visible browser contract fixture renders each preset's distinct article box-shadow while data-ly-layout remains synthwave."
+      }
+    }
+  ],
+  "containers": {
+    "names": ["ly-scope"],
+    "type": "inline-size"
+  },
+  "thresholds": {
+    "containerMinWidths": ["42rem", "44rem", "48rem", "52rem", "72rem"],
+    "viewportMaxHeights": ["44rem", "30rem"]
+  },
+  "tokens": {
+    "geometry": [
+      "--ly-space-0", "--ly-space-1", "--ly-space-2", "--ly-space-3", "--ly-space-4",
+      "--ly-space-5", "--ly-space-6", "--ly-space-7", "--ly-space-8", "--ly-space-9",
+      "--ly-wrapper-compact", "--ly-wrapper-prose", "--ly-wrapper-content", "--ly-wrapper-wide",
+      "--ly-page-padding-inline", "--ly-safe-area-inline", "--ly-safe-area-block-start",
+      "--ly-safe-area-block-end", "--ly-wrapper-gutter", "--ly-wrapper-max", "--ly-profile-gap",
+      "--ly-gap", "--ly-grid-gap", "--ly-stack-gap", "--ly-cluster-gap",
+      "--ly-section-padding-block", "--ly-section-padding-block-compact", "--ly-header-height",
+      "--ly-sticky-position", "--ly-cover-min",
+      "--ly-shell-min", "--ly-scroll-max", "--ly-switcher-threshold", "--ly-sidebar-size",
+      "--ly-sidebar-content-min", "--ly-grid-columns", "--ly-grid-min", "--ly-split-min",
+      "--ly-pane-min", "--ly-pane-size", "--ly-media-min", "--ly-media-size", "--ly-reel-item-min",
+      "--ly-reel-item-max", "--ly-frame-ratio", "--ly-split-primary", "--ly-split-secondary",
+      "--ly-recipe-rail", "--ly-recipe-aside", "--ly-gallery-min", "--ly-card-grid-min",
+      "--ly-app-shell-medium-areas", "--ly-app-shell-medium-columns", "--ly-app-shell-wide-areas",
+      "--ly-app-shell-wide-columns", "--ly-dashboard-medium-areas", "--ly-dashboard-medium-columns",
+      "--ly-dashboard-wide-areas", "--ly-dashboard-wide-columns", "--ly-docs-wide-areas",
+      "--ly-docs-wide-columns", "--ly-list-detail-wide-areas", "--ly-list-detail-wide-columns",
+      "--ly-split-hero-wide-areas", "--ly-split-hero-wide-columns", "--ly-center-max",
+      "--ly-cover-padding", "--ly-z-header", "--ly-split-align", "--ly-media-align",
+      "--ly-split-hero-align"
+    ]
+  },
+  "companions": {
+    "ui-style-kit-css": ">=2.1.0 <3.0.0",
+    "interactive-surface-css": ">=1.5.0 <2.0.0"
+  }
+}