microcopy

<objective> Write microcopy strings for software product UI. Output is one or more short strings (rarely > 20 words each) that match the place they appear: button, error, empty state, tooltip, helper text, modal, onboarding card.

Use when the user wants to fill a UI element with text. The skill picks the right register (default: friendly-professional, no jargon, no slang), the right length budget per element type, and applies the universal rules: plain language, action-oriented, never blame the user, never use jargon.

This skill does NOT:

• write marketing landing pages (different scale + register)
• write technical documentation (use essay-write for longer-form docs)
• design layouts or component structures (use a design tool)
• write cold outreach (use cold-email)</objective>

ROLE

Read the request → identify UI element type → check length budget → write the string(s) → run universal rules check → return paste-ready text.

PIPELINE

1. Identify element type. From the request: button / error message / empty state / tooltip / helper text / modal / 404-500-offline page / onboarding card / inline alert / toast notification. Each has different length budget and tone — see references/element-types.md.

2. Identify context. What's around the element? What did the user just do (or fail to do)? What's the next action they can take? Microcopy without context is decorative; with context, it's load-bearing.

3. Apply length budget. See references/length-budgets.md:

   • Button label: ≤ 8 words (most: 1-3 words)
   • Tooltip: ≤ 12 words
   • Error message: 1 sentence (≤ 20 words)
   • Helper text: 1 short sentence
   • Empty state heading: ≤ 6 words; body: ≤ 25 words
   • Modal title: ≤ 8 words; body: ≤ 50 words

4. Apply universal rules — see references/rules.md:

   • Plain language (8th-grade reading level)
   • Action-oriented (verb first when possible)
   • Never blame the user ("Your input is wrong" ❌ → "This email is missing the @" ✅)
   • Never use jargon (system-level, not user-level)
   • Be specific (don't say "an error occurred" — say what failed)
   • Always offer next step (what should the user DO?)

5. Pick voice. Default: friendly-professional (see references/voice-by-product-type.md for adjustments). Override only if user names a different brand voice.

6. Run writer — but delete the water, not the function. Microcopy is almost entirely function: the next step, the recovery action, the button verb. Writer's default treatment is deletion, and at this length a single deleted clause can remove the only actionable thing on screen. Treat functional elements by replacement or simplification instead. After the pass, verify the next step is still stated. See forbidden-substitutions.md in the writer skill.

7. Output. One or multiple strings (if alternatives are useful), each formatted for paste. If error → also include the structured form: code, title, body, action.

MODES

• microcopy <element-type> for <context> — write a single string
• microcopy --variants 3 <element-type> — return 3 alternatives in different registers (e.g. casual / friendly / minimal)
• microcopy error <error-context> — structured error: title + body + primary action
• microcopy empty-state <context> — structured empty state: heading + body + primary CTA + secondary
• microcopy 404 / 500 / offline / maintenance — full-page error
• microcopy --improve <existing-string> — rewrite a weak existing string with notes on why

REFERENCES (load on demand)

File	When to load
references/element-types.md	Identifying element type — full taxonomy with examples per type
references/length-budgets.md	Checking budget — exact word and character limits per type
references/rules.md	Applying the 10 universal rules (plain language, action verbs, no blame, no jargon, etc.)
references/voice-by-product-type.md	Picking voice — adjustments for SaaS / dev tool / fintech / e-commerce / consumer / B2B
references/banned-words.md	Strip list — words that mark text as low-quality microcopy (jargon, hedge words, robot-speak)

EXAMPLES

See examples/before-after.md — 10 calibration pairs covering errors, buttons, empty states, tooltips, 404 pages.

CONSTRAINTS

• Never blame the user. Always frame as "this didn't happen" not "you did it wrong".
• Never use jargon. "Authentication failed" → "We couldn't sign you in".
• Always offer next step. Error tells what failed AND what to do. Empty state tells what's missing AND what to add.
• Use sentence case for buttons. "Save changes" not "Save Changes" (unless the brand specifically uses title case).
• No exclamation marks for routine actions. Reserved for genuine celebrations (signup complete, first achievement). Default tone is calm.
• No emojis in errors. They look infantilizing. OK in achievement / onboarding microcopy if brand allows.
• Be specific about what failed. "Server error" ❌ → "We couldn't reach our servers — check your connection or try again in a minute" ✅
• Don't use technical codes user-facing. "HTTP 500" stays in the dev console; user sees friendly explanation.
• Plural / singular careful. "1 item selected" not "1 items selected". Most i18n libraries handle this; check the platform.
• Localizable. Avoid puns, idioms, culture-specific references unless the product is single-locale.

INVOCATION HINTS

When the user says any of:

• "write / rewrite an error message for..."
• "empty state copy for..."
• "tooltip wording / helper text for..."
• "button label / button copy"
• "404 / 500 / offline page text"
• "onboarding text / card copy"
• "modal title / modal body"
• "toast notification text"
• "inline alert wording"

RU triggers (use the skill when the user writes any of):

• «текст ошибки / сообщение об ошибке / напиши ошибку для ...»
• «empty state на русском / пустое состояние / "ничего не найдено"»
• «лейбл для кнопки / надпись на кнопке / текст кнопки»
• «тултип / подсказка при наведении / hover-текст»
• «404 / 500 / страница "оффлайн" на русском»
• «онбординг-карточка / текст для туториала»
• «текст модалки / заголовок модального окна»
• «уведомление / toast / поп-ап текст»
• «перепиши эту микрокопию короче»

For RU patterns per UI element (typography «ёлочки», обращение «вы», friendly vs formal register), see references/element-types.md section RU patterns per element.

Use this skill. For longer-form (landing page sections, marketing copy) → not this skill; use essay-write or a marketing-specific skill.

If user wants register/tone shift of EXISTING microcopy — pair with tone-shifter (e.g. shift formal → friendly).