@cruglobal/cornerstone-components 0.1.0

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

@@ -0,0 +1,612 @@
+# Full-page layouts with `<cs-page>`
+
+You are here because STEP 0 determined you're building a **full page, app shell, or site layout**. In
+this branch, `<cs-page>` is **required** and the rules below are absolute. Do not hand-roll a full-page
+grid; `<cs-page>` exists precisely so you don't have to.
+
+**`<cs-page>` fully owns the page layout.** It is the grid, the sticky regions, the responsive
+navigation, the mobile drawer, and the `html`/`body` reset — all of it. Your job is to slot content into
+named regions and let the component do the work. Do **not** rebuild any of this by hand: no full-page
+`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
+
+---
+
+## Mental model
+
+`<cs-page>` is a grid of named regions. Picture **5 stacked rows**, where the middle row splits into
+**3 columns**:
+
+```
+┌──────────────────────────────────────────────┐
+│ banner                                       │  ← optional, hidden when empty
+├──────────────────────────────────────────────┤
+│ header                            (sticky)   │
+├──────────────────────────────────────────────┤
+│ subheader                         (sticky)   │  ← e.g. breadcrumbs
+├──────────┬───────────────────────┬───────────┤
+│ menu /   │ main-header           │ aside     │
+│ navi-    │ ┌───────────────────┐ │ (sticky)  │
+│ gation   │ │ main (default)    │ │           │
+│ (sticky) │ └───────────────────┘ │           │
+│          │ main-footer           │           │
+├──────────┴───────────────────────┴───────────┤
+│ footer                                       │  ← always below the fold
+└──────────────────────────────────────────────┘
+```
+
+You opt into regions by slotting content. **Empty slots render nothing**, so use only the regions you
+need. The default (unnamed) slot is your main content.
+
+Two columns behave differently below `mobile-breakpoint`: the `navigation` (menu) column collapses into a
+drawer automatically, but the **`aside` column does not** — it has no drawer, so you must hide it yourself
+on mobile or it overlaps the content (see Hard rule 5).
+
+---
+
+## ⚠️ The `navigation` slot is automatic — one copy serves both views
+
+This is the single most important thing to understand about `<cs-page>`, and the most common source of
+mistakes. **The `navigation` slot is special: the component _moves_ your nav to the right place for the
+current view, automatically — it renders in exactly one place at a time, never both.**
+
+- On **desktop** (at or above `mobile-breakpoint`, default `768px`), the content you put in
+  `slot="navigation"` renders as a **persistent left sidebar column**.
+- On **mobile** (below the breakpoint), that _same_ content is moved into a `<cs-drawer>`, toggled by a
+  hamburger button the component shows for you.
+
+You write the nav **once**, in `slot="navigation"`, and `<cs-page>` handles both views. The same is true
+for `navigation-header` and `navigation-footer` (they become the drawer's header/footer on mobile).
+
+**Because the component does this for you:**
+
+- **For a single nav, write it once in `slot="navigation"` — don't also copy it into `header`.** One
+  `slot="navigation"` is _moved_ between views (desktop sidebar ⇄ mobile drawer); it is never rendered in
+  two places at once, so a single copy already serves both views. If you _author_ a second copy in
+  `header` (or anywhere else) and don't hide it per view, **both copies show** on whatever view they're
+  both visible in — typically desktop, where you'd then see the same links in the header **and** in the
+  left sidebar. That double-nav-on-desktop is the most common `<cs-page>` mistake.
+- **Header nav on desktop is the _one_ case where duplicating is correct — but it's deliberate, not
+  free.** If you want links in the header bar on desktop (no left sidebar) plus a mobile drawer, you
+  **must** put the links in `header` _and_ mirror them in `slot="navigation"` (the drawer needs that
+  copy), then hide each in the view where it shouldn't appear. The `navigation` copy renders a **visible
+  left sidebar on desktop** unless you hide it — that's the trap. Use the
+  [header-on-desktop / drawer-on-mobile recipe below](#the-one-place-duplicating-nav-is-correct-header-on-desktop-drawer-on-mobile);
+  it is the only sanctioned, view-scoped duplication.
+- **Don't toggle the nav yourself, and don't show/hide the hamburger.** The toggle button and its
+  desktop/mobile visibility are already styled and wired by the component.
+- **Don't write media queries for nav, the sidebar, or the toggle.** The desktop↔mobile switch is driven
+  by `<cs-page>`'s own `view` state, not by your CSS. Reserve media queries for genuinely page-specific
+  content adjustments, never for the nav machinery.
+
+**First decision, before any markup: does this page have a left sidebar on desktop?**
+
+- **Yes** (app shell, docs, dashboard) → put your nav in `slot="navigation"` and follow Hard rule 5 (set
+  `--menu-width`, reset to `auto` on mobile). This is the intended path. Copy the app/docs example below.
+- **No** (landing page, marketing site, most content pages) → you have two clean options, both of which
+  still let `<cs-page>` do the work:
+  - **Simplest:** put your primary nav in `slot="navigation"` anyway. You'll get a small desktop sidebar
+    instead of header nav, which is fine for many content pages. The mobile drawer comes free. (Note: this
+    gives you a **sidebar**, not header links — if you specifically want nav in the header bar, that
+    doesn't happen automatically; use the recipe below.)
+  - **Header nav + mobile drawer, no desktop sidebar** (the classic marketing/hero look): keep the nav in
+    the `header` for desktop, mirror it in `slot="navigation"` for the mobile drawer, and use the
+    **deliberate-exception recipe below** to hide each in the view where it shouldn't appear. This is the
+    _one_ place duplication is correct — and it's controlled, view-scoped duplication, not an accident.
+
+---
+
+## The one place duplicating nav is correct: header on desktop, drawer on mobile
+
+Use this **only** for a marketing/hero page where you want nav links **in the header on desktop** but a
+**mobile drawer menu** — and explicitly **no** left sidebar on desktop. This is the single sanctioned
+exception to "never duplicate," because you're deliberately rendering the nav differently per view.
+
+All four steps are required — steps 3 and 4 are what stop the nav from showing twice on desktop:
+
+1. Put the desktop links in the **`header`** slot.
+2. Mirror the same links in the **`navigation`** slot. On mobile this copy powers the drawer; on desktop
+   this **same copy also renders a visible left sidebar** — which you don't want here, so step 4 hides it.
+   (Skipping this mirror means no mobile drawer; including it without step 4 means the links show in both
+   the header and a desktop sidebar.)
+3. Hide the header links on mobile: `cs-page[view='mobile'] .header-nav { display: none }`.
+4. Hide the desktop sidebar on desktop: `cs-page[view='desktop']::part(navigation) { display: none }`.
+   (`::part(navigation)` targets _only_ the desktop sidebar wrapper; the mobile drawer is unaffected, so
+   the drawer still works. This is the step people forget — without it you get the same links in the
+   header **and** the left sidebar on desktop.)
+
+```html
+<cs-page>
+  <header slot="header" class="cs-split section">
+    <strong>My Brand</strong>
+    <!-- Desktop links — shown in the header, hidden on mobile via step 3 -->
+    <nav class="header-nav cs-cluster cs-gap-l">
+      <a href="#features">Features</a>
+      <a href="#pricing">Pricing</a>
+      <a href="#faq">FAQ</a>
+      <cs-button variant="brand">Get started</cs-button>
+    </nav>
+    <!-- Your OWN toggle, last child so cs-split right-aligns it. Mobile-only; opens the drawer.
+         Supplying this suppresses <cs-page>'s built-in hamburger (see note below). -->
+    <cs-button data-toggle-nav appearance="plain" class="cs-mobile-only">
+      <cs-icon name="menu" label="Open menu"></cs-icon>
+    </cs-button>
+  </header>
+
+  <!-- Same links, mirrored for the mobile drawer (opened by the header toggle above).
+       The desktop sidebar is hidden via step 4. -->
+  <nav slot="navigation" class="cs-stack cs-gap-2xs">
+    <a href="#features" data-drawer="close">Features</a>
+    <a href="#pricing" data-drawer="close">Pricing</a>
+    <a href="#faq" data-drawer="close">FAQ</a>
+    <cs-button variant="brand">Get started</cs-button>
+  </nav>
+
+  <main>…</main>
+  <footer slot="footer" class="section"><small>&copy; My Brand</small></footer>
+</cs-page>
+
+<style>
+  /* No --menu-width here: in this recipe the desktop sidebar is hidden, so leave --menu-width at its
+     `auto` default. Setting a fixed value (e.g. 14rem) reserves an empty left column — see note below. */
+  cs-page[view='mobile'] .header-nav {
+    display: none; /* hide desktop header links on mobile */
+  }
+  cs-page[view='desktop']::part(navigation) {
+    display: none; /* hide the desktop sidebar; mobile drawer is unaffected */
+  }
+</style>
+```
+
+You do **not** need your own `<cs-drawer>` or any media queries for this — the drawer comes from
+`<cs-page>`. **You should, however, supply your own `data-toggle-nav` button inside the `header`** (as
+shown above), so the hamburger is placed and styled _with_ your header bar. Adding any
+`[data-toggle-nav]` element automatically suppresses `<cs-page>`'s built-in hamburger. If you omit your
+own toggle, the built-in one renders **before** your header content inside the component's flex header
+and **wraps onto its own unstyled row** (left-aligned, no background) — the #2 bug of this recipe. The
+`.cs-mobile-only` class shows your toggle only below `mobile-breakpoint`, so the desktop header stays
+clean. The only custom CSS is the two `view`-scoped hide rules above.
+
+⚠️ **In this recipe, do NOT set a fixed `--menu-width` — leave it at its `auto` default.** The left
+`menu` column's width is `minmax(0, var(--menu-width))`, and `--menu-width` defaults to `auto`. Hiding
+the desktop sidebar with `::part(navigation){display:none}` removes the sidebar _content_, but the grid
+track width is governed **only** by `--menu-width` — not by whether the content is visible. With `auto`,
+the now-empty column collapses to nothing; with a fixed value like `14rem` (often copied in from the
+sidebar/app-shell skeleton below), the track stays `14rem` and you get a **reserved empty band down the
+left side on desktop**. This is the classic "I added `display: none` and the gap is still there" bug:
+`display: none` never touched the width. If you see that empty band, search your CSS for a fixed
+`--menu-width` and remove it.
+
+---
+
+## Everything below is `<cs-page>`-only
+
+The capabilities in this file **only work on elements inside a `<cs-page>`**. Outside one, they are
+inert; they do nothing, silently. Do not lift them into a section, widget, or any layout that isn't a
+`<cs-page>`. This includes:
+
+- The **slots** (`slot="header"`, `slot="navigation"`, `slot="aside"`, etc.). `slot` only matters on a direct child of `<cs-page>`.
+- The **`view='mobile'` / `view='desktop'` state** and the CSS that keys off it.
+- **`.cs-desktop-only` / `.cs-mobile-only`**. These are not general responsive utilities; they work _only_ via `<cs-page>`'s `view` selector. Outside `<cs-page>` they do nothing; use a CSS media query instead.
+- **`data-toggle-nav`**. Only `<cs-page>` listens for it.
+- The custom properties **`--menu-width`**, **`--main-width`**, **`--aside-width`**.
+- **Sticky** banner/header/subheader/menu/aside, the mobile **navigation drawer**, and the automatic **`html`/`body` reset**.
+
+If you're not building a full page, you don't get these, and you don't need them. Use the layout
+utilities instead (see [layouts-inpage.md](layouts-inpage.md)).
+
+---
+
+## Hard rules (these are the things that go wrong)
+
+1. **Reset `html` and `body`.** `<cs-page>` injects this reset itself (via `:has(cs-page)`), but include
+   it explicitly anyway. It's the documented recommendation and it covers SSR and browsers without
+   `:has()` support. Without the reset you can see gaps around the page:
+
+   ```css
+   html,
+   body {
+     min-height: 100%;
+     padding: 0;
+     margin: 0;
+   }
+   ```
+
+   (If you use [native styles](https://cruglobal.github.io/cornerstone-design-system/docs/utilities/native/), this is already handled.)
+
+2. **`<cs-page>` provides no semantic elements.** It does not emit `<main>`, `<header>`, `<footer>`,
+   etc. Slot your own:
+
+   ```html
+   <header slot="header">…</header>
+   <nav slot="navigation">…</nav>
+   <main>…</main>
+   <aside slot="aside">…</aside>
+   <footer slot="footer">…</footer>
+   ```
+
+3. **Set `main { padding: 0 }` for full-bleed pages — `<cs-page>` pads `main` by default.** `<cs-page>` pads the main content area, which insets
+   full-bleed section backgrounds (heroes, color bands) so they can't reach the viewport edges. Set
+   `main { padding: 0 }` and give each `<section>` its own horizontal gutter instead — a
+   `padding-inline` or an inner max-width wrapper:
+
+   ```css
+   main {
+     padding: 0;
+   }
+   .section {
+     padding-inline: var(--cs-space-xl); /* or wrap content in a centered max-width container */
+   }
+   ```
+
+   Backgrounds then run edge-to-edge while content stays inset. Keep the default padding only when the
+   whole page is a single narrow, contained column (a docs article, a login form).
+
+4. **Use `navigation`, not `menu`, for the responsive sidebar.** The `navigation` slot (plus
+   `navigation-header` / `navigation-footer`) auto-collapses into a drawer on mobile. The `menu` slot
+   means "I'll take over the left column entirely and handle mobile myself"; only use it if you truly
+   need that.
+
+5. **Only set a fixed `--menu-width` when you actually render a desktop sidebar; reset it on mobile.**
+   The `menu` column is `minmax(0, var(--menu-width))` and `--menu-width` defaults to `auto`, so its
+   width is controlled **only** by `--menu-width` — never by whether the sidebar content is visible.
+   Two cases:
+
+   - **Desktop sidebar layout** (the `navigation` slot is visible as a left column on desktop — app
+     shell, docs, dashboard): set a fixed `--menu-width` (e.g. `16rem`); it's holding real content. A
+     fixed width still reserves space below the breakpoint, so collapse it back to `auto` for
+     `view='mobile'`. The `navigation` sidebar moves into the drawer automatically; the `aside` does
+     not, so to hide it on mobile also set `display: none` on that slot.
+   - **No desktop sidebar** (the header/drawer recipe above — desktop sidebar hidden via
+     `::part(navigation){display:none}`): **leave `--menu-width` at `auto`. Do not set a fixed value.**
+     Hiding the sidebar collapses its content but not the grid track, so a fixed `--menu-width` reserves
+     an empty left column on desktop. (This is the recipe's #1 bug.)
+
+   For the desktop-sidebar case:
+
+   ```css
+   cs-page {
+     --menu-width: 16rem;
+     --aside-width: 18rem;
+   }
+   cs-page[view='mobile'] {
+     --menu-width: auto;
+     --aside-width: auto;
+   }
+   cs-page[view='mobile'] [slot='aside'] {
+     display: none; /* aside has no drawer; hide it explicitly on mobile */
+   }
+   ```
+
+6. **Let `<cs-page>` own the nav — don't toggle it, don't media-query it.** Put nav in
+   `slot="navigation"` **once**; the component renders it as the desktop sidebar and moves it into the
+   mobile drawer for you (one copy, never rendered in two places at once). The hamburger button and its
+   desktop/mobile visibility are already handled — don't write CSS to show or hide it, and don't add media
+   queries for the nav, sidebar, or toggle. The **one** time you intentionally author a second copy is the
+   header-on-desktop / drawer-on-mobile recipe above — and there you must hide each copy in the view where
+   it shouldn't appear (`view`-scoped CSS), or the links show in both the header and the desktop sidebar. The default hamburger opens the `navigation` drawer; if you want a custom
+   toggle, add `data-toggle-nav` to any element inside `<cs-page>` (this auto-hides the default
+   hamburger). You can add `data-toggle-nav` to **multiple** elements — they all toggle the same drawer
+   (handy for an app shell with, say, both a header and a footer toggle). `data-toggle-nav` only toggles
+   the `navigation` drawer, so it does nothing without `navigation` content — never pair it with a
+   hand-rolled drawer. **When you want the toggle to live
+   inside your own styled header bar (the header/drawer recipe), put a `data-toggle-nav` button there
+   yourself** rather than relying on the built-in hamburger — the built-in one renders in the header
+   _before_ your `header` slot content and wraps onto its own unstyled row, outside your bar.
+
+7. **Close the drawer when a nav link is tapped.** The mobile navigation is a `<cs-drawer>`, so add
+   `data-drawer="close"` to your navigation links, so tapping one then closes the drawer (otherwise it
+   stays open over the page you just navigated to):
+
+   ```html
+   <nav slot="navigation" class="cs-stack cs-gap-2xs">
+     <a href="#dashboard" data-drawer="close">Dashboard</a>
+     <a href="#settings" data-drawer="close">Settings</a>
+   </nav>
+   ```
+
+8. **Custom elements never self-close.** `<cs-button></cs-button>`, not `<cs-button />`.
+
+9. **`view` is read-only; never set it.** The component sets `view='mobile'` / `view='desktop'` itself
+   (via a `ResizeObserver`, defaulting to `'desktop'` for SSR). You only ever _read_ it in CSS
+   (`cs-page[view='mobile'] { … }`). Don't gate critical initial rendering on it.
+
+---
+
+## Canonical example — landing page
+
+A hero-driven marketing/landing page. Nav goes in `slot="navigation"` **once**; `<cs-page>` shows it as a
+sidebar on desktop and as a drawer (with a hamburger) on mobile. **No hand-rolled `<cs-drawer>`, no
+toggle wiring, no media queries** — the component handles all of it. This is the simplest correct shape.
+
+> Want nav in the **header bar** on desktop instead of a sidebar (the classic marketing look)? Use the
+> **"header on desktop, drawer on mobile" recipe** near the top of this file — it's the one sanctioned
+> way to duplicate nav, and it still lets `<cs-page>` provide the drawer and hamburger.
+
+```html
+<cs-page>
+  <header slot="header" class="section">
+    <strong>My Brand</strong>
+  </header>
+
+  <!-- Write the nav ONCE. Desktop: sidebar. Mobile: drawer + hamburger, automatically. -->
+  <nav slot="navigation" class="cs-stack cs-gap-2xs">
+    <a href="#features" data-drawer="close">Features</a>
+    <a href="#pricing" data-drawer="close">Pricing</a>
+    <a href="#faq" data-drawer="close">FAQ</a>
+    <cs-button variant="brand">Get started</cs-button>
+  </nav>
+
+  <main>
+    <section class="section cs-stack cs-gap-l">
+      <h1>Big headline</h1>
+      <p>Hero content.</p>
+      <cs-button variant="brand" size="l">Get started</cs-button>
+    </section>
+    <!-- more full-bleed <section class="section"> blocks … -->
+  </main>
+
+  <footer slot="footer" class="section">
+    <small>&copy; My Brand</small>
+  </footer>
+</cs-page>
+
+<style>
+  html,
+  body {
+    min-height: 100%;
+    padding: 0;
+    margin: 0;
+  }
+  main {
+    padding: 0;
+  }
+  .section {
+    padding-inline: var(--cs-space-xl);
+  }
+  cs-page {
+    --menu-width: 14rem;
+  }
+  cs-page[view='mobile'] {
+    --menu-width: auto; /* collapse the reserved sidebar space on mobile (Hard rule 5) */
+  }
+</style>
+```
+
+## Canonical example — app/docs (with a desktop sidebar)
+
+A documentation-style layout using header, subheader (with a mobile nav toggle), a collapsing
+navigation sidebar, main content, a sticky table-of-contents aside, and a footer. **Only use the
+`navigation` slot when you want this left sidebar on desktop.**
+
+```html
+<cs-page mobile-breakpoint="920">
+  <header slot="header" class="cs-split">
+    <div class="cs-cluster">
+      <strong>Cornerstone</strong>
+      <a href="#">Docs</a>
+      <a href="#">Components</a>
+    </div>
+    <div class="cs-cluster">
+      <cs-button variant="brand">Sign up</cs-button>
+    </div>
+  </header>
+
+  <nav slot="subheader" class="cs-cluster cs-gap-xs">
+    <cs-button data-toggle-nav appearance="plain" class="cs-mobile-only">
+      <cs-icon name="menu" label="Menu"></cs-icon>
+    </cs-button>
+    <cs-breadcrumb>
+      <cs-breadcrumb-item href="/">Home</cs-breadcrumb-item>
+      <cs-breadcrumb-item>Layouts</cs-breadcrumb-item>
+    </cs-breadcrumb>
+  </nav>
+
+  <nav slot="navigation-header">
+    <strong>Guide</strong>
+  </nav>
+  <nav slot="navigation" class="cs-stack cs-gap-2xs">
+    <a href="#start" data-drawer="close">Getting started</a>
+    <a href="#layout" data-drawer="close">Layout</a>
+    <a href="#theming" data-drawer="close">Theming</a>
+  </nav>
+
+  <!-- Contained docs column, so the default main padding is kept (see Hard rule 3).
+       For a landing page with full-bleed heroes/bands, zero it: main { padding: 0 }. -->
+  <main class="cs-stack cs-gap-xl">
+    <h1>Getting started</h1>
+    <p>Your content goes here.</p>
+    <h2 id="layout">Layout</h2>
+    <p>More content.</p>
+  </main>
+
+  <aside slot="aside" class="cs-desktop-only cs-stack cs-gap-m">
+    <strong>On this page</strong>
+    <ul class="cs-stack cs-gap-2xs">
+      <li><a href="#start">Getting started</a></li>
+      <li><a href="#layout">Layout</a></li>
+    </ul>
+  </aside>
+
+  <footer slot="footer" class="cs-grid cs-gap-2xl">
+    <div class="cs-stack cs-gap-xs">
+      <strong>Product</strong>
+      <a href="#">Features</a>
+      <a href="#">Pricing</a>
+    </div>
+    <div class="cs-stack cs-gap-xs">
+      <strong>Company</strong>
+      <a href="#">About</a>
+      <a href="#">Contact</a>
+    </div>
+  </footer>
+</cs-page>
+
+<style>
+  html,
+  body {
+    min-height: 100%;
+    padding: 0;
+    margin: 0;
+  }
+  cs-page {
+    --menu-width: 15rem;
+    --aside-width: 16rem;
+  }
+  cs-page[view='mobile'] {
+    --menu-width: auto;
+    --aside-width: auto;
+  }
+</style>
+```
+
+> **Choosing `mobile-breakpoint`.** The default is `768px`, which is often too narrow once you have a
+> real sidebar. Documentation and app layouts commonly use a wider value (the example above uses `920`;
+> app shells frequently use `1152`). Pick the width at which your sidebar + content stop fitting
+> comfortably, not a fixed device size. It accepts a number (px) or a CSS length like `60em`.
+
+---
+
+## Anti-patterns
+
+| ❌ Don't                                                                                                         | ✅ Do                                                                                                                                                                               |
+| ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Forget the `html, body` reset → gaps appear                                                                      | Always add the reset (or use native styles)                                                                                                                                         |
+| Expect `<cs-page>` to emit `<main>`/`<header>`                                                                   | Slot in your own semantic elements                                                                                                                                                  |
+| Put nav in `menu` and wonder why it won't collapse                                                               | Use `navigation` (+ `navigation-header`/`-footer`) for mobile collapse                                                                                                              |
+| Author a second nav copy in `header` while also using `slot="navigation"`, without hiding one per view → links show in **both** the header and the desktop sidebar | Write nav **once** in `slot="navigation"` (it moves between views automatically). For header nav on desktop + a mobile drawer, use the header-on-desktop / drawer-on-mobile recipe and `view`-scope-hide each copy |
+| Hand-roll your own `<cs-drawer>` + toggle button for the mobile menu                                             | Put nav in `slot="navigation"`; `<cs-page>` provides the drawer and hamburger automatically                                                                                         |
+| Write media queries to show/hide the nav, sidebar, or hamburger                                                  | Don't — the component switches via its own `view` state. Media queries are for page content, not the nav machinery                                                                  |
+| Pair `data-toggle-nav` with your own `<cs-drawer>` (it toggles the `navigation` drawer, not yours → dead button) | Use the `navigation` slot's built-in drawer; `data-toggle-nav` only ever controls that one                                                                                          |
+| Set `--menu-width: 16rem` and leave it on mobile                                                                 | Reset widths to `auto` under `cs-page[view='mobile']`                                                                                                                               |
+| Nav links that leave the drawer open after a tap                                                                 | Add `data-drawer="close"` to navigation links                                                                                                                                       |
+| Expect `aside` to disappear on mobile on its own                                                                 | `aside` has no drawer; hide it (`.cs-desktop-only` or `display: none`)                                                                                                              |
+| Try to set `view="mobile"` yourself                                                                              | `view` is read-only; the component sets it. Only read it in CSS                                                                                                                     |
+| Hand-roll a `display: grid` page shell                                                                           | Use `<cs-page>`; it already is the grid                                                                                                                                             |
+| Nest `<cs-page>` inside a section or another page                                                                | One `<cs-page>` per page, at the top level                                                                                                                                          |
+| Hardcode header colors with hex                                                                                  | Use `--cs-color-surface-*` / semantic tokens                                                                                                                                        |
+| `<cs-button />` (self-closing)                                                                                   | `<cs-button></cs-button>`                                                                                                                                                           |
+
+## `<cs-page>` checklist
+
+Before calling a `<cs-page>` layout done, walk this **`<cs-page>`-specific** structural pass. This sits
+alongside the general structural Final Pass in SKILL.md and the visual Polish Checklist in composition.md;
+each catches different things.
+
+- [ ] **Right sidebar decision.** Landing page: nav in `slot="navigation"` **once** (auto sidebar on desktop, drawer on mobile) — or, if you want header-bar nav with no desktop sidebar, the header-on-desktop / drawer-on-mobile recipe above with `--menu-width` left at `auto`. App shell / docs: `navigation` slot with `--menu-width` set, reset to `auto` under `cs-page[view='mobile']`. Either way, don't hand-roll a `<cs-drawer>`.
+- [ ] **`html, body` reset** is in place (or you're using native styles) — otherwise gaps appear around the page.
+- [ ] **Your own semantic elements are slotted** — `<header>`, `<main>`, `<footer>`, `<nav>`, `<aside>`. `<cs-page>` emits none.
+- [ ] **`main` padding is `0`** for full-bleed pages where sections own their gutter; keep the default only for a single contained column (docs article, login form).
+- [ ] **Sidebar widths reset on mobile.** `--menu-width` and `--aside-width` go to `auto` under `cs-page[view='mobile']` so they don't leak; the `aside` is hidden (`display: none`) on mobile since it has no auto-drawer.
+- [ ] **`data-drawer="close"`** is on every link in the mobile-collapsing nav, so tapping one closes the drawer instead of leaving it open over the next page.
+- [ ] **`data-toggle-nav` only toggles the `navigation` drawer.** Use it to open the `navigation` slot's drawer (or supply it in the header for the header/drawer recipe); never wire it to a hand-rolled drawer.
+- [ ] **`view` is read-only.** Read it in CSS (`cs-page[view='mobile']`); never set it as an attribute.
+- [ ] **One `<cs-page>` per page**, at the top level — never nested inside a section or another `<cs-page>`.
+
+---
+
+## Sticky sections
+
+`banner`, `header`, `subheader`, `menu`, and `aside` are sticky by default. (It's the `menu` wrapper
+around the left sidebar that sticks; your `navigation` content scrolls within it.) To opt out, pass a
+space-delimited list to `disable-sticky`:
+
+```html
+<cs-page disable-sticky="aside"> … </cs-page>
+```
+
+---
+
+## Server-side rendering
+
+`<cs-page>` is SSR-safe, but a few defaults exist because the mobile drawer needs JavaScript and can't run
+during SSR. When rendering on the server, know:
+
+- **`view` defaults to `'desktop'`.** The component can't measure the viewport until JS runs, so the
+  first paint is the desktop layout; it switches to `'mobile'` on hydration via a `ResizeObserver`. Don't
+  gate critical content on `view` — it's `'desktop'` until the client takes over.
+- **Set `disable-navigation-toggle` yourself for the initial render if needed.** On the client the
+  component auto-detects whether to show the hamburger (based on `navigation` content and any custom
+  `data-toggle-nav`), but that detection doesn't run during SSR. Set the attribute explicitly to control
+  the server-rendered markup.
+- **Prevent hydration layout shift by pre-setting the height custom properties.** `--banner-height`,
+  `--header-height`, and `--subheader-height` are measured at runtime (default `0px`). If you know them,
+  set them on `<cs-page>` so sticky offsets are correct before JS runs. See
+  [CSS custom properties](#css-custom-properties).
+
+---
+
+## API reference
+
+For the authoritative, always-current API, see the [page component docs](https://cruglobal.github.io/cornerstone-design-system/docs/components/page)
+or the `cornerstone` skill. This is a working summary.
+
+### Slots
+
+| Slot                     | Purpose                                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
+| _(default)_              | The page's main content.                                                                 |
+| `banner`                 | Above the header. Hidden when empty.                                                     |
+| `header`                 | Top of the page. Sticky.                                                                 |
+| `subheader`              | Below the header (e.g. breadcrumbs). Sticky.                                             |
+| `menu`                   | Left column. _Overrides_ `navigation` and makes you handle mobile yourself. Rarely used. |
+| `navigation`             | Left sidebar content. Collapses into a drawer on mobile. Use this for nav.               |
+| `navigation-header`      | Header of the navigation area (drawer header on mobile).                                 |
+| `navigation-footer`      | Footer of the navigation area (drawer footer on mobile).                                 |
+| `navigation-toggle`      | Your own button to toggle the nav drawer.                                                |
+| `navigation-toggle-icon` | Your own icon for the toggle button.                                                     |
+| `main-header`            | Inline header above the main content.                                                    |
+| `main-footer`            | Inline footer below the main content.                                                    |
+| `aside`                  | Right sidebar (e.g. table of contents). Sticky. **No auto-drawer — hide it on mobile yourself** (`cs-page[view='mobile'] [slot='aside'] { display: none }`) or it overlaps. |
+| `skip-to-content`        | Custom text for the "skip to content" link.                                              |
+| `footer`                 | Page footer. Always below the fold.                                                      |
+
+### Attributes
+
+| Attribute                   | Type                    | Default     | Purpose                                                           |
+| --------------------------- | ----------------------- | ----------- | ----------------------------------------------------------------- |
+| `view`                      | `'mobile' \| 'desktop'` | `'desktop'` | Reflects the current view. Set automatically; you read it in CSS. |
+| `nav-open`                  | `boolean`               | `false`     | Whether the mobile nav drawer is open.                            |
+| `mobile-breakpoint`         | `string`                | `'768px'`   | Width at which navigation collapses. Accepts px or CSS lengths.   |
+| `navigation-placement`      | `'start' \| 'end'`      | `'start'`   | Which side the mobile drawer opens from. Use `end` for RTL or right-handed reach. |
+| `disable-navigation-toggle` | `boolean`               | `false`     | Hide the default hamburger button.                                |
+| `disable-sticky`            | `string`                | —           | Space-delimited list of sections to make non-sticky.              |
+
+### CSS custom properties
+
+| Property             | Default | Purpose                                                                                                                                                  |
+| -------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--menu-width`       | `auto`  | Width of the left (menu) column.                                                                                                                          |
+| `--main-width`       | `1fr`   | Width of the main content column.                                                                                                                         |
+| `--aside-width`      | `auto`  | Width of the right (aside) column.                                                                                                                        |
+| `--banner-height`    | `0px`   | Measured automatically once rendered. Set it to the known height to prevent layout shift before JS runs — useful for SSR. Used to offset sticky regions. |
+| `--header-height`    | `0px`   | Measured automatically once rendered. Set it to the known height to prevent layout shift before JS runs — useful for SSR. Used to offset sticky regions. |
+| `--subheader-height` | `0px`   | Measured automatically once rendered. Set it to the known height to prevent layout shift before JS runs — useful for SSR. Used to offset sticky regions. |
+
+### CSS parts
+
+Style internal regions with `::part()` from outside the component (e.g. `cs-page::part(header) { … }`).
+
+| Part                     | What it is                                                                                                   |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `base`                   | The outermost wrapper.                                                                                        |
+| `banner`                 | The banner region above the header.                                                                           |
+| `header`                 | The header region.                                                                                            |
+| `subheader`              | The subheader region.                                                                                         |
+| `body`                   | The wrapper around `menu`, `main`, and `aside`.                                                               |
+| `menu`                   | The sticky left column wrapper.                                                                               |
+| `navigation`             | **The desktop sidebar `<nav>` only** — _not_ the mobile drawer. This is what the header/drawer recipe hides. |
+| `navigation-header`      | The navigation area's header.                                                                                |
+| `navigation-footer`      | The navigation area's footer.                                                                                |
+| `navigation-toggle`      | The default hamburger `<cs-button>`.                                                                          |
+| `navigation-toggle-icon` | The default hamburger `<cs-icon>`.                                                                            |
+| `main-header`            | The inline header above main content.                                                                        |
+| `main-content`           | The main content region.                                                                                     |
+| `main-footer`            | The inline footer below main content.                                                                        |
+| `aside`                  | The sticky right column.                                                                                      |
+| `footer`                 | The page footer.                                                                                              |
+| `drawer`                 | The mobile navigation `<cs-drawer>`. (Drawer internals are also exposed via `drawer__*` parts.)              |
+
+(Also exposed: `skip-to-content`, the visually hidden skip link.)