Authoring HTML in a JavaScript World

Hi, I'm Tony Alicia. This is Authoring HTML in a JavaScript World. First, a little about me. You may find me teaching on Udemy, Pluralsight, Teachable, and YouTube and I work with a company called the Smythe Group. Now, if you'd like to connect, feel free to reach out. You can find me and my courses on my website at TonyAlicia.dev. Shoot me an email, find me on YouTube, Twitter. You can go to TheSmytheGroup.com to find out about how we help dev teams become their best selves and do their best work.

But this talk is Authoring HTML in a JavaScript World. And all of us, all of you that are listening, you all spend your time in JavaScript. Whether we're writing TypeScript, whether we're dealing with databases, whether we're on the server, whether we're writing tests, our life revolves around JavaScript. It's a JavaScript world. And yet there's three legs of the stool when it comes to foundational web technologies, HTML, CSS, and JavaScript.

So in this talk, I'd like to challenge you to change your way of thinking, to change your approach to how you build your React components. What I mean by that is this. Let's say you get a prototype. This is a very simplistic example. But you get a prototype, perhaps from a designer, and now you have to implement it. What's the first thing that goes through your head? What are the first steps in your mind as you imagine implementing the prototype in React? Well, it may be that you start thinking about which will be components, how the component structure will be, what the CSS will be to make the actual website or web app look like a prototype. So really, mentally, we kind of start in the CSS world. How can I make it look like the prototype? And we start in the JS world. How can I make it work? How can I make the actual app do what the prototype says it should do? And then along the way, somewhere along the road, we put in some HTML. It really is a sort of structure, a scaffold, a skeleton on which to hang a JavaScript code and CSS. And if we're writing JSX, you might say, well, I'm not writing HTML. But really, we are, because they're both being converted into the DOM. And so ultimately to the user, it's the same as if we were writing HTML. So choosing our elements is something that happens along the way. I'd like to challenge you to change your mindset and instead think about HTML first. What would happen if we thought about our HTML first and then started thinking about how to make the application work and the CSS comes along for the ride as we make it look like the prototype? Again, if we're just looking at the prototype and we're thinking about the HTML, what we're actually thinking about is what is the meaning of each of these pieces of information that we see in the prototype. If we're thinking about HTML, we're thinking about semantics and the word semantic means having to do with meaning. The entire point of authoring our HTML, and we're going to introduce that phrase when we author our HTML, when we behave as HTML authors, meaning we're choosing our HTML elements according to the information and things that are happening on the page on the screen, then we're dealing with semantics. We're authoring in a semantic way.

Now I'd like to talk about the benefits of authoring our HTML in a semantic way and what that really looks like. For starters, let's talk about learnability. We're all trying to keep up with the latest things happening in the JavaScript world. But HTML is a skill. HTML authoring is a skill. And it's a very learnable skill.

Let's go for example to a website that many front-end web developers have never visited. The HTML Specification. In that specification we have what is essentially our dictionary. The meaning of each of the HTML elements. I think every front-end developer should at least be familiar with section 4 of the HTML Specification, where it specifies what all of the elements mean, what they do.

For example, the address element. I can click on it, and if I use that element, it represents, again semantics, it represents the contact information for the nearest article or body element ancestor. So, in other words, if I have contact information for the page, or for something that's in an article element, I can use address. That would be the most semantic choice. I would be expressing meaning, as opposed to just wrapping it in a div, and we'll talk about that in just a bit.

So, the idea is that HTML is learnable. You can become familiar with the meanings of each of the elements. And that can help you in your work. Now beyond that, we can talk about readability and maintainability. That's another major benefit of thinking about your HTML, of authoring your HTML and your components, versus thinking about the CSS and JavaScript first.

So what do we mean by this? Well, if I don't author my HTML, if I think first about the CSS and JS and just try to make it look like the prototype and work like the prototype, then I probably might end up with something that looks like this. I might have lots of divs and spans, span div div div span, span div span div div span, because I'm really just using the HTML as a way to have if statements and things to return from my functional components and things to hang my CSS classes on. But I'm not thinking about the content. What does the content mean?

Another way to think about it is that, if I look at the prototype, I can first think about the content without any of the visuals. What are these things? Is it a header? Is it a name value pair with a name and then it's, it's actual value as far as like a title, like model Corolla year 2010, is it a list? Is it a list where order matters or it doesn't matter? Is it address information? Is it contact information? And then we begin to semantically mark up our document. And it might end up looking something like this. For example, the DL, DT and DD. Well, if I go to section four, and I look that up, I can see the DL, DT, DD, they represent association list name value pairs. So how can I mark up a name value pair that is a piece of data with its label that isn't a form element? Well, this would be one way. As opposed to span and div, I can do so semantically.

Now, when we think about this, when we compare the non-semantic to the semantic, what are the benefits? The benefits are immediately, the semantic version is more readable. I can look at the contents and understand what it is. And therefore, a year from now, when someone else on my team or me, when I return to look at these components, well, it's now more maintainable. It's easier for me to understand what they are, what they do, what their intent was. And when you think about coming back to look at your components, oftentimes these pieces of data aren't explicitly written.

Often they're variables. So, if you have div, div, span, div, span with lots of variables, it can be very difficult to understand what you're looking at. On the other hand, if you're well marked up, if you've authored your HTML, the HTML itself is providing information to you about what that content is. Plus, also, if you're in the browser and you're in the browser tools and you open up the elements, now instead of digging through a bunch of div, span, div, span, span, div, span, you're going to have elements available to you that can help you find your way as you're debugging, editing, etc. Some of these are benefits to readability and maintainability of your components.

So, if I have, in the future, a React component and I'm using my JSX and I'm choosing the elements that will ultimately end up being in the DOM, even just having good semantic elements returning from my React components and within my React components, I'm going to see that benefit. They open the component and they immediately have a better picture of what this thing is and what it does.

Alright, now, what's another benefit? Another benefit is accessibility. Now, when you think about accessibility you might think about ARIA, right? But, you know, you can add too much ARIA. You can make things worse. The first step of accessibility, and ARIA is important, but the first step is good HTML allowing the browser or screen readers to use the elements as anticipated because the people making browsers and screen readers, what are they looking at to decide how things work? How they interpret the HTML? They're looking at the specification, the HTML specification. So, if I say that this piece of information, this piece of data, this interactive piece of my web page or web app, if I mark it up properly, if I author my HTML, now the user agent can do its work properly. And by user agent, what we mean is a software program that translates content into the format a user wants to consume. See, our HTML is not about building visual web pages. It's about marking up information so that user agents, programs, like our browser, like a screen reader, can then decide what to do. Now, if I mark up a piece of text as strong, then maybe a visual browser will make it bold and a screen reader will say it in a different tone of voice. It's all about how the user wants to consume the information. That's why it's called a user agent. It's working on behalf of the user, and by authoring our HTML, we're working on behalf of the user as well. We're making our React components more accessible. And this goes back to the foundations of HTML. Here's a quote and I'll just focus on a couple aspects from the HTML specification itself. HTML conveys meaning, not presentation. So, you don't have to change the page in order to have different presentations, and that includes presentations through various screen readers. For example, a blind user using a browser, using speech synthesis, might get different vocal tones depending on how we've marked up our apps, our web pages. So, accessibility.

Now here's another one. Performance. Do you think about HTML when you think about performance? You're probably thinking about your JavaScript, you're probably thinking about your database, you're probably thinking about network and edge functions, whatever it is that comes to mind, but you know you can vastly improve the performance of your React applications by authoring your HTML well. How so? Well, every element that you place in your component, every level of elements that you add, becomes what ultimately? Becomes a node in the DOM. Becomes a piece of information in the user's device memory. Becomes something that the CSS has to traverse. Because when you do a CSS selector, you're asking it to look through the DOM and find certain nodes. The bigger, the wider, the deeper your DOM, the slower your application will perform. And that's not a new idea.

For example, in the Google Lighthouse scoring, there's an idea of avoiding excessive DOM size. And that says above a certain amount of nodes, 800 nodes, 1400 nodes, you're going to get into performance problems that will be flagged by the Lighthouse score. But that's not to say that all of a sudden, as soon as you reach that number of nodes, you have bad performance. As you add more nodes to your DOM, your performance decreases. It's the amount of time it takes for the JavaScript to generate templates, or if it's pre-generated on the server, it's larger amounts of information being downloaded. It makes your CSS slower. And the browser, the browser engine has to paint all of these things to the screen, has to decide what to do. So as you're scrolling or you're opening and closing in accordion, the more DOM elements you have, the less performant those interactions will be because the more the browser has to do.

I've actually worked with teams who were having a performance issue on some complex dashboard or page and app, and they were looking at the JavaScript and the database and the network. And in reality, we took a couple of hours to author their HTML. They had divs inside of divs inside of divs. Large amounts of nested nodes. And the problem is with something like React, well, if I author poorly in a component, and then I put that component in a loop inside a poorly authored component, and I put that component in a loop inside another poorly HTML authored component, my final DOM can be far larger than what it looks to be in my component JSX. So they ended up with so many DOM nodes. But that was the performance problem. A couple hours of work, and we saw a massive performance increase. By authoring properly, reducing the DOM size. Because when you think about the HTML, you tend to write less HTML. And you also tend to already have the placeholders you need for your CSS. For example, if I think about this semantic code. I am immediately starting to also see where the boundaries of components might be. I'm immediately starting to see where my CSS might need to hang. Might need to be attached to these DOM nodes in order to match the prototype. But if I'm just thinking about making it look right. Not only do I end up with non-semantic HTML. I tend to end up with HTML that looks like this. Nested, nested, nested. Because all I'm thinking about is, Oh, I need CSS for that, let me add an element. Oh, I need CSS for that, let me add an element. And we end up reducing, negatively impacting, the performance of our application simply by not authoring our HTML.

Now there's another benefit. And that benefit is future-proofing. Remember we said that the idea is that you're telling the user agent what this thing is, what these pieces of information are. And that means if a future user agent consumes the DOM, consumes the results of your JSX, consumes your HTML, then it will be able to determine how to present to its users your information.

For example, here's a new user agent, Safari for Vision OS. And when Vision OS and Safari and Vision OS was talked about, in one of the slides, it talked about interactive regions, meaning that you're looking at a web page. How do we know that this is something that I then can focus on, interact with, that I can copy-paste, whatever the case is. Well, they looked at the HTML, starting with things like buttons, and links, and menus. So, in the future, if I use a p-tag, a paragraph, instead of a div, then a future OS like Vision OS could say, ah, well, the p-tag is something that I can copy-paste. But if it's all divs, we don't really know, do we? So, if you invest the time now in your HTML, then you can save time later, and you make your app more future-proof, will last longer as user agents change in the future.

So often the question is, where to begin? I already have a lot of divs and spans in my React components. Well, some easy places to start. To start putting your mindset into the authoring your HTML place, think about elements that don't have default CSS, because often folks reach for divs because they don't have default CSS. But there are other elements that don't have default CSS, and you could start there. I want to show you one thing in the HTML specification. We can see that the div element is actually called in the specification the element of last resort, when no other element is suitable. But there are many other suitable elements where we often use div. For example, an article which is a self-contained piece of information, a card might be an article, a section of your document where there's headers, that could be a replacement for a div. A replacement for a div, the header element, we're often wrapping pieces. Maybe you have a header and a subheader and some icons. So we wrap those in divs. The header element could be perfect for that. An aside for something that isn't directly to do with whatever is on the page, like here's some other links, here's some other activities you can take on this particular app that isn't related to the page I'm looking at in the app. Those all can be direct swap outs for a div. And you can start to look at your content and start to think, well, is this an article? Is this a section? Is this a header? This is a side? And your team can actually have some fun having those conversations because there may not be a correct answer, a perfect answer, but at least you're thinking about it and you've decided as a team, you know what we think this is an aside. And, you will immediately see the benefits in maintainability, readability, when you're coming back and editing these components.

So again, I challenge you, try a different approach. Instead of CSS first, keep adding HTML elements as I need, make it all work, make it look like a prototype. Consider swapping it, start by looking at your content, authoring your HTML, and then begin to make it work, begin to make it look like the prototype. You'll be thinking in a way that will not only be learnable as a developer, become accustomed to what the elements are and available, but also in a way that will help you have more readable, maintainable, accessible, and future-proof React applications. And that's it, so thank you again, and I hope to see you online.