@synergy-design-system/metadata 3.7.0 → 3.9.0

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

@@ -0,0 +1,42 @@
+# syn-progress-ring
+
+## Summary
+
+Progress rings are used to show the progress of a determinate operation in a circular fashion.
+
+## Common Use Cases
+
+- Compact progress indication in cards or widgets.
+- Show operation progress in dashboards and modal dialogs.
+- Indicate completion state in space constrained UI areas.
+
+## Usage Guidelines
+
+### Progress Semantics
+
+- Use progress rings when a compact circular indicator fits the layout better than a bar.
+- Use determinate mode when the progress value is known.
+- Avoid using rings for long verbose progress explanations.
+
+### Size and Stroke
+
+- Adjust size based on container density and reading distance.
+- Use track and indicator width values that keep the ring legible at small sizes.
+- Keep sizing consistent across similar components in one view.
+
+### Labels and Values
+
+- Include labels or nearby text describing the operation.
+- Show percentage values when users need exact feedback.
+- Use concise text to avoid crowding around the ring.
+
+## Accessibility
+
+- Provide clear labels for ring progress when meaning is not obvious from context.
+- Use determinate values for measurable tasks and avoid ambiguous visual states.
+- Ensure color choices meet contrast requirements against the background.
+
+## Related Components
+
+- syn-progress-bar
+- syn-spinner

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

@@ -0,0 +1,49 @@
+# syn-radio-button
+
+## Summary
+
+Radios buttons allow the user to select a single option from a group using a button-like control.
+
+## Common Use Cases
+
+- Select one option from a group where one is already preselected.
+- Switch between groups of settings.
+- Filter views by a parent category.
+
+## Usage Guidelines
+
+### Background
+
+- Use with light background options such as white, neutral-100, or primary-100.
+
+### Behavior
+
+- Don't use as input method in forms, for they are not form elements. Use syn-radio instead.
+- Slot inside of an syn-radio-group.
+- Use only in groups, as they are designed to allow the user to activate one of several options. To work with a single option, use syn-checkbox instead.
+- Pre-select always a "default" value; there is no invalid state.
+- Limit the number of options in the group. Users should be able to retain all options available and not be overwhelmed by them.
+
+### Content
+
+- Include icons to support each option visually if possible.
+- Label each choice clearly.
+
+### Styling
+
+- All radio buttons in the group must be styled similarly, e.g., each one is labelled with both text and icon.
+- Avoid styling options only with icons if they are not common symbols, to prevent ambiguous interpretations.
+
+## Accessibility
+
+- Provide meaningful alternative text for icon-only radio buttons.
+- Communicate the group's function-such as filtering or view switching-through clear context or labels.
+
+## Related Components
+
+- syn-radio
+- syn-radio-group
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,43 @@
+# syn-radio-group
+
+## Summary
+
+Radio groups are used to group multiple [radios](/components/radio) or [radio buttons](/components/radio-button) so they function as a single form control.
+
+## Common Use Cases
+
+- Present options in forms where only one selection is allowed (e.g., gender selection, payment methods).
+- Provide clear and concise choices in settings or configuration panels.
+- Enable users to make a selection in surveys or questionnaires.
+- Offer options in filter panels where only one filter can be applied at a time.
+
+## Usage Guidelines
+
+### Background
+
+- Use with light background options such as white, neutral-100, or primary-100.
+
+### Grouping and Labels
+
+- Group related options together using fieldsets and legends for better context and accessibility.
+- Provide a group label that states the category or describes the actions to take.
+
+### Selection Behavior
+
+- Provide a default selected option; never display options without a default selection.
+- Do not disable all choices in a group; if a selection is not applicable, consider hiding the group instead.
+- Use only when users need to select one option; for multiple selections, use checkboxes instead.
+
+## Accessibility
+
+- Ensure that the group label is short and concise as it may be read out when users enter the group.
+- Ensure radios are easily tappable on touch devices.
+
+## Related Components
+
+- syn-radio
+- syn-radio-button
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,46 @@
+# syn-radio
+
+## Summary
+
+Radios allow the user to select a single option from a group.
+
+## Common Use Cases
+
+- Choose one delivery method from a short list.
+- Select one billing frequency such as monthly or yearly.
+- Pick one preference in settings where only a single active mode is allowed.
+- Answer single-choice questions in forms and surveys.
+
+## Usage Guidelines
+
+### Option Structure
+
+- Use radios when users must select exactly one option from a small, predefined list.
+- Keep options mutually exclusive and avoid overlapping meanings between choices.
+- Present options in a stable order and keep wording parallel to make comparison easier.
+
+### Labels and Guidance
+
+- Always provide a meaningful group label on the parent syn-radio-group.
+- Use concise option labels and add help text when options need extra explanation.
+- Prefer sentence case and domain terms users already know.
+
+### Selection Behavior
+
+- Set a sensible default when one option is expected in most cases, but avoid preselecting high-risk choices.
+- If no safe default exists, require explicit user selection before submit.
+- Do not mix radios and checkboxes for the same decision set.
+
+## Accessibility
+
+- Use syn-radio inside syn-radio-group so assistive technologies can interpret options as one exclusive choice set.
+- Ensure each radio has a clear, unique visible label; avoid ambiguous labels such as "Option 1" without context.
+- Use disabled or readonly states only when users can still understand why an option is unavailable.
+
+## Related Components
+
+- syn-radio-group
+
+## Related Templates
+
+- Forms

package/data/layers/rules/component/component:syn-range-tick.md

@@ -0,0 +1,48 @@
+# syn-range-tick
+
+## Summary
+
+Ticks visually improve positioning on range sliders.
+
+## Common Use Cases
+
+- Mark key values such as minimum, midpoint, and maximum on a range slider.
+- Show meaningful breakpoints for pricing, durations, or configurable thresholds.
+- Improve readability of uneven or grouped value scales in advanced range scenarios.
+- Provide subdivision markers between primary ticks for better visual orientation.
+
+## Usage Guidelines
+
+### Scale Mapping
+
+- Use syn-range-tick inside the ticks slot of syn-range to visualize value intervals along the slider track.
+- Align tick labels with actual slider values so visual markers and range behavior stay consistent.
+- Use short, scannable labels for major points such as min, mid, and max values.
+
+### Subdivisions
+
+- Use subdivision ticks to improve orientation between major labeled ticks.
+- Avoid labeling every subdivision when it creates visual clutter; prioritize key waypoints.
+- Keep spacing patterns predictable to avoid implying incorrect value intervals.
+
+### Layout and Density
+
+- Keep tick density proportional to available width so labels do not overlap on smaller screens.
+- Test responsive behavior when using uneven spacing or custom groupings to ensure labels remain readable.
+- Do not use ticks as standalone indicators outside a range context where values cannot be interpreted reliably.
+
+## Accessibility
+
+- Treat range ticks as supportive visual markers; do not rely on ticks alone to communicate critical values or state.
+- Provide meaningful text labels for major ticks so users can understand the scale together with the range label and value output.
+- Ensure tick labels have sufficient contrast and remain readable at all supported sizes and viewport widths.
+- When subdivision ticks are unlabeled, ensure major labeled ticks still provide enough context for orientation.
+- For precise input scenarios, provide an additional text or numeric input method because ticks are not interactive controls.
+
+## Related Components
+
+- syn-range
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,46 @@
+# syn-range
+
+## Summary
+
+Ranges allow the user to select values within a given range using one or two thumbs.
+
+## Common Use Cases
+
+- Adjust settings within a defined range (e.g., volume, brightness).
+- Filter results by specifying a price range or product parameters.
+- Select time intervals for scheduling or reminder tasks.
+- Set minimum and maximum inputs (e.g., age, quantity, distance).
+- Visualize progress by assigning milestones within a larger goal or process.
+
+## Usage Guidelines
+
+### Context
+
+- Position the range component in an uncluttered area to facilitate easy interaction.
+- Reserve the component for relevant, contextually meaningful ranges (e.g., price filters, time spans).
+
+### Labels and Value Display
+
+- Provide clear labels or tooltips indicating the current value or range.
+- Pair the slider with text labels or numeric indicators for precise adjustments.
+- Avoid relying solely on color or visuals; add a text representation for clarity.
+
+### Range Definition
+
+- Choose realistic minimum and maximum values for the intended use case.
+- Avoid extremely large intervals (e.g., 1 to 1,000,000) unless necessary, and label them thoroughly.
+- Use appropriate step sizes for fine control (e.g., increments of 5 or 10 for a price slider).
+- Enable two-handle sliders (min/max) if the scenario requires independent adjustments.
+
+## Accessibility
+
+- Always provide a label for the range so that screenreaders correctly announce the component.
+- Provide alternative input methods like numeric input fields or a stepper, allowing users who struggle with dragging to manually set values.
+
+## Related Components
+
+- syn-range-tick
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,42 @@
+# syn-select
+
+## Summary
+
+Selects allow you to choose items from a menu of predefined options.
+
+## Common Use Cases
+
+- Enable users to select one or more options from a list of predefined choices in forms.
+- Implement in filter panels to allow users to refine search results or data views.
+- Provide options in settings pages where users need to choose preferences from a list.
+
+## Usage Guidelines
+
+### Content and Labels
+
+- Keep each option to a single line of text for readability.
+- Ensure all options have consistent line lengths for easier scanning.
+- Avoid using the same word or phrase at the beginning of options.
+- Provide a meaningful placeholder option to guide users.
+
+### Selection Behavior
+
+- Use for lists with more than five options; for fewer options, consider using syn-radio for single selection or syn-checkbox for multiple selection.
+- Apply the "multiple" attribute when multiple selections are allowed.
+- By default, the number of selected options is displayed after the text.
+- Display selected options as tags within the field to help users track their selections.
+- Consider limiting the maximum number of displayed selectable options to avoid overwhelming users. We recommend displaying 6-8 (with scrolling for additional results).
+
+## Accessibility
+
+- If multiple options can be selected, clearly announce this capability to screenreader users and offer a way to view all chosen items.
+- Be aware that group labels in select components will be neglected by most assistive devices.
+
+## Related Components
+
+- syn-option
+- syn-optgroup
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,47 @@
+# syn-side-nav
+
+## Summary
+
+The <syn-side-nav /> element contains secondary navigation and fits below the header.
+It can be used to group multiple navigation items (<syn-nav-item />s) together.
+
+## Common Use Cases
+
+- Secondary navigation beneath a primary header.
+- Section navigation in management and admin applications.
+- Persistent workspace navigation for desktop oriented layouts.
+
+## Usage Guidelines
+
+### Navigation Structure
+
+- Use side navigation for secondary or section level navigation.
+- Organize items into clear groups with consistent naming patterns.
+- Avoid deeply nested structures that are hard to scan and maintain.
+
+### Layout Variants
+
+- Use sticky mode when navigation should remain visible during page scroll.
+- Use fixed mode only when it does not block core page content.
+- Use rail mode for compact icon first navigation with strong icon semantics.
+
+### Interaction
+
+- Use indentation consistently to reflect hierarchy.
+- Provide footer actions only for secondary utilities and account controls.
+- Ensure collapse and expand behavior is predictable across breakpoints.
+
+## Accessibility
+
+- Provide clear navigation labels and preserve logical focus order.
+- Ensure current location is communicated for active items and sections.
+- Keep rail and collapsed states keyboard operable and understandable.
+
+## Related Components
+
+- syn-nav-item
+- syn-header
+
+## Related Templates
+
+- AppShell

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

@@ -0,0 +1,38 @@
+# syn-spinner
+
+## Summary
+
+Spinners are used to show the progress of an indeterminate operation.
+
+## Common Use Cases
+
+- Indicate that content is being loaded, such as when fetching data from a server or loading a new page.
+- Show ongoing background processes, like file uploads or data processing tasks.
+- Used within buttons or interactive elements to indicate that an action is being processed.
+- Apply to sections of a page that are loading independently, such as widgets or panels.
+- Display when a form is being submitted to show that the submission is in progress.
+
+## Usage Guidelines
+
+### Behavior and Placement
+
+- Use for processes that take a short amount of time (typically under 4 seconds).
+- Apply within specific sections rather than blocking the entire page, unless absolutely necessary.
+- Place in a consistent location relative to the content it is loading.
+
+### Content
+
+- Include a label or message to provide context about what is being loaded, especially if the loading time is long.
+
+### Styling
+
+- Maintain consistency in size and style; avoid using spinners of varying sizes on the same page.
+
+## Accessibility
+
+- Assign role="status" or use a live region (e.g., aria-live="polite") to inform screen reader users of ongoing loading.
+- A spinner shouldn't itself be focusable or interactive, nor prevent from navigating to other parts of the page while loading continues.
+
+## Known Issues
+
+- **Safari**: The spinner component may experience animation issues in Safari, causing it to appear wobbly.

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

@@ -0,0 +1,39 @@
+# syn-switch
+
+## Summary
+
+Switches allow the user to toggle an option on or off.
+
+## Common Use Cases
+
+- Allow users to switch between two states.
+- Use to enable or disable settings, such as turning notifications on or off.
+- Toggle features or functionalities within an application, applying changes immediately.
+
+## Usage Guidelines
+
+### Behavior
+
+- Use for actions that take effect immediately without requiring additional confirmation.
+- Ensure the visual state accurately reflects its functional state.
+- If it's unclear whether the component is showing a state or an action, use syn-checkbox instead.
+
+### Content
+
+- Make sure both the label and action are clear by using appropriate text.
+- Place label text on top of the control, such as in a header, while action text should be placed to the right, next to the control.
+- Use adjectives to describe actions, as they are less ambiguous than verbs.
+- Limit use to binary choices, such as "on/off" or "yes/no".
+
+## Accessibility
+
+- Consider alternatives to switches, as many users may find them confusing.
+- If the switch triggers dynamic changes (e.g., loading new content), provide a corresponding announcement.
+
+## Related Components
+
+- syn-checkbox
+
+## Related Templates
+
+- Forms

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

@@ -0,0 +1,35 @@
+# syn-tab-group
+
+## Summary
+
+Tab groups organize content into a container that shows one section at a time.
+
+## Common Use Cases
+
+- Organize content into different sections, allowing users to switch between them without leaving the page.
+- Implement in dashboards where users need to access different data views or widgets.
+- Group settings or configuration options into categories for easier navigation.
+- Display different aspects of a product, such as description, reviews, and specifications.
+- Arrange user profile information into sections like personal details, activity, and settings.
+
+## Usage Guidelines
+
+### Behavior
+
+- Maintain a consistent tab order across different pages or sections to reduce confusion and enhance user familiarity.
+- Limit the number of tabs (typically no more than six) to avoid overwhelming users; for more options, consider using side navigation.
+- Do not nest tabs within other tab containers.
+
+### Content
+
+- Choose labels that are concise and use no more than two words.
+- Ensure the first tab is the most relevant for the user.
+- Place related tabs next to each other for logical grouping.
+- Avoid overloading each tabs content with too much information; keep it manageable and focused.
+
+## Accessibility
+
+- Provide a clear label for the tab group (e.g., via aria-label or aria-labelledby).
+- The tab group takes a single tabstop, then focus moves to the first interactive element in the tab panel, or the tab panel if there is none. Arrow keys should be used to move between tabs.
+- Use only for non-critical information. Hiding content can become a potential barrier, making it more challenging for users to access information.
+- For purely decorative images, ALT-tags should be left empty so that screen readers can bypass them and concentrate on conveying meaningful content.

package/data/layers/rules/component/component:syn-tab-panel.md

@@ -0,0 +1,44 @@
+# syn-tab-panel
+
+## Summary
+
+Tab panels are used inside [tab groups](/components/tab-group) to display tabbed content.
+
+## Common Use Cases
+
+- Display section content for settings tabs such as General, Security, and Notifications.
+- Show contextual content areas in dashboards without navigating away from the current page.
+- Present product details split into overview, specifications, and documentation sections.
+- Render user-managed views paired with closable tabs in workspace-like interfaces.
+
+## Usage Guidelines
+
+### Structure and Mapping
+
+- Use tab panels for related content sections that belong to the same workflow or information scope.
+- Keep one active panel visible at a time and ensure inactive panels are not presented as primary content areas.
+- Pair each panel with a unique name and keep naming consistent with corresponding tab panel attributes.
+
+### Content Design
+
+- Keep panel content focused and scannable; split dense content into subsections or supporting components.
+- Use consistent spacing and hierarchy across panels so context switches feel predictable.
+- Avoid large layout shifts between panels that can disorient users during navigation.
+
+### Dynamic Content
+
+- Use lazy loading or deferred rendering for heavy panel content when performance is a concern.
+- Show clear loading or empty states when panel data is not immediately available.
+- Do not remove active panel content without immediately providing a meaningful replacement.
+
+## Accessibility
+
+- Use syn-tab-panel only inside syn-tab-group and ensure each panel name matches exactly one syn-tab panel reference.
+- Ensure panel content starts with clear, descriptive structure (for example headings) so users can quickly understand context after switching tabs.
+- Avoid placing essential instructions only in inactive panels when users must complete tasks in sequence.
+- When panel content updates dynamically, preserve user context and avoid unexpected focus jumps.
+
+## Related Components
+
+- syn-tab
+- syn-tab-group

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

@@ -0,0 +1,44 @@
+# syn-tab
+
+## Summary
+
+Tabs are used inside [tab groups](/components/tab-group) to represent and activate [tab panels](/components/tab-panel).
+
+## Common Use Cases
+
+- Switch between related settings categories within a single page.
+- Organize product detail content such as overview, specifications, and resources.
+- Provide document-style workspaces with optional closable tabs for temporary views.
+- Separate dashboard subviews without full page navigation.
+
+## Usage Guidelines
+
+### Structure and Mapping
+
+- Use tabs to switch between related sections within the same context, not for unrelated destinations.
+- Keep one tab active at all times and align each tab panel value with a corresponding tab-panel name.
+- Prefer short labels (one to three words) and avoid wrapping labels to multiple lines where possible.
+
+### Interaction Model
+
+- Use default activation for faster navigation when content updates are lightweight.
+- Use manual activation when panel content is heavy, expensive to load, or likely to cause disorientation during arrow-key navigation.
+- Avoid adding too many tabs in one row; if overflow is common, verify scrolling tabs remain understandable and easy to navigate.
+
+### Closable Tabs
+
+- Use closable tabs only when users create temporary or user-managed views (for example document tabs).
+- When closing tabs, also remove or update the related panel and immediately show a logical fallback tab.
+- Do not use closable tabs for essential navigation where accidental removal would block user progress.
+
+## Accessibility
+
+- Use syn-tab only inside syn-tab-group together with matching syn-tab-panel elements to preserve correct tab and tabpanel semantics.
+- Ensure every tab has a concise, unique label so users can identify sections quickly with both visual and assistive technologies.
+- Use disabled tabs only when users are informed why content is unavailable, and avoid disabling tabs that are required to complete core tasks.
+- When tabs are closable, ensure closing a tab moves focus predictably to the next logical tab and keeps users oriented in the updated set.
+
+## Related Components
+
+- syn-tab-group
+- syn-tab-panel

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

@@ -0,0 +1,46 @@
+# syn-tag-group
+
+## Summary
+
+A tag group is used to display multiple tags that belong together, often representing selected filters, categories, or user‑generated labels.
+It arranges tags in flexible rows and supports different sizes and layouts.
+Tags can be removable, icon‑based, or purely textual.
+
+## Common Use Cases
+
+- Show currently active filters in search and table views.
+- Display selected categories or labels in forms.
+- Manage multi-select states with removable tag chips.
+
+## Usage Guidelines
+
+### Grouping Strategy
+
+- Use tag groups for sets of related tags such as active filters or selected labels.
+- Keep tags short and consistent to avoid visual noise.
+- Use label alignment and group labels to clarify the meaning of the collection.
+
+### Interaction
+
+- Use removable tags when users can directly edit a selection.
+- Provide clear feedback when a tag is removed from the group.
+- Avoid mixing non-removable and removable semantics without clear distinction.
+
+### Sizing and Layout
+
+- Use group size variants consistently with nearby controls.
+- Wrap tags cleanly and preserve readable spacing in narrow layouts.
+- Avoid excessive tag counts without offering collapse or summary behavior.
+
+## Accessibility
+
+- Ensure each tag has clear readable text and a meaningful remove action when removable.
+- Expose group labeling context when tags represent selected filters or categories.
+
+## Related Components
+
+- syn-tag
+
+## Related Templates
+
+- Tag-Group

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

@@ -0,0 +1,40 @@
+# syn-tag
+
+## Summary
+
+Tags are used as labels to organize things or to indicate a selection.
+
+## Common Use Cases
+
+- Label and categorize items to help users filter and find relevant content.
+- Highlight important keywords or attributes associated with an item.
+- Allow users to filter content dynamically by clicking on tags.
+- Display topics or categories associated with an article, post or product.
+
+## Usage Guidelines
+
+### Behavior
+
+- Use the "removable" attribute to include a small close "x" button next to the label.
+- Avoid using a standalone, non-removable tag, as its selected/unselected state could be unclear. Apply the "removable" attribute for those cases.
+
+### Labels
+
+- Try to keep a similar text length for all labels, and specially avoid excessively long ones. If necessary, truncate the label and show the full text in a tooltip on hover.
+- Don't use tags to indicate the status of a task, use syn-status-badge instead.
+
+## Accessibility
+
+- Ensure each tag has a short, meaningful text label that can be understood without visual context alone.
+- For removable tags, ensure the remove action is clearly announced by assistive technologies and communicates which tag will be removed.
+- Provide visible focus indication for any interactive tag or remove control and keep focus order consistent with surrounding controls.
+- When tags are presented as a set (for example, active filters), provide group context with a clear label via syn-tag-group or an equivalent labeled container.
+- After a tag is removed, move focus predictably to a logical next element and provide feedback about the updated state when relevant.
+
+## Related Components
+
+- syn-tag-group
+
+## Related Templates
+
+- Tag Group