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. |
| 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. |
| UI ID |
Source |
Purpose |
ui.action.shell.sidebarTrigger |
ShadcnSidebarLayout.tsx, apps/web/app/components/ui/sidebar.tsx |
Open/collapse sidebar. |
ui.action.shell.search |
nav-actions.tsx, SearchButton.tsx |
Open command palette/search. |
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.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.analytics |
AdminSidebar.tsx |
Analytics. |
ui.nav.admin.entities |
AdminSidebar.tsx |
Entity builder/runtime. |
ui.nav.admin.workflows |
AdminSidebar.tsx |
Workflow plugin candidate. |
ui.nav.admin.api |
AdminSidebar.tsx |
API key area. |
ui.nav.admin.events |
AdminSidebar.tsx |
Events. |
ui.nav.admin.auditTrails |
AdminSidebar.tsx |
Audit trails. |
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.portals |
AdminSidebar.tsx |
Portals plugin candidate. |
ui.nav.admin.prompts |
AdminSidebar.tsx |
Prompt builder plugin candidate. |
ui.nav.admin.emailMarketing |
AdminSidebar.tsx |
Email marketing plugin candidate. |
ui.nav.admin.knowledgeBase |
AdminSidebar.tsx |
Knowledge base plugin candidate. |
ui.nav.admin.helpDesk |
AdminSidebar.tsx |
Help desk plugin candidate. |
ui.nav.admin.onboarding |
AdminSidebar.tsx |
Onboarding. |
ui.nav.admin.metrics |
AdminSidebar.tsx |
Metrics. |
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. |
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.
