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 `