Nino's Blog

Semantic markup

2019-06-02

Often in code, I see that my colleagues don’t adhere to semantic markup, which leads to a11y problems. If you can’t spend time on learning all accessibility techniques, even though I believe you should, stick to this HTML template and you’ll utilize Pareto rule (80/20) to the fullest.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="description" content="This is a website of a non existing company.">
    <link rel="shortcut icon" href="./favicon.ico">
    <title>Company name</title>
    <script src="https://unpkg.com/some-package@1.0.0/package.js"></script>
  </head>
  <body>
  <header>
    <img src="..." alt="Company's logo" />
    <h1>Non existing company</h1>
    <nav aria-label="main"> <-- Since we have two nav elements on the page. -->
        <a href="/">Homepage</a>
        <a href="/career">Career</a>
    </nav>
    <button aria-press="false" aria-label="Play company's hymn"><svg aria-hidden="true">...</svg></button>
  </header>
  <main> <-- Landmark elements to indicate important content region. -->
    <section aria-labelledby="products">
      <h2 id="products">Products<h2>
      <form role="search" aria-labelledby="search-header">
        <h3 id="search-header">Product search<h3>
        <label for="search">Search products<label>  <-- Even if label is not in a design, use label, but hide it. -->
        <input id="search" type="search" aria-describedby="search-error">
        <button type="submit">Search</button>
        <span id="search-error" aria-live="polite">error text</span> <-- If providing feedback as user type use aria-live="polite", if you provide feedback on submit use aria-label="assertive". -->
      </form>
      <article>
        <header>
            <h3>We provide the best product ever</h3>
        </header>
        <h4>Reason 1 why it is the best</h4>
        <p>Some text...</p>
        <h4>Reason 2 why it is the best</h4>
        <p>Some text...</p>
      </article>
    </section>
    <aside>
      <section>
        <p>Get your promo coupon now</p>
      </section>
    </aside>
  </main>
  <footer>
      <section>
        <nav aria-label="secondary">
          <a href="/terms">Terms</a>
          <a href="/about">
            About
            <svg aria-hidden="true">...</svg> <-- To hide element from accessibility tree, since we have text "About".-->
          </a>
          <a href="https:://www.facebook.com/company" aria-label="Get in touch on Facebook"> <-- Icon only link -->
            <svg aria-hidden="true">...</svg>
          <a>
        <nav>
        <address>
            <p>Wall Street 1, NY</p>
            <p>
                <span>Yourtown</span>,
                <span>AK</span>,
                <span >12345</span>
            </p>
        </address>
          <address>
              <a href="mailto:us@example.com">fake@company.com</a>
          </address>
      </section>
  </footer>
  <body>
</html>

Here are other HTML elements that you may need:

  • <time> - Specifies the date/time within a document.
  • <q> Quote from some source.
  • <qblockquote> Block quote
  • <qcite> For citing.
  • <qinput> Input is used with various attributes to create form input elements.
  • <qtextarea> For multi-line text entry.
  • <qmeter> Used to represent a number when the minimum and maximum is known, for example 10%.
  • <qfieldset> Group related items in a form.
  • <qfigure> Define self contained content such as photos or diagrams.
  • <qcode> - For code examples. A little bit like <qsamp> and <qkbd>, but specifically for code.
  • <qdata> - Used for script friendly data.
  • <qabbr title=“Cascading Style Sheets”>CSS<q/abbr>
  • <qstrong> The enclosed text is of strong importance.
  • <qb> Similar for strong, but only styling will change, not sematnics.
  • <qbr> Single line break. Think of br as short for break.
  • <qhr> This can be used for separating text within a paragraph. Typically renders as a horizontal line running across the page.
  • <qwbr> The optional line wrap.
  • <qdd>, <qdt>, <qdl> Description list
  • <qdel> Mark text as deleted without actually deleting it. This will typically be rendered as a strikethrough.
  • <qins> Useful for denoting text that has been added to an HTML file since the original version. Updates to a blog post for example. This is typically rendered as underlined text, although this can really be rendered just about any way you want with a stylesheet.
  • <qdialog> Dialog box
  • <qiframe> Makes it possible to embed another page within a page.
  • <qtable> For making tables in an HTML page.
  • <qmenu> Used for creating various kinds of menus
  • <qmenuitem> Specify actions that can be taken with a menu.
  • <qselect> Used with <qoption> for selecting a particular option.
  • <qoption> Used within the <qselect> tag to specify an option.
  • <qsmall> Typically used for small print. Useful for comments within the main content.
  • <qnoscript> is useful for specifying content that should be rendered when scripting isn’t supported.
  • <qoutput> Displays the output of an action, such as from a script or form.
  • <qpre> For preformatted text. This can be useful for demonstrating code, especially if there are multiple lines.
  • <qsup> For displaying superscript. Useful for math, especially in conjunction with <qsub> (subscript).
  • <qprogress> Display the progress of an action, such as with a script.
  • <qtrack> Used to specify text tracks with <qaudio> and <qvideo>.
  • <qtable> For making tables in an HTML page.
  • <qtbody> Groups table rows.
  • <qtd> Table data; this represents a data cell within a table.
  • <qtfoot> Table footer.
  • <qth> Table header cell.
  • <qthead> Table header row.
  • <qdetails>, <qsummary>

    I have keys but no doors. I have space but no room. You can enter but can’t leave. What am I A keyboard.

Written by Nino Majder who lives and breaths web development. Follow him on Twitter