ColorKit Skill
Overview
This skill provides expert guidance on ColorKit, a powerful, cross-platform Swift library for advanced color management. It covers advanced color creation (Hex, OKLAB, HSL), professional blending modes, precise color space transformations with perceptual gamut mapping, and comprehensive accessibility checks using WCAG and APCA standards. Use this skill to help developers implement sophisticated color logic and ensure UI accessibility across all Apple platforms.
Agent Behavior (Follow These Rules)
- 1. Clarify Color Space Needs: Always identify if the user needs standard sRGB or wide-gamut (Display P3, Adobe RGB) support before recommending conversion methods.
- Prioritize CKColor: Encourage the use of
CKColor as the unified entry point for all color operations, as it handles platform-specific differences and color space metadata automatically. - Recommend Perceptual Mapping: When converting between gamuts, suggest using
converted(to:iterations:) for OKLAB-based perceptual mapping to preserve visual intent. - Emphasize Accessibility: Proactively mention APCA (
isAPCAAccessible) for modern typography contrast needs, alongside traditional WCAG ratios. - Dynamic Colors: Always consider system appearance (Light/Dark mode) when suggesting color initializers, favoring those that support adaptive variants.
- Contextual Bridges: Provide clear examples of bridging
CKColor to native types like Color, UIColor, or NSColor when UI integration is the goal.
Project Settings
ColorKit's behavior is influenced by the project's deployment targets and Swift version.
- - Deployment Targets: iOS 13.0+, macOS 10.15+, tvOS 13.0+, watchOS 6.0+, and visionOS 1.0+.
- Swift Version: Requires Swift 5.9+.
If these are unknown, ask the developer to confirm them, especially when discussing HDR or wide-gamut features.
Quick Decision Tree
When a developer needs ColorKit guidance, follow this decision tree:
- 1. Creating a new color?
* From Hex string/int →
references/CKColor.md
* Using specific models (OKLAB, HSL, CMYK) →
references/ColorModels.md
* Adaptive for Light/Dark mode → INLINECODE10
- 2. Converting between color spaces?
* Basic conversion or Perceptual Gamut Mapping →
references/ColorOperations.md
* Handling wide-gamut (P3, Adobe RGB) → INLINECODE12
- 3. Performing accessibility checks?
* WCAG 2.1 Contrast Ratio →
references/Accessibility.md
* APCA (WCAG 3.0) Perceptual Contrast →
references/Accessibility.md
* Font-specific readability → INLINECODE15
- 4. Blending or modifying colors?
* Photoshop-style blending (Multiply, Overlay, etc.) →
references/Blending.md
* Adjusting opacity, lightness, or saturation → INLINECODE17
- 5. Integrating with UI frameworks?
* SwiftUI (
Color,
ShapeStyle) →
references/NativeBridges.md
* UIKit/AppKit (
UIColor,
NSColor) →
references/NativeBridges.md
* Core Graphics/Image (
CGColor,
CIColor) → INLINECODE26
- 6. Storing or persisting colors?
* Using
Codable or
Sendable → INLINECODE29
Triage-First Playbook
- - "My colors look different after conversion."
* Explain gamut clipping and recommend using
converted(to:iterations:) for perceptual mapping. Refer to
references/ColorOperations.md.
- - "How do I support Dark Mode with custom colors?"
* Show how to use
CKColor initializers that take both light and dark variants. Refer to
references/CKColor.md.
- - "Is my text readable on this background?"
* Guide them through using
isAPCAAccessible with specific font size and weight. Refer to
references/Accessibility.md.
- - "I get a compiler error when using CKColor in SwiftUI."
* Remind them that
CKColor conforms to
ShapeStyle directly, but they might need
.color property for some modifiers. Refer to
references/NativeBridges.md.
Core Patterns Reference
Basic Initialization & Usage
CODEBLOCK0
Advanced Operations
CODEBLOCK1
Accessibility Check
CODEBLOCK2
Integration Quick Guide
ColorKit is integrated via Swift Package Manager.
- 1. Add Package Dependency: In Xcode, go to File > Add Package Dependency and enter
https://github.com/SzpakKamil/ColorKit.git. - Import:
import ColorKit in your Swift files. - Deployment Targets: iOS 13.0+, macOS 10.15+, tvOS 13.0+, watchOS 6.0+, visionOS 1.0+ (Swift 5.9+).
For detailed setup, see references/Setup.md.
Reference Files
Load these files as needed for specific topics:
- -
ColorKit.md - General overview and key capabilities. Setup.md - Installation and project integration.CKColor.md - Detailed documentation for the core CKColor struct, initializers, and persistence.ColorOperations.md - Conversion, gamut mapping, and basic modifications.ColorModels.md - Using specialized models like OKLAB, HSL, CMYK, etc.NativeBridges.md - Integration with SwiftUI, UIKit, AppKit, and Core Graphics.Accessibility.md - WCAG and APCA contrast calculations and readability checks.Blending.md - Advanced blending modes and transparency handling._index.md - A comprehensive index for all ColorKit reference documentation.
Best Practices Summary
- 1. Use CKColor Everywhere: It serves as a universal color type that simplifies cross-platform logic.
- Prefer APCA for Text: APCA provides better perceptual accuracy for modern typography than traditional WCAG 2.1.
- Always Map Gamuts: Use perceptual mapping when moving from wide gamuts (P3) to narrow ones (sRGB) to avoid "dead" colors.
- Leverage ShapeStyle: Take advantage of
CKColor's direct conformance to ShapeStyle in SwiftUI for cleaner code. - Stay Adaptive: Use adaptive initializers to ensure your UI looks great in both Light and Dark modes without extra logic.
Note: This skill is based on the comprehensive documentation for ColorKit. For further details, visit the official documentation at documentation.kamilszpak.com/documentation/colorkit/ or the project website at kamilszpak.com/pl/colorkit.
ColorKit 技能
概述
本技能提供关于 ColorKit 的专业指导，这是一个功能强大的跨平台 Swift 库，专为高级色彩管理而设计。涵盖高级色彩创建（Hex、OKLAB、HSL）、专业混合模式、带感知色域映射的精确色彩空间转换，以及基于 WCAG 和 APCA 标准的全面无障碍检查。使用此技能可帮助开发者实现复杂的色彩逻辑，并确保所有 Apple 平台上的 UI 无障碍性。
代理行为（遵循以下规则）
- 1. 明确色彩空间需求： 在推荐转换方法前，始终确认用户需要标准 sRGB 还是广色域（Display P3、Adobe RGB）支持。
- 优先使用 CKColor： 鼓励使用 CKColor 作为所有色彩操作的统一入口点，因为它能自动处理平台特定差异和色彩空间元数据。
- 推荐感知映射： 在色域间转换时，建议使用 converted(to:iterations:) 进行基于 OKLAB 的感知映射，以保留视觉意图。
- 强调无障碍性： 主动提及 APCA（isAPCAAccessible）以满足现代排版对比度需求，同时兼顾传统 WCAG 比率。
- 动态色彩： 在建议色彩初始化器时，始终考虑系统外观（浅色/深色模式），优先选择支持自适应变体的初始化器。
- 上下文桥接： 当目标是 UI 集成时，提供将 CKColor 桥接到原生类型（如 Color、UIColor 或 NSColor）的清晰示例。
项目设置
ColorKit 的行为受项目的部署目标和 Swift 版本影响。
- - 部署目标： iOS 13.0+、macOS 10.15+、tvOS 13.0+、watchOS 6.0+ 和 visionOS 1.0+。
- Swift 版本： 需要 Swift 5.9+。
如果这些信息未知，请要求开发者确认，尤其是在讨论 HDR 或广色域功能时。
快速决策树
当开发者需要 ColorKit 指导时，请遵循此决策树：
- 1. 创建新颜色？
* 从 Hex 字符串/整数 → references/CKColor.md
* 使用特定模型（OKLAB、HSL、CMYK） → references/ColorModels.md
* 适应浅色/深色模式 → references/CKColor.md
- 2. 在色彩空间之间转换？
* 基本转换或感知色域映射 → references/ColorOperations.md
* 处理广色域（P3、Adobe RGB） → references/ColorOperations.md
- 3. 执行无障碍检查？
* WCAG 2.1 对比度比率 → references/Accessibility.md
* APCA（WCAG 3.0）感知对比度 → references/Accessibility.md
* 特定字体的可读性 → references/Accessibility.md
- 4. 混合或修改颜色？
* Photoshop 风格混合（正片叠底、叠加等） → references/Blending.md
* 调整不透明度、亮度或饱和度 → references/ColorOperations.md
- 5. 与 UI 框架集成？
* SwiftUI（Color、ShapeStyle） → references/NativeBridges.md
* UIKit/AppKit（UIColor、NSColor） → references/NativeBridges.md
* Core Graphics/Image（CGColor、CIColor） → references/NativeBridges.md
- 6. 存储或持久化颜色？
* 使用 Codable 或 Sendable → references/CKColor.md
分类优先剧本
* 解释色域裁剪，并推荐使用 converted(to:iterations:) 进行感知映射。参考 references/ColorOperations.md。
* 展示如何使用同时接受浅色和深色变体的 CKColor 初始化器。参考 references/CKColor.md。
* 指导他们使用带有特定字体大小和字重的 isAPCAAccessible。参考 references/Accessibility.md。
- - 在 SwiftUI 中使用 CKColor 时出现编译器错误。
* 提醒他们 CKColor 直接遵循 ShapeStyle，但某些修饰符可能需要 .color 属性。参考 references/NativeBridges.md。
核心模式参考
基本初始化与使用
swift
import ColorKit
// Hex 初始化
let brand = CKColor(hexString: #007AFF)
// 自适应颜色
let adaptive = CKColor(hexString: #007AFF, hexStringDark: #0A84FF)
// 在 SwiftUI 中使用
Circle().fill(adaptive)
高级操作
swift
// 感知转换为 sRGB
let p3 = CKColor(red: 1.0, green: 0.0, blue: 0.0, colorSpace: .displayP3)
let sRGB = p3.converted(to: .sRGB, iterations: 6)
// 混合
let blended = brand.blended(with: .black, mode: .multiply, opacity: 0.5)
无障碍检查
swift
let bg = CKColor.white
let isAccessible = brand.isAPCAAccessible(on: bg, size: 16, weight: .regular)
集成快速指南
ColorKit 通过 Swift Package Manager 集成。
- 1. 添加包依赖： 在 Xcode 中，转到 File > Add Package Dependency 并输入 https://github.com/SzpakKamil/ColorKit.git。
- 导入： 在 Swift 文件中使用 import ColorKit。
- 部署目标： iOS 13.0+、macOS 10.15+、tvOS 13.0+、watchOS 6.0+、visionOS 1.0+（Swift 5.9+）。
有关详细设置，请参阅 references/Setup.md。
参考文件
根据需要加载这些文件以获取特定主题：
- - ColorKit.md - 总体概述和关键功能。
- Setup.md - 安装和项目集成。
- CKColor.md - 核心 CKColor 结构体、初始化器和持久化的详细文档。
- ColorOperations.md - 转换、色域映射和基本修改。
- ColorModels.md - 使用专用模型，如 OKLAB、HSL、CMYK 等。
- NativeBridges.md - 与 SwiftUI、UIKit、AppKit 和 Core Graphics 的集成。
- Accessibility.md - WCAG 和 APCA 对比度计算及可读性检查。
- Blending.md - 高级混合模式和不透明度处理。
- _index.md - 所有 ColorKit 参考文档的综合索引。
最佳实践总结
- 1. 处处使用 CKColor： 它作为一个通用颜色类型，简化了跨平台逻辑。
- 文本优先使用 APCA： APCA 为现代排版提供了比传统 WCAG 2.1 更好的感知准确性。
- 始终进行色域映射： 从广色域（P3）转换到窄色域（sRGB）时，使用感知映射以避免死颜色。
- 利用 ShapeStyle： 在 SwiftUI 中利用 CKColor 直接遵循 ShapeStyle 的特性，以获得更简洁的代码。
- 保持自适应： 使用自适应初始化器，确保您的 UI 在浅色和深色模式下都看起来很棒，无需额外逻辑。
注意： 本技能基于 ColorKit 的全面文档。有关更多详细信息，请访问官方文档 documentation.kamilszpak.com/documentation/colorkit/ 或项目网站 kamilszpak.com/pl/colorkit。
