Add CSS variables reference documentation and color template files

- Created /templates/ directory with colors_custom_light.css and colors_custom_dark.css - Added comprehensive CSS_VARIABLES.md documentation - Updated README with improved Custom Color Palettes section - Updated docs/README.md to include new resources - Updated CHANGELOG with new additions Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>
2026-01-30 02:05:49 +00:00
parent 6a3f1322f9
commit 13abfbcbb9
6 changed files with 998 additions and 8 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,15 +21,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [03.06.03] - 2026-01-30

+### Added
+- **Templates Directory**: Created `/templates/` directory with ready-to-use color palette templates
+  - `colors_custom_light.css` - Comprehensive light mode color template with all available variables
+  - `colors_custom_dark.css` - Comprehensive dark mode color template with all available variables
+- **CSS Variables Documentation**: Added complete CSS variables reference guide (`docs/CSS_VARIABLES.md`)
+  - Complete list of all customizable CSS variables
+  - Organized by category (colors, typography, borders, etc.)
+  - Usage examples and tips for customization
+  - Light and dark mode variable differences documented
+
 ### Changed
 - **README**: Updated title to "README - MokoCassiopeia (VERSION: 03.06.03)"
 - **README**: Fixed custom color variables instructions with correct file paths
 - **README**: Updated example CSS variables to use actual template variable names (e.g., `--color-link` instead of `--cassiopeia-color-link`)
 - **README**: Added note that custom color files are excluded from version control via `.gitignore`
+- **README**: Enhanced Custom Color Palettes section with step-by-step instructions
+- **README**: Added link to CSS Variables documentation for complete reference
 - **TOC CSS**: Updated bootstrap-toc.css to use template color variables for proper theme integration
 - **Version**: Updated version to 03.06.03 across all files

 ### Documentation
+- **docs/README.md**: Added CSS Variables Reference to developer documentation section
+- **docs/README.md**: Updated project structure to include `/templates/` directory
+- **docs/README.md**: Updated version to 03.06.03
 - Clarified that `colors_custom.css` files are gitignored to prevent fork-specific customizations from being committed

 ## [03.06.02] - 2026-01-30
--- a/README.md
+++ b/README.md
@@ -205,14 +205,16 @@ Access template configuration via **System → Site Templates → MokoCassiopeia

 MokoCassiopeia supports custom color schemes:

-1. Create `media/templates/site/mokocassiopeia/css/colors/light/colors_custom.css` for light mode
-2. Create `media/templates/site/mokocassiopeia/css/colors/dark/colors_custom.css` for dark mode
-3. Define CSS variables (reference `colors_standard.css` for structure)
-4. Select "Custom" palette in template settings
+1. **Copy template files** from `/templates/` directory:
+   - `colors_custom_light.css` → `media/templates/site/mokocassiopeia/css/colors/light/colors_custom.css`
+   - `colors_custom_dark.css` → `media/templates/site/mokocassiopeia/css/colors/dark/colors_custom.css`
+2. **Customize** the CSS variables to match your brand colors
+3. **Enable in Joomla**: System → Site Templates → MokoCassiopeia → Theme tab → Set palette to "Custom"
+4. **Save** and view your site with custom colors

 **Note:** Custom color files are excluded from version control (`.gitignore`) to prevent fork-specific customizations from being committed.

-**Example CSS Variables:**
+**Quick Example:**

 ```css
 :root[data-bs-theme="light"] {
@@ -224,6 +226,8 @@ MokoCassiopeia supports custom color schemes:
 }
 ```

+**Complete Reference:** See [CSS Variables Documentation](./docs/CSS_VARIABLES.md) for all available variables and detailed usage examples.
+
 ### Table of Contents

 Enable automatic TOC for articles:
@@ -319,8 +323,15 @@ See [Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md) for packaging instr
 - **[Quick Start](./docs/QUICK_START.md)** - 5-minute developer setup
 - **[Development Guide](./docs/JOOMLA_DEVELOPMENT.md)** - Comprehensive development guide
 - **[Workflow Guide](./docs/WORKFLOW_GUIDE.md)** - Git workflow and processes
+- **[CSS Variables Reference](./docs/CSS_VARIABLES.md)** - Complete CSS customization guide
 - **[Documentation Index](./docs/README.md)** - All documentation links

+### Customization Resources
+
+- **[Template Files](./templates/)** - Ready-to-use color palette templates
+  - `colors_custom_light.css` - Light mode template
+  - `colors_custom_dark.css` - Dark mode template
+
 ### Governance

 - **[Contributing](./CONTRIBUTING.md)** - How to contribute
--- a/docs/CSS_VARIABLES.md
+++ b/docs/CSS_VARIABLES.md
@@ -0,0 +1,481 @@
+<!--
+ Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+
+ This file is part of a Moko Consulting project.
+
+ SPDX-License-Identifier: GPL-3.0-or-later
+
+ # FILE INFORMATION
+ DEFGROUP: Joomla.Template.Site
+ INGROUP: MokoCassiopeia.Documentation
+ REPO: https://github.com/mokoconsulting-tech/MokoCassiopeia
+ FILE: docs/CSS_VARIABLES.md
+ VERSION: 03.06.03
+ BRIEF: Complete CSS variable reference for MokoCassiopeia template
+-->
+
+# CSS Variables Reference - MokoCassiopeia
+
+This document provides a complete reference of all CSS variables available in the MokoCassiopeia template for customization.
+
+## Table of Contents
+
+- [Using Custom Color Palettes](#using-custom-color-palettes)
+- [Primary Brand Colors](#primary-brand-colors)
+- [Link Colors](#link-colors)
+- [Navigation Colors](#navigation-colors)
+- [Header Background](#header-background)
+- [Container Backgrounds](#container-backgrounds)
+- [Bootstrap Color Palette](#bootstrap-color-palette)
+- [Body & Typography](#body--typography)
+- [Additional Theme Colors](#additional-theme-colors)
+- [Borders & Shadows](#borders--shadows)
+- [Form Colors](#form-colors)
+
+---
+
+## Using Custom Color Palettes
+
+To create custom color schemes:
+
+1. **Copy template files** from `./templates/` directory:
+   - `colors_custom_light.css` → `media/templates/site/mokocassiopeia/css/colors/light/colors_custom.css`
+   - `colors_custom_dark.css` → `media/templates/site/mokocassiopeia/css/colors/dark/colors_custom.css`
+
+2. **Edit the variables** in the copied files to match your brand
+
+3. **Enable in Joomla**:
+   - Navigate to: System → Site Templates → MokoCassiopeia
+   - Under "Theme" tab, set palette to "Custom"
+   - Save changes
+
+4. **Note**: Custom files are gitignored and won't be committed to the repository
+
+---
+
+## Primary Brand Colors
+
+### `--color-primary`
+- **Description**: Main brand color used throughout the template
+- **Light Mode Default**: `#112855`
+- **Dark Mode Default**: `#112855`
+- **Usage**: Headers, primary buttons, brand elements
+
+### `--accent-color-primary`
+- **Description**: Primary accent color for interactive elements
+- **Light Mode Default**: `#3f8ff0`
+- **Dark Mode Default**: `#3f8ff0`
+- **Usage**: Hover states, focus indicators, call-to-action elements
+
+### `--accent-color-secondary`
+- **Description**: Secondary accent color
+- **Light Mode Default**: `#3f8ff0`
+- **Dark Mode Default**: `#6fb3ff`
+- **Usage**: Secondary highlights, alternative styling
+
+---
+
+## Link Colors
+
+### `--color-link`
+- **Description**: Default color for hyperlinks
+- **Light Mode Default**: `#224FAA`
+- **Dark Mode Default**: `white`
+- **Usage**: All text links in content
+
+### `--color-hover`
+- **Description**: Color when hovering over links and interactive elements
+- **Light Mode Default**: `var(--accent-color-primary)`
+- **Dark Mode Default**: `gray`
+- **Usage**: Hover states for links and buttons
+
+### `--color-active`
+- **Description**: Color for active/selected links
+- **Light Mode Default**: (not set)
+- **Dark Mode Default**: `var(--mainmenu-nav-link-color)`
+- **Usage**: Active navigation items, selected states
+
+### `--link-color`
+- **Description**: Bootstrap-compatible link color variable
+- **Light Mode Default**: `#224faa`
+- **Dark Mode Default**: `#8ab4f8`
+- **Usage**: Alternative link color variable for Bootstrap compatibility
+
+### `--link-hover-color`
+- **Description**: Bootstrap-compatible hover color
+- **Light Mode Default**: `#424077`
+- **Dark Mode Default**: `#c3d6ff`
+- **Usage**: Link hover state for Bootstrap components
+
+---
+
+## Navigation Colors
+
+### `--mainmenu-nav-link-color`
+- **Description**: Text color for main navigation menu
+- **Light Mode Default**: `white`
+- **Dark Mode Default**: `#fff`
+- **Usage**: Navigation menu text
+
+### `--nav-text-color`
+- **Description**: General navigation text color
+- **Light Mode Default**: `white`
+- **Dark Mode Default**: `gray`
+- **Usage**: Navigation elements
+
+### `--nav-bg-color`
+- **Description**: Background color for navigation bars
+- **Light Mode Default**: `var(--color-link)`
+- **Dark Mode Default**: `var(--color-primary)`
+- **Usage**: Navigation background
+
+---
+
+## Header Background
+
+### `--header-background-image`
+- **Description**: Background image URL for header
+- **Default**: `url('../../../../../../media/templates/site/mokocassiopeia/images/bg.svg')`
+- **Usage**: Header section background
+
+### `--header-background-attachment`
+- **Description**: CSS background-attachment property
+- **Default**: `fixed`
+- **Options**: `scroll`, `fixed`, `local`
+
+### `--header-background-repeat`
+- **Description**: CSS background-repeat property
+- **Default**: `repeat`
+- **Options**: `repeat`, `repeat-x`, `repeat-y`, `no-repeat`
+
+### `--header-background-size`
+- **Description**: CSS background-size property
+- **Default**: `auto`
+- **Options**: `auto`, `cover`, `contain`, specific sizes
+
+---
+
+## Container Backgrounds
+
+Each container section has the following customizable properties:
+
+### Container Sections
+- `below-topbar` - Below top navigation bar
+- `top-a` - Top section A
+- `top-b` - Top section B
+- `toc` - Table of Contents sidebar
+- `sidebar` - Sidebar area
+- `bottom-a` - Bottom section A
+- `bottom-b` - Bottom section B
+
+### Available Properties per Container
+Replace `{section}` with the container name:
+
+- `--container-{section}-bg-image` - Background image URL
+- `--container-{section}-bg-color` - Background color
+- `--container-{section}-bg-position` - Background position
+- `--container-{section}-bg-attachment` - Attachment (scroll/fixed)
+- `--container-{section}-bg-repeat` - Repeat pattern
+- `--container-{section}-bg-size` - Background size
+- `--container-{section}-border` - Border styling
+- `--container-{section}-border-radius` - Border radius
+
+### Special TOC Variables
+
+#### `--container-toc-bg`
+- **Description**: Background color for TOC container
+- **Light Mode Default**: `var(--mainmenu-nav-link-color)`
+- **Dark Mode Default**: (empty, transparent)
+
+#### `--container-toc-color`
+- **Description**: Text color for TOC
+- **Light Mode Default**: `var(--color-primary)`
+- **Dark Mode Default**: `#dbe3ff`
+
+---
+
+## Bootstrap Color Palette
+
+### Contextual Colors
+
+#### `--primary`
+- **Light Mode**: `#010156`
+- **Dark Mode**: `#010156`
+- **Usage**: Primary theme color
+
+#### `--secondary`
+- **Light Mode**: `#6d757e`
+- **Dark Mode**: `#48525d`
+- **Usage**: Secondary elements
+
+#### `--success`
+- **Light Mode**: `#448344`
+- **Dark Mode**: `#4aa664`
+- **Usage**: Success messages, positive actions
+
+#### `--info`
+- **Light Mode**: `#30638d`
+- **Dark Mode**: `#4f7aa0`
+- **Usage**: Informational messages
+
+#### `--warning`
+- **Light Mode**: `#ad6200`
+- **Dark Mode**: `#c77a00`
+- **Usage**: Warning messages
+
+#### `--danger`
+- **Light Mode**: `#a51f18`
+- **Dark Mode**: `#c23a31`
+- **Usage**: Error messages, destructive actions
+
+#### `--light`
+- **Light Mode**: `#f9fafb`
+- **Dark Mode**: `#1b2027`
+- **Usage**: Light backgrounds
+
+#### `--dark`
+- **Light Mode**: `#353b41`
+- **Dark Mode**: `#0f1318`
+- **Usage**: Dark backgrounds
+
+### Standard Colors
+
+Available in both themes:
+- `--blue`, `--indigo`, `--purple`, `--pink`
+- `--red`, `--orange`, `--yellow`, `--green`
+- `--teal`, `--cyan`
+- `--black`, `--white`
+
+### Gray Scale
+
+Available in 9 shades: `--gray-100` through `--gray-900`
+
+Light mode ranges from very light (`#f9fafb`) to very dark (`#22262a`).
+Dark mode ranges are inverted for better contrast on dark backgrounds.
+
+---
+
+## Body & Typography
+
+### `--body-font-family`
+- **Description**: Default font stack for body text
+- **Default**: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif`
+- **Usage**: All body text
+
+### `--body-font-size`
+- **Description**: Base font size
+- **Default**: `1rem` (typically 16px)
+- **Usage**: Base typography size
+
+### `--body-font-weight`
+- **Description**: Default font weight
+- **Default**: `400`
+- **Usage**: Body text weight
+
+### `--body-line-height`
+- **Description**: Line height for body text
+- **Default**: `1.5`
+- **Usage**: Text line spacing
+
+### `--body-color`
+- **Description**: Main text color
+- **Light Mode Default**: `#22262a`
+- **Dark Mode Default**: `#e6ebf1`
+- **Usage**: Body text color
+
+### `--body-bg`
+- **Description**: Main background color
+- **Light Mode Default**: `#fff`
+- **Dark Mode Default**: `#0e1318`
+- **Usage**: Page background
+
+### `--heading-color`
+- **Description**: Color for headings (h1-h6)
+- **Light Mode Default**: `inherit`
+- **Dark Mode Default**: `#f1f5f9`
+- **Usage**: Heading text
+
+---
+
+## Additional Theme Colors
+
+### `--muted-color`
+- **Default**: `#6d757e`
+- **Usage**: Muted/secondary text
+
+### `--code-color`
+- **Light Mode**: `#e93f8e`
+- **Dark Mode**: `#ff7abd`
+- **Usage**: Inline code elements
+
+### `--highlight-bg`
+- **Light Mode**: `#fbeea8`
+- **Dark Mode**: `#ffe28a1a`
+- **Usage**: Text highlighting, mark elements
+
+### `--emphasis-color`
+- **Light Mode**: `#000`
+- **Dark Mode**: `#fff`
+- **Usage**: Emphasized text
+
+### `--secondary-bg`
+- **Light Mode**: `#eaedf0`
+- **Dark Mode**: `#151b22`
+- **Usage**: Secondary backgrounds, alternate rows
+
+### `--tertiary-bg`
+- **Light Mode**: `#f9fafb`
+- **Dark Mode**: `#10151b`
+- **Usage**: Tertiary backgrounds, subtle contrast
+
+---
+
+## Borders & Shadows
+
+### Border Variables
+
+#### `--border`
+- **Default**: `5px`
+- **Usage**: Border width shorthand
+
+#### `--border-width`
+- **Default**: `1px`
+- **Usage**: Standard border width
+
+#### `--border-style`
+- **Default**: `solid`
+- **Usage**: Border style
+
+#### `--border-color`
+- **Light Mode**: `#dfe3e7`
+- **Dark Mode**: `#2b323b`
+- **Usage**: Standard border color
+
+#### `--border-color-translucent`
+- **Light Mode**: `#0000002d`
+- **Dark Mode**: `#ffffff26`
+- **Usage**: Semi-transparent borders
+
+### Border Radius
+
+- `--border-radius`: `.25rem` (default)
+- `--border-radius-sm`: `.2rem` (small)
+- `--border-radius-lg`: `.3rem` (large)
+- `--border-radius-xl`: `.3rem` (extra large)
+- `--border-radius-xxl`: `2rem` (2x extra large)
+- `--border-radius-pill`: `50rem` (pill-shaped)
+
+### Box Shadows
+
+#### `--box-shadow`
+- **Default**: `0 .5rem 1rem rgba(0,0,0,.15)`
+- **Usage**: Standard drop shadow
+
+#### `--box-shadow-sm`
+- **Default**: `0 .125rem .25rem rgba(0,0,0,.075)`
+- **Usage**: Small/subtle shadow
+
+#### `--box-shadow-lg`
+- **Default**: `0 1rem 3rem rgba(0,0,0,.175)`
+- **Usage**: Large/prominent shadow
+
+#### `--box-shadow-inset`
+- **Default**: `inset 0 1px 2px rgba(0,0,0,.075)`
+- **Usage**: Inset/inner shadow
+
+---
+
+## Form Colors
+
+### Focus Ring
+
+#### `--focus-ring-width`
+- **Default**: `.25rem`
+- **Usage**: Width of focus indicators
+
+#### `--focus-ring-opacity`
+- **Light Mode**: `.25`
+- **Dark Mode**: `.6`
+- **Usage**: Opacity of focus ring
+
+#### `--focus-ring-color`
+- **Light Mode**: `rgba(1,1,86,.25)`
+- **Dark Mode**: `rgba(84,114,255,.4)`
+- **Usage**: Color of focus indicators
+
+### Validation Colors
+
+#### Valid State
+- `--form-valid-color`: Success green
+  - Light: `#448344`
+  - Dark: `#78d694`
+- `--form-valid-border-color`: Matching border color
+
+#### Invalid State
+- `--form-invalid-color`: Error red
+  - Light: `#a51f18`
+  - Dark: `#ff8e86`
+- `--form-invalid-border-color`: Matching border color
+
+---
+
+## Usage Examples
+
+### Example 1: Custom Brand Colors
+
+```css
+:root[data-bs-theme="light"] {
+  --color-primary: #1e40af;
+  --accent-color-primary: #3b82f6;
+  --color-link: #2563eb;
+  --color-hover: #1d4ed8;
+}
+```
+
+### Example 2: Custom Container Background
+
+```css
+:root[data-bs-theme="light"] {
+  --container-top-a-bg-color: #f3f4f6;
+  --container-top-a-bg-image: url('/images/pattern.svg');
+  --container-top-a-bg-repeat: repeat;
+  --container-top-a-border-radius: 8px;
+}
+```
+
+### Example 3: Custom Typography
+
+```css
+:root[data-bs-theme="light"] {
+  --body-font-family: 'Inter', sans-serif;
+  --body-font-size: 1.125rem;
+  --heading-color: #1f2937;
+}
+```
+
+---
+
+## Tips for Customization
+
+1. **Start with templates**: Use the provided template files as a starting point
+2. **Test both themes**: Ensure your colors work well in both light and dark modes
+3. **Use CSS variables**: Reference other variables with `var()` for consistency
+4. **Check contrast**: Ensure text remains readable against backgrounds
+5. **Use fallbacks**: Provide fallback values in `var()` functions
+6. **Test responsively**: Verify colors work on all screen sizes
+7. **Document changes**: Keep notes on custom color choices
+
+---
+
+## See Also
+
+- [README](../README.md) - Main documentation
+- [Quick Start Guide](./QUICK_START.md) - Getting started
+- [Development Guide](./JOOMLA_DEVELOPMENT.md) - Developer resources
+- Template files in `/templates/` directory
+
+---
+
+**Version**: 03.06.03  
+**Last Updated**: 2026-01-30  
+**Maintainer**: Moko Consulting
--- a/docs/README.md
+++ b/docs/README.md
@@ -40,8 +40,14 @@ This directory contains comprehensive documentation for the MokoCassiopeia Jooml
  * Joomla extension packaging
  * Multi-version testing

+* **[CSS Variables Reference](CSS_VARIABLES.md)** - Complete CSS customization guide
+  * All available CSS variables
+  * Custom color palette creation
+  * Usage examples and tips
+  * Light and dark mode theming
+
 * **[Roadmap](ROADMAP.md)** - Version-specific roadmap
-  * Current features (v03.06.00)
+  * Current features (v03.06.03)
  * Feature evolution timeline
  * Planned enhancements
  * Development priorities
@@ -59,10 +65,14 @@ moko-cassiopeia/
 │   ├── QUICK_START.md      # Quick start guide for developers
 │   ├── WORKFLOW_GUIDE.md   # Development workflow guide
 │   ├── JOOMLA_DEVELOPMENT.md # Joomla-specific development guide
+│   ├── CSS_VARIABLES.md    # CSS variables reference
 │   └── ROADMAP.md          # Version-specific roadmap
 ├── src/                     # Template source code
 │   ├── templates/          # Joomla template files
 │   └── media/              # Assets (CSS, JS, images)
+├── templates/               # Template files for customization
+│   ├── colors_custom_light.css # Light mode color template
+│   └── colors_custom_dark.css  # Dark mode color template
 ├── tests/                   # Automated tests
 └── .github/                # GitHub configuration and workflows
 ```
@@ -105,13 +115,14 @@ This project adheres to [MokoStandards](https://github.com/mokoconsulting-tech/M
 * Repository: [https://github.com/mokoconsulting-tech/MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia)
 * Path: /docs/README.md
 * Owner: Moko Consulting
-* Version: 03.06.02
+* Version: 03.06.03
 * Status: Active
-* Effective Date: 2026-01-09
+* Effective Date: 2026-01-30

 ## Revision History

 | Date       | Change Summary                                        | Author          |
 | ---------- | ----------------------------------------------------- | --------------- |
+| 2026-01-30 | Added CSS Variables reference, updated version to 03.06.03 | GitHub Copilot |
 | 2026-01-09 | Initial documentation index created for MokoStandards compliance. | GitHub Copilot |
 | 2026-01-27 | Updated with roadmap link and version to 03.05.01.   | GitHub Copilot  |
--- a/templates/colors_custom_dark.css
+++ b/templates/colors_custom_dark.css
@@ -0,0 +1,245 @@
+@charset "UTF-8";
+/* Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+
+ This file is part of a Moko Consulting project.
+
+ SPDX-License-Identifier: GPL-3.0-or-later
+
+ # FILE INFORMATION
+ DEFGROUP: Joomla.Template.Site
+ INGROUP: MokoCassiopeia.Templates
+ PATH: ./templates/colors_custom_dark.css
+ VERSION: 03.06.03
+ BRIEF: Template for custom dark mode color definitions
+ 
+ # USAGE INSTRUCTIONS
+ 1. Copy this file to: media/templates/site/mokocassiopeia/css/colors/dark/colors_custom.css
+ 2. Customize the CSS variables below to match your brand colors for dark mode
+ 3. In Joomla admin, go to System → Site Templates → MokoCassiopeia
+ 4. Under Theme tab, set "Dark Mode Palette" to "Custom"
+ 5. Save and view your site in dark mode to see the custom colors
+ 
+ NOTE: This file is excluded from version control (.gitignore) to prevent
+ fork-specific customizations from being committed to the repository.
+ */
+
+/* -----------------------------------------------
+ * CUSTOM DARK THEME
+ * --------------------------------------------- */
+
+:root[data-bs-theme='dark']{
+	/* System hint for native widgets */
+	color-scheme: dark;
+
+	/* ===== PRIMARY BRAND COLORS ===== */
+	/* Main brand color used throughout the template */
+	--color-primary: #112855;
+	
+	/* Accent colors for interactive elements */
+	--accent-color-primary: #3f8ff0;
+	--accent-color-secondary: #6fb3ff;
+
+	/* ===== LINK COLORS ===== */
+	/* Color for hyperlinks in dark mode */
+	--color-link: white;
+	
+	/* Color when hovering over links */
+	--color-hover: gray;
+	
+	/* Active link color */
+	--color-active: var(--mainmenu-nav-link-color);
+
+	/* ===== NAVIGATION ===== */
+	/* Text color in main menu */
+	--mainmenu-nav-link-color: #fff;
+	
+	/* Background color for navigation */
+	--nav-text-color: gray;
+	--nav-bg-color: var(--color-primary);
+
+	/* ===== HEADER BACKGROUND ===== */
+	/* Background image for header section (same as light mode) */
+	--header-background-image: url('../../../../../../media/templates/site/mokocassiopeia/images/bg.svg');
+	--header-background-attachment: fixed;
+	--header-background-repeat: repeat;
+	--header-background-size: auto;
+
+	/* ===== CONTAINER BACKGROUNDS ===== */
+	/* Below Topbar Container */
+	--container-below-topbar-bg-image: ;
+	--container-below-topbar-bg-color: ;
+	--container-below-topbar-bg-position: center;
+	--container-below-topbar-bg-attachment: fixed;
+	--container-below-topbar-bg-repeat: no-repeat;
+	--container-below-topbar-bg-size: cover;
+	--container-below-topbar-border: ;
+	--container-below-topbar-border-radius: ;
+
+	/* Top A Container */
+	--container-top-a-bg-image: ;
+	--container-top-a-bg-color: ;
+	--container-top-a-bg-position: center;
+	--container-top-a-bg-attachment: fixed;
+	--container-top-a-bg-repeat: no-repeat;
+	--container-top-a-bg-size: cover;
+	--container-top-a-border: ;
+	--container-top-a-border-radius: ;
+
+	/* Top B Container */
+	--container-top-b-bg-image: ;
+	--container-top-b-bg-color: ;
+	--container-top-b-bg-position: center;
+	--container-top-b-bg-attachment: fixed;
+	--container-top-b-bg-repeat: no-repeat;
+	--container-top-b-bg-size: cover;
+	--container-top-b-border: ;
+	--container-top-b-border-radius: ;
+
+	/* Table of Contents Container */
+	--container-toc-bg: ;
+	--container-toc-color: #dbe3ff;
+
+	/* Sidebar Container */
+	--container-sidebar-bg-image: ;
+	--container-sidebar-bg-color: ;
+	--container-sidebar-bg-position: center;
+	--container-sidebar-bg-attachment: scroll;
+	--container-sidebar-bg-repeat: repeat;
+	--container-sidebar-bg-size: auto;
+	--container-sidebar-border: ;
+	--container-sidebar-border-radius: ;
+
+	/* Bottom A Container */
+	--container-bottom-a-bg-image: ;
+	--container-bottom-a-bg-color: ;
+	--container-bottom-a-bg-position: center;
+	--container-bottom-a-bg-attachment: fixed;
+	--container-bottom-a-bg-repeat: no-repeat;
+	--container-bottom-a-bg-size: cover;
+	--container-bottom-a-border: ;
+	--container-bottom-a-border-radius: 5px;
+
+	/* Bottom B Container */
+	--container-bottom-b-bg-image: ;
+	--container-bottom-b-bg-color: ;
+	--container-bottom-b-bg-position: center;
+	--container-bottom-b-bg-attachment: fixed;
+	--container-bottom-b-bg-repeat: no-repeat;
+	--container-bottom-b-bg-size: cover;
+	--container-bottom-b-border: ;
+	--container-bottom-b-border-radius: ;
+
+	/* ===== BOOTSTRAP 5 COLOR PALETTE (Dark Mode) ===== */
+	/* Lightened colors for dark mode visibility */
+	--blue: #91a4ff;
+	--black: #000;
+	--indigo: #b19cff;
+	--purple: #c0a5ff;
+	--pink: #ff8fc0;
+	--red: #ff7a73;
+	--orange: #ff9c4d;
+	--yellow: #ffd166;
+	--green: #78d694;
+	--teal: #76e3ff;
+	--cyan: #6fb7ff;
+	--white: #fff;
+
+	/* Gray scale tuned for dark mode */
+	--gray-100: #161a20;
+	--gray-200: #1b2027;
+	--gray-300: #222831;
+	--gray-400: #2b323b;
+	--gray-500: #36404a;
+	--gray-600: #48525d;
+	--gray-700: #5b6672;
+	--gray-800: #cfd6de;
+	--gray-900: #e6ebf1;
+
+	/* Contextual colors (adjusted for dark backgrounds) */
+	--primary: #010156;
+	--secondary: #48525d;
+	--success: #4aa664;
+	--info: #4f7aa0;
+	--warning: #c77a00;
+	--danger: #c23a31;
+	--light: #1b2027;
+	--dark: #0f1318;
+
+	/* ===== BODY & TYPOGRAPHY ===== */
+	--body-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif;
+	--body-font-size: 1rem;
+	--body-font-weight: 400;
+	--body-line-height: 1.5;
+
+	--body-color: #e6ebf1;
+	--body-color-rgb: 230, 235, 241;
+	--body-bg: #0e1318;
+	--body-bg-rgb: 14, 19, 24;
+
+	/* ===== ADDITIONAL THEME COLORS ===== */
+	--muted-color: #6d757e;
+	--hr-color: var(--border-color, #dfe3e7);
+	--link-active-color: var(--link-color);
+	--code-color: #ff7abd;
+	--code-color-ink: var(--code-color, #e93f8e);
+	--border-color-soft: var(--border-color, #dfe3e7);
+	--kbd-bg: var(--secondary-bg, #eaedf0);
+	--kbd-ink: var(--body-bg, #fff);
+	--toc-bg: var(--secondary-bg, #eaedf0);
+	--toc-ink: var(--color-primary, #112855);
+	--selection-bg: var(--highlight-bg, #fbeea8);
+	--selection-ink: var(--body-color, #22262a);
+	
+	--emphasis-color: #fff;
+	--emphasis-color-rgb: 255, 255, 255;
+
+	--secondary-color: #e6ebf1bf;
+	--secondary-color-rgb: 230, 235, 241;
+	--secondary-bg: #151b22;
+	--secondary-bg-rgb: 21, 27, 34;
+
+	--tertiary-color: #e6ebf180;
+	--tertiary-color-rgb: 230, 235, 241;
+	--tertiary-bg: #10151b;
+	--tertiary-bg-rgb: 16, 21, 27;
+
+	--heading-color: #f1f5f9;
+
+	--link-color: #8ab4f8;
+	--link-color-rgb: 138, 180, 248;
+	--link-decoration: underline;
+	--link-hover-color: #c3d6ff;
+	--link-hover-color-rgb: 195, 214, 255;
+
+	--highlight-color: #111;
+	--highlight-bg: #ffe28a1a;
+
+	/* ===== BORDERS & SHADOWS ===== */
+	--border: 5px;
+	--border-width: 1px;
+	--border-style: solid;
+	--border-color: #2b323b;
+	--border-color-translucent: #ffffff26;
+
+	--border-radius: .25rem;
+	--border-radius-sm: .2rem;
+	--border-radius-lg: .3rem;
+	--border-radius-xl: .3rem;
+	--border-radius-xxl: 2rem;
+	--border-radius-pill: 50rem;
+
+	--box-shadow: 0 .5rem 1rem #00000066;
+	--box-shadow-sm: 0 .125rem .25rem #00000040;
+	--box-shadow-lg: 0 1rem 3rem #00000080;
+	--box-shadow-inset: inset 0 1px 2px #00000040;
+
+	/* ===== FORM COLORS ===== */
+	--focus-ring-width: .25rem;
+	--focus-ring-opacity: .6;
+	--focus-ring-color: #5472ff66;
+
+	--form-valid-color: #78d694;
+	--form-valid-border-color: #78d694;
+	--form-invalid-color: #ff8e86;
+	--form-invalid-border-color: #ff8e86;
+}
--- a/templates/colors_custom_light.css
+++ b/templates/colors_custom_light.css
@@ -0,0 +1,227 @@
+@charset "UTF-8";
+/* Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+
+ This file is part of a Moko Consulting project.
+
+ SPDX-License-Identifier: GPL-3.0-or-later
+
+ # FILE INFORMATION
+ DEFGROUP: Joomla.Template.Site
+ INGROUP: MokoCassiopeia.Templates
+ PATH: ./templates/colors_custom_light.css
+ VERSION: 03.06.03
+ BRIEF: Template for custom light mode color definitions
+ 
+ # USAGE INSTRUCTIONS
+ 1. Copy this file to: media/templates/site/mokocassiopeia/css/colors/light/colors_custom.css
+ 2. Customize the CSS variables below to match your brand colors
+ 3. In Joomla admin, go to System → Site Templates → MokoCassiopeia
+ 4. Under Theme tab, set "Light Mode Palette" to "Custom"
+ 5. Save and view your site to see the custom colors
+ 
+ NOTE: This file is excluded from version control (.gitignore) to prevent
+ fork-specific customizations from being committed to the repository.
+ */
+
+/* -----------------------------------------------
+ * CUSTOM LIGHT THEME
+ * --------------------------------------------- */
+
+:root[data-bs-theme="light"] {
+	color-scheme: light;
+	
+	/* ===== PRIMARY BRAND COLORS ===== */
+	/* Main brand color used throughout the template */
+	--color-primary: #112855;
+	
+	/* Accent colors for interactive elements */
+	--accent-color-primary: #3f8ff0;
+	--accent-color-secondary: #3f8ff0;
+	
+	/* ===== LINK COLORS ===== */
+	/* Color for hyperlinks */
+	--color-link: #224FAA;
+	
+	/* Color when hovering over links */
+	--color-hover: var(--accent-color-primary);
+	
+	/* ===== NAVIGATION ===== */
+	/* Text color in main menu */
+	--mainmenu-nav-link-color: white;
+	
+	/* Background color for navigation */
+	--nav-text-color: white;
+	--nav-bg-color: var(--color-link);
+	
+	/* ===== HEADER BACKGROUND ===== */
+	/* Background image for header section */
+	--header-background-image: url('../../../../../../media/templates/site/mokocassiopeia/images/bg.svg');
+	--header-background-attachment: fixed;
+	--header-background-repeat: repeat;
+	--header-background-size: auto;
+	
+	/* ===== CONTAINER BACKGROUNDS ===== */
+	/* Below Topbar Container */
+	--container-below-topbar-bg-image: ;
+	--container-below-topbar-bg-color: ;
+	--container-below-topbar-bg-position: auto;
+	--container-below-topbar-bg-attachment: fixed;
+	--container-below-topbar-bg-repeat: repeat;
+	--container-below-topbar-bg-size: auto;
+	--container-below-topbar-border: ;
+	--container-below-topbar-border-radius: ;
+	
+	/* Top A Container */
+	--container-top-a-bg-image: ;
+	--container-top-a-bg-color: ;
+	--container-top-a-bg-position: auto;
+	--container-top-a-bg-attachment: fixed;
+	--container-top-a-bg-repeat: repeat;
+	--container-top-a-bg-size: auto;
+	--container-top-a-border: ;
+	--container-top-a-border-radius: ;
+	
+	/* Top B Container */
+	--container-top-b-bg-image: ;
+	--container-top-b-bg-color: ;
+	--container-top-b-bg-position: auto;
+	--container-top-b-bg-attachment: fixed;
+	--container-top-b-bg-repeat: repeat;
+	--container-top-b-bg-size: auto;
+	--container-top-b-border: ;
+	--container-top-b-border-radius: ;
+	
+	/* Table of Contents Container */
+	--container-toc-bg: var(--mainmenu-nav-link-color);
+	--container-toc-color: var(--color-primary);
+	
+	/* Sidebar Container */
+	--container-sidebar-bg-image: ;
+	--container-sidebar-bg-color: ;
+	--container-sidebar-bg-position: auto;
+	--container-sidebar-bg-attachment: scroll;
+	--container-sidebar-bg-repeat: repeat;
+	--container-sidebar-bg-size: auto;
+	--container-sidebar-border: ;
+	--container-sidebar-border-radius: ;
+	
+	/* Bottom A Container */
+	--container-bottom-a-bg-image: ;
+	--container-bottom-a-bg-color: ;
+	--container-bottom-a-bg-position: auto;
+	--container-bottom-a-bg-attachment: fixed;
+	--container-bottom-a-bg-repeat: repeat;
+	--container-bottom-a-bg-size: auto;
+	--container-bottom-a-border: ;
+	--container-bottom-a-border-radius: ;
+	
+	/* Bottom B Container */
+	--container-bottom-b-bg-image: ;
+	--container-bottom-b-bg-color: ;
+	--container-bottom-b-bg-position: auto;
+	--container-bottom-b-bg-attachment: fixed;
+	--container-bottom-b-bg-repeat: repeat;
+	--container-bottom-b-bg-size: auto;
+	--container-bottom-b-border: ;
+	--container-bottom-b-border-radius: ;
+	
+	/* ===== BOOTSTRAP 5 COLOR PALETTE ===== */
+	/* Standard Bootstrap color variables */
+	--blue: #010156;
+	--black: #000;
+	--indigo: #6812f3;
+	--purple: #6f42c2;
+	--pink: #e93f8e;
+	--red: #a51f18;
+	--orange: #fd7e17;
+	--yellow: #ad6200;
+	--green: #448344;
+	--teal: #5abfdd;
+	--cyan: #30638d;
+	--white: #fff;
+	
+	/* Gray scale */
+	--gray-100: #f9fafb;
+	--gray-200: #eaedf0;
+	--gray-300: #dfe3e7;
+	--gray-400: #ced4da;
+	--gray-500: #adb5bd;
+	--gray-600: #6d757e;
+	--gray-700: #484f56;
+	--gray-800: #353b41;
+	--gray-900: #22262a;
+	
+	/* Contextual colors */
+	--primary: #010156;
+	--secondary: #6d757e;
+	--success: #448344;
+	--info: #30638d;
+	--warning: #ad6200;
+	--danger: #a51f18;
+	--light: #f9fafb;
+	--dark: #353b41;
+	
+	/* ===== BODY & TYPOGRAPHY ===== */
+	--body-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif;
+	--body-font-size: 1rem;
+	--body-font-weight: 400;
+	--body-line-height: 1.5;
+	--body-color: #22262a;
+	--body-color-rgb: 34, 38, 42;
+	--body-bg: #fff;
+	--body-bg-rgb: 255, 255, 255;
+	
+	/* ===== ADDITIONAL THEME COLORS ===== */
+	--muted-color: #6d757e;
+	--hr-color: var(--border-color, #dfe3e7);
+	--link-active-color: var(--link-color);
+	--code-color: #e93f8e;
+	--code-color-ink: var(--code-color, #e93f8e);
+	--border-color-soft: var(--border-color, #dfe3e7);
+	--kbd-bg: var(--secondary-bg, #eaedf0);
+	--kbd-ink: var(--body-bg, #fff);
+	--toc-bg: var(--secondary-bg, #eaedf0);
+	--toc-ink: var(--color-primary, #112855);
+	--selection-bg: var(--highlight-bg, #fbeea8);
+	--selection-ink: var(--body-color, #22262a);
+	--emphasis-color: #000;
+	--emphasis-color-rgb: 0, 0, 0;
+	--secondary-color: #22262abf;
+	--secondary-bg: #eaedf0;
+	--tertiary-color: #22262a80;
+	--tertiary-bg: #f9fafb;
+	--heading-color: inherit;
+	--link-color: #224faa;
+	--link-color-rgb: 34, 79, 170;
+	--link-decoration: underline;
+	--link-hover-color: #424077;
+	--link-hover-color-rgb: 66, 64, 119;
+	--highlight-color: #22262a;
+	--highlight-bg: #fbeea8;
+	
+	/* ===== BORDERS & SHADOWS ===== */
+	--border: 5px;
+	--border-width: 1px;
+	--border-style: solid;
+	--border-color: #dfe3e7;
+	--border-color-translucent: #0000002d;
+	--border-radius: .25rem;
+	--border-radius-sm: .2rem;
+	--border-radius-lg: .3rem;
+	--border-radius-xl: .3rem;
+	--border-radius-xxl: 2rem;
+	--border-radius-pill: 50rem;
+	--box-shadow: 0 .5rem 1rem #00000026;
+	--box-shadow-sm: 0 .125rem .25rem #00000013;
+	--box-shadow-lg: 0 1rem 3rem #0000002d;
+	--box-shadow-inset: inset 0 1px 2px #00000013;
+	
+	/* ===== FORM COLORS ===== */
+	--focus-ring-width: .25rem;
+	--focus-ring-opacity: .25;
+	--focus-ring-color: #01015640;
+	--form-valid-color: #448344;
+	--form-valid-border-color: #448344;
+	--form-invalid-color: #a51f18;
+	--form-invalid-border-color: #a51f18;
+}