kandev/docs/decisions/2026-07-29-interactive-accent-surface-semantics.md

ADR-2026-07-29-interactive-accent-surface-semantics: Separate Brand Accent from Interactive Surface Fills

Status: accepted Date: 2026-07-29 Area: frontend

Context

Kandev's accent token is a bright brand color, while several inherited UI patterns treated it as a neutral background for hover, focus, open, and selected states. That combination reduced text contrast and obscured semantic status colors on icons. The problem appeared across shared menu primitives and application-specific selectors, so local fixes alone would keep drifting.

Decision

• Transient interactive states such as hover, focus, and open use a neutral muted, input, or card-derived surface with the normal foreground.
• Persistent non-semantic selection uses a neutral or card fill plus a primary accent border or inset ring. Components reserve border width or use an inset ring so selection does not change layout.
• True primary actions use the matched primary and primary-foreground token pair. Semantic status fills keep their domain-specific colors.
• Shared menu, context-menu, menubar, select, and table primitives preserve explicit semantic icon colors instead of forcing descendants to an accent foreground.
• The bright brand accent token remains available for intentional brand emphasis, but not as the default interactive surface fill.

No product spec changes are needed because this standard changes visual token usage without changing product capabilities, navigation, or workflows.

Consequences

Selection remains recognizable through the accent boundary without placing text or colored icons on a saturated background. Hover and keyboard-focus states remain visible in light and dark themes. New interactive components must choose transient, selected, primary-action, or semantic-status styling explicitly instead of relying on the generic accent-background convention.

Alternatives Considered

• Neutralize the global accent token. Rejected because it would remove the existing bright brand color from intentional accent uses and silently alter unrelated surfaces.
• Patch only the reported PR controls. Rejected because the same contrast failure existed in shared primitives and other selectors.
• Add another interaction-background token. Rejected because existing muted, input, and card surfaces already express the needed neutral states.