@xenapseai/ui-kit

A React component library and YAML-driven UI engine for the Xenapse ecosystem. Provides primitives, layout components, schema-driven forms, and a component-tree renderer — all styled with a dark industrial theme.

Purpose

ui-kit is the shared front-end layer for Xenapse services. It ships:

• Primitive components — Button, Badge, Toggle, Slider, SparkLine, LogEntry, Text, Table, StatCard, FormField
• Layout components — Panel, TabBar, Header, Page, Card, Grid, Modal
• Schema-driven forms — render forms from YAML schema files at runtime (no code required)
• Component tree renderer — render full UI trees from a YAML/JSON DSL
• Theming — dark industrial theme with runtime token overrides via ThemeProvider

Architecture

ui-kit is a ui_engine library consumed by other Xenapse services. It exposes no server API. Downstream services import components directly and, optionally, pass YAML schemas to the engine layer to render forms or component trees at runtime.

xenapse service
  └── imports @xenapseai/ui-kit
        ├── React components  (Panel, TabBar, Badge, …)
        ├── SchemaRenderer    (YAML → form)
        └── ComponentTreeRenderer (YAML → component tree)

The package ships two entry points:

| Entry | Purpose | |-------|---------| | @xenapseai/ui-kit | All components, engine, and theme | | @xenapseai/ui-kit/tailwind-preset | Tailwind CSS preset for consumers |

Installation

npm install @xenapseai/ui-kit

Peer dependencies required:

"react": "^18.0.0 || ^19.0.0",
"react-dom": "^18.0.0 || ^19.0.0"

Usage

Components

import { Panel, Badge, TabBar, Button } from '@xenapseai/ui-kit';

<Panel title="Status" accent="green">
  <Badge label="ONLINE" color="green" />
  <Button variant="primary" onClick={…}>Save</Button>
</Panel>

Schema-driven forms

Render a form entirely from a YAML schema file — no React form code needed:

import { SchemaRenderer } from '@xenapseai/ui-kit';
import schemaYaml from './config.yaml?raw';

function ConfigForm() {
  const [data, setData] = React.useState({});
  return <SchemaRenderer yaml={schemaYaml} formData={data} onChange={setData} />;
}

See docs/schema-format.md for the full YAML schema reference including supported widgets (range, textarea, checkboxes, datalist, hidden, …).

Theming

Wrap your app with ThemeProvider to override design tokens:

import { ThemeProvider } from '@xenapseai/ui-kit';

<ThemeProvider tokens={{ colors: { accent: { cyan: '#f59e0b' } } }}>
  <App />
</ThemeProvider>

Use the useTheme hook to read resolved tokens inside components. See docs/theme-customization.md for all default token values and the Tailwind preset setup.

Tailwind preset

// tailwind.config.js
import uiKitPreset from '@xenapseai/ui-kit/tailwind-preset';

export default {
  presets: [uiKitPreset],
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@xenapseai/ui-kit/dist/**/*.js',
  ],
};

Development

make dev      # start Vite dev server
make test     # run unit tests (vitest)
make lint     # TypeScript type-check
make build    # compile to dist/

Screenshot / component tests:

npm run test:screenshots          # run Playwright component tests
npm run test:screenshots:update   # update snapshots

Publishing

This package is published manually through GitHub Actions.

Required secret: NPM_TOKEN — an npm automation token that can publish @xenapseai/ui-kit.

Manual workflow: Actions → Publish npm package → Run workflow

Recommended first run:

• dry_run: true
• tag: latest

Real publish:

• dry_run: false
• tag: latest

The workflow runs lint, tests, build, npm pack --dry-run (to inspect package contents in logs), and then publishes.

If npm rejects the publish because the version already exists, bump version in package.json first.

Integration

• Uses sandbox: false
• Uses gitops: false