From a4003d5463860c713cff19498e02199422a820b8 Mon Sep 17 00:00:00 2001
From: simurai <simulus@gmail.com>
Date: Wed, 19 Feb 2020 22:45:55 +0900
Subject: [PATCH 1/2] Remove <dl> from .form-group

---
 docs/content/components/box.md   | 16 ++++----
 docs/content/components/forms.md | 68 +++++++++++++++++++-------------
 src/forms/form-control.scss      |  3 +-
 src/forms/form-group.scss        | 29 +++++++++-----
 src/forms/form-validation.scss   |  6 ++-
 5 files changed, 74 insertions(+), 48 deletions(-)

diff --git a/docs/content/components/box.md b/docs/content/components/box.md
index 3e3f94ab22..8772d039cc 100644
--- a/docs/content/components/box.md
+++ b/docs/content/components/box.md
@@ -531,10 +531,10 @@ You can put forms in boxes. Often form submission buttons are aligned to the bot
   </div>
   <form>
     <div class="Box-body">
-      <dl class="form-group">
-        <dt><label>Example label</label></dt>
-        <dd><input class="form-control" type="text" /></dd>
-      </dl>
+      <div class="form-group">
+        <div class="form-group-header"><label>Example label</label></div>
+        <div class="form-group-body"><input class="form-control" type="text" /></div>
+      </div>
       <div class="form-checkbox">
         <label>
           <input type="checkbox" checked="checked" />
@@ -563,10 +563,10 @@ When a box is all by itself centered on a page you can use [column widths](/obje
       <h3 class="f1-light">
         Example form
       </h3>
-      <dl class="form-group mb-4">
-        <dt><label>Example label</label></dt>
-        <dd><input class="form-control" type="text" /></dd>
-      </dl>
+      <div class="form-group mb-4">
+        <div class="form-group-header"><label>Example label</label></div>
+        <div class="form-group-body"><input class="form-control" type="text" /></div>
+      </div>
       <button class="btn btn-primary btn-block">
         Submit
       </button>
diff --git a/docs/content/components/forms.md b/docs/content/components/forms.md
index ec2205689e..0f9223bf52 100644
--- a/docs/content/components/forms.md
+++ b/docs/content/components/forms.md
@@ -183,14 +183,20 @@ Use the `.select-sm` class to resize both default and custom `<select>`s to matc
 
 ```html live
 <form>
-  <dl class="form-group">
-    <dt><label for="example-text">Example Text</label></dt>
-    <dd><input class="form-control" type="text" value="Example Value" id="example-text" /></dd>
-  </dl>
-
-  <dl class="form-group">
-    <dt><label for="example-select">Example Select</label></dt>
-    <dd>
+  <div class="form-group">
+    <div class="form-group-header">
+      <label for="example-text">Example Text</label>
+    </div>
+    <div class="form-group-body">
+      <input class="form-control" type="text" value="Example Value" id="example-text" />
+    </div>
+  </div>
+
+  <div class="form-group">
+    <div class="form-group-header">
+      <label for="example-select">Example Select</label>
+    </div>
+    <div class="form-group-body">
       <select class="form-select" id="example-select">
         <option>Choose an option</option>
         <option>Git</option>
@@ -200,27 +206,31 @@ Use the `.select-sm` class to resize both default and custom `<select>`s to matc
         <option>Bears</option>
         <option>Battlestar Galactica</option>
       </select>
-    </dd>
-  </dl>
+    </div>
+  </div>
 
-  <dl class="form-group">
-    <dt><label for="example-textarea">Example Textarea</label></dt>
-    <dd>
+  <div class="form-group">
+    <div class="form-group-header">
+      <label for="example-textarea">Example Textarea</label>
+    </div>
+    <div class="form-group-body">
       <textarea class="form-control" id="example-textarea"></textarea>
-    </dd>
-  </dl>
+    </div>
+  </div>
 </form>
 ```
 
 #### Form group validation
 
-Convey errors and warnings for form groups. Add the appropriate class—either `.errored` or `.warn`—to the `<dl class="form-group">` to start. Then, house your error messaging in an additional `<dd>` with either `.error` or `.warning`.
+Convey errors and warnings for form groups. Add the appropriate class—either `.errored` or `.warn`—to the `<div class="form-group">` to start. Then, house your error messaging in an additional `<div>` with either `.error` or `.warning`.
 
 ```html live
 <form class="pb-2">
-  <dl class="form-group errored">
-    <dt><label for="example-text-errored">Example Text</label></dt>
-    <dd>
+  <div class="form-group errored">
+    <div class="form-group-header">
+      <label for="example-text-errored">Example Text</label>
+    </div>
+    <div class="form-group-body">
       <input
         class="form-control"
         type="text"
@@ -228,13 +238,15 @@ Convey errors and warnings for form groups. Add the appropriate class—either `
         id="example-text-errored"
         aria-describedby="form-error-text"
       />
-    </dd>
-    <dd class="error" id="form-error-text">This example input has an error.</dd>
-  </dl>
+    </div>
+    <div class="error" id="form-error-text">This example input has an error.</div>
+  </div>
   <br />
-  <dl class="form-group warn">
-    <dt><label for="example-text-warn">Example Text</label></dt>
-    <dd>
+  <div class="form-group warn">
+    <div class="form-group-header">
+      <label for="example-text-warn">Example Text</label>
+    </div>
+    <div class="form-group-body">
       <input
         class="form-control"
         type="text"
@@ -242,9 +254,9 @@ Convey errors and warnings for form groups. Add the appropriate class—either `
         id="example-text-warn"
         aria-describedby="form-warning-text"
       />
-    </dd>
-    <dd class="warning" id="form-warning-text">This example input has a warning.</dd>
-  </dl>
+    </div>
+    <div class="warning" id="form-warning-text">This example input has a warning.</div>
+  </div>
 </form>
 ```
 
diff --git a/src/forms/form-control.scss b/src/forms/form-control.scss
index 5a54e68758..778f320899 100644
--- a/src/forms/form-control.scss
+++ b/src/forms/form-control.scss
@@ -188,7 +188,8 @@ label {
     // stylelint-disable-next-line primer/spacing
     margin: 0 30px 0 0;
 
-    dt {
+    dt, // TODO: Deprecate
+    .form-group-header {
       label {
         display: inline-block;
         // stylelint-disable-next-line primer/spacing
diff --git a/src/forms/form-group.scss b/src/forms/form-group.scss
index 2de8d1493a..4ca89f7779 100644
--- a/src/forms/form-group.scss
+++ b/src/forms/form-group.scss
@@ -1,9 +1,15 @@
-// Form groups
-//
-// Typical form groups - `<dl.form-group>` with a `<dt>` containing the label and
-// `<dd> containing the form elements.
 // stylelint-disable selector-max-compound-selectors
 // stylelint-disable selector-max-type
+
+// Form groups
+//
+// Usage:
+//
+// <div class="form-group">
+//   <div class="form-group-header"> containing the label
+//   <div class="form-group-body"> containing the form elements
+// </div>
+
 .form-group {
   // stylelint-disable-next-line primer/spacing
   margin: 15px 0;
@@ -42,7 +48,8 @@
   // stylelint-enable selector-no-qualifying-type
 
   // The Label
-  dt {
+  dt, // TODO: Deprecate
+  .form-group-header {
     // stylelint-disable-next-line primer/spacing
     margin: 0 0 6px;
   }
@@ -51,14 +58,16 @@
     position: relative;
   }
 
-  &.flattened dt {
+  &.flattened dt, // TODO: Deprecate
+  &.flattened .form-group-header {
     float: left;
     margin: 0;
     // stylelint-disable-next-line primer/typography
     line-height: 32px;
   }
 
-  &.flattened dd {
+  &.flattened dd, // TODO: Deprecate
+  &.flattened .form-group-body {
     // stylelint-disable-next-line primer/typography
     line-height: 32px;
   }
@@ -67,7 +76,8 @@
   // Form Elements
   //
   // stylelint-disable selector-no-qualifying-type
-  dd {
+  dd, // TODO: Deprecate
+  .form-group-body {
     h4 {
       margin: $spacer-1 0 0;
 
@@ -87,7 +97,8 @@
   //
 
   &.required {
-    dt label::after {
+    dt label::after, // TODO: Deprecate
+    .form-group-header label::after {
       // stylelint-disable-next-line primer/spacing
       padding-left: 5px;
       color: $text-red;
diff --git a/src/forms/form-validation.scss b/src/forms/form-validation.scss
index a341e4821a..a6b49c8b2a 100644
--- a/src/forms/form-validation.scss
+++ b/src/forms/form-validation.scss
@@ -1,6 +1,7 @@
 // Needs refactoring
 // stylelint-disable selector-no-qualifying-type, selector-max-type
-dl.form-group > dd {
+dl.form-group > dd, // TODO: Deprecate
+.form-group > .form-group-body {
   .form-control {
     &.is-autocheck-loading,
     &.is-autocheck-successful,
@@ -25,7 +26,8 @@ dl.form-group > dd {
 
 // Retinization of form validation icons that aren't octicons yet
 @include retina-media-query {
-  dl.form-group > dd {
+  dl.form-group > dd, // TODO: Deprecate
+  .form-group > .form-group-body {
     .form-control {
       &.is-autocheck-loading,
       &.is-autocheck-successful,

From 45a6476e52efec681a1937a6e39dcb22a136d877 Mon Sep 17 00:00:00 2001
From: simurai <simurai@github.com>
Date: Tue, 24 Mar 2020 10:54:09 +0900
Subject: [PATCH 2/2] Update docs/content/components/box.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Mu-An 慕安 <me@muanchiou.com>
---
 docs/content/components/box.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/content/components/box.md b/docs/content/components/box.md
index 8772d039cc..e01afbe37d 100644
--- a/docs/content/components/box.md
+++ b/docs/content/components/box.md
@@ -533,7 +533,7 @@ You can put forms in boxes. Often form submission buttons are aligned to the bot
     <div class="Box-body">
       <div class="form-group">
         <div class="form-group-header"><label>Example label</label></div>
-        <div class="form-group-body"><input class="form-control" type="text" /></div>
+        <div class="form-group-body"><input class="form-control" type="text"></div>
       </div>
       <div class="form-checkbox">
         <label>