feat(design-tokens): add elevation tokens (#4207)

.changeset/ninety-avocados-shout.md

@@ -0,0 +1,6 @@
+---
+"@twilio-paste/design-tokens": minor
+"@twilio-paste/core": minor
+---
+
+[Design Tokens] Update aliases and add new tokens for elevation foundations

packages/paste-core/primitives/box/type-docs.json

@@ -727,7 +727,7 @@
       "description": "Responsive prop for the CSS `background-attachment` property"
     },
     "backgroundColor": {
-      "type": "\"inherit\" | \"none\" | \"colorBackground\" | \"colorBackgroundAvailable\" | \"colorBackgroundBody\" | \"colorBackgroundBodyInverse\" | \"colorBackgroundBrand\" | \"colorBackgroundBrand10\" | ... 56 more ... | { ...; }",
+      "type": "\"inherit\" | \"none\" | \"colorBackground\" | \"colorBackgroundAvailable\" | \"colorBackgroundBody\" | \"colorBackgroundBodyElevation\" | \"colorBackgroundBodyInverse\" | \"colorBackgroundBrand\" | ... 64 more ... | { ...; }",
       "defaultValue": null,
       "required": false,
       "externalProp": false,
@@ -958,7 +958,7 @@
       "description": "Responsive prop for the CSS `bottom` property"
     },
     "boxShadow": {
-      "type": "\"none\" | \"shadow\" | \"shadowBorder\" | \"shadowBorderBottomBrand10Strong\" | \"shadowBorderBottomBrand20Strong\" | \"shadowBorderBottomBrand30Strong\" | \"shadowBorderBottomDecorative10Weaker\" | ... 75 more ... | { ...; }",
+      "type": "\"none\" | \"shadow\" | \"shadowBorder\" | \"shadowBorderBottomBrand10Strong\" | \"shadowBorderBottomBrand20Strong\" | \"shadowBorderBottomBrand30Strong\" | \"shadowBorderBottomDecorative10Weaker\" | ... 85 more ... | { ...; }",
       "defaultValue": null,
       "required": false,
       "externalProp": false,

packages/paste-core/primitives/sibling-box/type-docs.json

@@ -829,7 +829,7 @@
       "description": "Responsive prop for the CSS `background-attachment` property"
     },
     "backgroundColor": {
-      "type": "\"inherit\" | \"none\" | \"colorBackground\" | \"colorBackgroundAvailable\" | \"colorBackgroundBody\" | \"colorBackgroundBodyInverse\" | \"colorBackgroundBrand\" | \"colorBackgroundBrand10\" | ... 56 more ... | { ...; }",
+      "type": "\"inherit\" | \"none\" | \"colorBackground\" | \"colorBackgroundAvailable\" | \"colorBackgroundBody\" | \"colorBackgroundBodyElevation\" | \"colorBackgroundBodyInverse\" | \"colorBackgroundBrand\" | ... 64 more ... | { ...; }",
       "defaultValue": null,
       "required": false,
       "externalProp": false,
@@ -1060,7 +1060,7 @@
       "description": "Responsive prop for the CSS `bottom` property"
     },
     "boxShadow": {
-      "type": "\"none\" | \"shadow\" | \"shadowBorder\" | \"shadowBorderBottomBrand10Strong\" | \"shadowBorderBottomBrand20Strong\" | \"shadowBorderBottomBrand30Strong\" | \"shadowBorderBottomDecorative10Weaker\" | ... 75 more ... | { ...; }",
+      "type": "\"none\" | \"shadow\" | \"shadowBorder\" | \"shadowBorderBottomBrand10Strong\" | \"shadowBorderBottomBrand20Strong\" | \"shadowBorderBottomBrand30Strong\" | \"shadowBorderBottomDecorative10Weaker\" | ... 85 more ... | { ...; }",
       "defaultValue": null,
       "required": false,
       "externalProp": false,

packages/paste-core/primitives/text/type-docs.json

@@ -531,7 +531,7 @@
       "description": "Responsive prop for the CSS `bottom` property"
     },
     "boxShadow": {
-      "type": "\"none\" | \"shadow\" | \"shadowBorder\" | \"shadowBorderBottomBrand10Strong\" | \"shadowBorderBottomBrand20Strong\" | \"shadowBorderBottomBrand30Strong\" | \"shadowBorderBottomDecorative10Weaker\" | ... 75 more ... | { ...; }",
+      "type": "\"none\" | \"shadow\" | \"shadowBorder\" | \"shadowBorderBottomBrand10Strong\" | \"shadowBorderBottomBrand20Strong\" | \"shadowBorderBottomBrand30Strong\" | \"shadowBorderBottomDecorative10Weaker\" | ... 85 more ... | { ...; }",
       "defaultValue": null,
       "required": false,
       "externalProp": false,

packages/paste-design-tokens/tokens/aliases/box-shadow.yml

@@ -3,7 +3,7 @@ imports:
   - ./offset.yml
   - ./spacing.yml
 aliases:
-  shadow-elevation-0: "none"
-  shadow-elevation-10: "{!offset-0} {!offset-10} {!offset-40} {!offset-0} {!palette-gray-100-transparent-10}"
-  shadow-elevation-20: "{!offset-0} {!offset-20} {!offset-60} {!offset-0} {!palette-gray-100-transparent-20}"
-  shadow-elevation-30: "{!offset-0} {!offset-60} {!offset-80} {!offset-0} {!palette-gray-100-transparent-20}"
+  deprecated-shadow-elevation-0: "none"
+  deprecated-shadow-elevation-10: "{!offset-0} {!offset-10} {!offset-40} {!offset-0} {!palette-gray-100-transparent-10}"
+  deprecated-shadow-elevation-20: "{!offset-0} {!offset-20} {!offset-60} {!offset-0} {!palette-gray-100-transparent-20}"
+  deprecated-shadow-elevation-30: "{!offset-0} {!offset-60} {!offset-80} {!offset-0} {!palette-gray-100-transparent-20}"

packages/paste-design-tokens/tokens/aliases/color-palette.yml

@@ -29,14 +29,19 @@ aliases:
   palette-gray-0: "#ffffff"
   palette-gray-05: "#f9f9fa"
   palette-gray-10: "#f4f4f6"
+  palette-gray-15: "#edeef2"
   palette-gray-20: "#e1e3ea"
   palette-gray-30: "#cacdd8"
-  palette-gray-40: "#aeb2c1"
+  palette-gray-40: "#8e96ae"
   palette-gray-50: "#8891aa"
+  palette-gray-55: "#67728e"
   palette-gray-60: "#606b85"
   palette-gray-70: "#4b5671"
+  palette-gray-75: "#404f6e"
   palette-gray-80: "#394762"
+  palette-gray-85: "#25395b"
   palette-gray-90: "#1f304c"
+  palette-gray-95: "#19273E"
   palette-gray-100: "#121c2d"
   palette-gray-110: "#0F1621"
 
@@ -52,7 +57,7 @@ aliases:
   palette-gray-0-transparent-90: "rgba(255, 255, 255, 0.9)"
   palette-gray-0-transparent-100: "rgba(255, 255, 255, 1)"
 
-  ## Grays transparent based on darkest gray
+  ## Grays transparent based on dark gray
   palette-gray-100-transparent-10: "rgba(18, 28, 45, 0.1)"
   palette-gray-100-transparent-20: "rgba(18, 28, 45, 0.2)"
   palette-gray-100-transparent-30: "rgba(18, 28, 45, 0.3)"
@@ -64,6 +69,13 @@ aliases:
   palette-gray-100-transparent-90: "rgba(18, 28, 45, 0.9)"
   palette-gray-100-transparent-100: "rgba(18, 28, 45, 1)"
 
+  ## Grays transparent based on darkest gray
+  palette-gray-110-transparent-05: "rgba(15, 22, 33, 0.05)"
+  palette-gray-110-transparent-10: "rgba(15, 22, 33, 0.1)"
+
+  ## Blacks transparent
+  palette-black-transparent-40: "rgba(0, 0, 0, 0.4)"
+
   ## Blues transparent based on darkest blue
   palette-blue-100-transparent-10: "rgba(6, 3, 58, 0.1)"
   palette-blue-100-transparent-20: "rgba(6, 3, 58, 0.2)"

packages/paste-design-tokens/tokens/aliases/color.yml

@@ -11,4 +11,3 @@ aliases:
   sun: "#FF7A00"
   white: "#FFFFFF"
   white-accent: "#F6FBFE"
-  black-transparent-40: "rgba(0, 0, 0, 0.4)"

packages/paste-design-tokens/tokens/aliases/offset.yml

@@ -14,3 +14,4 @@ aliases:
   offset-90: "32px"
   offset-negative-05: -1px
   offset-negative-20: -4px
+  offset-negative-60: -16px

packages/paste-design-tokens/tokens/global/background-color.yml

@@ -33,6 +33,9 @@ props:
   color-background-weak:
     value: "{!palette-gray-05}"
     comment: Weak background color used for containers.
+  color-background-weaker:
+    value: "{!palette-gray-0}"
+    comment: Background color for elevated elements. Matches color-background-body in light mode but appears slightly lighter in dark mode to maintain focus.
 
   # brand backgrounds
   color-background-brand:
@@ -210,3 +213,26 @@ props:
   color-background-notification:
     value: "{!palette-red-60}"
     comment: Background color used for notifications.
+
+  #elevation background
+  color-background-body-elevation:
+    value: "{!palette-gray-05}"
+    comment: Elevation token for color-background-body elements.
+  color-background-weak-elevation:
+    value: "{!palette-gray-05}"
+    comment: Elevation token for color-background-weak elements.
+  color-background-elevation:
+    value: "{!palette-gray-15}"
+    comment: Elevation token for color-background elements.
+  color-background-inverse-elevation:
+    value: "{!palette-gray-95}"
+    comment: Elevation token for color-background-inverse elements.
+  color-background-inverse-weak-elevation:
+    value: "{!palette-gray-85}"
+    comment: Elevation token for color-background-inverse-weak elements.
+  color-background-inverse-strong-elevation:
+    value: "{!palette-gray-75}"
+    comment: Elevation token for color-background-inverse-strong elements.
+  color-background-inverse-stronger-elevation:
+    value: "{!palette-gray-75}"
+    comment: Elevation token for color-background-inverse-stronger elements.

packages/paste-design-tokens/tokens/global/box-shadow.yml

@@ -4,19 +4,18 @@ global:
 imports:
   - ../aliases/box-shadow.yml
   - ../aliases/offset.yml
-  - ../aliases/color.yml
 props:
   shadow-high:
-    value: "{!shadow-elevation-30}"
+    value: "{!deprecated-shadow-elevation-30}"
     comment: High elevation default shadow.
   shadow:
-    value: "{!shadow-elevation-20}"
+    value: "{!deprecated-shadow-elevation-20}"
     comment: Default shadow.
   shadow-low:
-    value: "{!shadow-elevation-10}"
+    value: "{!deprecated-shadow-elevation-10}"
     comment: Low elevation default shadow.
   shadow-card:
-    value: "{!shadow-elevation-10}"
+    value: "{!deprecated-shadow-elevation-10}"
     comment: Shadow for cards.
   shadow-focus:
     value: "{!offset-0} {!offset-0} {!offset-0} {!offset-20} {!palette-blue-60-transparent-70}"
@@ -250,11 +249,43 @@ props:
     value: "{!offset-20} {!offset-0} {!offset-40} {!offset-negative-20} {!palette-gray-100-transparent-20}"
     comment: Left shadow border for elements.
   shadow-left-inverse:
-    value: "{!offset-20} {!offset-0} {!offset-40} {!offset-negative-20} {!black-transparent-40}"
+    value: "{!offset-20} {!offset-0} {!offset-40} {!offset-negative-20} {!palette-black-transparent-40}"
     comment: Left shadow border for inverse elements.
   shadow-right:
     value: "{!offset-negative-20} {!offset-0} {!offset-40} {!offset-negative-20} {!palette-gray-100-transparent-20}"
     comment: Right shadow border for elements.
   shadow-right-inverse:
-    value: "{!offset-negative-20} {!offset-0} {!offset-40} {!offset-negative-20} {!black-transparent-40}"
+    value: "{!offset-negative-20} {!offset-0} {!offset-40} {!offset-negative-20} {!palette-black-transparent-40}"
     comment: Right shadow border for inverse elements.
+
+  # Elevation
+  shadow-elevation-05:
+    value: "{!offset-0} {!offset-0} {!offset-0} {!offset-05} {!palette-gray-15}"
+    comment: Accent shadows that subtly define the edges of a container. They serve as a lightweight alternative to risen shadows at lower elevations.
+  shadow-elevation-top-05:
+    value: "{!offset-0} {!offset-negative-05} {!offset-0} {!offset-0} {!palette-gray-15}"
+    comment: Accent shadows that subtly define the top edges of an element. They serve as a lightweight alternative to risen shadows at lower elevations.
+  shadow-elevation-bottom-05:
+    value: "{!offset-0} {!offset-05} {!offset-0} {!offset-0} {!palette-gray-15}"
+    comment: Accent shadows that subtly define the bottom edge of an element. They serve as a lightweight alternative to risen shadows at lower elevations.
+  shadow-elevation-inverse-05:
+    value: "{!offset-0} {!offset-0} {!offset-0} {!offset-05} {!palette-gray-90}"
+    comment: Accent shadows that subtly define the the edges of a container on inverse backgrounds. They serve as a lightweight alternative to risen shadows at lower elevations.
+  shadow-elevation-bottom-inverse-05:
+    value: "{!offset-0} {!offset-05} {!offset-0} {!offset-0} {!palette-gray-90}"
+    comment: Accent shadows that subtly define the bottom edge of an inverse element. They serve as a lightweight alternative to risen shadows at lower elevations.
+  shadow-elevation-right-inverse-05:
+    value: "{!offset-05} {!offset-0} {!offset-0} {!offset-0} {!palette-gray-90}"
+    comment: Accent shadows that subtly define the right edge of an inverse element. They serve as a lightweight alternative to risen shadows at lower elevations.
+  shadow-elevation-10:
+    value: "{!offset-0} {!offset-negative-05} {!offset-0} {!offset-0} {!palette-gray-10}, {!offset-0} {!offset-15} {!offset-20} {!offset-0} {!palette-gray-110-transparent-10}"
+    comment: Use on elements that overlay other UI components but remain visually connected to the elements behind them.
+  shadow-elevation-inverse-10:
+    value: "{!offset-0} {!offset-negative-05} {!offset-0} {!offset-0} {!palette-gray-90}, {!offset-0} {!offset-15} {!offset-20} {!offset-0} {!palette-black-transparent-40}"
+    comment: Use on inverse elements that overlay other UI components but remain visually connected to the elements behind them.
+  shadow-elevation-20:
+    value: "{!offset-0} {!offset-0} {!offset-0} {!offset-05} {!palette-gray-05}, {!offset-0} {!offset-30} {!offset-40} {!offset-0} {!palette-gray-110-transparent-10}, {!offset-60} {!offset-60} {!offset-90} {!offset-0} {!palette-gray-110-transparent-05}"
+    comment: Use on elements that sit above the UI to indicate a greater distance distance from the surface behind them.
+  shadow-elevation-left-20:
+    value: "{!offset-0} {!offset-0} {!offset-0} {!offset-05} {!palette-gray-05}, {!offset-negative-20} {!offset-0} {!offset-40} {!offset-0} {!palette-gray-110-transparent-10}, {!offset-negative-60} {!offset-0} {!offset-90} {!offset-0} {!palette-gray-110-transparent-05}"
+    comment: Use for elements that dynamically open from the right side of the screen, appearing above the UI to indicate a greater separation from the underlying surface.

packages/paste-design-tokens/tokens/themes/dark/aliases/box-shadow.yml

@@ -2,9 +2,8 @@ imports:
   - ../../../aliases/box-shadow.yml
   - ../../../aliases/offset.yml
   - ./color-palette.yml
-  - ./color.yml
 aliases:
-  shadow-elevation-0: "none"
-  shadow-elevation-10: "{!offset-0} {!offset-10} {!offset-20} {!offset-0} {!black-transparent-40}"
-  shadow-elevation-20: "{!offset-0} {!offset-20} {!offset-60} {!offset-0} {!black-transparent-50}"
-  shadow-elevation-30: "{!offset-0} {!offset-60} {!offset-80} {!offset-20} {!black-transparent-50}"
+  deprecated-shadow-elevation-0: "none"
+  deprecated-shadow-elevation-10: "{!offset-0} {!offset-10} {!offset-20} {!offset-0} {!palette-black-transparent-40}"
+  deprecated-shadow-elevation-20: "{!offset-0} {!offset-20} {!offset-60} {!offset-0} {!palette-black-transparent-50}"
+  deprecated-shadow-elevation-30: "{!offset-0} {!offset-60} {!offset-80} {!offset-20} {!palette-black-transparent-50}"

packages/paste-design-tokens/tokens/themes/dark/aliases/color-palette.yml

@@ -99,6 +99,18 @@ aliases:
   palette-gray-80-transparent-90: "rgba(57, 71, 98, 0.9)"
   palette-gray-80-transparent-100: "rgba(57, 71, 98, 1)"
 
+  ## Blacks transparent
+  palette-black-transparent-10: "rgba(0, 0, 0, 0.1)"
+  palette-black-transparent-20: "rgba(0, 0, 0, 0.2)"
+  palette-black-transparent-30: "rgba(0, 0, 0, 0.3)"
+  palette-black-transparent-40: "rgba(0, 0, 0, 0.4)"
+  palette-black-transparent-50: "rgba(0, 0, 0, 0.5)"
+  palette-black-transparent-60: "rgba(0, 0, 0, 0.6)"
+  palette-black-transparent-70: "rgba(0, 0, 0, 0.7)"
+  palette-black-transparent-80: "rgba(0, 0, 0, 0.8)"
+  palette-black-transparent-90: "rgba(0, 0, 0, 0.9)"
+  palette-black-transparent-100: "rgba(0, 0, 0, 1)"
+
   ## Greens
   palette-green-10: "#edfdf3"
   palette-green-20: "#d1fae0"

packages/paste-design-tokens/tokens/themes/dark/global/background-color.yml

@@ -3,7 +3,6 @@ global:
   category: background-color
 imports:
   - ../../../global/background-color.yml
-  - ../aliases/color.yml
   - ../aliases/color-palette.yml
 props:
   # base background
@@ -31,6 +30,9 @@ props:
   color-background-weak:
     value: "{!palette-gray-100}"
     comment: Weak default background color.
+  color-background-weaker:
+    value: "{!palette-gray-100}"
+    comment: Background color for elevated elements. Matches color-background-body in light mode but appears slightly lighter in dark mode to maintain focus.
 
   # brand backgrounds
   color-background-brand:
@@ -191,3 +193,14 @@ props:
   color-background-decorative-40-weakest:
     value: "{!palette-purple-80}"
     comment: "Weakest background color with no semantic meaning, used for decorative purposes only. Should generally be used with matching decorative border and/or text tokens."
+
+  #elevation background
+  color-background-body-elevation:
+    value: "{!palette-gray-95}"
+    comment: Elevation token for color-background-body elements.
+  color-background-weak-elevation:
+    value: "{!palette-gray-100}"
+    comment: Elevation token for color-background-weak elements.
+  color-background-elevation:
+    value: "{!palette-gray-95}"
+    comment: Elevation token for color-background elements.

packages/paste-design-tokens/tokens/themes/dark/global/border-color.yml

@@ -3,7 +3,6 @@ global:
   category: border-color
 imports:
   - ../../../global/border-color.yml
-  - ../aliases/color.yml
   - ../aliases/color-palette.yml
 props:
   color-border-strong:

packages/paste-design-tokens/tokens/themes/dark/global/box-shadow.yml

@@ -6,16 +6,16 @@ imports:
   - ../aliases/box-shadow.yml
 props:
   shadow-high:
-    value: "{!shadow-elevation-30}"
+    value: "{!deprecated-shadow-elevation-30}"
     comment: High elevation default shadow.
   shadow:
-    value: "{!shadow-elevation-20}"
+    value: "{!deprecated-shadow-elevation-20}"
     comment: Default shadow.
   shadow-low:
-    value: "{!shadow-elevation-10}"
+    value: "{!deprecated-shadow-elevation-10}"
     comment: Low elevation default shadow.
   shadow-card:
-    value: "{!shadow-elevation-10}"
+    value: "{!deprecated-shadow-elevation-10}"
     comment: Shadow for cards.
   shadow-focus:
     value: "{!offset-0} {!offset-0} {!offset-0} {!offset-20} {!palette-gray-60}"
@@ -179,8 +179,28 @@ props:
 
   # Left / Right
   shadow-left:
-    value: "{!offset-20} {!offset-0} {!offset-40} {!offset-negative-20} {!black-transparent-40}"
+    value: "{!offset-20} {!offset-0} {!offset-40} {!offset-negative-20} {!palette-black-transparent-40}"
     comment: Left shadow border for elements.
   shadow-right:
-    value: "{!offset-negative-20} {!offset-0} {!offset-40} {!offset-negative-20} {!black-transparent-40}"
+    value: "{!offset-negative-20} {!offset-0} {!offset-40} {!offset-negative-20} {!palette-black-transparent-40}"
     comment: Right shadow border for elements.
+
+  # Elevation
+  shadow-elevation-05:
+    value: "{!offset-0} {!offset-0} {!offset-0} {!offset-05} {!palette-gray-90}"
+    comment: Accent shadows that subtly define the edges of a container. They serve as a lightweight alternative to risen shadows at lower elevations.
+  shadow-elevation-top-05:
+    value: "{!offset-0} {!offset-negative-05} {!offset-0} {!offset-0} {!palette-gray-90}"
+    comment: Accent shadows that subtly define the top edges of an element. They serve as a lightweight alternative to risen shadows at lower elevations.
+  shadow-elevation-bottom-05:
+    value: "{!offset-0} {!offset-05} {!offset-0} {!offset-0} {!palette-gray-90}"
+    comment: Accent shadows that subtly define the bottom edge of an element. They serve as a lightweight alternative to risen shadows at lower elevations.
+  shadow-elevation-10:
+    value: "{!offset-0} {!offset-negative-05} {!offset-0} {!offset-0} {!palette-gray-90}, {!offset-0} {!offset-15} {!offset-20} {!offset-0} {!palette-black-transparent-40}"
+    comment: Use on elements that overlay other UI components but remain visually connected to the elements behind them.
+  shadow-elevation-20:
+    value: "{!offset-0} {!offset-0} {!offset-0} {!offset-05} {!palette-gray-95}, {!offset-0} {!offset-30} {!offset-40} {!offset-0} {!palette-black-transparent-30}, {!offset-60} {!offset-60} {!offset-90} {!offset-0} {!palette-black-transparent-20}"
+    comment: Use on elements that sit above the UI to indicate a greater distance distance from the surface behind them.
+  shadow-elevation-left-20:
+    value: "{!offset-0} {!offset-0} {!offset-0} {!offset-05} {!palette-gray-95}, {!offset-negative-20} {!offset-0} {!offset-40} {!offset-0} {!palette-black-transparent-30}, {!offset-negative-60} {!offset-0} {!offset-90} {!offset-0} {!palette-black-transparent-20}"
+    comment: Use for elements that dynamically open from the right side of the screen, appearing above the UI to indicate a greater separation from the underlying surface.

packages/paste-design-tokens/tokens/themes/dark/global/text-color.yml

@@ -3,7 +3,6 @@ global:
   category: text-color
 imports:
   - ../../../global/text-color.yml
-  - ../aliases/color.yml
   - ../aliases/color-palette.yml
 props:
   # body text