@cruglobal/cornerstone-components 0.6.2 → 0.7.0

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

@@ -0,0 +1,240 @@
+# Tailwind CSS
+
+**Full documentation:** https://cruglobal.github.io/cornerstone-design-system/frameworks/tailwind
+
+<div class="cs-cluster cs-gap-2xs cs-not-prose">
+  <cs-badge variant="success" appearance="filled" pill>
+    <cs-icon name="check_circle" slot="start"></cs-icon>Verified on Tailwind 4.3
+  </cs-badge>
+  <cs-badge variant="neutral" appearance="filled" pill>Tailwind CLI</cs-badge>
+  <cs-badge variant="neutral" appearance="filled" pill>esbuild</cs-badge>
+</div>
+
+Partway through a move from Tailwind v4 to Cornerstone Components, an app runs both on the same page. That works,
+but not with the obvious setup. Four things go wrong:
+
+1. **The Cornerstone Components stylesheet never loads.** Tailwind leaves its `@import url()` lines in place, and
+   the browser either skips them or looks for the files in the wrong folder.
+2. **Preflight flattens components.** Tailwind's reset strips the padding, margins and borders that components give
+   themselves, so dropdown items lose their padding and dividers disappear.
+3. **Spacing utilities grow inside some components.** Tailwind's `--spacing` unit has the same name as a component
+   property, so `p-4` inside a card comes out six times too big.
+4. **The wrong library wins.** Whichever one you import second outranks the other, so either Preflight undoes
+   the styles Cornerstone Components gives native elements, or Cornerstone Components overrides your Tailwind
+   classes.
+
+The setup below fixes all four with one script that runs before Tailwind and one entry stylesheet.
+[Why each piece is there](#why-each-piece-is-there) says what breaks without it.
+
+## Setup
+
+Install esbuild alongside Tailwind. The script uses it to flatten the Cornerstone Components stylesheet.
+
+```bash
+npm install @cruglobal/cornerstone-components tailwindcss @tailwindcss/cli esbuild
+```
+
+Save this script at the root of your project:
+
+```js
+// build-cornerstone-css.mjs: run before every Tailwind build.
+import { build } from 'esbuild';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const out = 'tmp/cornerstone';
+mkdirSync(out, { recursive: true });
+
+// 1. The Cornerstone Components stylesheet, flattened into one file.
+await build({
+  entryPoints: [require.resolve('@cruglobal/cornerstone-components/styles/cornerstone.css')],
+  bundle: true,
+  outfile: `${out}/cornerstone.css`,
+});
+
+// Tag names from the manifest the package ships, so both lists follow the package.
+const manifest = require('@cruglobal/cornerstone-components/custom-elements.json');
+const components = manifest.modules.flatMap((module) => module.declarations ?? []).filter((d) => d.tagName);
+const tags = components.map((d) => d.tagName).join(', ');
+const spacingTags = components
+  .filter((d) => d.cssProperties?.some((property) => property.name === '--spacing'))
+  .map((d) => d.tagName)
+  .join(', ');
+
+// 2. Preflight, with its universal reset kept off every cs-* element.
+const preflight = readFileSync(require.resolve('tailwindcss/preflight.css'), 'utf8');
+const resetSelector = '*,\n::after,';
+if (!preflight.includes(resetSelector)) {
+  throw new Error('tailwindcss/preflight.css no longer opens with `*,`. Update this script.');
+}
+writeFileSync(`${out}/preflight.css`, preflight.replace(resetSelector, `:where(:not(${tags})),\n::after,`));
+
+// 3. Tailwind's spacing unit, back on the content of components with a --spacing of their own.
+const rule = `:is(${spacingTags}) > :not(${spacingTags}) {\n  --spacing: --theme(--spacing inline);\n}\n`;
+writeFileSync(`${out}/spacing.css`, spacingTags ? rule : '');
+```
+
+It writes three files to `tmp/cornerstone/`. Keep that folder out of git, because the files are rebuilt from
+whatever versions are installed. Keep it out of anything your asset pipeline serves on its own, too: the files are
+input for Tailwind, not stylesheets to link. Rails' `stylesheet_link_tag :app`, for one, links every CSS file under
+`app/assets`.
+
+Import the three files from your Tailwind entry stylesheet, in this order. The paths are relative to the entry file,
+so adjust them if yours lives in another folder.
+
+```css
+/* app.css */
+@layer theme, base, cornerstone, components, utilities;
+
+@import 'tailwindcss/theme.css' layer(theme);
+@import './tmp/cornerstone/preflight.css' layer(base);
+@import './tmp/cornerstone/spacing.css' layer(base);
+@import './tmp/cornerstone/cornerstone.css' layer(cornerstone);
+@import 'tailwindcss/utilities.css' layer(utilities);
+```
+
+Then run the script ahead of every Tailwind build:
+
+```json
+{
+  "scripts": {
+    "build:css": "node build-cornerstone-css.mjs && tailwindcss -i app.css -o build/app.css"
+  }
+}
+```
+
+Load the components the way you would without Tailwind. See [Installation](https://cruglobal.github.io/cornerstone-design-system/#loading-the-library).
+
+## Why each piece is there
+
+### Flattening the stylesheet
+
+`styles/cornerstone.css` is a chain of `@import url()` lines, and the files it imports import more. A browser
+follows the chain. Tailwind does not: it inlines imports written as quoted paths, and it
+[keeps `url()` imports in its output as they are](https://github.com/tailwindlabs/tailwindcss/blob/v4.3.3/packages/tailwindcss/src/at-import.ts#L106-L110).
+
+So `@import '@cruglobal/cornerstone-components/styles/cornerstone.css'` in a Tailwind entry builds without an error
+and loads nothing from Cornerstone Components: no theme, no native styles, no utilities. How it fails depends on
+where you put it:
+
+- **After `@import 'tailwindcss'`**, the lines sit below Tailwind's own rules, and
+  [an `@import` after other rules is invalid](https://www.w3.org/TR/css-cascade-5/#at-import). The browser skips
+  them with no request and no console message, so there is nothing to spot.
+- **Before it**, the lines stay at the top, and the browser looks for each file next to the compiled stylesheet,
+  where none of them are. Each one is a 404.
+
+The script's first step bundles the chain into one file with esbuild, which Tailwind can inline.
+
+### The Preflight copy
+
+[Preflight](https://tailwindcss.com/docs/preflight) is Tailwind's set of base styles, and it opens with a reset on
+every element:
+
+```css
+*,
+::after,
+::before,
+::backdrop,
+::file-selector-button {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+  border: 0 solid;
+}
+```
+
+Each `cs-*` component sets its own padding, margins and borders on its host element, from inside its shadow root
+with `:host`. Any rule in the page that matches the same element beats a `:host` rule, whatever its layer or
+specificity, because the cascade [compares where a rule comes from](https://www.w3.org/TR/css-cascade-5/#cascade-context)
+first. So `*` wins: dropdown items lose their padding, dividers lose their line and margins, and cards lose their
+border. No layer order can fix that, which is why the script edits Preflight instead.
+
+The copy changes only that one selector, to `:where(:not(cs-badge, cs-button, …))`. The reset skips every `cs-*`
+element and still reaches everything else, and `:where()` keeps its specificity at zero, the same as `*`. The tag
+list comes from the `custom-elements.json` the package ships, so a new component is covered when you update. If a
+later Tailwind release changes how Preflight opens, the script stops with an error rather than writing a copy that
+still resets components.
+
+Tailwind [documents importing Preflight on its own](https://tailwindcss.com/docs/preflight#disabling-preflight),
+which is what lets the copy stand in for it. Leaving Preflight out is the other way to stop the reset. Keep it if the
+markup you have not ported yet depends on it.
+
+### The spacing reset
+
+Tailwind v4 builds its spacing utilities from one theme variable: [`p-4` is `calc(var(--spacing) * 4)`](https://tailwindcss.com/docs/padding),
+and [`--spacing` is `0.25rem`](https://tailwindcss.com/docs/theme) unless you change it. Some `cs-*` components
+have a `--spacing` property of their own, set on their host. Custom properties inherit, so content inside those
+components reads the component's value instead of Tailwind's. In the checks below, `p-4` came out 96px instead of
+16px inside a `<cs-card>`.
+
+The script finds those components in `custom-elements.json` (they are the ones whose API reference lists
+`--spacing`) and writes one rule for them:
+
+```css
+:is(cs-card, cs-details, …) > :not(cs-card, cs-details, …) {
+  --spacing: --theme(--spacing inline);
+}
+```
+
+- **The `>` reaches the component's own children**, the content you put in it, and everything deeper inherits from
+  them. The component's shadow root still reads the host's value, so a card keeps its own padding.
+- **The `:not(…)` skips those same components** when one sits right inside another. Without it, a `<cs-divider>`
+  placed straight in a card takes Tailwind's unit as its own spacing, and its margins shrink from 16px to 4px.
+- **`--theme(--spacing inline)` writes Tailwind's value**, `0.25rem` or whatever your `@theme` sets. The `inline`
+  matters. Without it Tailwind writes `var(--spacing)`, a property that
+  [refers to itself](https://www.w3.org/TR/css-variables-1/#cycles), which CSS treats as invalid, and every spacing
+  utility inside the component computes to nothing. Tailwind's documentation does not describe `--theme()`, but its
+  `inline` option is [in Tailwind's source](https://github.com/tailwindlabs/tailwindcss/blob/v4.3.3/packages/tailwindcss/src/css-functions.ts#L99-L103),
+  and Tailwind's own Preflight uses the function.
+
+This is a workaround. Whether the components' `--spacing` should be renamed so the two stop clashing is
+[an open decision](https://github.com/CruGlobal/cornerstone-design-system/issues/182), so keep the rule until it is
+settled. If a later release drops `--spacing` from every component, the script writes an empty file and the rule is
+gone.
+
+### The layer order
+
+Both libraries put their page styles in [cascade layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
+Tailwind declares `theme`, `base` (where Preflight lives), `components` and `utilities`. Cornerstone Components
+declares its own `cs-*` layers in `styles/layers.css`, starting with its native element styles. Layers rank in the
+order they are first named, so with no statement at the top, the library you import second outranks the first:
+
+- **Cornerstone Components first:** Preflight outranks Cornerstone Components' native element styles. Plain
+  headings shrink to body text and lists lose their bullets.
+- **Tailwind first:** Cornerstone Components outranks every Tailwind utility. `text-sm mb-8` on a heading does
+  nothing, and `bg-red-600` on a button loses to Cornerstone Components' button style.
+
+The statement puts Preflight lowest, then Cornerstone Components, then Tailwind's components and utilities. So the
+native element styles win over the reset, and any Tailwind class you write still wins over Cornerstone Components.
+
+`layer(cornerstone)` puts all of Cornerstone Components into one layer, with its own layers nested inside in their
+own order. Naming its layers one by one in the statement gives the same result today. The difference is later: a
+layer the statement does not name ranks after `utilities`, so a layer added in a future Cornerstone Components
+release would outrank every Tailwind class. One parent layer cannot fall out of step.
+
+## What has been verified
+
+> **Info**
+>
+> Checked in a scratch project with Tailwind CSS 4.3.3, the Tailwind CLI, esbuild 0.28.2 and this package at 0.6.2, in
+> headless Chromium, Firefox and WebKit. Each problem was reproduced first and then shown fixed by the setup above, with
+> the same numbers in all three browsers.
+>
+> - **The `@import url()` chain:** Tailwind kept the lines. Placed after Tailwind, every browser dropped them with no
+>   request and no console message. Placed before it, every browser requested them from the compiled file's folder and
+>   got 404s. Either way, no `--cs-*` token was set. The flattened file gave the same value for every standard
+>   property on the test page, in light and dark. The only differences were in how esbuild spaces and quotes a few
+>   custom property values.
+> - **Preflight:** `<cs-dropdown-item>` had no padding, and `<cs-divider>` had no line or margins. With the copy, the
+>   item had 8px by 16px of padding and the divider a 1px line with 16px margins.
+> - **`--spacing`:** `p-4` came out 96px inside `<cs-card>`, `<cs-dialog>` and `<cs-drawer>`, and 64px inside
+>   `<cs-details>` and `<cs-accordion-item>`. With the reset it was 16px in all five, and the card kept its 24px padding.
+>   Without `inline`, `p-4` came out 0. Without `:not(…)`, a divider straight in a card dropped to 4px margins. A custom
+>   `--spacing` in `@theme` carried through to the reset.
+> - **Layer order:** both failures above were reproduced. With the statement, Cornerstone Components' heading styles
+>   and list bullets held, and `text-sm`, `mb-8` and `bg-red-600` all applied. Naming Cornerstone Components' layers
+>   one by one instead of using `layer(cornerstone)` gave the same value for every property.
+>
+> **Not yet verified:** Tailwind's Vite and PostCSS plugins. The `url()` handling is in Tailwind's core, but a bundler
+> can process imports before Tailwind sees them, so check your compiled CSS for any leftover `@import url(` lines.

package/dist/unbundled/skills/cornerstone/references/installation.md

@@ -135,6 +135,28 @@ its components have registered:
 The autoloader removes it as soon as discovery completes, or after two seconds, whichever comes first.
 See [Reducing FOUCE](https://cruglobal.github.io/cornerstone-design-system/utilities/fouce).
 
+## Building with Claude Code
+
+If your team uses [Claude Code](https://claude.ai/code), commit this to your app's
+`.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "cru": { "source": { "source": "github", "repo": "CruGlobal/cornerstone-design-system" } }
+  },
+  "enabledPlugins": { "cornerstone@cru": true }
+}
+```
+
+It installs the `cornerstone` plugin for everyone who opens the project, once they trust the folder.
+The plugin carries Cornerstone's two [Agent Skills](https://cruglobal.github.io/cornerstone-design-system/ai/agent-skills), read from the copy inside your
+installed package so they match its version, and a check at the start of each session that points
+Claude at the design skill before it writes UI. Without them, Claude tends to rebuild what the
+components and layout utilities already do in custom CSS. It also adds Daniel, Cornerstone's
+assistant, whom you can ask for by name. See [Agent Skills](https://cruglobal.github.io/cornerstone-design-system/ai/agent-skills) for the details and
+for other AI tools.
+
 ## Where to start
 
 - **Components** — the reference for all 70 elements, grouped by what they are for.

package/dist/unbundled/skills/cornerstone/references/utilities/fouce.md

@@ -30,3 +30,18 @@ import { preventTurboFouce } from '/dist/cornerstone.js';
 
 preventTurboFouce();
 ```
+
+> **Warning**
+>
+> **`cs-cloak` on `<html>` or `<body>` can blank the whole page long after it has loaded.** The cloak is a CSS rule,
+> not a one-time step. While an element has the class, it goes invisible whenever it holds a custom element that is not
+> defined yet, and stays invisible until every one is defined or two seconds pass. Any custom element counts, not only
+> `cs-*` ones, and it can happen again each time a new one appears. Pasting into a block editor is one way to hit it.
+>
+> `cornerstone.loader.js` removes the class once, when the first page's components have loaded or two seconds have
+> passed, and nothing else in the library removes it. Load the library without the loader and the class stays on.
+> Under Turbo it comes back on every visit, because each new `<body>` arrives with the classes your layout gave it.
+>
+> So if your app adds elements after the page loads, put `cs-cloak` only on the region that needs it, and not around
+> the part that adds them. `<html>` or `<body>` is only safe when the loader has removed the class and nothing puts it
+> back.

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

@@ -10,7 +10,7 @@ description: >
   composition. Pair with the `cornerstone` skill, which documents individual component APIs.
 license: MIT
 metadata:
-  version: "0.6.2"
+  version: "0.7.0"
   author: Cornerstone
   homepage: https://cruglobal.github.io/cornerstone-design-system
 compatibility: Works in modern browsers. Requires no build tools when using the CDN. Works with bundlers like Webpack and Vite when installed via npm.
@@ -23,7 +23,7 @@ and compose interfaces that look intentionally designed rather than merely funct
 important habit is to **lean into Cornerstone's design system first** — its components, layout utilities,
 tokens, and styling API — and reach for custom CSS only when the system genuinely doesn't cover the need
 (see "Use Cornerstone's design system first" below). For the API of any single component (props, slots,
-events), use the companion `cornerstone` skill or [llms.txt](https://cruglobal.github.io/cornerstone-design-system/docs/ai/).
+events), use the companion `cornerstone` skill or [llms.txt](https://cruglobal.github.io/cornerstone-design-system/ai/).
 
 Read this file first. It routes you to the right reference and states the rules that matter most.
 
@@ -96,7 +96,7 @@ Before you write a custom class, a raw `flex`/`grid` rule, a hardcoded value, or
 **work down this ladder and stop at the first rung that does the job:**
 
 1. **A component.** Is there already a `<cs-*>` for this (button, card, dialog, dropdown, input, tabs, …)?
-   Use it instead of assembling the same thing from `<div>`s. Check the companion [`cornerstone` skill](https://cruglobal.github.io/cornerstone-design-system/docs/ai/) before building UI by hand. **Watch for these commonly re-invented ones:**
+   Use it instead of assembling the same thing from `<div>`s. Check the companion [`cornerstone` skill](https://cruglobal.github.io/cornerstone-design-system/ai/) before building UI by hand. **Watch for these commonly re-invented ones:**
    a "featured/Most Popular" pricing tier is a `<cs-card>` with a `<cs-badge>` in its header slot (not an
    absolutely-positioned hand-rolled ribbon); a section separator is `<cs-divider>` (not a styled `<hr>`);
    a pill/label is `<cs-tag>` or `<cs-badge>`; a quote mark, check bullet, or star rating is `<cs-icon>` /
@@ -113,7 +113,7 @@ Before you write a custom class, a raw `flex`/`grid` rule, a hardcoded value, or
 4. **The component's styling API.** Need a component to look different? **First look up that specific
    component's documented styling API** — its **attributes** (`variant`, `appearance`, `size`, `pill`, …),
    its **CSS custom properties** (`--cs-*` it exposes), and its **CSS parts** (`::part(...)`) — in the
-   companion [`cornerstone` skill](https://cruglobal.github.io/cornerstone-design-system/docs/ai/) (or [llms.txt](https://cruglobal.github.io/cornerstone-design-system/docs/ai/)).
+   companion [`cornerstone` skill](https://cruglobal.github.io/cornerstone-design-system/ai/) (or [llms.txt](https://cruglobal.github.io/cornerstone-design-system/ai/)).
    Then style through that API in this order: **attributes → component tokens → `::part()`**. Never guess a
    token name, a part name, or which token a `variant` resolves to, and never fight the shadow DOM with host
    CSS. This lookup is **mandatory** — see rule 9 below. (Also composition.md.)
@@ -130,6 +130,27 @@ system already has it, and using it gives you theming, dark mode, accessibility,
 
 ---
 
+## Porting an existing app from another framework
+
+Moving a page or app to Cornerstone from another framework (a utility framework, a component kit, or your
+own hand-written CSS) is a new build on Cornerstone, not the old app restyled. The old look belongs to the
+old framework, and carrying it over builds the parallel design language the ladder above rules out.
+
+1. **Strip the old framework's classes.** Remove its utility and component classes from every element you
+   port, including `<html>`, `<body>`, and the layout wrappers. Left in place, they keep styling the page
+   and fight Cornerstone's own styles, so you can't tell which one is doing the work.
+2. **Let Cornerstone's theme set the look.** Matching the old spacing, sizes, colors, and borders by hand in
+   custom CSS builds a second design on top of Cornerstone's. You maintain it, and it overrides the theme
+   instead of following it.
+3. **Start from Cornerstone's defaults.** Use each component (and `<cs-page>`, for a full page) as shipped,
+   and look at the result first. Then change only what needs it, working down the ladder above.
+
+**Already carrying custom CSS from the old look?** Switch each declaration off and look at the page at each
+breakpoint, in light and dark, and in each interactive state (hover, focus, open). Delete every one whose
+removal changes nothing in any of them. In one real port, most of them changed nothing.
+
+---
+
 ## The rules that matter most
 
 These are the things that go wrong most often. Treat them as hard constraints.
@@ -147,8 +168,8 @@ These are the things that go wrong most often. Treat them as hard constraints.
    page CSS, classes, and `color`/`background` declarations **do not reach inside them** and **`variant`
    colors resolve through tokens you cannot guess**. Before you write **any** custom CSS that targets a
    `<cs-*>` element — or that sets a `--cs-*` token expecting that element to consume it — **open that exact
-   component's reference** in the companion [`cornerstone` skill](https://cruglobal.github.io/cornerstone-design-system/docs/ai/)
-   (`references/components/<name>.md`) or [llms.txt](https://cruglobal.github.io/cornerstone-design-system/docs/ai/) and read its
+   component's reference** in the companion [`cornerstone` skill](https://cruglobal.github.io/cornerstone-design-system/ai/)
+   (`references/components/<name>.md`) or [llms.txt](https://cruglobal.github.io/cornerstone-design-system/ai/) and read its
    **CSS Parts**, **CSS Custom Properties**, **Attributes** (`variant`/`appearance`/`size`/…), and any
    **Styling** notes. Then style **only** through what that doc lists, in this order: **attributes →
    the component's own tokens → its documented `::part()`**.
@@ -187,7 +208,7 @@ These are the things that go wrong most often. Treat them as hard constraints.
 
    **Contrast on colored bands (a separate, equally common button bug).** Even with correct `::part(button)` usage, a button can vanish because its colors match the band it sits on. **Never place an `appearance="outlined"` or `appearance="plain"` button whose `variant` matches the band color** — e.g. `<cs-button variant="brand" appearance="outlined">` on a brand-colored hero or CTA. The outline and label are the same hue as the background, so the button is effectively invisible (this is exactly what happened on the brand-colored hero bands of multiple pages). On any colored band, a secondary button must use a **contrasting** treatment: a solid/filled neutral or on-color button, or an outline/text recolored via `::part(button)` to the band's on-color token (`--cs-color-*-on-loud`, or a surface token). After placing any button on a non-default background, verify its label **and** border are clearly visible against that band.
 
-10. **Use `<cs-icon>` for icons; never emojis.** Don't put emojis in the UI unless the user explicitly asks for them — and that includes the places they sneak in: logos, image-`alt`/placeholder text, list bullets, decorative `::before` content, and JS-injected toast/success messages. Reach for the [`<cs-icon>`](https://cruglobal.github.io/cornerstone-design-system/docs/components/icon) component instead. The default icon library is Material Symbols (sharp), whose names are snake_case. Brand logos come from the separate `brands` library. Search [fonts.google.com/icons](https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Sharp) rather than guessing a name — a name that doesn't exist renders nothing. See [references/composition.md](references/composition.md) for usage.
+10. **Use `<cs-icon>` for icons; never emojis.** Don't put emojis in the UI unless the user explicitly asks for them — and that includes the places they sneak in: logos, image-`alt`/placeholder text, list bullets, decorative `::before` content, and JS-injected toast/success messages. Reach for the [`<cs-icon>`](https://cruglobal.github.io/cornerstone-design-system/components/icon) component instead. The default icon library is Material Symbols (sharp), whose names are snake_case. Brand logos come from the separate `brands` library. Search [fonts.google.com/icons](https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Sharp) rather than guessing a name — a name that doesn't exist renders nothing. See [references/composition.md](references/composition.md) for usage.
 11. **Keep markup valid and accessible.** Use real heading elements for hierarchy (`<h2>`/`<h3>`/`<h4>`) — don't fake a heading with a styled `<strong>`, which breaks the document outline. Give icon-only controls a `label` (or `aria-label`) and images meaningful `alt`. Never put two `style` attributes on one element — the second silently wins; merge them (or, per Rule 8, use a class).
 
 ---

package/dist/unbundled/skills/cornerstone-design/references/composition.md

@@ -202,7 +202,7 @@ Font sizes follow a 1.125 modular scale (`--cs-font-size-*`):
 
 ## Icons
 
-Use the [`<cs-icon>`](https://cruglobal.github.io/cornerstone-design-system/docs/components/icon) component for icons. **Never use
+Use the [`<cs-icon>`](https://cruglobal.github.io/cornerstone-design-system/components/icon) component for icons. **Never use
 emojis in the UI** unless the user explicitly asks for them — emojis render inconsistently across
 platforms and don't inherit color, size, or weight the way icons do.
 
@@ -493,7 +493,7 @@ cs-button.full-width-control::part(button) {
 ```
 
 **Look up each component's parts, custom properties, and attributes in the
-[`cornerstone` skill](https://cruglobal.github.io/cornerstone-design-system/docs/ai/)** (the companion component-API skill) or that
+[`cornerstone` skill](https://cruglobal.github.io/cornerstone-design-system/ai/)** (the companion component-API skill) or that
 component's docs page — every component lists its "CSS parts" and "CSS custom properties." Do this for
 **whatever** `<cs-*>` element you're styling, not just the common ones; the right hook differs by
 component. Don't guess internal class names — they aren't stable and aren't selectable. If a component

package/dist/unbundled/skills/cornerstone-design/references/layouts-page.md

@@ -10,7 +10,7 @@ named regions and let the component do the work. Do **not** rebuild any of this
 `display: grid`, no media queries for the nav/sidebar/toggle, no hand-rolled mobile drawer, no manual
 show/hide of a hamburger. Every time you reach for one of those, stop — `<cs-page>` already does it.
 
-Full docs: https://cruglobal.github.io/cornerstone-design-system/docs/components/page
+Full docs: https://cruglobal.github.io/cornerstone-design-system/components/page
 
 ---
 
@@ -214,7 +214,7 @@ utilities instead (see [layouts-inpage.md](layouts-inpage.md)).
    }
    ```
 
-   (If you use [native styles](https://cruglobal.github.io/cornerstone-design-system/docs/utilities/native/), this is already handled.)
+   (If you use [native styles](https://cruglobal.github.io/cornerstone-design-system/utilities/native/), this is already handled.)
 
 2. **`<cs-page>` provides no semantic elements.** It does not emit `<main>`, `<header>`, `<footer>`,
    etc. Slot your own:
@@ -469,6 +469,30 @@ navigation sidebar, main content, a sticky table-of-contents aside, and a footer
 
 ---
 
+## Slot wrappers have a layout; change it with utilities
+
+`<cs-page>` lays out the element you slot into each region. The `navigation` wrapper, for one, is a column.
+The [Default Slot Styles](https://cruglobal.github.io/cornerstone-design-system/components/page/#default-slot-styles)
+table in the Page docs lists every slot's defaults, and so does `references/components/page.md` in the
+companion `cornerstone` skill.
+
+A style on the slotted element always beats these defaults, so **to rearrange a wrapper, put layout
+utilities on it; don't write CSS.** For a rail beside a sidebar in `slot="navigation"`:
+
+```html
+<nav slot="navigation" class="cs-split cs-align-items-stretch cs-justify-content-start">
+  <div class="cs-stack cs-gap-xs"><!-- rail: icon-only cs-buttons --></div>
+  <div class="cs-stack cs-gap-2xs"><!-- sidebar: links --></div>
+</nav>
+```
+
+`cs-split` makes the row (`cs-cluster` sets no direction, so the column stays). `cs-align-items-stretch`
+runs both parts full height instead of centering them. `cs-justify-content-start` stops the split pushing
+them apart in the mobile drawer. Add `cs-gap-0` if the parts should meet edge to edge. A split wraps, so a
+fixed `--menu-width` must fit both parts.
+
+---
+
 ## Anti-patterns
 
 | ❌ Don't                                                                                                         | ✅ Do                                                                                                                                                                               |
@@ -540,7 +564,7 @@ during SSR. When rendering on the server, know:
 
 ## API reference
 
-For the authoritative, always-current API, see the [page component docs](https://cruglobal.github.io/cornerstone-design-system/docs/components/page)
+For the authoritative, always-current API, see the [page component docs](https://cruglobal.github.io/cornerstone-design-system/components/page)
 or the `cornerstone` skill. This is a working summary.
 
 ### Slots

package/dist/unbundled/skills/cornerstone-design/references/theming.md

@@ -8,7 +8,7 @@ For the _why_ behind WA's three-layer color system — why semantic tokens beat
 `*-on-*` pairings are non-negotiable, and how to avoid the "accessible but ugly" trap — see
 [principles.md § Color](principles.md#1-color-less-is-more-and-never-alone).
 
-Full docs: https://cruglobal.github.io/cornerstone-design-system/docs/themes
+Full docs: https://cruglobal.github.io/cornerstone-design-system/themes
 
 ---
 
@@ -134,7 +134,7 @@ Any `--cs-*` token can be overridden at any scope. Common knobs:
 
 Scope overrides to a subtree by putting them on a selector other than `:root`. See
 [composition.md](composition.md) for the spacing/typography scales and for styling component internals
-via `::part()`, and [customizing](https://cruglobal.github.io/cornerstone-design-system/docs/customizing/) for the full reference.
+via `::part()`, and [customizing](https://cruglobal.github.io/cornerstone-design-system/customizing/) for the full reference.
 
 ---