# Novi UI (English summary)

> A React component library built on React Aria Components.
> One core holds behaviour and accessibility; several themes hold structure and style.
> Version 0.6.0
>
> The full documentation, per-component props and rationale are in Japanese:
> [llms.txt](https://novi-42r.pages.dev/llms.txt) and [llms-full.txt](https://novi-42r.pages.dev/llms-full.txt).

## Rules you must follow (these differ from other libraries)

- **No provider.** Import and use. Do not wrap the tree
- **`isDisabled`, not `disabled`. `onPress`, not `onClick`** (React Aria conventions)
- **Every component emits `data-slot="<name>"`.** Target these to override styles
- variant is one of `solid | outline | soft | ghost | plain`
- size is `sm | md | lg`, color is `default | primary | secondary | success | warning | danger`
- Use the `--novi-color-*` custom properties. Never write literal colour values
- **Spacing is a token too, not `p-4` / `gap-4`.** Inside a surface use `--novi-pad-surface-x` / `--novi-pad-surface-y`; horizontal padding of a control uses `--novi-pad-control-x-{sm,md,lg}`; between elements use `--novi-gap-{inline,stack,section}`
- Headings use `--novi-font-heading` / `--novi-tracking-tight` / `--novi-leading-heading`; body text uses `--novi-leading-body`; figures use `--novi-font-numeric`
- Extend styles with `tv({ extend, slots })`. **`base` has no effect on a slot definition**
- To override the classes of a variant, use `classNames={{ <slot>: '...' }}`

## Install

**Requires React 19 and Tailwind CSS v4.** A theme's CSS ships token definitions only; the
component classes are generated by the consuming project's Tailwind through `@source`.
Omit `@source` and everything renders unstyled.

```bash
pnpm add @novi-ui/core @novi-ui/raster react-aria-components
```

```css
/* app/globals.css */
@import "tailwindcss";
@import "@novi-ui/core/base.css";
@import "@novi-ui/raster/raster.css";
/* path is relative to this CSS file */
@source "../node_modules/@novi-ui/raster/dist";
```

Dark mode is `<html data-novi-scheme="dark">`; omit it to follow the OS setting.

## Themes

- `@novi-ui/raster` (Raster) — minimal / Swiss grid. Modal floats in the centre over a dimmed backdrop; close is an ✕ at the top right
- `@novi-ui/tactile` (Tactile) — touch-first, larger surfaces. Modal rises from the bottom as a sheet; close is full-width in the footer
- `@novi-ui/flatlay` (Flatlay) — no z-axis, paper and ruled lines. Nothing floats. Modal replaces the page as a full takeover; close is “← back” at the top left. Select and Menu expand in flow and push the page down

Import components from the theme package. **Props never change when you change theme.**
A theme changes how the DOM is assembled, not only how it looks.

## Colourways

Each theme owns a set of 8 colours, selected with the `data-novi-color` attribute.
**The names differ per theme.** An unknown name does not break anything; it falls back to
that theme's default colour.

```html
<html data-novi-theme="tactile" data-novi-color="madder">
```

- **Raster**: ink / prussian / forest / olive / ochre / brick / bordeaux / graphite
- **Tactile**: indigo / peacock / sage / saffron / madder / cochineal / mauve / greige
- **Flatlay**: fieldbook / blueprint / carbon / ribbon / eraser / manila / legalpad / pencil

`success` / `warning` / `danger` are unaffected by the colourway.

## Classes you must not write

CI checks these mechanically; a violation fails the build.
**The rules differ per theme.** The rationale for each is in the Japanese
[llms.txt](https://novi-42r.pages.dev/llms.txt).

### Raster (`@novi-ui/raster`)

- `shadow-*（shadow-none とトークン shadow-[var(--novi-shadow-*)] は可）`
- `rounded-md / lg / xl / 2xl / 3xl と任意値の角丸`
- `border-2 以上`
- `scale-* / scale-x-* / scale-y-*`
- `rotate-* / animate-spin`
- `リテラルの色値（#fff / rgb() / hsl() / oklch()）`
- `duration-*（--novi-duration-* の任意値を除く）`
- `8px 以上の生の余白ユーティリティ（p/px/py/pt/pb/pl/pr/gap-2 以上）`

### Tactile (`@novi-ui/tactile`)

- `トークンを経由しない角丸（rounded-sm / rounded-full / rounded-t-xl など）`
- `トークン外の影（shadow-md / shadow-[0_1px…] など）`
- `border-2 以上`
- `押下状態以外の scale-*`
- `rotate-* / animate-spin`
- `リテラルの色値（#fff / rgb() / hsl() / oklch()）`
- `8px 以上の生の余白ユーティリティ（p/px/py/pt/pb/pl/pr/gap-2 以上）`
- `duration-*（--novi-duration-* の任意値を除く）`

### Flatlay (`@novi-ui/flatlay`)

- `z-index の指定（z-10 / z-[999] / zIndex）`
- `fixed / absolute`
- `sticky`
- `トークン外の影（shadow-md / shadow-[0_1px…] など）`
- `高さ・スライドのアニメーション`
- `scale-* / translate-* / rotate-* / animate-spin`
- `トークンを経由しない角丸（rounded-sm / rounded-full / rounded-t-xl など）`
- `リテラルの色値（#fff / rgb() / hsl() / oklch()）`
- `duration-*（--novi-duration-* の任意値を除く）`
- `8px 以上の生の余白ユーティリティ（p/px/py/pt/pb/pl/pr/gap-2 以上）`

## Components

- [Accordion](https://novi-42r.pages.dev/docs/components/accordion/)
- [Avatar](https://novi-42r.pages.dev/docs/components/avatar/)
- [Badge](https://novi-42r.pages.dev/docs/components/badge/)
- [Breadcrumbs](https://novi-42r.pages.dev/docs/components/breadcrumbs/)
- [Button](https://novi-42r.pages.dev/docs/components/button/)
- [Card](https://novi-42r.pages.dev/docs/components/card/)
- [Checkbox](https://novi-42r.pages.dev/docs/components/checkbox/)
- [CheckboxGroup](https://novi-42r.pages.dev/docs/components/checkboxgroup/)
- [ColorPicker](https://novi-42r.pages.dev/docs/components/colorpicker/)
- [ComboBox](https://novi-42r.pages.dev/docs/components/combobox/)
- [DatePicker](https://novi-42r.pages.dev/docs/components/datepicker/)
- [Input](https://novi-42r.pages.dev/docs/components/input/)
- [Menu](https://novi-42r.pages.dev/docs/components/menu/)
- [Modal](https://novi-42r.pages.dev/docs/components/modal/)
- [NumberField](https://novi-42r.pages.dev/docs/components/numberfield/)
- [Pagination](https://novi-42r.pages.dev/docs/components/pagination/)
- [Popover](https://novi-42r.pages.dev/docs/components/popover/)
- [Progress](https://novi-42r.pages.dev/docs/components/progress/)
- [Radio](https://novi-42r.pages.dev/docs/components/radio/)
- [RadioGroup](https://novi-42r.pages.dev/docs/components/radiogroup/)
- [Select](https://novi-42r.pages.dev/docs/components/select/)
- [Skeleton](https://novi-42r.pages.dev/docs/components/skeleton/)
- [Spinner](https://novi-42r.pages.dev/docs/components/spinner/)
- [Switch](https://novi-42r.pages.dev/docs/components/switch/)
- [Table](https://novi-42r.pages.dev/docs/components/table/)
- [Tabs](https://novi-42r.pages.dev/docs/components/tabs/)
- [Textarea](https://novi-42r.pages.dev/docs/components/textarea/)
- [Toast](https://novi-42r.pages.dev/docs/components/toast/)
- [Tooltip](https://novi-42r.pages.dev/docs/components/tooltip/)

Anything not listed is **not implemented**. Do not substitute something similar — use
react-aria-components directly, and note that it ships no styles.

## Optional

- [llms-full.txt](https://novi-42r.pages.dev/llms-full.txt): every prop, slot and example (Japanese)
- [Getting started](https://novi-42r.pages.dev/docs/getting-started/) (Japanese)