diff --git a/.changeset/remove-brand-themes.md b/.changeset/remove-brand-themes.md
new file mode 100644
index 0000000000..1440afbdd5
--- /dev/null
+++ b/.changeset/remove-brand-themes.md
@@ -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.
diff --git a/agent_docs/README.md b/agent_docs/README.md
index 2e3c1de63d..a8aafa3cb3 100644
--- a/agent_docs/README.md
+++ b/agent_docs/README.md
@@ -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.
diff --git a/agent_docs/code_style.md b/agent_docs/code_style.md
index cc4b5ff14c..a925429dce 100644
--- a/agent_docs/code_style.md
+++ b/agent_docs/code_style.md
@@ -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
This may take a while.Could not save the alert.
@@ -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.
diff --git a/agent_docs/data_viz_colors.md b/agent_docs/data_viz_colors.md
index 53fec06188..92d7960281 100644
--- a/agent_docs/data_viz_colors.md
+++ b/agent_docs/data_viz_colors.md
@@ -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:
@@ -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}`)
@@ -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
```
@@ -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 ``) 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
@@ -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
@@ -406,8 +384,8 @@ 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
@@ -415,15 +393,14 @@ preference:
### 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`.
@@ -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
@@ -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` |
diff --git a/agent_docs/themes.md b/agent_docs/themes.md
index e162f9c9a6..c322650805 100644
--- a/agent_docs/themes.md
+++ b/agent_docs/themes.md
@@ -1,179 +1,94 @@
-# Themes (HyperDX & ClickStack)
+# Appearance (ClickStack + color mode)
-> How the brand theme system works, how it interacts with light/dark color
-> mode, and where to make changes safely. Read this before touching anything
-> in `packages/app/src/theme/`, before adding a new brand, or before
-> hard-coding any color, logo, or favicon path in the app.
+> How colors, logos, and light/dark mode work. Read this before changing
+> anything in `packages/app/src/theme/`, adding a semantic CSS variable, or
+> hard-coding a color, logo, or favicon path.
>
-> For **chart colors specifically** (categorical palette, heatmap gradient,
-> semantic success/warn/error chart colors) see
-> [`data_viz_colors.md`](data_viz_colors.md) — it covers the chart-specific
-> rules in more depth. This doc covers everything else.
+> For chart colors see [`data_viz_colors.md`](data_viz_colors.md).
## TL;DR
-The app has **two independent theming concepts**:
-
-| Concept | Values | Who controls it | Stored in | What it affects |
-| ------------------ | ------------------------------ | --------------------------- | ------------------------------------------ | ----------------------------------------------------- |
-| **Brand theme** | `hyperdx` \| `clickstack` | Deployment (build/env) | `NEXT_PUBLIC_THEME` + html class | Branding: logos, favicons, accent colors, fonts |
-| **Color mode** | `light` \| `dark` \| `system` | End user (preferences UI) | `localStorage: hdx-user-preferences` | Light/dark appearance: backgrounds, text, borders |
-
-Each deployment ships **one** brand theme. Users can flip between light and
-dark inside that brand but cannot switch brands in production. In dev you
-can override the brand via `window.__HDX_THEME.set('clickstack')`.
-
-The runtime wiring is:
-
-1. Server-side (`pages/_document.tsx`) puts `theme-hyperdx` or
- `theme-clickstack` on `` based on `NEXT_PUBLIC_THEME`.
-2. An inline script (`SystemColorSchemeScript`) sets
- `data-mantine-color-scheme="light|dark"` on `` from
- `localStorage.hdx-user-preferences.colorMode` before React hydrates.
-3. SCSS in `packages/app/src/theme/themes/{brand}/_tokens.scss` defines all
- semantic CSS variables (`--color-bg-body`, `--color-text-primary`, …)
- inside `.theme-{brand}[data-mantine-color-scheme='{mode}']` selectors —
- one block per (brand × mode) combination, four blocks total.
-4. Mantine config (`{brand}/mantineTheme.ts`) sets `primaryColor`,
- font, spacing, and per-component overrides — most colors come back out
- via CSS vars rather than Mantine palette entries.
-5. React reads the active brand via `useAppTheme()` (rarely needed —
- prefer CSS vars).
+The product is ClickStack. There is no brand switch, no `NEXT_PUBLIC_THEME`,
+and no second palette.
-**Hard rules**:
+| Concept | Values | Who controls it | Stored in | What it affects |
+| -------------- | ----------------------------- | ------------------------- | ------------------------------------ | ------------------------------------------------- |
+| **Color mode** | `light` \| `dark` \| `system` | End user (preferences) | `localStorage: hdx-user-preferences` | Backgrounds, text, borders |
-- **Never** hard-code a hex/named color in a component. Use a semantic CSS
- var (`var(--color-bg-surface)`, `var(--color-text-primary)`, …).
-- **Never** branch on `themeName` to choose colors. The CSS var already
- resolves to the right value per brand. Branching is OK for *layout* or
- *content* differences (different copy, different logo placement) — not
- colors.
-- **Never** confuse `IS_CLICKHOUSE_BUILD` with the theme. That flag gates
- *features* (e.g. embedded mode, ClickHouse Cloud onboarding) and is
- unrelated to brand colors. A `clickstack`-themed build can have
- `IS_CLICKHOUSE_BUILD=false` and vice versa.
+The UI font is Inter. Mono faces (IBM Plex Mono, Roboto Mono) stay available
+for logs and code. The preferences modal does not offer a font picker.
-## Brand theme
+Color mode:
-### Where the themes are defined
+- Values: `'system' | 'light' | 'dark'`. Default `'system'`.
+- `'system'` follows `window.matchMedia('(prefers-color-scheme: dark)')`.
+- `SystemColorSchemeScript` sets `data-mantine-color-scheme` on ``
+ before React hydrates.
+- `useResolvedColorScheme()` returns `'light' | 'dark'` for `ThemeWrapper`,
+ which passes it to `MantineProvider` as `forceColorScheme`.
-Everything lives under `packages/app/src/theme/`:
+Older stored preferences used a `theme` key for light/dark. Migration in
+`useUserPreferences.tsx` rewrites that to `colorMode`. Don't reintroduce
+the old name.
-```text
-theme/
-├── index.ts # Registry, validation, DEFAULT_THEME, getDevThemeName
-├── types.ts # ThemeName, ThemeConfig, FaviconConfig types
-├── ThemeProvider.tsx # AppThemeProvider + useAppTheme/useWordmark/useLogomark hooks
-├── semanticColorsGrouped.ts # Grouping metadata for the storybook
-├── ChartColors.stories.tsx # Visual reference for chart palette
-├── SemanticColors.stories.tsx# Visual reference for semantic vars
-├── themes/
-│ ├── _base-tokens.scss # Fallback vars when no theme class is applied (SSR safety)
-│ ├── components.module.scss# Shared component overrides (slider marks, etc.)
-│ ├── hyperdx/
-│ │ ├── index.ts # ThemeConfig export: name, displayName, logos, favicon, mantineTheme
-│ │ ├── _tokens.scss # All semantic CSS vars (dark + light), scoped to .theme-hyperdx
-│ │ ├── mantineTheme.ts # Mantine palette + component overrides
-│ │ ├── Logomark.tsx # Icon-only logo (used in collapsed sidenav, favicons context)
-│ │ └── Wordmark.tsx # Full "HyperDX" wordmark
-│ └── clickstack/
-│ ├── index.ts # Same shape as hyperdx/index.ts
-│ ├── _tokens.scss # Same shape — adds Click UI palette + yellow brand
-│ ├── mantineTheme.ts # Same shape — yellow primaryColor
-│ ├── Logomark.tsx
-│ └── Wordmark.tsx
-└── __tests__/ # ThemeProvider + theme validation tests
-```
-
-Favicons live under `packages/app/public/favicons/{brand}/`. The
-`FaviconConfig` type in `types.ts` enforces the directory/filename
-convention via Zod.
-
-### Each `ThemeConfig` ships:
-
-```ts
-type ThemeConfig = {
- name: 'hyperdx' | 'clickstack';
- displayName: string; // 'HyperDX' | 'ClickStack' — used in UI copy
- cssClass: string; // 'theme-hyperdx' | 'theme-clickstack'
- mantineTheme: MantineThemeOverride;
- Wordmark: React.ComponentType;
- Logomark: React.ComponentType<{ size?: number }>;
- favicon: { svg, png32, png16, appleTouchIcon, themeColor };
-};
+```html
+
```
-The registry in `theme/index.ts` validates both themes against a Zod
-schema at module load time. In production, a failed validation throws;
-in development it logs and falls back to `hyperdx`.
+Tokens live in `packages/app/src/theme/_tokens.scss`, scoped to
+`[data-mantine-color-scheme='dark']` and
+`[data-mantine-color-scheme='light']`.
+`packages/app/src/theme/_base-tokens.scss` imports that file.
+Mantine component overrides are in `packages/app/src/theme/mantineTheme.ts`.
-### How brand resolution works at runtime
-
-| Phase | Source of truth | Notes |
-| --------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| SSR (`_document.tsx`) | `process.env.NEXT_PUBLIC_THEME` | Adds `theme-{name}` class to `` so SCSS vars resolve on the first paint. |
-| Initial React render | `propsThemeName ?? DEFAULT_THEME` in provider | Matches SSR — never reads localStorage during render to avoid hydration mismatch. |
-| Post-hydration (dev only) | `localStorage.hdx-dev-theme` via `getDevThemeName` | Updates state in a `useEffect`. Causes a one-frame flash; intentional for dev UX. |
-| Post-hydration (prod) | Stable — no reads from storage | `setTheme`/`toggleTheme` are no-ops in production. Confirmed by the `IS_DEV` gate. |
-
-`IS_DEV` is true when `NODE_ENV === 'development'` **or**
-`NEXT_PUBLIC_IS_LOCAL_MODE === 'true'` — so the OSS local-mode build also
-exposes the dev theme switcher in `UserPreferencesModal`.
-
-### Dev-mode theme switching
-
-Three ways to flip brand in dev:
-
-1. **UI**: open the user preferences modal — there's a "Brand theme"
- select gated on `isDev`.
-2. **Console**: `window.__HDX_THEME.set('clickstack')`,
- `window.__HDX_THEME.toggle()`, `window.__HDX_THEME.clear()`.
-3. **Storage**: set `localStorage.setItem('hdx-dev-theme', 'clickstack')`
- and reload.
+**Hard rules**:
-`clear()` removes the override and reverts to `NEXT_PUBLIC_THEME` (or
-`hyperdx` if unset).
+- Don't hard-code a hex or named color in a component. Use a semantic CSS
+ var (`var(--color-bg-surface)`, `var(--color-text-primary)`, …).
+- Don't branch on color mode to pick a semantic color. The var already
+ resolves. Branch only when a component truly needs a different asset
+ (for example the heatmap palette).
+- Don't confuse `IS_CLICKHOUSE_BUILD` with appearance. That flag gates
+ features (embedded mode, ClickHouse Cloud onboarding).
-## Color mode (light / dark / system)
+## Brand
-Color mode is **per-user**, persisted to
-`localStorage.hdx-user-preferences` under the `colorMode` key. Defined in
-`packages/app/src/useUserPreferences.tsx`:
+Product name, page titles, and logos come from `packages/app/src/brand/`.
+`useBrandDisplayName()` and `usePageTitle()` return ClickStack (plus
+`INSTANCE_TITLE_SUFFIX` on titles). `useWordmark()` and `useLogomark()`
+return the marks in that folder. Call sites use those hooks. A downstream
+build replaces `brand/` and keeps the same call sites. The color tokens
+stay shared.
-- Values: `'system' | 'light' | 'dark'`. Default `'system'`.
-- `'system'` follows `window.matchMedia('(prefers-color-scheme: dark)')`
- and reacts to changes.
-- The inline `SystemColorSchemeScript` (rendered very early) sets
- `data-mantine-color-scheme` before React hydrates so there's no flash.
-- `useResolvedColorScheme()` returns the resolved `'light' | 'dark'` for
- consumption by `ThemeWrapper` (which forwards it to `MantineProvider`
- as `forceColorScheme`).
-
-The user preferences storage also handles **migration from the legacy
-`theme` key** — older versions used `theme: 'light'|'dark'|'system'`;
-the migration code in `useUserPreferences.tsx` rewrites it to
-`colorMode` so existing users don't lose their preference. Don't
-re-introduce the old name.
-
-### Why two attributes (`class` + `data-attr`)?
+```tsx
+import { useLogomark, useWordmark } from '@/brand';
-```html
-
+function TopBar() {
+ const logo = useLogomark({ size: 24 });
+ const wordmark = useWordmark();
+ return (
+
+ {logo}
+ {wordmark}
+
+ );
+}
```
-The combined selector `.theme-clickstack[data-mantine-color-scheme='dark']`
-in `_tokens.scss` lets a single SCSS file define **all four** variants
-(2 brands × 2 modes) without duplication at the call site. Each block
-redefines `--color-bg-body`, `--color-text`, etc. for that specific
-combination. There is no JS branching on brand/mode for color
-resolution — CSS handles it.
+Favicons are static links in `packages/app/pages/_document.tsx`, under
+`packages/app/public/favicons/clickstack/`.
-## How to consume themes in code
+ClickStack specifics:
-### From CSS / SCSS
+- Mantine `primaryColor: 'yellow'`. The yellow ramp is the Click UI brand
+ palette (`--palette-brand-*`) from `theme/_tokens.scss`.
+- Accent `#faff69` (`--palette-brand-300`) is for links and outlines, not
+ chart series.
+- Warning tokens use Mantine `orange`, because yellow is the brand gold.
+- Most semantic vars reference Click UI globals (`--click-global-color-*`).
+- Tabler icons use `stroke-width: 1.5`.
-Just use the semantic vars. They resolve automatically based on the
-brand + mode classes on ``:
+## How to consume colors
```scss
.sidenav {
@@ -181,339 +96,57 @@ brand + mode classes on ``:
color: var(--color-text-sidenav-link);
border-right: 1px solid var(--color-border);
}
-
-.sidenav__link[data-active='true'] {
- background: var(--color-bg-sidenav-link-active);
- color: var(--color-text-sidenav-link-active);
-}
-```
-
-The full list of semantic vars is in
-`packages/app/src/theme/semanticColorsGrouped.ts` (used to build the
-storybook story). Categories: backgrounds, borders, text, icons,
-overlay, states, json (syntax highlight), charts.
-
-### From React (inline style, when CSS won't reach)
-
-Use the var string directly in `style={}` — `MantineProvider` doesn't
-need to know about it:
-
-```tsx
-
```
-Use **`useMantineColorScheme()`** when you genuinely need to branch on
-`light` vs `dark` (e.g. picking a heatmap palette). Don't branch on it
-to pick a semantic color — the var does that for you.
+The list of semantic vars is in
+`packages/app/src/theme/semanticColorsGrouped.ts`. In React, use the var
+string in `style={{}}`. Use `useMantineColorScheme()` only when you must
+branch on light vs dark.
-### From React (reading the active brand)
+### Semantic component variants
-```tsx
-import { useAppTheme, useThemeName, useBrandDisplayName } from '@/theme/ThemeProvider';
+Prefer these over raw Mantine palette props (`color="yellow"`, `c="green"`):
-function Header() {
- const { theme } = useAppTheme(); // full ThemeConfig
- const themeName = useThemeName(); // 'hyperdx' | 'clickstack'
- const brand = useBrandDisplayName(); // 'HyperDX' | 'ClickStack' — use in UI copy
- // …
-}
-```
+- ``
+- ``
+- `