# SQL Catalog UI Semantic Visual System

## 1. Purpose

This document is the visual-system delta for the SQL Catalog MVP. It overrides older references to
large summary cards, a full-width metric strip, and a sidebar-first default layout.

The product is an operational workbench. Visual emphasis must follow task urgency and workflow
meaning, not component availability.

## 2. Theme And Surfaces

- Dark is the default and primary review mode. Light remains available as a user preference.
- Page, card, popover, table, and input surfaces use neutral near-black or gray values.
- The background may use the restrained violet, amber, rose, indigo, and cyan diffusion already used
  by Slow Log Explorer. These colors remain atmospheric and must not reduce table contrast.
- Borders establish grouping. Cards are used only for bounded tools or repeated items, not to make
  every page section float.

## 3. Semantic Color Roles

### 3.1 Interaction

Violet is reserved for interaction state:

- active navigation;
- focus rings and selected controls;
- navigation drag targets;
- the dirty `Apply Filters` action.

Violet must not represent severity, health, success, or workflow state.

### 3.2 Severity

| Severity | Color role | Meaning |
| --- | --- | --- |
| Critical | Red | Immediate or highest-risk SQL issue |
| High | Yellow | Serious issue that is distinct from Critical |
| Medium | Lake blue | Material issue worth tracking |
| Low | Neutral gray | Lower-risk issue |
| Info | Neutral gray | Informational signal |

Severity is normally rendered as colored text. It is never inferred from color alone because the
severity label remains visible.

### 3.3 Workflow State

| State role | Color | Examples |
| --- | --- | --- |
| Pending | Neutral gray | waiting triage, assessment, pending, new |
| Processing | Yellow | active, reviewing, planning, alignment, execution, in treatment |
| Observing | Lake blue | watching, observation |
| Abnormal | Red | reappeared, regressed, failed, blocked |
| Terminal positive | Green | fixed, improved, completed |
| Terminal neutral | Muted green | reviewed, unchanged, no action needed, not optimizable, accepted risk, cancelled, superseded, archived |

Workflow colors describe current meaning, not entity type. A zero-valued risk counter uses neutral
text instead of retaining its warning or danger color. Pending work must not use yellow: yellow is
reserved for work that is actively being processed. Multiple terminal meanings may use different
green chroma or lightness, but they remain visibly part of the same terminal family.

### 3.4 Analytical And Chart Color

- All analytical charts use the shared ECharts runtime. Every chart has an explicit container height,
  internal plot padding, theme-token colors, pointer-following Tooltips, and `ResizeObserver`-driven
  resizing when its panel or application layout changes.
- Chart series have dedicated tokens and do not borrow workflow-state colors.
- A stacked chart uses mutually exclusive parts. The Finding trend therefore renders `Critical` and
  `Non-critical`; it must not stack `Critical` over an `All Findings` series that already contains it.
- Critical remains red in a severity breakdown. A current-period Critical count in a comparison
  table is ordinary numeric data and remains neutral.
- Improvement deltas use a restrained green and regressions use red. This delta meaning is separate
  from terminal workflow status.
- Chart grid lines use a lower-contrast, dashed analytical-grid token. They must not look like the
  solid separators that divide panels and table rows.

## 4. Emphasis Rules

- Routine severity and workflow values use `SeverityText` and `StatusText`.
- Filled or bordered badges are not used in normal tables, metadata bars, lists, or timelines.
- A filled badge is reserved for a rare callout that must interrupt scanning, such as an unhandled
  blocking condition. It is not the default representation for an enum.
- Destructive red is reserved for dangerous actions and danger states. Success green is reserved for
  completed positive outcomes. Neither color is decorative.
- Muted text is used for labels and secondary metadata, not for primary SQL identity or commands.

### 4.1 Action Control Geometry

- Every button variant reserves the same one-pixel border footprint inside the declared control
  height. A 28-pixel primary and a 28-pixel secondary button therefore share the same outer geometry.
- A text-labeled secondary button uses a restrained neutral fill and a visible neutral border in its
  resting state. It must not rely on a nearly invisible outline next to a high-contrast filled action.
- Primary fill remains visually dominant, but the border is part of its own 28-pixel box rather than
  increasing its rendered size. One primary action per command group is the normal maximum.
- Transparent ghost treatment is reserved for familiar icon utilities and low-emphasis commands, not
  for a text-labeled peer beside a primary action.
- Focus rings sit outside the border footprint and do not change layout dimensions.

This follows the hierarchy in [GitHub Primer button guidance](https://primer.style/product/components/button/):
primary is sparse, default/secondary is the normal paired action, and transparent treatment is
reserved for subtle or compound controls.

## 5. Information Density

- A small set of counters must not receive a dedicated full-width row or a grid of summary cards.
- Workbench counters share the page-title action line.
- List counters share the existing filter action line and use only their natural width.
- Related values are separated by a thin divider and remain readable as one compact group.
- Detail metadata uses a wrapping one- or two-row metadata bar.
- Table rows target approximately 40 pixels. Digest and SQL columns receive useful width and own
  horizontal scrolling rather than forcing page-level overflow.
- A wide table exposes synchronized horizontal scroll controls above and below the table. The table
  body itself does not add a third visible horizontal scrollbar.
- Pagination follows the table and includes the visible row range, total count, page position,
  previous/next navigation, and a compact rows-per-page control where the API supports it.
- List pages retain bottom breathing room after the final panel; the table or paginator must never
  touch the viewport edge.

Larger summary areas are justified only when they add analytical structure such as a trend,
distribution, comparison, or drilldown. Raw counts alone do not qualify.

## 6. Filter Interaction

The list-page filter model follows Slow Log Explorer:

1. Pinned filters and active optional filters appear as compact segmented chips.
2. Changes update draft state and do not issue a request immediately.
3. A dirty draft changes `Reload` to the violet `Apply Filters` action.
4. `Reset` restores the currently applied state; it does not silently clear applied URL filters.
5. `Add Filter` shows all optional filters, indicates active items with a check, and can add or remove
   several filters without closing the picker.
6. Applying filters updates URL search parameters and resets pagination.

Time-based Finding queries use the Slow Log Explorer time-range control instead of a basic preset
select. It provides Relative, Natural, and Custom modes, displays the browser's local time zone, and
writes paired `from` and `to` ISO timestamps when the global filter draft is applied. The Findings
page applies that range to `created_at`; source observation and receipt timestamps remain optional
diagnostic fields rather than user-selectable Feed time bases. Custom and relative ranges are limited
to 30 days in this MVP.

The time-range popover uses neutral surface contrast for active tabs, calendar selection, range
endpoints, hover, and focus. It does not reuse the application's violet action highlight; violet
remains reserved for the global dirty `Apply Filters` action outside the picker.

Select controls use the shared Radix implementation from the Slow Log Explorer stack. Trigger text
and the chevron have an explicit gap and at least 12 pixels of right-side padding. Every trigger has
an accessible name and full keyboard behavior.

## 7. Accessibility And Validation

- Color always accompanies visible text.
- Focus rings use the interaction color and remain visible in Dark mode.
- Controls expose accessible names, not only adjacent visual labels.
- Motion respects `prefers-reduced-motion`.
- At 1280 and 1440 pixel desktop widths, pages must have no page-level horizontal overflow.
- Select menus, filter pickers, table scroll containers, and detail SQL containers are included in
  visual review, not only their closed states.