@arclux/arc-ui

Lit web components implementing the Arclight design system. This is the canonical source — every framework wrapper package is generated from these components by Prism.

Installation

npm install @arclux/arc-ui lit

Usage

Register every component (simplest — one import defines all <arc-*> elements):

import '@arclux/arc-ui/register';

Or register only what you use for smaller bundles — each component subpath defines just that element and its required children:

import '@arclux/arc-ui/button';
import '@arclux/arc-ui/card';
import '@arclux/arc-ui/command-palette'; // also registers arc-command-item / arc-command-group

Then use the elements anywhere HTML works:

<arc-button variant="primary">Get Started</arc-button>

<arc-card>
  <h3>Card Title</h3>
  <p>Card content.</p>
</arc-card>

<arc-input label="Email" type="email" placeholder="[email protected]"></arc-input>

The bare entry point (import { ArcButton } from '@arclux/arc-ui') exports the component classes without registering any custom elements — use it when you want to control registration yourself (custom tag names, scoped registries).

Events

Components emit arc-* CustomEvents (arc-input, arc-change, arc-select, arc-close, …) that bubble and cross shadow boundaries. Payloads are on event.detail:

document.querySelector('arc-input').addEventListener('arc-input', (e) => {
  console.log(e.detail.value);
});

Theming

Components read design tokens from CSS custom properties. Compound tokens (gradients, glows, focus rings) reference a small set of base tokens, so overriding just the accents re-themes everything:

:root {
  --accent-primary: rgb(77, 126, 247);
  --accent-primary-rgb: 77, 126, 247;
  --accent-secondary: rgb(34, 211, 238);
  --accent-secondary-rgb: 34, 211, 238;
}

Dark theme is the default; set data-theme="light" (or "auto") on the root element to switch. Per-component fine-tuning is available via ::part() selectors on most components.

Icons

Icons ship separately, in @arclux/arc-ui-icons — Phosphor (1,500+) and Lucide (1,900+). Core carries no icon data and selects no library, so register one:

npm i @arclux/arc-ui-icons

import '@arclux/arc-ui-icons/phosphor'; // one line; selects it too

import { iconRegistry } from '@arclux/arc-ui';
iconRegistry.use('lucide');                   // switch, once both are registered
iconRegistry.set({ myLogo: '<svg>…</svg>' }); // or register your own icons

<arc-icon> then lazy-loads one module per glyph (~500 bytes), so only the icons a page renders are ever fetched. For an app that uses a dozen, skip the pack and import them directly — import check from '@arclux/arc-ui-icons/phosphor/check' — then hand them to set().

<arc-icon name="magnifying-glass" size="md"></arc-icon>
<arc-icon name="book-open" size="20"></arc-icon> <!-- named sizes or numeric px -->

TypeScript & tooling

The package ships type declarations for every component plus a custom-elements.json manifest, so editors with web-component tooling get tag, attribute, and event completion.

Prop types are unions where the component accepts a fixed set of values (variant: 'primary' | 'secondary' | 'ghost'), and arc-* event names are registered in GlobalEventHandlersEventMap with typed detail payloads, so addEventListener('arc-change', …) autocompletes and type-checks.

Editor support

VS Code — add the bundled custom data to .vscode/settings.json for tag, attribute, and attribute-value completion (with hover docs) in plain HTML:

{
  "html.customData": ["./node_modules/@arclux/arc-ui/vscode.html-custom-data.json"],
  "css.customData": ["./node_modules/@arclux/arc-ui/vscode.css-custom-data.json"]
}

JetBrains IDEs (WebStorm, IntelliJ) — no setup needed; the bundled web-types.json is picked up automatically.

React 19 without the wrapper

React 19 renders custom elements natively. If you use the tags directly instead of @arclux/arc-ui-react, opt into typed JSX for all arc-* tags:

{ "compilerOptions": { "types": ["@arclux/arc-ui/react-jsx"] } }

<arc-button variant="primry"> then fails to compile with Did you mean '"primary"'?.

Development warnings

For runtime feedback while building, import the dev module (development only — it installs a document-wide observer):

if (import.meta.env.DEV) import('@arclux/arc-ui/dev');

It warns in the console — with a link to the right docs page — about invalid attribute values (variant="primry"), camelCase property names used as attributes (confirmLabel= instead of confirm-label=), and attribute-name typos (vairant).

Framework Wrappers

If you are using a framework, prefer the dedicated wrapper package:

| Framework | Package | |-----------|---------| | React | @arclux/arc-ui-react | | Vue 3 | @arclux/arc-ui-vue | | Svelte 5 | @arclux/arc-ui-svelte | | Angular | @arclux/arc-ui-angular | | Solid | @arclux/arc-ui-solid | | Preact | @arclux/arc-ui-preact | | Plain HTML/CSS | @arclux/arc-ui-html |

Links

• Documentation & interactive examples
• Repository
• License (MIT)