@atlaskit/ads-mcp 1.2.0 → 1.3.0

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

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 export const listGetAllComponentsTool = {
   name: 'ads_get_all_components',
-  description: `Returns **every** Atlassian Design System component record as separate JSON text chunks (full catalog; large payload).
+  description: `Returns **every** canonical Atlassian Design System (ADS) component record as separate JSON text chunks (full catalog; large payload). For non-ADS public \`@atlaskit/*\` packages, use \`atlaskit_get_components\` or \`atlaskit_search_components\`.
 
 WHEN TO USE:
 Last resort when \`ads_plan\` / \`ads_search_components\` is insufficient and you must enumerate all components. Prefer search for normal component picking.

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

@@ -4,10 +4,10 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export const listGetAtlaskitComponentsTool = {
   name: 'atlaskit_get_components',
-  description: `Returns the names and packages of all atlaskit components excluding components covered by the Atlassian Design System.
+  description: `Returns a compact inventory of public \`@atlaskit/*\` component packages that are not covered by the Atlassian Design System (ADS) component catalog. Output is names and packages only.
 
 WHEN TO USE:
-Use this when you want to see what components are available without the full metadata payload.
+Use this for fallback discovery after ADS component search is not enough, or when you need to see which non-ADS \`@atlaskit/*\` components are available without the full metadata payload. For implementation examples and props, use \`atlaskit_search_components\`.
 
 No parameters.`,
   annotations: {

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

@@ -4,10 +4,10 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export const listGetAtlaskitHooksTool = {
   name: 'atlaskit_get_hooks',
-  description: `Returns the names and packages of all atlaskit hooks excluding hooks covered by the Atlassian Design System.
+  description: `Returns a compact inventory of public \`@atlaskit/*\` hooks that are not covered by the Atlassian Design System (ADS) catalog. Output is names and packages only.
 
 WHEN TO USE:
-Use this when you want to see what hooks are available without the full metadata payload.
+Use this for fallback discovery when you need a non-ADS \`@atlaskit/*\` hook inventory without the full metadata payload. For usage guidance, parameters, and return values, use \`atlaskit_search_hooks\`.
 
 No parameters.`,
   annotations: {

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

@@ -4,10 +4,10 @@ import { z } from 'zod';
 import { zodToJsonSchema } from '../../helpers';
 export const listGetAtlaskitUtilitiesTool = {
   name: 'atlaskit_get_utilities',
-  description: `Returns the names and packages of all atlaskit utilities (functions, constants, types) excluding utilities covered by the Atlassian Design System.
+  description: `Returns a compact inventory of public \`@atlaskit/*\` utilities (functions, constants, types) that are not covered by the Atlassian Design System (ADS) catalog. Output is names and packages only.
 
 WHEN TO USE:
-Use this when you want to see what utilities are available without the full metadata payload.
+Use this for fallback discovery when you need a non-ADS \`@atlaskit/*\` utility inventory without the full metadata payload. For usage guidance and signatures, use \`atlaskit_search_utilities\`.
 
 No parameters.`,
   annotations: {

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

@@ -3,7 +3,7 @@
  *
  * Structured content for content guidelines from design-system-docs foundations content.
  *
- * @codegen <<SignedSource::613be582db295e634b62c0f119c15494>>
+ * @codegen <<SignedSource::f7260b1dc10cf36a78f833788065aca6>>
  * @codegenCommand yarn build structured-docs
  */
 
@@ -32,7 +32,7 @@ export const guidelinesStructuredContent = [{
   content: '<SectionMessage title="">\n\tDate and time formatting is tied to a person’s locale and account settings. Because of this, what\n\ta customer sees could be different from the guidelines on this page.\n</SectionMessage>\n\n## Date and time for internationalization\n\nEach programming language has an i18n (internationalization) library that automatically localizes\ntime and date strings based on a user’s locale settings/preferences. Time and date strings should\nnever be localized manually by a designer, engineer, or translator.\n\nThe Product Internationalization team is responsible for creating app UI content in non-English\nlanguages by localizing externalized code strings provided by our Product Engineers.\n\nEngineers must:\n\n- Ensure date and time references/strings are not hardcoded \n- Reference the programming i18n library API, which will automatically format time and date strings\n  as per a customer’s detected or selected locale.\n\n## Date formats\n\nAtlassian uses US date formatting (for example: January 12, 2028).\n\nWhen you’re handing designs over to engineers, you need to specify which date format length is\nneeded. The i18n library API will use this information to format the date accordingly. Date and time\nformats should not be hardcoded.\n\nThere are 4\n[date format lengths](https://cldr.unicode.org/translation/date-time/date-time-patterns#basic-date-formats):\nfull, long, medium, and short.\n\n### Full date\n\nThe full date format is weekday, month, day, year.\n\n<DoDontGrid>\n\t<DoDont type="do">Sunday, August 14, 2028</DoDont>\n</DoDontGrid>\n\n### Long date\n\nA long date format is month, day, year\n\n<DoDontGrid>\n\t<DoDont type="do">November 8, 2008</DoDont>\n</DoDontGrid>\n\n### Medium date\n\nThe medium date format is abbreviated month, day, year. Only use this format when space is limited.\n\n<DoDontGrid>\n\t<DoDont type="do">Sep 26, 1952</DoDont>\n</DoDontGrid>\n\n#### Abbreviating months and days\n\nIf you need to abbreviate months or days, use the first 3 letters of the month or day.\n\n| Month abbreviation | Month in full |     | Day abbreviation | Day in full |\n| ------------------ | ------------- | --- | ---------------- | ----------- |\n| Jan                | January       |     | Mon              | Monday      |\n| Feb                | February      |     | Tue              | Tuesday     |\n| Mar                | March         |     | Wed              | Wednesday   |\n| Apr                | April         |     | Thu              | Thursday    |\n| May                | May           |     | Fri              | Friday      |\n| Jun                | June          |     | Sat              | Saturday    |\n| Jul                | July          |     | Sun              | Sunday      |\n| Aug                | August        |     |                  |             |\n| Sep                | September     |     |                  |             |\n| Oct                | October       |     |                  |             |\n| Nov                | November      |     |                  |             |\n| Dec                | December      |     |                  |             |\n\n### Short date\n\nShort format dates are written in digits.\n\nIn most cases, avoid short format dates as different countries use the date in a different order,\nwhich can cause confusion and effect readability and usability. In the US, 10-8-2026 is October 8,\n2026, but in Australia and the UK, it’s August 10, 2026.\n\nHowever, short format dates might be suitable for situations like data storage, sorting or\nfiltering, or data export/import. If using, use the ISO 8601 international standard for numerical\ndate format, which is YYYY-MM-DD.\n\n## Ordinal numbers\n\nDon’t use ordinal numbers (1st, 2nd, 3rd, and so on) in dates.\n\n## Date ranges\n\nIf you have a date range, use ‘to’ and not hyphens. For example: ‘2020 to 2024’. Hyphens are read\nout by screen readers as ‘hyphen’, which can lead to confusion.\n\nAn exception is financial years, which use a hyphen without spaces on either side. For example:\nFY2008-09\n\nUse ‘and’ if a range is preceded by ‘between’. For example: He was in Paris between 2025 and 2026.\n\n<DoDontGrid>\n\t<DoDont type="do">2014 to 2015</DoDont>\n\t<DoDont type="dont">2014-15</DoDont>\n</DoDontGrid>\n\n## Time formats\n\nShow time in digits for precision and to give a clearer expression of time.\n\nSpecify to engineers which time format length is needed. The i18n library API will then format the\ntime according to a customer’s account settings. Make sure time is not hardcoded.\n\nUse a colon (:) to separate the hours and minutes (though this might change depending on a user’s\nlocale and account settings).\n\nLike dates, there are 4\n[time format lengths](https://cldr.unicode.org/translation/date-time/date-time-patterns#basic-time-formats):\nfull, long, medium, and short.\n\n### Full time\n\nThe full time format is hour, minutes, seconds, and time zone spelt out.\n\n<DoDontGrid>\n\t<DoDont type="do">3:30:10 p.m. Pacific Standard Time</DoDont>\n</DoDontGrid>\n\n### Long time\n\nThe long time format is hour, minutes, seconds, and the time zone initials.\n\n<DoDontGrid>\n\t<DoDont type="do">11:18:30 p.m. PST</DoDont>\n</DoDontGrid>\n\n### Medium time\n\nThe medium time format is hour, minutes, and seconds.\n\n<DoDontGrid>\n\t<DoDont type="do">8:50:28 a.m.</DoDont>\n</DoDontGrid>\n\n### Short time\n\nThe short time format is hour and minutes.\n\n<DoDontGrid>\n\t<DoDont type="do">2:40 p.m.</DoDont>\n</DoDontGrid>\n\n### 24-hour time\n\nThe 24-hour format is useful for more serious communications, for example in the case of outages and\nsecurity comms. The use of the 24-hour format is mostly system-driven by the i18n library API.\n\nThis format numbers hours from 00:00 hours (midnight) to 23:59 and uses 4 digits: the first 2 digits\nare the hours and the next 2 digits are the minutes. Use a colon (:) to separate the hours and\nminutes, though this might change depending on someone\'s account settings.\n\n## Writing time\n\n### Duration and timestamps\n\nWhen writing timestamps, labels on graphs, or durations, avoid using zeros before the hour. For\nexample: 5:29. not 05:29. Use a colon between the hours and minutes with no spaces on either side.\n\n### Using a.m. and p.m.\n\nFormat time using ‘a.m.’ and ‘p.m.’ when creating content like blogs, manuals, and instructions.\n\n- Lowercase ‘a.m.’ and ‘p.m.’\n- Use periods between the letters\n- Add a space between the time and the ‘a.m.’ or ‘p.m.’. For example: 6:30 a.m. (not 6:30a.m.)\n\n### Time range\n\n- If you have a time range that’s entirely in the morning or evening, use \'a.m.\' or \'p.m.\' only\n  once. For example: 6:30 to 10 p.m.\n- If the time range goes from the morning into the evening (or vice versa), use both. For example:\n  10 a.m. to 2 p.m.\n\n### Noon, midday, and midnight\n\nWhere suitable, use ‘noon’, ‘midday’ or ‘midnight’ instead of ‘12 am’ or ‘12 pm’ as it makes it\neasier for people to differentiate between these times.\n\n### Avoid using ‘fortnightly ‘or ‘bi’ for months and years\n\nAvoid using ‘fortnightly’ and the prefix ‘bi’ to mean either 2 or twice, as these terms can be\nconfusing.\n\nInstead of:\n\n- **Fortnightly**: write ‘every 2 weeks’\n- **Bimonthly**: write ‘twice a month’ or ‘every 2 months’\n- **Biannual**: write ‘twice a year’ or ‘every 2 years’.\n\n<DoDontGrid>\n\t<DoDont type="do">Your sprint will repeat every 2 weeks.</DoDont>\n\t<DoDont type="dont">Your sprint will repeat fortnightly.</DoDont>\n</DoDontGrid>\n\n## Date and time formats\n\nThere are also full, long, medium, and short format lengths when combining date and time.\n\n### Full date and time\n\n<DoDontGrid>\n\t<DoDont type="do">Wednesday, June 12, 2024 at 6:25:59 p.m. Eastern Standard Time</DoDont>\n</DoDontGrid>\n\n### Long date and time\n\n<DoDontGrid>\n\t<DoDont type="do">April 25, 2027 at 9:05:32 p.m. PST</DoDont>\n</DoDontGrid>\n\n### Medium date and time\n\n<DoDontGrid>\n\t<DoDont type="do">Sep 5, 1999, 1:25:59 a.m.</DoDont>\n</DoDontGrid>\n\n### Short date and time\n\n<DoDontGrid>\n\t<DoDont type="do">2028-10-22, 6:25 p.m. </DoDont>\n</DoDontGrid>\n\n## Relative date and time\n\nIn some cases, like when the exact date is less important, the easiest way to describe something\nthat happened very recently is using the ‘ago’ format.\n\nFor future and past events, use approximate time by rounding down to the largest or most recent date\nor time.\n\nYou should always provide a way for people to see the actual timestamp, usually via a tooltip.\n\n### Past\n\n| Description                 | Display                      | Display when limited space     |\n| --------------------------- | ---------------------------- | ------------------------------ |\n| Within the last few seconds | just now                     | now                            |\n| Within the last minute      | a minute ago                 | 1 m                            |\n| Within 59 minutes           | x minutes ago                | X m                            |\n| 60 minutes ago              | 1 hour ago                   | 1 h                            |\n| x hours ago                 | x hours ago                  | X h                            |\n| 1 day ago                   | yesterday                    | 1 d                            |\n| 1 day ago (with time)       | yesterday at 5:05 pm         | n/a                            |\n| 2 days ago < 7 days         | x days ago                   | Use the truncated date (Aug 8) |\n| 7 days ago                  | 1 week ago                   | Use the truncated date (Aug 8) |\n| > 7 days ago                | Date stamp: "August 8, 2018" | Use the truncated date (Aug 8) |\n\n### Future\n\n| Description                   | Display                      | Display when limited space     |\n| ----------------------------- | ---------------------------- | ------------------------------ |\n| Within the next few seconds   | shortly                      | now                            |\n| In the next minute            | In 1 minute                  | in 1 m                         |\n| In the next 60 minutes        | In x minutes                 | in X m                         |\n| In 60 minutes                 | In 1 hour                    | in 1 hr                        |\n| In x hours                    | In x hours                   | in X hr                        |\n| In 1 day (by date, not hours) | tomorrow                     | Use the truncated date (Aug 8) |\n| In 2 to 7 days                | In x days                    |                                |\n| In 7 days                     | In 1 week                    |                                |\n| In > 7 days                   | Date stamp: "August 8, 2018" |                                |\n| > 7 days ago                  | Date stamp: "August 8, 2018" |                                |\n\n## Style and punctuation\n\nStyle and punctuation for dates and time can change depending on locale and is determined by the\ni18n library API.\n\n### Capitalization\n\n- Months and days in English are proper nouns and start with a capital letter.\n- Specific days or periods in history are all proper nouns, so should be capitalized. For example:\n  New Year’s Day, Renaissance, Cold War.\n- Use capital letters for all institutional holidays, religious days, and public events. For\n  example: Ramadan, Yom Kippur, Good Friday, Martin Luther King Jr. Day.\n\n### Apostrophes\n\n- Avoid using apostrophes in UI copy and in developer and support documentation.\n- In more casual writing, you can use an apostrophe to stand in for the missing numerals in the\n  year, such as \'the \'70s’.\n\n## Resources\n\n- [Int.DateTimeFormat constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#try_it) -\n  a JavaScript library that devs can use and where designers can check formatting of date and time.\n- [Date formats](https://cldr.unicode.org/translation/date-time/date-time-patterns#basic-date-formats)\n- [Time formats](https://cldr.unicode.org/translation/date-time/date-time-patterns#basic-time-formats)',
   keywords: ['date', 'time', 'formatting', 'localization', 'datetime', 'content']
 }, {
-  content: 'People care about how apps talk to them. YouTube, GitHub, and Slack all have a distinct voice, tone,\nand personality.\n\nApps engage us, manage to make us feel at home, capture our attention, and earn our loyalty.\n\nPoor messaging contributes to a poor user experience, which leads to dissatisfaction. On the other\nhand, good copy reflects our apps\' voice (personality) and enables us to build a better relationship\nwith our audience.\n\nIn short, good messaging may not be the reason people stay with our apps, but bad messaging could be\nthe reason they decide to leave.\n\n## Choose a message type\n\nUse different types of messages to guide people through their tasks. Each message type has a\nconsistent visual and writing style to help people know what to expect.\n\nUse these guidelines to choose and write the types of messages:\n\n- [Information message](https://atlassian.design/foundations/content/designing-messages/info-messages)\n  — provides additional information to motivate people.\n- [Error message](https://atlassian.design/foundations/content/designing-messages/error-messages) —\n  alerts people of a problem that has occurred and informs them what to do next.\n- [Success message](https://atlassian.design/foundations/content/designing-messages/success-messages)\n  — celebrates success along with the people using our apps.\n- [Warning message](https://atlassian.design/foundations/content/designing-messages/warning-messages)\n  — gives advanced notice of a potential change that may result in loss of data or an error state.\n- [Feature discovery](https://atlassian.design/foundations/content/designing-messages/feature-discovery)\n  — lets people know about a new feature.\n\n## Select the right component\n\nUse the table to identify the right component for your content.\n\nFor example:\n\n- If you want to highlight a new feature to a user, consider using spotlight or empty state.\n- If you want to tell someone they\'ve accomplished a task, consider a flag.\n\n| Component           | Information message | Success message | Warning message | Error message | Feature discovery |\n| ------------------- | ------------------- | --------------- | --------------- | ------------- | ----------------- |\n| **Empty state**     | Yes                 | Yes             |                 |               | Yes               |\n| **Banner**          | Yes                 |                 | Yes             | Yes           |                   |\n| **Flag**            | Yes                 | Yes             | Yes             | Yes           |                   |\n| **Section message** | Yes                 |                 | Yes             | Yes           |                   |\n| **Inline message**  | Yes                 | Yes             | Yes             | Yes           |                   |\n| **Modal dialog**    | Yes                 |                 | Yes             |               |                   |\n| **Spotlight**       |                     |                 |                 |               | Yes               |\n\n### Empty state\n\nUse empty states to show when there is nothing to display in a view, for example, when a board has\nno tasks, someone clears their inbox, or a search returns no results.\n\nRead guidance on writing effective\n[empty state messages](https://atlassian.design/foundations/content/designing-messages/empty-state).\n\n<img\n\tsrc={messagesEmptyState}\n\talt="Empty state encouraging an admin to add people to a Jira project space."\n/>\n\nAn empty state can appear as a full-screen message or within panels, tables, and other containers.\n\n[Usage guidance for empty state component](https://atlassian.design/components/empty-state/usage).\n\n### Banner\n\nUse banners only for critical system-level messaging for example, warnings about loss of data or\nfunctionality.\n\n<img src={messagesBanner} alt="Banner message example with a red error message." />\n\nBanners appear at the top of the screen and shift the content below them.\n\n[Usage guidance for banner component](https://atlassian.design/components/banner/usage).\n\n### Flag\n\nUse flags for confirmations, alerts, and acknowledgments that require minimal user interaction.\n\n<img\n\tsrc={messagesFlag}\n\talt="Example of a flag message with a green tick icon, the heading \'You are now connected\', and the text describing a group the user is added to."\n/>\n\nFlags are event-driven messages that appear by overlaying content at the bottom left of the screen,\nemerging from the navigation sidebar.\n\n[Usage guidance for flag component](https://atlassian.design/components/flag/usage).\n\n### Section message\n\nUse section messages to alert the user of something that has happened in a specific section of the\nscreen.\n\n<img\n\tsrc={messagesSectionMessages}\n\talt="Example of a section message showing green tick icon, the heading Merged pull request, details of the pull request, and links to the hash and user name, and the time it happened."\n/>\n\nSection messages appear above the affected area (for example, work items in Jira).\n\n[Usage guidance for section message component](https://atlassian.design/components/section-message/usage).\n\n### Inline message\n\nUse inline messages to alert people to a required action or important information.\n\n<img\n\tsrc={messagesInlineDialog}\n\talt="Example of a cursor on a yellow caution icon triggering an inline dialog message."\n/>\n\nInline messages consist of an icon, message, and sometimes secondary text. People can interact with\nthe icon, title, or secondary text to reveal the full inline message.\n\n[Usage guidance for inline message component](https://atlassian.design/components/inline-message/usage).\n\n### Modal dialog\n\nUse modal dialogs to present a short-term task the user needs to perform.\n\n<img\n\tsrc={messagesModal}\n\talt="A modal that presents a task and a dropdown menu, with a clear action."\n/>\n\nModal dialogs display content in a layer above the page.\n\n[Usage guidance for modal dialog component](https://atlassian.design/components/modal-dialog/usage).\n\n### Spotlight\n\nUse a spotlight to bring attention to a specific part of the UI, such as a button or icon, to\neducate users about key features or workflows.\n\nRead guidance on writing effective\n[feature discovery messages](https://atlassian.design/foundations/content/designing-messages/feature-discovery).\n\n<img\n\tsrc={spotlightSingleStep}\n\talt="Example of a single-step spotlight with content about Jira tasks pointing at a task on a Jira board."\n/>\n\n[Usage guidance for spotlight component](https://atlassian.design/components/spotlight/usage).\n\n## Set the appearance (color and icon)\n\nMessages use colors and icons to help indicate content and urgency.\n\nMake sure you use the right\n[color role for your situation](https://atlassian.design/foundations/color#color-roles). For\nexample, yellow typically implies a warning, while green can imply success.\n\n<img\n\tsrc={colorRolesAndIcons}\n\talt="Icons showing different icons and colors we use in messages. Informative messages use a blue circle icon with an i inside, success is a green check icon, warning is a yelowish triangle icon with an exclamation mark, danger is a red diamond icon with an exclamation mark, and discovery or new is a purple circle with a question mark inside."\n/>\n\nReview [guidelines on using icons](https://atlassian.design/foundations/iconography) and\n[usage guidance for the icon component](https://atlassian.design/components/icon/usage).',
+  content: 'People care about how apps talk to them. YouTube, GitHub, and Slack all have a distinct voice, tone,\nand personality.\n\nApps engage us, manage to make us feel at home, capture our attention, and earn our loyalty.\n\nPoor messaging contributes to a poor user experience, which leads to dissatisfaction. On the other\nhand, good copy reflects our apps\' voice (personality) and enables us to build a better relationship\nwith our audience.\n\nIn short, good messaging may not be the reason people stay with our apps, but bad messaging could be\nthe reason they decide to leave.\n\n## Choose a message type\n\nUse different types of messages to guide people through their tasks. Each message type has a\nconsistent visual and writing style to help people know what to expect.\n\nUse these guidelines to choose and write the types of messages:\n\n- [Information message](https://atlassian.design/foundations/content/designing-messages/info-messages)\n  — provides additional information to motivate people.\n- [Error message](https://atlassian.design/foundations/content/designing-messages/error-messages) —\n  alerts people of a problem that has occurred and informs them what to do next.\n- [Success message](https://atlassian.design/foundations/content/designing-messages/success-messages)\n  — celebrates success along with the people using our apps.\n- [Warning message](https://atlassian.design/foundations/content/designing-messages/warning-messages)\n  — gives advanced notice of a potential change that may result in loss of data or an error state.\n- [Feature discovery](https://atlassian.design/foundations/content/designing-messages/feature-discovery)\n  — lets people know about a new feature.\n\n## Select the right component\n\nUse the table to identify the right component for your content.\n\nFor example:\n\n- If you want to highlight a new feature to a user, consider a spotlight card, benefits modal, or\n  empty state.\n- If you want to tell someone they\'ve accomplished a task, consider a flag.\n\n| Component                                     | Information message | Success message | Warning message | Error message | Feature discovery |\n| --------------------------------------------- | ------------------- | --------------- | --------------- | ------------- | ----------------- |\n| **Empty state**                               | Yes                 | Yes             |                 |               | Yes               |\n| **Banner**                                    | Yes                 |                 | Yes             | Yes           |                   |\n| **Flag**                                      | Yes                 | Yes             | Yes             | Yes           |                   |\n| **Section message**                           | Yes                 |                 | Yes             | Yes           |                   |\n| **Inline message**                            | Yes                 | Yes             | Yes             | Yes           |                   |\n| **Modal dialog**                              | Yes                 |                 | Yes             |               |                   |\n| **Benefits modal**                            |                     |                 |                 |               | Yes               |\n| **Onboarding (spotlight) and spotlight card** |                     |                 |                 |               | Yes               |\n\n### Empty state\n\nUse empty states to show when there is nothing to display in a view, for example, when a board has\nno tasks, someone clears their inbox, or a search returns no results.\n\nRead guidance on writing effective\n[empty state messages](https://atlassian.design/foundations/content/designing-messages/empty-state).\n\n<img\n\tsrc={messagesEmptyState}\n\talt="Empty state encouraging an admin to add people to a Jira project space."\n/>\n\nAn empty state can appear as a full-screen message or within panels, tables, and other containers.\n\n[Usage guidance for empty state component](https://atlassian.design/components/empty-state/usage).\n\n### Banner\n\nUse banners only for critical system-level messaging for example, warnings about loss of data or\nfunctionality.\n\n<img src={messagesBanner} alt="Banner message example with a red error message." />\n\nBanners appear at the top of the screen and shift the content below them.\n\n[Usage guidance for banner component](https://atlassian.design/components/banner/usage).\n\n### Flag\n\nUse flags for confirmations, alerts, and acknowledgments that require minimal user interaction.\n\n<img\n\tsrc={messagesFlag}\n\talt="Example of a flag message with a green tick icon, the heading \'You are now connected\', and the text describing a group the user is added to."\n/>\n\nFlags are event-driven messages that appear by overlaying content at the bottom left of the screen,\nemerging from the navigation sidebar.\n\n[Usage guidance for flag component](https://atlassian.design/components/flag/usage).\n\n### Section message\n\nUse section messages to alert the user of something that has happened in a specific section of the\nscreen.\n\n<img\n\tsrc={messagesSectionMessages}\n\talt="Example of a section message showing green tick icon, the heading Merged pull request, details of the pull request, and links to the hash and user name, and the time it happened."\n/>\n\nSection messages appear above the affected area (for example, work items in Jira).\n\n[Usage guidance for section message component](https://atlassian.design/components/section-message/usage).\n\n### Inline message\n\nUse inline messages to alert people to a required action or important information.\n\n<img\n\tsrc={messagesInlineDialog}\n\talt="Example of a cursor on a yellow caution icon triggering an inline dialog message."\n/>\n\nInline messages consist of an icon, message, and sometimes secondary text. People can interact with\nthe icon, title, or secondary text to reveal the full inline message.\n\n[Usage guidance for inline message component](https://atlassian.design/components/inline-message/usage).\n\n### Modal dialog\n\nUse modal dialogs to present a short-term task the user needs to perform.\n\n<img\n\tsrc={messagesModal}\n\talt="A modal that presents a task and a dropdown menu, with a clear action."\n/>\n\nModal dialogs display content in a layer above the page.\n\n[Usage guidance for modal dialog component](https://atlassian.design/components/modal-dialog/usage).\n\n### Benefits modal\n\nBenefits modals explain the value of a significant new feature or experience change.\n\nRead guidance on writing effective\n[feature discovery messages](https://atlassian.design/foundations/content/designing-messages/feature-discovery).\n\n<img\n\tsrc={messagesBenefitsModal}\n\talt="A modal for a Jira update that includes the key elements of a benefits modal."\n/>\n\nA benefits modal focuses a person\'s attention on a large or impactful update.\n\n[Usage guidance for benefits modal component](https://atlassian.design/components/onboarding/benefits-modal/usage).\n\n### Onboarding (spotlight) and spotlight card\n\nAn onboarding spotlight introduces new features to users through focused messages or multi-step\ntours. A spotlight card is for onboarding messages that need a more flexible layout, or don\'t\nrequire a dialog.\n\nRead guidance on writing effective\n[feature discovery messages](https://atlassian.design/foundations/content/designing-messages/feature-discovery).\n\n<img\n\tsrc={messagesOnboarding}\n\talt="An example of a spotlight pulse expanded into a spotlight component that encourages people to try the new feature."\n/>\n\n[Usage guidance for onboarding (spotlight) component](https://atlassian.design/components/onboarding/usage)\nand [spotlight card component](https://atlassian.design/components/onboarding/spotlight-card/usage).\n\n## Set the appearance (color and icon)\n\nMessages use colors and icons to help indicate content and urgency.\n\nMake sure you use the right\n[color role for your situation](https://atlassian.design/foundations/color#color-roles). For\nexample, yellow typically implies a warning, while green can imply success.\n\n<img\n\tsrc={colorRolesAndIcons}\n\talt="Icons showing different icons and colors we use in messages. Informative messages use a blue circle icon with an i inside, success is a green check icon, warning is a yelowish triangle icon with an exclamation mark, danger is a red diamond icon with an exclamation mark, and discovery or new is a purple circle with a question mark inside."\n/>\n\nReview [guidelines on using icons](https://atlassian.design/foundations/iconography) and\n[usage guidance for the icon component](https://atlassian.design/components/icon/usage).',
   keywords: ['designing messages', 'messages', 'banner', 'flag', 'section message', 'inline message', 'modal', 'empty state', 'content']
 }, {
   content: "An empty state message appears after someone has completed a task or workflow, or has cleared all\ndata associated with certain functionality. For example, clearing their inbox. These messages are a\nway to celebrate, add energy, and motivate people to get on with their next task.\n\nEmpty states can appear within a particular functionality or as a full-screen message. When crafting\nan empty state message, remember that most people scan text instead of reading everything. Make\nevery word count and avoid irrelevant details.\n\n## Writing best practices\n\n### Titles\n\n- Include an informative, scannable title. Try and limit the number of words as much as possible.\n- Titles are a good place to add wink if it’s appropriate.\n- Write in sentence case and don’t use punctuation unless it's a question.\n- Use the heading to describe the empty state or as an opportunity to tell people what they can do.\n\n### Body copy\n\n- Include the reason for the empty state and where they can go next. If there is nothing for them to\n  do, celebrate finishing a task.\n- Avoid repeating content from the title.\n- Keep messages one to two sentences long. Be considerate of people's time and patience. Be short,\n  to the point, and avoid using jargon.\n- Avoid having people look in another location for more information, but if it can't be avoided, use\n  a link to support content.\n\n### Call to action (CTA)\n\n- When offering an action to perform after an empty state, use imperative verbs such as “Try”,\n  “Remove”, or “Create”, in the CTA to describe what action people will be making instead of vague\n  terms such as “OK”.\n- An option to dismiss or cancel lets people feel reassured that they can opt-out.\n- Limit your CTA to one or two words.\n- Your CTA button should always complement the title of the empty state.\n- Empty states are an opportunity to encourage people to interact further with our apps. While\n  optional they’re a good way to educate people about where they can go next or motivate them to\n  explore.\n\nBe careful of how many call to action buttons are on one page. You don’t want to overwhelm people\nwith too many options.\n\n## Voice and tone\n\nYou want to leave people feeling motivated, supported, and delighted. Convey accurate emotions and\nmake sure people know how to respond. Follow some of the following\n[Atlassian voice and tone principles](https://atlassian.design/foundations/content/voice-tone) to\nbuild your message:\n\n### Motivate by showing possibilities\n\nCompleting a task makes people feel ambitious, inspired, curious. Provide people with the incentive\nand excitement for continued growth in our apps.\n\nShow the possibilities of what can be accomplished by presenting them with next steps, or offer\nopportunities for advanced knowledge. This is always better than leaving people at a dead end.\n\n### Delight with unexpectedly pleasing experiences\n\nWe’re celebrating the success or progress of completing a task. Write to convey excitement. You are\ngiving a pat on the back for a job well done.\n\nBut remember not to overdo it. Timing and repetition are critical. Messages that appear more\nfrequently should be more concise and less delightful, for example clearing notifications. If\nmessages are appearing repeatedly, consider multiple versions. These are low commitment experiences,\nwe want to give flowers not puppies.\n\nMessages that appear after a bigger, optimistic action can be more playful, for example, a modal\ndialog. Remember that depending on the component you use, illustrations can also help to add a wink\nto your message.\n\n## Patterns and UX strategies\n\nIf an empty state has more than one potential cause or solution, try one of the following writing\nstrategies.\n\n### An empty state vs. a blank slate message\n\nAn empty state lets people know when they’ve completed or have cleared a task(s). By contrast, a\nblank slate is a type of message in which people have never come across or tried a new feature\nbefore. Blank slates promote and encourage people to try something new.\n\nUse text, design elements, and visual clues to differentiate where people are in their journeys.",
@@ -74,7 +74,7 @@ export const guidelinesStructuredContent = [{
   content: 'Icons are symbols designed to represent concepts or specific features. A company\'s iconography style\ncan express a lot about a brand and its values.\n\nAtlassian\'s iconography has rounded corners and curves to align with our typography and other\nrounded UI elements, whilst square end terminals add boldness to create a harmonious app expression\nof Atlassian\'s broader design language.\n\n## Iconography principles\n\nFollow these principles to design and use Atlassian icons in a cohesive, useful, and legible way.\n\n**Design for universal understanding**\n\nDesign icons that use widely recognized symbols and established visual metaphors. Ensure icons are\neasily understood by a diverse audience by avoiding specific cultural or language aspects.\n\n**Balance simplicity and detail to create legibility**\n\nCraft icons that are simple enough for quick recognition, yet detailed enough to convey meaning\neffectively, even at small sizes.\n\n**Maintain visual harmony**\n\nEnsure icons work together as a cohesive system by adhering to consistent size, shape, and style\nguidelines across the entire set.\n\n**Use icons intentionally**\n\nIcons are powerful signifiers that can aid comprehension and help with navigation. They can also add\nclutter or confuse people when used poorly. Use text labels to support icons wherever possible, and\navoid using icons where they aren’t necessary.\n\n## Using Atlassian icons\n\nAtlassian icons are available as a component (React), Figma library, and in our documentation:\n\n- [View Atlassian icons](https://atlassian.design/components/icon)\n- [Icon component usage](https://atlassian.design/components/icon/usage)\n- [Icon tile component](https://atlassian.design/components/icon/icon-tile)\n- [Figma library of Atlassian icons (Atlassian employees only)](https://go.atlassian.com/ads-icons-figma)\n\n## Visual style\n\nAtlassian’s icon style has a 1.5px stroke width with shapes that pair rounded corners with sharp\ninterior corners and square line caps.\n\n### Simplicity and metaphor\n\nWherever possible, use [existing icons](https://atlassian.design/components/icon) to maintain\nconsistency and reinforce visual concepts across Atlassian apps so they become familiar to\ncustomers.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: consistencyDo, alt: \'\' }}>\n\t\tUse an existing icon or visual metaphor for consistency and clarity wherever possible.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: consistencyDont, alt: \'\' }}>\n\t\tCreate a new icon if a suitable one already exists to represent the same metaphor.\n\t</DoDont>\n</DoDontGrid>\n\nUse simplified shapes with the minimum detail required to express a metaphor. The goal of an icon is\nto aid clear, quick comprehension — excess detail can distract and do the opposite. The small size\nof icons makes it harder to see fine details, so optimise for simplicity and legibility.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: simplifiedShapesDo, alt: \'\' }}>\n\t\tUse simple shapes with the minimum detail required to express a metaphor with clarity and\n\t\tlegibility.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: simplifiedShapesDont, alt: \'\' }}>\n\t\tDon’t add excess detail. This may distract and be challenging to understand at a small sizes.\n\t</DoDont>\n</DoDontGrid>\n\nWhen creating a new icon, use symbols that clearly represent a concept. Try to use metaphors with\nclear and established associations wherever possible.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: metaphorsDo, alt: \'\' }}>\n\t\tUse familiar symbols with clear and established associations that clearly represent a concept.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: metaphorsDont, alt: \'\' }}>\n\t\tUse caution when creating an icon that isn’t a widely recognized symbol. It may be confused with\n\t\tanother concept or misunderstood.\n\t</DoDont>\n</DoDontGrid>\n\n### Perspective and angles\n\nShapes should appear straight on or from a full 90 degree profile. Don’t use diagonal perspectives\nto create 3D shapes because these can be hard to discern at a glance, especially for people with\nsome cognitive disabilities.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: perspectiveDo, alt: \'\' }}>\n\t\tUse shapes that appear straight on without dimensionality.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: perspectiveDont, alt: \'\' }}>\n\t\tDon’t use diagonal perspectives to create 3D shapes as they can be hard to discern at a glance.\n\t</DoDont>\n</DoDontGrid>\n\n### Size and spacing\n\nSystem icons are drawn within a 16 × 16px bounding box and are available in two sizes:\n\n#### Medium (16px) — use in most cases\n\nMedium icons are 16 × 16px in size and are the **default** size in our system. This size balances\nharmoniously with body text and the density of Atlassian’s apps.\n\n#### Small (12px) — Use sparingly\n\nSmall icons are 12 × 12px in size and are downscaled from their 16px counterpart. This size should\nbe used sparingly as they aren\'t as legible as 16px icons. Limit usage of 12px icons to the\nfollowing uses:\n\n- **Chevrons** — always use 12px chevrons, particularly within buttons, icon buttons, and dropdowns\n  to maintain cohesion with Atlassian\'s visual language.\n\n- **Field validation messaging** — use 12px status icons for information, warnings, and errors.\n\n- **Within small contained elements** — 12px icons balance with small text within tags, badges,\n  statuses, and other similar compact elements.\n\n- **App affiliation** — use 12px icons for "Powered by Atlassian Intelligence" or other Atlassian\n  app affiliations.\n\n- **Secondary actions** — use 12px icons to communicate hierarchy between primary way-finding icons\n  and secondary actions so they don’t compete for attention.\n\n- **Supporting role** — use 12px icons for supporting actions that shouldn\'t draw attention away\n  from important content.\n\n![](./_assets/icon_sizing_options.png)\n\nTo apply spacing around an icon, we recommend placing it within a Box primitive with a padding value\napplied from our spacing system.\n\nWhen larger icons sizes are needed for decorative purposes, consider using an\n[icon tile](https://atlassian.design/components/icon/icon-tile) which places the icon on a colored\nbackground tile. Icon tiles are available in multiple sizes and provides accessible icon and\nbackground color pairings.\n\n### Shapes\n\nIcons use consistent shapes to ensure a consistent look and feel across the set. We’ve designed each\nshape for optical scale and balance, so that taller, thinner shapes don’t feel like a different\nscale from shorter or wider shapes.\n\n![](./_assets/Keyline_shapes.png)\n\nWhen designing new icons, you can use our icon template with built-in keyline shapes to guide your\ndesigns.\n\nReusing existing shapes from other icons can also help with consistency across the set. Make sure to\nuse shapes that best represent the object metaphor you are expressing.\n\n### Corners and curves\n\nCurved edges lend to a friendlier feel, but keep internal edges sharp to maintain clarity.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: cornersDo, alt: \'\' }}>\n\t\tWhere possible, keep internal angles sharp.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: cornersDont, alt: \'\' }}>\n\t\tDon’t apply curves on internal anchor points.\n\t</DoDont>\n</DoDontGrid>\n\n### End caps\n\nEnd points should be squared off, not rounded.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: endPointsDo, alt: \'\' }}>\n\t\tSet end point style to "none" to ensure the path aligns with a pixel edge to prevent blurry\n\t\tresults.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: endPointsDont, alt: \'\' }}>\n\t\tDon’t use "round" or "square" stroke end point styles.\n\t</DoDont>\n</DoDontGrid>\n\n### Color\n\nLike most elements in our system, icons use design tokens for colors. Icons can use icon-specific\ncolor tokens or text color tokens for when you\'re matching an icon and text color. You can set the\ncolor of the icon using the\n[icon component](https://atlassian.design/components/icon/code#UNSAFE_IconNew-color).\n\nBoth icon and text color tokens are designed to have enough color contrast against backgrounds and\nsurfaces in Atlassian apps.\n\n## Contribution and adding new icons\n\nCurrently Atlassian teams can contribute icons to our system for new designs and features.\n\n- Before contributing an icon, look at our existing icon library and consider the following\n  questions:\n- Is the icon I’m contributing very similar to another system icon?\n- Can I use an existing multi-purpose icon?\n- Could my icon be confused with another concept that exists in apps?\n- Does this design really require an icon at all? Would a text label, button, or other approach\n  provide a clearer affordance for customer understanding?\n\nTo contribute a new icon, follow the\n[contribution guide (Atlassian employees only)](https://go.atlassian.com/ads-icon-contribution).\n\n## Related\n\n- Browse all icons and learn how to use them in apps with the\n  [icon component](https://atlassian.design/components/icon).',
   keywords: ['iconography', 'icons', 'visual design', 'symbols', 'brand', 'component design']
 }, {
-  content: 'import {\n\tTypographyPrinciples,\n\tTypographyHeadingTable,\n\tTypographyBodyTable,\n\tTypographyMetricTable,\n\tTypographyCodeTable,\n} from \'@af/design-system-docs-ui\';\n\n\n\nimport {\n\tAtlassianLogoCard,\n\tAttributionCards,\n\tPropertyCards,\n\tAppCards,\n} from \'./_logo-asset-cards.partial\';\n\n\n\n\n\n\n\n\n\n<SectionMessage title="Download logos" appearance="information">\n\t<Stack space="space.100">\n\t\t<Text>\n\t\t\tThe full set of app (product) logos are available in{\' \'}\n\t\t\t<Link href="https://orangedam.atlassian.com/">Atlassian Mosaic</Link>.\n\t\t</Text>\n\t\t<Text>\n\t\t\tLogos used to represent third-party integrations are available in{\' \'}\n\t\t\t<Link href="https://atlaskit.stg.atlassian.com/packages/platform-labs/logo-third-party">\n\t\t\t\tAtlaskit staging (Atlassians only)\n\t\t\t</Link>\n\t\t\t.\n\t\t</Text>\n\t</Stack>\n</SectionMessage>\n\nThis page includes downloadable logo files for use in marketing contexts as well as specific usage\nguidance for app or marketing contexts.\n\nIf you want to add logos to app (product) experiences, use the\n[logo component](https://atlassian.design/components/logo/examples).\n\n## Download the logos\n\nEach downloadable file includes variations of color and layout in approved formats and the below\nelements combined together:\n\n- logomarks – the icon portion of a logo\n- wordmarks – the name of the app (product) or property\n- straplines or other secondary text.\n\nAssets for isolated logomarks are also included.\n\n![Annotated graphic of the Atlassian logo, showing the logomark, strapline and wordmark.](./_assets/logo-anatomy.png)\n\n### Our iconic Atlassian logo\n\nOur iconic company logo.\n\nInclude `Atlassian` as the alt-text for the logo in digital experiences.\n\n<AtlassianLogoCard />\n\n#### Atlassian app strapline\n\nThe Atlassian logomark and wordmark can be coupled with a list of app (product) names under it.\nFollow the below guidance when using logos that contain straplines:\n\n- Always centre the app names under the logo and don’t scale the logo below 280px wide.\n- Write Atlassian and the app name in the alt-text in digital experiences.\n\n![Logo strapline with Jira, Confluence, Trello and Bitbucket wordmarks center-aligned beneath the Atlassian logo.](./_assets/logo-centered.png)\n\n### Attribution logos\n\nThe attribution logos are a type of lockup that combine app (product) or property logomarks with the\nAtlassian strapline.\n\nThey create consistency in our portfolio, and help customers connect them with our overall Atlassian\nbrand. Follow the below guidance when using attribution logos:\n\n- Only use attribution logos when the Atlassian context is not clear. For example, in\n  advertisements, videos, and white papers. You don’t need to use them on Atlassian properties like\n  [www.atlassian.com](https://www.atlassian.com) or in app (product) user interfaces.\n- Never compose your own attribution logos or deconstruct the official assets.\n- Write the name of the app (product)/property and Atlassian in the alt-text for in digital\n  experiences.\n\n<AttributionCards />\n\n### Property logos\n\nThe Atlassian program and property logos are a lockup of the Atlassian logomark and wordmark and the\nname in Charlie Sans. Follow the below guidance when using property logos:\n\n- On a white background, the program name is rendered in neutral with the logo in primary blue. On\n  darker backgrounds, both program and logo are white.\n- Write `Atlassian` and the name of the property as the alt-text in digital experiences.\n\n<PropertyCards />\n\n### App (product) logos\n\nWith the Atlassian System of Work and collections framework our primary products, secondary products\nand plaftform features are now referred to as apps.\n\nWe’ve updated our logos to reflect this change, using marks that symbolize functionality, contained\nin a tile. An app’s glyph is chosen based on the apps functionality; its tile color refers to its\ncollection.\n\nThe logomarks are contained by a tile shape, colored with their associated collection. Follow the\nbelow guidance when using App (product) logos:\n\n- Use when the Atlassian context is clear.\n- If you need to connect the app to Atlassian, use an attribution logo instead. For example, in a\n  video or advertisement.\n- Write the name of the apps in the alt-text in digital experiences.\n\nAssets include both isolated logomarks and lockups with wordmarks.\n\n<AppCards />\n\n#### Logomarks\n\nA logomark is a symbol or icon shown without the app (product)/property name or brand workmark. For\nan app (product), this refers to the tile. Follow the below guidance when using logomarks:\n\n- If you’re including the logomark in product experiences, use the\n  [icon](https://atlassian.design/components/logo/examples#icon) variant of the logo component.\n- Only use logomarks on their own when the context is very clear and where possible pair with\n  descriptive text.\n- Write `Atlassian` or the app/property name in the alt-text in digital experiences.\n\n![](./_assets/lockups-nav.png)\n\nLogomarks are paired with native text in top navigations.\n\n![](./_assets/logos-contained-logomarks.png)\n\nLogomarks are suitable when rendering the app name natively in its environment is more legible and\nuser-friendly.\n\n![](./_assets/logos-jira-app-store.png)\n\nLogomarks can be used when environmental restrictions do not allow for proper clearance guidelines\nto be followed for full logos.\n\n#### Logomark shape and size\n\nThe [logo](https://atlassian.design/components/logo) component comes in specific sizes and the\nlogomark has a pre-defined radius. These should not be altered.\n\nThe exception to this is when appearing on external sources such as Apple mobile apps and Google\nMarketplace where specific container shapes need to be used.\n\nLogomarks should never be nested inside additional containers.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: tileRadiusDo, alt: \'\' }}>\n\t\tUse the default radius values that are applied to the backgrounds of app logo icons.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: tileRadiusDont, alt: \'\' }}>\n\t\tDon’t adjust the radius values of the backgrounds of product logo icons.\n\t</DoDont>\n\t<DoDont type="do" image={{ url: containersDo, alt: \'\' }}>\n\t\tAllow breathing room around product logo icons.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: containersDont, alt: \'\' }}>\n\t\tDon’t add unnecessary containers around app logo icons.\n\t</DoDont>\n</DoDontGrid>\n\n### Aligning logos\n\n#### Align logomarks with other elements\n\n- Middle align with the logo mark when the copy is less than the height of the container.\n- Top-align or stack below with center-alignment if it’s taller than the container.\n\n![](./_assets/logos-alignment-ratio.png)\n\n#### Aligning app (product) logos\n\nWhere app (product) logos are arranged in a vertical or horizontal list, use the height or weight of\nthe logomark portion to align.\n\n![](./_assets/tile-align-horizontal.png) ![](./_assets/tile-align-vertical.png)\n\n## Logo clearance\n\nWhen displaying logos outside of an app UI, surround them with clear space free of type, graphics,\nand other elements that might cause visual clutter.\n\n#### Ideal clearance — Atlassian logo\n\n![](./_assets/clearance-horizontal.png) ![](./_assets/clearance-vertical.png)\n\n#### Minimum clearance — Atlassian logo\n\nUse the capital "A" of the Atlassian wordmark to define the minimum clearance around the logo.\n\n![](./_assets/top-bottom-clearance-atlassian.png)\n\n#### Ideal clearance — app (product) logo\n\n![](./_assets/logos-ideal-clearance-app.png)\n\n#### Minimum clearance — app (product) logo\n\nUse the height and width of the logo wordmark to find the minimum clearance around the logo.\n\n![](./_assets/top-bottom-clearance-app.png)\n\n## Color options\n\nLogos are available in three color options to suit different colored environments – Brand, inverse\nand neutral.\n\n![](./_assets/logo-stack-colors.png)\n\nDon’t edit or place logos in ways that reduce the clarity and legibility of the image.\n\n<DoDontGrid>\n\t<DoDont type="dont" image={{ url: colorDont, alt: \'\' }}>\n\t\tDon’t use unapproved color combinations.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: shadowDont, alt: \'\' }}>\n\t\tDon’t use a drop shadow.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: legibilityDont, alt: \'\' }}>\n\t\tDon’t use the logo on top of complex backgrounds.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: outlineDont, alt: \'\' }}>\n\t\tDon’t outline the logo.\n\t</DoDont>\n</DoDontGrid>',
+  content: 'import {\n\tTypographyHeadingTable,\n\tTypographyBodyTable,\n\tTypographyMetricTable,\n\tTypographyCodeTable,\n} from \'@af/design-system-docs-ui\';\n\n\n\nimport {\n\tAtlassianLogoCard,\n\tAttributionCards,\n\tPropertyCards,\n\tAppCards,\n} from \'./_logo-asset-cards.partial\';\n\n\n\n\n\n\n\n\n\n<SectionMessage title="Download logos" appearance="information">\n\t<Text>\n\t\tThe full set of app (product) logos are available in{\' \'}\n\t\t<Link href="https://orangedam.atlassian.com/">Atlassian Mosaic</Link>\n\t</Text>\n</SectionMessage>\n\nThis page includes downloadable logo files for use in marketing contexts as well as specific usage\nguidance for app or marketing contexts.\n\nIf you want to add logos to app (product) experiences, use the\n[logo component](https://atlassian.design/components/logo/examples).\n\n## Download the logos\n\nEach downloadable file includes variations of color and layout in approved formats and the below\nelements combined together:\n\n- logomarks – the icon portion of a logo\n- wordmarks – the name of the app (product) or property\n- straplines or other secondary text.\n\nAssets for isolated logomarks are also included.\n\n![Annotated graphic of the Atlassian logo, showing the logomark, strapline and wordmark.](./_assets/logo-anatomy.png)\n\n### Our iconic Atlassian logo\n\nOur iconic company logo.\n\nInclude `Atlassian` as the alt-text for the logo in digital experiences.\n\n<AtlassianLogoCard />\n\n#### Atlassian app strapline\n\nThe Atlassian logomark and wordmark can be coupled with a list of app (product) names under it.\nFollow the below guidance when using logos that contain straplines:\n\n- Always centre the app names under the logo and don’t scale the logo below 280px wide.\n- Write Atlassian and the app name in the alt-text in digital experiences.\n\n![Logo strapline with Jira, Confluence, Trello and Bitbucket wordmarks center-aligned beneath the Atlassian logo.](./_assets/logo-centered.png)\n\n### Attribution logos\n\nThe attribution logos are a type of lockup that combine app (product) or property logomarks with the\nAtlassian strapline.\n\nThey create consistency in our portfolio, and help customers connect them with our overall Atlassian\nbrand. Follow the below guidance when using attribution logos:\n\n- Only use attribution logos when the Atlassian context is not clear. For example, in\n  advertisements, videos, and white papers. You don’t need to use them on Atlassian properties like\n  [www.atlassian.com](https://www.atlassian.com) or in app (product) user interfaces.\n- Never compose your own attribution logos or deconstruct the official assets.\n- Write the name of the app (product)/property and Atlassian in the alt-text for in digital\n  experiences.\n\n<AttributionCards />\n\n### Property logos\n\nThe Atlassian program and property logos are a lockup of the Atlassian logomark and wordmark and the\nname in Charlie Sans. Follow the below guidance when using property logos:\n\n- On a white background, the program name is rendered in neutral with the logo in primary blue. On\n  darker backgrounds, both program and logo are white.\n- Write `Atlassian` and the name of the property as the alt-text in digital experiences.\n\n<PropertyCards />\n\n### App (product) logos\n\nWith the Atlassian System of Work and collections framework our primary products, secondary products\nand plaftform features are now referred to as apps.\n\nWe’ve updated our logos to reflect this change, using marks that symbolize functionality, contained\nin a tile. An app’s glyph is chosen based on the apps functionality; its tile color refers to its\ncollection.\n\nThe logomarks are contained by a tile shape, colored with their associated collection. Follow the\nbelow guidance when using App (product) logos:\n\n- Use when the Atlassian context is clear.\n- If you need to connect the app to Atlassian, use an attribution logo instead. For example, in a\n  video or advertisement.\n- Write the name of the apps in the alt-text in digital experiences.\n\nAssets include both isolated logomarks and lockups with wordmarks.\n\n<AppCards />\n\n#### Logomarks\n\nA logomark is a symbol or icon shown without the app (product)/property name or brand workmark. For\nan app (product), this refers to the tile. Follow the below guidance when using logomarks:\n\n- If you’re including the logomark in product experiences, use the\n  [icon](https://atlassian.design/components/logo/examples#icon) variant of the logo component.\n- Only use logomarks on their own when the context is very clear and where possible pair with\n  descriptive text.\n- Write `Atlassian` or the app/property name in the alt-text in digital experiences.\n\n![](./_assets/lockups-nav.png)\n\nLogomarks are paired with native text in top navigations.\n\n![](./_assets/logos-contained-logomarks.png)\n\nLogomarks are suitable when rendering the app name natively in its environment is more legible and\nuser-friendly.\n\n![](./_assets/logos-jira-app-store.png)\n\nLogomarks can be used when environmental restrictions do not allow for proper clearance guidelines\nto be followed for full logos.\n\n#### Logomark shape and size\n\nThe [logo](https://atlassian.design/components/logo) component comes in specific sizes and the\nlogomark has a pre-defined radius. These should not be altered.\n\nThe exception to this is when appearing on external sources such as Apple mobile apps and Google\nMarketplace where specific container shapes need to be used.\n\nLogomarks should never be nested inside additional containers.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: tileRadiusDo, alt: \'\' }}>\n\t\tUse the default radius values that are applied to the backgrounds of app logo icons.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: tileRadiusDont, alt: \'\' }}>\n\t\tDon’t adjust the radius values of the backgrounds of product logo icons.\n\t</DoDont>\n\t<DoDont type="do" image={{ url: containersDo, alt: \'\' }}>\n\t\tAllow breathing room around product logo icons.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: containersDont, alt: \'\' }}>\n\t\tDon’t add unnecessary containers around app logo icons.\n\t</DoDont>\n</DoDontGrid>\n\n### Aligning logos\n\n#### Align logomarks with other elements\n\n- Middle align with the logo mark when the copy is less than the height of the container.\n- Top-align or stack below with center-alignment if it’s taller than the container.\n\n![](./_assets/logos-alignment-ratio.png)\n\n#### Aligning app (product) logos\n\nWhere app (product) logos are arranged in a vertical or horizontal list, use the height or weight of\nthe logomark portion to align.\n\n![](./_assets/tile-align-horizontal.png) ![](./_assets/tile-align-vertical.png)\n\n## Logo clearance\n\nWhen displaying logos outside of an app UI, surround them with clear space free of type, graphics,\nand other elements that might cause visual clutter.\n\n#### Ideal clearance — Atlassian logo\n\n![](./_assets/clearance-horizontal.png) ![](./_assets/clearance-vertical.png)\n\n#### Minimum clearance — Atlassian logo\n\nUse the capital "A" of the Atlassian wordmark to define the minimum clearance around the logo.\n\n![](./_assets/top-bottom-clearance-atlassian.png)\n\n#### Ideal clearance — app (product) logo\n\n![](./_assets/logos-ideal-clearance-app.png)\n\n#### Minimum clearance — app (product) logo\n\nUse the height and width of the logo wordmark to find the minimum clearance around the logo.\n\n![](./_assets/top-bottom-clearance-app.png)\n\n## Color options\n\nLogos are available in three color options to suit different colored environments – Brand, inverse\nand neutral.\n\n![](./_assets/logo-stack-colors.png)\n\nDon’t edit or place logos in ways that reduce the clarity and legibility of the image.\n\n<DoDontGrid>\n\t<DoDont type="dont" image={{ url: colorDont, alt: \'\' }}>\n\t\tDon’t use unapproved color combinations.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: shadowDont, alt: \'\' }}>\n\t\tDon’t use a drop shadow.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: legibilityDont, alt: \'\' }}>\n\t\tDon’t use the logo on top of complex backgrounds.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: outlineDont, alt: \'\' }}>\n\t\tDon’t outline the logo.\n\t</DoDont>\n</DoDontGrid>',
   keywords: ['logos', 'brand', 'identity', 'logo usage', 'brand guidelines']
 }, {
   content: '## About radius tokens\n\nRadius tokens standardize corner roundness, ensuring consistency and cohesion throughout all of our\napps. Pair radius tokens with radius focus tokens to bring focus to the selected element. This helps\nusers identify which element is active.\n\n## Radius tokens and usage guidelines\n\nUse radius tokens to apply roundness across different states and use cases.\n\n<Stack space="space.200">\n\t<RadiusTable />\n\t<Text>* Token values are subject to change and should be used as an indication only.</Text>\n</Stack>\n\n## Radius examples and usage\n\n### Extra small\n\nUse the `radius.xsmall` token for extra small detail elements like badges, checkboxes, avatar\nlabels, and keyboard shortcuts.\n\n![Two examples, one of checkboxes and one of keyboard shortcuts in a tooltip, both of which use the "radius.xsmall" token.](./_assets/radius-xsmall.png)\n\n### Small\n\nUse the `radius.small` token for small elements like labels, lozenges, timestamps, tags, dates,\ntooltip containers, imagery inside tables, and compact buttons.\n\n![Examples of lozenges, tooltips, dates and photos in a section that all use the "radius.small" token.](./_assets/radius-small.png)\n\n### Medium\n\nUse the `radius.medium` token for interactive elements like buttons, inputs, text areas, selects,\nnavigation items, and smart links.\n\n![Examples of buttons, smart links, text fields, dropdowns, and navigation menu items all using the "radius.medium" token.](./_assets/radius-medium.png)\n\n### Large\n\nUse the `radius.large` token for elements like cards, in-page containers, floating UIs, and dropdown\nmenus.\n\n![Two examples, one of a progress summary card and one of a Jira work item on a board, both of which use the "radius.large" token.](./_assets/radius-large.png)\n\n### Extra large\n\nUse the `radius.xlarge` token for full-page containers, large containers, modal dialogs, Kanban\ncolumns, and tables.\n\n![Two examples, one of a confirmation dialog and one of a table, both of which use the "radius.xlarge" token.](./_assets/radius-xlarge.png)\n\n### Extra extra large\n\nUse the `radius.xxlarge` token for video players.\n\n![An example of the Loom video player using the "radius.xxlarge" token.](./_assets/radius-xxlarge.png)\n\n### Full\n\nUse the `radius.full` token for avatars, names, user-related UI, and emoji reactions. This token can\nalso be used for dividers and other pill-shaped elements since it results in a fully round radius.\n\n![A mix of circular and pill-shaped examples of avatars, user mentions, and name cursors all using the "radius.full" token.](./_assets/radius-full.png)\n\n### Tile\n\nUse the `radius.tile` token exclusively for tile components, such as icon tile or object tile. This\ntoken should not be used outside of tiles.\n\n![An example of tile objects all using the "radius.tile" token.](./_assets/radius-tile.png)\n\n## Radius token for focus state\n\nA component\'s focus state is critical for accessibility. The corner radius of the focus ring must\nalign visually with the component it surrounds.\n\n### Focus state design specifications\n\n![Diagram showing an interactive element with a blue focus ring offset by 2px. A note explains “Focus ring radius = element radius + 2px,” illustrating how the focus ring\'s corner radius is calculated relative to the component.](./_assets/focus-ring-1.png)\n\nThe focus ring is implemented in two key ways:\n\n1. **Offset**: The focus ring is positioned 2px away from the component\'s bounding box.\n2. **Radius value**: The corner radius of the focus ring is always +2px greater than the component’s\n   base corner radius value.\n\n### How to implement the focus ring for code and design\n\nThe focus ring is managed differently between code and design:\n\n- **In code**: When you’re using interactive design system components, focus rings are automatically\n  applied. When you’re building custom components, use the\n  [focusable component](https://atlassian.design/components/primitives/focusable/examples). The 2px\n  visual offset and the radius calculation (component radius +2px) are automatically handled by the\n  focusable component\'s logic. This means developers never need to apply a separate radius token for\n  the focus state.\n- **In design**: Automatic calculations aren’t possible in design tools, so designers must use a\n  dedicated set of tokens to enforce the correct radius relationship. These tokens mirror the\n  component radius names but carry the calculated +2px value to ensure visual accuracy in design\n  files.\n\n![Diagram of a button showing the base radius of "radius.medium" and its corresponding focus‑state radius token "radius.focus.medium" relationship.](./_assets/focus-ring-2.png)\n\n<Stack space="space.200">\n\t<RadiusFocusTable />\n\t<Text>* Token values are subject to change and should be used as an indication only.</Text>\n</Stack>',
@@ -98,7 +98,7 @@ export const guidelinesStructuredContent = [{
   content: "Understand how to use design tokens when applying our foundations in your designs.\n\n## Before you begin\n\nMake sure you understand the basics of\n[design tokens](https://atlassian.design/tokens/design-tokens).\n\n## Using tokens in Figma\n\n1. Get access to our Figma libraries with design tokens built-in as styles and in components.\n   [Access Figma libraries](https://atlassian.design/get-started/figma-libraries).\n\n2. Install and use the\n   [Atlassian Design Tokens Figma plugin](https://www.figma.com/community/plugin/1144189860740169808/Atlassian-Design-Tokens)\n   to simplify finding and applying Atlassian design tokens in your designs.\n   ![](./_assets/figma-plugin.png)\n\n3. (Atlassian employees only) Use the Figma plugin convert old design files to use design tokens,\n   and to convert your designs to dark mode.\n\n## Review tokens and styles in your app\n\nView new colors and styles in your app during migration using the\n[Chrome plugin (Atlassians only)](https://go.atlassian.com/dst-chrome-theme-plugin).\n\nNew colors and other values won’t be visible until each app officially releases their changes when\nafter testing is complete. The chrome plugin allows you to view the latest tokens behind the scenes\nduring testing.\n\n## What's next\n\n- Search all of our available design tokens and their descriptions in\n  [all tokens](https://atlassian.design/components/tokens/all-tokens).\n- For extra help choosing the right token, use our\n  [Token picker](https://atlassian.design/components/tokens/all-tokens?isTokenPickerOpen=true).\n- Review new usage guidance in our color, elevation, and spacing\n  [foundations](https://atlassian.design/foundations).\n- Check out our\n  [design tokens onboarding video resources (for Atlassians only)](https://go.atlassian.com/design-token-onboarding).\n\n## Get help\n\n- Atlassians can get help with tokens in [Slack](https://go.atlassian.com/help-design-system).\n- For general help with the Atlassian Design system,\n  [contact us](https://atlassian.design/contact-us).",
   keywords: ['design tokens in design', 'figma', 'design tools', 'design workflow']
 }, {
-  content: "import {\n\tTypographyPrinciples,\n\tTypographyHeadingTable,\n\tTypographyBodyTable,\n\tTypographyMetricTable,\n\tTypographyCodeTable,\n} from '@af/design-system-docs-ui';\n\n## Overview\n\nWe have moved our app suite to a refreshed typography system. Using our\n[app (product) typefaces](https://atlassian.design/foundations/typography/product-typefaces-and-scale),\nAtlassian Sans and Atlassian Mono, will create a consistent experience across all browsers. As apps\nmove to this system, we provide support to help transition smoothly between systems.\n\n## Typographic principles\n\nFollow these principles to create legible and visually balanced typography. Use in conjunction with\nthe Atlassian [color tokens](https://atlassian.design/foundations/color) and\n[space tokens](https://atlassian.design/foundations/spacing) in app experiences.\n\n<TypographyPrinciples />\n\n## Brand fonts\n\nWhen you need to express the Atlassian brand, such as in marketing, we use our custom brand font,\nCharlie Sans. Only authenticated users can download our\n[brand fonts](https://brandfolder.com/atlassian-brand-creative-library/atlassian-public-asset-library).\n\n![](./_assets/brand-banner.png)\n\n## App fonts\n\nFor all in-app experiences, we use our Atlassian fonts,\n[Atlassian Sans](https://atlassian.design/foundations/typography/product-typefaces-and-scale#atlassian-sans)\nand\n[Atlassian Mono](https://atlassian.design/foundations/typography/product-typefaces-and-scale#atlassian-mono).\nThis ensures the UI is optimized, performs well and is frictionless as you move between Atlassian\napps and experiences regardless of platform. For apps not yet using our refreshed system, we use\nsystem fonts via our modernized or legacy systems.\n\nAll app fonts are available for download in [Atlassian Mosaic](https://orangedam.atlassian.com/) in\nTTF format.\n\n![](./_assets/app-fonts.png)\n\n## Text styles and tokens\n\nText styles and typography tokens are made up of specific font values, including font family, font\nsize, and line height. Where text styles appear in design and Figma, typography tokens are used in\ncode.\n\nUse heading, body and code text styles and tokens in your designs. Each style has optimized spacing\nvalues based on font size, and is designed to work with our other foundations such as spacing and\ncolor. These typographic decisions are built into typography tokens and will enable typography\ntheming in the future.\n\nWe also recommend using heading and text components in code to simplify implementation of typography\ntokens.\n\nLearn more about\n[applying typography tokens and text styles](https://atlassian.design/foundations/typography/applying-typography/).\n\n![](./_assets/text-styles.png)\n\n### Rem units in tokens\n\nTypography tokens use\n[rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units)\ninstead of pixel values for font-size and line-heights. Font size is calculated dynamically by\nmultiplying the rem unit with the browser default size of 16px (i.e. 1rem is equal to 16px).\n\nUnlike pixels which are absolute (or fixed), rem are relative units that adjust according to the\nroot element (html) size. Using rem units allow users to adjust the size of text depending on their\nneeds or browser size, improving the responsiveness and accessibility of designs.\n\n### Heading\n\nUse headings for page titles or subheadings to introduce content. Headings are sized to contrast\nwith content, increase visual hierarchy, and help readers easily understand the structure of\ncontent.\n\nHeadings should be used to introduce a new section of content. Use heading styles, rather than bold\nor a change of font size, as they’re important for accessibility.\n\nHeading levels help users navigate a page, especially users of screen readers and other assistive\ntechnology. Using the right heading levels also helps to group content so it’s easier to scan.\n\nHeading levels (`<h1>` to `<h6>`) should be used in a descending sequence. Only use one h1 per page\n(usually the page title) and don’t skip a level (for example, use an h2 then an h4).\n\n![](./_assets/heading1.png)\n\nHeadings come in a range of sizes, for use in different contexts:\n\n- **XXL** and **XL** are suitable for brand and marketing content.\n- **XL** and **L** are suitable for page titles in apps such as a form title.\n- **M** can be used in large components where space is not limited and perfectly balances with Body\n  M, such as modals.\n- **S** and **XS** are for titles in small components where space is limited, such as flags.\n- **XXS** should be used sparingly and is suitable when matched with Body S, for example, in fine\n  print.\n\n![](./_assets/heading2.png) ![](./_assets/heading3.png)\n\n<TypographyHeadingTable />\n\n### Body\n\nUse body text for main content. They typically appear after headings or subheadings as detailed\ndescriptions and messages, but also as standalone text in components. Body text includes additional\nparagraph spacing for readability and flow in blocks of text.\n\nBody text comes in three sizes, for use in different contexts:\n\n- **Body L** is the default size for long-form content. Use this size for a comfortable reading\n  experience such as in blogs.\n- **Body M (Default)** is the default size in components or where space is limited, for detailed or\n  descriptive content such as primary descriptions in flags.\n- **Body S** should be used sparingly and is for secondary level content such as fine print or\n  semantic messaging.\n\n![](./_assets/body-l.png) ![](./_assets/body-m.png) ![](./_assets/body-s.png)\n\n<TypographyBodyTable />\n\n\\* See paragraph spacing below.\n\n#### Paragraph spacing\n\nParagraph spacing is set in Figma text style libraries only. To represent paragraphs in code, use\nseparate text components for each paragraph and manage paragraph spacing with the\n[stack component](https://atlassian.design/components/primitives/stack/examples).\n\n#### Body font weight\n\nFont weight is applied through the choice of text style in Figma, or through font weight tokens in\ncode. Three weights are available for body text:\n\n- **Regular** weight is for generic paragraphs to contrast with headings, and medium text in\n  components.\n- **Medium** weight is for alignment with iconography. Use this weight in most components and\n  whenever text could be seen beside line icons.\n- **Bold** weight is for unique cases where text needs to be differentiated or given more emphasis.\n  Use this weight sparingly.\n\n![](./_assets/weight-regular.png) ![](./_assets/weight-medium.png) ![](./_assets/weight-bold.png)\n\n### Metric\n\nUse metric when you want to emphasize certain numbers. Understand when to use this style, with our\ndo and don’t examples.\n\n[Metric style do and don't examples](https://atlassian.design/foundations/typography/applying-typography#metric)\n\n![](./_assets/metric1.png) ![](./_assets/metric2.png)\n\n<TypographyMetricTable />\n\n### Code\n\nThe code text style is reserved for representing code in our\n[code block component](https://atlassian.design/components/code/code-block/).\n\n<TypographyCodeTable />\n\nCode can also appear [inline](https://atlassian.design/components/code/examples) following the style\nsettings of the block of text it sits within. In this context, this token is relative to its\ncontainer's font size. Assuming a container font size of 14 px (0.875 rem), this token will have a\nfont size of 12.25 px. The line height is equal to the font size.",
+  content: "import {\n\tTypographyHeadingTable,\n\tTypographyBodyTable,\n\tTypographyMetricTable,\n\tTypographyCodeTable,\n} from '@af/design-system-docs-ui';\n\n\n\n## Overview\n\nWe have moved our app suite to a refreshed typography system. Using our\n[app (product) typefaces](https://atlassian.design/foundations/typography/product-typefaces-and-scale),\nAtlassian Sans and Atlassian Mono, will create a consistent experience across all browsers. As apps\nmove to this system, we provide support to help transition smoothly between systems.\n\n## Typographic principles\n\nFollow these principles to create legible and visually balanced typography. Use in conjunction with\nthe Atlassian [color tokens](https://atlassian.design/foundations/color) and\n[space tokens](https://atlassian.design/foundations/spacing) in app experiences.\n\n<FeatureBlockGrid columns={3}>\n\t{principles.map((item) => (\n\t\t<FeatureBlock key={item.title} {...item} headingLevel=\"h3\" />\n\t))}\n</FeatureBlockGrid>\n\n## Brand fonts\n\nWhen you need to express the Atlassian brand, such as in marketing, we use our custom brand font,\nCharlie Sans. Only authenticated users can download our\n[brand fonts](https://brandfolder.com/atlassian-brand-creative-library/atlassian-public-asset-library).\n\n![](./_assets/brand-banner.png)\n\n## App fonts\n\nFor all in-app experiences, we use our Atlassian fonts,\n[Atlassian Sans](https://atlassian.design/foundations/typography/product-typefaces-and-scale#atlassian-sans)\nand\n[Atlassian Mono](https://atlassian.design/foundations/typography/product-typefaces-and-scale#atlassian-mono).\nThis ensures the UI is optimized, performs well and is frictionless as you move between Atlassian\napps and experiences regardless of platform. For apps not yet using our refreshed system, we use\nsystem fonts via our modernized or legacy systems.\n\nAll app fonts are available for download in [Atlassian Mosaic](https://orangedam.atlassian.com/) in\nTTF format.\n\n![](./_assets/app-fonts.png)\n\n## Text styles and tokens\n\nText styles and typography tokens are made up of specific font values, including font family, font\nsize, and line height. Where text styles appear in design and Figma, typography tokens are used in\ncode.\n\nUse heading, body and code text styles and tokens in your designs. Each style has optimized spacing\nvalues based on font size, and is designed to work with our other foundations such as spacing and\ncolor. These typographic decisions are built into typography tokens and will enable typography\ntheming in the future.\n\nWe also recommend using heading and text components in code to simplify implementation of typography\ntokens.\n\nLearn more about\n[applying typography tokens and text styles](https://atlassian.design/foundations/typography/applying-typography/).\n\n![](./_assets/text-styles.png)\n\n### Rem units in tokens\n\nTypography tokens use\n[rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units)\ninstead of pixel values for font-size and line-heights. Font size is calculated dynamically by\nmultiplying the rem unit with the browser default size of 16px (i.e. 1rem is equal to 16px).\n\nUnlike pixels which are absolute (or fixed), rem are relative units that adjust according to the\nroot element (html) size. Using rem units allow users to adjust the size of text depending on their\nneeds or browser size, improving the responsiveness and accessibility of designs.\n\n### Heading\n\nUse headings for page titles or subheadings to introduce content. Headings are sized to contrast\nwith content, increase visual hierarchy, and help readers easily understand the structure of\ncontent.\n\nHeadings should be used to introduce a new section of content. Use heading styles, rather than bold\nor a change of font size, as they’re important for accessibility.\n\nHeading levels help users navigate a page, especially users of screen readers and other assistive\ntechnology. Using the right heading levels also helps to group content so it’s easier to scan.\n\nHeading levels (`<h1>` to `<h6>`) should be used in a descending sequence. Only use one h1 per page\n(usually the page title) and don’t skip a level (for example, use an h2 then an h4).\n\n![](./_assets/heading1.png)\n\nHeadings come in a range of sizes, for use in different contexts:\n\n- **XXL** and **XL** are suitable for brand and marketing content.\n- **XL** and **L** are suitable for page titles in apps such as a form title.\n- **M** can be used in large components where space is not limited and perfectly balances with Body\n  M, such as modals.\n- **S** and **XS** are for titles in small components where space is limited, such as flags.\n- **XXS** should be used sparingly and is suitable when matched with Body S, for example, in fine\n  print.\n\n![](./_assets/heading2.png) ![](./_assets/heading3.png)\n\n<TypographyHeadingTable />\n\n### Body\n\nUse body text for main content. They typically appear after headings or subheadings as detailed\ndescriptions and messages, but also as standalone text in components. Body text includes additional\nparagraph spacing for readability and flow in blocks of text.\n\nBody text comes in three sizes, for use in different contexts:\n\n- **Body L** is the default size for long-form content. Use this size for a comfortable reading\n  experience such as in blogs.\n- **Body M (Default)** is the default size in components or where space is limited, for detailed or\n  descriptive content such as primary descriptions in flags.\n- **Body S** should be used sparingly and is for secondary level content such as fine print or\n  semantic messaging.\n\n![](./_assets/body-l.png) ![](./_assets/body-m.png) ![](./_assets/body-s.png)\n\n<TypographyBodyTable />\n\n\\* See paragraph spacing below.\n\n#### Paragraph spacing\n\nParagraph spacing is set in Figma text style libraries only. To represent paragraphs in code, use\nseparate text components for each paragraph and manage paragraph spacing with the\n[stack component](https://atlassian.design/components/primitives/stack/examples).\n\n#### Body font weight\n\nFont weight is applied through the choice of text style in Figma, or through font weight tokens in\ncode. Three weights are available for body text:\n\n- **Regular** weight is for generic paragraphs to contrast with headings, and medium text in\n  components.\n- **Medium** weight is for alignment with iconography. Use this weight in most components and\n  whenever text could be seen beside line icons.\n- **Bold** weight is for unique cases where text needs to be differentiated or given more emphasis.\n  Use this weight sparingly.\n\n![](./_assets/weight-regular.png) ![](./_assets/weight-medium.png) ![](./_assets/weight-bold.png)\n\n### Metric\n\nUse metric when you want to emphasize certain numbers. Understand when to use this style, with our\ndo and don’t examples.\n\n[Metric style do and don't examples](https://atlassian.design/foundations/typography/applying-typography#metric)\n\n![](./_assets/metric1.png) ![](./_assets/metric2.png)\n\n<TypographyMetricTable />\n\n### Code\n\nThe code text style is reserved for representing code in our\n[code block component](https://atlassian.design/components/code/code-block/).\n\n<TypographyCodeTable />\n\nCode can also appear [inline](https://atlassian.design/components/code/examples) following the style\nsettings of the block of text it sits within. In this context, this token is relative to its\ncontainer's font size. Assuming a container font size of 14 px (0.875 rem), this token will have a\nfont size of 12.25 px. The line height is equal to the font size.",
   keywords: ['typography', 'typeface', 'fonts', 'text', 'readability', 'design tokens']
 }, {
   content: "## Typography tokens and text styles\n\nUse text styles when designing in Figma, and typography tokens and components in code. Use the\n[heading component](https://atlassian.design/components/heading/examples) for heading text, and the\n[text component](https://atlassian.design/components/primitives/text/examples) for body text. To\nlearn how to apply our typography styles in Figma, go to our Figma Typography Playground for step by\nstep instructions and helpful tips.\n\nThe following table outlines our Figma text styles, their corresponding typography tokens, and\nsuggestions for when and where to apply them.\n\n<TypographyTextStyleTable />\n\n## Usage guidelines\n\nFollow these guidelines when using tokens and text styles, to create a seamless and consistent user\nexperience across platform experiences.\n\nUse [space tokens](https://atlassian.design/foundations/spacing) and\n[color tokens](https://atlassian.design/foundations/color) in conjunction with typography to align\nto the design foundations.\n\n### Accessibility\n\nTypography tokens and components have been designed with accessibility considerations in mind. Some\npeople need to read text on different screen sizes or at different magnification levels. Coding your\ntypographic experiences correctly helps assistive technology interpret the structure of your\ncontent.\n\nTo ensure app experiences are accessible for all of our users, ensure that you do the following:\n\n- Use responsive text, typography tokens, use relative values (rem) to determine font size on\n  different browser default sizes.\n- Use text styles (in Figma) and typography tokens and components (in code) to ensure a legible font\n  family, font size, and visual hierarchy between text styles.\n- Use the correct heading levels for an accessible experience. Use heading styles (in Figma) and\n  typography tokens and components (in code) to establish the correct hierarchy of heading levels.\n  Use headings to group related content and help users navigate and scan a page.\n- Use [text color tokens](https://atlassian.design/components/tokens/all-tokens#color-text) to\n  achieve minimum color contrast for legibility.\n- Apply correct HTML tag hierarchy to ensure assistive technologies interpret your experiences\n  correctly.\n- Follow established experience patterns for interactions using text.\n\nThe general guidance for comfortable reading is to use a minimum font size of 16px for long-form\ntext such as blogs. The smallest font size available in the Atlassian Design System typography\ntokens is 12px. Avoid using this, except for in fine print.\n\nVisit our [accessibility documentation](https://atlassian.design/foundations/accessibility/) to\nunderstand more about accessible design.\n\n### Heading\n\nUse headings for page titles and subheadings to introduce content. They help readers scan and\nunderstand the structure of content.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: clearHeadingsDo, alt: '' }}>\n\t\tWrite succinct and clear headings to summarise content on a page or section.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: clearHeadingsDont, alt: '' }}>\n\t\tDon’t write overly long titles. Use shorter titles that can be viewed easily on all screen\n\t\tsizes.\n\t</DoDont>\n\t<DoDont type=\"do\" image={{ url: largeHeadingsDo, alt: '' }}>\n\t\tUse large headings to draw attention to content.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: largeHeadingsDont, alt: '' }}>\n\t\tDon’t use heading sizes smaller than the body font size. Use headings equal or less than twice\n\t\tthe body font size.\n\t</DoDont>\n\t<DoDont type=\"do\" image={{ url: differentiateHeadingsDo, alt: '' }}>\n\t\tClearly differentiate heading sizes to create hierarchy.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: differentiateHeadingsDont, alt: '' }}>\n\t\tDon’t use similar heading sizes for different heading levels. Use between 2-4 heading size\n\t\tdifference between levels.\n\t</DoDont>\n</DoDontGrid>\n\n### Body\n\nUse body text for the main content. You can use body text after headings or subheadings, for example\nas detailed descriptions and messages, but it may also be used as standalone text in components.\n\nIn Figma, paragraph spacing is set for body text styles only. To represent paragraphs in code, use\nseparate [text components](https://atlassian.design/components/primitives/text/examples) for each\nparagraph and manage paragraph spacing with the\n[stack component](https://atlassian.design/components/primitives/stack/).\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: useBodyTextDo, alt: '' }}>\n\t\tUse body text for paragraphs of text such as descriptions or blogs.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: useBodyTextDont, alt: '' }}>\n\t\tDon’t use body text for headings. That’s what headings are for!\n\t</DoDont>\n\t<DoDont type=\"do\" image={{ url: componentsDo, alt: '' }}>\n\t\tUse body text in components such as buttons, inputs, lozenges and menus.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: componentsDont, alt: '' }}>\n\t\tDon’t use heading text in components, instead use body text with a heavier font weight to create\n\t\tgreater contrast.\n\t</DoDont>\n\t<DoDont type=\"do\" image={{ url: textStylesDo, alt: '' }}>\n\t\tUse the text styles and typography tokens. Body text has optimized line height for reading\n\t\tcomfortably.\n\t</DoDont>\n</DoDontGrid>\n\n### Metric\n\nUse metric style when you want to emphasize certain numbers. Numbers you can apply this style to\ninclude:\n\n- **metrics and standalone numbers** (for example, 45%, 100)\n- **numbers with units** (for example, 12 km, 8 hours, 4 days)\n- **currency, totals, and pricing** (for example, $70, Total $550.00)\n\nNumbers can be accompanied with symbols such as %, $, #, or \\*. For numbers that you don’t want to\nemphasize, use body styles that are smaller than the highlighted metric. For example, use body style\nsmall for other small chart content like chart keys, legends, and axes.\n\n#### Apply metric style to numbers and text\n\nMetric can also be applied to numbers and text. This works best for short words. For example:\n\n- ‘10% capacity’\n- ‘55% complete’\n- ‘3 in review’\n\n#### Apply metric style in sizes S, M, or L\n\nThere are 3 sizes for metric. Use the sizes in these scenarios:\n\n- Use S for numbers in the middle of small donut charts and single-value tiles.\n- Use M for numbers in the middle of medium donut charts.\n- Use L for numbers in the middle of large donut charts.\n\nTo apply metric correctly, check these examples of what to do and what to avoid.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: emphasiseMetricDo, alt: '' }}>\n\t\tUse metric to emphasize a number in a donut chart. For example ‘10%’. Use body style small\n\t\tregular for the subtext. For example ’capacity’.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: emphasiseMetricDont, alt: '' }}>\n\t\tDon’t apply metric to the subtext under a number in a donut chart. For example, don’t apply it\n\t\tto ‘capacity’.\n\t</DoDont>\n\t<DoDont type=\"do\" image={{ url: smallTextDo, alt: '' }}>\n\t\tUse body style small for other small chart content like chart keys, legends, and axes. For\n\t\texample, On track 12, Off track 6, At risk 4.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: smallTextDont, alt: '' }}>\n\t\tDon’t use metric for the numbers on the chart key. For example, On track 12, Off track 6, At\n\t\trisk 4.\n\t</DoDont>\n\t<DoDont type=\"do\" image={{ url: shortStatementDo, alt: '' }}>\n\t\tUse metric to emphasize a short statement with words and numbers. For example ‘2 complete’, ‘3\n\t\tin review’ in single-value tiles.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: shortStatementDont, alt: '' }}>\n\t\tDon’t use metric for longer statements. For example ‘Teams with work item cycle time under or\n\t\tover 7 days’.\n\t</DoDont>\n\t<DoDont type=\"do\" image={{ url: chartTitleDo, alt: '' }}>\n\t\tUse heading styles for chart titles.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: chartTitleDont, alt: '' }}>\n\t\tDon’t use metric for chart titles.\n\t</DoDont>\n\t<DoDont type=\"do\" image={{ url: totalDo, alt: '' }}>\n\t\tUse metric for a total in a chart. For example $100.00.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: totalDont, alt: '' }}>\n\t\tDon’t use metric for a total in a billing screen. For example USD 500.00. Use 16px body style\n\t\tinstead.\n\t</DoDont>\n</DoDontGrid>\n\n### Code\n\nUse code text to represent code only, either inline or in code blocks.\n\n![](./_assets/code-text.png)\n\n### Font weights\n\nThere are four font weights available in our system: regular, medium, semibold and bold. We selected\nthese based on our fallback fonts to minimise the visual differences across operating systems.\n\n![](./_assets/font-weights.png)\n\nWe recommend using the following default weights for our text styles:\n\n- Body in **regular** weight for paragraphs.\n- Body in **medium** weight for use in components and alongside icons.\n- Body in **bold** weight should be used in unique cases where text needs to be differentiated or\n  given more emphasis. Use this weight sparingly.\n\nSemibold weight is also available but use this weight with caution. Our fallback fonts don’t support\nthis weight and will default to bold.\n\n![](./_assets/body-weights.png)\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: fontWeightDo, alt: '' }}>\n\t\tUse bold weight in headings to contrast with regular weight body content.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: fontWeightDont, alt: '' }}>\n\t\tDon’t use regular or bold weights when text is beside an icon. Icon stroke width is designed to\n\t\talign with medium weight text.\n\t</DoDont>\n</DoDontGrid>\n\n### Links\n\nUse [`color.link`](https://atlassian.design/components/tokens/all-tokens#color-link) tokens for\ninline links, and see [Link](https://atlassian.design/components/link) and\n[Link button](https://atlassian.design/components/button/link-button) for more guidance.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: linksDo, alt: '' }}>\n\t\tUse design tokens to follow inline link styling and provide visual clues to identify links in\n\t\tstatic text.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: linksDont, alt: '' }}>\n\t\tDon’t show inline links in the same colour as surrounding text or ignore styling patterns for\n\t\tinteractive text.\n\t</DoDont>\n</DoDontGrid>\n\n## Best practices\n\n### All caps\n\nAtlassian writing guidance specifies avoiding the use of all caps. For readability, accessibility\nand localisation reasons, avoid the use of all caps unless text is an acronym. However, the lozenge\ncomponent will continue to use all caps for the foreseeable future.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: allCapsDo, alt: '' }}>\n\t\tUse all caps for acronyms, such as issue IDs.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: allCapsDont, alt: '' }}>\n\t\tDon’t use all caps for full words.\n\t</DoDont>\n</DoDontGrid>\n\n### Truncation\n\nNever truncate text. If you do use truncated text, for example if you are displaying user generated\ncontent of an unknown length, make sure that there's another option for people to expand and read\nthe text.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: truncationDo, alt: '' }}>\n\t\tDisplay content using the maximum character count allowed within components, especially if it is\n\t\timportant information.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: truncationDont, alt: '' }}>\n\t\tDon’t truncate content, if you must truncate make sure there is an option for people to expand\n\t\tand read the full text.\n\t</DoDont>\n</DoDontGrid>\n\n### Line length\n\nWide lines of body text are difficult to read. Readers may choose a wide layout but it’s good\npractice to design for the ideal line length.\n\nFor the English language, optimal line length is between 60 and 80 characters per line including\nspacing, or approximately 10-12 words.\n\nThis can vary based on font, font size and how it will be displayed. For example, line lengths need\nto be shorter when reading text on smaller devices.\n\n![](./_assets/line-length.png)\n\n### Visual hierarchy\n\nCreating hierarchy means using different font weights and sizes to let people easily see what\ncontent is the most important.\n\nOur typography system allows visual hierarchy to be achieved in multiple ways. Using some or all of\nthe below suggestions are ways to create extra levels of meaning and hierarchy to your work.\n\nUse text styles and font weights to draw attention to titles and important content.\n\n![](./_assets/visual-hierarchy-1.png)\n\nUse text size and color to differentiate between primary and secondary level content.\n\n![](./_assets/visual-hierarchy-2.png)\n\n### Writing\n\nRead more about writing style and content guidelines in our\n[content documentation](https://atlassian.design/content).\n\n## Service and educational typography\n\nThe Atlassian Design System’s focus is app UI, however our service sites use a mixture of both\nmarketing and app typography. The appropriate typography can be assessed on a case-by-case basis\ndepending on the following considerations:\n\n- Atlassian messaging vs. user-generated or modified content\n- editorial content vs. technical content\n- brand marketing visual styles vs. app UI visual styles\n- consistency across sites vs. one-off solutions\n\nPlease work directly with the Creative & Design teams when assessing typography for these types of\nproperties.\n\nVisit [Atlassian Brand documentation](https://brandfolder.com/atlassian-brand-creative-library) for\nmore assets and guidance (authenticated users only).\n\n## Data Center apps\n\nFor all new features, we recommend using Atlassian Design System and other\n[Atlaskit components](https://atlaskit.atlassian.com/packages). For existing code, you can continue\nto use [Atlassian User Interface (AUI)](https://aui.atlassian.com/aui/latest/docs/typography.html).",

package/dist/es2019/tools/plan/list-plan-tool.js

@@ -4,10 +4,13 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { planInputSchema } from './plan-input-schema';
 export const listPlanTool = {
   name: 'ads_plan',
-  description: `Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and **ads_search_atlaskit_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** (including legacy/broader Atlaskit) for a UI task.
+  description: `Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and optionally **atlaskit_search_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** for a UI task.
 
 WHEN TO USE:
-**Implementing or iterating on a UI**—new screen, feature, or polish—and you need candidate **token** names, **icon** imports, and **component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.
+**Implementing or iterating on a UI**—new screen, feature, or polish—and you need candidate **token** names, **icon** imports, and **ADS component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.
+
+ADS-FIRST ROUTING:
+Use \`components\` for canonical ADS components. Use \`atlaskitComponents\` only as explicit fallback research for public \`@atlaskit/*\` packages outside the ADS catalog, or after ADS component search has no useful match. This tool does not auto-populate \`atlaskitComponents\` from \`components\`.
 
 At least one of \`tokens\`, \`icons\`, \`components\`, or \`atlaskitComponents\` must contain search terms (use \`[]\` for lists you do not need).
 
@@ -21,7 +24,7 @@ Example request:
 	"tokens": ["spacing", "inverted text", "background primary", "animation"],
 	"icons": ["search", "folder", "user"],
 	"components": ["button", "input", "select", "heading"],
-	"atlaskitComponents": ["inline-dialog", "onboarding", "page-layout"]
+	"atlaskitComponents": ["editor-core", "onboarding", "page-layout"]
 }
 \`\`\`
 

package/dist/es2019/tools/plan/plan-input-schema.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 export const planInputSchema = z.object({
   tokens: z.array(z.string()).describe('Search terms for ADS design tokens (fuzzy by default). Use `[]` if you only need icons or components. Prefer **at least two** terms per non-empty list when you know what you need.'),
   icons: z.array(z.string()).describe('Search terms for ADS icons. Use `[]` if you only need tokens or components. Prefer **at least two** terms per non-empty list when known.'),
-  components: z.array(z.string()).describe('Search terms for ADS components. Use `[]` if you only need tokens or icons. Prefer **at least two** terms per non-empty list when known.'),
-  atlaskitComponents: z.array(z.string()).describe('Search terms for Atlaskit components. Use `[]` if you only need core ADS components. Prefer **at least two** terms per non-empty list when known.'),
-  limit: z.number().default(2).describe('Max matches **per term** for each non-empty list (default 2). Same limit applies to tokens, icons, and both ADS and atlaskit component searches.').optional()
+  components: z.array(z.string()).describe('Search terms for canonical ADS components. Use `[]` if you only need tokens, icons, or explicit Atlaskit fallback research. Prefer **at least two** terms per non-empty list when known.'),
+  atlaskitComponents: z.array(z.string()).describe('Search terms for public `@atlaskit/*` components outside the ADS catalog. Use only as explicit fallback research when ADS component search is not enough; this is not auto-populated from `components`. Use `[]` if you only need canonical ADS components. Prefer **at least two** terms per non-empty list when known.'),
+  limit: z.number().default(2).describe('Max matches **per term** for each non-empty list (default 2). Same limit applies to tokens, icons, ADS components, and explicit Atlaskit component fallback searches.').optional()
 });

package/dist/es2019/tools/plan/plan-tool.js

@@ -17,7 +17,7 @@ export const planTool = async ({
       isError: true,
       content: [{
         type: 'text',
-        text: 'Error: At least one search type (tokens_search, icons_search, components_search, or atlaskit_components_search) must be provided with search terms'
+        text: 'Error: At least one search type (tokens, icons, components, or atlaskitComponents) must be provided with search terms'
       }]
     };
   }

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

@@ -4,10 +4,10 @@ import { zodToJsonSchema } from '../../helpers/zod-to-json-schema';
 import { searchAtlaskitComponentsInputSchema } from './search-atlaskit-components-input-schema';
 export const listSearchAtlaskitComponentsTool = {
   name: 'atlaskit_search_components',
-  description: `Searches the bundled Atlaskit component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).
+  description: `Searches the bundled public \`@atlaskit/*\` component catalog outside the Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).
 
 WHEN TO USE:
-**Selecting which Atlaskit component to use**—package name, examples, and props—before implementation. Use when searching for specific Atlaskit components that might not be in the core ADS catalog.`,
+Use this for fallback research when \`ads_search_components\` or \`ads_plan.components\` does not find a useful ADS component, or when the user asks about a specific public \`@atlaskit/*\` package that is not part of ADS. Prefer canonical ADS components first for standard UI.`,
   annotations: {
     title: 'Search Atlaskit components',
     readOnlyHint: true,

package/dist/es2019/tools/search-atlaskit-hooks/list-search-atlaskit-hooks-tool.js

@@ -4,10 +4,10 @@ import { zodToJsonSchema } from '../../helpers';
 import { searchAtlaskitHooksInputSchema } from './search-atlaskit-hooks-input-schema';
 export const listSearchAtlaskitHooksTool = {
   name: 'atlaskit_search_hooks',
-  description: `Search for atlaskit hooks by name, package, category, description, or keywords.
+  description: `Search public \`@atlaskit/*\` hooks outside the Atlassian Design System (ADS) catalog by name, package, category, description, or keywords.
 
 WHEN TO USE:
-Use this when you want to find a hook but don't know its exact name or package.`,
+Use this for fallback research when you want to find a non-ADS \`@atlaskit/*\` hook but do not know its exact name or package.`,
   annotations: {
     title: 'Search Atlaskit hooks',
     readOnlyHint: true,

package/dist/es2019/tools/search-atlaskit-utilities/list-search-atlaskit-utilities-tool.js

@@ -4,10 +4,10 @@ import { zodToJsonSchema } from '../../helpers';
 import { searchAtlaskitUtilitiesInputSchema } from './search-atlaskit-utilities-input-schema';
 export const listSearchAtlaskitUtilitiesTool = {
   name: 'atlaskit_search_utilities',
-  description: `Search for atlaskit utilities (functions, constants, types) by name, package, category, description, or keywords.
+  description: `Search public \`@atlaskit/*\` utilities (functions, constants, types) outside the Atlassian Design System (ADS) catalog by name, package, category, description, or keywords.
 
 WHEN TO USE:
-Use this when you want to find a utility but don't know its exact name or package.`,
+Use this for fallback research when you want to find a non-ADS \`@atlaskit/*\` utility but do not know its exact name or package.`,
   annotations: {
     title: 'Search Atlaskit utilities',
     readOnlyHint: true,

package/dist/es2019/tools/search-components/list-search-components-tool.js

@@ -7,7 +7,9 @@ export const listSearchComponentsTool = {
   description: `Searches the bundled Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **props** for each match (trimmed payload).
 
 WHEN TO USE:
-**Selecting which ADS component to use**—package name, examples, and props—before implementation. Use when composing a new view or swapping a primitive. Prefer \`ads_plan\` when you also need token and icon discovery in one shot.`,
+**Selecting which canonical ADS component to use**—package name, examples, and props—before implementation. Use when composing a new view or swapping a primitive. Prefer \`ads_plan\` when you also need token and icon discovery in one shot.
+
+If you are looking for a public \`@atlaskit/*\` scoped package that is not part of the ADS component catalog, use \`atlaskit_search_components\` for fallback research instead of this ADS-only search.`,
   annotations: {
     title: 'Search ADS components',
     readOnlyHint: true,

package/dist/es2019/tools/search-components/search-components-tool.js

@@ -72,7 +72,7 @@ export const searchComponentsTool = async ({
     return {
       content: [{
         type: 'text',
-        text: `Error: No components found for '${terms.join(', ')}'. Available components: ${components.map(c => c.name).join(', ')}`
+        text: `Error: No ADS components found for '${terms.join(', ')}'. If this is a public @atlaskit/* package outside the ADS catalog, call atlaskit_search_components with the same terms. Available ADS components: ${components.map(c => c.name).join(', ')}`
       }]
     };
   }

package/dist/esm/instructions.js

@@ -1 +1 @@
-export var instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nFor org-wide standards alongside ADS tools: pair Context Engine `get_accessibility_docs` with `ads_get_a11y_guidelines`, `get_content_standards_docs` with `ads_get_guidelines`, and `get_i18n_docs` with `ads_i18n_conversion_guide` (Traduki/i18n policy plus the bundled formatMessage refactor guide).\nThese tools will support you, but for deep research you may also fetch https://atlassian.design/llms.txt, https://atlassian.design/llms-a11y.txt, or https://atlassian.design/ directly.\n";
+export var instructions = "\nYou are an expert in the Atlassian Design System (ADS).\nYou can search for tokens, icons, and components and return guidance on how to build user interfaces.\nUse ads_* tools for canonical ADS resources: components, tokens, icons, foundations, accessibility, lint rules, i18n, and migrations.\nUse atlaskit_* tools only for further research into public @atlaskit/* scoped packages that are not covered by the ADS catalog, such as non-ADS components, hooks, and utilities. Prefer ADS resources first for standard UI.\nYou have special accessibility knowledge and can ensure interfaces built with ADS components are accessible to all users.\nYou can analyze code for accessibility violations, provide specific fix suggestions, and offer guidance on accessibility best practices.\nFor org-wide standards alongside ADS tools: pair Context Engine `get_accessibility_docs` with `ads_get_a11y_guidelines`, `get_content_standards_docs` with `ads_get_guidelines`, and `get_i18n_docs` with `ads_i18n_conversion_guide` (Traduki/i18n policy plus the bundled formatMessage refactor guide).\nThese tools will support you, but for deep research you may also fetch https://atlassian.design/llms.txt, https://atlassian.design/llms-a11y.txt, or https://atlassian.design/ directly.\n";