0026 — Line and histogram colors on the wire
Status: Accepted Date: 2026-11-05 Amends: ADR-0012
Context and Problem Statement
Section titled “Context and Problem Statement”ADR-0012 put the
renderer’s colors on the format=series wire for fills, hbars, divlines
and hlines. It left lines and histogram without color, so the web chart
colored them from a rotating palette keyed by indicator name. That palette
cannot express what the PNG draws. Volume bars are green or red by candle
direction, MACD’s histogram is green or red by sign, and the Awesome
Oscillator’s by slope. In the web chart all three were one flat palette
color, and EMA lines did not match the PNG either. Histograms also had no
label, so the legend and Style tab showed hist0.
Decision Drivers
Section titled “Decision Drivers”- The web chart should look like the PNG. The server’s colors are the source of truth (as in ADR-0012).
- Histogram colors are per bar. They must stay aligned with
valuesthrough warmup trimming, push tails, tail merges, history pages and replay slices. - Keep the payload small. A 500-bar Volume pane has two distinct colors.
- Additive change: older servers and older web builds keep working.
Considered Options
Section titled “Considered Options”Per-bar CSS strings (colors: ["rgba(…)", …]). This is the simplest
option. It repeats a ~20-byte string per bar, about 10 KB per 500-bar
histogram.
Palette plus indices (chosen). palette lists each distinct color
once and color_idx[i] indexes it. Merging two responses remaps indices,
because each response builds its own palette.
Client rules per indicator (up/down by candle, sign, slope). This mirrors Rust logic by hand, the same drift ADR-0012 removed.
Decision Outcome
Section titled “Decision Outcome”Chosen option: palette plus indices.
- Each item of
linesgetscolor(CSS"rgba(r,g,b,a)"from the samecss_rgbahelper as ADR-0012) andwidth(the PNG stroke width in px). - Each item of
histogramgets:label.Barscarry no label of their own, so the panel label is used ("Volume","AO"). When a line already has that name (MACD’s"MACD"line) the label is"Histogram". With several histograms the labels are numbered ("KVF 1","KVF 2").palette, the distinct colors in order of first appearance.color_idx, one entry per value, aligned withvalues: an index intopalette, ornullwhere the value is null (warmup) or the bar has no color.
- Each item of
signalsgets the dot’scolor.
Warmup trimming already cuts Bars.colors with y, and push tails use
the same serializer (series_tail → series_json), so pushed and polled
tails stay identical.
On the web the resolution order is user override > server color >
palette. The palette remains only as a fallback for older servers. For
histograms the user’s Style-tab color (ADR-0017) replaces every bar’s
color. Otherwise each bar takes its server color. The klinecharts bar
figure’s styles(data, indicator, defaultStyles) callback reads that color
from the bar’s KLineData, where it is stashed next to the value. Lines
take the server width unless the user set one. The legend and the Data
Window show a histogram’s value in the color of the bar they read.
mergeOlder, mergeTail and replay slicing carry color_idx like
values, remapping incoming indices into the current palette and adding
any color it lacks.
Consequences
Section titled “Consequences”- Good: Volume, MACD, AO and every other histogram match the PNG, and line colors and widths do too. Legend and Style tab labels are real names.
- Good: a 500-bar histogram costs about 500 small integers plus a two-entry palette.
- Bad: merges must remap palette indices. This is a small helper
(
colorIdxInto) shared by paging, tails and replay. - Bad: one more piece of wire contract. The Zod schema and
reference/mcp.mdmust follow any change. - Neutral: stored histogram overrides keep their index keys (
hist0), so saved styles still apply.