From 34093e5162de271a9f58e7725900c449e407555f Mon Sep 17 00:00:00 2001 From: mariohamann Date: Fri, 8 May 2026 09:36:51 +0200 Subject: [PATCH 1/3] fix: clarify `sd-menu` usage as a system menu and update related documentation --- .changeset/menu-navigation-wording.md | 5 +++ packages/docs/src/stories/components/menu.mdx | 33 +++++++++++-------- .../src/stories/components/menu.stories.ts | 11 ++++--- 3 files changed, 31 insertions(+), 18 deletions(-) create mode 100644 .changeset/menu-navigation-wording.md diff --git a/.changeset/menu-navigation-wording.md b/.changeset/menu-navigation-wording.md new file mode 100644 index 0000000000..2a11e5ce48 --- /dev/null +++ b/.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`. diff --git a/packages/docs/src/stories/components/menu.mdx b/packages/docs/src/stories/components/menu.mdx index 31523357cd..bf909d33e8 100644 --- a/packages/docs/src/stories/components/menu.mdx +++ b/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. @@ -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,9 +47,9 @@ 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 @@ -57,18 +57,23 @@ Used as a list of choices to the user, such as a set of actions or functions. - 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 Solid DS Best Practices for WCAG Compliance to learn more about our accessibility standards.`; +Visit Solid DS Best Practices for WCAG Compliance to learn more about our accessibility standards.\`; diff --git a/packages/docs/src/stories/components/menu.stories.ts b/packages/docs/src/stories/components/menu.stories.ts index 90ff1ede02..1256e53706 100644 --- a/packages/docs/src/stories/components/menu.stories.ts +++ b/packages/docs/src/stories/components/menu.stories.ts @@ -55,7 +55,7 @@ export const Default = { Menu - + ${generateTemplate({ args @@ -110,12 +110,15 @@ export const Checkmark = { }; /** - * To create a submenu, nest an `` in any menu item. + * Use the `submenu` slot to nest an `` inside any menu item to create a submenu. */ export const Submenu = { render: () => html` - Menu + + Menu + + Menu item 1 Menu item 2 @@ -139,7 +142,7 @@ export const Grouping = { Menu - + Menu item 1 From 125dc7496e81f58345033e1fd2ec6ade0eb3999e Mon Sep 17 00:00:00 2001 From: mariohamann Date: Fri, 8 May 2026 09:49:50 +0200 Subject: [PATCH 2/3] update skills --- .github/agents/dev-bugfix.agent.md | 2 +- .github/agents/dev-component.agent.md | 2 +- .../dev-issue-implementation-planner.agent.md | 2 +- .github/agents/dev-style-component.agent.md | 2 +- .../agents/docs-templates-specialist.agent.md | 14 ++++++------ .../agents/pm-refinement-preparer.agent.md | 2 +- .../write-documentation-stories/SKILL.md | 2 +- .../skills/write-template-stories/SKILL.md | 22 +++++++++---------- .vscode/mcp.json | 4 ++++ 9 files changed, 28 insertions(+), 24 deletions(-) diff --git a/.github/agents/dev-bugfix.agent.md b/.github/agents/dev-bugfix.agent.md index 0674b79a4b..b69f907002 100644 --- a/.github/agents/dev-bugfix.agent.md +++ b/.github/agents/dev-bugfix.agent.md @@ -1,7 +1,7 @@ --- name: "Dev: Bugfix Developer" description: "Use when implementing a bug fix from a GitHub issue. Reads the bug issue, implements a TDD fix, adds comprehensive tests, and creates a changeset. Use for: bug fixes, regression fixes, component patches, fix: issues." -tools: [github/issue_read, edit/editFiles , edit/createFile, edit/createDirectory, search, agent] +tools: [github/issue_read, edit/editFiles , edit/createFile, edit/createDirectory, search, agent, figma/get_design_context, figma/get_screenshot] --- ## Role diff --git a/.github/agents/dev-component.agent.md b/.github/agents/dev-component.agent.md index a28493c53d..1c7a046a85 100644 --- a/.github/agents/dev-component.agent.md +++ b/.github/agents/dev-component.agent.md @@ -1,7 +1,7 @@ --- name: "Dev: Component Developer" description: "Use when implementing or modifying a Lit web component from a GitHub issue. Handles both new components (feat: ✨ add sd-*) and adding features to existing ones. Scaffolds, implements, tests, documents, and prepares a changeset." -tools: [github/issue_read, edit/editFiles, edit/createFile, edit/createDirectory, search, agent] +tools: [github/issue_read, edit/editFiles, edit/createFile, edit/createDirectory, search, agent, figma/get_design_context, figma/get_screenshot] --- ## Role diff --git a/.github/agents/dev-issue-implementation-planner.agent.md b/.github/agents/dev-issue-implementation-planner.agent.md index b387f15aab..d9d4f8e147 100644 --- a/.github/agents/dev-issue-implementation-planner.agent.md +++ b/.github/agents/dev-issue-implementation-planner.agent.md @@ -1,7 +1,7 @@ --- name: "Dev: Github Issue Implementation Planner" description: "Use when implementing any GitHub issue. Reads the issue, summarizes requirements to create an implementation plan and based on the issue type, helps choosing a specialized implementation agent. Use for: implementing any GitHub issue, issue summarization, implementation planning and agent selection." -tools: [read/problems, read/readFile, agent, edit/createDirectory, edit/createFile, edit/editFiles, edit/rename, search, github/issue_read] +tools: [read/problems, read/readFile, agent, edit/createDirectory, edit/createFile, edit/editFiles, edit/rename, search, github/issue_read, figma/get_design_context, figma/get_screenshot] handoffs: - label: Plan Implementation agent: Plan diff --git a/.github/agents/dev-style-component.agent.md b/.github/agents/dev-style-component.agent.md index 5ef0c7cb55..8f7d0cfd6c 100644 --- a/.github/agents/dev-style-component.agent.md +++ b/.github/agents/dev-style-component.agent.md @@ -1,7 +1,7 @@ --- name: "Dev: Style Component Developer" description: "Use when implementing or modifying a CSS style module from a GitHub issue. Handles both new styles (feat: ✨ add sd-*) and adding variants/modifiers to existing ones. Scaffolds, implements, creates stories, and prepares a changeset." -tools: [github/issue_read, read/readFile, edit/editFiles , edit/createFile, edit/createDirectory, search, agent] +tools: [github/issue_read, read/readFile, edit/editFiles , edit/createFile, edit/createDirectory, search, agent, figma/get_design_context, figma/get_screenshot] --- ## Role diff --git a/.github/agents/docs-templates-specialist.agent.md b/.github/agents/docs-templates-specialist.agent.md index f2c283a555..4686912557 100644 --- a/.github/agents/docs-templates-specialist.agent.md +++ b/.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 diff --git a/.github/agents/pm-refinement-preparer.agent.md b/.github/agents/pm-refinement-preparer.agent.md index 99e83b0a66..62fb026c4e 100644 --- a/.github/agents/pm-refinement-preparer.agent.md +++ b/.github/agents/pm-refinement-preparer.agent.md @@ -1,7 +1,7 @@ --- name: "PM: Refinement Preparer" description: "Use when preparing for refinement sessions. Fetches issues from the '🛠️ To be pre-refined' and '⚙️ To be refined' columns and analyzes each for unclear requirements, missing technical information, and missing business cases. Produces open questions per issue to guide the refinement discussion." -tools: [github/projects_get, github/projects_list, execute/runInTerminal, read/readFile] +tools: [github/projects_get, github/projects_list, execute/runInTerminal, read/readFile, figma/get_design_context, figma/get_screenshot] --- > ⚠️ DEVELOPER NOTES ONLY - AGENT HAS TO IGNORE THIS SECTION ⚠️ diff --git a/.github/skills/write-documentation-stories/SKILL.md b/.github/skills/write-documentation-stories/SKILL.md index ce0fc267fc..525f94336d 100644 --- a/.github/skills/write-documentation-stories/SKILL.md +++ b/.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 --- diff --git a/.github/skills/write-template-stories/SKILL.md b/.github/skills/write-template-stories/SKILL.md index 783885b022..34638a2a21 100644 --- a/.github/skills/write-template-stories/SKILL.md +++ b/.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 `` — 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 `` — 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 - [ ] `