# MasterGo 组件与组件集生成规范

## 1. 规则继承与输出契约

- **规则继承**：本规范定义 MasterGo **母版组件 (Component)** 与 **组件集 (Component Set)** 的生成代码；基础 HTML/Tailwind 转译规范（零 Margin、纯 Flex、FontAwesome 图标、`<p>` 与 `<span>` 选型及 5 要素全集）**完全继承 `page-generate.md`**。
- **输出契约**：
  1. 仅输出纯 HTML 代码片段，禁止混入 Markdown 解释或 `html/head/body` 等外层标签。
  2. 根节点必须且只能包含 `data-type="component"` 或 `data-type="component-set"`。
  3. 所有节点必须包含语义化 `data-name="..."`（推荐中文业务名，如 `data-name="图标容器"`）。

## 2. 根节点与变体契约（Root & Variants）

### 单组件 (`data-type="component"`)
用于单一形态组件（如 Badge、Avatar）。根节点声明 `data-type="component"` 与 `data-name="组件名"`。

### 组件集 (`data-type="component-set"`)
用于多形态/多尺寸/多状态组件。必须遵循：
1. **直接子节点**：所有变体节点必须为 `data-type="component"` 且必须是 `component-set` 的**直接子元素**（禁止中间包裹 `div`）。
2. **变体属性展平**：写为 `data-variant-维度="值"`（如 `data-variant-状态="主要"` `data-variant-尺寸="大"`）。
3. **维度对齐与语言一致**：同一组件集内所有变体必须包含相同的维度键集合；**键与值同语言**（中文键配合中文值，如 `状态="主要"`；英文键配合英文值，如 `status="primary"`）。
4. **变体数量控制**：变体总数建议 ≤ 16，维度数 ≤ 3。

## 3. 组件属性协议 (`data-prop` & `data-prop-bind-*`)

属性用于控制实例的**显隐**与**文案**，避免变体笛卡尔积爆炸。

### 声明与绑定语法
1. **根节点一次性声明 (`data-prop`)**：写在 `component` 或 `component-set` 的根节点上（变体共享）：
   ```html
   data-prop='[{"type":"boolean","name":"显示图标","value":true},{"type":"text","name":"按钮文本","value":"确认"}]'
   ```
2. **子节点图层绑定 (`data-prop-bind-*`)**：
   - 显隐绑定：`data-prop-bind-visible="中文属性名"`（绑在容器 `div` 上，隐藏时整块空间折叠）。
   - 文本绑定：`data-prop-bind-text="中文属性名"`（绑在 `<span>` / `<p>` 文本节点上）。

### 变体 (Variant) 与属性 (Prop) 的划分判定
- **外形 / 尺寸 / 颜色 / 风格差异** ➜ 用 **变体** (`data-variant-*`)
- **元素可选 / 能否隐藏** ➜ 用 **BOOL 属性** (`type: "boolean"`)
- **文本内容变化** ➜ 用 **TEXT 属性** (`type: "text"`)
- **单一图层原则**：主组件只呈现最典型的默认形态，禁止在同一图层并存多个互斥节点（如输入框不要同时画占位符和填值 text）。

## 4. 组件尺寸契约 (`widthMode × heightMode`)

变体节点（`data-type="component"`）必须根据复用场景显式确定宽高模式：

| 模式 | 含义 | 决定方 | 典型 Tailwind 语法 | 适用场景 |
| :--- | :--- | :--- | :--- | :--- |
| `hug` | 内容撑开 | 内容驱动 | **不写死固定宽高**，靠 `px-[...]/py-[...]/gap-[...]` 撑开 | Button, Badge, Tag, Tooltip |
| `fixed` | 尺寸固定 | 组件自身 | 根节点写死 `w-[...]/h-[...]`，内部配合 `flex-1/self-stretch/overflow-hidden` | Avatar, IconButton, Input, Card 容器 |
| `fill` | 填满父级 | 父容器决定 | 宽度写 `self-stretch`，高度写 `flex-1` | Table, List, Panel, Sidebar 高度 |

> ⚠️ 避免常见尺寸错误：严禁随手给所有组件写死固定宽高；`hug` 组件禁止写 `flex-1`；`fixed` 组件内部溢出内容必须加 `overflow-hidden`。

## 5. 变量优先与字体规范

1. **设计系统变量 (`var(...)`) 优先**：若落盘了 `variable.json`，关键视觉属性（色彩、字号、圆角、间距等）**必须优先使用** Tailwind 任意值 `var(变量原文)` 引用（如 `bg-[var(色彩/brand/primary)]`）；匹配不到真实变量时才回退字面值（遵循 `variable-import.md`）。
2. **字体规范**：默认使用 Inter。指定字体时先调用 `get_fonts`，并在文本节点显式写 `style="font-family: 'family'"`。

## 6. 参考规范范式

### 精炼组件集范式（包含变体、data-prop、尺寸契约与变量引用）

```html
<div
  data-type="component-set"
  data-name="按钮"
  data-prop='[{"type":"boolean","name":"显示图标","value":true},{"type":"text","name":"按钮文本","value":"确认"}]'
  class="flex flex-col justify-start items-start gap-[12px] p-[16px] bg-[#F8FAFC]"
>
  <!-- 变体 1：主要按钮（hug 模式） -->
  <div
    data-type="component"
    data-name="按钮-主要"
    data-variant-状态="主要"
    class="flex flex-row justify-center items-center gap-[8px] bg-[#2563EB] rounded-[8px] px-[16px] py-[10px]"
  >
    <div data-name="图标容器" data-prop-bind-visible="显示图标" class="flex flex-row justify-center items-center">
      <i data-name="图标" class="fas fa-star text-[14px] text-[#FFFFFF]"></i>
    </div>
    <span data-name="文字" data-prop-bind-text="按钮文本" class="text-[14px] leading-[18px] font-[600] text-[#FFFFFF] text-left">确认</span>
  </div>

  <!-- 变体 2：次要按钮（hug 模式） -->
  <div
    data-type="component"
    data-name="按钮-次要"
    data-variant-状态="次要"
    class="flex flex-row justify-center items-center gap-[8px] bg-[#E2E8F0] rounded-[8px] px-[16px] py-[10px]"
  >
    <div data-name="图标容器" data-prop-bind-visible="显示图标" class="flex flex-row justify-center items-center">
      <i data-name="图标" class="fas fa-star text-[14px] text-[#0F172A]"></i>
    </div>
    <span data-name="文字" data-prop-bind-text="按钮文本" class="text-[14px] leading-[18px] font-[600] text-[#0F172A] text-left">确认</span>
  </div>
</div>
```