@atlaskit/ads-mcp 0.20.3 → 0.21.0

package/dist/es2019/tools/get-atlaskit-components/get-atlaskit-components-tool.js

@@ -0,0 +1,14 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+import { atlaskitComponents } from './atlaskit-components.codegen';
+export const getAtlaskitComponentsTool = async () => {
+  const components = atlaskitComponents.map(component => ({
+    name: component.name,
+    package: component.package
+  }));
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(components, null, 2)
+    }]
+  };
+};

package/dist/es2019/tools/get-atlaskit-components/list-get-atlaskit-components-tool.js

@@ -0,0 +1,21 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+import { z } from 'zod';
+import { zodToJsonSchema } from '../../helpers';
+export const listGetAtlaskitComponentsTool = {
+  name: 'atlaskit_get_components',
+  description: `Returns the names and packages of all atlaskit components excluding components covered by the Atlassian Design System.
+
+WHEN TO USE:
+Use this when you want to see what components are available without the full metadata payload.
+
+No parameters.`,
+  annotations: {
+    title: 'Get all Atlaskit components',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(z.object({}))
+};

package/dist/es2019/tools/get-guidelines/get-guidelines-input-schema.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export const getGuidelinesInputSchema = z.object({
+  terms: z.array(z.string()).default([]).describe('Search terms matched against guideline keywords and body (fuzzy). Examples: `["empty state", "voice tone"]`, `["color tokens", "spacing"]`, `["elevation", "grid"]`. Omit or use an empty array to return **all** guidelines as Markdown.').optional(),
+  limit: z.number().default(1).describe('Max matches **per term** when `terms` is non-empty (default 1). Ignored when returning all guidelines.').optional()
+});

package/dist/es2019/tools/get-guidelines/get-guidelines-tool.js

@@ -0,0 +1,55 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+import Fuse from 'fuse.js';
+import { cleanQuery } from '../../helpers/clean-query';
+import { guidelinesStructuredContent } from './guidelines-structured-content.codegen';
+export const getGuidelinesTool = async params => {
+  const {
+    terms = [],
+    limit = 1
+  } = params;
+  const searchTerms = terms.filter(Boolean).map(cleanQuery);
+  const guidelineDocs = guidelinesStructuredContent;
+
+  // If no search terms provided, return all guidelines formatted as Markdown
+  if (searchTerms.length === 0) {
+    const allGuidelinesMarkdown = guidelineDocs.map(guideline => guideline.content).join('\n\n');
+    return {
+      content: [{
+        type: 'text',
+        text: allGuidelinesMarkdown
+      }]
+    };
+  }
+
+  // Use Fuse.js to fuzzy-search by keywords and content
+  const fuse = new Fuse(guidelineDocs, {
+    keys: [{
+      name: 'keywords',
+      weight: 3
+    }, {
+      name: 'content',
+      weight: 1
+    }],
+    threshold: 0.4
+  });
+  const results = searchTerms.map(term => fuse.search(term).slice(0, limit)).flat();
+
+  // Remove duplicates by content (same guideline can match multiple terms)
+  const seen = new Set();
+  const uniqueResults = results.filter(result => {
+    const text = result.item.content;
+    if (seen.has(text)) {
+      return false;
+    }
+    seen.add(text);
+    return true;
+  });
+  const matchedGuidelines = uniqueResults.map(result => result.item);
+  const formattedGuidelines = matchedGuidelines.map(guideline => guideline.content).join('\n\n');
+  return {
+    content: [{
+      type: 'text',
+      text: formattedGuidelines
+    }]
+  };
+};

package/dist/es2019/tools/get-guidelines/{index.js → list-get-guidelines-tool.js}

@@ -1,13 +1,7 @@
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
-import Fuse from 'fuse.js';
-import { z } from 'zod';
-import { cleanQuery, zodToJsonSchema } from '../../helpers';
-import { guidelinesStructuredContent } from './guidelines-structured-content.codegen';
-export const getGuidelinesInputSchema = z.object({
-  terms: z.array(z.string()).default([]).describe('Search terms matched against guideline keywords and body (fuzzy). Examples: `["empty state", "voice tone"]`, `["color tokens", "spacing"]`, `["elevation", "grid"]`. Omit or use an empty array to return **all** guidelines as Markdown.').optional(),
-  limit: z.number().default(1).describe('Max matches **per term** when `terms` is non-empty (default 1). Ignored when returning all guidelines.').optional()
-});
+import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
+import { getGuidelinesInputSchema } from './get-guidelines-input-schema';
 export const listGetGuidelinesTool = {
   name: 'ads_get_guidelines',
   description: `Returns Atlassian Design System (ADS) **foundations** guidelines as Markdown: the bundled design-system-docs foundations set (not component API docs).
@@ -37,55 +31,4 @@ It is **not** for picking a component’s props or package (use \`ads_plan\` / \
     openWorldHint: true
   },
   inputSchema: zodToJsonSchema(getGuidelinesInputSchema)
-};
-export const getGuidelinesTool = async params => {
-  const {
-    terms = [],
-    limit = 1
-  } = params;
-  const searchTerms = terms.filter(Boolean).map(cleanQuery);
-  const guidelineDocs = guidelinesStructuredContent;
-
-  // If no search terms provided, return all guidelines formatted as Markdown
-  if (searchTerms.length === 0) {
-    const allGuidelinesMarkdown = guidelineDocs.map(guideline => guideline.content).join('\n\n');
-    return {
-      content: [{
-        type: 'text',
-        text: allGuidelinesMarkdown
-      }]
-    };
-  }
-
-  // Use Fuse.js to fuzzy-search by keywords and content
-  const fuse = new Fuse(guidelineDocs, {
-    keys: [{
-      name: 'keywords',
-      weight: 3
-    }, {
-      name: 'content',
-      weight: 1
-    }],
-    threshold: 0.4
-  });
-  const results = searchTerms.map(term => fuse.search(term).slice(0, limit)).flat();
-
-  // Remove duplicates by content (same guideline can match multiple terms)
-  const seen = new Set();
-  const uniqueResults = results.filter(result => {
-    const text = result.item.content;
-    if (seen.has(text)) {
-      return false;
-    }
-    seen.add(text);
-    return true;
-  });
-  const matchedGuidelines = uniqueResults.map(result => result.item);
-  const formattedGuidelines = matchedGuidelines.map(guideline => guideline.content).join('\n\n');
-  return {
-    content: [{
-      type: 'text',
-      text: formattedGuidelines
-    }]
-  };
 };

package/dist/es2019/tools/get-lint-rules/get-lint-rules-input-schema.js

@@ -0,0 +1,7 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+import { z } from 'zod';
+export const getLintRulesInputSchema = z.object({
+  terms: z.array(z.string()).default([]).describe('Search terms matched against rule name, description, and docs body (fuzzy unless \`exactName\` is true). Example: `["icon-label", "xcss", "design token"]`. Omit or empty: return **all** rules as JSON.').optional(),
+  limit: z.number().default(1).describe('Max matches **per term** when searching (default 1). Not used when returning all rules.').optional(),
+  exactName: z.boolean().default(false).describe('If true, resolve each term by **exact** ESLint rule name (case-insensitive). If false, fuzzy search across name, description, and content.').optional()
+});

package/dist/es2019/tools/get-lint-rules/{index.js → get-lint-rules-tool.js}

@@ -1,35 +1,8 @@
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
 import Fuse from 'fuse.js';
-import { z } from 'zod';
-import { cleanQuery, zodToJsonSchema } from '../../helpers';
+import { cleanQuery } from '../../helpers/clean-query';
 import { lintRulesMcpStructuredContent } from './lint-rules-structured-content.codegen';
-export const getLintRulesInputSchema = z.object({
-  terms: z.array(z.string()).default([]).describe('Search terms matched against rule name, description, and docs body (fuzzy unless \`exactName\` is true). Example: `["icon-label", "xcss", "design token"]`. Omit or empty: return **all** rules as JSON.').optional(),
-  limit: z.number().default(1).describe('Max matches **per term** when searching (default 1). Not used when returning all rules.').optional(),
-  exactName: z.boolean().default(false).describe('If true, resolve each term by **exact** ESLint rule name (case-insensitive). If false, fuzzy search across name, description, and content.').optional()
-});
-export const listGetLintRulesTool = {
-  name: 'ads_get_lint_rules',
-  description: `Returns documentation for **Constellation** (Atlassian Design System) ESLint rules shipped with this MCP—rule purpose, examples, and fixes where available.
-
-WHAT YOU GET:
-- No \`terms\`: JSON array of all rule payloads.
-- With \`terms\`: fuzzy search (or exact rule name when \`exactName\` is true); JSON for one or more matching rules.
-
-WHEN TO USE:
-Explaining or fixing an ESLint message from ADS rules (e.g. \`icon-label\`, \`ensure-proper-xcss-usage\`, \`no-deprecated-apis\`), or browsing rule docs without opening the repo. Prefer this over guessing from rule id alone.
-
-This tool does not run ESLint; it only returns bundled documentation.`,
-  annotations: {
-    title: 'Get ADS ESLint rule docs',
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: true
-  },
-  inputSchema: zodToJsonSchema(getLintRulesInputSchema)
-};
 export const getLintRulesTool = async params => {
   const {
     terms = [],

package/dist/es2019/tools/get-lint-rules/list-get-lint-rules-tool.js

@@ -0,0 +1,24 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
+import { getLintRulesInputSchema } from './get-lint-rules-input-schema';
+export const listGetLintRulesTool = {
+  name: 'ads_get_lint_rules',
+  description: `Returns documentation for **Constellation** (Atlassian Design System) ESLint rules shipped with this MCP—rule purpose, examples, and fixes where available.
+
+WHAT YOU GET:
+- No \`terms\`: JSON array of all rule payloads.
+- With \`terms\`: fuzzy search (or exact rule name when \`exactName\` is true); JSON for one or more matching rules.
+
+WHEN TO USE:
+Explaining or fixing an ESLint message from ADS rules (e.g. \`icon-label\`, \`ensure-proper-xcss-usage\`, \`no-deprecated-apis\`), or browsing rule docs without opening the repo. Prefer this over guessing from rule id alone.
+
+This tool does not run ESLint; it only returns bundled documentation.`,
+  annotations: {
+    title: 'Get ADS ESLint rule docs',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(getLintRulesInputSchema)
+};

package/dist/es2019/tools/i18n-conversion/i18n-conversion-input-schema.js

@@ -0,0 +1,5 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+import { z } from 'zod';
+export const i18nConversionInputSchema = z.object({
+  guide: z.enum(['hardcoded-string-to-formatmessage']).describe('Which bundled guide to return. Currently only `hardcoded-string-to-formatmessage` (JSX literals → `formatMessage` / intl patterns).')
+});

package/dist/es2019/tools/i18n-conversion/i18n-conversion-tool.js

@@ -0,0 +1,11 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+import { i18nConversionGuide } from './guide';
+export const i18nConversionTool = async _params => {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(i18nConversionGuide, null, 2)
+    }]
+  };
+};

package/dist/es2019/tools/i18n-conversion/{index.js → list-i18n-conversion-tool.js}

@@ -1,11 +1,7 @@
 /* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
 
-import { z } from 'zod';
-import { zodToJsonSchema } from '../../helpers';
-import { i18nConversionGuide } from './guide';
-export const i18nConversionInputSchema = z.object({
-  guide: z.enum(['hardcoded-string-to-formatmessage']).describe('Which bundled guide to return. Currently only `hardcoded-string-to-formatmessage` (JSX literals → `formatMessage` / intl patterns).')
-});
+import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
+import { i18nConversionInputSchema } from './i18n-conversion-input-schema';
 export const listI18nConversionTool = {
   name: 'ads_i18n_conversion_guide',
   description: `Returns a **bundled** step-by-step guide for replacing hardcoded UI strings with \`formatMessage\` (and related patterns) using @atlassian/jira-intl or react-intl-next: message constants, placeholders, descriptions, and scope/limitations for systematic refactors.
@@ -26,12 +22,4 @@ WHEN TO USE / TYPICAL TRIGGERS:
     openWorldHint: false
   },
   inputSchema: zodToJsonSchema(i18nConversionInputSchema)
-};
-export const i18nConversionTool = async _params => {
-  return {
-    content: [{
-      type: 'text',
-      text: JSON.stringify(i18nConversionGuide, null, 2)
-    }]
-  };
 };

package/dist/es2019/tools/migration-guides/get-available-migration-ids.js

@@ -0,0 +1,17 @@
+/**
+ * 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 { migrationRegistry } from './migration-registry';
+
+/**
+ * Get all available migration IDs for use in the tool schema
+ */
+export const getAvailableMigrationIds = () => {
+  return Object.keys(migrationRegistry);
+};

package/dist/es2019/tools/migration-guides/{registry.js → get-available-migrations-description.js}

@@ -8,12 +8,6 @@
  */
 
 import { migrationRegistry } from './migration-registry';
-/**
- * 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
@@ -21,5 +15,4 @@ export const getAvailableMigrationIds = () => {
  */
 export const getAvailableMigrationsDescription = () => {
   return Object.values(migrationRegistry).map(m => `- "${m.id}": ${m.description}`);
-};
-export { migrationRegistry } from './migration-registry';
+};

package/dist/es2019/tools/migration-guides/list-migration-guides-tool.js

@@ -0,0 +1,25 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
+import { getAvailableMigrationsDescription } from './get-available-migrations-description';
+import { migrationGuidesInputSchema } from './migration-guides-input-schema';
+export const listMigrationGuidesTool = {
+  name: 'ads_migration_guides',
+  description: `Returns a structured Atlassian Design System (ADS) **migration guide** for a known package or API migration (before/after examples, best practices, links).
+
+WHEN TO USE:
+You are upgrading or refactoring code between ADS packages or APIs and need the official migration pattern for a specific id listed below.
+
+Pass **both** \`migration\` and \`description\` using a **matching pair** from the enum (schema enforces valid combinations).
+
+Available migrations:
+${getAvailableMigrationsDescription()}`,
+  annotations: {
+    title: 'ADS Migration Guides',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  inputSchema: zodToJsonSchema(migrationGuidesInputSchema)
+};

package/dist/es2019/tools/migration-guides/migration-guides-input-schema.js

@@ -0,0 +1,10 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+import { z } from 'zod';
+import { getAvailableMigrationIds } from './get-available-migration-ids';
+import { getAvailableMigrationsDescription } from './get-available-migrations-description';
+const migrationIds = getAvailableMigrationIds();
+const migrationDescriptions = getAvailableMigrationsDescription();
+export const migrationGuidesInputSchema = z.object({
+  migration: z.enum(migrationIds).describe('Migration id from the registry. Must match the guide you want (see tool description list).'),
+  description: z.enum(migrationDescriptions).describe('Human-readable migration label that pairs with `migration` in the schema—choose the entry that matches the selected id.')
+});

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

@@ -0,0 +1,39 @@
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+import { getAvailableMigrationIds } from './get-available-migration-ids';
+import { migrationRegistry } from './migration-registry';
+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/migration-registry.js

@@ -1,4 +1,7 @@
-import { onboardingJiraSpotlight, onboardingMultiStep, onboardingSingleStep, onboardingWithMotion } from './migrations/onboarding-to-spotlight';
+import { onboardingJiraSpotlight } from './migrations/onboarding-jira-spotlight';
+import { onboardingMultiStep } from './migrations/onboarding-multi-step';
+import { onboardingSingleStep } from './migrations/onboarding-single-step';
+import { onboardingWithMotion } from './migrations/onboarding-with-motion';
 export const migrationRegistry = {
   [onboardingJiraSpotlight.id]: onboardingJiraSpotlight,
   [onboardingSingleStep.id]: onboardingSingleStep,

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

@@ -0,0 +1,230 @@
+const additionalResources = 'Visit https://hello.atlassian.net/wiki/spaces/DST/pages/6069774593 or https://atlassian.design/components/spotlight for more context';
+export const onboardingJiraSpotlight = {
+  id: 'jira-spotlight',
+  title: 'JiraSpotlight Migration',
+  description: 'Use when code contains `JiraSpotlight` import from `@atlassian/jira-spotlight`',
+  fromPackage: '@atlassian/jira-spotlight',
+  toPackage: '@atlaskit/spotlight',
+  examples: [{
+    title: 'Internal <JiraSpotlight /> migration',
+    description: 'Internal migrations are possible for JiraSpotlight usages which only pass simple/textual content to JiraSpotlight children',
+    before: `
+// file1.tsx
+import { JiraSpotlight } from '@atlassian/jira-spotlight/src/ui/jira-spotlight.tsx';
+
+export const OnboardingSpotlightWrapper = () => {
+	const spotlightId = 'some-unique-identifier'
+	const { dark, light } = spotlightImageUrls[spotlightId];
+	const imageUrl = colorMode === 'dark' ? dark : light;
+
+	return (
+		<JiraSpotlight
+			image={imageUrl}
+			actions={[
+				{
+					onClick,
+					text: formatMessage(dismiss),
+				},
+			]}
+			heading={formatMessage(heading)}
+			target={spotlightId}
+			key={spotlightId}
+			targetRadius={3}
+			targetBgColor={token('elevation.surface')}
+			messageId={spotlightId}
+			messageType="transactional"
+			dialogWidth={275}
+		>
+			{formatMessage(body)}
+		</JiraSpotlight>
+	);
+}
+
+// file2.tsx
+import { SpotlightTarget } from '@atlaskit/onboarding';
+
+const spotlightId = 'some-unique-identifier'
+
+export const SomeFeature = () => {
+	return (
+		<SpotlightTarget name={spotlightId}>
+			// Target code
+		</SpotlightTarget>
+	);
+}
+`,
+    after: `
+// file1.tsx
+import { JiraSpotlight } from '@atlassian/jira-spotlight/src/ui/jira-spotlight.tsx';
+
+export const OnboardingSpotlightWrapper = () => {
+	const spotlightId = 'some-unique-identifier'
+	const { dark, light } = spotlightImageUrls[spotlightId];
+	const imageUrl = colorMode === 'dark' ? dark : light;
+
+	return (
+		<JiraSpotlight
+			isMigrated // isMigrated prop passed
+			image={imageUrl}
+			actions={[
+				{
+					onClick,
+					text: formatMessage(dismiss),
+				},
+			]}
+			heading={formatMessage(heading)}
+			target={spotlightId}
+			key={spotlightId}
+			targetRadius={3}
+			targetBgColor={token('elevation.surface')}
+			messageId={spotlightId}
+			messageType="transactional"
+			dialogWidth={275}
+		>
+			{formatMessage(body)}
+		</JiraSpotlight>
+	);
+}
+
+// file2.tsx
+// Updated SpotlightTarget import statement
+import { SpotlightTarget } from '@atlassian/jira-spotlight/src/ui/SpotlightTarget.tsx';
+
+export const SomeFeature = () => {
+	const spotlightId = 'some-unique-identifier'
+
+	return (
+		<SpotlightTarget name={spotlightId}>
+			// Target code
+		</SpotlightTarget>
+	);
+}
+			`,
+    explanation: `Key changes when migrating a JiraSpotlight:
+- A JiraSpotlight and a SpotlightTarget are part of the same usage if they share a spotlightId value - Referenced in JiraSpotlight.target and SpotlightTarget.name props
+- Pass isMigrated={true} to JiraSpotlight.
+- Update SpotlightTarget import statment from '@atlaskit/onboarding' to '@atlassian/jira-spotlight/src/ui/SpotlightTarget.tsx';
+- These changes allow switching the internal implementation to '@atlaskit/spotlight' via a feature flag.
+- This internal migration is only possible for usages that don't rely too heavily on the 'children' prop, as complex values, like heading, images, etc passed to 'children' are difficult to parse.
+`
+  }, {
+    title: 'Complex <JiraSpotlight /> migration',
+    description: 'Complex migrations are necessary for JiraSpotlight usages that make heavy use of the `children` prop to achieve customisation instead of relying on the `heading`, `body`, `image`, and/or `actions` props.',
+    before: `
+// file1.tsx
+import { JiraSpotlight } from '@atlassian/jira-spotlight/src/ui/jira-spotlight.tsx';
+
+export const OnboardingSpotlightWrapper = () => {
+	const spotlightId = 'some-unique-identifier'
+	const { dark, light } = spotlightImageUrls[spotlightId];
+	const imageUrl = colorMode === 'dark' ? dark : light;
+
+	return (
+		<JiraSpotlight
+			target={spotlightId}
+			targetRadius={3}
+			dialogPlacement=''
+			targetBgColor={token('elevation.surface')}
+			messageId={spotlightId}
+			messageType="transactional"
+			dialogWidth={275}
+		>
+			<CustomSpotlightInner>
+				{imageUrl}
+				{formatMessage(heading)}
+				{formatMessage(body)}
+				<CustomSpotlightAction>
+					{formatMessage(dismiss)}
+				</CustomSpotlightAction>
+			</CustomSpotlightInner>
+		</JiraSpotlight>
+	);
+}
+
+// file2.tsx
+import { SpotlightTarget } from '@atlaskit/onboarding';
+
+const spotlightId = 'some-unique-identifier'
+
+export const SomeFeature = () => {
+	return (
+		<SpotlightTarget name={spotlightId}>
+			// Target code
+		</SpotlightTarget>
+	);
+}
+`,
+    after: `
+// file2.tsx - Spotlight code has been co-located to the targeted element
+import { Text } from '@atlaskit/primitives/compiled';
+import {
+  PopoverContent,
+  PopoverProvider,
+  PopoverTarget,
+  SpotlightActions,
+  SpotlightBody,
+  SpotlightCard,
+  SpotlightControls,
+  SpotlightDismissControl,
+  SpotlightFooter,
+  SpotlightHeader,
+  SpotlightHeadline,
+  SpotlightPrimaryAction,
+} from '@atlaskit/spotlight';
+import Image from '@atlaskit/image';
+import { ChoreographedComponent } from '@atlassian/jira-spotlight/src/ui/ChoreographedComponent.tsx';
+
+export const SomeFeature = () => {
+	const { dark, light } = spotlightImageUrls[spotlightId];
+
+	const [isSpotlightVisible, actions] = useListViewOnboarding({
+		projectId: String(projectData.id),
+		id: spotlightId,
+	});
+
+	return (
+		<PopoverProvider>
+			<PopoverTarget>{renderTrigger(isSpotlightVisible)}</PopoverTarget>
+			<ChoreographedComponent messageId={spotlightId} messageType="transactional">
+				<PopoverContent isVisible={isSpotlightVisible} placement="bottom-start" dismiss={onClick}>
+					<SpotlightCard>
+						<SpotlightHeader>
+							<SpotlightHeadline>{formatMessage(heading)}</SpotlightHeadline>
+							<SpotlightControls>
+								<SpotlightDismissControl />
+							</SpotlightControls>
+						</SpotlightHeader>
+						<SpotlightMedia>
+							<Image src={light} srcDark={dark} alt="" />
+						</SpotlightMedia>
+						<SpotlightBody>
+							<Text>{formatMessage(body)}</Text>
+						</SpotlightBody>
+						<SpotlightFooter>
+							<SpotlightActions>
+								<SpotlightPrimaryAction onClick={onClick}>
+									{formatMessage(dismiss)}
+								</SpotlightPrimaryAction>
+							</SpotlightActions>
+						</SpotlightFooter>
+					</SpotlightCard>
+				</PopoverContent>
+			</ChoreographedComponent>
+		</PopoverProvider>
+	);
+};`,
+    explanation: `Key changes when migrating a single step spotlight:
+- Replace JiraSpotlight with ChoreographedComponent from '@atlassian/jira-spotlight'.
+- PopoverProvider maintains internal Spotlight state.
+- Replace SpotlightTarget with PopoverTarget - wraps the element to highlight
+- Replace Spotlight with PopoverContent containing SpotlightCard - controls visibility and positioning
+- 'heading' becomes SpotlightHeadline inside SpotlightHeader
+- 'actions' becomes SpotlightActions with SpotlightPrimaryAction (and optionally SpotlightSecondaryAction)
+- 'body' content moves into SpotlightBody wrapped with Text component
+- Add SpotlightDismissControl inside SpotlightControls for the close button
+- The 'target' and/or 'targetName' prop is replaced with PopoverTarget directly wrapping the target element
+- 'dialogPlacement' prop becomes 'placement' on PopoverContent. Mapping: "top right" → "top-start", "top center" → "top", "top left" → "top-end", "right bottom" → "right-start", "right middle" → "right-start | right-end", "right top" → "right-end", "bottom left" → "bottom-end", "bottom center" → "bottom", "bottom right" → "bottom-start", "left top" → "left-end", "left middle" → "left-start | left-end", "left bottom" → "left-start"'`
+  }],
+  bestPractices: [],
+  additionalResources
+};