# EnhancedProjectCard

> Portfolio project card with image or video media and metadata; video is a paused preview unless autoPlayVideo loops it while on screen.

- Status: stable
- Group: marketing
- Page: https://www.digitaltableteur.com/design-system/components/enhanced-project-card
- Contract: https://www.digitaltableteur.com/contracts/v1/EnhancedProjectCard.contract.json

## When to use

Work-index project card with image or video preview and metadata. Video stays paused unless autoPlayVideo is set; then it loops muted while on screen and never for visitors who prefer reduced motion. The richer sibling of ProjectCard; use one per index, not both.

## When not to use

- Do not render both EnhancedProjectCard and ProjectCard in the same index; pick one per grid.
- Do not rely on the thumbnail to carry meaning; it always renders with an empty alt, so the title and description must say what the project is.

## Look-alikes

The contract names no look-alike with a deciding condition.

## Props

| Prop | Type | Default | Description | Required |
| --- | --- | --- | --- | --- |
| `title` | `string` | none | Project title. | Yes |
| `slug` | `string` | none | URL slug for project detail page. | Yes |
| `thumbnail` | `string` | none | Thumbnail image URL. | Yes |
| `videoThumbnail` | `string \| string[]` | none | Video thumbnail: one URL, or several in preference order (for example WebM then MP4). `thumbnail` is its poster. Paused unless `autoPlayVideo`. | No |
| `description` | `string` | none | Short description. | No |
| `category` | `string` | none | Project category. | No |
| `tags` | `string[]` | none | Project tags; only the first three render. | No |
| `aspectRatio` | `"video" \| "square" \| "portrait" \| "landscape"` | `video` | Image aspect ratio. | No |
| `showCategory` | `boolean` | `true` | Show category in caption. Defaults to true. | No |
| `showDescription` | `boolean` | `true` | Show description on hover. Defaults to true; when false the description is screen-reader-only and becomes the link's accessible description. | No |
| `autoPlayVideo` | `boolean` | `false` | Loop the video like a GIF: muted, inline, playing only while on screen, and never for visitors who prefer reduced motion (they see the poster). Keep such clips short. | No |
| `comingSoon` | `boolean` | `false` | Render as a non-interactive teaser with a "coming soon" badge over the media. | No |
| `comingSoonLabel` | `string` | none | Visible badge label for the coming-soon overlay. Defaults to the translated "Coming soon" (`workComingSoon`). | No |
| `contentLanguage` | `string` | none | BCP 47 language tag for project-authored title and metadata. | No |
| `coverGlow` | `boolean` | `false` | Glow the cover in its own colours on hover. Off by default; the work index opts in, other surfaces (home, related work) stay quiet. Default false. | No |
| `priority` | `boolean` | `false` | Load the image thumbnail eagerly and preload it (next/image `priority`). Set it only on cards in the first visible row, where the cover is the page's largest paint; everywhere else the default lazy load is right. Default false. | No |
| `className` | `string` | none | Custom className. | No |

## Variants

- Available aspect ratios: `video`, `square`, `portrait`, `landscape` (default `video`).

## Invalid combinations

The contract records no invalid combinations.

## Keyboard

| Key | Behaviour |
| --- | --- |
| General | Unless comingSoon is set, the whole card is a single link (`<a>` via next/link); Tab focuses it, Enter activates it. With comingSoon the root is a non-interactive `<div>` and takes no focus. |
| General | Hover-only metadata affordances also fire on `:focus-visible` so keyboard users get parity. |

## Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

| Level | Rule | How it is checked |
| --- | --- | --- |
| MUST | ARIA: Root is a stretched `<a>` named through aria-labelledby by its visible text in visual order: category (when shown), title, the description when showDescription is true, then tags. When showDescription is false the description is screen-reader-only and becomes the aria-describedby description instead. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | ARIA: The thumbnail image `alt` is empty and the `<video>` is `aria-hidden` because the adjacent project copy provides the equivalent. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | ARIA: Project-authored copy can carry an explicit BCP 47 language without overriding localized status text. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | Required stories produce no axe violations at the configured severity. | Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8. |
| MUST | The accessibility tree (role, name, state) matches the committed snapshot for every required story. | Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2. |
| MUST | The component remains legible and operable under a real browser forced-colors: active pass. | Automated by `npm run test:stories:hc`. |
| MUST | Every documented keyboard interaction works as specified. | Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2. |
| MUST | A human completed an end-to-end accessibility review of this component. | Manual review, last on 2026-11-04. |

## Install and import

- In-repo only. EnhancedProjectCard is not exported from `@digitaltableteur/react`, so there is no public import path.

## Links

- Machine-readable contract (Design System Contract 1.0): https://www.digitaltableteur.com/contracts/v1/EnhancedProjectCard.contract.json
- Markdown version of this page: https://www.digitaltableteur.com/design-system/components/enhanced-project-card.md
- Component index as JSON: https://www.digitaltableteur.com/design-system/components.json
- All components: https://www.digitaltableteur.com/design-system/components
- Source: The implementation lives in a private repository. This page, its Markdown twin and the contract are generated from it at build time and are the public source of truth.