mcugen: Material Color Theme Generator 🖌️

mcugen is a CLI tool that generates Material Design color palettes and themes. It allows you to create, template, and deploy color schemes based on images or base colors—perfect for those who want to customize themes for apps, dotfiles, or other resources with easy automation.

---

What Does mcugen Do?

• Extracts Material color palettes from images or hex colors
• Generates dark and light Material color schemes
• Renders templates with Material colors for easy integration
• Supports pre/post hooks and directory-based target management
• Prevents unsafe usage (running as root, invalid paths, etc.)
• Checks for updates automatically

---

Core Features Overview

Feature	Description
🎨 Material Colors	Uses Google's Material Color Utilities for extracting palettes
🖼️ Image Support	Extracts dominant color from your image for theme generation
🏷️ Hex Support	Accepts a single base color (hex) for theme generation
🛠️ Template Engine	Renders output files using customizable templates and color variables
🔐 Safety	Ensures output is always inside your $HOME, never runs as root
🔄 Update Check	Notifies you if a new version is available
🧩 Hooks	Runs pre/post shell scripts for custom automation
📁 Targets	Supports multiple independent targets, each with its own template

---

Installation

Install globally from npm:

npm install -g mcugen

---

CLI Usage

mcugen --mode <dark|light> --image <path>
mcugen --mode <dark|light> --color <hex>

Options

Option	Description
--mode	dark or light (required)
--image	Path to image file to extract colors from
--color	Base color in hex format (e.g., #2196f3)
--help	Show help message

Examples

mcugen --mode dark --image ~/Pictures/wallpaper.png
mcugen --mode light --color "#00bcd4"

---

How It Works

• Step 1: Parses CLI arguments for mode and input (image or color).
• Step 2: Extracts the source color palette (via image quantization or color).
• Step 3: Generates Material Design color schemes (dark and light).
• Step 4: Saves generated color schemes as ~/.config/mcugen/colors.json.
• Step 5: Renders templates in target directories using the generated schemes.
• Step 6: Runs pre- and post-generation hooks if present.

---

Directory Structure

By default, mcugen uses the following structure in your home directory:

~/.config/mcugen/
├── colors.json            # Generated Material color schemes
└── targets/
    ├── <target1>/
    │   ├── template       # Template file for rendering
    │   ├── pre            # (Optional) Pre-generation hook
    │   └── post           # (Optional) Post-generation hook
    └── <target2>/
        └── ...

---

Template Rendering

Templates support Mustache-like variable interpolation and conditional expressions:

• Use {{ light.primary.hex }} to get the hex for the primary color in the light scheme.
• Use {{ dark.background.rgb }} for RGB of background in dark mode.
• Use conditional: {{ value1 | value2 }} — renders value1 if mode is light, value2 if dark.

Template Example

background: {{ light.background.hex }};
foreground: {{ dark.onBackground.hex }};
primary:    {{ light.primary.hex | dark.primary.hex }};

---

Target System

• Each subdirectory in targets/ represents an independent target.
• Each must contain a template file.
• Optional pre and post scripts run before and after rendering.
• Output file is placed in the same relative path inside your $HOME.

---

Material Color Generation Logic

• Image: Uses sharp to resize and extract RGB pixels, then Google's material-color-utilities to quantize and score colors.
• Hex Color: Directly generates theme from provided color.
• Both: Produces "light" and "dark" schemes containing all Material color roles.

---

Template Variable Reference

Color objects for both schemes expose several formats:

Format	Example	Description
.hex	#2196f3	Standard hex
.hex_stripped	2196f3	Hex without #
.hex_argb	#ff2196f3	ARGB hex
.rgb	rgb(33,150,243)	CSS RGB
.rgba	rgba(33,150,243,1.0)	CSS RGBA
.r, .g, .b, .a	33	Numeric components
.argb_int	e.g. 4281558687	Integer representation

---

Error Handling

• Root User: Refuses to run as root for safety.
• Invalid Output Path: Ensures templates can't write outside of $HOME.
• Template Errors: Catches missing variables or syntax errors.
• File System: Fully synchronous and atomic; errors out on failure.

---

Update Checks

Each run (if network available) checks for the latest version on GitHub. If an update is found, you'll get a clear, friendly notice with upgrade instructions.

---

Detailed Function List

Function	Purpose
ensureNotRoot	Prevents execution as root user
isNewerVersion	Compares semantic version strings
checkForUpdates	Fetches latest version and notifies if outdated
init	Initializes config/targets directories
help	Displays help message
parseArgs	Parses arguments and validates input
argbToFormats	Converts ARGB int to multiple color formats
getImagePixels	Extracts RGB pixel values from an image
generateFromImage	Generates theme from image colors
generateFromColor	Generates theme from a hex color
extractSchemes	Builds color role tables for light/dark schemes
generateMaterialTheme	Orchestrates theme generation and metadata
writeColorsJson	Saves color theme to file
loadColors	Loads color theme from file
renderTemplate	Renders templates with the theme context
resolveSingle	Resolves a template variable expression
resolveOutputPath	Calculates safe output file path
assertInsideHome	Ensures path is inside user's home
runHook	Executes pre/post scripts if present
renderTargets	Handles all template rendering for all targets

---

Example Workflow

Suppose you want to update your terminal theme to match your wallpaper:

1. Place your template in ~/.config/mcugen/targets/.
2. Run:

   mcugen --mode dark --image ~/Pictures/wallpaper.png

3. mcugen:
   • Extracts the palette
   • Writes colors.json
   • Renders your template with new colors
   • Outputs to your $HOME directory

---

API Endpoints

mcugen is a CLI tool and does not expose a web API. All logic is local, synchronous, and filesystem-based. No API endpoints are present in the code.

---

Troubleshooting

• Not changing colors?
  Check your template for correct variable usage and ensure colors.json is updating.
• Permission denied?
  Make sure you're not running as root and have write permissions to your home directory.
• "no targets found"?
  Ensure you have at least one target directory with a template file.
• Update not detected?
  The tool only checks for updates if it can reach GitHub and if network access is available.

---

{
  "title": "Best Practice",
  "content": "Keep your templates and hooks under version control for easy portability and collaboration."
}

---

Contributing

1. Fork the mcugen GitHub repo
2. Submit PRs for bug fixes, features, or template improvements
3. Open issues for feedback or questions

---

License

MIT © 2026 Megh Badonia

---

Credits

• Google Material Color Utilities
• sharp image processing
• Inspired by pywal and Material Theming

---

Version

Current: 1.0.0

---

Questions?

Open an issue on GitHub or email the maintainer for support.

---

Happy theming! 🖌️