Catppuccin Port Creation Skill

Overview

Agent skill for automated Catppuccin theme generation, color validation, and port preparation. The agent handles technical theme generation while users handle manual repository and submission tasks.

Quick Start

For immediate help:

Agent generates: Theme files, color mappings, validation reports
User handles: Repository setup, testing, GitHub submissions
Colors defined in: references/official-palette.json
Port template: https://github.com/catppuccin/template

Agent Capabilities

Target Analysis

When given an application/library name (e.g., "XYZ"), the agent can:

Research the application's theming system and documentation
Identify if it uses CSS, JSON, XML, or proprietary theme formats
Find existing theme examples and configuration files
Locate color customization APIs or styling hooks
Determine theming architecture (component-level, global, hybrid)

Theme Generation

Converts color schemes to CSS, SCSS, JSON, XML formats
Creates all four flavor variants (Latte, Frappé, Macchiato, Mocha)
Applies semantic color mappings for consistency
Generates component-specific color definitions

Color Validation

Validates against official Catppuccin palette
Calculates WCAG contrast ratios
Identifies color conflicts and suggests fixes
Generates compliance reports

Analysis & Preparation

Extracts colors from existing themes
Identifies unthemed elements from screenshots
Generates preview compositions
Creates submission-ready documentation

User Responsibilities

Repository Setup

git clone https://github.com/catppuccin/template.git <port-name>
cd <port-name>
rm -rf .git
git init

Testing & Submission

Test all four flavors in target application
Take screenshots for preview generation
Create GitHub issues/PRs for submission
Respond to review feedback

Workflow

Phase 1: Target Analysis

When user requests a port for "XYZ":

Agent: Researches XYZ's theming documentation, identifies styling system
Agent: Finds existing themes and color customization methods
User: Confirms target application and provides any special requirements

Phase 2: Theme Generation

Agent: Generates theme files based on XYZ's theming system
Agent: Creates all four flavor variants with proper semantic mapping
User: Tests themes in XYZ application, provides feedback

Phase 3: Preparation

Agent: Creates documentation specific to XYZ's installation process
User: Takes screenshots of themed XYZ application
Agent: Generates preview compositions from user screenshots

Phase 4: Submission

User: Creates GitHub issue/PR for XYZ port
Agent: Assists with any reviewer-requested changes

Common Issues

Color Problems

Agent can: Detect mismatched colors, suggest fixes, generate corrected files
User should: Provide screenshots, test fixes in application

Repository Issues

Agent can: Generate proper structure, create README files
User should: Initialize repository, update metadata

Submission Issues

Agent can: Check for duplicates, validate package completeness
User should: Create GitHub issue/PR, respond to feedback

Resources

For detailed guidelines, color references, and community support:

Official documentation: https://github.com/catppuccin/catppuccin
Color palette: references/official-palette.json (this directory)
Community discussions: https://discord.com/servers/catppuccin-907385605422448742
Userstyles submissions: https://github.com/catppuccin/userstyles
Application port reviews: https://github.com/catppuccin/catppuccin/issues/new?assignees=&template=port-review.yml

tools-catppuccin