Dataviz Style Guide

If a series represents success, it is green (#15803d). If it represents error, it is red (#b91c1c). Pick the family from the meaning, then assign it. A bar chart of four random metrics does not get blue/purple/green/amber by default — pick by what each metric means.

Gridlines: #eaeaea, only on the value axis, behind the data. Tick labels and axis title: #666. Data labels: #1a1a1a. The chart should read as one continuous tone with the data emerging from it — not as a grid of competing rectangles.

The same six color families serve Graphviz, matplotlib, Vega-Lite, and Mermaid. Copy the hex values exactly — full six-digit lowercase. Do not substitute a "close enough" color. The coordination cost of keeping all diagrams aligned is paid precisely once, here, and recovered every time a reader moves between pages.

The 100-weight fills are pastel backgrounds. The 700-weight values serve triple duty: node border, node text, and series stroke. The 50-weight is for cluster/region backgrounds — lighter than the node fill so the region recedes behind its contents.

When the data is continuous (a heatmap, a gradient encoding), stretch the matching family between its 50-weight and its 700-weight.

• Sequential blue: #eff6ff → #1d4ed8
• Sequential green: #f0fdf4 → #15803d
• Diverging (error vs success): #b91c1c ← #ffffff → #15803d

Do not use jet or rainbow colormaps. Do not use the viridis or plasma defaults unless you are encoding physical quantities where those are the established convention.

When series are genuinely peer categories (three datacenters in a comparison plot), use the families in this order: Blue, Amber, Green, Purple, Yellow, Red. This is the categorical-range defined in the Clojure palette below and reflected in axes.prop_cycle in the matplotlib style.

The featured series uses its 700-weight. All other series collapse to #cccccc at 1 px stroke. This is more useful than a legend and less confusing than coloring everything.

Paste into ~/.config/matplotlib/stylelib/walsh.mplstyle or load with plt.style.use('walsh.mplstyle').

# walsh.mplstyle — wal.sh chart style
# Load with: plt.style.use('walsh')

figure.facecolor     : #fafafa
axes.facecolor       : #ffffff
axes.edgecolor       : #666666
axes.labelcolor      : #666666
axes.titlecolor      : #1a1a1a
axes.titleweight     : 700
axes.titlesize       : 14
axes.titlepad        : 12
axes.labelsize       : 11
axes.spines.top      : False
axes.spines.right    : False
axes.grid            : True
axes.grid.axis       : y
axes.axisbelow       : True
grid.color           : #eaeaea
grid.linewidth       : 0.8
grid.linestyle       : -
xtick.color          : #666666
ytick.color          : #666666
xtick.labelsize      : 10
ytick.labelsize      : 10
xtick.direction      : out
ytick.direction      : out
font.family          : Helvetica, Arial, sans-serif
font.size            : 10

# Six semantic families, ordered for categorical use
axes.prop_cycle : cycler('color', [
    '#1d4ed8', '#b45309', '#15803d',
    '#6b21a8', '#a16207', '#b91c1c'])

legend.frameon       : False
legend.fontsize      : 10
lines.linewidth      : 2.0
lines.solid_capstyle : round
patch.edgecolor      : #1d4ed8
patch.facecolor      : #dbeafe

Pin the semantic names in every script so the meaning is explicit at the call site.

# walsh_colors.py — semantic palette constants
BLUE_FILL   = "#dbeafe"
BLUE_STROKE = "#1d4ed8"

PURPLE_FILL   = "#ede9fe"
PURPLE_STROKE = "#6b21a8"

GREEN_FILL   = "#dcfce7"
GREEN_STROKE = "#15803d"

AMBER_FILL   = "#fef3c7"
AMBER_STROKE = "#b45309"

YELLOW_FILL   = "#fef9c3"
YELLOW_STROKE = "#a16207"

RED_FILL   = "#fee2e2"
RED_STROKE = "#b91c1c"

# Chrome
BG         = "#fafafa"
PLOT_BG    = "#ffffff"
AXIS       = "#666666"
GRID       = "#eaeaea"
TEXT       = "#1a1a1a"
GHOST      = "#cccccc"

# Categorical order (non-semantic, peer categories)
CATEGORICAL = [BLUE_STROKE, AMBER_STROKE, GREEN_STROKE,
               PURPLE_STROKE, YELLOW_STROKE, RED_STROKE]

seaborn inherits matplotlib's rcParams automatically. Set the palette explicitly to override seaborn's defaults.

import seaborn as sns
from walsh_colors import CATEGORICAL

sns.set_theme(style="whitegrid", rc={
    "axes.facecolor": "#ffffff",
    "figure.facecolor": "#fafafa",
    "grid.color": "#eaeaea",
})
sns.set_palette(CATEGORICAL)

Vertical bars when categories are short labels; horizontal when they are not. Bars are filled with the 700-weight color, no stroke, no rounding. Use one color per bar only when each bar means something different; otherwise all bars in blue 700.

Conventions:

• Sort descending by value unless the category order is meaningful
• Y-axis always starts at 0
• No legend when all bars share one color — use the title instead
• Max 12 bars before switching to a table or a top-N + "other" slice

Fig 08.1 — error rate by service (blue, ordered descending)
  2.0% |
  1.5% |  ■
  1.0% |  ■  ■
  0.5% |  ■  ■  ■  ■  ■
   0%  +--+--+--+--+--+--
       auth orders search media profile geo

2 px stroke, round joins. If you have multiple series, only the primary one is blue; the rest follow the categorical order. Threshold lines are amber dashed; alert moments are red callouts (small filled triangle on the time axis).

This archetype is the site's most common chart. The advisory daily counts charts (advisory-daily-counts.png, atcscc-cache.png) use this archetype: blue primary series, amber dashed threshold at +2 SD, red dot markers on exceedances.

Conventions:

• Show the threshold in the subtitle rather than a legend entry
• If the series has gaps (missing data), show them as dashed segments or explicit gap markers rather than connecting across the void
• Annotate significant events with a vertical rule in #cccccc and a short label in Helvetica 10 above the axis

Points: 60 px² square markers (Vega-Lite default size 60), no stroke. Use opacity: 0.6 when overplotting is likely. A fit line, if present, is purple at 1.5 px, no markers.

Use only when the stack genuinely sums to a meaningful total. Each layer uses its semantic family's 100-weight fill with a 1 px 700-weight stroke between layers. Limit to 4 layers; beyond that switch to small multiples.

Sequential ramp from the family's 50-weight to its 700-weight (e.g., blue: #eff6ff → #1d4ed8). Cells are square, 1 px gap, no border. Annotate the cell value in Helvetica 10; color flips to white when the cell is darker than #888888.

Grid of identical charts, one slice each. Share axes (resolve: {scale: {y: "shared"}} in Vega-Lite). Each panel's series uses the same color — the slice is the variable, not the encoding. Label panels with their slice value above the chart area, Helvetica 12, #666666.

gnuplot is available on the site's publishing host and renders cleanly inside org-mode without additional dependencies. Use it for charts that live inside a single .org file.

set terminal pngcairo size 800,450 enhanced font "Helvetica,10" \
    background "#fafafa"
set output 'chart.png'

set border lc rgb "#666666"
set grid ytics lc rgb "#eaeaea" lw 0.8
set xtics textcolor rgb "#666666"
set ytics textcolor rgb "#666666"
set xlabel "Date" textcolor rgb "#666666"
set ylabel "Count" textcolor rgb "#666666"
set title "Request rate" textcolor rgb "#1a1a1a" font "Helvetica,14"

# Primary series in blue 700
set style line 1 lc rgb "#1d4ed8" lw 2 pt 7 ps 0.8
# Threshold in amber dashed
set style line 2 lc rgb "#b45309" lw 1.5 dt 2
# Exceedance dots in red
set style line 3 lc rgb "#b91c1c" pt 7 ps 1.2

plot data using 1:2 with linespoints ls 1 title "", \
     threshold with lines ls 2 title ""

• Is this a graph (nodes + edges)? Use Graphviz.
• Is this a time series, bar, scatter, or distribution plot? Use gnuplot for org-mode documents, Vega-Lite for interactive or web output, matplotlib for Python notebooks.
• Is this a sequence diagram, Gantt, or ER diagram? Use Mermaid.
• Does it need interactivity or animation? Use Vega-Lite or D3/SVG.

Always include #+CAPTION, #+NAME, and #+ATTR_HTML with a descriptive :alt text. The alt text describes what the chart shows, not what type of chart it is.

#+CAPTION: Request rate vs SLO target, last 6 days
#+NAME: fig:requests-slo
#+ATTR_HTML: :alt Line chart showing blue request series staying well below the amber SLO threshold of 200/s :width 700
file:chart.svg

For Graphviz diagrams built with org-babel, use :file diagram.png in the src block header and add the same caption/name/attr-html block immediately after the closing #+end_src.