material-inspired-component-library 9.1.0 → 9.1.2

package/components/datepicker/index.scss

@@ -31,6 +31,7 @@
 @include statelayer.token('focus-state-layer-opacity');
 @include statelayer.token('pressed-state-layer-opacity');
 @include statelayer.token('disabled-state-layer-opacity');
+@include statelayer.token('focus-indicator-thickness');
 @include statelayer.property;
 
 @include typography.scale('headline-large');
@@ -41,7 +42,7 @@
 %view-transition-base {
     block-size: fit-content;
     opacity: 1;
-    transition-duration: var(--md-comp-date-picker-motion-spatial-duration);
+    transition-duration: var(--_datepicker-motion-spatial-duration);
 
     &.micl-datepicker__view-hidden {
         block-size: 0;
@@ -65,12 +66,12 @@
     background-repeat: no-repeat;
     background-size: 100%;
     background-clip: content-box;
-    transition: --statelayer-opacity var(--md-comp-date-picker-button-motion-duration) linear;
+    transition: --statelayer-opacity var(--_datepicker-button-motion-duration) linear;
 
     &:hover {
         --statelayer-opacity: var(--md-sys-state-hover-state-layer-opacity);
     }
-    &:focus-visible {
+    &:is(:focus-visible, :has(input:focus-visible)) {
         --statelayer-opacity: var(--md-sys-state-focus-state-layer-opacity);
     }
     &:active {
@@ -78,15 +79,20 @@
     }
 }
 
+%focus-indicator {
+    outline: var(--md-sys-state-focus-indicator-thickness, 3px) solid var(--md-comp-date-picker-focus-indicator-color, var(--md-sys-color-secondary));
+    outline-offset: -1px;
+}
+
 dialog.micl-dialog.micl-datepicker {
-    --md-comp-date-picker-motion-spatial: #{motion.$md-sys-motion-expressive-fast-effects};
-    --md-comp-date-picker-motion-spatial-duration: #{motion.$md-sys-motion-expressive-default-spatial-duration};
-    --md-comp-date-picker-motion-duration: #{motion.$md-sys-motion-expressive-default-effects-duration};
-    --md-comp-date-picker-motion-duration-reverse: #{motion.$md-sys-motion-expressive-fast-effects-duration};
-    --md-comp-date-picker-button-motion-duration: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
+    --_datepicker-motion-spatial: var(--md-comp-date-picker-motion-spatial, #{motion.$md-sys-motion-expressive-fast-effects});
+    --_datepicker-motion-spatial-duration: var(--md-comp-date-picker-motion-spatial-duration, #{motion.$md-sys-motion-expressive-default-spatial-duration});
+    --_datepicker-motion-duration: var(--md-comp-date-picker-motion-duration, #{motion.$md-sys-motion-expressive-default-effects-duration});
+    --_datepicker-motion-duration-reverse: var(--md-comp-date-picker-motion-duration-reverse, #{motion.$md-sys-motion-expressive-fast-effects-duration});
+    --_datepicker-button-motion-duration: var(--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);
 
@@ -153,7 +159,7 @@ dialog.micl-dialog.micl-datepicker {
         min-block-size: 330px;
         padding-inline: 0;
         overflow: hidden auto;
-        transition: min-block-size var(--md-comp-date-picker-motion-spatial-duration) var(--md-comp-date-picker-motion-spatial);
+        transition: min-block-size var(--_datepicker-motion-spatial-duration) var(--_datepicker-motion-spatial);
     }
 
     .micl-dialog__actions {
@@ -179,6 +185,13 @@ dialog.micl-dialog.micl-datepicker {
             margin-block: -2px;
         }
     }
+
+    @media (prefers-reduced-motion: reduce) {
+        --_datepicker-motion-spatial-duration: 0ms;
+        --_datepicker-motion-duration: 0ms;
+        --_datepicker-motion-duration-reverse: 0ms;
+        --_datepicker-button-motion-duration: 0ms;
+    }
 }
 
 .micl-datepicker__inputmode {
@@ -275,10 +288,10 @@ dialog.micl-dialog.micl-datepicker {
     overflow: hidden;
     transform: translateX(0);
     transition:
-        transform var(--md-comp-date-picker-motion-spatial-duration) var(--md-comp-date-picker-motion-spatial),
-        opacity var(--md-comp-date-picker-motion-duration-reverse) linear,
-        block-size var(--md-comp-date-picker-motion-duration-reverse) linear allow-discrete,
-        display var(--md-comp-date-picker-motion-duration-reverse) linear allow-discrete;
+        transform var(--_datepicker-motion-spatial-duration) var(--_datepicker-motion-spatial),
+        opacity var(--_datepicker-motion-duration-reverse) linear,
+        block-size var(--_datepicker-motion-duration-reverse) linear allow-discrete,
+        display var(--_datepicker-motion-duration-reverse) linear allow-discrete;
 
     &.micl-datepicker__view-hidden {
         block-size: 0%;
@@ -293,6 +306,38 @@ dialog.micl-dialog.micl-datepicker {
     &.micl-moveleft {
         transform: translateX(-50%);
     }
+    // The flex row is laid out from the inline start, so the off-screen half of
+    // the strip sits on the opposite side in a right-to-left context.
+    &:dir(rtl) {
+        &.micl-startright,
+        &.micl-moveleft {
+            transform: translateX(50%);
+        }
+    }
+    &.micl-datepicker__nudge-min,
+    &.micl-datepicker__nudge-max {
+        animation: micl-datepicker-nudge var(--_datepicker-motion-duration) ease-in-out;
+    }
+    &.micl-datepicker__nudge-min {
+        --_nudge: 8px;
+    }
+    &.micl-datepicker__nudge-max {
+        --_nudge: -8px;
+    }
+    &:dir(rtl) {
+        &.micl-datepicker__nudge-min {
+            --_nudge: -8px;
+        }
+        &.micl-datepicker__nudge-max {
+            --_nudge: 8px;
+        }
+    }
+}
+
+@keyframes micl-datepicker-nudge {
+    50% {
+        translate: var(--_nudge, 0) 0;
+    }
 }
 .micl-datepicker__calendar {
     flex-shrink: 0;
@@ -304,12 +349,16 @@ dialog.micl-dialog.micl-datepicker {
 
     box-sizing: border-box;
     display: grid;
-    grid-template-columns: repeat(7, var(--_target));
     grid-template-rows: 40px repeat(6, var(--_target));
     block-size: 100%;
     inline-size: 100%;
     padding-inline: 12px;
 
+    > * {
+        display: grid;
+        grid-template-columns: repeat(7, var(--_target));
+    }
+
     span, time {
         box-sizing: border-box;
         display: inline-flex;
@@ -368,12 +417,16 @@ dialog.micl-dialog.micl-datepicker {
         &:is(.micl-datepicker__today, .micl-datepicker__selected):is(:hover, :focus-visible, :active) {
             --statelayer-color: currentColor;
         }
-        &.micl-datepicker__outside {
+        &.micl-datepicker__disabled {
             color: rgb(from var(--md-sys-color-on-surface) r g b / var(--md-sys-state-disabled-state-layer-opacity));
+            pointer-events: none;
         }
-        &:not(.micl-datepicker__outside) {
+        &:not(.micl-datepicker__disabled) {
             cursor: pointer;
         }
+        &:focus-visible {
+            @extend %focus-indicator;
+        }
     }
 }
 
@@ -403,15 +456,23 @@ dialog.micl-dialog.micl-datepicker {
 
         span {
             visibility: hidden;
-            color: var(--md-sys-color-on-surface);
+            color: inherit;
         }
         &:has(input:checked) {
-            background-color: var(--md-sys-color-surface-variant);
+            color: var(--md-comp-date-picker-selection-month-selected-label-text-color, var(--md-sys-color-on-surface));
+            background-color: var(--md-comp-date-picker-selection-month-selected-container-color, var(--md-sys-color-surface-variant));
 
             span {
                 visibility: visible;
             }
         }
+        &:has(input:disabled) {
+            color: rgb(from var(--md-sys-color-on-surface) r g b / var(--md-sys-state-disabled-state-layer-opacity));
+            pointer-events: none;
+        }
+        &:has(input:focus-visible) {
+            @extend %focus-indicator;
+        }
     }
 }
 .micl-datepicker__years {
@@ -444,10 +505,13 @@ dialog.micl-dialog.micl-datepicker {
             background-color: var(--md-comp-date-picker-selection-year-selected-container-color, var(--md-sys-color-primary));
 
             // The state layer of the selected year follows its label color.
-            &:is(:hover, :focus-visible, :active) {
+            &:is(:hover, :active, :has(input:focus-visible)) {
                 --statelayer-color: currentColor;
             }
         }
+        &:has(input:focus-visible) {
+            @extend %focus-indicator;
+        }
     }
 }
 :is(.micl-datepicker__months, .micl-datepicker__years) input[type=radio] {
@@ -475,6 +539,6 @@ dialog.micl-dialog.micl-datepicker {
     }
 }
 
-.micl-no-transition {
+.micl-datepicker__no-transition {
     transition: none !important;
 }

package/components/dialog/README.md

@@ -1,102 +1,170 @@
 # Dialog
-This component implements the [Material Design 3 Expressive Dialog](https://m3.material.io/components/dialogs/overview) design. A dialog is a small window that prompts the user to make a decision or enter additional information.
+This component implements the [Material Design 3 Expressive Dialog](https://m3.material.io/components/dialogs/overview) design. A dialog is a small, focused window that prompts the user to make a decision or enter additional information.
 
 ## Basic Usage
 
 ### HTML
-To create a basic dialog, use the `<dialog>` element with the `micl-dialog` class. You can open and close the dialog using JavaScript, or you can use a control element, such as a button, to open and close the dialog.
+
+To create a dialog, use the `<dialog>` element with the `micl-dialog` class and open it from a control element, such as a button.
 
 ```HTML
-<dialog id="mydialog" class="micl-dialog" popover closedby="any" aria-labelledby="mytitle" aria-describedby="mydesc">
+<dialog id="mydialog" class="micl-dialog" closedby="closerequest" aria-labelledby="mytitle" aria-describedby="mydesc">
   <div class="micl-dialog__headline">
     <h2 id="mytitle">Basic dialog</h2>
     <span id="mydesc" class="micl-dialog__supporting-text">An example of a basic dialog</span>
   </div>
+  <form method="dialog" class="micl-dialog__actions">
+    <button class="micl-button-text-s" value="" autofocus>Cancel</button>
+    <button class="micl-button-text-s" value="ok">OK</button>
+  </form>
 </dialog>
 
-<button type="button" popovertarget="mydialog">Open Basic Dialog</button>
-```
+<button type="button" class="micl-button-filled-m" command="show-modal" commandfor="mydialog">Open Basic Dialog</button>
 
-- The `popover` attribute makes the dialog a non-modal (light dismiss) popover.
+```
 
-- The `closedby="any"` attribute allows the dialog to be closed by clicking or tapping outside of it, or by pressing the <kbd>Esc</kbd> key.
+* `command="show-modal"` combined with `commandfor` opens the dialog as a **modal**: the browser moves it to the top layer, traps keyboard focus inside it, and makes the rest of the page inert. This is the Material Design default and the recommended approach for most use cases.
+* `closedby="closerequest"` is the default for a modal dialog and allows the <kbd>Esc</kbd> key to close it. Using `closedby="any"` will additionally close the dialog when the user clicks outside of it. Avoid `closedby="none"`, as it removes the <kbd>Esc</kbd> key escape route.
+* `aria-labelledby` points to the heading and `aria-describedby` to the supporting text, ensuring assistive technologies announce both when the dialog opens.
+* Buttons inside a `<form method="dialog">` close the dialog when activated, and the activating button's `value` is passed to `dialog.returnValue`. Give a canceling button an explicit `value=""`—a button without a `value` attribute leaves `returnValue` unchanged from its previous state. An empty `returnValue` is the conventional way to signal a cancellation.
+* `autofocus` designates the control that receives focus when the dialog opens. Place this on the least destructive action.
 
 ### CSS
+
 Import the dialog styles into your project:
 
 ```CSS
 @use "material-inspired-component-library/dist/button";
 @use "material-inspired-component-library/dist/iconbutton";
 @use "material-inspired-component-library/dist/dialog";
+
 ```
 
 Or import all MICL styles:
+
 ```CSS
 @use "material-inspired-component-library/styles";
+
 ```
 
 ### JavaScript
-No custom JavaScript is required for the core functionality of this component, as the native popover attribute handles the open/close behavior.
+
+No custom JavaScript is required for the core functionality of this component. The native `command` and `popover` attributes handle the open and close behaviors entirely.
 
 ### Live Demo
-A live example of the [Dialog component](https://henkpb.github.io/micl/dialog.html) is available to interact with.
 
-## Variants
-When dialogs with the `popover` attribute are opened, they animate from the control element to the center of the screen. They can be easily dismissed by clicking outside or pressing <kbd>Esc</kbd>.
+A live example of the [Dialog component](https://henkpb.github.io/micl/dialog.html) is available for interaction.
+
+## Anatomy
+
+A dialog consists of up to three sections:
+
+* `micl-dialog__headline`: The header of the dialog. It usually contains:
+  * A heading element (`<h1>`-`<h6>`).
+  * An optional icon (`micl-dialog__icon`). When present, the icon, heading, and supporting text are centered.
+  * An optional sub-header (`micl-dialog__subhead`). Text that exceeds one line is truncated with an ellipsis.
+  * An optional `micl-dialog__supporting-text` element describing the dialog's purpose.
 
-Removing the `popover` attribute creates a more intrusive **modal** dialog. This type of dialog requires the user to interact with its buttons or press the <kbd>Esc</kbd> key to close it.
+
+* `micl-dialog__content`: The optional main content area where additional information is placed. This section scrolls if the content exceeds the dialog's maximum height.
+* `micl-dialog__actions`: A container for action buttons. In a modal dialog, these must be placed inside a `<form method="dialog">`.
 
 ```HTML
-<dialog id="mydialog" class="micl-dialog" closedby="closerequest" role="alertdialog" aria-labelledby="mytitle" aria-describedby="mydesc">
+<dialog id="mydialog" class="micl-dialog" closedby="closerequest" aria-labelledby="mytitle" aria-describedby="mydesc">
   <div class="micl-dialog__headline">
     <span class="micl-dialog__icon material-symbols-outlined" aria-hidden="true">info</span>
-    <h2 id="mytitle">Modal dialog</h2>
-    <span id="mydesc" class="micl-dialog__supporting-text">An example of a modal dialog</span>
+    <h2 id="mytitle">Headline</h2>
+    <span class="micl-dialog__subhead">Sub-header</span>
+    <span id="mydesc" class="micl-dialog__supporting-text">Supporting text</span>
   </div>
-  <div class="micl-dialog__actions">
-    <form method="dialog">
-      <button class="micl-button-text-s" autofocus>Cancel</button>
-      <button class="micl-button-text-s" value="save">Save</button>
-    </form>
+  <div class="micl-dialog__content">
+    …
   </div>
+  <form method="dialog" class="micl-dialog__actions">
+    <button class="micl-button-text-s" value="" autofocus>Cancel</button>
+    <button class="micl-button-text-s" value="ok">OK</button>
+  </form>
 </dialog>
 
-<button type="button" command="show-modal" commandfor="mydialog">Open Modal Dialog</button>
 ```
 
-- The `closedby="closerequest"` attribute restricts closing methods, typically requiring an explicit action within the dialog.
+## Variants
+
+### Alert dialog
 
-By default, modal dialogs open in the center of the screen. You can anchor a modal dialog to a control element using the `micl-dialog--docked` class and CSS Anchor settings, causing it to open relative to that element:
+A dialog that interrupts the user with an urgent message must use `role="alertdialog"` to ensure assistive technologies announce it appropriately. Keep the content concise and provide at least one confirming and one dismissive action.
 
 ```HTML
-<dialog id="mydialog" class="micl-dialog micl-dialog--docked" style="position-anchor:--myanchor">
+<dialog id="mydialog" class="micl-dialog" closedby="closerequest" role="alertdialog" aria-labelledby="mytitle" aria-describedby="mydesc">
+  <div class="micl-dialog__headline">
+    <span class="micl-dialog__icon material-symbols-outlined" aria-hidden="true">delete</span>
+    <h2 id="mytitle">Delete selected images?</h2>
+    <span id="mydesc" class="micl-dialog__supporting-text">Images will be permanently removed from all synchronized devices.</span>
+  </div>
+  <form method="dialog" class="micl-dialog__actions">
+    <button class="micl-button-text-s" value="" autofocus>Cancel</button>
+    <button class="micl-button-text-s" value="dodelete">Delete</button>
+  </form>
 </dialog>
 
-<button type="button" popovertarget="mydialog" style="anchor-name:--myanchor">Open Modal Dialog</button>
+<button type="button" class="micl-button-outlined-m" command="show-modal" commandfor="mydialog">Delete images</button>
+
 ```
 
-### Dialog Structure Sections
-A dialog typically consists of three main sections to organize its content:
+### Light-dismiss dialog
 
-- `micl-dialog__headline`: The header of the dialog. It usually contains:
+Adding the `popover` attribute renders the dialog as a popover instead of a modal. It animates outward from the opening control element and closes automatically when the user clicks outside of it or presses <kbd>Esc</kbd>.
 
-  - A heading element (`<h1>`-`<h6>`).
+```HTML
+<dialog id="mydialog" class="micl-dialog" popover aria-labelledby="mytitle" aria-describedby="mydesc">
+  <div class="micl-dialog__headline">
+    <h2 id="mytitle">Light-dismiss dialog</h2>
+    <span id="mydesc" class="micl-dialog__supporting-text">An example of a dialog that closes when you click outside it</span>
+  </div>
+  <div class="micl-dialog__actions">
+    <button type="button" class="micl-button-text-s" popovertarget="mydialog" popovertargetaction="hide" autofocus>OK</button>
+  </div>
+</dialog>
+
+<button type="button" class="micl-button-outlined-m" popovertarget="mydialog">Open Dialog</button>
 
-  - An optional icon (use `micl-dialog__icon`).
+```
+
+> [!IMPORTANT]
+> A popover is not a modal. The browser does not trap focus inside it nor does it make the rest of the page inert. Review the Accessibility guidelines before choosing this variant.
 
-  - An optional sub-header (e.g., `<span class="micl-dialog__subhead">`).
+Because a popover is governed by the Popover API rather than standard dialog behavior, two modal attributes have no effect here:
 
-  - An optional `micl-dialog__supporting-text` element, describing the dialog's purpose.
+* `closedby` is ignored. Light dismissal and <kbd>Esc</kbd> key support are handled natively by the `popover` attribute.
+* `<form method="dialog">` will not close a popover. You must close it using a button with `popovertarget` and `popovertargetaction="hide"`, as shown above.
 
-- `micl-dialog__content`: The optional main content area of the dialog, where additional information can be placed.
+### Docked dialog
 
-- `micl-dialog__actions`: A container for action buttons that allow the user to perform actions related to the dialog or close it. Actions are typically placed in a `<form method="dialog">` for native HTML dialog closing.
+A docked dialog opens adjacent to the control element rather than centering on the screen. Add the `micl-dialog--docked` class, assign an `anchor-name` to the control element, and link the dialog using `position-anchor`:
+
+```HTML
+<dialog id="mydialog" class="micl-dialog micl-dialog--docked" style="position-anchor:--myanchor" popover aria-labelledby="mytitle">
+  <div class="micl-dialog__headline">
+    <h2 id="mytitle">Docked dialog</h2>
+  </div>
+  <div class="micl-dialog__actions">
+    <button type="button" class="micl-button-text-s" popovertarget="mydialog" popovertargetaction="hide">Close</button>
+  </div>
+</dialog>
+
+<button type="button" class="micl-button-outlined-m" popovertarget="mydialog" style="anchor-name:--myanchor">Open Docked Dialog</button>
+
+```
+
+* The dialog places itself below the control element and flips above it if there is insufficient vertical space.
+* A docked dialog fades in and out in place, rather than scaling out from the control element.
 
 ### Full-screen dialog
-A full-screen dialog covers the entire viewport, primarily on smaller screens. On screens wider than 560 pixels, a full-screen dialog behaves like a basic dialog. Use the `micl-dialog--fullscreen` modifier class for this variant:
+
+A full-screen dialog covers the entire viewport on compact windows (599px and narrower). On wider windows, it behaves like a basic dialog. Use the `micl-dialog--fullscreen` modifier class:
 
 ```HTML
-<dialog id="mydialog" class="micl-dialog micl-dialog--fullscreen" closedby="none" aria-labelledby="mytitle" aria-describedby="mydesc">
+<dialog id="mydialog" class="micl-dialog micl-dialog--fullscreen" closedby="closerequest" aria-labelledby="mytitle" aria-describedby="mydesc">
   <form method="dialog" class="micl-dialog__headline">
     <button class="micl-dialog__fullscreen micl-iconbutton-standard-s material-symbols-outlined" aria-label="Close">close</button>
     <span class="micl-dialog__icon material-symbols-outlined" aria-hidden="true">person</span>
@@ -107,44 +175,71 @@ A full-screen dialog covers the entire viewport, primarily on smaller screens. O
     <span id="mydesc" class="micl-dialog__supporting-text">This dialog covers the whole screen.</span>
   </div>
   <form method="dialog" class="micl-dialog__actions">
-    <button class="micl-button-text-s" autofocus>Cancel</button>
+    <button class="micl-button-text-s" value="" autofocus>Cancel</button>
     <button class="micl-button-text-s" value="dosave">Save</button>
   </form>
 </dialog>
 
-<button type="button" command="show-modal" commandfor="mydialog">Open Full-Screen Dialog</button>
+<button type="button" class="micl-button-outlined-m" command="show-modal" commandfor="mydialog">Open Full-Screen Dialog</button>
+
 ```
 
-- In full-screen mode, `micl-dialog__fullscreen` buttons placed directly within the `micl-dialog__headline` become visible, while the `micl-dialog__icon` and `micl-dialog__actions` at the bottom are hidden.
+* In full-screen mode, `micl-dialog__fullscreen` buttons placed directly within the `micl-dialog__headline` become visible. The `micl-dialog__icon` and the standard `micl-dialog__actions` at the bottom are hidden.
+* On wider screens, the layout reverts: `micl-dialog__fullscreen` buttons are hidden, and the standard bottom actions (`micl-dialog__actions`) are displayed.
+* Scrolling within `micl-dialog__content` applies elevation to the header. This effect relies on scroll-driven animations.
+
+## Accessibility
 
-- When not in full-screen mode (e.g., on wider screens), the `micl-dialog__fullscreen` buttons are hidden, and the standard dialog actions (`micl-dialog__actions`) are visible.
+* **Prefer a modal dialog.** A dialog opened via `command="show-modal"` (or `dialog.showModal()`) correctly utilizes the top layer, traps focus, and hides background content from screen readers. A `popover` dialog does none of this. Reserve the light-dismiss variant strictly for short, non-critical context.
+* **Always label the dialog.** Point `aria-labelledby` to the primary heading element. If supporting text is present, link it using `aria-describedby`.
+* **Use `role="alertdialog"` exclusively** for dialogs that interrupt the user with urgent messages requiring immediate response.
+* **Maintain keyboard navigation.** `closedby="closerequest"` is the default for a reason. Using `closedby="none"` removes the <kbd>Esc</kbd> key escape route and should only be used when a user *must not* abandon the process (and even then, an explicit close button must remain).
+* **Assign `autofocus`** to the control that should receive focus upon opening, prioritizing the dismissive action over destructive ones. Without it, browsers will focus the dialog container itself.
+* **Provide context for icons.** Give icon-only buttons an `aria-label`, and mark decorative glyphs (like `micl-dialog__icon`) with `aria-hidden="true"`.
+* **Respect motion preferences.** Motion is disabled if the user has requested reduced motion at the OS level; the dialog will appear and disappear instantly.
 
 ## Theming
-Each dialog 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 dialogs.
+
+Dialogs can be themed using CSS custom properties following the Material Design 3 component-token naming convention. Apply them to a parent element to style its child dialogs.
 
 | Custom property | Meaning | Default |
-|---|---|---|
-| `--md-comp-dialog-min-width` | The minimum width of a dialog | `280px` |
-| `--md-comp-dialog-max-width` | The maximum width of a dialog | `560px` |
-| `--md-comp-dialog-padding` | The inner padding between the dialog's edge and its content | `24px` |
-| `--md-comp-dialog-headline-space` | The vertical spacing between the elements in the header | `16px` |
-| `--md-comp-dialog-container-color` | The background color of the dialog | `--md-sys-color-surface-container-high` |
-| `--md-comp-dialog-container-shape` | The corner rounding of the dialog | `--md-sys-shape-corner-extra-large` |
-| `--md-comp-dialog-container-elevation` | The shadow (elevation) of the dialog | `--md-sys-elevation-level3` |
-| `--md-comp-dialog-headline-color` | The text color of the headline | `--md-sys-color-on-surface` |
-| `--md-comp-dialog-supporting-text-color` | The text color of the supporting text | `--md-sys-color-on-surface-variant` |
-| `--md-comp-dialog-icon-color` | The color of the dialog icon | `--md-sys-color-secondary` |
-| `--md-comp-dialog-icon-size` | The size of the dialog icon | `--md-sys-icon-size` |
-| `--md-comp-full-screen-dialog-container-color` | The background color of a full-screen dialog | `--md-sys-color-surface` |
+| --- | --- | --- |
+| `--md-comp-dialog-min-width` | Minimum width of a dialog | `280px` |
+| `--md-comp-dialog-max-width` | Maximum width of a dialog | `560px` |
+| `--md-comp-dialog-margin` | Minimum padding between the dialog and the viewport edge | `48px` |
+| `--md-comp-dialog-padding` | Inner padding between the dialog edge and its content | `24px` |
+| `--md-comp-dialog-headline-space` | Vertical spacing between header elements | `16px` |
+| `--md-comp-dialog-container-color` | Dialog background color | `--md-sys-color-surface-container-high` |
+| `--md-comp-dialog-container-shape` | Dialog border radius (corner rounding) | `--md-sys-shape-corner-extra-large` |
+| `--md-comp-dialog-container-elevation` | Dialog shadow depth (elevation) | `--md-sys-elevation-level3` |
+| `--md-comp-dialog-content-color` | Text color for the main content area | `--md-sys-color-on-surface` |
+| `--md-comp-dialog-headline-color` | Text color for the headline | `--md-sys-color-on-surface` |
+| `--md-comp-dialog-subhead-color` | Text color for the sub-header | `--md-sys-color-on-surface` |
+| `--md-comp-dialog-supporting-text-color` | Text color for supporting text | `--md-sys-color-on-surface-variant` |
+| `--md-comp-dialog-icon-color` | Color of the header icon | `--md-sys-color-secondary` |
+| `--md-comp-dialog-icon-size` | Size of the header icon | `--md-sys-icon-size` |
+| `--md-comp-dialog-motion-spatial` | The easing function used when the dialog opens. Uses a spring animation that slightly overshoots the final size before settling | `--md-sys-motion-expressive-fast-spatial` |
+| `--md-comp-dialog-motion-duration` | Animation duration for opening | `650ms` |
+| `--md-comp-dialog-motion-duration-reverse` | Animation duration for closing | `350ms` |
+| `--md-comp-full-screen-dialog-container-color` | Background color of a full-screen dialog | `--md-sys-color-surface` |
 
 **Example: Changing the dialog padding**
 
 ```HTML
-<div style="--md-comp-dialog-padding:16px">
+<div style="--md-comp-dialog-padding: 16px;">
   <dialog class="micl-dialog">
   </dialog>
 </div>
+
 ```
 
 ## Compatibility
-This component uses **popover anchor positioning** to place the dialog in relation to its invoker. This is a modern CSS feature that may not be fully supported in all browsers. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/anchor#browser_compatibility) for details.
+
+This component utilizes modern web platform features. Review [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/anchor#browser_compatibility) before deploying it in production environments.
+
+* **Open/Close Mechanisms:** Relies on [Invoker commands](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API) (`command` / `commandfor`) and the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API). To support legacy browsers, you must implement manual `showModal()` JavaScript calls.
+* **Positioning:** [CSS anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/anchor) dynamically places docked dialogs. In unsupported browsers, light-dismiss dialogs will appear centered rather than scaling out from the control element, and docked dialogs will fall back to the center of the screen.
+* **Animations:** Uses [`@starting-style`](https://developer.mozilla.org/en-US/docs/Web/CSS/@starting-style) and [`transition-behavior: allow-discrete`](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-behavior) for open/close transitions. Without these, the dialog appears instantly.
+* **Dynamic Sizing:** [`interpolate-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/interpolate-size) allows the dialog to animate smoothly to its calculated width. In browsers that do not yet support this (e.g., Firefox 156), the dialog still fades and travels, but assumes its final dimensions immediately.
+* **Advanced Styling:** Utilizes [`:has()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has), [`:dir()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir), and [relative color syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Relative_colors) for icon layout, right-to-left placement, and backdrop rendering.
+* **Header Elevation:** Uses [Scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline/scroll) to elevate the header when content scrolls. Where unsupported, the header remains flat—a purely cosmetic fallback.