@atlaskit/ads-mcp 1.11.5 → 1.11.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @atlaskit/ads-mcp
 
+## 1.11.7
+
+### Patch Changes
+
+- [`d3100c1dd0a33`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/d3100c1dd0a33) -
+  Use authored elevation guidance for surface selection, interaction states, drag restoration,
+  scroll boundaries, and nested overlay layering. Improve foundation retrieval for container
+  surfaces and popups inside modals.
+
+## 1.11.6
+
+### Patch Changes
+
+- [`c149c3839b565`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/c149c3839b565) -
+  Add EntryPoint migration guidance to the ADS MCP registry.
+
 ## 1.11.5
 
 ### Patch Changes

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

@@ -9,7 +9,7 @@ exports.guidelinesStructuredContent = void 0;
  *
  * Structured content for authored agent guidelines and design-system-docs foundations content.
  *
- * @codegen <<SignedSource::425b1c773867acafd317f203d71685ac>>
+ * @codegen <<SignedSource::ff17b8b82e5f2c80a40be5b39e323eab>>
  * @codegenCommand yarn build structured-docs
  */
 
@@ -70,8 +70,9 @@ var guidelinesStructuredContent = exports.guidelinesStructuredContent = [{
   content: "<SectionMessage title=\"\">\n\tThe guidance on this page relates to voice and tone for user interfaces and app experiences. For\n\tbroader guidance, including marketing, view{' '}\n\t<Link href=\"https://go.atlassian.com/voice-tone\">Brand Voice and Tone (Atlassians only)</Link>\n</SectionMessage>\n\nOur voice is essentially Atlassian's personality and is made up of the following traits:\n\n- Bold\n- Optimistic\n- Practical, with a wink\n\nTone is how we express Atlassian’s voice, and it should change depending on the situation the user\nis in (for example, receiving an error versus successfully completing a project).\n\nWhether it’s writing content for our apps, user interface, websites, or communications, you should\nfollow our voice and tone guidelines to ensure people recognize they’re interacting with Atlassian\nwherever they are.\n\n## How to apply Atlassian’s personality traits\n\nHow each trait is applied should depend on the audience and situation. Use these questions to help\nyou work out the right balance:\n\n- What is the emotional state of the user when they encounter your content or solution, and where\n  are they on their journey?\n- How might our personality traits enhance a moment of celebration?\n- How might our personality traits diffuse a moment of frustration or pain?\n\n<br></br>\n\n### Bold\n\nWhen we say bold, it’s about motivating teams with the right amount of support at the right time to\ndo their best work.\n\n- Offer best practices or just enough help to get the work started.\n- Give accurate information so people can make educated decisions.\n- Understand a person's struggles and desired outcomes, and give just enough information so someone\n  can get where they need to go.\n\n#### When to be more bold\n\n- Person is feeling: confident, interested, trust, anticipation.\n- Examples: power users, admins, daily users.\n\n#### When to be less bold\n\n- Person is feeling: apprehension, confusion, annoyance, fear, anger.\n- Examples: new users, trial users, when introducing a new concept, feature, or app.\n\n<br></br>\n\n### Optimistic\n\nWriting with optimism is understanding where in the journey someone is and highlighting the key\npoints that will help them along the way.\n\n- Focus on the most important bits the person needs in the moment. This gives people confidence in\n  our apps.\n- Weave a consistent story across apps and use the same vocabulary across all messaging.\n- Create a seamless flow across experiences. This lets people know that no matter where they’re\n  working, they can expect a familiar, consistent experience.\n- Keep people in the loop by informing them of relevant features, apps, and opportunities for\n  success.\n\n#### When to be more optimistic\n\n- Person is feeling: ambitious, inspired, curious, admiration.\n- Examples: power users, admins, daily users.\n\n#### When to be less optimistic\n\n- Person is feeling: anticipation, unsupported, confused, uncertain.\n- Examples: someone is new to Atlassian, trial users, when introducing a new concept, feature, or\n  app.\n\n<br></br>\n\n### Practical, with a wink\n\nOur practical side means getting to the point and being direct and concise.\n\n- Be on the lookout for opportunities where we can offer a helping hand.\n- Write clear, accurate, and concise content that makes interfaces more usable and consistent — and\n  builds trust.\n- Write content that is understandable for anyone, anywhere, regardless of their culture or language\n  so that everyone feels part of the team.\n\nThe ‘with a wink’ part of this trait needs more discernment when applying it to UI and app content\n(as opposed to marketing content) and remember that it isn’t always appropriate to use. Be mindful\nof where someone is at and what they might be experiencing before going beyond the practical.\n\n#### When to be more practical\n\n- Person is feeling: overwhelmed, unsure, hesitant, stressed.\n- Examples: people with deadlines or being blocked by errors, supporting new or occasional users,\n  introducing new features.\n\n#### When you can add the ‘wink’\n\n- Person is feeling: successful, joy, proud, relief.\n- Examples: power users, during social interactions, success messages.\n\n<br></br>\n\n## Voice and tone principles\n\nAtlassian's personality traits help keep our voice consistent across a range of different customer\nand app experiences. We can better support the full spectrum of experience for people by applying\nthe following principles.\n\nOur voice and tone principles:\n\n- [Inform to build trust](https://atlassian.design/foundations/content/voice-tone#inform-to-build-trust)\n- [Empower to inspire action](https://atlassian.design/foundations/content/voice-tone#empower-to-inspire-action)\n- [Encourage people along the path](https://atlassian.design/foundations/content/voice-tone#encourage-people-along-the-path)\n- [Motivate by showing possibilities](https://atlassian.design/foundations/content/voice-tone#motivate-by-showing-possibilities)\n- [Satisfy by meeting expectations](https://atlassian.design/foundations/content/voice-tone#satisfy-by-meeting-expectations)\n- [Delight with unexpectedly pleasing experiences](https://atlassian.design/foundations/content/voice-tone#delight-with-unexpectedly-pleasing-experiences)\n\n<br></br>\n\n### Inform to build trust\n\nBe open and clear about the experience.\n\n- Tell people only what they need to know in the moment and nothing more.\n- Be aware of when a user may be new or confused, and tone down the boldness by being more\n  prescriptive.\n- Let people know where they are in their journey and what this part of the app will do.\n\nWrite as a knowledgable member of the team. Show up at the right time and be open, humble, and warm.\nOffer direction for the most appropriate next steps.\n\n#### Places to use 'Inform to build trust'\n\n- In-app: [flags](https://atlassian.design/components/flag/usage),\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages),\n  and [spotlights](https://atlassian.design/components/spotlight/usage)\n- New features or apps\n- In confusing, warning, or error states\n\n<br></br>\n\n### Empower to inspire action\n\nEducate where people need it most.\n\n- Offer opportunities to learn at pivotal times to empower people to move in the right direction.\n- Give best practices and recommendations for next steps.\n- Suggest ways to improve or make decisions.\n- Let people know that Atlassian and fellow community members are available to help them make\n  decisions.\n\nWrite as if you are educating. You are a teacher with empathy and an understanding of what it’s like\nto be in the weeds. You expect your audience to have a basic understanding.\n\n#### Places to use 'Empower to inspire action'\n\n- In-app: [spotlights](https://atlassian.design/components/spotlight/usage) and\n  [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- When something requires an action\n- When guidance is needed\n\n<br></br>\n\n### Encourage people along the path\n\nInspire by providing support in the right place. Be consistent and dependable.\n\n- Offer waypoints, help, and support if people are feeling confused or frustrated at points along\n  their journey.\n- Be human: give guidance, support, and encouragement along the way.\n- Guide people by revealing information gracefully. Let them know they’re on the right path, they\n  aren’t alone, and that delivering projects and building teams can be challenging.\n\nWrite in an upbeat, friendly way. Acknowledge the opportunities in the here-and-now and walk through\nit with them.\n\n#### Places to use 'Encourage people along the path'\n\n- In-app:\n  [information messages](https://atlassian.design/foundations/content/designing-messages/info-messages),\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages),\n  and [section messages](https://atlassian.design/components/section-message/usage)\n- When something requires an action\n\n<br></br>\n\n### Motivate by showing possibilities\n\nProvide incentive and enthusiasm for continued growth.\n\n- Consider why someone would want to do this.\n- Show the possibilities of what can be accomplished by giving examples of how other people\n  accomplish the same task or by presenting the ideal state.\n- Describe the end result by giving expert testimony or offer opportunities for advanced knowledge.\n\nWrite like an expert. Focus more on the solution than on the problem. Show people the possible\nbenefits.\n\n#### Places to use 'Motivate by showing possibilities'\n\n- In-app: [spotlights](https://atlassian.design/components/spotlight/usage) and\n  [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- Educational opportunities — it's a chance to give best practices, and tips and tricks\n\n<br></br>\n\n### Satisfy by meeting expectations\n\nGive people what they need.\n\n- All of our content should be practical at a minimum.\n- Provide quick and thorough answers, guidance, actions, and instructions (rather than trying to\n  lead, inspire, motivate, delight, or encourage).\n- Simply tell people what they need to know and get out of the way.\n\nWrite as if you are explaining to your friend how to travel somewhere you’ve visited regularly.\n\n#### Places to use 'Satisfy by meeting expectations'\n\n- In-app:\n  [warning messages](https://atlassian.design/foundations/content/designing-messages/warning-messages),\n  [information messages](https://atlassian.design/foundations/content/designing-messages/info-messages),\n  and\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages)\n- Across all UI and app content\n\n<br></br>\n\n### Delight with unexpectedly pleasing experiences\n\nYou can deliver appropriate delight (a ‘wink’) by celebrating success or progress, but only once\nyou’ve built trust. Don’t overdo it. \n\n- Delight means little flourishes, not humor or being cheeky.\n- Always ask yourself what someone might be feeling at that moment and if delight is appropriate.\n  Also question whether it will be understood or appreciated by our global audience.\n- Think about the timing and how frequently a user will see this. Once may amuse, but a dozen times\n  may annoy.\n\n#### Places to use ‘Delight with unexpectedly pleasing experiences’\n\n- In-app:\n  [success messages](https://atlassian.design/foundations/content/designing-messages/success-messages)\n  and [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- Social interactions, while introducing new experiences",
   keywords: ['voice', 'tone', 'writing', 'content', 'brand']
 }, {
-  content: 'import {\n\tTokenElevationBackgroundChangeExample,\n\tTokenElevationChangeExample,\n} from \'../../../components/interactive-elevations\';\n\n\n\n\n\nElevations are the layered surfaces that form the foundation of the UI. They create a blank canvas\nwhere other UI will be placed, such as text, icons, backgrounds, and borders.\n\n![](./_assets/elevation-layers.png)\n\nMost elevations consist of surfaces and shadows. Together, surfaces and shadows give the impression\nof lift or depth. Elevations can guide focus through layering, or indicate that the UI can be\nscrolled, slid, or dragged.\n\n## Applying elevations\n\nThe elevations use [design tokens](https://atlassian.design/tokens/design-tokens) to apply different\nsurface levels. The highest two elevation surfaces, raised and overlay, are paired with shadows to\ncreate more depth.\n\n![](./_assets/applying-elevations-light.png)\n\n### Elevations in dark theme\n\nShadows can be harder to see in dark mode, so dark mode elevations also rely on different surface\ncolors. Imagine that the surfaces are distantly lit from the front — the higher the elevation, the\nlighter the surface looks.\n\n![](./_assets/applying-elevations-dark-1.png)\n\nRaised and overlay surfaces are still paired with shadows for added depth and consistency in dark\nmode.\n\n![](./_assets/applying-elevations-dark-2.png)\n\n## Types of elevations\n\nThere are four basic elevation levels:\n\n1. [Sunken](#sunken)\n2. [Default](#default)\n3. [Raised](#raised)\n4. [Overlay](#overlay)\n\nThere is also one "[overflow](#overflow)" elevation for special cases.\n\n### Sunken\n\nSunken is the lowest elevation available. The sunken surface creates a backdrop (or well) where\nother content sits. Columns on a Kanban board are a good example of the sunken elevation.\n\nOnly use sunken surfaces on the default surface level. Don’t apply sunken elevations on raised or\noverlay elevations. To differentiate areas of the UI in other ways, use whitespace or borders\ninstead.\n\n![](./_assets/elevation-sunken-1.png)\n\n#### Using `elevation.surface.sunken` vs `color.background.neutral`\n\nAlthough `elevation.surface.sunken` and `color.background.neutral` tokens may appear similar in\nlight mode, they behave differently in dark mode. Here are the main differences between the two:\n\n`elevation.surface.sunken` is an opaque (solid) token that darkens in both light and dark modes. Use\nthis token as a backdrop to group content or elements together (such as a kanban board) on the\ndefault surface.\n\n![](./_assets/elevation-sunken-2.png)\n\n`color.background.neutral` is a token that uses a transparent color. It darkens in light mode and\nlightens in dark mode. Use this token when you need the background to adapt to different elevations,\nwhich is relevant in dark mode since surfaces change depending on what elevation you’re on.\n\n![](./_assets/elevation-sunken-3.png)\n\n### Default\n\nThe default elevation is the baseline with respect to all other layers. It represents a flat UI\nsurface with no visual lift, such as a Confluence page.\n\nUse `elevation.surface` as the starting point for body content when building a UI. To create flat\ncards, pair with a border.\n\n![](./_assets/elevation-surface-1.png)\n\n### Raised\n\nRaised elevations sit slightly higher than default elevations. They are reserved for cards that can\nbe moved, such as Jira and Trello cards. In special circumstances, they can be used for cards as a\nway to provide additional heirarchy or emphasis.\n\nAlways pair `elevation.surface.raised` with `elevation.shadow.raised`. This is particularly\nimportant in dark mode, where raised surfaces are lighter to help differentiate elevations.\n\n![](./_assets/elevation-raised-1.png)\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tUse raised elevations intentionally. If using for emphasis, limit to one section or focal point\n\t\tof the screen.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tRaised elevations can create visual noise, so don’t use to group content when a border or white\n\t\tspace would suffice.\n\t</DoDont>\n</DoDontGrid>\n\n### Overlay\n\nOverlay is the highest elevation available. It is reserved for a UI that sits over another UI, such\nas modals, dialogs, dropdown menus, floating toolbars, and floating single-action buttons.\n\nAlways pair `elevation.surface.overlay` with `elevation.shadow.overlay`. This is important in dark\nmode, where overlay surfaces are lighter to help differentiate elevations.\n\nOverlays can stack on top of other overlays.\n\n![](./_assets/elevation-overlay-1.png)\n\n### Overflow\n\nOverflow is a shadow indicating content has [scrolled](#scrolled) outside a view. It can be used for\nvertical or horizontal scroll. An example of overflow shadows is the horizontal scroll in tables on\na Confluence page.\n\n![](./_assets/elevation-overflow-1.png)\n\nIf box shadows are not technically feasible, use the combination of\n`elevation.shadow.overflow.spread` and `elevation.shadow.overflow.perimeter` to replicate the\noverflow shadow.\n\n## Interaction states\n\n### Hovered and pressed\n\nElevations use surface color changes to communicate hovered and pressed states. Use the hovered and\npressed elevation tokens to create these visual changes.\n\n![](./_assets/elevation-hovered.png)\n\nTransitions between elevations can be used as an alternative to hovered and pressed tokens, but only\nfor default and raised elevations (not overlays):\n\n- Transition to overlay elevation on hover\n- Transition to raised elevation on press\n\nThis approach should be used sparingly to avoid excessive animation. It should not be used for very\nsmall UI, as elevation changes are harder to see than surface color changes at this size.\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tUse the recommended hovered and pressed tokens for interaction states on elevations.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tDon’t combine elevation transitions and hovered and pressed tokens for interactive states. Use\n\t\tone or the other.\n\t</DoDont>\n</DoDontGrid>\n\n#### Background change example\n\n<TokenElevationBackgroundChangeExample />\n\n#### Elevation change example\n\n<TokenElevationChangeExample />\n\n### Dragged\n\nUse the overlay elevation for any UI that is being dragged. Once moved, it returns to its original\nelevation.\n\n![](./_assets/elevation-dragged-1.png)\n\n### Scrolled\n\nWhen scrollable content exceeds the available area, a border or [overflow](#overflow) shadow can be\napplied at the point the content is cut off to indicate there is hidden content that can be scrolled\nback into view.\n\nA border is the default approach for scrolled content and can be seen in modal sticky headers and\nfooters, and top and side navigation.\n\n![](./_assets/elevation-scrolled.png)\n\n[Overflow](#overflow) shadows are reserved for experiences where a border might be easily missed,\nsuch as in very small UI or tables that use borders to separate cells.\n\nBoth approaches should apply the appropriate surface token where the content is being hidden.\n\n## All elevation tokens and values\n\nFor the full list of elevation design tokens and their values, see our\n[design token reference list](https://atlassian.design/components/tokens/all-tokens). Every token\ncomes with a description to help you ensure you’re using the correct one.\n\n## Best practices\n\n### Follow the recommended surface and shadow pairings\n\nRaised and overlay elevations have dedicated surface and shadow pairings.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: pairingDo, alt: \'\' }}>\n\t\tWhen creating elevations, always pair matching surface and shadow tokens.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: pairingDont, alt: \'\' }}>\n\t\tDon\'t mix different shadow and surface elevation tokens.\n\t</DoDont>\n</DoDontGrid>\n\n### Replace elevation surfaces with background colors only when required\n\nElevation surfaces use our\n[neutral palettes](https://atlassian.design/foundations/color#neutral-colors). If a different color\nis needed, surface tokens can be swapped for any solid background token. When using background\ntokens, align to the behavior of\n[interaction states for color tokens](https://atlassian.design/foundations/color#interaction-states).\n\n![](./_assets/background-colors.png)\n\n### Avoid excessive use of raised and overlay elevations\n\nThe shadows and surfaces of raised and overlay elevations can create busy UI if not applied\nintentionally. Follow the recommended guidance when considering these elevations.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: groupingDo, alt: \'\' }}>\n\t\tLimit the use of overlay elevations by grouping related buttons together in a floating toolbar\n\t\tif they are required to sit over another UI.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: groupingDont, alt: \'\' }}>\n\t\tDon’t have more than one floating button next to each other.\n\t</DoDont>\n</DoDontGrid>\n\n### Check contrast ratios\n\nAlways make sure your elevation and background choices are accessible.\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tCheck the contrast ratio for UI on overlay surfaces in dark mode to ensure it meets\n\t\taccessibility requirements.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tDon\'t assume that because UI is accessible in light mode, it will be in dark mode. Some UI may\n\t\tneed tweaking.\n\t</DoDont>\n</DoDontGrid>\n\n## Z-index\n\nThe z-index determines the stacking order of elements. Elements with a higher z-index always sit in\nfront of elements with a lower z-index.\n\nDifferent UI can have the same elevation style, but each UI should apply a different z-index to\nindicate the layer(s) order in a stack (or where the elements touch).\n\n| Z-index | Example usage                                                                     | Elevation level |\n| ------- | --------------------------------------------------------------------------------- | --------------- |\n| 100     | None                                                                              | None            |\n| 200     | [Atlassian navigation](https://atlassian.design/components/atlassian-navigation/) | Default         |\n| 300     | [Inline dialog](https://atlassian.design/components/inline-dialog/)               | Overlay         |\n| 400     | [Popup](https://atlassian.design/components/popup/)                               | Overlay         |\n| 500     | [Blanket](https://atlassian.design/components/blanket/)                           | None            |\n| 510     | [Modal](https://atlassian.design/components/modal-dialog/)                        | Overlay         |\n| 600     | [Flag](https://atlassian.design/components/flag/)                                 | Overlay         |\n| 700     | [Spotlight](https://atlassian.design/components/onboarding/)                      | Overlay         |\n| 800     | [Tooltip](https://atlassian.design/components/tooltip/)                           | None            |\n\n## Related\n\n- Learn about the basics of [design tokens](https://atlassian.design/tokens/design-tokens).\n- See the list of [all design tokens](https://atlassian.design/components/tokens/all-tokens) for\n  full descriptions and values for all tokens.',
-  keywords: ['elevation', 'shadow', 'depth', 'z-index', 'layering', 'design tokens']
+  content: '# Elevation\n\nUse elevation to choose structural surfaces, visual depth, and scroll boundaries for Atlassian UI.\nIdentify the element’s role, host surface, and whether it is interactive. Preserve valid existing\ntreatment; reuse the ADS component’s built-in appearance before styling custom UI. For example,\nModal and Popup own their floating treatment. Consult the selected component before customization;\navoid adding a second shadow or elevated wrapper.\n\nFor custom UI, choose the resting surface and separation first, then derive interaction and drag\nstates. During review, explain the role that justifies any change and identify unresolved host or\ncomponent dependencies.\n\nElevations provide a canvas for text, icons, backgrounds, and borders. Surfaces and shadows\ncommunicate lift or depth and can indicate movable or scrollable content. They do not establish\nkeyboard focus, selection, or stacking order.\n\n## Choose the surface from its purpose\n\nThere are four basic elevation levels: sunken, default, raised, and overlay. Overflow is a special\nshadow for scroll boundaries.\n\n| Purpose                      | Surface                       | Separation or shadow                       |\n| ---------------------------- | ----------------------------- | ------------------------------------------ |\n| Primary page or flat content | `elevation.surface`           | Whitespace; `color.border` for flat cards  |\n| Neutral grouping             | `elevation.surface.container` | Container background; boundary when needed |\n| Recessed grouping on default | `elevation.surface.sunken`    | Recessed backdrop, such as a Kanban column |\n| Movable card                 | `elevation.surface.raised`    | `elevation.shadow.raised`                  |\n| UI floating over other UI    | `elevation.surface.overlay`   | `elevation.shadow.overlay`                 |\n\nDefault is the baseline for page content. A container is a grouping treatment, not another elevation\nlevel. Clickability alone does not require raised elevation.\n\nReserve raised elevation for movable cards. In special circumstances, use it for emphasis, limited\nto one section or focal point. Prefer whitespace, borders, or container backgrounds for ordinary\ngrouping; excessive shadows create visual noise.\n\nOverlay is the highest elevation, for modals, dialogs, dropdown menus, floating toolbars, and\nfloating single-action buttons. Overlays can stack on other overlays. Group related floating actions\nin a floating toolbar; do not place more than one floating button next to another.\n\nAlways pair raised and overlay surfaces with their matching shadows. Do not mix surface and shadow\nlevels. These pairings remain necessary in dark mode.\n\n## Keep interaction treatment consistent\n\nUse the surface’s own hovered and pressed variants when the surface itself is interactive. Apply\nthem to the interactive element; containing controls does not make the surrounding page or group\ninteractive.\n\n| Resting surface               | Hovered surface                       | Pressed surface                       | Shadow                     |\n| ----------------------------- | ------------------------------------- | ------------------------------------- | -------------------------- |\n| `elevation.surface`           | `elevation.surface.hovered`           | `elevation.surface.pressed`           | None                       |\n| `elevation.surface.container` | `elevation.surface.container.hovered` | `elevation.surface.container.pressed` | None                       |\n| `elevation.surface.raised`    | `elevation.surface.raised.hovered`    | `elevation.surface.raised.pressed`    | `elevation.shadow.raised`  |\n| `elevation.surface.overlay`   | `elevation.surface.overlay.hovered`   | `elevation.surface.overlay.pressed`   | `elevation.shadow.overlay` |\n\nA background change does not require an elevation change. The catalog defines no hovered or pressed\nvariants for sunken surfaces; use the treatment of the controls inside them. Look up other\ncombinations rather than constructing token names.\n\nElevation transitions are an alternative only for default and raised surfaces, never overlays:\ntransition to overlay surface and shadow on hover, then raised surface and shadow on press. Use this\nsparingly to avoid excessive animation. Do not use it for very small UI, where surface color changes\nare easier to see. Choose either elevation transitions or hovered/pressed surface tokens; do not\ncombine them. Follow applicable motion and reduced-motion guidance.\n\nUse overlay elevation for any UI being dragged, with its matching surface and shadow. Restore the\noriginal elevation when the drag completes or is cancelled. Follow the drag component’s movement and\naccessibility behavior.\n\nPreserve selection and keyboard-focus cues during hover and press; consult color guidance for those\ntreatments.\n\n## Respect nesting and theme behavior\n\nUse sunken surfaces only on the default elevation. Within raised or overlay surfaces, distinguish\nsections with whitespace or borders.\n\nIn dark mode, shadows are harder to see, so higher elevations also use lighter surface colors. Think\nof surfaces lit from the front: greater height makes the surface appear lighter. A shadow alone does\nnot reproduce raised or overlay treatment. Use tokens in each theme rather than copying light-theme\ncolor values.\n\nAlthough they can look similar in light mode, these backgrounds behave differently:\n\n- `elevation.surface.sunken` is opaque and darkens in both themes. Use it as a recessed backdrop for\n  grouped content on the default surface.\n- `color.background.neutral` is translucent: it darkens in light mode and lightens in dark mode,\n  adapting to the elevation beneath it.\n- `elevation.surface.container` provides neutral container grouping; its rendered appearance can\n  depend on the underlying surface.\n\nElevation surfaces use neutral palettes. Replace a surface with a solid background token only when a\ndifferent color is required. Follow the\n[color interaction-state guidance](https://atlassian.design/foundations/color#interaction-states)\nwhen using background tokens. Choose semantic and selected backgrounds for their meaning or state,\nnot merely because their color resembles a surface.\n\nCheck contrast against the rendered background, including underlying surfaces and overlapping\ntranslucent layers. Do not assume light-mode accessibility carries over to dark mode; check UI on\noverlay surfaces especially.\n\n## Indicate hidden scrollable content\n\nFor vertical or horizontal scrolling, indicate where content has scrolled out of view. Start with a\nborder at the cutoff, as in sticky modal headers and footers or top and side navigation. Apply the\nappropriate surface token where content is hidden.\n\nUse `elevation.shadow.overflow` when a border could be missed, such as very small UI or tables with\ncell borders. Place it at the relevant boundary, not decoratively around every scrollable container.\n\nIf the full overflow shadow is technically infeasible, pair `elevation.shadow.overflow.spread` with\n`elevation.shadow.overflow.perimeter` to replicate it. Follow their token descriptions.\n\n## Distinguish visual depth from stacking\n\nElevation surfaces and shadows communicate visual depth; they do not establish stacking order.\n\nUse the host component’s supported positioning and layering behavior. For components using the\nbrowser top layer, follow that component’s implementation rather than applying a numeric z-index\nrecipe. Check the installed version and migration guidance before changing existing layering.\n\nFor custom UI that uses numbered stacking, consult the\n[ADS z-index reference](https://atlassian.design/foundations/elevation/#z-index) and follow the\nrepository’s layering constraints. Do not derive layer values from elevation tokens or assume that\nincreasing z-index can place content above a top-layer surface.\n\nFor nested overlays, verify visibility, focus, and dismissal. Layering coordination does not replace\nthe host component’s accessibility behavior.\n\n## Retrieve only the missing detail\n\nWhen loaded through the ADS skill, follow its retrieval order.\n\nUse the guidance here first. If a detail is missing, use `atlas ads`; use ADS MCP only after a CLI\nerror, an empty result, or a missing capability. For tokens, search by purpose, then confirm the\nexact token:\n\n```sh\natlas ads search "<purpose>" --type token --limit 5 --json\natlas ads token elevation.surface --json\n```\n\nFor MCP fallback, use `ads_search_tokens` for token usage, `ads_search_components` for component\nAPIs, or `ads_get_a11y_guidelines` for accessibility; follow each tool’s exposed schema. Don’t\nrepeat a successful lookup through another route, fetch the full catalog, or construct tokens by\nappending state suffixes. If a detail remains unresolved, label it unverified and state what still\nneeds checking.\n\n## Verify the result\n\nCheck matching surface/shadow pairs, interaction variants, drag restoration on completion and\ncancellation, scroll indicators at the correct edge, and nested-layer visibility, focus, and\ndismissal. Check text, icons, focus indicators, and meaningful boundaries in supported themes and\nstates. Distinguish verified token names from tested behavior: screenshots alone do not establish\ndrag cancellation, focus, or dismissal.\n\n## Sources\n\nPrinciples: [ADS elevation](https://atlassian.design/foundations/elevation). Exact names, purposes,\nand values: the bundled elevation token reference or\n[design token reference list](https://atlassian.design/components/tokens/all-tokens). Use the\nselected component’s reference for its API and behavior.',
+  name: 'Elevation',
+  keywords: ['elevation', 'shadow', 'depth', 'z-index', 'layering', 'design tokens', 'surfaces', 'containers', 'cards', 'overlays', 'hover', 'press', 'drag', 'scroll boundaries', 'dark mode', 'popup inside modal', 'nested overlays']
 }, {
   content: '## Overview\n\nGrid is a system for arranging content consistently within the main content area of an Atlassian\napp.\n\nIn Figma, grids are set up using\n[Figma layout guides](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides).\nThe code equivalent is built using a combination of [primitives](/components/primitives/overview)\nsuch as box, stack, and inline.\n\nFor everything outside of the main content area, including navigation and panel, see the\n[layout component](/components/navigation-system/layout).\n\n<img\n\tsrc={layoutAnatomy}\n\tsrcDark={layoutAnatomyDark}\n\talt="Layout component anatomy showing the top nav, side nav, main, and panel. Grid sits within main."\n/>\n\n## Grid basics\n\nThe Figma grid component has three basic elements:\n\n- **Columns** divide the main content area into 12 equal parts for horizontal structure.\n- **Gutters** are the gaps between columns, providing consistent separation between content.\n- **Margins** are the empty space between the outer columns and the edge of the main content area.\n  They give content clear space.\n\n<img\n\tsrc={gridAnatomy}\n\tsrcDark={gridAnatomyDark}\n\talt="Figma grid component anatomy showing columns, gutters, and margins."\n/>\n\nAligning content to the columns supports a variety of layouts in the main content area. For example,\ncontent can span 12, 6, or 4 columns.\n\n<img\n\tsrc={columnSpan}\n\tsrcDark={columnSpanDark}\n\talt="Diagram showing content arrangement spanning 12, 6, or 4 grid columns."\n/>\n\nContent can also sit centered within the grid. For example, a centered block can span 8, 10, or 12\ncolumns.\n\n<img\n\tsrc={columnOffset}\n\tsrcDark={columnOffsetDark}\n\talt="Diagram showing content arrangement center-aligned on the grid and spanning 8, 10, or 12 grid columns."\n/>\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridBasicsDo,\n\t\t\turlDarkMode: gridBasicsDoDark,\n\t\t\talt: \'Example of content aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content within the app\'s main content area across any number of columns required.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridBasicsDont,\n\t\t\turlDarkMode: gridBasicsDontDark,\n\t\t\talt: \'Example of content overflowing into grid gutters and margins, breaking visual alignment.\',\n\t\t}}\n\t>\n\t\tDon\'t allow content to overflow into gutters or margins. This breaks visual alignment and makes\n\t\tlayouts unpredictable.\n\t</DoDont>\n</DoDontGrid>\n\n## How to choose what to align to the grid\n\nWithin the main content area, align content containers to the grid columns. Examples include cards,\nimages, text blocks, tables, and forms.\n\nSmall elements, like buttons and icons, do not need to align to this grid. Use\n[space tokens](/foundations/spacing#space-tokens) to manage the space between and within them\ninstead.\n\n<img\n\tsrc={spacingTokens}\n\tsrcDark={spacingTokensDark}\n\talt="Example showing cards aligned to grid columns. The horizontally placed input field and buttons, as well as the content within the card, do not align to the grid columns and are instead managed with space tokens."\n/>\n\nThe same applies within content containers. Only top-level containers need to align to the grid. Use\nspace tokens for the elements inside them, such as cards and table columns.\n\n<img\n\tsrc={contentContainers}\n\tsrcDark={contentContainersDark}\n\talt="Example showing kanban columns aligned to the grid, but the cards within them using space tokens."\n/>\n\nOverlays like modals, tooltips, and dropdown menus also sit outside the grid, as they float above\nthe page content.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: alignContentDo,\n\t\t\turlDarkMode: alignContentDoDark,\n\t\t\talt: \'Example of content containers aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content containers to our grid columns, such as cards, images, text blocks, tables, and\n\t\tforms.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: alignContentDont,\n\t\t\turlDarkMode: alignContentDontDark,\n\t\t\talt: \'Example of buttons and icons incorrectly aligned to the grid columns instead of using space tokens.\',\n\t\t}}\n\t>\n\t\tDon\'t align small elements, such as buttons or icons, to the grid. Instead, use space tokens to\n\t\tmanage their spacing.\n\t</DoDont>\n</DoDontGrid>\n\n## Nested grids\n\nSpace tokens are recommended for aligning content within containers, but you can also apply an\ninternal grid.\n\nWhile the underlying concepts are the same for columns, gutters, and margins, our grid component in\nFigma is only intended for the main content area. When setting up a grid inside a container, use our\n[space tokens](/foundations/spacing#space-tokens).\n\n[Create your own Figma layout guides](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides).\n\n<img\n\tsrc={nestedGrid}\n\tsrcDark={nestedGridDark}\n\talt="Example showing a card sitting on the main grid. The card has its own nested grid."\n/>\n\n## Grid breakpoints\n\nBreakpoints are based on the viewport width, not the width of the main content area. Showing or\nhiding the side navigation or a panel does not change which breakpoint the grid uses.\n\nThese are our default values for the grid in the main content area. Check your app or local system\nfor the specific grid values in use, as they may differ.\n\n<BreakpointsTable />\n\nAt each breakpoint, the gutter width, margin width, and number of columns adjust within the main\ncontent area. Breakpoints also affect layout areas like navigation and panels. For details see the\n[layout component](/components/navigation-system/layout).\n\nDesign for at least two device sizes from the table above, and preferably more. Always include\nmobile (`xxs`).\n\n<img\n\tsrc={gridBreakpoints}\n\tsrcDark={gridBreakpointsDark}\n\talt="Example showing how the grid changes across three breakpoint ranges: m – xl, xs – s, and xxs."\n/>\n\n## Grid types\n\nThere are two types of grid:\n\n- **Fixed grids** have a maximum width and sit centered in the main content area. This default\n  option comes in two sizes: fixed-wide and fixed-narrow.\n- **Fluid grids** fill the available space in the main content area. Use fluid grids when content\n  expands horizontally and has no natural maximum width. Use sparingly, because at very large\n  viewports, text lines can become too long and visual relationships between elements may break\n  down.\n\nWhen the main content area is smaller than the maximum width, such as at smaller breakpoints, fixed\ngrids behave the same as fluid grids.\n\n<img\n\tsrc={gridTypes}\n\tsrcDark={gridTypesDark}\n\talt="Side-by-side comparison of fixed and fluid grids on desktop and mobile viewports."\n/>\n\n### Fixed grids\n\nThere are two fixed grid options:\n\n- **Fixed-wide** has a maximum width of 1296px (including margins). Use this as the default for most\n  experiences.\n- **Fixed-narrow** has a maximum width of 864px (including margins). Use this for long-form content\n  such as blogs and articles, to limit line length and increase readability. Some internal elements,\n  such as headers, may break out of the grid to span across the page.\n\n<img\n\tsrc={fixedGridTypes}\n\tsrcDark={fixedGridTypesDark}\n\talt="Side-by-side comparison of fixed-wide and fixed-narrow grids."\n/>\n\n### Choosing between fixed and fluid grids\n\n| Grid type            | Maximum width (margins included) | Use when                                                    | Examples                                |\n| -------------------- | -------------------------------- | ----------------------------------------------------------- | --------------------------------------- |\n| Fixed-wide (default) | 1296px                           | Content benefits from structure but doesn\'t need full width | Dashboards, directories, search results |\n| Fixed-narrow         | 864px                            | Long-form reading is the primary activity                   | Blogs, articles, documentation          |\n| Fluid                | No maximum                       | Content expands horizontally with no natural maximum width  | Kanban boards, whiteboards              |\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedWideDo,\n\t\t\turlDarkMode: fixedWideDoDark,\n\t\t\talt: \'Example using a fixed-wide grid for a table directory.\',\n\t\t}}\n\t>\n\t\tUse fixed-wide grids for structured content, such as dashboards, search results, and\n\t\tdirectories.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedWideDont,\n\t\t\turlDarkMode: fixedWideDontDark,\n\t\t\talt: \'Example using a fixed-wide grid for long-form content.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-wide grids for long-form content like blogs and articles. Long line lengths\n\t\timpair readability.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedNarrowDo,\n\t\t\turlDarkMode: fixedNarrowDoDark,\n\t\t\talt: \'Example using a fixed-narrow grid for long-form content.\',\n\t\t}}\n\t>\n\t\tUse fixed-narrow grids for long-form content, such as blogs and articles.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedNarrowDont,\n\t\t\turlDarkMode: fixedNarrowDontDark,\n\t\t\talt: \'Example using a fixed-narrow grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-narrow grids for content that needs more horizontal space. Use fixed-wide or\n\t\tfluid instead.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fluidDo,\n\t\t\turlDarkMode: fluidDoDark,\n\t\t\talt: \'Example using a fluid grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tUse fluid grids for content that expands horizontally, such as kanban boards and whiteboards.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fluidDont,\n\t\t\turlDarkMode: fluidDontDark,\n\t\t\talt: \'Example using a fluid grid for a table directory.\',\n\t\t}}\n\t>\n\t\tDon\'t use fluid grids for structured content with a natural width, such as dashboards or\n\t\tdirectories. Elements lose their visual relationship at large viewports.\n\t</DoDont>\n</DoDontGrid>\n\n## Applying grid\n\nThe default grid is already built into the Figma layout component.\n\n1. Select your grid type from the component properties panel.\n2. Choose your breakpoint from the responsive menu in the appearance panel.\n\n<img\n\tsrc={applyingGrid}\n\tsrcDark={applyingGridDark}\n\talt="Screenshot of the Figma layout component with the properties panel showing grid type and responsive selectors."\n/>\n\nYou can also use this grid outside of the layout component. Select it from the assets panel in the\nADS Foundations library, or\n[create your own](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides) using\nyour app\'s values.\n\n**Tip:** Use **Shift + G** (Mac) or **Control + G** (Windows) to show or hide the grid in Figma.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridSpanDo,\n\t\t\turlDarkMode: gridSpanDoDark,\n\t\t\talt: \'Example of the grid spanning the main content area only.\',\n\t\t}}\n\t>\n\t\tSpan only the main content area. Exclude the side nav and panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridSpanDont,\n\t\t\turlDarkMode: gridSpanDontDark,\n\t\t\talt: \'Example of the grid spanning the side nav and main area.\',\n\t\t}}\n\t>\n\t\tDon\'t span the grid across navigation or panel areas.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointSettingDo,\n\t\t\turlDarkMode: breakpointSettingDoDark,\n\t\t\talt: \'Screenshot of the Figma responsive setting in the appearance panel.\',\n\t\t}}\n\t>\n\t\tChange the breakpoint from the responsive setting in the appearance panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointSettingDont,\n\t\t\turlDarkMode: breakpointSettingDontDark,\n\t\t\talt: \'Example of manually resizing the grid component.\',\n\t\t}}\n\t>\n\t\tDon\'t change the breakpoint by resizing the grid or layout component. The linked grid styles\n\t\twill map incorrectly.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointViewportDo,\n\t\t\turlDarkMode: breakpointViewportDoDark,\n\t\t\talt: \'Breakpoint set to the full viewport width.\',\n\t\t}}\n\t>\n\t\tSet the grid breakpoint to the full viewport width.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointViewportDont,\n\t\t\turlDarkMode: breakpointViewportDontDark,\n\t\t\talt: \'Breakpoint set to the content area width only.\',\n\t\t}}\n\t>\n\t\tDon\'t set the breakpoint based on the main content area width. Breakpoints are based on the full\n\t\tviewport width.\n\t</DoDont>\n</DoDontGrid>\n\n## Grid and auto layout\n\nGrid is a layout guide and a visual reference for aligning content to columns. To build layouts in\nFigma that adjust as the breakpoint changes, use auto layout to position content along the grid\ncolumns.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: autoLayoutDo,\n\t\t\turlDarkMode: autoLayoutDoDark,\n\t\t\talt: \'Screenshot of Figma auto layout settings.\',\n\t\t}}\n\t>\n\t\tUse auto layout to build responsive layouts that align to the grid.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: autoLayoutDont,\n\t\t\turlDarkMode: autoLayoutDontDark,\n\t\t\talt: \'Example of manually positioning content in Figma.\',\n\t\t}}\n\t>\n\t\tDon\'t use absolute positioning or drag-to-place content without auto layout. Manual placement\n\t\tdoesn\'t adapt to changing breakpoints and breaks responsive layouts.\n\t</DoDont>\n</DoDontGrid>\n\n## Related\n\n- [Layout](/components/navigation-system/layout) is the component that defines the outer structure\n  of an app, including navigation, panels, and the main content area.\n- [Primitives](/components/primitives/overview) are the box, stack, and inline primitives used to\n  build equivalent layouts in code.\n- [Spacing](/foundations/spacing) uses space tokens to ensure consistent alignment and separation\n  between elements.\n- [ADS Figma libraries](/get-started/design/figma-libraries/atlassians) contain the pre-built grid\n  with default Atlassian breakpoint values.\n- [Auto layout in Figma](https://help.figma.com/hc/en-us/articles/360040451373-Guide-to-auto-layout)\n  is Figma\'s guide to building responsive layouts that align to grid columns.',
   keywords: ['grid', 'layout', 'responsive', 'spacing', 'alignment', 'design system']

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

@@ -7,8 +7,9 @@ Object.defineProperty(exports, "__esModule", {
 exports.migrationRegistry = void 0;
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _avatarXsmallToXxsmall = require("./migrations/avatar-xsmall-to-xxsmall");
+var _interactionToEntryPoint = require("./migrations/interaction-to-entry-point");
 var _onboardingJiraSpotlight = require("./migrations/onboarding-jira-spotlight");
 var _onboardingMultiStep = require("./migrations/onboarding-multi-step");
 var _onboardingSingleStep = require("./migrations/onboarding-single-step");
 var _onboardingWithMotion = require("./migrations/onboarding-with-motion");
-var migrationRegistry = exports.migrationRegistry = (0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)({}, _avatarXsmallToXxsmall.avatarXsmallToXxsmall.id, _avatarXsmallToXxsmall.avatarXsmallToXxsmall), _onboardingJiraSpotlight.onboardingJiraSpotlight.id, _onboardingJiraSpotlight.onboardingJiraSpotlight), _onboardingSingleStep.onboardingSingleStep.id, _onboardingSingleStep.onboardingSingleStep), _onboardingMultiStep.onboardingMultiStep.id, _onboardingMultiStep.onboardingMultiStep), _onboardingWithMotion.onboardingWithMotion.id, _onboardingWithMotion.onboardingWithMotion);
+var migrationRegistry = exports.migrationRegistry = (0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)((0, _defineProperty2.default)({}, _avatarXsmallToXxsmall.avatarXsmallToXxsmall.id, _avatarXsmallToXxsmall.avatarXsmallToXxsmall), _interactionToEntryPoint.interactionToEntryPoint.id, _interactionToEntryPoint.interactionToEntryPoint), _onboardingJiraSpotlight.onboardingJiraSpotlight.id, _onboardingJiraSpotlight.onboardingJiraSpotlight), _onboardingSingleStep.onboardingSingleStep.id, _onboardingSingleStep.onboardingSingleStep), _onboardingMultiStep.onboardingMultiStep.id, _onboardingMultiStep.onboardingMultiStep), _onboardingWithMotion.onboardingWithMotion.id, _onboardingWithMotion.onboardingWithMotion);

package/dist/cjs/tools/migration-guides/migrations/interaction-to-entry-point.js

@@ -0,0 +1,22 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.interactionToEntryPoint = void 0;
+var interactionToEntryPoint = exports.interactionToEntryPoint = {
+  id: 'interaction-to-entry-point',
+  title: 'Interaction to EntryPoint migration',
+  description: 'Use when replacing an existing modal, popup, dropdown, or similar interaction boundary with an EntryPoint. It does not apply to new inline UI, API-only work, or test-only changes.',
+  fromPackage: 'product-owned interaction',
+  toPackage: '@atlassian/entry-points',
+  examples: [{
+    title: 'Move a controlled modal to an EntryPoint trigger',
+    description: 'Replace locally owned visibility state and direct rendering with the product-supported trigger and required provider.',
+    before: "\nconst [isOpen, setIsOpen] = useState(false);\n\n<Button aria-haspopup=\"dialog\" onClick={() => setIsOpen(true)}>\n\tOpen modal\n</Button>\n{isOpen && <Modal onClose={() => setIsOpen(false)}>\u2026</Modal>}\n",
+    after: "\n<ModalContextProvider>\n\t<ModalButtonTrigger entryPoint={modalEntryPoint} appearance=\"primary\">\n\t\tOpen modal\n\t</ModalButtonTrigger>\n</ModalContextProvider>\n",
+    explanation: 'The trigger owns visibility while the loaded root receives the supplied close callback. This is a structural example only: confirm the product API, provider requirements, focus return, Escape and outside dismissal, analytics, and any existing controlled-open contract before applying it.'
+  }],
+  bestPractices: ['Read the applicable product and package guides, then inspect the current interaction, its callers, and the shipped target trigger. Identify open/close paths, callbacks, state and data owners, provider lifetime, and the trigger ref, keyboard, disabled, and semantic props.', 'Use a direct conversion only when the supported target contract preserves required behavior. Do not remove public controlled or default-open behavior, manufacture unsupported props, or force a migration by changing requirements.', 'Move deferred UI behind the product-supported lazy root and remove eager value imports that defeat it. Keep preload parameters, queries, runtime props, and injected trigger props separate.', 'Forward the supplied trigger ref and interaction props to the actual control. Keep state, analytics, providers, and close side effects with the owner whose lifetime the existing contract requires.', 'For GraphQL, preload only data available at open time and consume the matching query reference in the lazy UI. Do not hand-edit generated artifacts or replace unrelated data architectures.', 'Trace the launcher through the trigger, EntryPoint, and lazy root to the rendered experience. A disconnected descriptor or unused preload is not a completed migration.', 'Run the smallest supported checks that observe changed behavior. Check opening, closing, callbacks, focus and keyboard behavior, data freshness, loading, and failures only when the original interaction requires them.'],
+  additionalResources: 'Report independently whether the conversion is full, partial, or blocked; whether behavior is preserved, changed, or unresolved; and which checks actually ran. Do not claim performance gains or runtime parity without evidence.'
+};

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

@@ -3,7 +3,7 @@
  *
  * Structured content for authored agent guidelines and design-system-docs foundations content.
  *
- * @codegen <<SignedSource::425b1c773867acafd317f203d71685ac>>
+ * @codegen <<SignedSource::ff17b8b82e5f2c80a40be5b39e323eab>>
  * @codegenCommand yarn build structured-docs
  */
 
@@ -64,8 +64,9 @@ export const guidelinesStructuredContent = [{
   content: "<SectionMessage title=\"\">\n\tThe guidance on this page relates to voice and tone for user interfaces and app experiences. For\n\tbroader guidance, including marketing, view{' '}\n\t<Link href=\"https://go.atlassian.com/voice-tone\">Brand Voice and Tone (Atlassians only)</Link>\n</SectionMessage>\n\nOur voice is essentially Atlassian's personality and is made up of the following traits:\n\n- Bold\n- Optimistic\n- Practical, with a wink\n\nTone is how we express Atlassian’s voice, and it should change depending on the situation the user\nis in (for example, receiving an error versus successfully completing a project).\n\nWhether it’s writing content for our apps, user interface, websites, or communications, you should\nfollow our voice and tone guidelines to ensure people recognize they’re interacting with Atlassian\nwherever they are.\n\n## How to apply Atlassian’s personality traits\n\nHow each trait is applied should depend on the audience and situation. Use these questions to help\nyou work out the right balance:\n\n- What is the emotional state of the user when they encounter your content or solution, and where\n  are they on their journey?\n- How might our personality traits enhance a moment of celebration?\n- How might our personality traits diffuse a moment of frustration or pain?\n\n<br></br>\n\n### Bold\n\nWhen we say bold, it’s about motivating teams with the right amount of support at the right time to\ndo their best work.\n\n- Offer best practices or just enough help to get the work started.\n- Give accurate information so people can make educated decisions.\n- Understand a person's struggles and desired outcomes, and give just enough information so someone\n  can get where they need to go.\n\n#### When to be more bold\n\n- Person is feeling: confident, interested, trust, anticipation.\n- Examples: power users, admins, daily users.\n\n#### When to be less bold\n\n- Person is feeling: apprehension, confusion, annoyance, fear, anger.\n- Examples: new users, trial users, when introducing a new concept, feature, or app.\n\n<br></br>\n\n### Optimistic\n\nWriting with optimism is understanding where in the journey someone is and highlighting the key\npoints that will help them along the way.\n\n- Focus on the most important bits the person needs in the moment. This gives people confidence in\n  our apps.\n- Weave a consistent story across apps and use the same vocabulary across all messaging.\n- Create a seamless flow across experiences. This lets people know that no matter where they’re\n  working, they can expect a familiar, consistent experience.\n- Keep people in the loop by informing them of relevant features, apps, and opportunities for\n  success.\n\n#### When to be more optimistic\n\n- Person is feeling: ambitious, inspired, curious, admiration.\n- Examples: power users, admins, daily users.\n\n#### When to be less optimistic\n\n- Person is feeling: anticipation, unsupported, confused, uncertain.\n- Examples: someone is new to Atlassian, trial users, when introducing a new concept, feature, or\n  app.\n\n<br></br>\n\n### Practical, with a wink\n\nOur practical side means getting to the point and being direct and concise.\n\n- Be on the lookout for opportunities where we can offer a helping hand.\n- Write clear, accurate, and concise content that makes interfaces more usable and consistent — and\n  builds trust.\n- Write content that is understandable for anyone, anywhere, regardless of their culture or language\n  so that everyone feels part of the team.\n\nThe ‘with a wink’ part of this trait needs more discernment when applying it to UI and app content\n(as opposed to marketing content) and remember that it isn’t always appropriate to use. Be mindful\nof where someone is at and what they might be experiencing before going beyond the practical.\n\n#### When to be more practical\n\n- Person is feeling: overwhelmed, unsure, hesitant, stressed.\n- Examples: people with deadlines or being blocked by errors, supporting new or occasional users,\n  introducing new features.\n\n#### When you can add the ‘wink’\n\n- Person is feeling: successful, joy, proud, relief.\n- Examples: power users, during social interactions, success messages.\n\n<br></br>\n\n## Voice and tone principles\n\nAtlassian's personality traits help keep our voice consistent across a range of different customer\nand app experiences. We can better support the full spectrum of experience for people by applying\nthe following principles.\n\nOur voice and tone principles:\n\n- [Inform to build trust](https://atlassian.design/foundations/content/voice-tone#inform-to-build-trust)\n- [Empower to inspire action](https://atlassian.design/foundations/content/voice-tone#empower-to-inspire-action)\n- [Encourage people along the path](https://atlassian.design/foundations/content/voice-tone#encourage-people-along-the-path)\n- [Motivate by showing possibilities](https://atlassian.design/foundations/content/voice-tone#motivate-by-showing-possibilities)\n- [Satisfy by meeting expectations](https://atlassian.design/foundations/content/voice-tone#satisfy-by-meeting-expectations)\n- [Delight with unexpectedly pleasing experiences](https://atlassian.design/foundations/content/voice-tone#delight-with-unexpectedly-pleasing-experiences)\n\n<br></br>\n\n### Inform to build trust\n\nBe open and clear about the experience.\n\n- Tell people only what they need to know in the moment and nothing more.\n- Be aware of when a user may be new or confused, and tone down the boldness by being more\n  prescriptive.\n- Let people know where they are in their journey and what this part of the app will do.\n\nWrite as a knowledgable member of the team. Show up at the right time and be open, humble, and warm.\nOffer direction for the most appropriate next steps.\n\n#### Places to use 'Inform to build trust'\n\n- In-app: [flags](https://atlassian.design/components/flag/usage),\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages),\n  and [spotlights](https://atlassian.design/components/spotlight/usage)\n- New features or apps\n- In confusing, warning, or error states\n\n<br></br>\n\n### Empower to inspire action\n\nEducate where people need it most.\n\n- Offer opportunities to learn at pivotal times to empower people to move in the right direction.\n- Give best practices and recommendations for next steps.\n- Suggest ways to improve or make decisions.\n- Let people know that Atlassian and fellow community members are available to help them make\n  decisions.\n\nWrite as if you are educating. You are a teacher with empathy and an understanding of what it’s like\nto be in the weeds. You expect your audience to have a basic understanding.\n\n#### Places to use 'Empower to inspire action'\n\n- In-app: [spotlights](https://atlassian.design/components/spotlight/usage) and\n  [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- When something requires an action\n- When guidance is needed\n\n<br></br>\n\n### Encourage people along the path\n\nInspire by providing support in the right place. Be consistent and dependable.\n\n- Offer waypoints, help, and support if people are feeling confused or frustrated at points along\n  their journey.\n- Be human: give guidance, support, and encouragement along the way.\n- Guide people by revealing information gracefully. Let them know they’re on the right path, they\n  aren’t alone, and that delivering projects and building teams can be challenging.\n\nWrite in an upbeat, friendly way. Acknowledge the opportunities in the here-and-now and walk through\nit with them.\n\n#### Places to use 'Encourage people along the path'\n\n- In-app:\n  [information messages](https://atlassian.design/foundations/content/designing-messages/info-messages),\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages),\n  and [section messages](https://atlassian.design/components/section-message/usage)\n- When something requires an action\n\n<br></br>\n\n### Motivate by showing possibilities\n\nProvide incentive and enthusiasm for continued growth.\n\n- Consider why someone would want to do this.\n- Show the possibilities of what can be accomplished by giving examples of how other people\n  accomplish the same task or by presenting the ideal state.\n- Describe the end result by giving expert testimony or offer opportunities for advanced knowledge.\n\nWrite like an expert. Focus more on the solution than on the problem. Show people the possible\nbenefits.\n\n#### Places to use 'Motivate by showing possibilities'\n\n- In-app: [spotlights](https://atlassian.design/components/spotlight/usage) and\n  [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- Educational opportunities — it's a chance to give best practices, and tips and tricks\n\n<br></br>\n\n### Satisfy by meeting expectations\n\nGive people what they need.\n\n- All of our content should be practical at a minimum.\n- Provide quick and thorough answers, guidance, actions, and instructions (rather than trying to\n  lead, inspire, motivate, delight, or encourage).\n- Simply tell people what they need to know and get out of the way.\n\nWrite as if you are explaining to your friend how to travel somewhere you’ve visited regularly.\n\n#### Places to use 'Satisfy by meeting expectations'\n\n- In-app:\n  [warning messages](https://atlassian.design/foundations/content/designing-messages/warning-messages),\n  [information messages](https://atlassian.design/foundations/content/designing-messages/info-messages),\n  and\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages)\n- Across all UI and app content\n\n<br></br>\n\n### Delight with unexpectedly pleasing experiences\n\nYou can deliver appropriate delight (a ‘wink’) by celebrating success or progress, but only once\nyou’ve built trust. Don’t overdo it. \n\n- Delight means little flourishes, not humor or being cheeky.\n- Always ask yourself what someone might be feeling at that moment and if delight is appropriate.\n  Also question whether it will be understood or appreciated by our global audience.\n- Think about the timing and how frequently a user will see this. Once may amuse, but a dozen times\n  may annoy.\n\n#### Places to use ‘Delight with unexpectedly pleasing experiences’\n\n- In-app:\n  [success messages](https://atlassian.design/foundations/content/designing-messages/success-messages)\n  and [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- Social interactions, while introducing new experiences",
   keywords: ['voice', 'tone', 'writing', 'content', 'brand']
 }, {
-  content: 'import {\n\tTokenElevationBackgroundChangeExample,\n\tTokenElevationChangeExample,\n} from \'../../../components/interactive-elevations\';\n\n\n\n\n\nElevations are the layered surfaces that form the foundation of the UI. They create a blank canvas\nwhere other UI will be placed, such as text, icons, backgrounds, and borders.\n\n![](./_assets/elevation-layers.png)\n\nMost elevations consist of surfaces and shadows. Together, surfaces and shadows give the impression\nof lift or depth. Elevations can guide focus through layering, or indicate that the UI can be\nscrolled, slid, or dragged.\n\n## Applying elevations\n\nThe elevations use [design tokens](https://atlassian.design/tokens/design-tokens) to apply different\nsurface levels. The highest two elevation surfaces, raised and overlay, are paired with shadows to\ncreate more depth.\n\n![](./_assets/applying-elevations-light.png)\n\n### Elevations in dark theme\n\nShadows can be harder to see in dark mode, so dark mode elevations also rely on different surface\ncolors. Imagine that the surfaces are distantly lit from the front — the higher the elevation, the\nlighter the surface looks.\n\n![](./_assets/applying-elevations-dark-1.png)\n\nRaised and overlay surfaces are still paired with shadows for added depth and consistency in dark\nmode.\n\n![](./_assets/applying-elevations-dark-2.png)\n\n## Types of elevations\n\nThere are four basic elevation levels:\n\n1. [Sunken](#sunken)\n2. [Default](#default)\n3. [Raised](#raised)\n4. [Overlay](#overlay)\n\nThere is also one "[overflow](#overflow)" elevation for special cases.\n\n### Sunken\n\nSunken is the lowest elevation available. The sunken surface creates a backdrop (or well) where\nother content sits. Columns on a Kanban board are a good example of the sunken elevation.\n\nOnly use sunken surfaces on the default surface level. Don’t apply sunken elevations on raised or\noverlay elevations. To differentiate areas of the UI in other ways, use whitespace or borders\ninstead.\n\n![](./_assets/elevation-sunken-1.png)\n\n#### Using `elevation.surface.sunken` vs `color.background.neutral`\n\nAlthough `elevation.surface.sunken` and `color.background.neutral` tokens may appear similar in\nlight mode, they behave differently in dark mode. Here are the main differences between the two:\n\n`elevation.surface.sunken` is an opaque (solid) token that darkens in both light and dark modes. Use\nthis token as a backdrop to group content or elements together (such as a kanban board) on the\ndefault surface.\n\n![](./_assets/elevation-sunken-2.png)\n\n`color.background.neutral` is a token that uses a transparent color. It darkens in light mode and\nlightens in dark mode. Use this token when you need the background to adapt to different elevations,\nwhich is relevant in dark mode since surfaces change depending on what elevation you’re on.\n\n![](./_assets/elevation-sunken-3.png)\n\n### Default\n\nThe default elevation is the baseline with respect to all other layers. It represents a flat UI\nsurface with no visual lift, such as a Confluence page.\n\nUse `elevation.surface` as the starting point for body content when building a UI. To create flat\ncards, pair with a border.\n\n![](./_assets/elevation-surface-1.png)\n\n### Raised\n\nRaised elevations sit slightly higher than default elevations. They are reserved for cards that can\nbe moved, such as Jira and Trello cards. In special circumstances, they can be used for cards as a\nway to provide additional heirarchy or emphasis.\n\nAlways pair `elevation.surface.raised` with `elevation.shadow.raised`. This is particularly\nimportant in dark mode, where raised surfaces are lighter to help differentiate elevations.\n\n![](./_assets/elevation-raised-1.png)\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tUse raised elevations intentionally. If using for emphasis, limit to one section or focal point\n\t\tof the screen.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tRaised elevations can create visual noise, so don’t use to group content when a border or white\n\t\tspace would suffice.\n\t</DoDont>\n</DoDontGrid>\n\n### Overlay\n\nOverlay is the highest elevation available. It is reserved for a UI that sits over another UI, such\nas modals, dialogs, dropdown menus, floating toolbars, and floating single-action buttons.\n\nAlways pair `elevation.surface.overlay` with `elevation.shadow.overlay`. This is important in dark\nmode, where overlay surfaces are lighter to help differentiate elevations.\n\nOverlays can stack on top of other overlays.\n\n![](./_assets/elevation-overlay-1.png)\n\n### Overflow\n\nOverflow is a shadow indicating content has [scrolled](#scrolled) outside a view. It can be used for\nvertical or horizontal scroll. An example of overflow shadows is the horizontal scroll in tables on\na Confluence page.\n\n![](./_assets/elevation-overflow-1.png)\n\nIf box shadows are not technically feasible, use the combination of\n`elevation.shadow.overflow.spread` and `elevation.shadow.overflow.perimeter` to replicate the\noverflow shadow.\n\n## Interaction states\n\n### Hovered and pressed\n\nElevations use surface color changes to communicate hovered and pressed states. Use the hovered and\npressed elevation tokens to create these visual changes.\n\n![](./_assets/elevation-hovered.png)\n\nTransitions between elevations can be used as an alternative to hovered and pressed tokens, but only\nfor default and raised elevations (not overlays):\n\n- Transition to overlay elevation on hover\n- Transition to raised elevation on press\n\nThis approach should be used sparingly to avoid excessive animation. It should not be used for very\nsmall UI, as elevation changes are harder to see than surface color changes at this size.\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tUse the recommended hovered and pressed tokens for interaction states on elevations.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tDon’t combine elevation transitions and hovered and pressed tokens for interactive states. Use\n\t\tone or the other.\n\t</DoDont>\n</DoDontGrid>\n\n#### Background change example\n\n<TokenElevationBackgroundChangeExample />\n\n#### Elevation change example\n\n<TokenElevationChangeExample />\n\n### Dragged\n\nUse the overlay elevation for any UI that is being dragged. Once moved, it returns to its original\nelevation.\n\n![](./_assets/elevation-dragged-1.png)\n\n### Scrolled\n\nWhen scrollable content exceeds the available area, a border or [overflow](#overflow) shadow can be\napplied at the point the content is cut off to indicate there is hidden content that can be scrolled\nback into view.\n\nA border is the default approach for scrolled content and can be seen in modal sticky headers and\nfooters, and top and side navigation.\n\n![](./_assets/elevation-scrolled.png)\n\n[Overflow](#overflow) shadows are reserved for experiences where a border might be easily missed,\nsuch as in very small UI or tables that use borders to separate cells.\n\nBoth approaches should apply the appropriate surface token where the content is being hidden.\n\n## All elevation tokens and values\n\nFor the full list of elevation design tokens and their values, see our\n[design token reference list](https://atlassian.design/components/tokens/all-tokens). Every token\ncomes with a description to help you ensure you’re using the correct one.\n\n## Best practices\n\n### Follow the recommended surface and shadow pairings\n\nRaised and overlay elevations have dedicated surface and shadow pairings.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: pairingDo, alt: \'\' }}>\n\t\tWhen creating elevations, always pair matching surface and shadow tokens.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: pairingDont, alt: \'\' }}>\n\t\tDon\'t mix different shadow and surface elevation tokens.\n\t</DoDont>\n</DoDontGrid>\n\n### Replace elevation surfaces with background colors only when required\n\nElevation surfaces use our\n[neutral palettes](https://atlassian.design/foundations/color#neutral-colors). If a different color\nis needed, surface tokens can be swapped for any solid background token. When using background\ntokens, align to the behavior of\n[interaction states for color tokens](https://atlassian.design/foundations/color#interaction-states).\n\n![](./_assets/background-colors.png)\n\n### Avoid excessive use of raised and overlay elevations\n\nThe shadows and surfaces of raised and overlay elevations can create busy UI if not applied\nintentionally. Follow the recommended guidance when considering these elevations.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: groupingDo, alt: \'\' }}>\n\t\tLimit the use of overlay elevations by grouping related buttons together in a floating toolbar\n\t\tif they are required to sit over another UI.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: groupingDont, alt: \'\' }}>\n\t\tDon’t have more than one floating button next to each other.\n\t</DoDont>\n</DoDontGrid>\n\n### Check contrast ratios\n\nAlways make sure your elevation and background choices are accessible.\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tCheck the contrast ratio for UI on overlay surfaces in dark mode to ensure it meets\n\t\taccessibility requirements.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tDon\'t assume that because UI is accessible in light mode, it will be in dark mode. Some UI may\n\t\tneed tweaking.\n\t</DoDont>\n</DoDontGrid>\n\n## Z-index\n\nThe z-index determines the stacking order of elements. Elements with a higher z-index always sit in\nfront of elements with a lower z-index.\n\nDifferent UI can have the same elevation style, but each UI should apply a different z-index to\nindicate the layer(s) order in a stack (or where the elements touch).\n\n| Z-index | Example usage                                                                     | Elevation level |\n| ------- | --------------------------------------------------------------------------------- | --------------- |\n| 100     | None                                                                              | None            |\n| 200     | [Atlassian navigation](https://atlassian.design/components/atlassian-navigation/) | Default         |\n| 300     | [Inline dialog](https://atlassian.design/components/inline-dialog/)               | Overlay         |\n| 400     | [Popup](https://atlassian.design/components/popup/)                               | Overlay         |\n| 500     | [Blanket](https://atlassian.design/components/blanket/)                           | None            |\n| 510     | [Modal](https://atlassian.design/components/modal-dialog/)                        | Overlay         |\n| 600     | [Flag](https://atlassian.design/components/flag/)                                 | Overlay         |\n| 700     | [Spotlight](https://atlassian.design/components/onboarding/)                      | Overlay         |\n| 800     | [Tooltip](https://atlassian.design/components/tooltip/)                           | None            |\n\n## Related\n\n- Learn about the basics of [design tokens](https://atlassian.design/tokens/design-tokens).\n- See the list of [all design tokens](https://atlassian.design/components/tokens/all-tokens) for\n  full descriptions and values for all tokens.',
-  keywords: ['elevation', 'shadow', 'depth', 'z-index', 'layering', 'design tokens']
+  content: '# Elevation\n\nUse elevation to choose structural surfaces, visual depth, and scroll boundaries for Atlassian UI.\nIdentify the element’s role, host surface, and whether it is interactive. Preserve valid existing\ntreatment; reuse the ADS component’s built-in appearance before styling custom UI. For example,\nModal and Popup own their floating treatment. Consult the selected component before customization;\navoid adding a second shadow or elevated wrapper.\n\nFor custom UI, choose the resting surface and separation first, then derive interaction and drag\nstates. During review, explain the role that justifies any change and identify unresolved host or\ncomponent dependencies.\n\nElevations provide a canvas for text, icons, backgrounds, and borders. Surfaces and shadows\ncommunicate lift or depth and can indicate movable or scrollable content. They do not establish\nkeyboard focus, selection, or stacking order.\n\n## Choose the surface from its purpose\n\nThere are four basic elevation levels: sunken, default, raised, and overlay. Overflow is a special\nshadow for scroll boundaries.\n\n| Purpose                      | Surface                       | Separation or shadow                       |\n| ---------------------------- | ----------------------------- | ------------------------------------------ |\n| Primary page or flat content | `elevation.surface`           | Whitespace; `color.border` for flat cards  |\n| Neutral grouping             | `elevation.surface.container` | Container background; boundary when needed |\n| Recessed grouping on default | `elevation.surface.sunken`    | Recessed backdrop, such as a Kanban column |\n| Movable card                 | `elevation.surface.raised`    | `elevation.shadow.raised`                  |\n| UI floating over other UI    | `elevation.surface.overlay`   | `elevation.shadow.overlay`                 |\n\nDefault is the baseline for page content. A container is a grouping treatment, not another elevation\nlevel. Clickability alone does not require raised elevation.\n\nReserve raised elevation for movable cards. In special circumstances, use it for emphasis, limited\nto one section or focal point. Prefer whitespace, borders, or container backgrounds for ordinary\ngrouping; excessive shadows create visual noise.\n\nOverlay is the highest elevation, for modals, dialogs, dropdown menus, floating toolbars, and\nfloating single-action buttons. Overlays can stack on other overlays. Group related floating actions\nin a floating toolbar; do not place more than one floating button next to another.\n\nAlways pair raised and overlay surfaces with their matching shadows. Do not mix surface and shadow\nlevels. These pairings remain necessary in dark mode.\n\n## Keep interaction treatment consistent\n\nUse the surface’s own hovered and pressed variants when the surface itself is interactive. Apply\nthem to the interactive element; containing controls does not make the surrounding page or group\ninteractive.\n\n| Resting surface               | Hovered surface                       | Pressed surface                       | Shadow                     |\n| ----------------------------- | ------------------------------------- | ------------------------------------- | -------------------------- |\n| `elevation.surface`           | `elevation.surface.hovered`           | `elevation.surface.pressed`           | None                       |\n| `elevation.surface.container` | `elevation.surface.container.hovered` | `elevation.surface.container.pressed` | None                       |\n| `elevation.surface.raised`    | `elevation.surface.raised.hovered`    | `elevation.surface.raised.pressed`    | `elevation.shadow.raised`  |\n| `elevation.surface.overlay`   | `elevation.surface.overlay.hovered`   | `elevation.surface.overlay.pressed`   | `elevation.shadow.overlay` |\n\nA background change does not require an elevation change. The catalog defines no hovered or pressed\nvariants for sunken surfaces; use the treatment of the controls inside them. Look up other\ncombinations rather than constructing token names.\n\nElevation transitions are an alternative only for default and raised surfaces, never overlays:\ntransition to overlay surface and shadow on hover, then raised surface and shadow on press. Use this\nsparingly to avoid excessive animation. Do not use it for very small UI, where surface color changes\nare easier to see. Choose either elevation transitions or hovered/pressed surface tokens; do not\ncombine them. Follow applicable motion and reduced-motion guidance.\n\nUse overlay elevation for any UI being dragged, with its matching surface and shadow. Restore the\noriginal elevation when the drag completes or is cancelled. Follow the drag component’s movement and\naccessibility behavior.\n\nPreserve selection and keyboard-focus cues during hover and press; consult color guidance for those\ntreatments.\n\n## Respect nesting and theme behavior\n\nUse sunken surfaces only on the default elevation. Within raised or overlay surfaces, distinguish\nsections with whitespace or borders.\n\nIn dark mode, shadows are harder to see, so higher elevations also use lighter surface colors. Think\nof surfaces lit from the front: greater height makes the surface appear lighter. A shadow alone does\nnot reproduce raised or overlay treatment. Use tokens in each theme rather than copying light-theme\ncolor values.\n\nAlthough they can look similar in light mode, these backgrounds behave differently:\n\n- `elevation.surface.sunken` is opaque and darkens in both themes. Use it as a recessed backdrop for\n  grouped content on the default surface.\n- `color.background.neutral` is translucent: it darkens in light mode and lightens in dark mode,\n  adapting to the elevation beneath it.\n- `elevation.surface.container` provides neutral container grouping; its rendered appearance can\n  depend on the underlying surface.\n\nElevation surfaces use neutral palettes. Replace a surface with a solid background token only when a\ndifferent color is required. Follow the\n[color interaction-state guidance](https://atlassian.design/foundations/color#interaction-states)\nwhen using background tokens. Choose semantic and selected backgrounds for their meaning or state,\nnot merely because their color resembles a surface.\n\nCheck contrast against the rendered background, including underlying surfaces and overlapping\ntranslucent layers. Do not assume light-mode accessibility carries over to dark mode; check UI on\noverlay surfaces especially.\n\n## Indicate hidden scrollable content\n\nFor vertical or horizontal scrolling, indicate where content has scrolled out of view. Start with a\nborder at the cutoff, as in sticky modal headers and footers or top and side navigation. Apply the\nappropriate surface token where content is hidden.\n\nUse `elevation.shadow.overflow` when a border could be missed, such as very small UI or tables with\ncell borders. Place it at the relevant boundary, not decoratively around every scrollable container.\n\nIf the full overflow shadow is technically infeasible, pair `elevation.shadow.overflow.spread` with\n`elevation.shadow.overflow.perimeter` to replicate it. Follow their token descriptions.\n\n## Distinguish visual depth from stacking\n\nElevation surfaces and shadows communicate visual depth; they do not establish stacking order.\n\nUse the host component’s supported positioning and layering behavior. For components using the\nbrowser top layer, follow that component’s implementation rather than applying a numeric z-index\nrecipe. Check the installed version and migration guidance before changing existing layering.\n\nFor custom UI that uses numbered stacking, consult the\n[ADS z-index reference](https://atlassian.design/foundations/elevation/#z-index) and follow the\nrepository’s layering constraints. Do not derive layer values from elevation tokens or assume that\nincreasing z-index can place content above a top-layer surface.\n\nFor nested overlays, verify visibility, focus, and dismissal. Layering coordination does not replace\nthe host component’s accessibility behavior.\n\n## Retrieve only the missing detail\n\nWhen loaded through the ADS skill, follow its retrieval order.\n\nUse the guidance here first. If a detail is missing, use `atlas ads`; use ADS MCP only after a CLI\nerror, an empty result, or a missing capability. For tokens, search by purpose, then confirm the\nexact token:\n\n```sh\natlas ads search "<purpose>" --type token --limit 5 --json\natlas ads token elevation.surface --json\n```\n\nFor MCP fallback, use `ads_search_tokens` for token usage, `ads_search_components` for component\nAPIs, or `ads_get_a11y_guidelines` for accessibility; follow each tool’s exposed schema. Don’t\nrepeat a successful lookup through another route, fetch the full catalog, or construct tokens by\nappending state suffixes. If a detail remains unresolved, label it unverified and state what still\nneeds checking.\n\n## Verify the result\n\nCheck matching surface/shadow pairs, interaction variants, drag restoration on completion and\ncancellation, scroll indicators at the correct edge, and nested-layer visibility, focus, and\ndismissal. Check text, icons, focus indicators, and meaningful boundaries in supported themes and\nstates. Distinguish verified token names from tested behavior: screenshots alone do not establish\ndrag cancellation, focus, or dismissal.\n\n## Sources\n\nPrinciples: [ADS elevation](https://atlassian.design/foundations/elevation). Exact names, purposes,\nand values: the bundled elevation token reference or\n[design token reference list](https://atlassian.design/components/tokens/all-tokens). Use the\nselected component’s reference for its API and behavior.',
+  name: 'Elevation',
+  keywords: ['elevation', 'shadow', 'depth', 'z-index', 'layering', 'design tokens', 'surfaces', 'containers', 'cards', 'overlays', 'hover', 'press', 'drag', 'scroll boundaries', 'dark mode', 'popup inside modal', 'nested overlays']
 }, {
   content: '## Overview\n\nGrid is a system for arranging content consistently within the main content area of an Atlassian\napp.\n\nIn Figma, grids are set up using\n[Figma layout guides](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides).\nThe code equivalent is built using a combination of [primitives](/components/primitives/overview)\nsuch as box, stack, and inline.\n\nFor everything outside of the main content area, including navigation and panel, see the\n[layout component](/components/navigation-system/layout).\n\n<img\n\tsrc={layoutAnatomy}\n\tsrcDark={layoutAnatomyDark}\n\talt="Layout component anatomy showing the top nav, side nav, main, and panel. Grid sits within main."\n/>\n\n## Grid basics\n\nThe Figma grid component has three basic elements:\n\n- **Columns** divide the main content area into 12 equal parts for horizontal structure.\n- **Gutters** are the gaps between columns, providing consistent separation between content.\n- **Margins** are the empty space between the outer columns and the edge of the main content area.\n  They give content clear space.\n\n<img\n\tsrc={gridAnatomy}\n\tsrcDark={gridAnatomyDark}\n\talt="Figma grid component anatomy showing columns, gutters, and margins."\n/>\n\nAligning content to the columns supports a variety of layouts in the main content area. For example,\ncontent can span 12, 6, or 4 columns.\n\n<img\n\tsrc={columnSpan}\n\tsrcDark={columnSpanDark}\n\talt="Diagram showing content arrangement spanning 12, 6, or 4 grid columns."\n/>\n\nContent can also sit centered within the grid. For example, a centered block can span 8, 10, or 12\ncolumns.\n\n<img\n\tsrc={columnOffset}\n\tsrcDark={columnOffsetDark}\n\talt="Diagram showing content arrangement center-aligned on the grid and spanning 8, 10, or 12 grid columns."\n/>\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridBasicsDo,\n\t\t\turlDarkMode: gridBasicsDoDark,\n\t\t\talt: \'Example of content aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content within the app\'s main content area across any number of columns required.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridBasicsDont,\n\t\t\turlDarkMode: gridBasicsDontDark,\n\t\t\talt: \'Example of content overflowing into grid gutters and margins, breaking visual alignment.\',\n\t\t}}\n\t>\n\t\tDon\'t allow content to overflow into gutters or margins. This breaks visual alignment and makes\n\t\tlayouts unpredictable.\n\t</DoDont>\n</DoDontGrid>\n\n## How to choose what to align to the grid\n\nWithin the main content area, align content containers to the grid columns. Examples include cards,\nimages, text blocks, tables, and forms.\n\nSmall elements, like buttons and icons, do not need to align to this grid. Use\n[space tokens](/foundations/spacing#space-tokens) to manage the space between and within them\ninstead.\n\n<img\n\tsrc={spacingTokens}\n\tsrcDark={spacingTokensDark}\n\talt="Example showing cards aligned to grid columns. The horizontally placed input field and buttons, as well as the content within the card, do not align to the grid columns and are instead managed with space tokens."\n/>\n\nThe same applies within content containers. Only top-level containers need to align to the grid. Use\nspace tokens for the elements inside them, such as cards and table columns.\n\n<img\n\tsrc={contentContainers}\n\tsrcDark={contentContainersDark}\n\talt="Example showing kanban columns aligned to the grid, but the cards within them using space tokens."\n/>\n\nOverlays like modals, tooltips, and dropdown menus also sit outside the grid, as they float above\nthe page content.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: alignContentDo,\n\t\t\turlDarkMode: alignContentDoDark,\n\t\t\talt: \'Example of content containers aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content containers to our grid columns, such as cards, images, text blocks, tables, and\n\t\tforms.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: alignContentDont,\n\t\t\turlDarkMode: alignContentDontDark,\n\t\t\talt: \'Example of buttons and icons incorrectly aligned to the grid columns instead of using space tokens.\',\n\t\t}}\n\t>\n\t\tDon\'t align small elements, such as buttons or icons, to the grid. Instead, use space tokens to\n\t\tmanage their spacing.\n\t</DoDont>\n</DoDontGrid>\n\n## Nested grids\n\nSpace tokens are recommended for aligning content within containers, but you can also apply an\ninternal grid.\n\nWhile the underlying concepts are the same for columns, gutters, and margins, our grid component in\nFigma is only intended for the main content area. When setting up a grid inside a container, use our\n[space tokens](/foundations/spacing#space-tokens).\n\n[Create your own Figma layout guides](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides).\n\n<img\n\tsrc={nestedGrid}\n\tsrcDark={nestedGridDark}\n\talt="Example showing a card sitting on the main grid. The card has its own nested grid."\n/>\n\n## Grid breakpoints\n\nBreakpoints are based on the viewport width, not the width of the main content area. Showing or\nhiding the side navigation or a panel does not change which breakpoint the grid uses.\n\nThese are our default values for the grid in the main content area. Check your app or local system\nfor the specific grid values in use, as they may differ.\n\n<BreakpointsTable />\n\nAt each breakpoint, the gutter width, margin width, and number of columns adjust within the main\ncontent area. Breakpoints also affect layout areas like navigation and panels. For details see the\n[layout component](/components/navigation-system/layout).\n\nDesign for at least two device sizes from the table above, and preferably more. Always include\nmobile (`xxs`).\n\n<img\n\tsrc={gridBreakpoints}\n\tsrcDark={gridBreakpointsDark}\n\talt="Example showing how the grid changes across three breakpoint ranges: m – xl, xs – s, and xxs."\n/>\n\n## Grid types\n\nThere are two types of grid:\n\n- **Fixed grids** have a maximum width and sit centered in the main content area. This default\n  option comes in two sizes: fixed-wide and fixed-narrow.\n- **Fluid grids** fill the available space in the main content area. Use fluid grids when content\n  expands horizontally and has no natural maximum width. Use sparingly, because at very large\n  viewports, text lines can become too long and visual relationships between elements may break\n  down.\n\nWhen the main content area is smaller than the maximum width, such as at smaller breakpoints, fixed\ngrids behave the same as fluid grids.\n\n<img\n\tsrc={gridTypes}\n\tsrcDark={gridTypesDark}\n\talt="Side-by-side comparison of fixed and fluid grids on desktop and mobile viewports."\n/>\n\n### Fixed grids\n\nThere are two fixed grid options:\n\n- **Fixed-wide** has a maximum width of 1296px (including margins). Use this as the default for most\n  experiences.\n- **Fixed-narrow** has a maximum width of 864px (including margins). Use this for long-form content\n  such as blogs and articles, to limit line length and increase readability. Some internal elements,\n  such as headers, may break out of the grid to span across the page.\n\n<img\n\tsrc={fixedGridTypes}\n\tsrcDark={fixedGridTypesDark}\n\talt="Side-by-side comparison of fixed-wide and fixed-narrow grids."\n/>\n\n### Choosing between fixed and fluid grids\n\n| Grid type            | Maximum width (margins included) | Use when                                                    | Examples                                |\n| -------------------- | -------------------------------- | ----------------------------------------------------------- | --------------------------------------- |\n| Fixed-wide (default) | 1296px                           | Content benefits from structure but doesn\'t need full width | Dashboards, directories, search results |\n| Fixed-narrow         | 864px                            | Long-form reading is the primary activity                   | Blogs, articles, documentation          |\n| Fluid                | No maximum                       | Content expands horizontally with no natural maximum width  | Kanban boards, whiteboards              |\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedWideDo,\n\t\t\turlDarkMode: fixedWideDoDark,\n\t\t\talt: \'Example using a fixed-wide grid for a table directory.\',\n\t\t}}\n\t>\n\t\tUse fixed-wide grids for structured content, such as dashboards, search results, and\n\t\tdirectories.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedWideDont,\n\t\t\turlDarkMode: fixedWideDontDark,\n\t\t\talt: \'Example using a fixed-wide grid for long-form content.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-wide grids for long-form content like blogs and articles. Long line lengths\n\t\timpair readability.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedNarrowDo,\n\t\t\turlDarkMode: fixedNarrowDoDark,\n\t\t\talt: \'Example using a fixed-narrow grid for long-form content.\',\n\t\t}}\n\t>\n\t\tUse fixed-narrow grids for long-form content, such as blogs and articles.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedNarrowDont,\n\t\t\turlDarkMode: fixedNarrowDontDark,\n\t\t\talt: \'Example using a fixed-narrow grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-narrow grids for content that needs more horizontal space. Use fixed-wide or\n\t\tfluid instead.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fluidDo,\n\t\t\turlDarkMode: fluidDoDark,\n\t\t\talt: \'Example using a fluid grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tUse fluid grids for content that expands horizontally, such as kanban boards and whiteboards.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fluidDont,\n\t\t\turlDarkMode: fluidDontDark,\n\t\t\talt: \'Example using a fluid grid for a table directory.\',\n\t\t}}\n\t>\n\t\tDon\'t use fluid grids for structured content with a natural width, such as dashboards or\n\t\tdirectories. Elements lose their visual relationship at large viewports.\n\t</DoDont>\n</DoDontGrid>\n\n## Applying grid\n\nThe default grid is already built into the Figma layout component.\n\n1. Select your grid type from the component properties panel.\n2. Choose your breakpoint from the responsive menu in the appearance panel.\n\n<img\n\tsrc={applyingGrid}\n\tsrcDark={applyingGridDark}\n\talt="Screenshot of the Figma layout component with the properties panel showing grid type and responsive selectors."\n/>\n\nYou can also use this grid outside of the layout component. Select it from the assets panel in the\nADS Foundations library, or\n[create your own](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides) using\nyour app\'s values.\n\n**Tip:** Use **Shift + G** (Mac) or **Control + G** (Windows) to show or hide the grid in Figma.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridSpanDo,\n\t\t\turlDarkMode: gridSpanDoDark,\n\t\t\talt: \'Example of the grid spanning the main content area only.\',\n\t\t}}\n\t>\n\t\tSpan only the main content area. Exclude the side nav and panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridSpanDont,\n\t\t\turlDarkMode: gridSpanDontDark,\n\t\t\talt: \'Example of the grid spanning the side nav and main area.\',\n\t\t}}\n\t>\n\t\tDon\'t span the grid across navigation or panel areas.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointSettingDo,\n\t\t\turlDarkMode: breakpointSettingDoDark,\n\t\t\talt: \'Screenshot of the Figma responsive setting in the appearance panel.\',\n\t\t}}\n\t>\n\t\tChange the breakpoint from the responsive setting in the appearance panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointSettingDont,\n\t\t\turlDarkMode: breakpointSettingDontDark,\n\t\t\talt: \'Example of manually resizing the grid component.\',\n\t\t}}\n\t>\n\t\tDon\'t change the breakpoint by resizing the grid or layout component. The linked grid styles\n\t\twill map incorrectly.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointViewportDo,\n\t\t\turlDarkMode: breakpointViewportDoDark,\n\t\t\talt: \'Breakpoint set to the full viewport width.\',\n\t\t}}\n\t>\n\t\tSet the grid breakpoint to the full viewport width.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointViewportDont,\n\t\t\turlDarkMode: breakpointViewportDontDark,\n\t\t\talt: \'Breakpoint set to the content area width only.\',\n\t\t}}\n\t>\n\t\tDon\'t set the breakpoint based on the main content area width. Breakpoints are based on the full\n\t\tviewport width.\n\t</DoDont>\n</DoDontGrid>\n\n## Grid and auto layout\n\nGrid is a layout guide and a visual reference for aligning content to columns. To build layouts in\nFigma that adjust as the breakpoint changes, use auto layout to position content along the grid\ncolumns.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: autoLayoutDo,\n\t\t\turlDarkMode: autoLayoutDoDark,\n\t\t\talt: \'Screenshot of Figma auto layout settings.\',\n\t\t}}\n\t>\n\t\tUse auto layout to build responsive layouts that align to the grid.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: autoLayoutDont,\n\t\t\turlDarkMode: autoLayoutDontDark,\n\t\t\talt: \'Example of manually positioning content in Figma.\',\n\t\t}}\n\t>\n\t\tDon\'t use absolute positioning or drag-to-place content without auto layout. Manual placement\n\t\tdoesn\'t adapt to changing breakpoints and breaks responsive layouts.\n\t</DoDont>\n</DoDontGrid>\n\n## Related\n\n- [Layout](/components/navigation-system/layout) is the component that defines the outer structure\n  of an app, including navigation, panels, and the main content area.\n- [Primitives](/components/primitives/overview) are the box, stack, and inline primitives used to\n  build equivalent layouts in code.\n- [Spacing](/foundations/spacing) uses space tokens to ensure consistent alignment and separation\n  between elements.\n- [ADS Figma libraries](/get-started/design/figma-libraries/atlassians) contain the pre-built grid\n  with default Atlassian breakpoint values.\n- [Auto layout in Figma](https://help.figma.com/hc/en-us/articles/360040451373-Guide-to-auto-layout)\n  is Figma\'s guide to building responsive layouts that align to grid columns.',
   keywords: ['grid', 'layout', 'responsive', 'spacing', 'alignment', 'design system']

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

@@ -1,10 +1,12 @@
 import { avatarXsmallToXxsmall } from './migrations/avatar-xsmall-to-xxsmall';
+import { interactionToEntryPoint } from './migrations/interaction-to-entry-point';
 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 = {
   [avatarXsmallToXxsmall.id]: avatarXsmallToXxsmall,
+  [interactionToEntryPoint.id]: interactionToEntryPoint,
   [onboardingJiraSpotlight.id]: onboardingJiraSpotlight,
   [onboardingSingleStep.id]: onboardingSingleStep,
   [onboardingMultiStep.id]: onboardingMultiStep,

package/dist/es2019/tools/migration-guides/migrations/interaction-to-entry-point.js

@@ -0,0 +1,29 @@
+export const interactionToEntryPoint = {
+  id: 'interaction-to-entry-point',
+  title: 'Interaction to EntryPoint migration',
+  description: 'Use when replacing an existing modal, popup, dropdown, or similar interaction boundary with an EntryPoint. It does not apply to new inline UI, API-only work, or test-only changes.',
+  fromPackage: 'product-owned interaction',
+  toPackage: '@atlassian/entry-points',
+  examples: [{
+    title: 'Move a controlled modal to an EntryPoint trigger',
+    description: 'Replace locally owned visibility state and direct rendering with the product-supported trigger and required provider.',
+    before: `
+const [isOpen, setIsOpen] = useState(false);
+
+<Button aria-haspopup="dialog" onClick={() => setIsOpen(true)}>
+	Open modal
+</Button>
+{isOpen && <Modal onClose={() => setIsOpen(false)}>…</Modal>}
+`,
+    after: `
+<ModalContextProvider>
+	<ModalButtonTrigger entryPoint={modalEntryPoint} appearance="primary">
+		Open modal
+	</ModalButtonTrigger>
+</ModalContextProvider>
+`,
+    explanation: 'The trigger owns visibility while the loaded root receives the supplied close callback. This is a structural example only: confirm the product API, provider requirements, focus return, Escape and outside dismissal, analytics, and any existing controlled-open contract before applying it.'
+  }],
+  bestPractices: ['Read the applicable product and package guides, then inspect the current interaction, its callers, and the shipped target trigger. Identify open/close paths, callbacks, state and data owners, provider lifetime, and the trigger ref, keyboard, disabled, and semantic props.', 'Use a direct conversion only when the supported target contract preserves required behavior. Do not remove public controlled or default-open behavior, manufacture unsupported props, or force a migration by changing requirements.', 'Move deferred UI behind the product-supported lazy root and remove eager value imports that defeat it. Keep preload parameters, queries, runtime props, and injected trigger props separate.', 'Forward the supplied trigger ref and interaction props to the actual control. Keep state, analytics, providers, and close side effects with the owner whose lifetime the existing contract requires.', 'For GraphQL, preload only data available at open time and consume the matching query reference in the lazy UI. Do not hand-edit generated artifacts or replace unrelated data architectures.', 'Trace the launcher through the trigger, EntryPoint, and lazy root to the rendered experience. A disconnected descriptor or unused preload is not a completed migration.', 'Run the smallest supported checks that observe changed behavior. Check opening, closing, callbacks, focus and keyboard behavior, data freshness, loading, and failures only when the original interaction requires them.'],
+  additionalResources: 'Report independently whether the conversion is full, partial, or blocked; whether behavior is preserved, changed, or unresolved; and which checks actually ran. Do not claim performance gains or runtime parity without evidence.'
+};

package/dist/esm/tools/get-guidelines/guidelines-structured-content.codegen.js

@@ -3,7 +3,7 @@
  *
  * Structured content for authored agent guidelines and design-system-docs foundations content.
  *
- * @codegen <<SignedSource::425b1c773867acafd317f203d71685ac>>
+ * @codegen <<SignedSource::ff17b8b82e5f2c80a40be5b39e323eab>>
  * @codegenCommand yarn build structured-docs
  */
 
@@ -64,8 +64,9 @@ export var guidelinesStructuredContent = [{
   content: "<SectionMessage title=\"\">\n\tThe guidance on this page relates to voice and tone for user interfaces and app experiences. For\n\tbroader guidance, including marketing, view{' '}\n\t<Link href=\"https://go.atlassian.com/voice-tone\">Brand Voice and Tone (Atlassians only)</Link>\n</SectionMessage>\n\nOur voice is essentially Atlassian's personality and is made up of the following traits:\n\n- Bold\n- Optimistic\n- Practical, with a wink\n\nTone is how we express Atlassian’s voice, and it should change depending on the situation the user\nis in (for example, receiving an error versus successfully completing a project).\n\nWhether it’s writing content for our apps, user interface, websites, or communications, you should\nfollow our voice and tone guidelines to ensure people recognize they’re interacting with Atlassian\nwherever they are.\n\n## How to apply Atlassian’s personality traits\n\nHow each trait is applied should depend on the audience and situation. Use these questions to help\nyou work out the right balance:\n\n- What is the emotional state of the user when they encounter your content or solution, and where\n  are they on their journey?\n- How might our personality traits enhance a moment of celebration?\n- How might our personality traits diffuse a moment of frustration or pain?\n\n<br></br>\n\n### Bold\n\nWhen we say bold, it’s about motivating teams with the right amount of support at the right time to\ndo their best work.\n\n- Offer best practices or just enough help to get the work started.\n- Give accurate information so people can make educated decisions.\n- Understand a person's struggles and desired outcomes, and give just enough information so someone\n  can get where they need to go.\n\n#### When to be more bold\n\n- Person is feeling: confident, interested, trust, anticipation.\n- Examples: power users, admins, daily users.\n\n#### When to be less bold\n\n- Person is feeling: apprehension, confusion, annoyance, fear, anger.\n- Examples: new users, trial users, when introducing a new concept, feature, or app.\n\n<br></br>\n\n### Optimistic\n\nWriting with optimism is understanding where in the journey someone is and highlighting the key\npoints that will help them along the way.\n\n- Focus on the most important bits the person needs in the moment. This gives people confidence in\n  our apps.\n- Weave a consistent story across apps and use the same vocabulary across all messaging.\n- Create a seamless flow across experiences. This lets people know that no matter where they’re\n  working, they can expect a familiar, consistent experience.\n- Keep people in the loop by informing them of relevant features, apps, and opportunities for\n  success.\n\n#### When to be more optimistic\n\n- Person is feeling: ambitious, inspired, curious, admiration.\n- Examples: power users, admins, daily users.\n\n#### When to be less optimistic\n\n- Person is feeling: anticipation, unsupported, confused, uncertain.\n- Examples: someone is new to Atlassian, trial users, when introducing a new concept, feature, or\n  app.\n\n<br></br>\n\n### Practical, with a wink\n\nOur practical side means getting to the point and being direct and concise.\n\n- Be on the lookout for opportunities where we can offer a helping hand.\n- Write clear, accurate, and concise content that makes interfaces more usable and consistent — and\n  builds trust.\n- Write content that is understandable for anyone, anywhere, regardless of their culture or language\n  so that everyone feels part of the team.\n\nThe ‘with a wink’ part of this trait needs more discernment when applying it to UI and app content\n(as opposed to marketing content) and remember that it isn’t always appropriate to use. Be mindful\nof where someone is at and what they might be experiencing before going beyond the practical.\n\n#### When to be more practical\n\n- Person is feeling: overwhelmed, unsure, hesitant, stressed.\n- Examples: people with deadlines or being blocked by errors, supporting new or occasional users,\n  introducing new features.\n\n#### When you can add the ‘wink’\n\n- Person is feeling: successful, joy, proud, relief.\n- Examples: power users, during social interactions, success messages.\n\n<br></br>\n\n## Voice and tone principles\n\nAtlassian's personality traits help keep our voice consistent across a range of different customer\nand app experiences. We can better support the full spectrum of experience for people by applying\nthe following principles.\n\nOur voice and tone principles:\n\n- [Inform to build trust](https://atlassian.design/foundations/content/voice-tone#inform-to-build-trust)\n- [Empower to inspire action](https://atlassian.design/foundations/content/voice-tone#empower-to-inspire-action)\n- [Encourage people along the path](https://atlassian.design/foundations/content/voice-tone#encourage-people-along-the-path)\n- [Motivate by showing possibilities](https://atlassian.design/foundations/content/voice-tone#motivate-by-showing-possibilities)\n- [Satisfy by meeting expectations](https://atlassian.design/foundations/content/voice-tone#satisfy-by-meeting-expectations)\n- [Delight with unexpectedly pleasing experiences](https://atlassian.design/foundations/content/voice-tone#delight-with-unexpectedly-pleasing-experiences)\n\n<br></br>\n\n### Inform to build trust\n\nBe open and clear about the experience.\n\n- Tell people only what they need to know in the moment and nothing more.\n- Be aware of when a user may be new or confused, and tone down the boldness by being more\n  prescriptive.\n- Let people know where they are in their journey and what this part of the app will do.\n\nWrite as a knowledgable member of the team. Show up at the right time and be open, humble, and warm.\nOffer direction for the most appropriate next steps.\n\n#### Places to use 'Inform to build trust'\n\n- In-app: [flags](https://atlassian.design/components/flag/usage),\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages),\n  and [spotlights](https://atlassian.design/components/spotlight/usage)\n- New features or apps\n- In confusing, warning, or error states\n\n<br></br>\n\n### Empower to inspire action\n\nEducate where people need it most.\n\n- Offer opportunities to learn at pivotal times to empower people to move in the right direction.\n- Give best practices and recommendations for next steps.\n- Suggest ways to improve or make decisions.\n- Let people know that Atlassian and fellow community members are available to help them make\n  decisions.\n\nWrite as if you are educating. You are a teacher with empathy and an understanding of what it’s like\nto be in the weeds. You expect your audience to have a basic understanding.\n\n#### Places to use 'Empower to inspire action'\n\n- In-app: [spotlights](https://atlassian.design/components/spotlight/usage) and\n  [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- When something requires an action\n- When guidance is needed\n\n<br></br>\n\n### Encourage people along the path\n\nInspire by providing support in the right place. Be consistent and dependable.\n\n- Offer waypoints, help, and support if people are feeling confused or frustrated at points along\n  their journey.\n- Be human: give guidance, support, and encouragement along the way.\n- Guide people by revealing information gracefully. Let them know they’re on the right path, they\n  aren’t alone, and that delivering projects and building teams can be challenging.\n\nWrite in an upbeat, friendly way. Acknowledge the opportunities in the here-and-now and walk through\nit with them.\n\n#### Places to use 'Encourage people along the path'\n\n- In-app:\n  [information messages](https://atlassian.design/foundations/content/designing-messages/info-messages),\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages),\n  and [section messages](https://atlassian.design/components/section-message/usage)\n- When something requires an action\n\n<br></br>\n\n### Motivate by showing possibilities\n\nProvide incentive and enthusiasm for continued growth.\n\n- Consider why someone would want to do this.\n- Show the possibilities of what can be accomplished by giving examples of how other people\n  accomplish the same task or by presenting the ideal state.\n- Describe the end result by giving expert testimony or offer opportunities for advanced knowledge.\n\nWrite like an expert. Focus more on the solution than on the problem. Show people the possible\nbenefits.\n\n#### Places to use 'Motivate by showing possibilities'\n\n- In-app: [spotlights](https://atlassian.design/components/spotlight/usage) and\n  [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- Educational opportunities — it's a chance to give best practices, and tips and tricks\n\n<br></br>\n\n### Satisfy by meeting expectations\n\nGive people what they need.\n\n- All of our content should be practical at a minimum.\n- Provide quick and thorough answers, guidance, actions, and instructions (rather than trying to\n  lead, inspire, motivate, delight, or encourage).\n- Simply tell people what they need to know and get out of the way.\n\nWrite as if you are explaining to your friend how to travel somewhere you’ve visited regularly.\n\n#### Places to use 'Satisfy by meeting expectations'\n\n- In-app:\n  [warning messages](https://atlassian.design/foundations/content/designing-messages/warning-messages),\n  [information messages](https://atlassian.design/foundations/content/designing-messages/info-messages),\n  and\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages)\n- Across all UI and app content\n\n<br></br>\n\n### Delight with unexpectedly pleasing experiences\n\nYou can deliver appropriate delight (a ‘wink’) by celebrating success or progress, but only once\nyou’ve built trust. Don’t overdo it. \n\n- Delight means little flourishes, not humor or being cheeky.\n- Always ask yourself what someone might be feeling at that moment and if delight is appropriate.\n  Also question whether it will be understood or appreciated by our global audience.\n- Think about the timing and how frequently a user will see this. Once may amuse, but a dozen times\n  may annoy.\n\n#### Places to use ‘Delight with unexpectedly pleasing experiences’\n\n- In-app:\n  [success messages](https://atlassian.design/foundations/content/designing-messages/success-messages)\n  and [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- Social interactions, while introducing new experiences",
   keywords: ['voice', 'tone', 'writing', 'content', 'brand']
 }, {
-  content: 'import {\n\tTokenElevationBackgroundChangeExample,\n\tTokenElevationChangeExample,\n} from \'../../../components/interactive-elevations\';\n\n\n\n\n\nElevations are the layered surfaces that form the foundation of the UI. They create a blank canvas\nwhere other UI will be placed, such as text, icons, backgrounds, and borders.\n\n![](./_assets/elevation-layers.png)\n\nMost elevations consist of surfaces and shadows. Together, surfaces and shadows give the impression\nof lift or depth. Elevations can guide focus through layering, or indicate that the UI can be\nscrolled, slid, or dragged.\n\n## Applying elevations\n\nThe elevations use [design tokens](https://atlassian.design/tokens/design-tokens) to apply different\nsurface levels. The highest two elevation surfaces, raised and overlay, are paired with shadows to\ncreate more depth.\n\n![](./_assets/applying-elevations-light.png)\n\n### Elevations in dark theme\n\nShadows can be harder to see in dark mode, so dark mode elevations also rely on different surface\ncolors. Imagine that the surfaces are distantly lit from the front — the higher the elevation, the\nlighter the surface looks.\n\n![](./_assets/applying-elevations-dark-1.png)\n\nRaised and overlay surfaces are still paired with shadows for added depth and consistency in dark\nmode.\n\n![](./_assets/applying-elevations-dark-2.png)\n\n## Types of elevations\n\nThere are four basic elevation levels:\n\n1. [Sunken](#sunken)\n2. [Default](#default)\n3. [Raised](#raised)\n4. [Overlay](#overlay)\n\nThere is also one "[overflow](#overflow)" elevation for special cases.\n\n### Sunken\n\nSunken is the lowest elevation available. The sunken surface creates a backdrop (or well) where\nother content sits. Columns on a Kanban board are a good example of the sunken elevation.\n\nOnly use sunken surfaces on the default surface level. Don’t apply sunken elevations on raised or\noverlay elevations. To differentiate areas of the UI in other ways, use whitespace or borders\ninstead.\n\n![](./_assets/elevation-sunken-1.png)\n\n#### Using `elevation.surface.sunken` vs `color.background.neutral`\n\nAlthough `elevation.surface.sunken` and `color.background.neutral` tokens may appear similar in\nlight mode, they behave differently in dark mode. Here are the main differences between the two:\n\n`elevation.surface.sunken` is an opaque (solid) token that darkens in both light and dark modes. Use\nthis token as a backdrop to group content or elements together (such as a kanban board) on the\ndefault surface.\n\n![](./_assets/elevation-sunken-2.png)\n\n`color.background.neutral` is a token that uses a transparent color. It darkens in light mode and\nlightens in dark mode. Use this token when you need the background to adapt to different elevations,\nwhich is relevant in dark mode since surfaces change depending on what elevation you’re on.\n\n![](./_assets/elevation-sunken-3.png)\n\n### Default\n\nThe default elevation is the baseline with respect to all other layers. It represents a flat UI\nsurface with no visual lift, such as a Confluence page.\n\nUse `elevation.surface` as the starting point for body content when building a UI. To create flat\ncards, pair with a border.\n\n![](./_assets/elevation-surface-1.png)\n\n### Raised\n\nRaised elevations sit slightly higher than default elevations. They are reserved for cards that can\nbe moved, such as Jira and Trello cards. In special circumstances, they can be used for cards as a\nway to provide additional heirarchy or emphasis.\n\nAlways pair `elevation.surface.raised` with `elevation.shadow.raised`. This is particularly\nimportant in dark mode, where raised surfaces are lighter to help differentiate elevations.\n\n![](./_assets/elevation-raised-1.png)\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tUse raised elevations intentionally. If using for emphasis, limit to one section or focal point\n\t\tof the screen.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tRaised elevations can create visual noise, so don’t use to group content when a border or white\n\t\tspace would suffice.\n\t</DoDont>\n</DoDontGrid>\n\n### Overlay\n\nOverlay is the highest elevation available. It is reserved for a UI that sits over another UI, such\nas modals, dialogs, dropdown menus, floating toolbars, and floating single-action buttons.\n\nAlways pair `elevation.surface.overlay` with `elevation.shadow.overlay`. This is important in dark\nmode, where overlay surfaces are lighter to help differentiate elevations.\n\nOverlays can stack on top of other overlays.\n\n![](./_assets/elevation-overlay-1.png)\n\n### Overflow\n\nOverflow is a shadow indicating content has [scrolled](#scrolled) outside a view. It can be used for\nvertical or horizontal scroll. An example of overflow shadows is the horizontal scroll in tables on\na Confluence page.\n\n![](./_assets/elevation-overflow-1.png)\n\nIf box shadows are not technically feasible, use the combination of\n`elevation.shadow.overflow.spread` and `elevation.shadow.overflow.perimeter` to replicate the\noverflow shadow.\n\n## Interaction states\n\n### Hovered and pressed\n\nElevations use surface color changes to communicate hovered and pressed states. Use the hovered and\npressed elevation tokens to create these visual changes.\n\n![](./_assets/elevation-hovered.png)\n\nTransitions between elevations can be used as an alternative to hovered and pressed tokens, but only\nfor default and raised elevations (not overlays):\n\n- Transition to overlay elevation on hover\n- Transition to raised elevation on press\n\nThis approach should be used sparingly to avoid excessive animation. It should not be used for very\nsmall UI, as elevation changes are harder to see than surface color changes at this size.\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tUse the recommended hovered and pressed tokens for interaction states on elevations.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tDon’t combine elevation transitions and hovered and pressed tokens for interactive states. Use\n\t\tone or the other.\n\t</DoDont>\n</DoDontGrid>\n\n#### Background change example\n\n<TokenElevationBackgroundChangeExample />\n\n#### Elevation change example\n\n<TokenElevationChangeExample />\n\n### Dragged\n\nUse the overlay elevation for any UI that is being dragged. Once moved, it returns to its original\nelevation.\n\n![](./_assets/elevation-dragged-1.png)\n\n### Scrolled\n\nWhen scrollable content exceeds the available area, a border or [overflow](#overflow) shadow can be\napplied at the point the content is cut off to indicate there is hidden content that can be scrolled\nback into view.\n\nA border is the default approach for scrolled content and can be seen in modal sticky headers and\nfooters, and top and side navigation.\n\n![](./_assets/elevation-scrolled.png)\n\n[Overflow](#overflow) shadows are reserved for experiences where a border might be easily missed,\nsuch as in very small UI or tables that use borders to separate cells.\n\nBoth approaches should apply the appropriate surface token where the content is being hidden.\n\n## All elevation tokens and values\n\nFor the full list of elevation design tokens and their values, see our\n[design token reference list](https://atlassian.design/components/tokens/all-tokens). Every token\ncomes with a description to help you ensure you’re using the correct one.\n\n## Best practices\n\n### Follow the recommended surface and shadow pairings\n\nRaised and overlay elevations have dedicated surface and shadow pairings.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: pairingDo, alt: \'\' }}>\n\t\tWhen creating elevations, always pair matching surface and shadow tokens.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: pairingDont, alt: \'\' }}>\n\t\tDon\'t mix different shadow and surface elevation tokens.\n\t</DoDont>\n</DoDontGrid>\n\n### Replace elevation surfaces with background colors only when required\n\nElevation surfaces use our\n[neutral palettes](https://atlassian.design/foundations/color#neutral-colors). If a different color\nis needed, surface tokens can be swapped for any solid background token. When using background\ntokens, align to the behavior of\n[interaction states for color tokens](https://atlassian.design/foundations/color#interaction-states).\n\n![](./_assets/background-colors.png)\n\n### Avoid excessive use of raised and overlay elevations\n\nThe shadows and surfaces of raised and overlay elevations can create busy UI if not applied\nintentionally. Follow the recommended guidance when considering these elevations.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: groupingDo, alt: \'\' }}>\n\t\tLimit the use of overlay elevations by grouping related buttons together in a floating toolbar\n\t\tif they are required to sit over another UI.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: groupingDont, alt: \'\' }}>\n\t\tDon’t have more than one floating button next to each other.\n\t</DoDont>\n</DoDontGrid>\n\n### Check contrast ratios\n\nAlways make sure your elevation and background choices are accessible.\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tCheck the contrast ratio for UI on overlay surfaces in dark mode to ensure it meets\n\t\taccessibility requirements.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tDon\'t assume that because UI is accessible in light mode, it will be in dark mode. Some UI may\n\t\tneed tweaking.\n\t</DoDont>\n</DoDontGrid>\n\n## Z-index\n\nThe z-index determines the stacking order of elements. Elements with a higher z-index always sit in\nfront of elements with a lower z-index.\n\nDifferent UI can have the same elevation style, but each UI should apply a different z-index to\nindicate the layer(s) order in a stack (or where the elements touch).\n\n| Z-index | Example usage                                                                     | Elevation level |\n| ------- | --------------------------------------------------------------------------------- | --------------- |\n| 100     | None                                                                              | None            |\n| 200     | [Atlassian navigation](https://atlassian.design/components/atlassian-navigation/) | Default         |\n| 300     | [Inline dialog](https://atlassian.design/components/inline-dialog/)               | Overlay         |\n| 400     | [Popup](https://atlassian.design/components/popup/)                               | Overlay         |\n| 500     | [Blanket](https://atlassian.design/components/blanket/)                           | None            |\n| 510     | [Modal](https://atlassian.design/components/modal-dialog/)                        | Overlay         |\n| 600     | [Flag](https://atlassian.design/components/flag/)                                 | Overlay         |\n| 700     | [Spotlight](https://atlassian.design/components/onboarding/)                      | Overlay         |\n| 800     | [Tooltip](https://atlassian.design/components/tooltip/)                           | None            |\n\n## Related\n\n- Learn about the basics of [design tokens](https://atlassian.design/tokens/design-tokens).\n- See the list of [all design tokens](https://atlassian.design/components/tokens/all-tokens) for\n  full descriptions and values for all tokens.',
-  keywords: ['elevation', 'shadow', 'depth', 'z-index', 'layering', 'design tokens']
+  content: '# Elevation\n\nUse elevation to choose structural surfaces, visual depth, and scroll boundaries for Atlassian UI.\nIdentify the element’s role, host surface, and whether it is interactive. Preserve valid existing\ntreatment; reuse the ADS component’s built-in appearance before styling custom UI. For example,\nModal and Popup own their floating treatment. Consult the selected component before customization;\navoid adding a second shadow or elevated wrapper.\n\nFor custom UI, choose the resting surface and separation first, then derive interaction and drag\nstates. During review, explain the role that justifies any change and identify unresolved host or\ncomponent dependencies.\n\nElevations provide a canvas for text, icons, backgrounds, and borders. Surfaces and shadows\ncommunicate lift or depth and can indicate movable or scrollable content. They do not establish\nkeyboard focus, selection, or stacking order.\n\n## Choose the surface from its purpose\n\nThere are four basic elevation levels: sunken, default, raised, and overlay. Overflow is a special\nshadow for scroll boundaries.\n\n| Purpose                      | Surface                       | Separation or shadow                       |\n| ---------------------------- | ----------------------------- | ------------------------------------------ |\n| Primary page or flat content | `elevation.surface`           | Whitespace; `color.border` for flat cards  |\n| Neutral grouping             | `elevation.surface.container` | Container background; boundary when needed |\n| Recessed grouping on default | `elevation.surface.sunken`    | Recessed backdrop, such as a Kanban column |\n| Movable card                 | `elevation.surface.raised`    | `elevation.shadow.raised`                  |\n| UI floating over other UI    | `elevation.surface.overlay`   | `elevation.shadow.overlay`                 |\n\nDefault is the baseline for page content. A container is a grouping treatment, not another elevation\nlevel. Clickability alone does not require raised elevation.\n\nReserve raised elevation for movable cards. In special circumstances, use it for emphasis, limited\nto one section or focal point. Prefer whitespace, borders, or container backgrounds for ordinary\ngrouping; excessive shadows create visual noise.\n\nOverlay is the highest elevation, for modals, dialogs, dropdown menus, floating toolbars, and\nfloating single-action buttons. Overlays can stack on other overlays. Group related floating actions\nin a floating toolbar; do not place more than one floating button next to another.\n\nAlways pair raised and overlay surfaces with their matching shadows. Do not mix surface and shadow\nlevels. These pairings remain necessary in dark mode.\n\n## Keep interaction treatment consistent\n\nUse the surface’s own hovered and pressed variants when the surface itself is interactive. Apply\nthem to the interactive element; containing controls does not make the surrounding page or group\ninteractive.\n\n| Resting surface               | Hovered surface                       | Pressed surface                       | Shadow                     |\n| ----------------------------- | ------------------------------------- | ------------------------------------- | -------------------------- |\n| `elevation.surface`           | `elevation.surface.hovered`           | `elevation.surface.pressed`           | None                       |\n| `elevation.surface.container` | `elevation.surface.container.hovered` | `elevation.surface.container.pressed` | None                       |\n| `elevation.surface.raised`    | `elevation.surface.raised.hovered`    | `elevation.surface.raised.pressed`    | `elevation.shadow.raised`  |\n| `elevation.surface.overlay`   | `elevation.surface.overlay.hovered`   | `elevation.surface.overlay.pressed`   | `elevation.shadow.overlay` |\n\nA background change does not require an elevation change. The catalog defines no hovered or pressed\nvariants for sunken surfaces; use the treatment of the controls inside them. Look up other\ncombinations rather than constructing token names.\n\nElevation transitions are an alternative only for default and raised surfaces, never overlays:\ntransition to overlay surface and shadow on hover, then raised surface and shadow on press. Use this\nsparingly to avoid excessive animation. Do not use it for very small UI, where surface color changes\nare easier to see. Choose either elevation transitions or hovered/pressed surface tokens; do not\ncombine them. Follow applicable motion and reduced-motion guidance.\n\nUse overlay elevation for any UI being dragged, with its matching surface and shadow. Restore the\noriginal elevation when the drag completes or is cancelled. Follow the drag component’s movement and\naccessibility behavior.\n\nPreserve selection and keyboard-focus cues during hover and press; consult color guidance for those\ntreatments.\n\n## Respect nesting and theme behavior\n\nUse sunken surfaces only on the default elevation. Within raised or overlay surfaces, distinguish\nsections with whitespace or borders.\n\nIn dark mode, shadows are harder to see, so higher elevations also use lighter surface colors. Think\nof surfaces lit from the front: greater height makes the surface appear lighter. A shadow alone does\nnot reproduce raised or overlay treatment. Use tokens in each theme rather than copying light-theme\ncolor values.\n\nAlthough they can look similar in light mode, these backgrounds behave differently:\n\n- `elevation.surface.sunken` is opaque and darkens in both themes. Use it as a recessed backdrop for\n  grouped content on the default surface.\n- `color.background.neutral` is translucent: it darkens in light mode and lightens in dark mode,\n  adapting to the elevation beneath it.\n- `elevation.surface.container` provides neutral container grouping; its rendered appearance can\n  depend on the underlying surface.\n\nElevation surfaces use neutral palettes. Replace a surface with a solid background token only when a\ndifferent color is required. Follow the\n[color interaction-state guidance](https://atlassian.design/foundations/color#interaction-states)\nwhen using background tokens. Choose semantic and selected backgrounds for their meaning or state,\nnot merely because their color resembles a surface.\n\nCheck contrast against the rendered background, including underlying surfaces and overlapping\ntranslucent layers. Do not assume light-mode accessibility carries over to dark mode; check UI on\noverlay surfaces especially.\n\n## Indicate hidden scrollable content\n\nFor vertical or horizontal scrolling, indicate where content has scrolled out of view. Start with a\nborder at the cutoff, as in sticky modal headers and footers or top and side navigation. Apply the\nappropriate surface token where content is hidden.\n\nUse `elevation.shadow.overflow` when a border could be missed, such as very small UI or tables with\ncell borders. Place it at the relevant boundary, not decoratively around every scrollable container.\n\nIf the full overflow shadow is technically infeasible, pair `elevation.shadow.overflow.spread` with\n`elevation.shadow.overflow.perimeter` to replicate it. Follow their token descriptions.\n\n## Distinguish visual depth from stacking\n\nElevation surfaces and shadows communicate visual depth; they do not establish stacking order.\n\nUse the host component’s supported positioning and layering behavior. For components using the\nbrowser top layer, follow that component’s implementation rather than applying a numeric z-index\nrecipe. Check the installed version and migration guidance before changing existing layering.\n\nFor custom UI that uses numbered stacking, consult the\n[ADS z-index reference](https://atlassian.design/foundations/elevation/#z-index) and follow the\nrepository’s layering constraints. Do not derive layer values from elevation tokens or assume that\nincreasing z-index can place content above a top-layer surface.\n\nFor nested overlays, verify visibility, focus, and dismissal. Layering coordination does not replace\nthe host component’s accessibility behavior.\n\n## Retrieve only the missing detail\n\nWhen loaded through the ADS skill, follow its retrieval order.\n\nUse the guidance here first. If a detail is missing, use `atlas ads`; use ADS MCP only after a CLI\nerror, an empty result, or a missing capability. For tokens, search by purpose, then confirm the\nexact token:\n\n```sh\natlas ads search "<purpose>" --type token --limit 5 --json\natlas ads token elevation.surface --json\n```\n\nFor MCP fallback, use `ads_search_tokens` for token usage, `ads_search_components` for component\nAPIs, or `ads_get_a11y_guidelines` for accessibility; follow each tool’s exposed schema. Don’t\nrepeat a successful lookup through another route, fetch the full catalog, or construct tokens by\nappending state suffixes. If a detail remains unresolved, label it unverified and state what still\nneeds checking.\n\n## Verify the result\n\nCheck matching surface/shadow pairs, interaction variants, drag restoration on completion and\ncancellation, scroll indicators at the correct edge, and nested-layer visibility, focus, and\ndismissal. Check text, icons, focus indicators, and meaningful boundaries in supported themes and\nstates. Distinguish verified token names from tested behavior: screenshots alone do not establish\ndrag cancellation, focus, or dismissal.\n\n## Sources\n\nPrinciples: [ADS elevation](https://atlassian.design/foundations/elevation). Exact names, purposes,\nand values: the bundled elevation token reference or\n[design token reference list](https://atlassian.design/components/tokens/all-tokens). Use the\nselected component’s reference for its API and behavior.',
+  name: 'Elevation',
+  keywords: ['elevation', 'shadow', 'depth', 'z-index', 'layering', 'design tokens', 'surfaces', 'containers', 'cards', 'overlays', 'hover', 'press', 'drag', 'scroll boundaries', 'dark mode', 'popup inside modal', 'nested overlays']
 }, {
   content: '## Overview\n\nGrid is a system for arranging content consistently within the main content area of an Atlassian\napp.\n\nIn Figma, grids are set up using\n[Figma layout guides](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides).\nThe code equivalent is built using a combination of [primitives](/components/primitives/overview)\nsuch as box, stack, and inline.\n\nFor everything outside of the main content area, including navigation and panel, see the\n[layout component](/components/navigation-system/layout).\n\n<img\n\tsrc={layoutAnatomy}\n\tsrcDark={layoutAnatomyDark}\n\talt="Layout component anatomy showing the top nav, side nav, main, and panel. Grid sits within main."\n/>\n\n## Grid basics\n\nThe Figma grid component has three basic elements:\n\n- **Columns** divide the main content area into 12 equal parts for horizontal structure.\n- **Gutters** are the gaps between columns, providing consistent separation between content.\n- **Margins** are the empty space between the outer columns and the edge of the main content area.\n  They give content clear space.\n\n<img\n\tsrc={gridAnatomy}\n\tsrcDark={gridAnatomyDark}\n\talt="Figma grid component anatomy showing columns, gutters, and margins."\n/>\n\nAligning content to the columns supports a variety of layouts in the main content area. For example,\ncontent can span 12, 6, or 4 columns.\n\n<img\n\tsrc={columnSpan}\n\tsrcDark={columnSpanDark}\n\talt="Diagram showing content arrangement spanning 12, 6, or 4 grid columns."\n/>\n\nContent can also sit centered within the grid. For example, a centered block can span 8, 10, or 12\ncolumns.\n\n<img\n\tsrc={columnOffset}\n\tsrcDark={columnOffsetDark}\n\talt="Diagram showing content arrangement center-aligned on the grid and spanning 8, 10, or 12 grid columns."\n/>\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridBasicsDo,\n\t\t\turlDarkMode: gridBasicsDoDark,\n\t\t\talt: \'Example of content aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content within the app\'s main content area across any number of columns required.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridBasicsDont,\n\t\t\turlDarkMode: gridBasicsDontDark,\n\t\t\talt: \'Example of content overflowing into grid gutters and margins, breaking visual alignment.\',\n\t\t}}\n\t>\n\t\tDon\'t allow content to overflow into gutters or margins. This breaks visual alignment and makes\n\t\tlayouts unpredictable.\n\t</DoDont>\n</DoDontGrid>\n\n## How to choose what to align to the grid\n\nWithin the main content area, align content containers to the grid columns. Examples include cards,\nimages, text blocks, tables, and forms.\n\nSmall elements, like buttons and icons, do not need to align to this grid. Use\n[space tokens](/foundations/spacing#space-tokens) to manage the space between and within them\ninstead.\n\n<img\n\tsrc={spacingTokens}\n\tsrcDark={spacingTokensDark}\n\talt="Example showing cards aligned to grid columns. The horizontally placed input field and buttons, as well as the content within the card, do not align to the grid columns and are instead managed with space tokens."\n/>\n\nThe same applies within content containers. Only top-level containers need to align to the grid. Use\nspace tokens for the elements inside them, such as cards and table columns.\n\n<img\n\tsrc={contentContainers}\n\tsrcDark={contentContainersDark}\n\talt="Example showing kanban columns aligned to the grid, but the cards within them using space tokens."\n/>\n\nOverlays like modals, tooltips, and dropdown menus also sit outside the grid, as they float above\nthe page content.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: alignContentDo,\n\t\t\turlDarkMode: alignContentDoDark,\n\t\t\talt: \'Example of content containers aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content containers to our grid columns, such as cards, images, text blocks, tables, and\n\t\tforms.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: alignContentDont,\n\t\t\turlDarkMode: alignContentDontDark,\n\t\t\talt: \'Example of buttons and icons incorrectly aligned to the grid columns instead of using space tokens.\',\n\t\t}}\n\t>\n\t\tDon\'t align small elements, such as buttons or icons, to the grid. Instead, use space tokens to\n\t\tmanage their spacing.\n\t</DoDont>\n</DoDontGrid>\n\n## Nested grids\n\nSpace tokens are recommended for aligning content within containers, but you can also apply an\ninternal grid.\n\nWhile the underlying concepts are the same for columns, gutters, and margins, our grid component in\nFigma is only intended for the main content area. When setting up a grid inside a container, use our\n[space tokens](/foundations/spacing#space-tokens).\n\n[Create your own Figma layout guides](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides).\n\n<img\n\tsrc={nestedGrid}\n\tsrcDark={nestedGridDark}\n\talt="Example showing a card sitting on the main grid. The card has its own nested grid."\n/>\n\n## Grid breakpoints\n\nBreakpoints are based on the viewport width, not the width of the main content area. Showing or\nhiding the side navigation or a panel does not change which breakpoint the grid uses.\n\nThese are our default values for the grid in the main content area. Check your app or local system\nfor the specific grid values in use, as they may differ.\n\n<BreakpointsTable />\n\nAt each breakpoint, the gutter width, margin width, and number of columns adjust within the main\ncontent area. Breakpoints also affect layout areas like navigation and panels. For details see the\n[layout component](/components/navigation-system/layout).\n\nDesign for at least two device sizes from the table above, and preferably more. Always include\nmobile (`xxs`).\n\n<img\n\tsrc={gridBreakpoints}\n\tsrcDark={gridBreakpointsDark}\n\talt="Example showing how the grid changes across three breakpoint ranges: m – xl, xs – s, and xxs."\n/>\n\n## Grid types\n\nThere are two types of grid:\n\n- **Fixed grids** have a maximum width and sit centered in the main content area. This default\n  option comes in two sizes: fixed-wide and fixed-narrow.\n- **Fluid grids** fill the available space in the main content area. Use fluid grids when content\n  expands horizontally and has no natural maximum width. Use sparingly, because at very large\n  viewports, text lines can become too long and visual relationships between elements may break\n  down.\n\nWhen the main content area is smaller than the maximum width, such as at smaller breakpoints, fixed\ngrids behave the same as fluid grids.\n\n<img\n\tsrc={gridTypes}\n\tsrcDark={gridTypesDark}\n\talt="Side-by-side comparison of fixed and fluid grids on desktop and mobile viewports."\n/>\n\n### Fixed grids\n\nThere are two fixed grid options:\n\n- **Fixed-wide** has a maximum width of 1296px (including margins). Use this as the default for most\n  experiences.\n- **Fixed-narrow** has a maximum width of 864px (including margins). Use this for long-form content\n  such as blogs and articles, to limit line length and increase readability. Some internal elements,\n  such as headers, may break out of the grid to span across the page.\n\n<img\n\tsrc={fixedGridTypes}\n\tsrcDark={fixedGridTypesDark}\n\talt="Side-by-side comparison of fixed-wide and fixed-narrow grids."\n/>\n\n### Choosing between fixed and fluid grids\n\n| Grid type            | Maximum width (margins included) | Use when                                                    | Examples                                |\n| -------------------- | -------------------------------- | ----------------------------------------------------------- | --------------------------------------- |\n| Fixed-wide (default) | 1296px                           | Content benefits from structure but doesn\'t need full width | Dashboards, directories, search results |\n| Fixed-narrow         | 864px                            | Long-form reading is the primary activity                   | Blogs, articles, documentation          |\n| Fluid                | No maximum                       | Content expands horizontally with no natural maximum width  | Kanban boards, whiteboards              |\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedWideDo,\n\t\t\turlDarkMode: fixedWideDoDark,\n\t\t\talt: \'Example using a fixed-wide grid for a table directory.\',\n\t\t}}\n\t>\n\t\tUse fixed-wide grids for structured content, such as dashboards, search results, and\n\t\tdirectories.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedWideDont,\n\t\t\turlDarkMode: fixedWideDontDark,\n\t\t\talt: \'Example using a fixed-wide grid for long-form content.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-wide grids for long-form content like blogs and articles. Long line lengths\n\t\timpair readability.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedNarrowDo,\n\t\t\turlDarkMode: fixedNarrowDoDark,\n\t\t\talt: \'Example using a fixed-narrow grid for long-form content.\',\n\t\t}}\n\t>\n\t\tUse fixed-narrow grids for long-form content, such as blogs and articles.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedNarrowDont,\n\t\t\turlDarkMode: fixedNarrowDontDark,\n\t\t\talt: \'Example using a fixed-narrow grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-narrow grids for content that needs more horizontal space. Use fixed-wide or\n\t\tfluid instead.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fluidDo,\n\t\t\turlDarkMode: fluidDoDark,\n\t\t\talt: \'Example using a fluid grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tUse fluid grids for content that expands horizontally, such as kanban boards and whiteboards.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fluidDont,\n\t\t\turlDarkMode: fluidDontDark,\n\t\t\talt: \'Example using a fluid grid for a table directory.\',\n\t\t}}\n\t>\n\t\tDon\'t use fluid grids for structured content with a natural width, such as dashboards or\n\t\tdirectories. Elements lose their visual relationship at large viewports.\n\t</DoDont>\n</DoDontGrid>\n\n## Applying grid\n\nThe default grid is already built into the Figma layout component.\n\n1. Select your grid type from the component properties panel.\n2. Choose your breakpoint from the responsive menu in the appearance panel.\n\n<img\n\tsrc={applyingGrid}\n\tsrcDark={applyingGridDark}\n\talt="Screenshot of the Figma layout component with the properties panel showing grid type and responsive selectors."\n/>\n\nYou can also use this grid outside of the layout component. Select it from the assets panel in the\nADS Foundations library, or\n[create your own](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides) using\nyour app\'s values.\n\n**Tip:** Use **Shift + G** (Mac) or **Control + G** (Windows) to show or hide the grid in Figma.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridSpanDo,\n\t\t\turlDarkMode: gridSpanDoDark,\n\t\t\talt: \'Example of the grid spanning the main content area only.\',\n\t\t}}\n\t>\n\t\tSpan only the main content area. Exclude the side nav and panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridSpanDont,\n\t\t\turlDarkMode: gridSpanDontDark,\n\t\t\talt: \'Example of the grid spanning the side nav and main area.\',\n\t\t}}\n\t>\n\t\tDon\'t span the grid across navigation or panel areas.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointSettingDo,\n\t\t\turlDarkMode: breakpointSettingDoDark,\n\t\t\talt: \'Screenshot of the Figma responsive setting in the appearance panel.\',\n\t\t}}\n\t>\n\t\tChange the breakpoint from the responsive setting in the appearance panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointSettingDont,\n\t\t\turlDarkMode: breakpointSettingDontDark,\n\t\t\talt: \'Example of manually resizing the grid component.\',\n\t\t}}\n\t>\n\t\tDon\'t change the breakpoint by resizing the grid or layout component. The linked grid styles\n\t\twill map incorrectly.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointViewportDo,\n\t\t\turlDarkMode: breakpointViewportDoDark,\n\t\t\talt: \'Breakpoint set to the full viewport width.\',\n\t\t}}\n\t>\n\t\tSet the grid breakpoint to the full viewport width.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointViewportDont,\n\t\t\turlDarkMode: breakpointViewportDontDark,\n\t\t\talt: \'Breakpoint set to the content area width only.\',\n\t\t}}\n\t>\n\t\tDon\'t set the breakpoint based on the main content area width. Breakpoints are based on the full\n\t\tviewport width.\n\t</DoDont>\n</DoDontGrid>\n\n## Grid and auto layout\n\nGrid is a layout guide and a visual reference for aligning content to columns. To build layouts in\nFigma that adjust as the breakpoint changes, use auto layout to position content along the grid\ncolumns.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: autoLayoutDo,\n\t\t\turlDarkMode: autoLayoutDoDark,\n\t\t\talt: \'Screenshot of Figma auto layout settings.\',\n\t\t}}\n\t>\n\t\tUse auto layout to build responsive layouts that align to the grid.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: autoLayoutDont,\n\t\t\turlDarkMode: autoLayoutDontDark,\n\t\t\talt: \'Example of manually positioning content in Figma.\',\n\t\t}}\n\t>\n\t\tDon\'t use absolute positioning or drag-to-place content without auto layout. Manual placement\n\t\tdoesn\'t adapt to changing breakpoints and breaks responsive layouts.\n\t</DoDont>\n</DoDontGrid>\n\n## Related\n\n- [Layout](/components/navigation-system/layout) is the component that defines the outer structure\n  of an app, including navigation, panels, and the main content area.\n- [Primitives](/components/primitives/overview) are the box, stack, and inline primitives used to\n  build equivalent layouts in code.\n- [Spacing](/foundations/spacing) uses space tokens to ensure consistent alignment and separation\n  between elements.\n- [ADS Figma libraries](/get-started/design/figma-libraries/atlassians) contain the pre-built grid\n  with default Atlassian breakpoint values.\n- [Auto layout in Figma](https://help.figma.com/hc/en-us/articles/360040451373-Guide-to-auto-layout)\n  is Figma\'s guide to building responsive layouts that align to grid columns.',
   keywords: ['grid', 'layout', 'responsive', 'spacing', 'alignment', 'design system']

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

@@ -1,7 +1,8 @@
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import { avatarXsmallToXxsmall } from './migrations/avatar-xsmall-to-xxsmall';
+import { interactionToEntryPoint } from './migrations/interaction-to-entry-point';
 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 var migrationRegistry = _defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty({}, avatarXsmallToXxsmall.id, avatarXsmallToXxsmall), onboardingJiraSpotlight.id, onboardingJiraSpotlight), onboardingSingleStep.id, onboardingSingleStep), onboardingMultiStep.id, onboardingMultiStep), onboardingWithMotion.id, onboardingWithMotion);
+export var migrationRegistry = _defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty(_defineProperty({}, avatarXsmallToXxsmall.id, avatarXsmallToXxsmall), interactionToEntryPoint.id, interactionToEntryPoint), onboardingJiraSpotlight.id, onboardingJiraSpotlight), onboardingSingleStep.id, onboardingSingleStep), onboardingMultiStep.id, onboardingMultiStep), onboardingWithMotion.id, onboardingWithMotion);

package/dist/esm/tools/migration-guides/migrations/interaction-to-entry-point.js

@@ -0,0 +1,16 @@
+export var interactionToEntryPoint = {
+  id: 'interaction-to-entry-point',
+  title: 'Interaction to EntryPoint migration',
+  description: 'Use when replacing an existing modal, popup, dropdown, or similar interaction boundary with an EntryPoint. It does not apply to new inline UI, API-only work, or test-only changes.',
+  fromPackage: 'product-owned interaction',
+  toPackage: '@atlassian/entry-points',
+  examples: [{
+    title: 'Move a controlled modal to an EntryPoint trigger',
+    description: 'Replace locally owned visibility state and direct rendering with the product-supported trigger and required provider.',
+    before: "\nconst [isOpen, setIsOpen] = useState(false);\n\n<Button aria-haspopup=\"dialog\" onClick={() => setIsOpen(true)}>\n\tOpen modal\n</Button>\n{isOpen && <Modal onClose={() => setIsOpen(false)}>\u2026</Modal>}\n",
+    after: "\n<ModalContextProvider>\n\t<ModalButtonTrigger entryPoint={modalEntryPoint} appearance=\"primary\">\n\t\tOpen modal\n\t</ModalButtonTrigger>\n</ModalContextProvider>\n",
+    explanation: 'The trigger owns visibility while the loaded root receives the supplied close callback. This is a structural example only: confirm the product API, provider requirements, focus return, Escape and outside dismissal, analytics, and any existing controlled-open contract before applying it.'
+  }],
+  bestPractices: ['Read the applicable product and package guides, then inspect the current interaction, its callers, and the shipped target trigger. Identify open/close paths, callbacks, state and data owners, provider lifetime, and the trigger ref, keyboard, disabled, and semantic props.', 'Use a direct conversion only when the supported target contract preserves required behavior. Do not remove public controlled or default-open behavior, manufacture unsupported props, or force a migration by changing requirements.', 'Move deferred UI behind the product-supported lazy root and remove eager value imports that defeat it. Keep preload parameters, queries, runtime props, and injected trigger props separate.', 'Forward the supplied trigger ref and interaction props to the actual control. Keep state, analytics, providers, and close side effects with the owner whose lifetime the existing contract requires.', 'For GraphQL, preload only data available at open time and consume the matching query reference in the lazy UI. Do not hand-edit generated artifacts or replace unrelated data architectures.', 'Trace the launcher through the trigger, EntryPoint, and lazy root to the rendered experience. A disconnected descriptor or unused preload is not a completed migration.', 'Run the smallest supported checks that observe changed behavior. Check opening, closing, callbacks, focus and keyboard behavior, data freshness, loading, and failures only when the original interaction requires them.'],
+  additionalResources: 'Report independently whether the conversion is full, partial, or blocked; whether behavior is preserved, changed, or unresolved; and which checks actually ran. Do not claim performance gains or runtime parity without evidence.'
+};

package/dist/types/tools/get-guidelines/guidelines-structured-content.codegen.d.ts

@@ -3,7 +3,7 @@
  *
  * Structured content for authored agent guidelines and design-system-docs foundations content.
  *
- * @codegen <<SignedSource::425b1c773867acafd317f203d71685ac>>
+ * @codegen <<SignedSource::ff17b8b82e5f2c80a40be5b39e323eab>>
  * @codegenCommand yarn build structured-docs
  */
 export interface GuidelineStructuredContent {

package/dist/types/tools/migration-guides/migrations/interaction-to-entry-point.d.ts

@@ -0,0 +1,2 @@
+import type { MigrationGuide } from '../types';
+export declare const interactionToEntryPoint: MigrationGuide;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/ads-mcp",
-	"version": "1.11.5",
+	"version": "1.11.7",
 	"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",
@@ -24,7 +24,7 @@
 		"@atlaskit/icon": "^38.0.0",
 		"@atlaskit/icon-lab": "^7.11.0",
 		"@atlaskit/platform-feature-flags": "^2.2.0",
-		"@atlaskit/tokens": "^20.7.0",
+		"@atlaskit/tokens": "^20.8.0",
 		"@axe-core/playwright": "^4.11.1",
 		"@axe-core/puppeteer": "^4.11.1",
 		"@babel/runtime": "^7.0.0",