mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-12-06 17:27:57 +00:00

Files

akcodez 2ff14e4224 Add BDS link styles and update existing link styles

- Introduced new styles for BDS link icons, including hover and focus states.
- Updated existing link styles to exclude BDS links from certain color and hover effects.
- Ensured consistent styling across light and dark themes for BDS links.
- Refactored landing page link styles to accommodate new BDS link classes.

2025-12-02 10:21:52 -08:00

10 KiB

Raw Blame History

Link Component

A comprehensive, accessible link component from the XRPL.org Brand Design System (BDS). Supports multiple variants, sizes, and automatic theme-aware color states with animated arrow icons.

Installation
Basic Usage
Props API
Variants
Sizes
Color States
Icon Animations
Accessibility
Best Practices
Examples
Related Components

Installation

import { Link } from 'shared/components/Link';
// or
import { Link } from 'shared/components/Link/Link';

Basic Usage

// Internal link (default)
<Link href="/docs">View Documentation</Link>

// External link
<Link href="https://example.com" variant="external" target="_blank" rel="noopener noreferrer">
  External Resource
</Link>

// Inline link (no icon)
<p>
  Learn more about <Link href="/about" variant="inline">our mission</Link>.
</p>

Props API

Prop	Type	Default	Description
`href`	`string`	required	The URL the link points to
`variant`	`'internal' \| 'external' \| 'inline'`	`'internal'`	Link variant determining icon and behavior
`size`	`'small' \| 'medium' \| 'large'`	`'medium'`	Size of the link text and icon
`icon`	`'arrow' \| 'external' \| null`	`null`	Override icon type (auto-determined by variant if `null`)
`disabled`	`boolean`	`false`	Disables the link, preventing navigation
`children`	`React.ReactNode`	required	Link text content
`className`	`string`	-	Additional CSS classes
`...rest`	`AnchorHTMLAttributes`	-	All standard anchor attributes (`target`, `rel`, etc.)

Variants

Internal (Default)

For navigation within the same website. Displays a horizontal arrow (→) that animates to a chevron (>) on hover.

<Link href="/docs" variant="internal">
  Internal Documentation
</Link>

External

For links to external websites. Displays a diagonal arrow with corner bracket (↗) that animates on hover. Always use with target="_blank" and rel="noopener noreferrer" for security.

<Link 
  href="https://github.com/XRPLF" 
  variant="external" 
  target="_blank" 
  rel="noopener noreferrer"
>
  GitHub Repository
</Link>

Inline

For links embedded within body text. No icon is displayed, making the link flow naturally within paragraphs.

<p>
  The XRP Ledger is a decentralized blockchain. You can{" "}
  <Link href="/docs" variant="inline">read the documentation</Link>{" "}
  to learn more.
</p>

Sizes

Size	Font Size	Line Height	Icon Gap
`small`	14px	1.5	6px
`medium`	16px	1.5	8px
`large`	20px	1.5	10px

<Link href="/docs" size="small">Small Link</Link>
<Link href="/docs" size="medium">Medium Link</Link>
<Link href="/docs" size="large">Large Link</Link>

Color States

The Link component automatically handles color states based on the current theme. Colors are applied via CSS and follow the Figma design specifications.

Light Mode

State	Color Token	Hex Value	Additional Styles
Enabled	Green 400	`#0DAA3E`	No underline
Hover	Green 500	`#078139`	Underline, arrow animates
Focus	Green 500	`#078139`	Underline, black outline
Active	Green 400	`#0DAA3E`	Underline
Visited	Lilac 400	`#7649E3`	No underline
Disabled	Gray 400	`#A2A2A4`	No underline, no pointer

Dark Mode

State	Color Token	Hex Value	Additional Styles
Enabled	Green 300	`#21E46B`	No underline
Hover	Green 200	`#70EE97`	Underline, arrow animates
Focus	Green 200	`#70EE97`	Underline, white outline
Active	Green 300	`#21E46B`	Underline
Visited	Lilac 300	`#C0A7FF`	No underline
Disabled	Gray 500	`#838386`	No underline, no pointer

Focus Outline

Light Mode: 2px solid black (#000000)
Dark Mode: 2px solid white (#FFFFFF)

Icon Animations

Both internal and external arrow icons feature a smooth animation on hover/focus:

Animation Duration: 150ms
Timing Function: cubic-bezier(0.98, 0.12, 0.12, 0.98)

Internal Arrow Animation

The horizontal line of the arrow (→) shrinks from left to right, revealing a chevron shape (>).

External Arrow Animation

The diagonal line of the external arrow (↗) scales down toward the top-right corner, leaving just the corner bracket.

Disabled State

When disabled, the animation is disabled and the icon opacity is reduced to 50%.

Accessibility

The Link component follows accessibility best practices:

Focusable via Tab key
Activatable via Enter key
Clear focus indicator with high-contrast outline

ARIA Attributes

aria-disabled="true" is applied when the link is disabled
Icons are marked with aria-hidden="true" to prevent screen reader announcement

Best Practices

Use descriptive link text - Avoid "click here" or "read more"
External links - Consider adding "(opens in new tab)" for screen readers
Disabled state - Provide context for why the link is disabled

// Good - Descriptive link text
<Link href="/pricing">View pricing plans</Link>

// Bad - Non-descriptive
<Link href="/pricing">Click here</Link>

// External with screen reader context
<Link 
  href="https://example.com" 
  variant="external" 
  target="_blank"
  rel="noopener noreferrer"
  aria-label="GitHub Repository (opens in new tab)"
>
  GitHub Repository
</Link>

Best Practices

Do's

Use appropriate variants

// Internal navigation
<Link href="/about" variant="internal">About Us</Link>

// External sites
<Link href="https://github.com" variant="external" target="_blank" rel="noopener noreferrer">
  GitHub
</Link>

// Within paragraphs
<p>Learn about <Link href="/xrp" variant="inline">XRP</Link> today.</p>

Match size to context

// Navigation/CTA - use large
<Link href="/get-started" size="large">Get Started</Link>

// Body content - use medium
<Link href="/docs" size="medium">Documentation</Link>

// Footnotes/captions - use small
<Link href="/terms" size="small">Terms of Service</Link>

Always use security attributes for external links

<Link 
  href="https://external-site.com" 
  variant="external"
  target="_blank"
  rel="noopener noreferrer"
>
  External Site
</Link>

Don'ts

Don't use disabled for navigation prevention - Use proper routing instead

// Bad - Using disabled for auth gate
<Link href="/dashboard" disabled={!isAuthenticated}>Dashboard</Link>

// Good - Handle in onClick or router
<Link href="/dashboard" onClick={handleAuthCheck}>Dashboard</Link>

Don't mix variants inappropriately

// Bad - External link with internal variant
<Link href="https://example.com" variant="internal">External Site</Link>

// Good
<Link href="https://example.com" variant="external">External Site</Link>

Don't use inline variant for standalone links

// Bad - Standalone inline link
<Link href="/docs" variant="inline">Documentation</Link>

// Good - Use internal for standalone
<Link href="/docs" variant="internal">Documentation</Link>

Examples

<nav className="d-flex flex-column gap-3">
  <Link href="/docs" size="medium">Documentation</Link>
  <Link href="/tutorials" size="medium">Tutorials</Link>
  <Link href="/api" size="medium">API Reference</Link>
  <Link 
    href="https://github.com/XRPLF" 
    variant="external" 
    size="medium"
    target="_blank"
    rel="noopener noreferrer"
  >
    GitHub
  </Link>
</nav>

Call-to-Action Section

<div className="d-flex flex-column gap-4">
  <Link href="/get-started" size="large">
    Get Started with XRPL
  </Link>
  <Link href="/use-cases" size="large">
    Explore Use Cases
  </Link>
</div>

Rich Text Content

<article>
  <p>
    The XRP Ledger (XRPL) is a decentralized, public blockchain led by a{" "}
    <Link href="/community" variant="inline">global community</Link>{" "}
    of businesses and developers. It supports a wide variety of{" "}
    <Link href="/use-cases" variant="inline">use cases</Link>{" "}
    including payments, tokenization, and DeFi.
  </p>
  
  <p>
    To learn more, check out the{" "}
    <Link href="/docs" variant="inline">official documentation</Link>{" "}
    or visit the{" "}
    <Link 
      href="https://github.com/XRPLF" 
      variant="inline"
      target="_blank"
      rel="noopener noreferrer"
    >
      GitHub repository
    </Link>.
  </p>
</article>

Disabled State

<div className="d-flex flex-column gap-3">
  <Link href="/premium" size="medium" disabled>
    Premium Features (Coming Soon)
  </Link>
  <span className="text-muted">This feature is not yet available.</span>
</div>

LinkArrow - The animated arrow icon component used internally by Link
Button - For actions that don't navigate (forms, modals, etc.)

File Structure

shared/components/Link/
├── index.ts          # Exports
├── Link.tsx          # Main component
├── Link.md           # This documentation
├── LinkArrow.tsx     # Arrow icon component
├── _link.scss        # Link styles
└── _link-icons.scss  # Arrow icon styles & animations

Changelog

v1.0.0

Initial release with internal, external, and inline variants
Three size options (small, medium, large)
Theme-aware color states (light/dark mode)
Animated arrow icons
Full accessibility support

10 KiB

Raw Blame History

Link Component

Table of Contents

Installation

Basic Usage

Props API

Variants

Internal (Default)

External

Inline

Sizes

Color States

Light Mode

Dark Mode

Focus Outline

Icon Animations

Internal Arrow Animation

External Arrow Animation

Disabled State

Accessibility

Keyboard Navigation

ARIA Attributes

Best Practices

Best Practices

Do's

Don'ts

Examples

Navigation Menu

Call-to-Action Section

Rich Text Content

Disabled State

File Structure

Changelog

v1.0.0

10 KiB Raw Blame History

Link Component

Table of Contents

Installation

Basic Usage

Props API

Variants

Internal (Default)

External

Inline

Sizes

Color States

Light Mode

Dark Mode

Focus Outline

Icon Animations

Internal Arrow Animation

External Arrow Animation

Disabled State

Accessibility

Keyboard Navigation

ARIA Attributes

Best Practices

Best Practices

Do's

Don'ts

Examples

Navigation Menu

Call-to-Action Section

Rich Text Content

Disabled State

Related Components

File Structure

Changelog

v1.0.0

10 KiB

Raw Blame History