UI kit

The component kit of Vela™: buttons, tabs, toggle groups, badges, dialogs, drawers, menus, tooltips, popovers and form controls. One file per component, Zag state machines for behavior, CSS in cascade layers over design tokens, and one typed theme config. It installs with @luxalgo/vela and works without the chart too: npm install @luxalgo/vela-ui.

import { createButton } from '@luxalgo/vela-ui/button';
import { createTheme, ensureUIHost } from '@luxalgo/vela-ui/theme';

const app = document.getElementById('app')!;
ensureUIHost(app, createTheme({ accent: '#7c3aed' }));

const save = createButton({ text: 'Save', variant: 'default' });
app.append(save.el);

ensureUIHost makes the element a kit host: it carries the theme and the kit's base styles, and menus, dialogs and tooltips opened from inside it mount there, themed. applyTheme(app, theme) switches a host to another theme later.

• One import path per component (@luxalgo/vela-ui/<name>), so a bundle holds only the components it imports. Every component is create<Name>(props), returning a handle with el and destroy(). When you discard a whole subtree, disposeWithin(root) (@luxalgo/vela-ui/dispose) releases every control in it, handles kept or not: controls that run a state machine must be released, not only removed, or their page-wide listeners stay behind. A destroyed dialog, drawer or popover releases its content itself.
• Styles give way to yours. Component CSS sits in the vela.ui cascade layer, so a page's own CSS overrides it without !important. Every part carries a data-slot; variants and sizes are data-variant and data-size.
• One theme config. createTheme sets the brand color, radius and font, any token by name, each component's settings, or a component's whole look; a wrong name fails the typecheck. See Theming and What to change, and where.

Command line

A vela-ui.json at the project's root says where copies go and which theme file to check: { "aliases": { "ui": "#ui" }, "theme": "brand.theme.json" } (#ui is a package.json imports alias, or write a folder). Copies are recorded in vela-ui.lock.json, with their upstream version kept under .vela-ui/: commit both. The first add offers to add a note to the project's AGENTS.md pointing coding agents at this package's reference.

For coding agents

See Coding agents for every skill and how to install them. Three agent skills ship in skills/: using the components, theming and writing components. npx skills experimental_sync links them into a project's agent once the package is installed (Vela's own package pulls them in too), and npx skills add LuxAlgo/Vela installs them from the repository. llms.txt indexes them with the rest of the reference.

Reference

• dist/manifest.json (@luxalgo/vela-ui/manifest.json): every component's import, props, variants, parts and slots, settings, the tokens it reads and an example, generated from the source.
• dist/theme.schema.json (@luxalgo/vela-ui/theme.schema.json): the JSON Schema of a theme written to a file.
• llms.txt: a short index of the above, for coding agents.
• Writing a component: the one-file shape and its rules.
• @luxalgo/vela-ui/stylelint: the shared stylelint config for CSS written with the css tag (tokens through t, no raw colors, logical directions, parts not classes). Extend it and name your layer: vela.ui for components of your own, so themes restyle them like the kit's, and vela.custom for CSS that restyles components ({ extends: ['@luxalgo/vela-ui/stylelint'], rules: { 'vela/layer': 'vela.ui' } }). It needs stylelint, postcss-lit and stylelint-config-recommended. CSS outside the kit takes the tag and the tokens from @luxalgo/vela-ui/css and @luxalgo/vela-ui/t.
• @luxalgo/vela-ui/stylelint/lint: lintCss({ files, baseline?, update? }) runs that config and fails when postcss-lit skips a template (it would pass while checking nothing). With a baseline file, CSS written before the rules keeps its known violations, counted per file and rule: the run fails when a count grows, and when one shrinks until update: true rewrites the file, so the baseline only tightens.

ES modules only. Licensed under Apache-2.0.