@atlaskit/ads-mcp 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @atlaskit/ads-mcp
 
+## 0.17.0
+
+### Minor Changes
+
+- [`f5a9fb963d33b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f5a9fb963d33b) -
+  Include guidelines from structured content in the ADS MCP
+
 ## 0.16.0
 
 ### Minor Changes

package/dist/cjs/index.js

@@ -20,6 +20,7 @@ var _getA11yGuidelines = require("./tools/get-a11y-guidelines");
 var _getAllIcons = require("./tools/get-all-icons");
 var _getAllTokens = require("./tools/get-all-tokens");
 var _getComponents = require("./tools/get-components");
+var _getGuidelines = require("./tools/get-guidelines");
 var _getIcons = require("./tools/get-icons");
 var _getLintRules = require("./tools/get-lint-rules");
 var _getTokens = require("./tools/get-tokens");
@@ -115,6 +116,11 @@ var getToolRegistry = exports.getToolRegistry = function getToolRegistry() {
       inputSchema: _getLintRules.getLintRulesInputSchema,
       tool: _getLintRules.listGetLintRulesTool
     };
+    baseTools[_getGuidelines.listGetGuidelinesTool.name] = {
+      handler: _getGuidelines.getGuidelinesTool,
+      inputSchema: _getGuidelines.getGuidelinesInputSchema,
+      tool: _getGuidelines.listGetGuidelinesTool
+    };
   } else {
     baseTools[_getAllTokens.listGetAllTokensTool.name] = {
       handler: _getAllTokens.getAllTokensTool,

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

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.guidelinesStructuredContent = void 0;
+/**
+ * THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
+ *
+ * Structured content for content guidelines from design-system-docs foundations content.
+ *
+ * @codegen <<SignedSource::4f7efe5f3afd0bc4b8832adf32e729d9>>
+ * @codegenCommand yarn build structured-docs
+ */
+
+var guidelinesStructuredContent = exports.guidelinesStructuredContent = [{
+  content: '## A note for Content Designers\n\nWhen you’re working with engineers, all they need is the time and date format length, and the i18n\nlibrary API will format the date accordingly based on the locale signals Atlassian provides.\n\nEach programming language has an i18n library that automatically localizes time and date strings\nbased on a user’s locale settings/preferences. Date and time formatters are used to convert dates\nand times from their internal representations to textual form and back again in a\nlanguage-independent manner.\n\nTime and date strings should never be localized manually by a translator as time and date strings\nshould be tied to a user’s locale (country and language) not their language. Hardcoding time and\ndate content is bad practice and creates a bad international customer experience.\n\n## Abbreviating days and months\n\nUse abbreviations when space is limited. Be clear about which months or days you are referring to.\n\nUse these abbreviations for the days of the week:\n\n- Monday – Mon\n- Tuesday – Tue\n- Wednesday – Wed\n- Thursday – Thu\n- Friday – Fri\n- Saturday – Sat\n- Sunday – Sun\n\nUse these abbreviations for the months:\n\n- January – Jan\n- February – Feb\n- March – Mar\n- April – Apr\n- May – leave it as May\n- June – Jun\n- July – Jul\n- August – Aug\n- September – Sep\n- October – Oct\n- November – Nov\n- December – Dec\n\n<DoDont type="do">Be consistent when using abbreviations</DoDont>\n<DoDont type="dont">\n\tDon’t use the shortest form of days and months – F, M, N, etc. If there isn’t room to designate\n\tthe month, work on redesigning.\n</DoDont>\n\n## The date format in American English\n\nUsually, the month comes before the day, then followed by the year. On the 8th day of the month of\nJanuary, in the year 2020, then the date in American English can be written as:\n\n- Jan 8\n- January 8\n- January 8, 2020\n- Monday, January 8, 2020\n\nAtlassian uses American English when writing in English. The formats above are broken down below to\nhelp when writing absolute values are required. Choose patterns that are appropriate for your\ncontext.\n\n### Long date\n\nUse full date in cards, bylines, and anywhere else space or your design allows for it:\n\n- Use numerals for the day\n- Spell out the month and day of the week in words\n- Give the full four-digit year, not a two-digit abbreviation\n\nDon’t use ordinal numbers, for example, 1st, 2nd, 3rd, etc.\n\n<DoDont type="do">Tuesday, April 12, 1952</DoDont>\n<DoDont type="dont">Tuesday 12th April 1952</DoDont>\n\n### Medium date\n\nYou can also use a shorter format. Here spell out the month and use numerals for the day and year:\n\n<DoDont type="do">April 12, 1952</DoDont>\n\n### Short date\n\nWhen space is limited shorten dates further, for example in lists, tables, charts, and comments.\n\n- Spell out the month using abbreviations\n- Use numerals for the day and the year\n\nWe recommend using the following pattern in shorter spaces:\n\n<DoDont type="do">Sep 14, 2006</DoDont>\n\nWhen you need to leave out either the day or year, where possible, spell out the month in full.\n\n- October 22 or July 2019\n\n## Numerical dates\n\nWriting dates entirely in numbers has disadvantages when it comes to readability and usability. This\nis because parts of the world use the date in a different order for numeric dates. Avoid doing this\nif it\'s possible because it often also has large UX implications. Instead, we recommend using any of\nthe other date formats above.\n\nIf it’s absolutely necessary to express a date in numerical date format, use the format YYYY-MM-DD,\nand separate the elements by using hyphens. This conforms to\n[ISO 8601 international standards](https://wikipedia.org/wiki/ISO_8601) for numerical date format.\n\n- 2021-05-23\n\nIn a content draft or design spec if you’re adding a fictional date, choose a day greater than 12.\nThis will help to clearly differentiate the day from the month.\n\n## Grammar and punctuation\n\nPunctuation is a localization issue and should be localized wherever possible. Avoid if possible,\ndefaulting to no punctuation.\n\n### Hyphens\n\nWhen writing as numerals separate the numbers with an unspaced hyphen, using the format above.\n\n### Apostrophes\n\nAvoid using apostrophes. In more casual writing, you can use expressions such as ‘the seventies’ or\n\'the \'70s\' - using contractions for the missing numerals in the year.\n\n### Capital and lower case\n\nMonths and days are proper nouns and start with a capital letter. Specific days, times of the year\nor periods in history are all proper nouns. Use capitals for all proper nouns.\n\nUse initial capitals for all institutional holidays, religious days, and public events:\n\n- New Year’s Day\n- Good Friday\n- Ramadan\n- Yom Kippur\n\n## Using ‘to’ and ‘from’\n\nUse ‘to’ if a number range is preceded by ‘from’ in a phrase. Use ‘and’ if a range is preceded by\n‘between’. Avoid using hyphens and en dashes in spans of dates.\n\n<DoDont type="do">From 2015 to 2019</DoDont>\n<DoDont type="dont">2014 - 2015</DoDont>\n\nWhen this isn\'t possible, for example:\n\n- financial years\n- or when information is in parentheses, such as terms of office and years of birth and death.\n\nFor these, use a hyphen without any spaces on either side:\n\n- FY2008-09\n- John Smith (1917–1992) had 3 younger siblings.\n\n## Divisions of the year\n\nSpring in the northern hemisphere is autumn (fall) in the southern hemisphere. Avoid talking about\nseasons. Instead, use months or quarters.\n\n## Time\n\nIn most cases, especially when you need to be precise, use numbers to give a clearer expression of\ntime. Use a colon between the hours and minutes with no spaces on either side.\n\n<DoDont type="do">3:30:42 p.m. PST</DoDont>\n\nIf it’s an exact hour, no “:00″ is required. For timestamps, labels on graphs, durations, and more\navoid using zeros. Only show minutes if it’s not on the hour.\n\n<DoDont type="do">8 a.m.</DoDont>\n<DoDont type="dont">8:00am</DoDont>\n\n### Using ‘a.m.’ and ‘p.m.’\n\n<SectionMessage title="a.m/p.m clarification">\n<Stack space="space.100">\nUse the following date/time formatting guidelines when creating static content, like a blog, manuals, instructions, etc.\n\nKeep in mind that, for dynamic content, the design system components expect a locale value\nrepresenting the end users preferred date/time format from their profile or their system (e.g.\nbrowser), which could be different from the guidelines on this page.\n\n</Stack>\n</SectionMessage>\n\nAs with American English in most cases, we use rules set by the AP style guide.\n\n- Lowercase a.m. and p.m., with periods.\n- Use numerals, with a space between the time and the a.m. or p.m., for example, 6:30 a.m.\n- If a time range is entirely in the morning or evening, use a.m. or p.m. only once: “6:30-10 p.m.”\n  If it goes from the morning into the evening (or vice versa), you need both: “10 a.m.-2 p.m.”\n\n### Noon, midday, and midnight\n\nWhere possible use ‘noon’, ‘midday’ or ‘midnight’ instead of ‘12 a.m.’ or ‘12 p.m.’ to make it\neasier for people.\n\n### The 24-hour system\n\nUse the 24-hour system if it helps people understand your content. But it’s important to understand\nthat many times this is system-driven. This is important if you’re referring to time in the context\nof more serious communications, for example, in case of outages and in security comms.\n\nThe 24-hour system numbers hours from 00:00 hours (midnight) to 23:59 and always uses at least 4\ndigits. If seconds are included use 6 digits.\n\n- The first 2 digits are the hours\n- The next 2 digits are the minutes\n- The last 2 digits are the seconds\n\nUse a colon to separate the hours, minutes, and seconds.\n\n### Talking about time\n\nAvoid using the prefix ‘bi’ to mean either 2 or twice. It can be confusing.\n\n- ‘Bimonthly’ can mean either every 2 months or twice a month.\n- ‘Biannual’ means twice a year.\n\nInstead, use fortnightly or the phrase ‘every 2’.\n\n<DoDont type="do">Your x will repeat every 2 weeks</DoDont>\n<DoDont type="dont">Your x will repeat bi-monthly</DoDont>\n\n### Using date and time together\n\nThis is used when displaying both the date and the time of day. For example, in historical versions\nof pages. To do this use the following formats\n\n- MMM dd, yyyy HH:mm\n- dd, HH:mm\n\n### Relative date and time\n\nIt’s important that you express date and time information as you would speak in conversation when\nthe situation allows for it.\n\nIn some cases, the easiest way to describe something that happened very recently is using the ‘ago’\nformat. Use this when the exact date is less important. For future and past events, use approximate\ntime by rounding down to the largest or most recent date or 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## Writing for languages other than English and internationalization\n\nDate and time formatting differs greatly from country to country, and even within regions of a\ncountry, such as Canada and Switzerland.\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\nIn order to accurately localize date and time formatting for different locales (country and\nlanguage), we require Engineers to ensure that all content containing the date and time references\nare not hardcoded and reference built-in i18n libraries/APIs for automatic format\n\n### Best practice for Engineers\n\nThe best practice for Internationalization is for Engineers not to hardcode time and date strings\nand to reference the programming i18n library API which will automatically format time and date\nstrings as per the detected or selected locale.',
+  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 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.",
+  keywords: ['empty state', 'messages', 'content', 'designing messages']
+}, {
+  content: 'An error message, different from a warning message, appears **after** someone has taken an action.\nThe message draws their attention to what has happened and what the consequences are, and what\npeople need to do to move forward. Optionally, they can also include why something happened and\nwhether the problem will occur again.\n\nWhen crafting an error message, remember that most people scan text instead of reading everything.\nMake every word count and avoid irrelevant details.\n\n## Writing best practices\n\n### Title\n\n- Titles are optional depending on the component you choose.\n- Include an informative, scannable title. Try and imagine people trying to understand what’s\n  happening by reading the title on its own.\n- Avoid explaining what to do.\n- Limit titles to three to four words where possible, excluding “an”, “a”, or “the”. The character\n  count will depend on the component you choose.\n- Write in sentence case with appropriate punctuation.\n\n### Body\n\n- Include: the reason for the error and the problem, how someone should act and what happens if they\n  don’t act.\n- If you don’t know the reason for an error, don’t make one up – just say that something’s gone\n  wrong and offer a solution for what people can do.\n- Avoid repeating content from the title.\n- Keep messages to 1 to 2 sentences.\n- Avoid putting technical information in the message or having people look in another location. If\n  it can\'t be avoided, use a link to support content.\n\n<DoDont type="do" image={{ url: errorMessagesBodyDo, alt: \'\' }} />\n<DoDont type="dont" image={{ url: errorMessagesBodyDont, alt: \'\' }} />\n\n### Call to action (CTA)\n\n- When an error message invokes a choice, use imperative verbs such as “Save”, “Remove”, or\n  “Create”, in the CTA to describe what action people will be making instead of vague terms such as\n  “OK”.\n- An option to dismiss or cancel lets people feel reassured that they can opt out.\n- Limit your CTA to 1 or 2 words.\n\n## Voice and tone\n\nErrors are high-stakes situations. They can be frustrating at a minimum, or catastrophic at their\nworst – especially when they involve work.\n\nYou want to leave people feeling supported and reassured. Convey an error message with empathy and\ntact. The correct level of urgency will let people understand how to respond. Follow some of the\nfollowing\n[Atlassian voice and tone principles](https://atlassian.design/foundations/content/voice-tone) to\nbuild your message:\n\n### Inform to build trust\n\nBe open and clear about what\'s happening in the app. Be aware that your reader could be new or\nconfused, and tone down the boldness by being more prescriptive.\n\n<DoDont type="do" image={{ url: errorMessagesTrustDo, alt: \'\' }} />\n<DoDont type="dont" image={{ url: errorMessagesTrustDont, alt: \'\' }} />\n\nTreat errors as an opportunity to educate people. Help them understand why they’re experiencing\nsomething and how they can avoid similar issues in the future. You may even be able to teach them\nsomething that can help them understand and manage the technology they use beyond our apps.\n\n### Encourage people along the path\n\nBe consistent and dependable. Avoid messaging that focuses on the problem without offering a\nsolution or way forward. Focus on next steps where possible and stay away from negative words or\nphrases.\n\n<DoDont type="do" image={{ url: errorMessagesEncourageDo, alt: \'\' }} />\n<DoDont type="dont" image={{ url: errorMessagesEncourageDont, alt: \'\' }} />\n\nUse _we_ instead of _you_, as emphasizing the relationship between the person and the problem could\nmake them feel like they’re being held responsible.\n\n### Satisfy by meeting expectations\n\nProvide quick and thorough answers, guidance, actions, and instructions. Give them the information\nthey need then get out of their way.\n\n<DoDont type="do" image={{ url: errorMessagesExpectationsDo, alt: \'\' }} />\n<DoDont type="dont" image={{ url: errorMessagesExpectationsDont, alt: \'\' }} />\n\nAvoid using “please” and “sorry”. Saying "sorry" in error messages can make the situation worse by\ncausing errors to appear more severe than they actually are. Similarly, saying "please" can\nundermine the authority and credibility of your message and lead people to think a required step is\noptional. Unless the error has severe and irreparable consequences, avoid niceties.\n\n## Patterns and UX strategies\n\nIf the error has more than one potential cause or solution, try one of the following writing\nstrategies.\n\n### A warning message vs. an error message\n\nAn error message alerts people of a problem that has already occurred. By contrast, a warning\nmessage alerts people of a condition that might cause a problem in the future.\n\nUse text, design elements, and visual clues to differentiate the difference between where people are\nin their journeys.\n\n### Offer a backup solution\n\nStick to the most likely cause or the simplest solution in the first sentence of the error message\nand offer an alternative backup solution in the second sentence in case the error keeps occurring\n(for example, contacting support). Try to reframe the error as an opportunity to inspire trust and\nconfidence.\n\n<DoDont type="do" image={{ url: errorMessagesBackupDo, alt: \'\' }} />\n<DoDont type="dont" image={{ url: errorMessagesBackupDont, alt: \'\' }} />\n\n### Reveal additional information gradually\n\nFor dead ends, start with something short but kind, and add context or other details only if the\nerror will reoccur.\n\n## Related components\n\nUse error messages in the following components:\n\n- [Flag](https://atlassian.design/components/flag/examples)\n- [Inline message](https://atlassian.design/components/inline-message/examples)\n- [Modal dialog](https://atlassian.design/components/modal-dialog/examples)\n- [Section message](https://atlassian.design/components/section-message/)\n\n## Accessibility\n\n- Use alternative text for illustrations and symbols in your messages\n- Avoid jargon and use simple language\n- Make links as descriptive as possible\n- Make text easily scannable to highlight key information.',
+  keywords: ['error messages', 'errors', 'content', 'designing messages']
+}, {
+  content: 'These messages highlight a new or recently updated experience. Let people know what\'s changed, and\ninvite them to try something new. A feature discovery message should leave your reader feeling\ncurious, excited, and empowered.\n\nFor more guidance on this messaging type, see the new or updated feature pattern.\n\n## Tips and tricks\n\n- When introducing the new feature, consider what the user is trying to accomplish, what they were\n  just doing, and where they need to go.\n- Titles and messages should clearly indicate user benefits. For example, "Find your work faster"\n  instead of "New search".\n- This should be a positive experience for people, so it\'s okay to be delightful, just don\'t overdo\n  it.\n\n## Voice and tone\n\nDetermine if you need to inform (a feature has moved) or educate (the experience or interaction has\nchanged). Introduce the change, communicate its benefits, and provide a call to action if\nappropriate\n\nBe bold and optimistic about a new feature, especially if there are benefits and improvements for\nthe user. Be clear and practical, and you can add a little “wink” to entice the user to try\nsomething new.\n\n## Examples\n\nThe information flag below promotes the updated search feature, giving the option of learning more\nor trying out the new search.\n\n<img src={featureDiscoveryFlag} alt="Information flag to highlight a new search feature." />\n\nThis example encourages and empowers the user to begin using Jira as intended by adding work items.\n\n<img\n\tsrc={featureDiscoveryStart}\n\talt="Information modal promoting how to add a work item to Jira."\n/>\n\nThis Bitbucket example encourages people to improve their Bitbucket experience by adding branch\npermissions. It clearly states the benefits and ideal state of using this feature.\n\n<img\n\tsrc={featureDiscoveryBitbucket}\n\talt="An information modal for BitBucket highlighting how to add a branch permission."\n/>\n\n## Related components\n\n- [Flag](https://atlassian.design/components/flag/examples)\n- [Benefits modal](https://atlassian.design/components/onboarding/benefits-modal/usage)\n- [Spotlight](https://atlassian.design/components/onboarding/usage)',
+  keywords: ['feature discovery', 'onboarding', 'content', 'designing messages']
+}, {
+  content: 'Use these messages when you want to provide more information without disrupting someone’s work or\nrequiring them to take action.\n\nAn info message needs to leave your reader feeling:\n\n1. Informed\n2. Helped and supported\n3. In control of their situation\n\nInformation messages may be used to communicate a change in state or important information about an\nexperience or feature. Get right to the point and say why it’s important.\n\n## Tips and tricks\n\n- Get right to the point\n- Say why it\'s important, then let them get back to work\n- Keep the information useful and don\'t disrupt your users experience with the message\n\n## Voice and tone\n\nInform the user about something that might happen or impact them. Then let them get back to work.\nBased on the situation, you can add more of a “wink” to your message, but keep it clear and concise.\n\n## Examples\n\nThis flag informs the user they were logged out due to inactivity. It’s personable, informative and\noffers a clear action to log back in.\n\n<img\n\tsrc={infoMessagesFlag}\n\talt="Information flag informing someone they have been logged out. The call-to-action is to login."\n/>\n\nThis message is used to inform the user and give a reason behind an empty state.\n\n<img\n\tsrc={infoMessagesEmptyState}\n\talt="Empty state encouraging an admin to add people to a Jira project space."\n/>\n\n## Related components\n\n- [Flag](https://atlassian.design/components/flag/examples)\n- [Inline message](https://atlassian.design/components/inline-message/examples)\n- [Section message](https://atlassian.design/components/section-message/examples)',
+  keywords: ['info messages', 'information', 'content', 'designing messages']
+}, {
+  content: "A success message appears after someone has taken an action or completed a task. The message is an\nopportunity to confirm the action or congratulate them.\n\nWhen crafting a success message, remember that most people scan text instead of reading everything.\nMake every word count and avoid irrelevant details.\n\n## Writing best practices\n\n### Title\n\n- Titles are optional depending on the component you choose. Avoid using “Success!” or\n  “successfully” in a title.\n- Include an informative, scannable title. Try and imagine people trying to understand what’s\n  happening by reading the title on its own.\n- Limit titles to three to four words where possible, excluding “an”, “a”, or “the”. The character\n  count will depend on the component you choose.\n- Write in sentence case and no use of periods.\n- Avoid using exclamations! We don't want to be overly enthusiastic about everything!\n\n### Body\n\n- Include the reason for the success — confirm what action someone has taken or what task has been\n  completed. If someone has created something give them an opportunity to view it.\n- Avoid repeating content from the title.\n- Keep messages to 1 to 2 sentences. Use a few words of praise followed by one or two sentences of\n  informative insight.\n- Avoid putting technical information in the message or having people look in another location. If\n  it can't be avoided, use a link to support content.\n\nIt’s important to show possibility once someone has achieved something. We want to tell people the\nresult of something, for example ‘you’ve closed the ticket'; how to undo it, for example, ‘ask your\nspace admin to restore the page, if needed’; and the step forward if possible, for example ‘View\nyour new space or set the permissions on your new space’.\n\n### Call to action (CTA)\n\n- CTAs are often optional unless there are any follow-up options. Don’t include a CTA unnecessarily.\n- Always give people an option to dismiss the message.\n- When a success message invokes a choice, use imperative verbs such as “Save”, “Remove”, or\n  “Create”, in the CTA to describe what action people will be making instead of vague terms such as\n  “OK”.\n- Limit your CTA to 1 or 2 words.\n\n## Voice and tone\n\nSuccess messages should leave people feeling empowered, motivated, and satisfied with their efforts.\n\nYou want to confirm the outcome and then get out of people’s way. Follow some of the following\n[Atlassian Voice and Tone principles](https://atlassian.design/foundations/content/voice-tone) to\nbuild your message:\n\n**Delight with unexpectedly pleasing experiences**\n\nWe’re celebrating success or progress once we’ve built trust. 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. Success messages that appear more\nfrequently should be more concise and have less delight. If messages are appearing repeatedly,\nconsider multiple versions if you want to add some humor. These are low commitment experiences, we\nwant 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## Related components\n\nUse success messages in the following components:\n\n- [Flag](https://atlassian.design/components/flag/examples)\n- [Banner](https://atlassian.design/components/banner/examples)\n- [Inline message](https://atlassian.design/components/inline-message/examples)\n- [Modal dialog](https://atlassian.design/components/modal-dialog/examples)\n- [Section message](https://atlassian.design/components/section-message/)\n\n## Accessibility\n\n- Use alternative text for illustrations and symbols in your messages.\n- Avoid jargon and use simple language.\n- Make links as descriptive as possible.\n- Make text easily scannable to highlight key information.",
+  keywords: ['success messages', 'content', 'designing messages']
+}, {
+  content: "A warning message, different from error messages, appears **before** someone takes an action to\nindicate a significant change or potential loss of data. It draws their attention to a potential\nproblem that may or may not require an action on the user’s part.\n\nWhen crafting warning messages, remember that most people scan text instead of reading everything.\nMake every word count and avoid irrelevant details.\n\n## Writing best practices\n\n### Titles\n\n- Titles are optional depending on the component you choose.\n- Include an informative, scannable title. People should understand what’s happening by reading the\n  title on its own.\n- Avoid explaining what to do.\n- Limit titles to three to four words where possible, excluding “an”, “a”, or “the”. The character\n  count will depend on the component you choose.\n- Write in sentence case with appropriate punctuation.\n\n<DoDont type=\"do\" image={{ url: warningMessagesTitlesDo, alt: '' }}>\n\tYour bill may increase\n</DoDont>\n<DoDont type=\"dont\" image={{ url: warningMessagesTitlesDont, alt: '' }}>\n\tTime to pay up!\n</DoDont>\n\nBy giving people this warning before they add extra members to their team you’re giving them a\nchance to reconsider their options after having all the information. Avoid using a wink in instances\nwhere there could be a problem for people.\n\n### Body copy\n\n- Include: the reason for the warning and the potential problem, how someone should act, and what\n  happens if they don’t act.\n- If you don’t know the reason for a warning, don’t make one up – just say that something’s gone\n  wrong and offer a solution for what they can do.\n- Avoid repeating content from the title.\n- Keep messages to 1 to 2 sentences.\n- Avoid people having to look in another location for more information. If this can't be avoided,\n  use a link to support content.\n\n<DoDont type=\"do\" image={{ url: warningMessagesBodyDo, alt: '' }}>\n\tWe’re running into some difficulties\n</DoDont>\n<DoDont type=\"dont\" image={{ url: warningMessagesBodyDont, alt: '' }}>\n\tYou’ve lost connection\n</DoDont>\n\nUse “we’re” instead of “you’re” to avoid blaming people for issues in the app.\n\n### Call to action (CTA)\n\n- When a warning message invokes a choice, use imperative verbs such as “Save”, “Remove”, or\n  “Create”, in the CTA to describe what action people will be making instead of vague terms such as\n  “Done”.\n- An option to dismiss or cancel lets people feel reassured that they can opt-out.\n- Limit your CTA to 1 or 2 words.\n\n## Voice and tone\n\nYou want to leave people feeling informed, supported and reassured. Convey the correct level of\nurgency and make sure they understand how to respond. Follow the\n[Atlassian voice and tone principles](https://atlassian.design/foundations/content/voice-tone) to\nbuild your message:\n\n### Inform to build trust\n\nInform, but don't alarm. If the warning comes before an action, clearly communicate what will happen\nif the action is taken.\n\n### Encourage them along the path\n\nGive clear, concise advice on which path to take and describe and provide alternatives if possible.\n\n### Satisfy by meeting expectations\n\nUse language that sounds and feels human, is natural and accessible. Explains the situation clearly\nand without assuming they have any advanced knowledge.\n\n## Patterns and UX strategies\n\nConsider the context in which the message appears. The type of warning message required will change\ndepending on the risk, consequences, and immediacy of the problem.\n\n### Raise awareness\n\nWarning messages make people aware of a condition or potential problem, even if they don't have to\ntake immediate action.\n\n<DoDont type=\"do\" image={{ url: warningMessagesAwarenessDo, alt: '' }}>\n\tPayment details needed\n</DoDont>\n<DoDont type=\"dont\" image={{ url: warningMessagesAwarenessDont, alt: '' }}>\n\tWe’re going to close your account\n</DoDont>\n\nThis message describes the condition or problem, the implications and their importance, and offers a\nbutton to dismiss the message.\n\n### Highlight an imminent problem\n\nThis is when someone needs to act immediately to prevent an issue.\n\nHere the message describes what people need to do, explains the condition and why it’s important,\nand offers a button for each of the options.\n\nIt's important to give people a timeline in which to make a certain change. You don’t want to create\npanic and rush people into making changes.\n\n### Confirm a risky action\n\nThis message should ask people whether they want to proceed, explain any reasons why they may not\nwish to proceed, and offer commit buttons for proceeding or canceling an action. You should also\ninform them whether any actions they take can be easily undone.\n\n<DoDont type=\"do\" image={{ url: warningMessagesConfirmDo, alt: '' }}>\n\tConfirm a risky action\n</DoDont>\n<DoDont type=\"dont\" image={{ url: warningMessagesConfirmDont, alt: '' }}>\n\tRisky action\n</DoDont>\n\n## Related components\n\nUse warning messages in the following components:\n\n- [Banner](https://atlassian.design/components/banner/examples)\n- [Flag](https://atlassian.design/components/flag/examples)\n- [Inline message](https://atlassian.design/components/inline-message/examples)\n- [Modal dialog](https://atlassian.design/components/modal-dialog/examples)\n- [Section message](https://atlassian.design/components/section-message/)\n\n## Accessibility\n\n- Use alternative text for illustrations and symbols in your messages\n- Avoid jargon and use simple language\n- Make links as descriptive as possible\n- Make text easily scannable to highlight key information.",
+  keywords: ['warning messages', 'warnings', 'content', 'designing messages']
+}, {
+  content: '## Principles for inclusive language\n\n### Use words that reflect our diverse world\n\nInclusive language isn’t about following a list of good and bad words. It’s about taking an approach\nto your writing that avoids assumptions, stereotypes, and treats people with respect.\n\nOur apps are for all kinds of people. The words we use should help them have a great experience.\nConsider how your language is helping or harming people.\n\n### Make content easy to understand\n\nBe inclusive by using plain language. Remove jargon, metaphors, and idioms. Simple wording is proven\nto help people complete their tasks faster and with higher success rates. It also ensures that you\naren’t excluding people by using words that are specific to your context.\n\n### Learn from your audience\n\nRely on the expertise of people who belong to the groups you’re writing about. You can do this by\nreading resources put out by advocacy groups, or consulting with people from diverse communities.\nNever assume people from a diverse community want to educate or give feedback – always ask for\npermission first.\n\n## How to describe people\n\n### Be clear\n\nWhen you need to describe a group of people, use clear language that aligns with how people describe\nthemselves.\n\nWhen you’re not sure, always use person-first language. This language centers the person, rather\nthan their difference. For example, “people with disabilities”, rather than “disabled people” In\nsome circumstances people prefer to use identity-first language to represent themselves, such as in\nthe Deaf community.\n\nYou can reduce inaccurate assumptions or stereotypes by improving the way you describe people’s\ndifferences. For example:\n\n| Good                                                                                     | Better                                                                                       | Reason                                                                                                                                                   |\n| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Alternative text helps people with visual disabilities interact with the user interface. | Alternative text helps people who use assistive technology interact with the user interface. | Not all people who use assistive technology, like screen readers have visual disabilities. Using this definition is more inclusive, and more accurate.   |\n| This project was done in consultation with people of Indigenous backgrounds.             | This project was done in consultation with First Nations Australians.                        | Use specific terms when referring to racial and ethnic groups. Vague terms don\'t acknowledge the different experiences of racial and ethnic communities. |\n\n### Don’t change words used to describe people\n\nDon’t modify phrases to make differences sound positive. Words like “differently abled” or\n“handi-capable” are patronizing, and don’t fit with the full diversity of human experiences.\n\nAvoiding describing people’s differences can reinforce the prejudices of society. Describing race,\nethnicity, disability, age, class, gender, and sexuality isn’t a negative thing, unless these\ndescriptions are being used in discriminatory ways. For example, only use the phrase “people of\ncolor” when you don’t have enough information to be more specific.\n\n## Avoiding microaggressions\n\nMicroaggressions are actions that aren’t intentionally aggressive, but contribute towards an\nenvironment that excludes people towards people who belong to marginalized communities. This makes\npeople feel excluded, fatigued, and unseen.\n\nIn writing, microaggressions are words that are associated with stereotypes, or phrases that have a\nnegative origin, like “long time no see” – a phrase historically used to make fun of people who\nspoke limited English, which has now slipped into casual use.\n\nThese words may seem inoffensive to some people. Remember that our goal is to do more than just\navoid causing offense. We want to create apps that include all people.\n\n### Avoid metaphors and idioms\n\nMetaphors and idioms are non-literal phrases people use in regular speech. Metaphors are when people\ncompare something to something else (such as “they were like a fish out of water”), while idioms are\nphrases where the meaning isn’t conveyed by any of the words (such as “between a rock and a hard\nplace”). Idioms are only understood from cultural familiarity with the phrase, which makes them\nunhelpful if you’re writing for a global audience.\n\nSome metaphors and idioms invoke histories of violence, patriarchy, or colonization. Other metaphors\nand idioms can confuse people outside of the group, country, or culture the phrase originates from.\nThis creates an environment that includes some people more than others.\n\nWhen you’re writing content for a wide audience, be literal. Don’t rely on harmful or confusing\nphrases.\n\n| Example                                                      | Alternative                                      | Reason                                                                                                                                                                                                                                 |\n| ------------------------------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| blacklist/whitelist                                          | blocklist/allowlist                              | Associating “black” with negative and “white” with positive experiences perpetuates racial inequity.                                                                                                                                   |\n| killing it                                                   | doing great work                                 | Violent words are unnecessary, and can cause negative feelings.                                                                                                                                                                        |\n| Automation in Jira makes work item creation a piece of cake. | Automation helps teams create work items faster. | Some people won’t have heard the phrase “piece of cake” used this way before, especially if English isn’t their first language. This creates an unnecessary barrier to comprehension that you can avoid by being accurate and literal. |\n\n### Word use, appropriation, and reclamation\n\nThe context and identity of the person using a word or phrase can change whether a word or phrase is\nhelpful or harmful. Sometimes words are used for their original purpose, sometimes they are\nappropriated, and sometimes words are reclaimed.\n\nAppropriation is when words are used outside of their original context in ways that are hurtful or\nminimizing to a group of people.\n\n| Appropriation                           | Proper use                                 | Reason                                                                                                            |\n| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |\n| Let’s have a powwow about the new logo. | I’m taking leave to attend a powwow.       | Powwows are important cultural gatherings, and using this as a throwaway word to describe a meeting is offensive. |\n| I’m so OCD about deleting my emails.    | My experiences getting diagnosed with OCD. | Avoid using medical and disability related terms as metaphors. It reinforces negative stereotypes.                |\n\nReclamation is when a group starts using language that people previously used to harm them, with the\nintention to make it a positive word or phrase. For example, the word ‘queer’ was previously used as\na homophobic term, but now many people describe themselves with the word ‘queer’. Don’t use these\nwords if you don’t belong to the group the word originates from.\n\n### Don’t make assumptions about abilities\n\nDon’t use phrasing that makes assumptions about how people experience your app. For example, by\nmaking claims about how easy your experience is.\n\n| Example                           | Alternative                             | Reason                                                                                               |\n| --------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| It’s easy to set up your project. | Set up your new project in a few steps. | It’s more precise about why the workflow is easy, without excluding people based on their abilities. |\n\n### Words that are misinterpreted as microaggressions\n\nDesigners avoid some words related to disabilities because they’re trying to be inclusive. These\nwords aren\'t microaggressions because words that relate to disabilities aren’t negative words. You\nonly need to avoid using them in a negative context.\n\nYou can use them if they help make things clear.\n\n| Phrasing                                                                                                                | Reason                                                                                                                                                                                                                                                        |\n| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Words related to vision, like: "View all Jira work items", "Watch the webinar recording", and "See what Trello can do". | People who are blind or low vision aren’t excluded by these words. They still ‘view’ a list of items, in a different way. Where it makes sense to do so, avoid these words. You don’t need to remove them if they’re accurate.                                |\n| Enabled/disabled                                                                                                        | Disabled isn\'t an offensive word. It reflects when people are limited by their environment, and society. Avoid associating the word disabled with negative states. Wherever you can, alternatives to ‘disabled’, like ‘turned off’ or ‘unavailable’ are good. |\n\n## Techniques for inclusive app experiences\n\n### Use they/them pronouns, and gender neutral language\n\nWhen referring to a person, use the pronouns they tell you to use. When referring to a person or a\ngroup of people you don’t know, use they/them pronouns. This makes the app more gender inclusive.\n\n| Example                                                                     | Alternative                                                            | Reason                                                          |\n| --------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------- |\n| Ask your project admin to enable editing permissions on his or her account. | Ask your project admin to enable editing permissions on their account. | Using they/them pronouns is more inclusive, and easier to read. |\n\n### Build inclusive forms\n\nWhen you gather data about people, remember that pre-defined categories don’t accurately reflect the\ndiversity of our world. Form fields can prevent people from using software if they\'re unable to fit\ninto the schemas we’ve defined for them.\n\nIf you need to collect information about people’s identities, give people the option to choose not\nto answer, or to give a self-defined answer. When gathering information about names, use a “Full\nname” field instead of separating names by first name, last name, and salutation.\n\nAvoid setting any particular group of people as the default option. This implies that other groups\nare not the norm, not common, or forces them to navigate and configure things more than others.\n\nOne way to avoid this is by not asking for more information than necessary. Often detailed personal\ninformation isn’t relevant to our apps, so ask yourself if you really need people to identify or\ngroup themselves before building this into apps.\n\n### Be accurate\n\nIt can be tempting to keep visual labels short, and hide the descriptive information behind an\naria-label. We’re moving away from this approach, because descriptive language also improves the\nexperience for people who don’t use assistive technology.\n\n| Example                                                                                                                                                            | Alternative                                                                                                                                                                          | Reason                                                                                                                                                                                                        |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Ask Atlassian Intelligence about a project or topic within your company’s knowledge base. [Learn more](https://www.atlassian.com/platform/artificial-intelligence) | Ask Atlassian Intelligence about a project or topic within your company’s knowledge base. [About Atlassian Intelligence](https://www.atlassian.com/platform/artificial-intelligence) | Accurate, descriptive links reduce the cognitive burden we put onto people using our apps. For more examples, read [alternatives to “learn more” (Atlassians only)](https://go.atlassian.com/learn-more-alt). |\n| Atlassian Intelligence is great for speeding up your work, and helping you be productive.                                                                          | Use Atlassian Intelligence to find answers, get summaries, and generate content.                                                                                                     | Don’t use vague promotional language. Describing new features with accuracy builds trust and helps people make informed decisions.                                                                            |\n| Step 1                                                                                                                                                             | Create project (Step 1 of 3)                                                                                                                                                         | Describe tasks accurately, so that people know where they are in their workflow.                                                                                                                              |\n\n### Write helpful examples\n\nIt can be tempting to use the example text for form fields or search boxes to add fun and delight to\nan app or platform.\n\nIf your example includes an example company name or task, make sure that these are accurate enough\nto convey what the example is showing.\n\n| Example                                                                         | Alternative                                                                              | Reason                                                                                                                |\n| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| Ask AI a question, like “Show me all work items in the ‘Donut Plains’ project.” | Ask AI a question, like “Show me all work items in the ‘Snack Delivery System’ project.” | It’s okay to make your examples fun, but don’t let specific cultural references make it confusing! Keep it universal. |\n\n### Make alt text concise and consistent\n\nIf images provide information, always include alternative text (“alt text”). When you’re writing\nalternative text, consider how that text will change the screen reader experience.\n\nIf you’re working on an app experience with elements that are very repetitive, like iconography,\ndon’t make alternative text too wordy as this will make the experience worse for people who use\nassistive technology. For example:\n\n| Not enough information | Too much information                                          | Just right       |\n| ---------------------- | ------------------------------------------------------------- | ---------------- |\n| Question mark          | Jira customer support question. Created by Jira service desk. | Support question |\n\nIf you’re using the same visuals in multiple places, make sure that you use the same alt text every\ntime it appears. The design system helps with this by providing label guidelines for components like\n[modal dialogs](https://atlassian.design/components/modal-dialog/examples) and\n[spinners](https://atlassian.design/components/spinner/examples).\n\n## Use reference material\n\nLanguage is changing all the time, so we don’t maintain a list of terms to use or avoid. Use\nresources like the\n[APA Inclusive Language Guide](https://www.apa.org/about/apa/equity-diversity-inclusion/language-guidelines)\nor\n[AP Stylebook](https://www.apstylebook.com/ap_stylebook?az_chapter=71&other_chapter=150#chapter_other_tab)\nto learn about specific terms.\n\n<SectionMessage title="We\'ve reorganized this website">\n\tThese guidelines are here to help you use inclusive language when designing apps and platforms.\n\tYou can access the{\' \'}\n\t<Link href="https://go.atlassian.com/global-inclusive-language">\n\t\tarchived global inclusive language guidelines (Atlassians only)\n\t</Link>\n\t, these are deprecated and will be replaced in the future.\n</SectionMessage>',
+  keywords: ['inclusive writing', 'inclusion', 'accessibility', 'content', 'language']
+}, {
+  content: '<SectionMessage title="Atlassian vocabulary">\n\tFor specific vocabulary and to view our internal word list and glossary, head to {\' \'}\n\t<Link href="https://go.atlassian.com/vocab">go/vocab (Atlassians only)</Link>.\n</SectionMessage>\n\n## Style and formatting\n\n### Abbreviations\n\n- Use the full name of features and apps in customer-facing copy.\n- Don’t use \'e.g.\', ‘i.e.’, ‘etc.’, or \'&\' as they\'re not localization friendly and can be confusing for users of assistive technologies.\n\n<DoDont type="do">Ask the experts at Jira Service Desk.</DoDont>\n<DoDont type="dont"> Ask the experts at JSD.</DoDont>\n\n<DoDont type="do">Use an input component. For example, a button or a select.</DoDont>\n<DoDont type="dont"> Use an input component, e.g. a button or a select etc.</DoDont>\n\n#### Plural abbreviations\nDon’t use an apostrophe for plural abbreviations.\n\n<DoDont type="do">1990s, DVDs</DoDont>\n<DoDont type="dont"> 1990’s, DVD’s</DoDont>\n\n### Articles (a, an, the)\n\nAvoid articles in buttons, labels, and action-based headings in the UI.\n\n<DoDont type="do">Create password</DoDont>\n<DoDont type="dont"> Create a password</DoDont>\n\n### Bold\n\nUse bold text to draw the reader’s eye to key phrases and statements in your content,\n  though don\'t over do it.\n- For in-app copy or help articles, use bold when referring to static UI elements like menu items,\n  buttons, or headings.\n- If bold is needed but the UI doesn’t support it — for example in a UI message or a flag where\n  the title is already bold — you can use [italics](#italics).\n\n<DoDont type="do">Go to <b>General configuration</b> then <b>User macros</b>.</DoDont>\n<DoDont type="dont">Go to the <b>settings page and select Configuration</b>.</DoDont>\n\n### Capitalization\n\n- Use sentence case in all titles, headings, menu items, labels, and buttons.\n- Capitalize proper nouns in headings, such as names of people, companies, or apps.\n\n<DoDont type="do">Create work item</DoDont>\n<DoDont type="dont">Create Work Item</DoDont>\n\n<DoDont type="do">Add permissions for Arni Karan</DoDont>\n<DoDont type="dont">Add permissions for arni karan</DoDont>\n\n### Contractions (shortened words)\n\n- Use contractions, where possible, as they convey a conversational, friendly tone.\n- Use curly apostrophes in UI copy\n\t- On a Mac: **option** + **shift** + **]**\n\t- On Windows: **Control** + **\'** (or **alt** + **0146**)\n\n<DoDont type="do">We can’t load this page.</DoDont>\n<DoDont type="dont">We cannot load this page.</DoDont>\n\n### Date and time\n\nView [date and time guidelines](https://atlassian.design/foundations/content/date-time).\n\n### Gender (he, she, they)\n\n- If known, use the pronouns a customer provides. If you don’t know, avoid gendered pronouns wherever\npossible.\n- If it’s not possible, use ’they’ or ’their’ rather than ‘his/her’ or ’he/she’.\n\n<DoDont type="do">Ask your admin to add you.</DoDont>\n<DoDont type="dont">Ask your admin if she can add you.</DoDont>\n\n<DoDont type="do">Add permissions to their account.</DoDont>\n<DoDont type="dont">Add permissions to her account.</DoDont>\n\n### Headings and titles\n\n- Use sentence case. Only capitalize the first word of a sentence, proper nouns, and trademarked\n  names (for example: apps, countries, people\'s names).\n- Don’t use bold or italics.\n- Don\'t use periods.\n- Reconsider using question marks. Preferably rephrase the heading so it’s a statement.\n- Phrase UI and documentation headings with an action verb.\n- Avoid gerunds (the ‘ing’ form of verbs) in UI copy.\n\n<DoDont type="do">Organize your to-do list with Trello</DoDont>\n<DoDont type="dont">Want to Organize <em>Your</em> To-Do List With Trello?</DoDont>\n\n<DoDont type="do">Add a page to your project</DoDont>\n<DoDont type="dont">Adding a page to your project</DoDont>\n\n#### Articles in headings\n\n- Articles (a, an, the) aren’t always needed in UI headings.\n- They\'re better suited to more conversational sections, like product marketing copy and empty states, as they make these sections more approachable and improve understanding.\n\n<DoDont type="do">Create work item</DoDont>\n<DoDont type="dont">Create a work item</DoDont>\n\n### Italics\n\nIn apps, use italics sparingly as it can be difficult to read. Don’t use italics in hyperlinks.\n\nItalics can be used for:\n- UI elements that might change, like a field name or user input.\n- For emphasis if the UI doesn’t support bold. For example, in a flag or UI message.\n\n### Lists\n\nUse lists to draw the reader’s eye and make items easier to scan and follow. Try to limit lists to 6 items or less. If there are more items, make multiple lists.\n\n#### Bulleted list\n\n- Use to list options or when the order of the items doesn’t matter.\n- Phrase each item in a parallel way.\n- Don’t use commas or periods at the end of each item.\n\n##### Fragmented sentences\n\nIf your list has fragmented sentences, use a lowercase letter for each item and don’t use a period at the end of the list. Use a lead-in sentence with a colon before the items.\n\n<DoDont type="do">\n\tDue to security concerns, all employees are required to:\n\t<ul>\n\t\t<li>wear an identification tag</li>\n\t\t<li>use their security pass to enter or leave an office before 7 a.m. and after 6 p.m.</li>\n\t\t<li>alert security if a suspicious package is found</li>\n\t</ul>\n</DoDont>\n\n<DoDont type="dont">\n\tDue to security concerns, all employees are required to;\n\t<ul>\n\t\t<li>Wear an identification tag in the building,</li>\n\t\t<li>You must use your identification tag to enter an office before 7 a.m. and exit after 6 p.m., and</li>\n\t\t<li>If a suspicious package is found, alert security.</li>\n\t</ul>\n</DoDont>\n\n##### Complete sentences\n\nFor lists with complete sentences, start an item with a capital letter and end it with a period. Don’t use a lead-in sentence with a colon.\n\n<DoDont type="do">\n\tAtlassian has updated security requirements for employees.\n\t<p></p>\n\t<ul>\n\t\t<li>Always wear your identification tag when working in an office.</li>\n\t\t<li>Use your identification tag to enter an office before 7 am and when you leave after 6 pm.</li>\n\t</ul>\n</DoDont>\n\n<DoDont type="dont">\n\tAtlassian has updated security requirements for employees:\n\t<ul>\n\t\t<li>always wear your identification tag when working in an office</li>\n\t\t<li>use your identification tag to enter an office before 7 am and when you leave after 6 pm.</li>\n\t</ul>\n</DoDont>\n\n#### Numbered lists\n\nUse numbered lists for tasks or lists where the order of the items matters. Capitalize the first word of each item and end the item with a period.\n\n<DoDont type="do">\n\tTo add a new user macro:\n\t<ol>\n\t\t<li>Go to <b>Settings</b> then <b>General configuration</b> then <b>User macros</b>.</li>\n\t\t<li>Choose <b>Create a user macro</b>.</li>\n\t\t<li>Enter the macro details.</li>\n\t</ol>\n</DoDont>\n\n<DoDont type="dont">\n\tTo add a new user macro -\n\t<ol>\n\t\t<li>go to <b>Settings</b> then <b>General configuration</b> then <b>User macros</b></li>\n\t\t<li>choose <b>Create a user macro</b></li>\n\t\t<li>enter the macro details.</li>\n\t</ol>\n</DoDont>\n\n### Monospaced text\n\nUse `monospaced font` for names of a file or directory. It’s mostly used in attributes, strings, and administrator and developer docs.\n\n<DoDont type="do">The location of the Home directory is stored in a configuration file called <code>confluence-init.properties</code>.</DoDont>\n<DoDont type="dont">The location of the Home directory is stored in a configuration file called <b>confluence-init.properties</b>.</DoDont>\n\n\n### Numbers\n\nUse digits rather than words in most cases.\n\n**Exceptions**:\n\n- If a number starts a sentence, write it out.\n- In common expressions, write the number out. For example: _It’s one thing after another_.\n- When writing long-form or formal content, write out numbers one to nine.\n- Write out the numbers ‘zero’ and ‘one’ if it could be confused for the letters L, I, or O.\n\n<DoDont type="do">Your password should be a minimum of 8 characters. </DoDont>\n<DoDont type="dont">Your password should be a minimum of eight characters.</DoDont>\n\n<DoDont type="do">Loom is one of the best apps for sharing information in a personal way.</DoDont>\n<DoDont type="dont">Loom is 1 of the best apps for sharing information in a personal way.</DoDont>\n\n#### Number ranges\n\nUse ’to’ and not hyphens in number ranges, except if space is limited, like in a table or mobile app.\n\n<DoDont type="do">View rows 1 to 4 in the table.</DoDont>\n<DoDont type="dont">View rows 1-4 in the table.</DoDont>\n\n#### Numbers \'out of\'\n\nUse ‘of’ rather than a forward slash ( / ) to show a number out of another number.\n\n<DoDont type="do">Step 1 of 2</DoDont>\n<DoDont type="dont">Step 1/2</DoDont>\n\n#### Numbers from 1,000\n\nUse a comma to indicate the thousand in a number.\n\n<DoDont type="do">\n\t<ul>\n\t\t<li>4,500</li>\n\t\t<li>10,000</li>\n\t\t<li>1,250,000</li>\n\t</ul>\n</DoDont>\n\n<DoDont type="dont">\n\t<ul>\n\t\t<li>4500</li>\n\t\t<li>10000</li>\n\t\t<li>1250000</li>\n\t</ul>\n</DoDont>\n\n### Spelling words\n\nUse US English in UI copy and code. Check spellings in [Merriam-Webster online dictionary](https://www.merriam-webster.com/).\n\n<DoDont type="do">\n\t<ul>\n\t\t<li>color</li>\n\t\t<li>organization</li>\n\t\t<li>labeled</li>\n\t</ul>\n</DoDont>\n\n<DoDont type="dont">\n\t<ul>\n\t\t<li>colour</li>\n\t\t<li>organisation</li>\n\t\t<li>labelled</li>\n\t</ul>\n</DoDont>\n\n### Truncation\n\nEllipses (…) are used to show that text has been cut off — or truncated — when a message doesn’t fit in a given space.\n- Avoid truncation whenever possible: shorten UI messages or wrap the text.\n- Test your designs using multiple screen widths and magnification levels to ensure it doesn’t truncate.\n- If truncation can’t be avoided, for example in user-generated content or icon buttons, use a [tooltip](https://atlassian.design/components/tooltip/examples) to display the full text for accessibility and usability.\n- In ADS components that truncate, the ellipsis appears without any space next to the last visible character (for example: Work in pro…).\n\n<DoDont type="do" image={{ url: truncationDo, alt: "" }}>\n    Shorten or wrap messages.\n</DoDont>\n<DoDont type="dont" image={{ url: truncationDont , alt: "" }}>\n    Don’t truncate unless it can’t be avoided.\n</DoDont>\n\n### UI elements\n\n- Use sentence case, even if the UI element doesn’t use it.\n- Use bold to emphasize the UI element in a step.\n- If the UI element has an icon, bold both the name and the icon.\n- Avoid using a > symbol where possible, as it is read out as “greater than” by assistive technologies, leading to confusion. Use ‘then’ instead.\n\n<DoDont type="do">Go to <b>More</b>, then <b>Link work item</b>. </DoDont>\n<DoDont type="dont">Go to <b>More</b> > <b>Link Work Item</b>. </DoDont>\n\n## Grammar\n\n### Active voice\n\nUse active voice whenever possible as it improves readability and reflects Atlassian’s [voice and tone](https://atlassian.design/foundations/content/voice-tone).\n\nActive voice:\n- puts the emphasis on the person or thing doing an action.\n- makes content shorter, clearer, friendlier, and more conversational.\n\n<DoDont type="do">Administrators control access to Atlassian Cloud applications.</DoDont>\n<DoDont type="dont">Access to Atlassian Cloud applications is controlled by administrators.</DoDont>\n\n### Pronouns (you, your, we)\n\n- Minimize the use of pronouns.\n- Most of the time they can be avoided. However, when advising a user, indicating that something in the UI is theirs, or in error messages, you can use ‘you’ or ’your’ or ’we’ for a friendlier tone.\n\n<DoDont type="do">Get access to your work items here.</DoDont>\n<DoDont type="dont">Get access to the work items here.</DoDont>\n\n<DoDont type="do">Your projects</DoDont>\n<DoDont type="dont">My projects</DoDont>\n\n<DoDont type="do">We couldn\'t load your page</DoDont>\n<DoDont type="dont">The page couldn\'t be loaded </DoDont>\n\n### Tense\n\n**Present tense** helps make instructions and messages in the UI clear and engaging.\n\n<DoDont type="do">We can’t load work item DSP-32113.</DoDont>\n<DoDont type="dont">We couldn’t load work item DSP-32113.</DoDont>\n\n<DoDont type="do">Validation is required.</DoDont>\n<DoDont type="dont">Validation will be required.</DoDont>\n\n**Past tense** can be used to communicate a completed action, like in error message headings and success flags, or where there could be confusion.\n\n<DoDont type="do">\n\t<ul>\n\t\t<li>Upload failed</li>\n\t\t<li>File created</li>\n\t</ul>\n</DoDont>\n\n<DoDont type="dont">\n\t<ul>\n\t\t<li>Upload fail</li>\n\t\t<li>File create</li>\n\t</ul>\n</DoDont>\n\n## Punctuation\n\n### Apostrophes (\')\n- Use an apostrophe to show possession. The apostrophe is placed before the ‘s’ for singular terms and after the ‘s’ for plurals.\n- If a word ends in an ‘s’ and is singular, add an ‘s after the ‘s’.\n- Use a curly apostrophe for better readability and to differentiate from code.\n\t- On a Mac: **option** + **shift ** + **]**\n\t- On Windows: **Control** + **\'** (or **alt** + **0146**)\n\n<DoDont type="do">\n\t<ul>\n\t\t<li>A week’s time</li>\n\t\t<li>Three weeks’ time</li>\n\t\t<li>James’s work items</li>\n\t</ul>\n</DoDont>\n\n<DoDont type="dont">\n\t<ul>\n\t\t<li>A weeks time</li>\n\t\t<li>Three week\'s time</li>\n\t\t<li>James\' work items</li>\n\t</ul>\n</DoDont>\n\n### Colons (:)\n\n- Use colons to introduce a bulleted list or series of steps.\n- Don’t use colons at the end of headings.\n\n<DoDont type="do">\n\tA password should have:\n\t<ul>\n\t<li>12 characters or more </li>\n\t<li>at least one symbol and one number</li>\n\t<li>a mix of capital and lowercase letters</li>\n\t</ul>\n</DoDont>\n<DoDont type="dont">\n<p><b>Turn on two-factor authentication:</b></p>\n<p>Keep your account safe with an extra layer of security.</p>\n</DoDont>\n\n### Commas (,)\n\nUse an Oxford (or ‘serial’) comma to offset the final item in a list.\n\n<DoDont type="do">Jira, Confluence, Loom, and Bitbucket are all Atlassian apps.</DoDont>\n<DoDont type="dont">Jira, Confluence, Loom and Bitbucket are all Atlassian apps. </DoDont>\n\n### Dashes (—) and hyphens (-)\n\n#### Dashes\n\n- Use dashes in UI content sparingly. If using, use a spaced em dash.\n- In long-form content, use them sparingly to show an abrupt change in a sentence — like this. If the break happens in the middle of a sentence —  ike this — use spaced em dashes on either side of the phrase.\n- If possible, rewrite the sentence or make 2 sentences to avoid a dash. Clear, concise sentences are better for readability and accessibility.\n- Don\'t use a dash or hyphen for ranges of numbers. Use \'to\' instead.\n- When adding the space, use non-breaking spaces (**option** + **shift** + **space**) to avoid the dash shifting to a new line.\n- To make an em dash:\n\t- On a Mac: **option** + **shift** + **hyphen**\n\t- On Windows: **Control** + **Alt** + **-** (or **Alt** + **0151**)\n\n<DoDont type="do">Jira Service Management belongs to Jira\'s family of apps. They’re all built on the same platform and share the same site URL.</DoDont>\n<DoDont type="dont">Jira Service Management belongs to Jira\'s family of apps — they’re all built on the same platform and share the same site URL.</DoDont>\n\n<DoDont type="do">50 to 100</DoDont>\n<DoDont type="dont">50—100</DoDont>\n\n#### Hyphens\n\n- If a noun is described by 2 or more words, use a hyphen to join those words together so they act as a compound adjective (or compound modifier).\n- **Exceptions**: don’t add a hyphen after the word ‘very’ or adverbs ending in -ly.\n- For specific hyphenated word guidance, check [Vocabulary (Atlassians only)](https://hello.atlassian.net/wiki/spaces/AV/pages/1686830783/Atlassian+global+vocabulary+list).\n- Use a hyphen when not doing so could cause confusion or ambiguity. Consult the [Merriam-Webster dictionary](https://www.merriam-webster.com/) if you’re not sure.\n\n<DoDont type="do">\n\t<ul>\n\t<li>system-wide update</li>\n\t<li>character-counter logic</li>\n\t<li>widely communicated update</li>\n\t<li>very cold drink</li>\n\t<li>autocorrect</li>\n\t<li>coworker</li>\n\t<li>preexisting</li>\n\t</ul>\n</DoDont>\n<DoDont type="dont">\n<ul>\n\t<li>system wide update</li>\n\t<li>character counter logic</li>\n\t<li>widely-communicated update</li>\n\t<li>very-cold drink</li>\n\t<li>auto-correct</li>\n\t<li>co-worker</li>\n\t<li>pre-existing</li>\n\t</ul>\n</DoDont>\n\n<DoDont type="do">\n\t<ul>\n\t<li>re-sign the document</li>\n\t<li>re-create the page</li>\n\t</ul>\n</DoDont>\n<DoDont type="dont">\n<ul>\n\t<li>resign the document</li>\n\t<li>recreate the page</li>\n\t</ul>\n</DoDont>\n\n### Ellipses ( … )\n\n- Don’t put spaces in between the periods in an ellipsis.\n- Use the symbol for the ellipsis rather than a string of periods:\n\t- On a Mac: **Option** + **;**\n\t- On Windows: **Ctrl** + **Alt** + **.** (or **Alt** + **0133**)\n\n\n#### Truncation\nEllipses can be used to show that text has been cut off — or truncated — when a message doesn’t fit in a given space. View [truncation guidance](#truncation).\n\n#### Quotes\n\n- When using an ellipsis to omit part of a long quote, include spaces on either side of the ellipsis ( … ).\n- For example: “From medicine and space travel to disaster response … our products help teams all over the planet advance humanity through the power of software.” Atlassian: Discover our story.\n\n### Exclamation marks (!)\n\n- Avoid exclamation marks in UI copy and minimize their use in product marketing copy.\n- They can be considered for exciting or new things, but ask yourself if it’s really that exciting or if one is needed. Don’t use more than one exclamation mark per page.\n\n<DoDont type="do">Project is complete.</DoDont>\n<DoDont type="dont">Project is complete!</DoDont>\n\n### Periods (.)\n\n- Use a period (full stop) at the end of complete sentences, including in helper text, messages, and notifications.\n- Don’t use periods in headers, titles, tooltips, field descriptions, and menu names, even if they are full sentences. While long content is discouraged, an exception is if these elements contain more than 1 sentence.\n- Only use periods in a bulleted list if the item is a complete sentence. Don’t add a period at the end of a list of fragments.\n- Add only one space after a period (full stop).\n\n<DoDont type="do"><p><b>Accessibility principles</b></p>\n<p>Our principles cover the main requirements to design and build accessible experiences.</p></DoDont>\n<DoDont type="dont"><p><b>Accessibility principles.</b></p>\n<p>Our principles cover the main requirements to design and build accessible experiences.</p></DoDont>\n\nIf a link ends a sentence, include a period but don’t hyperlink it.\n\n<DoDont type="do">Atlassian’s work is guided by <a href="https://www.atlassian.com/company/values">5 core values</a>.</DoDont>\n<DoDont type="dont">Atlassian’s work is guided by <a href="https://www.atlassian.com/company/values">5 core values.</a></DoDont>\n\n### Quotation marks (‘’ | “”)\n\nIn the UI, use:\n- single curly quotes, unless you\'re writing in code or there’s a semantic reason to use straight quotes.\n\nIn body copy and long-form content, such as documentation and marketing, use:\n- double quotes (”“) for speech and direct quotes. Don’t use italics.\n- single quotes (‘’) to draw attention to a word you’re defining.\n\n<DoDont type="do">“We have big things planned for the coming year,” said Mike.</DoDont>\n<DoDont type="dont">‘We have big things planned for the coming year,’ said Mike.</DoDont>\n\n<DoDont type="do">They tried to avoid talking about the ‘big’ secret.</DoDont>\n<DoDont type="dont">They tried to avoid talking about the “big“ secret.</DoDont>\n\n#### Emphasis\n\nDon’t use quotation marks to emphasize UI elements, page titles, and other objects. Instead use [bold](#Bold).\n\n<DoDont type="do">Go to <b>Settings</b>.</DoDont>\n<DoDont type="dont">Go to ‘Settings’.</DoDont>\n\n#### Shortcuts\n\n##### Mac\n\n- Double quotes:\n\t- opening marks: **option** + **[**\n\t- closing marks: **option** + **shift** + **[**\n- Single quotes:\n\t- opening marks: **option** + **]**\n\t- closing marks: **option** + **shift** + **]**\n\n##### Windows\n\n- Double quotes:\n\t- opening marks: **Alt** + **0147**\n\t- closing marks: **Alt** + **0148**\n- Single quotes:\n\t- opening marks: **Alt** + **0145**\n\t- closing marks: **Alt** + **0146**',
+  keywords: ['language', 'grammar', 'capitalization', 'truncation', 'content']
+}, {
+  content: 'We use the Atlassian voice and tone in all of our properties and content, from user interfaces to\nemail, social media, and other channels.\n\nAny Atlassian who works with customer-facing communications should follow the voice and tone\nguidelines: content designers, engineers, product designers, blog contributors, product managers,\nmarketers... pretty much everyone.\n\nTo help teams do the best work of their lives, we:\n\n- offer solutions that help people at the moment they need it\n- simplify complex problems into easy-to-understand pieces\n- inspire people to try new things\n\nWith a familiar tone, clear language, and a solid knowledge of our audience, we craft messages that\nget teams moving in the right direction, then we get out of their way.\n\nThe Atlassian voice is based on the Atlassian brand personality traits of:\n\n- bold\n- optimistic\n- practical, with a wink\n\nTo provide consistent, friendly, and helpful content for people, use this guidance with our other\nguidelines:\n\n- [Language and grammar](https://atlassian.design/foundations/content/language-and-grammar)\n- [Inclusive language](https://atlassian.design/foundations/content/inclusive-writing)\n- [Vocabulary (Atlassians only)](https://go.atlassian.com/vocab)\n\n## Atlassian’s personality traits\n\nWhen writing with Atlassian\'s voice, we\'re part of the team. We\'re that friend or colleague who is\nalways up on new trends and wants to be helpful and share new wisdom with everyone in a relatable\nway.\n\nWe know when it\'s time to be serious and direct, and when it\'s time to be more casual.\n\nPersonality comes across best in the details. The emphasis of each trait should be contextual to the\naudience and situation.\n\nHere are some questions you can ask yourself during your process to assess whether or not you’re\nleveraging our personality traits well.\n\n- What is the emotional state of the person when encountering your solution during their journey?\n- How might our personality traits help enhance a moment of celebration?\n- How might our personality traits help diffuse a moment of frustration or pain?\n\n### Bold\n\nMotivate teams to do their best work. Offer best practices to get people going in the right\ndirection.\n\nBe bold and offer just enough help to get the work started, and then get out of the way.\n\nGive accurate information so people can make educated decisions. Understand the person\'s struggles\nand desired outcomes and give enough information to let them get where they need to go.\n\n### Optimistic\n\nGo on the journey with people and highlight the key points that will help them the most, right now.\n\nBe in the moment by focusing attention on the important bits first. This gives people confidence in\nour apps.\n\nWeave a consistent story across our fabric and be diligent about vocabulary across all messaging by\nbeing brand-conscious across apps.\n\nCreate a seamless flow across all the things. Let people know that they can jump in and start\nworking, and can expect a familiar experience across all of the things. Keep teams in the loop about\nwhat is happening by informing them of relevant features, apps, and opportunities for success.\n\n### Practical, with a wink\n\nGet to the point and be direct. Be concise.\n\nBe on the lookout for opportunities and be quick to offer a helping hand. Give the user just enough\nto know that something awesome is around the corner and then get out of the way.\n\nWrite clear, accurate, and concise text that makes interfaces more usable and consistent — and\nbuilds trust.\n\nWrite text that is understandable by anyone, anywhere, regardless of their culture or language so\nthat everyone feels they are part of the team.\n\n## Voice and tone principles\n\nA consistent voice creates better relationships with our customers.\n\nBut, there is one caveat.\n\nThere are times when you need to speak to different subsets of people, for instance among different\napps, and your tone might not be quite the same. That\'s okay! We\'ve provided enough guidance to help\nadjust our tone to accommodate for:\n\n- where people are at in their journey\n- their emotional state\n- the app or property you are writing for\n\nThe voice and tone principles:\n\n- [Inform to build trust](https://atlassian.design/foundations/content/voice-tone#inform-to-build-trust)\n- [Empower to inspire action](https://atlassian.design/foundations/content/voice-tone#empower-to-inspire-action)\n- [Encourage people along the path](https://atlassian.design/foundations/content/voice-tone#encourage-people-along-the-path)\n- [Motivate by showing possibilities](https://atlassian.design/foundations/content/voice-tone#motivate-by-showing-possibilities)\n- [Satisfy by meeting expectations](https://atlassian.design/foundations/content/voice-tone#satisfy-by-meeting-expectations)\n- [Delight with unexpectedly pleasing experiences](https://atlassian.design/foundations/content/voice-tone#delight-with-unexpectedly-pleasing-experiences)\n\n### Inform to build trust\n\n**Inform** by being **open** and **clear** on what people are experiencing in our apps.\n\nTell people what they need to know at that moment and nothing more. Be aware of when a user may be\nnew or confused, and tone down the boldness by being more prescriptive. Let people know where they\nare in their journey and what they are looking at in the app.\n\nWrite as a knowledgable member of the team. Show up at the right time and be open, humble, and warm\n— offer direction for the most appropriate next steps and get out of the way.\n\n#### When we need to be less bold\n\nPerson is feeling: apprehension, confusion, annoyance, fear, loathing, anger.\n\nExamples: new users, evaluators, and when introducing a new concept, feature, or app\n\n<img\n\tsrc={lessBoldLight}\n\tsrcDark={lessBoldDark}\n\talt="Slider between less bold and more bold, with the dot much closer to less bold end."\n/>\n\n#### Places we use this principle\n\n- In-app: [flags](https://atlassian.design/components/flag/usage),\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages),\n  and [onboarding (spotlight)](https://atlassian.design/components/onboarding/usage)\n- Being informative and to build trust\n\n### Empower to inspire action\n\n**Educate** where we people need it most. Offer **opportunities** to learn at pivotal times to\n**empower** people to move in the right direction. Offer best practices and recommendations for next\nsteps while suggesting ways to improve and make decisions.\n\nLet people know Atlassian and fellow community members are available to help people make decisions.\n\nWrite as if you are educating. You are a teacher with empathy and an understanding of what it’s like\nto be in the weeds. You expect your audience to have a basic understanding.\n\n#### When we want to be more bold\n\nPerson is feeling: confident, interested, trust, anticipation.\n\nExamples: power users, admins, everyday users\n\n<img\n\tsrc={moreBoldLight}\n\tsrcDark={moreBoldDark}\n\talt="Slider between less bold and more bold, with the dot much closer to more bold end."\n/>\n\n#### Places we use this principle\n\n- In-app: [onboarding (spotlight)](https://atlassian.design/components/onboarding/usage),\n  [benefits modal](https://atlassian.design/components/onboarding/benefits-modal/usage), and\n  [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- Something requires an action from the person\n- Educational opportunities\n- Social opportunities — let them know best practices\n\n### Encourage people along the path\n\n**Inspire** initial **optimism** by providing **support** in the right place. Be **consistent** and\n**dependable**.\n\nOffer waypoints, help, and support if people are feeling confused or frustrated at a point in their\njourney. This principle is about being human, giving guidance, support, and encouragement along the\nway.\n\nGuide people by revealing information gracefully. Let them know they are on the right path, they\naren’t alone, and that delivering projects and building teams can be challenging.\n\nWrite in an upbeat, friendly way. Acknowledge the opportunities in the here-and-now and walk through\nit with them.\n\n#### When we need to be less optimistic\n\nPerson is feeling: anticipation, unsupported, confused, uncertain\n\nExamples: new to Atlassian, evaluators, or when introducing a new concept, feature, or app\n\n<img\n\tsrc={lessOptimisticLight}\n\tsrcDark={lessOptimisticDark}\n\talt="Slider between less optimistic and more optimistic, with the dot much closer to the less optimistic end."\n/>\n\n#### Places we use this principle\n\n- In-app:\n  [information messages](https://atlassian.design/foundations/content/designing-messages/info-messages),\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages),\n  and [section messages](https://atlassian.design/components/section-message/usage)\n- Something requires an action from the person\n\n### Motivate by showing possibilities\n\nProvide **incentive** and **excitement** for continued growth.\n\nConsider why someone would want to do this.\n\nShow the possibilities of what can be accomplished by giving examples of how other people accomplish\nthe same task, or by presenting the ideal state. Describe the end result, giving expert testimony,\nor offer opportunities for advanced knowledge.\n\nWrite like an expert. Focus more on the solution than on the problem. Show people the possible\nbenefits.\n\n#### When we want to be more optimistic\n\nPerson is feeling: ambitious, inspired, curious, admiration.\n\nExamples: power users, admins, everyday users\n\n<img\n\tsrc={moreOptimisticLight}\n\tsrcDark={moreOptimisticDark}\n\talt="Slider between less optimistic and more optimistic, with the dot much closer to the more optimistic end."\n/>\n\n#### Places we use this principle\n\n- In-app: [onboarding (spotlight)](https://atlassian.design/components/onboarding/usage) and\n  [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- Educational opportunities — it\'s a chance to tell them how other industry leaders do it, give best\n  practices, and tips and tricks\n\n### Satisfy by meeting expectations\n\nGive people what they need.\n\nProvide **quick and thorough** answers, guidance, actions, and instructions. We aren’t trying to\nlead, inspire, motivate, delight, or encourage. Simply tell people what they need to know and get\nout of the way.\n\nAll of our content should be practical at a minimum. Write as if you are explaining to your friend\nhow to travel somewhere you’ve visited regularly.\n\n#### When we need to be practical\n\nPerson is feeling: overwhelmed and stressed.\n\nExamples: people under pressure with deadlines — everyone feels this way sometimes\n\n<img\n\tsrc={lessWinkyLight}\n\tsrcDark={lessWinkyDark}\n\talt="Slider between practical and winky, with the dot much closer to the practical end."\n/>\n\n#### Places we use this principle\n\n- Whenever we can\n- In-app:\n  [warning messages](https://atlassian.design/foundations/content/designing-messages/warning-messages),\n  [information messages](https://atlassian.design/foundations/content/designing-messages/info-messages),\n  and\n  [error messages](https://atlassian.design/foundations/content/designing-messages/error-messages)\n\n### Delight with unexpectedly pleasing experiences\n\n“Wink” where appropriate. We deliver appropriate **delight** — celebrate **success** or **progress**\nonce we’ve built **trust**.\n\nBut don’t overdo it. These are little flourishes: we give flowers, not puppies.\n\nPay particular attention to people’s state of mind. Think about the timing, and how frequently they\nwill see this.\n\n#### When we can share a little delight\n\nPerson is feeling: successful, joy, pride, relief.\n\nExamples: evaluators, power users, during social interactions\n\n<img\n\tsrc={moreWinkyLight}\n\tsrcDark={moreWinkyDark}\n\talt="Slider between practical and winky, with the dot much closer to the winky end."\n/>\n\n#### Places we use this principle\n\n- In-app:\n  [success messages](https://atlassian.design/foundations/content/designing-messages/success-messages)\n  and [modal dialogs](https://atlassian.design/components/modal-dialog/usage)\n- Social interactions and while introducing new experiences',
+  keywords: ['voice', 'tone', 'writing', 'content', 'brand']
+}];

package/dist/cjs/tools/get-guidelines/index.js

@@ -0,0 +1,99 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.listGetGuidelinesTool = exports.getGuidelinesTool = exports.getGuidelinesInputSchema = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _fuse = _interopRequireDefault(require("fuse.js"));
+var _zod = require("zod");
+var _helpers = require("../../helpers");
+var _guidelinesStructuredContent = require("./guidelines-structured-content.codegen");
+/* eslint-disable-next-line import/extensions -- MCP SDK requires .js extensions for ESM imports */
+
+var getGuidelinesInputSchema = exports.getGuidelinesInputSchema = _zod.z.object({
+  terms: _zod.z.array(_zod.z.string()).default([]).describe('An array of search terms to find content guidelines by keywords or content, eg. `["messages", "empty state", "voice tone"]`. If empty or not provided, returns all guidelines.').optional(),
+  limit: _zod.z.number().default(1).describe('Maximum number of results per search term in the array (default: 1)').optional()
+});
+var listGetGuidelinesTool = exports.listGetGuidelinesTool = {
+  name: 'ads_get_guidelines',
+  description: "Get Atlassian Design System content guidelines (foundations content) with optional search functionality.\n\n- If search parameters are provided, searches for guidelines matching the criteria by keywords or content.\n- If no search parameters are provided, returns all guidelines.\n\nExample: use this tool to look up content guidance for designing messages, voice and tone, date and time, inclusive writing, or language and grammar.",
+  annotations: {
+    title: 'Get ADS guidelines',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: (0, _helpers.zodToJsonSchema)(getGuidelinesInputSchema)
+};
+var getGuidelinesTool = exports.getGuidelinesTool = /*#__PURE__*/function () {
+  var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(params) {
+    var _params$terms, terms, _params$limit, limit, searchTerms, guidelineDocs, allGuidelinesMarkdown, fuse, results, seen, uniqueResults, matchedGuidelines, formattedGuidelines;
+    return _regenerator.default.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          _params$terms = params.terms, terms = _params$terms === void 0 ? [] : _params$terms, _params$limit = params.limit, limit = _params$limit === void 0 ? 1 : _params$limit;
+          searchTerms = terms.filter(Boolean).map(_helpers.cleanQuery);
+          guidelineDocs = _guidelinesStructuredContent.guidelinesStructuredContent; // If no search terms provided, return all guidelines formatted as Markdown
+          if (!(searchTerms.length === 0)) {
+            _context.next = 6;
+            break;
+          }
+          allGuidelinesMarkdown = guidelineDocs.map(function (guideline) {
+            return guideline.content;
+          }).join('\n\n');
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: allGuidelinesMarkdown
+            }]
+          });
+        case 6:
+          // Use Fuse.js to fuzzy-search by keywords and content
+          fuse = new _fuse.default(guidelineDocs, {
+            keys: [{
+              name: 'keywords',
+              weight: 3
+            }, {
+              name: 'content',
+              weight: 1
+            }],
+            threshold: 0.4
+          });
+          results = searchTerms.map(function (term) {
+            return fuse.search(term).slice(0, limit);
+          }).flat(); // Remove duplicates by content (same guideline can match multiple terms)
+          seen = new Set();
+          uniqueResults = results.filter(function (result) {
+            var text = result.item.content;
+            if (seen.has(text)) {
+              return false;
+            }
+            seen.add(text);
+            return true;
+          });
+          matchedGuidelines = uniqueResults.map(function (result) {
+            return result.item;
+          });
+          formattedGuidelines = matchedGuidelines.map(function (guideline) {
+            return guideline.content;
+          }).join('\n\n');
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: formattedGuidelines
+            }]
+          });
+        case 13:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee);
+  }));
+  return function getGuidelinesTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();