ultimate-jekyll-manager 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -14,6 +14,21 @@ 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.2.2] - 2026-05-18
+
+### Added
+
+- **`docs/<topic>.md` deep references** — 17 new files referenced by the v1.2.0 CLAUDE.md reorg that hadn't been committed yet: `ads.md`, `analytics.md`, `appearance.md`, `assets.md`, `audit.md`, `css.md`, `icons.md`, `images.md`, `javascript-libraries.md`, `jekyll-plugin.md`, `layouts-and-pages.md`, `lazy-loading.md`, `local-development.md`, `page-loading.md`, `project-structure.md`, `seo.md`, `xss-prevention.md`. Restores parity with the cross-links already shipped in [CLAUDE.md](CLAUDE.md).
+- **`src/defaults/docs/README.md`, `src/defaults/test/README.md`, `src/defaults/CHANGELOG.md`** — consumer-project scaffolding files distributed via the `defaults` gulp task.
+
+---
+## [1.2.1] - 2026-05-18
+
+### Changed
+
+- **Default `/extension` page** — removed the redundant downloads-section heading block ("Install" badge + "Available on every browser" headline + "Choose your browser below to get started" subheadline) that duplicated the role of the page hero. Browser-selector pills now sit directly under the hero. Affects `src/defaults/dist/_layouts/themes/classy/frontend/pages/extension/index.html` and drops the now-unused `downloads.superheadline` / `downloads.headline` / `downloads.headline_accent` / `downloads.subheadline` frontmatter keys.
+
 ---
 ## [1.2.0] - 2026-05-12
 

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Ultimate Jekyll Manager (UJM)
 
-> **Note for contributors and Claude:** This file is the architectural overview — identity, top-level conventions, and a map to deep references. The **meat** (per-subsystem APIs, page customization recipes, theming, behavior tables, defaults lists) lives in `docs/<topic>.md`. When extending or adding content, write it in the matching `docs/*.md` file and cross-link from here — do NOT inline it. If a topic doesn't have a doc yet, create one. Goal: keep this file under 300 lines. Long-form content that hasn't been migrated yet lives in `docs/_legacy-claude-md.md` — a holding pen for material to be split into proper `docs/<topic>.md` files over time.
+> **Note for contributors and Claude:** This file is the architectural overview — identity, top-level conventions, and a map to deep references. The **meat** (per-subsystem APIs, page customization recipes, theming, behavior tables, defaults lists) lives in `docs/<topic>.md`. When extending or adding content, write it in the matching `docs/*.md` file and cross-link from here — do NOT inline it. If a topic doesn't have a doc yet, create one. Goal: keep this file under 250 lines.
 
 ## Identity
 
@@ -20,6 +20,19 @@ The only things that ARE safe to run inside UJM itself:
 - `npm run prepare` — copies `src/` → `dist/` via prepare-package
 - `npm test` (aka `npx mgr test`) — runs UJM's own three-layer test suite
 
+## Recommended skills
+
+- **`UJM:patterns`** — SSOT for Ultimate Jekyll Manager architecture, gulp pipeline, frontend Manager, and theme conventions. Auto-loads on UJM-specific keywords (`_config.yml`, `theme.id`, `uj_icon`, `page.resolved`, `npx mgr setup`, etc.) and when touching files in `src/_layouts/`, `src/_includes/`, `src/pages/`, `src/assets/`, `config/ultimate-jekyll-manager.json`.
+- **`js:patterns`** — JavaScript/Node.js conventions: file structure, JSDoc, defensive coding (`?.` usage), template literals, `package.json` conventions. Auto-loads when creating new `.js` files or touching JS module structure.
+
+## 🚨 READ WEB-MANAGER TOO
+
+**UJM ships `web-manager` as a runtime singleton on every page** — it powers auth, Firebase, reactive `data-wm-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.). Any task that touches auth flows, Firestore reads/writes, subscription resolution, push notifications, or DOM bindings means you are working with web-manager as much as with UJM.
+
+**Required reading:**
+- **`node_modules/web-manager/CLAUDE.md`** — top-level overview + index
+- **`node_modules/web-manager/docs/`** — module deep references (Auth, Bindings, Firestore, Notifications, etc.)
+
 ## Quick Start
 
 ### For Consuming Projects
@@ -35,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: `npm install --save-dev /Users/ian/.../ultimate-jekyll-manager`
+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`.
 4. `npm test` — runs UJM's own 60 test suites
 
 ## Architecture
@@ -166,30 +179,44 @@ Don't ship behavioral changes with stale docs. Validate first, then document —
 
 ## Documentation
 
-Deep references live in `docs/`. Treat docs as a first-class deliverable.
+Deep references live in `docs/`. Treat docs as a first-class deliverable. **Whenever you make a behavioral change, update both this overview AND the relevant `docs/*.md` deep reference.**
+
+### Framework reference
 
 - [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/_legacy-claude-md.md](docs/_legacy-claude-md.md) — holding pen for content not yet split into proper subsystem docs. Anything still in here should be migrated to the appropriate `docs/<topic>.md` when touched.
-
-Planned/expected (create as needed, sourcing from `_legacy-claude-md.md`):
-- `docs/build-system.md` — gulp pipeline, task graph, env-var matrix
-- `docs/cli.md` — CLI command surface, env-var conventions
-- `docs/templating.md` — `{ }` vs `[ ]` brackets, variable resolution
-- `docs/defaults.md` — FILE_MAP routing, merge strategies, theme fallback
-- `docs/webpack.md` — entry points, aliases, dev-block stripping
-- `docs/sass.md` — page-specific bundles, purgecss safelist, theme load paths
-- `docs/jekyll.md` — config merge chain, build.json, hooks
-- `docs/audit.md` — HTML validation, spellcheck, Lighthouse
-- `docs/translation.md` — AI translation pipeline, cache, ignored pages
-- `docs/imagemin.md` — responsive variants, GitHub cache
-- `docs/service-worker.md` — SW lifecycle, cache composition, Firebase messaging
-- `docs/managers.md` — frontend Manager class, dynamic page module loading
-- `docs/config-schema.md` — `_config.yml` fields, `ultimate-jekyll-manager.json` fields
-- `docs/setup.md` — what `npx mgr setup` does (7+ phases)
-- `docs/themes.md` — classy theme structure, custom themes, fallback
-- `docs/components.md` — account dropdown, nav, footer JSON-driven sections
-- `docs/page-customization.md` — frontmatter-driven page customization without HTML
+- [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`
+
+### Project & dev environment
+
+- [docs/project-structure.md](docs/project-structure.md) — UJM repo layout and consuming-project layout
+- [docs/local-development.md](docs/local-development.md) — browsersync URL, Firebase emulator connect, PurgeCSS safelist
+- [docs/assets.md](docs/assets.md) — UJM vs consumer file layout, section config (nav/footer/account), frontmatter-driven page customization, webpack aliases, page module pattern
+
+### Pages, layouts, content
+
+- [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
+- [docs/icons.md](docs/icons.md) — Font Awesome conventions, `{% uj_icon %}` vs prerendered icons in JS, size reference
+- [docs/seo.md](docs/seo.md) — Alternatives collection (competitor comparison pages) + Schema/JSON-LD (`SoftwareApplication`, `FAQPage`)
+
+### Frontend behavior
+
+- [docs/css.md](docs/css.md) — section padding rule, theme-adaptive classes, cards in colored sections, `<html>` data attributes
+- [docs/appearance.md](docs/appearance.md) — dark/light/system mode switching: JS API, HTML attributes
+- [docs/page-loading.md](docs/page-loading.md) — page-loading protection, `.btn-action`, layered form-protection strategy
+- [docs/lazy-loading.md](docs/lazy-loading.md) — `data-lazy="@type value"` syntax and supported types
+- [docs/ads.md](docs/ads.md) — Vert units: AdSense include + Promo Server fallback, size presets
+
+### JS libraries & security
+
+- [docs/javascript-libraries.md](docs/javascript-libraries.md) — WebManager singleton + UJM libs at `src/assets/js/libs/` (prerendered icons, authorizedFetch, usage bindings, payment-config, FormManager)
+- [docs/xss-prevention.md](docs/xss-prevention.md) — zero-trust DOM injection rules, `escapeHTML`, postMessage origin checks, redirect validation
+
+### Analytics
+
+- [docs/analytics.md](docs/analytics.md) — ITM tracking, gtag/fbq/ttq guidelines, TikTok-specific rules
 
 `TODO.md` + `TODO-*.md` files at the repo root track pass-by-pass progress and decisions.

package/dist/defaults/CHANGELOG.md

@@ -0,0 +1,15 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## Changelog Categories
+
+- `BREAKING` for breaking changes.
+- `Added` for new features.
+- `Changed` for changes in existing functionality.
+- `Deprecated` for soon-to-be removed features.
+- `Removed` for now removed features.
+- `Fixed` for any bug fixes.
+- `Security` in case of vulnerabilities.

package/dist/defaults/CLAUDE.md

@@ -1,15 +1,25 @@
 # ========== Default Values ==========
 # Ultimate Jekyll Manager (UJM) — consumer project
 
-> **Auto-managed file.** Everything between `# ========== Default Values ==========` and `# ========== Custom Values ==========` is owned by `ultimate-jekyll-manager` and rewritten on every `npx mgr setup`. Put your own project-specific notes BELOW the `Custom Values` marker — that section is preserved verbatim across setups.
-
 ## Framework
 
 This project consumes **Ultimate Jekyll Manager** (UJM) — a comprehensive framework for building modern Jekyll-powered static sites. UJM provides one-line bootstrap per context (build / frontend / service-worker), a multi-stage gulp pipeline (defaults / distribute / webpack / sass / imagemin / jekyll / audit / translation / minifyHtml / serve), default Jekyll layouts + themes, a frontend ES-module Manager with dynamic per-page module loading, a service worker with Firebase Messaging + cache management, and a built-in three-layer test framework.
 
-**Framework's own docs** (read these for deep-dives; both paths point to the same files, the absolute path works regardless of working directory):
-- Top-level overview: `/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-manager/CLAUDE.md` (or `node_modules/ultimate-jekyll-manager/CLAUDE.md`)
-- Subsystem references: `/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-manager/docs/` (or `node_modules/ultimate-jekyll-manager/docs/`)
+## 🚨 READ THE FRAMEWORK DOCS FIRST
+
+**Before doing ANY work on this codebase, Claude MUST read the framework documentation — that is where the architecture, conventions, APIs, and gotchas live. Skipping these will result in solutions that conflict with framework patterns.**
+
+**Required reading:**
+- **`node_modules/ultimate-jekyll-manager/CLAUDE.md`** — top-level overview + index
+- **`node_modules/ultimate-jekyll-manager/docs/`** — subsystem deep references (read the relevant ones for the task at hand)
+
+## 🚨 READ WEB-MANAGER TOO
+
+**UJM ships `web-manager` as a runtime singleton on every page** — it powers auth, Firebase, reactive `data-wm-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.). Any task that touches auth flows, Firestore reads/writes, subscription resolution, push notifications, or DOM bindings means you are working with web-manager as much as with UJM.
+
+**Required reading:**
+- **`node_modules/web-manager/CLAUDE.md`** — top-level overview + index
+- **`node_modules/web-manager/docs/`** — module deep references (Auth, Bindings, Firestore, Notifications, etc.)
 
 ## Quick start
 
@@ -67,6 +77,8 @@ At build time, `require('ultimate-jekyll-manager/build')` exposes:
 - `Manager.logger(name)` — timestamped logger instance
 - `Manager.require(path)` — escape hatch for UJM transitive deps (use sparingly)
 
+<!-- Everything above this marker is owned by the framework and rewritten on every `npx mgr setup`. Add your project-specific notes below — they are preserved across setups. -->
+
 # ========== Custom Values ==========
 
 ## Project-specific notes

package/dist/defaults/dist/_layouts/themes/classy/frontend/pages/extension/index.html

@@ -11,12 +11,6 @@ hero:
 
 # Downloads Section
 downloads:
-  superheadline:
-    icon: "puzzle-piece"
-    text: "Install"
-  headline: "Available on every"
-  headline_accent: "browser"
-  subheadline: "Choose your browser below to get started"
   loading:
     headline: "Detecting Browser"
     description: "Determining your browser..."
@@ -124,26 +118,6 @@ cta:
 <!-- Downloads Section -->
 <section class="pt-0">
   <div class="container">
-    <div class="text-center mb-5" data-lazy="@class animation-slide-up">
-      {% iftruthy page.resolved.downloads.superheadline.text %}
-        <span class="badge bg-body-tertiary border-gradient-rainbow border-1 text-body p-2 mb-1 fw-semibold small">
-          {% iftruthy page.resolved.downloads.superheadline.icon %}
-            {% uj_icon page.resolved.downloads.superheadline.icon, "me-1" %}
-          {% endiftruthy %}
-          {{ page.resolved.downloads.superheadline.text }}
-        </span>
-      {% endiftruthy %}
-      <h2 class="h2 mb-2">
-        {{ page.resolved.downloads.headline }}
-        {% iftruthy page.resolved.downloads.headline_accent %}
-          <span class="text-accent">{{ page.resolved.downloads.headline_accent }}</span>
-        {% endiftruthy %}
-      </h2>
-      {% iftruthy page.resolved.downloads.subheadline %}
-        <p class="fs-5 text-muted">{{ page.resolved.downloads.subheadline }}</p>
-      {% endiftruthy %}
-    </div>
-
     <!-- Browser Selector -->
     <div class="row justify-content-center mb-5">
       <div class="col-12">

package/dist/defaults/docs/README.md

@@ -0,0 +1,17 @@
+# Project docs
+
+Per-subsystem deep references live here. Keep `CLAUDE.md` short — it should read as a **table of contents** that points at files in this directory.
+
+## Pattern
+
+When you find yourself adding more than a paragraph to `CLAUDE.md`, create a new `docs/<topic>.md` instead and link to it from `CLAUDE.md`. Goal: the project's `CLAUDE.md` stays under ~250 lines.
+
+Examples of good `docs/*.md` topics:
+- Subsystem deep-dives (one per area of the codebase)
+- Architectural decisions / "why we built it this way"
+- Defaults tables, behavior matrices, edge cases
+- Setup walkthroughs that don't belong in `README.md`
+
+## See also
+
+The framework's own docs follow this same pattern — browse `node_modules/ultimate-jekyll-manager/docs/` for the canonical examples.

package/dist/defaults/test/README.md

@@ -0,0 +1,31 @@
+# Project tests
+
+Drop your project test suites here. The framework auto-runs them alongside its own when you run `npx mgr test`.
+
+## Layers
+
+Match the framework's three layers — Ultimate Jekyll Manager's test runner discovers files by the directory they sit in:
+
+| Directory | Runtime | Use for |
+|---|---|---|
+| `test/build/` | Plain Node | Build-time logic, config validation, pure utilities |
+| `test/page/` | Browser page served from a local HTTP server | DOM, frontend Manager, page-specific scripts, `data-wm-bind` directives |
+| `test/boot/` | Consumer's actual built `_site/` | End-to-end smoke tests (does the site boot, does the service worker register, do dynamic pages load) |
+
+## Quick example
+
+```js
+// test/build/my-feature.test.js
+const assert = require('ultimate-jekyll-manager/test/assert');
+
+module.exports = {
+  'my feature does the thing': async () => {
+    const result = await doTheThing();
+    assert.equal(result, 'expected');
+  },
+};
+```
+
+## See also
+
+`node_modules/ultimate-jekyll-manager/docs/test-framework.md` — full reference for the test framework (layers, assert API, fixtures, runner internals).

package/docs/ads.md

@@ -0,0 +1,78 @@
+# Ad Units (Verts)
+
+Ultimate Jekyll provides ad unit includes that display Google AdSense ads with automatic fallback to in-house ads served from promo-server when AdSense is blocked or unfilled.
+
+## Include Files
+
+| Include | Purpose |
+|---------|---------|
+| `modules/adunits/adsense.html` | AdSense ad with promo-server fallback |
+| `modules/adunits/promo-server.html` | Direct promo-server ad (no AdSense) |
+
+## AdSense Include
+
+```liquid
+{% include /modules/adunits/adsense.html type="in-article" %}
+{% include /modules/adunits/adsense.html type="in-article" vert-size="rectangle" %}
+{% include /modules/adunits/adsense.html type="display" vert-size="banner" %}
+{% include /modules/adunits/adsense.html type="display" vert-size="300" %}
+```
+
+**Parameters:**
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `type` | No | `display` | Ad type: `display`, `in-article`, `in-feed`, `multiplex` |
+| `slot` | No | From site config | Override the ad slot ID |
+| `vert-size` | No | (unconstrained) | Max height preset or pixel value (cannot use `size` — conflicts with Liquid's built-in `size` filter) |
+| `style` | No | `""` | Custom inline CSS |
+| `layout` | No | `image-above` | Layout for `in-feed` type: `image-above`, `image-side` |
+
+## Promo Server Include
+
+```liquid
+{% include /modules/adunits/promo-server.html vert-id="/verts/units/test/google" %}
+{% include /modules/adunits/promo-server.html vert-id="/verts/units/test/google" vert-size="banner" %}
+```
+
+**Parameters:**
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `vert-id` | Yes | `""` | Path to the vert on promo-server |
+| `vert-size` | No | (unconstrained) | Max height preset or pixel value |
+| `style` | No | `""` | Custom inline CSS |
+
+## Size Presets
+
+The `vert-size` parameter accepts preset names or raw pixel values. Presets constrain the ad unit's max-height:
+
+| Preset | Max Height | Typical Use |
+|--------|-----------|-------------|
+| `banner` | 150px | Horizontal banner ads |
+| `leaderboard` | 90px | Wide horizontal ads (alias for banner) |
+| `rectangle` | 250px | Medium rectangle, in-content ads |
+| `large-rectangle` | 600px | Large rectangle, sidebar ads |
+| `skyscraper` | 600px | Tall sidebar ads |
+
+Raw pixel values are also accepted: `vert-size="300"` → 300px max-height.
+
+When no `vert-size` is specified, the ad unit renders unconstrained.
+
+## How It Works
+
+1. The include renders a `data-lazy="@script ..."` div that lazy-loads `vert.bundle.js` when scrolled into view
+2. `vert.js` creates a `<vert-unit>` custom element with `max-height` + `overflow: hidden` (if `vert-size` is set)
+3. For AdSense types: loads the AdSense script, pushes the ad, and monitors fill status
+4. If AdSense is blocked or unfilled, falls back to a promo-server iframe
+5. The promo-server iframe content uses CSS container queries to adapt its layout to the available space
+6. Ad units are hidden for non-basic plan users via `data-wm-bind="@hide auth.account.subscription.product.id !== basic"`
+
+## File Locations
+
+| Purpose | Path |
+|---------|------|
+| AdSense include | `src/defaults/dist/_includes/modules/adunits/adsense.html` |
+| Promo Server include | `src/defaults/dist/_includes/modules/adunits/promo-server.html` |
+| Vert JS module | `src/assets/js/modules/vert.js` |
+| Vert CSS | `src/assets/css/core/_verts.scss` |

package/docs/analytics.md

@@ -0,0 +1,90 @@
+# Analytics & Tracking
+
+Ultimate Jekyll uses three tracking platforms: Google Analytics (gtag), Facebook Pixel (fbq), and TikTok Pixel (ttq).
+
+## ITM (Internal Tracking Medium)
+
+Internal tracking system modeled after UTM for cross-property user journey tracking.
+
+| Parameter | Purpose | Examples |
+|-----------|---------|----------|
+| `itm_source` | Platform/origin | `website`, `browser-extension`, `app`, `email` |
+| `itm_medium` | Delivery mechanism | `modal`, `prompt`, `banner`, `tooltip` |
+| `itm_campaign` | Specific campaign/feature | `exit-popup`, `premium-unlock`, `newsletter-signup` |
+| `itm_content` | Specific context | Page path, feature ID, variant |
+
+**Examples:**
+
+```
+# Website exit popup
+?itm_source=website&itm_medium=modal&itm_campaign=exit-popup&itm_content=/pricing
+
+# Extension premium unlock
+?itm_source=browser-extension&itm_medium=prompt&itm_campaign=premium-unlock&itm_content=bulk-export
+```
+
+## Tracking Guidelines
+
+**IMPORTANT Rules:**
+- Track important user events with `gtag()`, `fbq()`, and `ttq()` functions
+- NEVER add conditional checks for tracking functions (e.g., `if (typeof gtag !== 'undefined')`)
+- Always assume tracking functions exist — they're globally available or stubbed
+- Reference standard events documentation before implementing custom tracking
+
+**Standard Events Documentation:**
+- **Google Analytics GA4:** https://developers.google.com/analytics/devguides/collection/ga4/reference/events
+- **Facebook Pixel:** https://www.facebook.com/business/help/402791146561655?id=1205376682832142
+- **TikTok Pixel:** https://ads.tiktok.com/help/article/standard-events-parameters?redirected=2
+
+## Platform-Specific Requirements
+
+### TikTok Pixel Requirements
+
+TikTok has strict validation requirements:
+
+**Required Parameters:**
+- `content_id` — MUST be included in all events
+
+**Valid Content Types:**
+- `"product"`
+- `"product_group"`
+- `"destination"`
+- `"hotel"`
+- `"flight"`
+- `"vehicle"`
+
+Any other content type will generate a validation error.
+
+**Example:**
+
+```javascript
+// ✅ CORRECT
+ttq.track('ViewContent', {
+  content_id: 'product-123',
+  content_type: 'product'
+});
+
+// ❌ WRONG - Missing content_id
+ttq.track('ViewContent', {
+  content_type: 'product'
+});
+
+// ❌ WRONG - Invalid content_type
+ttq.track('ViewContent', {
+  content_id: 'product-123',
+  content_type: 'custom'  // Not in approved list
+});
+```
+
+## Tracking Implementation
+
+**IMPORTANT:** Always track events to ALL THREE platforms in this order:
+1. Google Analytics (gtag)
+2. Facebook Pixel (fbq)
+3. TikTok Pixel (ttq)
+
+Track events directly without existence checks. All three tracking calls should be made together for every event.
+
+**Development Mode:**
+
+In development mode, all tracking calls are intercepted and logged to the console for debugging. See `src/assets/js/libs/dev.js` for implementation.

package/docs/appearance.md

@@ -0,0 +1,65 @@
+# Appearance Switching System
+
+Ultimate Jekyll supports dark/light/system theme switching with user preference persistence.
+
+## Supported Modes
+
+- `dark` — Force dark mode
+- `light` — Force light mode
+- `system` — Auto-detect from OS preference (`prefers-color-scheme`)
+
+## JavaScript API
+
+```javascript
+// Get/set preference
+webManager.uj().appearance.get();        // Returns 'dark', 'light', 'system', or null
+webManager.uj().appearance.set('dark');  // Save and apply preference
+webManager.uj().appearance.getResolved(); // Returns actual theme: 'dark' or 'light'
+
+// Utilities
+webManager.uj().appearance.toggle();     // Toggle between dark/light
+webManager.uj().appearance.cycle();      // Cycle: dark → light → system → dark
+webManager.uj().appearance.clear();      // Clear saved preference
+```
+
+## HTML Data Attributes
+
+```html
+<!-- Buttons to set appearance (auto-gets 'active' class) -->
+<button data-appearance-set="light">Light</button>
+<button data-appearance-set="dark">Dark</button>
+<button data-appearance-set="system">System</button>
+
+<!-- Display current mode as text -->
+<span data-appearance-current></span>
+
+<!-- Show/hide icons based on current mode -->
+<span data-appearance-icon="light" hidden>☀️</span>
+<span data-appearance-icon="dark" hidden>🌙</span>
+<span data-appearance-icon="system" hidden>💻</span>
+```
+
+## Dropdown Example
+
+```html
+<div class="dropdown">
+  <button class="btn dropdown-toggle" data-bs-toggle="dropdown">
+    <span data-appearance-icon="light" hidden>{% uj_icon "sun", "fa-md me-2" %}</span>
+    <span data-appearance-icon="dark" hidden>{% uj_icon "moon-stars", "fa-md me-2" %}</span>
+    <span data-appearance-icon="system" hidden>{% uj_icon "circle-half-stroke", "fa-md me-2" %}</span>
+    <span data-appearance-current></span>
+  </button>
+  <ul class="dropdown-menu">
+    <li><a class="dropdown-item" href="#" data-appearance-set="light">Light</a></li>
+    <li><a class="dropdown-item" href="#" data-appearance-set="dark">Dark</a></li>
+    <li><a class="dropdown-item" href="#" data-appearance-set="system">System</a></li>
+  </ul>
+</div>
+```
+
+## Implementation
+
+- **Inline script:** `src/defaults/dist/_includes/core/body.html` — Runs immediately to prevent flash
+- **Module:** `src/assets/js/core/appearance.js` — API and UI handling
+- **Storage:** Saved under `_manager.appearance.preference` in localStorage
+- **Test page:** `/test/libraries/appearance`