Skip to content

ericrisco/rsc-harness / skills/ux

Use when an app or SaaS must be easy to use: designing complete user flows, screens and every state, navigation, forms, onboarding, tables, dashboards, search or AI features, or auditing usability and accessibility. Anyone finishes the job without a manual; experts go fast. NOT the visual direction (design), NOT the words (landing-copy).

FileKindSize
SKILL.mdskill md9.3 KB
THIRD_PARTY.mdmarkdown1.6 KB
evals/cases.yamlconfig2.5 KB
references/flows.mdmarkdown7.3 KB
upstream/UPSTREAM.jsonconfig4.7 KB
upstream/ux-designer/GUIDE.mdmarkdown15.2 KB
upstream/ux-designer/LICENSEother1.0 KB
upstream/ux-designer/references/01-core-principles.mdmarkdown7.9 KB
upstream/ux-designer/references/02-laws-of-ux.mdmarkdown8.3 KB
upstream/ux-designer/references/03-accessibility.mdmarkdown10.7 KB
upstream/ux-designer/references/04-visual-design.mdmarkdown8.9 KB
upstream/ux-designer/references/05-information-architecture.mdmarkdown9.1 KB
upstream/ux-designer/references/06-interaction-design.mdmarkdown11.2 KB
upstream/ux-designer/references/07-forms-and-inputs.mdmarkdown11.4 KB
upstream/ux-designer/references/08-mobile-ux.mdmarkdown10.9 KB
upstream/ux-designer/references/09-ux-writing.mdmarkdown9.0 KB
upstream/ux-designer/references/10-user-research.mdmarkdown10.6 KB
upstream/ux-designer/references/11-design-systems.mdmarkdown13.2 KB
upstream/ux-designer/references/12a-presence-awareness.mdmarkdown10.2 KB
upstream/ux-designer/references/12b-conflict-resolution-sync.mdmarkdown15.8 KB
upstream/ux-designer/references/13a-canvas-navigation.mdmarkdown9.5 KB
upstream/ux-designer/references/13b-canvas-objects-performance.mdmarkdown14.2 KB
upstream/ux-designer/references/14-ai-ux-patterns.mdmarkdown20.9 KB
upstream/ux-designer/references/15-ethical-design.mdmarkdown13.9 KB
upstream/ux-designer/references/16-onboarding.mdmarkdown16.5 KB
upstream/ux-designer/references/17-notifications.mdmarkdown17.7 KB
upstream/ux-designer/references/18-data-visualization.mdmarkdown18.8 KB
upstream/ux-designer/references/19-search-ux.mdmarkdown19.0 KB
upstream/ux-designer/references/20-emotional-design.mdmarkdown14.5 KB
upstream/ux-designer/references/21-data-tables.mdmarkdown20.5 KB
upstream/ux-designer/references/22-performance-ux.mdmarkdown17.5 KB
upstream/ux-designer/references/23-internationalization.mdmarkdown15.4 KB
upstream/ux-designer/references/24-voice-and-multimodal.mdmarkdown15.9 KB
upstream/ux-designer/references/25a-barcode-camera-scanning.mdmarkdown21.3 KB
upstream/ux-designer/references/25b-barcode-scanner-workflows.mdmarkdown25.3 KB
upstream/ux-designer/references/25c-barcode-display.mdmarkdown17.3 KB
upstream/ux-usability-foundations/GUIDE.mdmarkdown16.0 KB
upstream/ux-usability-foundations/LICENSEother1.0 KB
upstream/ux-usability-foundations/references/anti-patterns.mdmarkdown8.3 KB
upstream/ux-usability-foundations/references/checklists.mdmarkdown6.2 KB
upstream/ux-usability-foundations/references/decision-prompts.mdmarkdown10.0 KB
upstream/ux-usability-foundations/references/principle-cards.mdmarkdown15.4 KB

upstream/ux-designer/references/07-forms-and-inputs.md

View on GitHub
# Forms & Input Design

Forms are often where users complete their goals—signing up, checking out, submitting data. Good form design directly impacts conversion rates and user satisfaction.

---

## Contents

- Form Design Principles
- Labels and Placeholders
- Input Types
- Validation
- Required Fields
- Multi-Step Forms
- Specific Field Patterns
- Form Layout
- Submit Buttons
- Accessibility Checklist
- Sources

---

## Form Design Principles

### Evidence

Baymard's checkout research repeatedly finds that the average checkout shows roughly twice as many fields as needed, and that "too long / complicated checkout" is a top-cited abandonment reason. Treat widely quoted single figures (e.g. "81% abandon forms", "multi-step raises completion 86%") as unsourced marketing numbers — measure your own funnel instead.

### Fundamental Principles

1. **Ask only what you need** - Every field is friction
2. **Group related fields** - Logical chunking
3. **One column is usually best** - Easier scanning
4. **Clear labels** - No placeholder-only labels
5. **Smart defaults** - Pre-fill when possible
6. **Progressive disclosure** - Show fields when relevant

---

## Labels and Placeholders

### Labels

```html
<!-- Always use labels (not just placeholders) -->
<div class="form-field">
  <label for="email">Email address</label>
  <input type="email" id="email" name="email" />
</div>

<!-- Label placement -->
<!-- Top-aligned: Best for long forms, mobile -->
<!-- Left-aligned: Good for short forms, scanning -->
<!-- Right-aligned: Avoid (harder to scan) -->
```

**Best Practices:**
- Position labels above inputs (top-aligned)
- Keep labels short and clear
- Don't end with colons (modern convention)
- Associate with `for` attribute

### Placeholders

```html
<!-- Use for hints, not labels -->
<input
  type="email"
  placeholder="you@example.com"
  aria-label="Email address"
/>

<!-- Never use as the only label -->
<!-- Disappears on focus, causing confusion -->
```

**Placeholder Guidelines:**
- Show example format, not label
- Use gray text (but not too light)
- Don't rely on it for critical info
- Disappears—users may forget what field is

---

## Input Types

### HTML5 Input Types

```html
<!-- Use appropriate types for mobile keyboards and validation -->
<input type="text" />       <!-- Default -->
<input type="email" />      <!-- Email keyboard -->
<input type="tel" />        <!-- Phone keyboard -->
<input type="number" />     <!-- Numeric keyboard -->
<input type="url" />        <!-- URL keyboard -->
<input type="password" />   <!-- Hidden characters -->
<input type="search" />     <!-- Search field -->
<input type="date" />       <!-- Date picker -->
<input type="time" />       <!-- Time picker -->
<input type="datetime-local" /> <!-- DateTime picker -->
```

### Input Attributes

```html
<input
  type="email"
  name="email"
  id="email"
  required                    <!-- Validation -->
  aria-required="true"        <!-- Accessibility -->
  autocomplete="email"        <!-- Autofill hint -->
  inputmode="email"          <!-- Keyboard hint -->
  pattern="[^@]+@[^@]+\.[^@]+" <!-- Custom validation -->
  placeholder="you@example.com"
/>
```

### Autocomplete Values

```html
<!-- Enable browser autofill -->
<input autocomplete="given-name" />    <!-- First name -->
<input autocomplete="family-name" />   <!-- Last name -->
<input autocomplete="email" />
<input autocomplete="tel" />
<input autocomplete="street-address" />
<input autocomplete="postal-code" />
<input autocomplete="cc-number" />     <!-- Credit card -->
<input autocomplete="new-password" />  <!-- For password creation -->
<input autocomplete="current-password" /> <!-- For login -->
```

---

## Validation

### Validation Timing

| Timing | Pros | Cons | Best For |
|--------|------|------|----------|
| On blur | Immediate feedback | Can feel aggressive | Most fields |
| On submit | Low friction | Delayed error discovery | Short forms |
| On input | Real-time | Annoying while typing | Password strength |
| Hybrid | Balanced | Complex to implement | Professional forms |

### Recommended Approach

```javascript
// Validate on blur (when user leaves field)
// Don't validate while typing
// Re-validate on correction

input.addEventListener('blur', validate);
input.addEventListener('input', () => {
  // Only clear errors while typing if previously invalid
  if (hasError) validate();
});
```

### Error Messages

```html
<!-- Good: Specific, actionable -->
<span class="error">
  Please enter a valid email address (e.g., name@example.com)
</span>

<!-- Bad: Vague, unhelpful -->
<span class="error">Invalid input</span>
```

**Error Message Guidelines:**
- Place near the field (below or inline)
- Use red color + icon (not color alone)
- Be specific about what's wrong
- Suggest how to fix
- Use human-friendly language
- Don't blame the user

### Visual Error Indicators

```css
.input-error {
  border-color: #dc3545;
  background-color: #fff8f8;
}

.error-message {
  color: #dc3545;
  font-size: 0.875rem;
  margin-top: 0.25rem;
  display: flex;
  align-items: center;
  gap: 0.25rem;
}

.error-message::before {
  content: "⚠️";
}
```

### Accessibility for Errors

```html
<div class="form-field">
  <label for="email">Email</label>
  <input
    type="email"
    id="email"
    aria-describedby="email-error"
    aria-invalid="true"
  />
  <span id="email-error" role="alert">
    Please enter a valid email address
  </span>
</div>
```

---

## Required Fields

### Marking Required Fields

```html
<!-- Visual indicator -->
<label for="name">
  Name <span class="required" aria-hidden="true">*</span>
  <span class="sr-only">(required)</span>
</label>

<!-- Alternative: Mark optional fields -->
<label for="phone">
  Phone <span class="optional">(optional)</span>
</label>
```

**Convention:**
- If most fields required: mark optional
- If most fields optional: mark required
- Use asterisk (*) for required
- Explain asterisk at form start

---

## Multi-Step Forms

### When to Use

- Long forms (7+ fields)
- Complex processes (checkout, applications)
- Collecting different types of info
- Reducing cognitive load

### Progress Indicator

```html
<nav aria-label="Form progress">
  <ol class="steps">
    <li class="completed" aria-current="false">
      <span class="step-number">1</span>
      <span class="step-label">Personal Info</span>
    </li>
    <li class="current" aria-current="step">
      <span class="step-number">2</span>
      <span class="step-label">Shipping</span>
    </li>
    <li class="upcoming" aria-current="false">
      <span class="step-number">3</span>
      <span class="step-label">Payment</span>
    </li>
  </ol>
</nav>
```

### Best Practices

- Show step count (Step 2 of 4)
- Allow going back to previous steps
- Save progress automatically
- Validate each step before proceeding
- Keep navigation visible
- Allow skipping optional sections

---

## Specific Field Patterns

### Password Fields

```html
<div class="password-field">
  <label for="password">Password</label>
  <div class="input-wrapper">
    <input
      type="password"
      id="password"
      autocomplete="new-password"
      minlength="8"
    />
    <button type="button" class="toggle-visibility">
      Show
    </button>
  </div>
  <div class="password-strength" aria-live="polite">
    <!-- Strength indicator -->
  </div>
  <ul class="password-requirements">
    <li>At least 8 characters</li>
    <li>One uppercase letter</li>
    <li>One number</li>
  </ul>
</div>
```

### Phone Numbers

```html
<input
  type="tel"
  inputmode="numeric"
  autocomplete="tel"
  placeholder="(555) 123-4567"
/>

<!-- Consider: -->
<!-- - Auto-format as user types -->
<!-- - Accept various formats -->
<!-- - Show expected format -->
```

### Credit Cards

```html
<input
  type="text"
  inputmode="numeric"
  autocomplete="cc-number"
  pattern="[\d ]{13,19}"
  placeholder="1234 5678 9012 3456"
  maxlength="19"
/>

<!-- Auto-format with spaces -->
<!-- Detect card type from number -->
<!-- Show card icon -->
```

### Addresses

```html
<input
  type="text"
  autocomplete="address-line1"
  placeholder="Street address"
/>

<!-- Consider: -->
<!-- - Address autocomplete (Google Places) -->
<!-- - Country-specific formats -->
<!-- - Postal code lookup -->
```

### Date Selection

```html
<!-- Native date picker -->
<input type="date" />

<!-- Or custom for better UX -->
<input
  type="text"
  placeholder="MM/DD/YYYY"
  inputmode="numeric"
/>

<!-- Consider: -->
<!-- - Relative dates ("Today", "Tomorrow") -->
<!-- - Date range pickers -->
<!-- - Mobile-friendly selectors -->
```

---

## Form Layout

### Single Column

```
┌─────────────────────────────┐
│ First Name                  │
├─────────────────────────────┤
│ Last Name                   │
├─────────────────────────────┤
│ Email                       │
├─────────────────────────────┤
│ [Submit]                    │
└─────────────────────────────┘

Best for: Mobile, most web forms
```

### Multi-Column (Use Sparingly)

```
┌──────────────┬──────────────┐
│ First Name   │ Last Name    │
├──────────────┴──────────────┤
│ Email                       │
├──────────────┬──────────────┤
│ City         │ State │ Zip  │
└──────────────┴──────────────┘

Use for: Related short fields
Avoid: Different topics side by side
```

### Grouping

```html
<fieldset>
  <legend>Shipping Address</legend>
  <!-- Address fields -->
</fieldset>

<fieldset>
  <legend>Billing Address</legend>
  <!-- Address fields -->
</fieldset>
```

---

## Submit Buttons

### Button Labels

```html
<!-- Specific, action-oriented -->
<button type="submit">Create Account</button>
<button type="submit">Place Order</button>
<button type="submit">Send Message</button>

<!-- Avoid generic -->
<button type="submit">Submit</button>
```

### Button States

```html
<button type="submit" disabled>
  <!-- Before form is valid -->
  Create Account
</button>

<button type="submit" class="loading">
  <span class="spinner" aria-hidden="true"></span>
  <span>Creating Account...</span>
</button>
```

### Button Placement

- Primary action on the right (or full-width on mobile)
- Cancel/back on the left
- Don't hide the submit button
- Ensure visible without scrolling

---

## Accessibility Checklist

- [ ] Labels properly associated with inputs
- [ ] Error messages linked with `aria-describedby`
- [ ] Required fields marked with `aria-required`
- [ ] Invalid fields marked with `aria-invalid`
- [ ] Errors announced with `role="alert"`
- [ ] Keyboard navigation works correctly
- [ ] Focus management on errors
- [ ] Sufficient color contrast
- [ ] Touch targets at least 44×44px

---

## Sources

- [Nielsen Norman Group - Form Design](https://www.nngroup.com/articles/web-form-design/)
- [Baymard Institute - Form Usability](https://baymard.com/blog/current-state-of-checkout-ux)
- [Luke Wroblewski - Web Form Design](https://www.lukew.com/resources/web_form_design.asp)
- [GOV.UK Design System - Forms](https://design-system.service.gov.uk/patterns/)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall