AIチュートリアル

Open Claude UIチュートリアル：高忠実度AI会話インターフェースと本番品質のインタラクションアニメーションを構築

このチュートリアルでは、React、TypeScript、Tailwind CSSプロジェクトにopen-claude-uiを導入し、デザイントークンとテーマスタイルを設定する方法を解説します。モデル切り替え、スクロールフェードコンテナ、チャット入力欄を組み合わせ、さらにIMEガード、スクロールピン、スプリングアニメーション、アクセシブルなインタラクションモジュールを適用します。

2026年10月15日約20分で読了

Open Claude UIチュートリアル：高忠実度AI会話インターフェースと本番品質のインタラクションアニメーションを構築

プロジェクト概要

open-claude-ui は、最新のデスクトップ AI クライアント向けオープンソース UI コンポーネントライブラリ兼アニメーションエンジンです。REA リバースエンジニアリングフレームワークを基盤に、静的 AST 解析、クロージャコードの難読化解除、ランタイムトレース、ASAR リソースの分解を行い、研究成果を再利用可能な React コンポーネント、Hooks、テーマスタイル、技術ドキュメントとして整理しています。

単に画面の外観を再現するだけでなく、操作感に影響するエンジニアリングの仕組みも重点的に再現しています。たとえば、物理スプリングのパラメーター、CJK 入力メソッドの保護、スクロール端のフェード、ストリーミングメッセージのスクロール制御、カーソルアンカーによるズーム、ドラッグのデッドゾーン、Web Audio による合成通知音などです。

コンプライアンスに関する説明：プロジェクトでは、商用フォントや録音ファイルなどの専有バイナリーアセットを配布せず、システムフォントのフォールバックスタックと Web Audio API によるコードベースの効果音を使用しています。プロジェクトは MIT License を採用しており、成果物は学習、研究、エンジニアリング上の交流を目的としています。

適したプロジェクト

AI チャットクライアント、モデルコンソール、ツール呼び出し承認画面、デスクトップアシスタント、メディアビューアー、マルチエージェント協働スペースを開発している場合、このリポジトリから必要なコンポーネントを導入できます。ビジュアルトークンや複雑なインタラクションを自分で再調整する必要はありません。

Web AI アプリ：会話バブル、リッチテキスト入力ボックス、モデル切り替え、Token ダッシュボードを使用できます。
ストリーミング生成画面：スクロールピン、思考プロセスの折りたたみ、フェードマスクを使用できます。
デスクトップアプリ：Electron ウィンドウファクトリー、macOS タイトルバー、Vibrancy マテリアル方式を使用できます。
Artifacts とマルチメディアアプリ：分割ペインのドラッグ、メディアライトボックス、共有要素トランジション、iframe サンドボックスブリッジを使用できます。
アクセシブルなアプリ：WAI-ARIA の考え方に沿った Roving TabIndex フォーカス移動 Hook を使用できます。

主な機能

デザイントークンとビジュアルシステム

Surface 0 から Surface 3 までの低コントラストなサーフェス階層、テラコッタオレンジ #d97757、高 DPI ディスプレイ向けの極細ボーダー補正、システムフォントのフォールバックスタック、ボタン、パネル、バブル、入力ボックス向けの角丸マトリクスを提供します。グローバルテーマ変数とキーフレームは code-examples/cds-theme.css に集約されています。

30 個の独立したコードモジュール

リポジトリには、11 個の基礎的なアトミックコントロールと、19 個のアーキテクチャまたはインタラクションモジュールが含まれています。コンポーネントのソースコードは code-examples にあり、TypeScript の統合エクスポート入口は src/index.ts です。これらのモジュールは、ボタン、セグメント選択、入力ボックス、会話バブル、MCP 判断カード、メディアビューアー、ストリーミング Diff、デスクトップウィンドウ、マルチエージェントキャンバスなどをカバーしています。

プロダクション品質のインタラクション機構

Bouncy、Snappy、Gentle、Heavy Snap の 4 種類の物理スプリングプリセット。
スクロール領域では 7 段階の非線形 Alpha マスクを使用し、上端または下端に達しているかに応じて動的に調整。
入力ボックスでは isComposing と keyCode === 229 の二重条件により CJK 入力メソッドを保護。
ストリーミング出力では、下部 40px の許容範囲と 150ms の手動スクロール冷却時間を使用し、自動スクロールによるビューポートの奪取を防止。
マイク波形では 8% のノイズゲートしきい値と 0.7 乗の Gamma 圧縮を使用。
ドラッグとギャラリー操作には 4px のポインター移動デッドゾーンを設け、手のわずかな揺れを除外。

オフラインコンポーネントプレビュー

リポジトリには、単一ファイルのインタラクティブな Storybook docs/claude-components-storybook.html が付属しています。ローカル開発サーバーを起動しなくても、テラコッタのカラーパレット、ダークモード、ボタンのフィードバック、セグメントカプセル、スプリングアニメーション、添付ファイルタイル、コピー状態のアニメーションを確認できます。

インストールと環境準備

技術スタックの確認

リポジトリの記載によると、プロジェクトには次の環境が推奨されます。

React 18 以上。
TypeScript 5.5 以上。
Tailwind CSS 3.4 以上。
Framer Motion 11 以上。

README には、特定のパッケージマネージャー向けのインストールコマンドは記載されていません。開始前に、作業環境、Git 依存関係、またはパッケージ公開方式に従って、プロジェクトから open-claude-ui パスへアクセスできるようにし、上記のピア技術スタックが設定済みであることを確認してください。

まずオフライン Storybook を確認する

リポジトリのソースコードを取得済みであれば、プレビューファイルを直接開けます。

open docs/claude-components-storybook.html

この手順により、業務プロジェクトを変更せずに、コンポーネントの見た目、ダークテーマ、インタラクションアニメーションが要件に合っているかを確認できます。

テーマスタイルの設定

グローバル CSS の読み込み

アプリケーションのグローバルスタイル入口で CDS テーマファイルを読み込みます。CSS カスタムプロパティとコンポーネントに必要なキーフレームが含まれています。

@import "open-claude-ui/code-examples/cds-theme.css";

このテーマは、サーフェスカラー、テラコッタのブランドカラー、ボーダー、シャドウ、アニメーションの基盤を提供します。コンポーネント間の一貫性を保つため、既存の CSS 変数を優先して使用し、各コンポーネントで色を繰り返しハードコードしないことを推奨します。

Tailwind 設定の拡張

プロジェクトの tailwind.config.js で、リポジトリが提供するテーマ拡張を読み込みます。

const cdsTheme = require("open-claude-ui/code-examples/tailwind.config.js");

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/open-claude-ui/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {
      ...cdsTheme.theme.extend
    }
  }
};

content 配列には、アプリケーションのソースコードと、open-claude-ui 内で Tailwind クラス名を含むファイルを含める必要があります。そうしないと、プロダクションビルド時にコンポーネントが使用するユーティリティクラスが生成されない可能性があります。

基本的な使い方：モデル制御とチャット入力エリアの構築

次の例では、3 つのコアモジュールを組み合わせています。

ScrollFadeContainer：スクロール可能な領域に上下端のフェードを追加します。
ModelSwitcherWithTokenGauge：モデル選択、Extended Thinking の状態、Token 予算を表示します。
ChatComposer：メッセージ入力と送信コールバックを提供します。

import React, { useState } from 'react';
import {
  ChatComposer,
  ModelSwitcherWithTokenGauge,
  ScrollFadeContainer
} from 'open-claude-ui';

export function App() {
  const [model, setModel] = useState<
    'sonnet-3.5' | 'haiku-3.5' | 'opus-3'
  >('sonnet-3.5');
  const [thinking, setThinking] = useState(true);

  return (
    <div className="flex h-screen w-full bg-[var(--cds-surface-1)]">
      <ScrollFadeContainer
        axis="vertical"
        fadeSize={32}
        className="flex-1 p-6"
      >
        <div className="mx-auto max-w-3xl space-y-4">
          <ModelSwitcherWithTokenGauge
            currentModel={model}
            onModelChange={setModel}
            extendedThinking={thinking}
            onThinkingChange={setThinking}
            tokenBudget={{
              inputTokens: 12400,
              outputTokens: 3200,
              cacheReadTokens: 48000,
              cacheWriteTokens: 16000,
              maxContextWindow: 200000
            }}
          />

          <ChatComposer
            onSend={(text) => console.log('Send message:', text)}
          />
        </div>
      </ScrollFadeContainer>
    </div>
  );
}

状態管理を理解する

currentModel と extendedThinking はどちらもアプリケーション層で管理されるため、モデル切り替えを実際のモデルリクエスト設定と同期できます。例の tokenBudget では、入力、出力、キャッシュ読み取り、キャッシュ書き込み、最大コンテキストウィンドウをそれぞれダッシュボードに渡しています。

例では ChatComposer の onSend はログを出力するだけです。実際のプロジェクトに接続する場合は、このコールバックで会話サービスを呼び出し、メッセージリストを更新し、ストリーミング応答の状態を開始できます。

よく使うコンポーネントの選択ガイド

基本コントロール

CdsButton：XS、SM、MD、LG の 4 サイズと、Primary、Secondary、Ghost、Outline、Danger の 5 バリエーションを提供します。
SegmentedControl：モード切り替えに使用し、純粋な幾何学的位置合わせと Framer Motion の layoutId アニメーション方式に対応します。
StatusIndicators：テラコッタのブリージングライト、リアルタイムアクティビティパルス、思考中の 3 点アニメーション、スケルトンの光沢アニメーションを含みます。
ConfirmationDialog：通常操作または危険な操作の確認に使用し、ぼかしマスクとキーボードフォーカス制約を備えています。
AttachmentCard：デスクトップタイルと入力ボックス内のインラインカプセルという 2 種類の添付ファイル表示方式に対応します。

会話とツール呼び出し

ChatMessageBubbles：ユーザーバブルとアシスタントの透明なタイポグラフィを区別します。
ThinkingAccordion：折りたたみ可能な思考プロセスを表示し、生成中は強制的に展開した状態を維持できます。
RichComposerWithMentions：/ コマンド、@ コンテキスト、Token 予測が必要な入力端末に適しています。
McpToolDecisionCard：ツール認証フローに使用し、pending_approval、running、success、error の各状態をカバーします。

メディア、コード、Artifacts

MediaLightboxViewer：75vw のギャラリートラック、カーソルアンカーによる Pan/Zoom、ドラッグのデッドゾーン、Ctrl＋ホイールズームを提供します。
ArtifactsSplitPaneResizer：2 ペインのサイズ変更、端の折りたたみ、ダブルクリックによる 50/50 スナップ、iframe のポインターイベント干渉を処理します。
EpitaxyIframeBridge：Origin 検証と分離された postMessage RPC プロトコルを通じて、プレビューサンドボックスに接続します。
StreamingDiffViewer：増分ストリーミング追加に対応し、統合 Diff と分割 Diff の 2 種類のモードを提供します。
CodeBlock：コードコンテナと 2.5 秒で減衰するコピー状態を提供します。

高度な実践

中日韓入力メソッドを保護する

チャット入力欄でキーボードイベントを独自に拡張する必要がある場合は、入力メソッドの合成保護を必ず維持してください。ユーザーがピンインや仮名の候補ウィンドウで Enter キーを押したとき、メッセージを送信してはいけません。プロジェクトでは二重判定を採用しています：

const composing =
  event.nativeEvent.isComposing || event.keyCode === 229;

if (event.key === 'Enter' && !composing) {
  // メッセージを送信
}

Escape キーについても、入力メソッドの候補レイヤーを閉じる際にイベントがバブリングを続け、誤ってダイアログウィンドウまで閉じてしまわないようにする必要があります。

ストリーミング出力によるスクロール位置の奪取を防ぐ

継続的に追加される Token の管理には、useClaudeScrollPinning を使用できます。主な戦略には、40px の下部許容範囲、150ms の手動スクロール冷却時間、35vh の弾性バッファが含まれます。ユーザーが下部付近にいる場合は、画面が出力に追従できます。一方、ユーザーが履歴メッセージを確認するために上へスクロールしたら、自動スクロールですぐにビューポートを下部へ戻してはいけません。

アニメーションプリセットを統一して使用する

プロジェクトでは、ClaudeMotionPresets.ts に調整済みの4種類のスプリング設定を用意しています。新しいコンポーネントを開発する際は、アニメーションごとに剛性や減衰を自由に設定するのではなく、Bouncy、Snappy、Gentle、Heavy Snap を優先的に再利用してください。これにより、ボタン、パネル、ドラッグ吸着、共有要素のトランジションで一貫した物理表現を保てます。

iframe の分割ペインドラッグを正しく処理する

分割バーを iframe 上でドラッグすると、iframe がポインターイベントを奪い、ドラッグが中断されることがあります。ArtifactsSplitPaneResizer はドラッグ開始時にイベントの捕捉を防ぐ仕組みを有効にし、4px の移動デッドゾーン、端の制約、ダブルクリックによる中央吸着を組み合わせます。アプリに Artifacts プレビューが含まれる場合は、分割バー自身のマウスイベントだけを監視するのではなく、このモジュールを優先的に再利用してください。

キーボードユーザーの完全なナビゲーションを維持する

useClaudeRovingFocus は、1次元または2次元の方向キーによるナビゲーション、Home と End による境界への移動、RTL のミラー反転をサポートします。モデルグリッド、添付ファイル一覧、ツールカードの配列を構築する際は、正しい ARIA セマンティクスと可視フォーカス状態も同時に維持してください。

モデルのレート制限とサービス異常を処理する

useRateLimitBackoff は 429 と 503 のレスポンスを対象に、切り捨て指数バックオフ、ジッターの注入、3回の自動サーキットブレーカー復旧機構を提供します。モデルリクエスト層に適していますが、いつ再試行するか、いつエラーを表示するか、いつユーザーによる手動復旧を許可するかは、各自の API レスポンス構造に応じてアプリケーション側で判断する必要があります。

技術マニュアルで深く学ぶ

コンポーネントのソースコードに加えて、リポジトリには3,000行を超えるデザインシステム技術マニュアルも用意されています。次の順序で読むことをおすすめします：

まず、デザイン哲学、Surface のカラースケール、角丸マトリクス、ヘアラインボーダーのルールを読みます。
次に、ボタン、セグメントコントロール、状態インジケーター、確認ダイアログを学びます。
続いて、セッション入力、CJK ガード、モデル切り替え、MCP ステートマシンを研究します。
複雑なアニメーションが必要になったら、スプリングパラメータ、環境光、スクロールマスクを確認します。
デスクトップアプリ、メディアツール、コラボレーションスペースを開発する際は、対応するシステムアーキテクチャの章を読みます。

完全版のマニュアルは docs/Claude Design System (CDS).md にあります。プロジェクトのリバースエンジニアリング作業は REA を利用して行われています。

AI Coding Agent と協働する

リポジトリには AGENTS.md、CLAUDE.md、.cursorrules、Copilot 用の指示ファイルが用意されています。Cursor、Claude Code、GitHub Copilot などのツールで新しいインターフェースを生成する際は、リポジトリ既存のトークン、スプリングプリセット、ボーダーの原則、入力メソッド保護のルールに従うよう Agent に指示できます。

プロンプト例：このリポジトリの AGENTS.md の規約に厳密に従い、CDS のテラコッタデザイントークンと ClaudeMotionPresets のスプリングプリセットを使用して、現在のコンポーネントを構築してください。

まとめ

open-claude-ui は、AI クライアントのビジュアルトークン、セッションコントロール、アニメーション物理、マルチメディアインタラクション、デスクトップアーキテクチャを再利用可能なモジュールとして整理しています。最も確実な導入方法は、まずオフラインの Storybook で表示を確認し、次にテーマ CSS と Tailwind の拡張を導入し、最後にチャット入力欄、モデル切り替え、スクロールコンテナなどの中核コンポーネントから組み合わせていくことです。ストリーミング出力、CJK 入力、iframe ドラッグ、キーボードナビゲーションなどの複雑な場面では、表面的なスタイルだけをコピーするのではなく、リポジトリに既存の Hooks とステートマシンをできる限り再利用してください。