Color System And Semantic Colors

Who this is for

• Data Visualization Engineers who build dashboards, charts, and reporting UIs.
• Design system contributors defining tokens for analytics products.
• BI developers who translate metrics into clear, accessible color encodings.

Prerequisites

• Basic color terminology (hue, saturation, value/lightness).
• Familiarity with chart types (categorical, sequential, diverging).
• Comfort with theme tokens or variables (CSS variables, JSON tokens).

Why this matters

In data products, color is not decoration—it communicates state, priority, and trends.

• Map KPI states to colors (success, warning, danger) in dashboards.
• Provide consistent chart palettes across dozens of reports.
• Ensure readability in light and dark themes and under color-vision deficiencies.
• Reduce one-off choices by using semantic tokens that scale.

Concept explained simply

A color system is a set of reusable building blocks. Instead of hard-coding hex values, you assign meanings (semantics) to tokens like success or danger. Charts and UI components reference those tokens, so everything stays consistent across the app.

Mental model: 3-layer cake

1. Base palette: Neutral grays + a brand hue with steps (50–900).
2. Semantic tokens: Meaningful roles (success, warning, danger, info, neutral) with foreground, background, and border variants.
3. Component/chart tokens: Tokens for actual usage (axis, gridlines, legend, categorical series 1–12, sequential ramps, diverging ramps).

Worked examples

Example 1 — Minimal KPI dashboard color system (light theme)

1. Pick base: brand indigo and neutrals.
   • Brand (indigo-ish): 50 #EEF2FF, 100 #E0E7FF, 200 #C7D2FE, 300 #A5B4FC, 400 #818CF8, 500 #6366F1, 600 #4F46E5, 700 #4338CA, 800 #3730A3, 900 #312E81
   • Neutral gray: 50 #F9FAFB … 900 #111827
2. Map semantics:
   • semantic.success: fg #2E7D32, bg #E6F4EA, border #A5D6A7
   • semantic.warning: fg #B26A00, bg #FFF4D6, border #FFDFA3
   • semantic.danger: fg #C62828, bg #FDE7E9, border #F5B5B8
   • semantic.info: fg #1E88E5, bg #E3F2FD, border #90CAF9
   • neutral: text.primary #111827, surface.default #FFFFFF
3. Chart tokens:
   • chart.gridline #E5E7EB, chart.axis #374151, chart.annotation #111827
   • chart.categorical.1–6: [#0072B2, #E69F00, #009E73, #CC79A7, #D55E00, #56B4E9]
   • chart.sequential.1–7 (blue ramp light→dark): [#E8F1FB, #D1E3F7, #A6C8EF, #7AACE7, #4E90DF, #2F73C6, #1E58A6]
4. States:
   • state.hover: darken current by ~8%
   • state.selected: add border #111827 at 1.5px or increase luminance contrast
   • state.muted: apply 50% opacity or map to neutral.400–500

{
  "semantic": {
    "success": {"fg": "#2E7D32", "bg": "#E6F4EA", "border": "#A5D6A7"},
    "warning": {"fg": "#B26A00", "bg": "#FFF4D6", "border": "#FFDFA3"},
    "danger": {"fg": "#C62828", "bg": "#FDE7E9", "border": "#F5B5B8"},
    "info": {"fg": "#1E88E5", "bg": "#E3F2FD", "border": "#90CAF9"}
  },
  "chart": {
    "categorical": ["#0072B2","#E69F00","#009E73","#CC79A7","#D55E00","#56B4E9"],
    "sequential": ["#E8F1FB","#D1E3F7","#A6C8EF","#7AACE7","#4E90DF","#2F73C6","#1E58A6"],
    "gridline": "#E5E7EB", "axis": "#374151", "annotation": "#111827"
  }
}

Example 2 — Semantic thresholds for a KPI

KPI: On-time shipping rate (%). Thresholds:

• ≥ 95% → success
• 90–94% → warning
• < 90% → danger

Bar color mapping:

• value ≥ 95 → semantic.success.fg
• 90 ≤ value ≤ 94 → semantic.warning.fg
• value < 90 → semantic.danger.fg

Accessibility: add value labels or icons; do not rely on color alone.

Example 3 — Dark theme adaptation

• Swap surfaces: surface.default #0B0F1A, text.primary #E5E7EB, gridlines #273043.
• Adjust tokens: use brighter tints for marks so they pop on dark background (increase lightness by ~15–20%).
• Keep semantics consistent: danger stays red, success stays green, but use lighter variants for foreground on dark.

{
  "surface": {"default": "#0B0F1A"},
  "text": {"primary": "#E5E7EB"},
  "chart": {"gridline": "#273043", "axis": "#C7D2FE"},
  "semantic": {
    "success": {"fg": "#6FD08C", "bg": "#0F2A1B", "border": "#2E7D32"},
    "warning": {"fg": "#FFD27A", "bg": "#2A1F05", "border": "#B26A00"},
    "danger": {"fg": "#FFA1A6", "bg": "#2A0E10", "border": "#C62828"},
    "info": {"fg": "#8EC7FF", "bg": "#0C2233", "border": "#1E88E5"}
  }
}

Hands-on exercises

Do these now. Solutions are hidden under each exercise.

Exercise 1 — Design semantic color tokens (light theme)

Goal: Create semantic tokens for a light theme using brand blue #1E88E5 and neutral gray #111827–#F9FAFB.

1. Define text.primary (#111827), surface.default (#FFFFFF), and gridline (#E5E7EB).
2. Set these semantic tokens (fg/bg/border): success, warning, danger, info.
3. Ensure body-text contrast ≥ 4.5:1 on surface.default.
4. Provide state.selected as a 1.5px border #111827.

{
  "text": {"primary": "#111827"},
  "surface": {"default": "#FFFFFF"},
  "chart": {"gridline": "#E5E7EB"},
  "semantic": {
    "success": {"fg": "#2E7D32", "bg": "#E6F4EA", "border": "#A5D6A7"},
    "warning": {"fg": "#B26A00", "bg": "#FFF4D6", "border": "#FFDFA3"},
    "danger": {"fg": "#C62828", "bg": "#FDE7E9", "border": "#F5B5B8"},
    "info": {"fg": "#1E88E5", "bg": "#E3F2FD", "border": "#90CAF9"}
  },
  "state": {"selected": {"border": "#111827", "width": "1.5px"}}
}

Expected output

{
  "semantic": {
    "success": {"fg": "", "bg": "", "border": ""},
    "warning": {"fg": "", "bg": "", "border": ""},
    "danger": {"fg": "", "bg": "", "border": ""},
    "info": {"fg": "", "bg": "", "border": ""}
  }
}

Exercise 2 — Build a 6-color categorical palette (color-blind aware)

Requirements:

• 6 distinct hues with good luminance spread on white.
• Avoid red–green confusion as the only separator.
• Add a 1px border #FFFFFF for marks on dark backgrounds.

["#0072B2","#E69F00","#009E73","#CC79A7","#D55E00","#56B4E9"]

Expected output

["#........","#........","#........","#........","#........","#........"]

Checklist (self-review)

• Semantic tokens exist for success, warning, danger, info with fg/bg/border.
• Text and key marks meet contrast targets (4.5:1 for text, ~3:1 for marks).
• Chart palettes defined: categorical, sequential, and (if needed) diverging.
• States defined: hover, active, selected, muted, disabled.
• Tokens are themeable (light/dark) without changing semantics.

Common mistakes and self-check

• Hard-coding brand hex everywhere. Fix: reference semantic or chart tokens.
• Using red/green only to show pass/fail. Fix: add icons, patterns, or shapes.
• Too many similar hues in categorical palettes. Fix: reduce to 6–8 strong hues.
• Low-contrast small text on colored backgrounds. Fix: test contrast and adjust tint/shade.
• Inconsistent selection color per chart. Fix: define a single selection token/state.

Practical projects

• Reskin an existing dashboard using only tokens (no raw hex). Measure how many components update automatically.
• Build a legend component that reads chart.categorical tokens and renders swatches with labels and selection states.
• Create a sequential ramp for a heatmap and document min/mid/max mapping rules (e.g., diverging with a neutral midpoint).

Learning path

• Before this: basic color theory; chart types and encodings.
• Now: define semantic tokens and chart palettes in light/dark.
• Next: apply tokens to states, legends, tooltips, and annotation systems; expand to typography and spacing tokens.

Next steps

• Document your tokens in a central spec (names, hex, usage, do/don’t).
• Pilot the system in 2–3 critical dashboards and gather feedback.
• Add test cases for contrast and theme coverage.

Mini challenge

Pick one dashboard and replace all hex values with semantic or chart tokens. Track how many unique colors you can eliminate while keeping clarity or improving it.

Quick Test

Take the quick test to check your understanding. Available to everyone; logged-in users get saved progress.