@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/link/design.md

@@ -0,0 +1,160 @@
+# Link — Design (https://design.candescent.com/docs/components/link)
+
+## Usage
+
+**Example**
+
+**Common alternative names**: Hyperlink, URL
+
+## Anatomy
+
+A Link is made up of link text and optional icons. The clickable area follows the text (and icons), unless your implementation expands the hit target for accessibility.
+
+**Anatomy\_link**
+
+1. **Link text:** The visible label that describes where the user will go. Follow the label and content guidelines below.
+2. **Underline:** The line treatment that supports affordance and focus. It works together with color and focus styles so users can recognize the control and understand where it leads.
+
+---
+
+Usage
+
+Use a **Link** when you want someone to **go somewhere**: another page, another site, another section on the same page, or a resource that opens in another app (for example, mail or phone).
+
+### When to use
+
+> [!TIP]
+>
+> **When the user should navigate to another destination**
+>
+> - ex: Open a different page or URL in the product.
+> - ex: Open an external website, PDF, or help article.
+
+> [!TIP]
+>
+> **When the user should jump within the same page**
+>
+> - ex: Anchor link to a lower section (“Jump to billing”).
+> - ex: Return to top or to a named heading on long content.
+
+> [!TIP]
+>
+> **When the user should open another app via a protocol**
+>
+> - ex: `mailto:` for email.
+> - ex: `tel:` for phone.
+
+### **When not to use**
+
+> [!CAUTION]
+>
+> **For actions that complete work on the current screen**
+>
+> - ex: Submit, Save, Delete (without navigating away as the main intent).
+> - ex: Open a dialog, menu, or drawer that acts on the current context.
+> - Instead, consider using a [Button](https://design.candescent.com/docs/components/button/content.md) component.
+
+> [!CAUTION]
+>
+> **When a control should match primary button hierarchy**
+>
+> - ex: The single most important next step in a flow (“Continue,” “Pay now”).
+> - ex: Destructive confirmation where the pattern is a [Button](https://design.candescent.com/docs/components/button/content.md), not body copy.
+
+> [!CAUTION]
+>
+> **When the UI is main application navigation**
+>
+> - ex: Primary nav, tabs, or menus built for wayfinding → use the navigation pattern or component, not ad hoc links.
+
+### Link color
+
+Most links should use the color.content.link color token. This color helps links be easily recognizable to users, especially as they are quickly scanning content. Links should read as an obvious destination—especially outside dense body copy (cards, footers, helper rows).
+
+- **Do:** Use the link color token for a single prominent “Schedule a demo” style link when it is the main affordance in that module.
+- **Don't:** Don’t apply link styling to multiple sentences. Only link the shortest, most descriptive phrase, such as “Contact us” or “Book a demo.”
+
+### Link versus ghost button
+
+**Ghost** **buttons** can look like links. Use **Link** for navigation semantics; use **Button** when the user performs an action **without** treating it as “go to a URL.”
+
+- **Do:** Use a button for actions like cancelling a task to clearly communicate that the action will trigger a change.
+- **Don't:** Don’t use link styling for actions like cancelling a task, as links imply navigation rather than an action.
+
+### Links in lists and paragraphs
+
+Lists inside running copy are a common place for **Link**. The goal is to keep each line **easy to scan** and each destination **obvious on its own**, including when people navigate by links (keyboard or screen reader) or tap on mobile.
+
+- **Do:** Put the link on the shortest phrase that still describes the destination for that list item so the line reads clearly with or without surrounding context.
+- **Don't:** Don’t repeat generic link labels on every row (“Details,” “Here,” “More”)—out of context every link sounds the same, and the list becomes hard to use for assistive technology users and for quick scanning on small screens.
+
+### Layout and placement
+
+The primary path forward on a surface (e.g. continue, save, confirm) should usually be a [Button](https://design.candescent.com/docs/components/button/content.md). **Links** support **navigation** or **reference** (help, policy, learn more) and sit **lower in the hierarchy** than that primary action.
+
+_usage\_text\_01-ex_
+
+### Breakpoints
+
+A Link’s width comes from **typography and layout**, not from fixed control widths like a Button. **Inline** links wrap with the surrounding text as the container narrows; **standalone** links span the content column and wrap like a line of copy unless your pattern constrains them.
+
+- **Mobile**
+
+  Within the Mobile breakpoint (width \< 600px), links should wrap naturally with surrounding text as the container narrows, ensuring readability without truncation or overflow.
+- **Desktop**
+
+  Within the larger breakpoint (width ≥ 600px), links should remain inline with surrounding text and only wrap when constrained by the layout or container width.
+
+On **narrow** viewports, plan for **multi-line** link labels: underlines and focus rings should follow the **full wrapped shape**, and tap targets for standalone links should stay comfortable when lines break. In **wide** layouts, links behave the same semantically, only the **measure** and **wrapping** change.
+
+---
+
+## Behavior
+
+### Interaction states
+
+By default, a Link is interactive. Visual feedback is applied consistently across touch, pointer, and keyboard interactions. **Underline behavior** is controlled by the underline prop and appears in response to the relevant interaction state, such as focus or hover.
+
+- **Resting**
+
+  Default appearance when the link is not hovered or focused.
+- **Hover**
+
+  Pointer is over the link’s interactive target (including expanded hit area if you use one).
+- **Focus**
+
+  Keyboard focus is on the link; the **focus indicator** must be visible and meet CDS focus guidance.
+
+### Visited
+
+When a user has opened a link’s destination in this browsing context, the browser marks it as **visited**, and the **Link** component applies **visited** styling automatically, using the color.content.link-visited color token so teams don’t need to wire this behavior manually.
+
+- **visited**
+
+  The destination has been opened in this browsing context per browser history / your routing rules.
+
+## Content
+
+## Link text
+
+Screen readers can scan a page for links and read them aloud independent of their context. For this reason, ensure that link text is purposeful and descriptive of the link destination. Avoid generic phrases like "learn more" and "here".
+
+| **Example**                                                                                                                                                                                                                         | **Read aloud by screen reader** |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| ✅ _Reimagine your account opening, digital banking and branch experiences with our integrated digital-first solutions._ _[Explore digital banking](https://cds-docs.d3vcloud.com/foundations/content-design/writing-for-all#)\*\*._ | ✅ _“Explore digital banking”_   |
+| ❌ _Reimagine your account opening, digital banking and branch experiences with our integrated digital-first solutions._ _[Learn more](https://cds-docs.d3vcloud.com/foundations/content-design/writing-for-all#)\*\*._              | ❌ _“Learn more”_                |
+| ❌ _Reimagine your account opening, digital banking and branch experiences with our integrated digital-first solutions. Click_ _[here](https://cds-docs.d3vcloud.com/foundations/content-design/writing-for-all#)_ _to learn more._  | ❌ _“here”_                      |
+
+Additionally, link text should be in sentence case.
+
+- ✅ Interested in learning more? [Schedule a demo](https://www.candescent.com/contact).
+- ❌ Interested in learning more? [Schedule a Demo](https://www.candescent.com/contact).
+- ❌ Interested in learning more? [schedule a demo](https://www.candescent.com/contact).
+
+## URLs as link text
+
+Links should typically be written in plain text that describes the link's destination. However, if you must to write out a URL, don't include `www.`, `http://`, or other protocol information in the link label.
+
+- ✅ Visit [candescent.com](https://www.candescent.com/) for more information.
+- ❌ Visit [www.candescent.com](https://www.candescent.com/) for more information.
+- ❌ Visit [https://www.candescent.com/](https://www.candescent.com/) for more information.