layout-style-css 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to `layout-style-css` are documented here.
+
+This project follows semantic versioning. The `1.1.1` release is additive and keeps the existing `ly-*` public contract intact.
+
+## [1.1.1] - 2026-07-05
+
+### Added
+
+- Added versioned wiki documentation under `docs/wiki` for installation, layout primitives, recipes, UI Style Kit compatibility, demo deployment, publishing, security, and contribution workflows.
+- Added UI Style Kit-compatible structural aliases for `saas`, `bento`, `max`, `bau`, `tactile`, `neo`, `retro`, `brutal`, `cyber`, `y2k`, and `rg` prefixes.
+- Added layout recipe helpers for button groups, card grids, card sizing, galleries, and carousels.
+- Added F-Pattern, Z-Pattern, Split-Screen, Mondrian, and Synthwave layout styles.
+- Added `layout-style-css/all-with-ui-kit-and-interactive-surface.css` for the three-library import path.
+- Added direct `./dist/*.css` package exports for consumers that need generated dist files.
+- Added `CHANGELOG.md`, `CONTRIBUTING.md`, and `SECURITY.md` to the release documentation set.
+
+### Changed
+
+- Reworked the demo mobile controls into a compact drawer so the sticky header does not consume the mobile viewport.
+- Expanded the demo to cover app shell, wrappers, split layouts, sidebars, panes, button groups, card grids, card sizes, galleries, carousels, frames, and scroll areas.
+- Updated README examples to use exported CSS entrypoints and valid CDN links.
+- Updated npm release metadata, package file allowlist, and release verification scripts for the `1.1.1` package.
+- Updated the npm publish workflow to publish from `release.published` events and explicit `workflow_dispatch` tags.
+
+### Fixed
+
+- Fixed README quick-start imports that referenced non-exported paths.
+- Fixed malformed UI Style Kit CDN link markup in the README.
+- Clarified responsive column utility documentation so class groups do not imply bare numeric class names.
+- Preserved GitHub Pages artifact generation with a Pages-root `index.html`.
+- Fixed the release automation path so draft releases can be published before the npm workflow runs.
+
+### Security
+
+- Kept the layout CSS contract free of visual properties owned by `ui-style-kit-css`.
+- Kept the package CSS-only at runtime with no network calls, dynamic script execution, or secret handling.
+- Added release verification coverage for npm pack contents and documentation completeness.
+
+## [1.0.0]
+
+### Added
+
+- Initial public release of layout primitives, layout style files, generated dist bundles, and demo coverage.
+

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Thanks for improving `layout-style-css`. This repository is a CSS layout library, so changes should keep structure, spacing, responsive behavior, and package contracts separate from visual styling.
+
+## Local Setup
+
+```bash
+npm install
+npm run build
+npm run lint
+npm test
+```
+
+Run the full release gate before opening a release PR:
+
+```bash
+npm run release:verify
+```
+
+## Development Rules
+
+- Keep authored CSS in `styles/`.
+- 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/layout-ui-style-kit-bridge.css` only when they map to layout primitives or layout recipes.
+- Update README, `docs/wiki`, and `CHANGELOG.md` when a public class, export, recipe, release workflow, or package behavior changes.
+
+## Testing Expectations
+
+Every change that affects public behavior should update or preserve:
+
+- `test/layout-css-contract.test.mjs` for package, CSS, docs, and tarball contracts.
+- `test/demo-smoke.test.mjs` for rendered demo behavior.
+- `test/pages-artifact.test.mjs` for GitHub Pages output.
+- `stylelint` for authored CSS formatting.
+
+## Review Checklist
+
+- The package remains publishable as a public npm library.
+- The npm tarball contains only intended release files.
+- README examples use exported package entrypoints.
+- Documentation links resolve to versioned files.
+- Demo controls remain compact on mobile and tablet viewports.
+- New CSS does not introduce UI Style Kit-owned visual declarations.
+
+## Wiki Updates
+
+The source for the project wiki is `docs/wiki/`. If GitHub Wiki is enabled for the repository, mirror those files into the wiki remote after the main branch documentation is merged.
+

package/README.md

@@ -4,6 +4,28 @@ 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.1 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:
@@ -15,14 +37,30 @@ This package owns the spatial layer only. That separation lets you change layout
 
 ## Install
 
+Use as a standalone layout system with all styles or just one layout personality.
+
 ```bash
-npm install layout-style-css ui-style-kit-css@2.0.1
+# Install the full layout system
+npm install layout-style-css@1.1.1
 ```
 
-Install Interactive Surface CSS only when you want the optional three-library bundle:
+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 interactive-surface-css@1.2.5
+npm install layout-style-css@1.1.1 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.1 ui-style-kit-css@2.0.1 interactive-surface-css@1.2.5
 ```
 
 ## Quick Start
@@ -30,7 +68,17 @@ npm install interactive-surface-css@1.2.5
 Import UI Style Kit first, then the layout CSS:
 
 ```js
-import "ui-style-kit-css/dist/ui-style-kit.css";
+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";
 ```
 
@@ -39,10 +87,10 @@ Use one root element for UI style, layout style, theme, and mode:
 ```html
 <body
   class="ly-root"
-  data-ui="minimal-saas"
-  data-layout="minimal-saas"
-  data-theme="arctic-indigo"
-  data-mode="light"
+  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>
@@ -70,11 +118,12 @@ Layout-only CDN entry:
 <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:
+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.min.css">
+<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
@@ -85,7 +134,7 @@ Recommended CDN pairing with UI Style Kit:
 | `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. |
+| `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. |
 
@@ -97,6 +146,49 @@ The three-library aggregate imports in this order:
 @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.
@@ -206,6 +298,82 @@ Use for inboxes, editors, queues, and preview workflows.
 </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 |
@@ -219,6 +387,11 @@ Use for inboxes, editors, queues, and preview workflows.
 | `.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. |
@@ -237,8 +410,8 @@ Utilities are composition-only. They set layout variables, spacing, flow, visibi
 | 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-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. |
 
@@ -298,6 +471,11 @@ Each layout style file targets layout selectors only. It does not key off `data-
 | `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
 
@@ -314,6 +492,8 @@ data-ui="cyberpunk" data-layout="maximalist" data-theme="arctic-indigo" data-mod
 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:
@@ -354,6 +534,8 @@ The artifact is written to `output/github-pages/` and contains:
 - 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
@@ -378,6 +560,12 @@ demo/
 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.
@@ -404,16 +592,17 @@ The check command builds `dist/`, runs Stylelint, runs contract tests, runs resp
 Before publishing:
 
 ```bash
-npm view layout-style-css@1.0.0 version --json
-npm run release:verify
+npm view layout-style-css@1.1.1 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.0.0
+npm login
+npm publish --access public
+npm view layout-style-css@1.1.1
 ```
 
 After publish, verify these CDN URLs:
@@ -423,7 +612,7 @@ 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.0.0` in `Foscat/layout-style-css`.
+Tag the release as `v1.1.1` 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.1`.
 
 ## Compatibility
 

package/SECURITY.md

@@ -0,0 +1,45 @@
+# Security Policy
+
+`layout-style-css` is a CSS-only layout package. It does not execute JavaScript at runtime, make network requests, process user input, store credentials, or read secrets.
+
+## Supported Versions
+
+| Version | Supported |
+| --- | --- |
+| `1.1.x` | Yes |
+| `1.0.x` | Security fixes only when practical |
+
+## Reporting A Vulnerability
+
+Use GitHub security advisories for private reports when available. If advisories are not enabled, open a minimal GitHub issue that avoids public exploit details and asks for a private coordination path.
+
+Please include:
+
+- affected version and package entrypoint
+- affected selector, file, or demo behavior
+- reproduction steps
+- expected impact
+- whether the issue affects package consumers, the demo, or GitHub Pages deployment
+
+## Security Model
+
+The primary security risks for this package are supply-chain and documentation risks:
+
+- incorrect package exports that make consumers import unexpected files
+- malformed CDN examples that point to wrong assets
+- accidental runtime JavaScript or network behavior in docs or demo code
+- package contents that include secrets, build caches, or unrelated local files
+- CSS that hides important controls or breaks keyboard-visible flows in the demo
+
+The release gate verifies package contents, README imports, documentation links, CSS contracts, rendered demo behavior, and GitHub Pages artifact structure.
+
+## Dependency Checks
+
+Run the local dependency audit before publishing:
+
+```bash
+npm audit --audit-level=moderate
+```
+
+The package also uses `npm run release:verify` to run build, lint, tests, pack dry-run, and publish dry-run checks.
+