material-inspired-component-library 8.1.1 → 9.0.0

package/README.md

@@ -1,21 +1,47 @@
-# Material-Inspired Component Library (MICL)
-The Material-Inspired Component Library (MICL) offers a free and open-source collection of beautifully crafted components leveraging native HTML markup, designed to align with the [Material Design 3](https://m3.material.io/) guidelines. MICL prioritizes minimal HTML markup and often requires no JavaScript, making it a lightweight and efficient choice for your projects.
+# MICL — Material Design 3 Expressive for the plain web
 
-## Why Choose MICL?
-- **Embrace Material Design 3:** Seamlessly integrate the aesthetic and user experience principles of Material Design into your web pages and applications.
-- **Lightweight & Efficient:** Benefit from components built with straightforward HTML and minimal to no JavaScript, ensuring fast loading times and a streamlined development process.
-- **Effortless Dark Mode:** Enjoy out-of-the-box support for both light and dark modes, automatically adapting to your defined color scheme.
+[![npm](https://img.shields.io/npm/v/material-inspired-component-library)](https://www.npmjs.com/package/material-inspired-component-library)
+[![license](https://img.shields.io/github/license/henkpb/micl)](LICENSE)
+![zero dependencies](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)
 
-## Why Might MICL Not Be for You?
-- **Heavy JavaScript Dependencies:** If your project heavily relies on a JavaScript framework for component interaction, MICL's minimalist approach might not be the best fit.
-- **Bootstrap Preference:** Users deeply integrated with or preferring the Bootstrap CSS framework may find MICL's distinct design philosophy less suitable.
-- **Legacy Browser Support:** MICL is designed for modern browsers, and comprehensive support for older browser versions is not a primary focus.
+**MICL (Material-Inspired Component Library)** is a free, open-source implementation of [Material Design 3](https://m3.material.io/) — including the current **M3 Expressive** update — built from native HTML elements and modern CSS. No custom elements, no framework, no runtime dependencies, and for most components no JavaScript at all.
 
-## Demo & Documentation 📖
-Explore the components in a live environment and see how they work.
+**[Live showcase](https://henkpb.github.io/micl/)** · **[Component documentation](components/README.md)** · **[Quick start](#quick-start-)**
 
-- **Live Demo:** [The MICL Showcase](https://henkpb.github.io/micl/)
-- **Component Documentation:** [View all component documentation](components/README.md)
+## Why MICL exists
+
+When Google wound down [material-web](https://github.com/material-components/material-web), the web platform lost its reference implementation of Material Design 3 — and the design system's newest chapter, **M3 Expressive**, never reached the open web at all.
+
+MICL picks up that torch with the opposite architecture. Where material-web wrapped every component in a JavaScript custom element, MICL styles the HTML you already write: a progress bar is a `<progress>`, a dialog is a `<dialog>`, a menu is a popover, a navigation rail is a `<nav>`. The heavy lifting is done by modern CSS — registered custom properties, container style queries, typed `attr()`, `clip-path: shape()`, anchor positioning — so components render on first paint, keep their native semantics and accessibility, and never fight your framework (or your decision not to use one).
+
+## Highlights
+
+- **The M3 Expressive catalogue, on the web first.** 29 components, the Material shape library, adaptive pane layouts — and the signature Expressive details, like wavy progress indicators drawn and animated entirely in CSS, with the wave motion running on the compositor.
+- **Native HTML first.** Components are your own markup plus a class. Forms post, dialogs trap focus, `<progress>` announces progress — because the platform does it, not a re-implementation.
+- **(Almost) no JavaScript.** Most components need none. All interactive behaviour for the entire library fits in one dependency-free ~11 kB minified and gzipped file — or import per-component slices and let your bundler tree-shake the rest.
+- **Theming per the spec.** Ready-made colour themes with light, dark and high-contrast variants, and every component themable through spec-named `--md-comp-*` custom properties.
+- **À la carte delivery.** Full bundle or per-component CSS/JS pairs, npm or CDN ([jsDelivr](https://cdn.jsdelivr.net/npm/material-inspired-component-library/dist/micl.css)).
+- **International by default.** Right-to-left layouts mirror automatically, and `prefers-reduced-motion` is respected throughout.
+
+## How MICL compares
+
+| | **MICL** | material-web | Beer CSS | MUI | Angular Material |
+|---|---|---|---|---|---|
+| Design spec | **M3 Expressive** | M3 | M3 | Material-influenced (M2 heritage) | M3 |
+| Actively developed | ✅ | ❌ development wound down | ✅ | ✅ | ✅ |
+| Framework required | none | none (Lit runtime) | none | React | Angular |
+| Component model | native HTML + CSS | custom elements | HTML + CSS classes | React components | Angular components |
+| Usable without JavaScript | ✅ most components | ❌ | partly | ❌ | ❌ |
+| Runtime dependencies | **0** | Lit | 0 | several | Angular |
+| Server-side rendering | plain HTML + CSS, nothing to hydrate | needs SSR shims | ✅ | hydration | hydration |
+
+<sup>Comparison reflects the situation at the time of writing (July 2026); corrections welcome.</sup>
+
+## Trade-offs — when MICL might not fit
+
+- **Modern browsers only.** MICL leans on current CSS. Chromium-based browsers get the full experience today; Firefox degrades gracefully where a feature hasn't shipped yet (e.g. determinate progress values wait on typed `attr()`, available behind a preview-setting). Legacy browser support is a non-goal.
+- **CSS-first philosophy.** If your team expects components as framework objects with props and events, MICL's markup-plus-classes approach will feel different — that difference is the point, but it is a real difference.
+- **Not a Bootstrap look-alike.** MICL implements Material Design 3 faithfully rather than offering a neutral, endlessly re-skinnable base.
 
 ## Quick start 🚀
 
@@ -28,10 +54,27 @@ npm install material-inspired-component-library
 
 **Sass/SCSS**
 
-To import the styles for a single component (e.g., the [Card component](components/card/README.md)):
+To import the styles for a single component (e.g., the [Card component](components/card/README.md)), import the shared base styles once, followed by the component:
 ```SCSS
+@use "material-inspired-component-library/dist/base";
 @use "material-inspired-component-library/dist/card";
 ```
+The base file contains the foundation design tokens and the `@property` registrations required by the ripple effect. It is small, needed only once, and already included in the full `micl.css`.
+
+Some components build on other MICL components; when importing them individually, import their companions as well (each component's README shows the complete list):
+
+| Component | Also import |
+| --------- | ----------- |
+| appbar | iconbutton |
+| datepicker | dialog, textfield, button, iconbutton, divider |
+| dialog | button, iconbutton |
+| menu | list |
+| navigationrail | iconbutton |
+| select | textfield, menu, list |
+| sidesheet | button, iconbutton, divider |
+| snackbar | button, iconbutton |
+| stepper | button |
+| timepicker | dialog, button, iconbutton |
 
 To import all MICL styles:
 ```SCSS
@@ -51,6 +94,8 @@ Copy the main `micl.css` file to your distribution folder and include it in your
 <link rel="stylesheet" type="text/css" href="path/to/dist/micl.css">
 ```
 
+The per-component stylesheets can be included the same way; include `base.css` once before them (`<link rel="stylesheet" type="text/css" href="path/to/dist/base.css">`).
+
 The main MICL CSS file can also be found on CDN networks, like on jsDelivr: `https://cdn.jsdelivr.net/npm/material-inspired-component-library/dist/micl.css`
 
 ### 3. Add the HTML & JavaScript
@@ -66,18 +111,31 @@ Here is a simple example of a [Card component](components/card/README.md).
 </div>
 ```
 
+And here is the Expressive circular progress indicator — note that updating `value` is all it takes; the 500 ms Material-motion transition, the size adjustments, and the track gap are all CSS:
+
+```HTML
+<progress class="micl-circular-progress" value="0.6"></progress>
+```
+
 Some components, like the [List](components/list/README.md), require a small amount of JavaScript to handle interactive behaviour. Because the JavaScript footprint in MICL is so small, you can import the code for all components at once.
 ```JavaScript
-import micl from "material-inspired-component-library/dist/micl";
+import "material-inspired-component-library/dist/micl";
 ```
 This will initialize all MICL components, including those that will be added to the DOM later on.
 
+To load only the JavaScript for the components you use, import their files individually. Each component registers itself with a shared runtime, so any combination works:
+```JavaScript
+import "material-inspired-component-library/dist/list";
+import "material-inspired-component-library/dist/textfield";
+```
+
 **Plain JavaScript**
 
 Copy the main `micl.js` file to your distribution folder and include it in your application:
 ```HTML
 <script src="path/to/dist/micl.js"></script>
 ```
+The per-component files can be included the same way (`<script src="path/to/dist/list.js"></script>`).
 
 The main MICL JavaScript file can also be found on CDN networks, like on jsDelivr: `https://cdn.jsdelivr.net/npm/material-inspired-component-library/dist/micl.js`
 
@@ -90,9 +148,23 @@ MICL uses the [**Google Sans**](https://fonts.google.com/specimen/Google+Sans) a
 
 The [Styles guide](styles/README.md) describes how to change the default font.
 
+## Under the hood 🔬
+
+MICL doubles as a working tour of what production CSS can do in 2026. A few of the techniques in the codebase:
+
+- **Typed `attr()`** turns `<progress value>` and `aria-valuenow` into animatable CSS values — determinate indicators transition per the Material motion spec with zero JavaScript.
+- **Registered `@property` custom properties** drive interpolable gradients: carved progress tracks, conic arcs, trigonometric cap positioning.
+- **Compositor-only animation**: the Expressive wave travel is a transform over a static mask — no per-frame repaints, no matter how many indicators run.
+- **`clip-path: shape()`** clips progress rings to geometrically antialiased annuli, with a gradient-mask fallback.
+- **Container style queries** switch components at exact computed states (a wave collapsing to a mathematically flat bar at 100 %).
+- **Anchor positioning** places menus and submenus without measurement code.
+
+Each component's README documents its approach and its graceful-degradation story.
+
 ## Foundations 🪟
-A separate CSS file, based on the [Material Design Layout Foundation](https://m3.material.io/foundations/layout/understanding-layout/overview), provides styles for an adaptive layout. It includes styles for the **window frame**, **body region** and **panes** that adjust to the available screen space, ensuring your layout follows Material Design's responsive guidelines.
+Separate CSS files, based on the [Material Design Layout Foundation](https://m3.material.io/foundations/layout/layout-overview), provide foundational styles that are not tied to a single component. The **Layout** foundation includes styles for the **window frame**, **rail region** and **panes** that adapt to the available screen space, ensuring your layout follows Material Design's adaptive design guidelines. The **Field** foundation arranges form fields in a grid with the standard Material vertical rhythm, optionally led by an icon column.
 
+- [x] [Field](foundations/field/README.md)
 - [x] [Layout](foundations/layout/README.md)
 
 ## Available components ✅
@@ -105,13 +177,17 @@ The library currently consists of the following components:
 - [x] [Button](components/button/README.md)
 - [x] [Card](components/card/README.md)
 - [x] [Checkbox](components/checkbox/README.md)
+- [x] [Chip](components/chip/README.md)
 - [x] [Date picker](components/datepicker/README.md)
+- [x] [Date range picker](components/datepicker/README.md)
 - [x] [Dialog](components/dialog/README.md)
 - [x] [Divider](components/divider/README.md)
 - [x] [Icon button](components/iconbutton/README.md)
 - [x] [List](components/list/README.md)
 - [x] [Menu](components/menu/README.md)
+- [x] [Navigation bar](components/navigationbar/README.md)
 - [x] [Navigation rail](components/navigationrail/README.md)
+- [x] [Progress indicator](components/progressindicator/README.md)
 - [x] [Radio button](components/radio/README.md)
 - [x] [Select](components/select/README.md)
 - [x] [Shapes](components/shapes/README.md)
@@ -125,6 +201,18 @@ The library currently consists of the following components:
 
 ## Change Log ↪️
 
+### 9.0.0 (20.07.2026)
+- **BREAKING**: Renamed all CSS custom properties from --md-sys- to --md-comp-.
+- **BREAKING**: Renamed the layout class `micl-body` and its `micl-body--*` modifiers to `micl-panes`/`micl-panes--*`, aligning with the M3 Expressive layout terminology.
+- **BREAKING**: Per-component CSS files no longer embed the shared foundation styles; load `dist/base.css` once before them. The full `micl.css` is unaffected.
+- **Chip**: New component.
+- **Progress indicator**: New component.
+- **Navigation bar**: New component.
+- **Navigation rail**: Support for adaptive behaviour.
+- **Date Range picker**: Select two dates in the Date picker to return a date range.
+- **Field**: The `micl-grid-field` and `micl-grid-iconfield` classes are now the 'Field' layout foundation with its own stylesheet (`dist/field.css`).
+- **Layout**: The window now reserves the safety regions (`env(safe-area-inset-*)`) around the content, and sticky app bars and navigation rails stay below the top safety region.
+
 ### 8.1.0 (24.06.2026)
 - **Shapes**: The Material shape library supported as the 'Shapes' component.
 
@@ -148,7 +236,7 @@ The library currently consists of the following components:
 - **Time picker**: New component.
 
 ### 4.0.0 (27.10.2025)
-- **BREAKING**: Moved layout.scss to sub-folder.
+- **BREAKING**: Moved layout.scss to subfolder.
 - **Alert**: New component.
 - **Stepper**: New component.
 

package/components/README.md

@@ -11,4 +11,4 @@ Each component is self-contained in a separate folder, making it easy to find wh
 
 Most components are standalone, but some are built on top of others. For example, the [Menu component](./menu/README.md) extends the [List component](./list/README.md), so it requires the styles and functionality of both. Always check the documentation for each component to see which dependencies you need to import. This ensures everything works as expected.
 
-A [separate CSS file](../foundations/layout/README.md), based on the [Material Design Layout Foundation](https://m3.material.io/foundations/layout/understanding-layout/overview), provides styles for an adaptive layout. It includes styles for the **window frame**, **body region** and **panes** that adjust to the available screen space, ensuring your layout follows Material Design's responsive guidelines.
+A [separate CSS file](../foundations/layout/README.md), based on the [Material Design Layout Foundation](https://m3.material.io/foundations/layout/layout-overview), provides styles for an adaptive layout. It includes styles for the **window frame**, **rail region** and **panes** that adapt to the available screen space, ensuring your layout follows Material Design's adaptive design guidelines.

package/components/accordion/README.md

@@ -113,17 +113,17 @@ Since the Accordion is based on the List component, you can use the same utility
 ## Keyboard
 Each `<summary>` is a tab stop in document order — `Tab` and `Shift+Tab` move focus through the accordion headers. While focus is on a header, `Enter` or `Space` toggles the panel open or closed. As an optional enhancement, `ArrowDown` and `ArrowUp` move focus to the next or previous header in the same group; focus wraps around at the ends.
 
-## Customizations
-You can customize the appearance of the Accordion component by overriding its own global CSS variables and those from the List component. These variables are declared on the `:root` pseudo-class and can be changed on any appropriate parent element to affect its child accordions.
+## Theming
+You can customize the appearance of the Accordion component by overriding its own CSS custom properties and those of the [List](../list/README.md) component. Set them on any appropriate parent element to affect its child accordions.
 
-| Variable name | Default Value | Description |
-| ------------- | ------------- | ----------- |
-| --md-sys-accordion-item-space | 0px | The space between an opened accordion item and its next neighbour. |
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-accordion-item-space` | The space between an opened accordion item and its next neighbour. | `0px` |
 
 **Example: Changing the margin between an opened item and the next**
 
 ```HTML
-<div class="micl-list" style="--md-sys-accordion-item-space:4px">
+<div class="micl-list" style="--md-comp-accordion-item-space:4px">
   <details>
     ...
   </details>

package/components/alert/README.md

@@ -56,9 +56,9 @@ To change the color, add one of the following modifier classes to the main `<div
 
 | Class name | Description |
 | ---------- | ----------- |
-| micl-alert--primary | Uses the main color scheme of your application |
-| micl-alert--secondary | Uses a color scheme that is less prominent than the main one |
-| micl-alert--tertiary | Uses a color scheme that provides contrasting accents |
+| `micl-alert--primary` | Uses the main color scheme of your application |
+| `micl-alert--secondary` | Uses a color scheme that is less prominent than the main one |
+| `micl-alert--tertiary` | Uses a color scheme that provides contrasting accents |
 
 ### Alert Content Structure
 The Alert component is built with a few key structural elements.
@@ -69,18 +69,18 @@ The Alert component is built with a few key structural elements.
 
 - `micl-alert__supporting-text` (optional): Used for a short description or supplementary information. It is displayed in a smaller font.
 
-## Customizations
-You can customize the appearance of the Alert component by overriding its global CSS variables. These variables are declared on the `:root` pseudo-class and can be changed on any appropriate parent element to affect its child alert.
+## Theming
+Each alert can be themed with CSS custom properties. Set them on any appropriate parent element to affect its child alerts.
 
-| Variable name | Default Value | Description |
-| ------------- | ------------- | ----------- |
-| --md-sys-alert-padding | 16px | The inner padding between the alert's edge and its content |
-| --md-sys-alert-space | 16px | The spacing between the optional icon and the text container |
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-alert-padding` | The inner padding between the alert's edge and its content | `16px` |
+| `--md-comp-alert-space` | The spacing between the optional icon and the text container | `16px` |
 
 **Example: Changing the padding**
 
 ```HTML
-<div style="--md-sys-alert-padding:24px">
+<div style="--md-comp-alert-padding:24px">
   <div class="micl-alert-filled" role="alert">
     ...
   </div>

package/components/alert/index.scss

@@ -19,7 +19,6 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-@use '../../foundations';
 @use '../../styles/shape';
 @use '../../styles/typography';
 
@@ -28,27 +27,19 @@
 @include typography.scale('title-medium');
 @include typography.scale('body-medium');
 
-:root {
-    --md-sys-alert-padding: 16px;
-    --md-sys-alert-space: 16px;
-}
-
-.micl-alert-filled,
-.micl-alert-tonal,
-.micl-alert-outlined {
-    --md-sys-alert-background-color: inherit;
-    --md-sys-alert-color: inherit;
+$alerts: ':is(.micl-alert-filled, .micl-alert-tonal, .micl-alert-outlined)';
 
+#{$alerts} {
     box-sizing: border-box;
     display: flex;
     inline-size: 100%;
-    padding: var(--md-sys-alert-padding, 16px);
-    column-gap: var(--md-sys-alert-space, 8px);
+    padding: var(--md-comp-alert-padding, 16px);
+    column-gap: var(--md-comp-alert-space, 16px);
     border: none;
     outline: none;
     border-radius: var(--md-sys-shape-corner-small, 8px);
-    background-color: var(--md-sys-alert-background-color);
-    color: var(--md-sys-alert-color);
+    background-color: var(--_background-color, transparent);
+    color: var(--_color, inherit);
 
     .micl-alert__icon {
         block-size: var(--md-sys-icon-size, 24px);
@@ -60,7 +51,7 @@
         flex-direction: column;
         row-gap: 8px;
 
-        h1, h2, h3, h4, h5, h6, .micl-heading {
+        :is(h1, h2, h3, h4, h5, h6, .micl-heading) {
             @include typography.title-medium;
 
             margin: 0;
@@ -74,53 +65,37 @@
 }
 
 .micl-alert-filled {
-    --md-sys-alert-background-color: var(--md-sys-color-error);
-    --md-sys-alert-color: var(--md-sys-color-on-error);
+    --_background-color: var(--md-sys-color-error);
+    --_color: var(--md-sys-color-on-error);
 
-    &.micl-alert--primary {
-        --md-sys-alert-background-color: var(--md-sys-color-primary);
-        --md-sys-alert-color: var(--md-sys-color-on-primary);
-    }
-    &.micl-alert--secondary {
-        --md-sys-alert-background-color: var(--md-sys-color-secondary);
-        --md-sys-alert-color: var(--md-sys-color-on-secondary);
-    }
-    &.micl-alert--tertiary {
-        --md-sys-alert-background-color: var(--md-sys-color-tertiary);
-        --md-sys-alert-color: var(--md-sys-color-on-tertiary);
+    @each $scheme in primary, secondary, tertiary {
+        &.micl-alert--#{$scheme} {
+            --_background-color: var(--md-sys-color-#{$scheme});
+            --_color: var(--md-sys-color-on-#{$scheme});
+        }
     }
 }
 
 .micl-alert-tonal {
-    --md-sys-alert-background-color: var(--md-sys-color-error-container);
-    --md-sys-alert-color: var(--md-sys-color-on-error-container);
+    --_background-color: var(--md-sys-color-error-container);
+    --_color: var(--md-sys-color-on-error-container);
 
-    &.micl-alert--primary {
-        --md-sys-alert-background-color: var(--md-sys-color-primary-container);
-        --md-sys-alert-color: var(--md-sys-color-on-primary-container);
-    }
-    &.micl-alert--secondary {
-        --md-sys-alert-background-color: var(--md-sys-color-secondary-container);
-        --md-sys-alert-color: var(--md-sys-color-on-secondary-container);
-    }
-    &.micl-alert--tertiary {
-        --md-sys-alert-background-color: var(--md-sys-color-tertiary-container);
-        --md-sys-alert-color: var(--md-sys-color-on-tertiary-container);
+    @each $scheme in primary, secondary, tertiary {
+        &.micl-alert--#{$scheme} {
+            --_background-color: var(--md-sys-color-#{$scheme}-container);
+            --_color: var(--md-sys-color-on-#{$scheme}-container);
+        }
     }
 }
 
 .micl-alert-outlined {
-    --md-sys-alert-color: var(--md-sys-color-error);
+    --_color: var(--md-sys-color-error);
 
-    border: 1px solid var(--md-sys-alert-color);
+    border: 1px solid var(--_color);
 
-    &.micl-alert--primary {
-        --md-sys-alert-color: var(--md-sys-color-primary);
-    }
-    &.micl-alert--secondary {
-        --md-sys-alert-color: var(--md-sys-color-secondary);
-    }
-    &.micl-alert--tertiary {
-        --md-sys-alert-color: var(--md-sys-color-tertiary);
+    @each $scheme in primary, secondary, tertiary {
+        &.micl-alert--#{$scheme} {
+            --_color: var(--md-sys-color-#{$scheme});
+        }
     }
 }

package/components/appbar/README.md

@@ -19,6 +19,7 @@ To add a basic (small) app bar, use the `<header>` element with the `micl-appbar
 Import the app bar styles into your project:
 
 ```CSS
+@use "material-inspired-component-library/dist/iconbutton";
 @use "material-inspired-component-library/dist/appbar";
 ```
 
@@ -60,7 +61,7 @@ Use the `micl-appbar__leading` (or: `micl-appbar__leading-icon`) class for an el
 
 ```HTML
 <header class="micl-appbar">
-  <a href="index.html" class="micl-appbar__leading-icon micl-link micl-iconbutton-standard-m" aria-label="Home">
+  <a href="index.html" class="micl-appbar__leading-icon micl-iconbutton-standard-m" aria-label="Home">
     <span class="material-symbols-outlined" aria-hidden="true">home</span>
   </a>
   <div class="micl-appbar__headline">
@@ -86,14 +87,26 @@ Use the `micl-appbar__trailing` (or: `micl-appbar__trailing-icon`) class for ele
 ### Sticky app bar
 The app bar is 'glued' to the top of the page when one of the following conditions is met:
 
-- The [body region](../../foundations/layout/README.md) contains only one pane.
-- The body region contains two or more panes and the page has a compact size.
-- The body region contains two or more panes, has the `micl-body--stacked-to-expanded` class and the page has a compact or medium size.
-- The body region contains two or more panes, has the `micl-body--stacked-to-large` class and the page has a compact, medium or expanded size.
-- The body region contains two or more panes, has the `micl-body--stacked-to-extralarge` class and the page has a compact, medium, expanded or large size.
+- The [pane area](../../foundations/layout/README.md) contains only one pane.
+- The pane area contains two or more panes and the window is at the compact breakpoint.
+- The pane area contains two or more panes, has the `micl-panes--stacked-to-expanded` class and the window is at the compact or medium breakpoint.
+- The pane area contains two or more panes, has the `micl-panes--stacked-to-large` class and the window is at the compact, medium or expanded breakpoint.
+- The pane area contains two or more panes, has the `micl-panes--stacked-to-extralarge` class and the window is at the compact, medium, expanded or large breakpoint.
 - The app bar has the `micl-appbar--sticky` class.
 
 Adding the `micl-appbar--not-sticky` class to the app bar will prohibit gluing the app bar to the top of the page.
 
+## Theming
+Each app bar 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 app bars.
+
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-app-bar-container-color` | The background color of the app bar | inherited from the page |
+| `--md-comp-app-bar-on-scroll-container-color` | The background color while the page is scrolled | `--md-sys-color-surface-container` |
+| `--md-comp-app-bar-title-color` | The text color of the headline | `--md-sys-color-on-surface` |
+| `--md-comp-app-bar-subtitle-color` | The text color of the subtitle | `--md-sys-color-on-surface-variant` |
+| `--md-comp-app-bar-leading-icon-color` | The color of the leading icon | `--md-sys-color-on-surface` |
+| `--md-comp-app-bar-trailing-icon-color` | The color of the trailing icons | `--md-sys-color-on-surface-variant` |
+
 ## Compatibility
 This component uses the `animation-timeline` CSS property for the scroll-effect, which may not be supported in your browser. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline#browser_compatibility) for details.