@muraldevkit/ds-foundation 2.25.0 → 2.27.0

package/dist/tokens/contextual-variables/border.json

@@ -28,11 +28,11 @@
 	"border-radius": {
 		"tight": {
 			"$value": "{radii.01}",
-			"$description": "Tight corner radius."
+			"$description": "When the content has tight spacing considerations."
 		},
 		"content": {
 			"$value": "{radii.02}",
-			"$description": "Default content corner radius."
+			"$description": "For elements that are static content."
 		},
 		"content-large": {
 			"$value": "{radii.03}",
@@ -40,7 +40,7 @@
 		},
 		"functional": {
 			"$value": "{radii.03}",
-			"$description": "Corner radius for functional elements."
+			"$description": "For interactive elements. If a component can be both static and functional (e.g., Avatars), use the functional token over the \"Content\" token."
 		},
 		"functional-large": {
 			"$value": "{radii.04}",
@@ -48,15 +48,15 @@
 		},
 		"container": {
 			"$value": "{radii.04}",
-			"$description": "Corner radius for containers."
+			"$description": "For components/elements that are shells, meaning that the element itself doesn't typically know or care what the child elements are and simply provide a bounding element, for example, drawers, popovers, etc."
 		},
 		"container-large": {
 			"$value": "{radii.05}",
-			"$description": "Large corner radius for containers."
+			"$description": "For components/elements that are large, shell containers (e.g., modals or other near full-page elements)."
 		},
 		"rounded": {
 			"$value": "{radii.07}",
-			"$description": "Rounded corner radius."
+			"$description": "For components/elements that intentionally have an overly rounded appearance. Special note for elements that are pure circles (e.g. spinner, radio button, etc.), in these cases use a component token overwrite to make it 100% rounded."
 		},
 		"rounded-large": {
 			"$value": "{radii.08}",

package/dist/tokens/contextual-variables/color.json

@@ -56,34 +56,6 @@
 			"$value": "rgba({gray.100}, 1)",
 			"$description": "Background, selected state."
 		},
-		"background-highlight": {
-			"secondary": {
-				"$value": "{color.background-decorative}",
-				"$description": "Deprecated — use `background-decorative` instead."
-			},
-			"hover": {
-				"$value": "{color.background-hover}",
-				"$description": "Deprecated — use `background-hover` instead."
-			},
-			"active": {
-				"$value": "{color.background-active}",
-				"$description": "Deprecated — use `background-active` instead."
-			},
-			"selected": {
-				"$value": "{color.background-selected}",
-				"$description": "Deprecated — use `background-selected` instead."
-			},
-			"emph": {
-				"active": {
-					"$value": "{color.background-emph.active}",
-					"$description": "Deprecated — use `background-emph-active` instead."
-				},
-				"selected": {
-					"$value": "{color.background-active}",
-					"$description": "Deprecated — use `background-active` instead."
-				}
-			}
-		},
 		"background-emph": {
 			"hover": {
 				"$value": "rgba({gray.10}, 1)",
@@ -96,39 +68,39 @@
 		},
 		"background-info": {
 			"$value": "rgba({status.info}, 1)",
-			"$description": "Background for info status surfaces."
+			"$description": "Use for all use cases where we denote a status and there is a colored background. Use --mrl-color-text-inverse with these background colors."
 		},
 		"background-info-light": {
 			"$value": "rgba({status.info-light}, 1)",
-			"$description": "Light background for info status surfaces."
+			"$description": "Use for background of inline block notifications and badges."
 		},
 		"background-success": {
 			"$value": "rgba({status.success}, 1)",
-			"$description": "Background for success status surfaces."
+			"$description": "Use for all use cases where we denote a status and there is a colored background. Use --mrl-color-text-inverse with these background colors."
 		},
 		"background-success-light": {
 			"$value": "rgba({status.success-light}, 1)",
-			"$description": "Light background for success status surfaces."
+			"$description": "Use for background of inline block notifications and badges."
 		},
 		"background-warning": {
 			"$value": "rgba({status.warning}, 1)",
-			"$description": "Background for warning status surfaces."
+			"$description": "Use for all use cases where we denote a status and there is a colored background. Use --mrl-color-text-inverse with these background colors."
 		},
 		"background-warning-light": {
 			"$value": "rgba({status.warning-light}, 1)",
-			"$description": "Light background for warning status surfaces."
+			"$description": "Use for background of inline block notifications and badges."
 		},
 		"background-error": {
 			"$value": "rgba({status.error}, 1)",
-			"$description": "Background for error status surfaces."
+			"$description": "Use for all use cases where we denote a status and there is a colored background. Use --mrl-color-text-inverse with these background colors."
 		},
 		"background-error-light": {
 			"$value": "rgba({status.error-light}, 1)",
-			"$description": "Light background for error status surfaces."
+			"$description": "Use for background of inline block notifications and badges."
 		},
 		"background-private": {
 			"$value": "rgba({gray.100}, 1)",
-			"$description": "Background for private content warnings."
+			"$description": "Use for all use cases where we denote a status and there is a colored background. Use --mrl-color-text-inverse with these background colors. The private variable is deprecated and will be removed in v2."
 		},
 		"background-inverse": {
 			"$value": "rgba({gray.100}, 1)",
@@ -136,31 +108,31 @@
 		},
 		"background-inverse-hover": {
 			"$value": "rgba({gray.90}, 1)",
-			"$description": "Inverse surface background, hover state."
+			"$description": "Use only with --mrl-color-background-inverse; other colored backgrounds will have a different style set that's TBD."
 		},
 		"background-disabled": {
 			"$value": "rgba({gray.40}, 1)",
-			"$description": "Background for disabled controls."
+			"$description": "Use only when there is a background on a disabled element and the text used would be --mrl-color-text-inverse. In the product the current usage aligns to --mrl-gray-50 but Design provided new guidelines for all future work."
 		},
 		"line": {
 			"$value": "rgba({gray.70}, 1)",
-			"$description": "Default line/border color."
+			"$description": "Use with the Base style set."
 		},
 		"line-hover": {
 			"$value": "rgba({gray.90}, 1)",
-			"$description": "Line color, hover state."
+			"$description": "Use with the Base style set."
 		},
 		"line-active": {
 			"$value": "rgba({gray.100}, 1)",
-			"$description": "Line color, active state."
+			"$description": "Use with the Base style set."
 		},
 		"line-selected": {
 			"$value": "rgba({gray.90}, 1)",
-			"$description": "Line color, selected state."
+			"$description": "Use with the Base style set."
 		},
 		"line-disabled": {
 			"$value": "rgba({gray.40}, 1)",
-			"$description": "Line color for disabled controls."
+			"$description": "In the product the current usage aligns to --mrl-gray-50 but Design provided new guidelines for all future work."
 		},
 		"line-secondary": {
 			"$value": "rgba({gray.30}, 1)",
@@ -170,29 +142,25 @@
 			"$value": "rgba({blue.20}, 1)",
 			"$description": "Line color for decorative, non-interactive surfaces."
 		},
-		"line-highlight-secondary": {
-			"$value": "{color.line-secondary}",
-			"$description": "Deprecated — use `line-secondary` instead."
-		},
 		"line-divider": {
 			"$value": "rgba({gray.20}, 1)",
-			"$description": "Divider line color."
+			"$description": "Design calls this Light but we want a more semantic name in the code base."
 		},
 		"line-divider-inverse": {
 			"$value": "rgba({gray.80}, 1)",
-			"$description": "Divider line color on inverse surfaces."
+			"$description": "Design calls this Dark but we want a more semantic name in the code base. This is intended for use on dark or saturated backgrounds."
 		},
 		"line-emph": {
 			"$value": "rgba({gray.20}, 1)",
-			"$description": "Emphasized line color."
+			"$description": "Use with the Base with Emphasis style set."
 		},
 		"line-emph-hover": {
 			"$value": "rgba({gray.90}, 1)",
-			"$description": "Emphasized line color, hover state."
+			"$description": "Use with the Base with Emphasis style set."
 		},
 		"line-emph-active": {
 			"$value": "rgba({black}, 1)",
-			"$description": "Emphasized line color, active state."
+			"$description": "Use with the Base with Emphasis style set."
 		},
 		"line-inverse": {
 			"$value": "rgba({white}, 1)",
@@ -217,7 +185,7 @@
 			},
 			"emph-selected": {
 				"$value": "rgba({gray.100}, 1)",
-				"$description": "Emphasized icon color, selected state."
+				"$description": "Used when there is an icon and you're following the Base with Emphasis style set. For all other states, the icon is the same color as the text."
 			}
 		},
 		"input-icon-default": {
@@ -226,115 +194,79 @@
 		},
 		"text": {
 			"$value": "rgba({gray.80}, 1)",
-			"$description": "Default body text color."
+			"$description": "Use for the Base style set."
 		},
 		"text-hover": {
 			"$value": "rgba({gray.90}, 1)",
-			"$description": "Text color, hover state."
+			"$description": "Use for the Base style set."
 		},
 		"text-active": {
 			"$value": "rgba({gray.90}, 1)",
-			"$description": "Text color, active state."
+			"$description": "Use for the Base style set."
 		},
 		"text-selected": {
 			"$value": "rgba({gray.100}, 1)",
-			"$description": "Text color, selected state."
+			"$description": "Use for the Base style set."
 		},
 		"text-disabled": {
 			"$value": "rgba({gray.40}, 1)",
-			"$description": "Text color for disabled controls."
+			"$description": "In the product the current usage aligns to --mrl-gray-50 but Design provided new guidelines for all future work."
 		},
 		"text-disabled-inverse": {
 			"$value": "rgba({white}, 1)",
-			"$description": "Disabled text color on inverse surfaces."
+			"$description": "Use when the background of the element uses --mrl-color-background-disabled."
 		},
 		"text-emph": {
 			"$value": "rgba({gray.90}, 1)",
-			"$description": "Emphasized text color."
+			"$description": "Use for the Base with Emphasis style set."
 		},
 		"text-emph-hover": {
 			"$value": "rgba({gray.90}, 1)",
-			"$description": "Emphasized text color, hover state."
+			"$description": "Use for the Base with Emphasis style set."
 		},
 		"text-emph-active": {
 			"$value": "rgba({black}, 1)",
-			"$description": "Emphasized text color, active state."
-		},
-		"text-highlight": {
-			"$value": "{color.text-emph}",
-			"$description": "Deprecated — use `text-emph` instead."
-		},
-		"text-highlight-hover": {
-			"$value": "{color.text-emph-hover}",
-			"$description": "Deprecated — use `text-emph-hover` instead."
-		},
-		"text-highlight-active": {
-			"$value": "{color.text-emph-active}",
-			"$description": "Deprecated — use `text-emph-active` instead."
-		},
-		"text-highlight-selected": {
-			"$value": "{color.text-inverse-selected}",
-			"$description": "Deprecated — use `text-inverse-selected` instead."
-		},
-		"text-highlight-emph": {
-			"$value": "{color.text-emph}",
-			"$description": "Deprecated — use `text-emph` instead."
-		},
-		"text-highlight-emph-hover": {
-			"$value": "{color.text-emph-hover}",
-			"$description": "Deprecated — use `text-emph-hover` instead."
-		},
-		"text-highlight-emph-active": {
-			"$value": "{color.text-emph-active}",
-			"$description": "Deprecated — use `text-emph-active` instead."
-		},
-		"text-highlight-emph-selected": {
-			"$value": "{color.text-inverse-selected}",
-			"$description": "Deprecated — use `text-inverse-selected` instead."
+			"$description": "Use for the Base with Emphasis style set."
 		},
 		"text-inverse": {
 			"$value": "rgba({white}, 1)",
-			"$description": "Text color on inverse surfaces."
+			"$description": "Use for Inverse or any saturated background color, such as statuses."
 		},
 		"text-inverse-secondary": {
 			"$value": "rgba({gray.10}, 1)",
-			"$description": "Secondary text color on inverse surfaces."
+			"$description": "Use for Inverse or any saturated background color, such as statuses. This should only be used when there are multiple text colors within a single element. If there is only one color, always use --mrl-color-text-inverse to create consistency."
 		},
 		"text-inverse-hover": {
 			"$value": "rgba({white}, 1)",
-			"$description": "Inverse text color, hover state."
+			"$description": "Use for Inverse or any saturated background color, such as statuses."
 		},
 		"text-inverse-active": {
 			"$value": "rgba({white}, 1)",
-			"$description": "Inverse text color, active state."
+			"$description": "Use for Inverse or any saturated background color, such as statuses."
 		},
 		"text-inverse-selected": {
 			"$value": "rgba({white}, 1)",
-			"$description": "Inverse text color, selected state."
-		},
-		"text-02": {
-			"$value": "{color.text-heading}",
-			"$description": "Deprecated — use `text-heading` instead."
+			"$description": "Use for Inverse or any saturated background color, such as statuses."
 		},
 		"text-secondary": {
 			"$value": "rgba({gray.70}, 1)",
-			"$description": "Secondary text color."
+			"$description": "Use for static text only; if you're working on an interactive element, use one of the defined style sets. This is also used for placeholder text within form elements."
 		},
 		"text-label": {
 			"$value": "rgba({gray.100}, 1)",
-			"$description": "Text color for form labels."
+			"$description": "Use for static text only; if you're working on an interactive element, use one of the defined style sets."
 		},
 		"text-heading": {
 			"$value": "rgba({gray.100}, 1)",
-			"$description": "Text color for headings."
+			"$description": "Use for static text only; if you're working on an interactive element, use one of the defined style sets."
 		},
 		"text-success": {
 			"$value": "rgba({status.success}, 1)",
-			"$description": "Text color for success messages."
+			"$description": "Use when the background is white/transparent only; for elements with a status color background use --mrl-color-text-inverse."
 		},
 		"text-warning": {
 			"$value": "rgba({gray.90}, 1)",
-			"$description": "Text color for warning messages."
+			"$description": "Use when the background is white/transparent only; for elements with a status color background use --mrl-color-text-inverse."
 		},
 		"text-warning-light": {
 			"$value": "rgba({gray.80}, 1)",
@@ -342,11 +274,11 @@
 		},
 		"text-error": {
 			"$value": "rgba({status.error}, 1)",
-			"$description": "Text color for error messages."
+			"$description": "Use when the background is white/transparent only; for elements with a status color background use --mrl-color-text-inverse."
 		},
 		"text-info": {
 			"$value": "rgba({status.info}, 1)",
-			"$description": "Text color for info messages."
+			"$description": "Use when the background is white/transparent only; for elements with a status color background use --mrl-color-text-inverse."
 		},
 		"text-private": {
 			"$value": "rgba({gray.100}, 1)",
@@ -354,23 +286,23 @@
 		},
 		"background-inverse-active": {
 			"$value": "{color.accent}",
-			"$description": "Inverse surface background, active state."
+			"$description": "Use only with --mrl-color-background-inverse; other colored backgrounds will have a different style set that's TBD."
 		},
 		"background-inverse-selected": {
 			"$value": "{color.accent}",
-			"$description": "Inverse surface background, selected state."
+			"$description": "Use only with --mrl-color-background-inverse; other colored backgrounds will have a different style set that's TBD."
 		},
 		"line-emph-selected": {
 			"$value": "{color.accent}",
-			"$description": "Emphasized line color, selected state."
+			"$description": "Use with the Base with Emphasis style set."
 		},
 		"text-emph-selected": {
 			"$value": "{color.accent}",
-			"$description": "Emphasized text color, selected state."
+			"$description": "Use for the Base with Emphasis style set."
 		},
 		"background-page": {
 			"$value": "rgb(243, 245, 246)",
-			"$description": "Intentional one-off page background (#f3f5f6)."
+			"$description": "This is an intentional one-off contextual token that does not use our standard color scales. It should only be used as the background color for non-canvas pages."
 		},
 		"background-hover": {
 			"$value": "{black-opacity.00}",

package/dist/tokens/contextual-variables/typography.json

@@ -2,35 +2,38 @@
 	"$description": "Contextual Typography Tokens. We have 6 different use cases for text: display, headlines, titles, body copy (text), and interactive UI elements. For each category, the default is the medium, [primary] variation. For use cases that have differences between mobile and desktop (display, and headline), we implement mobile as the default since our implementation follows a mobile-first philosophy for performance.",
 	"body-font": {
 		"$value": "{font-family.01}, sans-serif",
-		"$type": "fontFamily"
+		"$type": "fontFamily",
+		"$description": "Used for all body copy."
 	},
 	"heading": {
 		"font": {
 			"$value": "{font-family.01}, sans-serif",
-			"$type": "fontFamily"
+			"$type": "fontFamily",
+			"$description": "Used for most headings."
 		},
 		"font-alt": {
 			"$value": "{font-family.02}, serif",
-			"$type": "fontFamily"
+			"$type": "fontFamily",
+			"$description": "Used for headings with kind=\"display\"."
 		}
 	},
 	"type-size": {
 		"$description": "Typography - Font Size",
 		"display": {
 			"$value": "{font-size.08}",
-			"$description": "Contextual typography token."
+			"$description": "When the viewport is 600px or wider, this token uses --mrl-font-size-09."
 		},
 		"display-large": {
 			"$value": "{font-size.09}",
-			"$description": "Contextual typography token."
+			"$description": "When the viewport is 600px or wider, this token uses --mrl-font-size-10."
 		},
 		"display-small": {
 			"$value": "{font-size.07}",
-			"$description": "Contextual typography token."
+			"$description": "When the viewport is 600px or wider, this token uses --mrl-font-size-08."
 		},
 		"display-xsmall": {
 			"$value": "{font-size.06}",
-			"$description": "Contextual typography token."
+			"$description": "When the viewport is 600px or wider, this token uses --mrl-font-size-07."
 		},
 		"headline": {
 			"$value": "{font-size.06}",
@@ -38,7 +41,7 @@
 		},
 		"headline-large": {
 			"$value": "{font-size.06}",
-			"$description": "Contextual typography token."
+			"$description": "When the viewport is 600px or wider, this token uses --mrl-font-size-07."
 		},
 		"headline-small": {
 			"$value": "{font-size.04}",
@@ -74,23 +77,23 @@
 		"$type": "number",
 		"title": {
 			"$value": "{line-height.05}",
-			"$description": "Contextual typography token."
+			"$description": "The title use case follows the same line-height scale as text."
 		},
 		"title-large": {
 			"$value": "{line-height.06}",
-			"$description": "Contextual typography token."
+			"$description": "The title use case follows the same line-height scale as text."
 		},
 		"title-small": {
 			"$value": "{line-height.08}",
-			"$description": "Contextual typography token."
+			"$description": "The title use case follows the same line-height scale as text."
 		},
 		"title-xsmall": {
 			"$value": "{line-height.06}",
-			"$description": "Contextual typography token."
+			"$description": "The title use case follows the same line-height scale as text."
 		},
 		"title-xxsmall": {
 			"$value": "{line-height.06}",
-			"$description": "Contextual typography token."
+			"$description": "The title use case follows the same line-height scale as text."
 		},
 		"display": {
 			"$value": "{line-height.02}",
@@ -114,11 +117,11 @@
 		},
 		"headline-large": {
 			"$value": "{line-height.07}",
-			"$description": "Contextual typography token."
+			"$description": "When the viewport is 600px or wider, this token uses --mrl-line-height-06."
 		},
 		"headline-small": {
 			"$value": "{line-height.02}",
-			"$description": "Contextual typography token."
+			"$description": "When the viewport is 600px or wider, this token uses --mrl-line-height-09."
 		},
 		"text": {
 			"$value": "{line-height.09}",
@@ -226,7 +229,7 @@
 		},
 		"headline-small": {
 			"$value": "{letter-spacing.04}",
-			"$description": "Contextual typography token."
+			"$description": "When the viewport is 600px or wider, this token uses --mrl-letter-spacing-03."
 		},
 		"text": {
 			"$value": "{letter-spacing.03}",

package/dist/tokens/global-variables/typography.json

@@ -167,27 +167,27 @@
 		"01": {
 			"$value": 400,
 			"$type": "fontWeight",
-			"$description": "Font weight token."
+			"$description": "Regular. Font weight token."
 		},
 		"02": {
 			"$value": 500,
 			"$type": "fontWeight",
-			"$description": "Font weight token."
+			"$description": "Medium. Font weight token."
 		},
 		"03": {
 			"$value": 600,
 			"$type": "fontWeight",
-			"$description": "Font weight token."
+			"$description": "Semi-bold. Font weight token."
 		},
 		"04": {
 			"$value": 700,
 			"$type": "fontWeight",
-			"$description": "Font weight token."
+			"$description": "Bold. Font weight token."
 		},
 		"05": {
 			"$value": 800,
 			"$type": "fontWeight",
-			"$description": "Font weight token."
+			"$description": "Extra-bold. Font weight token."
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@muraldevkit/ds-foundation",
-	"version": "2.25.0",
+	"version": "2.27.0",
 	"description": "Mural's design system's Foundation package containing our design language features used across all components",
 	"license": "https://www.mural.co/terms/developer-addendum",
 	"scripts": {