@synergy-design-system/metadata 3.7.0 → 3.9.0

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

@@ -0,0 +1,45 @@
+# syn-file
+
+## Summary
+
+File controls allow selecting an arbitrary number of files for uploading.
+
+## Common Use Cases
+
+- Upload one or more documents in forms.
+- Attach files to support tickets or feedback forms.
+- Collect folders or batches of assets for import workflows.
+
+## Usage Guidelines
+
+### File Selection
+
+- Use single file mode for one required document and multiple mode only when truly needed.
+- Use directory selection only for workflows where folder upload is expected.
+- Use hide-value only when file names are presented elsewhere in the UI.
+
+### Labels and Guidance
+
+- Describe allowed file types and size limits near the control.
+- Provide examples for naming or formatting if uploads must follow a convention.
+- Keep helper text short and task specific.
+
+### Validation and States
+
+- Use invalid state and clear error copy when upload constraints are not met.
+- Use readonly when users can inspect but not change the selected files.
+- Avoid disabling file input unless there is a clear blocking condition.
+
+## Accessibility
+
+- Always provide a visible label and use help text to explain accepted files and limits.
+- Ensure drag and drop interactions are complemented by a clickable file picker.
+- Expose validation errors in text and not by color alone.
+
+## Related Components
+
+- syn-validate
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,48 @@
+# syn-header
+
+## Summary
+
+The <syn-header /> element provides a generic application header
+that can be used to add applications name, toolbar and primary navigation.
+
+## Common Use Cases
+
+- Display primary navigation links for easy access to different sections of the website.
+- Showcase the company logo prominently to reinforce brand identity.
+- Include links for user account access.
+- Provide a prominent search function to help users quickly find content.
+
+## Usage Guidelines
+
+### Layout
+
+- Place navigation items in the navigation slot, the logo at the left, and meta navigation on the right in wider viewports to keep consistency across products.
+- In smaller viewports, place an expandable menu on the left to host navigation items while keeping the logo consistently on the left across all viewport sizes.
+- Keep the navigation fixed at the top of the website when scrolling back to the top.
+
+### Navigation Structure and Content
+
+- Include the logo, main navigation, and, if applicable, meta navigation.
+- Use the number of navigation items that best suits the content, always ensuring categories are clearly labeled and mutually exclusive.
+- Regularly update the navigation links to reflect current content and structure.
+
+### Visual Style and Branding
+
+- Provide clear visual indicators for active or selected navigation items.
+- Refrain from customizing elements in ways that deviate from the brand identity.
+- Include the company logo prominently; do not use a header without the corresponding logo.
+
+## Accessibility
+
+- Refrain from injecting non-navigation or unrelated content (like dynamic elements) into the header container to avoid distracting or confusing assistive technology.
+- Provide a unique ID on the header container for skip links, ensuring keyboard users can quickly bypass navigation if desired.
+- When placing a logo in the header, the alt text should describe its target (e.g., 'Start Page') rather than the image itself (e.g., 'SICK Logo'), and it should either match the visual label or at least start with the same words.
+
+## Related Components
+
+- syn-prio-nav
+- syn-nav-item
+
+## Related Templates
+
+- AppShell

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

@@ -0,0 +1,41 @@
+# syn-icon-button
+
+## Summary
+
+Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars.
+
+## Common Use Cases
+
+- Toolbar actions such as edit, delete, and settings.
+- Compact controls in tables, cards, and dialogs.
+- Navigation utility actions in headers and side panels.
+
+## Usage Guidelines
+
+### Labeling
+
+- Use concise labels that describe the resulting action, such as "Edit" or "Close".
+- Add a tooltip when extra context is helpful, especially in dense toolbars.
+- Keep label wording consistent across the product.
+
+### Interaction
+
+- Use icon buttons for quick actions and compact controls.
+- Prefer regular buttons when text improves clarity.
+- Use disabled state sparingly and explain why an action is unavailable when possible.
+
+### Size
+
+- Use size variants consistently within a control group.
+
+## Accessibility
+
+- Always provide a meaningful label attribute for icon only buttons.
+- Ensure focus styles remain visible in all variants and states.
+- Avoid using icon buttons for destructive actions without clear context or confirmation.
+
+## Related Components
+
+- syn-icon
+- syn-button
+- syn-tooltip

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

@@ -0,0 +1,42 @@
+# syn-icon
+
+## Summary
+
+Icons are symbols that can be used to represent various options within an application.
+
+## Common Use Cases
+
+- Add visual cues to buttons, alerts, and status messages.
+- Represent actions in compact toolbars.
+- Support navigation and quick scanning in dense layouts.
+
+## Usage Guidelines
+
+### Semantics
+
+- Use icons to support text, not replace it, unless the icon is universally understood.
+- For icon only interactions, pair with syn-icon-button and an accessible label.
+- Choose icons that match the user intent and context.
+
+### Styling
+
+- Use consistent icon sizes within the same interface area.
+- Use design tokens for color and avoid ad hoc hex colors.
+- Keep visual weight balanced when combining icons with text.
+
+### Icon Sources
+
+- Use bundled libraries for common icons whenever possible.
+- Use custom libraries only when required by brand or domain specific assets.
+- Validate fallback behavior when loading icons from CDN or sprite sheets.
+
+## Accessibility
+
+- Provide a label when the icon conveys meaning or triggers an action.
+- Use decorative icons without labels so assistive tech can ignore them.
+- Do not rely on icon color alone to communicate state.
+
+## Related Components
+
+- syn-icon-button
+- syn-button

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

@@ -0,0 +1,50 @@
+# syn-input
+
+## Summary
+
+Inputs collect data from the user.
+
+## Common Use Cases
+
+- Collect user data in forms, including names, emails, dates, and passwords.
+- Allow users to enter numerical values like quantities or prices.
+- Long or descriptive labels, helper text, or units are needed.
+- Forms with many fields that users must scan quickly.
+- Complex fields with adornments, counters, or tooltips.
+- Compact layouts and simple fields.
+
+## Usage Guidelines
+
+### Input Types
+
+- Use appropriate field types for the given purpose (e.g., "email", "password", "number"). For custom autocomplete functionalities (e.g., search fields) use syn-combobox.
+- Use for brief text input only. For longer inputs, such as comments or user feedback, use syn-textarea instead.
+
+### Labels and Placeholders
+
+- Use descriptive and concise labels.
+- Avoid using placeholder text as a substitute for labels.
+
+### User Guidance
+
+- Provide instructions within helper text for completing the field, such as password or character count (e.g., "maxlength" and "minlength"...).
+- Offer additional guidance with tooltips or help text to guide users on the expected input format and prevent unclear or ambiguous interpretation.
+
+### Validation and Formatting
+
+- Use dynamic formatting to automatically format user input as they type.
+- Validate user entries in real-time to provide immediate feedback whenever possible.
+- Avoid using fields for actions that require immediate feedback; use buttons instead.
+
+## Accessibility
+
+- Ensure that focus moves in sequential order between input fields and other form elements. When an input field is focused, it should be clearly indicated.
+- Avoid disabled input fields. If needed, ensure that they remain in the regular tab order but cannot be activated, allowing screen readers to announce their state and purpose. Use the native disabled attribute or appropriate ARIA attributes (e.g., aria-disabled="true").
+- Ensure input fields are usable on all screen sizes. On smaller screens, consider using larger touch targets for input fields.
+- Placeholder text should offer a hint of what the user should write and must always go together with a label.
+- Prefer keeping the input enabled by default by relying on default values or by validating on submit.
+- Use "autocomplete" attribute to enable automated browser assistance when filling out forms.
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,47 @@
+# syn-menu-item
+
+## Summary
+
+Menu items provide options for the user to pick from in a menu.
+
+## Common Use Cases
+
+- Offer contextual actions in dropdown and overflow menus.
+- Expose compact command lists in app headers and toolbars.
+- Provide preference toggles with checkbox-style menu items.
+- Present grouped navigation shortcuts in compact surfaces.
+
+## Usage Guidelines
+
+### Structure and Order
+
+- Use menu items for action lists or option lists that are secondary to the main page flow.
+- Order items by user priority and group related actions together, separated by dividers when needed.
+- Keep labels short and action-oriented (for example, "Rename", "Export", "Delete").
+
+### Item Types and States
+
+- Use normal items for immediate actions and checkbox items for persistent on/off preferences.
+- Avoid mixing destructive actions among neutral actions without clear visual separation.
+- Use loading state only for actions with pending async work and keep feedback short-lived.
+
+### Content and Density
+
+- Use prefix icons to improve scanability, but ensure labels are still self-explanatory without icons.
+- Use suffix content for supplementary context such as status or additional hints.
+- Avoid overly dense menus with long labels, deep nesting, or too many checkable items in one list.
+
+## Accessibility
+
+- Use menu items inside syn-menu so keyboard navigation and selection events remain consistent.
+- Ensure each item has a clear text label; icons in prefix or suffix slots must not be the only way to convey meaning.
+- For type="checkbox" items, ensure checked states communicate meaningful toggles and can be understood without visual cues alone.
+- Use disabled state only when necessary and provide context when an action is unavailable.
+
+## Related Components
+
+- syn-menu
+
+## Related Templates
+
+- AppShell

package/data/layers/rules/component/component:syn-menu-label.md

@@ -0,0 +1,43 @@
+# syn-menu-label
+
+## Summary
+
+Menu labels are used to describe a group of menu items.
+
+## Common Use Cases
+
+- Organize command menus with multiple categories.
+- Separate account actions from content actions.
+- Improve scannability in dropdown and context menus.
+
+## Usage Guidelines
+
+### Grouping
+
+- Use menu labels to separate related item groups in large menus.
+- Use consistent grouping logic such as task type, frequency, or section.
+- Avoid too many groups that make scanning harder.
+
+### Content
+
+- Use concise titles such as "File" or "Account".
+- Use sentence case or title case consistently across the menu.
+- Avoid verbose labels that duplicate menu item wording.
+
+### Menu Structure
+
+- Pair menu labels with separators when visual grouping needs reinforcement.
+- Keep group sizes balanced to avoid very long unbroken sections.
+- Ensure grouped items remain logically ordered within each section.
+
+## Accessibility
+
+- Use menu labels to improve orientation in long menus and grouped options.
+- Keep label text short so assistive technologies announce groups efficiently.
+- Do not use menu labels as interactive menu items.
+
+## Related Components
+
+- syn-menu
+- syn-menu-item
+- syn-divider

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

@@ -0,0 +1,51 @@
+# syn-menu
+
+## Summary
+
+Menus provide a list of options for the user to choose from.
+
+## Common Use Cases
+
+- Navigate between different sections or pages.
+- Access various functions or features quickly.
+- Switch between user account settings or preferences.
+- Provide shortcuts for frequently used tasks.
+
+## Usage Guidelines
+
+### 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.
+
+### Labels and Value Display
+
+- Use clear, descriptive labels to ensure users know what to expect.
+- Use icons alongside text for better visual identification of actions.
+- Avoid overwhelming users with too many menu items. Keep it concise and focused.
+
+### Structure and Organization
+
+- Organize menu items in a logical, hierarchical order to enhance navigation.
+- 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.
+
+## Accessibility
+
+- 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.
+- 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.
+
+## Related Components
+
+- syn-menu-item
+- syn-dropdown
+
+## Related Templates
+
+- AppShell

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

@@ -0,0 +1,44 @@
+# syn-nav-item
+
+## Summary
+
+Flexible button / link component that can be used to quickly build navigations.
+
+## Common Use Cases
+
+- Populate an `<syn-prio-nav>` within a `<syn-header>` navigation bar at the top of a page, helping users easily access different sections.
+- Implement navigation items in a `<syn-side-nav>` for a more detailed and hierarchical navigation structure.
+
+## Usage Guidelines
+
+### Background Options
+
+- Use with background options of white, neutral-100, and primary-100.
+
+### Labels and Icons
+
+- Use clear, concise labels for navigation items.
+- Don't use icons alone unless they are universally understood.
+- Use icons and labels together to enhance comprehension.
+
+### Spacing
+
+- Use indented for nested navigation items in vertical desktop or mobile viewports and in horizontal mobile menus.
+
+### Text Styles and Descriptions
+
+- Be consistent in the use of descriptions: Include them for all items at the same level and keep them similar in length.
+
+## Accessibility
+
+- Provide a logical tab order that follows the visual sequence of navigation items and their different levels.
+- Use aria-current="page" or aria-current="location" on the active navigation item to communicate the user's current location.
+
+## Related Components
+
+- syn-side-nav
+- syn-prio-nav
+
+## Related Templates
+
+- AppShell

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

@@ -0,0 +1,37 @@
+# syn-optgroup
+
+## Summary
+
+The <syn-optgroup> element creates a grouping for <syn-option>s within a <syn-select>.
+
+## Common Use Cases
+
+- Provide options in selects or comboboxes.
+- Allow users to select from a list of predefined choices in forms or settings, where they might choose one or more options.
+- Present filter options in searches or data tables.
+
+## Usage Guidelines
+
+### Behavior
+
+- Provide a reason or alternative if some choice is disabled.
+
+### Content
+
+- Make sure all items in the list are mutually exclusive and unambiguous to help users understand what they are selecting.
+- Provide a default choice where applicable to guide users.
+- Use the optional grouping label and/or divider attributes to visually identify the groups.
+
+## Accessibility
+
+- Ensure that the group label is short and concise as it may be read out when users enter the group.
+
+## Related Components
+
+- syn-select
+- syn-combobox
+- syn-option
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,34 @@
+# syn-option
+
+## Summary
+
+Options define the selectable items within various form controls such as [select](/components/select).
+
+## Common Use Cases
+
+- Provide options in selects or comboboxes.
+- Allow users to select from a list of predefined choices in forms or settings, where they might choose one or more options.
+- Present filter options in searches or data tables.
+
+## Usage Guidelines
+
+### Content
+
+- Make sure all items in the list are mutually exclusive and unambiguous to help users understand what they are selecting.
+- Provide a default choice where applicable to guide users.
+
+## Accessibility
+
+- Long option names can be difficult to understand and perceive, so it's best to keep them concise.
+- Ensure that the beginning of each option is unique to avoid confusion, especially for screen reader users.
+- Don't include headings or interactive elements like links, buttons, or checkboxes within dropdown options.
+
+## Related Components
+
+- syn-select
+- syn-combobox
+- syn-optgroup
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,42 @@
+# syn-pagination
+
+## Summary
+
+<syn-pagination /> provides page navigation, direct page input, and page-size selection for large data sets.
+
+## Common Use Cases
+
+- Navigate through table records across pages.
+- Paginate long result lists in search and catalog pages.
+- Control page size in data heavy admin views.
+
+## Usage Guidelines
+
+### Navigation
+
+- Use pagination for large datasets where loading all records at once is not practical.
+- Keep page size options meaningful for the context, such as 10, 25, and 50.
+- Show current page and total pages so users understand position.
+
+### Compact and Size Variants
+
+- Use compact mode when horizontal space is limited.
+- Use size variants consistently with nearby form controls.
+- Avoid changing pagination density between sibling views without reason.
+
+### Behavior
+
+- Preserve current page when filters and sorting stay compatible with the dataset.
+- Reset to page one when filter changes invalidate the current page.
+- Disable controls only when navigation is not possible, such as first or last page boundaries.
+
+## Accessibility
+
+- Provide clear labels for pagination controls and page size selectors.
+- Ensure keyboard users can reach and operate next, previous, and direct page input.
+- Announce page changes and invalid page input clearly.
+
+## Related Components
+
+- syn-select
+- syn-input

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

@@ -0,0 +1,42 @@
+# syn-popup
+
+## Summary
+
+Popup is a utility that lets you declaratively anchor "popup" containers to another element.
+
+## Common Use Cases
+
+- Anchor floating menus to trigger controls.
+- Display contextual information near data points.
+- Implement custom positioned overlays in advanced layouts.
+
+## Usage Guidelines
+
+### Placement
+
+- Choose placements that keep popup content near the trigger and inside the viewport.
+- Use distance and skidding to fine tune alignment in complex layouts.
+- Use arrows when they help users relate popup content to its anchor.
+
+### Activation and Lifecycle
+
+- Use explicit activation logic for interactive popups and dismiss on outside interaction.
+- Handle flip and shift options to avoid clipping in constrained containers.
+- Prefer stable anchor elements and verify behavior when anchors resize.
+
+### Content and Scope
+
+- Keep popup content focused and short for quick understanding.
+- Avoid placing long workflows inside simple popup containers.
+- Use dialog or drawer for complex multi-step interactions.
+
+## Accessibility
+
+- Ensure popup content remains reachable by keyboard when interactive elements are present.
+- Do not hide critical information in popups that are hard to trigger on touch devices.
+- Use clear trigger affordances so users understand where popup content comes from.
+
+## Related Components
+
+- syn-dropdown
+- syn-tooltip

package/data/layers/rules/component/component:syn-prio-nav.md

@@ -0,0 +1,47 @@
+# syn-prio-nav
+
+## Summary
+
+The `<syn-prio-nav />` element provides a generic navigation bar
+that can be used to group multiple navigation items (usually horizontal `<syn-nav-item />`s)
+together. It will automatically group all items not visible in the viewport into a custom
+priority menu.
+
+## Common Use Cases
+
+- Primary horizontal navigation with overflow handling.
+- App headers that must adapt to changing viewport widths.
+- Section navigation where top destinations should stay visible.
+
+## Usage Guidelines
+
+### Priority Handling
+
+- Place the most important destinations first so they stay visible longer.
+- Move lower priority items into overflow menus when space is limited.
+- Review priority order regularly as product usage evolves.
+
+### Labels and Structure
+
+- Keep labels short and distinct to prevent truncation and ambiguity.
+- Avoid deep nesting in top level priority navigation.
+- Use predictable ordering patterns such as task or category order.
+
+### Responsive Behavior
+
+- Test behavior at common breakpoints to ensure overflow remains usable.
+- Ensure menu fallback remains discoverable on narrow viewports.
+- Keep interaction patterns consistent between desktop and mobile.
+
+## Accessibility
+
+- Ensure navigation items are keyboard reachable and ordered logically.
+- Use clear labels that reflect destination and not internal naming.
+- Communicate current location with proper active state semantics.
+
+## Related Components
+
+- syn-nav-item
+- syn-menu
+- syn-menu-item
+- syn-header

package/data/layers/rules/component/component:syn-progress-bar.md

@@ -0,0 +1,42 @@
+# syn-progress-bar
+
+## Summary
+
+Progress bars are used to show the status of an ongoing operation.
+
+## Common Use Cases
+
+- Show progress for uploads, downloads, or data processing.
+- Indicate completion status in multi-step operations.
+- Display background task progress in dashboards and forms.
+
+## Usage Guidelines
+
+### Determinate vs Indeterminate
+
+- Use determinate mode for measurable tasks such as uploads or imports.
+- Use indeterminate mode for short operations when duration cannot be estimated.
+- Switch to determinate mode as soon as reliable progress information is available.
+
+### Labels and Values
+
+- Provide descriptive labels that state what process is progressing.
+- Show values when users benefit from precise completion feedback.
+- Keep labeling consistent across similar processes.
+
+### Visual Styling
+
+- Use custom heights carefully to preserve readability and visual balance.
+- Maintain sufficient contrast between track and indicator.
+- Avoid decorative overuse of animated progress indicators.
+
+## Accessibility
+
+- Provide accessible labels for progress context, especially when multiple bars are visible.
+- Use determinate mode when actual progress is known and indeterminate only when unknown.
+- Do not rely on color only to communicate progress status.
+
+## Related Components
+
+- syn-progress-ring
+- syn-spinner