---
id: portfolio.ds.project-hero-item
name: "Project Hero Item"
type: subcomponent
status: active
relations: [{"type":"composes","target":"portfolio.ds.heading"},{"type":"composes","target":"portfolio.ds.paragraph"},{"type":"composes","target":"portfolio.ds.site-logo"},{"type":"related_to","target":"portfolio.ds.extra-small-corner-radius"},{"type":"related_to","target":"portfolio.ds.focus-interaction-states"},{"type":"related_to","target":"portfolio.ds.project-hero-carousel"},{"type":"related_to","target":"portfolio.ds.spacing"}]
sources: ["apps/portfolio-site/src/design-system/docs/project-hero-item.astro","apps/portfolio-site/src/lib/designSystemRegistry.ts","packages/design-system/src/components/ProjectHeroItem.astro","packages/design-system/src/components/ProjectVisual.astro","packages/design-system/src/components/generated/SiteLogoMark.astro"]
catalog: ["apps/portfolio-site/src/design-system/docs/project-hero-item.astro"]
previews: ["apps/portfolio-site/src/design-system/docs/project-hero-item.astro"]
---
# Project Hero Item

## Purpose

Independent project presentation for `Project Hero Carousel`.

The component is developed in parallel with the current production composition. It does not import, wrap, extend, or reference `Project Item` or the hidden card implementation.

## Contract

- Belongs directly under `Project Hero Carousel`.
- Renders one whole-item link with project title, short description, destination, and visual key.
- Composes the shared `Project Visual` media primitive without depending on the old project-item path.
- Supports a parent-owned `runtimeFallback` policy: standalone Item previews keep the realtime visual fallback, while Project Hero Carousel disables its repeated inline fallback and relies on the lightweight project placeholder.
- Project Visual supplies a lightweight WebP first-frame placeholder beneath pre-rendered video. The placeholder is visible immediately and remains until playback actually starts, so Item never exposes its debug surface as a loading state.
- Uses a full-bleed image or animation as the bottom layer.
- Uses an opaque solid panel above the media for title and description.
- Rounds the solid copy panel with Extra Small Corner Radius (`--radius-xs`, `4px`).
- Sizes the solid copy panel with `width: fit-content`: its natural maximum follows the copy, while its hard maximum is the Hero Item width minus the standard left and right surface insets.
- Keeps the complete description and limits its measure to `max-width: 30ch`; when the available panel width is narrower than that measure, the panel contracts to the available width and copy wraps instead of overflowing or being truncated. No fixed desktop minimum width is imposed.
- Appends the canonical animated Site Logo inline at the end of the description. The mark is `0.8em` square relative to the description font size and inherits inverse text color so it renders white directly on the black copy panel.
- Reuses the shared synchronized cursor animation and reduced-motion behavior from Site Logo instead of duplicating logo geometry or motion.
- Uses regular weight for both copy levels: the project title uses the body-size token and the description uses the larger H3-size token.
- Has a fixed default height of `36rem` (`576px`).
- Has a maximum width of `64rem` (`1024px`), producing a `16:9` box at maximum size.
- Uses `width: 100%`; when the parent is narrower than `64rem`, only the width contracts and the fixed height remains unchanged.
- At the existing Mobile breakpoint (`≤640px`), replaces the overlay geometry with a stacked layout: full-width media first, then left-aligned title and description.
- Mobile media is forced to `aspect-ratio: 4 / 3` and `width: 100%`; the desktop fixed height does not carry into Mobile.
- Mobile copy uses the page surface without the black solid panel, and the inline Site Logo inherits normal text color.
- Mobile title and description have zero horizontal padding. The space below the description equals the `--space-4` gap between media and title, creating symmetric vertical breathing room around the copy block.
- The current-project label shown above media in the carousel reference belongs to future carousel navigation and is not rendered by Project Hero Item.
- Supports the canonical State Preview set: `normal`, `hover`, `focus`, `focus-visible`, `pressed`, `selected`, and `disabled`.
- Hover lift plus media-only Pressed and Selected dimming are explicit, component-specific expressive behaviors of `Project Hero Item`. They do not redefine shared interaction tokens, generic card behavior, or the interaction contract of any other component.
- Pressed and Selected apply their shared Alt interaction overlays only to the media/animation layer; the opaque copy panel remains unchanged.
- Hover does not add an overlay or darken the media. At Tablet and wider layouts, its only visual treatment is an expressive lift of the opaque copy panel by `--space-2` (`8px`) over `200ms ease-out`; the media and outer Hero Item remain stationary.
- Mobile is an explicit Hover exception: because its copy is not rendered as an opaque card, Hover has no visual treatment at all—no lift and no dimming. Focus, focus-visible, pressed, selected, and disabled remain available on Mobile. Reduced-motion mode removes the desktop/tablet hover transition and transform.
- Focus and focus-visible use the extra-contrast rings required by a filled visual surface.
- Disabled uses shared disabled opacity, removes the destination, and prevents pointer and keyboard activation while preserving readable content.
- The Design System State Preview mirrors the real disabled contract by removing its demonstration destination and tab stop when `disabled` is selected, then restoring them for other states.
- Uses Design System color, spacing, radius, typography, and interaction tokens.
- Does not switch the production Homepage or current `Project Hero` to this component.

## Use

- Building and reviewing the Project Hero Carousel item presentation in isolation.
- Composing the future looping project carousel after the item contract is accepted.

## Do Not Use

- Do not replace the current production `Project Hero` without explicit owner approval.
- Do not use as a generic project card or inside Related Projects.
- Do not introduce imports or CSS/DOM coupling to `Project Item` or the hidden card implementation.
- Do not reuse the component-specific Hover lift or media-only Pressed and Selected treatments as a generic card interaction pattern without a separate Design System decision.

## Props

| Prop | Values | Purpose |
| --- | --- | --- |
| `project` | `{ title, summary, href, visualKey }` | Supplies abstract project copy, destination, and animation selection. |
| `target` | anchor target | Controls destination browsing context. |
| `rel` | anchor relationship | Supplies explicit link relationship metadata. |
| `disabled` | boolean | Removes the destination and interaction while preserving readable content. |
| `runtimeFallback` | boolean | Keeps the realtime Project Visual fallback by default; the parent carousel disables it to avoid repeating dormant SVG trees. |

## Accessibility

- The whole item is one keyboard-focusable link.
- Focus and focus-visible states use shared interaction tokens.
- Decorative animation is hidden from assistive technology; title and summary remain readable link content.
- `_blank` targets receive `noreferrer` when no explicit relationship is supplied.

## Verification

- Confirm the maximum box is `1024 × 576` and therefore `16:9`.
- Confirm narrower previews reduce width while preserving the `576px` height.
- Confirm the Mobile preview instead renders full-width `4:3` media followed by left-aligned title and complete description, with no overlay or horizontal overflow.
- Confirm Mobile title and description align directly to the media edge with zero horizontal padding, and that the space below description equals the space between media and title.
- Confirm animation stays beneath the solid copy panel.
- Confirm long descriptions remain complete and wrap within the `30ch` maximum measure without truncation.
- Confirm the solid copy panel shrinks below its natural text width when the Hero Item is constrained, and that its text reflows inside the panel without horizontal overflow.
- Confirm the white inline Site Logo follows the final description text at `0.8em`, stays visible without a backing tile, blinks through the shared cursor timeline, and remains static under reduced motion.
- Confirm every State switcher value produces the documented interaction treatment without changing item dimensions.
- Confirm Hover lifts only the desktop/tablet solid copy panel by `8px` over `200ms`, while Mobile Hover produces no visual change and reduced-motion previews do not move it.
- Confirm Pressed and Selected darken only the media/animation and leave the solid copy panel visually unchanged.
- Confirm no source imports or references `Project Item` or the hidden card implementation.
- Confirm current `Project Hero`, Homepage, Related Projects, and `Project Item` remain unchanged.
- Run `scripts/design-system-graph --check --no-write`.