dns-control UI rev
Context
Section titled “Context”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 / Non-Goals
Section titled “Goals / Non-Goals”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-testidattributes 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.
Decisions
Section titled “Decisions”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.
D3. Badge text uppercases by CSS
Section titled “D3. Badge text uppercases by CSS”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.
D8. The regex mode is a server parameter
Section titled “D8. The regex mode is a server parameter”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.
D9. One status bar per list
Section titled “D9. One status bar per list”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.
D10. The differ preview is a HoverCard on a link
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.
D11. Tables on a phone
Section titled “D11. Tables on a phone”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.
D12. The font ships in the bundle
Section titled “D12. The font ships in the bundle”@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.
Risks / Trade-offs
Section titled “Risks / Trade-offs”- [The sidebar block adds markup around every screen and the App tests render the shell] →
App.test.tsrenders insideSidebar.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-monostack, 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.
Migration Plan
Section titled “Migration Plan”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.
Open Questions
Section titled “Open Questions”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.