AI suggestions
One look wherever Claude is asked for something: a pill with a warm sweep round its edge and a spark, and a card the suggestion arrives in. Nothing changes until someone chooses “Use this”.
Aerial view of a white beach and turquoise water.
Aerial view of a white beach and turquoise water.
Show code
<button type="button" class="sn-ai sn-ai--small"><span class="sn-ai-label">Suggest a description</span></button>
<!-- While Claude works -->
<button type="button" class="sn-ai sn-ai--small" aria-busy="true" aria-disabled="true"><span class="sn-ai-label">Thinking…</span></button>
<!-- A suggestion -->
<div class="sn-ai-card" role="group" aria-label="Suggested description">
<span class="sn-ai-card-label">Suggested by Claude</span>
<p>Aerial view of a white beach and turquoise water.</p>
<div class="sn-ai-card-actions"><button class="btn-secondary">Use this</button> <button class="btn-secondary">No thanks</button></div>
</div>
<!-- By script -->
import { aiButton, aiBusy, aiCard } from '@somnia/core/lib/ai.js';
const ask = aiButton('Suggest a description');
ask.addEventListener('click', async () => {
aiBusy(ask, true);
try { field.after(aiCard({ value: await suggest(), actions: [use, no] })); }
finally { aiBusy(ask, false, { after: 'Suggest again' }); }
}); When to use it
- Anywhere Claude is asked for words: a description, a title, search details.
- Before the fields it would fill, with a line saying what is sent.
Use something else when:
- Nothing is being asked of Claude: an ordinary button. The look means one thing.
- The words would be written without anyone choosing them: don't. Nothing changes until “Use this”.
How it works
- Every request to Claude uses
.sn-ai, never a plain button or a link, so people learn one thing: this asks Claude.--smallinside forms and dialogs. - It goes before the fields it fills, with a line under it saying what's sent and that nothing changes until “Use this”. Each suggestion arrives in a
.sn-ai-cardunder its own field. - The colours are the
color.ai.*tokens (start, middle, end and the card's surface), the same in every brand: Claude looks like Claude on every site. The words stay in the page's ink, so contrast never rests on them. - While Claude works,
aiBusy()marks the button busy (aria-busyandaria-disabled, neverdisabled, so it keeps the keyboard's focus), ignores a second press, turns the sweep, pulses the spark and shimmers the words, which say what's happening (“Thinking…”, “Looking at the picture…”). Afterwards it reads “Suggest again”. - The spark is a generic four-point star, not Anthropic's logo. Suggest buttons don't print.
Do and don't
Do
- Say what is sent to Claude, beside the button
- Offer “Use this” and “No thanks” on every suggestion
Don't
- Fill a field without being asked
- Use the look for anything that isn’t Claude
Accessibility
What it does for you
- Suggest is a real button, named by its words, 34px high in a form and 40px at full size.
- While Claude works it is busy, not disabled: it keeps the keyboard’s focus, its words say what is happening ("Thinking…"), and a second press does nothing.
- A suggestion arrives in a named group, with "Use this" and "No thanks" as real buttons. Nothing is written until one is pressed.
- The words are the page’s own text colour; the coloured sweep and the spark are decoration.
- With reduced motion nothing turns, pulses or shimmers.
What you need to do
- Words on the button that say what will be suggested.
- A line beside it saying what is sent to Claude.
- Move the focus to the suggestion when it arrives, so it is read out.
Keyboard
| Key | What it does |
|---|---|
| Tab | Moves to Suggest; then, in a suggestion, to Use this and No thanks. |
| Enter or Space | Asks for a suggestion; takes it or turns it down. |
What a screen reader is told
- A button, "Suggest a description"; while it works, "Thinking…", busy and unavailable.
- The suggestion: a group, "Suggested description", then its words and two buttons.
This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.
WCAG 2.2
| Criterion | Level | How this meets it |
|---|---|---|
| 1.4.3 Contrast (Minimum) | AA | The words are the page’s text colour on the page’s surface. |
| 2.1.1 Keyboard | A | Native buttons throughout. |
| 2.3.3 Animation from Interactions | AAA | The sweep, the pulse and the shimmer stop with reduced motion. |
| 2.5.8 Target Size (Minimum) | AA | Suggest is 34px high or more; the choices are full-size buttons. |
| 3.2.2 On Input | A | Nothing in the form changes until "Use this". |
| 4.1.2 Name, Role, Value | A | A named button that says it is busy; a named group. |
The criteria this component has a part in. A page that uses it still has to meet the rest.
Checked
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 8 of 8 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 5 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not yet Not yet checked by a person |
The 8 checks made with the keyboard, on the example at the top of this page:
- Passed Suggest is a button named by its words
- Passed A busy Suggest button says so, is marked unavailable, and is not disabled: Tab still reaches it
- Passed A press on a busy button does nothing
- Passed A suggestion is a named group holding its words and two buttons
- Passed Tab goes from Suggest to the suggestion’s buttons, in order
- Passed Every button is at least 24px high
- Passed The button’s words have at least 4.5:1 against the page, in light and dark
- Passed With reduced motion a busy button does not turn, pulse or shimmer
Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.
Not yet checked
- How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
- Windows high contrast (forced colours) has not been looked at by a person.
- Whether a screen reader says "Thinking…" when the button’s words change is the reader’s own business. The suggestion taking the focus when it arrives is what tells them it is done.
Evidence
Where it's used
| Where | For |
|---|---|
| Somnia CMS | Search details, keywords, topics and related entries on a page; captions and descriptions for pictures, videos, documents and audio. |
What we saw, and what changed
| When | What we saw | What changed |
|---|---|---|
| Requests to Claude were made from links and plain buttons that looked like anything else. | One Suggest button and one card for what comes back, the same everywhere (1.59.0). | |
| While Claude worked the button was disabled, which can drop the keyboard’s focus for the seconds it takes. | It is marked busy and keeps the focus; a press while busy is ignored (1.87.0). |
From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.
What we don't know yet
- How often a suggestion is used as it comes, changed, or turned down is not counted: only that one was asked for, and what it cost.