material-inspired-component-library 8.1.0 → 9.0.0

package/components/navigationrail/index.scss

@@ -19,13 +19,13 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-@use '../../foundations';
 @use '../../foundations/layout';
 @use '../../styles/elevation';
 @use '../../styles/motion';
 @use '../../styles/shape';
 @use '../../styles/statelayer';
 @use '../../styles/typography';
+@use 'navitem';
 
 @include elevation.level(0);
 @include elevation.level(2);
@@ -42,7 +42,6 @@
 @include statelayer.keyframes;
 
 @include typography.scale('label-large');
-@include typography.scale('label-medium');
 
 .micl-navigationrail {
     --md-comp-nav-rail-spring-buffer: 100px;
@@ -56,9 +55,11 @@
     --_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);
     --_navigationrail-item-direction: column;
-    --_navigationrail-item-width: var(--md-comp-nav-rail-item-short-container-height, 56px);
+    --_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);
+
     --_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-container-delay: calc(var(--_navigationrail-morph-speed) / 2);
@@ -70,7 +71,7 @@
     display: flex;
     flex-direction: column;
     align-items: flex-start;
-    block-size: 100vh;
+    block-size: calc(100vh - env(safe-area-inset-top, 0px));
     min-block-size: 100%;
     margin-block: 0;
     margin-inline: calc(-1 * var(--md-sys-layout-window-margin, 0px)) auto;
@@ -80,7 +81,6 @@
     border: none;
     border-radius: var(--md-comp-nav-rail-collapsed-container-shape, 0px);
     box-shadow: var(--md-comp-nav-rail-collapsed-container-elevation, var(--md-sys-elevation-level0));
-    opacity: 100%;
     overflow: hidden;
     z-index: 9;
     interpolate-size: allow-keywords;
@@ -105,43 +105,19 @@
         inline-size: 100%;
         row-gap: var(--_navigationrail-content-gap);
         padding-block: var(--md-comp-nav-rail-item-header-space-minimum, 40px) 16px;
-        padding-inline: 20px 0;
+        padding-inline: 20px;
 
         overflow: hidden auto;
         transition: row-gap var(--_navigationrail-morph-speed) linear;
 
-        &> a.micl-navigationrail__item:focus-visible {
-            --statelayer-opacity: var(--md-sys-state-focus-state-layer-opacity, 10%);
-        }
-
         &> a.micl-navigationrail__item {
-            --micl-ripple: 1;
-            --statelayer-color: var(--md-sys-color-on-secondary-container);
+            @extend %micl-navitem;
+
             --_navigationrail-item-base-height: var(--md-comp-nav-rail-item-short-container-height, 56px);
             --_navigationrail-item-margin-bottom: 0px;
             --_navigationrail-item-padding-block: 12px;
 
-            box-sizing: border-box;
-            display: flex;
-            position: relative;
-            align-items: center;
             row-gap: var(--md-comp-nav-rail-collapsed-item-vertical-space, 4px);
-            outline: none;
-            text-decoration: none;
-            cursor: pointer;
-
-            overflow: visible;
-            background-color: transparent;
-            background-image:
-                radial-gradient(
-                    circle at var(--micl-x, center) var(--micl-y, center),
-                    transparent 0%,
-                    rgb(from var(--statelayer-color) r g b / calc(var(--statelayer-opacity) * var(--md-sys-state-ripple-opacity-factor))) 10%,
-                    transparent 10%
-                ),
-                linear-gradient(rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)));
-            background-repeat: no-repeat;
-            background-size: 0%, 100%;
 
             &:has(.micl-navigationrail__text) {
                 --_navigationrail-item-base-height: var(--md-comp-nav-rail-item-vertical-active-indicator-height, 32px);
@@ -178,7 +154,7 @@
             padding-block: var(--_navigationrail-item-target-padding, var(--_navigationrail-item-padding-block));
             flex-direction: var(--_navigationrail-item-direction);
 
-            border-radius: calc(var(--_navigationrail-item-target-height, var(--_navigationrail-item-base-height)) / 2);
+            border-radius: var(--md-comp-nav-rail-item-container-shape, calc(var(--_navigationrail-item-target-height, var(--_navigationrail-item-base-height)) / 2));
 
             transition:
                 inline-size calc(var(--_navigationrail-morph-speed) / 2) var(--_navigationrail-item-delay) linear,
@@ -192,58 +168,47 @@
                 --statelayer-opacity var(--md-comp-nav-rail-motion-duration) linear;
 
             .micl-navigationrail__icon {
+                @extend %micl-navitem-icon;
                 font-size: var(--md-comp-nav-rail-item-icon-size, var(--md-sys-icon-size));
                 inline-size: var(--md-comp-nav-rail-item-icon-size, var(--md-sys-icon-size));
-                margin: 0;
-                padding-block: 4px;
-                padding-inline: 16px;
-                color: var(--md-sys-color-on-surface-variant);
-                font-variation-settings: 'FILL' 0;
+                padding-inline: var(--md-comp-nav-rail-item-active-indicator-leading-space, 16px) var(--md-comp-nav-rail-item-active-indicator-trailing-space, 16px);
             }
             .micl-navigationrail__text {
-                @include typography.label-medium;
-                min-block-size: var(--md-sys-typescale-label-medium-line-height);
-                margin: 4px 0px 0px 0px;
-                color: var(--md-sys-color-on-surface-variant);
-                overflow: hidden;
+                @extend %micl-navitem-text;
                 animation: var(--_navigationrail-text-animation);
+                // the typography and box switch discretely at the midpoint of the morph,
+                // while the animation above fades the text out and back in around it
+                transition:
+                    font 0s calc(var(--_navigationrail-morph-speed) / 2),
+                    letter-spacing 0s calc(var(--_navigationrail-morph-speed) / 2),
+                    margin 0s calc(var(--_navigationrail-morph-speed) / 2),
+                    padding 0s calc(var(--_navigationrail-morph-speed) / 2);
             }
 
-            &:hover {
-                --statelayer-opacity: var(--md-sys-state-hover-state-layer-opacity, 8%);
-            }
             &:active {
-                --statelayer-opacity: var(--md-sys-state-pressed-state-layer-opacity, 10%);
                 transition-duration: 0ms, 0ms, 0ms, calc(var(--_navigationrail-morph-speed) / 2), 0ms, var(--md-comp-nav-rail-motion-duration);
             }
-            &.micl-rippling {
-                animation: micl-ripple var(--md-sys-state-ripple-duration) motion.$md-sys-motion-easing-standard;
-            }
         }
 
         &> a.micl-navigationrail__item[aria-current="page"] {
-            background-color: var(--md-sys-color-secondary-container);
+            @extend %micl-navitem-current;
 
             .micl-navigationrail__icon {
-                color: var(--md-sys-color-on-secondary-container);
-                font-variation-settings: 'FILL' 1;
+                @extend %micl-navitem-current-icon;
             }
             .micl-navigationrail__text {
-                color: var(--md-sys-color-secondary);
+                @extend %micl-navitem-current-text;
             }
         }
     }
 
     &[open] {
+        --micl-duration: var(--md-comp-nav-rail-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));
         box-shadow: var(--md-comp-nav-rail-expanded-modal-container-elevation, var(--md-sys-elevation-level2));
         background-color: var(--md-comp-nav-rail-expanded-modal-container-color, var(--md-sys-color-surface-container));
-        transition:
-            opacity var(--md-comp-nav-rail-motion-duration) linear,
-            margin-inline-start var(--md-comp-nav-rail-motion-duration) var(--md-comp-nav-rail-motion-spatial),
-            overlay var(--md-comp-nav-rail-motion-duration) linear allow-discrete,
-            display var(--md-comp-nav-rail-motion-duration) linear allow-discrete;
 
         &::backdrop {
             background-color: rgba(0, 0, 0, var(--md-sys-state-backdrop-opacity, 32%));
@@ -254,14 +219,14 @@
     &::backdrop {
         background-color: rgba(0, 0, 0, 0);
         transition:
-            background-color var(--md-comp-nav-rail-motion-duration) linear,
-            overlay var(--md-comp-nav-rail-motion-duration) linear allow-discrete,
-            display var(--md-comp-nav-rail-motion-duration) linear allow-discrete;
+            background-color var(--micl-duration) linear,
+            overlay var(--micl-duration) linear allow-discrete,
+            display var(--micl-duration) linear allow-discrete;
     }
 }
 
 dialog.micl-navigationrail,
-nav.micl-navigationrail:has(> .micl-navigationrail__headline .micl-button--toggle.micl-button--selected) {
+nav.micl-navigationrail:has(> .micl-navigationrail__headline .micl-button--toggle[aria-pressed="true"]) {
     --_navigationrail-current-max-width: var(--md-comp-nav-rail-expanded-container-width-maximum, 360px);
     --_navigationrail-current-min-width: var(--md-comp-nav-rail-expanded-container-width-minimum, 220px);
     --_navigationrail-item-direction: row;
@@ -283,15 +248,18 @@ nav.micl-navigationrail:has(> .micl-navigationrail__headline .micl-button--toggl
     background-color: var(--md-comp-nav-rail-expanded-container-color, var(--md-sys-color-surface));
 
     & > .micl-navigationrail__content > a.micl-navigationrail__item {
+        max-inline-size: 100%;
+
         &::before {
             content: "";
             position: absolute;
             inset: 0px;
-            inset-inline-end: calc(-1 * (var(--md-comp-nav-rail-expanded-container-width-maximum, 360px) - 16px - 100%));
+            inset-inline-end: calc(-1 * (var(--md-comp-nav-rail-expanded-container-width-maximum, 360px) - var(--md-comp-nav-rail-item-horizontal-full-width-trailing-space, 16px) - 100%));
             background-color: transparent;
         }
         .micl-navigationrail__text {
             @include typography.label-large;
+            margin-block-start: 0;
             margin-inline-start: var(--_navigationrail-expanded-text-margin);
             padding-inline-end: 16px;
         }
@@ -303,7 +271,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(.micl-button--selected)) {
+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-text-animation: var(--_navigationrail-morph-speed) linear forwards navigationrail-text-to-collapsed;
 }
@@ -312,9 +280,9 @@ nav.micl-navigationrail {
     position: sticky;
     float: inline-start;
     inset: unset;
-    inset-block-start: 0;
+    inset-block-start: env(safe-area-inset-top, 0px);
     inset-inline-start: 0;
-    border-inline-end: var(--md-comp-nav-rail-divider-thickness, 0px) solid var(--md-comp-nav-rail-divider-color, var(--md-sys-divider-color));
+    border-inline-end: var(--md-comp-nav-rail-divider-thickness, 0px) solid var(--md-comp-nav-rail-divider-color, var(--md-comp-divider-color));
 }
 
 dialog.micl-navigationrail {
@@ -326,10 +294,10 @@ dialog.micl-navigationrail {
     opacity: 0%;
 
     transition:
-        opacity var(--md-comp-nav-rail-motion-duration-reverse) linear,
-        margin-inline-start var(--md-comp-nav-rail-motion-duration-reverse) var(--md-comp-nav-rail-motion-spatial),
-        overlay var(--md-comp-nav-rail-motion-duration-reverse) linear allow-discrete,
-        display var(--md-comp-nav-rail-motion-duration-reverse) linear allow-discrete;
+        opacity var(--micl-duration) linear,
+        margin-inline-start var(--micl-duration) var(--md-comp-nav-rail-motion-spatial),
+        overlay var(--micl-duration) linear allow-discrete,
+        display var(--micl-duration) linear allow-discrete;
 
     &[open] {
         display: flex;
@@ -343,68 +311,46 @@ dialog.micl-navigationrail {
     }
 }
 
-@keyframes navigationrail-text-to-collapsed {
-    0% {
-        @include typography.label-large;
-        margin-block-start: 0;
-        margin-inline-start: var(--_navigationrail-expanded-text-margin);
-        padding-inline-end: 16px;
-        opacity: 100%
-    }
-    49.9% {
-        @include typography.label-large;
-        margin-block-start: 0;
-        margin-inline-start: var(--_navigationrail-expanded-text-margin);
-        padding-inline-end: 16px;
-        opacity: 0%;
-    }
-    50.1% {
-        @include typography.label-medium;
-        min-block-size: var(--md-sys-typescale-label-medium-line-height);
-        margin-block-start: -16px;
-        margin-inline-start: 0px;
-        padding-inline-end: 0px;
-        opacity: 0%;
-    }
-    100% {
-        @include typography.label-medium;
-        min-block-size: var(--md-sys-typescale-label-medium-line-height);
-        margin-block-start: 4px;
-        margin-inline-start: 0px;
-        padding-inline-end: 0px;
-        opacity: 100%;
+// Adaptive rail: acts as a modal navigation rail below the named breakpoint and
+// as a permanently visible standard (expanded) rail at the breakpoint and above.
+$_breakpoints: (
+    medium:     layout.$md-sys-breakpoint-medium-min,
+    expanded:   layout.$md-sys-breakpoint-expanded-min,
+    large:      layout.$md-sys-breakpoint-large-min,
+    extralarge: layout.$md-sys-breakpoint-extralarge-min,
+);
+
+@each $name, $min in $_breakpoints {
+    @media (min-width: $min) {
+        dialog.micl-navigationrail--modal-to-#{$name}:not([open]) {
+            display: flex;
+            position: sticky;
+            float: inline-start;
+            inset: unset;
+            inset-block-start: env(safe-area-inset-top, 0px);
+            inset-inline-start: 0;
+            min-inline-size: var(--_navigationrail-current-min-width);
+            max-inline-size: var(--_navigationrail-current-max-width);
+            margin-inline: calc(-1 * var(--md-sys-layout-window-margin, 0px)) auto;
+            padding-inline: 0;
+            opacity: 100%;
+            border-inline-end: var(--md-comp-nav-rail-divider-thickness, 0px) solid var(--md-comp-nav-rail-divider-color, var(--md-comp-divider-color));
+        }
     }
 }
 
+// The static rules plus the delayed transitions above carry the typography switch;
+// the keyframes only fade the text and slide it along the block axis.
+@keyframes navigationrail-text-to-collapsed {
+    0%   { margin-block-start: 0;     opacity: 100%; }
+    45%  { margin-block-start: 0;     opacity: 0%; }
+    55%  { margin-block-start: -16px; opacity: 0%; }
+    100% { margin-block-start: 4px;   opacity: 100%; }
+}
+
 @keyframes navigationrail-text-to-expanded {
-    0% {
-        @include typography.label-medium;
-        min-block-size: var(--md-sys-typescale-label-medium-line-height);
-        margin-block-start: 4px;
-        margin-inline-start: 0px;
-        padding-inline-end: 0px;
-        opacity: 100%;
-    }
-    49.9% {
-        @include typography.label-medium;
-        min-block-size: var(--md-sys-typescale-label-medium-line-height);
-        margin-block-start: -16px;
-        margin-inline-start: 0px;
-        padding-inline-end: 0px;
-        opacity: 0%;
-    }
-    50.1% {
-        @include typography.label-large;
-        margin-block-start: 0px;
-        margin-inline-start: var(--_navigationrail-expanded-text-margin);
-        padding-inline-end: 16px;
-        opacity: 0%;
-    }
-    100% {
-        @include typography.label-large;
-        margin-block-start: 0px;
-        margin-inline-start: var(--_navigationrail-expanded-text-margin);
-        padding-inline-end: 16px;
-        opacity: 100%;
-    }
-}
+    0%   { margin-block-start: 4px;   opacity: 100%; }
+    45%  { margin-block-start: -16px; opacity: 0%; }
+    55%  { margin-block-start: 0;     opacity: 0%; }
+    100% { margin-block-start: 0;     opacity: 100%; }
+}

package/components/progressindicator/README.md

@@ -4,20 +4,40 @@ This component implements the [Material Design 3 Expressive Progress indicators]
 ## Basic Usage
 
 ### HTML
-Progress indicators use the native `<progress>` element. Add the `micl-progress-linear` class for the linear (bar) variant or `micl-progress-circular` for the circular (ring) variant.
+The flat linear variant and the circular variant use the native `<progress>` element. A **determinate** indicator has a known value: provide the `value` and (optionally) `max` attributes. An **indeterminate** indicator has an unknown value: omit the `value` attribute entirely.
 
-A **determinate** indicator has a known value. Provide the `value` and (optionally) `max` attributes:
+```HTML
+<progress class="micl-linear-progress" value="0.6"></progress>
+<progress class="micl-circular-progress" value="60" max="100"></progress>
+
+<progress class="micl-linear-progress"></progress>
+<progress class="micl-circular-progress"></progress>
+```
+
+The signature Expressive **wavy** indicators cannot be drawn inside a native `<progress>`, so they use a `progressbar`-role element with a wave child instead. A determinate wavy indicator reads its fraction from the `aria-valuenow` / `aria-valuemax` attributes:
 
 ```HTML
-<progress class="micl-progress-linear" value="0.6" max="1"></progress>
-<progress class="micl-progress-circular" value="60" max="100"></progress>
+<div role="progressbar" class="micl-linear-progress"
+     aria-valuemin="0" aria-valuemax="1" aria-valuenow="0.6">
+  <div class="micl-linear-progress__wave" aria-hidden="true"></div>
+</div>
+
+<div role="progressbar" class="micl-circular-progress"
+     aria-valuemin="0" aria-valuemax="1" aria-valuenow="0.6">
+  <div class="micl-circular-progress__wave" aria-hidden="true"></div>
+</div>
 ```
 
-An **indeterminate** indicator has an unknown value. Omit the `value` attribute entirely:
+The indeterminate wavy indicators take a modifier class and, per the ARIA `progressbar` pattern, simply omit `aria-valuenow`:
 
 ```HTML
-<progress class="micl-progress-linear"></progress>
-<progress class="micl-progress-circular"></progress>
+<div role="progressbar" class="micl-linear-progress micl-linear-progress--indeterminate">
+  <div class="micl-linear-progress__wave" aria-hidden="true"></div>
+</div>
+
+<div role="progressbar" class="micl-circular-progress micl-circular-progress--indeterminate">
+  <div class="micl-circular-progress__wave" aria-hidden="true"></div>
+</div>
 ```
 
 ### CSS
@@ -33,11 +53,9 @@ Or import all MICL styles:
 ```
 
 ### JavaScript
-No custom JavaScript is required for indeterminate indicators — the looping animation is driven entirely by CSS via the native `:indeterminate` state.
-
-For determinate indicators, the bundled handler mirrors the `value` and `max` attributes into the CSS custom properties that drive the fill, the active/track gap and the Expressive wave amplitude. It also flattens the wave into a straight line over the final 10% of progress.
+No custom JavaScript is required for the core functionality of this component.
 
-> **Updating progress at runtime:** the handler observes the `value` and `max` *attributes*. When you update progress dynamically, set the attribute (`element.setAttribute('value', 0.7)`) rather than only the IDL property (`element.value = 0.7`), so the indicator stays in sync. Alternatively, you may set the `--md-comp-progress-fraction` custom property (a number between `0` and `1`) directly for pure-CSS control without the handler.
+To update progress at runtime, set the `value` attribute (`<progress>`) or the `aria-valuenow` attribute (wavy) and the indicator animates to the new value. Note that setting only the IDL property (`element.value = 0.7`) does not change the attribute; use `element.setAttribute(…)`.
 
 ### Live Demo
 A live example of the [Progress Indicator component](https://henkpb.github.io/micl/progressindicator.html) is available to interact with.
@@ -45,44 +63,62 @@ A live example of the [Progress Indicator component](https://henkpb.github.io/mi
 ## Variants
 The Progress Indicator component offers the following variants:
 
-| CSS class | Description |
-| --------- | ----------- |
-| micl-progress-linear | A horizontal linear progress bar |
-| micl-progress-circular | A circular progress ring |
-| micl-progress-circular--s | Small circular ring (28px) |
-| micl-progress-circular--m | Medium circular ring (48px, default) |
-| micl-progress-circular--l | Large circular ring (64px) |
-
-Each variant is **determinate** when a `value` attribute is present and **indeterminate** when it is omitted.
-
-The signature Expressive *wavy active indicator* is applied to the linear variant as a static shape (rasterised once, so any number of determinate indicators cost nothing per frame). Its amplitude eases to zero as the indicator reaches completion, and setting `--md-comp-progress-wave-amplitude` to `0` produces a flat (pre-Expressive) active indicator. Only the transient loading states animate: the linear indeterminate comet, and the circular indeterminate spinner (a GPU-composited rotation). The circular variant renders a smooth ring.
-
-The component respects the `dir` global attribute, automatically mirroring the linear sweep direction for right-to-left (RTL) languages when `dir="rtl"` is applied to an ancestor element. It also honours the user's `prefers-reduced-motion` setting by disabling the travelling wave and looping animations.
-
-## Customizations
-You can customize the appearance of the Progress Indicator component by overriding its global CSS variables. Following the MICL convention, these `--md-comp-progress-*` variables can be set on `:root` or on any appropriate parent element to affect its child progress indicators. The colour roles default to the Material Design system colour tokens per the M3 progress-indicator specification.
-
-| Variable name | Default Value | Description |
-| ------------- | ------------- | ----------- |
-| --md-comp-progress-active-color | var(--md-sys-color-primary) | Colour of the active (filled) indicator |
-| --md-comp-progress-track-color | var(--md-sys-color-secondary-container) | Colour of the remaining track |
-| --md-comp-progress-stop-color | var(--md-sys-color-primary) | Colour of the linear end stop indicator dot |
-| --md-comp-progress-thickness | 4px | Thickness of the linear track and circular ring stroke |
-| --md-comp-progress-track-gap | 4px | Gap between the active indicator and the remaining track (linear) |
-| --md-comp-progress-stop-size | 4px | Diameter of the linear end stop indicator dot |
-| --md-comp-progress-linear-width | 100% | Default width of the linear indicator |
-| --md-comp-progress-wave-wavelength | 40px | Wavelength of the Expressive active wave |
-| --md-comp-progress-wave-amplitude | 3px | Amplitude of the Expressive active wave (set to `0` to disable) |
-| --md-comp-progress-indeterminate-duration | var(--md-sys-motion-duration-extra-long4) | Period of the indeterminate loop |
-| --md-comp-progress-circular-size | 48px | Diameter of the circular indicator |
-| --md-comp-progress-wave-image | (inline SVG) | The sine-ribbon mask used for the wavy active indicator |
-
-**Example: A thicker linear indicator with a calmer wave**
+| CSS class | Element | Description |
+| --------- | ------- | ----------- |
+| `micl-linear-progress` | `<progress>` | A flat horizontal progress bar |
+| `micl-linear-progress` | `<div role="progressbar">` | The Expressive wavy progress bar |
+| `micl-linear-progress--indeterminate` | `<div role="progressbar">` | Modifier for the indeterminate wavy bar |
+| `micl-circular-progress` | `<progress>` | A flat circular progress ring |
+| `micl-circular-progress` | `<div role="progressbar">` | The Expressive wavy progress ring |
+| `micl-circular-progress--indeterminate` | `<div role="progressbar">` | Modifier for the indeterminate wavy ring |
+
+- Right-to-left layouts mirror the sweep direction, the wave travel, the gap and the stop dot automatically — via the inherited direction, no extra classes.
+- Under `prefers-reduced-motion` the decorative wave travel is disabled; the functional progress animations are kept.
+
+## Theming
+Each progress indicator can be themed with CSS custom properties that follow the Material Design 3 component-token naming convention.
+
+### Linear (flat and wavy)
+
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-linear-progress-active-indicator-color` | Colour of the active indicator | `--md-sys-color-primary` |
+| `--md-comp-linear-progress-track-color` | Colour of the remaining track | `--md-sys-color-secondary-container` |
+| `--md-comp-linear-progress-stop-color` | Colour of the stop indicator dot | `--md-sys-color-primary` |
+| `--md-comp-linear-progress-track-thickness` | Thickness of the track | `4px` |
+| `--md-comp-linear-progress-active-thickness` | Thickness of the active indicator | `4px` |
+| `--md-comp-linear-progress-track-active-space` | Gap between the active indicator and the track | `4px` |
+| `--md-comp-linear-progress-stop-size` | Diameter of the stop indicator dot | `4px` |
+| `--md-comp-linear-progress-stop-trailing-space` | Inset of the stop dot from the trailing edge | `0px` |
+
+### Wavy only
+
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-linear-progress-active-wave-amplitude` | Maximum wave amplitude; set to `0px` for a flat (pre-Expressive) bar | `3px` |
+| `--md-comp-linear-progress-active-wave-wavelength` | Wavelength of the determinate wave | `40px` |
+| `--md-comp-linear-progress-indeterminate-active-wave-wavelength` | Wavelength of the indeterminate wave | `20px` |
+| `--md-comp-linear-progress-wave-image` | The repeating wave mask tile (advanced) | built-in |
+
+### Circular
+
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-circular-progress-active-indicator-color` | Colour of the active arc | `--md-sys-color-primary` |
+| `--md-comp-circular-progress-track-color` | Colour of the remaining track ring | `--md-sys-color-secondary-container` |
+| `--md-comp-circular-progress-size` | Diameter of the indicator | `40px` |
+| `--md-comp-circular-progress-active-thickness` | Stroke thickness of **both** the active arc and the track ring | `4px` |
+| `--md-comp-circular-progress-track-active-space` | Arc-length gap between the active arc and the track | `4px` |
+| `--md-comp-circular-progress-wave-image` | The wavy ring mask (advanced, wavy variant) | built-in |
+
+**Example: A thicker wavy indicator with a calmer wave**
 
 ```HTML
-<progress class="micl-progress-linear" value="0.4"
-  style="--md-comp-progress-thickness:8px;--md-comp-progress-wave-amplitude:2px"></progress>
+<div role="progressbar" class="micl-linear-progress" aria-valuenow="0.4" aria-valuemax="1"
+     style="--md-comp-linear-progress-active-thickness:6px;--md-comp-linear-progress-active-wave-amplitude:2px">
+  <div class="micl-linear-progress__wave" aria-hidden="true"></div>
+</div>
 ```
 
 ## Compatibility
-This component utilizes relative RGB color values, CSS `mask`, `conic-gradient` and registered `@property` custom properties, 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.
+Determinate indicators read the `value`/`max` (or `aria-valuenow`/`aria-valuemax`) attributes from CSS using typed [`attr()`](https://developer.mozilla.org/en-US/docs/Web/CSS/attr) (CSS Values Level 5). This is supported in Chromium-based browsers; Firefox has the feature implemented behind the `layout.css.attr.enabled` preference (about:config) and is expected to ship it soon.