PhenoTheme

🧬 Why did we build PhenoTheme?

The more we vibecode, the more projects are open at once, and my tiny brain saves a few cycles by using the visual cortex to distinguish between editors. I've used Stuart Robinson's Window Colors extension for years, but am looking for a little more visual sophistication and differentiation.

🧬🧬 Who benefits from PhenoTheme?

PhenoTheme is for developers and teams who:

• Work with multiple repositories simultaneously (consultants, full-stack developers, DevOps engineers)
• Switch contexts frequently between different projects, microservices, or client codebases
• Want zero-configuration automation - no manual color picking or setup required

🧬🧬🧬 What does PhenoTheme do?

PhenoTheme is a VS Code extension that deterministically generates beautiful, visually optimized, disambiguated color schemes for each repository you work with. Like biological phenotypes expressing genetic information, each repository gets a unique "visual phenotype" derived from its "genetic code" (the repository name).

Core Features

🎨 Two-Color Signature System

• Each repository gets a unique primary + secondary hue combination (45-60° apart)
• Editor uses primary hue, sidebar uses secondary hue for clear differentiation
• Deterministically generates colors based on repository name hash
• Uses scientific hue-shifting on Solarized theme foundation
• Maintains excellent contrast ratios and accessibility standards

⚡ Zero-Configuration Automation

• Automatically detects when you open a new repository
• Instantly applies two-color signature to editor, sidebar, title bar, and status bar
• Saves settings to .vscode/settings.json while preserving existing settings
• Works consistently across team members and machines

🎯 Professional Quality

• Reduced saturation backgrounds (12-20%) for better text readability
• WCAG AA contrast compliance with automatic text color adjustment
• Split-analogous color harmony prevents clashing
• Visual hierarchy: editor (lightest) → sidebar → panels → chrome (darkest)

🔧 Flexible Options

• UI-only mode: keeps editor pure Solarized, colors only the chrome
• Full mode: applies two-color signature throughout
• Manual regeneration commands for testing
• Preserves existing workspace settings like window.title

🧬🧬🧬🧬 How do I use PhenoTheme?

Installation

1. Install from VS Code Marketplace

   code --install-extension phenotheme
   

   Or search for "PhenoTheme" in the Extensions panel (Ctrl+Shift+X)

2. Open any repository

   • PhenoTheme automatically detects when you open a workspace
   • Colors are applied instantly based on the repository name
   • Settings are saved to .vscode/settings.json

3. That's it!

   • No configuration required
   • Each repository gets its unique, beautiful color scheme
   • Colors remain consistent across sessions and team members

Available Commands

Access these via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

• PhenoTheme: Regenerate Colors - Apply full two-color signature to current workspace
• PhenoTheme: Regenerate UI Only - Apply colors only to UI chrome, keep editor pure Solarized
• PhenoTheme: Show Repository Fingerprint - Display repository hash, hue values, and current status
• PhenoTheme: Toggle Colors - Enable/disable PhenoTheme for current workspace
• PhenoTheme: Reset to Default - Remove all color customizations

Current Implementation Status

This is an alpha release focusing on the core two-color signature system. Current features:

✅ Implemented

• Deterministic hash generation from repository names
• Two-color signature system (primary + secondary hues)
• Scientific color theory with split-analogous harmony
• Automatic contrast adjustment for accessibility
• UI-only and full modes
• Settings preservation (doesn't overwrite existing config)

🚧 Planned for Future Releases

• Multiple base theme support (currently Solarized only)
• User preference configuration UI
• Team synchronization features
• Advanced collision detection

How It Works

1. Repository Detection: PhenoTheme analyzes the workspace root folder name
2. Hash Generation: Creates a deterministic hash using djb2 algorithm
3. Hue Calculation: Primary hue derived from hash (0-360° in 30° increments with micro-variation)
4. Secondary Hue: Split-analogous hue calculated 45-60° from primary for harmony
5. Color Generation: Low-saturation backgrounds with scientific color relationships
6. Contrast Adjustment: Automatic text color optimization for WCAG AA compliance
7. Application: Updates workbench.colorCustomizations and editor.tokenColorCustomizations
8. Persistence: Saves to .vscode/settings.json while preserving existing settings

Example Output

When you open a repository called "kubernetes", PhenoTheme generates:

{
  "workbench.colorCustomizations": {
    "editor.background": "#eff2ed",        // Primary hue (62°) - very light
    "sideBar.background": "#d7e4e0",       // Secondary hue (113°) - distinct but harmonious
    "titleBar.activeBackground": "#268bd2", // Accent from Solarized palette
    "statusBar.background": "#2aa198",      // Secondary hue accent
    "editor.foreground": "#586e75",         // High contrast text
    // ... plus 30+ other carefully calculated colors
  },
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      // Full syntax highlighting with transposed Solarized palette
    ]
  }
}

🧬🧬🧬🧬🧬 Extras

Lean Hypothesis

• We believe that developers working with multiple repositories and projects simultaneously
• Have a harder time than they need to because it's cognitively demanding to keep track of which codebase they're looking at when switching between similar-looking VS Code windows
• And we could address that at low cost by automatically giving each repository a unique, beautiful, and deterministic visual identity to reduce context-switching overhead and improve developer productivity, while maintaining excellent design principles and team consistency.

Development

This is a fork of Window Colors. Find the original README as README-window_colors.md.

Project Structure

src/
├── extension.ts          # Main extension entry point
├── colorGenerator.ts     # Core color generation logic
├── themeManager.ts       # Base theme handling
├── hashUtils.ts          # Repository name hashing
├── settingsManager.ts    # VS Code settings integration
└── commands/            # Extension commands
    ├── regenerate.ts
    ├── configure.ts
    └── teamMode.ts

Building from Source

# Clone and install dependencies
git clone https://github.com/yourorg/phenotheme
cd phenotheme
npm install

# Build the extension
npm run compile

# Run tests
npm test

# Package for distribution
vsce package

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Key areas for contribution:

• Additional base theme support (One Dark, Dracula, GitHub themes)
• Color accessibility improvements and testing
• Team collaboration features
• Performance optimizations
• Configuration UI and user preferences

Inspiration & Credits

• Window Colors Extension by Stuart Robinson - Original automatic coloring concept
• Peacock Extension by John Papa - Manual workspace coloring inspiration
• Solarized by Ethan Schoonover - Scientific color palette design
• Biological Phenotype Expression - The conceptual model for deterministic visual expression

Roadmap

Phase 1: Two-Color Foundation ✅ (Current Alpha)

• [x] Deterministic hash generation (djb2 algorithm)
• [x] Two-color signature system (primary + secondary hues)
• [x] Split-analogous color harmony
• [x] Automatic contrast adjustment (WCAG AA)
• [x] Settings preservation
• [x] UI-only and full modes

Phase 2: Polish & Expansion

• [ ] Multiple base theme support (One Dark, Dracula, GitHub)
• [ ] User preferences UI and configuration
• [ ] Advanced collision detection
• [ ] Accessibility testing and validation
• [ ] Performance optimizations

Phase 3: Team & Collaboration

• [ ] Team color synchronization
• [ ] Project hierarchy support
• [ ] Git remote integration
• [ ] Custom theme creation tools
• [ ] Workspace sharing features

License

MIT License - see LICENSE file for details.

Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📧 Contact: howdy+phenotheme@discovery.works

PhenoTheme: Where code genetics meets visual expression 🧬