# Uhuru UI React Setup

This guide shows how to use `@digitwhale_innovations/uhuru-ui` in an external React app.

It is written for React only.

## Recommended Stack

Use:

- React
- React DOM
- TypeScript
- Vite

Uhuru UI is source-first, so a modern bundler like Vite is the cleanest setup for external consumers.

## 1. Create a React App

The quickest path is a Vite React app:

```bash
npm create vite@latest my-uhuru-app -- --template react-ts
cd my-uhuru-app
npm install
```

## 2. Install Uhuru UI

Install the package from your registry or package source:

```bash
npm install @digitwhale_innovations/uhuru-ui
```

If you are using a private registry, make sure the machine has access to that registry before installing.

## 3. Import Uhuru Styles Once

Import the package stylesheet once at the app entry point.

```tsx
// src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { UhuruProvider } from "@digitwhale_innovations/uhuru-ui";
import "@digitwhale_innovations/uhuru-ui/styles.css";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <UhuruProvider theme="light" density="compact">
      <App />
    </UhuruProvider>
  </React.StrictMode>,
);
```

## 4. Build Your App Inside UhuruProvider

Wrap your app once so every component receives the shared theme, density, and radius tokens.

```tsx
// src/App.tsx
import { Button, Card, CardBody, CardHeader } from "@digitwhale_innovations/uhuru-ui";

export default function App() {
  return (
    <main style={{ padding: 24 }}>
      <Card>
        <CardHeader
          eyebrow="Workspace"
          title="Uhuru Billing"
          description="A simple external React setup."
        />
        <CardBody>
          <Button>Save changes</Button>
        </CardBody>
      </Card>
    </main>
  );
}
```

## 5. What To Import

Import components directly from the package root:

```tsx
import { Button, Card, TextField } from "@digitwhale_innovations/uhuru-ui";
```

For styles, import only once:

```tsx
import "@digitwhale_innovations/uhuru-ui/styles.css";
```

## 6. Theme Colors

UhuruProvider now resolves accent colors through `presetAccent`. Use `accentPresets` to add or replace the bundled preset list, and keep `colors` for final token overrides when the product needs a one-off adjustment beyond the selected preset.

## 7. Supported React Range

The package currently declares React peer support for:

- React 17
- React 18
- React 19

## 8. Notes For External Consumers

- This package is source-first, so a React setup with a proper bundler is recommended.
- Vite is the safest default for external use.
- Do not rely on the internal workspace alias used inside this repository.
- If you are publishing your own app, keep the package version pinned and update intentionally.

## 9. Minimal External Setup Checklist

- Create a React app
- Install `@digitwhale_innovations/uhuru-ui`
- Import `@digitwhale_innovations/uhuru-ui/styles.css`
- Wrap the app with `UhuruProvider`
- Use Uhuru components from the package root

## 9. Example Folder Layout

```text
my-uhuru-app/
  src/
    App.tsx
    main.tsx
    index.css
  package.json
  vite.config.ts
```

## 10. If You Hit A Build Issue

If your external React app cannot compile the package source directly, use Vite or another bundler that can transpile TypeScript dependencies.

That is the expected setup for Uhuru UI today.