From e4ccb841a9d601b9571326d3554852470d033ae3 Mon Sep 17 00:00:00 2001
From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com>
Date: Tue, 12 May 2026 22:29:40 +0000
Subject: [PATCH 1/2] feat(app): refactor ColorSwatchInput to palette tokens
 [HDX-1360]

PR-1 of the issue #1360 series. The existing ColorSwatchInput
(orphan in OSS since #440) used a free-form ColorInput plus a
hand-picked 9-value hex array. Refactor it to a palette-only
picker driven by the unified 13-token palette landed in #1627:
ten categorical tokens (chart-1..chart-10) and three semantic
tokens (chart-success, chart-warning, chart-error).

Storing tokens (not hex) lets user color choices reflow across
themes and color modes without losing contrast or breaking the
WCAG ratios baked into the palette.

The component remains internal in this PR. PRs 2b through 6b
in the issue #1360 series wire it into ChartSeriesEditor,
ChartDisplaySettingsDrawer, and the number-tile thresholds /
reference-line editors. PR 7 mirrors the schema fields on the
external dashboards API. PR 8 documents the feature.

Highlights:
- New ChartPaletteToken type + CHART_PALETTE_TOKENS,
  CATEGORICAL_PALETTE_TOKENS, SEMANTIC_PALETTE_TOKENS arrays,
  isChartPaletteToken type guard in utils.ts.
- New getColorFromCSSToken(token) reads the matching
  --color-chart-* CSS variable, with SSR-safe fallbacks.
- New resolveChartColor(token, fallbackIndex, level) for PR 2b
  to plug into setLineColors / formatResponseForPieChart.
- ColorSwatchInput popover split into categorical / semantic
  sections; trigger uses --color-outline-focus for focus-visible;
  swatch buttons use aria-pressed; legacy non-token values are
  guarded to treat as unset.
- Storybook stories matrix: six isolated stories (picker
  mechanics) and five in-context mocks (InSeriesRow,
  InLineChart, InStackedBar, InNumberTile,
  InReferenceLineEditor). The in-context stories are
  storybook-only mocks; they do not import the real editor
  components.
- 13 RTL tests cover the rejection rules and keyboard nav.
---
 .../components/ColorSwatchInput.module.scss   |  39 ++
 .../components/ColorSwatchInput.stories.tsx   | 436 +++++++++++++++++-
 .../src/components/ColorSwatchInput.test.tsx  | 190 ++++++++
 .../app/src/components/ColorSwatchInput.tsx   | 245 +++++++---
 packages/app/src/utils.ts                     | 120 +++++
 5 files changed, 964 insertions(+), 66 deletions(-)
 create mode 100644 packages/app/src/components/ColorSwatchInput.module.scss
 create mode 100644 packages/app/src/components/ColorSwatchInput.test.tsx

diff --git a/packages/app/src/components/ColorSwatchInput.module.scss b/packages/app/src/components/ColorSwatchInput.module.scss
new file mode 100644
index 0000000000..90ab70122c
--- /dev/null
+++ b/packages/app/src/components/ColorSwatchInput.module.scss
@@ -0,0 +1,39 @@
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 2px 6px;
+  border-radius: 4px;
+  background-color: var(--color-bg-field);
+  border: 1px solid var(--color-border);
+  color: var(--color-text);
+  font-size: 11px;
+  line-height: 1;
+  cursor: pointer;
+  user-select: none;
+  transition:
+    background-color 100ms ease,
+    border-color 100ms ease;
+
+  &:hover {
+    background-color: var(--color-bg-field-highlighted);
+    border-color: var(--color-border);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--color-outline-focus);
+    outline-offset: 1px;
+  }
+
+  &[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.6;
+  }
+}
+
+.swatchButton {
+  &[data-selected] {
+    background-color: var(--color-bg-field-highlighted);
+    box-shadow: inset 0 0 0 1.5px var(--color-text);
+  }
+}
diff --git a/packages/app/src/components/ColorSwatchInput.stories.tsx b/packages/app/src/components/ColorSwatchInput.stories.tsx
index 50722f9560..2ec8f17bd0 100644
--- a/packages/app/src/components/ColorSwatchInput.stories.tsx
+++ b/packages/app/src/components/ColorSwatchInput.stories.tsx
@@ -1,16 +1,448 @@
 import React from 'react';
+import {
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Line,
+  LineChart,
+  ReferenceLine,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts';
+import {
+  Box,
+  Card,
+  Divider,
+  Group,
+  Select,
+  Stack,
+  Text,
+  TextInput,
+} from '@mantine/core';
 import type { Meta } from '@storybook/nextjs';
+import { IconChartLine } from '@tabler/icons-react';
+
+import {
+  CATEGORICAL_PALETTE_TOKENS,
+  CHART_PALETTE_TOKENS,
+  ChartPaletteToken,
+  getColorFromCSSToken,
+  SEMANTIC_PALETTE_TOKENS,
+} from '@/utils';
 
 import { ColorSwatchInput } from './ColorSwatchInput';
 
 const meta = {
+  title: 'ColorSwatchInput',
   component: ColorSwatchInput,
 } satisfies Meta<typeof ColorSwatchInput>;
 
 export default meta;
 
+// ---------------------------------------------------------------------------
+// Tier 1: isolated stories (picker mechanics)
+// ---------------------------------------------------------------------------
+
 export const Default = () => {
-  const [color, setColor] = React.useState<string | undefined>('#6610f2');
+  const [value, setValue] = React.useState<ChartPaletteToken | undefined>(
+    undefined,
+  );
+  return <ColorSwatchInput value={value} onChange={setValue} />;
+};
+
+export const Selected = () => {
+  const [value, setValue] = React.useState<ChartPaletteToken | undefined>(
+    'chart-1',
+  );
+  return <ColorSwatchInput value={value} onChange={setValue} />;
+};
+
+export const Disabled = () => (
+  <Group gap="md">
+    <ColorSwatchInput disabled />
+    <ColorSwatchInput value="chart-warning" disabled />
+  </Group>
+);
+
+export const WithCustomLabel = () => {
+  const [value, setValue] = React.useState<ChartPaletteToken | undefined>(
+    undefined,
+  );
+  return (
+    <ColorSwatchInput value={value} onChange={setValue} label="Series color" />
+  );
+};
+
+/**
+ * One trigger per token, all pre-selected. Renders the full matrix so the
+ * design review can compare swatch sizes, hover states, and per-token
+ * contrast across themes without opening the popover thirteen times.
+ */
+export const AllTokensSelected = () => (
+  <Stack gap="xs">
+    <Text size="sm" fw={500}>
+      Categorical
+    </Text>
+    <Group gap="xs" wrap="wrap">
+      {CATEGORICAL_PALETTE_TOKENS.map(token => (
+        <ColorSwatchInput key={token} value={token} />
+      ))}
+    </Group>
+    <Text size="sm" fw={500} mt="md">
+      Semantic
+    </Text>
+    <Group gap="xs" wrap="wrap">
+      {SEMANTIC_PALETTE_TOKENS.map(token => (
+        <ColorSwatchInput key={token} value={token} />
+      ))}
+    </Group>
+  </Stack>
+);
+
+/**
+ * Picker mounted alongside other form controls so reviewers can verify
+ * the focus order during keyboard nav (Tab into the picker, activate
+ * with Enter or Space, Tab between swatches, Esc closes).
+ */
+export const KeyboardNav = () => {
+  const [value, setValue] = React.useState<ChartPaletteToken | undefined>();
+  return (
+    <Stack gap="md" style={{ maxWidth: 380 }}>
+      <TextInput
+        label="Series name"
+        defaultValue="errors"
+        description="Tab from this input into the picker, activate, and pick a swatch."
+      />
+      <ColorSwatchInput value={value} onChange={setValue} />
+      <TextInput label="Tab target after the picker" placeholder="next field" />
+    </Stack>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Tier 2: in-context stories (product framing)
+//
+// Storybook-only mocks. No production imports of ChartSeriesEditor or
+// ChartDisplaySettingsDrawer; those land in PRs 2b through 6b. The mocks
+// approximate the layouts so the design review can rule on placement
+// before any consumer PR opens.
+// ---------------------------------------------------------------------------
+
+type SeriesMockData = {
+  name: string;
+  token: ChartPaletteToken | undefined;
+  lineStyle: 'solid' | 'dashed' | 'dotted';
+};
+
+const DEFAULT_SERIES_MOCK: SeriesMockData[] = [
+  { name: 'errors', token: 'chart-error', lineStyle: 'solid' },
+  { name: 'warnings', token: 'chart-warning', lineStyle: 'dashed' },
+  { name: 'successes', token: 'chart-success', lineStyle: 'solid' },
+];
 
-  return <ColorSwatchInput value={color} onChange={value => setColor(value)} />;
+const MOCK_TIME_DATA = Array.from({ length: 12 }).map((_, i) => ({
+  t: `${i}:00`,
+  errors: Math.round(20 + 8 * Math.sin(i / 2)),
+  warnings: Math.round(40 + 12 * Math.cos(i / 3)),
+  successes: Math.round(120 + 25 * Math.sin(i / 4 + 1)),
+}));
+
+const LINE_STYLE_DASHARRAY: Record<SeriesMockData['lineStyle'], string> = {
+  solid: '0',
+  dashed: '4 3',
+  dotted: '2 2',
+};
+
+function parseLineStyle(value: string | null): SeriesMockData['lineStyle'] {
+  if (value === 'dashed' || value === 'dotted') return value;
+  return 'solid';
+}
+
+function MockSeriesPreview({
+  series,
+  variant,
+  height = 140,
+}: {
+  series: SeriesMockData[];
+  variant: 'line' | 'bar';
+  height?: number;
+}) {
+  const ChartCmp = variant === 'line' ? LineChart : BarChart;
+  return (
+    <ResponsiveContainer width="100%" height={height}>
+      <ChartCmp
+        data={MOCK_TIME_DATA}
+        margin={{ left: 0, right: 12, top: 8, bottom: 0 }}
+      >
+        <CartesianGrid stroke="var(--color-border)" strokeDasharray="2 2" />
+        <XAxis dataKey="t" hide />
+        <YAxis hide />
+        <Tooltip cursor={false} />
+        {series.map(s => {
+          const color = s.token
+            ? getColorFromCSSToken(s.token)
+            : 'var(--color-text-muted)';
+          return variant === 'line' ? (
+            <Line
+              key={s.name}
+              type="monotone"
+              dataKey={s.name}
+              stroke={color}
+              strokeDasharray={LINE_STYLE_DASHARRAY[s.lineStyle]}
+              dot={false}
+              strokeWidth={2}
+              isAnimationActive={false}
+            />
+          ) : (
+            <Bar
+              key={s.name}
+              dataKey={s.name}
+              stackId="stack"
+              fill={color}
+              isAnimationActive={false}
+            />
+          );
+        })}
+      </ChartCmp>
+    </ResponsiveContainer>
+  );
+}
+
+function SeriesRow({
+  series,
+  onChange,
+}: {
+  series: SeriesMockData;
+  onChange: (next: SeriesMockData) => void;
+}) {
+  return (
+    <Group
+      gap="xs"
+      wrap="nowrap"
+      align="center"
+      style={{
+        padding: '6px 8px',
+        border: '1px solid var(--color-border)',
+        borderRadius: 4,
+        background: 'var(--color-bg-field)',
+      }}
+    >
+      <Text size="xs" style={{ minWidth: 90 }}>
+        {series.name}
+      </Text>
+      <Text size="xs" c="dimmed">
+        count(*)
+      </Text>
+      <Box style={{ flex: 1 }} />
+      <ColorSwatchInput
+        value={series.token}
+        onChange={token => onChange({ ...series, token })}
+      />
+      <Select
+        size="xs"
+        w={92}
+        value={series.lineStyle}
+        onChange={v => onChange({ ...series, lineStyle: parseLineStyle(v) })}
+        data={[
+          { value: 'solid', label: 'Solid' },
+          { value: 'dashed', label: 'Dashed' },
+          { value: 'dotted', label: 'Dotted' },
+        ]}
+      />
+    </Group>
+  );
+}
+
+function useSeriesList() {
+  const [seriesList, setSeriesList] =
+    React.useState<SeriesMockData[]>(DEFAULT_SERIES_MOCK);
+  const updateAt = React.useCallback((idx: number, next: SeriesMockData) => {
+    setSeriesList(curr => curr.map((s, i) => (i === idx ? next : s)));
+  }, []);
+  return { seriesList, updateAt };
+}
+
+/**
+ * Mocks the eventual `ChartSeriesEditor` layout: a stack of series rows,
+ * each carrying the palette picker + line-style dropdown inline. A small
+ * Recharts preview above the rows reacts to picks in real time.
+ */
+export const InSeriesRow = () => {
+  const { seriesList, updateAt } = useSeriesList();
+  return (
+    <Stack gap="sm" style={{ maxWidth: 540 }}>
+      <Card withBorder padding="sm">
+        <Group gap="xs" mb={6}>
+          <IconChartLine size={14} stroke={1.5} />
+          <Text size="sm" fw={500}>
+            Line tile preview
+          </Text>
+        </Group>
+        <MockSeriesPreview series={seriesList} variant="line" />
+      </Card>
+      <Stack gap={6}>
+        {seriesList.map((s, i) => (
+          <SeriesRow
+            key={s.name}
+            series={s}
+            onChange={next => updateAt(i, next)}
+          />
+        ))}
+      </Stack>
+    </Stack>
+  );
 };
+
+function InTimeChart({ variant }: { variant: 'line' | 'bar' }) {
+  const { seriesList, updateAt } = useSeriesList();
+  return (
+    <Group align="stretch" gap="md" wrap="nowrap" style={{ maxWidth: 880 }}>
+      <Card withBorder padding="sm" style={{ flex: 1 }}>
+        <Text size="sm" fw={500} mb={6}>
+          {variant === 'line'
+            ? 'Errors / warnings / successes over time'
+            : 'Stacked bar tile preview'}
+        </Text>
+        <MockSeriesPreview series={seriesList} variant={variant} height={220} />
+      </Card>
+      <Card withBorder padding="sm" w={300}>
+        <Text size="xs" c="dimmed" mb={6}>
+          Series
+        </Text>
+        <Stack gap={6}>
+          {seriesList.map((s, i) => (
+            <SeriesRow
+              key={s.name}
+              series={s}
+              onChange={next => updateAt(i, next)}
+            />
+          ))}
+        </Stack>
+      </Card>
+    </Group>
+  );
+}
+
+/** Production-shaped layout for a line tile: chart on top, series panel on the side. */
+export const InLineChart = () => <InTimeChart variant="line" />;
+
+/** Same shape as `InLineChart` but driving a stacked-bar tile. */
+export const InStackedBar = () => <InTimeChart variant="bar" />;
+
+/**
+ * Mocked number tile: the picker drives the static color of the rendered
+ * value. The threshold editor with operator / value / per-rule colors is
+ * out of scope for this PR and lands with PR 6b; for the design review we
+ * only need to lock in placement of the color picker.
+ */
+export const InNumberTile = () => {
+  const [color, setColor] = React.useState<ChartPaletteToken | undefined>(
+    'chart-success',
+  );
+  const resolved = color ? getColorFromCSSToken(color) : 'var(--color-text)';
+  return (
+    <Group align="stretch" gap="md" wrap="nowrap" style={{ maxWidth: 600 }}>
+      <Card withBorder padding="md" style={{ flex: 1 }}>
+        <Text size="xs" c="dimmed" mb={6}>
+          Request rate (rps)
+        </Text>
+        <Text
+          style={{
+            fontSize: 48,
+            fontWeight: 600,
+            color: resolved,
+            lineHeight: 1,
+          }}
+        >
+          1,234
+        </Text>
+      </Card>
+      <Card withBorder padding="md" w={260}>
+        <Stack gap="xs">
+          <Text size="xs" c="dimmed">
+            Static color
+          </Text>
+          <ColorSwatchInput value={color} onChange={setColor} />
+          <Divider my={4} />
+          <Text size="xs" c="dimmed">
+            Thresholds (preview only)
+          </Text>
+          <Text size="xs">≥ 500 &rarr; chart-error</Text>
+          <Text size="xs">≥ 100 &rarr; chart-warning</Text>
+        </Stack>
+      </Card>
+    </Group>
+  );
+};
+
+/**
+ * Mocked reference-line editor focused on the picker. The value / label /
+ * style inputs that wrap it on the editor side land with PR 5b; for this
+ * PR we only need to lock in how the picker reads inside the editor.
+ */
+export const InReferenceLineEditor = () => {
+  const [token, setToken] = React.useState<ChartPaletteToken | undefined>(
+    'chart-warning',
+  );
+  return (
+    <Stack gap="sm" style={{ maxWidth: 560 }}>
+      <Card withBorder padding="sm">
+        <Text size="sm" fw={500} mb={6}>
+          Line chart with reference line
+        </Text>
+        <ResponsiveContainer width="100%" height={160}>
+          <LineChart
+            data={MOCK_TIME_DATA}
+            margin={{ left: 0, right: 12, top: 8, bottom: 0 }}
+          >
+            <CartesianGrid stroke="var(--color-border)" strokeDasharray="2 2" />
+            <XAxis dataKey="t" hide />
+            <YAxis hide domain={[0, 200]} />
+            <Tooltip cursor={false} />
+            <Line
+              type="monotone"
+              dataKey="warnings"
+              stroke={getColorFromCSSToken('chart-2')}
+              dot={false}
+              strokeWidth={2}
+              isAnimationActive={false}
+            />
+            <ReferenceLine
+              y={100}
+              stroke={token ? getColorFromCSSToken(token) : 'transparent'}
+              strokeDasharray="4 3"
+              label={{
+                value: 'SLA',
+                position: 'insideTopRight',
+                fill: token ? getColorFromCSSToken(token) : undefined,
+                fontSize: 11,
+              }}
+            />
+          </LineChart>
+        </ResponsiveContainer>
+      </Card>
+      <Card withBorder padding="sm">
+        <Group gap="md" align="center">
+          <Text size="xs" c="dimmed">
+            Reference-line color
+          </Text>
+          <ColorSwatchInput value={token} onChange={setToken} />
+        </Group>
+      </Card>
+    </Stack>
+  );
+};
+
+/**
+ * Reference: every available palette token, rendered as a row of pre-selected
+ * pickers. Useful as a single screenshot for design review.
+ */
+export const TokensReference = () => (
+  <Group gap={4} wrap="wrap" style={{ maxWidth: 800 }}>
+    {CHART_PALETTE_TOKENS.map(token => (
+      <ColorSwatchInput key={token} value={token} />
+    ))}
+  </Group>
+);
diff --git a/packages/app/src/components/ColorSwatchInput.test.tsx b/packages/app/src/components/ColorSwatchInput.test.tsx
new file mode 100644
index 0000000000..e56cf43748
--- /dev/null
+++ b/packages/app/src/components/ColorSwatchInput.test.tsx
@@ -0,0 +1,190 @@
+import { fireEvent, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { CHART_PALETTE_TOKENS, ChartPaletteToken } from '@/utils';
+
+import { ColorSwatchInput } from './ColorSwatchInput';
+
+describe('ColorSwatchInput', () => {
+  it('renders an unselected trigger by default', () => {
+    renderWithMantine(<ColorSwatchInput />);
+
+    const trigger = screen.getByTestId('color-swatch-input-trigger');
+    expect(trigger).toHaveTextContent(/color/i);
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(trigger).toHaveAttribute(
+      'aria-label',
+      expect.stringMatching(/pick/i),
+    );
+  });
+
+  it('opens the palette popover when the trigger is clicked', async () => {
+    const user = userEvent.setup();
+    renderWithMantine(<ColorSwatchInput />);
+
+    await user.click(screen.getByTestId('color-swatch-input-trigger'));
+
+    expect(
+      await screen.findByTestId('color-swatch-option-chart-1'),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId('color-swatch-option-chart-success'),
+    ).toBeInTheDocument();
+  });
+
+  it('exposes a swatch for every palette token', async () => {
+    const user = userEvent.setup();
+    renderWithMantine(<ColorSwatchInput />);
+
+    await user.click(screen.getByTestId('color-swatch-input-trigger'));
+
+    for (const token of CHART_PALETTE_TOKENS) {
+      expect(
+        await screen.findByTestId(`color-swatch-option-${token}`),
+      ).toBeInTheDocument();
+    }
+  });
+
+  it('calls onChange with the picked palette token', async () => {
+    const onChange = jest.fn();
+    const user = userEvent.setup();
+    renderWithMantine(<ColorSwatchInput onChange={onChange} />);
+
+    await user.click(screen.getByTestId('color-swatch-input-trigger'));
+    await user.click(
+      await screen.findByTestId('color-swatch-option-chart-warning'),
+    );
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith('chart-warning');
+  });
+
+  it('reflects the selected token in the trigger', () => {
+    renderWithMantine(<ColorSwatchInput value="chart-error" />);
+
+    const trigger = screen.getByTestId('color-swatch-input-trigger');
+    expect(trigger).toHaveTextContent(/error/i);
+    expect(trigger).toHaveAttribute(
+      'aria-label',
+      expect.stringMatching(/error/i),
+    );
+  });
+
+  it('marks only the selected swatch as pressed', async () => {
+    const user = userEvent.setup();
+    renderWithMantine(<ColorSwatchInput value="chart-2" />);
+
+    await user.click(screen.getByTestId('color-swatch-input-trigger'));
+
+    const selected = await screen.findByTestId('color-swatch-option-chart-2');
+    const other = await screen.findByTestId('color-swatch-option-chart-3');
+    expect(selected).toHaveAttribute('aria-pressed', 'true');
+    expect(other).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  it('clears the selection via the Clear button', async () => {
+    const onChange = jest.fn();
+    const user = userEvent.setup();
+    renderWithMantine(<ColorSwatchInput value="chart-1" onChange={onChange} />);
+
+    await user.click(screen.getByTestId('color-swatch-input-trigger'));
+    await user.click(await screen.findByTestId('color-swatch-input-clear'));
+
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith(undefined);
+  });
+
+  it('does not show a Clear button when no value is set', async () => {
+    const user = userEvent.setup();
+    renderWithMantine(<ColorSwatchInput />);
+
+    await user.click(screen.getByTestId('color-swatch-input-trigger'));
+
+    expect(
+      await screen.findByTestId('color-swatch-option-chart-1'),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId('color-swatch-input-clear'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('treats a legacy non-token value as unset and never echoes it back', async () => {
+    const onChange = jest.fn();
+    const user = userEvent.setup();
+    renderWithMantine(
+      <ColorSwatchInput
+        // Simulate a legacy hex string surviving from before the palette refactor.
+        value={'#ff0000' as unknown as ChartPaletteToken}
+        onChange={onChange}
+      />,
+    );
+
+    const trigger = screen.getByTestId('color-swatch-input-trigger');
+    expect(trigger).toHaveTextContent(/color/i);
+    expect(trigger).toHaveAttribute(
+      'aria-label',
+      expect.stringMatching(/pick/i),
+    );
+
+    await user.click(trigger);
+    // The legacy value should not pre-select any swatch.
+    for (const token of CHART_PALETTE_TOKENS) {
+      expect(
+        await screen.findByTestId(`color-swatch-option-${token}`),
+      ).toHaveAttribute('aria-pressed', 'false');
+    }
+  });
+
+  it('respects disabled and does not open the popover', async () => {
+    const user = userEvent.setup();
+    renderWithMantine(<ColorSwatchInput disabled />);
+
+    const trigger = screen.getByTestId('color-swatch-input-trigger');
+    expect(trigger).toHaveAttribute('data-disabled');
+
+    await user.click(trigger);
+    expect(
+      screen.queryByTestId('color-swatch-option-chart-1'),
+    ).not.toBeInTheDocument();
+  });
+
+  it('closes the popover after a selection', async () => {
+    const user = userEvent.setup();
+    renderWithMantine(<ColorSwatchInput />);
+
+    await user.click(screen.getByTestId('color-swatch-input-trigger'));
+    await user.click(await screen.findByTestId('color-swatch-option-chart-3'));
+
+    await waitFor(() => {
+      expect(
+        screen.queryByTestId('color-swatch-option-chart-3'),
+      ).not.toBeInTheDocument();
+    });
+  });
+
+  it('uses the custom label in the trigger when no value is set', () => {
+    renderWithMantine(<ColorSwatchInput label="Series color" />);
+    const trigger = screen.getByTestId('color-swatch-input-trigger');
+    expect(trigger).toHaveTextContent(/series color/i);
+  });
+
+  it('keyboard activates the trigger and selects a swatch with Enter', async () => {
+    const onChange = jest.fn();
+    renderWithMantine(<ColorSwatchInput onChange={onChange} />);
+
+    const trigger = screen.getByTestId('color-swatch-input-trigger');
+    trigger.focus();
+    expect(trigger).toHaveFocus();
+
+    fireEvent.keyDown(trigger, { key: 'Enter', code: 'Enter' });
+    fireEvent.click(trigger);
+
+    const firstSwatch = await screen.findByTestId(
+      'color-swatch-option-chart-1',
+    );
+    firstSwatch.focus();
+    fireEvent.click(firstSwatch);
+
+    expect(onChange).toHaveBeenCalledWith('chart-1');
+  });
+});
diff --git a/packages/app/src/components/ColorSwatchInput.tsx b/packages/app/src/components/ColorSwatchInput.tsx
index 359cd09cea..d89960a26e 100644
--- a/packages/app/src/components/ColorSwatchInput.tsx
+++ b/packages/app/src/components/ColorSwatchInput.tsx
@@ -2,101 +2,218 @@ import React from 'react';
 import {
   ActionIcon,
   Button,
-  ColorInput,
   ColorSwatch,
   Group,
   Popover,
   SimpleGrid,
+  Stack,
   Text,
+  Tooltip,
+  UnstyledButton,
+  VisuallyHidden,
 } from '@mantine/core';
+import { IconCircleOff, IconX } from '@tabler/icons-react';
 
-// Different from auto colors, TBD
-const COLOR_PRESETS = [
-  '#e60049',
-  '#0bb4ff',
-  '#50e991',
-  '#e6d800',
-  '#9b19f5',
-  '#ffa300',
-  '#dc0ab4',
-  '#b3d4ff',
-  '#00bfa0',
-];
+import {
+  CATEGORICAL_PALETTE_TOKENS,
+  ChartPaletteToken,
+  getColorFromCSSToken,
+  isChartPaletteToken,
+  SEMANTIC_PALETTE_TOKENS,
+} from '@/utils';
+
+import classes from './ColorSwatchInput.module.scss';
 
 const Z_INDEX = 9999;
 
+const TOKEN_LABELS: Record<ChartPaletteToken, string> = {
+  'chart-1': 'Color 1',
+  'chart-2': 'Color 2',
+  'chart-3': 'Color 3',
+  'chart-4': 'Color 4',
+  'chart-5': 'Color 5',
+  'chart-6': 'Color 6',
+  'chart-7': 'Color 7',
+  'chart-8': 'Color 8',
+  'chart-9': 'Color 9',
+  'chart-10': 'Color 10',
+  'chart-success': 'Success',
+  'chart-warning': 'Warning',
+  'chart-error': 'Error',
+};
+
+export type ColorSwatchInputProps = {
+  /** Currently selected palette token, if any. */
+  value?: ChartPaletteToken;
+  /** Called with the new token, or `undefined` when the user clears the picker. */
+  onChange?: (value?: ChartPaletteToken) => void;
+  /** Optional label shown in the trigger when no color is selected. */
+  label?: string;
+  /** Disable the trigger and prevent opening the popover. */
+  disabled?: boolean;
+  /** Accessible label used when no `label` prop is provided. */
+  ariaLabel?: string;
+};
+
+/**
+ * Palette picker for chart series, number-tile, threshold, and
+ * reference-line colors. Always persists a `ChartPaletteToken`, never
+ * a raw hex value, so user choices reflow correctly across themes and
+ * light / dark color modes.
+ *
+ * See `notes/repo-conventions/hyperdx/tile-styling.md` for the full
+ * design decision (palette-only, no free-form hex).
+ */
 export const ColorSwatchInput = ({
   value,
   onChange,
-}: {
-  value?: string;
-  onChange?: (value?: string) => void;
-}) => {
+  label = 'Color',
+  disabled = false,
+  ariaLabel,
+}: ColorSwatchInputProps) => {
   const [opened, setOpened] = React.useState(false);
 
-  const handleChange = (color?: string) => {
-    onChange?.(color);
+  // Guard against legacy values that are not in the current palette.
+  const safeValue = value && isChartPaletteToken(value) ? value : undefined;
+
+  const handleChange = (next?: ChartPaletteToken) => {
+    onChange?.(next);
     setOpened(false);
   };
 
+  const triggerAriaLabel = ariaLabel
+    ? ariaLabel
+    : safeValue
+      ? `${label}: ${TOKEN_LABELS[safeValue]}`
+      : `Pick ${label.toLowerCase()}`;
+
   return (
     <Popover
-      position="bottom"
+      position="bottom-start"
       shadow="md"
       opened={opened}
       onChange={setOpened}
-      closeOnClickOutside={false}
+      withinPortal
+      trapFocus
+      closeOnEscape
+      closeOnClickOutside
+      disabled={disabled}
     >
       <Popover.Target>
-        <Button
-          size="compact-xs"
-          variant="secondary"
-          onClick={() => setOpened(o => !o)}
+        <UnstyledButton
+          type="button"
+          disabled={disabled}
+          onClick={() => !disabled && setOpened(o => !o)}
+          aria-haspopup="dialog"
+          aria-expanded={opened}
+          aria-label={triggerAriaLabel}
+          data-testid="color-swatch-input-trigger"
+          className={classes.trigger}
+          data-disabled={disabled || undefined}
         >
-          {value ? (
-            <Group gap="xs">
-              <Text size="xs">Color</Text>
-              <ColorSwatch color={value} size={14} />
-            </Group>
-          ) : (
-            <Text size="xs">Choose color</Text>
-          )}
-        </Button>
+          <Group gap={6} wrap="nowrap" align="center">
+            {safeValue ? (
+              <ColorSwatch
+                color={getColorFromCSSToken(safeValue)}
+                size={14}
+                withShadow={false}
+              />
+            ) : (
+              <IconCircleOff size={14} stroke={1.5} aria-hidden />
+            )}
+            <Text size="xs" c="dimmed">
+              {safeValue ? TOKEN_LABELS[safeValue] : label}
+            </Text>
+          </Group>
+        </UnstyledButton>
       </Popover.Target>
       <Popover.Dropdown p="xs" style={{ zIndex: Z_INDEX }}>
-        <ColorInput
-          size="xs"
-          value={value}
-          onChange={color => onChange?.(color)}
-          placeholder="#000000"
-          radius="md"
-          variant="filled"
-          w="130"
-          onBlur={() => setOpened(false)}
-          popoverProps={{
-            zIndex: Z_INDEX + 1,
-            closeOnClickOutside: false,
-          }}
-        />
-        <SimpleGrid cols={4} spacing={0} verticalSpacing={0} my="xs">
-          {COLOR_PRESETS.map(color => (
-            <ActionIcon
-              key={color}
-              size="md"
-              variant={value === color ? 'filled' : 'subtle'}
+        <Stack gap="xs">
+          <div>
+            <VisuallyHidden>Categorical colors</VisuallyHidden>
+            <Text size="xs" c="dimmed" mb={4} aria-hidden>
+              Categorical
+            </Text>
+            <SwatchGrid
+              tokens={CATEGORICAL_PALETTE_TOKENS}
+              value={safeValue}
+              onSelect={handleChange}
+            />
+          </div>
+          <div>
+            <VisuallyHidden>Semantic colors</VisuallyHidden>
+            <Text size="xs" c="dimmed" mb={4} aria-hidden>
+              Semantic
+            </Text>
+            <SwatchGrid
+              tokens={SEMANTIC_PALETTE_TOKENS}
+              value={safeValue}
+              onSelect={handleChange}
+              cols={3}
+            />
+          </div>
+          {safeValue && (
+            <Button
+              size="compact-xs"
+              variant="subtle"
               color="gray"
-              onClick={() => handleChange(color)}
+              leftSection={<IconX size={12} stroke={1.5} />}
+              onClick={() => handleChange(undefined)}
+              data-testid="color-swatch-input-clear"
             >
-              <ColorSwatch color={color} size={14} />
-            </ActionIcon>
-          ))}
-        </SimpleGrid>
-        {value && (
-          <Button size="compact-xs" color="gray" onClick={() => handleChange()}>
-            Clear
-          </Button>
-        )}
+              Clear
+            </Button>
+          )}
+        </Stack>
       </Popover.Dropdown>
     </Popover>
   );
 };
+
+function SwatchGrid({
+  tokens,
+  value,
+  onSelect,
+  cols = 5,
+}: {
+  tokens: readonly ChartPaletteToken[];
+  value: ChartPaletteToken | undefined;
+  onSelect: (token: ChartPaletteToken) => void;
+  cols?: number;
+}) {
+  return (
+    <SimpleGrid cols={cols} spacing={4} verticalSpacing={4}>
+      {tokens.map(token => {
+        const selected = value === token;
+        return (
+          <Tooltip
+            key={token}
+            label={TOKEN_LABELS[token]}
+            withArrow
+            openDelay={200}
+            zIndex={Z_INDEX + 1}
+          >
+            <ActionIcon
+              size="md"
+              radius="sm"
+              variant="subtle"
+              color="gray"
+              onClick={() => onSelect(token)}
+              data-testid={`color-swatch-option-${token}`}
+              data-selected={selected || undefined}
+              aria-label={TOKEN_LABELS[token]}
+              aria-pressed={selected}
+              className={classes.swatchButton}
+            >
+              <ColorSwatch
+                color={getColorFromCSSToken(token)}
+                size={16}
+                withShadow={false}
+              />
+            </ActionIcon>
+          </Tooltip>
+        );
+      })}
+    </SimpleGrid>
+  );
+}
diff --git a/packages/app/src/utils.ts b/packages/app/src/utils.ts
index 294f31946f..ad145ed413 100644
--- a/packages/app/src/utils.ts
+++ b/packages/app/src/utils.ts
@@ -408,6 +408,56 @@ export const COLORS = [
   CHART_PALETTE.gray, // 10
 ];
 
+/**
+ * The set of palette tokens a user can pick for chart series colors,
+ * number-tile colors, reference lines, and threshold rules.
+ *
+ * Tokens map to CSS variables in `packages/app/src/theme/themes/<theme>/_tokens.scss`:
+ *   chart-1 .. chart-10        -> --color-chart-1 .. --color-chart-10
+ *   chart-success/warning/error -> --color-chart-{success|warning|error}
+ *
+ * Storing tokens (not hex) lets user choices reflow correctly across
+ * themes and color modes; see notes/repo-conventions/hyperdx/tile-styling.md.
+ */
+export const CHART_PALETTE_TOKENS = [
+  'chart-1',
+  'chart-2',
+  'chart-3',
+  'chart-4',
+  'chart-5',
+  'chart-6',
+  'chart-7',
+  'chart-8',
+  'chart-9',
+  'chart-10',
+  'chart-success',
+  'chart-warning',
+  'chart-error',
+] as const;
+
+export type ChartPaletteToken = (typeof CHART_PALETTE_TOKENS)[number];
+
+/** Categorical tokens (chart-1 .. chart-10). */
+export const CATEGORICAL_PALETTE_TOKENS = CHART_PALETTE_TOKENS.slice(
+  0,
+  10,
+) as readonly ChartPaletteToken[];
+
+/** Semantic tokens (success / warning / error). */
+export const SEMANTIC_PALETTE_TOKENS = CHART_PALETTE_TOKENS.slice(
+  10,
+) as readonly ChartPaletteToken[];
+
+/** Type guard for runtime validation of an unknown token string. */
+export function isChartPaletteToken(
+  value: unknown,
+): value is ChartPaletteToken {
+  return (
+    typeof value === 'string' &&
+    (CHART_PALETTE_TOKENS as readonly string[]).includes(value)
+  );
+}
+
 /**
  * Detects the active theme by checking for theme classes on documentElement.
  * Returns 'clickstack' if theme-clickstack class is present, 'hyperdx' otherwise.
@@ -465,6 +515,55 @@ function getColorFromCSSVariable(index: number): string {
   return COLORS[index % colorArrayLength];
 }
 
+/**
+ * Reads a chart color from a palette token by resolving the matching
+ * CSS variable (`--color-chart-<token-without-prefix>` for categorical
+ * tokens, `--color-chart-{success|warning|error}` for semantic tokens).
+ *
+ * Falls back to the appropriate slot in `COLORS` (categorical) or the
+ * HyperDX semantic palette (success / warning / error) when running
+ * server-side or when `getComputedStyle` fails.
+ *
+ * @example
+ *   getColorFromCSSToken('chart-1')        // brand green
+ *   getColorFromCSSToken('chart-warning')  // theme-aware warning
+ */
+export function getColorFromCSSToken(token: ChartPaletteToken): string {
+  const cssVarName = `--color-${token}`;
+
+  if (typeof window === 'undefined') {
+    return paletteTokenSSRFallback(token);
+  }
+
+  try {
+    const computedStyle = getComputedStyle(document.documentElement);
+    const color = computedStyle.getPropertyValue(cssVarName).trim();
+    if (color && color !== '') {
+      return color;
+    }
+  } catch {
+    // Fallback if getComputedStyle fails
+  }
+
+  return paletteTokenSSRFallback(token);
+}
+
+function paletteTokenSSRFallback(token: ChartPaletteToken): string {
+  switch (token) {
+    case 'chart-success':
+      return CHART_PALETTE.green;
+    case 'chart-warning':
+      return CHART_PALETTE.orange;
+    case 'chart-error':
+      return CHART_PALETTE.red;
+    default: {
+      // Categorical token: chart-N where N is 1..10
+      const index = Number(token.slice('chart-'.length)) - 1;
+      return COLORS[index] ?? COLORS[0];
+    }
+  }
+}
+
 export function hashCode(str: string) {
   let hash = 0,
     i,
@@ -617,6 +716,27 @@ export const getColorProps = (index: number, level: string): string => {
   return colorOverride ?? getColorFromCSSVariable(index);
 };
 
+/**
+ * Resolves the chart color to use for a series. User-picked palette
+ * token wins; otherwise falls back to the existing index-based
+ * assignment with log-level override (`getColorProps`).
+ *
+ * Behavior is unchanged for series with no user-set color: callers can
+ * substitute `getColorProps(index, level)` with
+ * `resolveChartColor(undefined, index, level)` without any visible
+ * difference.
+ */
+export const resolveChartColor = (
+  token: ChartPaletteToken | undefined,
+  fallbackIndex: number,
+  level: string = '',
+): string => {
+  if (token) {
+    return getColorFromCSSToken(token);
+  }
+  return getColorProps(fallbackIndex, level);
+};
+
 export const truncateMiddle = (str: string, maxLen = 10) => {
   const coercedStr = `${str}`;
   if (coercedStr.length <= maxLen) {

From cccdcb0bb78fa87c9436c715b4a2b7794991aad9 Mon Sep 17 00:00:00 2001
From: Alex Fedotyev <alex.fedotyev@clickhouse.com>
Date: Tue, 12 May 2026 22:33:40 +0000
Subject: [PATCH 2/2] chore(app): drop dormant exports flagged by knip

resolveChartColor and ColorSwatchInputProps had no consumers on
this branch and tripped the knip CI check. Drop resolveChartColor
entirely (the next PR in the issue #1360 series adds it back
alongside its first consumer in ChartUtils.setLineColors), and
make ColorSwatchInputProps an internal type alias (consumers
infer the prop shape from typeof ColorSwatchInput).
---
 .../app/src/components/ColorSwatchInput.tsx   |  2 +-
 packages/app/src/utils.ts                     | 21 -------------------
 2 files changed, 1 insertion(+), 22 deletions(-)

diff --git a/packages/app/src/components/ColorSwatchInput.tsx b/packages/app/src/components/ColorSwatchInput.tsx
index d89960a26e..2ce27a9ecf 100644
--- a/packages/app/src/components/ColorSwatchInput.tsx
+++ b/packages/app/src/components/ColorSwatchInput.tsx
@@ -42,7 +42,7 @@ const TOKEN_LABELS: Record<ChartPaletteToken, string> = {
   'chart-error': 'Error',
 };
 
-export type ColorSwatchInputProps = {
+type ColorSwatchInputProps = {
   /** Currently selected palette token, if any. */
   value?: ChartPaletteToken;
   /** Called with the new token, or `undefined` when the user clears the picker. */
diff --git a/packages/app/src/utils.ts b/packages/app/src/utils.ts
index ad145ed413..8f90aec72c 100644
--- a/packages/app/src/utils.ts
+++ b/packages/app/src/utils.ts
@@ -716,27 +716,6 @@ export const getColorProps = (index: number, level: string): string => {
   return colorOverride ?? getColorFromCSSVariable(index);
 };
 
-/**
- * Resolves the chart color to use for a series. User-picked palette
- * token wins; otherwise falls back to the existing index-based
- * assignment with log-level override (`getColorProps`).
- *
- * Behavior is unchanged for series with no user-set color: callers can
- * substitute `getColorProps(index, level)` with
- * `resolveChartColor(undefined, index, level)` without any visible
- * difference.
- */
-export const resolveChartColor = (
-  token: ChartPaletteToken | undefined,
-  fallbackIndex: number,
-  level: string = '',
-): string => {
-  if (token) {
-    return getColorFromCSSToken(token);
-  }
-  return getColorProps(fallbackIndex, level);
-};
-
 export const truncateMiddle = (str: string, maxLen = 10) => {
   const coercedStr = `${str}`;
   if (coercedStr.length <= maxLen) {