Skip to content

Visual language

The visual standard for Danbyte is defined in /CLAUDE.md at the project root. The running React SPA in frontend/ is its source of truth - read the shared primitives before adding UI.

In one breath

Restrained, real, neutral. Borders define edges, not shadows. Color exists only to convey state. The interface is built for technical operators who scan a lot of data fast - typography and spacing serve that, not decoration.

Tokens

  • Neutrals: Tailwind zinc. Not gray, not slate.
  • Status colors (only when conveying state):
    • Success - emerald
    • Warning - amber
    • Danger - red
    • Neutral - zinc
  • Primary / accent: --primary is Danbyte blue (styles.css), and the chart ramp is built from it. Earlier drafts of this doc claimed a neutral primary with no brand accent; the shipped token has been blue for a long time and the whole product is built and screenshotted against it, so the doc was the stale side and has been corrected here rather than the token. Blue is for primary action and selection only - it is not decoration, and it never carries meaning that belongs to a status colour.
  • One selection colour. Anything meaning "this is the selected thing" uses --primary. Canvas surfaces (3D, floor plan, site map, topology) can't read CSS variables today and hard-code #0ea5e9 in ~19 places, which is a different blue - so selection currently reads as two colours depending on which surface you're on. Until a readCssVar() bridge exists, keep new canvas code on the shared constant rather than adding another literal.
  • Links: never blue. Use the .link class (styles.css) - it inherits the surrounding text colour and reveals an underline only on hover and keyboard focus (with a focus ring). This keeps link-dense pages from turning into a wall of blue while still marking clickability. --primary is reserved for primary action / selection, never for a link. A trailing chain-glyph affordance is available as the opt-in .link-icon variant for the rare prominent standalone link; it is off by default to avoid per-row clutter and hover reflow in tables. The shared cell factories (components/cells/*) and TanStack Links alike all use .link.
  • Mono font: for every IP, CIDR, MAC, serial, ID, UUID, custom-field key.
  • Tabular nums: on every counter, percentage, timestamp.
  • Radii: rounded-md and rounded-lg only. rounded-full for presence/health dots and avatars.
  • Statuses are pills, never dots. A status renders as its ColorBadge pill everywhere it appears - table cells, dropdown options, the selected value of a select. A colored dot beside a plain name is not an acceptable compact form of a status.
  • Badges are squarish, never pills. Every count/label chip uses the Badge primitive (rounded-[5px]) - including chips floating over a canvas (map, floor plan, topology). Do not hand-roll rounded-full pill buttons for labels or counts; rounded-full stays reserved for status dots and avatars. Severity chips use the semantic variants (destructive, warning, success) as separate badges per severity, not one combined pill. A scale with two red levels (a vulnerability's Critical / High, Fix first / High) puts the worst on destructive-solid (solid bg-destructive) and the next on the soft destructive. Chips overlaying a tinted/tiled canvas sit on a solid bg-background/95 rounded-md border backdrop so the tint reads.
  • Tooltips never go white in dark mode. The plain tooltip is a chip: inverted on light (dark chip, light text), but on dark it steps up to a raised surface rather than inverting all the way to near-white, which glared against the zinc palette. Rich content - headings, muted secondary text, semantic colour - uses variant="panel" instead, because those colours are chosen against the page background. Use the shared Tooltip or InfoTip, never a title= attribute.
  • Canvas bands (topology layers): rows neutral by default - --muted toward --border, title centred on top unless a cable crosses there - side bands on a pastel zone swatch; never a free colour picker, never the role colour the cards already carry.
  • Arrowheads only on lines that have a direction - an application flow's (#163): a solid head in the line's own colour at the destination, at both ends for a flow both ways, drawn as a polygon (never an SVG <marker>, which the PDF sanitizer drops). Cables and sessions stay plain lines. A device dependency on the Topology map (#450) is the one canvas line with a React Flow marker at its downstream card, in its medium's colour; it is a screen layer the exports leave out.
  • Impact rings ("What if this fails?" on the Topology map, components/topology/what-if.ts): an outline on the card in the impact colours the impact lists use - thick --destructive for the failed device, --destructive for down, dashed amber for reduced redundancy - with every other card faded as a search miss is. Never a fill.
  • Flow diagrams draw one neutral row band per application, titled with its path, and neutral cards: the colour stays with roles and statuses.
  • Canvas notes are text in text-foreground/75 and Lucide icons in --muted-foreground, no box unless outlined (border-border on bg-card); never coloured.
  • Shadows: don't. Borders define edges. Exception: dropdowns/popovers get shadow-sm.

See /CLAUDE.md for the canonical class snippets per component (button, badge, tag, table, dropdown, etc).

Where to look

  • frontend/src/styles.css - the active design tokens and global styling
  • frontend/src/components/ui/ - the shadcn primitives (button, badge, input, checkbox, select, command, popover, dialog, …)
  • frontend/src/components/forms/ - the form-field layer built on those primitives, re-exported from one barrel (@/components/forms)
  • frontend/src/components/ - shared and domain components (DataTable, ListPageShell, DetailShell, KvCard, StatusBadge, ObjectPicker, …)
  • docs/architecture/shadcn-tokens.md - the token/variable reference

Never hand-roll a control

Every interactive control comes from the primitives above. A native <input type="checkbox">, <select>, or a <div> styled to look like one is wrong even when the classes approximate the design: it renders with the browser's own widget, ignores the theme, and drifts the moment tokens change.

Need Use Not
Checkbox with a label FormCheckbox from @/components/forms <label><input type="checkbox">
Bare checkbox (table cell, list row) Checkbox from @/components/ui/checkbox <input type="checkbox">
Dropdown of fixed options FormSelect, or Select for an unlabelled one <select>
Long / searchable option list, and any field whose options are rows of another table (site, location, VRF, role, tenant, interface) FormCombobox / Combobox; FormStatusSelect for a status FormSelect or <select> fed with query rows
Searchable picker in a popover Popover + Command (see ui/combobox.tsx) a hand-built input + <button> list
Free text with common values FormText with suggestions (or SuggestInput directly) <datalist>, or a <select> that locks out other values
Object reference ObjectPicker or an existing domain picker preset (onPickMany when a list collects several at once) a bespoke fetch + list
A long read-only text: a rendered config, JSON, a log, a diff FileViewer (components/file-viewer/): read-only CodeMirror on the semantic tokens, line numbers, search (hotkey for /), wrap, copy, download, syntax colours on the --syntax-* tokens (language: json, xml, yaml, ini, netconf, log, text; the default config, or auto, picks from the file name then the first lines), outline and folding for config and JSON, a diff view (unified or side by side), resizable with the height kept per user (storageKey), full screen a <pre className="max-h-96 overflow-auto">
PRTG sensor kind SensorKindPicker (button + dialog) or SensorKindBrowser (inline) from components/prtg/sensor-kind-picker.tsx: search, category rail, sortable columns, Standard kinds pinned a FormSelect of kinds, or another kind list

Labels name their control. Field (and every Form* built on it) gives its <label> an id and hands it to the control through context: Input, Textarea, SelectTrigger, Combobox, MultiCombobox, Checkbox, Switch, DatePicker, TimePicker, IdMultiSelect and TagMultiSelect take the id, aria-labelledby, aria-describedby for the hint and error, and aria-invalid on an error. A child of <Field> built from these needs no wiring. A field that sits in a page header beside the other filters (a list's device filter) passes labelHidden (Field, and ObjectPicker with its presets): the label stays, for screen readers only, and the control lines up with the buttons. A second control in the same field (a unit box beside a number) goes in NoFieldControl with its own aria-label; popover, dialog, sheet and menu content already cut the link. An unlabelled control outside a Field (a filter rail) takes an aria-label. A field whose body is a run of controls that each name themselves (the device form's Card lines) is a <Field group>: the same caption, but it names the role="group" instead of pointing a <label> at one control, and nothing inside takes the field's id. A caption that is not a <label> (a popover's PopoverField, a filter rail heading) names the control under it through CaptionControl; <PopoverField group> is the group form. CodeEditor takes its name from the surrounding Field too, or from aria-label. An icon-only button sits in IconTip (components/icon-tip.tsx): its label is both the aria-label and the tooltip. Scrollable <pre> blocks and regions with nothing focusable inside take tabIndex={0} so the keyboard can scroll them. components/a11y-control-names.test.tsx sweeps the source for select triggers, comboboxes and icon buttons without a name.

Radix controls report changes differently from DOM ones - Checkbox uses onCheckedChange(bool) and Select uses onValueChange(string), not onChange(event). A Radix SelectItem also cannot carry value=""; give an "any" row a sentinel value and map it at both ends.

Dead classes have bitten this codebase three times. The archived reference/design/tokens.css was deleted in 9ba017d while 450+ call sites still referenced its classes:

class sites found
.ck (checkboxes → browser defaults) ~40 2026
.num (tabular figures) 367 2026-07
text-destructive-foreground (delete buttons) 89 2026-07

All three are fixed, .num now lives in src/styles.css, and destructive confirms use variant="destructive". The lesson stands: if you find a class with no definition behind it, delete the markup and use a primitive. Grep styles.css before trusting a bare class name.

Loading, and the shared Maps parts

One loader. A page, section, panel or canvas that is fetching shows <Loading /> (components/loading.tsx): the first-load splash spinner with a small muted Loading… under it, centred in the box it loads. The splash itself is the same component with its label kept for screen readers only. A table keeps its built-in loading row. A pending labelled button keeps its size and swaps the verb (Saving…); a spinner on its own is for icon-only buttons. The ellipsis is always the one … character.

The Maps pages (Topology, Site map, Floor plans) build their chrome from shared parts, so a control reads the same on each:

Need Use
Toolbar controls (h-7, text-xs, size-3 icons) components/map-toolbar.tsx: BarButton, BarIconButton (its required label is the aria-label and the tooltip; destructive is ghost with destructive text; tipSide moves the tip off the bottom for a control that is not in a top bar), BarToggle (aria-pressed, muted when off), BarMenuTrigger (label plus chevron, no tooltip) and BarTip (the plain default tooltip, below the control)
Undo and Redo on a bar HistoryButtons (components/topology/history-buttons.tsx), each with its key in the tip; HistoryMenuItems for the same two in a More menu
A map's Arrange ▾ ArrangeMenu (components/topology/arrange-menu.tsx): Reset layout, the bands and the Layout group (direction, Levels…)
Zoom buttons in a map's corner ZoomControls (components/topology/zoom-controls.tsx): Zoom in, Zoom out and Fit view, the bar's icon buttons stacked, tips to the right
A map embedded in another page (a device's Map tab, a trace, a tunnel) EmbeddedMap (components/topology/embedded-map.tsx): the Diagram's Detailed cards and Elbow lines, no overview, a folded legend
A rail map (VLANs, virtual networks) RailCanvas (fills a page, scrolls) or RailFrame (a card on a detail page), from components/topology/rail-diagram.tsx, with RailLegend (components/topology/rail-legend.tsx) in the corner
Leaving the map for an object's page OpenLink (components/open-link.tsx): a router link drawn as a bar button with a leading ArrowUpRight, e.g. Open device. Drilling in on the same map is a plain button, no arrow
Unsaved edits on the way out LeaveGuardDialog (components/leave-guard-dialog.tsx), driven by useBlocker({ withResolver: true }): Discard unsaved changes? with Keep editing / Discard and leave
A shortcut in a tooltip or menu Kbd (components/ui/kbd.tsx), with modKey() (lib/mod-key.ts) for the modifier: ${modKey()}S reads ⌘S on a Mac, Ctrl+S elsewhere
The Objects sidebar ObjectsPanel (components/objects-panel.tsx): Objects and its count, the search box, CheckFilterTabs, the hidden row, then the page's ObjectsSections. Each group inside is a FoldableGroup (components/foldable-group.tsx) with its count and, where it can be hidden, the VisibilityToggle eye
How much is hidden, with the sidebar shut HiddenChip (components/hidden-chip.tsx): N hidden · Show all, in the corner the page names with position (the one its MiniMap, legend and attribution leave free)
A right-click menu on a canvas PointerMenu (components/pointer-menu.tsx): the shared dropdown opened at the pointer. A key an item shows (H, Del) is passed in keys, so it acts on what was right-clicked, not on the selection
The detail panel over a canvas PanelShell (components/map-panel.tsx): title and Close, PanelRow key/value rows, PanelSections under a SectionLabel, and the actions at the foot (Open … first). SectionLabel also heads a legend
A name that will not sit clearly by its object on a floor plan The label pass's callout (components/floorplan/plan-callouts.ts, drawn by plan-callouts-layer.tsx): a plain rounded-md box in --popover with a --border outline, at a constant size on screen, the name then at most three lines (a status or role as its badge, never a dot); a straight leader from the middle of the box edge facing the object to the object's edge - 1.25 px --muted-foreground on a 3 px --background casing, a small dot at the object - so it reads on any map or plan. Hover or selection lights the pair in --primary with a thicker leader, drawn over the rest; the others keep full ink (never faded). A row of racks whose names do not fit gets one row name instead (plan-rows.ts): bold text along the row at its angle, never upside down, on a --background plate with a --border outline. From afar the row is one bar along its line in its racks' colour, and a room's rows one --popover plate on the room with the racks' icon square and Data Hall 1 · 120 racks (plan-lod.ts)
A placed object or planning tile on a floor plan Display → Tile icons (on by default; components/floorplan/tile-face.ts, drawn by TileShape and printed by plan-svg.ts from the same layout): the tile is a solid rounded block in the colour Color by gives it - its type's, its role's, a status's or a capacity level's, never one picked from a name - with a 1 px border a shade of that colour (darker on a light page, lighter on a dark one). A tile linked to nothing is the same colour at 60 % over the page. On it, centred in what the front-edge marker and the capacity bar leave free, the Lucide icon of what it is (tileIcon: the device's or its type's, the tile type's, the role's, else the kind's - container for a rack, rows-4 for a cabinet), white wherever white keeps 3 : 1 on the fill and near-black otherwise; the name and the marks take the same ink. The glyph scales with the tile (at most 30 px on a rack-sized tile, more on a big one), sits above or beside a name drawn in the tile and gives way to it when both do not fit, and is never drawn under 10 px. Icons are one SVG sprite per canvas (tile-glyph.tsx): one <symbol> per icon, a <use> per tile. A tile the colouring is not about stays pale so the racks read; zones and photos are unchanged. Off, tiles are the plain tint they always were
A floor plan from afar Display → Detail: Auto (components/floorplan/plan-detail.ts): one clear picture per zoom, never everything at once. Whole floor: rooms as flat blocks in their area type's tint (no hatch), thin walls, one centred room label (room-labels-layer.tsx) - the name in --foreground semibold, a muted facts line under it (72 racks · 61% full, 3 UPS), an alarm as a squarish badge in its check colour - at a constant 12 / 10.5 px on a halo of the page, upright or along a narrow room, never over another (the smaller room gives way, its name in the shared tooltip on hover); the base map blanked to --background inside the building. A hall on screen: rows as bars, icon tiles, no callouts but the hovered or selected one's, zones a light wash, door swings back. Racks readable: short names (A01), the capacity bar and the camera cone only in focus, the front edge faint, a fine faint hatch. Always full is the old everything-everywhere look
Zooming into a floor plan from afar Click to zoom (components/floorplan/plan-zoom.ts): the room a click would fit lights its outline under the pointer (the selection's stroke), the cursor a pointer; the view eases with the 3D fly-to's cubic in-out (easeInOut), instantly under reduced motion. Room labels stay upright - over their room's edges before they turn - and only a name ever turns; a badge never does
Filtering what a map shows (floor plans) PlanFilterMenu (components/floorplan/plan-filter-menu.tsx): a BarMenuTrigger Filter with its count Badge, a popover of the lists' FacetGroups and ExpressionFilter, a Hide others Switch; then the lists' SavedViews (compact, h-7) and, while a filter is on, HiddenChip with position="inline" - what it keeps, N shown, Clear. What it leaves out recedes at the rack table's 25 % (areas 35 %), never a new colour
A chip on a canvas (Partial map) Bordered bg-background/95, no shadow and no blur: shadows are for overlays
A legend on a canvas LegendFrame (components/map-legend.tsx): bordered and opaque bg-background, no shadow and no blur, headed Legend with a Hide legend button, open or folded (remembered per browser under its storageKey, or held by the page), so a colored rail or card behind it never shows through; folded, an outline xs button with the List icon. w-60 unless its rows need their own width (w-fit). A legend that is part of an exported picture keeps its Hide button out of the export: the button and the folded chip carry data-export-skip, which the floor plan's PNG export filters out. The floor plan draws its keys - Color by, cables, area types - as sections of one card (PlanLegend, components/floorplan/plan-legend.tsx), never as boxes stacked in the corner; hideable={false} stays for a legend that must never fold. The topology's CanvasLegend, the rail maps' RailLegend, the site map's legend and the 3D room's key are built on it. TopologyCanvas takes its box as keepClear, so a fit keeps the map beside or above it; RailCanvas keeps room for it under the drawing
A legend's rows From components/map-legend.tsx: LegendRow (swatch, then label), LegendLine (a line keys a line), LegendTones (a colour mode's keys as short lines, wrapping), and LegendPills / LegendStatuses for roles and statuses as their ColorBadge / StatusBadge pills - never a coloured dot beside a name. LegendItems draws a list of LegendItems in that order
Speeds lib/speed.ts: parseSpeedMbps (a bare number is kbps, as on the server), parseSpeedKbps (a speed typed into a *_kbps form field: whole kbps, null when blank, undefined when it is not a speed), fmtKbps / fmtMbps (short 10G, 100/20M; long 10 Gbps) and the one tier scale, SPEED_TIERS, that the faceplates, the 3D room and the topology's and the site map's Speed colouring share
Time left to an end date (end of life, support coverage) LifetimeBar (components/cells/lifecycle-cell.tsx) is the one time bar: a thin muted track filled with the elapsed share of start → end, a terse countdown (EoL in 2 y, Ends in 40 d) and the exact date in the shared tooltip. Its colour goes by time left against the source's warning window - destructive once past, warning inside the window, else primary - never by percent, so it agrees with the status pills. An end without a start is the countdown alone, no end is the source's pill, nothing is a dash: never an empty track. LifecycleBar wraps it for a device type or platform
What monitors an object (a device's or VM's Overview and header) MonitoringHeaderBadge (components/monitoring/monitoring-bar.tsx) in the header: the overall pill (worst wins) with the sources on hover. MonitoringBar on the Overview: the overall pill once in its header line, then up to three problems, each a link with the state as a w-1 left edge in its semantic colour plus the state's name (no second pill), the source as a bordered muted chip and the message clamped with the shared tooltip; then one segment per source - name, a stacked h-1.5 rounded-md bar (destructive / amber / emerald, muted for unknown and paused), counts as muted text. All clear, it is one line (slot="compact", in the grid); with problems full width (slot="banner"). At most one pill per card. The Sensors strip and the Monitoring tab's PRTG row keep MonitoringSourceRow
A measured value against its limits (a PRTG channel, a check's reading) Gauge (components/gauge.tsx): a half-circle track, the value as an arc and as the big number with its unit, min and max at the ends, no needle. Props value, unit, min, max, warn and error - each a band { below?, above? } drawn as a thin arc outside the track in the warning and destructive colours. The value arc takes the colour of the band it is in (gaugeTone), emerald inside the limits, and stays neutral when there are no bands
A value from a fixed set of outcomes (a PRTG lookup channel: Yes / No, Good / Weak / Unsafe) LookupBar (components/lookup-bar.tsx): one segment per possible state in order, the current one filled in its tone (ok emerald, warning amber, error destructive, neutral muted), the others quiet track, the current label underneath, each segment named in the shared tooltip. Props states ({ key, label, tone }[]), current, optional label
A glance at recent values Sparkline (components/sparkline.tsx): a small line in currentColor, muted by default, scaled to its own range, gaps left as gaps. The graph you read is a ChartContainer chart
How full a rack is lib/rack-capacity.ts: above the tenant's warning level amber, above its critical level red (80 / 95 % by default, useCapacityThresholds), in the status colours - never the accent - and formatWatts. CapacityBar (components/cells/capacity-bar.tsx) is its thin bar; PowerFigure (components/cells/power-figure.tsx) reads a rack's power as demand / supply and PortsFigure (components/cells/ports-figure.tsx) its ports as in use / counted. On a map the level goes on a rack's fill and monitoring keeps its outline (components/floorplan/tile-paint.ts). IPAM prefixes keep their own scale (UtilCell)

Anything that copies to the clipboard goes through copyWithToast() (lib/clipboard.ts), so a copy that fails always says Couldn't copy.

Widths and truncation are the primitive's job

A control must declare one width contract, and the shared primitives do:

primitive contract
Input, Textarea, SelectTrigger, Combobox w-full min-w-0 - fill the slot, and stay shrinkable
compact toolbar control an explicit w-* plus shrink-0 at the call site

Never let a control size itself to its content. SelectTrigger shipped with upstream shadcn's w-fit, so it was narrow when empty and grew when a value was picked - a labelled field in a grid row changed width and shoved its neighbours.

Long values ellipsise, they don't clip. Watch for one trap: truncate and line-clamp-* both set display, so they lose to a sibling flex on the same element. If a value span needs flex (icon + text), put the truncation on the inner text node instead.

Dialog width: use size, never a class

DialogContent and AlertDialogContent take a size prop (sm | md | lg | xl | 2xl | 3xl, default md = 28rem) which is keyed off data-size.

Do not pass a width class. cn() is tailwind-merge, which only dedupes classes carrying the same modifier - so an unprefixed max-w-lg does not cancel the primitive's sm:max-w-*. Both land, specificity ties, and Tailwind emits the variant later, so the default wins on every desktop. Six dialogs shipped believing they were wide and weren't. data-size can't be clobbered that way.

Pick by content, not by taste: md for 2–4 fields, lg for 5–7, xl for 8+ or any 2-column grid, 2xl/3xl for tables, trees and traces.

List-page chrome

Every list page is ListPageShell + DataTable - no exceptions, so header height, search placement, action order, and the loading/error/empty treatment can't drift page to page (source of truth: frontend/src/components/list-page-shell.tsx, reference implementation routes/manufacturers.index.tsx):

  • The shell owns the header (title · count chip · actions) and the scrolling body. The actions follow the action ribbon order: actions - TableActions (Import / Export) and any view controls - then Add X (the shell's add prop, solid primary) at the right end.
  • Search sits in the toolbar row over the table, not the header (#507). The shell draws one row at the top of the body - the narrow-window rail button, Saved views, then the search box - and the page's DataTable moves its own controls (selection count, Download, Columns) up into the same row, right-aligned, instead of drawing a second row. The row sits outside the loading switch, so the search box never remounts while someone types. A page whose list is not a DataTable still gets the row, with search alone.
  • The header is one h-14 row when everything fits; the toolbar row wraps too - the search box narrows (18rem down to 10rem) before Download and Columns move to a second line, so a 320 px window shows every control. Nothing in a page header is ever scrolled out of sight behind a hidden scrollbar - the same goes for DetailShell's actions and tab strip, which wrap too.
  • Add X is the copy for a create button, with no icon. Not "New X".
  • Filters live in the rail (FilterRail + FacetGroup, usually via useTableFilters), not in a second toolbar row under the header. A filter that is genuinely either/or (no "any" state) is a SegmentedTabs switch in the action cluster instead; a single-select filter over a long fixed list can be a Select under a rail heading.
  • A facet with no options renders nothing, and a derived enum facet (a yes/no or state split computed from the row rather than read off a catalog object) sets hideWhenSingle so it also disappears when every row lands in the same bucket - ticking its one option would select the whole table. Rail length is the budget: a rail you have to scroll to reach Manufacturer is worse than a short one.
  • Empty is either the DataTable "No results." row (a filter matched nothing) or an EmptyState carrying first-run guidance (nothing exists yet) - never a bare paragraph. Loading and errors are the shell's, via its query prop.
  • A tabbed list (Prefixes, Drift, Alerts, Compliance, Jobs) puts one h-10 SegmentedTabs strip above the shell and renders a shell per tab, so each tab supplies its own count, search, rail, and actions.
  • Tables are paged by DataTable alone. When the API pages server-side, hand it serverPagination={{ page, pageCount, totalRows, onPageChange }} so that one pager drives the server - don't add a second Prev/Next row.
  • A grouped table (groupBy, e.g. Prefixes by VRF) pages like any other: a page counts rows after expansion, group banners included, at the user's page size (#479). The header checkbox ticks the page's rows, never a whole group behind a banner; Select all N ticks the rest. pagedWhenGrouped={false} opts out, only for a grouped table that stays short.
  • The big lists - Devices, Interfaces, Cables, Virtual machines - page, sort and filter on the server through useServerList (lib/server-list.ts, #482): it keeps the page, ordering, search and the rail in the URL, reads the rail's counts from <list>/facets/, asks for the slim view=table row (plus the catalog columns on show), and hands DataTable its serverPagination (with Select all N across pages), serverSorting (only what the server sorts keeps a sortable header) and an exportAll that walks every matching row. The rail is useServerTableFilters: the same URL params and saved-view snapshot as useUrlTableFilters, with counts from the server. A facet the server does not count (one filled from another request, like Monitoring) is left out of facets. A new big list adds a TableSpec in api/list_specs.py and the TableListMixin on its viewset.
  • A list page that fetches its rows in one capped request hands the shell the server's answer, page={query.data}. When count exceeds the rows that arrived, the count chip reads N of M in the warning badge, an amber notice over the table says the list is cut off, FilterRail says its counts are partial, and DataTable's Download names the rows it holds - one context, no per-page wiring beyond the prop.
  • A list request without page_size answers 100 rows. A table, picker or dropdown that needs every row fetches through apiAll (lib/api-all.ts), which walks next 1,000 rows a request up to 10,000 and hands back one page-shaped answer; anything else names its page_size. Never call api on a list without one (#447), and never name a page_size above the API's 2,000 cap: walk next instead (#452). Keep reads at 1,000 rows or fewer; the server limits pages above 1,000 to two at a time per user, and api queues any such read to match and retries a 429 after its Retry-After.
  • An embedded table on a detail page fetches one capped page (page_size=500) rather than paging. Hand DataTable the server's total={q.data?.count} with it: when more rows exist than arrived it says so, instead of a site with 600 prefixes showing exactly 500 and looking complete.
  • An embedded table that can run past a screenful (devices, interfaces, IPs, VMs, prefixes, VLANs, logs, change history) turns on DataTable's searchable with a searchPlaceholder naming what it searches ("Search devices…"); the Embedded*Table helpers have it on, searchable={false} for a list that stays short. It filters loaded rows only - with total set, a capped list says the search covers the first page; a serverPagination table needs a server search instead. Columns are matched by their text: a cell-only column reads its meta.export value or the row field named like its id.
  • A list that is a view of another list (e.g. /racks/elevations) gets the shell's backTo / backLabel breadcrumb rather than its own nav.
  • A table that points at its rows' objects somewhere else on the page (a rack on a floor plan) uses DataTable's opt-in onRowHover (the row under the pointer, null once it leaves) and onRowClick. A click on a link, checkbox, button, input or other control in a cell stays that control's, as does a text selection or a click in a menu a cell opened; a cell can mark more with data-row-click="ignore". Without the props a table is unchanged.

Row actions always go through RowActions / actionsColumn(), and every list-page table names a tableId so it gets the persistent column picker. Every tableId is registered in frontend/src/lib/tables.ts with the api list path its rows come from (null when they are not one list's rows) - routes/-table-registry.test.ts fails on an unregistered id, and an id built at runtime passes autoColumns (an api path, or false) itself.

A table wider than its pane scrolls sideways inside its own frame, with the row actions pinned to the right edge, and the Download / Columns bar wraps instead of running off. The pinned column holds only the compact row actions (edit, delete - an icon or two). Wider per-row controls go in an ordinary column that scrolls with the data: the interface tables keep cable status, trace, connect and the IP buttons in port_actions and pin only Edit. A pinned column as wide as the pane covers every data column on a narrow window. Its header cell, and a stickyHeader table's header row, are opaque, so the columns scrolling under them never show through. The page itself never scrolls or clips sideways. For that, every flex item between the table and the page carries min-w-0: ListPageShell, DetailShell and DataTable already do, and a bare DetailTab gives it to each direct child. A pane that nests its own rail-and-table row inside another flex row puts min-w-0 on that row too. components/table-overflow.test.tsx checks this for the shared shells and the prefix IPs pane. The app's main column is overflow-clip, not overflow-hidden, so not even focusing a control past its edge can scroll the page sideways.

stickyHeader makes the table's own frame the scroller in both directions, so it needs a parent that bounds its height - the pane is a flex min-h-0 flex-1 flex-col column (see PrefixIpsTable). Then the header row stays in view and the sideways scrollbar sits at the pane's bottom edge rather than after the last row. In a pane that grows with its content the header does not stick.

A DataTable or OverviewTable wider than its frame gets a floating scrollbar (components/table-scroll.tsx): a thin proxy bar, sticky to the viewport's bottom edge while the table is on screen, that settles under the table once its end scrolls into view and stays in step with the table both ways. It replaces the frame's own horizontal bar, and a soft inset shadow marks each side with more columns to scroll to. A stickyHeader table that scrolls in a bounded pane keeps its native bar (already at the pane's bottom edge), and printing hides both. Shift-wheel and trackpad sideways scrolling work on the table as before.

The rule: a sideways scrollbar is never below the fold. Anything wide and tall enough to scroll sideways gets the same floating bar, never a bare overflow-x-auto whose bar sits after the last row. table-scroll.tsx has the two wrappers for content outside DataTable:

  • ScrollFrame - the bordered frame around a shadcn <Table> (the table's own container scrolls). SimpleTable and the hand-built detail tables (component templates, members, terminations, search results, device bays, modules and antennas) use it.
  • HScroll - wide content that is not a table: the rack elevations wall, the rack and cabinet drawings when zoomed past their column, the device's rack card, the image list, the OID explorer. className lays out the content, frameClassName draws the frame, viewportRef reaches the scroller for code that measures it. While it overflows the viewport is a named, focusable region, so arrow keys scroll it; it prints unclipped.

Both show the bar only while the content overflows, add no height of their own (the proxy takes the place of the native bar), and stay in step with the content both ways. Out of scope: canvases that pan (topology, floor plans, the site map), bounded boxes whose bar is already in view (a max-h-* list, a dialog's code block, a kanban board that fills its pane), and one-line strips (headers, tab rows, faceplates, cable traces).

Pinned columns. Every DataTable lets a column be pinned to the left edge from the Columns menu (a Lucide Pin / PinOff button per shown column, labelled through the shared Tooltip). A pinned column keeps its place in the column order and sticks (position: sticky) only once sideways scrolling would carry it past the left edge, at left = the widths of the pinned columns before it in display order, so pins stack up in table order as each is passed; the select column sticks too whenever anything is pinned (lib/column-pins.ts, widths measured from the header row). Pins are part of the saved layout (pinned beside order and hidden in /api/prefs/columns/<table>/; the list's order does not matter, and older layouts without the key load unchanged). Guardrails: the stuck band is capped at 60% of the frame (later pins scroll), and pins are ignored in a frame under 640 px. A stuck cell is opaque - --background with the row's stripe / hover / selected tint over it (styles.css) - and the right-most column that is actually stuck carries a 1 px --border hairline; no shadow. Nothing is reordered, so exports and prints keep the table's order. A table where pinning makes no sense passes pinnable={false}. Known limit: a page's own rowClassName tint does not reach the stuck cells, which show the plain row colour.

The action ribbon

A page header's buttons follow one order everywhere (#507) - source of truth frontend/src/components/action-ribbon.tsx, laid out by DetailShell and ListPageShell from their slot props, so a page never orders them by hand:

Slot What goes there Look
add Creating something: Add IP, Add device, Add object Button default - solid primary
edit EditButton (a link to the edit route, or onClick for a dialog) tinted - the primary hue, softened; the only tinted button in a header
actions The few verbs an operator uses daily: Connect, Show on, Topology, Run, Check now, Test outline
exports DropdownMenuItems for the Export menu: spec sheet, PDF report, Print label, SBOM, CSR. The route's Import / Export joins them outline menu
more DropdownMenuItems for the More menu: Clone (CloneMenuItem), Sync from type, Move to site…, Renumber…, Add child prefix. Plan a change joins them outline menu
remove DeleteButton ghost, destructive text - always last
  • The order is: page actions, Export, More, then Add, Edit and Delete at the right end. Edit sits right after Add, is the one tinted button, and only Delete goes further right, so the ways to change data read together where the eye ends.
  • Outputs (anything that hands you a file, a PDF, a label or the clipboard) go in Export; rarer verbs in More. A page with neither shows neither menu. A menu whose items all decline to render (no label template matches, no import right) says Nothing available rather than opening empty.
  • A menu item that opens a dialog keeps the dialog outside the menu - the menu unmounts its items when it closes. Such actions are hooks returning { item, dialog } (useObjectReportItem, useRackSyncType, useRackMove, useCabinetSyncType, useExportBundle); the page puts item in the slot and renders dialog in its body.
  • Several places to look an object up fold into one Show on control (ShowOnFloorPlan with siteMap, CableShowOn): a plain button when there is one place, a menu when there are more.
  • Permission gating stays on the page: pass canDo(…) && <EditButton …/>; a falsy slot renders nothing.

Column factories

One entity, one column factory (frontend/src/components/columns/), reused by its list page and every embedded table. A second ColumnDef[] for the same entity is how a row starts reading differently depending on which page you opened it from - a device that shows its compliance marker on /devices and hides it on the site page, a site link that is blue in one table and neutral in the next.

Entity Factory
Prefix buildPrefixColumns()
IP address buildIpColumns()
Device buildDeviceColumns()
Interface buildInterfaceColumns() (+ DEVICE_INTERFACE_COLUMNS preset)
VLAN buildVlanColumns()
Rack buildRackColumns()
Cluster buildClusterColumns()
Virtual machine buildVmColumns()
Aggregate buildAggregateColumns()
Cable buildCableColumns()
VRF buildVrfColumns()
Site buildSiteColumns()
Device type buildDeviceTypeColumns()
Device role buildDeviceRoleColumns()
Service buildServiceColumns()

Each takes options - never per-caller branches inside the factory:

  • include / omit pick columns; the factory's canonical order always applies, so two pages showing the same columns cannot show them in a different order. buildPrefixColumns also takes order for the one surface that genuinely leads with a different column.
  • selection, actions, humanIds add the checkbox, actionsColumn(), and the # numid column.
  • violations adds the compliance marker, monitoring the roll-up status column, tagFilter wires tag chips to a page filter (omit it and the chips are static rather than falsely clickable), cfDefs adds custom-field columns.
  • A handful carry a named presentation knob where an embedded pane genuinely renders a column differently from the list - siteVariant (linked vs muted plain text), buildClusterColumns' typeVariant, buildCableColumns' labelVariant / terminationsLinked / statusEditable, buildServiceColumns' linked (the device / VM pane renders the name and IP as plain text), and the header labels vidHeader / nameHeader / heightHeader. Prefer one of these over a second ColumnDef[]; the point is that the variant is declared at the call site instead of hidden in a copied column.
  • plainHeaders, zeroCounts and countFacets keep an older surface reading exactly as it did: a read-only or embedded table that never offered sorting on a column, one that prints 0 rather than - for an empty count, or a tab that filters counts by range instead of the list page's in-use / unused split.
  • A page's own columns are spliced around the factory's output (rack position, monitoring bindings, a virtual-chassis Member column, the cables list's trace-plus-row-actions pair) - see routes/locations.$id.tsx, routes/racks.$id.tsx, and routes/cables.index.tsx.

Catalog columns

DataTable adds the rest by itself (#243): for a registered table it asks /api/list-fields/ what the list's rows carry and offers every field no factory column covers - and every custom field (cf_<key>) - as a column that starts hidden, sorts, exports, and renders by its kind (components/columns/auto-columns.tsx). So a factory hand-writes only the columns that need a look of their own (a badge, a link, a facet), and:

  • a column whose id is not the row key it shows sets meta.field (the device factory's type shows device_type, the cable factory's a shows a_terminations), else the menu offers the field twice;
  • a page that leaves a field out on purpose passes autoColumns={{ exclude }};
  • rows that wrap the list row ({ kind, ip }) pass autoColumns={{ get }};
  • a new field worth a column goes into the list serializer, with the joins that keep api/tests_list_queries.py flat - it then appears in the menu with no frontend change. Detail-only getters use @detail_only.

An object value reads as its name; a record with no name of its own reads as its parts (a link peer sw1 · Gi1/0/1, an unlabelled cable #50), the same in the cell, the sort and the export. A field whose values render no text on the rows seen so far is not offered.

Object references inside a cell come from components/cells/: siteColumn / SiteCell, deviceColumn / DeviceCell, plus locationColumn, rackColumn, platformColumn, manufacturerColumn, vrfColumn, tagsColumn, timeAgoColumn, numidColumn. They render a reference as a link (never plain text), underlined on hover and never text-primary blue, and they carry the facet meta the filter rail reads. Each column helper takes className for tables that run text-xs.

Detail-page tabs

Every object detail page follows one tab convention (source of truth: frontend/src/components/segmented-tabs.tsx, reference implementations routes/devices.$id.tsx and routes/interfaces.$id.tsx):

  • The breadcrumb header and the summary section carry only the headline: the object's name/title, status/state badges, one subtitle line, tags and the description. No facts, counts or figures - not even one or two - and no bands of text under it: every fact goes in the Overview cards.
  • All the remaining attributes live in an Overview tab - the first tab, and the default - rendered as KvCard tables (<KvCard title rows>) in a grid gap-6 lg:grid-cols-2, grouped into a few sensibly-titled cards. This is the "read it as tables in the page body" layout. A settings-style page that groups its facts in SettingsCards (the PRTG Overview) puts the same rows in the card with <KvTable inset rows> and layout="flush", and the card's actions in its footer.
  • After Overview come the related-object tabs (with a count where the API provides one), then always Journal and Change log as the last two, in that order.
  • On a narrow window the tab strip wraps onto more rows instead of scrolling, so Journal and Change log never sit out of sight past its edge. The header's actions do the same beside the breadcrumb, moving under it when less than 18rem is left.

Never render Change log (ChangeLogPanel) or Journal (JournalPanel) - or a wall of attribute fields - inline in the header. Attributes go in the Overview tab's KvCards; history and journal are always their own tabs.

The detail hero

The summary section itself is DetailHero, passed to DetailShell's hero prop (source of truth: frontend/src/components/detail-shell.tsx, reference implementation routes/aggregates.$id.tsx). It owns the section wrapper and the title element and its size - a page only supplies content:

slot renders
title (+ mono) the page's single <h1>, always text-2xl font-semibold tracking-tight
badges status/state chips, inline with the title and wrapping with it
subtitle one secondary line - a parent link, a facility ID, ports, a second row of chips
tags <TagList tags={…} />
description the object's description
children anything else in the left column, below the description
stats + statCols the SLA page's figure rail - no other page uses it

Facts do not go in the header: a count, size or utilisation is a row in an Overview KvCard - custom fields included, as CustomFieldValues layout="cards" in the Overview grid. The one exception is the SLA page, whose stats rail keeps the agreement's live figures (this period, budget left, members); no other page passes stats.

Never pass a title size, and never hand-roll the section. The hero was copied 42× before this primitive existed and had drifted to four title sizes (text-lg, text-xl, text-2xl, text-3xl), three title elements (div/span/h1, only four of them a real heading), two incompatible layouts, a local DetailStat fork that rendered prefix utilisation 50% larger than every other stat in the product, and one page (cables) with no title at all. If a title is an identifier - IP, CIDR, ASN, interface, circuit ID - pass mono; if it is a coloured catalog object, pass the ColorBadge as title so the badge still sizes itself and the <h1> still lands in the document outline.

A hero needing an extra full-width band under it (SNMP credentials, CustomFieldValues, a usage note) renders DetailHero and the band as siblings in a fragment. Prefer folding the content into a slot: extra stacked strips push the tab bar down the page, which is why the prefix page's ancestor chain is now its hero subtitle and its subnet-details disclosure sits at the top of the Overview tab.