VA Design System Monitor

VA Design System Monitor

VA Design System のコンポーネントのステータスや成熟度レベルを監視し、実装例を生成する包括的なツールです。VA の公式 Storybook から直接取得した実際の例を利用できるようになりました！ AI 連携用の npm パッケージ と MCP（Model Context Protocol）サービス の両方で利用できます。

✨ 主な機能

• 🎯 公式の実例：VA の Storybook リポジトリから実際の HTML の例を直接取得します
• 📊 コンポーネントのステータス監視：成熟度レベルと使用に関する推奨事項を追跡します
• 🔧 スマートなフォールバック：公式の例がない場合に、適切な例を生成します
• 🚀 複数のインターフェース：CLI、プログラム用 API、MCP サービス
• 🔒 本番環境対応：vets-website および va-application-template のインフラストラクチャ向けに構築されています
• 🌐 幅広い互換性：Node 14.15.0+ から Node 22+ まで動作します

🚀 クイックスタート

オプション 1：NPM パッケージ（推奨）

コマンドラインから利用できるように、グローバルにインストールします：

# Install globally
npm install -g va-design-system-monitor

# Get real examples from VA Storybook
va-components examples va-radio
va-components examples va-button

# Check component status and properties  
va-components check va-modal
va-components props va-accordion
va-components list recommended

または、プロジェクトにローカルインストールします：

# Install locally
npm install va-design-system-monitor

# Use with npx
npx va-components examples va-radio

# Or use programmatically
import { getOfficialExamples, checkComponent } from 'va-design-system-monitor';

// Get real examples from VA Storybook
const radioExamples = await getOfficialExamples('va-radio');
console.log(radioExamples.examples); // Real HTML from official stories!

オプション 2：ローカル開発

リポジトリをクローンし、便利な npm スクリプトを使ってください：

# Clone the repository
git clone <repository-url>
cd va-design-system-monitor

# Install dependencies  
npm install

# Quick setup for MCP (auto-configures Cursor & Claude Desktop)
npm run setup:npm        # For published package (recommended)
npm run setup:local      # For local development
npm run setup:manual     # Show manual config instructions

🎯 MCP の簡単セットアップ

自動セットアップ（推奨）

# After cloning the repo, just run:
npm run setup:npm
# This auto-configures both Cursor and Claude Desktop!

MCP の手動設定

手動で設定する場合は、MCP 設定に以下を追加してください：

Cursor：

• macOS/Linux：~/.cursor/mcp.json
• Windows：%USERPROFILE%\.cursor\mcp.json（インストール方法によって場所が異なる場合があります）

{
  "servers": {
    "va-design-system-monitor": {
      "command": "npx",
      "args": ["-y", "va-design-system-monitor"],
      "env": {}
    }
  }
}

Claude Desktop：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/claude-desktop/config.json

macOS/Windows 用の形式：

{
  "mcpServers": {
    "va-design-system-monitor": {
      "command": "npx",
      "args": ["-y", "va-design-system-monitor"],
      "env": {}
    }
  }
}

Linux 用の形式：

{
  "mcp": {
    "servers": {
      "va-design-system-monitor": {
        "command": "npx",
        "args": ["-y", "va-design-system-monitor"],
        "env": {}
      }
    }
  }
}

⚡ 便利な NPM スクリプト

セットアップとサーバー

npm run setup            # Auto-setup MCP (local development)
npm run setup:npm        # Auto-setup MCP (npm package)
npm run setup:manual     # Show manual setup instructions
npm run server           # Start MCP server
npm run mcp              # Alias for server

クイックコマンド（引数は不要です！）

npm run quick:button     # Check + examples for va-button
npm run quick:alert      # Check + examples for va-alert  
npm run quick:modal      # Check + examples for va-modal

コンポーネントの確認

npm run check            # Check any component (you provide name)
npm run check:button     # Check va-button specifically
npm run check:alert      # Check va-alert specifically
npm run check:modal      # Check va-modal specifically

例の取得

npm run examples         # Examples for any component
npm run examples:button  # va-button examples
npm run examples:alert   # va-alert examples

リストとレポート

npm run list:recommended # List production-ready components
npm run list:caution     # List components needing caution
npm run report           # Full status report

開発

npm run dev              # Start server with file watching
npm run dev:watch        # Alias for dev
npm run dev:cli          # CLI with file watching

📋 CLI コマンド

コンポーネントのステータスと情報

# Check component status and maturity
va-components check va-button

# Get all component properties/props
va-components props va-button

# Generate implementation examples
va-components examples va-button

# Validate multiple components
va-components validate va-button va-alert va-card

# Lint components for issues
va-components lint va-modal va-table

検索とレポート

# List components by status
va-components list recommended
va-components list caution
va-components list stable

# Generate comprehensive report
va-components report
va-components report --json

JSON 出力

プログラムから利用する場合は、任意のコマンドに --json を追加してください：

va-components check va-button --json
va-components examples va-alert --json

🔧 プログラム用 API

基本的な使い方

import { 
  checkComponent, 
  validateComponents, 
  getComponentProperties,
  getComponentExamples 
} from 'va-design-system-monitor';

// Check a single component
const button = await checkComponent('va-button');
console.log(button.status); // 'STABLE'

// Get component properties
const props = await getComponentProperties('va-button');
console.log(props.properties); // Array of property objects

// Generate examples
const examples = await getComponentExamples('va-button');
console.log(examples.examples); // Array of implementation examples

// Validate multiple components
const results = await validateComponents(['va-button', 'va-alert']);
console.log(results.summary); // Validation summary

高度な使い方

import { VAComponentMonitor } from 'va-design-system-monitor';

const monitor = new VAComponentMonitor({
  cacheTimeout: 10 * 60 * 1000, // 10 minutes
  definitionsUrl: 'custom-url' // Optional custom URL
});

// Get all components
const components = await monitor.getComponents();

// Generate report
const report = await monitor.generateReport();

// Check production readiness
const isReady = await monitor.isProductionReady('va-button');

🤖 MCP サービス（AI 連携）

MCP サービスとして実行すると、以下のツールを利用できます：

利用可能なツール

• get_component_status - コンポーネントのステータスと成熟度を取得します
• getComponentProperties - コンポーネントのプロパティ／props を取得します
• getComponentExamples - 実装例を生成します
• list_recommended_components - 本番環境で使用できるコンポーネントの一覧を表示します
• list_caution_components - 注意が必要なコンポーネントの一覧を表示します
• get_components_by_status - ステータスでコンポーネントを絞り込みます
• validate_components_in_code - コンポーネントのリストを検証します
• generate_component_report - ステータスに関する包括的なレポートを生成します

AI の使用例

AI アシスタントに次のように尋ねます：

• 「va-button のプロパティを表示して」
• 「va-alert コンポーネントの例を生成して」
• 「本番環境での使用が推奨されている VA コンポーネントはどれですか？」
• 「次のコンポーネントを検証して：va-button、va-modal、va-card」

🎯 出力例

コンポーネントのステータス

{
  "name": "Button",
  "tagName": "va-button", 
  "status": "STABLE",
  "maturityLevel": "deployed",
  "recommendation": "Safe for production use - actively deployed"
}

コンポーネントのプロパティ

{
  "component": {
    "name": "Button",
    "tagName": "va-button",
    "status": "STABLE"
  },
  "properties": [
    {
      "name": "text",
      "type": "string",
      "optional": true,
      "description": "The text displayed on the button"
    },
    {
      "name": "disabled",
      "type": "boolean", 
      "optional": true,
      "description": "If true, the click event will not fire"
    }
  ]
}

実装例

{
  "component": {
    "name": "Button",
    "tagName": "va-button",
    "status": "STABLE"
  },
  "examples": [
    {
      "title": "Basic Usage",
      "description": "Simple example showing essential action functionality",
      "code": "<va-button text=\"Submit Application\"></va-button>",
      "framework": "HTML/Web Components"
    },
    {
      "title": "Accessibility Enhanced", 
      "description": "Example with enhanced screen reader support",
      "code": "<va-button text=\"Submit Application\" label=\"Submit your disability benefits application\"></va-button>",
      "framework": "HTML/Web Components"
    }
  ]
}

📦 インストールとセットアップ

グローバルインストール

npm install -g va-design-system-monitor

プロジェクトへのローカルインストール

npm install va-design-system-monitor

MCP サーバーのセットアップ

1. リポジトリをクローンします：

   git clone <repository-url>
   cd va-design-system-monitor
   npm install
   

2. Cursor で MCP を設定します：

   • macOS/Linux：~/.cursor/mcp.json
   • Windows：%USERPROFILE%\.cursor\mcp.json（インストール方法によって場所が異なる場合があります）

   {
     "servers": {
       "va-design-system-monitor": {
         "command": "npx",
         "args": ["-y", "va-design-system-monitor"],
         "env": {}
       }
     }
   }
   

3. Claude Desktop で MCP を設定します：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/claude-desktop/config.json

   macOS/Windows の形式：

   {
     "mcpServers": {
       "va-design-system-monitor": {
         "command": "npx",
         "args": ["-y", "va-design-system-monitor"],
         "env": {}
       }
     }
   }
   

   Linux の形式：

   {
     "mcp": {
       "servers": {
         "va-design-system-monitor": {
           "command": "npx",
           "args": ["-y", "va-design-system-monitor"],
           "env": {}
         }
       }
     }
   }
   

4. 接続をテストします：

   # Run the MCP server directly
   node bin/mcp-server.js
   

🔍 コンポーネントのステータスレベル

• RECOMMENDED - ベストプラクティスであり、本番環境での使用に対応しています
• STABLE - 本番環境で安全に使用できます
• EXPERIMENTAL - 開発・テスト環境でのみ使用してください
• AVAILABLE_WITH_ISSUES - 使用できますが、問題が発生する場合があります
• USE_WITH_CAUTION - 既知の問題があるか、評価中です

🛠 開発

# Clone and install
git clone <repository-url>
cd va-design-system-monitor
npm install

# Run CLI locally
node bin/cli.js check va-button

# Run MCP server locally  
node bin/mcp-server.js

# Run tests
npm test

🤝 コントリビューション

VA 開発者コミュニティからのコントリビューションを歓迎します！バグ修正、機能追加、ドキュメントの改善など、皆さまのご協力がこのツールをより良いものにします。

🚀 コントリビューター向けクイックスタート

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/va-design-system-monitor.git
cd va-design-system-monitor
npm install

# Create a feature branch
git checkout -b feature/your-feature-name

# Make your changes and test them
npm run test
npm run dev  # Test the CLI locally

# Commit your changes
git add .
git commit -m "feat: add your feature description"

# Push and create a pull request
git push origin feature/your-feature-name

📋 コントリビューションの方法

🐛 バグ報告

• GitHub issue tracker をご利用ください
• 再現手順、期待される動作、実際の動作を記載してください
• 関連するシステム情報（Node のバージョン、OS など）を追加してください

✨ 機能リクエスト

• 「enhancement」ラベルを付けて issue を作成してください
• ユースケースと期待する機能を説明してください
• 使用例を含めてください

🔧 コードのコントリビューション

• リポジトリをフォークし、機能ブランチを作成してください
• 既存のコードスタイルと規約に従ってください
• 新しい機能にはテストを追加してください
• 必要に応じてドキュメントを更新してください
• 提出前にすべてのテストが成功することを確認してください

🧪 開発ワークフロー

# Run tests
npm test

# Start development server with file watching
npm run dev

# Test CLI commands locally
node bin/cli.js check va-button

# Test MCP server locally
node bin/mcp-server.js

# Build for production
npm run build

📝 コードスタイル

• 型安全性のために TypeScript を使用してください
• ESLint の設定に従ってください
• 明確で内容が伝わるコミットメッセージを書いてください
• 公開 API には JSDoc コメントを追加してください
• 新しい機能には テストを含めてください

🎯 ご協力いただきたい分野

• コンポーネントの対応範囲：より多くの VA コンポーネントへの対応追加
• フレームワークとの統合：React、Vue、Angular の例
• パフォーマンス：キャッシュと最適化の改善
• ドキュメント：より多くの例とユースケース
• テスト：エッジケースと統合テスト

🔒 セキュリティ

セキュリティの脆弱性を発見した場合は、公開 issue を作成せず、メンテナーにメールで非公開に報告してください。

📜 行動規範

このプロジェクトでは Contributor Covenant を採用しています。すべてのやり取りにおいて、敬意を持ち、誰もが受け入れられる対応を心がけてください。

🏆 謝辞

コントリビューターの皆さまは、README とリリースノートで紹介されます。VA 開発ツールの改善にご協力いただき、ありがとうございます！

---

ご質問はありますか？ お気軽に issue を作成するか、メンテナーにお問い合わせください。いつでもお手伝いします！

📝 ライセンス

MIT License - 詳細は LICENSE ファイルをご覧ください。