---
id: portfolio.ds.project-item
name: "Project Item"
type: component
status: active
relations: [{"type":"composes","target":"portfolio.ds.debug-square-video-animation"},{"type":"composes","target":"portfolio.ds.network-path-video-animation"},{"type":"composes","target":"portfolio.ds.project-card"},{"type":"composes","target":"portfolio.ds.scaffolding-video-animation"},{"type":"related_to","target":"portfolio.ds.debug-square-animation"},{"type":"related_to","target":"portfolio.ds.debug-square-video-animation"},{"type":"related_to","target":"portfolio.ds.home-page"},{"type":"related_to","target":"portfolio.ds.network-path-animation"},{"type":"related_to","target":"portfolio.ds.network-path-video-animation"},{"type":"related_to","target":"portfolio.ds.project-card"},{"type":"related_to","target":"portfolio.ds.project-hero"},{"type":"related_to","target":"portfolio.ds.related-projects-content"},{"type":"related_to","target":"portfolio.ds.scaffolding-animation"},{"type":"related_to","target":"portfolio.ds.scaffolding-video-animation"}]
sources: ["apps/portfolio-site/src/design-system/docs/project-item.astro","apps/portfolio-site/src/lib/designSystemRegistry.ts","apps/portfolio-site/src/pages/design-system/index.astro","packages/design-system/src/components/DebugSquareAnimation.astro","packages/design-system/src/components/DebugSquareVideoAnimation.astro","packages/design-system/src/components/NetworkPathAnimation.astro","packages/design-system/src/components/NetworkPathVideoAnimation.astro","packages/design-system/src/components/ProjectHero.astro","packages/design-system/src/components/ProjectItem.astro","packages/design-system/src/components/ProjectVisual.astro","packages/design-system/src/components/ScaffoldingAnimation.astro","packages/design-system/src/components/ScaffoldingVideoAnimation.astro"]
catalog: ["apps/portfolio-site/src/design-system/docs/project-item.astro"]
previews: ["apps/portfolio-site/src/design-system/docs/project-item.astro"]
---
# Project Item

## Purpose
Reusable visual tile component for project blocks.

`Project Item` renders exactly one project tile and exposes the two visual states used by project block compositions: `big` and `small`. It also selects one active visual animation; the default goes through `Debug Square Video Animation`, which falls back to `Debug Square Animation`.

## Hook

Use inside project blocks when one project needs to appear as a visual tile.

## Contract
- Belongs under Components as the reusable visual project tile.
- Renders one project only.
- Supports `state="big"` and `state="small"`.
- Supports `animation`, with `debug-square` as the default plus `network-path` and `scaffolding` as active options.
- Preserves `project.visualKey` when real content supplies it.
- Uses default `animation` when the project has no explicit visual metadata.
- Must not infer animation from title, href, slug, or other content strings; missing, unknown, or deprecated visual metadata means `Debug Square Animation`.
- The component preview exposes `state` only and renders the default animation; do not preview this component as a matrix of internal animation variants.
- `big` is used for the latest updated featured project.
- `small` is used for compact related or secondary projects.
- Uses `Project Card` internally with the `gallery` variant.
- Inherits the gallery tile affordance from `Project Card`: a white diagonal arrow below the summary.
- Inherits `--shadow-crisp-black` on gallery title, summary, and arrow from `Project Card`.
- Owns the visual-animation child family used by gallery project tiles.
- Animation children use generic component names, not project or project names.
- Owns the rounded tile shape and clips the internal card to that radius.
- Does not define its own width or height; it fills the grid cell assigned by `Project Hero`.
- Standalone Design System preview must provide a parent preview cell with explicit height; do not add intrinsic height back into `Project Item` to fix preview visibility.
- Project parent blocks must consume this component instead of passing projects directly into `Project Card`.
- Parent components must consume `Project Item` through documented public props only; they must not override its internal animation, card styling, spacing, or visual child selection.
- Does not own the surrounding grid, section order, or homepage placement.

## Use
- Building or reviewing `Project Hero`.
- Building or reviewing `Related Projects`.
- A single project tile needs to switch between featured and compact presentation.

## Do Not Use
- Rendering regular non-visual project cards; use `Project Card`.
- Rendering the full projects index page; use `Projects Index Page`.
- Rendering a single project detail page; use `Project Landing Page`.

## Props

| Prop | Values | Purpose |
| --- | --- | --- |
| `project` | object | Project card data passed to `Project Card`. |
| `state` | `big`, `small` | Selects featured-tile or lower-row tile presentation. |
| `animation` | `debug-square`, `network-path`, `scaffolding` | Selects the visual animation when `project.visualKey` is not set. |

## Related Components And Patterns

- `Project Hero`: approved parent block.
- `Related Projects Content`: approved parent block.
- `Project Card`: internal gallery card renderer.
- `Project Visual`: shared visual-key selector used by cards and headers.
- `Debug Square Video Animation`: default pre-renderable shell; owns `Debug Square Animation` as its source/fallback child.
- `Network Path Video Animation`: pre-renderable shell; owns `Network Path Animation` as its source/fallback child.
- `Scaffolding Video Animation`: pre-rendered wrapper that owns the realtime `Scaffolding Animation` source/fallback child.
- `Home Page`: page composition that uses `Project Hero`.

## Code Paths

- `packages/design-system/src/components/ProjectItem.astro`
- `packages/design-system/src/components/ProjectVisual.astro`
- `packages/design-system/src/components/DebugSquareVideoAnimation.astro`
- `packages/design-system/src/components/DebugSquareAnimation.astro`
- `packages/design-system/src/components/NetworkPathVideoAnimation.astro`
- `packages/design-system/src/components/NetworkPathAnimation.astro`
- `packages/design-system/src/components/ScaffoldingAnimation.astro`
- `packages/design-system/src/components/ScaffoldingVideoAnimation.astro`
- `packages/design-system/src/components/ProjectHero.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`

## 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.