# Home Page

## Essence

Page-content composition component for the public homepage.

`Home Page` owns the homepage order and the default homepage content groups. It is content only: `Page Template` owns Header and the outer page shell.

## Hook

Use inside `Page Template` for the public `/` route when the site needs the agreed Calm Heresy homepage structure.

## Internal Rules

- Is inserted into `Page Template` as the `Home Page` content variant.
- Does not render `Header`.
- Does not render `Page Template`.
- It does not own outer page padding; full-width child blocks own their own internal spacing.
- Uses the full available page width instead of the standard detail-page content max-width.
- Keeps readable line length inside text-owning children such as `Homepage Hero` and `Article Hero`.
- Renders `Homepage Hero` first.
- Owns homepage section order:
  1. Hero Question.
  2. Use Case Hero.
  3. What matters now.
- Passes a manually selected featured use-case into `Use Case Hero`; current crown use-case is LifeGraph.
- Passes latest use-cases into the lower row of `Use Case Hero`.
- Shows only cards and actions that navigate somewhere.
- Uses `Use Case Hero` for the built-agentic-work portfolio strip.
- Uses `Article Hero` for the latest-articles block.
- Does not locally nest `Card Grid` for the latest articles; `Article Hero Content` owns the nested grid inside `Article Hero`.
- Passes notes into `Article Hero`; lower article-section content owns grid and card rendering.
- Uses real navigable routes only; planned project placeholders were replaced by Use Cases.
- Does not create primary sections for Before AI, Setup, Tooling, or SSH details.

## Use When

- Rendering the public homepage.
- Previewing the complete homepage composition in the Design System.
- A route needs the complete homepage content order without owning content layout inline.
- Showing the abstract homepage composition without binding the component to real article content.

## Do Not Use When

- Rendering one homepage block; use `Homepage Hero` or `Article Hero`.
- Rendering a generic page that is not the homepage.
- Rendering the page shell; use `Page Template`.
- Rendering one card or card grid directly.
- A page needs to lead with tooling or setup details.

## Props

| Prop | Values | Purpose |
| --- | --- | --- |
| `notes` | array of article card items | Items for `What matters now`; when omitted, `Home Page` renders abstract article cards for Design System preview. |
| `featuredUseCase` | use-case card item | Manually selected crown use-case for the top full-width tile. |
| `useCases` | array of use-case card items | Latest use-cases for the lower row of `Use Case Hero`. |

Note item shape follows `Article Card`:

| Field | Values | Purpose |
| --- | --- | --- |
| `title` | string | Article title. |
| `summary` | string | Article preview text. |
| `href` | URL/string | Article destination. |
| `publishedAt` | string | Publish date metadata. |
| `topics` | string[] | Public topics. |

## Accessibility Notes

- `Homepage Hero` owns the page-level H1.
- `Article Hero` owns the article-section H2 through `Article Hero Header`.
- Repeated cards should be linked while the MVP homepage is constrained to navigable items.
- Placeholder routes are acceptable while destination pages are unfinished.

## Related Components And Patterns

- `Page Template`: owns Header plus replaceable content shell.
- `Homepage Hero`: first block.
- `Use Case Hero`: visual strip for built use-cases.
- `Article Hero`: latest-four article block.
- `Card Grid`: repeated-card layout nested inside `Article Hero Content`.
- `Article Card`: latest notes teaser card rendered inside `Article Hero Content`.

## Code Paths

- `packages/design-system/src/components/HomePage.astro`
- `apps/portfolio-site/src/pages/index.astro`
- `apps/portfolio-site/src/pages/use-cases/index.astro`
- `apps/portfolio-site/src/pages/notes/index.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`
- `apps/portfolio-site/src/pages/design-system/essences/[slug].md.ts`