ultimate-jekyll-manager 1.6.8 → 1.6.9

package/CHANGELOG.md

@@ -14,6 +14,18 @@ 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
 

package/CLAUDE.md

@@ -158,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/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

@@ -38,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/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.8",
+  "version": "1.6.9",
   "description": "Ultimate Jekyll dependency manager",
   "main": "dist/index.js",
   "exports": {