Meter

A read-only graphical display of a numeric value within a known range. Storage used, quota consumed, password strength, battery level. The host carries full role="meter" ARIA semantics, the value is clamped into [min, max], and the value text is real Intl.NumberFormat output — a locale-aware percentage by default, or units/currency/plain numbers via formatOptions.

Live preview Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" label="Storage used" show-label show-value></md-meter>
  <md-meter value="82" color="warning" label="Quota used" show-label show-value></md-meter>
  <md-meter value="3" max="10" color="success" label="Seats taken" value-text="3 of 10 seats" show-label show-value></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter value="65" label="Storage used" showLabel show-value></MdMeter>
        <MdMeter value="82" color="warning" label="Quota used" showLabel show-value></MdMeter>
        <MdMeter value="3" max="10" color="success" label="Seats taken" valueText="3 of 10 seats" showLabel show-value></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" label="Storage used" show-label show-value></md-meter>
  <md-meter value="82" color="warning" label="Quota used" show-label show-value></md-meter>
  <md-meter value="3" max="10" color="success" label="Seats taken" value-text="3 of 10 seats" show-label show-value></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter value="65" label="Storage used" show-label show-value></md-meter>
    <md-meter value="82" color="warning" label="Quota used" show-label show-value></md-meter>
    <md-meter value="3" max="10" color="success" label="Seats taken" value-text="3 of 10 seats" show-label show-value></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" label="Storage used" show-label show-value></md-meter>
  <md-meter value="82" color="warning" label="Quota used" show-label show-value></md-meter>
  <md-meter value="3" max="10" color="success" label="Seats taken" value-text="3 of 10 seats" show-label show-value></md-meter>
</div>

Read-only by design

A meter is a reading, not a control: no events, no methods, no slots, nothing focusable. If the user should change the value, you want md-slider; if you are visualising an activity, you want md-progress-indicator.

Not a Material Design 3 component

M3 has no meter page. This is the WAI-ARIA meter pattern drawn on MD3 progress-indicator geometry, so the visuals follow M3 while the semantics follow the ARIA spec; the guidance below is house rules.

Install

Already installed? See the Installation guide for one-time package setup (core + tokens, fonts). Each tab below shows two patterns for using md-meter in your project: Option A registers every AWC UI component at once (simplest), Option B imports only this component for tree-shake-friendly bundles.

HTML React Angular Vue Svelte

Copy

<!-- ─── Option A: global registration (all components) ─── -->
<script type="module">
  import '@awc-ui/core/define';
</script>


<!-- ─── Option B: single import (tree-shake only md-meter) ─── -->
<script type="module">
  import '@awc-ui/core/components/md-meter';
</script>


<md-meter></md-meter>

Copy

// ─── Option A: typed React wrapper (registers all components) ───
//   Importing from '@awc-ui/react' calls defineCustomElements() as a
//   side effect, so every md-* element becomes available in the browser.
import { MdMeter } from '@awc-ui/react';

export function Example() {
  return <MdMeter></MdMeter>;
}


// ─── Option B: single import (tree-shake to only md-meter) ───
//   Skip the wrapper and use the raw custom element. Smallest bundle,
//   but you lose typed props/events on JSX.
import '@awc-ui/core/components/md-meter';

export function ExampleTreeShaken() {
  return <md-meter></md-meter>;
}

Copy

// ─── Option A: schema module (any md-* element accepted) ───
//   Pair with `defineCustomElements(window)` in main.ts.
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@Component({
  standalone: true,
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `<md-meter></md-meter>`,
})
export class ExampleComponent {}


// ─── Option B: typed directive (tree-shake friendly) ───
//   Pair with `import '@awc-ui/core/components/md-meter'` in main.ts.
import { Component } from '@angular/core';
import { MdMeter } from '@awc-ui/angular';

@Component({
  standalone: true,
  imports: [MdMeter],
  template: `<md-meter></md-meter>`,
})
export class ExampleTreeShakenComponent {}

Copy

<!-- ─── Option A: typed Vue wrapper (registers all components) ─── -->
<script setup lang="ts">
import { MdMeter } from '@awc-ui/vue';
</script>

<template>
  <MdMeter></MdMeter>
</template>


<!-- ─── Option B: single import (tree-shake to only md-meter) ─── -->
<script setup lang="ts">
import '@awc-ui/core/components/md-meter';
</script>

<template>
  <md-meter></md-meter>
</template>

Copy

<!-- ─── Option A: global registration (done once in main entry) ─── -->
<!-- main.ts:                                                          -->
<!--   import { defineCustomElements } from '@awc-ui/svelte';        -->
<!--   defineCustomElements(window);                                   -->

<md-meter></md-meter>


<!-- ─── Option B: single import (tree-shake to only md-meter) ─── -->
<script lang="ts">
  import '@awc-ui/core/components/md-meter';
</script>

<md-meter></md-meter>

When to use

• A current state within a known range: disk/storage usage, quota, capacity.
• A strength or level reading: password strength, signal, battery.
• Anywhere native <meter> semantics fit but you want MD3 visuals, theming and density.

When not to use

Situation	Use instead
How far along an activity is (upload, install, load)	md-progress-indicator
An unknown-length wait	md-loading-indicator
The user should change the value	md-slider
A score the user assigns	md-rating
A tiny binary/status signal	md-status-dot or md-badge

Meter vs progress indicator

The load-bearing distinction: a meter shows a state (“how full”), a progress indicator shows an activity (“how far along”). That is why md-meter deliberately has no indeterminate mode, no M3-Expressive 4px gap, no stop dot and no completion animation — it is a plain track + fill that sits still.

Value & range

value is clamped into [min, max] before ARIA, geometry and formatting — value="150" in a 0–100 range renders and announces 100%. An inverted range (max < min) collapses to an empty one instead of emitting invalid ARIA.

Clamping and custom ranges Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="0" label="Empty" show-label show-value></md-meter>
  <md-meter value="50" label="Half" show-label show-value></md-meter>
  <md-meter value="100" label="Full" show-label show-value></md-meter>
  <md-meter value="150" label="Clamped from 150" show-label show-value></md-meter>
  <md-meter min="100" max="200" value="150" label="Range 100–200" show-label show-value></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter value="0" label="Empty" showLabel show-value></MdMeter>
        <MdMeter value="50" label="Half" showLabel show-value></MdMeter>
        <MdMeter value="100" label="Full" showLabel show-value></MdMeter>
        <MdMeter value="150" label="Clamped from 150" showLabel show-value></MdMeter>
        <MdMeter min="100" max="200" value="150" label="Range 100–200" showLabel show-value></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="0" label="Empty" show-label show-value></md-meter>
  <md-meter value="50" label="Half" show-label show-value></md-meter>
  <md-meter value="100" label="Full" show-label show-value></md-meter>
  <md-meter value="150" label="Clamped from 150" show-label show-value></md-meter>
  <md-meter min="100" max="200" value="150" label="Range 100–200" show-label show-value></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter value="0" label="Empty" show-label show-value></md-meter>
    <md-meter value="50" label="Half" show-label show-value></md-meter>
    <md-meter value="100" label="Full" show-label show-value></md-meter>
    <md-meter value="150" label="Clamped from 150" show-label show-value></md-meter>
    <md-meter min="100" max="200" value="150" label="Range 100–200" show-label show-value></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="0" label="Empty" show-label show-value></md-meter>
  <md-meter value="50" label="Half" show-label show-value></md-meter>
  <md-meter value="100" label="Full" show-label show-value></md-meter>
  <md-meter value="150" label="Clamped from 150" show-label show-value></md-meter>
  <md-meter min="100" max="200" value="150" label="Range 100–200" show-label show-value></md-meter>
</div>

The last example shows the default value text is the value’s position in the range, not the raw number: 150 in 100–200 reads “50%”.

Label & value header

show-label and show-value render an optional header row above the track — label start-aligned, formatted value end-aligned. The visible value span is aria-hidden; screen readers get the exact same string once, via aria-valuetext on the host.

Header combinations Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="40" label="Bare track (label is ARIA-only)"></md-meter>
  <md-meter value="40" label="Label only" show-label></md-meter>
  <md-meter value="40" label="Value only" show-value></md-meter>
  <md-meter value="40" label="Label and value" show-label show-value></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter value="40" label="Bare track (label is ARIA-only)"></MdMeter>
        <MdMeter value="40" label="Label only" show-label></MdMeter>
        <MdMeter value="40" label="Value only" show-value></MdMeter>
        <MdMeter value="40" label="Label and value" showLabel show-value></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="40" label="Bare track (label is ARIA-only)"></md-meter>
  <md-meter value="40" label="Label only" show-label></md-meter>
  <md-meter value="40" label="Value only" show-value></md-meter>
  <md-meter value="40" label="Label and value" show-label show-value></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter value="40" label="Bare track (label is ARIA-only)"></md-meter>
    <md-meter value="40" label="Label only" show-label></md-meter>
    <md-meter value="40" label="Value only" show-value></md-meter>
    <md-meter value="40" label="Label and value" show-label show-value></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="40" label="Bare track (label is ARIA-only)"></md-meter>
  <md-meter value="40" label="Label only" show-label></md-meter>
  <md-meter value="40" label="Value only" show-value></md-meter>
  <md-meter value="40" label="Label and value" show-label show-value></md-meter>
</div>

Formatting

Three tiers, most specific wins:

Tier	What is formatted	Example output
default	percentage of the range, Intl percent style	24%, 24 %, ٢٤٪
formatOptions	the clamped raw value, any Intl.NumberFormatOptions	256 GB, €750.00, 7.4
value-text	nothing — your literal string wins	3 of 10 seats

formatOptions is a JS-only object prop — set it as a property, not an attribute. locale (BCP-47) picks the Intl locale; leave it empty to follow the runtime’s default.

Percent, unit, currency and literal value text Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<md-meter id="meter-gb" value="256" max="512" label="Gigabytes" show-label show-value></md-meter>
<md-meter id="meter-eur" value="750" max="1000" locale="de-DE" label="Budget spent" show-label show-value></md-meter>

<script type="module">
  const gb = document.getElementById('meter-gb');
  const eur = document.getElementById('meter-eur');
  gb.formatOptions = { style: 'unit', unit: 'gigabyte' };
  eur.formatOptions = { style: 'currency', currency: 'EUR' };
</script>

Copy

import { MdMeter } from '@awc-ui/react';

const formatOptions = { style: 'unit', unit: 'gigabyte' };

const eurFormatOptions = { style: 'currency', currency: 'EUR' };

export function Demo() {
  return (
    <>
      <MdMeter id="meter-gb"
        formatOptions={formatOptions} value="256" max="512" label="Gigabytes" showLabel show-value></MdMeter>
      <MdMeter id="meter-eur"
        formatOptions={eurFormatOptions} value="750" max="1000" locale="de-DE" label="Budget spent" showLabel show-value></MdMeter>
    </>
  );
}

Copy

import { Component } from '@angular/core';

// Bind the CAMELCASE name. [format-options]="…" would set a
// "format-options" property that md-meter never reads, and the
// meter would silently fall back to the default percent output.
@Component({
selector: 'app-formatted-meters',
template: `
  <md-meter
    [formatOptions]="gbFormat"
    value="256"
    max="512"
    label="Gigabytes"
    show-label
    show-value
  ></md-meter>

  <md-meter
    [formatOptions]="eurFormat"
    locale="de-DE"
    value="750"
    max="1000"
    label="Budget spent"
    show-label
    show-value
  ></md-meter>
`,
})
export class FormattedMetersComponent {
gbFormat: Intl.NumberFormatOptions = { style: 'unit', unit: 'gigabyte' };
eurFormat: Intl.NumberFormatOptions = { style: 'currency', currency: 'EUR' };
}

Copy

<script setup lang="ts">
import '@awc-ui/core/define';

const gbFormat: Intl.NumberFormatOptions = { style: 'unit', unit: 'gigabyte' };
const eurFormat: Intl.NumberFormatOptions = { style: 'currency', currency: 'EUR' };
</script>

<template>
<!-- :formatOptions, not :format-options — Vue only sets a binding as a DOM
     property when the name exists on the element. -->
<md-meter
  :formatOptions="gbFormat"
  value="256"
  max="512"
  label="Gigabytes"
  show-label
  show-value
/>

<md-meter
  :formatOptions="eurFormat"
  locale="de-DE"
  value="750"
  max="1000"
  label="Budget spent"
  show-label
  show-value
/>
</template>

Copy

<script>
  import '@awc-ui/core/define';

  const formatOptions = { style: 'unit', unit: 'gigabyte' };

  const eurFormatOptions = { style: 'currency', currency: 'EUR' };
</script>

<md-meter id="meter-gb"
  {formatOptions} value="256" max="512" label="Gigabytes" show-label show-value></md-meter>
<md-meter id="meter-eur"
  formatOptions={eurFormatOptions} value="750" max="1000" locale="de-DE" label="Budget spent" show-label show-value></md-meter>

One string, two consumers

Whatever the formatter (or value-text) produces drives both the visible header value and aria-valuetext, so what is seen and what is announced can never disagree. Invalid formatOptions combinations degrade to the raw value instead of throwing.

Color

color takes a theme role name, resolved at runtime to the --md-sys-color-<role> / -<role>-container pair — fill on container. Any role a theme defines works (color="brand"), not just the seven baseline ones. The default (primary) keeps the progress-indicator’s neutral look: primary fill on a secondary-container track.

Reading	color
Neutral measurement	primary (default)
Healthy / plenty left	success
Approaching the limit	warning
Critical / exceeded	error
Informational level	info

Color roles, including the semantic status roles Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" color="primary" label="primary" show-label show-value></md-meter>
  <md-meter value="65" color="secondary" label="secondary" show-label show-value></md-meter>
  <md-meter value="65" color="tertiary" label="tertiary" show-label show-value></md-meter>
  <md-meter value="65" color="success" label="success" show-label show-value></md-meter>
  <md-meter value="65" color="warning" label="warning" show-label show-value></md-meter>
  <md-meter value="65" color="error" label="error" show-label show-value></md-meter>
  <md-meter value="65" color="info" label="info" show-label show-value></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter value="65" color="primary" label="primary" showLabel show-value></MdMeter>
        <MdMeter value="65" color="secondary" label="secondary" showLabel show-value></MdMeter>
        <MdMeter value="65" color="tertiary" label="tertiary" showLabel show-value></MdMeter>
        <MdMeter value="65" color="success" label="success" showLabel show-value></MdMeter>
        <MdMeter value="65" color="warning" label="warning" showLabel show-value></MdMeter>
        <MdMeter value="65" color="error" label="error" showLabel show-value></MdMeter>
        <MdMeter value="65" color="info" label="info" showLabel show-value></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" color="primary" label="primary" show-label show-value></md-meter>
  <md-meter value="65" color="secondary" label="secondary" show-label show-value></md-meter>
  <md-meter value="65" color="tertiary" label="tertiary" show-label show-value></md-meter>
  <md-meter value="65" color="success" label="success" show-label show-value></md-meter>
  <md-meter value="65" color="warning" label="warning" show-label show-value></md-meter>
  <md-meter value="65" color="error" label="error" show-label show-value></md-meter>
  <md-meter value="65" color="info" label="info" show-label show-value></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter value="65" color="primary" label="primary" show-label show-value></md-meter>
    <md-meter value="65" color="secondary" label="secondary" show-label show-value></md-meter>
    <md-meter value="65" color="tertiary" label="tertiary" show-label show-value></md-meter>
    <md-meter value="65" color="success" label="success" show-label show-value></md-meter>
    <md-meter value="65" color="warning" label="warning" show-label show-value></md-meter>
    <md-meter value="65" color="error" label="error" show-label show-value></md-meter>
    <md-meter value="65" color="info" label="info" show-label show-value></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" color="primary" label="primary" show-label show-value></md-meter>
  <md-meter value="65" color="secondary" label="secondary" show-label show-value></md-meter>
  <md-meter value="65" color="tertiary" label="tertiary" show-label show-value></md-meter>
  <md-meter value="65" color="success" label="success" show-label show-value></md-meter>
  <md-meter value="65" color="warning" label="warning" show-label show-value></md-meter>
  <md-meter value="65" color="error" label="error" show-label show-value></md-meter>
  <md-meter value="65" color="info" label="info" show-label show-value></md-meter>
</div>

Never colour alone

A status colour must be paired with the visible value, the label, or value-text — colour is invisible to many users and to screen readers.

The canonical quota recipe switches the role as thresholds are crossed:

Threshold-driven status colors Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="45" color="success" label="Storage used" value-text="45 GB of 100 GB" show-label show-value></md-meter>
  <md-meter value="82" color="warning" label="Storage used" value-text="82 GB of 100 GB" show-label show-value></md-meter>
  <md-meter value="96" color="error" label="Storage used" value-text="96 GB of 100 GB" show-label show-value></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter value="45" color="success" label="Storage used" valueText="45 GB of 100 GB" showLabel show-value></MdMeter>
        <MdMeter value="82" color="warning" label="Storage used" valueText="82 GB of 100 GB" showLabel show-value></MdMeter>
        <MdMeter value="96" color="error" label="Storage used" valueText="96 GB of 100 GB" showLabel show-value></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="45" color="success" label="Storage used" value-text="45 GB of 100 GB" show-label show-value></md-meter>
  <md-meter value="82" color="warning" label="Storage used" value-text="82 GB of 100 GB" show-label show-value></md-meter>
  <md-meter value="96" color="error" label="Storage used" value-text="96 GB of 100 GB" show-label show-value></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter value="45" color="success" label="Storage used" value-text="45 GB of 100 GB" show-label show-value></md-meter>
    <md-meter value="82" color="warning" label="Storage used" value-text="82 GB of 100 GB" show-label show-value></md-meter>
    <md-meter value="96" color="error" label="Storage used" value-text="96 GB of 100 GB" show-label show-value></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="45" color="success" label="Storage used" value-text="45 GB of 100 GB" show-label show-value></md-meter>
  <md-meter value="82" color="warning" label="Storage used" value-text="82 GB of 100 GB" show-label show-value></md-meter>
  <md-meter value="96" color="error" label="Storage used" value-text="96 GB of 100 GB" show-label show-value></md-meter>
</div>

Thickness

thickness is the track height in dp (default 4). It is density-scaled (0.5px per rung) and floored at 2px; --md-meter-height overrides it entirely.

Track thickness Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" thickness="2" label="2px"></md-meter>
  <md-meter value="65" label="4px (default)"></md-meter>
  <md-meter value="65" thickness="8" label="8px"></md-meter>
  <md-meter value="65" thickness="12" label="12px"></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter value="65" thickness="2" label="2px"></MdMeter>
        <MdMeter value="65" label="4px (default)"></MdMeter>
        <MdMeter value="65" thickness="8" label="8px"></MdMeter>
        <MdMeter value="65" thickness="12" label="12px"></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" thickness="2" label="2px"></md-meter>
  <md-meter value="65" label="4px (default)"></md-meter>
  <md-meter value="65" thickness="8" label="8px"></md-meter>
  <md-meter value="65" thickness="12" label="12px"></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter value="65" thickness="2" label="2px"></md-meter>
    <md-meter value="65" label="4px (default)"></md-meter>
    <md-meter value="65" thickness="8" label="8px"></md-meter>
    <md-meter value="65" thickness="12" label="12px"></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" thickness="2" label="2px"></md-meter>
  <md-meter value="65" label="4px (default)"></md-meter>
  <md-meter value="65" thickness="8" label="8px"></md-meter>
  <md-meter value="65" thickness="12" label="12px"></md-meter>
</div>

Circular

variant="circular" draws the same reading as a ring. show-value puts the value in the middle of it and show-label captions it underneath — the bar’s header row doesn’t apply. size is the diameter in dp (default 48, clamped to 24–240); everything else — color, thickness, formatOptions, the ARIA contract — behaves exactly as it does on the bar.

Ring sizes, thickness and colour roles Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; align-items: flex-start; gap: 32px; flex-wrap: wrap;">
  <md-meter variant="circular" value="72" show-value></md-meter>
  <md-meter variant="circular" value="72" size="72" thickness="6" show-value show-label label="Storage"></md-meter>
  <md-meter variant="circular" value="41" size="96" thickness="8" color="tertiary" show-value show-label label="Quota used"></md-meter>
  <md-meter variant="circular" value="92" size="96" thickness="8" color="error" show-value show-label label="Almost full"></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', alignItems: 'flex-start', gap: '32px', flexWrap: 'wrap' }}>
        <MdMeter variant="circular" value="72" show-value></MdMeter>
        <MdMeter variant="circular" value="72" size="72" thickness="6" showValue showLabel label="Storage"></MdMeter>
        <MdMeter variant="circular" value="41" size="96" thickness="8" color="tertiary" showValue showLabel label="Quota used"></MdMeter>
        <MdMeter variant="circular" value="92" size="96" thickness="8" color="error" showValue showLabel label="Almost full"></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; align-items: flex-start; gap: 32px; flex-wrap: wrap;">
  <md-meter variant="circular" value="72" show-value></md-meter>
  <md-meter variant="circular" value="72" size="72" thickness="6" show-value show-label label="Storage"></md-meter>
  <md-meter variant="circular" value="41" size="96" thickness="8" color="tertiary" show-value show-label label="Quota used"></md-meter>
  <md-meter variant="circular" value="92" size="96" thickness="8" color="error" show-value show-label label="Almost full"></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; align-items: flex-start; gap: 32px; flex-wrap: wrap;">
    <md-meter variant="circular" value="72" show-value></md-meter>
    <md-meter variant="circular" value="72" size="72" thickness="6" show-value show-label label="Storage"></md-meter>
    <md-meter variant="circular" value="41" size="96" thickness="8" color="tertiary" show-value show-label label="Quota used"></md-meter>
    <md-meter variant="circular" value="92" size="96" thickness="8" color="error" show-value show-label label="Almost full"></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; align-items: flex-start; gap: 32px; flex-wrap: wrap;">
  <md-meter variant="circular" value="72" show-value></md-meter>
  <md-meter variant="circular" value="72" size="72" thickness="6" show-value show-label label="Storage"></md-meter>
  <md-meter variant="circular" value="41" size="96" thickness="8" color="tertiary" show-value show-label label="Quota used"></md-meter>
  <md-meter variant="circular" value="92" size="96" thickness="8" color="error" show-value show-label label="Almost full"></md-meter>
</div>

The ring fills clockwise from twelve o’clock in every locale — it is not mirrored under dir="rtl", matching Material’s circular progress indicator (and a clock face). Only the caption text direction flips; see The ring does not mirror below for the side-by-side.

Events

md-meter emits no events — it is a pure read-only display, so there is nothing to listen to and nothing to cancel.

Event	Cancelable	Detail	Fires
none	—	—	A meter is a reading, not a control — drive it by setting value

Drive it from your state layer instead: set value (and color, value-text) and the fill animates to its new position over 300ms, zeroed under prefers-reduced-motion. Press a threshold below — only value, value-text and color change:

Driving the reading from state — value, value-text and color Open in Storybook

45 GB 82 GB 96 GB

Show code for each technology

HTML React Angular Vue Svelte

Copy

<md-meter id="quota" max="100" label="Storage used" show-label show-value></md-meter>

<script type="module">
const quota = document.getElementById('quota');

function setUsage(usedGb, totalGb) {
  const ratio = usedGb / totalGb;
  quota.max = totalGb;
  quota.value = usedGb;
  quota.valueText = usedGb + ' GB of ' + totalGb + ' GB';
  quota.color = ratio >= 0.95 ? 'error' : ratio >= 0.8 ? 'warning' : 'success';
}

setUsage(45, 100);
</script>

Copy

import { MdMeter } from '@awc-ui/react';

export function QuotaMeter({ usedGb, totalGb }: { usedGb: number; totalGb: number }) {
const ratio = usedGb / totalGb;
const color = ratio >= 0.95 ? 'error' : ratio >= 0.8 ? 'warning' : 'success';
return (
  <MdMeter
    value={usedGb}
    max={totalGb}
    color={color}
    label="Storage used"
    valueText={`${usedGb} GB of ${totalGb} GB`}
    showLabel
    showValue
  />
);
}

Copy

import { Component, Input } from '@angular/core';

@Component({
selector: 'app-quota-meter',
template: `
  <md-meter
    [value]="usedGb"
    [max]="totalGb"
    [color]="color"
    label="Storage used"
    [valueText]="usedGb + ' GB of ' + totalGb + ' GB'"
    show-label
    show-value
  ></md-meter>
`,
})
export class QuotaMeterComponent {
@Input() usedGb = 0;
@Input() totalGb = 100;
get color() {
  const ratio = this.usedGb / this.totalGb;
  return ratio >= 0.95 ? 'error' : ratio >= 0.8 ? 'warning' : 'success';
}
}

Copy

<script setup lang="ts">
import { computed } from 'vue';

const props = defineProps<{ usedGb: number; totalGb: number }>();
const color = computed(() => {
const ratio = props.usedGb / props.totalGb;
return ratio >= 0.95 ? 'error' : ratio >= 0.8 ? 'warning' : 'success';
});
</script>

<template>
<md-meter
  :value="usedGb"
  :max="totalGb"
  :color="color"
  label="Storage used"
  :value-text="usedGb + ' GB of ' + totalGb + ' GB'"
  show-label
  show-value
/>
</template>

Copy

<script lang="ts">
export let usedGb = 0;
export let totalGb = 100;
$: ratio = usedGb / totalGb;
$: color = ratio >= 0.95 ? 'error' : ratio >= 0.8 ? 'warning' : 'success';
</script>

<md-meter
value={usedGb}
max={totalGb}
{color}
label="Storage used"
value-text="{usedGb} GB of {totalGb} GB"
show-label
show-value
/>

API Reference

tune

Properties

Property	Attribute	Type	Default	Reflects
value	value	number	0	—
min	min	number	0	—
max	max	number	100	—
label	label	string	''	—
showLabel	show-label	boolean	false	—
showValue	show-value	boolean	false	—
valueText	value-text	string	''	—
locale	locale	string	''	—
formatOptions	JS only	Intl.NumberFormatOptions	—	—
color	color	| 'primary' | 'secondary' | 'tertiary' | 'error' | 'success' | 'warning' | 'info' | (string & {})	'primary'	Yes
variant	variant	'linear' | 'circular'	'linear'	Yes
size	size	number	48	—
thickness	thickness	number	4	—
density	density	0 | -1 | -2 | -3 | -4	0	Yes

palette

CSS Custom Properties

Override on the host element for per-instance theming:

Property	Description
--md-meter-indicator-color	Fill colour (defaults to the `color` role)
--md-meter-track-color	Track background (defaults to the role's container)
--md-meter-track-shape	Track + fill corner radius (default corner-full pill)
--md-meter-height	Track thickness (overrides the `thickness` prop)
--md-meter-label-color	Header label text colour
--md-meter-value-color	Header value text colour
--md-meter-size	Ring diameter (circular variant)

layers

CSS Shadow Parts

Style internal elements through shadow DOM with ::part():

Part	Description
circular	The ring's box (circular variant only)
track	Background track / ring (the full range)
indicator	Value fill inside the track / the value arc
value	Header value text (rendered when `show-value`)
label	Header label text (rendered when `show-label`)

Accessibility

• The host is the single ARIA surface: role="meter", aria-valuemin/aria-valuemax/aria-valuenow (clamped and sanitized), and aria-valuetext carrying the human-readable formatted reading.
• label becomes aria-label — always set it; role="meter" needs an accessible name.
• All internal DOM is aria-hidden, so the visible header value is never announced in addition to aria-valuetext.
• Nothing is focusable and there are no pointer/keyboard behaviours — a meter is a reading, not a control.
• Don’t rely on colour alone for meaning; pair status colours with visible text.

Inspect these three in the accessibility panel: the bar and the ring expose an identical host contract — role="meter", the same aria-valuenow and the same aria-valuetext — because the shape is presentational and the semantics never move into the shadow root. Tab through them and nothing takes focus.

The same ARIA contract on the bar and the ring Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" label="Storage used" show-label show-value></md-meter>
  <md-meter value="3" max="10" label="Seats taken" value-text="3 of 10 seats" show-label show-value></md-meter>
  <md-meter variant="circular" value="65" size="72" label="Storage used" show-value show-label></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter value="65" label="Storage used" showLabel show-value></MdMeter>
        <MdMeter value="3" max="10" label="Seats taken" valueText="3 of 10 seats" showLabel show-value></MdMeter>
        <MdMeter variant="circular" value="65" size="72" label="Storage used" showValue show-label></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" label="Storage used" show-label show-value></md-meter>
  <md-meter value="3" max="10" label="Seats taken" value-text="3 of 10 seats" show-label show-value></md-meter>
  <md-meter variant="circular" value="65" size="72" label="Storage used" show-value show-label></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter value="65" label="Storage used" show-label show-value></md-meter>
    <md-meter value="3" max="10" label="Seats taken" value-text="3 of 10 seats" show-label show-value></md-meter>
    <md-meter variant="circular" value="65" size="72" label="Storage used" show-value show-label></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" label="Storage used" show-label show-value></md-meter>
  <md-meter value="3" max="10" label="Seats taken" value-text="3 of 10 seats" show-label show-value></md-meter>
  <md-meter variant="circular" value="65" size="72" label="Storage used" show-value show-label></md-meter>
</div>

The accessibility story scripts these assertions against the live component.

RTL, density & i18n

RTL — the bar’s geometry is 100% CSS logical properties: the fill anchors to the inline start and grows toward the inline end, so under dir="rtl" the whole meter mirrors with no configuration. The header row swaps with it — label to the right, value to the left. See RTL and the RTL story.

<div dir="rtl">
  <md-meter value="65" label="التخزين المستخدم" locale="ar" show-label show-value></md-meter>
</div>

The same meter in both directions. Nothing is re-authored between the two rows — only dir (and the already-localized label/locale) changes:

Same markup, dir=ltr vs dir=rtl

ltr

rtl

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="max-inline-size:360px;">
    <md-meter value="65" label="Storage used" show-label show-value></md-meter>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="max-inline-size:360px;">
    <md-meter value="65" label="التخزين المستخدم" locale="ar" show-label show-value></md-meter>
  </div>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>ltr</span>
        <div dir="ltr" style={{ maxInlineSize: '360px' }}>
          <MdMeter value="65" label="Storage used" showLabel show-value></MdMeter>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>rtl</span>
        <div dir="rtl" style={{ maxInlineSize: '360px' }}>
          <MdMeter value="65" label="التخزين المستخدم" locale="ar" showLabel show-value></MdMeter>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="max-inline-size:360px;">
    <md-meter value="65" label="Storage used" show-label show-value></md-meter>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="max-inline-size:360px;">
    <md-meter value="65" label="التخزين المستخدم" locale="ar" show-label show-value></md-meter>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
    <div dir="ltr" style="max-inline-size:360px;">
      <md-meter value="65" label="Storage used" show-label show-value></md-meter>
    </div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
    <div dir="rtl" style="max-inline-size:360px;">
      <md-meter value="65" label="التخزين المستخدم" locale="ar" show-label show-value></md-meter>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="max-inline-size:360px;">
    <md-meter value="65" label="Storage used" show-label show-value></md-meter>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="max-inline-size:360px;">
    <md-meter value="65" label="التخزين المستخدم" locale="ar" show-label show-value></md-meter>
  </div>
</div>

The ring does not mirror

The bar flips because it is a box on the inline axis. The ring is a clock face: it fills clockwise from twelve o’clock in every locale, matching Material’s circular progress indicator. Only the centred value and the caption follow the text direction — never add your own scaleX(-1).

The arc starts at twelve o'clock in both directions — only the text flips

ltr

rtl

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
    <md-meter variant="circular" value="65" size="72" label="Storage" show-value show-label></md-meter>
    <md-meter variant="circular" value="92" size="72" color="error" label="Almost full" show-value show-label></md-meter>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
    <md-meter variant="circular" value="65" size="72" label="التخزين" locale="ar" show-value show-label></md-meter>
    <md-meter variant="circular" value="92" size="72" color="error" label="ممتلئ تقريبا" locale="ar" show-value show-label></md-meter>
  </div>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>ltr</span>
        <div dir="ltr" style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'flex-start' }}>
          <MdMeter variant="circular" value="65" size="72" label="Storage" showValue show-label></MdMeter>
          <MdMeter variant="circular" value="92" size="72" color="error" label="Almost full" showValue show-label></MdMeter>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>rtl</span>
        <div dir="rtl" style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'flex-start' }}>
          <MdMeter variant="circular" value="65" size="72" label="التخزين" locale="ar" showValue show-label></MdMeter>
          <MdMeter variant="circular" value="92" size="72" color="error" label="ممتلئ تقريبا" locale="ar" showValue show-label></MdMeter>
        </div>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
    <md-meter variant="circular" value="65" size="72" label="Storage" show-value show-label></md-meter>
    <md-meter variant="circular" value="92" size="72" color="error" label="Almost full" show-value show-label></md-meter>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
    <md-meter variant="circular" value="65" size="72" label="التخزين" locale="ar" show-value show-label></md-meter>
    <md-meter variant="circular" value="92" size="72" color="error" label="ممتلئ تقريبا" locale="ar" show-value show-label></md-meter>
  </div>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
    <div dir="ltr" style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
      <md-meter variant="circular" value="65" size="72" label="Storage" show-value show-label></md-meter>
      <md-meter variant="circular" value="92" size="72" color="error" label="Almost full" show-value show-label></md-meter>
    </div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
    <div dir="rtl" style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
      <md-meter variant="circular" value="65" size="72" label="التخزين" locale="ar" show-value show-label></md-meter>
      <md-meter variant="circular" value="92" size="72" color="error" label="ممتلئ تقريبا" locale="ar" show-value show-label></md-meter>
    </div>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">ltr</span>
  <div dir="ltr" style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
    <md-meter variant="circular" value="65" size="72" label="Storage" show-value show-label></md-meter>
    <md-meter variant="circular" value="92" size="72" color="error" label="Almost full" show-value show-label></md-meter>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rtl</span>
  <div dir="rtl" style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
    <md-meter variant="circular" value="65" size="72" label="التخزين" locale="ar" show-value show-label></md-meter>
    <md-meter variant="circular" value="92" size="72" color="error" label="ممتلئ تقريبا" locale="ar" show-value show-label></md-meter>
  </div>
</div>

Every density rung

density="-1…-4" thins the track (4px down to the 2px floor at -4) and tightens the header spacing and type. Those four rungs locally override an inherited global data-density; density="0" is the default and means “inherit whatever the ancestor says”. All five rungs, both shapes, same meter:

Density 0 through -4 — the bar's track and the ring's diameter both taper Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 24px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" density="0" label="Density 0 — default" show-label show-value></md-meter>
  <md-meter value="65" density="-1" label="Density -1" show-label show-value></md-meter>
  <md-meter value="65" density="-2" label="Density -2" show-label show-value></md-meter>
  <md-meter value="65" density="-3" label="Density -3" show-label show-value></md-meter>
  <md-meter value="65" density="-4" label="Density -4 — 2px floor" show-label show-value></md-meter>
</div>
<div style="display: flex; align-items: flex-start; gap: 28px; flex-wrap: wrap; margin-block-start: 32px;">
  <md-meter variant="circular" value="65" size="72" thickness="6" density="0" label="0" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-1" label="-1" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-2" label="-2" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-3" label="-3" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-4" label="-4" show-value show-label></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '24px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter value="65" density="0" label="Density 0 — default" showLabel show-value></MdMeter>
        <MdMeter value="65" density="-1" label="Density -1" showLabel show-value></MdMeter>
        <MdMeter value="65" density="-2" label="Density -2" showLabel show-value></MdMeter>
        <MdMeter value="65" density="-3" label="Density -3" showLabel show-value></MdMeter>
        <MdMeter value="65" density="-4" label="Density -4 — 2px floor" showLabel show-value></MdMeter>
      </div>
      <div style={{ display: 'flex', alignItems: 'flex-start', gap: '28px', flexWrap: 'wrap', marginBlockStart: '32px' }}>
        <MdMeter variant="circular" value="65" size="72" thickness="6" density="0" label="0" showValue show-label></MdMeter>
        <MdMeter variant="circular" value="65" size="72" thickness="6" density="-1" label="-1" showValue show-label></MdMeter>
        <MdMeter variant="circular" value="65" size="72" thickness="6" density="-2" label="-2" showValue show-label></MdMeter>
        <MdMeter variant="circular" value="65" size="72" thickness="6" density="-3" label="-3" showValue show-label></MdMeter>
        <MdMeter variant="circular" value="65" size="72" thickness="6" density="-4" label="-4" showValue show-label></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; flex-direction: column; gap: 24px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" density="0" label="Density 0 — default" show-label show-value></md-meter>
  <md-meter value="65" density="-1" label="Density -1" show-label show-value></md-meter>
  <md-meter value="65" density="-2" label="Density -2" show-label show-value></md-meter>
  <md-meter value="65" density="-3" label="Density -3" show-label show-value></md-meter>
  <md-meter value="65" density="-4" label="Density -4 — 2px floor" show-label show-value></md-meter>
</div>
<div style="display: flex; align-items: flex-start; gap: 28px; flex-wrap: wrap; margin-block-start: 32px;">
  <md-meter variant="circular" value="65" size="72" thickness="6" density="0" label="0" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-1" label="-1" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-2" label="-2" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-3" label="-3" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-4" label="-4" show-value show-label></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 24px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter value="65" density="0" label="Density 0 — default" show-label show-value></md-meter>
    <md-meter value="65" density="-1" label="Density -1" show-label show-value></md-meter>
    <md-meter value="65" density="-2" label="Density -2" show-label show-value></md-meter>
    <md-meter value="65" density="-3" label="Density -3" show-label show-value></md-meter>
    <md-meter value="65" density="-4" label="Density -4 — 2px floor" show-label show-value></md-meter>
  </div>
  <div style="display: flex; align-items: flex-start; gap: 28px; flex-wrap: wrap; margin-block-start: 32px;">
    <md-meter variant="circular" value="65" size="72" thickness="6" density="0" label="0" show-value show-label></md-meter>
    <md-meter variant="circular" value="65" size="72" thickness="6" density="-1" label="-1" show-value show-label></md-meter>
    <md-meter variant="circular" value="65" size="72" thickness="6" density="-2" label="-2" show-value show-label></md-meter>
    <md-meter variant="circular" value="65" size="72" thickness="6" density="-3" label="-3" show-value show-label></md-meter>
    <md-meter variant="circular" value="65" size="72" thickness="6" density="-4" label="-4" show-value show-label></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 24px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" density="0" label="Density 0 — default" show-label show-value></md-meter>
  <md-meter value="65" density="-1" label="Density -1" show-label show-value></md-meter>
  <md-meter value="65" density="-2" label="Density -2" show-label show-value></md-meter>
  <md-meter value="65" density="-3" label="Density -3" show-label show-value></md-meter>
  <md-meter value="65" density="-4" label="Density -4 — 2px floor" show-label show-value></md-meter>
</div>
<div style="display: flex; align-items: flex-start; gap: 28px; flex-wrap: wrap; margin-block-start: 32px;">
  <md-meter variant="circular" value="65" size="72" thickness="6" density="0" label="0" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-1" label="-1" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-2" label="-2" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-3" label="-3" show-value show-label></md-meter>
  <md-meter variant="circular" value="65" size="72" thickness="6" density="-4" label="-4" show-value show-label></md-meter>
</div>

Below -2, check legibility rather than hit area

Nothing here is focusable, so density costs no touch target — it costs readability. The track bottoms out at 2px, the ring at 24px, and the centred value is sized off the diameter (~26% of it), so a tapered ring stops being able to hold its own number long before it stops being drawn. Drop show-value on the small rungs and let label carry the reading. See Density.

Density and direction together

The two are independent signals, so they compose without any extra wiring — and a local density="-1…-4" still wins over the inherited rung. Going the other way — back out of an inherited rung — needs the custom property rather than density="0", so the last meter below sets --md-sys-density-scale: 0 inline:

dir=rtl with data-density=-2: one meter pinned locally to -4, one reset to the default rung with --md-sys-density-scale

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div dir="rtl" data-density="-2" style="display:flex;flex-direction:column;gap:20px;max-inline-size:360px;">
  <md-meter value="45" color="success" label="التخزين المستخدم" locale="ar" show-label show-value></md-meter>
  <md-meter value="82" color="warning" label="الحصة المستخدمة" locale="ar" show-label show-value></md-meter>
  <md-meter value="96" color="error" density="-4" label="كثافة -4 محليا" locale="ar" show-label show-value></md-meter>
  <md-meter value="30" label="إعادة الضبط إلى الرقم صفر" locale="ar" style="--md-sys-density-scale: 0;" show-label show-value></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div dir="rtl" data-density="-2" style={{ display: 'flex', flexDirection: 'column', gap: '20px', maxInlineSize: '360px' }}>
        <MdMeter value="45" color="success" label="التخزين المستخدم" locale="ar" showLabel show-value></MdMeter>
        <MdMeter value="82" color="warning" label="الحصة المستخدمة" locale="ar" showLabel show-value></MdMeter>
        <MdMeter value="96" color="error" density="-4" label="كثافة -4 محليا" locale="ar" showLabel show-value></MdMeter>
        <MdMeter value="30" label="إعادة الضبط إلى الرقم صفر" locale="ar" style={{ '--md-sys-density-scale': '0' }} showLabel show-value></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div dir="rtl" data-density="-2" style="display:flex;flex-direction:column;gap:20px;max-inline-size:360px;">
  <md-meter value="45" color="success" label="التخزين المستخدم" locale="ar" show-label show-value></md-meter>
  <md-meter value="82" color="warning" label="الحصة المستخدمة" locale="ar" show-label show-value></md-meter>
  <md-meter value="96" color="error" density="-4" label="كثافة -4 محليا" locale="ar" show-label show-value></md-meter>
  <md-meter value="30" label="إعادة الضبط إلى الرقم صفر" locale="ar" style="--md-sys-density-scale: 0;" show-label show-value></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div dir="rtl" data-density="-2" style="display:flex;flex-direction:column;gap:20px;max-inline-size:360px;">
    <md-meter value="45" color="success" label="التخزين المستخدم" locale="ar" show-label show-value></md-meter>
    <md-meter value="82" color="warning" label="الحصة المستخدمة" locale="ar" show-label show-value></md-meter>
    <md-meter value="96" color="error" density="-4" label="كثافة -4 محليا" locale="ar" show-label show-value></md-meter>
    <md-meter value="30" label="إعادة الضبط إلى الرقم صفر" locale="ar" style="--md-sys-density-scale: 0;" show-label show-value></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div dir="rtl" data-density="-2" style="display:flex;flex-direction:column;gap:20px;max-inline-size:360px;">
  <md-meter value="45" color="success" label="التخزين المستخدم" locale="ar" show-label show-value></md-meter>
  <md-meter value="82" color="warning" label="الحصة المستخدمة" locale="ar" show-label show-value></md-meter>
  <md-meter value="96" color="error" density="-4" label="كثافة -4 محليا" locale="ar" show-label show-value></md-meter>
  <md-meter value="30" label="إعادة الضبط إلى الرقم صفر" locale="ar" style="--md-sys-density-scale: 0;" show-label show-value></md-meter>
</div>

density="0" means “inherit”, not “reset”

There is deliberately no [density="0"] rule in the token layer or in md-meter.css — density is a reflected prop, so density="0" is written onto virtually every element, and a rule for it would pin rung 0 everywhere and break global inheritance outright. Only -1…-4 declare --md-sys-density-scale on the host. A meter inside data-density="-2" therefore stays at -2 even with density="0" on it — it renders pixel-identical to its neighbours. To opt back out, set the custom property the rungs feed, style="--md-sys-density-scale: 0", which beats both the inherited value and the :host([density=…]) rules; or drop the ancestor’s data-density altogether.

Density — density="-1…-4" locally overrides the inherited data-density rung (0 inherits it); on the ring it shrinks the whole circle 2px per rung (floored at 24px) so radius and stroke stay in proportion. See the Density story and Density.

i18n — label and value-text are plain text props: resolve them in your i18n layer. locale + formatOptions cover the Intl side — digits, separators, percent signs, units and currencies all follow the locale. See the Localization story.

Theming

Custom property	Purpose	Default
--md-meter-indicator-color	Fill colour	The color role (primary)
--md-meter-track-color	Track background	The role’s container (secondary-container)
--md-meter-track-shape	Track + fill corner radius	--md-sys-shape-corner-full
--md-meter-height	Track thickness	thickness prop (4px, density-scaled)
--md-meter-size	Ring diameter (circular only)	size prop (48px, density-scaled)
--md-meter-label-color	Header label text	--md-sys-color-on-surface
--md-meter-value-color	Header value text	--md-sys-color-on-surface-variant

Custom-property overrides Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" label="Brand colours" style="--md-meter-indicator-color: #6200ee; --md-meter-track-color: #e0d4f5;"></md-meter>
  <md-meter value="65" label="Square corners" style="--md-meter-track-shape: 2px;"></md-meter>
  <md-meter value="65" label="Tall track" style="--md-meter-height: 12px;"></md-meter>
  <md-meter variant="circular" value="65" label="Bigger ring" show-value style="--md-meter-size: 96px;"></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter value="65" label="Brand colours" style={{ '--md-meter-indicator-color': '#6200ee', '--md-meter-track-color': '#e0d4f5' }}></MdMeter>
        <MdMeter value="65" label="Square corners" style={{ '--md-meter-track-shape': '2px' }}></MdMeter>
        <MdMeter value="65" label="Tall track" style={{ '--md-meter-height': '12px' }}></MdMeter>
        <MdMeter variant="circular" value="65" label="Bigger ring" showValue style={{ '--md-meter-size': '96px' }}></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" label="Brand colours" style="--md-meter-indicator-color: #6200ee; --md-meter-track-color: #e0d4f5;"></md-meter>
  <md-meter value="65" label="Square corners" style="--md-meter-track-shape: 2px;"></md-meter>
  <md-meter value="65" label="Tall track" style="--md-meter-height: 12px;"></md-meter>
  <md-meter variant="circular" value="65" label="Bigger ring" show-value style="--md-meter-size: 96px;"></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter value="65" label="Brand colours" style="--md-meter-indicator-color: #6200ee; --md-meter-track-color: #e0d4f5;"></md-meter>
    <md-meter value="65" label="Square corners" style="--md-meter-track-shape: 2px;"></md-meter>
    <md-meter value="65" label="Tall track" style="--md-meter-height: 12px;"></md-meter>
    <md-meter variant="circular" value="65" label="Bigger ring" show-value style="--md-meter-size: 96px;"></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter value="65" label="Brand colours" style="--md-meter-indicator-color: #6200ee; --md-meter-track-color: #e0d4f5;"></md-meter>
  <md-meter value="65" label="Square corners" style="--md-meter-track-shape: 2px;"></md-meter>
  <md-meter value="65" label="Tall track" style="--md-meter-height: 12px;"></md-meter>
  <md-meter variant="circular" value="65" label="Bigger ring" show-value style="--md-meter-size: 96px;"></md-meter>
</div>

CSS parts — track, indicator, label, value, and circular (the ring’s box). track and indicator name the bar’s two divs on the linear variant and the two SVG circles on the circular one, so one ::part() rule survives a variant swap. Use them for what a colour token cannot express — gradients, opacity, filters:

::part() reaching into the shadow root Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html — register the AWC UI elements once -->
<script type="module">
  import '@awc-ui/core/define';
</script>

<style>
  .meter-gradient::part(indicator) { background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8); }
  .meter-subtle::part(track)       { opacity: 0.35; }
  .meter-strong::part(label)       { font-weight: 700; text-transform: uppercase; letter-spacing: .08em; }
  .meter-boxed::part(value) {
  padding: 1px 6px;
  border-radius: 6px;
  background: var(--md-sys-color-secondary-container);
  color: var(--md-sys-color-on-secondary-container);
  }
</style>
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter class="meter-gradient" value="65" label="Gradient indicator" show-label show-value></md-meter>
  <md-meter class="meter-subtle" value="40" label="Faded track" show-label show-value></md-meter>
  <md-meter class="meter-strong meter-boxed" value="65" label="Styled label and value" show-label show-value></md-meter>
</div>

Copy

import { MdMeter } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <style>
        .meter-gradient::part(indicator) { background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8); }
        .meter-subtle::part(track)       { opacity: 0.35; }
        .meter-strong::part(label)       { font-weight: 700; text-transform: uppercase; letter-spacing: .08em; }
        .meter-boxed::part(value) {
        padding: 1px 6px;
        border-radius: 6px;
        background: var(--md-sys-color-secondary-container);
        color: var(--md-sys-color-on-secondary-container);
        }
      </style>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '20px', inlineSize: '100%', maxInlineSize: '360px' }}>
        <MdMeter className="meter-gradient" value="65" label="Gradient indicator" showLabel show-value></MdMeter>
        <MdMeter className="meter-subtle" value="40" label="Faded track" showLabel show-value></MdMeter>
        <MdMeter className="meter-strong meter-boxed" value="65" label="Styled label and value" showLabel show-value></MdMeter>
      </div>
    </>
  );
}

Copy

// app.module.ts — register the AWC UI elements once
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AwcUiModule } from '@awc-ui/angular';

@NgModule({
  imports: [AwcUiModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

<!-- app.component.html -->
<style>
  .meter-gradient::part(indicator) { background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8); }
  .meter-subtle::part(track)       { opacity: 0.35; }
  .meter-strong::part(label)       { font-weight: 700; text-transform: uppercase; letter-spacing: .08em; }
  .meter-boxed::part(value) {
  padding: 1px 6px;
  border-radius: 6px;
  background: var(--md-sys-color-secondary-container);
  color: var(--md-sys-color-on-secondary-container);
  }
</style>
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter class="meter-gradient" value="65" label="Gradient indicator" show-label show-value></md-meter>
  <md-meter class="meter-subtle" value="40" label="Faded track" show-label show-value></md-meter>
  <md-meter class="meter-strong meter-boxed" value="65" label="Styled label and value" show-label show-value></md-meter>
</div>

Copy

<script setup>
import '@awc-ui/core/define';
</script>

<template>
  <style>
    .meter-gradient::part(indicator) { background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8); }
    .meter-subtle::part(track)       { opacity: 0.35; }
    .meter-strong::part(label)       { font-weight: 700; text-transform: uppercase; letter-spacing: .08em; }
    .meter-boxed::part(value) {
    padding: 1px 6px;
    border-radius: 6px;
    background: var(--md-sys-color-secondary-container);
    color: var(--md-sys-color-on-secondary-container);
    }
  </style>
  <div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
    <md-meter class="meter-gradient" value="65" label="Gradient indicator" show-label show-value></md-meter>
    <md-meter class="meter-subtle" value="40" label="Faded track" show-label show-value></md-meter>
    <md-meter class="meter-strong meter-boxed" value="65" label="Styled label and value" show-label show-value></md-meter>
  </div>
</template>

Copy

<script>
  import '@awc-ui/core/define';
</script>

<style>
  .meter-gradient::part(indicator) { background: linear-gradient(to right, #1a237e, #7c4dff, #ce93d8); }
  .meter-subtle::part(track)       { opacity: 0.35; }
  .meter-strong::part(label)       { font-weight: 700; text-transform: uppercase; letter-spacing: .08em; }
  .meter-boxed::part(value) {
  padding: 1px 6px;
  border-radius: 6px;
  background: var(--md-sys-color-secondary-container);
  color: var(--md-sys-color-on-secondary-container);
  }
</style>
<div style="display: flex; flex-direction: column; gap: 20px; inline-size: 100%; max-inline-size: 360px;">
  <md-meter class="meter-gradient" value="65" label="Gradient indicator" show-label show-value></md-meter>
  <md-meter class="meter-subtle" value="40" label="Faded track" show-label show-value></md-meter>
  <md-meter class="meter-strong meter-boxed" value="65" label="Styled label and value" show-label show-value></md-meter>
</div>

Check any override in both themes — the dark-theme story is the counterpart to the stories above.

Related

md-progress-indicator · md-loading-indicator · md-slider · md-rating · md-status-dot · md-badge

AI / LLM Context

For AI Agents — md-meter

Two artefacts to give your AI agent so it generates correct UI with this component. The per-component spec answers "how do I use this exact tag?". The main-llm spec answers "which tag should I pick in the first place?".

Per-component

md-meter spec card

Identity · when to use / when NOT · decision cues · behavioural contract · do/don't · anti-patterns · full API. Paste into your agent when you're implementing with this component.

Copy specExpand view

Main-LLM spec

AWC UI Operator's Manual

System-prompt preamble · decision matrix · token reference · page recipes · anti-patterns. Paste into the system prompt at the start of a piece of work.

Open specExpand view

md-meter readme.md

Copy readme

# md-meter

<!-- llm:meta
tag: md-meter
category: status
status: custom
m3-guidelines: none — M3 has no meter page
m3-derived-from: https://m3.material.io/components/progress-indicators/guidelines
form-associated: false
depends-on: none
used-by: none
-->

**A read-only graphical display of a numeric value within a known range.**
Storage used, quota consumed, password strength, battery level. `role="meter"`
with the full ARIA value contract on the host, value clamping, Intl-driven
formatting (locale-aware percent by default), and MD3 semantic status colors.

> ⚠️ **Not a Material Design 3 component.** M3 has progress indicators, not
> meters; the Do/Don't below is house rules derived from the progress-indicator
> guidance plus native `<meter>` semantics.

> Setup, theming, density and i18n are configured once for the whole library —
> see [`main-llm.md`](../../../../../main-llm.md) at the repo root. Quick start:
> `import '@awc-ui/core/define';`

---

## When to use

- A **current state** within a known range: disk/storage usage, quota, capacity.
- A **strength or level reading**: password strength, signal, battery.
- Anywhere native `<meter>` semantics fit but you want MD3 visuals and theming.
- The same reading **as a ring** — a dashboard tile, a card corner, a compact
  status dot with a number in it — via `variant="circular"`.

## When NOT to use

| Situation | Use instead |
|---|---|
| Showing how far along an **activity** is (upload, install, load) | `md-progress-indicator` — determinate |
| An unknown-length wait | `md-loading-indicator` or indeterminate `md-progress-indicator` |
| The user should **change** the value | `md-slider` |
| A star/score the user assigns | `md-rating` |
| A tiny binary/status signal | `md-status-dot` or `md-badge` |

**Meter vs progress indicator** is the load-bearing distinction: a meter shows a
*state* ("how full"), a progress indicator shows an *activity* ("how far
along"). That is why md-meter deliberately has **no** indeterminate mode, no
4px expressive gap, no stop dot, and no completion animation — it is a plain
track + fill that sits still.

## Decision cues

Pick the **shape** by the space, not the meaning — both variants read the same
value and carry identical semantics.

| Situation | Setting |
|---|---|
| Reading sits under a label, full container width | `variant="linear"` (default) |
| Reading is a tile / card headline / dashboard cell | `variant="circular"` |
| Ring needs to be bigger or smaller than 48px | `size="24…240"` |
| Value should be readable inside the ring | `show-value` (centres it) |
| Ring needs a caption | `show-label` (sits underneath) |
| Ring is decorative-small (no room for text) | omit both; `label` still names it for AT |

Pick `color` by what the reading means. Any theme-defined role name works
(`color="brand"` resolves `--md-sys-color-brand` / `-brand-container`).

| Reading | `color` |
|---|---|
| Neutral measurement | `primary` (default — primary fill on secondary-container track) |
| Healthy / plenty left | `success` |
| Approaching the limit | `warning` |
| Critical / exceeded | `error` |
| Informational level | `info` |

## API contract

The full property table is at the bottom of this file. This is the short form an
implementer needs.

```html
<md-meter
  value="24"                          <!-- default: 0 -->
  min="0"                             <!-- default: 0 -->
  max="100"                           <!-- default: 100 -->
  label="Storage used"                <!-- accessible name; header text -->
  show-label show-value               <!-- optional; both default false -->
  value-text="24 GB of 100 GB"        <!-- overrides the formatted value text -->
  locale="de-DE"                      <!-- Intl locale for the value text -->
  color="primary|secondary|tertiary|error|success|warning|info|<any-role>"
                                      <!-- default: primary -->
  thickness="4"                       <!-- track dp; density-scaled, floor 2px -->
  variant="linear|circular"           <!-- default: linear -->
  size="48"                           <!-- ring diameter dp; circular only, 24-240 -->
  density="-1|-2|-3|-4"               <!-- default: 0 (uncompacted) -->
></md-meter>

<!-- The ring: value in the middle, label captioned underneath -->
<md-meter variant="circular" value="72" size="96" thickness="8"
          label="Storage used" show-label show-value></md-meter>
```

```js
// formatOptions is a JS-only object prop (no attribute):
meter.formatOptions = { style: 'unit', unit: 'gigabyte' };
```

**Events** — none. **Methods** — none. Nothing is focusable or interactive.

**Slots** — none; the component renders no `<slot>`. `label` is a text prop so
your i18n layer resolves it.

**Parts** — `track`, `indicator`, `label`, `value`, and `circular` (the ring's
box). `track` / `indicator` are the bar's two divs on the linear variant and the
two SVG circles on the circular one — the same names, so a consumer's
`::part(indicator)` rule keeps working across a variant swap.

### Behavioral contract worth knowing

- `value` is **clamped** into `[min, max]` before ARIA, geometry, and
  formatting — `value="150"` renders and announces 100%. An inverted range
  (`max < min`) collapses to an empty one rather than emitting invalid ARIA,
  and non-finite inputs fall back to `min` / `0` / `100`.
- Default value text is the value's **position in the range** as a locale-aware
  percentage, not the raw number — a reading is only meaningful against its
  bounds: value 24 in 0–100 → "24%"; value 150 in 100–200 → "50%".
- `formatOptions` switches formatting to the **clamped raw value** through
  `Intl.NumberFormat` (units, currency, plain numbers). It is a **JS-only
  object prop** — an HTML attribute will not parse. Invalid option combinations
  degrade to the raw value instead of throwing.
- `value-text` overrides both `aria-valuetext` and the visible header value —
  one string drives what is seen and what is announced, so they can never
  disagree.
- The visible header value is `aria-hidden`; screen readers get the host's
  `aria-valuetext` exactly once.
- `color` is guarded: values that are not a plain CSS ident are ignored (the
  name is interpolated into a custom-property name). Unknown-but-valid role
  names degrade to the neutral primary look.
- Value changes animate the fill (300ms standard easing); the transition is
  removed under `prefers-reduced-motion`. The ring animates
  `stroke-dashoffset` — a single number, so it interpolates; the arc is drawn
  on a `pathLength="1"` circle so the fill IS the fraction, with no
  circumference arithmetic to redo whenever size or thickness changes.
- **`variant="circular"` replaces the header row**, it does not add to it:
  `show-value` renders the value inside the ring, `show-label` captions it
  underneath. Only one element ever carries `part="track"`.
- `size` is **clamped to 24–240px** (md-progress-indicator's band) and ignored
  entirely by the bar. Density tapers the whole ring (2px/rung) rather than the
  stroke alone, so radius and stroke stay in proportion.
- The centred ring value is sized at 26% of the diameter, so a small ring
  cannot hold a long reading.
- The stroke straddles the radius, so the drawn circle is always
  `size − thickness` across — budget for that when aligning a ring to
  neighbouring content.
- The ring **does not mirror under `dir="rtl"`** — it fills clockwise from
  twelve o'clock in every locale, matching Material's circular progress
  indicator. Only the caption's text direction flips.
- At `value` = min the arc is hidden outright, so its round cap can't leave a
  stray dot on an empty ring.

---

## Do / Don't

House rules, informed by [M3 · Progress indicators · Guidelines](https://m3.material.io/components/progress-indicators/guidelines)
and by native `<meter>` semantics.

| ✅ Do | ❌ Don't |
|---|---|
| Pick the shape by the space — bar in a column of labelled rows, ring as a tile's focal point | Don't show the same reading as both a bar and a ring on one screen — it reads as two measurements |
| Let one element carry the reading: `show-value` (+ `value-text`) | Don't pair the meter with your own `<span>` of the same number — the two will drift |
| Size the ring for its text; drop `show-value` below ~40px | Don't cram "45 GB of 100 GB" into a 24px ring |
| Treat `thickness` as legibility: thicken it (6–8px) as the ring grows | Don't leave a hairline arc on a large ring, or a fat one that closes a small ring's hole |
| Pair threshold colour with visible text or a label | Don't let a red ring be the only signal — that fails WCAG 1.4.1 |
| Pass `color` a theme **role name** | Don't pass a raw CSS colour — use `--md-meter-indicator-color` for that |
| Fix the range when a reading can exceed it | Don't try to render the overflow; `value` is clamped |
| Let the built-in 300ms fill transition run | Don't animate `inline-size` / `stroke-dashoffset` from outside — you'll fight the component |
| Leave the ring's clockwise fill alone in RTL | Don't add your own `scaleX(-1)` — Material's circular progress doesn't mirror either |
| Always set `label` | Don't ship a `role="meter"` with no accessible name |

---

## Patterns

```html
<!-- Ring, sized and captioned -->
<md-meter variant="circular" label="Storage used" value="72" size="96" thickness="8"
          show-label show-value></md-meter>

<!-- Compact ring with no text at all (the label still names it for AT) -->
<md-meter variant="circular" label="Battery" value="41" size="24" thickness="3"></md-meter>

<!-- Storage quota with visible header -->
<md-meter label="Storage used" value="65" show-label show-value></md-meter>

<!-- Status-colored quota (switch the role as thresholds are crossed) -->
<md-meter label="Storage used" value="96" color="error" show-label show-value></md-meter>

<!-- Fully custom reading -->
<md-meter label="Seats taken" max="10" value="3" value-text="3 of 10 seats"
          show-label show-value></md-meter>
```

```html
<!-- Absolute reading instead of percent: formatOptions is a JS property -->
<md-meter id="gb" label="Storage used" value="256" max="512"
          show-label show-value></md-meter>

<script type="module">
  const gb = document.getElementById('gb');
  gb.formatOptions = { style: 'unit', unit: 'gigabyte' };
</script>
```

```html
<!-- Threshold colours: swap the role as the reading crosses a boundary -->
<md-meter id="quota" label="Storage used" max="512" show-label show-value></md-meter>

<script type="module">
  const quota = document.getElementById('quota');

  function setUsage(gigabytes) {
    quota.value = gigabytes;
    const pct = (gigabytes / quota.max) * 100;
    quota.color = pct >= 95 ? 'error' : pct >= 80 ? 'warning' : 'success';
    // The label keeps the state available as words, not colour alone.
    quota.label = `Storage used — ${pct >= 95 ? 'full' : pct >= 80 ? 'nearly full' : 'healthy'}`;
  }

  setUsage(410);
</script>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| md-meter for an upload/install | `md-progress-indicator` | A meter is a state, not an activity; it has no indeterminate fallback. |
| Omitting `label` | Always set `label` | `role="meter"` needs an accessible name. |
| A second visible value element you maintain yourself | `show-value` (+ `value-text` if needed) | The built-in value can never drift from `aria-valuetext`. |
| `format-options='{"style":"percent"}'` as an attribute | `el.formatOptions = { … }` in JS | Objects don't cross the attribute boundary. |
| `color="#ff0000"` | A role name, or `--md-meter-indicator-color` | `color` takes theme role *names*, not CSS colors. |
| Expecting `value="150"` to overflow the track | It clamps to `max` | A reading past `max` means the range is wrong, not the meter. |
| `variant="circular"` + expecting the header row | The value goes in the middle, the label underneath | The header is the bar's layout. |
| Mirroring the ring yourself for RTL | Leave it | Material's circular progress doesn't mirror; a clock face doesn't either. |
| `size` on the linear variant | `thickness` (bar) / `size` (ring) | The bar is full-width by design. |
| Listening for a change event | Read the value you set | The meter emits no events. |

## Accessibility, RTL, density, i18n

**Accessibility** — the host carries `role="meter"`, `aria-valuemin/max/now`
(clamped/sanitized), `aria-valuetext` (the formatted reading), and `aria-label`
from `label`. All internal DOM is `aria-hidden`. Nothing is focusable — a meter
is not a control. Color is never the only signal: pair status colors with the
visible value or label text.

**RTL** — the bar's geometry is 100% logical properties; the fill anchors to the
inline start and mirrors for free under `dir="rtl"`. The **ring deliberately does
not mirror**: it fills clockwise from twelve o'clock in every locale (Material's
circular progress behaves the same). Only its caption text flips.

**Density** — `density="-1…-4"` locally overrides the inherited `data-density`
rung: it thins the track (4px → 2px floor), tightens the header spacing and
type, and on the ring shrinks the whole circle 2px per rung (floored at 24px) so
radius and stroke stay in proportion. Rung `0` is the uncompacted default and is
inert — it does **not** opt a meter out of an inherited rung; for that, set
`style="--md-sys-density-scale: 0"` on the element.

**i18n** — `label` and `value-text` are plain text props (resolve them in your
i18n layer). `locale` + `formatOptions` exist only for Intl-computed value
output — digits, separators, percent signs, units and currencies follow the
locale.

## Related components

`md-progress-indicator` · `md-loading-indicator` · `md-slider` · `md-rating` ·
`md-status-dot` · `md-badge`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-meter-indicator-color` | Fill color | The `color` role (`--md-sys-color-primary` by default) |
| `--md-meter-track-color` | Track background | The role's container (`--md-sys-color-secondary-container` by default) |
| `--md-meter-track-shape` | Track + fill corner radius | `--md-sys-shape-corner-full` |
| `--md-meter-height` | Track thickness | The `thickness` prop (4px, density-scaled, floor 2px) |
| `--md-meter-size` | Ring diameter (circular only) | The `size` prop (48px, density-scaled, floor 24px) |
| `--md-meter-label-color` | Header / caption label text | `--md-sys-color-on-surface` |
| `--md-meter-value-color` | Header / centre value text | `--md-sys-color-on-surface-variant` |

**CSS parts** — `track`, `indicator`, `label`, `value`, `circular`.

```css
md-meter.quota-warning {
  --md-meter-indicator-color: var(--md-sys-color-warning);
  --md-meter-track-color: var(--md-sys-color-warning-container);
}
```

<!-- Auto Generated Below -->

## Properties

| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
| `value` | `value` | Current value. Clamped into `[min, max]` for ARIA, geometry and formatting. | `number` | `0` |
| `min` | `min` | Lower bound of the range. | `number` | `0` |
| `max` | `max` | Upper bound of the range. Never below `min` — an inverted range collapses to an empty one. | `number` | `100` |
| `label` | `label` | Accessible name (`aria-label`). Also the visible label when `show-label` is set. Pass already-localized text. | `string` | `''` |
| `showLabel` | `show-label` | Render `label` — in the header row (linear) or as a caption under the ring (circular). | `boolean` | `false` |
| `showValue` | `show-value` | Render the formatted value — end-aligned in the header row (linear) or centred in the ring (circular). The visible span is `aria-hidden`; AT reads `aria-valuetext` instead. | `boolean` | `false` |
| `valueText` | `value-text` | Overrides the formatted value entirely — both `aria-valuetext` and the visible value. | `string` | `''` |
| `locale` | `locale` | BCP-47 locale for `Intl.NumberFormat` output. Empty = the runtime default. Intl-computed output only; translatable copy goes through `label`. | `string` | `''` |
| `formatOptions` | — | `Intl.NumberFormatOptions` for the value text. **JS-only object prop** — set it as a property, not an attribute. Omitted = locale-aware percent of the range. | `Intl.NumberFormatOptions \| undefined` | `undefined` |
| `color` | `color` | Theme colour role for fill + track. Any role the theme defines works — `<name>` resolves to `--md-sys-color-<name>` / `-<name>-container`. Non-ident values are ignored. | `'primary' \| 'secondary' \| 'tertiary' \| 'error' \| 'success' \| 'warning' \| 'info' \| string` | `'primary'` |
| `variant` | `variant` | Shape of the reading: a horizontal bar, or a ring with the value centred and the label captioned beneath. Reflected. | `'linear' \| 'circular'` | `'linear'` |
| `size` | `size` | Ring diameter in dp — **circular only**, ignored by the bar. Clamped to 24–240. | `number` | `48` |
| `thickness` | `thickness` | Track / stroke thickness in dp. Density-scaled (0.5px per rung), floored at 2px. | `number` | `4` |
| `density` | `density` | Local density rung, overriding an inherited global `data-density`. 0 = default, -4 = ultra-compact. Reflected. | `0 \| -1 \| -2 \| -3 \| -4` | `0` |

## Events

None. A meter is a read-only display — drive it by setting `value`.

## Methods

None. Nothing here is focusable or interactive.

## Slots

None. `label` is a text prop so your i18n layer resolves it.

## Shadow Parts

| Part | On | Element |
|---|---|---|
| `track` | both | The full range — a div (linear) or the background circle (circular) |
| `indicator` | both | The value fill — a div (linear) or the value arc (circular) |
| `label` | both | Label text: header row (linear) or caption under the ring (circular) |
| `value` | both | Formatted value: header row (linear) or ring centre (circular) |
| `circular` | circular | The ring's box, wrapping the SVG and the centred value |

## Dependencies

None — `md-meter` renders no other AWC UI component.

AWC UI Operator’s Manual

Copy spec

# main-llm.md — AWC UI build director

<!-- llm:meta
role: director
audience: llm
library: "@awc-ui/core"
component-count: 57
sub-component-count: 24
manual-count: 81
per-component-docs: ./packages/core/src/components/<tag>/readme.md
-->

**You are building a web app with AWC UI, a Material Design 3 web-component
library.** This file is the entry point and the only document you need before
writing UI code. Everything here is self-contained: tokens, recipes,
composition rules and the ship checklist. Per-component detail lives in
`./packages/core/src/components/<tag>/readme.md` — e.g.
[`md-button`](./packages/core/src/components/md-button/readme.md).

Your job, in order:

1. **Interview** the user (§1). Do not skip it and do not guess.
2. **Lock the configuration** their answers imply (§2) and bootstrap it (§3–§4).
3. **Route every UI need through the decision matrix** (§5) — never pick a
   component by name-similarity.
4. **Load the component's readme.md before writing a single line of its
   markup** (§6). The file is
   `./packages/core/src/components/<tag>/readme.md` — read it in full, do not
   skim it, and do not write the markup from memory of a similar library. Each
   one has a `When NOT to use`, a `Do / Don't` table sourced from
   [m3.material.io](https://m3.material.io), and an `Anti-patterns` table of
   mistakes models actually make. If you are about to use three components,
   load all three readmes first.
5. **Check what nests inside what** (§7) and start from a recipe (§8) rather
   than from a blank page.
6. **Apply the universal rules** (§9) — the API, content and accessibility
   rules every component is bound by, and the ones §10 checks you against.
7. **Run the ship checklist** (§10) before declaring done.

**Fail closed.** If you cannot satisfy a step — no component fits, a token
doesn't exist, an accessible name has nowhere to come from — say so and ask.
Do not invent an `md-*` tag, a prop, or a token. If it is not in this file or
in the component's manual, it does not exist.

---

## §1 — Interview the user

Ask these **one at a time**, in this order. Each answer closes off decisions
downstream, so don't batch them into a wall of questions. Skip a question only
if the user has already answered it unprompted.

If the user says "just pick sensible defaults", use the **bold** option and tell
them what you chose.

### 1.1 Scope and shape

1. **What is the app?** One or two sentences — domain, primary job, who uses it.
2. **What kind of surface is it?**
   - Internal tool / admin console / dashboard
   - Data-heavy CRUD application
   - Consumer-facing product
   - Marketing or content site
   - Mobile-first / PWA
3. **Which framework?** React · Angular · Vue · Svelte · **plain HTML** ·
   Next · Nuxt · SvelteKit · Astro
4. **Does it server-render?** (SSR/SSG, or **client-only SPA**)
5. **Roughly how many distinct screens**, and what are the top 3?

### 1.2 Look and feel

6. **Density** — how much information per screen?
   - `0` — **default**, comfortable, touch-friendly
   - `-1` / `-2` — compact; typical for admin consoles
   - `-3` / `-4` — ultra-compact; dense data tables, trading/ops screens
7. **Theme** — light only, dark only, or **both with a user toggle**?
   Does it follow the OS preference?
8. **Brand color** — a seed/primary color, or **stock MD3 palette**?
9. **Expressive motion** — keep **ripple and shape-morph on** (default), or turn
   them off for a flatter, more utilitarian feel?
10. **Shape language** — **rounded** (MD3 default) or squared?

### 1.3 Internationalization

11. **How many locales**, and which?
12. **Any RTL locales** (Arabic, Hebrew, Farsi, Urdu)? — this changes layout
    verification and directional-icon handling.
13. **Which i18n engine?** (i18next, vue-i18n, ngx-translate, Paraglide, custom)
    Components are engine-agnostic — you localize in the consumer layer.
14. **Locale-formatted values** — dates, numbers, currency? Which locale drives
    `Intl`?

### 1.4 Data and forms

15. **Is there significant tabular data?** How many rows, and is it
    server-paged? (Drives how you page `md-table` — it holds the state, you
    supply each page of rows.)
16. **Are there charts?** Which questions should they answer?
17. **How heavy are the forms?** Validation rules, async validation, multi-step?
18. **Rich text editing anywhere?** — ⚠️ **AWC UI has no RTE component.** If yes,
    you must integrate a third-party editor (TipTap, Lexical, Quill) and style
    it to the MD3 tokens yourself. Confirm this with the user explicitly.

### 1.5 Constraints

19. **Accessibility target** — **WCAG 2.1 AA** (what the library is tested to),
    or stricter?
20. **Browser/device support floor?**
21. **Anything already decided** you must not change — existing design system,
    router, state library, CSS approach?

---

## §2 — Map answers to configuration

| Answer | What you set |
|---|---|
| Admin console / data-heavy | `data-density="-1"` or `-2` on `<html>`; prefer `size="xs"`/`"sm"` on actions |
| Consumer / marketing | leave density alone (`0` is the default); larger button sizes (`md`/`lg`) for CTAs |
| Mobile-first | `md-navigation-bar` + `md-fab`; avoid `md-navigation-rail`, `md-transfer-list`, wide tables |
| Desktop-first | `md-navigation-rail` or `md-app-bar`; rail over bottom bar |
| Dark mode | `data-theme="dark"` on `<html>`; wire a toggle, and mirror OS via `prefers-color-scheme` |
| Both themes with toggle | persist the choice; set the attribute before first paint to avoid a flash |
| Brand color | override the `--md-sys-color-*` roles in your own stylesheet, loaded after the tokens (§4.2) |
| Flat / utilitarian | `data-ripple="off"` and `data-shape-morph="off"` on `<html>` |
| Any RTL locale | `dir="rtl"` on `<html>`; add `mirror-icon` to `md-button`s with directional glyphs; swap the glyph name yourself everywhere else (§4.5) |
| Multiple locales | build a dictionary in the consumer layer and feed component text props from it; never hardcode strings in markup |
| `Intl`-formatted values | pass a `locale` prop where a component exposes one; format everything else before it reaches the component |
| SSR | import from `@awc-ui/core/hydrate` on the server; use the client/server wrappers in `@awc-ui/react` |
| Heavy forms | components are form-associated via `ElementInternals` — use a real `<form>`, `md-button type="submit"`, and native `required` (§4.7) |
| Rich text | integrate a third-party editor; there is no `md-rich-text` |

### 2.1 Global switches — the complete set

All are attributes on `<html>` (or any ancestor; the nearest one wins).

```html
<html
  lang="en"
  dir="ltr"                  <!-- or rtl -->
  data-theme="dark"          <!-- omit for light -->
  data-density="-1"          <!-- -1 … -4; see below -->
  data-ripple="off"          <!-- default on -->
  data-shape-morph="off"     <!-- default on -->
>
```

**`data-density="0"` is inert.** No `[density="0"]` rule exists — density `0` is
simply the base values on `:root`, and a `0` rule would pin them onto every
element (reflected props write `density="0"` almost everywhere) and break global
inheritance. So the *overriding* range is `-1 … -4`. To escape an inherited rung
for one subtree, reset the scale directly:

```css
.opt-out-of-density { --md-sys-density-scale: 0; }
```

Per-component overrides beat the global one: a `density` prop, or
`ripple="off"` / `shape-morph="off"` on the element. **53 of the 57 top-level
components expose a `density` prop.** The four that don't: `md-divider`,
`md-ripple`, `md-sparkline`, `md-tabs`. (Nine sub-components also lack one —
they inherit density from the parent that owns their layout.)

---

## §3 — Install and bootstrap

```bash
npm install @awc-ui/core
```

**Register everything (recommended).** Two imports, once per app entry — one
defines every component, one loads the tokens. Both come from `@awc-ui/core`
itself, so this path needs no second package:

```ts
import { defineCustomElements } from '@awc-ui/core/loader';
import '@awc-ui/core/css/tokens.css';

defineCustomElements(window);
```

`@awc-ui/core/css/tokens.css` is the complete, self-contained token sheet —
light and dark colour roles, shape, elevation, motion, typescale, spacing and
z-index. It is the same set documented in §4.1.

**One-line alternative.** `@awc-ui/core/define` does both steps in a single
import. It loads the package's own token sheet, so it needs nothing else
installed:

```ts
import '@awc-ui/core/define'; // defines every component + loads the token sheet
```

`define` is client-only (it eval-guards `window`) and, because it imports CSS,
it needs a bundler. Never import it into a server graph.

**Per-component registration**, for size-sensitive bundles — load the token
sheet once yourself:

```ts
import '@awc-ui/core/css/tokens.css';
import '@awc-ui/core/components/md-button';
import '@awc-ui/core/components/md-text-field';
```

**Framework wrappers** — use these instead of raw elements; they handle
registration, typed props, and event binding. Below the version floor, drop to
the raw custom elements and the `loader` import above.

| Framework | Package | Requires |
|---|---|---|
| React / Next | `@awc-ui/react` | React 18+ |
| Angular | `@awc-ui/angular` (`AwcUiModule`) | Angular 17+ |
| Vue / Nuxt | `@awc-ui/vue` | Vue 3 |
| Svelte / SvelteKit | `@awc-ui/svelte` | Svelte 4+ |
| Plain HTML / Astro | `@awc-ui/core/loader` | — |

**SSR** — `@awc-ui/core/hydrate` renders Declarative Shadow DOM on the server.
`@awc-ui/react` ships matching client/server wrappers. Keep `define` and
`loader` out of the server graph; both are browser entries.

**Fonts** — components expect Roboto and Material Symbols Outlined to be
available. The library does **not** inject them. Every `icon="…"` prop renders a
Material Symbols glyph inside shadow DOM, so the font must be registered at the
**document** level (font registration crosses shadow boundaries; class rules do
not — the components declare the class rule inside their own roots):

```html
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap">
```

To swap the whole library to a different Material Symbols cut, set
`--md-sys-icon-font-family` on `:root` and load the matching `@font-face`.

---

## §4 — Global configuration reference

### 4.1 The token system

All AWC UI styling resolves to design tokens. **Never hardcode hex colours,
pixel radii, shadows, or font stacks** — they break theming, dark mode, density
and RTL in one stroke. Every value below is a real custom property defined by
`@awc-ui/tokens`; you may read them, and you may override them.

#### Color roles

Light is the default; `[data-theme="dark"]` swaps the palette. Every role has a
matching `on-` role for content drawn on top of it.

| Token | Light | Dark | Typical usage |
|---|---|---|---|
| `--md-sys-color-primary` | `#6750A4` | `#D0BCFF` | Filled buttons, active states |
| `--md-sys-color-on-primary` | `#FFFFFF` | `#381E72` | Text/icons on primary |
| `--md-sys-color-primary-container` | `#EADDFF` | `#4F378B` | FAB, selected segments |
| `--md-sys-color-on-primary-container` | `#21005D` | `#EADDFF` | Text on primary-container |
| `--md-sys-color-secondary` | `#625B71` | `#CCC2DC` | Secondary accents |
| `--md-sys-color-secondary-container` | `#E8DEF8` | `#4A4458` | Tonal buttons, chips |
| `--md-sys-color-tertiary` | `#7D5260` | `#EFB8C8` | Tertiary accents |
| `--md-sys-color-tertiary-container` | `#FFD8E4` | `#633B48` | Tertiary surfaces |
| `--md-sys-color-error` | `#B3261E` | `#F2B8B5` | Error / destructive |
| `--md-sys-color-on-error` | `#FFFFFF` | `#601410` | Content on error |
| `--md-sys-color-error-container` | `#F9DEDC` | `#8C1D18` | Error surfaces |
| `--md-sys-color-surface` | `#FFFBFE` | `#1C1B1F` | Page / card background |
| `--md-sys-color-on-surface` | `#1C1B1F` | `#E6E1E5` | Body text |
| `--md-sys-color-surface-variant` | `#E7E0EC` | `#49454F` | Muted fills |
| `--md-sys-color-on-surface-variant` | `#49454F` | `#CAC4D0` | Secondary text, icons |
| `--md-sys-color-surface-container-lowest` | `#FFFFFF` | `#0F0D13` | Lowest surface tier |
| `--md-sys-color-surface-container-low` | `#F7F2FA` | `#1D1B20` | Card / elevated button bg |
| `--md-sys-color-surface-container` | `#F3EDF7` | `#211F26` | Default container tier |
| `--md-sys-color-surface-container-high` | `#ECE6F0` | `#2B2930` | Dialog / menu surfaces |
| `--md-sys-color-surface-container-highest` | `#E6E0E9` | `#36343B` | Highest surface tier |
| `--md-sys-color-outline` | `#79747E` | `#938F99` | Borders (3:1 contrast) |
| `--md-sys-color-outline-variant` | `#CAC4D0` | `#49454F` | Dividers (low contrast) |
| `--md-sys-color-inverse-surface` | `#313033` | `#E6E1E5` | Snackbar, inverse chips |
| `--md-sys-color-inverse-on-surface` | `#F4EFF4` | `#313033` | Content on inverse-surface |
| `--md-sys-color-scrim` | `#000000` | `#000000` | Modal scrims |

**Semantic status roles** — beyond the baseline M3 palette, the library adds
`success`, `warning` and `info`, each with `on-`, `-container` and
`on-…-container` companions, in both themes, AA-verified. Used by `md-chip`,
`md-badge`, `md-meter`, `md-status-dot`.

| Token | Light | Dark |
|---|---|---|
| `--md-sys-color-success` | `#2E6B4F` | `#9DD5B0` |
| `--md-sys-color-success-container` | `#B8F0CE` | `#14512F` |
| `--md-sys-color-warning` | `#7A5900` | `#EFC148` |
| `--md-sys-color-warning-container` | `#FFDF9B` | `#5C4200` |
| `--md-sys-color-info` | `#38608F` | `#A2C9FE` |
| `--md-sys-color-info-container` | `#D3E4FF` | `#1E4975` |

#### Shape tokens

| Token | Value | Typical usage |
|---|---|---|
| `--md-sys-shape-corner-none` | `0px` | Square edges |
| `--md-sys-shape-corner-extra-small` | `4px` | Snackbar, small chips |
| `--md-sys-shape-corner-small` | `8px` | Cards (outlined), small surfaces |
| `--md-sys-shape-corner-medium` | `12px` | Cards (default), inputs |
| `--md-sys-shape-corner-large` | `16px` | Dialogs, large cards |
| `--md-sys-shape-corner-extra-large` | `28px` | Bottom sheets |
| `--md-sys-shape-corner-full` | `9999px` | Buttons, chips, FAB |

Partial-corner variants also exist for surfaces that meet an edge:
`--md-sys-shape-corner-extra-small-top`, `-large-top`, `-large-end`,
`-extra-large-top`. Their values are four-value `border-radius` shorthands
(e.g. `16px 16px 0px 0px`), so assign them to `border-radius`, not to a single
corner.

#### Elevation tokens

`-0` is the keyword `none`; `-1` through `-5` are complete `box-shadow` values,
and those five are **re-declared with deeper shadows under `[data-theme="dark"]`**
— so always use the token rather than copying its value.

| Token | When |
|---|---|
| `--md-sys-elevation-0` | `none` — resting cards, flat surfaces |
| `--md-sys-elevation-1` | Elevated buttons and cards at rest |
| `--md-sys-elevation-2` | Hover bump |
| `--md-sys-elevation-3` | FAB, menus, dialogs at rest |
| `--md-sys-elevation-4` – `-5` | Reserved for the most prominent surfaces |

#### Motion tokens

Durations come in four families of four: `short1…4` (50/100/150/200ms),
`medium1…4` (250/300/350/400ms), `long1…4` (450/500/550/600ms), and
`extra-long1…4` (700/800/900/1000ms).

| Token | Value | When |
|---|---|---|
| `--md-sys-motion-duration-short2` | `100ms` | Buttons, ripples, state layers |
| `--md-sys-motion-duration-medium2` | `300ms` | Dialogs, sheets, menus |
| `--md-sys-motion-duration-long2` | `500ms` | Large surface transitions |
| `--md-sys-motion-duration-extra-long1` | `700ms` | Ambient / chart entrances |
| `--md-sys-motion-easing-standard` | `cubic-bezier(0.2, 0, 0, 1)` | Small utility transitions |
| `--md-sys-motion-easing-standard-accelerate` | `cubic-bezier(0.3, 0, 1, 1)` | Exits |
| `--md-sys-motion-easing-standard-decelerate` | `cubic-bezier(0, 0, 0, 1)` | Entrances |
| `--md-sys-motion-easing-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` | Expressive transitions |
| `--md-sys-motion-easing-emphasized-accelerate` | `cubic-bezier(0.3, 0, 0.8, 0.15)` | Expressive exits |
| `--md-sys-motion-easing-emphasized-decelerate` | `cubic-bezier(0.05, 0.7, 0.1, 1)` | Expressive entrances |
| `--md-sys-motion-easing-linear` | `linear` | Progress, indeterminate loops |

> `--md-sys-motion-easing-emphasized` deliberately equals the standard curve:
> the full M3 emphasized curve is a two-phase path interpolator that CSS cannot
> express. The accelerate and decelerate halves *are* expressible, and are the
> ones to reach for.

MD3 Expressive also ships spring pairs, each an easing plus its natural
duration: `--md-sys-motion-spring-{spatial,effects}-{fast,default,slow}-easing`
and `…-duration`. Spatial = position/size/shape; effects = colour/opacity.

#### State-layer opacities

| Token | Value |
|---|---|
| `--md-sys-state-hover-state-layer-opacity` | `0.08` |
| `--md-sys-state-focus-state-layer-opacity` | `0.12` |
| `--md-sys-state-pressed-state-layer-opacity` | `0.12` |
| `--md-sys-state-dragged-state-layer-opacity` | `0.16` |
| `--md-sys-state-disabled-container-opacity` | `0.12` |
| `--md-sys-state-disabled-content-opacity` | `0.38` |

#### Typography, spacing and layering

- **Typescale** — `--md-sys-typescale-<role>-<size>-*` for
  `display`/`headline`/`title`/`label`/`body` × `large`/`medium`/`small`. Each
  role exposes `-font-family`, `-font-size`, `-line-height`, `-font-weight`,
  `-letter-spacing`, plus a `-font` shorthand
  (e.g. `--md-sys-typescale-headline-medium-font: 400 28px/36px Roboto, sans-serif`).
  Use the shorthand on the `font` property for headings you write yourself.
- **Spacing** — a 4px scale that tightens with density:
  `--md-sys-spacing-inset-{xs,sm,md,lg,xl}` (internal padding, 4/8/12/16/24px)
  and `--md-sys-spacing-gap-{xs,sm,md,lg}` (between siblings, 4/8/12/16px), plus
  `--md-sys-spacing-row-height` (`56px` at density 0).
- **Layering** — `--md-sys-z-index-app-bar` (100), `-navigation` (200),
  `-bottom-sheet` (300), `-popup` (1000), `-dialog-scrim` (1001), `-tooltip`
  (1500), `-snackbar` (2000). Use these instead of inventing z-indexes, or your
  overlay will land under a menu.

### 4.2 Theming and rebranding

To rebrand, redefine the role variables **after** the tokens stylesheet — both
themes, or dark mode inherits your light brand colour:

```css
:root {
  --md-sys-color-primary: #00629E;
  --md-sys-color-on-primary: #FFFFFF;
  --md-sys-color-primary-container: #CFE5FF;
  --md-sys-color-on-primary-container: #001D33;
}
[data-theme="dark"] {
  --md-sys-color-primary: #9BCBFF;
  --md-sys-color-on-primary: #003354;
  --md-sys-color-primary-container: #004A78;
  --md-sys-color-on-primary-container: #CFE5FF;
}
```

Per-component knobs are `--md-<component>-*` custom properties, listed in each
manual's Theming section (`--md-button-container-color`,
`--md-card-container-shape`, …). Prefer those over `::part()`, and prefer
`::part()` over reaching into shadow internals, which are unstable and will
break on any release.

**Overriding a colour role forfeits the library's contrast testing.** Re-verify
AA (4.5:1 text, 3:1 borders and dividers) after any palette change. The Theme
Generator at <https://awc-ui.dev/theme-generator> takes a seed colour, emits both
palettes as `--md-sys-color-*` overrides, and runs the WCAG checks live — use it
rather than hand-picking container and `on-` pairs.

### 4.3 Density

`data-density` steps `-1 → -4`; each rung trims ~4px of padding and touch
target, driving `--md-sys-density-scale` and the spacing tokens. `-4` is the
floor. Set it globally, override locally with the `density` prop. Do not go
below `-2` on touch-primary surfaces — you will break the 48px target.

Two details that bite:

- **`density="0"` does nothing** — see §2 for why, and for the
  `--md-sys-density-scale: 0` escape hatch.
- **`md-table` accepts two vocabularies**: the semantic `compact` / `standard` /
  `comfortable` (row heights 36 / 52 / 60px) *and* the numeric rungs. They
  compose — `density="compact"` inside a `data-density="-2"` region condenses
  further.

### 4.4 Dark mode

Set `data-theme="dark"` on `<html>` (or any ancestor — the nearest wins). The
tokens swap automatically and inherit across every shadow boundary; no
per-component code. To mirror the OS, read `prefers-color-scheme` and write the
attribute **before first paint**, or the page flashes light.

### 4.5 RTL

Layout is written with CSS logical properties, so it flips with `dir="rtl"`
without extra work. Two things still need you:

- **Directional glyphs do not flip.** Material Symbols are not auto-mirrored.
  `md-button` has a `mirror-icon` prop that mirrors its own leading/trailing
  glyph — set it on buttons using arrows, chevrons, `send`, `reply`, and leave
  it off for `add`, `search`, `favorite`. **`mirror-icon` exists only on
  `md-button`.** Everywhere else — `md-icon-button icon="…"`, `md-list-item`
  leading/trailing icons, `md-app-bar leading-icon` — swap the glyph name
  yourself (`arrow_back` ↔ `arrow_forward`).
- **Icon props you supply yourself** — e.g. `md-transfer-list`'s
  `move-right-icon` / `move-left-icon` / `move-all-*-icon` — must be swapped by
  you when the direction flips.

Never write physical CSS (`margin-left`, `padding-right`, `left`) around these
components. Use `margin-inline-start`, `padding-inline-end`, `inset-inline-end`.

### 4.6 Internationalization

Components are **i18n-engine-agnostic by design**. Every user-visible string is
either slotted content or a prop. Localize in the consumer layer: resolve your
dictionary to plain strings, then pass them in. Do not add a translation engine
inside a component. `locale` props exist only where a component computes an
`Intl`-formatted value itself: `md-date-picker`, `md-number-field`,
`md-meter`, `md-dialog`, and the charts (`md-bar-chart`, `md-line-chart`,
`md-area-chart`, `md-pie-chart`). `md-time-picker` has no
`locale` prop — it takes `format="12h" | "24h"` instead.

Templated strings keep their placeholder tokens when translated — translate
around the braces, don't remove them:

```html
<md-transfer-list count-template="{checked} / {total} ausgewählt"></md-transfer-list>
```

Other templated props: `md-autocomplete status-template`, `md-otp-field
cell-label-template`. Default prop values are English (`Search`, `Dismiss`,
`No results`, `Move selected to target`, …) — every one of them needs
translating in a localized app.

### 4.7 Forms and validation

Fourteen components are form-associated via `ElementInternals`, so they
participate in `FormData` and constraint validation like native controls:

`md-text-field` · `md-number-field` · `md-otp-field` · `md-select` ·
`md-multi-select` · `md-autocomplete` · `md-checkbox` · `md-radio` ·
`md-switch` · `md-slider` · `md-rating` · `md-date-picker` · `md-time-picker` ·
`md-button`

Rules:

- Use a real `<form>`. `md-button type="submit"` calls `form.requestSubmit()`
  (not `submit()`), so the `submit` event fires **and** built-in constraint
  validation runs. `required` genuinely blocks submit.
  `md-button type="reset"` calls `form.reset()`.
- Give every control a `name`, or it will not appear in `FormData`.
- Do **not** add hidden `<input>`s to mirror values — that's the old pattern and
  it double-submits.
- Validity changes are announced on a `mdValidityChange` event on the control.
  Error presentation is `error` + `error-text` on the field.
- Boolean state props differ by control — `md-checkbox` uses `checked`,
  `md-switch` uses **`selected`**, `md-select-option` uses `selected`. Check the
  manual; guessing `checked` on a switch silently does nothing.

---

## §5 — Component decision matrix

Route by **need**, not by name. If the need isn't listed, find the closest row
and read that component's `When NOT to use`.

### 5.1 Actions

| Need | Use | Don't use |
|---|---|---|
| Discrete labelled action | `md-button` | `md-chip`, raw `<button>` |
| Icon-only action | `md-icon-button` | `md-button` with no label |
| A destructive action | `md-button` + `md-dialog` to confirm | an unconfirmed `filled` button |
| The single most prominent screen action (mobile) | `md-fab` | a second `filled` `md-button` |
| One prominent action that expands to several | `md-fab-menu` + `md-fab-menu-item` | a stack of FABs |
| Primary action + variants of it | `md-split-button` | button + separate menu |
| 2–5 related actions as one unit | `md-button-group` | loose adjacent buttons |
| Mutually exclusive view/mode switch | `md-segmented-button-set` + `md-segmented-button` | radio buttons, tabs |
| Overflow / contextual actions | `md-menu` + `md-menu-item` | a row of text buttons |

### 5.2 Text input

| Need | Use | Don't use |
|---|---|---|
| Any single-line or multi-line text entry | `md-text-field` | raw `<input>` |
| A number with steppers and locale formatting | `md-number-field` | `md-text-field type="number"` |
| A one-time code / PIN | `md-otp-field` | a row of text fields |
| Text entry with suggestions | `md-autocomplete` | `md-select` |
| Site/app-wide search with a results surface | `md-search` | `md-text-field` with an icon |

### 5.3 Selection

| Need | Use | Don't use |
|---|---|---|
| One of many, from a list | `md-select` + `md-select-option` | radio group over ~7 options |
| One of few (2–5), all visible | `md-radio` | `md-select` |
| Several of many | `md-multi-select` | many `md-checkbox`es |
| Several of few, all visible | `md-checkbox` | `md-multi-select` |
| Instant on/off setting | `md-switch` | `md-checkbox` |
| A value in a numeric range | `md-slider` | `md-text-field type=number` |
| Subjective score | `md-rating` | slider |
| A color | `md-color-picker` | `<input type=color>` |
| Assign a subset from a bounded pool, side by side | `md-transfer-list` | two lists + buttons |
| Filter / attribute / removable entry | `md-chip` | small buttons |
| A date | `md-date-picker` | three selects |
| A time | `md-time-picker` | text field |

### 5.4 Navigation

| Need | Use | Don't use |
|---|---|---|
| Top-level destinations, mobile | `md-navigation-bar` + `md-navigation-tab` | tabs |
| Top-level destinations, desktop | `md-navigation-rail` + `md-navigation-rail-tab` | bottom bar |
| App header: title, actions, search | `md-app-bar` | a custom `<header>` |
| A dense action strip | `md-toolbar` | app bar |
| Sibling views **within** one screen | `md-tabs` + `md-tab` + `md-tab-panels` + `md-tab-panel` | navigation bar |
| Hierarchy / where-am-I | `md-breadcrumbs` + `md-breadcrumb-item` | text links |
| A linear multi-step flow | `md-stepper` + `md-step` | tabs |
| Contextual popup actions | `md-menu` + `md-menu-item`, `md-menu-item-group`, `md-sub-menu-item` | dialog |
| Hierarchical command menu (File → Export → PDF) | `md-menu` + `md-sub-menu-item` | nested dialogs |

### 5.5 Containment and feedback

| Need | Use | Don't use |
|---|---|---|
| Group related content | `md-card` | a bare `<div>` with a border |
| Blocking decision or focused task | `md-dialog` | a new page |
| Critical error the user must acknowledge | `md-dialog` | `md-snackbar` |
| Supplementary content from the bottom (mobile) | `md-bottom-sheet` | dialog |
| Supplementary content from the side (desktop) | `md-side-sheet` | dialog |
| Brief confirmation of an action, optionally undoable | `md-snackbar` | dialog, alert |
| Explain a control on hover/focus | `md-tooltip` | a dialog or inline hint |
| Progressive disclosure of sections | `md-accordion` + `md-accordion-item` | tabs |
| Visual separation | `md-divider` | a styled `<hr>` |
| A vertical set of records | `md-list` + `md-list-item` | a table |
| Determinate/indeterminate progress | `md-progress-indicator` | spinner GIF |
| Brand-consistent page/content loading | `md-loading-indicator` | custom spinner |
| Content-shaped loading placeholder | `md-skeleton` | a spinner over the whole page |
| Count or status on an element | `md-badge` | superscript text |
| Compact status dot | `md-status-dot` | a colored emoji |
| Read-only value within a known range (quota, battery) | `md-meter` | `md-progress-indicator` |
| A person or entity image/initials | `md-avatar` | a raw `<img>` |
| Touch feedback inside a custom control | `md-ripple` | custom CSS animation |

### 5.6 Data

| Need | Use | Don't use |
|---|---|---|
| Any table | `md-table-container` wrapping `md-table`, with `-head`/`-body`/`-row`/`-cell`/`-foot` inside the table and `-toolbar`/`-pagination` beside it in the container (§7.1) | a native `<table>` |
| Sorting, selection, paging on that table | the same parts — `md-table` carries the STATE (`sort-by`, `sort-order`, `selection`, `row-offset`, `row-count`, `loading`) and emits events; you own the data and do the actual sorting/paging | expecting it to sort an array for you |
| Hierarchy / reporting lines | `md-organization-chart` | nested lists |
| Compare categories | `md-bar-chart` | pie chart |
| Trend over time | `md-line-chart` | bar chart |
| Trend with cumulative volume | `md-area-chart` | line chart |
| Parts of a whole (≤ ~6 slices) | `md-pie-chart` | bar chart |
| Inline micro-trend in a cell or card | `md-sparkline` | a full chart |

> **There is no data-driven table component.** `md-table` is composable: you
> render the rows. It tracks and announces sort, selection and pagination state
> and emits events when the user changes them, but the sorting, filtering and
> slicing of your data is yours to perform. Render rows from your own array in
> response to those events.

### 5.7 Choosing the variant

The matrix picks the component; this picks its shape. Every value below is a
real enum member — anything not listed here is not a valid value.

| Component | Prop | Values, and when |
|---|---|---|
| `md-button` | `variant` | `filled` the one primary action · `tonal` a strong secondary · `outlined` secondary, and the safe choice for a destructive action behind a confirm · `text` low emphasis, dialog Cancel · `elevated` when it sits on a busy or coloured background (default `filled`) |
| `md-button` / `md-icon-button` / `md-button-group` | `size` | `xs` `sm` `md` `lg` `xl` — default `sm`; go `md`/`lg` for consumer CTAs, `xs`/`sm` for dense admin UI |
| `md-icon-button` | `variant` | `standard` (default) · `filled` · `tonal` · `outlined` |
| `md-button-group` | `variant` | `standard` spaced · `connected` fused into one bar |
| `md-fab` | `size` | `standard` (default) · `medium` · `large` |
| `md-fab` | `variant` | `primary-container` (default) · `secondary-container` · `tertiary-container` · `surface` · `primary` · `secondary` · `tertiary` |
| `md-card` | `variant` | `filled` for a group of comparable items · `elevated` (default) for a hero or featured item · `outlined` for a settings or form section |
| `md-text-field` / `md-select` | `variant` | `outlined` for forms on a surface · `filled` for dense or tinted layouts (`md-text-field` defaults to `filled`, `md-select` to `outlined`) — pick one and use it for every field on the screen |
| `md-text-field` | `type` | any native input type: `password`, `email`, `tel`, `url`, `search`, … (default `text`) |
| `md-text-field` | `multiline` | `"auto-grow"` grows with content · `"fixed"` with `rows` for a fixed comment box · `false` (default) single line |
| `md-search` | `variant` | `contained` (default) · `divided` |
| `md-app-bar` | `variant` | `small` (default) · `medium` · `large` for a prominent headline · `search` for a bar that hosts a field |
| `md-chip` | `variant` | `assist` (default) · `filter` for toggleable facets · `input` for user-entered removable values · `suggestion` |
| `md-chip` | `appearance` | `outlined` (default) · `filled` · `elevated` |
| `md-badge` | `variant` | `small` a bare dot · `large` (default) a count |
| `md-tooltip` | `variant` | `plain` (default) a short label on an icon control · `rich` an explanatory popover that may hold a link or action |
| `md-divider` | — | **no `variant`** — use the booleans `inset`, `inset-start`, `inset-end` |
| `md-side-sheet` | `variant` | `standard` coexists with page content · `modal` overlays with a scrim |
| `md-bottom-sheet` | `variant` | `standard` (default) · `detached` floating above the edge |
| `md-dialog` | `fullscreen` | boolean — a full-screen dialog for a long mobile task |
| `md-date-picker` | `variant` | `modal-input` (default) calendar plus a typed field · `modal` calendar only · `docked` inline, anchored to the field |
| `md-time-picker` | `variant` | `dial` · `input` (default) |
| `md-progress-indicator` | `variant` | `linear` (default) · `circular`; add `indeterminate` when the total is unknown |
| `md-list-item` | `lines` | `1` · `2` · `3` — must match how much supporting text you pass |
| `md-navigation-bar` | — | 3–5 destinations. Fewer than three: use `md-tabs`. More than five: a rail or a menu |
| `md-navigation-rail` | — | 3–7 destinations; cap the overflow with `max-visible` |

### 5.8 Not in the library

Rich text editor · file upload/dropzone · calendar/scheduler view · map ·
toast stack manager (use `md-snackbar` and manage the queue yourself) ·
data grid with virtualized columns. If the user needs one, say so plainly and
integrate a third-party component styled with the MD3 tokens.

**There is no `md-grid`, no `md-data-table`, no `md-layout`, no `md-icon`.**
If a tag is not listed in §6, it does not exist — do not emit it.

---

## §6 — Component inventory

**Every component has exactly one manual, and it is the readme.md in its own
source folder:**

```
./packages/core/src/components/<tag>/readme.md
```

e.g. [`md-select`](./packages/core/src/components/md-select/readme.md),
[`md-button`](./packages/core/src/components/md-button/readme.md).

**Load that file before you use the component.** There is no second, shorter
summary to rely on — this readme is the single source, so anything you do not
read there, you do not know. Each one carries When-to-use, a Do/Don't table
from M3, copy-paste patterns, an anti-patterns table, and the theming surface.

Work through them one at a time: pick the component from the decision matrix
(§5), load its readme, write that component's markup, then move to the next.

There are 81 manuals for 57 components: 24 of them document sub-components that
are only valid inside a parent (a table cell, a tab panel, a select option).
Every sub-component manual names its parent in the first line, and §7 below
summarises the nesting.

`status` in each manual's `llm:meta` block is one of:

- **`md3-mapped`** — has a Material Design 3 guidelines page; the Do/Don't is
  sourced from it.
- **`custom`** — an addition to MD3; guidance is derived house rules.
- **`sub-component`** — only valid inside a specific parent.

| Category | Components |
|---|---|
| Actions | `md-button` `md-icon-button` `md-fab` `md-fab-menu` `md-fab-menu-item` `md-split-button` `md-button-group` `md-segmented-button` `md-segmented-button-set` |
| Text input | `md-text-field` `md-number-field` `md-otp-field` `md-autocomplete` `md-search` |
| Selection | `md-select` `md-select-option` `md-multi-select` `md-checkbox` `md-radio` `md-switch` `md-slider` `md-rating` `md-color-picker` `md-transfer-list` `md-chip` |
| Pickers | `md-date-picker` `md-time-picker` |
| Navigation | `md-app-bar` `md-toolbar` `md-navigation-bar` `md-navigation-tab` `md-navigation-rail` `md-navigation-rail-tab` `md-tabs` `md-tab` `md-tab-panels` `md-tab-panel` `md-breadcrumbs` `md-breadcrumb-item` `md-menu` `md-menu-item` `md-menu-item-group` `md-sub-menu-item` `md-stepper` `md-step` |
| Containment | `md-card` `md-dialog` `md-bottom-sheet` `md-side-sheet` `md-snackbar` `md-tooltip` `md-accordion` `md-accordion-item` `md-divider` `md-list` `md-list-item` |
| Data | `md-table` `md-table-container` `md-table-head` `md-table-body` `md-table-row` `md-table-cell` `md-table-foot` `md-table-toolbar` `md-table-pagination` `md-table-sort-label` `md-table-expand-toggle` `md-organization-chart` |
| Charts | `md-bar-chart` `md-line-chart` `md-area-chart` `md-pie-chart` `md-sparkline` |
| Status & feedback | `md-progress-indicator` `md-loading-indicator` `md-skeleton` `md-badge` `md-status-dot` `md-meter` `md-avatar` `md-ripple` |

---

## §7 — Composition rules

### 7.1 What nests inside what

A sub-component is only valid inside its parent. Putting one anywhere else
produces an unstyled, unregistered-looking element with no keyboard behaviour,
because the parent is what wires roving tabindex, ARIA ids and selection.

| Parent | Children it manages |
|---|---|
| `md-button-group` | `md-button`, `md-icon-button` |
| `md-segmented-button-set` | `md-segmented-button` |
| `md-fab-menu` | `md-fab-menu-item` (anchored to an `md-fab` via `anchor="<id>"`) |
| `md-menu` | `md-menu-item`, `md-sub-menu-item`, `md-menu-item-group` — **not** `md-divider`; separate rows with `md-menu-item`'s own `divider` (or `gap`) prop |
| `md-menu-item-group` | `md-menu-item` |
| `md-sub-menu-item` | a nested `md-menu` in `slot="submenu"` — the items go in *that* menu. There is no default slot, so anything else you nest renders nothing |
| `md-select`, `md-multi-select`, `md-autocomplete` | `md-select-option` |
| `md-list` | `md-list-item`, `md-divider` |
| `md-tabs` | `md-tab` |
| `md-tab-panels` | `md-tab-panel` (one per tab, in tab order) |
| `md-navigation-bar` | `md-navigation-tab` |
| `md-navigation-rail` | `md-navigation-rail-tab`, plus an `md-fab` in `slot="fab"` |
| `md-accordion` | `md-accordion-item` |
| `md-stepper` | `md-step` (horizontal steppers also take `slot="content"`) |
| `md-breadcrumbs` | `md-breadcrumb-item` |
| `md-table-container` | `md-table` — **it wraps the table, not the other way round** — plus `md-table-toolbar` in `slot="top"` and `md-table-pagination` in `slot="bottom"`, which sit outside the scroll region |
| `md-table` | `md-table-head`, `md-table-body`, `md-table-foot` (and bare `md-table-row`). It does **not** accept the container, toolbar or pagination |
| `md-table-head` / `-body` / `-foot` | `md-table-row` |
| `md-table-row` | `md-table-cell`, plus `md-table-expand-toggle` for an expandable row |
| `md-table-cell` | `md-table-sort-label` in a header cell |
| `md-tooltip` | **its trigger** — the tooltip wraps the element it describes in its default slot |
| `md-dialog` | body content in the default slot; `md-button` in `slot="actions"` |
| `md-bottom-sheet` / `md-side-sheet` | content in the default slot; `md-button` in `slot="actions"`; headline in `slot="headline"` |
| `md-app-bar` | `md-icon-button` in `slot="leading"` and `slot="trailing"`; `md-menu` for overflow; a field in `slot="search"` on `variant="search"` |
| `md-toolbar` | `md-icon-button`, `md-button`, `md-button-group`; an `md-fab` in `slot="fab"`; `slot="leading"` / `slot="trailing"` for the end clusters |

### 7.2 Pairs that belong together

These don't nest — they sit next to each other in a working flow. Reaching for
one usually means you want the other.

| This | Goes with | Why |
|---|---|---|
| `md-icon-button` | `md-tooltip` | The tooltip supplies the visible meaning the icon lacks |
| `md-button` (`soft-disabled`) | `md-tooltip` | Explains *why* the action is unavailable |
| `md-fab` | `md-fab-menu` | The FAB is the menu's anchor |
| `md-split-button` | `md-menu` | The trailing half opens it |
| `md-card` | `md-button`, `md-icon-button`, `md-divider` | Footer actions, corner action, internal sections |
| `md-list-item` | `md-checkbox`, `md-switch`, `md-icon-button` | Trailing controls in a selectable or settings row |
| `md-bottom-sheet` / `md-side-sheet` | `md-list` | Action menus and filter panels inside the sheet |
| `md-search` | `md-list`, `md-avatar`, `md-icon-button` | Results in the panel; account and voice/filter affordances in the trailing slot |
| `md-date-picker` | `md-time-picker` | Date + time row for booking and scheduling forms |
| `md-time-picker` | `md-button` | The trigger, when `hide-trigger` is set. The picker **is** its own dialog — don't nest it in another one |
| `md-text-field` | `md-button` | Submit / cancel in the form footer |
| `md-multi-select` / `md-autocomplete` | `md-text-field`, `md-menu`, `md-chip` | The field is the trigger (and inherits its variant, density and error state), the menu is the option surface, chips are the selected values |
| `md-autocomplete` | `md-progress-indicator` | The loading row while suggestions are fetched |
| `md-transfer-list` | `md-checkbox`, `md-text-field`, `md-icon-button` | Per-row select, per-side search, mover controls |
| `md-number-field` | `md-text-field` hooks, `md-icon-button` | It *is* an `md-text-field` internally — every `--md-text-field-*` custom property passes through — and its steppers are `md-icon-button`s |
| `md-otp-field` | `md-button` | Verify action (`auto-submit` covers the no-button flow) |
| Any chart | `md-card` | Charts belong on a dashboard tile |
| `md-line-chart` | `md-segmented-button-set` | Period picker (1W / 1M / 1Y) driving the range |
| `md-sparkline` | `md-list-item`, `md-table-cell` | Trend column beside a value |
| `md-skeleton` | `md-card`, `md-list` | Render N placeholders in the real layout while fetching |
| `md-meter` | `md-chip`, `md-card` | Same semantic status colour on both; quota and usage summaries live on a card |
| `md-color-picker` | `md-text-field`, `md-button` | Label and helper text beside it in a form; save / cancel in the surrounding popover or dialog |
| `md-rating` | `md-text-field`, `md-card` | A rating row in a review form; aggregate scores on a review card |
| `md-accordion` | `md-divider` | Optional inner dividers inside long item content |
| `md-stepper` | `md-button` | Next / back / submit adjacent to the stepper |

### 7.3 Nesting that is always wrong

- A dialog opened from inside a dialog. Use `md-stepper` inside **one**
  `md-dialog`.
- A component inside a native interactive element (`<button>`, `<a>`) — it
  nests interactive controls and destroys the accessibility tree. Use the
  component's own `href` / `type` props.
- `md-tabs` used for top-level app navigation. Tabs switch sibling views of the
  same data; destinations are `md-navigation-bar` / `md-navigation-rail`.

---

## §8 — Page recipes

Complete, runnable screens. Each renders as-is once the components are
registered and the token sheet and font links from §3 are loaded — no
placeholder identifiers, no helper functions to write.

### 8.1 Login screen

`<form>` is load-bearing: it is what makes `required` block submit and what
`type="submit"` calls `requestSubmit()` on.

```html
<main style="display: grid; place-items: center; min-block-size: 100dvh; padding: 24px;">
  <form id="login-form" style="inline-size: min(420px, 100%);">
    <md-card variant="elevated" style="padding: 32px; display: flex; flex-direction: column; gap: 20px;">
      <h1 style="margin: 0; font: var(--md-sys-typescale-headline-medium-font);">Sign in</h1>

      <md-text-field
        variant="outlined"
        label="Email"
        type="email"
        name="email"
        autocomplete="username"
        required
      ></md-text-field>

      <md-text-field
        variant="outlined"
        label="Password"
        type="password"
        name="password"
        autocomplete="current-password"
        password-toggle="internal"
        required
      ></md-text-field>

      <md-button variant="filled" type="submit" full-width>Sign in</md-button>
      <md-button variant="text" href="/forgot-password">Forgot password?</md-button>
    </md-card>
  </form>
</main>

<script type="module">
  document.getElementById('login-form').addEventListener('submit', (e) => {
    e.preventDefault();
    const data = new FormData(e.currentTarget);
    console.log(data.get('email'), data.get('password'));
  });
</script>
```

### 8.2 Settings page (mobile)

Top app bar + grouped rows of instant-apply switches. `md-switch` uses
**`selected`**, not `checked`. The rows are `type="text"` (non-interactive), so
the switch is the only control — one tab stop per setting.

```html
<md-app-bar variant="small" headline="Settings">
  <md-icon-button slot="leading" icon="arrow_back" aria-label="Back"></md-icon-button>
</md-app-bar>

<main style="padding: 16px; display: flex; flex-direction: column; gap: 16px;">
  <md-card variant="outlined">
    <md-list>
      <md-list-item headline="Notifications" supporting-text="Push, email, in-app" lines="2">
        <md-switch slot="trailing" selected aria-label="Enable notifications" data-setting="notifications"></md-switch>
      </md-list-item>
      <md-divider></md-divider>
      <md-list-item headline="Dark mode" supporting-text="Match system" lines="2">
        <md-switch slot="trailing" aria-label="Enable dark mode" data-setting="dark"></md-switch>
      </md-list-item>
      <md-divider></md-divider>
      <md-list-item headline="Sync over cellular">
        <md-switch slot="trailing" selected aria-label="Sync over cellular" data-setting="cellular"></md-switch>
      </md-list-item>
    </md-list>
  </md-card>
</main>

<md-snackbar id="settings-toast" message="Setting saved"></md-snackbar>

<script type="module">
  const toast = document.getElementById('settings-toast');
  document.querySelectorAll('md-switch[data-setting]').forEach((sw) => {
    sw.addEventListener('mdChange', (e) => {
      if (sw.dataset.setting === 'dark') {
        document.documentElement.setAttribute('data-theme', e.detail.selected ? 'dark' : 'light');
      }
      toast.show();
    });
  });
</script>
```

### 8.3 Settings form (deferred save, with validation)

When settings are saved on submit rather than applied instantly, use a real
form. `required` blocks the submit; every control needs a `name` to reach
`FormData`.

```html
<form id="profile-form" style="max-inline-size: 560px; margin: 24px auto; padding: 0 16px;">
  <md-card variant="outlined" style="padding: 24px; display: flex; flex-direction: column; gap: 20px;">
    <h2 style="margin: 0; font: var(--md-sys-typescale-title-large-font);">Profile</h2>

    <md-text-field
      variant="outlined"
      label="Display name"
      name="displayName"
      required
      supporting-text="Shown on your public profile"
    ></md-text-field>

    <md-select variant="outlined" label="Language" name="language" value="en" required>
      <md-select-option value="en" label="English"></md-select-option>
      <md-select-option value="de" label="Deutsch"></md-select-option>
      <md-select-option value="ar" label="العربية"></md-select-option>
    </md-select>

    <!-- md-checkbox has NO label slot. It is a labelable, form-associated
         element: wrap it in a native <label> (which names it AND forwards
         clicks), or give the host an aria-label. Text between the tags is
         NOT rendered. -->
    <label style="display: inline-flex; align-items: center; gap: 12px; cursor: pointer;">
      <md-checkbox name="newsletter" value="yes" supporting-text="Monthly, no more"></md-checkbox>
      <span>Send me product news</span>
    </label>

    <div style="display: flex; gap: 8px; justify-content: flex-end;">
      <md-button variant="text" type="reset">Reset</md-button>
      <md-button variant="filled" type="submit">Save changes</md-button>
    </div>
  </md-card>
</form>

<md-snackbar id="saved-toast" message="Changes saved" action="Undo"></md-snackbar>

<script type="module">
  const form = document.getElementById('profile-form');
  const toast = document.getElementById('saved-toast');

  form.addEventListener('submit', (e) => {
    e.preventDefault();
    const data = Object.fromEntries(new FormData(form));
    console.log(data); // { displayName, language, newsletter? }
    toast.show();
  });

  toast.addEventListener('mdAction', () => form.reset());
</script>
```

### 8.4 Dashboard with a FAB

```html
<md-app-bar variant="medium" headline="Inbox">
  <md-icon-button slot="trailing" icon="search" aria-label="Search"></md-icon-button>
  <md-icon-button slot="trailing" icon="filter_list" aria-label="Filter"></md-icon-button>
</md-app-bar>

<main style="padding: 16px; display: grid; gap: 12px; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));">
  <md-card variant="filled" interactive style="padding: 16px;">
    <strong>Acme contract</strong>
    <p style="margin: 4px 0 0; color: var(--md-sys-color-on-surface-variant);">Renewal due in 5 days</p>
  </md-card>
  <md-card variant="filled" interactive style="padding: 16px;">
    <strong>Q4 report draft</strong>
    <p style="margin: 4px 0 0; color: var(--md-sys-color-on-surface-variant);">Shared by Alex</p>
  </md-card>
</main>

<md-fab
  icon="add"
  aria-label="New item"
  style="position: fixed; inset-block-end: 16px; inset-inline-end: 16px; z-index: var(--md-sys-z-index-navigation);"
></md-fab>
```

`inset-inline-end` (not `right`) is what keeps the FAB in the correct corner
under `dir="rtl"`.

### 8.5 Destructive confirmation dialog

`md-dialog` traps focus and returns it to the trigger on close — do not add your
own focus management. The error colouring goes through the button's own custom
properties, never a hex.

```html
<md-button id="open-delete" variant="outlined">Delete account</md-button>

<md-dialog id="confirm-delete" headline="Delete account?" icon="warning">
  <p style="margin: 0;">
    This will permanently delete your account and all associated data.
    This action cannot be undone.
  </p>
  <md-button id="cancel-delete" slot="actions" variant="text">Cancel</md-button>
  <md-button
    id="do-delete"
    slot="actions"
    variant="filled"
    style="--md-button-container-color: var(--md-sys-color-error);
           --md-button-label-color: var(--md-sys-color-on-error);"
  >Delete</md-button>
</md-dialog>

<script type="module">
  const dialog = document.getElementById('confirm-delete');
  document.getElementById('open-delete').addEventListener('mdClick', () => dialog.show());
  document.getElementById('cancel-delete').addEventListener('mdClick', () => dialog.close());
  document.getElementById('do-delete').addEventListener('mdClick', () => {
    dialog.close();
    // perform the deletion
  });
</script>
```

If you omit `slot="actions"` entirely, `md-dialog` renders its own Cancel / OK
pair (labels via `cancel-label` / `ok-label`) and closes itself.

### 8.6 Tabbed content page

`md-tab-panels` finds the nearest preceding `md-tabs` (or the one named by
`for`), follows its `mdTabChange`, and wires `aria-controls` /
`aria-labelledby` both ways. **No JavaScript is required**, and `md-tab` has no
`value` or `selected` prop — selection lives on `md-tabs` as `active-tab-index`.

```html
<md-tabs id="profile-tabs" aria-label="Profile sections" active-tab-index="0">
  <md-tab label="Posts"></md-tab>
  <md-tab label="Replies"></md-tab>
  <md-tab label="Likes" badge="3"></md-tab>
</md-tabs>

<md-tab-panels for="profile-tabs">
  <md-tab-panel style="padding: 16px;">
    <p style="margin: 0;">Your posts appear here.</p>
  </md-tab-panel>
  <md-tab-panel style="padding: 16px;">
    <p style="margin: 0;">Your replies appear here.</p>
  </md-tab-panel>
  <md-tab-panel style="padding: 16px;">
    <p style="margin: 0;">Posts you liked appear here.</p>
  </md-tab-panel>
</md-tab-panels>
```

To react to the switch (lazy-loading a panel, for example), listen on the tabs:

```js
document.getElementById('profile-tabs')
  .addEventListener('mdTabChange', (e) => console.log(e.detail.index, e.detail.previousIndex));
```

### 8.7 The full recipe library

Twenty-two more complete screens live in the documentation, each with a live
demo, the full markup, framework tabs, and production notes. When the user's
request matches one of these, read that page (append the slug to
`https://awc-ui.dev/recipes/`) instead of composing from scratch:

| Recipe slug | Screen |
|---|---|
| `two-factor-verification` | OTP entry, resend countdown, backup-codes dialog |
| `kpi-overview` | Stat tiles with sparklines + charts under a range switcher |
| `data-grid-console` | Bulk-action data table: filters, selection, undo |
| `server-fleet-status` | Table of hosts with meters, sparklines, status dots |
| `release-health-drilldown` | Table row → side-sheet master-detail with charts |
| `csv-import-wizard` | Stepper: upload, map columns, validate, import |
| `role-permission-assignment` | Transfer-list permissions with confirm dialog |
| `org-chart-explorer` | Searchable org chart with side-sheet profiles |
| `moderation-queue` | Verdict controls, confidence meter, card queue |
| `checkout-wizard` | Three-step commerce checkout with validation |
| `appointment-booking` | Date + time pickers inside a stepper flow |
| `survey-nps` | Paged survey using every input control |
| `notification-preferences` | Accordion × switch matrix, quiet hours |
| `app-shell` | Responsive rail/bar chrome, SSR-ready, zero CLS |
| `inbox-shell` | Three-zone list + reading-pane layout |
| `mobile-filter-sheet` | Bottom-sheet filters with applied-chip row |
| `product-reviews` | Rating input + per-star meter breakdown |
| `order-tracking` | Shipment timeline stepper with progress meter |
| `portfolio-markets` | Finance charts + holdings table + trade ticket |
| `pricing-page` | Plan cards, billing toggle, comparison table |
| `async-feedback-patterns` | Skeleton/progress/snackbar choreography rules |
| `charts-gallery` | Every chart component, live-retheming palette |

---

## §9 — Universal do's and don'ts

Apply to every component. Component-specific rules live in each manual.

### 9.1 API and styling

| ✅ Do | ❌ Don't |
|---|---|
| Use the custom element directly — it *is* the control, with its own `href` / `type` props | Wrap it in a native `<button>` / `<a>` (§7.3) |
| Set arrays and objects as **JS properties** (`el.items = [...]`) | Pass them as HTML attributes — they won't parse |
| Theme via `--md-<component>-*` properties, then `::part()` | Reach into shadow internals or override `.md-*` classes |
| Change appearance through design tokens (§4.1) | Hardcode hex colors, px spacing, shadows, or font stacks |
| Use `--md-sys-z-index-*` for your own overlays | Invent z-indexes that land under a menu |
| Use logical CSS (`margin-inline-start`, `inset-inline-end`) | Use `margin-left`, `right`, `padding-right` |
| Set `data-density` / `data-theme` / `dir` once, globally | Set them per component unless you mean a local exception |
| Listen to the component's `md*` events | Rely on native `click` — it fires even when the component's `disabled` / `loading` guard suppressed the action |
| Check the manual for the state prop name | Assume `checked`; `md-switch` uses `selected` |
| Render the element, then call its `@Method` | Call `.show()` on an element not yet in the DOM |

Toggling components flip their own state on activation and *then* emit. On
`md-button`, `mdClick` is cancelable — `preventDefault()` on it vetoes the
toggle and any navigation. `mdChange` fires after the flip and is not
cancelable. If a controlled parent rejects a change it must revert the child
explicitly.

`md-button` has a **toggle mode**: set `toggle` and the button flips its own
`selected` on each activation and exposes `aria-pressed`. `selected` is the
state, not the switch — set it for the initial pressed state and read it back
from `mdClick`'s `detail.selected`. Setting `toggle` and then styling
"pressed" yourself, or setting `selected` without `toggle` (which emits no
`aria-pressed` at all), both produce a control that lies to assistive tech.

### 9.2 Content and hierarchy

| ✅ Do | ❌ Don't |
|---|---|
| Use sentence case for all labels | Uppercase or title-case UI text |
| Keep one high-emphasis action per screen region | Compete `filled` buttons against each other |
| Use `soft-disabled` + `md-tooltip` for contextually-unavailable actions | Use `disabled` and remove it from tab order with no explanation |
| Localize every text prop and `aria-label` | Leave default English prop values in a translated app |

**`disabled` vs `soft-disabled`.** Both render the disabled appearance, but
`disabled` also removes the control from the tab order, so a keyboard or screen
reader user can never find out *why* it is off. `soft-disabled` keeps the
control focusable and announced while still blocking activation — which is what
lets an `md-tooltip` on it explain the gate. Use it whenever the reason is
informative rather than obvious.

Nesting rules — dialog inside a dialog, a component inside a native
`<button>` / `<a>`, tabs used as app navigation — live in §7.3.

### 9.3 Accessibility contract

The library ships WCAG 2.1 AA keyboard and ARIA wiring by default. These are the
rules you must not break:

1. **Every icon-only control gets an accessible name.** `md-icon-button`,
   `md-fab`, and icon-only `md-tab` are nameless without `aria-label` (or
   `aria-labelledby`). `md-fab` will also accept `label`, and warns in the
   console when it has neither.
2. **Every form field gets a `label` prop.** `placeholder` is not a label — it
   disappears on type.
3. **Don't break the tab order.** Every interactive control must be reachable by
   Tab and operable by Enter/Space. If you add `tabindex="-1"` to anything,
   have a reason.
4. **Don't write your own focus trap.** `md-dialog`, `md-bottom-sheet` and
   `md-side-sheet` trap focus while open and restore it to the trigger on
   close — including across shadow boundaries. Adding your own fights theirs.
5. **Don't wrap components in your own live regions.** `md-snackbar` announces
   itself (`politeness="polite"` by default, `"assertive"` when the message must
   interrupt). For an error that blocks the task, use `md-dialog`.
6. **Don't disable motion yourself.** Components honour
   `prefers-reduced-motion: reduce` internally.
7. **Directional icons do not auto-flip in RTL** — see §4.5.
8. **Re-verify contrast after overriding any colour role** — the library's AA
   testing covers the shipped palette only. The Theme Generator at
   <https://awc-ui.dev/theme-generator> runs the WCAG checks live (§4.2).

---

## §10 — Before you ship

1. **Every icon-only control has an accessible name.**
2. **Keyboard-only pass**: reach and operate every control; focus is always
   visible; no traps in dialogs/menus/sheets; focus returns to the trigger.
3. **Theme pass**: light *and* dark, if both are supported — and the attribute
   is set before first paint.
4. **RTL pass**, if an RTL locale ships — check directional icons specifically,
   and grep your own CSS for physical properties.
5. **Density pass** at the configured rung — no clipped labels, touch targets
   still adequate. Remember `density="0"` is inert; use
   `--md-sys-density-scale: 0` to opt a subtree out.
6. **Forms**: every control has a `name`; `required` blocks submit; `FormData`
   contains every field; reset works.
7. **No hardcoded strings** left in markup if the app is localized — including
   default prop values like `Search`, `Dismiss`, `No results`.
8. **No hardcoded design values** — grep the diff for hex colours, `px` radii,
   `box-shadow`, and `z-index` literals.
9. **Contrast** re-verified against AA if colour roles were overridden.
10. **SSR**: if server-rendered, confirm no hydration mismatch and that content
    is present with JS disabled.
11. **No shadow-internal CSS** — only tokens, custom properties, and `::part()`.
12. **Every `md-*` tag you emitted appears in §6.** If it doesn't, it doesn't
    exist.