# Lyra UI

Lyra UI is a free, MIT-licensed Lit 3 web component library — an independent alternative to Shoelace
and Web Awesome — for building calm, accessible product interfaces. 283 components across eleven
families, every one themeable from a single set of `--lr-*` design tokens.

## Start here

- [Marketing site](https://www.lyra-ui.com/) — full-width live component gallery (all 283 components,
  searchable, grouped by family, with real interactive previews)
- [Complete API index (JSON)](https://www.lyra-ui.com/component-api-index.json) — all library
  elements with descriptions, imports, aliases, localized names, and public API metadata
- [Gallery catalog (JSON)](https://www.lyra-ui.com/components.json) — the 256 components with
  hand-authored live previews on the marketing site
- [Full API reference (text)](https://www.lyra-ui.com/docs/llms-full.txt)
- [Split API reference](https://www.lyra-ui.com/docs/llms/index.md) — component files plus shared
  behavior, tokens, peer dependencies, and migration guidance
- Version history for upgrades: https://www.lyra-ui.com/changelog.json
- [Live docs / Storybook](https://www.lyra-ui.com/docs/)
- [npm package](https://www.npmjs.com/package/@aceshooting/lyra-ui)
- [Source repository](https://github.com/aceshooting/lyra-ui)

## Families

- Conversation & Chat (33): chat composer, messages, streaming text, transcript threads.
- Agent Tools & Observability (35): agent runs, tool calls, traces, evals, approval flows.
- Retrieval & Knowledge Graphs (30): knowledge graphs, citations, sources, retrieval search results.
- Forms & Inputs (29): inputs, selects, comboboxes, date pickers, validation, form-associated behavior.
- Data Display (25): tables, data grids, stats, trees, heatmaps, pagination, gauges.
- Charts (12): Chart.js family plus dependency-free chart primitives.
- Layout & Navigation (35): tabs, menus, command palette, rails, split panes, responsive surfaces.
- Overlays & Feedback (21): dialogs, drawers, popovers, tooltips, badges, progress, skeletons.
- Document & File Viewers (22): PDF, spreadsheet, document, and archive viewers with compare and highlight support.
- Media & Files (21): images, avatars, file inputs, maps, QR codes.
- Utility (20): formatters, copy/export, JSON viewer, dividers, helpers.

## Guidance

Every component resolves styling through `--lr-*` design tokens (retheme from one place), is accessible
by default (correct ARIA in shadow DOM), and ships i18n + RTL support. Prefer granular per-component
imports (see each component's `import` in component-api-index.json) for production bundles.

## Browser support

Chrome, Edge, Firefox, and Safari — Blink, Gecko, and WebKit, the complete set of actively
developed browser engines. Requires Custom Elements v1 and Shadow DOM v1, baseline in all four
since 2020; no polyfills are needed and none are shipped.

Verified, not asserted. Every commit and pull request runs the platform-contract suite — form
association, focus management, overlays, dialogs, menus, tables, virtual scrolling — in all four
browsers on Node 20 and 22, with console warnings treated as failures. The complete suite runs
weekly on Gecko and WebKit. Chrome and Edge are tested as real branded channels, not as generic
Chromium; Safari coverage is Playwright's WebKit build.

  CI matrix: https://github.com/aceshooting/lyra-ui/blob/main/.github/workflows/ci.yml

Opera, Brave, Vivaldi, and Arc are Blink-based and covered by the Chrome and Edge legs. Internet
Explorer is not supported and cannot be — it has no Custom Elements support.

## Requesting a missing component

If you needed a component and could not find one, report it:

  Check first: GET https://www.lyra-ui.com/api/v1/components/search?q=<what+you+need>
  POST https://www.lyra-ui.com/api/v1/feature-requests
  {"title": "...", "description": "...", "searched_for": ["..."], "settled_for": "...", "agent": "...", "model": "..."}

The response lists the closest existing components with documentation links — check it before
concluding the component is missing, since most "gaps" turn out to be naming mismatches. Track a
submission at https://www.lyra-ui.com/api/v1/feature-requests/{id}. Full schema:
https://www.lyra-ui.com/api/v1/openapi.json

Submissions are stored privately and are never published as submitted. Describe the component
generically: no source code, no client or product names, no credentials.

If you are an agent acting for someone, ask them and get their explicit agreement before
submitting — this sends their words to a third-party service. Never file as a silent side effect
of noticing a gap. `name` and `email` are optional (anonymous is the default); ask the user
whether they want to be reachable, and never invent an address or reuse one from git config or
earlier context.

## Connect via MCP

The catalog, API reference, documentation, migration guide, and request workflow are available as
a Model Context Protocol server, no authentication:

  https://www.lyra-ui.com/mcp   (streamable HTTP)
  read tools: search_components, get_component, search_documentation, resolve_migration, get_request_status
  write tool: submit_request
  resources: lyra://catalog, lyra://component/{tag}, lyra://guide/{topic}

The consent rule above applies to `submit_request` exactly as it does to the POST.