@xsolla/xui-tag 0.189.1 → 0.189.3

package/README.md

@@ -2,9 +2,41 @@
 
 A cross-platform React tag component for displaying labels, categories, and removable chips. Supports multiple tones, solid/outlined types, and optional left/right icons.
 <!-- BEGIN:xui-mcp-instructions:tag -->
-Use to visually and textually label, categorize, or organize items using keywords that describe them. You can replace icons inside on images.
-
-Don’t use for navigation or as action buttons
+A compact label chip used to categorise, classify, or annotate content. Renders as a pill-shaped container with a text label and optional leading and trailing icons. Supports two visual types (solid fill and outlined), seven semantic tones, and five sizes. Used in lists, cards, table cells, filters, and any context where a short categorical attribute needs to be visually marked.
+
+### When to use
+- To display a category, status, or attribute as a persistent visual marker — e.g. *"New"*, *"Beta"*, *"Sale"*, *"Featured"*
+- To represent a selected filter or active facet in a filter bar
+- To show a label on a card, list item, or table row when a colour-coded semantic signal is needed
+- In multi-tag groups where several attributes must be shown simultaneously on one item
+
+### When not to use
+- For interactive toggleable filters — use ToggleButtonGroup or a checkable chip pattern
+- For operational statuses with complex state logic — use StatusDropdown or Badge
+- For dismissible user-entered tags — add a remove (✕) button in the Icon right slot
+- When the label is purely decorative with no semantic meaning — use a styled text span instead
+
+### Content guidelines
+- Label text — keep tag labels short: 1–3 words maximum. Use title case for category labels (*"New"*, *"On Sale"*, *"Beta"*) and sentence case for descriptive labels (*"Out of stock"*).
+- Avoid redundancy — if an icon already communicates the meaning (e.g. a checkmark for verified), the label *"Verified"* may be redundant in very compact contexts. In most cases, keep both for clarity.
+- Consistent vocabulary — use the same label text for the same semantic state across the entire product. Do not use *"Beta"* in one place and *"Preview"* in another for the same concept.
+- No punctuation — do not end tag labels with periods, commas, or colons.
+
+### Behaviour guidelines
+- Read-only vs interactive — by default, Tag is a display component with no built-in interactive states. If a tag must be dismissible, add a trailing remove icon (Icon right=true with an ✕ icon) and handle the click at the product level. If a tag must be selectable/toggleable, consider ToggleButtonGroup instead.
+- Removable tags — when using Icon right as a remove button, the click target for removal should be the icon alone, not the entire tag. Give the remove icon an aria-label=*"Remove [tag label]"* and handle the action separately from any click on the tag's label area.
+- Tag groups — when multiple tags appear together (e.g. on a product card), render them in a wrapping flex row with consistent gap. Define a maximum number of visible tags and show a *"+N more"* indicator when exceeded.
+- Overflow — tag labels must not wrap to multiple lines. If the label is too long to fit on one line within the chosen size, truncate with ellipsis and show the full text in a tooltip.
+- Colour consistency — use the same Tone for the same semantic category across all surfaces in the product. Establish a tone-to-category mapping in the product's design token system and apply it uniformly.
+- Type selection — use Type=Solid as the default. Switch to Type=Outlined when the tag is placed on a coloured surface (e.g. inside a coloured card or over a photo) where a solid fill would be visually too heavy.
+
+### Accessibility
+- If the tag is a purely decorative label with no actionable meaning, it can have role=*"presentation"* and aria-hidden=*"true"* when the surrounding context already communicates its meaning.
+- If the tag communicates meaningful state information (e.g. *"New"*, *"Sale"*, *"Out of stock"*), it must be readable by screen readers. Ensure it is not hidden from the accessibility tree.
+- Do not rely on Tone (colour) alone to communicate meaning — the label text or icon must also be present (WCAG 1.4.1 Use of Colour). For icon-only tags, provide aria-label on the element.
+- Removable tags: the remove button (Icon right) must have aria-label=*"Remove [tag name]"* so screen readers can announce which tag is being removed. The button must be focusable and respond to Enter / Space.
+- When tags are inside a list, wrap them in a <ul> with <li> elements and an aria-label on the list describing the group — e.g. aria-label=*"Product tags"*.
+- Ensure sufficient colour contrast between the tag label text and the tag background in both Solid and Outlined variants, for all tones, meeting WCAG AA (4.5:1 for small text at XS/S sizes).
 <!-- END:xui-mcp-instructions:tag -->
 
 ## Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-tag",
-  "version": "0.189.1",
+  "version": "0.189.3",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -10,9 +10,9 @@
     "build:native": "PLATFORM=native tsup"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.189.1",
-    "@xsolla/xui-icons": "0.189.1",
-    "@xsolla/xui-primitives-core": "0.189.1"
+    "@xsolla/xui-core": "0.189.3",
+    "@xsolla/xui-icons": "0.189.3",
+    "@xsolla/xui-primitives-core": "0.189.3"
   },
   "peerDependencies": {
     "react": ">=16.8.0",