@atlaskit/ads-mcp 1.12.6 → 1.12.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,7 +9,7 @@ exports.guidelinesStructuredContent = void 0;
9
9
  *
10
10
  * Structured content for authored agent guidelines and design-system-docs foundations content.
11
11
  *
12
- * @codegen <<SignedSource::d37366d3a7d35067f9080be0dfa1463f>>
12
+ * @codegen <<SignedSource::5879a53f49ff5634b7e5a4c34a6de527>>
13
13
  * @codegenCommand yarn build structured-docs
14
14
  */
15
15
 
@@ -17,7 +17,7 @@ var guidelinesStructuredContent = exports.guidelinesStructuredContent = [{
17
17
  content: "## Building accessible apps\n\nAn accessible app means people of all abilities can interact with, understand, and navigate it.\n\nADS components ship with built-in accessibility features, such as keyboard support and sensible ARIA\nusage. However, you still need to review your patterns, content, and interactions so your app is\naccessible end-to-end.\n\n### Follow our accessibility principles\n\nOur principles cover the main requirements to design and build accessible experiences, helping you\nto put accessibility into action.\n\n#### Build consistent experiences\n\nThe user experience should be familiar, identifiable, and work as expected regardless of device,\nscreen size, platform, or assistive technology.\n\n- Use design system components as the basis of every experience. They have inbuilt accessibility\n features and create consistency across apps.\n- Ensure the same components, patterns, and interactions are used for the same experiences across\n pages and apps to lessen cognitive load.\n\n#### Keep experiences and language simple\n\nRespect people’s time by making apps that are uncomplicated and easy to use.\n\n- Avoid complex process and experiences.\n- Use similar patterns across apps and experiences.\n- Use concise and plain language.\n- Aim for content to be written at a reading level of ages 12 to 14.\n\n#### Be inclusive\n\nAccessible design is inclusive of people of all races, ethnicities, genders, sexual orientations,\nand backgrounds.\n\n- Use [inclusive language](https://atlassian.design/foundations/content/inclusive-writing).\n- Don’t make assumptions about people’s abilities.\n- Avoid jargon,\n [metaphors, and non-literal phrases](https://atlassian.design/foundations/content/inclusive-writing#avoid-metaphors-and-idioms).\n\n#### Give people control\n\nPeople should be able to adapt our apps to suit their needs.\n\n- Enable [reflow](https://www.w3.org/WAI/WCAG21/Understanding/reflow.html) across all screen sizes.\n- Allow people to adjust scale, contrast, and colors.\n- Make sure personal reduced motion settings are respected by our apps.\n- Inform people about high-impact changes before you make them.\n\n#### Provide text alternatives\n\nText is powerful for assistive technologies, as it can be seen on a screen, heard using\ntext-to-speech, and touched with a braille screen reader.\n\n- Use visible and accessible labels.\n- Write clear and concise labels and\n [alternative (alt) text](https://accessibility.huit.harvard.edu/describe-content-images).\n- Include a transcript for videos on the page or link to it.\n\n#### Ensure color is accessible\n\nSome people can’t perceive color, while others perceive limited color.\n\n- Never rely on color alone to convey meaning.\n- Use a color contrast ratio of 4.5:1 for regular text and 3:1 for large text and graphics.\n\n#### Use semantic HTML\n\n[Semantic HTML](https://www.w3schools.com/html/html5_semantic_elements.asp) describes the exact\nmeaning of an element to a web browser. It helps people using assistive technology navigate and\ninterpret page elements.\n\n- Use `header` , `nav`, `footer` (for example).\n- Don't use `div` or `span` (for example) as they don't convey meaning.\n\n#### Test apps broadly\n\nTest with different tools and a diverse array of people.\n\n- Test apps with people with disabilities and across different levels of technical experience.\n- Use different types of technology and accessibility tools, such as\n [Accessibility Insights](https://accessibilityinsights.io), to test your app.\n\n## What to consider when building accessible apps\n\nEveryone will experience a disability at some point in their lives, whether it's a situational\nimpairment or a permanent or temporary disability. At these times, assistive technology can help\npeople use our apps — but only if they’re built to be accessible.\n\nConsider the following when designing and building your app. And remember: people are multi-faceted,\nso it's important not to solve for one disability in isolation.\n\n### Visual disabilities\n\n- Provide clear and informative alternative (alt) text and semantic HTML.\n- Don’t rely on color alone to convey meaning, and make sure color contrast is accessible.\n- Examples of visual disabilities include:\n - Blind (permanent)\n - Migraine (temporary)\n - Lost glasses (situational)\n\n### Auditory disabilities\n\n- Include closed captions and transcripts for videos.\n- Make sure transcripts for audio are available.\n- Examples of auditory disabilities include:\n - Deaf (permanent)\n - Ear infection (temporary)\n - On public transport (situational)\n\n### Limited mobility\n\n- Support keyboard navigation, large selectable targets, and correct semantic HTML.\n- Examples of limited mobility include:\n - Cerebral palsy (permanent)\n - Broken wrist (temporary)\n - Crying baby (situational)\n\n### Cognitive disabilities\n\n- Use wording that’s clear and in plain language.\n- Break up big chunks of text using headings and subheadings, bullet points, and small paragraphs.\n- Design experiences that are easy to navigate.\n- Examples of cognitive disabilities include:\n - Dyslexia (permanent)\n - Anxiety (temporary)\n - Busy office (situational)\n\n<SectionMessage title=\"Benefits of accessible apps\">\n\tWhen we consider accessibility and inclusion throughout every part of the design and development\n\tprocess, we create apps that benefit everyone on a team, reach more people, comply with\n\tlegislation, and keep us innovative.\n</SectionMessage>\n\n## Helpful tools (Atlassians only)\n\n<IconCardGroup data={contactUsCards} />",
18
18
  keywords: ['accessibility', 'wcag', 'keyboard', 'aria', 'assistive technology', 'inclusive design', 'usability']
19
19
  }, {
20
- content: "# Border\n\nUse this guidance when choosing borders, dividers, selected indicators, or keyboard focus rings for\nAtlassian UI. Start with the existing ADS component treatment. For custom UI, choose the border's\npurpose before its width and color.\n\nBorders communicate boundaries and state. They do not supply interaction behavior, accessible names,\nselection semantics, or elevation.\n\n## Choose the treatment from its purpose\n\n| Purpose | Width | Color | Application |\n| -------------------------------------------- | ----------------------- | ----------------------- | ------------------------------------------------------------------------------ |\n| Flat grouping or divider | `border.width` | `color.border` | Separate content when whitespace or a surface alone is insufficient. |\n| Neutral boundary requiring stronger contrast | `border.width` | `color.border.bold` | Use when the boundary must be perceivable; check the actual adjacent surfaces. |\n| Form control boundary | `border.width` | `color.border.input` | Prefer the form component's supplied treatment. |\n| Persistent selected indicator | `border.width.selected` | `color.border.selected` | Identify a selected or opened item, such as a tab or list option. |\n| Keyboard focus ring | `border.width.focused` | `color.border.focused` | Use the component's focus treatment or Focusable for custom interactive UI. |\n| Invalid form control | `border.width` | `color.border.danger` | Pair the boundary with the control's error message and invalid semantics. |\n| Disabled element with a border | `border.width` | `color.border.disabled` | Follow the component's disabled appearance and behavior. |\n\nToken values can change. Use token references rather than copying their current pixel, rem, or color\nvalues. Border width, color, style, and radius are separate decisions. Set an appropriate border\nstyle for a custom boundary; width and color alone do not make a CSS border visible.\n\nThe table describes custom treatments, not overrides for ADS components. Preserve an existing valid\ncomponent appearance, including components that use an underline or another indicator instead of an\nenclosing border.\n\n## Preserve component-owned treatments\n\nReuse ADS controls before recreating their states. Read the selected component's guidance before\ncustomizing its border, selected indicator, or focus ring. Avoid wrapping an ADS control in another\nvisible focus ring when it already supplies one.\n\nFor custom interactive elements that need a focus treatment, use the supported Focusable pattern and\nretain the element's keyboard behavior and semantics. Focusable supplies focus styling and renders a\nbutton by default; a custom host element still needs its appropriate semantics and keyboard\nbehavior. It does not implement selection. Retrieve its API before composing it with the host\nelement.\n\nFor Figma work, use the ADS Focus Ring component. Code and design should preserve the same focus\nmeaning without requiring identical implementation mechanics.\n\n## Keep selection and keyboard focus distinct\n\nPair `border.width.selected` with `color.border.selected` for a custom selected indicator. Pair\n`border.width.focused` with `color.border.focused` for a custom focus ring.\n\nSelection can persist after focus moves away. A selected item can also receive keyboard focus: keep\nits selected indicator and show the focus ring independently. Do not replace selection with focus\nstyling, or use a thicker selected border as the only keyboard focus cue.\n\nAn invalid field still needs a visible focus indicator when focused. Preserve the invalid boundary,\nerror message, and focus treatment together rather than choosing one state to hide the other. Hover\nand press should retain relevant selected, invalid, and focus cues. Use the component's state\nbehavior; do not invent tokens by appending `.hovered` or `.pressed` to a border token.\n\nAvoid layout shifts as indicators appear or change width. Follow the component's existing\nimplementation. For custom UI, reserve the necessary space or use a supported indicator that does\nnot change layout; check text wrapping and target dimensions in each state.\n\n## Choose semantic and accent colors deliberately\n\nUse the color token whose documented purpose matches the boundary. Brand, status, and accent colors\nare not interchangeable simply because they look similar in one theme.\n\n- Status boundaries use the relevant semantic border family, such as `color.border.warning`,\n `color.border.success`, or `color.border.information`. Communicate necessary status with text or\n another recognizable cue as well as color.\n- On bold backgrounds, consult `color.border.inverse` and the host component's guidance.\n- For non-status categories or accent surfaces, retrieve the color accents guidance and the\n corresponding accent border token. A subtle accent background may need an accent border when the\n boundary communicates required information.\n- Subtle status border variants are intended for decoration and may not meet the contrast needed for\n a required boundary. Do not substitute them solely to make a meaningful border less prominent.\n\n`color.border` is useful for grouping and separation; it is not a guarantee of sufficient contrast\nfor every required control boundary. Token descriptions guide the choice, while the rendered\nforeground/background pairing determines the result.\n\n## Check the rendered boundary and focus ring\n\nWhere a boundary or state indicator conveys information needed to identify or operate the UI, check\nthe applicable 3:1 non-text contrast requirement against adjacent colors. Decorative dividers have a\ndifferent role; do not turn every separator into a bold border to satisfy a blanket rule.\n\nCheck supported themes and relevant states on their actual host surfaces. Resolve translucent\nbackgrounds over the surface beneath them before calculating contrast. A light-theme screenshot or a\ntoken name alone does not establish dark-theme accessibility.\n\nExercise keyboard focus through the real interaction path. Confirm the ring is visible, is not\nclipped by overflow, and remains distinguishable on selected or invalid elements. Preserve a usable\nfocus indicator when customizing styles; do not remove the outline without a working replacement.\n\nUse whitespace, surface treatment, or a border according to the intended hierarchy. Borders can\nseparate sections within an overlay without adding another shadow. For floating surfaces or scroll\nboundaries, consult elevation guidance rather than treating a border as a complete layering recipe.\n\n## Retrieve only the missing detail\n\nWhen loaded through the ADS skill, follow its retrieval order.\n\nUse the border token reference for widths, the color token reference for border colors, and\ncomponent references for APIs and behavior. Border radius belongs to the shape guidance; do not\ninfer a radius from the border width.\n\nUse the guidance here first. If a detail is missing, use `atlas ads`; use ADS MCP only after a CLI\nerror, an empty result, or a missing capability. For tokens, search by purpose, then confirm the\nexact token:\n\n```sh\natlas ads search \"selected border\" --type token --limit 5 --json\natlas ads token border.width.selected --json\natlas ads token color.border.selected --json\n```\n\nFor MCP fallback, use `ads_search_tokens` for token usage, `ads_search_components` for component\nAPIs, or `ads_get_a11y_guidelines` for accessibility; follow each tool’s exposed schema. Don’t\nrepeat a successful lookup through another route, fetch the full catalog, or construct tokens by\nappending state suffixes. If a detail remains unresolved, label it unverified and state what still\nneeds checking.\n\n## Verify the result\n\nCheck the cases relevant to the task:\n\n- The boundary's purpose justifies its width and color.\n- Selected and focused indicators use their documented token pairings.\n- Focus remains visible on selected and invalid elements, including during hover or press.\n- State changes do not move surrounding content or clip the focus indicator.\n- Meaningful boundaries and state cues remain perceivable on the actual surfaces in supported\n themes.\n- Existing ADS controls retain their built-in behavior and do not acquire duplicate focus rings.\n\nReport token verification separately from rendered and keyboard checks. State which themes and\nstates were checked, and identify unverified behavior without claiming it passed.\n\n## Sources\n\nDesign principles: [ADS border](https://atlassian.design/foundations/border). Exact token names and\npurposes: the ADS border and color token catalogs. Component guidance supplies APIs and interaction\nbehavior; color and color accents guidance supplies semantic pairing and contrast context.",
20
+ content: "# Border\n\nUse this guidance when choosing borders, dividers, selected indicators, or keyboard focus rings for\nAtlassian UI. Start with the existing ADS component treatment. For custom UI, choose the border's\npurpose before its width and color.\n\nBorders communicate boundaries and state. They do not supply interaction behavior, accessible names,\nselection semantics, or elevation.\n\n## Choose the treatment from its purpose\n\n| Purpose | Width | Color | Application |\n| -------------------------------------------- | ----------------------- | ----------------------- | ------------------------------------------------------------------------------ |\n| Flat grouping or divider | `border.width` | `color.border` | Separate content when whitespace or a surface alone is insufficient. |\n| Neutral boundary requiring stronger contrast | `border.width` | `color.border.bold` | Use when the boundary must be perceivable; check the actual adjacent surfaces. |\n| Form control boundary | `border.width` | `color.border.input` | Prefer the form component's supplied treatment. |\n| Persistent selected indicator | `border.width.selected` | `color.border.selected` | Identify a selected or opened item, such as a tab or list option. |\n| Keyboard focus ring | `border.width.focused` | `color.border.focused` | Use the component's focus treatment or Focusable for custom interactive UI. |\n| Invalid form control | `border.width` | `color.border.danger` | Pair the boundary with the control's error message and invalid semantics. |\n| Disabled element with a border | `border.width` | `color.border.disabled` | Follow the component's disabled appearance and behavior. |\n\nToken values can change. Use token references rather than copying their current pixel, rem, or color\nvalues. Border width, color, style, and radius are separate decisions. Set an appropriate border\nstyle for a custom boundary; width and color alone do not make a CSS border visible.\n\nThe table describes custom treatments, not overrides for ADS components. Preserve an existing valid\ncomponent appearance, including components that use an underline or another indicator instead of an\nenclosing border.\n\n## Preserve component-owned treatments\n\nReuse ADS controls before recreating their states. Read the selected component's guidance before\ncustomizing its border, selected indicator, or focus ring. Avoid wrapping an ADS control in another\nvisible focus ring when it already supplies one.\n\nInspect the rendered boundary and focus styles in the host page before declaring the component\ntreatment preserved. Check for consumer and host overrides.\n\nFor custom interactive elements that need a focus treatment, use the supported Focusable pattern and\nretain the element's keyboard behavior and semantics. Focusable supplies focus styling and renders a\nbutton by default; a custom host element still needs its appropriate semantics and keyboard\nbehavior. It does not implement selection. Retrieve its API before composing it with the host\nelement.\n\nFor Figma work, use the ADS Focus Ring component. Code and design should preserve the same focus\nmeaning without requiring identical implementation mechanics.\n\n## Keep selection and keyboard focus distinct\n\nPair `border.width.selected` with `color.border.selected` for a custom selected indicator. Pair\n`border.width.focused` with `color.border.focused` for a custom focus ring.\n\nSelection can persist after focus moves away. A selected item can also receive keyboard focus: keep\nits selected indicator and show the focus ring independently. Do not replace selection with focus\nstyling, or use a thicker selected border as the only keyboard focus cue.\n\nFor drag-and-drop destinations, follow the\n[Pragmatic drag and drop guidance](https://atlassian.design/components/pragmatic-drag-and-drop/design-guidelines/)\nand use its supplied drop-indicator components. A drop indicator communicates placement, rather than\npersistent selection or keyboard focus.\n\nAn invalid field still needs a visible focus indicator when focused. Preserve the invalid boundary,\nerror message, and focus treatment together rather than choosing one state to hide the other. Hover\nand press should retain relevant selected, invalid, and focus cues. Use the component's state\nbehavior; do not invent tokens by appending `.hovered` or `.pressed` to a border token.\n\nAvoid layout shifts as indicators appear or change width. Follow the component's existing\nimplementation. For custom UI, reserve the necessary space or use a supported indicator that does\nnot change layout; check text wrapping and target dimensions in each state.\n\n## Choose semantic and accent colors deliberately\n\nUse the color token whose documented purpose matches the boundary. Brand, status, and accent colors\nare not interchangeable simply because they look similar in one theme.\n\n- Status boundaries use the relevant semantic border family, such as `color.border.warning`,\n `color.border.success`, or `color.border.information`. Communicate necessary status with text or\n another recognizable cue as well as color.\n- On bold backgrounds, consult `color.border.inverse` and the host component's guidance.\n- For non-status categories or accent surfaces, retrieve the color accents guidance and the\n corresponding accent border token. A subtle accent background may need an accent border when the\n boundary communicates required information.\n- Subtle status border variants are intended for decoration and may not meet the contrast needed for\n a required boundary. Do not substitute them solely to make a meaningful border less prominent.\n\n`color.border` is useful for grouping and separation; it is not a guarantee of sufficient contrast\nfor every required control boundary. Token descriptions guide the choice, while the rendered\nforeground/background pairing determines the result.\n\n## Check the rendered boundary and focus ring\n\nWhere a boundary or state indicator conveys information needed to identify or operate the UI, check\nthe applicable 3:1 non-text contrast requirement against adjacent colors. Decorative dividers have a\ndifferent role; do not turn every separator into a bold border to satisfy a blanket rule.\n\nCheck supported themes and relevant states on their actual host surfaces. Resolve translucent\nbackgrounds over the surface beneath them before calculating contrast. A light-theme screenshot or a\ntoken name alone does not establish dark-theme accessibility.\n\nExercise keyboard focus through the real interaction path. Confirm the ring is visible, is not\nclipped by overflow, and remains distinguishable on selected or invalid elements. Preserve a usable\nfocus indicator when customizing styles; do not remove the outline without a working replacement.\n\nUse whitespace, surface treatment, or a border according to the intended hierarchy. Borders can\nseparate sections within an overlay without adding another shadow. For floating surfaces or scroll\nboundaries, consult elevation guidance rather than treating a border as a complete layering recipe.\n\n## Retrieve only the missing detail\n\nWhen loaded through the ADS skill, follow its retrieval order.\n\nUse the border token reference for widths, the color token reference for border colors, and\ncomponent references for APIs and behavior. Border radius belongs to the shape guidance; do not\ninfer a radius from the border width.\n\nUse the guidance here first. If a detail is missing, use `atlas ads`; use ADS MCP only after a CLI\nerror, an empty result, or a missing capability. For tokens, search by purpose, then confirm the\nexact token:\n\n```sh\natlas ads search \"selected border\" --type token --limit 5 --json\natlas ads token border.width.selected --json\natlas ads token color.border.selected --json\n```\n\nFor MCP fallback, use `ads_search_tokens` for token usage, `ads_search_components` for component\nAPIs, or `ads_get_a11y_guidelines` for accessibility; follow each tool’s exposed schema. Don’t\nrepeat a successful lookup through another route, fetch the full catalog, or construct tokens by\nappending state suffixes. If a detail remains unresolved, label it unverified and state what still\nneeds checking.\n\n## Verify the result\n\nCheck the cases relevant to the task:\n\n- The boundary's purpose justifies its width and color.\n- Selected and focused indicators use their documented token pairings.\n- For selectable controls, check selected without focus, focused without selection, and selected with\n keyboard focus separately.\n- Focus remains visible on selected and invalid elements, including during hover or press.\n- State changes do not move surrounding content or clip the focus indicator.\n- Meaningful boundaries and state cues remain perceivable on the actual surfaces in supported\n themes.\n- Existing ADS controls retain their built-in behavior and do not acquire duplicate focus rings.\n\nReport token verification separately from rendered and keyboard checks. State which themes and\nstates were checked, and identify unverified behavior without claiming it passed.\n\n## Sources\n\nDesign principles: [ADS border](https://atlassian.design/foundations/border). Exact token names and\npurposes: the ADS border and color token catalogs. Component guidance supplies APIs and interaction\nbehavior; color and color accents guidance supplies semantic pairing and contrast context.",
21
21
  name: 'Border',
22
22
  keywords: ['border', 'dividers', 'selected indicators', 'focus rings', 'width and color pairing', 'input boundaries', 'contrast', 'stroke', 'outline', 'design tokens', 'visual hierarchy']
23
23
  }, {