On this page Theme Theme

The m3e-theme component is a non-visual element used to apply dynamic color, expressive motion, density, and strong focus indicators to nested, theme-aware elements.

Installation 
npm i @m3e/theme
 Usage

This section outlines usage examples and configuration guidance for the components in this package.

Color

Use the color attribute to specify a HEX color from which to derive color palettes. This will set CSS custom properties that reflect the standard Material Design 3 color palettes. For example, --md-sys-color-primary is set to the primary color.

Primary
On Primary
Primary Container
On Primary Container
Secondary
On Secondary
Secondary Container
On Secondary Container
Tertiary
On Tertiary
Tertiary Container
On Tertiary Container
Error
On Error
Error Container
On Error Container
Background
On Background
Surface
On Surface
Surface Variant
On Surface Variant
Inverse Surface
Inverse On Surface
Outline
Outline Variant
Shadow
Scrim
Surface Tint
 
<m3e-theme color="#4285F4">
  <!-- Swatches omitted for brevity -->
</m3e-theme>
Schemes

Themes support three color schemes: light, dark, and auto (default). Use the scheme attribute to specify the color scheme.

When auto is used, the theme dynamically responds to system preferences by monitoring the media queries (prefers-color-scheme: light) and (prefers-color-scheme: dark), selecting the appropriate color scheme based on the user's environment.

Primary
On Primary
Primary Container
On Primary Container
Secondary
On Secondary
Secondary Container
On Secondary Container
Tertiary
On Tertiary
Tertiary Container
On Tertiary Container
Error
On Error
Error Container
On Error Container
Background
On Background
Surface
On Surface
Surface Variant
On Surface Variant
Inverse Surface
Inverse On Surface
Outline
Outline Variant
Shadow
Scrim
Surface Tint
 
<m3e-theme color="#4285F4" scheme="dark">
  <!-- Swatches omitted for brevity -->
</m3e-theme>
Density

Use the density attribute to control layout compactness across density-aware components within a theme. It adjusts spacing, padding, and sizing to achieve a more compact or more spacious visual rhythm.

When a theme is initialized with a density value, it sets the system token --md-sys-density-scale to reflect that value. This token is used by density-aware components to adjust their internal layout metrics.

The following example demonstrates how m3e-button responds to theme-level density adjustments. A medium-sized button is shown, which supports a minimum density of -2. Note that densities -3 and -2 produce identical layout behavior for this size, as values below the supported threshold are clamped to -2.

-3 density -2 density -1 density 0 (default) density 1 density 
<m3e-theme density="-3">
  <!-- Buttons omitted for brevity -->
</m3e-theme>
<!-- Additional densities omitted for brevity -->
Motion

Themes support two motion schemes: standard (default) and expressive. These schemes define how components animate across the system, using spring-based physics to guide spatial and effect transitions. Use the motion attribute to control the motion scheme.

The following example illustrates how the m3e-switch adapts to the motion scheme. Note the spring effect when clicking the expressive example. 

<m3e-theme motion="standard">
  <!-- Switch omitted for brevity -->
</m3e-theme>
<m3e-theme motion="expressive">
  <!-- Switch omitted for brevity -->
</m3e-theme>
Accessibility

By default, themes are not given an ARIA role, indicating that they are treated as neutral, non-semantic elements in the accessibility tree unless explicitly referenced or annotated.

Native module support

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following. 

<script type="module" src="/node_modules/@m3e/theme/dist/index.js"></script>

In addition, you must use an import map to include dependencies. 

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

For production, use index.min.js for faster load times.

API

This package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.