Rating

A subjective score on a small, discrete scale. Star (or custom-glyph) rating with a configurable maximum, optional half-steps, a hover preview, and form participation via ElementInternals. Not a Material Design 3 component — M3 has no rating page, so there is no spec to point at; the guidance here is house rules derived from M3’s slider and icon-button pages plus this component’s own behaviour.

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>

<md-rating value="3" rating-label="Rate this product"></md-rating>
<md-rating value="4.5" precision="0.5" show-value-label rating-label="Average rating" readonly></md-rating>

Copy

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

export function Demo() {
  return (
    <>
      <MdRating value="3" ratingLabel="Rate this product"></MdRating>
      <MdRating value="4.5" precision="0.5" showValueLabel ratingLabel="Average rating" readonly></MdRating>
    </>
  );
}

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 -->
<md-rating value="3" rating-label="Rate this product"></md-rating>
<md-rating value="4.5" precision="0.5" show-value-label rating-label="Average rating" readonly></md-rating>

Copy

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

<template>
  <md-rating value="3" rating-label="Rate this product"></md-rating>
  <md-rating value="4.5" precision="0.5" show-value-label rating-label="Average rating" readonly></md-rating>
</template>

Copy

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

<md-rating value="3" rating-label="Rate this product"></md-rating>
<md-rating value="4.5" precision="0.5" show-value-label rating-label="Average rating" readonly></md-rating>

Install

Already installed? See the Installation guide for one-time package setup (core + tokens, fonts). Each tab below shows two patterns for using md-rating 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-rating) ─── -->
<script type="module">
  import '@awc-ui/core/components/md-rating';
</script>


<md-rating></md-rating>

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 { MdRating } from '@awc-ui/react';

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


// ─── Option B: single import (tree-shake to only md-rating) ───
//   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-rating';

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

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-rating></md-rating>`,
})
export class ExampleComponent {}


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

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

Copy

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

<template>
  <MdRating></MdRating>
</template>


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

<template>
  <md-rating></md-rating>
</template>

Copy

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

<md-rating></md-rating>


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

<md-rating></md-rating>

When to use

• Capturing a subjective judgement on a small scale: product reviews, satisfaction, difficulty.
• Displaying an aggregate score read-only.

When not to use

Situation	Use instead
An objective value on a continuum	md-slider
A precise number	md-text-field with type="number"
Binary like / dislike	md-icon-button with toggle
More than ~10 points of scale	md-slider
Progress toward completion	md-progress-indicator
A non-interactive status	md-badge / md-status-dot
Choosing among labelled options	md-radio / md-segmented-button

Decision cues

Need	Setting
A star scale the user sets	Default (interactive)
Display-only average	readonly
Half stars	precision="0.5"
More or fewer items	max
A numeric readout	show-value-label
Different glyphs	icon / empty-icon
No hover preview	hover="off"
Smaller glyphs	size, or --md-rating-item-size

Sizes

Five sizes. The default is md, unlike md-button which defaults to sm.

xs / sm / md (default) / lg / xl 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-rating value="3" size="xs" rating-label="Extra small"></md-rating>
<md-rating value="3" size="sm" rating-label="Small"></md-rating>
<md-rating value="3" size="md" rating-label="Medium"></md-rating>
<md-rating value="3" size="lg" rating-label="Large"></md-rating>
<md-rating value="3" size="xl" rating-label="Extra large"></md-rating>

Copy

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

export function Demo() {
  return (
    <>
      <MdRating value="3" size="xs" ratingLabel="Extra small"></MdRating>
      <MdRating value="3" size="sm" ratingLabel="Small"></MdRating>
      <MdRating value="3" size="md" ratingLabel="Medium"></MdRating>
      <MdRating value="3" size="lg" ratingLabel="Large"></MdRating>
      <MdRating value="3" size="xl" ratingLabel="Extra large"></MdRating>
    </>
  );
}

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 -->
<md-rating value="3" size="xs" rating-label="Extra small"></md-rating>
<md-rating value="3" size="sm" rating-label="Small"></md-rating>
<md-rating value="3" size="md" rating-label="Medium"></md-rating>
<md-rating value="3" size="lg" rating-label="Large"></md-rating>
<md-rating value="3" size="xl" rating-label="Extra large"></md-rating>

Copy

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

<template>
  <md-rating value="3" size="xs" rating-label="Extra small"></md-rating>
  <md-rating value="3" size="sm" rating-label="Small"></md-rating>
  <md-rating value="3" size="md" rating-label="Medium"></md-rating>
  <md-rating value="3" size="lg" rating-label="Large"></md-rating>
  <md-rating value="3" size="xl" rating-label="Extra large"></md-rating>
</template>

Copy

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

<md-rating value="3" size="xs" rating-label="Extra small"></md-rating>
<md-rating value="3" size="sm" rating-label="Small"></md-rating>
<md-rating value="3" size="md" rating-label="Medium"></md-rating>
<md-rating value="3" size="lg" rating-label="Large"></md-rating>
<md-rating value="3" size="xl" rating-label="Extra large"></md-rating>

Check the per-item hit target at small size and deep density — a 5-item scale at xs gives very small targets on touch.

Precision and scale

precision is 1 (whole steps) or 0.5 (half steps). With 0.5 the value is fractional — don’t assume an integer.

max sets the number of items and defaults to 5. Keep it small; a 20-star scale belongs in a md-slider.

Whole steps, half steps, and a wider max 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-rating value="3" precision="1" show-value-label rating-label="Whole steps"></md-rating>
<md-rating value="3.5" precision="0.5" show-value-label rating-label="Half steps"></md-rating>
<md-rating value="7" max="10" show-value-label rating-label="Ten point scale"></md-rating>

Copy

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

export function Demo() {
  return (
    <>
      <MdRating value="3" precision="1" showValueLabel ratingLabel="Whole steps"></MdRating>
      <MdRating value="3.5" precision="0.5" showValueLabel ratingLabel="Half steps"></MdRating>
      <MdRating value="7" max="10" showValueLabel ratingLabel="Ten point scale"></MdRating>
    </>
  );
}

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 -->
<md-rating value="3" precision="1" show-value-label rating-label="Whole steps"></md-rating>
<md-rating value="3.5" precision="0.5" show-value-label rating-label="Half steps"></md-rating>
<md-rating value="7" max="10" show-value-label rating-label="Ten point scale"></md-rating>

Copy

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

<template>
  <md-rating value="3" precision="1" show-value-label rating-label="Whole steps"></md-rating>
  <md-rating value="3.5" precision="0.5" show-value-label rating-label="Half steps"></md-rating>
  <md-rating value="7" max="10" show-value-label rating-label="Ten point scale"></md-rating>
</template>

Copy

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

<md-rating value="3" precision="1" show-value-label rating-label="Whole steps"></md-rating>
<md-rating value="3.5" precision="0.5" show-value-label rating-label="Half steps"></md-rating>
<md-rating value="7" max="10" show-value-label rating-label="Ten point scale"></md-rating>

Value label

show-value-label prints the numeric value beside the glyphs. Pair it with readonly for aggregate scores — glyph count alone is not precise enough to communicate an average.

Numeric value label 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-rating value="4" show-value-label rating-label="With value label"></md-rating>
<md-rating value="2.5" precision="0.5" show-value-label rating-label="Fractional value label"></md-rating>

Copy

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

export function Demo() {
  return (
    <>
      <MdRating value="4" showValueLabel ratingLabel="With value label"></MdRating>
      <MdRating value="2.5" precision="0.5" showValueLabel ratingLabel="Fractional value label"></MdRating>
    </>
  );
}

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 -->
<md-rating value="4" show-value-label rating-label="With value label"></md-rating>
<md-rating value="2.5" precision="0.5" show-value-label rating-label="Fractional value label"></md-rating>

Copy

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

<template>
  <md-rating value="4" show-value-label rating-label="With value label"></md-rating>
  <md-rating value="2.5" precision="0.5" show-value-label rating-label="Fractional value label"></md-rating>
</template>

Copy

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

<md-rating value="4" show-value-label rating-label="With value label"></md-rating>
<md-rating value="2.5" precision="0.5" show-value-label rating-label="Fractional value label"></md-rating>

States

readonly still renders and announces the score but blocks interaction (and switches the internal role to img). disabled also greys it out and drops it from the tab order; soft-disabled stays focusable so keyboard users can discover it.

Enabled / readonly / disabled / soft-disabled — try tabbing through 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-rating value="4" rating-label="Enabled"></md-rating>
<md-rating value="4" readonly rating-label="Read-only"></md-rating>
<md-rating value="4" disabled rating-label="Disabled"></md-rating>
<md-rating value="4" soft-disabled rating-label="Soft-disabled"></md-rating>

Copy

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

export function Demo() {
  return (
    <>
      <MdRating value="4" ratingLabel="Enabled"></MdRating>
      <MdRating value="4" readonly ratingLabel="Read-only"></MdRating>
      <MdRating value="4" disabled ratingLabel="Disabled"></MdRating>
      <MdRating value="4" softDisabled ratingLabel="Soft-disabled"></MdRating>
    </>
  );
}

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 -->
<md-rating value="4" rating-label="Enabled"></md-rating>
<md-rating value="4" readonly rating-label="Read-only"></md-rating>
<md-rating value="4" disabled rating-label="Disabled"></md-rating>
<md-rating value="4" soft-disabled rating-label="Soft-disabled"></md-rating>

Copy

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

<template>
  <md-rating value="4" rating-label="Enabled"></md-rating>
  <md-rating value="4" readonly rating-label="Read-only"></md-rating>
  <md-rating value="4" disabled rating-label="Disabled"></md-rating>
  <md-rating value="4" soft-disabled rating-label="Soft-disabled"></md-rating>
</template>

Copy

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

<md-rating value="4" rating-label="Enabled"></md-rating>
<md-rating value="4" readonly rating-label="Read-only"></md-rating>
<md-rating value="4" disabled rating-label="Disabled"></md-rating>
<md-rating value="4" soft-disabled rating-label="Soft-disabled"></md-rating>

Displaying an average without readonly

Users will think they are rating. Any score you are showing rather than collecting needs readonly.

Custom glyphs

icon and empty-icon take any Material Symbols name. outline-empty (default on) draws unfilled items as outlines; turn it off for solid empties.

Custom glyphs and solid empties Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-rating value="3" icon="star" empty-icon="star" rating-label="Stars"></md-rating>
<md-rating value="3" icon="favorite" empty-icon="favorite" rating-label="Hearts"></md-rating>
<md-rating value="3" icon="bolt" empty-icon="bolt" rating-label="Bolts"></md-rating>
<md-rating value="3" icon="local_fire_department" empty-icon="local_fire_department" rating-label="Flames"></md-rating>
<md-rating value="3" outline-empty="false" rating-label="Solid empties"></md-rating>

Copy

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdRating } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdRating value="3" icon="star" emptyIcon="star" ratingLabel="Stars"></MdRating>
      <MdRating value="3" icon="favorite" emptyIcon="favorite" ratingLabel="Hearts"></MdRating>
      <MdRating value="3" icon="bolt" emptyIcon="bolt" ratingLabel="Bolts"></MdRating>
      <MdRating value="3" icon="local_fire_department" emptyIcon="local_fire_department" ratingLabel="Flames"></MdRating>
      <MdRating value="3" outlineEmpty="false" ratingLabel="Solid empties"></MdRating>
    </>
  );
}

Copy

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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 -->
<md-rating value="3" icon="star" empty-icon="star" rating-label="Stars"></md-rating>
<md-rating value="3" icon="favorite" empty-icon="favorite" rating-label="Hearts"></md-rating>
<md-rating value="3" icon="bolt" empty-icon="bolt" rating-label="Bolts"></md-rating>
<md-rating value="3" icon="local_fire_department" empty-icon="local_fire_department" rating-label="Flames"></md-rating>
<md-rating value="3" outline-empty="false" rating-label="Solid empties"></md-rating>

Copy

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <md-rating value="3" icon="star" empty-icon="star" rating-label="Stars"></md-rating>
  <md-rating value="3" icon="favorite" empty-icon="favorite" rating-label="Hearts"></md-rating>
  <md-rating value="3" icon="bolt" empty-icon="bolt" rating-label="Bolts"></md-rating>
  <md-rating value="3" icon="local_fire_department" empty-icon="local_fire_department" rating-label="Flames"></md-rating>
  <md-rating value="3" outline-empty="false" rating-label="Solid empties"></md-rating>
</template>

Copy

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<md-rating value="3" icon="star" empty-icon="star" rating-label="Stars"></md-rating>
<md-rating value="3" icon="favorite" empty-icon="favorite" rating-label="Hearts"></md-rating>
<md-rating value="3" icon="bolt" empty-icon="bolt" rating-label="Bolts"></md-rating>
<md-rating value="3" icon="local_fire_department" empty-icon="local_fire_department" rating-label="Flames"></md-rating>
<md-rating value="3" outline-empty="false" rating-label="Solid empties"></md-rating>

Keep the glyph conventional for a score. An ambiguous icon makes the scale unreadable.

Hover preview

hover="preview" (the default) previews the value under the pointer and emits mdHover; it does not change value until a click. Set hover="off" on touch-primary or very dense surfaces.

Hover preview on and off 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-rating value="3" hover="preview" rating-label="Hover preview on"></md-rating>
<md-rating value="3" hover="off" rating-label="Hover preview off"></md-rating>

Copy

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

export function Demo() {
  return (
    <>
      <MdRating value="3" hover="preview" ratingLabel="Hover preview on"></MdRating>
      <MdRating value="3" hover="off" ratingLabel="Hover preview off"></MdRating>
    </>
  );
}

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 -->
<md-rating value="3" hover="preview" rating-label="Hover preview on"></md-rating>
<md-rating value="3" hover="off" rating-label="Hover preview off"></md-rating>

Copy

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

<template>
  <md-rating value="3" hover="preview" rating-label="Hover preview on"></md-rating>
  <md-rating value="3" hover="off" rating-label="Hover preview off"></md-rating>
</template>

Copy

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

<md-rating value="3" hover="preview" rating-label="Hover preview on"></md-rating>
<md-rating value="3" hover="off" rating-label="Hover preview off"></md-rating>

Forms

md-rating is form-associated via ElementInternals — it submits value under name with no hidden input, exactly as md-slider does. A value of 0 submits as absent rather than "0".

default-value is the clear target, not the reset target

default-value (default 0) is where the rating lands when the user clicks the item it is already sitting on — the click-to-clear escape hatch, and its only job.

A <form> reset is a separate path: formResetCallback restores the value the element was authored with, captured once at load. The demo below is authored value="4" and sets no default-value, so Reset returns it to 4, and clicking the 4th star clears it to 0.

Inside a form — submit and reset Open in Storybook

Send feedback Reset

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>

<form id="feedback">
  <md-rating name="satisfaction" value="4" show-value-label rating-label="Satisfaction"></md-rating>

  <md-button variant="filled" type="submit">Send feedback</md-button>
  <md-button variant="text" type="reset">Reset</md-button>
</form>

Copy

import { MdButton, MdRating } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <form id="feedback">
        <MdRating name="satisfaction" value="4" showValueLabel ratingLabel="Satisfaction"></MdRating>

        <MdButton variant="filled" type="submit">Send feedback</MdButton>
        <MdButton variant="text" type="reset">Reset</MdButton>
      </form>
    </>
  );
}

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 -->
<form id="feedback">
  <md-rating name="satisfaction" value="4" show-value-label rating-label="Satisfaction"></md-rating>

  <md-button variant="filled" type="submit">Send feedback</md-button>
  <md-button variant="text" type="reset">Reset</md-button>
</form>

Copy

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

<template>
  <form id="feedback">
    <md-rating name="satisfaction" value="4" show-value-label rating-label="Satisfaction"></md-rating>

    <md-button variant="filled" type="submit">Send feedback</md-button>
    <md-button variant="text" type="reset">Reset</md-button>
  </form>
</template>

Copy

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

<form id="feedback">
  <md-rating name="satisfaction" value="4" show-value-label rating-label="Satisfaction"></md-rating>

  <md-button variant="filled" type="submit">Send feedback</md-button>
  <md-button variant="text" type="reset">Reset</md-button>
</form>

Reading it back out is plain FormData — there is no wrapper API to learn:

HTML React Angular Vue Svelte

Copy

<form id="feedback">
<md-rating name="satisfaction" value="4" show-value-label rating-label="Satisfaction"></md-rating>

<md-button variant="filled" type="submit">Send feedback</md-button>
<md-button variant="text" type="reset">Reset</md-button>
</form>

<script type="module">
document.getElementById('feedback').addEventListener('submit', (e) => {
  e.preventDefault();
  const data = new FormData(e.target);
  console.log(Object.fromEntries(data));   // { satisfaction: '4' }
});
</script>

Copy

import { MdRating, MdButton } from '@awc-ui/react';

export function FeedbackForm() {
function onSubmit(e: React.FormEvent<HTMLFormElement>) {
  e.preventDefault();
  const data = new FormData(e.currentTarget);
  console.log(Object.fromEntries(data));   // { satisfaction: '4' }
}

return (
  <form onSubmit={onSubmit}>
    <MdRating name="satisfaction" value={4} showValueLabel ratingLabel="Satisfaction" />

    <MdButton variant="filled" type="submit">Send feedback</MdButton>
    <MdButton variant="text" type="reset">Reset</MdButton>
  </form>
);
}

Copy

import { Component } from '@angular/core';
// Requires AwcUiModule from '@awc-ui/angular' in the owning NgModule.

@Component({
selector: 'app-feedback-form',
template: `
  <form (submit)="onSubmit($event)">
    <md-rating name="satisfaction" [value]="4" [showValueLabel]="true"
               ratingLabel="Satisfaction"></md-rating>

    <md-button variant="filled" type="submit">Send feedback</md-button>
    <md-button variant="text" type="reset">Reset</md-button>
  </form>
`,
})
export class FeedbackFormComponent {
onSubmit(e: Event) {
  e.preventDefault();
  const data = new FormData(e.target as HTMLFormElement);
  console.log(Object.fromEntries(data));   // { satisfaction: '4' }
}
}

Copy

<script setup lang="ts">
import { MdRating, MdButton } from '@awc-ui/vue';

function onSubmit(e: Event) {
e.preventDefault();
const data = new FormData(e.target as HTMLFormElement);
console.log(Object.fromEntries(data));   // { satisfaction: '4' }
}
</script>

<template>
<form @submit="onSubmit">
  <MdRating name="satisfaction" :value="4" :showValueLabel="true" ratingLabel="Satisfaction" />

  <MdButton variant="filled" type="submit">Send feedback</MdButton>
  <MdButton variant="text" type="reset">Reset</MdButton>
</form>
</template>

Copy

<script lang="ts">
function onSubmit(e: Event) {
  e.preventDefault();
  const data = new FormData(e.target as HTMLFormElement);
  console.log(Object.fromEntries(data));   // { satisfaction: '4' }
}
</script>

<!-- Svelte assigns to the DOM property when one exists, so numeric props must
   be written as expressions: value="4" would set the STRING "4". -->
<form on:submit={onSubmit}>
<md-rating name="satisfaction" value={4} showValueLabel={true} ratingLabel="Satisfaction"></md-rating>

<md-button variant="filled" type="submit">Send feedback</md-button>
<md-button variant="text" type="reset">Reset</md-button>
</form>

getLabel is a function prop

getLabel supplies the per-value screen-reader announcement. Function props do not cross the attribute boundary, so there is no get-label attribute — set it in JS.

Pick a value — the announcement string follows it 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-rating id="rating" value="3" rating-label="Rate this product"></md-rating>

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

  // Function prop — no get-label attribute exists, so set it in JS.
  rating.getLabel = (v) => v + ' out of ' + rating.max + ' stars';
</script>

Copy

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

// Plain function — the wrapper assigns it as a property, so it goes through
// like any other prop. No ref, no effect.
const labelFor = (v: number) => v + ' out of 5 stars';

export function ProductRating() {
return <MdRating getLabel={labelFor} value={3} ratingLabel="Rate this product" />;
}

Copy

import { Component } from '@angular/core';
// Requires AwcUiModule from '@awc-ui/angular' in the owning NgModule — its
// MdRating proxy declares getLabel as an input, so it binds like any other.

@Component({
selector: 'app-product-rating',
template: `
  <md-rating [getLabel]="labelFor" [value]="3" ratingLabel="Rate this product"></md-rating>
`,
})
export class ProductRatingComponent {
labelFor = (v: number) => v + ' out of 5 stars';
}

Copy

<script setup lang="ts">
import { MdRating } from '@awc-ui/vue';

const labelFor = (v: number) => v + ' out of 5 stars';
</script>

<template>
<MdRating :getLabel="labelFor" :value="3" ratingLabel="Rate this product" />
</template>

Copy

<script lang="ts">
const labelFor = (v: number) => v + ' out of 5 stars';
</script>

<!-- Svelte assigns to the DOM property when one exists, so getLabel goes
   through as a plain prop — no bind:this, no onMount. -->
<md-rating getLabel={labelFor} value={3} ratingLabel="Rate this product"></md-rating>

Events

Event	Cancelable	Detail	Fires
mdHover	no	number | null	Hover preview changes; null on leave
mdChange	no	number	A rating is committed

“Cancelable” here means veto honoured. Both are declared as bare @Event()s, so Stencil emits them with its default cancelable: true — preventDefault() succeeds and defaultPrevented reads true. The component never checks it — mdHover is a bare notification, and mdChange is emitted after value has already been assigned. To reject a score, write the previous one back to value in your handler.

mdHover is a preview — never read it as the chosen value.

You want to…	Listen to
Store the score the user picked	mdChange
Paint a live “you are about to pick 4” caption	mdHover
Clear that caption when the pointer leaves	mdHover with detail === null
React to rating.value = 4 set from your own code	Neither — no event fires

Both events bubble and are composed, so one delegated listener on an ancestor catches every rating. Sweep the pointer across the stars, then click:

mdHover previews, mdChange commits

Hover across the stars, then click one.

Show code for each technology

HTML React Angular Vue Svelte

Copy

<md-rating id="score" precision="0.5" show-value-label name="score" rating-label="Rate this product"></md-rating>

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

// Function prop — no get-label attribute exists, so assign it in JS.
r.getLabel = (v) => v + ' out of ' + r.max + ' stars';

r.addEventListener('mdChange', (e) => submitScore(e.detail));
r.addEventListener('mdHover', (e) => preview(e.detail));   // null on leave
</script>

Copy

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

const labelFor = (v: number) => v + ' out of 5 stars';

export function ProductRating() {
// getLabel is a FUNCTION prop; the wrapper assigns it as a property, so it
// goes through as a prop like any other. No ref, no effect.
return (
  <MdRating
    getLabel={labelFor}
    precision={0.5}
    showValueLabel
    name="score"
    ratingLabel="Rate this product"
    onMdChange={(e) => submitScore(e.detail)}
    onMdHover={(e) => preview(e.detail)}
  />
);
}

Copy

import { Component } from '@angular/core';
// Requires AwcUiModule from '@awc-ui/angular' in the owning NgModule — its
// MdRating proxy declares getLabel as an input, so it binds like any other.

@Component({
selector: 'app-product-rating',
template: `
  <md-rating
    [getLabel]="labelFor"
    [precision]="0.5"
    [showValueLabel]="true"
    name="score"
    ratingLabel="Rate this product"
    (mdChange)="onChange($event)"
    (mdHover)="onHover($event)"
  ></md-rating>
`,
})
export class ProductRatingComponent {
labelFor = (v: number) => v + ' out of 5 stars';

onChange(e: CustomEvent<number>) { submitScore(e.detail); }
onHover(e: CustomEvent<number | null>) { preview(e.detail); }
}

Copy

<script setup lang="ts">
import { MdRating } from '@awc-ui/vue';

const labelFor = (v: number) => v + ' out of 5 stars';

function onChange(e: CustomEvent<number>) { submitScore(e.detail); }
function onHover(e: CustomEvent<number | null>) { preview(e.detail); }
</script>

<template>
<MdRating
  :getLabel="labelFor"
  :precision="0.5"
  :showValueLabel="true"
  name="score"
  ratingLabel="Rate this product"
  @mdChange="onChange"
  @mdHover="onHover"
/>
</template>

Copy

<script lang="ts">
const labelFor = (v: number) => v + ' out of 5 stars';

function onChange(e: CustomEvent<number>) { submitScore(e.detail); }
function onHover(e: CustomEvent<number | null>) { preview(e.detail); }
</script>

<!-- Svelte assigns to the DOM property when one exists, so getLabel goes
   through as a plain prop — no bind:this, no onMount. -->
<md-rating
getLabel={labelFor}
precision={0.5}
showValueLabel={true}
name="score"
ratingLabel="Rate this product"
on:mdChange={onChange}
on:mdHover={onHover}
></md-rating>

API Reference

tune

Properties

Property	Attribute	Type	Default	Reflects
value	value	number	0	Yes
defaultValue	default-value	number	0	—
max	max	number	5	Yes
precision	precision	1 | 0.5	1	Yes
size	size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Yes
readonly	readonly	boolean	false	Yes
disabled	disabled	boolean	false	Yes
softDisabled	soft-disabled	boolean	false	Yes
icon	icon	string	'star'	—
emptyIcon	empty-icon	string	'star'	—
outlineEmpty	outline-empty	boolean	true	Yes
getLabel	JS only	(value: number) => string	—	—
showValueLabel	show-value-label	boolean	false	Yes
ratingLabel	rating-label	string	'Rating'	—
name	name	string	''	Yes
hover	hover	'preview' | 'off'	'preview'	Yes
density	density	0 | -1 | -2 | -3 | -4	0	Yes

function

Methods

Method	Parameters
focusRating()	none

palette

CSS Custom Properties

Override on the host element for per-instance theming:

Property	Description
--md-rating-item-size	Icon dimension (per `size`)
--md-rating-item-gap	Space between items
--md-rating-active-color	Filled icon color
--md-rating-inactive-color	Empty icon color
--md-rating-focus-ring-color	Focus ring color
--md-rating-focus-ring-width	Focus ring width
--md-rating-focus-ring-offset	Focus ring offset
--md-rating-state-layer-color	Hover / press overlay color
--md-rating-value-label-color	Color of the inline value label
--md-rating-value-label-font	Font of the value label
--md-rating-pop-scale	Scale on hover/active (MD3 Expressive)
--md-rating-duration	Animation duration
--md-rating-icon-font-family	—

layers

CSS Shadow Parts

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

Part	Description
icon-empty	The background (outline) icon
icon-filled	The clipped foreground (filled) icon
state-layer	Hover / press overlay — a filled glyph tracing the icon shape
ripple	Press ripple — a glyph-clipped expanding circle
items	The slider container
value-label	The inline numeric value label

Accessibility

• rating-label names the control (default "Rating"); getLabel supplies the per-value announcement — set both.
• Keyboard: arrow keys move through the scale by one precision step, Home clears to 0, End jumps to max, and a digit key 0–9 sets that value outright when it is within max. Every other key (Tab, Escape) is left alone so a dialog or menu ancestor can still act on it. focusRating() focuses the control programmatically.
• Filled vs empty is conveyed by glyph fill, not colour alone — keep outline-empty on unless you have another cue.
• readonly stays readable to assistive tech (role="img"); disabled leaves the tab order (tabindex="-1"), while soft-disabled keeps tabindex="0".
• Check the per-item hit target at small size and deep density.

The focusable node is the shadow-internal slider, so an IDREF can’t reach it from outside. The component resolves the name for you instead, in this order: host aria-labelledby → host aria-label → an associated <label for> (via ElementInternals.labels) → the rating-label prop. Tab through these — the first three announce three different names, the soft-disabled one still takes focus, and the disabled one is skipped:

Naming sources, and who stays in the tab order

default label rating-label aria-labelledby

Product quality

soft-disabled disabled readonly

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:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">default label</span>
  <md-rating value="3"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rating-label</span>
  <md-rating value="3" rating-label="Overall satisfaction"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-labelledby</span>
  <div style="display:flex;gap:10px;align-items:center;flex-wrap:wrap;">
    <span id="rating-a11y-ext" style="font: var(--md-sys-typescale-body-small); color: var(--md-sys-color-on-surface-variant);">Product quality</span>
    <md-rating value="3" aria-labelledby="rating-a11y-ext"></md-rating>
  </div>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">soft-disabled</span>
  <md-rating value="3" soft-disabled rating-label="Soft-disabled — still focusable"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">disabled</span>
  <md-rating value="3" disabled rating-label="Disabled — skipped"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">readonly</span>
  <md-rating value="3" readonly rating-label="Average rating"></md-rating>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>default label</span>
        <MdRating value="3"></MdRating>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>rating-label</span>
        <MdRating value="3" ratingLabel="Overall satisfaction"></MdRating>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>aria-labelledby</span>
        <div style={{ display: 'flex', gap: '10px', alignItems: 'center', flexWrap: 'wrap' }}>
          <span id="rating-a11y-ext" style={{ font: 'var(--md-sys-typescale-body-small)', color: 'var(--md-sys-color-on-surface-variant)' }}>Product quality</span>
          <MdRating value="3" aria-labelledby="rating-a11y-ext"></MdRating>
        </div>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>soft-disabled</span>
        <MdRating value="3" softDisabled ratingLabel="Soft-disabled — still focusable"></MdRating>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>disabled</span>
        <MdRating value="3" disabled ratingLabel="Disabled — skipped"></MdRating>
        <span style={{ inlineSize: '9rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>readonly</span>
        <MdRating value="3" readonly ratingLabel="Average rating"></MdRating>
      </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:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">default label</span>
  <md-rating value="3"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rating-label</span>
  <md-rating value="3" rating-label="Overall satisfaction"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-labelledby</span>
  <div style="display:flex;gap:10px;align-items:center;flex-wrap:wrap;">
    <span id="rating-a11y-ext" style="font: var(--md-sys-typescale-body-small); color: var(--md-sys-color-on-surface-variant);">Product quality</span>
    <md-rating value="3" aria-labelledby="rating-a11y-ext"></md-rating>
  </div>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">soft-disabled</span>
  <md-rating value="3" soft-disabled rating-label="Soft-disabled — still focusable"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">disabled</span>
  <md-rating value="3" disabled rating-label="Disabled — skipped"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">readonly</span>
  <md-rating value="3" readonly rating-label="Average rating"></md-rating>
</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:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">default label</span>
    <md-rating value="3"></md-rating>
    <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rating-label</span>
    <md-rating value="3" rating-label="Overall satisfaction"></md-rating>
    <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-labelledby</span>
    <div style="display:flex;gap:10px;align-items:center;flex-wrap:wrap;">
      <span id="rating-a11y-ext" style="font: var(--md-sys-typescale-body-small); color: var(--md-sys-color-on-surface-variant);">Product quality</span>
      <md-rating value="3" aria-labelledby="rating-a11y-ext"></md-rating>
    </div>
    <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">soft-disabled</span>
    <md-rating value="3" soft-disabled rating-label="Soft-disabled — still focusable"></md-rating>
    <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">disabled</span>
    <md-rating value="3" disabled rating-label="Disabled — skipped"></md-rating>
    <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">readonly</span>
    <md-rating value="3" readonly rating-label="Average rating"></md-rating>
  </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:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">default label</span>
  <md-rating value="3"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">rating-label</span>
  <md-rating value="3" rating-label="Overall satisfaction"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">aria-labelledby</span>
  <div style="display:flex;gap:10px;align-items:center;flex-wrap:wrap;">
    <span id="rating-a11y-ext" style="font: var(--md-sys-typescale-body-small); color: var(--md-sys-color-on-surface-variant);">Product quality</span>
    <md-rating value="3" aria-labelledby="rating-a11y-ext"></md-rating>
  </div>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">soft-disabled</span>
  <md-rating value="3" soft-disabled rating-label="Soft-disabled — still focusable"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">disabled</span>
  <md-rating value="3" disabled rating-label="Disabled — skipped"></md-rating>
  <span style="inline-size:9rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">readonly</span>
  <md-rating value="3" readonly rating-label="Average rating"></md-rating>
</div>

The last row is the one to sanity-check with a screen reader: readonly switches the internal role from slider to img, which ignores aria-valuetext, so the score is folded into the accessible name instead — “Average rating: 3 Stars”.

RTL, density & i18n

RTL — under dir="rtl" the input axis mirrors and the glyph row does not. Nothing opts in, but the two halves read different signals:

Under dir="rtl"	What happens	Driven by
ArrowRight / ArrowLeft	Swap — ArrowRight walks down the scale	Computed direction (JS)
Pointer half/full split within an item	Mirrors — the trailing (left) edge of a glyph now means full	Computed direction (JS)
Value label	Moves to the left of the glyphs	Host inherits direction: rtl
Order of the glyphs	Unchanged — item 1 stays on the left	See below
The rendered half-fill inside one glyph	Unchanged — always fills from the glyph’s physical left	clip-path: inset() is physical, and the glyph spans force direction: ltr

The row order is the surprise. The stylesheet mirrors it with flex-direction: row-reverse, but that container has also inherited direction: rtl from the host, and under RTL a flex row already runs right-to-left — so the two reversals cancel and the glyphs land back in physical left-to-right order. Measured in Chrome, the five item left edges under an inherited dir="rtl" come out ascending: item 1 is the leftmost.

One more asymmetry worth knowing: the JS reads the computed direction, while the CSS mirror keys off a dir attribute on the host or an ancestor. A container styled direction: rtl in CSS with no dir attribute therefore flips the keyboard and pointer maths and leaves the flex rule out of it entirely. Set the attribute, not the property. See RTL.

<div dir="rtl">
  <md-rating value="2.5" precision="0.5" show-value-label rating-label="التقييم"></md-rating>
</div>

The same ratings in both directions. Nothing is re-authored between the two rows — only dir and the translated labels change. Compare them carefully: within each rating the stars sit in the same order in both rows, and only the value label crosses to the other side of its glyphs. (The three ratings as a group do reorder in the rtl row — that is the wrapping flex container, not the component.) The rest of the mirroring is in the keyboard and pointer maths, which a screenshot cannot show — focus a star in the rtl row and press ArrowRight to see it count down.

Same markup, dir=ltr vs dir=rtl — the value label swaps sides, the glyph order does not Open in Storybook

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:center;">
    <md-rating value="3" rating-label="Rating"></md-rating>
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="Average"></md-rating>
    <md-rating value="4" readonly show-value-label rating-label="Read-only"></md-rating>
  </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:center;">
    <md-rating value="3" rating-label="التقييم"></md-rating>
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating value="4" readonly show-value-label rating-label="للقراءة فقط"></md-rating>
  </div>
</div>

Copy

import { MdRating } 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: 'center' }}>
          <MdRating value="3" ratingLabel="Rating"></MdRating>
          <MdRating value="2.5" precision="0.5" showValueLabel ratingLabel="Average"></MdRating>
          <MdRating value="4" readonly showValueLabel ratingLabel="Read-only"></MdRating>
        </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: 'center' }}>
          <MdRating value="3" ratingLabel="التقييم"></MdRating>
          <MdRating value="2.5" precision="0.5" showValueLabel ratingLabel="المتوسط"></MdRating>
          <MdRating value="4" readonly showValueLabel ratingLabel="للقراءة فقط"></MdRating>
        </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:center;">
    <md-rating value="3" rating-label="Rating"></md-rating>
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="Average"></md-rating>
    <md-rating value="4" readonly show-value-label rating-label="Read-only"></md-rating>
  </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:center;">
    <md-rating value="3" rating-label="التقييم"></md-rating>
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating value="4" readonly show-value-label rating-label="للقراءة فقط"></md-rating>
  </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:center;">
      <md-rating value="3" rating-label="Rating"></md-rating>
      <md-rating value="2.5" precision="0.5" show-value-label rating-label="Average"></md-rating>
      <md-rating value="4" readonly show-value-label rating-label="Read-only"></md-rating>
    </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:center;">
      <md-rating value="3" rating-label="التقييم"></md-rating>
      <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
      <md-rating value="4" readonly show-value-label rating-label="للقراءة فقط"></md-rating>
    </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:center;">
    <md-rating value="3" rating-label="Rating"></md-rating>
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="Average"></md-rating>
    <md-rating value="4" readonly show-value-label rating-label="Read-only"></md-rating>
  </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:center;">
    <md-rating value="3" rating-label="التقييم"></md-rating>
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating value="4" readonly show-value-label rating-label="للقراءة فقط"></md-rating>
  </div>
</div>

Don’t pin dir on the rating — let it inherit

Pinning dir="ltr" on a rating inside an RTL block is worse than a no-op: it splits the control against itself. :host-context([dir="rtl"]) matches when the host or any ancestor carries the attribute, so the pinned rating still gets flex-direction: row-reverse from the container — but its own computed direction is now ltr, so nothing cancels it. Measured in Chrome, the pinned row’s five item left edges come out descending: item 1 lands on the right. Meanwhile the JS, reading that same ltr, leaves the arrow keys and the pointer split unmirrored.

The result is a control whose glyphs run one way and whose input runs the other: ArrowRight counts up while the scale climbs leftward. Compare the two rows, both inside the same dir="rtl" container:

Inherit dir, don't pin it — the wrong row is the reversed one, and its arrow keys disagree with it

correct

wrong

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" style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating value="3" rating-label="التقييم"></md-rating>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
    <md-rating dir="ltr" value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating dir="ltr" value="3" rating-label="التقييم"></md-rating>
  </div>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div dir="rtl" style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '14px 16px', alignItems: 'center' }}>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>correct</span>
        <div style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdRating value="2.5" precision="0.5" showValueLabel ratingLabel="المتوسط"></MdRating>
          <MdRating value="3" ratingLabel="التقييم"></MdRating>
        </div>
        <span style={{ inlineSize: '4.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>wrong</span>
        <div style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'center' }}>
          <MdRating dir="ltr" value="2.5" precision="0.5" showValueLabel ratingLabel="المتوسط"></MdRating>
          <MdRating dir="ltr" value="3" ratingLabel="التقييم"></MdRating>
        </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 dir="rtl" style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating value="3" rating-label="التقييم"></md-rating>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
    <md-rating dir="ltr" value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating dir="ltr" value="3" rating-label="التقييم"></md-rating>
  </div>
</div>

Copy

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

<template>
  <div dir="rtl" style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
    <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
      <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
      <md-rating value="3" rating-label="التقييم"></md-rating>
    </div>
    <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
    <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
      <md-rating dir="ltr" value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
      <md-rating dir="ltr" value="3" rating-label="التقييم"></md-rating>
    </div>
  </div>
</template>

Copy

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

<div dir="rtl" style="display:grid;grid-template-columns:auto 1fr;gap:14px 16px;align-items:center;">
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating value="3" rating-label="التقييم"></md-rating>
  </div>
  <span style="inline-size:4.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
    <md-rating dir="ltr" value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating dir="ltr" value="3" rating-label="التقييم"></md-rating>
  </div>
</div>

Every density rung

density="-1…-4" is a local override of the inherited data-density. It drives the same --md-sys-density-scale signal, tapering the glyph size and the gap between items. 0 is the default value rather than a rung of its own, so the first row below is what you get with no attribute at all:

Density 0 through -4 — glyph size and item gap both taper

0

-1

-2

-3

-4

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;">0</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="0" value="3" rating-label="Density 0"></md-rating><md-rating density="0" value="3.5" precision="0.5" show-value-label rating-label="Density 0 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-1" value="3" rating-label="Density -1"></md-rating><md-rating density="-1" value="3.5" precision="0.5" show-value-label rating-label="Density -1 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-2" value="3" rating-label="Density -2"></md-rating><md-rating density="-2" value="3.5" precision="0.5" show-value-label rating-label="Density -2 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-3" value="3" rating-label="Density -3"></md-rating><md-rating density="-3" value="3.5" precision="0.5" show-value-label rating-label="Density -3 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-4" value="3" rating-label="Density -4"></md-rating><md-rating density="-4" value="3.5" precision="0.5" show-value-label rating-label="Density -4 with label"></md-rating></div>
</div>

Copy

import { MdRating } 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' }}>0</span>
        <div style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'center' }}><MdRating density="0" value="3" ratingLabel="Density 0"></MdRating><MdRating density="0" value="3.5" precision="0.5" showValueLabel ratingLabel="Density 0 with label"></MdRating></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-1</span>
        <div style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'center' }}><MdRating density="-1" value="3" ratingLabel="Density -1"></MdRating><MdRating density="-1" value="3.5" precision="0.5" showValueLabel ratingLabel="Density -1 with label"></MdRating></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-2</span>
        <div style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'center' }}><MdRating density="-2" value="3" ratingLabel="Density -2"></MdRating><MdRating density="-2" value="3.5" precision="0.5" showValueLabel ratingLabel="Density -2 with label"></MdRating></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-3</span>
        <div style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'center' }}><MdRating density="-3" value="3" ratingLabel="Density -3"></MdRating><MdRating density="-3" value="3.5" precision="0.5" showValueLabel ratingLabel="Density -3 with label"></MdRating></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-4</span>
        <div style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'center' }}><MdRating density="-4" value="3" ratingLabel="Density -4"></MdRating><MdRating density="-4" value="3.5" precision="0.5" showValueLabel ratingLabel="Density -4 with label"></MdRating></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;">0</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="0" value="3" rating-label="Density 0"></md-rating><md-rating density="0" value="3.5" precision="0.5" show-value-label rating-label="Density 0 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-1" value="3" rating-label="Density -1"></md-rating><md-rating density="-1" value="3.5" precision="0.5" show-value-label rating-label="Density -1 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-2" value="3" rating-label="Density -2"></md-rating><md-rating density="-2" value="3.5" precision="0.5" show-value-label rating-label="Density -2 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-3" value="3" rating-label="Density -3"></md-rating><md-rating density="-3" value="3.5" precision="0.5" show-value-label rating-label="Density -3 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-4" value="3" rating-label="Density -4"></md-rating><md-rating density="-4" value="3.5" precision="0.5" show-value-label rating-label="Density -4 with label"></md-rating></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;">0</span>
    <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="0" value="3" rating-label="Density 0"></md-rating><md-rating density="0" value="3.5" precision="0.5" show-value-label rating-label="Density 0 with label"></md-rating></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
    <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-1" value="3" rating-label="Density -1"></md-rating><md-rating density="-1" value="3.5" precision="0.5" show-value-label rating-label="Density -1 with label"></md-rating></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
    <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-2" value="3" rating-label="Density -2"></md-rating><md-rating density="-2" value="3.5" precision="0.5" show-value-label rating-label="Density -2 with label"></md-rating></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
    <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-3" value="3" rating-label="Density -3"></md-rating><md-rating density="-3" value="3.5" precision="0.5" show-value-label rating-label="Density -3 with label"></md-rating></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
    <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-4" value="3" rating-label="Density -4"></md-rating><md-rating density="-4" value="3.5" precision="0.5" show-value-label rating-label="Density -4 with label"></md-rating></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;">0</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="0" value="3" rating-label="Density 0"></md-rating><md-rating density="0" value="3.5" precision="0.5" show-value-label rating-label="Density 0 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-1" value="3" rating-label="Density -1"></md-rating><md-rating density="-1" value="3.5" precision="0.5" show-value-label rating-label="Density -1 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-2" value="3" rating-label="Density -2"></md-rating><md-rating density="-2" value="3.5" precision="0.5" show-value-label rating-label="Density -2 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-3" value="3" rating-label="Density -3"></md-rating><md-rating density="-3" value="3.5" precision="0.5" show-value-label rating-label="Density -3 with label"></md-rating></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;"><md-rating density="-4" value="3" rating-label="Density -4"></md-rating><md-rating density="-4" value="3.5" precision="0.5" show-value-label rating-label="Density -4 with label"></md-rating></div>
</div>

Below -2, check your touch targets

Each rung takes 2px off the glyph, so the default md item goes from 28px at 0 to 20px at -4 — and every item is its own hit target, sitting next to four neighbours. That is far under the 48px pointer-coarse devices want, and precision="0.5" halves it again by splitting each item into two zones. On touch surfaces, pair a shallow rung with a larger size (or --md-rating-item-size) rather than shrinking both. See Density.

Density and direction together

The two are independent signals, so they compose without extra wiring — a wrapper sets the rung for everything inside it, and any one rating can take a tighter rung of its own.

density="0" is not an opt-out

Only -1 through -4 have a rule — there is deliberately no :host([density="0"]) and no [data-density="0"]. Because --md-sys-density-scale is an inherited custom property, a rating written density="0" inside a data-density="-2" wrapper still inherits -2 and draws 24px glyphs like its neighbours. To restore the default rung on one element, reset the signal directly: style="--md-sys-density-scale: 0".

dir=rtl with data-density=-2: three inherit, one tightens to -4, one resets the signal to 0

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;gap:24px;flex-wrap:wrap;align-items:center;">
  <md-rating value="3" rating-label="التقييم"></md-rating>
  <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
  <md-rating value="4" readonly show-value-label rating-label="للقراءة فقط"></md-rating>
  <md-rating value="3" density="-4" rating-label="أكثر إحكاما"></md-rating>
  <md-rating value="3" rating-label="افتراضي" style="--md-sys-density-scale: 0;"></md-rating>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div dir="rtl" data-density="-2" style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'center' }}>
        <MdRating value="3" ratingLabel="التقييم"></MdRating>
        <MdRating value="2.5" precision="0.5" showValueLabel ratingLabel="المتوسط"></MdRating>
        <MdRating value="4" readonly showValueLabel ratingLabel="للقراءة فقط"></MdRating>
        <MdRating value="3" density="-4" ratingLabel="أكثر إحكاما"></MdRating>
        <MdRating value="3" ratingLabel="افتراضي" style={{ '--md-sys-density-scale': '0' }}></MdRating>
      </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;gap:24px;flex-wrap:wrap;align-items:center;">
  <md-rating value="3" rating-label="التقييم"></md-rating>
  <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
  <md-rating value="4" readonly show-value-label rating-label="للقراءة فقط"></md-rating>
  <md-rating value="3" density="-4" rating-label="أكثر إحكاما"></md-rating>
  <md-rating value="3" rating-label="افتراضي" style="--md-sys-density-scale: 0;"></md-rating>
</div>

Copy

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

<template>
  <div dir="rtl" data-density="-2" style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
    <md-rating value="3" rating-label="التقييم"></md-rating>
    <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
    <md-rating value="4" readonly show-value-label rating-label="للقراءة فقط"></md-rating>
    <md-rating value="3" density="-4" rating-label="أكثر إحكاما"></md-rating>
    <md-rating value="3" rating-label="افتراضي" style="--md-sys-density-scale: 0;"></md-rating>
  </div>
</template>

Copy

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

<div dir="rtl" data-density="-2" style="display:flex;gap:24px;flex-wrap:wrap;align-items:center;">
  <md-rating value="3" rating-label="التقييم"></md-rating>
  <md-rating value="2.5" precision="0.5" show-value-label rating-label="المتوسط"></md-rating>
  <md-rating value="4" readonly show-value-label rating-label="للقراءة فقط"></md-rating>
  <md-rating value="3" density="-4" rating-label="أكثر إحكاما"></md-rating>
  <md-rating value="3" rating-label="افتراضي" style="--md-sys-density-scale: 0;"></md-rating>
</div>

Density — density="-1…-4" locally overrides the inherited data-density rung; 0 is the default value, not an override. See Density.

i18n — translate rating-label, and make getLabel locale-aware (pluralization: “1 star” vs “2 stars”). Format the number with Intl when show-value-label is on.

Theming

Custom property	Purpose	Default
--md-rating-item-size	Glyph size	Per size (16–48px)
--md-rating-item-gap	Spacing between items	4px
--md-rating-active-color	Filled glyph colour	secondary
--md-rating-inactive-color	Empty glyph colour	on-surface-variant at 30%
--md-rating-focus-ring-color / -width / -offset	Focus ring	secondary / 3px / 2px
--md-rating-state-layer-color	Hover / press overlay	on-surface
--md-rating-value-label-color / -font	Numeric label	on-surface
--md-rating-pop-scale / --md-rating-duration	Selection animation	1.12 / 150ms
--md-rating-icon-font-family	Glyph font	Material Symbols

Themed instances Open in Storybook

Show code for each technology

HTML React Angular Vue Svelte

Copy

<!-- index.html <head> — the icon font the components draw from -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

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

<md-rating value="4" icon="favorite" empty-icon="favorite" rating-label="Error toned" style="--md-rating-active-color: var(--md-sys-color-error); --md-rating-inactive-color: var(--md-sys-color-error-container);"></md-rating>
<md-rating value="3" show-value-label rating-label="Wide gap" style="--md-rating-item-gap: 16px; --md-rating-item-size: 32px;"></md-rating>

Copy

// Icons need the Material Symbols stylesheet in index.html — see Installation.
import { MdRating } from '@awc-ui/react';

export function Demo() {
  return (
    <>
      <MdRating value="4" icon="favorite" emptyIcon="favorite" ratingLabel="Error toned" style={{ '--md-rating-active-color': 'var(--md-sys-color-error)', '--md-rating-inactive-color': 'var(--md-sys-color-error-container)' }}></MdRating>
      <MdRating value="3" showValueLabel ratingLabel="Wide gap" style={{ '--md-rating-item-gap': '16px', '--md-rating-item-size': '32px' }}></MdRating>
    </>
  );
}

Copy

// Icons need the Material Symbols stylesheet in index.html — see Installation.
// 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 -->
<md-rating value="4" icon="favorite" empty-icon="favorite" rating-label="Error toned" style="--md-rating-active-color: var(--md-sys-color-error); --md-rating-inactive-color: var(--md-sys-color-error-container);"></md-rating>
<md-rating value="3" show-value-label rating-label="Wide gap" style="--md-rating-item-gap: 16px; --md-rating-item-size: 32px;"></md-rating>

Copy

<script setup>
// Icons need the Material Symbols stylesheet in index.html — see Installation.
import '@awc-ui/core/define';
</script>

<template>
  <md-rating value="4" icon="favorite" empty-icon="favorite" rating-label="Error toned" style="--md-rating-active-color: var(--md-sys-color-error); --md-rating-inactive-color: var(--md-sys-color-error-container);"></md-rating>
  <md-rating value="3" show-value-label rating-label="Wide gap" style="--md-rating-item-gap: 16px; --md-rating-item-size: 32px;"></md-rating>
</template>

Copy

<script>
  // Icons need the Material Symbols stylesheet in index.html — see Installation.

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

<md-rating value="4" icon="favorite" empty-icon="favorite" rating-label="Error toned" style="--md-rating-active-color: var(--md-sys-color-error); --md-rating-inactive-color: var(--md-sys-color-error-container);"></md-rating>
<md-rating value="3" show-value-label rating-label="Wide gap" style="--md-rating-item-gap: 16px; --md-rating-item-size: 32px;"></md-rating>

Every default resolves through an md-sys-color role, so a rating that sets no custom properties follows the theme on its own:

Untouched defaults — follows the page theme 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;gap:20px;flex-wrap:wrap;align-items:center;">
  <md-rating value="4" rating-label="Untouched defaults"></md-rating>
  <md-rating value="3.5" precision="0.5" show-value-label rating-label="Half steps"></md-rating>
  <md-rating value="5" readonly rating-label="Read-only"></md-rating>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '20px', flexWrap: 'wrap', alignItems: 'center' }}>
        <MdRating value="4" ratingLabel="Untouched defaults"></MdRating>
        <MdRating value="3.5" precision="0.5" showValueLabel ratingLabel="Half steps"></MdRating>
        <MdRating value="5" readonly ratingLabel="Read-only"></MdRating>
      </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;gap:20px;flex-wrap:wrap;align-items:center;">
  <md-rating value="4" rating-label="Untouched defaults"></md-rating>
  <md-rating value="3.5" precision="0.5" show-value-label rating-label="Half steps"></md-rating>
  <md-rating value="5" readonly rating-label="Read-only"></md-rating>
</div>

Copy

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

<template>
  <div style="display:flex;gap:20px;flex-wrap:wrap;align-items:center;">
    <md-rating value="4" rating-label="Untouched defaults"></md-rating>
    <md-rating value="3.5" precision="0.5" show-value-label rating-label="Half steps"></md-rating>
    <md-rating value="5" readonly rating-label="Read-only"></md-rating>
  </div>
</template>

Copy

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

<div style="display:flex;gap:20px;flex-wrap:wrap;align-items:center;">
  <md-rating value="4" rating-label="Untouched defaults"></md-rating>
  <md-rating value="3.5" precision="0.5" show-value-label rating-label="Half steps"></md-rating>
  <md-rating value="5" readonly rating-label="Read-only"></md-rating>
</div>

CSS parts

Part	Element
items	The slider container — the whole row of glyphs
icon-empty	The background (outline) glyph
icon-filled	The clipped foreground (filled) glyph
state-layer	Hover / press overlay — a filled glyph tracing the icon shape
ripple	Press ripple — a glyph-clipped expanding circle
value-label	The inline numeric value label

items, icon-filled and value-label

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>
  .parts-rating::part(items) { gap: 12px; }
  .parts-rating::part(icon-filled) { filter: drop-shadow(0 1px 2px rgba(0,0,0,.35)); }
  .parts-rating::part(value-label) { font-variant-numeric: tabular-nums; font-weight: 700; }
</style>
<md-rating class="parts-rating" value="3" show-value-label rating-label="Styled parts"></md-rating>

Copy

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

export function Demo() {
  return (
    <>
      <style>
        .parts-rating::part(items) { gap: 12px; }
        .parts-rating::part(icon-filled) { filter: drop-shadow(0 1px 2px rgba(0,0,0,.35)); }
        .parts-rating::part(value-label) { font-variant-numeric: tabular-nums; font-weight: 700; }
      </style>
      <MdRating className="parts-rating" value="3" showValueLabel ratingLabel="Styled parts"></MdRating>
    </>
  );
}

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>
  .parts-rating::part(items) { gap: 12px; }
  .parts-rating::part(icon-filled) { filter: drop-shadow(0 1px 2px rgba(0,0,0,.35)); }
  .parts-rating::part(value-label) { font-variant-numeric: tabular-nums; font-weight: 700; }
</style>
<md-rating class="parts-rating" value="3" show-value-label rating-label="Styled parts"></md-rating>

Copy

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

<template>
  <style>
    .parts-rating::part(items) { gap: 12px; }
    .parts-rating::part(icon-filled) { filter: drop-shadow(0 1px 2px rgba(0,0,0,.35)); }
    .parts-rating::part(value-label) { font-variant-numeric: tabular-nums; font-weight: 700; }
  </style>
  <md-rating class="parts-rating" value="3" show-value-label rating-label="Styled parts"></md-rating>
</template>

Copy

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

<style>
  .parts-rating::part(items) { gap: 12px; }
  .parts-rating::part(icon-filled) { filter: drop-shadow(0 1px 2px rgba(0,0,0,.35)); }
  .parts-rating::part(value-label) { font-variant-numeric: tabular-nums; font-weight: 700; }
</style>
<md-rating class="parts-rating" value="3" show-value-label rating-label="Styled parts"></md-rating>

Related

md-slider · md-icon-button · md-progress-indicator · md-badge · md-segmented-button

AI / LLM Context

For AI Agents — md-rating

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-rating 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-rating readme.md

Copy readme

# md-rating

<!-- llm:meta
tag: md-rating
category: selection
status: custom
m3-guidelines: none — not an M3 component
m3-derived-from: https://m3.material.io/components/sliders/guidelines, https://m3.material.io/components/icon-buttons/guidelines
reference-parity: https://mui.com/material-ui/react-rating/
form-associated: true
depends-on: none
used-by: none
-->

**A subjective score on a small, discrete scale.** Star (or custom-glyph)
rating with configurable maximum, optional half-steps, hover preview, and form
participation via `ElementInternals`.

> ⚠️ **Not a Material Design 3 component.** M3 has no rating page, so there is
> no spec to point at. The Do/Don't below are house rules derived from M3's
> slider and icon-button guidance plus this component's behavior.

> Setup, theming, density and i18n are configured once for the whole library —
> see [`main-llm.md`](../../../../../main-llm.md) at the repo root.

---

## When to use

- Capturing a **subjective judgement** on a small scale: product reviews,
  satisfaction, difficulty.
- **Displaying** an aggregate score read-only (`readonly`).

## When NOT to use

| Situation | Use instead |
|---|---|
| An objective value on a continuum | `md-slider` |
| A precise number | `md-text-field type="number"` |
| Binary like/dislike | `md-icon-button toggle` |
| More than ~10 points of scale | `md-slider` |
| Progress toward completion | `md-progress-indicator` |
| A non-interactive status | `md-badge` / `md-status-dot` |
| Choosing among labelled options | `md-radio` / `md-segmented-button-set` |

## Decision cues

| Need | Setting |
|---|---|
| Half-star precision | `precision="0.5"` |
| Non-interactive display | `readonly` |
| Numeric value beside the stars | `show-value-label` |
| Custom glyph | `icon` / `empty-icon` |
| Solid rather than outlined empties | `outline-empty="false"` |
| No hover preview (touch/dense UI) | `hover="off"` |
| Localized per-value announcement | `getLabel` (function prop) |
| Submit with a form | `name` |

## API contract

```html
<md-rating
  value="3.5" default-value="0"
  max="5" precision="1|0.5"
  size="xs|sm|md|lg|xl"          <!-- default: md -->
  icon="star" empty-icon="star" outline-empty
  readonly disabled soft-disabled
  show-value-label
  rating-label="Rating"          <!-- accessible name -->
  hover="preview|off"
  name="score"
  density="-1|-2|-3|-4"          <!-- default: 0 = uncompacted -->
></md-rating>
```

`getLabel` is a **function prop** — set it in JS:

```js
rating.getLabel = (v) => `${v} out of 5 stars`;
```

**Events**

| Event | Detail | Fires |
|---|---|---|
| `mdHover` | `number \| null` | Hover preview changes; `null` on leave. Suppressed entirely when `hover="off"` |
| `mdChange` | `number` | A rating is committed by click or keyboard |

Both bubble and are composed.

**Methods** — `focusRating()` (async). It focuses the shadow-internal
`role="slider"` element; calling `.focus()` on the host does nothing useful.

**Slots** — none. The glyphs are Material Symbols names via `icon` /
`empty-icon`; the component renders no `<slot>`.

**Parts** — `items` (the focusable slider container), `item` plus exactly one
of `item-full` / `item-half` / `item-empty` on each glyph wrapper,
`icon-filled`, `icon-empty`, `state-layer`, `ripple`, `value-label`.

### Behavioral contract worth knowing

- **Form-associated**: submits `value` under `name` as a string. A value of
  `0` submits **nothing** — it is treated as "no rating given", so read the key
  with `formData.has(name)` rather than assuming an entry exists.
- `value` is a **number**, and with `precision="0.5"` it can be fractional.
  Out-of-range or `NaN` values are clamped into `[0, max]`, and shrinking `max`
  re-clamps `value`.
- **Clicking the current value clears it to `default-value`** (default `0`).
  That is what `default-value` is for — it is *not* the initial display (set
  `value` for that) and *not* the form-reset target.
- **Form reset restores the value the markup was authored with**, not
  `default-value`.
- `mdChange` fires on user interaction only. Assigning `el.value` from script
  updates the control and the form value silently.
- `readonly` is not just "disabled without the grey": the control switches from
  `role="slider"` to `role="img"`, drops out of the tab order, and folds the
  score into its accessible name.
- `disabled` sets `tabindex="-1"`; `soft-disabled` keeps the control focusable
  (so it stays discoverable) while blocking interaction.
- `hover="preview"` (default) previews the value under the pointer and emits
  `mdHover`; it does **not** change `value` until a click. `hover="off"`
  suppresses both the preview and the event.
- **`empty-icon` is ignored while `outline-empty` is on** — and it is on by
  default. With `outline-empty`, empty items are drawn with the *filled* glyph
  in the inactive colour. Set `outline-empty="false"` to make `empty-icon`
  take effect.
- Keyboard: `ArrowUp` / `ArrowDown` and `ArrowLeft` / `ArrowRight` step by
  `precision` (the left/right pair follows reading direction and swaps in RTL),
  `Home` sets `0`, `End` sets `max`, and a **digit key `0`-`9`** sets that value
  directly when it is within `max`. Any other key is left to bubble, so `Escape`
  still closes an enclosing dialog or menu.
- The accessible name is resolved in this order: host `aria-labelledby` text,
  host `aria-label`, the text of any `<label>` associated with the host, then
  the `rating-label` prop. Pointing `aria-labelledby` at your own heading works
  even though the focusable node lives in the shadow root.
- `getLabel` drives the per-value announcement (`aria-valuetext`) **and** the
  visible `show-value-label` text — the single most useful i18n hook here.
- The press ripple is drawn inside the glyph silhouette, not as a circle, and
  it honours the global ripple switch: `data-ripple="off"` on any ancestor (or
  `ripple="off"` on the host) suppresses it. There is no `ripple` prop.

---

## Do / Don't

House rules — derived from M3 slider/icon-button guidance, not a spec page.

| ✅ Do | ❌ Don't |
|---|---|
| Keep `max` small (5 is conventional) | Don't build a 20-star scale — use `md-slider` |
| Use `readonly` for displayed aggregate scores | Don't leave a display-only rating interactive |
| Provide `getLabel` so each value announces meaningfully | Don't let a screen reader announce a bare number |
| Give the control a `rating-label` | Don't ship an unnamed rating |
| Use `precision="0.5"` only if half-steps are real input | Don't offer half-steps users can't reliably hit on touch |
| Keep the glyph conventional (stars) | Don't use an ambiguous glyph for a score |
| Pair the stars with a numeric label for aggregates | Don't rely on glyph count alone for a precise average |
| Turn `hover` off on touch-primary surfaces | Don't depend on hover preview for the interaction to make sense |

---

## Patterns

```html
<!-- Interactive, half steps -->
<md-rating precision="0.5" name="score" rating-label="Rate this product"></md-rating>
<script type="module">
  const r = document.querySelector('md-rating');
  r.getLabel = (v) => `${v} out of ${r.max} stars`;
  r.addEventListener('mdChange', (e) => console.log('rated', e.detail));
  r.addEventListener('mdHover',  (e) => console.log('preview', e.detail)); // null on leave
</script>

<!-- Read-only aggregate with the number shown -->
<md-rating value="4.3" precision="0.5" readonly show-value-label
           rating-label="Average rating"></md-rating>

<!-- Custom glyph (outline-empty on: the filled glyph draws the empties too) -->
<md-rating icon="favorite" max="5" rating-label="Love it"></md-rating>

<!-- Distinct empty glyph: outline-empty must be turned off -->
<md-rating icon="favorite" empty-icon="favorite_border" outline-empty="false"
           rating-label="Love it"></md-rating>

<!-- In a form -->
<form>
  <md-rating name="satisfaction" rating-label="Satisfaction"></md-rating>
  <md-button type="submit">Send feedback</md-button>
</form>

<!-- Touch-first: no hover preview -->
<md-rating hover="off" size="lg" rating-label="Delivery"></md-rating>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| `get-label` as an HTML attribute | Assign `getLabel` in JS | Function props don't cross the attribute boundary. |
| `default-value` used to set the initial score | Set `value` | `default-value` is what a re-click clears to. |
| Expecting a form entry for an unrated control | Check `formData.has(name)` | A value of `0` submits nothing. |
| `empty-icon` set while `outline-empty` is on | Add `outline-empty="false"` | The filled glyph is used for empties by default. |
| `ratingEl.focus()` | `await ratingEl.focusRating()` | The focusable node is inside the shadow root. |
| Displaying an average without `readonly` | Add `readonly` | Otherwise users think they're rating. |
| Reading `mdHover` as the chosen value | Use `mdChange` | Hover is a preview and can be `null`. |
| `max="10"` with `precision="0.5"` on touch | Reduce `max`, or use `md-slider` | 20 targets is unhittable. |
| No `rating-label` | Set it | It's the control's accessible name. |
| A slider for a 5-point subjective score | `md-rating` | And vice versa for continuous values. |
| Styling `.md-rating__item` | Use `::part(item)`, `::part(item-full)`, … | Internals are encapsulated; the parts are the supported hook. |
| Assuming an integer `value` | It can be fractional | With `precision="0.5"`. |

## Accessibility, RTL, density, i18n

**Accessibility**
- `rating-label` names the control; `getLabel` supplies the per-value
  announcement — set both.
- Keyboard: arrows step by `precision`, `Home` / `End` jump to `0` / `max`,
  and digit keys set a value directly. `focusRating()` focuses the control
  programmatically.
- Name the control with host `aria-labelledby` / `aria-label`, a wrapping
  `<label>`, or the `rating-label` prop — all four are honoured, in that
  order.
- Filled vs empty is conveyed by glyph fill, not colour alone; keep
  `outline-empty` on unless you have another cue.
- `readonly` remains readable to AT; `disabled` leaves the tab order.
- Check the per-item hit target at small `size` and deep density.

**RTL** — the scale fills from the reading start, so it mirrors under
`dir="rtl"`. Arrow-key direction follows reading order.

**Density** — `density="-1…-4"` locally overrides the inherited `data-density`
rung; rung `0` is the uncompacted default and is inert, so it is not an opt-out
from an ancestor rung (for that, set `style="--md-sys-density-scale: 0"`). Each
rung trims 2px off the glyph size for the current `size` (12px floor). Check
the per-item hit target before going deep on touch.

**i18n** — translate `rating-label`, and make `getLabel` locale-aware
(pluralization: "1 star" vs "2 stars"). Format the value with `Intl` when
`show-value-label` is on.

## Related components

`md-slider` · `md-icon-button` · `md-progress-indicator` · `md-badge` ·
`md-segmented-button-set`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-rating-item-size` | Glyph size | Per `size`: 16 / 20 / 28 / 36 / 48px, minus 2px per density rung (12px floor) |
| `--md-rating-item-gap` | Space between glyphs | `--md-sys-spacing-gap-xs` (4px) |
| `--md-rating-active-color` | Filled glyph colour | `--md-sys-color-secondary` |
| `--md-rating-inactive-color` | Empty glyph colour | `--md-sys-color-on-surface-variant` at 30% |
| `--md-rating-state-layer-color` | Hover/press overlay | `--md-sys-color-on-surface` |
| `--md-rating-focus-ring-color` | Focus ring colour | `--md-sys-color-secondary` |
| `--md-rating-focus-ring-width` / `--md-rating-focus-ring-offset` | Focus ring geometry | `3px` / `2px` |
| `--md-rating-value-label-color` | `show-value-label` text colour | `--md-sys-color-on-surface` |
| `--md-rating-value-label-font` | `show-value-label` font shorthand | `label-medium` typescale |
| `--md-rating-icon-font-family` | Glyph font | `Material Symbols Rounded`, then Outlined / Material Icons |
| `--md-rating-pop-scale` | Scale of the hover/select pop | `1.12` |
| `--md-rating-duration` | Pop duration | `--md-sys-motion-duration-short3` (150ms) |

**CSS parts** — `items`, `item`, `item-full`, `item-half`, `item-empty`,
`icon-filled`, `icon-empty`, `state-layer`, `ripple`, `value-label`.

```css
md-rating.brand {
  --md-rating-active-color: var(--md-sys-color-tertiary);
  --md-rating-pop-scale: 1;   /* no pop */
}
```

<!-- Auto Generated Below -->


## Overview

`md-rating` — Material Design 3 Expressive Rating control.

A star-rating input: configurable max, half-step precision, custom icons
(Material Symbols glyphs OR slotted SVG/HTML), per-value icons
(filled / empty), hover preview, read-only and disabled modes,
keyboard navigation (Arrow + Home/End), and reset to zero.

MD3 Expressive: items animate with a brief tonal "scale-up" pop on
hover and selection; press uses a state-layer + ripple. The
underlying ARIA pattern is a slider so screen readers announce the
value as a continuous range.

## Properties

| Property         | Attribute          | Description                                                                                                                                                                                                                                                                                                                                                                                                                    | Type                                       | Default     |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | ----------- |
| `defaultValue`   | `default-value`    | Default value used when the consumer clears the rating (re-clicking the current value).                                                                                                                                                                                                                                                                                                                                        | `number`                                   | `0`         |
| `density`        | `density`          | Local density rung. Drives the same `--md-sys-density-scale` signal that a global `data-density` ancestor sets, so a local value simply overrides the inherited one. 0 = default, -4 = ultra-compact.                                                                                                                                                                                                                          | `-1 \| -2 \| -3 \| -4 \| 0`                | `0`         |
| `disabled`       | `disabled`         | Disabled — non-interactive and visually dimmed; not focusable.                                                                                                                                                                                                                                                                                                                                                                 | `boolean`                                  | `false`     |
| `emptyIcon`      | `empty-icon`       | Material Symbols glyph used for *empty* items.                                                                                                                                                                                                                                                                                                                                                                                 | `string`                                   | `'star'`    |
| `getLabel`       | --                 | Optional label provider — `el.getLabel = (v) => "${v} Stars"`. Used by the hidden screen-reader text and the visible value label when `show-value-label` is set.                                                                                                                                                                                                                                                               | `((value: number) => string) \| undefined` | `undefined` |
| `hover`          | `hover`            | Hover-preview behaviour:   - `'preview'` (default) — display the hovered value over the live one.   - `'off'` — no hover preview; `value` is the only signal.                                                                                                                                                                                                                                                                  | `"off" \| "preview"`                       | `'preview'` |
| `icon`           | `icon`             | Material Symbols glyph used for *filled* items.                                                                                                                                                                                                                                                                                                                                                                                | `string`                                   | `'star'`    |
| `max`            | `max`              | Maximum rating (number of items rendered).                                                                                                                                                                                                                                                                                                                                                                                     | `number`                                   | `5`         |
| `name`           | `name`             | Form name for native form participation.                                                                                                                                                                                                                                                                                                                                                                                       | `string`                                   | `''`        |
| `outlineEmpty`   | `outline-empty`    | Use the *filled* glyph for empty items as well, drawn with the outline-only color treatment — a solid silhouette outline behind the fill.                                                                                                                                                                                                                                                     | `boolean`                                  | `true`      |
| `precision`      | `precision`        | Step size — `1` (full only) or `0.5` (half).                                                                                                                                                                                                                                                                                                                                                                                   | `0.5 \| 1`                                 | `1`         |
| `ratingLabel`    | `rating-label`     | Accessible name for the rating control.  The attribute is `rating-label`, NOT `aria-label-rating`. Anything starting with `aria-` is parsed as an ARIA attribute, and `aria-label-rating` is not one — so the previous name made axe report a CRITICAL `aria-valid-attr` violation on every consumer that used the documented API. The value still ends up as the host's accessible name; only the attribute spelling changed. | `string`                                   | `'Rating'`  |
| `readonly`       | `readonly`         | Read-only — purely decorative; no interaction, no focus.                                                                                                                                                                                                                                                                                                                                                                       | `boolean`                                  | `false`     |
| `showValueLabel` | `show-value-label` | When true, render the current numeric value beside the items.                                                                                                                                                                                                                                                                                                                                                                  | `boolean`                                  | `false`     |
| `size`           | `size`             | Size of each item.                                                                                                                                                                                                                                                                                                                                                                                                             | `"lg" \| "md" \| "sm" \| "xl" \| "xs"`     | `'md'`      |
| `softDisabled`   | `soft-disabled`    | Soft-disabled — disabled visuals but remains focusable for discoverability.                                                                                                                                                                                                                                                                                                                                                    | `boolean`                                  | `false`     |
| `value`          | `value`            | Current numeric rating (0 → max, half-steps when precision = 0.5).                                                                                                                                                                                                                                                                                                                                                             | `number`                                   | `0`         |


## Events

| Event      | Description                                                          | Type                          |
| ---------- | -------------------------------------------------------------------- | ----------------------------- |
| `mdChange` | Fires whenever the value changes via interaction.                    | `CustomEvent<number>`         |
| `mdHover`  | Fires while the user is hovering (or `null` when the cursor leaves). | `CustomEvent<null \| number>` |


## Methods

### `focusRating() => Promise<void>`

Programmatically focus the rating.

#### Returns

Type: `Promise<void>`




## Shadow Parts

| Part            | Description |
| --------------- | ----------- |
| `"icon-empty"`  |             |
| `"icon-filled"` |             |
| `"items"`       |             |
| `"ripple"`      |             |
| `"state-layer"` |             |
| `"value-label"` |             |


----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*

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.