Safari, Chrome, and Firefox all seem fine with PNG icons so I think we don't need to deal with actual .ico icons.

We have a large number of favicon assets, but may are not referenced or mis-referenced. I plan to dynamically composite all of them instead.

To customize this:

• Upload one or more images to Files.
  • They must be SQUARE.
  • They should probably be PNGs.
  • 64x64 is a good place to start. The other sizes we currently use are 76x76, 120x120, and 152x152 but these are only for Apple/iOS icons.
• Grab the PHID for your image with file.search or by peeking at the database.

In local.json or a custom config file, configure:

"ui.favicons": [
  {
    "source": "PHID-FILE-i5lhyb7yez6kkydkkyct",
    "width": 612,
    "height": 612
  }
],

Width and height should be correct, and specified in pixels. This option is currently documented nowhere but this comment.

You can provide multiple sizes and we'll try to automatically select the best size. This may be useful if you want to carefully use your real skill with graphics manipulation to scale the image down in a nonlinear way (for example, by making outlines relatively thicker or actually redrawing the icon at small sizes). Just resizing it in Photoshop probably won't do much better than the automatic resize.

The above file is this image:

With the configuration above, I get this favicon behavior:

The resizer should respect alpha channels and transparency if you want to do it right, I just didn't bother since magic wanding the background got all the zebra stripes too. I didn't think my example image through very well.

Additionally, we'll automatically composite "emblems" onto the icon to show status information, like the pink "unread messages" dot:

You can specify new emblems at multiple scales using ui.favicons, but don't. Or do, but don't tell me about it.

Currently, we specify two emblems ("dot-red", "dot-pink") and use only one ("dot-pink" to indicate unread messages).

We support four independent emblem locations (upper right, lower right, lower left, upper left) and use only one (upper right).

For example, here's the zebra composited to 420x420 with emblems (clockwise): "dot-red", null, "dot-pink", "dot-red". This looks awful because it's scaled up and we only ship with lower-resolution assets for the dot emblems, but it should be reasonably easy to see what's going on. Note the alpha channel blending where the dot emblems overlay the zebra's stripes:

We may use the other emblem locations in the future to indicate things like build status, bulk job status, notifications, etc.; or to let you play a very small game of connect 4 called "connect 2".

(This still needs documentation and validation for the configuration option before it's done, but I don't have any short-term plans to pursue those.)

validation for the configuration option

This should include loading the files and their data, see D19406.

Can't wait for "connect 2" to come out on playstation six.