docs(agent): single source of truth for data viz colors#2269
Conversation
Adds agent_docs/data_viz_colors.md so humans and agents have one place to look before touching anything that renders a color in a chart, sparkline, heatmap, legend, or status pill. The colors were already in the codebase but spread across four files (two _tokens.scss, utils.ts, DBHeatmapChart.tsx) with non-obvious coupling — a hex change in one place silently desyncs the others. What the doc covers: - The three independent viz color systems and how they're consumed: categorical 1-10 via --color-chart-N + getColorProps(), semantic success/warning/error + highlights via getChartColor*(), heatmap continuous via DBHeatmapChart's component-local darkPalette/lightPalette arrays. - Per-theme rationale: why HyperDX leads with brand green (#00c28a), why ClickStack leads with Observable blue (#437eef), and why the Click UI yellow accent intentionally stays out of the chart palette. - The "change a hex in all four places" rule for keeping hyperdx/_tokens.scss, clickstack/_tokens.scss, CHART_PALETTE, and CLICKSTACK_CHART_PALETTE / COLORS in sync. - Recipes for multi-series, status pills (var vs function form), heatmaps, and pie sorting. - Anti-patterns (hex strings, raw Mantine palette for status, importing private palette objects) and a pre-merge checklist. - File reference summary table for fast jumps. Wiring so the doc is discoverable from existing entry points: - agent_docs/README.md: added data_viz_colors.md to the Files list with a one-line trigger. - agent_docs/code_style.md: added a paragraph at the bottom of the existing "Semantic design tokens" section pointing at the new doc, since that's where someone reaching for c="green.5" on a chart lands first. Docs only — no code or runtime changes. Co-authored-by: Cursor <cursoragent@cursor.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
|
github-actions
Bot
added
the
review/tier-1
🟢 Tier 1 — TrivialDocs, images, lock files, or a dependency bump. No functional code changes detected. Why this tier:
Review process: Auto-merge once CI passes. No human review required. Stats
|
PR ReviewDocs-only PR. File/line references and exported-helper names check out. One factual inaccuracy worth fixing before merge — otherwise this is a useful consolidation.
No code or runtime changes, no security/test surface. Fix the slot-difference claim and this is good to merge. |
Deep ReviewScope: docs-only — Intent: Create a single source of truth that captures the three already-existing data-viz color systems (categorical, semantic, heatmap) and wire it into the existing agent-doc entry points. The doc stakes its value on being navigationally correct — its own test plan asks to spot-check that file/line references resolve. I verified every cited path, identifier, hex, and re-export claim against the code at the PR head. The brand/theme rationale, semantic/highlight hexes, palette ordering, ✅ No critical issues found. 🟡 P2 — recommended
🔵 P3 nitpicks (2)
Reviewers (4): correctness, testing, maintainability, project-standards. Testing gaps: none — the PR ships only documentation, and the author's pre-merge checklist (storybook render parity + file/line resolution + GitHub markdown render) is the appropriate verification surface for this change. |
E2E Test Results✅ All tests passed • 174 passed • 3 skipped • 1251s
Tests ran across 4 shards in parallel. |
2 participants
Summary
agent_docs/data_viz_colors.mdas a single source of truth for the three independent viz color systems already in the repo (categorical--color-chart-1..10, semantic--color-chart-{success,warning,error}+ highlights, and the component-local heatmapdarkPalette/lightPaletteinDBHeatmapChart.tsx).Filesentry inagent_docs/README.md, and a paragraph at the bottom of the "Semantic design tokens" section inagent_docs/code_style.md(since that's where someone reaching forc="green.5"on a chart lands first).Why
The colors were already in the codebase but spread across four files (
packages/app/src/theme/themes/{hyperdx,clickstack}/_tokens.scss,packages/app/src/utils.ts,packages/app/src/components/DBHeatmapChart.tsx) with non-obvious coupling. Specifically:CHART_PALETTE/CLICKSTACK_CHART_PALETTE/COLORSinutils.ts(used in SSR and inChartColors.stories.tsx).#00c28a, ClickStack = Observable blue#437eef) and that rationale wasn't written down.The doc captures these rules, the "change a hex in all four places" invariant, recipes for the four common consumption patterns (multi-series, status pill, heatmap, pie sort), anti-patterns, and a pre-merge checklist for chart-touching PRs.
Test plan
Design Tokens / Chart Colorsstory and confirm the doc's references (palette ordering, semantic color names, label list) match what's on screen in both themes and both schemes.hyperdx/_tokens.scss:97-117,clickstack/_tokens.scss:182-201and:383-402,utils.ts:359/378/398,DBHeatmapChart.tsx:147/156,deltaChartUtils.ts:98,ChartUtils.tsx:444).Made with Cursor