What is really fun with InDesign swatches is that, depending on how the user manipulates the document, it may sometimes verify the following assertion:
doc.swatches.length < doc.unusedSwatches.length
which at first glance seems absurd.
In fact, the concept of swatch has two different scopes according to the context—yes, this is very confusing!
(1) A Swatch_1 (primary meaning) usually refers to an "abstract class" that addresses as well: colors, tints, gradients, mixed inks, mixed ink groups, and even a special instance, the [None] swatch (the only element whose actual cast is Swatch).
(2) A Swatch_2 (secondary meaning) refers to a NAMED Swatch_1, i.e. an element that is shown in the Swatches panel (and whose name property is defined).
The doc.swatches collection only sees Swatch_2 elements, while the doc.unusedSwatches array may also contain Swatch_1 elements, i.e. anonymous colors or tints that are not used in the layout but still exist behind the scene.
To my knowledge, an anonymous Swatch_1 can only be of type Color or Gradient. Each time the user plays with the sliders in the Colors panel or in the Gradients panel, I think InDesign mutely creates the corresponding anonymous Swatch_1 elements, which increases the unusedSwatches count!
Note that unused swatches and anonymous swatches are two really different things. An anonymous Swatch_1 may be in use (e.g. the user locally applies an unnamed color) and conversely a strict named Swatch_2 may be unused (as shown by the "Select All Unused" feature).
A serious limitation of the DOM is that we have no direct access to all anonymous swatches as such.
It is possible to investigate on the anonymous swatches in use through:
app.menuActions.itemByName("$ID/Add All Unnamed Colors").invoke(); // only target anonymous swatches IN USE
but the obscure swatches which are both anonymous and unused won't appear. Therefore it is quite difficult to analyze in depth these elements via a script. Maybe IDML is more verbose on that question…
Helpful as always Marc. Another problem with doc.unusedSwatches, if I remember right, is that it may contain colors that, while not used directly in the layout, are used in gradient objects—so removing them will mess up any gradients that rely on them. Showing unnamed colors and getting rid of unused swatches is maybe the only area where I rely on invoking menu actions (and even that often doesn't work, due to swatches that are selected by "Select All Unused" but then can't be removed!).
If the idml is any guide, it doesn't look like a new color is saved every time you adjust the sliders in the color palette. It looks like the document default is saved, if that's anonymous, but if you color an object by adjusting the sliders and then delete that object, the color doesn't appear in the idml. The color objects have some intriguing-looking hidden properties:
<Color Self="Color/ue4" Model="Process" Space="CMYK" ColorValue="0 55.00000000000001 75 0" ColorOverride="Normal" AlternateSpace="NoAlternateColor" AlternateColorValue="" Name="$ID/" ColorEditable="true" ColorRemovable="true" Visible="false" SwatchCreatorID="7937"/>
With some stubborn unused swatches that won't delete even after an idml round-trip, I've manually changed that ColorRemovable to "true" and InDesign has allowed me to remove the swatch.
Thanks for the very clear explanation, we are learning lots of things from your end.