material-inspired-component-library 9.0.2 → 9.1.1

package/components/checkbox/index.scss

@@ -22,8 +22,7 @@
 @use '../../styles/motion';
 @use '../../styles/shape';
 @use '../../styles/statelayer';
-@use '../../styles/typography';
-@use './label';
+@use '../../styles/togglelabel';
 
 @include shape.corner('full');
 
@@ -33,6 +32,7 @@
 @include statelayer.token('pressed-state-layer-opacity');
 @include statelayer.token('disabled-state-layer-opacity');
 @include statelayer.token('focus-indicator-thickness');
+@include statelayer.token('focus-indicator-outer-offset');
 @include statelayer.token('ripple-opacity-factor');
 @include statelayer.token('ripple-duration');
 @include statelayer.property;
@@ -51,28 +51,33 @@ $checkbox: 'input[type=checkbox].micl-checkbox';
     --_size: var(--md-comp-checkbox-container-size, 18px);
     --_outline-width: var(--md-comp-checkbox-outline-width, 2px);
     --_check-thickness: var(--md-comp-checkbox-check-thickness, 2px);
+    --_layer: max(var(--md-sys-state-layer-size, 40px), calc(var(--_size) + 22px));
+    --_target: max(var(--md-sys-state-target-size, 48px), calc(var(--_layer) + 8px));
     --statelayer-color: var(--md-sys-color-on-surface);
 
     appearance: none;
     box-sizing: border-box;
     position: relative;
-    inline-size: var(--md-sys-target-size, 48px);
-    min-inline-size: var(--md-sys-target-size, 48px);
-    block-size: var(--md-sys-target-size, 48px);
-    min-block-size: var(--md-sys-target-size, 48px);
+    inline-size: var(--_target);
+    min-inline-size: var(--_target);
+    block-size: var(--_target);
+    min-block-size: var(--_target);
     margin: 0;
-    border: calc((var(--md-sys-target-size, 48px) - var(--md-sys-state-layer-size, 40px)) / 2) solid transparent;
+    border: calc((var(--_target) - var(--_layer)) / 2) solid transparent;
     background-clip: content-box;
     background-color: transparent;
     -webkit-tap-highlight-color: transparent;
     border-radius: var(--md-sys-shape-corner-full);
-    outline-offset: -4px;
+    outline-offset: calc(
+        var(--md-sys-state-focus-indicator-outer-offset, 2px)
+        - ((var(--_target) - var(--_layer)) / 2)
+    );
 
     // The check mark: two currentColor borders rotated into a check, revealed by a
     // combination of block-size and clip-path transitions. currentColor, so that the
     // error and disabled states recolour it with a single color declaration.
     &::before {
-        --_check-width: calc(var(--_size) - 3px);
+        --_check-width: calc(var(--_size) * 5 / 6);
         --_check-height: calc(0.4667 * var(--_check-width));
 
         content: "";
@@ -82,14 +87,14 @@ $checkbox: 'input[type=checkbox].micl-checkbox';
         block-size: 0;
         inset: 0;
         inset-block-start: calc(-0.25 * var(--_size));
-        inset-inline-start: 1px;
+        inset-inline-start: calc(var(--_check-thickness) / 2);
         margin: auto;
         color: var(--md-comp-checkbox-selected-icon-color, var(--md-sys-color-on-primary));
         border-block-end: var(--_check-thickness) currentColor solid;
         border-inline-start: var(--_check-thickness) currentColor solid;
         transform: rotate(-45deg);
         transform-origin: center;
-        clip-path: rect(0 2px 0 0);
+        clip-path: rect(0 var(--_check-thickness) 0 0);
         z-index: 1;
         transition:
           block-size var(--md-sys-motion-duration-short3) var(--md-sys-motion-duration-short3) motion.$md-sys-motion-easing-standard-decelerate,
@@ -111,7 +116,7 @@ $checkbox: 'input[type=checkbox].micl-checkbox';
         inset: 0;
         margin: auto;
         border: var(--_outline-width) solid var(--_outline-color);
-        border-radius: 2px;
+        border-radius: var(--md-comp-checkbox-container-shape, 2px);
         background-color: var(--_container-color);
         transition:
             background-color var(--md-comp-checkbox-motion-duration-reverse) motion.$md-sys-motion-easing-emphasized var(--md-comp-checkbox-motion-duration-reverse),
@@ -122,7 +127,7 @@ $checkbox: 'input[type=checkbox].micl-checkbox';
 
         &::before {
             block-size: var(--_check-height);
-            clip-path: rect(0 calc(var(--_size) - 5px) var(--_size) 0);
+            clip-path: rect(0 calc(var(--_check-width) - var(--_check-thickness)) var(--_size) 0);
             transition:
                 block-size var(--md-sys-motion-duration-short3) var(--md-comp-checkbox-motion-spatial),
                 clip-path var(--md-sys-motion-duration-long4) var(--md-sys-motion-duration-short3) var(--md-comp-checkbox-motion-spatial);
@@ -137,7 +142,7 @@ $checkbox: 'input[type=checkbox].micl-checkbox';
         }
     }
     &:indeterminate::before {
-        inset-inline-start: 2px;
+        inset-inline-start: var(--_check-thickness);
         border-inline-start-width: 0px;
         transform: rotate(0deg);
     }
@@ -241,28 +246,33 @@ $checkbox: 'input[type=checkbox].micl-checkbox';
 }
 
 #{$checkbox}:not(:disabled) + label,
-label:has(+ #{$checkbox}:not(:disabled)) {
+label:has(+ #{$checkbox}:not(:disabled)),
+label:has(#{$checkbox}:not(:disabled)) {
     @extend %micl-toggle-label-pointer;
 }
 #{$checkbox} + label,
-label:has(+ #{$checkbox}) {
+label:has(+ #{$checkbox}),
+label:has(#{$checkbox}) {
     @extend %micl-toggle-label;
 }
 #{$checkbox}:disabled + label,
 label:has(+ #{$checkbox}:disabled) {
     @extend %micl-toggle-label-disabled;
 }
+label:has(#{$checkbox}:disabled) {
+    @extend %micl-toggle-label-disabled-text;
+}
 
 #{$checkbox}:dir(rtl) {
     &::before {
-        clip-path: rect(0 var(--_size) var(--_size) calc(var(--_size) - 2px));
+        clip-path: rect(0 var(--_size) var(--_size) calc(var(--_size) - var(--_check-thickness)));
     }
     &:checked::before {
-        clip-path: rect(0 var(--_size) var(--_size) 2px);
+        clip-path: rect(0 var(--_size) var(--_size) var(--_check-thickness));
         transform: rotate(45deg);
     }
     &:indeterminate::before {
-        clip-path: rect(0 var(--_size) var(--_size) 2px);
+        clip-path: rect(0 var(--_size) var(--_size) var(--_check-thickness));
         transform: rotate(0deg);
     }
 }

package/components/chip/index.scss

@@ -176,9 +176,9 @@
             &::before {
                 content: "";
                 position: absolute;
-                inset-block-start: calc((100% - var(--md-sys-target-size, 48px)) / 2);
+                inset-block-start: calc((100% - var(--md-sys-state-target-size, 48px)) / 2);
                 inset-inline-start: 0;
-                block-size: var(--md-sys-target-size, 48px);
+                block-size: var(--md-sys-state-target-size, 48px);
                 inline-size: 100%;
             }
         }
@@ -195,10 +195,10 @@
             &::before {
                 content: "";
                 position: absolute;
-                inset-block-start: calc((100% - var(--md-sys-target-size, 48px)) / 2);
-                inset-inline-start: calc((100% - var(--md-sys-target-size, 48px)) / 2);
-                block-size: var(--md-sys-target-size, 48px);
-                inline-size: var(--md-sys-target-size, 48px);
+                inset-block-start: calc((100% - var(--md-sys-state-target-size, 48px)) / 2);
+                inset-inline-start: calc((100% - var(--md-sys-state-target-size, 48px)) / 2);
+                block-size: var(--md-sys-state-target-size, 48px);
+                inline-size: var(--md-sys-state-target-size, 48px);
             }
         }
         .micl-chip__avatar {

package/components/datepicker/index.scss

@@ -86,7 +86,7 @@ dialog.micl-dialog.micl-datepicker {
     --md-comp-date-picker-button-motion-duration: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
 
     // Internal alias: the target size is referenced from many descendants.
-    --_target: var(--md-sys-target-size, 48px);
+    --_target: var(--md-sys-state-target-size, 48px);
 
     inline-size: var(--md-comp-date-picker-modal-container-width, 360px);
 

package/components/iconbutton/index.scss

@@ -56,10 +56,10 @@ $iconbuttons: ':is([class*="micl-iconbutton-standard-"], [class*="micl-iconbutto
         display: flex;
         align-items: center;
         justify-content: center;
-        block-size: var(--md-sys-target-size, 48px);
+        block-size: var(--md-sys-state-target-size, 48px);
         inline-size: 100%;
-        min-inline-size: var(--md-sys-target-size, 48px);
-        inset: calc((var(--micl-height) - var(--md-sys-target-size, 48px)) / 2) 0 0 calc((min(100%, var(--md-sys-target-size, 48px)) - var(--md-sys-target-size, 48px)) / 2);
+        min-inline-size: var(--md-sys-state-target-size, 48px);
+        inset: calc((var(--micl-height) - var(--md-sys-state-target-size, 48px)) / 2) 0 0 calc((min(100%, var(--md-sys-state-target-size, 48px)) - var(--md-sys-state-target-size, 48px)) / 2);
         background-color: transparent;
     }
 }

package/components/list/index.scss

@@ -390,11 +390,15 @@ $unselected: ':not(:checked, :has(input[type=checkbox]:checked), #{$open-accordi
     }
 }
 #{$items} {
-    input[type=checkbox].micl-checkbox {
-        block-size: 24px;
-        min-block-size: 24px;
-        inline-size: 24px;
-        min-inline-size: 24px;
+    // The compact list controls. The checkbox and the radio button derive all four of their
+    // size properties and their transparent border from these two, so overriding them shrinks
+    // the box without leaving the pseudo-elements wider than the padding box that centres
+    // them: sizing the element directly left an 18px container inside a 16px padding box,
+    // which start-aligned it.
+    input[type=checkbox].micl-checkbox,
+    input[type=radio].micl-radio {
+        --_layer: max(24px, var(--_size));
+        --_target: var(--_layer);
     }
 }
 

package/components/navigationrail/README.md

@@ -8,12 +8,12 @@ To create a simple navigation rail, use a `<nav>` element with the `micl-navigat
 
 ```HTML
 <nav id="mynavigationrail" class="micl-navigationrail">
-  <div class="micl-navigationrail__content" role="menu">
-    <a href="#" class="micl-navigationrail__item" role="menuitem" aria-current="page">
+  <div class="micl-navigationrail__content">
+    <a href="#" class="micl-navigationrail__item" aria-current="page">
       <span class="micl-navigationrail__icon material-symbols-outlined" aria-hidden="true">inbox</span>
       <span class="micl-navigationrail__text">Inbox</span>
     </a>
-    <a href="#" class="micl-navigationrail__item" role="menuitem">
+    <a href="#" class="micl-navigationrail__item">
       <span class="micl-navigationrail__icon material-symbols-outlined" aria-hidden="true">outbox</span>
       <span class="micl-navigationrail__text">Outbox</span>
     </a>
@@ -35,11 +35,12 @@ Or import all MICL styles:
 ```
 
 ### JavaScript
-This component requires JavaScript to support keyboard navigation. The library will automatically initialize new components as they're added to the DOM.
+No custom JavaScript is required for the core functionality of this component.
 
-```JavaScript
-import micl from "material-inspired-component-library/dist/micl";
-```
+> [!NOTE]
+> Opening and closing a modal navigation rail is handled natively by the `<dialog>` element and its invoker buttons, and the navigation items are ordinary links, activated with `Enter` like any other link.
+> 
+> Marking the current destination is left to the application: give the item for the current page the `aria-current="page"` attribute.
 
 ### Live Demo
 A live example of the [Navigation rail component](https://henkpb.github.io/micl/navigationrail.html) is available to interact with.
@@ -62,7 +63,7 @@ The basic example creates a **collapsed** navigation rail. Add a menu button to
       aria-label="Toggle navigation rail"
     ></button>
   </div>
-  <div class="micl-navigationrail__content" role="menu">
+  <div class="micl-navigationrail__content">
     ...
   </div>
 </nav>
@@ -86,7 +87,7 @@ A **modal** navigation rail is hidden until the user clicks a menu button. When
       autofocus
     >menu_open</button>
   </div>
-  <div class="micl-navigationrail__content" role="menu">
+  <div class="micl-navigationrail__content">
     ...
   </div>
 </dialog>

package/components/radio/README.md

@@ -11,6 +11,8 @@ To add a basic radio button, use the `<input type="radio">` element with the `mi
 <label for="myradio">First choice</label>
 ```
 
+**Note on labels**: The component automatically applies `cursor: pointer` and the **on-surface** color role to any `<label>` immediately preceding, immediately following, or wrapping a `micl-radio` input. You are encouraged to customize these CSS settings to match your design system.
+
 ### CSS
 Import the radio button styles into your project:
 
@@ -32,9 +34,49 @@ A live example of the [Radio button component](https://henkpb.github.io/micl/rad
 ## Variants
 A radio button can be disabled by adding the `disabled` attribute to the `<input>` element.
 
-The Radio Button component respects the `dir` global attribute, automatically adjusting its layout for right-to-left (RTL) languages when `dir="rtl"` is applied to an ancestor element.
+The Radio button component respects the element's computed direction, automatically adjusting its layout for right-to-left (RTL) languages — whether the `dir` attribute is set on the element itself or inherited from an ancestor.
+
+To vertically align a radio button with its label, wrap both in an element with styling similar to the following:
+
+```CSS
+.my-valign-class {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+}
+```
+
+```HTML
+<div class="my-valign-class">
+  <input type="radio" id="myradio" class="micl-radio" name="foo">
+  <label for="myradio">First choice</label>
+</div>
+```
+
+## Radio group
+Radio buttons are only meaningful as a group. Give every radio button for a given question the same `name`, and the browser makes the choices mutually exclusive for you — selecting one clears the others, and only the selected value is submitted.
+
+The group is also a single stop in the tab order: <kbd>Tab</kbd> moves into and out of it, while the arrow keys move the selection between the buttons inside it. This behaviour is native, so it needs no JavaScript and no `role` attributes.
 
-The component applies `cursor: pointer` and the color role **on surface** to the `<label>` element immediately preceding or following an `<input type="radio">` with the `micl-radio` class. You are encouraged to customize these CSS settings to match your design system.
+Wrap the group in a `<fieldset>` with a `<legend>` so that assistive technology announces the question along with each of the options:
+
+```HTML
+<fieldset>
+  <legend>Delivery</legend>
+  <div class="my-valign-class">
+    <input type="radio" id="ship1" class="micl-radio" name="delivery" value="standard" checked>
+    <label for="ship1">Standard</label>
+  </div>
+  <div class="my-valign-class">
+    <input type="radio" id="ship2" class="micl-radio" name="delivery" value="express">
+    <label for="ship2">Express</label>
+  </div>
+</fieldset>
+```
+
+Always mark one option as `checked`, unless leaving the question unanswered is a valid state. A group with no preselected option cannot be returned to its initial state by the user once a choice has been made.
+
+Adding the `required` attribute to a radio button makes the whole group mandatory — the browser will not submit the form until one of the buttons carrying that `name` is selected. The [Form foundation](../../foundations/form/README.md) leaves radio buttons to the browser's own reporting, so no MICL-specific error class is involved.
 
 ## Theming
 Each radio button can be themed with CSS custom properties that follow the Material Design 3 component-token naming convention. Set them on any appropriate parent element to affect its child radio buttons.
@@ -50,19 +92,17 @@ Each radio button can be themed with CSS custom properties that follow the Mater
 
 ```HTML
 <div style="--md-comp-radio-button-icon-size:28px">
-  <input type="radio" id="myradio" class="micl-radio">
+  <input type="radio" id="myradio" class="micl-radio" name="foo">
   <label for="myradio">Large radio button</label>
 </div>
 ```
 
-To vertically align a radio button with its label, wrap both in an element that has a styling like suggested below:
+## Compatibility
+This component relies on a few recent CSS features, which may not be fully supported in your browser:
 
-```HTML
-<div style="display:flex;flex-direction:row;align-items:center">
-  <input type="radio" id="myradio" class="micl-radio">
-  <label for="myradio">Large radio button</label>
-</div>
-```
+| Feature | Used for |
+|---|---|
+| [Relative RGB color values](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#browser_compatibility) | The state layer and the ripple |
+| [`:has()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has) | Styling a `<label>` that precedes its radio button |
 
-## Compatibility
-This component utilizes relative RGB color values, which may not be fully supported in your browser. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#browser_compatibility) for details.
+Please check the linked browser-compatibility tables for details.

package/components/radio/index.scss

@@ -22,7 +22,7 @@
 @use '../../styles/motion';
 @use '../../styles/shape';
 @use '../../styles/statelayer';
-@use '../checkbox/label';
+@use '../../styles/togglelabel';
 
 @include shape.corner('full');
 
@@ -32,6 +32,7 @@
 @include statelayer.token('pressed-state-layer-opacity');
 @include statelayer.token('disabled-state-layer-opacity');
 @include statelayer.token('focus-indicator-thickness');
+@include statelayer.token('focus-indicator-outer-offset');
 @include statelayer.token('ripple-opacity-factor');
 @include statelayer.token('ripple-duration');
 @include statelayer.property;
@@ -46,26 +47,31 @@ $radio: 'input[type=radio].micl-radio';
 
     --_size: var(--md-comp-radio-button-icon-size, 20px);
     --_outline-width: var(--md-comp-radio-button-outline-width, 2px);
+    --_layer: max(var(--md-sys-state-layer-size, 40px), calc(var(--_size) + 20px));
+    --_target: max(var(--md-sys-state-target-size, 48px), calc(var(--_layer) + 8px));
+    --statelayer-color: var(--md-sys-color-on-surface);
 
     appearance: none;
     box-sizing: border-box;
     position: relative;
-    inline-size: var(--md-sys-target-size, 48px);
-    min-inline-size: var(--md-sys-target-size, 48px);
-    block-size: var(--md-sys-target-size, 48px);
-    min-block-size: var(--md-sys-target-size, 48px);
+    inline-size: var(--_target);
+    min-inline-size: var(--_target);
+    block-size: var(--_target);
+    min-block-size: var(--_target);
     margin: 0;
-    border: calc((var(--md-sys-target-size, 48px) - var(--md-sys-state-layer-size, 40px)) / 2) solid transparent;
+    border: calc((var(--_target) - var(--_layer)) / 2) solid transparent;
     background-clip: content-box;
     background-color: transparent;
     -webkit-tap-highlight-color: transparent;
     border-radius: var(--md-sys-shape-corner-full);
-    outline-offset: -7px;
+    outline-offset: calc(
+        var(--md-sys-state-focus-indicator-outer-offset, 2px)
+        - ((var(--_target) - var(--_layer)) / 2)
+    );
 
-    // The ring and the dot in one box: the dot is the primary background clipped to the
-    // content box, hidden while the padding fills the ring, revealed when the checked
-    // padding shrinks to reveal a dot of half the icon size.
     &::after {
+        --_outline-color: var(--md-comp-radio-button-unselected-icon-color, var(--md-sys-color-on-surface-variant));
+
         content: "";
         box-sizing: border-box;
         position: absolute;
@@ -74,7 +80,7 @@ $radio: 'input[type=radio].micl-radio';
         inset: 0;
         margin: auto;
         padding: calc((var(--_size) / 2) - var(--_outline-width));
-        border: var(--_outline-width) solid var(--md-comp-radio-button-unselected-icon-color, var(--md-sys-color-on-surface-variant));
+        border: var(--_outline-width) solid var(--_outline-color);
         background-color: var(--md-comp-radio-button-selected-icon-color, var(--md-sys-color-primary));
         background-clip: content-box;
         border-radius: var(--md-sys-shape-corner-full);
@@ -82,12 +88,17 @@ $radio: 'input[type=radio].micl-radio';
             padding var(--md-comp-radio-button-motion-duration-reverse) var(--md-comp-radio-button-motion-effects),
             border-color var(--md-comp-radio-button-motion-duration-reverse) motion.$md-sys-motion-easing-emphasized;
     }
-    &:checked::after {
-        border-color: var(--md-comp-radio-button-selected-icon-color, var(--md-sys-color-primary));
-        padding: calc(0.15 * var(--_size));
-        transition:
-            padding var(--md-comp-radio-button-motion-duration) var(--md-comp-radio-button-motion-effects),
-            border-color var(--md-comp-radio-button-motion-duration) motion.$md-sys-motion-easing-emphasized;
+    &:checked {
+        --statelayer-color: var(--md-sys-color-primary);
+
+        &::after {
+            --_outline-color: var(--md-comp-radio-button-selected-icon-color, var(--md-sys-color-primary));
+
+            padding: calc((var(--_size) / 4) - var(--_outline-width));
+            transition:
+                padding var(--md-comp-radio-button-motion-duration) var(--md-comp-radio-button-motion-effects),
+                border-color var(--md-comp-radio-button-motion-duration) motion.$md-sys-motion-easing-emphasized;
+        }
     }
     &:not(:disabled) {
         --micl-ripple: 1;
@@ -108,31 +119,33 @@ $radio: 'input[type=radio].micl-radio';
             background-size 0ms,
             --statelayer-opacity var(--md-comp-radio-button-motion-duration) linear;
 
-        &:hover,
-        &:focus-visible,
-        &:active {
-            --statelayer-color: var(--md-sys-color-on-surface);
-
-            &:checked {
-                --statelayer-color: var(--md-sys-color-primary);
-            }
-            &::after {
-                border-color: var(--md-sys-color-on-surface);
-            }
-            &:checked::after {
-                border-color: var(--md-comp-radio-button-selected-icon-color, var(--md-sys-color-primary));
-            }
-        }
         &:hover {
             --statelayer-opacity: var(--md-sys-state-hover-state-layer-opacity, 8%);
+
+            &:not(:checked)::after {
+                --_outline-color: var(--md-sys-color-on-surface);
+            }
         }
         &:focus-visible {
             --statelayer-opacity: var(--md-sys-state-focus-state-layer-opacity, 10%);
 
             outline: var(--md-sys-state-focus-indicator-thickness, 3px) solid var(--md-sys-color-secondary);
+
+            &:not(:checked)::after {
+                --_outline-color: var(--md-sys-color-on-surface);
+            }
         }
         &:active {
+            --statelayer-color: var(--md-sys-color-on-surface);
             --statelayer-opacity: var(--md-sys-state-pressed-state-layer-opacity, 10%);
+
+            &:not(:checked) {
+                --statelayer-color: var(--md-sys-color-primary);
+
+                &::after {
+                    --_outline-color: var(--md-sys-color-on-surface);
+                }
+            }
         }
         &.micl-rippling {
             animation: micl-ripple var(--md-sys-state-ripple-duration);
@@ -142,7 +155,7 @@ $radio: 'input[type=radio].micl-radio';
         opacity: var(--md-sys-state-disabled-state-layer-opacity, 38%);
 
         &::after {
-            border-color: var(--md-sys-color-on-surface);
+            --_outline-color: var(--md-sys-color-on-surface);
         }
         &:checked::after {
             background-color: var(--md-sys-color-on-surface);
@@ -151,14 +164,19 @@ $radio: 'input[type=radio].micl-radio';
 }
 
 #{$radio}:not(:disabled) + label,
-label:has(+ #{$radio}:not(:disabled)) {
+label:has(+ #{$radio}:not(:disabled)),
+label:has(#{$radio}:not(:disabled)) {
     @extend %micl-toggle-label-pointer;
 }
 #{$radio} + label,
-label:has(+ #{$radio}) {
+label:has(+ #{$radio}),
+label:has(#{$radio}) {
     @extend %micl-toggle-label;
 }
 #{$radio}:disabled + label,
 label:has(+ #{$radio}:disabled) {
     @extend %micl-toggle-label-disabled;
 }
+label:has(#{$radio}:disabled) {
+    @extend %micl-toggle-label-disabled-text;
+}

package/components/stepper/index.scss

@@ -61,7 +61,7 @@
             // re-anchor it to this button's box.
             &::before {
                 inset: auto;
-                inset-block-start: calc(anchor(var(--micl-stepper-anchor) center) - var(--md-sys-target-size, 48px) / 2);
+                inset-block-start: calc(anchor(var(--micl-stepper-anchor) center) - var(--md-sys-state-target-size, 48px) / 2);
                 inset-inline-start: anchor(var(--micl-stepper-anchor) start);
                 inset-inline-end: anchor(var(--micl-stepper-anchor) end);
                 inline-size: auto;

package/components/switch/README.md

@@ -11,6 +11,8 @@ To add a basic switch, use the `<input type="checkbox">` element with the `micl-
 <label for="myswitch">My choice</label>
 ```
 
+**Note on labels**: The component applies `cursor: pointer` and the color role **on surface** to the `<label>` element immediately preceding, immediately following, or wrapping the `<input type="checkbox">` with the `micl-switch` class. You are encouraged to customize these CSS settings to match your design system.
+
 ### CSS
 Import the switch styles into your project:
 
@@ -30,7 +32,7 @@ No custom JavaScript is required for the core functionality of this component.
 A live example of the [Switch component](https://henkpb.github.io/micl/switch.html) is available to interact with.
 
 ## Variants
-By default, the component displays an icon on the switch handle in both the selected and unselected state. To remove the icon in the unselected state, assign an empty string to the following CSS variable:
+By default, the component displays an icon on the switch handle in both the selected and unselected state. To remove the icon in the unselected state, set the corresponding CSS custom property to an empty string:
 
 ```CSS
 #myswitch {
@@ -48,8 +50,6 @@ A switch can be disabled by adding the `disabled` attribute to the `<input>` ele
 
 The Switch component respects the element's computed direction, automatically adjusting its layout for right-to-left (RTL) languages — whether the `dir` attribute (including `dir="auto"`) is set on the element itself or inherited from an ancestor.
 
-The component applies `cursor: pointer` and the color role **on surface** to the `<label>` element immediately preceding or following the `<input type="checkbox">` with the `micl-switch` class. You are encouraged to customize these CSS settings to match your design system.
-
 ## Theming
 Each switch can be themed with CSS custom properties that follow the Material Design 3 component-token naming convention. Set them on any appropriate parent element to affect its child switches.
 
@@ -68,6 +68,25 @@ Each switch can be themed with CSS custom properties that follow the Material De
 | `--md-comp-switch-selected-track-color` | The track color when the switch is "on" | `--md-sys-color-primary` |
 | `--md-comp-switch-selected-handle-color` | The handle color when the switch is "on" | `--md-sys-color-on-primary` |
 | `--md-comp-switch-selected-icon-color` | The icon color when the switch is "on" | `--md-sys-color-on-primary-container` |
+| `--md-comp-switch-unselected-hover-handle-color` | The handle color when the switch is "off" and hovered | `--md-sys-color-on-surface-variant` |
+| `--md-comp-switch-unselected-focus-handle-color` | The handle color when the switch is "off" and focused | `--md-sys-color-on-surface-variant` |
+| `--md-comp-switch-unselected-pressed-handle-color` | The handle color when the switch is "off" and pressed | `--md-sys-color-on-surface-variant` |
+| `--md-comp-switch-selected-hover-handle-color` | The handle color when the switch is "on" and hovered | `--md-sys-color-primary-container` |
+| `--md-comp-switch-selected-focus-handle-color` | The handle color when the switch is "on" and focused | `--md-sys-color-primary-container` |
+| `--md-comp-switch-selected-pressed-handle-color` | The handle color when the switch is "on" and pressed | `--md-sys-color-primary-container` |
+| `--md-comp-switch-unselected-state-layer-color` | The state layer color around the handle when the switch is "off" | `--md-sys-color-on-surface` |
+| `--md-comp-switch-selected-state-layer-color` | The state layer color around the handle when the switch is "on" | `--md-sys-color-primary` |
+| `--md-comp-switch-focus-indicator-color` | The color of the focus indicator | `--md-sys-color-secondary` |
+| `--md-comp-switch-disabled-unselected-track-color` | The track color when the switch is disabled and "off" | `--md-sys-color-surface-container-highest` |
+| `--md-comp-switch-disabled-unselected-track-outline-color` | The track border color when the switch is disabled and "off" | `--md-sys-color-on-surface` |
+| `--md-comp-switch-disabled-unselected-handle-color` | The handle color when the switch is disabled and "off" | `--md-sys-color-on-surface` |
+| `--md-comp-switch-disabled-unselected-icon-color` | The icon color when the switch is disabled and "off" | `--md-sys-color-surface-container-highest` |
+| `--md-comp-switch-disabled-selected-track-color` | The track color when the switch is disabled and "on" | `--md-sys-color-on-surface` |
+| `--md-comp-switch-disabled-selected-handle-color` | The handle color when the switch is disabled and "on" | `--md-sys-color-surface` |
+| `--md-comp-switch-disabled-selected-icon-color` | The icon color when the switch is disabled and "on" | `--md-sys-color-on-surface` |
+| `--md-comp-switch-disabled-track-opacity` | The opacity of the track when the switch is disabled | `12%` |
+
+Because this component follows the Material Design 3 token set, the handle requires distinct colors for each interaction state. Modifying `--md-comp-switch-selected-handle-color` only changes the *resting* state. To ensure a consistent theme, remember to also override the matching `-hover-`, `-focus-`, and `-pressed-` properties.
 
 **Example: Changing the width of the switch**
 
@@ -79,4 +98,13 @@ Each switch can be themed with CSS custom properties that follow the Material De
 ```
 
 ## Compatibility
-This component utilizes relative RGB color values, which may not be fully supported in your browser. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#browser_compatibility) for details.
+This component relies on several recent CSS features, which may not be fully supported in your browser:
+
+| Feature | Used for |
+|---|---|
+| [Relative RGB color values](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#browser_compatibility) | Dimming the icon of a disabled, selected switch |
+| [`color-mix()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix) | The state layer around the handle |
+| [`:has()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has) | Styling a `<label>` that precedes its switch |
+| [`:dir()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir) | Mirroring the icon for right-to-left languages |
+
+Please check the linked browser-compatibility tables for details.