Style Guide

This is a living document to set out some guidelines for developing user interfaces in Koha. Some coding patterns can also be found in Interface patterns

Staff interface

Headings (DRAFT)

Every page requires an 'h1' heading

Headings should be in ascending order without gaps.. i.e. don't jump from h1 -> h5

Sidebar (DRAFT)

Filters or search forms on the left should always be positioned above the navigation. For examples see: invoices, tags or suggestions.

Cards (DRAFT)

Card layouts can be achieved using the 'page-section' class.

What about headings?

h1 should be outside of the page section, same for toolbars

h2... can be inside page section

Should page-section also be used for forms forms?

Use fieldset instead (?)

Toolbars (DRAFT)

When should a toolbar be floating

When is it acceptable to have multiple toolbars on a page

We should have a consistent guide as to what buttons belong in which toolbars and how those toolbars should be ordered and formatted

'Main' toolbar contains 'New', 'Edit', 'Calls to action that affect the whole page

'Selection toolbar' contains 'Selections', 'Actions that affect the selections'

'Filter bars' contain sets of pre-defined filters for the page view

Button order should be consistent ('New' should always be first)

https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=31761

https://github.com/jajm/koha-staff-interface-redesign/issues/26

Buttons vs Links : Owen suggests

Buttons are for actions you can take with the actual "thing" being displayed (e.g. bibliographic record, patron record, etc)

Text links are for actions you can take with the results displayed: check boxes, highlight/unhighlight, filter/unfilter etc.

One toolbar or two?.. When you've got actions that fit both descriptions above on the same page.. should they be in one toolbar with button types as above.. or two consecutive toolbars with button/links types described above.

Toolbars like "New something" go above the h1 heading (?)
When should items be space delimited, when should they be pipe (|) delimited ;P

Buttons (DRAFT)

When should a button be yellow, and how is that achieved?

Sample code: <input type="submit" class="btn btn-primary" value="Submit" />

Save/submit buttons should be yellow:- I don't think it's as simple as this

What about 'action' buttons inside a table.. I feel like perhaps sometimes they warrant one 'most important' button being marked as primary but in acquisitions basketgroups for example they're all marked in yellow (for a closed group) and to me this detracts from the important distinction of what makes a button the primary action for a page/section.

When should buttons be inside fieldsets and when should they be outside?

Should buttons be left aligned or right aligned?

When should a button contain an icon

When should a 'button' not be a button, but be a link (cancel)

What order should buttons be in.. if right aligned should the most important button be further right (Modals?)

Labelling of buttons: sometimes we use Save, Save changes, OK or Submit - standardize?

Alerts (DRAFT)

Where should they go... above everything, below toolbar, below first heading?

I feel below h1, would that make sense? Should be a good position to see them usually

I actually prefer them at the top... Though it does somewhat depend.. alerts for actions having just taken place that affect the whole feature I think make sense at the top.. like 'Item added' for example... especially if it's a modal-driven or other workflow that includes navigating away from the original page.

Think about the case of updating the name of a stock rotation rota or rotating collection.. at the moment, we move away to another page (but could instead trigger a modal in an ideal world).. upon completion, we navigate back to the list page.. it would be nice to have an alert at the very top saying 'Added successfully'.. that would fit with below the heading in my mind.

I was more thinking of the alerts about missing/wrong data in forms, like we have it on the patron form. The patron form is long, so I thought closer would be better. Open to any solution, guess we just have different pages in mind too
- Colors - Should we have a color that corresponds with each 'state' an alert is highlighted
- Green for 'success'
- Yellow for 'confirmation required'
- Red for 'failure/blocked'
- Blue for 'info only'
- See bugs 31973, 31996

What classes should we use here?.. page-section, note, alert, message, bg-color.. etc It would be great to reduce the number of classes a bit.

What about transient alerts.. like feedback that an api request suceeded (Think 'Thing added', 'Thing deeted', 'Thing updated' messages.. sysprefs already use humanmessage for this.. we could use it more maybe with things going more modal.

Modals

We should encourage more adoption of modals to replace simple forms (Stock rotation, Rotating collections are both prime candidates)

We need consistent modal markup examples for simple dialogues, dialogues that include alerts and dialogues that include forms.

We need a guideline to clarify what form a modal header title should take

We need a guideline to clarify what form modal footer action buttons should take

Colors

Encourage consistent adoption of bg-* colors for different page elements...

Sidebars

I have a few suggestions for formalizing sidebars..

I'd love to see them collapsible

I'd love to see them butt up against the top header and move the breadcrumb and perhaps search to the right of them.

Consistently use or don't use icons (erm introduces icons)

Some rules around subheadings and how deep we allow

Tabbed sections

When should we use a tabbed page-section

Should we dis-allow nesting?

Fieldsets

When should a fieldset be used?

Should we dis-allow nesting of fieldsets

Forms

Focus should be set to the first form field. Usually this can be achieved using the class 'focus' on the input element.
The submit button and other buttons at the end of the form should usually be within their own fieldset.