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
Install from VS Code Marketplace
code --install-extension phenotheme
Or search for "PhenoTheme" in the Extensions panel (Ctrl+Shift+X
)
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
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
- Repository Detection: PhenoTheme analyzes the workspace root folder name
- Hash Generation: Creates a deterministic hash using djb2 algorithm
- Hue Calculation: Primary hue derived from hash (0-360° in 30° increments with micro-variation)
- Secondary Hue: Split-analogous hue calculated 45-60° from primary for harmony
- Color Generation: Low-saturation backgrounds with scientific color relationships
- Contrast Adjustment: Automatic text color optimization for WCAG AA compliance
- Application: Updates
workbench.colorCustomizations
and editor.tokenColorCustomizations
- 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
]
}
}
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
PhenoTheme: Where code genetics meets visual expression 🧬