# Agent instructions

Instructions for AI agents (and contributors) working in this repo. Currently
covers the `otel-ui` frontend design system, since that's the active area of
work; add sections here as other parts of the repo get their own conventions.

## otel-ui: design system

### The rule

**One theme, light and dark - that's it.** `otel-ui/src/index.css` defines a
single set of `--ds-*` tokens with a dark variant (default) and a light
variant (`:root[data-theme="light"]`). Never introduce a second palette, a
third theme variant, or a new token namespace alongside `ds-*`. If a screen
needs a color, it comes from this table or it doesn't exist yet - extend the
table, don't invent a one-off.

The theme toggle lives in `TopBar.tsx`, persists to `localStorage`
(`otel.ui.theme`), and is applied before first paint by an inline script in
`index.html` so there's no flash of the wrong theme.

The repo still has a second, older color system - the MD3-style
`--color-surface-container-*` / `--color-on-surface` / `--color-primary-container`
tokens, also in `index.css` - left over from before this redesign. That system
is **dead**, not a design choice: it exists only because not every screen has
been migrated yet (see the checklist below). Never add new usages of it. Once
the checklist is empty, delete that whole legacy `@theme` block plus the old
Geist/Inter/JetBrains/Material-Symbols font `<link>` entries in `index.html`,
so exactly one design system remains in the codebase.

### Token reference

Source of truth is `otel-ui/src/index.css` (`:root` and `:root[data-theme="light"]`).
Tailwind utilities are generated as `bg-ds-*`, `text-ds-*`, `border-ds-*`.

| Token | Dark | Light | Used for |
|---|---|---|---|
| `ds-bg` | `#0D1014` | `#F4F2ED` | page ground |
| `ds-chrome` | `#0B0E12` | `#FFFFFF` | icon rail, top bar |
| `ds-surface` | `#14181E` | `#FFFFFF` | cards, panels |
| `ds-surface-2` | `#191E26` | `#F7F5F0` | inputs, chips, selected row |
| `ds-fill` | `#1D232B` | `#EDEAE3` | hairlines inside cards, chart bands, bar tracks |
| `ds-line` | `#242B34` | `#E3E0D8` | card/control borders |
| `ds-line-strong` | `#2A313B` | `#D6D2C8` | chip borders, neutral badges |
| `ds-text` | `#E8ECF2` | `#161A1F` | primary text |
| `ds-text-2` | `#98A3B2` | `#4F5964` | secondary text |
| `ds-text-3` | `#8B96A6` | `#6B7480` | labels, metadata, muted text - this is the accessibility floor, don't go dimmer |
| `ds-critical` / `ds-critical-bg` | `#FF6F5E` / `#2B1512` | `#C4402C` / `#FBE9E5` | breached threshold, open errors |
| `ds-warn` / `ds-warn-bg` | `#F0B24A` / `#2A2011` | `#8A5D0E` / `#F9EFDA` | degraded but not (necessarily) user-visible |
| `ds-ok` | `#4FCF9A` | `#1F7A56` | healthy, resolved, recovered |
| `ds-accent` / `ds-accent-bg` | `#7B8CFF` / `#161B33` | `#3B4FC4` / `#E9ECFB` | the one interactive accent - primary buttons, selected segment, links, focus |
| `ds-on-accent` | `ds-chrome` value | `#FFFFFF` | text on top of `ds-accent` |

**Colour is a signal, not decoration.** Chrome, borders and type are neutral.
`ds-critical` / `ds-warn` / `ds-ok` only appear where a real measurement is
out of its expected band or a real state changed (open vs resolved). A
severity pill's color must correspond to an actual state, never picked for
visual variety. Don't tint cards, headers or buttons "for interest."

### Fonts

Three families (`otel-ui/index.html` loads them; `index.css` exposes them as
`--font-display` / `--font-ui` / `--font-data`, used via Tailwind's
`font-[family-name:var(--font-display)]` arbitrary syntax):

- **Bricolage Grotesque** (`--font-display`) - page/card headings, big metric numbers.
- **Instrument Sans** (`--font-ui`) - all other UI text and body copy. Also the
  new global default (`index.css`'s `@theme` overrides `--font-body`), so
  unmigrated screens already inherit this typeface even before their colors move.
- **IBM Plex Mono** (`--font-data`) - anything a person would copy or grep:
  ids, `key=value` attribute pairs, timestamps, durations, service names.

Never Inter, Roboto, Arial, or a new font stack.

### Layout shell (already built - reuse, don't rebuild)

- `otel-ui/src/components/layout/IconRail.tsx` - 72px fixed icon rail, global nav, one `aria-label` per icon.
- `otel-ui/src/components/layout/TopBar.tsx` - 58px fixed top bar: search, time range, theme toggle, auth.
- `otel-ui/src/components/FilterBar.tsx` - generic filter bar (optional scope segmented control, removable chips, dashed add-filter, an always-visible match readout, clear-all). Reuse this on every screen that lists things instead of building a bespoke filter row.
- `App.tsx` wires the shell globally and renders the single page-level `<main>`. Screens render inside it - see pitfall #2 below.

### Screen pattern

Established by `IssuesVisualizer.tsx` (the triage overview) and
`RumSessionsVisualizer.tsx` (real-user sessions) - follow this shape for the
remaining screens:

- `<FilterBar />` at the top of the screen's content.
- A main content column (`flex-1`) plus an optional fixed-width aside
  (~340-420px) for supporting stats/panels.
- Cards: `rounded-[14px] border border-ds-line bg-ds-surface`, **no shadows,
  no gradients** - depth comes from the border and ground color alone.
- No per-service rainbow badges. `getServicePalette` in `otel-utils.ts` (the
  gradient hash-to-color picker) is legacy: per the original design spec, a
  muted per-service palette is reserved for trace-waterfall span coloring
  only, never for general UI chrome like service badges. Use a neutral
  `border-ds-line-strong text-ds-text-2` badge instead.
- Real `<button>` / `<a href>` / `<input>` + `<label>` only. Never `onClick`
  on a `div` or `span[role=button]`. `aria-label` on every icon-only control;
  `aria-hidden="true"` on decorative SVG icons (use `lucide-react`, not the
  Material Symbols icon font - see pitfall below).

### Pitfalls hit migrating Issues and RUM sessions - avoid repeating these

1. **No nested `<button>` elements.** Browsers implicitly close the outer
   `<button>` the moment they hit an inner one, which silently breaks click
   handling on whatever's after it in the DOM (this shipped once, undetected
   until manual testing). If a row/card needs both "click to expand" and
   inner action buttons, make the expandable area its own `<button>` and put
   the action buttons as **siblings**, not children.
2. **No nested `<main>` landmarks.** `App.tsx` already renders one `<main>`;
   a screen component must not render its own - use a `<div>`.
3. **`whitespace-nowrap` + `shrink-0` on fixed-height pills/badges.** Without
   them, a longer label silently wraps onto two lines and blows out the
   pill's height inside its flex row - easy to miss until you test with real
   (longer) data or a narrower viewport.
4. **Never fabricate data.** Before adding a metric, column, or button, check
   whether the field actually exists in the real data model - the backend API
   response, or for RUM specifically, what `static/otel-rum.js` actually
   sends (see the header comment in `otel-ui/src/lib/rum-utils.ts` for a
   worked example of what's real vs. invented). If a design reference shows
   something with no backing data - the RUM mockup invented rage clicks, geo
   location, a "frustration score", and session replay, none of which this
   pipeline captures - drop it or replace it with the closest real,
   honestly-labeled equivalent. Never wire up a control that looks
   functional but isn't backed by anything.
5. **Screenshots of a hidden Browser preview pane are unreliable** for
   `position: fixed` elements (stale compositor frame, even after a full
   reload). If a screenshot shows something that contradicts
   `getComputedStyle`, trust the computed style, front the tab, and re-check
   before concluding there's a real bug.

## Migration checklist

Converted to `ds-*` already: `App.tsx` (shell), `IconRail.tsx`, `TopBar.tsx`,
`FilterBar.tsx`, `IssuesVisualizer.tsx` (Issues / triage overview, tab0),
`RumSessionsVisualizer.tsx` (RUM sessions, tab7).

Everything below still renders with the legacy MD3 dark-only palette
(`text-on-surface`, `bg-surface-container-*`, `bg-primary-container`,
gradient badges, the Material Symbols icon font) and needs the same
treatment. Sizes are current line counts, biggest first:

| File | Lines | Tab / role | Notes |
|---|---|---|---|
| `TraceVisualization.tsx` | 1866 | Traces & Spans (tab1) | Waterfall + span detail; closest existing screen to the design spec's `trace-waterfall.html` reference |
| `MetricsVisualizer.tsx` | 1107 | Metrics & APM (tab2) | Imports `GaugeMeter.tsx` |
| `StructuredLogTerminal.tsx` | 582 | Live Log Stream (tab3) | Uses Material Symbols icons |
| `Tabs.tsx` (shell) | 513 | horizontal tab strip rendered above every screen | Gradient active-tab underline, slate colors; decide whether this strip is still needed now that `IconRail` is the primary nav, or whether it should just lose the gradient/slate styling |
| `SearchAndWatcher.tsx` | 504 | Archive & Trap (tab6) | |
| `ServiceGraph.tsx` | 495 | used by `TraceVisualization.tsx` | migrate alongside its caller |
| `WaveformHistogram.tsx` | 385 | shown above every non-Issues/RUM tab's content | Uses Material Symbols icons; see the shared-chrome note below |
| `GaugeMeter.tsx` | 372 | used by `MetricsVisualizer.tsx` | migrate alongside its caller |
| `TrendsVisualizer.tsx` | 323 | Historical Trends (tab5, only when ClickHouse stats are configured) | |
| `CommandAndQueryBar.tsx` | 251 | shown above every non-Issues/RUM tab's content | see the shared-chrome note below |
| `TelemetryFilters.tsx` | 124 | conditionally shown above `Tabs.tsx` content | service multiselect + attribute exclusions; candidate to rebuild on top of `FilterBar.tsx` instead of restyling in place |
| `SetupPanel.tsx` | 112 | Setup & Agent API (tab4) | |
| `PatternsVisualizer.tsx` | 76 | Similarity Patterns (tab8) | |
| `ViewErrorBoundary.tsx` | 62 | error fallback UI, wraps every tab's content | small, easy pass |
| `RolloutsVisualizer.tsx` | 48 | Cluster Rollouts (tab9) | |
| `AuthCallbackView` (inside `App.tsx`) | ~40 | OIDC callback screen | still 100% old tokens even though the rest of `App.tsx` is migrated |

**Shared chrome note:** `CommandAndQueryBar.tsx` (anomaly banner, filter
status strip, NDJSON export) and `WaveformHistogram.tsx` (volume/error
waveform with click-to-focus) are currently skipped entirely on the Issues
tab (`isTriageOverview` branch in `App.tsx`) because their old styling would
clash with the new `FilterBar`. When migrating the remaining tabs, decide
per screen whether that real functionality gets folded into the screen's own
`FilterBar`/content area (as happened for Issues and RUM sessions), or stays
as shared chrome above the remaining tabs, restyled to `ds-*` tokens.

### Finding old-pattern usages

```sh
grep -rlE "surface-container|text-on-surface|primary-container|bg-error-container|material-symbols-outlined" otel-ui/src
grep -rlE "from-[a-z]+-[0-9]+ via-[a-z]+-[0-9]+|getServicePalette" otel-ui/src
```

A file with zero hits and zero `ds-*` usage either has no meaningful styling
of its own (a pure hook/context) or hasn't been looked at yet - check the
checklist above.