Complex tokens for Drop Shadow and Typography

[GarthDB]

Problem statement

Drop shadow definitions include several values that don't need to be stored as separate values with separate names since they should always be used as a single shadow. This can make it complicated for implementations, products, and designers to know how to use the parts of the drop shadows together.

History

Drop shadows are stored as a combination of tokens: drop-shadow-x, drop-shadow-y, drop-shadow-blur, and drop-shadow-color.

In Spectrum 2, the proposed design will use more drop shadows for different elevation and state conditions and create the shadows by layering multiple drop shadows (CodePen example). Adding more drop shadows for different use cases and composed of several parts will further exasperate the complexity described in the problem statement above.

Future

If we use complex tokens similar to those used in Tokens Studio for Figma, we would be able to combine all the shadow parts into a single token with a single token name.

Alternatives considered

The only alternative we considered or found would be to create new tokens for each new shadow and part.

Decisions

We've decided to start with simpler shadows to reduce complexity and unblock S2 work while we research and establish a path forward for using complex tokens.

Example JSON Schema

I've written an example definition of the JSON schema we could use in the token system.

"$schema": https://json-schema.org/draft/2020-12/schema
"$id": https://opensource.adobe.com/spectrum-tokens/schemas/token-types/drop-shadow.json
title: Drop Shadow
description: Composite token for drop shadows
type: https://github.com/adobe/spectrum-tokens/discussions/297
allOf:
  - "$ref": https://opensource.adobe.com/spectrum-tokens/schemas/token-types/token.json
properties:
  "$schema":
    const: https://opensource.adobe.com/spectrum-tokens/schemas/token-types/dimension.json
  value:
    type: object
    properties:
      x:
        oneOf:
          - type: string # dimension in pixels
            pattern: "^(?:-?((?:\\d+\\.?\\d*)|(?:\\.?\\d+))(px))|0|\\d+dp$"
          - type: string # reference to an alias or dimension token
            pattern: "^\\{(\\w|-)*\\}$"
      "y":
        oneOf:
          - type: string # dimension in pixels
            pattern: "^(?:-?((?:\\d+\\.?\\d*)|(?:\\.?\\d+))(px))|0|\\d+dp$"
          - type: string # reference to an alias or dimension token
            pattern: "^\\{(\\w|-)*\\}$"
      blur:
        oneOf:
          - type: string # dimension in pixels
            pattern: "^(?:-?((?:\\d+\\.?\\d*)|(?:\\.?\\d+))(px|rem|em|%))|0|\\d+dp$"
          - type: string # reference to an alias or dimension token
            pattern: "^\\{(\\w|-)*\\}$"
      color:
        oneOf:
          - type: string # rgb(a) or hexidecimal color
            pattern: "^rgba\\((([0-1]?[0-9]?[0-9]?|2[0-4][0-9]|25[0-5]),\\s?){3}(0|1|0?\\.\\d+)\\)|rgb\\(([0-1]?[0-9]?[0-9]?|2[0-4][0-9]|25[0-5]){1,3}(,\\s?\\d{1,3}%?){2}\\)$"
          - type: string # reference to an alias or color token
            pattern: "^\\{(\\w|-)*\\}$"
  component: {}
  deprecated: {}
  deprecated_comment: {}
  uuid: {}

Consequences or Required Actions

Implementations will need to update their parsers to handle these new complex drop-shadow tokens. CSS custom properties support defining a shadow in a single custom property --shadow-part-1: 0px 2px 8px 0px rgba(0, 0, 0, 0.08);.

There are some unknowns and potential downsides introduced by trying to reference tokens inside and outside these complex object values. It seems that Tokens Studio for Figma supports using references inside the complex token definition like this:

"default-shadow": {
  "value": {
    "x": "0",
    "y": "2px",
    "blur": "8px",
    "spread": "0",
    "color": "{shadows.default}"
  },
  "$schema": "drop-shadow"
}

but it doesn't seem possible to reference individual parts of that complex token or do things like extend existing shadows. This means we would need to use aliases to share the parts of the shadows that have the same values for the same reasons (e.g., shadow color, etc).

[charlespina]

Here are some follow-up questions:

• Do these values need to change based on theme? Would that be difficult with a dictionary-valued token?
• Why wouldn't the alternative work? Is the hesitation because there are a number of "layers" and that would lead to a lot of similarly named tokens which differ by a number, eg, shadow-part1-x, shadow-part2-x?

[GarthDB]

@charlespina

• Yes, the drop-shadows need to change based on the color theme. They always use black, but in dark, the opacity is different.
• Yes, it would lead to a lot of similarly named tokens, and their relationship to each other isn't immediately clear outside of the name. This object value helps keep things together a little better and implies the parts aren't intended to be used separately.

[GarthDB]

I will need to update the color-set token schema definition to support having nested drop-shadow tokens for the different color themes.

[GarthDB]

I included the jsonschema example. I used the yaml format to support comments.

[GarthDB]

Also, this does bring us in closer alignment with the w3c spec for shadow tokens. Example:

{
  "shadow-token": {
    "$type": "shadow",
    "$value": {
      "color": "#00000088",
      "offsetX": "0.5rem",
      "offsetY": "0.5rem",
      "blur": "1.5rem",
      "spread": "0rem"
    }
  }
}

[GarthDB]

Thanks for the feedback. I'm closing this discussion for now.