Components

Card

A structured container component for grouping related content with header, body, and footer sections. Supports multiple colors, visual styles, and sizes through the recipe system.

Overview

The Card is a structured container element used for grouping related content into a visually distinct surface. It is composed of five recipe parts: useCardRecipe() for the container, useCardHeaderRecipe() for the top section with a bottom separator, useCardMediaRecipe() for an optional image at the top, useCardBodyRecipe() for the main content area, and useCardFooterRecipe() for the bottom section with a top separator. Each composable creates a fully configured recipe with color, variant, and size options — plus compound variants that handle the color-variant combinations automatically.

The Card recipes integrate directly with the default design tokens preset and generate type-safe utility classes at build time with zero runtime CSS.

Why use the Card recipe?

The Card recipe helps you:

  • Ship faster with sensible defaults: Get 3 colors, 3 visual styles, and 3 sizes out of the box with a single set of composable calls.
  • Compose structured layouts: Five coordinated recipes (container, header, media, body, footer) share the same variant axes, so your cards stay internally consistent.
  • Maintain consistency: Compound variants ensure every color-variant combination follows the same design rules, including separator colors and dark mode overrides.
  • Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
  • Stay type-safe: Full TypeScript support means your editor catches invalid color, variant, or size values at compile time.
  • Integrate with your tokens: Every value references the design tokens preset, so theme changes propagate automatically.

Usage

Register the recipes

Add the Card recipes to a local Styleframe instance. The global styleframe.config.ts provides design tokens and utilities, while the component-level file registers the recipes themselves:

src/components/card.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import {
    useCardRecipe,
    useCardHeaderRecipe,
    useCardMediaRecipe,
    useCardBodyRecipe,
    useCardFooterRecipe,
} from '@styleframe/theme';

const s = styleframe();

const card = useCardRecipe(s);
const cardHeader = useCardHeaderRecipe(s);
const cardMedia = useCardMediaRecipe(s);
const cardBody = useCardBodyRecipe(s);
const cardFooter = useCardFooterRecipe(s);

export default s;

Build the component

Import the card, cardHeader, cardBody, and cardFooter runtime functions from the virtual module and pass variant props to compute class names:

src/components/Card.tsx
import { card, cardHeader, cardBody, cardFooter, type CardProps } from "virtual:styleframe";

export function Card({
    color = "neutral",
    variant = "solid",
    size = "md",
    title,
    description,
    footer,
    children,
}: CardProps & { title?: string; description?: string; footer?: React.ReactNode; children?: React.ReactNode }) {
    return (
        <article className={card({ color, variant, size })}>
            {title && (
                <div className={cardHeader({ color, variant, size })}>
                    <h3>{title}</h3>
                </div>
            )}
            <div className={cardBody({ size })}>
                {description && <p>{description}</p>}
                {children}
            </div>
            {footer && (
                <div className={cardFooter({ color, variant, size })}>
                    {footer}
                </div>
            )}
        </article>
    );
}

See it in action

Colors

The Card recipe includes 3 color variants: light, dark, and neutral. Unlike semantic component recipes (Badge, Button, Callout), the Card uses neutral-spectrum colors designed for content surfaces rather than status communication. Each color is combined with every visual style variant through compound variants, so you get consistent, predictable styling across all combinations — including dark mode overrides.

The neutral color adapts automatically: it uses a light appearance in light mode and a dark appearance in dark mode, making it the safest default for general-purpose cards.

Color Reference

ColorTokenUse Case
light@color.white / @color.gray-*Light surfaces, stays light in dark mode
dark@color.gray-900Dark surfaces, stays dark in light mode
neutralAdaptive (light ↔ dark)Default color, adapts to the current color scheme
Pro tip: Use neutral as your default card color. It adapts automatically to the user's color scheme, so you don't need to manage light and dark variants separately.

Variants

Three visual style variants control how the card is rendered. Each variant is combined with the selected color through compound variants, so you always get the correct background, text, border, and separator colors for your chosen color.

Solid

Filled background with a subtle border. The most prominent style, ideal for primary content areas and featured sections.

Soft

Light tinted background with no visible border. A gentle, borderless style that works well for grouped content in dense layouts.

Subtle

Light tinted background with a matching border. Combines the softness of the soft variant with added visual definition from a border.

Sizes

Three size variants from sm to lg control the border radius of the card container and the padding and gap of the header, body, and footer sections.

Size Reference

SizeBorder RadiusHeader/Footer Padding (V / H)Body Padding (V / H)Gap
sm@border-radius.sm@0.5 / @0.75@0.5 / @0.75@0.375 – @0.5
md@border-radius.md@0.75 / @1@0.75 / @1@0.5 – @0.75
lg@border-radius.lg@1 / @1.25@1 / @1.25@0.75 – @1
Good to know: The size prop must be passed to each sub-recipe individually. The card container controls the border radius, while the header, body, and footer control their own padding and gap.

Anatomy

The Card recipe is composed of five independent recipes that work together to form a structured layout:

PartRecipeRole
ContaineruseCardRecipe()Outer wrapper with background, border, border radius, and shadow
HeaderuseCardHeaderRecipe()Top section with a bottom separator border, holding the card's heading
MediauseCardMediaRecipe()Optional image, shown at the top edge to edge, with a 16 / 9 aspect ratio
BodyuseCardBodyRecipe()Main content area with vertical flex layout
FooteruseCardFooterRecipe()Bottom section with a top separator border

Each part is a standalone recipe with its own set of variants. The color and variant props should be passed consistently to the container, header, and footer so that separator border colors match the card's visual style. The body recipe only requires a size prop for padding, and the media recipe a size prop so its rounded corners match the card's.

<!-- All five parts working together. The media comes after the header in the DOM, and shows above it. -->
<article class="card(...)">
    <div class="cardHeader(...)"><h3>Header content</h3></div>
    <div class="cardMedia(...)"><img src="/photo.jpg" alt="" /></div>
    <div class="cardBody(...)">Body content</div>
    <div class="cardFooter(...)">Footer content</div>
</article>
Pro tip: You don't have to use all five parts. A card with only a body is perfectly valid for simple content blocks. Add the header and footer only when your content needs distinct sections.

Accessibility

The Card recipes follow the Open Components Card standard. Here's what they do for you, and what's left to your markup.

  • Make the heading the link. When the whole card should take people somewhere, put a link in the heading inside the header, rather than wrapping the card in an <a> or a <button>. The recipe stretches that link over the card with its ::after pseudo-element, so pressing anywhere on the card, its border included, follows it, while the link's name stays the heading alone.
<!-- Correct: the heading's link stretches over the card -->
<article class="card(...)">
    <div class="cardHeader(...)">
        <h3><a href="/projects/analytical-engine">Analytical Engine</a></h3>
    </div>
    <div class="cardBody(...)"><p>A general-purpose mechanical computer.</p></div>
    <div class="cardFooter(...)">
        <button class="button(...)">Save</button>
    </div>
</article>
  • Actions stay clickable. Links, buttons and form fields in the media, the body, the footer and the rest of the header sit above the stretched link (position: relative and z-index: 1), so pressing one runs it rather than following the card's link.
  • Focus goes around the whole card. When the heading's link has keyboard focus, the card shows a 2px solid outline, 2px outside its border, in color.focus, the focus colour every component shares, or in color.primary if your colours define no focus. It reads the link with :has(a[href]:focus-visible), so an action shows its own focus ring instead, and only one thing ever looks focused.
  • Hover reads the link too. Inside @media (hover: hover), the border gets stronger and the heading is underlined while the pointer is over the part of the card that follows the link, but not over an action. No state changes the card's size or position.
  • Heading first. Put the media after the header in the DOM: order: -1 shows it at the top, so people who move from heading to heading land at the start of the card. Keep the media an image with nothing people can focus, and give an image that only illustrates the heading an empty alt.
  • Media keeps its space. The media's 16 / 9 aspect ratio holds its place while the image loads, its image fills it with object-fit: cover, and the text always sits below it, so its contrast never depends on the picture.
  • Nothing is clipped. The card has no fixed height and no overflow: hidden, so it grows with its text at 200% zoom. Long words, like a web address, wrap with overflow-wrap: break-word, and min-width: 0 lets it get narrower in a grid rather than overflow.
  • More contrast and forced colours. With prefers-contrast: more, the border is drawn in the text colour at full strength, on hover too. In forced colours mode, the border is drawn in CanvasText and the focus ring switches to Highlight.
  • Right to left. The header, body and footer pad their inline sides with padding-inline, and the media rounds its start corners with border-start-start-radius and border-start-end-radius, so the card mirrors itself in right-to-left layouts.
  • Modifiers. The color compounds use the dark modifier. The hover, more-contrast and forced-colours states are @media blocks in useCardRecipe's setup selectors rather than the hover-capable, contrast-more and forced-colors modifiers, because they read the link through :has(), or have to win over the color compounds' border classes.
  • Contrast. Every color and variant, light and dark included, has text of at least 4.5:1 against its background in the light and dark themes, and the focus ring has at least 3:1 against the page. A test checks this from the token values. If you override colours, check them again with the WebAIM Contrast Checker.

Customization

Overriding Defaults

Each card composable accepts an optional second argument to override any part of the recipe configuration. Overrides are deep-merged with the defaults, so you only need to specify the properties you want to change:

src/components/card.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import {
    useCardRecipe,
    useCardHeaderRecipe,
    useCardBodyRecipe,
    useCardFooterRecipe,
} from '@styleframe/theme';

const s = styleframe();

const card = useCardRecipe(s, {
    base: {
        borderRadius: '@border-radius.lg',
        boxShadow: '@box-shadow.md',
    },
    defaultVariants: {
        color: 'neutral',
        variant: 'subtle',
        size: 'lg',
    },
});

const cardHeader = useCardHeaderRecipe(s, {
    defaultVariants: {
        color: 'neutral',
        variant: 'subtle',
        size: 'lg',
    },
});

const cardBody = useCardBodyRecipe(s, {
    defaultVariants: {
        size: 'lg',
    },
});

const cardFooter = useCardFooterRecipe(s, {
    defaultVariants: {
        color: 'neutral',
        variant: 'subtle',
        size: 'lg',
    },
});

export default s;

Filtering Variants

If you only need a subset of the available variants, use the filter option to limit which values are generated. This reduces the output CSS and keeps your component API focused:

src/components/card.styleframe.ts
import { styleframe } from 'virtual:styleframe';
import { useCardRecipe } from '@styleframe/theme';

const s = styleframe();

// Only generate neutral color with solid and subtle styles
const card = useCardRecipe(s, {
    filter: {
        color: ['neutral'],
        variant: ['solid', 'subtle'],
    },
});

export default s;
Good to know: Filtering also removes compound variants and adjusts default variants that reference filtered-out values, so your recipe stays consistent.

API Reference

useCardRecipe(s, options?)

Creates the card container recipe with background, border, border radius, and shadow styling.

Parameters:

ParameterTypeDescription
sStyleframeThe Styleframe instance
optionsDeepPartial<RecipeConfig>Optional overrides for the recipe configuration
options.baseVariantDeclarationsBlockCustom base styles for the card container
options.variantsVariantsCustom variant definitions for the recipe
options.defaultVariantsRecord<keyof Variants, string>Default variant values for the recipe
options.compoundVariantsCompoundVariant[]Custom compound variant definitions for the recipe
options.filterRecord<string, string[]>Limit which variant values are generated

Variants:

VariantOptionsDefault
colorlight, dark, neutralneutral
variantsolid, soft, subtlesolid
sizesm, md, lgmd

useCardHeaderRecipe(s, options?)

Creates the card header recipe with a bottom separator border. Accepts the same parameters and variant axes as useCardRecipe.

Variants:

VariantOptionsDefault
colorlight, dark, neutralneutral
variantsolid, soft, subtlesolid
sizesm, md, lgmd

useCardMediaRecipe(s, options?)

Creates the card media recipe for an image at the top of the card, with a 16 / 9 aspect ratio and rounded start corners that match the card's when you pass it the same size. Accepts the same parameters as useCardRecipe.

Variants:

VariantOptionsDefault
colorlight, dark, neutralneutral
variantsolid, soft, subtlesolid
sizesm, md, lgmd

useCardBodyRecipe(s, options?)

Creates the card body recipe for the main content area. Accepts the same parameters as useCardRecipe.

Variants:

VariantOptionsDefault
colorlight, dark, neutralneutral
variantsolid, soft, subtlesolid
sizesm, md, lgmd

useCardFooterRecipe(s, options?)

Creates the card footer recipe with a top separator border. Accepts the same parameters and variant axes as useCardRecipe.

Variants:

VariantOptionsDefault
colorlight, dark, neutralneutral
variantsolid, soft, subtlesolid
sizesm, md, lgmd

Learn more about recipes →

Best Practices

  • Pass color and variant consistently: The container, header, and footer all need the same color and variant values so that separator borders match the card's visual style.
  • Pass size to each sub-recipe: The card container controls the border radius, but each section (header, body, footer) manages its own padding and gap based on the size prop.
  • Use neutral for general-purpose cards: The neutral color adapts to light and dark mode automatically, making it the safest default.
  • Prefer solid for primary content: Reserve soft and subtle for secondary or nested cards to create visual hierarchy.
  • Don't use all sections if you don't need them: A card with only a body is perfectly valid. Add headers and footers only when your content has distinct sections.
  • Filter what you don't need: If your component only uses one color, pass a filter option to reduce generated CSS.
  • Override defaults at the recipe level: Set your most common variant combination as defaultVariants so component consumers write less code.

FAQ