Skip to content

Instantly share code, notes, and snippets.

@stowball

stowball/ui-quick-tips.md

Last active October 27, 2019 13:49
Show Gist options
  • Save stowball/42fd83c82c4e2ffed7115be8bf7bc31b to your computer and use it in GitHub Desktop.
Save stowball/42fd83c82c4e2ffed7115be8bf7bc31b to your computer and use it in GitHub Desktop.
Download ZIP
Quick tips to build UI like Stowey
Raw
ui-quick-tips.md

Quick tips to build UI like Stowey

Order your CSS

  • Order your "selectors" in styles.js to match the source order. This makes it much easier to follow along when looking at both the styles and the view.
  • Order your class names in alphabetical order and grouped thematically. This makes it much easier to scan which properties are in use, and how they override each other.

The order for class names should match the order in which they're generated by Hucssley:

base
:visited
:focus
:hover
:hocus
:active
state
group:focus
group:hover
group:hocus
group-state
reduced-motion
print
responsive-base
responsive:visited
responsive:focus
responsive:hover
responsive:hocus
responsive:active
responsive-state
responsive-group:focus
responsive-group:hover
responsive-group:hocus
responsive-group-state

Unless anything has changed since 18/10/19, we unfortunately cannot lint for the above.

Simplify the view logic

Hucssley provides stateful classes to help you affect what gets rendered in a performant way. While this approach won't cover every scenario, toggling a class based on some condition is less overhead than adding or removing entire DOM nodes.

Don't

<div v-if="isExpanded"></div>

Do

<div v-bind:class="isExpanded && 'is-expanded'"></div>

and have appropriate, corresponding class names like:

display:none
is-expanded--display:block

Also, try to describe as much of the UI by default using the state, group and user interaction classes where possible, and not conditionally changing the view's output based off these scenarios. This allows you to fully understand what a component does under every circumstance, and not just the circumstance you're looking at in the browser at that time.

Don't

<button v-bind:class="[
  styles.button,
  isDisabled && styles.buttonWhenDisabled,
]" />

button: `
  border-radius:20
  padding-horizontal:50
`,
buttonWhenDisabled `
  cursor:default
  pointer-events:none
`,

Do

<button v-bind:class="[
  styles.button,
  isDisabled && 'is-disabled',
]" />

button: `
  border-radius:20
  padding-horizontal:50
  is-disabled--cursor:default
  is-disabled--pointer-events:none
`,

How to style based on props

Since our "CSS" is written in a JS object, we can group UI changes and easily correlate them to specific props.

Don't

<div v-bind:class="
  direction === 'up' ? styles.dirUp :
  direction === 'down' ? styles.dirDown :
  direction === 'left' ? styles.dirLeft : styles.dirRight
"></div>

dirUp: `
  rotate:90
`,
dirDown: `
  rotate:270
`,
dirLeft: `
  rotate:0
`,
dirRight: `
  rotate:180
`,

Do

<div v-bind:class="styles.direction[direction]"></div>

direction: {
  down: `
    rotate:270
  `,
  left: `
    rotate:0
  `,
  right: `
    rotate:180
  `,
  up: `
    rotate:90
  `,
}

Know CSS and scrutinise every class name added

Hucssley has a reset which saves us from having to undo default browser styles, so we shouldn't need to ever reset margin-bottom on paragraphs, or set a default text-align, for example.

However, really knowing the ins and outs of CSS is a skill in itself, and even for experts, writing CSS is occasionally a bit trial and error, so also make sure things like flex classes aren't just applied "in hope". Toggle each one and off to see if they actually make a difference, and permanently remove the ones that don't.

Don't

  <p v-bind:class="styles.root" />

root: `
  margin-bottom:0
  text-align:left
  typography:80
`

Do

  <p v-bind:class="styles.root" />

root: `
  typography:80
`

Learn how to debug Hucssley

If you write a class which you feel should work but doesn't, there are a few things to try:

  1. Check the Hucssley classes documentation to see if the one you're using is output at the modules or types you wish to use by default. If not, add a new variables file or update an existing one within /argos/component-library/src/css/variables/classes/ to add it.
  2. If the class is using a state, know that we have overridden the defaults with our own, more succinct set which can be added to as necessary within /argos/component-library/src/css/variables/global/_hu-states.scss.
  3. Add $hu-debug: true as the first line of the root index.scss within either the component-library or web-apps directory depending on where you're working. This will output Hucssley's complete list of generated classes above the UI in the browser.

Test in all browsers

It is not enough just to test in Chrome on Mac. Safari often presents its own unique challenges too. Windows browsers, especially IE 11 has a lot of other quirks, and Windows users don't have an option of "floating scrollbars" like Mac does, so scrollable regions may not render as intended there.

Mobile browsers have particular issues as well, especially Safari on iOS, so it's important to test on that too.

Don't

  • Assume it will work

Do

  • Install Xcode and the iOS simulator (but note that's it's only a simulator, not an emulator).
  • Install VirtualBox and the free Windows VMs: https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/
  • Install Android Studio and set up Android devices.
  • Test on your personal device.
  • Use BrowserStack or similar to test other browsers and devices "in the cloud".

Think about the invisible stuff

Sighted users can more easily perceive and understand user interfaces through Gestalt Principles such as Similarity, Proximity and Common Region.

On the other hand, the vision impaired need to have "the how and why" things exist explicitly described to them. We can cater for all use cases by applying a .visually-hidden class to an element that adds little or no benefit to sighted users while adequately describing meaning for users who need it.

Correct, semantic markup needs to be used to convey the structure of the page. Some quick wins are:

  • Headings are the primary way in which users of assistive technology understand a page's hierarchy. Every page needs to have an <h1>, even if it's .visually-hidden like in Search.
  • Heading levels must not be skipped, and each heading level must be set appropriate to context in which it sits. You can go down, then up and down again, but you can never jump from h1 to h3, or h2 to h4.
  • Build your UI and components un-styled and design-less to get the semantics correct. A list of "things" doesn't exist in a vacuum. Add a heading to describe what follows.
  • Button and Link text must make sense out of context. A bunch of "Click here", "Book now" and "Read more" actions are meaningless when a user is navigating through links only.
  • Use a <main> element for the container that wraps the main content of the page.
  • Use <fieldset>s to group related form inputs, and add a meaningful, concise <legend> which describes them.
  • Sighted users know when a button is pressed or a dropdown menu becomes visible, so add appropriate aria- state and property attributes to convey this information for other users.
  • Move focus to, or audibly announce (through aria-live regions) a change in the UI, such as an error toast message appearing. Sighted users can see it appear, but how would someone who can't see know?
  • Ensure interactive elements can be tabbed through in a sensible order, and add tabindex="-1" to elements that are programmatically focused to.

Know the limitations of the web for building rich applications

There are no HTML elements for Combo Boxes, Alerts etc, but luckily, the W3C have written – in detail – about how we can use ARIA and JavaScript to create accessible versions of these patterns and widgets.

Before you start any work, try and find an appropriate pattern, and then implement the relevant interactions, states and behaviours exactly as described.

If you can't find a pattern that matches (like Infinite Scroll, for example), I can't stress this enough:

Put yourself in the shoes of someone with a disability, especially vision impairment, and ask "if I can't see the interface, how will I know what action to perform next, and how should I be informed of the result of an action?"

Install and learn how to use screen-readers

  • macOS comes with VoiceOver built-in, and has a tutorial in System Preferences. Go and complete it.
  • iOS devices also include VoiceOver, and Android has TalkBack. Both of these have tutorials also.
  • Install ChromeVox.
  • Install NVDA in your Windows VM.
  • Install JAWS on Windows if you can.

Test your work in all of them to learn to how they behave and interact with your components. They're not perfect, and they're all different (including discrepancies when used with different browsers), so you may need to compromise on certain things to create the most accessible interfaces for all users.

Be annoyingly thorough

  • Does what you've built actually match the design?
  • Review and re-review your work before you even ask for others to review.
  • Have you considered everything written here and in the PR checklist?
  • In the absence of automating some of the checklist, don't just tick them thinking you've done them. Ensure you've done them, then tick them.
  • Most of all, take pride in your work. We want it to live long and prosper.

Work with SVGs

  • Sketch is a great UI design tool, but a terrible design tool.
  • Since the only(?)/accepted way to use icons in Sketch is to mask the shape over a rectangle, it means SVGs exported from Sketch are quite ridiculously complex and not compatible with a web-based icon system.
  • Know that exporting SVGs from Zepli is just a minified, not optimised version of Sketch's output.
  • SVGs should be exported and opened (or copy/pasted) in Affinity Designer to be cleaned up, simplified and exported with these settings.
  • Ideally – and eventually – they'll be consumed within an automatic icon system, but for now, a hand-minified version using SVGOMG is the quickest option.
  • Icons should be exported at the size they're commonly used at to reduce browser rounding errors when scaling.
  • Icons should be aligned and visually (not mathematically) centred for the context in which they sit

Depending on the quality of the original icon, the following manual optimisations should be considered when working with SVGs:

  • Delete all unused layers & groups
  • Remove any layer names
  • Convert strokes to fills
  • Simplify the amount of nodes and shapes used
  • Remove unnecessary nodes in obscured, not visible paths
  • Redraw shapes as necessary (<path>s to <circle>s etc)
  • Combine shapes of identical colours (where applicable)
  • Reduce amount of fractional pixels for node positions
  • Set all path colours to #000000

Here's a comparison of the various outputs for chevron-down:

Sketch

<?xml version="1.0" encoding="UTF-8"?>
<svg width="24px" height="24px" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
    <!-- Generator: Sketch 59 (86127) - https://sketch.com -->
    <title>icon/chevron_down</title>
    <desc>Created with Sketch.</desc>
    <defs>
        <polygon id="path-1" points="4 -2 2.59 -0.59 7.17 4 2.59 8.59 4 10 10 4"></polygon>
    </defs>
    <g id="icon/chevron_down" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
        <g id="ic_chevron_down" transform="translate(6.000000, 8.000000)">
            <mask id="mask-2" fill="white">
                <use xlink:href="#path-1"></use>
            </mask>
            <use id="Mask" fill="#000000" transform="translate(6.295000, 4.000000) rotate(90.000000) translate(-6.295000, -4.000000) " xlink:href="#path-1"></use>
            <g id="Color/Navy-80" mask="url(#mask-2)" fill="#003453">
                <g transform="translate(-6.000000, -8.000000)" id="Rectangle">
                    <rect x="0" y="0" width="24" height="24"></rect>
                </g>
            </g>
        </g>
    </g>
</svg>

Zeplin

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="24" height="24" viewBox="0 0 24 24">
    <defs>
        <path id="a" d="M4-2L2.59-.59 7.17 4 2.59 8.59 4 10l6-6z"/>
    </defs>
    <g fill="none" fill-rule="evenodd" transform="translate(6 8)">
        <mask id="b" fill="#fff">
            <use xlink:href="#a"/>
        </mask>
        <use fill="#000" transform="rotate(90 6.295 4)" xlink:href="#a"/>
        <g fill="#003453" mask="url(#b)">
            <path d="M-6-8h24v24H-6z"/>
        </g>
    </g>
</svg>

Affinity Designer

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="100%" height="100%" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
    <path d="M18.295,9.705l-1.41,-1.41l-4.59,4.58l-4.59,-4.58l-1.41,1.41l6,6l6,-6Z"/>
</svg>

Affinity Designer minified

<svg viewBox="0 0 24 24"><path d="M18.295 9.705l-1.41-1.41-4.59 4.58-4.59-4.58-1.41 1.41 6 6 6-6z"/></svg>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment