From 54255eeae9e49e4857fbb09f1342b6e2fb611235 Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 10:38:23 +0000 Subject: [PATCH] docs: RFC-002 Input + Definition of Done + Compliance Matrix update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - RFC_DEFINITION_OF_DONE.md (v1.0, LOCKED): - 12 criteria for every RFC component - Sign-off roles: Author, Reviewer, Automated, QA - Exit criteria: all 12 must pass - RFC-002: Canonical Input Component: - Cognitive Purpose: captures free-form text/numeric data - When to Use/NOT Use: clear boundaries vs Select, Switch, Date Picker - Interaction Contract: click, type, tab, blur, enter, escape - Failure Behaviour: invalid, network, max length, required, disabled - Accessibility Contract: label, focus, error, required, screen reader - AI Contract: when to choose Input vs alternatives - Token Dependencies: 13 tokens (bg, border, text, padding, radius, sizes, states) - Layout, Sizes (sm/md/lg), Variants (default/ghost/filled), States (8 states) - Keyboard, Touch, Motion (with reduced motion) - Anti-Patterns: placeholder as label, validation only on submit, etc. - Related Components: Select, Textarea, Search, Form, Label - DDR References: DDR-001, DDR-002, DDR-003 - Acceptance Criteria: 10 checklist items - COMPLIANCE_MATRIX.md: Input updated to 33% (Governance 🟑, Tokens 🟑, Motion 🟑, Accessibility 🟑, AI βœ…, QA ⏳) Rationale: Validate RFC-001 template works for different component types. Definition of Done ensures consistent quality. Compliance Matrix tracks progress visibly. --- docs/design/COMPLIANCE_MATRIX.md | 2 +- docs/design/RFC-002-Input.md | 263 ++++++++++++++++++++++++++ docs/design/RFC_DEFINITION_OF_DONE.md | 60 ++++++ 3 files changed, 324 insertions(+), 1 deletion(-) create mode 100644 docs/design/RFC-002-Input.md create mode 100644 docs/design/RFC_DEFINITION_OF_DONE.md diff --git a/docs/design/COMPLIANCE_MATRIX.md b/docs/design/COMPLIANCE_MATRIX.md index c4d16855c..ec52ab567 100644 --- a/docs/design/COMPLIANCE_MATRIX.md +++ b/docs/design/COMPLIANCE_MATRIX.md @@ -23,7 +23,7 @@ | Component | Governance | Tokens | Motion | Accessibility | AI | QA | Overall | |-----------|------------|--------|--------|---------------|-----|-----|---------| | Button | βœ… | βœ… | βœ… | 🟑 | βœ… | ⏳ | 82% | -| Input | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Input | 🟑 | 🟑 | 🟑 | 🟑 | βœ… | ⏳ | 33% | | Select | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | | Card | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | | Modal | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | diff --git a/docs/design/RFC-002-Input.md b/docs/design/RFC-002-Input.md new file mode 100644 index 000000000..0e953ec7b --- /dev/null +++ b/docs/design/RFC-002-Input.md @@ -0,0 +1,263 @@ +# 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 `