@cruglobal/cornerstone-components 0.6.1 → 0.7.0

package/dist/unbundled/react/zoomable-frame/index.js

@@ -1,24 +1,24 @@
-/*! Cornerstone Components 0.6.1 - MIT licensed. See LICENSE.md and NOTICE. */
+/*! Cornerstone Components 0.7.0 - MIT licensed. See LICENSE.md and NOTICE. */
 import {
   zoomable_frame_default
-} from "../../chunks/chunk.UZQB65CZ.js";
-import "../../chunks/chunk.3PZ5EWXX.js";
-import "../../chunks/chunk.BPPTP67I.js";
-import "../../chunks/chunk.4ER2E763.js";
-import "../../chunks/chunk.5YGOQ5YB.js";
-import "../../chunks/chunk.SLRESERY.js";
-import "../../chunks/chunk.A3J72J5J.js";
-import "../../chunks/chunk.ANHY6BXG.js";
-import "../../chunks/chunk.PGRLJT6U.js";
-import "../../chunks/chunk.UQMDB327.js";
-import "../../chunks/chunk.V3OJKPQZ.js";
-import "../../chunks/chunk.D7BHLZNU.js";
-import "../../chunks/chunk.5SB535WG.js";
-import "../../chunks/chunk.ZKPECPPZ.js";
-import "../../chunks/chunk.NWV3U6VD.js";
-import "../../chunks/chunk.AF4NWEDF.js";
-import "../../chunks/chunk.BG6YAMWP.js";
-import "../../chunks/chunk.LOD6ZXF2.js";
+} from "../../chunks/chunk.BGQ7WQMK.js";
+import "../../chunks/chunk.FD4M72EZ.js";
+import "../../chunks/chunk.ADCI3XRE.js";
+import "../../chunks/chunk.LXRZAZBE.js";
+import "../../chunks/chunk.PIEP4TY2.js";
+import "../../chunks/chunk.PLLLVECA.js";
+import "../../chunks/chunk.6MA5SVB3.js";
+import "../../chunks/chunk.3VYYIGXD.js";
+import "../../chunks/chunk.N6DONW5L.js";
+import "../../chunks/chunk.JB6AKMGD.js";
+import "../../chunks/chunk.N7QTQOAR.js";
+import "../../chunks/chunk.CG2W46XZ.js";
+import "../../chunks/chunk.TN255ITC.js";
+import "../../chunks/chunk.A6PE2BDS.js";
+import "../../chunks/chunk.RW2GBP4G.js";
+import "../../chunks/chunk.7CX7TYXB.js";
+import "../../chunks/chunk.F3TEYKB3.js";
+import "../../chunks/chunk.HWQS6OLV.js";
 export {
   zoomable_frame_default as default
 };

package/dist/unbundled/skills/cornerstone/SKILL.md

@@ -4,7 +4,7 @@ description: Cornerstone is a UI component library built with web components. Us
 license: MIT
 metadata:
   author: Cru Global
-  version: "0.6.1"
+  version: "0.7.0"
   homepage: https://cruglobal.github.io/cornerstone-design-system
   repository: https://github.com/CruGlobal/cornerstone-design-system
 compatibility: Works in modern browsers. Requires no build tools when using CDN. Works with bundlers like Webpack and Vite when installed via npm.
@@ -136,7 +136,7 @@ For complete usage details, see [Usage Guide](references/usage.md).
 - [`<cs-details>`](references/components/details.md) - Details display a brief summary and expand to reveal additional content. Use them to progressively disclose information, group related FAQs, or hide advanced options. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/details))
 - [`<cs-dialog>`](references/components/dialog.md) - Dialogs appear above the page and require the user's immediate attention. Use them for confirmations, forms, or focused tasks that interrupt the main flow. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/dialog))
 - [`<cs-divider>`](references/components/divider.md) - Dividers visually separate or group adjacent elements with a horizontal or vertical line. Use them to establish rhythm and hierarchy within menus, toolbars, and layouts. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/divider))
-- [`<cs-drawer>`](references/components/drawer.md) - Drawers slide in from the edge of a container to expose additional options and information without navigating away. Useful for navigation menus, filters, and secondary content. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/drawer))
+- [`<cs-drawer>`](references/components/drawer.md) - Drawers slide in from an edge of the viewport to expose additional options and information without navigating away. Useful for navigation menus, filters, and secondary content. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/drawer))
 - [`<cs-page>`](references/components/page.md) - Pages scaffold an entire application layout with header, navigation, sidebar, main content, aside, and footer regions. Use them to structure full pages with minimal markup and responsive behavior built in. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/page))
 - [`<cs-scroller>`](references/components/scroller.md) - Scrollers wrap overflowing content in an accessible container with visual cues that help users recognize and navigate scrollable regions. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/scroller))
 - [`<cs-split-panel>`](references/components/split-panel.md) - Split panels display two adjacent panels separated by a draggable divider, letting users resize each side to suit their workflow. ([docs](https://cruglobal.github.io/cornerstone-design-system/components/split-panel))
@@ -191,9 +191,7 @@ no warning.
 
 ### Valid slots (use these exact names)
 
-`banner`, `header`, `subheader`, `navigation-header`, `navigation`,
-`navigation-footer`, `menu`, `main-header`, `main-footer`, `aside`, `footer`,
-`skip-to-content`, `navigation-toggle`. **Anything else** (e.g. `slot="main"`, `slot="nav"`,
+`banner`, `header`, `subheader`, `menu`, `navigation-header`, `navigation`, `navigation-footer`, `desktop-navigation-header`, `desktop-navigation`, `desktop-navigation-footer`, `mobile-navigation-header`, `mobile-navigation`, `mobile-navigation-footer`, `navigation-toggle`, `navigation-toggle-icon`, `main-header`, `main-footer`, `aside`, `skip-to-content`, `skip-to-content-target`, `footer`. **Anything else** (e.g. `slot="main"`, `slot="nav"`,
 `slot="content"`) is silently ignored. There is no `nav` slot — the navigation slot is
 `navigation`. (`menu` is an advanced escape hatch that *replaces* the entire left navigation
 region; don't use it for ordinary nav links — and for a landing page, skip the left region

package/dist/unbundled/skills/cornerstone/references/components/accordion.md

@@ -9,8 +9,7 @@
     applications. It's built on open web standards and works with any framework.
   </cs-accordion-item>
   <cs-accordion-item label="Is it free to use?">
-    The core Cornerstone library is completely free and open source. A Pro tier is also available with additional
-    components and features.
+    Yes. Cornerstone Components is free and open source under the MIT license.
   </cs-accordion-item>
   <cs-accordion-item label="Does it work with my framework?">
     Yes! Cornerstone components are built as native web components, so they work with any framework including React,

package/dist/unbundled/skills/cornerstone/references/components/animation.md

@@ -202,6 +202,39 @@ Animations won't play until you apply the `play` attribute. You can omit it init
 </script>
 ```
 
+### Restarting Animations
+
+Setting `play` to `true` won't replay an animation that is still running, because `play` is already `true`. Call `restart()` to rewind to the start and play again, whether the animation has finished, is paused or is still running. Each restart is a new run, so the delay plays again and `cs-start` is emitted.
+
+```html
+<div class="animation-restart">
+  <cs-animation name="tada" duration="1000" iterations="1" play>
+    <div class="box"></div>
+  </cs-animation>
+
+  <cs-button appearance="filled" variant="brand">Replay</cs-button>
+</div>
+
+<script type="module">
+  const container = document.querySelector('.animation-restart');
+  const animation = container.querySelector('cs-animation');
+  const button = container.querySelector('cs-button');
+
+  button.addEventListener('click', () => {
+    animation.restart();
+  });
+</script>
+
+<style>
+  .animation-restart .box {
+    width: 100px;
+    height: 100px;
+    background-color: var(--cs-color-brand-fill-loud);
+    margin-bottom: var(--cs-space-l);
+  }
+</style>
+```
+
 ## API
 
 ### Importing
@@ -248,7 +281,7 @@ Valid slot names for this component (use exactly these — any other `slot` valu
 | `iterationStart` | `iteration-start` | The offset at which to start the animation, usually between 0 (start) and 1 (end). | `number` | `0` | — |
 | `keyframes` | — | The keyframes to use for the animation. If this is set, `name` will be ignored. | `Keyframe[] \| undefined` | — | — |
 | `name` | `name` | The name of the built-in animation to use. For custom animations, use the `keyframes` prop. | `string` | `'none'` | — |
-| `play` | `play` | Plays the animation. When omitted, the animation will be paused. This attribute will be automatically removed when the animation finishes or gets canceled. | `boolean` | `false` | Yes |
+| `play` | `play` | Plays the animation. When omitted, the animation will be paused. This attribute will be automatically removed when the animation finishes or gets canceled. To play it again from the start, call `restart()`. | `boolean` | `false` | Yes |
 | `playbackRate` | `playback-rate` | Sets the animation's playback rate. The default is `1`, which plays the animation at a normal speed. Setting this to `2`, for example, will double the animation's speed. A negative value can be used to reverse the animation. This value can be changed without causing the animation to restart. | `number` | `1` | — |
 
 ### Methods
@@ -257,6 +290,7 @@ Valid slot names for this component (use exactly these — any other `slot` valu
 | --- | --- | --- |
 | `cancel()` | Clears all keyframe effects caused by this animation and aborts its playback. | — |
 | `finish()` | Sets the playback time to the end of the animation corresponding to the current playback direction. | — |
+| `restart()` | Rewinds the animation to the start and plays it, whether it has finished, been canceled, been paused or is still running. Each restart is a new run: the delay and every iteration play again as the current options describe them, `play` is set to `true`, and `cs-start` is emitted. The run it interrupts emits neither `cs-cancel` nor `cs-finish`. If the animation doesn't exist yet, for example because nothing is slotted, it starts as soon as it does. Changing an option such as `duration` while the animation plays also starts a new run, so changing one in the same tick as `restart()` emits `cs-start` twice. | — |
 
 ### Events
 

package/dist/unbundled/skills/cornerstone/references/components/button.md

@@ -126,6 +126,21 @@ When an [icon](https://cruglobal.github.io/cornerstone-design-system/components/
 > <strong>Give icon-only buttons a label.</strong><br />
 > With no text to announce, a screen reader has nothing to read. Add `label` to the icon (`<cs-icon name="home" label="Home">`) so the button has an accessible name.
 
+### Icon Button With a Badge
+
+To show a [badge](https://cruglobal.github.io/cornerstone-design-system/components/badge) on an icon button, such as an unread count, put the badge in the `end` slot. The button pins a badge to its top corner from any slot, but only the default slot decides whether it is an icon button: a badge there counts as content beside the icon, so the button loses its square icon-button shape. The `start` slot keeps the shape too, but its spacing pushes the badge in from the corner.
+
+```html
+<cs-button appearance="plain">
+  <cs-icon name="notifications" label="Notifications, 3 unread"></cs-icon>
+  <cs-badge slot="end" pill aria-hidden="true">3</cs-badge>
+</cs-button>
+```
+
+A bare number does not say what it counts, so put the count and what it counts in the icon's `label`, and add `aria-hidden="true"` to the badge so it is not read twice. Update both when the count changes.
+
+This pattern does not announce a new count. If the count changes because of something the user did, such as adding an item to a cart, announce it as well. Keep an empty `<div class="cs-visually-hidden" role="status"></div>` on the page, outside the button, and set its text to the new count with context, such as "3 items in cart".
+
 ### Start & End Decorations
 
 Use the `start` and `end` slots to add presentational elements like `<cs-icon>` beside the button label.
@@ -222,7 +237,10 @@ Build the override out of [design tokens](https://cruglobal.github.io/cornerston
     border-right-color: var(--cs-color-pink-20);
     color: var(--cs-color-pink-95);
     font-size: var(--cs-font-size-l);
-    box-shadow: var(--cs-shadow-m) var(--cs-color-pink-20);
+    /* The geometry longhands, not --cs-shadow-m: that shorthand already ends in its own
+       colour, and a shadow layer with two colours is invalid. */
+    box-shadow: var(--cs-shadow-offset-x-m) var(--cs-shadow-offset-y-m) var(--cs-shadow-blur-m)
+      var(--cs-shadow-spread-m) var(--cs-color-pink-20);
     transition: all var(--cs-transition-slow) var(--cs-transition-easing);
   }
 

package/dist/unbundled/skills/cornerstone/references/components/color-picker.md

@@ -109,6 +109,29 @@ To offer a fully transparent option, include the `transparent` keyword as a swat
 >
 > Transparent swatches require the `opacity` attribute. Without it, the alpha channel is discarded and selecting the swatch yields opaque black.
 
+### Swatches From Design Tokens
+
+A swatch can be a design token, written as `var(--cs-name)` or `var(--cs-name, fallback)`, so brand colors don't have to be turned into hex in JavaScript first. Only `--cs-*` custom properties are read; a `var()` of any other custom property is left out. The picker looks the value up on itself each time it opens, so a theme set on any ancestor applies, including a switch between light and dark. Selecting the swatch sets the color it resolved to, in the picker's `format`. The value must resolve to hex, `rgb()`, `hsl()` or a color name. Anything else is left out, including tokens built with `color-mix()`.
+
+```html
+<cs-color-picker
+  label="Brand color"
+  swatches="
+    var(--cs-color-brand-fill-loud); var(--cs-color-brand-fill-normal); var(--cs-color-brand-fill-quiet);
+    var(--cs-color-success-fill-loud); var(--cs-color-warning-fill-loud); var(--cs-color-danger-fill-loud);
+  "
+></cs-color-picker>
+```
+
+A `var(--cs-*)` swatch without a label is named after its custom property, so `var(--cs-color-brand-fill-loud)` is announced as "brand fill loud". For a friendlier name, pass a `{ color, label }` object instead.
+
+```js
+picker.swatches = [
+  { color: 'var(--cs-color-brand-fill-loud)', label: 'Brand' },
+  { color: 'var(--cs-color-neutral-fill-loud)', label: 'Neutral' },
+];
+```
+
 ### Placement
 
 Set the `placement` attribute to control where the dropdown opens. The actual position may shift to keep the panel inside the viewport.
@@ -242,7 +265,7 @@ Valid slot names for this component (use exactly these — any other `slot` valu
 | `form` | — | By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work. | `HTMLFormElement \| null` | — | — |
 | `format` | `format` | The format to use. If opacity is enabled, these will translate to HEXA, RGBA, HSLA, and HSVA respectively. The color picker will accept user input in any format (including CSS color names) and convert it to the desired format. | `'hex' \| 'rgb' \| 'hsl' \| 'hsv'` | `'hex'` | — |
 | `hint` | `hint` | The color picker's hint. If you need to display HTML, use the `hint` slot instead. | `string` | `''` | — |
-| `label` | `label` | The color picker's label. This will not be displayed, but it will be announced by assistive devices. If you need to display HTML, you can use the `label` slot` instead. | `string` | `''` | — |
+| `label` | `label` | The color picker's label. It is displayed with the trigger and gives the trigger its accessible name. If you need to display HTML, use the `label` slot instead. | `string` | `''` | — |
 | `name` | `name` | The name of the form control, submitted as a name/value pair with form data. | `string \| null` | `null` | Yes |
 | `opacity` | `opacity` | Shows the opacity slider. Enabling this will cause the formatted value to be HEXA, RGBA, or HSLA. | `boolean` | `false` | — |
 | `open` | `open` | Indicates whether or not the popup is open. You can toggle this attribute to show and hide the popup, or you can use the `show()` and `hide()` methods and this attribute will reflect the popup's open state. | `boolean` | `false` | Yes |
@@ -251,7 +274,7 @@ Valid slot names for this component (use exactly these — any other `slot` valu
 | `size` | `size` | Determines the size of the color picker's trigger | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` | `'m'` | Yes |
 | `ssrHint` | `ssr-hint` | Only required for SSR. Set to `true` if you're slotting in a `hint` element so the server-rendered markup includes the hint before the component hydrates on the client. | `boolean` | `false` | Yes |
 | `ssrLabel` | `ssr-label` | Only required for SSR. Set to `true` if you're slotting in a `label` element so the server-rendered markup includes the label before the component hydrates on the client. | `boolean` | `false` | Yes |
-| `swatches` | `swatches` | One or more predefined color swatches to display as presets in the color picker. Can include any format the color picker can parse, including HEX(A), RGB(A), HSL(A), HSV(A), and CSS color names. Each color must be separated by a semicolon (`;`). Alternatively, you can pass an array of color values or an array of `{ color, label }` objects to this property using JavaScript. When using objects with labels, the label will be used for the swatch's accessible name instead of the raw color value. | `string \| string[] \| CsColorPickerSwatch[]` | `''` | — |
+| `swatches` | `swatches` | One or more predefined color swatches to display as presets in the color picker. Can include any format the color picker can parse, including HEX(A), RGB(A), HSL(A), HSV(A), and CSS color names. Each color must be separated by a semicolon (`;`). Alternatively, you can pass an array of color values or an array of `{ color, label }` objects to this property using JavaScript. When using objects with labels, the label will be used for the swatch's accessible name instead of the raw color value. A swatch can also be a design token, written as `var(--cs-name)` or `var(--cs-name, fallback)`, in any of these forms. The picker resolves it against its own computed style each time it opens, so a theme set on any ancestor applies, and selecting the swatch sets the resolved color in the picker's `format`. A swatch that doesn't resolve to a color the picker can parse is skipped, as is a `var()` of any custom property outside `--cs-*`. Without a label, a `var()` swatch is named after its custom property, so `var(--cs-color-brand-fill-loud)` is announced as "brand fill loud". | `string \| string[] \| CsColorPickerSwatch[]` | `''` | — |
 | `uppercase` | `uppercase` | By default, values are lowercase. With this attribute, values will be uppercase instead. | `boolean` | `false` | — |
 | `validationTarget` | — | Override this to change where constraint validation popups are anchored. | `undefined \| HTMLElement` | — | — |
 | `validators` | — | Validators are static because they have `observedAttributes`, essentially attributes to "watch" for changes. Whenever these attributes change, we want to be notified and update the validator. | `Validator[]` | `[]` | — |

package/dist/unbundled/skills/cornerstone/references/components/details.md

@@ -150,6 +150,33 @@ Use the `name` attribute to create accordion-like behavior where only one detail
 </div>
 ```
 
+### Reacting to Open & Close
+
+Listen for `cs-show` and `cs-hide` to keep your app's state in step with the details. Both fire on every open and close, whether it came from a click, the keyboard, code such as `show()`, or another details in the same `name` group. Neither fires for the `open` attribute a details starts with, so read the starting value from `open`.
+
+> **Warning**
+>
+> <strong>Don't read `open` in a `click` handler.</strong><br />
+> The details toggles inside its shadow root before the click reaches your listener on `<cs-details>` or any element around it, so `open` already holds the new state, not the old one. A click listener also runs for clicks that change nothing, such as clicks in the content, and never hears a toggle from the keyboard or from code.
+
+```html
+<div class="details-tracking cs-stack">
+  <cs-details summary="Shipping options">
+    Standard shipping takes three to five business days. Express shipping arrives the next business day.
+  </cs-details>
+  <p>Tracked state: <strong class="details-tracking-state">closed</strong></p>
+</div>
+
+<script type="module">
+  const demo = document.querySelector('.details-tracking');
+  const details = demo.querySelector('cs-details');
+  const state = demo.querySelector('.details-tracking-state');
+
+  details.addEventListener('cs-show', () => (state.textContent = 'open'));
+  details.addEventListener('cs-hide', () => (state.textContent = 'closed'));
+</script>
+```
+
 ## API
 
 ### Importing

package/dist/unbundled/skills/cornerstone/references/components/divider.md

@@ -36,12 +36,22 @@ Use the `--spacing` custom property to change the amount of space between the di
 </div>
 ```
 
+As a direct child of a layout utility such as `cs-stack` or `cs-cluster`, `--spacing` has no effect and the container's gap sets the space instead. These utilities set the margins of their children to zero, the divider included, so the gap is the only space between items. Add a [`cs-gap-*`](https://cruglobal.github.io/cornerstone-design-system/utilities/gap) class to the container to change it.
+
+```html
+<div class="cs-stack cs-gap-xl cs-text-center">
+  Above
+  <cs-divider></cs-divider>
+  Below
+</div>
+```
+
 ### Orientation
 
 The default orientation for dividers is `horizontal`. Set the `orientation` attribute to `vertical` to draw a vertical divider. The divider will span the full height of its [Flexbox](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox) or [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/grid) container.
 
 ```html
-<div class="cs-cluster cs-gap-0">
+<div class="cs-cluster">
   First
   <cs-divider orientation="vertical"></cs-divider>
   Middle
@@ -107,5 +117,5 @@ import CsDivider from '@cruglobal/cornerstone-components/react/divider/index.js'
 | Name | Description | Default |
 | --- | --- | --- |
 | `--color` | The color of the divider. | — |
-| `--spacing` | The spacing of the divider. | — |
+| `--spacing` | The margin on either side of the divider: above and below it when horizontal, left and right when vertical. As a direct child of a layout utility such as `cs-stack` or `cs-cluster`, the container's gap sets this space instead, so use a `cs-gap-*` class on the container to change it. | — |
 | `--width` | The width of the divider. | — |

package/dist/unbundled/skills/cornerstone/references/components/drawer.md

@@ -149,7 +149,7 @@ Use the `--size` custom property to set the drawer's size. This will be applied
 
 ### Scrolling
 
-By design, a drawer's height will never exceed 100% of its container. As such, drawers will not scroll with the page to ensure the header and footer are always accessible to the user.
+By design, a drawer's height will never exceed 100% of the viewport. As such, drawers will not scroll with the page to ensure the header and footer are always accessible to the user.
 
 ```html
 <cs-drawer label="Drawer" class="drawer-scrolling">

package/dist/unbundled/skills/cornerstone/references/components/page.md

@@ -4,11 +4,6 @@
 
 The page component is designed to power full webpages. It is flexible enough to handle most modern designs and includes a simple mechanism for handling desktop and mobile navigation.
 
-> **New**
->
-> <strong>Now Available in Cornerstone Core</strong><br />
-> Page moved over from Pro in [**3.5.0**](https://cruglobal.github.io/cornerstone-design-system/resources/changelog#wa_350). On an earlier Core version? Upgrade to use it.
-
 ## Layout Anatomy
 
 This image depicts a page's anatomy, including the default positions of each section. The labels represent the [named slots](#slots) you can use to populate them.
@@ -83,6 +78,12 @@ body {
 >
 > If you use [native styles](https://cruglobal.github.io/cornerstone-design-system/utilities/native/), this is already taken care of.
 
+### DOM Morphing
+
+`<cs-page>` writes the heights it measures to its own inline style, as [Header Heights](#header-heights) describes. DOM-diffing libraries such as Turbo 8 morph refreshes, idiomorph with htmx, and Alpine's morph plugin reset that inline style to the server's HTML, which doesn't have those heights.
+
+The page puts its measured heights back when that happens, and leaves the rest of the server's inline styles alone. You don't need a `turbo:before-morph-attribute` listener to keep Turbo off the page's `style` attribute.
+
 ## Examples
 
 > **Warning**
@@ -127,6 +128,30 @@ This is often desirable, but you can change this behavior using the `disable-sti
 <cs-page disable-sticky="header aside"> ... </cs-page>
 ```
 
+### Header Heights
+
+The page measures its `banner`, `header` and `subheader` and keeps each height in a custom property on itself: `--banner-height`, `--header-height` and `--subheader-height`. It uses them to place its sticky sections below one another. Your own styles can use them too, because everything inside the page inherits them. This makes the page's `<main>` a panel that fills the screen below the header and scrolls on its own:
+
+```css
+cs-page > main {
+  box-sizing: border-box;
+  block-size: calc(100dvh - var(--header-height));
+  overflow: auto;
+}
+```
+
+Each height is `0px` until the page has measured it, so a layout sized from one shifts when the page loads. The panel above starts as tall as the whole screen, then shrinks by the header's height.
+
+If you know a height ahead of time, set it on `<cs-page>` in your stylesheet, and the layout is right from the start. The page still measures, and its value replaces yours. So a guess that's a little off costs only a small shift, and the value stays right if the header's size changes later.
+
+```css
+cs-page {
+  --header-height: 64px;
+}
+```
+
+Set it on `cs-page` itself, not on `:root` or another ancestor. The page gives each height a `0px` default on its own element, and that default wins over a value inherited from above.
+
 ### Skip to Content
 
 The layout provides a "skip to content" link that's visually hidden until the user tabs into it. You don't have to do anything to configure this, unless you want to change the text displayed in the link. In that case, you can slot in your own text using the `skip-to-content` slot.
@@ -147,26 +172,59 @@ A page isn't very opinionated when it comes to responsive behaviors, but there a
 
 #### Default Slot Styles
 
-Each slot is a [flex container](https://developer.mozilla.org/en-US/docs/Glossary/Flex_Container) and specifies some flex properties so that your content is reasonably responsive by default.
+Most slots lay out the element you put in them, so its children are arranged before you write any styles. Each of these wrappers is a [flex container](https://developer.mozilla.org/en-US/docs/Glossary/Flex_Container) with a `--cs-space-m` gap between its children.
 
-The following slots specify `justify-content: space-between` and `flex-wrap: wrap` to evenly distribute child elements horizontally and allow them to wrap when space is limited.
+| Slot                                                                    | Direction | Alignment                                               | Wraps |
+| ----------------------------------------------------------------------- | --------- | ------------------------------------------------------- | ----- |
+| `header`, `subheader`, `main-header`                                    | row       | `align-items: center`, `justify-content: space-between` | yes   |
+| `main-footer`, `footer`                                                 | row       | `align-items: start`, `justify-content: space-between`  | yes   |
+| `banner`                                                                | row       | `align-items: center`, `justify-content: center`        | no    |
+| `navigation-header`, `navigation`, `navigation-footer`, `menu`, `aside` | column    | not set, so children stretch across                     | no    |
 
-- `header`
-- `subheader`
-- `main-header`
-- `main-footer`
-- `footer`
+The [desktop and mobile navigation slots](#different-navigation-on-mobile-and-desktop) are columns too, like the navigation slots they stand in for.
 
-The following slots specify `flex-direction: column` to arrange child elements vertically.
+The default slot is the exception. A `<main>` or `<section>` there gets padding, but its display is left alone.
 
-- `navigation-header`
-- `navigation` (or `menu`)
-- `navigation-footer`
-- `aside`
+#### Changing a Wrapper's Layout
+
+To arrange a wrapper's children another way, put [layout utilities](https://cruglobal.github.io/cornerstone-design-system/utilities/) on the wrapper instead of writing CSS for it. The defaults above are set from inside the page's shadow DOM, and a style on the slotted element itself always wins over them, whatever its specificity. So a utility class replaces a default outright.
+
+A navigation in two parts, such as an icon rail beside a list of links, is the usual case. The `navigation` wrapper is a column, so the parts stack until you make it a row.
+
+```html
+<cs-page>
+  ...
+  <nav slot="navigation" class="cs-split cs-align-items-stretch cs-justify-content-start">
+    <div class="cs-stack cs-gap-xs">
+      <cs-button appearance="plain" href="#home" data-drawer="close">
+        <cs-icon name="home" label="Home"></cs-icon>
+      </cs-button>
+      <cs-button appearance="plain" href="#search" data-drawer="close">
+        <cs-icon name="search" label="Search"></cs-icon>
+      </cs-button>
+      <cs-button appearance="plain" href="#settings" data-drawer="close">
+        <cs-icon name="settings" label="Settings"></cs-icon>
+      </cs-button>
+    </div>
+    <div class="cs-stack cs-gap-2xs">
+      <a href="#overview" data-drawer="close">Overview</a>
+      <a href="#reports" data-drawer="close">Reports</a>
+      <a href="#members" data-drawer="close">Members</a>
+    </div>
+  </nav>
+  ...
+</cs-page>
+```
+
+Each class does one job:
 
-And the `banner` slot specifies `justify-content: center` to horizontally center its child elements.
+- [`cs-split`](https://cruglobal.github.io/cornerstone-design-system/utilities/split/) makes the wrapper a row. It sets `flex-direction: row`, and `cs-cluster` sets no direction, so a cluster leaves the column in place.
+- `cs-align-items-stretch` runs both parts the full height of the navigation. A split centers its children by default, which floats a short rail to the middle.
+- `cs-justify-content-start` keeps the parts together. A split pushes its children to opposite ends, which opens a gap between them in the mobile drawer, or whenever `--menu-width` is wider than the parts.
 
-You can override the default display and flex properties for each slot with your own CSS.
+The split also puts a `--cs-space-m` gap between the parts. Add a [gap utility](https://cruglobal.github.io/cornerstone-design-system/utilities/gap/) to change it, such as `cs-gap-0` when the parts should meet edge to edge.
+
+On mobile the page moves this same wrapper into its drawer, classes included, so the parts stay side by side there as long as they fit. A split wraps, so when the drawer or a fixed `--menu-width` is narrower than both parts, the second part drops below the first.
 
 #### Responsive Navigation
 
@@ -206,6 +264,36 @@ cs-page[view='desktop'] [data-toggle-nav] {
 >
 > If you use [native styles](https://cruglobal.github.io/cornerstone-design-system/utilities/native/), this is handled for you, and the `data-toggle-nav` button is already hidden on wider screens.
 
+#### Different Navigation on Mobile and Desktop
+
+The navigation appears in two places: the sidebar on desktop and the drawer on mobile. The `navigation-header`, `navigation` and `navigation-footer` slots fill both. To show something different in one place, fill that place's own slot. It replaces the shared slot there, and the other place keeps showing the shared one.
+
+| Shared slot         | Sidebar only (desktop)      | Drawer only (mobile)       |
+| ------------------- | --------------------------- | -------------------------- |
+| `navigation-header` | `desktop-navigation-header` | `mobile-navigation-header` |
+| `navigation`        | `desktop-navigation`        | `mobile-navigation`        |
+| `navigation-footer` | `desktop-navigation-footer` | `mobile-navigation-footer` |
+
+A drawer often needs a title that the sidebar doesn't, because on desktop the page's header already names the app. This gives the drawer a header and leaves the sidebar without one.
+
+```html
+<cs-page>
+  <header slot="header">...</header>
+  <strong slot="mobile-navigation-header">Menu</strong>
+  <nav slot="navigation">...</nav>
+  ...
+</cs-page>
+```
+
+> **Warning**
+>
+> Don't use `cs-mobile-only` on a `navigation-header` to keep it out of the sidebar. It hides the header on desktop, but it breaks the sidebar's layout. The sidebar is a grid of three rows: the header, then the navigation in a row that grows to fill the column, then the footer. A hidden element drops out of that grid, so the navigation moves up into the header's row and stops filling the sidebar, and the footer moves up off the bottom. Use `mobile-navigation-header` instead, which leaves the sidebar's grid alone.
+
+Two gaps to know about for now:
+
+- **Content in a `desktop-navigation-*` slot still shows on mobile.** It stays at the side of the page, beside the main content, where the sidebar would be. Add `cs-desktop-only` to it as well. The sidebar isn't meant to show on mobile at all, so hiding its content there doesn't disturb anything.
+- **The menu button only appears when a shared slot has content.** The page decides whether to show its button from `navigation`, `navigation-header` and `navigation-footer` alone. If you fill only the `mobile-navigation-*` slots, add your own button with `data-toggle-nav`.
+
 #### Custom Widths
 
 You specify widths for some slots on your page with [CSS custom properties](#css-custom-properties) for `--menu-width`, `--main-width`, and `--aside-width`.
@@ -243,6 +331,10 @@ You can override the default spacing for each slot with your own CSS. In this ex
 }
 ```
 
+### Rules Between Regions
+
+The page doesn't offer a rule (divider) between its regions yet, such as a line under the header. There's no attribute that adds one, and no slot sits between two regions where a `<cs-divider>` could go.
+
 ## Utility Classes
 
 [Native styles](https://cruglobal.github.io/cornerstone-design-system/utilities/native/) define a few useful defaults for `<cs-page>`, as well as two utility classes you can use for common responsive design tasks:
@@ -250,6 +342,8 @@ You can override the default spacing for each slot with your own CSS. In this ex
 - `.cs-mobile-only` hides an element on the desktop view
 - `.cs-desktop-only` hides an element on the mobile view
 
+Before you use them on navigation content, read [Different Navigation on Mobile and Desktop](#different-navigation-on-mobile-and-desktop).
+
 ## API
 
 ### Importing
@@ -282,17 +376,24 @@ Valid slot names for this component (use exactly these — any other `slot` valu
 - `(default)` — The page's main content.
 - `aside` — Content to be shown on the right side of the page. Typically contains a table of contents, ads, etc. This section "sticks" to the top as the page scrolls.
 - `banner` — The banner that gets display above the header. The banner will not be shown if no content is provided.
+- `desktop-navigation` — The sidebar's content on desktop, in place of `navigation`. On mobile, `<cs-drawer>` still shows `navigation`.
+- `desktop-navigation-footer` — The sidebar's footer on desktop, in place of `navigation-footer`. On mobile, `<cs-drawer>` still shows `navigation-footer`.
+- `desktop-navigation-header` — The sidebar's header on desktop, in place of `navigation-header`. On mobile, `<cs-drawer>` still shows `navigation-header`.
 - `footer` — The content to display in the footer. This is always displayed underneath the viewport so will always make the page "scrollable".
 - `header` — The header to display at the top of the page. If a banner is present, the header will appear below the banner. The header will not be shown if there is no content.
 - `main-footer` — Footer to display inline below the main content.
 - `main-header` — Header to display inline above the main content.
 - `menu` — The left side of the page. If you slot an element in here, you will override the default `navigation` slot and will be handling navigation on your own. This also will not disable the fallback behavior of the navigation button. This section "sticks" to the top as the page scrolls.
+- `mobile-navigation` — The content of `<cs-drawer>` on mobile, in place of `navigation`. On desktop, the sidebar still shows `navigation`.
+- `mobile-navigation-footer` — The footer for `<cs-drawer>` on mobile, in place of `navigation-footer`. On desktop, the sidebar still shows `navigation-footer`.
+- `mobile-navigation-header` — The header for `<cs-drawer>` on mobile, in place of `navigation-header`. On desktop, the sidebar still shows `navigation-header`. Use it for a header only the drawer should have.
 - `navigation` — The main content to display in the navigation area. This is displayed on the left side of the page, if `menu` is not used. This section "sticks" to the top as the page scrolls.
 - `navigation-footer` — The footer for a navigation area. On mobile this will be the footer for `<cs-drawer>`.
 - `navigation-header` — The header for a navigation area. On mobile this will be the header for `<cs-drawer>`.
 - `navigation-toggle` — Use this slot to slot in your own button + icon for toggling the navigation drawer. By default it is a `<cs-button>` + a 3 bars `<cs-icon>`
 - `navigation-toggle-icon` — Use this to slot in your own icon for toggling the navigation drawer. By default it is 3 bars `<cs-icon>`.
 - `skip-to-content` — The "skip to content" slot. You can override this If you would like to override the `Skip to content` button and add additional "Skip to X", they can be inserted here.
+- `skip-to-content-target` — Where the "skip to content" link lands. If the document has no element with `id="main-content"`, the page adds an empty one to this slot, at the start of the main content. You don't need to fill it. To choose where the link lands, put `id="main-content"` on your own element in the main content.
 - `subheader` — A subheader to display below the `header`. This is a good place to put things like breadcrumbs.
 
 ### Attributes & Properties

package/dist/unbundled/skills/cornerstone/references/components/toast-item.md

@@ -9,11 +9,6 @@
 </cs-toast-item>
 ```
 
-> **New**
->
-> <strong>Now Available in Cornerstone Core</strong><br />
-> Toast Item moved over from Pro in [**3.11.0**](https://cruglobal.github.io/cornerstone-design-system/resources/changelog#unreleased). On an earlier Core version? Upgrade to use it.
-
 > **Info**
 >
 > <strong>Toast items are meant to live inside a `<cs-toast>` container.</strong><br />

package/dist/unbundled/skills/cornerstone/references/components/toast.md

@@ -19,11 +19,6 @@
 </script>
 ```
 
-> **New**
->
-> <strong>Now Available in Cornerstone Core</strong><br />
-> Toast moved over from Pro in [**3.11.0**](https://cruglobal.github.io/cornerstone-design-system/resources/changelog#unreleased). On an earlier Core version? Upgrade to use it.
-
 Adding a single `<cs-toast>` element to the page gives you the ability to dispatch notifications at any time. Toast notifications appear in a stack that renders in the [top layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer), showing above everything else on the page.
 
 You can put the `<cs-toast>` element anywhere in the DOM, as long as it's somewhere inside the `<body>`. In most apps, a single toast element is optimal.

package/dist/unbundled/skills/cornerstone/references/frameworks/rails.md

@@ -144,7 +144,8 @@ preventTurboFouce();
 
 It hooks `turbo:before-render`, holds the render until every component in the incoming body has registered,
 and gives up after two seconds so a failed import cannot wedge navigation. Pair it with the `cs-cloak` class
-for the initial load — both are covered on [Reducing FOUCE](https://cruglobal.github.io/cornerstone-design-system/utilities/fouce).
+for the initial load — both are covered on [Reducing FOUCE](https://cruglobal.github.io/cornerstone-design-system/utilities/fouce). Read the caution there before you
+put the class on `<body>`.
 
 ## Stimulus
 
@@ -174,9 +175,28 @@ export default class extends Controller {
 ```
 
 Note the event name. Form controls emit **native-named** events — `change`, `input`, `focus`, `blur` — so a
-Stimulus action for `<cs-select>` reads exactly as it would for a native `<select>`. The `cs-` prefix is
+Stimulus action for `<cs-select>` names the same event it would for a native `<select>`. The `cs-` prefix is
 reserved for events with no native equivalent, like `<cs-select>`'s own `cs-clear`.
 
+> **Warning**
+>
+> **Always write the event in a Stimulus action on a `cs-*` element.** On a few native elements Stimulus lets
+> you leave the event out and fills in a default, such as `click` for `<button>` and `change` for `<select>`.
+> It picks that default by tag name, and no `cs-*` tag is on its list. So a bare `modal#open` on a
+> `<cs-button>` never binds, and nothing tells you: Stimulus throws `missing event name` while it reads the
+> attribute, then catches that error itself and never reports it. The console stays empty.
+>
+> ```erb
+> <%# Before: never fires, and logs nothing %>
+> <cs-button data-action="modal#open">Open</cs-button>
+>
+> <%# After %>
+> <cs-button data-action="click->modal#open">Open</cs-button>
+> ```
+>
+> Write the event Stimulus would have filled in for the native element: `click->` on `<cs-button>`, `input->`
+> on `<cs-input>` and `<cs-textarea>`, and `change->` on `<cs-select>`.
+
 Read the value off the element rather than the event, as you would natively: `event.target.value`.
 
 ## What has been verified
@@ -198,6 +218,9 @@ Read the value off the element rather than the event, as you would natively: `ev
 > - **Propshaft for the stylesheet** — the theme's fonts applied, so the `@import` chain resolved. The logical
 >   path and the `:app` behaviour above were both measured against Propshaft's own resolver.
 >
+> The Stimulus warning was checked outside that app, against Stimulus 3.2.2: in its source, and by running it
+> under jsdom, where a bare action on a `cs-*` element bound nothing and logged nothing.
+>
 > Two things worth knowing before you copy into `public/`: `npm install` in a generated Rails app creates a
 > `package.json` and lock file at the app root, since one does not exist; and the copy is **11 MB across 1,114
 > files, all web-served** — 350 `.d.ts`, 142 React wrappers and the agent skill included. A three-component page