@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/data/docs/routes/components-typography-text.json

@@ -0,0 +1,444 @@
+{
+  "meta": {
+    "id": "Components-Text",
+    "title": "Text",
+    "exportName": "Text",
+    "description": "Text styles are predefined collections of typography rules (including font-size, font-weight, line-height, and letter-spacing) that create reusable, consistent styles.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/text/text.mdx",
+    "menu": [
+      "Components",
+      "Typography",
+      "Text"
+    ],
+    "route": "components/typography/text",
+    "tags": [
+      "component",
+      "typography",
+      "text"
+    ],
+    "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": "Typography scale and hierarchy",
+        "href": "#typography-scale-and-hierarchy",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Text tones and semantic coloring",
+        "href": "#text-tones-and-semantic-coloring",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=6041-23913&m=dev",
+    "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\nReadable and consistent text styling is important to creating effective user\nfriendly and efficient products. These styles and tools will help give the\nbuilding blocks and provide more options for creation, and there are still ways\nto allow for customization for the rare cases it is needed.\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=6041-23913&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Typography scale and hierarchy\n\nText styles here are recommended for most body styled text, and made to fit well\nwith component sizes. If you need to render large, bold text with a semantic\nmeaning, you should use the heading component instead.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Box>\n      <Text as=\"span\" textStyle=\"md\">Paragraph md</Text>\n      <Text as=\"span\"> - Primary body text, long descriptions, standard content blocks.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" textStyle=\"sm\">Paragraph sm</Text>\n      <Text as=\"span\"> - Secondary text, metadata, table content.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" textStyle=\"xs\">Paragraph xs</Text>\n      <Text as=\"span\"> - Tertiary content, small notes, timestamps.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" textStyle=\"caption\">CAPTION</Text>\n      <Text as=\"span\"> - Used for specialized, tracked metadata. (Includes letter-spacing: 1px).</Text>\n    </Box>\n  </Stack>\n)\n```\n\n### Text tones and semantic coloring\n\nText tones use color to semantically convey status, intent, or hierarchy. The\ndefault tone is used for the majority of UI text.\n\n**Color Rule:** All colored font-color is always set to step 11 of the given\ncolor scale (e.g., tomato.11, indigo.11). This ensures high contrast and\naccessibility.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Box>\n      <Text as=\"span\" color=\"fg\">Default tone</Text>\n      <Text as=\"span\"> - Standard body copy, primary content.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"fg.subtle\">Secondary</Text>\n      <Text as=\"span\"> - Helper text, metadata, inactive or less important UI elements.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"primary.11\">Primary</Text>\n      <Text as=\"span\"> - Mainly used for links or branded messages.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"info.11\">Info</Text>\n      <Text as=\"span\"> - Non-critical feedback, system messages.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"positive.11\">Positive</Text>\n      <Text as=\"span\"> - Successful actions, positive status indicators (e.g., \"Complete,\" \"Saved\").</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"critical.11\">Critical</Text>\n      <Text as=\"span\"> - Validation errors, destructive warnings, critical status indicators.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"warning.11\">Warning</Text>\n      <Text as=\"span\"> - Warnings, temporary issues, actions requiring review.</Text>\n    </Box>\n  </Stack>\n)\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nReadable and consistent text styling is important to creating effective user\nfriendly and efficient products. These styles and tools will help give the\nbuilding blocks and provide more options for creation, and there are still ways\nto allow for customization for the rare cases it is needed.\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=6041-23913&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Typography scale and hierarchy\n\nText styles here are recommended for most body styled text, and made to fit well\nwith component sizes. If you need to render large, bold text with a semantic\nmeaning, you should use the heading component instead.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Box>\n      <Text as=\"span\" textStyle=\"md\">Paragraph md</Text>\n      <Text as=\"span\"> - Primary body text, long descriptions, standard content blocks.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" textStyle=\"sm\">Paragraph sm</Text>\n      <Text as=\"span\"> - Secondary text, metadata, table content.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" textStyle=\"xs\">Paragraph xs</Text>\n      <Text as=\"span\"> - Tertiary content, small notes, timestamps.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" textStyle=\"caption\">CAPTION</Text>\n      <Text as=\"span\"> - Used for specialized, tracked metadata. (Includes letter-spacing: 1px).</Text>\n    </Box>\n  </Stack>\n)\n```\n\n### Text tones and semantic coloring\n\nText tones use color to semantically convey status, intent, or hierarchy. The\ndefault tone is used for the majority of UI text.\n\n**Color Rule:** All colored font-color is always set to step 11 of the given\ncolor scale (e.g., tomato.11, indigo.11). This ensures high contrast and\naccessibility.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Box>\n      <Text as=\"span\" color=\"fg\">Default tone</Text>\n      <Text as=\"span\"> - Standard body copy, primary content.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"fg.subtle\">Secondary</Text>\n      <Text as=\"span\"> - Helper text, metadata, inactive or less important UI elements.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"primary.11\">Primary</Text>\n      <Text as=\"span\"> - Mainly used for links or branded messages.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"info.11\">Info</Text>\n      <Text as=\"span\"> - Non-critical feedback, system messages.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"positive.11\">Positive</Text>\n      <Text as=\"span\"> - Successful actions, positive status indicators (e.g., \"Complete,\" \"Saved\").</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"critical.11\">Critical</Text>\n      <Text as=\"span\"> - Validation errors, destructive warnings, critical status indicators.</Text>\n    </Box>\n    <Box>\n      <Text as=\"span\" color=\"warning.11\">Warning</Text>\n      <Text as=\"span\"> - Warnings, temporary issues, actions requiring review.</Text>\n    </Box>\n  </Stack>\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": "Typography scale and hierarchy",
+          "href": "#typography-scale-and-hierarchy",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Text tones and semantic coloring",
+          "href": "#text-tones-and-semantic-coloring",
+          "depth": 3,
+          "numbering": [
+            1,
+            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  <Stack direction=\"column\" gap=\"400\">\n    <Text as=\"h2\" fontSize=\"600\" fontWeight=\"700\">Header text</Text>\n    <Text>Body text</Text>\n    <Text textTransform=\"uppercase\" letterSpacing=\"1px\" fontSize=\"350\">CAPTIONS</Text>\n  </Stack>\n)\n```\n\n### Accessibility standards\n\n- **Contrast:** The explicit rule of using color step 11 for colored text\n  ensures that colored text meets or exceeds minimum WCAG contrast ratios\n  against light backgrounds.\n- **Semantic HTML:** Ensure that text styles map correctly to semantic HTML tags\n  (e.g., Headlines should use `<h1>` through `<h6>`).\n- **Truncation:** For long body copy or component-specific labels, define clear\n  rules for truncation (using ellipses) and ensure a tooltip reveals the full\n  text on hover/focus.\n- **Avoid overlap:** Never overlap text elements or place complex colored\n  backgrounds behind text, as this voids the consistent contrast guaranteed by\n  the defined color scale.\n- **Scale usage:** Only use component-specific styles (e.g., button md) for\n  their intended purpose; do not use them to style arbitrary body text.\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"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Text, type TextProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation renders a paragraph element with default styling:\n\n```jsx live-dev\nconst App = () => {\n  return <Text>This is basic text content.</Text>;\n};\n```\n\n## Usage examples\n\n### Typography scale\n\nThe `textStyle` prop applies predefined typography styles from the design system. These styles include font-size, line-height, and letter-spacing optimized for readability:\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text textStyle=\"md\">Paragraph md - Primary body text, long descriptions</Text>\n      <Text textStyle=\"sm\">Paragraph sm - Secondary text, metadata, table content</Text>\n      <Text textStyle=\"xs\">Paragraph xs - Tertiary content, small notes, timestamps</Text>\n      <Text textStyle=\"caption\">CAPTION - Specialized metadata with letter spacing</Text>\n    </Stack>\n  );\n};\n```\n\n### Semantic color tones\n\nUse semantic color tokens to convey meaning and maintain consistent contrast ratios. All colored text uses step 11 of the color scale for accessibility:\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text color=\"fg\">Default - Standard body text</Text>\n      <Text color=\"fg.subtle\">Secondary - Helper text and metadata</Text>\n      <Text color=\"primary.11\">Primary - Links and branded messages</Text>\n      <Text color=\"info.11\">Info - System messages and non-critical feedback</Text>\n      <Text color=\"positive.11\">Positive - Success states and confirmations</Text>\n      <Text color=\"warning.11\">Warning - Cautions and items requiring review</Text>\n      <Text color=\"critical.11\">Critical - Errors and destructive actions</Text>\n    </Stack>\n  );\n};\n```\n\n### Polymorphic rendering\n\nUse the `as` prop to render Text as different HTML elements while maintaining the same styling API. This is essential for semantic HTML and accessibility:\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text as=\"p\">Renders as paragraph (default)</Text>\n      <Text as=\"span\">Renders as inline span</Text>\n      <Text as=\"div\">Renders as div block</Text>\n      <Text as=\"label\" htmlFor=\"example-input\">\n        Renders as form label\n      </Text>\n      <Text as=\"strong\" fontWeight=\"700\">\n        Renders as strong (bold)\n      </Text>\n      <Text as=\"em\" fontStyle=\"italic\">\n        Renders as emphasis (italic)\n      </Text>\n    </Stack>\n  );\n};\n```\n\n### Custom styling\n\nText supports all Chakra UI style props, allowing you to customize typography beyond the predefined styles:\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontSize=\"450\" fontWeight=\"600\" lineHeight=\"1.4\">\n        Custom font size and weight\n      </Text>\n      <Text letterSpacing=\"2px\" textTransform=\"uppercase\">\n        Custom letter spacing\n      </Text>\n      <Text textDecoration=\"underline\" textDecorationStyle=\"dashed\">\n        Custom text decoration\n      </Text>\n      <Text\n        maxWidth=\"300px\"\n        overflow=\"hidden\"\n        textOverflow=\"ellipsis\"\n        whiteSpace=\"nowrap\"\n      >\n        This text will truncate with an ellipsis when it exceeds the maximum width\n      </Text>\n    </Stack>\n  );\n};\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Text component provides semantic HTML text rendering. Use appropriate elements via the `as` prop to maintain document structure.\n\n**Semantic HTML best practices:**\n- Use `<p>` (default) for paragraphs\n- Use `<span>` for inline text\n- Use `<label>` for form field labels with `htmlFor` attribute\n- Use `<strong>` or `<em>` for emphasis\n- Avoid using `<div>` for text unless necessary for layout\n\n**Contrast requirements:**\nWhen using colored text, always use step 11 of the color scale (e.g., `primary.11`, `critical.11`) to ensure WCAG AA contrast ratios (4.5:1 minimum) against light backgrounds.\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 = \"product-description-text\";\n\nexport const ProductDescription = () => (\n  <Text id={PERSISTENT_ID} textStyle=\"md\">\n    Product details and specifications\n  </Text>\n);\n```\n\n#### Keyboard navigation\n\nAs a non-interactive display component, Text does not require keyboard interaction.\n\n## API reference\n\n<PropsTable id=\"Text\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Text 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\n\nVerify that Text renders correctly with different content types\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Text, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Text - Basic rendering\", () => {\n  it(\"renders text content\", () => {\n    render(\n      <NimbusProvider>\n        <Text>Hello World</Text>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Hello World\")).toBeInTheDocument();\n  });\n\n  it(\"renders with custom id for tracking\", () => {\n    const PERSISTENT_ID = \"product-description-text\";\n\n    render(\n      <NimbusProvider>\n        <Text id={PERSISTENT_ID}>Product description</Text>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Product description\")).toHaveAttribute(\n      \"id\",\n      PERSISTENT_ID\n    );\n  });\n\n  it(\"renders children elements\", () => {\n    render(\n      <NimbusProvider>\n        <Text>\n          Text with <strong>bold</strong> and <em>italic</em> content\n        </Text>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(/Text with/)).toBeInTheDocument();\n    expect(screen.getByText(\"bold\")).toBeInTheDocument();\n    expect(screen.getByText(\"italic\")).toBeInTheDocument();\n  });\n});\n```\n\n### Typography Scale\n\nTest different textStyle variants\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Text, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Text - Typography scale\", () => {\n  it(\"applies textStyle variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Text textStyle=\"md\" data-testid=\"text-element\">\n          Medium text\n        </Text>\n      </NimbusProvider>\n    );\n\n    const textElement = screen.getByTestId(\"text-element\");\n    expect(textElement).toBeInTheDocument();\n\n    // Test different textStyle values\n    const textStyles = [\"sm\", \"xs\", \"caption\"] as const;\n    textStyles.forEach((style) => {\n      rerender(\n        <NimbusProvider>\n          <Text textStyle={style} data-testid=\"text-element\">\n            {style} text\n          </Text>\n        </NimbusProvider>\n      );\n      expect(screen.getByTestId(\"text-element\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"combines textStyle with custom overrides\", () => {\n    render(\n      <NimbusProvider>\n        <Text textStyle=\"sm\" fontWeight=\"700\">\n          Bold small text\n        </Text>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Bold small text\")).toBeInTheDocument();\n  });\n});\n```\n\n### Semantic Colors\n\nTest semantic color application\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Text, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Text - Semantic colors\", () => {\n  it(\"applies semantic color tokens\", () => {\n    const colors = [\n      { color: \"fg\", label: \"Default text\" },\n      { color: \"fg.subtle\", label: \"Secondary text\" },\n      { color: \"primary.11\", label: \"Primary text\" },\n      { color: \"info.11\", label: \"Info text\" },\n      { color: \"positive.11\", label: \"Success text\" },\n      { color: \"warning.11\", label: \"Warning text\" },\n      { color: \"critical.11\", label: \"Error text\" },\n    ] as const;\n\n    render(\n      <NimbusProvider>\n        {colors.map(({ color, label }) => (\n          <Text key={color} color={color}>\n            {label}\n          </Text>\n        ))}\n      </NimbusProvider>\n    );\n\n    colors.forEach(({ label }) => {\n      expect(screen.getByText(label)).toBeInTheDocument();\n    });\n  });\n\n  it(\"maintains contrast with colored text\", () => {\n    render(\n      <NimbusProvider>\n        <Text color=\"critical.11\">Error message</Text>\n      </NimbusProvider>\n    );\n\n    const errorText = screen.getByText(\"Error message\");\n    expect(errorText).toBeInTheDocument();\n    // In a real application, you would verify the actual computed color\n    // meets WCAG contrast requirements against the background\n  });\n});\n```\n\n### Polymorphic Rendering\n\nTest rendering as different HTML elements\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Text, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Text - Polymorphic rendering\", () => {\n  it(\"renders as paragraph by default\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <Text>Default paragraph</Text>\n      </NimbusProvider>\n    );\n\n    const paragraph = container.querySelector(\"p\");\n    expect(paragraph).toBeInTheDocument();\n    expect(paragraph).toHaveTextContent(\"Default paragraph\");\n  });\n\n  it(\"renders as span when specified\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <Text as=\"span\">Inline text</Text>\n      </NimbusProvider>\n    );\n\n    const span = container.querySelector(\"span\");\n    expect(span).toBeInTheDocument();\n    expect(span).toHaveTextContent(\"Inline text\");\n  });\n\n  it(\"renders as label with htmlFor attribute\", () => {\n    render(\n      <NimbusProvider>\n        {/* @ts-expect-error - TypeScript doesn't infer element-specific props with polymorphic as prop */}\n        <Text as=\"label\" htmlFor=\"email-input\">\n          Email Address\n        </Text>\n      </NimbusProvider>\n    );\n\n    const label = screen.getByText(\"Email Address\");\n    expect(label.tagName).toBe(\"LABEL\");\n    expect(label).toHaveAttribute(\"for\", \"email-input\");\n  });\n\n  it(\"renders as div for layout purposes\", () => {\n    render(\n      <NimbusProvider>\n        <Text as=\"div\">Block text</Text>\n      </NimbusProvider>\n    );\n\n    const text = screen.getByText(\"Block text\");\n    expect(text).toBeInTheDocument();\n    expect(text.tagName).toBe(\"DIV\");\n  });\n});\n```\n\n### Custom Styling\n\nTest custom style prop application\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Text, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Text - Custom styling\", () => {\n  it(\"applies custom typography styles\", () => {\n    render(\n      <NimbusProvider>\n        <Text fontSize=\"450\" fontWeight=\"600\" letterSpacing=\"2px\">\n          Custom styled text\n        </Text>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Custom styled text\")).toBeInTheDocument();\n  });\n\n  it(\"applies truncation styles\", () => {\n    render(\n      <NimbusProvider>\n        <Text\n          maxWidth=\"200px\"\n          overflow=\"hidden\"\n          textOverflow=\"ellipsis\"\n          whiteSpace=\"nowrap\"\n        >\n          This is a very long text that should be truncated\n        </Text>\n      </NimbusProvider>\n    );\n\n    const text = screen.getByText(/This is a very long text/);\n    expect(text).toBeInTheDocument();\n  });\n\n  it(\"applies text transformation\", () => {\n    render(\n      <NimbusProvider>\n        <Text textTransform=\"uppercase\">uppercase text</Text>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"uppercase text\")).toBeInTheDocument();\n  });\n\n  it(\"applies responsive styles\", () => {\n    render(\n      <NimbusProvider>\n        <Text fontSize={{ base: \"350\", md: \"400\", lg: \"450\" }}>\n          Responsive text\n        </Text>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Responsive text\")).toBeInTheDocument();\n  });\n});\n```\n\n### Accessibility\n\nVerify semantic HTML and accessibility features\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Text, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Text - Accessibility\", () => {\n  it(\"maintains semantic structure with as prop\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <Text as=\"strong\">Important text</Text>\n      </NimbusProvider>\n    );\n\n    const strong = container.querySelector(\"strong\");\n    expect(strong).toBeInTheDocument();\n    expect(strong).toHaveTextContent(\"Important text\");\n  });\n\n  it(\"associates label with form control\", () => {\n    render(\n      <NimbusProvider>\n        {/* @ts-expect-error - TypeScript doesn't infer element-specific props with polymorphic as prop */}\n        <Text as=\"label\" htmlFor=\"username\">\n          Username\n        </Text>\n        <input id=\"username\" type=\"text\" />\n      </NimbusProvider>\n    );\n\n    const label = screen.getByText(\"Username\");\n    const input = screen.getByRole(\"textbox\");\n\n    expect(label).toHaveAttribute(\"for\", \"username\");\n    expect(input).toHaveAttribute(\"id\", \"username\");\n  });\n\n  it(\"supports title attribute for truncated text\", () => {\n    const longText = \"This is a very long text that will be truncated\";\n\n    render(\n      <NimbusProvider>\n        <Text\n          overflow=\"hidden\"\n          textOverflow=\"ellipsis\"\n          whiteSpace=\"nowrap\"\n          title={longText}\n        >\n          {longText}\n        </Text>\n      </NimbusProvider>\n    );\n\n    const text = screen.getByText(longText);\n    expect(text).toHaveAttribute(\"title\", longText);\n  });\n});\n```\n\n\n## Resources\n\n- [Chakra UI Text Documentation](https://www.chakra-ui.com/docs/components/text)\n- [Heading Component](../components/typography/heading) - Related typography component\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": "Typography scale",
+          "href": "#typography-scale",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Semantic color tones",
+          "href": "#semantic-color-tones",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Polymorphic rendering",
+          "href": "#polymorphic-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom styling",
+          "href": "#custom-styling",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "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",
+          "href": "#basic-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Typography Scale",
+          "href": "#typography-scale-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Semantic Colors",
+          "href": "#semantic-colors",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Polymorphic Rendering",
+          "href": "#polymorphic-rendering-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom Styling",
+          "href": "#custom-styling-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nThe purpose of these guidelines is to establish a clear typographic hierarchy,\noptimize content readability, and enforce accessibility standards.\n\n### Best practices\n\n- **Keep hierarchy consistent:** Use a limited, predefined set of text styles to\n  maintain visual consistency across all products. Add custom styles with\n  caution.\n- **Prioritize line length:** Use optimal line lengths (typically 50 to 75\n  characters per line) to prevent eye strain and facilitate reading.\n- **Use concise language:** Write clearly, avoiding unnecessary jargon or overly\n  long sentences to reduce cognitive load.\n- **Break up content:** Use short paragraphs, lists, and headings to break up\n  large blocks of text, making content easier to scan.\n- **Maintain consistent tone:** The language, style, and formality should be\n  consistent throughout the application, reflecting the brand's voice.\n- **Handle truncation gracefully:** When necessary, truncate long text with\n  ellipses and provide a tooltip or interaction element to reveal the full\n  content.\n- **Keep length in mind for translation:** When supporting text localization,\n  length can expand more than 20%. Design experiences that can be flexible to\n  shortening and lengthening of content.\n\n### Text Do's and Don'ts\n\n> [!TIP]\\\n> **Do**\n>\n> - Use predefined headings, body sizes, and weights to clearly signal the\n>   importance of content.\n> - Always maintain sufficient contrast between text and its background to meet\n>   WCAG AA standards (4.5:1 minimum).\n> - Keep line length between 50 to 75 characters to maximize reading speed and\n>   comfort.\n> - Ensure adequate vertical spacing (line-height) to prevent text lines from\n>   colliding and improve readability.\n> - Write clearly, avoiding unnecessary jargon and overly long sentences.\n> - Utilize short paragraphs, bullet points, and headings to make content\n>   scannable.\n> - Ensure any text used within images or icons has a text alternative or\n>   aria-label for screen readers.\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Avoid introducing too many different font sizes, weights, or families, which\n>   destroys visual consistency.\n> - Never use color as the only method to convey meaning (e.g., indicating an\n>   error solely with red text).\n> - Avoid excessively long lines of text (over 80 characters), which makes\n>   tracking difficult and causes fatigue.\n> - Avoid line heights that are too small, which makes text visually dense and\n>   difficult to read.\n> - Never truncate text without providing a clear way (like a tooltip) to view\n>   the full content.\n> - Avoid pairing text colors that barely distinguish themselves from the\n>   background, even if they look \"stylish.\"\n> - Stick to the approved typeface(s) in your design system.\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": "Text Do's and Don'ts",
+          "href": "#text-dos-and-donts",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,34 @@
+{
+  "meta": {
+    "id": "Components-Typography",
+    "title": "Typography",
+    "description": "Components for text styling and formatting.",
+    "order": 7,
+    "repoPath": "packages/nimbus/src/docs/typography.mdx",
+    "menu": [
+      "Components",
+      "Typography"
+    ],
+    "route": "components/typography",
+    "tags": [
+      "document"
+    ],
+    "toc": [],
+    "icon": "FontDownload",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Typography\n\nComponents for text styling and formatting.\n\n<CategoryOverview variant=\"list\" />\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Typography\n\nComponents for text styling and formatting.\n\n<CategoryOverview variant=\"list\" />\n",
+      "toc": []
+    }
+  }
+}