技能：icns-maker

概述

此技能将 PNG 图标转换为符合 macOS 现代设计规范的 .icns 格式。

自 macOS Big Sur 起，系统图标采用了统一的 Squircle（连续圆角矩形）视觉网格。在 1024×1024 像素的画布中，实体主体推荐尺寸约为 824×824 像素，四周预留约 100px 的透明外边距（Margin / Padding）。直接将撑满 1024×1024 画布的全出血（Full-bleed）图像压制为 .icns 会导致图标在 Dock 和 Finder 中视觉明显膨胀、过大。

本技能通过 macOS 自带的 sips 与 iconutil 自动进行主体缩放、边缘透明垫补，并生成标准的 10 阶分辨率 .iconset 打包为 .icns。

关键词: macOS 图标, icns, iconset, iconutil, sips, 边距补正, Big Sur, 图标制作

何时使用此技能

• 从 Figma、Sketch 或 Icon Composer 导出了全出血的 1024×1024 PNG 图标，需要制作合成 .icns。
• 发现现有的 .icns 在 macOS Dock 或应用程序列表中比系统自带 App 图标明显大上一圈。
• 需要将包含多套不同尺寸（如 *-16@1x.png 到 *-1024@1x.png）的导出目录批量打包为各自独立的 .icns。

工作流程

1. 命令行调用

本技能脚本统一放置在 scripts/ 目录下，提供 Python 原生脚本与 Shell 便捷入口。

单图转换

# 自动垫回透明留白（主体 824px，外扩回 1024px），在同目录生成 AppIcon.icns
python3 <path_to_skill>/scripts/make_icns.py AppIcon.png

# 指定输出文件路径
python3 <path_to_skill>/scripts/make_icns.py AppIcon.png -o /path/to/output.icns

目录批量处理

当指定一个目录时，脚本会自动聚合同组的多分辨率 PNG（如 prefix-1024@1x.png, prefix-512@1x.png 等），挑选最高分辨率文件作为 Master 进行生成：

# 批量处理整个导出目录
python3 <path_to_skill>/scripts/make_icns.py ~/Downloads/my-icons/

# 或通过 shell 包装脚本
/bin/bash <path_to_skill>/scripts/run.sh ~/Downloads/my-icons/

2. 常用参数

• --subject-size <N>：主体在 1024 画布中的缩放尺寸，默认 824。
• --full-bleed：原图若已内嵌留白，开启此参数将不额外添加透明外边距。
• -b, --backup：若目标 .icns 文件已存在，先将其备份到 backup_fullbleed_icns/ 目录再替换。
• -v, --verbose：输出每一步处理的详细日志。

3. 底层标准与分辨率映射

生成的 .iconset 包含 Apple 规范所要求的全套 10 阶资产：

• icon_16x16.png (16×16)
• icon_16x16@2x.png (32×32)
• icon_32x32.png (32×32)
• icon_32x32@2x.png (64×64)
• icon_128x128.png (128×128)
• icon_128x128@2x.png (256×256)
• icon_256x256.png (256×256)
• icon_256x256@2x.png (512×512)
• icon_512x512.png (512×512)
• icon_512x512@2x.png (1024×1024)

最终调用 iconutil -c icns <name>.iconset -o <name>.icns 完成二进制打包，并自动清理中间 .iconset 目录。

最佳实践

• 源图要求：尽量提供 1024×1024 像素、带透明通道（Alpha）的高清 PNG 格式源图。
• 圆角注意：若源图是带 Squircle 圆角的矩形，请确保背景是透明而非纯白色；如果原图不是圆角，在未做遮罩前补边距仍会保留方角。
• 安全替换：如果是在既有项目或导出目录中重新压制图标，建议加上 -b 参数以保留原始 .icns 备份。

常见陷阱

• 环境依赖：依赖 macOS 系统原生自带的 /usr/bin/sips 和 /usr/bin/iconutil，不支持在 Linux 或 Windows 容器下直接运行。
• 重名冲突：批量模式下默认以公共前缀命名输出文件（如 gemini-iOS-Default.icns）。