Bernt
558303784a
- 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.
266 lines
8.6 KiB
Markdown
266 lines
8.6 KiB
Markdown
# RFC-004: Canonical Card Component
|
|
|
|
**Status:** 🟡 Draft — Under review
|
|
**Tier:** 1 (Canonical)
|
|
**Inherits From:** — (root component)
|
|
**Author:** AI Agent
|
|
**Date:** 2026-07-02
|
|
|
|
---
|
|
|
|
## 1. COGNITIVE PURPOSE
|
|
|
|
Card exists to group related information into a bounded, scannable unit. It creates visual hierarchy by separating content from its surroundings without requiring explicit borders or dividers.
|
|
|
|
**Design Goal:** The user can scan, compare, and act on grouped information as a single unit.
|
|
|
|
---
|
|
|
|
## 2. WHEN TO USE
|
|
|
|
- Grouping related data (KPI, dataset, asset summary)
|
|
- Presenting actionable items that need context
|
|
- Creating scannable lists of heterogeneous content
|
|
- Elevating content above the page background
|
|
- Containing forms or workflows in a bounded area
|
|
|
|
## 3. WHEN NOT TO USE
|
|
|
|
- Single line of text (use plain text or List Item)
|
|
- Simple navigation (use Link or Navigation)
|
|
- Modal content (use Modal)
|
|
- Full-page content (use Page layout)
|
|
- When elevation is unnecessary (use flat surface)
|
|
|
|
---
|
|
|
|
## 4. USER EXPECTATION
|
|
|
|
- Card is visually distinct from background
|
|
- Card content is related and scannable
|
|
- Card may be clickable (if actionable)
|
|
- Card maintains consistent internal spacing
|
|
- Card adapts to container width
|
|
- Multiple cards align in grids or lists
|
|
|
|
---
|
|
|
|
## 5. INTERACTION CONTRACT
|
|
|
|
| Event | Response |
|
|
|-------|----------|
|
|
| Click (actionable) | Navigate or trigger primary action |
|
|
| Hover (actionable) | Elevation increases, cursor changes |
|
|
| Focus (actionable) | Focus ring appears |
|
|
| None (static) | No interaction, purely presentational |
|
|
|
|
---
|
|
|
|
## 6. FAILURE BEHAVIOUR
|
|
|
|
| Scenario | Response |
|
|
|----------|----------|
|
|
| Content overflows | Scroll internally or truncate with ellipsis |
|
|
| Image fails to load | Show placeholder or fallback icon |
|
|
| Action fails | Show error state on card or in adjacent area |
|
|
| Card is loading | Show skeleton state |
|
|
| Card is empty | Show empty state with guidance |
|
|
|
|
---
|
|
|
|
## 7. ACCESSIBILITY CONTRACT
|
|
|
|
- **Role:** Static cards use no ARIA role. Actionable cards use `role="button"` or `role="link"`.
|
|
- **Focus:** Actionable cards MUST have visible focus ring
|
|
- **Label:** Actionable cards MUST have accessible name (aria-label or visible text)
|
|
- **Screen reader:** MUST announce card as group or link/button
|
|
- **Keyboard:** Actionable cards MUST be activatable with Enter or Space
|
|
- **Color:** MUST NOT rely on color alone to indicate actionability
|
|
|
|
---
|
|
|
|
## 8. AI CONTRACT
|
|
|
|
| Scenario | AI Choice |
|
|
|----------|-----------|
|
|
| Group related data with actions | Card |
|
|
| Single data point with label | List Item |
|
|
| Navigation to another page | Link |
|
|
| Modal content | Modal |
|
|
| Full-page layout | Page |
|
|
| Simple text without grouping | Plain text |
|
|
|
|
---
|
|
|
|
## 9. TOKEN DEPENDENCIES
|
|
|
|
| Token | Semantic Reference | Usage |
|
|
|-------|-------------------|-------|
|
|
| `card-bg` | `surface-primary` | Background |
|
|
| `card-border` | `border-default` | Border (optional) |
|
|
| `card-radius` | `radius-lg` | Border radius |
|
|
| `card-padding` | `space-4` | Internal padding |
|
|
| `card-shadow` | `shadow-sm` | Default elevation |
|
|
| `card-shadow-hover` | `shadow-md` | Hover elevation (actionable) |
|
|
| `card-shadow-active` | `shadow-sm` | Active elevation |
|
|
| `card-divider` | `border-default` | Divider between sections |
|
|
| `card-header-text` | `text-primary` | Header text |
|
|
| `card-body-text` | `text-secondary` | Body text |
|
|
| `card-footer-text` | `text-muted` | Footer text |
|
|
| `card-loading-bg` | `surface-secondary` | Skeleton background |
|
|
|
|
---
|
|
|
|
## 10. LAYOUT
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ ┌─────────────────────────────────┐ │
|
|
│ │ Header (title, action) │ │
|
|
│ ├─────────────────────────────────┤ │
|
|
│ │ │ │
|
|
│ │ Body (content, data, media) │ │
|
|
│ │ │ │
|
|
│ ├─────────────────────────────────┤ │
|
|
│ │ Footer (metadata, actions) │ │
|
|
│ └─────────────────────────────────┘ │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
- **Header:** Top section, title + optional action, padding `space-4`
|
|
- **Body:** Main content, padding `space-4`, flexible height
|
|
- **Footer:** Bottom section, metadata or actions, padding `space-4`, top border `card-divider`
|
|
- **Divider:** 1px line between sections, `card-divider`
|
|
- **Gap:** No gap between sections (padding handles spacing)
|
|
|
|
---
|
|
|
|
## 11. SIZES
|
|
|
|
| Size | Width | Padding | Usage |
|
|
|------|-------|---------|-------|
|
|
| Small | 240px | `space-3` | Dense grids, compact data |
|
|
| Medium | 320px | `space-4` | Default, most content |
|
|
| Large | 480px | `space-5` | Featured content, dashboards |
|
|
| Fluid | 100% | `space-4` | Responsive, full-width |
|
|
|
|
---
|
|
|
|
## 12. VARIANTS
|
|
|
|
| Variant | Visual | Usage |
|
|
|---------|--------|-------|
|
|
| Default | Border, subtle shadow | Standard content grouping |
|
|
| Elevated | No border, stronger shadow | Featured content, dashboards |
|
|
| Outlined | Border, no shadow | Dense layouts, tables |
|
|
| Interactive | Hover elevation, cursor pointer | Clickable cards |
|
|
|
|
---
|
|
|
|
## 13. STATES
|
|
|
|
| State | Visual | Motion |
|
|
|-------|--------|--------|
|
|
| Default | `card-bg`, `card-shadow` | — |
|
|
| Hover (interactive) | `card-shadow-hover`, cursor pointer | `duration-interaction` |
|
|
| Active (interactive) | `card-shadow-active` | `duration-instant` |
|
|
| Focus (interactive) | Focus ring | `duration-instant` |
|
|
| Loading | Skeleton state | `duration-background` |
|
|
| Empty | Empty state illustration + text | — |
|
|
| Error | Error border or error message | `duration-interaction` |
|
|
|
|
---
|
|
|
|
## 14. KEYBOARD
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `Tab` | Move focus to next focusable element |
|
|
| `Enter` / `Space` | Activate actionable card |
|
|
| `Arrow keys` | Navigate between cards in grid/list |
|
|
|
|
---
|
|
|
|
## 15. TOUCH
|
|
|
|
- Touch target: Entire card if actionable
|
|
- Active state: Brief elevation reduction
|
|
- No gesture support (no swipe, pinch)
|
|
- Scroll: Card content scrolls internally if overflow
|
|
|
|
---
|
|
|
|
## 16. MOTION
|
|
|
|
| Transition | Animation | Duration | Easing |
|
|
|-----------|-----------|----------|--------|
|
|
| Hover (interactive) | Elevation increase | `duration-interaction` | `ease-out` |
|
|
| Active (interactive) | Elevation decrease | `duration-instant` | `ease-in` |
|
|
| Focus | Focus ring appear | `duration-instant` | `ease-out` |
|
|
| Loading skeleton | Shimmer animation | `duration-background` | `linear` |
|
|
| Error appear | Border color change | `duration-interaction` | `ease-out` |
|
|
|
|
**Reduced Motion:** No elevation animation. Focus ring appears instantly.
|
|
|
|
---
|
|
|
|
## 17. ANTI-PATTERNS
|
|
|
|
- ❌ **Nested cards:** Cards inside cards create visual confusion
|
|
- ❌ **Too much padding:** Wastes space, reduces information density
|
|
- ❌ **No visual distinction from background:** Defeats purpose of card
|
|
- ❌ **Inconsistent internal spacing:** Breaks scannability
|
|
- ❌ **Actionable without focus ring:** Accessibility failure
|
|
- ❌ **Clickable entire card with internal buttons:** Event collision
|
|
- ❌ **Card as only layout tool:** Use grid or flexbox for layout, card for grouping
|
|
- ❌ **Excessive elevation:** Competes with modals and overlays
|
|
|
|
---
|
|
|
|
## 18. RELATED COMPONENTS
|
|
|
|
- **Modal** — Overlay content, not inline
|
|
- **Panel** — Larger container, often full-height
|
|
- **List Item** — Single row, no grouping
|
|
- **Tile** — Image-first card variant
|
|
- **KPI Card** — Domain-specific card (Tier 3)
|
|
- **Dataset Card** — Domain-specific card (Tier 3)
|
|
|
|
---
|
|
|
|
## 19. DDR REFERENCES
|
|
|
|
- **DDR-001:** Device Adaptive over Desktop First (affects sizing and grid)
|
|
- **DDR-002:** Information-level typography (affects header and body text)
|
|
- **DDR-003:** Semantic color system (affects states)
|
|
- **DDR-005:** Elevation system (affects shadow tokens)
|
|
|
|
---
|
|
|
|
## 20. ACCEPTANCE CRITERIA
|
|
|
|
- [ ] All 12 Definition of Done criteria met
|
|
- [ ] Works with screen reader (announces as group or link/button)
|
|
- [ ] Keyboard navigation works (Tab, Enter, Space, Arrow keys)
|
|
- [ ] Touch target minimum 44px for actionable cards
|
|
- [ ] Focus ring visible on actionable cards
|
|
- [ ] Loading skeleton state implemented
|
|
- [ ] Empty state with guidance
|
|
- [ ] Error state handled
|
|
- [ ] Reduced motion respected
|
|
- [ ] No nested cards
|
|
|
|
---
|
|
|
|
## ÄNDRINGSHISTORIA
|
|
|
|
| Version | Datum | Beskrivning |
|
|
|---------|-------|-------------|
|
|
| 1.0 | 2026-07-02 | Initial RFC-004 following RFC-001 structure |
|
|
|
|
---
|
|
|
|
## STATUS
|
|
|
|
**DRAFT — Awaiting review**
|