docs: clarify browser support and add issue severity classification (#…

…4662)

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -62,7 +62,18 @@ body:
     - type: textarea
       id: code
       attributes:
-          label: Sample code that illustrates the problem
+          label: Sample code or abstract reproduction which illustrates the problem
+    - type: dropdown
+      id: severity
+      attributes:
+          label: Severity
+          description: Please select the severity level of this issue. For more details, refer to our [documentation](https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTING.md#issue-severity-classification)
+          options:
+              - SEV 1
+              - SEV 2
+              - SEV 3
+              - SEV 4
+              - SEV 5
     - type: textarea
       id: logs
       attributes:

CONTRIBUTING.md

@@ -50,10 +50,26 @@ Create an issue on the repository and provide the following information by filli
 -   A quick summary and/or background
 -   Steps to reproduce -
     -   Please be specific!
-    -   Reproduce your issue [here](https://studio.webcomponents.dev/workspace/adobe)
+    -   Please reproduce your issue in an isolated or abstract environment, preferrably [webcomponents.dev](https://studio.webcomponents.dev/workspace/adobe). Screenshots or videos from your local development environment are often not sufficient to help us determine if the issue originates from our library.
 -   What you would expect to happen
 -   What actually happens
 -   Notes (for example why you think this might be happening, or stuff you tried that didn't work)
+-   Issue severity
+
+### Issue severity classification
+
+Providing the correct issue severity classification helps us adequately assess and prioritize your issue.
+
+Please be aware of our issue severity classification criteria:
+
+<!-- prettier-ignore -->
+| Severity Level | Description | Examples |
+|---|---|---|
+| **SEV 1** | A critical design or functionality issue that breaks the design system, causes significant usability problems, or exposes critical security vulnerabilities. This issue impacts all users and/or essential workflows, making users unable to complete any tasks. Requires immediate attention. | Broken navigation system, complete unresponsiveness on all devices, components not rendering, inaccessible primary actions, security vulnerabilities.<br><br>Accessibility: The end user is not able to complete core tasks or activities (e.g., key navigational elements not accessible via keyboard, missing or incorrect form labels that prevent screen reader users from completing forms or actions, critical color contrast issues that prevent users from reading or interacting with essential content). |
+| **SEV 2** | A significant problem affecting the design, usability, or functionality of the system or components for a subset of users. This issue causes major disruptions and prevent users from completing tasks or workflows.<br><br>Accessibility: Does not conform with WCAG 2.1 Level AA criteria and blocks core user tasks (no known workaround). | Content that is out of view or unreachable by customers, critical buttons or links not functioning, or actions that cannot be submitted. Unintentional breaking changes causing disruptions in production environments.<br><br>Accessibility: Issue with a component or controller with widespread use and blocks core user tasks (no known workaround). |
+| **SEV 3** | A design or functionality issue that causes noticeable errors or minor usability problems for users which either cause confusion or degrade the user experience, but do not prevent task completion.<br><br>Accessibility: Does not conform with WCAG 2.1 Level AA criteria and is either non-blocking for core user tasks or blocking for non-core user tasks. | Misleading labels, inconsistent component behavior, unexpected interactions, decreases in system performance.<br><br>Accessibility: Workarounds are available and discoverable for the end user to complete core user tasks, or the end user is not able to complete non-core user tasks (e.g., inadequate ARIA labels, improper focus management, insufficient color contrast for non-critical elements). |
+| **SEV 4** | A minor design flaw that affects user experience, but doesn't have a serious impact on overall usability or functionality. This issue does not prevent users from completing tasks.<br><br>Accessibility: Does not conform with WCAG 2.1 Level AA criteria but has lower user impact. | Minor visual inconsistencies, non-critical content misalignment, or minor layout issues.<br><br>Accessibility: A WCAG violation is present in areas not frequently visited by end users, or it has a lower impact on overall accessibility and usability. |
+| **SEV 5** | A low-level design inconsistency or minor issue that slightly affects usability or aesthetic, with minimal impact on users. | Slight color deviations, minor typographical errors, or small spacing inconsistencies that do not impact functionality. |
 
 ## Do you intend to add a new feature or change an existing one?
 
@@ -92,6 +108,23 @@ type(scope?): subject #scope is optional, but should reference the package you a
 
 We maintain a specific standard of commit messages while committing to the respository. See [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
 
+## Browser support
+
+When contributing to our system or filing an issue, please consider the target browsers we support.
+
+We support the latest 2 major versions of these browsers for desktop:
+
+-   Google Chrome
+-   Mozilla Firefox
+-   Microsoft Edge
+-   Apple Safari for macOS
+
+We do not support Microsoft Internet Explorer.
+
+We support all viewport sizes across supported desktop browsers.
+
+While our components are designed to be responsive and mobile-friendly, we do not yet fully support mobile browsers due to limited testing in mobile hardware. We encourage contributors to keep mobile compatibility in mind and to test updates on mobile devices when possible.
+
 ## Do you want to contribute to the Spectrum Web Components documentation?
 
 Please read [Contributing Guidelines for documentation](https://github.com/adobe/spectrum-web-components#documentation)

README.md

@@ -8,8 +8,14 @@ To this end, Spectrum Web Components only targets _modern_, evergreen browsers t
 
 -   NodeJS >= 18.17.0
 -   Typescript
--   Browsers with Custom Elements V1 and Shadow DOM support, e.g. Chrome, Firefox, Safari, Edge (79+)
-    -   Or appropriate [polyfills](https://github.com/webcomponents/webcomponentsjs) in older browsers.
+-   Supported desktop browsers:
+    -   Last 2 versions of Chrome
+    -   Last 2 versions of Firefox
+    -   Last 2 versions of Safari
+    -   Last 2 versions of Edge
+-   Or appropriate [polyfills](https://github.com/webcomponents/webcomponentsjs) in older browsers.
+-   We support all viewport sizes across supported desktop browsers.
+-   While our components are designed to be responsive and mobile-friendly, we do not yet fully support mobile browsers due to limited testing in mobile hardware. We advise testing updates on mobile devices before updating and are happy to address any reported issues.
 
 # Getting started