material-inspired-component-library 9.1.1 → 9.1.2

package/components/menu/index.scss

@@ -139,12 +139,12 @@ $item-classes: ':is(.micl-list-item-one, .micl-list-item-two, .micl-list-item-th
 }
 
 .micl-menu[popover], select {
-    --md-comp-menu-motion-effects: #{motion.$md-sys-motion-expressive-fast-effects};
-    --md-comp-menu-motion-effects-duration: #{motion.$md-sys-motion-expressive-default-effects-duration};
-    --md-comp-menu-motion-effects-duration-reverse: #{motion.$md-sys-motion-expressive-default-effects-duration};
-    --md-comp-menu-motion-spatial: #{motion.$md-sys-motion-expressive-default-spatial};
-    --md-comp-menu-motion-spatial-duration: #{motion.$md-sys-motion-expressive-default-spatial-duration};
-    --md-comp-menu-motion-spatial-duration-reverse: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
+    --_menu-motion-effects: var(--md-comp-menu-motion-effects, #{motion.$md-sys-motion-expressive-fast-effects});
+    --_menu-motion-effects-duration: var(--md-comp-menu-motion-effects-duration, #{motion.$md-sys-motion-expressive-default-effects-duration});
+    --_menu-motion-effects-duration-reverse: var(--md-comp-menu-motion-effects-duration-reverse, #{motion.$md-sys-motion-expressive-default-effects-duration});
+    --_menu-motion-spatial: var(--md-comp-menu-motion-spatial, #{motion.$md-sys-motion-expressive-default-spatial});
+    --_menu-motion-spatial-duration: var(--md-comp-menu-motion-spatial-duration, #{motion.$md-sys-motion-expressive-default-spatial-duration});
+    --_menu-motion-spatial-duration-reverse: var(--md-comp-menu-motion-spatial-duration-reverse, #{motion.$md-sys-motion-expressive-fast-spatial-duration});
 
     --md-comp-list-container-shape: var(--md-comp-menu-active-container-shape, var(--md-comp-menu-container-shape, var(--md-sys-shape-corner-large, 16px)));
 
@@ -212,7 +212,7 @@ $item-classes: ':is(.micl-list-item-one, .micl-list-item-two, .micl-list-item-th
     border: none;
     outline: none;
     background-color: transparent;
-    --micl-duration: var(--md-comp-menu-motion-spatial-duration-reverse);
+    --micl-duration: var(--_menu-motion-spatial-duration-reverse);
     --micl-easing: linear;
     --_group-shape: var(--md-comp-menu-group-shape, var(--md-sys-shape-corner-small, 8px));
 
@@ -222,12 +222,12 @@ $item-classes: ':is(.micl-list-item-one, .micl-list-item-two, .micl-list-item-th
     transform-origin: center top;
     transition:
         opacity var(--micl-duration) var(--micl-easing),
-        transform var(--micl-duration) var(--md-comp-menu-motion-spatial),
+        transform var(--micl-duration) var(--_menu-motion-spatial),
         overlay var(--micl-duration) linear allow-discrete,
         display var(--micl-duration) linear allow-discrete;
 
     &:popover-open {
-        --micl-duration: var(--md-comp-menu-motion-spatial-duration);
+        --micl-duration: var(--_menu-motion-spatial-duration);
         --micl-easing: #{motion.$md-sys-motion-easing-emphasized-decelerate};
 
         display: flex;
@@ -249,9 +249,9 @@ $item-classes: ':is(.micl-list-item-one, .micl-list-item-two, .micl-list-item-th
     &::backdrop {
         background-color: rgba(0, 0, 0, 0);
         transition:
-            background-color var(--md-comp-menu-motion-effects-duration) linear,
-            overlay var(--md-comp-menu-motion-effects-duration) linear allow-discrete,
-            display var(--md-comp-menu-motion-effects-duration) linear allow-discrete;
+            background-color var(--_menu-motion-effects-duration) linear,
+            overlay var(--_menu-motion-effects-duration) linear allow-discrete,
+            display var(--_menu-motion-effects-duration) linear allow-discrete;
     }
 
     .micl-list {
@@ -259,7 +259,7 @@ $item-classes: ':is(.micl-list-item-one, .micl-list-item-two, .micl-list-item-th
         row-gap: 2px;
         background-color: var(--md-comp-menu-standard-container-color, var(--md-sys-color-surface-container-low));
         box-shadow: var(--md-comp-menu-container-elevation, var(--md-sys-elevation-level2));
-        transition: border-radius var(--md-comp-menu-motion-effects-duration-reverse) linear;
+        transition: border-radius var(--_menu-motion-effects-duration-reverse) linear;
 
         &+ .micl-list {
             border-start-start-radius: var(--_group-shape);

package/components/navigationbar/index.scss

@@ -19,7 +19,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-@use '../../foundations/layout';
+@use '../../foundations/layout/tokens' as layout;
 @use '../../styles/elevation';
 @use '../../styles/statelayer';
 @use '../navigationrail/navitem';
@@ -115,6 +115,12 @@ nav.micl-navigationbar {
                 margin-block-start: 0;
                 padding-inline-end: var(--md-comp-nav-bar-item-horizontal-active-indicator-trailing-space, 16px);
             }
+            .micl-navigationbar__text:has(+ .micl-badge--trailing) {
+                padding-inline-end: 0;
+            }
+            .micl-badge--trailing {
+                margin-inline-end: var(--md-comp-nav-bar-item-horizontal-active-indicator-trailing-space, 16px);
+            }
         }
     }
 }

package/components/navigationrail/index.scss

@@ -19,7 +19,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-@use '../../foundations/layout';
+@use '../../foundations/layout/tokens' as layout;
 @use '../../styles/elevation';
 @use '../../styles/motion';
 @use '../../styles/shape';
@@ -44,13 +44,12 @@
 @include typography.scale('label-large');
 
 .micl-navigationrail {
-    --md-comp-nav-rail-spring-buffer: 100px;
-    --md-comp-nav-rail-divider-thickness: 0px;
-    --md-comp-nav-rail-motion-spatial: #{motion.$md-sys-motion-expressive-slow-spatial};
-    --md-comp-nav-rail-motion-duration: #{motion.$md-sys-motion-expressive-slow-spatial-duration};
-    --md-comp-nav-rail-motion-duration-reverse: #{motion.$md-sys-motion-expressive-default-spatial-duration};
-    --md-comp-nav-rail-morph-duration: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
-    --md-comp-nav-rail-morph-duration-reverse: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
+    --_navigationrail-spring-buffer: var(--md-comp-nav-rail-spring-buffer, 100px);
+    --_navigationrail-motion-spatial: var(--md-comp-nav-rail-motion-spatial, #{motion.$md-sys-motion-expressive-slow-spatial});
+    --_navigationrail-motion-duration: var(--md-comp-nav-rail-motion-duration, #{motion.$md-sys-motion-expressive-slow-spatial-duration});
+    --_navigationrail-motion-duration-reverse: var(--md-comp-nav-rail-motion-duration-reverse, #{motion.$md-sys-motion-expressive-default-spatial-duration});
+    --_navigationrail-morph-duration: var(--md-comp-nav-rail-morph-duration, #{motion.$md-sys-motion-expressive-fast-spatial-duration});
+    --_navigationrail-morph-duration-reverse: var(--md-comp-nav-rail-morph-duration-reverse, #{motion.$md-sys-motion-expressive-fast-spatial-duration});
 
     --_navigationrail-current-max-width: var(--md-comp-nav-rail-collapsed-container-width, 96px);
     --_navigationrail-current-min-width: var(--md-comp-nav-rail-collapsed-container-width, 96px);
@@ -58,10 +57,10 @@
     --_navigationrail-item-width: var(--md-comp-nav-rail-item-vertical-active-indicator-width, 56px);
     --_navigationrail-item-target-height: var(--_navigationrail-item-base-height);
 
-    --micl-duration: var(--md-comp-nav-rail-motion-duration-reverse);
+    --micl-duration: var(--_navigationrail-motion-duration-reverse);
 
     --_navigationrail-content-gap: var(--md-comp-nav-rail-item-container-vertical-space, 6px);
-    --_navigationrail-morph-speed: var(--md-comp-nav-rail-morph-duration-reverse);
+    --_navigationrail-morph-speed: var(--_navigationrail-morph-duration-reverse);
     --_navigationrail-container-delay: calc(var(--_navigationrail-morph-speed) / 2);
     --_navigationrail-item-delay: 0ms;
     --_navigationrail-text-animation: none;
@@ -165,7 +164,7 @@
                 flex-direction 0s calc(var(--_navigationrail-morph-speed) / 2) linear allow-discrete,
                 background-color calc(var(--_navigationrail-morph-speed) / 2) linear,
                 background-size 0ms,
-                --statelayer-opacity var(--md-comp-nav-rail-motion-duration) linear;
+                --statelayer-opacity var(--_navigationrail-motion-duration) linear;
 
             .micl-navigationrail__icon {
                 @extend %micl-navitem-icon;
@@ -186,7 +185,7 @@
             }
 
             &:active {
-                transition-duration: 0ms, 0ms, 0ms, calc(var(--_navigationrail-morph-speed) / 2), 0ms, var(--md-comp-nav-rail-motion-duration);
+                transition-duration: 0ms, 0ms, 0ms, calc(var(--_navigationrail-morph-speed) / 2), 0ms, var(--_navigationrail-motion-duration);
             }
         }
 
@@ -203,7 +202,7 @@
     }
 
     &[open] {
-        --micl-duration: var(--md-comp-nav-rail-motion-duration);
+        --micl-duration: var(--_navigationrail-motion-duration);
 
         border-start-end-radius: var(--md-comp-nav-rail-expanded-modal-container-shape, var(--md-sys-shape-corner-large));
         border-end-end-radius: var(--md-comp-nav-rail-expanded-modal-container-shape, var(--md-sys-shape-corner-large));
@@ -237,7 +236,7 @@ nav.micl-navigationrail:has(> .micl-navigationrail__headline .micl-button--toggl
     --_navigationrail-item-target-padding: 16px;
 
     --_navigationrail-content-gap: 0px;
-    --_navigationrail-morph-speed: var(--md-comp-nav-rail-morph-duration);
+    --_navigationrail-morph-speed: var(--_navigationrail-morph-duration);
     --_navigationrail-container-delay: 0ms;
     --_navigationrail-item-delay: calc(var(--_navigationrail-morph-speed) / 2);
     --_navigationrail-text-animation: var(--_navigationrail-morph-speed) linear forwards navigationrail-text-to-expanded;
@@ -263,6 +262,12 @@ nav.micl-navigationrail:has(> .micl-navigationrail__headline .micl-button--toggl
             margin-inline-start: var(--_navigationrail-expanded-text-margin);
             padding-inline-end: 16px;
         }
+        .micl-navigationrail__text:has(+ .micl-badge--trailing) {
+            padding-inline-end: 0;
+        }
+        .micl-badge--trailing {
+            margin-inline-end: 16px;
+        }
 
         &:not(:has(.micl-navigationrail__icon)) .micl-navigationrail__text {
             margin-inline-start: 0px;
@@ -272,7 +277,7 @@ nav.micl-navigationrail:has(> .micl-navigationrail__headline .micl-button--toggl
 }
 
 nav.micl-navigationrail:has(> .micl-navigationrail__headline .micl-button--toggle.micl-button--toggled:not([aria-pressed="true"])) {
-    --_navigationrail-morph-speed: var(--md-comp-nav-rail-morph-duration-reverse);
+    --_navigationrail-morph-speed: var(--_navigationrail-morph-duration-reverse);
     --_navigationrail-text-animation: var(--_navigationrail-morph-speed) linear forwards navigationrail-text-to-collapsed;
 }
 
@@ -287,25 +292,25 @@ nav.micl-navigationrail {
 
 dialog.micl-navigationrail {
     display: none;
-    min-inline-size: calc(var(--md-comp-nav-rail-expanded-container-width-minimum, 220px) + var(--md-comp-nav-rail-spring-buffer));
-    max-inline-size: calc(var(--md-comp-nav-rail-expanded-container-width-maximum, 360px) + var(--md-comp-nav-rail-spring-buffer));
-    margin-inline-start: calc(-1 * (var(--md-comp-nav-rail-expanded-container-width-maximum, 360px) + var(--md-comp-nav-rail-spring-buffer)));
-    padding-inline: var(--md-comp-nav-rail-spring-buffer) 0;
+    min-inline-size: calc(var(--md-comp-nav-rail-expanded-container-width-minimum, 220px) + var(--_navigationrail-spring-buffer));
+    max-inline-size: calc(var(--md-comp-nav-rail-expanded-container-width-maximum, 360px) + var(--_navigationrail-spring-buffer));
+    margin-inline-start: calc(-1 * (var(--md-comp-nav-rail-expanded-container-width-maximum, 360px) + var(--_navigationrail-spring-buffer)));
+    padding-inline: var(--_navigationrail-spring-buffer) 0;
     opacity: 0%;
 
     transition:
         opacity var(--micl-duration) linear,
-        margin-inline-start var(--micl-duration) var(--md-comp-nav-rail-motion-spatial),
+        margin-inline-start var(--micl-duration) var(--_navigationrail-motion-spatial),
         overlay var(--micl-duration) linear allow-discrete,
         display var(--micl-duration) linear allow-discrete;
 
     &[open] {
         display: flex;
-        margin-inline-start: calc(-1 * var(--md-comp-nav-rail-spring-buffer));
+        margin-inline-start: calc(-1 * var(--_navigationrail-spring-buffer));
         opacity: 100%;
 
         @starting-style {
-            margin-inline-start: calc(-1 * (var(--md-comp-nav-rail-expanded-container-width-maximum, 360px) + var(--md-comp-nav-rail-spring-buffer)));
+            margin-inline-start: calc(-1 * (var(--md-comp-nav-rail-expanded-container-width-maximum, 360px) + var(--_navigationrail-spring-buffer)));
             opacity: 0%;
         }
     }

package/components/radio/index.scss

@@ -41,9 +41,9 @@
 $radio: 'input[type=radio].micl-radio';
 
 #{$radio} {
-    --md-comp-radio-button-motion-effects: #{motion.$md-sys-motion-expressive-slow-effects};
-    --md-comp-radio-button-motion-duration: #{motion.$md-sys-motion-expressive-slow-effects-duration};
-    --md-comp-radio-button-motion-duration-reverse: #{motion.$md-sys-motion-expressive-default-effects-duration};
+    --_motion-effects: var(--md-comp-radio-button-motion-effects, #{motion.$md-sys-motion-expressive-slow-effects});
+    --_motion-duration: var(--md-comp-radio-button-motion-duration, #{motion.$md-sys-motion-expressive-slow-effects-duration});
+    --_motion-duration-reverse: var(--md-comp-radio-button-motion-duration-reverse, #{motion.$md-sys-motion-expressive-default-effects-duration});
 
     --_size: var(--md-comp-radio-button-icon-size, 20px);
     --_outline-width: var(--md-comp-radio-button-outline-width, 2px);
@@ -85,8 +85,8 @@ $radio: 'input[type=radio].micl-radio';
         background-clip: content-box;
         border-radius: var(--md-sys-shape-corner-full);
         transition:
-            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;
+            padding var(--_motion-duration-reverse) var(--_motion-effects),
+            border-color var(--_motion-duration-reverse) motion.$md-sys-motion-easing-emphasized;
     }
     &:checked {
         --statelayer-color: var(--md-sys-color-primary);
@@ -96,8 +96,8 @@ $radio: 'input[type=radio].micl-radio';
 
             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;
+                padding var(--_motion-duration) var(--_motion-effects),
+                border-color var(--_motion-duration) motion.$md-sys-motion-easing-emphasized;
         }
     }
     &:not(:disabled) {
@@ -117,7 +117,7 @@ $radio: 'input[type=radio].micl-radio';
         cursor: pointer;
         transition:
             background-size 0ms,
-            --statelayer-opacity var(--md-comp-radio-button-motion-duration) linear;
+            --statelayer-opacity var(--_motion-duration) linear;
 
         &:hover {
             --statelayer-opacity: var(--md-sys-state-hover-state-layer-opacity, 8%);

package/components/select/index.scss

@@ -41,8 +41,8 @@ $selects: ':is(.micl-textfield-filled, .micl-textfield-outlined) > select';
     --_line-height: var(--md-comp-text-field-container-height, 56px);
 }
 #{$selects} {
-    --md-comp-list-motion-effects: #{motion.$md-sys-motion-expressive-fast-spatial};
-    --md-comp-list-motion-duration: #{motion.$md-sys-motion-expressive-default-effects-duration};
+    --_list-motion-effects: var(--md-comp-list-motion-effects, #{motion.$md-sys-motion-expressive-fast-spatial});
+    --_list-motion-duration: var(--md-comp-list-motion-duration, #{motion.$md-sys-motion-expressive-default-effects-duration});
 
     appearance: base-select;
     line-height: var(--_line-height);
@@ -168,7 +168,7 @@ $selects: ':is(.micl-textfield-filled, .micl-textfield-outlined) > select';
             // the list transition is repeated here without it.
             transition:
                 background-size 0ms,
-                --statelayer-opacity var(--md-comp-list-motion-duration) linear;
+                --statelayer-opacity var(--_list-motion-duration) linear;
         }
     }
 }

package/components/sidesheet/README.md

@@ -1,5 +1,6 @@
 # Side sheet
-This component implements the [Material Design 3 Expressive Side sheet](https://m3.material.io/components/side-sheets/overview) design. Side sheets provide optional content and actions without interrupting the main content.
+
+This component implements the [Material Design 3 Expressive Side sheet](https://m3.material.io/components/side-sheets/overview) specification. Side sheets display optional content and actions without interrupting the user's workflow in the main content area.
 
 ## Basic Usage
 
@@ -14,6 +15,7 @@ To create a standard side sheet, use the `<dialog>` element with the `popover` a
       type="button"
       class="micl-iconbutton-standard-s material-symbols-outlined"
       popovertarget="mysidesheet"
+      aria-label="Close"
     >close</button>
   </div>
   <div class="micl-sidesheet__content">
@@ -32,7 +34,7 @@ Import the side sheet styles into your project:
 @use "material-inspired-component-library/dist/sidesheet";
 ```
 
-Or import all MICL styles:
+Alternatively, import all MICL styles at once:
 ```CSS
 @use "material-inspired-component-library/styles";
 ```
@@ -41,25 +43,67 @@ Or import all MICL styles:
 No custom JavaScript is required for the core functionality of the side sheet component.
 
 ### Live Demo
-A live example of the [Side sheet component](https://henkpb.github.io/micl/sidesheet.html) is available to interact with.
+A live interactive demo of the [Side sheet component](https://henkpb.github.io/micl/sidesheet.html) is available.
+
+## Anatomy
+A **standard** side sheet allows the rest of the page to remain usable by dynamically narrowing the main content area to make room for itself. Its headline and actions container are both optional; a side sheet may consist of nothing but content.
+
+| Element | Meaning |
+| --- | --- |
+| `dialog.micl-sidesheet` | The container. Add the `popover` attribute for a standard side sheet; omit it for a modal one. |
+| `.micl-sidesheet__headline` | The header row: holds an optional back button, a heading, and an optional close button. |
+| `.micl-sidesheet__content` | The scrollable body of the side sheet. |
+| `.micl-sidesheet__actions` | An optional row of buttons pinned to the bottom, usually preceded by an `<hr class="micl-divider">`. |
+
+A side sheet is **docked**, meaning it spans the full height of the viewport and sits flush against the trailing edge.
+
+> [!WARNING]
+> The **standard** side sheet component dynamically applies CSS rules to the `<body>` element to properly resize the main content area when the sheet is open. Overriding these rules may cause unexpected layout behavior. The applied rules are:
+> ```CSS
+> box-sizing: border-box;
+> margin: 0;
+> max-inline-size: /* varies dynamically based on side sheet state */
+> transition: /* handles max-inline-size animation */
+> ```
+> 
+> These rules only take effect on medium window size classes (600px) and wider. On compact screens lacking horizontal space, the main content area is left untouched and the side sheet simply overlays it.
 
 ## Variants
-A **modal** side sheet blocks access to the rest of the page and must be dismissed explicitly by the user. This is suitable for critical tasks or information that requires a user's full attention.
+Using a plain `popover` attribute makes the side sheet an *auto* popover: it closes automatically when the user presses <kbd>Esc</kbd> or clicks anywhere outside of it. This behavior is ideal for temporary panels like settings menus.
 
-To create a modal side sheet, use the `<dialog>` element without the `popover` attribute. Use `closedby="closerequest"` to prevent the side sheet from being dismissed by clicking outside of it. You'll also need a button or other control with `popovertarget` to close it.
+### Co-Existing Side Sheet
+For a side sheet that should remain open while the user interacts with the main content, use `popover="manual"` instead. A manual popover is only dismissed by its own close button:
 
+```HTML
+<dialog id="mysidesheet" class="micl-sidesheet" popover="manual" aria-labelledby="mytitle">
+  ...
+</dialog>
+```
+
+To open a **standard** side sheet, link a trigger button to the sheet's ID using `popovertarget`:
+```HTML
+<button type="button" popovertarget="mysidesheet">Open Side Sheet</button>
+```
+
+### Modal Side Sheet
+A **modal** side sheet blocks access to the rest of the page and requires the user to explicitly dismiss it. This variant is suitable for critical tasks or information requiring full attention.
+
+To create a modal side sheet, use the `<dialog>` element *without* the `popover` attribute. Because it isn't a popover, `popovertarget` has no effect. Instead, you must provide a button (or another control) using `command="close"` to dismiss it. A modal side sheet is inherently not dismissed by outside clicks; explicitly setting `closedby="closerequest"` enforces this behavior while keeping the <kbd>Esc</kbd> key functional. (If you *do* want outside clicks to close it, use `closedby="any"` instead).
 ```HTML
 <dialog id="mysidesheet" class="micl-sidesheet" closedby="closerequest" aria-labelledby="mytitle">
   <div class="micl-sidesheet__headline">
     <button
       type="button"
       class="micl-iconbutton-standard-s material-symbols-outlined"
+      aria-label="Back"
     >arrow_back</button>
     <h2 id="mytitle">Title</h2>
     <button
       type="button"
       class="micl-iconbutton-standard-s material-symbols-outlined"
-      popovertarget="mysidesheet"
+      command="close"
+      commandfor="mysidesheet"
+      aria-label="Close"
     >close</button>
   </div>
   <div class="micl-sidesheet__content">
@@ -72,54 +116,63 @@ To create a modal side sheet, use the `<dialog>` element without the `popover` a
 </dialog>
 ```
 
-To open a standard or modal side sheet, link a button to the side sheet's ID using the `popovertarget` attribute:
+To open a **modal** side sheet, use the `show-modal` command instead:
 ```HTML
-<button type="button" popovertarget="mysidesheet">Open Side Sheet</button>
+<button type="button" command="show-modal" commandfor="mysidesheet">Open Side Sheet</button>
 ```
 
-The back-button and the actions-container are optional. To remove the vertical divider of the standard side sheet, assign zero to the following CSS variable:
-```CSS
-#mysidesheet {
-  --md-comp-sidesheet-divider-thickness: 0;
-}
-```
-
-> [!WARNING]
-> The **standard** side sheet component adds CSS rules to the `<body>` element to properly resize the main content area when the side sheet is open. Overriding these rules may cause the component to behave unexpectedly. The rules that are applied are:
-> ```CSS
-> box-sizing: border-box;
-> margin: 0;
-> max-inline-size: ...varies depending on if the side sheet is opened...
-> transition: ...transition on max-inline-size...
-> ```
+## Accessibility
+* **Name the side sheet:** A `<dialog>` is exposed to assistive technologies as a dialog. Always provide an accessible name by pointing `aria-labelledby` to the headline's heading `id`.
+* **Name the icon buttons:** Always provide a descriptive `aria-label` for icon buttons, like the back and close buttons.
+* **Manage initial focus:** A standard side sheet relies on the Popover API, which automatically moves focus into the side sheet when the user tabs away from the trigger button, and returns focus upon closing. A modal side sheet natively focuses its first focusable descendant. This is rarely the desired behavior if the first element is a "Back" button. Add the `autofocus` attribute to the control that should legitimately receive focus first. *(Note: placing `autofocus` directly on the `<dialog>` element is ignored).*
+* **Scrolling by keyboard:** When the content container overflows, modern browsers make it a distinct tab stop (often with a visible focus ring) so it can be scrolled via arrow keys. This is a deliberate accessibility feature; do not suppress the focus ring.
+* **Dismissal constraints:** A side sheet opened with `popover` or `showModal()` is dismissed via the <kbd>Esc</kbd> key. A `popover="manual"` side sheet is not, meaning a visible close button is strictly required.
+* **Respect motion preferences:** All motion is automatically disabled if the user has requested reduced motion at the OS level. The side sheet (and the main content resizing) will toggle instantly.
 
 ## Theming
-Each side sheet style can be themed with CSS custom properties that follow the Material Design 3 component-token naming convention.
+Each side sheet can be themed using CSS custom properties formatted to match the Material Design 3 component-token naming convention.
 
 | Custom property | Meaning | Default |
-|---|---|---|
-| `--md-comp-sidesheet-container-width` | The default (and minimum allowed) width of the side sheet | `256px` |
-| `--md-comp-sidesheet-container-max-width` | The largest allowed width of the side sheet | `400px` |
-| `--md-comp-sidesheet-padding` | The amount of space between the vertical edges and the content | `--md-sys-layout-window-margin` |
+| --- | --- | --- |
+| `--md-comp-sidesheet-container-width` | The width of the side sheet | `256px` |
+| `--md-comp-sidesheet-container-max-width` | The maximum allowed width of the side sheet; any larger `--md-comp-sidesheet-container-width` is clamped to this | `400px` |
+| `--md-comp-sidesheet-padding` | The padding between the vertical edges and the content | `--md-sys-layout-window-margin` |
+| `--md-comp-sidesheet-headline-height` | The minimum height of the headline row; increase this if using icon buttons larger than `micl-iconbutton-standard-s` | `40px` |
 | `--md-comp-sidesheet-container-shape` | The corner rounding of the standard side sheet | `--md-sys-shape-corner-none` |
+| `--md-comp-sidesheet-content-color` | The text color inside the side sheet | `--md-sys-color-on-surface` |
 | `--md-comp-sidesheet-standard-container-color` | The background color of the standard side sheet | `--md-sys-color-surface` |
-| `--md-comp-sidesheet-divider-thickness` | The thickness of the vertical divider of the standard side sheet | `1px` |
-| `--md-comp-sidesheet-divider-color` | The color of the vertical divider of the standard side sheet | `--md-sys-color-outline` |
-| `--md-comp-sidesheet-standard-container-elevation` | The shadow (elevation) of the standard side sheet | `--md-sys-elevation-level0` |
+| `--md-comp-sidesheet-divider-thickness` | The thickness of the standard side sheet's vertical divider | `1px` |
+| `--md-comp-sidesheet-divider-color` | The color of the standard side sheet's vertical divider | `--md-sys-color-outline-variant` |
+| `--md-comp-sidesheet-standard-container-elevation` | The shadow depth (elevation) of the standard side sheet | `--md-sys-elevation-level0` |
 | `--md-comp-sidesheet-modal-container-color` | The background color of the modal side sheet | `--md-sys-color-surface-container-low` |
-| `--md-comp-sidesheet-modal-container-elevation` | The shadow (elevation) of the modal side sheet | `--md-sys-elevation-level1` |
-| `--md-comp-sidesheet-modal-container-shape` | The corner rounding of the modal side sheet, applied to the two corners facing the content | `--md-sys-shape-corner-large` |
+| `--md-comp-sidesheet-modal-container-elevation` | The shadow depth (elevation) of the modal side sheet | `--md-sys-elevation-level1` |
+| `--md-comp-sidesheet-modal-container-shape` | The corner rounding of the modal side sheet (applied to the two corners facing the main content) | `--md-sys-shape-corner-large` |
+| `--md-comp-sidesheet-motion-spatial` | The easing function for sliding the side sheet (uses a spring animation that slightly overshoots before settling) | `--md-sys-motion-expressive-slow-spatial` |
+| `--md-comp-sidesheet-motion-duration` | Animation duration for opening | `650ms` |
+| `--md-comp-sidesheet-motion-duration-reverse` | Animation duration for closing | `500ms` |
 
-
-**Example: Changing the width of the sidesheet**
+**Example: Changing the width of the side sheet**
 
 ```HTML
-<body style="--md-comp-sidesheet-container-width:320px">
+<body style="--md-comp-sidesheet-container-width: 320px;">
   <dialog id="mysidesheet" class="micl-sidesheet" popover>
     ...
   </dialog>
 </body>
 ```
 
+To remove the vertical divider of a standard side sheet, set the following CSS variable to zero:
+```CSS
+#mysidesheet {
+  --md-comp-sidesheet-divider-thickness: 0;
+}
+```
+
+> [!NOTE]
+> For a **standard** side sheet, define the `--md-comp-sidesheet-container-width` custom property on the `<body>` (or `:root`) element rather than on the side sheet itself. The CSS rule responsible for shrinking the main content area reads this variable from the body. Setting it only on the `<dialog>` would cause the side sheet and the main content area to fall out of sync.
+
 ## Compatibility
-This component uses the Popover API, which might not be supported in all browsers. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API#api.htmlelement.popover) for details.
+
+The standard side sheet relies on the Popover API. Please review [browser compatibility for the Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) if you are targeting older browsers.
+
+The modal side sheet is opened and closed using the `command` and `commandfor` attributes. Review [browser compatibility for the Invoker Commands API](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API). If these attributes are not supported in your target environments, calling `showModal()` and `close()` via JavaScript serves as an effective fallback.