Phoenix Frontend

---
name: phoenix-frontend
description: Frontend development guidelines for the Phoenix AI observability platform. Use when writing, reviewing, or modifying React components, TypeScript code, styles, or UI features in the js/app/ directory. Triggers on any frontend task — new components, UI changes, styling, accessibility fixes, form handling, or component refactoring. Also use when the user asks about frontend conventions or component patterns for this project. For design system rules (error display, layout, dialogs, tokens), use the phoenix-design skill.
metadata:
  internal: true
---

# Phoenix Frontend Development

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

## Reference Files

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

| Reference | When to read |
|-----------|-------------|
| `references/components.md` | Creating, composing, or refactoring components |
| `references/relay.md` | Using Relay |
| `references/accessibility.md` | Any interactive element, form, overlay, or semantic markup |
| `references/test-ids.md` | Adding or changing `data-testid` attributes for E2E tests |
| `references/resize-svg-logo-assets.md` | Adding or updating provider/integration logo icons |

## Storybook

For any change to `js/app/stories/` or `js/app/.storybook/` — including stories that accompany a component change — use the `phoenix-storybook` skill.

## PXI data changes

When a PXI write changes the membership or filters of a mounted Relay query, use `useAgentDataChangeFetchKey` from `@phoenix/hooks` in the query owner. See `references/relay.md` for the event and fetch policy convention.

## Verification

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

## Route Metadata

When adding, removing, renaming, or materially changing what a page contains, update the route's `handle.agentRoute` metadata in `js/app/src/Routes.tsx` if an assistant agent should be able to link users to that destination. Keep metadata small and search-oriented:

- `label`: human page name.
- `description`: concise page purpose based on what the page now contains, including user phrases PXI might hear when looking for that page.

If a content change makes an existing route easier or harder to find by natural language, adjust `description` in the same change.

## 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.