#UI Components

The /ui entry point exposes portable React components that match The AI Platform without importing the desktop application's private packages. Use the public components for common controls, layout, forms, feedback, and overlays; keep application-specific composition and product logic in your miniapp.

React 19 and React DOM 19 are peer dependencies. Install them with the SDK when starting a React miniapp:

pnpm add @theaiplatform/miniapp-sdk react react-dom

#Use the Precompiled Stylesheet

The precompiled stylesheet is the simplest integration and does not require Tailwind in the consuming app. Import it once at the browser entry point:

import '@theaiplatform/miniapp-sdk/ui/styles.css';

import {
  Button,
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
  Field,
  FieldLabel,
  Input,
} from '@theaiplatform/miniapp-sdk/ui';

export function CreateProjectCard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Create project</CardTitle>
        <CardDescription>Start with a name you can recognize.</CardDescription>
      </CardHeader>
      <CardContent>
        <Field>
          <FieldLabel htmlFor="project-name">Name</FieldLabel>
          <Input id="project-name" name="name" />
        </Field>
      </CardContent>
      <CardFooter>
        <Button type="submit">Create</Button>
      </CardFooter>
    </Card>
  );
}

The stylesheet includes the platform tokens, light and dark themes, browser defaults, component utilities, and reduced-motion behavior used by this SDK version.

#Use Tailwind v4

If the miniapp already compiles Tailwind v4, import the source integration. It adds the platform token mapping and tells Tailwind to scan the SDK UI bundle. Keep an app-owned @source for your own components.

@import 'tailwindcss' source(none);
@import 'tw-animate-css';
@import '@theaiplatform/miniapp-sdk/ui/tailwind.css';

@source './src';

Use either styles.css or tailwind.css, not both. The first is ready-to-serve CSS; the second must pass through the consumer's Tailwind v4 build.

#Component Families

The initial public set includes:

• Foundations: Avatar, Badge, Button, headings, Icon, Progress, Separator, Skeleton, and StatusIndicator.
• Layout and data display: Alert, Card, Empty, Item, resizable panels, ScrollArea, Table, and Tabs.
• Forms: Checkbox, Field, Input, InputGroup, Label, native and custom selects, radio controls, Slider, Textarea, and toggles.
• Overlays: alert dialogs, dialogs, sheets, and tooltips.
• Miniapp compositions: CodeBlock, MiniAppIconButton, MiniAppMetric, MiniAppPageHeader, MiniAppSectionHeader, MiniAppStatusBar, and MiniAppToolbar.

Subcomponents such as CardHeader, DialogTitle, SelectItem, and TableRow are exported from the same entry point. TypeScript and editor completion provide the exact props for the installed SDK version.

#Theme and UI Scale

Install appearance synchronization at surface startup and call its cleanup function during unmount:

import { installMiniAppAppearanceSync } from '@theaiplatform/miniapp-sdk/web';

const stopAppearanceSync = installMiniAppAppearanceSync();

export function unmount() {
  stopAppearanceSync();
}

The helper applies the initial light or dark theme and a bounded root font size, then accepts live cosmetic updates only from the exact parent and host origin. It does not grant host authority or access to platform data.

#Accessibility and Composition

Compose the semantic parts supplied by each component family. Give every form control a visible FieldLabel or accessible name. Include DialogTitle and DialogDescription in dialogs, even when visually hidden by your own layout. Use asChild on triggers when a Button should remain the one interactive element. Preserve keyboard focus styles and do not place interactive controls inside another button.

Overlay components are browser-safe outside the desktop host. The platform can install its own native-view occlusion adapter without exposing that host detail to a miniapp.

#Rust/WASM Bridge

Use @theaiplatform/miniapp-sdk/ui/wasm when a Rust/WASM miniapp needs the public UI library without passing React values across the wasm-bindgen ABI. The entry owns one React root and its providers. Callers provide a flat, serializable, revisioned model whose nodes use stable IDs and controlled values for inputs, selections, tabs, dialogs, validation, disabled/busy state, progress, loading, empty, success, conflict, and failure surfaces.

import '@theaiplatform/miniapp-sdk/ui/styles.css';
import { createMiniAppUiRoot } from '@theaiplatform/miniapp-sdk/ui/wasm';

const root = createMiniAppUiRoot(container, initialModel, async (action) => {
  await wasm.onUiAction(action);
});

root.update(nextModel);
root.focus('name');
root.announce('Saved');
root.unmount();

Every dispatched action includes a unique eventId, the rendered model revision, stable controlId, optional entityId, action name, event kind, and serializable value. Rust reducers should reject revisions older than their current state and event IDs they have already consumed. The bridge itself rejects malformed graphs, missing/duplicate/cyclic nodes, changed state that reuses a revision, events retained from an older render, and lifecycle calls after teardown.

Theme, dark mode, UI scale, reduced motion, focus styling, dialog focus return, and live announcements remain owned by the SDK root. Rendering and dispatch failures are delivered as MiniAppUiError; wasm-bindgen imports should use catch so JavaScript exceptions become normal Rust Result values. unmount removes appearance listeners and is safe to repeat. The SDK does not expose a privileged host capability through this entry.

See the package's examples/wasm-ui crate for mount, update, focus, action validation, replay/stale rejection, and teardown from Rust.

#Agent-Readable Catalog

Build tools and coding agents can load @theaiplatform/miniapp-sdk/ui-components.json. The versioned catalog records the public import, both style choices, and component families. Use it for discovery; use the TypeScript declaration for exact props and subcomponent names.

import catalog from '@theaiplatform/miniapp-sdk/ui-components.json' with { type: 'json' };

console.log(catalog.groups.forms);

Treat the /ui export and catalog as an SDK-versioned contract. Do not import the platform's private UI source or copy components into a miniapp repository.