17.3.5 Shading Properties

This common complex type specifies the set of attributes used to define a object’s shading.

[Example: Consider the following paragraph shading:

<w:pPr>
  <w:shd w:val="pct20" w:themeColor="accent6" w:themeFill="accent3" />
</w:pPr>

The resulting paragraph uses the background color accent3 under the foreground pattern color accent6 as specified by the pct20 pattern mask. end example]

Attributes

fill (Shading Background Color)

Specifies the color used for the background for this shading.

This color can either be presented as a hex value (in RRGGBB format), or auto to allow a consumer to automatically determine the background shading color as appropriate.

If this attribute is omitted, then its value shall be assumed to be auto.

[Example: Consider a shading using a background color of hex value C3D69B, using the following WordprocessingML:

  <w:shd w:val="pct15" w:fill="C3D69B" />

The background color for this shading therefore is a color with a hex value of C3D69B. end example]

If the shading specifies the use of a theme color via the themeFill attribute, then this value is superseded by the theme color value.

The possible values for this attribute are defined by the ST_HexColor simple type (17.18.38).

color (Shading Pattern Color)

Specifies the color used for any foreground pattern specified for this shading using the val attribute.

This color can either be presented as a hex value (in RRGGBB format), or auto to allow a consumer to automatically determine the foreground shading color as appropriate.

If the shading style (the val attribute) specifies the use of no shading format or is omitted, then this property has no effect. Also, if the shading specifies the use of a theme color via the themeColor attribute, then this value is superseded by the theme color value.

If this attribute is omitted, then its value shall be assumed to be auto.

[Example: Consider a shading of style pct20 with a foreground color value of auto, as follows:

  <w:shd w:val="pct20"… w:color="auto"/>

The foreground color for this shading pattern therefore can be automatically be modified by a consumer as appropriate, for example, in order to ensure that the shading color can be distinguished against the page’s background color. end example]

The possible values for this attribute are defined by the ST_HexColor simple type (17.18.38).

themeFill (Shading Background Theme Color)

Specifies a theme color which should be applied to the background for this shading.

The specified theme color is a reference to one of the predefined theme colors, located in the document’s themes part, which allows for color information to be set centrally in the document.

If this attribute is omitted, then no theme color is applied, and the fill attribute shall be used to determine the shading background color.

[Example: Consider a paragraph which must have a background consisting of a theme

color accent3 with a theme color accent6 overlaid using a 20% fill pattern. This requirement is specified using the following WordprocessingML:

  <w:shd w:val="pct20" w:themeColor="accent6"
  w:themeFill="accent3" />

The resulting shading uses the background color specified by the accent3 theme color. end example]

The possible values for this attribute are defined by the ST_ThemeColor simple type (17.18.97).

themeColor (Shading Pattern Theme Color)

Specifies a theme color which should be applied to any foreground pattern specified for this shading using the val attribute.

The specified theme color is a reference to one of the predefined theme colors, located in the document’s themes part, which allows for color information to be set centrally in the document.

If this attribute is omitted, then no theme color is applied, and the color attribute shall be used to determine the shading pattern color.

[Example: Consider a paragraph which must have a background consisting of a theme color accent3 with a theme color accent6 overlaid using a 20% fill pattern. This requirement is specified using the following WordprocessingML:

  <w:pPr>
    <w:shd w:val="pct20" w:themeColor="accent6"
  w:themeFill="accent3" />
  </w:pPr>

The resulting paragraph uses the foreground pattern color accent6 in the region specified by the pct20 pattern mask. end example]

The possible values for this attribute are defined by the ST_ThemeColor simple type (17.18.97).

themeFillShade (Shading Background Theme Color Shade)

Specifies the shade value applied to the supplied theme color (if any) for this shading color.

If the themeFillShade is supplied, then it is applied to the RGB value of the themeFill color (from the theme part) to determine the final color applied to this border.

The themeFillShade value is stored as a hex encoding of the shade value (from 0 to 255) applied to the current border.

[Example: Consider a shade of 40% applied to a background shading color in a document. This shade is calculated as follows:

$$ 𝑆 _{𝑥𝑚𝑙} = 0.4 ∗ 255\\ = 102\\ = 66(ℎ𝑒𝑥) $$

The resulting themeFillShade value in the file format would be 66. end example]

Given an RGB color defined as three hex values in RRGGBB format, the shade is applied as follows:

Convert the color to the HSL color format (values from 0 to 1)
Modify the luminance factor as follows:

$$ L ^{′} = L ∗ Shade _{percentage}\\ $$

Convert the resultant HSL color to RGB

[Example: Consider a document with a background using the accent2 theme color, whose RGB value (in RRGGBB hex format) is C0504D.

The equivalent HSL color value would be ($1/360$,0.48,0.53).

Applying the shade formula with a shade percentage of 75% to the luminance, we get:

$$ 𝐿 ^{′} = 0.53 ∗ 0.75\\ = 0.39698 $$

Taking the resulting HSL color value of ($1/360$,0.48,0.39698)and converting back to RGB, we get 943634. This transformed value can be seen in the resulting shading’s fill attribute:

  <w:shd w:val="pct15" w:fill="943634" w:themeFill="accent2"
    w:themeFillShade="BF" />

end example]

The possible values for this attribute are defined by the ST_UcharHexNumber simple type (17.18.98).

themeFillTint (Shading Background Theme Color Tint)

Specifies the tint value applied to the supplied theme color (if any) for this shading instance.

If the themeFillTint is supplied, then it is applied to the RGB value of the themeFill color (from the theme part) to determine the final color applied to this border.

The themeFillTint value is stored as a hex encoding of the tint value (from 0 to 255) applied to the current border.

[Example: Consider a tint of 60% applied to a border in a document. This tint is calculated as follows:

$$ 𝑇 _{𝑥𝑚𝑙} = 0.6 ∗ 255\\ = 153\\ = 99(ℎ𝑒𝑥) $$

The resulting themeFillTint value in the file format would be 99. end example]

Given an RGB color defined as three hex values in RRGGBB format, the shade is applied as follows:

Convert the color to the HSL color format (values from 0 to 1)
Modify the luminance factor as follows:

$$ L ^{′} = L ∗ Tint + (1 − Tint )\\ L = L ∗ Tint + (1 − Tint )\\ $$

Convert the resultant HSL color to RGB

[Example: Consider a document with a background using the accent2 theme color, whose RGB value (in RRGGBB hex format) is 4F81BD.

The equivalent HSL color value would be ($213/360$,0.45,0.53).

Applying the tint formula with a tint percentage of 60% to the luminance, we get:

$$ 𝐿 ^{′} = 0.53 ∗ 0.6 + (1 − .6)\\ = 0.71 $$

Taking the resulting HSL color value of ($213/360$,0.45,0.71)and converting back to RGB, we get 95B3D7. This transformed value can be seen in the resulting shading’s fill attribute:

  <w:top w:val="single" w:sz="4" w:space="24"
    w:fill="95B3D7" w:themeFillColor="accent2"
    w:themeFillTint="99" />

end example]

The possible values for this attribute are defined by the ST_UcharHexNumber simple type (17.18.98).

themeShade (Shading Pattern Theme Color Shade)

Specifies the shade value applied to the supplied theme color (if any) for this shading color.

If the themeTint is supplied, the value of this attribute shall be ignored.

If the themeShade is supplied, then it is applied to the RGB value of the themeColor color (from the theme part) to determine the final color applied to this border.

The themeShade value is stored as a hex encoding of the shade value (from 0 to 255) applied to the current border.

[Example: Consider a shade of 40% applied to a background shading color in a document. This shade is calculated as follows:

$$ 𝑆 _{𝑥𝑚𝑙} = 0.4 ∗ 255\\ = 102\\ = 66(ℎ𝑒𝑥) $$

Te resulting themeShade value in the file format would be 66. end example]

Given an RGB color defined as three hex values in RRGGBB format, the shade is applied as follows:

Convert the color to the HSL color format (values from 0 to 1)
Modify the luminance factor as follows:

$$ L ^{′} = L ∗ Shade _{percentage}\\ $$

Convert the resultant HSL color to RGB

[Example: Consider a document with a background using the accent2 theme color, whose RGB value (in RRGGBB hex format) is C0504D.

The equivalent HSL color value would be ($1/360$,0.48,0.53).

Applying the shade formula with a shade percentage of 75% to the luminance, we get:

$$ 𝐿 ^{′} = 0.53 ∗ 0.75\\ = 0.39698 $$

Taking the resulting HSL color value of ($1/360$,0.48,0.39698)and converting back to RGB, we get 943634. This transformed value can be seen in the resulting background’s color attribute:

  <w:shd w:val="pct15" w:color="943634" w:themeColor="accent2"
    w:themeShade="BF" />

end example]

The possible values for this attribute are defined by the ST_UcharHexNumber simple type (17.18.98).

themeTint (Shading Pattern Theme Color Tint)

Specifies the tint value applied to the supplied theme color (if any) for this shading instance.

If the themeTint is supplied, then it is applied to the RGB value of the themeColor color (from the theme part) to determine the final color applied to this border.

The themeTint value is stored as a hex encoding of the tint value (from 0 to 255) applied to the current border.

[Example: Consider a tint of 60% applied to a border in a document. This tint is calculated as follows:

$$ 𝑇 _{𝑥𝑚𝑙} = 0.6 ∗ 255\\ = 153\\ = 99(ℎ𝑒𝑥) $$

The resulting themeTint value in the file format would be 99. end example]

Given an RGB color defined as three hex values in RRGGBB format, the shade is applied

as follows:

Convert the color to the HSL color format (values from 0 to 1)
Modify the luminance factor as follows:

$$ L ^{′} = L ∗ Tint + (1 − Tint )\\ L = L ∗ Tint + (1 − Tint )\\ $$

Convert the resultant HSL color to RGB

[Example: Consider a document with a background using the accent2 theme color, whose RGB value (in RRGGBB hex format) is 4F81BD.

The equivalent HSL color value would be ($213/360$,0.45,0.53).

Applying the tint formula with a tint percentage of 60% to the luminance, we get:

$$ 𝐿 ^{′} = 0.53 ∗ 0.6 + (1 − .6)\\ = 0.71 $$

Taking the resulting HSL color value of ($213/360$,0.45,0.71)and converting back to RGB, we get 95B3D7. This transformed value can be seen in the resulting shading’s color attribute:

  <w:shd w:val="pct15" w:color="95B3D7" w:themeColor="accent2"
    w:themeTint="99" />

end example]

The possible values for this attribute are defined by the ST_UcharHexNumber simple type (17.18.98).

val (Shading Pattern)

Specifies the pattern which shall be used to lay the pattern color over the background color for this paragraph shading.

This pattern consists of a mask which is applied over the background shading color to get the locations where the pattern color should be shown. Each of these possible masks are shown in the simple type values referenced below.

[Example: Consider a shaded paragraph which uses a 10 percent foreground fill, resulting in the following WordprocessingML:

  <w:shd w:val="pct10" … />

This shading val is pct10, indicating that the border style is a 10 percent foreground fill mask. end example]

The possible values for this attribute are defined by the ST_Shd simple type (17.18.78).

[Note: The W3C XML Schema definition of this complex type’s content model (CT_Shd) is located in A.1. end note]

Last updated on March 14, 2025

17.3.4 Border Properties