Angular

Make it Accessible: Better Layout with HTML

May 22, 2020

5 min read

Make it Accessible - 8 Part Series

Make it Accessible: Better layouts with HTML

In this article, I'm going to teach you how to use the HTML tags <div>, <section> and <article>, and how they can improve your web applications accessibility.

Here you can access all the resources used in the article.

The Problem

Web applications are built with HTML, and even though it isn't a programming language, it is nontheless complex. One of the first issues you may encounter is knowing which element to use, and the huge amount of elements available makes this issue even more challenging.

When it comes to your page's layout, some of the options are; <div>, <section> and <article>. Today, you're going to learn when you should use each of them.

The Solution

First, we will conceptualize each of the elements I just mentioned. You can learn more about these in the w3c wai aria practices guide, but let's discuss those concepts here:

The <div> element is often used as a container for other HTML elements to style them with CSS or to perform certain tasks with JavaScript. w3schools.com

You may be tempted to use <div> with some styles instead of learning about the available elements in HTML5. I have to tell you, if you do that, you're hurting your users. Each element has a specific purpose, and you should be using the right element. <div> is useful when you want to group some elements and give them some styling, that doesn't mean you should make everything with <div>.

The <section> tag defines sections in a document, such as chapters, headers, footers, or any other sections of the document. w3school.com

This is a very important tag as you start your accessibility journey. It gives context to your users, specially those with Screen Readers. By "context", I mean that if you wrap a group of elements with a section and give it an accessible name, once users focus one of the elements, it reads the parent container too.

The <article> tag specifies independent, self-contained content. w3school.com

Almost every application has some kind of catalogue showing several items having the same styles, and if you think it through, these items could be placed anywhere without any context. Articles are cool for those cases, even though these aren't landmarks, it's common for Screen Readers to have a mechanism to allow users to navigate through articles easily.

The Implementation

Next, we're going to do a small sample using each of the mentioned elements. Let's start with the <div>.

Using divs right

Now that you are fully aware of the purpose of a <div>, it is time to use it. For this one, I decided to take the easy road and make a very simple example. Let's say you have multiple "things" you want to group, and to which you want to apply some additional styling. That can be easily done like this:

<html>
  <head>
    <style>
      .square {
        display: inline-block;
        width: 150px;
        height: 150px;
        border: 1px solid black;
        margin: 10px;
        background-color: white;
      }

      .group {
        display: inline-block;
        margin: 0;
        background-color: #bbb;
      }
    </style>
  </head>

  <body>
    <header>
      <h1>Using divs right</h1>
    </header>

    <main>
      <div class="group">
        <div class="square"></div>
        <div class="square"></div>
      </div>
      <div class="square"></div>
      <div class="square"></div>
      <div class="square"></div>
    </main>
  </body>
</html>

To test this, create a file with the .html extension containing what I just gave you, and open it with your preferred browser. You'll notice that the first two have a light gray background. Once again, very simple and easy to follow. Let's jump to the next example.

Sections are the way to go

For this one, I was looking for a more exciting example. Let's say you are building an application for a movie theater that allows customers to order tickets online. If you buy a ticket, you want to have a page where you can see all the details about the movie and your ticket.

Let's start by thinking it through. We want to see all the information about the movie, title, synopsis, a banner image, and a genre. When it comes to the ticket, I want to see its worth, my seat number, and the time left for the show to start.

The HTML for something like this would look like this:

<html>
  <head>
    <style>
      body {
        margin: 0;
        padding: 0;
      }

      main {
        display: flex;
        align-items: flex-start;
        justify-content: center;
        flex-wrap: wrap;
        background-color: #333;
        min-height: calc(100vh - 80px);
        margin-top: 80px;
      }

      header {
        position: absolute;
        height: 80px;
        color: white;
        background-color: #444;
        padding: 2px 0;
        text-align: center;
        box-shadow: 0px 6px 3px 3px rgba(0, 0, 0, 0.1);
        width: 100%;
        top: 0px;
      }

      .card {
        box-shadow: 0px 6px 3px 3px rgba(0, 0, 0, 0.1);
        display: inline-block;
        margin: 20px;
      }

      .movie-details {
        width: 400px;
      }

      .movie-details figure {
        width: 100%;
        margin: 0;
      }

      .movie-details figure img {
        width: 100%;
        object-fit: cover;
      }

      .container {
        padding: 10px;
        border: 1px solid #333;
        background-color: #444;
        color: white;
      }

      .ticket-summary {
        width: 250px;
      }

      .ticket-summary dt {
        color: #ccc;
        font-size: 1.1rem;
        font-weight: bold;
        margin-top: 8px;
      }
    </style>
  </head>

  <body>
    <header>
      <h1>Your Ticket Details</h1>
    </header>

    <main>
      <section class="card movie-details" aria-label="movie details">
        <figure>
          <img src="./img.jpg" alt="" />
        </figure>

        <div class="container">
          <h2 style="margin: 6px 0;">Parasite</h2>
          <p style="text-align: justify;">
            Greed and class discrimination threaten the newly formed symbiotic
            relationship between the wealthy Park family and the destitute Kim
            clan.
          </p>
          <p><b>Comedy, Drama</b></p>
        </div>
      </section>

      <section
        class="card ticket-summary"
        aria-labelledby="ticket-summary-title"
        aria-describedby="ticket-summary-description"
      >
        <div class="container">
          <h2
            id="ticket-summary-title"
            style="margin: 6px 0; text-align: center;"
          >
            Ticket Summary
          </h2>
          <p id="ticket-summary-description" style="text-align: justify;">
            Remember to exchange your ticket identifier for the actual ticket as
            soon as you get to the movie theater.
          </p>
          <dl>
            <dt>Identifier</dt>
            <dd>123</dd>
            <dt>Seat</dt>
            <dd>B-12</dd>
            <dt>Price</dt>
            <dd>$ 2,00 USD</dd>
            <dt>Starts in</dt>
            <dd>2h 30m</dd>
          </dl>
        </div>
      </section>
    </main>
  </body>
</html>

For now you can ignore the styles, it's just to make it look less ugly, what I want you to pay attention to is the HTML part. Look at how I created two sections- one for the movie details, and one for the ticket summary. Another important takeaway is how I used aria-label and aria-labelledby. Both have the same results, but in the movie details, I wanted to read "Movie Details" instead of the movie title, and in the case of the Ticket Summary, it's different because we want to read the same title.

By structuring your HTML document this way, using sections with the proper accessible names, you're not only giving context to the user, but you're creating a hierachical view of the landmarks of your application. This makes it easier for Screen Readers to understand your page, and as a consequence, you get better usability for your disabled users.

Articles are useful too

I know that example may have set the bar a little high. For this example, I'm doing something simpler. Let's say that this movie theater we are "working for" wants to show all the available movies to possible customers. This is where articles shine the most, because let's face it, no matter how many movies there are, all of them will have the same styles.

Let's roll up our sleeves, and create a new html file with this content:

<html>
  <head>
    <style>
      body {
        margin: 0;
        padding: 0;
      }

      main {
        display: flex;
        align-items: flex-start;
        justify-content: center;
        flex-wrap: wrap;
        background-color: #333;
        min-height: calc(100vh - 80px);
        margin-top: 80px;
      }

      header {
        position: absolute;
        height: 80px;
        color: white;
        background-color: #444;
        padding: 2px 0;
        text-align: center;
        box-shadow: 0px 6px 3px 3px rgba(0, 0, 0, 0.1);
        top: 0px;
        width: 100%;
      }

      .card {
        box-shadow: 0px 6px 3px 3px rgba(0, 0, 0, 0.1);
        display: inline-block;
        margin: 20px;
      }

      .movies {
        display: flex;
        justify-content: center;
        flex-wrap: wrap;
        width: 800px;
      }

      .feed {
        display: flex;
        margin-top: 10px;
      }

      .movie {
        width: 200px;
        height: 420px;
      }

      .movie figure {
        width: 100%;
        height: 300px;
        margin: 0;
        overflow: hidden;
      }

      .movie figure img {
        width: 100%;
        object-fit: cover;
        height: 100%;
      }

      .container {
        padding: 10px;
        height: 100px;
        border: 1px solid #333;
        background-color: #444;
        color: white;
      }

      .movie h2 {
        margin: 8px 0;
        font-size: 1.2rem;
        font-weight: bold;
      }

      .movie p {
        margin: 8px 0;
        font-style: italic;
      }
    </style>
  </head>

  <body>
    <header>
      <h1>Movies List</h1>
    </header>

    <main>
      <section class="movies" aria-label="available movies">
        <div role="feed" class="feed">
          <article
            class="movie card"
            aria-labelledby="movie-name-1"
            aria-describedby="movie-genre-1"
            tabindex="0"
            aria-posinset="1"
            aria-setsize="3"
          >
            <figure>
              <img src="./movie-1.jpg" alt="" />
            </figure>
            <div class="container">
              <h2 id="movie-name-1">The Shawshank Redemption</h2>
              <p id="movie-genre-1">Drama</p>
            </div>
          </article>
          <article
            class="movie card"
            aria-labelledby="movie-name-2"
            aria-describedby="movie-genre-2"
            tabindex="0"
            aria-posinset="2"
            aria-setsize="3"
          >
            <figure>
              <img src="./movie-2.jpg" alt="" />
            </figure>
            <div class="container">
              <h2 id="movie-name-2">The Godfather</h2>
              <p id="movie-genre-2">Crime, Drama</p>
            </div>
          </article>
          <article
            class="movie card"
            aria-labelledby="movie-name-3"
            aria-describedby="movie-genre-3"
            tabindex="0"
            aria-posinset="3"
            aria-setsize="3"
          >
            <figure>
              <img src="./movie-3.jpg" alt="" />
            </figure>
            <div class="container">
              <h2 id="movie-name-3">The Dark Knight</h2>
              <p id="movie-genre-3">Crime, Drama</p>
            </div>
          </article>
        </div>
      </section>
    </main>
  </body>
</html>

Remember to focus on the HTML structure, not the styles. The first time I saw this kind of code, I was like, wow, what's all that aria stuff doing? Today, I'm going to make this easier for you.

First of all, I have to remind you that all of these ideas come from the WAI ARIA Authoring Practice Guide.

One thing to notice before heading to the code is that a list of movies is a feed. Also, don't reinvent the wheel. The WAI ARIA guide has a very detailed description of how a feed should be implemented while prioritizing accessibility. You have to start with <div> and role="feed", next you have to work on the articles.

Setting up the feed container is very simple. What's not so straightforward are the articles themselves. Each of the aria properties has a specific purpose:

aria-labelledby: Title of the movie.
aria-describedby: Additional information about the movie.
aria-posinset: Position of the movie in the list.
aria-setsize: Size of the list of movies.

There's also a tabindex="0" because once in a feed, screen readers provide users with additional navigation mechanisms that require us to make the articles "focusable".

NOTE: All the <img> in the samples have an empty alt like this alt="". It's because using an empty alt tells screen readers to ignore the images entirely, in a real life project for images that provide information, you always give a proper alt value.

Conclusion

Every time I write one of these series, I come up with the same conclusion: Just use HTML! I'm even thinking of changing the name to "It's Already Accessible". It's common to hear developers saying that HTML is too simple. It might be for some, but you still have to learn it. Whenever you write an application, try to build it following patterns like the ones in WAI-ARIA. Make sure to follow their specifications, and you'll make applications all of your users will love.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

I Broke My Hand So You Don't Have To (First-Hand Accessibility Insights)

We take accessibility quite seriously here at This Dot because we know it's important. Still, throughout my career, I've seen many projects where accessibility was brushed aside for reasons like "our users don't really use keyboard shortcuts" or "we need to ship fast; we can add accessibility later." The truth is, that "later" often means "never." And it turns out, anyone could break their hand, like I did. I broke my dominant hand and spent four weeks in a cast, effectively rendering it useless and forcing me to work left-handed. I must thus apologize for the misleading title; this post should more accurately be dubbed "second-hand" accessibility insights. The Perspective of a Developer Firstly, it's not the end of the world. I adapted quickly to my temporary disability, which was, for the most part, a minor inconvenience. I had to type with one hand, obviously slower than my usual pace, but isn't a significant part of a software engineer's work focused on thinking? Here's what I did and learned: - I moved my mouse to the left and started using it with my left hand. I adapted quickly, but the experience wasn't as smooth as using my right hand. I could perform most tasks, but I needed to be more careful and precise. - Many actions require holding a key while pressing a mouse button (e.g., visiting links from the IDE), which is hard to do with one hand. - This led me to explore trackpad options. Apart from the Apple Magic Trackpad, choices were limited. As a Windows user (I know, sorry), that wasn't an option for me. I settled for a cheap trackpad from Amazon. A lot of tasks became easier; however, the trackpad eventually malfunctioned, sending me back to the mouse. - I don't know a lot of IDE shortcuts. I realized how much I've been relying on a mouse for my work, subconsciously refusing to learn new keyboard shortcuts (I'll be returning my senior engineer license shortly). So I learned a few new ones, which is good, I guess. - Some keyboard shortcuts are hard to press with one hand. If you find yourself in a similar situation, you may need to remap some of them. - Copilot became my best friend, saving me from a lot of slow typing, although I did have to correct and rewrite many of its suggestions. The Perspective of a User As a developer, I was able to get by and figure things out to be able to work effectively. As a user, however, I got to experience the other side of the coin and really feel the accessibility (or lack thereof) on the web. Here are a few insights I gained: - A lot of websites apparently _tried_ to implement keyboard navigation, but failed miserably. For example, a big e-commerce website I tried to use to shop for the aforementioned trackpad seemed to work fine with keyboard navigation at first, but once I focused on the search field, I found myself unable to tab out from it. When you make the effort to implement keyboard navigation, please make sure it works properly and it doesn't get broken with new changes. I wholeheartedly recommend having e2e tests (e.g. with Playwright) that verify the keyboard navigation works as expected. - A few websites and web apps I tried to use were completely unusable with the keyboard and were designed to be used with a mouse only. - Some sites had elaborate keyboard navigation, with custom keyboard shortcuts for different functionality. That took some time to figure out, and I reckon it's not as intuitive as the designers thought it would be. Once a user learns the shortcuts, however, it could make their life easier, I suppose. - A lot of interactive elements are much smaller than they should be, making it hard to accurately click on them with your weaker hand. Designers, I beg you, please make your buttons bigger. I once worked on an application that had a "gloves mode" for environments where the operators would be using gloves, and I feel like maybe the size we went with for the "gloves mode" should be the standard everywhere, especially as screens get bigger and bigger. - Misclicking is easy, especially using your weaker hand. Be it a mouse click or just hitting an Enter key on accident. Kudos to all the developers who thought about this and implemented a confirmation dialog or other safety measures to prevent users from accidentally deleting or posting something. I've however encountered a few apps that didn't have any of these, and those made me a bit anxious, to be honest. If this is something you haven't thought about when developing an app, please start doing so, you might save someone a lot of trouble. Some Second-Hand Insights I was only a little bit impaired by being temporarily one-handed and it was honestly a big pain. In this post, I've focused on my anecdotal experience as a developer and a user, covering mostly keyboard navigation and mouse usage. I can only imagine how frustrating it must be for visually impaired users, or users with other disabilities, to use the web. I must confess I haven't always been treating accessibility as a priority, but I've certainly learned my lesson. I will try to make sure all the apps I work on are accessible and inclusive, and I will try to test not only the keyboard navigation, ARIA attributes, and other accessibility features, but also the overall experience of using the app with a screen reader. I hope this post will at least plant a little seed in your head that makes you think about what it feels like to be disabled and what would the experience of a disabled person be like using the app you're working on. Conclusion: The Humbling Realities of Accessibility The past few weeks have been an eye-opening journey for me into the world of accessibility, exposing its importance not just in theory but in palpable, daily experiences. My short-term impairment allowed me to peek into a life where simple tasks aren't so simple, and convenient shortcuts are a maze of complications. It has been a humbling experience, but also an illuminating one. As developers and designers, we often get caught in the rush to innovate and to ship, leaving behind essential elements that make technology inclusive and humane. While my temporary disability was an inconvenience, it's permanent for many others. A broken hand made me realize how broken our approach towards accessibility often is. The key takeaway here isn't just a list of accessibility tips; it's an earnest appeal to empathize with your end-users. "Designing for all" is not a checkbox to tick off before a product launch; it's an ongoing commitment to the understanding that everyone interacts with technology differently. When being empathetic and sincerely thinking about accessibility, you never know whose life you could be making easier. After all, disability isn't a special condition; it's a part of the human condition. And if you still think "Our users don't really use keyboard shortcuts" or "We can add accessibility later," remember that you're not just failing a compliance checklist, you're failing real people....

Dec 6, 2023

5 mins

AccessibilityA11yWeb DevelopmentHTML

How to add Dark Mode in your Web Application

How to Create Dark/Light Mode in your JavaScript project? Providing our visitors with the ability to toggle between white and dark themes has become one of the most important features of all time. In this article, we will cover the requirements to develop a persistent theme for your website successfully. The code provided as part of this article will be technology agnostic and can be used with all major front-end frameworks such as Vue, React, or Svelte. TL;DR If you are in a rush and just want access to the code, you can grab it from this Stackblitz: Light / Dark theme functionality in Vanilla JS. What is White/Dark Mode Before we jump into the code, we should first explain what the meaning behind the feature name "White/Dark Mode is". This feature was first introduced in our Operating system by allowing users to change their default theme into Dark Mode, After this, Dark Mode has slowly made its way into our most used applications and websites as users expected to have a consistent look from their native application to Web App equivalent. Providing "White/Dark mode" in your site means giving the user the ability to toggle their theme to either align to the Operating system theme settings or override it from the Web App UI. The above example shows the feature on thisdot.co triggered by the little toggle button available within the main navbar. Implementing Dark Mode with Javascript This feature has two main implementation levels. The first is the ability to assign the theme directly from the Operating System preferences, while the second combines the feature of the first plus the ability to override that feature from the UI. Some websites just offer the first option and allow the site to emulate the OS preferences, even if this is mostly fine for most users, in this post, we will develop the second option as it is the most complicated approach and, therefore the most complete. The development of this feature is going to be divided into the following steps: - Ensure CSS variables drive our application - Create a second set of variables for a dark theme - Create logic to read user preferences - Create logic to override the theme preference - Make our theme selection persistent Let's dive into the code with our first step and initialize our application. Move all styles into CSS variables We are going to start our application by initializing a plain VanillaJs Stackblitz. This creates a simple project with an index.js file that includes our HTML and a style.css file that includes our global styles. To be able to have a good starting point for our post, we are going to add some more elements on the main page of the app and then define some CSS variables to make our example more appealing. First, we are going to clean our index.js and just leave the style import: ` Then, we are going to change our index.html with the following content: ` And finally, define some CSS variables and styles in style.css: ` If you are new to CSS variables, you can read more about them in the MDN docs: Using CSS custom properties. There is one point to clarify regarding CSS variables and their naming convention. Because the color held within our variables will change (for example from red to blue), the variable name should be based on the color "role" (eg primary, shadow, border") and not on the actual color "blue, green". In our example, we can see this naming convention in action as the variables are called "primary", "secondary" and "background". The above should output a very simple but colorful design: Create a second set of variables for the dark theme Now that our basic application is set, it is time to create a second set of variables to be able to define the difference between the light and dark theme. As you may notice, the CSS variables are not a must for this to work, but having all the variables set makes the maintenance of the site much easier than having to update color and styles scattered around. We are returning to our style.css file and updating a few of the CSS properties. These variables will just be updated if the body has a specific class dark associated with it: ` As the above code shows, because we are just overriding the variables, we do not actually need to redeclare them all and we can just declare the variables that we wish to update. If we would go back and add a class of "dark" to our body in index.html we would see the following output: As you can see, both white themes are fully set up and working. All that is left is creating the logic that can handle the theme toggle, but before we do so, there is one more change to add to our CSS. In fact, some components, such as form controls and scrollbar, use a property called "color-scheme" to change their theme, to give this a try, we will add an in our HTML: ` Then, let's see how this would look in our design: The input is showing a white theme even if the dark theme is selected, and this is happening because we are not changing the "color-scheme" that is what is used for the form input. Let's fix this by adding another CSS variable and a CSS declaration within our body: ` With the above code, the "color-scheme" variable will be changed to align with our overall theme, as shown below: Note that settings can be overridden on a component-by-component level. In fact, if you would like to always display the white theme for a button or field, you can just redeclare the "color-scheme" and apply it to the CSS selection of your choice. It is now time to move forward and include some JS to make the toggling automatic. Create logic to read user preferences It is now time to write some JavaScript and make our application dynamic. In this first logical step, we are going to read our Operating System color preference and use it to toggle the class assigned to our body. To do so, we are going to use the "matchMedia" method to read the "prefer-color-scheme" just like shown in the code below: ` The next step is to assign or remove the class from our body depending on the preferred scheme: ` Let's see if this works. If you are on Mac you can change the preferences by following the following steps: 1) System settings 2) Appearance 3) Change the appearance If you change the preferences and refresh your application, you should be able to see the application changing on the fly. Create logic to override the theme preference Having to change the full OS just for a single Website theme preference may be a little bit too much. So, in this step, we are going to enhance our logic to be able to override the preferences. First, we are going to add a simple button in the HTML called Toggle Theme: ` Now, it is time to update the logic. First, we need to allow a way to override the preferences. We can do this by adding an argument to our updateScheme function: ` The above code just adds a global variable called selectedTheme and then, as we previously mentioned, adds a parameter of overrideScheme to our method and finally makes sure we use this variable if available selectedTheme = overriddenScheme || preferredScheme. The next step requires us to be able to update our selectedTheme on a button click: ` With the above code added to our application, we could override the system preferences, but unfortunately, our work is not completed. The logic we wrote above is not persistent, and the theme selection will be lost if we refresh the page. Make our theme selection persistent In this last step, we are going to save our selectedTheme in localStorage using the documentation provided in the MDN documentation: Local Storage. First, let's save the selectedTheme into local storage by using localStorage.setItem: ` Then make sure we read this value on load using localStorage.getItem: ` After the above changes, you should be able to toggle the theme, refresh the page and be able to see the correct theme loaded up for you. NOTE: Due to the way StackBlitz loads the JS, there will be a small flash, but if you would place this code in the head that flash should be extremely minimal. What about the images You may have noticed that we have left the image unchanged between the different themes. This was, unfortunately not by choice, as there is no native way to swap images when using class-based theming. If you were just to implement the theme based on System Preference, you could declare different images using the media query (prefers-color-scheme: dark). This would allow you to declare images like this: ` The above code will show day.jpg if your theme settings are light or night.jpg if dark. If you would like to implement something similar with a class-based theme, you will have to create a custom image component in your framework of choice that loads the correct theme, but this is outside this tutorial's scope. Conclusion It is now time to conclude this post and leave you to go and apply what we learned in your Web applications. Implementing this feature is quite simple, and it helps to improve your user's experience. The code we have written above is available on StackBlitz: Light / Dark theme functionality in Vanilla JS. But let's see it in action in: So, in this article, we have introduced CSS variables and ensured our design colors were driven solely by them. We created an override for this variable using a class-based approach; we then learned how some elements, such as input fields, can change the theme using the "color-theme" property. We then moved into the JS, where we used the media query "prefers-color-scheme" to read the user Operating System theme preferences and, last but not least, created a live toggle that would create and save a personal preference in LocalStorage....

Dec 26, 2023

9 mins

JavaScriptCSSHTML

Transforming Platform Engineering Through Chargeback Programs with Shuchi Mittal

Shuchi Mittal, the Head of Cloud enablement at Honeywell, discusses how she as a leader in platform engineering has been able to transform internal platform engineering teams at other organizations by providing teams with value-added services, and how they effectively managed costs. She talks about how to treat these teams as customers, and delivering services that meet the customer needs, but also charging them for their usage. By providing policy-compliant infrastructure and unique services tailored to their requirements, platform engineering teams can showcase their commitment to supporting the success of other teams within an organization. This approach not only fosters trust but also positions platform engineering as a strategic partner rather than just a service provider. By going beyond the basic infrastructure provisioning, the platform engineering team can offer services that help development and product teams streamline their processes and improve efficiency. Shuchi shares her work at Fiserv where she implemented a chargeback system to track usage and costs effectively, incentivizing better development practices. This not only helped in managing costs but also encouraged teams to optimize their resource utilization, leading to improved overall efficiency and more easily scalable systems. Her platform engineering team recognized the importance of effectively managing financial aspects to secure upfront investment for product development. By implementing a billing system based on gigabyte hours, they aligned costs with usage, enabling teams to have a clear understanding of their resource consumption. This approach not only provided transparency but also incentivized teams to adopt cost-effective practices. By strategically managing financial aspects, the platform engineering team gained the trust of stakeholders and secured the necessary resources to drive innovation and deliver value to the organization. Shuchi’s journey of platform engineering serves as a valuable example of how a team can transition from being a basic service provider to becoming an innovation partner within an organization. By building trust, offering value-added services, and strategically managing financial aspects, the platform engineering team successfully elevated their role and became a strategic enabler of innovation. Download this episode here....

Apr 16, 2024

2 mins

Engineering LeadershipSoftware Engineering

JSR - The cross-platform package manager for ESM

JSR - The cross-platform package manager for ESM Move over NPM, there’s a new package manager in town. JSR is a new open-source package registry for JavaScript and TypeScript. This particular release has caught my attention, and I’m excited to explore if and where JSR fits into our overflowing ecosystem. Setting the stage The JSR website has a page called Why JSR? I want to explore the _why_ a little bit further. I think that the _why_ points to JSR potentially being the future of the JavaScript ecosystem. NPM and JavaScript modules If you’ve found yourself confused about publishing and consuming packages and modules in the modern ESM era, you’re not alone. When NodeJS was created, there was no standard for JS modules. Node introduced CommonJS modules, and NPM provided a way to publish and consume these modules in our applications. It’s been years now since ES Modules became a standard and we are still in a weird module purgatory with no clear end in sight. JSR represents a fresh start, free from the baggage of the Node and NPM ecosystems. JavaScript runtimes and interoperability New JavaScript runtimes are popping up every year. WinterCG (_Web-interoperable Runtimes Community Group)_ was started to improve interoperability for the various runtimes with some standard APIs. Node has made steps towards this goal, but it might never get all the way there and NPM is coupled pretty tightly to that ecosystem. JSR supports several runtimes (depending on the package). This is a huge opportunity for it to become the package manager for the ecosystem at large. See cross-runtime support section for more details. NPM Compatibility JSR doesn’t end up being a complete departure from NPM since it includes an NPM compatibility layer. The docs highlight some limitations and provide deeper technical details on how this piece works. The simple overview is that you can install and use packages from JSR to a Node/NPM based project. The packages will get added to your package.json and node_modules directory. About the same as any package installed from NPM. JSR Overview At a high level, JSR is very similar to NPM. You can search for packages on the website. You can publish packages to their registry, and you can download packages from it as well. We touched on the two major features that set it apart from NPM: It only supports ESModules, and it has cross-runtime support. In the rest of the article we’ll explore the essentials (package management) and also some other really great features that feel like are bringing the JS package management ecosystem up to speed with our modern workflows. Native TypeScript I have to say I’m not surprised by this feature, considering JSR was developed by the same people behind Deno (a runtime that supports TS natively). It’s a great feature. If you haven’t figured it out yet TypeScript is a big deal and doesn’t seem to be fading away anytime soon. So what exactly does TS support look like in a package manager, though? If your runtime supports TypeScript natively (like Deno) - it can consume the TS files in your package directly. For environments that don’t, it will automatically compile your code to JavaScript and package it with type declaration files (.d.ts). Pretty, stinking, cool. The docs include a page called “about slow types”. It is probably worth a read on its own ,but the TLDR is that JSR will analyze your TS code and penalize you in certain ways if you have some type code that it considers to be slow. On the page, it outlines exactly what these penalties are, as well as what it considers slow types to be. Slow types will also come into play when we get into package scoring later in the article. Packages The docs have a page dedicated to packages. It covers some important stuff like deleting packages, versioning, documentation, and publishing. We’ll touch on some of it with an emphasis on the things that are done differently or better than with NPM. jsr.json file jsr.json is a configuration file that specifies a name, version, and exports of a package. It doesn’t include a list of dependencies like you would have in a package.json file. This is a configuration file for a package to be published to JSR. JSR dependencies are defined in an import map file or a package.json file, depending on the runtime. Adding packages to a project Adding packages to your project will vary depending on your target runtime. Here’s an example of installing it for Deno and NPM using various package managers. For Deno, an import map entry is created. For NPM, it gets installed as an NPM package using the JSR NPM compatibility layer. ` If the runtime has native JSR support, you don’t need to explicitly install packages. You can important them using the jsr: scheme. ` As you can see semantic versioning is supported and works similarly to NPM. Publishing packages If you want to publish a package to JSR, there are many important rules you need to be aware of. I recommend reading “Publishing packages” before moving forward with this. The main things to note are: ESModules only, npm packages are supported, JSR packages are supported, and node APIs are supported. So there aren’t many constraints. You just need to understand how exactly to do these things. IE: how do I use NPM dependencies, how do the imports work, etc? Once you’ve got all that down, you will be ready to publish your first package to JSR 😃 Documentation JSR emphasizes quality package documentation. It’s one of the factors in their package scoring algorithm, which we will discuss shortly. The important parts of a package’s documentation include: * a README.md file * symbol documentation - functions, interfaces, classes, etc * module documentation - docs for each exported module in a package The symbol and module documentation are written using JSDoc. The JSR website generates some nice documentation based on these 3 pieces on your package page. This means you can understand a package's entire public API without ever leaving jsr.io. Browser support The cross-runtime support is amazing, but I was curious where the original JavaScript runtime fit (the browser). According to the documentation: “You can use JSR with any tool that supports ES modules, and either has native support for JSR or supports npm packages using node_modules.” Since modern web browsers support ES modules, I will count this as JSR support. From what I can tell, though, there is one caveat. To include a module on a web page, we need a URL to download it from. Can we publish our package to JSR and use it to load a module via a script tag? According to the JSR usage policy, no. The “Unacceptable use” section states: “It is not acceptable to use JSR as a CDN for serving assets directly to web applications in a browser, except for development purposes.” So, it seems that this is a no-go for now. We will probably need to wait a bit for CDN services like jsdelivr to pull packages from the JSR registry, similar to what they do with NPM currently. Other notable features We’ve covered the most important bits about package management, TS support, NPM compatibility, etc. But there are still a few unique features that add an extra bit of sparkle to JSR. Scoring We mentioned earlier that documentation plays a part in a scoring algorithm. JSR analyzes all of the packages published to its registry and assigns them a score based on certain criteria: documentation, best practices, discoverability, and compatibility. This score is shown with every package listed on the website. You can also add a shiny badge to your README if you’re particularly proud of something. It’s still early on, so it’s likely this will evolve as time goes on. It’s an interesting gimmick, at the very least! Summary I am excited to have a new cross-platform compatible package manager that only supports ESM. As useful as NPM has been all these years, it carries a lot of baggage from “the olden days”. JSR’s native TypeScript support and reliance on modern standards is a breath of fresh air. It feels like I can publish a simple package without much ceremony. I’m excited to release my first package to JSR soon :)...

Apr 12, 2024

6 mins

JSRJavaScript

Make it Accessible: Better Layout with HTML

Make it Accessible - 8 Part Series

Make it Accessible: Better layouts with HTML

The Problem

The Solution

The Implementation

Using divs right

Sections are the way to go

Articles are useful too

Conclusion

You might also like

I Broke My Hand So You Don't Have To (First-Hand Accessibility Insights)

How to add Dark Mode in your Web Application

Transforming Platform Engineering Through Chargeback Programs with Shuchi Mittal

JSR - The cross-platform package manager for ESM

You might also like

I Broke My Hand So You Don't Have To (First-Hand Accessibility Insights)

How to add Dark Mode in your Web Application

Transforming Platform Engineering Through Chargeback Programs with Shuchi Mittal

JSR - The cross-platform package manager for ESM