Moko-Cassiopeia v02.00 — README

Joomla! site template by Moko Consulting License: GPL-3.0-or-later Compatibility: Joomla 4.4+ / 5.x (PHP 8.1+)

---

Overview

Moko-Cassiopeia is a streamlined, Bootstrap-friendly Joomla template with a tokenized color system, Google Tag Manager / Analytics hooks, and performance-minded assets.

• v02.00 (2025-08-30) introduces Dark Mode with OS auto-detection and an optional Dark Mode Toggle (ID 25) so users can manually switch themes; their preference persists.
• v01.00 was the initial public release (FA6, BS5, TOC, GTM/GA hooks).

Public roadmap: https://mokoconsulting.tech/support/joomla-cms/moko-cassiopeia-roadmap

---

What’s New in v02.00

• Dark Mode with prefers-color-scheme auto-detect.

• Dark Mode Toggle (Template param ID 25) with positions Header / Navbar / Footer.

  • Persists choice to localStorage (key: moko.theme).
  • Keyboard- and screen-reader-friendly; focus ring uses theme tokens.
  • Admin option “Show Theme Toggle” (On/Off).

• CSS refactor to variables: light tokens in :root, dark overrides in [data-theme="dark"].

• Lowered CSS specificity, rem units for scalable typography/spacing.

• Stabilized WebAsset registrations (LTR/RTL presets).

---

Features

• Dark Mode + Toggle Auto-detect plus manual switch; persistent per user.

• Bootstrap-friendly CSS Low specificity, variable-driven utilities for buttons, alerts, typography, spacing.

• GTM / GA Hooks Clean injection points for Google Tag Manager and optional direct GA4 tag.

• LTR / RTL Presets Stable asset registration pattern for palette and template styles.

• A11y & Performance Clear focus styling and balanced contrast; minified bundles in production.

---

Requirements

• Joomla 4.4+ / 5.x
• PHP 8.1+
• Modern evergreen browsers (graceful fallback if prefers-color-scheme isn’t available)

---

Installation

1. Install via Extensions → Manage → Install (upload the template .zip).
2. Set as default in System → Templates → Site Templates.
3. Clear caches: System → Clear Cache and hard-reload your browser.

---

Template Options (high-level)

Theme

• Force Theme: Auto (default) | Light | Dark
• Show Theme Toggle (ID 25): On | Off
• Toggle Position: Header | Navbar | Footer
• Default Theme (when not using Auto): Light

GTM / Analytics

• GTM Container ID (e.g., GTM-XXXXXXX)
• Analytics Tag ID (optional GA4 if not using GTM)

Performance

• Development Mode

  • Off → .min.css / .min.js bundles
  • On → unminified sources for debugging

---

Dark Mode — Tokens & Toggle

Color tokens

:root {
	--color-bg: #ffffff;
	--color-surface: #f8f9fa;
	--color-text: #1d2125;
	--color-text-muted: #6c757d;
	--color-border: #dee2e6;

	--color-primary: #0d6efd;
	--color-primary-contrast: #ffffff;

	--color-link: var(--color-primary);
	--color-link-hover: #0b5ed7;

	--focus-ring: 0 0 0 .2rem rgba(13,110,253,.25);
}

[data-theme="dark"] {
	--color-bg: #0e1116;
	--color-surface: #151922;
	--color-text: #e7eaf0;
	--color-text-muted: #a4acb9;
	--color-border: #2a3240;

	--color-primary: #66b2ff;
	--color-primary-contrast: #0d1117;

	--color-link: var(--color-primary);
	--color-link-hover: #99ccff;

	--focus-ring: 0 0 0 .2rem rgba(102,178,255,.35);
}

Programmatic switch (optional)

// Apply and persist a choice
document.documentElement.dataset.theme = 'dark'; // or 'light'
localStorage.setItem('moko.theme', 'dark');      // namespaced key

---

CSS Architecture

• template.css = structure/layout and component scaffolding
• No hard-coded hex in core selectors; all colors reference tokens
• Units: rem (replacing em) for scalable typography/spacing
• Low specificity to play nicely with Bootstrap and content plugins

---

GTM / Analytics Integration

• Enter GTM Container ID in Template Options to inject the GTM snippet.
• Optionally add a GA4 Measurement ID if not routing GA via GTM.
• Output uses Joomla rendering events to avoid duplication.

Verify tags with DevTools / Tag Assistant.

---

RTL / LTR Assets (WebAsset JSON)

Minimal pattern:

{
	"$schema": "https://developer.joomla.org/schemas/json/schema_web_assets.json",
	"name": "template.moko-cassiopeia",
	"assets": [
		{ "name": "template.moko-cassiopeia.styles",  "type": "style", "uri": "templates/moko-cassiopeia/css/template.min.css" },
		{ "name": "template.moko-cassiopeia.palette", "type": "style", "uri": "templates/moko-cassiopeia/css/colors_standard.min.css" },
		{ "name": "template.moko-cassiopeia", "type": "preset", "dependencies": ["template.moko-cassiopeia.styles","template.moko-cassiopeia.palette"] }
	]
}

In index.php:

/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = $this->getWebAssetManager();
$wa->usePreset('template.moko-cassiopeia');

---

Upgrade Notes

1.0 → 2.0

• Clear Joomla + browser caches.
• Convert any hard-coded colors in overrides to tokens (e.g., var(--color-text-muted)).
• Review spacing/typography where rem replaces em.
• Verify asset names if you referenced WebAsset handles directly.
• If you previously added a custom dark-mode toggle, remove it and enable Show Theme Toggle (ID 25).

---

Accessibility

• Improved contrast targets across light/dark.
• Visible, consistent focus indicators.
• Toggle is keyboard-navigable and labeled for assistive tech.

---

Troubleshooting

• Toggle not visible → Ensure “Show Theme Toggle” is on and placed in a visible position.
• Preference not persisting → Check localStorage availability and console for JS errors.
• Asset dependency warnings → Confirm preset/asset names match your joomla.asset.json.

---

Feature Rundown & Comparison

Moko-Cassiopeia v01.00 — Initial public release

• Font Awesome 6 integrated; Bootstrap 5 helpers.
• TOC utility hooks for article table of contents.
• GTM/GA hooks with safe injection points.
• Minimal, upgrade-friendly overrides; variable-ready CSS.

Moko-Cassiopeia v02.00 — Dark Mode + Toggle (ID 25)

• Dark Mode with OS auto-detect.
• Optional Dark Mode Toggle (ID 25) in Header / Navbar / Footer; persisted per user.
• Tokenized palette (:root + [data-theme="dark"]).
• CSS refactor: low specificity; rem units; Bootstrap-friendly utilities.
• Stabilized Web Asset registrations (LTR/RTL presets).

Baseline: Cassiopeia (Joomla 4.4 / 5.x)

• Responsive, accessible core site template with Bootstrap-friendly markup.
• Template options for color preset, layout width, sticky header, and module menu layouts.
• Web Asset Manager integration (joomla.asset.json, $this->getWebAssetManager()).

---

Roadmap

Public roadmap: https://mokoconsulting.tech/support/joomla-cms/moko-cassiopeia-roadmap

---

Changelog (1.0 → 2.0)

02.00 — 2025-08-30 — “Dark Mode”

Added

• Dark Mode with OS auto-detection (prefers-color-scheme).
• Dark Mode Toggle (param ID 25) with positions Header / Navbar / Footer; persists choice via localStorage (moko.theme); accessible markup and focus styling.
• Tokenized CSS palette with [data-theme="dark"] overrides.
• Admin override to force Light/Dark/Auto.
• Bootstrap-friendly utility hooks mapped to tokens.

Changed

• template.css now structure/layout only; colors via tokens.
• em → rem; reduced specificity; standardized focus indicators.

Fixed

• WebAsset registrations (LTR/RTL/preset deps) and dark-theme link/muted contrast.

Removed / Deprecated

• Hard-coded color declarations and legacy hex-based helper classes.

---

01.00 — Initial public release

• FA6, BS5, TOC, GTM/GA hooks.