@synergy-design-system/metadata 3.7.0 → 3.9.0

package/data/layers/rules/component/component:syn-alert.md

@@ -0,0 +1,81 @@
+# syn-alert
+
+## Summary
+
+Alerts are used to display important messages inline or as toast notifications.
+
+## Common Use Cases
+
+- 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.
+
+## Usage Guidelines
+
+### When to choose inline notifications
+
+- 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.
+
+### When to choose toast notifications
+
+- 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).
+
+### 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.
+
+### Variants & When to Use Them
+
+- 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.
+
+### Icons
+
+- 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.
+
+### Dismissal & Duration
+
+- 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.
+
+### Placement & Presentation
+
+- 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.
+
+### What to Avoid
+
+- 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.
+
+## 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.
+
+## Related Components
+
+- syn-validate

package/data/layers/rules/component/component:syn-badge.md

@@ -0,0 +1,42 @@
+# syn-badge
+
+## Summary
+
+Badges are used to draw attention and display statuses or counts.
+
+## Common Use Cases
+
+- 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
+
+## Usage Guidelines
+
+### Color
+
+- 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
+
+### Content
+
+- Use "+" for overflow values set by the application
+
+### Placement
+
+- Place where it preserves relation to the assigned element
+- Do not obscure any informative element or text
+- Do not alter the number formatting
+
+## 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
+
+## Known Issues
+
+- **Safari**: Badge with role='status' inside syn-button does not announce updates
+- **Firefox**: Only announces content of the element that has updates when multiple elements are inside the badge

package/data/layers/rules/component/component:syn-breadcrumb-item.md

@@ -0,0 +1,28 @@
+# syn-breadcrumb-item
+
+## Summary
+
+Breadcrumb Items are used inside [breadcrumbs](/components/breadcrumb) to represent different links.
+
+## Common Use Cases
+
+- Populate a syn-breadcrumb navigation helping users easily access different pages.
+
+## Usage Guidelines
+
+### Content and Labeling
+
+- Use clear and descriptive labels that accurately represent each page or section in the navigation path.
+
+## 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.
+
+## Related Components
+
+- syn-breadcrumb
+
+## Related Templates
+
+- Breadcrumb

package/data/layers/rules/component/component:syn-breadcrumb.md

@@ -0,0 +1,42 @@
+# syn-breadcrumb
+
+## Summary
+
+Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.
+
+## Common Use Cases
+
+- 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.
+
+## Usage Guidelines
+
+### Content and Labeling
+
+- 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.
+
+### Placement and Consistency
+
+- 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.
+
+### Responsiveness
+
+- On mobile devices breadcrumb must be shortened to only provide a link to the higher-level page.
+
+## 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.
+
+## Related Components
+
+- syn-breadcrumb-item
+
+## Related Templates
+
+- Breadcrumb

package/data/layers/rules/component/component:syn-button-group.md

@@ -0,0 +1,55 @@
+# syn-button-group
+
+## Summary
+
+Button groups can be used to group related buttons into sections.
+
+## Common Use Cases
+
+- Group related buttons that serve a common purpose or function together.
+- Use for actions that are logically connected (e.g., text formatting: bold, italic, underline).
+- Group buttons that control related settings or options within the same UI context.
+- Avoid grouping buttons that are unrelated or have conflicting purposes.
+- Use for toolbars with icon buttons and tooltip hints.
+- Use for segmented controls with radio buttons in a group.
+- Use for text formatting controls (bold, italic, underline, etc.).
+- Use for pagination or navigation controls with multiple related actions.
+- Use for filter or view controls with related options.
+
+## Usage Guidelines
+
+### Variants
+
+- Use outline variant (default) for secondary or neutral button groups.
+- Use filled variant for primary actions or emphasized button groups.
+- Keep variant consistent within a single button group for visual cohesion.
+- Choose variant based on the importance and prominence needed in the layout.
+
+### Composition & Related Elements
+
+- Combine with syn-icon for icon-only toolbar-style button groups.
+- Wrap buttons in syn-tooltip for additional context without cluttering the UI.
+- Use with syn-dropdown for split-button or menu patterns within groups.
+- Place all related interactive elements inside the button group slot.
+
+### Visual Consistency
+
+- Ensure adequate spacing between button groups and other UI elements.
+- Keep the number of buttons in a group manageable (typically 2-5 buttons).
+
+### Component Behavior
+
+- Each button in the group retains its individual click handlers and states.
+- Button states (focus, hover, active) are automatically managed by the component.
+- The component handles size and variant propagation to all child buttons.
+
+## Accessibility
+
+- Always provide a label property for accessibility and screen readers.
+- Label should describe the purpose of the button group (e.g., "Text formatting", "Page navigation").
+- Use clear, descriptive labels that help users understand the grouped buttons' relationship.
+- Labels are not displayed visually but are announced by assistive technologies.
+
+## Related Components
+
+- syn-button

package/data/layers/rules/component/component:syn-button.md

@@ -0,0 +1,54 @@
+# syn-button
+
+## Summary
+
+Buttons represent actions that are available to the user.
+
+## Common Use Cases
+
+- Highlight key actions, like "Request information" or "Next step".
+- Provide supporting actions, like "Learn more", "Explore topic", or "Cancel".
+- Use for functional actions after user input, such as submitting a form or searching for content.
+
+## Usage Guidelines
+
+### Action Labels
+
+- Write simple, self-explanatory labels that include both a verb (action) and a noun.
+- Use text-only labels whenever possible.
+- Avoid generic labels like "OK" or "Download". Use "Confirm selection" or "Download Report" instead.
+- Limit action labels to 1 to 3 words or 15 to 20 characters.
+
+### Action Priority
+
+- Select the appropriate variant for each action based on context and importance.
+- Avoid displaying more than one Call To Action (CTA) at a time on the screen, especially in the same context (e.g., teaser).
+
+### Function
+
+- Use to trigger an action or place a link inside it to navigate to other content.
+
+### Icons
+
+- Add icons to labels only when they clearly support the associated action (e.g., print, email, share), and reserve icon-only buttons for exceptions.
+- Avoid displaying both left and right icons simultaneously.
+- To prevent overcrowding, do not use icons on buttons with extensive copy that spans multiple lines.
+
+### Placement and Responsiveness
+
+- Maintain consistent placement of interactive elements throughout the user interface.
+- Position the primary action at the top (in vertical layout) or on the right (in horizontal layout) when paired with a secondary option.
+- Avoid placing two primary actions next to each other; opt for a secondary action instead.
+- Expand to full width on small devices if applicable.
+
+## Accessibility
+
+- Ensure that button text is unique and contextual. Screen readers will read it aloud, helping users understand the action associated with the button.
+- Keep button text short. Longer copy is harder to scan and increases cognitive load. Remember that translations may double the length of the text.
+- Be aware that button's height may change based on the user's preferred font size set system-wide.
+- For icon-only: Include an ARIA label describing its function (e.g., "Expand section") to ensure the button is accessible to screen readers.
+- Prefer keeping the button enabled by default by relying on default values or by validating on submit.
+
+## Related Templates
+
+- Forms

package/data/layers/rules/component/component:syn-card.md

@@ -0,0 +1,37 @@
+# syn-card
+
+## Summary
+
+Cards can be used to group related subjects in a container.
+
+## Common Use Cases
+
+- Display grouped information such as KPIs, summaries, or previews.
+- Provide a reusable container for dashboard elements.
+- Present actionable items with a compact overview and clear next steps.
+
+## Usage Guidelines
+
+### Content
+
+- Group related information into one card and keep each card focused on a single topic.
+- Use clear headings and concise body text to improve scanability.
+- Avoid overloading a card with too many actions or dense information.
+
+### Layout and Hierarchy
+
+- Use spacing and visual hierarchy to separate header, body, and footer regions.
+- Align card width and density with surrounding content so cards feel consistent.
+- Use shadows or sharp style consistently across a view.
+
+### Actions
+
+- Place primary actions in a predictable location such as the card footer.
+- Use action labels that clearly describe the result.
+- Limit actions to the most relevant options for the card context.
+
+## Accessibility
+
+- Ensure card content has a logical heading and text order so screen readers can parse it correctly.
+- Do not use cards as the only way to access critical information or actions.
+- Keep interactive elements inside cards keyboard reachable with clear focus indicators.

package/data/layers/rules/component/component:syn-chart.md

@@ -0,0 +1,39 @@
+# syn-chart
+
+## Summary
+
+The `<syn-chart>` component is a container for displaying charts. It provides a structured layout and styling for chart elements, allowing for consistent presentation across different types of charts. The chart component is based on [Apache ECharts](https://echarts.apache.org)
+
+## Common Use Cases
+
+- Display time-based trends such as sensor values, throughput, or production metrics.
+- Compare multiple data series in dashboards to identify differences and anomalies.
+- Present historical data to support analysis, reporting, and decision-making.
+- Visualize key performance indicators where users need a fast visual overview.
+
+## Usage Guidelines
+
+### Data and Purpose
+
+- Use charts when visual pattern recognition (trends, peaks, outliers) is more helpful than raw tables.
+- Keep the chart goal specific and clear (for example trend over time, comparison, distribution).
+- Avoid using charts when exact value lookup is the primary task; provide a table or value list as a complement.
+
+### Visual Clarity
+
+- Use clear axis labels, units, and legends so users can understand the data context immediately.
+- Limit the number of simultaneously visible series to reduce visual noise.
+- Choose palettes that maintain sufficient contrast between series and background.
+- Avoid excessive decoration and effects that do not add analytical value.
+
+### Responsiveness and Density
+
+- Ensure labels, tooltips, and legends remain readable at small viewport sizes.
+- Prevent overlapping labels and crowded markers by simplifying or reducing displayed data where needed.
+- Keep chart dimensions appropriate for the amount and complexity of the data shown.
+
+## Accessibility
+
+- Do not rely on color alone to distinguish data series; use labels, markers, or patterns where helpful.
+- Provide a text alternative or data table for users who cannot interpret visualizations reliably.
+- Ensure chart context is available in surrounding text, including what is shown and why it matters.

package/data/layers/rules/component/component:syn-checkbox.md

@@ -0,0 +1,34 @@
+# syn-checkbox
+
+## Summary
+
+Checkboxes allow the user to toggle an option on or off.
+
+## Common Use Cases
+
+- Used for selections that don't immediately trigger an action.
+- Selecting an option like "Agree to Terms and Conditions" before submitting a registration form.
+- Opt-in/Opt-out of notifications or subscriptions.
+
+## Usage Guidelines
+
+### Content
+
+- Provide a clear, descriptive label for each selection to avoid confusion.
+- Frame labels positively, such as "Enable notifications" instead of "Disable notifications."
+
+### Interaction and Usage
+
+- Ensure each selection operates independently unless used for bulk actions.
+- List selections in a logical order, such as alphabetical or numerical.
+- Refrain from using a single checkbox when the action should take effect immediately - use syn-switch instead.
+
+## Accessibility
+
+- Checkboxes should always look like checkboxes to meet user's expectations.
+- Nesting other interactive elements like links inside labels should be avoided.
+- An error-text with a warning icon should be placed underneath an invalid checkbox. Error messages should always provide hints for solutions.
+
+## Related Templates
+
+- Forms

package/data/layers/rules/component/component:syn-combobox.md

@@ -0,0 +1,42 @@
+# syn-combobox
+
+## Summary
+
+A combobox component that combines the functionality of a text input with a dropdown listbox,
+allowing users to either select from predefined options or enter custom values (when not restricted).
+
+## Common Use Cases
+
+- Allow users to select one or more options from a potentially large list by typing a search string and filtering suggestions.
+- Provide an autocomplete feature in forms where specific or complex entries benefit from quick lookup.
+- Implement in search fields or filter panels when users may not recall the exact option name but can approximate it.
+- Long or descriptive labels, helper text, or units are needed.
+- Forms with many fields that users must scan quickly.
+- Compact layouts and simple fields.
+
+## Usage Guidelines
+
+### Content and Labels
+
+- Keep option labels concise so that suggestions are easy to scan and select.
+- Provide a clear, descriptive placeholder (e.g., "Search or select an option...") to help users understand they can type and choose from suggestions.
+- Avoid repeating the same initial word in multiple suggestions to reduce scanning difficulty.
+
+### Searching Behavior
+
+- Filter available options in real time as the user types; highlight or bold matching text to indicate relevance.
+- Consider limiting the maximum number of displayed suggestions to avoid overwhelming users. We recommend displaying 6-8 (with scrolling for additional results).
+
+## Accessibility
+
+- A visible label may be omitted for search input fields within a combobox if an associated button-complete with a clear search icon and an appropriate accessible name (e.g., aria-label="Search")-is provided.
+- Be aware that group labels will be neglected by most assistive devices.
+
+## Related Components
+
+- syn-option
+- syn-optgroup
+
+## Related Templates
+
+- Forms

package/data/layers/rules/component/component:syn-details.md

@@ -0,0 +1,37 @@
+# syn-details
+
+## Summary
+
+Details show a brief summary and expand to show additional content.
+
+## Common Use Cases
+
+- Revealing additional content, such as a detailed description, specifications, or additional options without overwhelming the user with too much content at once.
+- Interactive elements like a single FAQ item, where the user can expand to see the answer.
+- Useful in forms to hide optional sections that the user can expand if needed, keeping the form clean and concise.
+
+## Usage Guidelines
+
+### Slots
+
+- Use the "summary" slot to add text to the header.
+- Use the "default" slot to add content.
+
+### Header Summary
+
+- Make sure the header summary clearly describes the content inside.
+- Keep header summaries concise to prevent them from wrapping onto multiple lines.
+
+### Content
+
+- Ensure the content is focused and necessary. If the information can be splitted into different meaningful units, consider using syn-accordion.
+- Avoid using collapsible sections for information that must always be visible.
+
+## Accessibility
+
+- Use only for non-critical information. Hiding content can become a potential barrier, making content more challenging to discover.
+- For purely decorative images, ALT-tags should be left empty so that screen readers can bypass them and concentrate on conveying meaningful content.
+
+## Related Components
+
+- syn-accordion

package/data/layers/rules/component/component:syn-dialog.md

@@ -0,0 +1,47 @@
+# syn-dialog
+
+## Summary
+
+Dialogs, sometimes called "modals", appear above the page and require the user's immediate attention.
+
+## Common Use Cases
+
+- Confirm an action which can have significant consequences and explicit user approval or input is needed (e.g. deleting a file).
+- Present important information that must be seen and acknowledged before proceeding (e.g., session expired and renewed login required).
+- Require users to enter information or select from multiple options before continuing.
+- For non-critical content or information that doesn't require immediate user input, please use syn-alert to avoid workflow disruption.
+
+## Usage Guidelines
+
+### Actions
+
+- Ensure a clear user journey by using a single primary button for the main action and secondary buttons for less important actions.
+- Provide an action to close the interaction if a close button is not present in the top-right corner.
+- Avoid having multiple primary action buttons within the same dialog.
+
+### Headline and Content
+
+- Use clear and concise headlines that describe the purpose.
+- Avoid displaying content unrelated to the current workflow.
+- Refrain from using dialogs for complex forms or large amounts of information.
+
+### Slots
+
+- Use the "label" slot to add a headline.
+- Add main content on the "default" slot. The "default" slot is always scrollable.
+- Use the "footer" slot to add action elements. The "footer" slot is always fixed.
+
+### User Interaction
+
+- Require users to take an action before they can continue interacting with the rest of the interface.
+- Provide multiple ways to close the dialog, such as an "X" button, a cancel button, or clicking outside the dialog.
+- Avoid excessive use of dialogs, as they can be disruptive to the user experience.
+
+## Accessibility
+
+- Always provide a headline for the dialog.
+- Always include a visible and easily accessible close button within the modal.
+
+## Known Issues
+
+- **Firefox / Chrome**: When the headline is set by slot instead of attribute, the dialog name is not being announced by VoiceOver in Chrome and Firefox.

package/data/layers/rules/component/component:syn-divider.md

@@ -0,0 +1,26 @@
+# syn-divider
+
+## Summary
+
+Dividers are used to visually separate or group elements.
+
+## Common Use Cases
+
+- Separate distinct item groups to help users clearly see and understand how different pieces of content relate to one another.
+- Provide visual breaks in long pages or forms to improve readability.
+
+## Usage Guidelines
+
+### Spacing and Consistency
+
+- Maintain consistent spacing around separators to prevent them from appearing cramped or too distant from the content they divide.
+- Ensure consistent use to prevent confusion, especially for users relying on assistive technologies.
+
+### Whitespace vs Visual Separators
+
+- Leverage whitespace effectively as a natural divider, which can offer a clean, easy to read and organised design without additional visual elements.
+
+## Accessibility
+
+- Verify that dividers are visible and distinct in high contrast mode settings, which are often used by users with visual impairments.
+- Use to provide clear separation between sections, helping users understand content flow. Screen readers announce dividers, offering context about transitions between sections.

package/data/layers/rules/component/component:syn-drawer.md

@@ -0,0 +1,45 @@
+# syn-drawer
+
+## Summary
+
+Drawers slide in from a container to expose additional options and information.
+
+## Common Use Cases
+
+- Display supplementary information or options without navigating away from the main screen.
+- Provide contextual help or guidance related to the current screen.
+- House navigation menus on smaller devices.
+- Present filter options, forms or settings that users can interact with without losing their place.
+
+## Usage Guidelines
+
+### Content
+
+- Ensure the content is supplementary and does not include critical information that users must see immediately such as notifications or alerts; instead, use syn-alert or syn-dialog for those purposes.
+- Check that the drawer content is fully visible and readable, even at larger font sizes.
+
+### Interaction and Behavior
+
+- Maintain the state of the content when it is reopened.
+- Avoid opening automatically without user interaction.
+- Provide multiple ways to close the interface for easy dismissal, such as a close button or clicking outside of it.
+
+### Layout
+
+- Ensure it does not cover critical content or actions on the main screen.
+- If using a tertiary action in the header, adjust the left padding to 0px for proper alignment.
+
+### Slots
+
+- Use the "header-actions" slot to add navigation and/or action elements if desired.
+- Use the "default" slot to add main content. The "default" slot is always scrollable.
+- Use the "footer" slot to add action elements if desired. The "footer" slot is always fixed.
+
+## Accessibility
+
+- Always provide a label for the drawer so that screenreaders correctly announce the component.
+- Make sure that the close button is always visible to ensure users are able to close the drawer.
+
+## Related Templates
+
+- AppShell

package/data/layers/rules/component/component:syn-dropdown.md

@@ -0,0 +1,36 @@
+# syn-dropdown
+
+## Summary
+
+Dropdowns expose additional content that "drops down" in a panel.
+
+## Common Use Cases
+
+- Provide a list of items in a compact space.
+- Display additional options or settings related to a specific item.
+- Enable navigation through different sections or categories.
+
+## Usage Guidelines
+
+### Behavior
+
+- Avoid hiding sets of less than 4 items in dropdowns.
+- Refrain from nesting dropdowns within each other. If nesting is strictly necessary, limit the menu to two layers to prevent complex operation and cognitive load.
+- Keep the panel near its trigger so users understand its context.
+
+### Panel Items
+
+- Group related panel items to make them easier to find, especially if there are many. Use a group label and syn-divider to separate them visually.
+
+### Triggers
+
+- Maintain consistent styling for dropdown triggers placed at the same level or in the same group; i.e., if a trigger has both text and icon, other triggers on the same level or group should also display text and icon.
+- Avoid truncating trigger labels if possible.
+
+## Accessibility
+
+- Ensure that when the menu is triggered via keyboard, the first item receives focus.
+
+## Related Templates
+
+- AppShell