# Page Template

## Essence

Base page-template composition.

`Page Template` defines the shared page contract: `Header` on top and replaceable content below.

## Hook

Use when a page needs the broad Portfolio page structure before a more specific page-template content is chosen.

## Status

Page template

## Aliases

- Base page template
- Generic shell
- Header plus content template

## Contract

- Renders `Header` at the top.
- Renders replaceable content below Header.
- Does not assume what the content is.
- Does not own side navigation, prop switchers, Preview, or Design System item documentation.
- Content fills the available page width.
- Page fills at least the viewport height.

## Ownership

| Owner | Responsibilities |
| --- | --- |
| Component | Header plus replaceable content composition. |
| Parent | Supplies concrete page content. |
| `Header` | Owns brand bar behavior and header interaction. |
| Content | Owns page-specific layout and semantics. |

## Public Props

- `brandName`: optional brand text passed to `Header`; default is `post-ai.system`.

## Slots

- default slot: replaceable page content.

## Preview-Only Context

- `Content: debug` shows `Stub Object` as abstract replaceable content.
- `Content: Component Page` shows `Component Page` as specialized template content inside the page template.
- The `Content` switcher is documentation-only and does not become a public prop of `Page Template`.

## Internal Rules

- Render `Header` first.
- Render content below Header.
- Keep the content slot generic; do not add component-page-specific controls.
- Use `Stub Object` in documentation previews when content is intentionally abstract.

## Non-Goals

- Does not replace `Component Page`; it provides the generic shell that can contain it.
- Does not define Design System side menu behavior.
- Does not own Preview, Prop Switcher, or component documentation structure.
- Does not define marketing/case-study content rules.

## Use When

- Defining the base shell shared by all page types.
- A page needs Header plus replaceable content.
- A specialized page template should be shown as content inside a page template shell.

## Do Not Use When

- Documenting one Design System item directly; use `Component Page Template`.
- Rendering only the content area without Header.
- A component preview needs only a bounded mini browser surface; use `Preview`.

## Edge Cases

- If a page should not use `Header`, create a specific page-template decision before bypassing this template.
- If page content needs side navigation, that belongs to a specialized content template.
- If Header behavior changes, update `Header` Essence and this template relationship.

## Accessibility Notes

- Header keeps its own accessible brand/navigation behavior.
- Main content uses native `main` semantics.
- Replaceable content must preserve its own heading hierarchy.

## Related Components And Patterns

| Item | Relationship | Direction | Notes |
| --- | --- | --- | --- |
| `Header` | Composes | Parent -> Child | Header is the top region of the page template. |
| `Stub Object` | Documents | Preview -> Placeholder | Used in the DS preview to show replaceable content. |
| `Component Page` | Specializes | Generic -> Specific | Component Page can be shown as specialized content inside Page Template. |

## Source Of Truth

| Source | Path / Link | Notes |
| --- | --- | --- |
| Component implementation | `packages/design-system/src/components/GenericPageTemplate.astro` | Primary behavior and layout source. |
| DS page | `apps/portfolio-site/src/pages/design-system/index.astro` | Visible documentation and example. |
| Relationship map | `docs/design-system/maps/component-relationship-map.md` | Component relationships. |

## Rule Confidence

| Rule | Evidence | Confidence |
| --- | --- | --- |
| Header plus replaceable content | User requested Header and content as Stub Object. | High |
| Base page-template behavior | User said this component describes generic properties and behaviors of all pages. | High |
| Content switcher examples | User requested debug and Component Page variants in the Page Template preview. | High |

## Open Questions

- Should the old `Component Page Template` page artifact be deprecated now that `Component Page` lives under Content?
- Should page-level content padding belong here or to specialized page templates?

## Code Paths

- `packages/design-system/src/components/GenericPageTemplate.astro`
- `packages/design-system/src/components/StubObject.astro`
- `packages/design-system/src/components/Header.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`
- `apps/portfolio-site/src/pages/design-system/essences/[slug].md.ts`
- `docs/design-system/maps/component-relationship-map.md`

## Validation Checklist

- [x] Canonical name is clear
- [x] Contract is explicit
- [x] Ownership is separated
- [x] Slots are listed
- [x] Related items use typed relationships
- [x] Code paths are listed
- [x] DS page link is updated
- [x] Route slug is updated