@commercetools/nimbus-mcp 0.1.0 → 2.10.0

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

@@ -0,0 +1,399 @@
+{
+  "meta": {
+    "id": "Components-Kbd",
+    "title": "Kbd",
+    "exportName": "Kbd",
+    "description": "The KBD component visually renders a keystroke or key combination to highlight it within textual instructions.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/kbd/kbd.mdx",
+    "menu": [
+      "Components",
+      "Typography",
+      "Kbd"
+    ],
+    "route": "components/typography/kbd",
+    "tags": [
+      "component",
+      "keyboard",
+      "key"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Basic",
+        "href": "#basic",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Key combinations",
+        "href": "#key-combinations",
+        "depth": 3,
+        "numbering": [
+          1,
+          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\nThe keyboard key component provides semantic and visual representation for\nkeyboard input, such as a shortcut, key press, or command line input, ensuring\nclarity and consistency when providing user instructions.\n\n## Variables\n\nGet familiar with the features.\n\n### Basic\n\n```jsx live\nconst App = () => <Kbd>Ctrl</Kbd>\n```\n\n### Key combinations\n\n```jsx live\nconst App = () => <div>Press <Kbd>Ctrl</Kbd> + <Kbd>C</Kbd> to copy</div>\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe keyboard key component provides semantic and visual representation for\nkeyboard input, such as a shortcut, key press, or command line input, ensuring\nclarity and consistency when providing user instructions.\n\n## Variables\n\nGet familiar with the features.\n\n### Basic\n\n```jsx live\nconst App = () => <Kbd>Ctrl</Kbd>\n```\n\n### Key combinations\n\n```jsx live\nconst App = () => <div>Press <Kbd>Ctrl</Kbd> + <Kbd>C</Kbd> to copy</div>\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic",
+          "href": "#basic",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Key combinations",
+          "href": "#key-combinations",
+          "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 = () => <div>Press <Kbd>Ctrl</Kbd> + <Kbd>C</Kbd> to copy</div>\n```\n\n### Accessibility standards\n\n- **Semantic meaning:** The `<kbd>` element provides clear semantic meaning to\n  screen readers, indicating that the enclosed text represents keyboard input.\n- **Reading flow:** Ensure the KBD component doesn't interrupt the natural\n  reading flow of the surrounding sentence.\n- **Contrast:** The key's background color and the text color must adhere to\n  WCAG contrast guidelines for legibility.\n- **Focus (N/A):** Note that the KBD component itself is generally\n  non-interactive and therefore should not be focusable via the keyboard.\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 { Kbd } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe Kbd component displays keyboard keys and shortcuts with consistent styling:\n\n```jsx live-dev\nconst App = () => (\n  <Text>\n    Press <Kbd>Enter</Kbd> to submit the form.\n  </Text>\n)\n```\n\n## Usage examples\n\n### Single keys\n\nDisplay individual keyboard keys:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"300\">\n    <Text>Press <Kbd>A</Kbd> to select all</Text>\n    <Text>Press <Kbd>Esc</Kbd> to cancel</Text>\n    <Text>Press <Kbd>Tab</Kbd> to move focus</Text>\n    <Text>Press <Kbd>Space</Kbd> to activate</Text>\n    <Text>Press <Kbd>Delete</Kbd> to remove</Text>\n  </Stack>\n)\n```\n\n### Key combinations\n\nDisplay multiple keys pressed together using separate Kbd components:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"300\">\n    <Text>\n      Press <Kbd>Ctrl</Kbd> + <Kbd>C</Kbd> to copy\n    </Text>\n    <Text>\n      Press <Kbd>Ctrl</Kbd> + <Kbd>V</Kbd> to paste\n    </Text>\n    <Text>\n      Press <Kbd>Ctrl</Kbd> + <Kbd>Z</Kbd> to undo\n    </Text>\n    <Text>\n      Press <Kbd>Ctrl</Kbd> + <Kbd>Shift</Kbd> + <Kbd>Z</Kbd> to redo\n    </Text>\n  </Stack>\n)\n```\n\n### Modifier keys\n\nShow common modifier key combinations:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"300\">\n    <Text>\n      <Kbd>⌘</Kbd> + <Kbd>S</Kbd> to save (macOS)\n    </Text>\n    <Text>\n      <Kbd>Ctrl</Kbd> + <Kbd>S</Kbd> to save (Windows/Linux)\n    </Text>\n    <Text>\n      <Kbd>Alt</Kbd> + <Kbd>Tab</Kbd> to switch windows\n    </Text>\n    <Text>\n      <Kbd>Shift</Kbd> + <Kbd>Enter</Kbd> to insert line break\n    </Text>\n  </Stack>\n)\n```\n\n### Arrow keys\n\nDisplay directional navigation keys:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"300\">\n    <Text>Use <Kbd>↑</Kbd> and <Kbd>↓</Kbd> to navigate options</Text>\n    <Text>Use <Kbd>←</Kbd> and <Kbd>→</Kbd> to move cursor</Text>\n    <Text>\n      Press <Kbd>Ctrl</Kbd> + <Kbd>↑</Kbd> to scroll to top\n    </Text>\n  </Stack>\n)\n```\n\n### Function keys\n\nDisplay function keys for special actions:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"300\">\n    <Text>Press <Kbd>F1</Kbd> for help</Text>\n    <Text>Press <Kbd>F5</Kbd> to refresh</Text>\n    <Text>Press <Kbd>F11</Kbd> for fullscreen</Text>\n    <Text>Press <Kbd>F12</Kbd> to open developer tools</Text>\n  </Stack>\n)\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Kbd component renders semantic `<kbd>` HTML elements which are recognized by screen readers as keyboard input. This helps assistive technology users understand that the content represents keys to press.\n\n**Best practices:**\n- Always use Kbd within descriptive text that explains the action\n- Provide clear context about what the keyboard shortcut does\n- Use consistent patterns for key combinations (e.g., modifier + key)\n- Consider providing alternative methods for users who cannot use keyboards\n\n**Example with clear context:**\n```jsx live-dev\nconst App = () => (\n  <Text>\n    To save your changes, press <Kbd>Ctrl</Kbd> + <Kbd>S</Kbd> or use the Save button.\n  </Text>\n)\n```\n\n#### Keyboard navigation\n\nThe Kbd component does not have interactive elements and does not require keyboard navigation. It is a display-only component used to visually represent keyboard keys.\n\n## API reference\n\n<PropsTable id=\"Kbd\" />\n\n## Common patterns\n\n### Help dialog shortcuts\n\nDisplay available keyboard shortcuts in a help menu:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Text fontWeight=\"semibold\">Keyboard Shortcuts</Text>\n    <Stack direction=\"column\" gap=\"200\">\n      <Stack direction=\"row\" justify=\"space-between\" width=\"300px\">\n        <Text>Copy</Text>\n        <Stack direction=\"row\" gap=\"100\" align=\"center\">\n          <Kbd>Ctrl</Kbd>\n          <Text>+</Text>\n          <Kbd>C</Kbd>\n        </Stack>\n      </Stack>\n      <Stack direction=\"row\" justify=\"space-between\" width=\"300px\">\n        <Text>Paste</Text>\n        <Stack direction=\"row\" gap=\"100\" align=\"center\">\n          <Kbd>Ctrl</Kbd>\n          <Text>+</Text>\n          <Kbd>V</Kbd>\n        </Stack>\n      </Stack>\n      <Stack direction=\"row\" justify=\"space-between\" width=\"300px\">\n        <Text>Search</Text>\n        <Stack direction=\"row\" gap=\"100\" align=\"center\">\n          <Kbd>Ctrl</Kbd>\n          <Text>+</Text>\n          <Kbd>F</Kbd>\n        </Stack>\n      </Stack>\n    </Stack>\n  </Stack>\n)\n```\n\n### Form field hints\n\nShow keyboard shortcuts in form field descriptions:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"300\">\n    <Text>\n      Type to search. Press <Kbd>Enter</Kbd> to select the first result.\n    </Text>\n    <Text>\n      Use <Kbd>Tab</Kbd> to move to the next field, or <Kbd>Shift</Kbd> + <Kbd>Tab</Kbd> to go back.\n    </Text>\n    <Text>\n      Press <Kbd>Esc</Kbd> to clear your input and close suggestions.\n    </Text>\n  </Stack>\n)\n```\n\n### Editor shortcuts\n\nDisplay text editor keyboard commands:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"300\">\n    <Text fontWeight=\"semibold\">Text Formatting</Text>\n    <Stack direction=\"column\" gap=\"200\">\n      <Text>\n        <Kbd>Ctrl</Kbd> + <Kbd>B</Kbd> for bold\n      </Text>\n      <Text>\n        <Kbd>Ctrl</Kbd> + <Kbd>I</Kbd> for italic\n      </Text>\n      <Text>\n        <Kbd>Ctrl</Kbd> + <Kbd>U</Kbd> for underline\n      </Text>\n      <Text>\n        <Kbd>Ctrl</Kbd> + <Kbd>K</Kbd> to insert link\n      </Text>\n    </Stack>\n  </Stack>\n)\n```\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-kbd--docs)\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": "Single keys",
+          "href": "#single-keys",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Key combinations",
+          "href": "#key-combinations",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Modifier keys",
+          "href": "#modifier-keys",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Arrow keys",
+          "href": "#arrow-keys",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Function keys",
+          "href": "#function-keys",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "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": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Help dialog shortcuts",
+          "href": "#help-dialog-shortcuts",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form field hints",
+          "href": "#form-field-hints",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Editor shortcuts",
+          "href": "#editor-shortcuts",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nVisually displaying keyboard components helps users learn how to work more\nquickly and more efficiently.\n\n### Best practices\n\n- **Contextual usage:** Only use the KBD component when referencing a literal\n  keyboard key press or shortcut. Do not use it for general UI elements (like\n  buttons or links).\n- **Maintain conciseness:** Keep the content inside the KBD component\n  short—usually one or two words, or a symbol—to represent the specific key\n  (e.g., Enter, Shift, Ctrl).\n- **Combinations:** Clearly indicate key combinations using a simple, recognized\n  separator (e.g., + or a hyphen) within the KBD component (e.g., Ctrl + S).\n- **Visual consistency:** Ensure the KBD component's border, background color,\n  and font style make it visually distinct from the surrounding text while\n  remaining integrated with the overall design.\n- **Appropriate sizing:** The size of the KBD text and box should be\n  proportional to the surrounding body text to avoid unnecessary visual\n  distraction.\n\n### Usage\n\nThis component is an additional way to convey information in a non interactive\nway. Use in moderation, using too often can make text unreadable.\n\n> [!TIP]\\\n> When to use\n\n- Displaying keyboard shortcuts in help text or tooltips\n- Representing individual keys in user interfaces\n- Highlighting keyboard navigation instructions\n- To display command line input or terminal code within technical instructions.\n- To clearly show keyboard shortcuts in application documentation or tooltips\n  (e.g., \"Press Ctrl + Z to undo\").\n\n> [!CAUTION]\\\n> When not to use\n\n- Don't allow the component to wrap excessively; keep the contained text short.\n- Don't use KBD for displaying long code snippets (use a `<code>` block\n  instead).\n- Don't use KBD without accompanying explanatory text to provide context.\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"
+        }
+      ]
+    }
+  }
+}