sf-lwc-content

name: sf-lwc-content description: > Microcopy and UI writing patterns for Lightning Web Components. Covers error message structure, empty state copy, button labels, help text, confirmation dialogs, placeholder text, toast messages, and internationalization-ready string patterns. Use when writing UI text, error messages, labels, help text, or when the user mentions microcopy, UX writing, content design, error messages, empty states, or button labels. license: MIT metadata: version: "1.0.0" author: "Brendan Sheridan" scoring: "100 points across 6 categories"

sf-lwc-content: Microcopy and UI Writing for LWC

The words inside a component matter as much as the visual design. Write clear, helpful, human UI text that guides users and reduces confusion.

Core Principles

1. Clear over clever — say exactly what happened and what to do next
2. Active voice — "Save the record" not "The record will be saved"
3. Verb-first buttons — "Create Account" not "Account Creation"
4. No jargon — "Something went wrong" not "Null pointer exception in line 42"
5. Consistent terminology — pick one word and use it everywhere

Error Messages

Structure: What + Why + What to Do

Every error message answers three questions:

┌─────────────────────────────────────────────┐
│  WHAT happened    │ "Record couldn't be saved"
│  WHY it happened  │ "Required fields are missing"
│  WHAT TO DO next  │ "Fill in Account Name and click Save again"
└─────────────────────────────────────────────┘

Error Templates

Error in Code

get userFriendlyError() {
    if (!this._error) return '';
    if (this._error.body?.message) {
        return this._error.body.message;
    }
    return 'Something went wrong. Try again, or contact your admin if the problem continues.';
}

Anti-Patterns

Empty States

Empty states are opportunities to guide users, not dead ends.

Structure: Explain + Guide + Act

┌─────────────────────────────────────────────┐
│           [Icon or illustration]             │
│                                             │
│     No {items} yet                          │  ← Explain
│     {Why this is empty or what items are}   │  ← Guide
│     [Create {Item}]                         │  ← Act
└─────────────────────────────────────────────┘

Empty State Templates

Button Labels

Rules

• Verb first: Save Record, Create Contact, Send Email
• Specific over generic: Save Changes not Submit, Delete Account not OK
• Match the action: the button label should describe what happens when clicked
• Destructive actions: use the verb that matches (Delete, Remove, Disconnect)

Common Pairs

Anti-Patterns

Help Text and Tooltips

When to Use

Help Text Templates

Accessibility Note

Tooltips must be keyboard-accessible. Use aria-describedby to link help text to its field:

<lightning-input
    label="Annual Revenue"
    field-name="AnnualRevenue"
    aria-describedby="revenue-help">
</lightning-input>
<div id="revenue-help" class="help-text">
    Enter the company's total annual revenue in USD.
</div>

Confirmation Dialogs

Structure: Consequence + Specific Action

┌─────────────────────────────────────────────┐
│  Delete this account?                        │  ← Question (what will happen)
│                                             │
│  This will permanently delete "Acme Corp"   │  ← Consequence
│  and all related contacts and cases.         │
│  This action can't be undone.               │
│                                             │
│        [Cancel]    [Delete Account]          │  ← Specific labels
└─────────────────────────────────────────────┘

Templates

Toast Messages

Format

// Success: past tense, brief
{ title: 'Account saved', message: 'Your changes have been saved.', variant: 'success' }

// Error: what happened + what to do
{ title: 'Couldn\'t save record', message: 'Check required fields and try again.', variant: 'error' }

// Warning: what to be aware of
{ title: 'Limited results', message: 'Showing first 200 records. Refine your search.', variant: 'warning' }

// Info: neutral notification
{ title: 'Record updated', message: 'Changes made by another user have been loaded.', variant: 'info' }

Rules

• Title: 2-4 words, sentence case
• Message: 1 sentence, actionable for errors
• Success toasts: optional message (title alone is often sufficient)
• Error toasts: always include a message with guidance

Placeholder Text

Rules

• Placeholders are examples, not labels — never replace a label with a placeholder
• Use realistic examples: Search accounts... not Type here
• Keep short: max 30-40 characters

Templates

Internationalization Readiness

String Patterns

• Never concatenate translated strings — word order varies by language
• Use Custom Labels for all user-facing text
• Allow 40% expansion for translated text (German/French are longer than English)
• Avoid text in images — it can't be translated

import SAVE_LABEL from '@salesforce/label/c.Save_Changes';
import ERROR_TITLE from '@salesforce/label/c.Error_Title';

export default class MyComponent extends LightningElement {
    labels = { SAVE_LABEL, ERROR_TITLE };
}

<lightning-button label={labels.SAVE_LABEL}></lightning-button>

Scoring Rubric (100 Points)

Cross-Skill Integration