Add new Interactive card

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>

.changeset/brown-rings-sort.md

@@ -0,0 +1,5 @@
+---
+'@backstage/ui': patch
+---
+
+Added interactive support to the `Card` component. Pass `onPress` to make the entire card surface pressable, or `href` to make it navigate to a URL. A transparent overlay handles the interaction while nested buttons and links remain independently clickable.

docs-ui/src/app/components/card/components.tsx

@@ -7,6 +7,8 @@ import {
   CardFooter,
 } from '../../../../../packages/ui/src/components/Card/Card';
 import { Text } from '../../../../../packages/ui/src/components/Text/Text';
+import { Button } from '../../../../../packages/ui/src/components/Button/Button';
+import { Flex } from '../../../../../packages/ui/src/components/Flex/Flex';
 
 export const Default = () => {
   return (
@@ -32,6 +34,70 @@ export const HeaderAndBody = () => {
   );
 };
 
+export const InteractiveButton = () => {
+  return (
+    <Card
+      style={{ width: '300px' }}
+      onPress={() => {}}
+      label="View component details"
+    >
+      <CardHeader>Interactive Card</CardHeader>
+      <CardBody>
+        Click anywhere on this card to trigger the press handler.
+      </CardBody>
+      <CardFooter>
+        <Text variant="body-small" color="secondary">
+          Click to interact
+        </Text>
+      </CardFooter>
+    </Card>
+  );
+};
+
+export const InteractiveLink = () => {
+  return (
+    <Card
+      style={{ width: '300px' }}
+      href="https://backstage.io"
+      label="Open Backstage documentation"
+    >
+      <CardHeader>Link Card</CardHeader>
+      <CardBody>This card navigates to a URL when clicked.</CardBody>
+      <CardFooter>
+        <Text variant="body-small" color="secondary">
+          Opens backstage.io
+        </Text>
+      </CardFooter>
+    </Card>
+  );
+};
+
+export const InteractiveWithNestedButtons = () => {
+  return (
+    <Card
+      style={{ width: '300px' }}
+      onPress={() => {}}
+      label="View plugin details"
+    >
+      <CardHeader>Card with Actions</CardHeader>
+      <CardBody>
+        Clicking the card background triggers the card press handler. The
+        buttons below remain independently interactive.
+      </CardBody>
+      <CardFooter>
+        <Flex gap="2">
+          <Button size="small" variant="secondary" onPress={() => {}}>
+            Primary
+          </Button>
+          <Button size="small" variant="tertiary" onPress={() => {}}>
+            Secondary
+          </Button>
+        </Flex>
+      </CardFooter>
+    </Card>
+  );
+};
+
 export const WithLongBody = () => {
   return (
     <Card style={{ width: '300px', height: '200px' }}>

docs-ui/src/app/components/card/page.mdx

@@ -12,8 +12,18 @@ import {
   defaultSnippet,
   headerAndBodySnippet,
   withLongBodySnippet,
+  interactiveButtonSnippet,
+  interactiveLinkSnippet,
+  interactiveWithNestedButtonsSnippet,
 } from './snippets';
-import { Default, HeaderAndBody, WithLongBody } from './components';
+import {
+  Default,
+  HeaderAndBody,
+  WithLongBody,
+  InteractiveButton,
+  InteractiveLink,
+  InteractiveWithNestedButtons,
+} from './components';
 import { PageTitle } from '@/components/PageTitle';
 import { Theming } from '@/components/Theming';
 import { CardDefinition } from '../../../utils/definitions';
@@ -81,6 +91,49 @@ When body content exceeds the available height, CardBody scrolls while header an
   code={withLongBodySnippet}
 />
 
+## Interactive cards
+
+Cards can be made interactive without wrapping the entire card in a button or link — which would conflict with any interactive elements inside. Instead, a transparent overlay covers the card surface, and nested buttons and links remain independently clickable above it.
+
+### Button
+
+Pass `onPress` and a `label` (used as the accessible name for screen readers) to make the whole card surface pressable.
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  layout="side-by-side"
+  preview={<InteractiveButton />}
+  code={interactiveButtonSnippet}
+/>
+
+### Link
+
+Pass `href` to make the card surface navigate to a URL. The `label` prop is optional but recommended for accessibility when the card content alone may not sufficiently describe the destination.
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  layout="side-by-side"
+  preview={<InteractiveLink />}
+  code={interactiveLinkSnippet}
+/>
+
+### With nested buttons
+
+Buttons and links inside the card remain independently interactive. Clicking them does not trigger the card's `onPress` handler.
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  layout="side-by-side"
+  preview={<InteractiveWithNestedButtons />}
+  code={interactiveWithNestedButtonsSnippet}
+/>
+
 <Theming definition={CardDefinition} />
 
 <ChangelogComponent component="card" />

docs-ui/src/app/components/card/props-definition.ts

@@ -15,6 +15,25 @@ const optionalChildrenPropDef: Record<string, PropDef> = {
 
 export const cardPropDefs: Record<string, PropDef> = {
   ...optionalChildrenPropDef,
+  onPress: {
+    type: 'enum',
+    values: ['() => void'],
+    responsive: false,
+    description:
+      'Handler called when the card is pressed. Makes the card interactive as a button. Requires label.',
+  },
+  href: {
+    type: 'string',
+    responsive: false,
+    description:
+      'URL to navigate to. Makes the card interactive as a link. Mutually exclusive with onPress.',
+  },
+  label: {
+    type: 'string',
+    responsive: false,
+    description:
+      'Accessible label announced by screen readers for the interactive overlay. Required when onPress is provided.',
+  },
   ...classNamePropDefs,
   ...stylePropDefs,
 };

docs-ui/src/app/components/card/snippets.ts

@@ -17,6 +17,50 @@ export const headerAndBodySnippet = `<Card style={{ width: '300px', height: '200
   <CardBody>Body content without a footer</CardBody>
 </Card>`;
 
+export const interactiveButtonSnippet = `<Card
+  style={{ width: '300px' }}
+  onPress={() => console.log('Card pressed')}
+  label="View component details"
+>
+  <CardHeader>Interactive Card</CardHeader>
+  <CardBody>Click anywhere on this card to trigger the press handler.</CardBody>
+  <CardFooter>Click to interact</CardFooter>
+</Card>`;
+
+export const interactiveLinkSnippet = `<Card
+  style={{ width: '300px' }}
+  href="https://backstage.io"
+  label="Open Backstage documentation"
+>
+  <CardHeader>Link Card</CardHeader>
+  <CardBody>This card navigates to a URL when clicked.</CardBody>
+  <CardFooter>Opens backstage.io</CardFooter>
+</Card>`;
+
+export const interactiveWithNestedButtonsSnippet = `import { Button, Flex } from '@backstage/ui';
+
+<Card
+  style={{ width: '300px' }}
+  onPress={() => console.log('Card pressed')}
+  label="View plugin details"
+>
+  <CardHeader>Card with Actions</CardHeader>
+  <CardBody>
+    Clicking the card background triggers the card press handler.
+    The buttons below remain independently interactive.
+  </CardBody>
+  <CardFooter>
+    <Flex gap="2">
+      <Button size="small" variant="secondary" onPress={() => console.log('Primary')}>
+        Primary
+      </Button>
+      <Button size="small" variant="tertiary" onPress={() => console.log('Secondary')}>
+        Secondary
+      </Button>
+    </Flex>
+  </CardFooter>
+</Card>`;
+
 export const withLongBodySnippet = `import { Text } from '@backstage/ui';
 
 <Card style={{ width: '300px', height: '200px' }}>

packages/ui/report.api.md

@@ -565,6 +565,12 @@ export const Card: ForwardRefExoticComponent<
   CardProps & RefAttributes<HTMLDivElement>
 >;
 
+// @public (undocumented)
+export type CardBaseProps = {
+  children?: ReactNode;
+  className?: string;
+};
+
 // @public
 export const CardBody: ForwardRefExoticComponent<
   CardBodyProps & RefAttributes<HTMLDivElement>
@@ -595,6 +601,13 @@ export interface CardBodyProps
   extends CardBodyOwnProps,
     React.HTMLAttributes<HTMLDivElement> {}
 
+// @public (undocumented)
+export type CardButtonVariant = {
+  onPress: () => void;
+  href?: never;
+  label: string;
+};
+
 // @public
 export const CardDefinition: {
   readonly styles: {
@@ -602,10 +615,14 @@ export const CardDefinition: {
   };
   readonly classNames: {
     readonly root: 'bui-Card';
+    readonly overlay: 'bui-CardOverlay';
   };
   readonly propDefs: {
     readonly children: {};
     readonly className: {};
+    readonly onPress: {};
+    readonly href: {};
+    readonly label: {};
   };
 };
 
@@ -670,15 +687,32 @@ export interface CardHeaderProps
     React.HTMLAttributes<HTMLDivElement> {}
 
 // @public (undocumented)
-export type CardOwnProps = {
-  children?: ReactNode;
-  className?: string;
+export type CardLinkVariant = {
+  href: string;
+  onPress?: never;
+  label?: string;
 };
 
 // @public
-export interface CardProps
-  extends CardOwnProps,
-    React.HTMLAttributes<HTMLDivElement> {}
+export type CardOwnProps = {
+  children?: ReactNode;
+  className?: string;
+  onPress?: () => void;
+  href?: string;
+  label?: string;
+};
+
+// @public
+export type CardProps = CardBaseProps &
+  Omit<React.HTMLAttributes<HTMLDivElement>, 'onPress'> &
+  (CardButtonVariant | CardLinkVariant | CardStaticVariant);
+
+// @public (undocumented)
+export type CardStaticVariant = {
+  onPress?: never;
+  href?: never;
+  label?: never;
+};
 
 // @public (undocumented)
 export const Cell: {

packages/ui/src/components/Card/Card.module.css

@@ -27,6 +27,48 @@
     overflow: hidden;
     min-height: 0;
     width: 100%;
+    position: relative;
+  }
+
+  .bui-CardOverlay {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+    background: transparent;
+    cursor: pointer;
+    border-radius: inherit;
+    border: none;
+    padding: 0;
+    appearance: none;
+    display: block;
+    width: 100%;
+
+    &:focus-visible {
+      outline: 2px solid var(--bui-ring);
+      outline-offset: -2px;
+    }
+
+    &:hover::after,
+    &[data-focused]::after {
+      content: '';
+      position: absolute;
+      inset: 0;
+      background: color-mix(in srgb, currentColor 5%, transparent);
+      border-radius: inherit;
+      pointer-events: none;
+    }
+  }
+
+  /*
+   * Interactive elements inside the card must sit above the overlay so they
+   * remain independently clickable. The overlay handles the rest of the surface.
+   */
+  .bui-Card[data-interactive]
+    :is(button, a[href], [role='button'], [role='link'], input, select, textarea):not(
+      .bui-CardOverlay
+    ) {
+    position: relative;
+    z-index: 2;
   }
 
   .bui-CardBody {

packages/ui/src/components/Card/Card.stories.tsx

@@ -231,6 +231,94 @@ export const BgOnProviders = meta.story({
   ),
 });
 
+export const Interactive = meta.story({
+  render: () => (
+    <Card
+      style={{ width: '300px' }}
+      onPress={() => alert('Card pressed')}
+      label="View component details"
+    >
+      <CardHeader>
+        <Text weight="bold">Interactive Card</Text>
+      </CardHeader>
+      <CardBody>
+        <Text>
+          Click anywhere on this card to trigger the press handler. The entire
+          card surface is interactive.
+        </Text>
+      </CardBody>
+      <CardFooter>
+        <Text variant="body-small" color="secondary">
+          Click to interact
+        </Text>
+      </CardFooter>
+    </Card>
+  ),
+});
+
+export const InteractiveAsLink = meta.story({
+  render: () => (
+    <Card
+      style={{ width: '300px' }}
+      href="https://backstage.io"
+      label="Open Backstage documentation"
+    >
+      <CardHeader>
+        <Text weight="bold">Link Card</Text>
+      </CardHeader>
+      <CardBody>
+        <Text>
+          This card navigates to a URL when clicked. The entire card surface
+          acts as a link.
+        </Text>
+      </CardBody>
+      <CardFooter>
+        <Text variant="body-small" color="secondary">
+          Opens backstage.io
+        </Text>
+      </CardFooter>
+    </Card>
+  ),
+});
+
+export const InteractiveWithNestedButtons = meta.story({
+  render: () => (
+    <Card
+      style={{ width: '300px' }}
+      onPress={() => alert('Card pressed')}
+      label="View plugin details"
+    >
+      <CardHeader>
+        <Text weight="bold">Card with Actions</Text>
+      </CardHeader>
+      <CardBody>
+        <Text>
+          Clicking the card background triggers the card press handler. The
+          buttons below remain independently interactive.
+        </Text>
+      </CardBody>
+      <CardFooter>
+        <Flex gap="2">
+          <Button
+            size="small"
+            variant="secondary"
+            onPress={() => alert('Primary action')}
+          >
+            Primary
+          </Button>
+          <Button
+            size="small"
+            variant="tertiary"
+            onPress={() => alert('Secondary action')}
+          >
+            Secondary
+          </Button>
+        </Flex>
+      </CardFooter>
+    </Card>
+  ),
+});
+
 export const CustomCardWithBox = meta.story({
   render: () => (
     <Flex direction="column" gap="4">

packages/ui/src/components/Card/Card.tsx

@@ -15,6 +15,7 @@
  */
 
 import { forwardRef } from 'react';
+import { Button as RAButton, Link as RALink } from 'react-aria-components';
 import { useDefinition } from '../../hooks/useDefinition';
 import {
   CardDefinition,
@@ -23,6 +24,7 @@ import {
   CardFooterDefinition,
 } from './definition';
 import type {
+  CardOwnProps,
   CardProps,
   CardHeaderProps,
   CardBodyProps,
@@ -38,18 +40,31 @@ import { Box } from '../Box/Box';
 export const Card = forwardRef<HTMLDivElement, CardProps>((props, ref) => {
   const { ownProps, restProps, dataAttributes } = useDefinition(
     CardDefinition,
-    props,
+    props as CardOwnProps &
+      Omit<React.HTMLAttributes<HTMLDivElement>, 'onPress'>,
   );
-  const { classes, children } = ownProps;
+  const { classes, children, onPress, href, label } = ownProps;
+  const isInteractive = !!(onPress || href);
 
   return (
     <Box
       bg="neutral"
       ref={ref}
       className={classes.root}
+      data-interactive={isInteractive || undefined}
       {...dataAttributes}
       {...restProps}
     >
+      {href && (
+        <RALink className={classes.overlay} href={href} aria-label={label} />
+      )}
+      {onPress && !href && (
+        <RAButton
+          className={classes.overlay}
+          onPress={onPress}
+          aria-label={label}
+        />
+      )}
       {children}
     </Box>
   );

packages/ui/src/components/Card/definition.ts

@@ -31,10 +31,14 @@ export const CardDefinition = defineComponent<CardOwnProps>()({
   styles,
   classNames: {
     root: 'bui-Card',
+    overlay: 'bui-CardOverlay',
   },
   propDefs: {
     children: {},
     className: {},
+    onPress: {},
+    href: {},
+    label: {},
   },
 });
 

packages/ui/src/components/Card/types.ts

@@ -16,10 +16,44 @@
 
 import type { ReactNode } from 'react';
 
-/** @public */
+/**
+ * Flat own-props shape used by the component definition system.
+ * @public
+ */
 export type CardOwnProps = {
   children?: ReactNode;
   className?: string;
+  onPress?: () => void;
+  href?: string;
+  label?: string;
+};
+
+/** @public */
+export type CardBaseProps = { children?: ReactNode; className?: string };
+
+/** @public */
+export type CardButtonVariant = {
+  /** Handler called when the card is pressed. Makes the card interactive as a button. */
+  onPress: () => void;
+  href?: never;
+  /** Accessible label announced by screen readers for the interactive card. */
+  label: string;
+};
+
+/** @public */
+export type CardLinkVariant = {
+  /** URL to navigate to. Makes the card interactive as a link. */
+  href: string;
+  onPress?: never;
+  /** Accessible label announced by screen readers for the interactive card. */
+  label?: string;
+};
+
+/** @public */
+export type CardStaticVariant = {
+  onPress?: never;
+  href?: never;
+  label?: never;
 };
 
 /**
@@ -27,9 +61,9 @@ export type CardOwnProps = {
  *
  * @public
  */
-export interface CardProps
-  extends CardOwnProps,
-    React.HTMLAttributes<HTMLDivElement> {}
+export type CardProps = CardBaseProps &
+  Omit<React.HTMLAttributes<HTMLDivElement>, 'onPress'> &
+  (CardButtonVariant | CardLinkVariant | CardStaticVariant);
 
 /** @public */
 export type CardHeaderOwnProps = {