# Component Page

## Essence

Private active composition used inside `Component Page Template` and the actual Design System shell.

It represents the main area below `Header`: `Component Page Template Menu Container` on the left and `Component Detail Body` on the right.

On Mobile breakpoint, it shows `Menu Navigation` above `Component Detail Body`. `Menu Navigation` shows `Component list` when the menu is hidden and `Back` when the menu is visible.

## Hook

Use when a Design System documentation page needs the standard main area: menu on the left, detail content on the right, and mobile menu overlay behavior.

## Status

Private active

## Aliases

- Template main area
- Page template main split
- Menu and detail composition

## Contract

- Renders a two-part composition: menu area first, detail body second.
- Keeps `Component Page Template Menu Container` on the left on desktop-sized layouts.
- Defaults the menu container width to 420px through `--menu-container-width`.
- Keeps `Component Detail Body` on the right on desktop-sized layouts.
- On Mobile breakpoint, hides the menu area until the user opens it.
- On Mobile breakpoint, renders `Menu Navigation` above `Component Detail Body`.
- On Mobile breakpoint, opens the menu area as a full-viewport overlay.
- Closes the mobile overlay through `Back` inside `Menu Navigation`.
- Keeps `Menu Navigation` outside the menu scroll area.
- Keeps `Menu Navigation` visible while the menu overlay is open.
- Highlights the selected page in the menu when the current page exists in the menu tree.
- Does not own `Header`.
- Does not own actual page routing or selected section state.
- Is used by `DesignSystemShell` for the actual `/design-system/` page layout.

## Ownership

| Owner | Responsibilities |
| --- | --- |
| Component | Owns the left/right main-area composition and mobile menu overlay state. |
| Parent | Supplies menu and detail slots. |
| `Component Page Template Menu Container` | Owns menu container behavior and right border. |
| `Component Detail Body` | Owns title, Essence link, prop switchers, optional search slot, and Preview. |
| `Menu Navigation` | Provides the mobile `Component list` and `Back` actions. |

## Public Props

- `ariaLabel`: accessible label for the main area.

## Slots

- `menu`: expected to contain `Component Page Template Menu Container`.
- `detail`: expected to contain `Component Detail Body`.

## Internal Rules

- Render `menu` before `detail`.
- Use a 420px menu column and flexible detail column on desktop-sized layouts.
- Read resized menu width from `--menu-container-width`.
- Collapse to one column on mobile-sized layouts.
- Keep the menu hidden on Mobile until opened by `Menu Navigation`.
- Place `Menu Navigation` above `Component Detail Body`.
- Render the opened menu as a full-viewport overlay on real mobile viewport.
- Render the opened menu as an in-preview overlay when the Component Preview breakpoint is Mobile.
- Keep `Menu Navigation` sticky above the menu overlay so the menu scrolls below it.
- Let `Back` inside `Menu Navigation` close the mobile overlay.
- Let Escape close the mobile overlay.
- Mark the selected/current page as active in template-level menu examples.
- Keep this component as the single source for Design System menu/detail layout behavior.

## Non-Goals

- Does not replace `Component Page Template`.
- Does not include `Header`.
- Does not include section-switching behavior.
- Does not decide Design System taxonomy.

## Use When

- Rendering the main body composition of `Component Page Template`.
- Rendering the actual Design System shell below `Header`.
- Keeping preview and actual Design System page composition aligned.

## Do Not Use When

- Building public product pages.
- Rendering a standalone component detail page without the menu area.
- Building a one-off page layout outside the Design System documentation area.

## Related Components And Patterns

| Item | Relationship | Direction | Notes |
| --- | --- | --- | --- |
| `Component Page Template` | Used By | Parent -> Child | Private child of the template. |
| `DesignSystemShell` | Used By | Parent -> Child | Uses Component Page for actual `/design-system/` layout while retaining section switching. |
| `Component Page Template Menu Container` | Composes | Parent -> Child | Left slot. |
| `Component Detail Body` | Composes | Parent -> Child | Right slot. |
| `Menu Navigation` | Composes | Parent -> Child | Mobile-only navigation above Component Detail Body. |

## Source Of Truth

| Source | Path / Link | Notes |
| --- | --- | --- |
| Component implementation | `packages/design-system/src/components/ComponentPage.astro` | Primary behavior and layout source. |
| Shell integration | `packages/design-system/src/components/DesignSystemShell.astro` | Actual Design System page uses this composition. |
| 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 |
| --- | --- | --- |
| Private under Component Page Template | User requested a new component under Component Page Template. | High |
| Contains Menu Container and Component Detail Body | User requested menu container on the left and detail body on the right. | High |
| Mobile menu overlay | User requested Component list trigger above title that opens menu as a viewport overlay. | High |
| Back closes mobile overlay | User explicitly requested Back closes the menu. | High |
| Menu Navigation ownership | User moved this component out of Menu Container and into Component Page. | High |
| Selected page highlight | User requested selected page should be highlighted at template level. | High |
| Actual shell usage | User approved actual pages using the Component Page composition. | High |

## Open Questions

- Should mobile collapse behavior stay here or move into a future responsive template rule?

## Code Paths

- `packages/design-system/src/components/ComponentPage.astro`
- `packages/design-system/src/components/DesignSystemShell.astro`
- `packages/design-system/src/components/MenuNavigation.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] Related items use typed relationships
- [x] Code paths are listed
- [x] DS page link is updated
- [x] Route slug is updated