ultimate-jekyll-manager 1.6.7 → 1.6.9

package/CHANGELOG.md

@@ -14,6 +14,25 @@ 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.6.9] - 2026-06-08
+
+### Added
+
+- **Bootstrap-first theming convention.** Added comprehensive guidance to `docs/themes.md` and the default consumer `CLAUDE.md` — themes must restyle Bootstrap classes, not create parallel design systems.
+- **Dev workflow documentation.** Added explicit instructions to `CLAUDE.md` and consumer defaults to check `logs/dev.log` instead of running `npm start`/`npm test` in consumer projects.
+
+### Fixed
+
+- **Signup metadata failure notification timeout.** Changed dev-only notification from permanent (`timeout: 0`) to 1 second (`timeout: 1000`) so it doesn't block the screen during development.
+
+---
+## [1.6.8] - 2026-06-07
+
+### Fixed
+
+- **Lazy loading animation flash.** Elements with `data-lazy="@class animation-*"` were briefly visible before the IntersectionObserver fired, causing a jarring flash (visible → disappear → fade-in). Added CSS rule to hide these elements from initial paint so they smoothly animate in.
+
 ---
 ## [1.6.5] - 2026-06-04
 

package/CLAUDE.md

@@ -43,6 +43,10 @@ The only things that ARE safe to run inside UJM itself:
 4. `npm run build` — production build (`UJ_BUILD_MODE=true`)
 5. `npm run deploy` — build + `npu sync --message='Deploy'`
 6. `npm test` (or `npx mgr test`) — runs framework + project test suites
+   - `npx mgr test pages/home` — run a specific test by path (relative to `test/`)
+   - `npx mgr test ujm:pages/home` — run only framework tests matching a path
+   - `npx mgr test project:custom-test` — run only consumer project tests matching a path
+   - Prefix with `TEST_EXTENDED_MODE=true` for tests that hit real external APIs
 
 ### For Framework Development (This Repository)
 
@@ -154,6 +158,10 @@ Same `{ layer, description, run(ctx) }` contract as EM/BXM. JSON-line reporter p
 
 Note: `-t` short alias belongs to `translation`. The `test` command uses `--test` flag + `test` positional only. See [docs/cli.md](docs/cli.md) (planned).
 
+## Development Workflow
+
+- **🚫 NEVER run `npm start` / `npm run build` / `npm test` in a consumer project** unless the user explicitly asks. The user runs the dev server — running it again kills theirs. Instead, **check `logs/dev.log`** after editing files to confirm the watcher recompiled successfully (`Reloading Browsers...` = success; `errored` = fix the error). If editing multiple files, check the log once after the last edit. A change that breaks the build is not a completed change.
+
 ## File Conventions
 
 - **CommonJS** in build-time / Node files (gulp tasks, commands, lib/). **ESM** in `src/index.js` (frontend Manager — webpack-bundled).

package/dist/assets/css/core/_lazy-loading.scss

@@ -12,6 +12,12 @@ img[data-lazy] {
   height: auto; // Maintain aspect ratio
 }
 
+// Hide elements with pending animation classes to prevent flash
+// (visible → disappear → fade-in) when IntersectionObserver fires
+[data-lazy*="animation-"] {
+  opacity: 0;
+}
+
 // Hide video/audio elements until loaded to prevent ugly native controls showing during shimmer
 [data-lazy-load-container].lazy-loading video,
 [data-lazy-load-container].lazy-loading audio {

package/dist/assets/js/core/auth.js

@@ -316,7 +316,7 @@ async function sendUserSignupMetadata(account) {
     /* @dev-only:start */
     webManager.utilities().showNotification(
       `[DEV] Failed to send signup metadata. Will retry on next page load (flags.signupProcessed is still false).`,
-      { type: 'warning', timeout: 0 }
+      { type: 'warning', timeout: 1000 }
     );
     /* @dev-only:end */
   }

package/dist/defaults/CLAUDE.md

@@ -28,6 +28,9 @@ npm start           # dev: clean → setup → bundle exec gulp serve (Jekyll +
 npm run build       # production build (UJ_BUILD_MODE=true): clean → setup → full gulp pipeline → _site/
 npm run deploy      # build → `npu sync --message='Deploy'` (publishes _site/)
 npx mgr test        # run framework + project test suites (build / page / boot layers)
+npx mgr test pages/home           # run a specific test by path (relative to test/)
+npx mgr test ujm:pages/home       # run only framework tests matching a path
+npx mgr test project:custom-test  # run only consumer project tests matching a path
 npx mgr audit       # HTML validation + spellcheck + optional Lighthouse
 npx mgr install dev  # use LOCAL ultimate-jekyll-manager source (to test framework edits)
 npx mgr install live # restore the published ultimate-jekyll-manager from npm
@@ -35,6 +38,26 @@ npx mgr install live # restore the published ultimate-jekyll-manager from npm
 
 > Editing the UJM framework source while working here? Run `npx mgr install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/ultimate-jekyll-manager`). Run `npx mgr install live` to switch back.
 
+## 🚨 BOOTSTRAP-FIRST — NEVER reinvent the wheel
+
+**UJM is built on Bootstrap 5.** Every page MUST use Bootstrap classes for layout, spacing, typography, buttons, cards, grid, flex, and all standard components. Custom CSS exists ONLY to override how Bootstrap classes LOOK (via theme SCSS), NOT to replace them with parallel classes.
+
+- **DO:** Use `.btn .btn-primary`, `.container`, `.row`, `.col-*`, `.d-flex`, `.gap-*`, `.py-5`, `.text-center`, `.card`, `.lead`, `.shadow`, `.rounded-*`, etc.
+- **DO NOT:** Create custom `.my-btn`, `.my-wrap`, `.my-section` classes when Bootstrap already has equivalents. Don't write `padding`, `display: flex`, `gap`, `margin`, `text-align`, `font-weight` in custom CSS when a Bootstrap utility does the same thing.
+- **Theme SCSS overrides appearance:** `.btn { border-radius: 50px; box-shadow: ... }` changes ALL buttons site-wide. You don't need `.lm-btn` — just restyle `.btn`.
+- **Custom CSS is for genuinely novel components only:** animated hero illustrations, grain overlays, marquee strips — things with no Bootstrap equivalent.
+
+See `node_modules/ultimate-jekyll-manager/docs/themes.md` for the full "Bootstrap-first" convention.
+
+## 🚨 Development workflow — MUST follow
+
+- **🚫 NEVER run `npm start`, `npm run build`, or `npm test`** unless the user explicitly asks. Assume the user is already running the dev server. Running these commands kills the user's process and wastes time.
+- **✅ ALWAYS check `logs/dev.log`** after editing source files (SCSS, JS, HTML, config) to confirm the build succeeded. The dev server's gulp watcher recompiles on file change — check the log for errors.
+  - Success: `Reloading Browsers...`
+  - Failure: `'sass' errored`, `'webpack' errored`, `'build-error'`, `'jekyll' errored`
+- If editing multiple files in a batch, check the log once after the last edit. Wait a few seconds for the watcher to recompile before reading the log.
+- **If the log shows an error, fix it immediately.** A change that breaks the build is not a completed change.
+
 ## Where things live
 
 - `src/_config.yml` — Jekyll config: brand, theme, meta, web_manager (Firebase). `Manager.getConfig('project')` reads this. **`brand.id` + `theme.id` are required.**

package/docs/test-framework.md

@@ -37,6 +37,26 @@ npx mgr test --reporter json   # machine-readable __UJM_TEST__ events
 
 `npm test` works too — added to consumer `package.json#scripts.test` on `npx mgr setup`.
 
+### Filtering tests
+
+Pass a path (relative to `test/`) as a positional argument to run specific tests:
+
+```bash
+# Run a single test file
+npx mgr test pages/home
+
+# Run only UJM framework tests
+npx mgr test ujm:pages/home
+
+# Run only consumer project tests
+npx mgr test project:custom-test
+
+# Combine with extended mode
+TEST_EXTENDED_MODE=true npx mgr test pages/boot-test
+```
+
+The filter matches against the test file path. `ujm:` and `project:` prefixes scope the filter to framework-only or project-only tests respectively. Without a prefix, both are searched.
+
 ## Layers
 
 | Layer | Runs in | Use for |

package/docs/themes.md

@@ -345,6 +345,56 @@ their own (frozen) text color. Nav/dropdown/footer links already win on specific
 
 ---
 
+## 🚨 BOOTSTRAP-FIRST — NEVER reinvent the wheel
+
+**This is the #1 theme authoring mistake.** A theme's job is to RESTYLE Bootstrap — not to build a parallel design system alongside it.
+
+### The rule
+
+Every HTML element must use **Bootstrap classes first**. Custom CSS exists ONLY to override how those Bootstrap classes look (colors, shadows, borders, radii, typography) via the theme's SCSS. You should NEVER:
+
+- Invent custom layout classes when Bootstrap grid/flex utilities exist (`.row`, `.col-*`, `.d-flex`, `.gap-*`, `.justify-content-*`, `.align-items-*`, `.text-center`, `.mx-auto`, etc.)
+- Create custom button classes (`.my-btn`, `.lm-btn`) when `.btn .btn-primary`, `.btn .btn-outline-dark`, etc. already exist — restyle `.btn` in theme SCSS instead
+- Create custom spacing/sizing classes when Bootstrap has `p-*`, `m-*`, `w-*`, `rounded-*`, `shadow-*`
+- Create custom text utilities when Bootstrap has `.text-muted`, `.lead`, `.display-*`, `.fw-*`, `.fs-*`
+- Create custom card/container classes when `.card`, `.card-body`, `.container`, `.lh-*` exist
+- Write `position`, `display`, `flex`, `gap`, `padding`, `margin`, `border-radius`, `text-align`, `font-weight`, `font-size` in custom CSS when a Bootstrap utility class does the same thing
+
+### What theme CSS IS for
+
+- Overriding Bootstrap component appearance: `.btn { border-radius: 50px; box-shadow: ... }` — changes how ALL buttons look
+- Setting design tokens: `$primary`, `$border-radius`, `$font-family-sans-serif` — passed to Bootstrap's `@forward`
+- CSS custom properties for the theme palette: `--lm-accent`, `--lm-ink`, etc.
+- Dark mode overrides via `[data-bs-theme="dark"]` variable remapping
+- Truly novel components with no Bootstrap equivalent (grain overlays, animated hero cards, marquee strips)
+- Mixins/utilities that compose Bootstrap patterns, not replace them
+
+### How to check yourself
+
+Before writing ANY custom CSS class, ask: "Does Bootstrap already have a class for this?" If yes, use it. If the Bootstrap class doesn't look right, override its appearance in theme SCSS — don't create a parallel class. The HTML should be 90%+ Bootstrap classes with custom classes only for genuinely novel UI patterns.
+
+### Anti-pattern example
+
+```html
+<!-- BAD: parallel design system -->
+<div class="lm-wrap">
+  <div class="lm-section">
+    <a class="lm-btn lm-btn-primary">Click</a>
+  </div>
+</div>
+
+<!-- GOOD: Bootstrap classes, theme restyled -->
+<div class="container">
+  <section class="py-5">
+    <a class="btn btn-primary">Click</a>
+  </section>
+</div>
+```
+
+The GOOD version uses zero custom CSS for layout/buttons — the theme's `_buttons.scss` restyled `.btn` and `.btn-primary` to look however it wants. The page `main.scss` only adds styles for genuinely novel components.
+
+---
+
 ## Authoring conventions (both paths)
 
 1. **Every token is `!default`** so consumers can override without forking.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultimate-jekyll-manager",
-  "version": "1.6.7",
+  "version": "1.6.9",
   "description": "Ultimate Jekyll dependency manager",
   "main": "dist/index.js",
   "exports": {