Allow the use of form `description` fields in form templates

[lyzadanger]

Right now, we're using deform widely on the h service for rendering forms. colander schemas, which are used by deform, have a description attribute available. But h forms only make use of the hint attribute, which gets rendered behind a tooltip.

I believe that tooltips can be appropriate in certain situations, but in other places they introduce extra work for the user and are not accessibility- or (very) mobile-friendly.

I'd like to be able to use and render descriptions—right now just in admin forms—by adding description property output to the form-field templates.

I've done a quick grep of the codebase and I don't see any use of description in colander schemas outside of my own new admin schema for groups; thus I'm hoping that exposing description in templates would not affect any existing forms (especially user-facing ones) but I'd like to discuss.

The actual work here would be relatively quick: add description to several form-field templates and appropriate styling.

[robertknight]

I believe that tooltips can be appropriate in certain situations, but in other places they introduce extra work for the user and are not accessibility- or (very) mobile-friendly.

I'll have a look at this PR more closely tomorrow but I just wanted to comment on this specifically.

Our tooltips do actually work on mobile devices and they are visible to assistive technology. See notes in tooltip-controller.js. I do note that for some form controls we have an affordance to make them larger depending on the input device (@media (pointer: coarse)) and we are missing this for tooltips.

[lyzadanger]

I'm glad our tooltips are (mostly) mobile-friendly! I think what I'm getting at is: would it be possible not to hide information behind something that requires a user action, especially in an admin-like form? Perhaps this is wandering into territory that @dawariley would be able to help us with.

The tooltip targets seem a little small and they're visually tiny—what they imply to me is more of a "footnote" (extra information about the field) versus the core description of what a field's purpose is. Does that make any sense or am I splitting hairs here?

The way it feels to me intuitively:

• description: The field is for this purpose, e.g. for a field with the name/title "Creator", a description might be: "The username of the group's creator" (as the username part isn't necessarily implied by the title). As per the summary of this issue, we're not displaying this anywhere.
• hint: Extra info, including, e.g. syntax, e.g. "entered as 'acct:username>@<authority'` or something like that, or things that not every user would need every time. Right now we're using "hint" (I'd argue) for both description and hints.

If we're hiding essential field information—the kind that would be needed to be able to fill out the form correctly by most of the people using the form—behind tooltips, that feels potentially cumbersome to me.

@robertknight Note: This isn't a PR :)

[seanh]

Agree with Lyza about tooltips hiding information

[seanh]

@lyzadanger I wonder if we can remove this one from the current sprint though? I think it's a general improvement to our forms (product wide, or at least h wide) rather than a part of the groups feature specifically. In fact the only forms that the groups feature involves (so far and for the foreseeable future) are staff-only admin forms. Also this will probably require design input for how showing field descriptions on forms should look.

Having said that I think improving the usability of our forms is important so if this is something you want to work on I'm happy to support that.

By the way, how much does this issue apply to our staff admin forms vs to our user-facing forms? Both?

Just for context, here are some other known issues with our user-facing form design. We could make a whole project out of "fixing forms" unfortunately:

• Hint tooltips broken when no JavaScript https://github.com/hypothesis/h/issues/3811
• Multiple validation errors at once break the design: https://github.com/hypothesis/h/issues/3648 (if you ask me this has to do with an unnecessarily clever design trying to put the error messages inside the form fields)
• Unstyled flash messages: https://github.com/hypothesis/h/issues/3725
• Trying to change your email address madness: https://github.com/hypothesis/h/issues/3727 and https://github.com/hypothesis/h/issues/3731
• Content overlaps label: https://github.com/hypothesis/h/issues/3764 (again, imo, trying to put the labels inside the fields is just a failed attempt at unnecessarily clever design getting us into trouble)
• Invisible horizontal scrolling: https://github.com/hypothesis/h/issues/3849
• Autocomplete dropdown obscures action buttons: https://github.com/hypothesis/h/issues/3967
• Highly unexpected behaviour of accidentally pressing Escape https://github.com/hypothesis/h/issues/4044
• Abnormal and confusing modal nature of forms. This was closed as "not a bug" but I think it's a horrible design fail personally, highly likely that this confuses the hell out of many users imo: https://github.com/hypothesis/h/issues/4010
• Another one that got closed but I don't think is fixed: https://github.com/hypothesis/h/issues/3777

Also P.S. at one point we actually got agreement that error messages should be moved outside of form fields but it never got done

[lyzadanger]

I agree that this is not urgent, but important 👍

[lyzadanger]

By the way, how much does this issue apply to our staff admin forms vs to our user-facing forms? Both?

AFAICT, none of our forms (by "forms" I mean deform using colander schema) use the description property at all except for the ones I have been adding in the admin-add-group form. That means—theoretically—that if I add description rendering to form-field templates, this should just work and none of the other (i.e. user-facing) forms should be affected.