使用说明

VA设计系统监视器

用于监控VA设计系统组件状态、成熟度级别和生成实施示例的综合工具。 现在，我们直接从弗吉尼亚州的官方故事书中选取真实的例子！ 既可作为 npm包 和 MCP（模型上下文协议）服务 用于AI集成。

✨ 主要特点

🎯 真实的官方例子：直接从VA的Storybook存储库中获取实际的HTML示例
📊 组件状态监控：跟踪成熟度级别和使用建议
🔧 智能回退：在官方示例不可用时生成智能示例
🚀 多个接口：CLI、编程API和MCP服务
🔒 生产就绪：专为兽医网站和va应用程序模板基础设施而构建
🌐 交叉兼容：通过节点22与节点14.15.0+配合使用+

🚀 快速开始

选项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配置中：

光标:

macOS/Linux： ~/.cursor/mcp.json
窗户： %USERPROFILE%\.cursor\mcp.json （位置可能因安装而异）

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

克劳德桌面:

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %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 -获取组件属性/道具
getComponentExamples -生成实施示例
list_recommended_components -列出生产就绪组件
list_caution_components -列出需要注意的组件
get_components_by_status -按状态过滤组件
validate_components_in_code -验证组件列表
generate_component_report -综合状态报告

AI使用示例

问你的AI助手：

“显示va按钮的属性”
“生成va警报组件的示例”
“建议生产哪些VA组件？”
验证以下组件：va按钮、va模式、va卡

🎯 输出示例

组件状态

{
  "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服务器设置

克隆存储库：

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

在游标中配置MCP:

macOS/Linux： ~/.cursor/mcp.json
窗户： %USERPROFILE%\.cursor\mcp.json （位置可能因安装而异）

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

在Claude Desktop中配置MCP:

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %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": {}
      }
    }
  }
}

测试连接：

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

🔍 组件状态级别

推荐 -最佳实践，生产就绪
稳定 -安全生产使用
实验性 -仅用于开发/测试
可用_无问题 -可用，但可能有问题
使用时注意事项 -已知问题或正在评估中

🛠 发展

# 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问题跟踪器
包括再现步骤、预期行为和实际行为
添加相关系统信息（节点版本、操作系统等）

✨ 功能请求

使用“增强”标签打开问题
描述用例和预期功能
包括如何使用它的示例

🔧 代码贡献

分叉存储库并创建功能分支
遵循现有的代码风格和约定
添加新功能的测试
根据需要更新文档
提交前确保所有测试通过

🧪 开发工作流程

# 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 配置
写 清晰、描述性的提交消息
添加 JSDoc评论 公共API
包含测试对于新功能

🎯 我们需要帮助的领域

组件覆盖范围：添加对更多VA组件的支持
框架集成：React、Vue、Angular示例
演出：缓存和优化改进
文档：更多示例和用例
测试：边缘案例和集成测试

🔒 安全

如果您发现安全漏洞，请通过向维护人员发送电子邮件私下报告，而不是公开问题。

📜 行为准则

该项目遵循贡献者契约。请在所有互动中保持尊重和包容。

🏆 认可

贡献者将在我们的README和发行说明中得到认可。感谢您帮助改进VA开发工具！

问题？ 请随时提出问题或联系维护人员。我们是来帮忙的！

📝 许可证

MIT许可证-有关详细信息，请参阅许可证文件。