everforest-resources/CONTRIBUTING.md

Contributing to Everforest Resources

Thank you for your interest in contributing to Everforest Resources! This project follows a generator-first approach where all theme files are generated from canonical palette definitions.

Quick Start

git clone https://github.com/ivuorinen/everforest-resources.git
cd everforest-resources
npm install
npm run generate

Development Workflow

1. Edit Only Source Files

Critical Rule: Only edit these files:

• palettes/everforest.json or palettes/everforest.yaml - Canonical color definitions
• template.txt files - Theme templates with color placeholders

Never edit generated files directly - they will be overwritten by the generator.

2. Template System

Templates use these placeholders:

• {{bg}}, {{bg1}}, {{bg2}} - Background colors
• {{fg}} - Foreground color
• {{red}}, {{orange}}, {{yellow}}, {{green}}, {{aqua}}, {{blue}}, {{purple}} - Accent colors
• {{gray1}}, {{gray2}}, {{gray3}} - Gray variations

3. Generate and Test

npm run lint:fix     # Auto-fix linting issues
npm run generate     # Generate all theme files
npm run validate     # Validate outputs
npm run ci           # Full CI pipeline

4. Installation Testing

./install.sh --dry-run    # Preview installation
./install.sh              # Install themes

Adding New Tools

CLI Tools

1. Create new directory: cli/newtool/
2. Add template.txt with color placeholders
3. Update scripts/generate-themes.mjs to include the new tool
4. Update install.sh to install the new tool's themes
5. Test all 6 variants are generated correctly

Terminal Emulators

1. Create new directory: terminals/newterminal/
2. Add template.ext (appropriate file extension)
3. Update generator and installer
4. Test with actual terminal application

Editors

1. Create new directory: editors/neweditor/
2. Add appropriate template file
3. Follow same pattern as existing editors

Code Quality

Linting and Formatting

npm run lint         # Check code quality
npm run lint:fix     # Auto-fix issues
npm run format       # Format all files

All code must pass Biome linting and formatting checks.

Pre-commit Hooks

The project uses Husky for:

• Commit message validation: Must follow Conventional Commits
• Pre-commit checks: Linting and basic validation

Example commit messages: feat: add support for new terminal emulator fix: correct color mapping in dark variant docs: update installation instructions

CI/CD Pipeline

All PRs must pass:

• Lint: Biome code quality checks
• Build: Generator + validation
• Snapshots: Playwright visual testing
• Commitlint: Conventional commit format
• CLI Verify: Installation testing

Architecture Principles

1. Generator-first: All outputs derive from palettes/everforest.(json|yaml)
2. Template system: Use placeholders, not hardcoded values
3. Variant completeness: All tools must support 6 variants (dark/light × hard/medium/soft)
4. ANSI-only for CLI: CLI tools use ANSI codes, not hex values
5. No manual edits: Generated files must never be hand-edited

Project Structure

palettes/           # Canonical color definitions
scripts/            # Generator and validation scripts
terminals/          # Terminal emulator themes
cli/                # CLI tool configurations
editors/            # Code editor themes
web/                # CSS themes and web demo
docs/               # Documentation
install.sh          # Universal installer
verify/             # Container-based verification

Common Issues

Template Errors

• Ensure all placeholders use double braces: {{color}}
• Check template syntax matches target tool's format
• Verify all 6 variants generate without errors

Color Mapping

• CLI tools should use ANSI codes from palette
• GUI applications can use hex values
• Follow existing patterns for color assignments

Installation Issues

• Always install to variant-specific paths
• Never overwrite user configuration files
• Provide manual activation instructions

Getting Help

• Issues: GitHub Issues
• Discussions: Use GitHub Discussions for questions
• Documentation: Check docs/ directory and CLAUDE.md

License

By contributing, you agree that your contributions will be licensed under the MIT License.