@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/claude-code/ux-search-copy/skill.yaml

@@ -0,0 +1,33 @@
+name: ux-search-copy
+version: "1.0.0"
+description: Search copy — placeholder text, zero-results messaging, autocomplete hints, search scope indicators, saved search patterns
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-empty-states
+  - ux-microcopy-principles
+  - ux-plain-language
+stack_signals: []
+keywords:
+  - search
+  - placeholder
+  - zero-results
+  - autocomplete
+  - search-scope
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/ux-settings-preferences/SKILL.md

@@ -0,0 +1,152 @@
+# Settings and Preferences Copy
+
+> Settings and preferences copy — toggle descriptions, preference explanations, consequence previews, settings organization
+
+## When to Use
+
+- Writing toggle labels and their supporting descriptions in settings panels
+- Designing notification preference panels with per-channel or per-event controls
+- Building account and security settings pages with irreversible options
+- Creating preference descriptions that explain the effect of enabling or disabling a control
+- Organizing settings pages into scannable, goal-oriented groups
+- Writing consequence preview copy for settings with significant side effects
+- NOT for: onboarding flows where users set initial preferences (use ux-onboarding-copy)
+- NOT for: permission and role settings that control what users can access (use ux-permission-access-copy)
+- NOT for: in-flow configuration steps embedded inside feature workflows
+
+## Instructions
+
+1. **Describe the effect of the setting, not the setting itself.** The label names the control; the description should explain what enabling or disabling it changes in the user's experience. "Email notifications" as a label is fine -- but the description should say "Get an email when someone comments on your work or assigns you a task" not "Manage your email notification preferences." Slack's notification settings say "Notify me about: Direct messages, mentions, and keywords" -- the effect is described, not the category. Figma's comment notifications say "Notify me when someone comments on a file I can edit" -- the trigger condition is explicit, not implied. A user reading only the description, without the label, should be able to understand exactly what will change in their experience if they toggle the setting.
+
+2. **Toggle labels use noun phrases describing what is enabled -- not the current state.** A toggle labeled "Notifications: ON" is problematic because the meaning inverts when the toggle is off. The label must work in both states. Use "Email notifications" not "Enable email notifications" (the toggle conveys enabled/disabled -- the label should not duplicate it). Use "Show avatars in sidebar" not "Avatars: Visible." Apple's System Settings toggles follow this pattern universally: "Allow apps to request to track" describes the permission, not the state. The label remains accurate whether the toggle is on or off, and screen readers announce it correctly in both states without the label needing to change.
+
+3. **Write consequence previews for settings with significant or irreversible side effects.** Users should know what will happen before they flip the toggle, not after. Settings that log out all other sessions, delete data, change visibility, or affect other users require inline consequence text placed directly beneath the toggle, visible before the user interacts. Atlassian Jira shows under the "Disable account" toggle: "This will remove this user's access to all projects and revoke their API tokens. Their assignments and comments will remain." GitHub's branch protection rule changes show: "Changes to this setting will take effect immediately and will apply to all new pull requests." The consequence preview belongs directly under the control -- not in a tooltip, help article, or post-action confirmation where the user encounters it too late to influence their decision.
+
+4. **Group settings by user goal, not technical category.** A "Notifications" page that groups items by technical delivery channel (Email, Push, SMS, In-app) forces users to hunt for the event they care about across four sections. A goal-based grouping asks: "When do I want to be notified?" and groups by event type (Mentions, Comments, Assignments, Deadlines). GitHub reorganized its notification settings from channel-first to event-first in 2020 and reported significant reduction in user confusion about notification routing. The test: can the user find the setting for "mentions from teammates" without reading every section heading? If finding a setting requires reading and understanding the entire page structure, the grouping is technical rather than goal-oriented.
+
+5. **Write dangerous settings with visual and copy separation.** Settings that are destructive, irreversible, or have wide scope (delete account, revoke all API keys, make repository public) should be physically separated from routine settings with a visually distinct section. GitHub's "Danger Zone" section is the canonical example -- red border, distinct section heading, and each setting in its own card with a specific warning. The copy inside a danger zone setting should state the scope explicitly: "This will permanently delete your account and all associated data, including repositories, packages, and gists. This action cannot be undone." Every dangerous setting gets its own action button, never a toggle -- toggles imply reversibility, which is incompatible with the user's mental model of destructive actions.
+
+6. **Help text answers "why would I change this?" -- not "what does this do?"** The label tells the user what the setting controls. The help text should answer the question the user is most likely to have: when would I want this on or off? Stripe's API key settings show help text: "Use restricted keys to give third-party services only the permissions they need." This tells the user the use case, not the definition of a restricted key. Apple's location services help text says "Apps that have requested to use your location are listed here. You can change or remove access at any time" -- not a definition of location services but guidance on the action the user might want to take. Write the help text by imagining the question a user would type into your support chat before finding the setting on their own.
+
+7. **Settings labels must work without reading surrounding context.** A settings page is often reached from search, deep links, or system notifications -- the user may not have scrolled past the page heading. Each label and toggle must be independently comprehensible. "Enable this" as a label is useless without the surrounding context. "Marketing emails" as a label is ambiguous -- is this emails I send or emails I receive? "Receive marketing emails from Acme" removes the ambiguity and works whether the user reaches this toggle from the page's top or from a search result highlighting this specific control. Slack's notification settings work at any zoom level or search result because every label includes the actor and event: "Notify me when I'm mentioned in a channel."
+
+## Details
+
+### Toggle Label Patterns
+
+Toggles have two states and one label. The label must be accurate and meaningful in both states. Use this decision tree:
+
+- **The action being enabled:** Use a gerund or noun phrase. "Email digests," "Two-factor authentication," "Automatic updates."
+- **A permission or visibility setting:** Describe what is allowed. "Allow teammates to see your active status," "Show profile in search results."
+- **A behavioral setting:** Describe the behavior that results. "Play a sound when a message arrives," "Mark messages as read when viewed."
+
+The label should NOT include words like "Enable," "Toggle," or "Turn on" -- the toggle UI element handles that semantics. The label should NOT include the current state: "Status: Active" as a toggle label is broken because it reads "Status: Active: OFF" when disabled. Document the chosen pattern convention in the design system so all future toggle labels default to the correct form.
+
+### Notification Preference Architecture
+
+Notification preference panels are among the most complex settings UIs in consumer software. The best implementations use a two-axis model:
+
+|             | Email    | Push     | In-App   |
+| ----------- | -------- | -------- | -------- |
+| Mentions    | [toggle] | [toggle] | [toggle] |
+| Comments    | [toggle] | [toggle] | [toggle] |
+| Assignments | [toggle] | [toggle] | [toggle] |
+| Due dates   | [toggle] | [toggle] | [toggle] |
+
+Each cell is independently controllable. Column headers name the delivery channel; row headers name the event. This lets a user who wants push-only mentions and email-only due dates express exactly that preference without hunting through multiple sections. The pattern scales to any combination of events and channels. GitHub's notification preferences, Slack's notification granularity, and Figma's comment notifications all approximate this model. Label the row headers with event names from the user's perspective ("Someone mentions me") rather than system event names ("mention_created").
+
+### Review Checklist
+
+Use this checklist before shipping or reviewing any settings page implementation:
+
+| Check                          | Criteria                                        | Pass Condition                                                      |
+| ------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------- |
+| Toggle label form              | Labels are noun phrases, not state descriptions | No labels with "Enable," "Status: ON/OFF," or current state in text |
+| Effect description             | Description explains user-facing effect         | Description does not restate the label; explains trigger or outcome |
+| Consequence previews           | Significant side-effects have inline preview    | Preview text appears beneath the control before interaction         |
+| Goal-based grouping            | Settings grouped by user goal                   | Section headings name user goals, not technical subsystems          |
+| Dangerous separation           | Irreversible settings are visually separated    | Danger zone has distinct border, heading, and button (not toggle)   |
+| Help text answers "why"        | Help text explains when to change the setting   | No help text that is just a restatement or definition of the label  |
+| Context-independence           | Labels work without surrounding section heading | Label is self-contained; "enable this" or "the above" never appears |
+| Dangerous settings use buttons | No dangerous action is a toggle                 | Toggle is never used for delete, terminate, or irreversible actions |
+
+### Anti-Patterns
+
+1. **The Technical Label.** Settings labeled with backend terminology that means nothing to the user. "Enable WebSocket fallback," "Use legacy authentication flow," "Disable CORS preflight caching." Before: "Enable compression artifacts reduction." After: "Reduce blurriness when viewing large images on slower connections." The test: would a user who did not write this feature understand the label without reading documentation? Technical labels are a symptom of settings being written by engineers for engineers -- they describe implementation details rather than user outcomes. Every technical label in a settings panel is a support ticket waiting to happen.
+
+2. **The Context-Dependent Toggle.** A toggle whose label changes meaning based on its position in the page hierarchy. A toggle that says "Enabled" inside a section titled "Push Notifications" reads correctly inline, but if the user reaches it via search or deep link, "Enabled" conveys nothing. Before: toggle labeled "Enabled" inside the "Marketing Emails" section. After: standalone toggle labeled "Marketing emails from Acme Corp." The rule: any toggle that would be meaningless if its containing section heading were removed is context-dependent and needs to be rewritten. This pattern is especially common in settings pages built incrementally, where new toggles are added to existing sections by developers who rely on the section heading for context.
+
+3. **The Consequence Surprise.** Significant settings with no consequence preview, where the user discovers the effect only after taking the action. Turning off two-factor authentication with no warning, then discovering the next login requires a backup code that was never saved. Before: toggle "Two-factor authentication" with no description. After: "Two-factor authentication -- Disable this only if you have a backup authentication method. Disabling will not affect active sessions but will remove 2FA requirements on your next login." The consequence preview reduces regret-driven support tickets and builds user trust by treating users as partners in understanding the product's behavior rather than recipients of unexplained system actions.
+
+4. **The Ungrouped Dump.** A settings page with 30-50 items in a single list, organized alphabetically or in the order they were added to the codebase. Before: a flat list of 40 toggles with no section dividers. After: grouped into "Notifications," "Appearance," "Privacy," "Advanced," with each group answering a distinct user goal and dangerous settings separated into their own section with visual treatment. The ungrouped dump is the most common settings page failure in products that have grown incrementally -- new settings are added at the bottom of the list because that is the easiest code change, not because it is the best placement for the user. A quarterly settings audit that re-evaluates grouping and ordering prevents the dump from accumulating.
+
+### Real-World Examples
+
+**Slack notification preferences.** Slack's notification preferences are a benchmark for the industry. The top-level structure separates "My preferences" (global defaults) from per-workspace and per-channel overrides -- a hierarchy that reflects how users actually think about notification scope. Inside each section, the controls use event-based labels: "Direct messages, mentions, and keywords," "All new messages," "Nothing." The keyword notification field shows an inline example: "Add words or phrases, separated by commas. Example: design review, Q4 launch." The consequence of each setting is visible: changing to "Nothing" in a channel shows "You'll stop being notified for this channel" immediately beneath the radio button. This real-time consequence preview is the product's acknowledgment that notification settings are consequential and users should understand the effect before they commit.
+
+**GitHub notification settings.** GitHub's 2020 notification redesign moved from a channel-centric model to an event-centric one. The current settings page groups notifications by where they come from (Participating, Watching, Ignoring) and lets users set delivery channel independently per category. Each category includes a one-sentence explanation of what "participating" or "watching" means in practice: "Participating means you were mentioned, committed to the repository, or commented in a thread." This explanation is essential -- GitHub-specific vocabulary like "watching" has a precise meaning that differs from casual use. The settings page teaches the vocabulary at the point of decision, which is more effective than a glossary users must navigate to separately when they encounter an unfamiliar term.
+
+**Figma editor preferences.** Figma's editor preferences are embedded in the product experience rather than a separate settings page -- accessible via the menu during active work. Preferences like "Show ruler," "Snap to objects," and "Clip content" use verb phrases that describe the visual or behavioral effect rather than technical feature names. The "Clip content" toggle, which controls whether content outside a frame is visible or hidden, includes a small diagram showing the before/after visual result -- copy alone cannot convey a spatial concept. This hybrid of label plus diagram is a pattern to adopt for any setting with a visual effect that words struggle to describe accurately. Figma's decision to embed preferences in the editor rather than a separate settings page reduces the distance between discovering a preference and changing it.
+
+**Apple System Settings organization.** Apple's System Settings (formerly System Preferences) uses a goal-based top-level organization: "Wi-Fi," "Bluetooth," "Notifications," "Focus," "Screen Time," "General." Each top-level item answers "what am I managing?" not "what subsystem does this configure?" Inside "Notifications," the structure is alphabetical by app name -- which is correct because the user arrives with a specific app in mind, not a general notification concept. Apple places consequence text inline for dangerous settings: "Erasing all content and settings will remove all media, data, and settings from this Mac. This action cannot be undone." The placement is immediately before the action button, not in a separate help section the user might skip. Apple's pattern of making consequence text non-collapsible and always visible demonstrates the company's position that users should be fully informed before acting on settings with significant effects.
+
+### Copy Formulas Quick Reference
+
+These are fill-in-the-blank templates for the most common settings and preferences copy patterns:
+
+- **Toggle label (action enabled):** `[Noun phrase]` -- e.g., "Email digests," "Two-factor authentication"
+- **Toggle label (permission):** `Allow [actor] to [action]` -- e.g., "Allow teammates to see your active status"
+- **Toggle label (behavior):** `[Behavior that results]` -- e.g., "Play a sound when a message arrives"
+- **Toggle description (trigger):** `Get [notification / alert] when [event].`
+- **Toggle description (effect):** `[Outcome] when this is enabled. [Outcome] when disabled.`
+- **Consequence preview:** `[Action] will [effect] immediately. [Downstream effect].`
+- **Dangerous setting title:** `[Specific action]` -- e.g., "Delete account," "Revoke all API keys"
+- **Dangerous setting description:** `This will permanently [effect]. [Downstream effects]. This action cannot be undone.`
+- **Help text (use case):** `Use this when [scenario]. Change this if [condition].`
+- **Notification event label:** `[Actor] [event]` -- e.g., "Someone mentions me," "A task is assigned to me"
+- **Section heading (goal-based):** `[What the user is managing]` -- e.g., "Notifications," "Privacy," "Security"
+- **Admin-enforced label:** `[Setting name] · Required by your organization`
+
+## Source
+
+- NNGroup -- "Settings vs. Preferences: Making the Right Choice," https://www.nngroup.com/articles/settings-preferences/
+- Apple Human Interface Guidelines -- Settings and preferences, https://developer.apple.com/design/human-interface-guidelines/settings
+- Google Material Design -- Settings pattern, https://m3.material.io/foundations/interaction/states/overview
+- Hoober, S. -- "How Do Users Really Hold Mobile Devices?" (2013), touch target and preference panel design
+- Podmajersky, T. -- _Strategic Writing for UX_ (2019), Chapter 6: Preferences and Configuration Copy
+- NNGroup -- "Cognitive Load and UX," https://www.nngroup.com/articles/minimize-cognitive-load/
+
+## Process
+
+1. **Inventory every setting in scope.** For each setting, answer three questions: what happens when this is on? What happens when this is off? What is the consequence if changed accidentally? This inventory drives all subsequent copy decisions. Settings with significant or irreversible consequences on change are flagged for consequence preview copy. Settings with technical or ambiguous labels are flagged for rewriting before any description is written.
+
+2. **Write the label as a noun phrase describing what is controlled.** Write the description as a sentence explaining the effect from the user's perspective, starting with the trigger or the outcome: "Get an email when..." or "Hides your profile from..." Test each label-plus-description pair by asking: could a user understand this toggle without reading the rest of the page? If not, the label is context-dependent and needs revision.
+
+3. **Identify settings with significant side effects.** For each flagged setting, write consequence preview copy and place it directly beneath the control -- not in a tooltip, not in a help link, not in a post-action confirmation. Review the consequence preview with engineering to confirm technical accuracy. The consequence preview for a setting that logs out all other sessions must confirm with engineering whether the current session is affected.
+
+4. **Group settings by user goal.** List all settings and sort them into goal-oriented groups. Name each group with a heading that answers "what is the user trying to manage?" not "what technical subsystem is this?" Test the groupings by describing them to a user unfamiliar with the settings page and asking them which group each setting belongs to -- if their answers match the groupings, the structure is goal-oriented. If they consistently place settings in different groups, revise the headings.
+
+5. **Identify and separate dangerous or irreversible settings.** Move them to a visually distinct section with explicit scope copy and a button (not toggle) that leads to a confirmation dialog. Review the complete settings page with a fresh-eyes pass to confirm that no destructive setting is within accidental-click distance of a routine setting -- proximity accidents are a real risk in settings UIs with dense, small toggle controls.
+
+## 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 toggle label is a noun phrase that remains accurate and meaningful regardless of the toggle's on/off state -- no labels include "Enable," "Status: ON," or the current state in the text.
+- Every setting description explains the effect from the user's perspective (trigger, outcome, or affected audience), not the technical implementation or a restatement of the label.
+- Settings with significant side effects (session logout, data deletion, visibility changes, access revocation) show consequence preview copy directly beneath the control, visible before the user interacts.
+- Settings are organized by user goal, with section headings that name what the user is managing rather than technical subsystems -- and dangerous settings are visually and spatially separated from routine controls.
+- All help text answers "when would I want to change this?" providing use-case context, rather than restating the label or defining the feature.
+- Dangerous or irreversible settings use a button leading to a confirmation dialog, never a toggle -- toggles are reserved for reversible preferences only.
+- Every toggle label works without its surrounding section heading, so users who reach a setting via search, deep link, or scroll can understand it without reading the full page structure.
+
+## Settings Search and Deep-Link Considerations
+
+Many operating systems and enterprise products offer a settings search that filters the settings page to matching controls. When a user types "notification" in macOS System Settings, matching controls are highlighted in-place. This behavior requires that every toggle label and description contain the vocabulary users would naturally type when searching for that setting. If the label is "Alerts" but users search for "notifications," the setting is invisible to search. Audit settings labels against the most common support queries about settings to identify vocabulary mismatches and adjust labels to match user language.
+
+Deep-linked settings (links shared in onboarding emails, help articles, or admin notifications that take users directly to a specific setting) place users in the middle of the settings page without the surrounding context that guides the reading experience. Every setting that is deep-linked should have a short descriptive paragraph or call-out box explaining why the user was sent there: "Your admin has asked you to enable two-factor authentication. Turn on the toggle below to secure your account." This contextual frame bridges the gap between the message that sent the user here and the control they need to interact with.
+
+Settings that have changed since the user last visited should surface a change indicator: a "New" badge, a banner, or a highlighted border. When a setting change was forced by an admin or a product update, the copy must acknowledge this: "Your organization requires two-factor authentication. This setting was enabled by your admin and cannot be changed." Surfacing admin-enforced settings with honest copy prevents users from filing support tickets about why they cannot toggle a control that appears interactive.

package/dist/agents/skills/claude-code/ux-settings-preferences/skill.yaml

@@ -0,0 +1,33 @@
+name: ux-settings-preferences
+version: "1.0.0"
+description: Settings and preferences copy — toggle descriptions, preference explanations, consequence previews, settings organization
+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-form-labels
+  - ux-content-hierarchy
+stack_signals: []
+keywords:
+  - settings
+  - preferences
+  - toggles
+  - configuration
+  - consequence-preview
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/ux-success-feedback/SKILL.md

@@ -0,0 +1,163 @@
+# Success Feedback
+
+> Success feedback copy — confirmation messages, celebration calibration, and next-step prompts that close the action loop and guide users forward
+
+## When to Use
+
+- Writing success toasts and confirmation messages after completed actions
+- Crafting celebration copy for milestone completions (onboarding complete, first payment received)
+- Adding next-step prompts after task completion
+- Writing confirmation emails for purchases, signups, and major account actions
+- Designing undo links and safety-net success messages for reversible actions
+- NOT for: loading state copy during operations (see ux-loading-states)
+- NOT for: notification center entries for events not triggered by the current user (see ux-notification-copy)
+- NOT for: empty state copy after a list is cleared (see ux-empty-states)
+
+## Instructions
+
+1. **State what succeeded specifically — never "Done!" alone.** "Project created" not "Done!" "Invoice sent to jordan@acme.com" not "Success!" "Payment of $149 received" not "Thank you!" The specific confirmation closes the action loop: the user knows their action was received, processed, and succeeded. Generic success confirmations like "Done!" require the user to remember what they were doing. Specific confirmations like "Project created" confirm both the action (created) and its object (project). Stripe: "Payment received." GitHub: "Branch deleted." Linear: "Issue archived." Each is independently comprehensible without context.
+
+2. **Calibrate celebration to consequence.** Completing your first-ever payment on Stripe warrants a more celebratory message than saving a notification preference. Finishing onboarding warrants more enthusiasm than updating a timezone setting. The calibration rule: match the emotional weight of the copy to the significance of the accomplishment. Stripe's first-payment confirmation to new merchants: "Your first payment has arrived! You're now ready to accept payments from customers worldwide." The same page for the 1,000th payment: "Payment of $149.00 received." One is a milestone; the other is routine. Treating routine actions with milestone enthusiasm habituates users to ignore success messages.
+
+3. **Include a next step when one is obvious.** "Project created. Invite your team →." "Account setup complete. Create your first issue." "Payment received. View your dashboard." The next step closes the loop and immediately provides forward momentum. Not every success message needs a next step — "Settings saved" does not, because the user knows what to do next. But after onboarding completion, first payment receipt, or any action that represents a significant milestone, the next step turns a confirmation into a launch pad. Linear: "Issue created. Add assignee →." GitHub: "Repository created. Add a README →."
+
+4. **Use past tense for completed actions.** "Project created" not "Project is being created" (that is a loading state). "Changes saved" not "Changes are saved" (the extra words add nothing). "Member removed" not "The member has been removed from your workspace" (the object does not need the full path). Past tense is the natural language form for completed events. It is also more compact — "Changes saved" (2 words) vs. "Your changes have been successfully saved" (6 words). Shorter success messages are better because they are read faster and dismissed faster, allowing the user to return to their task.
+
+5. **Do not over-celebrate routine actions.** "Settings saved" not "Awesome! Your settings are saved! Great job! 🎉." The emoji, the exclamation points, and the "Awesome!" add emotional weight to a routine action that does not deserve it. Over-celebration has two failure modes: it dilutes genuine celebration (if every action gets "Awesome!", the actual milestones are indistinguishable), and it irritates users who find the performative enthusiasm condescending. Reserve enthusiasm for genuine milestones. GitHub's routine confirmation messages are dry and minimal. Stripe's first-payment milestone message is genuinely warm. The contrast makes both more effective.
+
+6. **Undo links in success messages turn confirmations into safety nets.** "Message sent. Undo" is a toast that acknowledges success while offering a recovery path. "Issue archived. Undo" does the same. Undo in a success message works because it appears immediately after the action, when undoing is most relevant and most appreciated. Gmail's undo-send is the canonical example: the success toast contains both the confirmation ("Message sent") and the recovery action ("Undo"), making the confirmation the most useful UI element in the product. Undo links should appear within the success toast, not as a separate interaction.
+
+7. **For async operations, confirm receipt — not completion.** When the user submits a process that will complete in the background (export, data migration, payment processing, deployment), confirm that the process was received and started — not that it completed. "We're processing your export. You'll receive an email when it's ready." not "Export complete!" when the export has only been queued. Premature success messages are a form of deception — the user believes the action succeeded when it has only been scheduled. If the async operation fails after the user has received a "success" confirmation, the failure is more confusing because the user thought it was done.
+
+8. **First-time milestone messages should name what the user unlocked, not just what they completed.** "Your first project is created! You can now invite teammates, track issues, and publish reports." names the specific new capabilities the milestone unlocks. "Project created" for a first project misses the opportunity to explain what comes next. GitHub's repository creation confirmation for first-time users shows the README, issues, and code tabs — implicitly showing what the user can now do. Stripe's first-payment confirmation explains what the merchant can now do: accept payments, view transaction history, set up payouts. The milestone confirmation is also an onboarding moment.
+
+## Details
+
+### Success Message Patterns by Action Type
+
+Match the success message pattern to the type of action:
+
+| Action Type            | Pattern                                  | Example                                           |
+| ---------------------- | ---------------------------------------- | ------------------------------------------------- |
+| Routine save           | Object + past tense verb                 | "Changes saved"                                   |
+| Destructive (undoable) | Object + verb + undo link                | "Issue archived. Undo"                            |
+| Creation               | Specific object + created + next step    | "Project created. Invite your team →"             |
+| Async submission       | Receipt confirmation + notification path | "Export started. We'll email you when it's done." |
+| Milestone              | Celebration + unlocked capabilities      | "You're live! Customers can now pay you."         |
+| Social action          | Recipient name + action                  | "Invitation sent to jordan@acme.com"              |
+| Billing                | Specific amount + confirmation           | "Payment of $149 received"                        |
+| Permission change      | Who + new state                          | "Jordan is now an admin"                          |
+
+### Celebration Calibration Scale
+
+Match enthusiasm level to action significance:
+
+| Significance Level | Frequency      | Copy Register           | Example                                                                |
+| ------------------ | -------------- | ----------------------- | ---------------------------------------------------------------------- |
+| Routine            | Multiple/day   | Dry, minimal            | "Settings saved"                                                       |
+| Moderate           | Weekly         | Direct, positive        | "Profile updated"                                                      |
+| Notable            | Monthly        | Warm, forward-looking   | "Report published. View →"                                             |
+| Milestone          | Once or rarely | Celebratory, expansive  | "You're live! First payment received."                                 |
+| Major achievement  | Lifetime       | Full celebration moment | "Welcome aboard! Your account is fully set up and you're ready to go." |
+
+Treat every action as if it is the nth occurrence, not the first. Design the routine confirmation first, then add celebration only for genuine milestones.
+
+### Undo in Success Messages
+
+The undo pattern is a specific success message design that:
+
+1. Appears in a toast or snackbar immediately after the action
+2. Confirms the action succeeded
+3. Offers an undo link that reverses the action within a time window (usually 5-10 seconds)
+4. The time window is shown ("Undo (5s)") or indicated by the toast's auto-dismiss behavior
+
+Actions that support undo in success messages:
+
+- Message and email sending (Gmail's undo send)
+- Archiving and soft-deleting items
+- Bulk operations (archive all, mark all as read)
+- Moving items between states or locations
+
+Actions that cannot support undo:
+
+- Hard deletes (no undo possible — use a confirmation dialog instead)
+- Payments (cannot be reversed in the same way)
+- Published content (may be cached or seen by others immediately)
+
+### Success Message Character Limits
+
+| Component              | Target Length | Maximum Length |
+| ---------------------- | ------------- | -------------- |
+| Toast (routine)        | 2-5 words     | 80 characters  |
+| Toast (with undo)      | 3-8 words     | 100 characters |
+| Toast (with next step) | 5-10 words    | 120 characters |
+| Modal success          | 1-3 sentences | 200 characters |
+| Milestone message      | 2-4 sentences | 300 characters |
+
+### Anti-Patterns
+
+1. **The Generic Done.** "Done!" or "Success!" or "Complete!" with no specification of what was done, succeeded, or completed. These generic confirmations require the user to remember what they were doing — which is especially problematic for users who were distracted or operating under cognitive load. The fix is always the same: name the specific action and its object. "Issue #247 closed" is never worse than "Done!" and is usually significantly better. Generic success messages are often a sign that the success feedback was added as an afterthought.
+
+2. **The Celebration Overload.** "Amazing! You just saved your settings! Woohoo! 🎉🎊✨ You're doing great!" for a settings save. The emotional register is wildly disproportionate to the action. Celebration overload is particularly common in consumer apps targeting younger users, but it backfires — users feel condescended to, and genuine celebration moments (first payment, onboarding complete) become meaningless because every action already received maximum enthusiasm. The fix: dry for routine, warm for notable, celebratory only for milestones.
+
+3. **The Premature Success.** Showing "Export complete!" when the export has been queued but not yet processed. Showing "Payment successful" when the payment has been submitted but not confirmed. The async gap between submission and completion is a UX vulnerability — products that confirm receipt as completion set up users for confusion when the actual completion (or failure) occurs later. The fix: "Export started. We'll email you when it's ready." — confirms the receipt without claiming the completion.
+
+4. **The Missing Next Step.** A milestone confirmation that ends with a blank screen or auto-redirects to an empty dashboard with no guidance. The user completed onboarding or made their first sale and now faces an empty interface with no pointer to what to do next. The completion moment is the highest-engagement moment in a user's product experience — it is the wrong moment to provide no direction. Every milestone confirmation should name the most important next action and provide a direct path to it.
+
+### Real-World Examples
+
+**Stripe's Payment Confirmation for New Merchants.** Stripe's first-payment confirmation to merchants who are new to the platform: "Your first payment has arrived. You're now set up to accept payments from customers worldwide." The confirmation includes the amount, the customer name, and the timestamp. Below it: "Set up payouts →" as the next step. Stripe's design team has A/B tested this confirmation extensively — the version that names the unlocked capability ("accept payments from customers worldwide") has higher merchant activation than the version that just states the amount. The milestone framing motivates the next action.
+
+**GitHub's PR Merged State.** When a pull request is merged, GitHub shows a purple "Merged" badge and the text "Pull request successfully merged and closed." Below it: "You're all set — the branch has been merged, or you can delete the branch." The confirmation names what happened ("merged and closed"), explains the state ("all set"), and offers an optional cleanup action ("delete the branch"). GitHub's tone in this state is calm and complete — the work is done, the options are clear. There is no celebration for a routine merge, but the copy is satisfying because it is complete and specific.
+
+**Notion's Page Published State.** When a Notion page is published to the web, the confirmation shows: "Your page is now public." with a copy-link button and a share options button. The confirmation names the new state ("public"), provides the immediate next action (copy the link to share), and leaves further options one click away. Notion does not celebrate page publishing — it is a routine action for Notion users — but it provides the most useful next step (the link) at the moment it is needed. The confirmation doubles as the share workflow trigger.
+
+**Linear's Issue Closed Confirmation.** Linear shows "Issue closed" in a brief toast when an issue is marked done. The toast includes an "Undo" link for the first 5 seconds. The undo link is particularly valuable in Linear because issues are frequently closed accidentally when triaging. The success toast with undo replaces a "Are you sure you want to close this issue?" confirmation dialog — the undo approach is friendlier (no interruption) and equally safe (recovery is available immediately). Linear's success messages are uniformly minimal: the action name, the object, and an undo link where applicable.
+
+## Source
+
+- NNGroup — "Toast Notifications: 8 Design Guidelines" (2020), https://www.nngroup.com/articles/toast-notification/
+- Apple Human Interface Guidelines — Alerts and confirmations, https://developer.apple.com/design/human-interface-guidelines/alerts
+- Google Material Design — Snackbars, https://m3.material.io/components/snackbar/guidelines
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), success state and confirmation copy
+- Podmajersky, T. — _Strategic Writing for UX_ (2019), feedback copy and celebration calibration
+
+## Process
+
+1. Identify the action type and significance level — select the appropriate success message pattern from the table.
+2. Write the confirmation in past tense, naming the specific action and its object.
+3. Calibrate the emotional register to the significance level — routine = dry, milestone = celebratory.
+4. Add a next-step prompt for milestone completions and first-time actions.
+5. For reversible destructive actions, add an undo link within the success toast.
+6. For async operations, confirm receipt rather than completion and specify the completion notification path.
+
+### Success Feedback Copy Review Checklist
+
+Before shipping success feedback copy, verify each item:
+
+| Check                                            | Pass Criteria                                              |
+| ------------------------------------------------ | ---------------------------------------------------------- |
+| Specific action and object named                 | "Issue archived" not "Done!" or "Success!"                 |
+| Past tense used                                  | "Changes saved" not "Changes are saving"                   |
+| Celebration calibrated to significance           | Routine = dry, milestone = warm, major = celebratory       |
+| Next step present for milestones                 | "Project created. Invite your team →."                     |
+| Undo link for reversible destructive actions     | Toast includes "Undo" for archive, delete (soft), bulk ops |
+| Async operations confirm receipt, not completion | "Started" or "Queued" — not "Complete" before it is        |
+| First-time milestone names unlocked capabilities | States what the user can now do, not just what they did    |
+| No over-celebration for routine actions          | Settings saves and list items do not get "Amazing!" copy   |
+
+Success feedback is the moment users feel competent and effective — or they do not. A generic "Done!" robs that moment of its specificity. A premature success message destroys it when the actual completion or failure arrives later. The investment in specific, calibrated success copy pays back in user confidence and engagement.
+
+## 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
+
+- Success messages name the specific action and its object — no generic "Done!" or "Success!"
+- Emotional register matches significance level — routine confirmations are minimal, milestones are celebratory.
+- Milestone confirmations include a next-step prompt pointing to the most important immediate action.
+- Reversible destructive actions include an undo link in the success toast.
+- Async operations confirm receipt ("started," "queued"), not completion, with a notification path.
+- Past tense is used for all completed actions — no present progressive or future tense.

package/dist/agents/skills/claude-code/ux-success-feedback/skill.yaml

@@ -0,0 +1,33 @@
+name: ux-success-feedback
+version: "1.0.0"
+description: Success feedback copy — confirmation messages, celebration calibration, and next-step prompts that close the action loop and guide users forward
+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-notification-copy
+  - ux-loading-states
+stack_signals: []
+keywords:
+  - success-feedback
+  - confirmation
+  - celebration
+  - next-steps
+  - positive-reinforcement
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/ux-tooltip-contextual-help/SKILL.md

@@ -0,0 +1,163 @@
+# Tooltip and Contextual Help
+
+> Tooltip and contextual help writing — when to use tooltips, what to put in them, and progressive disclosure patterns that educate without interrupting
+
+## When to Use
+
+- Writing tooltip copy for icon buttons, truncated labels, and supplemental information
+- Deciding between tooltips, popovers, inline help, and contextual documentation links
+- Adding keyboard shortcut hints to toolbar and menu items
+- Writing coach mark copy for feature discovery during onboarding
+- Adding "Learn more" links and progressive disclosure to complex settings
+- NOT for: form field helper text (see ux-form-labels)
+- NOT for: error messages and validation feedback (see ux-error-messages)
+- NOT for: onboarding wizard step descriptions (see ux-onboarding-copy)
+
+## Instructions
+
+1. **Tooltips add information — they never repeat labels.** If the tooltip copies what the button or label already says, delete the tooltip. A "Send" button with a tooltip that says "Send" provides zero new information and adds a hover interaction for no gain. A "Send" button with a tooltip that says "Send to all project members (⌘↵)" provides new information: the scope and the keyboard shortcut. The test: does removing the tooltip cause the user to lose any information they could not get from the label? If not, remove the tooltip. Tooltips that restate labels add noise to the interface and teach users to ignore tooltips.
+
+2. **Write tooltips in one sentence — 80 characters maximum.** "Merge the current branch into the base branch and close this pull request." is 72 characters — at the limit and clear. Tooltips appear on hover and disappear when the user moves away; there is no time for the user to read a paragraph. If the explanation requires more than one sentence, use a popover with a "Learn more" link instead of a tooltip. Figma's toolbar tooltips are the reference: each one is a single phrase or short sentence — never a paragraph. When writing a tooltip, cut it until it cannot be cut further without losing meaning.
+
+3. **Answer the question the user is about to ask.** The user hovers over an unfamiliar element because they have a question: "What does this do?" or "What is this for?" The tooltip's job is to answer that specific question in the fewest possible words. For icon-only buttons, the question is usually "What action does this trigger?" For truncated text, the question is "What is the full text?" For a beta feature label, the question is "What does this affect?" Write the tooltip as if you know the exact question and are answering it precisely — not providing a general description of the element.
+
+4. **Use tooltips for supplemental information, inline help for required context.** If the user cannot use the feature correctly without knowing the tooltip's content, the information belongs inline — not in a tooltip. Tooltips are for supplemental, nice-to-have information that does not block task completion. Keyboard shortcut hints are perfect tooltip content — helpful but not required. A character limit constraint ("Descriptions are limited to 500 characters") is required context — it belongs below the field as helper text, where it is always visible, not in a tooltip that requires hovering. The distinction is: supplemental = tooltip, required = inline.
+
+5. **Never put critical information only in a tooltip.** Tooltips are invisible to touch and mobile users, inaccessible to users who navigate by keyboard without triggering hover, and often missed by users who work quickly. If the information would cause a mistake when missed (a pricing note, a data limitation, a permission requirement), it must appear in the persistent UI — not only in a tooltip. GitHub's "Private" label on repositories appears as persistent text in the UI; the tooltip adds a definition ("Only you and collaborators can see this") but does not carry the only indication that the repository is private.
+
+6. **Keyboard shortcut tooltips follow "Action (Shortcut)" format.** "Save (⌘S)" not "Press Command+S to save." "Bold (⌘B)" not "Keyboard shortcut: Command+B." The action name comes first — it is what the user needs to know. The shortcut is supplemental context, shown in parentheses because it is helpful but not the primary information. Figma and Linear use this pattern consistently across all keyboard-shortcut tooltips. The shortcut symbol should use the standard OS symbols: ⌘ (Command), ⌥ (Option), ⇧ (Shift), ⌃ (Control) for Mac; Ctrl, Alt, Shift for Windows.
+
+7. **"Learn more" links belong in popovers, not tooltips.** A tooltip with a "Learn more" link requires the user to hover, read, and click without moving away — which is physically difficult because moving toward the link often dismisses the tooltip. Popovers (click-triggered, persistent until dismissed) are the correct container for "Learn more" links, detailed explanations, and supplemental documentation. Stripe uses hover tooltips for simple definitions and click-triggered popovers for billing term explanations that link to documentation. The popover stays open while the user reads and clicks.
+
+8. **Disable tooltips on interactive elements when the element's state conveys the information.** A disabled button with a tooltip explaining why it is disabled ("You need admin permissions to do this") is appropriate — the tooltip provides information the button's state cannot. A fully enabled, clearly labeled button with a tooltip restating the label is not appropriate. GitHub shows "You need push access to this repository" tooltips on disabled merge buttons — the tooltip explains the disabled state, not the button's normal behavior. The tooltip answers the question the user would ask when they encounter the unexpected disabled state.
+
+## Details
+
+### Tooltip vs Popover vs Inline Help Decision
+
+Choose the help surface based on the information's complexity and the user's interaction:
+
+| Surface     | Trigger    | Persistence | Length        | Best For                                      |
+| ----------- | ---------- | ----------- | ------------- | --------------------------------------------- |
+| Tooltip     | Hover      | On hover    | 1-80 chars    | Simple definitions, keyboard shortcuts        |
+| Popover     | Click      | Until close | 1-3 sentences | Multi-sentence explanations + links           |
+| Inline help | Persistent | Always      | 1-2 sentences | Required context (constraints, format)        |
+| Coach mark  | First use  | One-time    | 1 sentence    | Feature discovery during onboarding           |
+| Help link   | Click      | New page    | Full docs     | Complex features requiring full documentation |
+
+### Tooltip Copy by Element Type
+
+Different element types have different tooltip needs:
+
+| Element Type         | Tooltip Content                      | Example                                          |
+| -------------------- | ------------------------------------ | ------------------------------------------------ |
+| Icon button          | Action name + shortcut if available  | "Archive issue (E)"                              |
+| Disabled button      | Reason for disabled state            | "Requires admin permissions"                     |
+| Truncated text       | Full untruncated text                | "Acme Dashboard — Q4 Performance Review Final"   |
+| Status label         | Definition of the status             | "In review: waiting for at least one approval"   |
+| Beta/new label       | What the feature does + limitations  | "Beta: may change before general release"        |
+| Metric or data point | Definition + calculation method      | "Weekly active users: unique sessions in 7 days" |
+| Avatar / profile     | Full name + role or relevant context | "Jordan Lee, Engineering Lead"                   |
+
+### Progressive Disclosure Hierarchy
+
+Use progressive disclosure to layer information by user need:
+
+1. **Label** — The primary identifier. Always visible. Maximum clarity.
+2. **Tooltip** — Supplemental context. Visible on hover. Under 80 characters.
+3. **Popover** — Extended explanation. Visible on click. 1-3 sentences + optional link.
+4. **Documentation link** — Full reference. Visible in popover or help center. Unlimited length.
+
+Not every element needs all four layers. Simple, self-explanatory labels need no tooltip. Complex features may need all four. The hierarchy ensures users who need more information can find it without overwhelming users who do not.
+
+### Accessibility Requirements for Tooltips
+
+Tooltips have specific accessibility requirements that affect both implementation and copy:
+
+- Tooltips must be accessible via keyboard focus, not only hover — the same content must appear when the element receives keyboard focus.
+- Tooltip content must be read by screen readers — implement via `aria-label` (for icon buttons), `aria-describedby` (for additional context), or `title` attribute (deprecated for interactive elements, acceptable for static).
+- Never put interactive elements (links, buttons) inside tooltips — use popovers for interactive content.
+- Critical information placed only in tooltips fails WCAG 1.1.1 (non-text content) for icon buttons and WCAG 1.3.1 (info and relationships) when the tooltip is the only label.
+
+### Tooltips vs Popovers vs Inline Help: Decision Guide
+
+When writing contextual help, select the surface before writing the copy:
+
+| Question                                            | If Yes → Use    |
+| --------------------------------------------------- | --------------- |
+| Is the information under 80 characters?             | Tooltip         |
+| Does the user need to click a link within the help? | Popover         |
+| Is the information required to complete the task?   | Inline help     |
+| Does the information persist across the session?    | Inline help     |
+| Is it a keyboard shortcut hint?                     | Tooltip         |
+| Does the information explain a non-obvious concept? | Popover or link |
+| Is this a one-time onboarding explanation?          | Coach mark      |
+
+The decision surface determines the copy format. Tooltip copy must fit on one line — if the first draft doesn't, use a popover. Inline help copy must be persistently useful — if the user would only want it once, use a coach mark. Coach mark copy must reference a specific visible element — if it doesn't, it belongs in documentation.
+
+### Anti-Patterns
+
+1. **The Redundant Tooltip.** The tooltip says exactly what the label says. A "Settings" button with a tooltip that says "Settings." A "Download" link with a tooltip that says "Download." The hover adds nothing — it's like having someone repeat your name back to you. Delete redundant tooltips entirely. They teach users to ignore tooltips, which means important supplemental tooltips are also ignored. Every tooltip should pass the test: does it add information the label does not contain?
+
+2. **The Essay Tooltip.** A tooltip containing three sentences, a bulleted list, or a paragraph. The user hovers to get a quick answer and instead reads a manual excerpt. Long tooltips also cause layout problems — they extend beyond the viewport, obscure nearby content, or are cut off. The fix: use a popover (click-triggered, persistent, scrollable) for any content that requires more than 80 characters. Tooltips are for one-sentence answers; popovers are for explanations.
+
+3. **The Critical-Only-In-Tooltip.** A fee disclosure, a data privacy warning, a billing consequence, or a permission requirement that appears only in a tooltip. When the information is critical — meaning missing it causes a mistake — it must appear in the persistent UI. Tooltips disappear; important information must persist. A common offender: "This action will be billed at $0.05 per query" placed only in a tooltip on an "Execute" button. Users who click without hovering incur charges they did not see. The billing consequence belongs as inline helper text, not a tooltip.
+
+4. **The Jargon Explainer.** Using a tooltip to define internal jargon instead of replacing the jargon with plain language. "WIP" with a tooltip that says "Work in Progress." "MRR" with a tooltip that says "Monthly Recurring Revenue." The better fix is to use plain language in the label itself ("Monthly revenue" instead of "MRR") so no tooltip is needed. Tooltips that define jargon are a sign that the primary label has failed. Use the tooltip copy as the label, and delete the tooltip.
+
+### Real-World Examples
+
+**Figma's Toolbar Tooltips.** Figma's toolbar is icon-only, which makes tooltips essential. Every tool has a tooltip following "Tool name (Shortcut)" format: "Frame (F)," "Rectangle (R)," "Pen (P)," "Text (T)." These tooltips do three things simultaneously: name the tool, confirm its purpose, and teach keyboard shortcuts. The shortcuts are discoverable only through tooltips — Figma uses this as a deliberate progressive disclosure strategy. Users who hover learn the shortcuts; users who never hover can still use the toolbar by clicking icons.
+
+**GitHub's Action Tooltips.** GitHub's PR interface uses tooltips to explain status labels and disabled states. A greyed-out "Merge pull request" button shows "This branch has conflicts that must be resolved" on hover — explaining why the button is disabled without cluttering the visible UI. Status check tooltips show the specific check name and its outcome. GitHub's tooltips are consistently one sentence and answer the question "Why is this in this state?" rather than "What is this element?"
+
+**Stripe Dashboard Hover Cards.** Stripe's Dashboard uses hover cards (a popover variant) rather than pure tooltips for complex metric definitions. Hovering over "MRR" shows a card: "Monthly Recurring Revenue: The normalized, annualized value of all active subscriptions, calculated monthly. Learn how we calculate MRR →." The hover card persists on hover (unlike a tooltip that dismisses when moving toward it), allowing the user to click the "Learn more" link. Stripe uses simple tooltips (one sentence) for simple elements and hover cards for financial metrics that require precise definitions.
+
+**Linear's Keyboard Shortcut Hints.** Linear is a keyboard-first product — nearly every action has a keyboard shortcut. Linear surfaces shortcuts through tooltips that follow "Action (Key)" format: "Create issue (C)," "Archive (E)," "Set priority (P)." The shortcuts are not listed in documentation or a separate shortcut guide — they are discovered entirely through tooltips. This progressive disclosure approach means new users are not overwhelmed by a shortcut reference, while power users naturally discover shortcuts through use. Linear's shortcut coverage in tooltips is comprehensive — the tooltip is the shortcut documentation.
+
+## Source
+
+- NNGroup — "Tooltip Guidelines" (2019), https://www.nngroup.com/articles/tooltip-guidelines/
+- Apple Human Interface Guidelines — Tooltips, https://developer.apple.com/design/human-interface-guidelines/tooltips
+- Google Material Design — Tooltips, https://m3.material.io/components/tooltips/guidelines
+- W3C WCAG 2.1 — Success Criterion 1.1.1: Non-text Content, https://www.w3.org/WAI/WCAG21/Understanding/non-text-content
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), contextual help and tooltip patterns
+
+## Process
+
+1. Identify whether the element is an icon button, disabled state, truncated text, or supplemental information — select the appropriate tooltip content pattern.
+2. Write the tooltip in one sentence, under 80 characters, answering the question the user would ask on hover.
+3. Confirm the tooltip adds information not present in the label — delete redundant tooltips.
+4. If content requires more than 80 characters or includes a link, use a popover instead.
+5. Verify that critical information does not appear only in the tooltip — move required context to inline helper text.
+
+### Tooltip Copy Review Checklist
+
+Before shipping tooltip or contextual help copy, verify each item:
+
+| Check                                         | Pass Criteria                                           |
+| --------------------------------------------- | ------------------------------------------------------- |
+| Tooltip adds information not in the label     | Removing tooltip causes information loss                |
+| Under 80 characters                           | One sentence, fits on one line in the tooltip component |
+| Answers the hover question                    | Addresses what a user would ask on hover                |
+| No interactive elements inside tooltip        | Links and buttons belong in popovers                    |
+| Critical information not tooltip-only         | Required info also appears in persistent UI             |
+| Keyboard shortcut format: "Action (Shortcut)" | "Bold (⌘B)" not "Press Command+B to bold"               |
+| Accessible via keyboard focus                 | Visible on :focus, not only on :hover                   |
+| Popovers used for multi-sentence content      | No tooltip over 80 chars — converted to popover         |
+
+The most impactful tooltip audit action: search for tooltips that duplicate labels and delete them. Redundant tooltips are the most common tooltip failure and the most damaging because they teach users to ignore all tooltips.
+
+## 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 tooltip adds information not present in the visible label — no redundant restatements.
+- Tooltip copy is one sentence, under 80 characters.
+- Keyboard shortcut tooltips follow "Action (Shortcut)" format using OS-standard symbols.
+- Critical information (billing, permissions, data consequences) appears in persistent UI, not tooltips only.
+- Popovers are used instead of tooltips for content requiring more than one sentence or a "Learn more" link.
+- Tooltips are accessible via keyboard focus, not only hover (meets WCAG accessibility requirements).