MokoConsulting/MokoCassiopeia
1
1
Fork 0
Code Issues 2 Pull Requests Actions Packages Releases 1 Activity

Add automated client fork creation workflow #79

Merged
Copilot merged 7 commits from copilot/create-readme-template into main 2026-02-20 02:00:06 +00:00
Conversation 4 Commits 7 Files Changed 8 +1277 -6
8 changed files with 1277 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
.github/workflows/create-client-fork.yml vendored Normal file
View File

@@ -0,0 +1,152 @@
---
github-advanced-security[bot] commented 2026-02-20 01:38:49 +00:00 (Migrated from github.com)
Review
Copy Link

Workflow does not contain permissions

Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {{contents: read}}

Show more details

## Workflow does not contain permissions Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {{contents: read}} [Show more details](https://github.com/mokoconsulting-tech/MokoCassiopeia/security/code-scanning/1)
github-advanced-security[bot] commented 2026-02-20 01:40:22 +00:00 (Migrated from github.com)
Review
Copy Link

Workflow does not contain permissions

Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {{contents: read}}

Show more details

## Workflow does not contain permissions Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {{contents: read}} [Show more details](https://github.com/mokoconsulting-tech/MokoCassiopeia/security/code-scanning/2)
# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
#
# SPDX-License-Identifier: GPL-3.0-or-later
#
# GitHub Actions Workflow: Create Client Fork Implementation
name: Create Client Fork
"on":
workflow_dispatch:
inputs:
client_name:
description: 'Client Name (e.g., "Acme Corporation")'
required: true
type: string
confirm:
description: 'Type "CONFIRM" to proceed'
required: true
type: string
jobs:
create-fork:
name: Setup Client Fork
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Validate confirmation
if: ${{ inputs.confirm != 'CONFIRM' }}
run: |
echo "::error::Type CONFIRM to proceed"
exit 1
- name: Checkout repository
uses: actions/checkout@v4
with:
token: ${{ secrets.GITHUB_TOKEN }}
- name: Setup Git
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- name: Create client fork branch
run: |
CLIENT_NAME="${{ inputs.client_name }}"
CLIENT_SLUG=$(echo "${CLIENT_NAME}" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:46 +00:00 (Migrated from github.com)
Review
Copy Link

CLIENT_SLUG is derived only by lowercasing and replacing spaces. Client names containing characters like /, &, ., or multiple whitespace can produce invalid git branch names (and could also lead to awkward paths in automation output). Consider sanitizing to [a-z0-9-], collapsing runs of -, and trimming leading/trailing dashes before forming BRANCH_NAME.

          CLIENT_SLUG=$(
            printf '%s' "${CLIENT_NAME}" \
              | tr '[:upper:]' '[:lower:]' \
              | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
          )
`CLIENT_SLUG` is derived only by lowercasing and replacing spaces. Client names containing characters like `/`, `&`, `.`, or multiple whitespace can produce invalid git branch names (and could also lead to awkward paths in automation output). Consider sanitizing to `[a-z0-9-]`, collapsing runs of `-`, and trimming leading/trailing dashes before forming `BRANCH_NAME`. ```suggestion CLIENT_SLUG=$( printf '%s' "${CLIENT_NAME}" \ | tr '[:upper:]' '[:lower:]' \ | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' ) ```
BRANCH_NAME="client-fork/${CLIENT_SLUG}"
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:47 +00:00 (Migrated from github.com)
Review
Copy Link

git checkout -b "${BRANCH_NAME}" will fail if the branch already exists (e.g., reruns for the same client). Consider adding an explicit existence check and emitting a clear ::error:: message (or switching to git checkout -B if overwriting is acceptable) so the failure mode is predictable.

          BRANCH_NAME="client-fork/${CLIENT_SLUG}"
          if git rev-parse --verify "${BRANCH_NAME}" >/dev/null 2>&1; then
            echo "::error::Branch ${BRANCH_NAME} already exists. Aborting to avoid overwriting existing client fork."
            exit 1
          fi
`git checkout -b "${BRANCH_NAME}"` will fail if the branch already exists (e.g., reruns for the same client). Consider adding an explicit existence check and emitting a clear `::error::` message (or switching to `git checkout -B` if overwriting is acceptable) so the failure mode is predictable. ```suggestion BRANCH_NAME="client-fork/${CLIENT_SLUG}" if git rev-parse --verify "${BRANCH_NAME}" >/dev/null 2>&1; then echo "::error::Branch ${BRANCH_NAME} already exists. Aborting to avoid overwriting existing client fork." exit 1 fi ```
git checkout -b "${BRANCH_NAME}"
echo "BRANCH_NAME=${BRANCH_NAME}" >> $GITHUB_ENV
echo "CLIENT_SLUG=${CLIENT_SLUG}" >> $GITHUB_ENV
- name: Copy custom color templates
run: |
echo "Copying colors_custom.css..."
cp templates/colors_custom.css src/media/css/colors/light/colors_custom.css
cp templates/colors_custom.css src/media/css/colors/dark/colors_custom.css
if [ -f "src/media/css/colors/light/colors_custom.css" ]; then
echo "✓ Created light mode colors_custom.css"
else
echo "::error::Failed to create light mode colors_custom.css"
exit 1
fi
if [ -f "src/media/css/colors/dark/colors_custom.css" ]; then
echo "✓ Created dark mode colors_custom.css"
else
echo "::error::Failed to create dark mode colors_custom.css"
exit 1
fi
- name: Replace README with client fork README
run: |
echo "Replacing README.md..."
sed "s/\[CLIENT NAME\]/${{ inputs.client_name }}/g" CLIENT_FORK_README.md > README.md
CURRENT_DATE=$(date +"%Y-%m-%d")
sed -i "s/\[DATE\]/${CURRENT_DATE}/g" README.md
sed -i "s/\[YOUR-FORK-URL\]/https:\/\/github.com\/${GITHUB_REPOSITORY}/g" README.md
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:48 +00:00 (Migrated from github.com)
Review
Copy Link

The sed replacement uses the raw inputs.client_name as the replacement string. If the client name contains characters meaningful to sed replacements (e.g., &, /, or backslashes), README generation can break or produce incorrect output. Escape the replacement string before substituting, or use a tool/approach that safely handles arbitrary text.

The sed replacement uses the raw `inputs.client_name` as the replacement string. If the client name contains characters meaningful to sed replacements (e.g., `&`, `/`, or backslashes), README generation can break or produce incorrect output. Escape the replacement string before substituting, or use a tool/approach that safely handles arbitrary text.
echo "✓ README.md replaced"
- name: Clean up template files
run: |
echo "Removing template files..."
if [ -f "CLIENT_FORK_README.md" ]; then
rm CLIENT_FORK_README.md
echo "✓ Removed CLIENT_FORK_README.md"
fi
if [ -f "templates/CLIENT_FORK_README_TEMPLATE.md" ]; then
rm templates/CLIENT_FORK_README_TEMPLATE.md
echo "✓ Removed templates/CLIENT_FORK_README_TEMPLATE.md"
fi
if [ -f "templates/README.md" ]; then
sed -i '/CLIENT_FORK_README_TEMPLATE.md/d' templates/README.md
sed -i '/Client Fork README Template/,/^---$/d' templates/README.md
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:47 +00:00 (Migrated from github.com)
Review
Copy Link

The workflow removes CLIENT_FORK_README.md but the templates/README.md edits only remove the client fork template section. templates/README.md still contains links/instructions pointing to ../CLIENT_FORK_README.md, which will be broken after deletion. Update the cleanup step to remove or rewrite all references to files that are deleted in the fork branch.

            sed -i '/Client Fork README Template/,/^---$/d' templates/README.md
            sed -i '/CLIENT_FORK_README.md/d' templates/README.md
The workflow removes `CLIENT_FORK_README.md` but the `templates/README.md` edits only remove the client fork template section. `templates/README.md` still contains links/instructions pointing to `../CLIENT_FORK_README.md`, which will be broken after deletion. Update the cleanup step to remove or rewrite all references to files that are deleted in the fork branch. ```suggestion sed -i '/Client Fork README Template/,/^---$/d' templates/README.md sed -i '/CLIENT_FORK_README.md/d' templates/README.md ```
echo "✓ Updated templates/README.md"
fi
echo "✓ Keeping templates/colors_custom.css"
- name: Commit changes
run: |
git add .
git status
if git diff --staged --quiet; then
echo "No changes to commit"
else
git commit -m "Setup client fork for ${{ inputs.client_name }}" \
-m "Copied colors_custom.css to src/media/css/colors/" \
-m "Replaced README.md with CLIENT_FORK_README.md" \
-m "Removed CLIENT_FORK_README.md" \
-m "Removed templates/CLIENT_FORK_README_TEMPLATE.md" \
-m "Kept templates/colors_custom.css as template"
echo "✓ Changes committed"
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:46 +00:00 (Migrated from github.com)
Review
Copy Link

The custom color files you copy into src/media/css/colors/*/colors_custom.css are ignored by .gitignore, so git add . will not stage them and the fork branch won’t actually contain the generated color files. Force-add just those files (e.g., explicit git add -f <paths>), or adjust the workflow to temporarily override the ignore rules before committing.

The custom color files you copy into src/media/css/colors/*/colors_custom.css are ignored by .gitignore, so `git add .` will not stage them and the fork branch won’t actually contain the generated color files. Force-add just those files (e.g., explicit `git add -f <paths>`), or adjust the workflow to temporarily override the ignore rules before committing.
fi
- name: Push branch
run: |
git push origin "${BRANCH_NAME}"
echo "✓ Branch ${BRANCH_NAME} pushed"
- name: Summary
run: |
cat >> $GITHUB_STEP_SUMMARY << EOF
## Client Fork Setup Complete! 🎉
### Changes Applied
- ✓ Copied colors_custom.css to src/media/css/colors/
- ✓ Replaced README.md
- ✓ Removed CLIENT_FORK_README.md
- ✓ Removed templates/CLIENT_FORK_README_TEMPLATE.md
- ✓ Kept templates/colors_custom.css
### Next Steps
1. Review branch: \`${BRANCH_NAME}\`
2. Customize colors in src/media/css/colors/
3. Update README.md with client details
4. Create new repository for ${{ inputs.client_name }}
5. Push branch to new repository
### Branch Information
- **Branch**: \`${BRANCH_NAME}\`
- **Client**: ${{ inputs.client_name }}
EOF

455
CLIENT_FORK_README.md Normal file
View File

@@ -0,0 +1,455 @@
<!-- Copyright (C) 2026 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: ./CLIENT_FORK_README.md
VERSION: 03.06.03
BRIEF: Template README for client custom code forks
-->
# [CLIENT NAME] - MokoCassiopeia Custom Fork
**Custom Joomla Template Fork for [CLIENT NAME]**
This is a customized fork of the [MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia) Joomla template, tailored specifically for [CLIENT NAME]'s website.
> **💡 Tip**: This fork was likely created using the automated [Client Fork Workflow](./docs/CLIENT_FORK_WORKFLOW.md). If you're creating a new client fork, use the workflow for instant setup!
---
## 📋 About This Fork
This repository contains client-specific customizations built on top of the MokoCassiopeia template. The template provides a modern, lightweight enhancement layer for Joomla with advanced theming, Font Awesome 7, Bootstrap 5, and dark mode support.
### Customization Strategy
This fork maintains the following customizations:
- **Custom Color Schemes**: Brand-specific colors for light and dark modes
- **Custom Code**: Client-specific HTML, CSS, and JavaScript customizations
- **Configuration**: Pre-configured template settings for the client environment
All customizations are designed to be preserved when syncing with upstream MokoCassiopeia updates.
---
## 🚀 Quick Start
### Prerequisites
- **Joomla**: 4.4.x or 5.x
- **PHP**: 8.0 or higher
- **Git**: For version control and syncing with upstream
- **Local Development**: MAMP/XAMPP/Docker for local testing
### Installation for Development
1. **Clone this repository**:
```bash
git clone [YOUR-FORK-URL]
cd [YOUR-FORK-NAME]
```
2. **Set up upstream remote** (for syncing updates):
```bash
git remote add upstream https://github.com/mokoconsulting-tech/MokoCassiopeia.git
git fetch upstream
```
3. **Install into Joomla**:
- Copy the `src/` directory contents to your Joomla installation:
- `src/templates/` → `[joomla]/templates/`
- `src/media/` → `[joomla]/media/templates/site/mokocassiopeia/`
- `src/language/` → `[joomla]/language/`
- `src/administrator/language/` → `[joomla]/administrator/language/`
4. **Enable the template**:
- Log into Joomla admin
- Navigate to **System → Site Templates**
- Set **MokoCassiopeia** as the default template
---
## 🎨 Custom Branding & Colors
### Custom Color Schemes
This fork includes custom color schemes specific to [CLIENT NAME]'s brand:
**Location**:
- Light mode: `src/media/css/colors/light/colors_custom.css`
- Dark mode: `src/media/css/colors/dark/colors_custom.css`
**Note**: These files are gitignored in the upstream repository to prevent conflicts, but are tracked in this fork.
### Modifying Brand Colors
1. **Edit the custom color files**:
```bash
# Light mode colors
edit src/media/css/colors/light/colors_custom.css
# Dark mode colors
edit src/media/css/colors/dark/colors_custom.css
```
2. **Key variables to customize**:
```css
:root[data-bs-theme="light"] {
--color-primary: #YOUR-BRAND-COLOR;
--accent-color-primary: #YOUR-ACCENT-COLOR;
--color-link: #YOUR-LINK-COLOR;
--nav-bg-color: #YOUR-NAV-BG;
}
```
3. **Test your changes**:
- Clear Joomla cache: System → Clear Cache
- Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R)
- View your site in light and dark modes
### Available CSS Variables
For a complete reference of all customizable CSS variables, see the [CSS Variables Documentation](./docs/CSS_VARIABLES.md) in the upstream repository.
---
## 🔧 Custom Code Injection
### Using custom.php
The `src/templates/custom.php` file allows for custom PHP functions and HTML snippets:
**Location**: `src/templates/custom.php`
**Example Use Cases**:
- Custom helper functions
- Client-specific HTML snippets
- Custom console logging
- Integration code
**Example**:
```php
<?php
// Custom helper function
function console_log($output, $with_script_tags = true) {
$js_code = 'console.log(' . json_encode($output, JSON_HEX_TAG) . ');';
if ($with_script_tags) {
$js_code = '<script>' . $js_code . '</script>';
}
echo $js_code;
}
?>
<!--
Custom HTML code can be added here
-->
```
### Custom Code via Joomla Template Settings
You can also inject custom code via the Joomla admin interface:
1. Navigate to **System → Site Templates → MokoCassiopeia**
2. Go to the **Custom Code** tab
3. Add custom HTML/CSS/JS in:
- **Custom Head Start**: Injected at the beginning of `<head>`
- **Custom Head End**: Injected at the end of `<head>`
This approach is ideal for:
- Analytics tracking codes
- Custom meta tags
- External script includes
- Custom CSS snippets
---
## 🔄 Syncing with Upstream Updates
To keep your fork up-to-date with new features and bug fixes from the upstream MokoCassiopeia repository:
### 1. Fetch Upstream Changes
```bash
# Ensure upstream remote is configured
git remote -v
# If upstream is not listed, add it:
# git remote add upstream https://github.com/mokoconsulting-tech/MokoCassiopeia.git
# Fetch latest changes
git fetch upstream
```
### 2. Review Changes
```bash
# See what changed in upstream
git log HEAD..upstream/main --oneline
# Review the diff
git diff HEAD..upstream/main
```
### 3. Merge Upstream Changes
```bash
# Switch to your main branch
git checkout main
# Merge upstream changes
git merge upstream/main
# Or rebase (preserves cleaner history):
# git rebase upstream/main
```
### 4. Resolve Conflicts
If conflicts occur (typically in custom files):
1. **Check conflict status**:
```bash
git status
```
2. **Resolve conflicts manually** in your editor:
- Look for conflict markers: `<<<<<<<`, `=======`, `>>>>>>>`
- Keep your custom changes
- Remove conflict markers
3. **Complete the merge**:
```bash
git add .
git commit -m "Merge upstream updates and resolve conflicts"
```
### 5. Test After Merging
- Clear Joomla cache
- Test critical functionality:
- Homepage loads correctly
- Custom colors are preserved
- Dark mode toggle works
- Navigation functions properly
- Custom code still executes
### Protected Files
The following files contain your customizations and should be carefully reviewed during merges:
- `src/media/css/colors/light/colors_custom.css` (custom light mode colors)
- `src/media/css/colors/dark/colors_custom.css` (custom dark mode colors)
- `src/templates/custom.php` (custom PHP code)
- Template configuration (stored in Joomla database, not in files)
---
## 📦 Building & Deployment
### Creating a Template Package
To create an installable ZIP package of your customized template:
1. **Prepare the package**:
```bash
cd src
zip -r ../mokocassiopeia-[CLIENT-NAME]-[VERSION].zip . -x "*.git*" "*.DS_Store"
```
2. **Install via Joomla**:
- Upload the ZIP file via **System → Install → Extensions**
- Or manually copy files to the Joomla installation
### Deployment to Production
**Recommended Deployment Methods**:
1. **Via Joomla Extension Manager** (Easiest):
- Create a ZIP package as described above
- Upload via Joomla admin interface
- The template will automatically overwrite the existing installation
2. **Via FTP/SFTP**:
- Upload changed files directly to the server
- Clear Joomla cache after deployment
3. **Via Git** (Advanced):
- Push changes to a deployment branch
- Use Git hooks or CI/CD to deploy to production
- Ensure proper file permissions
**Post-Deployment Checklist**:
- [ ] Clear Joomla cache (System → Clear Cache)
- [ ] Test homepage
- [ ] Test navigation and menus
- [ ] Verify custom colors appear correctly
- [ ] Test dark mode toggle
- [ ] Check mobile responsiveness
- [ ] Verify analytics tracking (if enabled)
---
## 🛠 Local Development Setup
### Setting Up a Local Joomla Environment
1. **Install a local server stack**:
- **MAMP** (Mac/Windows): https://www.mamp.info/
- **XAMPP** (Cross-platform): https://www.apachefriends.org/
- **Docker**: https://github.com/joomla-docker/docker-joomla
2. **Install Joomla**:
- Download Joomla from https://downloads.joomla.org/
- Extract to your local server's web directory
- Follow the Joomla installation wizard
3. **Install this template**:
- Copy files from this repository to your Joomla installation
- Or upload the ZIP package via Joomla's Extension Manager
4. **Enable development mode**:
- Edit `configuration.php`:
```php
public $debug = '1';
public $error_reporting = 'maximum';
```
### Development Workflow
1. **Make changes** to template files in your local Joomla installation
2. **Test changes** in your browser
3. **Copy changes back** to this repository:
```bash
# From Joomla installation
cp [joomla]/templates/mokocassiopeia/* [repo]/src/templates/
cp [joomla]/media/templates/site/mokocassiopeia/css/* [repo]/src/media/css/
```
4. **Commit and push** to your fork
5. **Deploy** to staging/production when ready
### Quick Testing Commands
```bash
# Clear Joomla cache from command line
rm -rf [joomla]/cache/*
rm -rf [joomla]/administrator/cache/*
# Watch for CSS changes (if using a build tool)
# npm run watch
```
---
## 📝 Customization Checklist
Use this checklist when setting up or modifying your custom fork:
### Initial Setup
- [ ] Fork the MokoCassiopeia repository
- [ ] Update this README with client name and details
- [ ] Configure custom brand colors
- [ ] Test light and dark modes
- [ ] Add custom code if needed
- [ ] Configure template settings in Joomla
- [ ] Set up analytics tracking (if required)
- [ ] Test on multiple devices and browsers
### Ongoing Maintenance
- [ ] Sync with upstream periodically (monthly recommended)
- [ ] Review upstream changelog for breaking changes
- [ ] Test thoroughly after merging upstream updates
- [ ] Keep this README updated with customization notes
- [ ] Document any client-specific configurations
- [ ] Maintain backup before major updates
---
## 📚 Documentation Resources
### MokoCassiopeia Documentation
- **[Main README](https://github.com/mokoconsulting-tech/MokoCassiopeia/blob/main/README.md)** - Features and overview
- **[CSS Variables Reference](./docs/CSS_VARIABLES.md)** - Complete CSS customization guide
- **[Development Guide](./docs/JOOMLA_DEVELOPMENT.md)** - Development and testing
- **[Quick Start](./docs/QUICK_START.md)** - Quick setup guide
- **[Changelog](./CHANGELOG.md)** - Version history
### Joomla Resources
- **[Joomla Documentation](https://docs.joomla.org/)** - Official Joomla docs
- **[Joomla Templates](https://docs.joomla.org/J4.x:How_to_Create_a_Joomla_Template)** - Template development guide
- **[Cassiopeia Documentation](https://docs.joomla.org/J4.x:Cassiopeia)** - Parent template docs
---
## 🔒 Security & Best Practices
### Security Considerations
1. **Keep Joomla Updated**: Always run the latest stable Joomla version
2. **Update Dependencies**: Regularly sync with upstream MokoCassiopeia for security patches
3. **Secure Custom Code**: Review all custom code for security vulnerabilities
4. **Use HTTPS**: Always serve production sites over HTTPS
5. **Regular Backups**: Maintain regular backups of both files and database
### Best Practices
1. **Version Control**: Commit changes frequently with clear messages
2. **Testing**: Always test changes locally before deploying to production
3. **Documentation**: Document all customizations in this README
4. **Code Review**: Have changes reviewed before deploying to production
5. **Staging Environment**: Use a staging site to test updates before production
---
## 📞 Support & Contact
### Client-Specific Support
**Client Contact**: [CLIENT CONTACT INFO]
**Developer Contact**: [DEVELOPER CONTACT INFO]
**Hosting Provider**: [HOSTING INFO]
### Upstream MokoCassiopeia Support
- **Repository**: https://github.com/mokoconsulting-tech/MokoCassiopeia
- **Issues**: https://github.com/mokoconsulting-tech/MokoCassiopeia/issues
- **Documentation**: https://github.com/mokoconsulting-tech/MokoCassiopeia/blob/main/README.md
- **Moko Consulting**: https://mokoconsulting.tech
---
## 📄 License
This fork maintains the original GPL-3.0-or-later license from MokoCassiopeia.
- **MokoCassiopeia**: GPL-3.0-or-later
- **Client Customizations**: GPL-3.0-or-later (or as specified by client agreement)
- **Third-Party Libraries**: See [Included Libraries](https://github.com/mokoconsulting-tech/MokoCassiopeia#-included-libraries)
---
## 📊 Fork Information
- **Upstream Repository**: https://github.com/mokoconsulting-tech/MokoCassiopeia
- **Fork Repository**: [YOUR-FORK-URL]
- **Client**: [CLIENT NAME]
- **Created**: [DATE]
- **Last Synced with Upstream**: [DATE]
- **Current Version**: 03.06.03
---
## 🔄 Revision History
| Date | Version | Change Summary | Author |
|------|---------|----------------|--------|
| [DATE] | 03.06.03 | Initial fork setup with custom colors and branding | [YOUR NAME] |
---
**Maintained by [CLIENT NAME] / [DEVELOPER NAME]**

23
README.md
View File

@@ -328,9 +328,13 @@ See [Joomla Development Guide](./docs/JOOMLA_DEVELOPMENT.md) for packaging instr
### Customization Resources ### Customization Resources
- **[Template Files](./templates/)** - Ready-to-use color palette templates - **[Template Files](./templates/)** - Ready-to-use templates for customization
- `colors_custom_light.css` - Light mode template - `colors_custom.css` - Custom color palette template
- `colors_custom_dark.css` - Dark mode template - `CLIENT_FORK_README_TEMPLATE.md` - Template for client fork documentation
### Client Forks
- **[Client Fork Guide](./CLIENT_FORK_README.md)** - Comprehensive guide for creating and maintaining client custom code forks
### Governance ### Governance
@@ -398,6 +402,19 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu
See [Workflow Guide](./docs/WORKFLOW_GUIDE.md) for detailed Git workflow. See [Workflow Guide](./docs/WORKFLOW_GUIDE.md) for detailed Git workflow.
### Client Custom Forks
Creating a custom fork for client-specific branding and code?
**Quick Setup**: Use our automated workflow to create a client fork in minutes:
- **[Client Fork Workflow Guide](./docs/CLIENT_FORK_WORKFLOW.md)** - Automated GitHub Actions workflow or local bash script
**Comprehensive Guide**: See our [Client Fork Guide](./CLIENT_FORK_README.md) for:
- Setting up custom color schemes
- Maintaining fork-specific customizations
- Syncing with upstream updates
- Deployment workflows
--- ---
## 📦 Included Libraries ## 📦 Included Libraries

320
docs/CLIENT_FORK_WORKFLOW.md Normal file
View File

@@ -0,0 +1,320 @@
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
BRIEF: Documentation for client fork creation workflow
-->
# Client Fork Creation Workflow
This document explains how to use the automated client fork creation tools to set up a new client-specific fork of MokoCassiopeia.
---
## Overview
The client fork creation workflow automates the process of preparing a repository for a client-specific fork. It performs the following actions:
1. ✅ Copies `templates/colors_custom.css` to `src/media/css/colors/light/colors_custom.css`
2. ✅ Copies `templates/colors_custom.css` to `src/media/css/colors/dark/colors_custom.css`
3. ✅ Replaces `README.md` with customized `CLIENT_FORK_README.md`
4. ✅ Removes `CLIENT_FORK_README.md` from root
5. ✅ Removes `templates/CLIENT_FORK_README_TEMPLATE.md`
6. ✅ Updates `templates/README.md` to remove fork template references
7. ✅ Keeps `templates/colors_custom.css` as a template for reference
---
## Method 1: GitHub Actions Workflow (Recommended)
### Prerequisites
- Repository admin or maintainer access
- GitHub Actions enabled for the repository
### Steps
1. **Navigate to Actions**
- Go to your repository on GitHub
- Click on the "Actions" tab
2. **Run the Workflow**
- Select "Create Client Fork" from the workflow list
- Click "Run workflow"
- Fill in the required inputs:
- **Client Name**: Full client name (e.g., "Acme Corporation")
- **Confirm**: Type "CONFIRM" to proceed
- Click "Run workflow" button
3. **Monitor Progress**
- The workflow will create a new branch named `client-fork/{client-slug}`
- You can monitor the progress in the Actions tab
- Once complete, you'll see a summary of changes
4. **Review the Branch**
- Navigate to the new branch: `client-fork/{client-slug}`
- Review the changes made
- The README will be customized with the client name
- Custom color files will be in place
5. **Create Client Repository**
- Create a new repository for the client
- Push the branch to the new repository:
```bash
git remote add client-repo <CLIENT_REPO_URL>
git push client-repo client-fork/{client-slug}:main
```
### Workflow Features
- ✅ **Safe Confirmation**: Requires typing "CONFIRM" to prevent accidental runs
- ✅ **Automated Branch Creation**: Creates a properly named branch automatically
- ✅ **Customized README**: Automatically fills in client name and date
- ✅ **Git Tracking**: Commits all changes with a descriptive message
- ✅ **Summary Report**: Provides a complete summary of actions taken
---
## Method 2: Local Bash Script
### Prerequisites
- Git installed on your local machine
- Bash shell (Linux, macOS, or Git Bash on Windows)
- Local clone of the MokoCassiopeia repository
### Steps
1. **Clone the Repository**
```bash
git clone https://github.com/mokoconsulting-tech/MokoCassiopeia.git
cd MokoCassiopeia
```
2. **Make Script Executable**
```bash
chmod +x scripts/create-client-fork.sh
```
3. **Run the Script**
```bash
./scripts/create-client-fork.sh "Client Name"
```
Example:
```bash
./scripts/create-client-fork.sh "Acme Corporation"
```
4. **Confirm Actions**
- The script will show you what it will do
- Type "yes" to proceed
- Review the changes shown
- Type "yes" to commit
5. **Push to New Repository**
```bash
# Add the client's repository as a remote
git remote add client-repo <CLIENT_REPO_URL>
# Push the branch
git push client-repo client-fork/{client-slug}:main
```
### Script Features
- 🎨 **Colored Output**: Easy-to-read colored terminal output
- ✅ **Interactive Confirmation**: Asks for confirmation before making changes
- ✅ **Safety Checks**: Verifies you're in the correct directory
- ✅ **Progress Indicators**: Shows each step as it completes
- ✅ **Git Status**: Shows what files changed before committing
- ✅ **Summary**: Provides a complete summary at the end
---
## What Gets Changed
### Files Created
```
src/media/css/colors/light/colors_custom.css [NEW]
src/media/css/colors/dark/colors_custom.css [NEW]
```
### Files Modified
```
README.md [REPLACED]
templates/README.md [UPDATED]
```
### Files Removed
```
CLIENT_FORK_README.md [DELETED]
templates/CLIENT_FORK_README_TEMPLATE.md [DELETED]
```
### Files Kept
```
templates/colors_custom.css [UNCHANGED]
```
---
## Post-Setup Steps
After running the workflow or script, you should:
1. **Customize Brand Colors**
- Edit `src/media/css/colors/light/colors_custom.css`
- Edit `src/media/css/colors/dark/colors_custom.css`
- Update CSS variables to match client branding
2. **Update README**
- Fill in client-specific contact information
- Add custom notes or configurations
- Update fork URL references
3. **Test Locally**
- Install the template in a local Joomla instance
- Test light and dark modes
- Verify custom colors appear correctly
4. **Create Client Repository**
- Create a new repository for the client
- Push the prepared branch to the new repo
- Set up appropriate access controls
5. **Enable Custom Palette in Joomla**
- Log into Joomla admin
- Navigate to System → Site Templates → MokoCassiopeia
- Under Theme tab, set palette to "Custom"
- Save and test
---
## Troubleshooting
### Workflow Fails with "CONFIRM" Error
**Problem**: Workflow stops immediately with confirmation error.
**Solution**: Make sure you type "CONFIRM" (in all caps) in the confirmation field.
### Script Says "CLIENT_FORK_README.md not found"
**Problem**: Script can't find required files.
**Solution**: Make sure you're running the script from the repository root directory:
```bash
cd /path/to/MokoCassiopeia
./scripts/create-client-fork.sh "Client Name"
```
### Colors Don't Appear After Setup
**Problem**: Custom colors don't show in Joomla.
**Solution**:
1. Enable custom palette in template settings
2. Clear Joomla cache (System → Clear Cache)
3. Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R)
### Branch Already Exists
**Problem**: Branch name conflicts with existing branch.
**Solution**: Either delete the old branch or choose a different client name:
```bash
# Delete old branch
git branch -D client-fork/{client-slug}
# Or use a more specific client name
./scripts/create-client-fork.sh "Client Name - Division"
```
---
## Examples
### Example 1: Simple Client Fork
```bash
# Using the script
./scripts/create-client-fork.sh "Acme Corporation"
```
This creates:
- Branch: `client-fork/acme-corporation`
- README title: "Acme Corporation - MokoCassiopeia Custom Fork"
### Example 2: Client with Multiple Words
```bash
# Using the script
./scripts/create-client-fork.sh "Global Tech Solutions Inc"
```
This creates:
- Branch: `client-fork/global-tech-solutions-inc`
- README title: "Global Tech Solutions Inc - MokoCassiopeia Custom Fork"
### Example 3: Using GitHub Actions
1. Go to Actions → Create Client Fork
2. Enter: "Mountain View Medical Center"
3. Enter: "CONFIRM"
4. Click "Run workflow"
Result:
- Branch: `client-fork/mountain-view-medical-center`
- README title: "Mountain View Medical Center - MokoCassiopeia Custom Fork"
---
## Best Practices
1. **Naming Convention**: Use the official client name as it should appear in documentation
2. **Branch Management**:
- Keep the branch until the client repository is set up
- Don't merge client fork branches back to main
3. **Custom Colors**:
- Document color choices in README
- Keep a backup of custom color files
- Test in both light and dark modes
4. **Version Tracking**:
- Note the upstream version in fork README
- Track when you last synced with upstream
5. **Security**:
- Don't commit client-specific credentials
- Review custom code before deployment
- Keep client forks private if they contain sensitive branding
---
## Related Documentation
- **[CLIENT_FORK_README.md](../CLIENT_FORK_README.md)** - Full client fork guide
- **[CSS Variables](../docs/CSS_VARIABLES.md)** - Complete CSS variable reference
- **[Main README](../README.md)** - MokoCassiopeia documentation
---
## Support
For issues with the workflow or script:
- Check this documentation first
- Review error messages carefully
- Contact: hello@mokoconsulting.tech
---
**Document Version**: 1.0
**Last Updated**: 2026-02-20
**Maintained by**: Moko Consulting

27
docs/README.md
View File

@@ -70,6 +70,21 @@ This directory contains comprehensive documentation for the MokoCassiopeia Jooml
For end-user documentation, installation instructions, and feature guides, see the main [README.md](../README.md) in the repository root. For end-user documentation, installation instructions, and feature guides, see the main [README.md](../README.md) in the repository root.
### Client Fork Documentation
* **[Client Fork Workflow](CLIENT_FORK_WORKFLOW.md)** - Automated client fork creation
* GitHub Actions workflow for instant fork setup
* Local bash script alternative
* Complete setup automation in minutes
* Post-setup customization guide
* **[Client Fork Guide](../CLIENT_FORK_README.md)** - Comprehensive guide for client custom code forks
* Setting up custom branding and colors
* Maintaining fork-specific customizations
* Syncing with upstream MokoCassiopeia
* Deployment and development workflows
* Template README for client forks
## Project Structure ## Project Structure
``` ```
@@ -83,11 +98,17 @@ moko-cassiopeia/
│ └── ROADMAP.md # Version-specific roadmap │ └── ROADMAP.md # Version-specific roadmap
├── src/ # Template source code ├── src/ # Template source code
│ ├── templates/ # Joomla template files │ ├── templates/ # Joomla template files
│ └── media/ # Assets (CSS, JS, images) │ ├── media/ # Assets (CSS, JS, images)
│ │ └── css/colors/ # Color schemes (light/dark subdirectories)
│ │ ├── light/ # Light mode color files (colors_custom.css)
│ │ └── dark/ # Dark mode color files (colors_custom.css)
│ └── language/ # Translation files
├── templates/ # Template files for customization ├── templates/ # Template files for customization
│ ├── colors_custom_light.css # Light mode color template │ ├── colors_custom.css # Custom color palette template (copy to src/media/css/colors/)
│ └── colors_custom_dark.css # Dark mode color template │ ├── CLIENT_FORK_README_TEMPLATE.md # Template for client fork docs
│ └── README.md # Guide to using templates
├── tests/ # Automated tests ├── tests/ # Automated tests
├── CLIENT_FORK_README.md # Client fork guide
└── .github/ # GitHub configuration and workflows └── .github/ # GitHub configuration and workflows
``` ```

168
scripts/create-client-fork.sh Executable file
View File

@@ -0,0 +1,168 @@
#!/bin/bash
# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
#
# SPDX-License-Identifier: GPL-3.0-or-later
#
# Script: Create Client Fork Setup
# This script prepares the repository for a client-specific fork by:
# - Copying custom color templates to the appropriate locations
# - Replacing the main README with the client fork README
# - Cleaning up template documentation files
set -e
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Function to print colored output
print_success() { echo -e "${GREEN}✓${NC} $1"; }
print_error() { echo -e "${RED}✗${NC} $1"; }
print_info() { echo -e "${BLUE}ℹ${NC} $1"; }
print_warning() { echo -e "${YELLOW}⚠${NC} $1"; }
# Check if client name is provided
if [ -z "$1" ]; then
print_error "Usage: $0 <CLIENT_NAME>"
echo "Example: $0 \"Acme Corporation\""
exit 1
fi
CLIENT_NAME="$1"
CLIENT_SLUG=$(echo "${CLIENT_NAME}" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:47 +00:00 (Migrated from github.com)
Review
Copy Link

CLIENT_SLUG only lowercases and replaces spaces, so client names with punctuation or characters like / can generate invalid git branch names. Sanitize the slug to an allowlist (e.g., [a-z0-9-]), collapse repeated -, and trim leading/trailing dashes before creating BRANCH_NAME.

CLIENT_SLUG=$(echo "${CLIENT_NAME}" \
    | tr '[:upper:]' '[:lower:]' \
    | sed -e 's/[^a-z0-9]/-/g' \
          -e 's/-\{2,\}/-/g' \
          -e 's/^-//' \
          -e 's/-$//')

if [ -z "${CLIENT_SLUG}" ]; then
    print_error "Client name '${CLIENT_NAME}' results in an empty slug after sanitization."
    exit 1
fi
`CLIENT_SLUG` only lowercases and replaces spaces, so client names with punctuation or characters like `/` can generate invalid git branch names. Sanitize the slug to an allowlist (e.g., `[a-z0-9-]`), collapse repeated `-`, and trim leading/trailing dashes before creating `BRANCH_NAME`. ```suggestion CLIENT_SLUG=$(echo "${CLIENT_NAME}" \ | tr '[:upper:]' '[:lower:]' \ | sed -e 's/[^a-z0-9]/-/g' \ -e 's/-\{2,\}/-/g' \ -e 's/^-//' \ -e 's/-$//') if [ -z "${CLIENT_SLUG}" ]; then print_error "Client name '${CLIENT_NAME}' results in an empty slug after sanitization." exit 1 fi ```
BRANCH_NAME="client-fork/${CLIENT_SLUG}"
echo ""
echo "╔════════════════════════════════════════════════════════════════╗"
echo "║ MokoCassiopeia - Client Fork Setup Script ║"
echo "╚════════════════════════════════════════════════════════════════╝"
echo ""
print_info "Client Name: ${CLIENT_NAME}"
print_info "Branch Name: ${BRANCH_NAME}"
echo ""
# Confirm before proceeding
read -p "Do you want to proceed? (yes/no): " -r
echo
if [[ ! $REPLY =~ ^[Yy]es$ ]]; then
print_warning "Operation cancelled by user"
exit 0
fi
# Check if we're in the right directory
if [ ! -f "CLIENT_FORK_README.md" ]; then
print_error "CLIENT_FORK_README.md not found. Are you in the repository root?"
exit 1
fi
# Create new branch
print_info "Creating branch: ${BRANCH_NAME}"
git checkout -b "${BRANCH_NAME}"
print_success "Branch created"
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:46 +00:00 (Migrated from github.com)
Review
Copy Link

The script creates a new branch immediately, but it doesn’t verify the working tree is clean first. If the user has unrelated local changes, they may be unintentionally carried into the client fork branch/commit. Consider failing early when git status --porcelain is non-empty (and/or stage only the specific expected files rather than git add .).

The script creates a new branch immediately, but it doesn’t verify the working tree is clean first. If the user has unrelated local changes, they may be unintentionally carried into the client fork branch/commit. Consider failing early when `git status --porcelain` is non-empty (and/or stage only the specific expected files rather than `git add .`).
# Copy custom color templates
print_info "Copying colors_custom.css to light and dark mode directories..."
cp templates/colors_custom.css src/media/css/colors/light/colors_custom.css
cp templates/colors_custom.css src/media/css/colors/dark/colors_custom.css
if [ -f "src/media/css/colors/light/colors_custom.css" ] && [ -f "src/media/css/colors/dark/colors_custom.css" ]; then
print_success "Created src/media/css/colors/light/colors_custom.css"
print_success "Created src/media/css/colors/dark/colors_custom.css"
else
print_error "Failed to create colors_custom.css files"
exit 1
fi
# Replace README with client fork README
print_info "Replacing README.md with CLIENT_FORK_README.md..."
sed "s/\[CLIENT NAME\]/${CLIENT_NAME}/g" CLIENT_FORK_README.md > README.md.new
mv README.md.new README.md
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:48 +00:00 (Migrated from github.com)
Review
Copy Link

The sed replacement uses ${CLIENT_NAME} unescaped as the replacement string. Names containing &, /, or backslashes can break the substitution or yield incorrect README content. Escape the replacement string (and ideally use a delimiter that avoids common characters) before running sed.

The sed replacement uses `${CLIENT_NAME}` unescaped as the replacement string. Names containing `&`, `/`, or backslashes can break the substitution or yield incorrect README content. Escape the replacement string (and ideally use a delimiter that avoids common characters) before running sed.
# Update fork information section
CURRENT_DATE=$(date +"%Y-%m-%d")
sed -i.bak "s/\[DATE\]/${CURRENT_DATE}/g" README.md
sed -i.bak "s/\[YOUR-FORK-URL\]/[UPDATE-WITH-YOUR-FORK-URL]/g" README.md
rm -f README.md.bak
print_success "README.md replaced with customized client fork README"
# Clean up template files
print_info "Removing template documentation files..."
if [ -f "CLIENT_FORK_README.md" ]; then
rm CLIENT_FORK_README.md
print_success "Removed CLIENT_FORK_README.md"
fi
if [ -f "templates/CLIENT_FORK_README_TEMPLATE.md" ]; then
rm templates/CLIENT_FORK_README_TEMPLATE.md
print_success "Removed templates/CLIENT_FORK_README_TEMPLATE.md"
fi
# Update templates/README.md
if [ -f "templates/README.md" ]; then
# Create a backup
cp templates/README.md templates/README.md.bak
# Remove references to CLIENT_FORK_README_TEMPLATE.md
sed '/CLIENT_FORK_README_TEMPLATE.md/d' templates/README.md > templates/README.md.tmp
mv templates/README.md.tmp templates/README.md
rm -f templates/README.md.bak
print_success "Updated templates/README.md"
fi
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:48 +00:00 (Migrated from github.com)
Review
Copy Link

This update to templates/README.md only deletes lines containing CLIENT_FORK_README_TEMPLATE.md, which will leave an incomplete/broken section (headings and instructions remain but the referenced file is deleted). Match the workflow behavior by removing the entire client-fork template section and any other references to files you delete during setup.

This update to `templates/README.md` only deletes lines containing `CLIENT_FORK_README_TEMPLATE.md`, which will leave an incomplete/broken section (headings and instructions remain but the referenced file is deleted). Match the workflow behavior by removing the entire client-fork template section and any other references to files you delete during setup.
print_success "Keeping templates/colors_custom.css as template"
# Show git status
echo ""
print_info "Git status:"
git status --short
# Commit changes
echo ""
read -p "Commit these changes? (yes/no): " -r
echo
if [[ $REPLY =~ ^[Yy]es$ ]]; then
git add .
git commit -m "Setup client fork for ${CLIENT_NAME}
- Copied colors_custom.css to src/media/css/colors/light/ and dark/
- Replaced README.md with customized CLIENT_FORK_README.md
- Removed CLIENT_FORK_README.md and templates/CLIENT_FORK_README_TEMPLATE.md
- Kept templates/colors_custom.css as template
This commit prepares the repository for ${CLIENT_NAME}'s custom fork."
copilot-pull-request-reviewer[bot] commented 2026-02-20 02:07:47 +00:00 (Migrated from github.com)
Review
Copy Link

The custom color files copied into src/media/css/colors/{light,dark}/colors_custom.css are ignored by this repo’s .gitignore, so git add . will not stage them. If the goal is for client forks to track these files, force-add those specific paths (or modify ignore rules as part of the fork setup) before committing.

The custom color files copied into `src/media/css/colors/{light,dark}/colors_custom.css` are ignored by this repo’s `.gitignore`, so `git add .` will not stage them. If the goal is for client forks to track these files, force-add those specific paths (or modify ignore rules as part of the fork setup) before committing.
print_success "Changes committed successfully"
echo ""
print_info "To push this branch, run:"
echo " git push origin ${BRANCH_NAME}"
fi
# Summary
echo ""
echo "╔════════════════════════════════════════════════════════════════╗"
echo "║ Setup Complete! 🎉 ║"
echo "╚════════════════════════════════════════════════════════════════╝"
echo ""
echo "Changes Applied:"
print_success "Copied colors_custom.css to src/media/css/colors/light/"
print_success "Copied colors_custom.css to src/media/css/colors/dark/"
print_success "Replaced README.md with customized client fork README"
print_success "Removed CLIENT_FORK_README.md"
print_success "Removed templates/CLIENT_FORK_README_TEMPLATE.md"
print_success "Kept templates/colors_custom.css as template"
echo ""
echo "Next Steps:"
echo "1. Review the changes in branch: ${BRANCH_NAME}"
echo "2. Customize colors in src/media/css/colors/light/colors_custom.css"
echo "3. Customize colors in src/media/css/colors/dark/colors_custom.css"
echo "4. Update README.md with client-specific details"
echo "5. Create a new repository for ${CLIENT_NAME}"
echo "6. Push this branch to the new repository"
echo ""

57
templates/CLIENT_FORK_README_TEMPLATE.md Normal file
View File

@@ -0,0 +1,57 @@
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
BRIEF: Quick template README for client custom code forks
-->
# [CLIENT NAME] - MokoCassiopeia Custom
Custom Joomla template fork for **[CLIENT NAME]**.
---
## 🎨 Custom Branding
**Brand Colors**:
- Primary: `[COLOR]`
- Accent: `[COLOR]`
- Background: `[COLOR]`
**Custom Files**:
- Light mode colors: `src/media/css/colors/light/colors_custom.css`
- Dark mode colors: `src/media/css/colors/dark/colors_custom.css`
- Custom PHP code: `src/templates/custom.php`
---
## 🔄 Syncing with Upstream
```bash
# Add upstream remote (first time only)
git remote add upstream https://github.com/mokoconsulting-tech/MokoCassiopeia.git
# Sync with upstream
git fetch upstream
git merge upstream/main
```
---
## 📚 Documentation
- **Full Client Fork Guide**: [CLIENT_FORK_README.md](../CLIENT_FORK_README.md)
- **MokoCassiopeia Docs**: https://github.com/mokoconsulting-tech/MokoCassiopeia
- **CSS Variables**: [docs/CSS_VARIABLES.md](../docs/CSS_VARIABLES.md)
---
## 📝 Quick Notes
[Add your client-specific notes here]
---
**Fork of**: [MokoCassiopeia](https://github.com/mokoconsulting-tech/MokoCassiopeia) v03.06.03
**Last Synced**: [DATE]
**Contact**: [CONTACT INFO]

81
templates/README.md Normal file
View File

@@ -0,0 +1,81 @@
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
BRIEF: Template files directory README
-->
# MokoCassiopeia Template Files
This directory contains template files for client customizations and custom code forks.
---
## 📁 Available Templates
### Custom Color Scheme Template
**File**: `colors_custom.css`
A comprehensive template for creating custom color schemes. This template includes all CSS variables used by MokoCassiopeia for both light and dark modes.
**Usage**:
1. Copy this file to either:
- `src/media/css/colors/light/colors_custom.css` (for light mode)
- `src/media/css/colors/dark/colors_custom.css` (for dark mode)
2. Customize the CSS variables to match your brand colors
3. Enable in Joomla: System → Site Templates → MokoCassiopeia → Theme tab
4. Set the appropriate palette to "Custom"
**Reference**: See [CSS Variables Documentation](../docs/CSS_VARIABLES.md) for complete variable reference.
---
### Client Fork README Template
**File**: `CLIENT_FORK_README_TEMPLATE.md`
A simplified README template for client-specific forks. Use this as a starting point for documenting your customizations.
**Usage**:
1. Copy this file to the root of your fork repository as `README.md`
2. Replace `[CLIENT NAME]` with your client's name
3. Fill in brand colors and contact information
4. Add client-specific notes and configurations
**For Comprehensive Fork Setup**: See [CLIENT_FORK_README.md](../CLIENT_FORK_README.md) for the complete client fork guide.
---
## 🎯 When to Use These Templates
### Creating a Client Fork
If you're creating a custom fork of MokoCassiopeia for a specific client:
1. **Start with the full guide**: Read [CLIENT_FORK_README.md](../CLIENT_FORK_README.md)
2. **Set up custom colors**: Use `colors_custom.css` as your starting point
3. **Document your fork**: Copy `CLIENT_FORK_README_TEMPLATE.md` to your fork
### Custom Colors Only
If you just need custom colors without forking:
1. Use the `colors_custom.css` template
2. Follow the instructions in the [main README](../README.md#custom-color-palettes)
3. Enable custom palette in Joomla template settings
---
## 📚 Additional Resources
- **[Main README](../README.md)** - MokoCassiopeia features and installation
- **[Client Fork Guide](../CLIENT_FORK_README.md)** - Complete guide for client forks
- **[CSS Variables Reference](../docs/CSS_VARIABLES.md)** - All available CSS variables
- **[Development Guide](../docs/JOOMLA_DEVELOPMENT.md)** - Development workflows
---
**Template Directory**: `/templates/`
**Version**: 03.06.03
**Maintained by**: Moko Consulting