# Inline Help First

**SHOULD** · **ID:** `content-inline-help-first` · **Category:** content
**Source:** [Vercel](https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)
**Interactive version:** https://ui-guides-agent-rules.netlify.app/principles/content-inline-help-first

> SHOULD: Inline help first; tooltips last resort

Prefer inline explanations; use tooltips as last resort

Tooltips hide information and require hovering, which doesn't work on touch devices. Whenever possible, include help text inline where it's always visible. Use tooltips only for supplementary information that would clutter the interface.

## Bad — do not do this

`content-inline-help-first-bad`

```tsx
import { HelpCircle } from 'lucide-react';

export function InlineHelpFirstBad() {
  return (
    <div className="w-full max-w-sm">
      <form className="space-y-4">
        <div>
          <div className="flex items-center gap-2 mb-1">
            <label htmlFor="bad-inline-api" className="block text-sm font-medium text-foreground">
              API Key
            </label>
            <button
              type="button"
              title="Your API key is used to authenticate requests"
              className="text-muted-foreground hover:text-muted-foreground"
            >
              <HelpCircle className="w-4 h-4" />
            </button>
          </div>
          <input
            id="bad-inline-api"
            type="text"
            className="w-full px-3 py-2 border border-border rounded-lg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
          />
        </div>
      </form>
      <p className="text-xs text-error mt-4">
        Help hidden in tooltip, not accessible on touch
      </p>
    </div>
  );
}
```

## Good — do this

`content-inline-help-first-good`

```tsx
export function InlineHelpFirstGood() {
  return (
    <div className="w-full max-w-sm">
      <form className="space-y-4">
        <div>
          <label htmlFor="good-inline-api" className="block text-sm font-medium text-foreground mb-1">
            API Key
          </label>
          <input
            id="good-inline-api"
            type="text"
            className="w-full px-3 py-2 border border-border rounded-lg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring"
          />
          <p className="text-xs text-muted-foreground mt-1">
            Your API key is used to authenticate requests. Find it in your account settings.
          </p>
        </div>
      </form>
      <p className="text-xs text-success mt-4">
        Help text always visible and accessible
      </p>
    </div>
  );
}
```

## References

- [Tooltip Usability](https://www.nngroup.com/articles/tooltip-guidelines/)