为什么值得关注

苹果未将 icon.json 的 schema 作为公共 API 发布，这个基于实际文件推导的参考填补了开发者在处理 Icon Composer 文件时的关键空白。

适合谁使用

开发图标生成或检查工具的程序员
使用 Icon Composer 的 macOS/iOS 开发者
验证图标文件跨系统兼容性的质量工程师

典型使用场景

解析并验证现有的 .icon 包以便迁移或测试
以编程方式生成新的 .icon 包以实现自动化图标创建
编辑构图属性，如填充、渐变、图层和外观特殊化设置

项目优势

开放字符串支持的枚举值允许解码未来的混合模式、外观和平台，无需等待包更新
通过 IconColor 保留原始色彩空间和精度，避免转换为平台特定类型
基于真实文件支持复杂的特殊化机制和多种 JSON 表示形式（如 blur 与 blur-material）

使用前须知

模式基于经验推导，可能未覆盖所有 Icon Composer 版本或边界情况
未知属性以 JSONValue 形式存储，需要手动映射才能实现完全无损的往返
未来 Icon Composer 更新可能引入新属性，需更新包以避免数据丢失

README 快速开始

IconComposerModel

IconComposerModel is a Swift package and a living reference for the contents of Apple Icon Composer's icon.json file. It is intended for apps and tools that need to inspect, generate, or modify .icon packages.

[!IMPORTANT] Apple documents how to use Icon Composer, but does not currently publish the icon.json schema as a public API. This reference is empirical. It will be updated from real files produced by different Icon Composer versions.

Add the package

Add this repository as a Swift Package dependency, then import the library:

import IconComposerModel

let iconJSON = iconPackageURL.appending(path: "icon.json")
let icon = try IconComposerIcon.decode(contentsOf: iconJSON)

print(icon.groups.count)
print(icon.groups.flatMap(\.layers).map(\.name))

To encode a modified model:

let data = try icon.encoded()
try data.write(to: iconJSON, options: .atomic)

The package uses open, string-backed values for evolving options such as blend modes and appearances. A newer value can therefore be decoded without waiting for a package update.

Package layout

A saved .icon file is a package (a directory presented as one file in Finder):

AppIcon.icon/
├── icon.json
└── Assets/
    ├── Background.svg
    └── Symbol.png

icon.json describes composition and rendering. The Assets directory contains the SVG or bitmap artwork named by image-name.

Attribute reference

Unless noted otherwise, attributes are optional. Icon Composer commonly omits a property when it has its default value.

Top-level icon

JSON attribute	Swift property	Meaning
`fill`	`fill`	Background fill used when no appearance-specific fill overrides it.
`fill-specializations`	`fillSpecializations`	Background fills for particular appearances.
`color-space-for-untagged-svg-colors`	`colorSpaceForUntaggedSVGColors`	Interprets colors in imported SVGs that have no embedded color-space tag. Observed values: `srgb`, `display-p3`.
`groups`	`groups`	Ordered collection of Liquid Glass groups that make up the icon.
`supported-platforms`	`supportedPlatforms`	Declares which enclosure families/platforms the design supports.

Fill

A fill is normally an object with one of these attributes:

JSON form	Meaning
`{"solid": ""}`	One flat co

icon-composer-template