@sig-ui/components

Framework-agnostic SigUI Web Components (light DOM).

What this package is for

Use @sig-ui/components for:

• accessible, token-driven UI components
• consistent design-language behavior through --sg-* tokens
• optional machine-backed interactive components
• optional HTMX rehydration support

How it fits in SigUI

core -> theme -> (dom + components)

• Depends on @sig-ui/core and @sig-ui/theme; @sig-ui/dom is a peer layer.
• Consumes CSS/token outputs generated from SigUI config.
• Can be replaced by project-owned components installed via sigui add.

Install

bun add @sig-ui/components

Quick examples

import { defineSiguiComponents } from "@sig-ui/components";
import "@sig-ui/components/styles/sigui.css";

defineSiguiComponents(); // registers interactive/composite sg-* tags

<sg-card>
  <h2>Hello</h2>
  <button class="sg-button" data-color="primary" type="button">Save</button>
</sg-card>

React quick start

import { useEffect } from "react";
import { defineSiguiComponents, toast } from "@sig-ui/components";
import "@sig-ui/components/styles/sigui.css";

let registered = false;

export function App() {
  useEffect(() => {
    if (!registered) {
      defineSiguiComponents();
      registered = true;
    }
  }, []);

  return (
    <>
      <sg-toast-provider position="bottom-right" />
      <button
        className="sg-button"
        data-color="primary"
        type="button"
        onClick={() => toast.success("Saved")}
      >
        Save
      </button>
    </>
  );
}

Vue quick start

Configure Vue to treat sg-* tags as custom elements:

// vite.config.js
import vue from "@vitejs/plugin-vue";

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith("sg-"),
        },
      },
    }),
  ],
};

<script setup>
import { onMounted } from "vue";
import { defineSiguiComponents, toast } from "@sig-ui/components";
import "@sig-ui/components/styles/sigui.css";

onMounted(() => defineSiguiComponents());
</script>

<template>
  <sg-toast-provider position="bottom-right" />
  <button class="sg-button" data-color="primary" type="button" @click="toast.success('Saved')">
    Save
  </button>
</template>

Optional HTMX integration

import { installSiguiHtmx } from "@sig-ui/components/lib/htmx";
import "@sig-ui/components/styles/htmx.css";

installSiguiHtmx();

A2UI agent UI rendering

import { defineSiguiComponents } from "@sig-ui/components";
import { SIGUI_A2UI_CATALOG_ID, createA2uiRenderer } from "@sig-ui/components/a2ui";
import "@sig-ui/components/styles/sigui.css";

defineSiguiComponents();

const renderer = createA2uiRenderer({
  root: document.querySelector("#agent-ui"),
  onAction(message) {
    // Forward to your agent transport.
  },
});

renderer.handleMessage({
  version: "v1.0",
  createSurface: {
    surfaceId: "example",
    catalogId: SIGUI_A2UI_CATALOG_ID,
    components: [
      { id: "root", component: "Card", padding: true, child: "text" },
      { id: "text", component: "Text", text: "Rendered from A2UI" },
    ],
  },
});

Main API

• defineSiguiComponents(options?)
• registry
• @sig-ui/components/a2ui: siguiA2uiCatalog, siguiA2uiCapabilities, validateA2uiMessage, createA2uiRenderer
• SiguiElement, rehydrateSubtree
• utilities: useMachine, useId, useReducedMotion, enableKeyboardNavigation
• feature flags: configureSiguiFeatures, getSiguiFeatureFlags, isSiguiFeatureEnabled

LLM instructions

When generating code with @sig-ui/components:

• Import @sig-ui/components/styles/sigui.css once at the app entry and call defineSiguiComponents() once during client startup.
• Use sg-* custom elements and .sg-* CSS classes as light-DOM components. Do not assume shadow DOM parts or closed component internals.
• Use framework conventions correctly: className in React, Vue isCustomElement for sg-*, and client-only registration in SSR frameworks.
• Do not register package components and sigui add project-owned copies for the same tag in one app. Pick package mode or project-owned mode per component.
• For generated A2UI, use @sig-ui/components/a2ui, validate messages before rendering, and keep actions routed through the host app.

Full docs

• docs/ARCHITECTURE_OVERVIEW.md
• docs/COMPONENTS.md
• docs/DOM.md (peer runtime)
• docs/THEME.md (token source)