@awc-ui/core

Material Design 3 Web Components, built with Stencil. 56 components that ship as standard custom elements, so they work in React, Angular, Vue, Svelte, or plain HTML, with SSR for Next.js, Nuxt, SvelteKit, Astro, and Angular.

For AI assistants

This package ships its own documentation. To point your project's assistants at it — Claude Code, Cursor, Copilot, Codex — run once, after installing:

npx awc-ui ai-setup

That writes a small block into the files those tools already read (AGENTS.md, CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md), leaving your own instructions in them untouched. Nothing is fetched from the network.

The documentation itself:

| File | What it gives you | | -------------------------------- | ----------------------------------------------------------------------------------------- | | main-llm.md | Start here. Interview, decision matrix, token reference, page recipes, ship checklist | | src/components/<tag>/readme.md | Full manual for one component — API, accessibility contract, anti-patterns |

Each component's manual has a When NOT to use and an Anti-patterns section. Read them: they describe the mistakes assistants actually make with this library.

Install

npm install @awc-ui/core

Start a project or check setup

npx --package @awc-ui/core awc-ui init my-app --framework next --dry-run
npx --package @awc-ui/core awc-ui init my-app --framework next

Bundled starters: html, next, nuxt, sveltekit, and astro. The command copies files into an empty directory and prints the install/run commands. It does not overwrite an existing project or install dependencies. Remove --dry-run to create the files. React, Angular, Vue and Svelte integration guides cover adding AWC UI to existing applications.

From an existing project:

npx awc-ui doctor
npx awc-ui doctor --json

The doctor checks local package resolution, coordinated package versions and source-level setup signals. It reports checks that still require a browser, such as SSR adoption. --framework overrides automatic framework detection.

Use

One import registers every element and loads the design tokens:

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

<md-button variant="filled" icon="add">Add item</md-button>

define imports tokens.css, so it is a bundler-only entry. Two cases need something else:

| Situation | Entry | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | Bundler (Vite, webpack, Next, Nuxt…) | import '@awc-ui/core/define' | | CDN / no bundler | load the loader, plus <link rel="stylesheet" href="…/@awc-ui/tokens/src/tokens.css"> | | Server-side rendering | @awc-ui/core/hydrate — reference apps for Next.js, Nuxt, SvelteKit, Astro, and Angular SSR live under apps/ in the repo |

Smallest bundles: per-component imports

define registers the elements for all 56 components, including their nested sub-components. Apps that want to ship only what they use import per component instead (the tokens then need one explicit CSS import):

import "@awc-ui/core/css/tokens.css";
import { defineCustomElement } from "@awc-ui/core/components/md-button";
defineCustomElement();

Client-only apps (no SSR) can go one step further: every components/* module also exists under components-csr/* — the same element with the Declarative-Shadow-DOM hydration support compiled out (≈3 kB gz smaller runtime). Import from there directly, or alias @awc-ui/core/dist/components → @awc-ui/core/dist/components-csr in the bundler to switch a whole app (framework wrappers included) in one line.

Framework wrappers

The elements work untouched anywhere, but typed wrappers give you props, events and JSX types:

| Framework | Package | | --------- | ------------------------------------------------------------------ | | React | @awc-ui/react | | Angular | @awc-ui/angular | | Vue | @awc-ui/vue | | Svelte | @awc-ui/svelte |

What's in the box

• 56 components across actions, selection, text inputs, navigation, containment, communication and data display.
• Design tokens — 200+ --md-sys-* custom properties, light and dark, plus per-component hooks and ::part() for anything the props don't cover.
• Accessibility — WAI-ARIA roles, keyboard support and focus management, verified with axe in CI. See https://awc-ui.dev/guides/accessibility/.
• Form participation — inputs are form-associated via ElementInternals, so they land in FormData and take part in constraint validation.
• RTL — logical properties throughout; directional icons mirror.
• Density — a global data-density signal, or a per-component density prop, from 0 down to -4.

Documentation

• Docs and live demos — https://awc-ui.dev
• Component reference — every component ships a readme.md next to its source with API, do/don't, patterns and anti-patterns.

License

MIT © AWC UI