@atlaskit/ads-mcp 1.10.1 → 1.10.3

package/dist/esm/tools/i18n-conversion/guide.js

@@ -5,33 +5,33 @@
 export var i18nConversionGuide = {
   id: 'hardcoded-string-to-formatmessage',
   title: 'Hardcoded String to formatMessage Conversion Guide',
-  description: 'Comprehensive guide for converting hardcoded strings to use formatMessage or FormattedMessage from @atlassian/jira-intl or react-intl',
-  purpose: 'This guide instructs LLM agents to convert hardcoded strings to use formatMessage or FormattedMessage. The import source depends on the file path: use @atlassian/jira-intl for Jira files (path contains "jira"), and react-intl for any non-Jira files. **CRITICAL: Check for existing imports** - If the file already imports from react-intl or react-intl, reuse that import. If the file already uses FormattedMessage, use FormattedMessage for consistency instead of useIntl + formatMessage. The goal is to find all hardcoded strings in JSX and convert them to internationalized messages.',
+  description: 'Comprehensive guide for converting hardcoded strings to use formatMessage or FormattedMessage from @jira/platform__react-intl or react-intl',
+  purpose: 'This guide instructs LLM agents to convert hardcoded strings to use formatMessage or FormattedMessage. The import source depends on the file path: use @jira/platform__react-intl for Jira files (path contains "jira"), and react-intl for any non-Jira files. **CRITICAL: Check for existing imports** - If the file already imports from react-intl or react-intl, reuse that import. If the file already uses FormattedMessage, use FormattedMessage for consistency instead of useIntl + formatMessage. The goal is to find all hardcoded strings in JSX and convert them to internationalized messages.',
   scope: "**CRITICAL SCOPE**: This process should **ONLY** focus on converting hardcoded strings (literal strings in JSX, eslint-disable comments for no-literal-string-in-jsx, etc.) to use formatMessage. Do NOT modify pre-existing messages that were already in the codebase, even if they have poor descriptions, incorrect placeholder names, or other quality issues. Only convert NEW hardcoded strings.\n\n**PATH SCOPE LIMITATION**: If a specific file, package name, or path is provided, **ONLY** find and convert hardcoded strings within that specified path. Do NOT modify files outside the provided scope.\n\n**CRITICAL: ONLY CONVERT STRINGS WITH ESLINT-DISABLE**: You MUST **ONLY** convert strings that have eslint-disable comments for @atlassian/i18n/no-literal-string-in-jsx. Do NOT proactively convert strings that don't have these comments. For example, field labels like `label=\"Space Name\"` that don't have eslint-disable comments should be LEFT AS-IS - they may be acceptable as-is or intentionally not internationalized. Only convert strings that explicitly have the eslint-disable comment indicating they need to be fixed.\n\n**CRITICAL: FIX ALL VIOLATIONS IN FILE**: When a specific file is mentioned (even with line numbers like `@file.tsx:139-142`), you MUST find and fix **ALL** @atlassian/i18n/no-literal-string-in-jsx violations in that entire file, not just the specific lines mentioned. Scan the entire file for hardcoded strings WITH eslint-disable comments and convert them all. The line numbers are just a reference point - the goal is to fix all i18n violations (those with eslint-disable comments) in the provided file.\n\n**CRITICAL: STRING FILTERING**: When finding eslint-disable comments, you MUST examine the actual string content. Only convert strings that contain **user-facing English text**. Many English strings are technical/non-user-facing and should NOT be converted (e.g., product names like \"Jira\", URLs like \"https://example.com\", technical IDs, symbols). Use the ESLint ignore patterns to identify which English strings to skip - strings matching ignore patterns should be LEFT AS-IS with their eslint-disable comments intact.",
-  implementationChecklist: ['**CRITICAL: Only convert strings with eslint-disable** - ONLY convert strings that have eslint-disable comments for @atlassian/i18n/no-literal-string-in-jsx. Do NOT convert strings without these comments (e.g., field labels like label="Space Name" without eslint-disable should remain as-is).', '**CRITICAL: Check for existing imports** - If the file already imports from react-intl or react-intl, REUSE that import. Only add a new import if none exists.', '**CRITICAL: Match existing pattern** - If the file already uses FormattedMessage, use FormattedMessage with inline props. If it uses useIntl + formatMessage, use defineMessage + formatMessage. Match the existing code style.', "**CRITICAL: When to use formatMessage() vs <FormattedMessage>** - Use formatMessage() for prop values (labels, placeholders, aria-labels), computed values, event handlers, and non-JSX contexts. Use <FormattedMessage> for JSX content where you'd otherwise write {formatMessage(...)}.", 'Import: Use "@atlassian/jira-intl" for Jira files or "react-intl" for non-Jira files. Note: "react-intl" and "react-intl" are treated the same way - both use the same API. When adding to existing imports, maintain alphabetical order: import { defineMessage, FormattedMessage } from "react-intl";', '**CRITICAL: FormattedMessage pattern** - When using FormattedMessage, define message details directly inline: <FormattedMessage id="..." defaultMessage="..." description="..." />. NO need to use defineMessage - FormattedMessage accepts these props directly.', '**CRITICAL: formatMessage pattern** - When using useIntl + formatMessage, create message constants using defineMessage (singular) at the top of the file - use defineMessage for each individual message, NOT defineMessages. Then use: const { formatMessage } = useIntl(); formatMessage(messageKey)', '**CRITICAL: i18n ID Format**: For files in `/next/packages/`, i18n ids MUST start with the package name (with dashes). Format: `{package-name}.{component-or-feature}.{message-key}`. Example: For package `comment-extension-handlers`, use `comment-extension-handlers.legacy-content-modal.close-button`. For package `rovo-ai-search`, use `rovo-ai-search.view-profile-text` or `rovo-ai-search.knowledge-cards.copy-email-address`.', '**CRITICAL: ai-non-final Suffix**: ALL new message IDs MUST end with `.ai-non-final` suffix. This applies to ALL newly created messages, regardless of whether existing messages in the file have this suffix. Format: `{message-key}.ai-non-final`. Example: `applinks.administration.list.applinks-table.system-label.ai-non-final`. This suffix indicates the message is AI-generated and may need review before finalization.', 'Replace hardcoded strings with either formatMessage(messageKey) or <FormattedMessage id="..." defaultMessage="..." description="..." /> based on existing pattern', '**CRITICAL: Write comprehensive descriptions** - Descriptions are instructions for translators. Include: (1) Where text is shown and the UI element (e.g., "on a button", "as an error message", "as a title", "for a link", "as a drop-down item"), (2) What it does, triggers, or prompts, (3) If there is a placeholder, explain how it will be substituted and with what, (4) If there is an ICU MessageFormat statement (not a placeholder!), provide instruction on the resolved ICU message, not on the ICU structure unless there are more than 2 plural statements, (5) Explain the purpose of the sentence in defaultMessage, (6) Propose an alternative text in Plain English only if the text contains an idiom. Descriptions must be 40+ chars and unique from defaultMessage.', 'Remove eslint-disable for no-literal-string-in-jsx ONLY after converting', '**VERIFICATION**: To verify all hardcoded strings are fixed, search for `@atlassian/i18n/no-literal-string-in-jsx` in the file. Do NOT run eslint - just search for the eslint-disable comments. If no matches are found, all hardcoded strings have been converted.'],
+  implementationChecklist: ['**CRITICAL: Only convert strings with eslint-disable** - ONLY convert strings that have eslint-disable comments for @atlassian/i18n/no-literal-string-in-jsx. Do NOT convert strings without these comments (e.g., field labels like label="Space Name" without eslint-disable should remain as-is).', '**CRITICAL: Check for existing imports** - If the file already imports from react-intl or react-intl, REUSE that import. Only add a new import if none exists.', '**CRITICAL: Match existing pattern** - If the file already uses FormattedMessage, use FormattedMessage with inline props. If it uses useIntl + formatMessage, use defineMessage + formatMessage. Match the existing code style.', "**CRITICAL: When to use formatMessage() vs <FormattedMessage>** - Use formatMessage() for prop values (labels, placeholders, aria-labels), computed values, event handlers, and non-JSX contexts. Use <FormattedMessage> for JSX content where you'd otherwise write {formatMessage(...)}.", 'Import: Use "@jira/platform__react-intl" for Jira files or "react-intl" for non-Jira files. Note: "react-intl" and "react-intl" are treated the same way - both use the same API. When adding to existing imports, maintain alphabetical order: import { defineMessage, FormattedMessage } from "react-intl";', '**CRITICAL: FormattedMessage pattern** - When using FormattedMessage, define message details directly inline: <FormattedMessage id="..." defaultMessage="..." description="..." />. NO need to use defineMessage - FormattedMessage accepts these props directly.', '**CRITICAL: formatMessage pattern** - When using useIntl + formatMessage, create message constants using defineMessage (singular) at the top of the file - use defineMessage for each individual message, NOT defineMessages. Then use: const { formatMessage } = useIntl(); formatMessage(messageKey)', '**CRITICAL: i18n ID Format**: For files in `/next/packages/`, i18n ids MUST start with the package name (with dashes). Format: `{package-name}.{component-or-feature}.{message-key}`. Example: For package `comment-extension-handlers`, use `comment-extension-handlers.legacy-content-modal.close-button`. For package `rovo-ai-search`, use `rovo-ai-search.view-profile-text` or `rovo-ai-search.knowledge-cards.copy-email-address`.', '**CRITICAL: ai-non-final Suffix**: ALL new message IDs MUST end with `.ai-non-final` suffix. This applies to ALL newly created messages, regardless of whether existing messages in the file have this suffix. Format: `{message-key}.ai-non-final`. Example: `applinks.administration.list.applinks-table.system-label.ai-non-final`. This suffix indicates the message is AI-generated and may need review before finalization.', 'Replace hardcoded strings with either formatMessage(messageKey) or <FormattedMessage id="..." defaultMessage="..." description="..." /> based on existing pattern', '**CRITICAL: Write comprehensive descriptions** - Descriptions are instructions for translators. Include: (1) Where text is shown and the UI element (e.g., "on a button", "as an error message", "as a title", "for a link", "as a drop-down item"), (2) What it does, triggers, or prompts, (3) If there is a placeholder, explain how it will be substituted and with what, (4) If there is an ICU MessageFormat statement (not a placeholder!), provide instruction on the resolved ICU message, not on the ICU structure unless there are more than 2 plural statements, (5) Explain the purpose of the sentence in defaultMessage, (6) Propose an alternative text in Plain English only if the text contains an idiom. Descriptions must be 40+ chars and unique from defaultMessage.', 'Remove eslint-disable for no-literal-string-in-jsx ONLY after converting', '**VERIFICATION**: To verify all hardcoded strings are fixed, search for `@atlassian/i18n/no-literal-string-in-jsx` in the file. Do NOT run eslint - just search for the eslint-disable comments. If no matches are found, all hardcoded strings have been converted.'],
   patterns: [{
     title: 'Button Text and Action Labels',
     description: 'Converting hardcoded button text with variables',
     before: "<Button style={styles} onClick={onClearVersion}>\n  Exit {description.join(' ')}\n</Button>",
-    after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst exitButton = defineMessage({\n  id: 'rovo-ai-search.exit-button.ai-non-final',\n  defaultMessage: 'Exit {version}',\n\tdescription: 'This is the text on a button. The placeholder {version} will be substituted with the version name (e.g., \"Exit v2.0\"). After a user clicks on the button, it will exit the version view and return to the main view. Appears in the version header.',\n});\n\nexport function MyComponent() {\n  const { formatMessage } = useIntl();\n\n  return (\n    <Button style={styles} onClick={onClearVersion}>\n      {formatMessage(exitButton, { version: description.join(' ') })}\n    </Button>\n  );\n}",
+    after: "import { useIntl, defineMessage } from '@jira/platform__react-intl';\n\nconst exitButton = defineMessage({\n  id: 'rovo-ai-search.exit-button.ai-non-final',\n  defaultMessage: 'Exit {version}',\n\tdescription: 'This is the text on a button. The placeholder {version} will be substituted with the version name (e.g., \"Exit v2.0\"). After a user clicks on the button, it will exit the version view and return to the main view. Appears in the version header.',\n});\n\nexport function MyComponent() {\n  const { formatMessage } = useIntl();\n\n  return (\n    <Button style={styles} onClick={onClearVersion}>\n      {formatMessage(exitButton, { version: description.join(' ') })}\n    </Button>\n  );\n}",
     explanation: 'Convert button text with variables to use placeholders in the message. Use descriptive placeholder names that match the variable context.'
   }, {
     title: 'Partial String Translation (Prefixes and Labels)',
     description: 'Translating only part of a string while preserving UI structure',
     before: "<Box xcss={styles}>\n  <span>Status: {selectedOptions[0]?.label}</span>\n  {selectedOptions.length > 1 && (\n    <Badge appearance=\"primary\" max={99}>\n      +{selectedOptions.length - 1}\n    </Badge>\n  )}\n</Box>",
-    after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst statusLabel = defineMessage({\n  id: 'filter.status-label.ai-non-final',\n  defaultMessage: 'Status: {status}',\n\tdescription: 'This is the text shown as a button label prefix for the status filter. The placeholder {status} will be substituted with the selected status label (e.g., \"Status: In Progress\"). Appears in the filter button to show the current filter state.',\n});\n\nexport function MyComponent() {\n  const { formatMessage } = useIntl();\n\n  return (\n    <Box xcss={styles}>\n      <span>\n        {formatMessage(statusLabel, {\n          status: selectedOptions[0]?.label,\n        })}\n      </span>\n      {selectedOptions.length > 1 && (\n        <Badge appearance=\"primary\" max={99}>\n          +{selectedOptions.length - 1}\n        </Badge>\n      )}\n    </Box>\n  );\n}",
+    after: "import { useIntl, defineMessage } from '@jira/platform__react-intl';\n\nconst statusLabel = defineMessage({\n  id: 'filter.status-label.ai-non-final',\n  defaultMessage: 'Status: {status}',\n\tdescription: 'This is the text shown as a button label prefix for the status filter. The placeholder {status} will be substituted with the selected status label (e.g., \"Status: In Progress\"). Appears in the filter button to show the current filter state.',\n});\n\nexport function MyComponent() {\n  const { formatMessage } = useIntl();\n\n  return (\n    <Box xcss={styles}>\n      <span>\n        {formatMessage(statusLabel, {\n          status: selectedOptions[0]?.label,\n        })}\n      </span>\n      {selectedOptions.length > 1 && (\n        <Badge appearance=\"primary\" max={99}>\n          +{selectedOptions.length - 1}\n        </Badge>\n      )}\n    </Box>\n  );\n}",
     explanation: 'When only part of a string needs translation (like a prefix "Status: " or label), create a message with a placeholder for the dynamic part. Preserve the existing UI structure (components, conditional rendering, etc.) and only translate the literal string portion.'
   }, {
     title: 'Dynamic Text Content',
     description: 'Converting conditional hardcoded strings',
     before: "<Text>{state.hasMore ? 'Show more' : 'Show less'}</Text>",
-    after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst showMore = defineMessage({\n  id: 'work-item.comments.show-more.ai-non-final',\n  defaultMessage: 'Show more',\n\tdescription: 'This is the text on a button. It appears when there are more items available to display. After a user clicks on the button, it will expand the view to show additional content. Used in the comments section footer.',\n});\n\nconst showLess = defineMessage({\n  id: 'work-item.comments.show-less.ai-non-final',\n  defaultMessage: 'Show less',\n\tdescription: 'This is the text on a button. It appears when the user wants to collapse the expanded view. After a user clicks on the button, it will hide the additional content that was previously expanded. Used in the comments section footer.',\n});\n\nexport function MyComponent() {\n  const { formatMessage } = useIntl();\n\n  return (\n    <Text>\n      {state.hasMore\n        ? formatMessage(showMore)\n        : formatMessage(showLess)}\n    </Text>\n  );\n}",
+    after: "import { useIntl, defineMessage } from '@jira/platform__react-intl';\n\nconst showMore = defineMessage({\n  id: 'work-item.comments.show-more.ai-non-final',\n  defaultMessage: 'Show more',\n\tdescription: 'This is the text on a button. It appears when there are more items available to display. After a user clicks on the button, it will expand the view to show additional content. Used in the comments section footer.',\n});\n\nconst showLess = defineMessage({\n  id: 'work-item.comments.show-less.ai-non-final',\n  defaultMessage: 'Show less',\n\tdescription: 'This is the text on a button. It appears when the user wants to collapse the expanded view. After a user clicks on the button, it will hide the additional content that was previously expanded. Used in the comments section footer.',\n});\n\nexport function MyComponent() {\n  const { formatMessage } = useIntl();\n\n  return (\n    <Text>\n      {state.hasMore\n        ? formatMessage(showMore)\n        : formatMessage(showLess)}\n    </Text>\n  );\n}",
     explanation: 'Create separate message constants for each conditional string. Use descriptive names that reflect the context.'
   }, {
     title: 'ICU Format for Numeric Values',
     description: 'Converting numeric placeholders to ICU plural format',
     before: "const moreMessage = `+ ${count} more`;",
-    after: "import { useIntl, defineMessage } from '@atlassian/jira-intl';\n\nconst moreProjectsMessage = defineMessage({\n  id: 'app.more-projects.ai-non-final',\n  defaultMessage: '{count, plural, one {+ # more} other {+ # more}}',\n\tdescription: 'This is the text shown when there are additional projects available. The variable {count} will be substituted with the number of remaining projects, and the message will display accordingly (e.g., \"+ 5 more\" or \"+ 1 more\"). Appears to indicate how many more items can be viewed.',\n});\n\nexport function MyComponent() {\n  const { formatMessage } = useIntl();\n  const count = 5;\n\n  return (\n    <Text>\n      {formatMessage(moreProjectsMessage, { count })}\n    </Text>\n  );\n}",
+    after: "import { useIntl, defineMessage } from '@jira/platform__react-intl';\n\nconst moreProjectsMessage = defineMessage({\n  id: 'app.more-projects.ai-non-final',\n  defaultMessage: '{count, plural, one {+ # more} other {+ # more}}',\n\tdescription: 'This is the text shown when there are additional projects available. The variable {count} will be substituted with the number of remaining projects, and the message will display accordingly (e.g., \"+ 5 more\" or \"+ 1 more\"). Appears to indicate how many more items can be viewed.',\n});\n\nexport function MyComponent() {\n  const { formatMessage } = useIntl();\n  const count = 5;\n\n  return (\n    <Text>\n      {formatMessage(moreProjectsMessage, { count })}\n    </Text>\n  );\n}",
     explanation: 'Use ICU plural format for numeric values that may need pluralization. The # symbol represents the numeric value in ICU format.'
   }, {
     title: 'Using FormattedMessage',
@@ -47,6 +47,6 @@ export var i18nConversionGuide = {
     explanation: "Use formatMessage() for prop values (labels, placeholders, aria-labels), computed values, event handlers, and non-JSX contexts. Use <FormattedMessage> for JSX content where you'd otherwise write {formatMessage(...)}. In this example, label and placeholder props use formatMessage(), while button text and content use FormattedMessage."
   }],
   bestPractices: ['Use descriptive names (userNameLabel not label) and placeholders (userName not value)', 'Use ICU plural format for numeric values: {count, plural, one {...} other {...}}', 'When using formatMessage pattern: Place message constants at top of file. When using FormattedMessage pattern: Define messages inline in JSX.', "Use formatMessage() for prop values (labels, placeholders, aria-labels), computed values, event handlers, and non-JSX contexts. Use <FormattedMessage> for JSX content where you'd otherwise write {formatMessage(...)}.", 'Convert arrow functions to body form if needed for hooks'],
-  commonPitfalls: ["**CRITICAL**: Converting strings that don't have eslint-disable comments - only convert strings with @atlassian/i18n/no-literal-string-in-jsx eslint-disable comments. Field labels and other strings without these comments should remain as-is.", '**CRITICAL**: Converting/removing eslint-disable for strings matching ignore patterns - technical/non-user-facing strings should remain hardcoded', '**CRITICAL**: Forgetting to remove eslint-disable comments after conversion - once a string is converted to use formatMessage/FormattedMessage, the eslint-disable comment must be removed', 'Using wrong import path - "jira" path needs @atlassian/jira-intl (with eslint-disable), others use react-intl', 'Adding eslint-disable for defineMessage in non-Jira files or forgetting it in Jira files', 'Missing useIntl hook when using formatMessage pattern, generic placeholder names, descriptions < 40 chars, or descriptions that do not follow the translator guidelines (missing UI element location, missing action explanation, etc.)', "Using placeholder names that don't match variable names - placeholder names in defaultMessage must exactly match the keys in the values object or formatMessage parameters", 'Modifying pre-existing messages or working outside specified path scope'],
+  commonPitfalls: ["**CRITICAL**: Converting strings that don't have eslint-disable comments - only convert strings with @atlassian/i18n/no-literal-string-in-jsx eslint-disable comments. Field labels and other strings without these comments should remain as-is.", '**CRITICAL**: Converting/removing eslint-disable for strings matching ignore patterns - technical/non-user-facing strings should remain hardcoded', '**CRITICAL**: Forgetting to remove eslint-disable comments after conversion - once a string is converted to use formatMessage/FormattedMessage, the eslint-disable comment must be removed', 'Using wrong import path - "jira" path needs @jira/platform__react-intl (with eslint-disable), others use react-intl', 'Adding eslint-disable for defineMessage in non-Jira files or forgetting it in Jira files', 'Missing useIntl hook when using formatMessage pattern, generic placeholder names, descriptions < 40 chars, or descriptions that do not follow the translator guidelines (missing UI element location, missing action explanation, etc.)', "Using placeholder names that don't match variable names - placeholder names in defaultMessage must exactly match the keys in the values object or formatMessage parameters", 'Modifying pre-existing messages or working outside specified path scope'],
   additionalResources: ['ESLint rule @atlassian/i18n/no-literal-string-in-jsx defines ignore patterns for technical strings (URLs, product names, symbols, etc.)']
 };

package/dist/esm/tools/i18n-conversion/list-i18n-conversion-tool.js

@@ -4,7 +4,7 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { i18nConversionInputSchema } from './i18n-conversion-input-schema';
 export var 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: message constants, placeholders, descriptions, and scope/limitations for systematic refactors.\n\nWhen working with i18n or hardcoded UI strings, use this tool alongside the Context Engine MCP tool `get_i18n_docs` for Atlassian-wide Traduki / i18n standards (message definition, extraction, pluralisation, formatting, workflow); this tool supplies the concrete hardcoded-string \u2192 `formatMessage` playbook bundled in ADS MCP.\n\nWHEN TO USE / TYPICAL TRIGGERS:\n- Refactoring JSX or TS literals to i18n; \"fix hardcoded string(s)\", \"convert hardcoded string in [file]\", \"literal string in JSX\".\n- \"Convert to i18n\", \"convert to formatMessage\", \"translate this string\", \"internationalize this string\", \"i18n this string\".\n- \"Use formatMessage\", \"use FormattedMessage\", \"wrap in formatMessage\", \"fix literal string\".\n- ESLint: `Literal string in JSX content should be internationalized. Use FormattedMessage or intl.formatMessage()`.\n- ESLint: `@atlassian/i18n/no-literal-string-in-jsx`.",
+  description: "Returns a **bundled** step-by-step guide for replacing hardcoded UI strings with `formatMessage` (and related patterns) using @jira/platform__react-intl or react-intl: message constants, placeholders, descriptions, and scope/limitations for systematic refactors.\n\nWhen working with i18n or hardcoded UI strings, use this tool alongside the Context Engine MCP tool `get_i18n_docs` for Atlassian-wide Traduki / i18n standards (message definition, extraction, pluralisation, formatting, workflow); this tool supplies the concrete hardcoded-string \u2192 `formatMessage` playbook bundled in ADS MCP.\n\nWHEN TO USE / TYPICAL TRIGGERS:\n- Refactoring JSX or TS literals to i18n; \"fix hardcoded string(s)\", \"convert hardcoded string in [file]\", \"literal string in JSX\".\n- \"Convert to i18n\", \"convert to formatMessage\", \"translate this string\", \"internationalize this string\", \"i18n this string\".\n- \"Use formatMessage\", \"use FormattedMessage\", \"wrap in formatMessage\", \"fix literal string\".\n- ESLint: `Literal string in JSX content should be internationalized. Use FormattedMessage or intl.formatMessage()`.\n- ESLint: `@atlassian/i18n/no-literal-string-in-jsx`.",
   annotations: {
     title: 'i18n conversion guide',
     readOnlyHint: true,

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

@@ -15,7 +15,7 @@ export var onboardingJiraSpotlight = {
     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: "\n// file1.tsx\nimport { JiraSpotlight } from '@atlassian/jira-spotlight/src/ui/jira-spotlight.tsx';\n\nexport const OnboardingSpotlightWrapper = () => {\n\tconst spotlightId = 'some-unique-identifier'\n\tconst { dark, light } = spotlightImageUrls[spotlightId];\n\tconst imageUrl = colorMode === 'dark' ? dark : light;\n\n\treturn (\n\t\t<JiraSpotlight\n\t\t\ttarget={spotlightId}\n\t\t\ttargetRadius={3}\n\t\t\tdialogPlacement=''\n\t\t\ttargetBgColor={token('elevation.surface')}\n\t\t\tmessageId={spotlightId}\n\t\t\tmessageType=\"transactional\"\n\t\t\tdialogWidth={275}\n\t\t>\n\t\t\t<CustomSpotlightInner>\n\t\t\t\t{imageUrl}\n\t\t\t\t{formatMessage(heading)}\n\t\t\t\t{formatMessage(body)}\n\t\t\t\t<CustomSpotlightAction>\n\t\t\t\t\t{formatMessage(dismiss)}\n\t\t\t\t</CustomSpotlightAction>\n\t\t\t</CustomSpotlightInner>\n\t\t</JiraSpotlight>\n\t);\n}\n\n// file2.tsx\nimport { SpotlightTarget } from '@atlaskit/onboarding';\n\nconst spotlightId = 'some-unique-identifier'\n\nexport const SomeFeature = () => {\n\treturn (\n\t\t<SpotlightTarget name={spotlightId}>\n\t\t\t// Target code\n\t\t</SpotlightTarget>\n\t);\n}\n",
-    after: "\n// file2.tsx - Spotlight code has been co-located to the targeted element\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';\nimport Image from '@atlaskit/image';\nimport { ChoreographedComponent } from '@atlassian/jira-spotlight/src/ui/ChoreographedComponent.tsx';\n\nexport const SomeFeature = () => {\n\tconst { dark, light } = spotlightImageUrls[spotlightId];\n\n\tconst [isSpotlightVisible, actions] = useListViewOnboarding({\n\t\tprojectId: String(projectData.id),\n\t\tid: spotlightId,\n\t});\n\n\treturn (\n\t\t<PopoverProvider>\n\t\t\t<PopoverTarget>{renderTrigger(isSpotlightVisible)}</PopoverTarget>\n\t\t\t<ChoreographedComponent messageId={spotlightId} messageType=\"transactional\">\n\t\t\t\t<PopoverContent isVisible={isSpotlightVisible} placement=\"bottom-start\" dismiss={onClick}>\n\t\t\t\t\t<SpotlightCard>\n\t\t\t\t\t\t<SpotlightHeader>\n\t\t\t\t\t\t\t<SpotlightHeadline>{formatMessage(heading)}</SpotlightHeadline>\n\t\t\t\t\t\t\t<SpotlightControls>\n\t\t\t\t\t\t\t\t<SpotlightDismissControl />\n\t\t\t\t\t\t\t</SpotlightControls>\n\t\t\t\t\t\t</SpotlightHeader>\n\t\t\t\t\t\t<SpotlightMedia>\n\t\t\t\t\t\t\t<Image src={light} srcDark={dark} alt=\"\" />\n\t\t\t\t\t\t</SpotlightMedia>\n\t\t\t\t\t\t<SpotlightBody>\n\t\t\t\t\t\t\t<Text>{formatMessage(body)}</Text>\n\t\t\t\t\t\t</SpotlightBody>\n\t\t\t\t\t\t<SpotlightFooter>\n\t\t\t\t\t\t\t<SpotlightActions>\n\t\t\t\t\t\t\t\t<SpotlightPrimaryAction onClick={onClick}>\n\t\t\t\t\t\t\t\t\t{formatMessage(dismiss)}\n\t\t\t\t\t\t\t\t</SpotlightPrimaryAction>\n\t\t\t\t\t\t\t</SpotlightActions>\n\t\t\t\t\t\t</SpotlightFooter>\n\t\t\t\t\t</SpotlightCard>\n\t\t\t\t</PopoverContent>\n\t\t\t</ChoreographedComponent>\n\t\t</PopoverProvider>\n\t);\n};",
+    after: "\n// file2.tsx - Spotlight code has been co-located to the targeted element\nimport { Text } from '@atlaskit/primitives/compiled';\nimport { PopoverContent } from '@atlaskit/spotlight/popover-content';\nimport { PopoverProvider } from '@atlaskit/spotlight/popover-provider';\nimport { PopoverTarget } from '@atlaskit/spotlight/popover-target';\nimport { SpotlightActions } from '@atlaskit/spotlight/actions';\nimport { SpotlightBody } from '@atlaskit/spotlight/body';\nimport { SpotlightCard } from '@atlaskit/spotlight/card';\nimport { SpotlightControls } from '@atlaskit/spotlight/controls';\nimport { SpotlightDismissControl } from '@atlaskit/spotlight/dismiss-control';\nimport { SpotlightFooter } from '@atlaskit/spotlight/footer';\nimport { SpotlightHeader } from '@atlaskit/spotlight/header';\nimport { SpotlightHeadline } from '@atlaskit/spotlight/headline';\nimport { SpotlightPrimaryAction } from '@atlaskit/spotlight/primary-action';\nimport Image from '@atlaskit/image';\nimport { ChoreographedComponent } from '@atlassian/jira-spotlight/src/ui/ChoreographedComponent.tsx';\n\nexport const SomeFeature = () => {\n\tconst { dark, light } = spotlightImageUrls[spotlightId];\n\n\tconst [isSpotlightVisible, actions] = useListViewOnboarding({\n\t\tprojectId: String(projectData.id),\n\t\tid: spotlightId,\n\t});\n\n\treturn (\n\t\t<PopoverProvider>\n\t\t\t<PopoverTarget>{renderTrigger(isSpotlightVisible)}</PopoverTarget>\n\t\t\t<ChoreographedComponent messageId={spotlightId} messageType=\"transactional\">\n\t\t\t\t<PopoverContent isVisible={isSpotlightVisible} placement=\"bottom-start\" dismiss={onClick}>\n\t\t\t\t\t<SpotlightCard>\n\t\t\t\t\t\t<SpotlightHeader>\n\t\t\t\t\t\t\t<SpotlightHeadline>{formatMessage(heading)}</SpotlightHeadline>\n\t\t\t\t\t\t\t<SpotlightControls>\n\t\t\t\t\t\t\t\t<SpotlightDismissControl />\n\t\t\t\t\t\t\t</SpotlightControls>\n\t\t\t\t\t\t</SpotlightHeader>\n\t\t\t\t\t\t<SpotlightMedia>\n\t\t\t\t\t\t\t<Image src={light} srcDark={dark} alt=\"\" />\n\t\t\t\t\t\t</SpotlightMedia>\n\t\t\t\t\t\t<SpotlightBody>\n\t\t\t\t\t\t\t<Text>{formatMessage(body)}</Text>\n\t\t\t\t\t\t</SpotlightBody>\n\t\t\t\t\t\t<SpotlightFooter>\n\t\t\t\t\t\t\t<SpotlightActions>\n\t\t\t\t\t\t\t\t<SpotlightPrimaryAction onClick={onClick}>\n\t\t\t\t\t\t\t\t\t{formatMessage(dismiss)}\n\t\t\t\t\t\t\t\t</SpotlightPrimaryAction>\n\t\t\t\t\t\t\t</SpotlightActions>\n\t\t\t\t\t\t</SpotlightFooter>\n\t\t\t\t\t</SpotlightCard>\n\t\t\t\t</PopoverContent>\n\t\t\t</ChoreographedComponent>\n\t\t</PopoverProvider>\n\t);\n};",
     explanation: "Key changes when migrating a single step spotlight:\n- Replace JiraSpotlight with ChoreographedComponent from '@atlassian/jira-spotlight'.\n- PopoverProvider maintains internal Spotlight state.\n- Replace SpotlightTarget with PopoverTarget - wraps the element to highlight\n- Replace Spotlight with PopoverContent containing SpotlightCard - controls visibility and positioning\n- 'heading' becomes SpotlightHeadline inside SpotlightHeader\n- 'actions' becomes SpotlightActions with SpotlightPrimaryAction (and optionally SpotlightSecondaryAction)\n- 'body' content moves into SpotlightBody wrapped with Text component\n- Add SpotlightDismissControl inside SpotlightControls for the close button\n- The 'target' and/or 'targetName' prop is replaced with PopoverTarget directly wrapping the target element\n- 'dialogPlacement' prop becomes 'placement' on PopoverContent. Mapping: \"top right\" \u2192 \"top-start\", \"top center\" \u2192 \"top\", \"top left\" \u2192 \"top-end\", \"right bottom\" \u2192 \"right-start\", \"right middle\" \u2192 \"right-start | right-end\", \"right top\" \u2192 \"right-end\", \"bottom left\" \u2192 \"bottom-end\", \"bottom center\" \u2192 \"bottom\", \"bottom right\" \u2192 \"bottom-start\", \"left top\" \u2192 \"left-end\", \"left middle\" \u2192 \"left-start | left-end\", \"left bottom\" \u2192 \"left-start\"'"
   }],
   bestPractices: [],

package/dist/esm/tools/migration-guides/migrations/onboarding-multi-step.js

@@ -9,7 +9,7 @@ export var onboardingMultiStep = {
     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 from '@atlaskit/button/default/button';\nimport IconButton from '@atlaskit/button/icon/button';\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 from '@atlaskit/button/default/button';\nimport IconButton from '@atlaskit/button/icon/button';\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};",
+    after: "import React, { useState } from 'react';\nimport Button from '@atlaskit/button/default/button';\nimport IconButton from '@atlaskit/button/icon/button';\nimport CommentAddIcon from '@atlaskit/icon/core/comment-add';\nimport CopyIcon from '@atlaskit/icon/core/copy';\nimport { Text } from '@atlaskit/primitives/compiled';\nimport { PopoverContent } from '@atlaskit/spotlight/popover-content';\nimport { PopoverProvider } from '@atlaskit/spotlight/popover-provider';\nimport { PopoverTarget } from '@atlaskit/spotlight/popover-target';\nimport { SpotlightActions } from '@atlaskit/spotlight/actions';\nimport { SpotlightBody } from '@atlaskit/spotlight/body';\nimport { SpotlightCard } from '@atlaskit/spotlight/card';\nimport { SpotlightControls } from '@atlaskit/spotlight/controls';\nimport { SpotlightDismissControl } from '@atlaskit/spotlight/dismiss-control';\nimport { SpotlightFooter } from '@atlaskit/spotlight/footer';\nimport { SpotlightHeader } from '@atlaskit/spotlight/header';\nimport { SpotlightHeadline } from '@atlaskit/spotlight/headline';\nimport { SpotlightPrimaryAction } from '@atlaskit/spotlight/primary-action';\nimport { SpotlightSecondaryAction } from '@atlaskit/spotlight/secondary-action';\nimport { SpotlightStepCount } from '@atlaskit/spotlight/step-count';\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:\n- SpotlightManager coordinated multiple spotlights in a tour. PopoverProvider manages internal state for a single spotlight.\n- Each target gets its own PopoverProvider > PopoverTarget > PopoverContent structure\n- The spotlight array pattern is replaced with individual SpotlightCard components per target\n- Control visibility with isVisible={currentStep === n} on each PopoverContent\n- Add SpotlightStepCount component in SpotlightFooter to show progress (e.g., \"1 of 3\")\n- Use SpotlightSecondaryAction for \"Back\" buttons instead of appearance: 'subtle' in the actions array\n- Use SpotlightPrimaryAction for \"Next\" and \"Done\" buttons\n- The renderActiveSpotlight pattern is no longer needed - visibility is controlled declaratively\n- Navigation functions use Math.max/Math.min to bound the step range safely\n- All other migration changes from single step spotlight migration guide apply."
   }],
   bestPractices: ['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.'],

package/dist/esm/tools/migration-guides/migrations/onboarding-single-step.js

@@ -9,7 +9,7 @@ export var onboardingSingleStep = {
     title: 'Migrate single step spotlight',
     description: 'Replace SpotlightTarget, and Spotlight with the new compositional @atlaskit/spotlight components',
     before: "\n// file1.tsx\nimport React, { useState } from 'react';\nimport Button from '@atlaskit/button/default/button';\nimport { Spotlight } from '@atlaskit/onboarding';\n\nconst OnboardingSpotlight = () => {\n  const [isSpotlightActive, setIsSpotlightActive] = useState(true);\n  const start = () => setIsSpotlightActive(true);\n  const end = () => setIsSpotlightActive(false);\n\n  return (\n\t\t{isSpotlightActive && (\n\t\t\t<Spotlight\n\t\t\t\tdialogPlacement='bottom right'\n\t\t\t\tactions={[\n\t\t\t\t\t{\n\t\t\t\t\t\tonClick: end,\n\t\t\t\t\t\ttext: 'Got it',\n\t\t\t\t\t},\n\t\t\t\t]}\n\t\t\t\theading=\"Feature Heading\"\n\t\t\t\ttarget=\"my-target\"\n\t\t\t>\n\t\t\t\tThis is the spotlight body content describing the feature.\n\t\t\t</Spotlight>\n\t\t)}\n  );\n};\n\n// file2.tsx\nimport React from 'react';\nimport Button from '@atlaskit/button/default/button';\nimport { Spotlight } from '@atlaskit/onboarding';\n\nconst SomeFeature = () => {\n\n  return (\n\t\t<SpotlightTarget name=\"my-target\">\n\t\t\t<Button>Target Element</Button>\n\t\t</SpotlightTarget>\n  );\n};\n",
-    after: "\n// file2.tsx -- the Spotlight has been co-located to the targeted element.\nimport React, { useState } from 'react';\nimport Button from '@atlaskit/button/default/button';\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};",
+    after: "\n// file2.tsx -- the Spotlight has been co-located to the targeted element.\nimport React, { useState } from 'react';\nimport Button from '@atlaskit/button/default/button';\nimport { Text } from '@atlaskit/primitives/compiled';\nimport { PopoverContent } from '@atlaskit/spotlight/popover-content';\nimport { PopoverProvider } from '@atlaskit/spotlight/popover-provider';\nimport { PopoverTarget } from '@atlaskit/spotlight/popover-target';\nimport { SpotlightActions } from '@atlaskit/spotlight/actions';\nimport { SpotlightBody } from '@atlaskit/spotlight/body';\nimport { SpotlightCard } from '@atlaskit/spotlight/card';\nimport { SpotlightControls } from '@atlaskit/spotlight/controls';\nimport { SpotlightDismissControl } from '@atlaskit/spotlight/dismiss-control';\nimport { SpotlightFooter } from '@atlaskit/spotlight/footer';\nimport { SpotlightHeader } from '@atlaskit/spotlight/header';\nimport { SpotlightHeadline } from '@atlaskit/spotlight/headline';\nimport { SpotlightPrimaryAction } from '@atlaskit/spotlight/primary-action';\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:\n- Do not use this migration guide for JiraSpotlight. Use 'jira-spotlight' instead.\n- PopoverProvider maintains internal Spotlight state. SpotlightManager coordinated multiple @atlaskit/onboarding usages and is no longer needed.\n- Replace SpotlightTarget with PopoverTarget - wraps the element to highlight\n- Replace Spotlight with PopoverContent containing SpotlightCard - controls visibility and positioning\n- The 'heading' prop becomes SpotlightHeadline inside SpotlightHeader\n- The 'actions' array becomes SpotlightActions with SpotlightPrimaryAction (and optionally SpotlightSecondaryAction)\n- The children content moves into SpotlightBody wrapped with Text component\n- Add SpotlightDismissControl inside SpotlightControls for the close button\n- The 'target' and/or 'targetName' prop is replaced with PopoverTarget directly wrapping the target element\n- The 'dialogPlacement' prop becomes 'placement' on PopoverContent. Mapping: \"top right\" \u2192 \"top-start\", \"top center\" \u2192 \"top\", \"top left\" \u2192 \"top-end\", \"right bottom\" \u2192 \"right-start\", \"right middle\" \u2192 \"right-start | right-end\", \"right top\" \u2192 \"right-end\", \"bottom left\" \u2192 \"bottom-end\", \"bottom center\" \u2192 \"bottom\", \"bottom right\" \u2192 \"bottom-start\", \"left top\" \u2192 \"left-end\", \"left middle\" \u2192 \"left-start | left-end\", \"left bottom\" \u2192 \"left-start\"'"
   }],
   bestPractices: ['PopoverTarget should wrap exactly one child element that will be highlighted', 'Always include SpotlightDismissControl for accessibility - allows users to dismiss via close button', 'SpotlightPrimaryAction is required and wraps the main CTA button', 'Wrap body text content in the Text component from @atlaskit/primitives/compiled'],

package/dist/esm/tools/migration-guides/migrations/onboarding-with-motion.js

@@ -9,7 +9,7 @@ export var onboardingWithMotion = {
     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/default/button';\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/default/button';\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};",
+    after: "import React, { useState } from 'react';\nimport Button from '@atlaskit/button/default/button';\nimport { FadeIn } from '@atlaskit/motion';\nimport { Text } from '@atlaskit/primitives/compiled';\nimport { PopoverContent } from '@atlaskit/spotlight/popover-content';\nimport { PopoverProvider } from '@atlaskit/spotlight/popover-provider';\nimport { PopoverTarget } from '@atlaskit/spotlight/popover-target';\nimport { SpotlightActions } from '@atlaskit/spotlight/actions';\nimport { SpotlightBody } from '@atlaskit/spotlight/body';\nimport { SpotlightCard } from '@atlaskit/spotlight/card';\nimport { SpotlightControls } from '@atlaskit/spotlight/controls';\nimport { SpotlightDismissControl } from '@atlaskit/spotlight/dismiss-control';\nimport { SpotlightFooter } from '@atlaskit/spotlight/footer';\nimport { SpotlightHeader } from '@atlaskit/spotlight/header';\nimport { SpotlightHeadline } from '@atlaskit/spotlight/headline';\nimport { SpotlightPrimaryAction } from '@atlaskit/spotlight/primary-action';\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:\n- Replace SpotlightTransition with FadeIn from @atlaskit/motion\n- Import FadeIn from '@atlaskit/motion' instead of SpotlightTransition from '@atlaskit/onboarding'\n- FadeIn uses a render props pattern - wrap content in {(props) => <div {...props}>...</div>}\n- The entranceDirection prop controls animation direction: 'left', 'right', 'top', or 'bottom'\n- All other migration changes from single step spotlight apply (PopoverProvider, compositional components, etc.)"
   }],
   bestPractices: ['Choose entranceDirection based on spotlight placement (e.g., "left" for right-placed spotlights)', 'Motion is optional - only add if the original onboarding spotlight used SpotlightTransition for entrance effects'],

package/dist/esm/tools/suggest-a11y-fixes/fixes.js

@@ -7,7 +7,7 @@ export var accessibilityFixes = {
       title: 'Use aria-label prop',
       description: 'Add aria-label for icon-only buttons',
       before: "<button onClick={handleClose}>\n  <CloseIcon />\n</button>",
-      after: "import { Button } from '@atlaskit/button';\n\n<Button aria-label=\"Close dialog\" onClick={handleClose}>\n  <CloseIcon />\n</Button>",
+      after: "import Button from '@atlaskit/button/default/button';\n\n<Button aria-label=\"Close dialog\" onClick={handleClose}>\n  <CloseIcon />\n</Button>",
       explanation: 'The aria-label provides a text description for screen readers while keeping the visual design clean.'
     }, {
       title: 'Use VisuallyHidden component',
@@ -301,7 +301,7 @@ export var accessibilityFixes = {
       title: 'Add adequate spacing',
       description: 'Ensure sufficient space between interactive elements',
       before: "<div>\n  <Button>Save</Button><Button>Cancel</Button>\n</div>",
-      after: "import { Stack } from '@atlaskit/stack';\n\n<Stack direction=\"horizontal\" space=\"space.100\">\n  <Button>Save</Button>\n  <Button>Cancel</Button>\n</Stack>",
+      after: "import { Inline } from '@atlaskit/primitives/compiled/inline';\n\n<Inline space=\"space.100\">\n  <Button>Save</Button>\n  <Button>Cancel</Button>\n</Inline>",
       explanation: 'Adequate spacing prevents accidental activation of adjacent controls.'
     }],
     bestPractices: ['Minimum 24x24 CSS pixels for touch targets', 'Provide adequate spacing between targets', 'Use ADS components that meet size requirements', 'Test on actual devices']

package/dist/types/tools/get-all-components/components.codegen.d.ts

@@ -3,7 +3,7 @@
  *
  * Structured content components from design-system *.docs.tsx files
  *
- * @codegen <<SignedSource::1198328c4df24125d34dda1b710ce3bd>>
+ * @codegen <<SignedSource::590b36be3f260295a7a348390a365a0a>>
  * @codegenCommand yarn workspace @af/ads-ai-tooling codegen
  */
 import type { ComponentMcpPayload } from './types';

package/dist/types/tools/get-atlaskit-components/atlaskit-components.codegen.d.ts

@@ -3,7 +3,7 @@
  *
  * Structured content components from *.docs.tsx files outside of design-system
  *
- * @codegen <<SignedSource::2c0bc13b400f853fe424766c56bd87ec>>
+ * @codegen <<SignedSource::7b96bd3e03cffc1a25343fd2a8608191>>
  * @codegenCommand yarn workspace @af/ads-ai-tooling codegen
  */
 import type { ComponentMcpPayload } from '../get-all-components/types';

package/dist/types/tools/get-atlaskit-hooks/atlaskit-hooks.codegen.d.ts

@@ -3,7 +3,7 @@
  *
  * Structured content hooks from design-system *.docs.tsx files
  *
- * @codegen <<SignedSource::eff635a23ccace1d4e4c6ef6efc21551>>
+ * @codegen <<SignedSource::8622cd207ede8e8e02275cd9e0dfc3cc>>
  * @codegenCommand yarn workspace @af/ads-ai-tooling codegen
  */
 import type { HookMcpPayload } from './types';

package/dist/types/tools/get-atlaskit-utilities/atlaskit-utilities.codegen.d.ts

@@ -3,7 +3,7 @@
  *
  * Structured content utilities from design-system *.docs.tsx files
  *
- * @codegen <<SignedSource::359ec42ca1d2584fe22747b346c596eb>>
+ * @codegen <<SignedSource::587058ae450ce5f947bac19798e23e51>>
  * @codegenCommand yarn workspace @af/ads-ai-tooling codegen
  */
 import type { UtilityMcpPayload } from './types';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/ads-mcp",
-	"version": "1.10.1",
+	"version": "1.10.3",
 	"description": "The official Atlassian Design System MCP server to develop apps and user interfaces matching the Atlassian style.",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -13,7 +13,7 @@
 	},
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
 	"scripts": {
-		"ak-postbuild": "yarn workspace @atlassian/structured-docs build",
+		"ak-postbuild": "afm workspace @atlassian/structured-docs build",
 		"prepare": "yarn ak-postbuild"
 	},
 	"bin": "index.js",
@@ -21,10 +21,10 @@
 	"types": "dist/types/index.d.ts",
 	"atlaskit:src": "src/index.tsx",
 	"dependencies": {
-		"@atlaskit/icon": "^37.5.0",
-		"@atlaskit/icon-lab": "^7.7.0",
-		"@atlaskit/platform-feature-flags": "^2.1.0",
-		"@atlaskit/tokens": "^16.9.0",
+		"@atlaskit/icon": "^37.6.0",
+		"@atlaskit/icon-lab": "^7.8.0",
+		"@atlaskit/platform-feature-flags": "^2.2.0",
+		"@atlaskit/tokens": "^16.12.0",
 		"@axe-core/playwright": "^4.11.1",
 		"@axe-core/puppeteer": "^4.11.1",
 		"@babel/runtime": "^7.0.0",
@@ -32,7 +32,7 @@
 		"axe-core": "^4.11.1",
 		"esbuild-register": "^3.4.1",
 		"fuse.js": "^6.6.2",
-		"jsdom": "^25.0.0",
+		"jsdom": "26.1.0",
 		"playwright": "1.57.0",
 		"puppeteer": "13.7.0",
 		"zod": "^3.23.8",
@@ -42,6 +42,6 @@
 		"@atlassiansox/analytics-node-client": "^4.0.0"
 	},
 	"devDependencies": {
-		"@atlassian/feature-flags-test-utils": "^1.2.0"
+		"@atlassian/feature-flags-test-utils": "^1.3.0"
 	}
 }