custom-elements-collection

v0.6.0

Published

2 days ago

A collection of 126 framework-agnostic Web Components (ce-* UI building blocks + lesson-* educational widgets) built on Lit, including chat-surface, RAG/agent, feedback-UI, decision-analysis, and form primitives for LLM applications. Each component is sel

Downloads

1,427

0High
0Medium
0Low

abramov

web-components custom-elements lit lit-element ui-components design-system dashboard lesson education html framework-agnostic

custom-elements-collection

🌐 Live demo: generativeui.ru/solutions/custom-elements-collection — Storybook-style catalog over every tag, with a live theme switcher across 10 themes.

A collection of 126 framework-agnostic Web Components built on Lit 3 — 110 general-purpose UI building blocks (ce-*) covering layout primitives, navigation, metrics, comparison & decision analysis, chat / agent surfaces, human-in-the-loop feedback, form controls, dashboards, and rich-content viewers, plus 16 educational widgets (lesson-*). Drop them into any HTML page, any framework, any static site generator. No build step required on the consumer side.

Every component is self-describing via a per-component *.meta.json file (see ADR-005) — props, events, slots, CSS variables, dependency graph, side effects, and accessibility notes are machine-readable.

30-second tour

<!doctype html>
<html data-ce-theme="dark">
<head>
  <link rel="stylesheet"
        href="https://unpkg.com/custom-elements-collection/dist/tokens/tokens.css">
  <script type="module"
          src="https://unpkg.com/custom-elements-collection/dist/auto.js"></script>
</head>
<body>
  <ce-shell>
    <ce-hero kicker="Status" title="Release readiness">
      <ce-kpi slot="stats" value="96%" label="Pass" color="green"></ce-kpi>
      <ce-kpi slot="stats" value="0"   label="Bugs" color="red"></ce-kpi>
    </ce-hero>
    <ce-callout type="success" title="Ready to ship">
      All quality gates green.
    </ce-callout>
  </ce-shell>
</body>
</html>

Install

pnpm add custom-elements-collection

Lit is bundled — no peer dependencies required.

Three ways to register tags

// A) Register every tag at once
import "custom-elements-collection/auto";

// B) Tree-shake to specific tags
import "custom-elements-collection/hero";
import "custom-elements-collection/kpi";
import "custom-elements-collection/lesson-quiz";

// C) Load dynamically at runtime
import { loadOnDemand } from "custom-elements-collection";
await loadOnDemand(["ce-hero", "ce-kpi", "lesson-rule"]);

Theming

All colors, spacing, and radii come from CSS custom properties named --ce-*. Ship the defaults and override anywhere:

<link rel="stylesheet"
      href="https://unpkg.com/custom-elements-collection/dist/tokens/tokens.css" />

:root {
  --ce-color-primary: oklch(72% 0.17 250);
  --ce-radius: 12px;
  --ce-font-sans: "Inter", system-ui, sans-serif;
}

Dark / light overrides are shipped as separate stylesheets:

<link rel="stylesheet"
      href="https://unpkg.com/custom-elements-collection/dist/tokens/dark.css" />
<link rel="stylesheet"
      href="https://unpkg.com/custom-elements-collection/dist/tokens/light.css" />

Component catalog

Full catalog with per-tag goals, recipes, and links lives in skill/SKILL.md (auto-generated from each *.meta.json). Quick map of what's in the box:

Layout & primitives (29)

ce-abbr · ce-accordion · ce-avatar · ce-avatar-group · ce-badge · ce-breadcrumbs · ce-callout · ce-card · ce-chip · ce-countdown · ce-details · ce-divider · ce-duration · ce-grid · ce-hero · ce-icon · ce-kbd · ce-link · ce-mark · ce-pagination · ce-progress-list · ce-relative-time · ce-section · ce-shell · ce-skeleton · ce-table · ce-tabs · ce-tag · ce-toc

Metrics & charts (11)

ce-bar-chart · ce-bar-row · ce-chart · ce-donut · ce-heat-cell · ce-heatmap · ce-heat-row · ce-kpi · ce-plot · ce-progress · ce-score

Comparison & narrative (19)

ce-code · ce-compare · ce-decision-tree · ce-example · ce-feature-card · ce-filter-bar · ce-flow · ce-flow-step · ce-matrix · ce-persona · ce-pricing-tier · ce-pros-cons · ce-quote · ce-rank-list · ce-recommendation · ce-step · ce-steps · ce-timeline · ce-verdict

Decision-analysis primitives — ce-pros-cons (two-column pros vs cons), ce-matrix (2×2 quadrant chart for Eisenhower / impact-effort), and ce-rank-list (positional leaderboard with optional deltas) — ship alongside the older narrative primitives.

Chat surfaces (18)

ce-attachment-strip · ce-chat-bubble · ce-chat-input · ce-citation · ce-conversation-tree · ce-copy-button · ce-cursor · ce-message-group · ce-rating · ce-reasoning · ce-retry-button · ce-source-card · ce-stop-button · ce-stream-status · ce-suggestion-chip · ce-thinking · ce-tool-call · ce-tool-result

LLM chat / copilot / agent UI primitives. ce-chat-input is a composite composer (auto-grow textarea + send/stop/attach buttons + Enter-to-submit) with ce-attachment-strip for previewable upload tiles above it. ce-message-group clusters consecutive same-role messages; ce-conversation-tree is the ◀ 2 / 5 ▶ branch picker for forked / regenerated responses; ce-stream-status is the connecting / streaming / done / error pill with optional tokens-per-second. ce-reasoning is a collapsible chain-of-thought trace; ce-thinking is the pre-token spinner. ce-suggestion-chip is the tappable follow-up prompt and ce-stop-button is the mid-stream cancel counterpart to ce-retry-button. ce-rating supports both thumbs-up/down and 0–N star modes and is form-associated. ce-tool-call collapses an LLM tool invocation with args / result / error slots; ce-tool-result is the panel companion for the return value. ce-source-card renders a retrieved-source card for RAG surfaces and pairs with inline ce-citation footnote markers. Compatible with @generative-dom/plugin-companion.

Feedback (8)

ce-bookmark · ce-comment · ce-dismiss · ce-feedback-bar · ce-feedback-export · ce-feedback-heatmap · ce-feedback-sink · ce-feedback-summary

Human-in-the-loop feedback for any HTML dashboard. Wrap content in <ce-feedback-sink subject="…">, drop one <ce-feedback-bar item="…"> per item with toggles + ratings + comments inside, and the sink streams to localStorage / HTTP / file / console / custom transport. ce-feedback-heatmap renders a verdict-distribution sparkbar from the same state. Live demo at demo/feedback.html.

Forms (12)

ce-button · ce-check-item · ce-checkbox · ce-checklist · ce-confirm · ce-date-picker · ce-file-upload · ce-input · ce-radio-group · ce-select · ce-textarea · ce-toggle

Themable form controls with full ARIA semantics: ce-button (primary/secondary/ghost/destructive + loading), ce-toggle (role=switch), ce-checkbox / ce-radio-group (with aria-checked semantics), ce-input / ce-textarea / ce-select / ce-date-picker (label + help/error + aria-describedby), ce-file-upload (drag-drop dropzone emitting ce-files), and ce-confirm (inline role=alertdialog yes/no).

Dashboard (6)

ce-clock · ce-counter · ce-gauge · ce-sparkline · ce-stat-group · ce-status-light

Compact dashboard cells: live ce-clock (Intl / IANA), animated ce-counter (rAF easing), semicircle ce-gauge (role=meter), inline ce-sparkline (line / area / bar), traffic-light ce-status-light, and the ce-stat-group KPI-grid wrapper.

Content (7)

ce-diff · ce-file-card · ce-image · ce-json · ce-key-value · ce-kv · ce-qr

Rich content for chat surfaces and reports: lazy ce-image with caption + fallback, ce-file-card attachment chip with type icons, ce-key-value / ce-kv definition-list grid with typed-value children (CDR-002), ce-json pretty-print viewer, LCS-based ce-diff (unified / split), and ce-qr byte-mode QR encoder with no runtime dependencies.

Education — `lesson-*` (16)

lesson-audio · lesson-compare · lesson-confidence · lesson-frame · lesson-gap · lesson-hint · lesson-match · lesson-myth · lesson-note · lesson-quickfire · lesson-quiz · lesson-reveal · lesson-rule · lesson-step · lesson-summary · lesson-vocab

A machine-readable manifest of every component is exported as COMPONENTS. Internal layout primitives (ce-docs-layout, ce-nav-list, ce-theme-switcher) ship with the package but are filtered out of the published manifest at publish time (see ADR-005).

Design principles

Light DOM by default. Components render into the page's DOM, so markdown, Mermaid diagrams, and Chart.js canvases work inside slots. Shadow DOM is opt-in per component where style isolation matters. See ADR-002.
Theming via CSS custom properties. No per-component prop explosion. See ADR-003.
Zero config on the consumer side. One <script type="module"> from a CDN gets you all tags.
Self-describing. Each component ships with a validated *.meta.json describing every prop, event, slot, CSS variable, side effect, and dependency. See ADR-005.
Type-safe. Full .d.ts for every component and the manifest.

Demo

The interactive catalog is hosted at generativeui.ru/solutions/custom-elements-collection — no install, no build, every component browsable with live examples and a theme switcher.

To run it locally, pnpm demo boots the same UI on :4600 against your working tree. The sidebar offers four navigation axes — all backed by the URL hash so deep links work and refreshes are safe:

Search — substring match across tag / name / goal / description / tags. Keyboard / focuses, Esc clears.
Group by — Group (default) / Tier / Stability / Category / Created month / A-Z.
Sort — A-Z, Z-A, Recently updated, Recently created, Most dependents, Least dependents.
Filters — opens a <ce-modal> with seven axes (stability, tier, category, has-events / has-slots / has-cssVars / has-globalDeps / has-sideEffects, free-form tags, created-in-last, updated-in-last). Recency axes carry both quick radios (7 / 30 / 90 / 365 days) and a free-form "custom days" input.

Each sidebar row shows a relative-time stamp (<ce-relative-time> for ≤ 30 days; the absolute ISO date older). Dates are auto-maintained by a pre-commit hook — see ADR-011 + ADR-012.

Documentation

Usage guide — plain HTML, bundlers, Vue / React / Svelte, theming, composition patterns, troubleshooting.
Architecture — repo layout, component anatomy, build pipeline, theming model.
ADRs — framework choice, Light DOM, theming, distribution modes, component meta files.
Publishing — how this library ships to npm AND to generativeui.ru/solutions/.

Companion projects

This library is one of two OSS sub-projects mounted under generativeui.ru/solutions/:

generative-dom — streaming-markdown parser & renderer for LLM chat surfaces. Pair with @generative-dom/plugin-companion to render ce-* tags directly from a streaming LLM response. (npm · GitHub)
custom-elements-collection (this repo) — the catalog the model picks from.

Browser support

Any evergreen browser with native support for customElements, ES modules, and CSS.registerProperty (Chrome / Edge / Firefox / Safari 16.4+).

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

custom-elements-collection

30-second tour

Install

Three ways to register tags

Theming

Component catalog

Layout & primitives (29)

Metrics & charts (11)

Comparison & narrative (19)

Chat surfaces (18)

Feedback (8)

Forms (12)

Dashboard (6)

Content (7)

Education — lesson-* (16)

Design principles

Demo

Documentation

Companion projects

Browser support

License

Education — `lesson-*` (16)