npm - @bastani/atomic - Versions diffs - 0.9.11-alpha.6 → 0.9.11-alpha.8 - Mend

@bastani/atomic 0.9.11-alpha.6 → 0.9.11-alpha.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (452) hide show

package/dist/builtin/workflows/skills/impeccable/reference/clarify.md CHANGED Viewed

@@ -1,288 +1,94 @@
-> **Additional context needed**: audience technical level and users' mental state in context.
+> **Additional context needed**: audience knowledge and emotional state.
-Find the unclear, confusing, or poorly written interface text and rewrite it. Vague copy creates support tickets and abandonment; specific copy gets users through the task.
+Rewrite unclear interface text so users understand what happened, what matters, and what to do next. Preserve factual meaning, product terminology, and brand voice.
+## Audit the language
----
+Read the entire interaction path, not isolated strings. Identify:
-## Assess Current Copy
+- ambiguous nouns, verbs, and actions;
+- internal jargon or assumed knowledge;
+- vague labels, outcomes, and system states;
+- missing consequences, recovery, or timing;
+- inconsistent terminology and capitalization;
+- redundant headings, intros, helper text, and confirmations;
+- text that breaks at realistic widths or in translation;
+- tone that ignores stress, risk, success, or urgency.
-Identify what makes the text unclear or ineffective:
+Infer audience and task from product context and surrounding UI. Ask before changing factual claims, legal meaning, or a term that may be domain-specific.
-1. **Find clarity problems**:
-   - **Jargon**: Technical terms users won't understand
-   - **Ambiguity**: Multiple interpretations possible
-   - **Passive voice**: "Your file has been uploaded" vs "We uploaded your file"
-   - **Length**: Too wordy or too terse
-   - **Assumptions**: Assuming user knowledge they don't have
-   - **Missing context**: Users don't know what to do or why
-   - **Tone mismatch**: Too formal, too casual, or inappropriate for situation
+## Set the message hierarchy
-2. **Understand the context**:
-   - Who's the audience? (Technical? General? First-time users?)
-   - What's the user's mental state? (Stressed during error? Confident during success?)
-   - What's the action? (What do we want users to do?)
-   - What's the constraint? (Character limits? Space limitations?)
+For each state, decide:
-**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.
+1. the one fact the user needs now;
+2. the action available next;
+3. supporting context that changes the decision;
+4. the appropriate tone for this moment.
-## Plan Copy Improvements
+Say each idea once. If the heading already explains the state, the introduction should add new information or disappear.
-Create a strategy for clearer communication:
+## Rewrite by function
-- **Primary message**: What's the ONE thing users need to know?
-- **Action needed**: What should users do next (if anything)?
-- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)
-- **Constraints**: Length limits, brand voice, localization considerations
+### Actions and navigation
-**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.
+Use a specific verb and object when the outcome is not already obvious. Labels should describe what will happen, not the gesture used to trigger it. Keep the same noun and verb for the same concept throughout the product.
-## Improve Copy Systematically
+For destructive actions, name the object and consequence. Prefer undo over confirmation when recovery is safe. When confirmation is necessary, name the action on both the message and button instead of using `Yes`, `No`, `OK`, or `Submit`.
-Refine text across these common areas:
+### Forms
-### Error Messages
-**Bad**: "Error 403: Forbidden"
-**Good**: "You don't have permission to view this page. Contact your admin for access."
+Use persistent labels; placeholders are examples, not labels. Put format and eligibility requirements before submission. Explain why information is requested only when it is not obvious. Required and optional treatment should be consistent.
-**Bad**: "Invalid input"
-**Good**: "Email addresses need an @ symbol. Try: name@example.com"
+Validation says what needs attention and how to correct it without blaming the user. Keep related instructions near the field and announce errors accessibly.
-**Principles**:
-- Explain what went wrong in plain language
-- Suggest how to fix it
-- Don't blame the user
-- Include examples when helpful
-- Link to help/support if applicable
-### Form Labels & Instructions
-**Bad**: "DOB (MM/DD/YYYY)"
-**Good**: "Date of birth" (with placeholder showing format)
-**Bad**: "Enter value here"
-**Good**: "Your email address" or "Company name"
-**Principles**:
-- Use clear, specific labels (not generic placeholders)
-- Show format expectations with examples
-- Explain why you're asking (when not obvious)
-- Put instructions before the field, not after
-- Keep required field indicators clear
-### Button & CTA Text
-**Bad**: "Click here" | "Submit" | "OK"
-**Good**: "Create account" | "Save changes" | "Got it, thanks"
+### Errors and permissions
-**Principles**:
-- Describe the action specifically
-- Use active voice (verb + noun)
-- Match user's mental model
-- Be specific ("Save" is better than "OK")
+An actionable error answers:
-### Help Text & Tooltips
-**Bad**: "This is the username field"
-**Good**: "Choose a username. You can change this later in Settings."
+1. what failed;
+2. why, when known and useful;
+3. how to recover or what alternative remains.
-**Principles**:
-- Add value (don't just repeat the label)
-- Answer the implicit question ("What is this?" or "Why do you need this?")
-- Keep it brief but complete
-- Link to detailed docs if needed
+Do not expose internal codes as the primary message. Do not promise a cause or resolution the system cannot know. Treat privacy, payment, deletion, access loss, and blocked work seriously; warmth is welcome, jokes are not.
-### Empty States
-**Bad**: "No items"
-**Good**: "No projects yet. Create your first project to get started."
+### Loading, empty, and success states
-**Principles**:
-- Explain why it's empty (if not obvious)
-- Show next action clearly
-- Make it welcoming, not dead-end
+Loading text names the real operation and sets an honest expectation when the wait is meaningful. Show determinate progress when available; never invent progress.
-### Success Messages
-**Bad**: "Success"
-**Good**: "Settings saved! Your changes will take effect immediately."
+An empty state distinguishes first use, no results, filters, permissions, and failure. Explain the state and provide the next useful action.
-**Principles**:
-- Confirm what happened
-- Explain what happens next (if relevant)
-- Be brief but complete
-- Match the user's emotional moment (celebrate big wins)
-### Loading States
-**Bad**: "Loading..." (for 30+ seconds)
-**Good**: "Analyzing your data... this usually takes 30-60 seconds"
-**Principles**:
-- Set expectations (how long?)
-- Explain what's happening (when it's not obvious)
-- Show progress when possible
-- Offer escape hatch if appropriate ("Cancel")
+Success confirms the completed outcome and mentions the next consequence only when it changes what the user should do. Routine success should be brief.
-### Confirmation Dialogs
-**Bad**: "Are you sure?"
-**Good**: "Delete 'Project Alpha'? This can't be undone."
+### Help and instructional text
-**Principles**:
-- State the specific action
-- Explain consequences (especially for destructive actions)
-- Use clear button labels ("Delete project" not "Yes")
-- Don't overuse confirmations (only for risky actions)
+Helper text answers an implicit question instead of restating the control. Use progressive disclosure for uncommon detail. Link text must make sense out of context; icon-only controls need accessible names.
-### Navigation & Wayfinding
-**Bad**: Generic labels like "Items" | "Things" | "Stuff"
-**Good**: Specific labels like "Your projects" | "Team members" | "Settings"
+## Voice, accessibility, and localization
-**Principles**:
-- Be specific and descriptive
-- Use language users understand (not internal jargon)
-- Make hierarchy clear
-- Consider information scent (breadcrumbs, current location)
+Voice stays consistent; tone adapts to the moment. Use plain language without flattening terminology the audience genuinely knows.
-## Apply Clarity Principles
+- Write complete translatable messages rather than concatenated fragments.
+- Keep variables and numbers structured so translators can reorder them.
+- Allow expansion instead of abbreviating prematurely.
+- Make alt text convey the image's information; use empty alt for decoration.
+- Keep screen-reader names aligned with visible labels and outcomes.
+- Do not rely on punctuation, color, or iconography to carry the message alone.
-Every piece of copy should follow these rules:
+Maintain a short terminology glossary when inconsistency spans the product. Do not vary words for literary effect in an interface.
-1. **Be specific**: "Enter email" not "Enter value"
-2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity)
-3. **Be active**: "Save changes" not "Changes will be saved"
-4. **Be human**: "Oops, something went wrong" not "System error encountered"
-5. **Tell users what to do**, not just what happened
-6. **Be consistent**: Use same terms throughout (don't vary for variety)
+## Verify
-**NEVER**:
-- Use jargon without explanation
-- Blame users ("You made an error" → "This field is required")
-- Be vague ("Something went wrong" without explanation)
-- Use passive voice unnecessarily
-- Write overly long explanations (be concise)
-- Use humor for errors (be empathetic instead)
-- Assume technical knowledge
-- Vary terminology (pick one term and stick with it)
-- Repeat information (headers restating intros, redundant explanations)
-- Use placeholders as the only labels (they disappear when users type)
+Read the flow in context and test:
-## Verify Improvements
+- comprehension without hidden product knowledge;
+- actionability at errors, empty states, and decision points;
+- factual accuracy and consistent terminology;
+- scanability at target widths and 200% zoom;
+- long names, localization expansion, pluralization, and dynamic values;
+- accessible names and announced state changes;
+- tone appropriate to consequence and emotional context.
-Test that copy improvements work:
+The final copy is as short as it can be without removing meaning or recovery.
-- **Comprehension**: Can users understand without context?
-- **Actionability**: Do users know what to do next?
-- **Brevity**: Is it as short as possible while remaining clear?
-- **Consistency**: Does it match terminology elsewhere?
-- **Tone**: Is it appropriate for the situation?
-When the copy reads cleanly, hand off to `$impeccable polish` for the final pass.
----
-## Reference Material
-The sections below were previously `ux-writing.md` and live inline now so the clarify flow has its deep UX-writing reference in one place.
-### UX Writing
-#### The Button Label Problem
-**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
-| Bad | Good | Why |
-|-----|------|-----|
-| OK | Save changes | Says what will happen |
-| Submit | Create account | Outcome-focused |
-| Yes | Delete message | Confirms the action |
-| Cancel | Keep editing | Clarifies what "cancel" means |
-| Click here | Download PDF | Describes the destination |
-**For destructive actions**, name the destruction:
-- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
-- "Delete 5 items" not "Delete selected" (show the count)
-#### Error Messages: The Formula
-Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".
-##### Error Message Templates
-| Situation | Template |
-|-----------|----------|
-| **Format error** | "[Field] needs to be [format]. Example: [example]" |
-| **Missing required** | "Please enter [what's missing]" |
-| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
-| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
-| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
-##### Don't Blame the User
-Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".
-#### Empty States Are Opportunities
-Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".
-#### Voice vs Tone
-**Voice** is your brand's personality, consistent everywhere.
-**Tone** adapts to the moment.
-| Moment | Tone Shift |
-|--------|------------|
-| Success | Celebratory, brief: "Done! Your changes are live." |
-| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
-| Loading | Reassuring: "Saving your work..." |
-| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
-**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
-#### Writing for Accessibility
-**Link text** must have standalone meaning: "View pricing plans" not "Click here". **Alt text** describes information, not the image: "Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
-#### Writing for Translation
-##### Plan for Expansion
-German text is ~30% longer than English. Allocate space:
-| Language | Expansion |
-|----------|-----------|
-| German | +30% |
-| French | +20% |
-| Finnish | +30-40% |
-| Chinese | -30% (fewer chars, but same width) |
-##### Translation-Friendly Patterns
-Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.
-#### Consistency: The Terminology Problem
-Pick one term and stick with it:
-| Inconsistent | Consistent |
-|--------------|------------|
-| Delete / Remove / Trash | Delete |
-| Settings / Preferences / Options | Settings |
-| Sign in / Log in / Enter | Sign in |
-| Create / Add / New | Create |
-Build a terminology glossary and enforce it. Variety creates confusion.
-#### Avoid Redundant Copy
-If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
-#### Loading States
-Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
-#### Confirmation Dialogs: Use Sparingly
-Most confirmation dialogs are design failures; consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
-#### Form Instructions
-Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.
----
-**Avoid**: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.
+When the language reads cleanly, hand off to `$impeccable polish` for the final pass.