[brandonkelly]

Description

Card view designers get a Thumb Style setting, with Normal and Cover options. With Cover, element cards whose thumbnail is an image that can fill a card become cover cards: the image covers the whole card, and the header and content are laid over it. The card is passed the image's luminance (analysis.colors.luminance) and works out everything else itself.

This applies to any element type whose thumbnail is an asset's image:

• Assets, whose thumbnail is their own image.
• Users, whose thumbnail is their photo.
• Any element with Thumb Sources ([6.x] Thumb Sources #20181): the first source with a thumbnail decides. An Assets field gives its first asset's image, including one within a Content Block. Other relation fields give their first related element's thumbnail, such as an entry's featured image or a user's photo. A source whose thumbnail isn't an asset's image, such as an Icon field, keeps the normal card.

 <craft-card
+  cover-src="…/800x600 crop"
+  luminance="[[[p10, p90], …], …]"   ← rows of regions, top to bottom
 >
-  <div slot="thumbnail">…</div>        ← still sent, but not shown
+  <div slot="header" data-theme="light|dark" data-cover="bar|backed">…</div>
+  <div class="card-main" data-theme="light|dark" data-cover="body">…</div>
 </craft-card>

coverAppearance(luminance, hasHeaderText)      cover.ts
  header ← top row of regions, body ← bottom row
  theme for each: black on white only if every region's P10 ≥ 0.25,
                  otherwise white on black (and with no luminance)
  fills are fixed, and pass over any pixel (#20152):
    header with text (label or badge) → bar      60% black / 52% white
    header with only controls         → backed   65%, 80% when hovered or pressed
    body                              → scrim    60% black / 52% white, over a 1px blur

The theme rule prefers white on black, as a black scrim reads as a natural shadow, while a white one washes out the photo (thupsi's suggestion). It only switches to black on white once the image is light throughout, where the black scrim would look like a gray smear. The cutoff was picked from a brightness ladder of the same photo. Since both themes' fills pass over any pixel, the cutoff only affects looks, not contrast.

Thumb Style setting

Cover cards are opt-in per field layout, through a Thumb Style setting in the card view designer's Appearance tab:

• Options: Normal and Cover, shown as illustrated radios like a Matrix field's View Mode setting (resources/public/images/thumb-styles/{normal,cover}.svg, with dark-mode variants).
• Defaults: Cover for asset volumes, Normal for everything else. Saved as cardThumbStyle in the field layout config, with FieldLayout::getCardThumbStyle(), setCardThumbStyle(), and the fluent cardThumbStyle().
• When it's shown: always, for every field layout. Cards without an asset image keep the normal card either way.
• Thumb Alignment comes after Thumb Style, since it depends on it. It's hidden while Thumb Style is Cover, since a cover card has no thumbnail to align, and when the layout has no thumbnail at all.
• Thumb Sources ([6.x] Thumb Sources #20181) replaces the single “Thumbnail Source” select: several fields can be chosen and ordered, and the first one with a thumbnail is used.
• Preview: the designer's preview card switches between a cover card and a normal card as the selection changes. Its sample image is Mt. Bachelor at sunset in the light theme and under the stars in the dark theme (resources/public/images/thumb-styles/bachelor-{light,dark}.jpg, 800×600 JPEGs without metadata), chosen for the theme being shown, and rendered again if the theme changes without a page load. The sample chip shows it as its thumbnail too. Each image's luminance, measured with Images::sample(), is passed to the cover card, so it gets the same treatment a real asset with that image would. Both get white on black.
• Preview size: the preview card's height is rounded up to a whole number of the workspace grid's 16px cells, plus its border, so both of its edges land on a row of dots, as the chip's do (CardViewDesigner::snapPreviewCard()).
• Preview header: only entry types' previews get a header, for their entry type's label and icon. Other element types' previews have no header, as their cards have nothing to show there.
• Settings height: beside the preview, the settings column is capped at 500px and scrolls, rather than stretching the designer taller than the preview needs.

Variations

All of these are in the Card stories (Cover*), and documented in Card.mdx. Hard inputs and failure states are in Components/Card/Edge Cases (#20152), which share their fixtures with the browser tests.

• Label bar (Cover): when the header has text (the label attribute or slot, a [data-card-label] element in the header slot, which element cards' titles now carry, or a badge), the header gets a bar the height of a normal card's header. It's 60% black or 52% white, blurred with the same blur as the index footer (--blur-md), and has a 1px bottom border in translucent white (20%) or black (15%).
• Backed controls (CoverBackedControls): with no text in the header, the checkbox and plain buttons always get a 65% backing in the color opposite their ink, blurred like the label bar. It strengthens to 80% when a button is hovered or pressed. The checkbox's backing extends 1px past its border, drawn with a 0 0 0 1px box shadow.
• Scrim: the content sits on a black or white scrim that fades in over 4.5rem above it with an eased curve, and is at full strength behind all of the text. The image blurs in under it by 1px, from halfway down the fade, so it stays crisp until just above the text (a backdrop-filter layer faded in with a mask). The blur reaches the card's edges, under its 1px border, as the image does, so no band of the sharp image shows along the sides and bottom.
• Hard images (CoverHardImages): plain white and black, thin stripes, and portraits whose measured rows are cropped out.
• Unknown luminance (CoverWithoutLuminance): images sampled before luminance was don't have it yet, so the card uses white on black.
• Not loaded or broken (CoverImageNotLoaded, CoverBrokenImage): the fills don't depend on the image, so text is legible before it loads. If it fails to load, the card falls back to a normal one with its thumbnail.
• Long content (CoverLongContent, CoverManyAttributes): the card grows past 4:3 to fit its content, with the scrim behind all of it, and the rest of its row grows to match.
• Selected (CoverActive): an accent border and a 2px accent ring.
• Normal cards alongside (CoverAlongsideNormalCards): only thumbnail images at least 480×360, between 3:4 and 2:1, and not possibly transparent get a cover (Asset::canCoverCard()). Smaller, narrower, or wider ones would be scaled up or cropped too far, and transparent ones would show the card's fill through them, so they keep the normal thumbnail card.

The layout rules, which hold for every variation:

• The ink is pure white at 90% or pure black at 85%, never a tint of the image.
• data-theme goes on the slotted header and content, not on the card, so checkboxes and other controls take the theme that matches the ink, while the card's own border, corners, and shadow follow the page's theme.
• The header's bottom border is always there, and only becomes visible with a bar, so turning the bar on or off moves nothing in the header.
• Header buttons in a cover card are never flush, so they line up with other cards' buttons.
• Card attribute previews are limited to one line, rather than two, so the content leaves more of the image showing. Previews that opt out of truncation (generated fields, chips, addresses) are left alone.
• A cover card's data-color (such as an entry type's color) only colors its outer border, semi-transparent over the image, in the page's light or dark theme as a normal card's border would be. Everything laid over the image keeps its white or black ink.
• A cover card is at least 4:3, and grows taller when its content needs more room, rather than running past its bottom padding. The card clips its overflow, which stops an aspect-ratio from growing, so it's a grid with a 4:3 spacer under its content instead.
• A cover card never grows past its column, so a long, truncated title can't widen it into the next card.
• The card's 1px border is an inset box shadow drawn over the image, bar, and scrim (::after), and the card clips to its rounded corners.

Normal card headers

Normal cards follow the same header rules as cover cards:

• With a label (the label attribute or slot, or a [data-card-label] element in the header slot), the header keeps its bar. Element cards' card titles carry data-card-label, so entry cards keep theirs, with their entry type's label and icon.
• Without a label, the header has no fill or rule of its own, so the checkbox and action button float over the card (card--bare-header). Its border stays, transparent, so the controls are exactly where they'd be with a bar. In a selected card, its controls take the body's colors rather than the selected bar's, which would be light on light.
• With nothing to show (no text, and nothing but empty divs and spans), the header isn't rendered, so the body is flush with the top of the card. The card re-renders on text changes in its light DOM too, as element cards fill their headers after it first renders.
• Matrix blocks' and workflow stages' titles now carry data-card-label, so they keep their bars.

Merged into this branch

• [6.x] Thumb Sources #20181 Thumb Sources: multiple ordered thumb sources, Thumb Style for every layout, user photo and Content Block covers, and ElementInterface::getThumb(), which returns a size-independent CraftCms\Cms\Element\Data\Thumb with getHtml(), getAsset(), and supportsCover(). FieldLayout::$thumbFieldKey and thumbFieldKey() are deprecated in favor of $thumbSources and thumbSources(). See that PR for the full API.
• [6.x] Cover cards: fixed fills so text and controls pass contrast over any image #20152 Cover card contrast (@gcamacho079): fixed fills that pass over any pixel, always-backed header controls, black and white focus rings, the broken image fallback, the edge case stories, and pixel-measured contrast tests.

Accessibility

• Contrast. Text gets at least 4.5:1 and controls 3:1 (WCAG 1.4.3 and 1.4.11) over any pixel, in either theme. The fills are fixed, so the contrast doesn't depend on the image, how it's cropped, or whether it has loaded. The worst case for text is about 5:1: 90% white ink over 60% black on a pure white pixel, or 85% black ink over 52% white on a pure black one.
• Measured against rendered pixels. The card's browser tests measure every pixel behind the text and controls over the hard images, with a long label and a body full of attributes. A temporary run over cards grown well past 4:3 (240 and 332px wide) and one forcing white on black over every hard image, including pure white, also found nothing under 4.5:1. Neither is kept as a test.
• Semi-transparent text. The a11y guidance warns against alpha text, because its contrast depends on what's behind it. Here it's deliberate: the ink sits on a fixed fill whose opacity is computed against the ink's worst case, so the result is predictable.
• Focus. Focused controls in a cover card get a black and white ring, which stands out over either theme's fill.
• Clamped previews. One-line previews hide the rest of their text behind an ellipsis. The full value is on the element's own page. I haven't checked how screen readers read the clamped text.
• Forced colors. Gradients, backdrop filters, and box shadows are dropped in forced colors, so there the header, content, and footer get a Canvas background over the image, and the card gets a real CanvasText border (Highlight when selected). This hasn't been tested in an actual forced-colors browser.
• Images. The cover is a decorative <img alt="">, because the card's content already names the element. The thumbnail isn't rendered. The designer's preview photo is decorative too.
• Thumb Style and Thumb Sources settings. Thumb Style is a labeled radio group with instructions, operated as a native radio group. Its illustrations are decorative (alt="") and sit in <label for> elements, so clicking one selects its option. Thumb Sources is a craft-checkbox-select, with labeled remove and reorder buttons and an “Add item” menu.
• Bare headers. On a normal card without a label, the header controls sit on the card's own body color. In a selected colored card, a checked checkbox keeps 3:1 and its border matches the body text.
• Selection. A selected cover card is marked by its checkbox as well as the accent ring.
• axe. axe measures cover-card text against the fill behind the image, so it reports false failures in the cover stories. Those stories turn off color-contrast for content inside craft-card[cover-src] only, and the browser tests check that contrast instead.
• Checklist. card.a11y.md has a Cover cards section, and each requirement names the test that verifies it.

The screenshots below predate #20152's fixed fills and the dark-first theme rule, so some bars and scrims in them are lighter, and On White II would now get white on black.

Screenshots

The collection folder in cards view. Every image but Wheatfield under Thunderclouds gets a cover.

Checkbox only: the checkbox is backed, since the image behind it is too busy for 4.5:1 on its own, and the backing is blurred.	Wheatfield under Thunderclouds (2400×1173) is wider than 2:1, so it keeps the normal card. Nothing in this folder is under 480×360.
High contrast: Klimt’s The Tree of Life, with regions from bright gold to near black. The blurred scrim keeps the title legible over the busy swirls.	Low contrast: Klimt’s Portrait of Adele Bloch-Bauer I, mostly even midtones.
Light image: Kandinsky’s On White II, the lightest in the folder.	Dark image: Van Gogh’s Self-Portrait, the darkest in the folder.
An entry: The Starry Night, a Collection entry (Work type) whose thumbnail field is an Assets field. Its card title gives the header a label, so it gets the label bar, with the checkbox in it. The Work entry type is violet. This shot predates cover cards taking that color for their border; the Cover designer shot below shows it.

Card view designer

Thumb Style set to Normal, with Thumb Alignment after it. The settings scroll beside the preview (shown scrolled to the bottom).

Thumb Style set to Cover: the preview becomes a cover card, taller than 4:3 to fit its content, with the Exhibit type's indigo as its border, and Thumb Alignment is hidden.

Evidence

• cover.test.ts:
  • Composites the ink over each theme's fill and backing on any sRGB pixel, independently of the card's own math, and checks 4.5:1 for text and 3:1 for controls, resting and hovered.
  • uses the fixed fills over …: light, dark, busy, pure white, pure black, unknown, and transparent luminance.
  • picks dark, with deep shadows under bright highlights and picks dark, when one region has shadows fail under the old contrast-based rule. picks light, when every region is light and picks light, for a pale image cover the other side of the 0.25 cutoff.
  • reads the header from the top row and the content from the bottom row, and white on black when the luminance is unknown or transparent.
• card.browser.test.ts, cover cards:
  • gives every pixel behind a cover card’s text 4.5:1, and behind its controls 3:1 and gives every pixel behind a cover card’s attributes 4.5:1, over each hard image and an image that hasn't loaded.
  • keeps every line of a cover card’s text and its controls where its fill is at full strength, across widths, text lengths, and text spacing.
  • keeps a cover card’s header controls in place when its header gets a label bar: header, checkbox, label, and button rects are identical with and without the bar.
  • grows a cover card past 4:3 when its content needs more room, and keeps a cover card within its width when its content has a long title.
  • gives a cover card’s border its color, and nothing else, reads a cover card’s luminance when it’s set as a JSON string, backs a cover card’s plain buttons more strongly when they’re hovered, gives a cover card’s focused … a black and white ring inside the card, and falls back to a normal card when its cover image fails to load.
• card.browser.test.ts, normal card headers: drops a card’s header bar when it has no label, keeping its controls in place, keeps a selected card’s bare header controls legible against its body, and leaves out a header with nothing to show, so the body starts at the card’s top.
• ElementHtmlTest:
  • covers an asset’s card only with an opaque image that can fill it: the size and ratio edges (479/480 wide, 359/360 tall, 2:1 vs. wider, 3:4 vs. narrower) and transparency.
  • An entry is covered by its Assets thumb source's image with Cover, and not with Normal, and by the first source that has a thumbnail.
  • An Assets field within a Content Block, and a user's photo, cover their cards.
  • An asset in a volume set to Normal keeps the normal card.
• CardDesignerTest: the preview is a cover card for asset volumes by default and for layouts set to Cover. Thumb Style is shown for every layout, and Thumb Alignment unless there's no thumbnail or cards are covered. Only entry type previews have a header. The sample image follows the theme.
• FluentBuilderTest: cardThumbStyle defaults, config round-trip, and rejecting invalid values. thumbFieldKey maps onto thumbSources.
• In the control panel: a user with a photo gets a cover card in the users index, and a cover card's attribute preview is clamped to one line while a normal card's is clamped to two.
• Card suite (vp test run src/components/card): 134 passed. vue-tsc: clean.

🤖 Generated with Claude Code

[github-actions]

📚 Storybook previews

@craftcms/ui — open Storybook

Changed components:

• Components/Card
• Components/Card/Edge Cases

resources/js — open Storybook

No changed components detected in this Storybook.

[thupsi]

@brandonkelly This is awesome, and I expect it will look great on photo-driven sources!

One reservation is the flip between white and dark text (with the matching scrim) depending on image luminance. With both variants side by side in the same grid, it looks a little inconsistent to me, and I find the dark scrim with light text more legible in most cases.

In the example below, the dark text would be applied (left), but the white text version (right) looks cleaner to me. The white scrim washes the photo out, while the dark one reads more like a natural shadow and keeps the image's depth:

I realize white text on very bright images needs a heavier scrim to hold contrast, so there's a tradeoff. Maybe the flip to dark text could kick in only for the brightest images, so most cards stay consistent?

[brandonkelly]

@thupsi Good call, done: