@xsolla/xui-switch 0.174.3 → 0.175.0

package/README.md

@@ -1,6 +1,54 @@
 # Switch
 
 A cross-platform toggle for binary on/off settings; a visual alternative to a checkbox.
+<!-- BEGIN:xui-mcp-instructions:switch -->
+Use a switch when a user can choose only one of the options: on or off. Use when items in a list can be independently controlled.
+
+### When to use
+
+- To toggle a single setting, feature, or preference on or off
+- When each item in a list can be independently enabled or disabled
+- When the change takes effect immediately, without requiring a *"Save"* or *"Submit"* action
+
+### When not to use
+- When the user must choose between more than two states — use a Select or Radio group
+- When the change requires confirmation before taking effect — use a Checkbox with a submit action instead
+- When the options are not binary (on/off) — use a ToggleButtonGroup
+
+### Content guidelines
+
+Label should describe the feature or setting being toggled, written as a noun or noun phrase: *"Email notifications"*, *"Auto-renew"*, *"Dark mode"*.
+
+Avoid labelling the switch with the action: not *"Enable notifications"* — just *"Notifications"*.
+
+Description should explain the impact of the toggle in plain language. Keep it to one sentence.
+
+Error message should be specific and constructive: *"This setting cannot be changed while another process is running"* — not just *"Error"*.
+
+### Behaviour guidelines
+
+The switch should take effect immediately on toggle, without requiring a confirmation step. If the action has significant consequences, show a confirmation dialog before applying.
+
+In a list of switches, each one is independent — toggling one should never affect the others unless there is an explicit dependency (e.g. a parent/child relationship between settings).
+
+Disabled switches should preserve their current value visibly so the user understands the current state even if they cannot change it. Provide a tooltip explaining why the switch is disabled.
+
+Avoid using a switch to replace a Checkbox in a form that is submitted later — switches imply immediate effect.
+
+### Accessibility
+
+The switch should render as role=*"switch"* with aria-checked=*"true"* or aria-checked=*"false"* to communicate its state to screen readers.
+
+The Description text should be linked via aria-describedby so screen readers announce it alongside the label.
+
+The Error message must be linked via aria-describedby so it is announced on focus in the Error state.
+
+Disabled switches should remain focusable (aria-disabled=*"true"* rather than the HTML disabled attribute) to allow tooltip display and screen reader announcement.
+
+Ensure the focus ring is visible for keyboard users — the component does not define a focus state visually; this must be implemented in code.
+
+The minimum touch target for interactive elements is 44×44px. Sizes S (16px tall) and M (18px tall) require additional padding in touch contexts to meet this threshold.
+<!-- END:xui-mcp-instructions:switch -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-switch",
-  "version": "0.174.3",
+  "version": "0.175.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,8 +13,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.174.3",
-    "@xsolla/xui-primitives-core": "0.174.3"
+    "@xsolla/xui-core": "0.175.0",
+    "@xsolla/xui-primitives-core": "0.175.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",