pmtl-ui-behavior
PMTL_VN interaction and accessibility discipline. Use when building or reviewing forms, navigation, dialogs, loading states, empty states, error handling, and interactive components.
SKILL.md.agents/skills/pmtl-ui-behavior/SKILL.md
GitHubPMTL 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
- Map the full interaction cycle before editing UI.
- Ensure semantic structure, focus handling, and mobile-safe controls.
- Add explicit state feedback for submit, loading, success, empty, and error paths.
- 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/04-execution-overlay/web/USER_FLOWS.mddesign/04-execution-overlay/web/PAGE_LOADER_CONTRACTS.mddesign/02-platform-baseline/web-runtime/COMPONENT_SPECS.mddesign/02-platform-baseline/web-runtime/ELDERLY_UX.mdpmtl-fe-implementationpmtl-review-web-ui
Pair with
pmtl-fe-implementationfor code structure.pmtl-admin-uifor admin workspace tables, filters, bulk actions, and operational forms.pmtl-ui-style-systemfor visual hierarchy.pmtl-review-web-uiwhen reviewing an existing surface.- Route-level page work should also read the relevant page owner docs before editing behavior.