# ADR-0068: Static help must look different from controls

- **Status:** Accepted
- **Date:** 2026-09-04
- **Deciders:** jka
- **Decision:** D68

## Context

In the Repositories dialog, a hint sentence in the normal text colour sat directly
above a borderless listbox whose single repository URL used the same colour. The
selectable, removable entry read as another line of help. The maintainer had
corrected this kind of problem more than once.

## Decision

In every window, explanatory text and interactive elements must be distinguishable
at a glance. Two measures are used together:

1. Help, description and hint text uses a muted secondary role (`gutter.fg`), never
   the `ui.fg` colour used by interactive text.
2. Interactive containers (lists, entries, text areas the user can select from) have
   a visible boundary (`-relief solid -borderwidth 1`), not a borderless widget on the
   window background.

Every new dialog is checked for help text that looks like a control, and controls
that look like help, before it ships.

## Consequences

- Users do not have to guess what is clickable.
- The rule is applied throughout later dialogs: agent prompts (ADR-0070), accepted
  certificates and the certificate review (ADR-0111).