@atlaskit/ads-mcp 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @atlaskit/ads-mcp
 
+## 0.11.0
+
+### Minor Changes
+
+- [`fb3c14e64741b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/fb3c14e64741b) -
+  Create 'ads-migration-guides' tool, to facilitate `@atlaskit/onboarding` -> `@atlaskit/spotlight`
+  migration, and any future migrations.
+
+### Patch Changes
+
+- Updated dependencies
+
+## 0.10.1
+
+### Patch Changes
+
+- [`a60a82196851a`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/a60a82196851a) -
+  Internal refactors to remove unused variables. No functional or public changes.
+- Updated dependencies
+
 ## 0.10.0
 
 ### Minor Changes

package/dist/cjs/helpers/analytics.js

@@ -51,7 +51,7 @@ if (!isAnalyticsOptedOut) {
       subproduct: 'ads-mcp',
       flushInterval: 5000
     });
-  } catch (error) {
+  } catch (_unused) {
     // Analytics client not available or failed to initialize
     // Log the error but continue without analytics
     console.error('Could not initialize analytics client. This is normal as it is only intended to measure authenticated Atlassians');
@@ -90,7 +90,7 @@ function sendOperationalEvent(_ref) {
         }, attributes)
       }
     });
-  } catch (error) {
+  } catch (_unused2) {
     // Analytics errors should not prevent normal operation
     // Silently fail to avoid disrupting the main functionality
     console.error('Error sending operational event to analytics');

package/dist/cjs/index.js

@@ -22,6 +22,7 @@ var _getAllTokens = require("./tools/get-all-tokens");
 var _getComponents = require("./tools/get-components");
 var _getIcons = require("./tools/get-icons");
 var _getTokens = require("./tools/get-tokens");
+var _migrationGuides = require("./tools/migration-guides");
 var _plan = require("./tools/plan");
 var _suggestA11yFixes = require("./tools/suggest-a11y-fixes");
 /* eslint-disable no-console, import/extensions */
@@ -61,7 +62,7 @@ var generateLogger = function generateLogger(level) {
   };
 };
 var getToolRegistry = exports.getToolRegistry = function getToolRegistry() {
-  var baseTools = (0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)({}, _analyzeA11y.listAnalyzeA11yTool.name, {
+  var baseTools = (0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)({}, _analyzeA11y.listAnalyzeA11yTool.name, {
     handler: _analyzeA11y.analyzeA11yTool,
     inputSchema: _analyzeA11y.analyzeA11yInputSchema,
     tool: _analyzeA11y.listAnalyzeA11yTool
@@ -85,6 +86,10 @@ var getToolRegistry = exports.getToolRegistry = function getToolRegistry() {
     handler: _suggestA11yFixes.suggestA11yFixesTool,
     inputSchema: _suggestA11yFixes.suggestA11yFixesInputSchema,
     tool: _suggestA11yFixes.listSuggestA11yFixesTool
+  }), _migrationGuides.listMigrationGuidesTool.name, {
+    handler: _migrationGuides.migrationGuidesTool,
+    inputSchema: _migrationGuides.migrationGuidesInputSchema,
+    tool: _migrationGuides.listMigrationGuidesTool
   });
 
   // Conditionally add token and icon tools based on feature flag

package/dist/cjs/tools/get-tokens/token-structured-content.codegen.js

@@ -9,7 +9,7 @@ exports.tokenStructuredContent = void 0;
  *
  * Structured content for tokens generated from token-metadata.
  *
- * @codegen <<SignedSource::41dd1fd7431557df57b792c2eb5e5f70>>
+ * @codegen <<SignedSource::71826c7e9b24620099bd0316f7a0a305>>
  * @codegenCommand yarn build structured-docs
  */
 
@@ -143,6 +143,11 @@ var tokenStructuredContent = exports.tokenStructuredContent = [{
   name: 'color.text.danger',
   description: 'Use for critical text, such as input field error messaging.',
   exampleValue: '#AE2E24'
+}, {
+  content: '# color.text.danger.bolder\n\nUse for text on top of danger semantic labels to ensure accessibility and desired visual appearance.\n\nExample Value: `#5D1F1A`\n',
+  name: 'color.text.danger.bolder',
+  description: 'Use for text on top of danger semantic labels to ensure accessibility and desired visual appearance.',
+  exampleValue: '#5D1F1A'
 }, {
   content: '# color.text.warning\n\nUse for text to emphasize caution, such as in moved lozenges.\n\nExample Value: `#9E4C00`\n',
   name: 'color.text.warning',
@@ -153,21 +158,41 @@ var tokenStructuredContent = exports.tokenStructuredContent = [{
   name: 'color.text.warning.inverse',
   description: 'Use for text when on bold warning backgrounds.',
   exampleValue: '#292A2E'
+}, {
+  content: '# color.text.warning.bolder\n\nUse for text on top of warning semantic labels to ensure accessibility and desired visual appearance.\n\nExample Value: `#693200`\n',
+  name: 'color.text.warning.bolder',
+  description: 'Use for text on top of warning semantic labels to ensure accessibility and desired visual appearance.',
+  exampleValue: '#693200'
 }, {
   content: '# color.text.success\n\nUse for text to communicate a favorable outcome, such as input field success messaging.\n\nExample Value: `#4C6B1F`\n',
   name: 'color.text.success',
   description: 'Use for text to communicate a favorable outcome, such as input field success messaging.',
   exampleValue: '#4C6B1F'
+}, {
+  content: '# color.text.success.bolder\n\nUse for text on top of success semantic labels to ensure accessibility and desired visual appearance.\n\nExample Value: `#37471F`\n',
+  name: 'color.text.success.bolder',
+  description: 'Use for text on top of success semantic labels to ensure accessibility and desired visual appearance.',
+  exampleValue: '#37471F'
 }, {
   content: '# color.text.discovery\n\nUse for text to emphasize change or something new, such as in new lozenges.\n\nExample Value: `#803FA5`\n',
   name: 'color.text.discovery',
   description: 'Use for text to emphasize change or something new, such as in new lozenges.',
   exampleValue: '#803FA5'
+}, {
+  content: '# color.text.discovery.bolder\n\nUse for text on top of discovery semantic labels to ensure accessibility and desired visual appearance.\n\nExample Value: `#48245D`\n',
+  name: 'color.text.discovery.bolder',
+  description: 'Use for text on top of discovery semantic labels to ensure accessibility and desired visual appearance.',
+  exampleValue: '#48245D'
 }, {
   content: '# color.text.information\n\nUse for informative text or to communicate something is in progress, such as in-progress lozenges.\n\nExample Value: `#1558BC`\n',
   name: 'color.text.information',
   description: 'Use for informative text or to communicate something is in progress, such as in-progress lozenges.',
   exampleValue: '#1558BC'
+}, {
+  content: '# color.text.information.bolder\n\nUse for text on top of information semantic labels to ensure accessibility and desired visual appearance.\n\nExample Value: `#123263`\n',
+  name: 'color.text.information.bolder',
+  description: 'Use for text on top of information semantic labels to ensure accessibility and desired visual appearance.',
+  exampleValue: '#123263'
 }, {
   content: '# color.text.subtlest\n\nUse for tertiary text, such as meta-data, breadcrumbs, input field placeholder and helper text.\n\nExample Value: `#6B6E76`\n',
   name: 'color.text.subtlest',
@@ -1198,6 +1223,21 @@ var tokenStructuredContent = exports.tokenStructuredContent = [{
   name: 'color.background.danger.pressed',
   description: 'Pressed state for color.background.danger',
   exampleValue: '#FFB8B2'
+}, {
+  content: '# color.background.danger.subtler\n\nUse for backgrounds of danger lozenges and badges to ensure accessibility and desired visual appearance.\n\nExample Value: `#FFD5D2`\n',
+  name: 'color.background.danger.subtler',
+  description: 'Use for backgrounds of danger lozenges and badges to ensure accessibility and desired visual appearance.',
+  exampleValue: '#FFD5D2'
+}, {
+  content: '# color.background.danger.subtler.hovered\n\nHovered state of color.background.danger.subtler\n\nExample Value: `#FFB8B2`\n',
+  name: 'color.background.danger.subtler.hovered',
+  description: 'Hovered state of color.background.danger.subtler',
+  exampleValue: '#FFB8B2'
+}, {
+  content: '# color.background.danger.subtler.pressed\n\nPressed state of color.background.danger.subtler\n\nExample Value: `#FD9891`\n',
+  name: 'color.background.danger.subtler.pressed',
+  description: 'Pressed state of color.background.danger.subtler',
+  exampleValue: '#FD9891'
 }, {
   content: '# color.background.danger.bold\n\nA vibrant background option for communicating critical information, such as in danger buttons and error banners.\n\nExample Value: `#C9372C`\n',
   name: 'color.background.danger.bold',
@@ -1228,6 +1268,21 @@ var tokenStructuredContent = exports.tokenStructuredContent = [{
   name: 'color.background.warning.pressed',
   description: 'Pressed state for color.background.warning',
   exampleValue: '#FBD779'
+}, {
+  content: '# color.background.warning.subtler\n\nUse for backgrounds of warning lozenges and badges to ensure accessibility and desired visual appearance.\n\nExample Value: `#FCE4A6`\n',
+  name: 'color.background.warning.subtler',
+  description: 'Use for backgrounds of warning lozenges and badges to ensure accessibility and desired visual appearance.',
+  exampleValue: '#FCE4A6'
+}, {
+  content: '# color.background.warning.subtler.hovered\n\nHovered state of color.background.warning.subtler\n\nExample Value: `#FBD779`\n',
+  name: 'color.background.warning.subtler.hovered',
+  description: 'Hovered state of color.background.warning.subtler',
+  exampleValue: '#FBD779'
+}, {
+  content: '# color.background.warning.subtler.pressed\n\nPressed state of color.background.warning.subtler\n\nExample Value: `#FBC828`\n',
+  name: 'color.background.warning.subtler.pressed',
+  description: 'Pressed state of color.background.warning.subtler',
+  exampleValue: '#FBC828'
 }, {
   content: '# color.background.warning.bold\n\nA vibrant background option for communicating caution, such as in warning buttons and warning banners.\n\nExample Value: `#FBC828`\n',
   name: 'color.background.warning.bold',
@@ -1258,6 +1313,21 @@ var tokenStructuredContent = exports.tokenStructuredContent = [{
   name: 'color.background.success.pressed',
   description: 'Pressed state for color.background.success',
   exampleValue: '#BDE97C'
+}, {
+  content: '# color.background.success.subtler\n\nUse for backgrounds of success lozenges and badges to ensure accessibility and desired visual appearance.\n\nExample Value: `#D3F1A7`\n',
+  name: 'color.background.success.subtler',
+  description: 'Use for backgrounds of success lozenges and badges to ensure accessibility and desired visual appearance.',
+  exampleValue: '#D3F1A7'
+}, {
+  content: '# color.background.success.subtler.hovered\n\nHovered state of color.background.success.subtler\n\nExample Value: `#BDE97C`\n',
+  name: 'color.background.success.subtler.hovered',
+  description: 'Hovered state of color.background.success.subtler',
+  exampleValue: '#BDE97C'
+}, {
+  content: '# color.background.success.subtler.pressed\n\nPressed state of color.background.success.subtler\n\nExample Value: `#B3DF72`\n',
+  name: 'color.background.success.subtler.pressed',
+  description: 'Pressed state of color.background.success.subtler',
+  exampleValue: '#B3DF72'
 }, {
   content: '# color.background.success.bold\n\nA vibrant background option for communicating a favorable outcome, such as in checked toggles.\n\nExample Value: `#5B7F24`\n',
   name: 'color.background.success.bold',
@@ -1288,6 +1358,21 @@ var tokenStructuredContent = exports.tokenStructuredContent = [{
   name: 'color.background.discovery.pressed',
   description: 'Pressed state for color.background.discovery',
   exampleValue: '#E3BDFA'
+}, {
+  content: '# color.background.discovery.subtler\n\nUse for backgrounds of discovery lozenges and badges to ensure accessibility and desired visual appearance.\n\nExample Value: `#EED7FC`\n',
+  name: 'color.background.discovery.subtler',
+  description: 'Use for backgrounds of discovery lozenges and badges to ensure accessibility and desired visual appearance.',
+  exampleValue: '#EED7FC'
+}, {
+  content: '# color.background.discovery.subtler.hovered\n\nHovered state of color.background.discovery.subtler\n\nExample Value: `#E3BDFA`\n',
+  name: 'color.background.discovery.subtler.hovered',
+  description: 'Hovered state of color.background.discovery.subtler',
+  exampleValue: '#E3BDFA'
+}, {
+  content: '# color.background.discovery.subtler.pressed\n\nPressed state of color.background.discovery.subtler\n\nExample Value: `#D8A0F7`\n',
+  name: 'color.background.discovery.subtler.pressed',
+  description: 'Pressed state of color.background.discovery.subtler',
+  exampleValue: '#D8A0F7'
 }, {
   content: '# color.background.discovery.bold\n\nA vibrant background option communicating change or something new, such as in onboarding spotlights.\n\nExample Value: `#964AC0`\n',
   name: 'color.background.discovery.bold',
@@ -1318,6 +1403,21 @@ var tokenStructuredContent = exports.tokenStructuredContent = [{
   name: 'color.background.information.pressed',
   description: 'Pressed state of color.background.information',
   exampleValue: '#ADCBFB'
+}, {
+  content: '# color.background.information.subtler\n\nUse for backgrounds of information lozenges and badges to ensure accessibility and desired visual appearance.\n\nExample Value: `#CFE1FD`\n',
+  name: 'color.background.information.subtler',
+  description: 'Use for backgrounds of information lozenges and badges to ensure accessibility and desired visual appearance.',
+  exampleValue: '#CFE1FD'
+}, {
+  content: '# color.background.information.subtler.hovered\n\nHovered state of color.background.information.subtler\n\nExample Value: `#ADCBFB`\n',
+  name: 'color.background.information.subtler.hovered',
+  description: 'Hovered state of color.background.information.subtler',
+  exampleValue: '#ADCBFB'
+}, {
+  content: '# color.background.information.subtler.pressed\n\nPressed state of color.background.information.subtler\n\nExample Value: `#8FB8F6`\n',
+  name: 'color.background.information.subtler.pressed',
+  description: 'Pressed state of color.background.information.subtler',
+  exampleValue: '#8FB8F6'
 }, {
   content: '# color.background.information.bold\n\nA vibrant background option for communicating information or something in-progress.\n\nExample Value: `#1868DB`\n',
   name: 'color.background.information.bold',

package/dist/cjs/tools/migration-guides/index.js

@@ -0,0 +1,78 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.migrationGuidesTool = exports.migrationGuidesInputSchema = exports.listMigrationGuidesTool = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _zod = require("zod");
+var _helpers = require("../../helpers");
+var _registry = require("./registry");
+// Build the enum dynamically from the registry
+var migrationIds = (0, _registry.getAvailableMigrationIds)();
+var migrationGuidesInputSchema = exports.migrationGuidesInputSchema = _zod.z.object({
+  migration: _zod.z.enum(migrationIds).describe("The specific migration to perform.\n")
+});
+var listMigrationGuidesTool = exports.listMigrationGuidesTool = {
+  name: 'ads_migration_guides',
+  description: "Provides migration guides for deprecated Atlassian Design System components. Returns before/after examples, best practices, and step-by-step migration instructions.\n\nAvailable migrations:\n".concat((0, _registry.getAvailableMigrationsDescription)()),
+  annotations: {
+    title: 'ADS Migration Guides',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  inputSchema: (0, _helpers.zodToJsonSchema)(migrationGuidesInputSchema)
+};
+var migrationGuidesTool = exports.migrationGuidesTool = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
+    var migration, guide;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          migration = params.migration;
+          guide = _registry.migrationRegistry[migration];
+          if (guide) {
+            _context.next = 4;
+            break;
+          }
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                error: "Unknown migration: ".concat(migration),
+                availableMigrations: (0, _registry.getAvailableMigrationIds)(),
+                suggestion: 'Please use one of the available migration IDs listed above.'
+              }, null, 2)
+            }]
+          });
+        case 4:
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                migration: guide.id,
+                title: guide.title,
+                description: guide.description,
+                fromPackage: guide.fromPackage,
+                toPackage: guide.toPackage,
+                examples: guide.examples,
+                bestPractices: guide.bestPractices,
+                additionalResources: guide.additionalResources,
+                nextSteps: ['Review the before/after examples to understand the migration pattern', 'Apply the migration pattern', 'Follow the best practices listed above', 'Test the migrated code thoroughly']
+              }, null, 2)
+            }]
+          });
+        case 5:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function migrationGuidesTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();

package/dist/cjs/tools/migration-guides/migrations/onboarding-to-spotlight.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.onboardingWithMotion = exports.onboardingSingleStep = exports.onboardingMultiStep = void 0;
+var additionalResources = "Visit https://hello.atlassian.net/wiki/spaces/DST/pages/6069774593 or https://atlassian.design/components/spotlight for more context";
+var onboardingSingleStep = exports.onboardingSingleStep = {
+  id: 'onboarding-single-step',
+  title: 'Single Step Spotlight Migration',
+  description: 'Migrate a single step spotlight from @atlaskit/onboarding to @atlaskit/spotlight',
+  fromPackage: '@atlaskit/onboarding',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Migrate single step spotlight',
+    description: 'Replace SpotlightManager, SpotlightTarget, SpotlightTransition, and Spotlight with the new compositional @atlaskit/spotlight components',
+    before: "import React, { useState } from 'react';\nimport Button from '@atlaskit/button/new';\nimport {\n  Spotlight,\n  SpotlightManager,\n  SpotlightTarget,\n  SpotlightTransition,\n} from '@atlaskit/onboarding';\n\nconst OnboardingSpotlight = () => {\n  const [isSpotlightActive, setIsSpotlightActive] = useState(false);\n  const start = () => setIsSpotlightActive(true);\n  const end = () => setIsSpotlightActive(false);\n\n  return (\n    <SpotlightManager>\n      <SpotlightTarget name=\"my-target\">\n        <Button>Target Element</Button>\n      </SpotlightTarget>\n      <div>\n        <Button appearance=\"primary\" onClick={start}>\n          Show spotlight\n        </Button>\n      </div>\n      <SpotlightTransition>\n        {isSpotlightActive && (\n          <Spotlight\n            actions={[\n              {\n                onClick: end,\n                text: 'Got it',\n              },\n            ]}\n            heading=\"Feature Heading\"\n            target=\"my-target\"\n            key=\"my-target\"\n          >\n            This is the spotlight body content describing the feature.\n          </Spotlight>\n        )}\n      </SpotlightTransition>\n    </SpotlightManager>\n  );\n};",
+    after: "import React, { useState } from 'react';\nimport Button from '@atlaskit/button/new';\nimport { Text } from '@atlaskit/primitives/compiled';\nimport {\n  PopoverContent,\n  PopoverProvider,\n  PopoverTarget,\n  SpotlightActions,\n  SpotlightBody,\n  SpotlightCard,\n  SpotlightControls,\n  SpotlightDismissControl,\n  SpotlightFooter,\n  SpotlightHeader,\n  SpotlightHeadline,\n  SpotlightPrimaryAction,\n} from '@atlaskit/spotlight';\n\nconst Spotlight = () => {\n  const [isVisible, setIsVisible] = useState(false);\n  const dismiss = () => setIsVisible(false);\n  const done = () => setIsVisible(false);\n\n  return (\n    <PopoverProvider>\n      <PopoverTarget>\n        <Button onClick={() => setIsVisible(true)}>Target Element</Button>\n      </PopoverTarget>\n      <PopoverContent dismiss={dismiss} placement=\"bottom-start\" isVisible={isVisible}>\n        <SpotlightCard>\n          <SpotlightHeader>\n            <SpotlightHeadline>Feature Heading</SpotlightHeadline>\n            <SpotlightControls>\n              <SpotlightDismissControl />\n            </SpotlightControls>\n          </SpotlightHeader>\n          <SpotlightBody>\n            <Text>This is the spotlight body content describing the feature.</Text>\n          </SpotlightBody>\n          <SpotlightFooter>\n            <SpotlightActions>\n              <SpotlightPrimaryAction onClick={done}>Got it</SpotlightPrimaryAction>\n            </SpotlightActions>\n          </SpotlightFooter>\n        </SpotlightCard>\n      </PopoverContent>\n    </PopoverProvider>\n  );\n};",
+    explanation: "Key changes when migrating a single step spotlight:\n1. Replace SpotlightManager with PopoverProvider - the new context provider\n2. Replace SpotlightTarget with PopoverTarget - wraps the element to highlight\n3. Replace SpotlightTransition and Spotlight with PopoverContent containing SpotlightCard - controls visibility and positioning\n4. The 'heading' prop becomes SpotlightHeadline inside SpotlightHeader\n5. The 'actions' array becomes SpotlightActions with SpotlightPrimaryAction (and optionally SpotlightSecondaryAction)\n6. The children content moves into SpotlightBody wrapped with Text component\n7. Add SpotlightDismissControl inside SpotlightControls for the close button\n8. The 'target' prop is no longer needed - PopoverTarget automatically handles this\n9. The 'dialogPlacement' prop becomes 'placement' on PopoverContent (e.g., 'bottom left' \u2192 'bottom-start')"
+  }],
+  bestPractices: ['Use PopoverProvider as the root wrapper for spotlight functionality', 'PopoverTarget should wrap exactly one child element that will be highlighted', 'Always include SpotlightDismissControl for accessibility - allows users to dismiss via close button', 'Use SpotlightPrimaryAction for the main call-to-action button', 'Wrap body text content in the Text component from @atlaskit/primitives/compiled', 'Map old dialogPlacement values: "bottom left" → "bottom-start", "bottom center" → "bottom", "bottom right" → "bottom-end"'],
+  additionalResources: additionalResources
+};
+var onboardingMultiStep = exports.onboardingMultiStep = {
+  id: 'onboarding-multi-step',
+  title: 'Multi Step Spotlight Tour Migration',
+  description: 'Migrate a multi-step spotlight tour from @atlaskit/onboarding to @atlaskit/spotlight',
+  fromPackage: '@atlaskit/onboarding',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Migrate multi step spotlight tour',
+    description: 'Replace the single SpotlightManager pattern with multiple PopoverProvider instances, one for each target in the tour',
+    before: "import React, { useState } from 'react';\nimport Button, { IconButton } from '@atlaskit/button/new';\nimport CommentAddIcon from '@atlaskit/icon/core/comment-add';\nimport CopyIcon from '@atlaskit/icon/core/copy';\nimport {\n  Spotlight,\n  SpotlightManager,\n  SpotlightTarget,\n  SpotlightTransition,\n} from '@atlaskit/onboarding';\n\nconst OnboardingTour = () => {\n  const [activeSpotlight, setActiveSpotlight] = useState<null | number>(null);\n  const start = () => setActiveSpotlight(0);\n  const next = () => setActiveSpotlight((activeSpotlight || 0) + 1);\n  const back = () => setActiveSpotlight((activeSpotlight || 1) - 1);\n  const end = () => setActiveSpotlight(null);\n\n  const renderActiveSpotlight = () => {\n    const spotlights = [\n      <Spotlight\n        actions={[\n          { onClick: () => next(), text: 'Next' },\n          { onClick: () => end(), text: 'Dismiss', appearance: 'subtle' },\n        ]}\n        heading=\"Add a comment\"\n        target=\"comment\"\n        key=\"comment\"\n      >\n        Quickly add a comment to the work item.\n      </Spotlight>,\n      <Spotlight\n        actions={[\n          { onClick: () => end(), text: 'Done' },\n          { onClick: () => back(), text: 'Back', appearance: 'subtle' },\n        ]}\n        heading=\"Copy code\"\n        target=\"copy\"\n        key=\"copy\"\n      >\n        Click to copy the example code to your clipboard.\n      </Spotlight>,\n    ];\n\n    if (activeSpotlight === null) {\n      return null;\n    }\n    return spotlights[activeSpotlight];\n  };\n\n  return (\n    <SpotlightManager>\n      <SpotlightTarget name=\"comment\">\n        <IconButton icon={CommentAddIcon} label=\"comment\" />\n      </SpotlightTarget>\n      <SpotlightTarget name=\"copy\">\n        <IconButton icon={CopyIcon} label=\"Copy\" />\n      </SpotlightTarget>\n      <Button appearance=\"primary\" onClick={start}>\n        Start tour\n      </Button>\n      <SpotlightTransition>{renderActiveSpotlight()}</SpotlightTransition>\n    </SpotlightManager>\n  );\n};",
+    after: "import React, { useState } from 'react';\nimport Button, { IconButton } from '@atlaskit/button/new';\nimport CommentAddIcon from '@atlaskit/icon/core/comment-add';\nimport CopyIcon from '@atlaskit/icon/core/copy';\nimport { Text } from '@atlaskit/primitives/compiled';\nimport {\n  PopoverContent,\n  PopoverProvider,\n  PopoverTarget,\n  SpotlightActions,\n  SpotlightBody,\n  SpotlightCard,\n  SpotlightControls,\n  SpotlightDismissControl,\n  SpotlightFooter,\n  SpotlightHeader,\n  SpotlightHeadline,\n  SpotlightPrimaryAction,\n  SpotlightSecondaryAction,\n  SpotlightStepCount,\n} from '@atlaskit/spotlight';\n\nconst SpotlightTour = () => {\n  const [currentStep, setCurrentStep] = useState<number>(0);\n\n  const dismiss = () => setCurrentStep(0);\n  const back = () => setCurrentStep(Math.max(currentStep - 1, 1));\n  const next = () => setCurrentStep(Math.min(currentStep + 1, 2));\n  const done = () => setCurrentStep(0);\n\n  return (\n    <>\n      <PopoverProvider>\n        <PopoverTarget>\n          <IconButton icon={CommentAddIcon} label=\"comment\" />\n        </PopoverTarget>\n        <PopoverContent dismiss={dismiss} placement=\"bottom-start\" isVisible={currentStep === 1}>\n          <SpotlightCard>\n            <SpotlightHeader>\n              <SpotlightHeadline>Add a comment</SpotlightHeadline>\n              <SpotlightControls>\n                <SpotlightDismissControl onClick={dismiss} />\n              </SpotlightControls>\n            </SpotlightHeader>\n            <SpotlightBody>\n              <Text>Quickly add a comment to the work item.</Text>\n            </SpotlightBody>\n            <SpotlightFooter>\n              <SpotlightStepCount>1 of 2</SpotlightStepCount>\n              <SpotlightActions>\n                <SpotlightPrimaryAction onClick={next}>Next</SpotlightPrimaryAction>\n              </SpotlightActions>\n            </SpotlightFooter>\n          </SpotlightCard>\n        </PopoverContent>\n      </PopoverProvider>\n\n      <PopoverProvider>\n        <PopoverTarget>\n          <IconButton icon={CopyIcon} label=\"Copy\" />\n        </PopoverTarget>\n        <PopoverContent dismiss={dismiss} placement=\"bottom-start\" isVisible={currentStep === 2}>\n          <SpotlightCard>\n            <SpotlightHeader>\n              <SpotlightHeadline>Copy code</SpotlightHeadline>\n              <SpotlightControls>\n                <SpotlightDismissControl onClick={dismiss} />\n              </SpotlightControls>\n            </SpotlightHeader>\n            <SpotlightBody>\n              <Text>Click to copy the example code to your clipboard.</Text>\n            </SpotlightBody>\n            <SpotlightFooter>\n              <SpotlightStepCount>2 of 2</SpotlightStepCount>\n              <SpotlightActions>\n                <SpotlightSecondaryAction onClick={back}>Back</SpotlightSecondaryAction>\n                <SpotlightPrimaryAction onClick={done}>Done</SpotlightPrimaryAction>\n              </SpotlightActions>\n            </SpotlightFooter>\n          </SpotlightCard>\n        </PopoverContent>\n      </PopoverProvider>\n\n      <Button appearance=\"primary\" onClick={() => setCurrentStep(1)}>\n        Start tour\n      </Button>\n    </>\n  );\n};",
+    explanation: "Key changes when migrating a multi-step spotlight tour:\n1. Replace the single SpotlightManager with multiple PopoverProvider instances - one for each target element\n2. Each target gets its own PopoverProvider > PopoverTarget > PopoverContent structure\n3. The spotlight array pattern is replaced with individual SpotlightCard components per target\n4. Use a single currentStep state (starting at 0 for hidden, 1+ for active steps) instead of null/index\n5. Control visibility with isVisible={currentStep === n} on each PopoverContent\n6. Add SpotlightStepCount component in SpotlightFooter to show progress (e.g., \"1 of 3\")\n7. Use SpotlightSecondaryAction for \"Back\" buttons instead of appearance: 'subtle' in the actions array\n8. Use SpotlightPrimaryAction for \"Next\" and \"Done\" buttons\n9. The renderActiveSpotlight pattern is no longer needed - visibility is controlled declaratively\n10. Navigation functions use Math.max/Math.min to bound the step range safely"
+  }],
+  bestPractices: ['Each target element in a tour needs its own PopoverProvider wrapper', 'Use a numeric currentStep state where 0 = hidden, 1+ = active step number', 'Always include SpotlightStepCount in multi-step tours for user orientation', 'First step should only have "Next" action, middle steps have "Back" and "Next", last step has "Back" and "Done"', 'Use SpotlightSecondaryAction for back/dismiss actions and SpotlightPrimaryAction for next/done', 'Include SpotlightDismissControl with onClick={dismiss} so users can exit the tour at any point', 'Bound navigation functions with Math.max/Math.min to prevent invalid step values', 'Preference duplicating Spotlight code instead of trying to have a single `@atlaskit/spotlight` instance that conditionally renders content based on step.'],
+  additionalResources: additionalResources
+};
+var onboardingWithMotion = exports.onboardingWithMotion = {
+  id: 'onboarding-with-motion',
+  title: 'Single Step Spotlight with Motion Migration',
+  description: 'Migrate a single step spotlight with entrance animation from @atlaskit/onboarding to @atlaskit/spotlight using @atlaskit/motion',
+  fromPackage: '@atlaskit/onboarding',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Migrate spotlight with transition animation',
+    description: 'Replace SpotlightTransition with FadeIn from @atlaskit/motion wrapped around the SpotlightCard',
+    before: "import React, { useState } from 'react';\nimport Button from '@atlaskit/button/new';\nimport {\n  Spotlight,\n  SpotlightManager,\n  SpotlightTarget,\n  SpotlightTransition,\n} from '@atlaskit/onboarding';\n\nconst OnboardingSpotlightWithTransition = () => {\n  const [isSpotlightActive, setIsSpotlightActive] = useState(false);\n  const start = () => setIsSpotlightActive(true);\n  const end = () => setIsSpotlightActive(false);\n\n  return (\n    <SpotlightManager>\n      <SpotlightTarget name=\"my-target\">\n        <Button>Target Element</Button>\n      </SpotlightTarget>\n      <div>\n        <Button appearance=\"primary\" onClick={start}>\n          Show spotlight\n        </Button>\n      </div>\n      <SpotlightTransition>\n        {isSpotlightActive && (\n          <Spotlight\n            actions={[\n              {\n                onClick: end,\n                text: 'Got it',\n              },\n            ]}\n            heading=\"Feature Heading\"\n            target=\"my-target\"\n            key=\"my-target\"\n          >\n            This is the spotlight body content describing the feature.\n          </Spotlight>\n        )}\n      </SpotlightTransition>\n    </SpotlightManager>\n  );\n};",
+    after: "import React, { useState } from 'react';\nimport Button from '@atlaskit/button/new';\nimport { FadeIn } from '@atlaskit/motion';\nimport { Text } from '@atlaskit/primitives/compiled';\nimport {\n  PopoverContent,\n  PopoverProvider,\n  PopoverTarget,\n  SpotlightActions,\n  SpotlightBody,\n  SpotlightCard,\n  SpotlightControls,\n  SpotlightDismissControl,\n  SpotlightFooter,\n  SpotlightHeader,\n  SpotlightHeadline,\n  SpotlightPrimaryAction,\n} from '@atlaskit/spotlight';\n\nconst SpotlightWithMotion = () => {\n  const [isVisible, setIsVisible] = useState(false);\n  const dismiss = () => setIsVisible(false);\n  const done = () => setIsVisible(false);\n\n  return (\n    <PopoverProvider>\n      <PopoverTarget>\n        <Button onClick={() => setIsVisible(true)}>Target Element</Button>\n      </PopoverTarget>\n      <PopoverContent done={done} dismiss={dismiss} placement=\"bottom-start\" isVisible={isVisible}>\n        <FadeIn entranceDirection=\"left\">\n          {(props) => (\n            <div {...props}>\n              <SpotlightCard>\n                <SpotlightHeader>\n                  <SpotlightHeadline>Feature Heading</SpotlightHeadline>\n                  <SpotlightControls>\n                    <SpotlightDismissControl />\n                  </SpotlightControls>\n                </SpotlightHeader>\n                <SpotlightBody>\n                  <Text>This is the spotlight body content describing the feature.</Text>\n                </SpotlightBody>\n                <SpotlightFooter>\n                  <SpotlightActions>\n                    <SpotlightPrimaryAction onClick={done}>Got it</SpotlightPrimaryAction>\n                  </SpotlightActions>\n                </SpotlightFooter>\n              </SpotlightCard>\n            </div>\n          )}\n        </FadeIn>\n      </PopoverContent>\n    </PopoverProvider>\n  );\n};",
+    explanation: "Key changes when migrating a spotlight with transition animation:\n1. Replace SpotlightTransition with FadeIn from @atlaskit/motion\n2. Import FadeIn from '@atlaskit/motion' instead of SpotlightTransition from '@atlaskit/onboarding'\n3. FadeIn uses a render props pattern - wrap content in {(props) => <div {...props}>...</div>}\n4. The entranceDirection prop controls animation direction: 'left', 'right', 'top', or 'bottom'\n5. SpotlightCard must be wrapped in a div that receives the animation props\n6. PopoverContent now accepts a 'done' prop in addition to 'dismiss' for completed actions\n7. All other migration changes from single step spotlight apply (PopoverProvider, compositional components, etc.)"
+  }],
+  bestPractices: ['Use FadeIn from @atlaskit/motion to add entrance animations to spotlights', 'Choose entranceDirection based on spotlight placement (e.g., "left" for right-placed spotlights)', 'Always wrap SpotlightCard in a div that receives the animation props from FadeIn', 'FadeIn uses render props pattern: {(props) => <div {...props}>content</div>}', 'Pass both done and dismiss props to PopoverContent when using motion', 'Motion is optional - only add if the original onboarding spotlight used SpotlightTransition for entrance effects'],
+  additionalResources: additionalResources
+};

package/dist/cjs/tools/migration-guides/registry.js

@@ -0,0 +1,36 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.migrationRegistry = exports.getAvailableMigrationsDescription = exports.getAvailableMigrationIds = void 0;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _onboardingToSpotlight = require("./migrations/onboarding-to-spotlight");
+/**
+ * Migration registry - central place to register all available migrations
+ *
+ * To add a new migration:
+ * 1. Create a new file in ./migrations/ with your MigrationGuide(s)
+ * 2. Import and add to the registry below
+ * 3. The tool will automatically include it in the available options
+ */
+
+var migrationRegistry = exports.migrationRegistry = (0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)({}, _onboardingToSpotlight.onboardingSingleStep.id, _onboardingToSpotlight.onboardingSingleStep), _onboardingToSpotlight.onboardingMultiStep.id, _onboardingToSpotlight.onboardingMultiStep), _onboardingToSpotlight.onboardingWithMotion.id, _onboardingToSpotlight.onboardingWithMotion);
+
+/**
+ * Get all available migration IDs for use in the tool schema
+ */
+var getAvailableMigrationIds = exports.getAvailableMigrationIds = function getAvailableMigrationIds() {
+  return Object.keys(migrationRegistry);
+};
+
+/**
+ * Get a formatted list of available migrations with descriptions
+ * Useful for tool descriptions and help text
+ */
+var getAvailableMigrationsDescription = exports.getAvailableMigrationsDescription = function getAvailableMigrationsDescription() {
+  return Object.values(migrationRegistry).map(function (m) {
+    return "- \"".concat(m.id, "\": ").concat(m.description);
+  }).join('\n');
+};

package/dist/cjs/tools/migration-guides/types.js

@@ -0,0 +1 @@
+"use strict";

package/dist/es2019/helpers/analytics.js

@@ -41,7 +41,7 @@ if (!isAnalyticsOptedOut) {
       subproduct: 'ads-mcp',
       flushInterval: 5000
     });
-  } catch (error) {
+  } catch {
     // Analytics client not available or failed to initialize
     // Log the error but continue without analytics
     console.error('Could not initialize analytics client. This is normal as it is only intended to measure authenticated Atlassians');
@@ -80,7 +80,7 @@ export function sendOperationalEvent({
         }
       }
     });
-  } catch (error) {
+  } catch {
     // Analytics errors should not prevent normal operation
     // Silently fail to avoid disrupting the main functionality
     console.error('Error sending operational event to analytics');

package/dist/es2019/index.js

@@ -13,6 +13,7 @@ import { getAllTokensTool, listGetAllTokensTool } from './tools/get-all-tokens';
 import { getComponentsTool, listGetComponentsTool } from './tools/get-components';
 import { getIconsInputSchema, getIconsTool, listGetIconsTool } from './tools/get-icons';
 import { getTokensInputSchema, getTokensTool, listGetTokensTool } from './tools/get-tokens';
+import { listMigrationGuidesTool, migrationGuidesInputSchema, migrationGuidesTool } from './tools/migration-guides';
 import { listPlanTool, planInputSchema, planTool } from './tools/plan';
 import { listSuggestA11yFixesTool, suggestA11yFixesInputSchema, suggestA11yFixesTool } from './tools/suggest-a11y-fixes';
 
@@ -92,6 +93,11 @@ export const getToolRegistry = () => {
       handler: suggestA11yFixesTool,
       inputSchema: suggestA11yFixesInputSchema,
       tool: listSuggestA11yFixesTool
+    },
+    [listMigrationGuidesTool.name]: {
+      handler: migrationGuidesTool,
+      inputSchema: migrationGuidesInputSchema,
+      tool: listMigrationGuidesTool
     }
   };
 

package/dist/es2019/tools/analyze-a11y/index.js

@@ -235,7 +235,7 @@ export const analyzeA11yTool = async params => {
         }, null, 2)
       }]
     };
-  } catch (error) {
+  } catch {
     // Fallback to pattern-based analysis if axe-core fails
     // console.warn('Axe-core analysis failed, falling back to pattern analysis:', error);