# SwiftUI 样式驱动组件

`SwiftUI` `iOS` `组件库` `样式协议` `Apple`

# SwiftUI 样式驱动组件技能

为所有支持 [Agent Skills 开放格式](https://agentskills.io/home) 的 AI 编程工具提供专业指导，帮助开发者使用 Apple 样式驱动架构模式构建可扩展的 SwiftUI 组件。

从 Apple 官方模式（`ButtonStyle`、`LabelStyle`、`ToggleStyle`）中提炼而来，为 AI 代理提供可直接使用的精简参考。

## 适用人群

- 希望构建符合 Apple 标准可扩展性的可复用 SwiftUI 组件库的团队。
- 需要为自定义组件实现多种视觉风格、同时避免代码重复的开发者。
- 希望实现基于环境的样式级联传递（可穿透视图层级）的任何人。

## 使用方法

### 方式 A：使用 skills.sh（推荐）

通过一条命令安装此技能：

```bash
npx skills add https://github.com/ahmadbrkt/swiftui-style-driven-components-skill --skill swiftui-style-driven-components
```

更多信息请访问 [skills.sh 平台页面](https://skills.sh/ahmadbrkt/SwiftUI-Style-Driven-Components-Skill/swiftui-style-driven-components)。

然后在 AI 代理中使用该技能，例如：
> 使用 swiftui 样式驱动组件技能，创建一个支持样式协议的 Card 组件

### 方式 B：Claude Code 插件

#### 个人使用

在 Claude Code 中为个人使用安装此技能：

1. 添加插件市场：
   ```bash
   /plugin marketplace add ahmadbrkt/SwiftUI-Style-Driven-Components-Skill
   ```

2. 安装技能：
   ```bash
   /plugin install swiftui-style-driven-components@swiftui-style-driven-components-skill
   ```

#### 项目配置

若希望为仓库中所有协作者自动提供此技能，请在仓库的 `.claude/settings.json` 中进行配置：

```json
{
  "enabledPlugins": {
    "swiftui-style-driven-components@swiftui-style-driven-components-skill": true
  },
  "extraKnownMarketplaces": {
    "swiftui-style-driven-components-skill": {
      "source": {
        "source": "github",
        "repo": "ahmadbrkt/SwiftUI-Style-Driven-Components-Skill"
      }
    }
  }
}
```

团队成员打开项目时，Claude Code 会提示其安装该技能。

### 方式 C：手动安装

1. **克隆**本仓库。
2. 按照工具的官方技能安装文档，**安装或符号链接** `swiftui-style-driven-components/` 文件夹（参见下方链接）。
3. **正常使用 AI 工具**，并让其在处理组件架构任务时使用 "swiftui-style-driven-components" 技能。

#### 技能保存位置

请参阅各工具的官方文档，以下是几个常用工具的参考：

- **Codex：** [技能保存位置](https://developers.openai.com/codex/skills/#where-to-save-skills)
- **Claude：** [使用技能](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#using-skills)
- **Cursor：** [启用技能](https://cursor.com/docs/context/skills#enabling-skills)

**验证方法**：

AI 代理应能引用 `swiftui-style-driven-components/SKILL.md` 中的分类/操作手册，并跳转到与组件任务相关的参考文件。

## 技能功能

本技能为 AI 编程工具提供全面的 SwiftUI 样式驱动组件指导，具体包括：

### 指导组件架构

- 判断何时使用样式协议，何时使用简单组件
- 按照 Apple 的组织模式构建文件结构
- 实现协议 → 配置 → 组件 → 环境的完整链路
- 设计具有内部类型擦除的类型安全 API

### 创建样式协议

- 定义带有 `DynamicProperty` 的协议以访问环境
- 使用 `@ViewBuilder @MainActor` 确保 UI 线程安全
- 创建带嵌套类型擦除视图的配置类型
- 严格遵循 Apple 的 `ButtonStyle`、`LabelStyle` 惯例

### 构建可扩展组件

- 编写从环境中读取样式的组件
- 在内部创建配置（不暴露给初始化器）
- 使用 `AnyView` 对 `style.makeBody` 进行类型擦除包装
- 支持在不修改现有组件的情况下添加新样式

### 实现环境样式

- 使用 `@Entry` 宏定义环境键
- 以存在类型（`any ComponentStyle`）存储样式
- 创建用于样式应用的视图修饰符
- 支持可穿透视图层级的子树样式级联

### 设计系统集成

- 使用设计令牌替代魔法数字
- 实现间距、排版和颜色系统
- 在组件间构建一致的视觉语言
- 通过环境值支持主题化

### 编写测试与预览

- 为所有样式变体组织快照测试
- 为不同配置构建预览结构
- 使用动态字体（Dynamic Type）测试无障碍支持
- 验证样式隔离与环境传播

## 本技能的独特之处

**Apple 原生模式**：严格遵循 Apple 构建 `ButtonStyle`、`LabelStyle`、`ToggleStyle` 及其他样式协议的方式。你的组件将让 SwiftUI 开发者感到原生自然。

**无倾向性**：专注于结构模式，而非视觉设计。适用于任何设计系统、组件库或项目架构。

**实用决策树**：包含关于何时使用样式协议、何时可以跳过的清晰指导。并非所有组件都需要此模式——本技能帮你做出判断。

**完整示例**：每个模式都包含完整、可编译的 Swift 代码，无伪代码或不完整片段。

**反模式指导**：同时展示正确（✅）和错误（❌）的做法，并解释模式重要性的原因。

## 技能结构

```
swiftui-style-driven-components/
├── SKILL.md                           # 主技能文件，包含决策树
└── references/
    ├── component-structure.md         # 文件组织与命名规范
    ├── style-protocol.md              # 协议定义与配置模式
    ├── environment-keys.md            # 环境注入与使用模式
    ├── common-patterns.md             # 便捷初始化器、参数化样式
    ├── design-system.md               # 设计令牌、排版、颜色
    ├── testing.md                     # 快照测试与测试组织
    ├── previews.md                    # 预览结构与检查清单
    └── accessibility.md               # 标签、标识符、动态字体
```

## 贡献

欢迎贡献！本仓库遵循 [Agent Skills 开放格式](https://agentskills.io/home)，该格式有特定的结构要求。

**强烈建议借助 AI 辅助进行贡献：**

- 使用 [skill-creator 技能](https://github.com/anthropics/skills/tree/main/skills/skill-creator) 配合 Claude，以确保格式正确
- 这有助于维护 Agent Skills 格式，并确保你的贡献能与 AI 代理正常协作

**请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，了解：**

- 如何使用 skill-creator 技能进行贡献
- Agent Skills 格式要求
- 质量标准与最佳实践
- Pull Request 流程

本技能持续维护，以反映最新的 SwiftUI 样式驱动组件最佳实践，并将随框架演进不断更新。

## 许可证

本技能为开源项目，采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE)。