Add reusable UX design and observability skills (#10)

2026-09-12 08:06:14 +02:00
1 parent abc3f2d048
commit 4cfbce9e03
@@ -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
@@ -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,
@@ -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.
@@ -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?