diff --git a/AGENTS.md b/AGENTS.md index acdf458..c1ed5ea 100644 --- a/AGENTS.md +++ b/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 diff --git a/docs/implementation.md b/docs/implementation.md index 17d801f..228e04a 100644 --- a/docs/implementation.md +++ b/docs/implementation.md @@ -1,5 +1,23 @@ # Product implementation record +## Reusable UX guidance — task #10 + +[Task #10](https://git.sendico.io/tech/sxchnge/issues/10), branch `skills-10`, +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, diff --git a/skills/ux-design/SKILL.md b/skills/ux-design/SKILL.md new file mode 100644 index 0000000..9a72d17 --- /dev/null +++ b/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. diff --git a/skills/ux-observability/SKILL.md b/skills/ux-observability/SKILL.md new file mode 100644 index 0000000..bdc8dab --- /dev/null +++ b/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?