Building web-tui-kit: a framework-independent browser UI with a stable contract

Building web-tui-kit: a framework-independent browser UI with a stable contract

I recently open-sourced web-tui-kit, a browser UI design system inspired by Debian debconf, dialog, and whiptail.

I've always liked the aesthetics of these interfaces. Their restrained colors, sharp boundaries, text-oriented layouts, and almost abstract appearance have a character of their own. They look like software from another era, yet I find that visual language especially interesting when brought into modern applications.

There's something appealing about taking an interface that looks as though it belongs in a terminal-based system configuration tool and making it work naturally in a contemporary browser application. I don't want to reproduce the limitations of old software. I want to preserve its distinctive aesthetic while benefiting from modern browser capabilities, semantic HTML, and familiar interactions.

That interest led me to build web-tui-kit: a reusable system that brings this visual language to browser-based tools without tying their UI to React, Vue, or another application framework.

The result is a small browser-native design system built primarily from CSS, semantic HTML, and a small amount of optional JavaScript.

Repository:

https://github.com/1990jk1990/web-tui-kit

Why another UI kit?

Most web UI libraries solve a much larger problem than I needed.

I wasn't looking for a component framework, application runtime, state-management solution, or build system. I wanted applications to be able to generate ordinary HTML and apply the same visual and behavioral contract regardless of whether the application itself was written with React, Vue, server-side templates, or no framework at all.

I also wanted the design to feel intentionally different from conventional modern dashboards. Rather than rounding every corner, adding gradients, or hiding the structure of an interface, I wanted to explore the directness of the classic Debian configuration aesthetic.

The visual direction comes from debconf, dialog, and whiptail: deliberately simple compositions built around dialogs, menus, radio lists, checklists, text inputs, gauges, actions, and keyboard-friendly navigation.

For me, combining that retro, almost backend-like appearance with modern applications is part of the appeal. The goal is not nostalgia alone, but a distinctive and reusable interface that still behaves like modern web software.

Framework-independent means more than "no dependencies"

One lesson from building this was that removing framework dependencies is the easy part.

The harder part is defining what downstream applications are actually allowed to depend on.

Starting with version 1.0, web-tui-kit therefore has an explicit public contract covering things such as:

• CSS tokens
• public CSS classes
• semantic markup relationships
• data attributes
• browser events
• interaction behavior

That boundary follows Semantic Versioning.

A patch release should not silently rename a class or change an event contract simply because the implementation still "looks right."

This is especially useful when the same design system is consumed by several applications — and also when coding assistants generate or modify UI. A stable reference is much more useful than telling an automated consumer to copy whatever happens to be on main that day.

The runtime stays small

A consuming application can vendor the released src/ files and include them directly:

<link rel="stylesheet" href="/ui/tokens.css">
<link rel="stylesheet" href="/ui/tui.css">
<script src="/ui/tui.js" defer></script>

The JavaScript is optional for applications that don't need the progressive keyboard enhancements.

There is no required application build step.

React, Vue, and server-rendered applications use the same semantic markup and classes rather than separate framework-specific component implementations.

Testing the contract

Once a UI becomes a dependency of other applications, screenshots alone are not enough.

The repository currently checks several different layers.

There are reviewed Chromium visual-regression baselines for the canonical UI compositions.

Interaction behavior is exercised in Chromium and Firefox.

Accessibility-semantic regression checks inspect browser-computed roles, accessible names, label relationships, native states, and progress semantics.

There is also representative narrow-touch browser testing and a recorded physical Chrome-for-Android baseline for the stable 1.0 line.

The React, Vue, and server-rendered integration recipes are executable regression fixtures rather than documentation snippets that are never tested.

I'm careful not to describe those automated checks as WCAG certification or comprehensive assistive-technology testing. They are evidence for specific browser semantics, not a substitute for real accessibility evaluation.

Releases are treated as artifacts

The current stable release is v1.0.1 and the project is MIT licensed.

Tagged releases produce a focused ZIP plus a SHA-256 checksum. Release creation runs the project tests, documentation validation, browser regressions, framework-recipe verification, and artifact checks before publishing.

For reproducible consumption, downstream applications can therefore pin an immutable release:

git clone --branch v1.0.1 --depth 1 \
  https://github.com/1990jk1990/web-tui-kit.git

For simply trying it locally:

git clone https://github.com/1990jk1990/web-tui-kit.git
cd web-tui-kit
python3 -m http.server 8000

Then open /demo/ in a browser.

What I'm interested in learning next

The project has reached a point where external technical feedback would be more useful than adding features in isolation.

I'm particularly interested in feedback on:

• whether the declared public-contract boundary is too broad or too narrow
• whether direct tagged vendoring is practical for this kind of library
• browser or touch interaction cases that the current tests miss
• semantic/accessibility issues in the canonical components
• integration problems in real React, Vue, or server-rendered applications

Issues and pull requests are welcome:

https://github.com/1990jk1990/web-tui-kit

If you've maintained a small framework-independent UI library before, I'd also be interested in how you decided which implementation details eventually became stable public API.