Home/Catalog/Clarity
Clarity — is it understood?
Brief 148

UI Microcopy & Labeling Audit

The words inside the interface — buttons, labels, tooltips, placeholders, helper text — do they say what happens next in plain language, or leave the user guessing?

MICROCOPY.md4 phases7 lenses~3.4k chars

Free & open · no signup · read-only — it ends by asking · nothing leaves your machine

What it does

You are working inside this repo. Mission: audit the small words that run the interface — button labels, field labels, tooltips, placeholders, helper text, confirmations, toasts — and find the ones that are vague, jargon-y, or leave the user guessing what happens next. This is the product's own words, not its marketing voice (17 covers that).

Read-only pass. Read the components, templates, and strings the UI renders, and run the app to see them in place; your only write is the report file.

What it looks for

7 lenses it looks through

Phase 2 sweeps the codebase through every one of these, citing file and line for each finding.

1

Says what happens

buttons name the action and its result ("Delete 3 files"), not "OK", "Submit", or "Yes"; the label that hides the outcome

2

Plain language

user words, not system or org jargon; the acronym, the internal codename, the database column surfaced as a label

3

Placeholder abuse

placeholders standing in for labels (gone the moment you type), or holding instructions the user needs while filling the field

4

Helper where it helps

the hint sits before the mistake, not only in the error after; format and requirements stated up front

5

Consistent terms

one name per concept across the UI; "delete" here, "remove" there, "archive" elsewhere for the same act

6

Tone & length

concise, calm, and human within the space; the paragraph on a button, the cute label that obscures

7

Honest confirmation

dialogs and toasts that name what happened or will happen, with an undo where truth allows, instead of a bare "Success"

The deliverable

What lands in your repo

One structured report at the repo root — or in reports/, if you keep one — the same shape every time, ready for a teammate — or the optional Studio — to act on.

MICROCOPY.md
1
String findings
each: lens · location · current text · the rewrite
2
Term glossary
the one word this product should use per concept, with the variants to retire
3
High-stakes labels
the destructive and irreversible actions to reword first
4
The voice rules
the handful of microcopy conventions (verbs on buttons, format hints up front) this codebase should adopt
One file. Evidence-backed. It ends by asking before touching anything.
How it works

What it makes the agent do

Every Goal Prompt follows the same four steps, so results are consistent and repeatable — no matter which one you run.

1
Phase 1

Gather the strings

Collect the interface microcopy.

2
Phase 2

Audit through 7 lenses

Cite the string and its location for every finding.

3
Phase 3

Curate

Rank by stakes × frequency.

4
Phase 4

Report

Create MICROCOPY.md at repo root.

Get started

Three ways to run this Goal Prompt

01 · COPY

Paste it in

Copy it and paste it into your agent inside the repo you want checked.

02 · INSTALL

As a slash command

Install the goal plugin once — two commands — then just type /goal:ui-microcopy.

1/plugin marketplace add GhostlyGawd/goal-prompts
2/plugin install goal@goal-prompts

Or install only this Goal Prompt as /goal-ui-microcopy:

curl -fsSL https://goal-prompts.vercel.app/install | BRIEF=148 sh
03 · AGENT

From an agent (MCP)

Let an agent fetch it mid-conversation, or pull the raw Goal Prompt by URL.

https://goal-prompts.vercel.app/raw/148.md
Transparency

The exact prompt

Nothing hidden — this is the whole Goal Prompt, verbatim. Read it in a minute, edit it, or copy it as-is.

Read the full brief (3,405 characters)
# Goal: UI Microcopy & Labeling Audit

You are working inside this repo. Mission: audit the small words that run the interface — button labels, field labels, tooltips, placeholders, helper text, confirmations, toasts — and find the ones that are vague, jargon-y, or leave the user guessing what happens next. This is the product's own words, not its marketing voice (17 covers that).

Read-only pass. Read the components, templates, and strings the UI renders, and run the app to see them in place; your only write is the report file.

## Phase 1 — Gather the strings
- Collect the interface microcopy: primary and secondary button labels, form labels and help, placeholders, tooltips, confirmation dialogs, toasts, section headings, nav items.
- Note where the strings live (components, i18n files, hardcoded) and whether they are centralized or scattered.
- Flag the highest-stakes words: the labels on destructive, paid, or irreversible actions.

## Phase 2 — Audit through 7 lenses
Cite the string and its location for every finding.
1. **Says what happens** — buttons name the action and its result ("Delete 3 files"), not "OK", "Submit", or "Yes"; the label that hides the outcome
2. **Plain language** — user words, not system or org jargon; the acronym, the internal codename, the database column surfaced as a label
3. **Placeholder abuse** — placeholders standing in for labels (gone the moment you type), or holding instructions the user needs while filling the field
4. **Helper where it helps** — the hint sits before the mistake, not only in the error after; format and requirements stated up front
5. **Consistent terms** — one name per concept across the UI; "delete" here, "remove" there, "archive" elsewhere for the same act
6. **Tone & length** — concise, calm, and human within the space; the paragraph on a button, the cute label that obscures
7. **Honest confirmation** — dialogs and toasts that name what happened or will happen, with an undo where truth allows, instead of a bare "Success"

## Phase 3 — Curate
- Rank by stakes × frequency: a vague label on a destructive or high-traffic action outranks a stiff tooltip seen once.
- Separate "unclear", "jargon", "inconsistent term", and "placeholder-as-label".
- For each, name the string, where it lives, and the rewrite.

## Phase 4 — Report
Create `MICROCOPY.md` at repo root:
1. **String findings** — each: lens · location · current text · the rewrite
2. **Term glossary** — the one word this product should use per concept, with the variants to retire
3. **High-stakes labels** — the destructive and irreversible actions to reword first
4. **The voice rules** — the handful of microcopy conventions (verbs on buttons, format hints up front) this codebase should adopt

Start the report with today's date. If `MICROCOPY.md` already exists from a previous run, read it first and lead with what changed since.

## Rules
- Every finding quotes the current string and gives the exact rewrite
- A button should name its action; if the label could be "OK", it is not done
- No user-facing interface copy in this repo? Say so in a one-paragraph null report and stop — a null result is a valid finding.
- If a `reports/` directory exists at the repo root, write the report there instead of the root.
- Before asking, present the top findings as a ranked list in plain words
- Report only — end by asking which strings to rewrite first

House rules for this Goal Prompt

  • Every finding quotes the current string and gives the exact rewrite
  • A button should name its action; if the label could be "OK", it is not done
  • No user-facing interface copy in this repo? Say so in a one-paragraph null report and stop — a null result is a valid finding.
  • If a reports/ directory exists at the repo root, write the report there instead of the root.
  • Before asking, present the top findings as a ranked list in plain words
  • Report only — end by asking which strings to rewrite first
Keep exploring

Pairs well with

Curated neighbors — briefs that answer the adjacent question, worth running in the same session.

More Clarity briefs

Runs inside these playbooks — curated sequences you can launch with one paste: