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