# Card Component

A flexible, polymorphic container component that provides a consistent visual structure for grouping related content with theme variant styling.

## Import path
```tsx
import Card from '@hubspot/cms-component-library/Card';
```

## Purpose

The Card component provides a reusable container for grouping related content in HubSpot CMS projects. It uses the theme variant system (via `data-card-variant` attribute) to apply visual styles like background color, text color, border radius, and borders. Use it when you need to visually separate and organize content into distinct sections with theme-consistent styling.

## Component Structure

```
Card/
├── index.tsx                    # Main component with render logic
├── types.ts                     # TypeScript type definitions
├── StyleFields.tsx              # HubSpot field definitions for styling (VariantSelectionField)
├── index.module.scss            # CSS module consuming theme variant CSS variables
└── stories/
    ├── Card.stories.tsx         # Storybook examples
    ├── CardDecorator.tsx        # Storybook decorator
    └── CardDecorator.module.scss # Decorator styles with variant variable definitions
```

## Components

### Card (Main Component)

**Purpose:** Polymorphic container component that renders as a `<div>`, `<article>`, or `<section>` element with theme variant styling applied via the `data-card-variant` attribute.

**Props:**
```tsx
{
  variant?: 'card1' | 'card2' | 'card3' | 'card4';  // Theme variant (default: 'card1')
  as?: 'div' | 'article' | 'section';             // HTML element to render (default: 'div')
  children?: React.ReactNode;                     // Card content
  className?: string;                             // Additional CSS classes
  style?: React.CSSProperties;                    // Inline styles
}
```

## Usage Examples

### Basic Card with Content

```tsx
import Card from '@hubspot/cms-component-library/Card';

<Card>
  <h3>Card Title</h3>
  <p>This is the card content.</p>
</Card>
```

### Semantic Article Card

```tsx
<Card as="article" variant="card3">
  <h3>Blog Post Title</h3>
  <p>Article content goes here...</p>
</Card>
```

### Dynamic Cards from Data

```tsx
const features = [
  { title: 'Analytics', description: 'Track performance metrics' },
  { title: 'Integration', description: 'Connect with existing tools' },
  { title: 'Support', description: '24/7 customer assistance' }
];

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '16px' }}>
  {features.map((feature) => (
    <Card key={feature.title}>
      <h3>{feature.title}</h3>
      <p>{feature.description}</p>
    </Card>
  ))}
</div>
```

## HubSpot CMS Integration

### Field Definitions

The Card component uses `VariantSelectionField` from `@hubspot/cms-components/fields` to allow theme variant selection in the CMS editor.

#### StyleFields.tsx

Configurable props for customizing field labels, names, and defaults:

```tsx
<Card.StyleFields
  cardVariantLabel="Card variant"
  cardVariantName="cardVariant"
  cardVariantDefault={{ variant_name: 'card1' }}
/>
```

**Fields:**
- `cardVariant`: VariantSelectionField for selecting theme variant (variantDefinitionName: "card")

### Module Usage Example

```tsx
import Card from '@hubspot/cms-component-library/Card';

export default function FeatureCardModule({ fieldValues }) {
  return (
    <Card
      variant={fieldValues.cardVariant.variant_name}
      as="article"
    >
      <h3>{fieldValues.title}</h3>
      <p>{fieldValues.description}</p>
    </Card>
  );
}

FeatureCardModule.fields = (
  <>
    <Card.StyleFields />
    <TextField label="Title" name="title" default="Feature title" />
    <TextField label="Description" name="description" default="Feature description" />
  </>
);
```

## Styling

### Theme Variant CSS Variables (provided by the variant system via `data-card-variant`)

- `--hs-card-borderRadius`: Border radius
- `--hs-card-backgroundColor`: Background color
- `--hs-card-color`: Text color
- `--hs-card-borderStyle`: Border style (e.g. `solid`, `none`)
- `--hs-card-borderWidth`: Border width (e.g. `1px`)
- `--hs-card-borderColor`: Border color


## Accessibility

The Card component follows accessibility best practices:

- **Semantic HTML**: Use the `as` prop to render appropriate semantic elements (`article` for blog posts, `section` for page sections, `div` for generic containers)
- **Content Structure**: Ensure proper heading hierarchy within card content (e.g., if cards are in an h2 section, use h3 for card titles)
- **Color Contrast**: Theme variants should meet WCAG AA contrast requirements; verify custom colors maintain sufficient contrast
- **Focus Management**: Cards themselves are not interactive, but ensure interactive elements within cards (buttons, links) have proper focus styles

## Best Practices

- **Choose semantic elements**: Use `as="article"` for self-contained content, `as="section"` for thematic groupings, and `as="div"` (default) for generic containers
- **Border radius via theme variants**: Border radius is controlled by the variant system, not a direct prop.
- **Override CSS variables**: Customize appearance using CSS variables rather than overriding class styles
- **Grid layouts**: Use CSS Grid or Flexbox for card layouts rather than relying on card margins
- **Content flexibility**: Cards are content-agnostic containers; structure internal content using appropriate semantic elements

## Related Components

- **Flex**: Use for arranging cards in flexible layouts
- **Grid**: Use for creating responsive card grids
- **Text**: Use with `textFeatureSet="heading"` for editable card titles
