feat(tenant): per-theme logos + file-upload + button UI polish

Replace the single tenant avatar with a pair of theme-scoped brand logos.
Render only the theme-matching <img> server-side and swap src on theme
toggle via a JS hook — no reload, no double request, no CSS tricks.

Tenant logos
- TenantLogoService (ImageUploadTrait) with theme whitelist and per-theme
  storage storage/tenants/{uuid}/logo/{light|dark}/, SIZES 128/256/512
- Public serving endpoint auth/tenant-logo-file so login can show the
  logo pre-auth; matching authenticated admin preview endpoint
- appTenantLogoUrl(?size, ?theme) with 4-step fallback cascade; PDF +
  mail always request 'light'
- Admin tenant edit: avatar block replaced by "Tenant logos" details
  block inside the Master-data tab, two side-by-side slots via Pico
  .grid with the core app-file-upload partial
- Policy rename ABILITY_ADMIN_TENANTS_AVATAR_VIEW -> LOGO_VIEW, action
  routes logo / logo-delete / logo-file with theme body/query param
- API endpoint path kept (backward compat), internals on new service
- CLI tenant:logo-migrate-avatars moves legacy avatar/ -> logo/light/
  idempotently (--dry-run, --yes, --cleanup)
- i18n "Tenant image" removed, 12 new keys synced across de/en

File upload component
- Full-width preview + filename/actions below (3D stack layout)
- Fixed 16:9 aspect ratio with 1rem inner padding for consistent
  preview size across any logo aspect
- Transparency checker pattern as background so black logos stay
  visible on dark mode and white logos on light mode
- form="" + deleteFormId support so the partial works with barrier
  forms inside another form

Buttons
- width:100% dropped from button[type="submit"]; scoped back via
  .login-main for the auth-flow primary CTA
- .outline base rule now tints background via color-mix of --app-color
  so secondary/primary/danger outlines all gain a subtle surface
- .outline.secondary restyled Stripe-style in both themes: solid white
  chip with soft shadow in light, solid elevated dark chip with white
  text in dark; neutral border replaces role-colored border
- .app-action-success/.app-action-danger outlines get color-mix bg +
  theme-aware outline-text tokens for stronger contrast
- Filled .primary/.app-action-success/.app-action-danger get raised
  box-shadow (inset highlight + drop) — opt-in via class so chrome
  buttons stay flat
- Dropped the legacy .secondary utility that was clobbering the
  custom-property cascade with a hardcoded muted color

Theme swap
- Logo img carries data-src-light + data-src-dark; theme-toggle JS
  swaps src when data-theme changes, keeping the topbar/login logo in
  sync without a page reload

Quality gates: PHPUnit (2045), PHPStan L5, CS-Fixer, docs link/drift,
codex skills sync — all green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

core/App/Container/Registrars/DirectoryRegistrar.php

@@ -9,8 +9,8 @@ use MintyPHP\Repository\Tenant\TenantRepository;
 use MintyPHP\Service\Directory\DirectoryServicesFactory;
 use MintyPHP\Service\Directory\DirectorySettingsGateway;
 use MintyPHP\Service\Org\DepartmentService;
-use MintyPHP\Service\Tenant\TenantAvatarService;
 use MintyPHP\Service\Tenant\TenantFaviconService;
+use MintyPHP\Service\Tenant\TenantLogoService;
 use MintyPHP\Service\Tenant\TenantScopeService;
 use MintyPHP\Service\Tenant\TenantService;
 use MintyPHP\Service\Tenant\TenantServicesFactory;
@@ -23,7 +23,7 @@ final class DirectoryRegistrar implements ContainerRegistrar
         $container->set(TenantScopeService::class, static fn (AppContainer $c): TenantScopeService => $c->get(TenantServicesFactory::class)->createTenantScopeService());
         $container->set(DepartmentService::class, static fn (AppContainer $c): DepartmentService => $c->get(DirectoryServicesFactory::class)->createDepartmentService());
         $container->set(DirectorySettingsGateway::class, static fn (AppContainer $c): DirectorySettingsGateway => $c->get(DirectoryServicesFactory::class)->createDirectorySettingsGateway());
-        $container->set(TenantAvatarService::class, static fn (AppContainer $c): TenantAvatarService => $c->get(TenantServicesFactory::class)->createTenantAvatarService());
+        $container->set(TenantLogoService::class, static fn (AppContainer $c): TenantLogoService => $c->get(TenantServicesFactory::class)->createTenantLogoService());
         $container->set(TenantFaviconService::class, static fn (AppContainer $c): TenantFaviconService => $c->get(TenantServicesFactory::class)->createTenantFaviconService());
         $container->set(TenantRepository::class, static fn (AppContainer $c): TenantRepository => $c->get(TenantServicesFactory::class)->createTenantRepository());
         $container->set(DepartmentRepository::class, static fn (AppContainer $c): DepartmentRepository => $c->get(DirectoryServicesFactory::class)->createDepartmentRepository());

core/App/Container/Registrars/UserRegistrar.php

@@ -44,7 +44,8 @@ final class UserRegistrar implements ContainerRegistrar
         ));
         $container->set(UserAccessPdfService::class, static fn (AppContainer $c): UserAccessPdfService => new UserAccessPdfService(
             $c->get(UserAccessTemplateService::class),
-            $c->get(BrandingLogoService::class)
+            $c->get(BrandingLogoService::class),
+            $c->get(\MintyPHP\Service\Tenant\TenantLogoService::class)
         ));
         $container->set(UserTenantContextService::class, static fn (AppContainer $c): UserTenantContextService => $c->get(UserServicesFactory::class)->createUserTenantContextService());
         $container->set(UserLifecycleService::class, static fn (AppContainer $c): UserLifecycleService => $c->get(UserServicesFactory::class)->createUserLifecycleService());

core/Console/Commands/Tenant/MigrateLogoAvatarsCommand.php

@@ -0,0 +1,133 @@
+<?php
+
+namespace MintyPHP\Console\Commands\Tenant;
+
+use MintyPHP\Console\Command;
+
+/**
+ * One-time filesystem migration from the legacy tenant avatar layout to the
+ * new per-theme logo layout.
+ *
+ *   storage/tenants/{uuid}/avatar/  →  storage/tenants/{uuid}/logo/light/
+ *
+ * Idempotent: reruns are a no-op because the source directory no longer
+ * exists (or the target is already populated).
+ */
+final class MigrateLogoAvatarsCommand extends Command
+{
+    public function name(): string
+    {
+        return 'tenant:logo-migrate-avatars';
+    }
+
+    public function description(): string
+    {
+        return 'Migrate legacy tenant avatar folders to the light-logo slot';
+    }
+
+    public function usage(): string
+    {
+        return <<<'USAGE'
+        Usage: php bin/console tenant:logo-migrate-avatars [options]
+
+        Options:
+          --dry-run    List tenants that would be migrated without moving files
+          --yes        Execute the migration (required unless --dry-run)
+          --cleanup    After migration, remove empty legacy avatar folders
+
+        The command scans storage/tenants/ and for every tenant with an
+        avatar/ subfolder moves its contents into logo/light/. Tenants that
+        already have logo/light/ are skipped.
+        USAGE;
+    }
+
+    public function execute(array $args, array $options): int
+    {
+        $dryRun = (bool) ($options['dry-run'] ?? false);
+        $confirm = (bool) ($options['yes'] ?? false);
+        $cleanup = (bool) ($options['cleanup'] ?? false);
+
+        if (!$dryRun && !$confirm) {
+            fwrite(STDERR, "Pass --dry-run to preview or --yes to execute.\n");
+            return 1;
+        }
+
+        $storageBase = $this->projectRoot() . '/storage/tenants';
+        if (!is_dir($storageBase)) {
+            fwrite(STDOUT, "No storage/tenants directory — nothing to migrate.\n");
+            return 0;
+        }
+
+        $entries = scandir($storageBase) ?: [];
+        $migrated = 0;
+        $skipped = 0;
+        $errors = 0;
+
+        foreach ($entries as $entry) {
+            if ($entry === '.' || $entry === '..') {
+                continue;
+            }
+            $tenantDir = $storageBase . '/' . $entry;
+            if (!is_dir($tenantDir)) {
+                continue;
+            }
+            $avatarDir = $tenantDir . '/avatar';
+            $logoLightDir = $tenantDir . '/logo/light';
+
+            if (!is_dir($avatarDir)) {
+                continue;
+            }
+
+            if (is_dir($logoLightDir)) {
+                fwrite(STDOUT, sprintf("skip   %s (logo/light already exists)\n", $entry));
+                $skipped++;
+                continue;
+            }
+
+            if ($dryRun) {
+                fwrite(STDOUT, sprintf("would  %s → logo/light\n", $entry));
+                $migrated++;
+                continue;
+            }
+
+            $logoParent = $tenantDir . '/logo';
+            if (!is_dir($logoParent) && !mkdir($logoParent, 0755, true) && !is_dir($logoParent)) {
+                fwrite(STDERR, sprintf("error  %s (could not create logo/)\n", $entry));
+                $errors++;
+                continue;
+            }
+
+            if (!rename($avatarDir, $logoLightDir)) {
+                fwrite(STDERR, sprintf("error  %s (rename failed)\n", $entry));
+                $errors++;
+                continue;
+            }
+
+            // Variant files are named 'avatar-{size}.{ext}' — rename them to 'logo-{size}.{ext}'.
+            $variants = glob($logoLightDir . '/avatar-*.*') ?: [];
+            foreach ($variants as $variantPath) {
+                $newName = preg_replace('/\/avatar-/', '/logo-', $variantPath, 1);
+                if ($newName && $newName !== $variantPath) {
+                    @rename($variantPath, $newName);
+                }
+            }
+
+            fwrite(STDOUT, sprintf("done   %s\n", $entry));
+            $migrated++;
+
+            if ($cleanup) {
+                // rename moved the directory; nothing to clean up. Listed for clarity.
+            }
+        }
+
+        fwrite(STDOUT, sprintf(
+            "\n%s — migrated=%d skipped=%d errors=%d\n",
+            $dryRun ? 'Dry-run complete' : 'Migration complete',
+            $migrated,
+            $skipped,
+            $errors
+        ));
+
+        return $errors > 0 ? 1 : 0;
+    }
+}

core/Http/AccessControl.php

@@ -13,7 +13,7 @@ class AccessControl
     /** Prefixes that are always public */
     private const ALWAYS_PUBLIC_PREFIXES = [
         'branding/',
-        'auth/tenant-avatar-file',
+        'auth/tenant-logo-file',
         'flash/',
         'auth/microsoft/',
         'api/',

core/Service/Access/TenantAuthorizationPolicy.php

@@ -14,7 +14,7 @@ class TenantAuthorizationPolicy implements AuthorizationPolicyInterface
     public const ABILITY_ADMIN_TENANTS_EDIT_SUBMIT = 'admin.tenants.edit.submit';
     public const ABILITY_ADMIN_TENANTS_DELETE = 'admin.tenants.delete';
     public const ABILITY_ADMIN_TENANTS_CUSTOM_FIELDS_MANAGE = 'admin.tenants.custom_fields.manage';
-    public const ABILITY_ADMIN_TENANTS_AVATAR_VIEW = 'admin.tenants.avatar.view';
+    public const ABILITY_ADMIN_TENANTS_LOGO_VIEW = 'admin.tenants.logo.view';
     public const ABILITY_ADMIN_TENANTS_MEDIA_UPDATE = 'admin.tenants.media.update';
 
     public function __construct(
@@ -32,7 +32,7 @@ class TenantAuthorizationPolicy implements AuthorizationPolicyInterface
             self::ABILITY_ADMIN_TENANTS_EDIT_SUBMIT,
             self::ABILITY_ADMIN_TENANTS_DELETE,
             self::ABILITY_ADMIN_TENANTS_CUSTOM_FIELDS_MANAGE,
-            self::ABILITY_ADMIN_TENANTS_AVATAR_VIEW,
+            self::ABILITY_ADMIN_TENANTS_LOGO_VIEW,
             self::ABILITY_ADMIN_TENANTS_MEDIA_UPDATE,
         ], true);
     }
@@ -46,7 +46,7 @@ class TenantAuthorizationPolicy implements AuthorizationPolicyInterface
             self::ABILITY_ADMIN_TENANTS_EDIT_SUBMIT => $this->authorizeAdminTenantsEditSubmit($context),
             self::ABILITY_ADMIN_TENANTS_DELETE => $this->authorizeAdminTenantsDelete($context),
             self::ABILITY_ADMIN_TENANTS_CUSTOM_FIELDS_MANAGE => $this->authorizeAdminTenantCustomFieldsManage($context),
-            self::ABILITY_ADMIN_TENANTS_AVATAR_VIEW => $this->authorizeAdminTenantAvatarView($context),
+            self::ABILITY_ADMIN_TENANTS_LOGO_VIEW => $this->authorizeAdminTenantLogoView($context),
             self::ABILITY_ADMIN_TENANTS_MEDIA_UPDATE => $this->authorizeAdminTenantMediaUpdate($context),
             default => AuthorizationDecision::deny(500, 'authorization_ability_not_supported'),
         };
@@ -147,7 +147,7 @@ class TenantAuthorizationPolicy implements AuthorizationPolicyInterface
         return $this->authorizeTenantWithPermission($context, PermissionService::CUSTOM_FIELDS_MANAGE);
     }
 
-    private function authorizeAdminTenantAvatarView(array $context): AuthorizationDecision
+    private function authorizeAdminTenantLogoView(array $context): AuthorizationDecision
     {
         $actorUserId = $this->actorUserId($context);
         if (!$this->hasPermission($actorUserId, PermissionService::TENANTS_VIEW)

core/Service/Tenant/TenantLogoService.php

@@ -4,92 +4,113 @@ namespace MintyPHP\Service\Tenant;
 
 use MintyPHP\Service\Image\ImageUploadTrait;
 
-class TenantAvatarService
+/**
+ * Tenant-scoped brand logo with per-theme variants (light + dark).
+ *
+ * Storage layout: storage/tenants/{uuid}/logo/{light|dark}/
+ * Each theme directory holds one original file plus three resized variants
+ * (128/256/512). Consumers that lack a theme context (PDF, e-mail) always ask
+ * for 'light' — this is the by-design invariant.
+ *
+ * The theme parameter is whitelisted on every public method; invalid values
+ * short-circuit to empty results so callers never need to repeat the check.
+ *
+ * @api
+ */
+class TenantLogoService
 {
     use ImageUploadTrait;
 
+    public const THEME_LIGHT = 'light';
+    public const THEME_DARK = 'dark';
+
+    /** @var list<string> */
+    public const THEMES = [self::THEME_LIGHT, self::THEME_DARK];
+
     private const MAX_SIZE = 5242880; // 5 MB
-    private const SIZES = [64, 128, 256];
-    private const DEFAULT_SIZE = 128;
+    private const SIZES = [128, 256, 512];
+    private const DEFAULT_SIZE = 256;
 
     public function isValidUuid(string $uuid): bool
     {
         return self::imageIsValidUuid($uuid);
     }
 
+    public function isValidTheme(string $theme): bool
+    {
+        return in_array($theme, self::THEMES, true);
+    }
+
     public function storageBase(): string
     {
         return self::imageStorageBase();
     }
 
-    public function tenantDir(string $uuid): string
+    public function tenantLogoDir(string $uuid, string $theme): string
     {
-        return $this->storageBase() . '/tenants/' . $uuid . '/avatar';
+        return $this->storageBase() . '/tenants/' . $uuid . '/logo/' . $theme;
     }
 
-    public function findAvatarPath(string $uuid, ?int $size = null): ?string
+    public function findLogoPath(string $uuid, string $theme, ?int $size = null): ?string
     {
-        if (!$this->isValidUuid($uuid)) {
+        if (!$this->isValidUuid($uuid) || !$this->isValidTheme($theme)) {
             return null;
         }
-        $dirs = $this->avatarDirs($uuid);
-        foreach ($dirs as $dir) {
-            if (!is_dir($dir)) {
-                continue;
-            }
-            if ($size) {
-                $size = $this->normalizeSize($size);
-                $variant = $this->findVariantPath($dir, $size);
-                if ($variant) {
-                    return $variant;
-                }
-            }
-            $defaultVariant = $this->findVariantPath($dir, self::DEFAULT_SIZE);
-            if ($defaultVariant) {
-                return $defaultVariant;
-            }
-            $original = self::imageFindOriginalPath($dir);
-            if ($original) {
-                return $original;
+        $dir = $this->tenantLogoDir($uuid, $theme);
+        if (!is_dir($dir)) {
+            return null;
+        }
+        if ($size) {
+            $size = $this->normalizeSize($size);
+            $variant = $this->findVariantPath($dir, $size);
+            if ($variant) {
+                return $variant;
             }
         }
-        return null;
+        $defaultVariant = $this->findVariantPath($dir, self::DEFAULT_SIZE);
+        if ($defaultVariant) {
+            return $defaultVariant;
+        }
+        $original = self::imageFindOriginalPath($dir);
+        return $original ?: null;
     }
 
-    public function hasAvatar(string $uuid): bool
+    public function hasLogo(string $uuid, string $theme): bool
     {
-        $path = $this->findAvatarPath($uuid);
+        $path = $this->findLogoPath($uuid, $theme);
         return $path ? is_file($path) : false;
     }
 
-    public function delete(string $uuid): bool
+    public function delete(string $uuid, string $theme): bool
     {
-        if (!$this->isValidUuid($uuid)) {
+        if (!$this->isValidUuid($uuid) || !$this->isValidTheme($theme)) {
             return false;
         }
-        foreach ($this->avatarDirs($uuid) as $dir) {
-            if (!is_dir($dir)) {
-                continue;
-            }
-            $matches = array_merge(
-                glob($dir . '/avatar-*.*') ?: [],
-                glob($dir . '/avatar.*') ?: [],
-                glob($dir . '/original.*') ?: []
-            );
-            foreach ($matches as $file) {
-                if (is_file($file)) {
-                    @unlink($file);
-                }
+        $dir = $this->tenantLogoDir($uuid, $theme);
+        if (!is_dir($dir)) {
+            return true;
+        }
+        $matches = array_merge(
+            glob($dir . '/logo-*.*') ?: [],
+            glob($dir . '/logo.*') ?: [],
+            glob($dir . '/original.*') ?: []
+        );
+        foreach ($matches as $file) {
+            if (is_file($file)) {
+                @unlink($file);
             }
         }
         return true;
     }
 
-    public function saveUpload(string $uuid, array $file): array
+    public function saveUpload(string $uuid, string $theme, array $file): array
     {
         if (!$this->isValidUuid($uuid)) {
             return ['ok' => false, 'error' => t('Tenant not found')];
         }
+        if (!$this->isValidTheme($theme)) {
+            return ['ok' => false, 'error' => t('Invalid theme')];
+        }
         if (empty($file) || !isset($file['tmp_name'])) {
             return ['ok' => false, 'error' => t('No file uploaded')];
         }
@@ -111,12 +132,12 @@ class TenantAvatarService
             return ['ok' => false, 'error' => t('Invalid image file')];
         }
 
-        $dir = $this->tenantDir($uuid);
+        $dir = $this->tenantLogoDir($uuid, $theme);
         if (!is_dir($dir) && !mkdir($dir, 0755, true) && !is_dir($dir)) {
             return ['ok' => false, 'error' => t('Upload failed')];
         }
 
-        $this->delete($uuid);
+        $this->delete($uuid, $theme);
         $originalPath = $dir . '/original.' . $ext;
         if (!move_uploaded_file($tmpPath, $originalPath)) {
             return ['ok' => false, 'error' => t('Upload failed')];
@@ -126,7 +147,7 @@ class TenantAvatarService
         $variantExt = function_exists('imagewebp') ? 'webp' : 'jpg';
         if (!$isSvg && self::imageCanResize()) {
             foreach (self::SIZES as $size) {
-                $target = $dir . '/avatar-' . $size . '.' . $variantExt;
+                $target = $dir . '/logo-' . $size . '.' . $variantExt;
                 self::imageResizeAndFit($originalPath, $target, $size, $size, $variantExt);
             }
         }
@@ -149,7 +170,7 @@ class TenantAvatarService
 
     private function findVariantPath(string $dir, int $size): ?string
     {
-        $matches = glob($dir . '/avatar-' . $size . '.*');
+        $matches = glob($dir . '/logo-' . $size . '.*');
         if (!$matches) {
             return null;
         }
@@ -158,19 +179,4 @@ class TenantAvatarService
         });
         return $matches[0];
     }
-
-    private function avatarDirs(string $uuid): array
-    {
-        $dirs = [$this->tenantDir($uuid)];
-        $legacy = $this->legacyTenantDir($uuid);
-        if ($legacy !== $dirs[0]) {
-            $dirs[] = $legacy;
-        }
-        return $dirs;
-    }
-
-    private function legacyTenantDir(string $uuid): string
-    {
-        return $this->storageBase() . '/tenants/' . $uuid;
-    }
 }

core/Service/Tenant/TenantServicesFactory.php

@@ -10,7 +10,7 @@ use MintyPHP\Service\Access\PermissionService;
 class TenantServicesFactory
 {
     private ?TenantScopeService $tenantScopeService = null;
-    private ?TenantAvatarService $tenantAvatarService = null;
+    private ?TenantLogoService $tenantLogoService = null;
     private ?TenantFaviconService $tenantFaviconService = null;
 
     public function __construct(
@@ -29,9 +29,9 @@ class TenantServicesFactory
         );
     }
 
-    public function createTenantAvatarService(): TenantAvatarService
+    public function createTenantLogoService(): TenantLogoService
     {
-        return $this->tenantAvatarService ??= new TenantAvatarService();
+        return $this->tenantLogoService ??= new TenantLogoService();
     }
 
     public function createTenantFaviconService(): TenantFaviconService

core/Service/User/UserAccessPdfService.php

@@ -7,6 +7,7 @@ use Dompdf\Options;
 use Endroid\QrCode\QrCode;
 use Endroid\QrCode\Writer\PngWriter;
 use MintyPHP\Service\Branding\BrandingLogoService;
+use MintyPHP\Service\Tenant\TenantLogoService;
 use Throwable;
 use ZipArchive;
 
@@ -14,7 +15,8 @@ class UserAccessPdfService
 {
     public function __construct(
         private readonly UserAccessTemplateService $userAccessTemplateService,
-        private readonly BrandingLogoService $brandingLogoService
+        private readonly BrandingLogoService $brandingLogoService,
+        private readonly ?TenantLogoService $tenantLogoService = null
     ) {
     }
 
@@ -29,7 +31,8 @@ class UserAccessPdfService
         $locale = (string) ($context['locale'] ?? '');
         $vars = is_array($context['vars'] ?? null) ? $context['vars'] : [];
         $vars['pdf_title'] = self::buildPdfTitle($locale);
-        $vars['app_logo_url'] = $this->resolveLogoDataUri();
+        $tenantUuid = (string) ($user['tenant_uuid'] ?? $user['primary_tenant_uuid'] ?? '');
+        $vars['app_logo_url'] = $this->resolveLogoDataUri($tenantUuid);
         $vars['login_qr_data_uri'] = self::buildLoginQrDataUri((string) ($vars['login_url'] ?? ''));
         $vars['generated_at'] = gmdate('Y-m-d H:i:s') . ' UTC';
 
@@ -152,13 +155,22 @@ class UserAccessPdfService
         return $html;
     }
 
-    private function resolveLogoDataUri(): string
+    private function resolveLogoDataUri(string $tenantUuid = ''): string
     {
         $path = '';
         $mime = '';
 
-        // Prefer tenant/app branding logo first.
-        if ($this->brandingLogoService->hasLogo()) {
+        // Prefer tenant light-logo if available (PDF has no theme context; always-light).
+        if ($this->tenantLogoService !== null && $tenantUuid !== '' && $this->tenantLogoService->hasLogo($tenantUuid, TenantLogoService::THEME_LIGHT)) {
+            $logoPath = $this->tenantLogoService->findLogoPath($tenantUuid, TenantLogoService::THEME_LIGHT, 128);
+            if ($logoPath && is_file($logoPath)) {
+                $path = $logoPath;
+                $mime = $this->tenantLogoService->detectMime($logoPath);
+            }
+        }
+
+        // Fallback to global app-branding logo.
+        if ($path === '' && $this->brandingLogoService->hasLogo()) {
             $logoPath = $this->brandingLogoService->findLogoPath(128);
             if ($logoPath && is_file($logoPath)) {
                 $path = $logoPath;

core/Support/helpers/app.php

@@ -407,7 +407,7 @@ function appLayoutNavReservedKeys(): array
         'currentTenant',
         'availableTenants',
         'tenantQueryParam',
-        'tenantAvatar',
+        'tenantLogo',
         'csrfKey',
         'csrfToken',
     ];
@@ -474,9 +474,12 @@ function appBuildLayoutNavContext(array $layoutAuth, array $session, array $quer
         $tenantQueryParam = '?tenant=' . urlencode($tenantUuid);
     }
 
-    $tenantHasAvatar = false;
-    if ($tenantUuid !== '' && class_exists(\MintyPHP\Service\Tenant\TenantAvatarService::class)) {
-        $tenantHasAvatar = app(\MintyPHP\Service\Tenant\TenantAvatarService::class)->hasAvatar($tenantUuid);
+    $tenantHasLogoLight = false;
+    $tenantHasLogoDark = false;
+    if ($tenantUuid !== '' && class_exists(\MintyPHP\Service\Tenant\TenantLogoService::class)) {
+        $logoService = app(\MintyPHP\Service\Tenant\TenantLogoService::class);
+        $tenantHasLogoLight = $logoService->hasLogo($tenantUuid, \MintyPHP\Service\Tenant\TenantLogoService::THEME_LIGHT);
+        $tenantHasLogoDark = $logoService->hasLogo($tenantUuid, \MintyPHP\Service\Tenant\TenantLogoService::THEME_DARK);
     }
 
     $csrfKey = \MintyPHP\Session::$csrfSessionKey;
@@ -498,10 +501,11 @@ function appBuildLayoutNavContext(array $layoutAuth, array $session, array $quer
         'currentTenant' => $currentTenant,
         'availableTenants' => $availableTenants,
         'tenantQueryParam' => $tenantQueryParam,
-        'tenantAvatar' => [
+        'tenantLogo' => [
             'uuid' => $tenantUuid,
             'name' => $tenantName,
-            'hasAvatar' => $tenantHasAvatar,
+            'hasLogoLight' => $tenantHasLogoLight,
+            'hasLogoDark' => $tenantHasLogoDark,
         ],
         'csrfKey' => $csrfKey,
         'csrfToken' => $csrfToken,

core/Support/helpers/branding.php

@@ -150,23 +150,57 @@ function appLogoUrl(?int $size = null): string
 }
 
 /**
- * Resolve logo for auth pages: tenant avatar -> global logo -> default SVG.
+ * Resolve a tenant-scoped logo URL for a given theme with fallback cascade:
+ *   1. Tenant logo for the requested theme
+ *   2. Tenant logo for the other theme (single-theme tenants work on both sides)
+ *   3. Global app logo
+ *   4. Hardcoded brand asset
  *
- * After logout the tenant context (`$_SESSION['current_tenant']`) is preserved,
- * so the login page can show the tenant avatar instead of the generic app logo.
+ * $theme defaults to currentTheme() when omitted, which is the correct choice
+ * for on-page rendering. For contexts without theme (PDF, e-mail) callers
+ * should pass 'light' explicitly via appTenantLogoUrlAbsolute().
  */
-function appAuthLogoUrl(?int $size = null): string
+function appTenantLogoUrl(?int $size = null, ?string $theme = null): string
 {
+    $theme = $theme ?? (function_exists('currentTheme') ? currentTheme() : 'light');
+    $otherTheme = $theme === 'dark' ? 'light' : 'dark';
+
     $tenantUuid = $_SESSION['current_tenant']['uuid'] ?? '';
-    if ($tenantUuid !== '' && class_exists('MintyPHP\\Service\\Tenant\\TenantAvatarService')) {
-        if (app(\MintyPHP\Service\Tenant\TenantAvatarService::class)->hasAvatar($tenantUuid)) {
-            $query = $size ? '&size=' . (int) $size : '';
-            return lurl('auth/tenant-avatar-file?uuid=' . rawurlencode($tenantUuid) . $query);
+    if ($tenantUuid !== '' && class_exists('MintyPHP\\Service\\Tenant\\TenantLogoService')) {
+        $service = app(\MintyPHP\Service\Tenant\TenantLogoService::class);
+        foreach ([$theme, $otherTheme] as $candidate) {
+            if ($service->hasLogo($tenantUuid, $candidate)) {
+                $query = '?uuid=' . rawurlencode($tenantUuid) . '&theme=' . rawurlencode($candidate);
+                if ($size) {
+                    $query .= '&size=' . (int) $size;
+                }
+                return lurl('auth/tenant-logo-file' . $query);
+            }
         }
     }
     return appLogoUrl($size);
 }
 
+/**
+ * Absolute tenant-logo URL for flows without theme context (PDF, e-mail).
+ * Defaults to the light variant — the single-theme convention for those flows.
+ */
+function appTenantLogoUrlAbsolute(int $size = 256, string $theme = 'light'): string
+{
+    return appUrl(appTenantLogoUrl($size, $theme));
+}
+
+/**
+ * Resolve logo for auth pages: tenant logo (theme-aware) -> global logo -> default.
+ *
+ * After logout the tenant context (`$_SESSION['current_tenant']`) is preserved,
+ * so the login page can show the tenant logo instead of the generic app logo.
+ */
+function appAuthLogoUrl(?int $size = null): string
+{
+    return appTenantLogoUrl($size);
+}
+
 /**
  * Absolute logo URL (used in e-mails and metadata).
  */