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.

HTML

The design system tries to guide the user of the design system to use semantic HTML as much as possible. This is encouraged by styling components with their tag name + query selector rather than just with a query selector.

For accessability, you will have to look at each individual component to see what the accessability concerns are. In general, though, the design system encourages the user of the design system to use a page layout that includes a navbar, a main section, a footer, and two sidebars that shows content from a mobile or near-mobile perspective.

<html>
<head>
<!-- SEO, Meta Tags, Css, JS -->
</head>
<body>
<header role="banner">
<!-- Navbar with 3 sections -->
</header>
<nav>
<!-- Commomn Site Navigation -->
</nav>
<main>
<!-- Page Content -->
</main>
<aside>
<!-- Page Navigation, Notifications -->
</aside>
<footer>
<!-- Footer -->
</footer>
</body>  
</html>

CSS

The design system uses a combination of semantic class names and styles for specific components. The design system makes use of CSS variables so that the design system is customizable for different themes.
The background colors, text colors, and font-family are the three main things that you might want to change when using the design system. The color scheme revolves around 7 main colors: primary, secondary, error, warning, info, success, and the secondary background. You can find out more about the semantic class names and the styling for specific components by visiting the pages for Utility Classes and the page for each component.

The design system assumes that your CSP (Content Security Policy) allows for inline styling for two main reasons:

Inline styling allows you to give components small changes when needed, which can make development easier, and
Inline styling is required for popovers that need to have an absolute position relative to the component that triggered the popover.

You can add custom css needed by just creating a custom CSS file.

NOTE: The main differences between the desktop, mobile, and tablet versions of the CSS are the breakpoints, which aren't included on tablet and mobile css, the way dialogs are styled, and the presence of drawer-like components, which are only included in mobile and tablet versions of the CSS.

JavaScript

The JavaScript that relates to each individual component can be seen on that component's page, but in general, on initial page load, the JavaScript adds listeners to elements based on their data-* attributes and based on their class names.
The JavaScript also adds listeners to all components that have the data-htmx so that the loop of adding listeners to content based on their data-* attributes is re-run after new content is loaded. This function can be seen below.

/**
* Function to call whenever new content is loaded
*/
function onNewContentLoaded() {

/* Dialogs */
shared.setDialogOpenButtons();
shared.setDialogCloseOnBackdropClick();
shared.setDialogCloseButtons();
/* Alerts */
shared.setCloseAlertsButtons();
/* Accordions (Details / Summaries) */
shared.setSummariesOnClickEvents();
/* Inputs (All - includes textareas and chips) */
shared.setInputListeners();
shared.setPasswordToggleButtons();
shared.copyInputButtons();
shared.regenerateInputValueButtons();
shared.setIncreaseButtonsListeners();
shared.setDecreaseButtonsListeners();
shared.setChipListeners();
shared.setToggleButtonGroups();
shared.setSelectButtonListeners();
shared.setComboboxListeners();

/* Menus, tooltips, dropdowns, snackbars */
shared.setPopoverListeners();
shared.setSnackbarListeners();
shared.setSnackbarCloseListers();

/* Buttons */
shared.setScrollToButtons();
shared.setNavigateBackButtons();
shared.setCopyCodeButtons();
shared.setCopyElementButtons();
shared.setHideShowButtons();
/* Tabs */
shared.setMobileStepperListeners();
shared.setTabListeners();

/* Time */
shared.setLocalTimes();

/* Images, Audio, Video */
shared.setImagesOnClick();
shared.setAudioListeners();
shared.setVideoListeners();

/* Drawers - Only On Mobile */
setDrawerButtons();


/* HTMX */
setHxElementListeners();
}

Things to Note

Here are some notes about the design system that I didn't really know where else to put:

A .dialog-open class is added to the <html> and <body> elements when a dialog is opened to prevent body scrolling. It is removed on dialog close.
To add a light mode / dark mode button to the application, add a button with the id light-mode-dark-mode to the page. When clicked, a function will run that changes the html tag's data-mode attribute from light to dark or vice versa.
To include an image dialog, a dialog, where images can be focused and the background blurred, include an element like the one below on the page.
Make sure to include the aria-live="polite" for regions - like search regions, that receive updated content.

Coming Soon

I plan to add a Lexical Rich Text Editor, graphs with d3.js, and maps with Google Maps to the design system soon.
The JavaScript for these functionalities will be self-contained since they will be a little larger than the default JavaScript, or they will at least greatly increase the bundle size (percentage-wise).

Need to optimize vector database performance with pgvector
Image Uploads, Video Uploads, and Audio uploads need to be included in the design system.

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