---
name: xycomponents-shared
version: 1.0.0
description: >-
  @czxingyu/xycomponents 安装、版本对齐与 Vue 应用接入。在业务项目中使用 xy- 组件、
  引入样式与类型、升级组件库，或需要确认 CLI 与 npm 包版本一致时使用。
  查询 Props/Events/Slots 前请先读本 skill，再读 xycomponents-cli skill。
metadata:
  requires:
    packages: ["@czxingyu/xycomponents"]
---

# xycomponents 共享规则

## 版本与 CLI 策略（必须遵守）

- **只在当前项目内**安装 `@czxingyu/xycomponents`；**不要**全局安装 CLI，也不要用与项目 `package.json` 版本不一致的全局命令。
- 安装组件库时会**自动**写入 Agent Skill（Cursor / Claude Code / Codex / `.agents/skills/` + `AGENTS.md`）。跳过：`XYCOMPONENTS_SKIP_SKILLS_INSTALL=1 pnpm add ...`
- 手动重装或升级后同步：`pnpm exec xycomponents skills install --consumer --json`
- CLI 元数据随 npm 包一起发布；**CLI 版本 = 已安装的包版本**。
- 升级组件库时重新安装，CLI 会同步更新：

```bash
pnpm add @czxingyu/xycomponents@latest
# 或锁定版本：pnpm add @czxingyu/xycomponents@0.1.2
```

- 安装或升级后验证：

```bash
pnpm exec xycomponents doctor --json
```

期望 `status` 为 `"pass"`。若命令不存在，说明依赖未安装或未执行 `pnpm install`。

## 应用接入

完整入口（默认推荐）：

```ts
import { createApp } from "vue";
import XyComponents from "@czxingyu/xycomponents";
import "@czxingyu/xycomponents/style";

createApp(App).use(XyComponents).mount("#app");
```

轻量入口（排除 Empty / List / Result / Table / Transfer 等大资源组件族）：

```ts
import XyComponentsLite from "@czxingyu/xycomponents/lite";
import "@czxingyu/xycomponents/lite/style";

app.use(XyComponentsLite);
```

全局模板类型（使用 `app.use(XyComponents)` 时推荐）：

```ts
/// <reference types="@czxingyu/xycomponents/global" />
```

## 命名约定

| 场景       | 形式               | 示例                    |
| ---------- | ------------------ | ----------------------- |
| Vue 组件名 | `Xy` + PascalCase  | `XyButton`              |
| 模板标签   | `xy-` + kebab-case | `<xy-button>`           |
| CLI 组件名 | kebab-case         | `button`、`date-picker` |

## 写组件代码前

1. 确认项目已安装 `@czxingyu/xycomponents`。
2. 读取 [xycomponents-cli](../xycomponents-cli/SKILL.md)。
3. 用 `pnpm exec xycomponents component <name> --json` 查 API，**禁止凭记忆猜测** Props / Events / Slots。
4. 需要示例时用 `pnpm exec xycomponents snippet <name> --example <id>`。
5. 遇到弃用或已删除组件，先 `pnpm exec xycomponents migrate <name> --json`。
6. 确认是库 Bug 或需要新能力时，读 [xycomponents-contribute](../xycomponents-contribute/SKILL.md) 提交 GitHub Issue。

## 入口选择

不确定用 default 还是 lite 时：

```bash
pnpm exec xycomponents package --json
```

## 样式与主题

- 必须引入对应 style 入口（`style` 或 `lite/style`）。
- 组件内不要硬编码 `font-size: Npx`；扩展尺寸请用 `components/style/vars.css` 中的 design token（`--xy-font-size-*`、`--xy-control-font-size-*` 等）。

## 本仓库（vue3components）维护者例外

在组件库源码仓库内开发时，先构建 CLI 再查询：

```bash
pnpm run build:cli
pnpm xycomponents component <name> --json
```

维护流程另见仓库根目录 `AGENTS.md`。