@xsolla/xui-link 0.189.1 → 0.189.3

package/README.md

@@ -2,7 +2,43 @@
 
 An accessible inline link. Renders an `<a>` element with theme-aware colour, optional underline, and automatic security attributes for external targets.
 <!-- BEGIN:xui-mcp-instructions:link -->
-To provide navigation, encourage actions, offer additional information
+An inline interactive text element that navigates the user to another location or triggers a related action. Renders as styled text with optional leading and trailing icons. Used inside body copy, lists, form helper text, and any context where navigation or a contextual action should blend with surrounding text rather than stand out as a button.
+
+### When to use
+- For in-text navigation links — e.g. *"Read our [Privacy Policy]"*, *"See [all results]"*
+- For contextual actions inside helper text, empty states, or notifications — e.g. *"[Resend code]"*, *"[Clear filters]"*, *"[Learn more]"*
+- When the action is secondary and should not visually compete with a primary Button
+- In breadcrumbs, footers, settings descriptions, and legal text where navigation is part of the prose
+
+### When not to use
+- As a primary call-to-action — use a Button
+- When the interaction triggers an operation (save, delete, submit) rather than navigating — use a Button or Flex button
+- For standalone navigation items in a menu or sidebar — use a Navigation component
+- When the link needs a container, padding, or icon-only format — use a Flex button
+
+### Content guidelines
+- Descriptive text — link labels must make sense out of context. Screen readers often navigate by listing all links on a page. Labels like *"here"*, *"this"*, or *"more"* are meaningless in isolation.
+- Action links — use an imperative verb phrase: *"Resend code"*, *"Clear filters"*, *"View all"*, *"Download report"*.
+- Navigation links — use the destination name or a descriptive noun phrase: *"Privacy Policy"*, *"API reference"*, *"Account settings"*.
+- Avoid punctuation — do not include trailing commas, periods, or colons inside the link text. Place punctuation outside the link: *"See our [FAQ]."* not *"See our [FAQ.]"*
+- Capitalisation — use sentence case for action links (*"View all results"*). Use title case only for proper names and document titles (*"Terms of Service"*, *"Privacy Policy"*).
+
+### Behaviour guidelines
+- Navigation vs action — use Link for navigation (opening a URL, switching routes) and for lightweight text-level actions (resend, clear, show more). For operations that change state on the server (delete, publish, submit), use a Button even if it is visually small.
+- External links — when a link opens in a new tab, always add a Right icon (external link symbol ↗) and include target=*"_blank"* with rel=*"noopener noreferrer"*. Inform screen reader users by including visually hidden text: *"(opens in new tab)"*, or include it in the aria-label.
+- Visited state — style :visited links distinctly in contexts where the browsing history is meaningful (documentation, article indexes). Do not override :visited styles in application UI where it adds no value.
+- Disabled links — avoid disabled links. If an action is not available, either remove the link entirely or replace it with plain text. If a disabled link is unavoidable, use aria-disabled=*"true"* and tabindex=*"-1"* rather than the disabled attribute (which does not exist on <a> elements).
+- Text length — keep link text concise and descriptive. A link labelled *"here"* or *"click here"* is meaningless out of context and inaccessible. The link text should describe the destination or action: *"View invoice #1042"*, *"Reset password"*, *"Download CSV"*.
+- Underline — Link text must be distinguishable from surrounding non-link text by more than colour alone (WCAG 1.4.1). Use an underline, heavier weight, or other non-colour cue in addition to the palette colour.
+
+### Accessibility
+- Link must be implemented as a native <a href=*"…"*> element — not a <div>, <span>, or <button> with a click handler. Native <a> elements are keyboard-focusable, announced as links by screen readers, and support right-click context menus.
+- The link must have a descriptive accessible name. If the visible text is not descriptive enough (e.g. it reads *"here"* in context), add aria-label with a more descriptive label.
+- External links must include aria-label or visually hidden text announcing that they open in a new tab: e.g. aria-label=*"API reference (opens in new tab)"*.
+- The focus state must have a visible :focus-visible ring that meets WCAG 2.4.7 (Focus Visible). Do not suppress the browser's default focus ring without providing a custom replacement.
+- Do not rely on colour alone to distinguish links from surrounding text (WCAG 1.4.1). Always use an underline or weight change in addition to the palette colour.
+- Icon-enriched links where the icon is decorative must have aria-hidden=*"true"* on the icon element so screen readers do not announce icon names.
+- Visited links in informational contexts (docs, knowledge base) should have a distinct :visited colour to help users track what they have already read.
 <!-- END:xui-mcp-instructions:link -->
 
 ## Installation

package/package.json

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