@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/cursor/ux-internationalization-writing/SKILL.md

@@ -0,0 +1,196 @@
+# Writing for Internationalization
+
+> Writing for internationalization — source strings that survive translation, concatenation traps, pluralization, date and number references
+
+## When to Use
+
+- Writing source strings for any product that will be translated or localized
+- Designing UI text that includes dynamic values -- numbers, dates, currencies, usernames
+- Building features with pluralized counts ("1 item" vs "2 items" vs "5 items")
+- Reviewing existing UI text for translation-readiness before a localization effort
+- Writing strings for apps that must support right-to-left (RTL) languages like Arabic or Hebrew
+- Creating templates for dynamic content that will be interpolated with variables
+- Auditing a codebase for hardcoded strings that should be externalized
+- NOT for: string extraction tooling and i18n library configuration (covered by engineering skills)
+- NOT for: locale-specific content creation (marketing copy for specific markets)
+- NOT for: right-to-left layout design (that is a design skill, not a writing skill)
+
+## Instructions
+
+1. **Never concatenate strings to build sentences.** This is the most common and most damaging i18n mistake. In English, "Welcome, " + name + "!" works. In German, the greeting might need the name in a different position. In Japanese, the sentence structure is completely different. Every concatenation is a translation blocker. Use template variables with complete sentences: `"Welcome, {name}!"` where the entire string including the variable position can be rearranged by translators. Airbnb's style guide mandates complete-sentence templates: `"{host_name} is a Superhost"` not `name + " is a " + badge_type`.
+
+2. **Use ICU MessageFormat for pluralization.** English has two plural forms (singular and plural): "1 item" and "2 items." But Arabic has six plural forms. Polish has four. Russian has three. The naive approach -- `count === 1 ? "item" : "items"` -- breaks in every language except English. ICU MessageFormat handles all plural forms:
+
+   ```
+   {count, plural,
+     =0 {No items}
+     one {{count} item}
+     other {{count} items}
+   }
+   ```
+
+   Translators can add the plural forms their language requires (zero, one, two, few, many, other) without changing code. The Unicode CLDR defines which counts map to which plural category for every language. Never implement pluralization logic in application code -- delegate it to the i18n library.
+
+3. **Do not embed UI text in code.** Every user-visible string must be in a resource file, even strings that seem too simple to externalize: "OK," "Cancel," "Error," "Loading..." These simple strings still need translation. A codebase where most strings are externalized but "OK" is hardcoded forces translators to miss it, resulting in a partially translated interface. Android's resource system enforces this: every string goes in `strings.xml`. React-intl and next-intl follow the same pattern. The rule: if a user can see it, it must be in the resource file.
+
+4. **Keep sentences complete and self-contained.** Translators work with individual strings, not with the full UI context. A string that says "and 3 more" is untranslatable without knowing what comes before it. The translator does not know if "3 more" refers to people, files, messages, or errors. Make every string a complete thought: "and 3 more files" or, better, "{count} more files." Provide translator comments that explain the context: "Shown below a list of files when more files exist than are displayed."
+
+5. **Avoid positional humor, puns, and wordplay.** Humor rarely survives translation because it depends on language-specific features: double meanings, homophones, cultural references, and rhythm. Google's "I'm Feeling Lucky" button required creative adaptation in every locale -- some translations abandoned the pun entirely and used a culturally equivalent phrase. Slack's playful loading messages ("Herding cats...") are untranslatable in most languages because the idiom does not exist. The rule: if the humor depends on English-language wordplay, it will not translate. Use direct language instead, or mark humor strings as "do not translate literally -- adapt for local culture."
+
+6. **Design for text expansion.** Translated text is almost always longer than English source text. German is approximately 30% longer. Finnish can be 40% longer. Arabic and Hebrew may be 25% longer. UI elements must accommodate this expansion without breaking layouts:
+
+   | Source Language | Target Language | Average Expansion |
+   | --------------- | --------------- | ----------------- |
+   | English         | German          | +30%              |
+   | English         | French          | +20%              |
+   | English         | Spanish         | +25%              |
+   | English         | Finnish         | +30-40%           |
+   | English         | Japanese        | -10% (characters) |
+   | English         | Chinese         | -30% (characters) |
+   | English         | Arabic          | +25%              |
+   | English         | Russian         | +20%              |
+
+   Button labels should have 30% extra space. Tooltips should not be width-constrained. Table columns should use flexible widths. If a button says "Save" (4 characters) in English, the German translation "Speichern" (10 characters) must fit. Design with the longest expected translation, not the English source.
+
+7. **Reference dates, times, and currencies with format tokens.** Never hardcode date formats, time formats, or currency symbols in strings. `"March 15"` is American English. The same date is `"15 March"` in British English, `"15. März"` in German, and `"3月15日"` in Japanese. Use format tokens: `"{date}"` or `"{date, date, medium}"` in ICU MessageFormat. The i18n library and the user's locale determine the display format. The same applies to currencies: `"{price}"` not `"$49.99"` -- because the same amount is `"49,99 €"` in Germany (note: comma for decimal, symbol after number).
+
+8. **Write translator-friendly comments for every string with a variable.** When a translator sees `"You have {count} new {type}"`, they need to know: What is {count}? A number. What is {type}? "messages," "notifications," or "alerts." Where does this string appear? In a notification badge. Without this context, the translator is guessing, and guesses produce bad translations. The comment format should include: variable descriptions, possible values, screen location, and character limits if applicable.
+
+   ```json
+   {
+     "notification_badge": {
+       "value": "You have {count} new {type}",
+       "comment": "Notification badge in header. {count}: integer, always >= 1. {type}: 'messages', 'notifications', or 'alerts'. Max 40 chars."
+     }
+   }
+   ```
+
+## Details
+
+### Concatenation Trap Examples
+
+These patterns look correct in English but break in translation:
+
+| Pattern (broken)                  | Why it breaks                                                        | Fix                                                                    |
+| --------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `"Welcome, " + name`              | Name position varies by language (Japanese: name + "さん、ようこそ") | `"Welcome, {name}!"`                                                   |
+| `verb + " " + count + " " + noun` | Word order changes (German: noun may come before count)              | `"{verb} {count} {noun}"` as one complete string                       |
+| `"Delete " + itemType + "?"`      | Some languages need the noun before "delete"                         | `"Delete {itemType}?"` with context comment                            |
+| `"in " + count + " days"`         | Preposition position varies; pluralization rules differ              | ICU: `"{count, plural, one {in {count} day} other {in {count} days}}"` |
+| `status + " since " + date`       | "Since" position varies; date format varies                          | `"{status} since {date}"` with format token                            |
+| `adjective + " " + noun`          | Adjective/noun order reverses in Romance and Asian languages         | `"{adjective} {noun}"` as one translatable unit                        |
+
+The underlying principle: every sentence must be a single translatable unit. Fragments assembled at runtime are untranslatable because the assembly logic is English grammar.
+
+### ICU MessageFormat Reference
+
+ICU MessageFormat is the industry standard for translatable strings with dynamic content. Key patterns:
+
+**Pluralization:**
+
+```
+{count, plural,
+  =0 {No messages}
+  one {{count} message}
+  other {{count} messages}
+}
+```
+
+**Gender selection:**
+
+```
+{gender, select,
+  female {{name} updated her profile}
+  male {{name} updated his profile}
+  other {{name} updated their profile}
+}
+```
+
+**Nested patterns:**
+
+```
+{count, plural,
+  =0 {No files shared}
+  one {{author} shared {count} file}
+  other {{author} shared {count} files}
+}
+```
+
+Translators add the plural categories their language needs. Arabic translators would add `zero`, `one`, `two`, `few`, `many`, and `other` categories. The CLDR defines which numbers map to which category per language.
+
+### Text Expansion Design Guidelines
+
+When designing UI to accommodate text expansion:
+
+- **Buttons:** Use min-width, not fixed width. Set min-width to 120% of the English text width.
+- **Navigation labels:** Allow wrapping to two lines or use abbreviation rules per locale.
+- **Table headers:** Use flexible column widths. Never set fixed pixel widths for columns containing translated text.
+- **Tooltips and popovers:** Use max-width constraints but allow height to grow.
+- **Dialog titles:** Allow wrapping. A dialog title that is one line in English may be two lines in German.
+- **Notification badges:** Use numeric counts instead of translated words when space is critical.
+
+Test with pseudo-localization: generate fake translations that are 30-40% longer than the source and use accented characters (e.g., "[Ẃéĺçöḿé ţö ŷöûŕ ďáşĥƀöáŕď!!!]"). This reveals layout breaks before real translation begins.
+
+### Translator Comment Conventions
+
+Effective translator comments include four elements:
+
+1. **Context:** Where does this string appear? "Shown in the page header when the user has unread notifications."
+2. **Variables:** What do the placeholders contain? "{count}: integer >= 0. {name}: user's display name, max 50 chars."
+3. **Constraints:** Are there length limits? "Max 30 characters including variables."
+4. **Tone:** What tone should the translation use? "Informal, friendly. This is a success message."
+
+Without these comments, translators work from guesswork. Mozilla's Pontoon translation platform requires comments for every string with a variable, reducing translation errors by an estimated 40%.
+
+### Anti-Patterns
+
+1. **The Concatenation Trap.** Building sentences by concatenating string fragments with variables: `"Showing " + count + " of " + total + " results"`. This produces correct English but fails in languages where word order differs, where prepositions change form based on the noun, or where the number affects the grammar of surrounding words. In Hungarian, the entire sentence structure may invert. In Arabic, the noun form changes based on the number. The fix: use a single template string with all variables: `"Showing {count} of {total} results"` -- and include a translator comment explaining what the variables contain and where the string appears.
+
+2. **The Hardcoded Format.** Embedding date, time, currency, or number formats directly in strings. `"Prices start at $9.99/month"` hardcodes the dollar sign, the decimal format (period vs comma), and the currency position (before vs after the number). In Germany, this should be `"Ab 9,99 $/Monat"` (comma for decimal). In Japan, `"月額 $9.99 から"` (different word order). The fix: use format tokens for all dynamic values. `"Prices start at {price}/month"` where {price} is formatted by the i18n library according to the user's locale.
+
+3. **The Orphaned Fragment.** A string that only makes sense when combined with other strings on the screen. "and 3 more" -- 3 more what? "in" -- in what? "total" -- total of what? These fragments are untranslatable because the translator has no context. In some languages, "and" changes form based on the following word, "in" requires a different preposition based on the noun, and "total" may need a different grammatical case. The fix: make every string a complete sentence or clause. "and 3 more files" or "{count} more files" with a translator comment.
+
+4. **The English-Only Pluralization.** Using `count === 1 ? singular : plural` for pluralization. This works in English but fails in languages with multiple plural forms. Welsh has five plural forms. Arabic has six. Even French handles zero differently from English (French uses singular for zero: "0 message" not "0 messages"). The fix: use ICU MessageFormat or your framework's pluralization system, which maps to the Unicode CLDR plural rules for each language.
+
+### Real-World Examples
+
+**Mozilla's Pontoon Translation Platform.** Mozilla's Pontoon enforces i18n writing best practices by design. Every string requires context (a translator comment). Variables are displayed with their possible values. Plural forms are presented with all CLDR categories for the target language. Translators can see the string in its UI context via screenshots. The result: Mozilla products are translated into over 100 languages with consistently high quality. Pontoon's design encodes the principle that translation quality depends on source string quality -- well-written, well-commented source strings produce accurate translations.
+
+**Airbnb's i18n String Patterns.** Airbnb localizes its product into 62 languages. Their i18n style guide mandates: complete sentences (no fragments), ICU MessageFormat for all pluralization, translator comments for every string with a variable, and pseudo-localization testing before every release. A typical Airbnb string: `"{host_name} is a Superhost in {city}. They have {review_count, plural, one {{review_count} review} other {{review_count} reviews}}."` The string is complete, self-contained, properly pluralized, and has a translator comment explaining each variable. This pattern scales to 62 languages because the source string carries all the context translators need.
+
+**Android Resource String Best Practices.** Android's resource system (`strings.xml`) enforces externalization of all user-visible strings. Google's Android developer documentation provides explicit guidance: use `plurals` resources for pluralization, `string-array` for lists, and translator comments via `translatable` and `description` attributes. Android Studio flags hardcoded strings with lint warnings. The system also supports ICU MessageFormat natively through the `MessageFormat` class. Android's approach demonstrates that i18n writing quality improves when the framework enforces best practices rather than relying on developer discipline.
+
+**Apple's Localization Guide.** Apple's internationalization documentation provides concrete examples of writing for translation. Their Xcode tooling generates a string catalog that surfaces every user-visible string, its context, and the translator comment. Apple mandates complete sentences in all localizable strings and provides a stringsdict format for pluralization that maps directly to CLDR plural categories. Their pseudo-localization testing tool simulates text expansion and right-to-left layout in every build, catching i18n writing failures before they reach translators.
+
+## Source
+
+- W3C Internationalization Best Practices -- https://www.w3.org/International/techniques/authoring-html
+- Unicode CLDR Plural Rules -- https://cldr.unicode.org/index/cldr-spec/plural-rules
+- ICU MessageFormat Documentation -- https://unicode-org.github.io/icu/userguide/format_parse/messages/
+- Google i18n Guide -- Internationalization best practices for developers
+- Mozilla Pontoon -- https://pontoon.mozilla.org, translation platform design principles
+- Apple Internationalization and Localization Guide -- String management and translator guidance
+- Android Developer Documentation -- Localization best practices and resource string guidelines
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Audit existing strings for concatenation, hardcoded formats, and orphaned fragments.
+3. Externalize all user-visible strings into resource files with translator comments.
+4. Replace naive pluralization with ICU MessageFormat or equivalent.
+5. Test with pseudo-localization to verify layout handles text expansion.
+6. Verify your implementation against the anti-patterns listed above.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- No user-visible strings are hardcoded in application code -- all are externalized in resource files.
+- No string concatenation is used to build sentences -- all strings are complete translatable units.
+- All pluralization uses ICU MessageFormat or framework-equivalent, not conditional logic.
+- Every string with a variable has a translator comment explaining the variable's content and context.
+- Dates, times, currencies, and numbers use format tokens, not hardcoded formats.
+- UI layouts accommodate 30-40% text expansion without breaking.

package/dist/agents/skills/cursor/ux-internationalization-writing/skill.yaml

@@ -0,0 +1,35 @@
+name: ux-internationalization-writing
+version: "1.0.0"
+description: Writing for internationalization — source strings that survive translation, concatenation traps, pluralization, date and number references
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-inclusive-language
+  - ux-plain-language
+  - ux-microcopy-principles
+  - design-i18n-design
+stack_signals: []
+keywords:
+  - internationalization
+  - i18n
+  - translation
+  - localization
+  - pluralization
+  - concatenation
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ux-loading-states/SKILL.md

@@ -0,0 +1,162 @@
+# Loading States
+
+> Loading state copy — progress transparency, expectation setting, and writing text that reduces perceived wait time and prevents users from abandoning
+
+## When to Use
+
+- Writing loading screen copy for initial app load and data fetching
+- Composing progress messages for file uploads, exports, deployments, and async operations
+- Writing skeleton screen copy (rare — usually none needed)
+- Creating multi-step progress indicators for long-running processes
+- Writing "still working" reassurance copy for unexpectedly long waits
+- NOT for: success feedback after loading completes (see ux-success-feedback)
+- NOT for: error messages when loading fails (see ux-error-messages)
+- NOT for: empty states shown when no content is found (see ux-empty-states)
+
+## Instructions
+
+1. **Name what is loading — never just "Loading..."** "Loading your dashboard" not "Loading..." "Fetching transactions from the last 30 days" not "Please wait." "Connecting to your GitHub account" not "Processing." Naming what is loading does two things: it confirms to the user that they took the right action (the system is loading what they asked for), and it sets expectations for what will appear when loading completes. Generic "Loading..." is acceptable for sub-second interactions where naming adds no value. For anything over one second, name the specific operation. The specificity also helps users diagnose slow loads — "Fetching transactions" that takes 20 seconds tells the user the database query is slow, not the page render.
+
+2. **Show progress for anything over 3 seconds.** Under 3 seconds: a spinner or loading indicator with no copy is sufficient — users will wait without anxiety. Over 3 seconds: add copy that names the operation and, if possible, shows progress. Over 10 seconds: add a time estimate or step indicator. Over 30 seconds: add reassurance and an explanation. The 3-second threshold is research-backed (NNGroup: users expect pages to load in under 3 seconds, and anxiety begins after 3 seconds of waiting). The copy requirement scales with the wait time because user anxiety scales with uncertainty.
+
+3. **Time estimates reduce perceived wait — use them for operations over 10 seconds.** "Usually takes about 30 seconds." "This typically takes 2-5 minutes." "Large files may take up to 10 minutes." The estimate sets an expectation. Users who expect a 30-second wait experience it as normal; users who expect an instant result experience a 5-second wait as a failure. Time estimates must be honest — if "usually takes 30 seconds" is actually "usually takes 2 minutes," users will distrust all time estimates in the product. When uncertain, give a range ("2-5 minutes") rather than a fixed estimate. Stripe's verification process shows "This usually takes a few seconds" for fast paths and "Verification may take 1-2 business days" for manual review paths.
+
+4. **Use present participle for in-progress operations.** "Saving..." not "Save in progress." "Uploading..." not "Upload is being processed." "Processing payment..." not "Payment is being processed." "Analyzing..." not "Analysis underway." The present participle (-ing form) is the natural language form for ongoing actions. It is shorter, more direct, and matches how people describe activities in conversation. The ellipsis after the present participle signals incompleteness — the action is ongoing. Without the ellipsis, "Saving" reads as a label, not a state.
+
+5. **Multi-step processes benefit from step indicators.** "Step 2 of 4: Analyzing data." "Verifying identity (3 of 5)." "Building your workspace... Creating channels, inviting members, configuring settings." Step indicators serve two purposes: they show progress (reducing anxiety) and they name each step (providing context for what is happening). GitHub Actions displays each job step as it runs, with individual step names and durations. Vercel shows deployment phases: "Building... Deploying to CDN... Running health checks..." Each phase is named, so users understand why each one takes as long as it does.
+
+6. **Reassure users on unexpectedly long waits.** Show "Still working..." or "This is taking longer than usual — thanks for your patience" at the 10-second mark for operations that promised to be fast. At the 30-second mark, add context: "Large datasets take more time to process." At the 60-second mark, offer an alternative if one exists: "You can continue working and we'll notify you when this is done." Silence during a long wait is the worst outcome — the user cannot distinguish between normal slowness, a stalled operation, and a complete failure. Reassurance copy tells the user the system is still alive and working.
+
+7. **Skeleton screens need no copy — the layout communicates structure.** Skeleton screens (grey placeholder shapes in the layout of the content that will load) show the structure before data arrives. They do not need loading copy because the visual structure already communicates "content is coming." Adding "Loading your dashboard" on top of a skeleton screen is redundant — the skeleton already shows that the dashboard is loading. The exception: if the skeleton screen has a section where the layout cannot predict what will appear (variable-length content, unknown number of items), add a brief label for that section only: "Loading notifications..."
+
+8. **Never fake progress — the progress bar must reflect reality.** A progress bar that jumps to 99% and stalls for 30 seconds is worse than no progress bar. Users who see 99% believe the operation is nearly complete and wait. At 30 seconds, they realize the bar is not real. The trust damage from a fake progress bar extends beyond the loading state — users distrust all subsequent progress indicators. If the actual progress cannot be measured, use indeterminate progress (a looping animation) rather than a fake bar. When progress can be measured (file upload percentage, step count), use a real progress bar that accurately reflects the operation.
+
+## Details
+
+### Loading Copy by Wait Duration
+
+Scale copy complexity to wait duration:
+
+| Duration      | Copy Level          | Pattern                        | Example                                         |
+| ------------- | ------------------- | ------------------------------ | ----------------------------------------------- |
+| < 1 second    | None                | Visual indicator only          | Spinner                                         |
+| 1-3 seconds   | Minimal             | Operation name only            | "Loading dashboard"                             |
+| 3-10 seconds  | Standard            | Operation + present participle | "Fetching your transactions..."                 |
+| 10-30 seconds | Standard + estimate | Operation + estimate           | "Analyzing data... Usually takes 15 seconds."   |
+| 30-60 seconds | Extended + steps    | Step indicator + context       | "Step 2 of 4: Processing your payment history"  |
+| 60+ seconds   | Full reassurance    | Step + estimate + alternative  | "Still processing... We'll notify you by email" |
+
+### Multi-Step Progress Patterns
+
+For operations with discrete steps, name each step and show position:
+
+**Linear progress:** "Step 2 of 5: Verifying identity" — clear, counts toward a known total.
+
+**Phase progress:** "Building → Deploying → Running health checks" with current phase highlighted — shows all phases upfront, reducing anxiety about unknown duration.
+
+**Log-style progress:** Real-time log entries (GitHub Actions style) — ideal for technical users who want to see what is happening. Each log line names the operation and its outcome.
+
+**Percentage progress:** "37% complete — uploading file.zip" — works only when actual percentage is measurable (file upload, batch processing). Never use for unknown-duration operations.
+
+### Operations That Need Time Estimates
+
+Some operations consistently take long enough to warrant time estimates in the loading copy:
+
+| Operation Type       | Typical Duration | Estimate Pattern                             |
+| -------------------- | ---------------- | -------------------------------------------- |
+| Large file upload    | 10s - 5min       | "Usually takes about [N] minutes"            |
+| Data export          | 15s - 2min       | "Exports typically take 30-60 seconds"       |
+| Account verification | 2s - 2 days      | "Usually instant, sometimes takes a minute"  |
+| AI/ML processing     | 5s - 30s         | "Analysis takes about 10-20 seconds"         |
+| Database migration   | 1min - 30min     | "Large migrations can take up to 30 minutes" |
+| Build / deployment   | 30s - 10min      | Shows per-step timing (GitHub Actions model) |
+
+### Async Operation Loading Patterns
+
+For operations that run in the background and complete after the user has navigated away:
+
+1. **Acknowledge receipt:** "We're processing your export. You can keep working — we'll notify you when it's ready."
+2. **Show status in a persistent location:** A "Jobs" or "Activity" panel that shows running operations.
+3. **Notify on completion:** Send in-app notification or email when the async operation completes.
+4. **Handle failure gracefully:** If the operation fails after the user has navigated away, the failure notification must re-establish full context — what was being processed, what failed, and what to do next.
+
+GitHub's Actions, Vercel's deployments, and Stripe's data exports all use this async pattern. The loading copy in the trigger screen ("We'll send you an email when your export is ready") sets the expectation that this is async and positions the completion notification as the primary feedback.
+
+### Loading Copy for First-Load vs Subsequent Loads
+
+First load (the first time a user sees a screen) and subsequent loads (returning to a screen after navigation) have different tolerance levels and different copy needs:
+
+**First load:** The user does not yet know what the screen contains. "Loading your dashboard" sets the expectation. A skeleton screen showing the dashboard's layout also sets the expectation visually. Both can coexist.
+
+**Subsequent load:** The user knows what is coming — they have seen this screen before. A skeleton screen alone is often sufficient. Adding "Loading your dashboard" for a user who visits the dashboard daily is unnecessary; they know what is loading.
+
+**Stale data refresh:** When the user is viewing a screen and data refreshes in the background: "Updating..." in a subtle indicator, not a full loading overlay. Replacing the visible content with a full loading screen for a background refresh is disproportionate. Stripe's transaction list uses a subtle "Refreshing..." indicator when new transactions arrive, not a full loading screen.
+
+When possible, detect whether the user is loading a screen for the first time and show richer loading copy, then progressively reduce loading copy for subsequent visits as the user builds familiarity.
+
+### Anti-Patterns
+
+1. **The Generic Spinner.** A spinner with no copy, no label, no progress indication, for an operation that takes 10+ seconds. The user stares at a spinning circle with no information about what is happening, whether it is progressing, or when it will finish. For operations under 3 seconds, this is acceptable. For anything longer, name the operation. The generic spinner is the loading equivalent of "Something went wrong" — it conveys that the system is doing something, but nothing specific or useful.
+
+2. **The Time Lie.** "Just a moment" for a 60-second operation. "This will only take a second" for a 20-second operation. "Almost done" displayed for 45 seconds. Time lies are uniquely damaging because they create a specific expectation — "a moment" means 2-3 seconds to most users — and then violate it. The user who hears "just a moment" and waits 60 seconds does not just experience a long wait; they experience a broken promise. Use honest time estimates ("Usually 30-60 seconds") or no estimate at all rather than optimistic lies.
+
+3. **The Silent Failure.** A loading indicator that stops spinning (or a progress bar that stops advancing) with no explanation. The operation has failed, but the UI still shows a loading state. The user waits indefinitely because there is no failure message. Loading states must always have a defined failure path — if the operation times out or fails, the loading copy must be replaced with an error message. The silent failure is worse than a loud failure because the user cannot distinguish between "still loading" and "stuck."
+
+4. **The Progress Paradox.** A progress bar that reaches 99% and stays there for longer than the 0-99% journey took. The progress bar promised completion and then stopped. This is more frustrating than a slow indeterminate spinner because it created a specific expectation ("almost done") and then violated it. If the final step of a multi-step operation is unpredictably long (compiling, finalizing, verifying), use an indeterminate indicator for that final step rather than a fake 99% bar.
+
+### Real-World Examples
+
+**GitHub Actions Progress Steps.** GitHub Actions shows each step of a CI/CD workflow as a named, timed entry in real-time. "Set up job: 3s," "Checkout code: 4s," "Install dependencies: 47s," "Run tests: 1m 23s." Each step is named, each step shows its duration as it runs, and each step's outcome (green checkmark, red X) is shown when complete. This level of transparency means users understand where time is being spent, can identify bottlenecks, and can accurately predict when the build will complete. The step-by-step disclosure is the gold standard for multi-step loading copy.
+
+**Stripe's Payment Processing.** Stripe's checkout shows "Processing..." during payment submission — the present participle is appropriate for the 2-3 second window. For Stripe's verification flows (which can take seconds to minutes depending on the verification path), the copy adapts: "Verifying your information..." for fast paths, "This verification may take a few minutes — we'll let you know when it's complete" for slower paths. Stripe never shows a fake progress bar for verification — it uses indeterminate indicators because the timing is genuinely unpredictable.
+
+**Vercel's Deployment Log.** Vercel shows real-time deployment logs during site builds: "Cloning repository," "Installing dependencies," "Building application," "Deploying to edge network." Each phase shows elapsed time, and the log expands to show individual commands and their outputs. For technical users (Vercel's audience), this transparency is exactly right — they want to see what is happening, not be told to wait. Vercel's loading state is the anti-pattern to generic spinners: it shows more information, not less, during long operations.
+
+**Linear's Data Sync Indicator.** Linear shows a persistent sync indicator in the sidebar that names the current sync operation: "Syncing issues..." or "Syncing with GitHub..." The indicator is subtle (small, in the sidebar) but always present during sync — users never wonder whether their data is up to date. When sync completes, the indicator disappears silently. When sync fails, the indicator changes to an error state with a "Retry" option. Linear's approach to loading states is to make them ambient — present enough to inform, subtle enough not to interrupt.
+
+## Source
+
+- NNGroup — "Response Times: The 3 Important Limits" (1993, updated 2014), https://www.nngroup.com/articles/response-times-3-important-limits/
+- NNGroup — "Skeleton Screens" (2021), https://www.nngroup.com/articles/skeleton-screens/
+- Google Material Design — Progress indicators, https://m3.material.io/components/progress-indicators/guidelines
+- Apple Human Interface Guidelines — Progress indicators, https://developer.apple.com/design/human-interface-guidelines/progress-indicators
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), loading and processing state copy patterns
+
+## Process
+
+1. Identify the expected duration of the loading operation and select the appropriate copy level from the duration table.
+2. Write the loading copy in present participle form, naming the specific operation being performed.
+3. For operations over 10 seconds, add a time estimate or step indicator.
+4. For operations over 60 seconds or that run asynchronously, add a reassurance message and an async completion notification path.
+5. Define the failure path — what copy appears if the loading operation times out or fails.
+
+### Loading State Copy Review Checklist
+
+Before shipping loading state copy, verify each item:
+
+| Check                                            | Pass Criteria                                              |
+| ------------------------------------------------ | ---------------------------------------------------------- |
+| Operations over 3s are named                     | "Loading your dashboard" not generic "Loading..."          |
+| Present participle form used                     | "Saving..." not "Save in progress"                         |
+| Time estimate present for 10s+ operations        | "Usually takes 30 seconds" or similar                      |
+| Step indicators for multi-step operations        | "Step 2 of 4: Analyzing data"                              |
+| Reassurance at 10s mark                          | "Still working..." for operations that promised to be fast |
+| No fake progress bars                            | Indeterminate indicator used when progress is unmeasurable |
+| Failure path defined                             | Error state copy exists for every loading state            |
+| Async operations confirm receipt, not completion | "Started — we'll email you" not premature "Complete"       |
+
+Loading states are often the last copy element added to a feature and the first to be shipped without review. A loading state that shows "Loading..." for 45 seconds is indistinguishable from a hang — users cannot tell whether the product is working or broken. Every loading state needs a corresponding failure state that makes the distinction clear.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- All loading states name the specific operation, not just "Loading..." for operations over 3 seconds.
+- Present participle form ("Saving...", "Processing...") is used for all in-progress operations.
+- Time estimates appear for operations expected to take over 10 seconds.
+- Multi-step operations show step position and name (e.g., "Step 2 of 4: Analyzing data").
+- No progress bar stalls at 99% — indeterminate indicators used when final step timing is unpredictable.
+- All loading states have a defined failure path — no silent failures where the spinner spins indefinitely.

package/dist/agents/skills/cursor/ux-loading-states/skill.yaml

@@ -0,0 +1,33 @@
+name: ux-loading-states
+version: "1.0.0"
+description: Loading state copy — progress transparency, expectation setting, and writing text that reduces perceived wait time and prevents users from abandoning
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-microcopy-principles
+  - ux-success-feedback
+  - design-loading-patterns
+stack_signals: []
+keywords:
+  - loading-state
+  - progress
+  - skeleton-screen
+  - expectation-setting
+  - wait-time
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ux-microcopy-principles/SKILL.md

@@ -0,0 +1,152 @@
+# Microcopy Principles
+
+> Microcopy principles — clarity, brevity, human voice, active voice, and the core rules all UI text follows
+
+## When to Use
+
+- Writing button labels, menu items, and navigation links
+- Composing error messages, validation text, and inline warnings
+- Creating tooltips, placeholder text, and helper descriptions
+- Writing empty state text, onboarding prompts, and first-run experiences
+- Drafting notification text, toast messages, and confirmation dialogs
+- Labeling form fields, toggles, and settings descriptions
+- Writing confirmation dialog titles, body text, and action button labels
+- Reviewing existing UI text for clarity, consistency, and brevity
+- NOT for: marketing copy, landing page headlines, or brand campaign text
+- NOT for: long-form documentation, blog posts, or technical writing
+
+## Instructions
+
+1. **Lead with the user's goal, not the system's action.** Microcopy should reflect what the user is trying to accomplish, not what the software is doing behind the scenes. Stripe's checkout button says "Pay $49.99" -- the user's goal -- not "Submit payment request" -- the system's action. GitHub says "Create repository" not "Initialize new remote Git repository." Apple says "Set Up Face ID" not "Enroll biometric authentication." The test: read the label out loud and ask whether the user or the system is the subject.
+
+2. **Use first and second person for human voice.** UI text should feel like a conversation between the product and the person using it. Use "you" and "your" to address the user directly. Use "we" when the product takes responsibility. Slack says "You have 3 unread messages" not "There are 3 unread messages in the channel." Notion says "Your workspace is ready" not "Workspace initialization complete." The shift from third person to second person transforms robotic status reports into human communication. Reserve third person for referring to other users: "Jordan commented on your pull request."
+
+3. **Keep UI text under two lines -- if longer, restructure or use progressive disclosure.** Screen real estate is finite and attention is scarcer. If a tooltip requires a paragraph, the feature is either poorly designed or the text needs a "Learn more" link to documentation. Slack's message action tooltips are one sentence maximum. GitHub's hover cards show the essential information with a link to the full profile. If you cannot say it in two lines, consider whether a modal, popover, or help page would serve the user better.
+
+4. **Front-load the keyword in every label.** Users scan the first two words of any text element. The distinguishing word must come first. GitHub uses "Pull requests" not "List of pull requests." Apple's Settings uses "Notifications" not "Manage your notifications." In a sidebar with ten items, the first word of each item is the only word most users will read. Compare a settings menu: "Notification preferences / Account settings / Privacy controls" is scannable. "Manage your notification preferences / Change your account settings / Update your privacy controls" buries the keywords.
+
+5. **Use specific verbs over generic ones.** Generic verbs -- "OK," "Submit," "Confirm," "Done" -- force the user to recall what the button does. Specific verbs name the action: "Save draft," "Delete project," "Send invitation," "Export CSV." Stripe uses "Add payment method" not "Continue." Linear uses "Create issue" not "OK." The most dangerous generic verb is "OK" in a destructive dialog -- the user may click without reading. GitHub's dialog says "Delete this repository" on the destructive button, making the consequence unmistakable.
+
+6. **Match the user's vocabulary -- test with the five-second rule.** Show a piece of UI text to someone unfamiliar with the product for five seconds. If they cannot explain what it does, the vocabulary is wrong. Notion calls pages "pages" because that is what users call them -- not "document instances" or "content nodes." Figma calls design files "files" not "design artifacts." The corollary: use the term people would type into a search box to find this feature. If users search for "dark mode," do not label the setting "Appearance theme."
+
+7. **Write for the moment -- microcopy must make sense without reading the rest of the page.** Every piece of microcopy exists in a context, but the user may not have read that context. A tooltip that says "Enable this" is useless without reading the label above it. Apple's Face ID setup says "Face ID is now set up" -- this is clear even if the user skipped every previous screen. A toast that says "Done!" communicates nothing. A toast that says "Project saved" communicates everything. Each text element should be independently comprehensible.
+
+8. **Eliminate filler words -- every word must earn its place.** Count the words in your UI text. Now remove every word that does not change the meaning. "You have successfully saved your changes to the document" becomes "Changes saved." "Please enter your email address in the field below" becomes "Email." "Click the button below to continue to the next step" becomes "Continue." Stripe's payment confirmation is "Payment successful" -- two words that convey the full message. The rule: if removing a word does not change the meaning, remove it.
+
+## Details
+
+### Character Limits by Component Type
+
+Different UI components have different spatial constraints. These limits are guidelines, not absolutes, but exceeding them is a strong signal that the text needs editing:
+
+| Component          | Target Length | Maximum Length | Example                             |
+| ------------------ | ------------- | -------------- | ----------------------------------- |
+| Button label       | 1-3 words     | 4 words        | "Save draft"                        |
+| Tab label          | 1-2 words     | 3 words        | "Activity"                          |
+| Menu item          | 2-4 words     | 5 words        | "Export as PDF"                     |
+| Tooltip            | 1 sentence    | 80 characters  | "Copy link to clipboard"            |
+| Toast / snackbar   | 1-2 sentences | 120 characters | "Changes saved. Undo"               |
+| Placeholder text   | 2-5 words     | 40 characters  | "Search issues..."                  |
+| Form field label   | 1-3 words     | 4 words        | "Email address"                     |
+| Helper text        | 1 sentence    | 100 characters | "Must be at least 8 characters"     |
+| Error message      | 1-2 sentences | 150 characters | "Password too short. Use 8+ chars." |
+| Empty state        | 2-3 sentences | 200 characters | "No projects yet. Create one to..." |
+| Confirmation title | 3-6 words     | 8 words        | "Delete this project?"              |
+| Confirmation body  | 1-2 sentences | 150 characters | "This will permanently remove..."   |
+
+### The Five-Second Test
+
+The five-second test is the simplest usability test for microcopy. The process:
+
+1. Show a single screen or component to a participant for exactly five seconds.
+2. Hide the screen.
+3. Ask: "What could you do on that screen?" or "What was that message about?"
+4. If the participant cannot answer accurately, the microcopy has failed.
+
+This test catches jargon, buried keywords, ambiguous labels, and text that requires context to understand. Run it on every new feature's key screens before launch. Stripe runs five-second tests on payment forms to verify that users understand what will happen when they click the primary button. The test costs almost nothing and catches the most severe microcopy failures.
+
+### Microcopy Audit Checklist
+
+When reviewing existing UI text, check each item against these criteria:
+
+- Does the label front-load the keyword?
+- Could a new user understand this text without training?
+- Is the verb specific enough to distinguish this action from other actions on the page?
+- Does the text use "you/your" or "we/our" instead of third person?
+- Is every word necessary -- can any word be removed without changing meaning?
+- Does the text length fit the component's spatial constraint?
+- Is the text consistent with how the same concept is labeled elsewhere in the product?
+
+### Confirmation Dialog Patterns
+
+Confirmation dialogs are where microcopy matters most because the consequences are highest. The anatomy of a well-written confirmation dialog:
+
+**Title:** State the action as a question. "Delete this project?" not "Are you sure?" The title must name the specific action and the specific object so the user does not need to read the body text.
+
+**Body:** State the consequence in one sentence. "This will permanently delete 'Acme Dashboard' and all its contents. This action cannot be undone." Name the object being affected. State whether the action is reversible. Do not pad with pleasantries or unnecessary warnings.
+
+**Primary action button:** Use the destructive verb, not "OK" or "Yes." "Delete project" makes the consequence explicit. Color the button red for destructive actions. GitHub uses this pattern consistently: the delete confirmation button says "Delete this repository" in red, and requires typing the repository name as additional friction.
+
+**Secondary action button:** "Cancel" or "Keep project" -- the safe option. Never label both buttons with ambiguous text like "Yes" and "No" -- force the user to read the question to understand which is which.
+
+### Microcopy for State Changes
+
+When the UI reflects a state change, the microcopy must communicate what happened and what the current state is:
+
+- **Completed actions:** Use past tense. "Message sent," "File uploaded," "Changes saved." Not "Sending message..." after the action is done.
+- **In-progress actions:** Use present participle with ellipsis. "Uploading file..." "Saving changes..." The ellipsis signals ongoing activity.
+- **Failed actions:** State what failed and why. "Upload failed -- file exceeds 10 MB limit." Not "Error."
+- **Toggled states:** Label the action, not the current state. A button that enables dark mode should say "Turn on dark mode" when dark mode is off, not "Dark mode: off." After toggling, it should say "Turn off dark mode." Slack's notification muting follows this pattern: "Mute channel" and "Unmute channel."
+
+### Anti-Patterns
+
+1. **The Robot Voice.** UI text written in third-person passive that sounds like it was generated by a system, not written by a human. "The operation has been completed successfully. The user's preferences have been updated accordingly." No user talks like this. No human would say this to another human. The fix: rewrite in second person active voice. "Your preferences are updated." Better: "Preferences saved." The robot voice appears most often in legacy enterprise software and in products where engineers write the UI text without a content review process.
+
+2. **The Wall of Text.** A tooltip, dialog, or notification that contains an entire paragraph of explanation when one sentence would suffice. The user needed to know "Your trial ends in 3 days," but the dialog says: "Thank you for trying our product. Your free trial period, which began on January 15, 2024, is scheduled to expire in 3 days on January 28, 2024. To continue using all premium features without interruption, please upgrade your subscription by visiting the billing page in your account settings." The fix: lead with the essential information, link to details. "Trial ends in 3 days. Upgrade to keep premium features."
+
+3. **The Vague Verb.** Buttons and actions that use generic verbs -- "Submit," "Process," "Confirm," "OK," "Done," "Go" -- that do not tell the user what will happen. A dialog with "OK" and "Cancel" forces the user to re-read the dialog to understand which button does what. The fix: name the specific action on every button. "Delete project" and "Keep project" instead of "OK" and "Cancel." "Send invitation" instead of "Submit." The most common offender: "Submit" on forms -- it should be "Create account," "Place order," "Send message," or whatever the form actually does.
+
+4. **The Redundant Label.** Labels that repeat information already visible in context. A "Name" field inside a section titled "Your Name" with placeholder text "Enter your name" and helper text "Type your full name here." Each repetition adds visual noise without adding information. The fix: each text element should add new information. The section title provides context, the field label names the specific field, the placeholder shows format ("Jane Smith"), and helper text adds constraints ("As it appears on your ID").
+
+### Real-World Examples
+
+**Stripe's Checkout Flow.** Stripe's payment form is a masterclass in microcopy economy. The card number field label is simply "Card number" -- not "Enter your credit or debit card number." The expiration field says "MM / YY" as placeholder text -- the format is the instruction. The CTA button says "Pay $49.99" -- specific verb, specific amount, no ambiguity. Error messages are equally precise: "Your card number is incomplete" (not "Invalid input"), "Your card was declined. Try a different payment method." (not "Payment failed"). Every piece of text serves exactly one purpose and uses the minimum words to do so. Stripe's checkout has been tested with millions of transactions, and the microcopy is a major reason for its industry-leading conversion rates.
+
+**GitHub's Pull Request Interface.** GitHub's PR interface demonstrates consistent verb-noun patterns across dozens of actions: "Create pull request," "Request review," "Merge pull request," "Close pull request," "Link issue," "Add assignees." Every action button follows the same structure -- imperative verb plus specific object. The review states are equally precise: "Approved," "Changes requested," "Commented." Status labels front-load the state: "Open," "Closed," "Merged" -- single words that communicate instantly. The file change summary "Showing 3 changed files with 47 additions and 12 deletions" packs five data points into one scannable sentence.
+
+**Slack's Notification Patterns.** Slack calibrates microcopy density to urgency. A direct message notification: "Jordan: Can you review the PR?" -- sender and message, nothing else. A channel mention: "#engineering -- Jordan mentioned you." An app notification: "Reminder: Team standup in 15 minutes." Each notification type has a distinct pattern optimized for scanning. Slack's threading microcopy is particularly effective: "3 replies" as a link below a message tells the user exactly what they will find if they click. The "also sent to #channel" indicator uses minimal text to convey a complex routing concept.
+
+**Notion's Progressive Disclosure.** Notion demonstrates how microcopy adapts to expertise. A blank page shows "Press '/' for commands" -- teaching the core interaction in five words. The slash command menu labels are pure front-loaded keywords: "To-do list," "Heading 1," "Toggle list," "Quote." Each label is the feature name, not a description of the feature. Hover tooltips add keyboard shortcuts for power users without cluttering the primary label. The empty database shows "Click '+' to add a row" -- always one specific next action, never a paragraph of explanation. As users gain expertise, the microcopy recedes: empty pages stop showing the hint after repeated use.
+
+## Source
+
+- Yifrah, K. -- _Microcopy: The Complete Guide_ (2017), comprehensive microcopy patterns and component-specific guidance
+- NNGroup -- "Microcopy: Tiny Words That Make a Huge Difference" (2017), evidence for microcopy impact on task completion
+- Google Material Design -- Writing guidelines, https://m3.material.io/foundations/content/overview
+- Apple Human Interface Guidelines -- Writing section, https://developer.apple.com/design/human-interface-guidelines/writing
+- Podmajersky, T. -- _Strategic Writing for UX_ (2019), component-based writing frameworks
+- Krug, S. -- _Don't Make Me Think_ (2014), the five-second test and first-impression usability
+- NNGroup -- "How Users Read on the Web" (1997, updated 2020), eye-tracking evidence for scanning behavior
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Audit all button labels, error messages, and tooltips against the character limits table.
+3. Run the five-second test on key screens to verify labels are immediately comprehensible.
+4. Check every button for specific verb-noun patterns — replace any generic "OK," "Submit," or "Confirm."
+5. Verify your implementation against the anti-patterns listed above.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+
+## Success Criteria
+
+- Every button label uses a specific verb-noun pattern, not a generic verb.
+- UI text uses second person ("you/your") consistently, not third person or passive voice.
+- No tooltip, toast, or helper text exceeds the character limits defined in this document.
+- The five-second test passes for all key screens -- users can identify the available action within five seconds.
+- Filler words are eliminated -- no text element contains words that can be removed without changing meaning.
+- Confirmation dialogs use specific verb-noun button labels, not "OK" and "Cancel."
+- State change messages use the correct tense: past for completed, present participle for in-progress, and specific cause for failures.