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>

config/assets.php

@@ -18,6 +18,7 @@ return [
                 'css/components/app-brand.css',
                 'css/components/app-file-upload.css',
                 'css/components/app-footer.css',
+                'css/components/app-tenant-logo.css',
             ],
             'core' => [
                 'css/core.css',

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 SIZES = [128, 256, 512];
-    private const DEFAULT_SIZE = 128;
+    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);
+        $dir = $this->tenantLogoDir($uuid, $theme);
-        foreach ($dirs as $dir) {
+        if (!is_dir($dir)) {
-            if (!is_dir($dir)) {
+            return null;
-                continue;
+        }
-            }
+        if ($size) {
-            if ($size) {
+            $size = $this->normalizeSize($size);
-                $size = $this->normalizeSize($size);
+            $variant = $this->findVariantPath($dir, $size);
-                $variant = $this->findVariantPath($dir, $size);
+            if ($variant) {
-                if ($variant) {
+                return $variant;
-                    return $variant;
-                }
-            }
-            $defaultVariant = $this->findVariantPath($dir, self::DEFAULT_SIZE);
-            if ($defaultVariant) {
-                return $defaultVariant;
-            }
-            $original = self::imageFindOriginalPath($dir);
-            if ($original) {
-                return $original;
             }
         }
-        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) {
+        $dir = $this->tenantLogoDir($uuid, $theme);
-            if (!is_dir($dir)) {
+        if (!is_dir($dir)) {
-                continue;
+            return true;
-            }
+        }
-            $matches = array_merge(
+        $matches = array_merge(
-                glob($dir . '/avatar-*.*') ?: [],
+            glob($dir . '/logo-*.*') ?: [],
-                glob($dir . '/avatar.*') ?: [],
+            glob($dir . '/logo.*') ?: [],
-                glob($dir . '/original.*') ?: []
+            glob($dir . '/original.*') ?: []
-            );
+        );
-            foreach ($matches as $file) {
+        foreach ($matches as $file) {
-                if (is_file($file)) {
+            if (is_file($file)) {
-                    @unlink($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.
+        // Prefer tenant light-logo if available (PDF has no theme context; always-light).
-        if ($this->brandingLogoService->hasLogo()) {
+        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;
+    $tenantHasLogoLight = false;
-    if ($tenantUuid !== '' && class_exists(\MintyPHP\Service\Tenant\TenantAvatarService::class)) {
+    $tenantHasLogoDark = false;
-        $tenantHasAvatar = app(\MintyPHP\Service\Tenant\TenantAvatarService::class)->hasAvatar($tenantUuid);
+    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,
+ * $theme defaults to currentTheme() when omitted, which is the correct choice
- * so the login page can show the tenant avatar instead of the generic app logo.
+ * 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 ($tenantUuid !== '' && class_exists('MintyPHP\\Service\\Tenant\\TenantLogoService')) {
-        if (app(\MintyPHP\Service\Tenant\TenantAvatarService::class)->hasAvatar($tenantUuid)) {
+        $service = app(\MintyPHP\Service\Tenant\TenantLogoService::class);
-            $query = $size ? '&size=' . (int) $size : '';
+        foreach ([$theme, $otherTheme] as $candidate) {
-            return lurl('auth/tenant-avatar-file?uuid=' . rawurlencode($tenantUuid) . $query);
+            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).
  */

i18n/default_de.json

@@ -322,6 +322,18 @@
   "Upload logo": "Logo hochladen",
   "Logo updated": "Logo aktualisiert",
   "Logo removed": "Logo entfernt",
+  "Tenant logos": "Mandanten-Logos",
+  "Light logo": "Logo (hell)",
+  "Dark logo": "Logo (dunkel)",
+  "Upload light logo": "Helles Logo hochladen",
+  "Upload dark logo": "Dunkles Logo hochladen",
+  "Delete light logo": "Helles Logo löschen",
+  "Delete dark logo": "Dunkles Logo löschen",
+  "No logo for this theme yet": "Für dieses Theme wurde noch kein Logo hochgeladen",
+  "Delete this logo?": "Dieses Logo löschen?",
+  "Invalid theme": "Ungültiges Theme",
+  "Logo": "Logo",
+  "Remove": "Entfernen",
   "Allowed file types: SVG, PNG, JPG, WEBP": "Erlaubte Dateitypen: SVG, PNG, JPG, WEBP",
   "Favicon": "Favicon",
   "Upload favicon": "Favicon hochladen",
@@ -462,7 +474,6 @@
   "Tenant can not be deleted while departments are assigned": "Mandant kann nicht gelöscht werden, solange Abteilungen zugewiesen sind",
   "Tenant can not be created": "Mandant kann nicht erstellt werden",
   "Tenant can not be updated": "Mandant kann nicht aktualisiert werden",
-  "Tenant image": "Mandantenbild",
   "Assigned tenants": "Zugewiesene Mandanten",
   "Assigned tenant": "Zugewiesener Mandant",
   "Primary tenant": "Hauptmandant",

i18n/default_en.json

@@ -322,6 +322,18 @@
   "Upload logo": "Upload logo",
   "Logo updated": "Logo updated",
   "Logo removed": "Logo removed",
+  "Tenant logos": "Tenant logos",
+  "Light logo": "Light logo",
+  "Dark logo": "Dark logo",
+  "Upload light logo": "Upload light logo",
+  "Upload dark logo": "Upload dark logo",
+  "Delete light logo": "Delete light logo",
+  "Delete dark logo": "Delete dark logo",
+  "No logo for this theme yet": "No logo for this theme yet",
+  "Delete this logo?": "Delete this logo?",
+  "Invalid theme": "Invalid theme",
+  "Logo": "Logo",
+  "Remove": "Remove",
   "Allowed file types: SVG, PNG, JPG, WEBP": "Allowed file types: SVG, PNG, JPG, WEBP",
   "Favicon": "Favicon",
   "Upload favicon": "Upload favicon",
@@ -462,7 +474,6 @@
   "Tenant can not be deleted while departments are assigned": "Tenant can not be deleted while departments are assigned",
   "Tenant can not be created": "Tenant can not be created",
   "Tenant can not be updated": "Tenant can not be updated",
-  "Tenant image": "Tenant image",
   "Assigned tenants": "Assigned tenants",
   "Assigned tenant": "Assigned tenant",
   "Primary tenant": "Primary tenant",

pages/admin/tenants/_form.phtml

@@ -210,6 +210,31 @@ $openOverrideCard = $detailsOpenAll;
         </label>
       </div>
       <hr>
+      <details name="tenant-master-branding" <?php e($detailsOpenAll ? 'open' : ''); ?>>
+        <summary><?php e(t('Tenant logos')); ?></summary>
+        <hr>
+        <div class="grid">
+          <?php
+          $logoTheme = 'light';
+          $hasLogo = $hasLogoLight ?? false;
+          $fieldLabel = t('Light logo');
+          $uploadFormId = 'tenant-logo-light-form';
+          $deleteFormId = 'tenant-logo-light-delete-form';
+          $canUpdate = $canUpdateTenant;
+          require templatePath('partials/tenant-logo-upload.phtml');
+          ?>
+          <?php
+          $logoTheme = 'dark';
+          $hasLogo = $hasLogoDark ?? false;
+          $fieldLabel = t('Dark logo');
+          $uploadFormId = 'tenant-logo-dark-form';
+          $deleteFormId = 'tenant-logo-dark-delete-form';
+          $canUpdate = $canUpdateTenant;
+          require templatePath('partials/tenant-logo-upload.phtml');
+          ?>
+        </div>
+      </details>
+      <hr>
       <details name="tenant-master-contact" <?php e($detailsOpenAll ? 'open' : ''); ?>>
         <summary><?php e(t('Contact')); ?></summary>
         <hr>

pages/admin/tenants/avatar-file(none).phtml

@@ -1,4 +0,0 @@
-<?php
-
-http_response_code(404);
-return;

pages/admin/tenants/data().php

@@ -19,11 +19,11 @@ $order = $filters['order'];
 $dir = $filters['dir'];
 $computedOrderKeys = ['users'];
 $userTenantRepository = app(\MintyPHP\Repository\Tenant\UserTenantRepository::class);
-$tenantAvatarService = app(\MintyPHP\Service\Tenant\TenantAvatarService::class);
+$tenantLogoService = app(\MintyPHP\Service\Tenant\TenantLogoService::class);
 $settingsDefaultsGateway = app(\MintyPHP\Service\Settings\SettingsDefaultsGateway::class);
 
 $gridUserCountEnricher = app(\MintyPHP\Service\Data\GridUserCountEnricher::class);
-$fetchRows = static function (array $tenantRows) use ($userTenantRepository, $tenantAvatarService, $settingsDefaultsGateway, $gridUserCountEnricher): array {
+$fetchRows = static function (array $tenantRows) use ($userTenantRepository, $tenantLogoService, $settingsDefaultsGateway, $gridUserCountEnricher): array {
     $userCounts = $gridUserCountEnricher->computeCounts(
         $tenantRows,
         $userTenantRepository->countUsersByTenantIds(...),
@@ -47,7 +47,10 @@ $fetchRows = static function (array $tenantRows) use ($userTenantRepository, $te
             'status_badge' => $tenantStatus->badgeVariant(),
             'status_label' => t($tenantStatus->labelToken()),
             'total_users' => $counts['active_users'] + $counts['inactive_users'],
-            'has_avatar' => $tenantUuid !== '' && $tenantAvatarService->hasAvatar($tenantUuid),
+            'has_logo' => $tenantUuid !== '' && (
+                $tenantLogoService->hasLogo($tenantUuid, \MintyPHP\Service\Tenant\TenantLogoService::THEME_LIGHT)
+                || $tenantLogoService->hasLogo($tenantUuid, \MintyPHP\Service\Tenant\TenantLogoService::THEME_DARK)
+            ),
         ];
     }
 

pages/admin/tenants/edit(default).phtml

@@ -16,11 +16,12 @@ $canManageCustomFields = (bool) ($pageAuth['can_manage_custom_fields'] ?? false)
 $canManageSso = (bool) ($pageAuth['can_manage_sso'] ?? false);
 $isReadOnly = !$canUpdateTenant;
 $titleText = $isReadOnly ? t('View tenant') : t('Edit tenant');
-$avatarUuid = (string) ($values['uuid'] ?? '');
+$tenantUuid = (string) ($values['uuid'] ?? '');
-$tenantAvatarService = app(\MintyPHP\Service\Tenant\TenantAvatarService::class);
+$tenantLogoService = app(\MintyPHP\Service\Tenant\TenantLogoService::class);
 $tenantFaviconService = app(\MintyPHP\Service\Tenant\TenantFaviconService::class);
-$hasAvatar = $avatarUuid !== '' && $tenantAvatarService->hasAvatar($avatarUuid);
+$hasLogoLight = $tenantUuid !== '' && $tenantLogoService->hasLogo($tenantUuid, \MintyPHP\Service\Tenant\TenantLogoService::THEME_LIGHT);
-$hasFavicon = $avatarUuid !== '' && $tenantFaviconService->hasFavicon($avatarUuid);
+$hasLogoDark = $tenantUuid !== '' && $tenantLogoService->hasLogo($tenantUuid, \MintyPHP\Service\Tenant\TenantLogoService::THEME_DARK);
+$hasFavicon = $tenantUuid !== '' && $tenantFaviconService->hasFavicon($tenantUuid);
 
 ?>
 
@@ -55,6 +56,29 @@ $hasFavicon = $avatarUuid !== '' && $tenantFaviconService->hasFavicon($avatarUui
     require templatePath('partials/app-details-validation-summary.phtml');
     ?>
 
+    <?php if ($canUpdateTenant && $tenantUuid !== ''): ?>
+      <form id="tenant-logo-light-form" method="post"
+        action="admin/tenants/logo/<?php e($tenantUuid); ?>" enctype="multipart/form-data" hidden>
+        <input type="hidden" name="theme" value="light">
+        <?php Session::getCsrfInput(); ?>
+      </form>
+      <form id="tenant-logo-dark-form" method="post"
+        action="admin/tenants/logo/<?php e($tenantUuid); ?>" enctype="multipart/form-data" hidden>
+        <input type="hidden" name="theme" value="dark">
+        <?php Session::getCsrfInput(); ?>
+      </form>
+      <form id="tenant-logo-light-delete-form" method="post"
+        action="admin/tenants/logo-delete/<?php e($tenantUuid); ?>" hidden>
+        <input type="hidden" name="theme" value="light">
+        <?php Session::getCsrfInput(); ?>
+      </form>
+      <form id="tenant-logo-dark-delete-form" method="post"
+        action="admin/tenants/logo-delete/<?php e($tenantUuid); ?>" hidden>
+        <input type="hidden" name="theme" value="dark">
+        <?php Session::getCsrfInput(); ?>
+      </form>
+    <?php endif; ?>
+
     <?php
     $detailsOpenAll = false;
     $isReadOnly = $isReadOnly ?? false;
@@ -83,45 +107,11 @@ $hasFavicon = $avatarUuid !== '' && $tenantFaviconService->hasFavicon($avatarUui
   </section>
   <aside id="app-details-aside-section">
     <div class="app-details-aside-section">
-      <div class="entity-avatar-block avatar-size-auto avatar-borderless">
-        <?php if ($hasAvatar): ?>
-          <a data-fslightbox="tenant-avatar" href="admin/tenants/avatar-file?uuid=<?php e($avatarUuid); ?>&size=256">
-            <img class="entity-avatar-image" src="admin/tenants/avatar-file?uuid=<?php e($avatarUuid); ?>&size=128"
-              alt="<?php e(t('Tenant image')); ?>">
-          </a>
-        <?php endif; ?>
-      </div>
       <hgroup>
         <h2><?php e($values['description'] ?? ''); ?></h2>
         <p><?php e(t('Tenant')); ?></p>
       </hgroup>
       <hr>
-      <?php if ($canUpdateTenant): ?>
-        <details name="tenant-avatar">
-          <summary>
-            <?php e(t('Upload image')); ?>
-          </summary>
-          <hr>
-          <form class="user-avatar-form" method="post" action="admin/tenants/avatar/<?php e($avatarUuid); ?>"
-            enctype="multipart/form-data">
-            <?php
-            $fileUpload = [
-                'name' => 'avatar',
-                'accept' => 'image/*',
-                'hint' => t('Allowed file types: SVG, PNG, JPG, WEBP'),
-                'currentSrc' => $hasAvatar ? 'admin/tenants/avatar-file?uuid=' . $avatarUuid . '&size=128' : '',
-                'deleteAction' => $hasAvatar ? 'admin/tenants/avatar-delete/' . $avatarUuid : '',
-            ];
-            require templatePath('partials/app-file-upload.phtml');
-            ?>
-            <button type="submit" class="app-action-success">
-              <?php e(t('Save')); ?>
-            </button>
-            <?php Session::getCsrfInput(); ?>
-          </form>
-        </details>
-      <?php endif; ?>
-      <hr>
       <?php if ($canUpdateTenant): ?>
         <details name="tenant-favicon">
           <summary>
@@ -130,16 +120,16 @@ $hasFavicon = $avatarUuid !== '' && $tenantFaviconService->hasFavicon($avatarUui
           <hr>
           <small><?php e(t('Square images are recommended (icons are center-cropped).')); ?></small>
           <hr>
-          <form class="user-avatar-form" method="post" action="admin/tenants/favicon/<?php e($avatarUuid); ?>"
+          <form class="user-avatar-form" method="post" action="admin/tenants/favicon/<?php e($tenantUuid); ?>"
             enctype="multipart/form-data">
             <?php
             $fileUpload = [
                 'name' => 'favicon',
                 'accept' => 'image/png',
                 'hint' => t('Allowed file types: PNG'),
-                'currentSrc' => $hasFavicon ? asset('favicon/tenants/' . $avatarUuid . '/favicon/favicon-32x32.png') : '',
+                'currentSrc' => $hasFavicon ? asset('favicon/tenants/' . $tenantUuid . '/favicon/favicon-32x32.png') : '',
                 'currentLabel' => t('Favicon'),
-                'deleteAction' => $hasFavicon ? 'admin/tenants/favicon-delete/' . $avatarUuid : '',
+                'deleteAction' => $hasFavicon ? 'admin/tenants/favicon-delete/' . $tenantUuid : '',
             ];
             require templatePath('partials/app-file-upload.phtml');
             ?>

pages/admin/tenants/index(default).phtml

@@ -43,7 +43,7 @@ $pageConfig = [
   'filterChipMeta' => $filterChipMeta,
   'gridLang' => $gridLang,
   'labels' => [
-    'avatar' => t('Avatar'),
+    'logo' => t('Logo'),
     'tenant' => t('Tenant'),
     'users' => t('Users'),
   ],

pages/admin/tenants/logo($id).php

@@ -3,31 +3,41 @@
 use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Router;
 use MintyPHP\Service\Access\TenantAuthorizationPolicy;
+use MintyPHP\Service\Tenant\TenantLogoService;
 use MintyPHP\Support\Flash;
 use MintyPHP\Support\Guard;
 
 $session = app(SessionStoreInterface::class)->all();
 Guard::requireLogin();
 $authorizationService = app(\MintyPHP\Service\Access\AuthorizationService::class);
-$tenantAvatarService = app(\MintyPHP\Service\Tenant\TenantAvatarService::class);
+$tenantLogoService = app(TenantLogoService::class);
 
 if (!actionRequirePost('admin/tenants')) {
     return;
 }
 
-if (!actionRequireCsrf('admin/tenants', 'admin/tenants', 'tenant_avatar_delete')) {
+if (!actionRequireCsrf('admin/tenants', 'admin/tenants', 'tenant_logo')) {
     return;
 }
 
 $errorBag = formErrors();
 $uuid = trim((string) ($id ?? ''));
-if (!$tenantAvatarService->isValidUuid($uuid)) {
+if (!$tenantLogoService->isValidUuid($uuid)) {
     $errorBag->addGlobal('Tenant not found');
-    flashFormErrors($errorBag, 'admin/tenants', 'tenant_avatar_delete');
+    flashFormErrors($errorBag, 'admin/tenants', 'tenant_logo');
     Router::redirect('admin/tenants');
     return;
 }
 
+$body = requestInput()->bodyAll();
+$theme = strtolower(trim((string) ($body['theme'] ?? '')));
+if (!$tenantLogoService->isValidTheme($theme)) {
+    $errorBag->addGlobal(t('Invalid theme'));
+    flashFormErrors($errorBag, "admin/tenants/edit/{$uuid}", 'tenant_logo_upload');
+    Router::redirect("admin/tenants/edit/{$uuid}");
+    return;
+}
+
 $tenant = app(\MintyPHP\Service\Tenant\TenantService::class)->findByUuid($uuid);
 $tenantId = (int) ($tenant['id'] ?? 0);
 $currentUserId = (int) ($session['user']['id'] ?? 0);
@@ -40,6 +50,14 @@ if (!$decision->isAllowed()) {
     return;
 }
 
-$tenantAvatarService->delete($uuid);
+$result = $tenantLogoService->saveUpload($uuid, $theme, requestInput()->filesAll()['logo'] ?? []);
-Flash::success('Avatar removed', "admin/tenants/edit/{$uuid}", 'tenant_avatar_removed');
+if (!($result['ok'] ?? false)) {
+    $error = $result['error'] ?? t('Upload failed');
+    $errorBag->addGlobal((string) $error);
+    flashFormErrors($errorBag, "admin/tenants/edit/{$uuid}", 'tenant_logo_upload');
+    Router::redirect("admin/tenants/edit/{$uuid}");
+    return;
+}
+
+Flash::success('Logo updated', "admin/tenants/edit/{$uuid}", 'tenant_logo_updated');
 Router::redirect("admin/tenants/edit/{$uuid}");

pages/admin/tenants/logo-delete($id).php

@@ -3,31 +3,41 @@
 use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Router;
 use MintyPHP\Service\Access\TenantAuthorizationPolicy;
+use MintyPHP\Service\Tenant\TenantLogoService;
 use MintyPHP\Support\Flash;
 use MintyPHP\Support\Guard;
 
 $session = app(SessionStoreInterface::class)->all();
 Guard::requireLogin();
 $authorizationService = app(\MintyPHP\Service\Access\AuthorizationService::class);
-$tenantAvatarService = app(\MintyPHP\Service\Tenant\TenantAvatarService::class);
+$tenantLogoService = app(TenantLogoService::class);
 
 if (!actionRequirePost('admin/tenants')) {
     return;
 }
 
-if (!actionRequireCsrf('admin/tenants', 'admin/tenants', 'tenant_avatar')) {
+if (!actionRequireCsrf('admin/tenants', 'admin/tenants', 'tenant_logo_delete')) {
     return;
 }
 
 $errorBag = formErrors();
 $uuid = trim((string) ($id ?? ''));
-if (!$tenantAvatarService->isValidUuid($uuid)) {
+if (!$tenantLogoService->isValidUuid($uuid)) {
     $errorBag->addGlobal('Tenant not found');
-    flashFormErrors($errorBag, 'admin/tenants', 'tenant_avatar');
+    flashFormErrors($errorBag, 'admin/tenants', 'tenant_logo_delete');
     Router::redirect('admin/tenants');
     return;
 }
 
+$body = requestInput()->bodyAll();
+$theme = strtolower(trim((string) ($body['theme'] ?? '')));
+if (!$tenantLogoService->isValidTheme($theme)) {
+    $errorBag->addGlobal(t('Invalid theme'));
+    flashFormErrors($errorBag, "admin/tenants/edit/{$uuid}", 'tenant_logo_delete');
+    Router::redirect("admin/tenants/edit/{$uuid}");
+    return;
+}
+
 $tenant = app(\MintyPHP\Service\Tenant\TenantService::class)->findByUuid($uuid);
 $tenantId = (int) ($tenant['id'] ?? 0);
 $currentUserId = (int) ($session['user']['id'] ?? 0);
@@ -40,14 +50,6 @@ if (!$decision->isAllowed()) {
     return;
 }
 
-$result = $tenantAvatarService->saveUpload($uuid, requestInput()->filesAll()['avatar'] ?? []);
+$tenantLogoService->delete($uuid, $theme);
-if (!($result['ok'] ?? false)) {
+Flash::success('Logo removed', "admin/tenants/edit/{$uuid}", 'tenant_logo_removed');
-    $error = $result['error'] ?? t('Upload failed');
-    $errorBag->addGlobal((string) $error);
-    flashFormErrors($errorBag, "admin/tenants/edit/{$uuid}", 'tenant_avatar_upload');
-    Router::redirect("admin/tenants/edit/{$uuid}");
-    return;
-}
-
-Flash::success('Avatar updated', "admin/tenants/edit/{$uuid}", 'tenant_avatar_updated');
 Router::redirect("admin/tenants/edit/{$uuid}");

pages/admin/tenants/logo-file().php

@@ -2,6 +2,7 @@
 
 use MintyPHP\Http\SessionStoreInterface;
 use MintyPHP\Service\Access\TenantAuthorizationPolicy;
+use MintyPHP\Service\Tenant\TenantLogoService;
 use MintyPHP\Support\Guard;
 
 $session = app(SessionStoreInterface::class)->all();
@@ -9,11 +10,13 @@ define('MINTY_ALLOW_OUTPUT', true);
 
 Guard::requireLogin();
 $authorizationService = app(\MintyPHP\Service\Access\AuthorizationService::class);
-$tenantAvatarService = app(\MintyPHP\Service\Tenant\TenantAvatarService::class);
+$tenantLogoService = app(TenantLogoService::class);
 
-$uuid = trim((string) (requestInput()->queryAll()['uuid'] ?? ''));
+$query = requestInput()->queryAll();
-$size = isset(requestInput()->queryAll()['size']) ? (int) requestInput()->queryAll()['size'] : null;
+$uuid = trim((string) ($query['uuid'] ?? ''));
-if (!$tenantAvatarService->isValidUuid($uuid)) {
+$theme = strtolower(trim((string) ($query['theme'] ?? '')));
+$size = isset($query['size']) ? (int) $query['size'] : null;
+if (!$tenantLogoService->isValidUuid($uuid) || !$tenantLogoService->isValidTheme($theme)) {
     http_response_code(404);
     return;
 }
@@ -25,7 +28,7 @@ if ($tenantId <= 0) {
     http_response_code(404);
     return;
 }
-$decision = $authorizationService->authorize(TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_AVATAR_VIEW, [
+$decision = $authorizationService->authorize(TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_LOGO_VIEW, [
     'actor_user_id' => $currentUserId,
     'target_tenant_id' => $tenantId,
 ]);
@@ -34,13 +37,13 @@ if (!$decision->isAllowed()) {
     return;
 }
 
-$path = $tenantAvatarService->findAvatarPath($uuid, $size);
+$path = $tenantLogoService->findLogoPath($uuid, $theme, $size);
 if (!$path || !is_file($path)) {
     http_response_code(404);
     return;
 }
 
-$mime = $tenantAvatarService->detectMime($path);
+$mime = $tenantLogoService->detectMime($path);
 header('Content-Type: ' . $mime);
 header('X-Content-Type-Options: nosniff');
 header('Content-Security-Policy: sandbox');

pages/api/v1/tenants/avatar($id).php

@@ -3,6 +3,7 @@
 use MintyPHP\Http\ApiAuth;
 use MintyPHP\Http\ApiBootstrap;
 use MintyPHP\Http\ApiResponse;
+use MintyPHP\Service\Tenant\TenantLogoService;
 use MintyPHP\Service\Tenant\TenantServicesFactory;
 
 define('MINTY_ALLOW_OUTPUT', true);
@@ -17,9 +18,9 @@ if ($uuid === '') {
     ApiResponse::notFound();
 }
 
-$tenantAvatarService = (app(TenantServicesFactory::class))->createTenantAvatarService();
+$tenantLogoService = (app(TenantServicesFactory::class))->createTenantLogoService();
 
-if (!$tenantAvatarService->isValidUuid($uuid)) {
+if (!$tenantLogoService->isValidUuid($uuid)) {
     ApiResponse::notFound();
 }
 
@@ -32,12 +33,21 @@ if ($tenantId <= 0) {
 ApiAuth::requireResourceAccess('tenants', $tenantId);
 
 $size = $request->hasQuery('size') ? $request->queryInt('size') : null;
-$path = $tenantAvatarService->findAvatarPath($uuid, $size);
+$theme = $request->hasQuery('theme') ? strtolower(trim((string) $request->queryAll()['theme'])) : TenantLogoService::THEME_LIGHT;
+if (!$tenantLogoService->isValidTheme($theme)) {
+    $theme = TenantLogoService::THEME_LIGHT;
+}
+$path = $tenantLogoService->findLogoPath($uuid, $theme, $size);
+if (!$path || !is_file($path)) {
+    // Fallback to the other theme so single-theme tenants still respond.
+    $otherTheme = $theme === TenantLogoService::THEME_DARK ? TenantLogoService::THEME_LIGHT : TenantLogoService::THEME_DARK;
+    $path = $tenantLogoService->findLogoPath($uuid, $otherTheme, $size);
+}
 if (!$path || !is_file($path)) {
     ApiResponse::notFound();
 }
 
-$mime = $tenantAvatarService->detectMime($path);
+$mime = $tenantLogoService->detectMime($path);
 header('Content-Type: ' . $mime);
 header('X-Content-Type-Options: nosniff');
 header('Content-Security-Policy: sandbox');

pages/auth/login().php

@@ -69,12 +69,12 @@ $authServicesFactory = app(AuthServicesFactory::class);
 $authService = $authServicesFactory->createAuthService();
 $rememberMeService = $authServicesFactory->createRememberMeService();
 $tenantSsoService = $authServicesFactory->createTenantSsoService();
-$tenantAvatarService = (app(TenantServicesFactory::class))->createTenantAvatarService();
+$tenantLogoService = (app(TenantServicesFactory::class))->createTenantLogoService();
 $userServicesFactory = app(UserServicesFactory::class);
 $userReadRepository = $userServicesFactory->createUserReadRepository();
 $userTenantContextService = $userServicesFactory->createUserTenantContextService();
 
-$resolveLoginCandidates = static function (string $inputEmail) use ($userReadRepository, $userTenantContextService, $tenantSsoService, $tenantAvatarService): array {
+$resolveLoginCandidates = static function (string $inputEmail) use ($userReadRepository, $userTenantContextService, $tenantSsoService, $tenantLogoService): array {
     $emailValue = strtolower(trim($inputEmail));
     if ($emailValue === '' || !filter_var($emailValue, FILTER_VALIDATE_EMAIL)) {
         return ['ok' => false];
@@ -119,7 +119,10 @@ $resolveLoginCandidates = static function (string $inputEmail) use ($userReadRep
             ? ($discoveryMethodsByTenantId[$tenantId] ?? ['local' => false, 'microsoft' => false, 'microsoft_reason' => '', 'ldap' => false, 'ldap_reason' => ''])
             : $tenantSsoService->resolveTenantLoginMethods($tenantId);
         $tenantUuid = (string) ($tenant['uuid'] ?? '');
-        $hasAvatar = $tenantUuid !== '' && $tenantAvatarService->hasAvatar($tenantUuid);
+        $hasLogoLight = $tenantUuid !== '' && $tenantLogoService->hasLogo($tenantUuid, \MintyPHP\Service\Tenant\TenantLogoService::THEME_LIGHT);
+        $hasLogoDark = $tenantUuid !== '' && $tenantLogoService->hasLogo($tenantUuid, \MintyPHP\Service\Tenant\TenantLogoService::THEME_DARK);
+        $hasAvatar = $hasLogoLight || $hasLogoDark;
+        $logoTheme = $hasLogoLight ? 'light' : ($hasLogoDark ? 'dark' : '');
         $candidate = [
           'id' => $tenantId,
           'uuid' => $tenantUuid,
@@ -127,7 +130,7 @@ $resolveLoginCandidates = static function (string $inputEmail) use ($userReadRep
           'slug' => $tenantSlug,
           'has_avatar' => $hasAvatar,
           'avatar_url' => $hasAvatar
-            ? lurl('auth/tenant-avatar-file?uuid=' . rawurlencode($tenantUuid) . '&size=256')
+            ? lurl('auth/tenant-logo-file?uuid=' . rawurlencode($tenantUuid) . '&theme=' . rawurlencode($logoTheme) . '&size=256')
             : '',
           'methods' => $methods,
         ];

pages/auth/tenant-logo-file().php

@@ -4,10 +4,12 @@ use MintyPHP\Service\Tenant\TenantServicesFactory;
 
 define('MINTY_ALLOW_OUTPUT', true);
 
-$uuid = trim((string) (requestInput()->queryAll()['uuid'] ?? ''));
+$query = requestInput()->queryAll();
-$size = isset(requestInput()->queryAll()['size']) ? (int) requestInput()->queryAll()['size'] : null;
+$uuid = trim((string) ($query['uuid'] ?? ''));
-$tenantAvatarService = (app(TenantServicesFactory::class))->createTenantAvatarService();
+$theme = strtolower(trim((string) ($query['theme'] ?? '')));
-if (!$tenantAvatarService->isValidUuid($uuid)) {
+$size = isset($query['size']) ? (int) $query['size'] : null;
+$tenantLogoService = (app(TenantServicesFactory::class))->createTenantLogoService();
+if (!$tenantLogoService->isValidUuid($uuid) || !$tenantLogoService->isValidTheme($theme)) {
     http_response_code(404);
     return;
 }
@@ -18,13 +20,13 @@ if (!$tenant || (string) ($tenant['status'] ?? 'active') !== 'active') {
     return;
 }
 
-$path = $tenantAvatarService->findAvatarPath($uuid, $size);
+$path = $tenantLogoService->findLogoPath($uuid, $theme, $size);
 if (!$path || !is_file($path)) {
     http_response_code(404);
     return;
 }
 
-$mime = $tenantAvatarService->detectMime($path);
+$mime = $tenantLogoService->detectMime($path);
 header('Content-Type: ' . $mime);
 header('X-Content-Type-Options: nosniff');
 header('Content-Security-Policy: sandbox');

phpstan-baseline.neon

@@ -1170,18 +1170,6 @@ parameters:
 			count: 1
 			path: core/App/Module/ModuleManifest.php
 
-		-
-			message: '#^Public method "MintyPHP\\Service\\Tenant\\TenantAvatarService\:\:hasAvatar\(\)" is never used$#'
-			identifier: public.method.unused
-			count: 1
-			path: core/Service/Tenant/TenantAvatarService.php
-
-		-
-			message: '#^Public method "MintyPHP\\Service\\Tenant\\TenantAvatarService\:\:saveUpload\(\)" is never used$#'
-			identifier: public.method.unused
-			count: 1
-			path: core/Service/Tenant/TenantAvatarService.php
-
 		-
 			message: '#^Public method "MintyPHP\\Service\\Tenant\\TenantFaviconService\:\:hasFavicon\(\)" is never used$#'
 			identifier: public.method.unused
@@ -1231,7 +1219,7 @@ parameters:
 			path: core/Service/Tenant/TenantService.php
 
 		-
-			message: '#^Public method "MintyPHP\\Service\\Tenant\\TenantServicesFactory\:\:createTenantAvatarService\(\)" is never used$#'
+			message: '#^Public method "MintyPHP\\Service\\Tenant\\TenantServicesFactory\:\:createTenantLogoService\(\)" is never used$#'
 			identifier: public.method.unused
 			count: 1
 			path: core/Service/Tenant/TenantServicesFactory.php

templates/partials/app-file-upload.phtml

@@ -11,11 +11,13 @@
  *       'name'           => 'avatar',                                    // required — input name attribute
  *       'accept'         => 'image/*',                                   // required — accepted file types
  *       'hint'           => t('Allowed file types: SVG, PNG, JPG, WEBP'),// optional — hint text below dropzone label
- *       'currentSrc'     => 'admin/tenants/avatar-file?uuid=…&size=128', // optional — URL of existing server file
+ *       'currentSrc'     => 'admin/tenants/logo-file?uuid=…&theme=light&size=128', // optional — URL of existing server file
  *       'currentLabel'   => t('Current image'),                          // optional — label for current file preview
- *       'deleteAction'   => 'admin/tenants/avatar-delete/…',             // optional — formaction for delete button (requires currentSrc)
+ *       'deleteAction'   => 'admin/tenants/logo-delete/…',               // optional — formaction for delete button (requires currentSrc)
  *       'deleteConfirm'  => t('Delete this image?'),                     // optional — confirm message on delete
  *       'required'       => false,                                       // optional — make input required
+ *       'formId'         => 'tenant-logo-light-form',                    // optional — HTML5 form attribute to associate input with an external form
+ *       'deleteFormId'   => 'tenant-logo-light-delete-form',             // optional — HTML5 form attribute for the delete button (bypasses formaction)
  *   ];
  *   require templatePath('partials/app-file-upload.phtml');
  *
@@ -35,8 +37,10 @@ $uploadCurrentLabel = trim((string) ($fileUpload['currentLabel'] ?? t('Current i
 $uploadDeleteAction = trim((string) ($fileUpload['deleteAction'] ?? ''));
 $uploadDeleteConfirm = trim((string) ($fileUpload['deleteConfirm'] ?? t('Delete this image?')));
 $uploadRequired = (bool) ($fileUpload['required'] ?? false);
+$uploadFormId = trim((string) ($fileUpload['formId'] ?? ''));
+$uploadDeleteFormId = trim((string) ($fileUpload['deleteFormId'] ?? ''));
 $hasCurrent = $uploadCurrentSrc !== '';
-$hasDelete = $hasCurrent && $uploadDeleteAction !== '';
+$hasDelete = $hasCurrent && ($uploadDeleteAction !== '' || $uploadDeleteFormId !== '');
 
 ?>
 <div data-app-component="file-upload" class="app-file-upload"
@@ -50,7 +54,7 @@ $hasDelete = $hasCurrent && $uploadDeleteAction !== '';
           <button type="button" class="app-file-upload-replace-button"><?php e(t('Replace')); ?></button>
           <?php if ($hasDelete): ?>
             <button type="submit" class="app-file-upload-delete-button"
-              formaction="<?php e($uploadDeleteAction); ?>" formmethod="post"
+              <?php if ($uploadDeleteFormId !== ''): ?>form="<?php e($uploadDeleteFormId); ?>"<?php else: ?>formaction="<?php e($uploadDeleteAction); ?>" formmethod="post"<?php endif; ?>
               data-confirm-message="<?php e($uploadDeleteConfirm); ?>"><?php e(t('Delete')); ?></button>
           <?php endif; ?>
         </span>
@@ -60,6 +64,7 @@ $hasDelete = $hasCurrent && $uploadDeleteAction !== '';
   <label class="app-file-upload-dropzone">
     <input type="file" name="<?php e($uploadName); ?>"
       <?php if ($uploadAccept !== ''): ?>accept="<?php e($uploadAccept); ?>"<?php endif; ?>
+      <?php if ($uploadFormId !== ''): ?>form="<?php e($uploadFormId); ?>"<?php endif; ?>
       <?php if ($uploadRequired): ?>required<?php endif; ?>>
     <span class="app-file-upload-dropzone-icon"><i class="bi bi-cloud-arrow-up"></i></span>
     <span class="app-file-upload-dropzone-label"><?php e(t('Drop file here or click to select')); ?></span>

templates/partials/app-main-aside.phtml

@@ -262,10 +262,12 @@ $layoutNav = is_array($layoutNav ?? null) ? $layoutNav : [];
 $currentTenant = is_array($layoutNav['currentTenant'] ?? null) ? $layoutNav['currentTenant'] : null;
 $availableTenants = is_array($layoutNav['availableTenants'] ?? null) ? $layoutNav['availableTenants'] : [];
 $tenantQueryParam = trim((string) ($layoutNav['tenantQueryParam'] ?? ''));
-$tenantAvatar = is_array($layoutNav['tenantAvatar'] ?? null) ? $layoutNav['tenantAvatar'] : [];
+$tenantLogo = is_array($layoutNav['tenantLogo'] ?? null) ? $layoutNav['tenantLogo'] : [];
-$tenantUuid = trim((string) ($tenantAvatar['uuid'] ?? ''));
+$tenantUuid = trim((string) ($tenantLogo['uuid'] ?? ''));
-$tenantName = trim((string) ($tenantAvatar['name'] ?? ''));
+$tenantName = trim((string) ($tenantLogo['name'] ?? ''));
-$hasTenantAvatar = !empty($tenantAvatar['hasAvatar']);
+$hasTenantLogoLight = !empty($tenantLogo['hasLogoLight']);
+$hasTenantLogoDark = !empty($tenantLogo['hasLogoDark']);
+$hasTenantLogo = $hasTenantLogoLight || $hasTenantLogoDark;
 $csrfKey = trim((string) ($layoutNav['csrfKey'] ?? \MintyPHP\Session::$csrfSessionKey));
 $csrfToken = (string) ($layoutNav['csrfToken'] ?? '');
 $moduleSlots = is_array($layoutNav['moduleSlots'] ?? null) ? $layoutNav['moduleSlots'] : [];

templates/partials/app-topbar.phtml

@@ -13,10 +13,12 @@ $csrfToken = $_SESSION[$csrfKey] ?? '';
 
 // Tenant branding data (from $layoutNav, same source as app-main-aside.phtml)
 $layoutNav = is_array($layoutNav ?? null) ? $layoutNav : [];
-$tenantAvatar = is_array($layoutNav['tenantAvatar'] ?? null) ? $layoutNav['tenantAvatar'] : [];
+$tenantLogo = is_array($layoutNav['tenantLogo'] ?? null) ? $layoutNav['tenantLogo'] : [];
-$brandTenantUuid = trim((string) ($tenantAvatar['uuid'] ?? ''));
+$brandTenantName = trim((string) ($tenantLogo['name'] ?? ''));
-$brandTenantName = trim((string) ($tenantAvatar['name'] ?? ''));
+$brandHasTenantLogo = !empty($tenantLogo['hasLogoLight']) || !empty($tenantLogo['hasLogoDark']);
-$brandHasTenantAvatar = !empty($tenantAvatar['hasAvatar']);
+$brandTenantLogoUrl = $brandHasTenantLogo ? appTenantLogoUrl(256, $theme) : '';
+$brandTenantLogoLight = $brandHasTenantLogo ? appTenantLogoUrl(256, 'light') : '';
+$brandTenantLogoDark = $brandHasTenantLogo ? appTenantLogoUrl(256, 'dark') : '';
 
 // Tenant switcher data
 $currentTenant = $_SESSION['current_tenant'] ?? null;
@@ -45,8 +47,12 @@ $moduleTopbarSlots = is_array($moduleSlots['topbar.right_item'] ?? null) ? $modu
         <i class="bi bi-list" aria-hidden="true"></i>
       </button>
       <a href="<?php e(lurl('')); ?>" class="app-topbar-brand">
-        <?php if ($brandHasTenantAvatar): ?>
+        <?php if ($brandTenantLogoUrl !== ''): ?>
-          <img src="auth/tenant-avatar-file?uuid=<?php e($brandTenantUuid); ?>&amp;size=256" alt="<?php e($brandTenantName); ?>">
+          <img class="app-tenant-logo" src="<?php e($brandTenantLogoUrl); ?>"
+            data-theme-src
+            data-src-light="<?php e($brandTenantLogoLight); ?>"
+            data-src-dark="<?php e($brandTenantLogoDark); ?>"
+            alt="<?php e($brandTenantName); ?>">
         <?php elseif ($brandTenantName !== ''): ?>
           <span class="app-topbar-brand-name"><?php e($brandTenantName); ?></span>
         <?php else: ?>

templates/partials/auth-logo.phtml

@@ -1,17 +1,29 @@
 <?php
 
+$authLogoHref = isset($authLogoHref) && is_string($authLogoHref) ? trim($authLogoHref) : '';
 $authLogoUrl = appAuthLogoUrl();
 if ($authLogoUrl === '') {
     return;
 }
-$authLogoHref = isset($authLogoHref) && is_string($authLogoHref) ? trim($authLogoHref) : '';
+
+// Offer both theme variants via data-* so the client can swap without reload.
+$authLogoLight = function_exists('appTenantLogoUrl') ? appTenantLogoUrl(null, 'light') : $authLogoUrl;
+$authLogoDark = function_exists('appTenantLogoUrl') ? appTenantLogoUrl(null, 'dark') : $authLogoUrl;
 ?>
 <div class="login-logo">
     <?php if ($authLogoHref !== ''): ?>
         <a href="<?php e($authLogoHref); ?>" class="login-logo-link">
-            <img src="<?php e($authLogoUrl); ?>" alt="<?php e(appTitle()); ?>" class="login-logo-img">
+            <img src="<?php e($authLogoUrl); ?>"
+                data-theme-src
+                data-src-light="<?php e($authLogoLight); ?>"
+                data-src-dark="<?php e($authLogoDark); ?>"
+                alt="<?php e(appTitle()); ?>" class="login-logo-img">
         </a>
     <?php else: ?>
-        <img src="<?php e($authLogoUrl); ?>" alt="<?php e(appTitle()); ?>" class="login-logo-img">
+        <img src="<?php e($authLogoUrl); ?>"
+            data-theme-src
+            data-src-light="<?php e($authLogoLight); ?>"
+            data-src-dark="<?php e($authLogoDark); ?>"
+            alt="<?php e(appTitle()); ?>" class="login-logo-img">
     <?php endif; ?>
 </div>

templates/partials/tenant-logo-upload.phtml

@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * Single-theme tenant-logo slot. Uses the standard app-file-upload.phtml
+ * partial for the drop-zone UI (upload + current preview + replace + delete),
+ * wired to a pair of barrier forms via the HTML5 form attribute.
+ *
+ * Required view vars:
+ *   $tenantUuid, $logoTheme ('light'|'dark'), $hasLogo (bool),
+ *   $fieldLabel, $uploadFormId, $deleteFormId, $canUpdate (bool)
+ */
+
+$tenantUuid = (string) ($tenantUuid ?? '');
+$logoTheme = (string) ($logoTheme ?? 'light');
+$hasLogo = (bool) ($hasLogo ?? false);
+$fieldLabel = (string) ($fieldLabel ?? '');
+$uploadFormId = (string) ($uploadFormId ?? '');
+$deleteFormId = (string) ($deleteFormId ?? '');
+$canUpdate = (bool) ($canUpdate ?? false);
+$previewUrl = $hasLogo
+    ? 'admin/tenants/logo-file?uuid=' . rawurlencode($tenantUuid) . '&theme=' . rawurlencode($logoTheme) . '&size=256'
+    : '';
+?>
+<div class="tenant-logo-slot">
+    <span class="tenant-logo-slot-label"><?php e($fieldLabel); ?></span>
+    <?php if ($canUpdate && $uploadFormId !== ''): ?>
+        <?php
+        $fileUpload = [
+            'name' => 'logo',
+            'accept' => 'image/svg+xml,image/png,image/jpeg,image/webp',
+            'hint' => t('Allowed file types: SVG, PNG, JPG, WEBP'),
+            'currentSrc' => $previewUrl,
+            'currentLabel' => $fieldLabel,
+            'formId' => $uploadFormId,
+            'deleteFormId' => $hasLogo && $deleteFormId !== '' ? $deleteFormId : '',
+            'deleteConfirm' => t('Delete this logo?'),
+        ];
+        require templatePath('partials/app-file-upload.phtml');
+        ?>
+        <div class="tenant-logo-actions">
+            <button type="submit" form="<?php e($uploadFormId); ?>" class="secondary outline small">
+                <?php e(t('Save')); ?>
+            </button>
+        </div>
+    <?php elseif ($hasLogo): ?>
+        <img class="tenant-logo-readonly-preview" src="<?php e($previewUrl); ?>" alt="<?php e($fieldLabel); ?>">
+    <?php endif; ?>
+</div>

tests/Architecture/AuthzAdminTenantsContractTest.php

@@ -46,14 +46,14 @@ class AuthzAdminTenantsContractTest extends TestCase
 
     public function testAdminTenantMediaEndpointsUseCentralPolicies(): void
     {
-        $avatarView = $this->readProjectFile('pages/admin/tenants/avatar-file().php');
+        $logoView = $this->readProjectFile('pages/admin/tenants/logo-file().php');
-        $this->assertStringContainsString('TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_AVATAR_VIEW', $avatarView);
+        $this->assertStringContainsString('TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_LOGO_VIEW', $logoView);
 
-        $avatarUpload = $this->readProjectFile('pages/admin/tenants/avatar($id).php');
+        $logoUpload = $this->readProjectFile('pages/admin/tenants/logo($id).php');
-        $this->assertStringContainsString('TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_MEDIA_UPDATE', $avatarUpload);
+        $this->assertStringContainsString('TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_MEDIA_UPDATE', $logoUpload);
 
-        $avatarDelete = $this->readProjectFile('pages/admin/tenants/avatar-delete($id).php');
+        $logoDelete = $this->readProjectFile('pages/admin/tenants/logo-delete($id).php');
-        $this->assertStringContainsString('TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_MEDIA_UPDATE', $avatarDelete);
+        $this->assertStringContainsString('TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_MEDIA_UPDATE', $logoDelete);
 
         $faviconUpload = $this->readProjectFile('pages/admin/tenants/favicon($id).php');
         $this->assertStringContainsString('TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_MEDIA_UPDATE', $faviconUpload);

tests/Architecture/AuthzUiLayoutContractTest.php

@@ -30,7 +30,7 @@ class AuthzUiLayoutContractTest extends TestCase
 
         $this->assertStringNotContainsString('$_GET', $aside);
         $this->assertStringNotContainsString('$_SESSION', $aside);
-        $this->assertStringNotContainsString('TenantAvatarService', $aside);
+        $this->assertStringNotContainsString('TenantLogoService', $aside);
         $this->assertStringNotContainsString('app(', $aside);
     }
 

tests/Service/Access/TenantAuthorizationPolicyTest.php

@@ -249,7 +249,7 @@ class TenantAuthorizationPolicyTest extends TestCase
         $this->assertDeniedDecision($decision, 403, 'permission_denied');
     }
 
-    public function testAvatarViewAllowsTenantViewerInScope(): void
+    public function testLogoViewAllowsTenantViewerInScope(): void
     {
         $permissionService = $this->permissionGatewayAllowing([
             15 => [PermissionService::TENANTS_VIEW],
@@ -262,7 +262,7 @@ class TenantAuthorizationPolicyTest extends TestCase
             ->willReturn(true);
 
         $policy = new TenantAuthorizationPolicy($permissionService, $scopeGateway);
-        $decision = $policy->authorize(TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_AVATAR_VIEW, [
+        $decision = $policy->authorize(TenantAuthorizationPolicy::ABILITY_ADMIN_TENANTS_LOGO_VIEW, [
             'actor_user_id' => 15,
             'target_tenant_id' => 9,
         ]);

tests/Service/Tenant/TenantLogoServiceTest.php

@@ -0,0 +1,115 @@
+<?php
+
+namespace MintyPHP\Tests\Service\Tenant;
+
+use MintyPHP\Service\Tenant\TenantLogoService;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Service behaviour test. Upload flows are covered via path-independent
+ * assertions (MIME + SVG guards + dir creation semantics) because
+ * move_uploaded_file() requires a real HTTP-uploaded file and cannot run
+ * under phpunit. Integration coverage for the move step lives in the
+ * manual smoketest documented in the execution report.
+ */
+class TenantLogoServiceTest extends TestCase
+{
+    private TenantLogoService $service;
+
+    protected function setUp(): void
+    {
+        $this->service = new TenantLogoService();
+    }
+
+    public function testIsValidThemeAcceptsWhitelistedThemes(): void
+    {
+        $this->assertTrue($this->service->isValidTheme('light'));
+        $this->assertTrue($this->service->isValidTheme('dark'));
+    }
+
+    public function testIsValidThemeRejectsUnknownThemes(): void
+    {
+        $this->assertFalse($this->service->isValidTheme(''));
+        $this->assertFalse($this->service->isValidTheme('dark-green'));
+        $this->assertFalse($this->service->isValidTheme('LIGHT'));
+    }
+
+    public function testIsValidUuidRejectsMalformedInput(): void
+    {
+        $this->assertFalse($this->service->isValidUuid('not-a-uuid'));
+        $this->assertFalse($this->service->isValidUuid(''));
+    }
+
+    public function testIsValidUuidAcceptsCanonicalUuid(): void
+    {
+        $this->assertTrue($this->service->isValidUuid('11111111-2222-3333-4444-555555555555'));
+    }
+
+    public function testFindLogoPathRejectsInvalidTheme(): void
+    {
+        $this->assertNull($this->service->findLogoPath('11111111-2222-3333-4444-555555555555', 'neon'));
+    }
+
+    public function testFindLogoPathRejectsInvalidUuid(): void
+    {
+        $this->assertNull($this->service->findLogoPath('bogus', 'light'));
+    }
+
+    public function testHasLogoReturnsFalseForMissingDirectory(): void
+    {
+        $this->assertFalse($this->service->hasLogo('11111111-2222-3333-4444-555555555555', 'light'));
+    }
+
+    public function testTenantLogoDirIncludesThemeSegment(): void
+    {
+        $uuid = '11111111-2222-3333-4444-555555555555';
+        $this->assertStringEndsWith('/tenants/' . $uuid . '/logo/light', $this->service->tenantLogoDir($uuid, 'light'));
+        $this->assertStringEndsWith('/tenants/' . $uuid . '/logo/dark', $this->service->tenantLogoDir($uuid, 'dark'));
+    }
+
+    public function testSaveUploadRejectsInvalidUuid(): void
+    {
+        $result = $this->service->saveUpload('not-uuid', 'light', [
+            'tmp_name' => '/tmp/whatever',
+            'error' => UPLOAD_ERR_OK,
+            'size' => 100,
+        ]);
+        $this->assertFalse($result['ok']);
+    }
+
+    public function testSaveUploadRejectsInvalidTheme(): void
+    {
+        $result = $this->service->saveUpload('11111111-2222-3333-4444-555555555555', 'neon', [
+            'tmp_name' => '/tmp/whatever',
+            'error' => UPLOAD_ERR_OK,
+            'size' => 100,
+        ]);
+        $this->assertFalse($result['ok']);
+    }
+
+    public function testSaveUploadRejectsOversizedFile(): void
+    {
+        $result = $this->service->saveUpload('11111111-2222-3333-4444-555555555555', 'light', [
+            'tmp_name' => '/tmp/whatever',
+            'error' => UPLOAD_ERR_OK,
+            'size' => 10 * 1024 * 1024,
+        ]);
+        $this->assertFalse($result['ok']);
+    }
+
+    public function testSaveUploadRejectsMissingFile(): void
+    {
+        $result = $this->service->saveUpload('11111111-2222-3333-4444-555555555555', 'light', []);
+        $this->assertFalse($result['ok']);
+    }
+
+    public function testDeleteRejectsInvalidUuid(): void
+    {
+        $this->assertFalse($this->service->delete('bogus', 'light'));
+    }
+
+    public function testDeleteRejectsInvalidTheme(): void
+    {
+        $this->assertFalse($this->service->delete('11111111-2222-3333-4444-555555555555', 'neon'));
+    }
+}

tests/Support/TenantLogoHelperTest.php

@@ -0,0 +1,95 @@
+<?php
+
+namespace MintyPHP\Tests\Support;
+
+use MintyPHP\App\AppContainer;
+use MintyPHP\Service\Branding\BrandingLogoService;
+use MintyPHP\Service\Tenant\TenantLogoService;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Covers the appTenantLogoUrl() fallback cascade:
+ *   1. tenant logo for the requested theme
+ *   2. tenant logo for the other theme
+ *   3. global app logo
+ *   4. hardcoded brand asset
+ */
+class TenantLogoHelperTest extends TestCase
+{
+    use AppContainerIsolationTrait;
+
+    private AppContainer $container;
+    private string $tenantUuid = '11111111-2222-3333-4444-555555555555';
+
+    protected function setUp(): void
+    {
+        $_SESSION = [];
+        $this->container = new AppContainer();
+        $this->pushAppContainer($this->container);
+    }
+
+    protected function tearDown(): void
+    {
+        $this->restoreAppContainer();
+        $_SESSION = [];
+    }
+
+    public function testFallsBackToAppLogoWithoutTenantContext(): void
+    {
+        $this->mockLogoService(false, false);
+        $this->mockBrandingLogo(false);
+
+        $url = appTenantLogoUrl(128, 'light');
+
+        $this->assertStringContainsString('brand/logo.svg', $url);
+    }
+
+    public function testUsesRequestedThemeWhenAvailable(): void
+    {
+        $_SESSION['current_tenant'] = ['uuid' => $this->tenantUuid];
+        $this->mockLogoService(true, true);
+
+        $url = appTenantLogoUrl(256, 'dark');
+
+        $this->assertStringContainsString('auth/tenant-logo-file', $url);
+        $this->assertStringContainsString('theme=dark', $url);
+    }
+
+    public function testFallsBackToOtherThemeWhenRequestedMissing(): void
+    {
+        $_SESSION['current_tenant'] = ['uuid' => $this->tenantUuid];
+        $this->mockLogoService(true, false);
+
+        $url = appTenantLogoUrl(256, 'dark');
+
+        $this->assertStringContainsString('auth/tenant-logo-file', $url);
+        $this->assertStringContainsString('theme=light', $url);
+    }
+
+    public function testFallsBackToAppLogoWhenTenantHasNoLogos(): void
+    {
+        $_SESSION['current_tenant'] = ['uuid' => $this->tenantUuid];
+        $this->mockLogoService(false, false);
+        $this->mockBrandingLogo(true);
+
+        $url = appTenantLogoUrl(128, 'light');
+
+        $this->assertStringContainsString('branding/logo', $url);
+    }
+
+    private function mockLogoService(bool $hasLight, bool $hasDark): void
+    {
+        $mock = $this->createMock(TenantLogoService::class);
+        $mock->method('hasLogo')->willReturnCallback(function (string $uuid, string $theme) use ($hasLight, $hasDark): bool {
+            return $theme === 'light' ? $hasLight : $hasDark;
+        });
+        $this->container->set(TenantLogoService::class, fn () => $mock);
+    }
+
+    private function mockBrandingLogo(bool $hasLogo): void
+    {
+        $mock = $this->createMock(BrandingLogoService::class);
+        $mock->method('hasLogo')->willReturn($hasLogo);
+        $this->container->set(BrandingLogoService::class, fn () => $mock);
+    }
+}

web/css/base/variables.base.css

@@ -120,6 +120,26 @@
   --app-text-selection-color: rgba(2, 154, 232, 0.25);
   --app-muted-color: #646b79;
   --app-muted-border-color: rgb(231, 234, 239.5);
+  --app-preview-checker-bg: #ffffff;
+  --app-preview-checker-fg: #eef0f3;
+  --app-button-filled-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.2),
+    0 1px 2px rgba(0, 0, 0, 0.12);
+  --app-button-filled-shadow-hover:
+    inset 0 1px 0 rgba(255, 255, 255, 0.25),
+    0 2px 4px rgba(0, 0, 0, 0.18);
+  --app-button-neutral-bg: #ffffff;
+  --app-button-neutral-bg-hover: #f6f8fa;
+  --app-button-neutral-border: #e3e6eb;
+  --app-button-neutral-border-hover: #c5c9d1;
+  --app-button-neutral-color: #1a1f2a;
+  --app-button-neutral-color-hover: #0b0f18;
+  --app-button-neutral-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.6),
+    0 1px 2px rgba(17, 24, 39, 0.08);
+  --app-button-neutral-shadow-hover:
+    inset 0 1px 0 rgba(255, 255, 255, 0.8),
+    0 2px 4px rgba(17, 24, 39, 0.12);
   --app-primary-h-light: 180.75;
   --app-primary-s-light: 37.38%;
   --app-primary-l-light: 58.04%;
@@ -293,6 +313,7 @@
   --app-action-success-hover-border: #176238;
   --app-action-success-focus-color: rgba(31, 122, 69, 0.45);
   --app-action-success-outline-background: rgba(31, 122, 69, 0.14);
+  --app-action-success-outline-color: #155a32;
   --app-action-danger-background: #b33636;
   --app-action-danger-border: #b33636;
   --app-action-danger-color: #fff;
@@ -300,6 +321,7 @@
   --app-action-danger-hover-border: #952d2d;
   --app-action-danger-focus-color: rgba(179, 54, 54, 0.45);
   --app-action-danger-outline-background: rgba(179, 54, 54, 0.14);
+  --app-action-danger-outline-color: #8f2727;
   --app-switch-background-color: #bfc7d9;
   --app-switch-checked-background-color: var(--app-primary-background);
   --app-switch-color: #fff;
@@ -610,6 +632,26 @@
   --app-text-selection-color: rgba(1, 170, 255, 0.1875);
   --app-muted-color: #6e6e6c;
   --app-muted-border-color: #2f2f2d;
+  --app-preview-checker-bg: #2a2a28;
+  --app-preview-checker-fg: #363634;
+  --app-button-neutral-bg: #30343b;
+  --app-button-neutral-bg-hover: #3b4048;
+  --app-button-neutral-border: #464b54;
+  --app-button-neutral-border-hover: #5b616c;
+  --app-button-neutral-color: #d5d9e0;
+  --app-button-neutral-color-hover: #ffffff;
+  --app-button-neutral-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.06),
+    0 1px 2px rgba(0, 0, 0, 0.3);
+  --app-button-neutral-shadow-hover:
+    inset 0 1px 0 rgba(255, 255, 255, 0.1),
+    0 2px 5px rgba(0, 0, 0, 0.35);
+  --app-button-filled-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.15),
+    0 1px 2px rgba(0, 0, 0, 0.4);
+  --app-button-filled-shadow-hover:
+    inset 0 1px 0 rgba(255, 255, 255, 0.2),
+    0 2px 5px rgba(0, 0, 0, 0.5);
   --app-primary-h-dark: var(--app-primary-h-light, var(--app-primary-h-base));
   --app-primary-s-dark: var(--app-primary-s-light, var(--app-primary-s-base));
   --app-primary-l-dark: var(--app-primary-l-light, var(--app-primary-l-base));
@@ -792,6 +834,7 @@
   --app-action-success-hover-border: #176238;
   --app-action-success-focus-color: rgba(31, 122, 69, 0.5);
   --app-action-success-outline-background: rgba(31, 122, 69, 0.2);
+  --app-action-success-outline-color: #4cc37a;
   --app-action-danger-background: #b33636;
   --app-action-danger-border: #b33636;
   --app-action-danger-color: #fff;
@@ -799,6 +842,7 @@
   --app-action-danger-hover-border: #952d2d;
   --app-action-danger-focus-color: rgba(179, 54, 54, 0.5);
   --app-action-danger-outline-background: rgba(179, 54, 54, 0.2);
+  --app-action-danger-outline-color: #e06666;
   --app-switch-background-color: #3a3a38;
   --app-switch-checked-background-color: var(--app-primary-background);
   --app-switch-color: #fff;

web/css/components/app-buttons.css

@@ -1,4 +1,29 @@
 @layer components {
+  /* Subtle 3D lift (inset top highlight + drop shadow) on filled
+     action-intent buttons only — explicit opt-in via class so chrome
+     buttons (topbar icons, aside icon bar, menu toggles) stay flat. */
+  :where(button, [type="submit"], [type="button"], [type="reset"], [role="button"]):is(
+    .primary,
+    .app-action-success,
+    .app-action-danger,
+    .danger
+  ):not(.outline):not(.contrast) {
+    box-shadow: var(--app-button-filled-shadow);
+  }
+
+  :where(button, [type="submit"], [type="button"], [type="reset"], [role="button"]):is(
+    .primary,
+    .app-action-success,
+    .app-action-danger,
+    .danger
+  ):not(.outline):not(.contrast):is(
+    [aria-current]:not([aria-current="false"]),
+    :hover,
+    :active
+  ) {
+    box-shadow: var(--app-button-filled-shadow-hover);
+  }
+
   /* Action button variants — success and danger colors with outline and focus states. */
 .app-action-success:is(button, [type="submit"], [type="button"], [role="button"]) {
   --app-background-color: var(--app-action-success-background);
@@ -18,9 +43,9 @@
 }
 
 .app-action-success:is(button, [type="submit"], [type="button"], [role="button"]).outline {
-  --app-background-color: transparent;
+  --app-background-color: color-mix(in srgb, var(--app-action-success-border) 10%, transparent);
   --app-border-color: var(--app-action-success-border);
-  --app-color: var(--app-action-success-border);
+  --app-color: var(--app-action-success-outline-color);
 }
 
 .app-action-success:is(
@@ -34,9 +59,9 @@
     :active,
     :focus
   ) {
-  --app-background-color: var(--app-action-success-outline-background);
+  --app-background-color: color-mix(in srgb, var(--app-action-success-border) 22%, transparent);
   --app-border-color: var(--app-action-success-border);
-  --app-color: var(--app-action-success-border);
+  --app-color: var(--app-action-success-outline-color);
 }
 
 .app-action-success:is(button, [type="submit"], [type="button"], [role="button"]):focus {
@@ -71,9 +96,9 @@
 
 .danger:is(button, [type="submit"], [type="button"], [role="button"]).outline,
 .app-action-danger:is(button, [type="submit"], [type="button"], [role="button"]).outline {
-  --app-background-color: transparent;
+  --app-background-color: color-mix(in srgb, var(--app-action-danger-border) 10%, transparent);
   --app-border-color: var(--app-action-danger-border);
-  --app-color: var(--app-action-danger-border);
+  --app-color: var(--app-action-danger-outline-color);
 }
 
 .danger:is(
@@ -98,9 +123,9 @@
     :active,
     :focus
   ) {
-  --app-background-color: var(--app-action-danger-outline-background);
+  --app-background-color: color-mix(in srgb, var(--app-action-danger-border) 22%, transparent);
   --app-border-color: var(--app-action-danger-border);
-  --app-color: var(--app-action-danger-border);
+  --app-color: var(--app-action-danger-outline-color);
 }
 
 .danger:is(button, [type="submit"], [type="button"], [role="button"]):focus,

web/css/components/app-file-upload.css

@@ -15,41 +15,56 @@
     background: color-mix(in srgb, var(--app-primary) 5%, var(--app-card-background-color));
   }
 
-  /* ── Current file (server-side, shown when data-current-src is set) ── */
+  /* ── Current file (server-side, shown when data-current-src is set) ──
+     Full-width preview on top, filename + actions row below. */
   .app-file-upload-current {
     display: flex;
-    align-items: center;
+    flex-direction: column;
-    gap: calc(var(--app-spacing) * 0.75);
+    gap: calc(var(--app-spacing) * 0.5);
     padding: calc(var(--app-spacing) * 0.75);
   }
 
   .app-file-upload-current-image {
-    width: 48px;
+    width: 100%;
-    height: 48px;
+    aspect-ratio: 16 / 9;
+    padding: var(--app-spacing);
     border-radius: calc(var(--app-border-radius) * 0.5);
-    object-fit: cover;
+    object-fit: contain;
-    flex-shrink: 0;
+    object-position: center;
     border: 1px solid var(--app-muted-border-color);
-    background: var(--app-background-color);
+    background-color: var(--app-preview-checker-bg);
+    background-image:
+      linear-gradient(45deg, var(--app-preview-checker-fg) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--app-preview-checker-fg) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--app-preview-checker-fg) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--app-preview-checker-fg) 75%);
+    background-size: 16px 16px;
+    background-position: 0 0, 0 8px, 8px -8px, -8px 0;
+    box-sizing: border-box;
   }
 
   .app-file-upload-current-meta {
-    flex: 1;
-    min-width: 0;
     display: flex;
-    flex-direction: column;
+    align-items: center;
-    gap: 2px;
+    justify-content: space-between;
+    gap: calc(var(--app-spacing) * 0.5);
+    min-width: 0;
   }
 
   .app-file-upload-current-label {
     font-size: var(--text-sm);
     font-weight: var(--font-medium);
     color: var(--app-contrast);
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
   }
 
   .app-file-upload-current-actions {
     display: flex;
     gap: calc(var(--app-spacing) * 0.25);
+    flex-shrink: 0;
   }
 
   .app-file-upload-current-actions button {
@@ -153,11 +168,12 @@
     80% { transform: translateX(2px); }
   }
 
-  /* ── Pending file preview (visible when new file selected) ── */
+  /* ── Pending file preview (visible when new file selected) ──
+     Same layout as current: full-width thumb + info row below. */
   .app-file-upload-preview {
     display: none;
-    align-items: center;
+    flex-direction: column;
-    gap: calc(var(--app-spacing) * 0.75);
+    gap: calc(var(--app-spacing) * 0.5);
     padding: calc(var(--app-spacing) * 0.75);
   }
 
@@ -166,49 +182,60 @@
   }
 
   .app-file-upload-thumbnail {
-    width: 48px;
+    width: 100%;
-    height: 48px;
+    aspect-ratio: 16 / 9;
+    padding: var(--app-spacing);
     border-radius: calc(var(--app-border-radius) * 0.5);
-    object-fit: cover;
+    object-fit: contain;
-    flex-shrink: 0;
+    object-position: center;
     border: 1px solid var(--app-muted-border-color);
-    background: var(--app-background-color);
+    background-color: var(--app-preview-checker-bg);
+    background-image:
+      linear-gradient(45deg, var(--app-preview-checker-fg) 25%, transparent 25%),
+      linear-gradient(-45deg, var(--app-preview-checker-fg) 25%, transparent 25%),
+      linear-gradient(45deg, transparent 75%, var(--app-preview-checker-fg) 75%),
+      linear-gradient(-45deg, transparent 75%, var(--app-preview-checker-fg) 75%);
+    background-size: 16px 16px;
+    background-position: 0 0, 0 8px, 8px -8px, -8px 0;
+    box-sizing: border-box;
   }
 
   .app-file-upload-file-icon {
-    width: 48px;
+    width: 100%;
-    height: 48px;
+    aspect-ratio: 16 / 9;
     border-radius: calc(var(--app-border-radius) * 0.5);
-    flex-shrink: 0;
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    font-size: var(--text-xl);
+    font-size: var(--text-3xl);
     color: var(--app-muted-color);
     background: var(--app-background-color);
     border: 1px solid var(--app-muted-border-color);
   }
 
   .app-file-upload-meta {
-    flex: 1;
-    min-width: 0;
     display: flex;
-    flex-direction: column;
+    align-items: center;
-    gap: 2px;
+    justify-content: space-between;
+    gap: calc(var(--app-spacing) * 0.5);
+    min-width: 0;
   }
 
   .app-file-upload-filename {
     font-size: var(--text-sm);
     font-weight: var(--font-medium);
     color: var(--app-contrast);
+    min-width: 0;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
+    flex: 1;
   }
 
   .app-file-upload-filesize {
     font-size: var(--text-xs);
     color: var(--app-muted-color);
+    flex-shrink: 0;
   }
 
   .app-file-upload-clear {

web/css/components/app-tenant-logo.css

@@ -0,0 +1,49 @@
+@layer components {
+  /* Topbar + login-hero logo. The server renders the theme-matching src
+     via appTenantLogoUrl($theme) / appAuthLogoUrl() — no CSS swap needed. */
+  .app-tenant-logo {
+    max-width: 160px;
+    height: 32px;
+    width: auto;
+    object-fit: contain;
+  }
+
+  .login-logo .app-tenant-logo {
+    max-width: 320px;
+    height: auto;
+    max-height: 96px;
+  }
+
+  .app-topbar-brand .app-tenant-logo {
+    max-height: calc(var(--app-topbar-height) - 1rem);
+  }
+
+  /* Tenant-edit "Tenant logos" slots — two Pico .grid columns. */
+  .tenant-logo-slot {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    min-width: 0;
+  }
+
+  .tenant-logo-slot-label {
+    font-size: var(--text-sm);
+    color: var(--app-muted-color);
+    margin: 0;
+  }
+
+  .tenant-logo-actions {
+    display: flex;
+    justify-content: flex-end;
+  }
+
+  .tenant-logo-actions button {
+    margin: 0;
+  }
+
+  .tenant-logo-readonly-preview {
+    max-width: 100%;
+    max-height: 120px;
+    object-fit: contain;
+  }
+}

web/css/layout/app-shell.css

@@ -975,7 +975,7 @@
 
   :is(button, [type="submit"], [type="button"], [role="button"]).outline,
   [type="reset"].outline {
-    --app-background-color: transparent;
+    --app-background-color: color-mix(in srgb, var(--app-color) 8%, transparent);
     --app-color: var(--app-primary);
     --app-border-color: var(--app-primary);
   }
@@ -992,7 +992,7 @@
       :active,
       :focus
     ) {
-    --app-background-color: transparent;
+    --app-background-color: color-mix(in srgb, var(--app-color) 18%, transparent);
     --app-color: var(--app-primary-hover);
     --app-border-color: var(--app-primary-hover);
   }
@@ -1029,6 +1029,37 @@
     --app-border-color: var(--app-secondary-hover);
   }
 
+  /* Stripe-style neutral chip — solid elevated surface, high-contrast text,
+     subtle neutral border, medium font-weight. Theme-aware via tokens:
+     in light mode a white chip with soft shadow, in dark mode a lifted
+     dark-gray chip with white text. */
+  :is(button, [type="submit"], [type="button"], [role="button"]).outline.secondary,
+  [type="reset"].outline {
+    --app-background-color: var(--app-button-neutral-bg);
+    --app-color: var(--app-button-neutral-color);
+    --app-border-color: var(--app-button-neutral-border);
+    box-shadow: var(--app-button-neutral-shadow);
+    font-weight: var(--font-medium);
+  }
+
+  :is(button, [type="submit"], [type="button"], [role="button"]).outline.secondary:is(
+      [aria-current]:not([aria-current="false"]),
+      :hover,
+      :active,
+      :focus
+    ),
+  [type="reset"].outline:is(
+      [aria-current]:not([aria-current="false"]),
+      :hover,
+      :active,
+      :focus
+    ) {
+    --app-background-color: var(--app-button-neutral-bg-hover);
+    --app-color: var(--app-button-neutral-color-hover);
+    --app-border-color: var(--app-button-neutral-border-hover);
+    box-shadow: var(--app-button-neutral-shadow-hover);
+  }
+
   :is(
       button,
       [type="submit"],
@@ -1371,7 +1402,6 @@
     content: " *";
   }
 
-  button[type="submit"],
   input:not([type="checkbox"], [type="radio"]),
   select,
   textarea {
@@ -2982,20 +3012,6 @@
     text-align: center;
   }
 
-  .primary {
-    box-shadow: rgba(0, 0, 0, 0.1) 0px 1px 2px;
-  }
-
-  .secondary {
-    border: 1px solid var(--app-border);
-    color: var(--app-muted-color);
-    box-shadow: rgba(0, 0, 0, 0.1) 0px 1px 2px;
-  }
-  .secondary:hover {
-    border: 1px solid var(--app-contrast);
-    color: var(--app-contrast);
-  }
-
   /* Loading state - global cursor and interaction blocking */
   body.is-loading {
     cursor: wait;

web/css/pages/app-login.css

@@ -3,6 +3,14 @@
     background: transparent;
   }
 
+  /* Login forms rely on a full-width primary submit button as the main CTA.
+     Global button[type="submit"] no longer defaults to width:100%, so we
+     restore that specifically for the auth flow. */
+  .login-main form > button[type="submit"],
+  .login-main form > .grid > button[type="submit"] {
+    width: 100%;
+  }
+
   /* ── Logo ── */
 
   .login-logo {

web/js/components/app-theme-toggle.js

@@ -6,6 +6,28 @@ import { postForm } from '../core/app-http.js';
 
 const setTheme = (theme) => {
   document.documentElement.dataset.theme = theme;
+  syncThemeAwareImages(theme);
+};
+
+/**
+ * Swap `src` on every <img data-theme-src> to the attribute matching the
+ * current theme — keeps tenant logos (topbar, login hero) in sync with the
+ * theme toggle without a full page reload.
+ */
+const syncThemeAwareImages = (theme) => {
+  const key = theme === 'dark' ? 'dark' : 'light';
+  const fallback = key === 'dark' ? 'light' : 'dark';
+  document.querySelectorAll('[data-theme-src]').forEach((img) => {
+    if (!(img instanceof HTMLImageElement)) {
+      return;
+    }
+    const next = img.dataset['src' + key.charAt(0).toUpperCase() + key.slice(1)]
+      || img.dataset['src' + fallback.charAt(0).toUpperCase() + fallback.slice(1)]
+      || '';
+    if (next && img.getAttribute('src') !== next) {
+      img.setAttribute('src', next);
+    }
+  });
 };
 
 const isDarkTheme = (theme) => theme === 'dark';

web/js/pages/admin-tenants-index.js

@@ -33,11 +33,11 @@ createListPageModule({
             sort: true,
             width: '75%',
             formatter: (cell, row) => {
-              const hasAvatar = cell?.has_avatar ? 1 : 0;
+              const hasLogo = cell?.has_logo ? 1 : 0;
               const uuid = encodeURIComponent(String(cell?.uuid ?? ''));
               let avatarHtml = '';
-              if (hasAvatar && uuid) {
+              if (hasLogo && uuid) {
-                const src = new URL(`admin/tenants/avatar-file?uuid=${uuid}&size=64`, appBase).toString();
+                const src = new URL(`admin/tenants/logo-file?uuid=${uuid}&theme=light&size=64`, appBase).toString();
                 avatarHtml = `<img class="grid-avatar grid-avatar-tenant" src="${src}" alt="" loading="lazy">`;
               } else {
                 const initials = escapeHtml(initialsForRow(row));
@@ -75,7 +75,7 @@ createListPageModule({
           {
             uuid: row.uuid ?? '',
             label: row.description ?? '',
-            has_avatar: row.has_avatar ? 1 : 0,
+            has_logo: row.has_logo ? 1 : 0,
           },
           row.total_users ?? 0,
           row.uuid,