# Component Page Template

## Essence

Standard documentation page composition for one Portfolio Design System item.

`Component Page Template` keeps each token, component, rule, or page-template entry readable in the same structure. Its main-area split is owned by `Component Page`; its private menu area is owned by `Component Page Template Menu Container`; its private inner stack is owned by `Component Detail Body`.

## Hook

Use when a Design System item needs a dedicated reference page.

## Internal Rules

- The page template has no outer top or bottom spacing.
- The actual page shell has no outer left or right spacing around `Component Page`.
- Header is followed immediately by the Menu and content region.
- Menu and content fill the remaining viewport height through the bottom window edge.
- Menu is the only vertical scroll container for navigation; nested menu items never create their own scrollbars.
- The content region uses `--space-8` top and bottom padding.
- Preview remains full width when the Breakpoint switcher changes, following the global breakpoint-preview rule.

- Renders one documented Design System item.
- Uses `Component Page` as the composition of Menu Container plus Component Detail Body.
- Uses `Component Detail Body` for the item name, Essence link, prop switchers, search slot, and Preview frame.
- Uses `Component Page Template Menu Container` for the side menu container and scroll behavior.
- Starts with the item name as Heading level 1 inside `Component Detail Body`.
- Shows an optional Essence link above prop switchers when `essenceHref` is provided.
- May later be composed as specialized content inside `Page Template`.
- Shows breakpoint controls first with `Mobile`, `Tablet`, `Desktop`, and `Ultra-wide`.
- Shows component-specific prop switchers only when the documented item defines them.
- Renders the documented item directly in the Preview area.
- Keeps preview-local interactions local; interacting with preview content must not mutate prop switcher state.

## Use When

- Documenting a Design System component, token, rule, pattern, or page template.
- A page needs a consistent preview-first structure.
- A component has properties or states that should be inspected with prop switchers.
- An Essence artifact exists and should be linked from the page.

## Do Not Use When

- The content is a marketing page, case study, or Artifact Shop page.
- The page needs a fundamentally different product layout.
- The item does not need a preview or Design System reference structure.
- A one-off layout would duplicate the template instead of extending it.

## Edge Cases

- If a component has no Essence yet, omit the Essence link until the Essence exists.
- If a component has no component-specific properties, show only the four-option breakpoint switcher.
- Nested previews must stay scoped so their scripts do not affect the real page shell.
- Links to Essence files should point to served markdown endpoints, not only local filesystem paths.

## Accessibility Notes

- The documented item name should preserve heading hierarchy.
- Prop switcher buttons must remain keyboard reachable.
- Preview content should preserve the accessibility behavior of the documented component.
- Essence links use the `Link` component and native anchor semantics.
- Focus styles use Design System focus tokens.

## Related Components And Patterns

- `Component Page`: private composition for Menu Container on the left and Component Detail Body on the right.
- `Component Detail Body`: private inner composition for the item name, Essence link, prop switchers, search slot, and Preview frame.
- `Component Page Template Menu Container`: private side menu container and scroll behavior.
- `ComponentPreview`: compatibility wrapper around `Component Detail Body`.
- `Page Template`: generic Header plus replaceable content composition.
- `DesignSystemPageTemplate`: owns the page-level menu and content area.
- `ComponentDoc`: wraps the page template metadata for each documented item.
- `Link`: renders the optional Essence link.
- `Prop Switcher`: controlled property rows inside the preview chrome.
- `Preview`: documented subcomponent for the preview surface.

## Code Paths

- `packages/design-system/src/components/ComponentPreview.astro`
- `packages/design-system/src/components/ComponentDetailBody.astro`
- `packages/design-system/src/components/ComponentPageTemplateMenuContainer.astro`
- `packages/design-system/src/components/Header.astro`
- `packages/design-system/src/components/ComponentPageTemplate.astro`
- `packages/design-system/src/components/DesignSystemPageTemplate.astro`
- `packages/design-system/src/components/ComponentDoc.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`
- `apps/portfolio-site/src/pages/design-system/essences/[slug].md.ts`