# Component Detail Body

## Essence

Private composition used inside `Component Page Template`.

It assembles the visible documentation stack for one Design System item: component name, optional Essence link, property switchers, optional search slot, and the Preview frame.

## Hook

Use when `Component Page Template` needs to render the standard inner documentation composition for a selected Design System item.

## Status

Private

## Aliases

- ComponentPreview implementation layer
- Preview chrome

## Contract

- Guarantees the standard top-to-bottom order: name, Essence link, prop switchers, search slot, Preview.
- Guarantees breakpoint controls render first.
- Guarantees component-specific prop switchers render before Preview.
- Owns internal padding around the full detail body.
- Owns preview-local property state and dataset updates.
- Does not own page-level Header, Menu, page routing, or section visibility.
- Does not decide whether an Essence link exists; parent supplies `essenceHref`.
- Does not persist state outside the local preview instance.

## Ownership

| Owner | Responsibilities |
| --- | --- |
| Component | Renders name, Essence link, prop switchers, search slot, Preview frame, and local preview state updates. |
| Parent | Supplies label, Essence link, property definitions, inverse context, search slot, and preview children. |
| Preview | Owns the visual frame where documented children render. |
| Token system | Supplies spacing, color, border, radius, typography, and interaction tokens. |
| Page/layout | Owns Header, Menu, section switching, and page-level scroll behavior. |

## Public Props

- `label`: visible component/page name.
- `fullWidth`: compatibility prop from earlier preview usage.
- `essenceHref`: optional markdown Essence route.
- `essenceLabel`: optional visible link label.
- `properties`: component-specific prop switcher rows.
- `inverse`: Preview background context.
- `showInverseControl`: whether to expose `Inverse` as a switcher.

## Preview-Only Context

- Breakpoint switcher records preview context but does not resize the Preview.
- Search slot is for documentation examples such as Icons search.
- `inverse` is a Preview context unless the documented component itself owns inverse behavior.

## Internal Rules

- Render `Heading level=1` for the label.
- Render Essence link only when `essenceHref` exists.
- Render Breakpoint first.
- Render optional Inverse row before component-specific properties when enabled.
- Render search slot after prop switchers and before Preview.
- Use `--space-8` as internal padding on all sides of the detail body.
- Render children directly inside the Preview frame.
- Keep preview-local interactions local; interacting with preview content must not mutate prop switchers unless explicitly wired by this composition.

## Non-Goals

- Does not replace `Component Page Template`.
- Does not define public product layout outside the Design System.
- Does not own Menu, Header, routing, or page scroll.
- Does not decide component existence or Design System taxonomy.

## Use When

- Rendering the inner content stack of `Component Page Template`.
- A Design System item needs name, Essence link, prop controls, and Preview in the standard order.
- A private implementation layer is needed behind the compatibility `ComponentPreview` wrapper.

## Do Not Use When

- Rendering non-Design-System product pages.
- A component needs only the Preview frame without title/link/controls.
- A parent template needs Header/Menu/page shell behavior.

## Edge Cases

- If no component-specific properties exist, render only Breakpoint unless other preview controls are explicitly enabled.
- If no Essence exists yet and deferral was approved, omit the Essence link.
- Nested instances must keep scripts scoped to the nearest `data-preview-id`.
- Preview-local property changes must not update unrelated nested previews.

## Accessibility Notes

- Label uses a semantic heading through `Heading`.
- Essence link uses the `Link` component and native anchor behavior.
- Prop switcher values are keyboard-reachable buttons.
- Active prop values must remain visually distinguishable.
- Preview children preserve their own accessibility contracts.

## Token Dependencies

- `--space-2`
- `--space-3`
- `--space-8`
- `--color-bg`
- `--color-bg-inverse`
- `--color-line`
- `--color-surface`
- `--color-secondary-text`
- `--color-accent`
- `--interaction-selected-bg`
- `--interaction-selected-color`
- `--radius-sm`

## Related Components And Patterns

| Item | Relationship | Direction | Notes |
| --- | --- | --- | --- |
| `Component Page Template` | Used By | Parent -> Child | Template uses this as its private inner composition. |
| `ComponentPreview` | Replaces | New implementation -> Compatibility wrapper | Wrapper delegates to this component for existing pages. |
| `Prop Switcher` | Composes | Parent -> Child | Property rows are this composition's subcomponent behavior. |
| `Prop Button` | Composes | Parent -> Child | Each property value is rendered as a button. |
| `Preview` | Composes | Parent -> Child | Frame area displays the documented component. |
| `Link` | Composes | Parent -> Child | Used for optional Essence link. |
| `Heading` | Composes | Parent -> Child | Used for the item name. |

## Change Impact

| Change | Risk | Review Needed |
| --- | --- | --- |
| Prop switcher state logic | High | Check all interactive component pages. |
| Preview frame spacing/border | Medium | Check visual consistency across token/component pages. |
| Heading or Essence link order | Medium | Check Component Page Template contract and screenshots. |
| Slot behavior | High | Check Icons search, nested previews, and private subcomponents. |

## Source Of Truth

| Source | Path / Link | Notes |
| --- | --- | --- |
| Component implementation | `packages/design-system/src/components/ComponentDetailBody.astro` | Primary behavior and layout source. |
| Compatibility wrapper | `packages/design-system/src/components/ComponentPreview.astro` | Existing DS pages use this wrapper. |
| DS page | `apps/portfolio-site/src/pages/design-system/index.astro` | Visible documentation and examples. |
| Relationship map | `docs/design-system/maps/component-relationship-map.md` | Component relationships. |

## Rule Confidence

| Rule | Evidence | Confidence |
| --- | --- | --- |
| Private to Component Page Template | User requested a private component to Component Page Template. | High |
| Preview and Prop Switcher are subcomponents | User requested the new component to have Preview and prop switcher as subcomponents. | High |
| ComponentPreview remains wrapper | Existing pages already import ComponentPreview broadly. | Medium |

## Open Questions

- Should `ComponentPreview` eventually be renamed or removed after all pages migrate to the new canonical component name?
- Should `Preview` become a separate code component instead of a documented subcomponent implemented inside this composition?

## Code Paths

- `packages/design-system/src/components/ComponentDetailBody.astro`
- `packages/design-system/src/components/ComponentPreview.astro`
- `packages/design-system/src/components/ComponentPageTemplate.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] Aliases are captured
- [x] Contract is explicit
- [x] Ownership is separated
- [x] Public props are separated from preview-only context
- [x] Token dependencies are listed
- [x] Related items use typed relationships
- [x] Accessibility notes are present
- [x] Change impact is described
- [x] Code paths are listed
- [x] DS page link is updated
- [x] Route slug is updated
- [x] Relationship map is updated
- [x] Build passed