Card

Visual Hierarchy

Use CardTitle for the primary heading and CardDescription for supporting context. Place the most important action in CardFooter and use CardAction for secondary actions positioned in the header. Limit to one primary action per card.

Spacing & Layout

Cards use px-6 horizontal padding and py-6 vertical padding by default. When placing cards in grids, use gap-4 for standard spacing or gap-6 for more breathing room. Keep card content concise to maintain scanability.

Responsive Behavior

Use responsive grid columns like md:grid-cols-2 or md:grid-cols-3 for card grids. Cards should stack to a single column on mobile. Set max-w-sm on standalone cards to prevent them from stretching too wide on large screens.

Color & Contrast

Cards use bg-card with text-card-foreground for the container, ensuring proper contrast in both light and dark modes. Borders use the semantic border token. Use text-muted-foreground for secondary text like descriptions.

Keyboard Navigation

• Tab -- Move focus through interactive elements within the card
• Enter or Space -- Activate buttons and links inside the card
• For clickable cards, add Enter handler via onKeyDown with tabIndex={0}

Screen Reader Support

• Use role="article" for standalone content cards to convey meaning
• Associate the card with its title using aria-labelledby pointing to the CardTitle id
• Interactive cards that act as links should have aria-label describing the destination
• Dynamic card content should use aria-live="polite" to announce updates

Semantic Structure

CardTitle renders as a div by default. For proper document outline, ensure heading levels are consistent with the page hierarchy. CardDescription provides supporting text that screen readers announce alongside the title when using aria-describedby.

Focus Management

Cards are not focusable by default since they are containers, not interactive elements. When making a card clickable, add tabIndex={0} and a visible focus ring with focus-visible:ring-[3px]. Ensure that individual interactive elements within the card remain independently focusable.

ARIA Attributes

{/* Standalone content card with article role */}
<Card role="article" aria-labelledby="card-title-1">
  <CardHeader>
    <CardTitle id="card-title-1">Project Status</CardTitle>
    <CardDescription>Current progress and milestones</CardDescription>
  </CardHeader>
  <CardContent>...</CardContent>
</Card>

{/* Interactive card as a link */}
<Card
  role="link"
  tabIndex={0}
  aria-label="View analytics dashboard"
  className="cursor-pointer"
  onClick={handleNavigate}
  onKeyDown={(e) => e.key === "Enter" && handleNavigate()}
>
  <CardHeader>
    <CardTitle>Analytics</CardTitle>
  </CardHeader>
</Card>

{/* Card with live region for dynamic content */}
<Card>
  <CardHeader>
    <CardTitle>Notifications</CardTitle>
  </CardHeader>
  <CardContent aria-live="polite">
    {notifications.map(n => <p key={n.id}>{n.text}</p>)}
  </CardContent>
</Card>