@uxelle/a2ui

A2UI v0.9 adapters for rendering agent-driven UI with uxElle components, Bayer's Generative Product Foundation (GPF).

Install

npm install @uxelle/a2ui @uxelle/components @uxelle/themes

@uxelle/components and @uxelle/themes are peer dependencies — the catalog renders real uxElle components and needs their CSS to look right. @uxelle/icons is a dependency: importing this package registers the full Material Symbols Sharp catalog so agent-chosen iconName values resolve.

What this package exports

• uxelleCatalog - A runtime Catalog for MessageProcessor.
• uxelleCatalogId - Catalog ID agents should target in createSurface.
• uxelleCatalogSchema - Human-readable contract and safety constraints.
• uxelleRecipes / uxelleRecipeIndex / getUxelleRecipe - Composition recipes (page shell, form section, navigation side) for host prompt injection next to the catalog schema.
• createA2uiMessageProcessor - Convenience factory for MessageProcessor.
• A2uiRenderer - Optional React helper that renders all active surfaces.
• A2uiThemeScope - Wrapper that applies theme data-* attributes to a subtree.

Supported component names (80 adapters)

Layout & text: A2uiLayout, A2uiText

Actions: A2uiButton, A2uiIconButton, A2uiButtonGroup, A2uiSegmentedControl, A2uiLink

Forms: A2uiTextfield, A2uiTextarea, A2uiFileUpload, A2uiLabel, A2uiFieldMessage, A2uiCheckbox, A2uiCheckboxGroup, A2uiSwitch, A2uiRadio, A2uiRadioGroup, A2uiListControls, A2uiSelect, A2uiMultiSelect, A2uiDatePicker, A2uiDatePickerRange

Lists & navigation: A2uiList, A2uiListItem, A2uiBreadcrumbs, A2uiBreadcrumb, A2uiNavLink, A2uiMenu, A2uiNavigation, A2uiNavigationSide, A2uiNavigationSideItem, A2uiNavigationSideSubItem, A2uiNavigationSideGroup

Display & feedback: A2uiIcon, A2uiDivider, A2uiSpinner, A2uiSkeleton, A2uiLinearProgress, A2uiTooltip, A2uiNotificationBadge, A2uiLabelBadge, A2uiBubble, A2uiFilterChip, A2uiFilterChipGroup, A2uiChoiceChip, A2uiChoiceChipGroup, A2uiImage, A2uiLogo, A2uiCard, A2uiProductCard, A2uiStatTile, A2uiBanner, A2uiBannerAnnouncement, A2uiScrim

Brand expression: A2uiDynamicAngleLine, A2uiDynamicAngleLineCombo, A2uiDynamicAngleShape, A2uiDynamicAngleShapeSurface, A2uiDynamicAngleTexture, A2uiDynamicAngleTextureText

Disclosure & tabs: A2uiAccordion, A2uiAccordionGroup, A2uiStepper, A2uiStepperItem, A2uiTab, A2uiTabGroup, A2uiSheet, A2uiDialog

Table: A2uiTable, A2uiTableGrid, A2uiTableHead, A2uiTableBody, A2uiTableRow, A2uiTableHeaderCell, A2uiTableCell, A2uiTableColumnSizingProvider

Chrome: A2uiFooter, A2uiHero, A2uiLanguageSelector, A2uiLanguageSelectorButton

Safety model

• No arbitrary HTML injection.
• No arbitrary class/style strings.
• URL props are sanitized to allow only http, https, mailto, tel, or relative links.
• Components are allowlisted through uxelleCatalog.
• Slot props use ChildList or structured data arrays (options, columns, steps).

Usage

Host setup (renderer)

Import global styles before rendering surfaces. @uxelle/components/base.css loads both component stylesheets (global baseline and component rules). Built @uxelle/components JS does not import CSS—use base.css plus a theme in Next.js App Router and other SSR hosts. See the Next.js host guide.

import "@uxelle/components/base.css";
import "@uxelle/themes/open-source.css";
import {
  A2uiRenderer,
  A2uiThemeScope,
  createA2uiMessageProcessor,
  uxelleCatalogId,
} from "@uxelle/a2ui";

const processor = createA2uiMessageProcessor((action) => {
  console.log("A2UI action", action);
});

processor.processMessages([
  {
    version: "v0.9",
    createSurface: { surfaceId: "main", catalogId: uxelleCatalogId },
  },
]);

Also apply uxElle theme CSS so token-driven colors and spacing resolve. Install @uxelle/themes and import @uxelle/themes/open-source.css (already shown above). When the whole app layout is already themed, surfaces inherit those variables automatically. For an isolated agent panel, wrap the renderer in A2uiThemeScope:

import { UXelleThemeProvider } from "@uxelle/themes/react";

// App layout: theme on <html> via provider
<UXelleThemeProvider theme="open-source" darkMode={false} colorSwitcher="default">
  {children}
</UXelleThemeProvider>

// Or scoped panel without touching document root:
<A2uiThemeScope theme="open-source" mode="light" colorSwitcher="default">
  <A2uiRenderer processor={processor} messages={messages} />
</A2uiThemeScope>

The theme prop is the kebab-case theme id (matching the CSS file name). Host apps choose the brand theme; agents do not. Discover available themes via @uxelle/themes/manifest.json or metadata.json.

Agent integration

Agents that generate A2UI JSON should target the uxElle catalog, not the basic A2UI default catalog.

Catalog ID — Use uxelleCatalogId (https://uxelle.dev/a2ui/catalogs/uxelle-v1.json) in every createSurface message. This string is a contract identifier shared between agent and renderer; the agent does not fetch it as a URL. The host registers uxelleCatalog with MessageProcessor and may expose uxelleCatalogSchema at an API route for documentation.

Prompt contract — Derive agent ui_description from uxelleCatalogSchema (exported by this package). Do not inject the basic A2UI catalog schema into the system prompt (include_schema: false). Including the default catalog causes models to emit generic component names (ChoicePicker, Card, …) instead of uxElle adapters (A2uiButton, A2uiTextfield, …).

Recipes — uxelleRecipes is a companion export, not part of the component catalog. Hosts inject the index (uxelleRecipeIndex) and/or full messages JSON next to the schema. Do not dump every recipe into every prompt.

import {
  uxelleCatalogId,
  uxelleCatalogSchema,
  uxelleRecipeIndex,
  uxelleRecipes,
} from "@uxelle/a2ui";

// Agent: set catalogId in createSurface
const catalogId = uxelleCatalogId;

// Host: serve schema + optional recipe index for agent docs / validation
export const catalog = uxelleCatalogSchema;
export const recipes = uxelleRecipeIndex;
// Full A2UI messages when the host wants a worked example:
// uxelleRecipes.find((recipe) => recipe.id === "form-section")?.messages

Layout spacing — A2uiLayout gap / padding / margin use theme layout-spacing variables: 0 or var(--uxl-theme-layout-spacing-*) (micro 0–3, small 4–6, medium 7–12, large 13–16). Do not emit raw pixel spacing.

Form binding — Bind field values with { path: "/form/fieldName" } on props like value or checked. Initialize the data model with updateDataModel and let the renderer handle two-way updates. Prefer dedicated form adapters (A2uiCheckbox, A2uiSelect, …) over simulating inputs with A2uiListItem actions.

Transport

This package covers the catalog, renderer, and message processor. For streaming agent responses over SSE and posting client actions back to an agent endpoint, use the companion package @uxelle/a2ui-transport. It exports useA2uiChat, useA2uiSseStream, createA2uiActionSender, and SSE parsing helpers that wire a processor from this package to your agent API.

License

GPL-3.0-only

Source

• Repository: Bayer-Group/bayer-uxelle
• Issues: github.com/Bayer-Group/bayer-uxelle/issues
• Contributing: DEVELOPER.md