DropletIcon

The rules a droplet's icon has to satisfy.

enum DropletIcon

Why Icon Composer, and not a PNG

Droppy draws a droplet's icon at seven sizes, on light and dark chrome, behind glass, and — in the Store's rows — beside a circular creator avatar. A flat PNG can only be right at one of those. An Icon Composer document carries the layers and their per-appearance specializations, so the host composes the correct thing for each surface instead of scaling one bitmap seven ways.

It is also what stops third-party droplets from looking bolted on. Every first-party droplet's icon is an Icon Composer document; a community droplet that ships one sits beside them without a seam.

Making one

Icon Composer ships with Xcode 26 and later: Xcode ▸ Open Developer Tool ▸ Icon Composer. droppykit new puts a starter document in your droplet already wired to the right filename, so the quickest route is to open that and replace the artwork.

What the document is

A .icon is a directory, not a single file:

WorldClock.icon/
  icon.json          the document: groups, layers, fills, specializations
  Assets/
    dial.png         every image icon.json refers to by `image-name`

icon.json holds groups, each with layers, plus optional fill-specializations and supported-platforms. Layer names are yours; Droppy does not require particular ones. What it requires is that the document is well formed and self-contained, which is what DropletIconValidation checks.

Geometry

  • Artwork is authored on a 1024×1024 square canvas.
  • Keep the mark inside the centre 820×820. macOS rounds the corners and the Store clips further; anything outside that box is cut.
  • Do not draw your own rounded rectangle and do not bake in a shadow. Icon Composer's own shadow on the group does that, and a painted-in one shows as a double edge.

What is checked, and what is not

Scripts/validate-droplet.sh refuses a droplet whose icon is missing, is not a directory ending in .icon, has no readable icon.json, declares no layers, or refers to an image that is not in Assets/. It cannot check whether the artwork is any good — that is what review is for.

Type properties

assetsDirectoryName

static let assetsDirectoryName: String

The directory inside the .icon directory holding layer images.

canvasSize

static let canvasSize: CGFloat

Edge length of the icon canvas, in pixels.

documentFileName

static let documentFileName: String

The document inside the .icon directory.

fileExtension

static let fileExtension: String

Filename extension of an Icon Composer document.

safeAreaSize

static let safeAreaSize: CGFloat

Edge length of the area artwork must stay inside, in pixels.

smallestRenderedSize

static let smallestRenderedSize: CGFloat

Smallest size the Store renders a droplet icon at, in points. Artwork that becomes a smudge here needs to be simpler, not sharper.