@atlaskit/ads-mcp 1.11.7 → 1.11.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.
- package/CHANGELOG.md +8 -0
- package/dist/cjs/tools/get-guidelines/guidelines-structured-content.codegen.js +4 -3
- package/dist/es2019/tools/get-guidelines/guidelines-structured-content.codegen.js +4 -3
- package/dist/esm/tools/get-guidelines/guidelines-structured-content.codegen.js +4 -3
- package/dist/types/tools/get-guidelines/guidelines-structured-content.codegen.d.ts +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# @atlaskit/ads-mcp
|
|
2
2
|
|
|
3
|
+
## 1.11.8
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [`317d9ef9c4e11`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/317d9ef9c4e11) -
|
|
8
|
+
Use authored border guidance for ADS foundation queries, including width and color pairings,
|
|
9
|
+
component-owned focus treatments, and verification guidance.
|
|
10
|
+
|
|
3
11
|
## 1.11.7
|
|
4
12
|
|
|
5
13
|
### Patch Changes
|
|
@@ -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::
|
|
12
|
+
* @codegen <<SignedSource::ce6d7e95afe22e87657ba2f992363111>>
|
|
13
13
|
* @codegenCommand yarn build structured-docs
|
|
14
14
|
*/
|
|
15
15
|
|
|
@@ -17,8 +17,9 @@ 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: '
|
|
21
|
-
|
|
20
|
+
content: "# Border\n\nUse this guidance when choosing borders, dividers, selected indicators, or keyboard focus rings\nfor Atlassian UI. Start with the existing ADS component treatment. For custom UI, choose the\nborder's purpose before its width and color.\n\nBorders communicate boundaries and state. They do not supply interaction behavior, accessible\nnames, selection 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\ncolor values. Border width, color, style, and radius are separate decisions. Set an appropriate\nborder style 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\nan enclosing 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\nand retain the element's keyboard behavior and semantics. Focusable supplies focus styling and\nrenders a button by default; a custom host element still needs its appropriate semantics and\nkeyboard behavior. It does not implement selection. Retrieve its API before composing it with\nthe host element.\n\nFor Figma work, use the ADS Focus Ring component. Code and design should preserve the same\nfocus meaning 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.\nPair `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:\nkeep its selected indicator and show the focus ring independently. Do not replace selection with\nfocus styling, 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.\nHover and press should retain relevant selected, invalid, and focus cues. Use the component's\nstate behavior; 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\n the boundary communicates required information.\n- Subtle status border variants are intended for decoration and may not meet the contrast needed\n for 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,\ncheck the applicable 3:1 non-text contrast requirement against adjacent colors. Decorative dividers\nhave a different 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\nor a token 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. Use the border token reference for\nwidths, the color token reference for border colors, and component references for APIs and behavior.\nBorder radius belongs to the shape guidance; do not infer a radius from the border width.\n\nFor CLI lookup, search by purpose before inspecting an exact token when the choice is unknown:\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\nWhen returned through MCP without local references, use the available ADS tools:\n`ads_search_tokens` for token usage, `ads_search_components` for component discovery, and\n`ads_get_a11y_guidelines` for focus and interaction accessibility. Use each tool's exposed input\nschema. Retrieve the missing detail without fetching the full catalog or repeating a successful\nlookup through another route.\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 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
|
+
name: 'Border',
|
|
22
|
+
keywords: ['border', 'dividers', 'selected indicators', 'focus rings', 'width and color pairing', 'input boundaries', 'contrast', 'stroke', 'outline', 'design tokens', 'visual hierarchy']
|
|
22
23
|
}, {
|
|
23
24
|
content: "# Color\n\nUse color tokens to communicate intent, hierarchy, and interaction in Atlassian UI. Start with the\nexisting ADS component treatment; use these choices when styling custom UI or reviewing a token\nchoice.\n\n## Choose the token family\n\n1. Identify what the color communicates. Use a semantic role for status, validation, actions, or\n discovery. Use an accent when the hue identifies a category and could change without changing its\n meaning. See the Color accents guidance for hue and pairing choices.\n2. Choose the background emphasis that fits the intended hierarchy.\n3. Pair it with the text, icon, and border tokens for that role and emphasis.\n4. For interactive UI, apply the state to the element that owns the interaction. Preserve separate\n cues for persistent selection and keyboard focus.\n\nApply tokens with `token('color...')` from `@atlaskit/tokens`. Tokens resolve for light and dark\nthemes, so use their semantic names instead of copying palette values or hardcoded colors.\n\n## Read token names\n\nMost tokens follow `color.[property].[role].[emphasis].[state]`:\n\n- **Property** describes where the color is applied: `background`, `text`, `icon`, or `border`.\n- **Role** describes its intent: `brand`, `danger`, `warning`, `success`, `information`,\n `discovery`, `neutral`, `selected`, `focused`, `input`, or `accent.[hue]`.\n- **Emphasis** describes contrast against the default surface: `bold`, `bolder`, `boldest`,\n `subtle`, `subtler`, or `subtlest`.\n- **State** describes an interaction state such as `hovered` or `pressed`.\n\nAccent tokens place the hue after the role, for example `color.background.accent.blue.subtlest`.\nLook up exceptions such as `color.link`, `color.blanket`, `color.skeleton`, and `color.chart.*` in\nthe token catalog rather than extending the pattern.\n\n## Choose a semantic role\n\n| Role | Choose it for | Example use |\n| :------------- | :------------------------------------------------ | :---------------------------------- |\n| `danger` | Destructive actions, errors, or critical failures | Error message or destructive action |\n| `warning` | Caution, risk, or something that needs attention | Risk notice |\n| `success` | A successful, completed, or valid state | Completion message |\n| `information` | A passive informational message | Informational notice |\n| `brand` | Primary actions or product identity | Primary action |\n| `discovery` | Discovery, AI, or a new feature | New feature callout |\n| `neutral` | Base surfaces and neutral layout | Page or control surface |\n| `input` | Form field backgrounds and boundaries | Text field |\n| `selected` | A persistent current choice | Selected row or option |\n| `focused` | Keyboard focus indicator; border only | Focus ring |\n| `accent.[hue]` | Categories and labels whose hue is optional | User-chosen tag |\n\nKeep fixed meaning in the semantic role. For example, an error uses `danger` and a successful state\nuses `success`; an accent red or green is for a category whose color does not carry that meaning.\n\n## Pair semantic backgrounds and foregrounds\n\n| Background | Text and icon |\n| :------------------------------------------------------ | :------------------------------------------------------------ |\n| Semantic `*.bold` or `*.bolder` | `color.text.inverse` and `color.icon.inverse` |\n| `color.background.warning.bold` | `color.text.warning.inverse` and `color.icon.warning.inverse` |\n| Subtle, subtler, subtlest, or default semantic surfaces | Matching role text and icon, such as `color.text.danger` |\n\nUse the warning-specific inverse pair shown above on a bold warning background. Accent foreground\npairings are in the Color accents guidance.\n\n```tsx\n// Error banner\nbackgroundColor: token('color.background.danger.bold'),\ncolor: token('color.text.inverse'),\n\n// Category label whose hue carries no status meaning\nbackgroundColor: token('color.background.accent.red.bolder'),\ncolor: token('color.text.inverse'),\n```\n\n## Apply state to the interactive element\n\n### Form fields\n\nUse `color.background.input` for the field background, with `color.background.input.hovered` and\n`color.background.input.pressed` for those states. Use `color.border.input` for the field boundary.\nStart with the ADS form component’s treatment when one owns the control.\n\n### Selection and focus\n\nUse `color.background.selected`, `color.text.selected`, `color.icon.selected`, or\n`color.border.selected` for a persistent choice. Use `color.border.focused` for keyboard focus. When\nan element is both selected and focused, keep the selected treatment and add the focus indicator.\nDon’t use link, brand, or focused tokens to communicate selection. Pair selection color with another\ncue, such as a checkmark, underline, border, or shape change, so selection remains clear without\ncolor alone.\n\nApply `hovered` and `pressed` variants to the currently interactive element. Keep a selected item\nrecognizable during those temporary states. Icons do not have dedicated hovered or pressed color\ntokens; use a subtle neutral background such as `color.background.neutral.subtle.hovered` or\n`color.background.neutral.subtle.pressed` when the icon’s control needs a surface response.\n\n## Check the rendered result\n\nInspect the foreground, meaningful borders, and state changes against the final visible background\nin the themes the experience supports. For translucent colors, include the underlying surface when\nchecking contrast. Use `color.chart.*` for chart marks and product UI tokens for axes, labels, and\ngridlines.\n\n## Look up exact tokens\n\nSearch the ADS token registry when an identifier or pairing is uncertain:\n\n```bash\natlas ads search \"danger background\" --type token\natlas ads token color.background.danger.bold --json\n```\n\nIf the Atlas plugin is unavailable, use\n`npx @atlaskit/ads-cli search \"danger background\" --type token`.",
|
|
24
25
|
name: 'Color',
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Structured content for authored agent guidelines and design-system-docs foundations content.
|
|
5
5
|
*
|
|
6
|
-
* @codegen <<SignedSource::
|
|
6
|
+
* @codegen <<SignedSource::ce6d7e95afe22e87657ba2f992363111>>
|
|
7
7
|
* @codegenCommand yarn build structured-docs
|
|
8
8
|
*/
|
|
9
9
|
|
|
@@ -11,8 +11,9 @@ export const guidelinesStructuredContent = [{
|
|
|
11
11
|
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} />",
|
|
12
12
|
keywords: ['accessibility', 'wcag', 'keyboard', 'aria', 'assistive technology', 'inclusive design', 'usability']
|
|
13
13
|
}, {
|
|
14
|
-
content: '
|
|
15
|
-
|
|
14
|
+
content: "# Border\n\nUse this guidance when choosing borders, dividers, selected indicators, or keyboard focus rings\nfor Atlassian UI. Start with the existing ADS component treatment. For custom UI, choose the\nborder's purpose before its width and color.\n\nBorders communicate boundaries and state. They do not supply interaction behavior, accessible\nnames, selection 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\ncolor values. Border width, color, style, and radius are separate decisions. Set an appropriate\nborder style 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\nan enclosing 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\nand retain the element's keyboard behavior and semantics. Focusable supplies focus styling and\nrenders a button by default; a custom host element still needs its appropriate semantics and\nkeyboard behavior. It does not implement selection. Retrieve its API before composing it with\nthe host element.\n\nFor Figma work, use the ADS Focus Ring component. Code and design should preserve the same\nfocus meaning 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.\nPair `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:\nkeep its selected indicator and show the focus ring independently. Do not replace selection with\nfocus styling, 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.\nHover and press should retain relevant selected, invalid, and focus cues. Use the component's\nstate behavior; 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\n the boundary communicates required information.\n- Subtle status border variants are intended for decoration and may not meet the contrast needed\n for 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,\ncheck the applicable 3:1 non-text contrast requirement against adjacent colors. Decorative dividers\nhave a different 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\nor a token 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. Use the border token reference for\nwidths, the color token reference for border colors, and component references for APIs and behavior.\nBorder radius belongs to the shape guidance; do not infer a radius from the border width.\n\nFor CLI lookup, search by purpose before inspecting an exact token when the choice is unknown:\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\nWhen returned through MCP without local references, use the available ADS tools:\n`ads_search_tokens` for token usage, `ads_search_components` for component discovery, and\n`ads_get_a11y_guidelines` for focus and interaction accessibility. Use each tool's exposed input\nschema. Retrieve the missing detail without fetching the full catalog or repeating a successful\nlookup through another route.\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 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.",
|
|
15
|
+
name: 'Border',
|
|
16
|
+
keywords: ['border', 'dividers', 'selected indicators', 'focus rings', 'width and color pairing', 'input boundaries', 'contrast', 'stroke', 'outline', 'design tokens', 'visual hierarchy']
|
|
16
17
|
}, {
|
|
17
18
|
content: "# Color\n\nUse color tokens to communicate intent, hierarchy, and interaction in Atlassian UI. Start with the\nexisting ADS component treatment; use these choices when styling custom UI or reviewing a token\nchoice.\n\n## Choose the token family\n\n1. Identify what the color communicates. Use a semantic role for status, validation, actions, or\n discovery. Use an accent when the hue identifies a category and could change without changing its\n meaning. See the Color accents guidance for hue and pairing choices.\n2. Choose the background emphasis that fits the intended hierarchy.\n3. Pair it with the text, icon, and border tokens for that role and emphasis.\n4. For interactive UI, apply the state to the element that owns the interaction. Preserve separate\n cues for persistent selection and keyboard focus.\n\nApply tokens with `token('color...')` from `@atlaskit/tokens`. Tokens resolve for light and dark\nthemes, so use their semantic names instead of copying palette values or hardcoded colors.\n\n## Read token names\n\nMost tokens follow `color.[property].[role].[emphasis].[state]`:\n\n- **Property** describes where the color is applied: `background`, `text`, `icon`, or `border`.\n- **Role** describes its intent: `brand`, `danger`, `warning`, `success`, `information`,\n `discovery`, `neutral`, `selected`, `focused`, `input`, or `accent.[hue]`.\n- **Emphasis** describes contrast against the default surface: `bold`, `bolder`, `boldest`,\n `subtle`, `subtler`, or `subtlest`.\n- **State** describes an interaction state such as `hovered` or `pressed`.\n\nAccent tokens place the hue after the role, for example `color.background.accent.blue.subtlest`.\nLook up exceptions such as `color.link`, `color.blanket`, `color.skeleton`, and `color.chart.*` in\nthe token catalog rather than extending the pattern.\n\n## Choose a semantic role\n\n| Role | Choose it for | Example use |\n| :------------- | :------------------------------------------------ | :---------------------------------- |\n| `danger` | Destructive actions, errors, or critical failures | Error message or destructive action |\n| `warning` | Caution, risk, or something that needs attention | Risk notice |\n| `success` | A successful, completed, or valid state | Completion message |\n| `information` | A passive informational message | Informational notice |\n| `brand` | Primary actions or product identity | Primary action |\n| `discovery` | Discovery, AI, or a new feature | New feature callout |\n| `neutral` | Base surfaces and neutral layout | Page or control surface |\n| `input` | Form field backgrounds and boundaries | Text field |\n| `selected` | A persistent current choice | Selected row or option |\n| `focused` | Keyboard focus indicator; border only | Focus ring |\n| `accent.[hue]` | Categories and labels whose hue is optional | User-chosen tag |\n\nKeep fixed meaning in the semantic role. For example, an error uses `danger` and a successful state\nuses `success`; an accent red or green is for a category whose color does not carry that meaning.\n\n## Pair semantic backgrounds and foregrounds\n\n| Background | Text and icon |\n| :------------------------------------------------------ | :------------------------------------------------------------ |\n| Semantic `*.bold` or `*.bolder` | `color.text.inverse` and `color.icon.inverse` |\n| `color.background.warning.bold` | `color.text.warning.inverse` and `color.icon.warning.inverse` |\n| Subtle, subtler, subtlest, or default semantic surfaces | Matching role text and icon, such as `color.text.danger` |\n\nUse the warning-specific inverse pair shown above on a bold warning background. Accent foreground\npairings are in the Color accents guidance.\n\n```tsx\n// Error banner\nbackgroundColor: token('color.background.danger.bold'),\ncolor: token('color.text.inverse'),\n\n// Category label whose hue carries no status meaning\nbackgroundColor: token('color.background.accent.red.bolder'),\ncolor: token('color.text.inverse'),\n```\n\n## Apply state to the interactive element\n\n### Form fields\n\nUse `color.background.input` for the field background, with `color.background.input.hovered` and\n`color.background.input.pressed` for those states. Use `color.border.input` for the field boundary.\nStart with the ADS form component’s treatment when one owns the control.\n\n### Selection and focus\n\nUse `color.background.selected`, `color.text.selected`, `color.icon.selected`, or\n`color.border.selected` for a persistent choice. Use `color.border.focused` for keyboard focus. When\nan element is both selected and focused, keep the selected treatment and add the focus indicator.\nDon’t use link, brand, or focused tokens to communicate selection. Pair selection color with another\ncue, such as a checkmark, underline, border, or shape change, so selection remains clear without\ncolor alone.\n\nApply `hovered` and `pressed` variants to the currently interactive element. Keep a selected item\nrecognizable during those temporary states. Icons do not have dedicated hovered or pressed color\ntokens; use a subtle neutral background such as `color.background.neutral.subtle.hovered` or\n`color.background.neutral.subtle.pressed` when the icon’s control needs a surface response.\n\n## Check the rendered result\n\nInspect the foreground, meaningful borders, and state changes against the final visible background\nin the themes the experience supports. For translucent colors, include the underlying surface when\nchecking contrast. Use `color.chart.*` for chart marks and product UI tokens for axes, labels, and\ngridlines.\n\n## Look up exact tokens\n\nSearch the ADS token registry when an identifier or pairing is uncertain:\n\n```bash\natlas ads search \"danger background\" --type token\natlas ads token color.background.danger.bold --json\n```\n\nIf the Atlas plugin is unavailable, use\n`npx @atlaskit/ads-cli search \"danger background\" --type token`.",
|
|
18
19
|
name: 'Color',
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Structured content for authored agent guidelines and design-system-docs foundations content.
|
|
5
5
|
*
|
|
6
|
-
* @codegen <<SignedSource::
|
|
6
|
+
* @codegen <<SignedSource::ce6d7e95afe22e87657ba2f992363111>>
|
|
7
7
|
* @codegenCommand yarn build structured-docs
|
|
8
8
|
*/
|
|
9
9
|
|
|
@@ -11,8 +11,9 @@ export var guidelinesStructuredContent = [{
|
|
|
11
11
|
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} />",
|
|
12
12
|
keywords: ['accessibility', 'wcag', 'keyboard', 'aria', 'assistive technology', 'inclusive design', 'usability']
|
|
13
13
|
}, {
|
|
14
|
-
content: '
|
|
15
|
-
|
|
14
|
+
content: "# Border\n\nUse this guidance when choosing borders, dividers, selected indicators, or keyboard focus rings\nfor Atlassian UI. Start with the existing ADS component treatment. For custom UI, choose the\nborder's purpose before its width and color.\n\nBorders communicate boundaries and state. They do not supply interaction behavior, accessible\nnames, selection 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\ncolor values. Border width, color, style, and radius are separate decisions. Set an appropriate\nborder style 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\nan enclosing 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\nand retain the element's keyboard behavior and semantics. Focusable supplies focus styling and\nrenders a button by default; a custom host element still needs its appropriate semantics and\nkeyboard behavior. It does not implement selection. Retrieve its API before composing it with\nthe host element.\n\nFor Figma work, use the ADS Focus Ring component. Code and design should preserve the same\nfocus meaning 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.\nPair `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:\nkeep its selected indicator and show the focus ring independently. Do not replace selection with\nfocus styling, 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.\nHover and press should retain relevant selected, invalid, and focus cues. Use the component's\nstate behavior; 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\n the boundary communicates required information.\n- Subtle status border variants are intended for decoration and may not meet the contrast needed\n for 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,\ncheck the applicable 3:1 non-text contrast requirement against adjacent colors. Decorative dividers\nhave a different 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\nor a token 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. Use the border token reference for\nwidths, the color token reference for border colors, and component references for APIs and behavior.\nBorder radius belongs to the shape guidance; do not infer a radius from the border width.\n\nFor CLI lookup, search by purpose before inspecting an exact token when the choice is unknown:\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\nWhen returned through MCP without local references, use the available ADS tools:\n`ads_search_tokens` for token usage, `ads_search_components` for component discovery, and\n`ads_get_a11y_guidelines` for focus and interaction accessibility. Use each tool's exposed input\nschema. Retrieve the missing detail without fetching the full catalog or repeating a successful\nlookup through another route.\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 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.",
|
|
15
|
+
name: 'Border',
|
|
16
|
+
keywords: ['border', 'dividers', 'selected indicators', 'focus rings', 'width and color pairing', 'input boundaries', 'contrast', 'stroke', 'outline', 'design tokens', 'visual hierarchy']
|
|
16
17
|
}, {
|
|
17
18
|
content: "# Color\n\nUse color tokens to communicate intent, hierarchy, and interaction in Atlassian UI. Start with the\nexisting ADS component treatment; use these choices when styling custom UI or reviewing a token\nchoice.\n\n## Choose the token family\n\n1. Identify what the color communicates. Use a semantic role for status, validation, actions, or\n discovery. Use an accent when the hue identifies a category and could change without changing its\n meaning. See the Color accents guidance for hue and pairing choices.\n2. Choose the background emphasis that fits the intended hierarchy.\n3. Pair it with the text, icon, and border tokens for that role and emphasis.\n4. For interactive UI, apply the state to the element that owns the interaction. Preserve separate\n cues for persistent selection and keyboard focus.\n\nApply tokens with `token('color...')` from `@atlaskit/tokens`. Tokens resolve for light and dark\nthemes, so use their semantic names instead of copying palette values or hardcoded colors.\n\n## Read token names\n\nMost tokens follow `color.[property].[role].[emphasis].[state]`:\n\n- **Property** describes where the color is applied: `background`, `text`, `icon`, or `border`.\n- **Role** describes its intent: `brand`, `danger`, `warning`, `success`, `information`,\n `discovery`, `neutral`, `selected`, `focused`, `input`, or `accent.[hue]`.\n- **Emphasis** describes contrast against the default surface: `bold`, `bolder`, `boldest`,\n `subtle`, `subtler`, or `subtlest`.\n- **State** describes an interaction state such as `hovered` or `pressed`.\n\nAccent tokens place the hue after the role, for example `color.background.accent.blue.subtlest`.\nLook up exceptions such as `color.link`, `color.blanket`, `color.skeleton`, and `color.chart.*` in\nthe token catalog rather than extending the pattern.\n\n## Choose a semantic role\n\n| Role | Choose it for | Example use |\n| :------------- | :------------------------------------------------ | :---------------------------------- |\n| `danger` | Destructive actions, errors, or critical failures | Error message or destructive action |\n| `warning` | Caution, risk, or something that needs attention | Risk notice |\n| `success` | A successful, completed, or valid state | Completion message |\n| `information` | A passive informational message | Informational notice |\n| `brand` | Primary actions or product identity | Primary action |\n| `discovery` | Discovery, AI, or a new feature | New feature callout |\n| `neutral` | Base surfaces and neutral layout | Page or control surface |\n| `input` | Form field backgrounds and boundaries | Text field |\n| `selected` | A persistent current choice | Selected row or option |\n| `focused` | Keyboard focus indicator; border only | Focus ring |\n| `accent.[hue]` | Categories and labels whose hue is optional | User-chosen tag |\n\nKeep fixed meaning in the semantic role. For example, an error uses `danger` and a successful state\nuses `success`; an accent red or green is for a category whose color does not carry that meaning.\n\n## Pair semantic backgrounds and foregrounds\n\n| Background | Text and icon |\n| :------------------------------------------------------ | :------------------------------------------------------------ |\n| Semantic `*.bold` or `*.bolder` | `color.text.inverse` and `color.icon.inverse` |\n| `color.background.warning.bold` | `color.text.warning.inverse` and `color.icon.warning.inverse` |\n| Subtle, subtler, subtlest, or default semantic surfaces | Matching role text and icon, such as `color.text.danger` |\n\nUse the warning-specific inverse pair shown above on a bold warning background. Accent foreground\npairings are in the Color accents guidance.\n\n```tsx\n// Error banner\nbackgroundColor: token('color.background.danger.bold'),\ncolor: token('color.text.inverse'),\n\n// Category label whose hue carries no status meaning\nbackgroundColor: token('color.background.accent.red.bolder'),\ncolor: token('color.text.inverse'),\n```\n\n## Apply state to the interactive element\n\n### Form fields\n\nUse `color.background.input` for the field background, with `color.background.input.hovered` and\n`color.background.input.pressed` for those states. Use `color.border.input` for the field boundary.\nStart with the ADS form component’s treatment when one owns the control.\n\n### Selection and focus\n\nUse `color.background.selected`, `color.text.selected`, `color.icon.selected`, or\n`color.border.selected` for a persistent choice. Use `color.border.focused` for keyboard focus. When\nan element is both selected and focused, keep the selected treatment and add the focus indicator.\nDon’t use link, brand, or focused tokens to communicate selection. Pair selection color with another\ncue, such as a checkmark, underline, border, or shape change, so selection remains clear without\ncolor alone.\n\nApply `hovered` and `pressed` variants to the currently interactive element. Keep a selected item\nrecognizable during those temporary states. Icons do not have dedicated hovered or pressed color\ntokens; use a subtle neutral background such as `color.background.neutral.subtle.hovered` or\n`color.background.neutral.subtle.pressed` when the icon’s control needs a surface response.\n\n## Check the rendered result\n\nInspect the foreground, meaningful borders, and state changes against the final visible background\nin the themes the experience supports. For translucent colors, include the underlying surface when\nchecking contrast. Use `color.chart.*` for chart marks and product UI tokens for axes, labels, and\ngridlines.\n\n## Look up exact tokens\n\nSearch the ADS token registry when an identifier or pairing is uncertain:\n\n```bash\natlas ads search \"danger background\" --type token\natlas ads token color.background.danger.bold --json\n```\n\nIf the Atlas plugin is unavailable, use\n`npx @atlaskit/ads-cli search \"danger background\" --type token`.",
|
|
18
19
|
name: 'Color',
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Structured content for authored agent guidelines and design-system-docs foundations content.
|
|
5
5
|
*
|
|
6
|
-
* @codegen <<SignedSource::
|
|
6
|
+
* @codegen <<SignedSource::ce6d7e95afe22e87657ba2f992363111>>
|
|
7
7
|
* @codegenCommand yarn build structured-docs
|
|
8
8
|
*/
|
|
9
9
|
export interface GuidelineStructuredContent {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atlaskit/ads-mcp",
|
|
3
|
-
"version": "1.11.
|
|
3
|
+
"version": "1.11.8",
|
|
4
4
|
"description": "The official Atlassian Design System MCP server to develop apps and user interfaces matching the Atlassian style.",
|
|
5
5
|
"author": "Atlassian Pty Ltd",
|
|
6
6
|
"license": "Apache-2.0",
|