# Use Case Card

## Essence

Reusable preview card for one built agentic use-case.

`Use Case Card` shows proof of work: a system, workflow, or artifact that exists or is being demonstrated.

## Hook

Use when a built use-case needs to appear in a list, homepage block, or index page.

## Internal Rules

- One card represents one use-case.
- The whole card is clickable when `href` is provided.
- Must include an image or placeholder visual.
- Shows thumbnail copy, not detail-page copy: `thumbnail_title` and `thumbnail_summary` are preferred for visual previews.
- If thumbnail fields are missing, fall back to `title` and `summary`.
- Shows up to three tags outside the `gallery` variant.
- Supports a `gallery` variant for homepage portfolio tiles where the visual is dominant, text sits on top of the image, and tags/summary are hidden.
- The `gallery` variant shows a white diagonal arrow icon below the summary as the tile affordance.
- Gallery titles, summaries, and arrow affordances use `--shadow-crisp-black` so inverse text/icons stay readable over visuals.
- Gallery tiles use a tight `--space-2` action gap between summary and arrow; compact gallery tiles use `--space-1`.
- Both normal and `gallery` variants use `Surface` spacing for internal card padding/gaps; compact gallery tiles must not introduce separate local padding.
- When a real image is not supplied, the `gallery` variant uses a plain debug-color stub image, not a decorative generated/fancy placeholder.
- A use-case may provide an explicit `visual_key` for a code-native visual.
- If no `imageSrc` and no `visual_key` are supplied, the card renders `Debug Square Video Animation`, which falls back to `Debug Square Animation` when no pre-rendered asset exists.
- Do not infer visual animation from `title`, `href`, slug, or other content strings; concrete visuals must be passed as data.
- `visual_key` values map to generic video wrapper components: `Debug Square Video Animation`, `Network Path Video Animation`, `Script Scroll Video Animation`, `Modular Geometry Video Animation`, or `Gradient Grid Video Animation`.
- Every video wrapper owns the original runtime animation as its source/fallback child, so parent cards never bypass the pre-renderable layer.
- Generic animation components are documented as children of `Use Case Item`; do not name animation components after concrete projects.
- Uses `Use Case Card`, not `Article Card`, because use-cases are built systems rather than notes.

## Props

| Prop | Values | Purpose |
| --- | --- | --- |
| `title` | string | Use-case preview title. |
| `summary` | string | Use-case preview summary. |
| `href` | URL string | Destination for the clickable card. |
| `imageSrc` | URL string | Optional visual image. |
| `imageLabel` | string | Placeholder label when no image is supplied. |
| `tags` | array | Up to three user-facing tags. |
| `variant` | `card`, `gallery` | `card` is the regular preview card; `gallery` is the visual-first tile used in use-case galleries and related-use-case blocks. |

## Use When

- Showing agentic work on the homepage.
- Listing all use-cases on `/use-cases/`.
- Previewing a use-case before opening its detail page.

## Do Not Use When

- Showing notes/articles.
- Rendering the full use-case page.
- Showing generic marketing cards without a concrete built thing.

## Code Paths

- `packages/design-system/src/components/UseCaseCard.astro`
- `packages/design-system/src/components/UseCaseItem.astro`