---
id: portfolio.ds.package-hero
name: "Package Hero"
type: component
status: active
relations: [{"type":"related_to","target":"portfolio.ds.package-item"}]
sources: ["apps/portfolio-site/src/design-system/docs/package-hero.astro","apps/portfolio-site/src/lib/designSystemRegistry.ts","packages/design-system/src/components/PackageHero.astro"]
catalog: ["apps/portfolio-site/src/design-system/docs/package-hero.astro"]
previews: ["apps/portfolio-site/src/design-system/docs/package-hero.astro"]
---
# Package Hero

## Purpose
Reusable titled composition for an ordered collection of accountable-software packages or systems.

`Package Hero` turns accepted `Package Item` records into one coherent Homepage-ready section while keeping each item's content and reveal behavior encapsulated.

## Hook

Use when a page needs one heading followed by a meaningful ordered group of `Package Item` records.

## Use
- Presenting a page-level group of reusable systems.
- Preserving editorial item order across every supported breakpoint.

## Contract
- Belongs under Blocks.
- Owns `Package Item` as its Design System child.
- Accepts `heading`, `headingVisible`, `headingLevel`, `items` and `id`, plus native section attributes.
- Each item contains a stable `id`, `title` and `description`; array order is presentation order.
- Renders the group as a labelled semantic `section` containing an ordered list.
- Passes item title, description, derived heading level and one-based index to `Package Item` without duplicating its markup or motion.
- Owns outer block spacing and the gap after its heading; each `Package Item` owns its own leading divider.
- Reserves a stable outer box with a `128px` top motion range and moves one internal layer containing both the heading and ordered list.
- Maps the section top edge's one-viewport entry phase to a bounded `0` to `-128px` vertical translation using the established Project Hero Carousel easing treatment; the completed offset then holds through the remaining long list.
- Coalesces transform updates through animation frames; Reduced Motion keeps the internal layer at `0px`.
- Fades each Package Item independently from 20–60% of that item's own upward exit using the shared smoothstep curve; the parent batches all item updates inside its existing motion frame.
- Keeps the semantic group heading at its requested rank while presenting it with the next smaller H3 visual typography step.
- Can visually hide the group heading without removing its accessible section name or leaving layout space; the Homepage uses this treatment.
- Fills the parent width and grows to its content height.
- Renders no section for an empty or invalid item collection.
- Does not own production localization, Homepage placement or future package destinations.
- Design System Preview uses six abstract records to exercise the owner-approved item count without publishing production claims.

## Props

| Prop | Values | Purpose |
| --- | --- | --- |
| `heading` | string | Visible group heading. |
| `headingVisible` | boolean | Keeps the semantic heading accessible while optionally removing it from visual flow. |
| `headingLevel` | `1`, `2`, `3`, `4` | Semantic rank of the group heading; item headings use the next available rank. |
| `items` | ordered `{ id, title, description }[]` | Package records rendered in source order. |
| `id` | string | Section id and prefix for its accessible heading relationship. |

## Do Not Use
- Do not use it for Projects, articles or unordered card galleries.
- Do not duplicate `Package Item` internals in the parent.
- Do not attach package links before canonical package destinations exist.

## Accessibility
- The section is named by its visible heading through `aria-labelledby`.
- The semantic ordered list preserves the supplied reading order independently of visual layout.
- Item heading rank follows the group heading rank without skipping a level.
- The group and its non-interactive children introduce no focus targets.

## Related Components And Patterns

- `Package Item`: child component composed once per item record.
- `Homepage Hero`: adjacent statement component in the future Homepage composition.

## Code Paths

- `packages/design-system/src/components/PackageHero.astro`
- `apps/portfolio-site/src/design-system/docs/package-hero.astro`

## Verification

- Confirm six abstract items render in the same source order at Mobile, Tablet, Desktop and Ultra-wide contexts.
- Confirm the section heading names the region and item titles use the next semantic heading rank.
- Confirm an empty `items` array emits no empty region.
- Confirm scrolling translates only the internal layer, does not shift adjacent sections, and fades each item independently from 20–60% without clipping; Reduced Motion disables translation and opacity-transition smoothing.
- Run `scripts/design-system-graph --check --no-write`.