design-prototype

デザインプロトタイプ

HTML ファイル 1 つで、ダブルクリックして開くだけで完全に操作できます。実際のデザインシステム（@lobehub/ui 6.x のコンポーネント、コンパイル済みの style.css、--lobe-* テーマトークン。バージョンはこのリポジトリの node_modules にあるものと完全に一致）でレンダリングされます。一方、ソースは本番環境向けの React（import { Block } from '@lobehub/ui'、createStaticStyles(({ css, cssVar }) => …)、フック、memo）のままです。本番環境への移行で必要なのは、ほとんどの場合「ファイルに分割すること」であり、「書き直すこと」ではありません。

プロトタイプのコードは手早く雑に書いてもかまいません（ファイル 1 つ、i18n なし、データはインラインで記述）。ただし、インタラクションは完成させてください。プロトタイプで重要なのはコードのスタイルではなく、状態、遷移、操作の手がかりです。

仕組み

one-time (~2s, cached):   scripts/build-runtime.sh  →  lobe-prototype-runtime.js (IIFE global)
                                                       + lobe-prototype-runtime.css
                                                       + vendored babel.min.js
per prototype (no build): single HTML  =  <link css> + <script runtime> + babel-standalone
                          + <script type="text/babel"> with production-style React

• ランタイムはリポジトリ内の node_modules から react、react-dom/client、@lobehub/ui の全名前空間、lucide-react、motion をバンドルします。そのため、トークン、コンポーネント、バージョンは本番環境と一致し、react／emotion／theme-scope は構成上シングルトンになります。
• entry.mjs では @lobehub/ui/theme.css、global.css、style.css（アプリが src/layout/GlobalProvider/AppTheme.tsx で読み込むものと同じ 3 つ）もインポートします。esbuild はこれらを lobe-prototype-runtime.css として出力し、テンプレートの <head> から読み込みます。
• 3 行の window.require シムと babel の transform-modules-commonjs により、プロトタイプで実際の import 文を維持できます。
• テーマ設定にはプロバイダーではなく CSS 属性を使います。テンプレートの head スクリプトが prefers-color-scheme から（また変更時にも）setLobeTheme({ appearance }) を呼び出すため、初回描画前から OS の設定に合わせてライト／ダークが切り替わります。テーマを固定するには setLobeTheme({ appearance: 'dark' }) を使うか、一部に適用する場合は <ThemeScope appearance="dark"> を使います。React ツリーは、アプリの AppTheme と同様に <ConfigProvider motion={motion}>（Button、Drawer、Modal などのモーション、フォント、フォーカスリング、ポップアップ用ポータルホストを提供）と <ToastHost /> でラップします。

⚠️ 純粋な CDN 方式（esm.sh の import maps）は再び試さないでください。すでに試して却下されています。esm.sh では依存チェーンに沿って CJS の名前付きエクスポート解析が次々と失敗し、さらに ?bundle によりバージョン指定のない react-is が混入して 404 になりました。本番環境のバージョンと完全に一致させるには、リポジトリ内の node_modules からバンドルするしかありません。

クイックスタート

1. ランタイムをプロトタイプのディレクトリにビルドします（任意のディレクトリを使用できます。/tmp でもかまいません）。

   bash .agents/skills/design-prototype/scripts/build-runtime.sh /tmp/my-proto
   

   lobe-prototype-runtime.{js,css} と babel.min.js がすでにあり、デザインシステムのバージョンが更新されていない場合はスキップしてください。初回実行時に babel.min.js を unpkg からダウンロードします（バージョン固定済み）。以降の実行では再利用されます。

2. references/template.html を同じディレクトリにコピーして名前を変更し、サンプルの App を実際の画面に置き換えます。ランタイムのシムブロックには手を加えないでください。

3. 開きます（open /tmp/my-proto/xxx.html）。サーバーもビルドも不要です。

提出前の確認

ヘッドレス環境でレンダリングされ、コンソールエラーが 0 件であることを確認します（このリポジトリの e2e Playwright が使えます）。

// node /tmp/check.mjs   — adjust paths
import { chromium } from '<repo>/e2e/node_modules/playwright/index.mjs';
const b = await chromium.launch();
const p = await b.newPage();
const errs = [];
p.on('pageerror', (e) => errs.push(String(e)));
await p.goto('file:///tmp/my-proto/xxx.html');
await p.waitForSelector('#root *', { timeout: 30000 });
await p.screenshot({ path: '/tmp/proto.png' }); // Read the screenshot yourself
console.log('errors:', errs);
await b.close();

その後、スクリーンショットを確認してください。プロトタイプは視覚的な成果物です。実際に確認せずに提出しないでください。ライトとダーク（prefers-color-scheme をエミュレート）に加え、その画面にモバイル向けの表示がある場合は狭いビューポートでも確認します。

ランタイムに含まれるもの（自由に拡張できます）

assets/entry.mjs を参照してください。ここが唯一の信頼できる情報源です。現在は次のものが含まれています。

• @lobehub/ui：完全な名前空間。すべてのコンポーネント（Button、Input、Modal、 createModal、confirmModal、Table、Switch、Checkbox、Radio、Badge、 Progress、Slider、Steps、Divider、DropdownMenu、Accordion、Collapsible、 Spin、Skeleton、DraggablePanel、FloatingSheet、…）に加えて、toast / ToastHost、 MotionProvider、setLobeTheme、ThemeScope、useThemeMode、useTheme、および スタイリング API の createStaticStyles、cssVar、cx、css、keyframes、responsive、 useResponsive
• @lobehub/icons：Amp、ClaudeCode、Codex、HermesAgent、OpenClaw、OpenCode
• lucide-react、motion/react、motion/react-m、react、react/jsx-runtime、 react-dom、react-dom/client：完全な名前空間

含まれていないもの：@lobehub/ui/form、@lobehub/ui/pro-table、@lobehub/ui/chat および その他のサブパスです。import * as x from '@lobehub/ui/<sub>' と '@lobehub/ui/<sub>': x のエントリーを追加して再ビルドしてください（約2秒）。サイズは約17MBのJS＋0.3MBのCSSです（ディスクから読み込む場合は問題ありません）。

v6相当のものを選ぶ

• フィードバック：toast.success(…) ＋ <ToastHost />。ダイアログ：Modal、createModal、 confirmModal。
• メニュー：DropdownMenu items={…}（クリックで開きます）。コンテキストメニュー：ContextMenuTrigger。
• レイアウト：Flexbox horizontal gap={…} / Center / Grid。Space はありません。
• 開閉表示：複数のセクションには Accordion、1つの領域には Collapsible。
• Badge、Checkbox、Divider、Progress、Radio、Slider、Steps、Switch、 Table（columns / dataSource / rowSelection）はルートからエクスポートされています。
• 名前がわからない場合は推測せず、node_modules/@lobehub/ui/es/index.d.mts を確認してください。不明なインポートはビルドエラーにならず、実行時に undefined になります。

注意点

• 本番と同様に、createStaticStyles ＋ cssVar.* でスタイルを指定してください。Emotion ベースで呼び出し時に挿入されるため、ビルドは不要です。トークンは var(--lobe-*) に解決され、テーマに応じて切り替わります。ライト／ダークの色をハードコードしないでください。
• コンポーネントのスタイルはカスケードレイヤー（lobe-base、lobe-popup、lobe-ui）にあります。そのため、プロトタイプの <style> 内にあるレイヤー外のCSSが優先されます。button { … } のようなグローバルセレクターではなく、className / style / classNames / styles のスロットプロパティで上書きしてください。
• lobe-prototype-runtime.css への <link> は残してください。これがないとコンポーネントはスタイルなしで表示され、--lobe-* トークンも未定義になります。
• babel は生の UMD ファイルのままにしてください（unpkg/jsdelivr）。esm.sh はこれを ESM に書き換えるため、通常の <script src> では export によってエラーになります。
• require shim は、インポート対象がランタイムに含まれていない場合、モジュール名とともにエラーをスローします。これはテンプレートの不具合ではなく、「entry.mjs に追加して再ビルドする」ための合図です。
• Text type が受け付けるのは secondary|success|warning|danger|info のみです。Tag color に primary はありません（DESIGN.md「Applying tokens in components」を参照）。

デザイン基準（本番の画面と同じ）

プロトタイプも画面の一部です。ux のチェックリストは、プロトタイプが 実演する内容 にも適用されます。

• 少なくとも1つ、通常とは異なる状態（空／読み込み中／エラー／処理中）を表示してください。できればテンプレートのように、状態を切り替えるストリップの背後に配置します。通常状態しかないプロトタイプではデザインの仕様が不十分になり、状態の不足を暗黙に容認してしまいます。
• アプリの画面上の規約を再利用してください。サイドパネルには DraggablePanel を使います（折りたたみとドラッグによるサイズ変更が標準で使えます）。読み込み表示は ux スキルのフィードバック §4.1 のシナリオ表に従います（Skeleton / Spin。variant="network" はAI関連の作業に限ります）。モーダルには createModal スタイルのフローを使います。
• 実装しない操作要素を表示しないでください（ズーム機能がないのに cursor: zoom-in を付ける、キー操作がないのにキーキャップ風のチップを表示するなど）。インタラクティブな プロトタイプでは、機能しない操作要素は仕様上の不具合です。
• 提出前に、プロトタイプに対して ux の Quick review を実施してください。意図的に対象外とした内容にはHTMLコメントで注記し、実装者が設計上の判断ではなく、対象から外したものだとわかるようにしてください。