This style guide is a work in progress; illustrations are coming soon. As-is, it powers the competitive advantages of Awọ

HTML Style Guide

The guides to doc-first markup

How to write better and consistent HTML

With a hundred and fifteen elements, as of writing, HTML makes plain text rich; rich for all users browsing with sight, sound, and touch. Heaven on earth.

Unto whomsoever much is given, of him shall be much required. Here, this much is semantics — the act of using the right element.

Semantics make a webpage available for whatever applicable sense organ users may use. Yet, the forces of the web are, secondarily, against it.

  • Web technologies are permissive languages.

    HTML won't complain if you use the wrong element. All, unfortunately, goes if, for example, you use a div element instead of a blockquote element.

    There and there, CSS can come in to fake any element. It can make a div element look like a blockquote element, or a list item, or, even, a variable phrase.

    To cap it, JS can make an element behave like another. It can make a div element, become clickable, be like: an a element, a button element, or another interactive element.

    Verily, for markup inspired by ideologies above, destruction is prepared, and a place in the outer darkness awaiteth it. HTMHELL.

  • Learning resources are counter-intuitive.

    Authors think in components: I need a postheading.

    Then, rethink in elements: I need a p element that must be after a h1, h2, h3, h4, h5, or h6 element that is under a hgroup element.

    And then, think about content models: What child components are allowed for this postheading? Oh, first of all, is the heading group, the parent of the postheading, allowed as a child where it was intended?

    Those thoughts shall cause the author to stumble, for before him lie twain tribulations which he must face:

    First, a conflict of expectations:

    Resources organize HTML by elements-to-use before content-they-create. Wheareas, authors think by content-to-create before elements-to-use.

    Second, loose and heterogenous content models:

    Loose because: the spec that strongly encourages an explicit p element, allows a blockquote element to contain phrasing content, thus, creating an implicit p element.

    Heterogenous because both p and div elements are Flow content. Yet, the content model of p element is phrasing content while, that of, blockquote element is flow content.

  • Most user-facing tool hardly takes advantage of those semantics.

    Browsers, the core agent every user uses, bury options to adjust the font size and color mode down in the settings page. Options far enough to discourage its uses; options incomplete to personalize a webpage.

    Moreso, among others, it doesn't help detect the contact information of the author, or the page depending on the use case of the address element. You have to browse through, line by line, for such when you could have jumped.

    Only if you don't need a plugin to experience the richness of the web. If.

As a result, web documents are no longer, truely, documents. Try your favourite homepage in reader mode, with a tool like Elo, check for readability — the document structure.

Poor knowledge and visual design have influenced how we write HTML.

To do better is to think doc-first. A mental model to structure markup for all users; not just only to the majority; not just only to those with sight.

Rather than by elements, this resource organizes HTML by components — and with style.

Neither will you learn to conjure elements to create components. Conjuring is wild: one element may create many components, and many elements may create one component. Nor will you walk in the wilderness of the untamed. HTML is very tolerant, and this is a ticking time bomb.

You'll browse through an index of components HTML can create. You'll walk with style.

Showing 0 components:

Metadata

8+2 elements for 26 metadata components

Metadata provide information about the document to agents.

8 elements: base, head, html, link, meta, script, style, and title; with 2 of eight transparent elements: noscript, and template; create and modify 26 metadata components.

Those elements are all elements used outside the body of a web document.

base, script, and title elements create one metadata each; a total of 3.

link element creates eight standard metadata, and any custom metadata, a total of 9, via some tokens of the rel attribute:

  • Icons, manifest, next, pingback, search, and stylesheet tokens create one metadata each.

  • Alternate token creates 2 metadata depending on whether or not there's an application mime type attribute. Besides, alternate token also modifies a stylesheet token.

style element create a persistent stylesheet. Like a link element with a rel of stylesheet, but persistent.

meta element creates thirteen standard metadata, and any custom metadata; a total of 14; via some attributes:

  • charset attribute creates 1 metadata.

  • http-equiv attribute creates 2 metadata via 2 of its 5 keywords: content-security-policy and refresh keywords. As for the other keywords: content-language, and set-cookie are non-conforming; content-type is an alternative of the charset attribute; default-style modifies a stylesheet; and x-ua-compatible target, now, obsolete browser;

  • name attribute creates 10 metadata via keywords of some standards. HTML Standards: application-name, author, description, generator, keywords, referrer, theme-color, and color-scheme keywords. CSS Standard: viewport. SEO standards: robots.

A web document must have one, and only one, title metadata. That one is optional if, and only if, the document is an iframe srcdoc document, or if title information is available from a higher-level protocol.

The title document, along with other metadata, and modifiers, must be under a head element, the metadata root, a root of elements for agents, which, along with a root for users, must be under a html element, the document root, which, also, must be after a doctype declaration — a declaration to help agents determine an appropriate rendering mode, validation method, etc..

Besides the title metadata should be: only one charset metadata, only one viewport metadata, base style metadata, and a specified language; for readability and responsiveness of the document.

A lang attribute on the html element specifies the document language.

Within the head element, a noscript element may contain: link, style, and meta elements; to modify their state for a script disabled state. As well as, a template element may contain any metadata for reusability.

Blocks

How 25+1 elements create 9 blocks

Blocks build the body of a web page.

12 primary elements: h1, h2, h3, h4, h5, h6, p, pre, summary, legend, th, and td; 14 secondary elements: body, main, hgroup, details, fieldset, dl, table, thead, tbody, tfoot, tr, colgroup, and col; with 1 multipurpose element: section; create and manage 9 blocks.

Primary block elements are block-level elements that can't contain block-level elements. They only contain inline-level elements.

h1 element creates a heading block, while h2 – h6 elements modify the level, progressively.

There can be any number of child headings, h2 – h6 elements, but the heading level, the number after the h, must only be one greater than that of the parent heading.

Just as one title element is a must for user agents to detect, so should one h1 element be for users to sense.

Each heading block should have a parent heading group, a hgroup element, to provide the scope for preheading and postheading blocks.

Moreso, a heading block should have an explicit section, general or independent, that is, a section element, or an article element, to define the boundary of the heading's content.

The root section, a section for h1 element, should have an explicit wrapper in element of main, a primary landmark, to define the scope for secondary landmarks.

A sub-section should be a child to a parent section; you should not section a non-sectioning element.

Since it is unrealistic to section secondary landmarks with off-page content, only the main landmark should have headings.

All landmarks must be in the body element, a root of elements for users, following the head element, a root of elements for agents.

pre elements, one of two paragraph types, create preformatted paragraphs.

p elements creates 3 block components depending on its context. If p is outside of an hgroup element, it's a plain paragraph, the other of two paragraph types. Else, if within, it can be: a preheading if before the heading block, or a postheading if after the heading block.

summary, legend, td, and th elements create title blocks.

To contain a title and its content, summary element requires a details element; legend element requires a fieldset element; td element requires a dl element; and th element requires a tr element, with a table element, and may use a thead element, tbody element, tfoot element, colgroup element, and col element.

Mixes

How 20+8 elements creates 22 mixes

Mixes create compound content for headings and titles. They contain paragraphs, and, optionally, themselves.

17 primary elements: address, article, aside, blockquote, caption, dd, dialog, div, figcaption, figure, footer, form, header, li, nav, search, and td; 3 secondary elements: ol, ul, and menu; 7 of eight transparent elements: a, del, ins, map, noscript, slot, and template; with 1 multipurpose element: section; create and manage 22 mixes.

Those elements, except secondary elements, are block-level elements that can contain paragraph blocks.

7 mix elements: aside, footer, form, header, nav, section, and search; create 7 secondary landmarks. Along with the primary landmark, the main element, they partition the body element.

Landmarks should not contain landmarks; Landmarks should partition the body element, not themselves.

Like how those 7, together with the main element, partition the body element for landmarks, so should those 7, together with an article element, partition a section for segments. Afterall, majority of them: nav, aside, header, and footer; already does.

Unlike the main element, which was scoped by the root heading, an article element create 1 mix of its own.

Within each partition should content lie in. No content should be outside of a partition.

17 more elements: address, blockquote, caption, dd, dialog, figcaption, figure, li, td, a, del, ins, map, noscript, slot, template, and div; with those 3 secondary elements; create 11 cards and 3 lists.

Not each of those seventeen create their own component. One may: create more, or support another.

  • li element, a list item, creates 3 list types: ordered list with ol element, unordered list with ul element, and menu list with menu element.

  • figcaption element helps figure element with a caption.

  • td, and caption elements provide data cells, and layer caption, respectively, for a table element initiated by a th element, a block component.

  • A set of dd elements provide the descriptions for each item initiated by a dt element, a block component.

  • slot element create a placeholder in a template element for a declarative shadow dom

A div element should group anonymous, block-level, content so CSS and JS may target them. Anonymous content may be by the introduction of: an element between a text, or an auxiliary content beside a main content.

Furthermore: a heading, summary, and legend elements should use a div element to contain their content to avoid anonymous content. Also, for consistency with other leads: td and its dd container; with th and its td container.

Similarly, a dt item should use a div element to wrap each item to avoid anonymous items.

A div should group anonymous content at inter-block level to avoid anonymous content.

  • hgroup, summary, and legend creates anonymous followers. Moreso, they create inconsistent markup to the other titles: dt and th.

  • hr creates anonymous sides.

  • Auxiliary content leaves main content anonymous.

Phrases

How 32+7 elements create 35 phrase components

Phrases build blocks using media and forms.

31 primary elements: abbr, b, bdi, bdo, button, cite, code, data, datalist, dfn, em, i, kbd, label, mark, meter, output, progress, q, rt, ruby, s, samp, small, span, strong, sub, sup, time, u, and var; 7 of eight transparent elements: a, del, ins, map, noscript, slot, and template; create ? phrases; with 1 secondary element; create and manage 35 phrases.

Primary phrase elements are inline-level elements that can contain inline-level elements for main content but not fallback content.

Those elements, except the secondary element, create phrase components, each.

Every phrase should be in a block, otherwise it becomes a part of an implied paragraph. Such paragraphs, even when on purpose, are open for transparent elements to cross, thus, open for misinterpretations.

A span element should group anonymous, inline-level, content so CSS and JS may target them. Anonymous content may be by the introduction of: an element between a text, or an auxiliary content beside a main content.

A span should group anonymous content at intra-block level to avoid anonymous content.

  • wbr, and br creates anonymous sides.

  • Phrases creates anonymous sibling text.

  • Auxiliary content leaves main content anonymous.

Media

How 15 elements plus text create 10 media

Media present information in Blocks.

9 primary elements: audio, canvas, embed, iframe, img, math, object, svg, and video; text; 6 secondary elements: area, br, picture, source, track, and wbr; with one of eight transparent elements: hr; create and manage 10 media.

Those primary elements, with text, create 10 media components.

Each media should have a span element, as a wrapper, to take advantage of the benefits of a box model, like the use of pseudo elements.

Forms

How 6 elements create 24 forms

Forms accept information in Blocks.

3 primary elements: input, select, and textarea; with 3 secondary elements: selectedcontent, optgroup, and option; create and manage 24 forms.

input element creates 22 forms via keywords of its type attribute.

select, and textarea elements create one form each.

Each form should have a span element, as a wrapper, to take advantage of the benefits of a box model, like the use of pseudo elements.