# Prop Switcher

## Essence

Locked property-control subcomponent of `Component Page Template`.

`Prop Switcher` renders one documented component property and its finite set of selectable values.

## Hook

Use when `Component Page Template` needs a controlled way to switch the previewed component between property values.

## Internal Rules

- Used only inside `Component Page Template`.
- Represents a component property, not arbitrary page controls.
- Renders a short property label.
- Contains one or more `Prop Button` values.
- Shows only when the documented component defines that property.
- The breakpoint switcher is the first Prop Switcher and exposes `Mobile`, `Tablet`, `Desktop`, and `Ultra-wide`.
- Changing the breakpoint context does not resize Preview or change component layout until a breakpoint-specific design is approved.
- Updates preview dataset state and active `Prop Button` state.
- Interacting inside the preview must not update Prop Switcher state unless explicitly designed.

## Use When

- A documented component has a finite property value set.
- A preview needs controlled state switching.
- A user needs to inspect component variants without changing production data.

## Do Not Use When

- The page is not using `Component Page Template`.
- The value is free-form input.
- The control performs a command or mutates persisted product state.
- The property belongs to global site navigation rather than the documented component.

## Edge Cases

- If a property has many values, consider a different control pattern before overloading Prop Switcher.
- If a property value is unavailable but meaningful, render the value as disabled rather than hiding it.
- If the property label becomes long, revisit the component property name.
- If state behavior becomes complex, introduce a dedicated preview-state helper instead of scattered page JavaScript.

## Accessibility Notes

- Property labels should be short and understandable.
- Each `Prop Button` must remain keyboard reachable unless disabled.
- Active and disabled states must be visually distinct.
- Focus states use Design System focus behavior.

## Related Components And Patterns

- `Component Page Template`: the only owner of Prop Switcher usage.
- `Prop Button`: locked value primitive inside Prop Switcher.
- `Preview`: displays the component state controlled by Prop Switcher.
- `ComponentPreview`: implementation layer that renders property rows and synchronizes preview dataset state.

## Code Paths

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