nk_jtb 0.29.0 → 0.30.0

package/code-review-codex-260608.md

@@ -0,0 +1,66 @@
+# Theme and Color System Review
+
+## Scope Reviewed
+
+- Application audit of the JTB color/theme subsystem.
+- Covered color maps, theme partials, utility generators, component defaults, and docs.
+- Source-level review only; generated CSS and browser visuals were not tested.
+
+## Findings
+
+### Medium — Runtime brand overrides do not update all brand-dependent components
+
+- **Impact:** A project that overrides `--primary` at runtime can get mixed old and new brand colors across components.
+- **Evidence:** Brand defaults are defined from SCSS values in [src/maps_and_variables/_components.scss:79](src/maps_and_variables/_components.scss#L79), [src/maps_and_variables/_components.scss:86](src/maps_and_variables/_components.scss#L86), [src/maps_and_variables/_components.scss:87](src/maps_and_variables/_components.scss#L87), and [src/maps_and_variables/_components.scss:93](src/maps_and_variables/_components.scss#L93); `.navbar` emits the compiled `$navbar-bg` in [src/components/_navbar.scss:4](src/components/_navbar.scss#L4), menu hover/underline uses compiled fallbacks in [src/components/_menu.scss:28](src/components/_menu.scss#L28) and [src/components/_menu.scss:48](src/components/_menu.scss#L48), while tabs use runtime `var(--primary)` in [src/components/_tabs.scss:6](src/components/_tabs.scss#L6) and [src/components/_tabs.scss:25](src/components/_tabs.scss#L25). The docs say CSS custom properties let users swap a brand color without recompiling in [docs/variable-system.md:47](docs/variable-system.md#L47).
+- **Fix:** Decide that brand colors are a runtime token family, then make brand-derived component defaults resolve through component CSS vars that default to `var(--primary)`, `var(--secondary)`, or `var(--accent)` instead of compiled `$primary` values.
+- **Trade-off:** Components that rely on Sass color functions for derived values still need compile-time fallbacks or explicit runtime tokens.
+
+### Medium — Brand theme text contrast can go stale after runtime color changes
+
+- **Impact:** Changing only `--primary`, `--secondary`, or `--accent` can leave stale text colors on theme classes and button states.
+- **Evidence:** [src/themes/_brand.scss:21](src/themes/_brand.scss#L21) computes `--on-{name}` from the compile-time `$brand-colors`, but brand themes and outline hover states consume `var(--on-{name})` in [src/themes/_brand.scss:57](src/themes/_brand.scss#L57) and [src/themes/_brand.scss:68](src/themes/_brand.scss#L68); brand button hover/active states also consume the same token in [src/components/_button.scss:113](src/components/_button.scss#L113). [docs/variable-system.md:87](docs/variable-system.md#L87) documents this caveat, but [docs/colors-and-themes.md:386](docs/colors-and-themes.md#L386) and [docs/colors-and-themes.md:414](docs/colors-and-themes.md#L414) still describe brand themes as runtime-swappable without that qualification.
+- **Fix:** Document and enforce runtime brand overrides as a full token set, or remove the implication that overriding only the base brand color is enough.
+- **Trade-off:** CSS cannot reliably choose accessible `on-*` colors from arbitrary runtime colors without either explicit tokens or newer browser-dependent color logic.
+
+### Medium — Brand themes now bypass the normal theme builder pipeline
+
+- **Impact:** `.primary`, `.secondary`, and `.accent` look like ordinary theme classes in the public API but are generated and maintained through different code paths.
+- **Evidence:** Static hue and semantic themes use [src/themes/_color.scss:36](src/themes/_color.scss#L36), [src/themes/_color.scss:41](src/themes/_color.scss#L41), and the shared builders in [src/mixins/_themes.scss:28](src/mixins/_themes.scss#L28); brand themes are generated manually in [src/themes/_brand.scss:56](src/themes/_brand.scss#L56). Buttons repeat the same split with static themes in [src/components/_button.scss:106](src/components/_button.scss#L106) and brand themes in [src/components/_button.scss:113](src/components/_button.scss#L113). Before `81b753b`, `primary`, `secondary`, and `accent` lived in `$base-colors` and passed through the same loops as hue themes.
+- **Fix:** Make one theme pipeline support both static Sass values and runtime CSS-var-backed values, then feed brand themes through that pipeline instead of hand-building them separately.
+- **Trade-off:** The shared theme builders need a small extension so they can accept precomputed runtime tokens instead of only Sass color values.
+
+### Low — Brand colors are not first-class across all color-consuming APIs
+
+- **Impact:** Users can reach for brand color classes in some places but not others, which makes the color system feel inconsistent.
+- **Evidence:** Background, text, and border utilities are generated from static palette maps in [src/utilities/_backgrounds.scss:23](src/utilities/_backgrounds.scss#L23), [src/maps_and_variables/_typography.scss:34](src/maps_and_variables/_typography.scss#L34), and [src/utilities/_border.scss:28](src/utilities/_border.scss#L28), while brand utility generation lives separately in [src/themes/_brand.scss:78](src/themes/_brand.scss#L78). Gradient utilities generate only base and scale color stops in [src/utilities/_gradients.scss:57](src/utilities/_gradients.scss#L57), and the gradient resolver checks semantic/base colors but not brand colors in [src/mixins/_gradients.scss:12](src/mixins/_gradients.scss#L12).
+- **Fix:** After the theme pipeline is unified, decide per utility domain whether brand tokens should be included.
+
+## Top Architectural Risks
+
+- Brand has two meanings: compile-time SCSS defaults and runtime CSS tokens.
+- Brand theme generation is separated from the normal theme builder pipeline.
+- Component defaults mix `$primary` and `var(--primary)`, so runtime theming is uneven.
+- Documentation promises runtime swapping more broadly than the implementation safely supports.
+
+## Top Refactor Priorities
+
+- Treat brand as a runtime token family, not just three extra colors.
+- Refactor theme builders so static and runtime-backed themes use the same public pipeline.
+- Convert brand-derived component defaults to CSS custom properties with brand-token fallbacks.
+- Tighten docs around what changes at runtime and what remains compile-time.
+
+## Next Sprint Action Plan
+
+- **Action:** Define a clear brand token contract; **Why now:** removes the current compile/runtime ambiguity; **Effort:** S; **First step:** write the required token list for `primary`, `secondary`, and `accent`.
+- **Action:** Unify theme generation; **Why now:** restores the pre-`81b753b` mental model where `.primary` and `.teal` are both normal themes; **Effort:** M; **First step:** extend [src/mixins/_themes.scss:28](src/mixins/_themes.scss#L28) to accept runtime-backed theme maps.
+- **Action:** Convert component brand defaults to runtime component vars; **Why now:** makes brand overrides consistent across components; **Effort:** M; **First step:** start with navbar and menu because they currently compile `$primary`.
+- **Action:** Update color/theme docs; **Why now:** prevents incorrect expectations about runtime swaps; **Effort:** S; **First step:** rewrite the runtime brand section in [docs/variable-system.md:75](docs/variable-system.md#L75).
+- **Action:** Decide whether gradient stops should support brand; **Why now:** closes the most visible missing color API; **Effort:** S; **First step:** choose whether `from-primary` and `to-primary` should exist.
+
+## Maintainability Risk
+
+Moderate. The current split is understandable, but the same brand concept is implemented through separate Sass maps, CSS vars, component variables, and docs language.
+
+## Cross-Boundary Coupling Risk
+
+Moderate. Color decisions cross maps, themes, utilities, components, and documentation, so a change to brand behavior can easily miss one boundary.

package/code-review-codex-260610.md

@@ -0,0 +1,35 @@
+# Commit Readiness Review
+
+## Scope Reviewed
+
+- Review type: changed-file commit readiness review.
+- Coverage: staged set, unstaged set, theme/color split, package metadata, and build validation.
+- Exclusions: no full application audit; only current worktree changes were assessed.
+
+## Findings
+
+### Medium — The staged set is not safe to commit by itself
+
+- **Impact:** A commit made from the current staged files would leave the repository internally inconsistent.
+- **Evidence:** The staged `src/maps_and_variables/_colors.scss` change removes the old `$theme-colors` model, while the migration from `src/utilities/_themes.scss` to `src/themes/` is still unstaged/untracked.
+- **Fix:** Either unstage the current files and regroup, or stage the full theme/color migration together.
+
+### Low — The package version bump should be kept out unless this is a release commit
+
+- **Impact:** Committing `package.json` and `package-lock.json` now would mix release metadata with framework architecture changes.
+- **Evidence:** Both files only change the project version from `0.28.3` to `0.29.1`.
+- **Fix:** Commit the version bump separately when cutting the release.
+
+### Low — The staged homepage/demo change is unrelated to the theme/color migration
+
+- **Impact:** Including `index.html` with SCSS architecture changes will make the commit harder to review and revert.
+- **Evidence:** The staged diff replaces the Dusk homepage demo with a layout/sidebar test page.
+- **Fix:** Commit `index.html` separately if the demo change is intentional.
+
+## Maintainability Risk
+
+Moderate. The final working tree builds, but the current staging split separates dependent SCSS changes across staged, unstaged, deleted, and untracked files.
+
+## Cross-Boundary Coupling Risk
+
+Moderate. Color maps, theme forwarding, utilities, docs, and generated examples are currently mixed; commit grouping needs to keep dependent SCSS files together.

package/docs/colors-and-themes.md

@@ -383,8 +383,8 @@ All JTB theme classes are context-aware. Apply the same class to a button, box,
 ## Semantic & Brand Themes
 
 Beyond hue themes, JTB provides semantic themes for communicating intent and
-brand themes (`primary`, `secondary`, `accent`) that are runtime-swappable via
-CSS custom properties.
+brand themes (`primary`, `secondary`, `accent`) for project identity. Brand
+themes are generated from the same Sass color maps as hue and semantic themes.
 
 <div class="grid cols-8 gap-025">
     <div class="primary rounded-05 h-4 flex-centered font-mono">primary</div>
@@ -411,9 +411,8 @@ border and text, filling on hover.
 
 ## Customizing
 
-Brand themes (`primary`, `secondary`, `accent`) are overridable at runtime via
-CSS custom properties. See [Customizing Themes](/docs/jtb/customizing-themes)
-for the full reference.
+Override brand colors with Sass variables before the build. See
+[Variable System](/docs/jtb/variable-system) for the full reference.
 
 ## Examples
 

package/docs/components/button.md

@@ -74,9 +74,9 @@ Apply theme modifiers for different colors:
 </div>
 ```
 
-`primary`, `secondary`, and `accent` follow the runtime semantic theme tokens
-documented in [/docs/jtb/variable-system](/docs/jtb/variable-system). Use that
-layer when you want to test brand variations without rebuilding the CSS.
+`primary`, `secondary`, and `accent` are brand theme names generated from the
+same Sass color maps as other button themes. See
+[Variable System](/docs/jtb/variable-system).
 
 ## Button Sizes (review)
 

package/docs/components/menu.md

@@ -1,10 +1,12 @@
 # Menu (review)
 
-<p class="lead">The <code>.menu</code> class creates vertical navigation lists with automatic styling for links, buttons, icons, and states. No item classes required, just add links to the list.</p>
+The `.menu` class creates vertical navigation lists with automatic styling for
+links, buttons, icons, and states. No item classes required — just add links to
+the list.
 
 ## Structure (review)
 
-Apply `.menu` to a `<ul>` element. The `<nav>` is just a container, the menu
+Apply `.menu` to a `<ul>` element. The `<nav>` is just a container; the menu
 itself is the list.
 
 ```html +code
@@ -15,15 +17,10 @@ itself is the list.
 </nav>
 ```
 
-> **This structure is important:** Keeping the container (`<nav>`) separate from
-> the component (`<ul class="menu">`) gives you flexibility to switch between
-> vertical and horizontal layouts, nest menus, and use the menu component
-> anywhere—sidebars, dropdowns, or navbars.
-
 ## Basic Usage (review)
 
-```html +demo-folded
-<nav class="bx">
+```html +demo-folded class="bx example-jtb"
+<nav>
     <ul class="menu">
         <li> 
             <a href="#"> <svg class="svg-icon-pink"></svg> Item </a> 
@@ -54,11 +51,11 @@ itself is the list.
 
 ### Adding Icons (review)
 
-Icons work automatically, just add them inside links or buttons. Spacing and
+Icons work automatically — just add them inside links or buttons. Spacing and
 alignment are handled by the `.menu` class.
 
-```html +demo-folded class="bx"
-<nav class="bg-white">
+```html +demo-folded class="bx example-jtb"
+<nav>
     <ul class="menu">
         <li>
             <a href="#"> 
@@ -72,9 +69,10 @@ alignment are handled by the `.menu` class.
 
 ### Section titles (`.menu-title`) (review)
 
-Use `.menu-title` for non-clickable labels that group menu items (e.g. “Account”, “Settings”). Place it inside the same `<ul class="menu">` as a sibling to `<li>` elements.
+Use `.menu-title` for non-clickable labels that group menu items. Place it
+inside the same `<ul class="menu">` as a sibling to `<li>` elements.
 
-```html
+```html +code
 <ul class="menu">
     <li class="menu-title">Section</li>
     <li><a href="#">Item</a></li>
@@ -83,19 +81,31 @@ Use `.menu-title` for non-clickable labels that group menu items (e.g. “Accoun
 
 ### Underline variant (`.link-underline`) (review)
 
-Add `.link-underline` to the menu element to replace the hover background with a sliding left-to-right underline on links and buttons. Use with `.menu`: e.g. `<ul class="menu link-underline">`.
+Add `.link-underline` to the menu element to replace the hover background with
+a sliding left-to-right underline on links and buttons.
+
+```html +code
+<ul class="menu link-underline">
+    <li><a href="#">Item</a></li>
+</ul>
+```
 
-### Chevron rotation (`.chevron` / `.chevron.open`) (review)
+### Chevron rotation (`.chevron`) (review)
 
-For parent items that expand/collapse, add `.chevron` to the icon (e.g. the caret SVG). Toggle the `.open` class when the submenu is open so the chevron rotates 180°.
+Add `.chevron` to a toggle icon. Toggle `.open` on it when the submenu is open
+to rotate the icon 180°.
+
+```html +code
+<svg class="chevron" :class="{ open: open }">...</svg>
+```
 
 ### Parent Items (review)
 
-Parent items use buttons to toggle child menus. Works for nested navigation or
-dropdowns. Uses Alpine.js for toggle behavior.
+Parent items use buttons to toggle child menus. Uses Alpine.js for toggle
+behaviour.
 
-```html +demo-folded class="bx"
-<nav class="bg-white">
+```html +demo-folded class="bx example-jtb"
+<nav>
     <ul class="menu">
         <li class="relative" x-data="{ open: false }" x-on:click.outside="open = false" x-on:keydown.escape="open = false">
             <button x-on:click="open = ! open">
@@ -123,10 +133,23 @@ dropdowns. Uses Alpine.js for toggle behavior.
 </nav>
 ```
 
+## SCSS Variables (review)
+
+| Variable                      | Default                                    | Description                  |
+| ----------------------------- | ------------------------------------------ | ---------------------------- |
+| `$menu-padding-x`             | `0.75rem`                                  | Horizontal item padding      |
+| `$menu-padding-y`             | `0.5rem`                                   | Vertical item padding        |
+| `$menu-icon-size`             | `1.25rem`                                  | Icon width and height        |
+| `$menu-hover-bg`              | `gray-100`                                 | Item hover background        |
+| `$menu-link-hover-color`      | `$primary`                                 | Item hover and active colour |
+| `$menu-link-underline-color`  | `$primary`                                 | Underline variant colour     |
+
+See [Variable System](/docs/jtb/variable-system) for override instructions.
+
 ## Utility Examples (review)
 
-```html +demo-folded
-<nav class="bx">
+```html +demo-folded class="bx example-utils"
+<nav>
     <ul class="txt-sm">
         <li>
             <a href="#" class="flex items-center gap-075 px-075 py-05 rounded-lg txt-gray-600 hover:bg-gray-100">
@@ -162,4 +185,3 @@ dropdowns. Uses Alpine.js for toggle behavior.
     </ul>
 </nav>
 ```
-

package/docs/examples/showcase-ui.md

@@ -1,10 +1,77 @@
 # JTB UI Showcase
 
+## Boxes
+
+```html +demo-folded
+<div class="bx relative overflow-hidden max-w-384px" style="background-color: var(--brand-primary-surface); border-color: var(--brand-primary-surface-border);">
+    <svg class="absolute -top-1.5 -right-1.5 opacity-10" width="120" height="120" viewBox="0 0 120 120" style="color: var(--brand-primary)">
+        <circle cx="60" cy="60" r="50" fill="currentColor"/>
+        <circle cx="60" cy="60" r="35" fill="none" stroke="currentColor" stroke-width="2"/>
+        <circle cx="60" cy="60" r="20" fill="none" stroke="currentColor" stroke-width="2"/>
+    </svg>
+    <svg class="absolute -bottom-1 -left-1 opacity-10" width="80" height="80" viewBox="0 0 80 80" style="color: var(--brand-primary)">
+        <circle cx="40" cy="40" r="35" fill="currentColor"/>
+    </svg>
+    <p class="txt-xs font-medium uppercase tracking-widest opacity-70" style="color: var(--brand-primary)">Also available as</p>
+    <p class="font-serif txt-base font-medium" style="color: var(--brand-primary-on-surface)">Part of a program</p>
+    <p class="txt-sm" style="color: var(--brand-primary-on-surface)">Save with a bundle discount when you enrol in the full program.</p>
+    <a href="#" class="txt-sm font-medium inline-flex items-center gap-025" style="color: var(--brand-primary)">View program →</a>
+</div>
+```
+
+## Brand colour + corner shapes
+
+```html +demo-folded
+<div class="bx primary relative overflow-hidden max-w-384px">
+    <svg class="absolute -top-1.5 -right-1.5 opacity-10" width="100" height="100" viewBox="0 0 100 100">
+        <rect x="10" y="10" width="80" height="80" rx="8" fill="white"/>
+        <rect x="25" y="25" width="50" height="50" rx="4" fill="none" stroke="white" stroke-width="2"/>
+    </svg>
+    <svg class="absolute -bottom-1.5 -left-1.5 opacity-10" width="90" height="90" viewBox="0 0 90 90">
+        <circle cx="45" cy="45" r="40" fill="white"/>
+        <circle cx="45" cy="45" r="25" fill="none" stroke="white" stroke-width="2"/>
+    </svg>
+    <p class="txt-xs font-medium uppercase tracking-widest txt-rose-200 opacity-80">Also available as</p>
+    <p class="font-serif txt-base font-medium">Part of a program</p>
+    <p class="txt-sm txt-rose-200 opacity-90">Save with a bundle discount when you enrol in the full program.</p>
+    <a href="#" class="txt-sm font-medium inline-flex items-center gap-025">View program →</a>
+</div>
+```
+
+## left border accent
+
+```html +demo-folded
+<div class="bx relative overflow-hidden max-w-384px bdr-l-3 bdr-l-primary">
+    <p class="txt-xs font-medium uppercase tracking-widest opacity-70" style="color: var(--primary)">Also available as</p>
+    <p class="font-serif txt-base font-medium">Part of a program</p>
+    <p class="txt-sm txt-muted">Save with a bundle discount when you enrol in the full program.</p>
+    <a href="#" class="txt-sm font-medium inline-flex items-center gap-025" style="color: var(--primary)">View program →</a>
+</div>
+```
+
+## diagonal shape bleed
+
+```html +demo-folded
+<div class="bx relative overflow-hidden max-w-384px" style="background-color: var(--brand-primary-surface); border-color: var(--brand-primary-surface-border);">
+    <svg class="absolute top-0 right-0" width="120" height="120" viewBox="0 0 120 120" style="color: var(--brand-primary)">
+        <polygon points="120,0 120,120 0,0" fill="currentColor" opacity="0.08"/>
+        <polygon points="120,0 120,80 40,0" fill="currentColor" opacity="0.08"/>
+    </svg>
+    <svg class="absolute bottom-0 left-0" width="70" height="70" viewBox="0 0 70 70" style="color: var(--brand-primary)">
+        <polygon points="0,70 70,70 0,0" fill="currentColor" opacity="0.06"/>
+    </svg>
+    <p class="txt-xs font-medium uppercase tracking-widest opacity-70" style="color: var(--brand-primary)">Also available as</p>
+    <p class="font-serif txt-base font-medium" style="color: var(--brand-primary-on-surface)">Part of a program</p>
+    <p class="txt-sm" style="color: var(--brand-primary-on-surface)">Save with a bundle discount when you enrol in the full program.</p>
+    <a href="#" class="txt-sm font-medium inline-flex items-center gap-025" style="color: var(--brand-primary)">View program →</a>
+</div>
+```
+
 ## Lists
 
 ### Checklist
 
-```html +demo-folded class="bx" class="bx"
+```html +demo-folded class="bx"
 <ul class="checklist">
     <li>12 months access from enrolment</li>
     <li>Downloadable resources included</li>
@@ -82,7 +149,7 @@
 
 ### Checklist (utility)
 
-```html +demo-folded class="bx" class="bx"
+```html +demo-folded class="bx"
 <ul class="space-y-05 txt-sm">
     <li class="flex gap-05">
         <svg class="wh-1.25 rounded-full bg-orange-100 txt-primary pxy-025" fill="none" viewBox="0 0 10 8" stroke="currentColor" stroke-width="1.5">

package/docs/jtb-status.md

@@ -287,6 +287,12 @@ Files parked in `docs/review/` — purpose or audience unclear.
 | `api/make-themes.md`                | audit  |                                       |
 | `api/variables.md`                  | ✅     |                                       |
 
+### Layouts
+
+| File                                  | Status  | Notes                                              |
+| ------------------------------------- | ------- | -------------------------------------------------- |
+| `layouts/layout-sidebar-main.md`      | partial | Base structure and independent scrolling confirmed |
+
 ### Components
 
 | File                                | Status  | Notes                                            |

package/docs/layouts/layout-sidebar-main.md

@@ -0,0 +1,84 @@
+# Sidebar + Main Layout (review)
+
+A two-column layout with a persistent sidebar and a main content area. Start with the base structure and layer characteristics on top as needed.
+
+## Base Structure
+
+A minimal shell: fixed-width sidebar, flex-fill main area.
+
+- `fs-0` prevents the sidebar from shrinking
+- `flex-1` on main fills the remaining space
+
+```html +demo-folded class="resizable-container with-docs-only-overrides"
+<div class="flex min-h-screen">
+    <aside class="w-16 fs-0 flex-col bg-slate-900">
+    </aside>
+
+    <main class="flex-1 bg-gray-200">
+    </main>
+</div>
+```
+
+## Characteristics (review)
+
+### Independent Scrolling
+
+Each region scrolls independently within its own bounds. The outer container needs a fixed height — not a min-height — so both regions know where they end. The specific height depends on context (`h-screen` for a full app shell, `h-full` inside another container).
+
+- Add `overflow-hidden` to the outer container and use a fixed height, not `min-h-screen`
+- Add `overflow-y-auto` to the sidebar
+- Add `overflow-y-auto` to main
+
+```html +demo-folded class="resizable-container with-docs-only-overrides"
+<div class="flex h-20 overflow-hidden">
+    <aside class="w-16 fs-0 flex-col bg-slate-900 overflow-y-auto">
+        <div class="pxy-075 space-y">
+            <div class="h-6 bg-slate-700 rounded"></div>
+            <div class="h-12 bg-slate-700 rounded"></div>
+        </div>
+    </aside>
+
+    <main class="flex-1 bg-gray-200 overflow-y-auto">
+        <div class="container-md py space-y">
+            <div class="bx h-8"></div>
+            <div class="bx h-10"></div>
+        </div>
+    </main>
+</div>
+```
+
+### Sticky Sidebar Header and Footer (review)
+
+When the sidebar needs a persistent header or footer, `overflow-y-auto` moves from the `aside` to an inner content region. The aside itself becomes the fixed frame; only the content between the header and footer scrolls.
+
+- Remove `overflow-y-auto` from the `aside`
+- Add a `<header>` and `<footer>` as direct children of the `aside`
+- Wrap the scrollable content in a `div` with `flex-1 overflow-y-auto`
+
+```html +demo-folded class="resizable-container with-docs-only-overrides"
+<div class="flex h-20 overflow-hidden">
+    <aside class="w-16 fs-0 flex-col bg-slate-900">
+        <header class="pxy-075 bdr-b bdr-slate-700">
+            <div class="h-2 bg-slate-600 rounded"></div>
+        </header>
+
+        <div class="flex-1 overflow-y-auto pxy-075 space-y">
+            <div class="h-6 bg-slate-700 rounded"></div>
+            <div class="h-12 bg-slate-700 rounded"></div>
+            <div class="h-6 bg-slate-700 rounded"></div>
+            <div class="h-6 bg-slate-700 rounded"></div>
+        </div>
+
+        <footer class="pxy-075 bdr-t bdr-slate-700">
+            <div class="h-2 bg-slate-600 rounded"></div>
+        </footer>
+    </aside>
+
+    <main class="flex-1 bg-gray-200 overflow-y-auto">
+        <div class="container-md py space-y">
+            <div class="bx h-8"></div>
+            <div class="bx h-10"></div>
+        </div>
+    </main>
+</div>
+```

package/docs/layouts-and-structures.md

@@ -1,92 +1,45 @@
-# JTB Layouts and Structures
-
-<p class="lead">Named layout patterns for page-level structure, with a clear distinction between layouts and reusable internal structures.</p>
-
-> Example previews may use docs-only wrapper overrides so they display cleanly
-> inside the documentation. The example code itself remains the correct
-> implementation to copy and use.
-
+# Layouts and Structures
+
+Named patterns for page-level structure. Layouts describe the overall shape of a page or major region. Structures are reusable internal arrangements that can appear inside any layout.
+
 ## Layouts
 
 Layouts describe the overall shape of a page or major page region.
 
 ### Defaults
 
-- use `container` for standard page sections
-- let the section or component own its internal padding
-- use `py-4-3-2` as a standard section rhythm
-- use `py-5-3-2` for more prominent sections
-
-### Sidebar + Main
-
-A layout with a persistent sidebar for navigation and a main area for the
-primary workspace. The sidebar width is deliberate and usually stays consistent.
-
-Typical use cases:
-
-- admin dashboards
-- account areas
-
-#### Flexbox Example (preferred)
-
-Typical implementation:
-
-- `flex` container
-- fixed-width sidebar using width utilities
-- `flex-1` main area
-
-```html +demo-folded class="resizable-container with-docs-only-overrides"
-<div class="flex min-h-screen">
-    <!-- Sidebar -->
-    <aside class="w-16 fs-0 to-md:hidden flex-col bg-slate-900 ">
-        <header class="pxy-075 bdr-b bdr-gray-200">
-            <div class="h-2 bg-slate-700 rounded"></div>
-        </header>
-
-        <div class="flex-1 pxy-075 space-y">
-            <div class="h-full bg-slate-700 rounded"></div>
-        </div>
-
-        <footer class="pxy-075 bdr-t bdr-gray-200">
-            <div class="h-2 bg-slate-700 rounded"></div>
-        </footer>
-    </aside>
-
-    <!-- Main Content Area -->
-    <main class="flex-1 bg-gray-200">
-        <div class="container-md py">
-            <div class="bx h-4"></div>
-            <div class="bx h-14"></div>
-        </div>
-    </main>
-</div>
-```
-
-## Structures
-
-Structures are reusable internal arrangements that can appear inside different
-layouts.
-
-Common use cases:
-
-- layouts with a dominant content region and a smaller supporting panel
-- pages that pair primary content with summary, context, or actions
-- sections that need a proportional split without equal visual weight
-
-### thirds-2-1
-
-A proportional structure with a larger primary region and a smaller supporting
-region in a two-thirds / one-third split.
-
-```html +demo-folded class="resizable-container with-docs-only-overrides"
-<div class="grid gap lg:cols-3">
-    <div class="lg:col-span-2 space-y">
-        <div class="bx h-6"></div>
-        <div class="bx h-10"></div>
-    </div>
-
-    <aside class="lg:col-span-1">
-        <div class="bx h-12"></div>
-    </aside>
-</div>
-```
+- Use `container` for standard page sections
+- Let the section or component own its internal padding
+- Use `py-4-3-2` as a standard section rhythm
+- Use `py-5-3-2` for more prominent sections
+
+### Individual Layout Docs
+
+- [Sidebar + Main](/docs/jtb/layouts/layout-sidebar-main)
+
+## Structures
+
+Structures are reusable internal arrangements that can appear inside different layouts.
+
+Common use cases:
+
+- layouts with a dominant content region and a smaller supporting panel
+- pages that pair primary content with summary, context, or actions
+- sections that need a proportional split without equal visual weight
+
+### thirds-2-1
+
+A proportional structure with a larger primary region and a smaller supporting region in a two-thirds / one-third split.
+
+```html +demo-folded class="resizable-container with-docs-only-overrides"
+<div class="grid gap lg:cols-3">
+    <div class="lg:col-span-2 space-y">
+        <div class="bx h-6"></div>
+        <div class="bx h-10"></div>
+    </div>
+
+    <aside class="lg:col-span-1">
+        <div class="bx h-12"></div>
+    </aside>
+</div>
+```