Alacris UI

A complete, themeable design system built with Alacris and nothing else. No other runtime dependencies, no build step, no CSS framework — 71 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 — anywhere that renders a tag.

Docs: Live catalog · Getting started

Install

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.

import { applyTheme } from '@alacris/ui';

applyTheme({ seed: '#0b57d0' });

<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:

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:

<script type="importmap">
{
  "imports": {
    "@alacris/core": "https://cdn.jsdelivr.net/npm/@alacris/[email protected]/dist/alacris.js",
    "@alacris/ui": "https://cdn.jsdelivr.net/npm/@alacris/[email protected]/src/index.js",
    "@alacris/ui/theme": "https://cdn.jsdelivr.net/npm/@alacris/[email protected]/src/theme/index.js",
    "@alacris/ui/components/": "https://cdn.jsdelivr.net/npm/@alacris/[email protected]/src/components/"
  }
}
</script>
<script type="module">
  import { applyTheme } from '@alacris/ui';
  applyTheme({ seed: '#0b57d0' });
</script>

<ui-button>Hello</ui-button>

Never mix two versions of @alacris/core on one page — two copies means two reactive graphs.

Theming

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.

Motion

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.

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.

Mobile viewport

Dialogs, sheets, drawers and the modal date picker are position: fixed; inset: 0 overlays sized by the visible viewport, not 100vh (which on phones and tablets is the height with the URL bar hidden, so a 100vh overlay runs off the bottom of the screen). Only the body scrolls, so headlines and actions stay on screen; drawers scroll their content above an optional pinned footer slot.

Two lines in the page's viewport meta finish the job:

<meta name="viewport"
      content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content">

• interactive-widget=resizes-content makes the on-screen keyboard shrink the layout viewport (Chrome on Android, 108+), so open overlays shrink above it with no script. Without it, the components follow window.visualViewport instead and pad themselves above the keyboard; that also covers browsers that ignore the key.
• viewport-fit=cover lets the page draw under notches and home indicators. Overlays then pad by env(safe-area-inset-*); without it those insets are 0 and nothing changes.

Own overlays can use the same plumbing: fitToViewport(el, host) writes --ui-vv-top / --ui-vv-bottom on el while the keyboard is up and scrolls the focused field back into view; visibleBounds() gives the visible band for positioning.

Entry points

Component modules have side effects (they call define()). Theme, motion and token modules do not.

In this repository

This package lives in ui/ of the Alacris repo 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/ in the same repo is a usage example and install guide, not this package.

ui/
  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

The live catalog is bmartel.github.io/alacris/ui — every component plus a theme playground, no clone required.

From a clone of the repo:

npm install
npm run demo        # kitchen sink: http://localhost:5173/ui/
                    # starter app:  http://localhost:5173/starter/
cd ui && npm test
cd ui && npm run test:chrome   # overlay geometry in headless Chrome at phone/tablet sizes (skips without Chrome)

License

MIT