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

# Overview

> Ekanos-styled UI primitives for building integrations outside the Ekanos monorepo.

`@ekanos/ui` is a curated, published slice of the internal `@kit/ui` library—Ekanos-styled components chosen from what the SDK's re-exported components and the example integrations actually use.

**Inside the monorepo:** keep importing `@kit/ui/*` directly. This package exists for partners who can't.

## Installation

```bash theme={null}
npm install @ekanos/ui
# or
pnpm add @ekanos/ui
```

## Peer dependencies

You provide these at runtime:

```json theme={null}
{
  "react": "^19.2.8",
  "react-dom": "^19.2.8",
  "react-hook-form": "^7.68.0",
  "@hookform/resolvers": "^5.2.2",
  "next-intl": "^4.14.7"
}
```

`react-hook-form` and `@hookform/resolvers` are only needed for form usage, and `next-intl` for `Trans`. Everything else the components need at runtime (Base UI, `class-variance-authority`, `clsx`, `tailwind-merge`, `cmdk`, `nanoid`) is a declared dependency.

## Quick start

### Option 1: Use the compiled stylesheet (no Tailwind)

```ts theme={null}
import '@ekanos/ui/styles.css';

import { Button } from '@ekanos/ui/button';
import { Card, CardContent, CardHeader, CardTitle } from '@ekanos/ui/card';

export function App() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Click me</Button>
      </CardContent>
    </Card>
  );
}
```

`styles.css` is self-contained: Tailwind Preflight, design tokens, light and dark mode, and every utility class the components emit. No build step; it works in Next.js, Vite, CRA, a plain `<link>`, anything. It does not contain utilities for classes you write yourself (`p-8`, `grid-cols-3`), and its Preflight is a global reset.

### Option 2: Integrate with your Tailwind build

```css theme={null}
@import 'tailwindcss';
@import '@ekanos/ui/theme.css';
```

This registers the token map, theme values, base rules, the `dark:` variant, and an `@source` pointing at the package's bundles so your Tailwind build generates the components' utilities. You then get Ekanos tokens in your own classes too. Pick one path: loading both means two copies of every utility.

See [Styling](/ui/styling) for the full paths and trade-offs.

## What's exported

One subpath per component (24 in total), plus four stylesheets:

| Category | Subpaths |
| - | - |
| Forms | `button`, `input`, `textarea`, `select`, `switch`, `label`, `form` |
| Overlays | `dialog`, `dropdown-menu`, `tooltip` |
| Layout & status | `card`, `badge`, `status-badge`, `stat`, `alert`, `skeleton`, `separator`, `spinner` |
| Page structure | `page` (`PageRail`, `PageTitleSection`, `PageToolbar`, `PageBody`, and more) |
| Utilities | `icon` (Font Awesome), `if`, `trans` (next-intl), `utils` (`cn()`, route helpers) |
| AI | `ai-prompt-input` (`PromptInput` compound components) |
| Stylesheets | `styles.css`, `theme.css`, `tokens.css`, `base.css` |

See [Components](/ui/components) for the full list and import paths.

## Design tokens

Every component emits Tailwind class strings bound to Ekanos's semantic design tokens (`bg-primary`, `text-muted-foreground`, `border-border`, `shadow-card`, …), so something has to define those — that is what the stylesheets are for.

`tokens.css` and `theme.css` carry Ekanos's full semantic token set — surfaces, brand, status, chart, sidebar, the elevation scale, radius, and fonts — for both themes, so utilities like `bg-chart-1` or `shadow-widget` resolve in your own markup on the Tailwind path. The compiled `styles.css` is pruned to what the package's own components use.

See [Styling](/ui/styling) for how to control dark mode and page backgrounds.

## Light and dark mode

Dark mode resolves in this order:

1. `.dark` or `[data-theme='dark']` ancestor — dark
2. `.light` or `[data-theme='light']` on `:root` — light
3. `@media (prefers-color-scheme: dark)` — dark
4. Default — light

So a page with no theme toggle respects the OS setting, and one with a toggle (next-themes, or custom) works by setting a class.

To adopt Ekanos's page surface (which makes dark mode look right rather than dark cards on white):

```html theme={null}
<body class="ekanos-root">
  <!-- content -->
</body>
```

## Icon handling

`Icon` renders Font Awesome markup. **You must supply the icon font** — this package ships no font data due to licensing.

If you have a **Font Awesome Pro license**, load your Pro CSS and every icon renders exactly as it does in Ekanos.

If you use **Font Awesome Free**, install it and override the icon style:

```ts theme={null}
import '@fortawesome/fontawesome-free/css/all.min.css';
import { IconStyleOverrideProvider } from '@ekanos/ui/icon';

<IconStyleOverrideProvider value="solid">
  {children}
</IconStyleOverrideProvider>
```

Free ships `fa-solid`, `fa-regular`, and `fa-brands`, and lacks many Pro glyphs. In development, `Icon` warns in the console once per name that Free does not ship.

See [Fonts & Icons](/ui/fonts-and-icons) for the full setup.

## Runtime notes

* **Base UI, not Radix** — popups use `@base-ui/react`; no `asChild` prop, use `render` instead
* **`Trans` needs next-intl** — renders against the host's messages; must run under a `NextIntlClientProvider`
* **`Spinner` is self-contained** — draws an SVG, no icon font needed
* **Client components are marked** — `'use client'` is preserved in each client entry's bundle
* **Server-safe entries** — `alert`, `badge`, `button`, `card`, `input`, `textarea`, `skeleton`, `if`, `spinner`, and `utils` carry no directive

See [Runtime Notes](/ui/runtime-notes) for details.

## Next steps

* [Browse all components](/ui/components)
* [Configure styling](/ui/styling)
* [Set up icons and fonts](/ui/fonts-and-icons)
* [Understand client/server boundaries](/ui/runtime-notes)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.