@atlaskit/ads-mcp 1.11.8 → 1.11.10
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 +15 -0
- package/dist/cjs/tools/get-all-components/components.codegen.js +2 -2
- package/dist/cjs/tools/get-atlaskit-components/atlaskit-components.codegen.js +2 -2
- package/dist/cjs/tools/get-atlaskit-hooks/atlaskit-hooks.codegen.js +6 -6
- package/dist/cjs/tools/get-atlaskit-utilities/atlaskit-utilities.codegen.js +2 -2
- package/dist/cjs/tools/get-guidelines/guidelines-structured-content.codegen.js +4 -3
- package/dist/es2019/tools/get-all-components/components.codegen.js +2 -2
- package/dist/es2019/tools/get-atlaskit-components/atlaskit-components.codegen.js +2 -2
- package/dist/es2019/tools/get-atlaskit-hooks/atlaskit-hooks.codegen.js +6 -6
- package/dist/es2019/tools/get-atlaskit-utilities/atlaskit-utilities.codegen.js +2 -2
- package/dist/es2019/tools/get-guidelines/guidelines-structured-content.codegen.js +4 -3
- package/dist/esm/tools/get-all-components/components.codegen.js +2 -2
- package/dist/esm/tools/get-atlaskit-components/atlaskit-components.codegen.js +2 -2
- package/dist/esm/tools/get-atlaskit-hooks/atlaskit-hooks.codegen.js +6 -6
- package/dist/esm/tools/get-atlaskit-utilities/atlaskit-utilities.codegen.js +2 -2
- package/dist/esm/tools/get-guidelines/guidelines-structured-content.codegen.js +4 -3
- package/dist/types/tools/get-all-components/components.codegen.d.ts +1 -1
- package/dist/types/tools/get-atlaskit-components/atlaskit-components.codegen.d.ts +1 -1
- package/dist/types/tools/get-atlaskit-hooks/atlaskit-hooks.codegen.d.ts +1 -1
- package/dist/types/tools/get-atlaskit-utilities/atlaskit-utilities.codegen.d.ts +1 -1
- package/dist/types/tools/get-guidelines/guidelines-structured-content.codegen.d.ts +1 -1
- package/package.json +1 -1
|
@@ -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::d37366d3a7d35067f9080be0dfa1463f>>
|
|
7
7
|
* @codegenCommand yarn build structured-docs
|
|
8
8
|
*/
|
|
9
9
|
|
|
@@ -11,7 +11,7 @@ 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: "# Border\n\nUse this guidance when choosing borders, dividers, selected indicators, or keyboard focus rings\
|
|
14
|
+
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.",
|
|
15
15
|
name: 'Border',
|
|
16
16
|
keywords: ['border', 'dividers', 'selected indicators', 'focus rings', 'width and color pairing', 'input boundaries', 'contrast', 'stroke', 'outline', 'design tokens', 'visual hierarchy']
|
|
17
17
|
}, {
|
|
@@ -78,7 +78,8 @@ export const guidelinesStructuredContent = [{
|
|
|
78
78
|
content: 'import {\n\tTypographyHeadingTable,\n\tTypographyBodyTable,\n\tTypographyMetricTable,\n\tTypographyCodeTable,\n} from \'@af/design-system-docs-ui\';\n\n\n\nimport {\n\tAtlassianLogoCard,\n\tAttributionCards,\n\tPropertyCards,\n\tAppCards,\n} from \'./_logo-asset-cards.partial\';\n\n\n\n\n\n\n\n\n\n<SectionMessage title="Download logos" appearance="information">\n\t<Stack space="space.100">\n\t\t<Text>\n\t\t\tThe full set of app (product) logos are available in{\' \'}\n\t\t\t<Link href="https://orangedam.atlassian.com/">Atlassian Mosaic</Link>.\n\t\t</Text>\n\t\t<Text>\n\t\t\tLogos used to represent third-party integrations are available in{\' \'}\n\t\t\t<Link href="https://atlaskit.stg.atlassian.com/packages/design-system-experimentation/logo-third-party">\n\t\t\t\tAtlaskit staging (Atlassians only)\n\t\t\t</Link>\n\t\t\t.\n\t\t</Text>\n\t</Stack>\n</SectionMessage>\n\nThis page includes downloadable logo files for use in marketing contexts as well as specific usage\nguidance for app or marketing contexts.\n\nIf you want to add logos to app (product) experiences, use the\n[logo component](https://atlassian.design/components/logo/examples).\n\n## Download the logos\n\nEach downloadable file includes variations of color and layout in approved formats and the below\nelements combined together:\n\n- logomarks – the icon portion of a logo\n- wordmarks – the name of the app (product) or property\n- straplines or other secondary text.\n\nAssets for isolated logomarks are also included.\n\n\n\n### Our iconic Atlassian logo\n\nOur iconic company logo.\n\nInclude `Atlassian` as the alt-text for the logo in digital experiences.\n\n<AtlassianLogoCard />\n\n#### Atlassian app strapline\n\nThe Atlassian logomark and wordmark can be coupled with a list of app (product) names under it.\nFollow the below guidance when using logos that contain straplines:\n\n- Always centre the app names under the logo and don’t scale the logo below 280px wide.\n- Write Atlassian and the app name in the alt-text in digital experiences.\n\n\n\n### Attribution logos\n\nThe attribution logos are a type of lockup that combine app (product) or property logomarks with the\nAtlassian strapline.\n\nThey create consistency in our portfolio, and help customers connect them with our overall Atlassian\nbrand. Follow the below guidance when using attribution logos:\n\n- Only use attribution logos when the Atlassian context is not clear. For example, in\n advertisements, videos, and white papers. You don’t need to use them on Atlassian properties like\n [www.atlassian.com](https://www.atlassian.com) or in app (product) user interfaces.\n- Never compose your own attribution logos or deconstruct the official assets.\n- Write the name of the app (product)/property and Atlassian in the alt-text for in digital\n experiences.\n\n<AttributionCards />\n\n### Property logos\n\nThe Atlassian program and property logos are a lockup of the Atlassian logomark and wordmark and the\nname in Charlie Sans. Follow the below guidance when using property logos:\n\n- On a white background, the program name is rendered in neutral with the logo in primary blue. On\n darker backgrounds, both program and logo are white.\n- Write `Atlassian` and the name of the property as the alt-text in digital experiences.\n\n<PropertyCards />\n\n### App (product) logos\n\nWith the Atlassian System of Work and collections framework our primary products, secondary products\nand plaftform features are now referred to as apps.\n\nWe’ve updated our logos to reflect this change, using marks that symbolize functionality, contained\nin a tile. An app’s glyph is chosen based on the apps functionality; its tile color refers to its\ncollection.\n\nThe logomarks are contained by a tile shape, colored with their associated collection. Follow the\nbelow guidance when using App (product) logos:\n\n- Use when the Atlassian context is clear.\n- If you need to connect the app to Atlassian, use an attribution logo instead. For example, in a\n video or advertisement.\n- Write the name of the apps in the alt-text in digital experiences.\n\nAssets include both isolated logomarks and lockups with wordmarks.\n\n<AppCards />\n\n#### Logomarks\n\nA logomark is a symbol or icon shown without the app (product)/property name or brand workmark. For\nan app (product), this refers to the tile. Follow the below guidance when using logomarks:\n\n- If you’re including the logomark in product experiences, use the\n [icon](https://atlassian.design/components/logo/examples#icon) variant of the logo component.\n- Only use logomarks on their own when the context is very clear and where possible pair with\n descriptive text.\n- Write `Atlassian` or the app/property name in the alt-text in digital experiences.\n\n\n\nLogomarks are paired with native text in top navigations.\n\n\n\nLogomarks are suitable when rendering the app name natively in its environment is more legible and\nuser-friendly.\n\n\n\nLogomarks can be used when environmental restrictions do not allow for proper clearance guidelines\nto be followed for full logos.\n\n#### Logomark shape and size\n\nThe [logo](https://atlassian.design/components/logo) component comes in specific sizes and the\nlogomark has a pre-defined radius. These should not be altered.\n\nThe exception to this is when appearing on external sources such as Apple mobile apps and Google\nMarketplace where specific container shapes need to be used.\n\nLogomarks should never be nested inside additional containers.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: tileRadiusDo, alt: \'\' }}>\n\t\tUse the default radius values that are applied to the backgrounds of app logo icons.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: tileRadiusDont, alt: \'\' }}>\n\t\tDon’t adjust the radius values of the backgrounds of product logo icons.\n\t</DoDont>\n\t<DoDont type="do" image={{ url: containersDo, alt: \'\' }}>\n\t\tAllow breathing room around product logo icons.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: containersDont, alt: \'\' }}>\n\t\tDon’t add unnecessary containers around app logo icons.\n\t</DoDont>\n</DoDontGrid>\n\n### Aligning logos\n\n#### Align logomarks with other elements\n\n- Middle align with the logo mark when the copy is less than the height of the container.\n- Top-align or stack below with center-alignment if it’s taller than the container.\n\n\n\n#### Aligning app (product) logos\n\nWhere app (product) logos are arranged in a vertical or horizontal list, use the height or weight of\nthe logomark portion to align.\n\n \n\n## Logo clearance\n\nWhen displaying logos outside of an app UI, surround them with clear space free of type, graphics,\nand other elements that might cause visual clutter.\n\n#### Ideal clearance — Atlassian logo\n\n \n\n#### Minimum clearance — Atlassian logo\n\nUse the capital "A" of the Atlassian wordmark to define the minimum clearance around the logo.\n\n\n\n#### Ideal clearance — app (product) logo\n\n\n\n#### Minimum clearance — app (product) logo\n\nUse the height and width of the logo wordmark to find the minimum clearance around the logo.\n\n\n\n## Color options\n\nLogos are available in three color options to suit different colored environments – Brand, inverse\nand neutral.\n\n\n\nDon’t edit or place logos in ways that reduce the clarity and legibility of the image.\n\n<DoDontGrid>\n\t<DoDont type="dont" image={{ url: colorDont, alt: \'\' }}>\n\t\tDon’t use unapproved color combinations.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: shadowDont, alt: \'\' }}>\n\t\tDon’t use a drop shadow.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: legibilityDont, alt: \'\' }}>\n\t\tDon’t use the logo on top of complex backgrounds.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: outlineDont, alt: \'\' }}>\n\t\tDon’t outline the logo.\n\t</DoDont>\n</DoDontGrid>',
|
|
79
79
|
keywords: ['logos', 'brand', 'identity', 'logo usage', 'brand guidelines']
|
|
80
80
|
}, {
|
|
81
|
-
content:
|
|
81
|
+
content: "# Radius\n\nUse when applying or reviewing rounded corners in an Atlassian prototype or AFM component.\n\n## Choose and apply radius\n\n1. Identify the element's role and whether an ADS component already owns its shape. Retrieve that\n component's guidance before changing it. Keep a correct existing treatment.\n2. For custom UI, choose by role using the table below; compact controls and tiles have their own\n treatments.\n3. Apply the token through the project's supported styling API. Token values are subject to change\n and indicative only; use names rather than copied pixels.\n\n| Role and source-supported examples | Token |\n| -------------------------------------------------------------------------------------------------------------------------------- | ---------------- |\n| Small details: badges, checkboxes, avatar labels, keyboard shortcuts | `radius.xsmall` |\n| Small supporting elements: labels, lozenges, timestamps, tags, dates, tooltip containers, imagery inside tables, compact buttons | `radius.small` |\n| Interactive elements: buttons, inputs, text areas, selects, navigation items, smart links | `radius.medium` |\n| Containment: cards, in-page containers, floating UI, dropdown menus | `radius.large` |\n| Large page elements: full-page containers, large containers, modal dialogs, Kanban columns, tables | `radius.xlarge` |\n| Video players | `radius.xxlarge` |\n| Avatars, names, user-related UI, emoji reactions; also dividers and other pill-shaped elements, since the radius is fully round | `radius.full` |\n| Tile components exclusively, such as icon tiles or object tiles; never outside tiles | `radius.tile` |\n\n## Preserve keyboard focus\n\nThe focus ring must align visually with the component: its offset is 2px from the component's\nbounding box, and its radius equals the element's radius plus 2px.\n\n- **In code:** ADS interactive controls already apply focus treatment. For custom components, use\n [Focusable](https://atlassian.design/components/primitives/focusable/examples), which handles the\n 2px offset and radius calculation automatically. No separate focus radius token is needed.\n- **In design:** Use the design-only `radius.focus.*` tokens, such as `radius.focus.medium` for\n `radius.medium`. They mirror the base radius names with the calculated +2px value because design\n tools cannot calculate the relationship automatically. Do not apply these tokens in code.\n\n## Retrieve only the missing detail\n\nWhen loaded through the ADS skill, follow its retrieval order.\n\nUse the guidance here first. If a detail is missing, use `atlas ads`; use ADS MCP only after a CLI\nerror, an empty result, or a missing capability. For tokens, search by purpose, then confirm the\nexact token:\n\n```sh\natlas ads search \"<purpose>\" --type token --limit 5 --json\natlas ads token radius.medium --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\nRun the relevant project checks and inspect corner appearance and keyboard focus. Report what\nchanged or why no change was needed, distinguishing lookups from checks actually performed.\n\n## Sources\n\nPrinciples: [ADS radius](https://atlassian.design/foundations/radius). Exact names and purposes: the\n[design token reference list](https://atlassian.design/components/tokens/all-tokens). Use the\nselected component’s reference for its API and behavior.",
|
|
82
|
+
name: 'Radius',
|
|
82
83
|
keywords: ['radius', 'border radius', 'corners', 'roundness', 'design tokens', 'visual consistency']
|
|
83
84
|
}, {
|
|
84
85
|
content: "The consistent and intentional use of a spacing system creates a more harmonious experience for the\nend user. A spacing system also lays a foundation for responsive design and customisable UI density\nin the future, which will enhance the overall quality and accessibility of our apps.\n\n## 8 pixel base unit\n\nOur spacing system is built around a base unit of 8 pixels. This base unit determines the spacing\nscale and ensures visual consistency across apps.\n\n## Scale\n\nBuilding off of the 8px base unit, the main foundation of our spacing system is the spacing scale.\nThis scale is a limited set of space values that can be used to lay out UI elements in a consistent\nway.\n\nEach spacing value is a multiple of the base unit and ranges from 0px to 80px to allow for\nflexibility while still maintaining consistency across different layouts.\n\n## Space tokens\n\nThe 8px base unit also forms the basis of our space token system, as the base unit `space.100`.\nEvery space token is a multiple of this base unit, the number suffix representing the percentage of\nthe base unit.\n\nFor example, `space.200` is 200% of the size of the base unit, therefore represents 16px.\n\nEach space token should be used in place of the raw pixel or REM values when adding space between\ncomponents or objects on a page. Usage examples are detailed below.\n\n<SpacingTokensTable />\n\n### Negative values\n\nOur space token system also includes\n[negative values](https://atlassian.design/components/tokens/all-tokens#space) from\n`space.negative.025` to `space.negative.400` (-2px to -32px) available in code. These can be useful\nfor breaking out of a container's padding or for overlapping elements. Before reaching for negative\ntokens, see if you can use the\n[Bleed primitive](https://atlassian.design/components/primitives/bleed/example) which is designed\nspecifically to handle negative whitespace.\n\n## Spacing usage\n\nDifferent use cases require different ranges of spacing units to achieve the best outcomes. Our\nspacing scale can be broken into three different size ranges:\n\n\n\n### Small values - 0px to 8px\n\nUse the tokens from `space.0` to `space.100` (0px to 8px) for small and compact pieces of UI.\n\n#### Examples\n\n- Gap between small icons and text\n- Container padding of small components (ie badges, icon buttons, table cells)\n- Gap between repeating elements (ie button groups)\n- Padding within input components\n- Vertical spacing between elements in a card (ie a title and description, a description and\n actions)\n- Gap between the trigger and elevated element (ie between dropdown button & menu)\n\n### Medium values - 12px to 24px\n\nUse the tokens `space.150` to `space.300` (12px to 24px) for larger and less dense pieces of UI.\n\n#### Examples\n\n- Container padding of larger components (ie buttons)\n- Space between avatar/large icon and content (ie section messages)\n- Vertical spacing between elements in cards\n- Spacing between items in less densely packed or larger components\n\n### Large values - 32px to 80px\n\nUse the tokens `space.400` to `space.1000` (32px to 80px) for the largest pieces of UI and for\nlayout elements.\n\n#### Examples\n\n- The space between content on the page (ie spacing between top of page and header)\n- Alignment within larger pieces of content (ie alignment of content in Flag)\n\n## Layout guidelines\n\nA layout is composed of UI elements and components as well as the space between them. Applying these\nguidelines helps customers quickly understand the relationship between elements, allowing them to\nscan and digest page content with ease.\n\nUse these guidelines in combination with space tokens to create layouts that are consistent and easy\nto understand.\n\n### Group by similarity\n\nUsers expect elements to be grouped semantically, or grouped in such a way that it provides greater\ncontext around the information provided.\n\nUsing consistent spacing around elements lends them a visual similarity that helps the user\nunderstand their semantic relationship. For example, a table or list of items should be spaced\nconsistently to create the sense of a cohesive unit or collection.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: similarityDo, alt: '' }}>\n\t\tGroup similar items together using similar spacing.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: similarityDont, alt: '' }}>\n\t\tGroup similar items differently.\n\t</DoDont>\n</DoDontGrid>\n\n### Group by proximity\n\nThe distance between elements creates semantic meaning, elements that are placed close to one\nanother are assumed to be related.\n\nUse this principle to create meaning by placing more related objects closer together, and less\nrelated objects further apart. For example, place elements that are part of the same flow or user\naction closer together so users can understand their relation.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: proximityDo, alt: '' }}>\n\t\tGroup related items close together so that users can scan the content more easily.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: proximityDont, alt: '' }}>\n\t\tGroup related items far apart.\n\t</DoDont>\n</DoDontGrid>\n\n### Create order and hierarchy\n\nUsers look for order in visual information to reduce the mental effort required to scan and process\ndata. Therefore, the ordering of elements on a page can be used to encourage users to follow a\ncertain flow or journey.\n\nHierarchy is used to rank elements and influence the order in which users view them. The sizing of\ndifferent elements lends more importance to larger elements by drawing focus, and less to\nsmaller-sized elements. Similarly, varying the amount of whitespace around an element can be used to\ngroup elements together or separate them to impart greater importance.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: hierarchyDo, alt: '' }}>\n\t\tUse scale and whitespace to rank elements.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: hierarchyDont, alt: '' }}>\n\t\tGive every element the same visual importance.\n\t</DoDont>\n</DoDontGrid>\n\n### Introduce visual rhythm\n\nPatterns of alternating elements and white space create visual rhythm, which influences way users\nscan a page and focus their attention.\n\nUsing a pattern of similar spacing between elements (such as in a table or list) creates a\npredictable rhythm for the user to follow. This consistent rhythm reinforces the similarity in\nimportance of each of these elements.\n\nVarying the spacing between and sizing of objects creates a more organic flow and guides the user\nthrough a page or experience naturally. Variation creates points of attention and contrast between\nobjects on the page and improves scannability.\n\n\n\n### Use optical adjustment\n\nWhile using a spacing system improves consistency, the visual harmony of a page may not be perfect\nthe first time. The visual weight of an element affects the size and spacing that may be required to\ncreate balance on the page, and may deviate from standard spacing patterns. Optical adjustments\nshould be used to correct these imbalances and maintain the page’s flow.\n\nOptical adjustments require using the spacing scale units and visual intuition to make minor changes\nto the spacing between objects in order to create visual harmony.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: opticalAdjustmentDo, alt: '' }}>\n\t\tAdjust spacing to create visual balance.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: opticalAdjustmentDont, alt: '' }}>\n\t\tUse standard spacing without considering its alignment with other elements.\n\t</DoDont>\n</DoDontGrid>\n\n## Related\n\n- Learn more about [design tokens](https://atlassian.design/tokens/design-tokens)\n- [List of all design tokens](https://atlassian.design/components/tokens/all-tokens)",
|