# Apple Human Interface Guidelines Colors

> HIG 配色：Android 用 colors.xml hex；iOS 必须用 SwiftUI Color 系统 API，含主题色 Color.cyan/pink/blue。Invoke when user needs iOS-style colors for Android app OR iOS color governance.

- Skill: `opn48/apple-human-interface-guidelines-colors` (Agent Skill)
- Install (CLI): `npx skillmds@latest add opn48/apple-human-interface-guidelines-colors`
- Raw SKILL.md: https://api.skillmd.com/api/skills/opn48/apple-human-interface-guidelines-colors/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: OPN48 (https://skillmd.com/u/opn48)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/opn48/apple-human-interface-guidelines-colors

---


# iOS System Colors

> **平台分流**
> - **Android**：下文 hex 表 → `values/colors.xml` / `values-night/colors.xml`
> - **iOS**：**禁止**在业务 UI 使用本表 hex；改用 SwiftUI `Color`（见 [iOS SwiftUI 实施方案](#ios-swiftui-实施方案)）

## iOS SwiftUI 实施方案

iOS 全部界面语义色与主题色走 [SwiftUI `Color`](https://developer.apple.com/documentation/swiftui/color) — context-dependent，渲染前由系统解析，自动适配浅色/深色/增对比度。

### 创建颜色的优先级

1. `Color.primary` / `Color.secondary` — 主/次级文字
2. `Color.cyan` / `Color.pink` / `Color.blue` / `Color.red` 等标准 palette
3. `Color(uiColor: .systemBackground)` 等 — 背景、分割、grouped 列表（SwiftUI 无对应静态成员时）
4. `Color("Name")` — 仅 VIP/品牌等无系统等价色

**禁止**（业务 UI）：`Color(red:)`、`Color(hex:)`、自定义 token 转发系统语义色、`UIColor.systemCyan` 作主题色。

### 主题色三档（App 设置）

| 设置项 | SwiftUI | 禁止 |
|--------|---------|------|
| 青柠青 | `Color.cyan` | hex、`Color(red:)`、封装 enum 转发 |
| 莓果粉 | `Color.pink` | 同上 |
| 海盐蓝 | `Color.blue` | 同上 |

```swift
@EnvironmentObject private var appearance: ThemeStore

.tint(appearance.accentColor)
.background(appearance.accentColor)

// ThemeStore.AccentTheme
var accentColor: Color {
    switch self {
    case .cyan: Color.cyan
    case .pink: Color.pink
    case .blue: Color.blue
    }
}
```

业务 View 直接写 SwiftUI `Color`；主题色唯一来源是应用级 `ThemeStore`（或等价的 `ObservableObject`），不新增二次封装层。

### 语义色（View 内直接用）

| 用途 | 写法 |
|------|------|
| 主文字 | `Color.primary` |
| 次级文字 | `Color.secondary` |
| 页面背景 | `Color(uiColor: .systemBackground)` |
| Tab/卡片背景 | `Color(uiColor: .secondarySystemBackground)` |
| 分割线 | `Color(uiColor: .separator)` |
| 错误/角标 | `Color.red` |
| accent 按钮上图标 | `Color.white` |
| 图片叠层文字 | `Color.white`（非 `primary`） |

### 着色 API

- 用 `.foregroundStyle(...)`、`.tint(...)`，新代码不用 `.foregroundColor`
- 不缓存 `color.resolve(in:)` 的 RGB
- 避免 `Theme.textPrimary` 等语义色二次封装；优先在 View 内直接写 SwiftUI `Color`

---

## 白天模式 (Light Mode) — Android hex 参考

### 彩色系

| 颜色名称 | Hex值 |
|----------|-------|
| sys_red | #FF3B30 |
| sys_orange | #FF9500 |
| sys_yellow | #FFCC00 |
| sys_green | #34C759 |
| sys_mint | #00c7be |
| sys_teal | #30b0c7 |
| sys_cyan | #32ade6 |
| sys_blue | #007AFF |
| sys_indigo | #5856D6 |
| sys_purple | #AF52DE |
| sys_pink | #FF2D55 |
| sys_brown | #a2845e |

### VIP配色 (opn48 design)

| 颜色名称 | Hex值 |
|----------|-------|
| vip_golden | #6F2C02 |
| vip_bg | #FFBE6B |

### 灰色系

| 颜色名称 | Hex值 |
|----------|-------|
| sys_gray1 | #8E8E93 |
| sys_gray2 | #AEAEB2 |
| sys_gray3 | #C7C7CC |
| sys_gray4 | #D1D1D6 |
| sys_gray5 | #E5E5EA |
| sys_gray6 | #F2F2F7 |

### 黑白系

| 颜色名称 | Hex值 |
|----------|-------|
| sys_black | #000000 |
| sys_white | #FFFFFF |

---

## 夜间模式 (Dark Mode)

### 彩色系

| 颜色名称 | Hex值 |
|----------|-------|
| sys_red | #FF453A |
| sys_orange | #FF9F0A |
| sys_yellow | #FFD60A |
| sys_green | #30D158 |
| sys_mint | #66D4CF |
| sys_teal | #40C8E0 |
| sys_cyan | #64D2FF |
| sys_blue | #0A84FF |
| sys_indigo | #5E5CE6 |
| sys_purple | #BF5AF2 |
| sys_pink | #FF375F |
| sys_brown | #AC8E68 |

### VIP配色 (opn48 design)

| 颜色名称 | Hex值 |
|----------|-------|
| vip_golden | #FFBE6B |
| vip_bg | #6F2C02 |

### 灰色系

| 颜色名称 | Hex值 |
|----------|-------|
| sys_gray1 | #8E8E93 |
| sys_gray2 | #636366 |
| sys_gray3 | #48484A |
| sys_gray4 | #3A3A3C |
| sys_gray5 | #2C2C2E |
| sys_gray6 | #1C1C1E |

### 黑白系 (反向)

| 颜色名称 | Hex值 |
|----------|-------|
| sys_black | #FFFFFF |
| sys_white | #000000 |

---

## 使用方式

### iOS — SwiftUI Color

**不要**把下方 hex 写入 Swift。主题色与语义色直接在 View 里写 SwiftUI API：

```swift
.foregroundStyle(Color.primary)
.background(Color(uiColor: .systemBackground))
.tint(appearance.accentColor)   // Color.cyan / .pink / .blue
```

Android hex 表仅用于 Android 资源与跨端设计对照。

### Android (values/colors.xml)

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- 白天模式颜色 (默认) -->
    <color name="sys_red">#FF3B30</color>
    <color name="sys_blue">#007AFF</color>
    <!-- ... 其他颜色 -->
</resources>
```

### Android 夜间模式 (values-night/colors.xml)

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- 夜间模式颜色 -->
    <color name="sys_red">#FF453A</color>
    <color name="sys_blue">#0A84FF</color>
    <!-- ... 其他颜色 -->
</resources>
```

---

## 使用场景

1. **UI组件着色**: Button、Icon、Badge等使用sys_blue等品牌色
2. **状态指示**: 成功(green)、警告(yellow)、错误(red)
3. **文字颜色**: 标题(sys_black/white)、次要文字(sys_gray1/2)
4. **背景色**: 卡片(sys_gray6)、分割线(sys_gray5)
5. **VIP特权**: vip_golden用于VIP标识，vip_bg用于VIP专区背景

---

## 透明度颜色

基于已有配色，在16进制RGB前增加两位十六进制数表示透明度。

### 跨平台透明度格式差异

| 平台 | 格式 | 透明度位置 | 示例 |
|------|------|-----------|------|
| Android (ColorInt) | ARGB | 前两位 | #AA007AFE |
| iOS (UIColor) | RGBA | 后两位 | #007AFEAA |
| CSS / Web | RGBA | 后两位 | #007AFEAA |
| Flutter | 根据传入方式 | - | Color(0xAA007AFE) |

### 格式说明

- **透明度通用规则**: 00 = 完全透明，FF = 完全不透明
- **Android (ARGB)**: 透明度在前，RGB在后
- **iOS / CSS / Web (RGBA)**: RGB在前，透明度在后

### 透明度对照表

| 透明度 | 十六进制值 |
|--------|------------|
| 0% (完全透明) | 00 |
| 5% | 0D |
| 10% | 1A |
| 20% | 33 |
| 30% | 4D |
| 40% | 66 |
| 50% | 80 |
| 60% | 99 |
| 70% | B3 |
| 80% | CC |
| 90% | E6 |
| 100% (完全不透明) | FF |

### 跨平台转换示例

以 50% 透明度 的 #007AFF (蓝色) 为例：

| 平台 | 格式 | 颜色值 |
|------|------|--------|
| Android (XML) | ARGB | #80007AFF |
| Android (Kotlin Color Int) | ARGB | 0x80007AFF |
| iOS (Swift) | RGBA | Color(red: 0.0, green: 0.478, blue: 1.0, opacity: 0.5) 或 #007AFF80 |
| CSS / Web | RGBA | rgba(0, 122, 255, 0.5) 或 #007AFF80 |
| Flutter | 根据使用 | Color(0x80007AFF) |

### 命名规则

格式: `{原色名}_{透明度百分比}`

例如: `sys_red_20` 表示20%透明度的sys_red

### 白天模式示例

| 颜色名称 | Hex值 | 描述 |
|----------|-------|------|
| sys_red_20 | #33FF3B30 | 20%透明度红色 |
| sys_red_50 | #80FF3B30 | 50%透明度红色 |
| sys_blue_20 | #33007AFF | 20%透明度蓝色 |
| sys_gray3_30 | #4DC7C7CC | 30%透明度灰色 |

### 夜间模式示例

| 颜色名称 | Hex值 | 描述 |
|----------|-------|------|
| sys_red_20 | #33FF453A | 20%透明度红色 |
| sys_red_50 | #80FF453A | 50%透明度红色 |
| sys_blue_20 | #330A84FF | 20%透明度蓝色 |
| sys_gray3_30 | #4D48484A | 30%透明度灰色 |

### Android使用示例

```xml
<!-- values/colors.xml (白天) -->
<color name="sys_red_20">#33FF3B30</color>
<color name="sys_blue_50">#80007AFF</color>

<!-- values-night/colors.xml (夜晚) -->
<color name="sys_red_20">#33FF453A</color>
<color name="sys_blue_50">#800A84FF</color>
```

### CSS / Web 使用示例

```css
/* CSS 变量方式 (推荐) */
:root {
    --sys-red: #FF3B30;
    --sys-red-50: rgba(255, 59, 48, 0.5);
    --sys-blue: #007AFF;
    --sys-blue-50: rgba(0, 122, 255, 0.5);
}

/* 直接使用 */
.button-overlay {
    background-color: rgba(255, 59, 48, 0.2);
}

/* 使用8位十六进制 (iOS/CSS兼容) */
.card-overlay {
    background-color: #FF3B3033; /* 20% 透明度 */
}
```

### Flutter 使用示例

```dart
// 使用ARGB格式 (与Android一致)
Color sysRed20 = Color(0x33FF3B30);
Color sysBlue50 = Color(0x80007AFF);

// 使用RGBA参数
Color sysBlue50Alt = Color.fromARGB(128, 0, 122, 255);
```

### 使用场景

1. **遮罩层**: 半透明黑色/白色覆盖层
2. **图标填充**: 图标使用半透明颜色作为填充
3. **背景装饰**: 卡片弱化背景色
4. **边框/分割线**: 使用低透明度颜色作为细微分割

### 注意事项

1. **Android XML**: 透明度放在RGB前面 (ARGB)
2. **iOS / CSS**: 透明度放在RGB后面 (RGBA)
3. **Flutter**: Color() 构造函数使用 ARGB 格式 (0xAARRGGBB)
4. **Web 开发**: 推荐使用 `rgba()` 或 `hsla()` 函数，兼容性好
5. **设计工具**: Sketch/Figma 导出通常是 RGBA 格式，Android 使用需转换