@synergy-design-system/metadata 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.8.0
+
+### Minor Changes
+
+- [#1276](https://github.com/synergy-design-system/synergy-design-system/pull/1276) [`a6b68f2`](https://github.com/synergy-design-system/synergy-design-system/commit/a6b68f2126ee0c63f2e9f5a91d96e97c2486e3c9) Thanks [@schilchSICKAG](https://github.com/schilchSICKAG)! - Released on: 2026-05-21
+
+  feat: ✨ component context guidelines ([#1187](https://github.com/synergy-design-system/synergy-design-system/issues/1187))
+  - Correct `@since` flags for all components
+  - Updated component usage rules (beta)
+  - Add missing rules files
+  - Create overviews for all components
+
 ## 3.7.0
 
 ## 3.6.0

package/README.md

@@ -81,6 +81,51 @@ if (component.data) {
 
 Use this flow when you need real file content (for example framework wrappers, styles, or examples), not only layer file paths.
 
+### Rules Layer
+
+Component usage guidance is published as a dedicated `rules` layer.
+Use it when you need authored guidance such as common use cases, usage guidelines, accessibility notes, related components, and known issues.
+
+```ts
+import {
+  getDataForComponent,
+  getRulesForComponent,
+} from "@synergy-design-system/metadata";
+
+const genericRulesLayer = await getDataForComponent("syn-accordion", {
+  layer: "rules",
+});
+
+const focusedRules = await getRulesForComponent("syn-accordion");
+
+console.log(genericRulesLayer.data?.rules?.[0]?.path);
+console.log(focusedRules.data?.rules?.[0]?.content);
+```
+
+Use `getDataForComponent(..., { layer: "rules" })` when you want to stay inside the generic layer-based component API.
+Use `getRulesForComponent()` when you want a narrower helper that requires the `rules` layer and never falls back to `full`.
+
+Generated rules markdown is stored under `data/layers/rules/component/` and referenced from each component entity through `layers.rules`.
+
+### CLI: Install Local Skills
+
+This package also provides a CLI command to generate self-contained Synergy skill bundles for local developer workflows.
+
+```bash
+npx @synergy-design-system/metadata install-skills --path .github/skills
+```
+
+The command supports both `--path ./dir` and `--path=./dir`, creates missing directories, and writes portable bundles under:
+
+- `synergy-component/SKILL.md`
+- `synergy-component/components/<component-name>/interface.md`
+- `synergy-component/components/<component-name>/rules.md`
+- `synergy-component/components/<component-name>/examples.md`
+- `synergy-templates/SKILL.md`
+- `synergy-templates/templates/<template-name>/examples.md`
+
+After generation, reference the skills in VS Code with `@synergy-component` and `@synergy-templates`.
+
 ### Public data artifacts
 
 - `data/index.json`

package/data/core/component/component:syn-accordion.json

@@ -17,7 +17,7 @@
           "documentation": "https://synergy-design-system.github.io/?path=/docs/components-syn-accordion--docs",
           "events": [],
           "packageName": "@synergy-design-system/react",
-          "since": "1.23.0",
+          "since": "2.3.0",
           "sourcePath": "packages/react/src/types/syn-jsx-elements.ts",
           "status": "stable",
           "subpathExport": "./types/latest",
@@ -38,7 +38,8 @@
       }
     },
     "override": {
-      "figmaComponentId": "41094-279501",
+      "figmaComponentId": "20877-88547",
+      "figmaDocsId": "41094-279501",
       "stories": [
         {
           "description": {
@@ -112,6 +113,42 @@
         "Structure"
       ]
     },
+    "rules": {
+      "accessibility": [
+        "Use only for non-critical information. Hiding content can become a potential barrier, making content more challenging to discover.",
+        "Use “close-others” attribute to keep only one item from the group open at a time, reducing the amount of information displayed at once and therefore reducing the cognitive load on the user."
+      ],
+      "component": "syn-accordion",
+      "related": {
+        "components": [
+          "syn-details"
+        ]
+      },
+      "usageGuidelines": [
+        {
+          "content": [
+            "Keep only one section open at a time to prevent information overload, unless multiple open sections are necessary.",
+            "Avoid nesting collapsible sections within each other to prevent a confusing user experience."
+          ],
+          "id": "Behavior",
+          "name": "Behavior"
+        },
+        {
+          "content": [
+            "Ensure the content is relevant and necessary; avoid including unrelated information.",
+            "Avoid using collapsible sections for content that needs to be always visible or is critical for immediate user attention."
+          ],
+          "id": "content",
+          "name": "Content"
+        }
+      ],
+      "useCases": [
+        "Organise content into collapsible sections to save space.",
+        "Display FAQs where each question can be expanded to reveal its answer.",
+        "Structure lengthy content into manageable expandable sections.",
+        "Create navigational menus where each section can be expanded to show sub-items, mainly for small viewports."
+      ]
+    },
     "sourceModulePath": "components/accordion/accordion.js",
     "summary": "Accordions provide the ability to group a list of `<syn-details>`."
   },
@@ -163,12 +200,18 @@
         "layer": "interface",
         "path": "layers/interface/component/component:syn-accordion.md"
       }
+    ],
+    "rules": [
+      {
+        "layer": "rules",
+        "path": "layers/rules/component/component:syn-accordion.md"
+      }
     ]
   },
   "name": "syn-accordion",
   "package": "components",
   "relations": [],
-  "since": "1.23.0",
+  "since": "2.3.0",
   "sources": [
     "packages/angular/components/accordion/accordion.component.ts",
     "packages/components/src/components/accordion/accordion.component.ts",

package/data/core/component/component:syn-alert.json

@@ -34,7 +34,7 @@
             }
           ],
           "packageName": "@synergy-design-system/react",
-          "since": "2.0",
+          "since": "1.20.0",
           "sourcePath": "packages/react/src/types/syn-jsx-elements.ts",
           "status": "stable",
           "subpathExport": "./types/latest",
@@ -55,7 +55,8 @@
       }
     },
     "override": {
-      "figmaComponentId": "41137-630160",
+      "figmaComponentId": "45147-41625",
+      "figmaDocsId": "41137-630160",
       "stories": [
         {
           "description": {
@@ -162,6 +163,108 @@
         "Feedback"
       ]
     },
+    "rules": {
+      "accessibility": [
+        "Don't use alerts for trivial updates that don't require user awareness.",
+        "Ensure the alert content is concise and clear, focusing on the most critical information.",
+        "Use simple language that users can quickly understand without additional context.",
+        "Include action items or next steps when appropriate (e.g., \"Your session ended. Please login again\").",
+        "Avoid redundant information — don't repeat the title in the body text."
+      ],
+      "component": "syn-alert",
+      "related": {
+        "components": [
+          "syn-validate"
+        ]
+      },
+      "usageGuidelines": [
+        {
+          "content": [
+            "Integrated into the area where the user is already focused to avoid disrupting the user's workflow.",
+            "Provide feedback on user actions, such as errors, warnings, or confirmations (e.g. \"Unable to save changes. Check your internet connection and try again.\", \"You have unsaved changes. Are you sure you want to leave this page?\" or \"Payment completed. Thank you for your purchase!\").",
+            "Announce important updates or changes within the application (e.g. \"New feature alert! You can now schedule posts directly from the dashboard.\", \"Maintenance scheduled for January 30th, 2:00 AM - 4:00 AM. The application will be unavailable during this time.\").",
+            "Highlight critical information or display system messages that require user attention(e.g. \"System update required. Please restart your application to apply the latest updates.\" or \"Your account has been temporarily suspended due to suspicious activity. Contact support for assistance.\").",
+            "May contain interactive elements such as links and buttons."
+          ],
+          "id": "choose-notification-type-inline",
+          "name": "When to choose inline notifications"
+        },
+        {
+          "content": [
+            "Take the user's attention temporarily away from their current task by appearing on the screen with animations to ensure they are noticed.",
+            "Provide feedback on user actions, such as errors, warnings, or confirmations. (e.g., \"Failed to load data\", \"Your message has been sent\", \"Your settings have been saved\").",
+            "Announce updates, reminders, or confirmations (e.g., \"Your settings have been saved\").",
+            "May contain interactive elements such as links and buttons.",
+            "They can serve as supplementary information for content available on other pages (e.g., a toast notification \"Item has been added to the cart\" alongside a shopping cart page)."
+          ],
+          "id": "choose-notification-type-toast",
+          "name": "When to choose toast notifications"
+        },
+        {
+          "content": [
+            "Keep alert messages concise and clear, focusing on the most critical information.",
+            "Use simple language that users can quickly understand without additional context.",
+            "Include action items or next steps when appropriate (e.g., \"Your session ended. Please login again\").",
+            "Avoid redundant information — don't repeat the title in the body text."
+          ],
+          "id": "content",
+          "name": "Content"
+        },
+        {
+          "content": [
+            "Primary variant: Use for general informational messages that don't require urgent attention.",
+            "Success variant: Use to confirm that an action was completed successfully.",
+            "Warning variant: Use when an action has unexpected consequences or requires user attention.",
+            "Danger variant: Use for critical errors, destructive actions, or situations requiring immediate response.",
+            "Neutral variant: Use for updates or system messages that are neither positive nor negative."
+          ],
+          "id": "variants",
+          "name": "Variants & When to Use Them"
+        },
+        {
+          "content": [
+            "Use icons for consistency (info, check_circle, warning, status-error, settings).",
+            "Ensure the icon clearly represents the alert type — don't use confusing or misleading icons.",
+            "Icons are optional but highly recommended for accessibility and visual clarity."
+          ],
+          "id": "icons",
+          "name": "Icons"
+        },
+        {
+          "content": [
+            "Make alerts closable for non-critical information that users might want to dismiss.",
+            "For critical errors or required information, consider hiding the close button.",
+            "Use auto-hide duration for informational alerts, especially toast notifications (typically 3000-5000ms).",
+            "Pause the auto-hide timer when the user hovers over the alert to allow time for reading."
+          ],
+          "id": "dismissal",
+          "name": "Dismissal & Duration"
+        },
+        {
+          "content": [
+            "For inline alerts: Place alerts near the relevant content (above forms, near inputs with errors). You may also use `syn-validate` for inline validation messages where appropriate.",
+            "For toast notifications: Use the `toast()` method to display temporary notifications in a stack.",
+            "Place success/confirmation alerts above affected content so users see confirmation after action.",
+            "Place error alerts prominently and ensure they don't disappear automatically."
+          ],
+          "id": "placement",
+          "name": "Placement & Presentation"
+        },
+        {
+          "content": [
+            "Never use alerts for decorative purposes or non-essential information.",
+            "Avoid stacking more than 3-4 alerts simultaneously to prevent cognitive overload.",
+            "Reserve alerts for messages that meaningfully impact the user's current task or workflow."
+          ],
+          "id": "avoidance",
+          "name": "What to Avoid"
+        }
+      ],
+      "useCases": [
+        "Inline notifications can provide contextual feedback to users. They are directly embedded within the content of a page or form.",
+        "Toast notifications provide brief, unobtrusive messages that appear as overlays to confirm actions or share updates without interrupting the user's current task."
+      ]
+    },
     "sourceModulePath": "components/alert/alert.js",
     "summary": "Alerts are used to display important messages inline or as toast notifications."
   },
@@ -213,6 +316,12 @@
         "layer": "interface",
         "path": "layers/interface/component/component:syn-alert.md"
       }
+    ],
+    "rules": [
+      {
+        "layer": "rules",
+        "path": "layers/rules/component/component:syn-alert.md"
+      }
     ]
   },
   "name": "syn-alert",
@@ -223,7 +332,7 @@
       "type": "dependsOn"
     }
   ],
-  "since": "2.0",
+  "since": "1.20.0",
   "sources": [
     "packages/angular/components/alert/alert.component.ts",
     "packages/components/src/components/alert/alert.component.ts",

package/data/core/component/component:syn-badge.json

@@ -17,7 +17,7 @@
           "documentation": "https://synergy-design-system.github.io/?path=/docs/components-syn-badge--docs",
           "events": [],
           "packageName": "@synergy-design-system/react",
-          "since": "2.0",
+          "since": "1.14.0",
           "sourcePath": "packages/react/src/types/syn-jsx-elements.ts",
           "status": "stable",
           "subpathExport": "./types/latest",
@@ -38,7 +38,8 @@
       }
     },
     "override": {
-      "figmaComponentId": "41137-656313",
+      "figmaComponentId": "14127-697924",
+      "figmaDocsId": "41137-656313",
       "stories": [
         {
           "description": {
@@ -101,6 +102,62 @@
         "Feedback"
       ]
     },
+    "rules": {
+      "accessibility": [
+        "Avoid using badges for purely decorative purposes",
+        "Ensure badge is sized and placed so it does not obscure other content or controls",
+        "If the badge conveys critical information, provide it in text elsewhere too",
+        "Use aria-live when badge content updates dynamically"
+      ],
+      "component": "syn-badge",
+      "knownIssues": [
+        {
+          "browser": "Safari",
+          "description": "Badge with role='status' inside syn-button does not announce updates"
+        },
+        {
+          "browser": "Firefox",
+          "description": "Only announces content of the element that has updates when multiple elements are inside the badge"
+        }
+      ],
+      "related": {
+        "components": [],
+        "templates": []
+      },
+      "usageGuidelines": [
+        {
+          "content": [
+            "Consistently apply one color choice for a cohesive look",
+            "Use default variants for standard notifications",
+            "Blue = neutral integration, green = more attention, red = maximum emphasis",
+            "Do not associate color variants with success or error states"
+          ],
+          "id": "color",
+          "name": "Color"
+        },
+        {
+          "content": [
+            "Use \"+\" for overflow values set by the application"
+          ],
+          "id": "content",
+          "name": "Content"
+        },
+        {
+          "content": [
+            "Place where it preserves relation to the assigned element",
+            "Do not obscure any informative element or text",
+            "Do not alter the number formatting"
+          ],
+          "id": "placement",
+          "name": "Placement"
+        }
+      ],
+      "useCases": [
+        "Show the count of newly added items",
+        "Display the number of messages received or tasks still pending",
+        "Present the quantity of items collected, like those in a shopping cart"
+      ]
+    },
     "sourceModulePath": "components/badge/badge.js",
     "summary": "Badges are used to draw attention and display statuses or counts."
   },
@@ -156,12 +213,18 @@
         "layer": "interface",
         "path": "layers/interface/component/component:syn-badge.md"
       }
+    ],
+    "rules": [
+      {
+        "layer": "rules",
+        "path": "layers/rules/component/component:syn-badge.md"
+      }
     ]
   },
   "name": "syn-badge",
   "package": "components",
   "relations": [],
-  "since": "2.0",
+  "since": "1.14.0",
   "sources": [
     "packages/angular/components/badge/badge.component.ts",
     "packages/components/src/components/badge/badge.component.ts",

package/data/core/component/component:syn-breadcrumb-item.json

@@ -17,7 +17,7 @@
           "documentation": "https://synergy-design-system.github.io/?path=/docs/components-syn-breadcrumb-item--docs",
           "events": [],
           "packageName": "@synergy-design-system/react",
-          "since": "2.0",
+          "since": "1.26.0",
           "sourcePath": "packages/react/src/types/syn-jsx-elements.ts",
           "status": "stable",
           "subpathExport": "./types/latest",
@@ -38,7 +38,8 @@
       }
     },
     "override": {
-      "figmaComponentId": "41127-679600",
+      "figmaComponentId": "18458-27218",
+      "figmaDocsId": "41127-679600",
       "stories": [
         {
           "description": {
@@ -57,6 +58,33 @@
         "Navigation"
       ]
     },
+    "rules": {
+      "accessibility": [
+        "Dynamically update breadcrumbs and announce changes with aria-live for screen readers.",
+        "Provide clear labels for breadcrumb items to ensure screen readers convey the navigation path effectively."
+      ],
+      "component": "syn-breadcrumb-item",
+      "related": {
+        "components": [
+          "syn-breadcrumb"
+        ],
+        "templates": [
+          "Breadcrumb"
+        ]
+      },
+      "usageGuidelines": [
+        {
+          "content": [
+            "Use clear and descriptive labels that accurately represent each page or section in the navigation path."
+          ],
+          "id": "content_and_labeling",
+          "name": "Content and Labeling"
+        }
+      ],
+      "useCases": [
+        "Populate a syn-breadcrumb navigation helping users easily access different pages."
+      ]
+    },
     "sourceModulePath": "components/breadcrumb-item/breadcrumb-item.js",
     "summary": "Breadcrumb Items are used inside [breadcrumbs](/components/breadcrumb) to represent different links."
   },
@@ -112,12 +140,18 @@
         "layer": "interface",
         "path": "layers/interface/component/component:syn-breadcrumb-item.md"
       }
+    ],
+    "rules": [
+      {
+        "layer": "rules",
+        "path": "layers/rules/component/component:syn-breadcrumb-item.md"
+      }
     ]
   },
   "name": "syn-breadcrumb-item",
   "package": "components",
   "relations": [],
-  "since": "2.0",
+  "since": "1.26.0",
   "sources": [
     "packages/angular/components/breadcrumb-item/breadcrumb-item.component.ts",
     "packages/components/src/components/breadcrumb-item/breadcrumb-item.component.ts",

package/data/core/component/component:syn-breadcrumb.json

@@ -17,7 +17,7 @@
           "documentation": "https://synergy-design-system.github.io/?path=/docs/components-syn-breadcrumb--docs",
           "events": [],
           "packageName": "@synergy-design-system/react",
-          "since": "2.0",
+          "since": "1.26.0",
           "sourcePath": "packages/react/src/types/syn-jsx-elements.ts",
           "status": "stable",
           "subpathExport": "./types/latest",
@@ -38,7 +38,8 @@
       }
     },
     "override": {
-      "figmaComponentId": "41137-748938",
+      "figmaComponentId": "18458-27241",
+      "figmaDocsId": "41137-748938",
       "stories": [
         {
           "description": {
@@ -101,6 +102,53 @@
         "Navigation"
       ]
     },
+    "rules": {
+      "accessibility": [
+        "Dynamically update breadcrumbs and announce changes with aria-live for screen readers.",
+        "Provide clear labels for breadcrumb items to ensure screen readers convey the navigation path effectively."
+      ],
+      "component": "syn-breadcrumb",
+      "related": {
+        "components": [
+          "syn-breadcrumb-item"
+        ],
+        "templates": [
+          "Breadcrumb"
+        ]
+      },
+      "usageGuidelines": [
+        {
+          "content": [
+            "Use clear and descriptive labels that accurately represent each page or section in the navigation path.",
+            "Keep breadcrumb trails short and easy to read to avoid overwhelming users.",
+            "The final breadcrumb item should be non-clickable, as it represents the current page or location."
+          ],
+          "id": "content_and_labeling",
+          "name": "Content and Labeling"
+        },
+        {
+          "content": [
+            "Ensure breadcrumbs are placed consistently across pages to align with user expectations.",
+            "Use breadcrumbs primarily in structured, multi-level navigation contexts. Avoid implementing them for non-hierarchical or dynamically generated paths, where they may confuse rather than assist users."
+          ],
+          "id": "placement_and_consistency",
+          "name": "Placement and Consistency"
+        },
+        {
+          "content": [
+            "On mobile devices breadcrumb must be shortened to only provide a link to the higher-level page."
+          ],
+          "id": "responsiveness",
+          "name": "Responsiveness"
+        }
+      ],
+      "useCases": [
+        "Clarify user location within the website or app hierarchy, improving orientation.",
+        "Allow easy navigation back to previous pages or higher-level sections.",
+        "Enhance discoverability by displaying category paths or product hierarchy levels.",
+        "Simplify backtracking from filtered or search result pages to broader content areas."
+      ]
+    },
     "sourceModulePath": "components/breadcrumb/breadcrumb.js",
     "summary": "Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy."
   },
@@ -156,6 +204,12 @@
         "layer": "interface",
         "path": "layers/interface/component/component:syn-breadcrumb.md"
       }
+    ],
+    "rules": [
+      {
+        "layer": "rules",
+        "path": "layers/rules/component/component:syn-breadcrumb.md"
+      }
     ]
   },
   "name": "syn-breadcrumb",
@@ -166,7 +220,7 @@
       "type": "dependsOn"
     }
   ],
-  "since": "2.0",
+  "since": "1.26.0",
   "sources": [
     "packages/angular/components/breadcrumb/breadcrumb.component.ts",
     "packages/components/src/components/breadcrumb/breadcrumb.component.ts",