Add Card component

[liuliu-dev]

Upstream the Card component from Pacer into @primer/react.

Issue: https://github.com/github/primer/issues/6467

Changelog

New

• Card — A styled container component with border, box-shadow, and border-radius; also supports custom content without subcomponents (plain container mode)
• Card.Icon — Renders a decorative icon in the card header (defaults to aria-hidden, supports aria-label for meaningful icons)
• Card.Image — Renders an edge-to-edge image in the card header
• Card.Heading — Renders a heading (defaults to h3, configurable via as prop)
• Card.Description — Renders a description below the heading
• Card.Menu — Slot for overlay menu (positioned absolute top-right)
• Card.Metadata — Renders metadata content below the description

Changed

• Playground Storybook story updated with boolean toggle controls for Card.Icon and Card.Metadata
• CustomContent Storybook story added to demonstrate using Card as a plain styled container with arbitrary children (no subcomponents)

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github-ui (Learn more about how to run integration tests)

[changeset-bot]

🦋 Changeset detected

Latest commit: 06edb74

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

To publish a canary release for integration testing, apply the Canary Release label to this PR.

[primer]

🤖 Lint issues have been automatically fixed and committed to this PR.

[primer]

🤖 Lint issues have been automatically fixed and committed to this PR.

[lukasoppermann]

@liuliu-dev should we tie the padding to the content-top, instead of icon bottom?

[github-actions]

Uh oh! @lukasoppermann, at least one image you shared is missing helpful alt text. Check #7723 (comment) to fix the following violations:

• Images should have meaningful alternative text (alt text) at line 3

Alt text is an invisible description that helps screen readers describe images to blind or low-vision users. If you are using markdown to display images, add your alt text inside the brackets of the markdown image.

Learn more about alt text at Basic writing and formatting syntax: images on GitHub Docs.

🤖 Beep boop! This comment was added automatically by github/accessibility-alt-text-bot.

[lukasoppermann]

This is also a use case: https://primer-1b76de82d9-13348165.drafts.github.io/storybook/?path=/story/components-card--custom-content

I am wondering if we should expect users to "bring their own padding" or if we should have a padding inside the card by default and a prop or a way to easily remove the default padding? CC: @siddharthkp ?

[github-actions]

Uh oh! @lukasoppermann, at least one image you shared is missing helpful alt text. Check #7723 (comment) to fix the following violations:

• Images should have meaningful alternative text (alt text) at line 3

Alt text is an invisible description that helps screen readers describe images to blind or low-vision users. If you are using markdown to display images, add your alt text inside the brackets of the markdown image.

Learn more about alt text at Basic writing and formatting syntax: images on GitHub Docs.

🤖 Beep boop! This comment was added automatically by github/accessibility-alt-text-bot.

[ericwbailey]

Thanks for the review @ericwbailey! Addressed:

Amazing! Thank you so much!

[liuliu-dev]

Thanks @lukasoppermann! Here's what I've updated based on your feedback:

• Updated typography and spacing to use the recommended tokens
• Padding: moved padding to the Card root and added a padding prop (normal | none), defaults to normal. Header/body no longer have their own padding, spacing between them is controlled by gap instead.
• Moved the custom content one into features stories.

[lukasoppermann]

@liuliu-dev perfect, thank you.

[siddharthkp]

I am wondering if we should expect users to "bring their own padding" or if we should have a padding inside the card by default and a prop or a way to easily remove the default padding? CC: @siddharthkp ?

I think bring your padding is a pattern we don't follow anywhere right now because it can lead to variation that is visibly inconsistent. Something we can take from PageLayout is the idea of padding: 'none' | 'condensed' | 'spacious' and of course, you can always fine-tune it with css.

[lukasoppermann]

I think bring your padding is a pattern we don't follow anywhere right now because it can lead to variation that is visibly inconsistent. Something we can take from PageLayout is the idea of padding: 'none' | 'condensed' | 'spacious' and of course, you can always fine-tune it with css.

The prop is now implemented, this makes sense to me.

@siddharthkp the Pagelayout does not make total sense to me, because there seems to be no default or normal one. Does the current implementation for card make sense to you?

you can always fine-tune it with css.

This is important! 👍

[siddharthkp]

@siddharthkp the Pagelayout does not make total sense to me, because there seems to be no default or normal one.

My bad, the values in the docs are none | condensed | normal

normal as a value is a bit weird to me. default is totally fine.

Does the current implementation for card make sense to you?

I've come into this blind, so I don't actually know what's going on or what we are trying to do 😅

I would say however, we should put this in experimental and not root index right away

[siddharthkp]

Should we export this from src/experimental/index until we build some confidence in the API with some usage?

[lukasoppermann]

Whatever you folks feel is best. Do we have a clear path for how we move this out of experimental? It feels like stuff stays in experimental for way to long some times.

[liuliu-dev]

Makes sense to keep it in experimental for now. It’s mostly upstreamed from Pacer so it’s not totally new, but the padding prop is new, if it looks good in usage we can move it out pretty quickly.

[siddharthkp]

Yep, but I would count pacer as super experimental too (and maybe deprecated).

It did not go through primer's patterns or accessibility process, so I'd like for us to be able to change our mind on the details

[siddharthkp]

^ which makes me wonder, @lukasoppermann are there any Card components as shared-components in github-ui that we should also consider as inventory?

Feels a bit strange to promote the experimental pacer component without looking at the other stable components that exist in github-ui

(Doesn't have to be blocking if we are putting this component in experimental, we can iterate over it before pushing for adoption)

[liuliu-dev]

Moved Card to @primer/react/experimental, merging now, happy to iterate in the future!

[lukasoppermann]

Figma component: https://github.com/github/primer/issues/6537

[primer-integration]

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/18126

[primer-integration]

Integration test results from github/github-ui:

  CI Passed
  VRT Passed
  Projects Passed

All checks passed!