Established

Contextual nudge

An in-place hint that an AI action is available on the object the user is already looking at.

MInboxSupport queue · 3 open

Charged twice this month

#4821 · Dana Ortiz · Pro plan, 8 seats

Dana Ortiz today 09:41

Hi, my card was charged $1,240 twice on 14 Aug. Can you refund one of them? I only have one workspace.

Invoice #882114 Aug, 09:12$1,240.00

Invoice #882214 Aug, 09:14$1,240.00

These two charges match. Milky can draft the refund reply.

Reply to Dana…

Public reply

Try it: Open each ticket: only the one Milky can actually help with gets a quiet hint. Use it, or dismiss it.

In the wild

How one product ships this pattern. Click a screenshot to enlarge it.

A new Notion page titled 'Weekend trip to Lisbon' with grey placeholder text 'Press space for AI or / for commands' on the first empty line, and 'Get started with' chips for Ask AI, AI Meeting Notes, Database, Form and Templates. — Notion
An empty line shows a quiet placeholder hint that AI is one keystroke away, and it disappears as soon as the user starts typing.
Source: Notion (captured Sep 2026) ↗

When to use

When the capability is buried in a menu and discovery is the actual bottleneck.

Seen in

Linear's suggest-sub-issues affordance, Gmail Help me write chip, Figma inline suggestions.

For engineers

Gate on eligibility server-side; a nudge that opens into "not available here" is worse than no nudge.

Build prompt

A neutral, component-only prompt for a coding agent. Edit the stack block or anything else to fit your project, then copy it.

# Build the "Contextual nudge" pattern: `ContextualNudge`

## Stack (edit this block to match your project)
- React 18+ with TypeScript: one function component, typed props, no `any`.
- Tailwind CSS, using your design system's tokens if you have them.
- Presentational only: data comes in through props, decisions go out through callbacks. No fetching or global state inside.
- If your codebase already has conventions (naming, shared components, tokens), follow them over this spec.

## What the pattern is for
An in-place hint that an AI action is available on the object the user is already looking at.

Use it when: When the capability is buried in a menu and discovery is the actual bottleneck.

## What to build
A small, dismissible hint attached to the object a person is already looking at, offering one AI action that is known to work on that object. It states why it appeared and opens straight into the action. It renders inline next to a record, message, row or empty field.

### Props
- `eligible`: boolean, decided by the parent from a server-side check. When false the component renders nothing.
- `reason`: string, the specific trigger in plain words, e.g. "These two charges match".
- `actionLabel`: string, a verb phrase naming the one action, e.g. "Draft refund reply".
- `variant`: "inline" | "placeholder", a bordered hint beside content, or a quiet placeholder inside an empty input that disappears on typing.
- `status`: "idle" | "running" | "done" | "error", controlled by the parent after the action is taken.
- `onAccept()`: called when the person takes the action. The component never performs it itself.
- `onDismiss(scope: "this" | "type")`: dismiss for this object only, or stop showing this kind of nudge.
- `shortcut?`: string, a key hint shown beside the label when the action has one.

### States it must render
- Hidden: `eligible` is false, nothing renders and no space is reserved.
- Idle: one line with the AI accent, the reason, the action button and a dismiss control.
- Placeholder: inside an empty field, muted hint text with the shortcut; it vanishes as soon as the person types.
- Running: the action button shows progress and is disabled; dismiss stays available.
- Done: the nudge collapses away once the result is shown elsewhere; it does not linger as a badge.
- Error: a short message that the action failed on this object, with retry.

### Interactions
- The action button calls `onAccept` and nothing else; it never opens a menu of unrelated actions.
- Dismiss offers "Not for this one" and "Stop suggesting this", each calling `onDismiss` with the matching scope.
- In placeholder variant, the shortcut key calls `onAccept` only while the field is empty and focused.

### Edge cases
- Several eligible objects on one screen: the parent should pass `eligible` for at most one; the component shows no generic sparkle when it has no specific `reason`.
- Eligibility changes while visible (e.g. the record is edited): hide immediately rather than let the person open into "not available here".
- An accept that the server then rejects: show the error state on the nudge, not a modal.
- A previously dismissed object: the parent passes `eligible: false`; the component holds no memory of its own.

## Must avoid
Sprinkling sparkle icons on every surface until the badge means nothing and users tune it out.

## Engineering constraint
Gate on eligibility server-side; a nudge that opens into "not available here" is worse than no nudge.

## Accessibility
- The nudge is a `note` (or `aside`) labelled by its reason, placed after the content it refers to in reading order so it is met in context.
- Do not move focus to the nudge when it appears; announce its appearance once, politely.

## House rules
- Real `<button>`/`<input>` elements, full keyboard use, visible focus; announce status changes with `aria-live="polite"`; respect `prefers-reduced-motion`.
- All user-facing text comes from props (or a `labels` prop) so it can be translated.
- One consistent accent marks anything the AI made or is doing; amber means "needs a person", red means risky, green means done. Never rely on colour alone.
- Fits a 360 px wide container without horizontal scrolling.

## Acceptance checks
- [ ] Every state above can be rendered by passing props, with no internal fake data.
- [ ] Every interaction and edge case above behaves as described.
- [ ] Nothing in "Must avoid" can happen with this component.

## Deliver
1. The component file with its exported prop types.
2. A short usage example that renders each state.

Download this prompt as Markdown, or every prompt as JSON for an agent.

Critique checklist for wayfinders

0 of 4 checked

These questions apply to every pattern in this family. Ticks are saved in this browser.

Can a first-time user act without typing anything?
Do suggestions reflect the user's actual context, not a generic list?
Is the system's boundary stated somewhere findable?
Do nudges stop appearing once the behaviour is learned?