Apply a gradient fill

A gradient in IDML is a named swatch, applied to a shape exactly the way a flat color is.

In short: a Gradient is defined once alongside the document's colors, with two or more GradientStop children that each reference an existing <Color> swatch by id. A shape uses it by pointing its FillColor at the gradient's Self id — the same attribute you'd set to a color — and orients a linear blend with GradientFillAngle on the shape itself. This recipe defines a two-stop linear gradient and fills a rectangle with it.

The recipe

1. Make sure the stop colors exist. A gradient holds no color of its own; each stop references an existing <Color> swatch by id. The example defines Color/Sun and Color/Sky as ordinary CMYK process colors before the gradient uses them.
2. Define the <Gradient> swatch in a Graphic resource part, next to the colors. Give it a Self id (this is what shapes will reference), a Name, and Type="Linear" — the other value is Radial. Mark it Visible="true" so it shows in a swatch panel.
3. Add the <GradientStop> children that define the blend. Each stop references a color with StopColor and places it along the gradient with Location, a percentage from 0 to 100. The example puts Color/Sun at 0 and Color/Sky at 100. Midpoint biases where the halfway blend sits between this stop and the next.
4. Apply it to a shape. Set the shape's FillColor to the gradient's Self id — exactly as you'd set it to a color. In the example's spread, the rectangle carries FillColor="Gradient/SkySun".
5. Orient a linear gradient with GradientFillAngle on the shape. The example uses 90, running the blend top-to-bottom. The angle lives on the shape that uses the gradient, not on the gradient definition — so one gradient can fill several shapes at different angles.

Worked over a filled rectangle

The Resources/Graphic.xml part below defines four colors and one Gradient swatch with two stops. Read it and you'll see the recipe's whole left side; the spread then applies it with a single FillColor.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<idPkg:Graphic xmlns:idPkg="http://ns.adobe.com/AdobeInDesign/idml/1.0/packaging" DOMVersion="20.0">
  <Color Self="Color/Black" Model="Process" Space="CMYK" ColorValue="0 0 0 100" ColorOverride="Specialblack" Name="Black" ColorEditable="false" ColorRemovable="false" Visible="true"/>
  <Color Self="Color/Paper" Model="Process" Space="CMYK" ColorValue="0 0 0 0" ColorOverride="Specialpaper" Name="Paper" ColorEditable="true" ColorRemovable="false" Visible="true"/>
  <Color Self="Color/Sun" Model="Process" Space="CMYK" ColorValue="0 15 90 0" ColorOverride="Normal" Name="Sun" ColorEditable="true" ColorRemovable="true" Visible="true"/>
  <Color Self="Color/Sky" Model="Process" Space="CMYK" ColorValue="70 25 0 0" ColorOverride="Normal" Name="Sky" ColorEditable="true" ColorRemovable="true" Visible="true"/>
  <Gradient Self="Gradient/SkySun" Type="Linear" Name="Sky to Sun" ColorEditable="true" ColorRemovable="true" Visible="true">
    <GradientStop Self="Gradient/SkySun/stop0" StopColor="Color/Sun" Location="0" Midpoint="50"/>
    <GradientStop Self="Gradient/SkySun/stop1" StopColor="Color/Sky" Location="100" Midpoint="50"/>
  </Gradient>
</idPkg:Graphic>

Things to get right

• Define the gradient before it's referenced. A shape's FillColor resolves the id at parse time; if Gradient/SkySun isn't in the resources, the fill has nothing to point at.
• Stops reference colors by id, never by value. You can't inline 0 15 90 0 on a stop — write a <Color> swatch and reference its Self. This is why changing the swatch updates every gradient that uses it.
• Two stops is the minimum; you can add more. Each extra <GradientStop> adds a band; keep them ordered by ascending Location.
• GradientFillAngle is ignored by a radial gradient. It only orients Linear gradients; a Radial blend runs from center outward regardless.
• A tint is a different mechanism. If you want a lighter version of one color rather than a blend between two, that's a tint, not a gradient — see gradients & tints.

For how the palette is structured — named colors, process vs. spot, and where swatches are defined — see Color & swatches.

Frequently asked questions

How does a shape reference a gradient? A shape points its FillColor at the gradient's Self id — exactly as it would point at a color. In the example the rectangle carries FillColor="Gradient/SkySun". There is no separate gradient-fill attribute; the same FillColor slot takes either a color id or a gradient id.

Do gradient stops store their own colors? No. A gradient holds no color of its own — each <GradientStop> references an existing <Color> swatch through its StopColor attribute. You can't inline a CMYK value on a stop; you write a <Color> swatch (the example defines Color/Sun and Color/Sky) and reference its id. That indirection is why editing one swatch updates every gradient that uses it.

How do I control the direction of a linear gradient? Set GradientFillAngle on the shape, not on the gradient definition. The example uses 90, running the blend top-to-bottom. Because the angle lives on the shape, one gradient swatch can fill several shapes at different angles. A Radial gradient ignores GradientFillAngle and always runs from its center outward.

What's the difference between a gradient and a tint? A gradient blends between two or more colors across a shape; a tint is a lighter version of a single color. If you want one color at reduced strength rather than a blend, that's a tint — see gradients & tints.