material-inspired-component-library 9.1.0 → 9.1.2

package/components/card/README.md

@@ -30,25 +30,11 @@ No custom JavaScript is required for the core functionality of this component.
 ### Live Demo
 A live example of the [Card component](https://henkpb.github.io/micl/card.html) is available to interact with.
 
-## Variants
-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.
-
-- `micl-card-filled`: A card with a solid background color, blending more seamlessly with its surroundings.
-  ```HTML
-  <div class="micl-card-filled">
-    <p>This is a filled card.</p>
-  </div>
-  ```
-
-- `micl-card-outlined`: A card with a clear border, often used for less prominent content or to indicate interactivity.
-
-### Card Content Structure
+## Anatomy
 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">
+<div class="micl-card-outlined">
   <img alt="Descriptive image text" class="micl-card__image" src="/path/to/your/image.jpg">
 
   <div class="micl-card__headline-m">
@@ -69,9 +55,17 @@ While the card container is the only required element, the Card component provid
   - `micl-card__headline-m` (medium) - *Used in the example above*
   - `micl-card__headline-l` (large)
 
-- `micl-card__image`: Applies styling to an `<img>` element or an element with a `background-image` style used as the primary image for the card.
+  A headline occupies a single line and is ellipsed when it does not fit. To let it run onto more lines before being ellipsed, increase the `--md-comp-card-headline-line-clamp` value:
+
+  ```HTML
+  <div class="micl-card__headline-m" style="--md-comp-card-headline-line-clamp:2">
+    <h2>A headline long enough to need a second line</h2>
+  </div>
+  ```
 
-- `micl-card__subhead`: For secondary headings, displayed with a smaller font than the main headline.
+- `micl-card__image`: Applies styling to an `<img>` element or an element with a `background-image` style used as the primary image for the card. The media carries the card's corner shape on every side, including the edges that face the card's interior.
+
+- `micl-card__subhead`: For secondary headings, displayed with a smaller font than the main headline. Like a headline it occupies a single line and is ellipsed when it does not fit; increase the `--md-comp-card-subhead-line-clamp` value to allow more lines.
 
 - `micl-card__supporting-text`: Intended for short descriptions or supplementary information, displayed with a smaller font.
 
@@ -79,8 +73,35 @@ While the card container is the only required element, the Card component provid
 
 - `micl-card__actions`: A flexible container for any action buttons.
 
+## Variants
+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.
+
+- `micl-card-filled`: A card with a solid background color, blending more seamlessly with its surroundings.
+  ```HTML
+  <div class="micl-card-filled">
+    <p>This is a filled card.</p>
+  </div>
+  ```
+
+- `micl-card-outlined`: A card with a clear border, often used for less prominent content or to indicate interactivity.
+
 ### Actionable Cards
-For cards that are themselves clickable or interactive (e.g., to navigate to another page), specify the `tabindex="0"` attribute on the card container. Non-actionable cards, which contain interactive elements like buttons or links within their content, should *not* have a tabindex on the card container itself.
+For a card that is itself clickable — the whole card navigates somewhere — use an `<a>` element with an `href` as the card container. The card then picks up the hover, focus, pressed and ripple states, and is operable with the keyboard and announced correctly by assistive technology without any extra attributes or JavaScript.
+
+```HTML
+<a class="micl-card-outlined" href="/article/42">
+  <div class="micl-card__headline-m">
+    <h2>Card headline</h2>
+  </div>
+  <p class="micl-card__supporting-text">The whole card is the link.</p>
+</a>
+```
+
+The same states are also applied to a card carrying `tabindex="0"`, which is the escape hatch for a card that acts on something other than a navigation. A `tabindex` only makes the card focusable, though — it does **not** make it operable. If you use it, you must supply the activation yourself: give the card the right `role` (usually `button`), and handle both `click` and the <kbd>Enter</kbd>/<kbd>Space</kbd> keys, or the card will be a focus stop that does nothing.
+
+Non-actionable cards, which contain interactive elements like buttons or links within their content, should be a `<div>` with neither an `href` nor a `tabindex` on the card container itself.
 
 ### Expandable Cards
 Cards can also serve as containers for expandable detail areas using the `<details>` and `<summary>` elements. In this scenario, the `<summary>` element becomes the actionable part of the card.
@@ -101,7 +122,7 @@ Cards can also serve as containers for expandable detail areas using the `<detai
 ```
 
 ### Compact Cards
-Add the `micl-card--compact` to the main `<div>` element (or, the `<summary>` element for expandable cards) to create a compact version of the card header.
+Add the `micl-card--compact` class to the main `<div>` element (or, the `<summary>` element for expandable cards) to create a compact version of the card header.
 
 ### States
 - **Disabled Cards**: To visually indicate a disabled card (e.g., non-interactive), add the `inert` attribute to the card container.
@@ -113,10 +134,15 @@ Each card can be themed with CSS custom properties that follow the Material Desi
 
 | Custom property | Meaning | Default |
 |---|---|---|
-| `--md-comp-card-margin` | Sets the spacing between adjacent cards both horizontally and vertically | `8px` |
 | `--md-comp-card-padding-inline` | Defines the amount of space between the left and right edges of a card and its content | `16px` |
 | `--md-comp-card-content-padding-block` | The amount of vertical padding reserved for the content area | `16px` |
-| `--md-comp-card-gap` | Defines the amount of vertical space between structural elements inside the card | `8px` |
+| `--md-comp-card-gap` | Defines the amount of space between structural elements inside the card, and between the buttons in a `micl-card__actions` row | `8px` |
+| `--md-comp-card-headline-line-clamp` | The number of lines a headline may run to before it is ellipsed | `1` |
+| `--md-comp-card-subhead-line-clamp` | The number of lines a subhead may run to before it is ellipsed | `1` |
+| `--md-comp-card-motion-duration` | How long the detail area of an expandable card takes to open and close, and how long a state layer takes to fade | `--md-sys-motion-expressive-default-spatial-duration` |
+| `--md-comp-card-motion-spatial` | The easing curve used while the detail area of an expandable card opens and closes | `--md-sys-motion-expressive-default-spatial` |
+
+The spacing *between* adjacent cards is not a property of the card itself — it is applied by the [Layout foundation](../../foundations/layout/README.md), which sets the gap on a `micl-pane` or `micl-pane__column` that holds cards. Set `--md-sys-card-margin` on, or above, that container.
 
 Each card style additionally supports the following CSS custom properties, as defined in the [Material Design 3 Expressive Card Specification](https://m3.material.io/components/cards/specs). The hover, focus, pressed and dragged properties only apply to actionable cards.
 
@@ -206,17 +232,19 @@ Each card style additionally supports the following CSS custom properties, as de
 | `--md-comp-outlined-card-dragged-state-layer-color` | The state layer color of the card while dragged | `--md-sys-color-on-surface` |
 | `--md-comp-outlined-card-dragged-state-layer-opacity` | The state layer opacity of the card while dragged | `--md-sys-state-dragged-state-layer-opacity` |
 
-**Example: Changing the card margins**
+**Example: Changing the spacing between cards**
+
+The gap comes from the pane that holds the cards, so set the property on the `micl-pane` (or on any of its ancestors):
 
 ```HTML
-<div style="--md-comp-card-margin:4px">
+<section class="micl-pane" style="--md-sys-card-margin:4px">
   <div class="micl-card-filled">
     <p>This is a filled card.</p>
   </div>
   <div class="micl-card-filled">
     <p>This is another filled card.</p>
   </div>
-</div>
+</section>
 ```
 
 To change the amount of rounding of a filled card's corners, you could for example add a CSS rule to your stylesheet:
@@ -228,6 +256,8 @@ To change the amount of rounding of a filled card's corners, you could for examp
 ```
 
 ## Compatibility
+To preserve its rounded corners, a card clips its internal content. Because of this, anything meant to extend past the card's edges (like a dropdown menu or tooltip) will be cut off unless it is rendered in the top layer with the `popover` attribute or a `<dialog>`, as the MICL Menu and Dialog components are.
+
 This component utilizes relative RGB color values, 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.
 
 The Card component uses the `interpolate-size` CSS property to smoothly open and close the detail area of a Details disclosure element, which might not be supported in your browser. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/interpolate-size#browser_compatibility) for details.

package/components/card/index.scss

@@ -84,7 +84,8 @@
         --_card-background-color: var(--md-comp-#{$name}-card-disabled-container-color, #{$inert-bg-default});
         --_card-elevation: var(--md-comp-#{$name}-card-disabled-container-elevation, #{$inert-elev-default});
         --_card-opacity: var(--md-comp-#{$name}-card-disabled-container-opacity, var(--md-sys-state-disabled-state-layer-opacity));
-        --_card-pointer-events: none;
+
+        pointer-events: none;
     }
 }
 
@@ -94,18 +95,23 @@
     --_card-focus-outline-offset: var(--md-comp-#{$name}-card-focus-indicator-outline-offset, var(--md-sys-state-focus-indicator-outer-offset));
 }
 
+$actionable: ':is([tabindex="0"], a[href])';
+
 @mixin card-interactive($state) {
-    &[tabindex='0']:not([inert]):#{$state},
-    &:not([tabindex='0']):not([inert]):has(> summary:#{$state}) {
+    &#{$actionable}:not([inert]):#{$state},
+    &:not(#{$actionable}):not([inert]):has(> summary:#{$state}) {
         @content;
     }
 }
 
 $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
 
+$headlines: ':is(.micl-card__headline-s, .micl-card__headline-m, .micl-card__headline-l)';
+
 #{$cards} {
-    --md-comp-card-motion-spatial: #{motion.$md-sys-motion-expressive-default-spatial};
-    --md-comp-card-motion-duration: #{motion.$md-sys-motion-expressive-default-spatial-duration};
+    --_card-motion-spatial: var(--md-comp-card-motion-spatial, #{motion.$md-sys-motion-expressive-default-spatial});
+    --_card-motion-duration: var(--md-comp-card-motion-duration, #{motion.$md-sys-motion-expressive-default-spatial-duration});
+    --_card-ripple-duration: var(--md-sys-state-ripple-duration);
 
     --_card-color: var(--md-sys-color-on-surface-variant);
 
@@ -113,25 +119,27 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
     flex-direction: column;
     block-size: fit-content;
     margin: 0;
-    outline: none;
-    overflow: hidden;
-    interpolate-size: allow-keywords;
-
+    border: var(--_card-border, none);
     border-radius: var(--_card-shape);
+    outline: none;
     background-color: var(--_card-background-color);
     box-shadow: var(--_card-elevation);
-    border: var(--_card-border, none);
+    text-decoration: none;
     opacity: var(--_card-opacity, 1);
-    pointer-events: var(--_card-pointer-events, auto);
+    color: inherit;
+    overflow: hidden;
+    interpolate-size: allow-keywords;
 
     &:not(.micl-card--compact):not(:has(>summary)) {
         row-gap: var(--md-comp-card-gap, 8px);
     }
 
-    &[tabindex='0']:not([inert]),
+    &#{$actionable}:not([inert]),
     &:not([inert]) > summary {
         --micl-ripple: 1;
 
+        --statelayer-color: var(--_card-hover-state-color);
+
         background-image:
             radial-gradient(
                 circle at var(--micl-x, center) var(--micl-y, center),
@@ -143,9 +151,10 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
         background-repeat: no-repeat;
         background-position: var(--micl-x, center) var(--micl-y, center), 0 0;
         background-size: 0%, 100%;
+        -webkit-tap-highlight-color: transparent;
         transition:
             background-size 0ms,
-            --statelayer-opacity var(--md-comp-card-motion-duration) linear;
+            --statelayer-opacity var(--_card-motion-duration) linear;
 
         &:is(:hover, :focus-visible, :active, .micl-card--dragging) {
             --_card-color: var(--md-sys-color-on-surface);
@@ -169,7 +178,7 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
             cursor: grabbing;
         }
         &.micl-rippling {
-            animation: micl-ripple calc(var(--md-sys-state-ripple-duration) * 1.722);
+            animation: micl-ripple calc(var(--_card-ripple-duration) * 1.722);
         }
 
         .micl-card__content {
@@ -184,14 +193,14 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
     @include card-interactive('focus-visible') {
         box-shadow: var(--_card-focus-elevation);
         border-color: var(--_card-focus-border-color, transparent);
-        outline: var(--_card-focus-outline-thickness, 0px) solid var(--_card-focus-outline-color, transparent);
-        outline-offset: var(--_card-focus-outline-offset, 0px);
+        outline: var(--_card-focus-outline-thickness) solid var(--_card-focus-outline-color);
+        outline-offset: var(--_card-focus-outline-offset);
     }
     @include card-interactive('active') {
         box-shadow: var(--_card-pressed-elevation);
         border-color: var(--_card-pressed-border-color, transparent);
     }
-    &[tabindex='0']:not([inert]).micl-card--dragging {
+    &#{$actionable}:not([inert]).micl-card--dragging {
         box-shadow: var(--_card-dragged-elevation);
         border-color: var(--_card-dragged-border-color, transparent);
     }
@@ -200,8 +209,8 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
         block-size: 0;
         overflow: hidden;
         transition:
-            block-size var(--md-comp-card-motion-duration) var(--md-comp-card-motion-spatial),
-            content-visibility var(--md-comp-card-motion-duration) linear allow-discrete;
+            block-size var(--_card-motion-duration) var(--_card-motion-spatial),
+            content-visibility var(--_card-motion-duration) linear allow-discrete;
     }
     &[open]::details-content {
         block-size: auto;
@@ -213,13 +222,16 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
         outline: none;
         list-style: none;
         cursor: pointer;
-        -webkit-tap-highlight-color: transparent;
 
         &:not(.micl-card--compact) {
             row-gap: var(--md-comp-card-gap, 8px);
         }
     }
 
+    @media (prefers-reduced-motion: reduce) {
+        --_card-motion-duration: 0ms;
+        --_card-ripple-duration: 0ms;
+    }
 }
 
 .micl-card-elevated {
@@ -281,6 +293,7 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
 .micl-card__image {
     display: block;
     inline-size: 100%;
+    object-fit: contain;
     background-position: center;
     background-repeat: no-repeat;
     background-size: contain;
@@ -289,12 +302,12 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
 
 #{$cards},
 #{$cards} > summary {
-    &> [class*='micl-card__headline-']:first-child {
+    &> #{$headlines}:first-child {
         padding-block-start: var(--md-comp-card-content-padding-block, 16px);
     }
 }
 
-[class*='micl-card__headline-'] {
+#{$headlines} {
     display: flex;
     align-items: center;
     column-gap: var(--md-comp-card-gap, 8px);
@@ -304,17 +317,15 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
         flex: 1 2 fit-content;
         margin: 0;
         padding-inline: var(--md-comp-card-padding-inline, 16px);
+        display: -webkit-box;
         overflow: hidden;
-        text-overflow: ellipsis;
-        white-space: nowrap;
+        -webkit-box-orient: vertical;
+        -webkit-line-clamp: var(--md-comp-card-headline-line-clamp, 1);
 
         &:has(+ button) {
             padding-inline-end: 0;
         }
     }
-    &:has(button) {
-        margin-block: 0;
-    }
 }
 
 @each $abbrev, $size in ('s': 'small', 'm': 'medium', 'l': 'large') {
@@ -325,13 +336,17 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
 
 .micl-card__subhead {
     @include typography.title-medium;
-    display: block;
-    margin: calc(-1 * var(--md-comp-card-gap, 8px)) 0 var(--md-comp-card-gap, 8px) 0;
-    padding: 0 var(--md-comp-card-padding-inline, 16px);
+    display: -webkit-box;
     overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
+    margin: 0 0 var(--md-comp-card-gap, 8px) 0;
+    padding: 0 var(--md-comp-card-padding-inline, 16px);
+    -webkit-box-orient: vertical;
+    -webkit-line-clamp: var(--md-comp-card-subhead-line-clamp, 1);
     color: var(--_card-color);
+
+    &:not(:first-child) {
+        margin-block-start: calc(-1 * var(--md-comp-card-gap, 8px));
+    }
 }
 
 .micl-card__supporting-text {
@@ -354,7 +369,7 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
     display: flex;
     flex-shrink: 0;
     flex-wrap: wrap;
-    gap: 8px;
+    gap: var(--md-comp-card-gap, 8px);
     padding-block: 0 var(--md-comp-card-content-padding-block, 16px);
     padding-inline: var(--md-comp-card-padding-inline, 16px);
 
@@ -366,24 +381,23 @@ $cards: ':is(.micl-card-elevated, .micl-card-filled, .micl-card-outlined)';
     }
 }
 
-.micl-card--compact,
-summary.micl-card--compact {
+.micl-card--compact {
     display: grid;
     grid-template-columns: 20% 1fr;
-    padding-block-end: 0;
 
     .micl-card__image {
         grid-column: 1;
         grid-row: 1 / span 4;
         block-size: 100%;
+        object-fit: cover;
         background-size: cover;
     }
-    [class*='micl-card__headline-'],
+    #{$headlines},
     .micl-card__subhead, .micl-card__supporting-text {
         grid-column: 2;
         min-inline-size: 0;
     }
-    [class*='micl-card__headline-'], .micl-card__supporting-text {
+    #{$headlines}, .micl-card__supporting-text {
         margin-block-start: var(--md-comp-card-gap, 8px);
     }
     .micl-card__subhead {
@@ -397,3 +411,8 @@ summary.micl-card--compact {
         margin-block-end: var(--md-comp-card-gap, 8px);
     }
 }
+
+summary.micl-card--compact {
+    display: grid;
+    padding-block-end: 0;
+}

package/components/checkbox/README.md

@@ -1,5 +1,5 @@
 # Checkbox
-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.
+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 set of choices.
 
 ## Basic Usage
 
@@ -11,6 +11,8 @@ To add a basic checkbox, use the `<input type="checkbox">` element with the `mic
 <label for="mycheckbox">Bar</label>
 ```
 
+**Note on labels**: The component automatically applies `cursor: pointer` and the **on surface** color role to any `<label>` immediately preceding, immediately following, or wrapping a `micl-checkbox` input. You are encouraged to customize these CSS settings to match your design system.
+
 ### CSS
 Import the checkbox styles into your project:
 
@@ -24,7 +26,7 @@ Or import all MICL styles:
 ```
 
 ### JavaScript
-This component requires JavaScript to support checkbox groups:
+This component only requires JavaScript when using checkbox groups:
 
 `import micl from "material-inspired-component-library/dist/micl";`
 
@@ -34,13 +36,28 @@ This will initialize any checkbox group, including those that will be added to t
 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.
-
 A checkbox can be disabled by adding the `disabled` attribute to the `<input>` element.
 
-The Checkbox component respects the element's computed direction, automatically adjusting its layout for right-to-left (RTL) languages — whether the `dir` attribute (including `dir="auto"`) is set on the element itself or inherited from an ancestor.
+The Checkbox component respects the element's computed direction, automatically adjusting its layout for right-to-left (RTL) languages — whether the `dir` attribute is set on the element itself or inherited from an ancestor.
+
+Adding the `micl-checkbox--error` CSS class to the `<input>` element will create an error-checkbox as specified by the Material Design 3 specification. You only need to set the class yourself when you drive the error state by hand — see [Validation](#validation) for letting the form foundation add and remove it from the checkbox's own validity.
 
-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.
+To vertically align a checkbox with its label, wrap both in an element with styling similar to the following:
+
+```CSS
+.my-valign-class {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+} 
+```
+
+```HTML
+<div class="my-valign-class">
+  <input type="checkbox" id="mycheckbox" class="micl-checkbox">
+  <label for="mycheckbox">Checkbox</label>
+</div>
+```
 
 ## 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.
@@ -59,26 +76,18 @@ You can establish a parent-child relationship among checkboxes. To do this, wrap
 
 To visually improve the layout, such as by indenting child checkboxes, use wrapper elements and utility classes:
 
-```CSS
-  .my-utility-class {
-    display: flex;
-    flex-direction: row;
-    align-items: center;
-  } 
-```
-
 ```HTML
 <div class="micl-checkbox-group">
-  <div class="my-utility-class">
+  <div class="my-valign-class">
     <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="my-utility-class">
+  <div role="group" style="padding-inline-start:16px">
+    <div class="my-valign-class">
       <input type="checkbox" id="cb1" class="micl-checkbox" value="c1">
       <label for="cb1">First Choice</label>
     </div>
-    <div class="my-utility-class">
+    <div class="my-valign-class">
       <input type="checkbox" id="cb2" class="micl-checkbox" checked value="c2">
       <label for="cb2">Second Choice</label>
     </div>
@@ -87,7 +96,66 @@ To visually improve the layout, such as by indenting child checkboxes, use wrapp
 </div>
 ```
 
-Note that checkbox groups support **nesting**, allowing a `micl-checkbox-group` to contain other `micl-checkbox-group` elements for multi-level hierarchies.
+Note that checkbox groups support **nesting**, allowing a `micl-checkbox-group` to contain other `micl-checkbox-group` elements for multi-level hierarchies. Each group must contain exactly one `micl-checkbox__parent`; a nested group without one is not tracked by its ancestor.
+
+The parent checkbox reflects the state of its descendants: **checked** when all of them are selected, **unchecked** when none are, and **indeterminate** when the selection is partial — including when that partial selection sits inside a nested group. Because an indeterminate parent is not itself checked, it is left out of form submission until everything below it is selected, and clicking it selects the whole group.
+
+Disabled checkboxes take no part in this. The parent neither changes them nor counts them, so a group whose only unselected checkbox is disabled still reports as fully selected, and a disabled checkbox that is checked does not by itself make its parent indeterminate. A nested group containing nothing but disabled checkboxes is skipped entirely rather than counting as an unselected branch.
+
+## Validation
+A single checkbox is made mandatory with the standard `required` attribute. On top of that, the form foundation adds **count validation** for a set of related checkboxes, so you can express rules such as "pick at least two" or "pick exactly three".
+
+### Error state
+Whenever the form foundation validates a checkbox, it adds the `micl-checkbox--error` class to any `<input type="checkbox">` carrying the `micl-checkbox` class that has a validation message, and removes the class again once the checkbox becomes valid. If you are using the form foundation, there is no need to toggle this class manually.
+
+### Counting checkboxes in a fieldset
+Wrap the related checkboxes in a `<fieldset>` and describe the rule with data attributes:
+
+| Attribute | Meaning |
+|---|---|
+| `data-miclvalidate-checkboxes-name` | The `name` shared by the checkboxes to count. Required. |
+| `data-miclvalidate-message` | The message shown when the rule is broken. Required — without it the fieldset is skipped. |
+| `data-miclvalidate-checkboxes-count-min` | The smallest allowed number of checked checkboxes. |
+| `data-miclvalidate-checkboxes-count-max` | The largest allowed number of checked checkboxes. |
+| `data-miclvalidate-checkboxes-count-equal` | The exact number of checked checkboxes required. |
+
+At least one of the three `count` attributes must be present. They may be combined, and the fieldset is invalid as soon as any one of them is violated.
+
+```HTML
+<form id="myform">
+  <fieldset
+    data-miclvalidate-checkboxes-name="topping"
+    data-miclvalidate-checkboxes-count-min="2"
+    data-miclvalidate-checkboxes-count-max="3"
+    data-miclvalidate-message="Please choose two or three toppings.">
+    <legend>Toppings</legend>
+    <input type="checkbox" id="t1" class="micl-checkbox" name="topping" value="olives">
+    <label for="t1">Olives</label>
+    <input type="checkbox" id="t2" class="micl-checkbox" name="topping" value="capers">
+    <label for="t2">Capers</label>
+    ...
+  </fieldset>
+</form>
+```
+
+### JavaScript
+Count validation must be triggered manually. Import the form foundation and call it, typically within a submit handler:
+
+```JavaScript
+import form from "material-inspired-component-library/dist/foundations/form";
+
+document.getElementById("myform").addEventListener("submit", event => {
+    if (!form.validateForm(event.currentTarget, true)) {
+        event.preventDefault();
+    }
+});
+```
+
+`validateForm(form, doReport)` checks every fieldset and every control in the form and returns `true` when all of them are valid. `validateFieldSet(fieldset, doReport)` does the same for a single `<fieldset>`. When `doReport` is `true` the browser additionally shows its own validation bubble; omit it to apply the error state silently.
+
+The message is attached to the **first** checkbox of the named set — that is the control that reports as invalid — and is cleared again as soon as that checkbox changes.
+
+Note that the counted set is defined by the `name` attribute, independently of the checkbox-group classes. If you combine count validation with a [checkbox group](#checkbox-group), give the `micl-checkbox__parent` checkbox a **different** `name` or none at all, otherwise it is counted alongside its children once they are all selected.
 
 ## Theming
 Each checkbox 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 checkboxes.
@@ -95,6 +163,7 @@ Each checkbox can be themed with CSS custom properties that follow the Material
 | Custom property | Meaning | Default |
 |---|---|---|
 | `--md-comp-checkbox-container-size` | The size of the checkbox itself | `18px` |
+| `--md-comp-checkbox-container-shape` | The corner radius of the checkbox | `2px` |
 | `--md-comp-checkbox-outline-width` | The thickness of the checkbox's border | `2px` |
 | `--md-comp-checkbox-check-thickness` | The thickness of the check mark | `2px` |
 | `--md-comp-checkbox-unselected-outline-color` | The border color of an unselected checkbox | `--md-sys-color-on-surface-variant` |
@@ -110,14 +179,14 @@ Each checkbox can be themed with CSS custom properties that follow the Material
 </div>
 ```
 
-To vertically align a checkbox with its label, wrap both in an element that has a styling like suggested below:
+## Compatibility
+This component relies on several recent CSS features, which may not be fully supported in your browser:
 
-```HTML
-<div style="display:flex;flex-direction:row;align-items:center">
-  <input type="checkbox" id="mycheckbox" class="micl-checkbox">
-  <label for="mycheckbox">Checkbox</label>
-</div>
-```
+| Feature | Used for |
+|---|---|
+| [Relative RGB color values](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#browser_compatibility) | The state layer and the ripple |
+| [`clip-path: rect()`](https://developer.mozilla.org/en-US/docs/Web/CSS/basic-shape/rect) | Revealing the check mark — without it the mark does not draw correctly |
+| [`:has()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:has) | Styling a `<label>` that precedes its checkbox |
+| [`:dir()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir) | Mirroring the check mark for right-to-left languages |
 
-## Compatibility
-This component utilizes relative RGB color values, 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.
+Please check the linked browser-compatibility tables for details.