Refine the visual display of the comment reply form help text

.changeset/cold-melons-boil.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': minor
+---
+
+Refine the visual display of the comment reply form help text

src/components/comment-form/comment-form.scss

@@ -3,7 +3,8 @@
 
 .c-comment-form {
   display: grid;
-  grid-gap: ms.step(2, 1rem) ms.step(4, 1rem);
+  grid-gap: size.$spacing-gap-comment-form-vertical
+    size.$spacing-gap-comment-form-horizontal;
   grid-template-columns: 1fr 1fr;
 }
 

src/components/comment-form/comment-form.stories.mdx

@@ -62,7 +62,7 @@ The form used to add a comment to an article. Including the `heading_id` and `he
   </Story>
 </Canvas>
 
-There is also a reply version of this component (`is_reply: true`), used to reply to an existing comment. (You'll also want to modify `heading_tag`, `heading_id`, `heading_class`, and `heading_text`. When using the [Comment pattern](/docs/components-comment--with-reply-button) this will be done automatically.)
+There is also a reply version of this component (`is_reply: true`), used to reply to an existing comment. (You'll also want to modify `heading_tag`, `heading_id`, `heading_class`, `heading_text`, and `main_label`. When using the [Comment pattern](/docs/components-comment--with-reply-button) this will be done automatically.)
 
 <Canvas>
   <Story

src/components/comment-form/comment-form.twig

@@ -12,13 +12,18 @@
     >
       {{ heading_text|default("Leave a Comment") }}
     </{{_heading_tag}}>
-    <p {% if help_text_id %}id="{{ help_text_id }}"{% endif %}>
-      Please be kind, courteous and constructive.
-      You may use simple HTML or
-      <a href="https://en.support.wordpress.com/markdown-quick-reference">Markdown</a>
-      in your comments.
-      All fields are required.
-    </p>
+
+    {% embed '@cloudfour/components/alert/alert.twig' %}
+      {% block content %}
+        <p {% if help_text_id %}id="{{ help_text_id }}"{% endif %}>
+          Please be kind, courteous and constructive.
+          You may use simple HTML or
+          <a href="https://en.support.wordpress.com/markdown-quick-reference">Markdown</a>
+          in your comments.
+          All fields are required.
+        </p>
+      {% endblock %}
+    {% endembed %}
   {% endblock %}
   {% embed '@cloudfour/objects/form-group/form-group.twig' with { label: main_label|default('Message') } %}
     {% block control %}

src/components/comment/comment.scss

@@ -50,6 +50,10 @@
 
 .c-comment.is-replying .c-comment__reply-form {
   display: block;
+  /// The top margin matches the grid gap spacing applied to the comment form.
+  /// Otherwise, the form's help text appears visually closer to the comment
+  /// you're responding to than to the form.
+  margin-top: size.$spacing-gap-comment-form-vertical;
 }
 
 /// Named object for consistency with the Media component.
@@ -134,10 +138,6 @@
   // Visually centers the child avatars with the indentation of the parent
   // comment. Without this, the replies feel nested too far to the right.
   margin-left: math.div(size.$square-avatar-small, -2);
-}
-
-.c-comment__replies,
-.c-comment__reply-form {
   // Since the replies are likely wrapped in a Rhythm object intended to inherit
   // the parent rhythm, we can use that custom property to inherit that same
   // spacing between the meta and replies.

src/tokens/size/spacing.js

@@ -1,4 +1,4 @@
-const { modularEm } = require('../../scripts/modular-scale');
+const { modularEm, modularRem } = require('../../scripts/modular-scale');
 
 module.exports = {
   size: {
@@ -49,6 +49,10 @@ module.exports = {
         logo_group: {
           value: modularEm(3),
         },
+        comment_form: {
+          horizontal: { value: modularRem(4) },
+          vertical: { value: modularRem(2) },
+        },
       },
       control: {
         text_inset: { value: modularEm(-1) },