@muraldevkit/ds-foundation 2.26.0 → 2.27.0

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

@@ -68,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)",
@@ -108,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)",
@@ -144,23 +144,23 @@
 		},
 		"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)",
@@ -185,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": {
@@ -194,79 +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."
+			"$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."
+			"$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)",
@@ -274,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)",
@@ -286,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.26.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": {