Checkbox

Select none, one, or many from a related set. Tri-state (checked / unchecked / indeterminate), form-associated via ElementInternals with the full constraint-validation API, and its own supporting/error line under the box.

Live preview Open in Storybook

Unchecked Checked Indeterminate

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>

<label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
  <md-checkbox></md-checkbox> Unchecked
  </label>
  <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
    <md-checkbox checked></md-checkbox> Checked
    </label>
    <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
      <md-checkbox indeterminate></md-checkbox> Indeterminate
      </label>

Copy

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

export function Demo() {
  return (
    <>
      <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
        <MdCheckbox></MdCheckbox> Unchecked
        </label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
          <MdCheckbox checked></MdCheckbox> Checked
          </label>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
            <MdCheckbox indeterminate></MdCheckbox> Indeterminate
            </label>
    </>
  );
}

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 -->
<label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
  <md-checkbox></md-checkbox> Unchecked
  </label>
  <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
    <md-checkbox checked></md-checkbox> Checked
    </label>
    <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
      <md-checkbox indeterminate></md-checkbox> Indeterminate
      </label>

Copy

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

<template>
  <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
    <md-checkbox></md-checkbox> Unchecked
    </label>
    <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
      <md-checkbox checked></md-checkbox> Checked
      </label>
      <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
        <md-checkbox indeterminate></md-checkbox> Indeterminate
        </label>
</template>

Copy

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

<label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
  <md-checkbox></md-checkbox> Unchecked
  </label>
  <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
    <md-checkbox checked></md-checkbox> Checked
    </label>
    <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
      <md-checkbox indeterminate></md-checkbox> Indeterminate
      </label>

Install

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


<md-checkbox></md-checkbox>

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

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


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

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

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


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

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

Copy

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

<template>
  <MdCheckbox></MdCheckbox>
</template>


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

<template>
  <md-checkbox></md-checkbox>
</template>

Copy

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

<md-checkbox></md-checkbox>


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

<md-checkbox></md-checkbox>

When to use

• Several related options where any number may be selected.
• A single opt-in that must be submitted with a form (terms, consent) — note this needs an explicit submit to take effect, unlike a switch.
• A parent/child selection tree, using indeterminate for the partial state.

When not to use

Situation	Use instead
Exactly one option from a list	md-radio
A setting that takes effect immediately	md-switch
More than ~7 options, or space is tight	md-multi-select
Assigning a subset from a large pool	md-transfer-list
Filtering by removable criteria	md-chip
Two opposing choices (on/off framing)	md-switch, or md-button-group
Running an action	md-button

Decision cues

Need	Setting
Independent on/off choices	This component
A mixed “some children checked” state	indeterminate
A hint under the control	supporting-text
A validation message	error-text
Blocks form submission when unchecked	required
Unavailable but still discoverable	soft-disabled
Smaller box	density="-1…-4"

Labelling — there is no slot

<md-checkbox>Label</md-checkbox> renders nothing

The component has no default slot. Text placed between the tags is discarded, and a bare checkbox has no accessible name at all (axe aria-toggle-field-name). Wrap it in a <label> — that gives both the name and a larger hit target — or set aria-label / aria-labelledby on the host.

label wrapper, aria-label, aria-labelledby

Email me updates Labelled by another element

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>

<label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
  <md-checkbox name="news" value="yes"></md-checkbox> Email me updates
  </label>
  <md-checkbox aria-label="Standalone checkbox with an aria-label"></md-checkbox>
  <span id="cb-external-label">Labelled by another element</span>
  <md-checkbox aria-labelledby="cb-external-label"></md-checkbox>

Copy

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

export function Demo() {
  return (
    <>
      <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px', cursor: 'pointer' }}>
        <MdCheckbox name="news" value="yes"></MdCheckbox> Email me updates
        </label>
        <MdCheckbox aria-label="Standalone checkbox with an aria-label"></MdCheckbox>
        <span id="cb-external-label">Labelled by another element</span>
        <MdCheckbox aria-labelledby="cb-external-label"></MdCheckbox>
    </>
  );
}

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 -->
<label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
  <md-checkbox name="news" value="yes"></md-checkbox> Email me updates
  </label>
  <md-checkbox aria-label="Standalone checkbox with an aria-label"></md-checkbox>
  <span id="cb-external-label">Labelled by another element</span>
  <md-checkbox aria-labelledby="cb-external-label"></md-checkbox>

Copy

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

<template>
  <label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
    <md-checkbox name="news" value="yes"></md-checkbox> Email me updates
    </label>
    <md-checkbox aria-label="Standalone checkbox with an aria-label"></md-checkbox>
    <span id="cb-external-label">Labelled by another element</span>
    <md-checkbox aria-labelledby="cb-external-label"></md-checkbox>
</template>

Copy

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

<label style="display: inline-flex; align-items: center; gap: 8px; cursor: pointer;">
  <md-checkbox name="news" value="yes"></md-checkbox> Email me updates
  </label>
  <md-checkbox aria-label="Standalone checkbox with an aria-label"></md-checkbox>
  <span id="cb-external-label">Labelled by another element</span>
  <md-checkbox aria-labelledby="cb-external-label"></md-checkbox>

States

Five states, three of them value-carrying and two of them availability modifiers:

State	Set with	Notes
Unchecked	(default)	checked absent
Checked	checked	Submits value under name
Indeterminate	indeterminate	aria-checked="mixed" — presentation only
Disabled	disabled	Skipped by Tab
Soft-disabled	soft-disabled	Same visuals, still focusable

All five states — try tabbing through them

Unchecked Checked Indeterminate Disabled Soft-disabled

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>

<label style="display: inline-flex; align-items: center; gap: 8px;">
  <md-checkbox></md-checkbox> Unchecked
  </label>
  <label style="display: inline-flex; align-items: center; gap: 8px;">
    <md-checkbox checked></md-checkbox> Checked
    </label>
    <label style="display: inline-flex; align-items: center; gap: 8px;">
      <md-checkbox indeterminate></md-checkbox> Indeterminate
      </label>
      <label style="display: inline-flex; align-items: center; gap: 8px;">
        <md-checkbox disabled checked></md-checkbox> Disabled
        </label>
        <label style="display: inline-flex; align-items: center; gap: 8px;">
          <md-checkbox soft-disabled></md-checkbox> Soft-disabled
          </label>

Copy

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

export function Demo() {
  return (
    <>
      <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
        <MdCheckbox></MdCheckbox> Unchecked
        </label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
          <MdCheckbox checked></MdCheckbox> Checked
          </label>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
            <MdCheckbox indeterminate></MdCheckbox> Indeterminate
            </label>
            <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
              <MdCheckbox disabled checked></MdCheckbox> Disabled
              </label>
              <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
                <MdCheckbox soft-disabled></MdCheckbox> Soft-disabled
                </label>
    </>
  );
}

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 -->
<label style="display: inline-flex; align-items: center; gap: 8px;">
  <md-checkbox></md-checkbox> Unchecked
  </label>
  <label style="display: inline-flex; align-items: center; gap: 8px;">
    <md-checkbox checked></md-checkbox> Checked
    </label>
    <label style="display: inline-flex; align-items: center; gap: 8px;">
      <md-checkbox indeterminate></md-checkbox> Indeterminate
      </label>
      <label style="display: inline-flex; align-items: center; gap: 8px;">
        <md-checkbox disabled checked></md-checkbox> Disabled
        </label>
        <label style="display: inline-flex; align-items: center; gap: 8px;">
          <md-checkbox soft-disabled></md-checkbox> Soft-disabled
          </label>

Copy

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

<template>
  <label style="display: inline-flex; align-items: center; gap: 8px;">
    <md-checkbox></md-checkbox> Unchecked
    </label>
    <label style="display: inline-flex; align-items: center; gap: 8px;">
      <md-checkbox checked></md-checkbox> Checked
      </label>
      <label style="display: inline-flex; align-items: center; gap: 8px;">
        <md-checkbox indeterminate></md-checkbox> Indeterminate
        </label>
        <label style="display: inline-flex; align-items: center; gap: 8px;">
          <md-checkbox disabled checked></md-checkbox> Disabled
          </label>
          <label style="display: inline-flex; align-items: center; gap: 8px;">
            <md-checkbox soft-disabled></md-checkbox> Soft-disabled
            </label>
</template>

Copy

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

<label style="display: inline-flex; align-items: center; gap: 8px;">
  <md-checkbox></md-checkbox> Unchecked
  </label>
  <label style="display: inline-flex; align-items: center; gap: 8px;">
    <md-checkbox checked></md-checkbox> Checked
    </label>
    <label style="display: inline-flex; align-items: center; gap: 8px;">
      <md-checkbox indeterminate></md-checkbox> Indeterminate
      </label>
      <label style="display: inline-flex; align-items: center; gap: 8px;">
        <md-checkbox disabled checked></md-checkbox> Disabled
        </label>
        <label style="display: inline-flex; align-items: center; gap: 8px;">
          <md-checkbox soft-disabled></md-checkbox> Soft-disabled
          </label>

disabled leaves the tab order entirely. soft-disabled keeps the same visuals but stays focusable, so a contextually-unavailable option is still discoverable by keyboard — M3’s preference.

Indeterminate is a presentation state

indeterminate renders the dash and exposes aria-checked="mixed". It is not a third user-selectable value: a click resolves the checkbox to checked or unchecked and clears the flag. A parent checkbox therefore has to recompute it every time a child changes.

Parent / child — click a child and the parent recomputes

Select all Analytics Billing

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>

<label><md-checkbox id="all"></md-checkbox> Select all</label>
<label><md-checkbox class="child" value="a"></md-checkbox> Analytics</label>
<label><md-checkbox class="child" value="b"></md-checkbox> Billing</label>

<script type="module">
  const all = document.getElementById('all');
  const kids = [...document.querySelectorAll('.child')];

  const sync = () => {
    const n = kids.filter((k) => k.checked).length;
    all.checked = n === kids.length;
    all.indeterminate = n > 0 && n < kids.length;   // recompute — a click clears it
  };

  kids.forEach((k) => k.addEventListener('mdChange', sync));
  all.addEventListener('mdChange', () => {
    kids.forEach((k) => (k.checked = all.checked));
    all.indeterminate = false;
  });
  sync();
</script>

Copy

import { MdCheckbox } from '@awc-ui/react';
import { useMemo, useState } from 'react';

export function PermissionTree() {
const [kids, setKids] = useState({ a: false, b: false });
const values = Object.values(kids);
const allChecked = values.every(Boolean);
const indeterminate = useMemo(
  () => values.some(Boolean) && !allChecked,
  [values, allChecked],
);

return (
  <>
    <label>
      <MdCheckbox
        checked={allChecked}
        indeterminate={indeterminate}
        onMdChange={(e) => setKids({ a: e.detail.checked, b: e.detail.checked })}
      />
      Select all
    </label>
    <label>
      <MdCheckbox
        checked={kids.a}
        onMdChange={(e) => setKids((k) => ({ ...k, a: e.detail.checked }))}
      />
      Analytics
    </label>
    <label>
      <MdCheckbox
        checked={kids.b}
        onMdChange={(e) => setKids((k) => ({ ...k, b: e.detail.checked }))}
      />
      Billing
    </label>
  </>
);
}

Copy

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

@Component({
selector: 'app-permission-tree',
template: `
  <label>
    <md-checkbox
      [checked]="allChecked"
      [indeterminate]="indeterminate"
      (mdChange)="setAll($event)"
    ></md-checkbox>
    Select all
  </label>
  <label>
    <md-checkbox [checked]="kids.a" (mdChange)="set('a', $event)"></md-checkbox>
    Analytics
  </label>
  <label>
    <md-checkbox [checked]="kids.b" (mdChange)="set('b', $event)"></md-checkbox>
    Billing
  </label>
`,
})
export class PermissionTreeComponent {
kids = { a: false, b: false };

get allChecked() { return this.kids.a && this.kids.b; }
get indeterminate() { return (this.kids.a || this.kids.b) && !this.allChecked; }

set(key: 'a' | 'b', e: CustomEvent) { this.kids[key] = e.detail.checked; }
setAll(e: CustomEvent) { this.kids = { a: e.detail.checked, b: e.detail.checked }; }
}

Copy

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

const kids = reactive({ a: false, b: false });
const allChecked = computed(() => kids.a && kids.b);
const indeterminate = computed(() => (kids.a || kids.b) && !allChecked.value);

function setAll(e: CustomEvent) {
kids.a = e.detail.checked;
kids.b = e.detail.checked;
}
</script>

<template>
<label>
  <md-checkbox
    :checked="allChecked"
    :indeterminate="indeterminate"
    @mdChange="setAll"
  />
  Select all
</label>
<label>
  <md-checkbox :checked="kids.a" @mdChange="(e) => (kids.a = e.detail.checked)" />
  Analytics
</label>
<label>
  <md-checkbox :checked="kids.b" @mdChange="(e) => (kids.b = e.detail.checked)" />
  Billing
</label>
</template>

Copy

<script lang="ts">
let kids = { a: false, b: false };

$: allChecked = kids.a && kids.b;
$: indeterminate = (kids.a || kids.b) && !allChecked;

function setAll(e: CustomEvent) {
  kids = { a: e.detail.checked, b: e.detail.checked };
}
</script>

<label>
<md-checkbox
  checked={allChecked}
  {indeterminate}
  on:mdChange={setAll}
/>
Select all
</label>
<label>
<md-checkbox checked={kids.a} on:mdChange={(e) => (kids.a = e.detail.checked)} />
Analytics
</label>
<label>
<md-checkbox checked={kids.b} on:mdChange={(e) => (kids.b = e.detail.checked)} />
Billing
</label>

Supporting and error text

A checkbox has nowhere else to show a failed required except the browser’s transient validation balloon, so it carries its own message line. One line is rendered, and error-text wins it whenever it is set — the component renders errorText || supportingText. error does not choose between them: it recolours that line to the error role and gives it role="alert".

error colours the line, aria-invalid colours the box

Three separate signals, easy to conflate:

Want	Set
The message line in the error colour, announced live	error
A different message while invalid	error-text (shown whenever set)
The box outlined/filled in the error colour	nothing — the host sets aria-invalid itself

The box recolour is driven by :host([aria-invalid="true"]), and the component sets aria-invalid when required is unsatisfied or setCustomValidity() holds a message. Setting error alone leaves the box in its normal colours; setting required on an unchecked box recolours it whether or not you set error.

Don’t show both at once

Swap supporting → error rather than stacking them. Two lines where there was one shifts the layout under the user’s pointer.

Wrap the label text when a message is present

A checkbox carrying a message stacks as [touch target, message], so a bare text node beside it aligns to the top of the touch target rather than to the box — about 15px high. Put the label in a <span> given the target’s height and centred, as the snippets below do.

Supporting text and error text

Email me updates I accept the terms

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>

<label style="display: inline-flex; align-items: flex-start; gap: 8px;">
  <md-checkbox supporting-text="You can change this later"></md-checkbox>
  <span style="display: flex; align-items: center; min-block-size: 48px;">Email me updates</span>
</label>

<label style="display: inline-flex; align-items: flex-start; gap: 8px;">
  <md-checkbox error error-text="You must accept to continue" required></md-checkbox>
  <span style="display: flex; align-items: center; min-block-size: 48px;">I accept the terms</span>
</label>

Copy

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

export function Demo() {
  return (
    <>
      <label style={{ display: 'inline-flex', alignItems: 'flex-start', gap: '8px' }}>
        <MdCheckbox supportingText="You can change this later"></MdCheckbox>
        <span style={{ display: 'flex', alignItems: 'center', minBlockSize: '48px' }}>Email me updates</span>
      </label>

      <label style={{ display: 'inline-flex', alignItems: 'flex-start', gap: '8px' }}>
        <MdCheckbox error errorText="You must accept to continue" required></MdCheckbox>
        <span style={{ display: 'flex', alignItems: 'center', minBlockSize: '48px' }}>I accept the terms</span>
      </label>
    </>
  );
}

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 -->
<label style="display: inline-flex; align-items: flex-start; gap: 8px;">
  <md-checkbox supporting-text="You can change this later"></md-checkbox>
  <span style="display: flex; align-items: center; min-block-size: 48px;">Email me updates</span>
</label>

<label style="display: inline-flex; align-items: flex-start; gap: 8px;">
  <md-checkbox error error-text="You must accept to continue" required></md-checkbox>
  <span style="display: flex; align-items: center; min-block-size: 48px;">I accept the terms</span>
</label>

Copy

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

<template>
  <label style="display: inline-flex; align-items: flex-start; gap: 8px;">
    <md-checkbox supporting-text="You can change this later"></md-checkbox>
    <span style="display: flex; align-items: center; min-block-size: 48px;">Email me updates</span>
  </label>

  <label style="display: inline-flex; align-items: flex-start; gap: 8px;">
    <md-checkbox error error-text="You must accept to continue" required></md-checkbox>
    <span style="display: flex; align-items: center; min-block-size: 48px;">I accept the terms</span>
  </label>
</template>

Copy

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

<label style="display: inline-flex; align-items: flex-start; gap: 8px;">
  <md-checkbox supporting-text="You can change this later"></md-checkbox>
  <span style="display: flex; align-items: center; min-block-size: 48px;">Email me updates</span>
</label>

<label style="display: inline-flex; align-items: flex-start; gap: 8px;">
  <md-checkbox error error-text="You must accept to continue" required></md-checkbox>
  <span style="display: flex; align-items: center; min-block-size: 48px;">I accept the terms</span>
</label>

Forms

md-checkbox is form-associated through ElementInternals. When checked it submits value (default "on") under name, and it restores its authored state on form reset. Don’t add a hidden <input> — the mirror double-submits.

required genuinely blocks submission. value-missing-label is a prop rather than a hardcoded string precisely so you can localize the “please check this box” message.

Required consent — submit with the box unchecked

I accept the terms

Continue 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>
  <label style="display: inline-flex; align-items: flex-start; gap: 8px;">
    <md-checkbox
      name="terms"
      value="accepted"
      required
      value-missing-label="Please accept the terms."
      error-text="You must accept to continue"
      ></md-checkbox>
      <span style="display: flex; align-items: center; min-block-size: 48px;">I accept the terms</span>
    </label>

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

Copy

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

export function Demo() {
  return (
    <>
      <form>
        <label style={{ display: 'inline-flex', alignItems: 'flex-start', gap: '8px' }}>
          <MdCheckbox
            name="terms"
            value="accepted"
            required
            valueMissingLabel="Please accept the terms."
            errorText="You must accept to continue"
            ></MdCheckbox>
            <span style={{ display: 'flex', alignItems: 'center', minBlockSize: '48px' }}>I accept the terms</span>
          </label>

          <MdButton variant="filled" type="submit">Continue</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>
  <label style="display: inline-flex; align-items: flex-start; gap: 8px;">
    <md-checkbox
      name="terms"
      value="accepted"
      required
      value-missing-label="Please accept the terms."
      error-text="You must accept to continue"
      ></md-checkbox>
      <span style="display: flex; align-items: center; min-block-size: 48px;">I accept the terms</span>
    </label>

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

Copy

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

<template>
  <form>
    <label style="display: inline-flex; align-items: flex-start; gap: 8px;">
      <md-checkbox
        name="terms"
        value="accepted"
        required
        value-missing-label="Please accept the terms."
        error-text="You must accept to continue"
        ></md-checkbox>
        <span style="display: flex; align-items: center; min-block-size: 48px;">I accept the terms</span>
      </label>

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

Copy

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

<form>
  <label style="display: inline-flex; align-items: flex-start; gap: 8px;">
    <md-checkbox
      name="terms"
      value="accepted"
      required
      value-missing-label="Please accept the terms."
      error-text="You must accept to continue"
      ></md-checkbox>
      <span style="display: flex; align-items: center; min-block-size: 48px;">I accept the terms</span>
    </label>

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

Reading the submitted value back out — the checkbox appears in FormData under name only when it is checked, so get('terms') is null for an unchecked box:

HTML React Angular Vue Svelte

Copy

<form id="signup">
<label>
  <md-checkbox name="terms" value="accepted" required></md-checkbox>
  I accept the terms
</label>

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

<script type="module">
document.getElementById('signup').addEventListener('submit', (e) => {
  e.preventDefault();
  const data = new FormData(e.target);
  console.log(data.get('terms'));   // 'accepted', or null when unchecked
});
</script>

Copy

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

export function SignupForm() {
function onSubmit(e: React.FormEvent<HTMLFormElement>) {
  e.preventDefault();
  const data = new FormData(e.currentTarget);
  console.log(data.get('terms'));   // 'accepted', or null when unchecked
}

return (
  <form onSubmit={onSubmit}>
    <label>
      <MdCheckbox name="terms" value="accepted" required />
      I accept the terms
    </label>

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

Copy

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

@Component({
selector: 'app-signup-form',
template: `
  <form (submit)="onSubmit($event)">
    <label>
      <md-checkbox name="terms" value="accepted" required></md-checkbox>
      I accept the terms
    </label>

    <md-button variant="filled" type="submit">Continue</md-button>
    <md-button variant="text" type="reset">Reset</md-button>
  </form>
`,
})
export class SignupFormComponent {
onSubmit(e: Event) {
  e.preventDefault();
  const data = new FormData(e.target as HTMLFormElement);
  console.log(data.get('terms'));   // 'accepted', or null when unchecked
}
}

Copy

<script setup lang="ts">
function onSubmit(e: Event) {
e.preventDefault();
const data = new FormData(e.target as HTMLFormElement);
console.log(data.get('terms'));   // 'accepted', or null when unchecked
}
</script>

<template>
<form @submit="onSubmit">
  <label>
    <md-checkbox name="terms" value="accepted" required />
    I accept the terms
  </label>

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

Copy

<script lang="ts">
function onSubmit(e: Event) {
  e.preventDefault();
  const data = new FormData(e.target as HTMLFormElement);
  console.log(data.get('terms'));   // 'accepted', or null when unchecked
}
</script>

<form on:submit={onSubmit}>
<label>
  <md-checkbox name="terms" value="accepted" required />
  I accept the terms
</label>

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

Methods — getValidity(), checkValidity(), reportValidity() and setCustomValidity(message) mirror the native constraint-validation API. Use setCustomValidity('') to clear a server-side message.

Events

Event	Cancelable	Detail	Fires
mdChange	no	{ checked, indeterminate }	Whenever the state changes
mdValidityChange	no	{ valid, validationMessage, flags }	Only when validity changes

Both details are inline shapes — there is no exported …Detail type for either. The typed handle the library does export is MdCheckboxCustomEvent<T>:

import type { MdCheckboxCustomEvent } from '@awc-ui/core';

type ChangeEvent = MdCheckboxCustomEvent<{
  checked: boolean;
  indeterminate: boolean;   // always false after a user click
}>;

type ValidityEvent = MdCheckboxCustomEvent<{
  valid: boolean;
  validationMessage: string;
  flags: Record<string, boolean>;   // e.g. { valueMissing: true }
}>;

mdValidityChange is not composed

It deliberately does not cross shadow boundaries, so a delegated listener on an ancestor in another shadow root will never see it. Bind it on the checkbox itself. mdChange is composed, so one delegated listener on a light-DOM wrapper catches every checkbox inside it.

The first validity state is not a change

mdValidityChange primes its baseline on mount and stays silent, so a page of required checkboxes does not emit one event per control on load. Read the starting state with getValidity() instead.

mdChange delegated on the wrapper, mdValidityChange bound on the box

I accept the terms (required) Partial selection (starts indeterminate)

Toggle either box. The first is required, so its validity flips too; the second resolves its mixed state on the first click.

Show code for each technology

HTML React Angular Vue Svelte

Copy

<md-checkbox id="terms" name="terms" required></md-checkbox>

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

cb.addEventListener('mdChange', (e) => {
  console.log(e.detail.checked, e.detail.indeterminate);
});

// Bind on the element itself — this event is composed: false.
cb.addEventListener('mdValidityChange', (e) => {
  console.log(e.detail.valid, e.detail.validationMessage);
});
</script>

Copy

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

export function TermsCheckbox() {
return (
  <MdCheckbox
    name="terms"
    required
    onMdChange={(e) => console.log(e.detail.checked, e.detail.indeterminate)}
    onMdValidityChange={(e) => console.log(e.detail.valid, e.detail.validationMessage)}
  />
);
}

Copy

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

@Component({
selector: 'app-terms-checkbox',
template: `
  <md-checkbox
    name="terms"
    required
    (mdChange)="onChange($event)"
    (mdValidityChange)="onValidity($event)"
  ></md-checkbox>
`,
})
export class TermsCheckboxComponent {
onChange(e: CustomEvent) {
  console.log(e.detail.checked, e.detail.indeterminate);
}
onValidity(e: CustomEvent) {
  console.log(e.detail.valid, e.detail.validationMessage);
}
}

Copy

<script setup lang="ts">
function onChange(e: CustomEvent) {
console.log(e.detail.checked, e.detail.indeterminate);
}
function onValidity(e: CustomEvent) {
console.log(e.detail.valid, e.detail.validationMessage);
}
</script>

<template>
<md-checkbox
  name="terms"
  required
  @mdChange="onChange"
  @mdValidityChange="onValidity"
/>
</template>

Copy

<script lang="ts">
function onChange(e: CustomEvent) {
  console.log(e.detail.checked, e.detail.indeterminate);
}
function onValidity(e: CustomEvent) {
  console.log(e.detail.valid, e.detail.validationMessage);
}
</script>

<md-checkbox
name="terms"
required
on:mdChange={onChange}
on:mdValidityChange={onValidity}
/>

API Reference

tune

Properties

Property	Attribute	Type	Default	Reflects
valueMissingLabel	value-missing-label	string	'Please check this box if you want to proceed.'	—
error	error	boolean	false	Yes
errorText	error-text	string	''	—
supportingText	supporting-text	string	''	—
checked	checked	boolean	false	Yes
indeterminate	indeterminate	boolean	false	Yes
disabled	disabled	boolean	false	Yes
softDisabled	soft-disabled	boolean	false	Yes
required	required	boolean	false	Yes
name	name	string	''	—
value	value	string	'on'	—
density	density	0 | -1 | -2 | -3 | -4	0	Yes

function

Methods

Method	Parameters
getValidity()	none
checkValidity()	none
reportValidity()	none
setCustomValidity()	message: string

palette

CSS Custom Properties

Override on the host element for per-instance theming:

Property	Description
--md-checkbox-container-color	Unchecked container (transparent)
--md-checkbox-selected-container-color	Checked / indeterminate fill
--md-checkbox-outline-color	Border color (unchecked)
--md-checkbox-outline-width	Border width
--md-checkbox-icon-color	Checkmark / dash color
--md-checkbox-container-shape	Container corner radius
--md-checkbox-container-size	Container size
--md-checkbox-icon-size	Icon size
--md-checkbox-state-layer-size	State-layer diameter
--md-checkbox-state-layer-color	State-layer color (unchecked)
--md-checkbox-selected-state-layer-color	State-layer color (checked/indeterminate)
--md-checkbox-touch-target-size	—
--md-checkbox-supporting-text-color	—
--md-checkbox-error-text-color	—

layers

CSS Shadow Parts

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

Part	Description
target	—
state-layer	Hover / focus / press overlay
container	The 18px checkbox box
icon	The SVG icon (checkmark or dash)
supporting-text	—

Accessibility

• Wrapping in <label> gives both the accessible name and a larger hit target — the preferred pattern. Otherwise use aria-label or aria-labelledby.
• Tri-state is exposed as aria-checked="mixed" when indeterminate.
• disabled leaves the tab order; soft-disabled stays focusable.
• Errors surface in error-text next to the control, not only in a transient browser balloon.
• The hit area is a full 48px at density 0, comfortably over the WCAG 2.5.8 target size. It tapers 4px per density rung (down to a 32px floor), so a dense layout that still has to be tappable needs --md-checkbox-touch-target-size raised by 4px per rung — 64px at -4 to get 48px back.
• Group related checkboxes in a fieldset with a legend, or a container with role="group" and an aria-label.

Keyboard

Key	Action
Tab	Focus the checkbox (disabled is skipped, soft-disabled is not)
Space	Toggle it

Tab through these four: the soft-disabled SMS row still takes focus so a screen-reader user can discover the option, the disabled Fax row is skipped entirely, and the mixed Push row announces as “partially checked” until the first Space resolves it.

A named group — Tab through it, Space to toggle

Email Push (some channels) SMS — unavailable on your plan Fax — skipped by Tab

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 role="group" aria-label="Notification preferences" style="display:flex;flex-direction:column;gap:8px;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Email</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Push (some channels)</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox soft-disabled></md-checkbox> SMS — unavailable on your plan</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox disabled></md-checkbox> Fax — skipped by Tab</label>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div role="group" aria-label="Notification preferences" style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox checked></MdCheckbox> Email</label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox indeterminate></MdCheckbox> Push (some channels)</label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox soft-disabled></MdCheckbox> SMS — unavailable on your plan</label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox disabled></MdCheckbox> Fax — skipped by Tab</label>
      </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 role="group" aria-label="Notification preferences" style="display:flex;flex-direction:column;gap:8px;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Email</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Push (some channels)</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox soft-disabled></md-checkbox> SMS — unavailable on your plan</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox disabled></md-checkbox> Fax — skipped by Tab</label>
</div>

Copy

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

<template>
  <div role="group" aria-label="Notification preferences" style="display:flex;flex-direction:column;gap:8px;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Email</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Push (some channels)</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox soft-disabled></md-checkbox> SMS — unavailable on your plan</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox disabled></md-checkbox> Fax — skipped by Tab</label>
  </div>
</template>

Copy

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

<div role="group" aria-label="Notification preferences" style="display:flex;flex-direction:column;gap:8px;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Email</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Push (some channels)</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox soft-disabled></md-checkbox> SMS — unavailable on your plan</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox disabled></md-checkbox> Fax — skipped by Tab</label>
</div>

RTL, density & i18n

RTL — the box, its state layer and the supporting line are all laid out with logical properties, so the control flips side with the document direction on its own. Nothing on md-checkbox needs setting. See RTL.

<div dir="rtl">
  <label><md-checkbox checked></md-checkbox> تذكرني</label>
</div>

Same markup, dir=ltr vs dir=rtl

ltr

Remember me Partial

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:20px;flex-wrap:wrap;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Remember me</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Partial</label>
  </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:20px;flex-wrap:wrap;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> تذكرني</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> جزئي</label>
  </div>
</div>

Copy

import { MdCheckbox } 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: '20px', flexWrap: 'wrap' }}>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox checked></MdCheckbox> Remember me</label>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox indeterminate></MdCheckbox> Partial</label>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>rtl</span>
        <div dir="rtl" style={{ display: 'flex', gap: '20px', flexWrap: 'wrap' }}>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox checked></MdCheckbox> تذكرني</label>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox indeterminate></MdCheckbox> جزئي</label>
        </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:20px;flex-wrap:wrap;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Remember me</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Partial</label>
  </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:20px;flex-wrap:wrap;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> تذكرني</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> جزئي</label>
  </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:20px;flex-wrap:wrap;">
      <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Remember me</label>
      <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Partial</label>
    </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:20px;flex-wrap:wrap;">
      <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> تذكرني</label>
      <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> جزئي</label>
    </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:20px;flex-wrap:wrap;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Remember me</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Partial</label>
  </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:20px;flex-wrap:wrap;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> تذكرني</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> جزئي</label>
  </div>
</div>

The nesting indent is yours, and it must be logical

The component flips itself, but the indent you put on a parent/child tree is your own CSS — and that is where direction usually breaks. Use margin-inline-start, not margin-left: under dir="rtl" the physical property pushes the child away from the end edge, so the child row lines up flush with its parent instead of stepping in from it.

margin-inline-start vs margin-left — both rows under dir=rtl

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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div style="display:flex;flex-direction:column;gap:4px;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> تحديد الكل</label>
    <label style="display:inline-flex;align-items:center;gap:8px;margin-inline-start:32px;"><md-checkbox checked></md-checkbox> التحليلات</label>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div style="display:flex;flex-direction:column;gap:4px;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> تحديد الكل</label>
    <label style="display:inline-flex;align-items:center;gap:8px;margin-left:32px;"><md-checkbox checked></md-checkbox> التحليلات</label>
  </div>
</div>

Copy

import { MdCheckbox } 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: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>correct</span>
        <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox indeterminate></MdCheckbox> تحديد الكل</label>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px', marginInlineStart: '32px' }}><MdCheckbox checked></MdCheckbox> التحليلات</label>
        </div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>wrong</span>
        <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox indeterminate></MdCheckbox> تحديد الكل</label>
          <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px', marginLeft: '32px' }}><MdCheckbox checked></MdCheckbox> التحليلات</label>
        </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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div style="display:flex;flex-direction:column;gap:4px;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> تحديد الكل</label>
    <label style="display:inline-flex;align-items:center;gap:8px;margin-inline-start:32px;"><md-checkbox checked></md-checkbox> التحليلات</label>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div style="display:flex;flex-direction:column;gap:4px;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> تحديد الكل</label>
    <label style="display:inline-flex;align-items:center;gap:8px;margin-left:32px;"><md-checkbox checked></md-checkbox> التحليلات</label>
  </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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
    <div style="display:flex;flex-direction:column;gap:4px;">
      <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> تحديد الكل</label>
      <label style="display:inline-flex;align-items:center;gap:8px;margin-inline-start:32px;"><md-checkbox checked></md-checkbox> التحليلات</label>
    </div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
    <div style="display:flex;flex-direction:column;gap:4px;">
      <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> تحديد الكل</label>
      <label style="display:inline-flex;align-items:center;gap:8px;margin-left:32px;"><md-checkbox checked></md-checkbox> التحليلات</label>
    </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:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">correct</span>
  <div style="display:flex;flex-direction:column;gap:4px;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> تحديد الكل</label>
    <label style="display:inline-flex;align-items:center;gap:8px;margin-inline-start:32px;"><md-checkbox checked></md-checkbox> التحليلات</label>
  </div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">wrong</span>
  <div style="display:flex;flex-direction:column;gap:4px;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> تحديد الكل</label>
    <label style="display:inline-flex;align-items:center;gap:8px;margin-left:32px;"><md-checkbox checked></md-checkbox> التحليلات</label>
  </div>
</div>

Every density rung

density="-1…-4" shrinks the box (18px → 14px, 1px per rung) and the touch target (48px → 32px, 4px per rung). The state layer is min(40px, target), so it holds at 40px through rung -2 and only starts shrinking at -3. See Density.

Rung	Box	Touch target	State layer
0	18px	48px	40px
-1	17px	44px	40px
-2	16px	40px	40px
-3	15px	36px	36px
-4	14px	32px	32px

Density 0 through -4 Open in Storybook

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:16px;align-items:center;"><md-checkbox density="0" checked></md-checkbox><md-checkbox density="0" indeterminate></md-checkbox><md-checkbox density="0"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-1" checked></md-checkbox><md-checkbox density="-1" indeterminate></md-checkbox><md-checkbox density="-1"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-2" checked></md-checkbox><md-checkbox density="-2" indeterminate></md-checkbox><md-checkbox density="-2"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-3" checked></md-checkbox><md-checkbox density="-3" indeterminate></md-checkbox><md-checkbox density="-3"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-4" checked></md-checkbox><md-checkbox density="-4" indeterminate></md-checkbox><md-checkbox density="-4"></md-checkbox></div>
</div>

Copy

import { MdCheckbox } 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: '16px', alignItems: 'center' }}><MdCheckbox density="0" checked></MdCheckbox><MdCheckbox density="0" indeterminate></MdCheckbox><MdCheckbox density="0"></MdCheckbox></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-1</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}><MdCheckbox density="-1" checked></MdCheckbox><MdCheckbox density="-1" indeterminate></MdCheckbox><MdCheckbox density="-1"></MdCheckbox></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-2</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}><MdCheckbox density="-2" checked></MdCheckbox><MdCheckbox density="-2" indeterminate></MdCheckbox><MdCheckbox density="-2"></MdCheckbox></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-3</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}><MdCheckbox density="-3" checked></MdCheckbox><MdCheckbox density="-3" indeterminate></MdCheckbox><MdCheckbox density="-3"></MdCheckbox></div>
        <span style={{ inlineSize: '3.5rem', opacity: '.65', fontSize: '.75rem', fontFamily: 'ui-monospace,monospace' }}>-4</span>
        <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}><MdCheckbox density="-4" checked></MdCheckbox><MdCheckbox density="-4" indeterminate></MdCheckbox><MdCheckbox density="-4"></MdCheckbox></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:16px;align-items:center;"><md-checkbox density="0" checked></md-checkbox><md-checkbox density="0" indeterminate></md-checkbox><md-checkbox density="0"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-1" checked></md-checkbox><md-checkbox density="-1" indeterminate></md-checkbox><md-checkbox density="-1"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-2" checked></md-checkbox><md-checkbox density="-2" indeterminate></md-checkbox><md-checkbox density="-2"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-3" checked></md-checkbox><md-checkbox density="-3" indeterminate></md-checkbox><md-checkbox density="-3"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-4" checked></md-checkbox><md-checkbox density="-4" indeterminate></md-checkbox><md-checkbox density="-4"></md-checkbox></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:16px;align-items:center;"><md-checkbox density="0" checked></md-checkbox><md-checkbox density="0" indeterminate></md-checkbox><md-checkbox density="0"></md-checkbox></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
    <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-1" checked></md-checkbox><md-checkbox density="-1" indeterminate></md-checkbox><md-checkbox density="-1"></md-checkbox></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
    <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-2" checked></md-checkbox><md-checkbox density="-2" indeterminate></md-checkbox><md-checkbox density="-2"></md-checkbox></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
    <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-3" checked></md-checkbox><md-checkbox density="-3" indeterminate></md-checkbox><md-checkbox density="-3"></md-checkbox></div>
    <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
    <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-4" checked></md-checkbox><md-checkbox density="-4" indeterminate></md-checkbox><md-checkbox density="-4"></md-checkbox></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:16px;align-items:center;"><md-checkbox density="0" checked></md-checkbox><md-checkbox density="0" indeterminate></md-checkbox><md-checkbox density="0"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-1</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-1" checked></md-checkbox><md-checkbox density="-1" indeterminate></md-checkbox><md-checkbox density="-1"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-2</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-2" checked></md-checkbox><md-checkbox density="-2" indeterminate></md-checkbox><md-checkbox density="-2"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-3</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-3" checked></md-checkbox><md-checkbox density="-3" indeterminate></md-checkbox><md-checkbox density="-3"></md-checkbox></div>
  <span style="inline-size:3.5rem;opacity:.65;font-size:.75rem;font-family:ui-monospace,monospace;">-4</span>
  <div style="display:flex;gap:16px;align-items:center;"><md-checkbox density="-4" checked></md-checkbox><md-checkbox density="-4" indeterminate></md-checkbox><md-checkbox density="-4"></md-checkbox></div>
</div>

The hit area shrinks too — and the custom property will not pin it

Each rung trims 4px off the touch target as well as the box, floored at 32px, so a -4 checkbox is a 32px target: fine for a dense data table on a mouse, genuinely hard to hit on touch.

--md-checkbox-touch-target-size is the input to that subtraction, not the result:

/* the component's own calc */
--_touch-size: max(32px, calc(var(--md-checkbox-touch-target-size, 48px)
                              + var(--md-sys-density-scale, 0) * 4px));

So setting it “back to 48px” at rung -4 still resolves to 32px — no change at all. To recover a real 48px target you have to pre-pay the trim: add 4px per rung.

/* a 48px target at density -4 */
md-checkbox[density="-4"].needs-touch {
  --md-checkbox-touch-target-size: 64px;   /* 64 − 4×4 = 48 */
}

See Density.

Density and direction together

A global data-density ancestor and a local density prop drive the same signal — --md-sys-density-scale — and the prop lands directly on the host, so a local rung wins over the inherited one, including inside an RTL subtree.

density="0" does not opt back out

There is deliberately no [density="0"] rule, in the checkbox or in the token layer: reflected props write density="0" onto virtually every element, so such a rule would pin density-0 values everywhere and break global inheritance. Absence of a rung means “inherit whatever the ancestor says” — density="0" inside data-density="-2" still renders at -2. Only -1 … -4 override an ancestor; to escape a dense subtree, put the checkbox outside it.

dir=rtl with data-density=-2, and one checkbox overriding to -4

بريد إلكتروني إشعارات رسائل قصيرة — density="-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 dir="rtl" data-density="-2" style="display:flex;flex-direction:column;gap:8px;inline-size:100%;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> بريد إلكتروني</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> إشعارات</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox density="-4" checked></md-checkbox> رسائل قصيرة — density=&quot;-4&quot;</label>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div dir="rtl" data-density="-2" style={{ display: 'flex', flexDirection: 'column', gap: '8px', inlineSize: '100%' }}>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox checked></MdCheckbox> بريد إلكتروني</label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox indeterminate></MdCheckbox> إشعارات</label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox density="-4" checked></MdCheckbox> رسائل قصيرة — density=&quot;-4&quot;</label>
      </div>
    </>
  );
}

Copy

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

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

<!-- app.component.html -->
<div dir="rtl" data-density="-2" style="display:flex;flex-direction:column;gap:8px;inline-size:100%;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> بريد إلكتروني</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> إشعارات</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox density="-4" checked></md-checkbox> رسائل قصيرة — density=&quot;-4&quot;</label>
</div>

Copy

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

<template>
  <div dir="rtl" data-density="-2" style="display:flex;flex-direction:column;gap:8px;inline-size:100%;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> بريد إلكتروني</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> إشعارات</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox density="-4" checked></md-checkbox> رسائل قصيرة — density=&quot;-4&quot;</label>
  </div>
</template>

Copy

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

<div dir="rtl" data-density="-2" style="display:flex;flex-direction:column;gap:8px;inline-size:100%;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> بريد إلكتروني</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> إشعارات</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox density="-4" checked></md-checkbox> رسائل قصيرة — density=&quot;-4&quot;</label>
</div>

Density — the box and the touch target taper on every rung; the state layer is clamped by the target (min(40px, target)) so it only starts moving at -3. --md-checkbox-container-size and --md-checkbox-icon-size are independent properties that merely share the same density-derived default, so overriding one by hand does not move the other — set both together, as the Theming demo below does.

i18n — translate supporting-text, error-text, value-missing-label and the visible label text. A hardcoded English value-missing-label in a localized app is the usual oversight; it is a prop precisely so you can feed it from your dictionary.

Theming

Custom property	Purpose	Default
--md-checkbox-container-color / --md-checkbox-selected-container-color	Box fill, unselected / selected	Transparent / primary
--md-checkbox-outline-color / --md-checkbox-outline-width	Box border	on-surface-variant / 2px
--md-checkbox-icon-color / --md-checkbox-icon-size	Checkmark and dash	on-primary
--md-checkbox-container-shape / --md-checkbox-container-size	Box radius and size	2px / 18px
--md-checkbox-state-layer-size / -color / --md-checkbox-selected-state-layer-color	Hover/press overlay	40px
--md-checkbox-touch-target-size	Base hit area, before density trims it	48px
--md-checkbox-supporting-text-color / --md-checkbox-error-text-color	Message line	on-surface-variant / error

Themed instances

Round and tertiary Larger box

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>

<label style="display: inline-flex; align-items: center; gap: 8px;">
  <md-checkbox checked style="--md-checkbox-selected-container-color: var(--md-sys-color-tertiary); --md-checkbox-container-shape: 999px;"></md-checkbox> Round and tertiary
  </label>
  <label style="display: inline-flex; align-items: center; gap: 8px;">
    <md-checkbox checked style="--md-checkbox-container-size: 24px; --md-checkbox-icon-size: 22px;"></md-checkbox> Larger box
    </label>

Copy

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

export function Demo() {
  return (
    <>
      <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
        <MdCheckbox checked style={{ '--md-checkbox-selected-container-color': 'var(--md-sys-color-tertiary)', '--md-checkbox-container-shape': '999px' }}></MdCheckbox> Round and tertiary
        </label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
          <MdCheckbox checked style={{ '--md-checkbox-container-size': '24px', '--md-checkbox-icon-size': '22px' }}></MdCheckbox> Larger box
          </label>
    </>
  );
}

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 -->
<label style="display: inline-flex; align-items: center; gap: 8px;">
  <md-checkbox checked style="--md-checkbox-selected-container-color: var(--md-sys-color-tertiary); --md-checkbox-container-shape: 999px;"></md-checkbox> Round and tertiary
  </label>
  <label style="display: inline-flex; align-items: center; gap: 8px;">
    <md-checkbox checked style="--md-checkbox-container-size: 24px; --md-checkbox-icon-size: 22px;"></md-checkbox> Larger box
    </label>

Copy

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

<template>
  <label style="display: inline-flex; align-items: center; gap: 8px;">
    <md-checkbox checked style="--md-checkbox-selected-container-color: var(--md-sys-color-tertiary); --md-checkbox-container-shape: 999px;"></md-checkbox> Round and tertiary
    </label>
    <label style="display: inline-flex; align-items: center; gap: 8px;">
      <md-checkbox checked style="--md-checkbox-container-size: 24px; --md-checkbox-icon-size: 22px;"></md-checkbox> Larger box
      </label>
</template>

Copy

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

<label style="display: inline-flex; align-items: center; gap: 8px;">
  <md-checkbox checked style="--md-checkbox-selected-container-color: var(--md-sys-color-tertiary); --md-checkbox-container-shape: 999px;"></md-checkbox> Round and tertiary
  </label>
  <label style="display: inline-flex; align-items: center; gap: 8px;">
    <md-checkbox checked style="--md-checkbox-container-size: 24px; --md-checkbox-icon-size: 22px;"></md-checkbox> Larger box
    </label>

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

Untouched defaults — follows the page theme

Checked Mixed Unchecked

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;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Checked</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Mixed</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox></md-checkbox> Unchecked</label>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <div style={{ display: 'flex', gap: '20px', flexWrap: 'wrap', alignItems: 'center' }}>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox checked></MdCheckbox> Checked</label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox indeterminate></MdCheckbox> Mixed</label>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox></MdCheckbox> Unchecked</label>
      </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;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Checked</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Mixed</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox></md-checkbox> Unchecked</label>
</div>

Copy

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

<template>
  <div style="display:flex;gap:20px;flex-wrap:wrap;align-items:center;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Checked</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Mixed</label>
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox></md-checkbox> Unchecked</label>
  </div>
</template>

Copy

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

<div style="display:flex;gap:20px;flex-wrap:wrap;align-items:center;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox checked></md-checkbox> Checked</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox indeterminate></md-checkbox> Mixed</label>
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox></md-checkbox> Unchecked</label>
</div>

CSS parts

Part	Element
target	The hit area — 48px at density 0, 32px at -4
state-layer	Hover / focus / press overlay
container	The box itself
icon	The mark — a Material Symbols glyph, not an SVG
supporting-text	The message line under the control

icon is a font glyph

It renders check, or remove when indeterminate, at FILL 1 / wght 600 — the same face md-step uses for a completed step, so the two marks match exactly. Style it with font properties (font-size, color, font-variation-settings) or transform; SVG properties like stroke and fill have nothing to act on.

container, icon, state-layer and supporting-text

Round box

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-cb::part(container) { border-radius: 999px; }
  .parts-cb::part(icon) { transform: scale(1.15); }
  .parts-cb::part(state-layer) { background: var(--md-sys-color-tertiary); }
  .parts-cb::part(supporting-text) { font-style: italic; letter-spacing: .02em; }
</style>
<div style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox class="parts-cb" checked></md-checkbox> Round box</label>
  <md-checkbox class="parts-cb" checked supporting-text="Styled supporting text" aria-label="With supporting text"></md-checkbox>
</div>

Copy

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

export function Demo() {
  return (
    <>
      <style>
        .parts-cb::part(container) { border-radius: 999px; }
        .parts-cb::part(icon) { transform: scale(1.15); }
        .parts-cb::part(state-layer) { background: var(--md-sys-color-tertiary); }
        .parts-cb::part(supporting-text) { font-style: italic; letter-spacing: .02em; }
      </style>
      <div style={{ display: 'flex', gap: '24px', flexWrap: 'wrap', alignItems: 'flex-start' }}>
        <label style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><MdCheckbox className="parts-cb" checked></MdCheckbox> Round box</label>
        <MdCheckbox className="parts-cb" checked supportingText="Styled supporting text" aria-label="With supporting text"></MdCheckbox>
      </div>
    </>
  );
}

Copy

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

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

<!-- app.component.html -->
<style>
  .parts-cb::part(container) { border-radius: 999px; }
  .parts-cb::part(icon) { transform: scale(1.15); }
  .parts-cb::part(state-layer) { background: var(--md-sys-color-tertiary); }
  .parts-cb::part(supporting-text) { font-style: italic; letter-spacing: .02em; }
</style>
<div style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox class="parts-cb" checked></md-checkbox> Round box</label>
  <md-checkbox class="parts-cb" checked supporting-text="Styled supporting text" aria-label="With supporting text"></md-checkbox>
</div>

Copy

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

<template>
  <style>
    .parts-cb::part(container) { border-radius: 999px; }
    .parts-cb::part(icon) { transform: scale(1.15); }
    .parts-cb::part(state-layer) { background: var(--md-sys-color-tertiary); }
    .parts-cb::part(supporting-text) { font-style: italic; letter-spacing: .02em; }
  </style>
  <div style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
    <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox class="parts-cb" checked></md-checkbox> Round box</label>
    <md-checkbox class="parts-cb" checked supporting-text="Styled supporting text" aria-label="With supporting text"></md-checkbox>
  </div>
</template>

Copy

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

<style>
  .parts-cb::part(container) { border-radius: 999px; }
  .parts-cb::part(icon) { transform: scale(1.15); }
  .parts-cb::part(state-layer) { background: var(--md-sys-color-tertiary); }
  .parts-cb::part(supporting-text) { font-style: italic; letter-spacing: .02em; }
</style>
<div style="display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start;">
  <label style="display:inline-flex;align-items:center;gap:8px;"><md-checkbox class="parts-cb" checked></md-checkbox> Round box</label>
  <md-checkbox class="parts-cb" checked supporting-text="Styled supporting text" aria-label="With supporting text"></md-checkbox>
</div>

md-checkbox::part(supporting-text) {
  font-style: italic;
}

Related

md-radio · md-switch · md-multi-select · md-transfer-list · md-chip · md-ripple

AI / LLM Context

For AI Agents — md-checkbox

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

Copy readme

# md-checkbox

<!-- llm:meta
tag: md-checkbox
category: selection
status: md3-mapped
m3-guidelines: https://m3.material.io/components/checkbox/guidelines
form-associated: true
depends-on: md-ripple
used-by: md-transfer-list
-->

**Select none, one, or many from a related set.** Tri-state (checked /
unchecked / indeterminate), form-associated via `ElementInternals`, with the
full constraint-validation API and its own supporting/error line.

> 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

- Several **related** options where any number may be selected.
- A single opt-in that must be **submitted with a form** (terms, consent) —
  note this needs an explicit action to take effect, unlike a switch.
- A **parent/child** selection tree, using `indeterminate` for the partial
  state.

## When NOT to use

| Situation | Use instead |
|---|---|
| Exactly one option from a list | `md-radio` |
| A setting that takes effect **immediately** | `md-switch` |
| More than ~7 options, or space is tight | `md-multi-select` |
| Assigning a subset from a large pool | `md-transfer-list` |
| Filtering by removable criteria | `md-chip` |
| Two opposing choices (on/off framing) | `md-switch`, or `md-button-group` |
| Running an action | `md-button` |

## Decision cues

| Need | Setting |
|---|---|
| Partial selection of children | `indeterminate` (visual only — see contract) |
| Must be ticked to submit | `required` |
| Helper text under the box | `supporting-text` |
| Validation message under the box | `error` + `error-text` |
| Localized native "please check this box" | `value-missing-label` |
| Unavailable but still discoverable | `soft-disabled` |

## API contract

```html
<label>
  <md-checkbox
    name="terms" value="accepted"
    checked indeterminate
    required
    supporting-text="You can change this later"
    error error-text="You must accept to continue"
    value-missing-label="Please accept the terms."
    disabled | soft-disabled
    density="-1|-2|-3|-4"
  ></md-checkbox>
  I accept the terms
</label>
```

**Events**

| Event | Detail | Notes |
|---|---|---|
| `mdChange` | `{ checked, indeterminate }` | User activation only (click / `Space`). Bubbles and is composed |
| `mdValidityChange` | `{ valid, validationMessage, flags }` | Only when validity **changes**; `composed: false` — does **not** cross shadow boundaries |

**Methods** — all async: `getValidity()`, `checkValidity()`,
`reportValidity()`, `setCustomValidity(message)`.

**Slots** — none. The component renders no `<slot>`; the label is external
(wrap in `<label>`, or set `aria-label` / `aria-labelledby` on the host).

**Parts** — `target`, `state-layer`, `container`, `icon`, `supporting-text`.

### Behavioral contract worth knowing

- **It has no slot.** The label is not slotted content — wrap the checkbox in a
  `<label>`, or set `aria-label` / `aria-labelledby` on the host. A bare
  checkbox has **no accessible name** (axe `aria-toggle-field-name`).
- Form-associated: submits `value` (default `"on"`) under `name` **when
  checked**, and restores on form reset. Don't add a hidden `<input>`.
- `mdChange` fires for **user activation only**. Setting `checked` /
  `indeterminate` from script updates the control and the form value silently —
  so a script-driven change never re-enters your own `mdChange` handler.
- `disabled` and `soft-disabled` both block activation; `disabled` sets
  `tabindex="-1"` while `soft-disabled` keeps `tabindex="0"` so the control
  stays discoverable.
- `aria-hidden="true"` on the host makes the checkbox **decorative**: the
  `tabindex` attribute is dropped entirely so it leaves the tab order. Use this
  for a mirror glyph inside an interactive row that owns the real toggle.
- `indeterminate` is a **presentation state**: it never reaches the form
  (submission is decided by `checked` alone) and it does not survive a user
  click — clicking a mixed checkbox sets `checked = true`, `indeterminate =
  false`. Your parent-checkbox logic must recompute it.
- `mdValidityChange` is deliberately **not composed**, so a parent across a
  shadow boundary won't see it. Listen on the element itself.
- `error-text` exists because a checkbox otherwise has nowhere to show a failed
  `required` except the browser's transient balloon.
- `value-missing-label` is a prop, not a hardcoded string, so you localize it.
- **The mark is a Material Symbols glyph, not an SVG path** — `check` when
  checked, `remove` when `indeterminate`, at `FILL 1 / wght 600`. It is drawn
  with `--md-sys-icon-font-family` (default `Material Symbols Outlined`); if
  that font is not loaded the box renders the literal word `check`.
- **A message changes the host's box.** With `supporting-text` or `error-text`
  the host becomes a column — `[touch target, message]` — sized to the touch
  target, with the message overflowing horizontally. Two consequences:
  the message is inset to line up with the **visible box** rather than the
  wider touch target; and a bare text node beside the checkbox aligns to the
  *top of the touch target*, roughly 15px above the box. Wrap the label text
  and centre it against the target (see Patterns).

---

## Do / Don't

Sourced from [M3 · Checkbox · Guidelines](https://m3.material.io/components/checkbox/guidelines).

| ✅ Do | ❌ Don't |
|---|---|
| Use checkboxes to select one **or more** options from a list | Don't use switches for a list of options — checkboxes imply the items are related and use less space |
| Use a parent checkbox to select/deselect all items | Don't leave a parent checkbox out of sync with its children |
| Give every checkbox a real label | Don't ship an unlabelled checkbox |
| Keep the option set related and scoped | Don't mix unrelated settings into one checkbox list |
| Use `indeterminate` for genuinely partial parent state | Don't use `indeterminate` as a third user-selectable value |
| Put validation in `error-text` next to the control | Don't rely on the browser's validation balloon alone |
| Use `required` where consent is mandatory | Don't pre-check a consent box |

---

## Patterns

```html
<!-- Labelled (native label = accessible name + click target) -->
<label><md-checkbox name="news" value="yes"></md-checkbox> Email me updates</label>

<!-- WITH a message: the host stacks [touch target, message], so give the label
     text the target's height and centre it, or it sits ~15px above the box. -->
<label style="display: inline-flex; align-items: flex-start; gap: 8px;">
  <md-checkbox supporting-text="You can change this later"></md-checkbox>
  <span style="display: flex; align-items: center; min-block-size: 48px;">Email me updates</span>
</label>

<!-- Parent / child with indeterminate -->
<label><md-checkbox id="all"></md-checkbox> Select all</label>
<label><md-checkbox class="child" value="a"></md-checkbox> Analytics</label>
<label><md-checkbox class="child" value="b"></md-checkbox> Billing</label>

<script type="module">
  const all = document.getElementById('all');
  const kids = [...document.querySelectorAll('.child')];

  const sync = () => {
    const n = kids.filter(k => k.checked).length;
    all.checked = n === kids.length;
    all.indeterminate = n > 0 && n < kids.length;   // recompute — a click clears it
  };

  kids.forEach(k => k.addEventListener('mdChange', sync));
  all.addEventListener('mdChange', () => {
    kids.forEach(k => (k.checked = all.checked));
    all.indeterminate = false;
  });
  sync();
</script>

<!-- Required consent in a form -->
<form>
  <label style="display: inline-flex; align-items: flex-start; gap: 8px;">
    <md-checkbox name="terms" value="accepted" required
                 value-missing-label="Please accept the terms."
                 error-text="You must accept to continue"></md-checkbox>
    <span style="display: flex; align-items: center; min-block-size: 48px;">I accept the terms</span>
  </label>
  <md-button type="submit">Continue</md-button>
</form>

<!-- Server-side validation (the methods are async) -->
<md-checkbox id="region" name="region"></md-checkbox>
<script type="module">
  const cb = document.getElementById('region');
  await cb.setCustomValidity('This option is unavailable in your region');
  // clear with: await cb.setCustomValidity('')
</script>
```

## Anti-patterns

| ❌ Wrong | ✅ Right | Why |
|---|---|---|
| `<md-checkbox>Label</md-checkbox>` | Wrap in `<label>`, or use `aria-label` | There is **no default slot** — the text won't render. |
| A hidden `<input>` mirroring the value | Use `name` + `value` | It's form-associated; the mirror double-submits. |
| Expecting `indeterminate` to persist through a click | Recompute it in your handler | Clicking resolves to checked/unchecked. |
| Listening for `mdValidityChange` on an ancestor across a shadow root | Listen on the element | `composed: false` by design. |
| A switch for a list of related options | `md-checkbox` | M3 states this directly. |
| A checkbox for a setting that applies instantly | `md-switch` | Checkboxes imply a submit step. |
| Ten checkboxes in a form | `md-multi-select` | Past ~7 the list dominates the layout. |
| Both `supporting-text` and `error-text` visible at once | Swap supporting → error | Showing both shifts layout (M3 text-field rule, same logic). |
| Pre-checked consent | Leave it unchecked | Consent must be an affirmative act. |
| Hardcoded English `value-missing-label` in a localized app | Feed it from your dictionary | It's a prop precisely so you can. |
| A bare text node next to a checkbox that has a message | Wrap it and centre it on the touch target | With a message the host stacks, so the text aligns to the target's top, ~15px above the box. |

## Accessibility, RTL, density, i18n

**Accessibility**
- Wrapping in `<label>` gives both the accessible name and a larger hit target —
  the preferred pattern. Otherwise `aria-label` / `aria-labelledby`.
- Tri-state is exposed as `aria-checked="mixed"` when `indeterminate`.
- `disabled` leaves the tab order; `soft-disabled` stays focusable.
- Errors surface in `error-text` next to the control, not only in a transient
  browser balloon.
- `--md-checkbox-touch-target-size` keeps the hit area ≥48px even when the
  visual box shrinks with density — don't set it below that on touch.
- The message line is inset by `(touch-size − container-size) / 2` so it lines
  up with the visible box at every density rung and any custom touch-target
  size, rather than with the wider invisible target.

**RTL** — the control mirrors automatically; the label side follows the
document direction.

**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 1px off the box and icon (18px → 14px floor) and 4px off the touch
target (48px → 32px floor); the state layer is `min(40px, touch)` so it never
exceeds the target. Watch the touch target at deep rungs.

**i18n** — translate `supporting-text`, `error-text`, `value-missing-label`, and
the visible label text.

## Related components

`md-radio` · `md-switch` · `md-multi-select` · `md-transfer-list` ·
`md-chip` · `md-ripple`

## Theming

| Custom property | Purpose | Default |
|---|---|---|
| `--md-checkbox-container-color` | Box fill when unselected | `transparent` |
| `--md-checkbox-selected-container-color` | Box fill when checked / indeterminate | `--md-sys-color-primary` |
| `--md-checkbox-outline-color` | Box border colour | `--md-sys-color-on-surface-variant` |
| `--md-checkbox-outline-width` | Box border width | `2px` |
| `--md-checkbox-icon-color` | Checkmark / dash colour | `--md-sys-color-on-primary` |
| `--md-checkbox-icon-size` | Glyph box | `max(14px, 18px + density * 1px)` |
| `--md-checkbox-container-shape` | Box corner radius | `2px` |
| `--md-checkbox-container-size` | Visible box size | `max(14px, 18px + density * 1px)` |
| `--md-checkbox-touch-target-size` | Hit area before density trim (keep >= 48px on touch) | `48px` |
| `--md-checkbox-state-layer-size` | Hover/press overlay diameter | `min(40px, touch target)` |
| `--md-checkbox-state-layer-color` | Overlay colour, unselected | `--md-sys-color-on-surface` |
| `--md-checkbox-selected-state-layer-color` | Overlay colour, selected | `--md-sys-color-primary` |
| `--md-checkbox-supporting-text-color` | `supporting-text` colour | `--md-sys-color-on-surface-variant` |
| `--md-checkbox-error-text-color` | `error-text` colour | `--md-sys-color-error` |

**CSS parts** — `target`, `state-layer`, `container`, `icon`,
`supporting-text`.

```css
md-checkbox.brand {
  --md-checkbox-selected-container-color: var(--md-sys-color-tertiary);
  --md-checkbox-icon-color: var(--md-sys-color-on-tertiary);
}
```

<!-- Auto Generated Below -->


## Overview

`md-checkbox` — Material Design 3 checkbox (with tri-state / indeterminate).

Form-associated: inside a `<form>` it submits its `value` under `name` when
checked, and restores on form reset. It is a *labelable* element — wrap it in
a `<label>` (clicks on the label text toggle it AND give it its accessible
name natively), or pass `aria-label` / `aria-labelledby` on the host. A bare,
unlabeled checkbox has no accessible name (axe `aria-toggle-field-name`).

## Properties

| Property            | Attribute             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Type                        | Default                                           |
| ------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------- |
| `checked`           | `checked`             | Whether the checkbox is checked                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `boolean`                   | `false`                                           |
| `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`            | Disables the checkbox                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `boolean`                   | `false`                                           |
| `error`             | `error`               | Show the supporting line in the error colour.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `boolean`                   | `false`                                           |
| `errorText`         | `error-text`          | Supporting / error message shown beneath the control.  A checkbox previously had nowhere to put a message, so a failed `required` could only surface as the browser's own validation balloon — visually unrelated to the field, and gone the moment you click away. This gives it the same inline supporting line md-text-field has.  The host is a fixed-size touch target, so the line is positioned OUT of that box rather than laid out inside it; see the CSS for why that cannot simply be a flex child. | `string`                    | `''`                                              |
| `indeterminate`     | `indeterminate`       | Whether the checkbox is in the indeterminate (mixed) state                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `boolean`                   | `false`                                           |
| `name`              | `name`                | Form name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `string`                    | `''`                                              |
| `required`          | `required`            | Whether the checkbox is required in a form                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `boolean`                   | `false`                                           |
| `softDisabled`      | `soft-disabled`       | Soft-disabled: disabled visuals but remains focusable for discoverability                                                                                                                                                                                                                                                                                                                                                                                                                                      | `boolean`                   | `false`                                           |
| `supportingText`    | `supporting-text`     | Supporting text shown when there is no error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `string`                    | `''`                                              |
| `value`             | `value`               | Form value submitted when checked                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `string`                    | `'on'`                                            |
| `valueMissingLabel` | `value-missing-label` | Localized constraint-validation message shown when `required` is unmet.  A prop rather than a hardcoded string, matching md-time-picker's `value-missing-label`: components stay i18n-engine-agnostic and the consumer localizes through its own dictionary. Native inputs get their message from the browser's locale for free; a form-associated custom element supplies its own, so leaving this hardcoded would ship an English-only form to every locale.                                                 | `string`                    | `'Please check this box if you want to proceed.'` |


## Events

| Event              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Type                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `mdChange`         | Emits when checked or indeterminate state changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `CustomEvent<{ checked: boolean; indeterminate: boolean; }>`                                  |
| `mdValidityChange` | Fires when this control's validity CHANGES — never on every keystroke, and never for a re-publish that lands on the same state.  `composed: false` is deliberate. Composites like md-select embed an md-text-field, and a composed event escapes that inner shadow root, so a listener on md-select would receive the inner field's event as well as the host's — two events, different payloads, for one logical control. Keeping it uncomposed means each component reports only for itself, while `bubbles: true` still lets a <form> or app root hear every control. | `CustomEvent<{ valid: boolean; validationMessage: string; flags: Record<string, boolean>; }>` |


## Methods

### `checkValidity() => Promise<boolean>`

Constraint-validation API, matching md-text-field and the native contract.

#### Returns

Type: `Promise<boolean>`



### `getValidity() => Promise<{ valid: boolean; validationMessage: string; flags: Record<string, boolean>; }>`

Current validity: boolean, message and flags. Mirrors md-text-field.

#### Returns

Type: `Promise<{ valid: boolean; validationMessage: string; flags: Record<string, boolean>; }>`



### `reportValidity() => Promise<boolean>`

Like checkValidity(), but also shows the browser's validation message.

#### Returns

Type: `Promise<boolean>`



### `setCustomValidity(message: string) => Promise<void>`

App/server-side validation: a non-empty message marks the control invalid
for its form until cleared with an empty string.

#### Parameters

| Name      | Type     | Description |
| --------- | -------- | ----------- |
| `message` | `string` |             |

#### Returns

Type: `Promise<void>`




## Shadow Parts

| Part                | Description                        |
| ------------------- | ---------------------------------- |
| `"container"`       | Box container that holds the icon  |
| `"icon"`            | Material Symbols glyph: `check`, or `remove` when indeterminate |
| `"state-layer"`     | State-layer overlay                |
| `"supporting-text"` | The message line (`supporting-text` / `error-text`) |
| `"target"`          | The 48px touch target that clips the ripple |


## Dependencies

### Used by
 - [md-transfer-list](../md-transfer-list)

### Depends on

- [md-ripple](../md-ripple)

### Graph
```mermaid
graph TD;
  md-checkbox --> md-ripple
  md-transfer-list --> md-checkbox
  style md-checkbox fill:#f9f,stroke:#333,stroke-width:4px
```

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

*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.