はじめに

Provider は要りません。Tailwind v4 のプロジェクトに CSS を数行足せば動きます。

前提

React 19 と react-aria-components 1.20 以上
Tailwind CSS v4 は必須です。 テーマの CSS はトークン定義だけを持ち、コンポーネントのクラスは利用側の Tailwind が生成します。Tailwind 無しでは何も描画されません

テーマを1つ選ぶ

3つのテーマは公開 API が完全に同一です。以下では Raster を使いますが、パッケージ名を読み替えるだけで他のテーマになります。

@novi-ui/rasterRasterミニマル / スイス系
@novi-ui/tactileTactileタッチファースト
@novi-ui/flatlayFlatlay帳票・文具 / z 軸なし

インストール

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";

/* テーマが出力するクラスを Tailwind に拾わせる。パスはこの CSS からの相対 */
@source "../node_modules/@novi-ui/raster/dist";

@source のパスは CSS ファイルからの相対です。src/app/globals.css に置くなら ../../node_modules/... になります。これを忘れるとコンポーネントは無スタイルで描画されます。

使う

import { Button, Input } from '@novi-ui/raster'

export function SignInForm() {
  return (
    <form>
      <Input label="メールアドレス" type="email" isRequired />
      <Button type="submit" color="primary">送信</Button>
    </form>
  )
}

ラップするものはありません。React Server Components からも型や slot 契約をそのまま import できます。

テーマ・配色・ダーク

すべて <html> の属性で決まります。どれも省略できます。

<html data-novi-theme="raster" data-novi-scheme="dark" data-novi-color="brick">

data-novi-theme: テーマ名（raster / tactile / flatlay）。上の手順のように raster.css を読むなら省略できます。複数テーマを1ページで併用するときは raster.scoped.css を読み、この属性の配下にだけ効かせます。
data-novi-scheme: light か dark。省略すると OS の設定に追従します。切り替えは属性を書き換えるだけです。
data-novi-color: 配色（カラーウェイ）。各テーマが8色を持ち、色名はテーマごとに違います。一覧は Lookbook に。知らない名前を渡しても壊れず、そのテーマの既定色になります。

// ダークにする
document.documentElement.dataset.noviScheme = 'dark'
// ライトに戻す
document.documentElement.dataset.noviScheme = 'light'
// 属性を消せば OS の設定に追従する
delete document.documentElement.dataset.noviScheme

AI エージェントと使う

Skill・レジストリ・MCP の3つを用意しています。どれも同じ中間表現から生成しているので、実装とずれません。shadcn のレジストリは @source まで注入するので、導入の事故（無スタイル）が起きません。

# Claude Code / Cursor / Codex / Copilot に規約と部品一覧を渡す
npx skills add yuuto22009911-hash/novi --skill novi-ui

# shadcn CLI で導入する（npm インストールと globals.css への @import / @source 注入。ソースはコピーしない）
npx shadcn@latest add https://novi-42r.pages.dev/r/raster.json

# MCP サーバ（読み取り専用・オフライン）
claude mcp add novi-ui -- npx -y @novi-ui/mcp

知っておくと良いこと

props 名は React Aria の慣習に従います: disabled ではなく isDisabled、onClick ではなく onPress です。基盤の props をそのまま流すことで、変換層に起因する a11y のバグを作り込まずに済みます。
ブランド色は8色から選びます: data-novi-color で選べる色は、全テーマ・ライト / ダークの全組み合わせでコントラストを検査済みです。どうしても外の色が要るときは --novi-color-primary を上書きできますが、検査の外に出ます。
日本語入力で誤送信しません: Input と TextArea の onKeyDown は IME 変換中のキーを受け取りません。変換確定の Enter でフォームが送信される事故を防げます。