# Aim Window UI

> @aimwindow/ui is Aim Window's own React component library. Aim Window is a service company, so every client project uses these same components with its own colours, fonts and style.

If you were told to use this library, follow this file.

## Rules

- Build the UI from these components. Do not search the web for UI, and do not add another UI library such as shadcn/ui or MUI.
- Read [COMPONENTS.md](COMPONENTS.md) before writing any UI. It has every component's import, props and an example.
- Pages arrange components and do not restyle them. To change a look, use a prop or the client's theme file.
- Put the client's look only in `src/theme.css`. Never edit the library's code or copy its components.
- Use token classes such as `bg-surface` and `text-muted`. Never hard-code a colour. Tailwind's default colours are removed, so `bg-red-500` does nothing.
- If the user has not given a client's colours and fonts, ask for them before building.
- If a component does not exist, say so, so that the user can add it to the library. Do not fetch one from the web. If it is needed right away, build it in the app from these components and tokens, and tell the user you did.

## Start a new project

This is for a Vite and React app, with React 19 and Tailwind CSS 4.

### 1. Install

```bash
pnpm add react react-dom lucide-react SITE/aimwindow-ui-fca45623ec.tgz
pnpm add -D tailwindcss @tailwindcss/vite
```

SITE is the address you read this file from, without /llms.txt. The file name changes with each release of the library, so run this again with the latest name to update an app.

### 2. Add the Tailwind plugin to vite.config.ts

```ts
import tailwindcss from '@tailwindcss/vite'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})
```

### 3. Set up src/index.css

```css
@import 'tailwindcss';
@import '@aimwindow/ui/tokens.css';
@import '@aimwindow/ui/base.css';
@import './theme.css';

/* Lets Tailwind see the classes the components use. The path is relative to this file. */
@source '../node_modules/@aimwindow/ui/dist';
```

### 4. Set the client's look

Copy [theme-template.css](theme-template.css) to `src/theme.css`, set the client's values, and delete the lines you do not need. Load the client's fonts in `index.html`, because the library does not load fonts. Without a theme file, the app gets Aim Window's blue and the Inter font, which is rarely right for a client.

Every component then follows the theme, in light and dark. White text sits on the primary colour, so pick a colour with at least 4.5:1 contrast against white, or set `--primary-fg`.

### 5. Wrap the app

```tsx
import { Button, ToastProvider } from '@aimwindow/ui'
import { Plus } from 'lucide-react'
import './index.css'

export function App() {
  return (
    <ToastProvider>
      <div className="flex flex-col gap-5 bg-bg p-5">
        <Button leftIcon={<Plus />}>Add customer</Button>
      </div>
    </ToastProvider>
  )
}
```

The theme follows the computer's light or dark setting. Set `data-theme="light"` or `"dark"` on `<html>` to choose one.

## Files

- [COMPONENTS.md](COMPONENTS.md): every component, its props and an example, plus helpers and token classes. Also at `node_modules/@aimwindow/ui/docs/COMPONENTS.md` once installed.
- [theme-template.css](theme-template.css): everything a client's look can change.
- [list-page-pattern.tsx](list-page-pattern.tsx): a finished list page, with a table, number cards, a side form and a delete confirmation. Start from it for any list of records.

## Components

- **Actions:** Button, IconButton, TableActions
- **Inputs:** Field, Input, Textarea, Select, DatePicker, Toggle, FileUpload
- **Data display:** DataTable, Kpi and KpiGrid, StatusBadge, Avatar, Card
- **Overlays:** Modal, FormDrawer, ConfirmDialog, Tooltip
- **Feedback:** ToastProvider and useToast, Skeleton, EmptyState