How I Built a New Color System
A color system is one of the first things you build into a design system — and one of the hardest to retrofit. By the time most teams get around to formalizing a system, the application already has a color palette in use, and those colors are usually tangled up in the brand. You can't just throw them out.
You can work around it. Here's the process I used to build a new color system at First American on top of an existing palette I couldn't fully replace. There are probably more efficient ways to do it — I had limited time and resources for what was largely a pet project.
What is a color system?
A color system is more than a color palette. It's a set of colors that represent the brand, carry meaning within the application, and come with guidelines for how and when to apply them — including pairings that meet accessibility requirements. It should also be flexible enough to give designers enough usable options for their work, with semantic meaning attached to specific states or actions (disabled, success, error, and so on).
When a palette doesn't offer enough options, designers fill the gap themselves, picking values that work for the moment. Add a team of designers to that mix and you end up with an out-of-control, undocumented palette that creates havoc for designers and undermines the maintainability and consistency of the application.
The problem
Unbalanced palette
At First American, the palette leaned heavily on light grays and blues with only a single color value for green and red. In an application that's 90% blue and 10% gray, that makes some sense, but the palette didn't support lighter tints or darker shades of any primary or secondary color. Colors were handpicked and added ad-hoc whenever a designer had a use case for one, usually at the sole discretion of that designer. There was no process around color system management.
Abstract color names
The old palette used real-world objects as names: celadon, gallery, flesh, mist. When you think of the word gallery, what color comes to mind? What is celadon? I had to google that one. The convention wasn't predictable, scaled poorly, and was very confusing to use.
Inconsistent application in code
First American runs a single monorepo of Angular components consumed by 20+ micro front-end applications. There was no consistency in how color was applied: some applications consumed the design tokens (Sass color variables) from the component library, some kept their own copy-pasted version of the palette, and some had raw hex values inline.
Research and audit
Before doing anything, I needed the lay of the land. I started by answering these questions:
- Is the color palette documented?
- What's the origin story of the palette?
- Which colors are part of the brand and can't be removed?
- Which colors were chosen systematically, and which were added ad-hoc?
- What are the primary, secondary, and status colors?
- Can the primary, secondary, and status colors be changed at all?
Then I ran a color audit — basically a UI inventory, scoped to color. I created a spreadsheet with one row per color in the design library and codebase, starting with the design documentation because those colors were usually chosen with purpose.
With more time I would have written a script, but this was a manual task. I opened VS Code and did a global search across the code; your mileage will vary depending on the architecture. Well-organized code makes the colors easy to find. Anything spread across multiple repositories or full of bespoke values takes longer. I recorded every color in the spreadsheet, noted how many times each one was referenced, and added a swatch in the row so I could see what I was dealing with.
Once the audit was done, I color-coded the rows:
- Green — untouchable brand colors.
- Red — obvious technical debt (e.g., a color that had a token but was being used as a hardcoded hex elsewhere).
- Orange — colors used once or never, or colors nearly identical to another (which one to keep usually took some research).
Categorization
I brought the green and orange colors into Figma as frames I could drag around freely, then grouped them by hue: gray, blue, green, red, and so on. That alone created order in the chaos. Within each hue group, I pared down nearly-identical colors by usage — if Color X was used more than Color Y, I kept X and dropped Y.
With the colors categorized, I had a foundation: a visual document showing which hues I needed and how many shades and tints I'd need in each to cover the application.
The new color system
Colorbox
I used a tool called Colorbox to generate the new system, applying an algorithm to each key color to produce a color band. Colorbox builds bands from color and graph inputs. There's more on the approach in Lyft's writeup and the Colorbox introduction.
A few things I learned along the way:
- Don't use the same algorithm for every color. Inputs that work well for one hue often don't translate to another.
- Skew each band toward light on one end and dark on the other. Mid-range colors rarely meet accessibility contrast standards, so they're of limited use.
- Keep color stops consistent across bands.
blue-100andgreen-100should sit at a similar tint level. That consistency is what makes accessible color pairings predictable once you codify them.
Defining the color bands
Using the primary and secondary colors — gray, blue, vivid blue, purple, yellow, orange, red, and green — I tweaked the algorithm for each key color to produce ten variations. I also wanted enough flexibility in the new system to map to the old colors without jarring shifts in the UI balance.
Then I assigned semantic variable names to each base color so designers and engineers had a clearer signal of how to use each one, removing the subjectivity and cognitive load (goodbye, celadon and gallery).
Next I tested the colors in Figma mockups to check for visual regressions, then wrote a migration document mapping each old color to its replacement and documenting each new color's semantic usage (e.g., black-800 = default body text).
One caveat: although I'd started introducing rudimentary design tokens (Sass variables) in the component library, the applications weren't consuming them yet. The code was still referencing reference tokens (color names) directly, with no multi-tiered token structure underneath.
Accessible pairings
Because the new system kept color stops consistent across hues, we could designate global stops for foreground and background pairings that meet WCAG 2.1 AA contrast ratios. A card background could be blue-100 with foreground at blue-800, and the same combination would work for green, red, and so on.
Rolling it out
We shipped the new system in phases rather than as a big-bang migration:
- Introduced the new color system in the Figma library as beta.
- Applied the new colors to all new components.
- Mapped the new colors to new design tokens.
- Communicated a deprecation window for the old palette in the component library.
Takeaways
- Even without a comprehensive token package in place, the new color system reduced confusion in design and engineering. All colors were documented along with their semantic usage.
- More color options led to less improvisation by designers, which cut technical debt in the code.
- The system laid the foundation for a more comprehensive token package with system, semantic, and component tokens.
Looking back, the most useful thing wasn't the colors themselves — it was the shared vocabulary the system gave designers and engineers. Everything that came after, the broader token package included, was easier to build because of it.