nudg

nudg は、コンポーネントの隣に置いた小さな JSON ファイルで UI インタラクションを記述します。状態、その間を移り変わるイベント、そして遷移時のモーションを定義します。AI コーディングツールがファイルを編集し、nudg が編集内容を検証して、小さなランタイムがアプリ内で再生します。

楽譜のようなものと考えてください

.nudg.json ファイルは楽譜です	どのパーツが、どの状態で、どのように動くかを記述します
ランタイムは演奏のルールです	TypeScript、Swift、Kotlin が同じ楽譜を同じように演奏し、共通の適合性テストスイートがそれを検証します
AIは編曲者です	「もっと弾むように」という変更は、曲全体ではなく、ひとつの記号を変えます
あなたはディレクターです	変更前と変更後を並べて見て、よりよいほうを選びます

「もっと弾むように」と伝え、変更前後を見て、判断する

   "animate": {
-    "knob.x": { "spring": { "duration": 0.35, "bounce": 0.25 } },
+    "knob.x": { "spring": { "duration": 0.35, "bounce": 0.6 } },

日常の言葉は単一のフィールドに対応します。もっと弾むようには bounce、もっとゆっくりは duration です。コンポーネントのコードは変わりません。

また、指示しなくても変更内容を表示します。nudg_compare は同じタップで両方のバージョンを再生し、まず、違いに気づくかどうかを示します（「明確な変化：knob.x が最大2.1単位異なる位置まで動き、落ち着くのが0.23秒遅くなります」、または 「人が気づくほどの変化はありません。まず誇張したバージョンを見てみましょう」）。次に、変更前と変更後の実際のフレームを並べて表示します。Web アプリではブラウザー上で、SwiftUI と Compose ではアプリ独自のビュー上で確認できます。見比べて判断してください。

ひとつのファイルにインタラクション全体を記述

上のトグルの完全な例です。

{
  "nudg": "1.1",
  "targets": ["knob", "track"],
  "values": { "knob.x": 0, "track.color": "#D1D5DB" },
  "animate": {
    "knob.x": { "spring": { "duration": 0.35, "bounce": 0.25 } },
    "track.color": { "tween": { "duration": 0.2, "ease": "out" } }
  },
  "initial": "off",
  "states": {
    "off": { "when": { "track.tap": "on" } },
    "on": {
      "set": { "knob.x": 20, "track.color": "#4ADE80" },
      "when": { "track.tap": "off" }
    }
  }
}

• 状態は位置を示します。 on では、ノブは20の位置にあり、トラックは緑色です。
• animate は動かし方を示します。 ノブはスプリングで移動し、色はトゥイーンします。
• when は状態間で何が変わるかを示します。 トラックをタップします。

アニメーションの途中で中断しても、スプリングは速度を保ったまま新しい方向へ動きます。追加の記述は不要です。

コンポーネントでは名前でパーツをバインドし、nudg がそのファイルに基づいて動かします。

import { useNudg } from "@nudg/core/react";
import toggle from "./toggle.nudg.json";

function Toggle() {
  const { bind } = useNudg(toggle);
  return (
    <button ref={bind("track")} aria-label="Wi-Fi" style={{ position: "relative", width: 52, height: 32, padding: 0, border: 0, borderRadius: 16 }}>
      <span ref={bind("knob")} style={{ position: "absolute", top: 4, left: 4, width: 24, height: 24, borderRadius: "50%", background: "#fff" }} />
    </button>
  );
}

見た目（サイズ、形、ノブの初期位置）はあなたが決め、ファイルが動きを制御します。値は要素のスタイルに直接反映されるため、動いている間にコンポーネントが再レンダリングされることはありません。Vite を使う場合は、プラグインに @nudg/core/vite の nudg() を追加します。ファイルはビルド時にコンパイルされ、エラーのあるファイルがあるとビルドは失敗します。nudg の追加サイズは約14 kB gzipped で、28 kB ではありません。React を使っていない場合は、DOM アダプターで data-nudg="knob" 属性をバインドします。詳しくは「nudg の使い方」をご覧ください。

ひとつのインポートでネイティブな操作感を実現

nudg は各プラットフォーム独自のモーションを、同じ形式のライブラリとして提供します。SwiftUI のスプリングと、公開値からコピーした Material 3 のモーショントークンを収録しています。standard、quick、playful などの共通名を使っているため、iOS の操作感から Android の操作感へ、1行の差分で切り替えられます。

-  "import": ["./motion/apple.nudg.json"],
+  "import": ["./motion/material-expressive.nudg.json"],
   "animate": { "knob.x": "standard", "track.color": "fade" }

すべての名前と値については、プラットフォームのモーションをご覧ください。

UI の言葉を標準的なインタラクションに

通常、duration: 0.35 や bounce: 0.2 のように指定することはありません。「これを FAB にして」「タブを使って」「ボトムシートとして表示して」「行をスワイプして削除できるようにして」「トーストをもっと iOS らしくして」といった言葉で伝えます。nudg は、こうした言葉を、その場限りのコードの推測ではなく、再利用可能なインタラクションパターンに対応させるために作られています。

方向性はモバイルファーストです。fab、tab-bar、bottom-sheet、toast / snackbar、swipe-row、carousel、switch、slider、dialog、list、grid、voice-chat、video-call、camera、music-player、video-player といったパターンには、想定されるパーツ、状態、ジェスチャー、プラットフォーム固有のモーションが備わっている必要があります。マークアップ、レイアウト、デバイス API は引き続きホストが担当し、nudg は AI が編集でき、人が評価できるインタラクションの振る舞いを提供します。

human UI words
  -> semantic pattern
  -> states, events, targets and motion
  -> compare / observe

はじめに

npm install @nudg/core
npx nudg recipe toggle --source > toggle.nudg.json   # a validated starter; `npx nudg recipe` lists them all

MCP 経由で nudg のツールを AI エージェントに渡します。これは Claude Code 用ですが、同じコマンドはどの MCP クライアントでも実行できます。

claude mcp add nudg -- npx -y @nudg/core mcp

または、CLI を使ってファイルを直接操作できます。

npx nudg validate toggle.nudg.json
npx nudg simulate toggle.nudg.json --send [email protected]

Node 22.4 以降が必要です。すべてのコマンドとオプションについては、nudg の使い方をご覧ください。

自然言語による UI はレシピから始まる

nudg は、AI に一から作り直させるのではなく、よく知られた UI 用語をバージョン管理されたインタラクション契約に対応させます。レシピには、想定されるパーツ、状態、イベント、連続的な入力、ホスト側の責任、モーション、既知のフォーマット上の不足点、検証済みのスターターが記載されています。

npx nudg recipe "video chat"
npx nudg recipe sheet --json
npx nudg recipe toggle --source > toggle.nudg.json

カタログには、スイッチ、タブ、シートから、ボイスチャット、カメラ、メディアプレーヤーまで、リリース済みのすべてのサンプルが含まれています。メニュー、スピナー、画面遷移など、現在のフォーマットでは表現できないパターンも、スターターなしで掲載されています。これにより、AI は推測で実装するのではなく、どの部分をホストが担うかを明示できます。レシピは実行時には通常の nudg ドキュメントのままです。コアをコンポーネント固有にすることなく、生成をガイドします。

シンプルなケースなら 1 行で

押下、ホバー、切り替え、トーストにはファイルは必要ありません。プリセットは、そのまま使える nudg ドキュメントです。

import { useNudg, presets } from "@nudg/core/react";

const { bind } = useNudg(presets.press({ scale: 0.96 }));
<button ref={bind("button")}>Save</button>

import { playDoc } from "@nudg/core/dom";
import { presets } from "@nudg/core";

playDoc(presets.toast({ duration: 3 }), document.querySelector(".toast"));

オプションだけでは足りない場合は、nudg preset press > press.nudg.json で同じドキュメントをファイルに書き出せます。あとは自分で編集することも、AI に編集させることもできます。

AI が自分の作業をチェック

エージェントはアニメーションを見られないため、nudg は何が起きたかをテキストと画像で伝えます。

ツール	エージェントに渡される情報
recipe	トグル、シート、ビデオチャットなど、人が使う UI 用語に対応する標準的なインタラクション契約と、検証済みのスターター。
validate	各問題の安定したコード、JSON ポインター、修正方法を示すヒント。
simulate	イベントのリストに対する時間経過ごとの状態と値。「つまみは 20.57 まで行き過ぎ、0.84 s から静止します」。
plot	下図のような、すべてのプロパティのモーショングラフ。
render	ヘッドレスブラウザーでキャプチャした、コンポーネントの実際のフレーム。
compare	同じタップをした前後の比較。人が違いに気づくかどうかに加え、両方を並べて表示し、スローモーションで再生するページも提供します。実行中のアプリを指定すると、ブラウザーで開きます。
critique	モーションが有効かどうかだけでなく、適切かどうかも評価します。遅すぎる、押下時のフィードバックが遅い、見えない、フェードが弾む、終了が遅い、タイムアウトが短い、Escape に対応していない、といった点を指摘します。それぞれに修正方法と情報源が示されます。
observe	ホスト側の実際の状態。実際のページをタップし、各フレームを計測してファイルと照合します。「要素は 0.18 s でページ外に出ました。リリースは一度も表示されません」。

サンプルサイトのプレイグラウンドにも同じ判定ビューがあり、リアルタイムで確認できます。元と比較では元の動作と編集内容を並べて再生し、どちらかをタップすると両方に反映されます。スローモーションは選択式で、入力中も判定が更新されます。

_{動作中にもう一度タップしたトグルの nudg plot 出力。バネは再始動せず、滑らかに向きを変えます。}

仕組み

nudg のコアは描画を一切行いません。イベントを受け取り、プロパティ値を出力し、薄いアダプターがそれらをビューに適用します。

 your app (web, React Native, SwiftUI, Compose, ...)
   │  events: tap, drag, hover, focus, app events
   ▼
 ┌──────────────── nudg core ────────────────┐
 │  states + clock + motion math (headless)   │
 └────────────────────────────────────────────┘
   │  values: knob.x = 18.3, track.color = #4ADE80
   ▼
 adapter sets them on your views

• 決定論的です。 同じタイミングで同じイベントを与えると、常に同じ値が得られるため、ほかのコードと同じようにモーションをテストできます。
• ポータブルです。 プロパティを設定してイベントを送信できるプラットフォームなら、どこでも nudg を実行できます。仕様と、言語に依存しない適合性テストスイートが、単一の実装ではなく動作を定義します。
• JSON だけです。 新しい構文もスタジオも不要で、差分を読みやすく保てます。現在のJSON Schemaによりエディターで補完が使え、パッケージは最新バージョンを @nudg/core/schema.json としてエクスポートします。

理由

インタラクティブなアニメーションは、通常、専用スタジオで作成するバイナリファイルに保存されます。AI はそれらを編集できず、レビュー担当者は差分を読めず、小さな変更のたびにそのツールを使わなければなりません。nudg では、インタラクションをテキストとしてリポジトリに保存できるため、普段 AI コーディングツールを使って作業している場所で扱えます。設計について詳しくはこちら。

ステータス

安定版です。 バージョン 1.5（フォーマット 1.1）はnpm で公開中です。すべてのセマンティックレシピのスターター、タップ、ホバー、ドラッグ、スローとグライド、ピンチ、長押しとダブルタップ、キーボードイベント、スクロール方向と入力しきい値、一時停止可能なタイマー、連続的なアプリおよびスクロール入力、計測されたレイアウト、エントリーキーフレーム、ループ、段階的な遅延、画面遷移、宣言型ホストインターフェース、モーションの軽減、型安全なホスト名（nudg generate）、すべてのプラットフォームで使える単一の「モーション終了」コールバック（onSettle）、ネイティブでのスクリーンリーダーによる起動と調整、フラッシュのないサーバーレンダリング、DOM、React（MUI、Radix、shadcn/ui とのブリッジを含む）、React Native、SwiftUI、Jetpack Compose 用のアダプターを備えています。1.x の間はファイルと API に機能が追加されるだけで、互換性を損なう変更は 2.0 まで行いません。変更履歴をご覧ください。

ロードマップでは、コンポーネントのインタラクションから画面やフロー、ネイティブアダプター、さらに単体コンテンツの探索まで、開発の優先事項と各段階の状況を追跡しています。モバイルファーストのセマンティックパターンは、この進展を基盤に構築されています。

ドキュメント

• nudg フォーマット：文法の全容です。
• nudg の使用方法：CLI、MCP サーバー、アダプター（DOM、React、React Native、SwiftUI、Compose）、プラットフォームのモーションについて説明します。
• 設計：原則、対象範囲、決定事項、未解決の問題です。
• ロードマップ：開発計画、現在の状況、完了基準です。
• 対応範囲：フォーマットで表現できる内容を、トリガー、応答、構造ごとに示し、実行可能な環境を説明します。
• AI エージェント向けガイド：フォーマットを 1 ページで説明します。編集契約には、AI ツールが前提にできるすべての事項が記載されています。
• 開発ログ：nudg の開発中に直面した問題と、その解決方法です。

すでに使っているコンポーネントと組み合わせる

nudg は、すでにあるコンポーネントにモーションを加えるもので、コンポーネントを置き換えるものではありません。shadcn/ui、Radix、Headless UI、React Aria では、useNudg(file, { watch: true }) がコンポーネントの表示する状態（data-state、aria-*）を追跡します。MUI、Ant Design、React Bootstrap では、nudgTransition(file) をトランジションスロットに接続できます。ライブラリが動作とアクセシビリティを担い、ファイルが表現のニュアンスを担います。AI で調整でき、あなた自身で評価できます。nudg の使用方法をご覧ください。

nudg の改善にご協力ください

nudg の目標は、モーションの変更を 1 ラウンドで済ませることです。ひと言伝えれば、変更前と変更後を確認して評価できます。それが実現できているかどうかは、お使いのマシン上で、マシンから外部に送信されることのないローカルログによって測定されます。nudg をお使いの場合は、時々共有してください。

npx @nudg/core log --share

送信される内容を正確に表示します（変更あたりのラウンド数、判定、ツール呼び出しの件数のみ。ファイル名、パス、コードは含まれません）。また、確認して送信できる GitHub Issue を開きます。

貢献

Issue とプルリクエストを歓迎します。nudg はコーディングの前に設計されるため、バグ修正以外の内容については、実装したい操作について話し合うため、まず Issue を作成してください。CONTRIBUTING.md をご覧ください。

ライセンス

MIT