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 © 2024 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! 🖌️