# Novi UI > React Aria Components を基盤にした React UI ライブラリ。 > 1つの core に複数の美学（テーマ）を持ち、挙動とアクセシビリティは core が引き受ける。 > バージョン 0.6.0 ## 必ず守ること（他のライブラリと違う点） - **Provider は不要**。import してそのまま使う。ラップしない - **`disabled` ではなく `isDisabled`**、**`onClick` ではなく `onPress`** を使う（React Aria 準拠） - **全コンポーネントは `data-slot="<名前>"` を出力する**。スタイルの上書きはこれを狙う - variant は `solid | outline | soft | ghost | plain` の5つのみ - size は `sm | md | lg`、color は `default | primary | secondary | success | warning | danger` - 色は `--novi-color-*` の CSS 変数を使う。リテラルの色値を書かない - **余白も `p-4` / `gap-4` ではなくトークンで書く**。面の内側は `--novi-pad-surface-x` / `--novi-pad-surface-y`、コントロールの左右は `--novi-pad-control-x-{sm,md,lg}`、要素間は `--novi-gap-{inline,stack,section}` - 見出しは `--novi-font-heading` / `--novi-tracking-tight` / `--novi-leading-heading`、本文は `--novi-leading-body`。数字は `--novi-font-numeric` - スタイルの拡張は `tv({ extend, slots })`。**`base` は slot 定義では効かない** - variant のクラスを上書きしたいときは `classNames={{ : '...' }}` を使う ## インストール **前提: React 19 / Tailwind CSS v4（必須）。** テーマの CSS はトークン定義だけで、コンポーネントのクラスは利用側の Tailwind が `@source` で生成する。`@source` を書き忘れると無スタイルで描画される。 ```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"; /* パスはこの CSS ファイルからの相対 */ @source "../node_modules/@novi-ui/raster/dist"; ``` ダークは ``（省略で OS 追従）。 ## テーマ - `@novi-ui/raster`（Raster）: ミニマル / スイス系 - `@novi-ui/tactile`（Tactile）: タッチファースト - `@novi-ui/flatlay`（Flatlay）: 帳票・文具 / z 軸なし コンポーネントはテーマパッケージから import する。**テーマを替えても props は変わらない。** テーマは見た目だけでなく DOM の組み立て方も替える（Tactile の Modal は下から出るシートになる）。 ## 色を選ぶ 各テーマは8色のカラーセットを持ち、`data-novi-color` 属性で切り替える。 **色名はテーマごとに違う。** 知らない名前を書いても壊れず、そのテーマの既定色になる。 ```html ``` - **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` は色選択の影響を受けない。 ## 書いてはいけないクラス CI が機械的に検査している。違反するとビルドが落ちる。 **規則はテーマごとに違う。** 使っているテーマの節を読むこと。 ### Raster（`@novi-ui/raster`） - `shadow-*（shadow-none とトークン shadow-[var(--novi-shadow-*)] は可）` — 影はトークン経由で、浮いている層だけに使う。面は境界線と背景色の差で表す - `rounded-md / lg / xl / 2xl / 3xl と任意値の角丸` — 角丸はトークン経由。Raster は sm=6 / md=8 / lg=12px の3段 - `border-2 以上` — 境界線は 1px のみ。面の分割は線の太さでなく余白で行う - `scale-* / scale-x-* / scale-y-*` — 動きで飾らない。モーションは opacity と translate のみ - `rotate-* / animate-spin` — 同上。回転は Spinner のみ例外（ADR-R2） - `リテラルの色値（#fff / rgb() / hsl() / oklch()）` — 色は必ず --novi-color-* を経由する。リテラル値を書かない - `duration-*（--novi-duration-* の任意値を除く）` — モーションの時間はトークン経由にする - `8px 以上の生の余白ユーティリティ（p/px/py/pt/pb/pl/pr/gap-2 以上）` — 余白はトークン経由（--novi-pad-* / --novi-gap-*）。余白がテーマの所有物でないと、各コンポーネントが各自の判断で数値を書き、3モデルが同じ密度に潰れる。8px 未満の微小インセットは部品の位置合わせなので生値を許す 色は `--novi-color-*` の CSS 変数経由でのみ指定する。リテラルの色値は書かない。中立色の chroma は 0 に固定し、面と文字の階層は明度だけで作る。 ### Tactile（`@novi-ui/tactile`） - `トークンを経由しない角丸（rounded-sm / rounded-full / rounded-t-xl など）` — 角丸はトークン経由。Tactile は sm=8 / md=14 / lg=20px で、none 以外は 8px 以上 - `トークン外の影（shadow-md / shadow-[0_1px…] など）` — 影はトークン経由。値は α ≤ 0.24 に縛られている - `border-2 以上` — 境界線は補助。使う場合も 1px のみ。面の分割は影と背景色差で行う - `押下状態以外の scale-*` — 装飾目的の scale は使わない。押下フィードバック（data-[pressed]:scale-*）のみ許可 - `rotate-* / animate-spin` — 回転は Spinner と Accordion のシェブロンのみ例外（ADR-T4） - `リテラルの色値（#fff / rgb() / hsl() / oklch()）` — 色は必ず --novi-color-* を経由する。リテラル値を書かない - `8px 以上の生の余白ユーティリティ（p/px/py/pt/pb/pl/pr/gap-2 以上）` — 余白はトークン経由（--novi-pad-* / --novi-gap-*）。余白がテーマの所有物でないと、各コンポーネントが自分の判断で数値を書き、3モデルが同じ密度に潰れる。8px 未満の微小インセット（アイコンの位置合わせ）だけ生値を許す - `duration-*（--novi-duration-* の任意値を除く）` — モーションの時間はトークン経由にする 色は --novi-color-* の CSS 変数経由でのみ指定する。data-novi-color で選ばれた染料に中立色まで追従するため、リテラル値を書くとテーマの外に取り残される ### Flatlay（`@novi-ui/flatlay`） - `z-index の指定（z-10 / z-[999] / zIndex）` — Flatlay は z 軸を持たない。重なりの順序は DOM 順だけで表す（例外なし・FR-02） - `fixed / absolute` — 浮く面を作らない。例外は modal.styles.ts（テイクオーバー）と tooltip.styles.ts の2つだけ（FR-03） - `sticky` — 滞留も重なり。スクロール中にコンテンツへ被る時点で z 軸の語彙になる（ADR-F4） - `トークン外の影（shadow-md / shadow-[0_1px…] など）` — 影は嘘（浮く層が存在しない）。トークンは全段 0 0 #0000 で、書いても何も出ない - `高さ・スライドのアニメーション` — 展開・格納は即時。押し下げに transition を付けると後続が滑り続けて読めなくなる（FR-12 / ADR-F1） - `scale-* / translate-* / rotate-* / animate-spin` — 押下は反転（スタンプ）で示す。動きで飾らない。例外は spinner.styles.ts のみ（FR-11） - `トークンを経由しない角丸（rounded-sm / rounded-full / rounded-t-xl など）` — 角丸はトークン経由。Flatlay は書類の直角で sm=md=2 / lg=4px - `リテラルの色値（#fff / rgb() / hsl() / oklch()）` — 色は必ず --novi-color-* を経由する。リテラル値を書かない - `duration-*（--novi-duration-* の任意値を除く）` — モーションの時間はトークン経由にする（Flatlay は 100ms の1本しかない） - `8px 以上の生の余白ユーティリティ（p/px/py/pt/pb/pl/pr/gap-2 以上）` — 余白はトークン経由（--novi-pad-* / --novi-gap-*）。生値で書くと3モデルが同じ密度に潰れ、「余白がテーマの所有物」でなくなる。8px 未満の微小インセットだけが例外（字やアイコンの当たり合わせ） 色は --novi-color-* の CSS 変数経由でのみ指定する。data-novi-color で染まるのは罫線だけだが、地の色もトークン経由でなければテーマの外に取り残される ## コンポーネント - [Accordion](https://novi-42r.pages.dev/docs/components/accordion/): 折りたたみできる項目の集合。 - [Avatar](https://novi-42r.pages.dev/docs/components/avatar/): 人や組織を表す画像。読み込みに失敗したら fallback を表示する。 - [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/): テーマのカラーセットから1色を選ぶ。選んだ値を `data-novi-color` に渡すと配色が変わる。 - [ComboBox](https://novi-42r.pages.dev/docs/components/combobox/): 文字を打って絞り込み、一覧から1つ選ぶ。選択肢が 20 件を超えるなら Select ではなくこちら。 - [DatePicker](https://novi-42r.pages.dev/docs/components/datepicker/): 日付を入力する。年 / 月 / 日のマスに直接打つか、カレンダーを開いて選ぶ。 - [Input](https://novi-42r.pages.dev/docs/components/input/): 1行テキスト入力。 - [Menu](https://novi-42r.pages.dev/docs/components/menu/): トリガーから開く操作の一覧。矢印キーで移動、Escape で閉じる。 - [Modal](https://novi-42r.pages.dev/docs/components/modal/): モーダルダイアログ。開いている間フォーカスは内側に閉じ込められ、Escape で閉じる。 - [NumberField](https://novi-42r.pages.dev/docs/components/numberfield/): 数値の入力。矢印キーと増減ボタンで `step` ずつ刻み、`Intl.NumberFormat` の書式（通貨・%・単位）で表示する。 - [Pagination](https://novi-42r.pages.dev/docs/components/pagination/): 一覧のページを移動する。現在ページは `aria-current` で示し、先頭と末尾のあいだが空くときだけ省略記号で詰める。 - [Popover](https://novi-42r.pages.dev/docs/components/popover/): トリガーに紐づいて浮かぶ小さな面。Escape で閉じてトリガーへフォーカスが戻る。 - [Progress](https://novi-42r.pages.dev/docs/components/progress/): 進捗の表示。`value` を省略すると不確定（indeterminate）表示になる。 - [Radio](https://novi-42r.pages.dev/docs/components/radio/): ラジオボタン。単体では使わず、必ず RadioGroup の中に置く。 - [RadioGroup](https://novi-42r.pages.dev/docs/components/radiogroup/): ラジオボタンのグループ。矢印キーで項目間を移動できる。 - [Select](https://novi-42r.pages.dev/docs/components/select/): 一覧から1つ選ぶ。矢印キーで移動、Escape で閉じてトリガーへフォーカスが戻る。 - [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/): 要素の補足説明。ホバーとフォーカスの両方で開く。 一覧にないものは**未実装**。近いもので代用せず、react-aria-components を直接使う。 ## Optional - [llms-full.txt](https://novi-42r.pages.dev/llms-full.txt): 全 props / slot / 使用例 - [llms-en.txt](https://novi-42r.pages.dev/llms-en.txt): English summary - [はじめに](https://novi-42r.pages.dev/docs/getting-started/): インストールと最小構成