SuggestionCard
StableOne writing suggestion with its type, the before and after, a reason, and Accept and Dismiss buttons.
Also known as writing suggestion, edit suggestion
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
Try it
Original: in order to be able to Suggested: to
Shorter phrasing says the same thing.
<SuggestionCard category="clarity" original="in order to be able to" suggestion="to"
explanation="Shorter phrasing says the same thing."
onAccept={() => accept()} onDismiss={() => dismiss()} />Accept or dismiss to see the result. The card shows one suggestion, like when you click an underlined phrase.
When to use it
Shows one writing suggestion with its type, the original crossed out next to the new text, and a short reason. One card per suggestion keeps each decision small.
Made of: Type label with icon · Original text · Suggested text · Reason · Accept · Dismiss
Use it for
- A spelling, grammar, clarity or tone fix for a phrase.
- A suggestion opened from an underlined phrase in the text.
Not for
- A whole AI draft: use SuggestionBar.
- A suggested ending to the line being typed: use GhostText.
Do and avoid
Original: at this point in time Suggested: now
Shorter and easier to read.
Original: Thanks for your order. We will send it soon and you will get it in a few days, we hope. Suggested: Thanks for your order. It ships on Monday and should arrive by Thursday. We will email you the tracking link.
Do
- Show one suggestion per card.
- Keep the explanation to a sentence.
- When you add a type, give it both a label and an icon.
- After Accept or Dismiss, move the cursor to the next suggestion or back to the text.
Avoid
- Do not tell types apart by color alone.
- Do not accept just because someone pointed at it or tabbed to it.
- Do not use it for a whole draft. Use SuggestionBar.
On a phone
- The card fills the width up to 384px, so it fills a phone and does not grow on a tablet.
- Accept and Dismiss keep their size and have a 44px tap area on touch screens.
- The original and the suggestion wrap as one paragraph.
Seen in products
- Grammarly underlines spans. Clicking one opens a card with one suggestion plus accept and dismiss.
- Grammarly underline colors map to categories: red correctness, blue clarity, green engagement and purple tone. It also has dynamic, document-specific categories.
- Apple Proofread shows edits with explanations the user can accept.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| category | "correctness" | "clarity" | "engagement" | "tone" | "correctness" | Picks the default label, icon and badge tone. |
| categoryLabel | string | none | Replaces the category text, for document-specific categories. |
| categoryIcon | ReactNode | none | Replaces the category icon. |
| originalrequired | string | none | Text as written, shown struck through. |
| suggestionrequired | string | none | Proposed replacement. An empty string shows (remove). |
| explanation | string | none | Short reason for the change. |
| onAccept / onDismiss | () => void | none | Resolve the suggestion. |
| acceptLabel / dismissLabel | string | "Accept" / "Dismiss" | Button text. |
| className | string | none | Extra classes on the card. |
"Show code under the preview gives the code for the example on the stage."
In Figma
In Figma, one SuggestionCard switches all of this from its properties panel, across 4 variants. Each property sets the React prop beside it, so design and code use the same names.
| Figma property | React | Values |
|---|---|---|
| Category | category | Correctness, Clarity, Engagement, Tone |
| Original | original | Any text |
| Suggestion | suggestion | Any text |
| Explanation | explanation | Any text |
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- category
- Set category to correctness, clarity, engagement or tone to change the badge colour and icon.
- removal
- When suggestion is empty, the card shows (remove) in place of the new text.
- focus
- Accept and Dismiss show a focus ring on keyboard focus.
Tokens
Change one of these and every part that uses it follows.
--surface--border--lime--danger--fg-muted--radius-card
Built in
- The card is named by its type, such as "Clarity suggestion".
- The type is a word plus an icon. Color is only extra.
- Hidden words say "Original" and "Suggested" before each text, because screen readers may not mention crossed-out text.
- Accept and Dismiss are real buttons.
- After Accept or Dismiss, keyboard focus moves to the next suggestion, else the previous one, else the text. Pass focusAfter to choose another place.
What you need to do
- When you add your own type, give it both a categoryLabel and a categoryIcon, so it never relies on color.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide