@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/data/docs/routes/components-buttons.json

@@ -0,0 +1,36 @@
+{
+  "meta": {
+    "id": "Components-Buttons",
+    "title": "Buttons",
+    "description": "Components for triggering actions, submitting forms, and navigation.",
+    "order": 3,
+    "repoPath": "packages/nimbus/src/docs/buttons.mdx",
+    "menu": [
+      "Components",
+      "Buttons"
+    ],
+    "route": "components/buttons",
+    "tags": [
+      "buttons",
+      "actions",
+      "interactions"
+    ],
+    "toc": [],
+    "icon": "SmartButton",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": " \n\n# Buttons  \n\nComponents for triggering actions, submitting forms, and navigation.\n\n<CategoryOverview variant=\"list\" />",
+  "views": {
+    "overview": {
+      "mdx": " \n\n# Buttons  \n\nComponents for triggering actions, submitting forms, and navigation.\n\n<CategoryOverview variant=\"list\" />",
+      "toc": []
+    }
+  }
+}

package/data/docs/routes/components-data-display-badge.json

@@ -0,0 +1,555 @@
+{
+  "meta": {
+    "id": "Components-Badge",
+    "title": "Badge",
+    "exportName": "Badge",
+    "description": "Briefly highlights or categorizes associated UI elements with concise visual cues for status or metadata.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/badge/badge.mdx",
+    "menu": [
+      "Components",
+      "Data Display",
+      "Badge"
+    ],
+    "route": "components/data-display/badge",
+    "tags": [
+      "component",
+      "badge",
+      "label",
+      "status",
+      "indicator"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Medium",
+        "href": "#medium",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "X-small",
+        "href": "#x-small",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "2X-small",
+        "href": "#2x-small",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Visual options",
+        "href": "#visual-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Semantic colors",
+        "href": "#semantic-colors",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Custom colors",
+        "href": "#custom-colors",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nBadges are small, visually distinct labels used to highlight status, category,\nor counts associated with other UI elements. They feature concise text and\ncustomizable styling for clear communication without overwhelming the primary\ncontent.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=2656-4636&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\n#### Medium\n\nThis is the default size.\n\n```jsx live\nconst App = () => (\n  <Badge colorPalette=\"primary\" size=\"md\">\n    <Icons.SentimentSatisfied />\n    Badge\n    <Icons.SentimentSatisfied />\n  </Badge>\n)\n```\n\n#### X-small\n\nFor uses where several badges will be shown at one time.\n\n```jsx live\nconst App = () => (\n  <Badge colorPalette=\"primary\" size=\"xs\">\n    <Icons.SentimentSatisfied />\n    Badge\n    <Icons.SentimentSatisfied />\n  </Badge>\n)\n```\n\n#### 2X-small\n\nUse these when there are a more than a few badges at one time, or to be less\ndistracting to let the user focus on other parts of the surrounding page.\n\n```jsx live\nconst App = () => (\n  <Badge colorPalette=\"primary\" size=\"2xs\">\n    <Icons.SentimentSatisfied />\n    Badge\n    <Icons.SentimentSatisfied />\n  </Badge>\n)\n```\n\n### Visual options\n\nBadges can be set to use either the semantic color palette or any other radix\ncolor. When pairing new radix colors, the formula uses the 3rd color shade for\nthe background and the 11th for text to maintain text accessibility.\n\n#### Semantic colors\n\nWhen a badge is supposed to convey a specific and consistent meaning, use these\npredefined color options.\n\n```jsx live\nconst App = () => {\n  const semanticColors = ['info', 'primary', 'positive', 'critical', 'warning', 'neutral'];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"center\" flexWrap=\"wrap\">\n      {semanticColors.map(color => (\n        <Badge key={color} colorPalette={color}>{color}</Badge>\n      ))}\n    </Stack>\n  )\n}\n```\n\n#### Custom colors\n\nWhen the color of the badge serves a purely aesthetic purpose, or the semantic\ncolor palette does not offer enough options, use any of these available options\nfrom our color palette.\n\n```jsx live\nconst App = () => {\n  const customColors = ['teal', 'pink', 'mint'];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"center\" flexWrap=\"wrap\">\n      {customColors.map(color => (\n        <Badge key={color} colorPalette={color}>{color}</Badge>\n      ))}\n    </Stack>\n  )\n}\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nBadges are small, visually distinct labels used to highlight status, category,\nor counts associated with other UI elements. They feature concise text and\ncustomizable styling for clear communication without overwhelming the primary\ncontent.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=2656-4636&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\n#### Medium\n\nThis is the default size.\n\n```jsx live\nconst App = () => (\n  <Badge colorPalette=\"primary\" size=\"md\">\n    <Icons.SentimentSatisfied />\n    Badge\n    <Icons.SentimentSatisfied />\n  </Badge>\n)\n```\n\n#### X-small\n\nFor uses where several badges will be shown at one time.\n\n```jsx live\nconst App = () => (\n  <Badge colorPalette=\"primary\" size=\"xs\">\n    <Icons.SentimentSatisfied />\n    Badge\n    <Icons.SentimentSatisfied />\n  </Badge>\n)\n```\n\n#### 2X-small\n\nUse these when there are a more than a few badges at one time, or to be less\ndistracting to let the user focus on other parts of the surrounding page.\n\n```jsx live\nconst App = () => (\n  <Badge colorPalette=\"primary\" size=\"2xs\">\n    <Icons.SentimentSatisfied />\n    Badge\n    <Icons.SentimentSatisfied />\n  </Badge>\n)\n```\n\n### Visual options\n\nBadges can be set to use either the semantic color palette or any other radix\ncolor. When pairing new radix colors, the formula uses the 3rd color shade for\nthe background and the 11th for text to maintain text accessibility.\n\n#### Semantic colors\n\nWhen a badge is supposed to convey a specific and consistent meaning, use these\npredefined color options.\n\n```jsx live\nconst App = () => {\n  const semanticColors = ['info', 'primary', 'positive', 'critical', 'warning', 'neutral'];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"center\" flexWrap=\"wrap\">\n      {semanticColors.map(color => (\n        <Badge key={color} colorPalette={color}>{color}</Badge>\n      ))}\n    </Stack>\n  )\n}\n```\n\n#### Custom colors\n\nWhen the color of the badge serves a purely aesthetic purpose, or the semantic\ncolor palette does not offer enough options, use any of these available options\nfrom our color palette.\n\n```jsx live\nconst App = () => {\n  const customColors = ['teal', 'pink', 'mint'];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"center\" flexWrap=\"wrap\">\n      {customColors.map(color => (\n        <Badge key={color} colorPalette={color}>{color}</Badge>\n      ))}\n    </Stack>\n  )\n}\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Medium",
+          "href": "#medium",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "X-small",
+          "href": "#x-small",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "2X-small",
+          "href": "#2x-small",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual options",
+          "href": "#visual-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Semantic colors",
+          "href": "#semantic-colors",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom colors",
+          "href": "#custom-colors",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <Badge\n    data-testid=\"status-badge\"\n    aria-label=\"Status: Active\"\n    colorPalette=\"primary\"\n  >\n    <Icons.StarOutline />\n    I am a badge\n  </Badge>\n)\n```\n\n### Accessibility standards\n\n- Always provide a meaningful label. If a visible label is not used, provide an\n  aria-label for screen readers.\n- Ensure sufficient color contrast for all elements (text and background).\n- Avoid relying on color alone to convey information.\n- Clearly indicate keyboard focus when interactive.\n- Support keyboard navigation (e.g., `Tab`, `Space`, `Enter`).\n- Manage text overflow (wrap text or truncate with a tooltip).\n- Use descriptive `aria-describedby` if attached to an interactive element.\n- Include a tooltip for icon-only badges.\n\n### Resources\n\n- [Adobe Spectrum Design System](https://spectrum.adobe.com/page/badge/)\n- [React Spectrum](https://react-spectrum.adobe.com/react-aria/useBadge.html)\n- [W3C ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/patterns/badge/)\n  (Search for \"Badge\" patterns or general guidance on status indicators)\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Badge, type BadgeProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses the default size and color:\n\n```jsx live-dev\nconst App = () => (\n  <Badge>Default Badge</Badge>\n)\n```\n\n## Usage examples\n\n### Size options\n\nThe `2xs`, `xs`, and `md` size variants are available to match your interface density:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Badge size=\"2xs\">2xs Badge</Badge>\n    <Badge size=\"xs\">xs Badge</Badge>\n    <Badge size=\"md\">md Badge</Badge>\n  </Stack>\n)\n```\n\n### Visual variants\n\nBadges support color palettes to convey semantic meaning or match a theme:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Badge colorPalette=\"primary\">Primary</Badge>\n    <Badge colorPalette=\"positive\">Positive</Badge>\n    <Badge colorPalette=\"info\">Info</Badge>\n    <Badge colorPalette=\"critical\">Critical</Badge>\n    <Badge colorPalette=\"cyan\">Cyan</Badge>\n  </Stack>\n)\n```\n\n### With icons\n\nBadges can contain icons alongside text for enhanced visual communication:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Badge>\n      <Icons.SentimentSatisfied />\n      Verified\n    </Badge>\n    <Badge colorPalette=\"critical\">\n      <Icons.Error />\n      Error\n    </Badge>\n  </Stack>\n)\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Badge component handles most accessibility requirements internally. However, you should ensure that the badge content is accessible.\n\n- **Color Contrast**: The default color mappings (shade 3 for background, shade 11 for text) are designed to meet WCAG contrast requirements.\n- **Screen Readers**: The badge text is read normally by screen readers. If the badge conveys status (like \"Error\"), ensure the text or a visually hidden label clarifies this context if it's not obvious from the surrounding content.\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-badge\";\n\nexport const Example = () => (\n  <Badge id={PERSISTENT_ID}>Status</Badge>\n);\n```\n\n#### Keyboard navigation\n\nBadges are non-interactive elements and do not receive focus or support keyboard interaction.\n\n## API reference\n\n<PropsTable id=\"Badge\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Badge within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the component renders with expected elements\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Badge, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Badge - Basic rendering\", () => {\n  it(\"renders content correctly\", () => {\n    render(\n      <NimbusProvider>\n        <Badge>Status: Active</Badge>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Status: Active\")).toBeInTheDocument();\n  });\n\n  it(\"renders with icon and text\", () => {\n    render(\n      <NimbusProvider>\n        <Badge>Verified</Badge>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Verified\")).toBeInTheDocument();\n  });\n});\n```\n\n### Variant Rendering Tests\n\nTest rendering with different sizes and color palettes\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Badge, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Badge - Variants\", () => {\n  it(\"renders with specific size\", () => {\n    render(\n      <NimbusProvider>\n        <Badge size=\"xs\">Small Badge</Badge>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Small Badge\")).toBeInTheDocument();\n  });\n\n  it(\"renders with specific color palette\", () => {\n    render(\n      <NimbusProvider>\n        <Badge colorPalette=\"critical\">Error</Badge>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Error\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-badge--docs)\n\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With icons",
+          "href": "#with-icons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variant Rendering Tests",
+          "href": "#variant-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nBadge guidelines ensure small, clear visual cues that highlight status or\nmetadata without overwhelming UI.\n\n### Best practices\n\n- **Be concise**: Keep badge labels short and to the point (ideally 1-2 words or\n  a small number).\n- **Use purposefully**: Only use badges to highlight truly important information\n  or status; avoid overusing them.\n- **Maintain visual hierarchy**: Ensure badges are visually less prominent than\n  the elements they annotate.\n- **Employ semantic colors**: Use established color palettes to consistently\n  indicate meaning (e.g., green for success, red for error).\n- **Place strategically**: Position badges consistently in relation to their\n  associated elements for easy recognition.\n- **Provide context**: If an icon-only badge is used, ensure a tooltip or\n  surrounding context clarifies its meaning.\n\n### Usage\n\nBadges are small labels that highlight relevant metadata without overwhelming\nthe primary content, often using color and short text or icons to quickly convey\nmeaning. They are commonly found attached to navigation items, buttons, lists,\nand avatars to draw attention to updates, counts, or specific attributes.\n\n#### Should I use badges or tags?\n\n- **Tags** display items of the same category, or basically a list of things\n  just styled more aesthetically (e.g., countries). An item can display more\n  than one tag at once as a group.\n- **Badges** highlight the differences between the listed items (e.g., status:\n  Published, Modified, Rejected) and benefit from semantic color ways to convey\n  process or status. An item should only show one badge; if you want to show\n  more than one, use a tag instead.\n\n> [!TIP]\\\n> When to use\n\n- **Use for concise information:** Keep badge text short (1-2 words) for quick\n  readability.\n- **Indicate status or category:** Clearly signal the state or classification of\n  an associated element.\n- **Maintain visual hierarchy:** Ensure badges are visually subordinate to the\n  elements they modify.\n- **Use color thoughtfully:** Employ color consistently to convey meaning (e.g.,\n  green for positive, red for negative).\n- **Ensure accessibility:** Provide sufficient color contrast meeting at least\n  AA requirements, and use ARIA attributes for screen readers.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Don't overuse badges:** Reserve them for important highlights to avoid\n  visual clutter.\n- **Don't use as headers:** Employ proper typography for establishing hierarchy.\n- **Don't use for lengthy feedback:** Use other UI elements for detailed\n  messages.\n- **Don't rely solely on color:** Supplement color with text or icons for\n  accessibility.\n- **Don't place them obstructively:** Ensure badges don't cover or interfere\n  with primary content or interactions.\n\n### Semantic colors\n\nUse the established color palettes to consistently indicate meaning (if\napplicable) when using badges.\n\n> [!TIP]\\\n> **Do**\n>\n> - When communicating a success or positive state, use grass (green). For a\n>   negative or critical state use tomato (red). If you need a warning state,\n>   use yellow (amber). For default or neutral color options, use grey (slate),\n>   blue, or purple (primary).\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"200\">\n    <Badge colorPalette=\"positive\">Published</Badge>\n    <Badge colorPalette=\"critical\">Expired</Badge>\n    <Badge colorPalette=\"warning\">Modified</Badge>\n    <Badge colorPalette=\"info\">Trial version</Badge>\n    <Badge colorPalette=\"primary\">Premium</Badge>\n    <Badge colorPalette=\"neutral\">Disabled</Badge>\n  </Stack>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't trick your users when the common pattern will be to have the meaning\n>   and color together.\n> - Do not use icons without label unless used with a tooltip label so users can\n>   best understand the meaning of the badge.\n> - Don't rely solely on color to relate a state. Pairing colors with an icon\n>   and short descriptive label will be the best experience for accessibility\n>   standards.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"200\">\n    <Badge colorPalette=\"positive\">Unpublish</Badge>\n    <Badge colorPalette=\"critical\">Publish</Badge>\n    <Badge colorPalette=\"warning\">\n      <Icons.Campaign />\n    </Badge>\n    <Badge colorPalette=\"info\">Expired</Badge>\n    <Badge colorPalette=\"primary\">\n      <Icons.Delete /> Delete\n    </Badge>\n    <Badge colorPalette=\"neutral\">\n      <Icons.FiberNew /> Updated\n    </Badge>\n  </Stack>\n);\n```\n\n### Purposeful uses\n\nTaking care not to overuse badges is important, they are great tools to help\nusers group or understand statuses, but overuse can be confusing and\noverwhelming.\n\n> [!TIP]\\\n> **Do**\n>\n> - Do use short and concise labels for badges, making sure not to overuse and\n>   clutter the space for the user.\n> - If using icons, pair the icon with a label or a tooltip so the user can\n>   understand the meaning.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select...\" data-testid=\"select\" w=\"1/2\">\n    <Select.Options>\n      <Select.OptionGroup label=\"Projects\">\n        <Select.Option>\n          <Flex alignItems=\"center\" justifyContent=\"space-between\">\n            <Text>Trial project</Text>\n            <Badge colorPalette=\"critical\" size=\"xs\">\n              Expired\n            </Badge>\n          </Flex>\n        </Select.Option>\n        <Select.Option>\n          <Flex alignItems=\"center\" justifyContent=\"space-between\">\n            <Text>Main project</Text>\n            <Badge colorPalette=\"positive\" size=\"xs\">\n              Production\n            </Badge>\n          </Flex>\n        </Select.Option>\n      </Select.OptionGroup>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not overuse badges.\n> - Do not be overly descriptive with labels. Keep language as short as\n>   possible.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select...\" data-testid=\"select\" w=\"1/2\">\n    <Select.Options>\n      <Select.OptionGroup label=\"Projects\">\n        <Select.Option>\n          <Flex alignItems=\"start\" justifyContent=\"space-between\">\n            <Text>Trial project</Text>\n            <Stack direction=\"column\" gap=\"100\" alignItems=\"end\">\n              <Badge colorPalette=\"critical\" size=\"xs\">\n                Expired\n              </Badge>\n              <Badge colorPalette=\"critical\" size=\"xs\">\n                Suspended\n              </Badge>\n              <Badge colorPalette=\"critical\" size=\"xs\">\n                Will be deleted soon, in 24 days\n              </Badge>\n            </Stack>\n          </Flex>\n        </Select.Option>\n        <Select.Option>\n          <Flex alignItems=\"start\" justifyContent=\"space-between\">\n            <Text>Main project</Text>\n            <Stack direction=\"column\" gap=\"100\" alignItems=\"end\">\n              <Badge colorPalette=\"positive\" size=\"xs\">\n                Production\n              </Badge>\n              <Badge colorPalette=\"warning\" size=\"xs\">\n                Modified, needs updating\n              </Badge>\n            </Stack>\n          </Flex>\n        </Select.Option>\n      </Select.OptionGroup>\n    </Select.Options>\n  </Select.Root>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Should I use badges or tags?",
+          "href": "#should-i-use-badges-or-tags",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Semantic colors",
+          "href": "#semantic-colors",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Purposeful uses",
+          "href": "#purposeful-uses",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}