material-inspired-component-library 3.0.2 → 4.0.0

package/README.md

@@ -32,10 +32,12 @@ To import the styles for a single component (e.g., the [Card component](componen
 ```SCSS
 @use "material-inspired-component-library/dist/card";
 ```
-To import all component styles:
+
+To import all MICL styles:
 ```SCSS
 @use "material-inspired-component-library/styles";
 ```
+
 Remember to import your [theme file](themes/README.md) as well:
 ```SCSS
 @use "path/to/mytheme";
@@ -79,11 +81,12 @@ This will initialize all MICL components, including those that will be added to
 ## 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.
 
-- [x] [Layout](layout/README.md)
+- [x] [Layout](foundations/layout/README.md)
 
 ## Available components ✅
 The library currently consists of the following components:
 - [x] [Accordion](components/accordion/README.md)
+- [x] [Alert](components/alert/README.md)
 - [x] [App Bar](components/appbar/README.md)
 - [x] [Badge](components/badge/README.md)
 - [x] [Bottom sheet](components/bottomsheet/README.md)
@@ -100,39 +103,38 @@ The library currently consists of the following components:
 - [x] [Select](components/select/README.md)
 - [x] [Side sheet](components/sidesheet/README.md)
 - [x] [Slider](components/slider/README.md)
+- [x] [Stepper](components/stepper/README.md)
 - [x] [Switch](components/switch/README.md)
 - [x] [Text field](components/textfield/README.md)
 
 ## Change Log ↪️
 
-### 3.0.0 (24.09.2025)
-**Features**
+### 4.0.0 (27.10.2025)
+- **BREAKING**: Moved layout.scss til sub-folder.
+- **Alert**: New component.
+- **Stepper**: New component.
 
+### 3.1.0 (19.10.2025)
+- **Checkbox**: Refactoring + added support for checkbox groups.
+
+### 3.0.0 (24.09.2025)
+- **BREAKING:** Use `<nav>` instead of `<div>` for Navigation rail.
 - **App Bar**: New component.
 - **Layout**: Support for adaptive layout.
-- Improved handling of target area for small buttons.
-- **BREAKING:** Use `<nav>` instead of `<div>` for Navigation rail.
+- **Buttons**: Improved handling of target area for small buttons.
 
 ### 2.0.0 (04.09.2025)
-**Features**
-
 - **Navigation rail**: New component.
 - **Badge**: New component.
 - **Ripple**: Now uses custom CSS properties.
 
 ### 1.3.0 (23.08.2025)
-**Features**
-
 - **Menu**: Added support for submenus.
 - **Ripple**: The ripple-effect does not use a pseudo-element anymore.
 - **State layer**: Rewrite for simpler styling.
 
 ### 1.2.0 (17.08.2025)
-**Features**
-
 - **List**: Added support for switches inside list items.
 
 ### 1.1.0 (12.08.2025)
-**Features**
-
 - **Text field**: Added support for multi-line text fields.

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](../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/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.

package/components/accordion/README.md

@@ -1,5 +1,5 @@
 # Accordion
-This component implements the the [Material Design 3 Expressive Expandable Lists](https://m3.material.io/components/lists/overview) design. Accordions are vertically stacked lists that allow you to show and hide sections of content.
+This component implements the [Material Design 3 Expressive Expandable Lists](https://m3.material.io/components/lists/overview) design. Accordions are vertically stacked lists that allow you to show and hide sections of content.
 
 ## Basic Usage
 
@@ -34,6 +34,11 @@ Import the list styles into your project:
 @use "material-inspired-component-library/dist/list";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### JavaScript
 This component requires JavaScript to support keyboard navigation:
 
@@ -43,8 +48,8 @@ import micl from "material-inspired-component-library/dist/micl";
 
 This will initialize any List component, including those that will be added to the DOM later on.
 
-### Demo
-A live example of the [Accordion component](https://henkpb.github.io/micl/accordion.html) is available for you to interact with.
+### Live Demo
+A live example of the [Accordion component](https://henkpb.github.io/micl/accordion.html) is available to interact with.
 
 ## Variants
 To ensure that only one accordion item within a group can be open at a time, add a matching `name` attribute to all the `<details>` elements you want to group together.

package/components/alert/README.md

@@ -0,0 +1,76 @@
+# Alert
+This component is an Alert component inspired by [Material Design 3 Expressive](https://m3.material.io/components). Alerts are used to inform the user of important changes in a prominent way.
+
+## Basic Usage
+
+### HTML
+To add a basic alert, use a `<div>` element with one of the primary alert style classes: `micl-alert-filled`, `micl-alert-tonal` or `micl-alert-outlined`.
+
+```HTML
+<div class="micl-alert-tonal" role="alert">
+  <span class="micl-alert__icon material-symbols-outlined">error</span>
+  <div class="micl-alert__text">
+    <h4>An error has occurred</h4>
+    <span class="micl-alert__supporting-text">Keyboard not responding. Press any key to continue.</span>
+  </div>
+</div>
+```
+
+### CSS
+Import the alert styles into your project:
+
+```CSS
+@use "material-inspired-component-library/dist/alert";
+```
+
+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.
+
+### Live Demo
+A live example of the [Alert component](https://henkpb.github.io/micl/alert.html) is available to interact with.
+
+## Variants
+Alerts are available in **three distinct styles**:
+
+- `micl-alert-filled`: An alert with a solid background color that stands out prominently.
+  ```HTML
+  <div class="micl-alert-filled" role="alert">
+    ...
+  </div>
+  ```
+
+- `micl-alert-tonal`: An alert with a lighter background color. This is the style shown in the Basic Usage section.
+
+- `micl-alert-outlined`: An alert with a clear border, typically used for less prominent content.
+
+### Alert Content Structure
+The alert in the Basic Usage section shows all available structural elements:
+
+- `micl-alert__icon`: An optional icon that appears before the alert text.
+
+- `micl-alert__text`: A container for the main alert heading (`<h1>`-`<h6>`) and the supporting text.
+
+- `micl-alert__supporting-text`: Intended for a short description or supplementary information, and 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.
+
+| 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 | Sets the spacing between the icon and the text |
+
+**Example: Changing the padding**
+
+```HTML
+<div style="--md-sys-alert-padding:24px">
+  <div class="micl-alert-filled" role="alert">
+    ...
+  </div>
+</div>
+```

package/components/alert/index.scss

@@ -0,0 +1,121 @@
+//
+// Copyright © 2025 Hermana AS
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+@use '../../foundations/layout';
+@use '../../styles/shapes';
+@use '../../styles/typography';
+
+: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;
+
+    box-sizing: border-box;
+    display: flex;
+    inline-size: 100%;
+    padding: var(--md-sys-alert-padding, 16px);
+    column-gap: var(--md-sys-alert-space, 8px);
+    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);
+
+    .micl-alert__icon {
+        block-size: var(--md-sys-layout-icon-size, 24px);
+        inline-size: var(--md-sys-layout-icon-size, 24px);
+        font-size: var(--md-sys-layout-icon-size, 24px);
+    }
+    .micl-alert__text {
+        display: flex;
+        flex-direction: column;
+        row-gap: 8px;
+
+        h1, h2, h3, h4, h5, h6, .micl-heading {
+            @include typography.title-medium;
+
+            margin: 0;
+        }
+        .micl-alert__supporting-text {
+            @include typography.body-medium;
+
+            margin: 0;
+        }
+    }
+}
+
+.micl-alert-filled {
+    --md-sys-alert-background-color: var(--md-sys-color-error);
+    --md-sys-alert-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);
+    }
+}
+
+.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);
+
+    &.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);
+    }
+}
+
+.micl-alert-outlined {
+    --md-sys-alert-color: var(--md-sys-color-error);
+
+    border: 1px solid var(--md-sys-alert-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);
+    }
+}

package/components/appbar/README.md

@@ -1,5 +1,5 @@
 # App Bar
-This component implements the the [Material Design 3 Expressive App Bar](https://m3.material.io/components/app-bars/overview) design. The app bar serves as the top container for a page, displaying the page title, primary actions, and navigation options.
+This component implements the [Material Design 3 Expressive App Bar](https://m3.material.io/components/app-bars/overview) design. The app bar serves as the top container for a page, displaying the page title, primary actions, and navigation options.
 
 ## Basic Usage
 
@@ -22,11 +22,16 @@ Import the app bar styles into your project:
 @use "material-inspired-component-library/dist/appbar";
 ```
 
+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.
 
-### Demo
-A live example of the [App Bar component](https://henkpb.github.io/micl/index.html) is available for you to interact with.
+### Live Demo
+A live example of the [App Bar component](https://henkpb.github.io/micl/index.html) is available to interact with.
 
 ## Variants
 The app bar component supports three sizes: **small**, **medium** (flexible), and **large** (flexible). Use a modifier class to specify a size other than the default small size.
@@ -81,7 +86,7 @@ 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](../../layout/README.md) contains only one pane.
+- 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.

package/components/appbar/index.scss

@@ -19,7 +19,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-@use '../../layout';
+@use '../../foundations/layout';
 @use '../../styles/elevation';
 @use '../../styles/shapes';
 @use '../../styles/statelayer';

package/components/badge/README.md

@@ -1,5 +1,5 @@
 # Badge
-This component implements the the [Material Design 3 Expressive Badge](https://m3.material.io/components/badges/overview) design. Badges are small status indicators that can show a count or simply signal new information.
+This component implements the [Material Design 3 Expressive Badge](https://m3.material.io/components/badges/overview) design. Badges are small status indicators that can show a count or simply signal new information.
 
 ## Basic Usage
 
@@ -19,11 +19,16 @@ Import the badge styles into your project:
 @use "material-inspired-component-library/dist/badge";
 ```
 
+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.
 
-### Demo
-A live example of the [Badge component](https://henkpb.github.io/micl/index.html) is available for you to interact with.
+### Live Demo
+A live example of the [Badge component](https://henkpb.github.io/micl/index.html) is available to interact with.
 
 ## Anchoring
 Badges are typically placed on top of other elements, like icons. To anchor a badge to a specific element, use CSS `anchor positioning`.

package/components/badge/index.scss

@@ -19,6 +19,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+@use '../../foundations/layout';
 @use '../../styles/typography';
 
 :root {

package/components/bottomsheet/README.md

@@ -1,5 +1,5 @@
 # Bottom sheet
-This component implements the the [Material Design 3 Expressive Bottom sheet](https://m3.material.io/components/bottom-sheets/overview) design. Bottom sheets show secondary content anchored to the bottom of the screen.
+This component implements the [Material Design 3 Expressive Bottom sheet](https://m3.material.io/components/bottom-sheets/overview) design. Bottom sheets show secondary content anchored to the bottom of the screen.
 
 ## Basic Usage
 
@@ -21,6 +21,11 @@ Import the bottom sheet styles into your project:
 @use "material-inspired-component-library/dist/bottomsheet";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### JavaScript
 This component requires JavaScript to support **resizable** bottom sheets. The library will automatically initialize new components as they're added to the DOM.
 
@@ -28,8 +33,8 @@ This component requires JavaScript to support **resizable** bottom sheets. The l
 import micl from "material-inspired-component-library/dist/micl";
 ```
 
-### Demo
-A live example of the [Bottom sheet component](https://henkpb.github.io/micl/bottomsheet.html) is available for you to interact with.
+### Live Demo
+A live example of the [Bottom sheet component](https://henkpb.github.io/micl/bottomsheet.html) is available to interact with.
 
 ## Variants
 Setting the `popover` attribute to `manual` lets a bottom sheet co-exist and be interactive with the rest of the page.

package/components/button/README.md

@@ -1,5 +1,5 @@
 # Button
-This component implements the the [Material Design 3 Expressive Button](https://m3.material.io/components/buttons/overview) design. Buttons are interactive elements that enable users to trigger actions or navigate.
+This component implements the [Material Design 3 Expressive Button](https://m3.material.io/components/buttons/overview) design. Buttons are interactive elements that enable users to trigger actions or navigate.
 
 ## Basic Usage
 
@@ -17,6 +17,11 @@ Import the button styles into your project:
 @use "material-inspired-component-library/dist/button";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### JavaScript
 This component requires JavaScript for interactive features like the **toggle logic**:
 
@@ -26,8 +31,8 @@ import micl from "material-inspired-component-library/dist/micl";
 
 This will initialize any Button component, including those that will be added to the DOM later on.
 
-### Demo
-A live example of the [Button component](https://henkpb.github.io/micl/button.html) is available for you to interact with.
+### Live Demo
+A live example of the [Button component](https://henkpb.github.io/micl/button.html) is available to interact with.
 
 ## Variants
 Buttons come in **five sizes**: extra small (`xs`), small (`s`), medium (`m`), large (`l`), and extra large (`xl`). To specify a size, append the appropriate postfix to the button's style class:

package/components/button/index.scss

@@ -19,6 +19,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+@use '../../foundations/layout';
 @use '../../styles/elevation';
 @use '../../styles/motion';
 @use '../../styles/shapes';
@@ -70,6 +71,7 @@ button.micl-button-outlined-xl {
         linear-gradient(rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)));
     background-repeat: no-repeat;
     background-size: 10000%, 100%;
+    -webkit-tap-highlight-color: transparent;
     cursor: pointer;
     transition:
         border-radius var(--md-sys-button-motion-duration) var(--md-sys-button-motion-effects),
@@ -112,6 +114,7 @@ button.micl-button-outlined-xs {
     position: relative;
     min-inline-size: var(--micl-width);
     block-size: var(--micl-height);
+    min-block-size: var(--micl-height);
     column-gap: 8px;
     padding-inline: 12px;
 
@@ -157,6 +160,7 @@ button.micl-button-outlined-s {
 
     min-inline-size: var(--micl-width);
     block-size: var(--micl-height);
+    min-block-size: var(--micl-height);
     column-gap: 8px;
     padding-inline: 16px;
 
@@ -202,6 +206,7 @@ button.micl-button-outlined-m {
 
     min-inline-size: var(--micl-width);
     block-size: var(--micl-height);
+    min-block-size: var(--micl-height);
     column-gap: 8px;
     padding-inline: 24px;
 
@@ -238,6 +243,7 @@ button.micl-button-outlined-l {
 
     min-inline-size: var(--micl-width);
     block-size: var(--micl-height);
+    min-block-size: var(--micl-height);
     column-gap: 12px;
     padding-inline: 48px;
 
@@ -274,6 +280,7 @@ button.micl-button-outlined-xl {
 
     min-inline-size: var(--micl-width);
     block-size: var(--micl-height);
+    min-block-size: var(--micl-height);
     column-gap: 16px;
     padding-inline: 64px;
 

package/components/card/README.md

@@ -1,5 +1,5 @@
 # Card
-This component implements the the [Material Design 3 Expressive Card](https://m3.material.io/components/cards/overview) design. Cards display content and actions about a single subject.
+This component implements the [Material Design 3 Expressive Card](https://m3.material.io/components/cards/overview) design. Cards display content and actions about a single subject.
 
 ## Basic Usage
 
@@ -19,14 +19,19 @@ Import the card styles into your project:
 @use "material-inspired-component-library/dist/card";
 ```
 
+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.
 
-### Demo
-A live example of the [Card component](https://henkpb.github.io/micl/card.html) is available for you to interact with.
+### Live Demo
+A live example of the [Card component](https://henkpb.github.io/micl/card.html) is available to interact with.
 
 ## Variants
-Cards come in **three distinct styles**:
+Cards are available in **three distinct styles**:
 
 - `micl-card-elevated`: A card with a subtle shadow, visually lifted from the background. This is the style shown in Basic Usage.
 
@@ -41,6 +46,7 @@ Cards come in **three distinct styles**:
 
 ### Card Content Structure
 While the card container is the only required element, the Card component provides several optional utility classes to help structure your card's content:
+
 ```HTML
 <div class="micl-card-outlined" tabindex="0">
   <img alt="Descriptive image text" class="micl-card__image" src="/path/to/your/image.jpg">

package/components/card/index.scss

@@ -289,5 +289,5 @@
     padding-block: var(--md-sys-card-content-padding-block) 0;
     padding-inline: var(--md-sys-card-padding-inline);
     background-color: inherit;
-    overflow: hidden;
+    overflow: clip visible;
 }

package/components/checkbox/README.md

@@ -1,5 +1,5 @@
 # Checkbox
-This component implements the the [Material Design 3 Expressive Checkbox](https://m3.material.io/components/checkbox/overview) design.
+This component implements the [Material Design 3 Expressive Checkbox](https://m3.material.io/components/checkbox/overview) design. A checkbox allows a user to select one or more options from a number of choices.
 
 ## Basic Usage
 
@@ -7,7 +7,7 @@ This component implements the the [Material Design 3 Expressive Checkbox](https:
 To add a basic checkbox, use the `<input type="checkbox">` element with the `micl-checkbox` class, paired with a `<label>` element:
 
 ```HTML
-<input type="checkbox" id="mycheckbox" class="micl-checkbox" value="foo">
+<input type="checkbox" id="mycheckbox" class="micl-checkbox">
 <label for="mycheckbox">Bar</label>
 ```
 
@@ -18,17 +18,20 @@ Import the checkbox styles into your project:
 @use "material-inspired-component-library/dist/checkbox";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### JavaScript
-This component requires JavaScript to support checking and unchecking using a keyboard:
+This component requires JavaScript to support checkbox groups:
 
-```JavaScript
-import micl from "material-inspired-component-library/dist/micl";
-```
+`import micl from "material-inspired-component-library/dist/micl";`
 
-This will initialize any Checkbox component, including those that will be added to the DOM later on.
+This will initialize any checkbox group, including those that will be added to the DOM later on.
 
-### Demo
-A live example of the [Checkbox component](https://henkpb.github.io/micl/checkbox.html) is available for you to interact with.
+### Live Demo
+A live example of the [Checkbox component](https://henkpb.github.io/micl/checkbox.html) is available to interact with.
 
 ## Variants
 Adding the `micl-checkbox--error` CSS class to the `<input>` element will create an error-checkbox as specified by the Material Design 3 specification.
@@ -37,20 +40,60 @@ A checkbox can be disabled by adding the `disabled` attribute to the `<input>` e
 
 The Checkbox component respects the `dir` global attribute, automatically adjusting its layout for right-to-left (RTL) languages when `dir="rtl"` is applied to an ancestor element.
 
+The component applies `cursor: pointer` and the color role **on surface** to the `<label>` element immediately preceding or following an `<input type="checkbox">` with the `micl-checkbox` class. You are encouraged to customize these CSS settings to match your design system.
+
+## Checkbox group
+You can establish a parent-child relationship among checkboxes. To do this, wrap the entire set of related checkboxes in an element using the `micl-checkbox-group` class. The designated parent checkbox must also include the `micl-checkbox__parent` class.
+
+```HTML
+<div class="micl-checkbox-group">
+  <input type="checkbox" id="cb0" class="micl-checkbox micl-checkbox__parent" value="c0">
+  <label for="cb0">Choices</label>
+  <input type="checkbox" id="cb1" class="micl-checkbox" value="c1">
+  <label for="cb1">First Choice</label>
+  <input type="checkbox" id="cb2" class="micl-checkbox" checked value="c2">
+  <label for="cb2">Second Choice</label>
+  ...
+</div>
+```
+
+To visually improve the layout, such as by indenting child checkboxes, use wrapper elements and utility classes:
+
+```HTML
+<div class="micl-checkbox-group">
+  <div class="micl-flex--vcenter">
+    <input type="checkbox" id="cb0" class="micl-checkbox micl-checkbox__parent" value="c0">
+    <label for="cb0">Choices</label>
+  </div>
+  <div style="padding-inline-start:16px">
+    <div class="micl-flex--vcenter">
+      <input type="checkbox" id="cb1" class="micl-checkbox" value="c1">
+      <label for="cb1">First Choice</label>
+    </div>
+    <div class="micl-flex--vcenter">
+      <input type="checkbox" id="cb2" class="micl-checkbox" checked value="c2">
+      <label for="cb2">Second Choice</label>
+    </div>
+    ...
+  </div>
+</div>
+```
+
+Note that checkbox groups support **nesting**, allowing a `micl-checkbox-group` to contain other `micl-checkbox-group` elements for multi-level hierarchies.
+
 ## Customizations
 You can customize the appearance of the Checkbox 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 checkboxes.
 
 | Variable name | Default Value | Description |
 | ------------- | ------------- | ----------- |
 | --md-sys-checkbox-border-width | 2px | Controls the thickness of the checkbox's border |
+| --md-sys-checkbox-check-thickness | 2px | The thickness of the checkmark |
 | --md-sys-checkbox-container-size | 18px | Defines the size of the checkbox itself |
-| --md-sys-checkbox-selected-icon | \2A3D | The character used as the checkmark for the checkbox |
-| --md-sys-checkbox-state-layer-radius | 20px | Sets the radius of the interactive area that indicates the component's current state (e.g., hover, focus, press) |
 
-**Example: Changing the size of the interactive area**
+**Example: Changing the border width of a checkbox**
 
 ```HTML
-<div style="--md-sys-checkbox-state-layer-radius:24px">
+<div style="--md-sys-checkbox-border-width:1px">
   <input type="checkbox" id="mycheckbox" class="micl-checkbox">
   <label for="mycheckbox">Checkbox</label>
 </div>