From harness-claude
Provides guidelines for writing clear form labels, helper text, required field indicators, and avoiding placeholder anti-patterns for accessible, confusion-free forms.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeThis skill uses the workspace's default tool permissions.
> Form labels and helper text — label clarity, placeholder anti-patterns, required-field indication, and writing forms that users complete without confusion
Guides form UX design with single-column layouts, optimal validation timing (blur/keystroke/submit), smart defaults, error recovery, progressive disclosure, and WCAG accessibility to reduce abandonment.
Improves unclear UX copy, error messages, microcopy, labels, and instructions for better interface clarity. Useful when refining confusing text or bad UX writing.
Crafts production-ready UI microcopy: button labels, error messages, tooltips, empty states, onboarding flows, and confirmation dialogs. For in-product text only.
Share bugs, ideas, or general feedback.
Form labels and helper text — label clarity, placeholder anti-patterns, required-field indication, and writing forms that users complete without confusion
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.
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.
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.
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.
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.
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.
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.
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.
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:
Each should add distinct value:
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.
Labels must be programmatically associated with their inputs or they are invisible to assistive technologies:
<label for="input-id"> or wrap the input in <label> — do not use visual proximity alone.aria-describedby so screen readers read both the label and the helper text when the field is focused.aria-describedby or aria-errormessage and marked with role="alert".required attribute and a visible indicator — do not rely on HTML required alone without a visible signal.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.
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.
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.
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).
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.
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.
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.