@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/home-design-tokens-typography.json

@@ -0,0 +1,184 @@
+{
+  "meta": {
+    "id": "TokensTypography",
+    "title": "Typography",
+    "description": "everything typography related",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/docs/tokens/typography.mdx",
+    "menu": [
+      "Home",
+      "Design Tokens",
+      "Typography"
+    ],
+    "route": "home/design-tokens/typography",
+    "tags": [
+      "text",
+      "headings",
+      "strong",
+      "bold",
+      "italic",
+      "emphasize"
+    ],
+    "toc": [
+      {
+        "value": "Text Styles",
+        "href": "#text-styles",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Available Text Styles",
+        "href": "#available-text-styles",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Fonts",
+        "href": "#fonts",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Font Sizes",
+        "href": "#font-sizes",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Font Weights",
+        "href": "#font-weights",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Letter Spacings",
+        "href": "#letter-spacings",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Line Heights",
+        "href": "#line-heights",
+        "depth": 2,
+        "numbering": [
+          1,
+          6
+        ],
+        "parent": "root"
+      }
+    ],
+    "icon": "FormatSize",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Typography\n\nBelow you'll find the raw tokens to change typography styles on a text-element.\n\n## Text Styles\n\nText styles are collections of multiple typography rules (such as `font-size`,\n`line-height`, `letter-spacing` etc.) that create a specific, reusable style.\n\n> [!NOTE]  \n> I added `caption`, `detail` & `body` from our existing styles, but they are\n> essentially just combinations of font-size & line-height and can be mapped to\n> `xs`, `sm` & `md`. The `headline` looks can be achieved by using the\n> textStyles on the `<Heading/>` component.\n\n```jsx\n<Text textStyle=\"nameOfDesiredTextStyle\">Heading 1</Text>\n```\n\n### Available Text Styles\n\n<TextStylesDemo />\n\n## Fonts\n\n<GenericTokenTableDemo category=\"fonts\" demoProperty=\"fontFamily\" />\n\n## Font Sizes\n\n<GenericTokenTableDemo category=\"fontSizes\" demoProperty=\"fontSize\" />\n\n## Font Weights\n\n<GenericTokenTableDemo category=\"fontWeights\" demoProperty=\"fontWeight\" />\n\n## Letter Spacings\n\n<GenericTokenTableDemo category=\"letterSpacings\" demoProperty=\"letterSpacing\" />\n\n## Line Heights\n\n<GenericTokenTableDemo category=\"lineHeights\" demoProperty=\"lineHeight\" />\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Typography\n\nBelow you'll find the raw tokens to change typography styles on a text-element.\n\n## Text Styles\n\nText styles are collections of multiple typography rules (such as `font-size`,\n`line-height`, `letter-spacing` etc.) that create a specific, reusable style.\n\n> [!NOTE]  \n> I added `caption`, `detail` & `body` from our existing styles, but they are\n> essentially just combinations of font-size & line-height and can be mapped to\n> `xs`, `sm` & `md`. The `headline` looks can be achieved by using the\n> textStyles on the `<Heading/>` component.\n\n```jsx\n<Text textStyle=\"nameOfDesiredTextStyle\">Heading 1</Text>\n```\n\n### Available Text Styles\n\n<TextStylesDemo />\n\n## Fonts\n\n<GenericTokenTableDemo category=\"fonts\" demoProperty=\"fontFamily\" />\n\n## Font Sizes\n\n<GenericTokenTableDemo category=\"fontSizes\" demoProperty=\"fontSize\" />\n\n## Font Weights\n\n<GenericTokenTableDemo category=\"fontWeights\" demoProperty=\"fontWeight\" />\n\n## Letter Spacings\n\n<GenericTokenTableDemo category=\"letterSpacings\" demoProperty=\"letterSpacing\" />\n\n## Line Heights\n\n<GenericTokenTableDemo category=\"lineHeights\" demoProperty=\"lineHeight\" />\n",
+      "toc": [
+        {
+          "value": "Text Styles",
+          "href": "#text-styles",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Available Text Styles",
+          "href": "#available-text-styles",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Fonts",
+          "href": "#fonts",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Font Sizes",
+          "href": "#font-sizes",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Font Weights",
+          "href": "#font-weights",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Letter Spacings",
+          "href": "#letter-spacings",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Line Heights",
+          "href": "#line-heights",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

package/data/docs/routes/home-design-tokens.json

@@ -0,0 +1,34 @@
+{
+  "meta": {
+    "id": "DesignTokens",
+    "title": "Design Tokens",
+    "description": "Style definitions (colors, fonts, spacing, etc.) for consistent UI components.",
+    "order": 2,
+    "repoPath": "packages/nimbus/src/docs/tokens.mdx",
+    "menu": [
+      "Home",
+      "Design Tokens"
+    ],
+    "route": "home/design-tokens",
+    "tags": [
+      "tokens",
+      "design"
+    ],
+    "toc": [],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Design Tokens\n\n<CategoryOverview />\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Design Tokens\n\n<CategoryOverview />\n",
+      "toc": []
+    }
+  }
+}

package/data/docs/routes/home-getting-started-core-concepts.json

@@ -0,0 +1,301 @@
+{
+  "meta": {
+    "id": "Home-Core Concepts",
+    "title": "Core Concepts",
+    "description": "Quick start guide to set up and use the package.",
+    "order": 2,
+    "repoPath": "packages/nimbus/src/docs/home-core-concepts.mdx",
+    "menu": [
+      "Home",
+      "Getting Started",
+      "Core Concepts"
+    ],
+    "route": "home/getting-started/core-concepts",
+    "tags": [
+      "document"
+    ],
+    "toc": [
+      {
+        "value": "Technical foundation",
+        "href": "#technical-foundation",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Core Concepts",
+        "href": "#core-concepts-1",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "1. NimbusProvider",
+        "href": "#1-nimbusprovider",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "2. Component Types",
+        "href": "#2-component-types",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Primitive Components",
+        "href": "#primitive-components",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Compound Components",
+        "href": "#compound-components",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "3. Design Tokens",
+        "href": "#3-design-tokens",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "4. Style Props",
+        "href": "#4-style-props",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "5. Polymorphism",
+        "href": "#5-polymorphism",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "6. Theming",
+        "href": "#6-theming",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          6
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "7. Responsive Styling",
+        "href": "#7-responsive-styling",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          7
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "8. Using Icons",
+        "href": "#8-using-icons",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          8
+        ],
+        "parent": "root"
+      }
+    ],
+    "icon": "LocalLibrary",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Core concepts\n\nThis page is designed to help you understand the foundational concepts so that\nyou can get quickly started with using the Nimbus Design System in your\nprojects.\n\nNimbus aims to provide a comprehensive suite of accessible and pre-themed React components, enabling developers to build beautiful and consistent user interfaces with ease. However, it's important to understand the following underlying concepts to make the most of the system.\n\n## Technical foundation\n\n- Nimbus is a [`react`](https://react.dev/) component library built to provide a\n  consistent and accessible design system.\n- Under the hood, it leverages the power of CSS-in-JS through\n  [`@emotion/react`](https://emotion.sh/)\n- For its styling and theming capabilities, Nimbus utilizes\n  [Chakra UI](https://chakra-ui.com/).\n- For all components that are requiring user-interaction Nimbus is making use of\n  suitable [`react-aria`](https://react-spectrum.adobe.com/react-aria/)\n  components or hooks to guarantee enterprise-grade accessibility.\n\n## Core Concepts\n\nTo effectively use the Nimbus Design System, it's helpful to understand the\nfollowing core concepts:\n\n### 1. NimbusProvider\n\nAt the root of your application, you'll need to include the `NimbusProvider`.\nThis component is essential as it provides the theme (colors, spacing,\ntypography, etc.) and other context necessary for all Nimbus components to\nfunction correctly.\n\n```tsx\nimport { NimbusProvider } from \"@commercetools/nimbus\";\nimport { YourApp } from \"./you-app\";\n\nfunction App() {\n  return (\n    <NimbusProvider>\n      <YourApp />\n    </NimbusProvider>\n  );\n}\n\nexport default App;\n```\n\n### 2. Component Types\n\nNimbus offers a rich library of pre-built UI components that you can use to\nconstruct your application's interface. These components are designed to be\naccessible, customizable, and consistent with the Nimbus design language.\n\nWe differentiate between two types of components:\n\n#### Primitive Components\n\nThese are fundamental building blocks, often representing a single HTML element\nor a very simple UI concept. They are designed to be used on their own or\ncomposed to create more complex UIs.\n\nExamples: `Button`, `Box`, `Flex`, `Text`, `Heading`, `Icon`.\n\n```tsx\nimport { Stack, Heading, Text, Button } from \"@commercetools/nimbus\";\n\nfunction MyPrimitiveExample() {\n  return (\n    <Stack>\n      <Heading>This is a heading</Heading>\n      <Text>This is a paragraph of text.</Text>\n      <Button>Click me</Button>\n    </Stack>\n  );\n}\n```\n\n#### Compound Components\n\nThese components are more complex and are typically made up of several distinct\nparts that work together to provide a piece of functionality. They often manage\ninternal state or have a specific structure.\n\nExamples: `Alert`, `Card`, `Grid`, `Select`, `Accordion`, `Table`.\n\nWhen using compound components, you'll import multiple related components at\nonce. For instance, with `Select`, you might use `Select.Root`,\n`Select.Options`, `Select.Option`, etc.\n\n```tsx\nimport { Select } from \"@commercetools/nimbus\"; // Assuming Select is a top-level import\n\nfunction MySelectExample() {\n  return (\n    <Select.Root placeholder=\"Select a fruit\">\n      <Select.Options>\n        <Select.Option>Apples</Select.Option>\n        <Select.Option>Bananas</Select.Option>\n        <Select.Option>Oranges</Select.Option>\n        <Select.Option>Cherries</Select.Option>\n      </Select.Options>\n    </Select.Root>\n  );\n}\n```\n\n### 3. Design Tokens\n\nAt the heart of Nimbus's theming capabilities are **Design Tokens**. These are\nnamed entities that store indivisible pieces of the visual design, such as\nspecific colors, spacing units, font sizes, border radii, etc. Instead of\nhardcoding a hex value like `#007bff` or a pixel value like `16px`, you simply\nuse a token.\n\nDesign tokens are organized by their **purpose** and map to one or more\nstyle-props.\n\n- **Color Tokens**: For any property that accepts a color value, like\n  `backgroundColor`, `color`, `borderColor`.\n- **Spacing Tokens**: Exclusively for properties that define space, such as\n  `padding`, `margin`, `gap`, `top`, `left`, etc.\n- **Size Tokens** : Used for `width`, `height`, `minWidth`, `maxWidth`,\n  `minHeight`, `maxHeight`.\n- **Typography Tokens**: For text-related style props like `fontSize`,\n  `fontWeight`, `lineHeight`.\n- etc.\n\nAll Nimbus components are fundamentally built using these design tokens.\n\n### 4. Style Props\n\nFor direct and granular CSS control, many Nimbus components expose **Style\nProps**. These props are typically named after their corresponding CSS\nproperties (e.g., `backgroundColor`, `padding`, `margin`, `width`, `display`,\n`alignItems`).\n\nThe key advantage of using Nimbus Style Props over inline `style` attributes is\ntheir direct integration with the **Design Token** system (see the\n[Design Tokens](#3-design-tokens) section). You should primarily use Design\nTokens as values for these props. This ensures that even fine-grained\nadjustments remain consistent with the overall design system and are easily\nmaintainable.\n\nStyle props are excellent for:\n\n- Making specific layout adjustments\n- Applying a specific color from the token palette directly (e.g.,\n  `color=\"primary.11\"`).\n- Overriding a particular aspect of a component's appearance when a more general\n  theming prop (like `variant` or `colorPalette`) doesn't cover the specific need, or\n  when a highly localized, one-off style is required.\n\n```tsx\nimport { Box, Text } from \"@commercetools/nimbus\";\n\nfunction CustomTextInBox() {\n  return (\n    <Box\n      padding=\"400\" // Design token for padding, comming from the spacing tokens\n      backgroundColor=\"primary.2\" // Design token for color, comming from the color tokens\n      border=\"solid-25\" // Token for borders\n      borderRadius=\"full\" // Design token for radii\n    >\n      <Text color=\"primary.11\" fontSize=\"1200\" fontWeight=\"500\">\n        This box uses Style Props with Design Tokens for custom styling.\n      </Text>\n    </Box>\n  );\n}\n```\n\nWhile Style Props offer great flexibility, it's generally recommended to use\nstandard theming props (discussed in the\n[Theming and Styling](#6-theming-and-styling) section) for common styling\nscenarios. Reserve Style Props for situations requiring specific, low-level\ncontrol, always pairing them with Design Tokens to maintain consistency.\n\n### 5. Polymorphism\n\nMany Nimbus components, particularly Primitive Components, support polymorphism.\nThis powerful feature allows you to change the underlying HTML element a\ncomponent renders to the DOM while retaining its established styling and\nbehavior. This is primarily achieved through the `as` or `asChild` props.\n\n- The `as` prop directly changes the rendered HTML tag. For example, a `Text`\n  component, which might render a `<span>` by default, can be changed to render\n  a `<p>` or an `<em>` tag:\n\n  ```tsx\n  import { Text } from \"@commercetools/nimbus\";\n\n  <Text as=\"p\">This text will be rendered as a paragraph.</Text>\n  <Text as=\"span\">This text will be rendered as a span.</Text>\n  ```\n\n- The `asChild` prop offers a more advanced way to handle polymorphism. It\n  allows a Nimbus component to delegate its rendering to a single child\n  component. When `asChild` is true, the Nimbus component itself doesn't render\n  a DOM element; instead, it clones its child and merges its own props (like\n  styles and event handlers) onto the child. This is incredibly useful for\n  applying Nimbus styling and behavior to an existing component (e.g., a `Link`\n  from a routing library) without altering the child's core functionality or\n  prop structure. It ensures that the child retains its own capabilities while\n  seamlessly integrating the parent's visual attributes.\n\n  ```tsx\n  import { Button } from \"@commercetools/nimbus\";\n  import { Link } from \"your-router-library\"; // Fictional router Link\n\n  <Button variant=\"solid\" colorPalette=\"primary\" asChild>\n    <Link to=\"/some-page\">Navigate</Link>\n  </Button>;\n\n  // = the Button's styles and behaviors are applied to the Link\n  ```\n\n  While most common in Primitive Components, some Compound Components might also\n  offer polymorphic capabilities where appropriate.\n\n### 6. Theming\n\nNimbus components derive their appearance from the underlying\n[Design Tokens](#3-design-tokens). Beyond direct styling with\n[Style Props](#4-style-props), components offer dedicated **theming props** to\napply common, pre-defined visual treatments.\n\nThese theming props are the primary way to align components with the established\nNimbus design language and ensure a consistent look and feel. They encapsulate\nsets of styles related to a component's variants, sizes, or semantic `colorPalette`s.\n\nCommon theming props include:\n\n- `variant`: Often dictates the overall style of a component (e.g., `solid`,\n  `outline`, `ghost`).\n- `size`: Controls the dimensions of the component (e.g., `sm`, `md`, `lg`).\n- `textStyle`: Specifically for text-based components like `Text` or `Heading`,\n  this prop applies a predefined typographic style (which includes font size,\n  weight, line height, etc.) like `body`, `caption`, `h1`, etc.\n- `colorPalette`: This prop is used to apply a specific color scheme to a\n  component when the color isn't necessarily tied to a semantic meaning (like\n  `success` or `warning`). Instead, it offers a way to achieve visual variation\n  or categorization. For example, a `Badge` component might use `colorPalette`\n  to offer various background and text color combinations (e.g., \"blue\",\n  \"green\", \"purple\", \"orange\") for purely aesthetic purposes or to group items\n  by a non-semantic color.\n\n```tsx\nimport { Button, Text, Card, Badge } from \"@commercetools/nimbus\";\n\nfunction ThemedComponents() {\n  return (\n    <>\n      <Text textStyle=\"caption\">I look like a caption</Text>\n      <Button variant=\"solid\" colorPalette=\"primary\" size=\"lg\">\n        Large Primary Button\n      </Button>\n      <Button variant=\"outline\" colorPalette=\"critical\" size=\"xs\">\n        xSmall Critical Outline\n      </Button>\n      <Badge colorPalette=\"blue\">Blue Badge</Badge>\n      <Badge colorPalette=\"purple\">Purple Badge</Badge>\n    </>\n  );\n}\n```\n\n### 7. Responsive Styling\n\nNimbus components are designed to be responsive, allowing you to adapt their\nstyles for different screen sizes. This is typically achieved by providing an an\nobject to [Style Props](#4-style-props) or some theming props.\n\nThe [breakpoints](/tokens/other/breakpoints) (e.g., `sm`, `md`, `lg`, `xl`,\n`2xl`) used for responsive styling are defined within the theme provided by\n`NimbusProvider`.\n\nThe `base` key is the default value that applies if no screen size matches.\n\n```tsx\nimport { Stack, Text } from \"@commercetools/nimbus\";\n\nfunction ResponsiveStack() {\n  return (\n    <Stack\n      direction={{ base: \"column\", md: \"row\" }} // Column on mobile, row on medium screens and up\n      padding={{ base: \"400\", lg: \"600\" }} // Different padding for small vs large screens\n      gap=\"400\"\n    >\n      <Text>Item 1</Text>\n      <Text>Item 2</Text>\n    </Stack>\n  );\n}\n```\n\nThis approach allows for intuitive and declarative responsive design directly\nwithin your component's props.\n\n### 8. Using Icons\n\nThe `@nimbus/icons` package provides a large set of icons optimized for use with\nNimbus components. These icons can be easily integrated to enhance the visual\ncommunication of your interface. They will adapt to the context they are used in\nby default and allow for easy customization when used in combination with the\nIcon component.\n\nTo use an icon, import it from `@commercetools/nimbus-icons` and use it like any\nother React component.\n\n```tsx\nimport { Button } from \"@commercetools/nimbus\";\nimport { IconCheckCircle } from \"@commercetools/nimbus-icons\";\n\nfunction ComponentsWithIcons() {\n  return (\n    <Button variant=\"solid\" colorPalette=\"primary\">\n      <IconCheckCircle /> Submit\n    </Button>\n  );\n}\n```\n\nFor more granular control over icon appearance, you can use the `Icon` component \nfrom Nimbus to customize properties such as size, color, and other style \nattributes. This component wraps the imported icons and allows them to be styled \nconsistently with the design system's tokens.\n\n```tsx\nimport { Icon, Box } from \"@commercetools/nimbus\";\nimport { IconEdit, IconDelete } from \"@commercetools/nimbus-icons\";\n\nfunction CustomizedIcons() {\n  return (\n    <Box display=\"flex\" gap=\"400\">\n      {/* Customize icon size */}\n      <Icon as={IconEdit} boxSize=\"800\" />\n      \n      {/* Customize icon color */}\n      <Icon as={IconDelete} color=\"critical.9\" />\n      \n      {/* Apply multiple style properties */}\n      <Icon\n        as={IconEdit}\n        boxSize=\"1000\"\n        color=\"primary.11\"\n        opacity=\"0.8\"\n        transition=\"all 0.2s\"\n        _hover={{ opacity: \"1\", transform: \"scale(1.1)\" }}\n      />\n    </Box>\n  );\n}\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Core concepts\n\nThis page is designed to help you understand the foundational concepts so that\nyou can get quickly started with using the Nimbus Design System in your\nprojects.\n\nNimbus aims to provide a comprehensive suite of accessible and pre-themed React components, enabling developers to build beautiful and consistent user interfaces with ease. However, it's important to understand the following underlying concepts to make the most of the system.\n\n## Technical foundation\n\n- Nimbus is a [`react`](https://react.dev/) component library built to provide a\n  consistent and accessible design system.\n- Under the hood, it leverages the power of CSS-in-JS through\n  [`@emotion/react`](https://emotion.sh/)\n- For its styling and theming capabilities, Nimbus utilizes\n  [Chakra UI](https://chakra-ui.com/).\n- For all components that are requiring user-interaction Nimbus is making use of\n  suitable [`react-aria`](https://react-spectrum.adobe.com/react-aria/)\n  components or hooks to guarantee enterprise-grade accessibility.\n\n## Core Concepts\n\nTo effectively use the Nimbus Design System, it's helpful to understand the\nfollowing core concepts:\n\n### 1. NimbusProvider\n\nAt the root of your application, you'll need to include the `NimbusProvider`.\nThis component is essential as it provides the theme (colors, spacing,\ntypography, etc.) and other context necessary for all Nimbus components to\nfunction correctly.\n\n```tsx\nimport { NimbusProvider } from \"@commercetools/nimbus\";\nimport { YourApp } from \"./you-app\";\n\nfunction App() {\n  return (\n    <NimbusProvider>\n      <YourApp />\n    </NimbusProvider>\n  );\n}\n\nexport default App;\n```\n\n### 2. Component Types\n\nNimbus offers a rich library of pre-built UI components that you can use to\nconstruct your application's interface. These components are designed to be\naccessible, customizable, and consistent with the Nimbus design language.\n\nWe differentiate between two types of components:\n\n#### Primitive Components\n\nThese are fundamental building blocks, often representing a single HTML element\nor a very simple UI concept. They are designed to be used on their own or\ncomposed to create more complex UIs.\n\nExamples: `Button`, `Box`, `Flex`, `Text`, `Heading`, `Icon`.\n\n```tsx\nimport { Stack, Heading, Text, Button } from \"@commercetools/nimbus\";\n\nfunction MyPrimitiveExample() {\n  return (\n    <Stack>\n      <Heading>This is a heading</Heading>\n      <Text>This is a paragraph of text.</Text>\n      <Button>Click me</Button>\n    </Stack>\n  );\n}\n```\n\n#### Compound Components\n\nThese components are more complex and are typically made up of several distinct\nparts that work together to provide a piece of functionality. They often manage\ninternal state or have a specific structure.\n\nExamples: `Alert`, `Card`, `Grid`, `Select`, `Accordion`, `Table`.\n\nWhen using compound components, you'll import multiple related components at\nonce. For instance, with `Select`, you might use `Select.Root`,\n`Select.Options`, `Select.Option`, etc.\n\n```tsx\nimport { Select } from \"@commercetools/nimbus\"; // Assuming Select is a top-level import\n\nfunction MySelectExample() {\n  return (\n    <Select.Root placeholder=\"Select a fruit\">\n      <Select.Options>\n        <Select.Option>Apples</Select.Option>\n        <Select.Option>Bananas</Select.Option>\n        <Select.Option>Oranges</Select.Option>\n        <Select.Option>Cherries</Select.Option>\n      </Select.Options>\n    </Select.Root>\n  );\n}\n```\n\n### 3. Design Tokens\n\nAt the heart of Nimbus's theming capabilities are **Design Tokens**. These are\nnamed entities that store indivisible pieces of the visual design, such as\nspecific colors, spacing units, font sizes, border radii, etc. Instead of\nhardcoding a hex value like `#007bff` or a pixel value like `16px`, you simply\nuse a token.\n\nDesign tokens are organized by their **purpose** and map to one or more\nstyle-props.\n\n- **Color Tokens**: For any property that accepts a color value, like\n  `backgroundColor`, `color`, `borderColor`.\n- **Spacing Tokens**: Exclusively for properties that define space, such as\n  `padding`, `margin`, `gap`, `top`, `left`, etc.\n- **Size Tokens** : Used for `width`, `height`, `minWidth`, `maxWidth`,\n  `minHeight`, `maxHeight`.\n- **Typography Tokens**: For text-related style props like `fontSize`,\n  `fontWeight`, `lineHeight`.\n- etc.\n\nAll Nimbus components are fundamentally built using these design tokens.\n\n### 4. Style Props\n\nFor direct and granular CSS control, many Nimbus components expose **Style\nProps**. These props are typically named after their corresponding CSS\nproperties (e.g., `backgroundColor`, `padding`, `margin`, `width`, `display`,\n`alignItems`).\n\nThe key advantage of using Nimbus Style Props over inline `style` attributes is\ntheir direct integration with the **Design Token** system (see the\n[Design Tokens](#3-design-tokens) section). You should primarily use Design\nTokens as values for these props. This ensures that even fine-grained\nadjustments remain consistent with the overall design system and are easily\nmaintainable.\n\nStyle props are excellent for:\n\n- Making specific layout adjustments\n- Applying a specific color from the token palette directly (e.g.,\n  `color=\"primary.11\"`).\n- Overriding a particular aspect of a component's appearance when a more general\n  theming prop (like `variant` or `colorPalette`) doesn't cover the specific need, or\n  when a highly localized, one-off style is required.\n\n```tsx\nimport { Box, Text } from \"@commercetools/nimbus\";\n\nfunction CustomTextInBox() {\n  return (\n    <Box\n      padding=\"400\" // Design token for padding, comming from the spacing tokens\n      backgroundColor=\"primary.2\" // Design token for color, comming from the color tokens\n      border=\"solid-25\" // Token for borders\n      borderRadius=\"full\" // Design token for radii\n    >\n      <Text color=\"primary.11\" fontSize=\"1200\" fontWeight=\"500\">\n        This box uses Style Props with Design Tokens for custom styling.\n      </Text>\n    </Box>\n  );\n}\n```\n\nWhile Style Props offer great flexibility, it's generally recommended to use\nstandard theming props (discussed in the\n[Theming and Styling](#6-theming-and-styling) section) for common styling\nscenarios. Reserve Style Props for situations requiring specific, low-level\ncontrol, always pairing them with Design Tokens to maintain consistency.\n\n### 5. Polymorphism\n\nMany Nimbus components, particularly Primitive Components, support polymorphism.\nThis powerful feature allows you to change the underlying HTML element a\ncomponent renders to the DOM while retaining its established styling and\nbehavior. This is primarily achieved through the `as` or `asChild` props.\n\n- The `as` prop directly changes the rendered HTML tag. For example, a `Text`\n  component, which might render a `<span>` by default, can be changed to render\n  a `<p>` or an `<em>` tag:\n\n  ```tsx\n  import { Text } from \"@commercetools/nimbus\";\n\n  <Text as=\"p\">This text will be rendered as a paragraph.</Text>\n  <Text as=\"span\">This text will be rendered as a span.</Text>\n  ```\n\n- The `asChild` prop offers a more advanced way to handle polymorphism. It\n  allows a Nimbus component to delegate its rendering to a single child\n  component. When `asChild` is true, the Nimbus component itself doesn't render\n  a DOM element; instead, it clones its child and merges its own props (like\n  styles and event handlers) onto the child. This is incredibly useful for\n  applying Nimbus styling and behavior to an existing component (e.g., a `Link`\n  from a routing library) without altering the child's core functionality or\n  prop structure. It ensures that the child retains its own capabilities while\n  seamlessly integrating the parent's visual attributes.\n\n  ```tsx\n  import { Button } from \"@commercetools/nimbus\";\n  import { Link } from \"your-router-library\"; // Fictional router Link\n\n  <Button variant=\"solid\" colorPalette=\"primary\" asChild>\n    <Link to=\"/some-page\">Navigate</Link>\n  </Button>;\n\n  // = the Button's styles and behaviors are applied to the Link\n  ```\n\n  While most common in Primitive Components, some Compound Components might also\n  offer polymorphic capabilities where appropriate.\n\n### 6. Theming\n\nNimbus components derive their appearance from the underlying\n[Design Tokens](#3-design-tokens). Beyond direct styling with\n[Style Props](#4-style-props), components offer dedicated **theming props** to\napply common, pre-defined visual treatments.\n\nThese theming props are the primary way to align components with the established\nNimbus design language and ensure a consistent look and feel. They encapsulate\nsets of styles related to a component's variants, sizes, or semantic `colorPalette`s.\n\nCommon theming props include:\n\n- `variant`: Often dictates the overall style of a component (e.g., `solid`,\n  `outline`, `ghost`).\n- `size`: Controls the dimensions of the component (e.g., `sm`, `md`, `lg`).\n- `textStyle`: Specifically for text-based components like `Text` or `Heading`,\n  this prop applies a predefined typographic style (which includes font size,\n  weight, line height, etc.) like `body`, `caption`, `h1`, etc.\n- `colorPalette`: This prop is used to apply a specific color scheme to a\n  component when the color isn't necessarily tied to a semantic meaning (like\n  `success` or `warning`). Instead, it offers a way to achieve visual variation\n  or categorization. For example, a `Badge` component might use `colorPalette`\n  to offer various background and text color combinations (e.g., \"blue\",\n  \"green\", \"purple\", \"orange\") for purely aesthetic purposes or to group items\n  by a non-semantic color.\n\n```tsx\nimport { Button, Text, Card, Badge } from \"@commercetools/nimbus\";\n\nfunction ThemedComponents() {\n  return (\n    <>\n      <Text textStyle=\"caption\">I look like a caption</Text>\n      <Button variant=\"solid\" colorPalette=\"primary\" size=\"lg\">\n        Large Primary Button\n      </Button>\n      <Button variant=\"outline\" colorPalette=\"critical\" size=\"xs\">\n        xSmall Critical Outline\n      </Button>\n      <Badge colorPalette=\"blue\">Blue Badge</Badge>\n      <Badge colorPalette=\"purple\">Purple Badge</Badge>\n    </>\n  );\n}\n```\n\n### 7. Responsive Styling\n\nNimbus components are designed to be responsive, allowing you to adapt their\nstyles for different screen sizes. This is typically achieved by providing an an\nobject to [Style Props](#4-style-props) or some theming props.\n\nThe [breakpoints](/tokens/other/breakpoints) (e.g., `sm`, `md`, `lg`, `xl`,\n`2xl`) used for responsive styling are defined within the theme provided by\n`NimbusProvider`.\n\nThe `base` key is the default value that applies if no screen size matches.\n\n```tsx\nimport { Stack, Text } from \"@commercetools/nimbus\";\n\nfunction ResponsiveStack() {\n  return (\n    <Stack\n      direction={{ base: \"column\", md: \"row\" }} // Column on mobile, row on medium screens and up\n      padding={{ base: \"400\", lg: \"600\" }} // Different padding for small vs large screens\n      gap=\"400\"\n    >\n      <Text>Item 1</Text>\n      <Text>Item 2</Text>\n    </Stack>\n  );\n}\n```\n\nThis approach allows for intuitive and declarative responsive design directly\nwithin your component's props.\n\n### 8. Using Icons\n\nThe `@nimbus/icons` package provides a large set of icons optimized for use with\nNimbus components. These icons can be easily integrated to enhance the visual\ncommunication of your interface. They will adapt to the context they are used in\nby default and allow for easy customization when used in combination with the\nIcon component.\n\nTo use an icon, import it from `@commercetools/nimbus-icons` and use it like any\nother React component.\n\n```tsx\nimport { Button } from \"@commercetools/nimbus\";\nimport { IconCheckCircle } from \"@commercetools/nimbus-icons\";\n\nfunction ComponentsWithIcons() {\n  return (\n    <Button variant=\"solid\" colorPalette=\"primary\">\n      <IconCheckCircle /> Submit\n    </Button>\n  );\n}\n```\n\nFor more granular control over icon appearance, you can use the `Icon` component \nfrom Nimbus to customize properties such as size, color, and other style \nattributes. This component wraps the imported icons and allows them to be styled \nconsistently with the design system's tokens.\n\n```tsx\nimport { Icon, Box } from \"@commercetools/nimbus\";\nimport { IconEdit, IconDelete } from \"@commercetools/nimbus-icons\";\n\nfunction CustomizedIcons() {\n  return (\n    <Box display=\"flex\" gap=\"400\">\n      {/* Customize icon size */}\n      <Icon as={IconEdit} boxSize=\"800\" />\n      \n      {/* Customize icon color */}\n      <Icon as={IconDelete} color=\"critical.9\" />\n      \n      {/* Apply multiple style properties */}\n      <Icon\n        as={IconEdit}\n        boxSize=\"1000\"\n        color=\"primary.11\"\n        opacity=\"0.8\"\n        transition=\"all 0.2s\"\n        _hover={{ opacity: \"1\", transform: \"scale(1.1)\" }}\n      />\n    </Box>\n  );\n}\n```\n",
+      "toc": [
+        {
+          "value": "Technical foundation",
+          "href": "#technical-foundation",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Core Concepts",
+          "href": "#core-concepts-1",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "1. NimbusProvider",
+          "href": "#1-nimbusprovider",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "2. Component Types",
+          "href": "#2-component-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Primitive Components",
+          "href": "#primitive-components",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Compound Components",
+          "href": "#compound-components",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "3. Design Tokens",
+          "href": "#3-design-tokens",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "4. Style Props",
+          "href": "#4-style-props",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "5. Polymorphism",
+          "href": "#5-polymorphism",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "6. Theming",
+          "href": "#6-theming",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "7. Responsive Styling",
+          "href": "#7-responsive-styling",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "8. Using Icons",
+          "href": "#8-using-icons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}