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/.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/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 - [ ] `