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.

Popovers

About Popovers

Popovers are basically all absolutely positioned elements except for custom select menus.
This design library uses Floating UI to create popovers, except for dialogs and snackbars. Dialogs are always centered on the screen using the native HTML <dialog> component, and snackbars are positioned so they will always be shown at the top of the screen.

For popover elements, the elements that data-pelem targets, you can include .o-sm .o-lg .o-xs classes which change the size of the offset to be 6px, 12px, and 4px respectively. The default offset is 8px.

If you want the popup to stay open even after the element that is initiated the popup is blurred, 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.

Dialogs

About Dialogs

Dialogs can be launched programmatically, via a button click, or by some combination of keydown events.
Each button that opens a dialog should have the following attributes: <button aria-haspopup="dialog" type="button" data-dialog="id of dialog">.
When a dialog is opened a .dialog-open class is added to the <html> <body> tags to prevent scrolling of the main page.
There are various attributes that can be included on the dialog to enforce some kind of behavior. These attributes can be seen below:

data-close-backdrop: Including this attribute on the dialog will mean that the dialog closes when the escape button is clicked.
data-esc: On Desktop, this button will close the open dialog when the ESC key is pressed.

The .close-dialog class can be added to buttons so that they close the closest dialog on click. Most dialogs (not #image-dialog) will have a single child element - a <div class="dialog"> - that has a small, medium, or large class.
This child element should usually have three children elements with the following format (unless you want to customize it):

<div class="dialog-header">
</div>
<div class="dialog-body">
</div>
<div class="dialog-footer" role="toolbar">
</div>

Dialog Examples:

Tooltips

Elements that have tooltips should have the data-popover boolean attribute as well as a data-pelem attribute equal to a query selector string that can be used to find the tooltip. If the tooltip is initiated by a mouse over event, the element with the tooltip should have the data-mouse boolean attribute, else if the tooltip is initiated by a focus event, the tooltip should have a data-click boolean attribute.
The tooltip itself should have a data-placement attribute equal to a valid placement value. The tooltip should have a role="tooltip".
All tooltips should have the .tooltip plus a class which controls the text size, e.g. .body2.

If you know the id of the tooltip, you can place an aria-describedby attribute on the element with a tooltip and set it equal to the id of the tooltip.

Tooltip Examples:

Menus

Menus are basically just tooltips with different styling (They share the same data-* attributes). Instead of the .tooltip class, you should use the .floating-menu class. It is probably best to not use the data-mouse attribute for menus, since menus are supposed to contain more information than a tooltip, and its better to have that information more securely open.
For images in menus, they should have the .no-click class.

Menu Examples:

The longest mountain range on Earth is called the mid-ocean ridge.

Snackbars

The element that triggers the snackbar should have a data-selem attribute that is equal to a query selector string that allows the client side JavaScript to find the snackbar element. When this element is clicked, the snackbar has its aria-hidden attribute set to false, which allows the user to see the snackbar at the top of the screen. The snackbar should have a role="alert".
The snackbar can include a data-snacktime attribute which should be equal to the number of milliseconds for which you want the snackbar to be visible. After this time, the snackbar will be removed from the screen.
If you want a button to close the snackbar, include the data-close-snackbar attribute on the button. When clicked, this button will get the closest <div class="snackbar"> element and set its aria-hidden attribute to true.
Should probably include aria-haspopup="true" on elements that have a snackbar popup unless the snackbar has a data-snacktime attribute.

Snackbar Examples:

Success Snackbar (Click Me):

Error Snackbar (Click Me):

Warning Snackbar (Click Me):

Info Snackbar (Click Me):

Secondary Background Snackbar (probably best for getting inputs) (Click Me):

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