Form check markup v2 (#25050)

* match layout behaviors

* ditch the indicator as separate element for psuedo-elements on the label

* move disabled to attribute only on input

* redo default inline check to support new markup

* redo inline forms

* clean up vars

* update validation mixin to new structure

* update checks in docs

* linting for for/id attributes

4 files changed, 82 insertions, 99 deletions

diff --git a/scss/_custom-forms.scss b/scss/_custom-forms.scss
index c752a9f11..e66638ba3 100644
--- a/scss/_custom-forms.scss
+++ b/scss/_custom-forms.scss
@@ -9,9 +9,13 @@
 
 .custom-control {
   position: relative;
-  display: inline-flex;
+  display: block;
   min-height: (1rem * $line-height-base);
   padding-left: $custom-control-gutter;
+}
+
+.custom-control-inline {
+  display: inline-flex;
   margin-right: $custom-control-spacer-x;
 }
 
@@ -20,51 +24,61 @@
   z-index: -1; // Put the input behind the label so it doesn't overlay text
   opacity: 0;
 
-  &:checked ~ .custom-control-indicator {
+  &:checked ~ .custom-control-label::before {
     color: $custom-control-indicator-checked-color;
     @include gradient-bg($custom-control-indicator-checked-bg);
     @include box-shadow($custom-control-indicator-checked-box-shadow);
   }
 
-  &:focus ~ .custom-control-indicator {
+  &:focus ~ .custom-control-label::before {
     // the mixin is not used here to make sure there is feedback
     box-shadow: $custom-control-indicator-focus-box-shadow;
   }
 
-  &:active ~ .custom-control-indicator {
+  &:active ~ .custom-control-label::before {
     color: $custom-control-indicator-active-color;
     background-color: $custom-control-indicator-active-bg;
     @include box-shadow($custom-control-indicator-active-box-shadow);
   }
 
   &:disabled {
-    ~ .custom-control-indicator {
-      background-color: $custom-control-indicator-disabled-bg;
-    }
+    ~ .custom-control-label {
+      color: $custom-control-label-disabled-color;
 
-    ~ .custom-control-description {
-      color: $custom-control-description-disabled-color;
+      &::before {
+        background-color: $custom-control-indicator-disabled-bg;
+      }
     }
   }
 }
 
-// Custom indicator
+// Custom control indicators
 //
-// Generates a shadow element to create our makeshift checkbox/radio background.
+// Build the custom controls out of psuedo-elements.
 
-.custom-control-indicator {
-  position: absolute;
-  top: (($line-height-base - $custom-control-indicator-size) / 2);
-  left: 0;
-  display: block;
-  width: $custom-control-indicator-size;
-  height: $custom-control-indicator-size;
-  pointer-events: none;
-  user-select: none;
-  background-color: $custom-control-indicator-bg;
-  @include box-shadow($custom-control-indicator-box-shadow);
+.custom-control-label {
+  margin-bottom: 0;
 
+  // Background-color and (when enabled) gradient
   &::before {
+    position: absolute;
+    top: (($line-height-base - $custom-control-indicator-size) / 2);
+    left: 0;
+    display: block;
+    width: $custom-control-indicator-size;
+    height: $custom-control-indicator-size;
+    pointer-events: none;
+    content: "";
+    user-select: none;
+    background-color: $custom-control-indicator-bg;
+    @include box-shadow($custom-control-indicator-box-shadow);
+  }
+
+  // Foreground (icon)
+  &::after {
+    position: absolute;
+    top: (($line-height-base - $custom-control-indicator-size) / 2);
+    left: 0;
     display: block;
     width: $custom-control-indicator-size;
     height: $custom-control-indicator-size;
@@ -75,28 +89,31 @@
   }
 }
 
+
 // Checkboxes
 //
 // Tweak just a few things for checkboxes.
 
 .custom-checkbox {
-  .custom-control-indicator {
+  .custom-control-label::before {
     @include border-radius($custom-checkbox-indicator-border-radius);
   }
 
-  .custom-control-input:checked ~ .custom-control-indicator {
-    @include gradient-bg($custom-control-indicator-checked-bg);
-
+  .custom-control-input:checked ~ .custom-control-label {
     &::before {
+      @include gradient-bg($custom-control-indicator-checked-bg);
+    }
+    &::after {
       background-image: $custom-checkbox-indicator-icon-checked;
     }
   }
 
-  .custom-control-input:indeterminate ~ .custom-control-indicator {
-    @include gradient-bg($custom-checkbox-indicator-indeterminate-bg);
-    @include box-shadow($custom-checkbox-indicator-indeterminate-box-shadow);
-
+  .custom-control-input:indeterminate ~ .custom-control-label {
     &::before {
+      @include gradient-bg($custom-checkbox-indicator-indeterminate-bg);
+      @include box-shadow($custom-checkbox-indicator-indeterminate-box-shadow);
+    }
+    &::after {
       background-image: $custom-checkbox-indicator-icon-indeterminate;
     }
   }
@@ -107,34 +124,16 @@
 // Tweak just a few things for radios.
 
 .custom-radio {
-  .custom-control-indicator {
+  .custom-control-label::before {
     border-radius: $custom-radio-indicator-border-radius;
   }
 
-  .custom-control-input:checked ~ .custom-control-indicator {
-    @include gradient-bg($custom-control-indicator-checked-bg);
-
+  .custom-control-input:checked ~ .custom-control-label {
     &::before {
-      background-image: $custom-radio-indicator-icon-checked;
+      @include gradient-bg($custom-control-indicator-checked-bg);
     }
-  }
-}
-
-
-// Layout options
-//
-// By default radios and checkboxes are `inline-block` with no additional spacing
-// set. Use these optional classes to tweak the layout.
-
-.custom-controls-stacked {
-  display: flex;
-  flex-direction: column;
-
-  .custom-control {
-    margin-bottom: $custom-control-spacer-y;
-
-    + .custom-control {
-      margin-left: 0;
+    &::after {
+      background-image: $custom-radio-indicator-icon-checked;
     }
   }
 }
diff --git a/scss/_forms.scss b/scss/_forms.scss
index 9cec3ac9c..72bde5784 100644
--- a/scss/_forms.scss
+++ b/scss/_forms.scss
@@ -207,33 +207,35 @@ select.form-control-lg {
 .form-check {
   position: relative;
   display: block;
-  margin-bottom: $form-check-margin-bottom;
-
-  &.disabled {
-    .form-check-label {
-      color: $text-muted;
-    }
-  }
-}
-
-.form-check-label {
   padding-left: $form-check-input-gutter;
-  margin-bottom: 0; // Override default `<label>` bottom margin
 }
 
 .form-check-input {
   position: absolute;
   margin-top: $form-check-input-margin-y;
   margin-left: -$form-check-input-gutter;
+
+  &:disabled ~ .form-check-label {
+    color: $text-muted;
+  }
+}
+
+.form-check-label {
+  margin-bottom: 0; // Override default `<label>` bottom margin
 }
 
-// Radios and checkboxes on same line
 .form-check-inline {
-  display: inline-block;
+  display: inline-flex;
+  align-items: center;
+  padding-left: 0; // Override base .form-check
   margin-right: $form-check-inline-margin-x;
 
-  .form-check-label {
-    vertical-align: middle;
+  // Undo .form-check-input defaults and add some `margin-right`.
+  .form-check-input {
+    position: static;
+    margin-top: 0;
+    margin-right: $form-check-inline-input-margin-x;
+    margin-left: 0;
   }
 }
 
@@ -310,10 +312,6 @@ select.form-control-lg {
       align-items: center;
       justify-content: center;
       width: auto;
-      margin-top: 0;
-      margin-bottom: 0;
-    }
-    .form-check-label {
       padding-left: 0;
     }
     .form-check-input {
@@ -323,23 +321,12 @@ select.form-control-lg {
       margin-left: 0;
     }
 
-    // Custom form controls
     .custom-control {
-      display: flex;
       align-items: center;
       justify-content: center;
-      padding-left: 0;
-    }
-    .custom-control-indicator {
-      position: static;
-      display: inline-block;
-      margin-right: $form-check-input-margin-x; // Flexbox alignment means we lose our HTML space here, so we compensate.
-      vertical-align: text-bottom;
     }
-
-    // Re-override the feedback icon.
-    .has-feedback .form-control-feedback {
-      top: 0;
+    .custom-control-label {
+      margin-bottom: 0;
     }
   }
 }
diff --git a/scss/_variables.scss b/scss/_variables.scss
index be3dd69b5..8290c96fc 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -423,12 +423,12 @@ $input-transition:                      border-color .15s ease-in-out, box-shado
 
 $form-text-margin-top:                  .25rem !default;
 
-$form-check-margin-bottom:              .5rem !default;
 $form-check-input-gutter:               1.25rem !default;
-$form-check-input-margin-y:             .25rem !default;
+$form-check-input-margin-y:             .3rem !default;
 $form-check-input-margin-x:             .25rem !default;
 
 $form-check-inline-margin-x:            .75rem !default;
+$form-check-inline-input-margin-x:      .3125rem !default;
 
 $form-group-margin-bottom:              1rem !default;
 
@@ -437,7 +437,6 @@ $input-group-addon-bg:                  $gray-200 !default;
 $input-group-addon-border-color:        $input-border-color !default;
 
 $custom-control-gutter:                 1.5rem !default;
-$custom-control-spacer-y:               .25rem !default;
 $custom-control-spacer-x:               1rem !default;
 
 $custom-control-indicator-size:         1rem !default;
@@ -446,7 +445,7 @@ $custom-control-indicator-bg-size:      50% 50% !default;
 $custom-control-indicator-box-shadow:   inset 0 .25rem .25rem rgba($black, .1) !default;
 
 $custom-control-indicator-disabled-bg:          $gray-200 !default;
-$custom-control-description-disabled-color:     $gray-600 !default;
+$custom-control-label-disabled-color:     $gray-600 !default;
 
 $custom-control-indicator-checked-color:        $white !default;
 $custom-control-indicator-checked-bg:           theme-color("primary") !default;
diff --git a/scss/mixins/_forms.scss b/scss/mixins/_forms.scss
index 470f80c15..ba1b16d6a 100644
--- a/scss/mixins/_forms.scss
+++ b/scss/mixins/_forms.scss
@@ -69,34 +69,32 @@
     }
   }
 
-
-  // TODO: redo check markup lol crap
   .form-check-input {
     .was-validated &:#{$state},
     &.is-#{$state} {
-      + .form-check-label {
+      ~ .form-check-label {
         color: $color;
       }
     }
   }
 
-  // custom radios and checks
   .custom-control-input {
     .was-validated &:#{$state},
     &.is-#{$state} {
-      ~ .custom-control-indicator {
-        background-color: lighten($color, 25%);
-      }
-      ~ .custom-control-description {
+      ~ .custom-control-label {
         color: $color;
+
+        &::before {
+          background-color: lighten($color, 25%);
+        }
       }
       &:checked {
-        ~ .custom-control-indicator {
+        ~ .custom-control-label::before {
           @include gradient-bg(lighten($color, 10%));
         }
       }
       &:focus {
-        ~ .custom-control-indicator {
+        ~ .custom-control-label::before {
           box-shadow: 0 0 0 1px $body-bg, 0 0 0 $input-focus-width rgba($color, .25);
         }
       }