nk_jtb 0.28.0 → 0.28.2

package/.ai/skills/jtb-documentation/SKILL.md

@@ -51,6 +51,8 @@ and typography helpers.
 - `preview-class="..."` → class applied to the preview container only, keeps copied code clean
 - `+demo` / `+demo-folded` → render preview and code together
 
+Use raw HTML (no demo attribute) when the block is purely visual demonstration and the markup is scaffold — showing the code would add noise rather than value.
+
 For layout/responsive docs, use:
 
 ```md
@@ -59,7 +61,9 @@ For layout/responsive docs, use:
 
 ## Examples Files
 
-Quick visual references — not comprehensive docs. Two files:
+Quick visual references — not comprehensive docs.
+
+**Default files:**
 
 - `docs/examples/showcase-typography.md` — font sizes, weights, families, text utilities
 - `docs/examples/showcase-ui.md` — components and UI elements: buttons, badges, checklist, box etc.
@@ -76,8 +80,6 @@ Format depends on content type:
 
 Group by component family under `##` headings. Variants sit under `###` within that group.
 
-Do not create a new examples file for a single component. If it does not fit the two above, discuss with the user.
-
 When a section of a component or utility doc is complete, ask:
 
 > Do you want this added to an examples file?

package/AGENTS.md

@@ -198,16 +198,26 @@ follow the direction.
 - When a skill system is available and a skill applies, invoke it before
   proceeding unless it conflicts with the user's explicit request.
 - Do not treat reading a `SKILL.md` file as a substitute for invoking the skill.
-- When updating prompts, guidelines, or skills, first identify the project's
-  source-of-truth file before editing.
 - Skills and guidelines are always edited via `.ai/` — never agent-managed
-  directories (`.claude/`, `.cursor/`, `.windsurf/`, etc.) directly.
-- Check whether the `.ai/` entry is a local file or a symlink before editing.
-  If it is a symlink, follow it to the target and edit there.
+  directories (`.claude/`, `.cursor/`, `.windsurf/`, etc.) directly. The path
+  you read from when a skill is invoked is never the path you edit.
+- Before editing any skill or guideline, run `ls -la .ai/skills/` or
+  `ls -la .ai/guidelines/` to confirm the correct source path. Do this every
+  time — do not skip it, do not rely on Glob, do not edit the path you read from.
+- Glob does not follow or reveal symlinks and will return misleading results.
+  Always use `ls -la` to locate files in `.ai/`.
+- If the file cannot be found after checking with `ls -la`, stop and ask.
+  Do not assume it does not exist, do not fall back to agent-managed
+  directories, and do not proceed without knowing the correct location.
+- Check whether the `.ai/` entry is a local file or a symlink. If it is a
+  symlink, follow it to the target and edit there.
 - Do not update matching copies in parallel or alternate locations unless they
   are the confirmed source of truth or the user explicitly asks.
-- After changing project guidelines or adding/updating skills, run
-  `php artisan boost:update` in the project so the changes take effect.
+- After changing project guidelines or adding/updating skills, run the
+  project's sync command to propagate changes to agent-managed directories.
+  Check `package.json` for an `ai:sync` script or equivalent. If no sync
+  command is available, note that the change will not propagate until the next
+  sync.
 - When a skill or prompt references a file that cannot be read, first try
   resolving it from the repository root.
 - If the file still cannot be found, stop and ask before proceeding.

package/CLAUDE.md

@@ -198,16 +198,26 @@ follow the direction.
 - When a skill system is available and a skill applies, invoke it before
   proceeding unless it conflicts with the user's explicit request.
 - Do not treat reading a `SKILL.md` file as a substitute for invoking the skill.
-- When updating prompts, guidelines, or skills, first identify the project's
-  source-of-truth file before editing.
 - Skills and guidelines are always edited via `.ai/` — never agent-managed
-  directories (`.claude/`, `.cursor/`, `.windsurf/`, etc.) directly.
-- Check whether the `.ai/` entry is a local file or a symlink before editing.
-  If it is a symlink, follow it to the target and edit there.
+  directories (`.claude/`, `.cursor/`, `.windsurf/`, etc.) directly. The path
+  you read from when a skill is invoked is never the path you edit.
+- Before editing any skill or guideline, run `ls -la .ai/skills/` or
+  `ls -la .ai/guidelines/` to confirm the correct source path. Do this every
+  time — do not skip it, do not rely on Glob, do not edit the path you read from.
+- Glob does not follow or reveal symlinks and will return misleading results.
+  Always use `ls -la` to locate files in `.ai/`.
+- If the file cannot be found after checking with `ls -la`, stop and ask.
+  Do not assume it does not exist, do not fall back to agent-managed
+  directories, and do not proceed without knowing the correct location.
+- Check whether the `.ai/` entry is a local file or a symlink. If it is a
+  symlink, follow it to the target and edit there.
 - Do not update matching copies in parallel or alternate locations unless they
   are the confirmed source of truth or the user explicitly asks.
-- After changing project guidelines or adding/updating skills, run
-  `php artisan boost:update` in the project so the changes take effect.
+- After changing project guidelines or adding/updating skills, run the
+  project's sync command to propagate changes to agent-managed directories.
+  Check `package.json` for an `ai:sync` script or equivalent. If no sync
+  command is available, note that the change will not propagate until the next
+  sync.
 - When a skill or prompt references a file that cannot be read, first try
   resolving it from the repository root.
 - If the file still cannot be found, stop and ask before proceeding.

package/docs/automatic-spacing.md

@@ -1,47 +1,14 @@
-# Auto Spacing System (review)
+# Auto Spacing
 
 <p class="lead">Automatic vertical spacing between block elements without
-requiring margin utilities on every element. Content flows naturally with
-consistent gaps.</p>
+requiring margin utilities on every element.</p>
 
-- **Relationship-Based** - Spacing determined by what elements follow each other
-- **Semantic-Aware** - Distinguishes between content and layout wrappers
 - **Flex/Grid Safe** - Automatically opts out when using gap-based layouts
 - **Low Specificity** - Uses `:where()` for easy overrides
 
-## How It Works (review)
+## Examples
 
-Two rules apply `margin-top: $base-gap` based on element relationships. Spacing
-targets (`p`, `h1-h6`, `table`, `ul`, etc.) add spacing when followed by other
-elements. Layout wrappers (`div`, `section`, `article`) only add spacing when
-followed by content—not other wrappers.
-
-## The Rules (review)
-
-### Rule 1: Spacing Targets (review)
-
-Content elements followed by any block element.
-
-```scss +code
-:where(#{$spacing-targets}, #{$common-classes}) + :where(*:not(#{$inline-exclusions})) {
-    margin-block-start: $base-gap;
-}
-```
-
-### Rule 2: Layout to Content (review)
-
-Layout wrappers followed by content elements. This prevents `div + div` spacing
-while catching `div + p`.
-
-```scss +code
-:where(div, section, article) + :where(#{$spacing-targets}) {
-    margin-block-start: $base-gap;
-}
-```
-
-## Visual Tests (review)
-
-### Should Space (review)
+### Should Space
 
 <div class="bx bg-stripes-pink">
     <h2 class="pxy-075 warning-light rounded-05">Heading 2</h2>
@@ -55,7 +22,7 @@ while catching `div + p`.
     <pre class="pxy-075 warning-light rounded-05">Pre</pre>
 </div>
 
-### Should NOT Space (review)
+### Should NOT Space
 
 <div class="bx bg-stripes-blue">
     <div class="pxy-075 info-light rounded-05">Div</div>
@@ -66,16 +33,10 @@ while catching `div + p`.
     <footer class="pxy-075 info-light rounded-05">Footer</footer>
 </div>
 
-## Flex and Grid (review)
+### Flex and Grid
 
 Elements inside flex or grid containers have margins reset—these layouts use `gap` instead.
 
-```scss +code
-:where([class*='flex'], [class*='grid']) > * {
-    margin: 0;
-}
-```
-
 <div class="grid cols-2 gap-1">
     <div>
         <p class="txt-sm">Flex (uses gap)</p>
@@ -95,3 +56,17 @@ Elements inside flex or grid containers have margins reset—these layouts use `
         </div>
     </div>
 </div>
+
+## How It Works
+
+Spacing is applied by element relationship, not position. Two categories determine behaviour:
+
+**Spacing targets** — `p`, headings, `ul`, `table`, `form`, `blockquote`, `pre` — add
+`margin-block-start` to whatever follows them.
+
+**Layout wrappers** — `div`, `section`, `article` — only add spacing when followed by
+content, not other wrappers. This prevents `div + div` from being spaced while
+still catching `div + p`.
+
+Elements inside flex or grid containers are exempt — margins reset to zero and
+`gap` handles spacing instead.

package/docs/jtb-status.md

@@ -242,7 +242,7 @@ a doc is confirmed accurate or a utility is completed.
 | `layouts-and-structures.md`                | ✅       |                                                                                        |
 | `responsive-design-patterns.md`            | review  |                                                                                        |
 | `responsive-design.md`                     | review  |                                                                                        |
-| `automatic-spacing.md`                     | review  |                                                                                        |
+| `automatic-spacing.md`                     | ✅       |                                                                                        |
 | `conventions-and-architecture-rules.md`    | review  |                                                                                        |
 | `magic-classes.md`                         | ✅       |                                                                                        |
 | `themes.md`                                | review  |                                                                                        |

package/homepage-examples.html

@@ -0,0 +1,416 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>JTB — Homepage Examples</title>
+</head>
+
+<body>
+
+    <!-- ═══════════════════════════════════════════════════════════════
+         EXAMPLE 1: AURORA
+         Dark gradient hero with floating blob shapes and swirl decoration
+         ═══════════════════════════════════════════════════════════════ -->
+
+    <nav class="navbar bg-slate-900">
+        <div class="container">
+            <a href="#" class="flex items-center gap-1">
+                <svg width="28" height="28" viewBox="0 0 28 28" fill="none" aria-hidden="true">
+                    <circle cx="14" cy="14" r="14" fill="oklch(60.6% 0.25 292.717deg)" />
+                    <path d="M8 20 L14 8 L20 20 M10.5 16 H17.5" stroke="white" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" />
+                </svg>
+                <span class="txt-white font-bold tracking-tight">Luminary</span>
+            </a>
+            <ul class="menu">
+                <li><a href="#" class="txt-gray-400">Features</a></li>
+                <li><a href="#" class="txt-gray-400">Pricing</a></li>
+                <li><a href="#" class="txt-gray-400">Docs</a></li>
+                <li><a href="#" class="txt-gray-400">Blog</a></li>
+            </ul>
+            <div class="flex gap-1">
+                <button class="btn sm">Sign in</button>
+                <button class="btn sm primary">Get Started</button>
+            </div>
+        </div>
+    </nav>
+
+    <div class="ex-hero bg-linear-to-br from-violet-950 to-indigo-900 relative overflow-hidden flex flex-col items-center justify-center pxy-4">
+
+        <!-- Blob shapes — organic border-radius via local helper -->
+        <div class="blob shape-tl absolute wh-30 bg-violet-500 opacity-20"></div>
+        <div class="blob-2 shape-br absolute wh-24 bg-indigo-400 opacity-20"></div>
+        <div class="rounded-full shape-mid-r absolute wh-16 bg-fuchsia-500 opacity-10"></div>
+        <div class="rounded-full shape-mid-l absolute wh-10 bg-sky-400 opacity-10"></div>
+
+        <!-- SVG swirl -->
+        <svg class="swirl-deco absolute opacity-10" width="600" height="600" viewBox="0 0 600 600" fill="none" aria-hidden="true">
+            <path d="M300 300 C300 200, 450 200, 450 300 C450 400, 300 400, 300 300 C300 150, 500 150, 500 300 C500 450, 250 500, 200 350 C150 200, 350 100, 450 200" stroke="white" stroke-width="1.5" fill="none" />
+            <path d="M300 300 C250 250, 200 300, 200 350 C200 420, 280 450, 350 420 C420 390, 460 320, 430 250 C400 180, 320 160, 260 200 C180 250, 160 360, 220 420 C280 480, 400 460, 450 380" stroke="white" stroke-width="1" fill="none" opacity="0.6" />
+        </svg>
+
+        <!-- Content -->
+        <div class="relative tac ex-hero-content">
+            <span class="txt-violet-300 txt-sm font-semibold tracking-widest uppercase">Platform &middot; 2025</span>
+            <h1 class="txt-white font-black lh-tight txt-4">Build beyond<br>ordinary limits</h1>
+            <p class="txt-indigo-200 lead">The design framework that lets you move fast without breaking things. Clean utilities, beautiful defaults, zero compromise.</p>
+            <div class="flex justify-center gap-1">
+                <button class="btn lg primary">Start for free</button>
+                <button class="btn lg">See the docs</button>
+            </div>
+        </div>
+
+        <!-- Bottom fade -->
+        <div class="absolute bottom-0 left-0 w-full ex-fade-bottom"></div>
+    </div>
+
+    <div class="ex-spacer bg-slate-900"></div>
+
+
+    <!-- ═══════════════════════════════════════════════════════════════
+         EXAMPLE 2: CLARITY
+         Light split hero with geometric shapes on the right
+         ═══════════════════════════════════════════════════════════════ -->
+
+    <nav class="navbar bg-white shadow-sm">
+        <div class="container">
+            <a href="#" class="flex items-center gap-1">
+                <svg width="24" height="24" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                    <rect x="2" y="2" width="9" height="9" rx="2" fill="oklch(62.3% 0.214 259.815deg)" />
+                    <rect x="13" y="2" width="9" height="9" rx="2" fill="oklch(70.2% 0.183 293.541deg)" opacity="0.6" />
+                    <rect x="2" y="13" width="9" height="9" rx="2" fill="oklch(70.2% 0.183 293.541deg)" opacity="0.6" />
+                    <rect x="13" y="13" width="9" height="9" rx="2" fill="oklch(62.3% 0.214 259.815deg)" />
+                </svg>
+                <span class="txt-slate-900 font-bold">Nexus</span>
+            </a>
+            <ul class="menu">
+                <li><a href="#" class="txt-gray-600">Product</a></li>
+                <li><a href="#" class="txt-gray-600">Solutions</a></li>
+                <li><a href="#" class="txt-gray-600">Enterprise</a></li>
+                <li><a href="#" class="txt-gray-600">Pricing</a></li>
+            </ul>
+            <div class="flex gap-1 items-center">
+                <a href="#" class="txt-gray-600 txt-sm">Log in</a>
+                <button class="btn sm primary">Book a demo</button>
+            </div>
+        </div>
+    </nav>
+
+    <div class="ex-hero bg-gray-50 relative overflow-hidden flex items-center">
+        <div class="container">
+            <div class="grid cols-2 items-center ex-hero-grid-gap">
+
+                <!-- Left: content -->
+                <div>
+                    <div class="flex items-center gap-05 ex-badge-row">
+                        <span class="badge primary">New</span>
+                        <span class="txt-sm txt-gray-600">v3.0 is here — <a href="#" class="txt-primary">read the changelog</a></span>
+                    </div>
+                    <h1 class="txt-slate-900 font-black lh-tight txt-3">The platform teams<br>actually love using</h1>
+                    <p class="lead txt-gray-600">Ship faster with infrastructure that gets out of your way. Built for teams who care about developer experience.</p>
+                    <div class="flex gap-1 items-center">
+                        <button class="btn lg primary">Get started free</button>
+                        <a href="#" class="flex items-center gap-05 txt-gray-600 txt-sm">
+                            <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
+                                <circle cx="8" cy="8" r="7.5" stroke="currentColor" stroke-width="1" />
+                                <path d="M6 5.5 L10.5 8 L6 10.5Z" fill="currentColor" />
+                            </svg>
+                            Watch 2 min demo
+                        </a>
+                    </div>
+                    <p class="txt-xs txt-muted">No credit card required &middot; 14-day free trial &middot; Cancel anytime</p>
+                </div>
+
+                <!-- Right: geometric decoration -->
+                <div class="relative ex-shapes-panel">
+                    <!-- Background ring -->
+                    <div class="rounded-full absolute geo-ring bg-blue-50 bdr bdr-blue-200"></div>
+                    <div class="rounded-full absolute geo-ring-inner bdr-2 bdr-blue-100" style="border-style: dashed;"></div>
+
+                    <!-- Floating cards -->
+                    <div class="bx shadow-lg absolute geo-card-1 ex-geo-card">
+                        <div class="flex items-center gap-05">
+                            <div class="rounded-full wh-2 bg-green-500"></div>
+                            <span class="txt-sm font-semibold txt-slate-900">Deploy successful</span>
+                        </div>
+                        <p class="txt-xs txt-muted">production &middot; 2s ago</p>
+                    </div>
+
+                    <div class="bx shadow-lg absolute geo-card-2 ex-geo-card">
+                        <span class="txt-xs txt-muted uppercase tracking-wider font-semibold">Uptime</span>
+                        <div class="flex items-center gap-05">
+                            <span class="txt-2 font-black txt-slate-900">99.9%</span>
+                        </div>
+                    </div>
+
+                    <div class="bx shadow-lg absolute geo-card-3 ex-geo-card">
+                        <span class="txt-xs txt-muted uppercase tracking-wider font-semibold">Team members</span>
+                        <div class="flex items-center">
+                            <div class="rounded-full wh-2 bg-violet-400 bdr-2 bdr-white" style="margin-inline-start: -0.25rem;"></div>
+                            <div class="rounded-full wh-2 bg-sky-400 bdr-2 bdr-white" style="margin-inline-start: -0.25rem;"></div>
+                            <div class="rounded-full wh-2 bg-emerald-400 bdr-2 bdr-white" style="margin-inline-start: -0.25rem;"></div>
+                            <div class="rounded-full wh-2 bg-rose-400 bdr-2 bdr-white" style="margin-inline-start: -0.25rem;"></div>
+                            <span class="txt-xs txt-muted mx-0.5">+14 more</span>
+                        </div>
+                    </div>
+
+                    <!-- Central shape -->
+                    <div class="geo-center rounded-xl bg-linear-to-br from-blue-500 to-violet-600 shadow-xl flex flex-col items-center justify-center absolute tac pxy-3">
+                        <svg width="48" height="48" viewBox="0 0 48 48" fill="none" aria-hidden="true">
+                            <path d="M24 4 L44 24 L24 44 L4 24Z" fill="white" opacity="0.2" />
+                            <path d="M24 12 L36 24 L24 36 L12 24Z" fill="white" opacity="0.4" />
+                            <circle cx="24" cy="24" r="6" fill="white" />
+                        </svg>
+                        <span class="txt-white font-bold txt-sm">Nexus Core</span>
+                    </div>
+
+                    <!-- Swirl SVG -->
+                    <svg class="geo-swirl absolute opacity-20" width="300" height="300" viewBox="0 0 300 300" fill="none" aria-hidden="true">
+                        <path d="M150 150 Q200 100 250 150 Q200 200 150 150 Q100 100 50 150 Q100 200 150 150" stroke="oklch(62.3% 0.214 259.815deg)" stroke-width="2" fill="none" />
+                        <path d="M150 150 Q220 80 290 150 Q220 220 150 150 Q80 80 10 150 Q80 220 150 150" stroke="oklch(62.3% 0.214 259.815deg)" stroke-width="1.5" fill="none" opacity="0.6" />
+                        <path d="M150 150 Q230 60 310 150" stroke="oklch(70.2% 0.183 293.541deg)" stroke-width="1" fill="none" opacity="0.5" />
+                    </svg>
+                </div>
+            </div>
+        </div>
+
+        <!-- Bottom wave -->
+        <svg class="wave-bottom" viewBox="0 0 1440 80" fill="none" preserveAspectRatio="none" aria-hidden="true">
+            <path d="M0 80 L0 40 Q360 0 720 40 Q1080 80 1440 40 L1440 80Z" fill="white" />
+        </svg>
+    </div>
+
+    <div class="ex-spacer bg-white"></div>
+
+
+    <!-- ═══════════════════════════════════════════════════════════════
+         EXAMPLE 3: DUSK
+         Cinematic dark image hero with frosted glass nav and wave divider
+         ═══════════════════════════════════════════════════════════════ -->
+
+    <div class="relative">
+        <!-- Nav sits inside hero to overlay it -->
+        <nav class="navbar-glass navbar absolute top-0 left-0 w-full z-above">
+            <div class="container">
+                <a href="#" class="flex items-center gap-1">
+                    <svg width="26" height="26" viewBox="0 0 26 26" fill="none" aria-hidden="true">
+                        <circle cx="13" cy="13" r="13" fill="white" opacity="0.15" />
+                        <path d="M7 13 Q13 5 19 13 Q13 21 7 13Z" fill="white" opacity="0.8" />
+                        <circle cx="13" cy="13" r="3" fill="white" />
+                    </svg>
+                    <span class="txt-white font-bold tracking-tight">Arcadia</span>
+                </a>
+                <ul class="menu">
+                    <li><a href="#" class="txt-white opacity-80">Work</a></li>
+                    <li><a href="#" class="txt-white opacity-80">Studio</a></li>
+                    <li><a href="#" class="txt-white opacity-80">Journal</a></li>
+                    <li><a href="#" class="txt-white opacity-80">Contact</a></li>
+                </ul>
+                <button class="btn sm" style="background: rgb(255 255 255 / 15%); border-color: rgb(255 255 255 / 30%); color: white;">
+                    Start a project
+                </button>
+            </div>
+        </nav>
+
+        <!-- Hero — gradient stands in for background image -->
+        <div class="ex-hero-dusk bg-linear-to-br from-slate-900 to-indigo-950 relative overflow-hidden">
+
+            <!-- "Photo" texture shapes -->
+            <div class="absolute inset-0 overflow-hidden">
+                <div class="rounded-full absolute photo-blob-1 bg-violet-800 opacity-30"></div>
+                <div class="rounded-full absolute photo-blob-2 bg-blue-900 opacity-40"></div>
+                <div class="blob absolute photo-blob-3 bg-indigo-800 opacity-20"></div>
+            </div>
+
+            <!-- Light streaks SVG -->
+            <svg class="absolute inset-0 w-full h-full opacity-10" viewBox="0 0 1200 700" preserveAspectRatio="xMidYMid slice" fill="none" aria-hidden="true">
+                <line x1="0" y1="700" x2="600" y2="0" stroke="white" stroke-width="1.5" />
+                <line x1="200" y1="700" x2="800" y2="0" stroke="white" stroke-width="0.75" />
+                <line x1="600" y1="700" x2="1100" y2="0" stroke="white" stroke-width="1" />
+                <line x1="900" y1="700" x2="1400" y2="100" stroke="white" stroke-width="0.5" />
+                <ellipse cx="700" cy="200" rx="300" ry="150" stroke="white" stroke-width="0.5" />
+            </svg>
+
+            <!-- Swirl overlay -->
+            <svg class="absolute swirl-dusk opacity-10" width="800" height="800" viewBox="0 0 800 800" fill="none" aria-hidden="true">
+                <path d="M400 400 C400 200, 650 200, 650 400 C650 600, 400 600, 400 400 C400 100, 750 100, 750 400 C750 700, 300 750, 200 500 C100 250, 450 100, 600 250" stroke="white" stroke-width="2" fill="none" />
+                <path d="M400 400 C350 350, 250 400, 250 500 C250 620, 370 660, 500 620 C630 580, 680 470, 640 350 C600 230, 470 200, 370 270 C250 360, 220 520, 320 620" stroke="white" stroke-width="1.2" fill="none" opacity="0.5" />
+                <circle cx="400" cy="400" r="180" stroke="white" stroke-width="0.5" opacity="0.3" />
+                <circle cx="400" cy="400" r="280" stroke="white" stroke-width="0.5" opacity="0.2" />
+            </svg>
+
+            <!-- Content -->
+            <div class="container ex-dusk-content relative">
+                <div class="ex-dusk-text">
+                    <span class="txt-indigo-300 txt-sm font-semibold tracking-widest uppercase">Creative Studio</span>
+                    <h1 class="txt-white font-black lh-tight txt-4">We craft digital<br>experiences that<br><em class="txt-violet-300">endure.</em></h1>
+                    <p class="txt-indigo-200 lead">Award-winning design and engineering for brands that refuse to be ordinary.</p>
+                    <div class="flex gap-1">
+                        <button class="btn lg primary">View our work</button>
+                        <button class="btn lg" style="background: rgb(255 255 255 / 10%); border-color: rgb(255 255 255 / 20%); color: white;">
+                            Our process
+                        </button>
+                    </div>
+                </div>
+            </div>
+
+            <!-- Wave divider -->
+            <svg class="wave-bottom" viewBox="0 0 1440 100" fill="none" preserveAspectRatio="none" aria-hidden="true">
+                <path d="M0 100 L0 60 Q200 20 400 50 Q600 80 800 40 Q1000 0 1200 30 Q1320 50 1440 20 L1440 100Z" fill="white" opacity="0.05" />
+                <path d="M0 100 L0 70 Q300 30 600 60 Q900 90 1200 50 Q1320 35 1440 40 L1440 100Z" fill="white" opacity="0.05" />
+                <path d="M0 100 L0 85 Q360 55 720 75 Q1080 95 1440 65 L1440 100Z" fill="rgb(15 23 42)" />
+            </svg>
+        </div>
+    </div>
+
+    <div class="ex-spacer bg-slate-950"></div>
+
+
+    <script type="module" src="/main.js"></script>
+
+    <style>
+        /*
+        ================================================================
+        LOCAL HELPERS — JTB gaps documented here
+        ================================================================
+
+        Gaps identified (candidates for JTB additions):
+
+        1.  min-h-{vh-fraction} — only min-h-screen (100vh) in JTB.
+            Useful: min-h-80vh, min-h-85vh for hero sections that
+            shouldn't consume the full viewport.
+
+        2.  backdrop-filter / blur — utilities commented out in JTB.
+            Critical for frosted-glass navbars. Currently relies on
+            inline or local CSS.
+
+        3.  Negative positioning (-top-{n}, -left-{n}) — not generated.
+            Needed for off-canvas decorative shapes.
+
+        4.  Organic blob border-radius — JTB has named/scale values but
+            no way to express e.g. "60% 40% 30% 70% / 60% 30% 70% 40%".
+            Could be solved with a small set of named blob variants.
+
+        5.  bg-transparent — transparent is not in JTB color maps.
+            Useful for overlay navbars and ghost buttons.
+
+        6.  gap-05 — JTB spacing values include 0.5 but the class name
+            sanitiser may render it as gap-0.5 not gap-05. This local
+            helper covers the gap (no pun intended) for sub-1 values
+            in flex rows.
+
+        7.  Gradient via-{color} — JTB gradients only support from/to,
+            no mid-stop.
+        ================================================================
+        */
+
+        /* --- Hero sizing ------------------------------------------ */
+        .ex-hero {
+            min-height: 88vh;
+            padding-block: 6rem 4rem;
+        }
+
+        .ex-hero-dusk {
+            min-height: 90vh;
+            padding-block: 6rem 5rem;
+        }
+
+        .ex-spacer { height: 2rem; }
+
+        /* --- Content max-widths ------------------------------------ */
+        .ex-hero-content { max-width: 44rem; }
+        .ex-dusk-text { max-width: 36rem; }
+        .ex-dusk-content { padding-block: 8rem 6rem; }
+
+        /* --- Bottom fade overlay ----------------------------------- */
+        .ex-fade-bottom {
+            height: 6rem;
+            background: linear-gradient(to bottom, transparent, rgb(15 10 40 / 60%));
+        }
+
+        /* --- Blob border-radius ------------------------------------ */
+        .blob { border-radius: 60% 40% 30% 70% / 60% 30% 70% 40%; }
+        .blob-2 { border-radius: 30% 70% 70% 30% / 30% 30% 70% 70%; }
+
+        /* --- Example 1 blob positions ------------------------------ */
+        .shape-tl { top: -8rem; inset-inline-start: -8rem; }
+        .shape-br { bottom: -10rem; inset-inline-end: -6rem; }
+        .shape-mid-r { top: 25%; inset-inline-end: 6%; }
+        .shape-mid-l { bottom: 20%; inset-inline-start: 8%; }
+
+        /* SVG swirl position */
+        .swirl-deco { top: 50%; left: 50%; transform: translate(-50%, -50%); pointer-events: none; }
+        .swirl-dusk { top: 50%; right: -10%; transform: translateY(-50%); pointer-events: none; }
+
+        /* --- Example 2 shapes panel -------------------------------- */
+        .ex-hero-grid-gap {
+            gap: 4rem;
+            min-height: 85vh;
+            padding-block: 6rem 3rem;
+        }
+
+        .ex-shapes-panel { height: 32rem; }
+
+        .geo-ring {
+            width: 28rem; height: 28rem;
+            top: 50%; left: 50%;
+            transform: translate(-50%, -50%);
+        }
+
+        .geo-ring-inner {
+            width: 20rem; height: 20rem;
+            top: 50%; left: 50%;
+            transform: translate(-50%, -50%);
+        }
+
+        .geo-center {
+            width: 10rem; height: 10rem;
+            top: 50%; left: 50%;
+            transform: translate(-50%, -50%);
+        }
+
+        .ex-geo-card { min-width: 11rem; }
+
+        .geo-card-1 { top: 10%; left: -2rem; }
+        .geo-card-2 { bottom: 15%; left: 2rem; }
+        .geo-card-3 { top: 15%; right: -1rem; }
+
+        .geo-swirl {
+            top: 50%; left: 50%;
+            transform: translate(-50%, -50%);
+            pointer-events: none;
+        }
+
+        /* --- Example 3 photo blobs --------------------------------- */
+        .photo-blob-1 { width: 40rem; height: 40rem; top: -10rem; right: -8rem; }
+        .photo-blob-2 { width: 30rem; height: 30rem; bottom: -5rem; left: -5rem; }
+        .photo-blob-3 { width: 20rem; height: 20rem; top: 30%; right: 20%; }
+
+        /* --- Frosted glass navbar ---------------------------------- */
+        .navbar-glass {
+            background: rgb(255 255 255 / 8%);
+            backdrop-filter: blur(12px);
+            -webkit-backdrop-filter: blur(12px);
+            border-bottom: 1px solid rgb(255 255 255 / 10%);
+        }
+
+        /* Override .navbar component background for glass variant */
+        nav.navbar.navbar-glass { background: rgb(255 255 255 / 8%); }
+
+        /* --- Wave divider ----------------------------------------- */
+        .wave-bottom {
+            position: absolute;
+            bottom: 0;
+            left: 0;
+            width: 100%;
+            height: 100px;
+        }
+
+        /* --- gap-05 fallback (sub-1 rem class name) --------------- */
+        .gap-05 { gap: 0.5rem; }
+        .mx-0\.5 { margin-inline: 0.25rem; }
+    </style>
+
+</body>
+</html>

package/index.html

@@ -10,18 +10,6 @@
 
 <body>
 
- 
-
-    <div class="mb-2.5">
-        <h2>Page loader</h2>
-        <div class="bx flex-col flex-centered gap-1">
-            <svg class="animate-dash wh-3 txt-blue-500" viewBox="0 0 44 44">
-                <circle cx="22" cy="22" r="16" stroke="currentColor" />
-            </svg>
-            <p class="txt-sm txt-muted">Loading your workspace…</p>
-        </div>
-    </div>
-
     <style>
         /* ============================================================
        Local helpers — JTB gaps documented in jtb-conversion-notes.md
@@ -183,6 +171,52 @@
     </style>
 
     <div class="py-1.5 container-md">
+     <style>
+
+/*SVG arc — @keyframes dash not in JTB animation utilities*/
+@keyframes dash {
+    0% {
+        stroke-dasharray: 1, 150;
+        stroke-dashoffset: 0;
+    }
+
+    50% {
+        stroke-dasharray: 90, 150;
+        stroke-dashoffset: -35;
+    }
+
+    100% {
+        stroke-dasharray: 90, 150;
+        stroke-dashoffset: -124;
+    }
+}
+
+.arc circle {
+    fill: none;
+    stroke-width: 3;
+    stroke-linecap: round;
+    animation: dash 1.4s ease-in-out infinite;
+}
+</style>
+
+<div class="mb-2.5">
+    <h2>SVG arc spinner</h2>
+    <div class="bx flex-vac flex-wrap gap-1.5">
+        <div class="flex-col flex-vac gap-05">
+            <svg class="animate-spin arc wh-2.5 txt-blue-500" viewBox="0 0 36 36">
+                <circle cx="18" cy="18" r="14" stroke="currentColor" />
+            </svg>
+            <span class="txt-xs txt-muted">smooth arc</span>
+        </div>
+        <div class="flex-col flex-vac gap-05">
+            <svg class="animate-spin arc wh-3 txt-emerald-500" viewBox="0 0 48 48">
+                <circle cx="24" cy="24" r="18" stroke="currentColor" />
+            </svg>
+            <span class="txt-xs txt-muted">teal / lg</span>
+        </div>
+    </div>
+</div>
+
         <div class="mb-2.5">
             <h2>Dot indicators</h2>
             <div class="bx flex-vac flex-wrap gap-1.5">
@@ -304,7 +338,15 @@
             </div>
         </div>
 
-
+        <div class="mb-2.5">
+            <h2>Page loader</h2>
+            <div class="bx flex-col flex-centered gap-1">
+                <svg class="animate-spin arc wh-3 txt-blue-500" viewBox="0 0 44 44">
+                    <circle cx="22" cy="22" r="16" stroke="currentColor" />
+                </svg>
+                <p class="txt-sm txt-muted">Loading your workspace…</p>
+            </div>
+        </div>
 
     </div>
 

package/jtb-conversion-notes.md

@@ -6,7 +6,7 @@ Actionable gaps found during conversion of `loaders_and_spinners.html`.
 
 | Gap                                 | Detail                                                                                                           |
 | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `@keyframes dash`                   | ✅ Added as `animate-dash` in `_animation.scss`.                                                                  |
+| `@keyframes dash`                   | SVG arc morphing — stroke-dasharray animates between values. No JTB equivalent. Candidate for `_animation.scss`. |
 | `@keyframes grow`                   | Vertical scale pulse for bar equalizer. No JTB equivalent.                                                       |
 | `@keyframes skeleton`               | Gradient sweep shimmer. Very commonly needed. Strong candidate for `_animation.scss`.                            |
 | `@keyframes progress-indeterminate` | Horizontal bar sweep for indeterminate progress. No JTB equivalent.                                              |
@@ -24,5 +24,5 @@ Actionable gaps found during conversion of `loaders_and_spinners.html`.
 
 | Gap                    | Detail                                                                                                                                          |
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| Spinner colour theming | ✅ `.spinner` component removed — spinner is now utility-based, colour via `txt-*`.                                                             |
+| Spinner colour theming | `.spinner` hardcodes `#f3f3f3` and `#3498db` — no CSS custom properties for colour. Accent and button-context spinners require local overrides. |
 | Icon-only button       | `.btn` has no square/icon variant. A `btn-icon` or `btn xs` pattern would cover `width = height, padding: 0`.                                   |

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "nk_jtb",
     "description": "Yet another utility based framework.",
-    "version": "0.28.0",
+    "version": "0.28.2",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/naykel76/nk_jtb.git"

package/scripts/jtb-nav.json

@@ -15,6 +15,10 @@
     },
     "Core Concepts": {
         "links": [
+            {
+                "name": "Auto Spacing",
+                "route_name": "docs.jtb.automatic-spacing"
+            },
             {
                 "name": "Layout & Structures",
                 "route_name": "docs.jtb.layouts-and-structures",

package/skills-lock.json

@@ -23,7 +23,7 @@
       "source": "naykel76/skills-and-guidelines",
       "sourceType": "github",
       "skillPath": "nk-documentation-best-practices/SKILL.md",
-      "computedHash": "64d145c8e7e332c70805a8faddf1fc2afe276aa6f3300c6c924c8a9f0fba7d85"
+      "computedHash": "ee039aac7739637fdab654b4ed156667bbf02937ba3510c1f8d928ce8215bacc"
     },
     "skill-creation": {
       "source": "naykel76/skills-and-guidelines",

package/src/base/_auto-spacing.scss

@@ -18,6 +18,16 @@ $inline-exclusions: svg, span;
     margin-block-start: $base-gap;
 }
 
+// Headings connect to text content below — tighter gap than $base-gap
+// Block components (.bx etc) fall back to $base-gap via the general rule
+:where(h1) + :where(p, ul, ol, blockquote) {
+    margin-block-start: 1rem;
+}
+
+:where(h2, h3, h4, h5, h6) + :where(p, ul, ol, blockquote) {
+    margin-block-start: 0.75rem;
+}
+
 // Reverse pattern - layout elements followed by content elements
 // Catches cases like div + p, section + h1, article + table, etc.
 // We can't add div/section/article to $spacing-targets because that would also
@@ -33,7 +43,7 @@ $inline-exclusions: svg, span;
 }
 
 // opt out for `flex` and `grid` element and use `gap` instead
-:where([class*='flex'], [class*='grid']) > * {
+:where([class~='flex'], [class~='flex-col'], [class~='flex-row'], [class~='flex-centered'], [class~='flex-vac'], [class~='flex-hac'], [class*='grid']) > * {
     margin: 0;
 }
 

package/src/base/_root.scss

@@ -2,16 +2,6 @@
 @use '../maps_and_variables/colors' as *;
 @use '../maps_and_variables/components' as *;
 @use '../maps_and_variables/typography' as *;
-@use '../functions/color-functions' as *;
-@use 'sass:map';
-
-@mixin define-runtime-theme-vars($theme-name, $theme-color) {
-    --#{$theme-name}: #{$theme-color};
-    --#{$theme-name}-hover: color-mix(in srgb, var(--#{$theme-name}), white 5%);
-    --#{$theme-name}-active: color-mix(in srgb, var(--#{$theme-name}), black 5%);
-    --#{$theme-name}-border: #{border-contrast($theme-color)};
-    --on-#{$theme-name}: #{text-color($theme-color)};
-}
 
 :root {
     // create css variables including brand colors
@@ -47,10 +37,10 @@
     --bg-toggle-on: var(--primary);
     --bg-toggle-ball: var(--white);
 
-    // -- Runtime Semantic Theme Colors --
-    @each $theme-name in $runtime-theme-colors {
-        @include define-runtime-theme-vars($theme-name, map.get($base-colors, $theme-name));
-    }
+    // -- Brand Colors --
+    --primary: #{$primary};
+    --secondary: #{$secondary};
+    --accent: #{$accent};
 
     // -- Text Colors --
     --text-color: #{$text-color};

package/src/base/_typography.scss

@@ -19,7 +19,7 @@
     text-wrap: balance;
 }
 
-:where(h2, h3, h4, h5, h6):where(:not(:first-child)) {
+:is(h2, h3, h4, h5, h6):not(:first-child) {
     margin-block-start: 1.5em;
 }
 

package/src/components/_button.scss

@@ -109,19 +109,3 @@
         @include active($color);
     }
 }
-
-@each $theme-name in $runtime-theme-colors {
-    .#{$button-prefix}.#{$theme-name} {
-        &:hover {
-            background-color: var(--#{$theme-name}-hover);
-            border-color: var(--#{$theme-name}-border);
-            color: var(--on-#{$theme-name});
-        }
-
-        &:active {
-            background-color: var(--#{$theme-name}-active);
-            border-color: var(--#{$theme-name}-border);
-            color: var(--on-#{$theme-name});
-        }
-    }
-}

package/src/maps_and_variables/_colors.scss

@@ -51,10 +51,6 @@ $theme-colors: (
     'warning': #ffdd57
 ) !default;
 
-// Semantic theme names that should remain runtime-swappable via CSS custom
-// properties. Hue and scale colors stay compile-time tokens.
-$runtime-theme-colors: ('primary', 'secondary', 'accent') !default;
-
 // based on Tailwind 500 series colors
 $base-colors: (
     'primary': base.$primary,

package/src/utilities/_backgrounds.scss

@@ -22,18 +22,4 @@ $background-color-properties: (
     )
 );
 
-$runtime-background-colors: ();
-
-@each $theme-name in $runtime-theme-colors {
-    $runtime-background-colors: map.set($runtime-background-colors, $theme-name, var(--#{$theme-name}));
-}
-
-$runtime-background-color-properties: (
-    background-color: (
-        prefix: 'bg-',
-        values: $runtime-background-colors
-    )
-);
-
 @include build-classes($background-color-properties, $responsive: false, $with-state: true);
-@include build-classes($runtime-background-color-properties, $responsive: false, $with-state: true);

package/src/utilities/_border.scss

@@ -51,23 +51,6 @@ $divider-properties-map: (
     )
 ) !default;
 
-$runtime-border-colors: ();
-
-@each $theme-name in $runtime-theme-colors {
-    $runtime-border-colors: map.set($runtime-border-colors, $theme-name, var(--#{$theme-name}));
-}
-
-$runtime-border-properties-map: (
-    border-color: (
-        prefix: #{$border-prefix},
-        values: $runtime-border-colors
-    ),
-    outline-color: (
-        prefix: 'outline-',
-        values: $runtime-border-colors
-    )
-);
-
 .divide-y-gradient > :not(:last-child) {
     border-block-end-width: 3px;
     border-image-slice: 1;
@@ -85,5 +68,4 @@ $runtime-border-properties-map: (
 // Builds
 // ============================================================================
 @include build-classes($border-properties-map, $responsive: true);
-@include build-classes($runtime-border-properties-map, $responsive: true);
 @include build-composite-classes($divider-properties-map, $responsive: true);

package/src/utilities/_themes.scss

@@ -50,22 +50,3 @@ $themes-map: ();
 @each $color, $value in map.merge($base-colors, $theme-colors) {
     @include build-outline-theme('#{$color}-outline', $value);
 }
-
-@each $theme-name in $runtime-theme-colors {
-    .#{$theme-name} {
-        background-color: var(--#{$theme-name});
-        border: 1px solid var(--#{$theme-name}-border);
-        color: var(--on-#{$theme-name});
-    }
-
-    .#{$theme-name}-outline {
-        background-color: transparent;
-        border: 1px solid var(--#{$theme-name});
-        color: var(--#{$theme-name});
-
-        &:hover:not(:disabled, .disabled) {
-            background-color: var(--#{$theme-name});
-            color: var(--on-#{$theme-name});
-        }
-    }
-}

package/src/utilities/_typography.scss

@@ -124,23 +124,8 @@ $text-classes-map: (
     )
 );
 
-$runtime-text-colors: ();
-
-@each $theme-name in $runtime-theme-colors {
-    $runtime-text-colors: map.set($runtime-text-colors, $theme-name, var(--#{$theme-name}));
-}
-
-$runtime-typography-properties-map: (
-    color: (
-        prefix: '#{$text-prefix}',
-        values: $runtime-text-colors,
-        states: ('hover', 'focus')
-    )
-);
-
 // ============================================================================
 // BUILDS
 // ============================================================================
 @include build-classes($typography-properties-map, $responsive: true);
-@include build-classes($runtime-typography-properties-map, $responsive: true);
 @include build-composite-classes($text-classes-map, $responsive: true);