@atlaskit/eslint-plugin-design-system 10.9.0 → 10.10.1

package/dist/cjs/rules/utils/error-boundary.js

@@ -1,9 +1,18 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.errorBoundary = void 0;
+exports.errorBoundary = errorBoundary;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
+// eslint-disable-next-line import/no-extraneous-dependencies
+
+// Need to intersect type RuleListener with a generic function to allow use of Parameters<...> to be used
+
+// Allow config to be to be easily passed from rules
+
 /**
  * ESLint rules should NEVER throw exceptions, because that breaks the VSCode ESLint server
  * (and probably the IntelliJ one too), which causes linting to fail in a file.
@@ -11,14 +20,52 @@ exports.errorBoundary = void 0;
  * It also breaks CI, which was the reason this error boundary was added. It's a final
  * catch all.
  */
-var errorBoundary = exports.errorBoundary = function errorBoundary(func, _ref) {
-  var config = _ref.config;
-  try {
-    func();
-  } catch (err) {
-    if (!config.failSilently) {
-      // eslint-disable-next-line no-console
-      console.warn(err);
-    }
+function errorBoundary(ruleOrRules) {
+  var config = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+  var failSilently = failSilentlyFromConfig(config);
+  if (isSingleRuleListener(ruleOrRules)) {
+    return wrapSingleRuleListener(ruleOrRules, failSilently);
+  }
+  return wrapRuleListener(ruleOrRules, failSilently);
+}
+function isSingleRuleListener(rule) {
+  return typeof rule === 'function';
+}
+function failSilentlyFromConfig(c) {
+  switch ((0, _typeof2.default)(c)) {
+    case 'undefined':
+      return false;
+    case 'boolean':
+      return c;
+    case 'object':
+      if ('failSilently' in c) {
+        var _c$failSilently;
+        return (_c$failSilently = c.failSilently) !== null && _c$failSilently !== void 0 ? _c$failSilently : false;
+      } else if ('config' in c) {
+        var _c$config$failSilentl;
+        return (_c$config$failSilentl = c.config.failSilently) !== null && _c$config$failSilentl !== void 0 ? _c$config$failSilentl : false;
+      }
+      return false;
+    default:
+      throw new Error('Invalid config');
   }
-};
+}
+function wrapSingleRuleListener(rule, failSilently) {
+  return function () {
+    try {
+      rule.apply(void 0, arguments);
+    } catch (err) {
+      if (!failSilently) {
+        // eslint-disable-next-line no-console
+        console.warn(err);
+      }
+    }
+  };
+}
+function wrapRuleListener(ruleListener, failSilently) {
+  return Object.entries(ruleListener).reduce(function (wrappedRuleListener, e) {
+    var ruleName = e[0];
+    var rule = e[1];
+    return Object.assign(wrappedRuleListener, (0, _defineProperty2.default)({}, ruleName, wrapSingleRuleListener(rule, failSilently)));
+  }, {});
+}

package/dist/es2019/presets/all.codegen.js

@@ -1,6 +1,6 @@
 /**
  * THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
- * @codegen <<SignedSource::9bb5329713677543f16019954484ae2f>>
+ * @codegen <<SignedSource::ab43b6e1a867d07b9a27eae78d48834a>>
  * @codegenCommand yarn workspace @atlaskit/eslint-plugin-design-system codegen
  */
 export default {
@@ -12,6 +12,7 @@ export default {
     '@atlaskit/design-system/icon-label': 'warn',
     '@atlaskit/design-system/no-banned-imports': 'error',
     '@atlaskit/design-system/no-css-tagged-template-expression': 'error',
+    '@atlaskit/design-system/no-custom-icons': 'warn',
     '@atlaskit/design-system/no-deprecated-apis': 'error',
     '@atlaskit/design-system/no-deprecated-design-token-usage': 'warn',
     '@atlaskit/design-system/no-deprecated-imports': 'error',

package/dist/es2019/rules/ensure-design-token-usage/index.js

@@ -27,25 +27,21 @@ const createWithConfig = initialConfig => context => {
     failSilently: (userConfig === null || userConfig === void 0 ? void 0 : userConfig.failSilently) || defaultConfig.failSilently
   };
   let tokenNode = null;
-  return {
-    ImportDeclaration: node => errorBoundary(() => {
+  return errorBoundary({
+    ImportDeclaration: node => {
       if (node.source.value === '@atlaskit/tokens' && config.applyImport) {
         tokenNode = node;
       }
-    }, {
-      config
-    }),
+    },
     // For expressions within template literals (e.g. `color: ${red}`) - color only
-    'TemplateLiteral > Identifier': node => errorBoundary(() => {
+    'TemplateLiteral > Identifier': node => {
       if (config.domains.includes('color')) {
         return lintTemplateIdentifierForColor(node, context, config);
       }
       return;
-    }, {
-      config
-    }),
+    },
     // const styles = css({ color: 'red', margin: '4px' }), styled.div({ color: 'red', margin: '4px' })
-    ObjectExpression: parentNode => errorBoundary(() => {
+    ObjectExpression: parentNode => {
       const {
         references
       } = context.getScope();
@@ -115,13 +111,11 @@ const createWithConfig = initialConfig => context => {
         }
       }
       parentNode.properties.forEach(findObjectStyles);
-    }, {
-      config
-    }),
+    },
     // CSSTemplateLiteral and StyledTemplateLiteral
     // const cssTemplateLiteral = css`color: red; padding: 12px`;
     // const styledTemplateLiteral = styled.p`color: red; padding: 8px`;
-    'TaggedTemplateExpression[tag.name="css"],TaggedTemplateExpression[tag.object.name="styled"],TaggedTemplateExpression[tag.callee.name="styled"]': node => errorBoundary(() => {
+    'TaggedTemplateExpression[tag.name="css"],TaggedTemplateExpression[tag.object.name="styled"],TaggedTemplateExpression[tag.callee.name="styled"]': node => {
       // To force the correct node type
       if (!isNodeOfType(node, 'TaggedTemplateExpression')) {
         return;
@@ -249,37 +243,29 @@ const createWithConfig = initialConfig => context => {
           }
         });
       }
-    }, {
-      config
-    }),
+    },
     // For inline JSX styles - literals (e.g. <Test color="red"/>) - color only
-    'JSXAttribute > Literal': node => errorBoundary(() => {
+    'JSXAttribute > Literal': node => {
       if (config.domains.includes('color')) {
         return lintJSXLiteralForColor(node, context, config);
       }
       return;
-    }, {
-      config
-    }),
+    },
     // For inline JSX styles - members (e.g. <Test color={color.red}/>) - color only
-    'JSXExpressionContainer > MemberExpression': node => errorBoundary(() => {
+    'JSXExpressionContainer > MemberExpression': node => {
       if (config.domains.includes('color')) {
         return lintJSXMemberForColor(node, context, config);
       }
       return;
-    }, {
-      config
-    }),
+    },
     // For inline JSX styles - identifiers (e.g. <Test color={red}/>) - color only
-    'JSXExpressionContainer > Identifier': node => errorBoundary(() => {
+    'JSXExpressionContainer > Identifier': node => {
       if (config.domains.includes('color')) {
         return lintJSXIdentifierForColor(node, context, config);
       }
       return;
-    }, {
-      config
-    })
-  };
+    }
+  }, config);
 };
 const rule = createLintRule({
   meta: ruleMeta,

package/dist/es2019/rules/index.codegen.js

@@ -1,6 +1,6 @@
 /**
  * THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
- * @codegen <<SignedSource::b359d356c482db0087ddfce5bd105403>>
+ * @codegen <<SignedSource::402e6eb5433560b1032e5ed926bb5564>>
  * @codegenCommand yarn workspace @atlaskit/eslint-plugin-design-system codegen
  */
 import consistentCssPropUsage from './consistent-css-prop-usage';
@@ -9,6 +9,7 @@ import ensureDesignTokenUsagePreview from './ensure-design-token-usage-preview';
 import iconLabel from './icon-label';
 import noBannedImports from './no-banned-imports';
 import noCssTaggedTemplateExpression from './no-css-tagged-template-expression';
+import noCustomIcons from './no-custom-icons';
 import noDeprecatedApis from './no-deprecated-apis';
 import noDeprecatedDesignTokenUsage from './no-deprecated-design-token-usage';
 import noDeprecatedImports from './no-deprecated-imports';
@@ -50,6 +51,7 @@ export default {
   'icon-label': iconLabel,
   'no-banned-imports': noBannedImports,
   'no-css-tagged-template-expression': noCssTaggedTemplateExpression,
+  'no-custom-icons': noCustomIcons,
   'no-deprecated-apis': noDeprecatedApis,
   'no-deprecated-design-token-usage': noDeprecatedDesignTokenUsage,
   'no-deprecated-imports': noDeprecatedImports,

package/dist/es2019/rules/no-custom-icons/checks/has-prop.js

@@ -0,0 +1,4 @@
+import { isNodeOfType } from 'eslint-codemod-utils';
+export function hasProp(node, propName) {
+  return isNodeOfType(node.openingElement, 'JSXOpeningElement') && node.openingElement.attributes.some(a => a.type === 'JSXAttribute' && a.name.name === propName);
+}

package/dist/es2019/rules/no-custom-icons/checks/is-from-import-source.js

@@ -0,0 +1,23 @@
+import { isImportedJSXElement } from './is-imported-jsx-element';
+export function createIsFromImportSourceFor(...importSources) {
+  const literalImportSources = importSources.filter(s => typeof s === 'string');
+  const matchImportSources = importSources.filter(s => s instanceof RegExp);
+  const varImportSourceMap = new Map();
+  function isFromImportSource(node) {
+    return isImportedJSXElement(node) && varImportSourceMap.has(node.openingElement.name.name);
+  }
+  isFromImportSource.importDeclarationHook = node => {
+    const source = node.source.value;
+    if (typeof source !== 'string' || !(literalImportSources.includes(source) || matchImportSources.some(r => r.test(source)))) {
+      return;
+    }
+    node.specifiers.filter(spec => ['ImportSpecifier', 'ImportDefaultSpecifier'].includes(spec.type)).forEach(spec => varImportSourceMap.set(spec.local.name, source));
+  };
+  isFromImportSource.getImportSource = node => {
+    if (!isFromImportSource(node)) {
+      throw new Error('Node is not an imported JSX element');
+    }
+    return varImportSourceMap.get(node.openingElement.name.name);
+  };
+  return isFromImportSource;
+}

package/dist/es2019/rules/no-custom-icons/checks/is-imported-jsx-element.js

@@ -0,0 +1,4 @@
+import { isNodeOfType } from 'eslint-codemod-utils';
+export function isImportedJSXElement(node) {
+  return isNodeOfType(node, 'JSXElement') && isNodeOfType(node.openingElement.name, 'JSXIdentifier');
+}

package/dist/es2019/rules/no-custom-icons/index.js

@@ -0,0 +1,61 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+
+import { createLintRule } from '../utils/create-rule';
+import { errorBoundary } from '../utils/error-boundary';
+import { hasProp } from './checks/has-prop';
+import { createIsFromImportSourceFor } from './checks/is-from-import-source';
+const rule = createLintRule({
+  meta: {
+    name: 'no-custom-icons',
+    type: 'problem',
+    docs: {
+      description: 'Enforces custom glyph icons are used.',
+      recommended: false,
+      severity: 'warn'
+    },
+    schema: [{
+      type: 'object',
+      properties: {
+        centralLocation: {
+          type: 'string'
+        },
+        failSilently: {
+          type: 'boolean'
+        }
+      },
+      additionalProperties: false
+    }],
+    messages: {
+      noCustomIcons: `Custom icons from {{importSource}} are no longer supported. Migrate to an icon from '@atlaskit/(icon-labs|icon/core|icon/utility)'{{locationMessage}}.
+[Migration guide](https://hello.atlassian.net/wiki/spaces/DST/pages/3748692796/New+ADS+iconography+-+Code+migration+guide).`
+    }
+  },
+  create(context) {
+    var _context$options$;
+    const isIconBase = createIsFromImportSourceFor('@atlaskit/icon', '@atlaskit/icon/base');
+    const {
+      centralLocation = '',
+      failSilently = false
+    } = (_context$options$ = context.options[0]) !== null && _context$options$ !== void 0 ? _context$options$ : {};
+    const locationMessage = centralLocation ? ` or move the icon to '${centralLocation}'` : '';
+    return errorBoundary({
+      JSXElement(node) {
+        var _isIconBase$getImport;
+        if (!isIconBase(node) || !hasProp(node, 'glyph')) {
+          return;
+        }
+        const importSource = (_isIconBase$getImport = isIconBase.getImportSource(node)) !== null && _isIconBase$getImport !== void 0 ? _isIconBase$getImport : '';
+        context.report({
+          node: node.openingElement,
+          messageId: 'noCustomIcons',
+          data: {
+            importSource,
+            locationMessage
+          }
+        });
+      },
+      ImportDeclaration: isIconBase.importDeclarationHook
+    }, failSilently);
+  }
+});
+export default rule;

package/dist/es2019/rules/no-legacy-icons/checks.js

@@ -1,5 +1,5 @@
 import { isNodeOfType } from 'eslint-codemod-utils';
-import { canAutoMigrateNewIconBasedOnSize, canMigrateColor, createAutoMigrationError, createCantFindSuitableReplacementError, createCantMigrateColorError, createCantMigrateFunctionUnknownError, createCantMigrateIdentifierError, createCantMigrateReExportError, createCantMigrateSizeUnknown, createCantMigrateSpreadPropsError, createCantMigrateUnsafeProp, createGuidance, createHelpers, findUNSAFEProp, getIconKey, getMigrationMapObject, locToString } from './helpers';
+import { canAutoMigrateNewIconBasedOnSize, canMigrateColor, createAutoMigrationError, createCantFindSuitableReplacementError, createCantMigrateColorError, createCantMigrateFunctionUnknownError, createCantMigrateIdentifierError, createCantMigrateReExportError, createCantMigrateSizeUnknown, createCantMigrateSpreadPropsError, createCantMigrateUnsafeProp, createGuidance, createHelpers, findUNSAFEProp, getMigrationMapObject, locToString } from './helpers';
 import { isSize } from './migration-map-temp';
 export const createChecks = context => {
   //create global variables to be shared by the checks
@@ -100,15 +100,17 @@ export const createChecks = context => {
     if (node.source && isNodeOfType(node.source, 'Literal') && 'value' in node.source) {
       const moduleSource = node.source.value;
       if (typeof moduleSource === 'string' && ['@atlaskit/icon/glyph/', '@atlaskit/icon-object/glyph/'].find(val => moduleSource.startsWith(val)) && node.specifiers.length) {
-        createCantMigrateReExportError(node, moduleSource, node.specifiers[0].exported.name, errorsManual);
-        guidance[locToString(node)] = createGuidance(moduleSource);
+        for (const spec of node.specifiers) {
+          createCantMigrateReExportError(spec, moduleSource, spec.exported.name, errorsManual);
+          guidance[locToString(spec)] = createGuidance(moduleSource);
+        }
       }
     } else if (node.declaration && isNodeOfType(node.declaration, 'VariableDeclaration')) {
       // export const Icon = AddIcon;
       for (const decl of node.declaration.declarations) {
         if (isNodeOfType(decl, 'VariableDeclarator') && 'init' in decl && decl.init && isNodeOfType(decl.init, 'Identifier') && decl.init.name in legacyIconImports) {
           createCantMigrateReExportError(node, legacyIconImports[decl.init.name].packageName, decl.init.name, errorsManual);
-          guidance[locToString(node)] = createGuidance(createGuidance(legacyIconImports[decl.init.name].packageName));
+          guidance[locToString(node)] = createGuidance(legacyIconImports[decl.init.name].packageName);
         }
       }
     } else if (!node.source && node.specifiers && node.specifiers.length > 0) {
@@ -174,18 +176,17 @@ export const createChecks = context => {
         UNSAFE_propName = result.UNSAFE_propName;
       }
       if (newIcon && isInNewButton && isNewIconMigratable && UNSAFE_size !== 'large' && UNSAFE_size !== 'xlarge') {
-        const iconKey = getIconKey(legacyIconImports[node.name].packageName);
-        createAutoMigrationError(node, legacyIconImports[node.name].packageName, node.name, newIcon, iconKey, errorsAuto);
-        guidance[locToString(node)] = createGuidance(legacyIconImports[node.name].packageName, 'medium');
+        createAutoMigrationError(node, legacyIconImports[node.name].packageName, node.name, errorsAuto);
+        guidance[locToString(node)] = createGuidance(legacyIconImports[node.name].packageName, isInNewButton, 'medium');
       } else if ((!newIcon || !isNewIconMigratable) && !UNSAFE_size) {
         createCantFindSuitableReplacementError(node, legacyIconImports[node.name].packageName, node.name, errorsManual);
-        guidance[locToString(node)] = createGuidance(legacyIconImports[node.name].packageName);
+        guidance[locToString(node)] = createGuidance(legacyIconImports[node.name].packageName, isInNewButton);
       } else if ((UNSAFE_size === 'large' || UNSAFE_size === 'xlarge') && UNSAFE_propName) {
         createCantMigrateUnsafeProp(node, UNSAFE_propName, UNSAFE_size, legacyIconImports[node.name].packageName, node.name, errorsManual);
-        guidance[locToString(node)] = createGuidance(legacyIconImports[node.name].packageName, UNSAFE_size);
+        guidance[locToString(node)] = createGuidance(legacyIconImports[node.name].packageName, isInNewButton, UNSAFE_size);
       } else if (!isInNewButton) {
         createCantMigrateFunctionUnknownError(node, legacyIconImports[node.name].packageName, node.name, errorsManual);
-        guidance[locToString(node)] = createGuidance(legacyIconImports[node.name].packageName);
+        guidance[locToString(node)] = createGuidance(legacyIconImports[node.name].packageName, isInNewButton);
       }
     }
   };
@@ -272,7 +273,6 @@ export const createChecks = context => {
         createCantMigrateSizeUnknown(node, errorsManual, legacyIconImports[name].packageName, name);
         hasManualMigration = true;
       }
-      guidance[locToString(node)] = createGuidance(legacyIconImports[name].packageName, size ? size : undefined);
       // Check for unsafe size
       if ((UNSAFE_size === 'large' || UNSAFE_size === 'xlarge') && (UNSAFE_propName === 'UNSAFE_iconAfter_size' || UNSAFE_propName === 'UNSAFE_iconBefore_size' || UNSAFE_propName === 'UNSAFE_size')) {
         createCantMigrateUnsafeProp(node, UNSAFE_propName, UNSAFE_size, legacyIconImports[name].packageName, name, errorsManual);
@@ -290,14 +290,14 @@ export const createChecks = context => {
         hasManualMigration = true;
       }
       const migrationMapObject = getMigrationMapObject(legacyIconImports[name].packageName);
-      const iconKey = getIconKey(legacyIconImports[name].packageName);
       const newIcon = migrationMapObject === null || migrationMapObject === void 0 ? void 0 : migrationMapObject.newIcon;
       const isNewIconMigratable = canAutoMigrateNewIconBasedOnSize(migrationMapObject === null || migrationMapObject === void 0 ? void 0 : migrationMapObject.sizeGuidance[(_size = size) !== null && _size !== void 0 ? _size : 'medium']);
       if (!hasManualMigration && newIcon && isNewIconMigratable) {
-        createAutoMigrationError(node, legacyIconImports[name].packageName, name, newIcon, iconKey, errorsAuto);
+        createAutoMigrationError(node, legacyIconImports[name].packageName, name, errorsAuto);
       } else if ((!newIcon || !isNewIconMigratable) && size) {
-        createCantFindSuitableReplacementError(node, legacyIconImports[name].packageName, name, errorsManual);
+        createCantFindSuitableReplacementError(node, legacyIconImports[name].packageName, name, errorsManual, migrationMapObject ? true : false);
       }
+      guidance[locToString(node)] = createGuidance(legacyIconImports[name].packageName, insideNewButton, size && isSize(size) ? size : undefined);
     }
   };
 
@@ -324,28 +324,20 @@ export const createChecks = context => {
       for (const [key, errorList] of Object.entries(errorsManual)) {
         const node = 'node' in errorList.errors[0] ? errorList.errors[0].node : null;
         if (node) {
+          const guidanceMessage = key in guidance ? guidance[key] : '';
           context.report({
             node,
             messageId: 'noLegacyIconsManualMigration',
             data: {
               iconName: errorList.iconName,
               importSource: errorList.importSource,
-              quietModeGuidance: isQuietMode ? 'For more information see the below errors:' : ''
+              guidance: isQuietMode ? guidanceMessage : `${guidanceMessage}For more information see the below errors.\n`
             }
           });
           if (!isQuietMode) {
             for (const error of errorList.errors) {
               context.report(error);
             }
-            if (key in guidance) {
-              context.report({
-                node,
-                messageId: 'guidance',
-                data: {
-                  guidance: guidance[key]
-                }
-              });
-            }
           }
         }
       }
@@ -360,16 +352,11 @@ export const createChecks = context => {
         }
         const node = 'node' in error ? error.node : null;
         if (node) {
-          context.report(error);
-          if (key in guidance && !isQuietMode) {
-            context.report({
-              node,
-              messageId: 'guidance',
-              data: {
-                guidance: guidance[key]
-              }
-            });
+          const guidanceMessage = key in guidance ? guidance[key] : '';
+          if ('data' in error && error.data) {
+            error.data.guidance = guidanceMessage;
           }
+          context.report(error);
         }
       }
     }

package/dist/es2019/rules/no-legacy-icons/helpers.js

@@ -19,7 +19,7 @@ export const getMigrationMapObject = iconPackage => {
  * @param iconPackage The name of the legacy icon package
  * @returns The unique identifier for the icon (the part after "@atlaskit/icon/glyph")
  */
-export const getIconKey = iconPackage => {
+const getIconKey = iconPackage => {
   const key = iconPackage.replace(/^@atlaskit\/icon\/glyph\//, '');
   return key;
 };
@@ -34,36 +34,43 @@ export const canAutoMigrateNewIconBasedOnSize = guidance => {
 /**
  * Creates the written guidance for migrating a legacy icon to a new icon
  */
-export const createGuidance = (iconPackage, size) => {
+export const createGuidance = (iconPackage, insideNewButton = false, size) => {
   const migrationMapObject = getMigrationMapObject(iconPackage);
   if (migrationMapObject) {
     const newIcon = migrationMapObject.newIcon;
     if (!newIcon) {
       return 'No equivalent icon in new set. An option is to contribute a custom icon into icon-labs package instead.\n';
     }
+    const buttonGuidanceStr = "Please set 'spacing' property of the new icon to 'none', to ensure appropriate spacing inside `@atlaskit/button`.\n";
+    let guidance = '';
     if (size) {
-      let guidance = `Fix: Use ${newIcon.name} from @atlaskit/${newIcon.library}/${newIcon.type}/${newIcon.name} instead.`;
-      if (migrationMapObject.sizeGuidance[size] in outcomeDescriptionMap) {
-        guidance += ` Please: ${outcomeDescriptionMap[migrationMapObject.sizeGuidance[size]]}\n`;
+      if (migrationMapObject.sizeGuidance[size] && canAutoMigrateNewIconBasedOnSize(migrationMapObject.sizeGuidance[size])) {
+        guidance += `Fix: Use ${newIcon.name} from @atlaskit/${newIcon.library}/${newIcon.type}/${newIcon.name} instead.`;
       } else {
-        guidance += ' No migration advice given.\n';
+        guidance += `No equivalent icon for this size, ${size}, in new set.`;
       }
-      return guidance;
+      guidance += `${migrationMapObject.sizeGuidance[size] in outcomeDescriptionMap ? ` Please: ${outcomeDescriptionMap[migrationMapObject.sizeGuidance[size]]}` : ' No migration size advice given.'}\n`;
     } else {
-      let guidance = `Use ${newIcon.name} from @atlaskit/${newIcon.library}/${newIcon.type}/${newIcon.name} instead.\nMigration suggestions, depending on the legacy icon size:\n`;
+      guidance = `Use ${newIcon.name} from @atlaskit/${newIcon.library}/${newIcon.type}/${newIcon.name} instead.\nMigration suggestions, depending on the legacy icon size:\n`;
       for (const [size, value] of Object.entries(migrationMapObject.sizeGuidance)) {
         guidance += `\t- ${size}: `;
         if (!(value in outcomeDescriptionMap)) {
           guidance += 'No migration advice given.\n';
         } else {
-          guidance += `${outcomeDescriptionMap[value]}\n`;
+          guidance += `${outcomeDescriptionMap[value]}.\n`;
         }
-        guidance;
       }
-      return guidance;
     }
+    if (insideNewButton) {
+      guidance += buttonGuidanceStr;
+    } else if (size && size === 'medium') {
+      guidance += "Setting the spacing property to 'spacious' will maintain the icon's box dimensions - but consider setting spacing='none' as it allows for easier control of spacing by parent elements.\n";
+    } else if (size) {
+      guidance += "In the new icon, please use spacing='none'.\n";
+    }
+    return guidance;
   } else {
-    return 'Migration suggestions not found\n';
+    return `Migration suggestions not found for "${iconPackage}".\n`;
   }
 };
 
@@ -139,13 +146,14 @@ export const createCantMigrateUnsafeProp = (node, propName, value, packageName,
   };
   pushManualError(locToString(node), errors, myError, packageName, iconName);
 };
-export const createCantFindSuitableReplacementError = (node, importSource, iconName, errors) => {
+export const createCantFindSuitableReplacementError = (node, importSource, iconName, errors, sizeIssue) => {
   const myError = {
     node,
     messageId: 'cantFindSuitableReplacement',
     data: {
       importSource,
-      iconName
+      iconName,
+      sizeGuidance: sizeIssue ? ' at the current size' : ''
     }
   };
   pushManualError(locToString(node), errors, myError, importSource, iconName);
@@ -188,18 +196,13 @@ export const createCantMigrateSizeUnknown = (node, errors, importSource, iconNam
   };
   pushManualError(locToString(node), errors, myError, importSource, iconName);
 };
-export const createAutoMigrationError = (node, importSource, iconName, newIcon, oldIconName, errors) => {
-  const migrationKey = newIcon.name === oldIconName ? newIcon.name : `${newIcon.name}--${oldIconName}`;
-  const newMigrationIconPackage = `@atlaskit/${newIcon.library}/${newIcon.type}/migration/${migrationKey}`;
+export const createAutoMigrationError = (node, importSource, iconName, errors) => {
   const myError = {
     node,
     messageId: 'noLegacyIconsAutoMigration',
     data: {
       importSource,
-      iconName,
-      newIcon: newIcon.name,
-      //TODO: provide size guidance
-      newPackage: newMigrationIconPackage
+      iconName
     }
   };
   errors[locToString(node)] = myError;