feat: Page Editor UX Phase 1 - live preview, hover mapping, visual layout picker

- PreviewHighlightService + appHighlightSource directive: shared hover/focus bridge between editor fields and the schematic live preview.
- BuilderLivePreviewComponent: in-page schematic homepage render (header/hero/blocks/footer) reading the same bootstrap the sections mutate, highlighting the area matching the active field.
- VisualLayoutPickerComponent: card-based layout picker (ControlValueAccessor, same shape as app-select) replacing the raw layout <select> in homepage-section.
- app-form-field gains optional usedBy/usedByLabel inputs for the "Where is this used?" helper text, wired into aria-describedby.
- Wired homepage/branding/theme sections with highlight sources + usedBy hints; live preview panel shown in project-editor-page for those three sections.
- All new copy added as translation keys (en/ru/hy).

src/app/features/project-editor/components/live-preview/builder-live-preview.component.html

@@ -0,0 +1,56 @@
+@if (bootstrap(); as bootstrap) {
+<div class="builder-live-preview" role="img" [attr.aria-label]="'builder.livePreviewTitle' | translate">
+  <header
+    class="builder-live-preview__header"
+    [class.builder-live-preview__header--active]="isActive('logo') || isActive('title')"
+  >
+    @if (bootstrap.branding.logoUrl) {
+      <img class="builder-live-preview__logo" [class.builder-live-preview__logo--active]="isActive('logo')" [src]="bootstrap.branding.logoUrl" alt="" />
+    } @else {
+      <span class="builder-live-preview__logo builder-live-preview__logo--placeholder" [class.builder-live-preview__logo--active]="isActive('logo')"></span>
+    }
+    <span class="builder-live-preview__title" [class.builder-live-preview__title--active]="isActive('title')">
+      {{ bootstrap.seo.default.title || bootstrap.branding.brandName }}
+    </span>
+  </header>
+
+  <div
+    class="builder-live-preview__hero"
+    [class.builder-live-preview__hero--active]="isActive('background') || isActive('image')"
+    [style.background]="bootstrap.theme.palette.backgroundSecondary"
+  >
+    <span class="builder-live-preview__hero-image" [class.builder-live-preview__hero-image--active]="isActive('image')" aria-hidden="true">
+      <app-icon name="image" [size]="18" />
+    </span>
+    <span
+      class="builder-live-preview__button"
+      [class.builder-live-preview__button--active]="isActive('button') || isActive('color')"
+      [style.background]="bootstrap.theme.palette.primary"
+    >
+      {{ 'builder.livePreviewButtonLabel' | translate }}
+    </span>
+  </div>
+
+  <div
+    class="builder-live-preview__blocks"
+    [class.builder-live-preview__blocks--active]="isActive('layout') || isActive('spacing')"
+  >
+    @for (block of blocks(); track block.id) {
+      <div
+        class="builder-live-preview__block"
+        [class.builder-live-preview__block--hidden]="!block.visible"
+        [class.builder-live-preview__block--active]="isActive('block:' + block.id)"
+        [attr.data-layout]="block.strategy"
+      >
+        <app-icon [name]="block.icon" [size]="14" />
+      </div>
+    } @empty {
+      <p class="builder-live-preview__empty">{{ 'builder.livePreviewEmpty' | translate }}</p>
+    }
+  </div>
+
+  <footer class="builder-live-preview__footer"></footer>
+</div>
+} @else {
+<p class="builder-live-preview__empty">{{ 'builder.livePreviewEmpty' | translate }}</p>
+}

src/app/features/project-editor/components/live-preview/builder-live-preview.component.scss

@@ -0,0 +1,160 @@
+.builder-live-preview {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-xs, 0.25rem);
+  border: 1px solid var(--border-color, #e4e4e7);
+  border-radius: var(--radius-lg, 10px);
+  overflow: hidden;
+  background: var(--bg-primary, #fff);
+}
+
+.builder-live-preview__header {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm, 0.5rem);
+  padding: var(--space-sm, 0.5rem) var(--space-md, 1rem);
+  border-bottom: 1px solid var(--border-color, #e4e4e7);
+  transition: box-shadow var(--transition-fast, 120ms ease);
+}
+
+.builder-live-preview__header--active {
+  box-shadow: inset 0 0 0 2px var(--primary-color, #2f6e5d);
+}
+
+.builder-live-preview__logo {
+  width: 24px;
+  height: 24px;
+  border-radius: var(--radius-sm, 4px);
+  object-fit: contain;
+  transition: outline-color var(--transition-fast, 120ms ease);
+  outline: 2px solid transparent;
+  outline-offset: 2px;
+}
+
+.builder-live-preview__logo--placeholder {
+  background: var(--bg-secondary, #f4f4f5);
+}
+
+.builder-live-preview__logo--active {
+  outline-color: var(--primary-color, #2f6e5d);
+}
+
+.builder-live-preview__title {
+  font-size: var(--font-size-sm, 0.8125rem);
+  font-weight: var(--font-weight-semibold, 600);
+  color: var(--text-primary, #1f322d);
+  border-radius: var(--radius-sm, 4px);
+  transition: box-shadow var(--transition-fast, 120ms ease);
+}
+
+.builder-live-preview__title--active {
+  box-shadow: inset 0 0 0 2px var(--primary-color, #2f6e5d);
+  padding: 0 var(--space-xs, 0.25rem);
+}
+
+.builder-live-preview__hero {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-sm, 0.5rem);
+  padding: var(--space-lg, 1.5rem) var(--space-md, 1rem);
+  transition: box-shadow var(--transition-fast, 120ms ease);
+}
+
+.builder-live-preview__hero--active {
+  box-shadow: inset 0 0 0 2px var(--primary-color, #2f6e5d);
+}
+
+.builder-live-preview__hero-image {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 40px;
+  height: 32px;
+  border-radius: var(--radius-md, 6px);
+  background: var(--bg-primary, #fff);
+  color: var(--text-secondary, #6b7280);
+  outline: 2px solid transparent;
+  outline-offset: 2px;
+}
+
+.builder-live-preview__hero-image--active {
+  outline-color: var(--primary-color, #2f6e5d);
+}
+
+.builder-live-preview__button {
+  padding: var(--space-xs, 0.25rem) var(--space-md, 1rem);
+  border-radius: var(--radius-md, 6px);
+  color: #fff;
+  font-size: var(--font-size-xs, 0.75rem);
+  font-weight: var(--font-weight-semibold, 600);
+  outline: 2px solid transparent;
+  outline-offset: 2px;
+  transition: outline-color var(--transition-fast, 120ms ease);
+}
+
+.builder-live-preview__button--active {
+  outline-color: var(--primary-color, #2f6e5d);
+}
+
+.builder-live-preview__blocks {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-xs, 0.25rem);
+  padding: var(--space-sm, 0.5rem) var(--space-md, 1rem);
+  border-radius: var(--radius-md, 6px);
+  transition: box-shadow var(--transition-fast, 120ms ease);
+}
+
+.builder-live-preview__blocks--active {
+  box-shadow: inset 0 0 0 2px var(--primary-color, #2f6e5d);
+}
+
+.builder-live-preview__block {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 28px;
+  border-radius: var(--radius-sm, 4px);
+  background: var(--bg-secondary, #f4f4f5);
+  color: var(--text-secondary, #6b7280);
+  outline: 2px solid transparent;
+  outline-offset: 2px;
+  transition: outline-color var(--transition-fast, 120ms ease), opacity var(--transition-fast, 120ms ease);
+}
+
+.builder-live-preview__block--hidden {
+  opacity: 0.35;
+}
+
+.builder-live-preview__block--active {
+  outline-color: var(--primary-color, #2f6e5d);
+}
+
+.builder-live-preview__footer {
+  height: 16px;
+  background: var(--bg-secondary, #f4f4f5);
+}
+
+.builder-live-preview__empty {
+  margin: 0;
+  padding: var(--space-md, 1rem);
+  font-size: var(--font-size-sm, 0.8125rem);
+  color: var(--text-secondary, #6b7280);
+  text-align: center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .builder-live-preview__header,
+  .builder-live-preview__logo,
+  .builder-live-preview__title,
+  .builder-live-preview__hero,
+  .builder-live-preview__hero-image,
+  .builder-live-preview__button,
+  .builder-live-preview__blocks,
+  .builder-live-preview__block {
+    transition: none;
+  }
+}

src/app/features/project-editor/components/live-preview/builder-live-preview.component.ts

@@ -0,0 +1,57 @@
+import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
+import { ProjectEditorFacade } from '../../facade/project-editor.facade';
+import { PreviewHighlightService } from '../../../../shared/services/preview-highlight.service';
+import { TranslatePipe } from '../../../../i18n/translate.pipe';
+import { IconComponent } from '../../../../shared/ui/icon/icon.component';
+import { AppIconName } from '../../../../shared/ui/icon/icon-registry';
+
+const BLOCK_ICON_BY_TYPE: Record<string, AppIconName> = {
+  hero: 'image',
+  categories: 'layoutGrid',
+  'product-collection': 'package',
+  'product-carousel': 'images',
+  'recently-viewed': 'history',
+  banner: 'megaphone',
+  partners: 'verified',
+  html: 'code',
+};
+
+/**
+ * Schematic (not pixel-accurate) representation of the storefront homepage,
+ * built from the same bootstrap the section editors mutate. It exists so a
+ * field can highlight "the area it affects" (§ PreviewHighlightService)
+ * without re-navigating away like ProjectEditorPreviewService.preview() does.
+ */
+@Component({
+  selector: 'app-builder-live-preview',
+  standalone: true,
+  imports: [TranslatePipe, IconComponent],
+  templateUrl: './builder-live-preview.component.html',
+  styleUrl: './builder-live-preview.component.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class BuilderLivePreviewComponent {
+  private readonly facade = inject(ProjectEditorFacade);
+  private readonly highlight = inject(PreviewHighlightService);
+
+  readonly bootstrap = this.facade.bootstrap;
+  readonly homepagePage = this.facade.homepagePage;
+  readonly activeHighlight = this.highlight.activeId;
+
+  readonly blocks = computed(() =>
+    [...(this.homepagePage()?.sections ?? [])]
+      .sort((a, b) => a.order - b.order)
+      .map(section => ({
+        id: section.id,
+        type: section.type,
+        strategy: section.layout?.strategy ?? 'stack',
+        columns: section.layout?.columns ?? 1,
+        visible: section.visible !== false,
+        icon: BLOCK_ICON_BY_TYPE[section.type] ?? 'stop',
+      }))
+  );
+
+  isActive(id: string): boolean {
+    return this.activeHighlight() === id;
+  }
+}

src/app/features/project-editor/pages/project-editor-page.component.html

@@ -82,27 +82,36 @@
         <p>{{ 'common.loading' | translate }}</p>
       </section>
     } @else {
-      <section class="project-editor-stack">
-        @if (canResetActiveSection()) {
-          <div class="project-editor-section-actions">
-            <app-button variant="danger" size="sm" (click)="resetActiveSection()">{{ 'builder.resetSection' | translate }}</app-button>
-          </div>
+      <div class="project-editor-work-area" [class.project-editor-work-area--with-preview]="showLivePreview()">
+        <section class="project-editor-stack">
+          @if (canResetActiveSection()) {
+            <div class="project-editor-section-actions">
+              <app-button variant="danger" size="sm" (click)="resetActiveSection()">{{ 'builder.resetSection' | translate }}</app-button>
+            </div>
+          }
+          @switch (activeSection()) {
+            @case ('general') { <app-project-editor-general-section /> }
+            @case ('branding') { <app-project-editor-branding-section /> }
+            @case ('theme') { <app-project-editor-theme-section /> }
+            @case ('header') { <app-project-editor-header-section /> }
+            @case ('footer') { <app-project-editor-footer-section /> }
+            @case ('homepage') { <app-project-editor-homepage-section /> }
+            @case ('widgets') { <app-project-editor-widgets-section /> }
+            @case ('static-pages') { <app-static-pages-editor /> }
+            @case ('features') { <app-project-editor-features-section /> }
+            @case ('languages') { <app-project-editor-languages-section /> }
+            @case ('navigation') { <app-project-editor-navigation-section /> }
+            @case ('preview') { <app-project-editor-preview-section /> }
+          }
+        </section>
+        @if (showLivePreview()) {
+          <aside class="project-editor-live-preview" aria-label="{{ 'builder.livePreviewTitle' | translate }}">
+            <h2 class="project-editor-live-preview__title">{{ 'builder.livePreviewTitle' | translate }}</h2>
+            <p class="project-editor-live-preview__hint">{{ 'builder.livePreviewHint' | translate }}</p>
+            <app-builder-live-preview />
+          </aside>
         }
-        @switch (activeSection()) {
-          @case ('general') { <app-project-editor-general-section /> }
-          @case ('branding') { <app-project-editor-branding-section /> }
-          @case ('theme') { <app-project-editor-theme-section /> }
-          @case ('header') { <app-project-editor-header-section /> }
-          @case ('footer') { <app-project-editor-footer-section /> }
-          @case ('homepage') { <app-project-editor-homepage-section /> }
-          @case ('widgets') { <app-project-editor-widgets-section /> }
-          @case ('static-pages') { <app-static-pages-editor /> }
-          @case ('features') { <app-project-editor-features-section /> }
-          @case ('languages') { <app-project-editor-languages-section /> }
-          @case ('navigation') { <app-project-editor-navigation-section /> }
-          @case ('preview') { <app-project-editor-preview-section /> }
-        }
-      </section>
+      </div>
       <app-project-editor-save-bar />
     }
   </main>

src/app/features/project-editor/pages/project-editor-page.component.scss

@@ -277,6 +277,44 @@
   justify-content: flex-end;
 }
 
+.project-editor-work-area {
+  display: grid;
+  gap: 16px;
+  align-items: start;
+}
+
+.project-editor-work-area--with-preview {
+  grid-template-columns: minmax(0, 1fr) 280px;
+}
+
+@media (max-width: 960px) {
+  .project-editor-work-area--with-preview {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+.project-editor-live-preview {
+  position: sticky;
+  top: var(--space-md, 1rem);
+  padding: var(--space-md, 1rem);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-lg, 10px);
+  background: var(--bg-primary);
+}
+
+.project-editor-live-preview__title {
+  margin: 0 0 var(--space-xs, 0.25rem);
+  font-size: var(--font-size-base, 0.875rem);
+  font-weight: var(--font-weight-semibold, 600);
+  color: var(--text-primary);
+}
+
+.project-editor-live-preview__hint {
+  margin: 0 0 var(--space-sm, 0.5rem);
+  font-size: var(--font-size-xs, 0.75rem);
+  color: var(--text-secondary);
+}
+
 .project-editor-empty {
   min-height: 240px;
   display: grid;

src/app/features/project-editor/pages/project-editor-page.component.ts

@@ -25,6 +25,10 @@ import { StaticPagesEditorComponent } from '../../content-management/components/
 import { ProjectEditorSaveBarComponent } from '../components/save-bar/project-editor-save-bar.component';
 import { EDITOR_SECTION_BOOTSTRAP_KEYS, ProjectEditorSectionId } from '../models/project-editor.model';
 import { BUILDER_GROUPS, SECTION_TO_GROUP } from '../builder/builder-groups.model';
+import { BuilderLivePreviewComponent } from '../components/live-preview/builder-live-preview.component';
+
+/** Sections that currently expose highlight-mapped fields (see HighlightSourceDirective usages) - showing the panel elsewhere would just be an inert, unhighlightable diagram. */
+const SECTIONS_WITH_LIVE_PREVIEW: ProjectEditorSectionId[] = ['branding', 'theme', 'homepage'];
 
 const KNOWN_SECTIONS: ProjectEditorSectionId[] = [
   'general', 'branding', 'theme', 'header', 'footer', 'homepage', 'widgets', 'static-pages', 'features', 'languages', 'navigation', 'preview'
@@ -68,6 +72,7 @@ const SECTION_LABEL_KEYS: Record<ProjectEditorSectionId, string> = {
     IconComponent,
     ButtonComponent,
     ConfirmDialogComponent,
+    BuilderLivePreviewComponent,
   ],
   templateUrl: './project-editor-page.component.html',
   styleUrls: ['./project-editor-page.component.scss'],
@@ -99,6 +104,8 @@ export class ProjectEditorPageComponent {
 
   readonly isModifiedActiveSection = computed(() => this.facade.modifiedSections().has(this.activeSection()));
 
+  readonly showLivePreview = computed(() => SECTIONS_WITH_LIVE_PREVIEW.includes(this.activeSection()));
+
   readonly overviewRoute = computed(() => ['/', this.languageService.currentLanguage(), 'edit']);
 
   /** Persistent escape hatch back to the admin dashboard - section editors previously had no route to the backoffice at all. */

src/app/features/project-editor/sections/branding-section.component.html

@@ -2,7 +2,14 @@
 <app-brand-overview />
 <app-section-card [title]="'builder.branding' | translate">
   <div class="editor-grid two">
-    <app-form-field [label]="'builder.logo' | translate" [hint]="'builder.logoDesc' | translate" [error]="fieldError('branding.logoUrl')">
+    <app-form-field
+      appHighlightSource="logo"
+      [label]="'builder.logo' | translate"
+      [hint]="'builder.logoDesc' | translate"
+      [error]="fieldError('branding.logoUrl')"
+      [usedBy]="[('builder.usedByHeader' | translate), ('builder.usedByFooter' | translate)]"
+      [usedByLabel]="'builder.usedByLabel' | translate"
+    >
       <app-image-field [value]="bootstrap.branding.logoUrl" (valueChange)="updateField('logoUrl', $event)" />
     </app-form-field>
     <app-form-field [label]="'builder.smallLogo' | translate" [hint]="'builder.smallLogoDesc' | translate">
@@ -14,7 +21,14 @@
     <app-form-field [label]="'builder.socialImage' | translate" [hint]="'builder.socialImageDesc' | translate">
       <app-image-field [value]="bootstrap.branding.socialImageUrl || ''" (valueChange)="updateField('socialImageUrl', $event)" />
     </app-form-field>
-    <app-form-field class="full" [label]="'builder.marketplaceTitle' | translate" [hint]="'builder.marketplaceTitleDesc' | translate">
+    <app-form-field
+      class="full"
+      appHighlightSource="title"
+      [label]="'builder.marketplaceTitle' | translate"
+      [hint]="'builder.marketplaceTitleDesc' | translate"
+      [usedBy]="[('builder.usedByHeader' | translate), ('builder.usedBySeo' | translate)]"
+      [usedByLabel]="'builder.usedByLabel' | translate"
+    >
       <app-input [ngModel]="bootstrap.seo.default.title" (ngModelChange)="updateMarketplaceTitle($event)" />
     </app-form-field>
   </div>

src/app/features/project-editor/sections/branding-section.component.ts

@@ -9,13 +9,14 @@ import { ButtonComponent } from '../../../shared/ui/button/button.component';
 import { ImageFieldComponent } from '../../../shared/ui/image-field/image-field.component';
 import { SectionCardComponent } from '../../../shared/ui/section-card/section-card.component';
 import { BrandOverviewComponent } from './brand/brand-overview.component';
+import { HighlightSourceDirective } from '../../../shared/ui/highlight-source/highlight-source.directive';
 
 type BrandingImageField = 'logoUrl' | 'logoCompactUrl' | 'faviconUrl' | 'socialImageUrl';
 
 @Component({
   selector: 'app-project-editor-branding-section',
   standalone: true,
-  imports: [FormsModule, TranslatePipe, InputComponent, FormFieldComponent, ButtonComponent, ImageFieldComponent, SectionCardComponent, BrandOverviewComponent],
+  imports: [FormsModule, TranslatePipe, InputComponent, FormFieldComponent, ButtonComponent, ImageFieldComponent, SectionCardComponent, BrandOverviewComponent, HighlightSourceDirective],
   templateUrl: './branding-section.component.html',
   styleUrls: ['./section.shared.scss'],
   changeDetection: ChangeDetectionStrategy.OnPush

src/app/features/project-editor/sections/homepage-section.component.html

@@ -17,7 +17,7 @@
           <app-icon name="grip" [size]="16" />
         </div>
 
-        <div class="block-card__preview">
+        <div class="block-card__preview" [appHighlightSource]="'block:' + section.id">
           <app-icon [name]="blockIcon(section.type)" [size]="20" />
         </div>
 
@@ -31,20 +31,28 @@
           <p class="block-card__desc">{{ blockDescription(section.type) }}</p>
 
           <div class="editor-grid two compact">
-            <label>
-              <span>{{ 'builder.layoutStrategyLabel' | translate }}</span>
-              <small class="field-desc">{{ layoutStrategyDescKey(section.layout?.strategy || 'stack') | translate }}</small>
-              <select [ngModel]="section.layout?.strategy || 'stack'" (ngModelChange)="updateLayout(section.id, 'strategy', $event)">
-                @for (option of layoutStrategyOptions; track option.value) {
-                  <option [value]="option.value">{{ option.labelKey | translate }}</option>
-                }
-              </select>
-            </label>
-            <label>
-              <span>{{ 'builder.columns' | translate }}</span>
-              <small class="field-desc">{{ 'builder.sectionColumnsDesc' | translate }}</small>
+            <app-form-field
+              appHighlightSource="layout"
+              [label]="'builder.layoutStrategyLabel' | translate"
+              [usedBy]="[blockLabel(section.type)]"
+              [usedByLabel]="'builder.usedByLabel' | translate"
+            >
+              <app-visual-layout-picker
+                [options]="layoutStrategyPickerOptions"
+                [ariaLabel]="'builder.layoutStrategyLabel' | translate"
+                [ngModel]="section.layout?.strategy || 'stack'"
+                (ngModelChange)="updateLayout(section.id, 'strategy', $event)"
+              />
+            </app-form-field>
+            <app-form-field
+              appHighlightSource="spacing"
+              [label]="'builder.columns' | translate"
+              [hint]="'builder.sectionColumnsDesc' | translate"
+              [usedBy]="[blockLabel(section.type)]"
+              [usedByLabel]="'builder.usedByLabel' | translate"
+            >
               <app-input type="number" [ngModel]="section.layout?.columns || 1" (ngModelChange)="updateLayout(section.id, 'columns', $event)" />
-            </label>
+            </app-form-field>
           </div>
         </div>
 

src/app/features/project-editor/sections/homepage-section.component.ts

@@ -13,6 +13,9 @@ import { SectionConfig } from '../../../shared/models/config';
 import { IconComponent } from '../../../shared/ui/icon/icon.component';
 import { AppIconName } from '../../../shared/ui/icon/icon-registry';
 import { ConfirmDialogComponent } from '../../../shared/ui/confirm-dialog/confirm-dialog.component';
+import { FormFieldComponent } from '../../../shared/ui/form-field/form-field.component';
+import { VisualLayoutPickerComponent, VisualLayoutOption } from '../../../shared/ui/visual-layout-picker/visual-layout-picker.component';
+import { HighlightSourceDirective } from '../../../shared/ui/highlight-source/highlight-source.directive';
 
 export interface LayoutStrategyOption {
   value: 'stack' | 'grid' | 'hero' | 'carousel' | 'split';
@@ -45,7 +48,7 @@ const BLOCK_BY_TYPE = new Map(BLOCK_CATALOG.map(entry => [entry.type, entry]));
 @Component({
   selector: 'app-project-editor-homepage-section',
   standalone: true,
-  imports: [DragDropModule, FormsModule, TranslatePipe, InputComponent, SectionCardComponent, ToggleComponent, EmptyStateComponent, HomepageOverviewComponent, IconComponent, ConfirmDialogComponent],
+  imports: [DragDropModule, FormsModule, TranslatePipe, InputComponent, SectionCardComponent, ToggleComponent, EmptyStateComponent, HomepageOverviewComponent, IconComponent, ConfirmDialogComponent, FormFieldComponent, VisualLayoutPickerComponent, HighlightSourceDirective],
   templateUrl: './homepage-section.component.html',
   styleUrls: ['./section.shared.scss', './homepage-section.component.scss'],
   changeDetection: ChangeDetectionStrategy.OnPush
@@ -70,9 +73,21 @@ export class ProjectEditorHomepageSectionComponent {
     { value: 'split', labelKey: 'builder.layoutStrategySplit', descKey: 'builder.layoutStrategySplitDesc' },
   ];
 
-  layoutStrategyDescKey(strategy: string | undefined): string {
-    return this.layoutStrategyOptions.find(option => option.value === strategy)?.descKey ?? '';
-  }
+  /** Card icons for the visual layout picker - purely decorative shorthand for each strategy's shape. */
+  private readonly layoutStrategyIcons: Record<LayoutStrategyOption['value'], AppIconName> = {
+    stack: 'list',
+    grid: 'layoutGrid',
+    hero: 'image',
+    carousel: 'images',
+    split: 'table',
+  };
+
+  readonly layoutStrategyPickerOptions: VisualLayoutOption[] = this.layoutStrategyOptions.map(option => ({
+    value: option.value,
+    labelKey: option.labelKey,
+    descKey: option.descKey,
+    icon: this.layoutStrategyIcons[option.value],
+  }));
 
   blockLabel(type: string): string {
     const entry = BLOCK_BY_TYPE.get(type);

src/app/features/project-editor/sections/theme-section.component.html

@@ -1,9 +1,23 @@
 @if (bootstrap(); as bootstrap) {
 <app-section-card [title]="'builder.theme' | translate">
   <div class="editor-grid two">
-    <app-form-field [label]="'builder.primaryColor' | translate" [hint]="'builder.primaryColorDesc' | translate" [error]="fieldError('theme.palette.primary')"><app-color-picker [ariaLabel]="'builder.primaryColor' | translate" [ngModel]="bootstrap.theme.palette.primary" (ngModelChange)="updatePalette('primary', $event)" /></app-form-field>
+    <app-form-field
+      appHighlightSource="color"
+      [label]="'builder.primaryColor' | translate"
+      [hint]="'builder.primaryColorDesc' | translate"
+      [error]="fieldError('theme.palette.primary')"
+      [usedBy]="[('builder.usedByButtons' | translate), ('builder.usedByLinks' | translate), ('builder.usedByBadges' | translate)]"
+      [usedByLabel]="'builder.usedByLabel' | translate"
+    ><app-color-picker [ariaLabel]="'builder.primaryColor' | translate" [ngModel]="bootstrap.theme.palette.primary" (ngModelChange)="updatePalette('primary', $event)" /></app-form-field>
     <app-form-field [label]="'builder.secondaryColor' | translate" [hint]="'builder.secondaryColorDesc' | translate" [error]="fieldError('theme.palette.secondary')"><app-color-picker [ariaLabel]="'builder.secondaryColor' | translate" [ngModel]="bootstrap.theme.palette.secondary" (ngModelChange)="updatePalette('secondary', $event)" /></app-form-field>
-    <app-form-field [label]="'builder.backgroundColor' | translate" [hint]="'builder.backgroundColorDesc' | translate" [error]="fieldError('theme.palette.backgroundPrimary')"><app-color-picker [ariaLabel]="'builder.backgroundColor' | translate" [ngModel]="bootstrap.theme.palette.backgroundPrimary" (ngModelChange)="updatePalette('backgroundPrimary', $event)" /></app-form-field>
+    <app-form-field
+      appHighlightSource="background"
+      [label]="'builder.backgroundColor' | translate"
+      [hint]="'builder.backgroundColorDesc' | translate"
+      [error]="fieldError('theme.palette.backgroundPrimary')"
+      [usedBy]="[('builder.usedByPageBackground' | translate)]"
+      [usedByLabel]="'builder.usedByLabel' | translate"
+    ><app-color-picker [ariaLabel]="'builder.backgroundColor' | translate" [ngModel]="bootstrap.theme.palette.backgroundPrimary" (ngModelChange)="updatePalette('backgroundPrimary', $event)" /></app-form-field>
     <app-form-field [label]="'builder.surfaceColor' | translate" [hint]="'builder.surfaceColorDesc' | translate" [error]="fieldError('theme.palette.backgroundSecondary')"><app-color-picker [ariaLabel]="'builder.surfaceColor' | translate" [ngModel]="bootstrap.theme.palette.backgroundSecondary" (ngModelChange)="updatePalette('backgroundSecondary', $event)" /></app-form-field>
     <app-form-field [label]="'builder.textColor' | translate" [hint]="'builder.textColorDesc' | translate" [error]="fieldError('theme.palette.textPrimary')"><app-color-picker [ariaLabel]="'builder.textColor' | translate" [ngModel]="bootstrap.theme.palette.textPrimary" (ngModelChange)="updatePalette('textPrimary', $event)" /></app-form-field>
     <app-form-field [label]="'builder.successColor' | translate" [hint]="'builder.successColorDesc' | translate" [error]="fieldError('theme.palette.success')"><app-color-picker [ariaLabel]="'builder.successColor' | translate" [ngModel]="bootstrap.theme.palette.success" (ngModelChange)="updatePalette('success', $event)" /></app-form-field>

src/app/features/project-editor/sections/theme-section.component.ts

@@ -8,6 +8,7 @@ import { FormFieldComponent } from '../../../shared/ui/form-field/form-field.com
 import { SectionCardComponent } from '../../../shared/ui/section-card/section-card.component';
 import { SelectComponent, SelectOption } from '../../../shared/ui/select/select.component';
 import { ColorPickerComponent } from '../../../shared/ui/color-picker/color-picker.component';
+import { HighlightSourceDirective } from '../../../shared/ui/highlight-source/highlight-source.directive';
 
 export interface ThemeModeOption {
   value: 'light' | 'dark' | 'system';
@@ -24,7 +25,7 @@ export interface SiteLayoutOption {
 @Component({
   selector: 'app-project-editor-theme-section',
   standalone: true,
-  imports: [FormsModule, TranslatePipe, FormFieldComponent, SectionCardComponent, SelectComponent, ColorPickerComponent],
+  imports: [FormsModule, TranslatePipe, FormFieldComponent, SectionCardComponent, SelectComponent, ColorPickerComponent, HighlightSourceDirective],
   templateUrl: './theme-section.component.html',
   styleUrls: ['./section.shared.scss'],
   changeDetection: ChangeDetectionStrategy.OnPush