ultimate-jekyll-manager 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -14,6 +14,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+---
+## [1.5.0] - 2026-06-02
+
+### Added
+
+- **Neobrutalism theme** — a complete second shipped theme (alongside `classy`), not a recolor: hard ink borders, offset "press" shadows, chunky display type, flat color-blocks, square controls. Custom homepage + pricing layouts. It restyles **standard Bootstrap classes** (`.btn`, `.card`, `.text-bg-*`) and a **universal semantic layout vocabulary** (`.section-hero`, `.showcase-row`, `.stat-block`, `.pricing-plan`, `.cta-panel`, …) — **no theme-prefixed classes** — so the same markup is swappable across themes (change `theme.id`, done). [src/assets/themes/neobrutalism/](src/assets/themes/neobrutalism/)
+- **Theme system: three-layer page-asset cascade (Global → Theme → Consumer) for BOTH CSS and JS.**
+  - Theme page CSS: `themes/<id>/pages/<path>/index.scss` compiles to a theme-suffixed bundle (`index.<themeId>.bundle.css`) via [src/gulp/tasks/sass.js](src/gulp/tasks/sass.js), linked by [head.html](src/defaults/dist/_includes/core/head.html) with `{% iffile %}`. Missing = nothing loads (component styles handle it), no fallback needed.
+  - Theme page JS: `__theme__/pages/<path>/index.js` loaded as the `#theme` layer in [src/index.js](src/index.js), executed `main → theme → project` (a `webpackInclude: /\.js$/` guard stops `.scss` from being pulled into the JS import context).
+  - Per-page HTML layout overrides under `_layouts/themes/<id>/` reuse classy's `page.resolved.*` frontmatter data contract and fall back to classy when a layout is absent.
+- **Theme-authoring template** at [src/assets/themes/_template/](src/assets/themes/_template/) + a full **[docs/themes.md](docs/themes.md)** reference for building a theme inside UJM or in a consumer project (selection/resolution, classy fallback, page CSS/JS layers, the no-prefix vocabulary, adaptive-button + interactive-accent gotchas).
+- **Single interactive-accent token** (`--nb-accent-interactive` = `var(--bs-primary)`) drives all hover/active states (blue), distinct from the yellow signature accent reserved for static blocks. Adaptive buttons (`btn-adaptive`/`-inverse`) get explicit theme overrides so they render solid and press like every other button.
+- **Asset-layer test harness** — `UJ_TEST_LAYERS` flag + [manage-test-layers.js](src/gulp/tasks/utils/manage-test-layers.js) generate real consumer-side test files; the `/test/libraries/layers` page renders the Global/Theme/Consumer cascade as red/green dots to prove all three layers load in order. `npm run start:test-layers` enables it.
+
 ---
 ## [1.4.3] - 2026-05-28
 

package/CLAUDE-ATTRIBUTION.md

@@ -0,0 +1,215 @@
+# Attribution Tracking System — Design & Implementation Plan
+
+> Working design doc for the unified attribution system. Captures UTM/ITM tags, affiliate codes, and ad click IDs with a per-type "first-touch with 30-day refresh" model, plus auto-sync to the server when authenticated.
+
+## Goals
+
+An all-in-one system to track how users arrive at the site so we can:
+1. Do UTM tracking (external marketing attribution)
+2. Do ITM tracking (internal mechanisms — exit popups, extension prompts, etc.)
+3. Capture ad click IDs for server-side conversion events (GA, Meta CAPI, TikTok Events API)
+4. Properly attribute recurring purchases that happen offline (subscription renewals)
+
+---
+
+## Design Decisions (settled)
+
+- **Attribution Model**: First-touch with 30-day refresh, **per-type basis**
+  - Each category (UTM, ITM, affiliate, adClicks) has independent freshness
+  - If no data exists for a type → save it
+  - If data exists AND is < 30 days old → preserve (first-touch protection)
+  - If data exists AND is >= 30 days old → overwrite (new journey)
+  - Categories are independent: can overwrite stale UTM while keeping fresh affiliate
+- **Freshness TTL**: 30 days globally for all types
+- **Ad click IDs**: lumped into a single `adClicks` object (user only arrives from one ad at a time; they share one timestamp)
+- **Server Sync**: on attribution change (if signed in) + signup + checkout
+  - `_meta.needsSync` flag for deferred sync when user later signs in (mirrors `notifications.syncSubscription()` pattern in web-manager)
+- **Storage**: User doc (rolling latest) + Subscription doc (frozen snapshot at purchase)
+- **`getFresh()` returns ALL fresh data** — server decides what's recent enough to attribute. Subscription gets a frozen snapshot used for ALL recurring conversions, even years later.
+- **No backwards compatibility** — replace the old shape cleanly, remove the ad-hoc 30-day check.
+
+---
+
+## Storage Structure
+
+```javascript
+// localStorage key: "attribution"
+{
+  utm: {
+    tags: { utm_source, utm_medium, utm_campaign, utm_term, utm_content },
+    timestamp: "ISO string",
+    url: "full landing URL",
+    page: "/path"
+  },
+  itm: {
+    tags: { itm_source, itm_medium, itm_campaign, itm_content },
+    timestamp: "ISO string",
+    url: "full URL",
+    page: "/path"
+  },
+  affiliate: {
+    code: "partner123",
+    timestamp: "ISO string",
+    url: "full URL",
+    page: "/path"
+  },
+  adClicks: {
+    // All ad click IDs lumped together (user only arrives from one ad at a time)
+    fbclid: "from URL param",
+    fbc:    "from _fbc cookie",
+    gclid:  "from URL param",
+    ttclid: "from URL param",
+    timestamp: "ISO string",
+    url: "full URL",
+    page: "/path"
+  },
+  _meta: {
+    needsSync: false,        // true if attribution changed while signed out
+    lastSynced: "ISO string" // last successful server sync
+  }
+}
+```
+
+---
+
+## Data Captured
+
+| Category | Source | Params |
+|---|---|---|
+| **UTM** | URL query | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
+| **ITM** | URL query (internal links, e.g. exit popup) | `itm_source`, `itm_medium`, `itm_campaign`, `itm_content` |
+| **Affiliate** | URL query | `aff` or `ref` |
+| **Ad Clicks** | URL query + cookie | `fbclid`, `fbc` (`_fbc` cookie), `gclid`, `ttclid` |
+
+ITM tags are emitted by internal mechanisms. Example: `exit-popup.js` already sets `itm_source=website&itm_medium=modal&itm_campaign=exit-popup&itm_content=<pathname>` on its CTA link. Those land as a query string on the next page and get captured like UTM.
+
+---
+
+## Files to Modify
+
+### 1. `src/assets/js/core/query-strings.js` — Core refactor
+
+Currently captures UTM + affiliate only (no freshness, no ITM, no ad clicks, no sync). Becomes the single owner of attribution capture + sync.
+
+Add:
+1. Constants: `ATTRIBUTION_KEY = 'attribution'`, `FRESHNESS_DAYS = 30`, `FRESHNESS_MS = 30 * 24 * 60 * 60 * 1000`
+2. `shouldPreserveAttribution(existingData)` — returns `true` if existing data is < 30 days old (preserve), `false` if missing or stale (allow overwrite)
+3. `processUTMParams()` / `processITMParams()` / `processAffiliateParams()` / `processAdClickParams()` — each:
+   - Reads its params, quits if none present
+   - Applies `shouldPreserveAttribution()` first-touch check
+   - Writes its category + metadata (timestamp/url/page)
+   - Returns `true` if it changed anything
+4. `getFbcCookie()` — parse `document.cookie` for `_fbc`
+5. `getAttribution()` — raw stored object (all, regardless of age)
+6. `getFreshAttribution()` — only categories < 30 days old, excludes `_meta`. This is the canonical thing sent to the server.
+7. `syncAttribution()`:
+   - If user signed in → POST fresh attribution to backend-manager, set `_meta.lastSynced`, clear `_meta.needsSync`
+   - If not signed in → set `_meta.needsSync = true`
+8. Auth-state listener for deferred sync: on sign-in, if `_meta.needsSync` is true, call `syncAttribution()`
+9. Public API on `webManager._ujLibrary.attribution`:
+   ```javascript
+   {
+     get:      () => getAttribution(),       // raw, all ages — debugging
+     getFresh: () => getFreshAttribution(),  // < 30 days — USE THIS
+     sync:     () => syncAttribution(),      // manual sync (usually automatic)
+     clear:    () => clearAttribution()      // wipe all attribution
+   }
+   ```
+
+`processQueryStrings()` orchestrates: run each processor, OR their return values; if anything changed, save to storage and call `syncAttribution()`.
+
+### 2. `src/assets/js/core/auth.js` — Use fresh attribution in signup
+
+`sendUserSignupMetadata(account)` currently reads raw `webManager.storage().get('attribution', {})` (line ~283). Change to:
+```javascript
+const attribution = webManager.uj().attribution.getFresh();
+```
+Everything else (the `flags.signupProcessed` SSOT gate, `/backend-manager/user/signup` endpoint, consent payload) stays as-is. Sync-on-change in query-strings.js is complementary — signup still sends attribution + context + consent in one shot.
+
+### 3. `src/assets/js/pages/payment/checkout/modules/api.js` — Use fresh attribution
+
+Line ~60 currently sends raw storage:
+```javascript
+attribution: webManager.storage().get('attribution', {}),
+```
+Change to:
+```javascript
+attribution: webManager.uj().attribution.getFresh(),
+```
+(The old ad-hoc 30-day UTM check from the former `session.js` is already gone — this just swaps raw → fresh so stale categories are dropped before the server snapshots them onto the subscription.)
+
+---
+
+## Sync Flow
+
+```
+User lands with ?utm_source=google (or itm_/fbclid/etc.)
+        │
+        ▼
+processQueryStrings()
+  - per-type freshness check (first-touch w/ 30-day refresh)
+  - update localStorage
+  - did anything change?
+        │ yes
+        ▼
+Is user signed in?
+  ├── YES → syncAttribution() now → set _meta.lastSynced
+  └── NO  → set _meta.needsSync = true
+        │
+        ▼ (later) user signs in
+auth-state listener
+  - _meta.needsSync? → syncAttribution() → clear flag
+```
+
+---
+
+## Server-Side Data Flow (informational — backend out of scope here)
+
+```
+USER DOC  /users/{uid}
+  attribution: { utm, itm, affiliate, adClicks }   ← rolling update on each sync
+
+        │ on purchase, snapshot →
+        ▼
+SUBSCRIPTION DOC  /users/{uid}/subscriptions/{subId}
+  attribution: { ... }   ← FROZEN at purchase time
+  → used for ALL recurring billing conversion events (even years later)
+```
+
+When a renewal fires months later, the server reads the subscription's frozen `attribution.adClicks.fbclid` (or gclid/ttclid) to send a server-side conversion event, attributing the recurring revenue to the original campaign.
+
+---
+
+## Public API Reference
+
+```javascript
+webManager.uj().attribution.get()       // raw stored attribution (all ages)
+webManager.uj().attribution.getFresh()  // only < 30 days — send this to server
+webManager.uj().attribution.sync()      // manual sync (normally automatic)
+webManager.uj().attribution.clear()     // wipe all attribution
+```
+
+---
+
+## Testing Checklist
+
+- [ ] UTM params captured on landing
+- [ ] ITM params captured (via exit-popup CTA link)
+- [ ] Affiliate code captured (`aff` / `ref`)
+- [ ] Ad click IDs captured (`fbclid`, `gclid`, `ttclid`)
+- [ ] `_fbc` cookie read correctly
+- [ ] First-touch protected per-type (revisit doesn't overwrite fresh data)
+- [ ] 30-day refresh per-type (stale category overwritten, fresh ones kept)
+- [ ] `getFresh()` excludes stale categories and `_meta`
+- [ ] Sync fires when signed in + attribution changes
+- [ ] `_meta.needsSync` set when signed out + attribution changes
+- [ ] Deferred sync fires on sign-in when `needsSync` is true
+- [ ] Signup (`auth.js`) sends `getFresh()` attribution
+- [ ] Checkout (`api.js`) sends `getFresh()` attribution
+
+---
+
+## Open Questions / Notes
+
+- Confirm the backend `user/signup` and checkout endpoints accept the new nested `adClicks` / `itm` shape (no backwards-compat shim — server should be updated in lockstep).
+- Decide the sync command/endpoint for the standalone `syncAttribution()` call (e.g. `user/attribution` vs reusing signup). Signup already carries attribution, so sync-on-change is mainly for users who change attribution *after* signup but *before* checkout.

package/CLAUDE.md

@@ -8,7 +8,7 @@ Ultimate Jekyll Manager (UJM) is a comprehensive framework for building modern J
 
 - One-line bootstrap per context (build / frontend / service-worker)
 - Multi-stage gulp pipeline (15 tasks: defaults / distribute / webpack / sass / imagemin / jekyll / jsonToHtml / preprocess / audit / translation / minifyHtml / serve / setup / developmentRebuild)
-- Default Jekyll layouts + themes (`classy` shipped; per-theme SCSS load paths)
+- Default Jekyll layouts + themes (`classy` + `neobrutalism` shipped; new themes inherit classy's layouts via the build-time fallback — see [docs/themes.md](docs/themes.md))
 - Frontend ES-module Manager with dynamic per-page module loading
 - Service worker with Firebase Messaging + cache management
 - A built-in **three-layer test framework** (build / page / boot)
@@ -48,7 +48,7 @@ The only things that ARE safe to run inside UJM itself:
 
 1. `npm install` — install UJM's own deps
 2. `npm start` (≡ `npm run prepare:watch`) — copies `src/` → `dist/` on file change
-3. Test in a consumer project: from inside the consumer, run `npx mgr install local` (swaps UJM to the local repo via the `install` CLI). Reverse with `npx mgr install prod`.
+3. Test in a consumer project: from inside the consumer, run `npx mgr install dev` to swap UJM to this local repo — required whenever you edit the framework source and want the consumer to pick up the changes (the consumer otherwise keeps its installed `node_modules/ultimate-jekyll-manager`). Reverse with `npx mgr install live`.
 4. `npm test` — runs UJM's own 60 test suites
 
 ## Architecture
@@ -63,7 +63,7 @@ UJM exposes three Manager entry points:
 | Frontend (browser ES module) | `import Manager from 'ultimate-jekyll-manager'` | `new Manager().initialize()` → wires webManager + loads page module |
 | Service worker | `importScripts('/build.js')` then construct `Manager` | Manages cache + Firebase Messaging |
 
-All three Managers mix in shared helpers via `attachTo(Manager)` from [src/utils/mode-helpers.js](src/utils/mode-helpers.js): `isDevelopment()`, `isProduction()`, `isTesting()`, `getVersion()`. See [docs/cross-context-helpers.md](docs/cross-context-helpers.md).
+All three Managers mix in shared helpers via `attachTo(Manager)` from [src/utils/mode-helpers.js](src/utils/mode-helpers.js): `isDevelopment()`, `isProduction()`, `isTesting()`, `getVersion()`. `getEnvironment()` returns `'development' | 'testing' | 'production'` (mutually exclusive — testing wins over dev); gate side effects on the INTENTIONAL check (`isProduction()` for prod-only, `isDevelopment() || isTesting()` for local-or-test) — never `!isDevelopment()`. See [docs/environment-detection.md](docs/environment-detection.md).
 
 ### Gulp pipeline
 
@@ -100,8 +100,8 @@ ES module class. Constructor stores `this.webManager`. `initialize()`:
 
 1. Calls `webManager.initialize(window.Configuration)`
 2. Reads `document.documentElement.dataset.pagePath` + `.assetPath`
-3. Loads (in parallel) `__main_assets__/js/ultimate-jekyll-manager.js` + page-specific modules from both `__main_assets__/js/pages/<path>/index.js` (UJM defaults) AND `__project_assets__/js/pages/<path>/index.js` (consumer overrides)
-4. Sequentially executes loaded modules (stops on first error)
+3. Loads (in parallel) `__main_assets__/js/ultimate-jekyll-manager.js` + page-specific modules from three layers: `__main_assets__/js/pages/<path>/index.js` (UJM default), `__theme__/pages/<path>/index.js` (active theme), and `__project_assets__/js/pages/<path>/index.js` (consumer). Missing at any layer is a no-op. See [docs/themes.md](docs/themes.md#5-page-specific-js-theme-aware-additive--mirrors-page-css).
+4. Sequentially executes loaded modules in order **main → theme → project** (stops on first error)
 
 Webpack aliases:
 - `__main_assets__` → UJM's `dist/assets/`
@@ -185,7 +185,7 @@ Deep references live in `docs/`. Treat docs as a first-class deliverable. **When
 
 - [docs/test-framework.md](docs/test-framework.md) — three-layer test harness reference (build / page / boot)
 - [docs/test-boot-layer.md](docs/test-boot-layer.md) — boot layer deep-dive (_site/ discovery, HTTP server, fixture vs consumer)
-- [docs/cross-context-helpers.md](docs/cross-context-helpers.md) — `isTesting`/`isDevelopment`/`isProduction`/`getVersion`
+- [docs/environment-detection.md](docs/environment-detection.md) — `isTesting`/`isDevelopment`/`isProduction`/`getVersion`
 - [docs/jekyll-plugin.md](docs/jekyll-plugin.md) — UJ Powertools gem: filters, tags, page variables (`page.resolved`, `uj_icon`, `uj_hash`, `iftruthy`, etc.)
 - [docs/audit.md](docs/audit.md) — workflow for fixing issues raised by `gulp/tasks/audit.js`
 
@@ -197,6 +197,7 @@ Deep references live in `docs/`. Treat docs as a first-class deliverable. **When
 
 ### Pages, layouts, content
 
+- [docs/themes.md](docs/themes.md) — theme system: selection + resolution (SCSS loadPaths, `__theme__`, classy layout fallback), shared vs per-theme layers, authoring a theme inside UJM OR in a consumer project, live validation
 - [docs/layouts-and-pages.md](docs/layouts-and-pages.md) — page types, layout chain, `asset_path` frontmatter
 - [docs/images.md](docs/images.md) — `@post/` shortcut for blog post images, BEM admin/post image handling, imagemin pipeline + source-size constraints + `UJ_IMAGEMIN_REWRITE_SOURCES` cleanup flag
 - [docs/icons.md](docs/icons.md) — Font Awesome conventions, `{% uj_icon %}` vs prerendered icons in JS, size reference

package/README.md

@@ -28,6 +28,7 @@
 * **SEO Optimized**: Ultimate Jekyll is fully SEO optimized.
 * **Blazingly Fast**: Ultimate Jekyll is blazingly fast.
 * **NPM & Gulp**: Ultimate Jekyll is fueled by an intuitive incorporation of npm and gulp.
+* **Themes**: Pick a shipped theme with `theme.id` (`classy` or `neobrutalism`), or author your own. New themes inherit all default page layouts automatically and only restyle/override what differs. See [docs/themes.md](docs/themes.md).
 * **Built-in test framework**: three layers (`build` / `page` / `boot`) — plain Node, headless Chromium tab, headless Chromium against real `_site/` with SW registration verification.
 
 ## 🚀 Getting started

package/dist/assets/css/pages/test/libraries/layers/index.scss

@@ -0,0 +1,28 @@
+/**
+ * /test — Global (framework default) page CSS — the first layer.
+ * Owns the base dot styling (every dot starts RED) and turns the
+ * "css-global" dot green to prove this layer loaded.
+ */
+
+// Base: every layer dot is red until its layer turns it green.
+.layer-row {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  font-size: 1.05rem;
+  padding: 0.35rem 0;
+}
+
+.layer-dot {
+  display: inline-block;
+  width: 1.1rem;
+  height: 1.1rem;
+  border-radius: 50%;
+  background: #e5484d; // red = layer not loaded
+  flex-shrink: 0;
+}
+
+// This layer loaded → its own dot goes green.
+.layer-dot[data-layer="css-global"] {
+  background: #30a46c; // green
+}

package/dist/assets/js/modules/redirect.js

@@ -54,9 +54,10 @@ const performRedirect = () => {
     }
   }
 
-  // Determine redirect delay
-  const isDevelopment = config.environment === 'development';
-  const timeout = isDevelopment ? 3000 : 1;
+  // Determine redirect delay — slow in any non-production environment (development OR
+  // testing) so the redirect is observable; near-instant in production.
+  const isNonProduction = config.environment !== 'production';
+  const timeout = isNonProduction ? 3000 : 1;
 
   // Build redirect URL
   let redirectUrl;
@@ -111,7 +112,7 @@ const performRedirect = () => {
   console.groupEnd();
 
   // Show user-friendly message in development
-  if (isDevelopment) {
+  if (config.environment === 'development') {
     console.log(`[Redirect] Delaying redirect by ${timeout}ms for development mode`);
   }
 

package/dist/assets/js/pages/download/index.js

@@ -38,7 +38,7 @@ const config = {
   selectors: {
     platformButtons: '.platform-btn',
     platformDownloads: '[data-platform]',
-    downloadButtons: '.tab-pane[data-platform] .btn-primary:not([type="submit"])',
+    downloadButtons: '.tab-pane[data-platform] [data-download]',
   },
 };
 

package/dist/assets/js/pages/feedback/index.js

@@ -17,6 +17,12 @@ export default () => {
     setupForm();
     setupRatingButtons();
 
+    // TEMP: expose for manual modal testing — remove before commit
+    window.__testReviewModal = () => showReviewModal('https://www.trustpilot.com/review/example.com', {
+      positive: 'This product is amazing and saved me hours!',
+      comments: 'Highly recommend to anyone.',
+    });
+
     // Resolve after initialization
     return resolve();
   });
@@ -120,7 +126,7 @@ function showReviewModal(reviewURL, data) {
   // Extract site name for display
   try {
     const siteName = new URL(fullURL).hostname.replace('www.', '');
-    $link.innerHTML = `${getPrerenderedIcon('arrow-up-right-from-square', 'me-2')} Write a Review on ${webManager.utilities().escapeHTML(siteName)}`;
+    $link.innerHTML = `${getPrerenderedIcon('arrow-up-right-from-square', 'me-2')} Post your review on ${webManager.utilities().escapeHTML(siteName)}`;
   } catch (e) {
     // Use default text
   }

package/dist/assets/js/pages/test/libraries/layers/index.js

@@ -0,0 +1,11 @@
+/**
+ * /test — Global (framework default) page JS — the first layer.
+ * Turns the "js-global" dot green to prove this layer loaded + ran.
+ */
+export default ({ manager, options }) => {
+  const dot = document.querySelector('.layer-dot[data-layer="js-global"]');
+  if (dot) {
+    dot.style.background = '#30a46c'; // green
+  }
+  console.log('[test-layer] global JS ran → js-global dot green');
+};

package/dist/assets/themes/_template/README.md

@@ -0,0 +1,50 @@
+# Theme Template
+
+A minimal, copy-paste starting point for a **brand-new UJM theme** — whether
+you're adding one inside UJM (`src/assets/themes/<id>/`) or creating one in your
+own consumer project (`<project>/src/assets/themes/<id>/`).
+
+> Full guide: [`docs/themes.md`](../../../../docs/themes.md).
+
+## Create a theme from this template
+
+1. **Copy this folder** to your theme id (the `_` prefix excludes this template
+   from selection, so rename it):
+   - Inside UJM: `src/assets/themes/my-theme/`
+   - In a consumer: `<project>/src/assets/themes/my-theme/`
+2. **Select it** in your consumer's `src/_config.yml`:
+   ```yaml
+   theme:
+     id: "my-theme"
+   ```
+3. **Customize** `_config.scss` (tokens), `css/` (styles), and `_theme.js`
+   (behaviors). Restyle Bootstrap's own classes (`.btn`, `.card`, `.navbar`,
+   `.form-control`) so the shared layouts pick up your look with no HTML edits.
+4. **Layouts/includes are inherited automatically.** You do NOT need to copy the
+   ~40 page layouts — UJM's build copies any missing layout/include from the
+   `classy` theme and rewrites the paths to your theme id. Override a layout only
+   when its *markup* (not just CSS) must differ — create
+   `src/defaults/dist/_layouts/themes/my-theme/<path>` (in UJM) or
+   `src/_layouts/themes/my-theme/<path>` (in a consumer) for just that file.
+   A common one: override `frontend/core/base.html` to load your theme's fonts.
+
+## What's here
+
+```
+_template/
+├── _config.scss              ← design tokens (!default) + Bootstrap forward
+├── _theme.scss               ← SCSS entry (config → root → styles → bootstrap overrides)
+├── _theme.js                 ← JS entry (Bootstrap UMD + DOM-ready behaviors)
+├── README.md                 ← this file
+└── css/
+    ├── base/_root.scss        ← SCSS → CSS-variable bridge (light/dark)
+    └── components/_components.scss  ← restyle Bootstrap classes here
+```
+
+## Principles (see docs/themes.md for the full list)
+
+- **Tokens are `!default`** so consumers can override without forking your theme.
+- **Bridge to CSS variables** in `_root.scss` for free dark-mode switching.
+- **Don't duplicate the shared layers** — `core/` CSS (animations, alerts, lazy
+  loading) and `bootstrap/overrides` are injected for every theme already.
+- **Namespace your own components** (`.mytheme-*`) to avoid collisions.

package/dist/assets/themes/_template/_config.scss

@@ -0,0 +1,60 @@
+// <Theme Name> Configuration
+// ALL customizable variables live here with !default so consuming projects can
+// override any of them BEFORE the theme is imported. Keep this file as the
+// single source of truth for your theme's design tokens.
+
+// ============================================
+// Bootstrap Color Overrides
+// ============================================
+$primary:   #3B82F6 !default;
+$secondary: #6B7280 !default;
+$success:   #10B981 !default;
+$info:      #06B6D4 !default;
+$warning:   #F59E0B !default;
+$danger:    #EF4444 !default;
+$light:     #F9FAFB !default;
+$dark:      #111827 !default;
+
+// ============================================
+// Surfaces (light + dark mode)
+// ============================================
+// Define your page/card backgrounds for each mode. _root.scss bridges these
+// into CSS variables so dark-mode switching needs no recompilation.
+$theme-bg-light:         #FFFFFF !default;
+$theme-surface-light:    #F3F4F6 !default;
+$theme-bg-dark:          #0B0B0F !default;
+$theme-surface-dark:     #16161C !default;
+
+// ============================================
+// Typography
+// ============================================
+$font-family-sans-serif: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif !default;
+$headings-font-weight: 700 !default;
+
+// ============================================
+// Component sizing
+// ============================================
+// Match Classy's avatar map so the shared layouts/includes render correctly.
+$avatar-sizes: (
+  null: 3rem, 2xs: 0.5rem, xs: 1.5rem, sm: 2rem, md: 2.5rem,
+  lg: 3.5rem, xl: 5rem, 2xl: 7.5rem, 3xl: 10rem, 4xl: 12.5rem, 5xl: 15rem
+) !default;
+
+// ============================================
+// Forward Bootstrap with our configuration
+// ============================================
+// Pass your overridden tokens into Bootstrap so .btn/.card/.form-control etc.
+// are generated with your colors. Add/remove forwards as your theme needs.
+@forward '../bootstrap/scss/bootstrap.scss' with (
+  $primary: $primary,
+  $secondary: $secondary,
+  $success: $success,
+  $info: $info,
+  $warning: $warning,
+  $danger: $danger,
+  $light: $light,
+  $dark: $dark,
+  $font-family-sans-serif: $font-family-sans-serif,
+  $headings-font-weight: $headings-font-weight,
+  $enable-negative-margins: true
+);

package/dist/assets/themes/_template/_theme.js

@@ -1,5 +1,14 @@
-// Import the theme entry point
-import './js/__INDEX__.js';
+// <Theme Name> — JS entry point
+// Loaded at runtime via webpack's __theme__ alias. Exposes Bootstrap globally
+// and runs your theme behaviors once the DOM is ready.
+import bootstrap from '__main_assets__/themes/bootstrap/js/index.umd.js';
+import { ready as domReady } from 'web-manager/modules/dom.js';
 
-// Add any custom code here
-// ...
+// Make Bootstrap available globally (used by UJM utilities + components)
+window.bootstrap = bootstrap;
+
+// Initialize theme behaviors when the DOM is ready
+domReady().then(() => {
+  // Add your theme's initializers here, e.g.:
+  // import('./js/navbar-scroll.js').then(m => m.default());
+});

package/dist/assets/themes/_template/_theme.scss

@@ -1,5 +1,17 @@
-// Import the theme entry point
-@use './scss/__INDEX__.scss' as *;
+// <Theme Name> — SCSS entry point
+// Import order matters: config (loads Bootstrap with your tokens) → root vars →
+// your styles → universal Bootstrap overrides (shared across all UJ themes).
 
-// Add any custom code here
-// ...
+// Forward config so consuming projects can override your !default tokens
+@forward 'config';
+@use 'config' as *;
+
+// CSS custom properties (light/dark bridge)
+@import 'css/base/root';
+
+// Your theme's styles (add base/layout/component partials as you grow)
+@import 'css/components/components';
+
+// Universal Bootstrap overrides shared by every UJ theme
+// (avatars, color-shades, soft-colors, spacing, etc.). Must come AFTER Bootstrap.
+@import '../bootstrap/overrides';

package/dist/assets/themes/_template/css/base/_root.scss

@@ -0,0 +1,19 @@
+// <Theme Name> — CSS Custom Properties
+// Bridges SCSS config into runtime CSS variables. Components should read these
+// var(--*) tokens (never the raw SCSS values) so dark mode is one override block.
+
+:root,
+[data-bs-theme="light"] {
+  --bs-body-bg: #{$theme-bg-light};
+  --bs-body-bg-rgb: #{red($theme-bg-light)}, #{green($theme-bg-light)}, #{blue($theme-bg-light)};
+  --bs-secondary-bg: #{$theme-surface-light};
+  // Add your own tokens, e.g.:
+  // --theme-card-bg: #{$theme-surface-light};
+}
+
+[data-bs-theme="dark"] {
+  --bs-body-bg: #{$theme-bg-dark};
+  --bs-body-bg-rgb: #{red($theme-bg-dark)}, #{green($theme-bg-dark)}, #{blue($theme-bg-dark)};
+  --bs-secondary-bg: #{$theme-surface-dark};
+  // --theme-card-bg: #{$theme-surface-dark};
+}

package/dist/assets/themes/_template/css/components/_components.scss

@@ -0,0 +1,23 @@
+// <Theme Name> — Components
+// Restyle Bootstrap's own classes here so all inherited markup (nav, hero,
+// cards, forms, buttons) picks up your look with NO HTML changes. Add files
+// like _buttons.scss / _cards.scss as your theme grows and @import them in
+// _theme.scss. This starter keeps everything in one file to stay minimal.
+
+// Example: give buttons your theme's personality
+.btn {
+  font-weight: 600;
+  // ...your button styling...
+}
+
+// Example: cards
+.card {
+  background: var(--bs-secondary-bg);
+  // ...your card styling...
+}
+
+// Example: a theme-namespaced helper for your own page layouts
+.theme-box {
+  background: var(--bs-secondary-bg);
+  padding: 1.5rem;
+}

package/dist/assets/themes/classy/README.md

@@ -2,21 +2,28 @@
 
 ## How to Customize in Your Consuming Project
 
-The Classy theme is designed to be fully customizable. All theme variables use `!default` which means you can override them BEFORE importing the theme.
+The Classy theme is designed to be fully customizable. All theme variables use `!default` which means you can override them BEFORE the theme is imported.
+
+> **How the import actually resolves:** Your project's `src/assets/css/main.scss`
+> does `@use 'ultimate-jekyll-manager' as *;`. That entry point `@forward`s the
+> theme, and UJM's SASS `loadPaths` resolve `theme` to whichever
+> `src/assets/themes/<theme.id>/_theme.scss` wins — your project's copy first,
+> then UJM's packaged copy. You never import the theme file by path directly.
+> See [`docs/themes.md`](../../../../docs/themes.md) for the full mechanism.
 
 ### Example: Customizing Colors in Your Project
 
 In your consuming project's `src/assets/css/main.scss`:
 
 ```scss
-// 1. Override Classy theme variables BEFORE importing the theme
-$primary: #FF0000;  // Change primary color to red
+// 1. Override Classy theme variables FIRST (they are !default, so yours win)
+$primary: #FF0000;          // Change primary color to red
 $classy-bg-light: #F5F5F5;  // Change light mode background
-$classy-bg-dark: #1A1A1A;  // Change dark mode background
+$classy-bg-dark: #1A1A1A;   // Change dark mode background
 $font-family-sans-serif: 'Inter', sans-serif;  // Change font
 
-// 2. Now import the Classy theme - it will use YOUR values
-@import '~ultimate-jekyll-manager/src/assets/themes/classy/theme';
+// 2. Import the framework — it loads the theme using YOUR values above
+@use 'ultimate-jekyll-manager' as *;
 
 // 3. Add your custom styles below
 .my-custom-class {
@@ -24,6 +31,11 @@ $font-family-sans-serif: 'Inter', sans-serif;  // Change font
 }
 ```
 
+To customize beyond variables — change actual component styles or markup —
+**shadow the theme**: create `src/assets/themes/classy/` in your project. UJM's
+loadPaths resolve your copy before the packaged one. (To build a wholly new
+look, author a new theme instead — see `docs/themes.md`.)
+
 ## Available Customizable Variables
 
 See `_config.scss` for the full list of variables you can override: