From 3e7816ad1707e65697eabbc7a244d262d2b178c6 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 7 Mar 2026 21:38:35 +0000
Subject: [PATCH] Update documentation for custom color templates and font
 requirements

Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>
---
 src/media/fonts/GOOGLE_FONTS_README.md | 12 ++++
 templates/README.md                    | 97 ++++++++++++++++++++++++--
 2 files changed, 102 insertions(+), 7 deletions(-)

diff --git a/src/media/fonts/GOOGLE_FONTS_README.md b/src/media/fonts/GOOGLE_FONTS_README.md
index 77ca100..ddb0464 100644
--- a/src/media/fonts/GOOGLE_FONTS_README.md
+++ b/src/media/fonts/GOOGLE_FONTS_README.md
@@ -16,6 +16,18 @@
 
 This directory should contain self-hosted Google Font files to eliminate CDN dependencies.
 
+## ⚠️ Manual Download Required
+
+The Google Font `.woff2` files are **NOT included** in the repository and must be downloaded manually before using non-default font schemes.
+
+**Currently Available:**
+- ✅ Osaka font (local TTF file, included)
+
+**Requires Manual Download:**
+- ❌ Roboto fonts (4 weight variants)
+- ❌ Noto Sans fonts (4 weight variants)
+- ❌ Fira Sans fonts (4 weight variants)
+
 ## Required Font Files
 
 Download the following `.woff2` font files and place them in this directory:
diff --git a/templates/README.md b/templates/README.md
index 34ce475..714770f 100644
--- a/templates/README.md
+++ b/templates/README.md
@@ -7,17 +7,100 @@
 
 # MokoCassiopeia Templates Directory
 
-This directory is reserved for future template files and customization resources.
+This directory contains template files for custom color schemes that can be copied to your template installation.
 
-## Custom Color Palettes
+## Custom Color Palette Templates
 
-For custom color schemes, you can create your own CSS files with custom CSS variables:
+Template files are provided for both light and dark themes with complete Bootstrap button definitions:
 
-1. Create a new CSS file in `src/media/css/colors/light/` or `src/media/css/colors/dark/`
-2. Define CSS variables following the pattern in `colors_standard.css`
-3. Use Joomla's template settings (System → Site Templates → MokoCassiopeia → Custom Code tab) to load your custom CSS
+### Available Templates
 
-**Reference**: See [CSS Variables Documentation](../docs/CSS_VARIABLES.md) for complete variable reference.
+| File | Theme | Description |
+|------|-------|-------------|
+| `colors_custom_light.css` | Light | Custom light theme with all Bootstrap button variants |
+| `colors_custom_dark.css` | Dark | Custom dark theme with all Bootstrap button variants |
+
+### Using Custom Color Templates
+
+1. **Copy** the template file to your template's CSS directory:
+   ```bash
+   # For light theme
+   cp templates/colors_custom_light.css src/media/css/colors/light/colors_custom.css
+   
+   # For dark theme
+   cp templates/colors_custom_dark.css src/media/css/colors/dark/colors_custom.css
+   ```
+
+2. **Customize** the CSS variables in your copied file:
+   - Modify `--color-primary`, `--accent-color-primary`, etc. to match your brand
+   - Adjust Bootstrap state colors (`--success`, `--info`, `--warning`, `--danger`)
+   - Update button variants if needed
+
+3. **Register** in `src/joomla.asset.json`:
+   - Ensure `template.light.colors_custom` and `template.dark.colors_custom` assets are defined
+   - Already configured by default in the asset manifest
+
+4. **Activate** via Joomla admin:
+   - Go to System → Site Templates → MokoCassiopeia
+   - Select "Custom" in the Color Palette dropdown
+   - Save and check your site
+
+### Bootstrap Button Variants Included
+
+All template files include complete definitions for:
+
+**Solid Buttons:**
+- `.btn-primary`, `.btn-secondary`, `.btn-success`, `.btn-info`, `.btn-warning`, `.btn-danger`, `.btn-light`, `.btn-dark`
+
+**Outline Buttons:**
+- `.btn-outline-primary`, `.btn-outline-secondary`, `.btn-outline-success`, `.btn-outline-info`, `.btn-outline-warning`, `.btn-outline-danger`, `.btn-outline-light`, `.btn-outline-dark`
+
+Each button variant includes hover, active, focus, and disabled states using CSS variables.
+
+## Color System Features
+
+### CSS Variable Structure
+
+Colors are defined as CSS variables allowing easy customization:
+
+```css
+:root[data-bs-theme="light"] {
+  --color-primary: #0066cc;
+  --accent-color-primary: #3399ff;
+  --success: #28a745;
+  --danger: #dc3545;
+  /* ...and many more */
+}
+```
+
+### Opacity Utilities
+
+Template includes opacity utility variables for creating translucent colors:
+
+```css
+--opacity-5: 0.05;
+--opacity-10: 0.1;
+--opacity-15: 0.15;
+--opacity-25: 0.25;
+--opacity-50: 0.5;
+--opacity-75: 0.75;
+--opacity-100: 1;
+```
+
+Use with rgba():
+```css
+background-color: rgba(var(--black-rgb), var(--opacity-10));
+```
+
+### Shadow Color Utilities
+
+Pre-defined shadow color variables:
+
+```css
+--shadow-color-light: rgba(var(--black-rgb), var(--opacity-15));
+--shadow-color-medium: rgba(var(--black-rgb), var(--opacity-25));
+--shadow-color-dark: rgba(var(--black-rgb), var(--opacity-30));
+```
 
 ---