Page cover image

Box Shadow - Token Type

Add elevation and depth to design elements by composing several shadow-related design decisions into a single Box Shadow Token.

Each design decision (color, spread, blur, offeset) that is a part of a Composite Token is referred to as a property of the Box Shadow Token in our guides.

Creating a new Box Shadow Token in the Tokens Studio Plugin for Figma.

Design decisions

While the Token Type label is specific to Box Shadow, this Token supports Inner Shadow and Drop Shadow design decisions.

Each property composed to create the shadow can be defined as it's own Token and referenced within the Box Shadow Composite Token:

  • X

  • Y

  • Blur

  • Spread

  • Shadow color

Similar to how shadows are defined in CSS, you can combine multiple shadows in a single Box Shadow Token. Box shadow Tokens applied to text layers would translate to text-shadow in CSS.

Looking for the Blur Effect in Figma? That's currently a property within our Dimension Token.

Cover

Box Shadow Tokens can be attached to Effect Styles in Figma.

Possible values

Like all Composite Tokens, you define the value of each property individually.

When you create the Box Shadow Token in the plugin, you can reference each Token you've already created as a property or enter a hard-coded value.

The best practice is to define all parts of a Composite Token, even with a null/none value, rather than to leave it empty.

Hard coded values

In the plugin, use the UI button to select between drop shadow or inner shadow.

The dedicated Token Type of each property within the Box Shadow Token has unique specifications, described in detail in their own technical docs.

1

X-offset

X defines the horizontal position of the shadow and are written as a numeric value and unit of measurement.

  • Positive values move the position to the right. For example 15px

  • Negative values move the position to the left. For example -0.255px

→ Jump to the Dimension Token guide

2

Y-offset

Y defines the vertical position of the shadow and are written as a numeric value and unit of measurement.

  • Positive values move the position higher up. For example 1.5px

  • Negative values move the position lower down. For example -10px

→ Jump to the Dimension Token guide

3

Blur radius

Blur defines the the softness of the shadow edges and is written as a numeric value and unit of measurement.

  • Higher values create a more diffused shadow, making the edges softer and less defined. For example 15px

  • A value of 0 creates a sharp shadow edge.

→ Jump to the Dimension Token guide

4

Spread radius

Spread defines the size of the shadow and is written as a numeric value and unit of measurement.

  • Positive values expand the shadow, making it larger. For example 5px

  • Negative values shrink it, making it smaller. For example -2.25px

→ Jump to the Dimension Token guide

5

Color

Color defines the color of the shadow as a solid, reduced opacity, or modified color value written in any color space supported by a Color Token.

You can also use the color picker to create the value by selecting the swatch to the left of the input.

→ Jump to the Color Token guide

Multiple layers

You can add another shadow layer to the current token by selecting the plus icon button in the Box Shadow Token form.

Once the Box Shadow Token form is open in the Plugin, select the + icon to add an additional shadow to your composition.

When you apply the Box Shadow Token to your design element in the Figma UI, you will see multiple shadow effects applied, one for each shadow layer you created within your token.

When you export a multiple-layer Box Shadow Token to Figma as a Style, you will see a single Effect Style applied, with multiple shadow effects within its value.

More details on Exporting Box Shadow Tokens to Effect styles below ↓.

Values that reference another Token

Like all Composite Tokens, you may reference an existing Token as the value for each individual property, as described above ↑.

If you'd prefer to reference an existing Box Shadow Composite Token as the value instead of defining each Property, select the Token's Reference mode button (2x2 circle icon).

With the Box Shadow Token form open in the Plugin, select the reference mode icon button to change its Value input. This allows you to reference another Box Shadow Composite Token as the value.

When trying to reference another Token as the Value for a Box Shadow Token, you will see Tokens in the dropdown list that are:

  • Lving in Token Sets that are currently active.

    • In the left menu on the plugin's Tokens page, a checkmark is visible next to the Token Set name.

  • Token Type is compatible:

    • boxShadow

However, like all Token Types, you can "force" a reference by manually entering the Token Name between curly brackets.

For example {token.name.here}

The value will show a broken reference until the originating Token Set is marked as enabled.

Jump to the guide on Token Values with References by selecting the card below to learn more.

Token Values with References

Apply Box Shadow Tokens

Box Shadow Tokens defines the inner or outer shadow styling of text, polygonal shape, and frame layers in Figma when the Token is applied.

With one or more elements selected in Figma, click on the name of your chosen Box Shadow Token in the Plugin to instantly apply its value.

Once a Token has been applied, it will remain attached until you manually remove it.

Effect Styles in Figma

Box Shadow Tokens can be attached to Effect Styles in Figma. Tokens Studio also supports Styles with Variable References.

Here are some tips for creating Effect Styles with Variable References using the Plugin.

Before you export your Box Shadow Tokens to Figma as styles, ensure each property within the Box Shadow Tokens has a value referencing another Token.

When you Export to Figma, select these Options from the menu to create Effect Styles with Variable References:

  • Effect Styles is selected.

  • Number and Color Variables are selected.

  • Create styles with variable references is selected.

Select the Export Styles and Variables from the Tokens page to configure the Options.

Ensure your Export to Figma as Themes or Sets configuration includes all necessary Tokens.

  • Themes and token sets where the referenced Tokens are located are active.

  • Themes and token sets where the variables are attached may need to be configured as reference only.

You'll notice the Effect Style will be created on Export, with all possible values mapped to the appropriate Variables, based on the Token Type for each property:

  • color (will create as color variable)

  • dimension (number variable)

  • number (number variable)

Jump to the guide on Exporting Tokens to Figma by selecting the card below to learn more.

Export to Figma Guide

W3C DTCG Token Format

Shadow is an official token type in the in the W3C Design Token Community Group specifications (9.5 Shadow).

The plugin had Box Shadow support long before the spec defined the shadow token, and as a result, we have some legacy decisions which do not completely align with the DTCG spec.

  • We write the type as BoxShadow where the spec writes it as shadow.

    • When you run the SD-Transforms npm package we will adjust this automatically to match the specification, details below.

  • The Plugin currently supports number Tokens in numeric value properties.

    • The spec requires dimension values only.

Transforming Tokens

Engineers typically transform Tokens used in code with Style Dictionary, which is tool-agnostic. Tokens coming from Tokens Studio require an additional step: @Tokens-studio/sd-transforms, an npm package that prepares Tokens for Style Dictionary.

When transforming Box Shadow Tokens, which are a Composite Token there are specific configurations to be aware of.

Composite Tokens require the SD-Transforms option to expand composite Tokens into multiple Tokens.

Make sure you look at the generic SD-Transforms package to include this option, which allows you to further customize this transformation further using Style Dictionary.

→ SD-Transforms Read-Me Doc, Using Expand

"object, object"

When you transform your Box Shadow Tokens and they show "object, object", it means your SD-Transforms configuration needs to be adjusted to include "expand".

The preprocessor in the SD-Transforms package will automatically convert the Tokens Studio specific Token Type of boxShadow to align with the DTCG Format Token Type of shadow.

→ SD-Transforms Read-Me Doc, Using the preprocessor

The innerShadow properties need to be transformed to inset to be CSS compatible.

→ SD-Transforms ts/shadow/innerShadow

Resources

Mentioned in this doc:

Figma resources:

CSS resources:

Community resources:

  • None yet!

💡 Something to share? Submit it here!

Known issues and bugs

Tokens Studio Plugin GitHub - Open issues for Token Type Box Shadow

  • Importing shadow styles causes the order of shadows to be reversed #2979

  • TokenDropdown collides in Color input of box shadows #2796

    • UI issue where the dropdown menu needs repositioning.

  • Multiple shadows in Box Shadow tokens - array bug #2280

    • Removing one shadow from a Token with many shadows combined does not remove the deleted shadow from the array in the JSON file.

🐞 If you are experiencing an issue not listed here, please reach out to us on the Troubleshooting channel of our community Slack, submit it on our feedback tool, or send us an email [email protected]

Requests, roadmap and changelog

  • Change boxShadow values from x and y to offsetX and offsetY #2052

    • Alignment with the W3C DTCG format for shadow token type

💌 Visit https://feedback.tokens.studio/ to contribute or subscribe to updates.

PreviousBorder - CompositeNextColor

Last updated

Was this helpful?