descriptionslop

webui/src/admin/components/SchemaConfigurationForm.jsx

@@ -103,9 +103,12 @@ function ConfigurationFieldTemplate({
         <label htmlFor={id} className="text-xs font-semibold text-slate-100">
           {label}{required ? <span className="ml-0.25 text-sky-300">*</span> : null}
         </label>
-        {description ? <div>{description}</div> : null}
       </div>
       <div className="configuration-value">
+        {/* Descriptions belong with the editable value rather than inside the
+            narrow key column. This keeps long operational guidance readable
+            without weakening the YAML-like key/value alignment. */}
+        {description ? <div className="configuration-value-description">{description}</div> : null}
         {children}
         {errors}
         {help}
@@ -121,22 +124,34 @@ function ConfigurationObjectTemplate({ description, fieldPathId, properties, tit
   if (fieldPathId.path.length === 0) {
     // The outer configuration card already names the root document. Rendering
     // its properties directly makes their schema order read like YAML lines.
-    return <div className="configuration-tree">{propertyLines}</div>;
+    // The root description remains outside that stack so its introductory
+    // text does not accidentally become another configuration section.
+    return (
+      <div>
+        {description ? <div className="configuration-root-description">{description}</div> : null}
+        <div className="configuration-tree">{propertyLines}</div>
+      </div>
+    );
   }
 
   if (typeof fieldPathId.path.at(-1) === 'number') {
     // Array items receive their numbered heading and action row from the array
-    // item template. Rendering only their ordered property lines prevents redundant
-    // nested boxes such as "Item 1" followed by another anonymous object box.
-    return <div>{propertyLines}</div>;
+    // item template. Rendering only their description and ordered property
+    // lines prevents redundant boxes while preserving the item's own guidance.
+    return (
+      <div>
+        {description ? <div className="configuration-item-description">{description}</div> : null}
+        {propertyLines}
+      </div>
+    );
   }
 
   return (
     <section className="configuration-branch">
       <header className="configuration-branch-heading">
         <h3>{title}</h3>
-        {description ? <div>{description}</div> : null}
       </header>
+      {description ? <div className="configuration-branch-description">{description}</div> : null}
       <div className="configuration-children">{propertyLines}</div>
     </section>
   );

webui/src/admin/styles.css

@@ -5,8 +5,9 @@
 
 .configuration-tree {
   /* A single ordered stack is the visual equivalent of YAML's top-to-bottom
-     document order. Separation comes from hierarchy, not unrelated tiles. */
-  @apply space-y-0.5;
+     document order. A deliberately large root gap makes the beginning and end
+     of every top-level section unmistakable, while nested lines stay compact. */
+  @apply mt-1 space-y-4;
 }
 
 .configuration-branch {
@@ -25,11 +26,6 @@
   @apply text-sm font-semibold text-slate-100;
 }
 
-.configuration-branch-heading > div,
-.configuration-branch-description {
-  @apply text-[0.7rem] text-slate-400;
-}
-
 .configuration-children {
   /* Every container contributes exactly one indentation and one guide. Deep
      descendants therefore explain their ancestry without calculating depth or
@@ -49,13 +45,31 @@
   @apply min-w-0;
 }
 
-.configuration-key .field-description,
-.configuration-key .help-block,
-.configuration-branch-description {
+.configuration-root-description,
+.configuration-branch-description,
+.configuration-item-description,
+.configuration-value-description {
   @apply block text-[0.7rem] leading-tight text-slate-500;
   margin-top: 0.125rem;
 }
 
+.configuration-root-description {
+  @apply mb-1;
+}
+
+.configuration-branch-description,
+.configuration-item-description {
+  /* Container help follows its heading at the same indentation; child keys
+     begin below it, preserving the same parent/child rhythm as YAML comments. */
+  @apply ml-0.5 max-w-[56rem];
+}
+
+.configuration-value-description {
+  /* A little separation from the widget keeps the help readable without
+     turning each setting back into a large card. */
+  @apply mb-0.5 max-w-[40rem];
+}
+
 .configuration-value input:not([type='checkbox']),
 .configuration-value select,
 .configuration-value textarea {