Card

UICard

Structured surfaces for product UILink to section

The Card component is a foundational surface used to group related content, actions, and metadata.

Use it for:

dashboard tiles
pricing blocks
settings panels
billing summaries
feature cards
list items
empty states
account sections
product surfaces

Card is built on semantic tokens such as bg-card, border-border, and text-card-foreground, so it stays consistent across light and dark themes.

Core idea

Card creates structure. Use it to group meaningful content, not as decoration.

ImportLink to section

card-import.tsx

import { Card } from "@pycolors/ui";

Basic usageLink to section

Use Card to group a title, description, content, and optional footer actions.

Account

Manage your profile settings.

Update personal details, security preferences, and integrations.

account-card.tsx

import {
  Button,
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from "@pycolors/ui";

export function AccountCard() {
  return (
    <Card className="max-w-sm">
      <CardHeader>
        <CardTitle>Account</CardTitle>
        <CardDescription>
          Manage your profile settings.
        </CardDescription>
      </CardHeader>

      <CardContent>
        <div className="text-sm text-muted-foreground">
          Update personal details, security preferences, and integrations.
        </div>
      </CardContent>

      <CardFooter className="justify-end gap-2">
        <Button variant="secondary">Cancel</Button>
        <Button>Save</Button>
      </CardFooter>
    </Card>
  );
}

When to use CardLink to section

Use Card when content needs a clear surface, boundary, or grouping.

Dashboards

Use for KPI tiles, analytics summaries, and grouped dashboard sections.

Settings

Use for profile, organization, security, and billing settings panels.

Billing

Use for plan summaries, invoice blocks, and payment method surfaces.

VariantsLink to section

Cards support semantic surface variants.

Use variants to adjust contrast without changing layout.

Default

Standard surface.

Muted

Subtle secondary surface.

Transparent

Layout-only surface.

card-variants.tsx

import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
} from "@pycolors/ui";

export function CardVariants() {
  return (
    <div className="grid gap-4 sm:grid-cols-3">
      <Card>
        <CardHeader>
          <CardTitle>Default</CardTitle>
          <CardDescription>Standard surface.</CardDescription>
        </CardHeader>
      </Card>

      <Card variant="muted">
        <CardHeader>
          <CardTitle>Muted</CardTitle>
          <CardDescription>Subtle secondary surface.</CardDescription>
        </CardHeader>
      </Card>

      <Card variant="transparent" className="border-dashed">
        <CardHeader>
          <CardTitle>Transparent</CardTitle>
          <CardDescription>Layout-only surface.</CardDescription>
        </CardHeader>
      </Card>
    </div>
  );
}

Available variantsLink to section

Variant	Purpose
`default`	Main surface using `bg-card`
`muted`	Secondary surface using a softer background
`transparent`	Layout-only container with no filled background

Variant rule

Use default for primary surfaces, muted for secondary groups, and transparent when you only need structure.

Interactive cardsLink to section

Use interactive when the whole card behaves like a selectable or navigational surface.

Clickable card

Hover and focus states communicate interactivity.

Interactive + muted

Useful for secondary selection items.

interactive-cards.tsx

import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
} from "@pycolors/ui";

export function InteractiveCards() {
  return (
    <div className="grid gap-4 sm:grid-cols-2">
      <Card interactive>
        <CardHeader>
          <CardTitle>Clickable card</CardTitle>
          <CardDescription>
            Hover and focus states communicate interactivity.
          </CardDescription>
        </CardHeader>
      </Card>

      <Card interactive variant="muted">
        <CardHeader>
          <CardTitle>Interactive + muted</CardTitle>
          <CardDescription>
            Useful for secondary selection items.
          </CardDescription>
        </CardHeader>
      </Card>
    </div>
  );
}

Interaction rule

If the card navigates, render it as a real link using asChild. If it performs an action, render it as a button or put a Button inside.

With iconLink to section

Use asChild to render Card as another element while preserving Card styling.

This is useful for link cards.

Read the docs

Go to documentation →

card-as-link.tsx

import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
} from "@pycolors/ui";

export function CardAsLink() {
  return (
    <Card asChild interactive className="max-w-sm">
      <a href="/docs" className="block">
        <CardHeader>
          <CardTitle>Read the docs</CardTitle>
          <CardDescription>Go to documentation →</CardDescription>
        </CardHeader>
      </a>
    </Card>
  );
}

CompositionLink to section

A Card usually follows this structure:

card-anatomy.tsx

<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
    <CardDescription>Description</CardDescription>
  </CardHeader>

  <CardContent>
    Content
  </CardContent>

  <CardFooter>
    Actions
  </CardFooter>
</Card>

Use each slot intentionally:

Slot	Purpose
`CardHeader`	Introduces the surface
`CardTitle`	Names the grouped content
`CardDescription`	Adds short context
`CardContent`	Holds the main body
`CardFooter`	Holds actions or supporting metadata

Usage patternsLink to section

Card vs section vs list itemLink to section

Situation	Use
Grouped content with a visible surface	Card
Large page section with headings	Section
Repeated compact rows	List item
Navigation tile	Card with `asChild` link
KPI or metric	Card
Table data	Table
Temporary status or error	Alert or EmptyState

Decision rule

Use Card when the surface helps users understand grouping, priority, or interaction.

APILink to section

Components

Component	Description
`Card`	Root surface
`CardHeader`	Header area
`CardTitle`	Card heading
`CardDescription`	Supporting text
`CardContent`	Main content area
`CardFooter`	Footer actions or metadata

Card props

Prop	Type	Default	Description
`variant`	`CardVariant`	`"default"`	Surface style
`interactive`	`boolean`	`false`	Adds hover and focus-visible feedback
`asChild`	`boolean`	`false`	Render via Radix Slot
`className`	`string`	—	Additional Tailwind classes

Card extends standard HTML div props.

card-props.ts

React.HTMLAttributes<HTMLDivElement>

TypeScript typesLink to section

card-types.ts

export type CardVariant =
  | "default"
  | "muted"
  | "transparent";

export type CardInteractive = boolean;

AccessibilityLink to section

Guidelines:

use meaningful headings inside cards when they introduce a section
keep interactive semantics accurate
use asChild with a for navigation
use asChild with button only when the whole card performs an action
avoid multiple nested interactive elements inside an interactive card
keep focus states visible for interactive cards
do not make a card interactive only for visual decoration

Accessibility rule

A clickable card should still be a real link or button. Visual interactivity is not enough.

Prefer / avoidLink to section

Prefer

clear grouping
consistent card rhythm
semantic headings
footer actions for card-level actions
real link semantics for navigation cards

Avoid

cards used only for decoration
too many nested cards
interactive styling on static content
clickable cards without link or button semantics
multiple competing actions inside one clickable card

Product copy guidelinesLink to section

Card copy should make the grouped content easy to understand.

Strong title examples

Titles should describe the surface immediately without extra wording.

AccountCurrent planRecent invoicesProject activityTeam members

Common questionsLink to section

ColorsSemantic surface roles used by cards.RadiusCorner radius tokens used for card surfaces.ShadowsElevation scale for cards and floating surfaces.AccessibilityBuild accessible surfaces with headings, semantics, and focus states.

Structured surfaces for product UILink to section

ImportLink to section

Basic usageLink to section

Account

When to use CardLink to section

Dashboards

Settings

Billing

VariantsLink to section

Default

Muted

Transparent

Available variantsLink to section

Interactive cardsLink to section

Clickable card

Interactive + muted

With iconLink to section

Read the docs

CompositionLink to section

Usage patternsLink to section

Start with the content group

Add a clear title

Keep actions in the footer

Use interactivity deliberately

Preserve semantic behavior

Card vs section vs list itemLink to section

APILink to section

Components

Card props

TypeScript typesLink to section

AccessibilityLink to section

Prefer / avoidLink to section

Prefer

Avoid

Product copy guidelinesLink to section

Strong title examples

Common questionsLink to section

On this page

Structured surfaces for product UILink to section

ImportLink to section

Basic usageLink to section

Account

When to use CardLink to section

Dashboards

Settings

Billing

VariantsLink to section

Default

Muted

Transparent

Available variantsLink to section

Interactive cardsLink to section

Clickable card

Interactive + muted

With iconLink to section

Read the docs

CompositionLink to section

Usage patternsLink to section

Start with the content group

Add a clear title

Keep actions in the footer

Use interactivity deliberately

Preserve semantic behavior

Card vs section vs list itemLink to section

APILink to section

Components

Card props

TypeScript typesLink to section

AccessibilityLink to section

Prefer / avoidLink to section

Product copy guidelinesLink to section

Strong title examples

Common questionsLink to section

Should every content group be a Card?

Can a Card be clickable?

When should I use the muted variant?

Can cards contain forms?

RelatedLink to section

On this page