PMTL UI Behavior

Purpose

Keep PMTL interactive surfaces accessible, predictable, and complete across forms, dialogs, navigation, and state feedback.

Use When

• Building or reviewing forms, navigation, dialogs, and interactive components.
• Checking loading, empty, success, and error behavior.
• Auditing focus, keyboard flow, or validation quality.

Required Inputs

• target route, component, or interaction flow
• affected state transitions such as loading, submit, success, empty, or error
• any relevant page or component owner doc

Expected Output

• Interfaces that communicate state clearly and remain keyboard-usable.
• No critical interaction gaps hidden behind styling alone.

Execution Approach

1. Map the full interaction cycle before editing UI.
2. Ensure semantic structure, focus handling, and mobile-safe controls.
3. Add explicit state feedback for submit, loading, success, empty, and error paths.
4. Verify the flow with keyboard-first behavior in mind.

Interaction rules

• Use :focus-visible, not generic :focus.
• Keep touch targets at least 44x44px.
• Keep mobile input font size at least 16px.
• Prefer inline validation and direct field feedback over toast-only failures.
• Focus the first invalid field after failed submit.
• Always provide loading, empty, success, and error states for non-trivial interactive surfaces.
• Use semantic HTML for landmarks and icon-only button labels.
• Prefer keyboard-complete flows: submit on Enter, dismiss on Escape when appropriate, restore focus after dialog close.

Form discipline

• Labels above inputs.
• Helper text optional, but structure must support it.
• Errors belong near the related control.
• Do not hide critical state changes behind motion alone.

Verification

• Check keyboard completion: tab order, Enter submit, Escape dismiss where appropriate.
• Check focus landing after validation failure and dialog close.
• Check every non-trivial surface for loading, empty, success, and error states.

Quality Criteria

• Interaction state is visible without guessing.
• Accessibility is built into the default flow, not bolted on later.
• Motion never becomes the only signal for a state change.

Edge Cases

• Async forms with partial success need explicit follow-up messaging.
• Toast-only validation is not enough when the form itself can explain the issue.
• Elderly-oriented surfaces need larger targets, calmer state changes, and clearer inline instructions than default app forms.
• Deep-linked flows opened from guides or reminders still need full validation, focus, and retry behavior.

References

• design/ui/USER_FLOWS.md
• design/ui/COMPONENT_SPECS.md
• design/ui/ELDERLY_UX.md
• pmtl-fe-implementation
• pmtl-review-web-ui

Pair with

• pmtl-fe-implementation for code structure.
• pmtl-ui-style-system for visual hierarchy.
• pmtl-review-web-ui when reviewing an existing surface.
• Route-level page work should also read the relevant page owner docs before editing behavior.