From 558303784add432174edda1c986babf8e84f52ed Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 10:41:19 +0000 Subject: [PATCH] docs: RFC-003 Select + RFC-004 Card + Compliance Matrix update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - RFC-003: Canonical Select Component: - Cognitive Purpose: choose one from predefined list - When to Use/NOT Use: clear boundaries vs Radio Group, Autocomplete, Multi-Select - Interaction Contract: click, arrow keys, type-to-search, escape - Failure Behaviour: empty, required, disabled, async loading, load failure - Accessibility Contract: combobox role, aria-expanded, aria-selected, focus management - AI Contract: when to choose Select vs alternatives - Token Dependencies: 21 tokens (trigger + dropdown + options) - Layout: trigger + dropdown with sections - Sizes (sm/md/lg), Variants (default/ghost/filled), States (10 states) - Keyboard: full navigation (Tab, Arrows, Enter, Escape, Home, End, letter keys) - Touch: 44px option targets, native scroll - Motion: dropdown open/close, option hover/select, chevron rotate - Anti-Patterns: < 4 options, > 50 options, no placeholder, clipping - Related Components: Input, Radio Group, Checkbox Group, Multi-Select, Autocomplete - DDR References: DDR-001 through DDR-004 - RFC-004: Canonical Card Component: - Cognitive Purpose: group related information into bounded unit - When to Use/NOT Use: clear boundaries vs List Item, Modal, Page - Interaction Contract: click/hover/focus for actionable, none for static - Failure Behaviour: overflow, image load fail, action fail, loading, empty - Accessibility Contract: role, focus, label, keyboard activation - AI Contract: when to choose Card vs alternatives - Token Dependencies: 12 tokens (bg, border, radius, padding, shadows, text) - Layout: Header + Body + Footer with optional divider - Sizes (sm/md/lg/fluid), Variants (default/elevated/outlined/interactive) - States (7 states), Keyboard, Touch, Motion (with reduced motion) - Anti-Patterns: nested cards, excessive padding, no distinction, event collision - Related Components: Modal, Panel, List Item, Tile, KPI Card, Dataset Card - DDR References: DDR-001, DDR-002, DDR-003, DDR-005 - COMPLIANCE_MATRIX.md: Select and Card updated to 33% Rationale: Validate RFC-001 template works for selection and container component types. Three different component types (action, selection, container) now tested. Mallen hΓ₯ller. --- docs/design/COMPLIANCE_MATRIX.md | 4 +- docs/design/RFC-003-Select.md | 293 +++++++++++++++++++++++++++++++ docs/design/RFC-004-Card.md | 265 ++++++++++++++++++++++++++++ 3 files changed, 560 insertions(+), 2 deletions(-) create mode 100644 docs/design/RFC-003-Select.md create mode 100644 docs/design/RFC-004-Card.md diff --git a/docs/design/COMPLIANCE_MATRIX.md b/docs/design/COMPLIANCE_MATRIX.md index ec52ab567..d5682172e 100644 --- a/docs/design/COMPLIANCE_MATRIX.md +++ b/docs/design/COMPLIANCE_MATRIX.md @@ -24,8 +24,8 @@ |-----------|------------|--------|--------|---------------|-----|-----|---------| | Button | βœ… | βœ… | βœ… | 🟑 | βœ… | ⏳ | 82% | | Input | 🟑 | 🟑 | 🟑 | 🟑 | βœ… | ⏳ | 33% | -| Select | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | -| Card | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | +| Select | 🟑 | 🟑 | 🟑 | 🟑 | βœ… | ⏳ | 33% | +| Card | 🟑 | 🟑 | 🟑 | 🟑 | βœ… | ⏳ | 33% | | Modal | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | | Navigation | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | | Table | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | 0% | diff --git a/docs/design/RFC-003-Select.md b/docs/design/RFC-003-Select.md new file mode 100644 index 000000000..7a5e43d17 --- /dev/null +++ b/docs/design/RFC-003-Select.md @@ -0,0 +1,293 @@ +# RFC-003: Canonical Select Component + +**Status:** 🟑 Draft β€” Under review +**Tier:** 1 (Canonical) +**Inherits From:** β€” (root component) +**Author:** AI Agent +**Date:** 2026-07-02 + +--- + +## 1. COGNITIVE PURPOSE + +Select exists to allow users to choose exactly one option from a predefined list. It reduces cognitive load by eliminating free-form input when the valid options are known in advance. + +**Design Goal:** The user can see available options, make a selection, and confirm their choice without typing or guessing. + +--- + +## 2. WHEN TO USE + +- Choosing from 5–20 predefined options +- Selecting a single value (country, status, category) +- When options have clear labels +- When free-form input would cause errors + +## 3. WHEN NOT TO USE + +- Fewer than 4 options (use Radio Group or Segmented Control) +- More than 50 options (use Searchable Select or Autocomplete) +- Multiple selections (use Multi-Select or Checkbox Group) +- Boolean choice (use Switch or Checkbox) +- Free-form entry (use Input) + +--- + +## 4. USER EXPECTATION + +- Clicking the field reveals all options +- Selected option is clearly indicated +- Current selection is visible when closed +- Options are searchable if list is long +- Keyboard can navigate options +- Disabled options are visually distinct + +--- + +## 5. INTERACTION CONTRACT + +| Event | Response | +|-------|----------| +| Click | Open dropdown, show options | +| Click option | Select option, close dropdown | +| Click outside | Close dropdown, keep selection | +| Tab | Move focus to next field, close dropdown | +| Arrow Down | Open dropdown or move to next option | +| Arrow Up | Move to previous option | +| Enter | Select focused option, close dropdown | +| Escape | Close dropdown, revert to previous selection | +| Type letter | Jump to first option starting with that letter | + +--- + +## 6. FAILURE BEHAVIOUR + +| Scenario | Response | +|----------|----------| +| No option selected | Show placeholder, allow form submission if optional | +| Required but empty | Show error on blur or submit | +| Option disabled | Prevent selection, show disabled state | +| Options load asynchronously | Show loading state, then populate | +| Options fail to load | Show error, allow retry | +| User types non-matching letter | No action, or show "no results" | + +--- + +## 7. ACCESSIBILITY CONTRACT + +- **Label:** Every Select MUST have associated `