Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/remove-brand-themes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@hyperdx/app': minor
---

The app always uses ClickStack branding. Brand selection, the HyperDX palette, and the font picker are removed. Light, dark, and system color mode stay in Preferences.
2 changes: 1 addition & 1 deletion agent_docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Instead of stuffing all instructions into `AGENTS.md` (which goes into every con
- **`page_layout.md`** - PageHeader, PageLayout, and consistent page chrome (titles, actions, tool pages)
- **`naming_objects.md`** - How users name and rename objects (dashboards, saved searches, tiles) with `InlineNameInput`. Read before adding or changing any place where something gets a name.
- **`data_viz_colors.md`** - Chart, heatmap, and semantic status colors. Read before adding or changing any color in a chart, sparkline, heatmap, legend, or status pill.
- **`themes.md`** - How the brand theme system (HyperDX vs ClickStack) and color mode (light/dark/system) work. Read before changing anything in `packages/app/src/theme/`, adding semantic CSS variables, or touching brand-conditional UI.
- **`themes.md`** - ClickStack appearance and color mode (light/dark/system). Read before changing anything in `packages/app/src/theme/`, adding semantic CSS variables, or hard-coding a color, logo, or favicon.
- **`observability.md`** - Instrumentation standards (tracing, metrics, context) and the shared helpers. Read when adding or changing a feature.
- **`evals.md`** - MCP eval framework: dual-slot setup, running A/B comparisons between branches, interpreting results. Read before running evals or benchmarking MCP changes.

Expand Down
10 changes: 5 additions & 5 deletions agent_docs/code_style.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,14 +177,14 @@ This pattern cannot be enforced by ESLint and requires manual code review.

### Semantic component variants (Alert / Text / danger controls)

We ship **themed semantic variants** for `Alert`, `Text`, `Button`, and `ActionIcon` so callouts and status text are token-driven and consistent across the HyperDX and ClickStack brands (and light/dark). **Prefer these over raw Mantine palette colors** (`color="yellow"`, `color="red"`, `c="green"`, etc.).
We ship **semantic variants** for `Alert`, `Text`, `Button`, and `ActionIcon` so callouts and status text are token-driven in both light and dark. **Prefer these over raw Mantine palette colors** (`color="yellow"`, `color="red"`, `c="green"`, etc.).

The variant → token mapping is centralized in `packages/app/src/theme/themes/semanticVariants.ts` (the single source of truth, consumed by both brand themes' `mantineTheme.ts`). See the Storybook stories `Components/Alert` (interactive `Playground`) and `Design tokens/Semantic variants` for the full visual matrix.
The variant → token mapping is centralized in `packages/app/src/theme/semanticVariants.ts` (the single source of truth, consumed by `theme/mantineTheme.ts`). See the Storybook stories `Components/Alert` (interactive `Playground`) and `Design tokens/Semantic variants` for the full visual matrix.

**`Alert`** — `info` | `success` | `warning` | `danger`. Renders a tinted `-subtle` background with the title, icon, **and body text** in the semantic color token:

```tsx
// ✅ token-driven, works in both brands + light/dark, meets WCAG AA
// ✅ token-driven, works in light and dark, meets WCAG AA
<Alert variant="warning" title="Heads up">This may take a while.</Alert>
<Alert variant="danger" title="Failed">Could not save the alert.</Alert>

Expand Down Expand Up @@ -398,11 +398,11 @@ render those verbatim.

## Semantic design tokens (prefer over raw Mantine colors)

The UI is built with **Mantine components**, but **colors and surfaces** should follow the **semantic CSS custom properties** in our themes (`--color-*`, etc.), not ad-hoc Mantine palette values. Those tokens are defined in `packages/app/src/theme/themes/**/_tokens.scss`, align with a **Click UI**–style system, and keep HyperDX and ClickStack visually consistent. They are the path toward a shared design system even while Mantine remains the component layer.
The UI is built with **Mantine components**, but **colors and surfaces** should follow the **semantic CSS custom properties** in our themes (`--color-*`, etc.), not ad-hoc Mantine palette values. Those tokens are defined in `packages/app/src/theme/_tokens.scss`, align with a **Click UI**–style system, and are shared by every deployment. They are the path toward a shared design system even while Mantine remains the component layer.

- **Do**: Use Mantine for layout, components, and spacing; use **semantic tokens** for themed backgrounds, text colors, borders, and states (e.g. `style={{ color: 'var(--color-text-muted)' }}` or `style={{ border: '1px solid var(--color-border)' }}`).
- **Do not**: Rely on raw Mantine color props for app chrome and content when a semantic token exists — e.g. `c="gray.5"`, `bg="dark.7"`, or arbitrary `color="blue.4"` for surfaces that should match the rest of the product.
- **Reference**: `packages/app/src/theme/semanticColorsGrouped.ts` (token names), theme SCSS under `packages/app/src/theme/themes/`, and Storybook (`SemanticColors` and related theme stories) for a visual map.
- **Reference**: `packages/app/src/theme/semanticColorsGrouped.ts` (token names), `packages/app/src/theme/_tokens.scss`, and Storybook (`SemanticColors` and related theme stories) for a visual map.

Mantine theme overrides in `packages/app/src/theme/**` may map Mantine’s scale to our palette; that does not replace using **`var(--color-...)`** in new styling where you need explicit color control.

Expand Down
119 changes: 47 additions & 72 deletions agent_docs/data_viz_colors.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,12 @@ and ClickStack:
| `chart-gray` | `#9498a0` |

**Source of truth for categorical hues lives in JS.** The matching
`--color-chart-{hue}` CSS vars in both
`packages/app/src/theme/themes/hyperdx/_tokens.scss` and
`packages/app/src/theme/themes/clickstack/_tokens.scss` are a stylesheet-author
`--color-chart-{hue}` CSS vars, included from
`packages/app/src/theme/_tokens.scss`, are a stylesheet-author
affordance only — `getColorFromCSSVariable` and `getColorFromCSSToken` skip
`getComputedStyle` for categorical tokens and return values straight from
`CATEGORICAL_HEX_BY_TOKEN` in `utils.ts`. The palette is the same on every theme
today, so a DOM round-trip per series buys nothing.
`CATEGORICAL_HEX_BY_TOKEN` in `utils.ts`. A DOM round-trip per series buys
nothing.

The CSS vars exist for:

Expand All @@ -69,21 +68,20 @@ The CSS vars exist for:
add per-brand entries to `CATEGORICAL_HEX_BY_TOKEN`.

The categorical hues and semantic chart colors live in a single shared partial,
`packages/app/src/theme/themes/_chart-categorical-tokens.scss` (`chart-categorical-tokens`
and `chart-semantic-tokens` mixins). Both brand themes `@use` it and `@include`
both mixins inside their per-theme `chart-tokens` mixin. Each theme's
`chart-tokens` mixin is then `@include`'d inside both `[data-mantine-color-scheme]`
selectors. Sass inlines the bodies at each call site, so the emitted CSS has the
same per-scheme specificity as a hand-duplicated block would — but the source
lives in **one place** for both layers. **If you change a categorical hex in the
shared partial, change it in `CATEGORICAL_HEX_BY_TOKEN` in `utils.ts` too. If
you change a semantic hex, update `SEMANTIC_CHART_PALETTE` in `utils.ts` too —
the SCSS and JS sources are intentionally mirrored.**

Brand identity for charts is carried by non-chart UI chrome (Mantine accent,
sidebar gradient, Click UI globals), not by per-brand chart semantic colors —
`success` and `info` reuse categorical `chart-green` and `chart-blue` on both
brands.
`packages/app/src/theme/_chart-categorical-tokens.scss` (`chart-categorical-tokens`
and `chart-semantic-tokens` mixins). `theme/_tokens.scss` `@use`s it and
`@include`s both mixins inside its `chart-tokens` mixin, which is then
`@include`'d inside both `[data-mantine-color-scheme]` selectors. Sass inlines
the bodies at each call site, so the emitted CSS has the same per-scheme
specificity as a hand-duplicated block would — but the source lives in **one
place**. **If you change a categorical hex in the shared partial, change it in
`CATEGORICAL_HEX_BY_TOKEN` in `utils.ts` too. If you change a semantic hex,
update `SEMANTIC_CHART_PALETTE` in `utils.ts` too — the SCSS and JS sources are
intentionally mirrored.**

Chart series colors are not the brand accent. `success` and `info` reuse
categorical `chart-green` and `chart-blue`. The yellow ClickStack accent stays
in non-chart chrome (Mantine accent, sidebar, Click UI globals).

### Semantic chart colors (`--color-chart-{success|warning|error|info}`)

Expand All @@ -97,23 +95,22 @@ brands.
--color-chart-error-highlight
```

Defined in both `_tokens.scss` files. **Unified on both brands**: `success`
reuses categorical `chart-green` (`#3ca951`); `info` reuses categorical
`chart-blue` (`#437eef`). Warning and error use the same Observable hexes across
themes.
Defined in the shared `chart-semantic-tokens` mixin. `success` reuses
categorical `chart-green` (`#3ca951`); `info` reuses categorical `chart-blue`
(`#437eef`). Warning and error use the same Observable hexes.

Unlike the categorical hues, **the semantic CSS vars are read at runtime** via
`getComputedStyle` (see `getSemanticChartColor` in `utils.ts`). That keeps
inline `var(--color-chart-warning)` consumers like `LogLevel.tsx` reacting to
theme switches without a React re-render, and it lets JS callers like
`getChartColorSuccess()` return the correct hex for the active theme.
inline `var(--color-chart-warning)` consumers like `LogLevel.tsx` in sync with
the stylesheet, and it lets JS callers like `getChartColorSuccess()` return the
same hex.

### Single source of truth in TS (`packages/app/src/utils.ts`)

```text
CATEGORICAL_HEX_BY_TOKEN # { 'chart-blue': '#437eef', ... } — file-private,
# authoritative for categorical hues
SEMANTIC_CHART_PALETTE # { hyperdx: {...}, clickstack: {...} } — file-private,
SEMANTIC_CHART_PALETTE # { success, warning, error, info, …highlight } — file-private,
# SSR/fallback for the semantic CSS vars
COLORS # ordered hex array, derived from CATEGORICAL_PALETTE_TOKENS
```
Expand Down Expand Up @@ -153,14 +150,12 @@ Internals worth knowing:
`CATEGORICAL_HEX_BY_TOKEN` — same shortcut, no `getComputedStyle`.
- Semantic tokens (`chart-success`, `-warning`, `-error`) read
`--color-{token}` from `documentElement` via `getComputedStyle` and fall
back to the active theme's `SEMANTIC_CHART_PALETTE` entry when running
server-side or when the DOM read fails.
back to `SEMANTIC_CHART_PALETTE` when running server-side or when the DOM
read fails.
- `getSemanticChartColor(varName, key)` is the shared helper that backs the
`getChartColor{Success,Warning,Error,Info}()` readers. It uses
`detectActiveTheme()` (checks for the `theme-clickstack` class on `<html>`) to
pick the correct per-brand fallback.
- During SSR, semantic readers return the **HyperDX** default — the hydration
mismatch window is tiny because charts render after data fetch on the client.
`getChartColor{Success,Warning,Error,Info}()` readers. SSR and DOM-read
failures use `SEMANTIC_CHART_PALETTE`. Charts usually render after data
fetch on the client, so that fallback rarely reaches the DOM.

### Legacy `chart-1` … `chart-10` tokens

Expand Down Expand Up @@ -361,38 +356,21 @@ const slices = sorted.map((d, i) => ({

`ChartUtils.tsx → buildPieChartData` already does this.

## Per-theme considerations

The categorical palette is identical on both themes — Observable 10. Semantic
`success` and `info` also reuse categorical hues on both brands.

### HyperDX
## Color mode

- `--color-chart-success` uses categorical `chart-green` (`#3ca951`).
- `--color-chart-info` uses categorical `chart-blue` (`#437eef`), so info-level
logs and `getChartColorInfo()` render the same blue as multi-series slot 0.
- Multi-series charts start at brand blue (slot 0, `#437eef`) and proceed
through the canonical palette — brand identity is preserved via the Mantine
green accent and sidebar gradient, not via chart semantic colors.

### ClickStack

- `--color-chart-info` uses categorical `chart-blue` (`#437eef`, same as
`--click-global-color-text-link-default`), so info-level logs and
`getChartColorInfo()` render that blue.
- The brand accent is **yellow** (`--palette-brand-300: #faff69`). It is **not**
in the chart palette and should not be added — yellow on a light background
fails contrast, and yellow as a series color reads as "warning" in most
contexts.
- `--color-chart-success` uses categorical `chart-green` (`#3ca951`).
- `--color-chart-info` uses categorical `chart-blue` (`#437eef`, same as
`--click-global-color-text-link-default`), so info-level logs and
`getChartColorInfo()` render the brand blue.

### Both themes

- The dark/light scheme split is handled by CSS (the same vars get redefined
inside each scheme selector). React code does not need to branch on scheme
except for the heatmap palette.
- The chart vars in `_tokens.scss` are intentionally duplicated across the dark
and light blocks. If you change one, change the other.
- The chart vars are intentionally included in both the dark and light blocks.
Change the shared mixin, not one selector.

## Adding new entries

Expand All @@ -406,24 +384,23 @@ preference:
1. **Group small categories** into "Other" before charting.
2. **Reuse slots** with patterns/strokes/labels for disambiguation.
3. If you really must extend: add `--color-chart-{newhue}` to the shared
`_chart-categorical-tokens.scss` partial — one edit covers both brands and
both schemes via the existing `@include` chain. Then append
`_chart-categorical-tokens.scss` partial — one edit covers both schemes via
the existing `@include` chain. Then append
`'chart-{newhue}'` to `CHART_PALETTE_TOKENS` in `common-utils/src/types.ts`,
add the hex to `CATEGORICAL_HEX_BY_TOKEN` in `utils.ts`, and add a label
entry in `ColorSwatchInput.tsx` → `TOKEN_LABELS` and
`ChartColors.stories.tsx` → `COLOR_LABELS`.

### A new semantic color (e.g. `--color-chart-pending`)

1. Pick the hex (unified across brands unless you have a deliberate per-brand split).
1. Pick the hex.
2. Add `--color-chart-pending` and (if needed) `--color-chart-pending-highlight`
to the `@mixin chart-semantic-tokens` block in
`_chart-categorical-tokens.scss`. The mixin is `@include`'d in each theme's
`chart-tokens` mixin, which is `@include`'d in each scheme selector — one edit
covers dark and light for both brands. For a per-brand override only, declare
the var in that brand's `chart-tokens` mixin after the shared `@include`.
3. Add `pending` (and optionally `pendingHighlight`) to
`SEMANTIC_CHART_PALETTE.hyperdx` and `.clickstack` in `utils.ts`.
`_chart-categorical-tokens.scss`. The mixin is `@include`'d from
`theme/_tokens.scss` inside each scheme selector — one edit covers dark
and light.
3. Add `pending` (and optionally `pendingHighlight`) to `SEMANTIC_CHART_PALETTE`
in `utils.ts`.
4. Append `'chart-pending'` to `CHART_PALETTE_TOKENS` (and
`SEMANTIC_PALETTE_TOKENS` slice will pick it up automatically) in
`common-utils/src/types.ts`.
Expand Down Expand Up @@ -470,8 +447,6 @@ Why each is wrong:

## Pre-merge checklist for chart-touching PRs

- [ ] Toggled HyperDX ↔ ClickStack theme — semantic success and info stay
unified (chart-green / chart-blue); categorical palette stays identical.
- [ ] Toggled dark ↔ light — categorical and semantic colors stay legible on
both backgrounds; heatmap gradient flips palettes.
- [ ] Status indicators use `getChartColor*()` / `var(--color-chart-*)`, not raw
Expand All @@ -483,15 +458,15 @@ Why each is wrong:
`CATEGORICAL_HEX_BY_TOKEN` in `utils.ts`).
- [ ] If you added or changed a semantic hex, changed it in **both** places
(`chart-semantic-tokens` mixin in `_chart-categorical-tokens.scss`,
`SEMANTIC_CHART_PALETTE.{theme}` in `utils.ts`).
`SEMANTIC_CHART_PALETTE` in `utils.ts`).
- [ ] Storybook `Design tokens / Chart colors` still renders correctly.

## File reference summary

| What | Where |
| --------------------------------------------------- | -------------------------------------------------------------------------------- |
| Shared chart vars (10 categorical hues + semantics) | `packages/app/src/theme/themes/_chart-categorical-tokens.scss` |
| Per-theme `chart-tokens` mixin (`@include` chain) | `packages/app/src/theme/themes/hyperdx/_tokens.scss`, `clickstack/_tokens.scss` |
| Shared chart vars (10 categorical hues + semantics) | `packages/app/src/theme/_chart-categorical-tokens.scss` |
| `chart-tokens` mixin (`@include` chain) | `packages/app/src/theme/_tokens.scss` |
| JS palette objects + reader functions | `packages/app/src/utils.ts` |
| Palette token enum + legacy migration | `packages/common-utils/src/types.ts` |
| Multi-series wiring (`setLineColors` etc.) | `packages/app/src/ChartUtils.tsx` |
Expand Down
Loading
Loading