clarify

$npx mdskill add educlopez/ui-craft/clarify

Reviews UX copy for clarity, specificity, and actionability.

  • Fixes vague, generic, or AI-sounding button labels and error messages.
  • Depends on the ui-craft skill for discovery and anti-slop tests.
  • Critiques by default; only applies changes when user says 'apply'.
  • Returns a table of copy diffs for buttons, errors, empty states, hints.

SKILL.md

.github/skills/clarifyView on GitHub ↗
---
name: clarify
description: "UX copy review across buttons, errors, empty states, and form hints — critiques by default, applies only on request. Use when copy feels vague, generic, or AI-sounding, or when the user says "fix the labels", "improve error messages", or "review the copy". Invoke when the user asks for clarify on their UI, or mentions 'clarify' alongside design / UI / frontend work."
---

<!-- HARNESS MIRROR — do not edit here. Canonical source: skills/ or commands/. After editing source, copy into cli/assets/<harness>/ and repo-root harness mirrors. -->

**Context:** this sub-skill is one lens of the broader `ui-craft` skill. If the `ui-craft` skill is also installed, read its SKILL.md first for Discovery + Anti-Slop + Craft Test, then apply the specific lens below.

Clarify the copy in the target the user described. Load the `ui-craft` skill.

**Default mode: critique, not edit.** Return the copy diff in a Review Format table. Only apply changes if the user says "apply".

**Checklist — walk the UI and flag every instance:**

1. **Button labels** — verb + object. "Send invite" > "Submit". "Delete project" > "Delete". Never "OK", "Submit", "Click here".
2. **Errors** — inline, specific, actionable. "Email already in use — sign in or use another address." Never "Something went wrong."
3. **Empty states** — one line explaining why empty + one CTA. "No projects yet. Create your first." not "It's empty here!"
4. **Form hints** — below the field, persistent, not just validation-triggered. "Must include a number and a symbol" as helper text, not as an error after submit.
5. **Confirmation language** — past tense, subject-first. "Project deleted." > "Successfully deleted project."
6. **Destructive actions** — the noun lives in the button. "Delete {projectName}" > "Delete". The dialog confirms; the button commits.
7. **Case** — sentence case by default. Title Case only for branded product names. Never ALL CAPS (exception: 11-13px category labels, already in SKILL.md).
8. **Voice** — clear > clever. Active voice. Short sentences. Real words ("cancel" not "discontinue", "start" not "initiate").

**Knob-agnostic** — clarity is not tunable. Run the full checklist regardless of CRAFT_LEVEL.

**References to read**: `references/copy.md` (microcopy voice + patterns), `references/accessibility.md` (error message expectations for screen readers).

**Output format** — the Review Format table:

| Before | After | Why |
| --- | --- | --- |

Prioritize by impact (errors and destructive actions first, then CTAs, then helper copy). End with a one-paragraph summary of the overall voice shift. If the user says "apply", edit the code and re-print the table with file paths.

More from educlopez/ui-craft

SkillDescription
adaptResponsive layout pass covering breakpoints, touch targets, safe areas, and fluid type. Use when the UI has layout or touch issues on mobile/tablet, when adding a new screen that hasn't been tested across viewports, or when the user says "make it responsive" / "fix mobile layout". Invoke when the user asks for adapt on their UI, or mentions 'adapt' alongside design / UI / frontend work.
animateMotion design pass — adds purposeful animations or removes excessive ones, respecting MOTION_INTENSITY and the project's animation stack. Use when the user asks to add animation, "make it feel smoother", fix janky transitions, or trim motion that's distracting. Invoke when the user asks for animate on their UI, or mentions 'animate' alongside design / UI / frontend work.
bolderAmplify personality — raises layout variance and motion, strengthens typography and one signature detail, without slop. Use when the UI works but feels safe, flat, or "template-y", or when the user says "bolder", "more personality", "more creative", or "make it pop" (still professional). Invoke when the user asks for bolder on their UI, or mentions 'bolder' alongside design / UI / frontend work.
colorizeColor strategy pass — introduces a single accent at 3-5 intentional placements, or reduces an over-colored UI back to 90% neutral. Use when the UI has no color identity, uses blue by default, or is shouting with too many competing accents. Invoke when the user asks for colorize on their UI, or mentions 'colorize' alongside design / UI / frontend work.
craftOne-shot build pipeline for a complete surface from an outcome recipe — inputs (or defaults) → composition → theme → build order → acceptance bar. Use when the user asks for a whole surface ("build me a dashboard", "hazme un dashboard") and expects a shippable result, not component-level help. Invoke when the user asks for craft on their UI, or mentions 'craft' alongside design / UI / frontend work.
critiqueDesign lens critique covering visual hierarchy, clarity, and anti-slop patterns — produces a findings table, no code edits unless asked. Use when the user wants a design review, says "what's wrong with this UI", or needs a second opinion before a handoff or presentation. Invoke when the user asks for critique on their UI, or mentions 'critique' alongside design / UI / frontend work.
delightDelight pass — adds one or two memorable micro-interactions (copy specificity, hover choreography, state transitions, one signature detail) without decoration or confetti. Use when the UI works but feels generic, or when the user says "make it feel special" / "add some personality". Invoke when the user asks for delight on their UI, or mentions 'delight' alongside design / UI / frontend work.
distillReduction pass — cuts content, structure, visuals, and dead code that doesn't answer a user question or drive an action, respecting CRAFT_LEVEL. Use when the UI feels cluttered, has too many CTAs, walls of text, or decorative noise, or when the user says "simplify this" / "it feels too busy". Invoke when the user asks for distill on their UI, or mentions 'distill' alongside design / UI / frontend work.
hardenProduction-readiness pass — audits and implements the full non-happy-path matrix: loading skeletons, empty states, error messages, partial data, i18n, offline, permissions, and first-run guidance. Use when preparing a surface for production or when the user says "it crashes on empty data" / "there's no loading state" / "harden this". Invoke when the user asks for harden on their UI, or mentions 'harden' alongside design / UI / frontend work.
heuristicProduce a scored heuristic critique of the UI using Nielsen's 10 + 6 design laws + optional persona walkthroughs. Outputs a machine-parseable scorecard plus a 0-100 UsabilityScore (the judged companion to the deterministic UICraftScore). Invoke when the user asks for heuristic on their UI, or mentions 'heuristic' alongside design / UI / frontend work.