@expcat/tigercat-vue

Tigercat

基于 Tailwind CSS v4 的 Vue 3 / React UI 组件库。两套框架共享设计 token、类型与交互约定。公开组件权威清单见 skills/tigercat/references/component-index.md（生成物）。

五个官方包版本对齐，遵循 SemVer。npm latest 是稳定版 2.9.4（v2，顶部徽章指向它），next 是预览版 3.0.0-rc.3（v3，当前 main 的文档与 API）。使用的 Tigercat 包应保持同一版本。

🚀 在线示例：https://expcat.github.io/Tigercat/ — Vue 3 与 React 组件示例、主题切换与暗色模式实时预览。

📘 AI Agent 文档 组件 API、使用示例和配置指南请参考 skills/tigercat/SKILL.md。 LLM 客户端可通过 @expcat/tigercat-mcp 按任务路由并读取最小必要上下文（默认读取随包快照，可离线使用，无需克隆仓库）。

特性

• Vue 3 与 React 组件保持一致的功能边界、命名和设计 token。
• 支持组件子路径导入、tree shaking、暗色模式、主题定制与国际化。
• 覆盖表单、导航、数据展示、虚拟化、图表、编辑器和复合业务组件。
• 提供 Vite 脚手架、组件辅助命令、环境诊断以及 MCP 文档路由。
• 支持 SSR。

快速开始

使用 CLI 创建项目（推荐）

CLI 会生成已配置 Tailwind CSS v4 的 Vue 3 或 React Vite 项目。下方命令使用预览通道 @next，与当前文档一致；使用稳定版时去掉 @next，并参阅对应版本的文档。

pnpm dlx @expcat/tigercat-cli@next create my-app --template vue3
# 或
pnpm dlx @expcat/tigercat-cli@next create my-app --template react

cd my-app
pnpm install
pnpm dev

手动安装

# Vue 3
pnpm add @expcat/tigercat-vue@next @expcat/tigercat-core@next
# React
pnpm add @expcat/tigercat-react@next @expcat/tigercat-core@next

# Tailwind CSS v4（两套框架均需要）
pnpm add -D tailwindcss @tailwindcss/vite

在 Vite 中启用 @tailwindcss/vite，然后在全局样式中引入 Tigercat 插件，并用 @source 注册已安装包的 dist（Tailwind v4 不会自动扫描 node_modules）。下方 ../node_modules/... 相对路径以 src/style.css 为准；样式文件放在其他位置时，请按实际位置调整：

@import 'tailwindcss';
@plugin "@expcat/tigercat-core/tailwind";
@source '../node_modules/@expcat/tigercat-*/dist/**/*.{js,mjs}';

用与上面相同的 dist-tag 运行 pnpm dlx @expcat/tigercat-cli@next doctor（稳定版去掉 @next），检查 Node.js、pnpm、Tailwind CSS、框架 peer dependency 与模板工具链。

Vue 3 示例

<script setup lang="ts">
import { Button } from '@expcat/tigercat-vue/Button'
</script>

<template>
  <Button variant="primary">开始使用</Button>
</template>

React 示例

import { Button } from '@expcat/tigercat-react/Button'

export function App() {
  return <Button variant="primary">开始使用</Button>
}

推荐在应用边界使用上述 PascalCase 子路径导入以获得更小的按需 bundle；根入口的命名导出仍可用于小型应用、hooks、command API 和共享类型。

文档

性能与兼容性

• 框架包提供 PascalCase 组件子路径导出并支持 tree shaking；高级组件优先使用子路径导入以减小 bundle。
• 大数据列表、Table / VirtualTable 虚拟化建议、图表降采样与主题 token 批量更新见 skills/tigercat/references/performance.md；token 用法见 theme.md。
• Vue: 3.x
• React / React DOM: 19.x
• Tailwind CSS / @tailwindcss/vite: 4.x
• Node.js: >= 22.13.0
• pnpm（仓库开发）: >= 11.9.0
• 浏览器支持范围为现代浏览器最新两个主要版本；功能 E2E 覆盖 Chromium、Firefox、WebKit 与移动 Chromium，不维护跨系统易漂移的图片对比基线。

MCP 接入（AI Agent）

@expcat/tigercat-mcp 是只读 stdio MCP 服务。接入后 Agent 可按任务路由到导入子路径、props/事件与 React/Vue 绑定差异（支持中文别名，如 表单、日期选择、表格），单次只内联所需小节：

# 预览版 next（3.0.0-rc.3）。稳定版 latest（2.9.4）去掉 @next
claude mcp add tigercat -- npx -y @expcat/tigercat-mcp@next

或在任意 MCP 客户端的 mcpServers 中配置（稳定版把包名改成 @expcat/tigercat-mcp）：

{
  "mcpServers": {
    "tigercat": {
      "command": "npx",
      "args": ["-y", "@expcat/tigercat-mcp@next"]
    }
  }
}

• 默认读取与已安装包版本固定的 skills 快照，可离线使用，无需克隆仓库。
• 本地开发：tigercat-mcp --root /path/to/Tigercat 读取可编辑的仓库 checkout。
• 可选远程镜像：--base-url <url> 或环境变量 TIGERCAT_MCP_BASE_URL，例如 https://expcat.github.io/Tigercat/mcp/。镜像版本与文件 SHA-256 必须匹配随包快照，实际正文在读取时校验。
• 来源优先级：--root > --base-url > TIGERCAT_MCP_BASE_URL > 随包快照。镜像不可达时，移除镜像配置即可使用随包快照。
• 诊断：tigercat-mcp --doctor。
• 仓库内启动：pnpm mcp:build 后 pnpm mcp:serve。

维护者标志、远程 allow-list 与部署约定见 scripts/README.md。

包

本地开发

git clone https://github.com/expcat/Tigercat.git
cd Tigercat
corepack pnpm setup
pnpm example:vue    # http://localhost:5173
pnpm example:react  # http://localhost:5174

常用命令

完整脚本与门禁清单见 scripts/README.md。

参与贡献

请先运行 corepack pnpm setup 完成依赖安装、构建和环境检查。提交前按 tests/README.md 选择命令；涉及公共 API、发布面或门禁策略的改动应运行 pnpm quality:release。

开发与评审必须遵守 CONTRIBUTING.md 的“根因修复与架构约束”；组件 API、示例与自动化维护规则以 skills/tigercat/SKILL.md 为准，当前项目状态与后续任务规则见 docs/ROADMAP.md。

License

MIT