# Form Token 设计

本文档定义 `AtomUI.Desktop.Controls.FormToken` 的专属语义、分类、使用范围和兼容边界。控件 Token 的通用分层、命名、计算、Theme Variables 边界和预设色规则见 [AtomUI 控件 Token 设计规范](../../../../engineering/development/control-token-guidelines.md)。Form 整体架构见 [Form 桌面版架构设计](overview.md)，内部实现原理见 [Form 桌面版实现原理](implementation.md)，设计和契约变化记录见 [Form Changelog](changelog.md)。

## 1. 定位

FormToken 是 Form 的控件级 Token scope，描述标签视觉、必填标记、冒号间距和表单项布局间距。输入控件自身高度、边框、状态色、图标尺寸、字体基础值和通用 spacing 来自 SharedToken 或对应输入控件 Token。

FormToken 不承载以下状态：

- `FieldName`、`InitialValues`、提交 values 或业务数据。
- `ValidateStatus`、`ValidateResult`、错误消息、警告消息或验证中状态。
- `FormLayout`、`RequiredMark`、`ValidateTrigger`、`ValidateStrategy` 等实例配置。
- 动态表单项数量、删除按钮显示状态或响应式 breakpoint 当前值。

## 2. Token 分类

### 2.1 标签文本 Token

- `LabelColor`
- `LabelFontSize`

这些 Token 控制 `FormItem` 标签文本的颜色和字号。默认值来自 `SharedToken.ColorTextHeading` 和 `SharedToken.FontSize`，使标签与桌面表单语义保持一致。

### 2.2 必填标记 Token

- `LabelRequiredMarkColor`

该 Token 控制默认必填星号颜色。默认值来自 `SharedToken.ColorError`。自定义必填或可选标记内容由 `CustomRequireMark`、`CustomRequireMarkTemplate`、`CustomOptionalMark` 和 `CustomOptionalMarkTemplate` 承载，不由 FormToken 生成具体内容。

### 2.3 标签冒号 Token

- `LabelColonMargin`

该 Token 控制标签冒号的 margin。它只描述冒号与标签内容之间的视觉间距，不决定冒号是否显示。冒号可见性由 `IsShowColon`、`LabelText` 和 `FormItem.Layout` 决定。

### 2.4 表单项间距 Token

- `FormItemSpacing`
- `InlineItemSpacing`

`FormItemSpacing` 控制表单项辅助信息区域和内容之间的垂直间距。`InlineItemSpacing` 控制 `FormLayout=Inline` 时 Form 根 StackPanel 的 item spacing。

### 2.5 垂直标签 Token

- `VerticalLabelPadding`
- `VerticalLabelMargin`

这些 Token 描述垂直布局下标签区域的 padding 和 margin。当前主题使用 `VerticalLabelMargin`，`VerticalLabelPadding` 属于 FormToken 稳定契约，调整时需要同步验证主题引用和 Token 类型、生成数据和 token.md。

## 3. 控件专项模型中的 Token 使用

FormToken 使用路径：

```text
SharedToken
  → FormToken
  → FormTheme / FormItemTheme
  → Form root spacing + FormItem label / marker / colon / help spacing
```

主题引用关系：

| Token | 主要使用点 |
| --- | --- |
| `LabelRequiredMarkColor` | `TextBlock#PART_DefaultRequireMark.Foreground`。 |
| `LabelColor` | `TextBlock#PART_Label.Foreground`。 |
| `LabelFontSize` | `TextBlock#PART_Label.FontSize`。 |
| `LabelColonMargin` | `TextBlock#PART_Colon.Margin`。 |
| `FormItemSpacing` | `PART_ContentLayout.Spacing` 和辅助信息区域最小高度。 |
| `InlineItemSpacing` | `FormLayout=Inline` 时 Form 根 items panel spacing。 |
| `VerticalLabelMargin` | `Layout=Vertical` 时标签区域 margin。 |

运行状态与 Token 分离：

```text
ValidateStatus / Help / ErrorMessageInlines
  → select visual state and message visibility
  → use SharedToken status colors or FormToken spacing
  → do not create per-state FormToken values
```

## 4. 控件家族影响

FormToken 直接影响 Form、FormItem 和 FormItemDecorator 参与的表单布局。它不会改变具体输入控件的高度、padding 或 border，这些由 LineEdit、Select、Cascader、TreeSelect、NumericUpDown 等控件自己的 Token 或 SharedToken 控制。

调整 FormToken 时必须评估：

- `FormTheme.axaml`
- `FormItemTheme.axaml`
- `FormItemDecoratorTheme.axaml`
- Form token.md 语义说明和 Gallery 示例
- `FormShowCasePageTests`

## 5. 兼容性要求

FormToken 属于 Form 主题契约。即使 `FormToken` 是 internal 类型，生成的 `FormTokenKind`、AXAML resource 使用点和 token.md 语义说明已经形成稳定依赖。

Token 变更要求：

- 不擅自重命名或删除现有 Token。
- 不把验证结果、业务值、动态表单项数量或当前 breakpoint 写成 Token。
- 不在 FormToken 中复制输入控件的高度、padding、边框、状态色或 focus ring Token。
- 不把 `FormLayout`、`RequiredMark`、`ValidateTrigger` 或 `ValidateStrategy` 变成 Token；它们是实例行为属性。
- 需要破坏性变更时，必须先说明影响范围并获得授权。

## 6. 验证策略

| 改动类型 | 验证要求 |
| --- | --- |
| 修改标签 Token | 验证水平、垂直、inline 布局下标签颜色、字号、tooltip 和 required mark 对齐。 |
| 修改冒号 Token | 验证 `IsShowColon=true/false`、长标签、右对齐和垂直布局下冒号可见性。 |
| 修改 spacing Token | 验证 Help、error、warning、无消息、inline 布局和动态表单项间距。 |
| 修改垂直标签 Token | 验证 `FormLayout=Vertical` 下标签与输入控件的垂直节奏。 |
| 删除或重命名 Token | 默认不允许；如获授权，需同步 AXAML 引用、生成文件、Token 类型、生成数据和 token.md和控件文档。 |
| 文档改动 | 运行 `git diff --check`，检查文档链接存在。 |