labsUI

labsui

labsUI のコンポーネントをプロジェクトに追加します。 あらゆるモーションを滑らかなスプリングで表現する、クリーンな React プリミティブです。コンポーネントはコードベースにコピーされるため、自由に編集できます。

React 19、Tailwind CSS v4、パスエイリアス （tsconfig.json の "paths": { "@/*": ["./src/*"] }）が必要です。CLI は Node.js 22 以降、または Deno で動作します。依存関係はなく、オフラインでも利用できます。

使い方

npx @kznlabs/labsui init                # once: styles, theme, utils, motion provider
npx @kznlabs/labsui add button tabs     # components plus everything they import
npx @kznlabs/labsui search date range   # find by name, export or intent
npx @kznlabs/labsui view dialog         # props, examples, what it installs
npx @kznlabs/labsui update              # newer components, keeping your edits
npx @kznlabs/labsui doctor              # check the setup

どのランナーでも使えます。bunx @kznlabs/labsui add button、pnpm dlx @kznlabs/labsui …、 yarn dlx @kznlabs/labsui …、または JSR を使った deno run -A jsr:@kznlabs/labsui add button が利用できます。npm の依存関係は、ロックファイルに記載されたパッケージマネージャーでインストールされます。

コンポーネントレジストリはパッケージ内に含まれているため、npm の依存関係のインストール以外にネットワークは必要ありません。また、どの labsui バージョンでも同じコンポーネントコードがインストールされます。npx @kznlabs/labsui@latest add … を使うと、最新のコンポーネントを取得できます。

グローバルインストール

各プロジェクトで npx @kznlabs/labsui の代わりに labsui と入力するには、次のようにします。

npm install -g @kznlabs/labsui    # or: bun add -g @kznlabs/labsui
deno install -gA -n labsui jsr:@kznlabs/labsui

グローバルインストールでは、各リリースにレジストリが含まれているのと同様に、コンポーネントのバージョンが固定されます。新しいコンポーネントが必要になったら更新してください（npm install -g @kznlabs/labsui@latest）。npx @kznlabs/labsui@latest を使うと、常に最新のものを取得できます。

コマンド

init

• styles/labsui.css（トークン、アクセントのプリセット、アニメーション）を書き込み、スタイルシート内の @import "tailwindcss" の直後にインポートを追加します。
• lib/utils、lib/theme、components/motion-provider を追加し、motion、clsx、tailwind-merge をインストールします。
• レジストリ URL、エイリアス、フォルダーを記録した labsui.json を保存します。
• ルートレイアウトに必要な行（テーマスクリプト、MotionProvider）を表示します。

既存のファイルは保持されるため、いつでも再実行できます。

add

レジストリを通じて依存関係を解決し（data-table は table、checkbox、pagination などを追加します）、各ファイルをエイリアスのフォルダーに書き込み、インポートする npm パッケージをインストールします。--overwrite を指定しない限り、既存のファイルは保持されます。保持された依存ファイルのコードがこのバージョンと異なる場合は、同期するための labsui update コマンドとともにファイル名が表示されます。新しいアイテムでその依存ファイルが必要になる場合があるためです。エイリアスが @/ でない場合は、インポートが一致するように書き換えられます。ルートレイアウトに一度だけ配置するコンポーネント（toast、confirm）は、追加する行を表示します。名前を間違えた場合は候補が表示されます。たとえば、buton には button が候補として提案されます。

list と search

list は、コンポーネント、ブロック、フック（use-disclosure、use-hotkey など）、ヘルパー（utils、theme など）をすべて表示します。フックとヘルパーは、それらをインポートするコンポーネントと一緒に追加されます。単独で使うには、名前を指定して追加してください。

search は、まず名前、次にアイテムがエクスポートする内容、最後に説明を基準に順位付けします。また、すべての単語が一致する必要があります。

labsui search useModal         # finds dialog
labsui search toast promise    # finds toast
labsui search --kind hook      # every hook

view

ターミナルを離れずに、アイテムを使ったコードを書く前に必要な情報をすべて確認できます。

• 各エクスポートの正確な props と型を、コンポーネントのソースから読み取って表示します。
• 使用例の行と、ドキュメントにある完全なサンプルを表示します。
• 追加されるファイルと、インストールされる npm パッケージを表示します。
• ルートレイアウトにマウントするものがあれば表示します。

サンプル内のインポートには、設定したエイリアスが使われます。--source を指定すると、ファイル自体も表示されます。

update と diff

コンポーネントは自分で編集できるため、更新によって変更が黙って取り消されることはありません。labsui.json には各項目を書き込んだ labsui のバージョンが記録され、labsui update（または labsui update dialog）はそのバージョンをベースとして使用します。

• 一度も編集していないファイルは置き換えられます。
• 編集済みのファイルは3方向マージされ、自分の変更とこのバージョンの変更の両方が反映されます。
• 同じ行を両方が変更した場合、ファイルに <<<<<<< yours ／ >>>>>>> labsui マーカーが追加され、update に一覧表示されます。解決するまで labsui doctor は失敗します。
• 更新対象の項目が新たに必要とする依存関係が追加されます。

ベースは、すべてのリリースのファイルを保持する JSR から取得されます。オフラインの場合、ホスト型レジストリを使用している場合、またはバージョンが記録される前に項目をインストールした場合、編集済みのファイルはそのまま残されます。labsui diff は、このバージョンと異なるインストール済み項目と、同じベースから各ファイルを変更したのが誰か（labsUI のみ（update で置き換え）、自分のみ（update で維持）、両方（update でマージ））を一覧表示します。また、空行またはインデントのみが異なるファイルにも印が付けられます。labsui diff dialog は、このバージョンのファイルから自分のファイルへのパッチを表示するか、dialog がインストールされていないことを示します。

doctor

セットアップを確認し、問題ごとに修正方法を表示します。React 19 と Tailwind v4、パスエイリアスと labsui.json、スタイルシートのインポート、MotionProvider とテーマスクリプト、インストール済みの場合の <Toaster /> と <Confirmer /> のマウント、不足している npm パッケージ、インストール済みのコンポーネントがインポートしているもののプロジェクトに存在しないファイルを確認します。また、このバージョン、自分の編集内容、または古いインストール状態と異なるインストール済み項目も一覧表示します。問題がある場合は終了コード 1 で終了するため、CI でも実行できます。

フレームワークの慣例ではなく、コードを読み取ります。どの React アプリでも同じように動作します。

コーディングエージェント

MCP サーバー

labsui mcp は、Model Context Protocol に対応するあらゆるエージェントに、stdio 経由で同じコマンドを提供します。エージェントに登録してください。

{
	"mcpServers": {
		"labsui": { "command": "npx", "args": ["-y", "@kznlabs/labsui", "mcp"] }
	}
}

エージェントがワークスペースとして共有するフォルダー（MCP ルート）、またはサーバーを起動したフォルダーで動作します。エージェントが別の場所でサーバーを起動し、ワークスペースを共有しない場合は、mcp の後に "--cwd", "/path/to/app" を追加してください。--cwd が常に優先されます。Claude Desktop はその一例です。ワークスペースを共有しないため、--cwd を指定してください。Windows では、Desktop は cmd 経由で npx を起動します。

{
	"mcpServers": {
		"labsui": {
			"command": "cmd",
			"args": ["/c", "npx", "-y", "@kznlabs/labsui", "mcp", "--cwd", "C:\\path\\to\\app"]
		}
	}
}

ツール	説明
search	名前、エクスポートまたは用途で項目を検索します
view	正確な props、例、依存関係、任意のソースを確認します
add	項目をプロジェクトにインストールします（ファイルは上書きしません）
init	初回セットアップを行い、ルートレイアウトのコードを返します
diff	このバージョンから編集済みファイルへのパッチを表示します
update	項目を更新し、自分の編集内容を3方向マージします
doctor	セットアップを確認し、問題ごとに修正方法を表示します

接続時に、サーバーは labsUI のコーディングルール（インポート、トークン、モーション、マウント）も送信するため、エージェントはライブラリの想定に沿ってコードを記述できます。エージェントが起動したフォルダーで動作し、そのプロジェクト内にのみ書き込みます。

MCP を使わない場合

• labsui rules は同じコーディングルールを Markdown で表示します。エージェントが読み込むファイルに追記してください：labsui rules >> AGENTS.md。
• 任意のコマンドに --json を付けると、標準出力に1つの JSON ドキュメントを出力します。npm の出力は標準エラーに送られます。エラーは { "error": "…" } 形式で、終了コードは 1 です。

オプション

フラグ	意味
--json	標準出力に機械可読形式で出力します
--kind <kind>	search のみ：component、block、hook、helper または setup
--source	view のみ：ソースファイルを含めます
--overwrite	既存のファイルを置き換えます
--dry-run	変更内容を表示しますが、何も書き込みません
--no-install	インストールコマンドを実行せずに表示します
--registry <url>	別のレジストリ（LABSUI_REGISTRY、または設定内の registry も使用可）
--cwd <dir>	別のプロジェクトフォルダーを対象に実行します

ライセンス

MIT。すべてのコンポーネントは、labsUI 独自の手作業によるコードです。