@atlaskit/ads-mcp 1.11.0 → 1.11.1
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 +8 -6
- package/dist/es2019/tools/get-guidelines/guidelines-structured-content.codegen.js +8 -6
- package/dist/esm/tools/get-guidelines/guidelines-structured-content.codegen.js +8 -6
- package/dist/types/tools/get-guidelines/guidelines-structured-content.codegen.d.ts +2 -2
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# @atlaskit/ads-mcp
|
|
2
2
|
|
|
3
|
+
## 1.11.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [`d4b518cf3921b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/d4b518cf3921b) -
|
|
8
|
+
Deliver authored color and color-accent guidance through ADS tools, including input backgrounds
|
|
9
|
+
and decorative border token usage.
|
|
10
|
+
|
|
3
11
|
## 1.11.0
|
|
4
12
|
|
|
5
13
|
### Minor Changes
|
|
@@ -7,9 +7,9 @@ exports.guidelinesStructuredContent = void 0;
|
|
|
7
7
|
/**
|
|
8
8
|
* THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
|
|
9
9
|
*
|
|
10
|
-
* Structured content for
|
|
10
|
+
* Structured content for authored agent guidelines and design-system-docs foundations content.
|
|
11
11
|
*
|
|
12
|
-
* @codegen <<SignedSource::
|
|
12
|
+
* @codegen <<SignedSource::425b1c773867acafd317f203d71685ac>>
|
|
13
13
|
* @codegenCommand yarn build structured-docs
|
|
14
14
|
*/
|
|
15
15
|
|
|
@@ -20,11 +20,13 @@ var guidelinesStructuredContent = exports.guidelinesStructuredContent = [{
|
|
|
20
20
|
content: '## About border tokens\n\nBorders define boundaries and add emphasis using a combination of width and color tokens. Width\ntokens control a border\'s prominence, while color tokens provide its meaning. Pair these tokens to\ncommunicate an element’s purpose, such as a simple divider, or a visible interactive state.\n\n## Border width tokens and usage guidelines\n\nUse border width tokens to provide a clear and intentional way to apply width across different\nstates and use cases.\n\n<Stack space="space.200">\n\t<BorderTable />\n\t<Text>* Token values are subject to change and should be used as an indication only.</Text>\n</Stack>\n\n### Default border width\n\nThe `border.width` token is the default value for all standard borders and dividers. It establishes\nthe baseline thickness for components that require a subtle, defining outline, ensuring they are\nvisually distinct.\n\n\n\n### Selected states\n\nUse the `border.width.selected` token to show users which option they’ve selected from a group.\nApply this token to highlight a user\'s choice, such as an active tab or a chosen item in a list.\n\n\n\n### Focus ring\n\nUse the `border.width.focused` token to define the thickness of the focus ring. Apply this token to\nshow keyboard users where they are on the page. When users press Tab to move through an interface,\nthe token highlights the active element they can interact with. This helps make your interface\naccessible to everyone.\n\n\n\n## Border color and width pairing\n\nCreate borders by pairing width and color tokens. Choose:\n\n- width tokens to control how thick and visible your border appears\n- color tokens to show what the border means, like its state or importance\n\nAlways pair the right width token with the right color token to keep your interface consistent and\nclear for users.\n\n\n\n### Visual indicator for selected state\n\nAlways pair the `border.width.selected` token with the `color.border.selected` token, to show users\nwhich items they’ve selected. Use this combination to consistently highlight selected elements, like\nan active tab or a chosen list item, throughout the interface.\n\n\n\n### Required pairing for focus state\n\nAlways pair the `border.width.focused` token with the `color.border.focused` token to define the\nthickness of the focus ring.\n\nUse this combination to consistently highlight elements that receive keyboard focus, so users always\nknow which element is active and ready for interaction.\n\nTo ensure consistency and accessibility when adding a focused state to your components, follow these\nstandards:\n\n- **Code:** Use the\n [Focusable component](https://atlassian.design/components/primitives/focusable/examples) to wrap\n all interactive elements requiring focus.\n- **Design:** Use the\n [Focus Ring component (Atlassians only)](https://go.atlassian.com/focus-ring-component) from the\n Atlassian Design System Figma library.\n\n\n\nIt’s important to consider contrast when using different accent colors in your UI. For subtle\nbackgrounds, pair them with an accent border to meet the 3:1 contrast requirement for accessibility.\n\n[More about accent colors](https://atlassian.design/foundations/color/accents#use-borders-for-more-contrast-around-subtle-backgrounds)\n\n',
|
|
21
21
|
keywords: ['border', 'stroke', 'outline', 'design tokens', 'visual hierarchy']
|
|
22
22
|
}, {
|
|
23
|
-
content:
|
|
24
|
-
|
|
23
|
+
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
|
+
name: 'Color',
|
|
25
|
+
keywords: ['color', 'selected state colors', 'focus indicator colors', 'hovered and pressed states', 'contrast', 'palette', 'brand', 'design tokens', 'themes', 'input backgrounds', 'semantic statuses']
|
|
25
26
|
}, {
|
|
26
|
-
content:
|
|
27
|
-
|
|
27
|
+
content: "# Color accents\n\nUse accents for categories, projects, and labels when their hue can change without changing their\nmeaning. Choose a semantic color role for status, alerts, validation, primary actions, and discovery\ninstead; see the Color guidance.\n\nStart with the existing ADS component treatment for tags and labels. For custom UI, keep the\nbackground, text, and icon in the same accent hue family.\n\n**Available hues:** `blue`, `teal`, `green`, `lime`, `yellow`, `orange`, `red`, `magenta`, `purple`,\nand `gray`.\n\nPrefer another accent hue, such as orange, to yellow. Yellow accents can appear brown as their\nvalues adjust to meet contrast requirements.\n\n## Pair hue and emphasis\n\n| Background emphasis | Text and icon |\n| :---------------------- | :-------------------------------------------- |\n| `subtlest` or `subtler` | Matching accent `default` or `bolder` |\n| `subtle` | Matching accent `bolder` |\n| `bolder` | `color.text.inverse` and `color.icon.inverse` |\n\n```tsx\n// A category tag: the blue hue identifies a category, not a status\nbackgroundColor: token('color.background.accent.blue.subtlest'),\ncolor: token('color.text.accent.blue'),\n```\n\nUse `color.chart.*` for chart marks. For other pairings, check the rendered foreground and\nbackground: text needs 4.5:1 contrast and meaningful UI boundaries need 3:1.\n\n## Choose borders by their purpose\n\nUse `color.border.accent.[hue]` for a meaningful accent border on a non-bold accent background when\nthe boundary needs to meet 3:1 contrast. Verify the rendered pair when the boundary communicates a\ncontrol or state. The `.subtle` accent border variant is decorative; use it for visual decoration\nthat does not need to identify a boundary or state, not for a required control boundary. A required\nboundary must remain distinguishable without relying on a low-contrast decorative border.\n\n## Verify themes and states\n\nCheck the tag or label in its actual component, theme, and interaction states. Confirm that its hue\nstill means only the category, its text remains legible, and any required boundary stays visible.",
|
|
28
|
+
name: 'Color accents',
|
|
29
|
+
keywords: ['accent colors', 'non-status color', 'categories', 'tags', 'color pairing', 'accent tags', 'decorative borders', 'required borders', 'status colors', 'semantic colors', 'success', 'warning', 'error']
|
|
28
30
|
}, {
|
|
29
31
|
content: '## The palette\n\n<ColorPaletteRamps />\n\n## Picking colors for dark mode\n\nNeutral colors are set up in a way that makes it easy to convert a light theme to a dark theme. If\nyou use our [design tokens](https://atlassian.design/tokens/design-tokens) to apply colors, this\nmapping is done for you.\n\nThere is a light neutral ramp and an equivalent dark neutral ramp. Neutral100 in the light neutral\nramp should equate to DarkNeutral100 in the dark neutral ramp.\n\n<img\n\tsrc={paletteNeutralMapping}\n\talt="How light neutral ramp maps to dark neutral ramp in light and dark mode respectively."\n/>\n\nSaturated colors are also easy to convert from a light theme to a dark theme using symmetry. We\ncurrently have 10 swatches set up in each palette. If the swatches are divided in half, each half\nbecomes a mirror.\n\n<img\n\tsrc={paletteSaturatedMapping}\n\talt="How colors in the blue ramp maps across light and dark mode."\n/>\n\nFor instance, if a button color is 700 in light theme, it will be 400 in dark theme. If a section\nmessage background is 100 in light theme, it will be 1000 in dark theme. Design tokens will handle\nthese conversions for you.\n\n<img\n\tsrc={paletteJiraBoard}\n\talt="Screenshot of a Confluence page, which is shown half in light mode and half in dark mode. The button background uses B700 in light mode and B400 in dark mode. The section message background uses B100 in light mode and B1000 in dark mode."\n/>\n\nUsing symmetry is a great place to start and will cover most use cases. However, it may not work for\nall use cases and color mapping can be adjusted accordingly.\n\n## Dedicated to\n\nThese colors have been dedicated to honor the memory of Rosie and Alexandria, and will be woven into\nAtlassian apps and design for years to come.\n\n<ColorPaletteDedication />',
|
|
30
32
|
keywords: ['color palette', 'color system', 'brand colors', 'primary', 'secondary']
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
|
|
3
3
|
*
|
|
4
|
-
* Structured content for
|
|
4
|
+
* Structured content for authored agent guidelines and design-system-docs foundations content.
|
|
5
5
|
*
|
|
6
|
-
* @codegen <<SignedSource::
|
|
6
|
+
* @codegen <<SignedSource::425b1c773867acafd317f203d71685ac>>
|
|
7
7
|
* @codegenCommand yarn build structured-docs
|
|
8
8
|
*/
|
|
9
9
|
|
|
@@ -14,11 +14,13 @@ export const guidelinesStructuredContent = [{
|
|
|
14
14
|
content: '## About border tokens\n\nBorders define boundaries and add emphasis using a combination of width and color tokens. Width\ntokens control a border\'s prominence, while color tokens provide its meaning. Pair these tokens to\ncommunicate an element’s purpose, such as a simple divider, or a visible interactive state.\n\n## Border width tokens and usage guidelines\n\nUse border width tokens to provide a clear and intentional way to apply width across different\nstates and use cases.\n\n<Stack space="space.200">\n\t<BorderTable />\n\t<Text>* Token values are subject to change and should be used as an indication only.</Text>\n</Stack>\n\n### Default border width\n\nThe `border.width` token is the default value for all standard borders and dividers. It establishes\nthe baseline thickness for components that require a subtle, defining outline, ensuring they are\nvisually distinct.\n\n\n\n### Selected states\n\nUse the `border.width.selected` token to show users which option they’ve selected from a group.\nApply this token to highlight a user\'s choice, such as an active tab or a chosen item in a list.\n\n\n\n### Focus ring\n\nUse the `border.width.focused` token to define the thickness of the focus ring. Apply this token to\nshow keyboard users where they are on the page. When users press Tab to move through an interface,\nthe token highlights the active element they can interact with. This helps make your interface\naccessible to everyone.\n\n\n\n## Border color and width pairing\n\nCreate borders by pairing width and color tokens. Choose:\n\n- width tokens to control how thick and visible your border appears\n- color tokens to show what the border means, like its state or importance\n\nAlways pair the right width token with the right color token to keep your interface consistent and\nclear for users.\n\n\n\n### Visual indicator for selected state\n\nAlways pair the `border.width.selected` token with the `color.border.selected` token, to show users\nwhich items they’ve selected. Use this combination to consistently highlight selected elements, like\nan active tab or a chosen list item, throughout the interface.\n\n\n\n### Required pairing for focus state\n\nAlways pair the `border.width.focused` token with the `color.border.focused` token to define the\nthickness of the focus ring.\n\nUse this combination to consistently highlight elements that receive keyboard focus, so users always\nknow which element is active and ready for interaction.\n\nTo ensure consistency and accessibility when adding a focused state to your components, follow these\nstandards:\n\n- **Code:** Use the\n [Focusable component](https://atlassian.design/components/primitives/focusable/examples) to wrap\n all interactive elements requiring focus.\n- **Design:** Use the\n [Focus Ring component (Atlassians only)](https://go.atlassian.com/focus-ring-component) from the\n Atlassian Design System Figma library.\n\n\n\nIt’s important to consider contrast when using different accent colors in your UI. For subtle\nbackgrounds, pair them with an accent border to meet the 3:1 contrast requirement for accessibility.\n\n[More about accent colors](https://atlassian.design/foundations/color/accents#use-borders-for-more-contrast-around-subtle-backgrounds)\n\n',
|
|
15
15
|
keywords: ['border', 'stroke', 'outline', 'design tokens', 'visual hierarchy']
|
|
16
16
|
}, {
|
|
17
|
-
content:
|
|
18
|
-
|
|
17
|
+
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
|
+
name: 'Color',
|
|
19
|
+
keywords: ['color', 'selected state colors', 'focus indicator colors', 'hovered and pressed states', 'contrast', 'palette', 'brand', 'design tokens', 'themes', 'input backgrounds', 'semantic statuses']
|
|
19
20
|
}, {
|
|
20
|
-
content:
|
|
21
|
-
|
|
21
|
+
content: "# Color accents\n\nUse accents for categories, projects, and labels when their hue can change without changing their\nmeaning. Choose a semantic color role for status, alerts, validation, primary actions, and discovery\ninstead; see the Color guidance.\n\nStart with the existing ADS component treatment for tags and labels. For custom UI, keep the\nbackground, text, and icon in the same accent hue family.\n\n**Available hues:** `blue`, `teal`, `green`, `lime`, `yellow`, `orange`, `red`, `magenta`, `purple`,\nand `gray`.\n\nPrefer another accent hue, such as orange, to yellow. Yellow accents can appear brown as their\nvalues adjust to meet contrast requirements.\n\n## Pair hue and emphasis\n\n| Background emphasis | Text and icon |\n| :---------------------- | :-------------------------------------------- |\n| `subtlest` or `subtler` | Matching accent `default` or `bolder` |\n| `subtle` | Matching accent `bolder` |\n| `bolder` | `color.text.inverse` and `color.icon.inverse` |\n\n```tsx\n// A category tag: the blue hue identifies a category, not a status\nbackgroundColor: token('color.background.accent.blue.subtlest'),\ncolor: token('color.text.accent.blue'),\n```\n\nUse `color.chart.*` for chart marks. For other pairings, check the rendered foreground and\nbackground: text needs 4.5:1 contrast and meaningful UI boundaries need 3:1.\n\n## Choose borders by their purpose\n\nUse `color.border.accent.[hue]` for a meaningful accent border on a non-bold accent background when\nthe boundary needs to meet 3:1 contrast. Verify the rendered pair when the boundary communicates a\ncontrol or state. The `.subtle` accent border variant is decorative; use it for visual decoration\nthat does not need to identify a boundary or state, not for a required control boundary. A required\nboundary must remain distinguishable without relying on a low-contrast decorative border.\n\n## Verify themes and states\n\nCheck the tag or label in its actual component, theme, and interaction states. Confirm that its hue\nstill means only the category, its text remains legible, and any required boundary stays visible.",
|
|
22
|
+
name: 'Color accents',
|
|
23
|
+
keywords: ['accent colors', 'non-status color', 'categories', 'tags', 'color pairing', 'accent tags', 'decorative borders', 'required borders', 'status colors', 'semantic colors', 'success', 'warning', 'error']
|
|
22
24
|
}, {
|
|
23
25
|
content: '## The palette\n\n<ColorPaletteRamps />\n\n## Picking colors for dark mode\n\nNeutral colors are set up in a way that makes it easy to convert a light theme to a dark theme. If\nyou use our [design tokens](https://atlassian.design/tokens/design-tokens) to apply colors, this\nmapping is done for you.\n\nThere is a light neutral ramp and an equivalent dark neutral ramp. Neutral100 in the light neutral\nramp should equate to DarkNeutral100 in the dark neutral ramp.\n\n<img\n\tsrc={paletteNeutralMapping}\n\talt="How light neutral ramp maps to dark neutral ramp in light and dark mode respectively."\n/>\n\nSaturated colors are also easy to convert from a light theme to a dark theme using symmetry. We\ncurrently have 10 swatches set up in each palette. If the swatches are divided in half, each half\nbecomes a mirror.\n\n<img\n\tsrc={paletteSaturatedMapping}\n\talt="How colors in the blue ramp maps across light and dark mode."\n/>\n\nFor instance, if a button color is 700 in light theme, it will be 400 in dark theme. If a section\nmessage background is 100 in light theme, it will be 1000 in dark theme. Design tokens will handle\nthese conversions for you.\n\n<img\n\tsrc={paletteJiraBoard}\n\talt="Screenshot of a Confluence page, which is shown half in light mode and half in dark mode. The button background uses B700 in light mode and B400 in dark mode. The section message background uses B100 in light mode and B1000 in dark mode."\n/>\n\nUsing symmetry is a great place to start and will cover most use cases. However, it may not work for\nall use cases and color mapping can be adjusted accordingly.\n\n## Dedicated to\n\nThese colors have been dedicated to honor the memory of Rosie and Alexandria, and will be woven into\nAtlassian apps and design for years to come.\n\n<ColorPaletteDedication />',
|
|
24
26
|
keywords: ['color palette', 'color system', 'brand colors', 'primary', 'secondary']
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
|
|
3
3
|
*
|
|
4
|
-
* Structured content for
|
|
4
|
+
* Structured content for authored agent guidelines and design-system-docs foundations content.
|
|
5
5
|
*
|
|
6
|
-
* @codegen <<SignedSource::
|
|
6
|
+
* @codegen <<SignedSource::425b1c773867acafd317f203d71685ac>>
|
|
7
7
|
* @codegenCommand yarn build structured-docs
|
|
8
8
|
*/
|
|
9
9
|
|
|
@@ -14,11 +14,13 @@ export var guidelinesStructuredContent = [{
|
|
|
14
14
|
content: '## About border tokens\n\nBorders define boundaries and add emphasis using a combination of width and color tokens. Width\ntokens control a border\'s prominence, while color tokens provide its meaning. Pair these tokens to\ncommunicate an element’s purpose, such as a simple divider, or a visible interactive state.\n\n## Border width tokens and usage guidelines\n\nUse border width tokens to provide a clear and intentional way to apply width across different\nstates and use cases.\n\n<Stack space="space.200">\n\t<BorderTable />\n\t<Text>* Token values are subject to change and should be used as an indication only.</Text>\n</Stack>\n\n### Default border width\n\nThe `border.width` token is the default value for all standard borders and dividers. It establishes\nthe baseline thickness for components that require a subtle, defining outline, ensuring they are\nvisually distinct.\n\n\n\n### Selected states\n\nUse the `border.width.selected` token to show users which option they’ve selected from a group.\nApply this token to highlight a user\'s choice, such as an active tab or a chosen item in a list.\n\n\n\n### Focus ring\n\nUse the `border.width.focused` token to define the thickness of the focus ring. Apply this token to\nshow keyboard users where they are on the page. When users press Tab to move through an interface,\nthe token highlights the active element they can interact with. This helps make your interface\naccessible to everyone.\n\n\n\n## Border color and width pairing\n\nCreate borders by pairing width and color tokens. Choose:\n\n- width tokens to control how thick and visible your border appears\n- color tokens to show what the border means, like its state or importance\n\nAlways pair the right width token with the right color token to keep your interface consistent and\nclear for users.\n\n\n\n### Visual indicator for selected state\n\nAlways pair the `border.width.selected` token with the `color.border.selected` token, to show users\nwhich items they’ve selected. Use this combination to consistently highlight selected elements, like\nan active tab or a chosen list item, throughout the interface.\n\n\n\n### Required pairing for focus state\n\nAlways pair the `border.width.focused` token with the `color.border.focused` token to define the\nthickness of the focus ring.\n\nUse this combination to consistently highlight elements that receive keyboard focus, so users always\nknow which element is active and ready for interaction.\n\nTo ensure consistency and accessibility when adding a focused state to your components, follow these\nstandards:\n\n- **Code:** Use the\n [Focusable component](https://atlassian.design/components/primitives/focusable/examples) to wrap\n all interactive elements requiring focus.\n- **Design:** Use the\n [Focus Ring component (Atlassians only)](https://go.atlassian.com/focus-ring-component) from the\n Atlassian Design System Figma library.\n\n\n\nIt’s important to consider contrast when using different accent colors in your UI. For subtle\nbackgrounds, pair them with an accent border to meet the 3:1 contrast requirement for accessibility.\n\n[More about accent colors](https://atlassian.design/foundations/color/accents#use-borders-for-more-contrast-around-subtle-backgrounds)\n\n',
|
|
15
15
|
keywords: ['border', 'stroke', 'outline', 'design tokens', 'visual hierarchy']
|
|
16
16
|
}, {
|
|
17
|
-
content:
|
|
18
|
-
|
|
17
|
+
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
|
+
name: 'Color',
|
|
19
|
+
keywords: ['color', 'selected state colors', 'focus indicator colors', 'hovered and pressed states', 'contrast', 'palette', 'brand', 'design tokens', 'themes', 'input backgrounds', 'semantic statuses']
|
|
19
20
|
}, {
|
|
20
|
-
content:
|
|
21
|
-
|
|
21
|
+
content: "# Color accents\n\nUse accents for categories, projects, and labels when their hue can change without changing their\nmeaning. Choose a semantic color role for status, alerts, validation, primary actions, and discovery\ninstead; see the Color guidance.\n\nStart with the existing ADS component treatment for tags and labels. For custom UI, keep the\nbackground, text, and icon in the same accent hue family.\n\n**Available hues:** `blue`, `teal`, `green`, `lime`, `yellow`, `orange`, `red`, `magenta`, `purple`,\nand `gray`.\n\nPrefer another accent hue, such as orange, to yellow. Yellow accents can appear brown as their\nvalues adjust to meet contrast requirements.\n\n## Pair hue and emphasis\n\n| Background emphasis | Text and icon |\n| :---------------------- | :-------------------------------------------- |\n| `subtlest` or `subtler` | Matching accent `default` or `bolder` |\n| `subtle` | Matching accent `bolder` |\n| `bolder` | `color.text.inverse` and `color.icon.inverse` |\n\n```tsx\n// A category tag: the blue hue identifies a category, not a status\nbackgroundColor: token('color.background.accent.blue.subtlest'),\ncolor: token('color.text.accent.blue'),\n```\n\nUse `color.chart.*` for chart marks. For other pairings, check the rendered foreground and\nbackground: text needs 4.5:1 contrast and meaningful UI boundaries need 3:1.\n\n## Choose borders by their purpose\n\nUse `color.border.accent.[hue]` for a meaningful accent border on a non-bold accent background when\nthe boundary needs to meet 3:1 contrast. Verify the rendered pair when the boundary communicates a\ncontrol or state. The `.subtle` accent border variant is decorative; use it for visual decoration\nthat does not need to identify a boundary or state, not for a required control boundary. A required\nboundary must remain distinguishable without relying on a low-contrast decorative border.\n\n## Verify themes and states\n\nCheck the tag or label in its actual component, theme, and interaction states. Confirm that its hue\nstill means only the category, its text remains legible, and any required boundary stays visible.",
|
|
22
|
+
name: 'Color accents',
|
|
23
|
+
keywords: ['accent colors', 'non-status color', 'categories', 'tags', 'color pairing', 'accent tags', 'decorative borders', 'required borders', 'status colors', 'semantic colors', 'success', 'warning', 'error']
|
|
22
24
|
}, {
|
|
23
25
|
content: '## The palette\n\n<ColorPaletteRamps />\n\n## Picking colors for dark mode\n\nNeutral colors are set up in a way that makes it easy to convert a light theme to a dark theme. If\nyou use our [design tokens](https://atlassian.design/tokens/design-tokens) to apply colors, this\nmapping is done for you.\n\nThere is a light neutral ramp and an equivalent dark neutral ramp. Neutral100 in the light neutral\nramp should equate to DarkNeutral100 in the dark neutral ramp.\n\n<img\n\tsrc={paletteNeutralMapping}\n\talt="How light neutral ramp maps to dark neutral ramp in light and dark mode respectively."\n/>\n\nSaturated colors are also easy to convert from a light theme to a dark theme using symmetry. We\ncurrently have 10 swatches set up in each palette. If the swatches are divided in half, each half\nbecomes a mirror.\n\n<img\n\tsrc={paletteSaturatedMapping}\n\talt="How colors in the blue ramp maps across light and dark mode."\n/>\n\nFor instance, if a button color is 700 in light theme, it will be 400 in dark theme. If a section\nmessage background is 100 in light theme, it will be 1000 in dark theme. Design tokens will handle\nthese conversions for you.\n\n<img\n\tsrc={paletteJiraBoard}\n\talt="Screenshot of a Confluence page, which is shown half in light mode and half in dark mode. The button background uses B700 in light mode and B400 in dark mode. The section message background uses B100 in light mode and B1000 in dark mode."\n/>\n\nUsing symmetry is a great place to start and will cover most use cases. However, it may not work for\nall use cases and color mapping can be adjusted accordingly.\n\n## Dedicated to\n\nThese colors have been dedicated to honor the memory of Rosie and Alexandria, and will be woven into\nAtlassian apps and design for years to come.\n\n<ColorPaletteDedication />',
|
|
24
26
|
keywords: ['color palette', 'color system', 'brand colors', 'primary', 'secondary']
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
|
|
3
3
|
*
|
|
4
|
-
* Structured content for
|
|
4
|
+
* Structured content for authored agent guidelines and design-system-docs foundations content.
|
|
5
5
|
*
|
|
6
|
-
* @codegen <<SignedSource::
|
|
6
|
+
* @codegen <<SignedSource::425b1c773867acafd317f203d71685ac>>
|
|
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.1",
|
|
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",
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
"@atlaskit/icon": "^38.0.0",
|
|
25
25
|
"@atlaskit/icon-lab": "^7.11.0",
|
|
26
26
|
"@atlaskit/platform-feature-flags": "^2.2.0",
|
|
27
|
-
"@atlaskit/tokens": "^20.
|
|
27
|
+
"@atlaskit/tokens": "^20.5.0",
|
|
28
28
|
"@axe-core/playwright": "^4.11.1",
|
|
29
29
|
"@axe-core/puppeteer": "^4.11.1",
|
|
30
30
|
"@babel/runtime": "^7.0.0",
|