# Installation and first use

Install the single npm package, check release availability, and add Faye UI to your React application.

## Install Faye UI from npm

Faye UI is packaged as one npm package, `@fayegram-ai/faye-ui`. Its component families, tokens, themes and integrations are import paths within that package. Component families are subpaths of that single install.

**Publication status: unpublished and not ready for release.** The `0.1.0` publication was withdrawn on October 23, 2026. The package is currently unavailable from npm. The command below describes installation after a corrected release becomes available; it does not work today. Documentation previews do not establish package availability.

Run this in your React application after publication:

```bash
npm install @fayegram-ai/faye-ui
```

A published package will not require GitHub access, repository cloning or a local library build. Package distribution is through npm. The official documentation address is [faye-ui.fayegram.com](https://faye-ui.fayegram.com/). Package support information will be announced with a corrected npm release.

## Requirements

Use Node.js 22.12 or later and React / React DOM 19.3 compatible with the declared `^19.3.0` peer ranges. The package installs its Base UI, Floating UI and raw Lucide dependencies automatically. Next.js is an optional peer (`^16.4.2`) for the Next integration; ordinary React applications do not need it.

## Component consumption
```tsx
'use client';
import '@fayegram-ai/faye-ui/tokens/layers.css';
import '@fayegram-ai/faye-ui/tokens/reset.css';
import '@fayegram-ai/faye-ui/tokens/theme.css';
import { FayeUIProvider } from '@fayegram-ai/faye-ui/provider/provider';
import { Button } from '@fayegram-ai/faye-ui/controls/button';

export function Application() {
  return <FayeUIProvider><Button tone="accent" variant="solid">Continue</Button></FayeUIProvider>;
}
```
Import the layer prelude and theme once at your application boundary. Component entry points import their own styles. The global reset is opt-in; embedded applications can use ScopedBaseline instead.

## Product namespace

The npm scope identifies the organization; `faye-ui` identifies this UI product. UI-owned styles, state and rendering integrations use the full product namespace:

| Contract | Identifier |
|---|---|
| Root CSS class | `.faye-ui-root` |
| CSS custom properties | `--faye-ui-*` |
| Theme scope attributes | `data-faye-ui-theme`, `data-faye-ui-scheme`, `data-faye-ui-density` |
| JavaScript DOM dataset access | `element.dataset.fayeUiTheme` |
| Docs color preference cookie | `faye-ui.docs.preference` |
| CSS cascade layers | `faye-ui.tokens`, `faye-ui.components`, `faye-ui.local` |
| Default theme ID | `faye-ui` |
| Native Node SSR condition | `--conditions=faye-ui-ssr` |

Organization artwork retains its own identity, such as `FayeMark`. Component families, themes and rendering integrations are module paths inside the one public package.

## Release status

See [verification](/docs/verification/) for the implementation's current checks and limits. Publishing the documentation and publishing the npm package are separate steps. The package currently declares an MIT license; repository visibility and package licensing are separate properties.