Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
Style Standardization — desktop-app/ui
This document is the authoritative reference for how a page is built in desktop-app/ui after the layout/token consolidation refactor. It complements the cross-app rules in ../../../docs/agents/frontend-style-rules.md. Read the shared and renderer application rules selected by the provider adapter first; this document owns Desktop-specific visual and layout patterns.
When in doubt, mimic an existing post-refactor page (WorkflowsPage, McpServersPage, AgentsPage) before inventing.
1. Page shell
Every top-level route renders the same skeleton. The shell is className-driven — there is intentionally no <PageShell> / <PageHeader> wrapper component. Use the classes directly.
<section className="page">
<div className="page-header">
<h2>Plugins</h2>
<p className="muted">Short description, one sentence.</p>
</div>
{error && (
<section className="page-card" role="alert">
…
</section>
)}
<div className="page-layout">
<section className="page-card [page-specific-modifier]">
{/* loading | empty | content */}
</section>
</div>
</section>
Rules:
- The page-level heading is
<h2>(the<h1>is implicit from the sidebar). Subsection headings inside.page-card__headerare<h3>. - Description goes in
<p className="muted">. Keep it to one sentence. .page-layoutexists to host one or more.page-cardsiblings — it sets the gap between cards. Wrap content in it even when there is a single card so future additions don't reflow.- Loading and empty states reuse the same
<EmptyState>primitive inside a.page-card. Don't invent loading skeletons at the page level. - Errors render as their own
.page-cardwithrole="alert"above the content layout. Never overlay errors on top of cards. - Page-specific styling (e.g.
workflows-list-card,contexts-board-card) is added as a second class on.page-card, not by replacing it. Exception: when the card contains only ada-grid(no header, no toolbar), the modifier should override the page-card frame tononeso only the grid's own frame is visible — see §3 "Table frame ownership".
Tokens consumed by the shell: --space-2-5, --space-3, --radius-md, --surface-strong, --shadow-soft, --font-size-{lg,2xl,3xl}, --text, --text-muted, --edge-rgb, --accent-rgb. Do not redefine these locally.
2. Tabs
Use .page-tabs + .page-tab with the active modifier:
<div className="page-tabs">
<button className={`page-tab${tab === 'a' ? ' active' : ''}`} onClick={() => setTab('a')}>
A
</button>
<button className={`page-tab${tab === 'b' ? ' active' : ''}`} onClick={() => setTab('b')}>
B
</button>
</div>
The legacy aliases .agents-fleet-tabs, .context-tabs, .team-tabs (and their -tab element classes) share the same styles via grouped selectors. New code uses .page-tabs / .page-tab only — don't add new domain-specific tab class families.
3. DataGrid (.da-grid)
The DataGrid is the canonical pattern for any tabular listing. It is a CSS-grid-driven primitive built from BEM classes.
const RESOURCE_GRID_COLS = 'minmax(0, 1.5fr) minmax(0, 0.9fr) minmax(0, 0.85fr)'
;<div className="da-grid" style={{ '--da-grid-cols': RESOURCE_GRID_COLS }}>
<div className="da-grid__head">
<span className="da-grid__col-header">Name</span>
<span className="da-grid__col-header da-grid__col-header--center">Scope</span>
</div>
<div className="da-grid__body">
{rows.map(row => (
<button
key={row.id}
type="button"
className={`da-grid__row da-grid__row--clickable${
row.id === selectedId ? ' da-grid__row--selected' : ''
}`}
onClick={() => onSelect(row.id)}
>
<span>{row.name}</span>
<span className="da-grid__cell--center">{row.scope}</span>
</button>
))}
</div>
</div>
Available modifiers:
- Rows —
--compact(denser row height),--clickable(cursor + hover state, required when the row is a<button>),--selected(highlighted state). - Column headers and cells —
--center,--right(alignment).
Column widths are set via the CSS variable --da-grid-cols inline. This is the only acceptable static inline-style use in pages. Genuinely runtime-computed values follow the documented checker escape-hatch process in §7. Two rules apply:
- If the column template is shared across two or more pages, define it as a named constant in a shared module under
src/lib/and import it from both. Extract it only once a second page actually needs the same template. - If the template is unique to one page, leave it as a literal inline next to the JSX it describes — colocation beats premature extraction.
Never add a new tabular-listing class family in parallel to .da-grid. Extend da-grid with new modifiers if needed.
Table frame ownership
Every table/grid always owns its own frame — regardless of what surrounds it.
da-grid always renders with border: 1px solid var(--table-frame-border), border-radius: var(--table-radius), and background: var(--table-frame-bg). Never override these to none / transparent in a contextual selector. The same applies to da-table__scroll and mcp-health-section.
When a grid lives inside a page-card that also has a header or toolbar, two visual layers are intentional:
page-card ← widget/panel frame (stronger border, shadow — from page-card tokens)
└─ header/toolbar
└─ da-grid ← data frame (--table-frame-* tokens, no shadow)
This "panel containing a table" hierarchy is correct. Do not flatten it by removing either frame.
For pages where da-grid is the only content of the card (no header, no toolbar), the page-card wrapper is made frameless via its page-specific modifier so only the grid frame is visible:
/* page-card that hosts only a da-grid — grid provides the frame */
.my-list-card {
border: none;
background: transparent;
box-shadow: none;
padding: 0;
}
Existing modifiers that follow this pattern: .contexts-board-card, .workflows-list-card.
da-table__scroll is the combined frame + scroll wrapper for da-table — no separate wrapper is needed.
Column header design language
All table headers — .da-grid__head, .da-table__col-header, and any future tabular header — share the same visual language:
| Property | Token |
|---|---|
| Font size | var(--table-header-font-size) (= --font-size-xs, 11 px) |
| Font weight | var(--font-weight-bold) |
| Letter spacing | var(--letter-spacing-caps) |
| Text transform | uppercase |
| Color | var(--table-header-color) |
| Background | var(--table-header-bg) |
Never hardcode 700, 0.06em, 11px, or var(--font-size-xs) / var(--text-dim) on a header — use the semantic table tokens above. Any custom header component (e.g. McpServerHealthTable) must follow the same token set.
4. Common Controls — Use Them
Imports come from @components/Common. Treat src/components/Common/index.ts
as the supported shared boundary: pages must use exported Common primitives
instead of inventing local equivalents. The current exported set is:
| Primitive | Key API |
|---|---|
Badge |
tone: 'neutral' | 'accent' | 'success' |
Button |
variant, color, size, block, loading, align |
DataTable |
native table props, compact, fullBleed, frameless |
DataTableFilter |
options, value, onChange, variant |
DetailRow |
label, value |
DropdownSelect |
options, value, onChange, placeholder |
EmptyState |
title, body |
Field |
label, hint, htmlFor, labelClassName, wrapperClassName |
IconButton |
icon button props |
MenuItem |
menu item props |
NavItem |
navigation item props |
Pill |
pill props |
ReferenceTag |
kind, children, optional button props |
SelectInput |
dense + native <select> props (children = <option>s) |
SelectableOption |
selectable option props |
StatusBanner |
text or children, tone, leadingIcon?, compact |
TabButton |
tab button props |
TextInput |
dense + native <input> props |
ToastStack |
items: ToastMessage[] |
Do not recreate equivalents inline. If a real new common control is needed, add it under src/components/Common/<Component>/index.tsx with colocated types.ts, then re-export it from src/components/Common/index.ts — not as a one-off in a page file.
5. Where pages live
- Top-level pages:
src/pages/*.tsx(flat).AgentsPage,WorkflowsPage,McpServersPage,FilesPage,SettingsPage. - Auth/error pages with their own subtree:
src/pages/<Name>Page/index.tsx(folder-based).AuthPage,UnavailablePage. - Tests:
src/pages/__tests__/<Name>Page.test.tsx.
When adding a new page, prefer flat <Name>Page.tsx unless the page already needs adjacent files (constants, types, sub-components).
6. CSS — what to extend, what to leave alone
- Shared primitive-style classes use the
da-prefix. The page shell and tabs intentionally use the unprefixed semantic namespage,page-card, andpage-tabs; do not rename them to add a prefix. - All shared layout/component classes live in
src/styles.css. Add new shared rules at the end of the relevant section. - Tokens live in
src/styles/tokens.css. Reach for an existing token first; promote a new value only when it is used in three or more places. - Do not hardcode colors or tokenized spacing, radii, shadows, motion,
typography, z-index, or table/grid surface values. Consume the variables from
src/styles/tokens.css. - Three legacy component-level stylesheets exist and must not be extended:
src/components/ChatListPanel.css,src/components/ProgressStepper.css,src/components/ArtifactsBadge.css. They predate the refactor. When a feature touches one of these surfaces, migrate the rules intostyles.css(boy-scout) — don't add new rules to the legacy file.
Typography scale
src/styles/tokens.css is authoritative for these values:
| Token | Value | Use |
|---|---|---|
--font-size-2xs |
10px |
timestamps and micro labels |
--font-size-xs |
11px |
column headers and metadata |
--font-size-sm |
12px |
secondary body and hints |
--font-size-md |
13px |
default body and table cells |
--font-size-lg |
15px |
emphasized body and row titles |
--font-size-xl |
18px |
card and section titles |
--font-size-2xl |
22px |
page subheads |
--font-size-3xl |
28px |
page heroes |
--font-size-4xl |
36px |
auth hero only |
Font weights are --font-weight-regular, --font-weight-medium,
--font-weight-semibold, and --font-weight-bold. Line heights are
--line-height-tight for headings and --line-height-normal for body and
hints. Do not add another font-size token without an explicit design decision;
use the existing t-shirt scale directly.
7. Enforcement
A subset of the rules above is enforced automatically by a small Node
checker under scripts/style-rules/ (mirrors scripts/prettier/run-on-staged.mjs).
It runs on every commit via .githooks/pre-commit and can be invoked manually:
npm run style-rules # full repo, errors only
npm run style-rules -- --strict # treat warnings as errors (CI)
npm run style-rules:staged # what pre-commit runs
What it catches today (errors block the commit):
da-no-hex-in-css— hex literal in any CSS file outsidetokens.cssand the 3 legacy files.da-no-raw-font-size—font-size: 13px/1remoutsidetokens.css. Use one ofvar(--font-size-{2xs|xs|sm|md|lg|xl|2xl|3xl|4xl}).da-no-new-component-css— new.cssfiles undersrc/other than the 5 allowlisted ones.da-no-hover-motion— non-nonetransformorfilterdeclarations in Desktop:hoverblocks. Use background, border, text color, or shadow.
Plus two warn-level checks (listed but don't block):
da-no-hex-in-tsx— hex literal in.ts/.tsxstrings.da-no-static-inline-style— JSXstyle={{…}}not containing--da-grid-colsor a documented runtime value.
Adding a runtime-value escape hatch
da-no-static-inline-style recognizes a small whitelist of substrings that
identify legitimate runtime-driven styles (popup positioning, computed
z-index, etc.). The current list lives in INLINE_STYLE_DYNAMIC_HINTS in
scripts/style-rules/rules.mjs.
If you add a new genuinely-dynamic inline style (e.g. a new menu anchor position computed from a ref), the warning will fire. Resolve it by:
- Confirming the style truly cannot live in
src/styles.css— most cases can. Atop/leftthat depends on a computedgetBoundingClientRect()is fine inline; a staticpadding: 8pxis not. - Picking a clearly-named variable for the dynamic value (e.g.
menuAnchorPosition, notpos) and using it inside the style block. - Adding that variable name as a string entry in
INLINE_STYLE_DYNAMIC_HINTS. One line. - Mentioning the new hint in this section so future contributors don't wonder where it came from.
Currently whitelisted hints: --da-grid-cols, fleetMenuPosition,
sessionMenuPosition, zIndex: visible.length, --seg-width (data-driven
stacked-bar segment width in the context-window breakdown popover),
FlyoutPosition (portaled flyout left/top computed from
getBoundingClientRect() via useFlyoutPosition; matches the
*FlyoutPosition result variables in ComposerPanel and AgentTitleSelector).
Extending coverage
To extend rules or add coverage to control-ui / profile-ui, edit
scripts/style-rules/rules.mjs. The checker has no external dependencies
and the full rule set is ~200 lines of readable JS — see
scripts/style-rules/README.md.
Keep this document synchronized with the checker. Do not add an enforcement rule without documenting its behavior and scope here.
8. Anti-patterns to avoid
- New CSS files at component level (
.module.cssor sibling.cssto a.tsx). The three legacy ones are the exception, not a precedent. - Re-declaring page shell layout inside a page (
<div style={{ display: 'grid', gap: '...' }}>instead of.page/.page-layout). - Adding a new tab class family per domain. Use
.page-tabs/.page-tab.active. - Adding a parallel grid/table class family. Extend
.da-gridmodifiers. - Hex colors literal in TS/TSX. The one acceptable case is user-controlled dynamic state (e.g. annotation color picker initial value).
- Static inline styles other than
--da-grid-cols. Genuinely runtime-computed values must use the documented §7 escape-hatch process; other styling belongs insrc/styles.cssorsrc/styles/tokens.css. - Removing a table's own frame via contextual overrides. Never write
.some-context .da-grid { border: none; background: transparent }— every table always owns its own frame regardless of what surrounds it. See §3 "Table frame ownership".