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. Notgray, notslate. - Status colors (only when conveying state):
- Success -
emerald - Warning -
amber - Danger -
red - Neutral -
zinc
- Success -
- Primary / accent:
--primaryis 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#0ea5e9in ~19 places, which is a different blue - so selection currently reads as two colours depending on which surface you're on. Until areadCssVar()bridge exists, keep new canvas code on the shared constant rather than adding another literal. - Links: never blue. Use the
.linkclass (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.--primaryis reserved for primary action / selection, never for a link. A trailing chain-glyph affordance is available as the opt-in.link-iconvariant 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 TanStackLinks 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-mdandrounded-lgonly.rounded-fullfor presence/health dots and avatars. - Statuses are pills, never dots. A status renders as its
ColorBadgepill 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
Badgeprimitive (rounded-[5px]) - including chips floating over a canvas (map, floor plan, topology). Do not hand-rollrounded-fullpill buttons for labels or counts;rounded-fullstays 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 ondestructive-solid(solidbg-destructive) and the next on the softdestructive. Chips overlaying a tinted/tiled canvas sit on a solidbg-background/95 rounded-md borderbackdrop 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 sharedTooltiporInfoTip, never atitle=attribute. - Canvas bands (topology layers): rows neutral by default -
--mutedtoward--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--destructivefor the failed device,--destructivefor 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/75and Lucide icons in--muted-foreground, no box unless outlined (border-borderonbg-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 stylingfrontend/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.csswas deleted in9ba017dwhile 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,
.numnow lives insrc/styles.css, and destructive confirms usevariant="destructive". The lesson stands: if you find a class with no definition behind it, delete the markup and use a primitive. Grepstyles.cssbefore 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 - thenAdd X(the shell'saddprop, 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
DataTablemoves 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 aDataTablestill 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 Xis the copy for a create button, with no icon. Not "New X".- Filters live in the rail (
FilterRail+FacetGroup, usually viauseTableFilters), not in a second toolbar row under the header. A filter that is genuinely either/or (no "any" state) is aSegmentedTabsswitch in the action cluster instead; a single-select filter over a long fixed list can be aSelectunder 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
hideWhenSingleso 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 anEmptyStatecarrying first-run guidance (nothing exists yet) - never a bare paragraph. Loading and errors are the shell's, via itsqueryprop. - A tabbed list (Prefixes, Drift, Alerts, Compliance, Jobs) puts one h-10
SegmentedTabsstrip above the shell and renders a shell per tab, so each tab supplies its own count, search, rail, and actions. - Tables are paged by
DataTablealone. When the API pages server-side, hand itserverPagination={{ 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 slimview=tablerow (plus the catalog columns on show), and handsDataTableitsserverPagination(with Select all N across pages),serverSorting(only what the server sorts keeps a sortable header) and anexportAllthat walks every matching row. The rail isuseServerTableFilters: the same URL params and saved-view snapshot asuseUrlTableFilters, with counts from the server. A facet the server does not count (one filled from another request, like Monitoring) is left out offacets. A new big list adds aTableSpecinapi/list_specs.pyand theTableListMixinon its viewset. - A list page that fetches its rows in one capped request hands the shell the
server's answer,
page={query.data}. Whencountexceeds the rows that arrived, the count chip reads N of M in thewarningbadge, an amber notice over the table says the list is cut off,FilterRailsays its counts are partial, andDataTable's Download names the rows it holds - one context, no per-page wiring beyond the prop. - A list request without
page_sizeanswers 100 rows. A table, picker or dropdown that needs every row fetches throughapiAll(lib/api-all.ts), which walksnext1,000 rows a request up to 10,000 and hands back one page-shaped answer; anything else names itspage_size. Never callapion a list without one (#447), and never name apage_sizeabove the API's 2,000 cap: walknextinstead (#452). Keep reads at 1,000 rows or fewer; the server limits pages above 1,000 to two at a time per user, andapiqueues any such read to match and retries a429after itsRetry-After. - An embedded table on a detail page fetches one capped page (
page_size=500) rather than paging. HandDataTablethe server'stotal={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'ssearchablewith asearchPlaceholdernaming what it searches ("Search devices…"); theEmbedded*Tablehelpers have it on,searchable={false}for a list that stays short. It filters loaded rows only - withtotalset, a capped list says the search covers the first page; aserverPaginationtable needs a server search instead. Columns are matched by their text: a cell-only column reads itsmeta.exportvalue or the row field named like its id. - A list that is a view of another list (e.g.
/racks/elevations) gets the shell'sbackTo/backLabelbreadcrumb 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-inonRowHover(the row under the pointer,nullonce it leaves) andonRowClick. 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 withdata-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).SimpleTableand 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.classNamelays out the content,frameClassNamedraws the frame,viewportRefreaches 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 putsitemin the slot and rendersdialogin its body. - Several places to look an object up fold into one Show on control
(
ShowOnFloorPlanwithsiteMap,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/omitpick columns; the factory's canonical order always applies, so two pages showing the same columns cannot show them in a different order.buildPrefixColumnsalso takesorderfor the one surface that genuinely leads with a different column.selection,actions,humanIdsadd the checkbox,actionsColumn(), and the#numid column.violationsadds the compliance marker,monitoringthe roll-up status column,tagFilterwires tag chips to a page filter (omit it and the chips are static rather than falsely clickable),cfDefsadds 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 labelsvidHeader/nameHeader/heightHeader. Prefer one of these over a secondColumnDef[]; the point is that the variant is declared at the call site instead of hidden in a copied column. plainHeaders,zeroCountsandcountFacetskeep an older surface reading exactly as it did: a read-only or embedded table that never offered sorting on a column, one that prints0rather 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, androutes/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'stypeshowsdevice_type, the cable factory'sashowsa_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 }) passautoColumns={{ get }}; - a new field worth a column goes into the list serializer, with the joins
that keep
api/tests_list_queries.pyflat - 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
KvCardtables (<KvCard title rows>) in agrid 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 inSettingsCards (the PRTG Overview) puts the same rows in the card with<KvTable inset rows>andlayout="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.