components / card

Card

Structured content surface with predictable spacing rhythm, surface recipes, and low-drama display styling.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Card is a non-interactive content surface for grouping related information without inventing bespoke box styling each time.
  • Its main job is to standardize surface treatment, density, and section rhythm across product surfaces.

Aliases

surface card

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Card when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Card contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Card label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Card behind decorative copy or overloaded surface treatments.
  • Do not stretch Card into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Card to group related content, controls, or summaries into one readable surface.
  • Use header and footer slots when the grouped content needs explicit structure.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not turn Card into a click-target for primary actions in this v1 contract.
  • Do not use Card when the content already has enough structural containment from layout alone.

Anti-patterns

  • Using Card as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy card usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

surface shell

root

Provides surface, border, radius, and spacing behavior.

optional leading block

header

Holds titles, badges, or summary metadata.

main content area

body

Holds the primary content of the card.

optional closing block

footer

Supports compact follow-up metadata or actions.

optional media slot

media

Supports image or visual content above or within the surface.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
padding'sm' | 'md' | 'lg''md'Chooses the card padding recipe.
surface'default' | 'raised' | 'outlined''default'Chooses the surface emphasis recipe.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Slots

NameDescription
defaultPrimary card body content.
headerOptional header content.
footerOptional footer content.
mediaOptional media content.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • default: Calm surface with minimal emphasis.
  • raised: Elevated surface for stronger separation.
  • outlined: Lower-elevation surface with clearer edge definition.

Sizes

  • sm: Tighter padding for denser summary blocks.
  • md: Default content density.
  • lg: More generous breathing room for editorial or onboarding surfaces.

States

  • rest: Cards are intentionally static in v1.

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Card is a structural surface and inherits semantics from the content placed inside it.

Keyboard

  • Card has no custom keyboard behavior in v1 because it is non-interactive.

Screen readers

  • Card structure is communicated through its child headings, text, and controls.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-card-bg
#f2f5fb
--dk-card-fg
#16181c
--dk-card-border
#95989d
--dk-card-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-card-padding
clamp(1.778rem, 1.6296rem + 0.658vw, 2.222rem)
--dk-card-shadow
0 10px 15px rgba(0, 0, 0, 0.06), 0 4px 6px rgba(0, 0, 0, 0.04)

media

--dk-card-media-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-card-media-min-height
140px

header

--dk-card-header-gap
clamp(0.563rem, 0.5156rem + 0.208vw, 0.703rem)
--dk-card-header-title-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-card-header-title-weight
650
--dk-card-header-meta-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

body

--dk-card-body-size
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-card-body-line-height
1.6

footer

--dk-card-footer-gap
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

Implementation notes

  • Card remains intentionally non-interactive in v1 so surface semantics stay honest.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: summary surface

A basic card with header, body, and footer content.

Copy snippet

<Card surface="raised" padding="md"><svelte:fragment slot="header"><strong>Launch checklist</strong></svelte:fragment>Ready for review.<svelte:fragment slot="footer">3 tasks left</svelte:fragment></Card>

Common patterns

1 example

common

Common: lighter grouping

Use an outlined card when grouping matters more than hierarchy.

Copy snippet

<Card surface="outlined" padding="sm">Compact supporting content.</Card>

Edge cases

1 example

edge

Edge: spacious editorial surface

Larger padding works for content-forward or onboarding surfaces.

Copy snippet

<Card surface="default" padding="lg"><svelte:fragment slot="header"><strong>Getting started</strong></svelte:fragment>Invite the first team members and configure your workspace.</Card>

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

default

pass

padding=md|surface=default

  • Contrast: 98.5 Lc
  • Layout: 0 / 280, 360

raised

pass

padding=md|surface=raised

  • Contrast: 98.5 Lc
  • Layout: 0 / 280, 360

outlined

pass

padding=md|surface=outlined

  • Contrast: 98.5 Lc
  • Layout: 0 / 280, 360