Card

Anatomy

1. Card Container: This rectangular container is the fundamental part of this component. It is styled with Canvas Tokens to ensure the background color, corner radius, depth, and outline stroke are coherent as a basis with cards within workday. This can be used as the basis for creating more tailored card types.
2. Title (Optional): The title explained
3. Paragraph (Optional): The Paragraph explained

Usage Guidance

• Cards hold a variety of content types, such as a combination of text, icons, imagery and actions related to a single topic.
• Check out the Card Framework Figma library created for the UI Platform framework for design guidance on how to layout and style your cards.
• Cards should be easy to digest, providing relevant information and available actions.
• Text and visual elements should be placed in a way that clearly indicates hierarchy.
• Cards should be placed inside a layout grid to help with alignment and sizing.
• Most cards are created and maintained by specific product teams. The Canvas card is a generic container which you can leverage when creating new cards. Check out the Canvas Kit card container to see what’s available in Canvas now.
• Need to create your own custom card for your product? Check out our Customizing Canvas section for guidance on creating new components in keeping with Canvas.

When to Use

• Use Cards when you need to group information in a digestible form.
• Use Cards when you need to offer a short entry point that is linked to more detailed content or a complex task.
• Use Cards to lay out single or multiple sets of related information in the same region of the page. Cards may include an image, a text summary, pills, and actions. Cards typically have similar widths, but heights should accommodate varying content.

When to Use Something Else

• When you need to show unrelated content types or actions in a single container.
• When you need to show content in multiple columns.
• When you need to display content in a table format.

Examples

Basic Example

Card includes a container component and Card.Body and Card.Heading subcomponents.

import React from 'react';
import {Card} from '@workday/canvas-kit-react/card';

export default () => {
  return (
    <Card>
      <Card.Heading>Canvas Supreme</Card.Heading>
      <Card.Body>
        Our house special supreme pizza includes pepperoni, sausage, bell peppers, mushrooms,
        onions, and oregano.
      </Card.Body>
    </Card>
  );
};

Borderless Example

The borderless variant removes the border from the Card, creating a cleaner appearance while maintaining the same internal spacing and structure. Use this variant when placing cards on colored backgrounds where you want the card to blend seamlessly without borders or shadows.

import React from 'react';
import {Card} from '@workday/canvas-kit-react/card';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const styles = createStyles({
  background: system.color.bg.alt.softer,
  padding: system.space.x4,
});

export default () => {
  return (
    <div className={styles}>
      <Card variant="borderless">
        <Card.Heading>Canvas Supreme</Card.Heading>
        <Card.Body>
          Our house special supreme pizza includes pepperoni, sausage, bell peppers, mushrooms,
          onions, and oregano.
        </Card.Body>
      </Card>
    </div>
  );
};

Filled Example

The filled variant adds a background color to the Card, creating a more prominent appearance while maintaining the same internal spacing and structure. Use this variant when you need a card with a grayish background to create visual separation from the page background.

import React from 'react';
import {Card} from '@workday/canvas-kit-react/card';

export default () => {
  return (
    <Card variant="filled">
      <Card.Heading>Canvas Supreme</Card.Heading>
      <Card.Body>
        Our house special supreme pizza includes pepperoni, sausage, bell peppers, mushrooms,
        onions, and oregano.
      </Card.Body>
    </Card>
  );
};

Custom Styles

Card and its subcomponents support custom styling via the cs prop. For more information, check our “How To Customize Styles”.

import * as React from 'react';

import {Card} from '@workday/canvas-kit-react/card';
import {createStyles, px2rem} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const customCardStyles = createStyles({
  boxShadow: system.depth[2],
  maxWidth: px2rem(320),
  padding: system.space.x3,
});

export default () => (
  <Card cs={customCardStyles}>
    <Card.Heading>Canvas Supreme</Card.Heading>
    <Card.Body>
      Our house special supreme pizza includes pepperoni, sausage, bell peppers, mushrooms, onions,
      and oregano.
    </Card.Body>
  </Card>
);

Stencils

You can also use Card stencils to extend styles for your own custom components. This allows you to compose styles without using components directly. In the example below, we’re extending Card stencils to create a custom MenuCard component.

Here’s an example of a Card with a reduced padding of x3 (0.75rem or 12px).

import * as React from 'react';
import {cardStencil, cardBodyStencil, cardHeadingStencil} from '@workday/canvas-kit-react/card';
import {createComponent} from '@workday/canvas-kit-react/common';
import {createStencil, px2rem, CSProps, handleCsProp} from '@workday/canvas-kit-styling';
import {system, brand} from '@workday/canvas-tokens-web';

const menuCardStencil = createStencil({
  extends: cardStencil,
  base: {
    display: 'flex',
    flexDirection: 'column',
    padding: system.space.zero,
    maxWidth: px2rem(320),
    boxShadow: system.depth[1],
    overflow: 'hidden',
  },
});

const menuCardHeroStencil = createStencil({
  base: {
    display: 'flex',
    alignItems: 'flex-end',
    background: brand.gradient.primary,
    aspectRatio: '1',
    maxHeight: px2rem(80),
    padding: system.space.x2,
  },
});

const MenuCardHero = createComponent('div')({
  displayName: 'MenuCard.Hero',
  Component: (elemProps: CSProps, ref, Element) => {
    return <Element ref={ref} {...handleCsProp(elemProps, menuCardHeroStencil())} />;
  },
});

const menuCardContentStencil = createStencil({
  base: {
    display: 'flex',
    flexDirection: 'column',
    gap: system.space.x2,
    padding: system.space.x2,
  },
});

const MenuCardContent = createComponent('div')({
  displayName: 'MenuCard.Content',
  Component: (elemProps: CSProps, ref, Element) => {
    return <Element ref={ref} {...handleCsProp(elemProps, menuCardContentStencil())} />;
  },
});

const menuCardHeadingStencil = createStencil({
  extends: cardHeadingStencil,
  base: {
    color: brand.primary.accent,
    margin: system.space.zero,
  },
});

const MenuCardHeading = createComponent('h3')({
  displayName: 'MenuCard.Heading',
  Component: (elemProps: CSProps, ref, Element) => {
    return <Element ref={ref} {...handleCsProp(elemProps, menuCardHeadingStencil())} />;
  },
});

const menuCardTextStencil = createStencil({
  extends: cardBodyStencil,
  base: {
    margin: 0,
  },
});

const MenuCardText = createComponent('p')({
  displayName: 'MenuCard.Text',
  Component: (elemProps: CSProps, ref, Element) => {
    return <Element ref={ref} {...handleCsProp(elemProps, menuCardTextStencil())} />;
  },
});

const MenuCard = createComponent('div')({
  displayName: 'MenuCard',
  Component: (elemProps: CSProps, ref, Element) => {
    return <Element ref={ref} {...handleCsProp(elemProps, menuCardStencil())} />;
  },
  subComponents: {
    Content: MenuCardContent,
    Heading: MenuCardHeading,
    Hero: MenuCardHero,
    Text: MenuCardText,
  },
});

export default () => (
  <MenuCard>
    <MenuCard.Hero>
      <MenuCard.Heading>Sausage Pizza</MenuCard.Heading>
    </MenuCard.Hero>
    <MenuCard.Content>
      <MenuCard.Text>
        Red sauce, homemade seasoned sausage, mushrooms, red bell peppers, rosemary, cheese.
      </MenuCard.Text>
      <MenuCard.Text></MenuCard.Text>
    </MenuCard.Content>
  </MenuCard>
);

Component API

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<Card role="dialog" aria-labelledby="card-heading">
  <Card.Heading id="card-heading">Card Title</Card.Heading>
  <Card.Body>Card Contents</Card.Body>
</Card>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

Accessibility Guidelines

Keyboard Interaction

Any interactive elements in the Card must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.

Cards must support the following keyboard interactions:

• Tab: Focuses interactive elements included in the card (e.g. buttons, links, inputs, selects, etc.)

Screen Reader Interaction

Cards must communicate the following to users:

• The title (heading) of a Card represents the beginning of the content in a card.
• Calls to action in a Card are uniquely distinguishable from other cards on the screen.

Design Annotations Needed

• Decide heading level for the Card title in context of the page. Read more about meaningful page structure for more information.
• Write accessible name for icon-only button variants. Read more about non-text content.
• Write unique accessible names for generic call to action buttons.
• Write text alternatives for images and illustrations, unless they are for decorative purposes only.

Implementation Markup Needed

• Cards must begin with a heading element <h2> - <h6>.
• When using multiple cards together in a group, use <ul> and <li> elements to build card containers as list items in an unordered list.
• An aria-label string is required for icon-only buttons and accessible tooltips can show the icon’s name for everyone.
• Images, illustrations, and icons that may be considered decorative or redundant can be hidden from screen readers by setting a null alt=”” attribute for <img> elements.
• [Included in component] Decorative <svg> icons are hidden from assistive technology with role=”presentation” and focusable=”false”.

Content Guidelines

• When writing content for Cards, refer to our Content Style Guide

Anatomy

1. Card Container: Cards are empty containers with design tokens applied to them.

2. Card Image (Optional): Supporting image or media element

3. Card Header (Optional): Commonly used for card titles

4. Card Body (Optional): Main content area that can hold custom layouts and other components

5. Card Footer (Optional): Mainly for actions or metadata

Usage Guidance

Cards are empty containers with basic styling applied to them. They are highly composable and can hold many types of content related to a single topic. Cards should summarize details about that topic and generally be interactive, taking users to full details.

Cards are Composable

Cards are containers that hold related content and actions about a topic. They are highly composable building blocks with any type of content, including other components, layouts, images, and steps.

Cards are Actionable

Cards should be interactive and lead to more details about a topic.

A Card may have multiple tap targets in CardFooter.

Try to keep Cards focused and avoid crowding the Card with multiple actions

Cards are Grouped

Cards are normally part of a larger collection of related cards. Isolated cards are rare. Make sure Cards are modular - each card being independent of each other.

Cards should be modular, meaning each card can exist independently without relying on another card’s content.

Cards are Consumable

Cards should be easily identifiable when contrasted against the rest of the page, grouped by a perceived boundary.

Borders, negative space, depth, or background color to a Card are all acceptable ways to separate a Card from the rest of the UI.

Cards are Adaptive

Card width and height should be adaptive to their context, alignment and sizing being determined by their parent layout. Truncation rules should be set by feature teams based on the layout used.

vStacks

Cards that are stacked on top of each other should prioritize card content instead of truncating text. Cards by default span edge-to-edge for screen margins.

As a rule of thumb, keep copy 3 lines or less avoid to overwhelming users.

Carousel Layout

Cards in a carousel should truncate text content instead of growing the content to preserve the baseline alignment of all cards in the same group.

When to Use

• To group and present related information (icons, text, actions) in a digestible way.
• To provide an entry point to more details. Cards provide a summary rather than the full details right away.
• To contain flexible layouts. Layouts may contain any type of content. Cards typically have similar widths, but heights should accommodate varying content.
• To display variable content that is different between Cards. Cards are differentiated from one another by their content.
• To build other card-like components, like an Alert Dialog.

When to Use Something Else

1. Use Text if content cannot exist separately from other Cards. Don’t force users to read card to card.
2. Use a List when users need to compare and contrast options against each other.
3. Use a Button for simple call to actions.
4. Use a Table for tabular content with multiple columns.
5. If no action is provided on the card, consider if a Card needs to be used at all.

Examples

Composition

Cards are composed of four content slots that are used for different purposes. All content slots are optional.

CardContainer

Card containers hold all card elements. Their size is determined by their content.

CardImage

By default, images render at the top of the card with an aspect ratio of {16/9}.

CardImage support custom aspect ratios.

CardHeader

CardHeader is an optional sub-component. It mainly serves as a title to identify the Card and defaults to h3.

1. Title: often communicates the subject of the card, such as the name of a feature area.
2. Subtext or Body Text(Optional): Subtext are smaller text elements, such as a byline in an article card. Body text includes body content, such as a snippet of an article.
3. Lead Area (Optional): An AccentIcon or Avatar may be used at the start of CardHeader.

CardHeader may be swapped with a custom header.

CardBody

CardBody serves as the primary content slot of the Card. This is where the main content should go. Any type of content may be used in Card.

In general, try to limit the amount of content that goes into a Card, as it’s meant to be a preview. One example could be to limit body text to 3 lines before truncating content.

CardFooter

CardFooter should be used for additional actions or metadata.

Don’t use Primary Buttons in CardFooter. Instead, the primary action should be placed on the entire Card.

Only display one Secondary or Tertiary Button in CardFooter. Any additional actions should be placed in the Overflow Menu.

CardFooter can be swapped with a custom footer component, if you’d like.

Overflow Menu

Overflow Menus contain related actions on the Card. They are typically placed in CardHeader or CardFooter.

Link

Cards should be interactive. They support the Link and onTapGesture properties. Both properties can be passed to Card so that the correct tag is created for screen readers.

Size

Three size options are provided by default - small, medium, and large. Increases in size are represented as increases in Card padding.

Custom Padding & Spacing

You may choose to overriding defaults with space tokens. See the Space article to learn more.

Style

Three visual styles of Cards - Elevated, Filled,and Outlined. There is no difference between Card styles and their function.

To determine what style to use, consider contrast requirements, and the consistent application of style across a feature.

Elevated

Use depth to show or hide an elevation on the card.

When depth is set to true, the border is set to false. Don’t use both depth and border on a card.

Filled

Filled Cards have default their background color to frenchVanilla100. Filled cards do not have a border or depth applied by default.

The color parameter can be used to change the background color of the card to something else.

In general, avoid changing the background color of Cards unless it’s necessary for contrast or feature requirements.

Outlined

A border may be used instead of depth. Outlined cards should not have a depth but may have a background color.

Images

A supporting visual can be used to make it easier to for users to identify a Card.

Overflow Actions

Overflow menus contain related actions. They are typically placed in the upper-right or lower-right corner of a card.

API Guidelines

Methods

Class name: CardComponent Module name: UIComponentsPlugin

    public init(
        featureData: FeatureMetricsData,
        media: Media? = EmptyView(),
        header: Header? = EmptyView(),
        content: Content? = EmptyView(),
        footer: Footer? = EmptyView(),
        style: CardStyle = .elevated,
        size: CardSize = .medium,
        cardTapActionInfo: CardTapActionInfo? = nil,
        accessibilityLabel: String = "",
        customActions: [CardCustomAction] = [],
        overflowButtonConfig: CardOverflowButtonConfig? = nil,
        fillVerticalSpace: Bool = false
    )

Parameters

Accessibility Guidelines

• If the entire card is tappable and it has nested controls, use custom actions to ensure Full Keyboard Access (FKA) users can access the nested controls as custom actions.

• Do not use tappable cards when nested controls cannot be implemented as custom actions. For example, ‘expandable containers’ do not work within custom actions so you cannot use custom actions here. Given custom actions are the only way to ensure keyboard users can access nested controls the only option is to not have tappable cards in the scenario.

• For blind users it is not always easy to determine where one card begins and where one ends or to understand that the card is grouped. Sighted users can see the borders of the card and the position of all the content within the card and understand that they form a card/group. In order to make grouping clearer, implement one of the following in order of preference:

  1. Have each card be a single accessibility element, because it is one element detected by VoiceOver, users understand it is grouped for a reason. This can work even if the card contains multiple buttons because the additional buttons (including overflow) can be customActions as long as they are all related.

  2. Use a heading for the card title; this will successfully denote the start of the card content and a new heading denotes the end of the previous card and start of a new one.

  3. Use the card title in each button name as a suffix. Let’s say the title name is ‘Plants’ e.g. ‘First button, Plants’ ‘Second button, Plants’ and ‘Open Menu, Plants’.

• Graphics and icons that do not communicate any additional information beyond what is represented in text may be considered decorative and should not provide any text alternative.

• The button text and background color must meet the minimum contrast requirement.

• For more accessibility considerations, refer to the Accessibility Guide.

Anatomy

1. Card Container: Cards are empty containers with design tokens applied to them.

2. Card Image (Optional): Supporting image or media element

3. Card Header (Optional): Commonly used for card titles

4. Card Body (Optional): Main content area that can hold custom layouts and other components

5. Card Footer (Optional): Mainly for actions or metadata

Usage Guidance

Cards are empty containers with basic styling applied to them. They are highly composable and can hold many types of content related to a single topic. Cards should summarize details about that topic and generally be interactive, taking users to full details.

Cards are Composable

Cards are containers that hold related content and actions about a topic. They are highly composable building blocks with any type of content, including other components, layouts, images, and steps.

Cards are Actionable

Cards should be interactive and lead to more details about a topic.

A Card may have multiple tap targets in CardFooter.

Try to keep Cards focused and avoid crowding the Card with multiple actions

Cards are Grouped

Cards are normally part of a larger collection of related cards. Isolated cards are rare. Make sure Cards are modular - each card being independent of each other.

Cards should be modular, meaning each card can exist independently without relying on another card’s content.

Cards are Consumable

Cards should be easily identifiable when contrasted against the rest of the page, grouped by a perceived boundary.

Borders, negative space, depth, or background color to a Card are all acceptable ways to separate a Card from the rest of the UI.

Cards are Adaptive

Card width and height should be adaptive to their context, alignment and sizing being determined by their parent layout. Truncation rules should be set by feature teams based on the layout used.

vStacks

Cards that are stacked on top of each other should prioritize card content instead of truncating text. Cards by default span edge-to-edge for screen margins.

As a rule of thumb, keep copy 3 lines or less avoid to overwhelming users.

Carousel Layout

Cards in a carousel should truncate text content instead of growing the content to preserve the baseline alignment of all cards in the same group.

When to Use

• To group and present related information (icons, text, actions) in a digestible way.
• To provide an entry point to more details. Cards provide a summary rather than the full details right away.
• To contain flexible layouts. Layouts may contain any type of content. Cards typically have similar widths, but heights should accommodate varying content.
• To display variable content that is different between Cards. Cards are differentiated from one another by their content.
• To build other card-like components, like an Alert Dialog.

When to Use Something Else

1. Use Text if content cannot exist separately from other Cards. Don’t force users to read card to card.
2. Use a List when users need to compare and contrast options against each other.
3. Use a Button for simple call to actions.
4. Use a Table for tabular content with multiple columns.
5. If no action is provided on the card, consider if a Card needs to be used at all.

Examples

Composition

Cards are composed of four content slots that are used for different purposes. All content slots are optional.

CardContainer

Card containers hold all card elements. Their size is determined by their content.

CardImage

By default, images render at the top of the card with an aspect ratio of {16/9}.

CardImage support custom aspect ratios.

CardHeader

CardHeader is an optional sub-component. It mainly serves as a title to identify the Card and defaults to h3.

1. Title: often communicates the subject of the card, such as the name of a feature area.
2. Subtext or Body Text(Optional): Subtext are smaller text elements, such as a byline in an article card. Body text includes body content, such as a snippet of an article.
3. Lead Area (Optional): An AccentIcon or Avatar may be used at the start of CardHeader.

CardHeader may be swapped with a custom header.

CardBody

CardBody serves as the primary content slot of the Card. This is where the main content should go. Any type of content may be used in Card.

In general, try to limit the amount of content that goes into a Card, as it’s meant to be a preview. One example could be to limit body text to 3 lines before truncating content.

CardFooter

CardFooter should be used for additional actions or metadata.

Don’t use Primary Buttons in CardFooter. Instead, the primary action should be placed on the entire Card.

Only display one Secondary or Tertiary Button in CardFooter. Any additional actions should be placed in the Overflow Menu.

CardFooter can be swapped with a custom footer component, if you’d like.

Overflow Menu

Overflow Menus contain related actions on the Card. They are typically placed in CardHeader or CardFooter.

Link

Cards should be interactive. They support the Link and onTapGesture properties. Both properties can be passed to Card so that the correct tag is created for screen readers.

Size

Three size options are provided by default - small, medium, and large. Increases in size are represented as increases in Card padding.

Custom Padding & Spacing

You may choose to overriding defaults with space tokens. See the Space article to learn more.

Style

Three visual styles of Cards - Elevated, Filled,and Outlined. There is no difference between Card styles and their function.

To determine what style to use, consider contrast requirements, and the consistent application of style across a feature.

Elevated

Use depth to show or hide an elevation on the card.

When depth is set to true, the border is set to false. Don’t use both depth and border on a card.

Filled

Filled Cards have default their background color to frenchVanilla100. Filled cards do not have a border or depth applied by default.

The color parameter can be used to change the background color of the card to something else.

In general, avoid changing the background color of Cards unless it’s necessary for contrast or feature requirements.

Outlined

A border may be used instead of depth. Outlined cards should not have a depth but may have a background color.

Images

A supporting visual can be used to make it easier to for users to identify a Card.

Overflow Actions

Overflow menus contain related actions. They are typically placed in the upper-right or lower-right corner of a card.

API Guidelines

Methods

  fun CardUiComponent(
    modifier: Modifier = Modifier,
    contentModifier: Modifier = Modifier,
    contentArrangement: Arrangement.Vertical = Arrangement.spacedBy(WorkdayTheme.canvasSpace.x4),
    size: CardSize = CardSize.Medium,
    style: CardStyle = CardStyle.Elevated,
    mediaConfig: CardMediaConfig? = null,
    customMediaContent: @Composable (() -> Unit)? = null,
    headerConfig: CardHeaderConfig? = null,
    headerTitleTextStyle: TextStyle = WorkdayTheme.canvasTypography.bodyLarge.toBold700Weight(),
    headerSubtitleTextStyle: TextStyle = WorkdayTheme.canvasTypography.bodySmall,
    customHeaderContent: @Composable (() -> Unit)? = null,
    footerConfig: CardFooterConfig? = null,
    customFooterContent: @Composable (() -> Unit)? = null,
    overflowMenuConfig: CardOverflowMenuConfig? = null,
    onClick: (() -> Unit)? = null,
    interactionSource: MutableInteractionSource = remember { MutableInteractionSource() },
    semanticProperties: CardSemanticProperties = CardSemanticProperties(),
    content: @Composable (() -> Unit)? = null,
)

Parameters

Accessibility Guidelines

Coming soon!