Cards

The actual card content is markdown
Card titles are not links
Card titles never become entries in the page index nav like section headings.
Card titles of both sizes are rendered as H6 to enhance accessibility while making sure they are always "inside" the actual headings
Either an icon or an image path can be set, but not both.
- To start with, Images are not supported for free-form in-content cards, only in places that are fully designed and implemented by developers. An Image is sized into the width of the card.
- Icons are supported anywhere but only those that are officially provided by the kit. An icon is sized into a fixed 48x48px square.
Cards can occur in two interaction variants, "clickable" (visually elevated) and "flat" (visually an outline only).
Cards must be embedded into a wrapper component that defines the responsive sizes (two aside / three aside) and parameters that must be identical in a given row or grid (clickable card area, the heading size)
A single card must not fill the full width but stay left aligned.
Multiple cards fill the full width and are scaled up to fill even if their content is smaller. Every card has the same width in all rows (resulting in a grid if it's multiple rows)
Cards are sorted in rows, then columns.
on the landing pages (src/index.mdx) a regular card has a minimum width of 328px and a narrow card a minimum width of 242px. This assures they stay 2- and 3-aside respectively.
if it's possible, cards would have different minimum sizes on content pages: narrow card 248px and regular 377px.

"Cards" Wrapper

Properties (for authors):

clickable (boolean): if set, the whole area of all child cards is a link, the card is elevated and has a hover effect if a link URL is set.
narrow (boolean): by default, two cards are shown side by side (except mobile viewports). if narrow is passed, the minimum card width is reduced so that three cards fit the content width on microsite landing pages.
smallTitle (boolean): lets all cards have a smaller title font.
fitContentColumn (boolean): renders a little differently for cards used on content pages. The is automatically set for cards on landing pages.

Minimal form

<Cards>
  <Card>foo</Card>
  <Card>bar</Card>
  <Card>next row unless three aside (narrow) prop passed?</Card>
  <Card>next row in any case</Card>
</Cards>

Output

foo
bar
next row unless three aside (narrow) prop passed?
next row in any case

All options configured

<Cards clickable narrow smallTitle fitContentColumn>
  <Card>foo</Card>
  <Card>bar</Card>
  <Card>next row unless three aside (narrow) prop passed?</Card>
  <Card>next row in any case</Card>
</Cards>

Output

"Card": the actual card

Properties (for authors):

title (string): the card title, no markdown allowed.
href (string): the link target of the bottom link and, if clickable is set, the whole card. href has no effect when neither clickable or textLink are set.
textLink (string): the bottom link text. If not set, no bottom link is rendered at all.
icon (component): the component to be rendered into the 48x48px space reserved for an icon. If not set, the space is not reserved.

None of the properties are required but the body content should not be empty.

Flat with Link

<Cards>
  <Card
    title="A regular heading"
    href="/components/images"
    textLink="Read more about images...">This is visually flat, has a link to the **images (bold)** page and only the link is a clickable target.</Card>
  <Card
    title="A regular heading"
    href="/components/images"
    textLink="Read more about images...">Short content, link bottom aligned</Card>
</Cards>

Output

A regular heading
This is visually flat, has a link to the images (bold) page and only the link is a clickable target.
Read more about images...
A regular heading
Short content, link bottom aligned
Read more about images...

Clickable with Link

Clickable cards must have a href set. If not that is an error condition in development mode

<Cards clickable>
  <Card
    title="Card with internal Link"
    href="/components/images"
    textLink="Read more about images...">This is visually eleveated, has a link to the **images (bold)** page and the complete card is a clickable target.</Card>
  <Card
    title="Card with external Link"
    href="https://commercetools.com"
    textLink="Read more about images...">This is visually eleveated, has a link to an **external (bold)** page and the
    complete card is a clickable target..</Card>
</Cards>

Output

Flat with Icon

This example assumes that the icon used here is already provided by the MDX provider anyways. But since it's MDX alternative or site-specific icons can be provided by adding an import statement in the MDX.

As discussed:

this would be the first place where authors have to learn more JSX syntax and not just the HTML-compatible subset.
Also, from an author experience perspective we need to be aware that referencing an icon that does not exist cannot be caught at runtime but will cause a compilation error.

<Cards smallTitle>
  <Card icon={<DummyIcon />} title="A smaller title">
    Example Text on a card with an icon.
  </Card>
</Cards>

Output

(no actual icon set until one is available to not break this page)

A smaller title
Example Text on a card with an icon.

Clickable (visually elevated)

Clickable cards have one card-level link target (href) and no other links in the content. They are visually elevated and elevate even more when hovered. The link target (href) can be repeated as a link at the bottom by setting a card link label.

Cards with Icons

Icons on cards that are not narrow are aligned to the top of the card regardless of whether they are clickable or flat.

<Cards>
  <Card
    title="A left aligned icon"
    icon={<DummyIcon />}
    href="/components/images"
    textLink="Read more about images...">
    The icon of this card should be left aligned.
  </Card>
  <Card
    title="A left aligned icon"
    icon={<DummyIcon />}
    href="/components/images"
    textLink="Read more about images...">
    The icon of this card should be left aligned. This has more descriptive text than the latter.
  </Card>
</Cards>

Output

A left aligned icon
The icon of this card should be left aligned.
Read more about images...
A left aligned icon
The icon of this card should be left aligned. This has more descriptive text than the latter.
Read more about images...

Icons on narrow cards are aligned to the left of the card regardless of whether they are clickable or flat.

<Cards narrow clickable>
  <Card
    title="A top aligned icon"
    href="/components/images"
    textLink="Clickable top aligned icon..."
    icon={<DummyIcon />}>
    The icon of this card should be top aligned.
  </Card>
  <Card
    title="A top aligned icon"
    href="/components/images"
    textLink="Clickable top aligned icon..."
    icon={<DummyIcon />}>
    The icon of this card should be top aligned. This has more descriptive text than the latter.
  </Card>
</Cards>

Output

Cards with Markdown in Body

Bullet List in Body of Flat Card

<Cards>
<Card title="Bullet List Body">

- Item 1
- Item 2 (dot)
  - Sub-item (circle)
- Item 3

</Card>
</Cards>

Bullet List Body
Item 1
Item 2 (dot)
Sub-item (circle)
Item 3

Link in Body of a Flat Card

<Cards>
  <Card
    title="Link in Body of Flat"
    href="/components/images"
    textLink="Click here"
    icon={<DummyIcon />}>
    This [link](/views/code-blocks) should render as a link.
  </Card>
</Cards>

Link in Body of Flat
This link should render as a link.
Click here

Link in Body of a Clickable Card

<Cards clickable>
  <Card
    title="Link in Body"
    href="/components/images"
    textLink="Click here"
    icon={<DummyIcon />}>
    This [link](/views/code-blocks) should **not** render as a link.
  </Card>
</Cards>

Link in Body
This link should not render as a link.
Click here

Cards with Images

Flat Card with an Image

<Cards>
  <Card image={<CardBannerApiIcon />}>
    Flat card with an image
  </Card>
  <Card image={<CardBannerDefaultIcon />}>
    Flat card with an image
  </Card>
  <Card image={<CardBannerMcIcon />}>
    Flat card with an image
  </Card>
  <Card image={<CardBannerOptional1Icon />}>
    Flat card with an image
  </Card>
  <Card image={<CardBannerOptional2Icon />}>
    Flat card with an image
  </Card>
  <Card image={<CardBannerOssIcon />}>
    Flat card with an image
  </Card>
</Cards>

Flat card with an image
Flat card with an image
Flat card with an image
Flat card with an image
Flat card with an image
Flat card with an image

Clickable Card with an Image

<Cards clickable>
  <Card
    title="Clickable with Image"
    href="/components/images"
    image={<CardBannerApiIcon />}>
    Clickable card with an image
  </Card>
  <Card
    title="Clickable with Image"
    href="/components/images"
    image={<CardBannerDefaultIcon />}>
    Clickable card with an image
  </Card>
  <Card
    title="Clickable with Image"
    href="/components/images"
    image={<CardBannerMcIcon />}>
    Clickable card with an image
  </Card>
  <Card
    title="Clickable with Image"
    href="/components/images"
    image={<CardBannerOptional1Icon />}>
    Clickable card with an image
  </Card>
  <Card
    title="Clickable with Image"
    href="/components/images"
    image={<CardBannerOptional2Icon />}>
    Clickable card with an image
  </Card>
  <Card
    title="Clickable with Image"
    href="/components/images"
    image={<CardBannerOssIcon />}>
    Clickable card with an image
  </Card>
</Cards>

Clickable Card with an Image and an external Link

<Cards clickable>
  <Card
    title="Clickable with Image and external link"
    href="https://commercetools.com"
    image={<CardBannerApiIcon />}>
    Clickable card with an image. The external link icon is not being rendered.
  </Card>
  <Card
    title="Clickable with Image and external link"
    href="https://commercetools.com"
    image={<CardBannerDefaultIcon />}>
    Clickable card with an image. The external link icon is not being rendered.
  </Card>
</Cards>

A Wide Card with an Image and an icon

<Cards>
  <Card image={<CardBannerApiIcon />} icon={<DummyIcon />}>
    Wide card with an image and an icon
  </Card>
  <Card image={<CardBannerDefaultIcon />} icon={<DummyIcon />}>
    Wide card with an image and an icon
  </Card>
  <Card image={<CardBannerMcIcon />} icon={<DummyIcon />}>
    Wide card with an image and an icon
  </Card>
  <Card image={<CardBannerOptional1Icon />} icon={<DummyIcon />}>
    Wide card with an image and an icon
  </Card>
  <Card image={<CardBannerOptional2Icon />} icon={<DummyIcon />}>
    Wide card with an image and an icon
  </Card>
  <Card image={<CardBannerOssIcon />} icon={<DummyIcon />}>
    Wide card with an image and an icon
  </Card>
</Cards>

Wide card with an image and an icon
Wide card with an image and an icon
Wide card with an image and an icon
Wide card with an image and an icon
Wide card with an image and an icon
Wide card with an image and an icon

A Narrow Card with an Image and an icon

<Cards narrow>
  <Card image={<CardBannerApiIcon />} icon={<DummyIcon />}>
    Narrow card with an image and an icon
  </Card>
  <Card image={<CardBannerDefaultIcon />} icon={<DummyIcon />}>
    Narrow card with an image and an icon
  </Card>
  <Card image={<CardBannerMcIcon />} icon={<DummyIcon />}>
    Narrow card with an image and an icon
  </Card>
  <Card image={<CardBannerOptional1Icon />} icon={<DummyIcon />}>
    Narrow card with an image and an icon
  </Card>
  <Card image={<CardBannerOptional2Icon />} icon={<DummyIcon />}>
    Narrow card with an image and an icon
  </Card>
  <Card image={<CardBannerOssIcon />} icon={<DummyIcon />}>
    Narrow card with an image and an icon
  </Card>
</Cards>

Narrow card with an image and an icon
Narrow card with an image and an icon
Narrow card with an image and an icon
Narrow card with an image and an icon
Narrow card with an image and an icon
Narrow card with an image and an icon

Misuse case: standalone cards

It cannot be prevented that a <Card> is used standalone and there are use cases where a plain wrapper border box is needed.

A formatted text inline in a Card

A formatted text in a single separate line in a card

A formatted text after and before extra blank lines in MDX