Iterate on shadow token values and implementation

[lgriffee]

Follow up to the work done in #4823
Continuation of conversation in #4614

[lgriffee]

Shadow Tokens

Based on the work done in #4823 we have the following set of shadow tokens now:

Name	Value
--p-shadow-transparent	0 0 0 0 transparent
--p-shadow-faint	0 1px 0 0 rgba(22, 29, 37, 0.05)
--p-shadow-base	0 0 0 1px rgba(63, 63, 68, 0.05), 0 1px 3px 0 rgba(63, 63, 68, 0.15)
--p-shadow-deep	0 0 0 1px rgba(6, 44, 82, 0.1), 0 2px 16px rgba(33, 43, 54, 0.08)
--p-shadow-button	0 1px 0 rgba(0, 0, 0, 0.05)
--p-shadow-top-bar	0 2px 2px -1px rgba(0, 0, 0, 0.15)
--p-shadow-card	0 0 5px rgba(23, 24, 24, 0.05), 0 1px 2px rgba(0, 0, 0, 0.15)
--p-shadow-popover	-1px 0 20px rgba(23, 24, 24, 0.05), 0 1px 5px rgba(0, 0, 0, 0.15)
--p-shadow-layer	0 31px 41px 0 rgba(32, 42, 53, 0.2), 0 2px 16px 0 rgba(32, 42, 54, 0.08)
--p-shadow-modal	0 26px 80px rgba(0, 0, 0, 0.2), 0 0px 1px rgba(0, 0, 0, 0.2)
--p-shadows-inset-button	inset 0 -1px 0 rgba(0, 0, 0, 0.2)
--p-shadows-inset-button-pressed	inset 0 1px 0 rgba(0, 0, 0, 0.15)

The next phase of work for these tokens would be to derive a token scale and values from design patterns that are based on a spatial vision.

@aaronccasanova had some great ideas to start this discussion:

My vote is moving away from shadow aliases in favor of a shadow scale. I don't have strong opinions on the token prefix (e.g. --p-shadows, --p-depth, --p-elevation, etc.) but do think we should have opinions for inset and outset tokens. A "simple" solution may be to:

• Add ~20 outset shadow tokens
• Add ~20 inset shadow tokens
• Update each alias token with the closest matching shadow token

Example token scales

Outset shadow tokens:

• --p-shadows-0: none
• --p-shadows-1: 0px 2px 1px -1px rgba(0,0,0,0.2)
• --p-shadows-2: 0px 2px 1px -1px rgba(0,0,0,0.2)
• --p-shadows-3: 0px 2px 1px -1px rgba(0,0,0,0.2)
• --p-shadows-4: 0px 2px 1px -1px rgba(0,0,0,0.2)
• --p-shadows-5: 0px 2px 1px -1px rgba(0,0,0,0.2)
• etc: ...

Inset shadow tokens:

• --p-shadows-inset-0: none
• --p-shadows-inset-1: 0px 2px 1px -1px inset rgba(0,0,0,0.2)
• --p-shadows-inset-2: 0px 2px 1px -1px inset rgba(0,0,0,0.2)
• --p-shadows-inset-3: 0px 2px 1px -1px inset rgba(0,0,0,0.2)
• --p-shadows-inset-4: 0px 2px 1px -1px inset rgba(0,0,0,0.2)
• --p-shadows-inset-5: 0px 2px 1px -1px inset rgba(0,0,0,0.2)
• etc: ...

Visual aid:

@lgriffee , @laurkim , and I briefly discussed another concern on how to address existing instances of box-shadow with custom colors. Our tentative solution is to set a custom property for box-shadow colors that can be optionally overridden globally or locally on a given CSS rule (open to other suggestions).

The above would look something like:

:root {
  --p-shadows-color: rgba(0, 0, 0, 0.2);
  --p-shadows-1: 1px 1px var(--p-shadows-color);
  --p-shadows-...
}

.default-shadow-color {
  box-shadow: var(--p-shadows-1);
}

.custom-shadow-color {
  --p-shadows-color: rgba(var(--custom-color), 0.2);
  box-shadow: var(--p-shadows-1);
}

Shadow One Off Values

There is also clean up work left to remove the following one off shadow values:

Component/File	Value
Badge	0 -102px 0 -100px currentColor inset
Badge	0 0 0 100px currentColor inset
Banner	0 -2px 0 0 rgba(var(--pc-banner-rgb-text), 0.75) inset
Banner	0 -2px 0 0 rgba(var(--pc-banner-rgb-text), 0) inset
Banner	0 -2px 0 0 rgba(var(--pc-banner-rgb-text), 0.25) inset
Button	0 0 0 border-width('base') currentColor
Button	0 0 0 1px currentColor
IndexTable	1px 1px 0 0 var(--p-divider), 1px 0 1px 1px rgba(63, 63, 68, 0.05), 1px 0 3px 0 rgba(63, 63, 68, 0.15)
KeyboardKey	0 0 0 1px var(--p-border-subdued)
SingleThumb	0 0 0 0 var(--p-focused)
SingleThumb	0 0 0 2px var(--p-focused)
TextStyle	inset 0 0 0 1px var(--p-border-subdued)
_focus-ring	0 0 0 $negative-offset var(--p-focused)
_focus-ring	0 0 0 $stroke var(--p-focused)
_buttons	border-width('base') solid var(--p-border-critical)
Index Table	drop-shadow(1px 0 0 var(--p-divider))
Index Table	drop-shadow(0 -1px 0 var(--p-divider))
Index Table	drop-shadow(-1px 0 0 var(--p-divider))

@johanstromqvist brought up some great questions for us to ask around these one off values moving forward:

Do we know why they exist? Are there any patterns to why? My gut says that there might be a couple of categories:

Sloppy work – values are one-off, but shouldn't be. Prompt teams to fix them. Maybe provide support?
Purposeful – values are one-off for good reasons. Let them?
Recurring – multiple one-off values that imply an unmet need. Consolidate and tokenize?

---

Including y'all here since you are Token Group Advocates for shadow
@aaronccasanova @martenbjork @sarahill @heyjoethomas

[aaronccasanova]

Thanks for kicking off this issue @lgriffee! Definitely interested to hear folks opinions on my comment you referenced about using token scales and our tentative solution for allowing customized box-shadow colors.

[mathildebuenerd]

@lgriffee we are adding two shadow values for the ColorPicker in this PR #4948. There is one inset shadow for the picker, and one for the draggers:

// ColorPicker.scss

$inner-shadow: inset 0 0 rem(2px) 0 rgba(0, 0, 0, 0.5);
$dragger-shadow: inset 0 rem(0.5px) rem(2px) 0 rgba(0, 0, 0, 0.4),
  0 rem(0.5px) rem(3px) 0 rgba(0, 0, 0, 0.4);

I haven't found a token that corresponds to these values, and I think they are purposeful, so I let it as it is. Let us know if you have any feedback or if there is a better way.

[lgriffee]

@mathildebuenerd Thanks so much for posting these two new shadow values in this thread! ❤️ Polaris' shadow tokens are a bit all over the map right now and definitely need to be iterated on (so don't worry about not finding a corresponding value!)—our team needs to think through a new spacial vision and scale for these values. It'll be really valuable to reference the two values you're adding when we discuss what that new scale should be!

[alex-page]

I am closing this issue for now. We will go through the token values for shadow intentionally in the future. Look forward to going through this issue then.