@alacris/ui 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alacris contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,148 @@
-Placeholder. Real releases come from https://github.com/bmartel/alacris
+# Alacris UI
+
+A complete, themeable design system built with **[Alacris](https://github.com/bmartel/alacris)** and nothing else. No other runtime dependencies, no build step, no CSS framework — 68 components, a three-tier token system, a theme engine that re-skins the whole page with one stylesheet write, and a documented motion layer.
+
+**Material Design is the default. Your design system is the point.** Every visual decision flows through tokens you can override at three levels — from "change the brand color" (one line) to "this is no longer Material at all".
+
+The tags are real custom elements, so they work in plain HTML and inside React, Vue, Svelte, Angular, Rails, Django, and [Alacris-Go](https://github.com/bmartel/alacris-go) — anywhere that renders a tag.
+
+**Docs:** [Getting started](https://bmartel.github.io/alacris/ui/getting-started/)
+
+## Install
+
+```bash
+npm install @alacris/ui
+```
+
+That pulls in `@alacris/core` as well. Do not also load a second copy of Alacris from a CDN on the same page — two copies means two reactive graphs, and updates stop crossing the boundary.
+
+```js
+import { applyTheme } from '@alacris/ui';
+
+applyTheme({ seed: '#0b57d0' });
+```
+
+```html
+<ui-button>Hello</ui-button>
+<ui-text-field label="Email" clearable></ui-text-field>
+<ui-switch label="Dark mode"></ui-switch>
+```
+
+Importing `@alacris/ui` registers every component. For a smaller page, import only what you use — each component module is self-contained:
+
+```js
+import { applyTheme } from '@alacris/ui/theme';
+import '@alacris/ui/components/ui-button.js';
+import '@alacris/ui/components/ui-text-field.js';
+
+applyTheme({ seed: '#0b57d0' });
+```
+
+### Without a bundler
+
+The published package is plain ESM. Point an import map at a pinned CDN build of Alacris (the only bare specifier the UI source uses) and at this package:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@alacris/core": "https://cdn.jsdelivr.net/npm/@alacris/core@0.11/dist/alacris.js",
+    "@alacris/ui": "https://cdn.jsdelivr.net/npm/@alacris/ui/src/index.js",
+    "@alacris/ui/theme": "https://cdn.jsdelivr.net/npm/@alacris/ui/src/theme/index.js",
+    "@alacris/ui/components/": "https://cdn.jsdelivr.net/npm/@alacris/ui/src/components/"
+  }
+}
+</script>
+<script type="module">
+  import { applyTheme } from '@alacris/ui';
+  applyTheme({ seed: '#0b57d0' });
+</script>
+
+<ui-button>Hello</ui-button>
+```
+
+Pin both packages in production.
+
+## Theming
+
+```js
+import { createTheme, applyTheme, setScheme, toggleScheme } from '@alacris/ui/theme';
+
+applyTheme({ seed: '#6750a4' });
+applyTheme({ seed: '#b3261e', density: -1 });
+setScheme('dark');
+toggleScheme();
+
+applyTheme(createTheme({
+  colors: { primary: '#0b57d0', tertiary: '#00695c' },
+  typography: 'google-sans',
+  shape: { radius: 0.5 },
+  overrides: { light: { 'color-surface': '#faf7f2' } },
+}));
+```
+
+`applyTheme` writes **one** document-level stylesheet of `--ui-*` custom properties and replaces it in place on the next call. Scheme switching after that is `data-ui-scheme` on `<html>` (`light` | `dark` | `auto`).
+
+Three places to intervene, from broadest to narrowest:
+
+1. **Re-theme the system** — `applyTheme({ seed, shape, … })`. Every component follows. Dark mode is generated automatically.
+2. **Re-skin one component type** — `ui-button { --ui-button-radius: 4px; }`.
+3. **Reach inside one instance** — `ui-dialog::part(surface) { backdrop-filter: blur(8px) }`.
+
+Full guide: [docs/theming.md](docs/theming.md).
+
+## Motion
+
+```js
+import { animate, fx, presence, withFlip } from '@alacris/ui/motion';
+
+animate(el, fx.slideInUp, { duration: 'medium2', easing: 'emphasizedDecelerate' });
+
+html`${presence(open, () => html`<div class="sheet">…</div>`, {
+  enter: fx.slideInUp, exit: fx.slideOutDown,
+})}`;
+```
+
+Durations and easings are tokens, so the theme's `motion.scale` governs CSS transitions and JS animation alike, and `prefers-reduced-motion` is honoured automatically. Full guide: [docs/motion.md](docs/motion.md).
+
+## Forms
+
+Named controls (`ui-text-field`, `ui-switch`, `ui-checkbox`, `ui-select`, …) are form-associated custom elements. Give a component a `name` and it submits, resets, and follows `<fieldset disabled>` like a native field.
+
+## Entry points
+
+| Import | What it is |
+| --- | --- |
+| `@alacris/ui` | registers every component; re-exports theme, motion, tokens, utilities |
+| `@alacris/ui/theme` | `createTheme`, `applyTheme`, scheme switching |
+| `@alacris/ui/motion` | `animate`, `fx`, `presence`, `withFlip`, `ripple` |
+| `@alacris/ui/tokens` | `sys` and the token engines |
+| `@alacris/ui/components/ui-button.js` | one element, registered as a side effect |
+
+Component modules have side effects (they call `define()`). Theme, motion and token modules do not.
+
+## In this repository
+
+This package lives in `starter/` of the [Alacris repo](https://github.com/bmartel/alacris) so the library and the design system can be developed together. They **publish separately**: `@alacris/ui` has its own version, changelog, and npm release. A commit that only changes this folder does not cut an Alacris library release.
+
+```
+starter/
+  src/           the published modules
+  types/         hand-written .d.ts
+  demo/          kitchen-sink app (not published)
+  docs/          theming, motion, component catalog
+  test/          node smoke tests
+  CONVENTIONS.md rules every component follows
+```
+
+From a clone of the repo:
+
+```bash
+npm install
+npm run demo        # http://localhost:5173/starter/
+cd starter && npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,79 @@
 {
   "name": "@alacris/ui",
-  "version": "0.0.0",
-  "description": "Placeholder so trusted publishing can be configured. Do not use.",
+  "version": "0.1.0",
+  "description": "Themeable design system for Alacris — Material defaults, sixty-eight custom elements, ESM-only, no build step.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./theme": {
+      "types": "./types/index.d.ts",
+      "default": "./src/theme/index.js"
+    },
+    "./motion": {
+      "types": "./types/index.d.ts",
+      "default": "./src/motion/index.js"
+    },
+    "./tokens": {
+      "types": "./types/index.d.ts",
+      "default": "./src/tokens/index.js"
+    },
+    "./components/*": "./src/components/*",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "module": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "unpkg": "./src/index.js",
+  "jsdelivr": "./src/index.js",
+  "sideEffects": [
+    "./src/index.js",
+    "./src/components/**/*.js"
+  ],
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node ../scripts/serve.js 5174",
+    "pretest": "node -e \"const fs=require('fs');fs.mkdirSync('node_modules/@alacris',{recursive:true});try{fs.symlinkSync('../../..','node_modules/@alacris/core')}catch{}\"",
+    "test": "node --import ./test/setup.js --test test/*.test.js",
+    "catalog": "node scripts/catalog.mjs"
+  },
+  "dependencies": {
+    "@alacris/core": "^0.11.0"
+  },
+  "peerDependencies": {
+    "@alacris/core": "^0.11.0"
+  },
+  "keywords": [
+    "alacris",
+    "web-components",
+    "custom-elements",
+    "design-system",
+    "material",
+    "theme",
+    "esm"
+  ],
   "license": "MIT",
-  "publishConfig": { "access": "public" }
+  "author": "Brandon Martel <brandonmartel@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bmartel/alacris.git",
+    "directory": "starter"
+  },
+  "homepage": "https://bmartel.github.io/alacris/ui/getting-started/",
+  "bugs": {
+    "url": "https://github.com/bmartel/alacris/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
 }

package/src/components/base.js

@@ -0,0 +1,46 @@
+// Shared base for every component's `styles` list. `css` interns by text, so
+// this parses exactly once for the whole page no matter how many components
+// include it.
+
+import { css } from '@alacris/core';
+import { sys } from '../tokens/sys.js';
+
+export const base = css`
+  *, *::before, *::after { box-sizing: border-box; }
+  :host {
+    font-family: ${sys.font.plain};
+    font-optical-sizing: auto;
+    font-synthesis: none;
+    -webkit-tap-highlight-color: transparent;
+  }
+  :host([hidden]) { display: none; }
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      transition-duration: 0.01ms;
+      animation-duration: 0.01ms;
+      animation-iteration-count: 1;
+    }
+  }
+`;
+
+/**
+ * The focus ring rule for a selector, e.g. ${focusRingOn('.control')}.
+ * Interpolate into a component's css template.
+ */
+export const focusRingOn = (selector) => `
+  ${selector}:focus-visible {
+    outline: var(--ui-focus-ring);
+    outline-offset: var(--ui-focus-ring-offset);
+  }
+`;
+
+/**
+ * Hover / focus-visible / pressed opacities for a `.layer` descendant.
+ * `host` is the interactive element (`.control`, `.header`, …). Pass
+ * `focus` when focus lives on a different node (the host custom element).
+ */
+export const stateLayerOn = (host, { focus = host } = {}) => `
+  ${host}:hover .layer { opacity: var(--ui-state-hover); }
+  ${focus}:focus-visible .layer { opacity: var(--ui-state-focus); }
+  ${host}:active .layer { opacity: var(--ui-state-pressed); }
+`;

package/src/components/ui-accordion-item.js

@@ -0,0 +1,157 @@
+// <ui-accordion-item> — one expandable panel inside <ui-accordion>.
+//
+// @prop  {string}  value=''       — REQUIRED identity of the panel (reported in events)
+// @prop  {boolean} expanded=false
+// @prop  {boolean} disabled=false
+// @prop  {string}  headline=''    — header text
+// @event ui-accordion-toggle — header activated; detail: { value, expanded }
+// @slot  (default) — panel content
+// @part  header  — the header <button>
+// @part  content — the collapsible region
+// @part  body    — padded wrapper around the default slot
+// @vars  see `t` below (`themeVars.names`)
+//
+// Expand/collapse animates block-size from the measured content height; in
+// environments without layout (zero heights) the animation is skipped and the
+// state applies instantly. The content region gets `hidden` only AFTER the
+// collapse animation completes.
+
+import { define, html, css, vars, effect } from '@alacris/core';
+import { sys } from '../tokens/sys.js';
+import { base, focusRingOn } from './base.js';
+import { ripple } from '../motion/ripple.js';
+import { animate } from '../motion/animate.js';
+import './ui-icon.js';
+
+const t = vars('ui-accordion-item', {
+  headerMinHeight: '48px',
+  padInline: sys.space(4),
+  headerFg: sys.color.onSurface,
+  iconFg: sys.color.onSurfaceVariant,
+  contentFg: sys.color.onSurfaceVariant,
+  font: sys.type.titleMd,
+  tracking: sys.tracking.titleMd,
+  contentFont: sys.type.bodyMd,
+  contentTracking: sys.tracking.bodyMd,
+});
+
+const styles = css`
+  :host { display: block; }
+  .heading { margin: 0; font: inherit; }
+  .header {
+    position: relative;
+    isolation: isolate;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: ${sys.space(3)};
+    inline-size: 100%;
+    min-block-size: calc(${t.headerMinHeight} + var(--ui-density, 0) * 4px);
+    padding-inline: ${t.padInline};
+    padding-block: ${sys.space(2)};
+    border: none;
+    background: transparent;
+    color: ${t.headerFg};
+    font: ${t.font};
+    letter-spacing: ${t.tracking};
+    text-align: start;
+    cursor: pointer;
+    user-select: none;
+  }
+  ${focusRingOn('.header')}
+  .layer {
+    position: absolute; inset: 0; z-index: -1;
+    background: currentColor; opacity: 0;
+    transition: opacity ${sys.duration.short2} ${sys.easing.standard};
+  }
+  .header:hover .layer { opacity: ${sys.state.hover}; }
+  .header:focus-visible .layer { opacity: ${sys.state.focus}; }
+  .header:active .layer { opacity: ${sys.state.pressed}; }
+  .header:disabled {
+    cursor: default;
+    pointer-events: none;
+    color: color-mix(in srgb, ${sys.color.onSurface} calc(${sys.state.disabledContent} * 100%), transparent);
+  }
+  .chevron {
+    color: ${t.iconFg};
+    transition: rotate ${sys.duration.short4} ${sys.easing.standard};
+  }
+  .header:disabled .chevron { color: inherit; }
+  .chevron.open { rotate: 180deg; }
+  .content { overflow: hidden; }
+  .content[hidden] { display: none; }
+  .body {
+    padding-inline: ${t.padInline};
+    padding-block-end: ${sys.space(4)};
+    font: ${t.contentFont};
+    letter-spacing: ${t.contentTracking};
+    color: ${t.contentFg};
+  }
+`;
+
+define('ui-accordion-item', {
+  props: { value: '', expanded: false, disabled: false, headline: '' },
+  styles: [base, styles],
+  setup({ value, expanded, disabled, headline }, host) {
+    let contentEl = null;
+    let anim = null;
+
+    // Animate block-size between 0 and the measured content height. Zero
+    // heights (no layout, e.g. simulated DOM) skip the animation entirely.
+    const apply = (exp) => {
+      const el = contentEl;
+      anim?.cancel();
+      anim = null;
+      if (exp) {
+        el.hidden = false;
+        const h = el.scrollHeight;
+        if (!h) return;
+        const a = (anim = animate(el, [{ blockSize: '0px' }, { blockSize: `${h}px` }], {
+          duration: 'medium2', easing: 'emphasizedDecelerate',
+        }));
+        // Cancelling after it finishes drops the fill, so block-size clears
+        // back to auto (the end keyframe equals the natural height).
+        a.finished.then(() => { if (anim === a) { anim = null; a.cancel(); } }, () => {});
+      } else {
+        const h = el.scrollHeight;
+        if (!h) { el.hidden = true; return; }
+        const a = (anim = animate(el, [{ blockSize: `${h}px` }, { blockSize: '0px' }], {
+          duration: 'short4', easing: 'emphasizedAccelerate',
+        }));
+        a.finished.then(() => { if (anim === a) { anim = null; a.cancel(); el.hidden = true; } }, () => {});
+      }
+    };
+
+    effect(() => {
+      const exp = expanded();
+      if (contentEl) apply(exp); // first run precedes the ref; it syncs below
+    });
+
+    const toggle = () => {
+      if (disabled()) return;
+      expanded.set(!expanded());
+      host.emit('ui-accordion-toggle', { value: value(), expanded: expanded() });
+    };
+
+    return html`
+      <h3 class="heading">
+        <button part="header" class="header" type="button" id="header"
+                ?disabled=${disabled}
+                aria-expanded=${() => String(expanded())}
+                aria-controls="content"
+                @click=${toggle}
+                ref=${(el) => ripple(el, { disabled })}>
+          <span class="layer" aria-hidden="true"></span>
+          <span class="headline">${headline}</span>
+          <ui-icon class=${() => `chevron${expanded() ? ' open' : ''}`} name="expand-more"></ui-icon>
+        </button>
+      </h3>
+      <div part="content" class="content" id="content" role="region" aria-labelledby="header"
+           ref=${(el) => { contentEl = el; el.hidden = !expanded.peek(); }}>
+        <div class="body" part="body"><slot></slot></div>
+      </div>`;
+  },
+});
+
+export const tag = 'ui-accordion-item';
+export const themeVars = t;

package/src/components/ui-accordion.js

@@ -0,0 +1,58 @@
+// <ui-accordion> — groups <ui-accordion-item> panels.
+//
+//   <ui-accordion>
+//     <ui-accordion-item value="a" headline="First">…</ui-accordion-item>
+//     <ui-accordion-item value="b" headline="Second">…</ui-accordion-item>
+//   </ui-accordion>
+//
+// @prop  {boolean} multi=false — allow several panels open at once; when
+//                                false, expanding one collapses the others
+// @event change — a panel was toggled by the user; detail: { value }
+// @slot  (default) — <ui-accordion-item> children
+// @vars  see `t` below (`themeVars.names`)
+//
+// Coordination rides the bubbling `ui-accordion-toggle` event from the items,
+// so only user interaction triggers single-open collapse; programmatic
+// `expanded` writes on an item are left alone.
+
+import { define, html, css, vars, onCleanup } from '@alacris/core';
+import { sys } from '../tokens/sys.js';
+import { base } from './base.js';
+import './ui-accordion-item.js';
+
+const t = vars('ui-accordion', {
+  dividerColor: sys.color.outlineVariant,
+});
+
+const styles = css`
+  :host { display: block; }
+  ::slotted(ui-accordion-item:not(:first-child)) {
+    border-block-start: 1px solid ${t.dividerColor};
+  }
+`;
+
+define('ui-accordion', {
+  props: { multi: false },
+  styles: [base, styles],
+  setup({ multi }, host) {
+    const onToggle = (e) => {
+      const item = e.target;
+      if (!multi() && e.detail?.expanded) {
+        for (const other of host.querySelectorAll('ui-accordion-item')) {
+          if (other !== item && other.expanded) other.expanded = false;
+        }
+      }
+      host.emit('change', { value: e.detail?.value });
+    };
+
+    // Listen on the host: items are light-DOM children, so their bubbling
+    // toggle events reach it without crossing this shadow root.
+    host.addEventListener('ui-accordion-toggle', onToggle);
+    onCleanup(() => host.removeEventListener('ui-accordion-toggle', onToggle));
+
+    return html`<slot></slot>`;
+  },
+});
+
+export const tag = 'ui-accordion';
+export const themeVars = t;

package/src/components/ui-alert.js

@@ -0,0 +1,168 @@
+// <ui-alert> — a severity-colored callout for statuses and messages.
+//
+//   <ui-alert severity="success" title="Saved" dismissible @dismiss=${remove}>
+//     Your changes are safe.
+//     <ui-button slot="action" variant="text">Undo</ui-button>
+//   </ui-alert>
+//
+// Live-region semantics: the host defaults to role="status" (announced
+// politely). If the alert appears dynamically in response to an event and must
+// interrupt, set role="alert" on the element yourself — an author-set role is
+// never overwritten.
+//
+// Dismissing: the close button collapses the alert (height + opacity), then
+// emits `dismiss`. The PARENT owns the DOM and removes the element (or flips
+// the condition rendering it).
+//
+// @prop  {string}  severity='info'  — info | success | warning | error
+// @prop  {string}  variant='tonal'  — tonal | filled | outlined
+// @prop  {boolean} dismissible=false — shows a trailing close button
+// @prop  {string}  icon=''  — leading icon override; defaults per severity
+//                             (info → 'info', success → 'check-circle',
+//                              warning → 'warning', error → 'error')
+// @prop  {string}  title='' — optional bold first line
+// @event dismiss — close button pressed, after the collapse animation
+// @slot  (default) — message body
+// @slot  action    — trailing action, e.g. a text <ui-button>
+// @part  container, icon, title, message, action, close
+// @vars  see `t` below (`themeVars.names`)
+
+import { define, html, css, vars, computed } from '@alacris/core';
+import { sys } from '../tokens/sys.js';
+import { base, focusRingOn } from './base.js';
+import { animate, settled } from '../motion/animate.js';
+import { ripple } from '../motion/ripple.js';
+import './ui-icon.js';
+
+const SEVERITY_ICONS = {
+  info: 'info',
+  success: 'check-circle',
+  warning: 'warning',
+  error: 'error',
+};
+
+const t = vars('ui-alert', {
+  radius: sys.radius.sm,
+  padding: sys.space(4),
+  gap: sys.space(3),
+  font: sys.type.bodyMd,
+  titleFont: sys.type.titleSm,
+});
+
+const styles = css`
+  :host { display: block; }
+  .container {
+    display: flex;
+    align-items: flex-start;
+    gap: ${t.gap};
+    padding: ${t.padding};
+    border: 1px solid transparent; /* structural: keeps outlined the same size */
+    border-radius: ${t.radius};
+    font: ${t.font};
+    letter-spacing: ${sys.tracking.bodyMd};
+  }
+  .icon { flex: none; --ui-icon-size: 1.375rem; }
+  .content { flex: 1; min-inline-size: 0; }
+  .title {
+    font: ${t.titleFont};
+    letter-spacing: ${sys.tracking.titleSm};
+    margin-block-end: ${sys.space(1)};
+  }
+  .action { flex: none; align-self: center; display: flex; align-items: center; }
+
+  /* tonal — severity container bg, on-container fg */
+  .tonal.info    { background: ${sys.color.infoContainer};    color: ${sys.color.onInfoContainer}; }
+  .tonal.success { background: ${sys.color.successContainer}; color: ${sys.color.onSuccessContainer}; }
+  .tonal.warning { background: ${sys.color.warningContainer}; color: ${sys.color.onWarningContainer}; }
+  .tonal.error   { background: ${sys.color.errorContainer};   color: ${sys.color.onErrorContainer}; }
+
+  /* filled — severity bg, on-severity fg */
+  .filled.info    { background: ${sys.color.info};    color: ${sys.color.onInfo}; }
+  .filled.success { background: ${sys.color.success}; color: ${sys.color.onSuccess}; }
+  .filled.warning { background: ${sys.color.warning}; color: ${sys.color.onWarning}; }
+  .filled.error   { background: ${sys.color.error};   color: ${sys.color.onError}; }
+
+  /* outlined — transparent bg, severity fg + border */
+  .outlined { background: transparent; border-color: currentColor; }
+  .outlined.info    { color: ${sys.color.info}; }
+  .outlined.success { color: ${sys.color.success}; }
+  .outlined.warning { color: ${sys.color.warning}; }
+  .outlined.error   { color: ${sys.color.error}; }
+
+  .close {
+    position: relative;
+    isolation: isolate;
+    flex: none;
+    align-self: center;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 28px;
+    block-size: 28px;
+    padding: 0;
+    border: none;
+    border-radius: ${sys.radius.full};
+    background: transparent;
+    color: inherit;
+    cursor: pointer;
+    --ui-icon-size: 18px;
+  }
+  ${focusRingOn('.close')}
+  .layer {
+    position: absolute; inset: 0; z-index: -1;
+    border-radius: inherit; background: currentColor; opacity: 0;
+    transition: opacity ${sys.duration.short2} ${sys.easing.standard};
+  }
+  .close:hover .layer { opacity: ${sys.state.hover}; }
+  .close:focus-visible .layer { opacity: ${sys.state.focus}; }
+  .close:active .layer { opacity: ${sys.state.pressed}; }
+`;
+
+define('ui-alert', {
+  props: { severity: 'info', variant: 'tonal', dismissible: false, icon: '', title: '' },
+  styles: [base, styles],
+  setup({ severity, variant, dismissible, icon, title }, host) {
+    // Polite live region by default; authors set role="alert" for interrupts.
+    if (!host.hasAttribute('role')) host.setAttribute('role', 'status');
+
+    const cls = computed(() => `container ${variant()} ${severity()}`);
+    const shownIcon = computed(() => icon() || SEVERITY_ICONS[severity()] || SEVERITY_ICONS.info);
+
+    let dismissing = false;
+    const onDismiss = () => {
+      if (dismissing) return;
+      dismissing = true;
+      const height = host.scrollHeight || 0;
+      // Simulated DOMs (and display:none hosts) measure 0 — skip straight out.
+      if (!height) { host.emit('dismiss'); return; }
+      host.style.overflow = 'hidden';
+      const anim = animate(
+        host,
+        [{ blockSize: `${height}px`, opacity: 1 }, { blockSize: '0px', opacity: 0 }],
+        { duration: 'medium1', easing: 'emphasizedAccelerate' },
+      );
+      settled(anim).then(() => host.emit('dismiss'));
+    };
+
+    return html`
+      <div class=${cls} part="container">
+        <ui-icon class="icon" part="icon" name=${shownIcon}></ui-icon>
+        <div class="content">
+          ${() => (title() ? html`<div class="title" part="title">${title}</div>` : null)}
+          <div class="message" part="message"><slot></slot></div>
+        </div>
+        <div class="action" part="action"><slot name="action"></slot></div>
+        ${() =>
+          dismissible()
+            ? html`<button class="close" part="close" type="button" aria-label="Dismiss"
+                      @click=${onDismiss} ref=${(el) => ripple(el, { centered: true })}>
+                  <span class="layer" aria-hidden="true"></span>
+                  <ui-icon name="close"></ui-icon>
+                </button>`
+            : null}
+      </div>`;
+  },
+});
+
+export const tag = 'ui-alert';
+export const themeVars = t;