User Interface (UI)

Let's start with how a card looks: its parts, what goes in each of them, how cards sit together on a page and how a card shows its states.

Anatomy

1

Analytical Engine4

Project3

2

A general-purpose mechanical computer.

5

Save6

By Charles Babbage7

8

Every card has a container and a header with a heading in it. The parts have no borders of their own, so a card reads as one block, from top to bottom. If a long card, like a settings panel, needs a line between two of its parts, that's a separator's job (see Content).

On screen, the media comes first, then the eyebrow and the heading, but in the DOM the heading comes first of all, with the eyebrow and the media after it (see Put the heading first). The parts always render in the same order, which you can see in the DOM contract.

Content

A card can be as small as a heading and a sentence, or hold every part. You can put any image in media, a short line like a category in eyebrow, Buttons in actions and details like the author in footer, while the body is whatever you put inside the card.

Difference Engine

Babbage's machine for working out tables of numbers, by the method of differences.

Analytical Engine

Project

Charles Babbage's design for a general-purpose mechanical computer, first described in 1837.

Save

By Charles Babbage

<Card heading="Difference Engine">
  <p>Babbage's machine for working out tables of numbers, by the method of differences.</p>
</Card>

<Card
  heading="Analytical Engine"
  eyebrow="Project"
  media={<img src="/projects/analytical-engine.jpg" alt="" />}
  actions={<Button size="sm" variant="outline">Save</Button>}
  footer="By Charles Babbage"
>
  <p>Charles Babbage's design for a general-purpose mechanical computer, first described in 1837.</p>
</Card>

• Keep the heading short, and make it the thing people are choosing between, like the project's name, so they can tell cards apart by their headings alone.
• The eyebrow is for a word or two that sorts the card, like a category or a date. Anything longer belongs in the body, where it doesn't push the heading down.
• An image that only illustrates the heading, like a product photo next to the product's name, has an empty alt, so screen readers skip it rather than read the name twice. You'll find more under Describe the media.
• Keep the body to a sentence or two. A card is a summary of a page, and people go to that page for the rest.
• We recommend at most two actions, ranked like any other Buttons, with an outline or ghost Button rather than a solid one, so a page of cards doesn't fill up with primary actions.
• The footer is for details about the card rather than about its subject, like who made it, when it was updated or how many comments it has. Its text is smaller and lighter than the body's, at 4.5:1 like the eyebrow, so it doesn't compete with the body.
• The parts have no borders between them. A line between two of them is a separator, which you add only where it helps, like above a footer of links. Inside a card it's decorative, since the heading already marks the structure, so draw it with an empty element's border, or use <hr aria-hidden="true">, rather than a plain <hr>, which screen readers announce. To run edge to edge, it takes the card's padding back with negative margins, like margin-inline: calc(-1 * var(--card--padding)).

Layout

A set of cards is a list, so put them in a <ul>, with each card as an <li> (as="li"). Screen readers then say how many cards there are, and let people skip past the whole list. A grid that fits as many cards as there's room for, each at least a set width, works on every screen without a breakpoint:

<ul className="projects">
  {projects.map((project) => (
    <Card
      key={project.id}
      as="li"
      heading={project.name}
      href={project.url}
      media={<img src={project.image} alt="" />}
      actions={<Button size="sm" variant="outline">Save</Button>}
    >
      <p>{project.summary}</p>
    </Card>
  ))}
</ul>

.projects {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(16rem, 100%), 1fr));
  gap: 1rem;
  margin: 0;
  padding: 0;
  list-style: none;
}

• The min(16rem, 100%) lets a card get narrower than 16rem on a narrow screen rather than overflow it, so the page never scrolls sideways at 320px wide (WCAG 1.4.10).
• Cards in a row of a grid stretch to the same height, and the body takes the spare height, or the header in a card without a body, so the actions and the footers line up from card to card.
• Keep the cards in the same order in the DOM as on screen, and don't reorder them with order, row-reverse or grid-auto-flow: dense. Tab follows the DOM, so a card that's moved on screen makes focus jump around (WCAG 1.3.2, 2.4.3).
• Safari has dropped the list role from lists with list-style: none, so VoiceOver doesn't say how many items there are. If that matters to you, add role="list" to the <ul>.

States

A card on its own has no states, since there's nothing to do with it. A card that's a link has two, hover and focus, and both come from its link, so they only ever show when pressing the card would follow it.

<Card heading="Difference Engine">
  <p>A machine for working out tables of numbers.</p>
</Card>

<Card heading="Analytical Engine" href="/projects/analytical-engine">
  <p>A general-purpose mechanical computer.</p>
</Card>

Both states read the link, rather than the card. That way, the card only looks hovered while the pointer is over the part of it that follows the link, and not over one of its actions, which shows its own hover instead. None of the states change the card's size or position, and you'll find how they behave under Every state.

Tokens

The card reads two theme tokens, which every component shares:

Everything else is mixed from the text colour: 70% for the eyebrow and the footer, which need 4.5:1, and 20% for the border at rest and 45% on hover. With our reference tokens, from the Tailwind CSS palette, the eyebrow and the footer come to 5.6:1 on white and 7.4:1 on zinc-900, the same as the Input's placeholder. The border is lighter than the Input's, since a card's heading says what it is, and WCAG only asks for 3:1 on a boundary people need to see to find the component (WCAG 1.4.11). You'll find the tokens themselves in the Button's tokens.css, which you can copy into your theme.

If you need to tune a card, you can set its own variables, such as --card--padding, --card--background or --card--media--aspect-ratio, from a class. The Card's styles sit in the components cascade layer, so your class wins without any specificity tricks:

import styles from "./ProjectCard.module.css";

<Card className={styles.project} heading="Analytical Engine" media={<img src="/projects/analytical-engine.jpg" alt="" />}>
  <p>A general-purpose mechanical computer.</p>
</Card>

.project {
  --card--background: var(--color--neutral-surface);
  --card--media--aspect-ratio: 4 / 3;
}

--color--neutral-surface stands in for a surface colour from your own theme, since the theme tokens don't have one. The Card is transparent by default, so it sits on whatever's behind it. If you give it a background, check the text's contrast against that background rather than the page's.

UI Checklist

FAQ