General Guidelines

Highlighting general best practices relevant to all dapp categories.

Intro

This section will emphasize best practices that are applicable across all the dapp categories. They comprise features that will be present regardless of the purpose and features of the dapp. This includes practices related to layout, navigation, and errors.

Basic Structure

  • Landmark and elements should follow a logical order

Landmarks

✅ Valid

<h1>Main Title <h1/>

    <h2> Section 1 <h2/>
        <h3> subtitle <h3/>

    <h2> Section 2 <h2/>
         <h3> subtitle <h3/>

✅ Valid

<h1>Main Title <h1/>

    <h2> Section 1 <h2/>
        <h3> subtitle <h3/>
            <h4> Feature <h4/>

❌Invalid : Skipped a level

See This Example: https://bad-dash-dapp.netlify.app/


<h1>Main Title <h1/>

<h2> Section 1 <h2/>
<h4> subtitle <h4/>

🟡 Not invalid per guideline, however expected by users and considered best practice :

Only 1 h1 allowed 

<h1>Main Title <h1/>

<h1> Section 1 <h1/>
<h2> subtitle <h2/>

This last example may be permitted on pages where there are technically two documents

Dapps with Sidebars / Navigation

See this reference, essentially navigation h2 headers may go before the main h1 title of the page:

https://www.w3.org/WAI/tutorials/page-structure/headings/#main-heading-after-navigation

Proper Error Handling Messages and Alerting

Dapp Errors

  • This is an area that may require more community effort, as some errors are blockchain specific (RPC errors) and can be abstracted for the user.

  • Here is a list of RPC error examples: https://support.quicknode.com/hc/en-us/articles/18106039481745-EVM-RPC-Error-Reference

  • Of course, wallet related errors are not the responsibility of dapp developers. However, contract specific errors related to the dapp can be abstracted or passed along with an error code for the user to raise a support ticket.

    • For example: "Failed to Stake" -> can have different error codes corresponding to the underlying reason

      • Code E01 : User Balance Low

      • Code E02: Staking Pool is full

      • etc

  • The Error message should be simple, and free of jargon as much as possible. Using codes can help users who would like to select and read more through documentation or pass it along to your group for support.

  • The bottom line, is that the error should convey the issue as concisely and clearly as possible.

Accessibility Documentation of Features

  • Keep a simple, clear list of issues that need to be resolved, offering any workarounds that users can leverage in the meantime.

    • Issues can be also kept open in public repositories. Ideally tag them as "a11y" bugs or patches for easier tracking and search.

Instructions / Help

  • Especially important for adoption and newcomers

Help

  • In addition to providing instructions and guidance for your dapp, also support or provide means to contact for further help. This could be in the form of a link to an accessible forum or email.

  • When help is present on the page, it must be consistent throughout the dapp. For example if a floating help button appears on one page, it should appear on others.

  • Dapps should include site maps even if they are simplistic. The site map should ideally include a 'contact us' link.

  • Context specific help can be extremely useful to supplement general page instructions.

    • For instance, what will a specific action do on this dapp?

    • Avoid Tooltips if possible. Although the pattern exists, a toggle or popup is often a better user experience.

WCAG Reference:

Instructions

  • Nearly all participants are willing to learn new technologies provided the documentation is accessible and easy to read and learn

Simple, jargon free text on website

  • If a website is more technical, there should be some form of documentation or further information for the user to easily and quickly understand the gist of the page

  • Abbreviations should also be defined via some mechanism for the user to determine the full meaning of the word. For instance an info popup on selecting "DEX" key term could offer a quick explanation that states it is a decentralized exchange, where users can trade without their assets being held by a third party.

Jargon

Some example changes that would be helpful for newcomers:

  • DAOs -> Voting / Governance

  • DEX -> Exchange

  • RPC Calls -> Request

WCAG 2.2 Reference

Keyboard Accessibility

  • "Skip to Main Content" button at the top. When the user first loads the site and hits tab, a button should popup allowing them to skip to the main content on the page.

  • Site Maps should be present even for simple applications

Tabbing

Tab through every component on your screen. Can you easily navigate the page only with a keyboard? Can you navigate each component in an obvious sequence?

WCAG 2.2 has expanded AA / AAA guidance to include a larger focus ring as well. This can be modified using styling atop component libraries:

  • Larger Focus Ring is a AAA enhancement depicted below.

Target Size

  • Users with motor/dexterity require more space and ease for interactive elements

  • They need better spacing and larger click areas so they do not miss or select the wrong buttons, links, etc. See the screen shot outside of this expandable for an example

  • In the screengrab below this section, we can see that there is a large enough space (and it's tabbable!) for users to select to move the carousel left or right.

Carousel component from our marketplace accessible example. Fake NFT collections are depicted such as a guitar, landscapes, etc
Target Size Example (see expandable section above)

Screen Reader Accessibility

  • The majority of WCAG covers screen reader accessibility, our guide highlights some specific guidelines pertinent to dapps, however kindly reference WCAG for considerations beyond anything we've highlighted here

Captions on videos

Captioning

  • Some dapps featured video content in the form of promotion or educational marketing

  • Regardless of whether you embed a video within your dapp/site, automatic captions do not necessarily capture and convey all text accurately. Consider building off the automatic transcript and amending inaccuracies. Furthermore, consider offering a separate summary and transcript.

  • Limit animations

DO NOT USE OVERLAYS!

  • If you're reading this guide, kindly research the subject of "accessibility overlays". They are generally discouraged by developers.

  • We've included this as its own point in our contribution guidelines.

Overlay Resources

Color Contrast

  • This is by far somehow the easiest issue to correct, yet simultaneously the most prevalent.

    • There's many tools in the form of browser plugins or websites that allow you to test for sufficient contrast. If you contribute one thing and only one thing to accessibility please at least do this.

Contrast

  • We've elected to use the following browser plugin, however many other websites and plugins exist. Feel free to use what works best for you.

  • Conceptually it is the same process, you can select via the color widget or via the dropper tool. Select the background color and the foreground color (usually the text). The tool will inform you if you've met WCAG standards for color contrast

  • There are some other options the tool allows you to use such as running an automated test or conducting a guided audit. Feel free to use those as well, however again many other tools exist.

WCAG 2.2 Reference

Login Button

  • Covered in Introduction > Foundational Basis > Laws of UX

  • Essentially as Jakob's law states, users have existing mental models.

  • Using existing login/signup button flows is key to making a better experience. On select, the user may choose to connect wallet among the modal options.

User Help

  • We've dedicated a subpage to this, see Consistent Help.

  • Essentially the user should always have access to some form of assistance or contact information.

Legal Popups/ Disclaimers

Legal Popups/Disclaimers

  • We encountered a lot of showstoppers (accessibility barriers) with regards to this.

  • It is understandable if a user is required to legally accept to meet legislation and compliance, however the user must be able to accept or close the popup.

  • Some users may get past with screen recognition, but ultimately the user must be able to accept the terms with just tabbing and also be able to understand the terms.

  • Some other variations of this include:

    • A Dapp has a sign to continue on a dapp browser

    • Dapp push notifications inaccessible

Sample Legal Disclaimer popup, at the bottom right is a button to accept the terms and continue.
Sample Legal Disclaimer popup

Mobile First Design:

  • Overall there is a stronger preference for mobile, regardless of whether people are on the go it's more convenient

WCAG 2.2 States:

WCAG 2.2 was initiated with the goal to continue the work of WCAG 2.1: Improving accessibility guidance for three major groups: users with cognitive or learning disabilities, users with low vision, and users with disabilities on mobile devices.

Mobile First

  • In browser developer consoles you may view your dapp or website in tablet or phone mode. As you switch to this view, what do you notice?

  • Many dapps tend to not be designed for mobile or to support different device types. As such elements overlapped, collapsed, or were not interactable.

  • Mobile first design contributes to adaptive interfaces and is better practice. Majority of users around the world are using phones, even outside of the accessibility community.

W3C Reference

PreviousDocumentation StructureNextGas Fees

Last updated