Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(mobile): reserve top chrome in CRM and detail views (#8395)

Peter Chinman99cbdbf8b98f
diff --git a/.agents/rules/web/mobile.md b/.agents/rules/web/mobile.md
index 59dc0a55d7..4ee5b49053 100644
--- a/.agents/rules/web/mobile.md
+++ b/.agents/rules/web/mobile.md
@@ -67,9 +67,13 @@ read their code, and follow that pattern rather than inventing a new one.
## Layout and chrome
-- Content scrolls under the floating chrome: pad the scroller with
- `mobile:pt-(--mobile-content-inset-top)` and
- `mobile:pb-(--mobile-content-inset-bottom)`, never a spacer.
+- Reserve `--mobile-content-inset-top` (safe area plus any floating split
+ header) with `touch:` on every full-frame view, including loading/error states
+ and record tabs; phone width alone and `--safe-top` alone do not cover tablets
+ or floating navigation. Use `ViewShell.Header` for collection controls; when
+ an in-flow header consumes the inset, reset it to `0px` on its content subtree
+ so nested lists/editors do not reserve it again. Otherwise pad the scroller
+ with the top and bottom content insets so content scrolls under the chrome.
- Safe areas come from the `--safe-*` CSS variables (e.g.
`bottom-[var(--safe-bottom,0px)]`); `getSafeAreaInset` only when JS needs
the number. Never measure insets yourself.
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index 31b3da4330..289ee4cdd0 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -95,6 +95,7 @@ ownership. Cancel, logout, and the ten-minute timeout retire pending callbacks.
- Virtualize mobile name results like desktop Command Menu; local Quick Access sources are unbounded, and mounting them all stalls iOS keyboard focus during layout. Load additional search pages near the scroll end instead of reserving a paging bar.
- Reconcile mobile full-text rows by entity ID so appending a page preserves DOM rows and scroll position; restore after responsive row measurement and disable browser scroll anchoring so layout changes cannot override the saved history offset.
- Reserve only the safe-area inset above mobile Search and Channels; their hidden split headers must not leave a blank strip or extend the top fade.
+- Follow [mobile layout and chrome](../../.agents/rules/web/mobile.md#layout-and-chrome) for full-frame views and record tabs; verify their first controls below the navigation with a nonzero safe area on phones and tablets.
- Show only the Recent conversation feed in mobile Channels, without view tabs or a persisted mobile tab selection.
- Mount the mobile search input before focusing it inside the dock tap; keep navigation in that handler so focus does not trigger a second navigation or lose iOS keyboard activation.
- Preserve focused chrome editors during deferred split insertion/removal autofocus; explicit return-focus commands may still focus the pane.
diff --git a/apps/web/src/components/entity-detail/EntityDetailTopBar.tsx b/apps/web/src/components/entity-detail/EntityDetailTopBar.tsx
index 43bdeb2165..2ca688f581 100644
--- a/apps/web/src/components/entity-detail/EntityDetailTopBar.tsx
+++ b/apps/web/src/components/entity-detail/EntityDetailTopBar.tsx
@@ -9,7 +9,12 @@ export function EntityDetailTopBar(
props: ParentProps<{ navigation?: JSX.Element; titleMenu?: JSX.Element }>
) {
return (
- <ViewShell.TopBar class={cn('touch:flex', props.navigation && 'gap-3')}>
+ <ViewShell.TopBar
+ class={cn(
+ 'touch:flex touch:h-auto touch:min-h-12 touch:pt-[calc(var(--mobile-content-inset-top,var(--safe-top,0px))+0.75rem)]',
+ props.navigation && 'gap-3'
+ )}
+ >
<ViewBreadcrumbs.Outlet
aria-label="Task location"
fallback={<EntityDetailBreadcrumbSkeleton />}
diff --git a/apps/web/src/components/view-shell/ViewShell.tsx b/apps/web/src/components/view-shell/ViewShell.tsx
index 18b56441d6..e94e8c8bbe 100644
--- a/apps/web/src/components/view-shell/ViewShell.tsx
+++ b/apps/web/src/components/view-shell/ViewShell.tsx
@@ -686,7 +686,7 @@ function Header(props: JSX.HTMLAttributes<HTMLElement>) {
<header
{...rest}
class={cn(
- 'shrink-0 px-4 py-4 touch:px-(--mobile-chrome-gutter) touch:pt-[calc(var(--safe-top,0px)+0.5rem)]',
+ 'shrink-0 px-4 py-4 touch:px-(--mobile-chrome-gutter) touch:pt-[calc(var(--mobile-content-inset-top,var(--safe-top,0px))+0.5rem)]',
local.class
)}
data-view-shell-header=""
diff --git a/apps/web/src/features/crm/browser-test/mobile-insets.browser.e2e.ts b/apps/web/src/features/crm/browser-test/mobile-insets.browser.e2e.ts
new file mode 100644
index 0000000000..6b4da9ef66
--- /dev/null
+++ b/apps/web/src/features/crm/browser-test/mobile-insets.browser.e2e.ts
@@ -0,0 +1,98 @@
+import { expect, test } from '@playwright/test';
+
+for (const device of [
+ { name: 'phone', width: 390, height: 844, hasTouch: true },
+ { name: 'tablet', width: 1024, height: 768, hasTouch: true },
+ { name: 'desktop', width: 1280, height: 800, hasTouch: false },
+]) {
+ test.describe(device.name, () => {
+ // A cold Vite server compiles the production shell's shared dependencies.
+ test.setTimeout(180_000);
+ test.use({
+ viewport: { width: device.width, height: device.height },
+ hasTouch: device.hasTouch,
+ });
+ test.beforeEach(async ({ page }) => {
+ await page.routeWebSocket('**', (socket) => socket.close());
+ await page.route('https://**', (route) => route.abort());
+ await page.route('**/__macro_dev/**', (route) => route.abort());
+ });
+
+ for (const surface of ['company', 'contact', 'crm', 'reviews', 'project']) {
+ test(`${surface} clears navigation without double insets`, async ({
+ page,
+ }, testInfo) => {
+ await page.goto(
+ `/src/features/crm/browser-test/mobile-insets.html?surface=${surface}`,
+ { waitUntil: 'domcontentloaded' }
+ );
+ if (surface === 'company' || surface === 'contact') {
+ const heading = page.getByRole('heading');
+ await expect(heading).toBeVisible({ timeout: 30000 });
+ const box = await heading.boundingBox();
+ expect(box?.y).toBe(device.hasTouch ? 116 : 48);
+ await page.screenshot({
+ path: testInfo.outputPath('overview-top.png'),
+ });
+ if (device.hasTouch) {
+ await page
+ .getByRole('button', { name: 'Files', exact: true })
+ .click();
+ const search = page.getByRole('searchbox', {
+ name: 'Search files',
+ });
+ await expect(search).toBeVisible();
+ const searchBox = await search.boundingBox();
+ expect(searchBox!.y).toBeGreaterThanOrEqual(100);
+ expect(searchBox!.y).toBeLessThan(112);
+ await search.fill('proposal');
+ await expect(page.getByText('Searching: proposal')).toBeVisible();
+ await page
+ .getByRole('button', { name: 'Overview', exact: true })
+ .click();
+ await expect(heading).toBeVisible({ timeout: 30000 });
+ }
+ const last = page.getByRole('button', { name: 'Last action' });
+ await last.evaluate((element) => {
+ const scroller = element.closest('.overflow-y-auto');
+ if (scroller) scroller.scrollTop = scroller.scrollHeight;
+ });
+ await expect(last).toBeVisible();
+ const lastBox = await last.boundingBox();
+ expect(lastBox!.y + lastBox!.height).toBeLessThanOrEqual(
+ device.height - (device.hasTouch ? 128 : 48)
+ );
+ } else if (surface === 'project') {
+ const button = page.getByRole('button', { name: 'Project tasks' });
+ await expect(button).toBeVisible();
+ const box = await button.boundingBox();
+ expect(box!.y).toBeGreaterThanOrEqual(device.hasTouch ? 59 : 0);
+ expect(box!.y).toBeLessThan(device.hasTouch ? 64 : 20);
+ await button.click();
+ await expect(page.getByText('Selected: tasks')).toBeVisible();
+ } else {
+ const button = page.getByRole('button', {
+ name: 'People',
+ exact: true,
+ });
+ await expect(button).toBeVisible();
+ const box = await button.boundingBox();
+ const top = device.hasTouch ? (surface === 'reviews' ? 100 : 55) : 16;
+ expect(box!.y).toBeGreaterThanOrEqual(top);
+ expect(box!.y).toBeLessThan(top + 5);
+ await button.click();
+ await expect(page.getByText('Selected: people')).toBeVisible();
+ await page
+ .getByRole('button', { name: 'Sales', exact: true })
+ .click();
+ await expect(
+ page.getByText('Selected: pipeline:sales')
+ ).toBeVisible();
+ }
+ await page.screenshot({
+ path: testInfo.outputPath(`${surface}-${device.name}.png`),
+ });
+ });
+ }
+ });
+}
diff --git a/apps/web/src/features/crm/browser-test/mobile-insets.html b/apps/web/src/features/crm/browser-test/mobile-insets.html
new file mode 100644
index 0000000000..36600aa011
--- /dev/null
+++ b/apps/web/src/features/crm/browser-test/mobile-insets.html
@@ -0,0 +1,5 @@
+<!doctype html>
+<html>
+ <head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>Mobile content insets</title></head>
+ <body><div id="root"></div><script type="module" src="./mobile-insets.tsx"></script></body>
+</html>
diff --git a/apps/web/src/features/crm/browser-test/mobile-insets.tsx b/apps/web/src/features/crm/browser-test/mobile-insets.tsx
new file mode 100644
index 0000000000..0d7b2b5859
--- /dev/null
+++ b/apps/web/src/features/crm/browser-test/mobile-insets.tsx
@@ -0,0 +1,103 @@
+import '@app/index.css';
+import { EntityDetailTopBar } from '@app/components/entity-detail/EntityDetailTopBar';
+import { ViewBreadcrumbs, ViewShell } from '@app/components/view-shell';
+import { SidePanel } from '@components/app/side-panel';
+import { isTouchDevice } from '@core/mobile/isTouchDevice';
+import { Button } from '@ui';
+import { createSignal, For, Match, Switch } from 'solid-js';
+import { render } from 'solid-js/web';
+import { CrmMobileTabs } from '../components/crm-mobile-tabs';
+import { RecordOverview } from '../components/record-overview';
+import { RecordSection } from '../components/record-section';
+
+// Production layout components with local content; no account or backend writes.
+const params = new URLSearchParams(location.search);
+const surface = params.get('surface') ?? 'company';
+const safeTop = Number(params.get('safe') ?? 47);
+const headerHeight = ['company', 'contact', 'reviews'].includes(surface)
+ ? 45
+ : 0;
+document.documentElement.dataset.touchDevice = String(isTouchDevice());
+
+function Fixture() {
+ const [tab, setTab] = createSignal('active');
+ const [search, setSearch] = createSignal('');
+ const [section, setSection] = createSignal('overview');
+ return (
+ <main
+ class="relative flex h-dvh flex-col bg-panel text-ink"
+ style={{
+ '--safe-top': `${safeTop}px`,
+ '--mobile-content-inset-top': `${safeTop + headerHeight}px`,
+ '--mobile-content-inset-bottom': '80px',
+ }}
+ >
+ <Switch>
+ <Match when={surface === 'crm' || surface === 'reviews'}>
+ <ViewShell.Header>
+ <CrmMobileTabs
+ active={tab()}
+ pipelines={[{ id: 'sales', name: 'Sales' }]}
+ lists={[]}
+ onNavigate={setTab}
+ />
+ </ViewShell.Header>
+ <div class="min-h-0 flex-1 overflow-auto touch:[--mobile-content-inset-top:0px]">
+ <p>Selected: {tab()}</p>
+ </div>
+ </Match>
+ <Match when={surface === 'project'}>
+ <SidePanel.Root defaultOpen={false}>
+ <ViewBreadcrumbs.Root value="project" onChange={() => {}}>
+ <EntityDetailTopBar
+ navigation={
+ <Button onClick={() => setSection('tasks')}>
+ Project tasks
+ </Button>
+ }
+ />
+ </ViewBreadcrumbs.Root>
+ </SidePanel.Root>
+ <p>Selected: {section()}</p>
+ </Match>
+ <Match when={surface === 'company' || surface === 'contact'}>
+ <nav
+ aria-label="Record navigation"
+ class="absolute inset-x-0 top-0 z-10 flex gap-2 bg-panel touch:top-(--safe-top) touch:h-11.25 not-touch:hidden"
+ >
+ <Button onClick={() => setSection('overview')}>Overview</Button>
+ <Button onClick={() => setSection('files')}>Files</Button>
+ </nav>
+ <Switch>
+ <Match when={section() === 'overview'}>
+ <RecordOverview>
+ <h1>
+ {surface === 'company' ? 'Acme company' : 'Maya contact'}
+ </h1>
+ <For each={Array.from({ length: 35 }, (_, i) => i)}>
+ {(index) => <p>Discussion item {index}</p>}
+ </For>
+ <Button>Last action</Button>
+ </RecordOverview>
+ </Match>
+ <Match when={section() === 'files'}>
+ <RecordSection
+ title="Files"
+ search={search()}
+ onSearchChange={setSearch}
+ >
+ <p>{search() ? `Searching: ${search()}` : 'No files yet.'}</p>
+ </RecordSection>
+ </Match>
+ </Switch>
+ </Match>
+ </Switch>
+ <div
+ aria-hidden="true"
+ class="pointer-events-none absolute inset-x-0 top-0 bg-panel/80 touch:h-(--safe-top)"
+ />
+ </main>
+ );
+}
+const root = document.getElementById('root');
+if (root) render(() => <Fixture />, root);
diff --git a/apps/web/src/features/crm/components/record-overview.tsx b/apps/web/src/features/crm/components/record-overview.tsx
new file mode 100644
index 0000000000..54cc6f63bd
--- /dev/null
+++ b/apps/web/src/features/crm/components/record-overview.tsx
@@ -0,0 +1,12 @@
+import type { ParentProps } from 'solid-js';
+
+/** Full-frame record content scrolls beneath the floating split chrome. */
+export function RecordOverview(props: ParentProps) {
+ return (
+ <div class="h-full overflow-y-auto px-6 pb-12 pt-12 scrollbar-hidden touch:pt-[calc(var(--mobile-content-inset-top,0px)+1.5rem)] touch:pb-[calc(var(--mobile-content-inset-bottom,0px)+3rem)]">
+ <div class="mx-auto flex max-w-3xl min-w-0 flex-col gap-6">
+ {props.children}
+ </div>
+ </div>
+ );
+}
diff --git a/apps/web/src/features/crm/components/record-section.tsx b/apps/web/src/features/crm/components/record-section.tsx
index 1bfef9d68b..6676fe33a3 100644
--- a/apps/web/src/features/crm/components/record-section.tsx
+++ b/apps/web/src/features/crm/components/record-section.tsx
@@ -18,7 +18,7 @@ export function RecordSection(
aria-label={props.title}
class="@container/record flex size-full min-h-0 flex-col"
>
- <div class="flex min-h-12 min-w-0 shrink-0 flex-wrap items-center gap-3 px-4 py-2">
+ <div class="flex min-h-12 min-w-0 shrink-0 flex-wrap items-center gap-3 px-4 py-2 touch:pt-[calc(var(--mobile-content-inset-top,0px)+0.5rem)]">
<SearchBar
size="sm"
label={`Search ${props.title.toLowerCase()}`}
@@ -36,7 +36,7 @@ export function RecordSection(
</div>
</Show>
</div>
- <div class="min-h-0 flex-1 overflow-y-auto px-2 pb-6">
+ <div class="min-h-0 flex-1 overflow-y-auto px-2 pb-6 touch:pb-[calc(var(--mobile-content-inset-bottom,0px)+1.5rem)] touch:[--mobile-content-inset-top:0px]">
{props.children}
</div>
</section>
diff --git a/apps/web/src/features/crm/views/company-detail.tsx b/apps/web/src/features/crm/views/company-detail.tsx
index ca83e7870f..6d4a748b86 100644
--- a/apps/web/src/features/crm/views/company-detail.tsx
+++ b/apps/web/src/features/crm/views/company-detail.tsx
@@ -2,6 +2,7 @@ import { SidePanel } from '@components/app/side-panel';
import PlusIcon from '@phosphor/plus.svg';
import { Button } from '@ui';
import { createMemo, Match, Show, Suspense, Switch } from 'solid-js';
+import { RecordOverview } from '../components/record-overview';
import { useCrmContext } from '../context/crm-context';
import type { CrmContact as CompanyContact } from '../core/contact';
import {
@@ -68,18 +69,16 @@ export function Company(props: {
<div class="min-h-0 min-w-0 flex-1">
<Switch>
<Match when={section() === 'overview'}>
- <div class="h-full overflow-y-auto px-6 pb-12 pt-12 scrollbar-hidden touch:pt-6">
- <div class="mx-auto flex max-w-3xl min-w-0 flex-col gap-6">
- <CompanyHeader company={company()} />
- <Show when={pipelinesEnabled()}>
- <context.PipelineEntries
- record={{ type: 'company', id: props.companyId }}
- onOpenPipeline={props.onOpenPipeline}
- />
- </Show>
- <CompanyDiscussionSection companyId={props.companyId} />
- </div>
- </div>
+ <RecordOverview>
+ <CompanyHeader company={company()} />
+ <Show when={pipelinesEnabled()}>
+ <context.PipelineEntries
+ record={{ type: 'company', id: props.companyId }}
+ onOpenPipeline={props.onOpenPipeline}
+ />
+ </Show>
+ <CompanyDiscussionSection companyId={props.companyId} />
+ </RecordOverview>
</Match>
<Match when={section() === 'team'}>
<CompanyContactsSection
@@ -116,7 +115,7 @@ export function Company(props: {
<Match when={section() === 'tasks'}>
<Suspense
fallback={
- <div class="p-6 text-center text-sm text-ink-muted">
+ <div class="p-6 text-center text-sm text-ink-muted touch:pt-[calc(var(--mobile-content-inset-top,0px)+1.5rem)]">
Loading…
</div>
}
@@ -124,7 +123,7 @@ export function Company(props: {
<Show
when={scope()}
fallback={
- <div class="p-6 text-center text-sm text-ink-muted">
+ <div class="p-6 text-center text-sm text-ink-muted touch:pt-[calc(var(--mobile-content-inset-top,0px)+1.5rem)]">
Loading…
</div>
}
diff --git a/apps/web/src/features/crm/views/contact-detail.tsx b/apps/web/src/features/crm/views/contact-detail.tsx
index 72c4b46926..2f95aee0fb 100644
--- a/apps/web/src/features/crm/views/contact-detail.tsx
+++ b/apps/web/src/features/crm/views/contact-detail.tsx
@@ -1,5 +1,6 @@
import { SidePanel } from '@components/app/side-panel';
import { createMemo, Match, Show, Suspense, Switch } from 'solid-js';
+import { RecordOverview } from '../components/record-overview';
import { useCrmContext } from '../context/crm-context';
import {
type ContactSection,
@@ -61,21 +62,19 @@ export function Contact(props: {
<div class="min-h-0 min-w-0 flex-1">
<Switch>
<Match when={section() === 'overview'}>
- <div class="h-full overflow-y-auto px-6 pb-12 pt-12 scrollbar-hidden touch:pt-6">
- <div class="mx-auto flex max-w-3xl min-w-0 flex-col gap-6">
- <ContactHeader
- contact={contact()}
- onOpenCompany={props.onOpenCompany}
+ <RecordOverview>
+ <ContactHeader
+ contact={contact()}
+ onOpenCompany={props.onOpenCompany}
+ />
+ <Show when={pipelinesEnabled()}>
+ <context.PipelineEntries
+ record={{ type: 'contact', id: props.contactId }}
+ onOpenPipeline={props.onOpenPipeline}
/>
- <Show when={pipelinesEnabled()}>
- <context.PipelineEntries
- record={{ type: 'contact', id: props.contactId }}
- onOpenPipeline={props.onOpenPipeline}
- />
- </Show>
- <ContactDiscussionSection contactId={props.contactId} />
- </div>
- </div>
+ </Show>
+ <ContactDiscussionSection contactId={props.contactId} />
+ </RecordOverview>
</Match>
<Match when={section() === 'emails'}>
<ContactEmailsSection contact={contact()} />
@@ -86,7 +85,7 @@ export function Contact(props: {
<Match when={section() === 'tasks'}>
<Suspense
fallback={
- <div class="p-6 text-center text-sm text-ink-muted">
+ <div class="p-6 text-center text-sm text-ink-muted touch:pt-[calc(var(--mobile-content-inset-top,0px)+1.5rem)]">
Loading…
</div>
}
@@ -94,7 +93,7 @@ export function Contact(props: {
<Show
when={scope()}
fallback={
- <div class="p-6 text-center text-sm text-ink-muted">
+ <div class="p-6 text-center text-sm text-ink-muted touch:pt-[calc(var(--mobile-content-inset-top,0px)+1.5rem)]">
Loading…
</div>
}
diff --git a/apps/web/src/features/crm/views/record-detail.tsx b/apps/web/src/features/crm/views/record-detail.tsx
index de484570f3..e358f53f10 100644
--- a/apps/web/src/features/crm/views/record-detail.tsx
+++ b/apps/web/src/features/crm/views/record-detail.tsx
@@ -168,7 +168,7 @@ export function CrmRecordDetail(props: {
tabindex={-1}
class="flex size-full min-h-0 min-w-0 flex-col overflow-hidden outline-none"
>
- <div class="flex h-12 min-w-0 shrink-0 items-center gap-3 border-b border-edge-muted px-4">
+ <div class="flex h-12 min-w-0 shrink-0 items-center gap-3 border-b border-edge-muted px-4 touch:h-auto touch:min-h-12 touch:pt-[calc(var(--mobile-content-inset-top,var(--safe-top,0px))+0.5rem)] touch:pb-2">
{props.navigation}
<ViewBreadcrumbs.Outlet
aria-label="CRM record location"
@@ -197,7 +197,7 @@ export function CrmRecordDetail(props: {
<SidePanel.Toggle />
</div>
</div>
- <div class="relative min-h-0 min-w-0 flex-1">
+ <div class="relative min-h-0 min-w-0 flex-1 touch:[--mobile-content-inset-top:0px]">
<Show when={current()} keyed>
{(record) => (
<RecordContent
diff --git a/apps/web/src/features/projects/project-detail.tsx b/apps/web/src/features/projects/project-detail.tsx
index b655fb1554..8f10404894 100644
--- a/apps/web/src/features/projects/project-detail.tsx
+++ b/apps/web/src/features/projects/project-detail.tsx
@@ -280,7 +280,7 @@ function ProjectDetailHost(props: ProjectDetailProps) {
)}
</Show>
</EntityDetailTopBar>
- <div class="relative min-h-0 min-w-0 flex-1">
+ <div class="relative min-h-0 min-w-0 flex-1 touch:[--mobile-content-inset-top:0px]">
<Suspense
fallback={<ProjectContentSkeleton section={props.route.section} />}
>
diff --git a/docs/agent-guide/crm.md b/docs/agent-guide/crm.md
index fff0783edd..cb5a719ba6 100644
--- a/docs/agent-guide/crm.md
+++ b/docs/agent-guide/crm.md
@@ -54,6 +54,20 @@ the full-frame list with the global **+ Company** action above the dock. People
strip. The embedded detail stack stays out of the mobile flow, so selecting a
row navigates in place.
+Verify touch spacing with a nonzero top safe area (for example 47px): the CRM
+tab strip clears the status bar, while standalone company/contact Overview and
+Team, Emails, Files, Tasks, and Calls clear both the status bar and floating
+record navigation. Switch tabs and check the first title/search control is
+visible and tappable. Scroll to the end to check content clears the dock. Repeat
+at tablet width; desktop retains its usual spacing. An embedded record header
+consumes the top inset once, so its content must not add it again.
+
+The account-free browser layout regression is
+`bunx playwright test --config src/features/crm/browser-test/playwright.config.ts mobile-insets.browser.e2e.ts`
+from `apps/web`. It mounts the production layout components with local content
+at phone, tablet, and desktop sizes; authenticated route and native-device
+checks remain separate.
+
On desktop, clicking a company or a person in the list (or pressing Enter on a
focused row) opens its details inside the CRM workspace, keeping the left
navigation visible. Each record has its own URL: `/app/companies/company/<uuid>`
diff --git a/docs/agent-guide/media/mobile-insets/contact-phone.png b/docs/agent-guide/media/mobile-insets/contact-phone.png
new file mode 100644
index 0000000000..8ecaff62af
Binary files /dev/null and b/docs/agent-guide/media/mobile-insets/contact-phone.png differ
diff --git a/docs/agent-guide/media/mobile-insets/crm-phone.png b/docs/agent-guide/media/mobile-insets/crm-phone.png
new file mode 100644
index 0000000000..5a8bfcbb6a
Binary files /dev/null and b/docs/agent-guide/media/mobile-insets/crm-phone.png differ
diff --git a/docs/agent-guide/ui-conventions.md b/docs/agent-guide/ui-conventions.md
index 52a0e0a848..fd49f828c8 100644
--- a/docs/agent-guide/ui-conventions.md
+++ b/docs/agent-guide/ui-conventions.md
@@ -9,6 +9,13 @@ keeps loaded items visible. Wait for real rows before navigating or selecting.
## Top bars
+On touch devices, check top bars with a nonzero safe area as well as at phone
+and tablet widths. Collection headers clear the pane's full top content inset:
+safe area only in composable CRM/Tasks/Drive, plus the floating split header in
+Reviews. Native project detail navigation also clears the safe area, with its
+content directly below it. Content nested below an in-flow header must not add
+the same inset again. See the [mobile layout rule](../../.agents/rules/web/mobile.md#layout-and-chrome).
+
Low-emphasis right-aligned split-header actions (including Calendar's touch/preview
New event and Channel's idle Call and Ask Macro) are borderless with a rounded-xl
background on hover. Emphasized variants retain their treatment, including an