UI Atlasの使い方

1. 登録名・用語で検索

   日本語名、英語の正式名、別名、関連名、用途・配置語を入力します。文章の意味推測ではなく、登録語の決定的な照合です。

2. カードから詳細を開く

   正式名、通称、非同義の関連UI、使う場面、避ける場面、状態、キーボード操作、ARIA、プラットフォーム差を確認します。

3. 形式を選んでコードを取得

   React + Tailwind、HTML + CSS、React Native、Compose、SwiftUI、WinUI、Flutterを切り替え、対象プロジェクトへ統合します。

必要環境はNode.js 22以降です。グローバルインストールせず、公開版を固定して実行できます。画面設計では最初にplatformsで3択と次の質問を取得します。

node --version
npx -y ui-atlas@3.0.1 platforms
npx -y ui-atlas@3.0.1 search "Side Sheet" --limit 5
npx -y ui-atlas@3.0.1 show drawer
npx -y ui-atlas@3.0.1 code drawer react
npx -y ui-atlas@3.0.1 stats

プロジェクトへ1部品を追加

npx -y ui-atlas@3.0.1 add drawer \
  --target react \
  --out ./src/components/Drawer.tsx

addは既存の異なるファイルを--forceなしで上書きしません。対応targetは次の7つです。

reacthtmlnativecomposeswiftuiwinuiflutter

AIまたは人が自由文をrequest.jsonへ正規化し、UI Atlasが登録済みの画面レシピと部品を決定します。次はデータ管理画面の有効な入力例です。

{
  "schemaVersion": 1,
  "goal": "Manage a large customer record set.",
  "family": "web",
  "platform": "web",
  "target": "react",
  "formFactor": "responsive",
  "surface": "data-management",
  "tasks": ["filter", "bulk-update"],
  "dataShape": "tabular",
  "dataVolume": "high",
  "navigationDepth": "application",
  "riskLevel": "high",
  "capabilities": ["search", "filter", "bulk-actions", "pagination"],
  "decisions": {
    "mobile-table": "priority-column-list",
    "bulk-scope": "all-filtered"
  },
  "constraints": []
}

npx -y ui-atlas@3.0.1 recommend \
  --input request.json \
  --out screen-plan.json

npx -y ui-atlas@3.0.1 audit --input screen-plan.json

npx -y ui-atlas@3.0.1 add \
  --plan screen-plan.json \
  --target react \
  --out ./generated-screen

--outを省略した場合はplan JSONそのものがstdoutへ出ます。--out screen-plan.jsonを指定した場合はplanをそのファイルへ保存し、stdoutには保存結果ui-atlas-write-resultが出ます。既存の異なるplanを置き換える場合だけ、内容を確認して--forceを追加します。

Skillは、Agentに正式名の扱い方とplatforms → search → recommend → audit → addの手順を教えます。最初に製品の種類を3択へ分け、CLIが返す次の質問に沿ってOSとtargetを決めます。Skill本文は版固定したnpx -y ui-atlas@3.0.1を使うため、裸のui-atlasグローバルコマンドは不要です。

# project
npx -y ui-atlas@3.0.1 init --agent claude --scope project

# user
npx -y ui-atlas@3.0.1 init --agent claude --scope user

# project
npx -y ui-atlas@3.0.1 init --agent codex --scope project

# user
npx -y ui-atlas@3.0.1 init --agent codex --scope user

# project
npx -y ui-atlas@3.0.1 init --agent opencode --scope project

# user
npx -y ui-atlas@3.0.1 init --agent opencode --scope user

hermes skills install https://ui-atlas.pages.dev/skill/ui-atlas/SKILL.md

# 認識確認
hermes skills list --source hub

# 更新確認と更新
hermes skills check
hermes skills update ui-atlas

# 削除
hermes skills uninstall ui-atlas

Claude Code・Codex・OpenCodeの更新と削除

更新前に配置先のSKILL.mdへ加えたローカル変更を確認・退避してください。公式配布内容へ置き換えるときだけ--forceを付けて、同じscopeへ再導入します。

npx -y ui-atlas@3.0.1 init --agent claude --scope project --force
npx -y ui-atlas@3.0.1 init --agent codex --scope project --force
npx -y ui-atlas@3.0.1 init --agent opencode --scope project --force

user scopeは--scope userへ変更します。削除は上に示した配置先のui-atlas Skillディレクトリを削除します。CLIにuninstall commandはありません。更新・削除後は新しいAgentセッションを開始します。

導入後の使い方

1. 新しいAgentセッションを開始

   既に開いているセッションへ後から導入した場合は、新規セッションまたは各Agentの再読み込みを使います。Hermesでは/resetでも反映できます。

2. 作るものを3つから選ぶ

   Agentはplatformsを実行し、Web・デスクトップアプリ・モバイルアプリのどれかを先に確認します。

3. OSとtargetを決める

   選んだ種類に必要な場合だけOSを確認し、その後にReact、SwiftUI、Composeなどの実装targetを選びます。

4. 要件を伝える

   例:「顧客一覧が必要。検索、filter、一括操作、paginationを含め、UI Atlasで候補、未決定事項、監査結果を示して」

5. 出力前に未決定事項を回答

   Agentは登録済みIDだけを使い、openDecisionsを勝手に補完せず確認します。

MCPは補助導線です。通常はSkillが版固定CLIを実行します。tool discoveryが必要なMCPクライアントでは、stdio server設定へ次のcommandとargsを登録します。設定ファイルの外形はクライアントごとに異なります。

{
  "command": "npx",
  "args": ["-y", "ui-atlas@3.0.1", "mcp"]
}

直接起動する場合:

npx -y ui-atlas@3.0.1 mcp

• ui_atlas_list_recipes
• ui_atlas_search
• ui_atlas_get_component
• ui_atlas_recommend_screen
• ui_atlas_generate_code
• ui_atlas_audit_plan

MCPはread-onlyです。ファイル保存は、内容と保存先を確認した後にCLIのaddを使います。

npm install ui-atlas@3.0.1

const atlas = require("ui-atlas");

const routes = atlas.platformRoutes();
const result = atlas.search("Off-canvas Panel", { limit: 5 });
const component = atlas.getComponent("drawer");
const code = atlas.getSnippet("drawer", "react");
const plan = atlas.recommend(request);
const report = atlas.auditPlan(plan);

レジストリだけを読む場合はrequire("ui-atlas/registry")、共有検索engineはrequire("ui-atlas/search-engine")を使えます。

UI Atlasのコードは、対象framework導入済みプロジェクトへ統合する出発点です。生成しただけで製品固有の品質を保証したことにはなりません。

• 対象プロジェクトのcompile・typecheck・build
• 実ブラウザまたは実機でのmountと主要操作
• キーボード、focus順、Escape、矢印キーの挙動
• Accessibility Tree、screen reader、文字拡大
• mobile / tablet / desktopのresponsive表示
• loading、empty、error、権限、実データ量
• 認証、API、validation、theme、製品固有E2E