fix(ui): chrome convergence — restore section title + surface backgrounds + homogeneous gutter (#4188)

* fix(admin): layout — PageHeader + CoreSurfaceTabBar siblings, router-view outside container

* fix(admin): users.view — re-add v-container+v-row pa-2 mt-0+v-col chrome

* fix(admin): organizations.view — re-add v-container+v-row+v-col chrome

* fix(admin): readiness.view — re-add v-container+v-row+v-col around v-card

* fix(admin): activity.view — re-add v-container+v-row+v-col chrome

* fix(admin): user.view — re-add v-container+v-row+v-col chrome around form card

* fix(users): profile.view — wrap content in v-row+v-col+v-card surface (homogeneous chrome)

* fix(users): organizations.view — wrap content in v-row+v-col+v-card surface

* docs(migrations): document chrome convergence convention + downstream guidance

Author: PierreBrisorgueil

MIGRATIONS.md

@@ -4,6 +4,158 @@ Breaking changes and upgrade notes for downstream projects.
 
 ---
 
+## Account / Organization / Admin chrome convergence (2026-05-21)
+
+**Non-breaking for default consumers.** Builds on #4183 (`corePageTabs`), #4184 (org tabs), #4185 (Account chrome), and #4187 (Admin chrome + `coreConfirmDialog` + `coreAvatarUploader`). Locks in one chrome convention across all "section + tab bar + routed children" layouts.
+
+### The convention
+
+Layouts (Account, Organization detail, Admin) use the same shape:
+
+```vue
+<template>
+  <v-container fluid>
+    <PageHeader icon="fa-solid fa-X" title="Section">
+      <template #actions v-if="...">...</template>
+    </PageHeader>
+    <CoreSurfaceTabBar :tabs="..." :can="..." :base-path="..." />
+  </v-container>
+  <router-view />
+</template>
+```
+
+- `PageHeader` and `CoreSurfaceTabBar` are **siblings inside the container** — NEVER pass tabs via PageHeader's `#tabs` slot. That slot replaces the icon+title row and is reserved for future cases that intentionally suppress the title (none in this codebase today).
+- `<router-view />` is **outside** the layout's `<v-container fluid>` — children supply their own gutter.
+
+Routed children wrap their primary content like this:
+
+```vue
+<template>
+  <v-container fluid>
+    <v-row class="pa-2 mt-0">
+      <v-col cols="12">
+        <v-card color="surface" :flat="config.vuetify.theme.flat" :class="config.vuetify.theme.rounded" class="pa-6">
+          <!-- primary content -->
+        </v-card>
+        <!-- optional sibling cards (e.g. danger zone) -->
+      </v-col>
+    </v-row>
+    <coreConfirmDialog ... />
+  </v-container>
+</template>
+```
+
+The `<v-card color="surface">` provides the visible pane background. Content that already provides its own surface (e.g. `coreDataTableComponent`) skips the wrap card to avoid double-surface — wrap the data table directly in `<v-col cols="12">` without an inner `<v-card>`.
+
+### Detail-page breadcrumb (admin only)
+
+Admin sub-views that drill into a single record publish a breadcrumb to the layout instead of carrying their own header:
+
+```javascript
+import { useAdminStore } from '../stores/admin.store';
+// ...
+watch: {
+  user: { immediate: true, handler(u) { this.publishBreadcrumb(u); } },
+},
+beforeUnmount() { useAdminStore().clearBreadcrumb(); },
+methods: {
+  publishBreadcrumb(u) {
+    if (!u || (!u.firstName && !u.lastName && !u.email)) return;
+    const title = [u.firstName, u.lastName].filter(Boolean).join(' ') || u.email;
+    useAdminStore().setBreadcrumb({ title, titleClass: 'text-capitalize' });
+  },
+},
+```
+
+In breadcrumb mode the layout hides `<CoreSurfaceTabBar>` (user is "drilled in") and renders `Section › <title>` via `<PageHeader>`'s `#breadcrumb` slot.
+
+### Shared destructive-confirm dialog
+
+`<coreConfirmDialog>` (from `src/modules/core/components/core.confirmDialog.component.vue`) replaces inline `<v-dialog>` blocks for destructive actions:
+
+```vue
+<coreConfirmDialog
+  v-model="confirmDelete"
+  title="Delete X"
+  :confirm-text="confirmTarget"
+  confirm-label="Delete"
+  confirm-color="error"
+  @confirm="remove"
+>
+  <!-- optional default slot for rich body content -->
+</coreConfirmDialog>
+```
+
+Supports a simple yes/no (no `confirm-text`) OR a typed-gate (`confirm-text="DELETE"` or `:confirm-text="orgName"` — confirm button stays disabled until the user types the exact string).
+
+### Avatar uploader
+
+`<coreAvatarUploader>` (`src/modules/core/components/core.avatarUploader.component.vue`) replaces hand-rolled `position-absolute` camera-button overlays:
+
+```vue
+<coreAvatarUploader :user="user" :size="200" @uploaded="$emit('avatar-uploaded')" />
+```
+
+Posts to `/users/avatar` by default; `endpoint` and `field` props let it serve other upload contracts (logos, banners) without forking.
+
+### Action for downstream projects
+
+**Default consumers (no admin extras, no custom account chrome):** no action required. The convention is applied uniformly inside devkit.
+
+**Projects with `config.admin.tabs` extras:** no structural change — extras are merged with the canonical `BUILT_IN_TABS` (Users, Organizations, Readiness, Activity) and passed through `CoreSurfaceTabBar`, which handles validation + CASL filtering via `resolveSurfaceTabs`. Existing tab descriptors (`{ value, label, icon, route, action?, subject? }`) work as-is.
+
+**Projects with module-specific tabs under a page title** (e.g. trawl_vue's `/developers`, `/scraps`, custom dashboards): you can now adopt the homogeneous `PageHeader + CoreSurfaceTabBar` sibling pattern instead of the legacy `<v-card><v-tabs><v-window>` in-card pattern. Migration is opt-in — the legacy pattern still works, but the new pattern integrates visually with Account / Organization / Admin and gets CASL gating for free.
+
+Before:
+
+```vue
+<v-container fluid>
+  <PageHeader icon="fa-solid fa-code" title="Developers" />
+  <v-row class="pa-2 mt-0">
+    <v-col cols="12">
+      <v-card color="surface">
+        <v-tabs v-model="tab">
+          <v-tab value="keys">...</v-tab>
+          <v-tab value="webhooks">...</v-tab>
+        </v-tabs>
+        <v-divider />
+        <v-window v-model="tab">
+          <v-window-item value="keys"><developersKeysTab :keys="..." /></v-window-item>
+          <v-window-item value="webhooks"><developersWebhooksTab :webhooks="..." /></v-window-item>
+        </v-window>
+      </v-card>
+    </v-col>
+  </v-row>
+</v-container>
+```
+
+After (route-driven, homogeneous with Account / Org / Admin):
+
+```vue
+<!-- developers.layout.vue -->
+<template>
+  <v-container fluid>
+    <PageHeader icon="fa-solid fa-code" title="Developers" />
+    <CoreSurfaceTabBar
+      :tabs="config.developers.tabs"
+      :can="developersCan"
+      :base-path="basePath"
+    />
+  </v-container>
+  <router-view />
+</template>
+```
+
+Plus `config.developers.tabs = [{ value: 'keys', label: 'API Keys', icon: 'fa-solid fa-key', route: 'keys' }, { value: 'webhooks', label: 'Webhooks', icon: 'fa-solid fa-globe', route: 'webhooks' }]`, then split the keys / webhooks tabs into routed children (`developers.keys.view.vue`, `developers.webhooks.view.vue`) each wrapping its content per the child-view shape above. Dialogs (`showCreateKeyDialog`, `showPlainKeyDialog`, etc.) move into the child views that own them.
+
+This migration is **opt-in per module** — coordinate with the maintainer of each module before applying.
+
+### Why
+
+`/admin/users`, `/users/profile`, `/users/organizations` looked visually disconnected from `/developers`, `/tasks` after #4187 (no surface background on routed panes, no section title on admin, ad-hoc padding). Locking in one convention makes every "section + tabs + content" layout in the app visually identical and lets downstream projects opt their own modules in cheaply.
+
+---
+
 ## Legal module + cookie consent banner (2026-05-07)
 
 **Non-breaking for default consumers.** New `modules/legal/` ships:

src/modules/admin/tests/admin.activity.view.unit.tests.js

@@ -187,11 +187,13 @@ import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
 
 describe('admin.activity.view — template chrome', () => {
-  it('does NOT wrap its template in <v-container> (admin layout owns chrome)', () => {
+  it('wraps its template in <v-container fluid> + <v-row class="pa-2 mt-0"> + <v-col cols="12">', () => {
     const here = dirname(fileURLToPath(import.meta.url));
     const sfc = readFileSync(resolve(here, '../views/admin.activity.view.vue'), 'utf8');
     const tmpl = sfc.split('<script>')[0];
-    expect(tmpl).not.toMatch(/<v-container/);
+    expect(tmpl).toMatch(/<v-container\s+fluid/);
+    expect(tmpl).toMatch(/<v-row[^>]*class="[^"]*pa-2\s+mt-0/);
+    expect(tmpl).toMatch(/<v-col\s+cols="12"/);
   });
 
   it('has zero inline style="…" attributes in its template', () => {

src/modules/admin/tests/admin.layout.unit.tests.js

@@ -45,8 +45,10 @@ const mountLayout = (configOverrides = {}, routePath = '/admin/users') =>
         RouterLink: true,
         RouterView: { template: '<div class="router-view-stub" />' },
         PageHeader: {
+          name: 'PageHeader',
+          props: ['title', 'icon'],
           template: `
-            <div class="page-header-stub">
+            <div class="page-header-stub" :data-title="title" :data-icon="icon">
               <slot name="avatar" />
               <slot name="breadcrumb" />
               <slot name="tabs" />
@@ -150,28 +152,58 @@ describe('admin.layout', () => {
     expect(wrapper.html()).not.toContain('No mailer configured');
   });
 
-  it('renders a single .admin-content wrapper around <router-view>', () => {
+  it('renders <CoreSurfaceTabBar> as a SIBLING of <PageHeader> (not inside its #tabs slot)', () => {
     const wrapper = mountLayout();
-    expect(wrapper.findAll('.admin-content').length).toBe(1);
-    expect(wrapper.find('.admin-content .router-view-stub').exists()).toBe(true);
+    const pageHeaderEl = wrapper.find('.page-header-stub');
+    const surfaceTabBarEl = wrapper.find('.surface-tab-bar-stub');
+    expect(pageHeaderEl.exists()).toBe(true);
+    expect(surfaceTabBarEl.exists()).toBe(true);
+    // Sibling layout: the tab-bar element is NOT inside the page-header-stub element.
+    expect(pageHeaderEl.element.contains(surfaceTabBarEl.element)).toBe(false);
   });
 
-  it('renders the breadcrumb when useAdminStore().currentBreadcrumb is set', async () => {
-    adminStoreState.currentBreadcrumb = { title: 'Jane Doe', titleClass: 'text-capitalize' };
+  it('renders <router-view> OUTSIDE the layout <v-container>', () => {
+    const wrapper = mountLayout();
+    const layoutContainer = wrapper.find('.v-container');
+    const routerViewEl = wrapper.find('.router-view-stub');
+    expect(layoutContainer.exists()).toBe(true);
+    expect(routerViewEl.exists()).toBe(true);
+    expect(layoutContainer.element.contains(routerViewEl.element)).toBe(false);
+  });
+
+  it('PageHeader receives title="Admin" + icon="fa-solid fa-user-tie" in list mode', () => {
+    const wrapper = mountLayout();
+    const ph = wrapper.findComponent({ name: 'PageHeader' });
+    expect(ph.props('title')).toBe('Admin');
+    expect(ph.props('icon')).toBe('fa-solid fa-user-tie');
+  });
+
+  it('PageHeader receives title="" + icon stays in breadcrumb mode', async () => {
+    adminStoreState.currentBreadcrumb = { title: 'Jane Doe' };
     const wrapper = mountLayout({}, '/admin/users/u1');
     await wrapper.vm.$nextTick();
-    expect(wrapper.text()).toContain('Jane Doe');
+    const ph = wrapper.findComponent({ name: 'PageHeader' });
+    expect(ph.props('title')).toBe('');
+    expect(ph.props('icon')).toBe('fa-solid fa-user-tie');
   });
 
-  it('does NOT render CoreSurfaceTabBar when currentBreadcrumb is set (detail mode)', async () => {
+  it('does NOT render <CoreSurfaceTabBar> when currentBreadcrumb is set (detail mode)', async () => {
     adminStoreState.currentBreadcrumb = { title: 'Jane Doe' };
     const wrapper = mountLayout({}, '/admin/users/u1');
     await wrapper.vm.$nextTick();
     expect(wrapper.findComponent({ name: 'CoreSurfaceTabBar' }).exists()).toBe(false);
   });
 
-  it('renders CoreSurfaceTabBar when currentBreadcrumb is null (list mode)', () => {
+  it('renders <CoreSurfaceTabBar> when currentBreadcrumb is null (list mode)', () => {
     const wrapper = mountLayout();
     expect(wrapper.findComponent({ name: 'CoreSurfaceTabBar' }).exists()).toBe(true);
   });
+
+  it('renders the breadcrumb when useAdminStore().currentBreadcrumb is set', async () => {
+    adminStoreState.currentBreadcrumb = { title: 'Jane Doe', titleClass: 'text-capitalize' };
+    const wrapper = mountLayout({}, '/admin/users/u1');
+    await wrapper.vm.$nextTick();
+    expect(wrapper.text()).toContain('Jane Doe');
+  });
+
 });

src/modules/admin/tests/admin.organizations.view.unit.tests.js

@@ -75,11 +75,12 @@ import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
 
 describe('admin.organizations.view — template chrome', () => {
-  it('does NOT wrap its template in <v-container> (admin layout owns chrome)', () => {
+  it('wraps its template in <v-container fluid> + <v-row class="pa-2 mt-0"> + <v-col cols="12">', () => {
     const here = dirname(fileURLToPath(import.meta.url));
     const sfc = readFileSync(resolve(here, '../views/admin.organizations.view.vue'), 'utf8');
-    // Extract only the top-level <template>…</template> block (before <script>)
-    const tmpl = sfc.split('<script>')[0] || '';
-    expect(tmpl).not.toMatch(/<v-container/);
+    const tmpl = sfc.split('<script>')[0];
+    expect(tmpl).toMatch(/<v-container\s+fluid/);
+    expect(tmpl).toMatch(/<v-row[^>]*class="[^"]*pa-2\s+mt-0/);
+    expect(tmpl).toMatch(/<v-col\s+cols="12"/);
   });
 });

src/modules/admin/tests/admin.readiness.view.unit.tests.js

@@ -99,11 +99,12 @@ import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
 
 describe('admin.readiness.view — template chrome', () => {
-  it('does NOT wrap its template in <v-container> (admin layout owns chrome)', () => {
+  it('wraps its template in <v-container fluid> + <v-row class="pa-2 mt-0"> + <v-col cols="12">', () => {
     const here = dirname(fileURLToPath(import.meta.url));
     const sfc = readFileSync(resolve(here, '../views/admin.readiness.view.vue'), 'utf8');
-    // Extract only the top-level <template>…</template> block (before <script>)
-    const tmpl = sfc.split('<script>')[0] || '';
-    expect(tmpl).not.toMatch(/<v-container/);
+    const tmpl = sfc.split('<script>')[0];
+    expect(tmpl).toMatch(/<v-container\s+fluid/);
+    expect(tmpl).toMatch(/<v-row[^>]*class="[^"]*pa-2\s+mt-0/);
+    expect(tmpl).toMatch(/<v-col\s+cols="12"/);
   });
 });

src/modules/admin/tests/admin.user.view.unit.tests.js

@@ -63,11 +63,13 @@ const mountView = (routeId = 'u1', initialUser = null) => {
 };
 
 describe('admin.user.view — template chrome', () => {
-  it('does NOT render its own <v-container> (admin layout owns chrome)', () => {
+  it('wraps its template in <v-container fluid> + <v-row class="pa-2 mt-0"> + <v-col cols="12">', () => {
     const here = dirname(fileURLToPath(import.meta.url));
     const sfc = readFileSync(resolve(here, '../views/admin.user.view.vue'), 'utf8');
     const tmpl = sfc.split('<script>')[0];
-    expect(tmpl).not.toMatch(/<v-container/);
+    expect(tmpl).toMatch(/<v-container\s+fluid/);
+    expect(tmpl).toMatch(/<v-row[^>]*class="[^"]*pa-2\s+mt-0/);
+    expect(tmpl).toMatch(/<v-col\s+cols="12"/);
   });
 
   it('does NOT render its own <PageHeader> (admin layout supplies breadcrumb)', () => {

src/modules/admin/tests/admin.users.view.unit.tests.js

@@ -128,12 +128,13 @@ import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
 
 describe('admin.users.view — template chrome', () => {
-  it('does NOT wrap its template in <v-container> (admin layout owns chrome)', () => {
+  it('wraps its template in <v-container fluid> + <v-row class="pa-2 mt-0"> + <v-col cols="12">', () => {
     const here = dirname(fileURLToPath(import.meta.url));
     const sfc = readFileSync(resolve(here, '../views/admin.users.view.vue'), 'utf8');
-    // Extract only the top-level <template>…</template> block (before <script>)
-    const tmpl = sfc.split('<script>')[0] || '';
-    expect(tmpl).not.toMatch(/<v-container/);
+    const tmpl = sfc.split('<script>')[0];
+    expect(tmpl).toMatch(/<v-container\s+fluid/);
+    expect(tmpl).toMatch(/<v-row[^>]*class="[^"]*pa-2\s+mt-0/);
+    expect(tmpl).toMatch(/<v-col\s+cols="12"/);
   });
 });
 

src/modules/admin/views/admin.activity.view.vue

@@ -1,16 +1,19 @@
 <template>
-  <!-- Audit disabled info state -->
-  <v-alert
-    v-if="config.audit && config.audit.enabled === false"
-    type="info"
-    variant="tonal"
-    density="compact"
-    :class="config.vuetify.theme.rounded"
-    icon="fa-solid fa-circle-info"
-  >
-    <span class="text-body-medium">Audit logging is disabled. Enable it in configuration to start tracking activity.</span>
-  </v-alert>
-  <v-card v-else width="100%" color="surface" :flat="config.vuetify.theme.flat" :class="config.vuetify.theme.rounded">
+  <v-container fluid>
+    <v-row class="pa-2 mt-0">
+      <v-col cols="12">
+        <!-- Audit disabled info state -->
+        <v-alert
+          v-if="config.audit && config.audit.enabled === false"
+          type="info"
+          variant="tonal"
+          density="compact"
+          :class="config.vuetify.theme.rounded"
+          icon="fa-solid fa-circle-info"
+        >
+          <span class="text-body-medium">Audit logging is disabled. Enable it in configuration to start tracking activity.</span>
+        </v-alert>
+        <v-card v-else width="100%" color="surface" :flat="config.vuetify.theme.flat" :class="config.vuetify.theme.rounded">
     <v-card-title>
       <v-row dense align="center">
         <v-col cols="12" sm="auto">
@@ -131,7 +134,10 @@
         <v-icon icon="fa-solid fa-angle-right" size="small"></v-icon>
       </v-btn>
     </v-card-actions>
-  </v-card>
+        </v-card>
+      </v-col>
+    </v-row>
+  </v-container>
 </template>
 <script>
 /**