130 Widgets

Building tools. Learning to build tools. Learning to build learning tools.

0. Preface & Orientation

What ColorIdentity does, what you’ll learn, and how this tutorial is organized.

What You’ll Build

ColorIdentity is a VS Code extension that automatically gives each workspace a unique, harmonious color identity. Open three projects side by side and you can tell them apart at a glance — the title bar, activity bar, and status bar each carry a tint derived from the workspace’s folder name.

Unlike extensions that let you pick arbitrary colors, ColorIdentity derives its palette from your workspace name and active color theme. In its default harmonized mode, it goes further: it analyzes your theme’s dominant hue and offers color suggestions based on color harmony theory (analogous, complementary, triadic, split-complementary). When you switch themes, your chosen harmony relationship carries over automatically — the colors adapt without reopening the picker.

Workspace folder name Active color theme ColorIdentity ┌─────────────────────┐ ┌──────────────────┐ ┌───────────────────────────────────┐ │ "my-project" │──────▶│ djb2 hash │──────▶│ hue = 217° (auto) │ └─────────────────────┘ └──────────────────┘ │ — or — │ │ hue = base + offset (harmonized) │ ┌──────────────────┐ │ │ │ Theme kind + │──────▶│ + theme profile (dark/light) │ │ theme base hue │ │ + harmony sat/lit adjustments │ └──────────────────┘ │ ↓ │ │ title bar, activity bar, │ │ status bar, tab bar │ └───────────────────────────────────┘

The extension is small — seven TypeScript files, around 1,190 lines of code total, with zero runtime dependencies. But it covers a surprising range of topics: VS Code extension APIs, HSL color theory, color harmony, deterministic hashing, theme analysis, PNG file encoding from scratch, event-driven reactivity, and workspace settings management. That’s what this tutorial is about.

What You’ll Learn

This tutorial teaches three subjects in parallel:

Extension VS Code API Color Color Science Arch Architecture
package.json manifest — Declaring commands, configuration, and activation events. HSL color space — Why hue/saturation/lightness is the right model for theme-aware color generation. Shared types — Defining interfaces that keep six files in sync without circular dependencies.
QuickPick API — Building a picker with icons, separators, and custom input flow. djb2 hashing — A classic string hash that maps workspace names to hues deterministically. Settings merging — Writing to workspace config without clobbering other extensions.
Event listeners — Reacting to theme changes and configuration changes. HSL-to-hex conversion — The math that turns color theory into #rrggbb strings. PNG encoding — Building a valid PNG from raw pixels using only Node’s zlib.
Status bar items — Adding interactive indicators to the VS Code chrome. Theme profiles — Deriving saturation and lightness ranges from the active theme kind. CRC-32 checksums — The integrity mechanism every PNG chunk requires.

Prerequisites

You need:

Tip

If you’ve never written a VS Code extension before, this tutorial starts from scratch and explains every API as it appears. You don’t need to run through Microsoft’s “Your First Extension” guide first, though it won’t hurt.

How This Tutorial Is Organized

Sections are tagged with one of three labels:

Like the other tutorials on this site, this one explains an existing project rather than having you type code line by line. Every section walks through real code from the ColorIdentity source, explains each decision, and highlights the tradeoffs. You’re encouraged to have the source open in VS Code alongside these pages.

The Seven Source Files

The entire extension lives in seven TypeScript files. Here’s the map:

File Lines Role
extension.ts 202 Entry point. Registers commands, creates the status bar, wires up event listeners, orchestrates color application.
colorGenerator.ts 233 The color engine. Hashes workspace names to hues, defines theme profiles, converts HSL to hex, generates the full palette with harmony-aware adjustments.
themeAnalyzer.ts 257 Theme analysis. Extracts the active theme’s base hue and generates harmony-relative color suggestions (analogous, complementary, triadic, split-complementary).
colorPicker.ts 222 The color picker UI. Dual-mode QuickPick: simple (fixed presets) or harmonized (theme-relative harmony groups), with swatch icons and custom hue input.
colorApplier.ts 85 Settings integration. Reads and writes workbench.colorCustomizations without clobbering other extensions.
swatchGenerator.ts 128 PNG encoder. Generates solid-color swatch images at runtime using raw PNG encoding — no image library.
types.ts 63 Shared interfaces and the config reader. Defines the contracts that keep the other six files decoupled.
Architecture Note

Notice the zero-dependency design. The extension uses only Node.js built-ins (path, fs, zlib) and the VS Code API. No color libraries, no image libraries, no utility packages. Everything is implemented from first principles. This makes the extension fast to activate, trivial to audit, and immune to supply-chain concerns. It also makes it a much more interesting thing to study.