7.4 KiB
7.4 KiB
UI Surface Map
This file maps stable UI IDs to the source files an agent should inspect before changing a surface.
Machine-readable map: docs/ui-inventory/surfaces.json.
Shell Surfaces
| UI ID | Source | Purpose |
|---|---|---|
ui.surface.shell.header |
apps/web/app/components/layouts/sidebars/shadcn/ShadcnSidebarLayout.tsx |
Authenticated shell header. |
ui.surface.shell.breadcrumb |
apps/web/app/components/layouts/sidebars/shadcn/ShadcnSidebarLayout.tsx |
Header breadcrumb container. |
ui.surface.shell.breadcrumb.current |
apps/web/app/components/layouts/sidebars/shadcn/ShadcnSidebarLayout.tsx |
Current page title. |
ui.surface.shell.navActions |
apps/web/app/components/layouts/sidebars/shadcn/nav-actions.tsx |
Header right action area. |
ui.surface.shell.main |
apps/web/app/components/layouts/sidebars/shadcn/ShadcnSidebarLayout.tsx |
Authenticated page content. |
Sidebar Surfaces
| UI ID | Source | Purpose |
|---|---|---|
ui.surface.app.sidebar |
apps/web/app/components/layouts/sidebars/shadcn/app-sidebar.tsx, apps/web/app/application/sidebar/AppSidebar.tsx |
Tenant app sidebar. |
ui.surface.admin.sidebar |
apps/web/app/components/layouts/sidebars/shadcn/app-sidebar.tsx, apps/web/app/application/sidebar/AdminSidebar.tsx |
Admin sidebar. |
ui.surface.docs.sidebar |
apps/web/app/components/layouts/sidebars/shadcn/app-sidebar.tsx, apps/web/app/application/sidebar/DocsSidebar.ts |
Docs sidebar. |
Header Actions
| UI ID | Source | Purpose |
|---|---|---|
ui.action.shell.sidebarTrigger |
ShadcnSidebarLayout.tsx, apps/web/app/components/ui/sidebar.tsx |
Open/collapse sidebar. |
ui.action.shell.search |
SubframeAppShell.tsx, nav-actions.tsx, SearchButton.tsx |
Open the desktop Spotlight search/command palette. |
ui.action.shell.searchMobile |
SubframeAppShell.tsx |
Open the viewport-filling mobile Spotlight overlay. |
ui.action.commandPalette.loadMore |
CommandPaletteDialog.tsx |
Expand tenant-search results from 20 to 50. |
ui.action.shell.aiAssistant |
nav-actions.tsx |
Open AI assistant. |
ui.action.shell.notifications |
nav-actions.tsx |
Notifications. |
ui.action.shell.onboarding |
nav-actions.tsx |
Onboarding. |
ui.action.shell.feedback |
nav-actions.tsx |
Feedback dialog. |
ui.action.shell.chatSupport |
nav-actions.tsx |
External support chat. |
ui.action.shell.more |
nav-actions.tsx |
More menu. |
ui.action.shell.profile |
ProfileButton.tsx, nav-actions.tsx |
Profile action. |
ui.action.shell.subscription |
nav-actions.tsx |
Subscription action. |
ui.action.shell.signOut |
nav-actions.tsx |
Sign out. |
Core Nav IDs
| UI ID | Source | Purpose |
|---|---|---|
ui.nav.app.dashboard |
AppSidebar.tsx |
Tenant dashboard. |
ui.nav.app.automation |
AppSidebar.tsx |
Tenant automation engine. |
ui.nav.app.crm |
AppSidebar.tsx |
Tenant CRM. |
ui.nav.app.leads |
AppSidebar.tsx |
Tenant lead inbox. |
ui.nav.app.projects |
AppSidebar.tsx |
Tenant projects and pipelines. |
ui.nav.app.forms |
AppSidebar.tsx |
Tenant forms and form-builder. |
ui.nav.app.settings |
AppSidebar.tsx |
Tenant settings. |
ui.nav.app.switchToAdmin |
AppSidebar.tsx |
Tenant-to-admin switch. |
ui.nav.admin.dashboard |
AdminSidebar.tsx |
Admin dashboard. |
ui.nav.admin.accounts |
AdminSidebar.tsx |
Accounts and users. |
ui.nav.admin.entities |
AdminSidebar.tsx |
Entity builder/runtime. |
ui.nav.admin.api |
AdminSidebar.tsx |
API key area. |
ui.nav.admin.audit |
AdminSidebar.tsx |
Audit & Events. |
ui.nav.admin.audit.viewer |
AdminSidebar.tsx |
Audit viewer. |
ui.nav.admin.audit.trails |
AdminSidebar.tsx |
Audit trails. |
ui.nav.admin.audit.events |
AdminSidebar.tsx |
Events. |
ui.nav.admin.notifications |
AdminSidebar.tsx |
Notifications. |
ui.nav.admin.featureFlags |
AdminSidebar.tsx |
Feature flags. |
ui.nav.admin.navigation |
AdminSidebar.tsx |
Navigation configuration. |
ui.nav.admin.prompts |
AdminSidebar.tsx |
Prompt builder plugin candidate. |
ui.nav.admin.emailMarketing |
AdminSidebar.tsx |
Email marketing plugin candidate. |
ui.nav.admin.platformLeads |
AdminSidebar.tsx |
Permission-gated platform lead inbox. |
ui.nav.admin.sales |
AdminSidebar.tsx |
Permission-gated daily platform sales workspace. |
ui.nav.admin.salesCommunication |
AdminSidebar.tsx |
Permission-gated email, telephony, and booking workspace group. |
ui.nav.admin.salesConfiguration |
AdminSidebar.tsx |
Permission-gated sales process and integration settings group. |
ui.nav.admin.sales.contacts |
AdminSidebar.tsx |
Tenant-less sales contact workspace. |
ui.nav.admin.sales.companies |
AdminSidebar.tsx |
Tenant-less sales company workspace. |
ui.nav.admin.sales.deals |
AdminSidebar.tsx |
Tenant-less sales deal pipeline. |
ui.nav.admin.sales.today |
AdminSidebar.tsx |
Personal tenant-less task queue for platform sales operators. |
ui.nav.admin.sales.email |
AdminSidebar.tsx |
Tenant-less sales email workspace and account settings. |
ui.nav.admin.sales.calls |
AdminSidebar.tsx |
Tenant-less sales telephony workspace and controlled dialer. |
ui.nav.admin.sales.bookings |
AdminSidebar.tsx |
Tenant-less booking workspace. |
ui.nav.admin.sales.telephonySettings |
AdminSidebar.tsx |
Aircall connection and telephony policy settings. |
ui.nav.admin.sales.leadSettings |
AdminSidebar.tsx |
Tenant-less lead assignment and scoring settings. |
ui.nav.admin.sales.pipelineSettings |
AdminSidebar.tsx |
Tenant-less pipeline and stage configuration. |
ui.nav.admin.sales.fieldsTags |
AdminSidebar.tsx |
Tenant-less sales field and tag administration. |
ui.nav.admin.sales.importExport |
AdminSidebar.tsx |
Tenant-less contact import and export workspace. |
ui.nav.admin.knowledgeBase |
AdminSidebar.tsx |
Knowledge base plugin candidate. |
ui.nav.admin.helpDesk |
AdminSidebar.tsx |
Help desk plugin candidate. |
ui.nav.admin.settings |
AdminSidebar.tsx |
Admin settings. |
ui.nav.admin.switchToApp |
AdminSidebar.tsx |
Admin-to-app switch. |
ui.nav.docs.introduction |
DocsSidebar.ts |
Docs introduction. |
Dynamic Patterns
| Pattern | Source | Notes |
|---|---|---|
ui.nav.app.entity.{entityName} |
AppSidebar.tsx |
Tenant entity nav entries. |
ui.nav.app.entityGroup.{groupSlug} |
AppSidebar.tsx |
Tenant entity group nav entries. |
ui.nav.app.entityGroup.{groupSlug}.entity.{entityName} |
AppSidebar.tsx |
Nested entity group entries. |
ui.nav.app.section.{sectionName} |
AppSidebar.tsx |
Tenant sidebar sections. |
ui.nav.docs.route.{routeSlug} |
DocsSidebar.ts |
Docs route entries. |
ui.surface.commandPalette.result.{entityType}.{entityId} |
CommandPaletteDialog.tsx |
Permission-filtered Spotlight result. |
ui.surface.commandPalette.recent.{recentId} |
CommandPaletteDialog.tsx |
Private recent-search entry. |
ui.surface.commandPalette.action.{actionId} |
CommandPaletteDialog.tsx |
Existing command-registry action shown alongside search results. |
Agent Guidance
When a prompt says "header right", "search", "sidebar", or "settings nav", resolve it to a UI ID first, then inspect the mapped source file. If no stable UI ID exists for a new surface, add it to apps/web/app/application/ui/uiRegistry.ts, render it as data-ui-id, update surfaces.json, and add a DOM test.