> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform-Aware UI Library

> Ship HTML-first consent, status, and orchestration screens with @frontmcp/ui and @frontmcp/uipack.

The FrontMCP UI packages provide a platform-aware HTML component system designed for LLM surfaces. They render complete markup (no React runtime required) and ship a Tailwind v4 theme system, page templates, and OpenAI App widgets so you can style consent screens, troubleshooting pages, or CodeCall dashboards inside any MCP server.

<Note>
  **Package responsibilities:**

  * `@frontmcp/ui` provides HTML components (`/components`), layouts (`/layouts`), widgets (`/widgets`), and React components (`/react`)
  * `@frontmcp/uipack` provides theming (`/theme`), page templates (`/pages`), and build utilities
</Note>

## Why use the UI packages

* **Pure HTML output** – Components return strings so you can stream them directly through MCP resources, auth flows, or ngrok tunnels.
* **Platform detection** – Helpers detect OpenAI, Claude, Gemini, and local browsers so you can inline scripts when networks are blocked.
* **Theme system** – Ship the default GitHub/OpenAI skin or mint your own palette, typography, and CDN URLs.
* **Zod validation** – Each component validates props at runtime and renders helpful error boxes instead of crashing.

## Install

<CodeGroup>
  ```bash npm theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
  npm install @frontmcp/ui @frontmcp/uipack
  ```

  ```bash pnpm theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
  pnpm add @frontmcp/ui @frontmcp/uipack
  ```

  ```bash yarn theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
  yarn add @frontmcp/ui @frontmcp/uipack
  ```
</CodeGroup>

## Compose a page layout

Wrap content with `baseLayout`, then mix components such as `card` and `button`. Everything resolves to HTML strings you can hand to an MCP resource or auth callback.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { baseLayout } from '@frontmcp/ui/layouts';
import { card, button } from '@frontmcp/ui/components';
import { DEFAULT_THEME } from '@frontmcp/uipack/theme';

const content = card(
  `
  <h2 class="text-lg font-semibold">CRM Access</h2>
  <p>Grant the CodeCall orchestrator access to customer data.</p>
  ${button('Approve', { variant: 'primary', type: 'submit' })}
`,
  { variant: 'elevated' },
);

const html = baseLayout(content, {
  title: 'Authorize CRM',
  description: 'Let the agent read CRM data for this session.',
  theme: DEFAULT_THEME,
  width: 'md',
  align: 'center',
  scripts: { tailwind: true },
});
```

Send `html` as the body of an MCP resource, OAuth consent page, or even an email.

## Theme and platform detection

Use `createTheme` to adjust palettes, typography, and CDN endpoints. Then decide whether to inline scripts (Claude Artifacts) or load from the network (OpenAI, Gemini).

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import {
  createTheme,
  buildCdnScriptsFromTheme,
  fetchAndCacheScriptsFromTheme,
  getPlatform,
  canUseCdn,
  needsInlineScripts,
} from '@frontmcp/uipack/theme';

const theme = createTheme({
  name: 'crm-dark',
  colors: {
    semantic: { primary: '#0BA5EC', secondary: '#6366F1', accent: '#F97316' },
  },
  cdn: {
    scripts: {
      tailwind: 'https://cdn.example.com/tailwind-4.js',
    },
  },
});

async function buildScripts(forPlatform: string) {
  const platform = getPlatform(forPlatform);

  if (canUseCdn(platform)) {
    return buildCdnScriptsFromTheme(theme);
  }

  if (needsInlineScripts(platform)) {
    await fetchAndCacheScriptsFromTheme(theme);
    return buildCdnScriptsFromTheme(theme, { inline: true });
  }

  return '';
}
```

<Tip>
  Claude Artifacts and other restricted environments block outbound requests. Call `fetchAndCacheScriptsFromTheme` during build, then inline the cached scripts with `buildCdnScriptsFromTheme(..., { inline: true })`.
</Tip>

## Page templates out of the box

Need a consent or error page fast? Use the prebuilt templates so every auth flow looks consistent.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { consentPage, consentSuccessPage, errorPage } from '@frontmcp/uipack/pages';

const grantScreen = consentPage({
  client: { name: 'CodeCall CRM', id: 'crm' },
  user: { name: 'Ada Lovelace', email: 'ada@example.com' },
  scopes: [
    { name: 'tools:users:*', description: 'Read and manage CRM users' },
    { name: 'tools:activities:*', description: 'Log activities and view stats' },
  ],
});

const successScreen = consentSuccessPage({
  clientName: 'CodeCall CRM',
  nextSteps: ['Return to the Inspector', 'Share the scoped token with your agent'],
});

const outageScreen = errorPage({
  title: 'CRM temporarily unavailable',
  description: 'We paused the orchestrator while maintenance completes.',
});
```

## Validation and debugging

Components validate input with Zod. When something is wrong, the library renders a compact error box that lists the component name and the failed property—perfect for catching mistakes before you ship.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { button } from '@frontmcp/ui/components';

const ok = button('Continue', { variant: 'primary' });

// Invalid variant => returns an error markup instead of throwing
const broken = button('Continue', { variant: 'purple' as any });
```

<Warning>
  Validation errors render in development and production. Keep an eye on your previews to ensure you only ship supported variants and attributes.
</Warning>

## Widgets and next steps

The `@frontmcp/ui/widgets` module exposes OpenAI App SDK components (resource pickers, action lists) plus status badges, progress indicators, and table helpers. Pair this guide with the [CodeCall CRM demo](/frontmcp/guides/codecall-crm-demo) to see the library inside a full orchestration workflow, or expose the HTML through an MCP resource for your own consent flows.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="CodeCall CRM Demo" icon="users" href="/frontmcp/guides/codecall-crm-demo">
    See UI in a complete application
  </Card>

  <Card title="Building Tool UI" icon="palette" href="/frontmcp/guides/building-tool-ui">
    Use UI components in tool templates
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/frontmcp/servers/tools">
    Full @Tool decorator documentation
  </Card>

  <Card title="Resources Reference" icon="database" href="/frontmcp/servers/resources">
    Expose HTML through MCP resources
  </Card>
</CardGroup>