---
title: "DropletIcon, DroppyKit"
description: "The rules a droplet's icon has to satisfy."
canonical: "https://getdroppy.app/docs/droppykit/api/droplet-icon"
last-updated: "2026-09-09"
---

# 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 icon in the Store is an Icon Composer document made in the same style, so a community droplet sits beside Droppy's own without a seam.

## Who makes it

Jordy designs every Store droplet's icon himself, in Icon Composer and in Droppy's current icon style, so it adapts to light, dark, clear and tinted icons and matches the rest of the Store. A droplet's developer does not make one: `droppykit new` writes a placeholder so the harness has something to draw, `droppykit submit` leaves it out of the merge request, and an idea for the icon goes in the merge request's Icon concept section. See [The icon](https://getdroppy.app/docs/droppykit/icons).

## 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`](https://getdroppy.app/docs/droppykit/api/droplet-icon-validation) 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 an icon document that 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/`. A package with no icon document passes, because a submission carries none; the Store's publish job is what refuses a droplet without Jordy's icon.

## 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.

### documentExtension

`static let documentExtension: String`

Alias of `fileExtension`, for call sites that read better naming the document rather than the file.

### 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.