Merge pull request 'Add reusable UX design and observability guidance' (#11) from skills-10 into main

Reviewed-on: #11

AGENTS.md

@@ -8,6 +8,14 @@
 - For cross-module work, apply every relevant scoped instruction file and
   completion workflow.
 
+## UX
+
+For any user-facing interface work, follow the
+[UX Design](skills/ux-design/SKILL.md) and
+[UX Observability](skills/ux-observability/SKILL.md) skills.
+UX is not considered complete unless the interface is both usable and measurable.
+Before considering UI work complete, apply the UX Review checklist from these skills.
+
 ## Gitea task policy
 
 Whenever creating or updating a Gitea task, correcting its tracker metadata, or

docs/implementation.md

@@ -1,5 +1,24 @@
 # Product implementation record
 
+## Reusable UX guidance — task #10
+
+[Task #10](https://git.sendico.io/tech/sxchnge/issues/10), branch `skills-10`,
+delivered in [PR #11](https://git.sendico.io/tech/sxchnge/pulls/11) into `main`,
+adds a concise root UX policy linking two independent skills in `skills/`:
+UX Design covers usable interfaces and its design review; UX Observability covers
+purposeful journey measurement and its observability review. Both preserve product
+conventions and avoid prescribing frameworks, vendors, or visual styles.
+
+Validation: both skills passed `quick_validate.py` from the skill-creator skill;
+root skill links resolve, scaffold checks and `git diff --check` pass. Manual
+review checked the requested principles and checklist coverage, duplication,
+contradictions, and actionable wording. The initial validator attempt lacked
+PyYAML; rerunning in a temporary virtual environment with PyYAML passed.
+
+This is documentation-only guidance, not an implementation or verification of
+product usability or journey instrumentation. Runtime tests and security scans
+were not run. No application behavior or analytics events changed.
+
 ## Scope
 
 The public Astro website now lives in `website/`, preserving its source, assets,

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.

skills/ux-observability/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ux-observability
+description: Define and review end-to-end measurement for important user journeys during user-facing interface work. Select purposeful semantic events and outcome metrics without instrumenting every control.
+---
+
+# UX Observability
+
+Important user journeys must be measurable end-to-end. Instrument journeys to
+understand whether users achieve their goals and where they fail. Do not add
+events merely because a UI control or screen exists.
+
+## Define the journey before implementation
+
+- Identify important journeys before implementing complex or business-critical
+  flows. For smaller UI changes, identify the affected journey and inspect its
+  existing measurement; reuse it when sufficient rather than adding events.
+- Inspect existing journey definitions, telemetry, and product conventions.
+  Follow established conventions over generic recommendations unless a concrete
+  problem justifies changing them. Do not prescribe vendors, SDKs, or UI frameworks.
+- Define success and UX quality measures before building the flow. Record its
+  start, actual successful outcome, failure states, abandonment rule, and any
+  meaningful intermediate or recovery states needed for diagnosis.
+- Define the measurement window and what counts as a journey attempt. Specify
+  how retries or resumed journeys affect counts and duration. Measure abandonment
+  through an explicit exit or a defined period without completion; do not assume
+  every missing completion is abandonment while asynchronous work is pending.
+- Measure the actual user outcome whenever possible. A successful local UI action
+  does not prove the underlying operation succeeded. If only a proxy is available,
+  label it and document the measurement gap instead of claiming outcome coverage.
+- When reconstruction requires it, correlate events across screens and asynchronous
+  operations with a scoped journey or correlation identifier. Define its lifetime
+  and retry behavior; avoid using sensitive identity data as the identifier.
+
+## Choose semantic events
+
+Distinguish these layers:
+
+| Layer | Example | Meaning |
+| --- | --- | --- |
+| UI interaction | A submit control is activated | A control was used |
+| User intent | The user requests payment | The user tried to advance a goal |
+| Journey state | Payment is submitted and processing | The operation reached a meaningful stage |
+| Business/UX outcome | Payment is confirmed or fails | The user's goal succeeded or encountered failure |
+
+The closer an event is to a meaningful outcome, the more valuable it generally
+is. Keep intent and completion distinct; one does not imply the other.
+
+- Track semantic actions, meaningful transitions, and outcomes. Prefer a small
+  number of stable, high-value events over exhaustive UI telemetry.
+- Avoid indiscriminate click tracking and speculative metrics. Events such as
+  `ButtonClicked`, `DropdownOpened`, `FieldFocused`, `FieldChanged`, and
+  `SubmitClicked` should not be added without a clear analytical purpose.
+- Prefer events such as `payment_started`, `payment_submitted`,
+  `payment_succeeded`, and `payment_failed` only when those names correspond to
+  meaningful states in the actual product journey. These are examples, not a
+  required event list. Emit success from evidence of the confirmed outcome.
+- Keep event meaning independent of widget names, component hierarchy, screen
+  structure, coordinates, or other UI implementation details. A UI refactor
+  should not invalidate the journey definition or its metrics.
+- For each event, record its meaning, emission condition, necessary properties,
+  and known purpose, consumer, or decision supported. Omit events with no such use.
+
+## Measure quality with minimal data
+
+- Make it possible to calculate successful completion/conversion, abandonment,
+  drop-off between meaningful steps, duration, failure rate, and relevant error
+  or recovery states. Define denominators and time boundaries so results are
+  interpretable; use only intermediate steps that help diagnose the journey.
+- Reuse existing outcome signals where possible. Keep correlation sufficient to
+  reconstruct important journeys without collecting unrelated activity.
+- Respect privacy and data-minimization requirements. Collect only properties
+  needed for the stated analytical purpose; do not capture sensitive user data,
+  form contents, or raw error payloads merely to simplify analysis.
+- Validate representative success, failure, retry, and abandonment scenarios
+  against emitted or existing signals. Check that retries or duplicate delivery
+  do not inflate outcomes and that cross-screen/asynchronous correlation works.
+  Document unavailable signals or measurement limitations honestly.
+- Keep measurement from blocking the user journey or changing its outcome when
+  telemetry is unavailable. Analytics should diagnose UX problems, not merely
+  demonstrate that users interacted with the interface.
+
+## UX Review
+
+Apply to important journeys affected by the change, using existing measurement
+where adequate. Record evidence and any gaps; a cosmetic change does not require
+new events, and absent instrumentation does not justify speculative telemetry.
+
+- [ ] Is the important journey observable end-to-end, with a defined start and
+  actual successful outcome rather than only a UI interaction?
+- [ ] Can completion, failure, abandonment, drop-off, duration, and relevant
+  recovery states be measured with defined attempts and measurement windows?
+- [ ] Are meaningful intermediate states measurable where they aid diagnosis?
+- [ ] Are events based on semantic intent, states, and outcomes rather than
+  individual controls, and would they remain meaningful after a UI refactor?
+- [ ] Can related events be correlated across screens and asynchronous operations
+  when necessary, with retries and duplicate events accounted for?
+- [ ] Does every event have a known purpose, consumer, or decision it supports?
+- [ ] Is collection limited to telemetry necessary to understand and improve the
+  experience, consistent with privacy requirements?
+- [ ] Have representative journeys been checked and measurement gaps identified,
+  without claiming that rendering correctly proves UX completion?