xrpl-dev-portal/shared/components/CardStat/CardStat.md

CardStat Component Documentation

Overview

The CardStat component is a statistics card that displays prominent numerical data with a descriptive label and optional call-to-action buttons. Following the XRPL Brand Design System (BDS), it supports four color variants and responsive layouts to showcase key metrics and statistics effectively.

Features

• Four Color Variants: Lilac (default), Green, Light Gray, and Dark Gray
• Flexible Content: Large statistic text with descriptive label
• Optional CTAs: Support for 0, 1, or 2 buttons (Primary and/or Secondary)
• Responsive Design: Adaptive sizing and typography across breakpoints
• Theme Support: Automatic light/dark mode adaptation
• Accessible: Semantic HTML with proper button accessibility

Props API

interface ButtonConfig {
  /** Button label text */
  label: string;
  /** Click handler for button */
  onClick?: () => void;
  /** Link href for button */
  href?: string;
}

interface CardStatProps {
  /** The main statistic to display (e.g., "6 Million+") */
  statistic: string;
  /** Descriptive label for the statistic */
  label: string;
  /** Background color variant */
  variant?: 'lilac' | 'green' | 'light-gray' | 'dark-gray';
  /** Primary button configuration */
  primaryButton?: ButtonConfig;
  /** Secondary button configuration */
  secondaryButton?: ButtonConfig;
  /** Additional CSS classes */
  className?: string;
}

Default Values

• variant: 'lilac'
• primaryButton: undefined (no button)
• secondaryButton: undefined (no button)
• className: ''

Color Variants

Lilac (Default)

A purple/lavender background that provides a soft, friendly appearance.

Best For:

• User-focused statistics (active wallets, users)
• Community metrics
• Engagement statistics

Usage:

<CardStat 
  statistic="6 Million+" 
  label="Active wallets"
  variant="lilac"
/>

Green

XRPL brand green background that reinforces brand identity.

Best For:

• Financial metrics (transaction volume, value moved)
• Growth statistics
• Positive indicators

Usage:

<CardStat 
  statistic="$1 Trillion+" 
  label="Value moved"
  variant="green"
/>

Light Gray

Light gray background for technology and reliability metrics.

Best For:

• Technical statistics (uptime, performance)
• Infrastructure metrics
• Stability indicators

Usage:

<CardStat 
  statistic="12+" 
  label="Continuous uptime years"
  variant="light-gray"
/>

Dark Gray

Neutral dark gray background for general-purpose statistics.

Best For:

• Neutral metrics
• Secondary information
• Supporting statistics

Usage:

<CardStat 
  statistic="70+" 
  label="Ecosystem partners"
  variant="dark-gray"
/>

Button Configurations

No Buttons

Display statistics without call-to-action buttons for informational purposes.

<CardStat 
  statistic="6 Million+" 
  label="Active wallets"
  variant="lilac"
/>

Single Button (Primary)

Include one primary button for a main call-to-action.

<CardStat 
  statistic="6 Million+" 
  label="Active wallets"
  variant="lilac"
  primaryButton={{
    label: "Learn More",
    href: "/wallets"
  }}
/>

Two Buttons (Primary + Secondary)

Include both primary and secondary buttons for multiple actions.

<CardStat 
  statistic="6 Million+" 
  label="Active wallets"
  variant="lilac"
  primaryButton={{
    label: "Learn More",
    href: "/wallets"
  }}
  secondaryButton={{
    label: "Get Started",
    onClick: handleGetStarted
  }}
/>

How It Works

Component Structure

The CardStat component uses BEM (Block Element Modifier) naming convention with the bds namespace:

• .bds-card-stat - Base card class
• .bds-card-stat--lilac - Lilac variant modifier
• .bds-card-stat--green - Green variant modifier
• .bds-card-stat--light-gray - Light gray variant modifier
• .bds-card-stat--dark-gray - Dark gray variant modifier
• .bds-card-stat__content - Inner content wrapper
• .bds-card-stat__text - Text section container
• .bds-card-stat__statistic - Large statistic text
• .bds-card-stat__label - Descriptive label text
• .bds-card-stat__buttons - Button container
• .bds-card-stat__button-link - Link wrapper for buttons

Layout

The card uses flexbox for vertical layout:

1. Content wrapper (.bds-card-stat__content): Main container with padding
2. Text section (.bds-card-stat__text): Contains statistic and label
3. Buttons section (.bds-card-stat__buttons): Optional CTA buttons

The layout automatically adjusts spacing between sections using flexbox justify-content: space-between.

Responsive Behavior

The component adapts to different screen sizes:

Base (Mobile, <576px):

• Padding: 8px
• Min height: 200px
• Statistic: 64px font size
• Label: 16px font size

MD (Tablet, ≥576px):

• Padding: 12px
• Min height: 208px
• Same typography as mobile

LG+ (Desktop, ≥992px):

• Padding: 16px
• Min height: 298px
• Statistic: 72px font size
• Label: 18px font size

Button Integration

Buttons use the existing BDS Button component with color="black" variant to ensure proper contrast on colored backgrounds. Buttons can be either:

• Links (href provided): Wrapped in an anchor tag for navigation
• Actions (onClick provided): Rendered as interactive buttons

Typography

Statistic Text

• Font: Booton, sans-serif
• Weight: 228 (Light)
• Size: 64px (mobile), 72px (desktop)
• Line Height: 70.4px (mobile), 79.2px (desktop)
• Letter Spacing: -4.5px (mobile), -5px (desktop)

Label Text

• Font: Booton, sans-serif
• Weight: 400 (Regular)
• Size: 16px (mobile), 18px (desktop)
• Line Height: 23.2px (mobile), 26.1px (desktop)
• Letter Spacing: 0px (mobile), -0.5px (desktop)

Spacing & Layout

• Border Radius: 8px
• Button Gap: 8px between buttons
• Text Gap: 4px between statistic and label
• Min Heights: 200px (mobile), 208px (tablet), 298px (desktop)

Usage Examples

Basic Usage

import { CardStat } from 'shared/components/CardStat';

// Simple statistic card
<CardStat 
  statistic="6 Million+" 
  label="Active wallets"
/>

// With color variant
<CardStat 
  statistic="$1 Trillion+" 
  label="Value moved"
  variant="green"
/>

With Buttons

// Single button (Light Gray variant)
<CardStat 
  statistic="12+" 
  label="Continuous uptime years"
  variant="light-gray"
  primaryButton={{
    label: "Learn More",
    href: "/about/uptime"
  }}
/>

// Two buttons (Dark Gray variant)
<CardStat 
  statistic="70+" 
  label="Ecosystem partners"
  variant="dark-gray"
  primaryButton={{
    label: "View Partners",
    href: "/partners"
  }}
  secondaryButton={{
    label: "Become Partner",
    onClick: handlePartnerSignup
  }}
/>

In PageGrid Layout

import { CardStat } from 'shared/components/CardStat';
import { PageGrid, PageGridRow, PageGridCol } from 'shared/components/PageGrid/page-grid';

<PageGrid>
  <PageGridRow>
    <PageGridCol span={{ base: 4, md: 4, lg: 4 }}>
      <CardStat 
        statistic="6 Million+" 
        label="Active wallets"
        variant="lilac"
      />
    </PageGridCol>
    <PageGridCol span={{ base: 4, md: 4, lg: 4 }}>
      <CardStat 
        statistic="$1 Trillion+" 
        label="Value moved"
        variant="green"
      />
    </PageGridCol>
    <PageGridCol span={{ base: 4, md: 4, lg: 4 }}>
      <CardStat 
        statistic="12+" 
        label="Continuous uptime years"
        variant="light-gray"
      />
    </PageGridCol>
  </PageGridRow>
</PageGrid>

With Click Handlers

const handleLearnMore = () => {
  console.log('Learn more clicked');
};

<CardStat 
  statistic="6 Million+" 
  label="Active wallets"
  variant="lilac"
  primaryButton={{
    label: "Learn More",
    onClick: handleLearnMore
  }}
/>

Accessibility

Semantic HTML

• Uses <div> elements with proper structure
• Button components handle their own accessibility
• Text content is readable by screen readers

Keyboard Navigation

• Buttons are fully keyboard accessible (Tab, Enter, Space)
• Links are keyboard navigable (Tab, Enter)
• Focus indicators provided by Button component

Color Contrast

All variants meet WCAG AA standards:

• Black text on colored backgrounds: Sufficient contrast
• Buttons: Use black variant with proper contrast on all backgrounds
• Dark mode dark gray: Switches to white text for proper contrast

Best Practices

1. Keep statistics concise - Use abbreviations (M for million, K for thousand)
2. Use descriptive labels - Make it clear what the statistic represents
3. Choose appropriate variants - Match color to the type of metric
4. Limit button usage - Use buttons only when actionable context is needed
5. Consider grid layouts - Use PageGrid for consistent spacing and alignment
6. Test responsiveness - Verify cards adapt properly at all breakpoints

When to Use

Use CardStat to:

• Highlight key metrics - Show important numbers prominently
• Dashboard sections - Create stat-focused areas on landing pages
• About pages - Showcase company or product statistics
• Feature sections - Emphasize quantitative benefits
• Report summaries - Display high-level data points

When NOT to Use

Avoid CardStat when:

• Complex data - Use charts or tables for detailed information
• Multiple related metrics - Consider data visualization components
• Non-numeric content - Use regular cards for text-heavy content
• Real-time updates - Consider dedicated dashboard components

Design Tokens

The component uses design tokens from the XRPL Brand Design System:

Colors

• $bds-card-stat-lilac-bg: #D9CAFF
• $bds-card-stat-green-bg: $green-300 (#EAFCF1)
• $bds-card-stat-light-gray-bg: #CAD4DF (light gray)
• $bds-card-stat-dark-gray-bg: #8A919A (dark gray)
• Text: #141414 (neutral black)

Spacing

• Border radius: 8px
• Button gap: 8px
• Text gap: 4px
• Content padding: 8px (mobile), 12px (tablet), 16px (desktop)

Motion

• Transition duration: 150ms
• Timing function: cubic-bezier(0.98, 0.12, 0.12, 0.98)

Theme Support

The component automatically adapts for light and dark modes:

Light Mode (Default)

• All color variants use their defined light backgrounds
• Black text on colored backgrounds

Dark Mode

• Dark Gray variant: Switches to darker gray background ($gray-400) with white text
• Other variants: Maintain colored backgrounds with black text

Showcase

See the interactive showcase at /about/cardstat-showcase for live examples of all variants, button configurations, and responsive behavior in PageGrid layouts.

File Structure

shared/components/CardStat/
├── CardStat.tsx        # Component implementation
├── CardStat.scss       # Component styles
├── CardStat.md         # This documentation
└── index.ts            # Exports

Related Components

• Button - Used for CTA buttons within cards
• PageGrid - For laying out multiple cards in responsive grids
• Divider - Can be used to separate card sections if needed