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

## Purpose
Reusable non-interactive presentation of one package or system and the recurring problem it solves.

`Package Item` gives future package collections a stable atomic content structure before canonical package destinations exist.

## Hook

Use inside a package or reusable-systems group when one item needs a title and a plain-language problem statement.

## Contract
- Renders exactly one package title, description and ordinal index.
- Uses semantic `Heading` and `Paragraph` primitives.
- Accepts heading levels 2 through 5 so the parent composition can preserve document hierarchy; defaults to level 3.
- Uses Design System typography, color and spacing tokens.
- Owns its leading `color-line` divider so the complete item remains visually self-contained in any parent list.
- Uses a two-column layout with the description on the left and a responsive Display Level 1 package title on the right on Desktop and wider viewports; semantic heading rank remains controlled separately by `headingLevel`.
- Uses twice the semantic surface gap between the description and title columns on Desktop and Ultra-wide; Tablet and Mobile retain the standard surface gap.
- Desktop and Ultra-wide reserve exactly two Display Level 1 title lines, so every Package Item in the collection has the same fixed content height even when a title renders on one line.
- Limits the description measure to `35ch`; content wraps naturally and is never truncated.
- Uses four times the semantic surface-bottom spacing below its content; the parent still owns spacing between complete items.
- Uses a single-column title-description layout on Tablet and Mobile so semantic and visual reading order remain aligned.
- Formats the ordinal index as a two-digit number such as `01`; Desktop and Ultra-wide align it to the reserved second title-line baseline in the left column, while Tablet and Mobile place it in the upper-right corner.
- On Desktop and Ultra-wide, the second description-line baseline aligns with the first package-title-line baseline; the description uses its Body line-height as the alignment offset.
- On Tablet and Mobile, the upper-right ordinal baseline aligns with the first-line baseline of the package title.
- Design System Preview breakpoint contexts reproduce both the layout change and the responsive Display Level 1 typography scale without depending on browser viewport width.
- Design System Preview alone provides a `Replay animation` debug action; it calls the component's replay method and is not a Package Item prop or production child.
- Keeps the visual title hidden until the top edge of the complete Package Item reaches the start of the viewport's lower third, `66%` down from the top, then reveals it once with the shared `38ms` grapheme typewriter rhythm and no cursor.
- Reserves the final title geometry with a hidden layout copy so animation does not move neighboring content.
- The animated output is absolutely layered over that layout copy and contains the complete grapheme sequence from its first frame; unrevealed graphemes stay hidden so final word wrapping is established before typing starts and cannot jump between lines during reveal.
- Reduced Motion and no-JavaScript states expose the complete title immediately.
- Fills the width assigned by its parent. Desktop and Ultra-wide use the fixed two-line title track; Tablet and Mobile continue to hug content height.
- Is intentionally non-interactive: no link, click handler, hover affordance, pressed state or disabled styling.
- Keeps the title and description in a stable article structure so a real destination can be introduced later without rewriting its content model.
- Does not own collection order, section heading, outer block spacing or Homepage placement.
- Design System Preview uses abstract copy and contains no production package claims.

## Use
- Presenting one reusable system inside `Package Hero`.
- Reviewing package title and problem-statement rhythm before Homepage integration.

## Do Not Use
- Linking to a package route that does not exist.
- Presenting projects, articles or generic navigation.
- Owning the complete package collection.

## Props

| Prop | Values | Purpose |
| --- | --- | --- |
| `title` | string | Package or reusable-system name. |
| `description` | string | Plain-language statement of the recurring problem solved. |
| `headingLevel` | `2`, `3`, `4`, `5` | Semantic heading rank selected by the parent composition. |
| `index` | positive number | One-based display order rendered with at least two digits. |

## Accessibility
- The item is an `article` with a semantic heading and paragraph.
- Reading order remains title then description at every breakpoint.
- The responsive visual layout does not change source order.
- The visual ordinal is hidden from assistive technology because the future parent list owns semantic order.
- The complete title remains available to assistive technology before and during visual animation.
- The item exposes no misleading keyboard or pointer interaction.

## Related Components And Patterns

- `Heading`: semantic title primitive.
- `Paragraph`: description primitive.
- `Package Hero`: parent block whose full composition is planned in Story `#0130`.

## Code Paths

- `packages/design-system/src/components/PackageItem.astro`
- `apps/portfolio-site/src/design-system/docs/package-item.astro`

## Verification

- Confirm the item remains non-interactive in rendered HTML.
- Verify title and description wrapping on all supported breakpoints.
- Run `scripts/design-system-graph --check --no-write`.