Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
refactor(agent-guidance): centralize frontend semantics
Josué9f6d6729b86f
diff --git a/desktop-app/ui/docs/STYLE_STANDARDIZATION.md b/desktop-app/ui/docs/STYLE_STANDARDIZATION.mdindex 8fa4675d6..3b7d8bcc0 100644--- a/desktop-app/ui/docs/STYLE_STANDARDIZATION.md+++ b/desktop-app/ui/docs/STYLE_STANDARDIZATION.md@@ -1,6 +1,6 @@# 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`](../../../docs/agents/frontend-style-rules.md) — read that first; this doc adds desktop-app-specific patterns.+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`](../../../docs/agents/frontend-style-rules.md) and the renderer application rules in [`../../../docs/agents/desktop-ui-rules.md`](../../../docs/agents/desktop-ui-rules.md). Read the shared rules first; this document owns Desktop-specific visual and layout patterns.When in doubt, mimic an existing post-refactor page (`ContextsPage`, `WorkflowsPage`, `TeamsPage`, `McpServersPage`) before inventing.@@ -92,7 +92,7 @@ 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 inline-style use in pages.** Two rules apply:+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:1. If the column template is shared across two or more pages, define it as a named constant in `src/lib/gridTemplates.ts` and import it. Existing constants: `SCOPED_RESOURCE_4COL`, `MEMBERS_3COL`.2. If the template is unique to one page, leave it as a literal inline next to the JSX it describes — colocation beats premature extraction.@@ -162,11 +162,11 @@ Imports come from `@components/Common`. The exported set is fixed:| `DetailRow` | `label`, `value` || `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.--### Feedback Placement+Button-, menu-, navigation-, and option-like UI must also reuse `IconButton`,+`TabButton`, `MenuItem`, `NavItem`, `Pill`, and `SelectableOption` from this+same export boundary rather than recreating them in a page.-Use the app toast stack for success feedback after a completed user action, such as saving settings, triggering workflows, or approving requests. Do not render inline green success banners inside page cards or forms for transient confirmations. Inline `StatusBanner` is reserved for persistent page state, warnings, errors, and informational messages that must remain visible while the user decides what to do next.+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@@ -178,10 +178,38 @@ When adding a new page, prefer flat `<Name>Page.tsx` unless the page already nee## 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 names `page`, `page-card`, and+ `page-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 into `styles.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. EnforcementA subset of the rules above is enforced automatically by a small Node@@ -243,5 +271,7 @@ and the full rule set is ~200 lines of readable JS — see- Adding a new tab class family per domain. Use `.page-tabs` / `.page-tab.active`.- Adding a parallel grid/table class family. Extend `.da-grid` modifiers.- Hex colors literal in TS/TSX. The one acceptable case is user-controlled dynamic state (e.g. annotation color picker initial value).-- Inline styles other than `--da-grid-cols`. If you find yourself reaching for one, the right move is usually a class on the global stylesheet or a new token.+- Static inline styles other than `--da-grid-cols`. Genuinely runtime-computed+ values must use the documented §7 escape-hatch process; other styling belongs+ in `src/styles.css` or `src/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".diff --git a/docs/agents/control-ui-rules.md b/docs/agents/control-ui-rules.mdnew file mode 100644index 000000000..28f483fa3--- /dev/null+++ b/docs/agents/control-ui-rules.md@@ -0,0 +1,43 @@+# Control UI coding rules++These provider-neutral rules apply only to `control-ui/**`. Combine them with+[`frontend-style-rules.md`](./frontend-style-rules.md). They do not apply to+`profile-ui`, Desktop, backend services, deployment manifests, or shared docs.++## Styling and components++- `app/globals.css` owns Control UI token declarations and shared CSS+ classes/layout. Consume colors, spacing, radii, shadows, motion, and z-index+ through its CSS variables instead of hardcoding tokenized values.+- Use the `cu-` prefix for shared utility classes.+- Reusable components live under `components/` in folders with `index.tsx` and+ colocated support such as `types.ts`.+- Reuse the primitives exported by `components/ui/index.tsx`: `Button`,+ `Field`, `TextInput`, `SelectInput`, `TextAreaInput`, `CheckboxField`, and+ `FormSection`.++## Routing++- Sidebar destinations and shareable tab-like sections use canonical Next App+ Router paths and child route segments. Do not use `?tab=...`, `profileTab`,+ `localStorage`, or component-only state as the section-routing source.+- Query parameters remain valid for transient actions, form modes, filters,+ search, and external callback state; they are not primary section navigation.+- Import internal destinations and dynamic/query builders from+ `app/constants/routes.ts`. Never inline Control UI paths in links, redirects,+ router actions, form actions, sidebar items, or tabs. Pass raw dynamic+ identifiers to the route builder.++## Page patterns++- Use `TablePanelHeader` and `TableHeaderRow` for route tables and sections.+- Keep the section icon, title, subtitle, search, refresh, and CTAs visible+ while initial loading, empty, and error states render in the content area.+ Disable header CTAs during initial loading, and let only the content pane+ scroll when rows overflow.+- Use `CreatePageHeader` plus `cu-create-panel`, `cu-create-content`, and+ `cu-create-actions` for full-screen create/install pages. Use `<h2>` for the+ create-page heading.+- Wrap auth-gated pages in `<AuthGate>`.+- Reserve `cu-modal-panel` for overlay/dialog contexts. Modal panel headings use+ `<h3>`; table panel labels are not headings.diff --git a/docs/agents/desktop-ui-rules.md b/docs/agents/desktop-ui-rules.mdnew file mode 100644index 000000000..c631b69b8--- /dev/null+++ b/docs/agents/desktop-ui-rules.md@@ -0,0 +1,38 @@+# Desktop renderer coding rules++These provider-neutral rules apply only to `desktop-app/ui/**`. Combine them+with [`frontend-style-rules.md`](./frontend-style-rules.md) and+[`../../desktop-app/ui/docs/STYLE_STANDARDIZATION.md`](../../desktop-app/ui/docs/STYLE_STANDARDIZATION.md).++They do not apply to `desktop-app/**` outside `ui/**`. Electron main-process,+preload, IPC, and shared scripts follow the repository-wide TypeScript/Node and+Desktop security guidance, not renderer styling or page-layout rules.++## Navigation++- Import top-level and nested in-memory destinations from+ `src/constants/navigation.ts`.+- Never inline Desktop route IDs in navigation handlers, comparisons, sidebar+ definitions, or view switches. Keep `NavItem` derived from the centralized+ navigation contract.++## Server state++- Every new top-level data section that reads server data uses TanStack Query+ as its server-state source of truth.+- Add a dedicated `use<Section>DataController()` or equivalently scoped query+ hook. Keep exported/reusable types in separate files and expose `loading`,+ `error`, required data, and `refresh()`.+- Consume query hooks directly where needed. Do not wrap `App` in section data+ providers or re-expose query state through React context; reserve contexts+ for client UI state and cross-cutting actions.+- Initial loads run once after successful authentication. Section navigation+ reads the current query/cache state, and manual refreshes refresh only that+ section unless the app-level refresh flow explicitly coordinates several+ sections.++## Visual and component architecture++`desktop-app/ui/docs/STYLE_STANDARDIZATION.md` is authoritative for renderer+tokens, shared CSS ownership, Common controls, page placement, page shells,+tabs, DataGrid, feedback surfaces, and style-rule enforcement.diff --git a/docs/agents/frontend-style-rules.md b/docs/agents/frontend-style-rules.mdindex 48afb6070..e87608c3a 100644--- a/docs/agents/frontend-style-rules.md+++ b/docs/agents/frontend-style-rules.md@@ -1,201 +1,91 @@-# Frontend style rules (control-ui, desktop-app/ui, profile-ui)+# Shared frontend rules-These rules apply only when editing files under `control-ui/**`, `desktop-app/ui/**`, and `profile-ui/**`.+These provider-neutral rules apply only to:-## Scope+- `control-ui/**`+- `profile-ui/**`+- `desktop-app/ui/**`-- Preserve the established interaction behavior first.-- Keep disabled, loading, hover, focus, validation, and empty states working before simplifying styles.-- Favor consolidation when two variants are effectively the same, but do not flatten intentionally different behavior.+They do not apply to `desktop-app/**` outside `ui/**` or to other repository+services. Combine them with the provider-neutral guidance for the application+being changed:-## Rules+- [`control-ui-rules.md`](./control-ui-rules.md)+- [`profile-ui-rules.md`](./profile-ui-rules.md)+- [`desktop-ui-rules.md`](./desktop-ui-rules.md)-1. Types in dedicated files+## Preserve behavior-- Do not declare exported or reusable `type` / `interface` definitions inside component implementation files.-- Keep reusable component and page types in a sibling `types.ts` file, or `*.types.ts` when the local structure needs it.-- Implementation files must import those types instead of redefining them inline.+- Preserve established interaction behavior before simplifying structure or+ styling.+- Keep disabled, loading, hover, focus, validation, error, and empty states+ working.+- Consolidate variants that are semantically equivalent, but do not flatten+ intentional application differences.-2. Color tokens via project-global CSS variables+## Types, constants, and imports-- Do not hardcode color values in component styles.-- Each project defines shared color tokens in its global stylesheet:- - `control-ui` → `app/globals.css`- - `desktop-app/ui` → `src/styles/tokens.css`- - `profile-ui` → `app/globals.css`-- Consume colors through `var(--token-name)` in components and shared styles.--3. Spacing, size, and motion tokens first--- Prefer existing CSS variables for spacing, radii, font sizes, shadows, and transitions.-- When no existing token fits, add a new scoped variable in the closest relevant stylesheet.-- Only promote a token to the global stylesheet when it is clearly shared across multiple modules.-- Use project-defined spacing scales (e.g., `--cu-space-*` in control-ui/profile-ui) instead of raw rem values.--**Typography scale** — currently defined in `desktop-app/ui/src/styles/tokens.css` and consumed throughout desktop-app's page shell, tabs, and primitives. control-ui/profile-ui will adopt the same scale when their typography is consolidated; until then, follow the inline values already in their stylesheets.--The authoritative values live in `tokens.css`; the table below mirrors them and must be kept in sync.--Body sizes:--- `--font-size-2xs` (10px) — micro: timestamps, dot-labels-- `--font-size-xs` (11px) — column headers, metadata-- `--font-size-sm` (12px) — secondary body, hints-- `--font-size-md` (13px, default) — default body, table cells-- `--font-size-lg` (15px) — emphasized body, row title-- `--font-size-xl` (18px) — card title, section title--Heading sizes:--- `--font-size-2xl` (22px) — page subhead-- `--font-size-3xl` (28px) — page hero-- `--font-size-4xl` (36px) — auth hero only--Font weights — `--font-weight-regular` (400), `--font-weight-medium` (500), `--font-weight-semibold` (600), `--font-weight-bold` (700).--Line heights — `--line-height-tight` (1.2, headings), `--line-height-normal` (1.45, body and hints).--Do not introduce new font-size tokens outside the scale. If a design needs a value not in the scale, raise it before adding a new token — the scale is intentionally narrow to prevent drift. There are no `h1..h4` or `display` aliases; use the t-shirt sizes above directly.--4. Prefer import aliases--- Prefer project aliases over deep relative imports whenever an alias exists.-- Typical aliases are `@/*`, `@components/*`, `@constants/*`, `@hooks/*`, `@lib/*`, `@pages/*`, and `@types/*`.--5. Constants in dedicated files--- Do not keep reusable configuration constants inside component or page implementation files.-- Store shared constants in the project constants area:- - `control-ui/app/constants`- - `desktop-app/ui/src/constants`- - `profile-ui/app/constants`+- Do not declare exported or reusable `type` or `interface` definitions inside+ component implementation files. Put them in a sibling `types.ts` or+ `*.types.ts` file and import them.+- Keep reusable configuration constants in the application's constants area.+ Local rendered copy used by only one component may remain in that component.- Keep each constants file scoped to one module, page, or domain.-- Exception: local rendered copy that belongs to only one component can stay in the implementation file.--6. Prefer folder-based components--- Reusable components and route-section components should live in a folder named after the component.-- Use `index.tsx` as the entry file and keep related files beside it, such as `types.ts`, `constants.ts`, and local styles.-- Avoid flat `ComponentName.tsx` files for components that already have related files or are likely to gain them.--7. Use single-purpose components--- Prefer small, purpose-built UI primitives instead of repeating native form controls inline.-- Forms should compose common building blocks such as field wrappers, text inputs, textareas, select controls, checkboxes, and buttons.-- Button styles should collapse into explicit variants such as `primary`, `secondary`, `ghost`, or `danger` when behavior is equivalent.-- If two styles differ only by tiny cosmetic drift, choose one shared version instead of preserving both.-- Keep the primitive API narrow and behavior-oriented; do not build one oversized component that hides unrelated concerns.-- Desktop app controls must compose the shared controls in `desktop-app/ui/src/components/Common`- (`Button`, `IconButton`, `TabButton`, `MenuItem`, `NavItem`, `Pill`, and `SelectableOption`) before adding local button/tab/menu markup.-- Interactive hover states must not move or scale controls. Do not add hover `transform`, `translate`, `top`, `margin`, or `filter` effects to buttons, tabs, menu items, pills, cards used as options, or navigation items. Use background, border, text color, and shadow tokens instead.--8. CSS class before inline style, always--- Never write `style={{ color: 'var(--cu-danger)' }}`. Use `.cu-field__error`, `.cu-text-danger`, or add a named class to the global stylesheet.-- The only exception is truly dynamic values (e.g., a progress bar width from JS state, or data-driven trust-chip colors).-- Inline styles on tables/columns break CSS override via media queries — use CSS classes for width and alignment.--9. One file owns shared styling per project--- All spacing, color, and layout primitives live in the project's global stylesheet:- - `control-ui` → `app/globals.css`- - `desktop-app/ui` → `src/styles/tokens.css`- - `profile-ui` → `app/globals.css`-- Never create a `.module.css` or component-level stylesheet for anything shared.-- If a class doesn't exist yet, add it to the project's global stylesheet with the project's prefix (e.g., `cu-` for control-ui/profile-ui).--10. No duplicated utilities--- If you need `toKebabCase`, `joinClasses`/`cn`, or any string helper, look in the project's `lib/` first.-- If it's not there, create it once in the appropriate lib file (e.g., `lib/string.ts`, `lib/cn.ts`).-- Never define a helper function inline in a component file.--11. Page shell consistency--Each project has a page shell pattern that every page must follow. Don't invent new wrappers, don't use modal classes on full-screen pages, don't re-declare layout inside a page.--**control-ui / profile-ui** — full-screen create/install pages:--- Auth/load handling → wrapper component (e.g., `<AuthGate>`).-- Page header → consistent icon/title/subtitle/back button layout (e.g., `<CreatePageHeader>`).-- Content panel → shared panel class with max-width, shadow, padding.-- Form grid → shared grid layout for fields.-- Action buttons → Cancel (ghost) + Submit (primary) footer pattern.--**desktop-app/ui** — every top-level page:--- Outer `<section className="page">` containing a `.page-header` (`<h2>` + `<p className="muted">`) and a `.page-layout` with one or more `.page-card`s.-- Loading and empty states are `<EmptyState>` rendered inside a `.page-card`. No page-level skeletons.-- Errors are their own `.page-card` with `role="alert"` above the layout.-- Tabs use `.page-tabs` + `.page-tab.active`.-- Tabular listings use `.da-grid` with column widths driven by the inline CSS variable `--da-grid-cols` (constants in `src/lib/gridTemplates.ts`). This is the only acceptable inline-style use.-- Full pattern documented in `desktop-app/ui/docs/STYLE_STANDARDIZATION.md`.--12. Semantic heading levels--- Create page headers should use `<h2>` since the page-level heading is implicit from nav/sidebar context.-- Table panel headers use `<span>` (not headings). Modal panel heads use `<h3>`.-- Avoid multiple `<h1>` tags per page — hurts accessibility and SEO.--13. key props must be stable--- Never use array index as a React key for lists that can be reordered or have items removed.-- Use a stable ID (UUID at creation, or a natural unique value from data).--14. Accessibility: focus-visible on all interactive elements--- All non-input interactive elements (buttons, links, sidebar items, tabs) must have `:focus-visible` styles.-- Use `:focus-visible` (not `:focus`) to avoid showing outlines on mouse clicks.-- Focus rings should use the project's focus color token with appropriate offset.--15. Project-specific component patterns--Each project has established patterns for common UI surfaces:--**control-ui / profile-ui** (cu- prefix):--- Route section navigation must use canonical Next App Router paths and child- route segments. Sidebar destinations and shareable tab-like sections must not- use `?tab=...`, ad hoc query keys such as `profileTab`, `localStorage`, or- component-only state as their routing source. The first/default tab may use- the parent route; other tabs should use child routes such as- `/hosts/[name]/env`, `/profile-admin/users`, or `/settings/social/telegram`.- Query params are reserved for transient actions, form modes, filters, search,- or external callback state, not primary section navigation.-- `TablePanelHeader` + `TableHeaderRow` for every route table/section-- Control UI route sections keep the header visible with icon, title, subtitle, search, refresh, and CTAs; initial loading belongs in the content area only, header CTAs are disabled during that initial load, and only the content pane scrolls when rows overflow.-- `CreatePageHeader` for every create/install page-- `cu-create-panel`, `cu-create-content`, `cu-create-actions` for create page shells-- `cu-modal-panel` reserved for overlay/dialog contexts only-- Transient success feedback for completed user actions must use the app toast/notification stack, not inline green success banners inside page cards or forms. Use inline status banners only for persistent page state, warnings, errors, or informational messages that should remain visible.--**desktop-app/ui** (`da-` prefix for shared primitives, unprefixed semantic names for shell):--- Page shell — `.page` / `.page-header` / `.page-layout` / `.page-card` / `.page-card__header`. See rule #11.-- Tabs — `.page-tabs` / `.page-tab` (with `.active`). Legacy aliases (`agents-fleet-tabs`, `context-tabs`, `team-tabs`) share styles via grouped selectors; new code uses `.page-tabs` only.-- Controls — use `Button`, `IconButton`, `TabButton`, `MenuItem`, `NavItem`, `Pill`, and `SelectableOption` from `@components/Common`. Variant/style decisions belong in the component props (`variant`, `color`, `size`, `block`, `loading`, `align`) plus semantic class names for layout only.-- DataGrid — `.da-grid` with BEM elements (`__head`, `__col-header`, `__body`, `__row`, `__cell`) and modifiers (`--clickable`, `--selected`, `--compact`, `--center`, `--right`). Column widths via `--da-grid-cols` inline; shared templates in `src/lib/gridTemplates.ts`.-- Transient success feedback for completed user actions must use the app toast stack, not inline green success banners inside page cards or forms. Use inline status banners only for persistent page state, warnings, errors, or informational messages that should remain visible.-- Pages live in `src/pages/` — flat `<Name>Page.tsx` for top-level, folder-based `<Name>Page/index.tsx` only for auth/error pages.-- Three legacy component CSS files (`ChatListPanel.css`, `ProgressStepper.css`, `ArtifactsBadge.css`) exist but **must not be extended** — migrate rules into `styles.css` opportunistically.-- Full pattern reference: `desktop-app/ui/docs/STYLE_STANDARDIZATION.md`.--## 16. Automated enforcement (style-rules)--A repo-local checker at `scripts/style-rules/` runs on `pre-commit` and enforces a-subset of the rules above. Currently scoped to `desktop-app/ui/**`. It blocks commits on:--- Hex literals in CSS outside `tokens.css` and the 3 legacy files.-- Raw `font-size` values (must use `var(--font-size-*)`).-- New component-level `.css` files outside the 5-file allowlist.-- Hover `transform` / `filter` effects in desktop CSS. Hover states can change- background, border, text color, and shadow, but must not move, scale, or- brightness-filter controls.--It also surfaces warnings (non-blocking) for hex literals in TS/TSX strings and JSX-inline `style={{…}}` other than `--da-grid-cols`. Manual run: `npm run style-rules`-(add `-- --strict` to fail on warnings, e.g. for CI).--Extend coverage to control-ui / profile-ui by broadening the rule predicates in-`scripts/style-rules/rules.mjs` once their patterns consolidate. Don't add rules-without a corresponding entry in this doc — undocumented rules cause drift, not prevent it.+- Prefer project aliases over deep relative imports when an alias exists.++## Tokens and shared CSS ownership++- Do not hardcode colors in component styles. Consume project tokens through+ `var(--token-name)`.+- Prefer existing tokens for spacing, radii, font sizes, shadows, and motion.+ Add a scoped token only when no existing token fits; promote it to the+ application's token file only when it is shared.+- Put token declarations and shared CSS classes/layout in the files below.+ Token files declare values; shared-style files own reusable selectors.++| Application | Token declarations | Shared CSS classes and layout |+| ---------------- | ----------------------- | ----------------------------- |+| `control-ui` | `app/globals.css` | `app/globals.css` |+| `profile-ui` | `app/globals.css` | `app/globals.css` |+| `desktop-app/ui` | `src/styles/tokens.css` | `src/styles.css` |++- Do not create a CSS module or component-level stylesheet for shared styles.+- Prefer a named CSS class over inline style. Inline style is reserved for+ values that are genuinely computed at runtime; an application's narrower+ guidance may restrict this further.++## Components and controls++- Prefer small, single-purpose primitives over repeated native form controls.+ Compose field wrappers, text inputs, textareas, selects, checkboxes, and+ variant-driven buttons from the target application's established primitives.+- Keep primitive APIs narrow and behavior-oriented. Consolidate cosmetic-only+ variants rather than building an oversized component.+- Reusable components and route-section components should use the target+ application's established folder convention. Keep related `types.ts`,+ `constants.ts`, and other support files beside the component.+- Interactive hover states must not move, scale, translate, reposition, or+ brightness-filter controls. Use background, border, text color, and shadow+ tokens instead of `transform`, `translate`, `top`, `margin`, or `filter`.++## Utilities++- Search the target application's `lib/` before adding string helpers such as+ `toKebabCase`, `joinClasses`, or `cn`.+- Create a missing reusable helper once in the appropriate library file. Do not+ define reusable utilities inline in a component.++## Feedback and accessibility++- Use the application's toast/notification stack for transient success after a+ completed action. Inline status banners are for persistent page state,+ warnings, errors, or information that must remain visible while the user+ acts.+- Use stable React keys for lists that can reorder or remove items. Never use+ an array index for those lists.+- Give every non-input interactive element a token-based `:focus-visible`+ treatment. Use `:focus-visible`, not `:focus`, so mouse clicks do not show a+ keyboard focus ring.+- Maintain a meaningful heading hierarchy and avoid multiple `<h1>` elements+ on one page. Follow the application's canonical page and modal heading+ levels.diff --git a/docs/agents/profile-ui-rules.md b/docs/agents/profile-ui-rules.mdnew file mode 100644index 000000000..7b85353e1--- /dev/null+++ b/docs/agents/profile-ui-rules.md@@ -0,0 +1,38 @@+# Profile UI coding rules++These provider-neutral rules apply only to `profile-ui/**`. Combine them with+[`frontend-style-rules.md`](./frontend-style-rules.md). They do not apply to+`control-ui`, Desktop, backend services, deployment manifests, or shared docs.++## Styling and components++- `app/globals.css` owns Profile UI token declarations and shared CSS+ classes/layout. Consume colors, spacing, radii, shadows, motion, and z-index+ through its CSS variables instead of hardcoding tokenized values.+- Continue using the `cu-` prefix shared with Control UI.+- Components and primitives remain colocated under `app/components/` in+ folders with `index.tsx` and colocated support such as `types.ts`. Do not+ migrate Profile UI to Control UI's `components/ui/` structure.+- Reuse Profile UI's existing primitives, including `Button`, `TextInput`,+ `SelectControl`, `FormField`, and `EditableList`.++## Routing++- Sidebar destinations and shareable tab-like sections use canonical Next App+ Router paths and child route segments. Do not use `?tab=...`, `profileTab`,+ `localStorage`, or component-only state as the section-routing source.+- Query parameters remain valid for transient actions, form modes, filters,+ search, and external callback state; they are not primary section navigation.+- Import internal destinations and dynamic/query builders from+ `app/constants/routes.ts`. Never inline Profile UI paths in links, redirects,+ router actions, sidebar items, or tabs. Pass raw dynamic identifiers to the+ route builder.++## Page patterns++- Use Profile UI's existing `AuthGate`, `CreatePageHeader`, create-panel,+ form-grid, and action-footer patterns for authenticated create/install flows.+- Full-screen create/install headings use `<h2>`. Modal panel headings use+ `<h3>`; table or panel labels are not headings.+- Reserve `cu-modal-panel` for overlay/dialog contexts rather than full-screen+ pages.