boc/docs/design/components/RFC-002-Input.md

# RFC-002: Canonical Input Component

**Status:** 🟡 Draft — Under review  
**Tier:** 1 (Canonical)  
**Inherits From:** — (root component)  
**Author:** AI Agent  
**Date:** 2026-07-02

---

## 1. COGNITIVE PURPOSE

Input exists to capture free-form text or numeric data from the user. It is the primary interface for data entry in forms, filters, and search.

**Design Goal:** The user knows what to enter, where to enter it, and whether the entry is valid — without reading documentation.

---

## 2. WHEN TO USE

- Free-form text entry (name, address, description)
- Numeric entry (quantity, price, coordinates)
- Password entry
- Search queries
- Filter values

## 3. WHEN NOT TO USE

- Selection from predefined options (use Select)
- Boolean toggle (use Switch or Checkbox)
- Date/time selection (use Date Picker)
- File upload (use File Input)
- Rich text (use Rich Text Editor)

---

## 4. USER EXPECTATION

- Input field is identifiable as editable
- Placeholder text hints at expected format
- Focus state indicates where typing will appear
- Validation errors are shown immediately or on blur
- Required fields are marked
- Disabled fields are visually distinct

---

## 5. INTERACTION CONTRACT

| Event | Response |
|-------|----------|
| Click | Focus input, place cursor |
| Type | Character appears at cursor position |
| Tab | Move focus to next field |
| Shift+Tab | Move focus to previous field |
| Blur | Validate (if configured), show error if invalid |
| Enter | Submit form (if single-line), new line (if multi-line) |
| Escape | Clear input (if configured), or cancel |

---

## 6. FAILURE BEHAVIOUR

| Scenario | Response |
|----------|----------|
| Invalid input on blur | Show error message below input, red border |
| Invalid input on submit | Show error, scroll to first error, focus it |
| Network validation fails | Show error, allow retry |
| Input exceeds max length | Prevent further input, show character count |
| Input is required but empty | Show error on blur or submit |
| Input is disabled | Ignore all interactions, show disabled state |

---

## 7. ACCESSIBILITY CONTRACT

- **Label:** Every input MUST have an associated `<label>` or `aria-label`
- **Focus:** Focus ring MUST be visible (WCAG 2.4.7)
- **Error:** Error message MUST be associated with `aria-describedby`
- **Required:** Required state MUST be communicated with `aria-required` or `required` attribute
- **Screen reader:** MUST announce label, current value, and error state
- **Color:** Error state MUST NOT rely on color alone (icon or text required)

---

## 8. AI CONTRACT

| Scenario | AI Choice |
|----------|-----------|
| Free-form text entry | Input |
| Predefined options | Select |
| Boolean toggle | Switch / Checkbox |
| Date/time | Date Picker |
| File upload | File Input |
| Search with suggestions | Search (specialized component) |

---

## 9. TOKEN DEPENDENCIES

| Token | Semantic Reference | Usage |
|-------|-------------------|-------|
| Token | Semantic Alias | Primitive | Usage |
|-------|---------------|-----------|-------|
| `input-bg` | `color.surface.default` | `gray-0` | Background |
| `input-border` | `color.border.default` | `gray-200` | Default border |
| `input-border-focus` | `color.border.focus` | `blue-500` | Focus border |
| `input-border-error` | `color.border.error` | `red-500` | Error border |
| `input-text` | `color.text.primary` | `gray-900` | Input text |
| `input-placeholder` | `color.text.muted` | `gray-400` | Placeholder text |
| `input-padding` | `space-3` | `12px` | Internal padding |
| `input-radius` | `radius-md` | `8px` | Border radius |
| `input-height-sm` | `space-8` | `32px` | Small height |
| `input-height-md` | `space-10` | `40px` | Medium height |
| `input-height-lg` | `space-12` | `48px` | Large height |
| `input-error-bg` | `color.status.danger` (at 5%) | `red-50` | Error background tint |
| `input-disabled-bg` | `color.surface.raised` | `gray-50` | Disabled background |
| `input-disabled-text` | `color.text.muted` | `gray-400` | Disabled text |

---

## 10. LAYOUT

```
┌─────────────────────────────────────┐
│ Label (optional)                    │
├─────────────────────────────────────┤
│ ┌─────────────────────────────────┐ │
│ │ Placeholder text...            │ │
│ └─────────────────────────────────┘ │
│ Helper text / Error message         │
└─────────────────────────────────────┘
```

- **Label:** Above input, left-aligned, `text-sm`, `font-medium`
- **Input:** Full width of container, padding `space-3`
- **Helper/Error:** Below input, `text-xs`, `color.text.muted` (helper) or `color.status.danger` (error)
- **Gap:** `space-1` between label and input, `space-1` between input and helper

---

## 11. SIZES

| Size | Height | Font Size | Padding | Usage |
|------|--------|-----------|---------|-------|
| Small | 32px | 14px | `space-2` | Dense forms, tables |
| Medium | 40px | 16px | `space-3` | Default, most forms |
| Large | 48px | 18px | `space-4` | Mobile, touch-first |

---

## 12. VARIANTS

| Variant | Visual | Usage |
|---------|--------|-------|
| Default | Border, background | Standard form input |
| Ghost | No border, underline only | Minimal UI, filters |
| Filled | Solid background, no border | High-contrast forms |

---

## 13. STATES

| State | Visual | Motion |
|-------|--------|--------|
| Default | `input-border`, `input-bg` | — |
| Hover | Border darkens slightly | `duration-instant` |
| Focus | `input-border-focus`, focus ring | `duration-instant` |
| Active | Same as focus | — |
| Disabled | `input-disabled-bg`, `input-disabled-text` | — |
| Error | `input-border-error`, `input-error-bg` | `duration-interaction` |
| Loading | Spinner inside input, disabled | `duration-attention` |
| Valid | Green checkmark icon (optional) | `duration-interaction` |

---

## 14. KEYBOARD

| Key | Action |
|-----|--------|
| `Tab` | Move focus to next field |
| `Shift+Tab` | Move focus to previous field |
| `Enter` | Submit form (single-line) |
| `Escape` | Clear input (if clearable) |
| `Ctrl+A` | Select all text |
| `Ctrl+C/V/X` | Copy/paste/cut |

---

## 15. TOUCH

- Touch target: Minimum 40px height (Medium size)
- Active state: Brief background tint
- No gesture support (no swipe, pinch)

---

## 16. MOTION

| Transition | Animation | Duration | Easing |
|-----------|-----------|----------|--------|
| Focus | Border color change | `duration-instant` | `ease-out` |
| Error appear | Border + background tint | `duration-interaction` | `ease-out` |
| Error disappear | Revert to default | `duration-interaction` | `ease-in` |
| Loading spinner | Rotate | `duration-background` | `linear` |

**Reduced Motion:** All transitions become instant (`duration-instant`).

---

## 17. ANTI-PATTERNS

- ❌ **Placeholder as label:** Placeholder disappears on typing, user loses context
- ❌ **Validation only on submit:** User should know immediately if input is wrong
- ❌ **No visual feedback on focus:** User cannot see where they are typing
- ❌ **Error message in color only:** Screen reader users miss it
- ❌ **Input without label:** Accessibility failure, unclear purpose
- ❌ **Too many variations:** Stick to Default, Ghost, Filled

---

## 18. RELATED COMPONENTS

- **Select** — Predefined options instead of free-form
- **Textarea** — Multi-line text entry
- **Search** — Input with autocomplete and suggestions
- **Form** — Groups inputs with validation logic
- **Label** — Associated text for input

---

## 19. DDR REFERENCES

- **DDR-001:** Device Adaptive over Desktop First (affects input sizing)
- **DDR-002:** Information-level typography (affects label and helper text)
- **DDR-003:** Semantic color system (affects error and disabled states)

---

## 20. ACCEPTANCE CRITERIA

- [ ] All 12 Definition of Done criteria met
- [ ] Works with screen reader (NVDA, VoiceOver, JAWS)
- [ ] Keyboard navigation works (Tab, Shift+Tab, Enter, Escape)
- [ ] Touch target minimum 40px on mobile
- [ ] Error state visible without color alone
- [ ] Placeholder does not replace label
- [ ] Loading state prevents duplicate submission
- [ ] Disabled state clearly distinct from enabled
- [ ] Focus ring visible and logical
- [ ] Reduced motion respected

---

## ÄNDRINGSHISTORIA

| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial RFC-002 following RFC-001 structure |

---

## STATUS

**DRAFT — Awaiting review**