Color System (HEX-Only) → Migration playbook

Extracted colors →

extracted-colors.txt

Distribution by Color Family

(using computed hue, saturation, luminance — NOT guessing)

Additional reads

• Step-1 → building Source of truth

  → contains

  every raw color

  in the codebase

  → normalized into

  (r,g,b,alpha,raw)
  

  format

  unified_full_raw.csv

• Step-2 → Master Genome File

  Goal:

  Unify all colors in the codebase into one safe canonical representation, BEFORE tokenizing / replacing.

  ---

  What we Must Do First

  Before touching tokens, clustering, or mapping —

  We must refactor all CSS to a consistent standard encoding, so that:

  • every color in your system looks the same
  • no more:
    • #fff, white, rgb(255,255,255)
    • #1b74e31f, rgba(27,116,227,0.1)
    • % opacity or random shorthand

  Master Genome File

  color_genome_master.csv

  What’s Inside (Columns Explained)

  column	meaning
  raw	exact original value from your extracted list (including trash, typos, rgba, 3-digit hex etc.)
  canonical	normalized rgba(r,g,b,a) — your final target encoding
  alpha_type	scrim, overlay, mask, semi, full, or invalid
  score	0-100 → “auto-replace confidence”
  bucket	coarse color family (grey, green, blue, red/orange, other)
  replace_safe	YES, NO, NEED_REVIEW
  notes	metadata space (currently blank, can later contain “shadow-only”, “platform-color”, etc.)

• Color Tokenization Stage 1 (HEX-Only) — Completed Summary

  📌 TL;DR

  We wrapped hardcoded hex colors behind a token layer — no UI change, zero risk.

  What We Just Achieved (Stage 1 Only)

  We completed the first foundational phase of color modernization — extracting and wrapping hardcoded hex colors across the app, introducing a stable, zero-risk token layer that makes future UI changes possible without breaking production.

  ---

  Why This Was Necessary

  Before this work:

  • UI contained ~3,338 raw color values directly in TSX / CSS / inline styles
  • Colors were inconsistent, duplicated, and hard to maintain
  • Rebrand / Dark Mode / UI refresh were virtually impossible without touching hundreds of files manually

  This work removes UI debt that would otherwise compound over time.

  ---

  What We Implemented (HEX Phase Only)

  1️⃣ Raw-Token Buffer Layer

  We introduced a translation layer to wrap hex values, without changing visuals:

  --wati-raw-353735: #353735;
  --wati-raw-666666: #666666;
  --wati-raw-d1d1d1: #d1d1d1;
  

  Usage example:

  color: var(--wati-raw-666666)
  border: 1px solid var(--wati-raw-d1d1d1)
  

  This makes the UI refactor-safe while remaining pixel-perfect.

  2️⃣ Extraction + Safe Wrapping Using Cursor

  Action	Output
  Extracted raw hex values across repo	CSV inventory
  Validated replacements	Cursor preview screen
  Applied updates	15 files modified
  Visual output change	0% (no diff)

  3️⃣ Storybook Support (Test Only)

  • Tokens are loadable inside Storybook
  • Raw token mode available for inspection
  • No production activation yet

  ---

  What We Did Not Do (Intentionally)

  To avoid production risk:

  • ❌ No full semantic remapping in the app
  • ❌ No auto-find & replace across repo
  • ❌ No JS logic changes
  • ❌ No unreviewed refactor

  Rollback is instant → delete the CSS import & remove override file.

  ---

  Current Result

  | --- | --- |

  ⚠️ Low % by design — Stage 1 = infrastructure, not completion.

  ---

  Engineering Guidelines — Effective Now

  | --- | --- |

  What This Enables Next

  This foundation unlocks:

  • Semantic token layer (text-strong, surface-default, accent-success)
  • Dark Mode support
  • Rebrand-ready UI
  • Faster UI rollout without regression

  ---

  Next step prompt

Introduction

This document is the full narrative of how we began transforming Wati’s UI foundation from a fragmented legacy color codebase into a modern, scalable design system — using human-led rules, AI-assisted refactoring (Cursor), and safe staged rollout methodology.

Why the Migration Is Necessary

Prior to this migration, WATI’s interface was held together by:

• 3,338+ hard‑coded color values
• scattered across more than 700 frontend files
• in many formats: #666, #353735, rgb(0 0 0 / 40%), rgba(0,0,0,0.12), and named colors like tomato
• no single source of truth
• no design‑system boundaries