Swatch Methods

Darty's Swatch methods create, update, rename, and merge swatches in the active Illustrator document. They work on document resources rather than tagged artwork, so a Darty tag is not required.

Use Tools → Methods → Swatches to configure Swatch or Merge Swatches and add the resulting method block to Builder. See the Swatches Tool for the visual editor workflow.

See the Swatches Tool for the visual Swatch and Merge Swatches editors.

Available Methods

Method	Purpose	Tools editor
`swatch`	Create a swatch, edit an existing swatch, or rename the swatch selected by name or number.	Swatch
`mergeSwatches`	Recolor artwork from source swatches to a target swatch, then remove the merged source swatches.	Merge Swatches

Method names are normalized when the sheet is processed, so the lowercase form mergeswatches is also accepted.

The swatch method locates a document swatch by swatchName or swatchNumber. If a named swatch does not exist, Darty creates it from the supplied color definition. If it already exists, Darty updates the properties supplied by that data row.

Editing a global or spot swatch can change the appearance of every Illustrator object that uses it. Test edits on a copy of the document when the swatch is already in production artwork.

Identity Properties

Property	Description
swatchName / name	Name of the swatch to create or edit. Supply this or `swatchNumber`. Names containing spaces should be quoted when they appear inside a combined color value.
swatchNumber	Numeric document swatch index used as an alternative to `swatchName`. A name is usually more stable when swatches may be reordered.
newName	New name for the located or newly created swatch. Leave it blank to keep the current name.
library / swatchLibrary	Optional swatch-library name passed to the swatch lookup. This property is accepted in manually authored sheets but is not currently shown in the Tools editor.
skip	Skips this method for the current data row. See * and Skip. Valid Values: `true`, `false`.

At least one of swatchName or swatchNumber is required. Avoid relying on swatchNumber when other rows or users may add, remove, or reorder document swatches.

Color Definition

You can provide the complete color in color, or split the definition across colorSpace and the channel properties. The Tools color control writes the same properties that a spreadsheet can use directly.

Property	Description
color	Combined color definition. Include a color model when the value would otherwise be ambiguous. Examples: `rgb 18 128 74`, `cmyk 86 0 42 50`, `lab 48 -42 19`, `grayscale 35`.
rgb	RGB color values without repeating the model in the data cell. Example: `18 128 74`.
cmyk	CMYK color values without repeating the model in the data cell. Example: `86 0 42 50`.
lab	Lab color values without repeating the model in the data cell. Example: `48 -42 19`.
colorSpace / colorMode	Color model used to interpret channel values. Valid Values: `RGB`, `CMYK`, `Lab`, `Gray`, `Grayscale`.
destColorSpace / destColorMode	Optional Illustrator color space for the stored result when it should differ from the input color space. Valid Values: `RGB`, `CMYK`, `Lab`, `Gray`, `Grayscale`.
channel1 / color1 / c1	RGB red, CMYK cyan, Lab lightness, or grayscale value. Model-specific aliases such as `red`, `r`, `cyan`, `c`, `gray`, `grey`, and `l` are also accepted.
channel2 / color2 / c2	RGB green, CMYK magenta, or Lab a value. Aliases include `green`, `g`, `magenta`, `m`, and `a`.
channel3 / color3 / c3	RGB blue, CMYK yellow, or Lab b value. Aliases include `blue`, `b`, `yellow`, and `y`.
channel4 / color4 / c4	CMYK black value. Aliases: `black`, `k`. It is not used by RGB, Lab, or grayscale colors.

Use these channel ranges:

RGB: red, green, and blue from 0 to 255.
CMYK: cyan, magenta, yellow, and black from 0 to 100.
Lab: L from 0 to 100; a and b from -128 to 127.
Grayscale: one gray value from 0 to 100.

For the complete combined-value syntax, named colors, hex values, and quoting rules, see Appearance - Colors & Swatches.

Process, Global, Spot, and Tint

Property	Description
spot	Sets the Illustrator color type. Use `true` for a spot swatch or `false` for a process swatch.
global	Makes a process swatch global when `true`. Artwork using a global swatch updates when that swatch is edited. Valid Values: `true`, `false`.
tint / customColorTint	Tint percentage for a spot or global color. Valid Values: `0` to `100`.
type	Combined color-type value accepted in manually authored sheets. Valid Values: `spot`, `global`, `process`, `none`. The Tools editor writes `spot` and `global` separately.

When editing an existing swatch, omit classification properties that you do not intend to change. For example, updating only its color channels does not require you to restate whether it is spot, process, or global.

Merge Swatches

mergeSwatches replaces the use of each source swatch with the target swatch, then removes the merged source swatches from the document. This is useful for consolidating duplicate brand colors or normalizing imported artwork.

Property	Description
target	Name of the swatch that should remain after the merge. Set it explicitly so the intended destination is unambiguous.
swatches	Required list of source swatch names to recolor and remove. The Tools editor accepts the names in its Source Swatches field.
skip	Skips this method for the current data row. See * and Skip. Valid Values: `true`, `false`.

Check that target names an existing document swatch and that it is not accidentally repeated in the source list. Swatch names are document resources; no artwork tag is needed in the Darty header.

Rename With the Swatch Method

In the Swatch Tools editor, identify the existing swatch with swatchName or swatchNumber and enter newName. Leave the color, classification, and tint properties unset when the name is the only value that should change.

Property	Description
swatchName / name	Current name of the swatch to rename. Supply this or `swatchNumber`.
swatchNumber	Document index of the swatch to rename when its name is not used.
newName	New name for that swatch.
skip	Skips this method for the current data row. See * and Skip. Valid Values: `true`, `false`.

Sample Spreadsheets

Create Global Process Swatches

This creates two reusable global RGB swatches.


*
swatch
swatchName	color	spot	global	tint
Swatch name	Color	Spot	Global	Tint
Brand Green	rgb 18 128 74	false	true	100
Brand Blue	rgb 38 92 180	false	true	100

Create CMYK Spot Swatches


*
swatch
swatchName	colorSpace	channel1	channel2	channel3	channel4	spot
Swatch name	Model	Cyan	Magenta	Yellow	Black	Spot
Packaging Orange	cmyk	0	58	92	0	true
Packaging Blue	cmyk	82	48	0	0	true

The color markers are approximate RGB previews for the browser. The spreadsheet values remain CMYK, and Illustrator's document color profile can produce a slightly different on-screen result.

Edit and Rename Existing Swatches

These rows change the RGB values of two existing swatches and rename them for the 2026 palette.


*
swatch
swatchName	color	newName
Existing name	Updated color	New name
Brand Green	rgb 10 142 82	Brand Green 2026
Brand Blue	rgb 30 104 196	Brand Blue 2026

Merge Duplicate Swatches

This recolors uses of Bright Green and Imported Green to Brand Green, then removes the two source swatches.


*
mergeSwatches
target	swatches
Target swatch	Source swatches
Brand Green	Bright Green, Imported Green
Brand Blue	Legacy Blue, Imported Blue

Practical Workflow

Create or confirm the target brand swatches before merging imported colors.
Prefer stable swatch names over numeric indexes in reusable sheets.
Use spot: false with global: true for a global process swatch; use spot: true for a spot swatch.
Inspect Illustrator's Swatches panel after creating or editing spot and global colors.
Before merging, save a copy of the document and confirm that the target and source names are exact.