Installation

Package Manager

Install the core component library and design tokens:

npm install @awc-ui/core @awc-ui/tokens

Or with other package managers:

# pnpm
pnpm add @awc-ui/core @awc-ui/tokens

# yarn
yarn add @awc-ui/core @awc-ui/tokens

Technology Wrappers

For the best developer experience, install the wrapper package for your technology:

# No wrapper needed — use the core package directly
npm install @awc-ui/core @awc-ui/tokens

npm install @awc-ui/core @awc-ui/tokens @awc-ui/react

npm install @awc-ui/core @awc-ui/tokens @awc-ui/angular

npm install @awc-ui/core @awc-ui/tokens @awc-ui/vue

npm install @awc-ui/core @awc-ui/tokens @awc-ui/svelte

Required Fonts

Add these to your HTML <head> for icons and typography:

<!-- Material Symbols Outlined — the icon font the library is built around.
     The four axis ranges are required: a default request returns a static
     instance and the FILL transition silently stops working. -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap">

<!-- Roboto (default MD3 body font) -->
<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap">

The request above downloads the entire variable icon font — close to 4 MB. That is convenient while prototyping (every icon just works) but is by far the largest transfer an AWC UI app makes. For production, list the icons you actually use with icon_names — Google Fonts then serves a subset font of a few kB with the same variable axes, so FILL transitions keep working:

<link rel="stylesheet"
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&icon_names=add,delete,menu,search&display=block">

Two rules: the icon_names list must be alphabetically sorted (the API rejects unsorted lists), and prefer display=block for icon fonts — with swap, users see the raw ligature text (“search”) until the font arrives. Audit your icons with a grep over icon= attributes and slotted material-symbols-outlined spans when the list drifts.

Or install from npm:

npm install material-icons material-symbols

import 'material-icons/iconfont/material-icons.css';
import 'material-symbols/outlined.css';

Component Registration

There are three ways to register components:

Option A: Auto-register all (recommended)

import '@awc-ui/core/define';

This registers every component and loads the AWC UI design-token stylesheet.

Option B: Lazy-load via the loader

import { defineCustomElements } from '@awc-ui/core/loader';
defineCustomElements(window);

Components are registered on-demand when first encountered in the DOM.

Option C: Per-component tree-shaking

import '@awc-ui/core/components/md-button';
import '@awc-ui/core/components/md-text-field';

Only the imported components are included in your bundle.

Design Tokens

The tokens CSS is automatically loaded with Option A. For Options B and C, import the tokens separately:

import '@awc-ui/tokens/tokens.css';

This provides all the --md-sys-* CSS custom properties for colors, typography, shape, elevation, and motion.

Next Steps

Quick Start — build your first page with AWC UI components
Components — browse all 48 MD3 components, each with HTML, React, Angular, Vue, and Svelte tabs in-page
Theming — customize colors, shapes, and typography