# Preview

## Essence

Locked subcomponent of `Component Page Template` that mimics a browser window for component examples.

`Preview` is the display surface where a Design System page renders any documented component as an example.

## Hook

Use when `Component Page Template` needs to show the documented component in a controlled mini browser surface.

## Internal Rules

- Used only inside `Component Page Template`.
- Mimics a browser window for component display.
- Renders the documented component directly inside the preview area.
- Width fills the parent.
- Height wraps content unless the page template deliberately constrains it.
- Exposes canonical `Inverse` values `false` and `true`.
- `Inverse: false` uses `--color-bg`.
- `Inverse: true` uses `--color-bg-inverse`.
- The Inverse switcher is shown when documenting Preview itself.
- Consuming component pages may set inverse Preview context without exposing it as a component prop.
- Does not add extra card wrappers around the documented component.
- Can contain `Stub Object` when the real component is abstract or not defined yet.
- Preview-local interactions may change local preview DOM state, but must not update prop switcher state.

## Use When

- A Design System page needs to show any component as an example.
- A component state should be inspected inside the page template.
- A page-template subcomponent needs a mini browser surface to test layout behavior.

## Do Not Use When

- The page is not a `Component Page Template` page.
- The content is a production page section rather than a Design System component example.
- The display surface needs custom product layout instead of the standard Design System preview.
- The component should be represented only as text, rules, or an Essence artifact.

## Edge Cases

- If the documented component is abstract, use `Stub Object` inside Preview.
- Use `Inverse: true` for components that require an inverse surface, without adding a fake parent component to the example.
- If nested previews are needed, scope scripts and DOM selection so nested preview behavior does not affect the outer page.
- If a component needs an extra wrapper, that wrapper should belong to the documented component itself, not to Preview.
- If Preview becomes needed outside `Component Page Template`, create a new pattern decision before reusing it.

## Accessibility Notes

- Preview should preserve the accessibility behavior of the documented component.
- Preview must not hide focus states of interactive children.
- Prop switchers and preview-local interactions must remain conceptually separate.
- Do not use Preview as a semantic replacement for the component it displays.

## Related Components And Patterns

- `Component Page Template`: the only owner of Preview usage.
- `ComponentPreview`: implementation layer that renders Preview chrome and controls.
- `Stub Object`: generic placeholder component that Preview may use for abstract examples.
- `Prop Switcher`: controls preview state above the preview area.
- `Link`: can link from Preview chrome to Essence artifacts when provided.

## Code Paths

- `packages/design-system/src/components/ComponentPreview.astro`
- `apps/portfolio-site/src/pages/design-system/index.astro`