My Design System

Why I Created a Design System

I was using Material UI for a project, and the bundle size, combined with the css-in-js approach to styling, resulted in an application that was difficult to render on the server and that had a pretty poor initial load time. I wanted to create a design system that was similar to Material UI / Flutter but that emphasized semantic HTML and a small bundle size.

Also, when creating a Rich Text Editor with Lexical, I found that it was best to not use highly abstracted components, so I tried to create a library of simple components that can be easily rendered on the server and that doesn't use too much CSS and JavaScript.

In summary, the goal of the design system is to create a look that is comparable to other popular design libraries used today while minimizing load time, bundle size, and complexity.

Assumptions

NOTE: This design system uses CSS and JavaScript that are tied together - i.e., some classes are required for components' JavaScript to work correctly. The design system bundles and transpiles client-side JavaScript using webpack, which is why you might want to download the JavaScript and CSS files from the resources section and tweak them / re-transpile them for your own use. If you make changes to the CSS, I recommend you use PostCSS so your changes will appear the same across all browsers.

The design system assumes that:

you want to use HTMX to create a SPA (Single Page Application),
you want to use semantic html, but that you want to style components primarily with CSS classes and inline styling,
your Content Security Policy allows for inline styling,
you want to use Floating UI for tooltips, menus, dropdowns, and the like,
you want to have slightly different layouts for desktop and mobile,
you want to prioritize mobile devices (you want the application that you show the user to always be similar to the mobile device view),
you do not want to listen to resize events on mobile

Explore the Design System

If you are looking for information about specific components or utility classes, use the links in the list below to find more information about those aspects of the system. Each aspect of the design system should describe the styling, accessability, and JavaScript concerns that go along with it.

If you are looking to learn more about the design system and the decisions made, continue reading below or navigate to the 'General' page for the design system.

If you want the code, navigate to the resources section.

Note that I am still working on documenting the design system. I got tired of writing the documentation and wanted to move onto other things. I will come back and finish / improve the documentation eventually.

Components and Utility Classes

NOTE: Popovers includes tooltips, dropdowns, dialogs, and menus - basically everything that is shown on mouseover or focus or everything that is in the top-layer. Media includes images, video, and audio. Surfaces includes cards, quotes, and asides. Other Inputs includes toggle buttons. Tabs includes tabs, steppers, and mobile steppers. Fixed Content includes the navbar, footer, sidebars, drawers, and Floating Action Buttons.

Select Inputs

Select

About Select

Select inputs should have a <label> tag that does not have a for attribute.
Select inputs should look like this:

<div class="select">
<button 
role="combobox" 
aria-haspopup="listbox" 
aria-controls="${id of select menu}" 
aria-labelledby="${id of label element for select}" 
class="select"  
data-popover 
data-pelem="${query selector string for select menu}" 
data-click 
aria-expanded="false"
>
  <span class="body1">${initial value}</span>
  <svg focusable="false" aria-hidden="true" viewBox="0 0 24 24" tabindex="-1" title="ArrowDropDown"><path d="m7 10 5 5 5-5z"></path></svg>
</button>
<div 
tabindex="-1" 
id="${id of select menu}" 
role="listbox" 
class="select-menu o-xs" 
data-placement="bottom" 
aria-orientation="vertical"
>
  <input type="text" hidden="" value="option-1" name="${name of input}" id="${name of input}">
  <button tabindex="-1" class="select-option" role="option" aria-selected="true" data-val="option-1">
    Option 1
  </button>
  <button tabindex="-1" class="select-option" role="option" aria-selected="true" data-val="option-2">
    Option 2
  </button>
  <button tabindex="-1" class="select-option" disabled role="option" aria-selected="true" data-val="disabled-option">
    Disabled Option
  </button>
</div>
</div>

where each select option has a data-val attribute equal to the value associated with that option. When a select option is clicked, the innerText of the option replaces the innerText of the <span> element and the data-val of the select option is set to be the value of the hidden text input.

Select Example:

Small Select Example:

Multiple Select

Multiple Selects were determined to not be worth it since they add too much complexity to client side code.

Below is an example of a disabled select. Make sure to add .disabled to the <label> element.

Multiple Select Example:

Combobox Inputs

About Combobox Inputs

Combobox inputs are pretty much the same as select inputs except for the fact that combobox inputs are going to have a hx-indicator, an aria-live region, and a wrapper for the indicator + select menu that should have a data-input attribute that is equal to the id of the input. The combobox should look something like this:

<label 
for="${id of text input}">
${label}:
</label>
<div class="text-input block medium">
<input 
name="${id of text input}" 
id="${id of text input}" 
type="search"
autocomplete="off"
class="medium mt-1 icon-before"
placeholder="Enter your favorite coding language..."
maxlength="50"
pattern="/^{1.50}$/"
spellecheck="off"
autocapitalize="off"

aria-autocomplete="list"
aria-haspopup="listbox"
role="combobox"
aria-expanded="false"
aria-controls="${id of combobox popup}"
data-popover
data-click
data-pelem="#${id of combobox popup}"

hx-post=""
hx-target="#${id of combobox aria-live region}"
hx-indicator="#${id of combobox indicator}"
hx-swap="innerHTML"
hx-trigger="keyup changed delay:200ms, search"
data-htmx
/>
<svg class="icon-before" focusable="false" aria-hidden="true" viewBox="0 0 24 24" tabindex="-1" title="Code"><path d="M9.4 16.6 4.8 12l4.6-4.6L8 6l-6 6 6 6 1.4-1.4zm5.2 0 4.6-4.6-4.6-4.6L16 6l6 6-6 6-1.4-1.4z"></path></svg>
<div 
class="select-menu o-xs" 
data-placement="bottom" 
id="#${id of combobox popup}" 
style="mx-height ?"

tabindex="-1"
role="listbox"
aria-orientation="vertical"
data-input="${name of associated text input}"
>
    <div aria-label="Coding Language Select Progressbar" 
    class="flex-row justify-center t-secondary htmx-indicator" 
    id="coding-language-example-search-indicator" role="progressbar" aria-busy="false">
        <div class="lds-dual-ring"></div>
    </div>
    <div aria-live="polite" id="${id of combobox aria-live reigion}">

    </div>
</div>
</div>

Favorite Coding Language:

If you want the popup to stay open even after an option is selected or a mousedown / touchstart event happens, then you can add a data-force-close attribute to the element that triggers the popup, the element with the data-pelem attribute, and it will remove the listeners for focusout and blur, which normally close the popup, with a listener for a click on the <body> or <div class="dialog"> element. See the example below. Notice how the combobox select menu does not close on mousedown.

Search States:

HTML Select And Autocomplete Components

I want to try to implement HTML <select> components to save some space on the page.

Combobox Search

Sometimes you want to render an autocomplete component like above but you don't want to make a request to the server to get options. Instead, you want to render all the options on load and sort the options by most relevant when the input changes, and let the user choose from the options.

Need To Implement This

Search Icons

About Icon Search

Resources

Click on the individual buttons to download separate files, or click on the All Files button to download a ZIP file of all the code. The code is sent pre-transpiled for readability.
Click on the VSCode Snippet button to download a copy of the html.json file that will make implementing this design system simpler.

All Files

Shared CSS

Desktop CSS Mobile CSS

Shared JavaScript

Desktop JavaScript Mobile JavaScript

VSCode Snippet