material-inspired-component-library 8.0.0 → 8.0.4

package/components/progressindicator/README.md

@@ -0,0 +1,88 @@
+# Progress Indicator
+This component implements the [Material Design 3 Expressive Progress indicators](https://m3.material.io/components/progress-indicators/overview) design. Progress indicators show the status of a process in real time, either as a determinate value or as an indeterminate, looping animation.
+
+## 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.
+
+A **determinate** indicator has a known value. Provide the `value` and (optionally) `max` attributes:
+
+```HTML
+<progress class="micl-progress-linear" value="0.6" max="1"></progress>
+<progress class="micl-progress-circular" value="60" max="100"></progress>
+```
+
+An **indeterminate** indicator has an unknown value. Omit the `value` attribute entirely:
+
+```HTML
+<progress class="micl-progress-linear"></progress>
+<progress class="micl-progress-circular"></progress>
+```
+
+### CSS
+Import the progress indicator styles into your project:
+
+```CSS
+@use "material-inspired-component-library/dist/progressindicator";
+```
+
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/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.
+
+> **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.
+
+### Live Demo
+A live example of the [Progress Indicator component](https://henkpb.github.io/micl/progressindicator.html) is available to interact with.
+
+## 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**
+
+```HTML
+<progress class="micl-progress-linear" value="0.4"
+  style="--md-comp-progress-thickness:8px;--md-comp-progress-wave-amplitude:2px"></progress>
+```
+
+## 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.

package/components/progressindicator/index.scss

@@ -0,0 +1,225 @@
+//
+// 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';
+@use '../../styles/motion';
+
+@include motion.duration('long2');
+@include motion.duration('extra-long4');
+
+// Registered so determinate updates from the JS handler interpolate smoothly.
+// Never keyframe-animated.
+@property --md-comp-progress-fraction {
+    syntax: '<number>';
+    initial-value: 0;
+    inherits: true;
+}
+
+// Non-themed defaults. Declared on :root so they can be overridden on :root or
+// any parent element (consistent with the other MICL components). The colour
+// roles are resolved per the M3 progress-indicator spec at the point of use
+// (see $active/$track/$stop) because the theme palette is scoped to the
+// .light/.dark window class and is therefore NOT in scope at :root.
+:root {
+    --md-comp-progress-thickness: 4px;
+    --md-comp-progress-track-gap: 4px;
+    --md-comp-progress-stop-size: 4px;
+    --md-comp-progress-linear-width: 100%;
+    --md-comp-progress-wave-wavelength: 40px;
+    --md-comp-progress-wave-amplitude: 3px;
+    --md-comp-progress-indeterminate-duration: var(--md-sys-motion-duration-extra-long4);
+    --md-comp-progress-circular-size: 48px;
+    --md-comp-progress-amplitude-scale: 1;
+
+    // One wavelength of a sine ribbon, stroked at a constant width, used as a
+    // static mask so the active indicator takes a wavy shape. Painted once —
+    // no animation, no per-frame cost. The stroke is WHITE so it reveals
+    // correctly whether the browser treats the SVG mask as alpha (white =
+    // opaque) or luminance (white = 1).
+    --md-comp-progress-wave-image: url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 10' preserveAspectRatio='none'%3E%3Cpath d='M0 5 Q10 -1 20 5 T40 5' fill='none' stroke='white' stroke-width='4' stroke-linecap='round'/%3E%3C/svg%3E");
+}
+
+// M3 progress-indicator colour mapping. Resolved on the component element so
+// the system palette (scoped to the themed window ancestor) is in scope; a
+// consumer-supplied --md-comp-progress-*-color on any ancestor still wins.
+$active: var(--md-comp-progress-active-color, var(--md-sys-color-primary));
+$track:  var(--md-comp-progress-track-color, var(--md-sys-color-secondary-container));
+$stop:   var(--md-comp-progress-stop-color, var(--md-sys-color-primary));
+
+%progress-reset {
+    -webkit-appearance: none;
+            appearance: none;
+    border: none;
+    margin: 0;
+    background-color: transparent;
+    color: $active;
+    vertical-align: middle;
+}
+
+// Static wavy active indicator. No animation: the mask is rasterised once and
+// never sampled again, so a screen full of determinate indicators costs
+// nothing per frame.
+@mixin wave {
+    background-color: $active;
+    -webkit-mask-image: var(--md-comp-progress-wave-image);
+            mask-image: var(--md-comp-progress-wave-image);
+    -webkit-mask-repeat: repeat-x;
+            mask-repeat: repeat-x;
+    -webkit-mask-position: 0 center;
+            mask-position: 0 center;
+    -webkit-mask-size: var(--md-comp-progress-wave-wavelength)
+        calc(var(--md-comp-progress-thickness) + 2 * var(--md-comp-progress-wave-amplitude) * var(--md-comp-progress-amplitude-scale, 1));
+            mask-size: var(--md-comp-progress-wave-wavelength)
+        calc(var(--md-comp-progress-thickness) + 2 * var(--md-comp-progress-wave-amplitude) * var(--md-comp-progress-amplitude-scale, 1));
+}
+
+//
+// Linear progress indicator
+//
+progress.micl-progress-linear {
+    @extend %progress-reset;
+
+    display: inline-block;
+    inline-size: var(--md-comp-progress-linear-width);
+    block-size: calc(var(--md-comp-progress-thickness) + 2 * var(--md-comp-progress-wave-amplitude));
+
+    // Track (remaining portion) + end stop indicator. Starts one track-gap
+    // after the active indicator, clipped to --thickness tall and centred.
+    @mixin track {
+        background-color: transparent;
+        background-image:
+            radial-gradient(circle, #{$stop} 0 50%, transparent 50%),
+            linear-gradient(90deg,
+                transparent 0 calc(var(--md-comp-progress-fraction, 0) * 100% + var(--md-comp-progress-track-gap)),
+                #{$track} calc(var(--md-comp-progress-fraction, 0) * 100% + var(--md-comp-progress-track-gap)) 100%);
+        background-repeat: no-repeat;
+        background-position: right center, left center;
+        background-size:
+            var(--md-comp-progress-stop-size) var(--md-comp-progress-stop-size),
+            100% var(--md-comp-progress-thickness);
+        border-radius: calc(var(--md-comp-progress-thickness) / 2);
+    }
+
+    &::-webkit-progress-bar  { @include track; }
+    &::-webkit-progress-value { @include wave; }
+    &::-moz-progress-bar      { @include wave; }
+
+    // Firefox renders the track on the element itself.
+    @-moz-document url-prefix() {
+        @include track;
+    }
+
+    // Indeterminate: a comet sweeping a transparent track. Only this transient
+    // state animates; the move is a single small repainted strip.
+    &:indeterminate {
+        background-image:
+            linear-gradient(90deg, transparent, #{$active}, transparent),
+            linear-gradient(#{$track}, #{$track});
+        background-repeat: no-repeat;
+        background-position: -40% center, left center;
+        background-size: 40% var(--md-comp-progress-thickness), 100% var(--md-comp-progress-thickness);
+        border-radius: calc(var(--md-comp-progress-thickness) / 2);
+        animation: micl-progress-linear-indeterminate var(--md-comp-progress-indeterminate-duration) var(--md-sys-motion-easing-standard, ease-in-out) infinite;
+
+        &::-webkit-progress-bar,
+        &::-webkit-progress-value { background: transparent; }
+        &::-moz-progress-bar      { background: transparent; }
+    }
+}
+
+@keyframes micl-progress-linear-indeterminate {
+    0%   { background-position: -40% center, left center; }
+    100% { background-position: 140% center, left center; }
+}
+
+//
+// Circular progress indicator
+//
+// Determinate: a static conic-gradient ring punched by a radial mask (white =
+// kept under both alpha and luminance masking). It is painted once and never
+// animated, so it costs nothing per frame.
+//
+progress.micl-progress-circular {
+    @extend %progress-reset;
+
+    --md-comp-progress-circular-gap-deg: 12deg;
+
+    display: inline-block;
+    box-sizing: border-box;
+    inline-size: var(--md-comp-progress-circular-size);
+    block-size: var(--md-comp-progress-circular-size);
+    border-radius: 50%;
+    background-image: conic-gradient(
+        #{$active} 0
+            max(0deg, calc(var(--md-comp-progress-fraction, 0) * 360deg - var(--md-comp-progress-circular-gap-deg))),
+        transparent
+            max(0deg, calc(var(--md-comp-progress-fraction, 0) * 360deg - var(--md-comp-progress-circular-gap-deg)))
+            calc(var(--md-comp-progress-fraction, 0) * 360deg),
+        #{$track} calc(var(--md-comp-progress-fraction, 0) * 360deg) 360deg);
+    -webkit-mask: radial-gradient(farthest-side,
+        transparent calc(100% - var(--md-comp-progress-thickness)),
+        #fff calc(100% - var(--md-comp-progress-thickness)));
+            mask: radial-gradient(farthest-side,
+        transparent calc(100% - var(--md-comp-progress-thickness)),
+        #fff calc(100% - var(--md-comp-progress-thickness)));
+
+    &::-webkit-progress-bar,
+    &::-webkit-progress-value { background: transparent; }
+    &::-moz-progress-bar      { background: transparent; }
+
+    &.micl-progress-circular--s { --md-comp-progress-circular-size: 28px; }
+    &.micl-progress-circular--m { --md-comp-progress-circular-size: 48px; }
+    &.micl-progress-circular--l { --md-comp-progress-circular-size: 64px; }
+
+    // Indeterminate: the canonical lightweight CSS spinner — a plain bordered
+    // ring (no gradient, no mask) rotated by transform. Chrome promotes this to
+    // a compositor layer, rasterises it once, and spins the texture on the GPU,
+    // so it is essentially free per frame regardless of how many are visible.
+    &:indeterminate {
+        background-image: none;
+        -webkit-mask: none;
+                mask: none;
+        border: var(--md-comp-progress-thickness) solid #{$track};
+        border-block-start-color: $active;
+        animation: micl-progress-circular-spin var(--md-comp-progress-indeterminate-duration) linear infinite;
+    }
+}
+
+@keyframes micl-progress-circular-spin {
+    to { transform: rotate(360deg); }
+}
+
+//
+// Right-to-left: mirror the linear sweep direction.
+//
+[dir=rtl] progress.micl-progress-linear {
+    transform: scaleX(-1);
+}
+
+//
+// Honour reduced-motion: stop the only two animated (loading) states.
+//
+@media (prefers-reduced-motion: reduce) {
+    progress.micl-progress-linear:indeterminate,
+    progress.micl-progress-circular:indeterminate {
+        animation: none;
+    }
+}

package/components/progressindicator/index.ts

@@ -0,0 +1,77 @@
+//
+// 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.
+
+export const progressindicatorSelector = 'progress.micl-progress-linear,progress.micl-progress-circular';
+
+export default (() =>
+{
+    // <progress> emits no input/change events when its value/max change, so a
+    // per-instance MutationObserver mirrors the determinate attributes into the
+    // CSS custom properties the SCSS reads. Indeterminate progress (no value
+    // attribute) is handled entirely in CSS via the :indeterminate pseudo-class.
+    const observers = new WeakMap<HTMLProgressElement, MutationObserver>();
+
+    const setVars = (element: HTMLProgressElement): void =>
+    {
+        // position is value/max for determinate, or -1 when indeterminate.
+        const fraction = element.position;
+
+        if (fraction < 0) {
+            element.style.removeProperty('--md-comp-progress-value');
+            element.style.removeProperty('--md-comp-progress-max');
+            element.style.removeProperty('--md-comp-progress-fraction');
+            element.style.removeProperty('--md-comp-progress-amplitude-scale');
+            return;
+        }
+
+        // The Expressive wave amplitude eases to zero over the final 10% so the
+        // active indicator settles into a straight line as it completes.
+        const scale = Math.max(0, Math.min(1, (1 - fraction) / 0.1));
+
+        element.style.setProperty('--md-comp-progress-value', String(element.value));
+        element.style.setProperty('--md-comp-progress-max', String(element.max || 1));
+        element.style.setProperty('--md-comp-progress-fraction', String(fraction));
+        element.style.setProperty('--md-comp-progress-amplitude-scale', String(scale));
+    };
+
+    return {
+        initialize: (element: HTMLProgressElement): void =>
+        {
+            if (!element.matches(progressindicatorSelector)) {
+                return;
+            }
+
+            setVars(element);
+
+            const observer = new MutationObserver(() => setVars(element));
+            observer.observe(element, { attributes: true, attributeFilter: ['value', 'max'] });
+            observers.set(element, observer);
+        },
+        cleanup: (element: HTMLProgressElement): void =>
+        {
+            const observer = observers.get(element);
+            if (observer) {
+                observer.disconnect();
+                observers.delete(element);
+            }
+        }
+    };
+})();

package/components/radio/index.scss

@@ -24,6 +24,19 @@
 @use '../../styles/shapes';
 @use '../../styles/statelayer';
 
+@include shapes.corner('full');
+
+@include statelayer.token('layer-size');
+@include statelayer.token('hover-state-layer-opacity');
+@include statelayer.token('focus-state-layer-opacity');
+@include statelayer.token('pressed-state-layer-opacity');
+@include statelayer.token('disabled-state-layer-opacity');
+@include statelayer.token('focus-indicator-thickness');
+@include statelayer.token('ripple-opacity-factor');
+@include statelayer.token('ripple-duration');
+@include statelayer.property;
+@include statelayer.keyframes;
+
 :root {
     --md-sys-radio-border-width: 2px;
     --md-sys-radio-container-size: 20px;

package/components/select/index.scss

@@ -26,6 +26,12 @@
 @use '../../styles/statelayer';
 @use '../../styles/typography';
 
+@include elevation.level(2);
+
+@include shapes.corner('large');
+
+@include statelayer.token('disabled-state-layer-opacity');
+
 .micl-textfield-filled > select {
     --md-comp-select-line-height: calc(var(--md-sys-textfield-height) - 18px - 3px);
 }
@@ -107,6 +113,8 @@
 
         .micl-list-item__text::after {
             content: attr(aria-description);
+            overflow: hidden;
+            text-overflow: ellipsis;
         }
         &::checkmark {
             color: var(--md-sys-color-on-surface-variant);

package/components/shape/README.md

@@ -0,0 +1,103 @@
+# Shape
+The Shape component renders Material Design 3 [Expressive Shapes](https://m3.material.io/styles/shape/overview-principles) — circle, square, pill, oval, heart, cookie, clover, sunny, and so on — as inline SVGs whose `d` attribute is supplied by CSS. Because the path data is set with `d:` rather than baked into the SVG markup, swapping a shape's class triggers a smooth `transition: d` morph between the old and new outline.
+
+## Basic Usage
+
+### HTML
+A shape is an empty `<svg>` with the base class `micl-shape` plus one of the shape modifier classes:
+
+```HTML
+<svg class="micl-shape micl-shape-heart" viewBox="0 0 100 100"><path /></svg>
+```
+
+Optional modifier classes:
+
+| Class | Effect |
+| --- | --- |
+| `micl-shape--outlined` | Renders the shape as a stroked outline instead of a filled fill |
+| `micl-shape--shadowed` | Adds a soft drop-shadow filter |
+
+### CSS
+
+The Shape component is **opt-in** — it is not included in the master `micl.css` bundle, because most apps don't need 35 decorative shapes. Pick one of three integration paths:
+
+**1. Import only the shapes you actually use (recommended for production):**
+
+```SCSS
+@use "material-inspired-component-library/components/shape" as shape;
+
+@include shape.base;
+@include shape.use("circle", "heart", "pill");
+```
+
+`shape.base` emits the shared `.micl-shape`, `.micl-shape--outlined`, and `.micl-shape--shadowed` rules. `shape.use(<names>...)` emits one `.micl-shape-<name> > path { d: … }` rule per name. Unknown names raise a Sass error at compile time.
+
+**2. Import the whole gallery via Sass:**
+
+```SCSS
+@use "material-inspired-component-library/components/shape" with ($master: true);
+```
+
+Equivalent to calling `shape.base` plus `shape.use(…)` with every shape.
+
+**3. Drop in the prebuilt CSS:**
+
+```HTML
+<link rel="stylesheet" href="material-inspired-component-library/dist/shape.css">
+```
+
+The prebuilt bundle contains all 35 shapes plus the base styles.
+
+### JavaScript
+No JavaScript is required. Morphing between shapes is a pure CSS animation: when you replace `micl-shape-heart` with `micl-shape-pill` on the element, the browser interpolates the `d:` value automatically. The morph timing can be customised via two CSS custom properties on the element:
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--morph-duration` | `0ms` | Length of the morph transition |
+| `--morph-easing` | `ease-in-out` | Easing curve of the transition |
+
+### Live Demo
+A live example of the [Shape component](https://henkpb.github.io/micl/shapes.html) is available, with a button per shape that morphs the demo SVG.
+
+## Variants
+The available shape names (use these as the `micl-shape-<name>` class and as arguments to `shape.use(...)`):
+
+```
+circle, square, slanted, arch, semicircle, oval, pill,
+triangle, arrow, fan, diamond, clamshell, pentagon, gem,
+very-sunny, sunny, cookie-4, cookie-6, cookie-7, cookie-9,
+cookie-12, clover-4, clover-8, burst, soft-burst, boom,
+soft-boom, flower, puffy, puffy-diamond, ghost-ish,
+pixel-circle, pixel-triangle, bun, heart
+```
+
+## Customizations
+The base styles size the SVG to 100 × 100 px, fill it with `green`, and let it overflow its viewBox horizontally (so wide shapes like *pill* and *fan* are not clipped). Override these on the element or on a parent:
+
+```HTML
+<svg class="micl-shape micl-shape-heart"
+     viewBox="0 0 100 100"
+     style="inline-size:64px;block-size:64px;fill:var(--md-sys-color-primary)">
+    <path />
+</svg>
+```
+
+For `micl-shape--outlined`, the stroke colour and width are controlled by the standard SVG `stroke` and `stroke-width` properties:
+
+```HTML
+<svg class="micl-shape micl-shape--outlined micl-shape-pill"
+     viewBox="0 0 100 100"
+     style="stroke:var(--md-sys-color-outline);stroke-width:3"><path /></svg>
+```
+
+## Contributing — regenerating the path data
+The 35 SVG path strings live in [`_paths.generated.scss`](./_paths.generated.scss) and are produced by [`tools/shapes/generate.mjs`](../../tools/shapes/generate.mjs). The Sass partial does no math at compile time — it only looks shapes up by name in the generated map. **Do not edit `_paths.generated.scss` by hand.**
+
+When you change a shape's vertex coordinates, repeat count, mirror flag, vertex count, or any of the underlying math:
+
+```bash
+npm run gen:shapes      # regenerate components/shape/_paths.generated.scss
+npm run check:shapes    # verify the file is up to date (CI runs this too)
+```
+
+Commit the regenerated `_paths.generated.scss` together with the change to the generator. CI fails if a PR modifies the generator without also updating the committed paths.