# Focus & Interaction States

## Essence

Foundation interaction-state token contract for interactable components.

`Focus & Interaction States` defines generic visual behavior for normal, hover, pressed, focus, focus-visible, selected, and disabled states.

## Hook

Use when building or reviewing any component that can be clicked, focused, selected, disabled, or otherwise interacted with.

## Internal Rules

- Use generic interaction tokens before creating component-local state colors.
- `normal` uses transparent background and accent text color.
- `hover` uses soft accent background and accent text color.
- `pressed` uses accent background and surface text color.
- `focus` uses inset 1px accent focus ring.
- `focus-visible` uses inset 2px accent focus ring.
- `selected` and `active` use selected background and selected text color.
- `disabled` uses `--interaction-disabled-opacity: 0.55`.
- Focus rings render inside the element so scrollable containers do not crop them.
- State names must stay aligned with Prop Naming Rule.

## Current Tokens

- `--interaction-normal-bg: transparent`.
- `--interaction-normal-color: var(--color-accent)`.
- `--interaction-hover-bg: var(--color-accent-soft)`.
- `--interaction-hover-color: var(--color-accent)`.
- `--interaction-pressed-bg: var(--color-accent)`.
- `--interaction-pressed-color: var(--color-surface)`.
- `--interaction-selected-bg: var(--color-accent-soft)`.
- `--interaction-selected-color: var(--color-accent)`.
- `--interaction-disabled-opacity: 0.55`.
- `--interaction-focus-ring: var(--focus-ring)`.
- `--interaction-focus-visible-ring: var(--focus-ring-visible)`.

## Use When

- Styling an interactive component state.
- Simulating component states in a preview.
- Reviewing hover, pressed, focus, selected, or disabled behavior.
- Checking that state colors remain consistent across components.

## Do Not Use When

- A component is not interactive.
- The state is component-specific and needs a new Design System decision.
- The visual change is layout, typography, or content rather than interaction behavior.

## Edge Cases

- Disabled items should be unavailable but still readable.
- Focus-visible should be stronger than generic focus.
- Selected/active state may share hover colors unless a future token separates them.
- If a component needs state behavior outside this set, update Prop Naming Rule and this essence together.

## Accessibility Notes

- Focus and focus-visible states must remain visible in scrollable containers.
- Disabled state should not rely only on opacity if meaning would be lost.
- Hover is not enough for keyboard accessibility.
- Pressed state should be visible during mouse or touch activation.

## Related Components And Patterns

- `Prop Naming Rule`: owns canonical state names.
- `Link`: consumes interaction state tokens.
- `Menu Item`: consumes selected, pressed, disabled, and focus tokens.
- `Collapsible Menu Item`: consumes hover, pressed, disabled, and focus tokens.
- `Disclosure Icon Button`: consumes icon interaction behavior through its parent button.
- `Prop Button`: consumes active, disabled, pressed, hover, and focus states.

## Code Paths

- `packages/design-system/src/styles/tokens.css`
- `apps/portfolio-site/src/pages/design-system/index.astro`