Skip to content

dns-control UI rev

See proposal.md, Why. The web app under apps/dns-control/web is a plain Vite and Svelte 5 project, not SvelteKit. It runs shadcn-svelte 1.5 on the vega preset with bits-ui 2 and Tailwind 4, with 20 registry components installed and every custom component a composition of them. Vite writes the bundle to web/dist, and the Go binary embeds that directory and serves it from its catch-all route, so every asset must come from the app’s own origin. The theme lives in web/src/app.css. Color mode follows the OS through prefers-color-scheme and the dark: variant maps to the same media query. The route is the hash and holds every filter value, so Back, Forward and a copied URL restore a view. Filtering, sorting and paging run on the server.

The Phase 2 and Phase 4 UI design contracts under .planning/ wrote the current screens. Three of their rules stay in force and shape this design: every badge carries text and color never carries meaning alone, every fact is visible text and no fact lives behind a hover alone, and an action result lands in the audit panel and not in a toast. One of their premises is gone: they rejected a sidebar because three destinations fit in one row of ghost buttons, and the app now has four with a fifth coming.

The search handler in internal/httpapi/search.go matches the name pattern with Go path.Match and rejects a malformed pattern before it reads the index. Its comment names the reason: no backtracking blowup. The lineage index holds every name in lowercase with its trailing dot.

Goals:

  • Every visual change comes from a registry component or a theme token. One custom control, the pattern input, is the only exception, and the design names why.
  • The three rules above survive. Tone is additive to text. The differ preview sits on a link. The audit panel stays.
  • Every existing unit test keeps its selectors. The data-testid attributes of today are the contract that the tests hold, and the rev moves markup around them.
  • The phone layout is a first-class target at 390px, with no horizontal scroll of the page.

Non-Goals:

  • No change to the data flow of a screen, to the polling rules, to the action dialogs or to the audit panel.
  • No chart. The API returns one value per reading and ClickStack holds the series.
  • No command palette. A jump-to-name palette is a feature and not part of a rev.
  • No theme toggle. Color mode follows the OS as today.
  • No match highlighting in the result rows. The design names it as a later option.

D1. The shell is the registry sidebar block

Section titled “D1. The shell is the registry sidebar block”

The shadcn-svelte sidebar ships with its provider, its trigger, a collapse to icons and a Sheet under the mobile breakpoint, all driven by one IsMobile hook that reads a media query. The app adds sidebar and sheet through the CLI and replaces TopBar.svelte with a Shell.svelte that renders Sidebar.Provider, Sidebar.Root, the five items and the identity block. The block does not need SvelteKit. Its items are anchors to the hash routes, so the router does not change.

Alternative: keep the top bar and move the overflow into a Sheet under 640px. One more destination fits that way and the one after that does not. Rejected because the growth is already planned.

D2. Two tone tokens, three writer hue tokens, one badge variant family

Section titled “D2. Two tone tokens, three writer hue tokens, one badge variant family”

app.css gains --ok and --warn beside --destructive, with light and dark values, and three hue-only tokens --writer-dns-control, --writer-external-dns and --writer-kea-d2 with a fourth unassigned --writer-reserve. Four shared numbers set the lightness and chroma of every writer badge in each theme. badge.svelte gains three variants in its tailwind-variants table: ok and warn follow the shape of destructive, a ten to fourteen percent tint with the tone as text, and writer reads its hue from a CSS variable --w-h and builds its two colors with oklch(). copy.ts gains a map from writer id to hue token, and StateBadge and NodeBadge gain a tone map from state and finding to variant.

The default hue of the writer variant lives in the var(--w-h, 0) read site and never in a declaration. A default set on the variant’s own class outranks a per-writer class and every writer renders at hue zero. The mock hit this exact trap.

Alternative: five fixed writer colors as five variants. Rejected because adding a writer would mean a new variant and a new pair of colors, where a hue token is one line and the weight stays equal by construction.

The badge base class gains uppercase tracking-wide text-[11px]. The DOM text stays in sentence case, so copy and a screen reader read words. DNS names, zone values, marks and record content never render inside a badge. The RR type badge on the phone card is the one exception where the text is already uppercase by convention.

D4. Names in lists strip the zone on the client

Section titled “D4. Names in lists strip the zone on the client”

Every list row carries zone beside name, so the client strips the zone as a suffix with one helper relativeName(name, zone) in format.ts. The helper returns @ when the two are equal. The helper never guesses: a name that does not end with its zone renders in full. The link target and the title attribute keep the full name. The helper runs on Search, Changes, the Health differ table and Leftover marks, and not on Name detail or Query log.

D5. Health leads with tiles and groups readings under tabs

Section titled “D5. Health leads with tiles and groups readings under tabs”

Four Card tiles open the screen. Each tile’s tone is the worst tone of the facts it sums up, computed in one tileTone() function per tile from the same HealthResponse the cards read. NodeCard keeps its readings and groups them under Tabs with Worker open by default. The card header gains a health badge from one nodeTone(node) rule: ok when the worker answers, Blocky runs and both checks pass; warn when the node is drained or a check has no reading; destructive when a check fails or the worker does not answer. Below 640px NodeCard renders as a Collapsible whose trigger holds the name, the keepalived state and the health badge, and whose content holds the Worker readings and the actions.

The data-testid="node-card" and data-node attributes stay on the card root in both forms, so the Health tests keep their selectors. The readings keep their dt and dd pairs inside the tab panels, so the readings() helper of the tests keeps working once it reads the open panel.

D6. Search filters move into the headers, the name input stays above

Section titled “D6. Search filters move into the headers, the name input stays above”

Each of the four filter headers renders a DropdownMenu with a RadioGroup of the values the last response offered, plus a Clear item when a value is set. Choosing an item calls the same go() function the form submit calls today, so the hash drives the request and nothing else changes in the data flow. A set filter fills the header icon in the accent and renders a chip above the table whose close button clears that one filter. The empty state moves inside the table body as one row that spans every column. Below 768px the four filters render as NativeSelect controls inside a Sheet behind a Filters button.

The name pattern stays as the one input above the table with its Search button. A wildcard search is the primary action, and a header-sized input would hide it. Sean can overrule this.

D7. The pattern input is the one custom control

Section titled “D7. The pattern input is the one custom control”

PatternInput.svelte wraps InputGroup. Its trailing addon holds a ToggleGroup of glob and regex. Behind the <input> sits a highlight layer, a div with aria-hidden that renders the same text as spans: operators in the accent, escapes in the muted token, literals in the foreground. The input’s text is transparent and its caret-color is the foreground. Both use font-mono at the same size and padding, so every character lines up, and the layer copies the input’s scrollLeft on each input and scroll event. A tokenizer in pattern.ts returns the spans for each mode and has its own unit test.

In glob mode the submit path appends . to a pattern that ends with neither . nor *. In regex mode the component compiles the pattern with new RegExp on each change and sets aria-invalid with the help line “Pattern does not compile” when that throws. The browser engine is not Go RE2, so the server stays the authority.

No registry component colors part of an input’s value, which is why this one control is custom.

Alternative: a contenteditable element. Rejected because it loses the native form behaviour of an input, from autofill to the mobile keyboard.

Query in search.go gains a Mode field with the values glob and regex, read from the mode query parameter and defaulting to glob. In regex mode checkPattern compiles (?i) plus the pattern with regexp.Compile and answers the existing invalid_filter for name when that fails. The match in FilterAll becomes re.MatchString(it.Name). An unknown mode answers invalid_filter for mode. The compiled regex is built once per request and reused across every row. SearchArgs of the MCP tool gains the same Mode field with the same default, and the tool passes it through to the same query parser, so both surfaces share one rule.

Go regexp is RE2 and runs in linear time with no backtracking, so the property that made the handler choose path.Match holds for the regex mode too. The length bound of the pattern stays.

The web router gains a mode field on the search route, written only when it is regex, so an existing URL keeps its meaning.

Each list screen renders a StatusBar.svelte as the last row inside the bordered table container, with role="status". It takes the count text, the optional page range, the optional Pagination and the freshness line. The summary paragraph and the sr-only summary of today go, and Freshness.svelte renders inside the bar instead of under the page header. On Health the bar sits under the tiles and holds the “Updated n seconds ago” text and the Refresh button.

Section titled “D10. The differ preview is a HoverCard on a link”

NodeBadge renders a Differ, Missing or Unreadable result as an anchor to the name detail, wrapped in HoverCard.Root. The content renders DiffPreview.svelte, which reads /api/names/{fqdn} through apiGet on first open, keeps the answer for the life of the row, and shows one row per node from node_values of the matching RRset type, with the differing value in the warn tone and the finding age under it. A failed read renders the one-line error copy of the name screen. An Agree result stays a plain badge.

The registry documents hover-card as a preview of what is behind a link, so the rule that no fact lives behind a hover alone holds: a tap follows the link and the detail holds the fact.

Alternative: a Popover on the badge that opens on tap. Rejected because it makes the preview a destination and asks for a second tap to reach the detail.

Alternative: add node_values to the search response. Rejected because the Search API stays as it is and the name route already answers.

Every Table.Root sits inside a div with rounded-xl border overflow-x-auto, and the Search and Query log tables set a minimum width, so a name never breaks inside a label. Below 768px Search and Changes render a RowCard.svelte per row instead of the table: the relative name in mono with overflow-wrap: anywhere, the badges, the first record and the time. The breakpoint is one IsMobile-style media query hook shared with the shell, with the width as its argument.

@fontsource/geist and @fontsource/geist-mono are imported in main.ts. Vite copies their woff2 files under /assets/ because they are above the inline limit, so they load from the app’s origin and survive a Content-Security-Policy with no data: source. app.css sets --font-sans and --font-mono in its @theme block to the two families with the system stacks as fallback. The weights are 400 and 500, the two the contract allows.

The proposal places this in the last pull request so Sean can drop it alone.

  • [The sidebar block adds markup around every screen and the App tests render the shell] → App.test.ts renders inside Sidebar.Provider, and the shell test covers the three widths through the mocked media query.
  • [Uppercase badge text at 11px is harder to read than 12px mixed case] → the tracking of 0.04em and the 500 weight compensate, and the contrast check runs on the real tint values before the tokens land.
  • [Pastel writer hues can collide with a tone at low chroma, sand with warn most of all] → the hues sit 30 or more degrees from every tone and the chroma gap keeps them apart. The palette section of the mock shows the four side by side for the eye.
  • [The highlight layer drifts from the input when the font fails to load] → both elements share one font-mono stack, so a fallback applies to both at once and alignment holds.
  • [A regex that compiles in the browser is refused by RE2, or the reverse] → the client hint is advisory and the server answer renders through the existing ErrorAlert. The help line says “Pattern does not compile” and never “invalid”.
  • [A regex over the whole index costs more than a glob] → the index is in memory and under two thousand names, the regex compiles once per request, and the length bound stays.
  • [The hover card reads the name route once per Differ row the person hovers] → the read is one small request and is cached for the row’s life. A screen with many Differ rows reads only the ones hovered.
  • [The phone card loses the Nodes column’s finding time] → the card shows the finding time as its last line.

Every pull request lands behind the normal release flow of docs/operations/releases.md. No pull request touches live DNS, a zone or a node. Rollback of any pull request is a revert of that pull request and the next release, or a pin back to the previous image tag in the ArgoCD application through git revert of the pin commit. Pull request 5 adds a query parameter with a default that keeps today’s behaviour, so an older client and a newer server, or the reverse, keep working.

A copy of this design lives at docs/engineering/specs/2026-10-06-dns-control-ui-rev-design.md, because the Health screen and the search modes are operator surfaces and the runbook points at them.

None. Sean confirmed on 2026-10-06 that the four Health tiles answer the first question he asks when he opens the screen, so the tiles of decision D5 are final.