Foundations
Interactions
Consistent, accessible behavior for links, focus, states, input modalities, motion, and feedback.
1. Component Overview
Definition
Interactions define how people discover, focus, activate, manipulate, and receive feedback from interface elements. The foundation governs links, focus indicators, state precedence, keyboard behavior, pointer and touch equivalence, motion, and response feedback across Web and Flutter.
Purpose
Consistent interaction rules make complex interfaces predictable and operable. A shared state model prevents components from inventing local behavior and ensures every input modality can complete the same task.
2. Types of Interactions
Navigation
Links, breadcrumbs, tabs, and other controls that change location or scope.
Actions
Buttons and commands that change data or initiate work.
Selection
Controls that choose values or persistent views.
Disclosure
Controls that reveal or hide content without changing destination.
Manipulation
Drag, resize, pan, zoom, or reorder with keyboard alternatives.
Feedback
Loading, progress, success, error, undo, and recovery after input.
3. Links
Links navigate to another page, resource, or page section. Inline links remain persistently underlined, use descriptive destination text, and expose default, visited, hover, focus-visible, and active states. Standalone links may omit the underline only when placement, wording, and another cue make navigation unambiguous.
Inline
Review the accessibility requirements before release.
Standalone
View focus guidanceExternal
Service documentation (external site)Do not use buttons as links or links as commands. Avoid ambiguous text, raw URLs in prose, and unnecessarily long linked sentences. Do not force a new tab solely because a destination is external.
4. Focus Indicators
Every interactive element exposes a consistent :focus-visible indicator. The canonical indicator is a solid 3px outline offset by 2px, resolves through the semantic focus color, maintains at least 3:1 contrast, and appears without transition.
3px / +2px3px / -4pxUse an inset variant only when an external ring would be clipped. Never remove focus or replace it only with a background, color, shadow, or hover change.
5. Interaction States
Focus remains visible over hover and selected styling. Disabled and loading behavior take precedence over activation. Selection is persistent; focus and hover are temporary.
resthoverfocus-visibleactiveselectedloadingdisabled6. Input Modalities & Keyboard
Keyboard, pointer, touch, switch, voice, and assistive-technology paths preserve the same outcome. Hover is an enhancement, not a requirement. Targets use at least 44 × 44 CSS pixels on Web and 48 × 48 dp in Flutter.
| Key | Result |
|---|---|
| Tab | Move to the next focusable element in logical reading order. |
| Shift+Tab | Move to the previous focusable element. |
| Enter | Activate links and the default action of applicable controls. |
| Space | Activate buttons, toggle controls, and select applicable items. |
| Escape | Close a transient surface and return focus to its invoker. |
| Arrow keys | Move within a composite widget according to its ARIA interaction pattern. |
| Home/End | Move to the first or last item when the component pattern defines it. |
7. Motion & Feedback
Motion explains a relationship or change; it does not decorate, block input, or delay confirmation. When reduced motion is requested, non-essential movement is removed and state communication remains immediate.
0msFocus visibility and immediate state correction120msHover, press, and compact feedback180msMenus, disclosures, and local state changes240msLarge surface transitions when spatial continuity mattersLoading keeps the accessible name stable, exposes busy state programmatically, prevents duplicate submission, and provides success, error, or recovery feedback when processing ends.
8. Architectural Integration (Web & Flutter)
Web imports interactions.css and consumes canonical --ds-duration-*, --ds-easing-*, and --ds-interaction-focus-* properties. JavaScript uses the registered state and key contracts rather than local timing or state strings.
Flutter uses DsDuration, DsEasing, DsFocus, and DsInteractionState. Widgets resolve keyboard focus through Focus, FocusableActionDetector, Shortcuts, and Actions where appropriate, while native semantics remain intact.
9. Best Practices (Dos and Don'ts)
Do
- Use links for navigation and buttons for actions.
- Preserve a visible focus indicator across every state.
- Align focus order with reading and task order.
- Provide keyboard alternatives for pointer gestures.
- Keep accessible names stable while loading.
- Respect reduced motion, forced colors, and minimum targets.
Don't
- Do not rely on hover, color, animation, or cursor shape alone.
- Do not remove outlines or create local focus styles.
- Do not disable a control without a discoverable reason when needed.
- Do not trap focus or fail to return it to the invoker.
- Do not use ambiguous link text or force new tabs.
- Do not introduce arbitrary timing, easing, target, or state values.
10. Accessibility (WCAG 2.2 AA)
Interactive elements expose a semantic role, accessible name, state, value, and result. Focus indicators maintain at least 3:1 contrast and are not clipped. Keyboard operation follows the native element or documented composite-widget pattern. Essential functionality does not depend on a path-based gesture, hover, fine pointer accuracy, animation, or color alone.
11. MCP Server Context
Use the canonical rest, hover, focus-visible, active, selected, loading, and disabled states; do not invent local interaction states. Use buttons for actions and links for navigation, preserve logical keyboard order, and implement the documented key model for composite controls. Apply canonical focus, duration, easing, and target tokens; never remove focus, rely on hover alone, or animate essential state changes when reduced motion is requested.