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

[PierreBrisorgueil]

Summary

Fixes three regressions reported by the user after #4187 (homogenization) shipped to production:

1. /users/profile + /users/organizations had transparent content with no surface card, tabs flush against the sidenav (no gutter).
2. /admin/users lost the "Admin" section title with icon above the tabs.
3. Spacing inconsistency between tabs ↔ content ↔ sidenav vs. the reference /developers + /tasks.

Plus a documentation gap raised at the same time:

4. MIGRATIONS.md needed to explain the new chrome convention to downstream projects (admin extras + tabs-under-title modules).

Root cause

#4187 misread corePageHeader's #tabs slot — that slot is mutually exclusive with the icon+title row, so putting CoreSurfaceTabBar inside it hid the section title. The established pattern (used by user.view.vue since #4185 and organization.detail.component.vue since #4184) is PageHeader and CoreSurfaceTabBar as siblings inside <v-container fluid>, with <router-view /> outside the container. The upstream PR #4185 also moved chrome from the monolithic user.view.vue to the layout, but the routed children (user.profile.view, user.organizations.view) never got their <v-card color="surface"> wrap back — leaving transparent panes.

The fix

admin.layout.vue (commit 8dc68af3)

• Drop <template v-if="!currentBreadcrumb" #tabs> slot wrapping. PageHeader + CoreSurfaceTabBar are siblings.
• Drop <div class="admin-content pa-4"> wrapper.
• Move <router-view /> outside <v-container fluid> — children own their gutter.
• icon="fa-solid fa-user-tie" is unconditional (shows in both list + breadcrumb mode).

5 admin sub-views (commits 37bb4bc5, dad8bd3d, 703c9637, 7cb8f6e0, 9efc4239)

• Re-add <v-container fluid> + <v-row class="pa-2 mt-0"> + <v-col cols="12"> chrome.
• coreDataTableComponent consumers (users, organizations) skip the wrap-card — data table already provides a surface.
• v-card-based views (readiness, activity, user form) keep their card INSIDE the <v-col>.

2 account child views (commits 7591fb2b, 1efec145)

• Wrap content in <v-row class="pa-2 mt-0"> + <v-col cols="12"> + <v-card color="surface"> inside <v-container fluid>.
• user.profile.view: danger zone restructured to flex row (heading + description + button inline) for visual coherence. All 3 info pieces preserved.

MIGRATIONS.md (commit 469994d6)

• New top section "Account / Organization / Admin chrome convergence (2026-05-21)" documents the 4 conventions (layout shape, breadcrumb mode, child wrap, downstream opt-in for tabs-under-title modules with a concrete /developers before/after example).

Tests

All 8 affected unit-test files updated in lockstep:

• 5 admin sub-view tests had their not.toMatch(/<v-container/) source-grep assertion REVERSED to toMatch(/<v-container fluid/) + require v-row pa-2 mt-0 + v-col cols=12.

• 2 account-view tests added the same source-grep assertion + <v-card color="surface"> check.

• admin.layout test: 6 new tests asserting sibling pattern (NOT inside #tabs slot), router-view outside container, title="Admin" / "" by breadcrumb mode, icon stays both modes.

• Devkit Vue full suite: 119 test files / 1910 tests green.

• Coverage: 98.98% / 94.11% / 98.95% / 99.59% — exact match with refactor(ui): homogenize Account, Organization detail, and Admin pages #4187 baseline (no logic paths changed, only templates).

• Audit: 0 vulnerabilities. No new deps.

Visual smoke (Chrome DevTools MCP)

GREEN — all 3 user-reported surfaces visually confirmed clean:

• /admin/users — icon + "Admin" title + tab bar; data table on bg-surface with matching gutter.
• /users/profile — Account chrome + profile form on bg-surface (rgb(255,255,255) confirmed via DOM), danger zone below.
• /users/organizations — Account chrome + org list on bg-surface, gutter matches /tasks reference.

Downstream propagation

After merge, propagate to all Vue downstream projects via /update-project. Order: pierreb_vue, comes_vue, trawl_vue, montaine_vue, ism_vue. Per feedback_shim_defer_downstream — on-demand. The trawl_vue propagation will be triggered first (user-priority) since the user reported the issue on trawl.me.

Summary by CodeRabbit

Release Notes

• Documentation

  • Added migration guidance for unified page layout conventions across admin and user interfaces.

• Refactor

  • Restructured page layouts for consistent spacing and visual hierarchy across admin views (activity, organizations, readiness, user management) and user profile pages.
  • Standardized content wrapping and container structure throughout the application.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: bc76ff68-0358-47c1-8bd9-af84701335ec

📥 Commits

Reviewing files that changed from the base of the PR and between 6416e4f and 469994d.

📒 Files selected for processing (17)

• MIGRATIONS.md
• src/modules/admin/tests/admin.activity.view.unit.tests.js
• src/modules/admin/tests/admin.layout.unit.tests.js
• src/modules/admin/tests/admin.organizations.view.unit.tests.js
• src/modules/admin/tests/admin.readiness.view.unit.tests.js
• src/modules/admin/tests/admin.user.view.unit.tests.js
• src/modules/admin/tests/admin.users.view.unit.tests.js
• src/modules/admin/views/admin.activity.view.vue
• src/modules/admin/views/admin.layout.vue
• src/modules/admin/views/admin.organizations.view.vue
• src/modules/admin/views/admin.readiness.view.vue
• src/modules/admin/views/admin.user.view.vue
• src/modules/admin/views/admin.users.view.vue
• src/modules/users/tests/user.organizations.view.unit.tests.js
• src/modules/users/tests/user.profile.view.unit.tests.js
• src/modules/users/views/user.organizations.view.vue
• src/modules/users/views/user.profile.view.vue

---

Walkthrough

This PR implements a unified page layout convention across admin and user modules. The admin layout template is refactored to move CoreSurfaceTabBar outside PageHeader as a sibling and remove the wrapper div around router-view. All routed views are wrapped in consistent v-container/v-row/v-col structure. Unit tests are updated to assert the new chrome pattern instead of prior negation expectations.

Changes

Chrome Convergence Implementation

Layer / File(s)	Summary
Migration documentation MIGRATIONS.md	Introduces the unified page layout convention: PageHeader and CoreSurfaceTabBar as siblings inside the container, router-view outside; routed-child wrapping rules with v-container/v-row/v-col; admin breadcrumb store publication; destructive dialog and avatar uploader standardization; downstream opt-in guidance for module-specific pages.
Admin layout core restructuring src/modules/admin/views/admin.layout.vue	CoreSurfaceTabBar moved outside PageHeader as a gated sibling (when !currentBreadcrumb); router-view rendered directly under container by removing admin-content wrapper div; error/warning banners adjusted with dedicated span blocks.
Admin view template wrapping src/modules/admin/views/admin.activity.view.vue, admin.organizations.view.vue, admin.readiness.view.vue, admin.user.view.vue, admin.users.view.vue	All admin views wrapped in v-container/v-row/v-col structure with padding/margin classes (pa-2 mt-0); existing content, bindings, and conditional logic preserved; only surrounding layout chrome changed.
Admin layout unit test enhancements src/modules/admin/tests/admin.layout.unit.tests.js	PageHeader stub enhanced to expose title/icon props via data attributes; new DOM placement assertions verify CoreSurfaceTabBar is sibling to (not inside) PageHeader, router-view renders outside v-container, and breadcrumb/tab-bar visibility toggles correctly in list vs detail modes.
Admin view template chrome assertions src/modules/admin/tests/admin.*.view.unit.tests.js	Tests updated to assert positive chrome validation (v-container fluid, v-row with pa-2 mt-0, v-col cols="12") via regex on SFC source, replacing prior negative "does not contain v-container" expectations.
User view template wrapping src/modules/users/views/user.organizations.view.vue, user.profile.view.vue	Organizations view wrapped in themed v-card within v-row/v-col; profile view wrapped in v-row/v-col and delete-account card restructured from v-card-title/text/actions to inline h3/p/button; list items and routing logic remain functionally identical.
User view template chrome testing src/modules/users/tests/user.*.view.unit.tests.js	Test stubs extended with v-row/v-col/v-card components; new template chrome blocks added to assert Vuetify structure (v-row with pa-2 mt-0, v-col cols="12", v-card color="surface") via SFC source regex matching.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• pierreb-devkit/Vue#4185: Refactors user.view.vue to use CoreSurfaceTabBar and splits /users/profile and /users/organizations child views, establishing the route structure this PR applies chrome standards to.
• pierreb-devkit/Vue#4187: Introduces admin chrome homogenization changes around breadcrumb/tab-bar placement and replacement of inline v-dialog with coreConfirmDialog, aligning with the migration guidance documented in this PR.
• pierreb-devkit/Vue#3975: Modifies admin.layout.vue and admin tab chrome structure, affecting the same CoreSurfaceTabBar/v-tabs region this PR refactors.

Suggested labels

Fix, Tests

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: restoring section titles, surface backgrounds, and consistent spacing in the UI chrome across admin and account modules.
Description check	✅ Passed	The description is comprehensive and well-structured, covering root cause analysis, detailed fixes across multiple files, test updates, validation results, and downstream propagation guidance. All major sections are properly addressed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/chrome-convergence

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.56%. Comparing base (6416e4f) to head (469994d).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4188   +/-   ##
=======================================
  Coverage   99.56%   99.56%           
=======================================
  Files          31       31           
  Lines        1140     1140           
  Branches      329      329           
=======================================
  Hits         1135     1135           
  Misses          5        5           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR fixes post-#4187 UI chrome regressions by restoring consistent “section header + tab bar + surfaced content” layout across Admin and Account child routes, and documents the convention for downstream projects.

Changes:

• Adjust admin.layout.vue to render PageHeader and CoreSurfaceTabBar as siblings (avoiding PageHeader’s #tabs mode), and move <router-view /> outside the layout container so children own their gutter/surface.
• Reintroduce consistent child-view chrome wrappers (v-container fluid + v-row pa-2 mt-0 + v-col cols=12 and surface cards where appropriate) for Admin sub-views and /users/* child views.
• Update unit tests to assert the restored chrome structure, and add a new MIGRATIONS section describing the convention and downstream opt-in patterns.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/modules/admin/views/admin.layout.vue	Restores section title visibility and consistent tab placement by making the tab bar a sibling (not #tabs) and moving router-view outside the container.
src/modules/admin/views/admin.users.view.vue	Adds standardized container/row/col guttering around the data table view.
src/modules/admin/views/admin.user.view.vue	Wraps the detail view in standardized guttering and keeps the surfaced card layout.
src/modules/admin/views/admin.readiness.view.vue	Adds standardized container/row/col chrome around the readiness surface.
src/modules/admin/views/admin.organizations.view.vue	Adds standardized container/row/col chrome around the organizations data table view.
src/modules/admin/views/admin.activity.view.vue	Adds standardized container/row/col chrome around the activity surface.
src/modules/users/views/user.profile.view.vue	Restores surface background and consistent guttering; restructures danger zone layout within the surfaced content area.
src/modules/users/views/user.organizations.view.vue	Restores surface background and consistent guttering around the organizations list content.
src/modules/admin/tests/admin.layout.unit.tests.js	Updates/extends tests to verify sibling tab-bar pattern, router-view placement, and header props across modes.
src/modules/admin/tests/admin.users.view.unit.tests.js	Updates chrome assertions to expect the new container/row/col structure.
src/modules/admin/tests/admin.user.view.unit.tests.js	Updates chrome assertions to expect the new container/row/col structure.
src/modules/admin/tests/admin.readiness.view.unit.tests.js	Updates chrome assertions to expect the new container/row/col structure.
src/modules/admin/tests/admin.organizations.view.unit.tests.js	Updates chrome assertions to expect the new container/row/col structure.
src/modules/admin/tests/admin.activity.view.unit.tests.js	Updates chrome assertions to expect the new container/row/col structure.
src/modules/users/tests/user.profile.view.unit.tests.js	Adds chrome structure assertions for the restored surfaced/guttered layout.
src/modules/users/tests/user.organizations.view.unit.tests.js	Adds chrome structure assertions for the restored surfaced/guttered layout.
MIGRATIONS.md	Documents the converged chrome convention and downstream opt-in migration pattern.