Fix a11y problems on star rating component

scss/forms/_star-rating.scss

@@ -3,31 +3,30 @@
 //
 
 .star-rating {
-  &.disabled,
-  &:disabled {
-    pointer-events: none;
-  }
 
-  > label {
+  > label,
+  span {
     display: block;
     float: left;
     width: 1em;
     height: 1em;
     font-size: $form-star-size;
     cursor: pointer;
-    @include form-star-rating($accessible-orange);
+    @include form-star-rating($accessible-orange, $accessible-orange);
 
     &:not(:first-of-type){
       margin-left: $form-star-margin-between;
     }
   }
 
-  > input:checked ~ label {
-    @include form-star-rating($gray-500);
+  > input:checked ~ label,
+  span {
+    @include form-star-rating($gray-700, $white);
   }
 
-  > input:checked + label {
-    @include form-star-rating($accessible-orange);
+  > input:checked + label,
+  .checked {
+    @include form-star-rating($accessible-orange, $accessible-orange);
   }
 
   > [data-focus-visible-added]:focus + label {
@@ -37,44 +36,85 @@
   }
 
   &:hover input + label {
-    @include form-star-rating($black);
+    @include form-star-rating($black, $black);
   }
 
   > input:hover ~ label {
-    @include form-star-rating($gray-500);
+    @include form-star-rating($gray-700, $white);
   }
 
   > input:hover + label {
-    @include form-star-rating($black);
+    @include form-star-rating($black, $black);
+  }
+
+  &.disabled,
+  &:disabled {
+    pointer-events: none;
+
+    > label {
+      @include form-star-rating($gray-700, $gray-700);
+    }
+
+    > input:checked ~ label {
+      @include form-star-rating($gray-500, $gray-500);
+    }
+
+    > input:checked + label {
+      @include form-star-rating($gray-700, $gray-700);
+    }
   }
 }
 
 .star-rating-dark {
   > label {
-    @include form-star-rating($brand-orange);
+    @include form-star-rating($brand-orange, $brand-orange);
   }
 
   > input:checked ~ label {
-    @include form-star-rating($gray-700);
+    @include form-star-rating($gray-500, $black);
   }
 
   > input:checked + label {
-    @include form-star-rating($brand-orange);
+    @include form-star-rating($brand-orange, $brand-orange);
   }
 
   &:hover input + label {
-    @include form-star-rating($white);
+    @include form-star-rating($white, $white);
   }
 
   > input:hover ~ label {
-    @include form-star-rating($gray-700);
+    @include form-star-rating($gray-500, $black);
   }
 
   > input:hover + label {
-    @include form-star-rating($white);
+    @include form-star-rating($white, $white);
   }
 }
 
-.star-rating-sm > label {
-  font-size: $form-star-size-sm;
+.star-rating-sm {
+
+  > label {
+    font-size: $form-star-size-sm;
+    @include form-star-rating-sm($accessible-orange, $accessible-orange);
+  }
+
+  > input:checked ~ label {
+    @include form-star-rating-sm($gray-700, $white);
+  }
+
+  > input:checked + label {
+    @include form-star-rating-sm($accessible-orange, $accessible-orange);
+  }
+
+  &:hover input + label {
+    @include form-star-rating-sm($black, $black);
+  }
+
+  > input:hover ~ label {
+    @include form-star-rating-sm($gray-700, $white);
+  }
+
+  > input:hover + label {
+    @include form-star-rating-sm($black, $black);
+  }
 }

scss/mixins/_star-rating.scss

@@ -1,5 +1,9 @@
 // scss-docs-start form-star-rating-mixin
-@mixin form-star-rating($color) {
-  background-image: escape-svg(url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 25 25'><path fill='#{$color}' d='m12.5 2.9 2.379 7.35 7.721-.007-6.25 4.536 2.392 7.346-6.242-4.547-6.242 4.547 2.392-7.346-6.25-4.536 7.721.007Z'/></svg>"));
+@mixin form-star-rating($path-color, $fill-color) {
+  background-image: escape-svg(url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 25 25'><path fill='#{$fill-color}' fill-rule='evenodd' stroke='#{$path-color}' d='m12.5 4.523 2.016 6.227 6.542-.005-5.296 3.843 2.027 6.224L12.5 16.96l-5.289 3.852 2.027-6.224-5.296-3.843 6.542.005L12.5 4.523Z'/></svg>"));
+}
+
+@mixin form-star-rating-sm($path-color, $fill-color) {
+  background-image: escape-svg(url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'><path fill='#{$fill-color}' fill-rule='evenodd' stroke='#{$path-color}' d='M10 3.943 11.54 8.7l4.998-.004-4.046 2.936 1.548 4.755L10 13.444l-4.04 2.943 1.548-4.755-4.046-2.936L8.46 8.7 10 3.943Z'/></svg>"));
 }
 // scss-docs-end form-star-rating-mixin

site/content/docs/5.3/forms/checks-radios.md

@@ -368,19 +368,19 @@ Star rating system is built on top of radios. Simply add `.star-rating` to a `<f
     <legend class="visually-hidden">Results relevance</legend>
 
     <input type="radio" id="terrible" name="rating" value="1" class="visually-hidden">
-    <label for="terrible" title="Terrible"></label>
+    <label for="terrible" title="Terrible"><span class="visually-hidden">Terrible</span></label>
 
     <input type="radio" id="bad" name="rating" value="2" class="visually-hidden">
-    <label for="bad" title="Bad"></label>
+    <label for="bad" title="Bad"><span class="visually-hidden">Bad</span></label>
 
     <input type="radio" id="mixed" name="rating" value="3" class="visually-hidden">
-    <label for="mixed" title="Mixed"></label>
+    <label for="mixed" title="Mixed"><span class="visually-hidden">Mixed</span></label>
 
     <input type="radio" id="good" name="rating" value="4" class="visually-hidden" checked>
-    <label for="good" title="Good"></label>
+    <label for="good" title="Good"><span class="visually-hidden">Good</span></label>
 
     <input type="radio" id="excellent" name="rating" value="5" class="visually-hidden">
-    <label for="excellent" title="Excellent"></label>
+    <label for="excellent" title="Excellent"><span class="visually-hidden">Excellent</span></label>
   </fieldset>
 </form>
 {{< /example >}}
@@ -395,19 +395,19 @@ Star ratings come with a smaller variant: `.star-rating-sm`.
     <legend class="visually-hidden">Results relevance</legend>
 
     <input type="radio" id="terrible2" name="rating" value="1" class="visually-hidden">
-    <label for="terrible2" title="Terrible"></label>
+    <label for="terrible2" title="Terrible"><span class="visually-hidden">Terrible</span></label>
 
     <input type="radio" id="bad2" name="rating" value="2" class="visually-hidden">
-    <label for="bad2" title="Bad"></label>
+    <label for="bad2" title="Bad"><span class="visually-hidden">Bad</span></label>
 
     <input type="radio" id="mixed2" name="rating" value="3" class="visually-hidden">
-    <label for="mixed2" title="Mixed"></label>
+    <label for="mixed2" title="Mixed"><span class="visually-hidden">Mixed</span></label>
 
     <input type="radio" id="good2" name="rating" value="4" class="visually-hidden" checked>
-    <label for="good2" title="Good"></label>
+    <label for="good2" title="Good"><span class="visually-hidden">Good</span></label>
 
     <input type="radio" id="excellent2" name="rating" value="5" class="visually-hidden">
-    <label for="excellent2" title="Excellent"></label>
+    <label for="excellent2" title="Excellent"><span class="visually-hidden">Excellent</span></label>
   </fieldset>
 </form>
 {{< /example >}}
@@ -422,45 +422,65 @@ Add `.star-rating-dark` to the `.star-rating` for a dark variant.
     <legend class="visually-hidden">Results relevance</legend>
 
     <input type="radio" id="terrible3" name="rating" value="1" class="visually-hidden">
-    <label for="terrible3" title="Terrible"></label>
+    <label for="terrible3" title="Terrible"><span class="visually-hidden">Terrible</span></label>
 
     <input type="radio" id="bad3" name="rating" value="2" class="visually-hidden">
-    <label for="bad3" title="Bad"></label>
+    <label for="bad3" title="Bad"><span class="visually-hidden">Bad</span></label>
 
     <input type="radio" id="mixed3" name="rating" value="3" class="visually-hidden">
-    <label for="mixed3" title="Mixed"></label>
+    <label for="mixed3" title="Mixed"><span class="visually-hidden">Mixed</span></label>
 
     <input type="radio" id="good3" name="rating" value="4" class="visually-hidden" checked>
-    <label for="good3" title="Good"></label>
+    <label for="good3" title="Good"><span class="visually-hidden">Good</span></label>
 
     <input type="radio" id="excellent3" name="rating" value="5" class="visually-hidden">
-    <label for="excellent3" title="Excellent"></label>
+    <label for="excellent3" title="Excellent"><span class="visually-hidden">Excellent</span></label>
   </fieldset>
 </form>
 {{< /example >}}
 
+### Readonly
+Make star ratings readable but non editable by using `<span>` instead of `<input>` elements.
+
+{{< example >}}
+<div class="star-rating">
+  <p class="visually-hidden">Star rating: rated 3 out of 5</p>
+
+    <div aria-hidden="true">
+      <span class="checked"></span>
+      <span class="checked"></span>
+      <span class="checked"></span>
+      <span></span>
+      <span></span>
+    </div>
+
+</div>
+{{< /example >}}
+
 ### Disabled
 
 Make star ratings look inactive inside or outside a form by adding the `disabled` boolean attribute to the `<fieldset>` element and the `checked` boolean attribute to any `<input>` element.
 
 {{< example >}}
-<fieldset class="star-rating" disabled>
+<fieldset class="star-rating" disabled aria-hidden="true">
+  <legend class="visually-hidden">Disabled star rating</legend>
+
   <input type="radio" id="terrible4" name="rating" value="1" class="visually-hidden">
-  <label for="terrible4" title="Terrible"></label>
+  <label for="terrible4" title="Terrible"><span class="visually-hidden">Terrible</span></label>
 
   <input type="radio" id="bad4" name="rating" value="2" class="visually-hidden">
-  <label for="bad4" title="Bad"></label>
+  <label for="bad4" title="Bad"><span class="visually-hidden">Bad</span></label>
 
   <input type="radio" id="mixed4" name="rating" value="3" class="visually-hidden" checked>
-  <label for="mixed4" title="Mixed"></label>
+  <label for="mixed4" title="Mixed"><span class="visually-hidden">Mixed</span></label>
 
   <input type="radio" id="good4" name="rating" value="4" class="visually-hidden">
-  <label for="good4" title="Good"></label>
+  <label for="good4" title="Good"><span class="visually-hidden">Good</span></label>
 
   <input type="radio" id="excellent4" name="rating" value="5" class="visually-hidden">
-  <label for="excellent4" title="Excellent"></label>
+  <label for="excellent4" title="Excellent"><span class="visually-hidden">Excellent</span></label>
 </fieldset>
-<span class="visually-hidden">rated 3 stars out of 5</span>
+<p class="visually-hidden">Disabled star rating: rated 3 out of 5</p>
 {{< /example >}}
 
 <!-- End mod -->

site/content/docs/5.3/migration.md

@@ -246,6 +246,12 @@ Please use Boosted v5.3.2 to have the dark mode available.
 
 - <span class="badge bg-success">New</span> Our range documentation now provides an example which displays the current selected value for better usability, but with some extra JavaScript code.
 
+- <span class="badge bg-success">New</span> Star rating has been slightly changed for accessibility purpose; a visually hidden `span` matching the title attribute was added and color contrast of inactive stars has been updated. Please reflect this modification into your websites. Our documentation also includes a disabled and a readonly state for this form element.
+  ```diff
+  -    <label for="excellent" title="Excellent"></label>
+  +    <label for="excellent" title="Excellent"><span class="visually-hidden">Excellent</span></label>
+  ```
+
 ### Helpers and utilities
 
 - <span class="badge bg-success">New</span> `.border-{color}-subtle`.