@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/ux-error-severity/SKILL.md

@@ -0,0 +1,155 @@
+# Error Severity Communication
+
+> Error severity communication — calibrating error tone to severity, from field validation to system failure to data loss
+
+## When to Use
+
+- Deciding between warning, error, and critical severity for a message
+- Writing data loss or irreversible action warnings that require urgent communication
+- Calibrating tone for field validation errors versus system outage messages
+- Designing error hierarchies for forms or dashboards with multiple issue types
+- Building escalation sequences for trial expiration, quota warnings, and usage alerts
+- NOT for: error message content and structure (see ux-error-messages)
+- NOT for: destructive action confirmation dialogs (see ux-destructive-action-copy)
+- NOT for: notification component selection and urgency calibration (see ux-notification-copy)
+
+## Instructions
+
+1. **Map severity to visual and textual weight — they must always match.** Field validation is calm and instructional. System errors are direct and factual. Data loss warnings are urgent and specific. The text must reinforce what the visual design communicates — using alarming language with a blue informational icon, or casual language with a red critical indicator, creates cognitive dissonance that undermines user trust. A red error badge on a benign "email already subscribed" message trains users to distrust the severity system. Severity levels must be consistent: the same category of error should always read the same way, everywhere in the product.
+
+2. **Use a four-tier severity model: info, warning, error, critical.** Each tier has distinct copy patterns that pair with visual treatment. Info (blue): supplemental context the user should know but that requires no action. Warning (amber): something that needs attention but does not block progress — the user can continue but should be aware. Error (red): something that failed and blocks a specific action — user must take action to proceed. Critical (red + icon + blocking): data loss, security issues, or irreversible states requiring immediate action — the user cannot proceed without addressing this. AWS Console uses all four tiers with consistent styling and copy conventions across hundreds of services.
+
+3. **Match punctuation and sentence structure to severity.** Informational messages use lowercase, periods, and suggest rather than demand. "Your draft is saved automatically." Warnings use direct statements that name the consequence. "This action will affect 47 team members." Error messages use imperative recovery instructions. "Payment failed. Try a different card." Critical messages use imperative sentences and explicit consequence statements. "This will permanently delete all data. This cannot be undone." The register escalates with severity — critical messages should feel heavier in both visual weight and grammatical authority than info messages.
+
+4. **Never escalate minor issues to high severity.** "Password too short" is not a critical error. "File successfully uploaded" is not a warning. Overuse of red styling, all-caps text, warning icons, or alarming language on routine events trains users to ignore real warnings. This is the severity version of the crying wolf effect — when everything looks urgent, nothing is urgent. Linear uses green checkmarks for success, amber for warnings about usage limits, and red only for genuine errors like failed syncs or authentication failures. Reserve the critical tier for events that genuinely warrant it.
+
+5. **For data-loss scenarios, name the specific data at risk.** "Your unsaved changes will be lost" is better than "Are you sure?" but "Your 3 unsaved comments and 1 uploaded image will be permanently deleted" is best. Specificity creates genuine understanding of consequence. Vague warnings like "data may be affected" are routinely dismissed because users cannot assess the actual impact. Figma's autosave conflict dialog names the specific edits from each editor that would be overwritten. GitHub's repository deletion confirmation names the repository and lists what is included: "All forks, pull requests, issues, and wikis will also be deleted."
+
+6. **System errors should communicate timeline when possible.** Users need to know whether to retry now, retry later, or wait for a fix. "We're looking into this" (investigating, indeterminate timeline), "Try again in a few minutes" (transient, short wait), "Service unavailable until 3:00 PM EST" (known resolution window), "Follow @status for updates" (unknown, ongoing monitoring). VS Code's extension marketplace shows degraded-service banners with specific context about what is affected and what the team is doing about it. A system error without a timeline leaves users unable to decide whether to wait, retry, or use an alternative.
+
+7. **Escalate severity language as risk accumulates — not just visual treatment.** Trial expiration warnings should escalate in copy intensity, not just color or icon. "Your trial ends in 14 days" (info) → "Trial ends in 3 days. Upgrade to keep your data" (warning) → "Trial ends tomorrow. Add billing now or lose access" (error) → "Your trial has ended. Export your data before it's deleted in 24 hours" (critical). Stripe, GitHub, and Figma all use this escalation pattern for quota and billing warnings. Each stage increases specificity and urgency in both the visual and copy treatment simultaneously.
+
+8. **Provide recovery actions proportional to severity tier.** Info tier recovery is optional: a "Learn more" link or a dismiss button. Warning tier recovery is a single clear action: "Enable backup" or "Upgrade plan." Error tier recovery is a specific instruction with a direct action button: "Try again" or "Switch card." Critical tier recovery requires explicit, high-friction confirmation: typing the project name, checking a checkbox, or clicking a prominently labeled destructive button. The friction of the recovery action should match the severity of the error — low friction for low severity, high friction for critical severity.
+
+## Details
+
+### Severity Tier Matrix
+
+The tier determines both the visual component (snackbar, banner, modal, inline) and the copy register. Info messages can appear in snackbars. Critical messages require blocking modals with explicit confirmation.
+
+| Tier     | Visual     | Persistence    | Copy Pattern                                 | Example                                       |
+| -------- | ---------- | -------------- | -------------------------------------------- | --------------------------------------------- |
+| Info     | Blue icon  | Dismissable    | Supplemental statement, lowercase            | "Your account is set to send weekly digests." |
+| Warning  | Amber icon | Persistent     | Direct statement of risk, period             | "Enabling this removes 2FA protection."       |
+| Error    | Red icon   | Until resolved | Named failure + recovery action              | "Payment failed. Try a different card."       |
+| Critical | Red block  | Blocking       | Named consequence + irreversibility + action | "This deletes all 47 projects permanently."   |
+
+### Escalation Patterns
+
+Severity should escalate when frequency or cumulative impact increases — not by time alone. The user's decision not to act is the trigger for escalation:
+
+- **First occurrence:** Info or warning level. "Your trial ends in 14 days."
+- **Second occurrence / midpoint:** Warning level with more urgency. "Trial ends in 7 days. Upgrade to keep your data."
+- **Final occurrence / threshold:** Error or critical level. "Trial ends tomorrow. Add billing now to prevent data loss."
+- **Post-threshold:** Critical with immediate action. "Your access has ended. Export data before deletion in 24 hours."
+
+This pattern is used by Stripe, GitHub, and Figma for trial expiration, usage limits, and quota warnings. Each message escalates in severity, visual treatment, and copy directness. Escalation copy must name the specific consequence at each stage — "data loss," "access lost," "files deleted" — so users understand why escalation is happening.
+
+### Recovery Urgency Mapping
+
+Recovery instructions must match the urgency of the error:
+
+- **Info:** Optional follow-up. "Learn more" or "Manage preferences."
+- **Warning:** Clear action with low friction. "Upgrade plan" or "Enable backup."
+- **Error:** Specific recovery step. "Try again" or "Use a different method."
+- **Critical:** Immediate, high-friction action required. "Confirm deletion by typing the project name below."
+
+Recovery actions at the critical tier should require active confirmation — a checkbox, a typed confirmation, or an explicit button press. Auto-recovery (the system fixes it silently) is acceptable for info and warning tiers. For error and critical tiers, the user must take the recovery action explicitly so they understand what happened and are not surprised by the outcome.
+
+### Severity Calibration Checklist
+
+Before assigning a severity tier, answer these questions:
+
+1. Does this block the user from continuing their primary task? (No → Info or Warning; Yes → Error or Critical)
+2. Is there a risk of data loss or irreversible action? (No → Info or Warning; Yes → Critical)
+3. Is user action required to resolve? (No → Info; Yes → Warning, Error, or Critical based on blocking status)
+4. Will the system recover automatically? (Yes → Info or Warning; No → Error or Critical)
+5. Has the user already ignored a lower-severity version of this message? (Yes → escalate one tier)
+
+### Anti-Patterns
+
+1. **The Boy Who Cried Wolf.** Every error styled as critical — red icons, bold text, alarming language — even for routine validation like "password too short" or "email already in use." When the severity design is overused, users stop reading error messages. They click the prominent button to dismiss and move on. Reserve red and blocking patterns for genuine errors. Slack uses this well: routine validation is subtle (red border, small inline text), while account-level issues use prominent banners. If every error looks like an emergency, real emergencies are ignored.
+
+2. **The Calm Catastrophe.** Data loss warnings that use the same casual tone as field validation messages. "You might lose some changes" uses hedged language ("might," "some") for what could be a significant data loss event. GitHub's repository deletion confirmation does the opposite: it names exactly what will be lost, states "This action CANNOT be undone," and requires typing the repository name before proceeding. When data is genuinely at risk, the copy must reflect the stakes unambiguously. Hedging language on critical messages is more dangerous than no warning at all.
+
+3. **The Severity Mismatch.** Red error styling on informational messages like "Email already subscribed (you'll continue to receive emails)" or warnings styled as errors when no action is blocked. The mismatch between visual severity (red) and actual consequence (information, not a failure) confuses users and erodes their ability to calibrate the importance of future messages. Visual severity and copy severity must always be consistent — if the visual says "critical," the copy must name a critical consequence. If the consequence is minor, use a minor-tier visual component.
+
+4. **The Undifferentiated Escalation.** Using only visual treatment to escalate (changing from blue to amber to red) without escalating the copy. "Free plan" in blue, then "Free plan" in amber, then "Free plan" in red — same text, changing color — communicates nothing specific about why the urgency is increasing. Copy must escalate alongside visuals: "14 days remaining" → "3 days remaining. Upgrade to keep access" → "Access ends tomorrow." The user should understand from the copy alone, without the visual treatment, that the situation has become more urgent.
+
+### Real-World Examples
+
+**Figma's Autosave Conflict Resolution.** When two editors modify the same frame simultaneously, Figma shows a warning-tier message: "Someone else made changes to this file. We've created a duplicate to preserve your work." The tone is calm because data is not lost — both versions are preserved. If instead Figma had lost one version, the message would escalate to critical: "Your changes from the last 10 minutes could not be saved due to a conflict." The distinction is consequential: the first requires a choice, the second requires recovery. Figma's severity calibration turns on whether data is lost, not just whether a conflict occurred.
+
+**AWS Console's Tiered Alert System.** AWS uses four distinct alert components across its console: blue informational banners for best-practice suggestions, amber warnings for configuration issues that could cause problems, red error banners for failures requiring attention, and blocking red modals for destructive operations like terminating production instances. Each tier uses consistent language patterns across all AWS services. An error banner always names the failed resource, states the error type, and links to documentation. This consistency means experienced AWS users can triage alerts by visual tier before reading the content — which is the goal of any severity system.
+
+**VS Code's Problem Panel Severity Levels.** VS Code's Problems panel sorts issues by severity (errors > warnings > info) and uses distinct iconography for each. Error messages in the panel name the specific file and line, describe the issue precisely ("Property 'id' does not exist on type 'User'"), and link to the offending code. Warning messages use softer language ("Consider using const instead of let") because they do not block compilation. The panel's sorting by severity means users address blockers first, then non-blocking issues — a natural triage workflow enforced by the severity system itself.
+
+**Stripe's Quota and Billing Escalation.** Stripe's usage-based billing warnings escalate from info (first approach to limit), to warning (near limit), to error (at limit, some features blocked), to critical (over limit, service may be interrupted). Each tier's message escalates in specificity: "Approaching your monthly limit" → "80% of your monthly limit used" → "Monthly limit reached. New charges are being blocked" → "Account suspended. Contact support to restore access." The copy names the specific consequence at each stage, giving merchants the information they need to act proportionally to the urgency.
+
+## Source
+
+- NNGroup — "Indicators, Validations, and Notifications: Pick the Correct Communication Option" (2015), https://www.nngroup.com/articles/indicators-validations-notifications/
+- Apple Human Interface Guidelines — Alerts and notifications, https://developer.apple.com/design/human-interface-guidelines/alerts
+- Google Material Design — Snackbar, banner, and dialog severity guidelines, https://m3.material.io/components/snackbar/guidelines
+- Yifrah, K. — _Microcopy: The Complete Guide_ (2017), severity calibration in error copy
+- Podmajersky, T. — _Strategic Writing for UX_ (2019), escalation patterns and severity tiers
+
+### Writing Severity Copy for Different User Expertise Levels
+
+Severity communication must account for the user's expertise with the domain, not just the technical severity of the event:
+
+- **Expert users** in developer tools can tolerate more technical specificity in error copy. "Build failed: TypeScript compilation error in auth.ts:47" is appropriate for a VS Code user. The severity is communicated by the error tier, not by adding alarm language.
+- **Non-expert users** in consumer products need consequence-focused language. "Your payment didn't go through" communicates severity through consequence, not technical codes.
+- **Mixed audiences** (Stripe, which serves both technical integrators and non-technical business users) need severity tiers that work both ways: the visual tier communicates to non-readers, the copy details communicate to readers.
+
+The severity tier must work visually before the user reads the copy. Experienced users triage by visual tier; new users read. Both pathways must lead to the same understanding of severity.
+
+## Process
+
+1. Classify the error into one of the four severity tiers (info, warning, error, critical) based on whether it blocks action and whether it risks data loss.
+2. Select the appropriate visual component for the tier — inline text, snackbar, banner, or blocking modal.
+3. Write copy that matches the tier's register: supplemental for info, direct for warning, recovery-focused for error, urgent-specific for critical.
+4. Verify the visual styling and copy severity are consistent — no alarming language with calm visual treatment, or vice versa.
+5. Check whether the error is part of an escalation sequence and calibrate the copy to the current stage of that sequence.
+
+### Severity Audit: Common Misclassifications
+
+Products commonly misclassify these events — use this table to calibrate:
+
+| Event                           | Common Misclassification | Correct Tier   | Reason                                              |
+| ------------------------------- | ------------------------ | -------------- | --------------------------------------------------- |
+| Password too short (validation) | Error                    | Field inline   | Not blocking the session, only the submit action    |
+| Email already registered        | Error                    | Field inline   | Recoverable — user can log in instead               |
+| File exceeds size limit         | Error                    | Warning        | Blocks the specific upload but not other actions    |
+| Subscription payment failed     | Warning                  | Error          | Blocks access — requires immediate recovery action  |
+| Repository about to be deleted  | Warning                  | Critical       | Irreversible — requires maximum friction            |
+| Trial ends in 14 days           | Critical                 | Info           | No immediate action required; 14 days is not urgent |
+| Trial ends tomorrow             | Info                     | Error/Critical | Requires action; delay has real consequence         |
+| Background sync delay           | Error                    | Info           | Not blocking user; user can continue working        |
+| Deployment failed on production | Warning                  | Error          | Production failures require immediate attention     |
+
+Reviewing this table against your product's existing error states will surface the most common misclassifications. The pattern: products over-use red for validation and under-use red for billing and data loss events.
+
+## 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
+
+- Each error or warning uses one of the four severity tiers with appropriate visual and copy treatment.
+- Critical severity messages name the specific data at risk, state irreversibility, and require explicit user action.
+- No routine validation error (password too short, field required) uses critical or error styling.
+- System errors include timeline information when available (retry timing, status link, incident status).
+- Escalation sequences increase severity language at each stage, not only visual treatment.
+- Visual severity and copy severity are always consistent — no mismatch between the component used and the language used.

package/dist/agents/skills/cursor/ux-error-severity/skill.yaml

@@ -0,0 +1,35 @@
+name: ux-error-severity
+version: "1.0.0"
+description: Error severity communication — calibrating error tone to severity, from field validation to system failure to data loss
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - ux-error-messages
+  - ux-microcopy-principles
+  - ux-voice-tone
+  - design-feedback-patterns
+stack_signals: []
+keywords:
+  - error-severity
+  - validation
+  - system-errors
+  - data-loss
+  - warning-levels
+  - tone-calibration
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ux-form-labels/SKILL.md

@@ -0,0 +1,159 @@
+# Form Labels and Helper Text
+
+> Form labels and helper text — label clarity, placeholder anti-patterns, required-field indication, and writing forms that users complete without confusion
+
+## When to Use
+
+- Writing form field labels and their associated descriptions
+- Adding helper text, hints, or format examples below input fields
+- Deciding what to put in placeholder text versus labels versus helper text
+- Indicating required versus optional fields across a form
+- Writing fieldset legends and form section headers
+- Designing multi-step form field disclosure sequences
+- NOT for: form validation error messages (see ux-error-messages)
+- NOT for: form layout, field ordering, and visual design decisions (see design-form-ux)
+- NOT for: form CTA buttons and submit labels (see ux-button-cta-copy)
+
+## Instructions
+
+1. **Labels must be visible at all times — never rely on placeholder text as the only label.** Placeholders disappear on focus, leaving users without context about what a field requires — especially during editing or review. This is both a UX failure and an accessibility failure. Screen readers may not reliably read placeholder text as field labels. WCAG 1.3.1 requires that label information be programmatically determinable, which placeholder-as-label violates. Stripe, GitHub, and Shopify all use visible above-field labels alongside placeholder text. When a user is copying a 16-digit card number from their wallet and needs to glance away from the screen, the label must still be visible when they return.
+
+2. **Use the shortest unambiguous label.** "Email" not "Email address" if context is clear. "Full name" not "Please enter your first and last name in this field." "Company" not "Company or organization name." The label is a scannable identifier, not an explanation. Stripe's payment form: "Card number" — two words. Every additional word is a tax on the user's attention. If the short form is ambiguous (would "Name" mean first name or full name?), use the minimum additional words needed to disambiguate ("Full name," not "Please enter your complete legal name as it appears on your ID"). Ambiguity is resolved by adding the one word that clarifies — not by adding an explanation.
+
+3. **Place helper text below the field, not above.** Helper text above competes visually with the label and disrupts the reading flow from label to input. Below the field, helper text acts as post-input support — visible when the user is filling in the field, out of the way during scanning. GitHub places "This will be the name of your repository" directly below the repository name input. Stripe places card format hints below the card number input. The exception: pre-conditions that prevent even attempting to fill a field ("You can only do this once a month") should appear above or as a warning before the field, because the user should know before they attempt to type.
+
+4. **Use placeholders only for format examples, never for instructions.** The correct use of placeholder text is demonstrating the expected format. Good placeholders: "jane@example.com" (email format), "MM / YY" (card expiry format), "+1 (555) 123-4567" (phone format), "ACME-2024" (reference format). Bad placeholders: "Enter your email address" (instruction that disappears), "Your company website" (label restatement), "e.g., Marketing Manager" (example that belongs in helper text). The placeholder should show the user what their actual data should look like — not tell them what to do. If removing the placeholder would confuse the user, the label is doing insufficient work.
+
+5. **Mark the minority, not the majority.** If most fields in a form are required, mark only the optional ones with "(optional)" in the label. If most fields are optional, mark only the required ones with an asterisk (_) and explain the convention once ("_ Required"). Never mark both required and optional — pick the convention that produces fewer marks. Marking everything creates noise; marking only exceptions creates signal. Stripe's payment form marks nothing — all fields are required and self-evidently so. GitHub's profile form marks optional fields only, since most fields are optional. The rule: the mark should appear on the minority of fields, whichever type that is.
+
+6. **Group related fields with clear section headers.** A form with more than 6-8 fields should be organized into named sections. "Billing information," "Shipping address," "Payment method" are sections in a checkout form — not a flat list of 15 fields. Section headers function as fieldset legends: they provide context for the group of fields that follows. Shopify's checkout separates contact, shipping, and payment into clearly headed sections, each with its own visual container. Section headers also enable the user to jump to a specific section without reading every field, which is especially important on mobile where scrolling is required.
+
+7. **Show constraints before the user encounters them.** Helper text that reveals constraints after an error is too late. "Must be at least 8 characters, include one number and one uppercase letter" should appear below the password field before the user has typed anything. This preemptive disclosure prevents errors before they happen — the most efficient form of error prevention. Stripe shows card number format hints before the user enters any digits. GitHub shows username constraints (alphanumeric, hyphens allowed, 1-39 characters) in helper text before submission. The only exception: constraints that depend on the user's input value itself (e.g., "That username is taken") cannot be preemptively shown.
+
+8. **Adapt labels to locale and context when the field meaning changes.** Shopify dynamically changes "ZIP code" to "Postcode" for UK addresses and "Postal code" for Canadian addresses — because the underlying concept and format differ by country. When the same field collects different information depending on context (country, plan type, user role), the label must reflect the specific variant. Generic labels like "Postal identifier" that try to cover all cases end up serving none of them well. Context-adaptive labels are a form of microcopy precision: the label is correct for the specific user filling it out, not correct in the abstract.
+
+## Details
+
+### Label vs Placeholder vs Helper Text
+
+Three distinct text elements serve three distinct purposes in forms. Each must add distinct value — if two elements say the same thing, one of them should be removed or rewritten.
+
+| Element     | Purpose                         | Persistent? | Example                                      |
+| ----------- | ------------------------------- | ----------- | -------------------------------------------- |
+| Label       | Names the field                 | Always      | "Email address"                              |
+| Placeholder | Shows expected format           | Until typed | "jane@example.com"                           |
+| Helper text | Adds context, constraints, tips | Always      | "Use the email associated with your account" |
+
+A common mistake is using all three to say the same thing:
+
+- Label: "Name"
+- Placeholder: "Enter your name"
+- Helper text: "Type your name here"
+
+Each should add distinct value:
+
+- Label: "Full name" (disambiguates — full, not first)
+- Placeholder: "Jane Smith" (shows the expected format)
+- Helper text: "As it appears on your government ID" (adds context not available from the label)
+
+### Required and Optional Field Indication Patterns
+
+**When most fields are required:** Mark only optional fields with "(optional)" in the label, immediately following the label text. "Middle name (optional)." Do not use asterisks for required fields when only 1-2 fields are optional — the mark on the exception is clearer than marks on the rule.
+
+**When most fields are optional:** Mark only required fields with an asterisk (_) and include a legend once at the top of the form: "_ Required." Do not mark optional fields at all — their unmarked state is the convention.
+
+**Mixed forms with no clear majority:** Use "(optional)" on optional fields and asterisks on required fields with a legend. This is the most explicit approach and works when the balance is roughly 50/50.
+
+**Never:** Use both asterisks and "(optional)" in the same form — users must infer the convention from the pattern, and using both creates ambiguity about which convention takes precedence.
+
+### Accessibility Requirements for Form Labels
+
+Labels must be programmatically associated with their inputs or they are invisible to assistive technologies:
+
+- Use `<label for="input-id">` or wrap the input in `<label>` — do not use visual proximity alone.
+- Placeholder text must NOT be the only label. It fails WCAG 1.3.1 because it disappears and may not be read by all assistive technologies.
+- Helper text should be associated via `aria-describedby` so screen readers read both the label and the helper text when the field is focused.
+- Error messages must be associated via `aria-describedby` or `aria-errormessage` and marked with `role="alert"`.
+- Required fields should use both the `required` attribute and a visible indicator — do not rely on HTML required alone without a visible signal.
+
+### Helper Text Character Limits
+
+Helper text has spatial and cognitive limits by form context:
+
+| Form Type        | Helper Text Limit | Example                                               |
+| ---------------- | ----------------- | ----------------------------------------------------- |
+| Simple inline    | 60 characters     | "Must be at least 8 characters"                       |
+| Standard form    | 100 characters    | "Use the email associated with your Stripe account"   |
+| Complex / wizard | 150 characters    | "This name will appear on invoices sent to customers" |
+| Settings form    | 200 characters    | "Changing this affects all team members immediately"  |
+
+When helper text exceeds the limit, consider whether the information belongs in a tooltip, a "Learn more" link, or inline documentation. Helper text that wraps to 4+ lines is probably documentation, not a hint.
+
+### Anti-Patterns
+
+1. **The Placeholder-as-Label.** Using placeholder text as the only label for a form field — no visible label above or beside the input. The placeholder disappears when the user clicks into the field, leaving them without context about what they were typing. Users who need to reference the field context while entering data (common for addresses, card numbers, and multi-field names) must clear their input to see the label again. This is a critical accessibility failure and consistently tested as one of the highest-friction patterns in form usability research. It is also a failure mode for users who tab between fields — the placeholder is gone before they begin typing.
+
+2. **The Redundant Stack.** Three text elements saying the same thing: label "Name," placeholder "Enter your name," helper text "Type your name here." Each element adds visual weight and reading time with no added value. The fix: use each element for a distinct purpose. Label names the field ("Full name"), placeholder demonstrates format ("Jane Smith"), helper text adds non-obvious context ("As shown on your ID"). Redundancy signals that the form was built by someone who was uncertain about what each element should do — the solution is to understand their distinct roles.
+
+3. **The Hidden Constraint.** Not revealing field requirements until after the user submits and receives a validation error. A password field with no helper text that, on error, reveals "Must be 8+ characters, include a number and uppercase letter." The user just had to fail to learn the rules. Move all constraints to helper text, visible before the user types. The only legitimate time to show constraints after the fact is when the constraint depends on the input value itself (e.g., "This username is already taken" cannot be preemptively shown because it depends on what the user typed).
+
+4. **The Instruction Placeholder.** Placeholder text that instructs ("Enter your email") rather than formats ("jane@example.com") or demonstrates ("ACME-2024"). Instruction placeholders disappear on focus, leaving users who paused mid-entry without context. They also waste the placeholder's one legitimate use — demonstrating format. Instruction placeholders are almost always a sign that the label is doing insufficient work. The fix: strengthen the label to be descriptive, then use the placeholder for format demonstration only.
+
+### Real-World Examples
+
+**Stripe's Payment Form.** Stripe's payment form is a reference implementation of minimal, functional form labels. "Card number" is the label — not "16-digit credit or debit card number." The placeholder shows the format: "1234 1234 1234 1234." No helper text is needed because the label and placeholder together provide complete context. The expiry field placeholder "MM / YY" is the format instruction. The CVV placeholder "CVC" is the conventional abbreviation users recognize. Every text element earns its place; nothing is redundant. Stripe's checkout form has been through extensive usability testing, and the minimal labels are the result — earlier versions had more text, which was progressively removed as testing confirmed users did not need it.
+
+**GitHub's Repository Creation Form.** GitHub's repository creation form demonstrates proper helper text placement. Below the repository name field: "Great repository names are short and memorable. Need inspiration? How about super-potato?" The helper text serves three purposes: sets the standard (short, memorable), offers inspiration (how about X?), and adds a touch of personality consistent with GitHub's voice. Below the visibility options: "Public repositories are visible to anyone. Private repositories are only visible to you." The helper text is additive — not a restatement of the radio button labels but an explanation of the consequence of each choice.
+
+**Shopify's Address Form Patterns.** Shopify's address forms demonstrate best-in-class required/optional field handling. All required fields are marked with asterisks (\*) and a legend explains the convention once at the form start. The "Address line 2" field is explicitly marked "(optional)" — because it is the exception in an otherwise-required form. Shopify also dynamically adjusts form fields based on selected country (postal code format, state/province terminology), with label text that adapts: "ZIP code" for US addresses, "Postcode" for UK addresses, "Postal code" for Canada. This locale-adaptive labeling is invisible when correct and jarring when wrong — Shopify gets it right.
+
+**Airbnb's Listing Setup Form.** Airbnb's property listing form handles a particularly complex scenario: dozens of fields across multiple sections, many optional, with constraints that vary by property type. Airbnb's approach: group fields into named sections with clear visual dividers ("Location," "Amenities," "House rules"), mark required fields with asterisks on a "required only" form where most fields are required, and provide contextual helper text that explains why the information is needed: "Guests will only see your neighborhood until they book" below the address field. The explanation of data use reduces user hesitation about privacy-sensitive fields.
+
+## Source
+
+- NNGroup — "Placeholders in Form Fields Are Harmful" (2014), https://www.nngroup.com/articles/form-design-placeholders/
+- Google Material Design — Text field guidelines, https://m3.material.io/components/text-fields/guidelines
+- Apple Human Interface Guidelines — Text fields, https://developer.apple.com/design/human-interface-guidelines/text-fields
+- W3C WCAG 2.1 — Success Criterion 1.3.1: Info and Relationships, https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships
+- Wroblewski, L. — _Web Form Design_ (2008), label placement research and required/optional field conventions
+
+## Process
+
+1. Inventory all form fields and classify each text element: label, placeholder, helper text.
+2. Verify every field has a persistent visible label — replace any placeholder-as-label with a real label.
+3. Assign each text element its specific role: label names, placeholder formats, helper text adds context or constraints.
+4. Audit required/optional indication — apply the minority-marking convention consistently across the form.
+5. Check programmatic label association (for="" or aria-describedby) for accessibility compliance.
+
+### Form Label Copy Review Checklist
+
+Before shipping any form, verify each item:
+
+| Check                                              | Pass Criteria                                       |
+| -------------------------------------------------- | --------------------------------------------------- |
+| All fields have persistent visible labels          | No placeholder-as-label in any field                |
+| Labels use shortest unambiguous form               | "Email" not "Email address" when context is clear   |
+| Placeholders show format only                      | "jane@example.com" not "Enter your email"           |
+| Helper text appears below fields                   | Not above, not inside the input                     |
+| Helper text adds unique value                      | Does not restate the label or placeholder           |
+| Constraints shown before submission                | Password rules visible before the user types        |
+| Required/optional marking uses minority convention | Only the minority type is marked                    |
+| Forms over 6-8 fields have section headers         | Named groups, not a flat 15-field list              |
+| Programmatic label association present             | for/id or aria-describedby on all inputs            |
+| Locale-sensitive fields adapt labels               | "ZIP code" vs "Postcode" by country when applicable |
+
+Form label audits consistently find placeholder-as-label as the most common violation. Running a quick audit by tabbing through a form with a screen reader reveals all label-association failures — any field that does not announce its label when focused has failed the accessibility check.
+
+## 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 field has a persistent visible label that is not reliant on placeholder text.
+- Placeholder text shows format examples only — no instructions or label restatements.
+- Helper text appears below each field and adds context not available from the label alone.
+- Required/optional indication uses the minority-marking convention consistently across the form.
+- All labels are programmatically associated with their inputs via for/id or aria-describedby.
+- Helper text that reveals constraints appears before the user types, not only after an error.

package/dist/agents/skills/cursor/ux-form-labels/skill.yaml

@@ -0,0 +1,36 @@
+name: ux-form-labels
+version: "1.0.0"
+description: Form labels and helper text — label clarity, placeholder anti-patterns, required-field indication, and writing forms that users complete without confusion
+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-plain-language
+  - ux-error-messages
+  - design-form-ux
+  - a11y-form-patterns
+stack_signals: []
+keywords:
+  - form-labels
+  - helper-text
+  - placeholder
+  - required-fields
+  - input-labels
+  - field-descriptions
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ux-inclusive-language/SKILL.md

@@ -0,0 +1,161 @@
+# Inclusive Language in UI
+
+> Inclusive language in UI — gender-neutral, ability-neutral, culture-aware writing, avoiding idioms that exclude
+
+## When to Use
+
+- Writing any user-facing text in a product used by a diverse audience
+- Reviewing existing UI text for gendered language, ableist metaphors, or cultural assumptions
+- Designing forms that collect personal information -- names, gender, titles, addresses
+- Writing error messages, help text, and onboarding copy that must work for all users
+- Creating onboarding flows that welcome users from different backgrounds and abilities
+- Building products that will be used in multiple countries, cultures, or language contexts
+- Updating legacy codebases and UI text that use outdated terminology (master/slave, whitelist/blacklist)
+- Writing accessibility-related UI text -- screen reader labels, skip navigation, alt text
+- NOT for: quoted content where the original language must be preserved
+- NOT for: legal text with specific legally defined terms that cannot be paraphrased
+
+## Instructions
+
+1. **Use "they/them" as the default singular pronoun in UI text.** When referring to a user whose gender is unknown or unspecified, use singular "they." "When a user logs in, they see their dashboard" -- not "he sees his dashboard" or "he or she sees his or her dashboard." GitHub, Slack, Stripe, and Google all adopted singular "they" in their style guides. The construction is grammatically established (used in English since the 14th century), shorter than "he or she," and inclusive of non-binary users. For direct address, prefer "you" -- "Your dashboard" is always better than "The user's dashboard."
+
+2. **Avoid ability-based metaphors in UI actions.** Standard UI verbs assume visual and physical ability: "see," "look at," "click," "drag," "watch." Replace them with ability-neutral alternatives that describe the cognitive action, not the physical one. "Check your settings" not "See your settings." "Select an option" not "Click an option." "Review the document" not "Look at the document." "Move the item" not "Drag the item." These alternatives work for screen reader users, keyboard-only users, and users with motor disabilities. They also happen to be more precise -- "review" implies cognitive evaluation, while "look at" only implies visual contact.
+
+   | Ability-specific (avoid) | Ability-neutral (prefer) |
+   | ------------------------ | ------------------------ |
+   | See the results          | View the results         |
+   | Look at the preview      | Review the preview       |
+   | Click the button         | Select the button        |
+   | Watch the video          | Play the video           |
+   | Hear the alert           | Receive the alert        |
+   | Walk through the steps   | Follow the steps         |
+   | Hands-on tutorial        | Interactive tutorial     |
+
+3. **Replace gendered defaults with neutral alternatives.** Language that assumes a default gender excludes people and reinforces stereotypes. Maintain a substitution list and apply it consistently:
+
+   | Gendered (avoid)    | Neutral (prefer)         |
+   | ------------------- | ------------------------ |
+   | mankind             | humanity, people         |
+   | man-hours           | person-hours, work hours |
+   | manpower            | workforce, staffing      |
+   | manned              | staffed, operated        |
+   | guys (as address)   | everyone, team, folks    |
+   | salesman            | salesperson, sales rep   |
+   | chairman            | chairperson, chair       |
+   | master/slave        | primary/replica          |
+   | blacklist/whitelist | blocklist/allowlist      |
+   | grandfathered       | legacy, exempt           |
+
+   GitHub renamed its default branch from "master" to "main" in 2020. The change was technically trivial (a configuration default) but symbolically significant -- it demonstrated that inclusive language in technical systems is achievable without disruption.
+
+4. **Avoid idioms that assume cultural context.** English-language idioms often assume familiarity with American culture, sports, or history. "Hit a home run" means nothing to a user in Germany. "Level the playing field" assumes knowledge of sports metaphors. "Grandfather clause" has roots in post-Civil War voter suppression. Replace idioms with direct language:
+
+   | Idiom (culturally bound) | Direct alternative             |
+   | ------------------------ | ------------------------------ |
+   | Hit a home run           | Succeeded, achieved the goal   |
+   | Move the needle          | Made measurable progress       |
+   | Low-hanging fruit        | Easy wins, quick tasks         |
+   | Drinking from a firehose | Overwhelming amount of info    |
+   | Boil the ocean           | Take on too much at once       |
+   | Circle back              | Return to this topic           |
+   | Open the kimono          | Share information              |
+   | Sanity check             | Quick review, confidence check |
+
+   Direct language is not only more inclusive -- it is more precise. "Quick review" is clearer than "sanity check" for any audience.
+
+5. **Use person-first or identity-first language based on community preference.** Different disability communities have different preferences. The Deaf community generally prefers identity-first ("deaf person"), while many other disability communities prefer person-first ("person with a disability"). When in doubt, use person-first language. In UI text, the best approach is often to focus on the situation, not the person: "If you use a screen reader" rather than "If you are a visually impaired person." This focuses on the tool and the experience, not the medical condition.
+
+6. **Design inclusive forms.** Forms are where inclusive language is most critical because they ask users to categorize themselves. Principles for inclusive forms:
+   - **Gender fields:** Provide "Prefer not to say" or "Prefer to self-describe" options. Never require binary gender selection. Only ask for gender when it is necessary for the product's function.
+   - **Name fields:** Use "Full name" or separate "Given name" and "Family name" instead of "First name" and "Last name" -- many cultures do not follow the Western first/last name convention. Support Unicode characters, hyphens, apostrophes, and spaces.
+   - **Title fields:** If a title is needed, make it optional and include gender-neutral options ("Mx."). Better yet, do not ask for titles at all -- most products do not need them.
+   - **Address fields:** Do not assume a country format. "State/Province/Region" accommodates more countries than "State." "Postal code" is more universal than "ZIP code."
+
+7. **Avoid violent metaphors in technical contexts.** Technical jargon often borrows from violent language: "kill the process," "terminate the connection," "abort the operation," "nuke the cache." In user-facing text, replace these with neutral alternatives: "end" or "stop" for "kill," "close" for "terminate," "cancel" for "abort," "clear" for "nuke." The violent metaphors are unnecessary -- the neutral alternatives are equally clear and do not carry the aggressive connotation. Apple's Human Interface Guidelines explicitly prohibit violent language in user-facing text.
+
+## Details
+
+### Inclusive Language Audit Checklist
+
+When reviewing existing UI text for inclusivity, check each item:
+
+- Are all pronouns gender-neutral (they/them) when the user's gender is unknown?
+- Do any UI actions assume physical ability (click, see, hear)?
+- Are there any gendered job titles or role names?
+- Do any idioms assume cultural context that non-Western users would not share?
+- Are form fields designed for global name formats, not just Western conventions?
+- Does the text avoid violent metaphors (kill, terminate, abort, nuke)?
+- Are disability references focused on the situation, not the person?
+- Is the text free of age-related assumptions ("even your grandmother could use it")?
+
+### Pronouns in UI Text
+
+The hierarchy of pronoun preference for UI text:
+
+1. **"You/your" (best).** Direct address eliminates the pronoun problem entirely. "Your dashboard" works for every user regardless of gender.
+2. **"They/their" (good).** When referring to a third party: "Ask your admin. They can grant you access."
+3. **Rephrase to avoid pronouns (good).** "The project owner can grant access" instead of "He or she can grant access."
+4. **"He or she" (avoid).** Wordy, binary, and excludes non-binary users. Never use in UI text.
+5. **Generic "he" (never).** Outdated and exclusionary. Never use in UI text.
+
+### Accessibility Language Patterns
+
+When writing UI text related to accessibility features:
+
+- **Screen reader labels:** Describe the function, not the disability. "Screen reader label" not "Blind user label." "Alternative text" not "Text for visually impaired users."
+- **Skip navigation:** "Skip to main content" is the standard phrasing. Do not elaborate with "for users who cannot see the navigation."
+- **Reduced motion:** "Reduce motion" not "For people with vestibular disorders." The setting name describes the action, not the medical condition.
+- **Keyboard navigation:** "Keyboard shortcuts" not "Alternative navigation for users who cannot use a mouse." Focus on the feature, not the reason someone might use it.
+
+The principle: accessibility features should be labeled by what they do, not by who needs them. This is both more inclusive and more useful -- sighted users also use keyboard shortcuts, and users without vestibular disorders may prefer reduced motion.
+
+### Anti-Patterns
+
+1. **The Gendered Default.** Using "he" or "his" as the default pronoun for unknown users. "When the admin reviews the request, he can approve or deny it." This pattern was once standard in English but is now recognized as exclusionary. It signals to non-male users that they are not the expected audience. The fix is simple and mechanical: replace "he" with "they" or restructure to use "you." "When you review the request, you can approve or deny it."
+
+2. **The Ableist Metaphor.** Using disability as a negative metaphor. "The interface is crippled without JavaScript." "That feature is lame." "Are you blind? The button is right there." These metaphors equate disability with failure, inadequacy, or incompetence. They are harmful to disabled users and imprecise for all users. The fix: describe the actual problem. "The interface has limited functionality without JavaScript." "That feature is ineffective." "The button is in the top-right corner."
+
+3. **The Cultural Assumption.** UI text that assumes all users share the same cultural references, holidays, seasonal context, or social norms. A "Happy Thanksgiving!" banner shown to users in Japan. A "Summer sale!" notification sent to users in the Southern Hemisphere where it is winter. Instructions that say "Call us during business hours" without specifying the timezone. Date formats that use MM/DD/YYYY (American) without considering that most of the world uses DD/MM/YYYY. The fix: design for the global user. Use ISO date formats or let users set their locale. Reference holidays only when the product is locale-specific. Always specify timezones.
+
+4. **The Tokenistic Inclusion.** Adding a single diverse emoji or stock photo to a product that otherwise uses exclusionary language throughout. Surface-level representation without substantive language changes is performative and can feel worse than no attempt at all -- it signals awareness without action. The fix: inclusive language is a systematic practice, not a decoration. Start with the language and terminology. Audit the entire product, not just the homepage.
+
+### Real-World Examples
+
+**Microsoft's Inclusive Writing Guide.** Microsoft published a comprehensive bias-free writing guide that their content teams use across all products. Key decisions: "they" as default singular pronoun, "select" instead of "click" (because touch and voice users do not click), "allowlist/blocklist" instead of "whitelist/blacklist," and person-first language for disability references. The guide includes specific examples for over 50 common patterns and is publicly available for other teams to reference. Microsoft's approach treats inclusive language as a content standard, not a suggestion -- it is enforced in code review the same way coding standards are.
+
+**GitHub's "main" Branch Rename.** In 2020, GitHub changed the default branch name from "master" to "main." The technical change was minimal -- one configuration default. The cultural impact was significant: it demonstrated that inclusive language changes in technical systems are feasible, low-cost, and symbolic of broader commitments. GitHub published a migration guide, provided tooling to update existing repositories, and set a timeline for the transition. The rename is now an industry-standard default adopted by GitLab, Bitbucket, and most open-source projects.
+
+**Slack's Inclusive Emoji and Language Patterns.** Slack supports diverse skin tone emoji, pronoun display in profiles, and uses inclusive language throughout its UI. Notification settings say "when someone mentions you" (gender-neutral). The team directory shows pronouns when users choose to display them, without making pronouns mandatory. Empty states say "No messages from anyone yet" rather than assuming a gendered pronoun for the hypothetical message sender. Slack's approach demonstrates that inclusive language can be systematic without being intrusive -- the changes are subtle, consistent, and respect user choice.
+
+**Apple's Human Interface Guidelines on Inclusion.** Apple's HIG dedicates a section to inclusive language with specific guidance: use "select" instead of "click" to accommodate touch, voice, and switch control users. Use "turn on" and "turn off" instead of "enable" and "disable" (which carry ability connotations). Refer to people, not users -- "people who use your app" rather than "your users." Apple's guidelines treat inclusive language as a design requirement, not optional polish, and enforce it across all first-party apps as part of their App Review process.
+
+## Source
+
+- Microsoft Writing Style Guide -- Bias-free communication, https://learn.microsoft.com/en-us/style-guide/bias-free-communication
+- W3C WCAG -- Cognitive accessibility guidelines, language clarity requirements
+- Google Developer Documentation Style Guide -- Inclusive language section, https://developers.google.com/style/inclusive-documentation
+- 18F Content Guide -- Inclusive language, https://content-guide.18f.gov/inclusive-language/
+- Apple Human Interface Guidelines -- Inclusion section, ability-neutral language guidance
+- Conscious Style Guide -- https://consciousstyleguide.com, comprehensive resource for bias-free writing
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Audit existing UI text using the inclusive language checklist in this document.
+3. Apply the substitution tables for gendered terms, ableist metaphors, and cultural idioms.
+4. Review all forms for inclusive field design (names, gender, titles, addresses).
+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
+
+- All UI text uses "they/them" or "you/your" -- no gendered pronouns for unknown users.
+- No ableist metaphors appear in user-facing text -- all actions use ability-neutral verbs.
+- All gendered defaults are replaced with neutral alternatives.
+- Forms use inclusive field labels and do not require binary gender selection.
+- No cultural idioms appear in UI text -- all language is direct and globally accessible.
+- Violent technical metaphors are replaced with neutral alternatives in user-facing text.

package/dist/agents/skills/cursor/ux-inclusive-language/skill.yaml

@@ -0,0 +1,33 @@
+name: ux-inclusive-language
+version: "1.0.0"
+description: Inclusive language in UI — gender-neutral, ability-neutral, culture-aware writing, avoiding idioms that exclude
+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-voice-tone
+  - ux-internationalization-writing
+stack_signals: []
+keywords:
+  - inclusive-language
+  - gender-neutral
+  - accessibility
+  - bias-free
+  - culture-aware
+metadata:
+  author: community
+state:
+  persistent: false
+  files: []
+depends_on: []