#UI Component Library

@zephyrcloudio/ui is the shared component library behind The AI Platform. Every surface in the desktop app is built from it. Miniapps get a portable subset of it — not the whole library — through @theaiplatform/miniapp-sdk/ui; see Agent-readable catalog.

Browse the library in the component explorer — stories for most components across all four tiers, in both light and dark themes. Some templates have no story yet, so the explorer is a wide sample rather than a complete API reference.

# 1. Storybook on its own, at http://localhost:6006 — no /ui path involved
pnpm build:deps
pnpm --filter @zephyrcloudio/ui storybook

# 2. The docs site with the explorer mounted at /ui/
pnpm exec turbo run build-storybook --filter=@zephyrcloudio/ui
pnpm --filter documentation build && pnpm --filter documentation preview

Pick a component on the left, change its props in the Controls panel, and switch themes from the toolbar.

#What you get

The library is organized into four tiers:

Two domain families cut across those tiers. ai covers chat and agent components including prompt input, conversation, and chain of thought. brand covers provider logos for Anthropic, OpenAI, Amazon Bedrock, and the rest.

#Installing

The package is published to GitHub Packages, so installing it needs a registry entry and a GitHub token with read:packages on the ZephyrCloudIO organization.

Add the scope to your .npmrc:

@zephyrcloudio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Then install the package and its React peers:

pnpm add @zephyrcloudio/ui react react-dom lucide-react

react and react-dom are peer dependencies. The library does not bundle its own copy. lucide-react is a dependency of the package rather than a peer, but a strict package manager will not let your own code import it unless you declare it too — and the icon usage below does.

Tailwind CSS v4 is required, not optional. The package ships no compiled component CSS: theme.css is token declarations, and tailwind.css is a source scan plus a few theme values. The class names on every component are emitted by your Tailwind build, so without it the components render unstyled.

pnpm add -D tailwindcss @tailwindcss/postcss

Register the PostCSS plugin:

// postcss.config.mjs
export default { plugins: { '@tailwindcss/postcss': {} } };

Then import all three stylesheets:

@import 'tailwindcss';
@import '@zephyrcloudio/ui/theme.css';
@import '@zephyrcloudio/ui/tailwind.css';

Icon glyphs come from lucide-react. It is a dependency of the library rather than a peer, but pnpm does not hoist it, so add it too if you pass glyphs to Icon yourself:

pnpm add lucide-react

#Importing components

Import paths are tier-free. A component's specifier is its own name, whatever tier it happens to live in:

import { Button } from '@zephyrcloudio/ui/button';
import { Dialog } from '@zephyrcloudio/ui/dialog';
import { Sidebar } from '@zephyrcloudio/ui/sidebar';

The two domain families keep their prefix:

import { PromptInput } from '@zephyrcloudio/ui/ai/prompt-input';
import { TapIcon } from '@zephyrcloudio/ui/brand/tap-icon';

Barrel imports pull from the whole library or the whole ai family at once:

import { Button, Dialog, H1 } from '@zephyrcloudio/ui';
import { Conversation, Message } from '@zephyrcloudio/ui/ai';

Prefer the per-component specifiers. They let your bundler drop everything you did not import.

Because paths carry no tier, a component moving between tiers never breaks your imports. The specifier is stable even when the internal file location is not.

#Theming

The library owns its design tokens. Import the theme stylesheet once, near the root of your app:

import '@zephyrcloudio/ui/theme.css';

That single import defines every token for both light and dark themes. Colors, surfaces, radii, shadows, and typography all come from it.

Style your own markup with the Tailwind utilities that reference those tokens:

<div className="bg-card text-card-foreground rounded-lg border-border">
  <p className="text-muted-foreground">Supporting copy</p>
</div>

Use the semantic token utilities rather than raw color values. bg-card follows the active theme. A hardcoded hex does not, and will look wrong in one of the two themes.

Dark mode is a class on the document root. Toggle dark on <html> and every token switches.

Do not read tokens through var(--token) directly, and do not hardcode colors or spacing. The Tailwind utilities are the supported surface. Token names are free to change between releases.

Import the library's Tailwind entry alongside the theme. It adds the @source scan that lets your build discover the class names used inside the package — without it Tailwind never emits them:

import '@zephyrcloudio/ui/tailwind.css';

This entry does not yet publish the @theme color mappings that generate the semantic utilities (bg-card, text-muted-foreground, and the rest) — those currently live in the desktop app's own stylesheet, not the package. Until they ship standalone, an external Tailwind build must define those @theme color mappings itself for those utilities to be emitted.

#Icons and headings

Two component families have a single supported entry point.

Render icons through Icon rather than reaching for a raw SVG or a lucide-react component:

import { Icon } from '@zephyrcloudio/ui/icon';
import { Search } from 'lucide-react';

<Icon icon={Search} size="sm" color="primary" />;

Size icons with the size prop, never with width or height utility classes.

Render headings through the H1 to H6 components rather than raw heading tags:

import { H1, H2 } from '@zephyrcloudio/ui';

<H1>Page title</H1>;

Both carry the type scale and spacing the rest of the library expects.

#Agent-readable catalog

The package ships a machine-readable catalog of the component subset that is portable to miniapps, grouped by family:

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

It exists so a specialist can pick the right component when generating miniapp UI: its import specifiers point at @theaiplatform/miniapp-sdk/ui, not the full @zephyrcloudio/ui surface, and it lists the portable subset rather than every component or its variants. For anything outside that subset, browse the component explorer or read the export map in packages/ui/package.json — the explorer covers most, but not all, exported components.

#Component explorer

The component explorer is the reference for everything above. Each component page lists its variants, sizes, and states, with a controls panel for changing props live and a theme switcher for checking both themes.

Start there when you are looking for a component. Come back here for how to install and import it.