From 69fca024d11b9e30f179552ad9fd6734188abe4c Mon Sep 17 00:00:00 2001
From: Kevin <kevin.davila@dotcms.com>
Date: Mon, 7 Sep 2026 23:23:49 -0500
Subject: [PATCH 1/7] Refactor dot-ai-config-detail component for improved UI
 and functionality

- Updated HTML structure for better layout and styling, including adjustments to class names and element properties.
- Enhanced loading and error handling with new components for better user feedback.
- Improved accessibility and readability by modifying text classes and labels.
- Updated icons to use Material Symbols for consistency across the application.
- Refactored dynamic field and settings card components for better organization and usability.
- Adjusted constants for AI capabilities to use more descriptive icon names.
---
 ...ot-ai-additional-properties.component.html |  16 +-
 .../dot-ai-capability-card.component.html     | 171 +++++++-------
 .../dot-ai-dynamic-field.component.html       |  16 +-
 .../dot-ai-settings-card.component.html       | 210 +++++++++---------
 .../dot-ai-config-detail.component.html       |  31 ++-
 .../dot-ai-config-detail.component.ts         |   9 +-
 .../dot-ai-config.constants.ts                |   6 +-
 .../WEB-INF/messages/Language.properties      |   4 +-
 8 files changed, 239 insertions(+), 224 deletions(-)

diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html
index 17cd78c4f37e..d541bdf08fde 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html
@@ -1,5 +1,5 @@
 <div class="flex flex-col gap-2">
-    <span class="text-xs font-medium text-gray-600">
+    <span class="text-sm font-semibold text-gray-600">
         {{ 'apps.ai.additional-properties.label' | dm }}
     </span>
 
@@ -10,20 +10,21 @@
                     <input
                         pInputText
                         formControlName="key"
-                        class="w-1/3 text-sm"
+                        class="w-2/5 font-mono text-sm"
                         [placeholder]="'apps.ai.additional-properties.key.placeholder' | dm" />
                     <input
                         pInputText
                         formControlName="value"
-                        class="flex-1 text-sm"
+                        class="flex-1 font-mono text-sm"
                         [placeholder]="'apps.ai.additional-properties.value.placeholder' | dm" />
                     <p-button
-                        icon="pi pi-trash"
                         [text]="true"
                         severity="secondary"
                         size="small"
                         [attr.aria-label]="'apps.ai.additional-properties.remove.aria-label' | dm"
-                        (onClick)="removeProperty(i)" />
+                        (onClick)="removeProperty(i)">
+                        <span class="material-symbols-outlined text-base">close</span>
+                    </p-button>
                 </div>
             }
         </div>
@@ -32,8 +33,9 @@
     <p-button
         [text]="true"
         size="small"
-        icon="pi pi-plus"
         [label]="'apps.ai.additional-properties.add.button' | dm"
         styleClass="self-start"
-        (onClick)="addProperty()" />
+        (onClick)="addProperty()">
+        <span class="material-symbols-outlined text-base">add</span>
+    </p-button>
 </div>
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
index 2ed003fd1428..9d834d33991a 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
@@ -1,13 +1,15 @@
-<div class="flex flex-col gap-4 rounded-lg border border-gray-200 bg-white p-4 shadow-sm">
+<div class="flex flex-col rounded-md border border-surface">
     <!-- Header -->
-    <div class="flex items-start gap-3">
-        <i class="text-lg text-gray-500" [class]="meta().icon"></i>
+    <div class="flex items-start gap-3 rounded-t-md bg-surface-50 px-5 py-4.5">
+        <span class="material-symbols-outlined mt-0.5 text-xl text-gray-600">
+            {{ meta().icon }}
+        </span>
         <div class="flex min-w-0 flex-1 flex-col gap-1">
             <div class="flex flex-wrap items-center gap-2">
-                <span class="text-sm font-semibold text-gray-900">{{ meta().title | dm }}</span>
+                <span class="font-semibold">{{ meta().title | dm }}</span>
                 <p-tag [value]="badgeLabel() | dm" [severity]="badgeSeverity()" />
             </div>
-            <span class="text-sm text-gray-500">{{ meta().description | dm }}</span>
+            <span class="text-sm text-gray-600">{{ meta().description | dm }}</span>
         </div>
         <p-toggleswitch
             [ngModel]="enabled()"
@@ -16,87 +18,98 @@
     </div>
 
     @if (enabled()) {
-        <!-- Provider grid -->
-        <div class="flex flex-col gap-2">
-            <span class="text-xs font-medium tracking-wide text-gray-600 uppercase">
-                {{ 'apps.ai.provider.label' | dm }}
-            </span>
-            <div class="grid grid-cols-4 gap-2">
-                @for (provider of orderedProviders(); track provider.provider) {
-                    <button
-                        type="button"
-                        class="flex flex-col items-start gap-0.5 rounded-md border p-2 text-left transition-colors"
-                        [class.border-indigo-500]="providerId() === provider.provider"
-                        [class.bg-indigo-50]="providerId() === provider.provider"
-                        [class.ring-1]="providerId() === provider.provider"
-                        [class.ring-indigo-500]="providerId() === provider.provider"
-                        [class.border-gray-200]="providerId() !== provider.provider"
-                        [class.cursor-not-allowed]="!isProviderSupported(provider)"
-                        [class.opacity-50]="!isProviderSupported(provider)"
-                        [disabled]="!isProviderSupported(provider)"
-                        [attr.data-testid]="'provider-tile-' + provider.provider"
-                        (click)="selectProvider(provider)">
-                        <span class="text-sm font-medium text-gray-800">
-                            {{ displayNameFor(provider.provider) }}
-                        </span>
-                        <span class="text-xs text-gray-400">{{ providerCaption(provider) }}</span>
-                    </button>
-                }
-            </div>
-        </div>
-
-        <!-- Visible fields (required, plus credentials/identity fields shown by default) -->
-        @if (visibleFields().length > 0) {
-            <div class="grid grid-cols-2 gap-4">
-                @for (field of visibleFields(); track field.name) {
-                    <dot-ai-dynamic-field [field]="field" [formGroup]="fieldsGroup()" />
-                }
+        <div class="flex flex-col gap-4.5 border-t border-surface px-5 pt-4.5 pb-5">
+            <!-- Provider grid -->
+            <div class="flex flex-col gap-2">
+                <span class="text-sm font-semibold text-gray-600">
+                    {{ 'apps.ai.provider.label' | dm }}
+                </span>
+                <div class="grid grid-cols-4 gap-2">
+                    @for (provider of orderedProviders(); track provider.provider) {
+                        <button
+                            type="button"
+                            class="flex flex-col items-start gap-0.5 rounded-md border px-3 py-2.5 text-left transition-colors"
+                            [class.border-primary]="providerId() === provider.provider"
+                            [class.bg-primary-50]="providerId() === provider.provider"
+                            [class.border-surface]="providerId() !== provider.provider"
+                            [class.cursor-not-allowed]="!isProviderSupported(provider)"
+                            [class.opacity-50]="!isProviderSupported(provider)"
+                            [disabled]="!isProviderSupported(provider)"
+                            [attr.data-testid]="'provider-tile-' + provider.provider"
+                            (click)="selectProvider(provider)">
+                            <span
+                                class="font-medium"
+                                [class.text-primary]="providerId() === provider.provider">
+                                {{ displayNameFor(provider.provider) }}
+                            </span>
+                            <small
+                                class="text-sm"
+                                [class.text-primary]="providerId() === provider.provider"
+                                [class.text-gray-600]="providerId() !== provider.provider">
+                                {{ providerCaption(provider) }}
+                            </small>
+                        </button>
+                    }
+                </div>
             </div>
-        }
 
-        <!-- Advanced (tuning fields + additional properties) -->
-        <p-panel
-            [toggleable]="true"
-            [toggler]="'header'"
-            [collapsed]="true"
-            [header]="
-                'apps.ai.advanced.optional.fields.header' | dm: [advancedFields().length.toString()]
-            "
-            transitionOptions="250ms cubic-bezier(0.4, 0, 0.2, 1)"
-            styleClass="text-sm">
-            <div class="flex flex-col gap-4">
-                @if (advancedFields().length > 0) {
-                    <div class="grid grid-cols-2 gap-4">
-                        @for (field of advancedFields(); track field.name) {
+            <!-- Visible fields (required, plus credentials/identity fields shown by default) -->
+            @if (visibleFields().length > 0) {
+                <div class="form">
+                    <div class="grid grid-cols-2 gap-x-4 gap-y-3.5">
+                        @for (field of visibleFields(); track field.name) {
                             <dot-ai-dynamic-field [field]="field" [formGroup]="fieldsGroup()" />
                         }
                     </div>
-                }
-                <dot-ai-additional-properties [properties]="additionalProperties" />
-            </div>
-        </p-panel>
+                </div>
+            }
 
-        <div class="flex flex-wrap items-center gap-3">
-            <p-button
-                [label]="'apps.ai.button.test-connection' | dm"
-                [outlined]="true"
-                [loading]="testing()"
-                severity="secondary"
-                size="small"
-                (onClick)="testConnection()" />
+            <!-- Advanced (tuning fields + additional properties) -->
+            <p-panel
+                [toggleable]="true"
+                [toggler]="'header'"
+                [collapsed]="true"
+                [header]="
+                    'apps.ai.advanced.optional.fields.header'
+                        | dm: [advancedFields().length.toString()]
+                "
+                transitionOptions="250ms cubic-bezier(0.4, 0, 0.2, 1)">
+                <div class="flex flex-col gap-4">
+                    @if (advancedFields().length > 0) {
+                        <div class="form">
+                            <div class="grid grid-cols-3 gap-x-4 gap-y-3.5">
+                                @for (field of advancedFields(); track field.name) {
+                                    <dot-ai-dynamic-field
+                                        [field]="field"
+                                        [formGroup]="fieldsGroup()" />
+                                }
+                            </div>
+                        </div>
+                    }
+                    <dot-ai-additional-properties [properties]="additionalProperties" />
+                </div>
+            </p-panel>
 
-            @if (testResult(); as result) {
-                <span
-                    class="flex items-center gap-1.5 text-sm"
-                    [class.text-green-600]="result.success"
-                    [class.text-red-600]="!result.success">
-                    <i
-                        class="pi"
-                        [class.pi-check-circle]="result.success"
-                        [class.pi-times-circle]="!result.success"></i>
-                    {{ result.message | dm }}
-                </span>
-            }
+            <div class="flex flex-wrap items-center gap-3">
+                <p-button
+                    [label]="'apps.ai.button.test-connection' | dm"
+                    [outlined]="true"
+                    [loading]="testing()"
+                    size="small"
+                    (onClick)="testConnection()" />
+
+                @if (testResult(); as result) {
+                    <span
+                        class="flex items-center gap-1.5 text-sm"
+                        [class.text-green-600]="result.success"
+                        [class.text-red-600]="!result.success">
+                        <span class="material-symbols-outlined text-base">
+                            {{ result.success ? 'check_circle' : 'error' }}
+                        </span>
+                        {{ result.message | dm }}
+                    </span>
+                }
+            </div>
         </div>
     }
 </div>
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
index b203d9e29bd0..befe4ac4ca0d 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
@@ -1,6 +1,6 @@
 <div class="field" [formGroup]="formGroup()">
-    <label [for]="field().name" class="text-xs font-medium text-gray-600">
-        {{ label() }}
+    <label [for]="field().name" class="flex items-center gap-1">
+        <span>{{ label() }}</span>
         @if (field().required) {
             <span class="text-red-500">*</span>
         }
@@ -14,7 +14,7 @@
                 [useGrouping]="false"
                 [invalid]="isInvalid()"
                 styleClass="w-full"
-                inputStyleClass="w-full text-sm" />
+                inputStyleClass="w-full" />
         }
         @case (DotAiProviderFieldType.SECRET) {
             @if (isMaskedSecret()) {
@@ -24,7 +24,7 @@
                     [id]="field().name"
                     [formControlName]="field().name"
                     [invalid]="isInvalid()"
-                    class="w-full text-sm" />
+                    class="w-full" />
             } @else {
                 <p-password
                     [inputId]="field().name"
@@ -33,7 +33,7 @@
                     [toggleMask]="true"
                     [invalid]="isInvalid()"
                     styleClass="w-full"
-                    inputStyleClass="w-full text-sm" />
+                    inputStyleClass="w-full" />
             }
         }
         @default {
@@ -42,11 +42,9 @@
                 [id]="field().name"
                 [formControlName]="field().name"
                 [invalid]="isInvalid()"
-                class="w-full text-sm" />
+                class="w-full" />
         }
     }
 
-    @if (field().hint) {
-        <small class="text-gray-500">{{ field().hint }}</small>
-    }
+    <small class="p-field-hint block min-h-5">{{ field().hint }}</small>
 </div>
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
index 5f6eabc2f243..2e99a77f7c32 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
@@ -1,120 +1,124 @@
-<div class="flex flex-col gap-4 rounded-lg border border-gray-200 bg-white p-4 shadow-sm">
-    <div class="flex items-start gap-3">
-        <i class="pi pi-cog text-lg text-gray-500"></i>
+<div class="flex flex-col rounded-md border border-surface">
+    <div class="flex items-start gap-3 rounded-t-md bg-surface-50 px-5 py-4.5">
+        <span class="material-symbols-outlined mt-0.5 text-xl text-gray-600">tune</span>
         <div class="flex min-w-0 flex-1 flex-col gap-1">
-            <span class="text-sm font-semibold text-gray-900">
+            <span class="font-semibold">
                 {{ 'apps.ai.settings.title' | dm }}
             </span>
-            <span class="text-sm text-gray-500">
+            <span class="text-sm text-gray-600">
                 {{ 'apps.ai.settings.description' | dm }}
             </span>
         </div>
     </div>
 
-    <form [formGroup]="form" class="flex flex-col gap-4">
-        <div class="field">
-            <label for="rolePrompt" class="text-xs font-medium text-gray-600">
-                {{ 'apps.ai.settings.role-prompt.label' | dm }}
-            </label>
-            <textarea
-                pTextarea
-                id="rolePrompt"
-                formControlName="rolePrompt"
-                rows="3"
-                class="w-full resize-y text-sm"
-                [placeholder]="'apps.ai.settings.role-prompt.placeholder' | dm"></textarea>
-            <small class="text-gray-500">
-                {{ 'apps.ai.settings.role-prompt.hint' | dm }}
-            </small>
-        </div>
-
-        <div class="grid grid-cols-2 gap-4">
+    <div class="flex flex-col gap-4.5 border-t border-surface px-5 pt-4.5 pb-5">
+        <form [formGroup]="form" class="form">
             <div class="field">
-                <label for="textPrompt" class="text-xs font-medium text-gray-600">
-                    {{ 'apps.ai.settings.text-prompt.label' | dm }}
+                <label for="rolePrompt">
+                    {{ 'apps.ai.settings.role-prompt.label' | dm }}
                 </label>
-                <input
-                    pInputText
-                    id="textPrompt"
-                    formControlName="textPrompt"
-                    class="w-full text-sm"
-                    [placeholder]="'apps.ai.settings.text-prompt.placeholder' | dm" />
+                <textarea
+                    pTextarea
+                    id="rolePrompt"
+                    formControlName="rolePrompt"
+                    rows="3"
+                    class="w-full resize-y"
+                    [placeholder]="'apps.ai.settings.role-prompt.placeholder' | dm"></textarea>
+                <small class="p-field-hint">
+                    {{ 'apps.ai.settings.role-prompt.hint' | dm }}
+                </small>
             </div>
-            <div class="field">
-                <label for="imagePrompt" class="text-xs font-medium text-gray-600">
-                    {{ 'apps.ai.settings.image-prompt.label' | dm }}
-                </label>
-                <input
-                    pInputText
-                    id="imagePrompt"
-                    formControlName="imagePrompt"
-                    class="w-full text-sm"
-                    [placeholder]="'apps.ai.settings.image-prompt.placeholder' | dm" />
+
+            <div class="grid grid-cols-2 gap-x-4 gap-y-3.5">
+                <div class="field">
+                    <label for="textPrompt">
+                        {{ 'apps.ai.settings.text-prompt.label' | dm }}
+                    </label>
+                    <input
+                        pInputText
+                        id="textPrompt"
+                        formControlName="textPrompt"
+                        class="w-full"
+                        [placeholder]="'apps.ai.settings.text-prompt.placeholder' | dm" />
+                </div>
+                <div class="field">
+                    <label for="imagePrompt">
+                        {{ 'apps.ai.settings.image-prompt.label' | dm }}
+                    </label>
+                    <input
+                        pInputText
+                        id="imagePrompt"
+                        formControlName="imagePrompt"
+                        class="w-full"
+                        [placeholder]="'apps.ai.settings.image-prompt.placeholder' | dm" />
+                </div>
             </div>
-        </div>
 
-        <div class="field w-1/2">
-            <label for="imageSize" class="text-xs font-medium text-gray-600">
-                {{ 'apps.ai.settings.image-size.label' | dm }}
-            </label>
-            <p-select
-                inputId="imageSize"
-                formControlName="imageSize"
-                [options]="imageSizeOptions"
-                optionLabel="label"
-                optionValue="value"
-                styleClass="w-full text-sm" />
-        </div>
-    </form>
+            <div class="field w-1/2">
+                <label for="imageSize">
+                    {{ 'apps.ai.settings.image-size.label' | dm }}
+                </label>
+                <p-select
+                    inputId="imageSize"
+                    formControlName="imageSize"
+                    [options]="imageSizeOptions"
+                    optionLabel="label"
+                    optionValue="value"
+                    styleClass="w-full" />
+            </div>
+        </form>
 
-    <p-panel
-        [toggleable]="true"
-        [toggler]="'header'"
-        [collapsed]="true"
-        [header]="'apps.ai.settings.advanced.header' | dm: [advancedFields.length.toString()]"
-        transitionOptions="250ms cubic-bezier(0.4, 0, 0.2, 1)">
-        <div class="flex flex-col gap-4">
-            <form [formGroup]="advancedForm" class="grid grid-cols-2 gap-4">
-                @for (settingsField of advancedFields; track settingsField.key) {
-                    @if (settingsField.type === 'checkbox') {
-                        <div class="field col-span-2 flex items-center gap-2">
-                            <p-checkbox
-                                [inputId]="settingsField.key"
-                                [formControlName]="settingsField.key"
-                                [binary]="true" />
-                            <label [for]="settingsField.key" class="text-sm text-gray-700">
-                                {{ settingsField.label | dm }}
-                            </label>
-                        </div>
-                    } @else {
-                        <div class="field">
-                            <label
-                                [for]="settingsField.key"
-                                class="text-xs font-medium text-gray-600">
-                                {{ settingsField.label | dm }}
-                            </label>
-                            @if (settingsField.type === 'number') {
-                                <p-inputnumber
-                                    [inputId]="settingsField.key"
-                                    [formControlName]="settingsField.key"
-                                    [useGrouping]="false"
-                                    styleClass="w-full"
-                                    inputStyleClass="w-full text-sm" />
+        <p-panel
+            [toggleable]="true"
+            [toggler]="'header'"
+            [collapsed]="true"
+            [header]="'apps.ai.settings.advanced.header' | dm: [advancedFields.length.toString()]"
+            transitionOptions="250ms cubic-bezier(0.4, 0, 0.2, 1)">
+            <div class="flex flex-col gap-4">
+                <div class="form">
+                    <form [formGroup]="advancedForm" class="grid grid-cols-3 gap-x-4 gap-y-3.5">
+                        @for (settingsField of advancedFields; track settingsField.key) {
+                            @if (settingsField.type === 'checkbox') {
+                                <div class="field form-checkbox col-span-3">
+                                    <p-checkbox
+                                        [inputId]="settingsField.key"
+                                        [formControlName]="settingsField.key"
+                                        [binary]="true" />
+                                    <label [for]="settingsField.key">
+                                        {{ settingsField.label | dm }}
+                                    </label>
+                                </div>
                             } @else {
-                                <input
-                                    pInputText
-                                    [id]="settingsField.key"
-                                    [formControlName]="settingsField.key"
-                                    class="w-full text-sm" />
-                            }
-                            @if (settingsField.hint) {
-                                <small class="text-gray-500">{{ settingsField.hint | dm }}</small>
+                                <div class="field">
+                                    <label [for]="settingsField.key">
+                                        {{ settingsField.label | dm }}
+                                    </label>
+                                    @if (settingsField.type === 'number') {
+                                        <p-inputnumber
+                                            [inputId]="settingsField.key"
+                                            [formControlName]="settingsField.key"
+                                            [useGrouping]="false"
+                                            styleClass="w-full"
+                                            inputStyleClass="w-full" />
+                                    } @else {
+                                        <input
+                                            pInputText
+                                            [id]="settingsField.key"
+                                            [formControlName]="settingsField.key"
+                                            class="w-full" />
+                                    }
+                                    <small class="p-field-hint block min-h-5">
+                                        @if (settingsField.hint) {
+                                            {{ settingsField.hint | dm }}
+                                        }
+                                    </small>
+                                </div>
                             }
-                        </div>
-                    }
-                }
-            </form>
-            <dot-ai-additional-properties [properties]="additionalProperties" />
-        </div>
-    </p-panel>
+                        }
+                    </form>
+                </div>
+                <dot-ai-additional-properties [properties]="additionalProperties" />
+            </div>
+        </p-panel>
+    </div>
 </div>
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
index cd7a9c7eb34f..7b140dd20d55 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
@@ -1,27 +1,23 @@
-<div class="min-h-0 flex-1 overflow-y-auto bg-white p-6 [scrollbar-gutter:stable]">
-    <div class="mx-auto flex max-w-3xl flex-col gap-4">
+<div class="min-h-0 flex-1 overflow-y-auto p-6 [scrollbar-gutter:stable]">
+    <div class="mx-auto flex max-w-4xl flex-col gap-4">
         <div class="mb-2">
-            <h2 class="m-0 text-xl font-semibold text-gray-900">
+            <h2 class="m-0 font-semibold text-gray-900">
                 {{ 'apps.ai.config.title' | dm }}
             </h2>
-            <p class="mt-1 mb-0 text-sm text-gray-500">
-                {{ 'apps.ai.config.subtitle' | dm }}
+            <p class="mt-1 mb-0 max-w-[60%] text-gray-600">
+                {{ 'apps.ai.config.first.subtitle' | dm }}
+            </p>
+            <p class="mt-1 mb-0 max-w-[60%] text-gray-600">
+                {{ 'apps.ai.config.second.subtitle' | dm }}
             </p>
-            @if (siteName()) {
-                <p class="mt-1 mb-0 text-sm text-gray-500">
-                    {{ 'apps.ai.config.site' | dm: [siteName()] }}
-                </p>
-            }
         </div>
 
         @if (loading()) {
-            <div class="flex items-center justify-center py-12 text-sm text-gray-400">
-                {{ 'apps.ai.loading' | dm }}
+            <div class="flex items-center justify-center py-12">
+                <dot-spinner />
             </div>
         } @else if (loadFailed()) {
-            <div class="flex items-center justify-center py-12 text-sm text-red-500">
-                {{ 'apps.ai.error.load' | dm }}
-            </div>
+            <p-message severity="error" [text]="'apps.ai.error.load' | dm" />
         } @else {
             @for (meta of capabilityMeta; track meta.capability) {
                 <dot-ai-capability-card
@@ -37,10 +33,9 @@ <h2 class="m-0 text-xl font-semibold text-gray-900">
     </div>
 </div>
 
-<div
-    class="flex shrink-0 items-center justify-end gap-4 border-t border-gray-200 bg-white px-6 py-3">
+<div class="flex shrink-0 items-center justify-end gap-4 border-t border-surface px-6 py-3">
     @if (dirty()) {
-        <span class="mr-auto text-sm text-gray-500">{{ 'apps.ai.unsaved.changes' | dm }}</span>
+        <small class="mr-auto text-gray-600">{{ 'apps.ai.unsaved.changes' | dm }}</small>
         <p-button
             [label]="'apps.ai.button.cancel' | dm"
             [text]="true"
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.ts b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.ts
index aed582e485ec..6e8a6793d420 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.ts
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.ts
@@ -16,6 +16,7 @@ import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import { ActivatedRoute } from '@angular/router';
 
 import { ButtonModule } from 'primeng/button';
+import { MessageModule } from 'primeng/message';
 
 import { map } from 'rxjs/operators';
 
@@ -31,7 +32,7 @@ import {
     DotMessageSeverity,
     DotMessageType
 } from '@dotcms/dotcms-models';
-import { DotMessagePipe } from '@dotcms/ui';
+import { DotMessagePipe, DotSpinnerComponent } from '@dotcms/ui';
 import { isEqual } from '@dotcms/utils';
 
 import {
@@ -44,13 +45,15 @@ import { CAPABILITY_META } from './dot-ai-config.constants';
 @Component({
     selector: 'dot-ai-config-detail',
     templateUrl: './dot-ai-config-detail.component.html',
-    host: { class: 'flex h-full w-full flex-col overflow-hidden bg-white' },
+    host: { class: 'flex h-full w-full flex-col overflow-hidden' },
     changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         ButtonModule,
         DotAiCapabilityCardComponent,
         DotAiSettingsCardComponent,
-        DotMessagePipe
+        DotMessagePipe,
+        DotSpinnerComponent,
+        MessageModule
     ]
 })
 export class DotAiConfigDetailComponent implements OnInit {
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config.constants.ts b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config.constants.ts
index 416dc11ffa61..7a0c06eb5e29 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config.constants.ts
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config.constants.ts
@@ -35,21 +35,21 @@ export const CAPABILITY_META: DotAiCapabilityMeta[] = [
         sectionKey: 'chat',
         title: 'apps.ai.capability.chat.title',
         description: 'apps.ai.capability.chat.description',
-        icon: 'pi pi-comments'
+        icon: 'forum'
     },
     {
         capability: DotAiCapability.EMBEDDINGS,
         sectionKey: 'embeddings',
         title: 'apps.ai.capability.embeddings.title',
         description: 'apps.ai.capability.embeddings.description',
-        icon: 'pi pi-sitemap'
+        icon: 'scatter_plot'
     },
     {
         capability: DotAiCapability.IMAGE,
         sectionKey: 'image',
         title: 'apps.ai.capability.image.title',
         description: 'apps.ai.capability.image.description',
-        icon: 'pi pi-image'
+        icon: 'image'
     }
 ];
 
diff --git a/dotCMS/src/main/webapp/WEB-INF/messages/Language.properties b/dotCMS/src/main/webapp/WEB-INF/messages/Language.properties
index f047cbd87d92..aca6c185f832 100644
--- a/dotCMS/src/main/webapp/WEB-INF/messages/Language.properties
+++ b/dotCMS/src/main/webapp/WEB-INF/messages/Language.properties
@@ -5619,8 +5619,8 @@ apps.content-analytics.generated.string.placeholder=Generated string will appear
 apps.content-analytics.generated.string.confirm.replace.header=Confirm Replacement
 apps.content-analytics.generated.string.confirm.replace.message=The current value will be replaced: "{0}". Are you sure you want to generate a new string?
 apps.ai.config.title=dotAI Configuration
-apps.ai.config.subtitle=Configure the AI providers used for chat, embeddings and image generation. Each capability is configured independently, so you can mix providers.
-apps.ai.config.site=Site: {0}
+apps.ai.config.first.subtitle=Configure the AI providers used for chat, embeddings and image generation.
+apps.ai.config.second.subtitle=Each capability is configured independently, so you can mix providers.
 apps.ai.loading=Loading...
 apps.ai.unsaved.changes=Unsaved changes
 apps.ai.button.cancel=Cancel

From 9ecc6e871fbc567faab59049e93e7ae2f7f86ad2 Mon Sep 17 00:00:00 2001
From: Kevin <kevin.davila@dotcms.com>
Date: Tue, 8 Sep 2026 09:57:08 -0500
Subject: [PATCH 2/7] Enhance dot-ai-config-detail component UI and
 functionality

- Updated text classes for improved readability and consistency across the component.
- Adjusted HTML structure to enhance layout, including margin and padding modifications.
- Implemented conditional rendering for hints in dynamic fields and settings card for better user experience.
- Standardized text color for additional properties and capability card labels to ensure uniformity.
---
 .../dot-ai-additional-properties.component.html        |  2 +-
 .../dot-ai-capability-card.component.html              |  2 +-
 .../dot-ai-dynamic-field.component.html                |  5 +++--
 .../dot-ai-settings-card.component.html                | 10 +++++-----
 .../dot-ai-config-detail.component.html                |  2 +-
 5 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html
index d541bdf08fde..321d12a9cea6 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html
@@ -1,5 +1,5 @@
 <div class="flex flex-col gap-2">
-    <span class="text-sm font-semibold text-gray-600">
+    <span class="text-sm font-semibold text-gray-950">
         {{ 'apps.ai.additional-properties.label' | dm }}
     </span>
 
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
index 9d834d33991a..3a1a7172bee4 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
@@ -21,7 +21,7 @@
         <div class="flex flex-col gap-4.5 border-t border-surface px-5 pt-4.5 pb-5">
             <!-- Provider grid -->
             <div class="flex flex-col gap-2">
-                <span class="text-sm font-semibold text-gray-600">
+                <span class="text-sm font-semibold text-gray-950">
                     {{ 'apps.ai.provider.label' | dm }}
                 </span>
                 <div class="grid grid-cols-4 gap-2">
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
index befe4ac4ca0d..9fdaf9cc206d 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
@@ -45,6 +45,7 @@
                 class="w-full" />
         }
     }
-
-    <small class="p-field-hint block min-h-5">{{ field().hint }}</small>
+    @if (field().hint) {
+        <small class="p-field-hint block min-h-5">{{ field().hint }}</small>
+    }
 </div>
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
index 2e99a77f7c32..2a455420eb42 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
@@ -75,7 +75,7 @@
             [header]="'apps.ai.settings.advanced.header' | dm: [advancedFields.length.toString()]"
             transitionOptions="250ms cubic-bezier(0.4, 0, 0.2, 1)">
             <div class="flex flex-col gap-4">
-                <div class="form">
+                <div class="form mb-2">
                     <form [formGroup]="advancedForm" class="grid grid-cols-3 gap-x-4 gap-y-3.5">
                         @for (settingsField of advancedFields; track settingsField.key) {
                             @if (settingsField.type === 'checkbox') {
@@ -107,11 +107,11 @@
                                             [formControlName]="settingsField.key"
                                             class="w-full" />
                                     }
-                                    <small class="p-field-hint block min-h-5">
-                                        @if (settingsField.hint) {
+                                    @if (settingsField.hint) {
+                                        <small class="p-field-hint block min-h-5">
                                             {{ settingsField.hint | dm }}
-                                        }
-                                    </small>
+                                        </small>
+                                    }
                                 </div>
                             }
                         }
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
index 7b140dd20d55..fdacffea9e5e 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
@@ -1,7 +1,7 @@
 <div class="min-h-0 flex-1 overflow-y-auto p-6 [scrollbar-gutter:stable]">
     <div class="mx-auto flex max-w-4xl flex-col gap-4">
         <div class="mb-2">
-            <h2 class="m-0 font-semibold text-gray-900">
+            <h2 class="m-0 text-2xl font-semibold text-gray-900">
                 {{ 'apps.ai.config.title' | dm }}
             </h2>
             <p class="mt-1 mb-0 max-w-[60%] text-gray-600">

From 84569d72e25fd08e10148997af906fff73a9eccb Mon Sep 17 00:00:00 2001
From: Kevin <kevin.davila@dotcms.com>
Date: Tue, 8 Sep 2026 11:09:15 -0500
Subject: [PATCH 3/7] Refactor dot-ai-config-detail component layout for
 improved UI consistency

- Updated HTML structure across multiple components to enhance layout and styling, including the use of flexbox for better alignment.
- Changed class names to ensure uniformity and improved readability in forms and fields.
- Enhanced the visual hierarchy by adjusting spacing and grouping of elements within the settings and capability cards.
---
 .../dot-ai-capability-card.component.html        |  4 ++--
 .../dot-ai-dynamic-field.component.html          |  2 +-
 .../dot-ai-settings-card.component.html          | 16 ++++++++--------
 3 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
index 3a1a7172bee4..7014db6e2838 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
@@ -55,7 +55,7 @@
 
             <!-- Visible fields (required, plus credentials/identity fields shown by default) -->
             @if (visibleFields().length > 0) {
-                <div class="form">
+                <div class="w-full">
                     <div class="grid grid-cols-2 gap-x-4 gap-y-3.5">
                         @for (field of visibleFields(); track field.name) {
                             <dot-ai-dynamic-field [field]="field" [formGroup]="fieldsGroup()" />
@@ -76,7 +76,7 @@
                 transitionOptions="250ms cubic-bezier(0.4, 0, 0.2, 1)">
                 <div class="flex flex-col gap-4">
                     @if (advancedFields().length > 0) {
-                        <div class="form">
+                        <div class="w-full">
                             <div class="grid grid-cols-3 gap-x-4 gap-y-3.5">
                                 @for (field of advancedFields(); track field.name) {
                                     <dot-ai-dynamic-field
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
index 9fdaf9cc206d..e064db60e70a 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
@@ -1,4 +1,4 @@
-<div class="field" [formGroup]="formGroup()">
+<div class="flex flex-col gap-2" [formGroup]="formGroup()">
     <label [for]="field().name" class="flex items-center gap-1">
         <span>{{ label() }}</span>
         @if (field().required) {
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
index 2a455420eb42..252fbbf377af 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
@@ -12,8 +12,8 @@
     </div>
 
     <div class="flex flex-col gap-4.5 border-t border-surface px-5 pt-4.5 pb-5">
-        <form [formGroup]="form" class="form">
-            <div class="field">
+        <form [formGroup]="form" class="flex w-full flex-col gap-5">
+            <div class="flex flex-col gap-2">
                 <label for="rolePrompt">
                     {{ 'apps.ai.settings.role-prompt.label' | dm }}
                 </label>
@@ -30,7 +30,7 @@
             </div>
 
             <div class="grid grid-cols-2 gap-x-4 gap-y-3.5">
-                <div class="field">
+                <div class="flex flex-col gap-2">
                     <label for="textPrompt">
                         {{ 'apps.ai.settings.text-prompt.label' | dm }}
                     </label>
@@ -41,7 +41,7 @@
                         class="w-full"
                         [placeholder]="'apps.ai.settings.text-prompt.placeholder' | dm" />
                 </div>
-                <div class="field">
+                <div class="flex flex-col gap-2">
                     <label for="imagePrompt">
                         {{ 'apps.ai.settings.image-prompt.label' | dm }}
                     </label>
@@ -54,7 +54,7 @@
                 </div>
             </div>
 
-            <div class="field w-1/2">
+            <div class="flex w-1/2 flex-col gap-1">
                 <label for="imageSize">
                     {{ 'apps.ai.settings.image-size.label' | dm }}
                 </label>
@@ -75,11 +75,11 @@
             [header]="'apps.ai.settings.advanced.header' | dm: [advancedFields.length.toString()]"
             transitionOptions="250ms cubic-bezier(0.4, 0, 0.2, 1)">
             <div class="flex flex-col gap-4">
-                <div class="form mb-2">
+                <div class="mb-2 w-full">
                     <form [formGroup]="advancedForm" class="grid grid-cols-3 gap-x-4 gap-y-3.5">
                         @for (settingsField of advancedFields; track settingsField.key) {
                             @if (settingsField.type === 'checkbox') {
-                                <div class="field form-checkbox col-span-3">
+                                <div class="col-span-3 flex flex-row items-center gap-2">
                                     <p-checkbox
                                         [inputId]="settingsField.key"
                                         [formControlName]="settingsField.key"
@@ -89,7 +89,7 @@
                                     </label>
                                 </div>
                             } @else {
-                                <div class="field">
+                                <div class="flex flex-col gap-2">
                                     <label [for]="settingsField.key">
                                         {{ settingsField.label | dm }}
                                     </label>

From 7b3cfcfb848a972231a7f9def7edc89b65dcbd45 Mon Sep 17 00:00:00 2001
From: Kevin <kevin.davila@dotcms.com>
Date: Tue, 8 Sep 2026 23:58:00 -0500
Subject: [PATCH 4/7] Refactor dot-ai-config-detail component for improved text
 layout

- Removed unnecessary max-width classes from subtitle paragraphs to enhance text display.
- Simplified HTML structure for better readability and consistency across the component.
---
 .../dot-ai-config-detail/dot-ai-config-detail.component.html  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
index fdacffea9e5e..e465a49d81f9 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
@@ -4,10 +4,10 @@
             <h2 class="m-0 text-2xl font-semibold text-gray-900">
                 {{ 'apps.ai.config.title' | dm }}
             </h2>
-            <p class="mt-1 mb-0 max-w-[60%] text-gray-600">
+            <p class="mt-1 mb-0 text-gray-600">
                 {{ 'apps.ai.config.first.subtitle' | dm }}
             </p>
-            <p class="mt-1 mb-0 max-w-[60%] text-gray-600">
+            <p class="mt-1 mb-0 text-gray-600">
                 {{ 'apps.ai.config.second.subtitle' | dm }}
             </p>
         </div>

From 75a819e694a2d82e5be3d585ed70ba824c008445 Mon Sep 17 00:00:00 2001
From: Kevin <kevin.davila@dotcms.com>
Date: Wed, 9 Sep 2026 00:02:24 -0500
Subject: [PATCH 5/7] Update form field guidelines and styling standards

- Removed outdated form markup examples from CLAUDE.md and replaced with a reference to the updated Form Fields documentation.
- Expanded the Form Fields section in STYLING_STANDARDS.md to clarify conventions and rules for field markup, including spacing, label handling, and component usage.
- Emphasized the importance of adhering to established guidelines to ensure consistency across the application.
---
 core-web/CLAUDE.md                 | 18 +++-------
 docs/frontend/STYLING_STANDARDS.md | 53 +++++++++++++++++++++++++++++-
 2 files changed, 56 insertions(+), 15 deletions(-)

diff --git a/core-web/CLAUDE.md b/core-web/CLAUDE.md
index d72e48a9a7c9..66eadb570b80 100644
--- a/core-web/CLAUDE.md
+++ b/core-web/CLAUDE.md
@@ -83,20 +83,10 @@ spectator.setInput('prop', value);           // ALWAYS use setInput
 
 ### Form Markup
 
-Always wrap form fields with this structure for consistent styling:
-
-```html
-<form class="form">
-  <div class="field">
-    <label for="name">Name</label>
-    <input pInputText id="name" />
-  </div>
-  <div class="field">
-    <label for="site">Site</label>
-    <p-select id="site" [options]="sites()" />
-  </div>
-</form>
-```
+See [Form Fields](docs/frontend/STYLING_STANDARDS.md#form-fields) for the current field-layout,
+typography, and hint-handling rules — do not hand-roll a form wrapper from memory or copy an
+existing form without checking it first. Different areas of the app (e.g. `edit-content`) have
+diverged in the past; the doc is the tie-breaker.
 
 ## Portlet Development
 
diff --git a/docs/frontend/STYLING_STANDARDS.md b/docs/frontend/STYLING_STANDARDS.md
index 01f4c4ab898d..c57095c5940c 100644
--- a/docs/frontend/STYLING_STANDARDS.md
+++ b/docs/frontend/STYLING_STANDARDS.md
@@ -11,7 +11,7 @@
 ```html
 <!-- ✅ Layout with Tailwind -->
 <div class="flex items-center gap-4 p-4">
-  <span class="text-sm font-semibold text-color">Title</span>
+  <span class="font-semibold">Title</span>
   <p-button label="Save" />
 </div>
 
@@ -24,6 +24,12 @@
 
 <!-- ❌ NEVER: custom CSS for what Tailwind handles -->
 <div class="my-custom-flex-container">...</div>
+
+<!-- ❌ NEVER: hand-rolled "card" — this is p-card reinvented -->
+<div class="flex flex-col rounded-md border border-surface">
+  <div class="flex items-start gap-3 rounded-t-md bg-surface-50 px-5 py-4.5">...</div>
+  <div class="border-t border-surface px-5 pt-4.5 pb-5">...</div>
+</div>
 ```
 
 ## When Custom SCSS Is Acceptable
@@ -113,6 +119,51 @@ PrimeNG ships two visually similar but semantically different components. Pick b
 - **Never use `p-chip` for purely informational status** — use `p-tag` with a `severity`.
 - **Never add Tailwind `!important` color overrides** (`bg-green-100!`, `text-red-700!`, etc.) to PrimeNG components. Rely on native `severity` plus the preset color tokens in `theme.config.ts`.
 
+## Form Fields
+
+The codebase currently has **more than one field-markup convention** (e.g. the global `.form`/
+`.field` classes in `apps/dotcms-ui/src/style.css`, and `edit-content`'s own
+`dot-card-field`/`dot-card-field-label` components). They do not render identically — before
+writing a new form, check how the most relevant *existing* surface (usually `edit-content`, the
+most actively maintained field UI) actually looks, don't just grep for a `.form`/`.field` example
+and copy it. Do not extend the global `.form`/`.field` classes to new features.
+
+Regardless of which markup you use, these rules apply to every field:
+
+- **No `text-*` size class on body copy or labels.** Labels and normal UI text inherit the
+  PrimeNG default size/weight — do not add `text-sm`, `text-base`, `font-medium`, etc. to make a
+  label "look right." The **only** text allowed `text-sm` is hint/error text under a field, and it
+  pairs with a muted/semantic color (`text-gray-500` for hints, `text-red-500` for errors).
+- **Label-to-control gap is `gap-2`.** A field wrapper is `flex flex-col gap-2` — label, then
+  control, nothing wider.
+- **A field reserves space for its hint only when it has one.** Render the hint conditionally
+  (`@if (field.hint) { <small class="text-sm text-gray-500">...</small> }`) — never a permanent
+  empty slot or a fixed `min-h-*` "for alignment" when there is no hint to show.
+- **Required marker is a literal `*`**, shown only `@if (field.required)`, styled `text-red-500`,
+  placed next to the label. Don't introduce a second, CSS-class-driven required mechanism for new
+  forms unless you are already extending a surface that uses one.
+- **Prefer PrimeNG components over hand-rolled equivalents**: `p-card` (not a bordered div with a
+  hand-built header bar), `p-panel`/`p-accordion` for collapsible sections, `p-toggleswitch` for
+  on/off toggles, `p-button` for actions. See the anti-pattern example above.
+
+```html
+<!-- ✅ Field -->
+<div class="flex flex-col gap-2">
+  <label for="name">Name</label>
+  <input pInputText id="name" [formControlName]="'name'" />
+  @if (hint) {
+    <small class="text-sm text-gray-500">{{ hint }}</small>
+  }
+</div>
+
+<!-- ❌ NEVER: sized/weighted label, permanently reserved hint slot -->
+<div class="flex flex-col gap-1">
+  <label for="name" class="text-sm font-medium">Name</label>
+  <input pInputText id="name" [formControlName]="'name'" />
+  <small class="text-sm text-gray-500 min-h-5">{{ hint }}</small>
+</div>
+```
+
 ## See also
 - [ANGULAR_STANDARDS.md](./ANGULAR_STANDARDS.md) — Component rules, templates
 - [docs/frontend/README.md](./README.md) — Index of all frontend docs

From 886aefac7f7b28fa4b083c48fdb20d6359c5ae49 Mon Sep 17 00:00:00 2001
From: Kevin <kevin.davila@dotcms.com>
Date: Wed, 9 Sep 2026 17:52:25 -0500
Subject: [PATCH 6/7] fix(dotai): address provider-config UI review feedback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Card borders were broken at the corners. A rounded parent does not clip its
children, so the header's square bottom corners painted over the arc and erased
the border stroke on a not-configured card, which renders header-only. The
capability card now clips with `overflow-hidden`; the settings card cannot (its
`p-select` overlay renders inline under `overlayAppendTo: 'self'`) so its header
takes the border's inner radius instead. Both carry the reason in a comment.

Other findings from review:

- `p-field-hint` is descendant-scoped to `.form`, which this tree has none of,
  so all three hints were rendering unstyled. Use the utilities directly.
- An icon projected as bare content into `p-button` does not satisfy `hasIcon`,
  so the remove button had lost `p-button-icon-only` and took the padding of a
  labelled button. Moved to `<ng-template #icon>`.
- `aria-label` on the `<p-button>` host never reached the real `<button>`; the
  icon-only button had no accessible name. Use the `ariaLabel` input.
- `bg-white` dropped from the host was only surviving on the browser's default
  canvas — nothing in the ancestor chain paints one. Restored as `bg-surface-0`.
- Field wrapper gap, the dead `siteName` computed, the orphaned
  `apps.ai.loading` key, and a PrimeIcons value left in a spec fixture.

Adds the missing specs for `dot-ai-settings-card` and
`dot-ai-additional-properties`, an assertion on `CAPABILITY_META`, and render
assertions for the loading and error branches — the existing specs ran with
`detectChanges: false` and never queried the DOM, so they stayed green through
a full template rewrite.

STYLING_STANDARDS.md: restore the `.form`/`.field` section as Legacy, including
that `.p-error` resolves to nothing in the built app (its stylesheet import is
commented out) and that `p-field-hint` only works inside `.form`; correct a
documented `dotFieldRequired` usage that the directive does not implement; and
document the rounded-container and `p-button` icon pitfalls.

No functional change: no logic, validation, or saved payload was touched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 ...ot-ai-additional-properties.component.html |  19 +-
 ...ai-additional-properties.component.spec.ts | 119 ++++++++++
 .../dot-ai-capability-card.component.html     |   9 +-
 .../dot-ai-capability-card.component.spec.ts  |   2 +-
 .../dot-ai-dynamic-field.component.html       |   2 +-
 .../dot-ai-settings-card.component.html       |  29 ++-
 .../dot-ai-settings-card.component.spec.ts    | 215 ++++++++++++++++++
 .../dot-ai-config-detail.component.html       |   7 +-
 .../dot-ai-config-detail.component.spec.ts    |  33 ++-
 .../dot-ai-config-detail.component.ts         |  11 +-
 .../dot-ai-config.constants.spec.ts           |  25 +-
 docs/frontend/STYLING_STANDARDS.md            | 140 ++++++++++--
 .../WEB-INF/messages/Language.properties      |   1 -
 13 files changed, 573 insertions(+), 39 deletions(-)
 create mode 100644 core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.spec.ts
 create mode 100644 core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.spec.ts

diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html
index 321d12a9cea6..5ac6ee850115 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.html
@@ -11,19 +11,29 @@
                         pInputText
                         formControlName="key"
                         class="w-2/5 font-mono text-sm"
+                        [attr.data-testid]="'property-key-' + i"
                         [placeholder]="'apps.ai.additional-properties.key.placeholder' | dm" />
                     <input
                         pInputText
                         formControlName="value"
                         class="flex-1 font-mono text-sm"
+                        [attr.data-testid]="'property-value-' + i"
                         [placeholder]="'apps.ai.additional-properties.value.placeholder' | dm" />
+                    <!-- Projected through `#icon`, not as bare content: p-button derives
+                         `p-button-icon-only` (the square, label-less shape) from the `icon` input
+                         or an `#icon` template, and bare content satisfies neither. -->
                     <p-button
                         [text]="true"
                         severity="secondary"
                         size="small"
-                        [attr.aria-label]="'apps.ai.additional-properties.remove.aria-label' | dm"
+                        [ariaLabel]="'apps.ai.additional-properties.remove.aria-label' | dm"
+                        [attr.data-testid]="'remove-property-' + i"
                         (onClick)="removeProperty(i)">
-                        <span class="material-symbols-outlined text-base">close</span>
+                        <ng-template #icon>
+                            <span class="material-symbols-outlined text-base" aria-hidden="true">
+                                close
+                            </span>
+                        </ng-template>
                     </p-button>
                 </div>
             }
@@ -35,7 +45,10 @@
         size="small"
         [label]="'apps.ai.additional-properties.add.button' | dm"
         styleClass="self-start"
+        data-testid="add-property"
         (onClick)="addProperty()">
-        <span class="material-symbols-outlined text-base">add</span>
+        <ng-template #icon>
+            <span class="material-symbols-outlined text-base" aria-hidden="true">add</span>
+        </ng-template>
     </p-button>
 </div>
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.spec.ts b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.spec.ts
new file mode 100644
index 000000000000..b7d76b44c674
--- /dev/null
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-additional-properties/dot-ai-additional-properties.component.spec.ts
@@ -0,0 +1,119 @@
+import { byTestId, createComponentFactory, Spectator } from '@openng/spectator/jest';
+
+import { FormArray, FormControl, FormGroup } from '@angular/forms';
+
+import { DotMessageService } from '@dotcms/data-access';
+import { MockDotMessageService } from '@dotcms/utils-testing';
+
+import {
+    DotAiAdditionalPropertiesComponent,
+    DotAiAdditionalPropertyGroup
+} from './dot-ai-additional-properties.component';
+
+describe('DotAiAdditionalPropertiesComponent', () => {
+    let spectator: Spectator<DotAiAdditionalPropertiesComponent>;
+    let properties: FormArray<DotAiAdditionalPropertyGroup>;
+
+    const createComponent = createComponentFactory({
+        component: DotAiAdditionalPropertiesComponent,
+        providers: [{ provide: DotMessageService, useValue: new MockDotMessageService({}) }]
+    });
+
+    function propertyRow(key: string, value: string): DotAiAdditionalPropertyGroup {
+        return new FormGroup({
+            key: new FormControl(key, { nonNullable: true }),
+            value: new FormControl(value, { nonNullable: true })
+        });
+    }
+
+    /**
+     * Rows have to exist before the first render. The component is OnPush and `properties` is a
+     * signal holding the FormArray, so pushing into that array from outside mutates it without
+     * changing the signal and without marking the component dirty. In the app the rows arrive the
+     * same way — hydrated into the array by the parent card before it renders.
+     */
+    function setup(rows: DotAiAdditionalPropertyGroup[] = []): void {
+        properties = new FormArray<DotAiAdditionalPropertyGroup>(rows);
+        spectator = createComponent({ props: { properties } });
+    }
+
+    /** p-button renders its own `<button>`; the testid sits on the `<p-button>` host. */
+    function clickButton(testId: string): void {
+        const button = spectator.query(byTestId(testId))?.querySelector('button');
+        expect(button).toBeTruthy();
+        spectator.click(button as HTMLElement);
+    }
+
+    describe('rendering', () => {
+        it('renders one key/value pair per control in the array', () => {
+            setup([propertyRow('listenerIndexer', 'true'), propertyRow('customFlag', 'yes')]);
+
+            expect(spectator.query(byTestId('property-key-0'))).toExist();
+            expect(spectator.query(byTestId('property-value-0'))).toExist();
+            expect(spectator.query(byTestId('property-key-1'))).toExist();
+            expect(spectator.query(byTestId('remove-property-1'))).toExist();
+        });
+
+        it('renders no rows and only the add button when the array is empty', () => {
+            setup();
+
+            expect(spectator.query(byTestId('property-key-0'))).not.toExist();
+            expect(spectator.query(byTestId('add-property'))).toExist();
+        });
+
+        it('binds each row to its own control', () => {
+            setup([propertyRow('listenerIndexer', 'true')]);
+
+            const key = spectator.query(byTestId('property-key-0')) as HTMLInputElement;
+            const value = spectator.query(byTestId('property-value-0')) as HTMLInputElement;
+
+            expect(key.value).toBe('listenerIndexer');
+            expect(value.value).toBe('true');
+        });
+    });
+
+    // The icons are projected through `<ng-template #icon>` rather than the `icon` input, which is
+    // a different p-button rendering path — these cover that clicks still reach the handlers, and
+    // that the icon-only button keeps the shape that path is required for.
+    describe('add / remove', () => {
+        it('appends an empty row when the add button is pressed', () => {
+            setup();
+
+            clickButton('add-property');
+
+            expect(properties.length).toBe(1);
+            expect(properties.at(0).value).toEqual({ key: '', value: '' });
+        });
+
+        it('removes only the pressed row', () => {
+            setup([propertyRow('keep', 'a'), propertyRow('drop', 'b')]);
+
+            clickButton('remove-property-1');
+
+            expect(properties.length).toBe(1);
+            expect(properties.at(0).value.key).toBe('keep');
+        });
+
+        it('keeps the remove button icon-only, which needs the `#icon` template path', () => {
+            setup([propertyRow('listenerIndexer', 'true')]);
+
+            const button = spectator.query(byTestId('remove-property-0'))?.querySelector('button');
+
+            // `p-button-icon-only` is derived from `hasIcon && !label`, and `hasIcon` counts the
+            // `icon` input or an `#icon` template — bare projected content satisfies neither.
+            expect(button?.classList.contains('p-button-icon-only')).toBe(true);
+        });
+    });
+
+    describe('accessible names', () => {
+        it('names the remove button, which has no visible label', () => {
+            setup([propertyRow('listenerIndexer', 'true')]);
+
+            const button = spectator.query(byTestId('remove-property-0'))?.querySelector('button');
+
+            expect(button?.getAttribute('aria-label')).toBe(
+                'apps.ai.additional-properties.remove.aria-label'
+            );
+        });
+    });
+});
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
index 7014db6e2838..6f31d4952581 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.html
@@ -1,6 +1,11 @@
-<div class="flex flex-col rounded-md border border-surface">
+<!-- `overflow-hidden` so the header fill is clipped to the border's inner curve. Without it the
+     header's square corners paint over the rounded corners: when the capability is off the header
+     is the only child, and its bottom corners erase the border stroke along both bottom arcs.
+     Safe here because nothing in this card opens a PrimeNG overlay (`p-password` runs with
+     `[feedback]="false"`) — see `dot-ai-settings-card`, which holds a `p-select` and cannot. -->
+<div class="flex flex-col overflow-hidden rounded-md border border-surface">
     <!-- Header -->
-    <div class="flex items-start gap-3 rounded-t-md bg-surface-50 px-5 py-4.5">
+    <div class="flex items-start gap-3 bg-surface-50 px-5 py-4.5">
         <span class="material-symbols-outlined mt-0.5 text-xl text-gray-600">
             {{ meta().icon }}
         </span>
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.spec.ts b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.spec.ts
index a84a9afd9214..2716e72ff489 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.spec.ts
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-capability-card/dot-ai-capability-card.component.spec.ts
@@ -23,7 +23,7 @@ describe('DotAiCapabilityCardComponent', () => {
         sectionKey: 'chat',
         title: 'apps.ai.capability.chat.title',
         description: 'apps.ai.capability.chat.description',
-        icon: 'pi pi-comments'
+        icon: 'forum'
     };
 
     const openAiProvider: DotAiProviderMetadata = {
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
index e064db60e70a..4b3f78bcbd32 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-dynamic-field/dot-ai-dynamic-field.component.html
@@ -46,6 +46,6 @@
         }
     }
     @if (field().hint) {
-        <small class="p-field-hint block min-h-5">{{ field().hint }}</small>
+        <small class="text-sm text-gray-500">{{ field().hint }}</small>
     }
 </div>
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
index 252fbbf377af..aa6e6b219e64 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.html
@@ -1,5 +1,11 @@
+<!-- The header fill needs the border's *inner* radius (the 1px border eats into it); matching the
+     parent's `rounded-md` leaves a wedge of page showing at the top corners. This card can't use
+     `overflow-hidden` like `dot-ai-capability-card` does — it holds a `p-select`, whose overlay
+     renders inline (`overlayAppendTo: 'self'`) and would be clipped. It doesn't need to: its body
+     is always present and has no fill, so the bottom corners have nothing to paint over them. -->
 <div class="flex flex-col rounded-md border border-surface">
-    <div class="flex items-start gap-3 rounded-t-md bg-surface-50 px-5 py-4.5">
+    <div
+        class="flex items-start gap-3 rounded-t-[calc(var(--radius-md)-1px)] bg-surface-50 px-5 py-4.5">
         <span class="material-symbols-outlined mt-0.5 text-xl text-gray-600">tune</span>
         <div class="flex min-w-0 flex-1 flex-col gap-1">
             <span class="font-semibold">
@@ -24,7 +30,7 @@
                     rows="3"
                     class="w-full resize-y"
                     [placeholder]="'apps.ai.settings.role-prompt.placeholder' | dm"></textarea>
-                <small class="p-field-hint">
+                <small class="text-sm text-gray-500">
                     {{ 'apps.ai.settings.role-prompt.hint' | dm }}
                 </small>
             </div>
@@ -54,7 +60,7 @@
                 </div>
             </div>
 
-            <div class="flex w-1/2 flex-col gap-1">
+            <div class="flex w-1/2 flex-col gap-2">
                 <label for="imageSize">
                     {{ 'apps.ai.settings.image-size.label' | dm }}
                 </label>
@@ -83,7 +89,10 @@
                                     <p-checkbox
                                         [inputId]="settingsField.key"
                                         [formControlName]="settingsField.key"
-                                        [binary]="true" />
+                                        [binary]="true"
+                                        [attr.data-testid]="
+                                            'settings-checkbox-' + settingsField.key
+                                        " />
                                     <label [for]="settingsField.key">
                                         {{ settingsField.label | dm }}
                                     </label>
@@ -99,16 +108,22 @@
                                             [formControlName]="settingsField.key"
                                             [useGrouping]="false"
                                             styleClass="w-full"
-                                            inputStyleClass="w-full" />
+                                            inputStyleClass="w-full"
+                                            [attr.data-testid]="
+                                                'settings-number-' + settingsField.key
+                                            " />
                                     } @else {
                                         <input
                                             pInputText
                                             [id]="settingsField.key"
                                             [formControlName]="settingsField.key"
-                                            class="w-full" />
+                                            class="w-full"
+                                            [attr.data-testid]="
+                                                'settings-text-' + settingsField.key
+                                            " />
                                     }
                                     @if (settingsField.hint) {
-                                        <small class="p-field-hint block min-h-5">
+                                        <small class="text-sm text-gray-500">
                                             {{ settingsField.hint | dm }}
                                         </small>
                                     }
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.spec.ts b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.spec.ts
new file mode 100644
index 000000000000..b702e520221a
--- /dev/null
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/components/dot-ai-settings-card/dot-ai-settings-card.component.spec.ts
@@ -0,0 +1,215 @@
+import { byTestId, createComponentFactory, Spectator } from '@openng/spectator/jest';
+
+import { DotMessageService } from '@dotcms/data-access';
+import { MockDotMessageService } from '@dotcms/utils-testing';
+
+import { DotAiSettingsCardComponent, DotAiSettingsValue } from './dot-ai-settings-card.component';
+
+import { SETTINGS_ADVANCED_FIELDS } from '../../dot-ai-config.constants';
+
+describe('DotAiSettingsCardComponent', () => {
+    let spectator: Spectator<DotAiSettingsCardComponent>;
+
+    const createComponent = createComponentFactory({
+        component: DotAiSettingsCardComponent,
+        providers: [{ provide: DotMessageService, useValue: new MockDotMessageService({}) }],
+        detectChanges: false
+    });
+
+    function setup(initialValue: DotAiSettingsValue | null = null): void {
+        spectator = createComponent({ props: { initialValue } });
+        spectator.detectChanges();
+    }
+
+    describe('advanced field rendering', () => {
+        // The advanced grid branches on `type`, and the three branches render different controls.
+        // These pin each branch to a field that actually uses it in SETTINGS_ADVANCED_FIELDS.
+        it('renders a checkbox for a checkbox-typed field', () => {
+            setup();
+
+            expect(spectator.query(byTestId('settings-checkbox-debugLogging'))).toExist();
+            expect(spectator.query(byTestId('settings-number-debugLogging'))).not.toExist();
+        });
+
+        it('renders a number input for a number-typed field', () => {
+            setup();
+
+            expect(spectator.query(byTestId('settings-number-embeddingsSplitAtTokens'))).toExist();
+            expect(
+                spectator.query(byTestId('settings-text-embeddingsSplitAtTokens'))
+            ).not.toExist();
+        });
+
+        it('renders a text input for a text-typed field', () => {
+            setup();
+
+            expect(spectator.query(byTestId('settings-text-embeddingsFileExtensions'))).toExist();
+            expect(
+                spectator.query(byTestId('settings-number-embeddingsFileExtensions'))
+            ).not.toExist();
+        });
+
+        it('renders every advanced field exactly once, in one of the three branches', () => {
+            setup();
+
+            SETTINGS_ADVANCED_FIELDS.forEach(({ key, type }) => {
+                const rendered = [
+                    spectator.query(byTestId(`settings-checkbox-${key}`)),
+                    spectator.query(byTestId(`settings-number-${key}`)),
+                    spectator.query(byTestId(`settings-text-${key}`))
+                ].filter(Boolean);
+
+                expect({ key, count: rendered.length }).toEqual({ key, count: 1 });
+                expect(spectator.query(byTestId(`settings-${type}-${key}`))).toExist();
+            });
+        });
+
+        it('gives every advanced control a label bound to it', () => {
+            setup();
+
+            SETTINGS_ADVANCED_FIELDS.forEach(({ key }) => {
+                const label = spectator.query(`label[for="${key}"]`);
+                expect({ key, labelled: !!label }).toEqual({ key, labelled: true });
+            });
+        });
+    });
+
+    describe('checkbox defaults', () => {
+        // `defaultValue` exists so an untouched checkbox doesn't silently save the wrong value
+        // when the key was never set on the backend.
+        it('seeds checkbox controls from their backend default', () => {
+            setup();
+
+            expect(spectator.component.advancedForm.get('embeddingsDeleteOldOnUpdate')?.value).toBe(
+                true
+            );
+            expect(spectator.component.advancedForm.get('debugLogging')?.value).toBe(false);
+        });
+
+        it('lets a saved value override the default', () => {
+            setup({ embeddingsDeleteOldOnUpdate: false });
+
+            expect(spectator.component.advancedForm.get('embeddingsDeleteOldOnUpdate')?.value).toBe(
+                false
+            );
+        });
+    });
+
+    describe('hydration', () => {
+        it('patches common and advanced values into their own forms', () => {
+            setup({ rolePrompt: 'You are a bot', embeddingsSplitAtTokens: 512 });
+
+            expect(spectator.component.form.get('rolePrompt')?.value).toBe('You are a bot');
+            expect(spectator.component.advancedForm.get('embeddingsSplitAtTokens')?.value).toBe(
+                512
+            );
+        });
+
+        it('routes an unknown key into additional properties', () => {
+            setup({ someCustomKey: 'custom' });
+
+            expect(spectator.component.additionalProperties.length).toBe(1);
+            expect(spectator.component.additionalProperties.at(0).value).toEqual({
+                key: 'someCustomKey',
+                value: 'custom'
+            });
+        });
+
+        // Regression: `imageSize` is rendered by the fixed <p-select>, not by the advanced list.
+        // If it were not in `knownKeys` it would hydrate into both the dropdown and a duplicate
+        // additional-property row — and since additional properties are applied last on save,
+        // that stale row would silently overwrite whatever the user picked.
+        it('does not duplicate a common field into additional properties', () => {
+            setup({ imageSize: '1024x1024', rolePrompt: 'x', textPrompt: 'y', imagePrompt: 'z' });
+
+            expect(spectator.component.additionalProperties.length).toBe(0);
+            expect(spectator.component.form.get('imageSize')?.value).toBe('1024x1024');
+        });
+
+        it('stringifies a non-string saved value instead of corrupting it via String()', () => {
+            setup({ listenerIndexer: { enabled: true, batchSize: 10 } });
+
+            // `getRawValue()` rather than `.value`: a FormGroup's `value` is a Partial, so the
+            // field reads as `string | undefined` and does not satisfy `JSON.parse`.
+            const value = spectator.component.additionalProperties.at(0).getRawValue().value;
+
+            expect(value).not.toBe('[object Object]');
+            expect(JSON.parse(value)).toEqual({ enabled: true, batchSize: 10 });
+        });
+    });
+
+    describe('buildPayloadSection', () => {
+        it('includes common and advanced values', () => {
+            setup({ rolePrompt: 'You are a bot', embeddingsSplitAtTokens: 512 });
+
+            const section = spectator.component.buildPayloadSection();
+
+            expect(section['rolePrompt']).toBe('You are a bot');
+            expect(section['embeddingsSplitAtTokens']).toBe(512);
+        });
+
+        it('omits empty values so an untouched field is not saved as blank', () => {
+            setup();
+
+            const section = spectator.component.buildPayloadSection();
+
+            expect('rolePrompt' in section).toBe(false);
+            expect('textPrompt' in section).toBe(false);
+        });
+
+        it('round-trips a hydrated object additional property back out', () => {
+            setup({ listenerIndexer: { enabled: true, batchSize: 10 } });
+
+            const section = spectator.component.buildPayloadSection();
+
+            expect(section['listenerIndexer']).toEqual({ enabled: true, batchSize: 10 });
+        });
+
+        it('keeps a checkbox default in the payload even when untouched', () => {
+            setup();
+
+            const section = spectator.component.buildPayloadSection();
+
+            expect(section['embeddingsDeleteOldOnUpdate']).toBe(true);
+        });
+    });
+
+    describe('changed output', () => {
+        it('emits when a common field changes', () => {
+            setup();
+            const changed = jest.fn();
+            spectator.output('changed').subscribe(changed);
+
+            spectator.component.form.patchValue({ rolePrompt: 'new' });
+
+            expect(changed).toHaveBeenCalled();
+        });
+
+        it('emits when an advanced field changes', () => {
+            setup();
+            const changed = jest.fn();
+            spectator.output('changed').subscribe(changed);
+
+            spectator.component.advancedForm.patchValue({ debugLogging: true });
+
+            expect(changed).toHaveBeenCalled();
+        });
+
+        // Loading a saved config must not make the page announce "Unsaved changes". Today that is
+        // guaranteed twice over: `ngOnInit` subscribes to `valueChanges` only *after* hydrating,
+        // and hydration patches with `emitEvent: false`. Asserting the silence alone would pass
+        // even with both protections removed, so the second half proves the subscription this
+        // stayed silent through is actually live.
+        it("stays silent while hydrating, then reports the user's own edits", () => {
+            spectator = createComponent({ props: { initialValue: { rolePrompt: 'saved' } } });
+            const changed = jest.fn();
+            spectator.output('changed').subscribe(changed);
+
+            spectator.detectChanges();
+            expect(changed).not.toHaveBeenCalled();
+
+            spectator.component.form.patchValue({ rolePrompt: 'edited by the user' });
+            expect(changed).toHaveBeenCalledTimes(1);
+        });
+    });
+});
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
index e465a49d81f9..8fd46d5d5f56 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.html
@@ -14,10 +14,13 @@ <h2 class="m-0 text-2xl font-semibold text-gray-900">
 
         @if (loading()) {
             <div class="flex items-center justify-center py-12">
-                <dot-spinner />
+                <dot-spinner data-testid="loading-indicator" />
             </div>
         } @else if (loadFailed()) {
-            <p-message severity="error" [text]="'apps.ai.error.load' | dm" />
+            <p-message
+                severity="error"
+                [text]="'apps.ai.error.load' | dm"
+                data-testid="error-message" />
         } @else {
             @for (meta of capabilityMeta; track meta.capability) {
                 <dot-ai-capability-card
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.spec.ts b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.spec.ts
index bbbc8ebdc924..6d9f79efbbc3 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.spec.ts
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.spec.ts
@@ -1,5 +1,5 @@
-import { createComponentFactory, mockProvider, Spectator } from '@openng/spectator/jest';
-import { of, throwError } from 'rxjs';
+import { byTestId, createComponentFactory, mockProvider, Spectator } from '@openng/spectator/jest';
+import { NEVER, of, throwError } from 'rxjs';
 
 import { NO_ERRORS_SCHEMA } from '@angular/core';
 import { ActivatedRoute } from '@angular/router';
@@ -84,4 +84,33 @@ describe('DotAiConfigDetailComponent', () => {
             expect(spectator.component.loading()).toBe(false);
         });
     });
+
+    // The specs above assert signal values against an unrendered component, so they stay green
+    // through any template change. These render the two states instead, so the loading and error
+    // branches are checked against the markup that actually ships.
+    describe('load-state rendering', () => {
+        it('renders the spinner and no error while the config is still loading', () => {
+            spectator = createComponent();
+            spectator.inject(DotAiService).getProviders.mockReturnValue(NEVER);
+            spectator.inject(DotAiService).getConfig.mockReturnValue(NEVER);
+
+            spectator.detectChanges();
+
+            expect(spectator.query(byTestId('loading-indicator'))).toExist();
+            expect(spectator.query(byTestId('error-message'))).not.toExist();
+        });
+
+        it('renders the error message and no spinner when the load fails', () => {
+            spectator = createComponent();
+            spectator.inject(DotAiService).getProviders.mockReturnValue(of(providers));
+            spectator
+                .inject(DotAiService)
+                .getConfig.mockReturnValue(throwError(() => new Error('network error')));
+
+            spectator.detectChanges();
+
+            expect(spectator.query(byTestId('error-message'))).toExist();
+            expect(spectator.query(byTestId('loading-indicator'))).not.toExist();
+        });
+    });
 });
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.ts b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.ts
index 6e8a6793d420..f50deaffd6c0 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.ts
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.ts
@@ -5,7 +5,6 @@ import {
     Component,
     DestroyRef,
     OnInit,
-    computed,
     effect,
     inject,
     signal,
@@ -45,7 +44,11 @@ import { CAPABILITY_META } from './dot-ai-config.constants';
 @Component({
     selector: 'dot-ai-config-detail',
     templateUrl: './dot-ai-config-detail.component.html',
-    host: { class: 'flex h-full w-full flex-col overflow-hidden' },
+    // `bg-surface-0` is the tokenized white the rest of this screen's chrome is built from. It has
+    // to be declared here: the wrapper this route renders into (`main-legacy.component.html`) sets
+    // no background, and neither does `html`/`body` — without it the page only looks right by
+    // falling back to the browser's default canvas.
+    host: { class: 'flex h-full w-full flex-col overflow-hidden bg-surface-0' },
     changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         ButtonModule,
@@ -77,10 +80,6 @@ export class DotAiConfigDetailComponent implements OnInit {
     readonly initialSettings = signal<Record<string, unknown> | null>(null);
     readonly providers = signal<DotAiProviderMetadata[]>([]);
 
-    /** The site this configuration applies to — already resolved by the route (see the
-     *  `dotAiConfigDetailResolver`), just never surfaced in the redesigned page. */
-    readonly siteName = computed(() => this.app()?.sites?.[0]?.name ?? null);
-
     private readonly capabilityCards = viewChildren(DotAiCapabilityCardComponent);
     private readonly settingsCard = viewChild(DotAiSettingsCardComponent);
 
diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config.constants.spec.ts b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config.constants.spec.ts
index 005d64b0f571..8b06b8b498f1 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config.constants.spec.ts
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config.constants.spec.ts
@@ -2,7 +2,30 @@ import { FormControl, FormGroup } from '@angular/forms';
 
 import { DotAiProviderFieldType } from '@dotcms/dotcms-models';
 
-import { isFieldAlwaysVisible, requiredUnlessValidator } from './dot-ai-config.constants';
+import {
+    CAPABILITY_META,
+    isFieldAlwaysVisible,
+    requiredUnlessValidator
+} from './dot-ai-config.constants';
+
+describe('CAPABILITY_META', () => {
+    // `icon` is interpolated as the text content of a `material-symbols-outlined` span
+    // (`dot-ai-capability-card.component.html`), not bound as a CSS class. A leftover PrimeIcons
+    // value still compiles and still renders — as the literal string "pi pi-comments".
+    it('carries a Material Symbols ligature name, never a PrimeIcons class', () => {
+        CAPABILITY_META.forEach(({ capability, icon }) => {
+            expect({ capability, icon: !!icon }).toEqual({ capability, icon: true });
+            expect(icon).not.toMatch(/(^|\s)pi(-|\s|$)/);
+            expect(icon).not.toContain(' ');
+        });
+    });
+
+    it('covers every capability exactly once', () => {
+        const capabilities = CAPABILITY_META.map((meta) => meta.capability);
+
+        expect(new Set(capabilities).size).toBe(capabilities.length);
+    });
+});
 
 describe('isFieldAlwaysVisible', () => {
     it('returns true for a required field regardless of type', () => {
diff --git a/docs/frontend/STYLING_STANDARDS.md b/docs/frontend/STYLING_STANDARDS.md
index c57095c5940c..798aa6fa1f83 100644
--- a/docs/frontend/STYLING_STANDARDS.md
+++ b/docs/frontend/STYLING_STANDARDS.md
@@ -3,7 +3,7 @@
 ## Priority: Tailwind CSS + PrimeNG Theme
 
 - **Use Tailwind utility classes** for layout, spacing, typography, colors, sizing, flexbox, and grid. Avoid custom SCSS when a Tailwind class exists.
-- **Use PrimeNG components** instead of building custom UI (e.g. `p-button`, `p-inputText`, `p-card`, `p-dialog`, `p-table`). PrimeNG theme tokens handle component styling automatically.
+- **Use PrimeNG components** instead of building custom UI (e.g. `p-button`, `p-card`, `p-dialog`, `p-table`; text inputs are the `pInputText` *directive* on a native `<input>`, not a component). PrimeNG theme tokens handle component styling automatically.
 - **Minimize custom CSS** — component `.scss` files should be the exception, not the default. Most components should need zero or near-zero custom styles.
 
 ## Tailwind Usage
@@ -24,14 +24,41 @@
 
 <!-- ❌ NEVER: custom CSS for what Tailwind handles -->
 <div class="my-custom-flex-container">...</div>
+```
+
+### Rounding a bordered container
+
+A rounded parent does **not** clip its children. A child with its own background — a card's tinted
+header band — therefore paints into the rounded corners, and the symptom depends on its radius:
+
+- **Child corner is square** (e.g. the header's *bottom* corners when it is the last child): the
+  fill covers the corner arc and **erases the border stroke** for several pixels. This reads as a
+  card whose border is broken or missing along part of the curve.
+- **Child radius equals the parent's**: the border eats 1px of it, so the child curves more
+  sharply than the space available and leaves a wedge of the page showing through.
+
+```html
+<!-- ✅ Preferred: the parent clips the fill to the border's inner curve, all four corners -->
+<div class="flex flex-col overflow-hidden rounded-md border border-surface">
+  <div class="bg-surface-50 px-5 py-4.5">...</div>
+</div>
 
-<!-- ❌ NEVER: hand-rolled "card" — this is p-card reinvented -->
+<!-- ✅ When you cannot clip: give the child the border's inner radius explicitly -->
 <div class="flex flex-col rounded-md border border-surface">
-  <div class="flex items-start gap-3 rounded-t-md bg-surface-50 px-5 py-4.5">...</div>
+  <div class="rounded-t-[calc(var(--radius-md)-1px)] bg-surface-50 px-5 py-4.5">...</div>
   <div class="border-t border-surface px-5 pt-4.5 pb-5">...</div>
 </div>
 ```
 
+`overflow-hidden` is the better fix — it is state-independent, so a header that is sometimes the
+last child (a collapsed card) stays correct. Reach for the explicit inner radius **only** when the
+container holds a PrimeNG overlay component (`p-select`, `p-datepicker`, `p-autocomplete`…): this
+app runs with `overlayAppendTo: 'self'` (PrimeNG's default), those panels render inline, and an
+`overflow-hidden` ancestor clips them. In that case the child must also round every corner it can
+be adjacent to — an unrounded corner against the parent's arc is the erased-border case above.
+
+Both cards in `dot-ai-config-detail` show the two branches, with the reason in a comment.
+
 ## When Custom SCSS Is Acceptable
 
 Custom SCSS is only allowed for:
@@ -130,21 +157,36 @@ and copy it. Do not extend the global `.form`/`.field` classes to new features.
 
 Regardless of which markup you use, these rules apply to every field:
 
-- **No `text-*` size class on body copy or labels.** Labels and normal UI text inherit the
-  PrimeNG default size/weight — do not add `text-sm`, `text-base`, `font-medium`, etc. to make a
-  label "look right." The **only** text allowed `text-sm` is hint/error text under a field, and it
-  pairs with a muted/semantic color (`text-gray-500` for hints, `text-red-500` for errors).
+- **No `text-*` size class on the label of a form control.** A control's label inherits the
+  PrimeNG default size/weight — do not add `text-sm`, `text-base`, `font-medium`, etc. to make it
+  "look right." The **only** text allowed `text-sm` is hint/error text under a field, and it pairs
+  with a muted/semantic color (`text-gray-500` for hints, `text-red-500` for errors).
+
+  This rule is about control labels. Section headings, group labels over a set of controls, and
+  card/section descriptions are a different typographic level and may size themselves
+  (`text-sm font-semibold` for a group label, `text-sm text-gray-600` for secondary copy).
+- **Use one gray scale.** `text-gray-*` and `text-surface-*` are separate scales
+  (`--color-gray-*` maps to `--p-gray-*`, not to surface). `text-gray-*` is the app's majority
+  convention — don't mix the two in one screen.
 - **Label-to-control gap is `gap-2`.** A field wrapper is `flex flex-col gap-2` — label, then
   control, nothing wider.
 - **A field reserves space for its hint only when it has one.** Render the hint conditionally
   (`@if (field.hint) { <small class="text-sm text-gray-500">...</small> }`) — never a permanent
   empty slot or a fixed `min-h-*` "for alignment" when there is no hint to show.
-- **Required marker is a literal `*`**, shown only `@if (field.required)`, styled `text-red-500`,
-  placed next to the label. Don't introduce a second, CSS-class-driven required mechanism for new
-  forms unless you are already extending a surface that uses one.
-- **Prefer PrimeNG components over hand-rolled equivalents**: `p-card` (not a bordered div with a
-  hand-built header bar), `p-panel`/`p-accordion` for collapsible sections, `p-toggleswitch` for
-  on/off toggles, `p-button` for actions. See the anti-pattern example above.
+- **Required marker.** For a form whose required fields are fixed, use the `dotFieldRequired`
+  directive (see below). For a form built from runtime metadata, use a literal `*` shown
+  `@if (field.required)` and styled `text-red-500` — the directive cannot track a field whose
+  requiredness changes after the first render.
+- **Prefer PrimeNG components over hand-rolled equivalents**: `p-panel`/`p-accordion` for
+  collapsible sections, `p-toggleswitch` for on/off toggles, `p-button` for actions. For a card
+  container, check what each one actually gives you before hand-rolling: `p-panel` is a border +
+  radius + a `surface.50` header band with its own divider, while `p-card` is overridden in
+  `theme.config.ts` to a plain bordered box (`shadow: none`, `1rem` padding) with **no** header
+  band — they are not interchangeable.
+- **A custom icon in a `p-button` goes in an `<ng-template #icon>`, not as bare content.**
+  `p-button-icon-only` — the square, label-less shape — is derived from the `icon` input or an
+  `#icon` template; bare projected content satisfies neither, so an icon-only button silently
+  renders with the padding of a labelled one.
 
 ```html
 <!-- ✅ Field -->
@@ -164,6 +206,78 @@ Regardless of which markup you use, these rules apply to every field:
 </div>
 ```
 
+### Legacy: the global `.form` / `.field` classes
+
+**Do not use these in new work.** They are documented here because 88 existing templates use them,
+and because two of the class names silently do nothing outside their scope.
+
+`apps/dotcms-ui/src/style.css` defines:
+
+| Class | What it does | Scope |
+|-------|--------------|-------|
+| `.form` | `w-full`, 5-unit rhythm between direct children | the form element |
+| `.form .field` | column layout, `gap-1` between label and control | one field |
+| `.form .field > label` | `text-sm font-medium` | labels, automatically |
+| `.form .p-field-hint` | `text-sm text-gray-500` | a field's hint |
+| `.form .p-field-error` | `text-sm text-red-500` | a field's error |
+
+Three things to know before you copy a template that uses them:
+
+- **`p-field-hint` and `p-field-error` only work inside `.form`.** Both rules are
+  descendant-scoped. On an element with no `.form` ancestor the class matches nothing and the text
+  renders at inherited size and color — no error, no warning, just wrong. Outside a `.form`, write
+  the utilities directly: `<small class="text-sm text-gray-500">`.
+- **The `p-` on those two is ours, not PrimeNG's**, as it is on `p-label-input-required`. PrimeNG
+  21 claims neither name. Not every `p-` class in a template comes from the library.
+- **`.p-error` is dead — never add it, and replace it when you touch a file that has it.** It is
+  defined only in `libs/dotcms-scss/angular/dotcms-theme/utils/_validation.scss`, reachable only
+  through `dotcms-theme/theme.scss`, and that import is **commented out** in
+  `libs/dotcms-scss/angular/styles.scss`. Nothing else the app builds defines it, so an element
+  carrying it renders as plain inherited text rather than red. There are live usages in
+  `dot-experiments` and `dot-content-types-edit` today whose validation errors do not look like
+  errors.
+
+For a field-level error use `<p-message severity="error" variant="simple">` — the `simple` variant
+renders as colored text with no box — or `<small class="text-sm text-red-500">`. A message that is
+*not* about a field (a dialog reporting a failed action, a page-wide warning) is a full `p-message`
+with a `severity`, not a field error borrowed for the occasion.
+
+### The `dotFieldRequired` directive
+
+`libs/ui/src/lib/dot-field-required/dot-field-required.directive.ts` puts the required asterisk on
+a label without markup. It has exactly two usages — there is **no** `dotFieldRequired` *input*:
+
+```html
+<!-- Always required -->
+<label dotFieldRequired for="name">Name</label>
+
+<!-- Required only if the named control carries Validators.required -->
+<label dotFieldRequired checkIsRequiredControl="name" for="name">Name</label>
+```
+
+It adds the class `p-label-input-required`, whose `::after { content: '*' }` rule lives at the top
+level of `apps/dotcms-ui/src/style.css` — **not** scoped to `.form`, so unlike `p-field-hint` it
+works anywhere.
+
+**Use it for a form whose required fields are fixed.** Do not use it for a form built from runtime
+metadata, for three reasons visible in the source:
+
+- **It is a one-way latch.** The constructor adds the class unconditionally; `checkIsRequiredControl`
+  is a plain setter that only ever *removes* it. Once removed it never comes back, and the setter
+  re-runs only when the bound string changes — so a control that becomes required again keeps no
+  asterisk.
+- **It only recognises `Validators.required` by reference** (`hasValidator(Validators.required)`).
+  A custom or cross-field validator reads as "not required".
+- **It requires a `FormGroupDirective` ancestor** (`inject(FormGroupDirective)`, not optional), so
+  it throws outside a reactive form.
+
+`dot-ai-config-detail` is the counter-example: its fields come from provider metadata and the
+`FormGroup` is rebuilt on every provider switch, while `@for (… track field.name)` reuses the DOM
+node. The same field name can change requiredness between providers — `model` is
+`ProviderField.required` for Vertex AI and `ProviderField.optionalUnless` for Azure — which the
+latch above would render stale. That screen uses the literal `*` bound to the metadata flag
+instead, per the Form Fields rules above.
+
 ## See also
 - [ANGULAR_STANDARDS.md](./ANGULAR_STANDARDS.md) — Component rules, templates
 - [docs/frontend/README.md](./README.md) — Index of all frontend docs
diff --git a/dotCMS/src/main/webapp/WEB-INF/messages/Language.properties b/dotCMS/src/main/webapp/WEB-INF/messages/Language.properties
index 2e8da9de2b3b..9615649b1559 100644
--- a/dotCMS/src/main/webapp/WEB-INF/messages/Language.properties
+++ b/dotCMS/src/main/webapp/WEB-INF/messages/Language.properties
@@ -5621,7 +5621,6 @@ apps.content-analytics.generated.string.confirm.replace.message=The current valu
 apps.ai.config.title=dotAI Configuration
 apps.ai.config.first.subtitle=Configure the AI providers used for chat, embeddings and image generation.
 apps.ai.config.second.subtitle=Each capability is configured independently, so you can mix providers.
-apps.ai.loading=Loading...
 apps.ai.unsaved.changes=Unsaved changes
 apps.ai.button.cancel=Cancel
 apps.ai.button.save=Save Configuration

From 146ac85feb03f1cfe218a9688a7b010c547958c3 Mon Sep 17 00:00:00 2001
From: Kevin <kevin.davila@dotcms.com>
Date: Wed, 9 Sep 2026 19:18:28 -0500
Subject: [PATCH 7/7] refactor(dot-ai): update service references in
 DotAiConfigDetailComponent tests

Replaced instances of DotAiService with DotAiConfigService in the unit tests for DotAiConfigDetailComponent to ensure consistency and accuracy in service usage. This change enhances the clarity of the tests and aligns them with the current service architecture.
---
 .../dot-ai-config-detail.component.spec.ts                | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.spec.ts b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.spec.ts
index 9f320cbce765..7b0140614060 100644
--- a/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.spec.ts
+++ b/core-web/apps/dotcms-ui/src/app/portlets/dot-apps/components/dot-ai-config-detail/dot-ai-config-detail.component.spec.ts
@@ -101,8 +101,8 @@ describe('DotAiConfigDetailComponent', () => {
     describe('load-state rendering', () => {
         it('renders the spinner and no error while the config is still loading', () => {
             spectator = createComponent();
-            spectator.inject(DotAiService).getProviders.mockReturnValue(NEVER);
-            spectator.inject(DotAiService).getConfig.mockReturnValue(NEVER);
+            spectator.inject(DotAiConfigService).getProviders.mockReturnValue(NEVER);
+            spectator.inject(DotAiConfigService).getConfig.mockReturnValue(NEVER);
 
             spectator.detectChanges();
 
@@ -112,9 +112,9 @@ describe('DotAiConfigDetailComponent', () => {
 
         it('renders the error message and no spinner when the load fails', () => {
             spectator = createComponent();
-            spectator.inject(DotAiService).getProviders.mockReturnValue(of(providers));
+            spectator.inject(DotAiConfigService).getProviders.mockReturnValue(of(providers));
             spectator
-                .inject(DotAiService)
+                .inject(DotAiConfigService)
                 .getConfig.mockReturnValue(throwError(() => new Error('network error')));
 
             spectator.detectChanges();