product-design

name	product-design
description	chmonitor's product design system + UX conventions, so every new feature looks and behaves consistent with the rest of the dashboard. Use BEFORE building or reviewing any UI: new pages, charts, cards, dialogs, empty/error/loading states, badges, onboarding, settings. Covers design tokens (OKLCH theme, dark mode, radius, chart colors), shadcn/ui rules, the ChartCard/ChartContainer pattern, data-table system, EmptyState variants, graceful error handling, ?host routing + hooks-at-deepest-consumer, file/route organization, and brand. Triggers: "new page", "add a chart", "build UI", "design", "component", "empty state", "loading", "consistent", "follow-up feature", "match the design", "what's new", "changelog", "dialog scroll", "settings gear", "schema compare", "settings diff", "add host", "pick a query", "query picker", "select labels", "ON CLUSTER", "advisor DDL", "advisor schema", "schema advisor", "command palette", "cmd k", "search dialog", "ttl partitions", "header title", "768", "truncate Overview", "essential sidebar", "more pages", "keep in sidebar", "hover add", "group heading", "customize dialog".
metadata	{"tags":"design-system, ui, ux, tailwind, shadcn, charts, tokens, conventions, brand"}

chmonitor product design system

The rulebook for keeping new features visually + behaviourally consistent. When in doubt, COPY the closest existing component rather than inventing. Full token values and file paths: docs/knowledge/product-design.md.

Non-negotiables

1. Never edit src/components/ui/* (shadcn primitives). Customise via the className prop at the call site, or a wrapper in src/components/ — never in ui/. Always merge classes with cn() (src/lib/utils.ts), never template-literal concatenation.
2. Tailwind v4, CSS-first. Tokens live in src/styles.css @theme blocks — there is no tailwind.config.ts. Use semantic tokens (bg-card, text-muted-foreground, border-border), not raw colors. Theme is OKLCH.
3. Dark mode is class-based (next-themes, .dark). Every surface must read correctly in both themes — only use semantic tokens, which flip automatically. Don't hardcode bg-white / text-black.
4. Hooks at the deepest consumer. A component that needs data calls useHostId() / useChartData() itself — do NOT prop-drill hostId.
5. ?host=N routing, never dynamic /N/... segments. Preserve other search params with buildUrl(pathname, { host }, searchParams).
6. No "AI slop" decoration — one clear signal per state, not several redundant ones. No full-saturation accent bars/rails stacked on an already-colored border; no gradient blobs/glow orbs behind icons. See "Anti-patterns" in docs/knowledge/product-design.md.

Tokens (semantic — use these names, not hex/oklch literals)

background foreground card card-foreground popover muted muted-foreground primary secondary accent destructive border input ring. Charts: --chart-1..13 for series, plus named accents --chart-red (error series), --chart-blue (info), --chart-green (success), --chart-yellow (warning) — only pass tokens that exist in styles.css to a chart's colors prop; an undefined var() renders the series black. Radius: rounded-md (9px) default, rounded-lg (10px), rounded-xl (14px) for cards. Brand accents: orange (metrics) + emerald (health/live) — see components/icons/chmonitor-logo.tsx.

Canonical idioms (match these class strings)

• Card surface: rounded-xl border bg-card shadow-sm (premium variant adds bg-gradient-to-b from-card/80 to-card/40 dark:from-card/60 dark:to-card/30 backdrop-blur-xl). See components/charts/chart-card-styles.ts.
• Icons: lucide-react, size-4 standard / size-3.5 compact / strokeWidth={1.5}.
• Dense text: text-[13px] controls, text-sm body, text-xs text-muted-foreground meta, text-xl font-semibold tracking-tight page/hero titles.
• Spacing: gap-1.5 compact, gap-2 standard, gap-4 generous; card content p-4 pt-0.
• Pill/secondary button link: inline-flex h-8 items-center gap-1.5 rounded-md border border-border px-3 text-[13px] font-medium hover:bg-muted.
• Clickable card → detail dialog: whole card is the target (role="button" + tabIndex={0} + onKeyDown={activateOnEnterOrSpace(open)}, never a nested <button>); inner links e.stopPropagation() (not preventDefault) so they still navigate. Drive drill-down from a per-item field, rendered via ResultTable. See components/health/{health-card-shell,health-detail-rows}.tsx.
• One severity signal per card: severity reads from a single tinted icon — never icon tile + colored border + severity pill + header count badge on the same finding. components/insights/severity-meta.ts is the source of truth (label / icon / iconColor / neutral badge); card surface, border and count badges stay neutral. Body line-clamp-2 + title tooltip; the breakdown goes in a detail dialog.
• A dialog opened from a popover lives OUTSIDE the popover subtree. Rendered inside PopoverContent, closing the popover unmounts the dialog and nothing appears. Keep the selected item + dialog in the parent, as a sibling of <Popover> — see components/insights/insights-popover.tsx.
• Dialog with sticky header/footer: is with (or a stable ). Header and footer are . The body is — that element is the scroll container. Do not use with for this: its viewport is and does not constrain unless the root has an explicit height, so notes paint under the footer and EmptyState can vanish inside a blank scrollbar box. Reset 's default to when the dialog is . Same list-scroll pattern without a footer: . See . For What's new, also set on the title () and reset the body on open — default focus would otherwise land on the first markdown link deep in an older note and the list to the middle. Screenshot thumbs () open a full-size overlay in the same dialog; Escape closes the overlay before the dialog. Do not add on — / drops the primitive's , so no longer centers in the viewport. already contains an inner overlay.

Illustrations (bespoke, brand-warm SVGs)

Prefer inline React SVG illustration components in components/illustrations/ over a lone lucide glyph for high-impact "moments" and for differentiating states. Rules:

• Token-driven only — colours come from currentColor (set by a caller text-* class), the OKLCH chart palette via Tailwind utilities (fill-chart-1, text-chart-red, …), and brand fill-orange-500 / fill-emerald-500. NEVER a raw hex/oklch or hsl(var(--…)) literal (that breaks on the OKLCH tokens — see docs/knowledge/cluster-topology.md).
• Motion-safe only — gate any animation on motion-safe: (e.g. motion-safe:animate-flow-stream, motion-safe:animate-pulse), never SMIL; add motion-reduce:animate-none on pulses.
• Theme-aware for free because everything is currentColor + semantic tokens; verify in both light and dark.
• Structural template: FlowConnector in components/connections/connection-help-panel.tsx.

Current components: WelcomeIllustration (first-run welcome hero), AgentGreetingIllustration (agent greeting hero), EmptyStateIllustration (one bespoke ~40×40 mini per EmptyStateVariant — wired into EmptyState, so ChartError gets a cause-appropriate illustration automatically via toEmptyStateVariant), BrokenWireIllustration (connection-error panel: a browser→chmonitor→source flow with the failed hop severed). Static art for the marketing/docs sites (which can't import React components) goes in repo-root assets/illustrations/ (synced like screenshots//backgrounds/).

Charts — always wrap state, never hand-roll it

Use ChartContainer (renders skeleton / ChartError / empty) + ChartCard (title, SQL, metadata, stale indicator, retry). Fetch with useChartData({ chartName, hostId, interval }). Header icon order: [StaleIndicator] [DateRange] [LogScaleToggle] [CardToolbar]. Copy an existing chart in components/charts/ as the template — don't reinvent the wiring.

Loading / empty / error

• Loading: a Skeleton that matches the final layout (components/skeletons/) to avoid layout shift; gate with Suspense where used.
• Empty: EmptyState (components/ui/empty-state.tsx) with the right variant (no-data | no-results | error | table-missing | timeout | filtered-empty | offline | loading), icon, title, description, optional action/onRefresh. Table query failures use the full (non-compact) EmptyState so timeout / missing-column copy is visible — never hourglass + Retry with no description.
• Interactive tool pages (Explain, Advisor): before the first run, a dashed-border EmptyState variant="no-data" ("Nothing to analyze/explain yet"). User-input issues — table-less SQL like SELECT 1, missing query_id — use the same EmptyState with next steps, never ErrorAlert titled "Analysis failed". ErrorAlert is for host/schema/fetch failures. Picking a query from the picker auto-runs, same as /explain. Advisor (/advisor) defaults to Schema & Settings (Query Advisor is the second tab; ?query= / ?queryId= still open it). The schema surface reuses Explorer DatabaseTree in a left sidebar (search + icon-only All / Needs attention / Hide suggested, group, sort — same catalog chrome as Schema Compare). Care tables get a single amber chart-yellow dot, not a second border or pill. Selecting a table shows findings + copyable recommend-only DDL (TuningFindingsPanel / RecommendDdlBlocks) and MV relations; never an Apply/Run control. When nothing needs fixing, a healthy empty state includes tips for creating new tables.
• Recommend-only DDL pairs: when cluster topology is known (Distributed engine or cluster metadata), Advisor findings and schema-diff plan items show the local table name plus a copyable ON CLUSTER variant of the same statement via RecommendDdlBlocks (components/ddl/recommend-ddl-blocks.tsx). Single-node / no topology stays a single statement. Never a Run/apply button — lib/ddl/on-cluster.ts is a pure transform.

Data tables

Use the components/data-table/ system (resizing, wrap toggle, sorting via sorting-fns.ts, pagination, faceted filters, row actions, SQL display). Synthetic column ids __expand, select, action are non-data — skip them in filter/search/sort/card wiring.

Favorites in the sidebar can be drag-reordered; order is the localStorage pin list (chm-pinned-favorites). Leaf sidebar rows also reveal Hide (EyeOff) beside the pin; that writes hiddenMenuHrefs and toasts Undo + Open Navigation (Settings → Workspace → Navigation). Hover + lists hidden siblings in that group (showMenuHref on click). Group headings show a hover + / Customize control that opens a per-category dialog (group-customize-dialog.tsx) listing every catalog child of that group: visible rows have Remove (hideMenuHref), hidden rows are muted with Add (showMenuHref). Toggle updates the rail immediately; Open is an explicit arrow. Footer Done, optional All pages… into Settings → Navigation (not the default path). Overview (no children) has no heading dialog. Footer About is never hideable. More is a flyout of hidden pages (not Settings). Essential is grouped (not flattened): Overview; AI Agent → Chat; Insights → Insights; Health → Health; Queries → Running + History; Tables → Overview + Explorer; Tools → SQL. Do not flatten those groups to Chat / SQL leaves.

User appearance settings

Entry: sidebar footer chrome beside Sign In / the avatar — [what's new] [gear] [Sign In / avatar] with flex items-center gap-1.5. What's new is WhatsNewButton (components/whats-new/, lucide Newspaper, aria-label="What's new", data-testid="whats-new-button", 44px mobile hit min-h-11 min-w-11 lg:min-h-8). A primary dot badge appears when APP_VERSION is newer than persisted lastSeenChangelogVersion (on UserSettings). The dialog (WhatsNewDialog, sibling of the menu via WhatsNewProvider in dashboard-shell.tsx) lists vX.Y.Z GitHub Releases newest first; auto-opens once per upgrade (sessionStorage), never on every navigation. Header and footer stay put; only the notes body (min-h-0 flex-1 overflow-y-auto) scrolls — see the sticky header/footer dialog idiom above. Manual open always works. Extra entry points: WhatsNewMenuItem next to About in the user dropdown, and a What's new action on /about. Do not add a Settings tab for changelog — Settings stays browser-local prefs. GET /api/v1/releases loads notes server-side (no browser GitHub calls). Copy comes from docs/whats-new/vX.Y.Z.md when present (same files as landing /changelog); otherwise the GitHub body is stripped to Features. Airgap fallback is the committed airgap-snapshot.json (friendly notes overlaid on latest v* Features), never a runtime fetch of CHANGELOG.md. Use NavSettingsButton / NavUserFooterRow (components/nav-user/nav-settings-button.tsx): lucide Settings, size-4, strokeWidth={1.5}, aria-label="Open settings", data-testid="nav-settings-button", tooltip "Settings". Hide when canUseSettings is false. Gear must work signed-out (these are local settings). Keep the dialog a sibling of the menu (not inside DropdownMenu / SignInButton). ⌘, still opens it (useSettingsShortcut). Do not invent a second settings store — always + .

The Settings dialog (components/settings/settings-form.tsx) exposes units (byteUnit, numberFormat), chart palette (chartPalette), table density (tableDensity), default time range, and workspace preset (workspacePreset, hiddenMenuHrefs) on UserSettings. Header is Settings icon + title + one-line "Local to this browser"; surface is rounded-xl border bg-card p-0 with a stable height (h-[min(42rem,90vh)], sm:max-w-4xl) and select-text so labels copy. Left rail is a flat column (no boxed tab well): section labels + icon rows, selected = muted pill, border-r divider. Below sm the rail stacks above the pane so Navigation fits 375. Content pane shows the active tab title. Theme (Light / Dark / System) is a settings row (label left, three window thumbnails right) on Appearance only. Navigation leads with a SegmentedControl workspace preset (Full / DBA / Engineer / SRE / Custom) plus an in-page sidebar-like menu tree (same groups, icons, nested children as nav-main). Groups default collapsed; picking a role remounts them closed. Parent rows are chevron-only. Nested children use SidebarMenuSubButton (text-left, same as the parent button) so a <button> row is not UA-centered; Hide stays shrink-0 on the right. Click a leaf to hide or show it — hidden rows stay visible but muted, like Dim unavailable pages. Expand/collapse does not write settings. Hide of an already-hidden-by- preset leaf stays on the role; Custom only when the hide list leaves hideListForPreset. Search filters the tree. When the preset is not Full, a Show all control applies Full. The sidebar More row is a searchable flyout of hidden leaves (click navigates; Customize… opens this pane). Group headings are the default customize surface (one group at a time — never a 40-checkbox wall of the whole catalog). Then the Dim / Hide unavailable-page demos. Hidden pages stay routable. Sidebar visibility is the hide list (getVisibleMenuItems + Alerts). ⌘K uses usePaletteMenuItems / getAllowedMenuItems so hidden pages stay indexed with a Hidden hint and do not auto-unhide. Landing on a hidden page shows Keep in sidebar. Settings > Navigation tree match the active host engine (useActiveHostEngine — default source engine, Postgres pages when is active). Timezone uses (search + browser zone on top). Palette is a card picker with mini bars, not a segmented control. Unit options show a sample value ( / ). Integrations: MCP live; Slack/Telegram/PagerDuty/Email/Discord shown disabled. First-run workspace is Custom + the Essential hide list (: grouped Overview; AI Agent → Chat; Insights → Insights; Health → Health; Queries → Running + History; Tables → Overview + Explorer; Tools → SQL). Full still restores every page. Other DEFAULTs reproduce the prior look (, …). Applied by (): units → module snapshot in ; palette/density → / on . For 2–3 choices use ; 4+ options wrap so the Navigation presets fit a 375 Settings pane. Show all is a full-width control under the hide-count line. Full detail: .

Adding a page

1. src/routes/(dashboard)/my-page.tsx ('use client', uses useHostId()).
2. Add a QueryConfig in src/lib/query-config/ if it needs data.
3. Register in src/menu/ (with feature gate / tableCheck if optional). Add the tab title in lib/page-title.ts (ROUTE_TITLE_MAP) when it differs from title-casing the last URL segment — ⌘K searches that <title> as well as the sidebar label. Interactive utilities (SQL, explorer, explain, compare, builder, advisor) go in menu/tools.ts. Data Explorer (/explorer) is also listed under Tables. TTL & Partitions (/ttl-partition-health) is a system-table inventory — it lives under Tables, not Tools or System. The listing includes a stacked in-range vs past-TTL bar (part max_date vs the parsed TTL interval). The same recommend-only rules also power the TTL & Partition Health card on /health (flagged-table count + detail dialog). Do not invent a third TTL surface; never ALTER TTL or DROP PARTITION from these pages. Other system-table views stay in their domain file. Tools is the last Main group, composed after Logs and before the About footer in menu/index.ts — do not put it after Overview / before AI Agent. The Tools parent must not set permission; copy the child's existing feature onto the leaf. Leave engines absent so Postgres hosts hide the whole Tools group — do not add engines: ['postgres']. DBA / Engineer / SRE presets include Tools. Webhook ingest (Inbound Events) lives under Health after Alert Settings — not as a top-level Others item; leave engines absent so Postgres hosts inherit Health (default source-engine family). Day-to-day pages belong in DEFAULT_VISIBLE_MENU_HREFS (lib/menu/slim-default.ts); omit specialist pages so the first-run sidebar stays Essential plus Insights, Explorer, and Query History (grouped: Overview; AI Agent → Chat; Insights → Insights; Health → Health; Queries → Running + History; Tables → Overview + Explorer; Tools → SQL) — they remain restorable from the group heading dialog, hover +, More, in-page More / Customize, or Settings → Navigation. Do not add Merges / Metrics / Clusters / Explain / Advisor, or Keeper / PeerDB / Security / Logs / System / Operations, to the keep list.
4. Compose ChartContainer + ChartCard; reuse skeletons + empty/error states.

File & naming conventions

kebab-case files; PascalCase components; use* camelCase hooks; props as interface XProps colocated; client components declare 'use client', server components don't; shared types in src/types/ or src/lib/api/types.ts. Details in docs/knowledge/conventions.md.

Keep this skill current

This skill is the source of truth for design consistency. When you introduce or change a durable UI pattern (a new token, a reusable component, an empty/error/onboarding convention), UPDATE this file + docs/knowledge/ product-design.md in the SAME change. See the "Auto-improve project skills" note in the root CLAUDE.md.