From 7a49093255ec36627b9dc88e0e993777930c7437 Mon Sep 17 00:00:00 2001
From: Philipp Doerre <philippdoerre@apps.gentics.com>
Date: Mon, 4 May 2026 10:51:38 +0000
Subject: [PATCH 1/5] =?UTF-8?q?fix(editor-ui):=20address=20review=20feedba?=
 =?UTF-8?q?ck=20=E2=80=94=20compare-mode=20+=20visual=20polish?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Quick-win batch from the first round of review (issues 4 and 5.4-5.6):

* editor-toolbar: hide the device-preview button while comparing
  language- or version-variants. The two iframes side-by-side in those
  modes would have to share one device-frame wrapper, which has no
  meaningful UX. The trigger is suppressed via a new `isComparing`
  guard inside determineVisibleButtons() that checks both
  editorState.compareWithId and the COMPARE_VERSION_* edit modes.

* device-preview-menu: add the gentics-ui-core `hollow` class to all
  icons inside the dropdown so they invert against the menu background
  and stay legible — matches the pattern used elsewhere in ui-core.

* content-frame: the device-preview info pill now sticks to the top of
  the scrollable .frame-wrapper while the user scrolls a tall device
  frame. Implementation: pill moved to be the first sibling of the
  iframe containers in the template, switched from
  position: absolute to position: sticky / top: 0.5rem.

* editor-toolbar: device-preview button now has a 0.5rem left margin so
  it no longer touches the BEARBEITEN button — matches the spacing
  convention for primary actions in the same file.

* tests: added a code comment in device-preview.spec.ts explaining why
  the compare-mode hide is not asserted at the e2e level (would
  require multi-language test data + reaching into Angular's injector
  from page.evaluate, both incongruent with the existing test style).

Issues 1, 2, 3, 5.1, 5.2 from the review will be addressed in
follow-up commits as discussed (Observable->Property refactor, URL
parameter persistence, aspect-ratio + design tokens).
---
 cms-ui/apps/editor-ui/e2e/device-preview.spec.ts | 11 +++++++++++
 .../content-frame/content-frame.component.html   | 16 ++++++++--------
 .../content-frame/content-frame.component.scss   | 15 +++++++++++----
 .../device-preview-menu.component.html           |  8 ++++----
 .../editor-toolbar/editor-toolbar.component.scss |  5 +++++
 .../editor-toolbar/editor-toolbar.component.ts   | 14 ++++++++++++--
 6 files changed, 51 insertions(+), 18 deletions(-)

diff --git a/cms-ui/apps/editor-ui/e2e/device-preview.spec.ts b/cms-ui/apps/editor-ui/e2e/device-preview.spec.ts
index 87ae9f71c7..4df5da3c25 100644
--- a/cms-ui/apps/editor-ui/e2e/device-preview.spec.ts
+++ b/cms-ui/apps/editor-ui/e2e/device-preview.spec.ts
@@ -159,6 +159,17 @@ test.describe('Device Preview', () => {
             await expect(trigger).toBeVisible();
         });
 
+        // The compare-mode visibility hide (Vorschau button suppressed when
+        // editorState.compareWithId is set or editMode is one of the
+        // COMPARE_VERSION_* values) is implemented in
+        // EditorToolbarComponent.determineVisibleButtons() and should be
+        // covered by either a Component-level unit test or the existing
+        // language-compare e2e flows when those land. It is intentionally
+        // not asserted here — driving the editor into compare-mode purely
+        // from this spec would require multi-language test data plus a
+        // brittle reach into Angular's injector from page.evaluate(),
+        // which the rest of the test suite avoids.
+
         test('removes the legacy Vorschau entry from the kebab menu', async ({ page }) => {
             const list = findList(page, ITEM_TYPE_PAGE);
             const row = findItem(list, IMPORTER.get(PAGE_ONE).id);
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html
index a2ff7374a8..e9f8449b8c 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html
@@ -118,6 +118,14 @@
             [longerMessage]="'editor.loading_takes_more_time' | gtxI18n"
         ></gtx-loading-spinner>
 
+        @if (devicePreviewActive$ | async; as activePreset) {
+            <div class="device-preview-info">
+                <icon class="device-preview-info-icon">{{ activePreset.icon }}</icon>
+                <span class="device-preview-info-label">{{ activePreset.labelKey | gtxI18n }}</span>
+                <span class="device-preview-info-size">{{ activePreset.width }} × {{ activePreset.height }}</span>
+            </div>
+        }
+
         <div class="frame-language-container" [class.hidden]="!comparePageId">
             <iframe
                 #diffFrame
@@ -146,14 +154,6 @@
 
             <div class="frame-language-indicator" [class.hidden]="!comparePageId">{{ itemLanguage?.name }}</div>
         </div>
-
-        @if (devicePreviewActive$ | async; as activePreset) {
-            <div class="device-preview-info">
-                <icon class="device-preview-info-icon">{{ activePreset.icon }}</icon>
-                <span class="device-preview-info-label">{{ activePreset.labelKey | gtxI18n }}</span>
-                <span class="device-preview-info-size">{{ activePreset.width }} × {{ activePreset.height }}</span>
-            </div>
-        }
     </div>
 
     <div class="hidden-file-picker" #filePickerWrapper>
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss
index 9dcbec85ac..3e29b18bf7 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss
@@ -81,10 +81,17 @@
         }
 
         .device-preview-info {
-            position: absolute;
-            top: 8px;
-            left: 50%;
-            transform: translateX(-50%);
+            // Sticks to the top of the scrollable .frame-wrapper while the
+            // user scrolls a tall device-frame (e.g. a 1024px-tall tablet
+            // inside a 600px-tall editor panel). The pill is the FIRST
+            // child after the loading indicators in the wrapper template,
+            // so its natural position is at the top — `position: sticky`
+            // then keeps it pinned there regardless of scroll position.
+            position: sticky;
+            top: 0.5rem;
+            align-self: center;
+            flex: 0 0 auto;
+            margin-bottom: 0.5rem;
             background: $gtx-color-primary;
             color: white;
             padding: 4px 12px;
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/device-preview-menu/device-preview-menu.component.html b/cms-ui/apps/editor-ui/src/app/content-frame/components/device-preview-menu/device-preview-menu.component.html
index 7d7ea9fecc..6c41fadae2 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/device-preview-menu/device-preview-menu.component.html
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/device-preview-menu/device-preview-menu.component.html
@@ -9,10 +9,10 @@
         [class.is-selected]="!activePresetId"
         (click)="onClear()"
     >
-        <icon left>aspect_ratio</icon>
+        <icon left class="hollow">aspect_ratio</icon>
         <span class="device-label">{{ 'editor.device_preview_clear' | gtxI18n }}</span>
         @if (!activePresetId) {
-            <icon class="device-check" right>check</icon>
+            <icon class="device-check hollow" right>check</icon>
         }
     </gtx-dropdown-item>
 
@@ -25,11 +25,11 @@
             [class.is-selected]="activePresetId === preset.id"
             (click)="onSelect(preset)"
         >
-            <icon left>{{ preset.icon }}</icon>
+            <icon left class="hollow">{{ preset.icon }}</icon>
             <span class="device-label">{{ preset.labelKey | gtxI18n }}</span>
             <span class="device-size">{{ preset.width }} × {{ preset.height }}</span>
             @if (activePresetId === preset.id) {
-                <icon class="device-check" right>check</icon>
+                <icon class="device-check hollow" right>check</icon>
             }
         </gtx-dropdown-item>
     }
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.scss b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.scss
index 7c6c59e043..75aa9a67e7 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.scss
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.scss
@@ -38,6 +38,11 @@
     }
 
     .device-preview-button {
+        // Spacing to whichever button comes before us in the
+        // .toolbar-actions row. Matches the existing margin convention
+        // used by other primary actions in this file.
+        margin-left: 0.5rem;
+
         // The `<gtx-button>` inside handles its own flex layout; we only
         // tweak the caret + label cosmetics here. Vertical centering is
         // achieved via inline-flex on the inner spans/icons so that the
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts
index d5db1e27b3..1b10609243 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts
@@ -473,8 +473,18 @@ export class EditorToolbarComponent implements OnInit, OnChanges, OnDestroy {
         const canPublish = !!(isPage || (isForm && (this.itemPermissions as FormPermissions)?.publish));
 
         // Device-preview is meaningful while we're looking at the rendered
-        // iframe (preview or edit mode) of a page or form.
-        const showDevicePreview = (isPage || isForm) && (previewing || editing) && userCan.view;
+        // iframe (preview or edit mode) of a page or form. It is suppressed
+        // during version- or language-comparison views, because there are
+        // two iframes side by side in those modes and the device-frame
+        // wrapper around a single one would only constrain the master
+        // iframe — confusing UX.
+        const isComparing = !!this.editorState?.compareWithId
+            || editMode === EditMode.COMPARE_VERSION_SOURCES
+            || editMode === EditMode.COMPARE_VERSION_CONTENTS;
+        const showDevicePreview = (isPage || isForm)
+            && (previewing || editing)
+            && !isComparing
+            && userCan.view;
 
         return {
             compareContents: (isPage || isForm) && editMode === EditMode.COMPARE_VERSION_SOURCES,

From 28bde916df7b852cb11b9edea54e97db9f3657c6 Mon Sep 17 00:00:00 2001
From: Philipp Doerre <philippdoerre@apps.gentics.com>
Date: Mon, 4 May 2026 10:53:49 +0000
Subject: [PATCH 2/5] refactor(editor-ui): replace device-preview async pipes
 with subscribed properties
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review feedback issue 2: async pipes in templates open a fresh
subscription on every change-detection cycle, multiply work, and make
debugging harder. The convention used elsewhere in the same toolbar
component (see e.g. `isSaving`, `focusMode`) is to subscribe once in
`ngOnInit`, store the value in a plain property, and call
`changeDetector.markForCheck()`.

Changes:

* editor-toolbar:
  - drop `devicePreviewState$` / `devicePreviewActive$` / `devicePreviewPresets$`
  - introduce `devicePreviewState` / `devicePreviewActivePreset` / `devicePreviewPresets`
  - subscribe to the three streams from DevicePreviewService in `ngOnInit`,
    push subscriptions onto the existing teardown array
  - update template bindings to read the plain properties directly
    (no async pipes anywhere on device-preview state)

* content-frame:
  - drop `devicePreviewActive$` Observable property
  - introduce `devicePreviewActivePreset` plain property
  - subscribe to `devicePreview.activePreset$` in `ngOnInit`
  - update the four template bindings (class.device-preview-active,
    data-active-preset, --device-w/--device-h, info pill @if) to use
    the plain property

No behavioural change. The DevicePreviewService API is unchanged — the
service still exposes Observables, only the consumers' subscription
shape changed.
---
 .../content-frame.component.html              | 16 +++++------
 .../content-frame/content-frame.component.ts  | 18 +++++++-----
 .../editor-toolbar.component.html             | 12 ++++----
 .../editor-toolbar.component.ts               | 28 ++++++++++++++-----
 4 files changed, 46 insertions(+), 28 deletions(-)

diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html
index e9f8449b8c..02c78df145 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html
@@ -92,10 +92,10 @@
     <div
         class="frame-wrapper"
         [class.hidden]="editMode === EditMode.EDIT_PROPERTIES || editMode === EditMode.EDIT_INHERITANCE || currentItem?.type === 'form'"
-        [class.device-preview-active]="!!(devicePreviewActive$ | async)"
-        [attr.data-active-preset]="(devicePreviewActive$ | async)?.id"
-        [style.--device-w.px]="(devicePreviewActive$ | async)?.width"
-        [style.--device-h.px]="(devicePreviewActive$ | async)?.height"
+        [class.device-preview-active]="!!devicePreviewActivePreset"
+        [attr.data-active-preset]="devicePreviewActivePreset?.id"
+        [style.--device-w.px]="devicePreviewActivePreset?.width"
+        [style.--device-h.px]="devicePreviewActivePreset?.height"
     >
         <gtx-progress-bar
             class="frame-requesting"
@@ -118,11 +118,11 @@
             [longerMessage]="'editor.loading_takes_more_time' | gtxI18n"
         ></gtx-loading-spinner>
 
-        @if (devicePreviewActive$ | async; as activePreset) {
+        @if (devicePreviewActivePreset) {
             <div class="device-preview-info">
-                <icon class="device-preview-info-icon">{{ activePreset.icon }}</icon>
-                <span class="device-preview-info-label">{{ activePreset.labelKey | gtxI18n }}</span>
-                <span class="device-preview-info-size">{{ activePreset.width }} × {{ activePreset.height }}</span>
+                <icon class="device-preview-info-icon">{{ devicePreviewActivePreset.icon }}</icon>
+                <span class="device-preview-info-label">{{ devicePreviewActivePreset.labelKey | gtxI18n }}</span>
+                <span class="device-preview-info-size">{{ devicePreviewActivePreset.width }} × {{ devicePreviewActivePreset.height }}</span>
             </div>
         }
 
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.ts b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.ts
index 0f178fbca6..a9d1cc5143 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.ts
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.ts
@@ -196,11 +196,12 @@ export class ContentFrameComponent implements OnInit, AfterViewInit, OnDestroy {
     isInQueue$: Observable<boolean> = undefined;
 
     /**
-     * Stream of the currently active device-preview preset (or null when off).
-     * Bound directly in the template to constrain the iframe to mobile / tablet
-     * / desktop viewport sizes via CSS custom properties.
+     * Currently active device-preview preset (or null when off). Mirrored
+     * from `DevicePreviewService.activePreset$` via a subscription set up
+     * in `ngOnInit`, so the template can read it as a plain property
+     * instead of opening async-pipe subscriptions on every render.
      */
-    public devicePreviewActive$: Observable<DevicePreset | null>;
+    public devicePreviewActivePreset: DevicePreset | null = null;
 
     private onLoadListener: EventListener;
     public itemPermissions: ItemPermissions = noItemPermissions;
@@ -242,9 +243,7 @@ export class ContentFrameComponent implements OnInit, AfterViewInit, OnDestroy {
         private aloha: AlohaIntegrationService,
         private urlBuilder: ResourceUrlBuilder,
         private devicePreview: DevicePreviewService,
-    ) {
-        this.devicePreviewActive$ = this.devicePreview.activePreset$;
-    }
+    ) { }
 
     ngOnInit(): void {
         this.customScriptHostService.initialize(this);
@@ -256,6 +255,11 @@ export class ContentFrameComponent implements OnInit, AfterViewInit, OnDestroy {
             return this.customerScriptService.createGCMSUIObject(this.customScriptHostService, iFrameWindow, iFrameDocument);
         };
 
+        this.subscriptions.push(this.devicePreview.activePreset$.subscribe((preset) => {
+            this.devicePreviewActivePreset = preset;
+            this.changeDetector.markForCheck();
+        }));
+
         this.subscriptions.push(
             this.appState.select((state) => state.editor.contentModified).subscribe((modified) => {
                 this.contentModified = modified;
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.html b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.html
index 400e812c1a..2d3872139b 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.html
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.html
@@ -132,7 +132,7 @@
                         class="primary-action device-preview-button"
                         data-action="device-preview"
                         data-context-id="device-preview"
-                        [class.is-active]="!!(devicePreviewActive$ | async)"
+                        [class.is-active]="!!devicePreviewActivePreset"
                     >
                         <gtx-dropdown-trigger>
                             <gtx-button
@@ -141,10 +141,10 @@
                                 [title]="'editor.device_preview_tooltip' | gtxI18n"
                                 data-context-trigger
                             >
-                                <icon left>{{ (devicePreviewActive$ | async)?.icon || 'devices' }}</icon>
+                                <icon left>{{ devicePreviewActivePreset?.icon || 'devices' }}</icon>
                                 <span class="device-preview-button-label">
-                                    @if (devicePreviewActive$ | async; as activePreset) {
-                                        {{ activePreset.labelKey | gtxI18n }}
+                                    @if (devicePreviewActivePreset) {
+                                        {{ devicePreviewActivePreset.labelKey | gtxI18n }}
                                     } @else {
                                         {{ 'editor.device_preview_label' | gtxI18n }}
                                     }
@@ -154,8 +154,8 @@
                         </gtx-dropdown-trigger>
                         <gtx-dropdown-content data-context-id="device-preview">
                             <gtx-device-preview-menu
-                                [presets]="devicePreviewPresets$ | async"
-                                [activePresetId]="(devicePreviewState$ | async)?.presetId"
+                                [presets]="devicePreviewPresets"
+                                [activePresetId]="devicePreviewState.presetId"
                                 (select)="selectDevicePreset($event)"
                                 (clear)="clearDevicePreset()"
                             ></gtx-device-preview-menu>
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts
index 1b10609243..56be2657d5 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts
@@ -118,10 +118,15 @@ export class EditorToolbarComponent implements OnInit, OnChanges, OnDestroy {
     public uploadInProgress$: Observable<boolean>;
     public alohaReady: boolean;
 
-    /** Streams from the DevicePreviewService — wired in ngOnInit. */
-    public devicePreviewState$: Observable<DevicePreviewState>;
-    public devicePreviewActive$: Observable<DevicePreset | null>;
-    public devicePreviewPresets$: Observable<DevicePreset[]>;
+    /**
+     * Mirror of `DevicePreviewService` state, kept as plain properties so
+     * the template doesn't have to subscribe via async pipes (which would
+     * each open their own subscription on every change-detection run).
+     * Wired in `ngOnInit` and torn down via `subscriptions`.
+     */
+    public devicePreviewState: DevicePreviewState = { active: false, presetId: null };
+    public devicePreviewActivePreset: DevicePreset | null = null;
+    public devicePreviewPresets: DevicePreset[] = [];
 
     public breadcrumbs: (IBreadcrumbLink | IBreadcrumbRouterLink)[] = [];
     public multilineExpanded: boolean;
@@ -152,9 +157,18 @@ export class EditorToolbarComponent implements OnInit, OnChanges, OnDestroy {
     ) {}
 
     ngOnInit(): void {
-        this.devicePreviewState$ = this.devicePreview.state$;
-        this.devicePreviewActive$ = this.devicePreview.activePreset$;
-        this.devicePreviewPresets$ = this.devicePreview.presets$;
+        this.subscriptions.push(this.devicePreview.state$.subscribe((state) => {
+            this.devicePreviewState = state;
+            this.changeDetector.markForCheck();
+        }));
+        this.subscriptions.push(this.devicePreview.activePreset$.subscribe((preset) => {
+            this.devicePreviewActivePreset = preset;
+            this.changeDetector.markForCheck();
+        }));
+        this.subscriptions.push(this.devicePreview.presets$.subscribe((presets) => {
+            this.devicePreviewPresets = presets;
+            this.changeDetector.markForCheck();
+        }));
 
         this.uploadInProgress$ = this.appState.select((state) => state.editor).pipe(
             map((editorState) => editorState.uploadInProgress),

From ed5011dcfdefff7e0bb61da9c3ee17fb6278e0af Mon Sep 17 00:00:00 2001
From: Philipp Doerre <philippdoerre@apps.gentics.com>
Date: Mon, 4 May 2026 10:58:00 +0000
Subject: [PATCH 3/5] refactor(editor-ui): drive device-preview state from URL
 query parameter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review feedback issue 1. The previous local-storage persistence (via the
LocalStorage wrapper) sat next to the UserSettingsService machinery
without integrating with it, and its convention diverged from the rest
of the editor. The reviewer suggested making the active preset part of
the URL instead — that lets the user share a preview link with a
specific device size, makes the browser back/forward buttons cycle
through presets naturally, and removes the need for any persistence
layer at all.

Implementation:

* DevicePreviewService:
  - inject Angular's Router instead of LocalStorage
  - on construction: parse current URL, seed state from `?device=`
  - subscribe to NavigationEnd events so the state stays in sync with
    every URL change (programmatic navigation, browser nav, deep links)
  - activate(id) / deactivate() now mutate the URL via parseUrl +
    navigateByUrl(... { replaceUrl: true }) — single source of truth is
    the URL, the BehaviorSubject is just a memoised mirror
  - exported new constant DEVICE_PREVIEW_QUERY_PARAM = 'device'
  - dropped persistLastPresetId / getLastUsedPresetId / activateLastUsed
  - implements OnDestroy so the router subscription cleans up
    (defensive — providedIn: 'root' services rarely tear down, but
    still correct)

* EditorToolbarComponent:
  - replaced ensurePreviewMode() + two sequential service calls with a
    single dispatchDevicePreview(presetId | null) helper. When in EDIT
    mode it does ONE router navigation that covers both the mode
    switch AND the device query parameter (using NavigationExtras with
    queryParamsHandling: 'merge') — so the iframe only reloads once.
  - removed the explicit auto-deactivate subscription on
    state.editor.editMode: leaving PREVIEW now drops the query param
    via normal navigation, the service picks that up, the state
    resets. Auto-deactivation comes for free from routing.

* device-preview.service.spec.ts:
  - swapped MockLocalStorage for a MockRouter that records
    navigateByUrl calls and emits synthetic NavigationEnd events
  - added tests for: URL seeding, unknown preset rejection, navigation
    side effects, browser back/forward simulation
  - kept the activePreset$ emission test

* device-preview.spec.ts (e2e):
  - replaced the LocalStorage assertion with three URL-state tests:
    URL contains ?device=<id> after activation, ?device= is gone after
    'Volle Breite', and reloading a URL with ?device=desktop restores
    the active preset (covers the 'shareable link' use case)
---
 .../apps/editor-ui/e2e/device-preview.spec.ts |  40 ++++--
 .../editor-toolbar.component.ts               |  75 +++++------
 .../device-preview.service.spec.ts            | 115 +++++++++++++----
 .../device-preview/device-preview.service.ts  | 118 +++++++++++-------
 4 files changed, 234 insertions(+), 114 deletions(-)

diff --git a/cms-ui/apps/editor-ui/e2e/device-preview.spec.ts b/cms-ui/apps/editor-ui/e2e/device-preview.spec.ts
index 4df5da3c25..3a759736a6 100644
--- a/cms-ui/apps/editor-ui/e2e/device-preview.spec.ts
+++ b/cms-ui/apps/editor-ui/e2e/device-preview.spec.ts
@@ -330,26 +330,44 @@ test.describe('Device Preview', () => {
     });
 
     /* --------------------------------------------------------------------- *
-     * Persistence
+     * URL state
      * --------------------------------------------------------------------- */
 
-    test.describe('Persistence', () => {
+    test.describe('URL state', () => {
 
-        test('persists the most recently used preset to local storage', async ({ page }) => {
+        test('writes the active preset id to the URL as `?device=` query param', async ({ page }) => {
             await openPageInPreview(page, IMPORTER.get(PAGE_ONE));
 
             await pickDevicePreset(page, PRESET_TABLET.id);
             await expect(page.locator(FRAME_WRAPPER)).toHaveAttribute('data-active-preset', PRESET_TABLET.id);
 
-            // The DevicePreviewService persists via the `LocalStorage` wrapper
-            // which prefixes its keys with `GCMSUI_`. The setting is
-            // application-wide (`getForAllUsers`), so the unprefixed key is
-            // `devicePreview.lastPresetId`.
-            const stored = await page.evaluate(() => localStorage.getItem('GCMSUI_devicePreview.lastPresetId'));
+            // URL now carries `?device=tablet`
+            await expect(page).toHaveURL(/[?&]device=tablet(&|$)/);
+        });
+
+        test('removes the query param when "Volle Breite" is picked', async ({ page }) => {
+            await openPageInPreview(page, IMPORTER.get(PAGE_ONE));
+
+            await pickDevicePreset(page, PRESET_MOBILE.id);
+            await expect(page).toHaveURL(/[?&]device=mobile(&|$)/);
+
+            await pickDevicePreset(page, 'clear');
+            await expect(page).not.toHaveURL(/[?&]device=/);
+        });
 
-            // LocalStorage wrapper stringifies values, so the expected
-            // shape is the JSON-encoded preset id.
-            expect(stored).toBe(JSON.stringify(PRESET_TABLET.id));
+        test('restores the active preset when reloading a URL with `?device=`', async ({ page }) => {
+            await openPageInPreview(page, IMPORTER.get(PAGE_ONE));
+
+            await pickDevicePreset(page, PRESET_DESKTOP.id);
+            const urlWithPreset = page.url();
+            expect(urlWithPreset).toMatch(/[?&]device=desktop(&|$)/);
+
+            // Hard-reload the URL to simulate the user opening a shared link.
+            await page.goto(urlWithPreset);
+            await page.locator('content-frame iframe.master-frame[loaded="true"]').waitFor({ timeout: 60_000 });
+
+            await expect(page.locator(FRAME_WRAPPER)).toHaveClass(/device-preview-active/);
+            await expect(page.locator(FRAME_WRAPPER)).toHaveAttribute('data-active-preset', PRESET_DESKTOP.id);
         });
     });
 });
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts
index 56be2657d5..a5ba5c7289 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.ts
@@ -211,14 +211,13 @@ export class EditorToolbarComponent implements OnInit, OnChanges, OnDestroy {
             this.changeDetector.markForCheck();
         }));
 
-        // Auto-deactivate device-preview when the user leaves PREVIEW mode
-        // (e.g. clicks "Bearbeiten" to start editing). Without this the user
-        // would end up editing in a 375px frame with Aloha toolbars cropped.
-        this.subscriptions.push(this.appState.select((state) => state.editor.editMode).subscribe((editMode) => {
-            if (editMode !== EditMode.PREVIEW && this.devicePreview.currentState.active) {
-                this.devicePreview.deactivate();
-            }
-        }));
+        // No explicit auto-deactivation needed: device-preview state is
+        // derived from the URL's `?device=` query parameter via
+        // DevicePreviewService. Whenever the user leaves PREVIEW mode (e.g.
+        // by clicking BEARBEITEN), the navigation drops the query param,
+        // and the service's NavigationEnd subscriber resets the state. So
+        // "no edit mode in mobile frame" comes for free from the routing
+        // layer.
 
         this.setUpBreadcrumbs(this.currentItem, this.currentNode?.id);
         this.checkIfInQueue();
@@ -391,44 +390,50 @@ export class EditorToolbarComponent implements OnInit, OnChanges, OnDestroy {
             .navigate();
     }
 
-    /**
-     * Switches the editor from EDIT to PREVIEW mode if currently editing.
-     * Both `selectDevicePreset` and `clearDevicePreset` route through this so
-     * any interaction with the Vorschau dropdown lands the user in PREVIEW.
-     */
-    private ensurePreviewMode(): void {
-        const editMode = this.editorState?.editMode;
-        if (editMode === EditMode.EDIT && this.currentNode && this.currentItem) {
-            this.navigationService
-                .detailOrModal(this.currentNode.id, this.currentItem.type, this.currentItem.id, EditMode.PREVIEW)
-                .navigate();
-        }
-    }
-
     /**
      * Activate device-preview mode for the given preset (mobile / tablet / …).
      * The content-frame iframe will be visually constrained to this size.
      *
-     * If the editor is currently in EDIT mode, this also switches to PREVIEW —
-     * editing inside a 375px viewport with Aloha toolbars overflowing is
-     * disorienting, and device-preview is conceptually a "view as end-user"
-     * mode. Return to editing via the BEARBEITEN button (which auto-
-     * deactivates the device preset, see ngOnInit).
+     * If the editor is currently in EDIT mode, switching mode and writing the
+     * `?device=` query parameter is performed in a single router navigation
+     * so the iframe only reloads once. Otherwise the service updates the
+     * query parameter directly, leaving the path unchanged.
      */
     public selectDevicePreset(preset: DevicePreset): void {
-        this.ensurePreviewMode();
-        this.devicePreview.activate(preset.id);
+        this.dispatchDevicePreview(preset.id);
     }
 
     /**
-     * Deactivate device-preview mode and return to full-width rendering.
-     * If the user picks "Volle Breite" while still in EDIT mode, this also
-     * switches to PREVIEW so the behaviour is consistent across all
-     * dropdown entries — every Vorschau interaction lands in PREVIEW.
+     * Deactivate device-preview mode (full-width rendering). Like selection,
+     * picking "Volle Breite" while in EDIT also switches to PREVIEW, so any
+     * interaction with the Vorschau dropdown lands the user there.
      */
     public clearDevicePreset(): void {
-        this.ensurePreviewMode();
-        this.devicePreview.deactivate();
+        this.dispatchDevicePreview(null);
+    }
+
+    /**
+     * Single entry point for both selection and clearing. Combines the
+     * EDIT→PREVIEW switch (if needed) with the device query parameter
+     * update into one navigation, then falls back to the service when the
+     * user is already in PREVIEW.
+     */
+    private dispatchDevicePreview(presetId: string | null): void {
+        const inEdit = this.editorState?.editMode === EditMode.EDIT;
+        if (inEdit && this.currentNode && this.currentItem) {
+            this.navigationService
+                .detailOrModal(this.currentNode.id, this.currentItem.type, this.currentItem.id, EditMode.PREVIEW)
+                .navigate({
+                    queryParams: { device: presetId },
+                    queryParamsHandling: 'merge',
+                });
+            return;
+        }
+        if (presetId) {
+            this.devicePreview.activate(presetId);
+        } else {
+            this.devicePreview.deactivate();
+        }
     }
 
     editInheritance(): void {
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/providers/device-preview/device-preview.service.spec.ts b/cms-ui/apps/editor-ui/src/app/content-frame/providers/device-preview/device-preview.service.spec.ts
index 3ad03b4d0f..3bb6c75bc5 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/providers/device-preview/device-preview.service.spec.ts
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/providers/device-preview/device-preview.service.spec.ts
@@ -1,60 +1,120 @@
 import { TestBed } from '@angular/core/testing';
-import { LocalStorage } from '../../../core/providers/local-storage/local-storage.service';
+import { NavigationEnd, Router } from '@angular/router';
+import { Subject } from 'rxjs';
 import {
     DEFAULT_DEVICE_PRESETS,
-    DEVICE_PREVIEW_LAST_PRESET_KEY,
+    DEVICE_PREVIEW_QUERY_PARAM,
     DevicePreviewService,
 } from './device-preview.service';
 
-class MockLocalStorage {
-    private store = new Map<string, any>();
-    getForAllUsers(key: string): any {
-        return this.store.has(key) ? this.store.get(key) : null;
+class MockRouter {
+    public events = new Subject<any>();
+    public url = '/editor/1/page/2/preview';
+    public navigateByUrlCalls: { tree: any; extras?: any }[] = [];
+
+    parseUrl(url: string): any {
+        const [path, query = ''] = url.split('?');
+        const queryParams: Record<string, string> = {};
+        if (query) {
+            for (const part of query.split('&')) {
+                const [k, v] = part.split('=');
+                if (k) {
+                    queryParams[decodeURIComponent(k)] = decodeURIComponent(v ?? '');
+                }
+            }
+        }
+        return {
+            path,
+            queryParams,
+            toString(): string {
+                const qp = Object.entries(this.queryParams)
+                    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v as string)}`)
+                    .join('&');
+                return qp ? `${this.path}?${qp}` : this.path;
+            },
+        };
     }
-    setForAllUsers(key: string, value: any): void {
-        this.store.set(key, value);
+
+    navigateByUrl(tree: any, extras?: any): Promise<boolean> {
+        this.navigateByUrlCalls.push({ tree, extras });
+        const newUrl = tree.toString();
+        this.url = newUrl;
+        // Emit a NavigationEnd to mimic real router behaviour
+        this.events.next(new NavigationEnd(1, newUrl, newUrl));
+        return Promise.resolve(true);
     }
 }
 
 describe('DevicePreviewService', () => {
 
     let service: DevicePreviewService;
-    let storage: MockLocalStorage;
+    let router: MockRouter;
 
-    beforeEach(() => {
-        storage = new MockLocalStorage();
+    function createService(initialUrl: string = '/editor/1/page/2/preview'): void {
+        router = new MockRouter();
+        router.url = initialUrl;
         TestBed.configureTestingModule({
             providers: [
                 DevicePreviewService,
-                { provide: LocalStorage, useValue: storage },
+                { provide: Router, useValue: router },
             ],
         });
         service = TestBed.inject(DevicePreviewService);
+    }
+
+    afterEach(() => {
+        service?.ngOnDestroy?.();
     });
 
-    it('starts deactivated with default presets exposed', () => {
+    it('starts deactivated when no device query param is present in the URL', () => {
+        createService('/editor/1/page/2/preview');
         expect(service.currentState).toEqual({ active: false, presetId: null });
         expect(service.presets.length).toBe(DEFAULT_DEVICE_PRESETS.length);
     });
 
-    it('activates a preset and persists it to local storage', () => {
+    it('seeds initial state from a `?device=` query param on the current URL', () => {
+        createService('/editor/1/page/2/preview?device=tablet');
+        expect(service.currentState).toEqual({ active: true, presetId: 'tablet' });
+    });
+
+    it('ignores an unknown preset id in the URL', () => {
+        createService('/editor/1/page/2/preview?device=xxx');
+        expect(service.currentState).toEqual({ active: false, presetId: null });
+    });
+
+    it('activate() writes the preset id into the URL via Router.navigateByUrl', () => {
+        createService();
         service.activate('mobile');
+        const last = router.navigateByUrlCalls.at(-1);
+        expect(last?.tree.queryParams[DEVICE_PREVIEW_QUERY_PARAM]).toBe('mobile');
         expect(service.currentState).toEqual({ active: true, presetId: 'mobile' });
-        expect(storage.getForAllUsers(DEVICE_PREVIEW_LAST_PRESET_KEY)).toBe('mobile');
     });
 
-    it('ignores activation requests for unknown preset ids', () => {
+    it('activate() ignores an unknown preset id', () => {
+        createService();
         service.activate('does-not-exist');
+        expect(router.navigateByUrlCalls.length).toBe(0);
         expect(service.currentState).toEqual({ active: false, presetId: null });
     });
 
-    it('deactivate() returns to inactive state', () => {
-        service.activate('tablet');
+    it('deactivate() removes the device query param from the URL', () => {
+        createService('/editor/1/page/2/preview?device=tablet');
+        expect(service.currentState.active).toBe(true);
         service.deactivate();
+        const last = router.navigateByUrlCalls.at(-1);
+        expect(last?.tree.queryParams[DEVICE_PREVIEW_QUERY_PARAM]).toBeUndefined();
         expect(service.currentState).toEqual({ active: false, presetId: null });
     });
 
+    it('deactivate() is a no-op when device-preview is already off', () => {
+        createService('/editor/1/page/2/preview');
+        service.deactivate();
+        expect(router.navigateByUrlCalls.length).toBe(0);
+    });
+
     it('toggle() switches the same preset off and a different preset on', () => {
+        createService();
+
         service.toggle('desktop');
         expect(service.currentState.active).toBe(true);
         expect(service.currentState.presetId).toBe('desktop');
@@ -66,18 +126,23 @@ describe('DevicePreviewService', () => {
         expect(service.currentState.presetId).toBe('mobile');
     });
 
-    it('activateLastUsed() restores the persisted preset', () => {
-        storage.setForAllUsers(DEVICE_PREVIEW_LAST_PRESET_KEY, 'tablet');
-        const restored = service.activateLastUsed();
-        expect(restored).toBe(true);
+    it('reflects URL changes coming from the router (browser back/forward)', () => {
+        createService('/editor/1/page/2/preview?device=tablet');
         expect(service.currentState.presetId).toBe('tablet');
-    });
 
-    it('activateLastUsed() returns false when no preset was persisted', () => {
-        expect(service.activateLastUsed()).toBe(false);
+        // Simulate the user navigating back to a URL without the device param
+        router.url = '/editor/1/page/2/preview';
+        router.events.next(new NavigationEnd(2, router.url, router.url));
+        expect(service.currentState).toEqual({ active: false, presetId: null });
+
+        // Simulate forward to a URL with a different preset
+        router.url = '/editor/1/page/2/preview?device=mobile';
+        router.events.next(new NavigationEnd(3, router.url, router.url));
+        expect(service.currentState).toEqual({ active: true, presetId: 'mobile' });
     });
 
     it('activePreset$ emits null while inactive and the resolved preset while active', (done) => {
+        createService();
         const emissions: (string | null)[] = [];
         service.activePreset$.subscribe(p => emissions.push(p?.id ?? null));
 
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/providers/device-preview/device-preview.service.ts b/cms-ui/apps/editor-ui/src/app/content-frame/providers/device-preview/device-preview.service.ts
index f18caad0ac..4f089a1469 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/providers/device-preview/device-preview.service.ts
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/providers/device-preview/device-preview.service.ts
@@ -1,7 +1,7 @@
-import { Injectable } from '@angular/core';
-import { BehaviorSubject, Observable } from 'rxjs';
-import { distinctUntilChanged, map } from 'rxjs/operators';
-import { LocalStorage } from '../../../core/providers/local-storage/local-storage.service';
+import { Injectable, OnDestroy } from '@angular/core';
+import { NavigationEnd, Router } from '@angular/router';
+import { BehaviorSubject, Observable, Subscription } from 'rxjs';
+import { distinctUntilChanged, filter, map } from 'rxjs/operators';
 import { DevicePreset, DevicePreviewState } from '../../models/device-preset';
 
 /**
@@ -15,24 +15,28 @@ export const DEFAULT_DEVICE_PRESETS: ReadonlyArray<DevicePreset> = Object.freeze
     { id: 'desktop-xl', labelKey: 'editor.device_desktop_xl_label', icon: 'tv',              width: 1600, height: 960 },
 ]);
 
-/** LocalStorage key for the most recently used preset id. */
-export const DEVICE_PREVIEW_LAST_PRESET_KEY = 'devicePreview.lastPresetId';
+/** Query-parameter name carrying the active preset id in the URL. */
+export const DEVICE_PREVIEW_QUERY_PARAM = 'device';
 
 /**
  * Holds the device-preview state (active flag + selected preset) and exposes
- * it as observables so the editor-toolbar and content-frame components stay in
- * sync.
+ * it as observables so the editor-toolbar and content-frame components stay
+ * in sync.
  *
- * Persistence: the most recently used preset is stored via the existing
- * `LocalStorage` wrapper so the user's last choice survives a reload.
+ * **State source of truth: the URL.** The active preset id lives as the
+ * `?device=<id>` query parameter on the editor route. Reasons:
+ *   - shareable links carry the user's preview format,
+ *   - browser back/forward navigates between formats naturally,
+ *   - no local persistence layer is needed (no UserSettings entry, no
+ *     LocalStorage handling, no per-user/per-tab divergence).
  *
- * Note on architecture: kept intentionally lightweight (BehaviorSubject) so
- * it does not pull in the global NgRx state graph for a UI-only concern.
- * If CMS-wide configurable presets become a requirement later, the `presets$`
- * observable is the natural extension point.
+ * The service mirrors the URL into its `state$` BehaviorSubject so that
+ * consumers don't have to deal with `ActivatedRoute` themselves. Mutations
+ * are performed via Angular's `Router`, which means they integrate cleanly
+ * with the rest of the editor's navigation flow.
  */
 @Injectable({ providedIn: 'root' })
-export class DevicePreviewService {
+export class DevicePreviewService implements OnDestroy {
 
     private readonly stateSubject = new BehaviorSubject<DevicePreviewState>({
         active: false,
@@ -43,6 +47,8 @@ export class DevicePreviewService {
         [...DEFAULT_DEVICE_PRESETS],
     );
 
+    private routerSubscription: Subscription;
+
     /** Stream of state changes (active flag, selected preset id). */
     public readonly state$: Observable<DevicePreviewState> = this.stateSubject.asObservable();
 
@@ -58,7 +64,22 @@ export class DevicePreviewService {
         distinctUntilChanged((a, b) => a?.id === b?.id),
     );
 
-    constructor(private localStorage: LocalStorage) {}
+    constructor(private router: Router) {
+        // Seed initial state from the current URL.
+        this.syncStateFromUrl(this.router.url);
+
+        // Keep state in sync with future URL changes (programmatic navigation,
+        // browser back/forward, links).
+        this.routerSubscription = this.router.events.pipe(
+            filter((e): e is NavigationEnd => e instanceof NavigationEnd),
+        ).subscribe((event) => {
+            this.syncStateFromUrl(event.urlAfterRedirects);
+        });
+    }
+
+    public ngOnDestroy(): void {
+        this.routerSubscription?.unsubscribe();
+    }
 
     /** Returns the latest synchronously-known state. */
     public get currentState(): DevicePreviewState {
@@ -74,22 +95,29 @@ export class DevicePreviewService {
         return this.presetsSubject.value.find(p => p.id === presetId);
     }
 
-    /** Activate device-preview with the given preset and persist the choice. */
+    /**
+     * Activate device-preview with the given preset by writing the preset id
+     * into the URL's `?device=` query parameter. The state is then updated
+     * via the router subscription.
+     *
+     * No-op if the preset id is unknown.
+     */
     public activate(presetId: string): void {
-        const preset = this.findPreset(presetId);
-        if (!preset) {
+        if (!this.findPreset(presetId)) {
             return;
         }
-        this.stateSubject.next({ active: true, presetId });
-        this.persistLastPresetId(presetId);
+        this.updateDeviceQueryParam(presetId);
     }
 
-    /** Turn device-preview off (returns to full-width content-frame). */
+    /**
+     * Turn device-preview off by removing the `?device=` query parameter from
+     * the URL. The state is then updated via the router subscription.
+     */
     public deactivate(): void {
         if (!this.stateSubject.value.active) {
             return;
         }
-        this.stateSubject.next({ active: false, presetId: null });
+        this.updateDeviceQueryParam(null);
     }
 
     /**
@@ -105,30 +133,34 @@ export class DevicePreviewService {
         }
     }
 
-    /** Returns the most recently used preset id, or null. */
-    public getLastUsedPresetId(): string | null {
-        const value = this.localStorage.getForAllUsers(DEVICE_PREVIEW_LAST_PRESET_KEY);
-        return typeof value === 'string' ? value : null;
-    }
+    /* --------------------------------------------------------------------- *
+     * Internal helpers
+     * --------------------------------------------------------------------- */
 
-    /**
-     * Activate the last-used preset if any was persisted; otherwise no-op.
-     * Useful when the user clicks the preview-button without picking a format.
-     */
-    public activateLastUsed(): boolean {
-        const last = this.getLastUsedPresetId();
-        if (last && this.findPreset(last)) {
-            this.activate(last);
-            return true;
+    private syncStateFromUrl(url: string): void {
+        const tree = this.router.parseUrl(url || '');
+        const raw = tree.queryParams?.[DEVICE_PREVIEW_QUERY_PARAM];
+        const presetId = typeof raw === 'string' ? raw : null;
+
+        const next: DevicePreviewState = presetId && this.findPreset(presetId)
+            ? { active: true, presetId }
+            : { active: false, presetId: null };
+
+        const current = this.stateSubject.value;
+        if (current.active === next.active && current.presetId === next.presetId) {
+            return;
         }
-        return false;
+        this.stateSubject.next(next);
     }
 
-    private persistLastPresetId(id: string): void {
-        try {
-            this.localStorage.setForAllUsers(DEVICE_PREVIEW_LAST_PRESET_KEY, id);
-        } catch {
-            // ignore — persistence is a nice-to-have, not critical
+    private updateDeviceQueryParam(presetId: string | null): void {
+        const tree = this.router.parseUrl(this.router.url);
+        if (presetId) {
+            tree.queryParams = { ...tree.queryParams, [DEVICE_PREVIEW_QUERY_PARAM]: presetId };
+        } else {
+            const { [DEVICE_PREVIEW_QUERY_PARAM]: _omit, ...rest } = tree.queryParams || {};
+            tree.queryParams = rest;
         }
+        this.router.navigateByUrl(tree, { replaceUrl: true });
     }
 }

From 34ef9d2f85cbd52cad9a16623709bba345cc5bf4 Mon Sep 17 00:00:00 2001
From: Philipp Doerre <philippdoerre@apps.gentics.com>
Date: Mon, 4 May 2026 11:02:43 +0000
Subject: [PATCH 4/5] style(editor-ui): aspect-ratio + design-token clean-up
 for device-preview
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review feedback issues 3, 5.1 and 5.2.

* aspect-ratio (issue 3): the device-frame now keeps the configured
  device's native aspect ratio when the editor panel is narrower than
  the preset's natural width. Implementation:
  - the --device-w / --device-h CSS custom properties are now bound as
    bare unitless numbers from the template (no .px suffix), so they
    can be used both in CSS aspect-ratio and — multiplied by 1px — in
    width/height
  - SCSS combines aspect-ratio with width: calc(var(--device-w) * 1px)
    and max-width: 100% / max-height: 100%, letting the browser shrink
    the box proportionally when stage size is constrained
  - the inner iframe takes width: 100% / height: 100% of the now
    aspect-locked container, so scrollbars only appear when the page
    content itself overflows the device viewport — not because of the
    container being mis-sized

* design tokens (issue 5.1): hard-coded hex / rgba colors are replaced
  by SCSS variables from libs/ui-core ($gtx-color-primary,
  $gtx-color-very-light-gray, $gtx-color-mid-gray, $gtx-color-dark-gray,
  $gtx-color-very-dark-gray, $gtx-color-light-gray) plus the
  app-level $gtx-color-page-background. Every alpha-tinted value uses
  rgba($gtx-color-…, X) instead of literal channels.

* relative units (issue 5.2): px values converted to rem (1rem = 16px
  is the editor-ui base font size) wherever they describe layout (gap,
  padding, margin, border-radius, font-size, box-shadow). The two
  remaining px values are 1px borders and the 0.5px letter-spacing —
  both intentional pixel-precise design hints.

* the menu-component SCSS now imports the shared "variables" file so
  it has access to $gtx-color-* without needing a per-file import map.
---
 .../content-frame.component.html              |  4 +-
 .../content-frame.component.scss              | 44 ++++++++++++-------
 .../device-preview-menu.component.scss        | 30 +++++++------
 .../editor-toolbar.component.scss             |  6 +--
 4 files changed, 49 insertions(+), 35 deletions(-)

diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html
index 02c78df145..f400bcc3d3 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.html
@@ -94,8 +94,8 @@
         [class.hidden]="editMode === EditMode.EDIT_PROPERTIES || editMode === EditMode.EDIT_INHERITANCE || currentItem?.type === 'form'"
         [class.device-preview-active]="!!devicePreviewActivePreset"
         [attr.data-active-preset]="devicePreviewActivePreset?.id"
-        [style.--device-w.px]="devicePreviewActivePreset?.width"
-        [style.--device-h.px]="devicePreviewActivePreset?.height"
+        [style.--device-w]="devicePreviewActivePreset?.width"
+        [style.--device-h]="devicePreviewActivePreset?.height"
     >
         <gtx-progress-bar
             class="frame-requesting"
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss
index 3e29b18bf7..3f79c4181c 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss
@@ -53,29 +53,41 @@
         // never re-mounted, which preserves Aloha state and the loaded URL.
         &.device-preview-active {
             background:
-                linear-gradient(45deg, rgba(0,0,0,0.04) 25%, transparent 25%) 0 0 / 20px 20px,
-                linear-gradient(-45deg, rgba(0,0,0,0.04) 25%, transparent 25%) 0 10px / 20px 20px,
-                linear-gradient(45deg, transparent 75%, rgba(0,0,0,0.04) 75%) 10px -10px / 20px 20px,
-                linear-gradient(-45deg, transparent 75%, rgba(0,0,0,0.04) 75%) 10px 0 / 20px 20px,
+                linear-gradient(45deg, rgba($gtx-color-mid-gray, 0.18) 25%, transparent 25%) 0 0 / 1.25rem 1.25rem,
+                linear-gradient(-45deg, rgba($gtx-color-mid-gray, 0.18) 25%, transparent 25%) 0 0.625rem / 1.25rem 1.25rem,
+                linear-gradient(45deg, transparent 75%, rgba($gtx-color-mid-gray, 0.18) 75%) 0.625rem -0.625rem / 1.25rem 1.25rem,
+                linear-gradient(-45deg, transparent 75%, rgba($gtx-color-mid-gray, 0.18) 75%) 0.625rem 0 / 1.25rem 1.25rem,
                 $gtx-color-very-light-gray;
-            padding: 16px;
+            padding: 1rem;
             overflow: auto;
             align-items: center;
 
             .frame-language-container {
                 flex: 0 0 auto;
-                width: var(--device-w, 100%);
-                height: var(--device-h, 100%);
+                // Keep the device's native aspect ratio regardless of how
+                // much horizontal/vertical space the editor panel currently
+                // gives us. The CSS variables --device-w / --device-h are
+                // unitless numbers (set as bare numbers from the
+                // ContentFrameComponent template, see [style.--device-w]
+                // bindings) so they can be used both in the ratio and —
+                // multiplied by 1px — as length values.
+                aspect-ratio: var(--device-w) / var(--device-h);
+                width: calc(var(--device-w) * 1px);
+                height: auto;
+                // Cap to the available stage area; the browser shrinks the
+                // box proportionally because of the aspect-ratio rule above.
                 max-width: 100%;
-                background: white;
-                box-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);
-                border-radius: 6px;
+                max-height: 100%;
+                background: $gtx-color-page-background;
+                box-shadow: 0 0.5rem 2rem rgba($gtx-color-very-dark-gray, 0.18);
+                border-radius: 0.375rem;
                 overflow: hidden;
                 transition: width 0.25s ease, height 0.25s ease;
 
                 .frame {
                     flex: 1 1 auto;
                     width: 100%;
+                    height: 100%;
                 }
             }
         }
@@ -93,20 +105,20 @@
             flex: 0 0 auto;
             margin-bottom: 0.5rem;
             background: $gtx-color-primary;
-            color: white;
-            padding: 4px 12px;
+            color: $gtx-color-page-background;
+            padding: 0.25rem 0.75rem;
             border-radius: 999px;
-            font-size: 12px;
+            font-size: 0.75rem;
             font-weight: 500;
             display: inline-flex;
             align-items: center;
-            gap: 8px;
-            box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15);
+            gap: 0.5rem;
+            box-shadow: 0 0.125rem 0.375rem rgba($gtx-color-very-dark-gray, 0.15);
             z-index: 5;
             pointer-events: none;
 
             .device-preview-info-icon {
-                font-size: 16px;
+                font-size: 1rem;
             }
 
             .device-preview-info-size {
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/device-preview-menu/device-preview-menu.component.scss b/cms-ui/apps/editor-ui/src/app/content-frame/components/device-preview-menu/device-preview-menu.component.scss
index 0e842ef325..c13836ec33 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/device-preview-menu/device-preview-menu.component.scss
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/device-preview-menu/device-preview-menu.component.scss
@@ -1,22 +1,24 @@
+@import "variables";
+
 :host {
     display: block;
-    min-width: 240px;
+    min-width: 15rem;
 }
 
 .device-preview-menu {
     .menu-header {
-        padding: 8px 14px 4px 14px;
-        font-size: 11px;
+        padding: 0.5rem 0.875rem 0.25rem 0.875rem;
+        font-size: 0.6875rem;
         font-weight: 600;
         text-transform: uppercase;
         letter-spacing: 0.5px;
-        color: rgba(0, 0, 0, 0.55);
+        color: $gtx-color-dark-gray;
     }
 
     .menu-divider {
         height: 1px;
-        background: rgba(0, 0, 0, 0.08);
-        margin: 4px 0;
+        background: $gtx-color-light-gray;
+        margin: 0.25rem 0;
     }
 
     .device-preview-item,
@@ -30,23 +32,23 @@
         }
 
         .device-size {
-            font-size: 11px;
-            color: rgba(0, 0, 0, 0.55);
-            margin-left: 8px;
+            font-size: 0.6875rem;
+            color: $gtx-color-dark-gray;
+            margin-left: 0.5rem;
             white-space: nowrap;
         }
 
         .device-check {
-            margin-left: 8px;
-            font-size: 16px;
+            margin-left: 0.5rem;
+            font-size: 1rem;
         }
 
         &.is-selected {
-            background: rgba(33, 150, 243, 0.08);
-            color: #1976d2;
+            background: rgba($gtx-color-primary, 0.08);
+            color: $gtx-color-primary;
 
             .device-size {
-                color: rgba(25, 118, 210, 0.7);
+                color: rgba($gtx-color-primary, 0.7);
             }
         }
     }
diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.scss b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.scss
index 75aa9a67e7..7523668cec 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.scss
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/editor-toolbar/editor-toolbar.component.scss
@@ -70,13 +70,13 @@
         &.is-active {
             gtx-button .button-event-wrapper button,
             gtx-button button {
-                background-color: rgba(25, 118, 210, 0.1);
-                color: #1565c0;
+                background-color: rgba($gtx-color-primary, 0.1);
+                color: $gtx-color-primary;
             }
 
             .device-preview-caret {
                 opacity: 1;
-                color: #1565c0;
+                color: $gtx-color-primary;
             }
         }
     }

From 72db37a9ffb6b6e3189a0e17baa75b4d7be9f818 Mon Sep 17 00:00:00 2001
From: Philipp Doerre <philippdoerre@apps.gentics.com>
Date: Mon, 4 May 2026 11:14:40 +0000
Subject: [PATCH 5/5] fix(editor-ui): use $gcms-color-page-background, not
 $gtx-
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The page-background variable is app-scoped and lives under the gcms-
prefix in apps/editor-ui/src/styles/_variables.scss. The previous
spelling $gtx-color-page-background does not exist in libs/ui-core,
which broke the dev-server's sass build:

  Undefined variable.
  > 81 │     background: $gtx-color-page-background;

Fixed in two places (frame-language-container background +
device-preview-info color).
---
 .../components/content-frame/content-frame.component.scss     | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss
index 3f79c4181c..f120598691 100644
--- a/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss
+++ b/cms-ui/apps/editor-ui/src/app/content-frame/components/content-frame/content-frame.component.scss
@@ -78,7 +78,7 @@
                 // box proportionally because of the aspect-ratio rule above.
                 max-width: 100%;
                 max-height: 100%;
-                background: $gtx-color-page-background;
+                background: $gcms-color-page-background;
                 box-shadow: 0 0.5rem 2rem rgba($gtx-color-very-dark-gray, 0.18);
                 border-radius: 0.375rem;
                 overflow: hidden;
@@ -105,7 +105,7 @@
             flex: 0 0 auto;
             margin-bottom: 0.5rem;
             background: $gtx-color-primary;
-            color: $gtx-color-page-background;
+            color: $gcms-color-page-background;
             padding: 0.25rem 0.75rem;
             border-radius: 999px;
             font-size: 0.75rem;