3. Hashing Names to Colors

The djb2 hash algorithm, deterministic hue generation, and the HSL color space.

The Core Idea

Color Identity’s defining feature is that the same workspace name always produces the same color. Open “my-api-server” on any machine, and it gets the same hue. This is achieved through deterministic hashing: a pure function that converts a string to a number in a predictable, repeatable way.

The function needs three properties:

• Deterministic: same input always produces the same output.
• Well-distributed: similar names (like api-v1 and api-v2) should produce noticeably different hues.
• Fast: it runs on every activation, so it needs to be instant.

The djb2 Hash Algorithm

/**
 * Deterministic hash of a string → number in [0, 360).
 * Uses djb2 — simple, fast, and produces a well-distributed spread.
 */
export function hashToHue(input: string): number {
    let hash = 5381;
    for (let i = 0; i < input.length; i++) {
        hash = ((hash << 5) + hash + input.charCodeAt(i)) >>> 0;
    }
    return hash % 360;
}

djb2 is one of the most well-known string hash functions, created by Daniel J. Bernstein. Despite its simplicity, it produces an excellent distribution across output values. Let’s trace through the algorithm:

1. Initialize with a magic number: hash = 5381. This starting value was chosen empirically by Bernstein — it produces fewer collisions than other initial values for typical input strings.
2. For each character: hash = hash * 33 + charCode. The expression (hash << 5) + hash is a bit-manipulation trick that computes hash * 32 + hash = hash * 33 without using multiplication. Then the character’s Unicode code point is added.
3. Keep it unsigned: >>> 0 forces the result to an unsigned 32-bit integer. Without this, JavaScript’s bitwise operators would produce signed values, and we’d get negative hashes.
4. Map to hue range: hash % 360 reduces the 32-bit hash to a value in [0, 360), which is exactly the hue range on the color wheel.

How Well Does It Distribute?

Let’s try some common workspace names and see what hues they produce:

Notice how my-project and my-project-2, which differ by only two characters, produce hues 37° apart — visually distinct. That’s the benefit of a well-distributed hash. A naive approach (like summing character codes) would produce similar values for similar strings.

The HSL Color Space

With a hue in hand, we need a color model that lets us control vibrancy and brightness independently. That’s HSL:

The key advantage of HSL over RGB for this project:

• Hue is the identity axis. We can lock the hue (derived from the workspace name) and vary saturation and lightness to match the theme. In RGB, changing “brightness” would require adjusting all three channels in a coordinated way.
• Theme adaptation is intuitive. Dark themes need low lightness and moderate saturation. Light themes need high lightness and low saturation. These are simple numerical adjustments on the S and L axes.
• Foreground contrast is predictable. Given a background lightness, we know that a foreground with very different lightness will be readable. This is much harder to reason about in RGB.