Examples

Basic Usage

The Story Card only needs a few data points to render a fully functional card.

Best Practices:

The headline and text should use sentence-case

Headlines shouldn't hold more than 75 characters, and a maximum of 40 when displaying Asian characters

Images should always be paired with an alternative text to support assistive technologies

Extended Usage

Optionally, the Story Card can be extended with additional information

Best Practices:

The tag should use title-case

The tag is used to categorize cards, for example by discipline

The badge is only used for promoting selected cards

The estimated reading time is rounded to full minutes using a minimum of one minute

Preview Video

A great way to turn the Story Card into an engaging teaser is to add a video that appears on hover gesture

In some cases it might be preferred to not rely on the hover gesture and play the video depending on other triggers. This can be done by setting the play-video attribute on the card.

Preview Image

To improve the user experience Story Cards can display preview images while waiting for the high-resolution image to be loaded.

Note: The example below demonstrates the rendering of the preview image only. In a production environment, a high-resolution _image_ would be set alongside.

Best practices:

Preview images should be a scaled version of the featured image with a maximum of 50px width

To ensure meaningful content to be shown as fast as possible without any additional network requests preview images should be provided as base64 encoded data URIs

Responsive Image and Performance

A great way to balance client-side performance and responsive images is by using srcset in conjunction with sizes and loading attributes. Read more about responsive image best practices here: Image

Logo

Instead of a tag, Story Cards can display a logo.

Best practices:

The logo is only to be used for brands or projects, not for sponsors

Logos should be SVG or PNG images with a transparent background

Logos with a width/height ratio lower than 1.5 should have logo-narrow enabled to optimized the appearance on the card

Make it favoritable

Story Cards can be favorited by users – while the favorite button will be persistently displayed on touch-based devices, the button will only show up on hover on devices with pointer-based inputs.

Best practices:

The state of whether the Story has been favorited or not has to be managed outside the component

The favorite-aria-label should reflect the action that will be performed based on the current "favorite" state

Clicking on the favorite button won't propagate the click event to the card component and won't go in the way of catching link redirection.

Mode and Appearance

By default, Story Cards adapt to a light mode environment and appear to light themselves. In a dark mode environment, we recommend changing the Story Card appearance to dark.

💡 Pro Tip

The appearance of a Story Card can be set using the appearance property or by nesting it into a cosmos-mode component. Read more about the Mode & Appearance concept.

Best practices:

The appearance of the card should follow the mode of the environment: The card appears light in a light environment and dark when used inside a dark environment.

The Story Card can use a light appearance in a dark environment for high-contrast designs, but should not use a dark appearance in a light environment

Compact Layout

Story Cards support a compact layout for use cases where it doesn't have enough space available.

💡 Pro Tip

The Story Card's layout is a Responsive Properties and can be configured per breakpoint. Try out this example

Best Practices:

The Story Card should use a compact layout whenever the available width is smaller than 290px

Listen to Resize Events

When initially mounting and whenever the media container of the Story Card resizes, the card emits a mediaresize event including the media's width and height.

A common use-case is to update the image to make it perfectly fit the available space.

Best Practices:

Only enable the observe-media-resize when needed