@atlaskit/ads-mcp 0.10.0 → 0.11.0

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

@@ -3,7 +3,7 @@
  *
  * Structured content for tokens generated from token-metadata.
  *
- * @codegen <<SignedSource::41dd1fd7431557df57b792c2eb5e5f70>>
+ * @codegen <<SignedSource::71826c7e9b24620099bd0316f7a0a305>>
  * @codegenCommand yarn build structured-docs
  */
 
@@ -137,6 +137,11 @@ export const 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',
@@ -147,21 +152,41 @@ export const 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',
@@ -1192,6 +1217,21 @@ export const 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',
@@ -1222,6 +1262,21 @@ export const 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',
@@ -1252,6 +1307,21 @@ export const 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',
@@ -1282,6 +1352,21 @@ export const 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',
@@ -1312,6 +1397,21 @@ export const 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/es2019/tools/migration-guides/index.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from '../../helpers';
+import { getAvailableMigrationIds, getAvailableMigrationsDescription, migrationRegistry } from './registry';
+
+// Build the enum dynamically from the registry
+const migrationIds = getAvailableMigrationIds();
+export const migrationGuidesInputSchema = z.object({
+  migration: z.enum(migrationIds).describe(`The specific migration to perform.\n`)
+});
+export const 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.
+
+Available migrations:\n${getAvailableMigrationsDescription()}`,
+  annotations: {
+    title: 'ADS Migration Guides',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  inputSchema: zodToJsonSchema(migrationGuidesInputSchema)
+};
+export const migrationGuidesTool = async params => {
+  const {
+    migration
+  } = params;
+  const guide = migrationRegistry[migration];
+  if (!guide) {
+    // This shouldn't happen if the schema validation works, but handle gracefully
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: `Unknown migration: ${migration}`,
+          availableMigrations: getAvailableMigrationIds(),
+          suggestion: 'Please use one of the available migration IDs listed above.'
+        }, null, 2)
+      }]
+    };
+  }
+  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)
+    }]
+  };
+};

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

@@ -0,0 +1,416 @@
+const additionalResources = "Visit https://hello.atlassian.net/wiki/spaces/DST/pages/6069774593 or https://atlassian.design/components/spotlight for more context";
+export const 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';
+import Button from '@atlaskit/button/new';
+import {
+  Spotlight,
+  SpotlightManager,
+  SpotlightTarget,
+  SpotlightTransition,
+} from '@atlaskit/onboarding';
+
+const OnboardingSpotlight = () => {
+  const [isSpotlightActive, setIsSpotlightActive] = useState(false);
+  const start = () => setIsSpotlightActive(true);
+  const end = () => setIsSpotlightActive(false);
+
+  return (
+    <SpotlightManager>
+      <SpotlightTarget name="my-target">
+        <Button>Target Element</Button>
+      </SpotlightTarget>
+      <div>
+        <Button appearance="primary" onClick={start}>
+          Show spotlight
+        </Button>
+      </div>
+      <SpotlightTransition>
+        {isSpotlightActive && (
+          <Spotlight
+            actions={[
+              {
+                onClick: end,
+                text: 'Got it',
+              },
+            ]}
+            heading="Feature Heading"
+            target="my-target"
+            key="my-target"
+          >
+            This is the spotlight body content describing the feature.
+          </Spotlight>
+        )}
+      </SpotlightTransition>
+    </SpotlightManager>
+  );
+};`,
+    after: `import React, { useState } from 'react';
+import Button from '@atlaskit/button/new';
+import { Text } from '@atlaskit/primitives/compiled';
+import {
+  PopoverContent,
+  PopoverProvider,
+  PopoverTarget,
+  SpotlightActions,
+  SpotlightBody,
+  SpotlightCard,
+  SpotlightControls,
+  SpotlightDismissControl,
+  SpotlightFooter,
+  SpotlightHeader,
+  SpotlightHeadline,
+  SpotlightPrimaryAction,
+} from '@atlaskit/spotlight';
+
+const Spotlight = () => {
+  const [isVisible, setIsVisible] = useState(false);
+  const dismiss = () => setIsVisible(false);
+  const done = () => setIsVisible(false);
+
+  return (
+    <PopoverProvider>
+      <PopoverTarget>
+        <Button onClick={() => setIsVisible(true)}>Target Element</Button>
+      </PopoverTarget>
+      <PopoverContent dismiss={dismiss} placement="bottom-start" isVisible={isVisible}>
+        <SpotlightCard>
+          <SpotlightHeader>
+            <SpotlightHeadline>Feature Heading</SpotlightHeadline>
+            <SpotlightControls>
+              <SpotlightDismissControl />
+            </SpotlightControls>
+          </SpotlightHeader>
+          <SpotlightBody>
+            <Text>This is the spotlight body content describing the feature.</Text>
+          </SpotlightBody>
+          <SpotlightFooter>
+            <SpotlightActions>
+              <SpotlightPrimaryAction onClick={done}>Got it</SpotlightPrimaryAction>
+            </SpotlightActions>
+          </SpotlightFooter>
+        </SpotlightCard>
+      </PopoverContent>
+    </PopoverProvider>
+  );
+};`,
+    explanation: `Key changes when migrating a single step spotlight:
+1. Replace SpotlightManager with PopoverProvider - the new context provider
+2. Replace SpotlightTarget with PopoverTarget - wraps the element to highlight
+3. Replace SpotlightTransition and Spotlight with PopoverContent containing SpotlightCard - controls visibility and positioning
+4. The 'heading' prop becomes SpotlightHeadline inside SpotlightHeader
+5. The 'actions' array becomes SpotlightActions with SpotlightPrimaryAction (and optionally SpotlightSecondaryAction)
+6. The children content moves into SpotlightBody wrapped with Text component
+7. Add SpotlightDismissControl inside SpotlightControls for the close button
+8. The 'target' prop is no longer needed - PopoverTarget automatically handles this
+9. The 'dialogPlacement' prop becomes 'placement' on PopoverContent (e.g., 'bottom left' → '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
+};
+export const 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';
+import Button, { IconButton } from '@atlaskit/button/new';
+import CommentAddIcon from '@atlaskit/icon/core/comment-add';
+import CopyIcon from '@atlaskit/icon/core/copy';
+import {
+  Spotlight,
+  SpotlightManager,
+  SpotlightTarget,
+  SpotlightTransition,
+} from '@atlaskit/onboarding';
+
+const OnboardingTour = () => {
+  const [activeSpotlight, setActiveSpotlight] = useState<null | number>(null);
+  const start = () => setActiveSpotlight(0);
+  const next = () => setActiveSpotlight((activeSpotlight || 0) + 1);
+  const back = () => setActiveSpotlight((activeSpotlight || 1) - 1);
+  const end = () => setActiveSpotlight(null);
+
+  const renderActiveSpotlight = () => {
+    const spotlights = [
+      <Spotlight
+        actions={[
+          { onClick: () => next(), text: 'Next' },
+          { onClick: () => end(), text: 'Dismiss', appearance: 'subtle' },
+        ]}
+        heading="Add a comment"
+        target="comment"
+        key="comment"
+      >
+        Quickly add a comment to the work item.
+      </Spotlight>,
+      <Spotlight
+        actions={[
+          { onClick: () => end(), text: 'Done' },
+          { onClick: () => back(), text: 'Back', appearance: 'subtle' },
+        ]}
+        heading="Copy code"
+        target="copy"
+        key="copy"
+      >
+        Click to copy the example code to your clipboard.
+      </Spotlight>,
+    ];
+
+    if (activeSpotlight === null) {
+      return null;
+    }
+    return spotlights[activeSpotlight];
+  };
+
+  return (
+    <SpotlightManager>
+      <SpotlightTarget name="comment">
+        <IconButton icon={CommentAddIcon} label="comment" />
+      </SpotlightTarget>
+      <SpotlightTarget name="copy">
+        <IconButton icon={CopyIcon} label="Copy" />
+      </SpotlightTarget>
+      <Button appearance="primary" onClick={start}>
+        Start tour
+      </Button>
+      <SpotlightTransition>{renderActiveSpotlight()}</SpotlightTransition>
+    </SpotlightManager>
+  );
+};`,
+    after: `import React, { useState } from 'react';
+import Button, { IconButton } from '@atlaskit/button/new';
+import CommentAddIcon from '@atlaskit/icon/core/comment-add';
+import CopyIcon from '@atlaskit/icon/core/copy';
+import { Text } from '@atlaskit/primitives/compiled';
+import {
+  PopoverContent,
+  PopoverProvider,
+  PopoverTarget,
+  SpotlightActions,
+  SpotlightBody,
+  SpotlightCard,
+  SpotlightControls,
+  SpotlightDismissControl,
+  SpotlightFooter,
+  SpotlightHeader,
+  SpotlightHeadline,
+  SpotlightPrimaryAction,
+  SpotlightSecondaryAction,
+  SpotlightStepCount,
+} from '@atlaskit/spotlight';
+
+const SpotlightTour = () => {
+  const [currentStep, setCurrentStep] = useState<number>(0);
+
+  const dismiss = () => setCurrentStep(0);
+  const back = () => setCurrentStep(Math.max(currentStep - 1, 1));
+  const next = () => setCurrentStep(Math.min(currentStep + 1, 2));
+  const done = () => setCurrentStep(0);
+
+  return (
+    <>
+      <PopoverProvider>
+        <PopoverTarget>
+          <IconButton icon={CommentAddIcon} label="comment" />
+        </PopoverTarget>
+        <PopoverContent dismiss={dismiss} placement="bottom-start" isVisible={currentStep === 1}>
+          <SpotlightCard>
+            <SpotlightHeader>
+              <SpotlightHeadline>Add a comment</SpotlightHeadline>
+              <SpotlightControls>
+                <SpotlightDismissControl onClick={dismiss} />
+              </SpotlightControls>
+            </SpotlightHeader>
+            <SpotlightBody>
+              <Text>Quickly add a comment to the work item.</Text>
+            </SpotlightBody>
+            <SpotlightFooter>
+              <SpotlightStepCount>1 of 2</SpotlightStepCount>
+              <SpotlightActions>
+                <SpotlightPrimaryAction onClick={next}>Next</SpotlightPrimaryAction>
+              </SpotlightActions>
+            </SpotlightFooter>
+          </SpotlightCard>
+        </PopoverContent>
+      </PopoverProvider>
+
+      <PopoverProvider>
+        <PopoverTarget>
+          <IconButton icon={CopyIcon} label="Copy" />
+        </PopoverTarget>
+        <PopoverContent dismiss={dismiss} placement="bottom-start" isVisible={currentStep === 2}>
+          <SpotlightCard>
+            <SpotlightHeader>
+              <SpotlightHeadline>Copy code</SpotlightHeadline>
+              <SpotlightControls>
+                <SpotlightDismissControl onClick={dismiss} />
+              </SpotlightControls>
+            </SpotlightHeader>
+            <SpotlightBody>
+              <Text>Click to copy the example code to your clipboard.</Text>
+            </SpotlightBody>
+            <SpotlightFooter>
+              <SpotlightStepCount>2 of 2</SpotlightStepCount>
+              <SpotlightActions>
+                <SpotlightSecondaryAction onClick={back}>Back</SpotlightSecondaryAction>
+                <SpotlightPrimaryAction onClick={done}>Done</SpotlightPrimaryAction>
+              </SpotlightActions>
+            </SpotlightFooter>
+          </SpotlightCard>
+        </PopoverContent>
+      </PopoverProvider>
+
+      <Button appearance="primary" onClick={() => setCurrentStep(1)}>
+        Start tour
+      </Button>
+    </>
+  );
+};`,
+    explanation: `Key changes when migrating a multi-step spotlight tour:
+1. Replace the single SpotlightManager with multiple PopoverProvider instances - one for each target element
+2. Each target gets its own PopoverProvider > PopoverTarget > PopoverContent structure
+3. The spotlight array pattern is replaced with individual SpotlightCard components per target
+4. Use a single currentStep state (starting at 0 for hidden, 1+ for active steps) instead of null/index
+5. Control visibility with isVisible={currentStep === n} on each PopoverContent
+6. Add SpotlightStepCount component in SpotlightFooter to show progress (e.g., "1 of 3")
+7. Use SpotlightSecondaryAction for "Back" buttons instead of appearance: 'subtle' in the actions array
+8. Use SpotlightPrimaryAction for "Next" and "Done" buttons
+9. The renderActiveSpotlight pattern is no longer needed - visibility is controlled declaratively
+10. 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
+};
+export const 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';
+import Button from '@atlaskit/button/new';
+import {
+  Spotlight,
+  SpotlightManager,
+  SpotlightTarget,
+  SpotlightTransition,
+} from '@atlaskit/onboarding';
+
+const OnboardingSpotlightWithTransition = () => {
+  const [isSpotlightActive, setIsSpotlightActive] = useState(false);
+  const start = () => setIsSpotlightActive(true);
+  const end = () => setIsSpotlightActive(false);
+
+  return (
+    <SpotlightManager>
+      <SpotlightTarget name="my-target">
+        <Button>Target Element</Button>
+      </SpotlightTarget>
+      <div>
+        <Button appearance="primary" onClick={start}>
+          Show spotlight
+        </Button>
+      </div>
+      <SpotlightTransition>
+        {isSpotlightActive && (
+          <Spotlight
+            actions={[
+              {
+                onClick: end,
+                text: 'Got it',
+              },
+            ]}
+            heading="Feature Heading"
+            target="my-target"
+            key="my-target"
+          >
+            This is the spotlight body content describing the feature.
+          </Spotlight>
+        )}
+      </SpotlightTransition>
+    </SpotlightManager>
+  );
+};`,
+    after: `import React, { useState } from 'react';
+import Button from '@atlaskit/button/new';
+import { FadeIn } from '@atlaskit/motion';
+import { Text } from '@atlaskit/primitives/compiled';
+import {
+  PopoverContent,
+  PopoverProvider,
+  PopoverTarget,
+  SpotlightActions,
+  SpotlightBody,
+  SpotlightCard,
+  SpotlightControls,
+  SpotlightDismissControl,
+  SpotlightFooter,
+  SpotlightHeader,
+  SpotlightHeadline,
+  SpotlightPrimaryAction,
+} from '@atlaskit/spotlight';
+
+const SpotlightWithMotion = () => {
+  const [isVisible, setIsVisible] = useState(false);
+  const dismiss = () => setIsVisible(false);
+  const done = () => setIsVisible(false);
+
+  return (
+    <PopoverProvider>
+      <PopoverTarget>
+        <Button onClick={() => setIsVisible(true)}>Target Element</Button>
+      </PopoverTarget>
+      <PopoverContent done={done} dismiss={dismiss} placement="bottom-start" isVisible={isVisible}>
+        <FadeIn entranceDirection="left">
+          {(props) => (
+            <div {...props}>
+              <SpotlightCard>
+                <SpotlightHeader>
+                  <SpotlightHeadline>Feature Heading</SpotlightHeadline>
+                  <SpotlightControls>
+                    <SpotlightDismissControl />
+                  </SpotlightControls>
+                </SpotlightHeader>
+                <SpotlightBody>
+                  <Text>This is the spotlight body content describing the feature.</Text>
+                </SpotlightBody>
+                <SpotlightFooter>
+                  <SpotlightActions>
+                    <SpotlightPrimaryAction onClick={done}>Got it</SpotlightPrimaryAction>
+                  </SpotlightActions>
+                </SpotlightFooter>
+              </SpotlightCard>
+            </div>
+          )}
+        </FadeIn>
+      </PopoverContent>
+    </PopoverProvider>
+  );
+};`,
+    explanation: `Key changes when migrating a spotlight with transition animation:
+1. Replace SpotlightTransition with FadeIn from @atlaskit/motion
+2. Import FadeIn from '@atlaskit/motion' instead of SpotlightTransition from '@atlaskit/onboarding'
+3. FadeIn uses a render props pattern - wrap content in {(props) => <div {...props}>...</div>}
+4. The entranceDirection prop controls animation direction: 'left', 'right', 'top', or 'bottom'
+5. SpotlightCard must be wrapped in a div that receives the animation props
+6. PopoverContent now accepts a 'done' prop in addition to 'dismiss' for completed actions
+7. 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
+};

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

@@ -0,0 +1,30 @@
+/**
+ * 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
+ */
+
+import { onboardingMultiStep, onboardingSingleStep, onboardingWithMotion } from './migrations/onboarding-to-spotlight';
+export const migrationRegistry = {
+  [onboardingSingleStep.id]: onboardingSingleStep,
+  [onboardingMultiStep.id]: onboardingMultiStep,
+  [onboardingWithMotion.id]: onboardingWithMotion
+};
+
+/**
+ * Get all available migration IDs for use in the tool schema
+ */
+export const getAvailableMigrationIds = () => {
+  return Object.keys(migrationRegistry);
+};
+
+/**
+ * Get a formatted list of available migrations with descriptions
+ * Useful for tool descriptions and help text
+ */
+export const getAvailableMigrationsDescription = () => {
+  return Object.values(migrationRegistry).map(m => `- "${m.id}": ${m.description}`).join('\n');
+};