feat(font tokens): add font family fallbacks (#8389)

**Related Issue:** #7175 ## Summary Add font family fallbacks to tokens and update the transformer to know how to interpret those for Styles
Esri · Dec 18, 2023 · b2fd255 · b2fd255
1 parent afbcb09
commit b2fd255
Show file tree

Hide file tree

Showing 6 changed files with 149 additions and 23 deletions.
diff --git a/packages/calcite-design-tokens/src/core/font.json b/packages/calcite-design-tokens/src/core/font.json
@@ -2,6 +2,11 @@
   "core": {
     "font": {
       "family": {
+        "andaleMono": {
+          "value": "Andale Mono",
+          "type": "fontFamilies",
+          "description": "Fallback for Monaco"
+        },
         "avenirNextPro": {
           "value": "Avenir Next LT Pro",
           "type": "fontFamilies"
@@ -10,9 +15,39 @@
           "value": "Avenir Next World",
           "type": "fontFamilies"
         },
+        "avenir": {
+          "value": "Avenir",
+          "type": "fontFamilies",
+          "description": "Fallback for Avenir Next"
+        },
+        "consolas": {
+          "value": "Consolas",
+          "type": "fontFamilies",
+          "description": "Fallback for Monaco"
+        },
+        "helveticaNeue": {
+          "value": "Helvetica Neue",
+          "type": "fontFamilies",
+          "description": "Fallback for Avenir Next"
+        },
+        "lucidaConsole": {
+          "value": "Lucida Console",
+          "type": "fontFamilies",
+          "description": "Fallback for Monaco"
+        },
         "monaco": {
           "value": "Monaco",
           "type": "fontFamilies"
+        },
+        "monospace": {
+          "value": "monospace",
+          "type": "fontFamilies",
+          "description": "Fallback for Monaco"
+        },
+        "sansSerif": {
+          "value": "sans-serif",
+          "type": "fontFamilies",
+          "description": "Fallback for Avenir Next"
         }
       },
       "style": {

diff --git a/packages/calcite-design-tokens/src/semantic/font.json b/packages/calcite-design-tokens/src/semantic/font.json
@@ -3,12 +3,26 @@
     "font": {
       "family": {
         "default": {
-          "value": "{core.font.family.avenirNextPro}",
-          "type": "fontFamilies"
+          "value": [
+            "{core.font.family.avenirNextWorld}",
+            "{core.font.family.avenirNextPro}",
+            "{core.font.family.avenir}",
+            "{core.font.family.helveticaNeue}",
+            "{core.font.family.sansSerif}"
+          ],
+          "type": "fontFamilies",
+          "description": "Primary font with fallbacks"
         },
         "code": {
-          "value": "{core.font.family.monaco}",
-          "type": "fontFamilies"
+          "value": [
+            "{core.font.family.monaco}",
+            "{core.font.family.consolas}",
+            "{core.font.family.andaleMono}",
+            "{core.font.family.lucidaConsole}",
+            "{core.font.family.monospace}"
+          ],
+          "type": "fontFamilies",
+          "description": "Font family for code with fallbacks"
         }
       },
       "weight": {

diff --git a/packages/calcite-design-tokens/support/tests/__snapshots__/index.spec.ts.snap b/packages/calcite-design-tokens/support/tests/__snapshots__/index.spec.ts.snap
@@ -86,9 +86,16 @@ exports[`generated tokens CSS core should match 1`] = `
   --calcite-font-weight-thin: 100;
   --calcite-font-weight-ultralight: 200; /* only for Avenir Next World (secondary font family) */
   --calcite-font-style-italic: italic; /* used in ratings */
+  --calcite-font-family-sans-serif: sans-serif; /* Fallback for Avenir Next */
+  --calcite-font-family-monospace: monospace; /* Fallback for Monaco */
   --calcite-font-family-monaco: Monaco;
+  --calcite-font-family-lucida-console: "Lucida Console"; /* Fallback for Monaco */
+  --calcite-font-family-helvetica-neue: "Helvetica Neue"; /* Fallback for Avenir Next */
+  --calcite-font-family-consolas: Consolas; /* Fallback for Monaco */
+  --calcite-font-family-avenir: Avenir; /* Fallback for Avenir Next */
   --calcite-font-family-avenir-next-world: "Avenir Next World";
   --calcite-font-family-avenir-next-pro: "Avenir Next LT Pro";
+  --calcite-font-family-andale-mono: "Andale Mono"; /* Fallback for Monaco */
   --calcite-container-size-1440: 1440px;
   --calcite-container-size-1152: 1152px;
   --calcite-container-size-854: 854px;
@@ -438,8 +445,10 @@ exports[`generated tokens CSS global should match 1`] = `
   --calcite-font-weight-regular: 400;
   --calcite-font-weight-normal: 400; /* For backwards compatibility only. This token will be removed from the published tokens in the next major in favor of the more descriptive word "regular" */
   --calcite-font-weight-light: 300; /* For Avenir Next World (secondary font family) */
-  --calcite-font-family-code: Monaco;
-  --calcite-font-family: "Avenir Next LT Pro";
+  --calcite-font-family-code: Monaco Consolas "Andale Mono" "Lucida Console"
+    monospace; /* Font family for code with fallbacks */
+  --calcite-font-family: "Avenir Next World" "Avenir Next LT Pro" Avenir
+    "Helvetica Neue" sans-serif; /* Primary font with fallbacks */
   --calcite-container-size-content-fixed: 1440px; /* only for lg breakpoint fixed grid width */
   --calcite-container-size-content-fluid: 100%; /* for fluid grid widths */
   --calcite-container-size-gutter: 16px;
@@ -727,9 +736,16 @@ export const calciteContainerSize768 = "768px";
 export const calciteContainerSize854 = "854px";
 export const calciteContainerSize1152 = "1152px";
 export const calciteContainerSize1440 = "1440px";
+export const calciteFontFamilyAndaleMono = "Andale Mono"; // Fallback for Monaco
 export const calciteFontFamilyAvenirNextPro = "Avenir Next LT Pro";
 export const calciteFontFamilyAvenirNextWorld = "Avenir Next World";
+export const calciteFontFamilyAvenir = "Avenir"; // Fallback for Avenir Next
+export const calciteFontFamilyConsolas = "Consolas"; // Fallback for Monaco
+export const calciteFontFamilyHelveticaNeue = "Helvetica Neue"; // Fallback for Avenir Next
+export const calciteFontFamilyLucidaConsole = "Lucida Console"; // Fallback for Monaco
 export const calciteFontFamilyMonaco = "Monaco";
+export const calciteFontFamilyMonospace = "monospace"; // Fallback for Monaco
+export const calciteFontFamilySansSerif = "sans-serif"; // Fallback for Avenir Next
 export const calciteFontStyleItalic = "italic"; // used in ratings
 export const calciteFontWeightUltralight = "200"; // only for Avenir Next World (secondary font family)
 export const calciteFontWeightThin = "100";
@@ -888,8 +904,8 @@ export const calciteContainerSizeMargin = "24px";
 export const calciteContainerSizeGutter = "16px";
 export const calciteContainerSizeContentFluid = "100%"; // for fluid grid widths
 export const calciteContainerSizeContentFixed = "1440px"; // only for lg breakpoint fixed grid width
-export const calciteFontFamily = "Avenir Next LT Pro";
-export const calciteFontFamilyCode = "Monaco";
+export const calciteFontFamily = ["Avenir Next World","Avenir Next LT Pro","Avenir","Helvetica Neue","sans-serif"]; // Primary font with fallbacks
+export const calciteFontFamilyCode = ["Monaco","Consolas","Andale Mono","Lucida Console","monospace"]; // Font family for code with fallbacks
 export const calciteFontWeightLight = "300"; // For Avenir Next World (secondary font family)
 export const calciteFontWeightNormal = "400"; // For backwards compatibility only. This token will be removed from the published tokens in the next major in favor of the more descriptive word "regular"
 export const calciteFontWeightRegular = "400";
@@ -954,15 +970,15 @@ export const calciteSpacingLg = "14px";
 export const calciteSpacingXl = "16px";
 export const calciteSpacingXxl = "20px";
 export const calciteSpacingXxxl = "32px";
-export const calciteTypography = {"fontFamily":"Avenir Next LT Pro","fontSize":"14px","fontWeight":"400","letterSpacing":"0","lineHeight":"16px","paragraphSpacing":"4px","textCase":"none","textDecoration":"none"};
+export const calciteTypography = {"fontFamily":["Avenir Next World","Avenir Next LT Pro","Avenir","Helvetica Neue","sans-serif"],"fontSize":"14px","fontWeight":"400","letterSpacing":"0","lineHeight":"16px","paragraphSpacing":"4px","textCase":"none","textDecoration":"none"};
 export const calciteTypographyLightMinus3h = {"fontSize":"10px","fontWeight":"300","lineHeight":"12px"};
 export const calciteTypographyLightMinus2h = {"fontSize":"12px","fontWeight":"300"};
 export const calciteTypographyLightMinus1h = {"fontWeight":"300"};
 export const calciteTypographyLight0h = {"fontSize":"16px","fontWeight":"300","lineHeight":"20px"};
 export const calciteTypographyLight1h = {"fontSize":"18px","fontWeight":"300","lineHeight":"24px"};
 export const calciteTypographyRegularMinus3h = {"lineHeight":"12px","fontSize":"10px"};
 export const calciteTypographyRegularMinus2h = {"fontSize":"12px"};
-export const calciteTypographyRegularMinus1h = {"fontFamily":"Avenir Next LT Pro","fontSize":"14px","fontWeight":"400","letterSpacing":"0","lineHeight":"16px","paragraphSpacing":"4px","textCase":"none","textDecoration":"none"};
+export const calciteTypographyRegularMinus1h = {"fontFamily":["Avenir Next World","Avenir Next LT Pro","Avenir","Helvetica Neue","sans-serif"],"fontSize":"14px","fontWeight":"400","letterSpacing":"0","lineHeight":"16px","paragraphSpacing":"4px","textCase":"none","textDecoration":"none"};
 export const calciteTypographyRegular0h = {"lineHeight":"20px","fontSize":"16px"};
 export const calciteTypographyRegular1h = {"lineHeight":"24px","fontSize":"18px"};
 export const calciteTypographyMediumMinus3h = {"fontWeight":"500","lineHeight":"12px","fontSize":"10px"};
@@ -1007,7 +1023,7 @@ export const calciteTypographyHierarchyHeading3 = {"fontWeight":"500","lineHeigh
 export const calciteTypographyHierarchyHeading4 = {"fontWeight":"500","lineHeight":"137.5%","fontSize":"16px"};
 export const calciteTypographyHierarchyHeading5 = {"fontWeight":"500","lineHeight":"137.5%"};
 export const calciteTypographyHierarchyBodySnug = {"lineHeight":"137.5%"};
-export const calciteTypographyHierarchyBody = {"fontFamily":"Avenir Next LT Pro","fontSize":"14px","fontWeight":"400","letterSpacing":"0","lineHeight":"16px","paragraphSpacing":"4px","textCase":"none","textDecoration":"none"};
+export const calciteTypographyHierarchyBody = {"fontFamily":["Avenir Next World","Avenir Next LT Pro","Avenir","Helvetica Neue","sans-serif"],"fontSize":"14px","fontWeight":"400","letterSpacing":"0","lineHeight":"16px","paragraphSpacing":"4px","textCase":"none","textDecoration":"none"};
 export const calciteTypographyHierarchyOverline = {"lineHeight":"12px","textCase":"uppercase","fontWeight":"700"};
 export const calciteTypographyHierarchyCaption = {"lineHeight":"137.5%","fontSize":"12px"};
 export const calciteZIndexDeep = "-999999";
@@ -1105,8 +1121,10 @@ export const calciteContainerSizeGutter : string;
 export const calciteContainerSizeContentFluid : string;
 /** only for lg breakpoint fixed grid width */
 export const calciteContainerSizeContentFixed : string;
-export const calciteFontFamily : string;
-export const calciteFontFamilyCode : string;
+/** Primary font with fallbacks */
+export const calciteFontFamily : string[];
+/** Font family for code with fallbacks */
+export const calciteFontFamilyCode : string[];
 /** For Avenir Next World (secondary font family) */
 export const calciteFontWeightLight : string;
 /** For backwards compatibility only. This token will be removed from the published tokens in the next major in favor of the more descriptive word "regular" */
@@ -1180,15 +1198,15 @@ export const calciteSpacingLg : string;
 export const calciteSpacingXl : string;
 export const calciteSpacingXxl : string;
 export const calciteSpacingXxxl : string;
-export const calciteTypography : { fontFamily: string, fontSize: string, fontWeight: string, letterSpacing: string, lineHeight: string, paragraphSpacing: string, textCase: string, textDecoration: string };
+export const calciteTypography : { fontFamily: string[], fontSize: string, fontWeight: string, letterSpacing: string, lineHeight: string, paragraphSpacing: string, textCase: string, textDecoration: string };
 export const calciteTypographyLightMinus3h : { fontSize: string, fontWeight: string, lineHeight: string };
 export const calciteTypographyLightMinus2h : { fontSize: string, fontWeight: string };
 export const calciteTypographyLightMinus1h : { fontWeight: string };
 export const calciteTypographyLight0h : { fontSize: string, fontWeight: string, lineHeight: string };
 export const calciteTypographyLight1h : { fontSize: string, fontWeight: string, lineHeight: string };
 export const calciteTypographyRegularMinus3h : { lineHeight: string, fontSize: string };
 export const calciteTypographyRegularMinus2h : { fontSize: string };
-export const calciteTypographyRegularMinus1h : { fontFamily: string, fontSize: string, fontWeight: string, letterSpacing: string, lineHeight: string, paragraphSpacing: string, textCase: string, textDecoration: string };
+export const calciteTypographyRegularMinus1h : { fontFamily: string[], fontSize: string, fontWeight: string, letterSpacing: string, lineHeight: string, paragraphSpacing: string, textCase: string, textDecoration: string };
 export const calciteTypographyRegular0h : { lineHeight: string, fontSize: string };
 export const calciteTypographyRegular1h : { lineHeight: string, fontSize: string };
 export const calciteTypographyMediumMinus3h : { fontWeight: string, lineHeight: string, fontSize: string };
@@ -1233,7 +1251,7 @@ export const calciteTypographyHierarchyHeading3 : { fontWeight: string, lineHeig
 export const calciteTypographyHierarchyHeading4 : { fontWeight: string, lineHeight: string, fontSize: string };
 export const calciteTypographyHierarchyHeading5 : { fontWeight: string, lineHeight: string };
 export const calciteTypographyHierarchyBodySnug : { lineHeight: string };
-export const calciteTypographyHierarchyBody : { fontFamily: string, fontSize: string, fontWeight: string, letterSpacing: string, lineHeight: string, paragraphSpacing: string, textCase: string, textDecoration: string };
+export const calciteTypographyHierarchyBody : { fontFamily: string[], fontSize: string, fontWeight: string, letterSpacing: string, lineHeight: string, paragraphSpacing: string, textCase: string, textDecoration: string };
 export const calciteTypographyHierarchyOverline : { lineHeight: string, textCase: string, fontWeight: string };
 export const calciteTypographyHierarchyCaption : { lineHeight: string, fontSize: string };
 export const calciteZIndexDeep : string;
@@ -1466,9 +1484,23 @@ export const calciteContainerSize768 : string;
 export const calciteContainerSize854 : string;
 export const calciteContainerSize1152 : string;
 export const calciteContainerSize1440 : string;
+/** Fallback for Monaco */
+export const calciteFontFamilyAndaleMono : string;
 export const calciteFontFamilyAvenirNextPro : string;
 export const calciteFontFamilyAvenirNextWorld : string;
+/** Fallback for Avenir Next */
+export const calciteFontFamilyAvenir : string;
+/** Fallback for Monaco */
+export const calciteFontFamilyConsolas : string;
+/** Fallback for Avenir Next */
+export const calciteFontFamilyHelveticaNeue : string;
+/** Fallback for Monaco */
+export const calciteFontFamilyLucidaConsole : string;
 export const calciteFontFamilyMonaco : string;
+/** Fallback for Monaco */
+export const calciteFontFamilyMonospace : string;
+/** Fallback for Avenir Next */
+export const calciteFontFamilySansSerif : string;
 /** used in ratings */
 export const calciteFontStyleItalic : string;
 /** only for Avenir Next World (secondary font family) */
@@ -1649,9 +1681,16 @@ $calcite-font-weight-light: 300; // only for Avenir Next World (secondary font f
 $calcite-font-weight-thin: 100;
 $calcite-font-weight-ultralight: 200; // only for Avenir Next World (secondary font family)
 $calcite-font-style-italic: italic; // used in ratings
+$calcite-font-family-sans-serif: sans-serif; // Fallback for Avenir Next
+$calcite-font-family-monospace: monospace; // Fallback for Monaco
 $calcite-font-family-monaco: Monaco;
+$calcite-font-family-lucida-console: "Lucida Console"; // Fallback for Monaco
+$calcite-font-family-helvetica-neue: "Helvetica Neue"; // Fallback for Avenir Next
+$calcite-font-family-consolas: Consolas; // Fallback for Monaco
+$calcite-font-family-avenir: Avenir; // Fallback for Avenir Next
 $calcite-font-family-avenir-next-world: "Avenir Next World";
 $calcite-font-family-avenir-next-pro: "Avenir Next LT Pro";
+$calcite-font-family-andale-mono: "Andale Mono"; // Fallback for Monaco
 $calcite-container-size-1440: 1440px;
 $calcite-container-size-1152: 1152px;
 $calcite-container-size-854: 854px;
@@ -1994,8 +2033,10 @@ $calcite-font-weight-medium: 500;
 $calcite-font-weight-regular: 400;
 $calcite-font-weight-normal: 400; // For backwards compatibility only. This token will be removed from the published tokens in the next major in favor of the more descriptive word "regular"
 $calcite-font-weight-light: 300; // For Avenir Next World (secondary font family)
-$calcite-font-family-code: Monaco;
-$calcite-font-family: "Avenir Next LT Pro";
+$calcite-font-family-code: Monaco Consolas "Andale Mono" "Lucida Console"
+  monospace; // Font family for code with fallbacks
+$calcite-font-family: "Avenir Next World" "Avenir Next LT Pro" Avenir
+  "Helvetica Neue" sans-serif; // Primary font with fallbacks
 $calcite-container-size-content-fixed: 1440px; // only for lg breakpoint fixed grid width
 $calcite-container-size-content-fluid: 100%; // for fluid grid widths
 $calcite-container-size-gutter: 16px;

diff --git a/packages/calcite-design-tokens/support/token-transformer/registerCalciteTransformers.ts b/packages/calcite-design-tokens/support/token-transformer/registerCalciteTransformers.ts
@@ -18,6 +18,7 @@ import { registerValueRGBA } from "./styleDictionary/transformer/value/valueRGBA
 import { registerNameSpacePath } from "./styleDictionary/transformer/name/nameSpacePath.js";
 import { registerFormatterDocs } from "./styleDictionary/formatter/docs.js";
 import { registerValueToREM } from "./styleDictionary/transformer/value/valueToREM.js";
+import { registerValueFontFamilyWithFallbacks } from "./styleDictionary/transformer/value/valueFontFamilyFallbacks.js";
 
 export async function registerCalciteTransformers(sd: StyleDictionary): Promise<void> {
   // Here we are registering the Transforms provided by Token Studio however,
@@ -27,21 +28,22 @@ export async function registerCalciteTransformers(sd: StyleDictionary): Promise<
   await registerTransforms(sd, {
     expand: false,
   });
-  registerValueRGBA(sd);
-  registerValueEvaluateMath(sd);
   registerAttributePlatformNames(sd);
   registerCustomJSONParser(sd);
   registerFilterSource(sd);
   registerFormatterCss(sd);
-  registerFormatterScss(sd);
+  registerFormatterDocs(sd);
   registerFormatterJs(sd);
+  registerFormatterScss(sd);
   registerNameCamelCase(sd);
   registerNameJoinPath(sd);
   registerNameKebabCase(sd);
+  registerNameSpacePath(sd);
   registerValueAlignFontWeightAndStyles(sd);
   registerValueAssetToken(sd);
+  registerValueEvaluateMath(sd);
+  registerValueFontFamilyWithFallbacks(sd);
+  registerValueRGBA(sd);
   registerValueStringWrapper(sd);
-  registerNameSpacePath(sd);
-  registerFormatterDocs(sd);
   registerValueToREM(sd);
 }
diff --git a/...ages/calcite-design-tokens/support/token-transformer/styleDictionary/transformer/utils.ts b/...ages/calcite-design-tokens/support/token-transformer/styleDictionary/transformer/utils.ts
@@ -15,6 +15,7 @@ import { valueEvaluateMath } from "./value/valueCheckEvaluateMath.js";
 import { CalciteValueRGBA } from "./value/valueRGBA.js";
 import { nameSpacePath } from "./name/nameSpacePath.js";
 import { CalciteValueToREM } from "./value/valueToREM.js";
+import { valueFontFamilyFallbacks } from "./value/valueFontFamilyFallbacks.js";
 
 export type TransformerTypeUnion = `${TransformerTypeEnum}`;
 
@@ -51,6 +52,7 @@ export const styles = [
   valueAssetToken,
   valueStringWrapper,
   CalciteValueToREM,
+  valueFontFamilyFallbacks,
   nameKebabCase,
 ];
 

diff --git a/...s/support/token-transformer/styleDictionary/transformer/value/valueFontFamilyFallbacks.ts b/...s/support/token-transformer/styleDictionary/transformer/value/valueFontFamilyFallbacks.ts
@@ -0,0 +1,32 @@
+import { Core as StyleDictionary } from "style-dictionary";
+import { Matcher } from "style-dictionary/types/Matcher.js";
+import { TransformedToken } from "style-dictionary/types/TransformedToken.js";
+import { TokenTypes } from "@tokens-studio/types";
+
+import { CalledTransformerFunction, TransformerConfig } from "../utils.js";
+
+export const matcher: Matcher = (token: TransformedToken) => {
+  return token.type === TokenTypes.FONT_FAMILIES && Array.isArray(token.value);
+};
+
+type FontFamilyFallbackToken = TransformedToken & { value: string[] };
+
+export const transformValuesFontFamilyWithFallbacks: CalledTransformerFunction<string> = (
+  token: FontFamilyFallbackToken
+) => {
+  return token.value.join(" ");
+};
+
+export const registerValueFontFamilyWithFallbacks = (sd: StyleDictionary): void => {
+  const transformerConfig: TransformerConfig = {
+    name: valueFontFamilyFallbacks,
+    transformer: transformValuesFontFamilyWithFallbacks,
+    type: "value",
+    matcher,
+    transitive: true,
+  };
+
+  sd.registerTransform(transformerConfig);
+};
+
+export const valueFontFamilyFallbacks = "value/calcite/font-family";