# Prop Naming Rule

## Essence

Rule for consistent property and value names across Design System components.

Properties and values that represent the same concept must use the same names from component to component.

## Hook

Use before adding or changing any component property, property value, preview switcher, or component essence spec.

## Internal Rules

- Use the same property name for the same concept across components.
- Use the same value name for the same value across components.
- Check existing component props before introducing a new name.
- Check existing values before introducing a new value.
- If a similar concept needs a different name, record a design-system decision before implementation.
- Prop and value naming should be boring, stable, and agent-readable.

## Current Canonical Props

- `Breakpoint`: responsive preview scope.
- `State`: visual or interaction state for a single interactive component.
- `Interaction`: simulated user interaction state where `State` would be ambiguous.
- `Level`: semantic heading level.
- `Alignment`: horizontal text alignment.
- `Disclosure`: expanded/collapsed content visibility.
- `Clickable`: whether a group label navigates separately from disclosure.
- `Inverse`: whether Preview uses its approved inverse background context.

## Current Canonical Values

- `Mobile`, `Tablet`, `Desktop`, `Ultra-wide`: canonical breakpoint range names.
- `normal`: base interactive state.
- `hover`: pointer hover state.
- `focus`: focus state.
- `focus-visible`: keyboard-visible focus state.
- `pressed`: active mouse/touch press state.
- `disabled`: unavailable state.
- `active`: selected control value or active local state.
- `selected`: currently selected navigation item.
- `visited`: visited link state.
- `left`, `center`, `right`: horizontal alignment values.
- `expanded`, `collapsed`: disclosure visibility values.
- `true`, `false`: boolean property values.

## Use When

- Creating a new component spec.
- Adding a property switcher.
- Naming a state or value in a preview.
- Writing a component essence.
- Reviewing whether a new prop name causes fragmentation.

## Do Not Use When

- The name is unrelated to component behavior or preview control.
- The concept is a one-off implementation detail that should not become public component language.

## Edge Cases

- If two components use different words for the same behavior, normalize to this rule.
- If a component really needs a new term, add the term to this rule before the component spreads it.
- If a value is component-specific, document why it is not reusable.

## Accessibility Notes

- Naming consistency helps agents preserve accessible states across components.
- State names should map cleanly to semantic or ARIA behavior when possible.

## Related Components And Patterns

- `Component Page Template`: uses prop switchers driven by these names.
- `Prop Switcher`: renders canonical property/value controls.
- `Prop Button`: renders one canonical value.
- All component essences: should follow this rule.

## Code Paths

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