---
id: portfolio.ds.project-header
name: "Project Header"
type: pattern
status: active
relations: [{"type":"composes","target":"portfolio.ds.debug-square-video-animation"},{"type":"composes","target":"portfolio.ds.heading"},{"type":"composes","target":"portfolio.ds.network-path-video-animation"},{"type":"composes","target":"portfolio.ds.scaffolding-video-animation"}]
sources: ["apps/portfolio-site/src/design-system/docs/project-header.astro","apps/portfolio-site/src/lib/designSystemRegistry.ts","packages/design-system/src/components/ProjectHeader.astro","packages/design-system/src/components/ProjectVisual.astro"]
catalog: ["apps/portfolio-site/src/design-system/docs/project-header.astro"]
previews: ["apps/portfolio-site/src/design-system/docs/project-header.astro"]
---
# Project Header

## Purpose
Full-screen opening block for a single project page.

`Project Header` introduces one project with a name, short one-sentence description, related background animation, and a bouncing down arrow.

## Hook

Use as the opening block of the current single-project landing page.

## Contract

- Project media must remain inside the Header background stacking context so the accepted black readability gradient always renders above video, placeholder, and runtime fallback layers and below Header content.
- Height is one screen: `100svh`.
- Uses `Block` spacing for internal padding.
- Aligns content to the left.
- Does not render version or last-updated metadata; `Project About` owns those facts below the hero.
- Uses `Heading` and `Paragraph` as text components.
- Has an owner-approved display-size exception for the hero title: `8rem` default, `4.5rem` tablet, `3rem` mobile.
- Has an owner-approved description-size exception: `h3` default, `h4` tablet, and `body` on mobile.
- Mirrors those responsive exceptions in Design System preview through `component-preview[data-breakpoint]`; do not rely only on viewport media queries.
- Lets the title span a wider horizontal line than article-style reading text.
- Adds `--space-8` between the title and description so the summary does not stick to the large heading; mobile uses `--space-6`.
- Uses `Project Visual` as the single background selector and `Debug Square Video Animation` as its default.
- Accepts only the active related visual keys; unknown or deprecated visual keys fall back to debug.
- Renders the background animation as a child component, not as a local copy.
- Uses the same dark gradient overlay and inverse white text treatment as `Project Item`.
- Renders a white bouncing down arrow.
- Does not render tags, eyebrow text, body text, related projects, or page template chrome.
- Is used by `Project Landing Page`.
- Reuses the canonical public `title` and `summary`; it does not accept alternate hero copy.

## Props

| Prop | Values | Purpose |
| --- | --- | --- |
| `title` | string | Project name. |
| `description` | string | One-sentence short description. |
| `visualKey` | `debug-square`, `network-path`, `lifegraph`, `scaffolding` | Optional related animation key; defaults to debug. |

## Code Paths

- `packages/design-system/src/components/ProjectHeader.astro`
- `packages/design-system/src/components/ProjectVisual.astro`
- `apps/portfolio-site/src/design-system/docs/project-header.astro`

## Use

Use when this named Design System contract is required by an approved composition or product surface.

## Do Not Use

Do not use outside the documented source, composition, or ownership contract without Design System Architect review.

## Accessibility

Preserve applicable accessibility behavior of the implementation and verify changes in actual usage.

## Verification

- Confirm every source path in frontmatter resolves to current implementation or documentation.
- Run `scripts/design-system-graph --check --no-write`.
- Verify actual usage and documented Preview against the enabled package profiles before completion.