Consolidate repository skills under .agents/skills

.agents/skills/ux-design/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: ux-design
+description: Design, implement, or review user-facing interfaces for usability, state handling, responsiveness, accessibility, performance, and trust. Apply to new flows and changes to existing interfaces.
+---
+
+# UX Design
+
+Use these instructions while implementing an interface and apply the UX Review
+before reporting it complete. Rendering correctly is only one part of completion.
+
+## Establish the flow
+
+- Identify the user's primary task, successful outcome, and shortest appropriate
+  path to that outcome before choosing layouts or controls.
+- Inspect comparable product flows, components, navigation, terminology, and
+  visual conventions. Reuse established patterns when they solve the same problem.
+  Prefer familiar interactions over novelty. Introduce a new component, pattern,
+  or term only for a concrete unmet need; document that reason.
+- When a generic recommendation conflicts with an established product convention,
+  inspect and follow the convention unless there is a concrete reason to change it.
+  Do not impose a framework, component library, or visual style.
+
+## Make actions understandable
+
+- Design mobile-first: make the primary task work on a small screen before
+  adapting it to larger screens. Make the primary action visually obvious.
+- Use hierarchy and recognizable affordances to show what matters, what is
+  interactive, what is happening, and what will happen next.
+- Minimize steps, unnecessary elements, decoration, and cognitive load. Keep
+  secondary, advanced, or rarely used information behind progressive disclosure
+  without hiding information needed for the primary task.
+- Treat copy as interface design: use clear, specific, consistent terms and
+  action labels. Improve an unclear interaction before adding explanatory prose.
+- Keep navigation, interactions, terminology, and visual conventions consistent
+  across the product, including responsive variants.
+- Preserve user input and context, including selections and the user's place in
+  a flow, whenever possible. Never unexpectedly navigate, submit, delete,
+  refresh, or modify user data.
+- Give users appropriate control, such as cancel, back, retry, or recovery.
+  Prefer undo or recovery for reversible actions. Reserve confirmation dialogs
+  for destructive, irreversible, consequential, or difficult-to-recover actions;
+  explain the action and its consequences clearly.
+- Never make hover, color alone, or gestures the only way to discover or perform
+  an important action. Provide visible, accessible alternatives.
+
+## Design states and feedback
+
+Treat screens and components as stateful systems. Identify relevant states before
+implementation: initial, loading, populated, empty, partial, success, error,
+disabled, permission-restricted, and offline. Use judgment; do not add states
+that the actual component or flow cannot encounter.
+
+- Make transitions understandable and preserve context through them. Distinguish
+  an empty result from data that is still loading or failed to load.
+- Give immediate, meaningful feedback after important actions. Distinguish work
+  in progress from confirmed success so users never have to guess the outcome.
+- Explain errors specifically: what went wrong and, when possible, the recovery
+  action. Keep user input after errors whenever possible and make retries usable.
+- Explain disabled actions and access restrictions when needed to proceed,
+  without disclosing information the user is not authorized to see.
+
+## Adapt and make accessible
+
+- Intentionally adapt layout, navigation, density, and interactions to available
+  space; do not just shrink a desktop layout. Preserve hierarchy and primary
+  actions across relevant viewport sizes and avoid unnecessary horizontal scroll.
+- Check realistic long content, translations where relevant, and text scaling;
+  do not validate only short placeholders.
+- Build accessibility into each state: readable text, sufficient contrast,
+  adequate touch targets, visible focus, and meaningful accessible names and
+  states. Check against applicable project and platform accessibility requirements.
+- Support keyboard navigation and screen-reader interaction where applicable.
+  Verify focus order, activation, and feedback through the actual flow, including
+  errors and state changes. Never convey important information by color alone.
+
+## Preserve performance and trust
+
+- Provide appropriate progress feedback for operations that are not immediate.
+  Avoid unnecessary loading states, layout shifts, and blocking unrelated actions.
+- Use optimistic updates only when safe, with reliable reconciliation and a
+  recovery path if the operation fails. Do not present an unconfirmed operation
+  as a confirmed outcome.
+- Never expose sensitive information unnecessarily, including in errors, loading
+  placeholders, and permission-related states.
+
+## UX Review
+
+Walk the changed flow with realistic content and applicable states. Record checks
+performed and any gaps; do not mark applicable unmet criteria as complete.
+
+### Usability
+
+- [ ] Can a new user understand the screen's purpose, primary task, and primary
+  action without external explanation?
+- [ ] Are interactive elements recognizable, and can the user tell what is
+  happening and what will happen next?
+- [ ] Are steps appropriate, with unnecessary interaction and cognitive load removed?
+- [ ] Does the flow follow existing product patterns and consistent terminology,
+  with a concrete reason for any departure?
+- [ ] Can users recover from errors, with input and context preserved where appropriate?
+- [ ] Are destructive or irreversible actions handled appropriately, with user
+  control and undo, recovery, or confirmation suited to the consequences?
+
+### States and responsiveness
+
+- [ ] Are all relevant states implemented, including loading, empty, error,
+  success, disabled, and permission-related states where applicable?
+- [ ] Are transitions understandable and context preserved?
+- [ ] Does the flow work well on mobile and across relevant viewport sizes with
+  realistic content lengths and text scaling?
+
+### Accessibility and performance
+
+- [ ] Are applicable accessibility requirements satisfied, with understandable,
+  accessible controls, names, states, focus, and keyboard/screen-reader behavior?
+- [ ] Are important actions discoverable without relying on hover, color, or gestures?
+- [ ] Do slow operations provide appropriate feedback, without unnecessary
+  loading states, layout shifts, or blocked interactions?
+
+This checklist assesses design. For full UI completion, also verify the project's
+observability requirements; a usable rendered screen alone does not establish a
+measurable user outcome.