Reading a card

A card is a small, self-contained unit that stands for one thing: a story, a product, a person, a number, a choice. This guide names its parts, so you can find the shape you need by what it is made of rather than by what it was once used for.

1. 1. Anatomy
2. 2. Purpose
3. 3. Interaction
4. 4. Size and context
5. 5. States
6. 6. Composing with the four layers
7. 7. Batch 001: Anatomy foundations
8. 8. Batch 002: Commerce
9. 9. Batch 003: Media
10. 10. Batch 004: People

1. Anatomy

Every card in the catalogue is described by five parts, and the browse facets read them directly.

The order matters more than the parts. Media on top reads picture first and suits a grid, where the eye scans across. Media left reads words first and suits a list, where the eye scans down. A background picture with words on it is for the few cards that should be looked at before they are read.

2. Purpose

The family says what the card is for. Preview cards stand in for something longer. Navigation cards are a way somewhere. Selection cards hold a choice. Control cards change a setting or reveal more. Status cards report a number or an event. Identity cards are about a person. Media cards put the picture or the video first. Commerce cards sell. Tiles are launchers: a glyph and a label.

Two cards can share an anatomy and differ in purpose. A stat tile and a plain card are both words in a box; the stat tile leads with one large number and a delta, because it is read in a glance on a dashboard, while the plain card is read in full.

3. Interaction

Seven kinds, from none to most.

4. Size and context

Size names the footprint the card wants: s, m, wide, tall, square, 2x2. On the wall page they map to a 12-column grid: s and square take 3 columns, m and tall take 4 (tall spans two rows), wide takes 6 or 8, and 2x2 takes 6 columns and two rows.

Context names where the card lives: a grid, a list, a carousel, a deck, a bento, a dashboard, a sidebar. The same card can live in several; the context tells you which layout it was drawn for.

Cards reflow with their own width, not the window's. Every medium, wide and 2x2 card is a container (container-type: inline-size; container-name: card) with at least one @container card rule, so a media-left card turns into a media-top card under 360px and an action row stacks when it runs out of room. Drag the width slider on any card page to watch it happen.

5. States

Rest is implied. A card lists the other states it handles: hover, focus, selected, loading, empty, error, disabled, expanded, flipped. The renderer sets data-state on the card root, and the template styles each one explicitly, alongside the real :hover and :focus-within.

Loading is handled for you: text becomes skeleton bars and pictures become a shimmer block, unless the template has its own loading rule. Empty and error need the template's own markup, because only the card knows what "nothing here" should say. Disabled dims the card and removes pointer events.

6. Composing with the four layers

A card on this site is the fifth layer on top of four shared ones, and every card page lets you swap each of them.

Copy CSS emits the card's template with every one of these resolved into the card's own block at the top, so it works pasted into a page that has none of this site's variables.

7. Batch 001: Anatomy foundations

The first batch is the vocabulary: twenty-nine shapes, one per idea, that every later card borrows from. They fall into nine groups. Text-only cards (Plain, Overline, Action footer) carry words and structure and nothing else. Media-top cards (Media, Avatar header, Icon-actions, Meta footer, Video) put a picture above the words and suit grids. The Media-left card puts a thumbnail beside the words and suits lists and sidebars. Background cards (Background media, Hover reveal, Flip) let the image fill the card and put the words on it or behind it. Tiles (Stat, Sparkline, Icon) are compact units for dashboards and bentos. Selection and control cards (Radio, Checkbox, Toggle, List row, Expandable) hold a choice or a setting. Identity cards (Profile, Testimonial) are about a person. Commerce cards (Badge, Ribbon, Product, Pricing) sell. Status and utility cards (Event, Notification, File) report something that happened or is about to.

Three decisions sit behind almost every one of them. First, where the media goes: on top for a grid of things people browse, on the left for a list people scan, as the background when the picture is the argument, or nowhere when the words are enough. Second, what the target is: the whole card (Media-left, Meta footer, Badge, List row) when the card opens one thing, or an action area (Media card links, Action footer buttons, Icon-actions pill) when the card offers more than one thing to do. Mixing the two, a clickable card full of buttons, is the most common card bug. Third, whether the card has a footer, and whether that footer asks (buttons) or informs (date, read time, counts).

Reach for the Media card first in a grid, the Media-left card first in a list, and the Plain card when there is no picture. Move to a neighbour only when one of the three decisions changes: a single primary action means the Product card or the Action footer card, a choice between cards means the Radio card, and a number that matters more than words means the Stat tile.

8. Batch 002: Commerce

The second batch follows one shopping trip from the grid to the parcel, in twenty-five cards. The grid comes first: the Compact product card for dense grids of four to six, the Swatch card when colour is the choice, the Quick-add card when size is, the Sale and Flash deal cards for markdowns and clocks, the Compare card for spec-heavy goods, and the Category tile and Collection banner card as doors into a range. The product moment adds the Product row card for lists, the Stock alert card for the item that has run out, the Bundle card for buying together, and the Subscription card for one-time against repeat. The basket is the Cart item card with its stepper, the Wishlist card for later, and the Order summary card beside them. Checkout is three radio cards: Delivery option, Address and Payment method. After the order comes the Order status card with its four-step tracker. Offers are the Coupon card and the Gift card; trust is the Review card, the Rating summary card and the Seller card. The Recently viewed card is the smallest unit, for strips and mini-carts.

Four conventions run through the batch. The price pair: the current price in the heading face, in accent only when it is a sale, with the old price struck through in muted beside it. The stock bar: a thin accent bar with the number left in accent beneath, so scarcity is read as a count, not a colour. Badges in accent: a sale percentage, a status, a saving or a default tag is the one place accent fills a shape, so there is never more than one per card. The ticket: the Coupon card's dashed border and notched edges say "discount" before a word is read, and an expired one gets a stamp rather than disappearing.

Reach for the Compact product card first in a grid, the Cart item card and the Order summary card first in the basket, and the Delivery option card first at checkout. Move to a neighbour when the decision changes: a choice of colour or size on the grid, a discount worth shouting, or a list instead of a grid.

9. Batch 003: Media

The third batch is about cards that carry something: a sound, a moving picture, a still picture or a piece of writing, in twenty-four cards. Sound comes first: the Audio player card for the track that is playing, the Track row card for a list of forty, the Album and Playlist cards for a library grid, the Podcast episode and Podcast show cards for spoken shows, and the Audio message card for a voice note in a chat. Moving pictures are the Video player card that plays in place, the Live stream card, the Short video card and the Story card. Still pictures are the Photo card with its credit, the Gallery card, the Carousel card and the Before and after card. Long text is the Article hero card for the lead story, the News card for the feed under it, the Quote image card, the Recipe card, the Course card and the Document card. The covers close it: the Book card, the Movie card and the Map card.

Five conventions run through the batch. Controls ride a gradient: a player's buttons sit on a black scrim fading up from the bottom edge, never on a solid bar that hides the picture. Text on an image is white, whatever the palette, because the picture decides the contrast, not the page. The play disc is the one call at rest: centred and large on a video, small and in a corner on a cover, and gone once playing starts. The waveform is the position: muted bars with the played part in accent, so one shape says audio and how far in. The ratio follows the medium: 1:1 for music and podcasts, 16:9 for video, 9:16 for shorts and stories, 2:3 for book and film covers, 3:2 for photographs.

Reach for the Audio player card first for sound, the Video player card when the video plays on the page and the Live stream card when it opens elsewhere, the Photo card for one picture and the Gallery card for many, and the Article hero card above a column of News cards. Move to a neighbour when the medium changes: a cover with a spine is a book, a poster with a score is a film, a square with a mosaic is a playlist.