Phoenix Frontend

Phoenix Frontend Development

Composable rules for building UI in the Phoenix app. Before starting work, explore app/src/components/ and app/package.json to understand existing patterns, packages, and conventions — then follow these rules.

Rule Files

Read the relevant file(s) based on the task:

Verification

After visual changes, use agent-browser to verify the UI looks correct. When modifying a shared component, check its usages across the app.

URL State

Significant view state must be recreatable from the URL. If a user can select a tab, sub-view, or detail state that should survive reloads, sharing, or adjacent-record pagination, encode it in route params or search params and preserve the relevant URL state during navigation.

Accessibility

Semantic elements

• Interactive actions MUST use buttons, not clickable divs
• Lists MUST use <ul>/<ol>

WCAG 2.1 AA baseline

WCAG 2.1 AA MUST be followed: 4.5:1 contrast for text, keyboard operability, visible focus indicators, labeled form inputs.

Component Patterns

Core vs. domain split

Explore app/src/components/ to understand the two layers:

• Core (components/core/) — presentational primitives. MUST NOT contain data fetching or business logic.
• Domain (everything else) — data-rich, composed from core primitives.

New features MUST compose from existing core primitives before creating new low-level UI.

Layout

Existing flex and view layout primitives SHOULD be used for consistent spacing and alignment. Explore components/core/ for what's available before writing ad-hoc layout wrappers.

Storybook

New core components MUST include minimal Storybook stories showing primary variants and states. Explore app/stories/ for the existing convention.

File convention

Explore a few existing components to match the established file structure (component, styles, types, barrel export).

Memoization

React Compiler is enabled — do NOT use useMemo, useCallback, or React.memo. The compiler handles memoization automatically. This includes callback props passed to children; define them inline without wrapping in useCallback.

Refs

React 19 treats ref as a regular prop — do NOT use forwardRef. Instead, accept ref directly in the props type and destructure it like any other prop. Add ref?: Ref<ElementType> to the props interface.

Callback props

Name callback props after the event (onProjectCreated, onDismiss), not the parent's implementation (refetchProjects). The callsite should read as plain English.

// Good
<NewProjectButton onProjectCreated={() => refetchProjects()} />

// Avoid
<NewProjectButton refetchProjects={() => refetchProjects()} />

Avoid useEffect

Prefer declarative React and React Aria patterns over imperative useEffect. Reach for useEffect only when there is no declarative alternative.

Overlays: Drawer vs. Modal

Phoenix has two overlay components with different purposes. Choosing the wrong one breaks the interaction model.

Drawer (components/core/overlay/Drawer.tsx)

A non-modal right-side panel. Use for list-detail flows where the user selects a row and inspects its details while keeping the list visible and interactive behind it.

• Does NOT render a backdrop — clicks pass through to the page behind it
• Resizable via drag handle; width persists to localStorage as a viewport percentage
• Dismissed with Escape or the collapse arrow button
• Route-driven: opening a drawer means navigating to a nested route (e.g., /sessions/:sessionId)
• The corresponding table row MUST be highlighted with data-selected so the user always knows which item they are viewing

Use Drawer when: the user needs to glance at details and return to the list without losing context (traces, spans, sessions).

Modal (components/core/overlay/Modal.tsx)

A modal overlay that demands focus. Comes in two variants:

• variant="default" — centered dialog with backdrop. Use for confirmations, forms, and focused workflows that require the user's full attention.
• variant="slideover" — full-height right-side panel with backdrop. Use when the content needs more space than a centered dialog but still requires modal focus (e.g., a complex creation form that shouldn't compete with the page behind it).

Both variants block interaction with the page behind them via ModalOverlay.

Decision guide

UX: list-detail pattern

Tables that open a detail view on row click MUST follow the layered list-detail pattern:

1. Row click navigates to a nested route (e.g., /traces/:traceId). The detail view renders via <Outlet /> alongside the table. 2. Selected row is highlighted by setting data-selected={isSelected} on the <tr>, where isSelected compares row.original.id against the URL param (via useParams). The existing selectableTableCSS styles tr[data-selected="true"] automatically. 3. Drawer opens with the detail content. The table remains visible and scrollable behind it. 4. Closing the drawer navigates back to the parent route, clearing the selection.

This pattern keeps the user oriented — they always see which row they selected and can click a different row to switch without closing first.

Shared constants

Shared literals (validation regexes, fixed string sets, etc.) belong in app/src/constants/ as focused modules re-exported from index.ts. Import via @phoenix/constants. Do not export them from component or form files.

Data Fetching

Relay store and cache retention

Declarative Relay hooks (usePreloadedQuery, useLazyLoadQuery) retain their query and fetched data in the Relay store cache for as long as the component using the hook is mounted. This makes them safe for hydrating data that is rendered on a page.

fetchQuery does not have this retention guarantee. Data fetched via fetchQuery can be evicted from the Relay store after enough subsequent requests (e.g., requests triggered by pagination). This means using fetchQuery to hydrate data that is rendered on a page is dangerous — the data may silently disappear from the store while the component is still mounted.

Query refs returned by loadQuery are retained until they are disposed. Use useQueryLoader when the component owns loading. When a route loader or other external owner returns a loadQuery ref directly to a component, that component must dispose the ref when it stops owning it.

Owned preloaded queries

Phoenix provides app/src/hooks/useOwnedPreloadedQuery.ts for the common route-loader pattern:

• Loader uses loadQuery(...) and returns a query ref.
• Component reads the ref with useOwnedPreloadedQuery(...).
• The hook hands the ref to useQueryLoader, so Relay disposes it on replacement or unmount.

Use this hook only when the current component owns the lifecycle of an externally created query ref, such as useLoaderData() returning a loadQuery result.

Do not use this hook when:

• the query ref is already managed by useQueryLoader
• the ref is shared and another component owns disposal
• the ref is passed through context or props for multiple readers without clear single-owner semantics

Rules

• Prefer declarative hooks. Use hooks such as usePreloadedQuery or useLazyLoadQuery to fetch data that will be rendered on a page.
• Avoid `fetchQuery` for page-rendered data. Do not use fetchQuery to hydrate data that a mounted component depends on for rendering.
• Limited safe uses of `fetchQuery`. fetchQuery is acceptable when the result is consumed immediately and not held in the store for rendering, such as fetching data for a redirect or a one-shot action.
• Prefer `useQueryLoader` for component-owned query refs. It handles retaining and disposal for refs the component loads itself.
• Use `useOwnedPreloadedQuery` for loader-owned query refs. If a route loader returns a loadQuery ref that this component owns directly, read it with useOwnedPreloadedQuery instead of usePreloadedQuery.
• Treat disposal as an ownership decision. Only the owner should dispose a query ref. Disposing a shared ref too early can make still-mounted readers hit missing-data or GC-related crashes later.

Resize SVG Logo Assets

Add provider or integration logo SVGs to the Phoenix frontend. Accepts raw SVGs, deterministically rescales them, converts to JSX, and inserts into the appropriate TSX file.

Targets

If the user does not specify a target, ask before proceeding.

Workflow

Step 1 — Collect SVGs

Accept input as:

• A single SVG file path
• A list of SVG file paths
• A directory containing .svg files
• Raw SVG markup pasted in the conversation (write to a temp file first)

Step 2 — Resize with the deterministic script

Use the helper script at .agents/skills/phoenix-frontend/scripts/scale-svg.py.

Single file:

uvx --with svgpathtools python .agents/skills/phoenix-frontend/scripts/scale-svg.py <target_size> <input.svg> <output.svg>

Batch (directory):

uvx --with svgpathtools python .agents/skills/phoenix-frontend/scripts/scale-svg.py --batch <target_size> <input_dir> <output_dir>

Target sizes:

• provider → 24
• integration → 32

Step 3 — Convert SVG to JSX

After resizing, read each output SVG and convert to a JSX component. Apply these attribute transformations:

Also:

• Remove the xmlns attribute from the root <svg> element (React adds it automatically).
• Self-close elements with no children (e.g., <path ... />).
• Keep the viewBox attribute as-is (it is already camelCase).

Step 4 — Apply color rules

• If the logo is exclusively one dark color (black, near-black, dark gray), replace the fill with currentColor so it follows Phoenix theme in light/dark mode.
• If the logo has explicit brand colors (multicolor), preserve them.

Step 5 — Insert into TSX file

Before adding to the file, confirm that the logos do not conflict with any existing entries. If there are similar logos already in place, list them and ask for confirmation before overwriting.

Provider icons (GenerativeProviderIcon.tsx)

1. Add the SVG as a private component following this pattern:

const NewProviderSVG = ({ height }: { height: number }) => (
  <svg
    viewBox="0 0 24 24"
    width={height}
    height={height}
    xmlns="http://www.w3.org/2000/svg"
  >
    {/* scaled paths here */}
  </svg>
);

2. Add an entry to the PROVIDER_ICONS record:

NEW_PROVIDER: NewProviderSVG,

Note: The key must match a value in the ModelProvider type. If the provider doesn't exist in the type yet, flag this to the user — the type may need updating upstream.

Integration icons (IntegrationIcons.tsx)

Add as a named export following this pattern:

export const NewIntegrationSVG = () => (
  <svg
    width="32"
    height="32"
    viewBox="0 0 32 32"
    fill="none"
    xmlns="http://www.w3.org/2000/svg"
  >
    {/* scaled paths here */}
  </svg>
);

Step 6 — Derive component name from filename

When the SVG filename follows the icon=Name.svg convention, derive the component name as NameSVG. For example:

• icon=LlamaIndex.svg → LlamaIndexSVG
• icon=Cerebras.svg → CerebrasSVG
• icon=LiveKit Agents.svg → LiveKitAgentsSVG

Strip the icon= prefix, remove spaces, and append SVG.

Step 7 — Verify

• Read the modified TSX file to confirm the new component compiles with

surrounding code.

• If the user provides a list of expected icon names, confirm each was added.

Workflow efficiency

• Work file-by-file, not in bulk. Scale an SVG, read the output, edit the

TSX — then move to the next. Do not dump all SVG contents into context or agent prompts as a batch.

• Don't marshal file contents through conversation. The scaled files are on

disk — read them directly when needed instead of buffering them into a message.

• Replace whole components when updating. If an existing SVG component needs

replacing, delete the old one entirely and write the new one fresh. Don't try to patch parts of it.

Safety

• Never hand-edit SVG path data. All coordinate changes must go through the

scale script.

• Never guess or approximate path geometry.
• If the scale script fails on a particular SVG, report the error to the user

rather than attempting a manual fix.

• Do not modify existing icons in the file unless explicitly asked.