@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/input/design.md

@@ -0,0 +1,389 @@
+# Input Field — Design (https://design.candescent.com/docs/components/input)
+
+## Usage
+
+**Example**
+
+**Common alternative names**: Text input, text box, text area, free-response, form control
+
+---
+
+## **Anatomy**
+
+An input field is the simplest and most common form of user input. Its simplicity makes it flexible enough to support many different input types.
+
+**Anatomy\_input-field**
+
+1. **Label**: Text describing what the input field is asking for.
+2. **Placeholder text**: optional assistive text that appears within an empty field.
+3. **Helper text**: An optional line of assistive text attached to the bottom of the field.
+4. **Start adornment**: An optional icon, text string, or button shown at the start of the field.
+5. **Value**: The current value of the field.
+6. **End adornment**: An optional icon, text string, or button shown at the end of the field.
+
+### **Size**
+
+Input fields are available in 2 sizes: **Default** and **Small**. These sizes give you flexibility when building layouts, but a consistent size should be used for all input fields on the same page.
+
+- **size: default**
+
+  The default size and the most commonly used size. Has a height of 72px when used without helper text.
+
+### **Required**
+
+An input field can be designated as a required input. The user will be required to enter a value before continuing or submitting the form.
+
+- **size: default**
+
+  The default size and the most commonly used size. Has a height of 72px when used without helper text.
+- **size: small**
+
+  A smaller size that should only be used when space is limited, or in complex forms. Has a height of 44px when used without helper text.
+
+### **Helper text**
+
+Helper text is an optional line of assistive text attached to the bottom of an input field. It can provide critical information, instructions, format, acceptance criteria, or other important information that will help users complete the input. It should also be used to provide an explanation when the field is in an error state.
+
+- **Show Helper Text?: true**
+
+  A line of small text is shown below the field. This variant increases the field height.
+
+### **Placeholder text**
+
+Placeholder text is optional assistive text that appears within a field before it contains a value. It can provide hints or examples of what the user should enter into the field. It disappears when the user starts typing.
+
+- **Show Placeholder?: true**
+
+  A line of assistive text is shown in grey inside the field.
+
+### **Adornments**
+
+Adornments are used to add a prefix, a suffix, or an action to an input field. For example, you can add an icon button to reveal/hide the contents of a password field, or add a currency symbol to the start of a money input.
+
+- **Show Leading Adornment?: true**
+
+  An optional icon, text string, or button shown at the start of the field. Vertically aligned with the value.
+- **Show Trailing Adornment?: true**
+
+  An optional icon, text string, or button shown at the end of the field. Vertically centered in the field.
+
+### **Hidden label**
+
+When absolutely necessary, the label of a input field can be hidden. There are very, very few places where hiding the field’s label is recommended, so avoid using this variant whenever possible.
+
+- **Show Label?: false**
+
+  The field label is hidden.
+
+---
+
+**Usage**
+
+Input fields should be used in forms to collect freeform text. The text can range in length from a single word to a few lines. However, if the text input is predictable and could be selected from a pre-defined list of options, consider using a [Select field](https://design.candescent.com/docs/components/select/content.md) or Autocomplete instead.
+
+### **When to use**
+
+> [!TIP]
+>
+> **Free response questions**
+>
+> - ex: “First name” or “Last name” on a form
+> - ex: The “Subject” field in an email
+> - ex: A “Comments” field on a product review form
+
+> [!TIP]
+>
+> **For collecting information that should follow a specific format**
+>
+> - ex: Email address
+> - ex: Phone number
+> - ex: ZIP code in a shipping address form
+> - ex: Dollar amount in a money transfer form
+
+### **When not to use**
+
+> [!CAUTION]
+>
+> **When the user needs to choose an option from a finite list**
+>
+> - ex: Select an account to use in a money transfer form
+> - ex: A yes or no question
+> - ex: Select a sorting option when viewing a list of transactions
+
+### **Layout and placement**
+
+Input fields are typically found on forms. When placing the component, make sure it is appropriately spaced from other form fields to prevent confusion.
+
+When using a input field in a form, please see the Form Pattern for additional guidance about layout and placement.
+
+### **Using helper text**
+
+Helper text is an optional line of assistive text attached to the bottom of an input. It can provide instructions, format, acceptance criteria, or other important information that will help the user complete the field.
+
+#### **When to use helper text**
+
+Helper text should only be used when necessary. Too much helper text will clutter the screen, and may overload the user. Use these guidelines to decide if helper text would be beneficial for your input field:
+
+- Does the field require a specific format to be valid/accepted?
+- Does the field require or prohibit specific characters?
+- Will most users need additional information to understand what the input is asking for?
+- Will users want to know why, how, or where their response will be used? Will they hesitate to answer without that info?
+
+Addressing these needs will help the user complete the input more quickly and with less errors.
+
+- **Do:** Include helper text when the input requires a specific format. Placeholder text is not enough.
+- **Do:** Include helper text when the input has character limits or a character restriction.
+- **Do:** Include helper text when the user needs additional info to understand exactly what the input is asking for.
+
+#### **When not to use helper text**
+
+Do not use helper text in place of a label, or to indicate that the input is required.
+
+- **Don't:** Don’t use helper text to indicate that an input is required.
+- **Don't:** Don’t use helper text in place of an input label.
+
+### **Using placeholder text**
+
+Placeholder text is an optional line of assistive text that appears within a field before it contains a value. It can provide hints or examples of what the user should enter into the field.
+
+#### **When to use placeholder text**
+
+Placeholder text can cause usability problems. Users may see placeholder text in a field and assume that the have already completed the field. Due to this risk, ensure that placeholder text is only used when necessary.
+
+Use these guidelines to decide if placeholder text would be beneficial for your input field:
+
+- Will the placeholder text complement the field’s helper text in a useful way?
+- Would users benefit from seeing an example of the value format as placeholder text?
+- Will the placeholder text help clarify the purpose of a field?
+- _**Will the benefits of using the placeholder text outweigh the potential usability risks?**_
+
+* **Do:** Placeholder text is acceptable in a search field, especially if it doesn’t have a visible label. Search fields are one of the only acceptable implementations of the hiddenLabel property.
+* **Caution:** Placeholder text can be used to provide an example of the desired format. This example informs users that they should enter their standard 5 digit ZIP code, not the expanded 9-digit code used by USPS. Keep in mind that this example will disappear once the user starts typing.
+
+#### **When not to use placeholder text**
+
+Placeholder text disappears once the user starts typing in the field. Therefore, it should not be used to convey instructions, format, acceptance criteria, or other important information the user will need to complete the field. In most cases, helper text is the preferred method of providing assistive text.
+
+- **Don't:** Don’t user placeholder text to inform users about the desired format. Use helper text instead.
+- **Don't:** Don’t use placeholder text to inform users about length requirements, character restrictions, or other acceptance criteria. Use helper text instead.
+- **Don't:** Don’t repeat the field’s label as placeholder text, and don’t instruct the user to fill out the field with placeholder text.
+
+### **Character limits**
+
+Character limits on input fields should be used sparingly. They should not be imposed on the user unless there is some technical limitation or logical reason. Use these guidelines to decide if imposing a character limit is a good idea:
+
+**❓** **Does an API, database, or other technical service have a character limit?**
+
+- ex: When a form is submitted, the API used to submit the information to the system can only accept values less than 255 characters
+- ex: The specific database structure being used for a product limits the length of strings to 100 characters
+
+**❓ Does the input type have a common-knowledge or standardized character limit?**
+
+- ex: All credit card numbers are 19 digits or less
+- ex: Credit card CVV/CVC numbers are 3 or 4 digits
+
+**❓ Will the value of the input be displayed on a physical object with a limited area?**
+
+- ex: The name printed on a credit card has a limit of 26 characters based on the physical width of the card
+
+If you decide to enforce a character limit on your field, see the Enforcing character limit section for enforcement and behavior guidelines.
+
+### **Character restrictions**
+
+The types of characters a user can enter into an input field should not be restricted unless there is some technical limitation or logical reason. In general, all Unicode characters should be permitted whenever possible. This includes:
+
+- Spaces and punctuation
+- Numbers
+- Supplemental alphabet characters (ñ, ç, ř)
+- Characters from other alphabets (Π, Ϛ, Я)
+- Special characters (▲, ✻, ➔) and Emoji (😁, ✌️, ♿)
+
+Use these guidelines to decide if imposing a restriction on special characters is a good idea:
+
+**❓ Does an API, database, or other technical service have character restrictions?**
+
+- ex: When a form is submitted, the API used to submit the information to the system cannot accept Emoji
+- ex: ex: A specific bank only allows their transaction memos to include alphanumeric characters
+
+**❓ Does the input type have a common-knowledge or standardized character restrictions?**
+
+- ex: Credit card numbers are only numeric characters
+- ex: Street addresses do not contain Emoji
+
+**❓ Will the value of the input be displayed on a physical object with a limited character set?**
+
+- ex: The name printed on a credit card cannot contain special characters or diacritics (Raúl Núñez becomes RAUL NUNEZ)
+
+In this example, the financial institution is using an API that does not restrict any characters from being used in an account name.
+
+- **Do:** Allow all unicode characters when possible.
+- **Caution:** Don’t restrict characters without a logical reason or technical limitation.
+
+If you decide to enforce a character limit on your field, see the Enforcing character restrictions section for enforcement and behavior guidelines.
+
+---
+
+## **Behavior**
+
+### **Interaction states**
+
+The default state of an input field is clickable and editable. The appearance of the field will respond as the user interacts with it.
+
+- **Resting**
+
+  Default state. User is not interacting with or typing in the field.
+- **Hover**
+
+  When the user’s cursor is hovering over the field.
+- **Focus**
+
+  When a keyboard user is focused on the field using tab navigation controls. In this state, the user can type into the field.
+
+### **Disabled**
+
+The input field can be disabled, which prevents the user from clicking on or interacting with the field in any way, including editing the current value. Using disabled fields can cause accessibility issues, so avoid using this state wherever possible.
+
+- **isDisabled: true**
+
+  In this state, the user cannot interact with the field or edit its current value. The value appears greyed out.
+
+### **Read only**
+
+The input field component can be set to read only mode, which prevents the user from editing the value of the field. Unlike the disabled state, the user can still interact with this field through hover and keyboard focus, allowing screen readers to read out the current value of the field.
+
+- **isReadOnly: true**
+
+  In this state, the user cannot edit the value of the field. However, the value remains fully visible, and the user can still interact with the field.
+
+### **Error state**
+
+When the user enters an invalid value or otherwise makes a mistake, the input field should react by switching to the error state. The input field should highlight red, and the helper text should show an error message.
+
+- **error: true**
+
+  When the user enters an invalid value or otherwise makes a mistake.
+
+#### **Showing error helper text**
+
+Helper text is **required** when the input is in an error state. If the input already had helper text before the error state, the helper text should change. If no helper text was present before the error, the error helper text should push down any content below the field.
+
+- **Example 1: Changing helper text**
+
+  In this example, the original field already had helper text. It should change when the field is in an error state.
+- **Example 2: New helper text**
+
+  In this example, the original did not have helper text. It should be added in when the field moves to an error state. Notice how the content below the field is pushed down.
+
+See the Writing error helper text section for details on how error helper text should be phrased.
+
+### **Placeholder text is temporary**
+
+If placeholder text is used, keep in mind that it will disappear once the user starts typing. See the previous Using placeholder text section to decide if placeholder text is right for your input field.
+
+_behavior\_placeholder\_01-ex_
+
+### **Enforcing character limit**
+
+See the previous Character limits section to determine if a character limit should be enforced on your input field.
+
+If a field does have a character limit, it’s important to consider when and how the user should be informed about the character limit. Use the following guidelines based on how likely the user is to reach the character limit.
+
+#### **Reaching the limit is common**
+
+If it is common for the user to reach the character limit in a field:
+
+1. Inform them of the character limit in the helper text before they begin typing:
+   - _Max length is_ _**X**_ _characters_
+2. As the user begins typing, the helper text does not change.
+3. Once the user’s input reaches 80% of the character limit, change the helper text to:
+   - _**X**_ _characters remaining_
+4. Continue changing the count as the user types. If they go back below 80%, revert to the original helper text.
+5. If the input reaches the character limit, allow the user to keep typing. Change the field to an error state, and change the helper text to:
+   - _**X**_ _characters over limit_
+
+#### **Reaching the limit is NOT common**
+
+If it is uncommon for the user to reach the character limit in a field:
+
+1. Don’t inform them of the character limit in the helper text before they begin typing.
+2. If the input does reach 80% of the character limit, then introduce helper text:
+   - _**X**_ _characters remaining_
+3. Continue changing the count as the user types. If they go back below 80%, hide the helper text.
+4. If the input reaches the character limit, allow the user to keep typing. Change the field to an error state, and change the helper text to:
+   - _**X**_ _characters over limit_
+
+### **Enforcing character restrictions**
+
+See the previous Character restrictions section to determine if a character limit should be enforced on your input field.
+
+If a field does have character restrictions, it’s important to consider when and how the user should be informed about the character limit. Use the following guidelines to determine how to best enforce character limits for your field.
+
+If there are only a few restricted characters, but they are **common** characters, the user should be informed of the restrictions in the helper text. In the example below, the financial institution is using an API that does not allow a few common characters: **$** **%** **#**
+
+- **Do:** When only a characters are restricted, and they are common characters, list them out in the helper text before the user starts typing.
+- **Don't:** When the restricted characters are common, don’t wait until a validation error occurs to inform the user of the restriction.
+
+If there are only a few restricted characters, but they are **uncommon** characters, the user does not need to be informed in the helper text until a validation error occurs. In the example below, the financial institution is using an API that does not allow a few uncommon characters: **§** **‡**
+
+- **Do:** If it is unlikely that the user will enter the restricted characters, wait until they actually input a restricted character before informing them.
+- **Caution:** While informing users about character restrictions in the helper text is usually recommended, including it for very uncommon characters will take up unnecessary vertical space.
+
+If only a specific set of characters is allowed, the user should be informed of the restrictions in the helper text. When possible, summarize the allowed characters instead of listing them out. In the example below, the financial institution is using an API that only allows alphanumeric characters in an account name.
+
+- **Do:** Summarize what characters are allowed in the helper text to inform the user before they begin typing.
+- **Don't:** When only a specific set of characters is allowed, don’t wait until a validation error occurs to inform the user of the restriction.
+
+If a field has character restrictions that are common-knowledge, the restrictions do not need to be explained in the helper text. If the user does enter a non-permitted character, the error should be explained in the helper text.
+
+- **Do:** For fields with common-knowledge restrictions, wait until the user makes an error to inform them that their input is invalid. In this example, email addresses have other validation steps aside from what characters are allowed, so checking for restricted characters should just be part of that validation process.
+- **Don't:** Don’t use the helper text to try and explain long and/or complicated rules to the user. It is not practical or useful to the user. If the user were creating an email address in this example, then explaining some rules may be helpful. But it should not be done in the helper text.
+
+## Content
+
+## **Label**
+
+Every input field in a form should have a corresponding label that helps the user understand what the input means. Labels should clearly and concisely describe the value or response requested from the user.
+
+Use these guidelines when writing labels:
+
+- Use between 1 to 3 words when possible
+- Labels should be written in sentence case (aside from proper nouns)
+- Don’t include a colon (:) after the label
+
+* **Do:** In this example, the labels are short, but are also clearly asking the user to create a name and select a type for the new account they are creating.
+* **Don't:** In this example, the labels are too short, so they becomes ambiguous. Is “Name” asking for the user’s name, the bank’s name, or the account’s name? And what is “Type” referring to? The user can’t know for sure before responding.
+* **Don't:** In this example, the labels are too long. The user already understands that they are being asked to complete the form, so the action verbs are not necessary.
+
+**Helper text**
+
+Helper text should be short and concise, and only provide information that is crucial to helping the user complete the form. Use these guidelines when writing helper text:
+
+- Aim for 1 line of text
+- Longer helper text should wrap to the next line, and not go too far past the longest option label
+- Helper text should be written in sentence case (aside from proper nouns)
+
+* **Do:** When writing helper text, aim for a single line of text. If the text must be longer, it should wrap down to a second line.
+* **Don't:** Helper text should not be longer than the input area. Wrap longer text down to a second line.
+
+### **Error helper text**
+
+Helper text must always be included when the input is an an error state. The combination of the icon, red color, and text must help the user understand:
+
+1. The field has an error
+2. What the error is
+3. How the user can correct their input and resolve the error
+
+- **Do:** This example concisely tells the user that there is an error, what the error is, and what they can do to resolve it.
+- **Caution:** Avoid vague explanations. This example tells the user that there is an error, but is not specific enough about why the value is invalid.
+- **Don't:** Don’t write unnecessarily long helper text. This example meets all the criteria listed above, but it is too long.
+
+**Placeholder text**
+
+If you do decide to use placeholder text, it should should be short and concise. It disappears when the user starts typing, so it should only provide information or hints that are not crucial. Use these guidelines when writing helper text:
+
+- Do not exceed the bounds of the input field (truncation)
+- Use anonymized values instead of real ones when possible
+- Do not repeat the field’s label as placeholder text
+
+* **Do:** Use anonymized values in placeholder text to avoid confusion. The inclusion of “e.g.” before the example helps the user understand that this is an example, not a value they have actually filled in.
+* **Don't:** Don’t use values in placeholder text that look real or are real. This may accidentally trick users into thinking they already completed the field, which will lead to an error when they try to submit the form.

package/docs/components/insurance-disclosure/content.md

@@ -0,0 +1,103 @@
+# FDIC Digital Sign (https://design.candescent.com/docs/components/insurance-disclosure)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=8550-3291), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/domain-insurancedisclosure--default)
+
+Presents the official FDIC lockup alongside optional disclosure copy. When `logoSource` is omitted, the bundled FDIC mark is rendered. Logo, accessible label, and copy are controlled via props — not a compound component.
+
+```tsx
+import { InsuranceDisclosure } from '@cdx-ui/components';
+```
+
+## Basic
+
+Unframed disclosure with Figma statement copy. This is the default layout — no border or padding on the root.
+
+```tsx
+import { InsuranceDisclosure } from '@cdx-ui/components';
+
+const FIGMA_STATEMENT = 'FDIC-Insured—Backed by the full faith and credit of the U.S. Government';
+
+export default function InsuranceDisclosureBasicDemo() {
+  return <InsuranceDisclosure label={FIGMA_STATEMENT} />;
+}
+```
+
+## Framed
+
+Pass `framed` to add surface chrome (background, border, radius, and padding). Prior versions always rendered this chrome; existing usages that need it must opt in with `framed`.
+
+```tsx
+import { InsuranceDisclosure } from '@cdx-ui/components';
+
+const FIGMA_STATEMENT = 'FDIC-Insured—Backed by the full faith and credit of the U.S. Government';
+
+export default function InsuranceDisclosureFramedDemo() {
+  return <InsuranceDisclosure framed label={FIGMA_STATEMENT} />;
+}
+```
+
+## Logo only
+
+Omit `label` to render just the bundled FDIC lockup.
+
+```tsx
+import { InsuranceDisclosure } from '@cdx-ui/components';
+
+export default function InsuranceDisclosureLogoOnlyDemo() {
+  return <InsuranceDisclosure />;
+}
+```
+
+## Long copy
+
+Longer disclosure text wraps within the row; constrain width at the layout level when needed.
+
+```tsx
+import { Box, InsuranceDisclosure } from '@cdx-ui/components';
+
+export default function InsuranceDisclosureLongCopyDemo() {
+  return (
+    <Box className="max-w-md">
+      <InsuranceDisclosure
+        label={
+          'FDIC-Insured—Backed by the full faith and credit of the U.S. Government. ' +
+          'Deposits are insured up to the maximum amount permitted by law. ' +
+          'Please contact your financial institution for full terms and coverage details.'
+        }
+      />
+    </Box>
+  );
+}
+```
+
+## API
+
+### InsuranceDisclosure
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `space?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl'` | — | — |
+| `reversed?` | `boolean` | — | — |
+| `logoSource?` | `string \| ImageSourcePropType` | — | — |
+| `logoAccessibilityLabel?` | `string` | — | — |
+| `framed?` | `boolean` | — | — |
+| `label?` | `string` | — | — |
+
+Wraps `HStack` — all `HStackProps` except `children` are supported (`space`, `reversed`, and [`ViewProps`](https://reactnative.dev/docs/view#props)).
+
+## Anatomy
+
+Renders an `HStack` with `space="md"` containing the FDIC lockup and, when `label` is provided, italic disclosure text. When `framed` is `true`, the root also has surface chrome (`bg-surface-primary`, border, radius, `px-3 py-2`). Content is driven by props, not sub-components.
+
+| `data-slot`                    | Element                                  |
+| ------------------------------ | ---------------------------------------- |
+| `insurance-disclosure`         | Root row                                 |
+| `insurance-disclosure-logo`    | Logo (bundled SVG or custom image)       |
+| `insurance-disclosure-content` | Label wrapper (only when `label` is set) |
+
+## Accessibility
+
+- When `logoSource` is omitted, the bundled FDIC lockup uses `accessibilityLabel="FDIC"`.
+- When `logoSource` is set, `logoAccessibilityLabel` is **required** — the custom logo is exposed via `accessibilityLabel`.
+- The disclosure `label` is static text and is not a live region; announce dynamic regulatory changes elsewhere.

package/docs/components/link/content.md

@@ -0,0 +1,180 @@
+# Link (https://design.candescent.com/docs/components/link)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=457-874), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/actions-link--open-in-new-tab)
+
+A compound component with sub-components for label and icon. Router-agnostic — integrate with Expo Router, React Navigation, or Next.js via `LinkProvider`.
+
+```tsx
+import { Link } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { Link } from '@cdx-ui/components';
+
+export default function LinkBasicDemo() {
+  return (
+    <Link href="https://example.com">
+      <Link.Label>Settings</Link.Label>
+    </Link>
+  );
+}
+```
+
+## With icons
+
+Use `Link.Icon` for a leading or trailing icon alongside the label.
+
+```tsx
+import { Link, Box } from '@cdx-ui/components';
+import { ChevronRight, Link2 } from '@cdx-ui/icons';
+
+export default function LinkWithIconDemo() {
+  return (
+    <Box className="gap-4">
+      <Link href="https://example.com/manage">
+        <Link.Label>Manage</Link.Label>
+        <Link.Icon as={ChevronRight} />
+      </Link>
+      <Link href="https://example.com/details">
+        <Link.Icon as={Link2} />
+        <Link.Label>Details</Link.Label>
+      </Link>
+    </Box>
+  );
+}
+```
+
+## Open in new tab
+
+Pass web-only anchor attributes through `webProps`.
+
+```tsx
+import { Link } from '@cdx-ui/components';
+
+export default function LinkOpenInNewTabDemo() {
+  return (
+    <Link href="https://example.com" webProps={{ target: '_blank', rel: 'noopener' }}>
+      <Link.Label>Open in new tab</Link.Label>
+    </Link>
+  );
+}
+```
+
+## Inline with text
+
+On web, `Link` flows inline with surrounding text. On native, use a flex row layout instead of nesting inside `Text`.
+
+```tsx
+import { Link, Text } from '@cdx-ui/components';
+
+export default function LinkInlineDemo() {
+  return (
+    <Text>
+      Read our{' '}
+      <Link href="https://example.com/terms">
+        <Link.Label>Terms of Service</Link.Label>
+      </Link>{' '}
+      and{' '}
+      <Link href="https://example.com/privacy">
+        <Link.Label>Privacy Policy</Link.Label>
+      </Link>
+      .
+    </Text>
+  );
+}
+```
+
+## Visited
+
+On web, visited styling uses the native CSS `:visited` pseudo-class. On native, pass `isVisited`.
+
+```tsx
+import { Link, Box } from '@cdx-ui/components';
+
+export default function LinkVisitedDemo() {
+  return (
+    <Box className="gap-4">
+      <Link href="https://example.com">
+        <Link.Label>Default link</Link.Label>
+      </Link>
+      <Link href="https://example.com/visited" isVisited>
+        <Link.Label>Visited link</Link.Label>
+      </Link>
+    </Box>
+  );
+}
+```
+
+## API
+
+### Link
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default pressable host. |
+| `href?` | `string` | — | URL or route path opened on press. Omit when the link only runs `onPress`. |
+| `action?` | `'navigate' \| 'push' \| 'replace'` | — | Navigation action forwarded to the `LinkProvider`. Defaults to `'navigate'`. |
+| `isVisited?` | `boolean` | — | If true, the link will render in its visited style (native). On web, visited styling is driven by the CSS `:visited` pseudo-class. |
+| `webProps?` | `React.AnchorHTMLAttributes<HTMLAnchorElement>` | — | HTML anchor attributes applied only on web. Ignored on native platforms. `target`, `rel`, and `download` are forwarded via react-native-web's `hrefAttrs`. |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props) (including `onPress`).
+
+## Sub-components
+
+### Link.Label
+
+Styled text content inside the link. Uses `text-content-link` with underline and offset.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | Renders the consumer's child element in place of the default `Text` host. |
+
+Inherits all [`TextProps`](https://reactnative.dev/docs/text#props).
+
+### Link.Icon
+
+Renders a Forge icon inside the link. Sized to match the label with `text-content-link` color.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `filled?` | `boolean` | — | When `true`, renders the filled variant of the icon (if available). Defaults to `false` (outlined). |
+| `size?` | `string \| number` | — | Width and height of the icon, in pixels or any SVG length. The bare icon renders at 24 when omitted. |
+| `data-testid?` | `string` | — | Test identifier forwarded to the rendered SVG. |
+| `as` | `ForgeIcon` | — | The `@cdx-ui/icons` component to render. |
+
+Inherits all `ForgeIconProps` (react-native-svg `SvgProps` plus `filled` and `size`).
+
+## LinkProvider
+
+Wrap your app to integrate `Link` with your router. Without a provider, links behave like `<a>` on web and call `Linking.openURL` on native.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `navigate` | `(href: string, action: LinkAction) => void \| Promise<void>` | — | Global navigation handler for `<Link>` instances whose `href` passes the `shouldNavigate` check. Called with the `href` and the per-instance `action`. |
+| `shouldNavigate?` | `((href: string) => boolean)` | — | Optional predicate evaluated at **render time** to decide whether the provider should handle a given `href`. - Returns `true` → the provider's `navigate` is called on press; on web the native `<a href>` is **removed** so the browser doesn't follow the link. - Returns `false` → the provider is bypassed; on web the `<a href>` is preserved (cmd-click, SEO, etc.); on native `Linking.openURL` is used. Defaults to `() => true` when omitted (all hrefs go through the provider). |
+| `children` | `ReactNode` | — | — |
+
+Use `shouldNavigate` to keep external URLs on the native `<a>` / `Linking.openURL` path (preserves cmd-click and “Copy link address” on web).
+
+```tsx
+import { LinkProvider, type LinkAction } from '@cdx-ui/components';
+
+function shouldNavigate(href: string): boolean {
+  return !/^https?:\/\//.test(href);
+}
+
+function navigate(href: string, action: LinkAction) {
+  // e.g. router.navigate / router.push / router.replace
+}
+
+<LinkProvider navigate={navigate} shouldNavigate={shouldNavigate}>
+  {children}
+</LinkProvider>
+```