Improve and make current UX guidelines#1677
Conversation
marmarta
force-pushed
the
uxguidelines
branch
4 times, most recently
from
8deeeaf to
6b8f63f
Compare
parulin
left a comment
parulin
left a comment
There was a problem hiding this comment.
Thanks for the update! The diff is messy so I have not checked if some of my comments applied to previous content, if so, please ignore them.
| font-weight: 600; | ||
| } | ||
|
|
||
| For color definitions, see below. |
There was a problem hiding this comment.
You should provide a link to the color section.
| Examples: | ||
|
|
||
| .. figure:: /attachment/doc/ui_design_buttons_1.png | ||
| :alt: part of Qubes OS Global Config: three buttons at the bottom of the screen. Blue button with text "Apply Changes and Close", and two flat normal buttons with text "Apply Changes" and "Cancel" |
There was a problem hiding this comment.
Same comment: the alt content is too long.
There was a problem hiding this comment.
I am not sure how to shorten this? Do you have any proposals?
There was a problem hiding this comment.
That?
.. figure:: /attachment/doc/ui_design_buttons_1.png
:alt: Three buttons to apply changes and/or close the dialog
In Qubes OS Global Config, there are three buttons at the bottom of the screen
The first one, :guilabel:`Apply Changes and Close` is a blue confirmation button. The two others, :guilabel:`Apply Changes` and :guilabel:`Cancel", are regular gray buttons.The following part is not an example but should be one of the recommendations, above don't you think?
Usually only one button should be marked visually as the main "confirmation" button. If there are multiple buttons who could serve this role, individual discernment must be used.
There was a problem hiding this comment.
That?
.. figure:: /attachment/doc/ui_design_buttons_1.png :alt: Three buttons to apply changes and/or close the dialog In Qubes OS Global Config, there are three buttons at the bottom of the screen The first one, :guilabel:`Apply Changes and Close` is a blue confirmation button. The two others, :guilabel:`Apply Changes` and :guilabel:`Cancel", are regular gray buttons.
My problem with this is that it seems that for the person not using the alt-text, there is a repetition between the image and the description. It doesn't make sense to me to repeat the contents of the image in the non-alt-text description, because then the image seems pointless?
The following part is not an example but should be one of the recommendations, above don't you think?
Usually only one button should be marked visually as the main "confirmation" button. If there are multiple buttons who could serve this role, individual discernment must be used.
good point, moved it
There was a problem hiding this comment.
My suggestion is not a good one because here, the person using the alt text has a repetition.
But for someone not using the alt text, I don't think the text is harmful, you have some context (this image comes from Qubes Global config, it is at the bottom of the screen) and things are clearly identified. Maybe it would be better to explicitly link the CSS class to the result. The text also helps the user figuring out what is the difference between the two buttons. Some people can see the image but maybe not the colors?
A better solution would be to provide the description somewhere else but I don't think it is easy to do that with Sphinx.
If you still don't like it, I have another suggestion:
.. figure:: /attachment/doc/ui_design_buttons_1.png
:alt: Three buttons to apply changes and/or close the dialog
The confirmation button appears in blue while the others are gray|
|
||
| For GUI elements, use Tailwind color system (from `Tailwind CSS system <https://www.tailwindcss.com>`__). In particular, you can refer to the colors below for a comprehensive set of readable colors. | ||
|
|
||
| .. raw:: html |
There was a problem hiding this comment.
This HTML table doesn't fit well in the documentation. Instead of copy-pasting it, is it possible to just provide a link to the original resource?
There was a problem hiding this comment.
It is a subset of the tailwind colors (I reworded to make this clearer). I think for copying and pasting, it is very useful to have a paste-able list of colors that can be also checked visually.
There was a problem hiding this comment.
Right now the table is a bit too large on the desktop version and very much on the mobile version.
marmarta
force-pushed
the
uxguidelines
branch
3 times, most recently
from
f81ec27 to
77cb6d4
Compare
| ========================= | ||
|
|
||
| Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority! | ||
| Unnecessary complexity and bad UI often scare users away from good software. To avoid this terrible fate, please always take usability and good user experience into account when contributing to Qubes OS. |
There was a problem hiding this comment.
| Unnecessary complexity and bad UI often scare users away from good software. To avoid this terrible fate, please always take usability and good user experience into account when contributing to Qubes OS. | |
| Unnecessary complexity and bad UI often scare users away from good software. To avoid this, please always take usability and good user experience into account when contributing to Qubes OS. |
There was a problem hiding this comment.
I would like to leave a little bit of personal style in the text.
| - avoid leaving users stranded - if there is an error message, there should also be guidance on how to recover or (preferably) an actionable solution | ||
|
|
||
| - Use ``application number`` instead of ``PID`` or ``Process Identification Number`` | ||
| Reduce cognitive load |
There was a problem hiding this comment.
disagree: this is reduce cognitive load [for the user], I think this is consistent
| ---- | ||
|
|
||
| |redx| **Avoid Technical Words** | ||
| Language |
There was a problem hiding this comment.
I think that the subheadings could be reordered, and there is quite some repetition which could be removed
There was a problem hiding this comment.
please tell me what do you mean specifically
|
|
||
| These words are more abstract and user relevant- they help a user understand what is happening based on already known concepts (disk space) or start to form a mental model of something new (Qubes). | ||
| Prefer a common, understandable concept to detailed technical explanations of a particular implementation | ||
| - Use ``disk space`` instead of ``root.img``, since while not quite accurate, it makes contextual sense |
There was a problem hiding this comment.
This isnt a good example because they are different things
There was a problem hiding this comment.
that's the point? if something is clearer, use a clearer concept instead of technically correct explanation.
| Prefer a common, understandable concept to detailed technical explanations of a particular implementation | ||
| - Use ``disk space`` instead of ``root.img``, since while not quite accurate, it makes contextual sense | ||
| - Use ``saving`` instead of ``savefile`` as the former is the action trying to be completed | ||
| - Use ``Qubes`` instead of ``qrexec-daemon`` as it gives better context on what is happening |
There was a problem hiding this comment.
I dont understand where you would want to use this.
There was a problem hiding this comment.
in error messages for example
|
If the alt-text repeats what is in the description you can leave "" or
(better imo) say so in the alt
|
|
I think I either replied or fixed all comments (...finally noticed ones github hid for me for some unknown reason). |
|
On Thu, May 07, 2026 at 04:03:33AM -0700, parulin wrote:
@parulin commented on this pull request.
>
-It is easy to start abbreviating (or making acronyms) of long terms like ``Disposable Virtual Machine`` depending on where the term shows up in an interface.
+Certain security considerations make it difficult to make Qubes OS fully accessible to tools such as screen readers (as a screen reader by design violates many security boundaries Qubes OS establishes). However, let the perfect not be the enemy of the good and let us strive for accessibility to a degree that is possible.
> I completely disagree. I think it good to address this head on.
What do you mean? I'm okay with acknowledging that the current status is not good but telling contributors that the accessibility is not good because of security reasons doesn't seem fair to me.
Why else do you think accessibility is not good?
If you can suggest a way that accessibility could be improved WITHOUT
compromising security and compartmentalisation, you should open a
discussion on qubes-devel and see it implemented. (I have not been able to
find one.)
Otherwise it is best to address this, so that developers are conscious
of the issues. (I think that USERS should also be aware of this.)
This is not patronising or hand wringing. @marmarta - you should
reinstate this.
|
|
On Wed, May 06, 2026 at 06:50:47AM -0700, Marta Marczykowska-Górecka wrote:
@marmarta commented on this pull request.
>
-|redx| **Avoid Technical Words**
+Language
please tell me what do you mean specifically
The Headings under Language could be arranged:
Use simple words
Use simple concepts
Follow current Qubes OS terminology
Avoid redundancy
Avoid acronyms
Avoid technical words
Or perhaps:
Use simple words
Use simple concepts
Avoid redundancy
Follow current Qubes OS terminology
Avoid acronyms
Avoid technical words
I think either flow better, but favor the first. (Positive first, then
admonitions.)
|
For the same reason that it is not good in a lot of other situations: it is not a priority.
Reading again the original paragraph, removing reasons and sticking to facts is acceptable to me:
This page is for contributors, so I don't think it's a good idea to provide them a reason for ignoring accessibility (by saying it is not secure or something else). |
|
On Fri, May 08, 2026 at 12:31:44AM -0700, parulin wrote:
parulin left a comment (QubesOS/qubes-doc#1677)
> Why else do you think accessibility is not good?
For the same reason that it is not good in a lot of other situations: it is not a priority.
> Otherwise it is best to address this, so that developers are conscious of the issues.
Reading again the original paragraph, removing reasons and sticking to facts is acceptable to me:
> Qubes OS is not fully accessible to tools such as screen readers. However, let the perfect not be the enemy of the good and let us strive for accessibility to a degree that is possible.
This page is for contributors, so I don't think it's a good idea to provide them a reason for ignoring accessibility (by saying it is not secure or something else).
I think you are misreading that guidance, and I think including the
"reasons" is important. I dont think anyone could read @marmarta
paragraph and think it gave them a reason to ignore accessibility.
For what its worth, the screen reader I am most familiar with does not
break compartmentalisation, although it is possible that others will. I
mean it does not merge outputs from different windows in to one stream.
It's necessary to step through some hoops and use certain helper scripts
to get anywhere near usable compartmentalisation.
A MAJOR issue I have referenced before - Sphinx generates every image as
a link to the originating image, using the alt text of the image. This
is unfortunate to say the least, but it's a Sphinx problem, which is why I
havent raised an issue.
|
Yes, I don't remember where you wrote about this and I haven't forgotten the issue, but I have to admit it wasn't my priority... |
|
There are just a few things to finish: |
3 participants
Improved, modernized and also expanded UX guidelines