Clarify sd-menu usage and update documentation

.changeset/menu-navigation-wording.md

@@ -0,0 +1,5 @@
+---
+'@solid-design-system/docs': patch
+---
+
+Updated `sd-menu` overview documentation to clarify that the component is intended as a system menu (action menus, context menus) rather than a site navigation component. Added a "Do Not Use for Site Navigation" guideline with a link to the WAI-ARIA Menu Button Pattern, revised common use cases to focus on actions and commands, and fixed the Submenu story trigger to use `sd-button` instead of `sd-navigation-item`.

.github/agents/docs-templates-specialist.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Docs: Templates Specialist"
 description: "Use when creating or improving Storybook template stories that showcase real-world UI compositions using multiple sd-* components. Retrieves Figma designs, queries the Solid MCP for component APIs and icons, then writes self-contained, production-realistic template stories. Use for: writing template stories, real-world usage examples, multi-component compositions, template documentation."
-tools: [edit/editFiles, edit/createFile, search, agent, mcp_figma_get_design_context, mcp_figma_get_screenshot, mcp_solid-design-_components, mcp_solid-design-_styles, mcp_solid-design-_templates, mcp_solid-design-_icon-search, mcp_solid-design-_token-info]
+tools: [edit/editFiles, edit/createFile, search, agent, figma/get_design_context, figma/get_screenshot, solid-design-system/components, solid-design-system/styles, solid-design-system/templates, solid-design-system/icon-search, solid-design-system/token-info]
 ---
 
 ## Role
@@ -28,7 +28,7 @@ Determine what template scenario needs to be built. Extract:
 ### Step 2: Gather Design Context
 
 Use the **Figma MCP** to get the design:
-- Call `mcp_figma_get_design_context` with the Figma node ID/URL
+- Call `figma/get_design_context` with the Figma node ID/URL
 - Extract layout, spacing, colors, and component usage
 - Capture the Figma URL for the story's `design.url` parameter
 
@@ -37,11 +37,11 @@ If no Figma link is provided, ask the user or proceed with best judgment using t
 ### Step 3: Query the Solid MCP
 
 Before writing any code:
-1. `mcp_solid-design-_components` — verify component APIs (properties, slots, events) for every `sd-*` component you plan to use
-2. `mcp_solid-design-_styles` — check relevant CSS style utilities
-3. `mcp_solid-design-_templates` — browse existing templates to avoid duplication and find structural inspiration
-4. `mcp_solid-design-_icon-search` — resolve correct icon names (always provide EN + DE synonyms)
-5. `mcp_solid-design-_token-info` — confirm correct Tailwind class names for spacing, colors, and typography
+1. `solid-design-system/components` — verify component APIs (properties, slots, events) for every `sd-*` component you plan to use
+2. `solid-design-system/styles` — check relevant CSS style utilities
+3. `solid-design-system/templates` — browse existing templates to avoid duplication and find structural inspiration
+4. `solid-design-system/icon-search` — resolve correct icon names (always provide EN + DE synonyms)
+5. `solid-design-system/token-info` — confirm correct Tailwind class names for spacing, colors, and typography
 
 ### Step 4: Read Reference Examples
 

.github/skills/write-documentation-stories/SKILL.md

@@ -161,7 +161,7 @@ Use the `{attribute}` attribute to {describe what it does}:
 - Show all values of an attribute side-by-side
 - Use placeholder images from `./placeholders/images/` for media slots
 - Never use generic filler ("Click me", "Default") or external image URLs
-- Never use `sd-icon` with `library="_internal"`, use names from `mcp_solid-design-_icon-search` instead
+- Never use `sd-icon` with `library="_internal"`, use names from `solid-design-system/icon-search` instead
 
 ---
 

.github/skills/write-template-stories/SKILL.md

@@ -21,20 +21,20 @@ Template stories live in `packages/docs/src/stories/templates/` and demonstrate
 
 ### 1. Get the Figma Design
 
-Use the **Figma MCP** (`mcp_figma_get_design_context`) to retrieve the design for the template.
+Use the **Figma MCP** (`figma/get_design_context`) to retrieve the design for the template.
 
 - Extract layout structure, spacing, colours, and which components are used
 - Identify the Figma node URL — it will be embedded in the story's `design` parameter
-- Match Tailwind tokens from the design (use `mcp_solid-design-_token-info` for the correct class names)
+- Match Tailwind tokens from the design (use `solid-design-system/token-info` for the correct class names)
 
 ### 2. Discover Available Components & Styles
 
 Use the **Solid MCP** tools to understand what is available:
 
-- `mcp_solid-design-system_components` — list all `sd-*` components; call with a specific component name to get its full API (properties, slots, events, CSS parts)
-- `mcp_solid-design-system_styles` — list all `sd-*` CSS styles; call with a specific style name to see class names
-- `mcp_solid-design-system_templates` — browse existing template compositions for inspiration and to avoid duplication
-- `mcp_solid-design-system_icon-search` — find the correct icon name for `<sd-icon name="...">` — always search with EN + DE synonyms
+- `solid-design-system/components` — list all `sd-*` components; call with a specific component name to get its full API (properties, slots, events, CSS parts)
+- `solid-design-system/styles` — list all `sd-*` CSS styles; call with a specific style name to see class names
+- `solid-design-system/templates` — browse existing template compositions for inspiration and to avoid duplication
+- `solid-design-system/icon-search` — find the correct icon name for `<sd-icon name="...">` — always search with EN + DE synonyms
 
 ### 3. Read Reference Examples
 
@@ -98,7 +98,7 @@ Templates must look like production UIs:
 - Use real, domain-appropriate label text (e.g., "Email address", "Amount in EUR", not "Label" or "Placeholder")
 - Use realistic values for inputs, options, and text (e.g., "John Smith", "€ 12,500", "Submit application")
 - Use placeholder images from `./placeholders/images/` for image slots
-- Use `sd-icon` with names from `mcp_solid-design-_icon-search` — never `library="_internal"`
+- Use `sd-icon` with names from `solid-design-system/icon-search` — never `library="_internal"`
 - Apply appropriate layout with Tailwind utility classes matching the Figma design
 
 ### Combine Components Meaningfully
@@ -228,10 +228,10 @@ export const ProductCardWithRating = {
 ## Checklist
 
 - [ ] Figma design retrieved via Figma MCP; `design.url` set in default export
-- [ ] Component APIs verified via `mcp_solid-design-_components` before use
-- [ ] Icons resolved via `mcp_solid-design-_icon-search` (never `library="_internal"`)
-- [ ] Tailwind tokens verified via `mcp_solid-design-_token-info`
-- [ ] Existing templates checked via `mcp_solid-design-_templates` to avoid duplication
+- [ ] Component APIs verified via `solid-design-system/components` before use
+- [ ] Icons resolved via `solid-design-system/icon-search` (never `library="_internal"`)
+- [ ] Tailwind tokens verified via `solid-design-system/token-info`
+- [ ] Existing templates checked via `solid-design-system/templates` to avoid duplication
 - [ ] Every `id` attribute is unique and story-prefixed
 - [ ] `<script type="module">` used for all inline scripts (`const`/`let` are safe in module scope)
 - [ ] `<script>` blocks use story-prefixed `getElementById` selectors

.vscode/mcp.json

@@ -10,6 +10,10 @@
     "solid-design-system": {
       "command": "node",
       "args": ["./packages/mcp/dist/bin/start.js"]
+    },
+    "figma": {
+      "url": "http://127.0.0.1:3845/mcp",
+      "type": "http"
     }
   }
 }

packages/docs/src/stories/components/menu.mdx

@@ -14,7 +14,7 @@ export const links = {
 export const content = `
 # Menu
 
-Used as a list of choices to the user, such as a set of actions or functions.
+Used as a system menu that presents a list of actions or options for the user to choose from.
 
 <DefaultStory />
 
@@ -32,8 +32,8 @@ Used as a list of choices to the user, such as a set of actions or functions.
 
 ### Common Use Cases
 
-- Navigate between different sections or pages.
-- Access various functions or features quickly.
+- Trigger actions or commands (e.g., "Save", "Delete", "Copy").
+- Access various functions or features quickly (e.g., context menus, action menus).
 - Switch between user account settings or preferences.
 - Provide shortcuts for frequently used tasks.
 
@@ -47,28 +47,33 @@ Used as a list of choices to the user, such as a set of actions or functions.
 
 #### Structure and Organization
 
-- Organize menu items in a logical, hierarchical order to enhance navigation.
+- Organize menu items in a logical order to reflect the actions available.
 - Prioritize frequently used functions at the top of the menu for quicker access.
-- Don’t use multiple menus with similar content on the same screen. Keep the navigation consistent and clear.
+- Don't use multiple menus with similar content on the same screen. Keep the structure consistent and clear.
 
 #### Behavior
 
 - Ensure the menu is easy to access and appears consistently across the platform.
 - Provide visual feedback (e.g., hover, active state) to indicate interactivity.
 - Ensure the menu is responsive and adapts well to different screen sizes and devices.
 
+#### Do Not Use for Site Navigation
+
+- \`sd-menu\` follows the [WAI-ARIA Menu Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) and is intended for system menus (action menus, context menus), **not** for navigating between pages or sections of a site.
+- For site navigation, use \`sd-navigation-item\` or similar navigation components instead.
+
 ### Accessibility Information
 
-- Keyboard Navigation: Ensure the menu can be opened, navigated, and closed using keyboard shortcuts (e.g., arrow keys to move between items, Enter to select, Esc to close).
-- Screen Reader Compatibility: Use appropriate ARIA roles, such as role="menu" for the menu container, role="menuitem" for each item, and aria-haspopup="true" for any submenu trigger. Provide descriptive, concise labels for each menu item.
-- Focus Management: Ensure that focus is automatically directed to the first menu item when the menu is opened. When the menu is closed, focus should return to the element that triggered the menu (e.g., button or link).
-- Visible Focus Indicators: Ensure all interactive menu items have visible focus states for keyboard and screen reader users. This could be through a color change, outline, or other visual indicators.
-- Limit Nested Menus: Avoid deep nesting of menus. Restrict the depth of nested menus to improve usability for screen readers and keyboard navigation.
-  Avoid Truncated Labels: Ensure that menu item labels are fully visible and not truncated. If the text is too long, consider using ellipses (...) and providing a tooltip or accessible description to display the full label.
-- Accessible Shortcuts: If the menu includes keyboard shortcuts or accelerators, ensure these are clearly communicated in the UI (e.g., with tooltips or labels like “Ctrl + S” for save) and accessible to screen readers.
-- Descriptive State Announcements: For dynamic menu behaviors (e.g., opening/closing or item selection), ensure that screen readers announce changes in state, such as "Menu opened" or "Option selected." Use ARIA live regions or alerts as needed.
+- Keyboard Interaction: The menu follows the [WAI-ARIA Menu Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/). Users can open, navigate, and close the menu using keyboard shortcuts (e.g., arrow keys to move between items, Enter or Space to select, Esc to close).
+- Screen Reader Compatibility: The component uses appropriate ARIA roles — \`role="menu"\` for the menu container and \`role="menuitem"\` for each item. Provide descriptive, concise labels for each menu item.
+- Focus Management: Focus is automatically directed to the first menu item when the menu opens. When the menu closes, focus returns to the element that triggered it.
+- Visible Focus Indicators: Ensure all interactive menu items have visible focus states for keyboard and screen reader users.
+- Limit Nested Menus: Avoid deep nesting of submenus to improve usability for screen readers and keyboard users.
+- Avoid Truncated Labels: Ensure that menu item labels are fully visible and not truncated. If the text is too long, consider using ellipses (...) and providing a tooltip or accessible description to display the full label.
+- Accessible Shortcuts: If the menu includes keyboard shortcuts or accelerators, ensure these are clearly communicated in the UI and accessible to screen readers.
+- Descriptive State Announcements: For dynamic menu behaviors (e.g., opening/closing or item selection), ensure that screen readers announce changes in state. Use ARIA live regions or alerts as needed.
 
-Visit <sd-link href="https://www.figma.com/design/VTztxQ5pWG7ARg8hCX6PfR/Solid-DS-%E2%80%93-Component-Library?node-id=38262-58412&t=1qhfYXrbNhSCYCzZ-4" target="_blank">Solid DS Best Practices for WCAG Compliance</sd-link> to learn more about our accessibility standards.`;
+Visit <sd-link href="https://www.figma.com/design/VTztxQ5pWG7ARg8hCX6PfR/Solid-DS-%E2%80%93-Component-Library?node-id=38262-58412&t=1qhfYXrbNhSCYCzZ-4" target="_blank">Solid DS Best Practices for WCAG Compliance</sd-link> to learn more about our accessibility standards.\`;
 
 <Meta title="Components/sd-menu/Overview" />
 

packages/docs/src/stories/components/menu.stories.ts

@@ -55,7 +55,7 @@ export const Default = {
       <sd-dropdown distance="4" rounded open>
         <sd-button variant="secondary" slot="trigger">
           Menu
-          <sd-icon library="_internal" name="chevron-down" slot="icon-right"></sd-icon>
+          <sd-icon name="system/chevron-down" slot="icon-right"></sd-icon>
         </sd-button>
         ${generateTemplate({
           args
@@ -110,12 +110,15 @@ export const Checkmark = {
 };
 
 /**
- * To create a submenu, nest an `<sd-menu slot="submenu">` in any menu item.
+ * Use the `submenu` slot to nest an `<sd-menu>` inside any menu item to create a submenu.
  */
 export const Submenu = {
   render: () => html`
     <sd-dropdown distance="4" rounded>
-      <sd-navigation-item slot="trigger" vertical>Menu</sd-navigation-item>
+      <sd-button variant="secondary" slot="trigger">
+        Menu
+        <sd-icon name="system/chevron-down" slot="icon-right"></sd-icon>
+      </sd-button>
       <sd-menu>
         <sd-menu-item>Menu item 1</sd-menu-item>
         <sd-menu-item>Menu item 2</sd-menu-item>
@@ -139,7 +142,7 @@ export const Grouping = {
     <sd-dropdown distance="4" rounded>
       <sd-button variant="secondary" slot="trigger">
         Menu
-        <sd-icon library="_internal" name="chevron-down" slot="icon-right"></sd-icon>
+        <sd-icon name="system/chevron-down" slot="icon-right"></sd-icon>
       </sd-button>
       <sd-menu>
         <sd-menu-item>Menu item 1</sd-menu-item>